@bridge4dev/runner 0.27.0 → 0.29.0

package/dist/checkpoints.js

@@ -0,0 +1,816 @@
+import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { createHash } from 'node:crypto';
+import { checkpointsDir } from './paths.js';
+import { isSecretPath } from './policy.js';
+import { log } from './log.js';
+const execFileAsync = promisify(execFile);
+// Ticket #126 — restore points for a session's working tree.
+//
+// A checkpoint is an ordinary git tree, built from the worktree as it stands,
+// and kept in an object store of the RUNNER's, never in the project's `.git`.
+// Three properties come out of that choice, and all three are load-bearing:
+//
+//  1. `git status --porcelain` is byte-identical before and after. Nothing is
+//     staged, stashed, committed or checked out to take one — verified on live
+//     repositories in the test suite.
+//  2. The blobs are outside `.git/objects`, so `git push --mirror` cannot carry
+//     them anywhere and `git log --all -p` inside the worktree is structurally
+//     blind to them. The agent's own reads (Bash `git`, `cat`, `grep`) are
+//     denied by `SECRET_PATH_PATTERNS`, which already covers the whole
+//     `devbridge-runner` tree.
+//  3. Secrets never become objects in the first place. The index is built from
+//     an EXPLICIT file list with `update-index`, not from `add -A`, so a `.env`
+//     is not blobbed and then filtered out of the tree — it is never read.
+//     That distinction matters: an unreferenced blob is still a readable blob.
+//
+// The single source of truth for what counts as a secret is `isSecretPath` in
+// `policy.ts`. There is deliberately no second list here (gotcha #110).
+const GIT_TIMEOUT_MS = 30_000;
+/** `--literal-pathspecs`: a path is a path, never a pattern (QA-105 MAJOR-1). */
+const GIT_GLOBAL_ARGS = ['--literal-pathspecs', '-c', 'core.quotePath=false'];
+/** argv has a ceiling; every path list is fed in batches of this size. */
+const PATH_BATCH = 400;
+/**
+ * Ceilings on one checkpoint.
+ *
+ * An unignored `dist/` would otherwise be blobbed on every single turn. When a
+ * ceiling is hit the checkpoint is SKIPPED and the caller says so out loud —
+ * a restore point that silently is not there is worse than none at all.
+ */
+const MAX_CHECKPOINT_FILES = 20_000;
+const MAX_CHECKPOINT_BYTES = 512 * 1024 * 1024;
+/** A single file bigger than this is left out of the checkpoint (with a notice). */
+const MAX_CHECKPOINT_FILE_BYTES = 64 * 1024 * 1024;
+/** Retention: nothing older than this survives, whatever the ordinal. */
+export const CHECKPOINT_MAX_AGE_MS = 14 * 24 * 3_600_000;
+/** Retention: the newest N per session. */
+export const CHECKPOINT_MAX_PER_SESSION = 200;
+/**
+ * How long the points of a session nobody mentions are kept anyway.
+ *
+ * The list of live sessions arrives capped, so absence from it is weak
+ * evidence. A day of silence is strong evidence — and until then the cost of
+ * being wrong is disk, while the cost of being wrong the other way is the only
+ * copy of somebody's uncommitted work.
+ */
+export const ORPHAN_GRACE_MS = 24 * 3_600_000;
+/**
+ * Where this repository's checkpoints live.
+ *
+ * Keyed by the repo's common git dir, so a session worktree and the project
+ * folder it belongs to share one store — which is what makes a DIRECT session
+ * and a BRANCH session on the same project interchangeable here.
+ */
+async function storeFor(worktreePath) {
+    const commonDir = await gitIn(worktreePath, 'rev-parse', '--path-format=absolute', '--git-common-dir');
+    const real = await realpath(commonDir);
+    const key = createHash('sha256').update(real).digest('hex').slice(0, 32);
+    return {
+        store: path.join(checkpointsDir(), `${key}.git`),
+        objectDir: path.join(real, 'objects'),
+    };
+}
+async function realpath(p) {
+    try {
+        return await fs.promises.realpath(p);
+    }
+    catch {
+        return p;
+    }
+}
+async function gitIn(cwd, ...args) {
+    const { stdout } = await execFileAsync('git', [...GIT_GLOBAL_ARGS, ...args], {
+        cwd,
+        timeout: GIT_TIMEOUT_MS,
+        maxBuffer: 32 * 1024 * 1024,
+        // The project's own environment must not leak in: a GIT_INDEX_FILE or
+        // GIT_DIR inherited from a parent process would silently retarget every
+        // command below at the wrong repository.
+        env: cleanEnv(),
+    });
+    return stdout.replace(/\n$/, '');
+}
+/**
+ * Run git against the checkpoint store with the project as its working tree.
+ *
+ * `GIT_INDEX_FILE` is inside the runner's state directory and never inside the
+ * worktree: an index file left in the project would be blobbed by the NEXT
+ * checkpoint, which is both a leak and an infinite growth loop.
+ */
+async function gitStore(store, worktreePath, indexFile, ...args) {
+    const { stdout } = await execFileAsync('git', [...GIT_GLOBAL_ARGS, ...args], {
+        cwd: worktreePath,
+        timeout: GIT_TIMEOUT_MS,
+        maxBuffer: 32 * 1024 * 1024,
+        env: {
+            ...cleanEnv(),
+            GIT_DIR: store,
+            GIT_WORK_TREE: worktreePath,
+            GIT_INDEX_FILE: indexFile,
+            GIT_AUTHOR_NAME: 'DevBridge',
+            GIT_AUTHOR_EMAIL: 'runner@devbridge.local',
+            GIT_COMMITTER_NAME: 'DevBridge',
+            GIT_COMMITTER_EMAIL: 'runner@devbridge.local',
+        },
+    });
+    return stdout.replace(/\n$/, '');
+}
+function cleanEnv() {
+    const env = { ...process.env };
+    delete env['GIT_DIR'];
+    delete env['GIT_WORK_TREE'];
+    delete env['GIT_INDEX_FILE'];
+    delete env['GIT_OBJECT_DIRECTORY'];
+    delete env['GIT_ALTERNATE_OBJECT_DIRECTORIES'];
+    return env;
+}
+async function ensureStore(worktreePath) {
+    const { store, objectDir } = await storeFor(worktreePath);
+    if (!fs.existsSync(store)) {
+        fs.mkdirSync(path.dirname(store), { recursive: true, mode: 0o700 });
+        await execFileAsync('git', ['init', '--quiet', '--bare', store], {
+            timeout: GIT_TIMEOUT_MS,
+            env: cleanEnv(),
+        });
+        fs.chmodSync(store, 0o700);
+    }
+    // Alternates let the store READ the project's objects (so `read-tree HEAD`
+    // resolves) while every object it WRITES stays on its own side. The direction
+    // is one-way: the project's git cannot see anything in here — asserted in the
+    // test suite, because that one-way-ness is the whole security argument.
+    const alternates = path.join(store, 'objects', 'info', 'alternates');
+    const wanted = `${objectDir}\n`;
+    if (!fs.existsSync(alternates) || fs.readFileSync(alternates, 'utf8') !== wanted) {
+        fs.mkdirSync(path.dirname(alternates), { recursive: true, mode: 0o700 });
+        fs.writeFileSync(alternates, wanted, { mode: 0o600 });
+    }
+    return store;
+}
+function indexFileFor(sessionId) {
+    return path.join(checkpointsDir(), 'index', `${sessionId}.idx`);
+}
+/**
+ * A private index file for ONE operation.
+ *
+ * Not one per session: a checkpoint taken while a preview is being built would
+ * otherwise share an index with it, and the loser of that race writes a tree
+ * describing a state that never existed. `git` gives no locking here — the
+ * file IS the state — so the isolation has to come from the name.
+ */
+let indexCounter = 0;
+function tempIndexFile(sessionId, tag) {
+    indexCounter += 1;
+    return path.join(checkpointsDir(), 'index', `${sessionId}.${tag}.${process.pid}.${indexCounter}.idx`);
+}
+const REF_PREFIX = 'refs/devbridge/checkpoints/';
+function refFor(sessionId, ordinal) {
+    return `${REF_PREFIX}${sessionId}/${ordinal}`;
+}
+/**
+ * Run git against a store alone — no working tree involved.
+ *
+ * Ref bookkeeping and garbage collection need no checkout, and demanding one
+ * would make housekeeping impossible for exactly the repositories that need it
+ * most: the ones whose sessions are already gone.
+ */
+async function gitRefs(store, ...args) {
+    const { stdout } = await execFileAsync('git', [...GIT_GLOBAL_ARGS, '--git-dir', store, ...args], {
+        timeout: GIT_TIMEOUT_MS,
+        maxBuffer: 32 * 1024 * 1024,
+        env: cleanEnv(),
+    });
+    return stdout.replace(/\n$/, '');
+}
+/** Checkpoint metadata read straight from a store, with no worktree. */
+async function readRecord(store, sessionId, ordinal) {
+    try {
+        const commit = await gitRefs(store, 'rev-parse', `${refFor(sessionId, ordinal)}^{commit}`);
+        const meta = decodeMeta(await gitRefs(store, 'log', '-1', '--format=%B', commit));
+        return meta ? { ordinal, commit, ...meta } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** NUL-separated git output → array, with the trailing empty field dropped. */
+function splitZ(raw) {
+    return raw.split('\0').filter((entry) => entry.length > 0);
+}
+/**
+ * Everything in the worktree that differs from HEAD right now, minus secrets.
+ *
+ * `-uall` matters: without it git collapses an untracked directory into a
+ * single `dir/` entry, and a checkpoint built from that list would silently
+ * miss every file inside it.
+ */
+async function changedPaths(worktreePath) {
+    const raw = await gitIn(worktreePath, 'status', '--porcelain=v1', '-uall', '-z');
+    const paths = [];
+    const secrets = [];
+    // Porcelain v1 with -z: `XY <path>` records, and a rename adds a second
+    // NUL-separated field. Both sides of a rename are ordinary paths for us.
+    const fields = splitZ(raw);
+    for (let i = 0; i < fields.length; i += 1) {
+        const entry = fields[i];
+        if (!entry || entry.length < 4)
+            continue;
+        const status = entry.slice(0, 2);
+        const file = entry.slice(3);
+        if (status[0] === 'R' || status[0] === 'C') {
+            // `R  new\0old` — the following field is the old path.
+            const old = fields[i + 1];
+            i += 1;
+            if (old)
+                push(old);
+        }
+        push(file);
+    }
+    function push(file) {
+        if (!file)
+            return;
+        const absolute = path.join(worktreePath, file);
+        if (isSecretPath(absolute)) {
+            secrets.push(file);
+            return;
+        }
+        paths.push(file);
+    }
+    return { paths: [...new Set(paths)], secrets: [...new Set(secrets)] };
+}
+async function runBatched(store, worktreePath, indexFile, args, paths) {
+    for (let i = 0; i < paths.length; i += PATH_BATCH) {
+        await gitStore(store, worktreePath, indexFile, ...args, '--', ...paths.slice(i, i + PATH_BATCH));
+    }
+}
+/**
+ * Build an index describing the worktree, under ONE set of rules.
+ *
+ * Both the checkpoint and the "where are we now" tree go through here, and
+ * that is the whole point. When the two were built by separate code with
+ * slightly different filters, a file excluded from one and present in the
+ * other appeared in the diff as "created after the checkpoint" — and a rewind
+ * offered to delete a file that had been there all along.
+ *
+ * The second rule is subtler and cost a live data-loss bug: a path we do not
+ * cover must be **removed from the index**, not merely left at its HEAD
+ * version. `read-tree --reset -u` writes every index entry to disk, so a
+ * tracked `.env` sitting at its HEAD version silently overwrote the user's
+ * local edits — while the preview, built from a diff in which both sides were
+ * identical, said nothing would happen to it. An entry that does not exist
+ * cannot be written.
+ */
+async function buildIndex(store, worktreePath, indexFile) {
+    fs.mkdirSync(path.dirname(indexFile), { recursive: true, mode: 0o700 });
+    fs.rmSync(indexFile, { force: true });
+    const headSha = await gitIn(worktreePath, 'rev-parse', 'HEAD');
+    await gitStore(store, worktreePath, indexFile, 'read-tree', headSha);
+    const { paths, secrets } = await changedPaths(worktreePath);
+    const excluded = new Set(secrets);
+    const included = [];
+    let byteCount = 0;
+    for (const file of paths) {
+        let size = 0;
+        try {
+            const stat = fs.lstatSync(path.join(worktreePath, file));
+            size = stat.isFile() ? stat.size : 0;
+        }
+        catch {
+            // Deleted since `status` ran — `update-index --remove` handles it.
+        }
+        if (size > MAX_CHECKPOINT_FILE_BYTES) {
+            excluded.add(file);
+            continue;
+        }
+        byteCount += size;
+        included.push(file);
+    }
+    // Everything HEAD tracks that we may not touch — not just the paths that
+    // happen to have changed. An unmodified tracked secret would otherwise stay
+    // in the index and be rewritten from HEAD on every restore.
+    for (const tracked of splitZ(await gitStore(store, worktreePath, indexFile, 'ls-files', '-z'))) {
+        if (isSecretPath(path.join(worktreePath, tracked)))
+            excluded.add(tracked);
+    }
+    await runBatched(store, worktreePath, indexFile, ['update-index', '--add', '--remove'], included);
+    const drop = [...excluded];
+    if (drop.length > 0) {
+        await runBatched(store, worktreePath, indexFile, ['update-index', '--force-remove'], drop);
+    }
+    // `read-tree <commit>` writes index entries with ZEROED stat data, and
+    // `read-tree --reset -u` rewrites every entry whose stat does not match the
+    // file on disk — which, with zeroed stat, is all of them. Without this
+    // refresh a rewind of one file re-wrote the whole repository: mtime churn on
+    // every tracked path, i.e. a full rebuild for every watcher on the machine.
+    //
+    // Exit status is deliberately ignored: `--refresh` reports "needs update"
+    // for genuinely modified paths by failing, and those are exactly the paths a
+    // rewind is supposed to touch.
+    try {
+        await gitStore(store, worktreePath, indexFile, 'update-index', '-q', '--refresh');
+    }
+    catch {
+        // Some entries differ from the worktree — expected, and the point.
+    }
+    return {
+        headSha,
+        included,
+        excluded: drop,
+        byteCount,
+        tooLarge: included.length > MAX_CHECKPOINT_FILES || byteCount > MAX_CHECKPOINT_BYTES,
+    };
+}
+async function nextOrdinal(store, worktreePath, sessionId) {
+    const raw = await gitStore(store, worktreePath, indexFileFor(sessionId), 'for-each-ref', '--format=%(refname)', `refs/devbridge/checkpoints/${sessionId}/`);
+    let max = 0;
+    for (const line of raw.split('\n')) {
+        const n = Number.parseInt(line.slice(line.lastIndexOf('/') + 1), 10);
+        if (Number.isFinite(n) && n > max)
+            max = n;
+    }
+    return max + 1;
+}
+/**
+ * Metadata rides in the commit MESSAGE, not in a side file.
+ *
+ * One object, one fsync, one thing to garbage-collect — and a checkpoint whose
+ * ref survives can never be missing its own metadata.
+ */
+function encodeMeta(meta) {
+    return `devbridge-checkpoint\n\n${JSON.stringify(meta)}\n`;
+}
+function decodeMeta(message) {
+    const start = message.indexOf('{');
+    if (start < 0)
+        return null;
+    try {
+        const parsed = JSON.parse(message.slice(start));
+        const kind = parsed['kind'];
+        return {
+            kind: kind === 'SAFETY' || kind === 'MANUAL' ? kind : 'TURN',
+            headSha: typeof parsed['headSha'] === 'string' ? parsed['headSha'] : '',
+            stagedPaths: Array.isArray(parsed['stagedPaths'])
+                ? parsed['stagedPaths'].filter((p) => typeof p === 'string')
+                : [],
+            createdAt: typeof parsed['createdAt'] === 'number' ? parsed['createdAt'] : 0,
+            fileCount: typeof parsed['fileCount'] === 'number' ? parsed['fileCount'] : 0,
+            byteCount: typeof parsed['byteCount'] === 'number' ? parsed['byteCount'] : 0,
+            ...(typeof parsed['agentAnchor'] === 'string' ? { agentAnchor: parsed['agentAnchor'] } : {}),
+            ...(typeof parsed['agentSession'] === 'string'
+                ? { agentSession: parsed['agentSession'] }
+                : {}),
+            ...(typeof parsed['messageSeq'] === 'number' ? { messageSeq: parsed['messageSeq'] } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Take a restore point for this worktree.
+ *
+ * Never throws for an ordinary failure: a checkpoint that could not be taken
+ * must not stop the message it was taken for from reaching the agent.
+ */
+export async function createCheckpoint(input) {
+    const { worktreePath, sessionId, kind } = input;
+    try {
+        const store = await ensureStore(worktreePath);
+        const indexFile = tempIndexFile(sessionId, 'create');
+        const built = await buildIndex(store, worktreePath, indexFile);
+        if (built.tooLarge) {
+            fs.rmSync(indexFile, { force: true });
+            return { created: false, reason: 'too-large' };
+        }
+        const { headSha, included, excluded: skippedFiles, byteCount } = built;
+        const tree = await gitStore(store, worktreePath, indexFile, 'write-tree');
+        const stagedPaths = splitZ(await gitIn(worktreePath, 'diff', '--cached', '--name-only', '-z')).filter((file) => !isSecretPath(path.join(worktreePath, file)));
+        const meta = {
+            kind,
+            headSha,
+            stagedPaths,
+            createdAt: Date.now(),
+            fileCount: included.length,
+            byteCount,
+            ...(input.agentAnchor ? { agentAnchor: input.agentAnchor } : {}),
+            ...(input.agentSession ? { agentSession: input.agentSession } : {}),
+            ...(input.messageSeq === undefined ? {} : { messageSeq: input.messageSeq }),
+        };
+        const commit = await gitStore(store, worktreePath, indexFile, 'commit-tree', tree, '-m', encodeMeta(meta));
+        const ordinal = await nextOrdinal(store, worktreePath, sessionId);
+        await gitStore(store, worktreePath, indexFile, 'update-ref', refFor(sessionId, ordinal), commit);
+        fs.rmSync(indexFile, { force: true });
+        return {
+            created: true,
+            record: { ordinal, commit, ...meta },
+            ...(input.messageSeq === undefined ? {} : { messageSeq: input.messageSeq }),
+            skippedFiles,
+        };
+    }
+    catch (error) {
+        const detail = String(error instanceof Error ? error.message : error).slice(0, 300);
+        if (/not a git repository|ambiguous argument 'HEAD'|unknown revision/i.test(detail)) {
+            return { created: false, reason: 'not-a-repo', detail };
+        }
+        log.warn('checkpoints: could not create a restore point', { sessionId, error: detail });
+        return { created: false, reason: 'failed', detail };
+    }
+}
+async function readCheckpoint(store, worktreePath, sessionId, ordinal) {
+    try {
+        const commit = await gitStore(store, worktreePath, indexFileFor(sessionId), 'rev-parse', `${refFor(sessionId, ordinal)}^{commit}`);
+        const message = await gitStore(store, worktreePath, indexFileFor(sessionId), 'log', '-1', '--format=%B', commit);
+        const meta = decodeMeta(message);
+        if (!meta)
+            return null;
+        return { ordinal, commit, ...meta };
+    }
+    catch {
+        return null;
+    }
+}
+export async function listCheckpoints(worktreePath, sessionId) {
+    try {
+        const store = await ensureStore(worktreePath);
+        const raw = await gitStore(store, worktreePath, indexFileFor(sessionId), 'for-each-ref', '--format=%(refname)', `refs/devbridge/checkpoints/${sessionId}/`);
+        const out = [];
+        for (const line of raw.split('\n')) {
+            if (!line.trim())
+                continue;
+            const ordinal = Number.parseInt(line.slice(line.lastIndexOf('/') + 1), 10);
+            if (!Number.isFinite(ordinal))
+                continue;
+            const record = await readCheckpoint(store, worktreePath, sessionId, ordinal);
+            if (record)
+                out.push(record);
+        }
+        return out.sort((a, b) => a.ordinal - b.ordinal);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Where the worktree stands right now, under the SAME rules a checkpoint uses.
+ *
+ * Identical filters are not a tidiness point: a path covered by one side and
+ * not the other shows up in the diff as a creation or a deletion that never
+ * happened, and the rewind acts on it.
+ */
+async function currentTree(store, worktreePath, indexFile) {
+    const built = await buildIndex(store, worktreePath, indexFile);
+    return {
+        tree: await gitStore(store, worktreePath, indexFile, 'write-tree'),
+        headSha: built.headSha,
+    };
+}
+const MAX_PREVIEW_ENTRIES = 5_000;
+/** What a rewind to this checkpoint would do, without doing any of it. */
+export async function previewRewind(input) {
+    const { worktreePath, sessionId, ordinal } = input;
+    const store = await ensureStore(worktreePath);
+    const indexFile = tempIndexFile(sessionId, 'preview');
+    const record = await readCheckpoint(store, worktreePath, sessionId, ordinal);
+    const { tree, headSha } = await currentTree(store, worktreePath, indexFile);
+    if (!record) {
+        return {
+            restore: [],
+            delete: [],
+            recreate: [],
+            headSha,
+            checkpointHeadSha: '',
+            treeOid: tree,
+            blockedReason: 'checkpoint-lost',
+        };
+    }
+    const raw = await gitStore(store, worktreePath, indexFile, 'diff-tree', '-r', '--no-renames', '--name-status', '-z', `${record.commit}^{tree}`, tree);
+    fs.rmSync(indexFile, { force: true });
+    const restore = [];
+    const remove = [];
+    const recreate = [];
+    const fields = splitZ(raw);
+    for (let i = 0; i + 1 < fields.length; i += 2) {
+        const status = fields[i] ?? '';
+        const file = fields[i + 1] ?? '';
+        // Direction is checkpoint → now: `A` means the file appeared after the
+        // checkpoint (a rewind deletes it), `D` means it was there and is gone
+        // (a rewind brings it back), everything else is a content change.
+        if (status.startsWith('A'))
+            remove.push(file);
+        else if (status.startsWith('D'))
+            recreate.push(file);
+        else
+            restore.push(file);
+    }
+    // A list too long to SHOW is a rewind we must not run. Truncating it and
+    // going ahead anyway would delete files nobody was shown — the one thing the
+    // confirmation exists to prevent — so the size of the change is itself a
+    // reason to refuse.
+    const total = restore.length + remove.length + recreate.length;
+    let blockedReason = total > MAX_PREVIEW_ENTRIES ? 'too-many-changes' : undefined;
+    const commitsSince = [];
+    if (!blockedReason && record.headSha && record.headSha !== headSha) {
+        blockedReason = 'head-moved';
+        try {
+            const listed = await gitIn(worktreePath, 'log', '--format=%h%x00%s', '--max-count=20', `${record.headSha}..${headSha}`);
+            for (const line of listed.split('\n')) {
+                if (!line.trim())
+                    continue;
+                const [sha, subject] = line.split('\0');
+                commitsSince.push({ sha: sha ?? '', subject: (subject ?? '').slice(0, 200) });
+            }
+        }
+        catch {
+            // The old HEAD is unreachable (history was rewritten) — the refusal
+            // stands on its own; the list is a courtesy.
+        }
+    }
+    if (!blockedReason && (await mergeInProgress(worktreePath))) {
+        blockedReason = 'merge-in-progress';
+    }
+    return {
+        restore: restore.slice(0, MAX_PREVIEW_ENTRIES),
+        delete: remove.slice(0, MAX_PREVIEW_ENTRIES),
+        recreate: recreate.slice(0, MAX_PREVIEW_ENTRIES),
+        headSha,
+        checkpointHeadSha: record.headSha,
+        treeOid: tree,
+        ...(blockedReason ? { blockedReason } : {}),
+        ...(commitsSince.length ? { commitsSince } : {}),
+        ...(total > MAX_PREVIEW_ENTRIES ? { truncated: true, totalChanges: total } : {}),
+    };
+}
+async function mergeInProgress(worktreePath) {
+    try {
+        const gitDir = await gitIn(worktreePath, 'rev-parse', '--path-format=absolute', '--git-dir');
+        return (fs.existsSync(path.join(gitDir, 'MERGE_HEAD')) ||
+            fs.existsSync(path.join(gitDir, 'REBASE_HEAD')) ||
+            fs.existsSync(path.join(gitDir, 'CHERRY_PICK_HEAD')));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Put the working tree back to a checkpoint.
+ *
+ * The SAFETY point is taken FIRST and its ref is on disk before a single byte
+ * of the worktree changes — kill the process between the two steps and the way
+ * back still exists. `read-tree --reset -u` restores content but does NOT
+ * delete files created after the checkpoint (verified on live git), so the
+ * deletions are done explicitly from a list the caller echoed back. There is no
+ * `git clean` anywhere in this file, on purpose: it deletes by rule rather than
+ * by list, and a rule is exactly what nobody confirmed.
+ */
+export async function applyRewind(input) {
+    const { worktreePath, sessionId, ordinal, confirmDeletes, expectedTreeOid } = input;
+    const store = await ensureStore(worktreePath);
+    const record = await readCheckpoint(store, worktreePath, sessionId, ordinal);
+    if (!record)
+        throw new Error('This restore point is no longer available');
+    const preview = await previewRewind({ worktreePath, sessionId, ordinal });
+    if (preview.blockedReason) {
+        throw new Error(rewindBlockMessage(preview.blockedReason));
+    }
+    const MOVED = 'The working tree changed while you were looking at it — open the preview again';
+    // The whole state, not just the deletions (QA-120 B1). `read-tree --reset -u`
+    // writes the RESTORE list as well, and that list is recomputed HERE — so a
+    // file saved from an editor while the dialog sat open used to be overwritten
+    // from the checkpoint without appearing on any list the person read.
+    if (expectedTreeOid && expectedTreeOid !== preview.treeOid)
+        throw new Error(MOVED);
+    const expected = [...preview.delete].sort();
+    const echoed = [...confirmDeletes].sort();
+    if (expected.length !== echoed.length || expected.some((p, i) => p !== echoed[i])) {
+        throw new Error(MOVED);
+    }
+    const safetyResult = await createCheckpoint({ worktreePath, sessionId, kind: 'SAFETY' });
+    if (!safetyResult.created) {
+        throw new Error(safetyResult.reason === 'too-large'
+            ? 'The working tree is too large to take a safety point — the rewind was not started'
+            : 'Could not take a safety point before the rewind — nothing was changed');
+    }
+    const indexFile = tempIndexFile(sessionId, 'rewind');
+    // Seed the index with the CURRENT state so `read-tree --reset -u` only
+    // touches files that actually differ. Against an empty index git rewrites
+    // every file in the repository, and an mtime bump on a whole tree is a full
+    // rebuild for every watcher on the machine.
+    await currentTree(store, worktreePath, indexFile);
+    await gitStore(store, worktreePath, indexFile, 'read-tree', '--reset', '-u', `${record.commit}^{tree}`);
+    fs.rmSync(indexFile, { force: true });
+    // `read-tree --reset -u` removes the files that are in the seeded index and
+    // not in the checkpoint — which is the same set the user just confirmed,
+    // because both come from the same tree diff. This pass is the belt to that
+    // brace: it names each path explicitly, re-checks it against the worktree
+    // root, and reports what is actually gone. Nothing here deletes by rule, and
+    // there is no `git clean` anywhere in this file.
+    await deletePaths(worktreePath, preview.delete);
+    const deleted = preview.delete.filter((rel) => !fs.existsSync(path.join(worktreePath, rel))).length;
+    await reconcileIndex(worktreePath, preview, record.stagedPaths);
+    return {
+        restored: preview.restore.length,
+        deleted,
+        recreated: preview.recreate.length,
+        safety: safetyResult.record,
+        rewoundToKind: record.kind,
+    };
+}
+export function rewindBlockMessage(reason) {
+    switch (reason) {
+        case 'head-moved':
+            return 'A commit was made after this restore point — rewind the commit from the Changes panel first';
+        case 'merge-in-progress':
+            return 'This worktree is in the middle of a merge — finish or abort it first';
+        case 'checkpoint-lost':
+            return 'This restore point is no longer available';
+        case 'too-many-changes':
+            return `More than ${MAX_PREVIEW_ENTRIES} files differ from this restore point — too many to list, and a rewind must never delete a file nobody was shown`;
+    }
+}
+/**
+ * Delete exactly the paths the user confirmed.
+ *
+ * Every one is re-checked against the worktree root here as well as in the API:
+ * this function is the last thing standing between a list and `unlink`, and a
+ * symlink that leaves the tree must not be followed out of it.
+ */
+async function deletePaths(worktreePath, paths) {
+    const root = await realpath(worktreePath);
+    let deleted = 0;
+    for (const rel of paths) {
+        if (path.isAbsolute(rel) || rel.split(/[\\/]/).includes('..'))
+            continue;
+        const target = path.resolve(worktreePath, rel);
+        const relative = path.relative(worktreePath, target);
+        if (!relative || relative.startsWith('..') || path.isAbsolute(relative))
+            continue;
+        if (relative.split(path.sep).includes('.git'))
+            continue;
+        // The PARENT is resolved, not the target: resolving the target would follow
+        // the very symlink we are deciding about.
+        let parentReal;
+        try {
+            parentReal = await fs.promises.realpath(path.dirname(target));
+        }
+        catch {
+            continue;
+        }
+        const parentRel = path.relative(root, parentReal);
+        if (parentRel.startsWith('..') || path.isAbsolute(parentRel))
+            continue;
+        try {
+            const stat = await fs.promises.lstat(target);
+            // Directories are never in the list — git names files — and a directory
+            // here would mean the list is not what we think it is.
+            if (stat.isDirectory())
+                continue;
+            await fs.promises.unlink(target);
+            deleted += 1;
+        }
+        catch {
+            // Already gone: the outcome the caller asked for.
+        }
+    }
+    return deleted;
+}
+/**
+ * Put the project's own index back the way it was at the checkpoint, for the
+ * paths this rewind touched — and only those.
+ *
+ * The rewind itself never touches the project index (it runs against an index
+ * of the runner's), so without this a file that was staged-as-added and is now
+ * deleted from disk would show up as `AD` forever. Paths outside the rewind are
+ * left strictly alone: the user's other staged work is none of our business.
+ */
+async function reconcileIndex(worktreePath, preview, stagedAtCheckpoint) {
+    const touched = [...new Set([...preview.restore, ...preview.delete, ...preview.recreate])];
+    if (touched.length === 0)
+        return;
+    const staged = new Set(stagedAtCheckpoint);
+    try {
+        for (let i = 0; i < touched.length; i += PATH_BATCH) {
+            await gitIn(worktreePath, 'reset', '--quiet', '--', ...touched.slice(i, i + PATH_BATCH));
+        }
+        const restage = touched.filter((file) => staged.has(file) && !preview.delete.includes(file));
+        for (let i = 0; i < restage.length; i += PATH_BATCH) {
+            await gitIn(worktreePath, 'add', '--', ...restage.slice(i, i + PATH_BATCH));
+        }
+    }
+    catch (error) {
+        // The files are already back; a staging area we could not reproduce is a
+        // cosmetic loss, not a reason to report the rewind as failed.
+        log.warn('checkpoints: could not restore the staging area', { error: String(error) });
+    }
+}
+/** Drop every restore point of one session (session deleted or purged). */
+export async function dropCheckpoints(worktreePath, sessionId) {
+    try {
+        const store = await ensureStore(worktreePath);
+        await deleteRefs(store, worktreePath, sessionId);
+        fs.rmSync(indexFileFor(sessionId), { force: true });
+    }
+    catch (error) {
+        log.warn('checkpoints: could not drop restore points', { sessionId, error: String(error) });
+    }
+}
+async function deleteRefs(store, worktreePath, sessionId) {
+    const raw = await gitStore(store, worktreePath, indexFileFor(sessionId), 'for-each-ref', '--format=%(refname)', `refs/devbridge/checkpoints/${sessionId}/`);
+    for (const ref of raw.split('\n')) {
+        if (!ref.trim())
+            continue;
+        await gitStore(store, worktreePath, indexFileFor(sessionId), 'update-ref', '-d', ref);
+    }
+}
+/**
+ * Garbage collection.
+ *
+ * Two jobs, and the second one is the reason this exists: deleting a session
+ * while its dev server is switched off leaves refs — a full copy of a working
+ * tree — with no row anywhere to point at them. The reconciliation on `hello`
+ * is what eventually removes those, so this takes a list of the sessions that
+ * still exist rather than a list of the ones that do not.
+ */
+export async function pruneCheckpoints(input) {
+    const { liveSessionIds } = input;
+    const now = input.now ?? Date.now();
+    const droppedSessions = [];
+    let droppedRefs = 0;
+    const root = checkpointsDir();
+    if (!fs.existsSync(root))
+        return { droppedSessions, droppedRefs };
+    // Every store, not just the one belonging to some worktree we happen to hold
+    // a path for. A session deleted while its dev server was switched off leaves
+    // refs behind with no row anywhere pointing at them, and the repository it
+    // came from may have no live session left to find it through.
+    for (const entry of fs.readdirSync(root)) {
+        if (!entry.endsWith('.git'))
+            continue;
+        const store = path.join(root, entry);
+        try {
+            const raw = await gitRefs(store, 'for-each-ref', '--format=%(refname)', REF_PREFIX);
+            const bySession = new Map();
+            for (const ref of raw.split('\n')) {
+                if (!ref.trim())
+                    continue;
+                const rest = ref.slice(REF_PREFIX.length);
+                const slash = rest.lastIndexOf('/');
+                if (slash <= 0)
+                    continue;
+                const sessionId = rest.slice(0, slash);
+                const ordinal = Number.parseInt(rest.slice(slash + 1), 10);
+                if (!Number.isFinite(ordinal))
+                    continue;
+                const list = bySession.get(sessionId) ?? [];
+                list.push(ordinal);
+                bySession.set(sessionId, list);
+            }
+            let droppedHere = 0;
+            for (const [sessionId, ordinals] of bySession) {
+                // "Not in the list" is NOT the same as "does not exist". The list the
+                // API sends on `hello` is capped — REVIEW sessions are trimmed to the
+                // ten most recent — so treating every absent id as an orphan would
+                // delete the restore points of a session that is merely quiet. Age is
+                // what makes the difference safe: a session deleted while its server
+                // was off stops being mentioned forever, so its points age out; a live
+                // one that fell off a truncated list is mentioned again within minutes.
+                const unlisted = !liveSessionIds.has(sessionId);
+                ordinals.sort((a, b) => b - a);
+                const keep = new Set(ordinals.slice(0, CHECKPOINT_MAX_PER_SESSION));
+                let survivors = 0;
+                for (const ordinal of ordinals) {
+                    let drop = !keep.has(ordinal);
+                    if (!drop) {
+                        const record = await readRecord(store, sessionId, ordinal);
+                        const age = record ? now - record.createdAt : Number.POSITIVE_INFINITY;
+                        drop = !record || age > CHECKPOINT_MAX_AGE_MS || (unlisted && age > ORPHAN_GRACE_MS);
+                    }
+                    if (!drop) {
+                        survivors += 1;
+                        continue;
+                    }
+                    await gitRefs(store, 'update-ref', '-d', refFor(sessionId, ordinal));
+                    droppedHere += 1;
+                }
+                if (survivors === 0) {
+                    droppedSessions.push(sessionId);
+                    fs.rmSync(indexFileFor(sessionId), { force: true });
+                }
+            }
+            droppedRefs += droppedHere;
+            if (droppedHere > 0) {
+                // Dropping a ref only unlinks it; the trees and blobs it named stay on
+                // disk until they are collected. Skipping this would make "retention"
+                // mean nothing at all for the thing that actually takes the space.
+                await gitRefs(store, 'reflog', 'expire', '--expire=now', '--all');
+                await gitRefs(store, 'gc', '--prune=now', '--quiet');
+            }
+        }
+        catch (error) {
+            log.warn('checkpoints: prune failed for a store', { store: entry, error: String(error) });
+        }
+    }
+    return { droppedSessions, droppedRefs };
+}
+//# sourceMappingURL=checkpoints.js.map