refactor(daemon): drop implementation narration from the daemon-exit change

AGENTS.md allows only public API docs, tool directives, and a brief citation to
an external constraint. The identity type, the pid-state union, the single wait
helper and the planted-red assertions carry the invariant; the prose restating
them, and the review history behind them, belong in the PR.

Kept: the exported identity/result types and the wait helper's contract, plus a
two-line citation for the one thing code cannot encode — a terminated pid awaiting
reap answers kill(pid, 0), keeps its start time, and reports `<defunct>`.

Author: thymikee

src/daemon/__tests__/daemon-exit-wait.test.ts

@@ -5,14 +5,9 @@ const DAEMON_COMMAND = '/opt/checkout/dist/src/internal/daemon.js';
 const OURS = 'Mon Aug 24 10:00:00 2026';
 const RECYCLED = 'Mon Aug 24 10:00:07 2026';
 const PID = 4242;
-// Small enough that a regression that waits the budget out still lands inside the
-// unit lane's wall-clock gate and fails on its assertion rather than on the clock.
 const TIMEOUT_MS = 1_000;
 const POLL_MS = 5;
 
-// A live process cannot be made to change identity mid-wait, so the host reads are
-// mocked: a recycled pid is the same live pid reporting a different start time,
-// which is what the host presents after reuse.
 const state = vi.hoisted(() => ({
   alive: new Map<number, boolean>(),
   starts: new Map<number, string>(),
@@ -36,7 +31,6 @@ vi.mock('../../utils/host-process.ts', async (importOriginal) => ({
   },
 }));
 
-/** Delivered signals only; a `0` probe is a liveness read, not a write. */
 const signals: NodeJS.Signals[] = [];
 let onSignal: (signal: NodeJS.Signals) => void = () => {};
 
@@ -81,10 +75,6 @@ test('waitForDaemonExit reports a daemon that keeps its identity as not exited',
   expect(wait.exited).toBe(false);
 });
 
-// A daemon killed by its own parent lingers as a zombie: kill(pid, 0) still succeeds
-// and the start time still matches, while ps reports the command as `<defunct>`.
-// Reading that as a recycled pid would hand the number back to callers while it is
-// still taken, so it must count as neither ending until the reap lands.
 test('waitForDaemonExit keeps waiting through a zombie until the pid is reaped', async () => {
   state.states.set(PID, 'Z+');
   state.commands.set(PID, '<defunct>');
@@ -102,9 +92,6 @@ test('waitForDaemonExit keeps waiting through a zombie until the pid is reaped',
   expect(reaped.exited).toBe(true);
 });
 
-// Planted red for the defect this pair exists to prevent: the grace wait used to poll
-// the bare pid, so a daemon that exited and had its pid reused read as "still running"
-// and the takeover escalated SIGKILL onto whatever now held that number.
 test('stopProcessForTakeover does not SIGKILL a pid recycled during the grace wait', async () => {
   onSignal = (signal) => {
     if (signal === 'SIGTERM') state.starts.set(PID, RECYCLED);

src/daemon/daemon-process.ts

@@ -56,33 +56,19 @@ export type DaemonProcessIdentity = {
 };
 
 export type DaemonExitWait = {
-  /** The pid no longer belongs to the identity: it exited, or the host recycled it. */
+  /** The pid was released, or the host handed it to a different process. */
   exited: boolean;
   elapsedMs: number;
 };
 
-/**
- * Poll for {@link waitForDaemonExit}. {@link classifyDaemonPid} reads `ps` only
- * once the cheap liveness check says the pid is still taken, so a daemon that has
- * already gone costs no subprocess at all.
- */
 const DAEMON_EXIT_POLL_MS = 100;
 
-/**
- * What a pid is doing relative to the identity that claimed it. `exiting` is the
- * state a bare liveness read cannot express: `kill(pid, 0)` still succeeds for a
- * process that has died but has not been reaped yet, while `ps` has already
- * dropped its row — a pid on its way out, not a pid handed to somebody else.
- */
 type DaemonPidState = 'ours' | 'exiting' | 'released' | 'recycled';
 
 function classifyDaemonPid(identity: DaemonProcessIdentity): DaemonPidState {
   if (!isProcessAlive(identity.pid)) return 'released';
-  // State and start time in one `ps` read. A process that has died but has not
-  // been reaped answers kill(pid, 0) AND still reports its original start time,
-  // so the state is the only field that separates it from one still running —
-  // and its command reads `<defunct>`, which would otherwise look like a pid
-  // handed to a different program.
+  // A terminated pid awaiting reap answers kill(pid, 0), keeps its start time, and
+  // reports its command as `<defunct>`; only the process state distinguishes it.
   const observed = readHostProcessIdentityObservations([identity.pid]).get(identity.pid);
   if (!observed || observed.state.startsWith('Z')) return 'exiting';
   if (observed.startTime !== identity.startTime) return 'recycled';
@@ -92,13 +78,8 @@ function classifyDaemonPid(identity: DaemonProcessIdentity): DaemonPidState {
 }
 
 /**
- * Waits for a daemon identity to leave the host. Two endings count as exited: the
- * pid was released, or the host handed it to someone else. Recycling is the one a
- * bare liveness wait gets wrong — it reports a stranger's pid as "still running",
- * which is what lets a grace wait escalate a SIGKILL onto an unrelated process —
- * so escalating callers must branch on this result, never on bare liveness. A pid
- * still being torn down is neither ending, so the wait keeps polling and callers
- * retain the old guarantee that the number is free before they act on it.
+ * Resolves once `identity` has left the host — released or recycled. A pid still
+ * being torn down is neither, so the wait continues until the number is free.
  */
 export async function waitForDaemonExit(
   identity: DaemonProcessIdentity,
@@ -119,12 +100,6 @@ export async function waitForDaemonExit(
   return { exited, elapsedMs: Date.now() - startedAt };
 }
 
-/**
- * The only way this module signals a daemon: identity is re-read immediately
- * before the write, so a pid recycled since the last observation cannot be
- * signaled at all. Escalation safety is then a property of the call, not a rule
- * each call site has to remember.
- */
 function signalDaemonIdentity(identity: DaemonProcessIdentity, signal: NodeJS.Signals): boolean {
   if (!isAgentDeviceDaemonProcess(identity.pid, identity.startTime)) return false;
   return trySignalProcess(identity.pid, signal);

test/integration/smoke-web-platform.test.ts

@@ -193,10 +193,6 @@ async function runWebShutdownSmoke(context: WebSmokeContext): Promise<void> {
     // orchestrator shutting the container down would, rather than going through `close`.
     process.kill(daemonPid, 'SIGTERM');
 
-    // The fleet dying and the daemon exiting are unordered — the daemon awaits the
-    // `agent-browser close` CLI's return, not the disappearance of the pids it reaps — so each
-    // settles on its own deadline from this SIGTERM and neither waits the other out. That the
-    // fleet closed BECAUSE the daemon closed it is held by WEB_SHUTDOWN_IDLE_TIMEOUT_MS above.
     const [after, daemonExit] = await Promise.all([
       settleManagedBrowserProcesses(status),
       waitForDaemonExit(daemonIdentity, {