@ashlr/hub 2.2.0

package/dist/core/sandbox/audit.js

@@ -0,0 +1,169 @@
+/**
+ * M21: Append-only audit trail for autonomous/sandbox actions.
+ *
+ * Writes to ~/.ashlr/audit/<YYYY-MM-DD>.jsonl — one JSON object per line.
+ * Rules:
+ *   - Append-only: never truncate, never rewrite, never delete a prior line.
+ *   - Never write secrets: summary is metadata only; secret-shaped tokens are
+ *     stripped defensively before persisting.
+ *   - audit() never throws; readAudit() skips malformed lines, never throws.
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { existsSync, mkdirSync, readdirSync, appendFileSync, readFileSync, } from 'node:fs';
+// ---------------------------------------------------------------------------
+// Public: auditDir()
+// ---------------------------------------------------------------------------
+/**
+ * Returns the absolute path to the audit directory: ~/.ashlr/audit.
+ * Created lazily by audit() — this function itself does NOT create it.
+ */
+export function auditDir() {
+    return join(homedir(), '.ashlr', 'audit');
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/** Current date as YYYY-MM-DD (UTC) for the daily file name. */
+function todayDateString() {
+    return new Date().toISOString().slice(0, 10);
+}
+/**
+ * Defensively strip secret-shaped tokens from a summary string before
+ * persisting. Targets common patterns: long hex strings, bearer tokens,
+ * base64-looking blobs, and key=value pairs that look like credentials.
+ *
+ * This is a best-effort guardrail — the contract says "summary is metadata
+ * only, never secrets"; callers are the primary enforcement point.
+ */
+function stripSecrets(summary) {
+    return (summary
+        // bearer / auth headers
+        .replace(/\b(Bearer|Token|Authorization)\s+[A-Za-z0-9\-._~+/]+=*/gi, '$1 [REDACTED]')
+        // key=value credential patterns  (api_key=xxx, secret=xxx, token=xxx, password=xxx)
+        .replace(/\b(api[_-]?key|secret|token|password|passwd|auth|credential)[=:\s]+[^\s,;'"]{8,}/gi, '$1=[REDACTED]')
+        // Known-prefix provider tokens (anchored on the prefix so we don't redact
+        // ordinary identifiers). Covers OpenAI/Anthropic-style sk-, GitHub PAT/OAuth
+        // ghp_/gho_/ghu_/ghs_/ghr_, Slack xox[baprs]-, and AWS access key ids.
+        .replace(/\bsk-[A-Za-z0-9_-]{16,}/g, '[REDACTED]')
+        .replace(/\bgh[poursa]_[A-Za-z0-9]{16,}/g, '[REDACTED]')
+        .replace(/\bxox[baprs]-[A-Za-z0-9-]{10,}/gi, '[REDACTED]')
+        .replace(/\bAKIA[0-9A-Z]{16}\b/g, '[REDACTED]')
+        // JWTs: three base64url segments separated by dots, header starts with eyJ.
+        .replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g, '[REDACTED]')
+        // Long hex strings ≥ 40 hex chars (private keys, raw API keys). Threshold
+        // raised above 32 so git SHA-1 (40) is borderline — but git short SHAs and
+        // path components are <40, and we WANT full forensic SHAs preserved, so we
+        // anchor on a length that real secrets exceed while commit/file metadata
+        // generally does not. Conservative: over-redaction would harm forensics.
+        .replace(/\b[0-9a-fA-F]{64,}\b/g, '[REDACTED]'));
+}
+// ---------------------------------------------------------------------------
+// Public: audit()
+// ---------------------------------------------------------------------------
+/**
+ * Append one audit entry to today's JSONL file under ~/.ashlr/audit/.
+ * Sets `ts` to the current ISO timestamp; the caller supplies everything else.
+ *
+ * Append-only: never truncates, never rewrites existing lines.
+ * Never throws — errors are swallowed silently to keep callers unblocked.
+ */
+export function audit(entry) {
+    try {
+        const dir = auditDir();
+        // Ensure audit directory exists (lazy mkdir).
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        const record = {
+            ts: new Date().toISOString(),
+            action: entry.action,
+            repo: entry.repo,
+            sandboxId: entry.sandboxId,
+            // Strip secret-shaped tokens defensively; summary is metadata only.
+            summary: stripSecrets(entry.summary),
+            result: entry.result,
+        };
+        const line = JSON.stringify(record) + '\n';
+        const filePath = join(dir, `${todayDateString()}.jsonl`);
+        // Append-only — appendFileSync creates the file if missing, never truncates.
+        appendFileSync(filePath, line, 'utf8');
+    }
+    catch {
+        // Intentionally swallowed: audit must never disrupt the caller's flow.
+    }
+}
+// ---------------------------------------------------------------------------
+// Public: readAudit()
+// ---------------------------------------------------------------------------
+/**
+ * Read audit entries across all date files, newest-first.
+ * `limit` caps the number returned (undefined or 0 => return all).
+ *
+ * Malformed JSONL lines are silently skipped; never throws.
+ */
+export function readAudit(limit) {
+    try {
+        const dir = auditDir();
+        if (!existsSync(dir)) {
+            return [];
+        }
+        // List all .jsonl files, sort descending (newest date first).
+        let files;
+        try {
+            files = readdirSync(dir)
+                .filter((f) => f.endsWith('.jsonl'))
+                .sort()
+                .reverse();
+        }
+        catch {
+            return [];
+        }
+        const entries = [];
+        const cap = limit !== undefined && limit > 0 ? limit : Infinity;
+        for (const file of files) {
+            if (entries.length >= cap)
+                break;
+            const filePath = join(dir, file);
+            let raw;
+            try {
+                raw = readFileSync(filePath, 'utf8');
+            }
+            catch {
+                continue; // unreadable file — skip
+            }
+            // Collect lines in reverse order so newest entries within the file come first.
+            const lines = raw.split('\n').filter((l) => l.trim() !== '').reverse();
+            for (const line of lines) {
+                if (entries.length >= cap)
+                    break;
+                try {
+                    const parsed = JSON.parse(line);
+                    if (parsed !== null &&
+                        typeof parsed === 'object' &&
+                        !Array.isArray(parsed)) {
+                        // Light structural validation — skip clearly malformed entries.
+                        const obj = parsed;
+                        if (typeof obj['ts'] === 'string' &&
+                            typeof obj['action'] === 'string' &&
+                            typeof obj['summary'] === 'string' &&
+                            (obj['result'] === 'ok' ||
+                                obj['result'] === 'refused' ||
+                                obj['result'] === 'error')) {
+                            entries.push(obj);
+                        }
+                    }
+                }
+                catch {
+                    // Malformed JSON line — skip silently.
+                }
+            }
+        }
+        return entries;
+    }
+    catch {
+        // Top-level guard: readAudit must never throw.
+        return [];
+    }
+}
+//# sourceMappingURL=audit.js.map

package/dist/core/sandbox/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../../src/core/sandbox/audit.ts"],"names":[],"mappings":"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"}

package/dist/core/sandbox/policy.d.ts

@@ -0,0 +1,61 @@
+/**
+ * policy.ts — Enrollment registry + kill switch (the gate).
+ *
+ * SAFETY RULES:
+ *  - Enrollment registry persisted at ~/.ashlr/enrollment.json, DEFAULT EMPTY.
+ *  - Kill switch backed by the presence of ~/.ashlr/KILL file.
+ *  - assertMayMutate ALWAYS throws when the kill switch is on, regardless of
+ *    enrollment or allowAnyRepo. allowAnyRepo ONLY bypasses the enrollment
+ *    check (for tests operating on tmp repos) — it NEVER bypasses the kill switch.
+ *  - enroll/unenroll normalize repo paths to absolute via path.resolve().
+ *  - All functions are idempotent; never throw except the intentional assert.
+ *  - No new runtime deps; node builtins only.
+ */
+/** Path to the enrollment registry file. */
+export declare function enrollmentPath(): string;
+/** Path to the kill-switch sentinel file. */
+export declare function killSwitchPath(): string;
+/**
+ * Returns true when the global kill switch is active.
+ * Backed by the presence of ~/.ashlr/KILL.
+ */
+export declare function killSwitchOn(): boolean;
+/**
+ * Turn the kill switch on (creates ~/.ashlr/KILL) or off (removes it).
+ * Idempotent in both directions.
+ */
+export declare function setKill(on: boolean): void;
+/**
+ * Returns true when `repo` (normalized to absolute path) is enrolled
+ * for autonomous work.
+ */
+export declare function isEnrolled(repo: string): boolean;
+/**
+ * Enroll `repo` for autonomous/sandbox mutation. Idempotent — enrolling
+ * an already-enrolled repo is a no-op. Normalizes to absolute path.
+ */
+export declare function enroll(repo: string): void;
+/**
+ * Remove `repo` from the enrollment registry. Idempotent — unenrolling
+ * an absent repo is a no-op. Normalizes to absolute path.
+ */
+export declare function unenroll(repo: string): void;
+/**
+ * Return all enrolled repos (absolute paths). Returns [] when nothing is
+ * enrolled (the default state — DEFAULT EMPTY).
+ */
+export declare function listEnrolled(): string[];
+/**
+ * Assert that autonomous/sandbox mutation of `repo` is permitted.
+ *
+ * Throws when:
+ *  1. The kill switch is on (ALWAYS, regardless of enrollment or opts).
+ *  2. `repo` is not enrolled AND `opts.allowAnyRepo` is not true.
+ *
+ * `opts.allowAnyRepo` is a TEST SEAM only — it bypasses enrollment so tests
+ * can operate on tmp repos without enrolling them. It NEVER bypasses the kill
+ * switch.
+ */
+export declare function assertMayMutate(repo: string, opts?: {
+    allowAnyRepo?: boolean;
+}): void;

package/dist/core/sandbox/policy.js

@@ -0,0 +1,211 @@
+/**
+ * policy.ts — Enrollment registry + kill switch (the gate).
+ *
+ * SAFETY RULES:
+ *  - Enrollment registry persisted at ~/.ashlr/enrollment.json, DEFAULT EMPTY.
+ *  - Kill switch backed by the presence of ~/.ashlr/KILL file.
+ *  - assertMayMutate ALWAYS throws when the kill switch is on, regardless of
+ *    enrollment or allowAnyRepo. allowAnyRepo ONLY bypasses the enrollment
+ *    check (for tests operating on tmp repos) — it NEVER bypasses the kill switch.
+ *  - enroll/unenroll normalize repo paths to absolute via path.resolve().
+ *  - All functions are idempotent; never throw except the intentional assert.
+ *  - No new runtime deps; node builtins only.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+// H6 (PART A — audit completeness): emit an audit() record inside
+// enroll/unenroll/setKill so EVERY path (CLI cmdEnroll OR any programmatic
+// caller — fixture, daemon, onboard) is captured — see
+// docs/contracts/CONTRACT-H6.md §A.2. audit.ts imports only node builtins + a
+// `type` from ../types.js and does NOT import policy.ts, so this static import
+// creates NO import cycle (re-verified by an H6 [STATIC] test). Metadata only:
+// action verb + repo abs path (a path is NOT a secret) + 'ok'.
+import { audit } from './audit.js';
+// ---------------------------------------------------------------------------
+// Path helpers (re-resolved at call time so tests can relocate HOME)
+// ---------------------------------------------------------------------------
+function ashlrDir() {
+    return join(homedir(), '.ashlr');
+}
+/** Path to the enrollment registry file. */
+export function enrollmentPath() {
+    return join(ashlrDir(), 'enrollment.json');
+}
+/** Path to the kill-switch sentinel file. */
+export function killSwitchPath() {
+    return join(ashlrDir(), 'KILL');
+}
+// ---------------------------------------------------------------------------
+// Internal I/O helpers
+// ---------------------------------------------------------------------------
+/** Read the enrollment registry. Returns { repos: [] } when absent/malformed. */
+function readRegistry() {
+    const p = enrollmentPath();
+    if (!existsSync(p))
+        return { repos: [] };
+    try {
+        const raw = readFileSync(p, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === 'object' &&
+            parsed !== null &&
+            !Array.isArray(parsed) &&
+            Array.isArray(parsed['repos'])) {
+            const repos = parsed['repos']
+                .filter((r) => typeof r === 'string');
+            return { repos };
+        }
+    }
+    catch {
+        // malformed — treat as empty
+    }
+    return { repos: [] };
+}
+/** Persist the enrollment registry, creating ~/.ashlr if needed. */
+function writeRegistry(reg) {
+    const dir = ashlrDir();
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(enrollmentPath(), JSON.stringify(reg, null, 2) + '\n', 'utf8');
+}
+// ---------------------------------------------------------------------------
+// Kill switch
+// ---------------------------------------------------------------------------
+/**
+ * Returns true when the global kill switch is active.
+ * Backed by the presence of ~/.ashlr/KILL.
+ */
+export function killSwitchOn() {
+    return existsSync(killSwitchPath());
+}
+/**
+ * Turn the kill switch on (creates ~/.ashlr/KILL) or off (removes it).
+ * Idempotent in both directions.
+ */
+export function setKill(on) {
+    const kp = killSwitchPath();
+    const dir = ashlrDir();
+    if (on) {
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        if (!existsSync(kp)) {
+            writeFileSync(kp, 'kill switch active\n', 'utf8');
+        }
+    }
+    else {
+        if (existsSync(kp)) {
+            unlinkSync(kp);
+        }
+    }
+    // H6 (§A.2): audit the kill-switch toggle on EVERY call (idempotent on disk;
+    // we audit the requested intent). repo is null (not repo-scoped); summary is
+    // metadata only. audit() swallows its own errors, so the "never throws"
+    // contract of setKill is preserved.
+    audit({
+        action: on ? 'kill:on' : 'kill:off',
+        repo: null,
+        sandboxId: null,
+        summary: `kill switch ${on ? 'on' : 'off'}`,
+        result: 'ok',
+    });
+}
+// ---------------------------------------------------------------------------
+// Enrollment registry
+// ---------------------------------------------------------------------------
+/**
+ * Returns true when `repo` (normalized to absolute path) is enrolled
+ * for autonomous work.
+ */
+export function isEnrolled(repo) {
+    const abs = resolve(repo);
+    const reg = readRegistry();
+    return reg.repos.includes(abs);
+}
+/**
+ * Enroll `repo` for autonomous/sandbox mutation. Idempotent — enrolling
+ * an already-enrolled repo is a no-op. Normalizes to absolute path.
+ */
+export function enroll(repo) {
+    const abs = resolve(repo);
+    const reg = readRegistry();
+    if (!reg.repos.includes(abs)) {
+        reg.repos.push(abs);
+        writeRegistry(reg);
+    }
+    // H6 (§A.2): audit AFTER the (idempotent) write so a no-op re-enroll STILL
+    // records the requested intent. The repo abs path is metadata, never a secret;
+    // audit() swallows its own errors so enroll's "never throws" contract holds.
+    audit({
+        action: 'enroll:add',
+        repo: abs,
+        sandboxId: null,
+        summary: `enrolled ${abs}`,
+        result: 'ok',
+    });
+}
+/**
+ * Remove `repo` from the enrollment registry. Idempotent — unenrolling
+ * an absent repo is a no-op. Normalizes to absolute path.
+ */
+export function unenroll(repo) {
+    const abs = resolve(repo);
+    const reg = readRegistry();
+    const filtered = reg.repos.filter(r => r !== abs);
+    if (filtered.length !== reg.repos.length) {
+        writeRegistry({ repos: filtered });
+    }
+    // H6 (§A.2): audit AFTER the (idempotent) write so a no-op unenroll STILL
+    // records the requested intent. Metadata only (abs path is not a secret);
+    // audit() swallows its own errors so unenroll's "never throws" contract holds.
+    audit({
+        action: 'enroll:remove',
+        repo: abs,
+        sandboxId: null,
+        summary: `unenrolled ${abs}`,
+        result: 'ok',
+    });
+}
+/**
+ * Return all enrolled repos (absolute paths). Returns [] when nothing is
+ * enrolled (the default state — DEFAULT EMPTY).
+ */
+export function listEnrolled() {
+    return readRegistry().repos;
+}
+// ---------------------------------------------------------------------------
+// assertMayMutate — the gate every sandbox-mutating op calls first
+// ---------------------------------------------------------------------------
+/**
+ * Assert that autonomous/sandbox mutation of `repo` is permitted.
+ *
+ * Throws when:
+ *  1. The kill switch is on (ALWAYS, regardless of enrollment or opts).
+ *  2. `repo` is not enrolled AND `opts.allowAnyRepo` is not true.
+ *
+ * `opts.allowAnyRepo` is a TEST SEAM only — it bypasses enrollment so tests
+ * can operate on tmp repos without enrolling them. It NEVER bypasses the kill
+ * switch.
+ */
+export function assertMayMutate(repo, opts) {
+    // Kill switch check — always enforced, no exceptions.
+    if (killSwitchOn()) {
+        throw new Error('autonomy kill switch is ON');
+    }
+    // Enrollment check — bypassed only by the explicit test hatch.
+    //
+    // H5 CHANGE 3 (env-gate allowAnyRepo): the `allowAnyRepo` hatch is effective
+    // ONLY when the process ALSO sets ASHLR_TEST_ALLOW_ANY_REPO=1, so a stray
+    // `allowAnyRepo:true` in any PRODUCTION path can NEVER bypass enrollment
+    // (mirrors advance.ts:155-157 EXACTLY). The kill-switch check above STAYS
+    // first and unconditional — it always wins (verify-safety CHECK 2 still
+    // passes). createSandbox passes opts straight through, so it inherits this
+    // gate transitively — single source of truth.
+    const allowAnyRepo = opts?.allowAnyRepo === true &&
+        process.env.ASHLR_TEST_ALLOW_ANY_REPO === '1';
+    if (!allowAnyRepo && !isEnrolled(repo)) {
+        throw new Error(`repo not enrolled for autonomous work: ${resolve(repo)}`);
+    }
+}
+//# sourceMappingURL=policy.js.map

package/dist/core/sandbox/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../../../src/core/sandbox/policy.ts"],"names":[],"mappings":"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"}

package/dist/core/sandbox/worktree.d.ts

@@ -0,0 +1,175 @@
+/**
+ * worktree.ts — isolated git-worktree sandbox (M21 SAFETY FOUNDATION).
+ *
+ * Creates an ISOLATED git worktree of a source repo on a NEW scratch branch
+ * under ~/.ashlr/sandboxes/<id>/, so autonomous edits NEVER touch the user's
+ * working tree, index, HEAD, or their checked-out branch. The worktree is
+ * created, used, then discarded (git worktree remove + scratch-branch delete).
+ *
+ * ISOLATION + DESTRUCTIVE-SAFETY (the whole point):
+ *  - Sandbox worktrees live ONLY under ~/.ashlr/sandboxes/.
+ *  - Creating/removing them MUST NOT modify the source repo's working tree,
+ *    index, HEAD, or the user's branches.
+ *  - `git worktree add -b <branch> <path> <baseHead>` off the current HEAD;
+ *    `git worktree remove --force` + `git branch -D` on cleanup.
+ *  - NEVER `git reset --hard` / `git checkout` in the source repo. NEVER push.
+ *    NEVER delete user branches. NEVER touch a repo that is not ENROLLED
+ *    (except via the explicit allowAnyRepo test hatch on a tmp repo).
+ *  - Every mutating op (and every refused/errored attempt) is audited.
+ *  - All git invoked via node:child_process arg ARRAYS (execFile, no shell).
+ *  - No new runtime deps; node builtins only.
+ */
+import type { Sandbox, SandboxDiff } from '../types.js';
+/**
+ * H5 CHANGE 1 — orphan-sweep staleness threshold (ms). This is the FALLBACK
+ * liveness proxy used ONLY for a sandbox that carries no usable `ownerPid`
+ * marker (older metadata, or a crash fixture that models a GONE owner). The
+ * PRIMARY liveness signal is the positive `ownerPid` marker (see Sandbox.ownerPid
+ * + ownerAlive() below): a sandbox whose owner pid is still alive is skipped by
+ * the sweep / disk-cap pre-sweep REGARDLESS of age, so a live in-flight worktree
+ * is never reclaimed out from under a running swarm — even a cross-process one.
+ *
+ * Because there is NO hard wall-clock cap on a swarm (the runner bounds a swarm
+ * by step count <= 200 and the token budget only — there is no elapsed-time
+ * deadline), createdAt-age is NOT by itself a sound liveness proxy. So this
+ * threshold is set FAR above any plausible 200-step run (6 hours) as a
+ * belt-and-suspenders bound for the only residual gap: the rare pid-reuse case
+ * where a crashed swarm's recorded pid was recycled by an unrelated live process
+ * (ownerAlive() would then falsely read 'alive', so age must also have elapsed
+ * before we'd ever reclaim). The cost of a too-LARGE value (a stale orphan
+ * lingering a few hours longer) is far cheaper than the cost of a too-SMALL one
+ * (force-removing a live worktree), so we err large. Shared by the daemon-start
+ * sweep wiring (loop.ts) and the disk-cap pre-sweep below.
+ *
+ * CROSS-PROCESS LIVENESS LIMITATION (documented): the only way a live worktree
+ * could still be reclaimed is if BOTH (a) its owner process crashed AND (b) the
+ * OS recycled its exact pid for a new live process AND (c) >6h elapsed — a
+ * vanishingly small window that, even if hit, only reclaims a worktree whose
+ * original owner is provably dead.
+ */
+export declare const ORPHAN_STALE_MS: number;
+/** Absolute path to the sandboxes root: ~/.ashlr/sandboxes. Created lazily. */
+export declare function sandboxesDir(): string;
+/**
+ * Create an isolated git-worktree sandbox of `sourceRepo` on a NEW scratch
+ * branch under ~/.ashlr/sandboxes/<id>/.
+ *
+ * FIRST calls assertMayMutate(sourceRepo, opts) — refuses (throws + audits
+ * result:'refused') if the kill switch is on OR the repo is not enrolled and
+ * opts.allowAnyRepo is not set. Verifies sourceRepo is a git repo. Reads the
+ * source HEAD WITHOUT mutating it. Adds the worktree via
+ * `git worktree add -b <branch> <path> <baseHead>` run in sourceRepo — this
+ * MUST NOT modify the source working tree, index, HEAD, or any user branch.
+ */
+export declare function createSandbox(sourceRepo: string, opts?: {
+    allowAnyRepo?: boolean;
+}): Sandbox;
+/**
+ * Capture the git diff of the sandbox worktree vs its base HEAD. Read-only —
+ * never mutates the worktree or the source repo. Counts come from --numstat;
+ * the unified patch from a plain `git diff <baseHead>` inside the worktree.
+ */
+export declare function sandboxDiff(sb: Sandbox): SandboxDiff;
+/**
+ * Remove a sandbox: `git worktree remove --force` then delete the scratch
+ * branch (`git branch -D`), both run against the source repo; then clean up
+ * persisted metadata. MUST NOT touch the source working tree/index/HEAD/user
+ * branches. Idempotent — tolerates an already-removed worktree, never throws
+ * on a missing dir.
+ */
+export declare function removeSandbox(sb: Sandbox): void;
+/**
+ * Enumerate persisted sandbox metadata under sandboxesDir(). Returns [] when
+ * none. Never throws on a malformed/partial entry (skips it).
+ */
+export declare function listSandboxes(): Sandbox[];
+/**
+ * Sweep ORPHANED sandboxes on restart (H2 crash-recovery). A swarm creates a
+ * worktree, uses it, then `removeSandbox`es it — all within a single in-memory
+ * `runSwarm` call. The sandbox lifetime is NOT persisted on the SwarmRun (there
+ * is no `sandboxId` field on a SwarmRun; the only `sandboxId` references are
+ * audit-log entries), so a process killed AFTER `git worktree add` but BEFORE
+ * `removeSandbox` leaves a worktree on disk under ~/.ashlr/sandboxes/<id>/ with
+ * no record linking it back to any swarm. Such a leftover would otherwise
+ * accumulate forever.
+ *
+ * LIVENESS (important — read before wiring a caller): a persisted sandbox is NOT
+ * necessarily an orphan. A `runSwarm` keeps its sandbox metadata on disk for the
+ * WHOLE run (createSandbox writes it at start, removeSandbox deletes it at the
+ * end), and the daemon runs several sandboxed swarms CONCURRENTLY, each with a
+ * live on-disk sandbox; a separately-launched `ashlr swarm` in another process is
+ * also possible (the re-entrancy guards are per-process). To NEVER force-remove a
+ * live worktree, the sweep uses TWO guards, in order:
+ *
+ *  1. POSITIVE liveness (primary, age-independent): a sandbox whose recorded
+ *     `ownerPid` is still alive (ownerAlive()) is SKIPPED regardless of age — so
+ *     a long-running swarm (same- OR cross-process) older than any staleMs is
+ *     never reclaimed out from under its owner. This closes the central gap that
+ *     createdAt-age alone could not (there is no wall-clock cap on a swarm).
+ *  2. AGE fallback (secondary): for a sandbox with NO usable ownerPid (older
+ *     metadata, or a crash fixture that models a GONE owner), the OPTIONAL
+ *     `staleMs` guard applies — a sandbox whose `createdAt` is younger than
+ *     `staleMs` is SKIPPED (conservatively assumed possibly-live). With NO
+ *     `staleMs` (the default, used by recovery PROOF tests where every sandbox is
+ *     a deliberately-dropped orphan with a dead/absent owner) it sweeps every
+ *     listed sandbox not protected by guard 1.
+ *
+ * This sweep composes the two EXISTING safe primitives — `listSandboxes()` to
+ * enumerate persisted sandbox metadata, then `removeSandbox()` for each — so it
+ * inherits all of removeSandbox's containment guards verbatim: it only ever runs
+ * `git worktree remove` / `git branch -D` against a path RE-DERIVED to live under
+ * `sandboxesDir()` and a branch RE-DERIVED into the `ashlr/sandbox/<id>` namespace
+ * (a metadata mismatch falls through to LOCAL dir cleanup only — never a git op on
+ * an arbitrary branch/path). It therefore can NEVER touch a user's working tree,
+ * index, HEAD, or any user branch.
+ *
+ * LOCAL-ONLY by construction: it adds NO outward capability (cleanup is purely
+ * inward — it removes only ashlr/sandbox/* worktrees + scratch refs, pushes
+ * nothing, opens no PR, applies no proposal), weakens NO guard (every removal
+ * goes through removeSandbox's full guard set), and changes NO happy-path
+ * behavior (a clean run already removes its own sandbox, so a healthy install
+ * has nothing to sweep). H5 wires this into daemon start (loop.ts, staleMs=
+ * ORPHAN_STALE_MS), the disk-cap pre-sweep above, and `ashlr sandbox gc` — every
+ * caller passes a staleMs and is additionally protected by the age-independent
+ * ownerAlive() guard, so no LIVE worktree is ever force-removed. Idempotent
+ * and never throws — a removal failure on one id is swallowed so the sweep always
+ * makes maximal progress. Returns the ids it swept so a caller / test can assert
+ * what was reclaimed.
+ *
+ * @param opts.staleMs Optional age guard (ms). Skip any sandbox whose `createdAt`
+ *   is younger than this — a conservative liveness proxy so a concurrently-live
+ *   sandbox is never force-removed. Omit to sweep all listed sandboxes.
+ */
+export declare function sweepOrphanSandboxes(opts?: {
+    staleMs?: number;
+}): string[];
+/**
+ * Reclaim the on-disk sandboxes belonging to ONE specific source repo — the
+ * scoped cleanup behind `ashlr onboard --rollback <repo>` (H7 BUILD ITEM 4).
+ *
+ * WHY a distinct sweep (not sweepOrphanSandboxes): the generic orphan sweep is a
+ * BACKGROUND restart heuristic — it protects a possibly-live owner whose pid is
+ * unreadable by ALSO requiring `createdAt` to be older than `staleMs` (6h). But a
+ * crash-leftover worktree from the VERY activation the user is now explicitly
+ * undoing is, by definition, fresh (< 6h old), so the generic sweep would SKIP it
+ * and the rollback would leave it on disk — contradicting "one-command undo of a
+ * first activation". For an explicit, user-requested cleanup of a NAMED repo that
+ * the user just unenrolled, the age heuristic is unwarranted.
+ *
+ * SAFETY (the real boundary is preserved): this drops ONLY the age guard, never
+ * the LIVE-OWNER guard. It still SKIPS any sandbox whose recorded `ownerPid` is
+ * still alive (ownerAlive()), so a running in-flight swarm's worktree is NEVER
+ * force-removed — even a fresh one. It is SCOPED: only sandboxes whose
+ * `sourceRepo` resolves to `resolve(repo)` are considered, so it never touches a
+ * different repo's sandboxes. Each removal goes through removeSandbox(), so it
+ * inherits the full branch-prefix / path-containment guards verbatim and can
+ * NEVER touch a user's working tree, index, HEAD, or any user branch.
+ *
+ * LOCAL-ONLY by construction: adds NO outward capability (inward cleanup only —
+ * removes only ashlr/sandbox/* worktrees + scratch refs), weakens NO guard.
+ * Idempotent; never throws — a failure on one id is swallowed so the sweep makes
+ * maximal progress. Returns the ids it reclaimed.
+ *
+ * @param repo The source repo whose sandboxes to reclaim (resolved internally).
+ */
+export declare function sweepRepoSandboxes(repo: string): string[];