chainlesschain 0.162.163 → 0.162.164

package/src/repl/agent-repl.js

@@ -2188,7 +2188,7 @@ export async function startAgentRepl(options = {}) {
         `  ${chalk.cyan("/export")}     Save this conversation to a Markdown file (/export [path])`,
       );
       logger.log(
-        `  ${chalk.cyan("/rewind")}     Rewind to an earlier turn (double-Esc lists); ${chalk.cyan("/rewind clear")} restores a /clear`,
+        `  ${chalk.cyan("/rewind")}     Rewind to an earlier turn (double-Esc lists); ${chalk.cyan("/rewind <n> --files|--conversation")} scopes it; ${chalk.cyan("/rewind <n> --branch")} forks a session; ${chalk.cyan("/rewind clear")} restores a /clear`,
       );
       logger.log(
         `  ${chalk.cyan("/goal <cond>")} Set a session goal checked after each turn (exit-zero:/file-exists:/contains:/regex:/text); ${chalk.cyan("/goal")} shows, ${chalk.cyan("/goal clear")} drops`,
@@ -3020,9 +3020,17 @@ export async function startAgentRepl(options = {}) {
           restoreClearedConversation,
           buildRewindPlan,
           renderRewindWarnings,
+          buildBranchPlan,
+          renderBranchPlan,
+          parseRewindArg,
+          RESTORE_SCOPE,
         } = await import("../lib/repl-rewind.js");
         const arg = trimmed.slice("/rewind".length).trim();
-        if (arg === "clear" || arg === "undo-clear") {
+        // Parse the turn number + optional restore scope (--conversation /
+        // --files / --both). Claude-Code parity: a rewind can restore the
+        // conversation only, the files only, or both.
+        const parsed = parseRewindArg(arg);
+        if (parsed.command === "clear") {
           // Restore the conversation stashed by /clear (Claude-Code 2.1.191).
           const r = restoreClearedConversation(
             messages,
@@ -3045,13 +3053,86 @@ export async function startAgentRepl(options = {}) {
           prompt();
           return;
         }
-        if (!arg) {
+        if (parsed.command === "branch") {
+          // "从这里分支" (P0-3's fourth restore action): fork a NEW independent
+          // session that keeps history up to the chosen turn and diverges from
+          // there. The origin session is NEVER truncated (preservesParent), so
+          // the live conversation continues unchanged.
+          const targetTurn = listUserTurns(messages, { limit: 1000 }).find(
+            (t) => t.n === parsed.n,
+          );
+          if (!targetTurn) {
+            logger.error(`No such turn: ${parsed.n} — run /rewind to list.`);
+          } else if (!sessionId) {
+            logger.error(
+              "Branch needs a persisted session — none is active yet.",
+            );
+          } else {
+            const turnIndex = targetTurn.index;
+            const plan = buildBranchPlan(
+              messages,
+              _checkpointMarks,
+              turnIndex,
+              {
+                parentSessionId: sessionId,
+                writeIntent: parsed.writeIntent,
+              },
+            );
+            if (!plan || !plan.branchSessionId) {
+              logger.error("Could not plan a branch from that turn.");
+            } else {
+              try {
+                const { createBranchSession } =
+                  await import("../harness/jsonl-session-store.js");
+                const res = createBranchSession({
+                  branchSessionId: plan.branchSessionId,
+                  parentSessionId: sessionId,
+                  parentTurnId: plan.parentTurnId,
+                  messages: messages.slice(0, turnIndex),
+                  meta: { title: `Branch of ${sessionId}` },
+                });
+                logger.log(
+                  chalk.green(
+                    res.created
+                      ? `🌿 branched to ${res.branchSessionId} — ${res.messages} message(s) kept; parent ${sessionId} untouched`
+                      : `🌿 branch ${res.branchSessionId} already exists; parent ${sessionId} untouched`,
+                  ),
+                );
+                for (const line of renderBranchPlan(plan))
+                  logger.log(chalk.yellow(line));
+                logger.log(
+                  chalk.gray(
+                    `  resume it with  cc agent --resume ${res.branchSessionId}` +
+                      (plan.requiresWorktree
+                        ? "  (write task → branch into an isolated worktree)"
+                        : ""),
+                  ),
+                );
+              } catch (e) {
+                logger.error(`branch failed: ${e.message}`);
+              }
+            }
+          }
+          prompt();
+          return;
+        }
+        if (parsed.command === "list") {
           logger.log(chalk.bold("\nRewind — pick a user turn (newest first):"));
           logger.log(renderTurnList(listUserTurns(messages)));
           const fileHint = _checkpointMarks.length
             ? "  (restores files to that point too — checkpoints are on)"
             : "  (conversation only — start with --checkpoint / git to also rewind files)";
           logger.log(chalk.gray(`Usage: /rewind <n>${fileHint}`));
+          logger.log(
+            chalk.gray(
+              "  scope: /rewind <n> --conversation | --files | --both (default)",
+            ),
+          );
+          logger.log(
+            chalk.gray(
+              "  branch: /rewind <n> --branch [--write] forks an independent session (parent kept)",
+            ),
+          );
           if (_clearedConversation) {
             logger.log(
               chalk.gray(
@@ -3060,50 +3141,67 @@ export async function startAgentRepl(options = {}) {
             );
           }
         } else {
-          // Snapshot BEFORE rewindToTurn truncates `messages`: buildRewindPlan
-          // needs the target turn still present to bind it to its checkpoint.
+          const scope = parsed.scope;
+          const rewindConversation = scope !== RESTORE_SCOPE.FILES;
+          const restoreFiles = scope !== RESTORE_SCOPE.CONVERSATION;
+          // Snapshot + locate the target turn BEFORE any truncation:
+          // buildRewindPlan needs the turn still present to bind its checkpoint,
+          // and a files-only rewind keeps the conversation intact entirely.
           const preRewind = messages.slice();
-          const res = rewindToTurn(messages, arg);
-          if (!res) {
-            logger.error(`No such turn: ${arg} — run /rewind to list.`);
+          const targetTurn = listUserTurns(messages, { limit: 1000 }).find(
+            (t) => t.n === parsed.n,
+          );
+          if (!targetTurn) {
+            logger.error(`No such turn: ${parsed.n} — run /rewind to list.`);
           } else {
-            logger.log(
-              chalk.yellow(
-                `⎌ rewound — dropped ${res.removed} message(s); edit and resend below`,
-              ),
-            );
-            // Coverage-aware honesty (P1 turn/checkpoint binding): print what a
-            // restore can and cannot promise for this turn BEFORE offering the
-            // file restore — a shell/external side-effect → PARTIAL, no
-            // checkpoint → files can't be restored, conversation/files drift.
-            // Derived from the REPL's existing marks (no new agent-loop events);
+            const turnIndex = targetTurn.index;
+            // 1) Conversation rewind (skipped for files-only).
+            if (rewindConversation) {
+              const res = rewindToTurn(messages, parsed.n);
+              logger.log(
+                chalk.yellow(
+                  `⎌ rewound — dropped ${res.removed} message(s); edit and resend below`,
+                ),
+              );
+            } else {
+              logger.log(
+                chalk.yellow("⎌ files-only rewind — conversation left intact"),
+              );
+            }
+            // 2) Coverage-aware honesty for the CHOSEN scope (P1 turn/checkpoint
+            // binding): print what a restore can and cannot promise — a shell/
+            // external side-effect → PARTIAL, no checkpoint → files can't be
+            // restored, and a scope-specific conversation/files drift. Derived
+            // from the REPL's existing marks (no new agent-loop events);
             // best-effort so the advisory never blocks the rewind itself.
             try {
               const plan = buildRewindPlan(
                 preRewind,
                 _checkpointMarks,
-                res.index,
+                turnIndex,
+                scope,
               );
               for (const line of renderRewindWarnings(plan))
                 logger.log(chalk.yellow(line));
             } catch {
               /* advisory only — a rewind must never fail over its own warning */
             }
-            // Claude-Code parity: rewind restores files too. Match the dropped
-            // turn to the snapshot taken just before it first mutated the tree,
-            // then offer to roll the working tree back to it (undoable — the
-            // restore takes its own safety checkpoint first).
-            const cp = pickCheckpointForTurn(_checkpointMarks, res.index);
-            pruneMarksAfter(_checkpointMarks, res.index);
+            // 3) File restore (skipped for conversation-only). Match the turn to
+            // the snapshot taken just before it first mutated the tree, then
+            // offer to roll the working tree back to it (undoable — the restore
+            // takes its own safety checkpoint first). Prune dropped-turn marks
+            // only when the conversation was actually truncated.
+            const cp = restoreFiles
+              ? pickCheckpointForTurn(_checkpointMarks, turnIndex)
+              : null;
+            if (rewindConversation)
+              pruneMarksAfter(_checkpointMarks, turnIndex);
             if (cp) {
               const q = (p) => new Promise((r) => rl.question(p, r));
-              const ans = (
-                await q(
-                  chalk.yellow(
-                    `  Also restore files to before this turn? (checkpoint ${cp.id}) [Y/n] `,
-                  ),
-                )
-              )
+              const promptText = rewindConversation
+                ? `  Also restore files to before this turn? (checkpoint ${cp.id}) [Y/n] `
+                : `  Restore files to before this turn? (checkpoint ${cp.id}) [Y/n] `;
+              const ans = (await q(chalk.yellow(promptText)))
                 .trim()
                 .toLowerCase();
               if (ans === "" || ans === "y" || ans === "yes") {
@@ -3120,7 +3218,7 @@ export async function startAgentRepl(options = {}) {
                   );
                 } catch (e) {
                   logger.error(
-                    `  file restore skipped: ${e.message} (conversation already rewound)`,
+                    `  file restore skipped: ${e.message}${rewindConversation ? " (conversation already rewound)" : ""}`,
                   );
                 }
               } else {
@@ -3130,9 +3228,19 @@ export async function startAgentRepl(options = {}) {
                   ),
                 );
               }
+            } else if (restoreFiles && scope === RESTORE_SCOPE.FILES) {
+              logger.log(
+                chalk.gray(
+                  "  no checkpoint captured for that turn — nothing to restore",
+                ),
+              );
             }
             prompt();
-            if (res.text) rl.write(res.text);
+            // Prefill the input line with the turn's text only when the
+            // conversation was rewound (edit-and-resend); files-only leaves the
+            // conversation and the prompt untouched.
+            if (rewindConversation && typeof targetTurn.content === "string")
+              rl.write(targetTurn.content);
             return;
           }
         }
@@ -3437,7 +3545,9 @@ export async function startAgentRepl(options = {}) {
             if (!_asyncHookSupervisor) {
               const { AsyncHookSupervisor } =
                 await import("../lib/async-hook-supervisor.cjs");
-              _asyncHookSupervisor = new AsyncHookSupervisor();
+              _asyncHookSupervisor = new AsyncHookSupervisor({
+                persistStats: true,
+              });
             }
             dispatchAsyncHooks(_settingsHooks, "ConfigChange", payload, {
               cwd,
@@ -4813,7 +4923,9 @@ export async function startAgentRepl(options = {}) {
         if (!_asyncHookSupervisor) {
           const { AsyncHookSupervisor } =
             await import("../lib/async-hook-supervisor.cjs");
-          _asyncHookSupervisor = new AsyncHookSupervisor();
+          _asyncHookSupervisor = new AsyncHookSupervisor({
+            persistStats: true,
+          });
         }
         dispatchAsyncHooks(
           _settingsHooks,
@@ -5100,7 +5212,7 @@ export async function startAgentRepl(options = {}) {
       if (_settingsHooks && !_asyncHookSupervisor) {
         const { AsyncHookSupervisor } =
           await import("../lib/async-hook-supervisor.cjs");
-        _asyncHookSupervisor = new AsyncHookSupervisor();
+        _asyncHookSupervisor = new AsyncHookSupervisor({ persistStats: true });
       }
       const {
         content: response,
@@ -5442,7 +5554,9 @@ export async function startAgentRepl(options = {}) {
           if (!_asyncHookSupervisor) {
             const { AsyncHookSupervisor } =
               await import("../lib/async-hook-supervisor.cjs");
-            _asyncHookSupervisor = new AsyncHookSupervisor();
+            _asyncHookSupervisor = new AsyncHookSupervisor({
+              persistStats: true,
+            });
           }
           dispatchAsyncHooks(
             _settingsHooks,

package/src/runtime/agent-core.js

@@ -26,6 +26,7 @@ import sharedHookRunner from "../lib/hook-runner.cjs";
 import sharedHookEvents from "../lib/settings-hook-events.cjs";
 import { mergeProviderOptions } from "../lib/provider-options.js";
 import { applyCredentialProxy } from "../lib/credential-proxy.js";
+import { describeBackgroundCommand } from "../lib/terminal-context.js";
 import { buildTelemetryAttributes } from "../lib/telemetry-ids.js";
 import { getPlanModeManager } from "../lib/plan-mode.js";
 import { CLISkillLoader } from "../lib/skill-loader.js";
@@ -45,6 +46,11 @@ import {
 import { createToolContext } from "../tools/tool-context.js";
 import { createToolTelemetryRecord } from "../tools/tool-telemetry.js";
 import { isAbortError, throwIfAborted } from "../lib/abort-utils.js";
+import {
+  classifyEditReplay,
+  editIdempotencyKey,
+  EDIT_REPLAY,
+} from "../lib/idempotency.js";
 import { buildSearchCommand } from "../lib/search-command.js";
 import { discoverCommands } from "../lib/slash-commands.js";
 import {
@@ -138,18 +144,37 @@ function _readBgStream(stream) {
 }
 
 /**
- * Snapshot of background shell tasks (for REPL/host status surfaces).
- * @returns {Array<{id:string,status:string,command:string,exitCode:number|null}>}
+ * Snapshot of background shell tasks (for REPL/host status surfaces AND the
+ * model-facing `check_shell { list:true }` tool).
+ *
+ * P1-2 (terminal-context): the `command` string can carry an inline secret
+ * (`FOO=token cmd`, `curl -H "Authorization: Bearer …"`); this list is shown to
+ * the model and rendered in `/tasks`, so run it through
+ * `describeBackgroundCommand` to secret-redact the command and expose the PID.
+ * The task's own lifecycle `status` (running/exited/failed/error) is preserved
+ * — that is distinct from a health check, so it is NOT replaced. `stoppable` is
+ * gated on the task still running (a valid pid alone doesn't make a dead task
+ * stoppable).
+ * @returns {Array<{id:string,status:string,command:string,pid:number|null,
+ *   stoppable:boolean,exitCode:number|null,startedAt:string,endedAt:string}>}
  */
 export function listBackgroundShellTasks() {
-  return Array.from(_backgroundShellTasks.values()).map((t) => ({
-    id: t.id,
-    status: t.status,
-    command: t.command,
-    exitCode: t.exitCode,
-    startedAt: t.startedAt,
-    endedAt: t.endedAt,
-  }));
+  return Array.from(_backgroundShellTasks.values()).map((t) => {
+    const desc = describeBackgroundCommand({
+      command: t.command,
+      pid: t.child?.pid,
+    });
+    return {
+      id: t.id,
+      status: t.status,
+      command: desc.command, // P1-2: secret-redacted
+      pid: desc.pid, // P1-2: PID surfaced
+      stoppable: t.status === "running" && desc.stoppable,
+      exitCode: t.exitCode,
+      startedAt: t.startedAt,
+      endedAt: t.endedAt,
+    };
+  });
 }
 
 // Kill a background task's whole process tree. Because tasks are spawned with
@@ -2100,6 +2125,26 @@ async function _withPostEditDiagnostics(result, filePath, cwd) {
   return newDiagnostics ? { ...result, newDiagnostics } : result;
 }
 
+/**
+ * Drop skills whose `paths:` frontmatter scopes them to a different subtree than
+ * the agent's cwd (large-monorepo lazy skill surface). A skill with no `paths`
+ * applies everywhere, so a skill set with none is returned unchanged. Best-effort:
+ * any failure (or an unlocatable project root → relCwd "") falls open to the full
+ * list, never hiding a skill spuriously.
+ */
+async function filterSkillsByCwd(skills, cwd) {
+  try {
+    if (!Array.isArray(skills) || skills.every((s) => !s?.paths)) return skills;
+    const { filterSkillsByRelCwd, relCwdForCwd } =
+      await import("../lib/skill-path-scope.js");
+    const { findProjectRoot } = await import("../lib/project-detector.js");
+    const root = (cwd && findProjectRoot(cwd)) || cwd || "";
+    return filterSkillsByRelCwd(skills, relCwdForCwd(cwd, root));
+  } catch {
+    return skills; // fail-open: never hide a skill because scoping errored
+  }
+}
+
 async function executeToolInner(
   name,
   args,
@@ -2323,6 +2368,30 @@ async function executeToolInner(
         replaceAll,
       );
       if (count === 0) {
+        // Idempotent replay (P0-2 "Diff Apply 内容哈希"): a resumed edit whose
+        // old_string is already gone but whose new_string is present already
+        // landed. Report a no-op success (NO write occurs — zero data risk)
+        // rather than a misleading "not found" error, so a recovered worker
+        // doesn't get stuck re-issuing an edit that already happened.
+        const replay = classifyEditReplay({
+          content,
+          oldString: args.old_string,
+          newString: args.new_string,
+        });
+        if (replay === EDIT_REPLAY.ALREADY_APPLIED) {
+          return attachDescriptor({
+            success: true,
+            path: filePath,
+            alreadyApplied: true,
+            idempotencyKey: editIdempotencyKey({
+              path: args.path,
+              oldString: args.old_string,
+              newString: args.new_string,
+              replaceAll,
+            }),
+            note: "edit already applied (new_string present, old_string absent) — no change made",
+          });
+        }
         return attachDescriptor({ error: "old_string not found in file" });
       }
       // Require a UNIQUE match (Claude-Code Edit parity) — replacing the first
@@ -3220,6 +3289,16 @@ async function executeToolInner(
           goalMaxTokens: args.goal_max_tokens ?? null,
           goalMaxCost: args.goal_max_cost ?? null,
           goalMaxTime: args.goal_max_time ?? null,
+          // P1-8: action classes this unattended task may still perform (e.g.
+          // "publish", "external_message"). Accepts an array or a comma list.
+          unattendedAllowlist: Array.isArray(args.unattended_allow)
+            ? args.unattended_allow
+            : typeof args.unattended_allow === "string"
+              ? args.unattended_allow
+                  .split(",")
+                  .map((s) => s.trim())
+                  .filter(Boolean)
+              : null,
         };
         if (action === "wakeup") {
           if (!args.prompt) {
@@ -3620,7 +3699,10 @@ async function executeToolInner(
     }
 
     case "run_skill": {
-      const allSkills = skillLoader.getResolvedSkills().filter(skillAllowed);
+      const allSkills = await filterSkillsByCwd(
+        skillLoader.getResolvedSkills().filter(skillAllowed),
+        cwd,
+      );
       if (allSkills.length === 0) {
         return attachDescriptor({
           error: _skillAllowlist
@@ -3766,7 +3848,10 @@ async function executeToolInner(
     }
 
     case "list_skills": {
-      let skills = skillLoader.getResolvedSkills().filter(skillAllowed);
+      let skills = await filterSkillsByCwd(
+        skillLoader.getResolvedSkills().filter(skillAllowed),
+        cwd,
+      );
       if (skills.length === 0) {
         return attachDescriptor({
           error: _skillAllowlist
@@ -6379,6 +6464,22 @@ function extractInitialPromptText(messages) {
   return "";
 }
 
+/**
+ * Stable id for a permission GATE decision, so a denied/gated tool span can be
+ * correlated with the decision that blocked it. Only gated results carry a
+ * `policy` (allow-path tools execute with no distinct decision), so this returns
+ * null when there's nothing to identify. Deterministic (call id + gate) — no
+ * clock/RNG — so a consumer holding the tool-result's policy + tool_call_id can
+ * recompute it. Not exported (no shim-parity impact) — only the telemetry seam
+ * uses it.
+ */
+function permissionDecisionId(callId, policy) {
+  if (!policy || typeof policy !== "object" || !policy.decision) return null;
+  const gate = policy.via || policy.decision;
+  const base = callId || "call";
+  return `${base}:perm:${gate}`;
+}
+
 export async function* agentLoop(messages, options) {
   // Shared iteration budget — replaces hardcoded MAX_ITERATIONS.
   // When options.iterationBudget is provided (e.g. from parent agent),
@@ -6858,6 +6959,18 @@ export async function* agentLoop(messages, options) {
       }
     }
 
+    // Per-span unified ids (P2 observability): the run-level default attributes
+    // stamp session/agent/workflow ids on every span, but turn/prompt ids are
+    // per-iteration. A "turn" is one model iteration of the run; "prompt" is the
+    // model request within that turn. Normalized through buildTelemetryAttributes
+    // so they get the same charset-sanitized + cardinality-bounded treatment as
+    // the run-level ids (turn.id correlates with the agent.iteration counter).
+    const modelIdAttrs = recorder
+      ? buildTelemetryAttributes({
+          turnId: `${runId}:t${budget.consumed}`,
+          promptId: `${runId}:t${budget.consumed}:p`,
+        })
+      : null;
     const result = await _withSpan(
       recorder,
       "agent.model",
@@ -6865,6 +6978,7 @@ export async function* agentLoop(messages, options) {
         "gen_ai.system": options.provider || "ollama",
         "gen_ai.request.model": options.model || "unknown",
         "agent.iteration": budget.consumed,
+        ...(modelIdAttrs || {}),
       },
       () => llmCall(callMessages, options),
       (span, r) => {
@@ -6886,6 +7000,21 @@ export async function* agentLoop(messages, options) {
           Array.isArray(r?.message?.tool_calls) &&
             r.message.tool_calls.length > 0,
         );
+        // response CONTENT is opt-in (--otlp-content): stamped only when
+        // enabled, redacted + length-capped through the same normalizer; the
+        // field is entirely absent by default so default OTLP stays unchanged.
+        if (options.otlpIncludeContent === true && r?.message?.content) {
+          const respAttrs = buildTelemetryAttributes(
+            { response: r.message.content },
+            { includeContent: true },
+          );
+          if (respAttrs["content.response"] != null) {
+            span.setAttribute(
+              "content.response",
+              respAttrs["content.response"],
+            );
+          }
+        }
       },
       "model_error",
     );
@@ -7163,17 +7292,66 @@ export async function* agentLoop(messages, options) {
 
       let toolResult;
       let toolError = null;
+      // Per-span unified ids (P2 observability): a tool span carries its turn.id
+      // (correlating with the model span of the same iteration), the provider's
+      // tool_use.id (so a tool-result event can be tied back to its call), and —
+      // when auto-checkpoint fired before a mutating tool — the checkpoint.id the
+      // user could restore to. All normalized through buildTelemetryAttributes.
+      // tool_arguments CONTENT is opt-in (--otlp-content): the alias key is only
+      // present when explicitly enabled, so by default the field is omitted
+      // entirely (byte-identical default OTLP), and even opted-in it's length-
+      // capped by redactContent. Mirrors the run-level content.prompt opt-in.
+      const toolContentOptIn = options.otlpIncludeContent === true;
+      const toolIdAttrs = recorder
+        ? buildTelemetryAttributes(
+            {
+              turnId: `${runId}:t${budget.consumed}`,
+              toolUseId: call.id,
+              checkpointId: cpId || undefined,
+              ...(toolContentOptIn ? { toolArguments: toolArgs } : {}),
+            },
+            { includeContent: toolContentOptIn },
+          )
+        : null;
       try {
         toolResult = await _withSpan(
           recorder,
           "agent.tool",
-          { "tool.name": toolName },
+          { "tool.name": toolName, ...(toolIdAttrs || {}) },
           () => executeTool(toolName, toolArgs, toolContext),
           (span, r) => {
             span.setAttribute(
               "tool.is_error",
               !!(r && typeof r === "object" && r.error),
             );
+            // permission.decision_id (P2): a GATED tool result carries a
+            // `policy` (deny / ask-fail / host-block / sandbox); allow-path
+            // tools execute with no distinct decision. Stamp a stable id
+            // (derived from the call + gate, so it's recomputable from the
+            // tool-result's policy + tool_call_id) plus the low-cardinality
+            // decision, letting a blocked tool span be tied to its decision.
+            const decId =
+              r && typeof r === "object"
+                ? permissionDecisionId(call.id, r.policy)
+                : null;
+            if (decId) {
+              const permAttrs = buildTelemetryAttributes({
+                decisionId: decId,
+                "permission.decision": r.policy.decision,
+              });
+              if (permAttrs["permission.decision_id"]) {
+                span.setAttribute(
+                  "permission.decision_id",
+                  permAttrs["permission.decision_id"],
+                );
+              }
+              if (permAttrs["permission.decision"]) {
+                span.setAttribute(
+                  "permission.decision",
+                  permAttrs["permission.decision"],
+                );
+              }
+            }
           },
           "tool_error",
         );

package/src/runtime/diagnostics.js

@@ -288,6 +288,66 @@ export async function collectDoctorReport() {
   };
 }
 
+/**
+ * Parse `git worktree list --porcelain` output into `{ path, branch }` entries.
+ *
+ * Pure (no I/O) so it can be unit-tested against fixed fixtures. A detached
+ * worktree has no `branch` line and yields `branch: null`.
+ */
+export function parseGitWorktrees(porcelain) {
+  if (!porcelain || typeof porcelain !== "string") return [];
+  const entries = [];
+  let cur = null;
+  for (const line of porcelain.split("\n")) {
+    const trimmed = line.trimEnd();
+    if (trimmed.startsWith("worktree ")) {
+      if (cur) entries.push(cur);
+      cur = { path: trimmed.slice("worktree ".length).trim(), branch: null };
+    } else if (trimmed.startsWith("branch ") && cur) {
+      cur.branch = trimmed
+        .slice("branch ".length)
+        .replace("refs/heads/", "")
+        .trim();
+    }
+  }
+  if (cur) entries.push(cur);
+  return entries;
+}
+
+/** Best-effort live git worktree list for the current repo. */
+export function collectWorktrees() {
+  return parseGitWorktrees(safeExec("git worktree list --porcelain"));
+}
+
+/**
+ * Map a doctor report + ambient runtime signals into the input contract of
+ * `buildDiagnosticBundle` (src/lib/diagnostic-bundle.js).
+ *
+ * Pure & deterministic aside from reading this process's own platform tags:
+ * the caller gathers live signals (env, worktrees, lockfiles) and passes them
+ * in, so the mapping itself is unit-testable. Session-runtime fields
+ * (connectionState, reconnectHistory, trace, redactionEvents) are absent from a
+ * cold `cc doctor` invocation and left to the bundle builder's safe defaults.
+ */
+export function buildDoctorDiagnosticInput(report, signals = {}) {
+  const r = report || {};
+  return {
+    version: r.version || null,
+    platform: {
+      os: process.platform,
+      arch: process.arch,
+      node: process.versions?.node || null,
+    },
+    ports: (Array.isArray(r.ports) ? r.ports : [])
+      .filter((p) => p && p.open)
+      .map((p) => ({ port: p.port, proto: p.name })),
+    worktrees: Array.isArray(signals.worktrees) ? signals.worktrees : [],
+    lockfiles: Array.isArray(signals.lockfiles) ? signals.lockfiles : [],
+    env: signals.env && typeof signals.env === "object" ? signals.env : {},
+    notes: signals.notes != null ? signals.notes : null,
+  };
+}
+
 /**
  * Collect a machine-readable status report.
  *