@duckmind/dm-darwin-x64 0.66.5 → 0.66.6

package/extensions/dm-subagents/src/runs/shared/subagent-prompt-runtime.js

@@ -18,6 +18,7 @@ import { captureWatchdogDiffBaseline, createWatchdogDiffTool, WATCHDOG_DIFF_TOOL
 import { inheritedNestedRouteOf } from "./nested-events.js";
 import { registerWaitTool } from "../background/wait-tool.js";
 import { drainOutstandingWork } from "../background/auto-drain.js";
+import { MODEL_ONLY_TOOL } from "../../shared/extension-context.js";
 import {
   childSupervisorMetadata,
   evaluateChildToolDiagnostic
@@ -173,9 +174,14 @@ export function stripGlobalContext(prompt) {
   const legacyStartIndex = rewrittenXml.indexOf(PROJECT_CONTEXT_LEGACY_HEADER);
   if (legacyStartIndex === -1)
     return rewrittenXml;
-  const legacyEndIndex = findSectionEnd(rewrittenXml, legacyStartIndex + PROJECT_CONTEXT_LEGACY_HEADER.length, [SKILLS_HEADER, DATE_HEADER]);
+  const legacyEndIndex = findSectionEnd(rewrittenXml, legacyStartIndex + PROJECT_CONTEXT_LEGACY_HEADER.length, [SKILLS_HEADER, DATE_HEADER, `
+
+# Environment Context
+
+`]);
   const legacyContext = rewrittenXml.slice(legacyStartIndex, legacyEndIndex);
-  return `${rewrittenXml.slice(0, legacyStartIndex)}${stripGlobalInstructionsFromLegacyContext(legacyContext)}${rewrittenXml.slice(legacyEndIndex)}`;
+  const filtered = stripGlobalInstructionsFromLegacyContext(legacyContext);
+  return `${rewrittenXml.slice(0, legacyStartIndex)}${/^## /m.test(filtered) ? filtered : ""}${rewrittenXml.slice(legacyEndIndex)}`;
 }
 export function stripInheritedSkills(prompt) {
   const startIndex = prompt.indexOf(SKILLS_HEADER);
@@ -187,16 +193,18 @@ export function stripInheritedSkills(prompt) {
 export function stripSubagentOrchestrationSkill(prompt) {
   return prompt.replace(/\n{0,2}<skill\s+name=["']dm-subagents["'][^>]*>[\s\S]*?<\/skill>\n{0,2}/g, `
 
-`).replace(/[ \t]*<skill>\s*[\s\S]*?<\/skill>\s*/g, (block) => SUBAGENT_ORCHESTRATION_SKILL_NAME_PATTERN.test(block) ? "" : block);
+`).replace(/^[ \t]*<skill>[\s\S]*?<\/skill>[ \t]*(?:\r?\n)?/gm, (block) => SUBAGENT_ORCHESTRATION_SKILL_NAME_PATTERN.test(block) ? "" : block).replace(/^(Loaded skills: )(.*)$/gm, (_line, prefix, names) => `${prefix}${names.split(", ").filter((name) => name !== "dm-subagents").join(", ")}`);
 }
 function stripChildBoundaryInstructions(prompt) {
   let rewritten = prompt;
-  for (const boundary of [CHILD_SUBAGENT_BOUNDARY_INSTRUCTIONS, CHILD_FANOUT_BOUNDARY_INSTRUCTIONS]) {
-    rewritten = rewritten.split(boundary).join("");
+  for (const instructions of [CHILD_SUBAGENT_BOUNDARY_INSTRUCTIONS, CHILD_FANOUT_BOUNDARY_INSTRUCTIONS, STRUCTURED_OUTPUT_INSTRUCTIONS]) {
+    rewritten = rewritten.split(`
+
+${instructions}`).join("").split(instructions).join("");
   }
   return rewritten.replace(/^(?:[ \t]*\r?\n)+/, "");
 }
-export function rewriteSubagentPrompt(prompt, options) {
+function stripInheritedPromptText(prompt, options) {
   let rewritten = prompt;
   if (!options.inheritProjectContext) {
     rewritten = stripProjectContext(rewritten);
@@ -207,15 +215,41 @@ export function rewriteSubagentPrompt(prompt, options) {
   if (!options.inheritSkills) {
     rewritten = stripInheritedSkills(rewritten);
   }
-  rewritten = stripSubagentOrchestrationSkill(rewritten);
-  rewritten = stripChildBoundaryInstructions(rewritten);
+  return stripChildBoundaryInstructions(stripSubagentOrchestrationSkill(rewritten));
+}
+function appendChildBoundary(prompt, options) {
   const boundary = options.fanoutChild ? CHILD_FANOUT_BOUNDARY_INSTRUCTIONS : CHILD_SUBAGENT_BOUNDARY_INSTRUCTIONS;
   const structured = options.structuredOutput ? `
 
 ${STRUCTURED_OUTPUT_INSTRUCTIONS}` : "";
-  return `${boundary}${structured}
+  return `${stripChildBoundaryInstructions(prompt)}
 
-${rewritten}`;
+${boundary}${structured}`;
+}
+export function rewriteSubagentPrompt(prompt, options) {
+  return appendChildBoundary(stripInheritedPromptText(prompt, options), options);
+}
+function filterChildPromptOptions(options, inherited) {
+  if (!inherited.inheritProjectContext)
+    options.contextFiles = [];
+  else if (!inherited.inheritGlobalContext)
+    options.contextFiles = (options.contextFiles ?? []).filter((file) => !isGlobalContextFile(file.path));
+  options.skills = inherited.inheritSkills ? (options.skills ?? []).filter((skill) => skill.name !== "dm-subagents") : [];
+  if (options.customPrompt)
+    options.customPrompt = stripInheritedPromptText(options.customPrompt, inherited);
+  if (options.appendSystemPrompt)
+    options.appendSystemPrompt = stripInheritedPromptText(options.appendSystemPrompt, inherited);
+}
+function rewritesChildPrompt(config) {
+  return config.inheritProjectContext !== undefined || config.inheritGlobalContext !== undefined || config.inheritSkills !== undefined || Boolean(config.fanoutChild);
+}
+export function registerSubagentPromptBoundary(dm, config) {
+  if (!rewritesChildPrompt(config))
+    return;
+  dm.on("before_agent_start", (event) => {
+    const finalized = appendChildBoundary(event.systemPrompt, { fanoutChild: config.fanoutChild, structuredOutput: Boolean(config.structuredOutput) });
+    return finalized === event.systemPrompt ? undefined : { systemPrompt: finalized };
+  });
 }
 function isParentOnlySubagentMessage(message) {
   const m = message;
@@ -260,18 +294,23 @@ export function rewriteForkCacheProviderRequest(event, ctx, forkCacheKey) {
     return;
   return { ...payload, prompt_cache_key: key };
 }
-function portableToolId(id) {
+function portableToolId(id, preserveBoundedCompositeToolIds = false) {
   if (PORTABLE_TOOL_ID_PATTERN.test(id) && id.length <= MAX_PORTABLE_TOOL_ID_LENGTH)
     return id;
+  if (preserveBoundedCompositeToolIds) {
+    const parts = id.split("|");
+    if (parts.length === 2 && parts.every((part) => PORTABLE_TOOL_ID_PATTERN.test(part) && part.length <= MAX_PORTABLE_TOOL_ID_LENGTH))
+      return id;
+  }
   const encoded = `tool_${Buffer.from(id).toString("base64url") || "empty"}`;
   if (encoded.length <= MAX_PORTABLE_TOOL_ID_LENGTH)
     return encoded;
   return `tool_${createHash("sha256").update(id).digest("base64url")}`;
 }
-function sanitizeToolHistoryMessage(message) {
+function sanitizeToolHistoryMessage(message, preserveBoundedCompositeToolIds = false) {
   const m = message;
   if (m?.role === "toolResult" && typeof m.toolCallId === "string") {
-    const toolCallId = portableToolId(m.toolCallId);
+    const toolCallId = portableToolId(m.toolCallId, preserveBoundedCompositeToolIds);
     return toolCallId === m.toolCallId ? message : { ...m, toolCallId };
   }
   if (m?.role !== "assistant" || !Array.isArray(m.content))
@@ -281,7 +320,7 @@ function sanitizeToolHistoryMessage(message) {
     const b = block;
     if (b?.type !== "toolCall" || typeof b.id !== "string")
       return block;
-    const id = portableToolId(b.id);
+    const id = portableToolId(b.id, preserveBoundedCompositeToolIds);
     if (id === b.id)
       return block;
     changed = true;
@@ -315,7 +354,7 @@ export function stripParentOnlySubagentMessages(messages, options = {}) {
       changed = true;
       continue;
     }
-    const sanitized = sanitizeToolIds ? sanitizeToolHistoryMessage(stripped) : stripped;
+    const sanitized = sanitizeToolIds ? sanitizeToolHistoryMessage(stripped, options.preserveBoundedCompositeToolIds === true) : stripped;
     if (stripped !== message || sanitized !== stripped)
       changed = true;
     filtered.push(sanitized);
@@ -413,6 +452,7 @@ function registerStructuredOutputTool(dm, structured) {
   const registerTool = dm.registerTool;
   registerTool({
     name: "structured_output",
+    ...MODEL_ONLY_TOOL,
     label: "Structured Output",
     description: "Submit the required final structured output for this subagent step. This terminates the step.",
     parameters,
@@ -520,6 +560,7 @@ export default function registerSubagentPromptRuntime(dm, config, drainObservati
       return;
     const messages = stripParentOnlySubagentMessages(event.messages, {
       sanitizeToolIds: !COMPOSITE_TOOL_ID_APIS.has(ctx?.model?.api ?? ""),
+      preserveBoundedCompositeToolIds: ctx?.model?.api === "openai-codex-responses",
       preserveFanoutToolHistory: config.fanoutChild
     });
     if (messages === event.messages)
@@ -544,20 +585,18 @@ export default function registerSubagentPromptRuntime(dm, config, drainObservati
     if (childSessionName && typeof dm.setSessionName === "function") {
       dm.setSessionName(childSessionName);
     }
-    const { inheritProjectContext, inheritGlobalContext, inheritSkills } = config;
-    const fanoutChild = config.fanoutChild;
-    let rewritten = event.systemPrompt;
-    if (inheritProjectContext !== undefined || inheritGlobalContext !== undefined || inheritSkills !== undefined || fanoutChild) {
-      rewritten = rewriteSubagentPrompt(event.systemPrompt, {
-        inheritProjectContext: inheritProjectContext ?? true,
-        inheritGlobalContext: inheritGlobalContext ?? true,
-        inheritSkills: inheritSkills ?? true,
-        fanoutChild,
-        structuredOutput: Boolean(config.structuredOutput)
-      });
-    }
-    if (rewritten === event.systemPrompt)
+    if (!rewritesChildPrompt(config))
       return;
-    return { systemPrompt: rewritten };
+    filterChildPromptOptions(event.systemPromptOptions, {
+      inheritProjectContext: config.inheritProjectContext ?? true,
+      inheritGlobalContext: config.inheritGlobalContext ?? true,
+      inheritSkills: config.inheritSkills ?? true
+    });
+    const filtered = stripInheritedPromptText(event.systemPrompt, {
+      inheritProjectContext: config.inheritProjectContext ?? true,
+      inheritGlobalContext: config.inheritGlobalContext ?? true,
+      inheritSkills: config.inheritSkills ?? true
+    });
+    return filtered === event.systemPrompt ? undefined : { systemPrompt: filtered };
   });
 }

package/extensions/dm-subagents/src/runs/shared/tool-availability.js

@@ -5,7 +5,7 @@ export function formatChildToolDiagnostic(diagnostic, options = {}) {
       `${subject} ran as a foreground child, which never loads the parent's ambient extensions, and these child tools were unavailable: ${diagnostic.missing.join(", ")}.`,
       "The `tools` field is a strict allowlist; it does not load extension code.",
       ...diagnostic.missingMcpDirectTools?.length ? [`MCP direct tools missing from the child registry: ${diagnostic.missingMcpDirectTools.join(", ")}.`] : [],
-      "Agents that need MCP tools (`mcpDirectTools`, or MCP tools from an ambient adapter such as dm-mcp-adapter) or models from a provider extension must run as background children (`async: true`), which load the ambient extensions.",
+      "MCP tools require background children (`async: true`) because only they load ambient extensions.",
       "For extension tools a foreground child can load, add the provider path to `subagentOnlyExtensions` (child-only), `extensions`, or as a path-like entry in `tools`, while keeping each registered tool name in `tools`."
     ].join(`
 `);

package/extensions/dm-subagents/src/runs/shared/workflow-async-child-guidance.js

@@ -6,6 +6,6 @@ export function workflowAsyncChildSteeringGuidance(status, state) {
     return [];
   return [
     "Async children recorded as running; direct steering rechecks controls. Choose an exact child ID (queued does not mean consumed):",
-    ...[...ids].map((id) => `  subagent({ action: "steer", id: "${id}", mode: "follow_up", message: "..." })`)
+    ...[...ids].map((id) => `  subagent({ action: "steer", id: "${id}", message: "...", options: { mode: "follow_up" } })`)
   ];
 }

package/extensions/dm-subagents/src/runs/shared/worktree-cleanup-apply.js

@@ -0,0 +1,169 @@
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { writePrivateAtomicJson } from "../../shared/atomic-json.js";
+import { readParallelHandoffManifest } from "./parallel-handoff.js";
+import { buildWorktreeCleanupPlan, isRegisteredCleanupWorktree, resolveCleanupRepoRoot, samePath, worktreeCleanupContentPayload, worktreeCleanupPlanPath, WORKTREE_CLEANUP_PLAN_TTL_MS } from "./worktree-cleanup-plan.js";
+import { withHandoffWriteLock, withRepositoryWorktreeLock } from "./worktree-lock.js";
+import { withWorktreeTransaction } from "./worktree.js";
+function assertContainedRealPath(repoRoot, candidate, create = false) {
+  const relative = path.relative(repoRoot, candidate);
+  if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))
+    throw new Error("Cleanup evidence must be inside the selected repository.");
+  let current = repoRoot;
+  for (const segment of relative.split(path.sep)) {
+    current = path.join(current, segment);
+    if (!fs.existsSync(current) && create)
+      fs.mkdirSync(current, { mode: 448 });
+    const stat = fs.lstatSync(current);
+    if (stat.isSymbolicLink())
+      throw new Error(`Cleanup evidence cannot use a symlink: ${current}`);
+  }
+}
+export function loadReviewedCleanupPlan(repo, planId, now = Date.now()) {
+  const repoRoot = resolveCleanupRepoRoot(repo);
+  const file = worktreeCleanupPlanPath(repoRoot, planId);
+  assertContainedRealPath(repoRoot, file);
+  const stat = fs.statSync(file);
+  if (!stat.isFile() || stat.size > 2 * 1024 * 1024)
+    throw new Error("Cleanup plan is not a bounded regular file.");
+  const plan = JSON.parse(fs.readFileSync(file, "utf-8"));
+  if (plan.version !== 1 || plan.planId !== planId || plan.repoRoot !== repoRoot || !Number.isFinite(plan.createdAt) || !Number.isFinite(plan.expiresAt) || plan.createdAt > now || plan.expiresAt <= now && !fs.existsSync(file.replace(/\.json$/, ".claim")) || plan.expiresAt - plan.createdAt !== WORKTREE_CLEANUP_PLAN_TTL_MS)
+    throw new Error("Cleanup plan is invalid, expired, or belongs to another repository.");
+  if (!Array.isArray(plan.entries) || plan.entries.length > 512 || !Array.isArray(plan.baseDirs) || plan.baseDirs.length !== 1 || !plan.baseDirs.every((item) => typeof item === "string" && path.isAbsolute(item)) || !Array.isArray(plan.metadataPaths) || !plan.metadataPaths.every((item) => typeof item === "string" && path.isAbsolute(item)) || !Array.isArray(plan.pruneCandidates))
+    throw new Error("Cleanup plan has invalid inventory fields.");
+  const paths = new Set;
+  for (const entry of plan.entries) {
+    if (!entry || typeof entry.path !== "string" || !path.isAbsolute(entry.path) || typeof entry.branch !== "string" || !["remove", "keep", "unknown"].includes(entry.decision) || !entry.preconditions || entry.preconditions.path !== entry.path || entry.preconditions.branch !== entry.branch || !Array.isArray(entry.reasons) || !entry.reasons.every((reason) => typeof reason === "string") || paths.has(entry.path))
+      throw new Error("Cleanup plan has invalid or duplicate entries.");
+    paths.add(entry.path);
+  }
+  const hash = createHash("sha256").update(JSON.stringify(worktreeCleanupContentPayload(plan))).digest("hex");
+  if (plan.contentHash !== hash)
+    throw new Error("Cleanup plan content hash does not match; create and review a fresh plan.");
+  return plan;
+}
+function recordRemoval(entry) {
+  const manifest = readParallelHandoffManifest(entry.handoffPath);
+  if (!manifest || manifest.runId !== entry.runId)
+    throw new Error("Handoff ownership changed before recording removal.");
+  const tasks = manifest.groups.flatMap((group) => group.cleanup.tasks).filter((task) => task.index === entry.taskIndex && samePath(path.resolve(path.dirname(entry.handoffPath), task.path), entry.path) && task.branch === entry.branch);
+  if (tasks.length !== 1)
+    throw new Error("Handoff task no longer identifies exactly one removed worktree.");
+  if (tasks[0].worktreeRemoved)
+    return;
+  tasks[0].worktreeRemoved = true;
+  tasks[0].branchRemoved = false;
+  tasks[0].preserved = true;
+  tasks[0].reason = "reviewed cleanup removed worktree; local branch retained";
+  manifest.updatedAt = Date.now();
+  writePrivateAtomicJson(entry.handoffPath, manifest);
+}
+export async function applyReviewedCleanupPlan(input) {
+  if (!input.authorized)
+    throw new Error("Worktree cleanup requires discardWorktree authorization.");
+  return withWorktreeTransaction(() => withRepositoryWorktreeLock(input.repo, async () => {
+    const plan = loadReviewedCleanupPlan(input.repo, input.planId);
+    const claimPath = worktreeCleanupPlanPath(plan.repoRoot, plan.planId).replace(/\.json$/, ".claim");
+    const receiptPath = path.join(claimPath, "receipt.json");
+    assertContainedRealPath(plan.repoRoot, path.dirname(claimPath));
+    try {
+      fs.mkdirSync(claimPath, { mode: 448 });
+    } catch (error) {
+      if (error.code !== "EEXIST")
+        throw error;
+      assertContainedRealPath(plan.repoRoot, receiptPath);
+      const receipt = JSON.parse(fs.readFileSync(receiptPath, "utf-8"));
+      if (receipt.version !== 1 || receipt.planId !== plan.planId || receipt.repoRoot !== plan.repoRoot || receipt.contentHash !== plan.contentHash || !Array.isArray(receipt.entries) || !["applying", "complete", "partial"].includes(receipt.state))
+        throw new Error("Claimed cleanup plan has an invalid receipt; inspect it before creating a fresh plan.");
+      for (const entry of plan.entries.filter((entry) => receipt.state !== "complete" && entry.decision === "remove" && receipt.entries.some((item) => (item?.state === "removing" || item?.state === "removed") && item.path === entry.path && item.branch === entry.branch))) {
+        await new Promise((resolve) => setImmediate(resolve));
+        input.signal?.throwIfAborted();
+        try {
+          fs.lstatSync(entry.path);
+          continue;
+        } catch (error) {
+          if (error.code !== "ENOENT")
+            throw error;
+        }
+        if (!isRegisteredCleanupWorktree(plan.repoRoot, entry.path) && entry.handoffPath) {
+          const item = receipt.entries.find((item) => item.path === entry.path && item.branch === entry.branch);
+          if (item.state === "removing") {
+            item.state = "removed";
+            item.reason = "interrupted removal reconciled; local branch retained";
+            writePrivateAtomicJson(receiptPath, receipt);
+          }
+          withHandoffWriteLock(entry.handoffPath, () => recordRemoval(entry));
+        }
+      }
+      return { receipt, receiptPath, reused: true };
+    }
+    const receipt = { version: 1, planId: plan.planId, repoRoot: plan.repoRoot, contentHash: plan.contentHash, state: "applying", startedAt: Date.now(), entries: [] };
+    writePrivateAtomicJson(receiptPath, receipt);
+    try {
+      const selected = input.select?.(plan);
+      for (const entry of plan.entries.filter((item) => item.decision === "remove")) {
+        await new Promise((resolve) => setImmediate(resolve));
+        input.signal?.throwIfAborted();
+        if (selected && !selected.has(entry.path)) {
+          receipt.entries.push({ path: entry.path, branch: entry.branch, state: "kept", reason: "outside the current retention excess" });
+        } else {
+          try {
+            if (!entry.handoffPath)
+              throw new Error("Reviewed entry has no handoff ownership.");
+            withHandoffWriteLock(entry.handoffPath, () => {
+              const manifest = readParallelHandoffManifest(entry.handoffPath);
+              if (!manifest || manifest.runId !== entry.runId)
+                throw new Error("Handoff ownership changed before cleanup validation.");
+              const fresh = buildWorktreeCleanupPlan({ repo: plan.repoRoot, candidatePaths: [entry.path], handoffPaths: plan.metadataPaths, worktreeBaseDir: path.dirname(plan.baseDirs[0]), foregroundRunOwnership: input.foregroundRunOwnership });
+              const candidate = fresh.entries.find((item) => item.path === entry.path);
+              if (fresh.warnings?.some((warning) => /capped|failed to inspect/.test(warning)) || !candidate || candidate.decision !== "remove" || candidate.handoffPath !== entry.handoffPath || candidate.runId !== entry.runId || candidate.taskIndex !== entry.taskIndex || candidate.patchPath !== entry.patchPath || JSON.stringify(candidate.preconditions) !== JSON.stringify(entry.preconditions)) {
+                receipt.entries.push({ path: entry.path, branch: entry.branch, state: "kept", reason: candidate?.reasons.join("; ") || "reviewed ownership or Git facts changed" });
+                return;
+              }
+              input.signal?.throwIfAborted();
+              const journalEntry = { path: entry.path, branch: entry.branch, state: "removing", reason: "removal prepared; outcome not yet recorded" };
+              receipt.entries.push(journalEntry);
+              writePrivateAtomicJson(receiptPath, receipt);
+              const removed = spawnSync("git", ["-C", plan.repoRoot, "worktree", "remove", "--", entry.path], { encoding: "utf-8", windowsHide: true });
+              if (removed.status !== 0)
+                throw new Error(removed.error?.message || removed.stderr.trim() || "git worktree remove failed");
+              journalEntry.state = "removed";
+              journalEntry.reason = "worktree removed; local branch retained";
+              writePrivateAtomicJson(receiptPath, receipt);
+              recordRemoval(entry);
+            });
+          } catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            const removed = receipt.entries.find((item) => item.path === entry.path && item.state === "removed");
+            if (removed) {
+              removed.reason += `; removal bookkeeping failed: ${reason}`;
+              receipt.error = reason;
+            } else {
+              const pending = receipt.entries.find((item) => item.path === entry.path && item.state === "removing");
+              if (pending) {
+                pending.reason += `; operation failed: ${reason}`;
+                receipt.error = reason;
+              } else
+                receipt.entries.push({ path: entry.path, branch: entry.branch, state: "failed", reason });
+            }
+          }
+        }
+        writePrivateAtomicJson(receiptPath, receipt);
+      }
+      receipt.state = !receipt.error && receipt.entries.every((entry) => entry.state === "removed") ? "complete" : "partial";
+    } catch (error) {
+      receipt.state = "partial";
+      receipt.error = error instanceof Error ? error.message : String(error);
+    }
+    receipt.completedAt = Date.now();
+    writePrivateAtomicJson(receiptPath, receipt);
+    return { receipt, receiptPath, reused: false };
+  }, { signal: input.signal }));
+}
+export function formatCleanupReceipt(result) {
+  const { receipt } = result;
+  return [`Worktree cleanup ${receipt.planId}: ${receipt.state}${result.reused ? " (previous receipt; plan not replayed)" : ""}`, "Local branches retained.", ...receipt.entries.map((entry) => `- ${entry.path}: ${entry.state}; ${entry.reason}`), ...receipt.error ? [receipt.error] : [], `Receipt: ${result.receiptPath}`].join(`
+`);
+}

package/extensions/dm-subagents/src/runs/shared/worktree-cleanup-plan.js

@@ -7,7 +7,7 @@ import { writeAtomicJson } from "../../shared/atomic-json.js";
 import { PROJECT_SUBAGENTS_RELATIVE_DIR } from "../../shared/artifacts.js";
 import { DEFAULT_STALE_TERMINAL_ACTIVE_MARKER_MS, activeRunMarkerAgeMs } from "../background/active-run-index.js";
 import { getAgentDir } from "../../shared/utils.js";
-import { isTerminalParallelHandoffChildStatus } from "./parallel-handoff.js";
+import { isTerminalParallelHandoffChildStatus, readParallelHandoffManifest } from "./parallel-handoff.js";
 import { MACHINE_DIFF_OPTIONS, validateWorktreePatchRepresentsCurrentWorktree } from "./worktree.js";
 export const WORKTREE_CLEANUP_PLAN_VERSION = 1;
 export const WORKTREE_CLEANUP_PLAN_TTL_MS = 30 * 60 * 1000;
@@ -68,15 +68,15 @@ function comparablePath(candidate) {
   const normalized = path.normalize(canonical);
   return process.platform === "win32" ? normalized.toLowerCase() : normalized;
 }
-function samePath(left, right) {
+export function samePath(left, right) {
   if (comparablePath(left) === comparablePath(right))
     return true;
   if (process.platform !== "win32")
     return false;
   try {
-    const leftStat = fs.statSync(left);
-    const rightStat = fs.statSync(right);
-    return leftStat.dev !== 0 && leftStat.ino !== 0 && leftStat.dev === rightStat.dev && leftStat.ino === rightStat.ino;
+    const leftStat = fs.statSync(left, { bigint: true });
+    const rightStat = fs.statSync(right, { bigint: true });
+    return leftStat.dev !== 0n && leftStat.ino !== 0n && leftStat.dev === rightStat.dev && leftStat.ino === rightStat.ino;
   } catch {
     return false;
   }
@@ -105,7 +105,7 @@ function validatePlanId(planId) {
   }
   return planId;
 }
-function resolveRepoRoot(repo) {
+export function resolveCleanupRepoRoot(repo) {
   const requested = path.resolve(repo);
   const toplevel = runGitChecked(requested, ["rev-parse", "--show-toplevel"]);
   return realpathExisting(toplevel);
@@ -154,6 +154,8 @@ export function parseGitWorktreeList(raw) {
       current.branch = line.slice("branch refs/heads/".length).trim();
     else if (line === "detached")
       delete current.branch;
+    else if (line === "locked" || line.startsWith("locked "))
+      current.locked = true;
     else if (line.startsWith("prunable "))
       current.prunable = line.slice("prunable ".length).trim();
   }
@@ -166,6 +168,9 @@ function listGitWorktrees(repoRoot) {
     throw new Error(gitFailure(result, `git -C ${repoRoot} worktree list --porcelain`));
   return parseGitWorktreeList(result.stdout);
 }
+export function isRegisteredCleanupWorktree(repoRoot, candidate) {
+  return listGitWorktrees(repoRoot).some((tree) => samePath(tree.path, candidate));
+}
 function readJsonFile(filePath) {
   return JSON.parse(fs.readFileSync(filePath, "utf-8"));
 }
@@ -179,8 +184,8 @@ function readManifest(manifestPath) {
       return { error: `parallel handoff manifest is not a regular file: ${manifestPath}` };
     if (stat.size > MAX_METADATA_FILE_BYTES)
       return { error: `parallel handoff manifest exceeds the ${MAX_METADATA_FILE_BYTES}-byte limit: ${manifestPath}` };
-    const parsed = readJsonFile(manifestPath);
-    if (!isRecord(parsed) || parsed.version !== 1 || !Array.isArray(parsed.groups)) {
+    const parsed = readParallelHandoffManifest(manifestPath);
+    if (!parsed) {
       return { error: `invalid parallel handoff manifest version or groups: ${manifestPath}` };
     }
     return { manifest: parsed };
@@ -288,12 +293,10 @@ function loadMetadata(input, repoRoot) {
   const discovered = discoverHandoffPaths(repoRoot, input);
   const records = [];
   const warnings = [...discovered.warnings];
-  const explicitPath = input.handoffPath ? path.isAbsolute(input.handoffPath) ? path.resolve(input.handoffPath) : path.resolve(repoRoot, input.handoffPath) : undefined;
   for (const manifestPath of discovered.paths) {
     const result = readManifest(manifestPath);
     if (!result.manifest) {
-      if (explicitPath && comparablePath(manifestPath) === comparablePath(explicitPath))
-        warnings.push(result.error);
+      warnings.push(result.error);
       continue;
     }
     const manifestRoot = resolveExistingPath(manifestPath);
@@ -379,7 +382,7 @@ function inspectRunState(record, now, foregroundRunOwnership) {
   return { kind: "terminal" };
 }
 function buildEntryBase(input) {
-  const recordedBaseDir = path.dirname(input.path);
+  const recordedBaseDir = input.metadata?.task.recordedBaseDir;
   const patchPath = input.metadata ? metadataPatchPath(input.metadata) : undefined;
   return {
     path: input.path,
@@ -397,7 +400,7 @@ function buildEntryBase(input) {
       branch: input.branch,
       ...input.git?.head ? { worktreeHead: input.git.head } : {},
       ...input.metadata?.group.baseCommit ? { baseCommit: input.metadata.group.baseCommit } : {},
-      recordedBaseDir,
+      ...recordedBaseDir ? { recordedBaseDir } : {},
       targetRef: input.targetHead
     }
   };
@@ -485,8 +488,16 @@ function buildManagedEntry(input) {
     return blockedEntry(entry, "ineligible", "keep", `worktree real path is inside DM extensions directory '${extensionsDir}'`);
   if (input.containmentInvalid || !pathInside(baseDir, pathInspection.realpath, true))
     return blockedEntry(entry, "ineligible", "keep", `worktree real path is outside configured base directory '${baseDir}'`);
+  const recordedBaseDir = record.task.recordedBaseDir;
+  if (typeof recordedBaseDir !== "string" || !path.isAbsolute(recordedBaseDir))
+    return blockedEntry(entry, "unknown", "keep", "handoff metadata has no creation-time base directory proof");
+  const creationRelative = path.relative(recordedBaseDir, pathInspection.realpath);
+  if (!creationRelative || creationRelative === ".." || creationRelative.startsWith(`..${path.sep}`) || path.isAbsolute(creationRelative))
+    return blockedEntry(entry, "ineligible", "keep", `worktree real path is outside its creation-time recorded base directory '${recordedBaseDir}'`);
   if (rootPath === comparablePath(pathInspection.realpath))
     return blockedEntry(entry, "ineligible", "keep", "worktree is the repository root");
+  if (git.locked)
+    return blockedEntry(entry, "ineligible", "keep", "Git worktree is locked");
   if (!git.branch)
     return blockedEntry(entry, "unknown", "unknown", "detached worktrees have no metadata-recorded branch");
   if (record.task.branch !== git.branch)
@@ -511,6 +522,9 @@ function buildManagedEntry(input) {
   if (git.branch === input.otherGitRecords.find((candidate) => comparablePath(candidate.path) === rootPath)?.branch) {
     return blockedEntry(entry, "ineligible", "keep", "metadata-recorded branch is checked out at the repository root");
   }
+  const retainedSession = record.child.sessionPath ?? record.status?.steps?.[record.child.index]?.sessionFile ?? record.status?.sessionFile;
+  if (typeof retainedSession === "string" && retainedSession.trim())
+    return blockedEntry(entry, "ineligible", "keep", "retained child resume still has a recorded session dependency");
   const runState = inspectRunState(record, input.now, foregroundRunOwnership);
   if (runState.kind === "unknown")
     return blockedEntry(entry, "unknown", "unknown", runState.reason ?? "owning run state is unknown");
@@ -539,6 +553,11 @@ function buildManagedEntry(input) {
   entry.preconditions.statusDigest = status.digest;
   if (status.output && status.output.trim())
     return blockedEntry(entry, "dirty", "keep", "worktree has uncommitted or untracked changes");
+  const ignored = runGit(worktreePath, ["ls-files", "--others", "--ignored", "--exclude-standard", "-z"]);
+  if (ignored.status !== 0)
+    return blockedEntry(entry, "unknown", "unknown", `ignored-file inspection failed: ${gitFailure(ignored, "git ls-files")}`);
+  if (ignored.stdout)
+    return blockedEntry(entry, "ineligible", "keep", "worktree contains ignored files; cleanup preserves them");
   const diff = runGit(worktreePath, ["diff", "--quiet", ...MACHINE_DIFF_OPTIONS, resolvedBase.value, "--"]);
   if (diff.status !== 0 && diff.status !== 1)
     return blockedEntry(entry, "unknown", "unknown", `git diff safety check failed: ${gitFailure(diff, "git diff")}`);
@@ -583,7 +602,7 @@ function buildManagedEntry(input) {
   }
   entry.state = "safe";
   entry.decision = "remove";
-  entry.willDeleteBranch = branchTipIsAncestor;
+  entry.willDeleteBranch = false;
   entry.reasons.push("extension-owned metadata, terminal run, contained clean worktree, and local divergence checks passed");
   if (!branchTipIsAncestor)
     entry.reasons.push("local branch tip is not an ancestor of target HEAD; future apply must retain the branch");
@@ -601,7 +620,7 @@ function buildMissingMetadataEntry(input) {
   const entry = buildEntryBase({ path: pathValue, branch: input.record.task.branch, source: "metadata", metadata: input.record, targetHead: input.targetHead });
   return blockedEntry(entry, "stale", "unknown", "handoff metadata records a worktree that is not present in Git worktree state");
 }
-function contentPayload(plan) {
+export function worktreeCleanupContentPayload(plan) {
   return {
     version: plan.version,
     repoRoot: plan.repoRoot,
@@ -618,7 +637,7 @@ function stableEntrySort(left, right) {
 export function buildWorktreeCleanupPlan(input) {
   if (typeof input.repo !== "string" || !input.repo.trim())
     throw new Error("worktree cleanup plan requires a repository path");
-  const repoRoot = resolveRepoRoot(input.repo);
+  const repoRoot = resolveCleanupRepoRoot(input.repo);
   const now = input.now ?? Date.now();
   if (!Number.isFinite(now))
     throw new Error("worktree cleanup plan timestamp must be finite");
@@ -639,6 +658,8 @@ export function buildWorktreeCleanupPlan(input) {
   const entries = [];
   const matchedMetadataRecords = new Set;
   for (const git of linkedGit) {
+    if (input.candidatePaths && !input.candidatePaths.some((candidate) => samePath(candidate, git.path)))
+      continue;
     const records = metadataByPath.get(comparablePath(git.path)) ?? (git.branch ? metadata.records.filter((record) => record.task.branch === git.branch && samePath(metadataRecordPath(record), git.path)) : []);
     if (records.length === 1)
       matchedMetadataRecords.add(records[0]);
@@ -682,7 +703,7 @@ export function buildWorktreeCleanupPlan(input) {
     pruneCandidates,
     ...warnings.length ? { warnings: [...new Set(warnings)].sort() } : {}
   };
-  const contentHash = sha256(JSON.stringify(contentPayload(basePlan)));
+  const contentHash = sha256(JSON.stringify(worktreeCleanupContentPayload(basePlan)));
   const planId = validatePlanId(input.planId ?? randomUUID());
   return {
     ...basePlan,
@@ -708,7 +729,6 @@ function formatPlanEntry(entry) {
 export function formatWorktreeCleanupPlan(created) {
   const { plan, planPath } = created;
   const removable = plan.entries.filter((entry) => entry.decision === "remove");
-  const branches = removable.filter((entry) => entry.willDeleteBranch === true);
   const kept = plan.entries.filter((entry) => entry.decision === "keep");
   const unknown = plan.entries.filter((entry) => entry.decision === "unknown");
   const section = (title, entries, empty) => [
@@ -723,7 +743,7 @@ export function formatWorktreeCleanupPlan(created) {
     "",
     ...section("Will remove", removable, "none"),
     "",
-    ...section("Will delete local branches", branches, "none (plan-only mode; no branch will be deleted)"),
+    "Local branches: all retained, including after apply.",
     "",
     ...section("Will keep, with reasons", kept, "none"),
     "",
@@ -734,7 +754,8 @@ export function formatWorktreeCleanupPlan(created) {
     ...plan.warnings?.length ? ["", "Warnings", ...plan.warnings.map((warning) => `- ${warning}`)] : [],
     "",
     `Plan saved: ${planPath}`,
-    "Plan-only mode: no worktrees or branches were removed."
+    "Plan-only mode: no worktrees or branches were removed.",
+    `Apply this reviewed plan: subagent({ action: "worktree.cleanup", options: { mode: "apply", repo: ${JSON.stringify(plan.repoRoot)}, planId: ${JSON.stringify(plan.planId)} } })`
   ];
   return lines.join(`
 `);

package/extensions/dm-subagents/src/runs/shared/worktree-lock.js

@@ -0,0 +1,38 @@
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { tryLease } from "../../shared/file-lease.js";
+export function withHandoffWriteLock(manifestPath, action) {
+  const requested = path.resolve(manifestPath);
+  fs.mkdirSync(path.dirname(requested), { recursive: true });
+  const absolute = path.join(fs.realpathSync.native(path.dirname(requested)), path.basename(requested));
+  const release = tryLease(`${absolute}.write-lock`);
+  if (!release)
+    throw new Error(`Handoff is being updated or cleaned: ${absolute}. Retry after the current operation completes.`);
+  try {
+    return action();
+  } finally {
+    release();
+  }
+}
+export async function withRepositoryWorktreeLock(repo, action, options = {}) {
+  const git = spawnSync("git", ["-C", repo, "rev-parse", "--path-format=absolute", "--git-common-dir"], { encoding: "utf-8", windowsHide: true });
+  if (git.status !== 0)
+    throw new Error(git.error?.message || git.stderr.trim() || "Cannot resolve Git common directory.");
+  const lockPath = path.join(fs.realpathSync(git.stdout.trim()), "dm-subagents-worktree.lock");
+  const deadline = Date.now() + (options.waitMs ?? 2000);
+  while (true) {
+    options.signal?.throwIfAborted();
+    const release = tryLease(lockPath);
+    if (release) {
+      try {
+        return await action();
+      } finally {
+        release();
+      }
+    }
+    if (Date.now() >= deadline)
+      throw new Error("Repository worktree maintenance is busy; retry later.");
+    await new Promise((resolve) => setTimeout(resolve, 25));
+  }
+}