chainlesschain 0.162.124 → 0.162.126

package/src/lib/checkpoint-store.js

@@ -76,9 +76,19 @@ function gitDir(root) {
   return path.resolve(root, git(["rev-parse", "--git-dir"], { cwd: root }));
 }
 
-/** Ref-safe session segment. */
+/**
+ * Ref-safe session segment. Beyond the charset filter, enforce git's per-
+ * component ref rules so a legit-looking name never makes every checkpoint op
+ * throw: a component may not begin with `.`, contain `..`, or end with `.lock`
+ * (`/` is already collapsed to `-`, so the session is always a single segment
+ * and cannot traverse the ref namespace).
+ */
 function sanitizeSession(session) {
-  const s = String(session || "default").replace(/[^A-Za-z0-9._-]/g, "-");
+  let s = String(session || "default").replace(/[^A-Za-z0-9._-]/g, "-");
+  s = s.replace(/\.{2,}/g, "."); // git forbids ".." in a refname
+  s = s.replace(/^\.+/, ""); // a component may not begin with "."
+  s = s.replace(/\.lock$/i, "-lock"); // nor end with ".lock"
+  s = s.replace(/\.+$/, ""); // nor end with a dot
   return s || "default";
 }
 
@@ -86,9 +96,20 @@ function sessionPrefix(session) {
   return `${REF_NS}/${sanitizeSession(session)}`;
 }
 
+// Monotonic per-process counter so two temp-index paths minted in the same
+// millisecond never collide. pid disambiguates across processes; Date.now() +
+// this counter disambiguate within one. A collision would mean two operations
+// sharing one GIT_INDEX_FILE (corrupt snapshot) or one's cleanup deleting the
+// other's live index.
+let _indexSeq = 0;
+
 /** Unique temp index path inside .git (never the real index). */
 function tempIndexPath(dir) {
-  return path.join(dir, `cc-checkpoint-index-${process.pid}-${Date.now()}`);
+  _indexSeq = (_indexSeq + 1) >>> 0;
+  return path.join(
+    dir,
+    `cc-checkpoint-index-${process.pid}-${Date.now()}-${_indexSeq}`,
+  );
 }
 
 /**
@@ -580,4 +601,10 @@ export function clearCheckpoints(cwd = process.cwd(), opts = {}) {
 }
 
 // Exposed for unit tests / advanced callers.
-export const _internals = { git, repoRoot, sanitizeSession, snapshotTree };
+export const _internals = {
+  git,
+  repoRoot,
+  sanitizeSession,
+  snapshotTree,
+  tempIndexPath,
+};

package/src/lib/claude-code-bridge.js

@@ -29,6 +29,13 @@ export const AGENT_STATUS = {
   TIMEOUT: "timeout",
 };
 
+// Bound how much of a child's stdout/stderr we retain in memory. A verbose or
+// runaway `claude -p` can stream unbounded stream-json; without a cap,
+// outputChunks.join("") OOMs the orchestrator. We keep the TAIL (oldest chunks
+// dropped) because stream-json's terminal `result` / last-assistant line — the
+// only thing _parseStreamJson needs — is at the end.
+export const MAX_AGENT_OUTPUT_BYTES = 32 * 1024 * 1024;
+
 // ─── Detection ───────────────────────────────────────────────────
 
 /**
@@ -98,6 +105,7 @@ export class ClaudeCodeAgent extends EventEmitter {
       context = "",
       allowedTools = null,
       killGraceMs = 3000,
+      maxOutputBytes = MAX_AGENT_OUTPUT_BYTES,
     } = options;
 
     const fullPrompt = context
@@ -126,6 +134,19 @@ export class ClaudeCodeAgent extends EventEmitter {
       const outDecoder = new TextDecoder("utf-8");
       const errDecoder = new TextDecoder("utf-8");
       let timedOut = false;
+      // Tail-bounded byte counters for the two buffers (see MAX_AGENT_OUTPUT_BYTES).
+      let outBytes = 0;
+      let errBytes = 0;
+      let outputTruncated = false;
+      // Drop oldest chunks until the buffer is back under the cap, keeping ≥1
+      // chunk (the most recent, where the result line lives).
+      const trim = (chunks, bytesRef) => {
+        let bytes = bytesRef;
+        while (bytes > maxOutputBytes && chunks.length > 1) {
+          bytes -= Buffer.byteLength(chunks.shift());
+        }
+        return bytes;
+      };
 
       const proc = _deps.spawn(this.cliCommand, args, {
         cwd,
@@ -155,15 +176,26 @@ export class ClaudeCodeAgent extends EventEmitter {
             ? data
             : outDecoder.decode(data, { stream: true });
         outputChunks.push(chunk);
+        outBytes += Buffer.byteLength(chunk);
+        if (outBytes > maxOutputBytes) {
+          outputTruncated = true;
+          outBytes = trim(outputChunks, outBytes);
+        }
+        // The live `output` event still streams every chunk verbatim — the cap
+        // only bounds what we RETAIN for the final rawOutput.
         this.emit("output", { agentId: this.id, chunk });
       });
 
       proc.stderr.on("data", (data) => {
-        errorChunks.push(
+        const chunk =
           typeof data === "string"
             ? data
-            : errDecoder.decode(data, { stream: true }),
-        );
+            : errDecoder.decode(data, { stream: true });
+        errorChunks.push(chunk);
+        errBytes += Buffer.byteLength(chunk);
+        if (errBytes > maxOutputBytes) {
+          errBytes = trim(errorChunks, errBytes);
+        }
       });
 
       proc.on("close", (code) => {
@@ -188,6 +220,7 @@ export class ClaudeCodeAgent extends EventEmitter {
           success: code === 0 && !timedOut,
           output: parsedOutput || rawOutput.slice(-4000), // last 4K chars fallback
           rawOutput,
+          outputTruncated, // true when the child exceeded maxOutputBytes
           exitCode: code,
           duration,
           timedOut,
@@ -257,6 +290,15 @@ export class ClaudeCodePool extends EventEmitter {
     this.model = options.model || null;
     this.agentTimeout = options.agentTimeout || 300_000;
 
+    // Bound retained completion history. dispatch() returns results directly,
+    // so _completed is only a recent-history buffer — but it was an unbounded
+    // array, so a long-lived pool dispatching many tasks leaked memory forever.
+    // Keep a recent window (FIFO). Default 1000; 0/invalid → 1000.
+    this.maxCompleted =
+      Number.isFinite(options.maxCompleted) && options.maxCompleted > 0
+        ? options.maxCompleted
+        : 1000;
+
     /** @type {Map<string, ClaudeCodeAgent>} */
     this._agents = new Map();
     this._completed = [];
@@ -315,6 +357,9 @@ export class ClaudeCodePool extends EventEmitter {
 
     this._agents.delete(agent.id);
     this._completed.push({ ...result, taskId: task.id });
+    if (this._completed.length > this.maxCompleted) {
+      this._completed.splice(0, this._completed.length - this.maxCompleted);
+    }
 
     this.emit("agent:complete", { taskId: task.id, ...result });
     return { taskId: task.id, ...result };

package/src/lib/config-manager.js

@@ -11,6 +11,16 @@ import { getConfigPath } from "./paths.js";
 import { DEFAULT_CONFIG } from "../constants.js";
 import { withFileLock } from "./with-file-lock.js";
 
+// Warn at most once per config path per process. Injectable seam: the default
+// stays silent under vitest so test output isn't polluted; tests override
+// `_deps.warn` to assert it fired.
+const _warnedConfigPaths = new Set();
+export const _deps = {
+  warn: (msg) => {
+    if (!process.env.VITEST) process.stderr.write(msg);
+  },
+};
+
 export function loadConfig() {
   const configPath = getConfigPath();
   if (!existsSync(configPath)) {
@@ -20,7 +30,21 @@ export function loadConfig() {
     const raw = readFileSync(configPath, "utf-8");
     const parsed = JSON.parse(raw);
     return deepMerge(structuredClone(DEFAULT_CONFIG), parsed);
-  } catch {
+  } catch (err) {
+    // The file EXISTS but couldn't be read/parsed (a typo, trailing comma, or
+    // truncated write). Silently returning defaults drops the user's entire
+    // config — provider, model, baseUrl, API key — and falls back to the
+    // default provider, producing a baffling "configured X but it runs Y / says
+    // no API key". Warn once so the failure is visible; still fall back so cc
+    // keeps working.
+    if (!_warnedConfigPaths.has(configPath)) {
+      _warnedConfigPaths.add(configPath);
+      _deps.warn(
+        `⚠️  Could not read config at ${configPath} (${err.message}). ` +
+          `Using defaults — your saved settings (provider / model / API key) are being IGNORED. ` +
+          `Fix the JSON to restore them.\n`,
+      );
+    }
     return { ...structuredClone(DEFAULT_CONFIG) };
   }
 }

package/src/lib/cost-budget.js

@@ -86,8 +86,19 @@ export class CostBudget {
     if (est.free) {
       this.sawFree = true;
     } else if (est.matched) {
-      this.spentUsd = round(this.spentUsd + est.totalCost);
-      this.priced = true;
+      // Defense-in-depth for a SAFETY control: a non-finite/negative cost (e.g.
+      // a malformed price table entry, or a non-numeric token count in a
+      // provider's usage event) must NOT poison spentUsd into NaN — `NaN >=
+      // limit` is always false, which would silently DISABLE the hard cap and
+      // allow unbounded spend on an unattended run. Only fold a clean cost;
+      // otherwise treat the record as unpriced.
+      const cost = Number(est.totalCost);
+      if (Number.isFinite(cost) && cost >= 0) {
+        this.spentUsd = round(this.spentUsd + cost);
+        this.priced = true;
+      } else {
+        this.sawUnpriced = true;
+      }
     } else if (tokens > 0) {
       this.sawUnpriced = true;
     }

package/src/lib/credential-guard.js

@@ -25,8 +25,16 @@
  */
 
 import { createRequire } from "node:module";
+import fsDefault from "node:fs";
+import pathDefault from "node:path";
 
 const require_ = createRequire(import.meta.url);
+
+// Injectable for tests (realpath of a symlink without touching the real fs).
+export const _deps = {
+  realpathSync: fsDefault.realpathSync,
+  resolve: pathDefault.resolve,
+};
 // Reuse the shell policy's compound-command splitter (separators + $()/backtick
 // extraction). It is regex-based on separators and leaves backslashes intact,
 // so Windows paths survive (unlike the escaping tokenizer, which strips `\`).
@@ -108,10 +116,43 @@ export function credentialFileReason(targetPath) {
   return null;
 }
 
+/**
+ * Like credentialFileReason, but also follows a symlink to its real target and
+ * re-checks. The name-only guard is bypassable: `read_file({path:"notes.txt"})`
+ * where notes.txt → ~/.ssh/id_rsa reads the key while the guard sees only the
+ * innocent name. fs.readFileSync follows symlinks, so the guard must too —
+ * resolve the real path and re-check its basename/patterns. Falls back to the
+ * literal check when the path can't be resolved (non-existent → the read fails
+ * anyway, nothing to gate). `cwd` anchors a relative target before realpath.
+ *
+ * @param {string} targetPath
+ * @param {object} [opts] { cwd, deps }
+ * @returns {string|null}
+ */
+export function credentialFileReasonResolved(targetPath, opts = {}) {
+  const direct = credentialFileReason(targetPath);
+  if (direct) return direct;
+  const deps = opts.deps || _deps;
+  const cwd = opts.cwd || process.cwd();
+  try {
+    const real = deps.realpathSync(
+      deps.resolve(cwd, String(targetPath || ".")),
+    );
+    const viaLink = credentialFileReason(real);
+    if (viaLink) return `${viaLink} (via symlink)`;
+  } catch {
+    // Unresolvable / non-existent — the read itself would fail; nothing to gate.
+  }
+  return null;
+}
+
 // ── secret ENV-VAR + command detection ──────────────────────────────────────
 
 // Content-reader commands: when one of these is aimed at a credential file, the
-// file's bytes land in the agent's tool output.
+// file's bytes land in the agent's tool output. Includes text processors
+// (awk/sed), encoders (base64), and field/byte slicers — all of which dump a
+// file's content just like `cat`, so an agent told to "read the .env" can't
+// route around the guard with `base64 .env` / `awk '{print}' .env`.
 const READ_COMMANDS = new Set([
   "cat",
   "tac",
@@ -127,8 +168,31 @@ const READ_COMMANDS = new Set([
   "xxd",
   "od",
   "strings",
+  "awk",
+  "gawk",
+  "mawk",
+  "sed",
+  "base64",
+  "base32",
+  "cut",
+  "rev",
+  "sort",
+  "uniq",
+  "tr",
+  "fold",
+  "expand",
+  "unexpand",
+  "column",
+  "paste",
+  "pr",
 ]);
 
+// grep-family is a content-reader too, but its FIRST non-flag arg is the search
+// PATTERN (which may itself look credential-ish, e.g. `grep "id_rsa" notes.txt`)
+// — so it is handled separately, checking only the FILE args after the pattern,
+// to keep the guard precise (no false positive on the pattern).
+const GREP_COMMANDS = new Set(["grep", "egrep", "fgrep", "rg", "ag"]);
+
 // Commands whose job is to print a value into output — the exfil surface for a
 // secret env var (a tool that merely CONSUMES `$API_KEY` does not echo it).
 const PRINT_COMMANDS = new Set([
@@ -243,6 +307,22 @@ export function commandReadsCredentials(command) {
       }
     }
 
+    // (b2) grep-family: skip the search pattern (first non-flag arg) and check
+    //      only the file args, so `grep KEY .env` is caught but `grep "id_rsa"
+    //      notes.txt` (searching FOR that text) is not a false positive.
+    if (GREP_COMMANDS.has(first)) {
+      for (const tok of nonFlagArgs.slice(1)) {
+        const r = credentialFileReason(tok);
+        if (r)
+          return {
+            reason: `reads ${r}`,
+            kind: "file",
+            target: tok,
+            segment: seg,
+          };
+      }
+    }
+
     // (c) printing / reading a secret-looking env var (via $VAR / %VAR% / env:).
     if (PRINT_COMMANDS.has(first) || READ_COMMANDS.has(first)) {
       const vars = referencedSecretVars(seg);

package/src/lib/git-integration.js

@@ -105,6 +105,11 @@ export function gitExec(args, cwd) {
     return execSync(`git ${args}`, {
       cwd,
       encoding: "utf-8",
+      // git diff/log/worktree-list output on a large repo easily exceeds
+      // execSync's 1 MB default → ENOBUFS. Match gitExecArgs' 64 MB ceiling so
+      // a big diff/log doesn't spuriously fail (e.g. worktree-diff's --numstat
+      // pass, which isn't wrapped in a degrade-gracefully try/catch).
+      maxBuffer: 64 * 1024 * 1024,
       stdio: ["pipe", "pipe", "pipe"],
     }).trim();
   } catch (err) {
@@ -188,7 +193,11 @@ export function gitAutoCommit(dir, message) {
     message ||
     `auto: ${status.files.length} file(s) changed — ${new Date().toISOString().slice(0, 16)}`;
 
-  gitExec(`commit -m "${commitMsg.replace(/"/g, '\\"')}"`, dir);
+  // Free-text message → argv (no shell) so `$()` / backticks / `;` in a
+  // caller-supplied message (e.g. `cc git auto-commit --message …`) can't
+  // inject a command. The prior `-m "${msg.replace(/"/g,'\\"')}"` only escaped
+  // double quotes — same gap fixed in worktree-isolator / mergeWorktree.
+  gitExecArgs(["commit", "-m", commitMsg], dir);
 
   const hash = gitExec("rev-parse --short HEAD", dir);
 
@@ -209,12 +218,17 @@ export function gitLog(dir, limit = 10) {
   }
 
   try {
+    // Coerce `limit` to a bounded positive integer before it is interpolated
+    // into the shell string — a non-numeric value (`5; rm -rf ~`) would
+    // otherwise inject. The only in-tree caller already passes an int; this is
+    // defense-in-depth at the exported boundary.
+    const n = Math.min(10000, Math.max(1, Number.parseInt(limit, 10) || 10));
     // Subject (%s) is free text that often contains "|"; keep it LAST so a
     // pipe in the subject can't shift the date/author fields, then re-join the
     // remainder. (Field order kept as %X|%X — Windows cmd.exe expands adjacent
     // %VAR% pairs, so a control-char separator like %x1f is not portable here.)
     const output = gitExec(
-      `log --oneline --no-decorate -${limit} --format="%H|%h|%ai|%an|%s"`,
+      `log --oneline --no-decorate -${n} --format="%H|%h|%ai|%an|%s"`,
       dir,
     );
     return output

package/src/lib/goal-store.js

@@ -124,6 +124,13 @@ export function createGoal(input = {}, opts = {}) {
     throw new Error("createGoal requires an objective");
   }
   const id = input.id || newId("goal");
+  // Generated ids are always safe, but `input.id` is caller-supplied — guard it
+  // like every other op (getGoal/saveGoal/deleteGoal) so a crafted id such as
+  // `../../etc/x` can't make atomicWriteFileSync write a .json OUTSIDE the
+  // goals dir. createGoal was the one mutation missing this check.
+  if (isUnsafeGoalId(id)) {
+    throw new Error(`非法 goal id: ${String(id).slice(0, 60)}`);
+  }
   const keyResults = (input.keyResults || []).map((kr) => normalizeKr(kr));
   const goal = {
     id,
@@ -207,6 +214,10 @@ function mutate(id, fn, opts = {}) {
   // sharing the goals dir) so concurrent goal edits don't lose an update.
   // Best-effort lock (with-file-lock): on contention timeout it proceeds anyway,
   // so the CLI never hangs.
+  // Guard before deriving the lock path: an unsafe id would otherwise place the
+  // lock file at a traversal path (`<root>/../../x.json.lock`) before getGoal
+  // even runs. getGoal/saveGoal also guard, but keep the lock inside the dir.
+  if (isUnsafeGoalId(id)) throw new Error(`no such goal: ${id}`);
   const root = opts.root || defaultRoot();
   return withFileLock(goalFile(root, id), () => {
     const goal = getGoal(id, opts);

package/src/lib/hook-manager.js

@@ -285,6 +285,10 @@ export async function executeHook(hook, context = {}) {
       const output = execSync(cmd, {
         encoding: "utf-8",
         timeout: hook.timeout || 5000,
+        // execSync defaults maxBuffer to 1 MB; a hook that prints more (a
+        // linter/build dumping output) would throw ENOBUFS and be reported as a
+        // FAILURE even though it succeeded. Give hook output generous headroom.
+        maxBuffer: 16 * 1024 * 1024,
         env,
       });
       const executionTime = Date.now() - start;

package/src/lib/interaction-adapter.js

@@ -159,7 +159,15 @@ export class WebSocketInteractionAdapter extends InteractionAdapter {
         },
         options.timeoutMs || 5 * 60 * 1000,
       );
-      this._pending.set(requestId, { resolve, reject, timeoutId });
+      // `kind` tags what KIND of response settles this request ("question" vs
+      // "host-tool"). Checked in _resolvePending so a peer's session-answer can
+      // never resolve a host-tool call with a plain string (or vice versa).
+      this._pending.set(requestId, {
+        resolve,
+        reject,
+        timeoutId,
+        kind: options.kind || null,
+      });
 
       this._sendWs({
         ...message,
@@ -170,12 +178,15 @@ export class WebSocketInteractionAdapter extends InteractionAdapter {
   }
 
   _ask(questionType, question, extra = {}) {
-    return this._request({
-      type: "question",
-      questionType,
-      question,
-      ...extra,
-    });
+    return this._request(
+      {
+        type: "question",
+        questionType,
+        question,
+        ...extra,
+      },
+      { kind: "question" },
+    );
   }
 
   async askInput(question, options = {}) {
@@ -200,7 +211,7 @@ export class WebSocketInteractionAdapter extends InteractionAdapter {
    * Resolves the corresponding pending promise.
    */
   resolveAnswer(requestId, answer) {
-    this._resolvePending(requestId, answer);
+    this._resolvePending(requestId, answer, "question");
   }
 
   async requestHostTool(toolName, args = {}, extra = {}) {
@@ -211,12 +222,12 @@ export class WebSocketInteractionAdapter extends InteractionAdapter {
         args,
         ...extra,
       },
-      { timeoutMs: extra.timeoutMs || 60 * 1000 },
+      { timeoutMs: extra.timeoutMs || 60 * 1000, kind: "host-tool" },
     );
   }
 
   resolveHostTool(requestId, payload) {
-    this._resolvePending(requestId, payload);
+    this._resolvePending(requestId, payload, "host-tool");
   }
 
   rejectAllPending(reason = createAbortError("Interaction interrupted")) {
@@ -310,11 +321,21 @@ export class WebSocketInteractionAdapter extends InteractionAdapter {
     }
   }
 
-  _resolvePending(requestId, payload) {
+  _resolvePending(requestId, payload, expectedKind = null) {
     const pending = this._pending.get(requestId);
     if (!pending) {
       return;
     }
+    // Kind guard: a question-answer must not settle a host-tool request (or
+    // vice versa). On a mismatch, IGNORE the message — leave the request pending
+    // so its correct resolver (or its timeout) can still settle it. Prevents a
+    // peer from resolving a host-tool call with a plain question string, or a
+    // question with a structured tool payload (type confusion of the awaited
+    // value). Backward-compatible: callers passing no expectedKind, and
+    // pre-kind pending entries, behave exactly as before.
+    if (expectedKind && pending.kind && pending.kind !== expectedKind) {
+      return;
+    }
 
     this._pending.delete(requestId);
     if (pending.timeoutId) {

package/src/lib/jetbrains-bridge.js

@@ -0,0 +1,147 @@
+/**
+ * JetBrains / IntelliJ IDEA built-in MCP discovery (cc-side).
+ *
+ * IntelliJ IDEA 2025.2+ ships a built-in MCP server (Settings | Tools | MCP
+ * Server) exposing the IDE's own indexed operations (find usages, file-by-path,
+ * search, run configs, VCS, …). Letting the agent call those instead of reading
+ * and grepping files itself is cheaper (fewer tokens) and faster (rides the IDE
+ * index) — that is the whole point of this bridge.
+ *
+ * Unlike our own ide/pdh bridges (ide-bridge.js / pdh-bridge.js), IDEA writes NO
+ * discovery lockfile, so cc cannot scan for it. Instead the ChainlessChain
+ * JetBrains plugin — which runs INSIDE the IDE and therefore knows whether MCP
+ * is supported (IDE >= 2025.2) and enabled, and on which endpoint — injects the
+ * exact endpoint into the env of the `cc agent` it spawns:
+ *
+ *     CHAINLESSCHAIN_JETBRAINS_MCP_URL    http://127.0.0.1:<port>/<path>
+ *     CHAINLESSCHAIN_JETBRAINS_TOKEN      optional bearer token
+ *     CHAINLESSCHAIN_JETBRAINS_TRANSPORT  optional: http | https | sse (else inferred)
+ *
+ * When the IDE does NOT support MCP (older than 2025.2) or it is disabled, the
+ * plugin injects nothing -> cc connects nothing. This is the product decision:
+ * if the IDE's MCP is unsupported, do not try to connect (no port scan, no
+ * external proxy fallback). Reserved server name `idea` -> tools `mcp__idea__*`.
+ *
+ * Pure CLI, no network scan, no external dependency: a deterministic
+ * env -> MCP-config mapping, fully unit-testable. The connect path reuses the
+ * existing MCP client (Streamable-HTTP) via mcp-config.js `loadJetbrainsMcp`.
+ */
+
+/** Transports the CLI's MCP client can actually talk (see mcp-client.js). */
+const SUPPORTED_TRANSPORTS = new Set(["http", "https", "sse"]);
+
+/**
+ * Only ever connect to a loopback endpoint. IDEA's built-in server binds
+ * localhost; refusing anything else keeps an injected env var from pointing cc
+ * at an arbitrary host. `new URL(...).hostname` strips the brackets from an
+ * IPv6 literal on most Node builds but keeps them on some — accept both forms.
+ */
+function isLoopbackUrl(url) {
+  try {
+    const h = new URL(url).hostname.toLowerCase();
+    return (
+      h === "127.0.0.1" || h === "::1" || h === "[::1]" || h === "localhost"
+    );
+  } catch {
+    return false;
+  }
+}
+
+function inferTransportFromUrl(url) {
+  if (/\/sse(\b|\/|$)/i.test(url)) return "sse";
+  if (/^https:/i.test(url)) return "https";
+  if (/^http:/i.test(url)) return "http";
+  return null;
+}
+
+/**
+ * Are we running under the ChainlessChain JetBrains plugin with IDE MCP
+ * available? True iff the plugin injected an MCP URL — which it only does when
+ * the IDE is >= 2025.2 and the MCP server is enabled. No URL = treat as
+ * unsupported and stay out of the way.
+ */
+export function isInJetbrainsContext(env = process.env) {
+  return !!(env && env.CHAINLESSCHAIN_JETBRAINS_MCP_URL);
+}
+
+/**
+ * Resolve the IDEA built-in MCP server to connect to, or null.
+ *
+ * Deterministic: the plugin-injected `CHAINLESSCHAIN_JETBRAINS_MCP_URL` (a
+ * loopback http/https/sse endpoint) is the single source of truth. A missing,
+ * non-loopback, or unsupported-transport URL yields null (don't connect).
+ *
+ * @param {object} opts  { env? }
+ * @returns {{url:string, transport:string, token:(string|null)}|null}
+ */
+export function discoverJetbrainsServer({ env = process.env } = {}) {
+  const url = env && env.CHAINLESSCHAIN_JETBRAINS_MCP_URL;
+  if (!url || !isLoopbackUrl(url)) return null;
+
+  const transport = String(
+    env.CHAINLESSCHAIN_JETBRAINS_TRANSPORT || inferTransportFromUrl(url) || "",
+  ).toLowerCase();
+  if (!SUPPORTED_TRANSPORTS.has(transport)) return null;
+
+  return {
+    url,
+    transport,
+    token:
+      typeof env.CHAINLESSCHAIN_JETBRAINS_TOKEN === "string"
+        ? env.CHAINLESSCHAIN_JETBRAINS_TOKEN
+        : null,
+  };
+}
+
+/**
+ * A discovered server -> an MCP server config row for `setupMcpFromConfig`.
+ * `longRunning` exempts it from the agent loop's per-call timeout (some IDE
+ * operations — e.g. an indexing-gated search — can take a while), matching the
+ * ide/pdh bridges.
+ */
+export function jetbrainsServerToMcpConfig(found) {
+  if (!found || !found.url) return null;
+  const headers = {};
+  if (found.token) headers.Authorization = `Bearer ${found.token}`;
+  return {
+    url: found.url,
+    transport: found.transport,
+    headers,
+    longRunning: true,
+  };
+}
+
+/**
+ * Human-readable explanation of why discovery did / didn't pick a server —
+ * backs `cc ide jetbrains`. Never surfaces the raw token.
+ */
+export function diagnoseJetbrains({ env = process.env } = {}) {
+  const rawUrl = (env && env.CHAINLESSCHAIN_JETBRAINS_MCP_URL) || null;
+  const chosen = discoverJetbrainsServer({ env });
+
+  let reason;
+  if (chosen) {
+    reason = "CHAINLESSCHAIN_JETBRAINS_MCP_URL injected by the IDE plugin";
+  } else if (!rawUrl) {
+    reason =
+      "no CHAINLESSCHAIN_JETBRAINS_MCP_URL — IDE MCP is unsupported (IDEA < " +
+      "2025.2) / disabled, or cc was not launched from the JetBrains plugin";
+  } else if (!isLoopbackUrl(rawUrl)) {
+    reason =
+      "injected URL is not a loopback (127.0.0.1/::1/localhost) endpoint";
+  } else {
+    reason = "injected URL is not a supported transport (http/https/sse)";
+  }
+
+  return {
+    supported: !!rawUrl,
+    chosen: chosen
+      ? {
+          url: chosen.url,
+          transport: chosen.transport,
+          hasToken: !!chosen.token,
+        }
+      : null,
+    reason,
+  };
+}

package/src/lib/jsonl-session-store.js

@@ -30,5 +30,7 @@ export {
   validateAllJsonlSessions,
   sampleMigratedSessionsValidation,
   sessionPath,
+  isUnsafeSessionId,
   appendTokenUsage,
+  toIsoSafe,
 } from "../harness/jsonl-session-store.js";