chainlesschain 0.162.166 → 0.162.168

package/src/lib/async-hook-queue.cjs

@@ -0,0 +1,288 @@
+"use strict";
+
+/**
+ * async-hook-queue — a small, best-effort, PERSISTENT queue for async settings
+ * hooks that opted into `asyncRewake: true` and finished in a FAILURE state.
+ *
+ * Why: AsyncHookSupervisor runs `async: true` hooks fire-and-forget and keeps
+ * their results ONLY in memory (`_results`/`_rewakes`). A rewake is the one
+ * actionable signal it produces — "a background check (e.g. `npm test`) failed,
+ * re-engage the agent with the error". If the process dies (crash, kill,
+ * hard exit) after the rewake was recorded but BEFORE the turn loop drained and
+ * surfaced it, that signal is silently lost: the next `--resume` of the same
+ * session has no idea a background check failed.
+ *
+ * This module gives the supervisor a durable place to park undrained rewakes,
+ * keyed by session id, so `--resume <id>` can recover them. The gap's P2 "Hooks"
+ * item calls for an "async hook 持久队列"; this is the reliability half of it
+ * (paired with the already-shipped `allowManagedHooksOnly`).
+ *
+ * Lifecycle (rewake-scoped on purpose — non-rewake results are informational and
+ * cheap to lose; rewakes are the failure signal worth surviving a crash):
+ *   record a rewake  → appendRewake()  (immediate write, survives even SIGKILL)
+ *   drain / surface  → removeRewakes() (consumed → no longer pending)
+ *   resume a session → takePending()   (load + clear that session's bucket)
+ *
+ * Design mirrors hook-stats-store.cjs: pure folds (no clock/RNG/fs inside), an
+ * injected fs for load/save, atomic tmp+rename writes, and per-session +
+ * per-session-count bounds so a runaway producer never grows the file without
+ * bound. Every path is best-effort — a corrupt/io-failed queue file must never
+ * block a hook or the agent.
+ */
+
+const os = require("node:os");
+const path = require("node:path");
+const fsDefault = require("node:fs");
+
+const CONFIG_DIR_NAME = ".chainlesschain";
+const MAX_RECORDS_PER_SESSION = 200; // drop oldest-recorded beyond this
+const MAX_SESSIONS = 100; // bound distinct session buckets
+const DEFAULT_STALE_MS = 7 * 24 * 60 * 60 * 1000; // prune buckets untouched >7d
+
+/** Default on-disk location (matches the ESM getHomeDir() layout). */
+function defaultAsyncHookQueuePath() {
+  return path.join(os.homedir(), CONFIG_DIR_NAME, "async-hook-queue.json");
+}
+
+/**
+ * Stable de-dupe key for one rewake record. Two records with the same
+ * (command, event, ts, ms, exitCode) are treated as the same pending item —
+ * enough to make removeRewakes() idempotent and appendRewake() not double-store
+ * a record that a caller replays. Pure, no hashing needed.
+ */
+function queueEntryKey(rec) {
+  if (!rec || typeof rec !== "object") return "";
+  return [
+    String(rec.command || ""),
+    String(rec.event || ""),
+    String(rec.ts ?? ""),
+    String(rec.ms ?? ""),
+    String(rec.exitCode ?? ""),
+  ].join("|");
+}
+
+/** Normalize a raw supervisor record into a compact stored rewake entry. */
+function normalizeRecord(rec) {
+  if (!rec || typeof rec !== "object") return null;
+  const command = String(rec.command || "").trim();
+  if (!command) return null;
+  return {
+    command,
+    event: rec.event ?? null,
+    exitCode: rec.exitCode ?? null,
+    error: rec.error ? String(rec.error) : null,
+    additionalContext: rec.additionalContext
+      ? String(rec.additionalContext)
+      : null,
+    blocked: !!rec.blocked,
+    ts: Number.isFinite(Number(rec.ts)) ? Number(rec.ts) : 0,
+    ms: Number.isFinite(Number(rec.ms)) ? Number(rec.ms) : 0,
+  };
+}
+
+/** Fresh empty queue. */
+function emptyQueue() {
+  return { sessions: {} };
+}
+
+/** Coerce an arbitrary parsed value into the queue shape. */
+function coerceQueue(parsed) {
+  if (
+    !parsed ||
+    typeof parsed !== "object" ||
+    typeof parsed.sessions !== "object" ||
+    !parsed.sessions
+  ) {
+    return emptyQueue();
+  }
+  return { sessions: parsed.sessions };
+}
+
+/**
+ * PURE fold: append `records` into `queue` under `sessionId` (mutates + returns
+ * `queue`). De-dupes by queueEntryKey, keeps the most-recent MAX_RECORDS_PER_
+ * SESSION, and stamps the bucket's `updatedAt` for stale pruning. `now` is
+ * supplied by the caller so the fold stays clock-free.
+ */
+function foldAppend(queue, sessionId, records, now) {
+  if (!queue || typeof queue !== "object") queue = emptyQueue();
+  if (!queue.sessions) queue.sessions = {};
+  const id = String(sessionId || "").trim();
+  if (!id) return queue;
+  const list = Array.isArray(records) ? records : [records];
+  const bucket = queue.sessions[id] || { records: [], updatedAt: 0 };
+  const seen = new Set(bucket.records.map(queueEntryKey));
+  for (const raw of list) {
+    const rec = normalizeRecord(raw);
+    if (!rec) continue;
+    const key = queueEntryKey(rec);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    bucket.records.push(rec);
+  }
+  // Never persist an empty bucket (all-invalid input, or nothing new for a
+  // session that had none) — it would just be dead weight in the file.
+  if (bucket.records.length === 0) return queue;
+  if (bucket.records.length > MAX_RECORDS_PER_SESSION) {
+    bucket.records = bucket.records.slice(
+      bucket.records.length - MAX_RECORDS_PER_SESSION,
+    );
+  }
+  bucket.updatedAt = Number.isFinite(Number(now))
+    ? Number(now)
+    : bucket.updatedAt;
+  queue.sessions[id] = bucket;
+  boundSessions(queue);
+  return queue;
+}
+
+/**
+ * PURE fold: remove `records` (by key) from `sessionId`'s bucket (mutates +
+ * returns `queue`). Empties → the bucket is deleted so the file self-cleans.
+ */
+function foldRemove(queue, sessionId, records) {
+  if (!queue || !queue.sessions) return queue || emptyQueue();
+  const id = String(sessionId || "").trim();
+  const bucket = queue.sessions[id];
+  if (!bucket) return queue;
+  const kill = new Set(
+    (Array.isArray(records) ? records : [records])
+      .map(normalizeRecord)
+      .filter(Boolean)
+      .map(queueEntryKey),
+  );
+  bucket.records = bucket.records.filter((r) => !kill.has(queueEntryKey(r)));
+  if (bucket.records.length === 0) delete queue.sessions[id];
+  return queue;
+}
+
+/** Keep only the MAX_SESSIONS most-recently-updated buckets. */
+function boundSessions(queue) {
+  if (!queue || !queue.sessions) return queue;
+  const ids = Object.keys(queue.sessions);
+  if (ids.length <= MAX_SESSIONS) return queue;
+  ids
+    .sort(
+      (a, b) =>
+        (queue.sessions[a].updatedAt || 0) - (queue.sessions[b].updatedAt || 0),
+    )
+    .slice(0, ids.length - MAX_SESSIONS)
+    .forEach((id) => delete queue.sessions[id]);
+  return queue;
+}
+
+/**
+ * PURE fold: drop buckets whose `updatedAt` is older than `now - staleMs`
+ * (mutates + returns `queue`). Guards the file against unbounded growth from
+ * sessions that were never resumed to drain their pending rewakes.
+ */
+function foldPruneStale(queue, now, staleMs = DEFAULT_STALE_MS) {
+  if (!queue || !queue.sessions) return queue || emptyQueue();
+  const cutoff = (Number.isFinite(Number(now)) ? Number(now) : 0) - staleMs;
+  for (const [id, bucket] of Object.entries(queue.sessions)) {
+    if (!bucket || (bucket.updatedAt || 0) < cutoff) delete queue.sessions[id];
+  }
+  return queue;
+}
+
+/** Best-effort read of the on-disk queue (→ empty on missing/corrupt). */
+function loadQueue(file = defaultAsyncHookQueuePath(), fs = fsDefault) {
+  try {
+    if (!fs.existsSync(file)) return emptyQueue();
+    return coerceQueue(JSON.parse(fs.readFileSync(file, "utf-8")));
+  } catch {
+    return emptyQueue();
+  }
+}
+
+/** Best-effort atomic write (tmp + rename). Never throws. */
+function saveQueue(queue, file = defaultAsyncHookQueuePath(), fs = fsDefault) {
+  try {
+    const dir = path.dirname(file);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    const tmp = `${file}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(queue), "utf-8");
+    fs.renameSync(tmp, file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Append one/more rewake records for `sessionId` and write back. Best-effort;
+ * returns true on a successful write. `now` defaults to Date.now() (the only
+ * non-pure entry point besides load/save).
+ */
+function appendRewake(
+  { sessionId, records, now } = {},
+  file = defaultAsyncHookQueuePath(),
+  fs = fsDefault,
+) {
+  const id = String(sessionId || "").trim();
+  if (!id || records == null) return false;
+  const at = Number.isFinite(Number(now)) ? Number(now) : Date.now();
+  const queue = foldAppend(loadQueue(file, fs), id, records, at);
+  return saveQueue(queue, file, fs);
+}
+
+/**
+ * Remove (mark consumed) rewake records for `sessionId` and write back.
+ * Best-effort; a no-op when nothing matches.
+ */
+function removeRewakes(
+  { sessionId, records } = {},
+  file = defaultAsyncHookQueuePath(),
+  fs = fsDefault,
+) {
+  const id = String(sessionId || "").trim();
+  if (!id || records == null) return false;
+  const queue = foldRemove(loadQueue(file, fs), id, records);
+  return saveQueue(queue, file, fs);
+}
+
+/**
+ * Load a session's pending rewakes AND clear its bucket (also prunes stale
+ * buckets while we hold the file). Returns the recovered records (possibly []).
+ * The single call a resuming runner makes on startup.
+ */
+function takePending(
+  { sessionId, now, staleMs } = {},
+  file = defaultAsyncHookQueuePath(),
+  fs = fsDefault,
+) {
+  const id = String(sessionId || "").trim();
+  if (!id) return [];
+  const at = Number.isFinite(Number(now)) ? Number(now) : Date.now();
+  let queue = loadQueue(file, fs);
+  const bucket = queue.sessions[id];
+  const recovered =
+    bucket && Array.isArray(bucket.records) ? bucket.records : [];
+  if (bucket) delete queue.sessions[id];
+  queue = foldPruneStale(queue, at, staleMs);
+  // Only rewrite if we actually changed something (recovered a bucket or the
+  // prune dropped one) — a pure read of an empty/unrelated queue leaves the
+  // file byte-unchanged.
+  if (recovered.length > 0 || bucket) saveQueue(queue, file, fs);
+  return recovered;
+}
+
+module.exports = {
+  defaultAsyncHookQueuePath,
+  queueEntryKey,
+  normalizeRecord,
+  emptyQueue,
+  coerceQueue,
+  foldAppend,
+  foldRemove,
+  foldPruneStale,
+  boundSessions,
+  loadQueue,
+  saveQueue,
+  appendRewake,
+  removeRewakes,
+  takePending,
+  MAX_RECORDS_PER_SESSION,
+  MAX_SESSIONS,
+  DEFAULT_STALE_MS,
+};

package/src/lib/async-hook-supervisor.cjs

@@ -73,6 +73,22 @@ class AsyncHookSupervisor {
         ? this._statsStore.defaultHookStatsPath()
         : null);
     this._statsFs = opts.statsFs || null; // injected fs for tests
+    // Persistent rewake queue (opt-in). A rewake — an async check that OPTED IN
+    // and finished in a FAILURE state — is the one actionable signal this
+    // supervisor produces, but it lives only in `_rewakes` until the turn loop
+    // drains it. If the process dies in that window the failure is lost. When a
+    // `sessionId` + `persistQueue` (or an explicit `queuePath`) are supplied,
+    // each rewake is durably parked keyed by session so `--resume` can recover
+    // it; it's removed again the moment the run drains it. Disabled (no writes,
+    // byte-unchanged) when either is absent — mirrors the stats-store opt-in.
+    this._queueStore = opts.queueStore || require("./async-hook-queue.cjs");
+    this._queueSessionId = opts.sessionId ? String(opts.sessionId) : null;
+    this._queuePath =
+      opts.queuePath ||
+      (opts.persistQueue === true
+        ? this._queueStore.defaultAsyncHookQueuePath()
+        : null);
+    this._queueFs = opts.queueFs || null; // injected fs for tests
     // The exit reaper is installed LAZILY (on first spawn), not in the ctor:
     // a supervisor that never dispatches a hook (or the many built in tests)
     // must not leave a permanent `process.once('exit')` listener behind —
@@ -359,6 +375,29 @@ class AsyncHookSupervisor {
     if (hook.asyncRewake && !rec.ok) {
       this._rewakes.push(rec);
       if (this._rewakes.length > RESULT_RING) this._rewakes.shift();
+      // Durably park it (opt-in) so a crash before the turn loop drains this
+      // rewake doesn't lose the failure signal. Immediate write, not deferred to
+      // stopAll — a rewake must survive even a hard exit that never runs stopAll.
+      this._persistRewake(rec);
+    }
+  }
+
+  /** True when a session id + queue location were both configured. */
+  _queueEnabled() {
+    return !!(this._queueSessionId && this._queuePath);
+  }
+
+  /** Best-effort durable append of one rewake record. Never throws. */
+  _persistRewake(rec) {
+    if (!this._queueEnabled()) return;
+    try {
+      this._queueStore.appendRewake(
+        { sessionId: this._queueSessionId, records: [rec], now: rec.ts },
+        this._queuePath,
+        this._queueFs || undefined,
+      );
+    } catch {
+      /* queue is best-effort */
     }
   }
 
@@ -377,6 +416,19 @@ class AsyncHookSupervisor {
   drainRewakes() {
     const r = this._rewakes;
     this._rewakes = [];
+    // The run has now consumed these rewakes (it will surface / re-engage on
+    // them), so they no longer need to survive a crash — drop the durable copies.
+    if (r.length > 0 && this._queueEnabled()) {
+      try {
+        this._queueStore.removeRewakes(
+          { sessionId: this._queueSessionId, records: r },
+          this._queuePath,
+          this._queueFs || undefined,
+        );
+      } catch {
+        /* queue is best-effort */
+      }
+    }
     return r;
   }
 

package/src/lib/background-phase-reporter.js

@@ -0,0 +1,116 @@
+/**
+ * background-phase-reporter — the missing PRODUCER for the background-agent
+ * `waiting_permission` phase (P0 state-machine slice,
+ * CLAUDE_CODE_CLI_INCREMENTAL_GAP_ANALYSIS_2026-07-12 §"后台 Agent 状态机").
+ *
+ * The consuming contract has existed for a while: `background-agent-phase.js`
+ * normalizes `waiting_permission` and `pendingApprovals > 0` into the
+ * dashboard's "Needs input" group, and `session-lifecycle.js` folds them into
+ * `waitingApproval`. But nothing ever WROTE those fields — the worker only
+ * emits `turn`/`idle`, so a background agent blocked on a human approval
+ * (`--permission-prompt-tool`, `--remote-control`) showed as "Working"
+ * indefinitely while a decision was actually pending.
+ *
+ * The production seam is the agent CHILD process, not the worker: the worker
+ * spawns each turn with `CC_BACKGROUND_AGENT_ID` in the environment, and the
+ * only places a plain headless run genuinely blocks on a human are the
+ * confirmer overrides installed on the ApprovalGate. This module wraps those
+ * confirmers: while one is awaiting a decision it patches the shared state
+ * file with `phase: "waiting_permission"` + a live `pendingApprovals` count,
+ * and restores `phase: "turn"` when every pending approval has settled.
+ *
+ * Safety properties:
+ *  - Disabled (no `CC_BACKGROUND_AGENT_ID`) → `wrapConfirmer` returns the
+ *    SAME function object; zero reads, zero writes, byte-identical behavior
+ *    for every non-background run.
+ *  - Never resurrects a terminal session: writes are skipped when the current
+ *    on-disk status is anything other than absent/"running" (mirrors the
+ *    worker's own writeHeartbeat guard).
+ *  - Best-effort throughout: a state-file hiccup must never break an approval.
+ *  - IO is injectable so tests never touch the real user data dir.
+ */
+
+import {
+  readBackgroundAgentState,
+  writeBackgroundAgentState,
+} from "./background-agent-supervisor.js";
+
+/**
+ * Create a phase reporter for the current process.
+ *
+ * @param {object} [opts]
+ * @param {string|null} [opts.agentId] background session id; defaults to
+ *   `process.env.CC_BACKGROUND_AGENT_ID`. Falsy → disabled no-op reporter.
+ * @param {(id:string)=>object|null} [opts.readState] injectable state reader
+ * @param {(state:object)=>void} [opts.writeState] injectable state writer
+ */
+export function createBackgroundPhaseReporter(opts = {}) {
+  const agentId =
+    opts.agentId !== undefined
+      ? opts.agentId
+      : process.env.CC_BACKGROUND_AGENT_ID;
+  const readState = opts.readState || readBackgroundAgentState;
+  const writeState = opts.writeState || writeBackgroundAgentState;
+  const enabled = typeof agentId === "string" && agentId.trim() !== "";
+  let pending = 0;
+
+  function patch(fields) {
+    if (!enabled) return false;
+    try {
+      const current = readState(agentId) || { id: agentId };
+      // Terminal states are owned by the worker/stopper — never write a
+      // "waiting" phase over a completed/failed/stopped record.
+      if (current.status && current.status !== "running") return false;
+      writeState({ ...current, id: agentId, ...fields });
+      return true;
+    } catch {
+      return false; // state persistence must never break the approval itself
+    }
+  }
+
+  return {
+    enabled,
+    /** Current in-process pending-approval count (for tests/introspection). */
+    pendingCount() {
+      return pending;
+    },
+    /** A human approval just started blocking progress. */
+    beginApproval() {
+      if (!enabled) return;
+      pending++;
+      patch({
+        phase: "waiting_permission",
+        pendingApprovals: pending,
+      });
+    },
+    /** A previously reported approval settled (approved, denied, or failed). */
+    endApproval() {
+      if (!enabled) return;
+      pending = Math.max(0, pending - 1);
+      if (pending === 0) {
+        // Back to a live turn — the worker owns the turn/idle transition, we
+        // only hand the phase back to its steady in-turn value.
+        patch({ phase: "turn", pendingApprovals: 0 });
+      } else {
+        patch({ pendingApprovals: pending });
+      }
+    },
+    /**
+     * Wrap a (potentially human-blocking) confirmer so the pending window is
+     * visible in the background state. Disabled → returns `confirmer`
+     * unchanged (same object identity, zero overhead).
+     */
+    wrapConfirmer(confirmer) {
+      if (!enabled || typeof confirmer !== "function") return confirmer;
+      const self = this;
+      return async function phaseReportingConfirmer(...args) {
+        self.beginApproval();
+        try {
+          return await confirmer(...args);
+        } finally {
+          self.endApproval();
+        }
+      };
+    },
+  };
+}

package/src/lib/doctor-checkup.js

@@ -26,6 +26,11 @@ import {
 import { execSync, spawnSync } from "node:child_process";
 import { join, basename } from "node:path";
 import { getHomeDir, getConfigPath } from "./paths.js";
+import {
+  languageIdForFile,
+  resolveServer,
+  describeServer,
+} from "./lsp/lsp-server-registry.js";
 import {
   checkAgenda,
   checkInstructionFiles,
@@ -33,6 +38,8 @@ import {
   checkHooks,
   checkSandbox,
   checkDuplicateSkills,
+  checkLspReadiness,
+  checkOrphanProcesses,
   DEFAULT_CHECKUP_THRESHOLDS,
 } from "./runtime-checkup.js";
 
@@ -604,16 +611,84 @@ async function worktreeSection(opts, deps) {
 
 // ── runtime checkup: agenda expiry + verbose instruction files ──────────────
 // Only the gaps the OTHER sections don't already cover. Stale sessions,
-// worktrees, orphan processes and lost background agents are handled by
-// transcriptSection / worktreeSection / backgroundSection — surfacing them here
-// too would double-report, so this section deliberately covers just the agenda
-// schedule store and the instruction files (cc.md / AGENTS.md / CLAUDE.md).
+// worktrees and lost background agents (worker STATUS) are handled by
+// transcriptSection / worktreeSection / backgroundSection — surfacing those
+// here too would double-report. This section covers the agenda schedule store,
+// instruction files (cc.md / AGENTS.md / CLAUDE.md), and — distinct from
+// backgroundSection's worker-status check — leaked agent CHILD subprocesses
+// (a per-turn agentPid still alive after its worker died), probed via a static
+// one-shot PID-liveness check and the shared checkOrphanProcesses evaluator.
 const SEVERITY_TO_LEVEL = {
   error: CHECK_LEVELS.ERR,
   warn: CHECK_LEVELS.WARN,
   info: CHECK_LEVELS.INFO,
 };
 
+// Heavy / generated directories a project-language scan must never descend into
+// (they'd dominate the budget and aren't the user's source).
+const LSP_SCAN_SKIP_DIRS = new Set([
+  "node_modules",
+  "dist",
+  "build",
+  "out",
+  "target",
+  "coverage",
+  "vendor",
+  "venv",
+  "__pycache__",
+]);
+
+/**
+ * Bounded shallow walk of a project root, counting source files per LSP
+ * languageId (via `languageIdForFile`). Deliberately capped by total entries
+ * visited AND depth so `cc doctor` stays fast on a huge monorepo; heavy build /
+ * vendor dirs and dot-dirs are skipped. fs access goes through injected `deps`
+ * (readdirSync/statSync) so it's unit-testable. Returns a Map languageId→count.
+ */
+function scanProjectLanguages(
+  root,
+  deps,
+  { maxEntries = 20000, maxDepth = 8 } = {},
+) {
+  const counts = new Map();
+  let visited = 0;
+  const stack = [{ dir: root, depth: 0 }];
+  while (stack.length && visited < maxEntries) {
+    const { dir, depth } = stack.pop();
+    let names;
+    try {
+      names = deps.readdirSync(dir);
+    } catch {
+      continue; // unreadable dir — skip, never crash the doctor
+    }
+    for (const name of names) {
+      if (visited >= maxEntries) break;
+      visited += 1;
+      const lang = languageIdForFile(name);
+      if (lang) {
+        counts.set(lang, (counts.get(lang) || 0) + 1);
+        continue;
+      }
+      // Not a source file — maybe a directory to descend (bounded). Skip heavy
+      // build/vendor trees and dot-dirs (rarely hold the user's own source).
+      if (
+        depth < maxDepth &&
+        !LSP_SCAN_SKIP_DIRS.has(name) &&
+        !String(name).startsWith(".")
+      ) {
+        let isDir = false;
+        try {
+          isDir = deps.statSync(join(dir, name)).isDirectory();
+        } catch {
+          isDir = false;
+        }
+        if (isDir) stack.push({ dir: join(dir, name), depth: depth + 1 });
+      }
+    }
+  }
+  return counts;
+}
+
 async function runtimeSection(opts, deps) {
   const checks = [];
   const now = deps.now();
@@ -789,6 +864,111 @@ async function runtimeSection(opts, deps) {
     checks.push(failedCheck("sandbox", "sandbox availability", err));
   }
 
+  // LSP readiness — languages the project actually contains but for which no
+  // language server is installed: the silent reason `code_intelligence` /
+  // `cc code-intel` degrades to plain text search. A STATIC install-gap check
+  // (no server is started); the project scan is bounded so it stays fast.
+  try {
+    const root = opts.cwd || process.cwd();
+    const langCounts = scanProjectLanguages(root, deps);
+    if (langCounts.size > 0) {
+      const languages = [];
+      for (const [languageId, fileCount] of langCounts) {
+        const resolved = resolveServer(languageId, root);
+        const desc = describeServer(languageId);
+        languages.push({
+          languageId,
+          fileCount,
+          available: !!resolved,
+          serverId: (resolved && resolved.id) || (desc && desc.id) || null,
+          exampleBin: desc && desc.bins ? desc.bins[0] : null,
+        });
+      }
+      for (const f of checkLspReadiness(languages)) {
+        checks.push(
+          check(
+            f.id,
+            `lsp ${f.ref}`,
+            SEVERITY_TO_LEVEL[f.severity] || CHECK_LEVELS.INFO,
+            `${f.message} — ${f.remediation}`,
+          ),
+        );
+      }
+    }
+  } catch (err) {
+    checks.push(failedCheck("lsp-readiness", "lsp server readiness", err));
+  }
+
+  // Orphaned agent subprocesses — a background worker died but its per-turn
+  // agent CHILD (the LLM/tool subprocess recorded as `agentPid`) is still
+  // alive: a leaked process nothing reaped. backgroundSection reports the
+  // worker's STATUS; this probes the actual child PID's liveness (static,
+  // one-shot, anchored on the process start time to defeat PID reuse) and
+  // feeds the shared checkOrphanProcesses evaluator. Only PIDs we recorded are
+  // probed → no false positives, no OS-wide process-table scan. Tests inject
+  // opts.backgroundProcesses / opts.activeSessionIds (mirrors
+  // opts.skillLayerEntries below).
+  try {
+    let processes = opts.backgroundProcesses;
+    let activeSessionIds = opts.activeSessionIds;
+    if (!processes) {
+      const bgMod = await import("./background-agent-supervisor.js");
+      const agents = bgMod.listBackgroundAgents({ all: true }) || [];
+      activeSessionIds = agents
+        .filter((a) => a.status === "running")
+        .map((a) => a.sessionId)
+        .filter(Boolean);
+      processes = [];
+      for (const a of agents) {
+        let state;
+        try {
+          state = bgMod.readBackgroundAgentState(a.id);
+        } catch {
+          continue; // unreadable/raced state file — skip
+        }
+        const agentPid = Number(state?.agentPid);
+        if (!Number.isInteger(agentPid) || agentPid <= 0) continue;
+        if (agentPid === Number(state?.pid)) continue; // that's the worker itself
+        // Alive AND still the same process we launched (not a reused PID).
+        const anchor = state.agentStartedAt || state.startedAt;
+        if (!bgMod.isSameProcess(agentPid, anchor)) continue; // dead → nothing to reap
+        const parentAlive = bgMod.isSameProcess(
+          Number(state.pid),
+          state.startedAt,
+        );
+        processes.push({
+          pid: agentPid,
+          alive: true,
+          parentAlive,
+          sessionId: state.sessionId || null,
+          kind: "agent-child",
+        });
+      }
+    }
+    for (const f of checkOrphanProcesses(processes, activeSessionIds || [])) {
+      const killCmd =
+        process.platform === "win32"
+          ? `taskkill /PID ${f.ref} /T /F`
+          : `kill ${f.ref}`;
+      checks.push(
+        check(
+          f.id,
+          `process pid=${f.ref}`,
+          SEVERITY_TO_LEVEL[f.severity] || CHECK_LEVELS.WARN,
+          `${f.message} — ${f.remediation}`,
+          {
+            id: `reap-orphan-${f.ref}`,
+            safe: false,
+            description: `terminate leaked agent subprocess pid=${f.ref}`,
+            command: killCmd,
+          },
+        ),
+      );
+    }
+  } catch (err) {
+    checks.push(failedCheck("orphan-process", "orphan agent processes", err));
+  }
+
   // Duplicate skills — an id defined in more than one layer silently shadows
   // (loadAll keeps only the winner), so a user's custom skill can override, or
   // be overridden by, another without any signal. opts.skillLayerEntries lets a