feat: add Linux command evidence lane (#2017)

* feat: add Linux command evidence lane

* fix: assert Linux find result shape

* fix: read Linux find result envelope

* fix: reset Linux calculator before diff

* fix: release Linux session before reset

* fix: guard Linux evidence session reset

* fix: forward Linux evidence timeout

* fix: tighten Linux evidence assertions

* fix: preserve Linux replay session identity

* fix: close Linux replay session before reset

* fix: share Linux evidence daemon state

* fix: keep Linux swipe evidence in bounds

* fix: keep Linux artifact gap honest

Author: thymikee

.github/workflows/linux.yml

@@ -136,6 +136,14 @@ jobs:
             --report-junit
             test/artifacts/replays-linux.junit.xml
 
+      - name: Reset daemon before Linux command evidence
+        run: pnpm clean:daemon
+
+      - name: Execute Linux command evidence
+        uses: ./.github/actions/run-gate
+        with:
+          gate: linux-command-evidence
+
       - name: Upload Linux artifacts
         if: always()
         uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2

package.json

@@ -193,7 +193,8 @@
     "test:replay:ios-device": "node --experimental-strip-types src/bin.ts test test/integration/replays/ios/device",
     "test:replay:android": "node --experimental-strip-types src/bin.ts test test/integration/replays/android/emulator",
     "test:replay:macos": "node --experimental-strip-types src/bin.ts test test/integration/replays/macos",
-    "test:replay:linux": "node --experimental-strip-types src/bin.ts test test/integration/replays/linux"
+    "test:replay:linux": "node --experimental-strip-types src/bin.ts test test/integration/replays/linux",
+    "test:linux:command-evidence": "node --experimental-strip-types test/integration/linux-e2e/live-runner.ts"
   },
   "files": [
     "bin",

scripts/check-affected/checks.ts

@@ -146,6 +146,12 @@ export const CHECK_CATALOG: readonly CheckSpec[] = [
   gate('replay-ios-device', 'iOS physical device replay suite', 'test:replay:ios-device', false),
   gate('replay-macos', 'macOS replay suite', 'test:replay:macos', false),
   gate('replay-linux', 'Linux replay suite', 'test:replay:linux', false),
+  gate(
+    'linux-command-evidence',
+    'Linux command evidence suite',
+    'test:linux:command-evidence',
+    false,
+  ),
   gate('replay-android', 'Android replay suite', 'test:replay:android', false),
 ];
 

scripts/check-affected/device-lanes.test.ts

@@ -13,7 +13,7 @@ function lanes(file: string): CheckId[] {
   const plan = selectChecks({ changedFiles: [file] });
   assert.equal(plan.failOpen, false, `${file} must not fail open`);
   return plan.checks.filter((id) =>
-    /^macos-coverage$|^replay-|^web-smoke$|^swift-runner-|^macos-helper$|^android-helpers$/.test(
+    /^macos-coverage$|^replay-|^linux-command-evidence$|^web-smoke$|^swift-runner-|^macos-helper$|^android-helpers$/.test(
       id,
     ),
   );
@@ -84,6 +84,7 @@ test('shared runtime surface owns every device lane', () => {
       'replay-ios-device',
       'replay-macos',
       'replay-linux',
+      'linux-command-evidence',
       'replay-android',
     ]);
   }
@@ -103,8 +104,11 @@ test('another family owns only its own lanes, so an Android-only change carries
   assert.deepEqual(lanes('test/integration/android-emulator-e2e/live-runner.ts'), [
     'replay-android',
   ]);
-  assert.deepEqual(lanes('src/platforms/linux/snapshot.ts'), ['replay-linux']);
-  assert.deepEqual(lanes('linux/atspi-dump.py'), ['replay-linux']);
+  assert.deepEqual(lanes('src/platforms/linux/snapshot.ts'), [
+    'replay-linux',
+    'linux-command-evidence',
+  ]);
+  assert.deepEqual(lanes('linux/atspi-dump.py'), ['replay-linux', 'linux-command-evidence']);
   assert.deepEqual(lanes('src/platforms/web/provider.ts'), ['web-smoke']);
   assert.deepEqual(lanes('test/integration/smoke-web-platform.test.ts'), ['web-smoke']);
   // Families with no CI lane fall through to the static gates only.

scripts/check-affected/device-lanes.ts

@@ -1,8 +1,8 @@
 // Device-lane ownership: which live device lanes a changed path can break (#1781 A9-2).
 //
 // The live lanes (`replay-ios`, `replay-ios-device`, `replay-macos`, `replay-android`,
-// `replay-linux`, `web-smoke`) drive the CLI and daemon against a real simulator, emulator,
-// desktop, or browser. Before this rule the selector could reach them only through a full
+// `replay-linux`, `linux-command-evidence`, `web-smoke`) drive the CLI and daemon against a real
+// simulator, emulator, desktop, or browser. Before this rule the selector could reach them only through a full
 // fail-open, so a TypeScript-only Apple change (`src/platforms/apple/**`) produced a plan
 // with no iOS check in it at all, and nothing could route `ios.yml` on the plan.
 //
@@ -42,7 +42,7 @@ const LEAF_LANES: Readonly<Record<Leaf, readonly CheckId[]>> = {
   macos: ['replay-macos'],
   apple: ['replay-ios', 'replay-ios-device', 'replay-macos'],
   android: ['replay-android'],
-  linux: ['replay-linux'],
+  linux: ['replay-linux', 'linux-command-evidence'],
   web: ['web-smoke'],
   harmonyos: [],
   vega: [],

scripts/check-affected/model.ts

@@ -85,6 +85,7 @@ export type CheckId =
   | 'replay-ios-device'
   | 'replay-macos'
   | 'replay-linux'
+  | 'linux-command-evidence'
   | 'replay-android';
 
 // The complete local check universe. A fail-open plan selects all of these;
@@ -146,6 +147,7 @@ export const ALL_CHECKS: readonly CheckId[] = [
   'replay-ios-device',
   'replay-macos',
   'replay-linux',
+  'linux-command-evidence',
   'replay-android',
 ];
 

test/integration/cli-json.ts

@@ -9,17 +9,19 @@ export type CliJsonResult = {
   stderr: string;
 };
 
-export function runSourceCliJsonSync(
-  args: string[],
-  options?: { env?: NodeJS.ProcessEnv },
-): CliJsonResult {
+export type CliJsonOptions = {
+  env?: NodeJS.ProcessEnv;
+  timeoutMs?: number;
+};
+
+export function runSourceCliJsonSync(args: string[], options?: CliJsonOptions): CliJsonResult {
   const result = runCmdSync(
     process.execPath,
     ['--experimental-strip-types', 'src/bin.ts', ...args],
     {
       allowFailure: true,
       env: options?.env,
-      timeoutMs: CLI_TIMEOUT_MS,
+      timeoutMs: options?.timeoutMs ?? CLI_TIMEOUT_MS,
     },
   );
   return cliJsonResult(result);

test/integration/linux-e2e/command-evidence.ad

@@ -0,0 +1,9 @@
+# This script is intentionally outside replays/linux: the existing Linux replay smoke scope is
+# kept unchanged. It owns the lane's test and replay evidence; the runner owns the other direct
+# command-specific evidence.
+context platform=linux target=desktop
+open gnome-calculator --relaunch
+wait "appname=gnome-calculator || windowtitle=Calculator || label=Calculator || label=0 || label=1 || label=5" 15000
+snapshot -i
+find role "button" exists
+close

test/integration/linux-e2e/command-evidence.ts

@@ -0,0 +1,17 @@
+import { PUBLIC_COMMANDS } from '../../../src/command-catalog.ts';
+
+/** Commands exercised by the separate Linux/Xvfb command-evidence lane. */
+export const LINUX_COMMAND_EVIDENCE_COMMANDS = [
+  PUBLIC_COMMANDS.capabilities,
+  PUBLIC_COMMANDS.doctor,
+  PUBLIC_COMMANDS.events,
+  PUBLIC_COMMANDS.replay,
+  PUBLIC_COMMANDS.test,
+  PUBLIC_COMMANDS.batch,
+  PUBLIC_COMMANDS.diff,
+  PUBLIC_COMMANDS.find,
+  PUBLIC_COMMANDS.swipe,
+] as const;
+
+export const LINUX_COMMAND_EVIDENCE_SCRIPT =
+  'test/integration/linux-e2e/command-evidence.ad' as const;

test/integration/linux-e2e/coverage-manifest.ts

@@ -36,6 +36,11 @@ export const LINUX_REPLAY_EVIDENCE: RepositoryEvidence = {
   test: '# Smoke test for Linux desktop automation on CI.',
 };
 
+export const LINUX_COMMAND_EVIDENCE: RepositoryEvidence = {
+  path: 'test/integration/linux-e2e/live-runner.ts',
+  test: 'runLinuxCommandEvidence',
+};
+
 const LINUX_PROVIDER_EVIDENCE: RepositoryEvidence = {
   path: 'test/integration/provider-scenarios/linux-desktop.test.ts',
   test: 'Provider-backed integration Linux desktop flow uses semantic desktop and input providers',
@@ -50,11 +55,16 @@ const LINUX_CAPABILITY_DECLARATION_PATH = 'src/core/command-descriptor/registry.
 const LINUX_CAPABILITY_DECLARATION = 'linux: LINUX_NONE';
 
 const C = PUBLIC_COMMANDS;
-const live = (assertion: string): LinuxPlatformCoverageEntry => ({
+const live = (
+  assertion: string,
+  owner: RepositoryEvidence = LINUX_REPLAY_EVIDENCE,
+): LinuxPlatformCoverageEntry => ({
   assertion,
   level: 'live',
-  owner: LINUX_REPLAY_EVIDENCE,
+  owner,
 });
+const commandEvidenceLive = (assertion: string): LinuxPlatformCoverageEntry =>
+  live(assertion, LINUX_COMMAND_EVIDENCE);
 const contract = (path: string, test: string, assertion: string): LinuxPlatformCoverageEntry => ({
   assertion,
   level: 'command-contract',
@@ -78,21 +88,26 @@ const gap = (assertion: string): LinuxPlatformCoverageEntry => ({
 /**
  * One primary, observable owner for every public command on the Linux desktop.
  *
- * Live rows are limited to the existing Linux replay. Contract rows cite the
- * existing provider scenario or dedicated Linux unit/runtime evidence; they do
- * not turn mocked provider calls into live desktop claims. Capability denials
- * are derived from the owning command-descriptor matrix. Known gaps are
- * explicit follow-up work, not an implicit claim that a generic command works.
+ * Live rows cite either the existing Linux replay or the separate command-evidence
+ * lane. The existing replay scope stays unchanged. Contract rows cite the existing
+ * provider scenario or dedicated Linux unit/runtime evidence; they do not turn
+ * mocked provider calls into live desktop claims. Capability denials are derived
+ * from the owning command-descriptor matrix. Known gaps are explicit follow-up
+ * work, not an implicit claim that a generic command works.
  */
 export const LINUX_PLATFORM_COVERAGE = {
-  [C.artifacts]: gap('No Linux-specific artifact inventory command evidence exists yet'),
+  [C.artifacts]: gap(
+    'No Linux live command creates a downloadable daemon artifact for inventory yet',
+  ),
   [C.devices]: contract(
     LINUX_PROVIDER_EVIDENCE.path,
     LINUX_PROVIDER_EVIDENCE.test,
     'Linux provider scenario inventories the selected desktop device through the daemon client',
   ),
-  [C.capabilities]: gap('No Linux-specific capabilities command evidence exists yet'),
-  [C.doctor]: gap('No Linux-specific doctor command evidence exists yet'),
+  [C.capabilities]: commandEvidenceLive(
+    'the command-evidence lane reads capabilities for the selected Linux desktop',
+  ),
+  [C.doctor]: commandEvidenceLive('the command-evidence lane reads Linux doctor diagnostics'),
   [C.apps]: contract(
     LINUX_RUNTIME_EVIDENCE.path,
     LINUX_RUNTIME_EVIDENCE.test,
@@ -111,15 +126,21 @@ export const LINUX_PLATFORM_COVERAGE = {
   ),
   [C.perf]: denial('perf', 'Linux capability declaration rejects native performance inspection'),
   [C.logs]: gap('No Linux-specific app-log command evidence exists yet'),
-  [C.events]: gap('No Linux-specific session event command evidence exists yet'),
+  [C.events]: commandEvidenceLive(
+    'the command-evidence lane reads the event timeline produced by its Linux session',
+  ),
   [C.network]: contract(
     LINUX_RUNTIME_EVIDENCE.path,
     LINUX_RUNTIME_EVIDENCE.test,
     'Linux runtime facts explicitly report network capture unavailable',
   ),
   [C.audio]: denial('audio', 'Linux capability declaration rejects native audio probing'),
-  [C.replay]: gap('No Linux-specific replay command evidence exists yet'),
-  [C.test]: gap('No Linux-specific test-suite command evidence exists yet'),
+  [C.replay]: commandEvidenceLive(
+    'the command-evidence lane replays a dedicated Linux script with a live session',
+  ),
+  [C.test]: commandEvidenceLive(
+    'the command-evidence lane runs a dedicated Linux script as a test suite',
+  ),
   [C.clipboard]: contract(
     'src/platforms/linux/__tests__/clipboard.test.ts',
     'writeLinuxClipboard uses xclip with stdin on X11',
@@ -143,14 +164,16 @@ export const LINUX_PLATFORM_COVERAGE = {
     LINUX_RUNTIME_EVIDENCE.test,
     'Linux runtime facts explicitly report Apple runner preparation unavailable',
   ),
-  [C.batch]: gap('No Linux-specific batch command evidence exists yet'),
+  [C.batch]: commandEvidenceLive('the command-evidence lane executes two live Linux read steps'),
   [C.close]: contract(
     LINUX_PROVIDER_EVIDENCE.path,
     LINUX_PROVIDER_EVIDENCE.test,
     'Linux provider scenario closes the calculator and observes the desktop close call',
   ),
   [C.snapshot]: live('the existing Linux replay captures the calculator accessibility tree'),
-  [C.diff]: gap('No Linux-specific snapshot diff command evidence exists yet'),
+  [C.diff]: commandEvidenceLive(
+    'the command-evidence lane observes a non-empty calculator snapshot mutation',
+  ),
   [C.wait]: live('the existing Linux replay waits for an observable calculator landmark'),
   [C.alert]: denial('alert', 'Linux capability declaration rejects native alert operations'),
   [C.settings]: denial(
@@ -163,7 +186,7 @@ export const LINUX_PLATFORM_COVERAGE = {
   ),
   [C.record]: gap('No Linux-specific recording command evidence exists yet'),
   [C.trace]: gap('No Linux-specific trace command evidence exists yet'),
-  [C.find]: gap('No Linux-specific find command evidence exists yet'),
+  [C.find]: commandEvidenceLive('the command-evidence lane resolves a live AT-SPI role match'),
   // Promoted from command-contract to live: the desktop replay now clicks a resolved digit
   // button on real Linux hardware and the downstream wait only passes if the click landed
   // (formerly missed — AT-SPI extents were computed screen-absolute-wrong under GTK4; see
@@ -230,7 +253,7 @@ export const LINUX_PLATFORM_COVERAGE = {
     'scrollLinux uses ydotool mousemove --wheel for vertical scroll',
     'Linux scroll dispatch uses the Wayland ydotool wheel primitive',
   ),
-  [C.swipe]: gap('No Linux-specific public swipe command evidence exists yet'),
+  [C.swipe]: commandEvidenceLive('the command-evidence lane dispatches a coordinate swipe'),
   // Promoted from command-contract to live by #1925: the desktop replay now runs a coordinate
   // focus on real Linux hardware, so the migrated `focusPoint` path has live changed-path
   // evidence rather than only the provider scenario at LINUX_PROVIDER_EVIDENCE.
@@ -254,6 +277,16 @@ export const LINUX_PLATFORM_COVERAGE_CLASSIFICATION_SUMMARY = buildCoverageClass
 
 export function liveCommandsForLinuxReplay(): PublicCommand[] {
   return Object.entries(LINUX_PLATFORM_COVERAGE)
-    .filter(([, entry]) => entry.level === 'live')
+    .filter(
+      ([, entry]) => entry.level === 'live' && entry.owner.path === LINUX_REPLAY_EVIDENCE.path,
+    )
+    .map(([command]) => command as PublicCommand);
+}
+
+export function liveCommandsForLinuxCommandEvidence(): PublicCommand[] {
+  return Object.entries(LINUX_PLATFORM_COVERAGE)
+    .filter(
+      ([, entry]) => entry.level === 'live' && entry.owner.path === LINUX_COMMAND_EVIDENCE.path,
+    )
     .map(([command]) => command as PublicCommand);
 }