chainlesschain 0.162.165 → 0.162.167

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

package/src/lib/governance-coverage.js

@@ -0,0 +1,179 @@
+/**
+ * Governance coverage metrics — the last open item of P1-9 ("覆盖率指标") in
+ * docs/CLAUDE_CODE_IDE_INCREMENTAL_GAP_ANALYSIS_2026-07-13.md, and the
+ * computation behind two §11.3 acceptance targets:
+ *
+ *   - "高风险 Tool Call Ledger/Trace 覆盖率：100%"
+ *       every high-risk (irreversible side-effecting) tool call MUST have a
+ *       side-effect-ledger entry AND a trace span.
+ *   - "Plugin/MCP/Skill/Hook 来源、版本、权限可追溯率：100%"
+ *       every externally-sourced tool/skill call MUST carry full provenance
+ *       (source + version + scope + a recorded permission decision).
+ *
+ * "High-risk" is NOT re-defined here — it is exactly what [[side-effect-ledger.js]]
+ * `classifyToolSideEffect` records (the ONE source), so this metric can't drift
+ * from what the ledger actually tracks. Provenance rows are the attribution
+ * records [[agent-tool-admission.js]] `buildToolAttribution` produces.
+ *
+ * PURE + deterministic: no fs / process / clock / RNG. The caller gathers a run's
+ * tool calls, the op-ids that got a ledger entry, the op-ids that got a trace
+ * span, and the attribution records; this reads back coverage ratios + the exact
+ * uncovered items so a gap is actionable, not just a number.
+ */
+
+import { classifyToolSideEffect } from "./side-effect-ledger.js";
+
+/** Coverage ratio in [0,1]; an empty population is vacuously fully covered. */
+function ratio(covered, total) {
+  return total === 0 ? 1 : covered / total;
+}
+
+/** Whether a tool call is high-risk (records an irreversible side effect). */
+export function isHighRiskToolCall(call) {
+  return classifyToolSideEffect(call?.tool, call?.args || {}) != null;
+}
+
+/**
+ * High-risk tool-call ledger + trace coverage (§11.3 metric).
+ *
+ * @param {object} params
+ * @param {Array<{tool:string, args?:object, opId?:string}>} params.toolCalls
+ *   every tool call the run issued (only high-risk ones enter the denominator)
+ * @param {Iterable<string>} [params.ledgerOpIds]  op-ids that got a ledger entry
+ * @param {Iterable<string>} [params.tracedOpIds]  op-ids that got a trace span
+ * @returns {{highRiskCount:number, ledgerCovered:number, traceCovered:number,
+ *            ledgerCoverage:number, traceCoverage:number,
+ *            uncoveredLedger:object[], uncoveredTrace:object[], ok:boolean}}
+ */
+export function computeSideEffectCoverage({
+  toolCalls = [],
+  ledgerOpIds = [],
+  tracedOpIds = [],
+} = {}) {
+  const ledgerSet = new Set([...ledgerOpIds].map(String));
+  const traceSet = new Set([...tracedOpIds].map(String));
+
+  const highRisk = [];
+  (Array.isArray(toolCalls) ? toolCalls : []).forEach((call, index) => {
+    const cls = classifyToolSideEffect(call?.tool, call?.args || {});
+    if (!cls) return; // not high-risk — excluded from the denominator
+    const opId = call?.opId == null ? null : String(call.opId);
+    highRisk.push({
+      index,
+      tool: String(call?.tool || ""),
+      kind: cls.kind,
+      opId,
+      ledger: opId != null && ledgerSet.has(opId),
+      traced: opId != null && traceSet.has(opId),
+    });
+  });
+
+  const total = highRisk.length;
+  const ledgerCovered = highRisk.filter((h) => h.ledger).length;
+  const traceCovered = highRisk.filter((h) => h.traced).length;
+  const pick = (h) => ({
+    index: h.index,
+    tool: h.tool,
+    kind: h.kind,
+    opId: h.opId,
+  });
+
+  return {
+    highRiskCount: total,
+    ledgerCovered,
+    traceCovered,
+    ledgerCoverage: ratio(ledgerCovered, total),
+    traceCoverage: ratio(traceCovered, total),
+    uncoveredLedger: highRisk.filter((h) => !h.ledger).map(pick),
+    uncoveredTrace: highRisk.filter((h) => !h.traced).map(pick),
+    ok: total === 0 ? true : ledgerCovered === total && traceCovered === total,
+  };
+}
+
+/** An attribution is in the provenance denominator if it's externally sourced. */
+function inProvenanceScope(attr) {
+  return Boolean(attr?.source) || String(attr?.tier || "") === "extension";
+}
+
+/**
+ * Plugin/MCP/Skill/Hook provenance traceability coverage (§11.3 metric). Only
+ * externally-sourced (or extension-tier) calls enter the denominator; a built-in
+ * mvp tool with no source is not part of this metric. An in-scope row is
+ * traceable only when source + version + scope are all present AND a permission
+ * decision was recorded (`admitted` is not null).
+ *
+ * @param {Array<object>} attributions  buildToolAttribution() records
+ * @returns {{total:number, traceable:number, coverage:number,
+ *            untraceable:Array<{index:number, tool:(string|null), missing:string[]}>,
+ *            ok:boolean}}
+ */
+export function computeProvenanceCoverage(attributions = []) {
+  const rows = [];
+  (Array.isArray(attributions) ? attributions : []).forEach((attr, index) => {
+    if (!inProvenanceScope(attr)) return;
+    const missing = [];
+    if (!attr?.source) missing.push("source");
+    if (!attr?.version) missing.push("version");
+    if (!attr?.scope) missing.push("scope");
+    if (attr?.admitted == null) missing.push("permission");
+    rows.push({
+      index,
+      tool: attr?.tool ?? null,
+      traceable: missing.length === 0,
+      missing,
+    });
+  });
+
+  const total = rows.length;
+  const traceable = rows.filter((r) => r.traceable).length;
+  return {
+    total,
+    traceable,
+    coverage: ratio(traceable, total),
+    untraceable: rows.filter((r) => !r.traceable),
+    ok: total === 0 ? true : traceable === total,
+  };
+}
+
+/** Format a ratio in [0,1] as a whole-or-1-decimal percentage string. */
+function pct(r) {
+  const v = r * 100;
+  return (Number.isInteger(v) ? v.toFixed(0) : v.toFixed(1)) + "%";
+}
+
+/**
+ * Combine both metrics into one report + a fail-closed `ok` (both must be 100%).
+ *
+ * @param {object} params
+ * @param {Array} [params.toolCalls]
+ * @param {Iterable<string>} [params.ledgerOpIds]
+ * @param {Iterable<string>} [params.tracedOpIds]
+ * @param {Array} [params.attributions]
+ * @returns {{sideEffect:object, provenance:object, ok:boolean}}
+ */
+export function computeGovernanceCoverage({
+  toolCalls = [],
+  ledgerOpIds = [],
+  tracedOpIds = [],
+  attributions = [],
+} = {}) {
+  const sideEffect = computeSideEffectCoverage({
+    toolCalls,
+    ledgerOpIds,
+    tracedOpIds,
+  });
+  const provenance = computeProvenanceCoverage(attributions);
+  return { sideEffect, provenance, ok: sideEffect.ok && provenance.ok };
+}
+
+/** One-line, token-free summary of a governance coverage report. */
+export function summarizeGovernanceCoverage(report) {
+  const se = report?.sideEffect || {};
+  const pr = report?.provenance || {};
+  return (
+    `high-risk ledger ${pct(se.ledgerCoverage ?? 1)} / trace ` +
+    `${pct(se.traceCoverage ?? 1)} (${se.highRiskCount ?? 0} calls) · ` +
+    `provenance ${pct(pr.coverage ?? 1)} (${pr.total ?? 0} sourced) · ` +
+    `${report?.ok ? "OK" : "GAPS"}`
+  );
+}