chainlesschain 0.162.183 → 0.162.185

package/src/harness/background-task-manager.js

@@ -8,8 +8,15 @@
  * Feature-flag gated: BACKGROUND_TASKS
  */
 
-import { existsSync, mkdirSync, appendFileSync, readFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import {
+  existsSync,
+  mkdirSync,
+  appendFileSync,
+  readFileSync,
+  realpathSync,
+  statSync,
+} from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { createHash } from "node:crypto";
 import { EventEmitter } from "node:events";
 import { getHomeDir } from "../lib/paths.js";
@@ -17,6 +24,7 @@ import executionBroker from "../lib/process-execution-broker/index.js";
 
 export const _deps = {
   spawn: executionBroker.spawn.bind(executionBroker),
+  platform: process.platform,
 };
 
 function getTasksDir() {
@@ -41,6 +49,7 @@ const RECOVERABLE_TASK_STATUSES = new Set([
   TaskStatus.PENDING,
   TaskStatus.RUNNING,
 ]);
+const SUPPORTED_STRONG_BOUNDARIES = new Set(["filesystem", "network"]);
 
 function validatePinnedSandboxPolicy(policy) {
   if (policy == null) return null;
@@ -51,7 +60,9 @@ function validatePinnedSandboxPolicy(policy) {
     !Array.isArray(policy.requiredBoundaries) ||
     policy.requiredBoundaries.length === 0 ||
     policy.requiredBoundaries.some(
-      (boundary) => typeof boundary !== "string" || boundary.length === 0,
+      (boundary) =>
+        typeof boundary !== "string" ||
+        !SUPPORTED_STRONG_BOUNDARIES.has(boundary),
     ) ||
     !Object.isFrozen(policy) ||
     !Object.isFrozen(policy.requiredBoundaries)
@@ -65,22 +76,88 @@ function validatePinnedSandboxPolicy(policy) {
   return policy;
 }
 
-function createUnsupportedSandboxError(sandboxPolicy) {
-  const requiredBoundaries = [...sandboxPolicy.requiredBoundaries];
-  const error = new Error(
-    `Background tasks cannot run without their required sandbox boundaries: ${requiredBoundaries.join(", ")}`,
-  );
-  error.code = "ERR_BACKGROUND_TASK_SANDBOX_UNSUPPORTED";
-  error.sandboxReason = "background_execution_unsupported";
+function createSandboxError(code, reason, message, requiredBoundaries = []) {
+  const error = new Error(message);
+  error.code = code;
+  error.sandboxReason = reason;
   error.sandboxFailClosed = true;
-  error.requiredBoundaries = requiredBoundaries;
+  error.requiredBoundaries = [...requiredBoundaries];
   error.actualGuarantees = [];
   error.missingBoundaries = [...requiredBoundaries];
   error.sandboxBackend = null;
-  error.sandboxCandidateBackend = null;
+  error.sandboxCandidateBackend =
+    _deps.platform === "linux" ? "linux-bwrap-workspace" : null;
   return error;
 }
 
+function canonicalSandboxBinding(workspaceCwd, executionCwd) {
+  try {
+    if (
+      typeof workspaceCwd !== "string" ||
+      !isAbsolute(workspaceCwd) ||
+      typeof executionCwd !== "string"
+    ) {
+      throw new Error("sandbox paths must be absolute");
+    }
+    const workspaceRoot = realpathSync.native(resolve(workspaceCwd));
+    const workingDirectory = realpathSync.native(resolve(executionCwd));
+    if (
+      !statSync(workspaceRoot).isDirectory() ||
+      !statSync(workingDirectory).isDirectory()
+    ) {
+      throw new Error("sandbox paths must be directories");
+    }
+    const rel = relative(workspaceRoot, workingDirectory);
+    if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+      throw new Error("execution cwd escapes workspace");
+    }
+    return { workspaceRoot, workingDirectory };
+  } catch (cause) {
+    const error = createSandboxError(
+      "ERR_BACKGROUND_TASK_SANDBOX_BINDING_INVALID",
+      "background_sandbox_binding_invalid",
+      "Background task sandbox workspace/cwd binding is invalid.",
+    );
+    error.cause = cause;
+    throw error;
+  }
+}
+
+function sameBoundaries(left, right) {
+  const normalizedLeft = Array.isArray(left) ? [...left].sort() : null;
+  const normalizedRight = Array.isArray(right) ? [...right].sort() : null;
+  return (
+    normalizedLeft &&
+    normalizedRight &&
+    normalizedLeft.length === normalizedRight.length &&
+    normalizedLeft.every((value, index) => value === normalizedRight[index])
+  );
+}
+
+function strongWorkerEnvironment(taskId) {
+  const blocked = new Set([
+    "BASH_ENV",
+    "CC_TASK_ID",
+    "ELECTRON_RUN_AS_NODE",
+    "ENV",
+    "GCONV_PATH",
+    "OPENSSL_CONF",
+    "RUBYOPT",
+  ]);
+  const blockedPrefixes = ["DYLD_", "LD_", "NODE_", "PYTHON"];
+  return Object.fromEntries([
+    ...Object.entries(process.env).filter(([key, value]) => {
+      const normalizedKey = key.toUpperCase();
+      return (
+        value != null &&
+        !blocked.has(normalizedKey) &&
+        !blockedPrefixes.some((prefix) => normalizedKey.startsWith(prefix))
+      );
+    }),
+    ["CC_TASK_ID", taskId],
+  ]);
+}
+
 export class BackgroundTaskManager extends EventEmitter {
   constructor(options = {}) {
     super();
@@ -123,14 +200,17 @@ export class BackgroundTaskManager extends EventEmitter {
     }
 
     const cwd = spec.cwd || process.cwd();
-    this._assertSandboxSupported(cwd);
+    const sandboxPolicy = this._resolvePinnedSandboxPolicy(cwd);
+    const sandboxBinding = sandboxPolicy
+      ? canonicalSandboxBinding(this._policyCwd, cwd)
+      : null;
 
     const id = `task-${Date.now()}-${createHash("sha256").update(Math.random().toString()).digest("hex").slice(0, 6)}`;
     const task = {
       id,
       type: spec.type || "shell",
       command: spec.command,
-      cwd,
+      cwd: sandboxBinding?.workingDirectory || cwd,
       description: spec.description || spec.command,
       status: TaskStatus.PENDING,
       createdAt: Date.now(),
@@ -145,6 +225,10 @@ export class BackgroundTaskManager extends EventEmitter {
       recoverySourceStatus: null,
       ownerNodeId: spec.ownerNodeId || this.nodeId,
       recoveryDecision: null,
+      sandboxWorkspaceCwd: sandboxBinding?.workspaceRoot || null,
+      sandboxRequiredBoundaries: sandboxPolicy
+        ? [...sandboxPolicy.requiredBoundaries].sort()
+        : null,
       _seq: ++this._createSeq,
     };
 
@@ -164,7 +248,34 @@ export class BackgroundTaskManager extends EventEmitter {
       throw new Error(`Task ${taskId} is not pending (status: ${task.status})`);
     }
 
-    this._assertSandboxSupported(task.cwd);
+    const sandboxPolicy = this._resolvePinnedSandboxPolicy(task.cwd);
+    const pinnedBoundaries = task.sandboxRequiredBoundaries;
+    if (
+      Boolean(sandboxPolicy) !== Array.isArray(pinnedBoundaries) ||
+      (sandboxPolicy &&
+        !sameBoundaries(sandboxPolicy.requiredBoundaries, pinnedBoundaries))
+    ) {
+      throw createSandboxError(
+        "ERR_BACKGROUND_TASK_SANDBOX_POLICY_CHANGED",
+        "background_sandbox_policy_changed",
+        "Background task sandbox policy changed after creation; recreate the task.",
+        sandboxPolicy?.requiredBoundaries || pinnedBoundaries || [],
+      );
+    }
+    if (sandboxPolicy) {
+      const currentBinding = canonicalSandboxBinding(this._policyCwd, task.cwd);
+      if (
+        currentBinding.workspaceRoot !== task.sandboxWorkspaceCwd ||
+        currentBinding.workingDirectory !== task.cwd
+      ) {
+        throw createSandboxError(
+          "ERR_BACKGROUND_TASK_SANDBOX_BINDING_CHANGED",
+          "background_sandbox_binding_changed",
+          "Background task sandbox workspace/cwd identity changed after creation; recreate the task.",
+          pinnedBoundaries,
+        );
+      }
+    }
 
     task.status = TaskStatus.RUNNING;
     task.startedAt = Date.now();
@@ -179,11 +290,21 @@ export class BackgroundTaskManager extends EventEmitter {
     );
     const child = _deps.spawn(
       process.execPath,
-      [...process.execArgv, workerPath, task.command, task.cwd, task.type],
+      [
+        ...(sandboxPolicy ? [] : process.execArgv),
+        workerPath,
+        task.command,
+        task.cwd,
+        task.type,
+        task.sandboxWorkspaceCwd || "",
+        JSON.stringify(task.sandboxRequiredBoundaries || []),
+      ],
       {
         cwd: task.cwd,
         stdio: ["pipe", "pipe", "pipe", "ipc"],
-        env: { ...process.env, CC_TASK_ID: taskId },
+        env: sandboxPolicy
+          ? strongWorkerEnvironment(taskId)
+          : { ...process.env, CC_TASK_ID: taskId },
         origin: "background-task:worker",
         policy: "allow",
         scope: "background-task",
@@ -199,6 +320,9 @@ export class BackgroundTaskManager extends EventEmitter {
       } else if (msg.type === "result") {
         this._complete(taskId, TaskStatus.COMPLETED, msg.data, null);
       } else if (msg.type === "error") {
+        task.errorCode = msg.code || null;
+        task.sandboxReason = msg.sandboxReason || null;
+        task.sandboxFailClosed = msg.sandboxFailClosed === true;
         this._complete(taskId, TaskStatus.FAILED, null, msg.error);
       }
     });
@@ -240,7 +364,7 @@ export class BackgroundTaskManager extends EventEmitter {
     return task;
   }
 
-  _assertSandboxSupported(executionCwd) {
+  _resolvePinnedSandboxPolicy(executionCwd) {
     if (!this._resolveSandboxPolicy) return;
     const sandboxPolicy = validatePinnedSandboxPolicy(
       this._resolveSandboxPolicy({
@@ -248,9 +372,15 @@ export class BackgroundTaskManager extends EventEmitter {
         executionCwd,
       }),
     );
-    if (sandboxPolicy) {
-      throw createUnsupportedSandboxError(sandboxPolicy);
+    if (sandboxPolicy && _deps.platform !== "linux") {
+      throw createSandboxError(
+        "ERR_BACKGROUND_TASK_SANDBOX_UNSUPPORTED",
+        "background_platform_backend_unavailable",
+        "Background task strong sandbox execution is only available on Linux.",
+        sandboxPolicy.requiredBoundaries,
+      );
     }
+    return sandboxPolicy;
   }
 
   get(taskId) {

package/src/harness/background-task-worker.js

@@ -5,24 +5,27 @@
  * Sends messages to parent: { type: "heartbeat"|"result"|"error", ... }
  */
 
-import executionBroker from "../lib/process-execution-broker/index.js";
+import { executeBackgroundTaskCommand } from "./background-task-command-runner.js";
 
-const [command, cwd, type] = process.argv.slice(2);
+const [
+  command,
+  cwd,
+  type,
+  sandboxWorkspaceCwd = "",
+  sandboxRequiredBoundaries = "",
+] = process.argv.slice(2);
 
 const heartbeat = setInterval(() => {
   if (process.send) process.send({ type: "heartbeat" });
 }, 5000);
 
 try {
-  const result = executionBroker.execSync(command, {
-    cwd: cwd || process.cwd(),
-    encoding: "utf-8",
-    timeout: 300000,
-    maxBuffer: 10 * 1024 * 1024,
-    origin: `background-task:command:${type || "unknown"}`,
-    policy: "allow",
-    scope: "background-task",
-    shell: true,
+  const result = await executeBackgroundTaskCommand({
+    command,
+    cwd,
+    type,
+    workspaceCwd: sandboxWorkspaceCwd,
+    requiredBoundaries: sandboxRequiredBoundaries,
   });
 
   if (process.send) {
@@ -33,6 +36,9 @@ try {
     process.send({
       type: "error",
       error: err.stderr || err.message || String(err),
+      code: err.code || null,
+      sandboxReason: err.sandboxReason || null,
+      sandboxFailClosed: err.sandboxFailClosed === true,
     });
   }
   process.exitCode = 1;

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

@@ -164,22 +164,73 @@ export function appendToolCall(sessionId, toolName, args) {
 
 /**
  * Compact tool-call record for usage attribution (用量归因): tool name +
- * error flag (+ optional skill and plugin/version hints) — deliberately NOT
- * the args, which can carry whole file bodies (write_file content) and would
- * bloat the transcript. Written at tool-result time by the agent drivers so
- * `cc session usage --by tool|mcp|plugin` and `cc insights` can aggregate tool
- * use for any persisted session.
+ * error flag (+ optional skill, plugin/version, and bounded observed duration)
+ * — deliberately NOT the args, which can carry whole file bodies (write_file
+ * content) and would bloat the transcript. Written at tool-result time by the
+ * agent drivers so `cc session usage --by tool|mcp|plugin` and `cc insights`
+ * can aggregate tool use for any persisted session.
  */
 export function appendToolCallCompact(
   sessionId,
-  { tool, isError, skill, plugin, pluginVersion } = {},
+  { tool, isError, skill, plugin, pluginVersion, durationMs } = {},
 ) {
+  const duration = normalizeCompactDuration(durationMs);
   appendEvent(sessionId, "tool_call", {
     tool: tool || "?",
     is_error: Boolean(isError),
     ...(skill ? { skill: String(skill) } : {}),
     ...(plugin ? { plugin: String(plugin) } : {}),
     ...(pluginVersion ? { plugin_version: String(pluginVersion) } : {}),
+    ...(duration !== null ? { duration_ms: duration } : {}),
+  });
+}
+
+/** Hard cap for one observed failed LLM/tool attempt (seven days). */
+export const MAX_COMPACT_DURATION_MS = 7 * 24 * 60 * 60 * 1000;
+
+function normalizeCompactDuration(value) {
+  if (value === null || value === undefined || value === "") return null;
+  const number = Number(value);
+  if (!Number.isFinite(number) || number < 0) return null;
+  return Math.min(MAX_COMPACT_DURATION_MS, Math.round(number));
+}
+
+/**
+ * Persist one automatic LLM stream retry without raw errors, prompts, URLs, or
+ * credentials. Provider/model are bounded identity labels; reason is a closed
+ * vocabulary produced by classifyStreamRetryReason().
+ */
+export function appendLlmRetryCompact(
+  sessionId,
+  { attempt, durationMs, provider, model, reason } = {},
+) {
+  const attemptNumber = Math.max(
+    1,
+    Math.min(15, Math.trunc(Number(attempt) || 1)),
+  );
+  const duration = normalizeCompactDuration(durationMs);
+  const cleanLabel = (value, max) => {
+    if (typeof value !== "string") return null;
+    const clean = value.replace(/\p{Cc}/gu, "").trim();
+    return clean ? clean.slice(0, max) : null;
+  };
+  const allowedReasons = new Set([
+    "timeout",
+    "dns",
+    "connection_refused",
+    "network_unreachable",
+    "connection_reset",
+    "unknown",
+  ]);
+  const cleanReason = allowedReasons.has(reason) ? reason : "unknown";
+  const cleanProvider = cleanLabel(provider, 64);
+  const cleanModel = cleanLabel(model, 128);
+  appendEvent(sessionId, "llm_retry", {
+    attempt: attemptNumber,
+    duration_ms: duration ?? 0,
+    reason: cleanReason,
+    ...(cleanProvider ? { provider: cleanProvider } : {}),
+    ...(cleanModel ? { model: cleanModel } : {}),
   });
 }
 

package/src/harness/mcp-client.js

@@ -14,6 +14,7 @@ import { EventEmitter } from "events";
 import { pathToFileURL } from "url";
 import { safeJsonParse } from "../lib/safe-json.js";
 import { EventRuntimeProducer } from "../lib/event-runtime-producer.js";
+import { resolvePluginWorkspaceAuthority } from "../lib/plugin-runtime/sandbox-policy.js";
 
 /**
  * Injectable dependencies — overridable from tests.
@@ -62,8 +63,7 @@ const URL_ELICITATION_REQUIRED = -32042;
 function supportsUrlElicitationVersion(version) {
   const normalized = String(version || "");
   return (
-    /^\d{4}-\d{2}-\d{2}$/.test(normalized) &&
-    normalized >= MCP_PROTOCOL_VERSION
+    /^\d{4}-\d{2}-\d{2}$/.test(normalized) && normalized >= MCP_PROTOCOL_VERSION
   );
 }
 
@@ -130,9 +130,7 @@ export function normalizeMcpElicitationRequest(
 
   const elicitationId = String(params.elicitationId || "").trim();
   if (!elicitationId) {
-    const error = new Error(
-      "URL mode MCP elicitation requires elicitationId",
-    );
+    const error = new Error("URL mode MCP elicitation requires elicitationId");
     error.code = "CC_MCP_ELICITATION_INVALID";
     throw error;
   }
@@ -267,10 +265,14 @@ export class MCPClient extends EventEmitter {
       Number(options.maxConcurrentElicitations) > 0
         ? Math.min(128, Number(options.maxConcurrentElicitations))
         : 32;
-    this._protocolVersion =
-      String(options.protocolVersion || MCP_PROTOCOL_VERSION);
+    this._protocolVersion = String(
+      options.protocolVersion || MCP_PROTOCOL_VERSION,
+    );
     this._runtimeProducer = options.eventRuntimeStore
-      ? new EventRuntimeProducer({ store: options.eventRuntimeStore, emitter: this })
+      ? new EventRuntimeProducer({
+          store: options.eventRuntimeStore,
+          emitter: this,
+        })
       : null;
   }
 
@@ -279,11 +281,11 @@ export class MCPClient extends EventEmitter {
     const sessionId = options.sessionId;
     if (sessionId != null && sessionId !== "") {
       const key = String(sessionId);
-      if (typeof handler === "function") this._elicitationHandlers.set(key, handler);
+      if (typeof handler === "function")
+        this._elicitationHandlers.set(key, handler);
       else this._elicitationHandlers.delete(key);
     } else {
-      this._elicitationHandler =
-        typeof handler === "function" ? handler : null;
+      this._elicitationHandler = typeof handler === "function" ? handler : null;
     }
     if (Number(options.timeoutMs) > 0) {
       this._elicitationTimeoutMs = Number(options.timeoutMs);
@@ -389,8 +391,9 @@ export class MCPClient extends EventEmitter {
       requestId,
       params,
     );
-    const negotiatedVersion =
-      this.servers.get(String(serverName))?.protocolVersion;
+    const negotiatedVersion = this.servers.get(
+      String(serverName),
+    )?.protocolVersion;
     if (
       request.mode === "url" &&
       negotiatedVersion &&
@@ -431,10 +434,7 @@ export class MCPClient extends EventEmitter {
           direct !== undefined &&
           String(direct?.action || "").toLowerCase() !== "defer"
         ) {
-          const response = this._normalizeElicitationResponse(
-            direct,
-            request,
-          );
+          const response = this._normalizeElicitationResponse(direct, request);
           this._settleUrlElicitation(request, response);
           try {
             this._runtimeProducer?.store.acknowledgeInbox(
@@ -504,7 +504,8 @@ export class MCPClient extends EventEmitter {
       });
       this.emit("elicitation-request", {
         ...request,
-        respond: (response) => this.respondElicitation(serverName, requestId, response),
+        respond: (response) =>
+          this.respondElicitation(serverName, requestId, response),
         cancel: () => this.cancelElicitation(serverName, requestId),
       });
     });
@@ -515,9 +516,7 @@ export class MCPClient extends EventEmitter {
     if (!id) return;
     const existing = this._urlElicitations.get(id);
     if (existing && existing.server !== request.server) {
-      throw new Error(
-        `MCP URL elicitation id collision across servers: ${id}`,
-      );
+      throw new Error(`MCP URL elicitation id collision across servers: ${id}`);
     }
     if (existing && existing.request?.url !== request.url) {
       throw new Error(
@@ -544,7 +543,9 @@ export class MCPClient extends EventEmitter {
     const entry = this._urlElicitations.get(request.elicitationId);
     if (!entry || entry.status === "completed") return;
     entry.status =
-      response?.action === "accept" ? "accepted" : response?.action || "decline";
+      response?.action === "accept"
+        ? "accepted"
+        : response?.action || "decline";
     if (entry.status === "accepted" && entry.completionNotified) {
       this._completeUrlElicitation(entry);
     }
@@ -757,7 +758,26 @@ export class MCPClient extends EventEmitter {
             `stdio transport requires a command (server "${name}")`,
           );
         }
-        const proc = _deps.spawn(config.command, config.args || [], {
+        const isPlugin = config.origin === "plugin:mcp";
+        const pluginWorkspaceRoot = isPlugin
+          ? resolvePluginWorkspaceAuthority(config.pluginWorkspaceAuthority, {
+              origin: config.origin,
+              pluginId: config.pluginId,
+              pluginVersion: config.pluginVersion,
+              pluginSource: config.pluginSource,
+            })
+          : null;
+        if (
+          isPlugin &&
+          config.sandboxPolicy?.requiredBoundaries?.length > 0 &&
+          !pluginWorkspaceRoot
+        ) {
+          throw new Error(
+            `plugin MCP server "${name}" is missing its trusted workspace authority`,
+          );
+        }
+        const spawnOptions = {
+          cwd: pluginWorkspaceRoot || process.cwd(),
           stdio: ["pipe", "pipe", "pipe"],
           // process.env < agent identity (CLAUDECODE / session id) < the
           // server's own config.env, so an explicit per-server override wins.
@@ -776,6 +796,19 @@ export class MCPClient extends EventEmitter {
           ...(config.sandboxPolicy
             ? { sandboxPolicy: config.sandboxPolicy }
             : {}),
+        };
+        const sandboxExecutionContract =
+          !isPlugin || pluginWorkspaceRoot
+            ? executionBroker.issueLinuxWorkspaceSandboxExecutionContract(
+                config.command,
+                config.args || [],
+                spawnOptions,
+                pluginWorkspaceRoot || process.cwd(),
+              )
+            : null;
+        const proc = _deps.spawn(config.command, config.args || [], {
+          ...spawnOptions,
+          ...(sandboxExecutionContract ? { sandboxExecutionContract } : {}),
         });
 
         entry.process = proc;
@@ -1113,7 +1146,8 @@ export class MCPClient extends EventEmitter {
       } catch {
         return false;
       }
-      if (request.mode !== "url" || ids.has(request.elicitationId)) return false;
+      if (request.mode !== "url" || ids.has(request.elicitationId))
+        return false;
       ids.add(request.elicitationId);
       normalized.push(request);
     }
@@ -1392,10 +1426,7 @@ export class MCPClient extends EventEmitter {
     entry._httpMessageStream = stream;
     stream.promise = (async () => {
       try {
-        while (
-          !stream.stopped &&
-          this.servers.get(serverName) === entry
-        ) {
+        while (!stream.stopped && this.servers.get(serverName) === entry) {
           stream.controller =
             typeof AbortController === "function"
               ? new AbortController()
@@ -1427,9 +1458,7 @@ export class MCPClient extends EventEmitter {
               );
             }
             const contentType = response.headers?.get
-              ? String(
-                  response.headers.get("content-type") || "",
-                ).toLowerCase()
+              ? String(response.headers.get("content-type") || "").toLowerCase()
               : "";
             if (!contentType.includes("text/event-stream")) return;
             const cap = Number.isFinite(entry.config?.maxBufferChars)
@@ -1438,8 +1467,7 @@ export class MCPClient extends EventEmitter {
             await _consumeSseMessageStream(response, {
               cap,
               stream,
-              onMessage: (message) =>
-                this._handleMessage(serverName, message),
+              onMessage: (message) => this._handleMessage(serverName, message),
             });
           } catch (error) {
             if (stream.stopped || stream.controller?.signal.aborted) return;
@@ -1564,11 +1592,8 @@ export class MCPClient extends EventEmitter {
 
       let envelope;
       if (contentType.includes("text/event-stream")) {
-        envelope = await _extractSseResponse(
-          response,
-          id,
-          cap,
-          (message) => this._handleMessage(serverName, message),
+        envelope = await _extractSseResponse(response, id, cap, (message) =>
+          this._handleMessage(serverName, message),
         );
       } else {
         const text = await _readBodyCapped(response, cap);
@@ -1813,8 +1838,7 @@ export class MCPClient extends EventEmitter {
         ...(entry.httpSessionId
           ? { "Mcp-Session-Id": entry.httpSessionId }
           : {}),
-        "MCP-Protocol-Version":
-          entry.protocolVersion || this._protocolVersion,
+        "MCP-Protocol-Version": entry.protocolVersion || this._protocolVersion,
       };
       try {
         const pending = _deps.fetch(entry.httpUrl, {
@@ -1986,9 +2010,7 @@ async function _consumeSseMessageStream(
       if (done) break;
       buffer += decoder.decode(value, { stream: true });
       if (cap > 0 && buffer.length > cap) {
-        throw new Error(
-          `MCP HTTP SSE event exceeded the ${cap}-char cap`,
-        );
+        throw new Error(`MCP HTTP SSE event exceeded the ${cap}-char cap`);
       }
       let boundary;
       while ((boundary = buffer.search(/\r?\n\r?\n/)) >= 0) {

package/src/lib/agent-batch.js

@@ -94,7 +94,10 @@ export async function runBatch(opts, deps) {
     try {
       worktreePath = createWorktree(unit.key, branch);
       onEvent({ type: "unit:start", key: unit.key, branch });
-      await runAgent(unit.prompt, worktreePath);
+      await runAgent(unit.prompt, worktreePath, {
+        key: unit.key,
+        branch,
+      });
 
       const stat = diffStat(worktreePath);
       record.filesChanged = stat.filesChanged;

package/src/lib/agent-team/team-worktree.js

@@ -126,6 +126,8 @@ export class TeamWorktreeCoordinator {
       sparsePaths: options.sparsePaths ?? null,
       symlinkDirectories: options.symlinkDirectories ?? null,
     };
+    this._onWorktree =
+      typeof options.onWorktree === "function" ? options.onWorktree : null;
   }
 
   isGitRepo() {
@@ -173,6 +175,7 @@ export class TeamWorktreeCoordinator {
         wtOptions,
       );
       this._created.set(key, { branch, path: worktreePath, committed: false });
+      this._onWorktree?.({ key, branch, path: worktreePath, holder });
       if (typeof runInWorktree === "function") {
         await runInWorktree({ key, task, holder, cwd: worktreePath });
       } else {