fix(android): never fabricate clipboard availability from a failed probe

Review blocker on #2021. The probe I added had a `catch { return true }`, then
cached that result by device id for the runtime owner's lifetime. A transient
adb offline or timeout therefore made `capabilities` advertise the clipboard on
a build with no clipboard shell — recreating the exact lie the fix was for, and
pinning it for the rest of the session. A test locked the behavior in.

Support is now a typed verdict with three states, because "we could not ask" is
not "it works": `supported | unsupported | probe-failed`. Only a definitive
answer is cached; `probe-failed` refuses conservatively with a hint saying
support could not be determined, and is deliberately not remembered, so the next
inspection asks again.

The same change repairs the ownership boundary. Turning raw adb stdout/stderr
into a verdict is Android tool knowledge, so it belongs to the Android owner, not
to shared vocabulary — `@agent-device/contracts/android-clipboard-support` now
carries the typed union alone. The parser returns to `src/platforms/android/adb.ts`
and runs in exactly one place, behind a new `AndroidToolHost.probeClipboardShellSupport`
that hands owners the verdict. That also settles which Android home owns it:
R13 lets only `src/platform-runtime.ts` import `@agent-device/platform-android`,
so a parser shared between the package and the root leaf cannot live in the
package either.

Tests now cover the failure path the previous ones locked the wrong way: a failed
probe refuses instead of admitting, its refusal says it could not determine
support rather than claiming the build lacks it, and it is not cached — a second
inspection re-probes and admits once the device answers.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019RpfS12XApXqasuAWZJaEX

Author: claude

packages/contracts/src/android-clipboard-support.ts

@@ -1,19 +1,13 @@
 /**
- * Whether an adb `cmd clipboard` invocation was refused because this Android build ships no shell
- * implementation for the clipboard service, rather than because the call itself failed.
+ * What an Android build's clipboard shell service answered when the owner asked.
  *
- * Shared so admission and execution decide identically: `packages/platform-android` probes with it
- * when generating facts, and the root clipboard leaf re-checks with it as defense in depth. Two
- * copies of this predicate could drift into a device that `capabilities` advertises and execution
- * refuses, which is exactly the split ADR 0019 §2 forbids.
+ * Three states, not two, because "we could not ask" is not "it works". `cmd clipboard` has no
+ * shell implementation on every build, and admission has to distinguish a build that said so from
+ * a probe that never got an answer — equating unknown with supported is how `capabilities` comes
+ * to advertise a clipboard that execution then refuses.
  *
- * It reads adb's own output because adb reports this condition in no other way: there is no exit
- * code or structured field that distinguishes "service has no shell command" from any other
- * non-zero result.
+ * Contracts carry the typed verdict only. Turning raw adb output into it is Android tool
+ * knowledge and stays with the Android owner (ADR 0019: platform output parsing belongs to the
+ * owning family, never to shared vocabulary).
  */
-export function isAndroidClipboardShellUnsupported(stdout: string, stderr: string): boolean {
-  const haystack = `${stdout}\n${stderr}`.toLowerCase();
-  return (
-    haystack.includes('no shell command implementation') || haystack.includes('unknown command')
-  );
-}
+export type AndroidClipboardShellSupport = 'supported' | 'unsupported' | 'probe-failed';

packages/contracts/src/platform-runtime-host.ts

@@ -1,5 +1,6 @@
 import type { DeviceInfo, Platform } from '@agent-device/kernel/device';
 import type { JsonObject, JsonValue } from './json.ts';
+import type { AndroidClipboardShellSupport } from './android-clipboard-support.ts';
 
 export type HostCommandRequest = Readonly<{
   executable: string;
@@ -49,6 +50,22 @@ export type AppleToolHost = Readonly<{
 
 /** Device-scoped Android transport selected by root composition; packages own all adb arguments. */
 export type AndroidToolHost = Readonly<{
+  /**
+   * Asks this device whether its clipboard service answers shell commands, as typed evidence.
+   *
+   * A host method rather than a `runAdb` call the caller classifies itself: normalizing adb's
+   * output is Android tool knowledge, and it happens once here rather than in every owner that
+   * needs the verdict.
+   *
+   * Optional, and its absence is not permission to assume support: a host that cannot probe
+   * leaves the owner unable to establish the capability, so the clipboard is refused rather than
+   * admitted. Only fabricated availability is forbidden — a refusal on incomplete information is
+   * the safe answer.
+   */
+  probeClipboardShellSupport?(
+    device: DeviceInfo,
+    signal?: AbortSignal,
+  ): Promise<AndroidClipboardShellSupport>;
   runAdb(
     device: DeviceInfo,
     args: readonly string[],

packages/platform-android/src/deployment/native.test.ts

@@ -28,6 +28,7 @@ function hostFixture(options: { bundletool?: boolean; bundletoolJar?: string } =
     },
     androidDeployment: { bundletoolJar: options.bundletoolJar },
     androidTools: {
+      probeClipboardShellSupport: async () => 'supported' as const,
       runAdb: async (_device, args, commandOptions, signal) =>
         await run({ executable: 'adb', args, ...commandOptions }, signal),
       installPackage: async (_device, packagePath, options, signal) =>

packages/platform-android/src/runtime.test.ts

@@ -1,4 +1,5 @@
 import { expect, test, vi } from 'vitest';
+import type { AndroidClipboardShellSupport } from '@agent-device/contracts/android-clipboard-support';
 import type {
   DeviceBinding,
   PlatformRuntimeHost,
@@ -32,6 +33,7 @@ test.each([
     stdout: 'mCurrentFocus=Window{1 u0 com.example.app/.MainActivity}',
   }));
   const host = {
+    androidTools: { probeClipboardShellSupport: async () => 'supported' as const },
     commands: {
       which: async () => 'tool',
       run: async () => ({ stdout: '1', stderr: '', exitCode: 0 }),
@@ -156,6 +158,7 @@ test.each([
 test('rejects the non-discovered Android simulator cell for appstate', async () => {
   const runtimeDevice = { ...device, kind: 'simulator' as const };
   const host = {
+    androidTools: { probeClipboardShellSupport: async () => 'supported' as const },
     processTransports: { resolve: async () => ({ mode: 'local' as const }) },
     localInteractors: { resolve: async () => ({}) },
     appState: {
@@ -197,17 +200,13 @@ test('rejects the non-discovered Android simulator cell for appstate', async ()
 });
 
 function androidNavigationHostFixture(
-  runAdb?: (
-    device: DeviceInfo,
-    args: readonly string[],
-  ) => Promise<{
-    stdout: string;
-    stderr: string;
-    exitCode: number;
-  }>,
+  probeClipboardShellSupport: () => Promise<AndroidClipboardShellSupport> = async () => 'supported',
 ) {
   return {
-    androidTools: { runAdb: runAdb ?? (async () => ({ stdout: '', stderr: '', exitCode: 0 })) },
+    androidTools: {
+      probeClipboardShellSupport,
+      runAdb: async () => ({ stdout: '', stderr: '', exitCode: 0 }),
+    },
     processTransports: { resolve: async () => ({ mode: 'local' as const }) },
     appInventory: {
       apple: { listApps: async () => [] },
@@ -417,6 +416,7 @@ test.each([
   'classifies the Android %s lifecycle denominator against the legacy dispatch cell',
   async (_name, runtimeDevice, legacy) => {
     const host = {
+      androidTools: { probeClipboardShellSupport: async () => 'supported' as const },
       processTransports: { resolve: async () => ({ mode: 'local' as const }) },
       appInventory: {
         apple: { listApps: async () => [] },
@@ -568,6 +568,7 @@ test('binds only the Android gesture tiers the target admitted', async () => {
 
 function gestureHost(): PlatformRuntimeHost {
   return {
+    androidTools: { probeClipboardShellSupport: async () => 'supported' as const },
     processTransports: { resolve: async () => ({ mode: 'local' as const }) },
     appInventory: {
       apple: { listApps: async () => [] },
@@ -583,12 +584,9 @@ function gestureHost(): PlatformRuntimeHost {
 // clipboard halves on every real Android kind, `capabilities` advertised `clipboard`, and
 // `clipboard read` then failed with `UNSUPPORTED_OPERATION` from the leaf. Admission now probes
 // the same condition the leaf checks, so a build with no clipboard shell command refuses up front.
-test.each([
-  ['no shell command implementation', 'cmd: No shell command implementation.'],
-  ['unknown command', 'Unknown command: clipboard'],
-])('refuses both clipboard halves when adb reports %s', async (_name, stdout) => {
+test('refuses both clipboard halves when the build reports no clipboard shell', async () => {
   const binding = await createAndroidPlatformRuntime(
-    androidNavigationHostFixture(async () => ({ stdout, stderr: '', exitCode: 0 })),
+    androidNavigationHostFixture(async () => 'unsupported'),
   ).bind({
     device: { ...device, id: 'android-no-clipboard-shell', kind: 'device' },
     intent: { kind: 'ordinary' },
@@ -611,29 +609,29 @@ test.each([
   expect(binding.facts.operations.appSwitcher).toEqual({ available: true });
 });
 
-test('probes the clipboard shell once per device, not once per inspection', async () => {
-  const runAdb = vi.fn(async (_device: DeviceInfo, _args: readonly string[]) => ({
-    stdout: '',
-    stderr: '',
-    exitCode: 0,
-  }));
-  const runtime = createAndroidPlatformRuntime(androidNavigationHostFixture(runAdb));
-  const target = { ...device, id: 'android-probe-cache', kind: 'device' as const };
+test.each([['supported'], ['unsupported']] as const)(
+  'caches a definitive %s verdict instead of re-probing per inspection',
+  async (verdict) => {
+    const probe = vi.fn(async () => verdict);
+    const runtime = createAndroidPlatformRuntime(androidNavigationHostFixture(probe));
+    const target = { ...device, id: `android-probe-cache-${verdict}`, kind: 'device' as const };
 
-  await runtime.inspectFacts(target);
-  await runtime.inspectFacts(target);
+    await runtime.inspectFacts(target);
+    await runtime.inspectFacts(target);
 
-  const clipboardProbes = runAdb.mock.calls.filter((call) => call[1].includes('clipboard'));
-  expect(clipboardProbes).toHaveLength(1);
-});
+    expect(probe).toHaveBeenCalledTimes(1);
+  },
+);
 
-test('an adb failure leaves the clipboard admitted rather than inventing an unsupported build', async () => {
+// The failure path is the one that recreates the defect if it guesses. A probe that never got an
+// answer must not report the clipboard available — execution would then refuse the very capability
+// `capabilities` advertised — and must not be remembered, or one transport blip decides the
+// question for the owner's whole life.
+test('a failed probe refuses rather than fabricating availability', async () => {
   const binding = await createAndroidPlatformRuntime(
-    androidNavigationHostFixture(async () => {
-      throw new Error('adb: device offline');
-    }),
+    androidNavigationHostFixture(async () => 'probe-failed'),
   ).bind({
-    device: { ...device, id: 'android-adb-offline', kind: 'device' },
+    device: { ...device, id: 'android-probe-failed', kind: 'device' },
     intent: { kind: 'ordinary' },
     scope: {
       signal: new AbortController().signal,
@@ -642,8 +640,42 @@ test('an adb failure leaves the clipboard admitted rather than inventing an unsu
     },
   });
 
-  // The probe is definitive in one direction only: adb naming the condition means unsupported, a
-  // probe that cannot run means unknown. Reporting unknown as unsupported would hide a working
-  // clipboard behind a transport hiccup.
-  expect(binding.facts.operations.readClipboard).toEqual({ available: true });
+  for (const key of ['readClipboard', 'writeClipboard'] as const) {
+    expect(binding.facts.operations[key]).toMatchObject({ available: false });
+    expect(binding.operations[key]).toBeUndefined();
+  }
+  // The refusal says it could not determine support, not that the build lacks it.
+  const fact = binding.facts.operations.readClipboard;
+  expect(fact.available === false && String(fact.hint)).toMatch(/could not determine/i);
+});
+
+test('a failed probe is not cached, so the next inspection asks again', async () => {
+  const probe = vi
+    .fn<() => Promise<AndroidClipboardShellSupport>>()
+    .mockResolvedValueOnce('probe-failed')
+    .mockResolvedValue('supported');
+  const runtime = createAndroidPlatformRuntime(androidNavigationHostFixture(probe));
+  const target = { ...device, id: 'android-probe-retry', kind: 'device' as const };
+
+  const first = await runtime.inspectFacts(target);
+  const second = await runtime.inspectFacts(target);
+
+  expect(first.operations.readClipboard.available).toBe(false);
+  expect(second.operations.readClipboard.available).toBe(true);
+  expect(probe).toHaveBeenCalledTimes(2);
+});
+
+test('a host with no clipboard probe refuses rather than assuming support', async () => {
+  const host = androidNavigationHostFixture();
+  const withoutProbe = { ...host, androidTools: {} } as unknown as PlatformRuntimeHost;
+
+  const facts = await createAndroidPlatformRuntime(withoutProbe).inspectFacts({
+    ...device,
+    id: 'android-no-probe',
+    kind: 'device',
+  });
+
+  // Absence of a probe is absence of evidence, not evidence of support.
+  expect(facts.operations.readClipboard.available).toBe(false);
+  expect(facts.operations.writeClipboard.available).toBe(false);
 });

packages/platform-android/src/runtime.ts

@@ -50,7 +50,7 @@ import { bindAndroidScreenRecordingRuntime } from './recording/runtime.ts';
 import { ensureAndroidReady } from './readiness/runtime.ts';
 import { readAndroidAppState } from './app-state.ts';
 import { bindAndroidApplicationLifecycle } from './lifecycle.ts';
-import { isAndroidClipboardShellUnsupported } from '@agent-device/contracts/android-clipboard-support';
+import type { AndroidClipboardShellSupport } from '@agent-device/contracts/android-clipboard-support';
 import {
   androidAppDeploymentFacts,
   createAndroidAppDeploymentOperations,
@@ -210,6 +210,33 @@ const clipboardShellUnavailable = Object.freeze({
   hint: 'This Android build ships no shell implementation for the clipboard service, so adb cannot read or write the clipboard on it.',
 } as const);
 
+/**
+ * The probe could not reach the device, so this owner does not know whether the build supports a
+ * shell clipboard. Refusing is the conservative answer and the only honest one: reporting
+ * available would hand the caller a capability execution may immediately reject, which is the
+ * exact failure fact-based admission exists to prevent. Deliberately not cached — the next
+ * inspection asks again.
+ */
+const clipboardShellUnknown = Object.freeze({
+  available: false,
+  reason: 'owner-capability-missing',
+  hint: 'Could not determine whether this Android build supports a shell clipboard: the adb probe did not complete. Retry once the device is reachable.',
+} as const);
+
+/**
+ * `probe-failed` covers both ways this owner can end up without an answer: the probe ran and could
+ * not reach the device, or the host exposes no probe at all. Neither is evidence of support, and
+ * both refuse rather than guess.
+ */
+async function probeClipboardShellSupport(
+  host: PlatformRuntimeHost,
+  device: DeviceInfo,
+): Promise<AndroidClipboardShellSupport> {
+  const probe = host.androidTools?.probeClipboardShellSupport;
+  if (!probe) return 'probe-failed';
+  return await probe.call(host.androidTools, device);
+}
+
 const tvRemoteUnavailable = Object.freeze({
   available: false,
   reason: 'unsupported-device-kind',
@@ -235,15 +262,17 @@ export function createAndroidPlatformRuntime(host: PlatformRuntimeHost): Platfor
    * Cached per device for this owner's lifetime: a build's shell command set cannot change while
    * the device is up, and admission would otherwise pay an adb round trip per request.
    */
-  const clipboardShell = new Map<string, Promise<boolean>>();
+  const clipboardShell = new Map<string, AndroidClipboardShellSupport>();
   const clipboardFact = async (device: DeviceInfo): Promise<RuntimeOperationFact> => {
     if (device.kind === 'simulator') return clipboardShellUnavailable;
-    let probe = clipboardShell.get(device.id);
-    if (!probe) {
-      probe = probeAndroidClipboardShell(host, device);
-      clipboardShell.set(device.id, probe);
-    }
-    return (await probe) ? available : clipboardShellUnavailable;
+    const support =
+      clipboardShell.get(device.id) ?? (await probeClipboardShellSupport(host, device));
+    // Only a definitive answer is worth keeping: a build's shell command set cannot change while
+    // the device is up, but a failed probe says nothing about the build and must not become a
+    // verdict this owner repeats for the rest of its life.
+    if (support !== 'probe-failed') clipboardShell.set(device.id, support);
+    if (support === 'supported') return available;
+    return support === 'unsupported' ? clipboardShellUnavailable : clipboardShellUnknown;
   };
   const inspectFacts = async (device: Parameters<typeof appLogs.inspectFacts>[0]) => {
     const logs = await appLogs.inspectFacts(device);
@@ -461,26 +490,3 @@ function androidInteractionOperations(
     }),
   };
 }
-
-/**
- * Asks the device, once, whether its clipboard service answers shell commands at all.
- *
- * Definitive only in one direction. adb naming the condition means unsupported; a probe that
- * cannot run (offline transport, adb failure) says nothing about shell support, so it reports
- * supported and leaves the real transport error to the operation that actually runs.
- */
-async function probeAndroidClipboardShell(
-  host: PlatformRuntimeHost,
-  device: DeviceInfo,
-): Promise<boolean> {
-  try {
-    const result = await host.androidTools.runAdb(
-      device,
-      ['shell', 'cmd', 'clipboard', 'get', 'text'],
-      { allowFailure: true },
-    );
-    return !isAndroidClipboardShellUnsupported(result.stdout, result.stderr);
-  } catch {
-    return true;
-  }
-}

src/platform-runtime-android-tool-host.ts

@@ -3,6 +3,26 @@ import type { AndroidToolHost } from '@agent-device/contracts/platform';
 /** Provider-aware Android transport. Command semantics and arguments stay package-owned. */
 export function createAndroidToolHost(): AndroidToolHost {
   return Object.freeze({
+    /**
+     * Definitive in both directions where adb answers, and honest when it does not: a transport
+     * failure reports `probe-failed` rather than a guess, so admission can refuse instead of
+     * fabricating availability the operation would then reject.
+     */
+    probeClipboardShellSupport: async (device, signal) => {
+      try {
+        const { runAndroidAdb, isClipboardShellUnsupported } =
+          await import('./platforms/android/adb.ts');
+        const result = await runAndroidAdb(device, ['shell', 'cmd', 'clipboard', 'get', 'text'], {
+          allowFailure: true,
+          signal,
+        });
+        return isClipboardShellUnsupported(result.stdout, result.stderr)
+          ? 'unsupported'
+          : 'supported';
+      } catch {
+        return 'probe-failed';
+      }
+    },
     runAdb: async (device, args, options, signal) => {
       const { runAndroidAdb } = await import('./platforms/android/adb.ts');
       const result = await runAndroidAdb(device, [...args], {

src/platforms/android/adb.ts

@@ -15,4 +15,17 @@ export async function runAndroidAdb(
   return await resolveAndroidAdbExecutor(device)(args, options);
 }
 
-export { isAndroidClipboardShellUnsupported as isClipboardShellUnsupported } from '@agent-device/contracts/android-clipboard-support';
+/**
+ * Whether an adb `cmd clipboard` invocation was refused because this build ships no shell
+ * implementation for the clipboard service, rather than because the call itself failed.
+ *
+ * adb reports this condition in its output and nowhere else — no exit code or structured field
+ * separates "service has no shell command" from any other non-zero result — so this is the one
+ * place that reads that prose, and it hands every caller a typed answer instead.
+ */
+export function isClipboardShellUnsupported(stdout: string, stderr: string): boolean {
+  const haystack = `${stdout}\n${stderr}`.toLowerCase();
+  return (
+    haystack.includes('no shell command implementation') || haystack.includes('unknown command')
+  );
+}