@delegance/claude-autopilot 7.10.1 → 7.11.0-pre.2

package/dist/src/cli/index.js

@@ -1264,7 +1264,7 @@ switch (subcommand) {
             process.stdout.write(focused ?? buildHelpText());
             process.exit(0);
         }
-        const { runRunsList, runRunsShow, runRunsGc, runRunsDelete, runRunsDoctor, } = await import("./runs.js");
+        const { runRunsList, runRunsShow, runRunsGc, runRunsDelete, runRunsDoctor, runRunsCleanup, } = await import("./runs.js");
         let result;
         switch (sub) {
             case 'list': {
@@ -1349,8 +1349,34 @@ switch (subcommand) {
                 });
                 break;
             }
+            case 'cleanup': {
+                // v7.11.0 PR 2/6 — stale repo-lock recovery. The only operation
+                // currently supported is `--force-unlock`. The verb is scoped
+                // under `runs` (not its own top-level command) because the
+                // intended audience is anyone who already runs `runs list` /
+                // `runs show` etc. — they shouldn't need to learn a new noun.
+                //
+                // SECURITY: `--lock-path` is INTENTIONALLY NOT exposed on the
+                // CLI. The handler accepts an override for tests, but routing a
+                // user-supplied path here would let a typo or malicious script
+                // `forceUnlockRepoLock` an arbitrary `<path>` + `<path>.lock`
+                // pair on disk. The lock path is always derived from the cwd as
+                // `<cwd>/.claude/run-state/repo.lock` in production.
+                // (Codex pass 1 WARNING.)
+                const forceUnlock = boolFlag('force-unlock');
+                const yes = boolFlag('yes');
+                const allowActive = boolFlag('allow-active');
+                result = await runRunsCleanup({
+                    cwd,
+                    forceUnlock,
+                    yes,
+                    allowActive,
+                    json,
+                });
+                break;
+            }
             default: {
-                process.stderr.write(`\x1b[31m[claude-autopilot] runs: unknown sub-verb "${sub}" — valid: list, show, gc, delete, doctor, watch\x1b[0m\n`);
+                process.stderr.write(`\x1b[31m[claude-autopilot] runs: unknown sub-verb "${sub}" — valid: list, show, gc, delete, doctor, watch, cleanup\x1b[0m\n`);
                 process.exit(1);
             }
         }

package/dist/src/cli/runs.d.ts

@@ -118,5 +118,34 @@ export interface RunsDoctorRunReport {
  *    events-corrupt     : events.ndjson can't be folded (bigger problem)
  */
 export declare function runRunsDoctor(opts: RunRunsDoctorOptions): Promise<RunsCliResult>;
+export interface RunRunsCleanupOptions {
+    cwd?: string;
+    /** Required — currently the only operation. Future cleanup verbs (e.g.
+     *  `--gc-worktrees`) would be additional bool flags on the same subcommand. */
+    forceUnlock: boolean;
+    /** Bypass the interactive `yes` prompt. Used by scripts (not exposed in
+     *  the README as an example — we want manual operators to type yes). */
+    yes?: boolean;
+    /** Permit clearing a lock whose holder is still alive (or whose status
+     *  cannot be determined, e.g. cross-host). By default we refuse to clear
+     *  non-stale locks because doing so can corrupt git state under a live
+     *  writer. Codex pass 1 WARNING — see issue #189 PR review. */
+    allowActive?: boolean;
+    /** Override the repo-lock path. Tests use this. INTENTIONALLY NOT exposed
+     *  on the CLI (see `src/cli/index.ts`) — a user-supplied path would let a
+     *  typo destroy arbitrary files on disk. */
+    lockPath?: string;
+    /** Custom stdin reader for tests. Defaults to a node:readline-bound
+     *  interface against process.stdin. */
+    promptFn?: (question: string) => Promise<string>;
+    json?: boolean;
+}
+/**
+ * `runs cleanup --force-unlock` — surface the holder, require explicit
+ * `yes` confirmation, then unlink the lock metadata + the proper-lockfile
+ * `.lock` directory. Idempotent: if nothing is held, returns success with
+ * a "nothing to do" message.
+ */
+export declare function runRunsCleanup(opts: RunRunsCleanupOptions): Promise<RunsCliResult>;
 export { statePath };
 //# sourceMappingURL=runs.d.ts.map

package/dist/src/cli/runs.js

@@ -18,11 +18,13 @@
 // mode", "Migration path". `--json` envelope shape in Phase 3 is the v1
 // surface; strict stdout/stderr channel discipline lands in Phase 5.
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 import * as readline from 'node:readline';
 import { GuardrailError } from "../core/errors.js";
 import { foldEvents, readEvents } from "../core/run-state/events.js";
 import { acquireRunLock } from "../core/run-state/lock.js";
+import { forceUnlockRepoLock, formatLockDiagnostic, isLockStale, peekRepoLock, } from "../core/run-state/repo-lock.js";
 import { decideReplay } from "../core/run-state/replay-decision.js";
 import { readStateSnapshot, statePath, writeStateSnapshot } from "../core/run-state/state.js";
 import { isValidULID } from "../core/run-state/ulid.js";
@@ -897,6 +899,230 @@ function diffStates(a, b) {
     }
     return null;
 }
+/** Default user prompt — single line, expects exactly the string `yes`. */
+function defaultPromptFn(question) {
+    return new Promise(resolve => {
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        rl.question(question, answer => {
+            rl.close();
+            resolve(answer);
+        });
+    });
+}
+/** Resolve the default repo-lock path relative to a given cwd. */
+function defaultRepoLockPath(cwd) {
+    return path.join(cwd, '.claude', 'run-state', 'repo.lock');
+}
+/**
+ * Validate that a caller-supplied `lockPath` is safe to use. We accept:
+ *   - the conventional default `<cwd>/.claude/run-state/repo.lock`
+ *   - paths under the OS temp dir (for tests using `mkdtemp` scratch dirs)
+ *
+ * Anything else throws. This protects against an internal caller routing
+ * user-controlled input into `forceUnlockRepoLock`, which would otherwise
+ * remove arbitrary `<path>` + `<path>.lock` pairs on disk.
+ *
+ * Codex pass 2 WARNING — the `lockPath` option remained on the exported
+ * API surface even after the CLI flag was removed.
+ */
+function assertSafeLockPath(lockPath, cwd) {
+    const conventional = defaultRepoLockPath(cwd);
+    const tmpRoot = os.tmpdir();
+    const resolved = path.resolve(lockPath);
+    if (resolved === path.resolve(conventional))
+        return;
+    // Allow temp-dir paths for tests. Use realpath-resolved tmpdir to handle
+    // /var → /private/var on macOS.
+    let tmpResolved;
+    try {
+        tmpResolved = fs.realpathSync(tmpRoot);
+    }
+    catch {
+        tmpResolved = path.resolve(tmpRoot);
+    }
+    const resolvedReal = (() => {
+        try {
+            return fs.realpathSync(path.dirname(resolved)) + path.sep + path.basename(resolved);
+        }
+        catch {
+            return resolved;
+        }
+    })();
+    if (resolvedReal.startsWith(tmpResolved + path.sep))
+        return;
+    throw new GuardrailError(`runs cleanup: lockPath override outside the expected location is refused (got "${lockPath}", expected "${conventional}" or a temp-dir path)`, {
+        code: 'invalid_config',
+        provider: 'runs-cli',
+        details: { lockPath, conventional },
+    });
+}
+/**
+ * `runs cleanup --force-unlock` — surface the holder, require explicit
+ * `yes` confirmation, then unlink the lock metadata + the proper-lockfile
+ * `.lock` directory. Idempotent: if nothing is held, returns success with
+ * a "nothing to do" message.
+ */
+export async function runRunsCleanup(opts) {
+    const cwd = opts.cwd ?? process.cwd();
+    const json = !!opts.json;
+    const lockPath = opts.lockPath ?? defaultRepoLockPath(cwd);
+    // Validate lockPath if it was supplied (Codex pass 2 WARNING).
+    if (opts.lockPath) {
+        try {
+            assertSafeLockPath(opts.lockPath, cwd);
+        }
+        catch (err) {
+            return maybeEnvelope('runs cleanup', json, {
+                exit: 1,
+                stdout: [],
+                stderr: [`[claude-autopilot] runs cleanup: ${formatErr(err)}`],
+            }, { error: formatErr(err) });
+        }
+    }
+    if (!opts.forceUnlock) {
+        const err = new GuardrailError('runs cleanup requires an operation flag — currently only --force-unlock is supported', {
+            code: 'invalid_config',
+            provider: 'runs-cli',
+            details: { lockPath },
+        });
+        return maybeEnvelope('runs cleanup', json, {
+            exit: 1,
+            stdout: [],
+            stderr: [`[claude-autopilot] runs cleanup: ${formatErr(err)}`],
+        }, { error: formatErr(err) });
+    }
+    // Read existing metadata. Missing meta + missing lock dir = nothing to
+    // clean; we say so and exit 0 (idempotent).
+    const meta = peekRepoLock(lockPath);
+    const lockDirExists = fs.existsSync(lockPath + '.lock');
+    if (!meta && !lockDirExists) {
+        return maybeEnvelope('runs cleanup', json, {
+            exit: 0,
+            stdout: [`runs cleanup: no repo lock at ${lockPath} — nothing to do`],
+            stderr: [],
+        }, { lockPath, cleared: false, reason: 'no-lock-present' });
+    }
+    // Print the diagnostic so the user knows exactly what they're clearing.
+    const diagnosticLines = [];
+    if (meta) {
+        diagnosticLines.push(formatLockDiagnostic(meta, lockPath));
+    }
+    else {
+        diagnosticLines.push(`Repo lock at ${lockPath} exists but has no metadata sidecar.`, '(The holder likely crashed between acquiring the lock and writing metadata.)');
+    }
+    // Safety gate: refuse to clear non-stale locks without --allow-active.
+    // A stale lock (dead PID AND >1h old) is safe to clear; anything else
+    // — live holder, unknown holder (no metadata), or cross-host — is
+    // suspicious. Codex pass 1 WARNING flagged that scripted `--yes` could
+    // silently steal an active lock. (#189 PR review)
+    //
+    // Fail-closed semantics (Codex pass 2 WARNING): only proceed when
+    // `isLockStale(meta) === true`. Any other value (false, or — if the
+    // signature evolves — null/undefined for "cannot determine") falls
+    // back to refusing without --allow-active.
+    const isConfirmedStale = meta ? isLockStale(meta) === true : false;
+    if (!isConfirmedStale && !opts.allowActive) {
+        const err = new GuardrailError(meta
+            ? `repo lock at ${lockPath} is not stale (holder appears active) — re-run with --allow-active to override`
+            : `repo lock at ${lockPath} has no metadata sidecar — holder identity is unknown. Re-run with --allow-active to override`, {
+            code: 'invalid_config',
+            provider: 'runs-cli',
+            details: { lockPath, ...(meta ? { metadata: meta } : {}) },
+        });
+        return maybeEnvelope('runs cleanup', json, {
+            exit: 1,
+            stdout: [],
+            stderr: [
+                ...diagnosticLines,
+                '',
+                `[claude-autopilot] runs cleanup: ${formatErr(err)}`,
+            ],
+        }, { error: formatErr(err), lockPath, ...(meta ? { previousHolder: meta } : {}) });
+    }
+    // Confirmation — REQUIRED in text mode, may be bypassed by --yes in
+    // scripted mode. JSON mode without --yes is rejected: we will not
+    // dump a confirmation prompt to JSON consumers.
+    if (!opts.yes) {
+        if (json) {
+            const err = new GuardrailError('runs cleanup --force-unlock requires --yes when used with --json', {
+                code: 'invalid_config',
+                provider: 'runs-cli',
+                details: { lockPath },
+            });
+            return maybeEnvelope('runs cleanup', json, {
+                exit: 1,
+                stdout: [],
+                stderr: [`[claude-autopilot] runs cleanup: ${formatErr(err)}`],
+            }, { error: formatErr(err), lockPath });
+        }
+        // Print diagnostic to stderr so it appears even under output piping.
+        for (const line of diagnosticLines) {
+            process.stderr.write(`${line}\n`);
+        }
+        process.stderr.write('\n');
+        const prompt = opts.promptFn ?? defaultPromptFn;
+        const answer = (await prompt('Type "yes" to force-unlock: ')).trim();
+        if (answer !== 'yes') {
+            return {
+                exit: 1,
+                stdout: [],
+                stderr: [`runs cleanup: aborted (confirmation not "yes")`],
+            };
+        }
+    }
+    // TOCTOU re-check (Codex pass 2 WARNING): between the safety gate above
+    // and the actual unlock, the holder could have released and a new
+    // process could have acquired the lock. Re-read the metadata and refuse
+    // the unlock if the holder identity changed since the diagnostic was
+    // printed. Skipped when --allow-active was explicitly requested (the
+    // user has accepted the risk; this branch is reserved for force-clear
+    // operations that should not be blocked by a fast-acquiring sibling).
+    if (!opts.allowActive) {
+        const refreshed = peekRepoLock(lockPath);
+        const sameHolder = (refreshed === null && meta === null) ||
+            (refreshed !== null &&
+                meta !== null &&
+                refreshed.pid === meta.pid &&
+                refreshed.hostname === meta.hostname &&
+                refreshed.run_id === meta.run_id &&
+                refreshed.acquired_at_iso === meta.acquired_at_iso);
+        if (!sameHolder) {
+            const err = new GuardrailError('repo lock changed hands during cleanup — refusing to clear the new holder', {
+                code: 'invalid_config',
+                provider: 'runs-cli',
+                details: {
+                    lockPath,
+                    ...(meta ? { observedHolder: meta } : {}),
+                    ...(refreshed ? { currentHolder: refreshed } : {}),
+                },
+            });
+            return maybeEnvelope('runs cleanup', json, {
+                exit: 1,
+                stdout: [],
+                stderr: [`[claude-autopilot] runs cleanup: ${formatErr(err)}`],
+            }, { error: formatErr(err), lockPath });
+        }
+    }
+    const removed = forceUnlockRepoLock(lockPath);
+    const stale = meta ? isLockStale(meta) : null;
+    return maybeEnvelope('runs cleanup', json, {
+        exit: 0,
+        stdout: [
+            ...diagnosticLines,
+            removed
+                ? `runs cleanup: removed repo lock at ${lockPath}`
+                : `runs cleanup: nothing to remove at ${lockPath}`,
+        ],
+        stderr: [],
+    }, {
+        lockPath,
+        cleared: removed,
+        ...(meta ? { previousHolder: meta, wasStale: stale } : {}),
+    });
+}
 // `statePath` is re-exported for convenience to keep CLI imports tidy.
 export { statePath };
 //# sourceMappingURL=runs.js.map

package/dist/src/core/concurrent-dispatch/budget-reservation.d.ts

@@ -0,0 +1,163 @@
+import { GuardrailError } from '../errors.ts';
+import { SerializedWriter } from '../run-state/serialized-writer.ts';
+/** Budget caps for a single run. `perRunUSD` is the hard ceiling on total
+ *  committed spend (spent + active reservations) across all concurrent
+ *  tasks. `perSubagentUSD` is the per-task hard cap that dispatch refuses
+ *  to exceed even if perRunUSD has headroom. */
+export interface BudgetCaps {
+    /** Total USD this run is allowed to commit across all subagents +
+     *  in-flight reservations. */
+    perRunUSD: number;
+    /** Hard per-subagent cap. A pre-flight estimate exceeding this rejects
+     *  dispatch; an actual cost exceeding it mid-execution triggers the
+     *  scheduler's SIGTERM path (PR 4) — this layer just emits the
+     *  `task.failed` event with `error_type: 'budget_exceeded'`. */
+    perSubagentUSD: number;
+}
+/** Per-task ledger entry. Reconstructed via `replayFromEvents` at startup
+ *  / resume. */
+export interface ReservationEntry {
+    task_id: string;
+    /** Latest reservation value (after any
+     *  `task.budget_increased_reservation` events; ABSOLUTE, not delta). */
+    reserved_usd: number;
+    /** True once `task.budget_released` has landed for this task. */
+    released: boolean;
+    /** Actual cost if `released` is true. */
+    actual_cost_usd?: number;
+}
+/** Result of replaying events.ndjson into a fresh ledger state. */
+export interface BudgetReplaySummary {
+    /** Sum of `actual_cost_usd` across released tasks. Committed against
+     *  `perRunUSD` permanently. */
+    spentTotal: number;
+    /** Sum of `reserved_usd` for tasks NOT yet released. Each task
+     *  contributes its LATEST reservation (absolute value), not the sum of
+     *  reserved + increased values. */
+    activeReservedTotal: number;
+    /** `spentTotal + activeReservedTotal`. The number the headroom check
+     *  compares against `perRunUSD`. */
+    committedTotal: number;
+    /** Per-task latest state. */
+    perTask: Map<string, ReservationEntry>;
+}
+/** Thrown by `reserve()` / `increaseReservation()` when the requested
+ *  amount would push the run over `perRunUSD`, or when a pre-flight
+ *  exceeds `perSubagentUSD`. Carries the GuardrailError code
+ *  `budget_exceeded` for upstream resume classification. */
+export declare class BudgetExceededError extends GuardrailError {
+    constructor(message: string, details: Record<string, unknown>);
+}
+export interface ReserveOptions {
+    /** Pre-flight cost estimate for the task in USD. */
+    preFlightEstimateUsd: number;
+    /** Budget caps for this run. */
+    caps: BudgetCaps;
+}
+export interface IncreaseReservationOptions {
+    /** New reservation total (NOT a delta — the absolute new value). */
+    newReservedUsd: number;
+    /** Free-form reason captured on the event. */
+    reason: string;
+    /** Budget caps for this run. */
+    caps: BudgetCaps;
+}
+export interface ReleaseOptions {
+    /** Actual cost spent by the subagent (from telemetry). */
+    actualCostUsd: number;
+}
+/**
+ * Budget reservation ledger. One instance per run, owned by the scheduler.
+ * All mutations route through the supplied `SerializedWriter` and re-replay
+ * events.ndjson under the exclusive lock so they are atomic against
+ * concurrent callers AND any other `BudgetReservation` instances pointed at
+ * the same run.
+ */
+export declare class BudgetReservation {
+    private readonly writer;
+    /** In-memory mirror of disk state, kept for fast `snapshot()` reads.
+     *  NOT authoritative — every mutating operation re-replays the on-disk
+     *  log inside the writer's exclusive lock before checking caps. Per-task
+     *  reservations stored in USD (public API); the running totals below are
+     *  in MICROS (integer-safe arithmetic). */
+    private reservations;
+    private spentMicros;
+    private activeReservedMicros;
+    constructor(writer: SerializedWriter);
+    /** Re-seed in-memory state from events.ndjson. Call on construction OR
+     *  on resume. Safe to call multiple times — overwrites the cache. */
+    hydrateFromEvents(eventsNdjsonPath: string): Promise<void>;
+    /** Read the current in-memory state. Best-effort: a concurrent writer
+     *  in another instance could make this stale until the next mutating
+     *  call re-hydrates from disk. */
+    snapshot(): BudgetReplaySummary;
+    /**
+     * Reserve budget for a task. Atomic under the writer lock:
+     *
+     *   1. HARD cap check (pre-lock): `preFlightEstimate <= caps.perSubagentUSD`
+     *   2. Acquire SerializedWriter lock
+     *   3. Re-replay events.ndjson from disk (authoritative)
+     *   4. Verify task doesn't already have an in-flight reservation
+     *   5. Verify `caps.perRunUSD - committedTotal >= preFlightEstimate`
+     *      (committedTotal = spent + active reservations)
+     *   6. If pass: append `task.budget_reserved` event + fsync
+     *      If fail: append `task.budget_halt` event + fsync, then throw
+     *   7. Release lock
+     *
+     * Throws `BudgetExceededError` on cap violations. The `task.budget_halt`
+     * variant is durable: the event lands inside the same critical section
+     * before the throw propagates, so a crash post-throw still surfaces the
+     * halt on resume.
+     */
+    reserve(taskId: string, opts: ReserveOptions): Promise<void>;
+    /**
+     * Bump an in-flight reservation to a new ABSOLUTE value. Atomic under
+     * the writer lock; re-replays disk state before checking caps.
+     * Re-checks `perRunUSD` against the NEW reservation total; halts the
+     * run with `task.budget_halt` if the bump would exceed the cap.
+     *
+     * Throws `BudgetExceededError` (with durable `task.budget_halt`) if no
+     * prior reservation exists, the bump is downward (use `release`
+     * instead), or the bump exceeds caps.
+     */
+    increaseReservation(taskId: string, opts: IncreaseReservationOptions): Promise<void>;
+    /**
+     * Release a reservation with the actual cost. Atomic under the writer
+     * lock; re-replays disk state. Moves the task's commitment from
+     * `activeReserved` to `spent`. Emits `task.budget_released` with
+     * `delta_vs_reservation_usd` (positive = under, negative = over).
+     *
+     * Note: a release with `actualCostUsd > reserved_usd` is NOT a halt —
+     * the budget was already committed at reservation time. The scheduler
+     * is expected to issue `increaseReservation` mid-flight when telemetry
+     * suggests overrun, and to emit `task.failed{error_type:'budget_exceeded'}`
+     * if the increase itself fails. This `release` just records the truth.
+     */
+    release(taskId: string, opts: ReleaseOptions): Promise<void>;
+    /** Internal: replace in-memory ledger from a replay summary (in micros).
+     *  Used by every mutating method to re-sync cache with disk under the
+     *  lock. */
+    private applyReplayMicros;
+    /**
+     * Replay events.ndjson into a fresh `BudgetReplaySummary` (decimal USD).
+     * Used by:
+     *   1. `hydrateFromEvents` — runtime cache seed on resume / startup
+     *   2. tests — to assert reconstruction is exact
+     *
+     * Internally calls `replayFromEventsMicros` and converts to USD at the
+     * boundary so external consumers see decimal numbers, but the fold itself
+     * is integer-micro arithmetic.
+     *
+     * Line parsing is lenient: blank lines are skipped, parse failures stop
+     * the walk (treated as truncated tail; the next `appendEvent` would
+     * emit `run.recovery`, and budget state stays consistent up to the
+     * last-known-good line).
+     */
+    static replayFromEvents(eventsNdjsonPath: string): BudgetReplaySummary;
+    /**
+     * Internal: micro-precision replay. Used by every mutating method INSIDE
+     * `withExclusive` so cap checks operate on integer arithmetic.
+     */
+    private static replayFromEventsMicros;
+}
+//# sourceMappingURL=budget-reservation.d.ts.map