fix(pair-agent): consent before killing a healthy headless daemon

The pair-agent headed switch spawned 'connect --force-restart'
unconditionally — auto-killing a live headless daemon (open tabs, cookies,
logins) in direct contradiction of the iron rule it sits beside ('only an
explicit --force-restart may kill a live daemon'). The CLI now captures
daemon liveness BEFORE ensureServer (which can itself boot a fresh daemon)
and relaunches only when the user passed --force-restart to pair-agent;
otherwise it prints the tab count and continues against the existing daemon.
The /pair-agent skill gains a matching one-way-door consent question
(template half rides the wave's template block).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

browse/test/busy-daemon-iron-rule.test.ts

@@ -146,6 +146,44 @@ describe('#2219 iron rule (CLI integration)', () => {
     }
   }, 30_000);
 
+  test('pair-agent over a live headless daemon WITHOUT --force-restart → daemon survives, notice printed, no headed relaunch', async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'browse-iron-'));
+    const stateFile = path.join(tmpDir, 'browse.json');
+    const daemon = await startHealthyDaemon();
+    try {
+      pidChild = spawn('sleep', ['60'], { stdio: 'ignore' });
+      const daemonPid = pidChild.pid!;
+      const stateContent = {
+        pid: daemonPid,
+        port: daemon.port,
+        token: 'iron-rule-token',
+        startedAt: new Date().toISOString(),
+        serverPath: '',
+        mode: 'launched' as const,
+      };
+      fs.writeFileSync(stateFile, JSON.stringify(stateContent, null, 2));
+
+      // Exit code is NOT asserted: the fake daemon answers /pair with
+      // non-JSON so handlePairAgent fails later — the iron rule under test
+      // is everything that happens BEFORE that: no kill, no headed relaunch.
+      const result = await runCli(['pair-agent'], baseEnv(stateFile));
+
+      // The consent notice: live session named, opt-in flag named.
+      expect(result.stderr).toContain('continuing against it');
+      expect(result.stderr).toContain('--force-restart');
+      // No headed relaunch was attempted.
+      const combined = result.stdout + result.stderr;
+      expect(combined).not.toContain('Opening GStack Browser');
+      // THE IRON RULE: the daemon process was not killed.
+      expect(isProcessAlive(daemonPid)).toBe(true);
+      // And the state file was not clobbered.
+      expect(JSON.parse(fs.readFileSync(stateFile, 'utf-8'))).toEqual(stateContent);
+    } finally {
+      await daemon.close();
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  }, 30_000);
+
   test('wedged-alive daemon + plain command → busy report + nonzero exit, NO kill', async () => {
     const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'browse-iron-'));
     const stateFile = path.join(tmpDir, 'browse.json');

browse/test/pair-agent-optin-gate.test.ts

@@ -122,3 +122,40 @@ describe('gate wiring — every tunnel activation point consults the guard', ()
     expect(SERVER_SRC).toContain("process.env.BROWSE_TUNNEL === '1' && !isPairAgentEnabled()");
   });
 });
+
+describe('pair-agent headed switch — #2219 iron-rule consent gate', () => {
+  // The behavioral leg (live daemon + no flag → notice, no kill) lives in
+  // busy-daemon-iron-rule.test.ts. These source pins cover the wiring the
+  // integration test can't exercise cheaply: the explicit-flag path and the
+  // capture-before-ensureServer ordering.
+
+  test('headed relaunch of a pre-existing live daemon is gated on explicit --force-restart', () => {
+    const gateAt = CLI_SRC.indexOf('if (pairAgentPreexistingDaemonAlive && !globalFlags.forceRestart) {');
+    expect(gateAt).toBeGreaterThan(-1);
+    // Refusal branch: notice printed, connect never spawned.
+    const elseAt = CLI_SRC.indexOf('} else {', gateAt);
+    expect(elseAt).toBeGreaterThan(gateAt);
+    const refusalBranch = CLI_SRC.slice(gateAt, elseAt);
+    expect(refusalBranch).toContain('continuing against it');
+    expect(refusalBranch).toContain('--force-restart to relaunch headed');
+    expect(refusalBranch).not.toContain('Bun.spawn');
+    // Consented branch (no pre-existing daemon OR explicit flag): the spawn
+    // of `connect --force-restart` lives here and ONLY here.
+    const branchEnd = CLI_SRC.indexOf('await handlePairAgent(state, commandArgs);', gateAt);
+    expect(branchEnd).toBeGreaterThan(elseAt);
+    const consentedBranch = CLI_SRC.slice(elseAt, branchEnd);
+    expect(consentedBranch).toContain("Bun.spawn([browseBin, 'connect', '--force-restart']");
+    // No second spawn site outside the gated block.
+    expect(CLI_SRC.indexOf("'connect', '--force-restart'")).toBe(CLI_SRC.lastIndexOf("'connect', '--force-restart'"));
+  });
+
+  test('pre-existing liveness is captured BEFORE ensureServer can boot a fresh daemon', () => {
+    // If the capture ran after ensureServer, a freshly-booted daemon would be
+    // indistinguishable from a session the user cares about — the gate would
+    // then refuse the headed switch even on a clean machine.
+    const captureAt = CLI_SRC.indexOf('pairAgentPreexistingDaemonAlive = Boolean(preState?.pid && isProcessAlive(preState.pid));');
+    const ensureAt = CLI_SRC.indexOf('let state = await ensureServer(globalFlags);');
+    expect(captureAt).toBeGreaterThan(-1);
+    expect(ensureAt).toBeGreaterThan(captureAt);
+  });
+});