fix(ci): split the differential CLI env into entry path and node flags

Addresses the P1 review on #2069. Tokenizing AGENT_DEVICE_CLI on whitespace
fixed the flags-plus-script shape but broke the other one: an override like
`/tmp/agent device.mjs`, which main passes through intact, became two arguments.
One variable cannot encode both — any delimiter that separates flags from the
entry can also occur inside a path.

So the two concerns become two variables that cannot be confused:

  AGENT_DEVICE_CLI             the entry script — ONE path, never split
  AGENT_DEVICE_CLI_NODE_FLAGS  node flags — split on whitespace, which is exact
                               because a node flag cannot contain a space

Defaults reproduce today's behavior, and the empty string runs an entry that
needs no flags.

The regression now runs through the production route the review asked for —
environment, parseRunnerArgs, runScenario, spawn — rather than calling
runAgentDeviceEngine with a hand-built argv, which cannot see the environment
contract at all. Each direction is pinned by its own case, verified against both
broken implementations: main's unsplit string fails "node flags stay separate
arguments", and the whitespace split fails "a CLI path containing spaces reaches
the spawn unsplit".

The maestro stub stays out of the spaced directory on purpose: runMaestroEngine
still splits its command on spaces, and a spaced stub path would fail these
tests for the other engine's reason.

Author: thymikee

.github/workflows/conformance-differential.yml

@@ -32,7 +32,11 @@ concurrency:
   cancel-in-progress: true
 
 env:
-  AGENT_DEVICE_CLI: '--experimental-strip-types src/bin.ts'
+  # Entry script and node flags are separate on purpose: one variable cannot
+  # encode both without either corrupting a path that contains spaces or
+  # spawning the whole line as a single node option.
+  AGENT_DEVICE_CLI: 'src/bin.ts'
+  AGENT_DEVICE_CLI_NODE_FLAGS: '--experimental-strip-types'
   DIFFERENTIAL_ONLY: ${{ github.event.inputs.only || '' }}
   # CI should not phone home, and it keeps `maestro --version` to just the
   # version instead of prefixing an analytics notice.

packages/maestro/test/conformance/differential/engine-process.test.ts

@@ -43,33 +43,24 @@ test('agent-device execution accepts a CLI path containing spaces', () => {
   }
 });
 
-// The regression the nightly ran into for two days: AGENT_DEVICE_CLI carries node
-// flags, and passing that line to node as one argument aborts before the CLI loads
-// ("bad option: --experimental-strip-types src/bin.ts"), which every scenario then
-// reports as an engine infrastructure failure rather than a divergence. Running the
-// workflow's own shape end to end is what pins it — a fixture path with no flag
-// cannot tell an argv from a command line.
-test('agent-device execution spawns node flags as their own arguments', () => {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-engine-argv-'));
-  const cliPath = path.join(root, 'cli.ts');
-  try {
-    fs.writeFileSync(cliPath, 'const code: number = 0;\nprocess.exit(code);\n');
-    assert.deepEqual(
-      runAgentDeviceEngine(resolveAgentDeviceCliArgv(`--experimental-strip-types ${cliPath}`), []),
-      { engine: 'agent-device', outcome: 'pass', exitCode: 0 },
-    );
-  } finally {
-    fs.rmSync(root, { recursive: true, force: true });
-  }
-});
-
-test('the agent-device CLI argv is the workflow command line, tokenized', () => {
-  // The fallback is the source-CLI line the device workflows pass explicitly, so a
-  // hand run without the variable reproduces CI rather than looking for a dist build.
-  assert.deepEqual(resolveAgentDeviceCliArgv(undefined), [
+test('the CLI argv keeps node flags and the entry script apart', () => {
+  // The default is the source CLI the device workflows name explicitly.
+  assert.deepEqual(resolveAgentDeviceCliArgv(undefined, undefined), [
     '--experimental-strip-types',
     'src/bin.ts',
   ]);
-  assert.deepEqual(resolveAgentDeviceCliArgv('  '), ['--experimental-strip-types', 'src/bin.ts']);
-  assert.deepEqual(resolveAgentDeviceCliArgv(' bin/agent-device.mjs '), ['bin/agent-device.mjs']);
+  // An entry path is never split, so spaces in it survive.
+  assert.deepEqual(resolveAgentDeviceCliArgv('/tmp/agent device.mjs', ''), [
+    '/tmp/agent device.mjs',
+  ]);
+  assert.deepEqual(resolveAgentDeviceCliArgv('/tmp/agent device.mjs', undefined), [
+    '--experimental-strip-types',
+    '/tmp/agent device.mjs',
+  ]);
+  // Flags are split, which is exact because a node flag cannot contain a space.
+  assert.deepEqual(resolveAgentDeviceCliArgv('bin/x.mjs', '--no-warnings  --enable-source-maps'), [
+    '--no-warnings',
+    '--enable-source-maps',
+    'bin/x.mjs',
+  ]);
 });

packages/maestro/test/conformance/differential/engine-process.ts

@@ -32,28 +32,38 @@ export function classifyAgentDeviceFailure(stdout: string): 'behavioral' | 'infr
   }
 }
 
-/** What the device workflows set AGENT_DEVICE_CLI to, and the default here. */
-const DEFAULT_AGENT_DEVICE_CLI = '--experimental-strip-types src/bin.ts';
-
 /**
- * AGENT_DEVICE_CLI is a command *line* — node flags plus the entry script —
- * mirroring AGENT_DEVICE_PERF_CLI in scripts/perf/config.ts. Tokenizing it here,
- * beside the spawn it feeds, is what keeps `runAgentDeviceEngine`'s precondition
- * satisfiable: no caller downstream holds a string that is neither a path nor an
- * argv. A path with spaces is unreachable through the variable, as in the perf
- * harness; pass it as a single array element instead.
+ * The agent-device CLI the differential drives, as two variables that cannot be
+ * confused for one another:
+ *
+ *   AGENT_DEVICE_CLI            the entry script — ONE path, never split, so a
+ *                               path containing spaces survives verbatim
+ *   AGENT_DEVICE_CLI_NODE_FLAGS node flags — split on whitespace, which is exact
+ *                               because a node flag cannot contain a space
+ *
+ * One variable holding `--experimental-strip-types src/bin.ts` cannot express
+ * both: splitting it corrupts `/tmp/agent device.mjs`, and not splitting it
+ * spawns the whole line as a single node option — the bug that infrastructure-
+ * failed every scenario from 2026-08-25. Set the flags variable to the empty
+ * string to run an entry that needs none (a built `bin/agent-device.mjs`).
  */
-export function resolveAgentDeviceCliArgv(value: string | undefined): string[] {
-  return (value?.trim() || DEFAULT_AGENT_DEVICE_CLI).split(/\s+/);
+const DEFAULT_CLI_ENTRY = 'src/bin.ts';
+const DEFAULT_CLI_NODE_FLAGS = '--experimental-strip-types';
+
+export function resolveAgentDeviceCliArgv(
+  entry: string | undefined,
+  nodeFlags: string | undefined,
+): string[] {
+  const flags = (nodeFlags ?? DEFAULT_CLI_NODE_FLAGS).split(/\s+/).filter(Boolean);
+  return [...flags, entry?.trim() || DEFAULT_CLI_ENTRY];
 }
 
 /**
- * `cliArgv` is a node argv — node flags plus the entry script — never a single
- * command string. AGENT_DEVICE_CLI carries `--experimental-strip-types src/bin.ts`
- * on every device workflow, so a lone `string` here spawns node with that whole
- * line as one option ("bad option: --experimental-strip-types src/bin.ts") and
- * every scenario infrastructure-fails. By the time a path reaches this array it
- * is already its own element, spaces and all.
+ * `cliArgv` is a node argv — flags and entry script as separate elements, built
+ * by `resolveAgentDeviceCliArgv`. Never a command line: spawning one as a single
+ * argument aborts node before the CLI loads ("bad option: --experimental-strip-
+ * types src/bin.ts"), which every scenario then reports as an infrastructure
+ * failure. An entry path reaching this array is already its own element.
  */
 export function runAgentDeviceEngine(cliArgv: readonly string[], args: string[]): EngineResult {
   const result = spawnSync(process.execPath, [...cliArgv, ...args, '--json'], {

packages/maestro/test/conformance/differential/run.test.ts

@@ -186,6 +186,99 @@ test('an ordinary Maestro process failure cannot satisfy a behavioral waiver', (
   }
 });
 
+// The production route the P1 review asked for: environment -> parseRunnerArgs ->
+// runScenario -> spawn. Calling runAgentDeviceEngine with a hand-built argv proves
+// the spawn, but not that the two variables reach it intact — and it is the
+// environment contract that broke the nightly and that a whitespace-split
+// AGENT_DEVICE_CLI would break again in the other direction.
+describe('the agent-device CLI environment route', () => {
+  const ROUTE_SCENARIO = {
+    id: 'cli-env-route',
+    flow: 'differential/flows/settle-after-tap.yaml',
+    comparesAcrossEngines: 'test fixture',
+    expect: 'pass',
+    divergenceMeans: 'test fixture',
+  } as const;
+
+  /** Run one scenario with AGENT_DEVICE_CLI* set, restoring the environment after. */
+  function reportForEnvironment(entry: string, nodeFlags: string, maestroCli: string) {
+    const previous = {
+      entry: process.env.AGENT_DEVICE_CLI,
+      flags: process.env.AGENT_DEVICE_CLI_NODE_FLAGS,
+    };
+    process.env.AGENT_DEVICE_CLI = entry;
+    process.env.AGENT_DEVICE_CLI_NODE_FLAGS = nodeFlags;
+    try {
+      const options = parseRunnerArgs([]);
+      return {
+        argv: options.agentDeviceCliArgv,
+        report: runScenario(ROUTE_SCENARIO, {
+          ...options,
+          maestroBin: `${process.execPath} ${maestroCli}`,
+        }),
+      };
+    } finally {
+      restoreEnv('AGENT_DEVICE_CLI', previous.entry);
+      restoreEnv('AGENT_DEVICE_CLI_NODE_FLAGS', previous.flags);
+    }
+  }
+
+  function restoreEnv(name: string, value: string | undefined): void {
+    if (value === undefined) delete process.env[name];
+    else process.env[name] = value;
+  }
+
+  /**
+   * `spaced` is a subdirectory whose NAME carries the space, so the entry path
+   * holds one whatever the file is called. The maestro stub deliberately stays
+   * out of it: `runMaestroEngine` still splits its command on spaces, and a
+   * spaced stub path would fail this test for the other engine's reason.
+   */
+  function withFixtureRoot(run: (spaced: string, maestroCli: string) => void): void {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-env-route-'));
+    const spaced = path.join(root, 'agent device');
+    fs.mkdirSync(spaced);
+    const maestroCli = path.join(root, 'maestro.mjs');
+    fs.writeFileSync(maestroCli, 'process.exit(0);\n');
+    try {
+      run(spaced, maestroCli);
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  }
+
+  test('a CLI path containing spaces reaches the spawn unsplit', () => {
+    withFixtureRoot((spaced, maestroCli) => {
+      const entry = path.join(spaced, 'cli.mjs');
+      fs.writeFileSync(entry, 'process.exit(0);\n');
+
+      const { argv, report } = reportForEnvironment(entry, '', maestroCli);
+
+      assert.deepEqual(argv, [entry], 'the entry path must stay one argument');
+      assert.equal(report.agentDevice.outcome, 'pass');
+      assert.equal(report.failed, false);
+    });
+  });
+
+  test('node flags stay separate arguments alongside a spaced path', () => {
+    withFixtureRoot((spaced, maestroCli) => {
+      const entry = path.join(spaced, 'cli.ts');
+      fs.writeFileSync(entry, 'const code: number = 0;\nprocess.exit(code);\n');
+
+      const { argv, report } = reportForEnvironment(
+        entry,
+        '--experimental-strip-types',
+        maestroCli,
+      );
+
+      // Neither property is expressible in a single whitespace-joined variable.
+      assert.deepEqual(argv, ['--experimental-strip-types', entry]);
+      assert.equal(report.agentDevice.outcome, 'pass');
+      assert.equal(report.failed, false);
+    });
+  });
+});
+
 test('every device flow targets the fixture app the workflow installs', () => {
   for (const scenario of DIFFERENTIAL_SCENARIOS) {
     const flowPath = path.join(CONFORMANCE_DIR, scenario.flow);

packages/maestro/test/conformance/differential/run.ts

@@ -54,7 +54,10 @@ export function parseRunnerArgs(argv: readonly string[]): RunnerOptions {
   const options: RunnerOptions = {
     dryRun: false,
     maestroBin: process.env.MAESTRO_BIN ?? 'maestro',
-    agentDeviceCliArgv: resolveAgentDeviceCliArgv(process.env.AGENT_DEVICE_CLI),
+    agentDeviceCliArgv: resolveAgentDeviceCliArgv(
+      process.env.AGENT_DEVICE_CLI,
+      process.env.AGENT_DEVICE_CLI_NODE_FLAGS,
+    ),
     traceRoot: process.env.AGENT_DEVICE_ARTIFACTS_DIR,
   };
   for (let i = 0; i < argv.length; i += 1) {