chainlesschain 0.162.170 → 0.162.171

package/src/gateways/ws/ws-agent-handler.js

@@ -26,6 +26,7 @@ import { runnableTaskModel } from "../../lib/runnable-provider.js";
 import { PlanState } from "../../lib/plan-mode.js";
 import { CLISlotFiller } from "../../lib/slot-filler.js";
 import { createAbortError, isAbortError } from "../../lib/abort-utils.js";
+import { createWsApprovalGate } from "./ws-approval-gate.js";
 
 export class WSAgentHandler {
   /**
@@ -34,7 +35,7 @@ export class WSAgentHandler {
    * @param {import("../../lib/interaction-adapter.js").WebSocketInteractionAdapter} options.interaction
    * @param {object} [options.db]
    */
-  constructor({ session, interaction, db }) {
+  constructor({ session, interaction, db, approvalGate }) {
     this.session = session;
     this.interaction = interaction;
     this.db = db || null;
@@ -44,6 +45,27 @@ export class WSAgentHandler {
     // P0-2: monotonic sequence for crash-safe side-effect ledger op ids. The
     // session id + a per-op nonce keep ids unique across turns and processes.
     this._sideEffectSeq = 0;
+    // P0 authority: permission-gate-over-WS. An explicitly injected gate wins
+    // (tests / embedders); otherwise one is built lazily on the first turn
+    // when CC_WS_APPROVAL_GATE=1 — its confirmer raises confirm questions
+    // over the interaction adapter WITH an approval binding the client must
+    // echo back on approve (mismatch → deny). Default (env unset, nothing
+    // injected): approvalGate stays null and loopOptions are byte-identical.
+    this._approvalGate = approvalGate || null;
+    this._approvalGateInit = Boolean(approvalGate);
+  }
+
+  /** Resolve the session's approval gate (lazy, opt-in; null when disabled). */
+  async _ensureApprovalGate() {
+    if (this._approvalGateInit) return this._approvalGate;
+    this._approvalGateInit = true;
+    if (process.env.CC_WS_APPROVAL_GATE === "1") {
+      this._approvalGate = await createWsApprovalGate({
+        sessionId: this.session.id,
+        interaction: this.interaction,
+      });
+    }
+    return this._approvalGate;
   }
 
   /**
@@ -127,6 +149,9 @@ export class WSAgentHandler {
         slotFiller,
         interaction: this.interaction,
         signal: abortController.signal,
+        // P0 authority: null unless opted in (byte-identical default — agent
+        // core already defaults `options.approvalGate || null`).
+        approvalGate: await this._ensureApprovalGate(),
       };
 
       // P0-2: crash-safe side-effect ledger for the IDE/bridge path — mirrors

package/src/gateways/ws/ws-approval-gate.js

@@ -0,0 +1,131 @@
+/**
+ * Permission-gate-over-WS — the approval-BINDING producer for the WS path.
+ *
+ * The consumer side has been wired for a while: WebSocketInteractionAdapter
+ * stores `options.binding` on a pending request, rides it out on the message,
+ * and `_resolvePending` rejects an approve whose echoed binding mismatches
+ * (deny, fail closed). What was missing is the PRODUCER: nothing on the WS
+ * path ever raised an approval request WITH a binding, because the WS agent
+ * handler wired no ApprovalGate at all (CONFIRM-tier decisions fell closed).
+ *
+ * This module supplies both halves:
+ *   - `buildWsApprovalConfirmer` — the gate confirmer that computes
+ *     `approvalBindingDigest({toolCallId, args, policyDigest})` (mirroring the
+ *     headless-stream `interactiveConfirm` producer) and asks the WS client
+ *     over the interaction adapter with the binding attached. Timeout /
+ *     disconnect / any transport error → false (fail closed).
+ *   - `createWsApprovalGate` — a session-scoped gate whose CONFIRM decisions
+ *     route to that confirmer. Policy tiers stay authoritative on the shared
+ *     singleton gate (so `sessions.policy.set` over WS keeps working and no
+ *     global confirmer is ever mutated — a per-session confirmer on the
+ *     process-wide singleton would race across concurrent WS sessions).
+ *
+ * Default byte-identical: the WS handler only builds this when
+ * `CC_WS_APPROVAL_GATE=1` (or a gate is injected); otherwise loopOptions
+ * carry `approvalGate: null` exactly as before.
+ */
+
+import { approvalBindingDigest } from "../../lib/agent-authority.js";
+
+/**
+ * Build the binding-attaching confirmer for one WS session.
+ *
+ * @param {object} opts
+ * @param {{askConfirm: Function}} opts.interaction - the session's WS adapter
+ * @param {string} opts.sessionId
+ * @returns {(ctx?: object) => Promise<boolean>}
+ */
+export function buildWsApprovalConfirmer({ interaction, sessionId }) {
+  let approvalSeq = 0;
+  return async (ctx = {}) => {
+    const command = ctx.command ?? ctx.args?.command ?? null;
+    const risk = ctx.riskLevel || ctx.risk || "unknown";
+    // Bind this approval to the exact call it authorizes (same recipe as the
+    // headless-stream producer): request identity + normalized args + the
+    // policy/rule in force. The client must echo it back on approve.
+    const binding = approvalBindingDigest({
+      toolCallId: `${sessionId}:appr-${++approvalSeq}`,
+      args: ctx.args ?? (command != null ? { command } : null),
+      policyDigest: ctx.rule || ctx.riskLevel || ctx.risk || null,
+    });
+    const what = ctx.tool || ctx.toolName || "tool";
+    const detail = command != null ? `: ${String(command).slice(0, 200)}` : "";
+    try {
+      const ok = await interaction.askConfirm(
+        `Approve ${what}${detail}? (risk: ${risk})`,
+        {
+          default: false,
+          binding,
+          // Structured context so UIs can render a proper approval card
+          // instead of parsing the question text.
+          approval: {
+            tool: what,
+            command,
+            risk,
+            rule: ctx.rule || null,
+          },
+        },
+      );
+      return ok === true;
+    } catch {
+      // timeout / disconnect / interrupt → fail closed, never approve
+      return false;
+    }
+  };
+}
+
+/**
+ * Create a session-scoped approval gate for the WS agent handler.
+ *
+ * Policy lookups delegate to the persistent singleton gate (per-session tiers
+ * set via `sessions.policy.set` stay live); CONFIRM decisions route to the
+ * binding-attaching WS confirmer. Returns null on any load failure so the
+ * caller degrades to the legacy no-gate path (fail closed at CONFIRM).
+ *
+ * @param {object} opts
+ * @param {string} opts.sessionId
+ * @param {{askConfirm: Function}} opts.interaction
+ * @param {object} [opts.deps] - test seams: `loadSingletons`, `loadSessionCore`
+ * @returns {Promise<object|null>}
+ */
+export async function createWsApprovalGate({
+  sessionId,
+  interaction,
+  deps = {},
+}) {
+  try {
+    const loadSingletons =
+      deps.loadSingletons ||
+      (() => import("../../lib/session-core-singletons.js"));
+    const loadSessionCore =
+      deps.loadSessionCore || (() => import("@chainlesschain/session-core"));
+    const [singletons, core] = await Promise.all([
+      loadSingletons(),
+      loadSessionCore(),
+    ]);
+    const inner = await singletons.getApprovalGate();
+    const confirmer =
+      deps.confirmer || buildWsApprovalConfirmer({ interaction, sessionId });
+    const gate = new core.ApprovalGate({
+      defaultPolicy: core.APPROVAL_POLICY?.STRICT || "strict",
+      confirm: confirmer,
+    });
+    return {
+      // Explicit ctx.policy always wins inside decide(); resolve it from the
+      // singleton on every call so mid-session `sessions.policy.set` applies.
+      decide: (ctx = {}) =>
+        gate.decide({
+          ...ctx,
+          policy:
+            ctx.policy || inner.getSessionPolicy(ctx.sessionId || sessionId),
+        }),
+      hasConfirmer: () => gate.hasConfirmer(),
+      setConfirmer: (fn) => gate.setConfirmer(fn),
+      getSessionPolicy: (sid) => inner.getSessionPolicy(sid || sessionId),
+      setSessionPolicy: (sid, policy) =>
+        inner.setSessionPolicy(sid || sessionId, policy),
+    };
+  } catch {
+    return null; // degrade to the legacy no-gate path
+  }
+}

package/src/lib/agent-worktree.js

@@ -11,11 +11,18 @@
  *    a merge hint. Removal failures fail-open to "kept".
  */
 
-import { execSync } from "child_process";
+import { execFileSync, execSync } from "child_process";
+import { existsSync, realpathSync } from "node:fs";
+import { resolve } from "node:path";
 import { createWorktree, removeWorktree } from "./worktree-isolator.js";
 import { findProjectRoot } from "./project-instructions.js";
 
-export const _deps = { execSync, createWorktree, removeWorktree };
+export const _deps = {
+  execFileSync,
+  execSync,
+  createWorktree,
+  removeWorktree,
+};
 
 function git(cmd, cwd, deps) {
   return (deps.execSync || execSync)(`git ${cmd}`, {
@@ -25,6 +32,132 @@ function git(cmd, cwd, deps) {
   });
 }
 
+function canonicalPath(value) {
+  const absolute = resolve(String(value || ""));
+  const real = realpathSync.native
+    ? realpathSync.native(absolute)
+    : realpathSync(absolute);
+  return process.platform === "win32" ? real.toLowerCase() : real;
+}
+
+function parseRegisteredWorktrees(text) {
+  const entries = [];
+  let current = null;
+  for (const line of String(text || "").split(/\r?\n/)) {
+    if (line.startsWith("worktree ")) {
+      if (current) entries.push(current);
+      current = { path: line.slice("worktree ".length) };
+      continue;
+    }
+    if (!current) continue;
+    if (line.startsWith("HEAD ")) current.head = line.slice("HEAD ".length);
+    if (line.startsWith("branch ")) {
+      current.branch = line.slice("branch ".length);
+    }
+  }
+  if (current) entries.push(current);
+  return entries;
+}
+
+/**
+ * Verify that persisted worktree metadata still identifies the same linked
+ * worktree. Cleanup callers use this as a fail-closed identity check before
+ * invoking any removal primitive: a missing/corrupt path must never turn into
+ * a recursive delete of the repository checkout.
+ *
+ * @returns {{valid:boolean, reason:string}}
+ */
+export function validateAgentWorktree(info, { deps = _deps } = {}) {
+  const worktreePath = info?.path || info?.worktreePath;
+  if (!worktreePath || !info?.repoRoot || !info?.branch || !info?.baseSha) {
+    return { valid: false, reason: "incomplete worktree metadata" };
+  }
+  if (!/^[0-9a-f]{40,64}$/i.test(String(info.baseSha))) {
+    return { valid: false, reason: "invalid worktree base SHA" };
+  }
+  if (!existsSync(worktreePath) || !existsSync(info.repoRoot)) {
+    return { valid: false, reason: "worktree or repository path is missing" };
+  }
+
+  try {
+    const repo = canonicalPath(info.repoRoot);
+    const worktree = canonicalPath(worktreePath);
+    if (repo === worktree) {
+      return {
+        valid: false,
+        reason: "refusing to treat the main checkout as an agent worktree",
+      };
+    }
+
+    const repoTop = canonicalPath(
+      git("rev-parse --show-toplevel", info.repoRoot, deps).trim(),
+    );
+    const worktreeTop = canonicalPath(
+      git("rev-parse --show-toplevel", worktreePath, deps).trim(),
+    );
+    if (repoTop !== repo || worktreeTop !== worktree) {
+      return { valid: false, reason: "worktree path identity mismatch" };
+    }
+
+    const registered = parseRegisteredWorktrees(
+      git("worktree list --porcelain", info.repoRoot, deps),
+    ).find((entry) => {
+      try {
+        return canonicalPath(entry.path) === worktree;
+      } catch {
+        return false;
+      }
+    });
+    if (!registered) {
+      return {
+        valid: false,
+        reason: "path is not a registered worktree of the repository",
+      };
+    }
+    if (registered.branch !== `refs/heads/${info.branch}`) {
+      return {
+        valid: false,
+        reason: "registered worktree branch does not match persisted metadata",
+      };
+    }
+    return { valid: true, reason: "verified" };
+  } catch (error) {
+    return {
+      valid: false,
+      reason: `worktree identity could not be verified: ${error.message}`,
+    };
+  }
+}
+
+function removeVerifiedAgentWorktree(info, deps) {
+  // Unit seams historically inject removeWorktree directly. Keep that seam,
+  // while production uses a non-forced git removal: if the tree changed
+  // between inspection and deletion, git refuses instead of discarding it.
+  if (deps.removeWorktree && deps.removeWorktree !== removeWorktree) {
+    deps.removeWorktree(info.repoRoot, info.path);
+    return null;
+  }
+
+  const run = deps.execFileSync || execFileSync;
+  run("git", ["worktree", "remove", info.path], {
+    cwd: info.repoRoot,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  try {
+    run("git", ["branch", "-D", "--", info.branch], {
+      cwd: info.repoRoot,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    return null;
+  } catch (error) {
+    // The worktree itself is already gone. Preserve an honest warning rather
+    // than claiming the whole cleanup failed and that the path was kept.
+    return `branch cleanup failed: ${error.message}`;
+  }
+}
+
 /**
  * @returns {{ path, branch, repoRoot, baseSha }}
  */
@@ -51,22 +184,57 @@ export function setupAgentWorktree({
 export function finishAgentWorktree(info, { deps = _deps } = {}) {
   if (!info) return { removed: false, kept: false, reason: "no worktree" };
 
+  // Production cleanup validates the persisted path against git's own
+  // worktree registry. Custom dependency bundles are test seams and retain the
+  // historical pure mocked behavior unless they provide validateWorktree.
+  const validation =
+    typeof deps.validateWorktree === "function"
+      ? deps.validateWorktree(info)
+      : deps === _deps
+        ? validateAgentWorktree(info, { deps })
+        : { valid: true, reason: "injected validation seam" };
+  if (!validation?.valid) {
+    return {
+      removed: false,
+      kept: true,
+      reason: `unverifiable worktree: ${validation?.reason || "unknown reason"}`,
+    };
+  }
+
   let dirty = true;
   let headSha = null;
+  let readable = false;
   try {
     dirty = git("status --porcelain", info.path, deps).trim().length > 0;
     headSha = git("rev-parse HEAD", info.path, deps).trim();
+    readable = true;
   } catch {
     /* unreadable → keep, never destroy work we cannot verify */
   }
 
+  if (!readable) {
+    return {
+      removed: false,
+      kept: true,
+      reason: "unverifiable worktree: git state could not be read",
+    };
+  }
+
   const hasCommits = headSha !== null && headSha !== info.baseSha;
   if (!dirty && !hasCommits) {
     try {
-      (deps.removeWorktree || removeWorktree)(info.repoRoot, info.path);
-      return { removed: true, kept: false, reason: "no changes" };
+      const warning = removeVerifiedAgentWorktree(info, deps);
+      return {
+        removed: true,
+        kept: false,
+        reason: warning ? `no changes; ${warning}` : "no changes",
+      };
     } catch (err) {
-      return { removed: false, kept: true, reason: `cleanup failed: ${err.message}` };
+      return {
+        removed: false,
+        kept: true,
+        reason: `cleanup failed: ${err.message}`,
+      };
     }
   }
   return {

package/src/lib/background-agent-supervisor.js

@@ -6,16 +6,21 @@ import {
   openSync,
   readFileSync,
   readdirSync,
+  realpathSync,
   renameSync,
   rmSync,
   statSync,
   writeFileSync,
 } from "node:fs";
 import { randomBytes } from "node:crypto";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { getHomeDir } from "./paths.js";
 import { deriveSessionState } from "./session-lifecycle.js";
+import {
+  finishAgentWorktree,
+  validateAgentWorktree,
+} from "./agent-worktree.js";
 
 export const DEFAULT_HEARTBEAT_INTERVAL_MS = 5000;
 export const DEFAULT_HEARTBEAT_STALE_MS = 120000;
@@ -280,6 +285,20 @@ export function writeBackgroundAgentState(state) {
     if (Number(current.pinnedAt || 0) > Number(next.pinnedAt || 0)) {
       next = { ...next, pinned: current.pinned, pinnedAt: current.pinnedAt };
     }
+    // A background worktree is immutable session identity, just like the
+    // conversation id. Heartbeat/finalize/rename writers may race with a stale
+    // snapshot, but no same-id transition is allowed to move the run back to
+    // the main checkout or drop the cleanup metadata.
+    if (current.worktreePath) {
+      next = {
+        ...next,
+        cwd: current.worktreePath,
+        repoRoot: current.repoRoot,
+        worktreePath: current.worktreePath,
+        baseSha: current.baseSha,
+        branch: current.branch,
+      };
+    }
   }
   const tmp = `${target}.${process.pid}.tmp`;
   writeFileSync(tmp, JSON.stringify(next, null, 2), { mode: 0o600 });
@@ -500,7 +519,7 @@ export function renameBackgroundAgent(id, title, options = {}) {
  * conversation session is NOT touched — that's `cc session delete`.
  */
 export function removeBackgroundAgent(id, options = {}) {
-  const state = effectiveBackgroundAgentState(readBackgroundAgentState(id), {
+  let state = effectiveBackgroundAgentState(readBackgroundAgentState(id), {
     now: options.now,
     heartbeatStaleMs: options.heartbeatStaleMs,
   });
@@ -513,15 +532,28 @@ export function removeBackgroundAgent(id, options = {}) {
     }
     try {
       stopBackgroundAgent(id);
+      state =
+        effectiveBackgroundAgentState(readBackgroundAgentState(id), {
+          now: options.now,
+          heartbeatStaleMs: options.heartbeatStaleMs,
+        }) || state;
     } catch {
       /* best-effort — the record removal below is the point of rm --force */
     }
   }
+  const worktree = cleanupBackgroundAgentWorktree(state, {
+    keepWorktree: options.keepWorktree === true,
+  });
   rmSync(statePath(id), { force: true });
   if (options.keepLog !== true) {
     rmSync(logPath(id), { force: true });
   }
-  return { id, removed: true, status: state.status };
+  return {
+    id,
+    removed: true,
+    status: state.status,
+    ...(worktree ? { worktree } : {}),
+  };
 }
 
 /**
@@ -598,6 +630,68 @@ export function buildFollowUpArgv(argv, opts = {}) {
   return out;
 }
 
+function canonicalPath(value) {
+  const absolute = resolve(String(value || ""));
+  try {
+    const real = realpathSync.native
+      ? realpathSync.native(absolute)
+      : realpathSync(absolute);
+    return process.platform === "win32" ? real.toLowerCase() : real;
+  } catch {
+    return process.platform === "win32" ? absolute.toLowerCase() : absolute;
+  }
+}
+
+/**
+ * Normalize and verify worktree metadata before it enters a background job.
+ * The metadata is persisted as top-level state fields for compatibility with
+ * status/IDE consumers: repoRoot/worktreePath/baseSha/branch.
+ */
+export function normalizeBackgroundWorktree(worktree, cwd) {
+  if (!worktree) return null;
+  const normalized = {
+    repoRoot: resolve(String(worktree.repoRoot || "")),
+    worktreePath: resolve(String(worktree.worktreePath || worktree.path || "")),
+    baseSha: String(worktree.baseSha || ""),
+    branch: String(worktree.branch || ""),
+  };
+  if (
+    !normalized.repoRoot ||
+    !normalized.worktreePath ||
+    !normalized.baseSha ||
+    !normalized.branch
+  ) {
+    throw new Error(
+      "Cannot launch background agent: incomplete worktree metadata",
+    );
+  }
+  if (canonicalPath(cwd) !== canonicalPath(normalized.worktreePath)) {
+    throw new Error(
+      "Cannot launch background agent: cwd does not match the persisted worktree path",
+    );
+  }
+  const validation = validateAgentWorktree({
+    ...normalized,
+    path: normalized.worktreePath,
+  });
+  if (!validation.valid) {
+    throw new Error(
+      `Cannot launch background agent: worktree metadata is not usable (${validation.reason})`,
+    );
+  }
+  return normalized;
+}
+
+function persistedWorktree(state) {
+  if (!state?.worktreePath) return null;
+  return {
+    repoRoot: state.repoRoot,
+    worktreePath: state.worktreePath,
+    baseSha: state.baseSha,
+    branch: state.branch,
+  };
+}
+
 /**
  * Continue a finished/crashed background session as a NEW background session
  * on the same conversation (`cc daemon resume <id> <prompt>`). The original
@@ -622,14 +716,27 @@ export function resumeBackgroundAgent(id, prompt, options = {}) {
   }
   const text = String(prompt || "").trim();
   if (!text) throw new Error("resume requires a prompt");
+  const worktree = persistedWorktree(state);
+  if (
+    worktree &&
+    options.cwd &&
+    canonicalPath(options.cwd) !== canonicalPath(worktree.worktreePath)
+  ) {
+    throw new Error(
+      `Background agent ${id} is bound to worktree "${worktree.worktreePath}" and cannot resume in a different cwd`,
+    );
+  }
   const argv = ["agent", "--session", state.sessionId, "-p", text];
   return launchBackgroundAgent({
     argv,
-    cwd: options.cwd || state.cwd || process.cwd(),
+    // Worktree sessions fail closed: never fall back to process.cwd(), which
+    // could silently resume a write task in the main checkout.
+    cwd: worktree?.worktreePath || options.cwd || state.cwd || process.cwd(),
     sessionId: state.sessionId,
     title: options.title || state.title || text.slice(0, 100),
     cliEntry: options.cliEntry,
     followUpArgv: ["agent", "--session", state.sessionId],
+    worktree,
   });
 }
 
@@ -667,8 +774,10 @@ export function launchBackgroundAgent({
   title,
   cliEntry,
   followUpArgv,
+  worktree,
 }) {
   assertUsableCwd(cwd);
+  const worktreeState = normalizeBackgroundWorktree(worktree, cwd);
   const id = createBackgroundAgentId();
   const dir = backgroundAgentsDir();
   const jobFile = join(dir, `${id}.job.${process.pid}.json`);
@@ -683,6 +792,7 @@ export function launchBackgroundAgent({
     title: title || "Background agent",
     cliEntry: cliEntry || process.argv[1],
     logFile: logPath(id),
+    ...(worktreeState || {}),
     // Present = interactive attach can start follow-up turns; absent = the
     // transport rejects prompts (log-only session).
     ...(Array.isArray(followUpArgv) ? { followUpArgv } : {}),
@@ -706,6 +816,7 @@ export function launchBackgroundAgent({
     endedAt: null,
     exitCode: null,
     logFile: job.logFile,
+    ...(worktreeState || {}),
   };
   writeBackgroundAgentState(state);
   let child;
@@ -866,6 +977,84 @@ export function stopBackgroundAgent(id) {
   return { ...next, stopped: true };
 }
 
+function activeWorktreeProcesses(state) {
+  const active = [];
+  if (
+    Number.isInteger(Number(state?.pid)) &&
+    Number(state.pid) > 0 &&
+    isSameProcess(state.pid, state.startedAt)
+  ) {
+    active.push("worker");
+  }
+  if (
+    Number.isInteger(Number(state?.agentPid)) &&
+    Number(state.agentPid) > 0 &&
+    isSameProcess(state.agentPid, state.agentStartedAt)
+  ) {
+    active.push("agent");
+  }
+  return active;
+}
+
+/**
+ * Explicit background-record cleanup owns the worktree teardown. Normal
+ * completion, kill, lost-worker reconciliation, attach and resume all retain
+ * it so a later resume continues in the exact same isolated checkout.
+ */
+export function cleanupBackgroundAgentWorktree(state, options = {}) {
+  const worktree = persistedWorktree(state);
+  if (!worktree) return null;
+  if (options.keepWorktree === true) {
+    return {
+      removed: false,
+      kept: true,
+      reason: "kept by explicit request",
+      path: worktree.worktreePath,
+    };
+  }
+
+  const blockers = [];
+  const active = activeWorktreeProcesses(state);
+  if (active.length) blockers.push(`active ${active.join("+")} process`);
+  if (Number(state?.pendingApprovals || 0) > 0) {
+    blockers.push("pending approval");
+  }
+  if (state?.pendingQuestion) blockers.push("pending user input");
+  if (
+    Number(state?.uncertainSideEffects || 0) > 0 ||
+    state?.phase === "uncertain_side_effect" ||
+    state?.phase === "uncertain-side-effect"
+  ) {
+    blockers.push("unfinished or uncertain side effect");
+  }
+  if (blockers.length) {
+    throw new Error(
+      `Refusing to clean background worktree "${worktree.worktreePath}": ${blockers.join(", ")}`,
+    );
+  }
+
+  if (!existsSync(worktree.worktreePath)) {
+    return {
+      removed: false,
+      kept: false,
+      reason: "worktree path already missing",
+      path: worktree.worktreePath,
+    };
+  }
+
+  const result = finishAgentWorktree({
+    ...worktree,
+    path: worktree.worktreePath,
+  });
+  if (!result.removed) {
+    throw new Error(
+      `Refusing to remove background agent record while its worktree is kept (${result.reason}). ` +
+        "Resolve or preserve the work first, or pass --keep-worktree to remove only the record.",
+    );
+  }
+  return { ...result, path: worktree.worktreePath };
+}
+
 export function openBackgroundLogFile(id) {
   const fd = openSync(logPath(id), "a", 0o600);
   return { fd, close: () => closeSync(fd) };