@livx.cc/agentx 0.94.38 → 0.95.2

package/dist/index.js

@@ -1588,7 +1588,7 @@ function makeRealShellTool(options) {
           proc.stderr?.on("data", collect);
           proc.on("error", (err) => {
             if (err?.name === "AbortError" || ctl.signal.aborted) return finish(reasonFor(timedOut, timeoutMs, clean(out)));
-            log4.debug("shell spawn error", err);
+            log5.debug("shell spawn error", err);
             finish(`[exit 1] ${err?.message ?? err}${out ? "\n" + clean(out) : ""}`);
           });
           proc.on("close", (code) => {
@@ -1650,7 +1650,7 @@ ${clean(out) || "(no output yet)"}`;
     }
   ];
 }
-var log4, clean, DETACHED, SECRET_ENV_RE, _spawn, ShellJobRegistry, NO_JOB2;
+var log5, clean, DETACHED, SECRET_ENV_RE, _spawn, ShellJobRegistry, NO_JOB2;
 var init_tools_shell = __esm({
   "src/tools.shell.ts"() {
     "use strict";
@@ -1658,7 +1658,7 @@ var init_tools_shell = __esm({
     init_redact();
     init_logging();
     init_shell_sandbox();
-    log4 = forComponent("shell");
+    log5 = forComponent("shell");
     clean = (s) => truncateOutput(redactSecrets(s.replace(/\n+$/, "")));
     DETACHED = { stdio: ["ignore", "pipe", "pipe"], detached: true };
     SECRET_ENV_RE = /(_API_KEY|_TOKEN|_SECRET|_PASSWORD|_PRIVATE_KEY|^AWS_|^GITHUB_TOKEN$|^OPENAI_|^ANTHROPIC_|^GOOGLE_|^GEMINI_|^GROQ_|^NPM_TOKEN$)/i;
@@ -2435,7 +2435,163 @@ ${sections.join("\n\n---\n\n")}`;
 
 // src/subagent.ts
 init_tools();
+import { mkdirSync as mkdirSync2, writeFileSync } from "fs";
+import { join as join3 } from "path";
 init_OverlayFilesystem();
+
+// src/worktree.ts
+import { spawnSync } from "child_process";
+import { symlinkSync, mkdirSync, statSync, readFileSync, rmSync } from "fs";
+import { join } from "path";
+var VALID_SEGMENT = /^[a-zA-Z0-9._-]+$/;
+var MAX_SLUG_LENGTH = 64;
+var GIT_NO_PROMPT_ENV = { GIT_TERMINAL_PROMPT: "0", GIT_ASKPASS: "" };
+function validateWorktreeSlug(slug2) {
+  if (!slug2) throw new Error("worktree slug must not be empty");
+  if (slug2.length > MAX_SLUG_LENGTH) throw new Error(`worktree slug must be \u2264${MAX_SLUG_LENGTH} chars (got ${slug2.length})`);
+  for (const seg of slug2.split("/")) {
+    if (seg === "." || seg === "..") throw new Error(`worktree slug must not contain "." or ".." segments`);
+    if (!VALID_SEGMENT.test(seg)) throw new Error(`worktree slug segment "${seg}" contains invalid characters (allowed: a-z A-Z 0-9 . _ -)`);
+  }
+}
+function flattenSlug(slug2) {
+  return slug2.replaceAll("/", "+");
+}
+function worktreeBranchName(slug2) {
+  return `worktree-${flattenSlug(slug2)}`;
+}
+function worktreesDir(repoRoot) {
+  return join(repoRoot, ".claude", "worktrees");
+}
+function worktreePathFor(repoRoot, slug2) {
+  return join(worktreesDir(repoRoot), flattenSlug(slug2));
+}
+function git(args, cwd) {
+  const r = spawnSync("git", args, {
+    cwd,
+    stdio: ["ignore", "pipe", "pipe"],
+    env: { ...process.env, ...GIT_NO_PROMPT_ENV }
+  });
+  return { ok: r.status === 0, stdout: (r.stdout ?? "").toString().trim(), stderr: (r.stderr ?? "").toString().trim() };
+}
+function findGitRoot(from) {
+  const r = git(["rev-parse", "--show-toplevel"], from);
+  return r.ok ? r.stdout : null;
+}
+function readWorktreeHead(worktreePath) {
+  try {
+    const gitFile = readFileSync(join(worktreePath, ".git"), "utf-8").trim();
+    const m = gitFile.match(/^gitdir:\s*(.+)$/);
+    if (!m) return null;
+    const headPath = join(m[1], "HEAD");
+    const head = readFileSync(headPath, "utf-8").trim();
+    const refMatch = head.match(/^ref:\s*(.+)$/);
+    if (!refMatch) return head.length === 40 ? head : null;
+    const refPath = join(m[1], "..", refMatch[1]);
+    try {
+      return readFileSync(refPath, "utf-8").trim();
+    } catch {
+    }
+    const r = git(["rev-parse", "HEAD"], worktreePath);
+    return r.ok ? r.stdout : null;
+  } catch {
+    return null;
+  }
+}
+function getOrCreateWorktree(repoRoot, slug2) {
+  validateWorktreeSlug(slug2);
+  const worktreePath = worktreePathFor(repoRoot, slug2);
+  const branch = worktreeBranchName(slug2);
+  const existingHead = readWorktreeHead(worktreePath);
+  if (existingHead) return { worktreePath, branch, headCommit: existingHead, existed: true };
+  mkdirSync(worktreesDir(repoRoot), { recursive: true });
+  const defaultBranch = git(["symbolic-ref", "--short", "refs/remotes/origin/HEAD"], repoRoot);
+  let baseBranch = defaultBranch.ok ? defaultBranch.stdout.replace(/^origin\//, "") : "HEAD";
+  const originRef = `origin/${baseBranch}`;
+  const hasOrigin = git(["rev-parse", "--verify", originRef], repoRoot);
+  if (!hasOrigin.ok) {
+    const fetched = git(["fetch", "origin", baseBranch], repoRoot);
+    if (!fetched.ok) baseBranch = "HEAD";
+  }
+  const base = baseBranch === "HEAD" ? "HEAD" : originRef;
+  const r = git(["worktree", "add", "-B", branch, worktreePath, base], repoRoot);
+  if (!r.ok) throw new Error(`failed to create worktree: ${r.stderr}`);
+  const headSha = git(["rev-parse", "HEAD"], worktreePath);
+  symlinkDirs(repoRoot, worktreePath, ["node_modules", ".bun"]);
+  return { worktreePath, branch, headCommit: headSha.stdout, existed: false, baseBranch };
+}
+function symlinkDirs(repoRoot, worktreePath, dirs) {
+  for (const dir of dirs) {
+    const src = join(repoRoot, dir);
+    const dst = join(worktreePath, dir);
+    try {
+      statSync(src);
+    } catch {
+      continue;
+    }
+    try {
+      symlinkSync(src, dst, "dir");
+    } catch (e) {
+      if (e?.code !== "EEXIST") console.error(`[worktree] symlink ${dir}: ${e?.message ?? e}`);
+    }
+  }
+}
+function cleanupWorktree(repoRoot, slug2, opts) {
+  validateWorktreeSlug(slug2);
+  const worktreePath = worktreePathFor(repoRoot, slug2);
+  const branch = worktreeBranchName(slug2);
+  try {
+    statSync(worktreePath);
+  } catch {
+    return { removed: false, reason: "not found" };
+  }
+  if (!opts?.force) {
+    const status = git(["status", "--porcelain", "-uno"], worktreePath);
+    if (status.ok && status.stdout) return { removed: false, reason: "uncommitted changes" };
+  }
+  for (const dir of ["node_modules", ".bun"]) {
+    try {
+      rmSync(join(worktreePath, dir));
+    } catch {
+    }
+  }
+  const rm = git(["worktree", "remove", "--force", worktreePath], repoRoot);
+  if (!rm.ok) return { removed: false, reason: rm.stderr };
+  git(["branch", "-D", branch], repoRoot);
+  return { removed: true };
+}
+var _session = null;
+function getWorktreeSession() {
+  return _session;
+}
+function enterWorktree(slug2, cwd) {
+  const repoRoot = findGitRoot(cwd);
+  if (!repoRoot) throw new Error("--worktree requires a git repository");
+  const info = getOrCreateWorktree(repoRoot, slug2);
+  process.chdir(info.worktreePath);
+  _session = {
+    originalCwd: cwd,
+    worktreePath: info.worktreePath,
+    slug: slug2,
+    branch: info.branch,
+    headCommit: info.headCommit
+  };
+  return _session;
+}
+function exitWorktree() {
+  if (!_session) return null;
+  const repoRoot = findGitRoot(_session.originalCwd);
+  if (!repoRoot) return null;
+  process.chdir(_session.originalCwd);
+  const result = cleanupWorktree(repoRoot, _session.slug);
+  _session = null;
+  return result;
+}
+
+// src/subagent.ts
+init_NodeDiskFilesystem();
+init_logging();
+var log3 = forComponent("subagent");
 async function boundedPool(items, limit, fn) {
   const out = new Array(items.length);
   let next = 0;
@@ -2448,13 +2604,86 @@ async function boundedPool(items, limit, fn) {
   await Promise.all(Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, worker));
   return out;
 }
+function sanitizeSlug(raw) {
+  return raw.replace(/[^a-zA-Z0-9._-]/g, "-").replace(/-+/g, "-").slice(0, 40);
+}
+function createWorktreeFs(cwd, label, index) {
+  const repoRoot = findGitRoot(cwd);
+  if (!repoRoot) return 'isolation: "worktree" requires a git repository';
+  const slug2 = `sub-${index}-${sanitizeSlug(label)}`;
+  try {
+    const info = getOrCreateWorktree(repoRoot, slug2);
+    return { repoRoot, slug: slug2, worktreePath: info.worktreePath, branch: info.branch };
+  } catch (e) {
+    return `worktree creation failed: ${e instanceof Error ? e.message : String(e)}`;
+  }
+}
+function releaseWorktree(handle) {
+  return cleanupWorktree(handle.repoRoot, handle.slug, { force: true });
+}
+function worktreePromptPrefix(branch) {
+  return `You are running in an isolated git worktree on branch "${branch}". When you finish making changes, commit them with a clear message before replying with your summary. Your worktree will be removed after you finish \u2014 only committed work survives (on the branch).
+
+`;
+}
+var traceSeq = 0;
+function traceFileFor(dir, label, depth) {
+  try {
+    mkdirSync2(dir, { recursive: true });
+    const id = `${Date.now().toString(36)}-${(traceSeq++).toString(36)}`;
+    return join3(dir, `${id}-d${depth}-${sanitizeSlug(label) || "sub"}.json`);
+  } catch (e) {
+    log3.warn(`subagent trace dir unavailable (${dir}) \u2014 running without a trace: ${e instanceof Error ? e.message : String(e)}`);
+    return void 0;
+  }
+}
+function flushTrace(file, meta, messages, status) {
+  try {
+    writeFileSync(file, JSON.stringify({ ...meta, status, updated: Date.now(), messages }, null, 2));
+  } catch (e) {
+    log3.warn(`subagent trace flush failed (${file}): ${e instanceof Error ? e.message : String(e)}`);
+  }
+}
+function installTrace(child, file, meta) {
+  const prev = child.options.host;
+  child.options.host = {
+    ...prev,
+    notify: (e) => {
+      if (e.kind === "turn_start") flushTrace(file, meta, child.transcript, "running");
+      prev?.notify?.(e);
+    }
+  };
+}
+function abortHint(label, res, file) {
+  const last = (res.text || "").trim().slice(0, 500);
+  const lines = [
+    `[sub-task '${label}' did NOT finish \u2014 ${res.finishReason} after ${res.steps} step(s). Treat its work as INCOMPLETE.]`,
+    last ? `Progress so far: ${last}` : "It produced no summary before stopping."
+  ];
+  if (file) lines.push(`Full transcript (every step it took): ${file} \u2014 Read it to see what was actually done.`);
+  lines.push("Decide: ignore it, re-delegate a fresh Task that continues from the trace, or start over. Do NOT assume the sub-task completed.");
+  return lines.join("\n");
+}
+async function runChildTraced(args) {
+  const { opts, label, agentType, prompt } = args;
+  if (args.signal) args.childOpts.signal = args.signal;
+  const file = opts.traceDir ? traceFileFor(opts.traceDir, label, args.childDepth) : void 0;
+  const meta = { label, agentType, prompt };
+  const child = new Agent(args.childOpts);
+  if (file) installTrace(child, file, meta);
+  const res = await child.run(prompt);
+  if (file) flushTrace(file, meta, child.transcript, res.finishReason);
+  const result = res.finishReason === "stop" ? res.text || `(child '${label}' finished with no summary; finishReason=${res.finishReason})` : abortHint(label, res, file);
+  await opts.hooks?.onSubagentStop?.(result, { label, agentType });
+  return { res, result };
+}
 function childOptionsFor(opts, fs, depth, maxDepth, agentType) {
   let def;
   if (agentType) {
     def = (opts.agents ?? []).find((a) => a.name === agentType);
     if (!def) return `no subagent type '${agentType}'. Available: ${(opts.agents ?? []).map((a) => a.name).join(", ") || "(none defined)"}`;
   }
-  const childOpts = { ai: opts.ai, fs, model: def?.model ?? opts.model, subagents: true, depth: depth + 1, maxDepth };
+  const childOpts = { ai: opts.ai, fs, model: def?.model ?? opts.model, subagents: true, depth: depth + 1, maxDepth, traceDir: opts.traceDir };
   if (opts.maxSteps != null) childOpts.maxSteps = opts.maxSteps;
   if (def?.systemPrompt) childOpts.systemPrompt = def.systemPrompt;
   if (def?.tools?.length) {
@@ -2471,7 +2700,7 @@ function makeTaskTool(opts) {
   const maxDepth = opts.maxDepth ?? 2;
   return {
     name: "Task",
-    description: "Delegate a self-contained sub-task to a child agent over the same filesystem. It runs autonomously with its own step budget and returns a concise summary \u2014 use to isolate context-heavy work (broad search, a scoped refactor). Provide a short `description` and a full `prompt`. Set `background: true` to run it detached (returns a job id to poll with JobOutput while you keep working); its file edits are overlay-isolated and commit when it finishes.",
+    description: 'Delegate a self-contained sub-task to a child agent over the same filesystem. It runs autonomously with its own step budget and returns a concise summary \u2014 use to isolate context-heavy work (broad search, a scoped refactor). Provide a short `description` and a full `prompt`. If it is interrupted or fails, the result is a STATUS HINT with a pointer to its full transcript (Read it to recover what it did, then decide whether to continue or restart) \u2014 do not assume an incomplete sub-task succeeded. Set `background: true` to run it detached (returns a job id to poll with JobOutput while you keep working); its file edits are overlay-isolated and commit when it finishes. Set `isolation: "worktree"` to run in a real git worktree (needed when the child uses real shell commands that must see/modify actual files) \u2014 slower (~200ms setup), auto-cleaned if no changes.',
     parameters: {
       type: "object",
       required: ["description", "prompt"],
@@ -2479,36 +2708,83 @@ function makeTaskTool(opts) {
         description: { type: "string", description: "a short (3-5 word) label for the sub-task" },
         prompt: { type: "string", description: "the full instructions the child agent should carry out" },
         agentType: { type: "string", description: "optional named subagent type (its persona, model, and scoped tools) \u2014 see the catalog" },
-        background: { type: "boolean", description: "run detached (overlay-isolated, commits on finish); returns a job id to poll with JobOutput instead of blocking" }
+        background: { type: "boolean", description: "run detached (overlay-isolated, commits on finish); returns a job id to poll with JobOutput instead of blocking" },
+        isolation: { type: "string", enum: ["overlay", "worktree"], description: 'isolation mode: "overlay" (default, VFS layer) or "worktree" (real git worktree for shell-heavy work)' }
       }
     },
-    async run({ description, prompt, agentType, background }, ctx) {
+    async run({ description, prompt, agentType, background, isolation }, ctx) {
       if (depth >= maxDepth) {
         return `Error: Task depth limit reached (maxDepth ${maxDepth}). Cannot spawn another child agent \u2014 do this work directly instead.`;
       }
       const label = String(description ?? agentType ?? "sub-task");
+      const useWorktree = isolation === "worktree";
       if (background && ctx.jobs) {
         const id = ctx.jobs.start(async ({ signal }) => {
-          const overlay = new OverlayFilesystem(opts.fs);
-          const childOpts2 = childOptionsFor(opts, overlay, depth, maxDepth, agentType);
+          let fs2;
+          let commit;
+          let wtHandle2;
+          if (useWorktree) {
+            const h = createWorktreeFs(process.cwd(), label, 0);
+            if (typeof h === "string") throw new Error(h);
+            wtHandle2 = h;
+            fs2 = new NodeDiskFilesystem(h.worktreePath);
+            commit = async () => {
+            };
+          } else {
+            const overlay = new OverlayFilesystem(opts.fs);
+            fs2 = overlay;
+            commit = () => overlay.commit();
+          }
+          const childOpts2 = childOptionsFor(opts, fs2, depth, maxDepth, agentType);
           if (typeof childOpts2 === "string") throw new Error(childOpts2);
-          childOpts2.signal = signal;
-          const res2 = await new Agent(childOpts2).run(String(prompt ?? ""));
-          if (signal.aborted) return "[killed before commit]";
-          await overlay.commit();
-          const summary2 = res2.text || `(child '${label}' finished with no summary; finishReason=${res2.finishReason})`;
-          await opts.hooks?.onSubagentStop?.(summary2, { label, agentType });
-          return summary2;
+          const childPrompt = wtHandle2 ? worktreePromptPrefix(wtHandle2.branch) + String(prompt ?? "") : String(prompt ?? "");
+          const { res, result } = await runChildTraced({ opts, childOpts: childOpts2, prompt: childPrompt, label, agentType, childDepth: depth + 1, signal });
+          if (res.finishReason === "aborted" || signal.aborted) {
+            wtHandle2 && releaseWorktree(wtHandle2);
+            return result;
+          }
+          await commit();
+          let summary = result;
+          if (wtHandle2) {
+            const r = releaseWorktree(wtHandle2);
+            if (!r.removed) summary += `
+
+[worktree removal failed: ${r.reason}]`;
+          }
+          return summary;
         }, { kind: "agent", label });
         return `Started background sub-task ${id} ('${label}') \u2014 poll with JobOutput({id:"${id}"}).`;
       }
-      const childOpts = childOptionsFor(opts, opts.fs, depth, maxDepth, agentType);
-      if (typeof childOpts === "string") return `Error: ${childOpts}`;
-      const child = new Agent(childOpts);
-      const res = await child.run(String(prompt ?? ""));
-      const summary = res.text || `(child agent finished '${label}' with no summary; finishReason=${res.finishReason})`;
-      await opts.hooks?.onSubagentStop?.(summary, { label, agentType });
-      return summary;
+      let fs;
+      let wtHandle;
+      if (useWorktree) {
+        const h = createWorktreeFs(process.cwd(), label, 0);
+        if (typeof h === "string") return `Error: ${h}`;
+        wtHandle = h;
+        fs = new NodeDiskFilesystem(h.worktreePath);
+      } else {
+        fs = opts.fs;
+      }
+      const childOpts = childOptionsFor(opts, fs, depth, maxDepth, agentType);
+      if (typeof childOpts === "string") {
+        wtHandle && releaseWorktree(wtHandle);
+        return `Error: ${childOpts}`;
+      }
+      try {
+        const childPrompt = wtHandle ? worktreePromptPrefix(wtHandle.branch) + String(prompt ?? "") : String(prompt ?? "");
+        const { result } = await runChildTraced({ opts, childOpts, prompt: childPrompt, label, agentType, childDepth: depth + 1, signal: ctx.signal });
+        let summary = result;
+        if (wtHandle) {
+          const r = releaseWorktree(wtHandle);
+          if (!r.removed) summary += `
+
+[worktree removal failed: ${r.reason}]`;
+        }
+        return summary;
+      } catch (e) {
+        if (wtHandle) releaseWorktree(wtHandle);
+        throw e;
+      }
     }
   };
 }
@@ -2518,7 +2794,7 @@ function makeTaskBatchTool(opts) {
   const maxParallel = opts.maxParallel ?? 4;
   return {
     name: "TaskBatch",
-    description: "Delegate SEVERAL independent sub-tasks to child agents that run concurrently; returns all their summaries. Each child is write-isolated (its file edits are merged back in array order). Use for parallel fan-out (review/search/scoped refactors across files). Provide `tasks: [{ description, prompt, agentType? }]`.",
+    description: 'Delegate SEVERAL independent sub-tasks to child agents that run concurrently; returns all their summaries. Each child is write-isolated (its file edits are merged back in array order). Use for parallel fan-out (review/search/scoped refactors across files). Provide `tasks: [{ description, prompt, agentType? }]`. Set `isolation: "worktree"` to run each child in its own git worktree (needed for real shell commands) \u2014 slower, auto-cleaned if no changes.',
     parameters: {
       type: "object",
       required: ["tasks"],
@@ -2535,30 +2811,53 @@ function makeTaskBatchTool(opts) {
               agentType: { type: "string", description: "optional named subagent type" }
             }
           }
-        }
+        },
+        isolation: { type: "string", enum: ["overlay", "worktree"], description: 'isolation mode for ALL children: "overlay" (default) or "worktree" (real git worktree each)' }
       }
     },
-    async run({ tasks }, _ctx) {
+    async run({ tasks, isolation }, ctx) {
       if (depth >= maxDepth) return `Error: Task depth limit reached (maxDepth ${maxDepth}). Cannot spawn child agents \u2014 do this work directly instead.`;
       const list = Array.isArray(tasks) ? tasks : [];
       if (!list.length) return "Error: TaskBatch needs a non-empty `tasks` array.";
+      const useWorktree = isolation === "worktree";
       const results = await boundedPool(list, maxParallel, async (t, i) => {
         const label = String(t?.description ?? t?.agentType ?? `task ${i + 1}`);
-        const overlay = new OverlayFilesystem(opts.fs);
-        const childOpts = childOptionsFor(opts, overlay, depth, maxDepth, t?.agentType);
+        let fs;
+        let overlay;
+        let wtHandle;
+        if (useWorktree) {
+          const h = createWorktreeFs(process.cwd(), label, i);
+          if (typeof h === "string") return { label, error: h, ok: false };
+          wtHandle = h;
+          fs = new NodeDiskFilesystem(h.worktreePath);
+        } else {
+          overlay = new OverlayFilesystem(opts.fs);
+          fs = overlay;
+        }
+        const childOpts = childOptionsFor(opts, fs, depth, maxDepth, t?.agentType);
         if (typeof childOpts === "string") return { label, error: childOpts, ok: false };
         try {
-          const res = await new Agent(childOpts).run(String(t?.prompt ?? ""));
-          await opts.hooks?.onSubagentStop?.(res.text, { label, agentType: t?.agentType });
-          return { label, text: res.text, overlay, ok: res.finishReason !== "error" };
+          const childPrompt = wtHandle ? worktreePromptPrefix(wtHandle.branch) + String(t?.prompt ?? "") : String(t?.prompt ?? "");
+          const { res, result } = await runChildTraced({ opts, childOpts, prompt: childPrompt, label, agentType: t?.agentType, childDepth: depth + 1, signal: ctx.signal });
+          return { label, text: result, overlay, wtHandle, ok: res.finishReason !== "error" && res.finishReason !== "aborted" };
         } catch (e) {
-          return { label, error: e instanceof Error ? e.message : String(e), ok: false };
+          return { label, error: e instanceof Error ? e.message : String(e), wtHandle, ok: false };
         }
       });
-      for (const r of results) if (r.ok && r.overlay) await r.overlay.commit().catch(() => {
-      });
-      return results.map((r, i) => `### ${i + 1}. ${r.label}
-${r.error ? `ERROR: ${r.error}` : r.text || "(no summary)"}`).join("\n\n");
+      const lines = [];
+      for (const r of results) {
+        if (r.ok && r.overlay) await r.overlay.commit().catch(() => {
+        });
+        let extra = "";
+        if (r.wtHandle) {
+          const wr = releaseWorktree(r.wtHandle);
+          if (!wr.removed) extra = `
+[worktree removal failed: ${wr.reason}]`;
+        }
+        lines.push(`### ${lines.length + 1}. ${r.label}
+${r.error ? `ERROR: ${r.error}` : r.text || "(no summary)"}${extra}`);
+      }
+      return lines.join("\n\n");
     }
   };
 }
@@ -2803,7 +3102,7 @@ function reasoningToChatFragment(model, effort) {
 }
 
 // src/Agent.ts
-var log3 = forComponent("Agent");
+var log4 = forComponent("Agent");
 function isAbortError(err) {
   const e = err;
   const blob = `${e?.message ?? ""} ${e?.name ?? ""} ${e?.code ?? ""} ${e?.cause?.name ?? ""}`;
@@ -2879,6 +3178,11 @@ var AgentOptions = class {
   depth = 0;
   /** Hard ceiling on subagent nesting (beyond it the `Task` tool refuses to spawn). */
   maxDepth = 2;
+  /** Real-disk dir where child agents stream their transcript as they run (origin-anchored — survives
+   *  worktree teardown / a child's own cwd). When set, an interrupted/failed child commits a STATUS HINT
+   *  + a pointer to its trace instead of a dangling tool_call, so the parent can read it and decide
+   *  whether to ignore, pick it up, or restart. Unset (library/sandbox default) = no tracing. */
+  traceDir;
   /** Stream tokens from the model. Takes effect only with a `host.notify`; off => current (non-stream) behavior. */
   stream = false;
   /** Fold the dropped middle of an over-long transcript into a synthetic summary (edge-safe, no LLM). Off => drop-oldest. */
@@ -2999,7 +3303,7 @@ var Agent = class _Agent {
       const disk = new NodeDiskFilesystem2(process.cwd());
       await disk.init();
       this.options.fs = new JailedFilesystem2(disk);
-      log3.info(`no fs provided \u2014 defaulting to jailed real disk at ${process.cwd()}`);
+      log4.info(`no fs provided \u2014 defaulting to jailed real disk at ${process.cwd()}`);
     }
     this.buildCtx();
   }
@@ -3053,7 +3357,7 @@ var Agent = class _Agent {
         agents = loaded.agents;
         if (loaded.catalog) systemPrompt += "\n\n" + loaded.catalog;
       }
-      const taskOpts = { ai: o.ai, model: o.model, fs, depth: o.depth, maxDepth: o.maxDepth, agents, hooks: o.hooks };
+      const taskOpts = { ai: o.ai, model: o.model, fs, depth: o.depth, maxDepth: o.maxDepth, agents, hooks: o.hooks, traceDir: o.traceDir };
       tools = [...tools, makeTaskTool(taskOpts), makeTaskBatchTool(taskOpts)];
     }
     if (o.checkpoints) tools = [...tools, ...checkpointTools()];
@@ -3142,7 +3446,7 @@ var Agent = class _Agent {
     let lastFp = "";
     let repeats = 0;
     const kill = (finishReason) => {
-      log3.warn(`kill-switch: ${finishReason} (steps=${steps}, tokens=${usage.totalTokens}, budgetTokens=${Math.round(usage.totalTokens - 0.9 * usage.cacheReadTokens)}, ms=${Date.now() - start - this.parkedMs}${this.parkedMs ? ` +${this.parkedMs} parked` : ""})`);
+      log4.warn(`kill-switch: ${finishReason} (steps=${steps}, tokens=${usage.totalTokens}, budgetTokens=${Math.round(usage.totalTokens - 0.9 * usage.cacheReadTokens)}, ms=${Date.now() - start - this.parkedMs}${this.parkedMs ? ` +${this.parkedMs} parked` : ""})`);
       this.ctx.jobs?.killAll();
       return { text: lastAssistantText(this.transcript), steps, finishReason, messages: this.transcript, usage, usageEstimated };
     };
@@ -3188,7 +3492,7 @@ var Agent = class _Agent {
             const transient = !o.signal?.aborted && !isAbortError(err) && attempt < 2 && (network || serverSide);
             if (!transient) throw err;
             const waitMs = 1e3 * (attempt + 1);
-            log3.warn(`network drop mid-step (${err?.message ?? err}) \u2014 retrying in ${waitMs}ms`);
+            log4.warn(`network drop mid-step (${err?.message ?? err}) \u2014 retrying in ${waitMs}ms`);
             o.host?.notify?.({ kind: "retry", message: `connection dropped \u2014 retrying step (#${attempt + 1})` });
             await new Promise((r) => setTimeout(r, waitMs));
           }
@@ -3204,7 +3508,7 @@ var Agent = class _Agent {
           bodyStr = void 0;
         }
         if (bodyStr && err instanceof Error && !err.message.includes(bodyStr)) err.detail = bodyStr;
-        log3.error(`chat() failed: ${err?.message ?? err}${bodyStr ? ` \u2014 ${bodyStr}` : ""}`, err);
+        log4.error(`chat() failed: ${err?.message ?? err}${bodyStr ? ` \u2014 ${bodyStr}` : ""}`, err);
         return { text: "", steps, finishReason: "error", messages: this.transcript, usage, usageEstimated, error: err };
       }
       if (o.signal?.aborted) return kill("aborted");
@@ -3231,7 +3535,7 @@ var Agent = class _Agent {
         });
       }
       if (toolCalls.length === 0) {
-        log3.verbose(`completed in ${steps} step(s)`);
+        log4.verbose(`completed in ${steps} step(s)`);
         await this.ctx.jobs?.drain();
         await this.activeHooks?.onStop?.(res.content ?? "");
         return { text: res.content ?? "", steps, finishReason: "stop", messages: this.transcript, usage, usageEstimated };
@@ -3297,13 +3601,13 @@ var Agent = class _Agent {
     const decision = await this.park(Promise.resolve(hooks?.preToolUse?.(call, meta)));
     if (decision?.block) {
       const blocked = `Blocked by hook: ${decision.reason ?? "no reason given"}`;
-      log3.debug(`${tc.function.name} -> ${blocked}`);
+      log4.debug(`${tc.function.name} -> ${blocked}`);
       await hooks?.postToolUse?.(call, blocked, meta);
       return blocked;
     }
     this.options.host?.notify?.({ kind: "tool_use", id: tc.id ?? "", name: tc.function.name, input: args });
     if (earlyError) {
-      log3.debug(`${tc.function.name} -> ${earlyError}`);
+      log4.debug(`${tc.function.name} -> ${earlyError}`);
       await hooks?.postToolUse?.(call, earlyError, meta);
       this.options.host?.notify?.({ kind: "tool_result", id: tc.id ?? "", output: earlyError, isError: true });
       return earlyError;
@@ -3312,12 +3616,12 @@ var Agent = class _Agent {
     let images;
     let threw = false;
     try {
-      log3.debug(`${tc.function.name}(${tc.function.arguments})`);
+      log4.debug(`${tc.function.name}(${tc.function.arguments})`);
       this.ctx.emit = hooks?.onToolOutput ? (chunk) => {
         try {
           hooks.onToolOutput(call, chunk, meta);
         } catch (e) {
-          log3.debug(`onToolOutput hook error: ${e}`);
+          log4.debug(`onToolOutput hook error: ${e}`);
         }
       } : void 0;
       const raw = await tool.run(args, this.ctx);
@@ -3329,7 +3633,7 @@ var Agent = class _Agent {
       }
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e);
-      log3.debug(`${tc.function.name} -> error: ${msg}`);
+      log4.debug(`${tc.function.name} -> error: ${msg}`);
       result = `Error: ${msg}`;
       threw = true;
     } finally {
@@ -3455,7 +3759,7 @@ function fitTokenBudget(messages, maxTokens) {
   const ids = callIdSet(messages.slice(from));
   while (from < messages.length && messages[from].role === "tool" && !ids.has(messages[from].tool_call_id ?? "")) total -= per[from++];
   if (total > maxTokens)
-    log3.warn(`context ~${total} tok still over maxContextTokens=${maxTokens} after trimming (system head can't be dropped)`);
+    log4.warn(`context ~${total} tok still over maxContextTokens=${maxTokens} after trimming (system head can't be dropped)`);
   return [...head, ...messages.slice(from)];
 }
 function compact(m, max, focus) {
@@ -4116,7 +4420,7 @@ init_tools_web();
 init_tools();
 init_tools_structured();
 init_logging();
-var log5 = forComponent("scratch");
+var log6 = forComponent("scratch");
 var SCRATCH_DIR = "/scratch";
 function shortArgs(args) {
   try {
@@ -4156,7 +4460,7 @@ var Scratch = class {
           await (this.dirReady ??= mkdirp(this.fs, dir));
           await this.fs.writeFile(path, header + raw);
         } catch (e) {
-          log5.debug("scratch write failed; returning raw", e);
+          log6.debug("scratch write failed; returning raw", e);
           return raw;
         }
         const preview = raw.slice(0, previewChars).replace(/\s+/g, " ").trim();
@@ -4186,7 +4490,7 @@ To pull a specific detail, Grep/Read ${path}, or call Ask({ question: "\u2026",
       await (this.dirReady ??= mkdirp(this.fs, dir));
       await this.fs.writeFile(path, header + full);
     } catch (e) {
-      log5.debug("scratch spill failed; cropping lossy", e);
+      log6.debug("scratch spill failed; cropping lossy", e);
       return full.slice(0, pageBytes) + `
 
 [output cropped to ${pageBytes} of ${full.length} bytes; full output unavailable (scratch write failed) \u2014 refine your query]`;
@@ -4232,7 +4536,7 @@ Question: ${q}`);
         const answer = (res.text ?? "").trim();
         return answer || "(no answer found in scratch)";
       } catch (e) {
-        log5.debug("Ask peek failed", e);
+        log6.debug("Ask peek failed", e);
         return `Error querying scratch: ${e?.message ?? e}`;
       }
     }
@@ -4241,7 +4545,7 @@ Question: ${q}`);
 
 // src/lessons.ts
 init_logging();
-var log6 = forComponent("Lessons");
+var log7 = forComponent("Lessons");
 var LessonOptionsDefaults = class {
   minRepeats = 2;
 };
@@ -4266,15 +4570,15 @@ function lessonCapture(options) {
       counts.set(lesson.slug, n);
       if (n < o.minRepeats) return;
       written.add(lesson.slug);
-      await writeFact(o.fs, o.dir, lesson.slug, lesson.body).catch((e) => log6.warn(`could not persist ${lesson.slug}: ${e?.message ?? e}`));
-      log6.debug(`captured lesson ${lesson.slug} (recurred ${n}\xD7)`);
+      await writeFact(o.fs, o.dir, lesson.slug, lesson.body).catch((e) => log7.warn(`could not persist ${lesson.slug}: ${e?.message ?? e}`));
+      log7.debug(`captured lesson ${lesson.slug} (recurred ${n}\xD7)`);
     }
   };
 }
 
 // src/reflect.ts
 init_logging();
-var log7 = forComponent("Reflect");
+var log8 = forComponent("Reflect");
 async function reflectOnRun(o) {
   const digest = digestRun(o.result.messages, o.maxDigestChars ?? 6e3);
   if (!digest.trim()) return null;
@@ -4290,7 +4594,7 @@ If the run was fine or the issue was purely task-specific (not generalizable), r
     const r = await o.ai.chat({ model: o.model, messages: [{ role: "user", content: prompt }], stream: false });
     text = r?.content ?? "";
   } catch (e) {
-    log7.warn(`reflection call failed: ${e?.message ?? e}`);
+    log8.warn(`reflection call failed: ${e?.message ?? e}`);
     return null;
   }
   const m = text.match(/LESSON:\s*(.+)/i);
@@ -4300,10 +4604,10 @@ If the run was fine or the issue was purely task-specific (not generalizable), r
   try {
     await writeFact(o.fs, o.dir, slug2, lesson);
   } catch (e) {
-    log7.warn(`could not persist lesson: ${e?.message ?? e}`);
+    log8.warn(`could not persist lesson: ${e?.message ?? e}`);
     return null;
   }
-  log7.debug(`reflection persisted ${slug2}`);
+  log8.debug(`reflection persisted ${slug2}`);
   return slug2;
 }
 function digestRun(messages, maxChars) {
@@ -4320,7 +4624,7 @@ function digestRun(messages, maxChars) {
 // src/duplex.ts
 import { MemFilesystem as MemFilesystem2 } from "@livx.cc/wcli/core";
 init_logging();
-var log8 = forComponent("DuplexAgent");
+var log9 = forComponent("DuplexAgent");
 function describeCall(call) {
   const v = call.args && Object.values(call.args).find((x) => typeof x === "string" && x.trim());
   const hint = v ? ` (${String(v).replace(/\s+/g, " ").trim().slice(0, 48)})` : "";
@@ -4460,7 +4764,7 @@ Today's date: ${(/* @__PURE__ */ new Date()).toDateString()}.`;
           const m = this.reflexBuf.match(RESERVED_EVENT_MARKER);
           if (m) {
             this.fabricationCut = true;
-            log8.warn(`reflex fabricated a [task \u2026] event in its spoken stream \u2014 cutting it (kept ${m.index} chars)`);
+            log9.warn(`reflex fabricated a [task \u2026] event in its spoken stream \u2014 cutting it (kept ${m.index} chars)`);
             const safe = this.reflexBuf.slice(this.reflexForwarded, m.index);
             if (!safe) return;
             if (safe.trim()) this.spokeThisTurn = true;
@@ -4539,7 +4843,7 @@ Today's date: ${(/* @__PURE__ */ new Date()).toDateString()}.`;
     try {
       await this.voice.send("[reminder] You dispatched a task but said nothing to the user. Say ONE short spoken acknowledgement now \u2014 no tools.");
     } catch (e) {
-      log8.warn(`ack nudge failed: ${e instanceof Error ? e.message : e}`);
+      log9.warn(`ack nudge failed: ${e instanceof Error ? e.message : e}`);
     } finally {
       this.nudging = false;
     }
@@ -4687,7 +4991,7 @@ Another agent just implemented the above. Independently check the CURRENT state
     this.notify("task_verify", `task ${id}: verifying`, { id });
     const cres = await new Agent(agentOpts).run(checkBrief);
     if (cres.finishReason !== "stop") {
-      log8.warn(`task ${id}: verify inconclusive (${cres.finishReason})`);
+      log9.warn(`task ${id}: verify inconclusive (${cres.finishReason})`);
       this.notify("task_verify", `task ${id}: verify inconclusive (${cres.finishReason})`, { id, finishReason: cres.finishReason });
     }
     const sum = (a = 0, b = 0) => a + b;
@@ -4790,7 +5094,7 @@ Another agent just implemented the above. Independently check the CURRENT state
     }
     rec.status = "done";
     rec.result = res.text;
-    log8.verbose(`task ${id} done (${res.steps} steps)`);
+    log9.verbose(`task ${id} done (${res.steps} steps)`);
     this.notify("task_done", `task ${id} (${rec.label}) completed`, {
       id,
       text: res.text,
@@ -4808,7 +5112,7 @@ Another agent just implemented the above. Independently check the CURRENT state
     this.dropAsk(rec.id);
     rec.status = "error";
     rec.result = msg;
-    log8.warn(`task ${rec.id} failed: ${msg}`);
+    log9.warn(`task ${rec.id} failed: ${msg}`);
     this.notify("task_error", `task ${rec.id} (${rec.label}) failed: ${msg}`);
     this.queueRevoice(`[task ${rec.id} failed] ${msg}`);
   }
@@ -5168,7 +5472,7 @@ init_logging();
 
 // src/voice/engine.ts
 init_logging();
-var log9 = forComponent("VoiceEngine");
+var log10 = forComponent("VoiceEngine");
 var now = () => performance.now();
 var forSpeech = (t) => t.replace(/[*_`#]+/g, "").replace(/^[ \t]*[-•]\s+/gm, "").replace(/\s*[\u2013\u2014]\s*/g, ", ").replace(/[\u2010\u2011]/g, "-").replace(/\s*\|\s*/g, ", ").replace(/(\d)\s+%/g, "$1%").replace(/\.{3,}/g, ".");
 var VoiceEngineOptions = class {
@@ -5276,7 +5580,7 @@ var VoiceEngine = class _VoiceEngine {
     this.stt.onLevel = (rms) => this.handleLevel(rms);
     await Promise.all([this.tts.connect(), this.stt.start()]);
     this.setState("listening");
-    log9.debug(`voice I/O up (${this.stt.usingAec ? "AEC" : "heuristic echo"} capture)`);
+    log10.debug(`voice I/O up (${this.stt.usingAec ? "AEC" : "heuristic echo"} capture)`);
   }
   get usingAec() {
     return this.stt.usingAec;
@@ -5328,7 +5632,7 @@ var VoiceEngine = class _VoiceEngine {
     this.reply += text;
     for (const w of this.words(this.reply)) this.echoWords.add(w);
     this.tts.speak(forSpeech(text), true);
-    if (!this.spokeDeltas && this.turnStartAt) log9.debug(`ttft: ${Math.round(now() - this.turnStartAt)}ms`);
+    if (!this.spokeDeltas && this.turnStartAt) log10.debug(`ttft: ${Math.round(now() - this.turnStartAt)}ms`);
     this.spokeDeltas = true;
     this.setState("speaking");
   }
@@ -5349,7 +5653,7 @@ var VoiceEngine = class _VoiceEngine {
       }
       this.drainTimer = null;
       this.speaking = false;
-      if (this.turnStartAt) log9.debug(`turn: ${Math.round(now() - this.turnStartAt)}ms (incl. playback)`);
+      if (this.turnStartAt) log10.debug(`turn: ${Math.round(now() - this.turnStartAt)}ms (incl. playback)`);
       this.echoUntil = now() + 2500;
       if (!this.usingAec) this.stt.reset();
       this.setState("listening");
@@ -5490,7 +5794,7 @@ var VoiceEngine = class _VoiceEngine {
     this.pendingUtt = this.pendingUtt ? `${this.pendingUtt} ${text}` : text;
     if (this.pendingTimer) clearTimeout(this.pendingTimer);
     if (this.options.incompleteMergeMs && this.looksIncomplete(this.pendingUtt)) {
-      log9.verbose(`hold: incomplete utterance "${this.pendingUtt.slice(-40)}"`);
+      log10.verbose(`hold: incomplete utterance "${this.pendingUtt.slice(-40)}"`);
       this.options.onHold();
       if (this.options.holdFiller && !this.speaking) {
         this.beginSpeech();
@@ -5588,7 +5892,7 @@ async function resolveAuth(auth) {
 }
 
 // src/voice/soniox.ts
-var log10 = forComponent("SonioxSTT");
+var log11 = forComponent("SonioxSTT");
 var now2 = () => performance.now();
 var SonioxSTTOptions = class {
   auth = "";
@@ -5645,9 +5949,9 @@ var SonioxSTT = class {
     this.ws.onmessage = (ev) => this.handle(JSON.parse(String(ev.data)));
     this.ws.onclose = (ev) => {
       if (this.stopped) return;
-      log10.warn(`soniox ws closed (${ev.code} ${ev.reason || ""}) \u2014 reconnecting`);
+      log11.warn(`soniox ws closed (${ev.code} ${ev.reason || ""}) \u2014 reconnecting`);
       this.reset();
-      this.connectWs().catch((e) => log10.error(`soniox reconnect failed: ${e.message}`));
+      this.connectWs().catch((e) => log11.error(`soniox reconnect failed: ${e.message}`));
     };
   }
   async start() {
@@ -5657,7 +5961,7 @@ var SonioxSTT = class {
     this.endpointTimer = setInterval(() => {
       const combined = (this.finalText + this.partialText).trim();
       if (!combined || now2() - this.lastChangeAt < this.options.silenceEndpointMs) return;
-      if (this.firstTokenAt) log10.debug(`stt: ${Math.round(now2() - this.firstTokenAt)}ms first-token\u2192silence-endpoint, "${combined.slice(0, 60)}"`);
+      if (this.firstTokenAt) log11.debug(`stt: ${Math.round(now2() - this.firstTokenAt)}ms first-token\u2192silence-endpoint, "${combined.slice(0, 60)}"`);
       this.reset();
       this.onUtterance(combined, now2());
     }, 120);
@@ -5674,7 +5978,7 @@ var SonioxSTT = class {
     });
   }
   handle(m) {
-    if (m.error_message) return log10.error(`soniox: ${m.error_message}`);
+    if (m.error_message) return log11.error(`soniox: ${m.error_message}`);
     let endpoint = false;
     for (const t of m.tokens ?? []) {
       if (t.text === "<end>") endpoint = true;
@@ -5690,7 +5994,7 @@ var SonioxSTT = class {
     this.onPartial(combined);
     if (endpoint && this.finalText.trim()) {
       const utterance = this.finalText.trim();
-      if (this.firstTokenAt) log10.debug(`stt: ${Math.round(now2() - this.firstTokenAt)}ms first-token\u2192endpoint, "${utterance.slice(0, 60)}"`);
+      if (this.firstTokenAt) log11.debug(`stt: ${Math.round(now2() - this.firstTokenAt)}ms first-token\u2192endpoint, "${utterance.slice(0, 60)}"`);
       this.reset();
       this.onUtterance(utterance, now2());
     }
@@ -5712,7 +6016,7 @@ var SonioxSTT = class {
 
 // src/voice/cartesia.ts
 init_logging();
-var log11 = forComponent("CartesiaTTS");
+var log12 = forComponent("CartesiaTTS");
 var now3 = () => performance.now();
 var CartesiaTTSOptions = class {
   auth = "";
@@ -5762,9 +6066,9 @@ var CartesiaTTS = class _CartesiaTTS {
       this.ws.onerror = (e) => rej(new Error(`cartesia ws: ${e.message || "connect failed"}`));
     });
     this.ws.onclose = (ev) => {
-      log11.warn(`cartesia ws closed (${ev.code} ${ev.reason || ""})`);
+      log12.warn(`cartesia ws closed (${ev.code} ${ev.reason || ""})`);
       if (!this.closed) {
-        this.connecting = this.doConnect().catch((e) => log11.error(`cartesia reconnect failed: ${e.message}`));
+        this.connecting = this.doConnect().catch((e) => log12.error(`cartesia reconnect failed: ${e.message}`));
       }
     };
     this.ws.onmessage = (ev) => {
@@ -5786,11 +6090,11 @@ var CartesiaTTS = class _CartesiaTTS {
           this.down = true;
           this.downAt = now3();
           this.consecutiveOk = 0;
-          log11.warn(`TTS circuit breaker open \u2014 ${this.consecutiveErrors} consecutive errors, switching to text-only`);
+          log12.warn(`TTS circuit breaker open \u2014 ${this.consecutiveErrors} consecutive errors, switching to text-only`);
           this.onDone();
           this.startProbe();
         } else if (!this.down) {
-          log11.warn(`cartesia: ${JSON.stringify(m)}`);
+          log12.warn(`cartesia: ${JSON.stringify(m)}`);
         }
       }
     };
@@ -5804,7 +6108,7 @@ var CartesiaTTS = class _CartesiaTTS {
     this.consecutiveOk = 0;
     this.stopProbe();
     const downMs = this.downAt ? now3() - this.downAt : 0;
-    (downMs < 2e3 ? log11.debug : log11.info)(`TTS recovered${downMs ? ` (down ${downMs}ms)` : ""}`);
+    (downMs < 2e3 ? log12.debug : log12.info)(`TTS recovered${downMs ? ` (down ${downMs}ms)` : ""}`);
   }
   /** Ensure the WS is open before sending — reconnects if idle-closed. */
   async ensureConnected() {
@@ -5923,6 +6227,7 @@ export {
   buildMcpCatalog,
   checkpointTool,
   checkpointTools,
+  cleanupWorktree,
   compileSynthesizedTool,
   composeHooks,
   contentText,
@@ -5931,12 +6236,17 @@ export {
   defaultTools,
   diskAgentOptions,
   editTool,
+  enterWorktree,
   exitSessionTool,
+  exitWorktree,
   expandCommand,
   expandEntry,
   expandTemplate,
+  findGitRoot,
   forComponent,
   fullAgentOptions,
+  getOrCreateWorktree,
+  getWorktreeSession,
   globTool,
   grepTool,
   htmlToText,
@@ -5990,8 +6300,10 @@ export {
   toolsByName,
   topByRelevance,
   validateToolCode,
+  validateWorktreeSlug,
   webFetchTool,
   webSearchTool,
+  worktreeBranchName,
   writeFact,
   writeTool
 };