refactor: migrate is to the request-bound device runtime (#1883)

* refactor: migrate is to the request-bound device runtime

`is` declares the shared selector capture use, admits once from exact owner
facts, refuses before binding, and binds exactly once. Its capability bucket,
the static HarmonyOS/Web command sets that augmented it, and
`requireCommandSupported` admission for `is` are gone; `'is'` leaves the
`createSelectorRuntime` capability union.

Admission now runs BEFORE the direct-iOS selector fast path. ADR 0019 requires
resolve -> admit -> bind before anything in a `device-runtime` command's request
path reaches the device, so that query becomes a fast path *within* an admitted
request rather than a way around exact-owner facts. The rule is documented once,
on `createBoundSelectorRuntime`, replacing the two duplicated call-site comments
`get` and `is` were each carrying.

Declared behaviour change: `is` takes the active-app plan split, so the facts
decide per family. On iOS `appBundleId` is the XCUITest attach target — with no
tracked app the runner's own process comes to the foreground, displaces the app
under test, and the capture then answers confidently about the runner's own
blank screen. An iOS `is` on a session with no tracked app is now a typed
SESSION_NOT_FOUND refusal carrying the `open` hint. Refusing beats
displacing-and-lying. Android captures the real launcher in that state and is
unchanged, which is what the platform facts already encoded.

The two Apple watchOS cells move from capability-admitted-then-runner-failure to
a typed unavailable refusal, the same classification snapshot, diff, and get
already landed.

R37 is the new parametrized cutover row. `find` keeps `createSelectorRuntime`
and its `requireCommandSupported` call, so `captureData` stays optional and
`captureSnapshotWithInteractor` stays: this unit is not the last selector unit.

* fix(is): a failing iOS assertion fails instead of exiting zero

Reverses part of #557, on thymikee's explicit instruction.

`is` is an assertion: the docs state it "exits non-zero on failure". The
direct-iOS fast path broke that contract — it reported a failed predicate as a
completed command, so on device

    $ agent-device is text id=… "Wrong Expected Text"
    Passed: is text          (exit 0)

because `{ok: true, pass: false}` reaches `isCliOutput`, which renders
"Passed: is <predicate>" without reading `pass`. A failing assertion reported as
success lets a replay run on past a broken state. Now:

    Error (COMMAND_FAILED): is text failed for selector id=…:
      expected="Wrong Expected Text" actual="Apple Account, …"   (exit 1)

The renderer needed no patch: a negative can no longer produce a success
envelope, so it is correct by construction.

Direction chosen deliberately. Making the two paths agree could have gone either
way, and "an agent asked a question and got an answer" is a real argument for the
other one. This follows the DOCUMENTED contract rather than merely the incumbent
behaviour, and the alternative is a far larger change: a zero-exit `is` would
alter every platform and path, break scripts that rely on it failing the shell,
and needs its own PR, docs, and probably a major version. It is also already how
`is hidden` and `is exists` behave end to end.

PASSING assertion, and that arm still answers with zero captures (pinned). Only
the negative falls through — what #557's own summary asked for, "preserving
snapshot fallback for misses", refusing fallback only for hard failures like
ambiguity. The fall-through was #557's own design, never armed: the `| null`
return and the caller's `if (!payload) return null;` guard were unreachable.
This makes that dead guard live.

Measured on iPhone 17 (median of 9, warm daemon): predicate holds 0.14s / 0
snapshots, unchanged; predicate fails 0.25s / 1 snapshot. ~+0.11s on failing
assertions only.

Correctness gain beyond the envelope: the fast path evaluates a ONE-NODE tree, so
`visible` cannot see the ancestor geometry a list row inherits and its negative
can be wrong. Falling through re-asks the real tree and can turn a spurious
negative into a pass.

The #557 pin moved with its reasoning at the pin site.

* fix(layering): let a cutover row state a data-only admission retirement

Review blocker on #1883: R37 claimed `legacyRetirement.routeNames:
['WEB_QUERY_COMMANDS_WITH_IS', 'HARMONYOS_IS_SUPPORT']`. Neither identifier has
ever existed. They satisfied the non-empty shape check while proving nothing —
the vacuous registry claim AGENTS.md warns about, and a green gate that would
stay green if the deletion were reverted.

The cause was the model, not the row. Every `LegacyRetirementClaim` form names
something that must NOT exist, which a row can always satisfy by inventing a
name. `is` retired no module, route, or dispatch projection because it had none:
its legacy admission was a capability bucket plus membership in two static
platform command sets, so its real retirement is a DATA deletion the model could
not express. Rather than patch around that with sentinels or a per-command
policy file — both forbidden by the playbook — this generalizes the model.

`staticCommandSets` names the sets themselves and is proven from both sides:
each must still be DECLARED in production source, and must no longer list the
command. A fictional set fails the first half; a skipped deletion fails the
second. That is what an identifier-shaped claim cannot state.

R37 now claims HARMONYOS_SUPPORTED_COMMANDS and WEB_QUERY_COMMANDS, which is the
deletion it actually performed.

Planted red, both halves, against the real gate:

  [R37 is-runtime-cutover] 2 violation(s):
    (is cutover row):1 — claims retired static command set
      'WEB_QUERY_COMMANDS_WITH_IS', which no production source declares
    (is cutover row):1 — claims retired static command set
      'HARMONYOS_IS_SUPPORT', which no production source declares

  [R37 is-runtime-cutover] 2 violation(s):
    src/core/capabilities.ts:59 — static command set WEB_QUERY_COMMANDS still
      admits is

so the exact claim that shipped is now rejected by name, and so is restoring the
membership it claims to have removed. Mechanism cases live with the other
planted-row tests; layering goes 177 -> 181.

* test(is): pin the exit-code guarantee independently of what answers the predicate

Prep for the Blocker 1 retirement, which deletes `buildDirectIosIsResult` — the
function the #557 reversal fixed. The reversal's guarantee must not evaporate
with it, so it gets a case that does not know how the daemon decided.

`is` is documented to "exit non-zero on failure". The reversal proved that at
the JSON envelope; nothing pinned it at the CLI boundary, which is where the
defect was actually visible (`Passed: is text`, exit 0). This asserts the CLI
contract directly: a `predicate_failed` response exits 1 and never renders as
passed.

It survives the retirement untouched, because it asserts the outcome rather than
the path. Planted red with the exact pre-#1739 envelope the shortcut produced
(`{ok: true, data: {pass: false}}`): `exitSpy.calls` is `[]` — no exit call at
all — so the case fails, which is the regression it exists to catch.

Unpushed on purpose: the restack will carry it into the retirement cycle.

* refactor(is): retire the direct-iOS selector shortcut

thymikee's ruling (option b). `is` declares `device-runtime`, so its request path
must reach the device only through the operations R37 declares. It did not: a
simple iOS `id=`/`label=` target was answered by a direct XCUITest querySelector
without any capture, ordered after admission but not executing through the seam.

This is not retired because it was wrong. `wait` hypothesized that the degenerate
one-node evaluation mis-answers `is visible` for off-viewport nodes, traced it
through the code convincingly, then tested it on device and it did not reproduce
— XCUITest's own query is conservative about visibility, so the degenerate
evaluation never gets the chance. It is retired because it was an undeclared,
unmeasured bypass that made R37's singularExecution claim false: the same class
of untruth as the sentinel retirement names fixed in the previous commit.

Declaring querySelector as a real operation instead was rejected for a concrete
reason: offscreen-target-probe.ts consumes queryDirectIosSelector with a plain
session and cannot take a bound operation, so declaring it now would ship it
twice until Wave 5 moves the probe — the deferred-duplication shape that got
get's read deferral overruled. It returns as a declared, fact-admitted,
section 9-measured operation in the unit that also moves the probe.

Retired: dispatchDirectIosSelectorIs, its call site, buildDirectIosIsResult, and
resolveDirectIosSelectorQuery — each had exactly one caller, all on this path —
plus the ResolvedDirectIosSelectorQuery type they orphaned and two imports.
queryDirectIosSelector itself stays: the offscreen probe still consumes it and it
remains single-copy.

Latency cost, stated plainly and not softened: a held predicate on a simple iOS
selector goes from ~0.14s with no capture to ~0.25s with one, measured as the
median of 9 warm runs on iPhone 17. There is no fallback and no fast path.

R37's comment finally describes the code: "every predicate answers from the
resolved tree" was written while the shortcut existed. Its scope is now stated
too, so it is not read as absolute — the Android foreground-blocker diagnostic
still reaches adb on the failure path, where it cannot produce or change a
verdict; that edge is pre-existing, co-owned with wait, and recorded as Wave 6
denominator work with R22's appState as its declared replacement.

Seven tests lost their subject. Those whose only content was the shortcut's own
mechanics are deleted; the outcome-level ones are retargeted and keep asserting
what survives.

---------

Co-authored-by: agent <agent@local>

Author: thymikee

scripts/layering/check.ts

@@ -36,8 +36,8 @@
 //     composition file; premature implementation loading and forbidden cross-boundary edges fail (R13).
 //   - Over COMMAND-ATOMIC RUNTIME CUTOVERS: one parametrized gate reads the migrated-command
 //     table (appstate R22, shutdown R23, boot R20, apps R21, install/deploy R24-R27,
-//     lifecycle R28-R31, devices R17, logs R14, network R15, record R16, snapshot R32, diff R33)
-//     and proves each command keeps
+//     lifecycle R28-R31, devices R17, logs R14, network R15, record R16, snapshot R32, diff R33,
+//     viewport R34, get R36, is R37 — R35 reserved for find) and proves each command keeps
 //     exactly one platform-execution path — retired routes, admission, modules, and widened
 //     runtime access cannot coexist with its operation-fact-derived descriptor and handler.
 //   - Over CONTRACTS PRODUCTION SOURCE: contracts owns vocabulary only — host, process, and timer

scripts/layering/runtime-command-cutover-model.ts

@@ -28,6 +28,17 @@ export type LegacyRetirementClaim = Readonly<{
   daemonOnlyProviderMethods?: readonly string[];
   /** `PlatformPlugin` facet keys retired with the legacy adapter. */
   pluginFacetKeys?: readonly string[];
+  /**
+   * Static platform command sets this command's admission DATA was removed from — the whole
+   * retirement of a command whose legacy admission was a capability bucket plus set membership,
+   * with no adapter module, route, or dispatch projection to name.
+   *
+   * Every other form above names something that must NOT exist, which a row can satisfy by
+   * inventing a name that never existed. This one is two-sided and cannot: each named set must
+   * still EXIST in production source, and must no longer list the command. A fictional set fails
+   * the first half, a skipped deletion the second.
+   */
+  staticCommandSets?: readonly string[];
 }>;
 
 /**
@@ -157,6 +168,7 @@ const RETIREMENT_FORMS = [
   'daemonOnlyRouteNames',
   'daemonOnlyProviderMethods',
   'pluginFacetKeys',
+  'staticCommandSets',
 ] as const satisfies readonly (keyof LegacyRetirementClaim)[];
 
 /**

scripts/layering/runtime-command-cutover-policy.test.ts

@@ -285,3 +285,57 @@ test('every shipped row states its claims', () => {
     [],
   );
 });
+
+// A data-only admission retirement — a capability bucket plus static-set membership, with no
+// module, route, or dispatch projection to name as gone. Both halves are planted, because the
+// half that matters is the one an identifier-shaped claim cannot state: a set that never existed.
+const DATA_ONLY_ROW: MigratedCommandCutover = {
+  ...PLANTED_ROW,
+  legacyRetirement: { staticCommandSets: ['WEB_QUERY_COMMANDS'] },
+};
+
+test('a data-only retirement is a stated claim, so a row needs no invented identifier', () => {
+  assert.deepEqual(cutoverRowDefects(DATA_ONLY_ROW), []);
+});
+
+test('planted red: a row claiming a static command set that does not exist is rejected', () => {
+  assert.deepEqual(
+    summariesFor(
+      PLANTED_RULE,
+      [['src/core/capabilities.ts', `const WEB_QUERY_COMMANDS = ['find'];`]],
+      [
+        {
+          ...DATA_ONLY_ROW,
+          legacyRetirement: { staticCommandSets: ['WEB_QUERY_COMMANDS_WITH_PLANTED'] },
+        },
+      ],
+    ).filter((summary) => summary.includes('static command set')),
+    [
+      "(planted cutover row): claims retired static command set 'WEB_QUERY_COMMANDS_WITH_PLANTED', which no production source declares",
+    ],
+  );
+});
+
+test('planted red: a claimed static command set that still lists the command is rejected', () => {
+  assert.deepEqual(
+    summariesFor(
+      PLANTED_RULE,
+      [['src/core/capabilities.ts', `const WEB_QUERY_COMMANDS = ['find', 'planted'];`]],
+      [DATA_ONLY_ROW],
+    ).filter((summary) => summary.includes('still admits')),
+    ['src/core/capabilities.ts: static command set WEB_QUERY_COMMANDS still admits planted'],
+  );
+});
+
+test('a claimed static command set that exists and dropped the command passes', () => {
+  // Scoped to this column: the planted row's singular-execution claims are unrelated here and
+  // have their own cases above.
+  assert.deepEqual(
+    summariesFor(
+      PLANTED_RULE,
+      [['src/core/capabilities.ts', `const WEB_QUERY_COMMANDS = ['find'];`]],
+      [DATA_ONLY_ROW],
+    ).filter((summary) => summary.includes('static command set')),
+    [],
+  );
+});

scripts/layering/runtime-command-cutover-policy.ts

@@ -79,6 +79,7 @@ function rowViolations(
     violations.push(...narrowingViolations(row, file, program));
   }
   violations.push(...exactCallViolations(row, files, programs));
+  violations.push(...staticCommandSetViolations(row, files, programs));
   const sources = new Map(files.map(({ path, source }) => [path, source]));
   for (const check of rowChecks(row)) violations.push(...check(sources));
   return violations;
@@ -356,6 +357,59 @@ function isAdmissionMember(
   );
 }
 
+/**
+ * A data-only admission retirement, proven from both sides.
+ *
+ * A command whose legacy admission was a capability bucket plus membership in a static platform
+ * command set retires no module, route, or dispatch projection — there is no identifier to name
+ * as gone. Naming an invented one satisfies the non-empty shape check while proving nothing, so
+ * the row names the sets themselves: each must still be DECLARED in production source, and must
+ * no longer carry this command.
+ *
+ * The existence half is what an identifier-shaped claim cannot express. The membership half
+ * overlaps the automatic static-set column for `WEB`/`HARMONY`-named sets, deliberately: stating
+ * it here keeps the declared claim self-sufficient rather than dependent on that regex.
+ */
+function staticCommandSetViolations(
+  row: MigratedCommandCutover,
+  files: readonly ProductionSource[],
+  programs: ReadonlyMap<string, AstNode>,
+): UnruledViolation[] {
+  const declared = row.legacyRetirement.staticCommandSets ?? [];
+  if (declared.length === 0) return [];
+  const violations: UnruledViolation[] = [];
+  const seen = new Set<string>();
+  for (const file of files) {
+    const program = programs.get(file.path);
+    if (!program) continue;
+    visitAst(program, (node) => {
+      const name = staticCommandSetName(node, declared);
+      if (name === undefined) return;
+      seen.add(name);
+      if (containsStringLiteral(node['init'], row.command)) {
+        violations.push(at(file, node, `static command set ${name} still admits ${row.command}`));
+      }
+    });
+  }
+  for (const name of declared) {
+    if (seen.has(name)) continue;
+    violations.push({
+      file: `(${row.command} cutover row)`,
+      line: 1,
+      message: `claims retired static command set '${name}', which no production source declares`,
+    });
+  }
+  return violations;
+}
+
+function staticCommandSetName(node: AstNode, declared: readonly string[]): string | undefined {
+  if (node['type'] !== 'VariableDeclarator') return undefined;
+  const id = node['id'] as AstNode | undefined;
+  if (id?.['type'] !== 'Identifier') return undefined;
+  const name = String(id['name']);
+  return declared.includes(name) ? name : undefined;
+}
+
 function containsStringLiteral(node: unknown, expected: string): boolean {
   let found = false;
   visitAst(node, (candidate) => {

scripts/layering/runtime-command-cutover-table.ts

@@ -25,7 +25,8 @@ import { retiredDispatchProjectionViolations } from './runtime-command-cutover-d
  * A row id is a report heading, so it must be unique across every stack that adds rows here.
  * `cutoverTableDefects` rejects a duplicate; lifecycle starts at R28 after the accepted
  * shutdown, install/deploy, and application-lifecycle allocations. Snapshot starts at R32;
- * diff follows at R33, viewport at R34, and get at R36 (R35 is reserved for find).
+ * diff follows at R33, viewport at R34, get at R36, and is at R37. R35 stays reserved for
+ * find, whose cutover is deferred behind the Wave 5 `focus`/`type` surfaces.
  */
 export const MIGRATED_COMMAND_CUTOVERS: readonly MigratedCommandCutover[] = [
   {
@@ -548,6 +549,43 @@ export const MIGRATED_COMMAND_CUTOVERS: readonly MigratedCommandCutover[] = [
       },
     },
   },
+  {
+    rule: 'R37 is-runtime-cutover',
+    command: 'is',
+    subject: 'element predicate',
+    tier: 'request-scoped',
+    execution: 'device-runtime',
+    // `is` retired no module, route, or dispatch projection — it had none. Its whole legacy
+    // admission was the capability bucket (rejected by this row's automatic descriptor column)
+    // plus membership in these two static sets, which is a DATA deletion. Naming the sets proves
+    // it from both sides: each must still be declared in production source and must no longer
+    // list `is`, so neither an invented name nor a skipped deletion can satisfy it.
+    legacyRetirement: {
+      staticCommandSets: ['HARMONYOS_SUPPORTED_COMMANDS', 'WEB_QUERY_COMMANDS'],
+    },
+    runtimeTypeNames: ['SnapshotRuntimeOperations'],
+    operations: { names: ['captureSnapshot', 'captureSnapshotWithoutActiveApp'] },
+    singularExecution: {
+      routes: ['dispatchIsViaRuntime'],
+      operations: ['captureSnapshot', 'captureSnapshotWithoutActiveApp'],
+      // `is` executes through the shared selector seam, so its capture owners are the SAME
+      // selectors `snapshot`/`diff`/`get` count. It declares no operation of its own: every
+      // predicate answers from the resolved tree, so `readTextAtPoint` stays R36's alone.
+      //
+      // Scope, stated so this is not read as absolute: the claim covers how a predicate is
+      // EXECUTED. Since the direct-iOS selector shortcut retired, the bound capture is the only
+      // thing that answers one. It does NOT claim the route makes no other device call — the
+      // Android foreground-blocker diagnostic still reaches adb through
+      // `platforms/android/app-lifecycle.ts`, on the FAILURE path only, where it can enrich an
+      // already-failed response's message but can never produce or change a verdict. That edge
+      // is pre-existing, co-owned with `wait`, and recorded as Wave 6 denominator work; R22's
+      // `appState` is its declared replacement.
+      operationOwners: {
+        captureSnapshot: ['selectActiveAppSnapshot'],
+        captureSnapshotWithoutActiveApp: ['selectSnapshotWithoutActiveApp'],
+      },
+    },
+  },
   {
     rule: 'R34 viewport-runtime-cutover',
     command: 'viewport',

src/__tests__/cli-exit-paths.test.ts

@@ -222,3 +222,39 @@ test('a --debug failure caps the daemon-log-tail dump instead of printing it unb
     'expected the byte cap to drop the oldest lines, not just the 200-line cap',
   );
 });
+
+// The end-to-end half of `is`'s documented contract: "is evaluates UI predicates against a
+// selector expression and exits non-zero on failure" (website/docs/docs/commands.md).
+//
+// This deliberately does NOT know how the daemon decided. It was written when the direct-iOS
+// shortcut answered some predicates itself and returned `{ok: true, pass: false}`, which the CLI
+// rendered as `Passed: is text` with exit 0 (#1739). The shortcut is retired and every predicate
+// now answers from the bound capture, so the guarantee is structural rather than guard-based —
+// and this case survives that change untouched, because a failed assertion must exit non-zero
+// whatever produced the failure.
+test('a failed `is` predicate exits non-zero, whatever answered it', async () => {
+  const restoreEnv = installIsolatedCliTestEnv();
+  const exitSpy = installExitSpy();
+  const stderr = captureStderr();
+  const sendToDaemon = async (): Promise<DaemonResponse> => ({
+    ok: false,
+    error: {
+      code: 'COMMAND_FAILED',
+      message: 'is text failed for selector id=greeting: expected="Welcome" actual="Goodbye"',
+      details: { command: 'is', reason: 'predicate_failed', predicate: 'text' },
+    },
+  });
+
+  try {
+    await runCli(['is', 'text', 'id=greeting', 'Welcome'], { sendToDaemon });
+  } finally {
+    stderr.restore();
+    exitSpy.restore();
+    restoreEnv();
+  }
+
+  assert.deepEqual(exitSpy.calls, [1]);
+  const output = stderr.read();
+  assert.ok(output.includes('COMMAND_FAILED'), 'expected the typed failure on stderr');
+  assert.ok(!output.includes('Passed'), 'a failed assertion must never render as passed');
+});

src/core/__tests__/capabilities.test.ts

@@ -232,7 +232,6 @@ test('macOS supports the Apple runner interaction core but excludes mobile-only
       'find',
       'focus',
       'get',
-      'is',
       'longpress',
       'logs',
       'perf',
@@ -306,7 +305,6 @@ test('Linux supports desktop interaction commands and blocks mobile/unsupported
       'focus',
       'get',
       'home',
-      'is',
       'longpress',
       'press',
       'screenshot',
@@ -334,7 +332,6 @@ test('web supports only the initial browser interaction slice', () => {
       'find',
       'get',
       'hover',
-      'is',
       'press',
       'record',
       'screenshot',

src/core/__tests__/capability-plugin-routing-parity.test.ts

@@ -180,11 +180,9 @@ const HARMONYOS_SUPPORTED_COMMANDS_REF = new Set([
   'fill',
   'find',
   'focus',
-  'get',
   'home',
   'gesture',
   'keyboard',
-  'is',
   'longpress',
   'press',
   'screenshot',
@@ -271,7 +269,6 @@ test('HarmonyOS static capabilities omit runtime-backed command admissions', ()
     'focus',
     'gesture',
     'home',
-    'is',
     'keyboard',
     'longpress',
     'perf',

src/core/capabilities.ts

@@ -47,7 +47,6 @@ const HARMONYOS_SUPPORTED_COMMANDS = new Set<string>([
   'home',
   'gesture',
   'keyboard',
-  'is',
   'longpress',
   'press',
   'scroll',
@@ -56,7 +55,7 @@ const HARMONYOS_SUPPORTED_COMMANDS = new Set<string>([
   'type',
   'wait',
 ]);
-const WEB_QUERY_COMMANDS = ['audio', 'find', 'is', 'wait'] as const;
+const WEB_QUERY_COMMANDS = ['audio', 'find', 'wait'] as const;
 const WEB_INTERACTION_COMMANDS = [
   'click',
   'fill',

src/core/command-descriptor/__tests__/parity.test.ts

@@ -60,6 +60,7 @@ const NO_CAPABILITY_PUBLIC_COMMANDS = new Set<string>([
   PUBLIC_COMMANDS.get,
   PUBLIC_COMMANDS.install,
   PUBLIC_COMMANDS.installFromSource,
+  PUBLIC_COMMANDS.is,
   PUBLIC_COMMANDS.logs,
   PUBLIC_COMMANDS.network,
   PUBLIC_COMMANDS.open,