chainlesschain 0.162.158 → 0.162.160

package/src/lib/llm-config-defaults.js

@@ -38,24 +38,40 @@ export async function reconcileConfigLlmProvider(cfgLlm = {}) {
   if (!cfgLlm || !cfgLlm.provider || !cfgLlm.baseUrl) {
     return { llm: cfgLlm, changed: false };
   }
-  const { inferProviderFromBaseUrl, modelForeignToProvider } = await import(
-    "./runnable-provider.js"
-  );
+  const { inferProviderFromBaseUrl, modelForeignToProvider } =
+    await import("./runnable-provider.js");
   const inferred = inferProviderFromBaseUrl(cfgLlm.baseUrl);
   if (!inferred || inferred === cfgLlm.provider) {
     return { llm: cfgLlm, changed: false };
   }
   const corrected = { ...cfgLlm, provider: inferred };
   if (modelForeignToProvider(inferred, cfgLlm.model)) {
-    const { selectModelForTask, TaskType } = await import(
-      "./task-model-selector.js"
-    );
+    const { selectModelForTask, TaskType } =
+      await import("./task-model-selector.js");
     const def = selectModelForTask(inferred, TaskType.CHAT);
     if (def) corrected.model = def;
   }
   return { llm: corrected, changed: true };
 }
 
+import { resolveApiKeyFromHelper } from "./api-key-helper.js";
+
+/**
+ * Key backfill order: config llm.apiKey (plaintext, legacy) first, then
+ * llm.apiKeyHelper (external command → OS credential store). The helper only
+ * runs when no key is otherwise present, so configured setups never pay a
+ * subprocess spawn.
+ */
+function backfillApiKey(options, cfgLlm) {
+  if (options.apiKey) return;
+  if (cfgLlm.apiKey) {
+    options.apiKey = cfgLlm.apiKey;
+  } else if (cfgLlm.apiKeyHelper) {
+    const key = resolveApiKeyFromHelper(cfgLlm.apiKeyHelper);
+    if (key) options.apiKey = key;
+  }
+}
+
 export function applyConfigLlmDefaults(options = {}, cfgLlm = {}, opts = {}) {
   // The IDE chat panel pins --provider/--model (read from config) but DROPS
   // --base-url/--api-key. With an explicit --provider the block below bails, so
@@ -71,7 +87,7 @@ export function applyConfigLlmDefaults(options = {}, cfgLlm = {}, opts = {}) {
     options.provider === cfgLlm.provider
   ) {
     if (!options.baseUrl && cfgLlm.baseUrl) options.baseUrl = cfgLlm.baseUrl;
-    if (!options.apiKey && cfgLlm.apiKey) options.apiKey = cfgLlm.apiKey;
+    backfillApiKey(options, cfgLlm);
     if (!options.model && !opts.explicitModel && cfgLlm.model) {
       options.model = cfgLlm.model;
     }
@@ -85,6 +101,6 @@ export function applyConfigLlmDefaults(options = {}, cfgLlm = {}, opts = {}) {
     options.model = cfgLlm.model;
   }
   if (!options.baseUrl && cfgLlm.baseUrl) options.baseUrl = cfgLlm.baseUrl;
-  if (!options.apiKey && cfgLlm.apiKey) options.apiKey = cfgLlm.apiKey;
+  backfillApiKey(options, cfgLlm);
   return options;
 }

package/src/lib/lsp/lsp-server-registry.js

@@ -67,8 +67,12 @@ function tsServer() {
   };
 }
 
-// Registry of plugin-contributed servers, keyed by languageId. Wins over
-// builtins if a plugin explicitly overrides.
+// Registry of plugin-contributed servers, keyed by languageId → ordered list of
+// defs (registration order). Multiple plugins may contribute a server for the
+// same languageId/extension; they are tried in order and then fall through to
+// the builtin, so one plugin's server being uninstalled or failing to resolve
+// does NOT knock out code intelligence for that extension — the next candidate
+// (another plugin, or the builtin) still serves it.
 const pluginServers = new Map();
 // Plugin-contributed extension→languageId overrides, kept SEPARATE from the
 // builtin EXTENSION_LANGUAGE map so `_resetPluginServers` (used by
@@ -86,12 +90,18 @@ export function registerLanguageServer(def) {
   if (!def || !def.languageId || !def.command) {
     throw new Error("registerLanguageServer requires { languageId, command }");
   }
-  pluginServers.set(def.languageId, {
+  const entry = {
     id: def.id || def.command,
     bins: [def.command],
     argsFor: () => (Array.isArray(def.args) ? def.args : []),
     fromPlugin: true,
-  });
+  };
+  const existing = pluginServers.get(def.languageId) || [];
+  // De-dupe by server id so re-registering the same server (e.g. a reload)
+  // doesn't stack duplicates, but distinct plugins for one language coexist.
+  const list = existing.filter((e) => e.id !== entry.id);
+  list.push(entry);
+  pluginServers.set(def.languageId, list);
   if (Array.isArray(def.extensions)) {
     for (const ext of def.extensions) {
       pluginExtensions.set(
@@ -123,17 +133,22 @@ export function languageIdForFile(filePath) {
  * @returns {{ languageId, id, command, args } | null}
  */
 export function resolveServer(languageId, projectRoot) {
-  const def = pluginServers.get(languageId) || BUILTIN_SERVERS[languageId];
-  if (!def) return null;
-  for (const bin of def.bins) {
-    const command = resolveBin(bin, projectRoot);
-    if (command) {
-      return {
-        languageId,
-        id: def.id,
-        command,
-        args: def.argsFor(bin),
-      };
+  // Try plugin-contributed servers in registration order, then the builtin.
+  // The first candidate whose binary actually resolves wins; a plugin server
+  // that isn't installed falls through instead of shadowing the builtin.
+  const candidates = [...(pluginServers.get(languageId) || [])];
+  if (BUILTIN_SERVERS[languageId]) candidates.push(BUILTIN_SERVERS[languageId]);
+  for (const def of candidates) {
+    for (const bin of def.bins) {
+      const command = resolveBin(bin, projectRoot);
+      if (command) {
+        return {
+          languageId,
+          id: def.id,
+          command,
+          args: def.argsFor(bin),
+        };
+      }
     }
   }
   return null;
@@ -185,17 +200,29 @@ export function resolveBin(bin, projectRoot) {
 export function probeServers(projectRoot) {
   const seen = new Set();
   const out = [];
-  const all = { ...BUILTIN_SERVERS };
-  for (const [lid, def] of pluginServers) all[lid] = def;
-  for (const [languageId, def] of Object.entries(all)) {
+  // One (languageId, def) pair per candidate: every plugin server plus each
+  // builtin. Probing each independently means an unavailable plugin server is
+  // reported as its own row without hiding the builtin's availability.
+  const pairs = [];
+  for (const [languageId, defs] of pluginServers) {
+    for (const def of defs) pairs.push([languageId, def]);
+  }
+  for (const [languageId, def] of Object.entries(BUILTIN_SERVERS)) {
+    pairs.push([languageId, def]);
+  }
+  for (const [languageId, def] of pairs) {
     if (seen.has(def.id)) continue; // one row per server family
     seen.add(def.id);
-    const resolved = resolveServer(languageId, projectRoot);
+    let command = null;
+    for (const bin of def.bins) {
+      command = resolveBin(bin, projectRoot);
+      if (command) break;
+    }
     out.push({
       languageId,
       id: def.id,
-      available: Boolean(resolved),
-      command: resolved ? resolved.command : null,
+      available: Boolean(command),
+      command,
     });
   }
   return out;

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

@@ -0,0 +1,174 @@
+/**
+ * Plugin governance (gap-2026-07-11 P2#13): dependency version constraints and
+ * "is this plugin actually in use" classification.
+ *
+ * Two failure modes this addresses:
+ *   1. A plugin that needs another plugin (or a minimum host version) installs
+ *      fine and then misbehaves at runtime because the dependency is absent or
+ *      too old. `checkPluginDependencies` validates a manifest `dependencies`
+ *      map (name → semver range) against what's installed, before load.
+ *   2. An "unused plugin" reaper that only counts tool invocations wrongly
+ *      flags a plugin whose entire value is passive — an LSP server, an MCP
+ *      server, hooks, or monitors — because those never show up as an explicit
+ *      tool call. `isPluginInUse` treats passive contributions as usage.
+ *
+ * Pure functions only; semver is the sole dependency.
+ */
+
+import semver from "semver";
+
+/**
+ * Passive component kinds — a plugin contributing any of these is "in use"
+ * even with zero explicit tool/skill invocations, because they work in the
+ * background (a language server, MCP tools surfaced on demand, lifecycle hooks,
+ * background monitors).
+ */
+export const PASSIVE_COMPONENT_KINDS = Object.freeze([
+  "lsp",
+  "mcp",
+  "hooks",
+  "monitors",
+]);
+
+/**
+ * Parse a manifest's `dependencies` field into a normalized map. Accepts:
+ *   { "other-plugin": "^1.2.0", "host": ">=0.162.0" }
+ * A reserved key `host` (or `cc`) constrains the CLI version itself. Returns
+ * `{ deps, hostRange, errors }`; bad ranges are collected, not thrown. Pure.
+ */
+export function parsePluginDependencies(manifest) {
+  const errors = [];
+  const deps = {};
+  let hostRange = null;
+  const raw = manifest && manifest.dependencies;
+  if (raw == null) return { deps, hostRange, errors };
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    errors.push("dependencies must be an object of name → semver range");
+    return { deps, hostRange, errors };
+  }
+  for (const [name, range] of Object.entries(raw)) {
+    if (typeof range !== "string" || range.trim() === "") {
+      errors.push(`dependency "${name}": range must be a non-empty string`);
+      continue;
+    }
+    if (!semver.validRange(range)) {
+      errors.push(`dependency "${name}": invalid semver range "${range}"`);
+      continue;
+    }
+    if (name === "host" || name === "cc") {
+      hostRange = range;
+    } else {
+      deps[name] = range;
+    }
+  }
+  return { deps, hostRange, errors };
+}
+
+/**
+ * Check a plugin's declared dependencies against installed plugins + the host
+ * version. `installed` is a map of pluginName → version string. Returns
+ * `{ ok, missing, mismatched, hostMismatch }`. Pure.
+ *
+ * @param {object} manifest         the depending plugin's manifest
+ * @param {object} opts             { installed, hostVersion }
+ */
+export function checkPluginDependencies(
+  manifest,
+  { installed = {}, hostVersion = null } = {},
+) {
+  const { deps, hostRange } = parsePluginDependencies(manifest);
+  const missing = [];
+  const mismatched = [];
+  for (const [name, range] of Object.entries(deps)) {
+    const have = installed[name];
+    if (have == null) {
+      missing.push({ name, range });
+      continue;
+    }
+    const coerced = semver.valid(have) || semver.coerce(have)?.version;
+    if (
+      !coerced ||
+      !semver.satisfies(coerced, range, { includePrerelease: true })
+    ) {
+      mismatched.push({ name, range, have });
+    }
+  }
+  let hostMismatch = null;
+  if (hostRange && hostVersion) {
+    const hv = semver.valid(hostVersion) || semver.coerce(hostVersion)?.version;
+    if (!hv || !semver.satisfies(hv, hostRange, { includePrerelease: true })) {
+      hostMismatch = { range: hostRange, have: hostVersion };
+    }
+  }
+  return {
+    ok: missing.length === 0 && mismatched.length === 0 && !hostMismatch,
+    missing,
+    mismatched,
+    hostMismatch,
+  };
+}
+
+/** Human-readable one-liners for a dependency check result. Pure. */
+export function formatDependencyIssues(name, result) {
+  const lines = [];
+  for (const m of result.missing) {
+    lines.push(`${name}: missing dependency ${m.name}@${m.range}`);
+  }
+  for (const m of result.mismatched) {
+    lines.push(
+      `${name}: dependency ${m.name}@${m.range} not satisfied by installed ${m.have}`,
+    );
+  }
+  if (result.hostMismatch) {
+    lines.push(
+      `${name}: requires cc ${result.hostMismatch.range}, running ${result.hostMismatch.have}`,
+    );
+  }
+  return lines;
+}
+
+/**
+ * Whether a plugin should be considered "in use". A plugin is in use when it
+ * contributes any passive component (LSP/MCP/hooks/monitors) OR when one of its
+ * named skills/agents/tools appears in `invokedNames`. Pure.
+ *
+ * @param {object} plugin           parsed manifest with `.components` + `.name`
+ * @param {object} opts             { invokedNames?: Set|Array }
+ * @returns {{ inUse, reason }}
+ */
+export function isPluginInUse(plugin, { invokedNames = [] } = {}) {
+  const components = (plugin && plugin.components) || {};
+  for (const kind of PASSIVE_COMPONENT_KINDS) {
+    if (hasComponent(components[kind])) {
+      return { inUse: true, reason: `passive ${kind}` };
+    }
+  }
+  const invoked =
+    invokedNames instanceof Set ? invokedNames : new Set(invokedNames || []);
+  const contributed = [
+    ...componentNames(components.skills),
+    ...componentNames(components.agents),
+  ];
+  for (const n of contributed) {
+    if (invoked.has(n)) return { inUse: true, reason: `invoked ${n}` };
+  }
+  return { inUse: false, reason: "no passive component and never invoked" };
+}
+
+function hasComponent(c) {
+  if (!c) return false;
+  if (Array.isArray(c)) return c.length > 0;
+  if (typeof c === "object") {
+    if (typeof c.count === "number") return c.count > 0;
+    if (c.file) return true;
+    if (c.inline) return true;
+  }
+  return false;
+}
+
+function componentNames(c) {
+  if (!Array.isArray(c)) return [];
+  return c
+    .map((e) => (typeof e === "string" ? e : e && (e.name || e.id)))
+    .filter(Boolean);
+}

package/src/lib/pr-link-ledger.js

@@ -0,0 +1,221 @@
+/**
+ * PR / session linking (gap-2026-07-11 P1#9) — Claude-Code agent-view parity:
+ * remember which pull requests a session created, viewed, commented on,
+ * merged, or pushed to, so `cc session show` and the background-agent
+ * dashboard can display `#123 open` next to the session.
+ *
+ * Sources:
+ * - successful `gh pr create/view/merge/comment/checkout/…` tool commands —
+ *   their stdout carries the canonical https://github.com/o/r/pull/N URL;
+ * - `git push` — best-effort `gh pr list --head <branch>` lookup (async,
+ *   3s timeout, silently skipped when gh is unavailable).
+ *
+ * Ledger: ~/.chainlesschain/pr-links.json
+ *   { "<sessionId>": [{ number, repo, url, state, action, updatedAt }] }
+ * Everything here is best-effort — a ledger failure must never break a tool
+ * result or a session listing.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { execFile } from "node:child_process";
+import { join } from "node:path";
+import { getHomeDir } from "./paths.js";
+
+export const _deps = { execFile, now: () => Date.now() };
+
+const MAX_LINKS_PER_SESSION = 20;
+const MAX_SESSIONS = 500;
+
+export function prLinkLedgerPath() {
+  return join(getHomeDir(), "pr-links.json");
+}
+
+export function readPrLinkLedger() {
+  try {
+    const p = prLinkLedgerPath();
+    if (!existsSync(p)) return {};
+    const parsed = JSON.parse(readFileSync(p, "utf-8"));
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {}; // corrupt ledger degrades to empty, never throws
+  }
+}
+
+function writeLedger(ledger) {
+  const ids = Object.keys(ledger);
+  if (ids.length > MAX_SESSIONS) {
+    // Evict the oldest sessions by their newest link's updatedAt.
+    const newest = (id) =>
+      Math.max(0, ...(ledger[id] || []).map((l) => l.updatedAt || 0));
+    for (const id of ids
+      .sort((a, b) => newest(a) - newest(b))
+      .slice(0, ids.length - MAX_SESSIONS)) {
+      delete ledger[id];
+    }
+  }
+  writeFileSync(prLinkLedgerPath(), JSON.stringify(ledger, null, 2), "utf-8");
+}
+
+const PR_URL_RE = /https:\/\/github\.com\/([\w.-]+)\/([\w.-]+)\/pull\/(\d+)/g;
+const GH_PR_CMD_RE =
+  /^\s*gh\s+pr\s+(create|view|merge|comment|checkout|edit|ready|close|reopen|review)\b/;
+const GH_PR_NUMBER_RE =
+  /^\s*gh\s+pr\s+(?:view|merge|comment|checkout|edit|ready|close|reopen|review)\s+(?:--\S+\s+)*#?(\d+)\b/;
+
+/** True when the shell command is a `gh pr …` subcommand we track. */
+export function isGhPrCommand(command) {
+  return GH_PR_CMD_RE.test(String(command || ""));
+}
+
+/**
+ * Extract PR refs from a tracked `gh pr` command + its output. Pure.
+ * @returns {Array<{number:number, repo:string|null, url:string|null, action:string}>}
+ */
+export function parsePrRefs(command, output) {
+  const cmd = String(command || "");
+  const match = cmd.match(GH_PR_CMD_RE);
+  if (!match) return [];
+  const action = match[1];
+  const refs = new Map(); // repo#number → ref
+
+  for (const m of String(output || "").matchAll(PR_URL_RE)) {
+    const repo = `${m[1]}/${m[2]}`;
+    const number = Number(m[3]);
+    refs.set(`${repo}#${number}`, {
+      number,
+      repo,
+      url: m[0],
+      action,
+    });
+  }
+  // `gh pr merge 123` style — explicit number, repo unknown from text alone.
+  if (refs.size === 0) {
+    const numbered = cmd.match(GH_PR_NUMBER_RE);
+    if (numbered) {
+      const number = Number(numbered[1]);
+      refs.set(`?#${number}`, { number, repo: null, url: null, action });
+    }
+  }
+  return [...refs.values()];
+}
+
+const TERMINAL_ACTIONS = { merge: "merged", close: "closed", reopen: "open" };
+
+/** Merge one PR ref into a session's link list (dedupe by repo#number). */
+export function recordPrLink(sessionId, ref, options = {}) {
+  if (!sessionId || !ref || !Number.isFinite(Number(ref.number))) return null;
+  const now = typeof options.now === "number" ? options.now : _deps.now();
+  const ledger = readPrLinkLedger();
+  const links = Array.isArray(ledger[sessionId]) ? ledger[sessionId] : [];
+  const key = (l) => `${l.repo || "?"}#${l.number}`;
+  const incoming = {
+    number: Number(ref.number),
+    repo: ref.repo || null,
+    url: ref.url || null,
+    state: ref.state || TERMINAL_ACTIONS[ref.action] || "open",
+    action: ref.action || null,
+    updatedAt: now,
+  };
+  const existing = links.find((l) => key(l) === key(incoming));
+  if (existing) {
+    Object.assign(existing, {
+      ...incoming,
+      url: incoming.url || existing.url,
+      repo: incoming.repo || existing.repo,
+    });
+  } else {
+    links.push(incoming);
+    if (links.length > MAX_LINKS_PER_SESSION) {
+      links.sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0));
+      links.length = MAX_LINKS_PER_SESSION;
+    }
+  }
+  ledger[sessionId] = links;
+  writeLedger(ledger);
+  return incoming;
+}
+
+/** Links for a session, newest first. */
+export function getPrLinks(sessionId) {
+  if (!sessionId) return [];
+  const links = readPrLinkLedger()[sessionId];
+  return Array.isArray(links)
+    ? [...links].sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0))
+    : [];
+}
+
+function ghPrForBranch(cwd, timeoutMs = 3000) {
+  const run = (file, fileArgs) =>
+    new Promise((resolve) => {
+      _deps.execFile(
+        file,
+        fileArgs,
+        { cwd, encoding: "utf8", timeout: timeoutMs, windowsHide: true },
+        (err, stdout) => resolve(err ? null : String(stdout || "").trim()),
+      );
+    });
+  return (async () => {
+    const branch = await run("git", ["rev-parse", "--abbrev-ref", "HEAD"]);
+    if (!branch || branch === "HEAD") return [];
+    const out = await run("gh", [
+      "pr",
+      "list",
+      "--head",
+      branch,
+      "--json",
+      "number,url,state",
+    ]);
+    if (!out) return [];
+    try {
+      const rows = JSON.parse(out);
+      return (Array.isArray(rows) ? rows : []).map((r) => {
+        const urlMatch = String(r.url || "").match(
+          /github\.com\/([\w.-]+)\/([\w.-]+)\/pull\//,
+        );
+        return {
+          number: Number(r.number),
+          url: r.url || null,
+          repo: urlMatch ? `${urlMatch[1]}/${urlMatch[2]}` : null,
+          state: String(r.state || "open").toLowerCase(),
+          action: "push",
+        };
+      });
+    } catch {
+      return [];
+    }
+  })();
+}
+
+/**
+ * Best-effort hook for the run_shell tool: record PR links produced by this
+ * command. Fire-and-forget — resolves quietly on every failure path.
+ */
+export async function recordFromShellCommand({
+  sessionId,
+  command,
+  output,
+  cwd,
+}) {
+  try {
+    if (!sessionId || !command) return;
+    if (isGhPrCommand(command)) {
+      for (const ref of parsePrRefs(command, output)) {
+        recordPrLink(sessionId, ref);
+      }
+      return;
+    }
+    if (/^\s*git\s+push\b/.test(String(command))) {
+      const refs = await ghPrForBranch(cwd || process.cwd());
+      for (const ref of refs) recordPrLink(sessionId, ref);
+    }
+  } catch {
+    /* never surface ledger failures into tool results */
+  }
+}
+
+/** One-line render for panels: "#123 open · #98 merged". */
+export function formatPrLinks(links) {
+  return (links || [])
+    .map((l) => `#${l.number}${l.state ? ` ${l.state}` : ""}`)
+    .join(" · ");
+}

package/src/lib/project-mcp-trust.js

@@ -0,0 +1,87 @@
+/**
+ * Project `.mcp.json` fingerprint trust (gap-analysis 2026-07-11 P1 "MCP 生命
+ * 周期" — 配置指纹变化后重新信任).
+ *
+ * `--project-mcp` opts a run into a checked-in `.mcp.json`, which can spawn
+ * arbitrary commands. That consent is for the file AS THE USER SAW IT — a
+ * later commit (or a compromised dependency's postinstall) editing the file
+ * must not ride the standing opt-in. So the first successful load records a
+ * sha256 fingerprint per absolute file path; a later load whose content no
+ * longer matches is REFUSED (fail-closed) until the user re-trusts via
+ * `CC_PROJECT_MCP_TRUST=1` (one-shot) or `cc mcp trust-project`.
+ *
+ * Store: ~/.chainlesschain/trusted-project-mcp.json  { [absPath]: {fingerprint, trustedAt} }
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { getHomeDir } from "./paths.js";
+
+export const _deps = { fs };
+
+function storePath(opts = {}) {
+  return (
+    opts.storePath ||
+    process.env.CC_PROJECT_MCP_TRUST_STORE ||
+    path.join(getHomeDir(), "trusted-project-mcp.json")
+  );
+}
+
+export function projectMcpFingerprint(content) {
+  return createHash("sha256").update(String(content), "utf-8").digest("hex");
+}
+
+function readStore(opts) {
+  try {
+    const raw = _deps.fs.readFileSync(storePath(opts), "utf-8");
+    const data = JSON.parse(raw);
+    return data && typeof data === "object" ? data : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Check a project .mcp.json against the trust store.
+ * @returns {{status:"first-use"|"trusted"|"changed", fingerprint:string}}
+ */
+export function checkProjectMcpTrust(file, content, opts = {}) {
+  const fingerprint = projectMcpFingerprint(content);
+  const record = readStore(opts)[path.resolve(file)];
+  if (!record || !record.fingerprint) {
+    return { status: "first-use", fingerprint };
+  }
+  return {
+    status: record.fingerprint === fingerprint ? "trusted" : "changed",
+    fingerprint,
+  };
+}
+
+/** Record (or re-record) the trusted fingerprint for a file. */
+export function recordProjectMcpTrust(file, content, opts = {}) {
+  const target = storePath(opts);
+  const store = readStore(opts);
+  store[path.resolve(file)] = {
+    fingerprint: projectMcpFingerprint(content),
+    trustedAt: new Date(
+      typeof opts.now === "number" ? opts.now : Date.now(),
+    ).toISOString(),
+  };
+  try {
+    _deps.fs.mkdirSync(path.dirname(target), { recursive: true });
+    _deps.fs.writeFileSync(target, JSON.stringify(store, null, 2), {
+      encoding: "utf-8",
+      mode: 0o600,
+    });
+    return true;
+  } catch {
+    return false; // best-effort — a failed record just re-prompts next run
+  }
+}
+
+/** Truthy CC_PROJECT_MCP_TRUST → the user explicitly re-trusts this run. */
+export function projectMcpRetrustRequested(env = process.env) {
+  const raw = String(env.CC_PROJECT_MCP_TRUST || "").toLowerCase();
+  return raw === "1" || raw === "true";
+}