@imdeadpool/guardex 7.0.21 → 7.0.23

package/src/output/index.js

@@ -87,6 +87,62 @@ function detectAutoFinishSummaryStatus(summary) {
   return null;
 }
 
+const AUTO_FINISH_DETAIL_PRIORITY = new Map([
+  ['fail', 0],
+  ['pending', 1],
+  ['done', 2],
+  ['skip', 3],
+]);
+
+function autoFinishDetailPriority(status) {
+  return AUTO_FINISH_DETAIL_PRIORITY.get(status) ?? AUTO_FINISH_DETAIL_PRIORITY.size;
+}
+
+function sortAutoFinishDetailEntries(details) {
+  return details
+    .map((detail, index) => {
+      const status = detectAutoFinishDetailStatus(detail) || 'other';
+      return {
+        detail,
+        index,
+        status,
+        priority: autoFinishDetailPriority(status),
+      };
+    })
+    .sort((left, right) => (left.priority - right.priority) || (left.index - right.index));
+}
+
+function summarizeHiddenAutoFinishDetails(hiddenEntries) {
+  const counts = new Map();
+  for (const entry of hiddenEntries) {
+    counts.set(entry.status, (counts.get(entry.status) || 0) + 1);
+  }
+
+  const segments = ['fail', 'pending', 'done', 'skip', 'other']
+    .map((status) => {
+      const count = counts.get(status) || 0;
+      return count > 0 ? `${status}=${count}` : '';
+    })
+    .filter(Boolean);
+
+  let status = null;
+  if ((counts.get('fail') || 0) > 0) {
+    status = 'fail';
+  } else if ((counts.get('pending') || 0) > 0) {
+    status = 'pending';
+  } else if ((counts.get('done') || 0) > 0) {
+    status = 'done';
+  } else if ((counts.get('skip') || 0) > 0) {
+    status = 'skip';
+  }
+
+  return {
+    status,
+    message: `… ${hiddenEntries.length} more branch result(s) hidden: ${segments.join(', ')}. ` +
+      'Re-run with --verbose-auto-finish for full details.',
+  };
+}
+
 function statusDot(status) {
   if (status === 'active') {
     return colorize('●', '32');
@@ -281,7 +337,14 @@ function detectRecoverableAutoFinishConflict(message) {
   if (/rebase --continue/i.test(text) && /rebase --abort/i.test(text)) {
     return {
       rawLabel: 'auto-finish requires manual rebase.',
-      summary: 'manual rebase required in the source-probe worktree; run rebase --continue or rebase --abort',
+      summary: 'manual rebase required on the branch before auto-finish can continue',
+    };
+  }
+
+  if (/Reattach '.+' in a regular worktree, then rebase it onto origin\/.+ manually\./i.test(text)) {
+    return {
+      rawLabel: 'auto-finish requires manual rebase.',
+      summary: 'manual rebase required on the branch before auto-finish can continue',
     };
   }
 
@@ -353,15 +416,19 @@ function printAutoFinishSummary(summary, options = {}) {
         detectAutoFinishSummaryStatus(summary),
       ),
     );
-    const visibleDetails = verbose ? details : details.slice(0, detailLimit).map(summarizeAutoFinishDetail);
+    const sortedDetailEntries = verbose ? [] : sortAutoFinishDetailEntries(details);
+    const visibleDetails = verbose
+      ? details
+      : sortedDetailEntries.slice(0, detailLimit).map((entry) => summarizeAutoFinishDetail(entry.detail));
     for (const detail of visibleDetails) {
       console.log(colorizeDoctorOutput(`[${TOOL_NAME}]   ${detail}`, detectAutoFinishDetailStatus(detail)));
     }
-    if (!verbose && details.length > visibleDetails.length) {
+    if (!verbose && sortedDetailEntries.length > visibleDetails.length) {
+      const hiddenSummary = summarizeHiddenAutoFinishDetails(sortedDetailEntries.slice(visibleDetails.length));
       console.log(
         colorizeDoctorOutput(
-          `[${TOOL_NAME}]   … ${details.length - visibleDetails.length} more branch result(s). Re-run with --verbose-auto-finish for full details.`,
-          'warn',
+          `[${TOOL_NAME}]   ${hiddenSummary.message}`,
+          hiddenSummary.status || 'warn',
         ),
       );
     }

package/src/report/session-severity.js

@@ -0,0 +1,213 @@
+const TASK_SIZE_UPPER_BOUNDS = {
+  'narrow-patch': 1_800_000,
+  'medium-change': 4_000_000,
+  'large-change': 8_000_000,
+};
+
+const TASK_SIZE_VALUES = new Set(Object.keys(TASK_SIZE_UPPER_BOUNDS));
+const FRAGMENTATION_PRESET_SCORES = {
+  clean: 0,
+  'few-extra-checks': 5,
+  'repeated-follow-ups': 10,
+  looping: 18,
+  'dominant-loop': 25,
+};
+const FINISH_PATH_PRESET_SCORES = {
+  'clear-early': 0,
+  'minor-hesitation': 5,
+  'late-decision': 10,
+  reopening: 15,
+};
+const POST_PROOF_PRESET_SCORES = {
+  'stops-soon': 0,
+  'small-tail': 5,
+  'notable-tail': 10,
+  'heavy-tail': 15,
+};
+const DRIVER_TIE_BREAK = ['fragmentation', 'writeStdin', 'finishPath', 'postProof', 'cost'];
+const DRIVER_LABELS = {
+  cost: 'cost vs expected scope',
+  fragmentation: 'turn fragmentation',
+  writeStdin: 'write_stdin churn',
+  finishPath: 'finish-path discipline',
+  postProof: 'post-proof drift',
+};
+
+function parseRequiredPositiveInteger(name, rawValue, { allowZero = true } = {}) {
+  const parsed = Number.parseInt(String(rawValue || ''), 10);
+  if (!Number.isFinite(parsed) || (!allowZero && parsed <= 0) || (allowZero && parsed < 0)) {
+    throw new Error(`${name} requires ${allowZero ? 'a non-negative integer' : 'a positive integer'} value`);
+  }
+  return parsed;
+}
+
+function parseBooleanFlag(name, rawValue) {
+  const normalized = String(rawValue || '').trim().toLowerCase();
+  if (normalized === 'yes' || normalized === 'true' || normalized === '1') {
+    return true;
+  }
+  if (normalized === 'no' || normalized === 'false' || normalized === '0') {
+    return false;
+  }
+  throw new Error(`${name} requires yes/no (or true/false, 1/0)`);
+}
+
+function clampScore(value, min, max) {
+  return Math.max(min, Math.min(max, Math.round(value)));
+}
+
+function parseTaskSize(rawTaskSize) {
+  const normalized = String(rawTaskSize || '').trim();
+  if (!TASK_SIZE_VALUES.has(normalized)) {
+    throw new Error(`--task-size must be one of: ${Array.from(TASK_SIZE_VALUES).join(', ')}`);
+  }
+  return normalized;
+}
+
+function resolveExpectedUpperBound(taskSize, rawExpectedBound) {
+  if (rawExpectedBound) {
+    return parseRequiredPositiveInteger('--expected-bound', rawExpectedBound, { allowZero: false });
+  }
+  return TASK_SIZE_UPPER_BOUNDS[taskSize];
+}
+
+function scoreCost(tokens, expectedUpperBound) {
+  const ratio = tokens / expectedUpperBound;
+  if (ratio <= 1.0) return 0;
+  if (ratio <= 1.5) return 5;
+  if (ratio <= 2.5) return 10;
+  if (ratio <= 4.0) return 18;
+  if (ratio <= 6.0) return 24;
+  return 30;
+}
+
+function scoreFragmentation(execCount, override) {
+  if (override) {
+    if (Object.prototype.hasOwnProperty.call(FRAGMENTATION_PRESET_SCORES, override)) {
+      return FRAGMENTATION_PRESET_SCORES[override];
+    }
+    return clampScore(parseRequiredPositiveInteger('--fragmentation', override), 0, 25);
+  }
+  if (execCount <= 4) return 0;
+  if (execCount <= 8) return 5;
+  if (execCount <= 16) return 10;
+  if (execCount <= 28) return 18;
+  return 25;
+}
+
+function scoreWriteStdin(writeStdinCount) {
+  if (writeStdinCount <= 0) return 0;
+  if (writeStdinCount <= 3) return 5;
+  if (writeStdinCount <= 6) return 10;
+  return 15;
+}
+
+function scoreFinishPath(completionBeforeTail, override) {
+  if (override) {
+    if (Object.prototype.hasOwnProperty.call(FINISH_PATH_PRESET_SCORES, override)) {
+      return FINISH_PATH_PRESET_SCORES[override];
+    }
+    return clampScore(parseRequiredPositiveInteger('--finish-path', override), 0, 15);
+  }
+  return completionBeforeTail ? 0 : 5;
+}
+
+function scorePostProof(completionBeforeTail, override) {
+  if (override) {
+    if (Object.prototype.hasOwnProperty.call(POST_PROOF_PRESET_SCORES, override)) {
+      return POST_PROOF_PRESET_SCORES[override];
+    }
+    return clampScore(parseRequiredPositiveInteger('--post-proof', override), 0, 15);
+  }
+  return completionBeforeTail ? 0 : 10;
+}
+
+function labelForTotal(total) {
+  if (total <= 15) return 'Healthy';
+  if (total <= 30) return 'Mildly fragmented';
+  if (total <= 50) return 'Inefficient';
+  if (total <= 75) return 'Runaway';
+  return 'Catastrophic';
+}
+
+function buildSessionSeverityReport(options) {
+  const taskSize = parseTaskSize(options.taskSize);
+  const tokens = parseRequiredPositiveInteger('--tokens', options.tokens);
+  const execCount = parseRequiredPositiveInteger('--exec-count', options.execCount);
+  const writeStdinCount = parseRequiredPositiveInteger('--write-stdin-count', options.writeStdinCount);
+  const completionBeforeTail = parseBooleanFlag('--completion-before-tail', options.completionBeforeTail);
+  const expectedUpperBound = resolveExpectedUpperBound(taskSize, options.expectedBound);
+  const costRatio = tokens / expectedUpperBound;
+  const scores = {
+    cost: scoreCost(tokens, expectedUpperBound),
+    fragmentation: scoreFragmentation(execCount, options.fragmentation),
+    writeStdin: scoreWriteStdin(writeStdinCount),
+    finishPath: scoreFinishPath(completionBeforeTail, options.finishPath),
+    postProof: scorePostProof(completionBeforeTail, options.postProof),
+  };
+  const total = scores.cost + scores.fragmentation + scores.writeStdin + scores.finishPath + scores.postProof;
+  const label = labelForTotal(total);
+  const rankedDimensions = Object.entries(scores)
+    .map(([key, score]) => ({ key, score, label: DRIVER_LABELS[key] }))
+    .filter((entry) => entry.score > 0)
+    .sort((left, right) => {
+      if (right.score !== left.score) {
+        return right.score - left.score;
+      }
+      return DRIVER_TIE_BREAK.indexOf(left.key) - DRIVER_TIE_BREAK.indexOf(right.key);
+    });
+  const primaryDriver = rankedDimensions[0] ? rankedDimensions[0].label : 'none';
+  const secondaries = rankedDimensions.slice(1).map((entry) => entry.label);
+
+  return {
+    taskSize,
+    expectedUpperBound,
+    tokens,
+    execCount,
+    writeStdinCount,
+    completionBeforeTail,
+    costRatio,
+    scores: {
+      ...scores,
+      total,
+    },
+    label,
+    primaryDriver,
+    secondaries,
+    outputLine: `Score ${total}/100 — ${label}. Primary: ${primaryDriver}. Secondaries: ${
+      secondaries.length > 0 ? secondaries.join(', ') : 'none'
+    }.`,
+  };
+}
+
+function renderSessionSeverityReport(report) {
+  return [
+    report.outputLine,
+    '',
+    `Task size: ${report.taskSize}`,
+    `Expected upper bound: ${report.expectedUpperBound}`,
+    `Actual tokens: ${report.tokens}`,
+    `Exec count: ${report.execCount}`,
+    `write_stdin count: ${report.writeStdinCount}`,
+    `Completion before tail churn: ${report.completionBeforeTail ? 'yes' : 'no'}`,
+    `Cost ratio: ${report.costRatio.toFixed(2)}x`,
+    '',
+    `A. Cost vs expected scope: ${report.scores.cost}`,
+    `B. Turn fragmentation: ${report.scores.fragmentation}`,
+    `C. write_stdin churn: ${report.scores.writeStdin}`,
+    `D. Finish-path discipline: ${report.scores.finishPath}`,
+    `E. Post-proof drift: ${report.scores.postProof}`,
+    '',
+    `Total: ${report.scores.total}`,
+    `Label: ${report.label}`,
+    `Primary driver: ${report.primaryDriver}`,
+    `Secondary drivers: ${report.secondaries.length > 0 ? report.secondaries.join(', ') : 'none'}`,
+  ].join('\n');
+}
+
+module.exports = {
+  TASK_SIZE_UPPER_BOUNDS,
+  buildSessionSeverityReport,
+  renderSessionSeverityReport,
+  labelForTotal,
+};

package/src/sandbox/index.js

@@ -1,68 +1,317 @@
-function createSandboxApi(deps) {
-  const {
-    protectedBaseWriteBlock,
-    runInstallInternal,
-    ensureSetupProtectedBranches,
-    ensureParentWorkspaceView,
-    buildParentWorkspaceView,
-    runFixInternal,
-  } = deps;
-
-  function assertProtectedMainWriteAllowed(options, commandName) {
-    const blocked = protectedBaseWriteBlock(options);
-    if (!blocked) {
-      return;
+const {
+  fs,
+  path,
+  SHORT_TOOL_NAME,
+  LOCK_FILE_RELATIVE,
+  defaultAgentWorktreeRelativeDir,
+} = require('../context');
+const { run, runPackageAsset } = require('../core/runtime');
+const {
+  resolveRepoRoot,
+  currentBranchName,
+  readProtectedBranches,
+  gitRefExists,
+  ensureRepoBranch,
+} = require('../git');
+
+function hasGuardexBootstrapFiles(repoRoot) {
+  const required = [
+    'AGENTS.md',
+    '.githooks/pre-commit',
+    '.githooks/pre-push',
+    LOCK_FILE_RELATIVE,
+  ];
+  return required.every((relativePath) => require('../context').fs.existsSync(path.join(repoRoot, relativePath)));
+}
+
+function protectedBaseWriteBlock(options, { requireBootstrap = true } = {}) {
+  if (options.dryRun || options.allowProtectedBaseWrite) {
+    return null;
+  }
+
+  const repoRoot = resolveRepoRoot(options.target);
+  if (requireBootstrap && !hasGuardexBootstrapFiles(repoRoot)) {
+    return null;
+  }
+
+  const branch = currentBranchName(repoRoot);
+  if (branch !== 'main') {
+    return null;
+  }
+
+  const protectedBranches = readProtectedBranches(repoRoot);
+  if (!protectedBranches.includes(branch)) {
+    return null;
+  }
+
+  return {
+    repoRoot,
+    branch,
+  };
+}
+
+function assertProtectedMainWriteAllowed(options, commandName) {
+  const blocked = protectedBaseWriteBlock(options);
+  if (!blocked) {
+    return;
+  }
+
+  throw new Error(
+    `${commandName} blocked on protected branch '${blocked.branch}' in an initialized repo.\n` +
+    `Keep local '${blocked.branch}' pull-only: start an agent branch/worktree first:\n` +
+    `  gx branch start "<task>" "codex"\n` +
+    `Override once only when intentional: --allow-protected-base-write`,
+  );
+}
+
+function extractAgentBranchStartMetadata(output) {
+  const branchMatch = String(output || '').match(/^\[agent-branch-start\] Created branch: (.+)$/m);
+  const worktreeMatch = String(output || '').match(/^\[agent-branch-start\] Worktree: (.+)$/m);
+  return {
+    branch: branchMatch ? branchMatch[1].trim() : '',
+    worktreePath: worktreeMatch ? worktreeMatch[1].trim() : '',
+  };
+}
+
+function resolveSandboxTarget(repoRoot, worktreePath, targetPath) {
+  const resolvedTarget = path.resolve(targetPath);
+  const relativeTarget = path.relative(repoRoot, resolvedTarget);
+  if (relativeTarget.startsWith('..') || path.isAbsolute(relativeTarget)) {
+    throw new Error(`sandbox target must stay inside repo root: ${resolvedTarget}`);
+  }
+  if (!relativeTarget || relativeTarget === '.') {
+    return worktreePath;
+  }
+  return path.join(worktreePath, relativeTarget);
+}
+
+function appendManagedForceArgs(args, options) {
+  if (!options.force) {
+    return;
+  }
+  args.push('--force');
+  for (const managedPath of options.forceManagedPaths || []) {
+    args.push(managedPath);
+  }
+}
+
+function buildSandboxSetupArgs(options, sandboxTarget) {
+  const args = ['setup', '--target', sandboxTarget, '--no-global-install', '--no-recursive'];
+  appendManagedForceArgs(args, options);
+  if (options.skipAgents) args.push('--skip-agents');
+  if (options.skipPackageJson) args.push('--skip-package-json');
+  if (options.skipGitignore) args.push('--no-gitignore');
+  if (options.dryRun) args.push('--dry-run');
+  return args;
+}
+
+function isSpawnFailure(result) {
+  return Boolean(result?.error) && typeof result?.status !== 'number';
+}
+
+function protectedBaseSandboxBranchPrefix() {
+  const now = new Date();
+  const stamp = [
+    now.getUTCFullYear(),
+    String(now.getUTCMonth() + 1).padStart(2, '0'),
+    String(now.getUTCDate()).padStart(2, '0'),
+  ].join('') + '-' + [
+    String(now.getUTCHours()).padStart(2, '0'),
+    String(now.getUTCMinutes()).padStart(2, '0'),
+    String(now.getUTCSeconds()).padStart(2, '0'),
+  ].join('');
+  return `agent/gx/${stamp}`;
+}
+
+function protectedBaseSandboxWorktreePath(repoRoot, branchName) {
+  return path.join(repoRoot, defaultAgentWorktreeRelativeDir(), branchName.replace(/\//g, '__'));
+}
+
+function resolveProtectedBaseSandboxStartRef(repoRoot, baseBranch) {
+  run('git', ['-C', repoRoot, 'fetch', 'origin', baseBranch, '--quiet'], { timeout: 20_000 });
+  if (gitRefExists(repoRoot, `refs/remotes/origin/${baseBranch}`)) {
+    return `origin/${baseBranch}`;
+  }
+  if (gitRefExists(repoRoot, `refs/heads/${baseBranch}`)) {
+    return baseBranch;
+  }
+  if (currentBranchName(repoRoot) === baseBranch) {
+    return null;
+  }
+  throw new Error(`Unable to find base ref for sandbox bootstrap: ${baseBranch}`);
+}
+
+function startProtectedBaseSandboxFallback(blocked, sandboxSuffix) {
+  const branchPrefix = protectedBaseSandboxBranchPrefix();
+  let selectedBranch = '';
+  let selectedWorktreePath = '';
+
+  for (let attempt = 0; attempt < 30; attempt += 1) {
+    const suffix = attempt === 0 ? sandboxSuffix : `${attempt + 1}-${sandboxSuffix}`;
+    const candidateBranch = `${branchPrefix}-${suffix}`;
+    const candidateWorktreePath = protectedBaseSandboxWorktreePath(blocked.repoRoot, candidateBranch);
+    if (gitRefExists(blocked.repoRoot, `refs/heads/${candidateBranch}`)) {
+      continue;
     }
+    if (fs.existsSync(candidateWorktreePath)) {
+      continue;
+    }
+    selectedBranch = candidateBranch;
+    selectedWorktreePath = candidateWorktreePath;
+    break;
+  }
 
-    throw new Error(
-      `${commandName} blocked on protected branch '${blocked.branch}' in an initialized repo.\n` +
-      `Keep local '${blocked.branch}' pull-only: start an agent branch/worktree first:\n` +
-      `  gx branch start "<task>" "codex"\n` +
-      `Override once only when intentional: --allow-protected-base-write`,
-    );
+  if (!selectedBranch || !selectedWorktreePath) {
+    throw new Error('Unable to allocate unique sandbox branch/worktree');
   }
 
-  function runSetupBootstrapInternal(options) {
-    const installPayload = runInstallInternal(options);
-    installPayload.operations.push(
-      ensureSetupProtectedBranches(installPayload.repoRoot, Boolean(options.dryRun)),
-    );
+  fs.mkdirSync(path.dirname(selectedWorktreePath), { recursive: true });
+  const startRef = resolveProtectedBaseSandboxStartRef(blocked.repoRoot, blocked.branch);
+  const addArgs = startRef
+    ? ['-C', blocked.repoRoot, 'worktree', 'add', '-b', selectedBranch, selectedWorktreePath, startRef]
+    : ['-C', blocked.repoRoot, 'worktree', 'add', '--orphan', selectedWorktreePath];
+  const addResult = run('git', addArgs);
+  if (isSpawnFailure(addResult)) {
+    throw addResult.error;
+  }
+  if (addResult.status !== 0) {
+    throw new Error((addResult.stderr || addResult.stdout || 'failed to create sandbox').trim());
+  }
 
-    let parentWorkspace = null;
-    if (options.parentWorkspaceView) {
-      installPayload.operations.push(
-        ensureParentWorkspaceView(installPayload.repoRoot, Boolean(options.dryRun)),
+  if (!startRef) {
+    const renameResult = run(
+      'git',
+      ['-C', selectedWorktreePath, 'branch', '-m', selectedBranch],
+      { timeout: 20_000 },
+    );
+    if (isSpawnFailure(renameResult)) {
+      throw renameResult.error;
+    }
+    if (renameResult.status !== 0) {
+      throw new Error(
+        (renameResult.stderr || renameResult.stdout || 'failed to name orphan sandbox branch').trim(),
       );
-      if (!options.dryRun) {
-        parentWorkspace = buildParentWorkspaceView(installPayload.repoRoot);
-      }
     }
+  }
+
+  return {
+    metadata: {
+      branch: selectedBranch,
+      worktreePath: selectedWorktreePath,
+    },
+    stdout:
+      `[agent-branch-start] Created branch: ${selectedBranch}\n` +
+      `[agent-branch-start] Worktree: ${selectedWorktreePath}\n`,
+    stderr: addResult.stderr || '',
+  };
+}
+
+function startProtectedBaseSandbox(blocked, { taskName, sandboxSuffix }) {
+  if (sandboxSuffix === 'gx-doctor') {
+    return startProtectedBaseSandboxFallback(blocked, sandboxSuffix);
+  }
+
+  const startResult = runPackageAsset('branchStart', [
+    '--task',
+    taskName,
+    '--agent',
+    SHORT_TOOL_NAME,
+    '--base',
+    blocked.branch,
+  ], { cwd: blocked.repoRoot });
+  if (isSpawnFailure(startResult)) {
+    throw startResult.error;
+  }
+  if (startResult.status !== 0) {
+    return startProtectedBaseSandboxFallback(blocked, sandboxSuffix);
+  }
 
-    const fixPayload = runFixInternal({
-      target: installPayload.repoRoot,
-      dryRun: options.dryRun,
-      force: options.force,
-      forceManagedPaths: options.forceManagedPaths,
-      dropStaleLocks: true,
-      skipAgents: options.skipAgents,
-      skipPackageJson: options.skipPackageJson,
-      skipGitignore: options.skipGitignore,
-      allowProtectedBaseWrite: options.allowProtectedBaseWrite,
-    });
-
-    return {
-      installPayload,
-      fixPayload,
-      parentWorkspace,
-    };
+  const metadata = extractAgentBranchStartMetadata(startResult.stdout);
+  const currentBranch = currentBranchName(blocked.repoRoot);
+  const worktreePath = metadata.worktreePath ? path.resolve(metadata.worktreePath) : '';
+  const repoRootPath = path.resolve(blocked.repoRoot);
+  const hasSafeWorktree = Boolean(worktreePath) && worktreePath !== repoRootPath;
+  const branchChanged = Boolean(currentBranch) && currentBranch !== blocked.branch;
+
+  if (!hasSafeWorktree || branchChanged) {
+    const restoreResult = ensureRepoBranch(blocked.repoRoot, blocked.branch);
+    if (!restoreResult.ok) {
+      const detail = [restoreResult.stderr, restoreResult.stdout].filter(Boolean).join('\n').trim();
+      throw new Error(
+        `sandbox startup switched protected base checkout and could not restore '${blocked.branch}'.` +
+        (detail ? `\n${detail}` : ''),
+      );
+    }
+    return startProtectedBaseSandboxFallback(blocked, sandboxSuffix);
   }
 
   return {
-    assertProtectedMainWriteAllowed,
-    runSetupBootstrapInternal,
+    metadata,
+    stdout: startResult.stdout || '',
+    stderr: startResult.stderr || '',
+  };
+}
+
+function cleanupProtectedBaseSandbox(repoRoot, metadata) {
+  const result = {
+    worktree: 'skipped',
+    branch: 'skipped',
+    note: 'missing sandbox metadata',
   };
+
+  if (!metadata?.worktreePath || !metadata?.branch) {
+    return result;
+  }
+
+  if (fs.existsSync(metadata.worktreePath)) {
+    const removeResult = run(
+      'git',
+      ['-C', repoRoot, 'worktree', 'remove', '--force', metadata.worktreePath],
+      { timeout: 30_000 },
+    );
+    if (isSpawnFailure(removeResult)) {
+      throw removeResult.error;
+    }
+    if (removeResult.status !== 0) {
+      throw new Error(
+        (removeResult.stderr || removeResult.stdout || 'failed to remove sandbox worktree').trim(),
+      );
+    }
+    result.worktree = 'removed';
+  } else {
+    result.worktree = 'missing';
+  }
+
+  if (gitRefExists(repoRoot, `refs/heads/${metadata.branch}`)) {
+    const branchDeleteResult = run(
+      'git',
+      ['-C', repoRoot, 'branch', '-D', metadata.branch],
+      { timeout: 20_000 },
+    );
+    if (isSpawnFailure(branchDeleteResult)) {
+      throw branchDeleteResult.error;
+    }
+    if (branchDeleteResult.status !== 0) {
+      throw new Error(
+        (branchDeleteResult.stderr || branchDeleteResult.stdout || 'failed to delete sandbox branch').trim(),
+      );
+    }
+    result.branch = 'deleted';
+  } else {
+    result.branch = 'missing';
+  }
+
+  result.note = 'sandbox worktree pruned';
+  return result;
 }
 
 module.exports = {
-  createSandboxApi,
+  protectedBaseWriteBlock,
+  assertProtectedMainWriteAllowed,
+  extractAgentBranchStartMetadata,
+  resolveSandboxTarget,
+  buildSandboxSetupArgs,
+  isSpawnFailure,
+  startProtectedBaseSandbox,
+  cleanupProtectedBaseSandbox,
 };