chainlesschain 0.162.161 → 0.162.162

package/src/lib/plugin-runtime/manifest.js

@@ -27,6 +27,11 @@
 import fs from "fs";
 import path from "path";
 import semver from "semver";
+import {
+  normalizeCapabilities,
+  normalizeOptionsSchema,
+  auditDeclaredCapabilities,
+} from "./capabilities.js";
 
 export const _deps = {
   existsSync: fs.existsSync,
@@ -73,6 +78,14 @@ export function parsePluginManifest(root) {
     scope: null,
     metadata: {},
     components: emptyComponents(),
+    // Declarative security contract (P1): the plugin's declared capabilities
+    // (manifest.permissions) + typed config schema (manifest.optionsSchema),
+    // normalized by capabilities.js. `capabilitiesDeclared` distinguishes a
+    // plugin that declared a permissions block (subject to the declared-vs-
+    // actual audit) from a legacy one that declared nothing (unrestricted).
+    capabilities: normalizeCapabilities(null),
+    capabilitiesDeclared: false,
+    optionsSchema: {},
     errors,
     warnings,
   };
@@ -165,6 +178,23 @@ export function parsePluginManifest(root) {
   c.bin = resolveBin(abs, manifest, safeResolve, warnings);
   c.settings = resolveSettings(abs, manifest, safeResolve);
 
+  // ── declared capabilities + options schema (P1) ──
+  const hasPermissions =
+    manifest.permissions &&
+    typeof manifest.permissions === "object" &&
+    !Array.isArray(manifest.permissions);
+  result.capabilities = normalizeCapabilities(manifest.permissions);
+  result.capabilitiesDeclared = Boolean(hasPermissions);
+  result.optionsSchema = normalizeOptionsSchema(manifest.optionsSchema);
+  // Declared-vs-actual audit runs ONLY when a permissions block is present — a
+  // legacy plugin that declares nothing is unrestricted by design, so it never
+  // gets these warnings (keeps existing manifests warning-free).
+  if (hasPermissions) {
+    for (const f of auditDeclaredCapabilities(result)) {
+      warnings.push(`capability: ${f.reason}`);
+    }
+  }
+
   result.ok = errors.length === 0;
   return result;
 }

package/src/lib/remote-approval-bridge.js

@@ -23,6 +23,10 @@
 
 import { randomBytes } from "crypto";
 import { WsRpcClient } from "./ws-rpc-client.js";
+import {
+  approvalFingerprintOk,
+  operationFingerprint,
+} from "./operation-fingerprint.js";
 import {
   buildDirectPairingUri,
   pickLanAddress,
@@ -113,6 +117,15 @@ export class RemoteApprovalBridge {
     const requestId = message.event.requestId || message.event.approvalId;
     const pending = requestId ? this._pending.get(requestId) : null;
     if (!pending) return;
+    // Confused-deputy guard: a resolve that carries an operation fingerprint
+    // must match the operation this ask published. A mismatch (stale card /
+    // replayed / swapped body) is rejected — the ask stays pending and fails
+    // closed on timeout. Absent fingerprint = legacy device, accepted.
+    if (
+      !approvalFingerprintOk(pending.fingerprint, message.event.fingerprint)
+    ) {
+      return;
+    }
     this._pending.delete(requestId);
     clearTimeout(pending.timer);
     const answer = message.event.answer ?? message.event.approved;
@@ -150,6 +163,7 @@ export class RemoteApprovalBridge {
     onRequestId = null,
   } = {}) {
     const requestId = `ra-${process.pid}-${++this._counter}-${randomBytes(4).toString("hex")}`;
+    const fingerprint = operationFingerprint({ tool, action, detail });
     if (onRequestId) {
       try {
         onRequestId(requestId);
@@ -171,6 +185,7 @@ export class RemoteApprovalBridge {
       if (typeof timer.unref === "function") timer.unref();
       this._pending.set(requestId, {
         timer,
+        fingerprint,
         resolve: (decision) => {
           this._publish({
             type: "permission.resolved",
@@ -187,6 +202,7 @@ export class RemoteApprovalBridge {
         tool: tool || null,
         action,
         detail,
+        fingerprint,
         askedAt: this._now(),
       });
     });

package/src/lib/review-pipeline.js

@@ -0,0 +1,227 @@
+/**
+ * Multi-agent code-review pipeline core (P2 "多 Agent Code Review").
+ *
+ * `cc review` today is a single read-only agent pass. The gap upgrades it to:
+ *   1. multiple finders (correctness / security / performance / tests),
+ *   2. a verifier that independently reproduces each finding,
+ *   3. a deduper that merges duplicates and confidence-filters,
+ *   4. structured output (path / line / category / severity / failure_scenario /
+ *      evidence).
+ *
+ * This module is the PURE aggregation core — normalize, dedup+merge, apply
+ * verifier verdicts, confidence-filter, rank, and render the structured report.
+ * The fan-out of finder/verifier AGENTS is orchestration the command layer adds;
+ * everything here is deterministic and testable without an LLM.
+ */
+
+/** The finder dimensions a full review fans out across. */
+export const REVIEW_DIMENSIONS = Object.freeze([
+  "correctness",
+  "security",
+  "performance",
+  "tests",
+]);
+
+const SEVERITY_RANK = Object.freeze({
+  critical: 5,
+  high: 4,
+  medium: 3,
+  low: 2,
+  note: 1,
+});
+const SEVERITY_LABEL = Object.freeze({
+  5: "Critical",
+  4: "High",
+  3: "Medium",
+  2: "Low",
+  1: "Note",
+});
+
+/** Canonical severity label (unknown → "Note"). */
+export function normalizeSeverity(sev) {
+  const r = SEVERITY_RANK[String(sev || "").toLowerCase()] || 1;
+  return SEVERITY_LABEL[r];
+}
+export function severityRank(sev) {
+  return SEVERITY_RANK[String(sev || "").toLowerCase()] || 0;
+}
+
+/** Clamp a confidence to [0,1]; non-numeric → `dflt`. */
+export function clampConfidence(v, dflt = 0.5) {
+  const n = Number(v);
+  if (!Number.isFinite(n)) return dflt;
+  return Math.max(0, Math.min(1, n));
+}
+
+function confOf(f) {
+  const n = Number(f?.confidence);
+  return Number.isFinite(n) ? n : 0.5;
+}
+
+function normTitle(title) {
+  return String(title || "")
+    .toLowerCase()
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, 80);
+}
+
+/** Dedup identity: same file location + same issue (title). Category-agnostic so
+ *  two finders reporting one bug under different categories merge. */
+export function findingKey(f) {
+  return `${f?.path || ""}:${f?.line ?? ""}:${normTitle(f?.title)}`;
+}
+
+function unionField(group, keys) {
+  const out = [];
+  const seen = new Set();
+  for (const f of group) {
+    for (const key of keys) {
+      const v = f?.[key];
+      const list = Array.isArray(v) ? v : v != null ? [v] : [];
+      for (const item of list) {
+        const s = String(item);
+        if (s && !seen.has(s)) {
+          seen.add(s);
+          out.push(s);
+        }
+      }
+    }
+  }
+  return out;
+}
+
+function maxSeverityLabel(group) {
+  let best = 0;
+  for (const f of group) best = Math.max(best, severityRank(f.severity));
+  return SEVERITY_LABEL[best] || "Note";
+}
+
+/**
+ * Merge findings that describe the SAME issue at the SAME location. The
+ * representative keeps the highest severity + highest confidence; categories /
+ * dimensions / evidence are unioned WHEN PRESENT (so a plain
+ * `{path,line,severity,title}` finding round-trips unchanged — the wiring into
+ * `parseFindings` relies on this). Shape-preserving for inputs without those
+ * fields.
+ */
+export function dedupeFindings(findings) {
+  const groups = new Map();
+  const order = [];
+  for (const f of findings || []) {
+    if (!f) continue;
+    const key = findingKey(f);
+    if (!groups.has(key)) {
+      groups.set(key, []);
+      order.push(key);
+    }
+    groups.get(key).push(f);
+  }
+  return order.map((key) => {
+    const group = groups.get(key);
+    const winner = [...group].sort(
+      (a, b) =>
+        severityRank(b.severity) - severityRank(a.severity) ||
+        confOf(b) - confOf(a),
+    )[0];
+    const merged = { ...winner, severity: maxSeverityLabel(group) };
+    if (Number.isFinite(Number(winner.confidence))) {
+      merged.confidence = Math.max(...group.map(confOf));
+    }
+    const cats = unionField(group, ["category", "categories"]);
+    if (cats.length) merged.categories = cats;
+    const dims = unionField(group, ["dimension", "dimensions"]);
+    if (dims.length) merged.dimensions = dims;
+    if (group.length > 1) merged.mergedCount = group.length;
+    return merged;
+  });
+}
+
+/**
+ * Apply verifier verdicts. `verdicts` maps a findingKey → { verified, confidence?,
+ * note? }. A finding the verifier could NOT reproduce (`verified === false`) is
+ * DROPPED; a reproduced one is kept, its confidence updated and a `verified`
+ * flag set. Findings with no verdict pass through as unverified.
+ */
+export function applyVerdicts(findings, verdicts = {}) {
+  const map =
+    verdicts instanceof Map
+      ? verdicts
+      : new Map(Object.entries(verdicts || {}));
+  const out = [];
+  for (const f of findings || []) {
+    if (!f) continue;
+    const v = map.get(findingKey(f));
+    if (!v) {
+      out.push(f);
+      continue;
+    }
+    if (v.verified === false) continue; // refuted → drop
+    out.push({
+      ...f,
+      verified: true,
+      confidence:
+        v.confidence != null ? clampConfidence(v.confidence) : confOf(f),
+      ...(v.note ? { verifierNote: String(v.note) } : {}),
+    });
+  }
+  return out;
+}
+
+/** Keep findings whose confidence is at least `minConfidence`. */
+export function filterByConfidence(findings, { minConfidence = 0 } = {}) {
+  return (findings || []).filter((f) => f && confOf(f) >= minConfidence);
+}
+
+/** Sort by severity (desc) then confidence (desc) then path/line for stability. */
+export function rankFindings(findings) {
+  return [...(findings || [])].sort(
+    (a, b) =>
+      severityRank(b.severity) - severityRank(a.severity) ||
+      confOf(b) - confOf(a) ||
+      String(a.path || "").localeCompare(String(b.path || "")) ||
+      (Number(a.line) || 0) - (Number(b.line) || 0),
+  );
+}
+
+function toOutputFinding(f) {
+  return {
+    path: String(f.path || ""),
+    line: Number.isFinite(Number(f.line)) ? Math.floor(Number(f.line)) : null,
+    category: f.category || (f.categories && f.categories[0]) || "correctness",
+    severity: normalizeSeverity(f.severity),
+    failure_scenario: String(f.failureScenario || f.failure_scenario || ""),
+    evidence: String(f.evidence || ""),
+    confidence: clampConfidence(f.confidence),
+  };
+}
+
+/**
+ * The full pipeline: dedup → apply verdicts → confidence-filter → rank → render
+ * the structured report (the gap's path/line/category/severity/failure_scenario/
+ * evidence output) plus severity/category rollups.
+ *
+ * @param {Array} rawFindings   findings from all finders
+ * @param {object} [opts]       { verdicts, minConfidence }
+ */
+export function buildReviewReport(
+  rawFindings,
+  { verdicts = {}, minConfidence = 0 } = {},
+) {
+  const deduped = dedupeFindings(rawFindings);
+  const verified = applyVerdicts(deduped, verdicts);
+  const filtered = filterByConfidence(verified, { minConfidence });
+  const ranked = rankFindings(filtered);
+  const findings = ranked.map(toOutputFinding);
+
+  const bySeverity = { Critical: 0, High: 0, Medium: 0, Low: 0, Note: 0 };
+  const byCategory = {};
+  for (const f of findings) {
+    bySeverity[f.severity] = (bySeverity[f.severity] || 0) + 1;
+    byCategory[f.category] = (byCategory[f.category] || 0) + 1;
+  }
+  return {
+    findings,
+    summary: { total: findings.length, bySeverity, byCategory },
+  };
+}

package/src/lib/runtime-checkup.js

@@ -0,0 +1,318 @@
+/**
+ * Runtime Checkup evaluators for `cc doctor` (P2 "Doctor").
+ *
+ * `cc doctor` today checks install/config/service health. The gap upgrades it to
+ * a RUNTIME checkup over live state: stale sessions/worktrees/agenda, orphaned
+ * background processes, slow or circuit-broken hooks, dead plugins/LSP servers,
+ * and verbose / code-derivable instruction files.
+ *
+ * This is the PURE evaluation core. The command layer collects a runtime
+ * SNAPSHOT (from session store, worktree list, agenda store, process table,
+ * hook/plugin stats) and a `now`, and this returns categorized findings. No I/O,
+ * no clock, no process access here → deterministic + unit-testable.
+ */
+
+const DAY = 24 * 60 * 60 * 1000;
+
+export const CHECKUP_SEVERITY = Object.freeze({
+  info: 1,
+  warn: 2,
+  error: 3,
+});
+
+function sev(level) {
+  return CHECKUP_SEVERITY[level] || CHECKUP_SEVERITY.info;
+}
+
+/** Default thresholds; every one is overridable per-call. */
+export const DEFAULT_CHECKUP_THRESHOLDS = Object.freeze({
+  staleSessionMs: 30 * DAY,
+  staleWorktreeMs: 7 * DAY,
+  agendaMissedGraceMs: 60 * 60 * 1000, // due but never fired for >1h → missed
+  agendaFiredRetireMs: 30 * DAY, // long-fired entry left lying around
+  slowHookMs: 5000,
+  hookFailureThreshold: 3,
+  instructionsMaxBytes: 12 * 1024,
+  instructionsDerivableRatio: 0.6, // ≥60% derivable from code → prune candidate
+});
+
+function finding(id, category, level, message, remediation, extra = {}) {
+  return {
+    id,
+    category,
+    severity: level,
+    severityRank: sev(level),
+    message,
+    remediation,
+    ...extra,
+  };
+}
+
+/** Sessions untouched past the stale threshold. */
+export function checkStaleSessions(sessions = [], now, t) {
+  const out = [];
+  for (const s of sessions) {
+    const last = Number(s?.lastActiveAt);
+    if (!Number.isFinite(last)) continue;
+    const age = now - last;
+    if (age > t.staleSessionMs) {
+      out.push(
+        finding(
+          "stale-session",
+          "sessions",
+          "warn",
+          `Session ${s.id} idle ${Math.floor(age / DAY)}d`,
+          "cc session prune",
+          { ref: s.id, ageMs: age },
+        ),
+      );
+    }
+  }
+  return out;
+}
+
+/** Worktrees that are merged, or simply old and untouched. */
+export function checkStaleWorktrees(worktrees = [], now, t) {
+  const out = [];
+  for (const w of worktrees) {
+    const created = Number(w?.createdAt);
+    if (!Number.isFinite(created)) continue;
+    const age = now - created;
+    if (w?.merged) {
+      out.push(
+        finding(
+          "merged-worktree",
+          "worktrees",
+          "warn",
+          `Worktree ${w.path} is merged and can be removed`,
+          "cc team worktree rm / git worktree remove",
+          { ref: w.path, merged: true },
+        ),
+      );
+    } else if (age > t.staleWorktreeMs) {
+      out.push(
+        finding(
+          "stale-worktree",
+          "worktrees",
+          "info",
+          `Worktree ${w.path} unused ${Math.floor(age / DAY)}d`,
+          "review and remove if abandoned",
+          { ref: w.path, ageMs: age },
+        ),
+      );
+    }
+  }
+  return out;
+}
+
+/** Agenda entries that missed their fire window, or long-fired leftovers. */
+export function checkAgenda(agenda = [], now, t) {
+  const out = [];
+  for (const a of agenda) {
+    const dueAt = Number(a?.dueAt);
+    const firedAt = Number(a?.firedAt);
+    if (Number.isFinite(dueAt) && !Number.isFinite(firedAt)) {
+      if (now - dueAt > t.agendaMissedGraceMs) {
+        out.push(
+          finding(
+            "agenda-missed",
+            "agenda",
+            "error",
+            `Agenda ${a.id} was due but never fired`,
+            "cc agenda list / re-arm or remove",
+            { ref: a.id, dueAt },
+          ),
+        );
+      }
+    } else if (
+      Number.isFinite(firedAt) &&
+      now - firedAt > t.agendaFiredRetireMs &&
+      !a?.recurring
+    ) {
+      out.push(
+        finding(
+          "agenda-retire",
+          "agenda",
+          "info",
+          `Agenda ${a.id} fired ${Math.floor((now - firedAt) / DAY)}d ago and can be retired`,
+          "cc agenda prune",
+          { ref: a.id, firedAt },
+        ),
+      );
+    }
+  }
+  return out;
+}
+
+/**
+ * Background processes whose recorded parent is gone (orphans), or that outlived
+ * the session that spawned them.
+ */
+export function checkOrphanProcesses(processes = [], activeSessionIds = []) {
+  const active = new Set(activeSessionIds.map(String));
+  const out = [];
+  for (const p of processes) {
+    if (!p?.alive) continue;
+    const parentDead = p.parentAlive === false;
+    const sessionGone = p.sessionId != null && !active.has(String(p.sessionId));
+    if (parentDead || sessionGone) {
+      out.push(
+        finding(
+          "orphan-process",
+          "processes",
+          "error",
+          `Background process pid=${p.pid}${p.kind ? ` (${p.kind})` : ""} orphaned`,
+          "terminate stray process; check background-shell cleanup",
+          { ref: p.pid, reason: parentDead ? "parent-dead" : "session-gone" },
+        ),
+      );
+    }
+  }
+  return out;
+}
+
+/** Hooks that run slow or have tripped their circuit breaker. */
+export function checkHooks(hooks = [], t) {
+  const out = [];
+  for (const h of hooks) {
+    if (h?.circuitOpen) {
+      out.push(
+        finding(
+          "hook-circuit-open",
+          "hooks",
+          "error",
+          `Hook ${h.id} circuit is open after ${h.failures ?? "?"} failures`,
+          "fix the hook or disable it in settings",
+          { ref: h.id, failures: h.failures },
+        ),
+      );
+      continue;
+    }
+    if (Number(h?.failures) >= t.hookFailureThreshold) {
+      out.push(
+        finding(
+          "hook-failing",
+          "hooks",
+          "warn",
+          `Hook ${h.id} failed ${h.failures} times`,
+          "inspect hook logs",
+          { ref: h.id, failures: h.failures },
+        ),
+      );
+    }
+    if (Number(h?.avgMs) > t.slowHookMs) {
+      out.push(
+        finding(
+          "hook-slow",
+          "hooks",
+          "warn",
+          `Hook ${h.id} averages ${Math.round(h.avgMs)}ms`,
+          "make the hook async or faster",
+          { ref: h.id, avgMs: h.avgMs },
+        ),
+      );
+    }
+  }
+  return out;
+}
+
+/** Plugins / LSP servers reported unhealthy or dead. */
+export function checkPluginsAndLsp(plugins = []) {
+  const out = [];
+  for (const p of plugins) {
+    if (p?.healthy === false) {
+      const isLsp = p.kind === "lsp" || p.lsp === true;
+      out.push(
+        finding(
+          isLsp ? "lsp-dead" : "plugin-dead",
+          isLsp ? "lsp" : "plugins",
+          "warn",
+          `${isLsp ? "LSP server" : "Plugin"} ${p.id} is unavailable`,
+          isLsp ? "cc code-intel / restart server" : "cc plugin validate",
+          { ref: p.id },
+        ),
+      );
+    }
+  }
+  return out;
+}
+
+/** Instruction files (cc.md / AGENTS.md) that are oversized or code-derivable. */
+export function checkInstructionFiles(files = [], t) {
+  const out = [];
+  for (const f of files) {
+    const bytes = Number(f?.bytes);
+    if (Number.isFinite(bytes) && bytes > t.instructionsMaxBytes) {
+      out.push(
+        finding(
+          "instructions-verbose",
+          "instructions",
+          "info",
+          `${f.path} is ${(bytes / 1024).toFixed(1)}KB — consider trimming`,
+          "move detail into referenced docs",
+          { ref: f.path, bytes },
+        ),
+      );
+    }
+    const ratio = Number(f?.derivableRatio);
+    if (Number.isFinite(ratio) && ratio >= t.instructionsDerivableRatio) {
+      out.push(
+        finding(
+          "instructions-derivable",
+          "instructions",
+          "info",
+          `${f.path} is ~${Math.round(ratio * 100)}% derivable from code`,
+          "delete code-derivable prose; keep only non-obvious guidance",
+          { ref: f.path, derivableRatio: ratio },
+        ),
+      );
+    }
+  }
+  return out;
+}
+
+/**
+ * Run every checkup against a runtime snapshot. Returns findings sorted most
+ * severe first, plus a rollup. Any missing snapshot section is simply skipped —
+ * partial snapshots produce partial (never crashing) results.
+ *
+ * @param {object} snapshot { sessions, worktrees, agenda, processes,
+ *   activeSessionIds, hooks, plugins, instructionFiles, now }
+ * @param {object} [opts] { thresholds }
+ */
+export function runRuntimeCheckup(snapshot = {}, { thresholds = {} } = {}) {
+  const t = { ...DEFAULT_CHECKUP_THRESHOLDS, ...thresholds };
+  const now = Number.isFinite(Number(snapshot.now))
+    ? Number(snapshot.now)
+    : null;
+  const findings = [];
+  if (now != null) {
+    findings.push(...checkStaleSessions(snapshot.sessions, now, t));
+    findings.push(...checkStaleWorktrees(snapshot.worktrees, now, t));
+    findings.push(...checkAgenda(snapshot.agenda, now, t));
+  }
+  findings.push(
+    ...checkOrphanProcesses(snapshot.processes, snapshot.activeSessionIds),
+  );
+  findings.push(...checkHooks(snapshot.hooks, t));
+  findings.push(...checkPluginsAndLsp(snapshot.plugins));
+  findings.push(...checkInstructionFiles(snapshot.instructionFiles, t));
+
+  findings.sort(
+    (a, b) =>
+      b.severityRank - a.severityRank ||
+      String(a.category).localeCompare(String(b.category)),
+  );
+
+  const byCategory = {};
+  const bySeverity = { error: 0, warn: 0, info: 0 };
+  for (const f of findings) {
+    byCategory[f.category] = (byCategory[f.category] || 0) + 1;
+    bySeverity[f.severity] = (bySeverity[f.severity] || 0) + 1;
+  }
+  return {
+    findings,
+    summary: { total: findings.length, byCategory, bySeverity },
+    ok: bySeverity.error === 0,
+  };
+}