specrails-desktop 2.29.2 → 2.29.4

package/server/dist/rails-router.js

@@ -21,6 +21,7 @@ const rail_isolation_1 = require("./rail-isolation");
 const rail_pr_store_1 = require("./rail-pr-store");
 const loop_effect_1 = require("./loop-effect");
 const rail_pr_decision_1 = require("./rail-pr-decision");
+const active_pr_continuation_1 = require("./active-pr-continuation");
 const rail_isolated_launch_1 = require("./rail-isolated-launch");
 const worktree_manager_1 = require("./worktree-manager");
 const rail_worktree_release_1 = require("./rail-worktree-release");
@@ -40,12 +41,21 @@ const VALID_REASONING_EFFORTS = new Set(['low', 'medium', 'high']);
 function prDeliveryContinuesTickets(delivery, ticketIds) {
     if (delivery.decision !== 'pr_draft' && delivery.decision !== 'pr_ready')
         return false;
-    if (!delivery.prUrl || !delivery.branch || delivery.prState !== 'pr-created')
+    if (!delivery.prUrl || !delivery.branch || !delivery.deliverySha || delivery.prState !== 'pr-created')
         return false;
     const covered = new Set(delivery.ticketIds);
     const requested = new Set(ticketIds);
     return requested.size > 0 && requested.size === covered.size && [...requested].every((id) => covered.has(id));
 }
+function prDeliveryCheckoutBlock(delivery) {
+    if (delivery.deliveryOutcome === 'blocked') {
+        return 'delivery is blocked and has no safely checkoutable result';
+    }
+    if (!delivery.deliverySha) {
+        return 'delivery has no verified commit available for checkout';
+    }
+    return null;
+}
 function emitPrDeliveryUpdate(c, prDeliveryId) {
     const row = (0, rail_pr_store_1.getPrDelivery)(c.db, prDeliveryId);
     if (!row)
@@ -268,6 +278,40 @@ function createRailsRouter() {
             res.status(500).json({ error: 'Failed to update rail profile' });
         }
     });
+    // GET /rails/:railIndex/pr-candidates — display-only open-PR suggestions for
+    // the "deliver into existing PR" launch affordance. Reuses the automatic-
+    // continuation matchers WITHOUT the ticket-status gate: suggestions are
+    // informational, selection is always an explicit user action. No side effects.
+    router.get('/:railIndex/pr-candidates', async (req, res) => {
+        const c = ctx(req);
+        const railIndex = parseInt(req.params.railIndex, 10);
+        if (isNaN(railIndex) || railIndex < 0 || railIndex >= rails_store_1.MAX_RAILS) {
+            res.status(400).json({ error: 'Invalid rail index' });
+            return;
+        }
+        try {
+            const rail = (0, rails_store_1.getRail)(c.db, railIndex);
+            const candidates = await (0, active_pr_continuation_1.listPrCandidatesForTickets)({
+                db: c.db,
+                exec: pr_publisher_1.defaultExec,
+                repoDir: c.project.path,
+                ticketIds: [...(rail?.ticketIds ?? [])],
+                getTicketSpec: (ticketId) => {
+                    try {
+                        return c.getTicketSpec(ticketId) ?? undefined;
+                    }
+                    catch {
+                        return undefined;
+                    }
+                },
+            });
+            res.json({ candidates });
+        }
+        catch (err) {
+            console.error('[rails-router] pr-candidates error:', err);
+            res.status(500).json({ error: 'Failed to list PR candidates' });
+        }
+    });
     // PUT /rails/:railIndex/engine — set the AI engine override for a rail
     // Body: { aiEngine: string | null } (null = use the project's primary provider)
     router.put('/:railIndex/engine', (req, res) => {
@@ -343,7 +387,16 @@ function createRailsRouter() {
             return;
         }
         let { mode = 'implement' } = req.body ?? {};
-        const { profileName, aiEngine, model, loopId: rawLoopId, reasoning_effort, originConversationId, originSurface } = req.body ?? {};
+        const { profileName, aiEngine, model, loopId: rawLoopId, reasoning_effort, originConversationId, originSurface, targetPrNumber } = req.body ?? {};
+        // Explicit target PR (deliver-rail-into-existing-pr): the user names an
+        // existing open PR as the delivery destination. Shape-validated here;
+        // resolved and verified inside the isolated launch, fail-closed.
+        if (targetPrNumber !== undefined && targetPrNumber !== null) {
+            if (typeof targetPrNumber !== 'number' || !Number.isSafeInteger(targetPrNumber) || targetPrNumber <= 0 || targetPrNumber > 1_000_000_000) {
+                res.status(400).json({ error: 'invalid_target_pr', detail: 'targetPrNumber must be a positive integer' });
+                return;
+            }
+        }
         let loopId = rawLoopId;
         // Origin link (safe-pr-review-flow): an agent-chat/MCP launch tags itself so
         // the PR decision can later be posted back into the launching conversation.
@@ -386,6 +439,13 @@ function createRailsRouter() {
             res.status(403).json({ error: 'Loops are disabled on this server' });
             return;
         }
+        // An explicit target PR is only meaningful on the isolated PR-delivery
+        // path. Reject early when that path is structurally unavailable rather
+        // than silently launching fresh work next to the designated PR.
+        if (typeof targetPrNumber === 'number' && (!(0, feature_flags_1.isLoopsEnabled)() || !(0, rail_isolation_1.isRailPrDeliveryEnabled)())) {
+            res.status(400).json({ error: 'target_pr_requires_pr_mode', detail: 'targetPrNumber requires loops and PR delivery to be enabled' });
+            return;
+        }
         // Freestyle model picker: optional, validated against the allow-list.
         // Ignored for non-freestyle modes (they use the orchestrator model).
         if (mode === 'freestyle' && model !== undefined && model !== null) {
@@ -562,11 +622,23 @@ function createRailsRouter() {
                         res.status(409).json({ error: 'pr_decision_pending', prDeliveryId: pendingSnapshot.id });
                         return;
                     }
+                    // Explicit target vs an undecided continuable delivery: the slot's
+                    // active generation owns its PR. A DIFFERENT explicit target would
+                    // append to the undecided branches → 409; the SAME PR is redundant
+                    // (the continuation contract below already drives it) and is dropped.
+                    if (pendingSnapshot && typeof targetPrNumber === 'number' && pendingSnapshot.prNumber !== targetPrNumber) {
+                        res.status(409).json({ error: 'pr_decision_pending', prDeliveryId: pendingSnapshot.id });
+                        return;
+                    }
                     continuablePrDelivery = pendingSnapshot;
                 }
                 const useIsolation = (0, rail_isolation_1.isolationApplies)({
                     loopsEnabled: (0, feature_flags_1.isLoopsEnabled)(), scope, ticketCount: rail.ticketIds.length, readOnly: loopReadOnly,
                 });
+                if (typeof targetPrNumber === 'number' && !useIsolation) {
+                    res.status(400).json({ error: 'target_pr_requires_pr_mode', detail: 'targetPrNumber requires an isolated (worktree) launch; this launch would run in the shared checkout' });
+                    return;
+                }
                 if (continuablePrDelivery && !loopReadOnly && !useIsolation) {
                     res.status(409).json({
                         error: 'pr_continuation_isolation_required',
@@ -580,6 +652,13 @@ function createRailsRouter() {
                     // unborn HEAD can't be branched). Fall back (with a message) otherwise.
                     const status = await (0, worktree_manager_1.repoIsolationStatus)(worktree_manager_1.defaultGitRunner, c.project.path);
                     if (status !== 'ok') {
+                        if (typeof targetPrNumber === 'number') {
+                            res.status(400).json({
+                                error: 'target_pr_requires_pr_mode',
+                                detail: `targetPrNumber requires worktree isolation, which is unavailable (${status})`,
+                            });
+                            return;
+                        }
                         if (continuablePrDelivery) {
                             res.status(409).json({
                                 error: 'pr_continuation_isolation_required',
@@ -603,10 +682,18 @@ function createRailsRouter() {
                                         deliveryId: continuablePrDelivery.id,
                                         decision: continuablePrDelivery.decision,
                                         branch: continuablePrDelivery.branch,
+                                        baseBranch: continuablePrDelivery.baseBranch,
                                         prUrl: continuablePrDelivery.prUrl,
                                         prNumber: continuablePrDelivery.prNumber,
+                                        deliverySha: continuablePrDelivery.deliverySha,
                                     },
                                 } : {}),
+                                // Explicit target only drives fresh launches; when the slot has
+                                // a continuable delivery for the same PR, the continuation
+                                // contract above is the (stricter) authority.
+                                ...(typeof targetPrNumber === 'number' && !continuablePrDelivery
+                                    ? { explicitPrTarget: { prNumber: targetPrNumber } }
+                                    : {}),
                             });
                             res.status(202).json({ loopRunIds: ids, railIndex, mode, isolated: true });
                             return;
@@ -619,6 +706,16 @@ function createRailsRouter() {
                                 });
                                 return;
                             }
+                            // Explicit-target validation failures are the USER's answer being
+                            // unusable — fail closed with the machine-readable code; never
+                            // fall back to a fresh shared-cwd run next to the designated PR.
+                            if (err instanceof active_pr_continuation_1.ExplicitPrTargetError) {
+                                res.status(err.code === 'target_pr_not_found' ? 404 : 409).json({
+                                    error: err.code,
+                                    detail: err.message,
+                                });
+                                return;
+                            }
                             if (continuablePrDelivery || err instanceof rail_isolated_launch_1.PrContinuationIsolationError) {
                                 const detail = err instanceof Error ? err.message : String(err);
                                 res.status(409).json({
@@ -881,7 +978,7 @@ function createRailsRouter() {
     // POST /rails/pr-decision — the ONE decision action (safe-pr-review-flow) both
     // surfaces (dashboard rail row + agent-chat card) call on a rail_pr_deliveries
     // row: create-pr | publish | discard/dismiss | poll/reopen | merge-local |
-    // acknowledge-no-changes, compare-and-set-guarded by
+    // acknowledge-no-changes | recover-and-retry, compare-and-set-guarded by
     // expectedDecision (a raced concurrent answer loses with 409 stale_decision).
     // Replaces the stateless v1 POST /rails/pr-review passthrough. The route only
     // validates and delegates — the action logic lives in rail-pr-decision.ts.
@@ -894,7 +991,7 @@ function createRailsRouter() {
             return;
         }
         if (!(0, rail_pr_decision_1.isPrDecisionAction)(action)) {
-            res.status(400).json({ error: "action must be 'create-pr', 'publish', 'discard', 'dismiss', 'poll-merge', 'reopen', 'merge-local' or 'acknowledge-no-changes'" });
+            res.status(400).json({ error: `action must be one of: ${rail_pr_decision_1.PR_DECISION_ACTIONS.join(', ')}` });
             return;
         }
         if (typeof expectedDecision !== 'string' || !expectedDecision) {
@@ -968,7 +1065,21 @@ function createRailsRouter() {
             res.status(404).json({ error: 'Unknown prDeliveryId' });
             return;
         }
+        const active = (0, rail_pr_store_1.getActivePrDeliveryByRail)(c.db, row.rail_index);
+        if (!active || active.id !== row.id) {
+            res.status(409).json({
+                error: 'stale_decision',
+                current: active?.decision ?? null,
+                currentPrDeliveryId: active?.id ?? null,
+            });
+            return;
+        }
         const snap = (0, rail_pr_store_1.toPrDeliverySnapshot)(row);
+        const checkoutBlock = prDeliveryCheckoutBlock(snap);
+        if (checkoutBlock) {
+            res.status(409).json({ error: 'checkout_not_deliverable', detail: checkoutBlock });
+            return;
+        }
         if (!snap.branch || !snap.prUrl) {
             res.status(409).json({ error: 'checkout_unavailable', detail: 'delivery has no PR branch' });
             return;
@@ -976,20 +1087,95 @@ function createRailsRouter() {
         try {
             const outcome = await (0, repo_lock_1.withRepoLock)(c.project.path, async () => {
                 admission.assertCurrent();
+                const current = (0, rail_pr_store_1.getActivePrDeliveryByRail)(c.db, row.rail_index);
+                if (!current || current.id !== row.id) {
+                    return {
+                        ok: false,
+                        status: 409,
+                        error: 'stale_decision',
+                        detail: 'The delivery generation changed before checkout.',
+                    };
+                }
+                const currentSnap = (0, rail_pr_store_1.toPrDeliverySnapshot)(current);
+                const currentCheckoutBlock = prDeliveryCheckoutBlock(currentSnap);
+                if (currentCheckoutBlock) {
+                    return {
+                        ok: false,
+                        status: 409,
+                        error: 'checkout_not_deliverable',
+                        detail: currentCheckoutBlock,
+                    };
+                }
+                if (!currentSnap.branch || !currentSnap.prUrl) {
+                    return {
+                        ok: false,
+                        status: 409,
+                        error: 'checkout_not_deliverable',
+                        detail: 'The current delivery no longer has an attached PR branch.',
+                    };
+                }
+                const cleanliness = await (0, project_git_1.inspectProjectCheckoutCleanliness)(c.project.path);
+                if (!cleanliness.ok) {
+                    return {
+                        ok: false,
+                        status: 409,
+                        error: 'checkout_safety_unknown',
+                        detail: cleanliness.detail,
+                    };
+                }
+                if (!cleanliness.clean) {
+                    return { ok: false, status: 409, error: 'checkout_dirty', detail: 'Working tree has uncommitted changes. Commit or stash them before checkout.' };
+                }
                 const info = await (0, project_git_1.getProjectGitInfo)(c.project.path);
                 if (!info.git) {
                     return { ok: false, status: 409, error: 'checkout_unavailable', detail: 'project is not a git repository' };
                 }
-                if (info.dirty) {
-                    return { ok: false, status: 409, error: 'checkout_dirty', detail: 'Working tree has uncommitted changes. Commit or stash them before checkout.' };
-                }
-                await (0, rail_worktree_release_1.releaseRailWorktrees)({
+                let archived = false;
+                const cleanupWarnings = await (0, rail_worktree_release_1.releaseRailWorktrees)({
                     db: c.db,
                     git: worktree_manager_1.defaultGitRunner,
                     repoDir: c.project.path,
-                    worktreeIds: snap.worktreeIds,
+                    worktreeIds: currentSnap.worktreeIds,
+                    expectedHeadByBranch: (0, rail_worktree_release_1.durableBranchHeads)(currentSnap.branches),
+                    overlayEvidenceByBranch: (0, rail_worktree_release_1.durableOverlayCleanupEvidence)(currentSnap.branches),
+                    settlementIgnoredByBranch: (0, rail_worktree_release_1.durableSettlementIgnoredPaths)(currentSnap.branches),
+                    onSafetyArchive: (archive) => {
+                        archived = true;
+                        if (!(0, rail_pr_store_1.appendPrDeliverySafetyArchive)(c.db, row.id, archive)) {
+                            throw new Error(`delivery ${row.id} disappeared while recording safety archive ${archive}`);
+                        }
+                    },
                 });
-                const checkedOut = await (0, project_git_1.checkoutProjectReviewBranch)(c.project.path, snap.branch);
+                if (archived) {
+                    const archivedRow = (0, rail_pr_store_1.getPrDelivery)(c.db, row.id);
+                    if (archivedRow) {
+                        const archivedSnap = (0, rail_pr_store_1.toPrDeliverySnapshot)(archivedRow);
+                        c.broadcast((0, rail_pr_store_1.toRailPrStateMessage)(c.project.id, archivedSnap));
+                        if (archivedRow.origin_conversation_id) {
+                            (0, agent_chat_registry_1.getAgentChatManager)()?.updatePrDecisionCard(archivedRow.origin_conversation_id, (0, rail_pr_store_1.toPrDecisionCardEnvelope)(c.project.id, archivedSnap));
+                        }
+                    }
+                }
+                if (cleanupWarnings.length > 0) {
+                    return {
+                        ok: false,
+                        status: 409,
+                        error: 'checkout_unavailable',
+                        detail: cleanupWarnings[0],
+                    };
+                }
+                // Cleanup just completed with ZERO warnings — clear any stale
+                // cleanup_incomplete evidence persisted by earlier failed release
+                // attempts, so the card stops claiming "Cleanup is incomplete" after
+                // the condition has been resolved. Same-state patch + live broadcast.
+                if (currentSnap.cleanupWarnings.length > 0 || currentSnap.statusCode === 'cleanup_incomplete') {
+                    (0, rail_pr_store_1.transitionDecision)(c.db, row.id, currentSnap.decision, currentSnap.decision, {
+                        cleanupWarnings: [],
+                        ...(currentSnap.statusCode === 'cleanup_incomplete' ? { statusCode: null } : {}),
+                    });
+                    emitPrDeliveryUpdate(c, row.id);
+                }
+                const checkedOut = await (0, project_git_1.checkoutProjectReviewBranch)(c.project.path, currentSnap.branch, currentSnap.deliverySha);
                 if (!checkedOut.ok) {
                     return { ok: false, status: 409, error: 'checkout_failed', detail: checkedOut.error };
                 }

package/server/dist/worktree-manager.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PR_NEVER_STAGE_PATHS = exports.defaultGitRunner = void 0;
+exports.PR_NEVER_STAGE_PATHSPEC_ROOTS = exports.PR_NEVER_STAGE_PATHS = exports.defaultGitRunner = void 0;
 exports.isGitRepo = isGitRepo;
 exports.repoIsolationStatus = repoIsolationStatus;
 exports.worktreeBranch = worktreeBranch;
@@ -63,13 +63,21 @@ const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const win_spawn_1 = require("./util/win-spawn");
+const GIT_RUNNER_TIMEOUT_MS = 120_000;
 exports.defaultGitRunner = {
     run(args, cwd) {
         return new Promise((resolve) => {
             // SystemRoot/ComSpec backfill so worktree + PR-decision git ops don't fail
             // to start under a pkg-stripped Windows sidecar env. No-op on POSIX.
             const env = (0, win_spawn_1.windowsSpawnEnv)();
-            (0, child_process_1.execFile)('git', args, { cwd, env, maxBuffer: 16 * 1024 * 1024, windowsHide: true }, (err, stdout, stderr) => {
+            (0, child_process_1.execFile)('git', args, {
+                cwd,
+                env,
+                timeout: GIT_RUNNER_TIMEOUT_MS,
+                killSignal: 'SIGTERM',
+                maxBuffer: 16 * 1024 * 1024,
+                windowsHide: true,
+            }, (err, stdout, stderr) => {
                 const code = err && typeof err.code === 'number' ? err.code : err ? 1 : 0;
                 resolve({ code, stdout: stdout?.toString() ?? '', stderr: stderr?.toString() ?? '' });
             });
@@ -233,8 +241,80 @@ async function gitRun(git, args, cwd) {
     }
 }
 function commitPathspecs(excludePaths) {
-    const allExcludePaths = [...exports.PR_NEVER_STAGE_PATHS, ...excludePaths];
-    return ['--', '.', ...allExcludePaths.map((p) => `:(exclude)${p}`)];
+    return [
+        '--', '.',
+        ...exports.PR_NEVER_STAGE_PATHSPEC_ROOTS.map((p) => `:(exclude)${p}`),
+        // Overlay names originate in the workspace filesystem. Treat them as
+        // literal top-level paths so glob/pathspec metacharacters cannot broaden
+        // the never-commit surface.
+        ...excludePaths.map((p) => `:(top,exclude,literal)${p}`),
+    ];
+}
+const INDEX_AUDIT_ARGS = [
+    'diff', '--cached', '--name-only', '--no-renames', '-z',
+    '--diff-filter=ACDMRTUXB', '--',
+];
+const PR_NEVER_STAGE_ROOTS = [...new Set(exports.PR_NEVER_STAGE_PATHS.map((entry) => entry.endsWith('/**') ? entry.slice(0, -3) : entry))];
+function normalizedGitPath(value) {
+    return path.sep === '\\' ? value.replaceAll('\\', '/') : value;
+}
+function isPathAtOrBelow(candidate, root) {
+    return candidate === root || candidate.startsWith(`${root}/`);
+}
+/**
+ * Collapse a path list to its minimal roots — drop any entry that is at or
+ * below another. Overlay-owned entries like `.claude/agent-memory` are
+ * SYMLINKS (the overlay links shared memory in). A git pathspec that descends
+ * INTO a symlink — `:(exclude).claude/agent-memory/**` or the `/explanations`
+ * subpaths — is rejected with `fatal: pathspec ... is beyond a symbolic link`,
+ * which aborts the entire `git add`/`git status` and blocks PR delivery. The
+ * symlink ROOT alone (`:(exclude).claude/agent-memory`) still excludes all of
+ * its contents (dir-level pathspec semantics) without traversing the link, and
+ * is equally correct for the copy-fallback case where it is a real directory.
+ */
+function minimalPathRoots(paths) {
+    const norm = [...new Set(paths.map((p) => (p.endsWith('/**') ? p.slice(0, -3) : p)))];
+    return norm.filter((p) => !norm.some((other) => other !== p && isPathAtOrBelow(p, other)));
+}
+/** Symlink-safe never-stage pathspec roots (see {@link minimalPathRoots}). */
+exports.PR_NEVER_STAGE_PATHSPEC_ROOTS = minimalPathRoots(exports.PR_NEVER_STAGE_PATHS);
+function forbiddenStagedPaths(staged, excludePaths) {
+    const overlayRoots = excludePaths.map(normalizedGitPath).filter(Boolean);
+    return staged.filter((candidate) => (PR_NEVER_STAGE_ROOTS.some((root) => isPathAtOrBelow(candidate, root))
+        || overlayRoots.some((root) => isPathAtOrBelow(candidate, root))));
+}
+function parseNulTerminatedPaths(result, phase) {
+    if (result.code !== 0) {
+        return { paths: [], error: `${phase}: ${gitFailure(result, `git diff failed with exit ${result.code}`)}` };
+    }
+    if (result.stdout === '')
+        return { paths: [] };
+    if (!result.stdout.endsWith('\0')) {
+        return { paths: [], error: `${phase}: git returned a malformed non-NUL-terminated path list` };
+    }
+    const paths = result.stdout.slice(0, -1).split('\0');
+    if (paths.some((entry) => entry.length === 0)) {
+        return { paths: [], error: `${phase}: git returned a malformed path list containing an empty entry` };
+    }
+    return { paths };
+}
+async function auditStagedPaths(git, worktreePath, excludePaths, phase) {
+    const result = await gitRun(git, [...INDEX_AUDIT_ARGS], worktreePath);
+    const parsed = parseNulTerminatedPaths(result, phase);
+    if (parsed.error)
+        return { forbidden: [], error: parsed.error };
+    return { forbidden: forbiddenStagedPaths(parsed.paths, excludePaths) };
+}
+function forbiddenResetPathspecs(excludePaths) {
+    return [
+        '--',
+        ...PR_NEVER_STAGE_ROOTS.map((entry) => `:(top,literal)${entry}`),
+        ...excludePaths.map(normalizedGitPath).filter(Boolean).map((entry) => `:(top,literal)${entry}`),
+    ];
+}
+function describeForbiddenPaths(paths) {
+    const shown = paths.slice(0, 5).map((entry) => JSON.stringify(entry)).join(', ');
+    return paths.length > 5 ? `${shown}, and ${paths.length - 5} more` : shown;
 }
 /**
  * Commit the worktree's current deliverable changes to its branch and verify
@@ -244,25 +324,75 @@ function commitPathspecs(excludePaths) {
  */
 async function commitWorktreeAndVerify(git, worktreePath, message, excludePaths = []) {
     const pathspecs = commitPathspecs(excludePaths);
-    const add = await gitRun(git, ['add', '-A', ...pathspecs], worktreePath);
-    const commit = add.code === 0
-        ? await gitRun(git, ['commit', '-m', message], worktreePath)
-        : { code: 1, stdout: '', stderr: 'skipped commit because git add failed' };
+    // The add is deliberately PLAIN — no exclude pathspecs. `git add` exits 1
+    // with "The following paths are ignored by one of your .gitignore files"
+    // whenever ANY pathspec item (exclude items included) names a git-ignored
+    // path, and our own info/exclude block (ensurePrNeverStageExcludes) plus repo
+    // .gitignore entries (e.g. `.claude/settings.local.json`) make exactly the
+    // excluded paths ignored. Ignored paths can never be staged without `-f`, so
+    // the plain add is safe for them; non-ignored overlay files DO get staged
+    // here and are unstaged by the audit → reset flow below before the commit,
+    // whose `--only` pathspecs (which git commit accepts without the
+    // ignored-path check) remain the authoritative exclusion.
+    const add = await gitRun(git, ['add', '-A', '--', '.'], worktreePath);
+    let indexSafe = false;
+    let indexError;
+    if (add.code === 0) {
+        const initialAudit = await auditStagedPaths(git, worktreePath, excludePaths, 'git index audit failed before commit');
+        if (initialAudit.error) {
+            indexError = initialAudit.error;
+        }
+        else if (initialAudit.forbidden.length === 0) {
+            indexSafe = true;
+        }
+        else {
+            // The plain add routinely stages non-ignored overlay files, and an
+            // earlier process may have put private paths in the index. Reset only the
+            // prohibited roots back to HEAD: working files remain intact for recovery.
+            const reset = await gitRun(git, ['reset', '--quiet', ...forbiddenResetPathspecs(excludePaths)], worktreePath);
+            if (reset.code !== 0) {
+                indexError = `git could not safely unstage forbidden paths: ${gitFailure(reset, `git reset failed with exit ${reset.code}`)}`;
+            }
+            else {
+                const finalAudit = await auditStagedPaths(git, worktreePath, excludePaths, 'git index re-audit failed after unstaging forbidden paths');
+                if (finalAudit.error) {
+                    indexError = finalAudit.error;
+                }
+                else if (finalAudit.forbidden.length > 0) {
+                    indexError = `forbidden paths remain staged after safe unstage: ${describeForbiddenPaths(finalAudit.forbidden)}`;
+                }
+                else {
+                    indexSafe = true;
+                }
+            }
+        }
+    }
+    // `--only` makes the allow/exclude pathspecs authoritative at commit time,
+    // not merely at the earlier `git add`/audit. This closes the remaining race
+    // where another process could stage a private path between audit and commit.
+    // Automated delivery also bypasses repository hooks: a pre-commit hook runs
+    // after our final audit and could otherwise stage an excluded secret into the
+    // commit. User working files and the ordinary index remain preserved.
+    const commit = add.code === 0 && indexSafe
+        ? await gitRun(git, ['commit', '--no-verify', '--only', '-m', message, ...pathspecs], worktreePath)
+        : { code: 1, stdout: '', stderr: 'skipped commit because the index was not proven safe' };
     const status = await gitRun(git, ['status', '--porcelain', '--untracked-files=all', ...pathspecs], worktreePath);
     const dirty = status.code === 0
         ? status.stdout.split('\n').map((line) => line.trimEnd()).filter(Boolean)
         : [];
     const error = add.code !== 0
         ? gitFailure(add, `git add failed with exit ${add.code}`)
-        : status.code !== 0
-            ? gitFailure(status, `git status failed with exit ${status.code}`)
-            : commit.code !== 0 && dirty.length > 0
-                ? gitFailure(commit, `git commit failed with exit ${commit.code}`)
-                : undefined;
+        : indexError
+            ? indexError
+            : status.code !== 0
+                ? gitFailure(status, `git status failed with exit ${status.code}`)
+                : commit.code !== 0 && dirty.length > 0
+                    ? gitFailure(commit, `git commit failed with exit ${commit.code}`)
+                    : undefined;
     return {
         staged: add.code === 0,
         committed: commit.code === 0,
-        clean: status.code === 0 && dirty.length === 0,
+        clean: indexSafe && status.code === 0 && dirty.length === 0,
         dirty,
         ...(error ? { error } : {}),
     };
@@ -276,11 +406,12 @@ async function commitWorktreeAndVerify(git, worktreePath, message, excludePaths
 async function commitWorktree(git, worktreePath, message, excludePaths = []) {
     await commitWorktreeAndVerify(git, worktreePath, message, excludePaths);
 }
-/** Remove a worktree (force) and optionally delete its branch. Worktree removal
- * failures throw so callers do not mark the ledger released while the checkout
- * is still mounted. Branch deletion remains best-effort. */
+/** Remove a worktree and optionally delete its branch. Explicit cleanup keeps
+ * the historical force default; automatic cleanup opts out. Removal failures
+ * throw so callers do not mark the ledger released while it is still mounted.
+ * Branch deletion remains best-effort. */
 async function removeWorktree(git, input) {
-    const removed = await git.run(['worktree', 'remove', '--force', input.worktreePath], input.repoDir);
+    const removed = await git.run(['worktree', 'remove', ...(input.force === false ? [] : ['--force']), input.worktreePath], input.repoDir);
     if (removed.code !== 0) {
         throw new Error(`git worktree remove failed for ${input.worktreePath}: ${gitFailure(removed, `exit ${removed.code}`)}`);
     }