@chorus-aidlc/chorus 0.12.1 → 0.13.1

package/chorus.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { execSync, fork } from "node:child_process";
+import { fork, spawn } from "node:child_process";
 import { randomBytes, createHash } from "node:crypto";
 import {
   existsSync,
@@ -38,6 +38,15 @@ import {
 // (`chorus daemon` / `chorus login`) never registers the server's handlers.
 // Pure module → unit-testable without this entry's import-time side effects.
 import { installServerSignalHandlers } from "./cli/server-signal-handlers.mjs";
+// Embedded-PGlite launch (child-exit capture + port-conflict fail-fast). Extracted
+// into a pure, dependency-injected module so it is unit-testable with fakes — see
+// cli/embedded-db.mjs and its __tests__ (GitHub #379).
+import {
+  launchEmbeddedPglite,
+  isPrismaAuthFailure,
+  formatMigrationAuthDiagnostic,
+  maskDbUrl,
+} from "./cli/embedded-db.mjs";
 
 /** Read the package version once for help/version output. */
 function pkgVersion() {
@@ -247,6 +256,27 @@ function waitForTcp(host, tcpPort, maxRetries = 30, intervalMs = 500) {
   });
 }
 
+// Quick one-shot probe: is something ALREADY listening on host:port right now?
+// Used as a pre-flight before forking embedded PGlite so we never fork onto a port
+// held by a foreign process (e.g. a real Postgres) and then mistake it for our own
+// PGlite. Resolves true if a TCP connection succeeds, false otherwise. (GitHub #379)
+function isPortOccupied(host, tcpPort, timeoutMs = 1000) {
+  return new Promise((resolve) => {
+    const socket = createConnection({ host, port: tcpPort });
+    let settled = false;
+    const done = (occupied) => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      resolve(occupied);
+    };
+    socket.setTimeout(timeoutMs);
+    socket.once("connect", () => done(true));
+    socket.once("timeout", () => done(false));
+    socket.once("error", () => done(false));
+  });
+}
+
 function ensureSecret() {
   const secretPath = join(dataDir, ".secret");
   if (process.env.NEXTAUTH_SECRET) return;
@@ -311,34 +341,52 @@ async function main() {
     const pgliteSocketEntry = resolveOrDie("@electric-sql/pglite-socket");
     const serverScript = resolve(dirname(pgliteSocketEntry), "scripts", "server.js");
 
-    pgliteProcess = fork(serverScript, [
-      `--db=${join(dataDir, "pglite")}`,
-      `--port=${PGLITE_PORT}`,
-      "--max-connections=10",
-    ], { stdio: "ignore", detached: false });
-
-    pgliteProcess.on("error", (err) => {
-      // MODULE_NOT_FOUND is unreachable after the resolveOrDie fix above, but
-      // guard against regressions (see issue #214).
-      if (err.code === "MODULE_NOT_FOUND") {
-        console.error(`PGlite server script unreachable: ${err.message}`);
-      } else {
-        console.error("PGlite process error:", err.message);
-      }
-      process.exit(1);
+    // Launch via the pure, dependency-injected module so a foreign listener on
+    // PGLITE_PORT can never be mistaken for our PGlite (GitHub #379): it pre-flights
+    // the port, then treats the child exiting before ready as fatal (any exit code,
+    // incl. the reproduced EADDRINUSE -> exit 0), instead of trusting "someone is
+    // listening". `waitForTcp`/`isPortOccupied` are injected so the logic unit-tests
+    // with fakes (see cli/embedded-db.mjs + __tests__).
+    const launch = await launchEmbeddedPglite({
+      host: "localhost",
+      port: PGLITE_PORT,
+      fork: () =>
+        fork(serverScript, [
+          `--db=${join(dataDir, "pglite")}`,
+          `--port=${PGLITE_PORT}`,
+          "--max-connections=10",
+        ], { stdio: "ignore", detached: false }),
+      waitForTcp,
+      preflightCheck: isPortOccupied,
+      logger: console,
     });
 
-    try {
-      await waitForTcp("localhost", PGLITE_PORT);
-    } catch (err) {
-      console.error(`\nERROR: ${err.message}`);
-      console.error(`\nPossible causes:`);
-      console.error(`  - Port ${PGLITE_PORT} is already in use`);
-      console.error(`  - Corrupt data in ${join(dataDir, "pglite")}/`);
+    if (!launch.ok) {
+      if (launch.reason === "child-exited") {
+        // The child (our PGlite) exited before the port was confirmed ready. The most
+        // common cause is the port being occupied by another process the child could
+        // not bind (EADDRINUSE), which PGlite catches and exits 0 — so key the message
+        // off the failure, not the exit code.
+        console.error(
+          `\nERROR: Embedded PostgreSQL (PGlite) exited before it was ready ` +
+            `(exit code ${launch.exitInfo?.code ?? "unknown"}).`
+        );
+        console.error(`\nMost likely port ${PGLITE_PORT} is already in use by another process`);
+        console.error(`(e.g. a real PostgreSQL). Free the port, or run on a different one:`);
+        console.error(`  chorus --pglite-port <port>`);
+      } else if (launch.reason === "not-ready") {
+        console.error(`\nERROR: ${launch.error?.message ?? "PGlite failed to start."}`);
+        console.error(`\nPossible causes:`);
+        console.error(`  - Port ${PGLITE_PORT} is already in use`);
+        console.error(`  - Corrupt data in ${join(dataDir, "pglite")}/`);
+      } else if (launch.reason === "child-error") {
+        console.error("PGlite process error:", launch.error?.message ?? String(launch.error));
+      }
+      // reason === "port-occupied" already logged the actionable message in the module.
       process.exit(1);
     }
 
-    console.log(`PGlite ready on port ${PGLITE_PORT}.`);
+    pgliteProcess = launch.child;
     process.env.DATABASE_URL = `postgresql://postgres:postgres@localhost:${PGLITE_PORT}/postgres?sslmode=disable`;
   }
 
@@ -350,14 +398,49 @@ async function main() {
   // 3. Run database migrations
   console.log("Running database migrations...");
   const prismaBin = resolveOrDie("prisma/build/index.js");
-  try {
-    execSync(`"${process.execPath}" "${prismaBin}" migrate deploy`, {
+  // Tee the migrate output: stream each chunk to the parent's stdout/stderr LIVE (so
+  // "Applying migration …" progress appears as it happens, not batched at the end) AND
+  // buffer it so an authentication failure can be classified and rewritten into an
+  // actionable Chorus diagnostic (GitHub #379).
+  const migrateResult = await new Promise((resolveMigrate) => {
+    const child = spawn(process.execPath, [prismaBin, "migrate", "deploy"], {
       cwd: __dirname,
-      stdio: "inherit",
       env: { ...process.env },
+      stdio: ["inherit", "pipe", "pipe"],
     });
-  } catch {
-    console.error("ERROR: Database migration failed.");
+    let out = "";
+    let err = "";
+    child.stdout.on("data", (chunk) => {
+      out += chunk;
+      process.stdout.write(chunk); // live echo
+    });
+    child.stderr.on("data", (chunk) => {
+      err += chunk;
+      process.stderr.write(chunk); // live echo
+    });
+    child.on("error", (e) => resolveMigrate({ status: 1, stdout: out, stderr: `${err}\n${e.message}` }));
+    child.on("close", (code, signal) => {
+      // A null exit code means the migrate process was killed by a signal — treat that
+      // as a failure (status 1), never as success, so we don't start the server against
+      // a half-migrated database.
+      resolveMigrate({ status: code === null ? 1 : code, stdout: out, stderr: err });
+    });
+  });
+  if (migrateResult.status !== 0) {
+    const combined = `${migrateResult.stdout ?? ""}\n${migrateResult.stderr ?? ""}`;
+    if (isPrismaAuthFailure(combined)) {
+      // Replace the bare Prisma P1000 (the last thing the user would otherwise see)
+      // with a self-explaining, path-appropriate diagnostic.
+      console.error(
+        formatMigrationAuthDiagnostic({
+          effectiveUrl: process.env.DATABASE_URL,
+          startedEmbedded: startEmbeddedPglite,
+          pglitePort: PGLITE_PORT,
+        })
+      );
+    } else {
+      console.error("ERROR: Database migration failed.");
+    }
     process.exit(1);
   }
   console.log("Migrations completed.");
@@ -389,11 +472,12 @@ async function main() {
   console.log("");
   console.log(`  URL:       http://${hostname === "0.0.0.0" ? "localhost" : hostname}:${port}`);
   console.log(`  Data:      ${dataDir}`);
-  const dbLabel = usePglite
-    ? (startEmbeddedPglite
-        ? "PGlite (embedded, pg.Pool max=1)"
-        : "PGlite (external, pg.Pool max=1)")
-    : "external PostgreSQL";
+  // When embedded PGlite was skipped, DATABASE_URL is what we actually connected to —
+  // name its host:port (credentials masked) so a residual/unintended export is visible
+  // rather than silent (GitHub #379, D4). Precedence semantics are unchanged.
+  const dbLabel = startEmbeddedPglite
+    ? "PGlite (embedded, pg.Pool max=1)"
+    : `${usePglite ? "PGlite (external, pg.Pool max=1)" : "external PostgreSQL"} (from DATABASE_URL: ${maskDbUrl(process.env.DATABASE_URL)})`;
   console.log(`  Database:  ${dbLabel}`);
   console.log(`  Redis:     ${process.env.REDIS_URL ? "connected" : "disabled (in-memory EventBus)"}`);
   const maskedPassword = process.env.DEFAULT_PASSWORD === "chorus"

package/cli/client-args.mjs

@@ -11,7 +11,7 @@
  * default long-lived daemon) is intentionally NOT in this set — it is the
  * absence of a recognized sub-action token.
  */
-export const DAEMON_ACTIONS = new Set(["stop", "status", "restart", "logs"]);
+export const DAEMON_ACTIONS = new Set(["stop", "status", "restart", "logs", "install", "uninstall"]);
 
 /** Known agent backends. Only `claude-code` is implemented; the rest reserve
  * the extension point (see daemon-agent-selection). Exported for the resolver
@@ -22,7 +22,8 @@ export const KNOWN_AGENTS = new Set(["claude-code"]);
  * Parse the client-subcommand flags out of an arg list. Recognizes the
  * pre-existing `--url` / `--api-key` / `--sigint-timeout` (space and `=` forms)
  * and boolean `--yolo`, plus the new `--agent <type>` (space + `=`), boolean
- * `--chorus-only`, `--verbose`, `-d`/`--detach`, and `--help`/`-h`.
+ * `--chorus-only`, `--verbose`, `-d`/`--detach`, `--force` (stop's forced
+ * pidfile cleanup), and `--help`/`-h`.
  *
  * Only keys that appear are set, so callers can distinguish "unset" from
  * "false" (important for layered env/flag precedence downstream).
@@ -37,7 +38,7 @@ export const KNOWN_AGENTS = new Set(["claude-code"]);
  * @returns {{
  *   url?: string, apiKey?: string, yolo?: boolean, sigintTimeout?: string,
  *   agent?: string, chorusOnly?: boolean, verbose?: boolean, detach?: boolean,
- *   cwd?: string[], help?: boolean,
+ *   cwd?: string[], force?: boolean, help?: boolean,
  * }}
  */
 export function parseClientFlags(argv) {
@@ -61,6 +62,7 @@ export function parseClientFlags(argv) {
     else if (a === "--chorus-only") out.chorusOnly = true;
     else if (a === "--verbose") out.verbose = true;
     else if (a === "-d" || a === "--detach") out.detach = true;
+    else if (a === "--force") out.force = true;
     else if (a === "--help" || a === "-h") out.help = true;
   }
   return out;
@@ -76,7 +78,7 @@ export function parseClientFlags(argv) {
  * or an unknown leading token) is the normal long-lived daemon (`run`).
  *
  * @param {string[]} rest  argv after the `daemon` subcommand token
- * @returns {"run"|"stop"|"status"|"restart"|"logs"}
+ * @returns {"run"|"stop"|"status"|"restart"|"logs"|"install"|"uninstall"}
  */
 export function parseDaemonAction(rest) {
   const first = rest[0];
@@ -98,10 +100,18 @@ agent notification stream, and wake a local headless agent on task dispatch.
 USAGE
   chorus daemon [options]              Run the daemon (foreground)
   chorus daemon -d [options]           Run the daemon in the background (detached)
-  chorus daemon stop                   Stop the background daemon
-  chorus daemon status                 Show whether the background daemon is running
-  chorus daemon restart                Restart the background daemon
-  chorus daemon logs                   Show the background daemon log
+  chorus daemon install [options]      Install as a boot-autostart service and
+                                       start it now (Linux systemd --user;
+                                       macOS/Windows print a template + steps)
+  chorus daemon uninstall              Remove the installed service (Linux) /
+                                       print removal steps (macOS/Windows)
+  chorus daemon stop                   Stop the daemon (delegates to the service
+                                       manager when installed, else the pidfile)
+  chorus daemon stop --force           Force-clean the pidfile when a stuck or
+                                       unverifiable pid blocks a normal stop
+  chorus daemon status                 Show whether the daemon is running
+  chorus daemon restart                Restart the daemon
+  chorus daemon logs                   Show the daemon log (journal when installed)
 
 OPTIONS
   --url <url>              Remote Chorus server URL            (env: CHORUS_URL)
@@ -130,11 +140,23 @@ CREDENTIALS
   ~/.chorus/daemon.json (from 'chorus login') > Claude Code plugin config.
   On a TTY with no resolvable credentials, the daemon prompts to complete them.
 
+SERVICE (install)
+  'chorus daemon install' is the recommended way to run the daemon permanently.
+  On Linux it generates a systemd --user unit that runs the daemon in the
+  FOREGROUND (Type=simple, no -d) so systemd owns the process directly: it
+  starts at login, restarts on failure, and 'systemctl --user stop' shuts it
+  down gracefully. Do NOT hand-write a Type=forking unit around 'chorus daemon
+  -d' — the daemon self-daemonizes, which systemd cannot track and which loops
+  on restart. The install captures the --cwd / --agent / --chorus-only flags you
+  pass. On macOS/Windows install prints a correct template you install manually.
+
 EXAMPLES
   chorus daemon                        # Foreground, default yolo (TTY confirms once)
   chorus daemon --chorus-only          # Restrict the woken agent to Chorus tools
   chorus daemon -d                     # Background; see 'chorus daemon logs'
-  chorus daemon stop                   # Stop the background daemon
+  chorus daemon install --cwd ~/proj   # Install + start as a boot service (Linux)
+  chorus daemon uninstall              # Remove the installed service
+  chorus daemon stop                   # Stop the daemon
 `;
 }
 

package/cli/control-handler.mjs

@@ -38,8 +38,13 @@ const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
  *                                            (null until the SSE handshake reports it).
  *   killer?: (child: any, opts: any) => Promise<any>,  Injectable; defaults to killProcessTree.
  *   sigintTimeoutMs?: number,                           Layered-resolved escalation window.
- *   redispatchResume?: (entityType: string, entityUuid: string) => void,  Re-run a wake
- *                                            for a resumed entity (子3); injected by the daemon.
+ *   redispatchResume?: (entityType: string, entityUuid: string, resumeReason?: string) => void,
+ *                                            Re-run a wake for a resumed entity (子3); injected
+ *                                            by the daemon. `resumeReason` ("user" | "crash",
+ *                                            add-crash-execution-resume) is the row's prior
+ *                                            interruptedReason from the control event — it
+ *                                            selects the continue-instruction variant; absent
+ *                                            or unknown degrades to the user-resume prompt.
  *   deliverTurn?: (turnUuid?: string) => void, Dispatch a PRECISE pending turn by uuid
  *                                            (子2 — origin-only live delivery). On a
  *                                            `deliver_turn` control event (after the Check-1
@@ -134,11 +139,23 @@ export function createControlHandler(deps) {
 
       // --- resume: re-dispatch the wake for this entity (子3). No running-child
       //     check — the subprocess is gone (it was interrupted); the wake path will
-      //     re-spawn and `--resume` the existing session. ---
+      //     re-spawn and `--resume` the existing session. `resumeReason` (the row's
+      //     prior interruptedReason, add-crash-execution-resume) is threaded through
+      //     so the wake prompt can state a crash explicitly; anything but the two
+      //     known values (or an older server sending none) degrades to undefined →
+      //     the existing user-resume prompt. ---
       if (command === "resume") {
-        logger.info(`[Chorus] control: resuming ${entityType}:${entityUuid} (re-dispatch wake)`);
+        const resumeReason =
+          event.resumeReason === "user" || event.resumeReason === "crash"
+            ? event.resumeReason
+            : undefined;
+        logger.info(
+          `[Chorus] control: resuming ${entityType}:${entityUuid} (re-dispatch wake` +
+            (resumeReason ? `, reason=${resumeReason}` : "") +
+            `)`
+        );
         try {
-          redispatchResume?.(entityType, entityUuid);
+          redispatchResume?.(entityType, entityUuid, resumeReason);
         } catch (err) {
           logger.warn(`[Chorus] control: resume re-dispatch failed for ${entityType}:${entityUuid}: ${err}`);
         }

package/cli/daemon-lifecycle.mjs

@@ -7,10 +7,11 @@
 // are unit-testable from a single host.
 //
 // State files live alongside the credentials in ~/.chorus:
-//   pidfile  ~/.chorus/daemon.pid   (the background daemon's pid)
+//   pidfile  ~/.chorus/daemon.pid   (JSON {pid, startedAt?, argsHint?}; legacy
+//                                    bare-number files from older CLIs still read)
 //   logfile  ~/.chorus/daemon.log   (its redirected stdout+stderr)
 
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import {
   existsSync,
   mkdirSync,
@@ -32,6 +33,7 @@ function defaultIO() {
     unlinkSync,
     writeFileSync,
     spawn,
+    spawnSync,
     // process.kill with signal 0 is the portable liveness probe (no signal sent).
     kill: (pid, sig) => process.kill(pid, sig),
     platform: process.platform,
@@ -50,48 +52,183 @@ export function logFilePath(io = defaultIO()) {
 }
 
 /**
- * Read the recorded pid, or null when absent / unreadable / malformed.
+ * The cmdline marker every legacy (pre-identity) chorus daemon carries — the
+ * fallback identity check when the pidfile recorded no argsHint.
+ */
+const DAEMON_CMD_MARKER = "daemon";
+
+/**
+ * Read the recorded pidfile as a structured record, or null when absent /
+ * unreadable / malformed. Two on-disk formats:
+ *   - JSON `{pid, startedAt?, argsHint?}` (current — written by startBackground)
+ *   - bare pid number (legacy — pre-identity CLIs) → `{ pid, legacy: true }`
  * @param {object} [io]
- * @returns {number|null}
+ * @returns {{ pid: number, startedAt?: string, argsHint?: string, legacy?: boolean }|null}
  */
-export function readPid(io = defaultIO()) {
+export function readPidRecord(io = defaultIO()) {
   const path = pidFilePath(io);
   try {
     if (!io.existsSync(path)) return null;
-    const raw = io.readFileSync(path, "utf8");
-    const pid = Number.parseInt(String(raw).trim(), 10);
-    return Number.isInteger(pid) && pid > 0 ? pid : null;
+    const raw = String(io.readFileSync(path, "utf8")).trim();
+    if (raw.startsWith("{")) {
+      const parsed = JSON.parse(raw);
+      const pid = Number.parseInt(String(parsed.pid), 10);
+      if (!Number.isInteger(pid) || pid <= 0) return null;
+      const record = { pid };
+      if (typeof parsed.startedAt === "string" && parsed.startedAt) record.startedAt = parsed.startedAt;
+      if (typeof parsed.argsHint === "string" && parsed.argsHint) record.argsHint = parsed.argsHint;
+      return record;
+    }
+    const pid = Number.parseInt(raw, 10);
+    return Number.isInteger(pid) && pid > 0 ? { pid, legacy: true } : null;
   } catch {
     return null;
   }
 }
 
 /**
- * Is `pid` a live process? Uses signal 0 (sends nothing; throws ESRCH when the
- * pid is gone, EPERM when alive-but-not-ours → still "alive").
+ * Read the recorded pid, or null when absent / unreadable / malformed.
+ * Thin compatibility wrapper over readPidRecord.
+ * @param {object} [io]
+ * @returns {number|null}
+ */
+export function readPid(io = defaultIO()) {
+  return readPidRecord(io)?.pid ?? null;
+}
+
+/**
+ * Query the identity (command line + start time) of the process currently
+ * occupying `pid`. One subprocess invocation, argument arrays only (no
+ * `shell:true`), pure JS:
+ *   - POSIX: `ps -p <pid> -o lstart=,args=` (lstart is second-resolution and
+ *     stable across probes of the same process). busybox `ps` rejects `-p` and
+ *     `-o lstart` → retry `ps -o pid=,args=` (full-table) and filter by the
+ *     pid column for cmdline-only verification.
+ *   - Windows: PowerShell `Get-CimInstance Win32_Process` (wmic is deprecated).
  * @param {number} pid @param {object} [io]
+ * @returns {{ cmdline: string, startedAt: string|null }|null} null = query failed
  */
-export function processAlive(pid, io = defaultIO()) {
-  if (!Number.isInteger(pid) || pid <= 0) return false;
+export function queryProcessIdentity(pid, io = defaultIO()) {
+  if (!Number.isInteger(pid) || pid <= 0) return null;
   try {
-    io.kill(pid, 0);
-    return true;
+    if (io.platform === "win32") {
+      const r = io.spawnSync(
+        "powershell",
+        [
+          "-NoProfile",
+          "-Command",
+          `Get-CimInstance Win32_Process -Filter 'ProcessId=${pid}' | Select-Object CommandLine,CreationDate | ConvertTo-Json`,
+        ],
+        { encoding: "utf8", windowsHide: true }
+      );
+      if (!r || r.status !== 0 || !r.stdout) return null;
+      const parsed = JSON.parse(r.stdout);
+      if (!parsed || typeof parsed.CommandLine !== "string") return null;
+      return { cmdline: parsed.CommandLine, startedAt: parsed.CreationDate ? String(parsed.CreationDate) : null };
+    }
+    // POSIX: lstart= + args= in one call. Output shape (no headers):
+    //   "Thu Jul  2 21:22:55 2026 /usr/bin/node /x/chorus.mjs daemon"
+    // lstart is a fixed 5-field prefix (dow mon dd hh:mm:ss yyyy).
+    const full = io.spawnSync("ps", ["-p", String(pid), "-o", "lstart=,args="], { encoding: "utf8" });
+    if (full && full.status === 0 && full.stdout && full.stdout.trim()) {
+      const line = full.stdout.trim();
+      const fields = line.split(/\s+/);
+      if (fields.length >= 6) {
+        const startedAt = fields.slice(0, 5).join(" ");
+        const cmdline = fields.slice(5).join(" ");
+        if (cmdline) return { cmdline, startedAt };
+      }
+    }
+    // busybox fallback: busybox ps rejects -p AND -o lstart (it only knows -o
+    // and -T), so list every process as "pid args" and filter by the pid
+    // column ourselves. Cmdline verification still possible; no start time.
+    const argsOnly = io.spawnSync("ps", ["-o", "pid=,args="], { encoding: "utf8" });
+    if (argsOnly && argsOnly.status === 0 && argsOnly.stdout) {
+      for (const line of argsOnly.stdout.split("\n")) {
+        const m = line.trim().match(/^(\d+)\s+(.+)$/);
+        if (m && Number.parseInt(m[1], 10) === pid) {
+          return { cmdline: m[2].trim(), startedAt: null };
+        }
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Is the process recorded by `record` still OUR live daemon? Identity-verified
+ * probe (fix-daemon-stale-pid-identity): pid existence alone is not enough —
+ * after a reboot the OS recycles pids, and a foreign owner surfaces as EPERM,
+ * which the old probe misread as "daemon alive". Decision table (tech design):
+ *   - ESRCH / invalid pid                → false (stale)
+ *   - pid exists (OK or EPERM):
+ *       identity recorded    → argsHint (when recorded) decides ALONE: cmdline
+ *                              contains it → true, else false. startedAt only
+ *                              decides when no argsHint was recorded; query
+ *                              failed → true (never auto-clean an identity we
+ *                              could not verify)
+ *       legacy record        → cmdline contains the daemon marker → true;
+ *                              foreign cmdline → false; query failed → EPERM
+ *                              proves it is not ours (same-user daemon) → false,
+ *                              while a signalable pid stays conservatively true
+ * Accepts a bare pid (number) for backward compatibility → treated as legacy.
+ * @param {number|{pid:number,startedAt?:string,argsHint?:string,legacy?:boolean}} record
+ * @param {object} [io]
+ */
+export function processAlive(record, io = defaultIO()) {
+  const rec = typeof record === "number" ? { pid: record, legacy: true } : record;
+  if (!rec || !Number.isInteger(rec.pid) || rec.pid <= 0) return false;
+  let eperm = false;
+  try {
+    io.kill(rec.pid, 0);
   } catch (err) {
-    return err && err.code === "EPERM";
+    if (!err || err.code !== "EPERM") return false;
+    eperm = true;
   }
+  // The pid exists. Verify the occupant is still our daemon.
+  const identity = queryProcessIdentity(rec.pid, io);
+  const hasRecordedIdentity = Boolean(rec.startedAt || rec.argsHint);
+  if (hasRecordedIdentity) {
+    if (identity === null) return true; // unverifiable → conservative: running
+    // Collapse whitespace on both sides: the ps parse re-joins fields with
+    // single spaces, so an argsHint containing consecutive spaces must not
+    // read as a mismatch (false-stale is the dangerous direction).
+    const liveCmd = identity.cmdline.replace(/\s+/g, " ");
+    const hint = rec.argsHint ? rec.argsHint.replace(/\s+/g, " ") : null;
+    // argsHint decides ALONE when recorded (fix-daemon-stop-ntp-false-stale):
+    // startedAt strings are clock-derived (POSIX lstart is recomputed from
+    // btime + start ticks at query time), so an NTP step after spawn shifts
+    // them for the SAME process — it must never veto a matching argsHint, or
+    // a boot-autostarted daemon becomes unstoppable once chrony corrects the
+    // clock. startedAt still decides for records without an argsHint.
+    if (hint) return liveCmd.includes(hint);
+    if (rec.startedAt && identity.startedAt !== null && identity.startedAt !== rec.startedAt) return false;
+    return true;
+  }
+  // Legacy record (no identity metadata): cmdline-marker fallback.
+  if (identity === null) {
+    // EPERM on a legacy record already proves the process belongs to another
+    // user — the CLI and daemon always run as the same user (q3=a self-heal,
+    // covers busybox systems where ps cannot report identity).
+    return !eperm;
+  }
+  return identity.cmdline.includes(DAEMON_CMD_MARKER);
 }
 
 /**
  * Current daemon status from the pidfile.
  * @param {object} [io]
  * @returns {{ running: boolean, pid: number|null, stale: boolean }}
- *   `stale` = a pidfile exists but its pid is dead (left behind by a crash).
+ *   `stale` = a pidfile exists but its pid is dead OR its identity no longer
+ *   matches (pid recycled after a reboot / crash).
  */
 export function isRunning(io = defaultIO()) {
-  const pid = readPid(io);
-  if (pid == null) return { running: false, pid: null, stale: false };
-  const alive = processAlive(pid, io);
-  return { running: alive, pid, stale: !alive };
+  const record = readPidRecord(io);
+  if (record == null) return { running: false, pid: null, stale: false };
+  const alive = processAlive(record, io);
+  return { running: alive, pid: record.pid, stale: !alive };
 }
 
 /** Ensure ~/.chorus exists for the pid/log files. */
@@ -145,22 +282,43 @@ export function startBackground(spec, io = defaultIO()) {
   // Let the parent exit without waiting on the child (POSIX + Windows).
   child.unref?.();
 
+  // Record the child's IDENTITY alongside its pid so later probes can tell
+  // "our daemon" from "a reboot-recycled pid" (fix-daemon-stale-pid-identity).
+  // argsHint: a distinguishing substring of the spawned command line. startedAt:
+  // the same query the probe uses (string-equality comparison, no clock math);
+  // a failed post-spawn query degrades to a record without startedAt.
+  const record = { pid: child.pid };
+  const argsHint = (spec.args ?? []).join(" ").trim();
+  if (argsHint) record.argsHint = argsHint;
+  const identity = queryProcessIdentity(child.pid, io);
+  if (identity?.startedAt) record.startedAt = identity.startedAt;
+
   ensureDir(pidFile, io);
-  io.writeFileSync(pidFile, `${child.pid}\n`, { mode: 0o600 });
+  io.writeFileSync(pidFile, `${JSON.stringify(record)}\n`, { mode: 0o600 });
   return { started: true, pid: child.pid, logFile, pidFile };
 }
 
 /**
  * Stop the recorded background daemon: signal it, then remove the pidfile.
- * @param {object} [io]
- * @returns {{ stopped: boolean, pid: number|null, reason: "stopped"|"not-running"|"stale-cleared"|"error", message: string }}
+ *
+ * `opts.force` (the `chorus daemon stop --force` escape hatch): best-effort
+ * SIGTERM (failure ignored), then unlink the pidfile UNCONDITIONALLY — for
+ * stuck states the identity probe cannot resolve (e.g. an unverifiable pid the
+ * operator knows is not the daemon).
+ * @param {object} [io] @param {{ force?: boolean }} [opts]
+ * @returns {{ stopped: boolean, pid: number|null, reason: "stopped"|"not-running"|"stale-cleared"|"forced"|"error", message: string }}
  */
-export function stopDaemon(io = defaultIO()) {
+export function stopDaemon(io = defaultIO(), opts = {}) {
   const pidFile = pidFilePath(io);
   const status = isRunning(io);
   if (status.pid == null) {
     return { stopped: false, pid: null, reason: "not-running", message: "no daemon is running (no pidfile)" };
   }
+  if (opts.force) {
+    try { io.kill(status.pid, "SIGTERM"); } catch { /* best-effort by design */ }
+    try { io.unlinkSync(pidFile); } catch { /* best-effort */ }
+    return { stopped: true, pid: status.pid, reason: "forced", message: `forced cleanup: signalled pid ${status.pid} (best-effort) and removed the pidfile` };
+  }
   if (!status.running) {
     // Stale pidfile — clean it up, report clearly (no silent failure).
     try { io.unlinkSync(pidFile); } catch { /* best-effort */ }
@@ -169,7 +327,16 @@ export function stopDaemon(io = defaultIO()) {
   try {
     io.kill(status.pid, "SIGTERM");
   } catch (err) {
-    return { stopped: false, pid: status.pid, reason: "error", message: `failed to signal pid ${status.pid}: ${err instanceof Error ? err.message : String(err)}` };
+    // Keep the pidfile: deleting a record we could not act on risks orphaning a
+    // genuinely live daemon. The message names the recovery path instead.
+    return {
+      stopped: false,
+      pid: status.pid,
+      reason: "error",
+      message:
+        `failed to signal pid ${status.pid}: ${err instanceof Error ? err.message : String(err)}` +
+        ` — the pid may have been recycled by the OS; if you are sure no daemon is running: chorus daemon stop --force`,
+    };
   }
   try { io.unlinkSync(pidFile); } catch { /* best-effort */ }
   return { stopped: true, pid: status.pid, reason: "stopped", message: `stopped daemon (pid ${status.pid})` };

package/cli/daemon-rest-client.mjs

@@ -134,10 +134,12 @@ export function createDaemonRestClient(opts) {
     /**
      * POST /api/daemon/turn-advance — advance a wake's DaemonSessionTurn lifecycle. The
      * server resolves the turn by the session BUSINESS KEY (`sessionId`); the optional
-     * `entityType`/`entityUuid` stamp the weak executionUuid link. Requires the
+     * `entityType`/`entityUuid` stamp the weak executionUuid link. An `interrupted`
+     * status may carry `interruptedReason` (`user`/`crash`/`shutdown` — the server
+     * rejects `offline`, which is its own reconcile verdict). Requires the
      * connectionUuid (the server addresses the turn against a connection the agent owns).
      */
-    async turnAdvance({ sessionId, status, entityType, entityUuid }) {
+    async turnAdvance({ sessionId, status, entityType, entityUuid, interruptedReason }) {
       const connectionUuid = getConnectionUuid();
       if (!connectionUuid) {
         const error = `cannot advance turn for session ${sessionId} → ${status} — no connection uuid yet`;
@@ -150,6 +152,8 @@ export function createDaemonRestClient(opts) {
         status,
         // Only sent when BOTH are present, so the server never gets a partial linkage.
         ...(entityType && entityUuid ? { entityType, entityUuid } : {}),
+        // Only meaningful alongside status=interrupted; never sent otherwise.
+        ...(status === "interrupted" && interruptedReason ? { interruptedReason } : {}),
       };
       return post(
         "turn-advance",