@duckmind/dm-windows-x64 0.61.4 → 0.61.9

package/extensions/dm-subagents/src/runs/shared/parallel-handoff.js

@@ -0,0 +1,653 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { writeAtomicJson } from "../../shared/atomic-json.js";
+import { stableJsonDigest } from "../../shared/launch-contract.js";
+import { cleanupWorktrees } from "./worktree.js";
+import { assertWorkflowLaneKey, normalizeWorkflowLaneMetadata } from "./lane-metadata.js";
+function optionalIdentity(value, label) {
+  if (value === undefined)
+    return;
+  if (typeof value !== "string" || !value.trim())
+    throw new Error(`${label} must be a non-empty string.`);
+  return value.trim();
+}
+function nonNegativeIndex(value, label) {
+  if (!Number.isSafeInteger(value) || value < 0)
+    throw new Error(`${label} must be a non-negative integer.`);
+  return value;
+}
+function normalizeLaneBinding(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error(`${label} must be an object.`);
+  const binding = value;
+  const unknown = Object.keys(binding).filter((field) => !["index", "taskIndex", "workflowKey", "runId", "lane"].includes(field));
+  if (unknown.length > 0)
+    throw new Error(`${label} has unsupported fields: ${unknown.join(", ")}.`);
+  const index = nonNegativeIndex(binding.index, `${label}.index`);
+  const taskIndex = nonNegativeIndex(binding.taskIndex, `${label}.taskIndex`);
+  const workflowKey = optionalIdentity(binding.workflowKey, `${label}.workflowKey`);
+  const runId = optionalIdentity(binding.runId, `${label}.runId`);
+  const lane = normalizeWorkflowLaneMetadata(binding.lane, `${label}.lane`);
+  assertWorkflowLaneKey(lane, workflowKey, `${label}.lane`);
+  return {
+    index,
+    taskIndex,
+    ...workflowKey ? { workflowKey } : {},
+    ...runId ? { runId } : {},
+    ...lane ? { lane } : {}
+  };
+}
+function validateManifestIdentity(parsed, manifestPath) {
+  if (parsed.version !== 1 || !Array.isArray(parsed.groups)) {
+    throw new Error(`Invalid parallel handoff manifest: ${manifestPath}`);
+  }
+  if (typeof parsed.runId !== "string" || !parsed.runId.trim())
+    throw new Error(`Invalid parallel handoff manifest '${manifestPath}': runId must be a non-empty string.`);
+  parsed.runId = parsed.runId.trim();
+  const workflowKeys = new Set;
+  const childRunIds = new Set;
+  const childIndexes = new Set;
+  for (const [groupIndex, group] of parsed.groups.entries()) {
+    if (!group || typeof group !== "object" || !Array.isArray(group.children) || !group.cleanup || !Array.isArray(group.cleanup.tasks))
+      throw new Error(`Invalid parallel handoff manifest '${manifestPath}': groups[${groupIndex}] is malformed.`);
+    if (group.laneBindings !== undefined) {
+      if (!Array.isArray(group.laneBindings))
+        throw new Error(`Invalid parallel handoff manifest '${manifestPath}': groups[${groupIndex}].laneBindings must be an array.`);
+      const taskIndexes = new Set;
+      const cleanupIndexes = new Set(group.cleanup.tasks.map((task) => task.index));
+      group.laneBindings = group.laneBindings.map((binding, bindingIndex) => {
+        const normalized = normalizeLaneBinding(binding, `Invalid parallel handoff manifest '${manifestPath}': groups[${groupIndex}].laneBindings[${bindingIndex}]`);
+        if (taskIndexes.has(normalized.taskIndex))
+          throw new Error(`Invalid parallel handoff manifest '${manifestPath}': groups[${groupIndex}] has duplicate lane binding taskIndex ${normalized.taskIndex}.`);
+        if (!cleanupIndexes.has(normalized.taskIndex))
+          throw new Error(`Invalid parallel handoff manifest '${manifestPath}': groups[${groupIndex}].laneBindings[${bindingIndex}] has no cleanup task for taskIndex ${normalized.taskIndex}.`);
+        taskIndexes.add(normalized.taskIndex);
+        return normalized;
+      });
+    }
+    const taskIndexes = new Set;
+    for (const [childIndex, child] of group.children.entries()) {
+      if (!child || typeof child !== "object" || !child.patch || typeof child.patch !== "object")
+        throw new Error(`Invalid parallel handoff manifest '${manifestPath}': groups[${groupIndex}].children[${childIndex}] is malformed.`);
+      const childRecord = child;
+      const index = nonNegativeIndex(childRecord.index, `Invalid parallel handoff manifest '${manifestPath}': groups[${groupIndex}].children[${childIndex}].index`);
+      const taskIndex = nonNegativeIndex(childRecord.taskIndex, `Invalid parallel handoff manifest '${manifestPath}': groups[${groupIndex}].children[${childIndex}].taskIndex`);
+      if (taskIndexes.has(taskIndex))
+        throw new Error(`Invalid parallel handoff manifest '${manifestPath}': groups[${groupIndex}] has duplicate child taskIndex ${taskIndex}.`);
+      taskIndexes.add(taskIndex);
+      if (childIndexes.has(index))
+        throw new Error(`Invalid parallel handoff manifest '${manifestPath}': duplicate child index ${index}.`);
+      childIndexes.add(index);
+      if (!group.cleanup.tasks.some((task) => task.index === taskIndex))
+        throw new Error(`Invalid parallel handoff manifest '${manifestPath}': groups[${groupIndex}].children[${childIndex}] has no cleanup task for taskIndex ${taskIndex}.`);
+      const workflowKey = optionalIdentity(childRecord.workflowKey, `Invalid parallel handoff manifest '${manifestPath}': groups[${groupIndex}].children[${childIndex}].workflowKey`);
+      const runId = optionalIdentity(childRecord.runId, `Invalid parallel handoff manifest '${manifestPath}': groups[${groupIndex}].children[${childIndex}].runId`);
+      const lane = normalizeWorkflowLaneMetadata(childRecord.lane, `Invalid parallel handoff manifest '${manifestPath}': groups[${groupIndex}].children[${childIndex}].lane`);
+      assertWorkflowLaneKey(lane, workflowKey, `Invalid parallel handoff manifest '${manifestPath}': groups[${groupIndex}].children[${childIndex}].lane`);
+      if (workflowKey && workflowKeys.has(workflowKey))
+        throw new Error(`Invalid parallel handoff manifest '${manifestPath}': duplicate workflow key '${workflowKey}'.`);
+      if (workflowKey)
+        workflowKeys.add(workflowKey);
+      if (runId && childRunIds.has(runId))
+        throw new Error(`Invalid parallel handoff manifest '${manifestPath}': duplicate child run id '${runId}'.`);
+      if (runId)
+        childRunIds.add(runId);
+      if (lane)
+        childRecord.lane = lane;
+      if (workflowKey)
+        childRecord.workflowKey = workflowKey;
+      if (runId)
+        childRecord.runId = runId;
+      childRecord.index = index;
+      childRecord.taskIndex = taskIndex;
+    }
+  }
+  return parsed;
+}
+export function readParallelHandoffManifest(manifestPath) {
+  if (!fs.existsSync(manifestPath))
+    return;
+  const parsed = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+  return validateManifestIdentity(parsed, manifestPath);
+}
+export function resolveParallelHandoffChild(input) {
+  const manifest = readParallelHandoffManifest(input.manifestPath);
+  if (!manifest)
+    return;
+  if (manifest.runId !== input.runId)
+    throw new Error(`Managed worktree handoff belongs to run '${manifest.runId}', not '${input.runId}'.`);
+  const workflowKey = input.workflowKey?.trim() || undefined;
+  const childRunId = input.childRunId?.trim() || undefined;
+  if (!workflowKey && !childRunId)
+    throw new Error("Parallel handoff child resolution requires workflowKey or childRunId.");
+  const matches = manifest.groups.flatMap((group) => group.children.map((child) => ({ group, child }))).filter(({ child }) => {
+    if (workflowKey && child.workflowKey !== workflowKey)
+      return false;
+    if (childRunId && child.runId !== childRunId)
+      return false;
+    return true;
+  });
+  if (matches.length > 1)
+    throw new Error(`Parallel handoff has multiple children matching workflow identity${workflowKey ? ` '${workflowKey}'` : ` '${childRunId}'`}.`);
+  return matches[0];
+}
+function resolveExistingPath(candidate) {
+  try {
+    return fs.realpathSync(candidate);
+  } catch {
+    return path.resolve(candidate);
+  }
+}
+function pathInside(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === "" || relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+export function resolveRetainedWorktreeCwd(manifestPath, runId, childIndex) {
+  const manifest = readParallelHandoffManifest(manifestPath);
+  if (!manifest)
+    return;
+  if (manifest.runId !== runId)
+    throw new Error(`Managed worktree handoff belongs to run '${manifest.runId}', not '${runId}'.`);
+  const match = manifest.groups.flatMap((group) => group.children.map((child) => ({ group, child }))).find(({ child }) => child.index === childIndex);
+  if (!match)
+    return;
+  const cleanup = match.group.cleanup.tasks.find((task) => task.index === match.child.taskIndex);
+  if (!cleanup)
+    throw new Error(`Async run '${runId}' child ${childIndex} has no managed worktree cleanup record.`);
+  const relativeCwd = path.relative(resolveExistingPath(match.group.repoRoot), resolveExistingPath(manifest.cwd));
+  if (path.isAbsolute(relativeCwd) || relativeCwd === ".." || relativeCwd.startsWith(`..${path.sep}`))
+    throw new Error(`Async run '${runId}' has an invalid managed worktree cwd.`);
+  const requiredCwd = path.join(cleanup.path, relativeCwd);
+  if (cleanup.worktreeRemoved || cleanup.branchRemoved)
+    throw new Error(`Async run '${runId}' required managed worktree was removed: ${requiredCwd}`);
+  let worktreeRoot = "";
+  let resolvedRequiredCwd = "";
+  try {
+    const rootStat = fs.lstatSync(cleanup.path);
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink())
+      throw new Error("worktree root is not a directory");
+    worktreeRoot = fs.realpathSync(cleanup.path);
+    if (!fs.statSync(requiredCwd).isDirectory())
+      throw new Error("path is not a directory");
+    resolvedRequiredCwd = fs.realpathSync(requiredCwd);
+  } catch (error) {
+    throw new Error(`Async run '${runId}' required managed worktree cwd is missing: ${requiredCwd}`, { cause: error instanceof Error ? error : undefined });
+  }
+  if (!pathInside(worktreeRoot, resolvedRequiredCwd))
+    throw new Error(`Async run '${runId}' has an invalid managed worktree cwd.`);
+  return requiredCwd;
+}
+function referenceFor(manifestPath, manifest) {
+  const children = manifest.groups.flatMap((group) => group.children);
+  return {
+    version: 1,
+    path: manifestPath,
+    groupCount: manifest.groups.length,
+    childCount: children.length,
+    changedPatches: children.filter((child) => child.patch.changed).length,
+    cleanupState: manifest.groups.every((group) => group.cleanup.state === "complete") ? "complete" : "partial",
+    ...Object.prototype.hasOwnProperty.call(manifest, "cleanupEligibility") ? { cleanupEligibility: trustedStoredCleanupEligibility(manifest) } : {}
+  };
+}
+const COMMIT_PATTERN = /^[0-9a-f]{40}$/i;
+const MANIFEST_DIGEST_PATTERN = /^[0-9a-f]{64}$/i;
+const MAX_ATTESTATION_ACTOR_LENGTH = 128;
+const MAX_ATTESTATION_TIMESTAMP_LENGTH = 64;
+const MAX_SUPERSESSION_ID_LENGTH = 128;
+function boundedString(value, label, maxBytes) {
+  if (typeof value !== "string" || !value.trim())
+    throw new Error(`${label} must be a non-empty string.`);
+  const normalized = value.trim();
+  if (normalized.includes(`
+`) || normalized.includes("\r"))
+    throw new Error(`${label} must not contain newlines.`);
+  if (Buffer.byteLength(normalized, "utf-8") > maxBytes)
+    throw new Error(`${label} must be at most ${maxBytes} bytes.`);
+  return normalized;
+}
+function commitString(value, label) {
+  const normalized = boundedString(value, label, 64).toLowerCase();
+  if (!COMMIT_PATTERN.test(normalized))
+    throw new Error(`${label} must be a full 40-character commit SHA.`);
+  return normalized;
+}
+function manifestDigestString(value, label) {
+  const normalized = boundedString(value, label, 64).toLowerCase();
+  if (!MANIFEST_DIGEST_PATTERN.test(normalized))
+    throw new Error(`${label} must be a full 64-character SHA-256 digest.`);
+  return normalized;
+}
+function manifestFactsDigest(manifest) {
+  return stableJsonDigest({
+    version: manifest.version,
+    runId: manifest.runId,
+    mode: manifest.mode,
+    source: manifest.source,
+    cwd: manifest.cwd,
+    groups: manifest.groups
+  });
+}
+function attestationTimestamp(value) {
+  const normalized = boundedString(value, "attestedAt", MAX_ATTESTATION_TIMESTAMP_LENGTH);
+  if (!Number.isFinite(Date.parse(normalized)))
+    throw new Error("attestedAt must be a valid timestamp.");
+  return normalized;
+}
+function normalizeMergeEvidence(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("merge must be an object.");
+  const merge = value;
+  const prNumber = merge.prNumber;
+  if (typeof prNumber !== "number" || !Number.isInteger(prNumber) || prNumber < 1)
+    throw new Error("merge.prNumber must be a positive integer.");
+  const treeEquivalent = merge.treeEquivalent;
+  if (treeEquivalent !== true && treeEquivalent !== false && treeEquivalent !== "unknown")
+    throw new Error("merge.treeEquivalent must be true, false, or 'unknown'.");
+  const postMergeChecks = merge.postMergeChecks;
+  if (postMergeChecks !== "recorded" && postMergeChecks !== "unknown")
+    throw new Error("merge.postMergeChecks must be 'recorded' or 'unknown'.");
+  return {
+    prNumber,
+    reviewedHead: commitString(merge.reviewedHead, "merge.reviewedHead"),
+    mergeCommit: commitString(merge.mergeCommit, "merge.mergeCommit"),
+    treeEquivalent,
+    postMergeChecks,
+    attestedBy: boundedString(merge.attestedBy, "merge.attestedBy", MAX_ATTESTATION_ACTOR_LENGTH),
+    attestedAt: attestationTimestamp(merge.attestedAt),
+    ...merge.manifestDigest === undefined ? {} : { manifestDigest: manifestDigestString(merge.manifestDigest, "merge.manifestDigest") }
+  };
+}
+function normalizeSupersessionEvidence(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("supersession must be an object.");
+  const supersession = value;
+  return {
+    supersededBy: boundedString(supersession.supersededBy, "supersession.supersededBy", MAX_SUPERSESSION_ID_LENGTH),
+    attestedBy: boundedString(supersession.attestedBy, "supersession.attestedBy", MAX_ATTESTATION_ACTOR_LENGTH),
+    attestedAt: attestationTimestamp(supersession.attestedAt),
+    ...supersession.manifestDigest === undefined ? {} : { manifestDigest: manifestDigestString(supersession.manifestDigest, "supersession.manifestDigest") }
+  };
+}
+function normalizeStoredCleanupEligibility(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return { state: "unknown" };
+  const eligibility = value;
+  if (eligibility.state === "active" || eligibility.state === "terminal-eligible" || eligibility.state === "superseded-eligible" || eligibility.state === "unknown") {
+    return { state: eligibility.state };
+  }
+  if (eligibility.state === "terminal-blocked" && typeof eligibility.reason === "string" && eligibility.reason.trim() && !eligibility.reason.includes(`
+`) && !eligibility.reason.includes("\r")) {
+    return { state: "terminal-blocked", reason: eligibility.reason.trim().slice(0, 256) };
+  }
+  return { state: "unknown" };
+}
+const STORED_CHILD_STATUSES = new Set(["pending", "running", "completed", "complete", "failed", "paused", "stopped", "detached", "rejected"]);
+export function isTerminalParallelHandoffChildStatus(status) {
+  return status === "completed" || status === "complete" || status === "failed" || status === "paused" || status === "stopped" || status === "rejected";
+}
+function hasValidStoredLaneShape(manifest) {
+  if (!manifest || typeof manifest !== "object" || manifest.version !== 1 || typeof manifest.runId !== "string" || !manifest.runId.trim() || !Array.isArray(manifest.groups) || manifest.groups.length === 0)
+    return false;
+  let hasManagedTask = false;
+  const valid = manifest.groups.every((group) => {
+    if (!group || typeof group !== "object" || typeof group.baseCommit !== "string" || !group.baseCommit.trim() || typeof group.repoRoot !== "string" || !group.repoRoot.trim())
+      return false;
+    const cleanup = group.cleanup;
+    if (!cleanup || typeof cleanup !== "object" || cleanup.state !== "complete" && cleanup.state !== "partial" || !Array.isArray(cleanup.tasks) || !Array.isArray(group.children))
+      return false;
+    if (cleanup.tasks.some((task) => !task || typeof task !== "object" || !Number.isSafeInteger(task.index) || task.index < 0 || typeof task.path !== "string" || !task.path.trim() || typeof task.branch !== "string" || !task.branch.trim()))
+      return false;
+    if (cleanup.tasks.length > 0)
+      hasManagedTask = true;
+    return group.children.every((child) => Boolean(child) && typeof child === "object" && typeof child.status === "string" && STORED_CHILD_STATUSES.has(child.status));
+  });
+  return valid && hasManagedTask;
+}
+function trustedStoredCleanupEligibility(manifest) {
+  const eligibility = normalizeStoredCleanupEligibility(manifest.cleanupEligibility);
+  if (!hasValidStoredLaneShape(manifest))
+    return { state: "unknown" };
+  if (hasActiveChildren(manifest))
+    return { state: "active" };
+  if (eligibility.state === "active")
+    return cleanupEligibilityForEvidence(manifest);
+  if (eligibility.state === "terminal-eligible" || eligibility.state === "superseded-eligible") {
+    const current = cleanupEligibilityForEvidence(manifest);
+    if (current.state === eligibility.state || current.state === "terminal-blocked" && / evidence is stale$/.test(current.reason))
+      return current;
+    return { state: "unknown" };
+  }
+  return eligibility;
+}
+function hasActiveChildren(manifest) {
+  return Array.isArray(manifest.groups) && manifest.groups.some((group) => {
+    if (!group || typeof group !== "object")
+      return false;
+    const children = Array.isArray(group.children) ? group.children : [];
+    if (children.length === 0 && Array.isArray(group.cleanup?.tasks) && group.cleanup.tasks.length > 0)
+      return true;
+    return children.some((child) => !child || typeof child !== "object" || !isTerminalParallelHandoffChildStatus(child.status));
+  });
+}
+function hasManagedWorktreeTasks(manifest) {
+  return manifest.groups.length > 0 && manifest.groups.some((group) => Array.isArray(group.cleanup?.tasks) && group.cleanup.tasks.length > 0);
+}
+function validateManifestForLaneEvidence(manifest, laneId) {
+  if (manifest.runId !== laneId)
+    throw new Error(`Lane '${laneId}' does not match manifest run '${manifest.runId}'.`);
+  if (!hasValidStoredLaneShape(manifest))
+    throw new Error("Lane manifest is malformed.");
+  if (!manifest.groups.length || !hasManagedWorktreeTasks(manifest))
+    throw new Error("Lane manifest has no managed worktree tasks.");
+  if (hasActiveChildren(manifest))
+    throw new Error("Lane has an active child owner; merge evidence must be recorded after local reconciliation.");
+  for (const group of manifest.groups) {
+    if (typeof group.repoRoot !== "string" || !group.repoRoot.trim())
+      throw new Error("Lane manifest has no valid repository root.");
+    if (group.cleanup.state !== "complete" && group.cleanup.state !== "partial")
+      throw new Error("Lane manifest has an invalid cleanup state.");
+    if (!Array.isArray(group.cleanup.tasks) || group.cleanup.tasks.some((task) => typeof task.path !== "string" || !task.path.trim() || typeof task.branch !== "string" || !task.branch.trim())) {
+      throw new Error("Lane manifest has an invalid cleanup task.");
+    }
+    if (!Array.isArray(group.children))
+      throw new Error("Lane manifest has invalid child records.");
+    for (const child of group.children) {
+      if (!STORED_CHILD_STATUSES.has(child.status)) {
+        throw new Error("Lane manifest has an invalid child status.");
+      }
+    }
+  }
+}
+function cleanupEligibilityForEvidence(manifest) {
+  if (hasActiveChildren(manifest))
+    return { state: "active" };
+  let merge;
+  if (manifest.merge) {
+    try {
+      merge = normalizeMergeEvidence(manifest.merge);
+    } catch {
+      return { state: "terminal-blocked", reason: "stored merge evidence is invalid" };
+    }
+  }
+  if (manifest.supersession) {
+    try {
+      const supersession = normalizeSupersessionEvidence(manifest.supersession);
+      if (supersession.manifestDigest !== manifestFactsDigest(manifest))
+        return { state: "terminal-blocked", reason: "stored supersession evidence is stale" };
+    } catch {
+      return { state: "terminal-blocked", reason: "stored supersession evidence is invalid" };
+    }
+    return { state: "superseded-eligible" };
+  }
+  if (!merge)
+    return { state: "terminal-blocked", reason: "no merge or supersession evidence recorded" };
+  if (merge.manifestDigest !== manifestFactsDigest(manifest))
+    return { state: "terminal-blocked", reason: "stored merge evidence is stale" };
+  if (merge.treeEquivalent !== true) {
+    return { state: "terminal-blocked", reason: merge.treeEquivalent === "unknown" ? "merged tree equivalence was not attested" : "merged tree is not equivalent to the reviewed head" };
+  }
+  if (merge.postMergeChecks !== "recorded")
+    return { state: "terminal-blocked", reason: "required post-merge checks were not recorded" };
+  return { state: "terminal-eligible" };
+}
+function sameMergeEvidence(left, right) {
+  return left.prNumber === right.prNumber && left.reviewedHead === right.reviewedHead && left.mergeCommit === right.mergeCommit && left.treeEquivalent === right.treeEquivalent && left.postMergeChecks === right.postMergeChecks && left.attestedBy === right.attestedBy && left.attestedAt === right.attestedAt;
+}
+function sameSupersessionEvidence(left, right) {
+  return left.supersededBy === right.supersededBy && left.attestedBy === right.attestedBy && left.attestedAt === right.attestedAt;
+}
+function firstRepositoryRoot(manifest) {
+  const repoRoot = Array.isArray(manifest.groups) ? manifest.groups[0]?.repoRoot : undefined;
+  return typeof repoRoot === "string" && repoRoot.trim() ? repoRoot.trim() : undefined;
+}
+function formatCleanupCommand(manifestPath, manifest) {
+  const repoRoot = firstRepositoryRoot(manifest);
+  return repoRoot ? `subagent({ action: "worktree.cleanup", repo: ${JSON.stringify(repoRoot)}, handoffPath: ${JSON.stringify(manifestPath)}, mode: "plan" })` : undefined;
+}
+export function formatStoredParallelHandoffCleanup(manifestPath, manifest) {
+  let stored = manifest;
+  if (!stored) {
+    try {
+      stored = readParallelHandoffManifest(manifestPath);
+    } catch {
+      stored = undefined;
+    }
+  }
+  if (!stored)
+    return ["Cleanup eligibility: unknown", "Reason: lane manifest is missing or invalid; removal is not safe.", `Plan command: subagent({ action: "worktree.cleanup", handoffPath: ${JSON.stringify(manifestPath)}, mode: "plan" })`].join(`
+`);
+  const eligibility = trustedStoredCleanupEligibility(stored);
+  const lines = [`Cleanup eligibility: ${eligibility.state}`];
+  if (eligibility.state === "terminal-blocked")
+    lines.push(`Reason: ${eligibility.reason}`);
+  if (eligibility.state === "unknown")
+    lines.push("Reason: stored eligibility is missing or invalid; removal is not safe.");
+  if (eligibility.state === "active")
+    lines.push("Reason: a child owner is still active; removal is not safe.");
+  const command = formatCleanupCommand(manifestPath, stored);
+  if (command)
+    lines.push(`Plan command: ${command}`);
+  return lines.join(`
+`);
+}
+export function recordParallelHandoffMerge(input) {
+  const manifest = readParallelHandoffManifest(input.manifestPath);
+  if (!manifest)
+    throw new Error(`Parallel handoff manifest not found: ${input.manifestPath}`);
+  validateManifestForLaneEvidence(manifest, boundedString(input.laneId, "laneId", MAX_SUPERSESSION_ID_LENGTH));
+  if (hasActiveChildren(manifest))
+    throw new Error("Lane has an active child owner; merge evidence must be recorded after local reconciliation.");
+  const merge = { ...normalizeMergeEvidence(input.merge), manifestDigest: manifestFactsDigest(manifest) };
+  if (manifest.merge) {
+    const existing = normalizeMergeEvidence(manifest.merge);
+    if (existing.reviewedHead !== merge.reviewedHead)
+      throw new Error(`Lane manifest is stale: reviewed head is already recorded as ${existing.reviewedHead}.`);
+    if (!sameMergeEvidence(existing, merge))
+      throw new Error("Lane manifest already contains different merge evidence for this reviewed head.");
+  }
+  const reconciled = { ...manifest, merge };
+  delete reconciled.supersession;
+  const updated = { ...reconciled, cleanupEligibility: cleanupEligibilityForEvidence(reconciled), updatedAt: input.now ?? Date.now() };
+  writeAtomicJson(input.manifestPath, updated);
+  return { manifest: updated, reference: referenceFor(input.manifestPath, updated), text: formatStoredParallelHandoffCleanup(input.manifestPath, updated) };
+}
+export function recordParallelHandoffSupersession(input) {
+  const manifest = readParallelHandoffManifest(input.manifestPath);
+  if (!manifest)
+    throw new Error(`Parallel handoff manifest not found: ${input.manifestPath}`);
+  const laneId = boundedString(input.laneId, "laneId", MAX_SUPERSESSION_ID_LENGTH);
+  validateManifestForLaneEvidence(manifest, laneId);
+  if (hasActiveChildren(manifest))
+    throw new Error("Lane has an active child owner; supersession must be recorded after local reconciliation.");
+  const supersession = { ...normalizeSupersessionEvidence(input.supersession), manifestDigest: manifestFactsDigest(manifest) };
+  if (supersession.supersededBy === laneId)
+    throw new Error("supersession.supersededBy must identify a different replacement lane.");
+  if (manifest.supersession) {
+    const existing = normalizeSupersessionEvidence(manifest.supersession);
+    if (!sameSupersessionEvidence(existing, supersession))
+      throw new Error("Lane manifest already contains different supersession evidence.");
+  }
+  const updated = { ...manifest, supersession, cleanupEligibility: cleanupEligibilityForEvidence({ ...manifest, supersession }), updatedAt: input.now ?? Date.now() };
+  writeAtomicJson(input.manifestPath, updated);
+  return { manifest: updated, reference: referenceFor(input.manifestPath, updated), text: formatStoredParallelHandoffCleanup(input.manifestPath, updated) };
+}
+function safeHandoffAgentName(agent) {
+  return agent.replace(/[^\w.-]/g, "_");
+}
+function missingDiff(input) {
+  const patchPath = path.join(path.dirname(input.manifestPath), `missing-diff-step-${input.stepIndex}-task-${input.taskIndex}-${safeHandoffAgentName(input.agent)}.patch`);
+  try {
+    fs.mkdirSync(path.dirname(patchPath), { recursive: true });
+    fs.writeFileSync(patchPath, "", "utf-8");
+  } catch {}
+  return {
+    index: input.taskIndex,
+    agent: input.agent,
+    branch: input.branch ?? "",
+    diffStat: "",
+    filesChanged: 0,
+    insertions: 0,
+    deletions: 0,
+    patchPath,
+    error: "diff artifact unavailable; no patch was captured"
+  };
+}
+export function writeParallelHandoffGroup(input) {
+  const now = input.now ?? Date.now();
+  const existing = readParallelHandoffManifest(input.manifestPath);
+  if (existing && (existing.runId !== input.runId || existing.mode !== input.mode || existing.source !== input.source)) {
+    throw new Error(`Parallel handoff manifest belongs to a different run: ${input.manifestPath}`);
+  }
+  const laneBindings = input.laneBindings?.map((binding, index) => normalizeLaneBinding(binding, `parallel handoff lane binding ${index}`));
+  if (laneBindings) {
+    const taskIndexes = new Set;
+    for (const binding of laneBindings) {
+      if (taskIndexes.has(binding.taskIndex))
+        throw new Error(`Parallel handoff has duplicate lane binding taskIndex ${binding.taskIndex}.`);
+      if (!input.setup.worktrees.some((worktree) => worktree.index === binding.taskIndex))
+        throw new Error(`Parallel handoff lane binding taskIndex ${binding.taskIndex} has no managed worktree.`);
+      if (binding.index !== input.flatStartIndex + binding.taskIndex)
+        throw new Error(`Parallel handoff lane binding index ${binding.index} does not match taskIndex ${binding.taskIndex}.`);
+      taskIndexes.add(binding.taskIndex);
+    }
+  }
+  const bindingForTask = (taskIndex) => laneBindings?.find((binding) => binding.taskIndex === taskIndex);
+  const group = {
+    stepIndex: input.stepIndex,
+    baseCommit: input.setup.baseCommit,
+    repoRoot: input.setup.cwd,
+    children: input.results.map((result, taskIndex) => {
+      const binding = bindingForTask(taskIndex);
+      const runId = optionalIdentity(result.runId ?? binding?.runId, `parallel handoff child ${taskIndex}.runId`);
+      const lane = normalizeWorkflowLaneMetadata(result.lane ?? binding?.lane, `parallel handoff child ${taskIndex}.lane`);
+      const workflowKey = optionalIdentity(result.workflowKey ?? binding?.workflowKey, `parallel handoff child ${taskIndex}.workflowKey`);
+      assertWorkflowLaneKey(lane, workflowKey, `parallel handoff child ${taskIndex}.lane`);
+      const diff = input.diffs[taskIndex] ?? missingDiff({
+        manifestPath: input.manifestPath,
+        stepIndex: input.stepIndex,
+        taskIndex,
+        agent: result.agent,
+        branch: input.setup.worktrees[taskIndex]?.branch
+      });
+      return {
+        index: input.flatStartIndex + taskIndex,
+        taskIndex,
+        agent: result.agent,
+        ...workflowKey ? { workflowKey } : {},
+        ...runId ? { runId } : {},
+        ...lane ? { lane } : {},
+        status: result.status,
+        summary: result.summary,
+        ...result.outputPath ? { outputPath: result.outputPath } : {},
+        ...result.structuredOutput !== undefined ? { structuredOutput: result.structuredOutput } : {},
+        ...result.structuredOutputPath ? { structuredOutputPath: result.structuredOutputPath } : {},
+        ...result.sessionPath ? { sessionPath: result.sessionPath } : {},
+        patch: {
+          path: diff.patchPath,
+          branch: diff.branch,
+          changed: diff.filesChanged > 0 || diff.insertions > 0 || diff.deletions > 0 || diff.diffStat.trim().length > 0,
+          diffStat: diff.diffStat,
+          filesChanged: diff.filesChanged,
+          insertions: diff.insertions,
+          deletions: diff.deletions,
+          ...diff.error ? { error: diff.error } : {}
+        }
+      };
+    }),
+    ...laneBindings && laneBindings.length > 0 && input.results.length === 0 ? { laneBindings } : {},
+    cleanup: input.cleanup ?? {
+      state: "partial",
+      pruned: false,
+      tasks: input.setup.worktrees.map((worktree) => ({
+        index: worktree.index,
+        path: worktree.path,
+        branch: worktree.branch,
+        worktreeRemoved: false,
+        branchRemoved: false,
+        preserved: true,
+        reason: "cleanup pending durable handoff capture"
+      }))
+    }
+  };
+  const groups = existing?.groups.filter((candidate) => candidate.stepIndex !== input.stepIndex) ?? [];
+  groups.push(group);
+  groups.sort((left, right) => left.stepIndex - right.stepIndex);
+  const manifestWithoutEligibility = {
+    version: 1,
+    runId: input.runId,
+    mode: input.mode,
+    source: input.source,
+    cwd: input.cwd,
+    createdAt: existing?.createdAt ?? now,
+    updatedAt: now,
+    groups,
+    ...existing && Object.hasOwn(existing, "merge") ? { merge: existing.merge } : {},
+    ...existing && Object.hasOwn(existing, "supersession") ? { supersession: existing.supersession } : {}
+  };
+  const carriesCleanupMetadata = existing !== undefined && (Object.hasOwn(existing, "merge") || Object.hasOwn(existing, "supersession") || Object.hasOwn(existing, "cleanupEligibility"));
+  const manifest = {
+    ...manifestWithoutEligibility,
+    ...carriesCleanupMetadata ? { cleanupEligibility: cleanupEligibilityForEvidence(manifestWithoutEligibility) } : {}
+  };
+  writeAtomicJson(input.manifestPath, manifest);
+  return referenceFor(input.manifestPath, manifest);
+}
+export function parallelHandoffPath(baseDir, runId) {
+  return runId ? path.join(baseDir, "handoffs", `${runId}.json`) : path.join(baseDir, "handoff.json");
+}
+export function writePendingParallelHandoff(input) {
+  return writeParallelHandoffGroup({ ...input, diffs: [], results: [] });
+}
+export function formatParallelHandoffReference(reference) {
+  return `Worktree handoff: ${reference.path} (${reference.childCount} children, ${reference.changedPatches} changed patches, cleanup ${reference.cleanupState})`;
+}
+export function formatParallelHandoffError(error) {
+  return `Worktree handoff unavailable: ${error instanceof Error ? error.message : String(error)}`;
+}
+export function discardPreservedWorktrees(manifestPath, authorization) {
+  const resolvedPath = path.resolve(manifestPath);
+  const manifest = readParallelHandoffManifest(resolvedPath);
+  if (!manifest)
+    throw new Error(`Parallel handoff manifest not found: ${resolvedPath}`);
+  let attempted = 0;
+  for (const group of manifest.groups) {
+    const pending = group.cleanup.tasks.filter((task) => task.preserved && (!task.worktreeRemoved || !task.branchRemoved));
+    if (pending.length === 0)
+      continue;
+    attempted += pending.length;
+    const report = cleanupWorktrees({
+      cwd: group.repoRoot,
+      baseCommit: group.baseCommit,
+      worktrees: pending.map((task) => ({
+        path: task.path,
+        agentCwd: task.path,
+        branch: task.branch,
+        index: task.index,
+        nodeModulesLinked: false,
+        syntheticPaths: []
+      }))
+    }, { kind: "discard", authorization });
+    const updates = new Map(report.tasks.map((task) => [task.index, task.worktreeRemoved && task.branchRemoved ? task : { ...task, preserved: true, reason: task.reason ?? "discard cleanup remains incomplete" }]));
+    group.cleanup = {
+      state: group.cleanup.tasks.every((task) => {
+        const next = updates.get(task.index) ?? task;
+        return next.worktreeRemoved && next.branchRemoved;
+      }) && report.pruned ? "complete" : "partial",
+      tasks: group.cleanup.tasks.map((task) => updates.get(task.index) ?? task),
+      pruned: report.pruned,
+      ...report.errors ? { errors: report.errors } : {}
+    };
+  }
+  manifest.updatedAt = Date.now();
+  writeAtomicJson(resolvedPath, manifest);
+  const remaining = manifest.groups.flatMap((group) => group.cleanup.tasks.map((task) => ({ group, task }))).filter(({ task }) => task.preserved && (!task.worktreeRemoved || !task.branchRemoved));
+  const lines = attempted === 0 ? [`No preserved worktrees remain in ${resolvedPath}.`] : [`Discard processed ${attempted} preserved worktree${attempted === 1 ? "" : "s"}.`, `Manifest: ${resolvedPath}`];
+  if (remaining.length > 0) {
+    lines.push("", "Some worktrees remain. Inspect and remove them manually if appropriate:");
+    for (const { group, task } of remaining) {
+      lines.push(`  git -C ${JSON.stringify(group.repoRoot)} status --short`, `  git -C ${JSON.stringify(group.repoRoot)} worktree remove --force ${JSON.stringify(task.path)}`, `  git -C ${JSON.stringify(group.repoRoot)} branch -D ${JSON.stringify(task.branch)}`);
+    }
+  }
+  return { manifest, text: lines.join(`
+`) };
+}