fix: report probe failure as a response field in its doc and keep skewed unanswered outcomes

The contract doc still said the daemon "warns instead" although the step now
travels on the response beside the warning. And an unanswered outcome with a
reason this client does not know (version skew) was dropped entirely; it now
stays unanswered with the reason omitted, encoded as an explicit client arm of
the confirmation union.

Author: thymikee

packages/contracts/src/application-lifecycle-runtime.ts

@@ -182,8 +182,8 @@ export type LaunchConfirmationUnansweredReason = 'alert-unrecognized' | 'url-own
 /**
  * A launch-confirmation probe step that failed or whose result could not be verified, so whether a
  * prompt is up is unknown. Not an outcome of the confirmation itself: the open reports no
- * confirmation for it and the daemon warns instead, keeping probe failure separate from what a
- * completed probe saw.
+ * confirmation for it and carries this step on the response beside a warning, keeping probe
+ * failure separate from what a completed probe saw.
  */
 export type LaunchConfirmationProbeFailure = 'alert-read' | 'alert-accept' | 'runner';
 
@@ -196,6 +196,19 @@ export type LaunchConfirmationOutcome =
       launchConfirmationProbeFailure?: undefined;
     }>;
 
+/**
+ * What a client reports about a launch confirmation. The platform always pairs an `unanswered`
+ * outcome with its reason; a version-skewed daemon may not, so this adds the arm where only the
+ * outcome survives and the unknown reason is omitted.
+ */
+export type LaunchConfirmationClientOutcome =
+  | LaunchConfirmationOutcome
+  | Readonly<{
+      launchConfirmation: 'unanswered';
+      launchConfirmationReason?: undefined;
+      launchConfirmationProbeFailure?: undefined;
+    }>;
+
 /** No confirmation reported: either none was seen or the probe could not read one. */
 export type LaunchConfirmationAbsent = Readonly<{
   launchConfirmation?: undefined;

packages/contracts/src/client-app.ts

@@ -3,7 +3,7 @@
 import type { AppsFilter } from './app-inventory.ts';
 import type {
   LaunchConfirmationAbsent,
-  LaunchConfirmationOutcome,
+  LaunchConfirmationClientOutcome,
 } from './application-lifecycle-runtime.ts';
 import type { JsonObject } from './json.ts';
 import type { SessionSurface } from './session-surface.ts';
@@ -101,8 +101,9 @@ export type AppOpenOptions = AgentDeviceRequestOverrides &
 
 export type AppOpenResult = AppOpenResultBase &
   // The same discriminated report the platform outcome carries: a seen confirmation pairs its
-  // reason, and only the absent arm can name a probe step that could not read one.
-  (LaunchConfirmationOutcome | LaunchConfirmationAbsent);
+  // reason, and only the absent arm can name a probe step that could not read one. The extra arm
+  // covers a daemon older than the reason field, which answers `unanswered` without one.
+  (LaunchConfirmationClientOutcome | LaunchConfirmationAbsent);
 
 type AppOpenResultBase = {
   session: string;

src/__tests__/agent-device-client-apps.test.ts

@@ -184,6 +184,29 @@ test('apps.open drops an unrecognized launch confirmation outcome instead of gue
   assert.equal('launchConfirmationReason' in result, false);
 });
 
+test('apps.open keeps an unanswered outcome whose reason predates this client', async () => {
+  const setup = createTransport(async (req) => {
+    if (req.command === 'open') {
+      return {
+        ok: true,
+        data: {
+          session: 'qa',
+          appBundleId: 'com.example.app',
+          launchConfirmation: 'unanswered',
+          launchConfirmationReason: 'a-reason-from-a-newer-daemon',
+        },
+      };
+    }
+    throw new Error(`Unexpected command: ${req.command}`);
+  });
+  const client = createAgentDeviceClient(setup.config, { transport: setup.transport });
+
+  const result = await client.apps.open({ app: 'com.example.app', platform: 'ios' });
+
+  assert.equal(result.launchConfirmation, 'unanswered');
+  assert.equal('launchConfirmationReason' in result, false);
+});
+
 test('apps.open reports a typed probe-failure step and drops an unrecognized one', async () => {
   const responses = [
     { step: 'alert-accept', reported: true },

src/client/client-normalizers.ts

@@ -2,7 +2,7 @@ import type { DaemonWireRequest, InternalRequestOptions } from '@agent-device/co
 import type {
   LaunchConfirmation,
   LaunchConfirmationAbsent,
-  LaunchConfirmationOutcome,
+  LaunchConfirmationClientOutcome,
   LaunchConfirmationProbeFailure,
   LaunchConfirmationUnansweredReason,
 } from '@agent-device/contracts/application-lifecycle-runtime';
@@ -387,19 +387,22 @@ export function normalizeOpenForegroundComposition(data: Record<string, unknown>
 }
 
 /**
- * The launch confirmation an open response reports, keyed on the typed outcome. The daemon pairs
- * an `unanswered` outcome with its reason, so an outcome or reason it does not recognize is dropped
- * rather than guessed, as is a probe step outside the typed set; warnings travel separately and
- * still reach the caller. With no outcome, the only report left is the typed probe-failure step.
+ * The launch confirmation an open response reports, keyed on the typed outcome. An outcome or
+ * reason outside the typed set is dropped rather than guessed, as is a probe step outside its
+ * typed set; warnings travel separately and still reach the caller. An `unanswered` whose reason
+ * the client does not recognize (version skew) stays `unanswered` without a reason: the prompt is
+ * on the device either way. With no outcome, the only report left is the typed probe-failure step.
  */
 export function normalizeLaunchConfirmation(
   data: Record<string, unknown>,
-): LaunchConfirmationOutcome | LaunchConfirmationAbsent {
+): LaunchConfirmationClientOutcome | LaunchConfirmationAbsent {
   const outcome = readLaunchConfirmationOutcome(data.launchConfirmation);
   if (outcome === 'accepted') return { launchConfirmation: 'accepted' };
   if (outcome === 'unanswered') {
     const reason = readLaunchConfirmationReason(data.launchConfirmationReason);
-    return reason ? { launchConfirmation: 'unanswered', launchConfirmationReason: reason } : {};
+    return reason
+      ? { launchConfirmation: 'unanswered', launchConfirmationReason: reason }
+      : { launchConfirmation: 'unanswered' };
   }
   const probeFailure = readLaunchConfirmationProbeFailure(data.launchConfirmationProbeFailure);
   return probeFailure ? { launchConfirmationProbeFailure: probeFailure } : {};