@chorus-aidlc/chorus 0.13.0 → 0.13.2

package/.next/standalone/public/skill/chorus/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus AI Agent collaboration platform — overview, common tools,
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.11.1"
+  version: "0.13.2"
   category: project-management
   mcp_server: chorus
 ---

package/.next/standalone/public/skill/code-reviewer-chorus/SKILL.md

@@ -4,7 +4,7 @@ description: Read-only adversarial Chorus code-review gateway — independently
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.11.1"
+  version: "0.13.2"
   category: project-management
   mcp_server: chorus
 ---

package/.next/standalone/public/skill/develop-chorus/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus Development workflow — claim tasks, report work, self-chec
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.11.1"
+  version: "0.13.2"
   category: project-management
   mcp_server: chorus
 ---
@@ -269,4 +269,6 @@ chorus_add_comment({ targetType: "task", targetUuid: "<task-uuid>", content: "Re
 ## Next
 
 - After submitting for verification, an Admin reviews using the `review-chorus` skill (`<BASE_URL>/skill/review-chorus/SKILL.md`)
+- **Human "Start Development" wake:** a `start_development` wake (the human clicked **Start Development** on the idea-detail panel) means: claim and execute ALL remaining tasks of the idea's approved proposal in dependency order — loop this workflow until no claimable task remains, leaving `to_verify` and other-session tasks untouched.
+- **Human "Yolo" wake:** a `yolo_requested` wake (the human clicked **Yolo** on the idea-detail panel) means: drive the WHOLE idea to done via the yolo skill (the full-auto AI-DLC pipeline), not just the execute stage — read the idea's current state and resume from whatever phase it is in. Unlike `start_development` it is stage-adaptive, and it must never merge or push a PR without explicit human approval.
 - For platform overview and shared tools, see `chorus` skill (`<BASE_URL>/skill/chorus/SKILL.md`)

package/.next/standalone/public/skill/idea-chorus/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus Idea workflow — claim ideas, run elaboration rounds, and p
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.11.1"
+  version: "0.13.2"
   category: project-management
   mcp_server: chorus
 ---
@@ -283,6 +283,14 @@ When a new direction surfaces (during elaboration, brainstorm, or review), decid
 
 This is a soft heuristic, not a rule — use judgment. Cycle prevention is automatic: you cannot set a parent that is the idea itself or one of its descendants. Parent and child must be in the same project (cross-project lineage is not supported yet). Deleting a parent re-parents its children to top-level (it never cascades).
 
+### Theme ideas
+
+A **theme** is an idea that only *groups* related children under a shared direction — it is not a deliverable itself. Set `isContainer: true` on `chorus_pm_create_idea` / `chorus_edit_idea` (or the detail-panel toggle) to make one; it is freely reversible. The one rule that matters: **a theme cannot create a proposal** — to deliver its direction, derive a child idea (`parentUuid = <theme>`) and write the proposal on the child. A theme may still elaborate (its elaboration is shared context for children), and its status/progress rolls up from its children. Everything else is self-documented on the tool params.
+
+#### Theme decompose (daemon-assisted)
+
+When a theme is created via the conversational "help me break this into child ideas" entry, don't create children immediately — **propose then create**: (1) edit the theme + optionally one short scope-elaboration round; (2) propose the candidate children as an elaboration round (`chorus_pm_start_elaboration`), one single-select question per candidate, for the user to accept/decline in the panel; (3) on the answer re-wake, create each accepted child with `chorus_pm_create_idea` (`parentUuid = <theme>`, left in `open`).
+
 ---
 
 ## Tips
@@ -299,4 +307,6 @@ This is a soft heuristic, not a rule — use judgment. Cycle prevention is autom
 
 - Once elaboration is resolved, use the `proposal-chorus` skill (`<BASE_URL>/skill/proposal-chorus/SKILL.md`) to create a Proposal with document and task drafts
 - **Human "Verify Elaborate" handoff:** when a human clicks **Verify Elaborate** on the idea-detail panel, Chorus resolves the elaboration and wakes the Idea's assigned daemon agent to write the proposal — so the woken agent picks up this idea→proposal handoff automatically (no human-authored proposal needed).
+- **Human "Start Development" handoff:** once the proposal is approved and unfinished tasks remain, the idea-detail panel shows a **Start Development** button (enabled while the assignee agent is online). A `start_development` wake means: claim and execute ALL remaining tasks of the idea's approved proposal in dependency order until none are claimable — not just one task.
+- **Human "Yolo" handoff:** the idea-detail panel also shows a **Yolo** button at ANY incomplete stage (enabled while the assignee agent is online), confirmed via a dialog before it fires. A `yolo_requested` wake means: drive the WHOLE idea to done via the yolo skill (the full-auto AI-DLC pipeline) — read the idea's current state first and resume from whatever phase it is in (self-elaborate + write the proposal if not yet resolved; execute if a proposal is approved with open tasks; etc.), never assuming a fixed stage. Complete through done + the completion report, but never merge or push a PR without explicit human approval.
 - For platform overview and shared tools, see the `chorus` skill (`<BASE_URL>/skill/chorus/SKILL.md`)

package/.next/standalone/public/skill/proposal-chorus/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus Proposal workflow — create proposals with document and tas
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.11.1"
+  version: "0.13.2"
   category: project-management
   mcp_server: chorus
 ---
@@ -83,6 +83,8 @@ chorus_pm_create_proposal({
 
 **Multiple Ideas:** You can combine multiple ideas into one proposal by passing multiple UUIDs in `inputUuids`.
 
+> **A theme cannot be a proposal input** — `chorus_pm_create_proposal` rejects any input idea with `isContainer = true`. Derive a child idea from the theme and write the proposal on the child instead. (See the theme-ideas section of the `idea-chorus` skill.)
+
 ### Step 2: Add Document Drafts
 
 Add document drafts one at a time:

package/.next/standalone/public/skill/proposal-reviewer-chorus/SKILL.md

@@ -4,7 +4,7 @@ description: Read-only adversarial Chorus proposal reviewer — audits PRD/task
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.11.1"
+  version: "0.13.2"
   category: project-management
   mcp_server: chorus
 ---

package/.next/standalone/public/skill/quick-dev-chorus/SKILL.md

@@ -4,7 +4,7 @@ description: Quick Task workflow — skip Idea→Proposal, create tasks directly
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.11.1"
+  version: "0.13.2"
   category: project-management
   mcp_server: chorus
 ---

package/.next/standalone/public/skill/review-chorus/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus Review workflow — approve/reject proposals, verify tasks,
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.11.1"
+  version: "0.13.2"
   category: project-management
   mcp_server: chorus
 ---

package/.next/standalone/public/skill/task-reviewer-chorus/SKILL.md

@@ -4,7 +4,7 @@ description: Read-only adversarial Chorus task reviewer — independently verifi
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.11.1"
+  version: "0.13.2"
   category: project-management
   mcp_server: chorus
 ---

package/.next/standalone/public/skill/yolo-chorus/SKILL.md

@@ -4,7 +4,7 @@ description: Full-auto AI-DLC pipeline — drive a single prompt from Idea throu
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.11.1"
+  version: "0.13.2"
   category: project-management
   mcp_server: chorus
 ---

package/README.md

@@ -104,9 +104,12 @@ The `chorus daemon` connects your local machine to a remote Chorus server as an
 chorus login                     # Authenticate (opens browser)
 chorus daemon                    # Start daemon in foreground
 chorus daemon -d                 # Start daemon in background (detached)
-chorus daemon stop               # Stop background daemon
+chorus daemon install            # Install as a boot-autostart service (Linux) — recommended
+chorus daemon uninstall          # Remove the installed service
+chorus daemon stop               # Stop the daemon (delegates to systemd when installed)
+chorus daemon stop --force       # Force-clean the pidfile if a stuck pid blocks stop
 chorus daemon status             # Check daemon status
-chorus daemon restart            # Restart background daemon
+chorus daemon restart            # Restart the daemon
 chorus daemon logs               # View daemon logs
 ```
 
@@ -114,12 +117,22 @@ chorus daemon logs               # View daemon logs
 
 - **Claude Code & Codex backends** — Auto-detects the `claude` (or `codex`) CLI on your PATH; pick with `--agent codex`
 - **Background mode** — Run with `-d` flag; manage with `stop/restart/logs`
+- **Boot-autostart service** — `chorus daemon install` generates a correct `systemd --user` unit and starts it (see below); `status/stop/restart/logs` then transparently delegate to systemd
 - **Permission modes** — Default is full access (yolo); use `--chorus-only` to restrict to Chorus MCP tools only
 - **Multi-path** — Serve several working directories from one daemon with repeatable `--cwd` (see below)
 - **Interactive setup** — Prompts for credentials on first start if not already configured
 
 The daemon requires authentication. Run `chorus login` first, or it will prompt for credentials interactively on first start (if running in a terminal).
 
+#### Run at boot / login — `chorus daemon install`
+
+```bash
+chorus daemon install --cwd ~/work/repo-a --cwd ~/work/repo-b   # install + start now, autostart at login
+chorus daemon uninstall                                         # disable + remove the service
+```
+
+On Linux, `install` generates a `systemd --user` unit that runs the daemon in the **foreground** (`Type=simple`, no `-d`) so systemd owns the process directly, then `daemon-reload` + `enable --now`. It captures the `--cwd`/`--agent`/`--chorus-only` flags you pass. Do **not** hand-write a `Type=forking` unit around `chorus daemon -d` — the daemon self-daemonizes, which systemd can't track and which loops on restart; let `install` write the right unit. On macOS/Windows, `install` prints a correct template you install manually. Run `chorus login` first so the unit can see your credentials. See [docs/DAEMON.md](docs/DAEMON.md) for details.
+
 #### Serve multiple working directories
 
 One daemon can serve several local working directories at once — each declared path registers as an independent connection (its own session + wake loop) under the same agent. A path is **just** a directory the daemon serves; it carries no project binding.

package/README.zh.md

@@ -95,9 +95,12 @@ DATABASE_URL=postgresql://user:pass@host:5432/chorus chorus
 chorus login                     # 认证（打开浏览器）
 chorus daemon                    # 前台启动 daemon
 chorus daemon -d                 # 后台启动 daemon（分离模式）
-chorus daemon stop               # 停止后台 daemon
+chorus daemon install            # 安装为开机自启服务（Linux）—— 推荐
+chorus daemon uninstall          # 卸载已安装的服务
+chorus daemon stop               # 停止 daemon（已安装服务时委派给 systemd）
+chorus daemon stop --force       # pid 卡死时强制清理 pidfile
 chorus daemon status             # 查看 daemon 状态
-chorus daemon restart            # 重启后台 daemon
+chorus daemon restart            # 重启 daemon
 chorus daemon logs               # 查看 daemon 日志
 ```
 
@@ -105,12 +108,22 @@ chorus daemon logs               # 查看 daemon 日志
 
 - **Claude Code 与 Codex 后端** — 自动检测 PATH 中的 `claude`（或 `codex`）CLI；用 `--agent codex` 选择
 - **后台模式** — 使用 `-d` 标志后台运行；用 `stop/restart/logs` 管理
+- **开机自启服务** — `chorus daemon install` 生成正确的 `systemd --user` unit 并启动（见下文）；此后 `status/stop/restart/logs` 会自动委派给 systemd
 - **权限模式** — 默认完全访问（yolo）；使用 `--chorus-only` 限制为仅 Chorus MCP 工具
 - **多路径** — 用可重复的 `--cwd` 让单个 daemon 同时服务多个工作目录（见下文）
 - **交互式设置** — 首次启动时如未配置凭证会提示输入
 
 daemon 需要先认证。首次使用请先运行 `chorus login`，或者 daemon 会在首次启动时交互式提示输入凭证（如果在终端中运行）。
 
+#### 开机 / 登录时自启 —— `chorus daemon install`
+
+```bash
+chorus daemon install --cwd ~/work/repo-a --cwd ~/work/repo-b   # 立即安装并启动，登录时自启
+chorus daemon uninstall                                         # 停用并移除该服务
+```
+
+在 Linux 上，`install` 会生成一个 `systemd --user` unit，让 daemon 以**前台**方式运行（`Type=simple`，不带 `-d`），从而由 systemd 直接接管进程，然后 `daemon-reload` + `enable --now`。它会捕获你传入的 `--cwd`/`--agent`/`--chorus-only` 参数。**不要**手写 `Type=forking` + `chorus daemon -d` 的 unit —— daemon 会自我 daemon 化，systemd 追踪不到，重启时会陷入死循环；交给 `install` 写正确的 unit。在 macOS/Windows 上，`install` 会打印一份可手动安装的正确模板。请先运行 `chorus login`，让 unit 能读到凭证。详见 [docs/DAEMON.md](docs/DAEMON.md)。
+
 #### 服务多个工作目录
 
 一个 daemon 可以同时服务多个本地工作目录——每个声明的路径会注册为一条独立连接（各自拥有会话与唤起循环），归属同一个 Agent。路径**仅仅**是 daemon 服务的目录，不携带任何项目绑定。

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})` };