@pellux/goodvibes-sdk 0.36.0 → 0.37.1

package/dist/platform/workspace/checkpoint/manager.js

@@ -0,0 +1,543 @@
+/**
+ * manager.ts
+ *
+ * WorkspaceCheckpointManager — the coarse, whole-workspace rewind layer.
+ *
+ * Complements (does not replace) FileUndoManager (../../state/file-undo.ts),
+ * which stays as the fine-grained, in-memory, per-file /undo layer. This
+ * manager persists across sessions, snapshots the ENTIRE workspace tree, and
+ * survives process restarts (backed by git objects + a JSON manifest on
+ * disk), which is the wrong shape for FileUndoManager but exactly the shape
+ * needed for "revert everything turn N did" or "restore the workspace to how
+ * it looked an hour ago".
+ *
+ * Storage layout (workspace-local, see side-git.ts for the git mechanics):
+ *   <workspaceRoot>/.goodvibes/checkpoints/git         — side GIT_DIR
+ *   <workspaceRoot>/.goodvibes/checkpoints/index.json  — manifest (JsonFileStore)
+ *
+ * Checkpoint refs live at refs/goodvibes/checkpoints/<id> inside the side
+ * repo, entirely separate from the user's real git refs and from compaction's
+ * `cpt_` boundary commits (which are conversation snapshots, not filesystem
+ * snapshots, and are not stored in git at all — see types.ts's header comment
+ * for the full disambiguation).
+ *
+ * Automatic snapshots subscribe to EXISTING runtime bus events
+ * (TURN_COMPLETED / TURN_ERROR / TURN_CANCEL / AGENT_COMPLETED) — no new
+ * event contract is introduced by this module.
+ */
+import { randomUUID } from 'node:crypto';
+import { existsSync, rmSync } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { logger } from '../../utils/logger.js';
+import { summarizeError } from '../../utils/error-display.js';
+import { JsonFileStore } from '../../state/json-file-store.js';
+import { RetentionPolicy, } from '../../runtime/retention/index.js';
+import { SideGitRunner, CHECKPOINT_REF_PREFIX, EMPTY_TREE_HASH } from './side-git.js';
+const ID_PREFIX = 'wcp';
+function generateCheckpointId(now) {
+    const ts = now().toString(36);
+    const rand = randomUUID().slice(0, 8);
+    return `${ID_PREFIX}_${ts}_${rand}`;
+}
+/** Default retention class per checkpoint kind when the caller does not specify one. */
+function defaultRetentionClassFor(kind) {
+    return kind === 'manual' ? 'forensic' : 'standard';
+}
+/**
+ * `Pruner` implementation for `RetentionPolicy` that deletes checkpoint REFS
+ * (not filesystem paths — that is what `SnapshotPruner`, the compaction-side
+ * pruner, does, and reusing it here would be a no-op at best since our
+ * "artifacts" are refs+objects, not files). Actual object reclamation is a
+ * single `git gc --prune=now` run once by `WorkspaceCheckpointManager.gc()`
+ * after refs are deleted, not per-record here.
+ */
+class WorkspaceCheckpointPruner {
+    sideGit;
+    onDeleted;
+    constructor(sideGit, onDeleted) {
+        this.sideGit = sideGit;
+        this.onDeleted = onDeleted;
+    }
+    async delete(candidates, options) {
+        const dryRun = options?.dryRun ?? false;
+        const deletedIds = [];
+        const failedIds = [];
+        const errors = {};
+        let reclaimedBytes = 0;
+        const byClass = {
+            short: { deletedCount: 0, reclaimedBytes: 0, deletedIds: [], candidateIds: [], failedIds: [] },
+            standard: { deletedCount: 0, reclaimedBytes: 0, deletedIds: [], candidateIds: [], failedIds: [] },
+            forensic: { deletedCount: 0, reclaimedBytes: 0, deletedIds: [], candidateIds: [], failedIds: [] },
+        };
+        for (const record of candidates) {
+            byClass[record.retentionClass].candidateIds.push(record.id);
+        }
+        if (dryRun) {
+            return {
+                deletedCount: 0,
+                reclaimedBytes: 0,
+                deletedIds: [],
+                candidateIds: candidates.map((c) => c.id),
+                failedIds: [],
+                errors: {},
+                dryRun: true,
+                byClass,
+            };
+        }
+        for (const record of candidates) {
+            try {
+                await this.sideGit.deleteRef(`${CHECKPOINT_REF_PREFIX}${record.id}`);
+                deletedIds.push(record.id);
+                reclaimedBytes += record.sizeBytes;
+                byClass[record.retentionClass].deletedCount += 1;
+                byClass[record.retentionClass].reclaimedBytes += record.sizeBytes;
+                byClass[record.retentionClass].deletedIds.push(record.id);
+                this.onDeleted(record.id);
+            }
+            catch (err) {
+                failedIds.push(record.id);
+                errors[record.id] = summarizeError(err);
+                byClass[record.retentionClass].failedIds.push(record.id);
+            }
+        }
+        return {
+            deletedCount: deletedIds.length,
+            reclaimedBytes,
+            deletedIds,
+            candidateIds: [],
+            failedIds,
+            errors,
+            dryRun: false,
+            byClass,
+        };
+    }
+}
+/**
+ * WorkspaceCheckpointManager — create/list/diff/restore/gc for whole-workspace
+ * git-backed snapshots, plus automatic snapshotting on existing turn/agent
+ * lifecycle events.
+ */
+export class WorkspaceCheckpointManager {
+    workspaceRoot;
+    checkpointRootDir;
+    sideGit;
+    manifestStore;
+    retentionPolicy;
+    now;
+    runtimeBus;
+    unsubscribers = [];
+    checkpoints = new Map();
+    initialized = false;
+    initPromise = null;
+    /**
+     * Promise-chain mutex serializing every public operation that touches the
+     * side repo's shared index or shared object store: `create`, `restore`,
+     * `gc`, and `diff` (see each method's `*Internal` body below). Without
+     * this, an auto-snapshot `create()` firing on a bus event (TURN_COMPLETED,
+     * TURN_ERROR, TURN_CANCEL, or AGENT_COMPLETED) could run its `git add -A`
+     * in between `restore()`'s
+     * `read-tree --reset` and `checkout-index -a -f`, silently corrupting the
+     * restore; two concurrent `create()` calls share the same hazard on the
+     * index, and a same-tick `gc()` could treat a not-yet-ref'd loose commit
+     * from an in-flight `create()` as unreachable and prune it out from under
+     * it. `diff()` is included too: the single-argument `git diff <tree-ish>`
+     * form (diffing a checkpoint against the live working tree) refreshes the
+     * index's stat cache as a side effect, which is itself a write.
+     *
+     * Each public method below only does `await this.init()` (idempotent, safe
+     * to race) before calling `withLock`; the actual git-touching work lives in
+     * a same-named `*Internal` method. Internal callers that need another
+     * locked operation's behavior (e.g. `restore()`'s safety checkpoint) call
+     * the `*Internal` method directly — never the public wrapper — so a single
+     * logical operation never tries to re-enter its own lock.
+     */
+    lockChain = Promise.resolve();
+    withLock(fn) {
+        // `lockChain` is constructed below so it never itself rejects (its
+        // continuation always swallows both outcomes) — chaining with a single
+        // `.then(fn)` is enough to guarantee `fn` only starts after every
+        // previously-queued operation has settled, regardless of whether that
+        // prior operation resolved or rejected.
+        const result = this.lockChain.then(fn);
+        this.lockChain = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    constructor(opts) {
+        this.workspaceRoot = opts.workspaceRoot;
+        this.checkpointRootDir = opts.checkpointDir ?? join(opts.workspaceRoot, '.goodvibes', 'checkpoints');
+        this.sideGit = new SideGitRunner({
+            workspaceRoot: opts.workspaceRoot,
+            gitDir: join(this.checkpointRootDir, 'git'),
+        });
+        this.manifestStore = new JsonFileStore(join(this.checkpointRootDir, 'index.json'));
+        this.now = opts.now ?? Date.now;
+        this.runtimeBus = opts.runtimeBus;
+        this.retentionPolicy = new RetentionPolicy(opts.retention, this.now, new WorkspaceCheckpointPruner(this.sideGit, (id) => this.checkpoints.delete(id)));
+    }
+    /**
+     * Idempotent setup: init the side repo, load the manifest (re-hydrating the
+     * in-memory RetentionPolicy so retention state survives process restarts),
+     * and subscribe to automatic-snapshot events if a runtime bus was provided.
+     * Safe to call multiple times; concurrent callers share one in-flight init.
+     */
+    async init() {
+        if (this.initialized)
+            return;
+        if (!this.initPromise) {
+            this.initPromise = this._init();
+        }
+        await this.initPromise;
+    }
+    async _init() {
+        await this.sideGit.init();
+        const manifest = await this.manifestStore.load();
+        this.checkpoints = new Map((manifest?.checkpoints ?? []).map((c) => [c.id, c]));
+        for (const checkpoint of this.checkpoints.values()) {
+            this.retentionPolicy.register({
+                id: checkpoint.id,
+                createdAt: checkpoint.createdAt,
+                sizeBytes: checkpoint.sizeBytes,
+                retentionClass: checkpoint.retentionClass,
+                path: this.sideGit.gitDir,
+            });
+        }
+        if (this.runtimeBus) {
+            this.subscribeToAutomaticSnapshots(this.runtimeBus);
+        }
+        this.initialized = true;
+    }
+    // ---------------------------------------------------------------------------
+    // Automatic snapshots
+    // ---------------------------------------------------------------------------
+    /**
+     * Subscribes to the EXISTING turn/agent lifecycle events — no new event
+     * types are introduced. A snapshot is taken at the boundary AFTER each
+     * turn/agent-run finishes, meaning "revert everything turn N did" means
+     * restoring the checkpoint captured BEFORE turn N, i.e. checkpoint[N-1] in
+     * `list()`'s (newest-first) ordering — an intentional off-by-one, documented
+     * here rather than hidden: this module always snapshots "where things ended
+     * up", never "where things started".
+     *
+     * Listener bodies are wrapped so a failure NEVER throws back into the bus:
+     * `RuntimeEventBus.emit()` only catches synchronous throws from a listener,
+     * not rejections from a returned (but un-awaited) promise, so every
+     * auto-snapshot call here is deliberately `.catch()`-guarded.
+     */
+    subscribeToAutomaticSnapshots(bus) {
+        const snapshotTurn = (turnId, reason) => {
+            this.create({ kind: 'turn', turnId, retentionClass: 'standard', label: `turn ${reason}` }).catch((err) => {
+                logger.warn('WorkspaceCheckpointManager: automatic turn snapshot failed', {
+                    turnId,
+                    reason,
+                    error: summarizeError(err),
+                });
+            });
+        };
+        const snapshotAgentRun = (agentId) => {
+            this.create({ kind: 'agent-run', agentId, retentionClass: 'standard', label: 'agent run' }).catch((err) => {
+                logger.warn('WorkspaceCheckpointManager: automatic agent-run snapshot failed', {
+                    agentId,
+                    error: summarizeError(err),
+                });
+            });
+        };
+        this.unsubscribers.push(bus.on('TURN_COMPLETED', ({ payload }) => {
+            snapshotTurn(payload.turnId, 'completed');
+        }), bus.on('TURN_ERROR', ({ payload }) => {
+            snapshotTurn(payload.turnId, 'error');
+        }), bus.on('TURN_CANCEL', ({ payload }) => {
+            snapshotTurn(payload.turnId, 'cancelled');
+        }), bus.on('AGENT_COMPLETED', ({ payload }) => {
+            snapshotAgentRun(payload.agentId);
+        }));
+    }
+    // ---------------------------------------------------------------------------
+    // Public API
+    // ---------------------------------------------------------------------------
+    /**
+     * Create a new checkpoint. Returns `null` (a cheap no-op) when the current
+     * workspace tree is identical to the parent checkpoint's tree — no commit,
+     * no ref, no manifest entry is created in that case.
+     *
+     * Serialized against every other index-touching operation on this manager
+     * — see `withLock`.
+     */
+    async create(opts) {
+        await this.init();
+        return this.withLock(() => this.createInternal(opts));
+    }
+    async createInternal(opts) {
+        await this.sideGit.stageAll(opts.paths);
+        const treeHash = await this.sideGit.writeTree();
+        const parent = this.mostRecentCheckpoint();
+        const parentTree = parent ? await this.sideGit.treeOf(parent.commit) : EMPTY_TREE_HASH;
+        if (parentTree === treeHash) {
+            logger.debug('WorkspaceCheckpointManager.create: tree unchanged since parent, no-op', {
+                kind: opts.kind,
+                parentId: parent?.id ?? null,
+            });
+            return null;
+        }
+        const id = generateCheckpointId(this.now);
+        const kind = opts.kind;
+        const retentionClass = opts.retentionClass ?? defaultRetentionClassFor(kind);
+        const label = opts.label ?? this.defaultLabel(kind, id);
+        const message = `wcp: ${kind} ${label}`.trim();
+        const commit = await this.sideGit.commitTree(treeHash, message);
+        await this.sideGit.updateRef(`${CHECKPOINT_REF_PREFIX}${id}`, commit);
+        const changedPaths = parent
+            ? await this.sideGit.diffNameOnly(parent.commit, commit)
+            : await this.sideGit.listTrackedFiles(commit);
+        const sizeBytes = await this.computeSizeBytes(changedPaths);
+        const checkpoint = {
+            id,
+            kind,
+            label,
+            createdAt: this.now(),
+            parentId: parent?.id ?? null,
+            turnId: opts.turnId,
+            agentId: opts.agentId,
+            retentionClass,
+            commit,
+            sizeBytes,
+        };
+        this.checkpoints.set(id, checkpoint);
+        this.retentionPolicy.register({
+            id,
+            createdAt: checkpoint.createdAt,
+            sizeBytes,
+            retentionClass,
+            path: this.sideGit.gitDir,
+        });
+        await this.persistManifest();
+        logger.debug('WorkspaceCheckpointManager.create: checkpoint created', { id, kind, parentId: checkpoint.parentId });
+        return checkpoint;
+    }
+    /** List checkpoints, newest-first. `list()[0]` is always the most recent checkpoint. */
+    async list(filter) {
+        await this.init();
+        let results = Array.from(this.checkpoints.values()).sort((a, b) => b.createdAt - a.createdAt);
+        if (filter?.kind)
+            results = results.filter((c) => c.kind === filter.kind);
+        if (filter?.since != null)
+            results = results.filter((c) => c.createdAt >= filter.since);
+        if (filter?.limit != null)
+            results = results.slice(0, filter.limit);
+        return results;
+    }
+    /**
+     * Diff two checkpoints, or a checkpoint against the live working tree when
+     * `b` is omitted.
+     *
+     * Serialized against every other index-touching operation on this manager
+     * — see `withLock`. The single-argument form (`b` omitted, diffing against
+     * the live working tree) refreshes the side index's stat cache as a side
+     * effect, so it is not purely read-only.
+     */
+    async diff(a, b) {
+        await this.init();
+        return this.withLock(() => this.diffInternal(a, b));
+    }
+    async diffInternal(a, b) {
+        const fromCheckpoint = this.requireCheckpoint(a);
+        const toCheckpoint = b ? this.requireCheckpoint(b) : undefined;
+        const [unifiedDiff, stat_, files] = await Promise.all([
+            this.sideGit.diff(fromCheckpoint.commit, toCheckpoint?.commit),
+            this.sideGit.diffStat(fromCheckpoint.commit, toCheckpoint?.commit),
+            this.sideGit.diffNameOnly(fromCheckpoint.commit, toCheckpoint?.commit),
+        ]);
+        return {
+            from: a,
+            to: b ?? 'WORKING',
+            files,
+            unifiedDiff,
+            stat: stat_,
+        };
+    }
+    /**
+     * Restore the workspace to the state captured by checkpoint `id`.
+     *
+     * By default (`safetyCheckpoint: true`) takes a checkpoint of the CURRENT
+     * state first, so a restore is itself undoable via another restore.
+     *
+     * Whole-workspace restore (no `opts.paths`):
+     *   1. Snapshot the current tracked-file set (via the safety checkpoint, or
+     *      a transient write-tree when `safetyCheckpoint: false`) — this is the
+     *      "before" set.
+     *   2. Reset the side index to the target checkpoint's tree and check every
+     *      file in it out to disk (re-creates anything the checkpoint had that
+     *      is currently missing or modified).
+     *   3. Remove exactly the files that were in the "before" set but are NOT
+     *      in the target checkpoint's tree (files created/tracked after the
+     *      checkpoint). Anything NOT in the "before" set — i.e. any untracked
+     *      path outside what this engine has ever snapshotted — is never
+     *      touched, by construction: it never appears in either set.
+     *
+     * Scoped restore (`opts.paths` provided) only checks out those paths from
+     * the target tree; it never removes files outside the given paths.
+     *
+     * Serialized against every other index-touching operation on this manager
+     * — see `withLock`. Without this, an auto-snapshot `create()` firing on a
+     * bus event could run its `git add -A` in between the `read-tree --reset`
+     * and `checkout-index -a -f` calls below, silently corrupting the restore.
+     */
+    async restore(id, opts) {
+        await this.init();
+        return this.withLock(() => this.restoreInternal(id, opts));
+    }
+    async restoreInternal(id, opts) {
+        const target = this.requireCheckpoint(id);
+        const wantSafety = opts?.safetyCheckpoint ?? true;
+        let beforeFiles;
+        let safetyCheckpointId = null;
+        if (wantSafety) {
+            // Calls createInternal directly (not the public, lock-acquiring
+            // `create()`) — this whole method already holds the lock.
+            const safety = await this.createInternal({ kind: 'manual', label: `pre-restore safety (before ${id})`, retentionClass: 'forensic' });
+            safetyCheckpointId = safety?.id ?? null;
+            const current = safety ?? this.mostRecentCheckpoint();
+            beforeFiles = current ? await this.sideGit.listTrackedFiles(current.commit) : [];
+        }
+        else {
+            await this.sideGit.stageAll();
+            const transientTree = await this.sideGit.writeTree();
+            beforeFiles = await this.sideGit.listTrackedFiles(transientTree);
+        }
+        if (opts?.paths && opts.paths.length > 0) {
+            const restoredFiles = [];
+            for (const path of opts.paths) {
+                try {
+                    await this.sideGit.raw(['checkout', target.commit, '--', path]);
+                    restoredFiles.push(path);
+                }
+                catch (err) {
+                    logger.warn('WorkspaceCheckpointManager.restore: scoped path checkout failed', {
+                        id,
+                        path,
+                        error: summarizeError(err),
+                    });
+                }
+            }
+            return { checkpointId: id, safetyCheckpointId, restoredFiles, removedFiles: [] };
+        }
+        const targetFiles = await this.sideGit.listTrackedFiles(target.commit);
+        const targetFileSet = new Set(targetFiles);
+        const removedFiles = beforeFiles.filter((path) => !targetFileSet.has(path));
+        await this.sideGit.readTreeReset(target.commit);
+        await this.sideGit.checkoutIndexAll();
+        for (const path of removedFiles) {
+            try {
+                rmSync(join(this.workspaceRoot, path), { force: true });
+            }
+            catch (err) {
+                logger.warn('WorkspaceCheckpointManager.restore: failed to remove file added after checkpoint', {
+                    id,
+                    path,
+                    error: summarizeError(err),
+                });
+            }
+        }
+        logger.debug('WorkspaceCheckpointManager.restore: restored', {
+            id,
+            safetyCheckpointId,
+            restoredCount: targetFiles.length,
+            removedCount: removedFiles.length,
+        });
+        return { checkpointId: id, safetyCheckpointId, restoredFiles: targetFiles, removedFiles };
+    }
+    /**
+     * Apply retention limits: `RetentionPolicy` selects prune candidates,
+     * `WorkspaceCheckpointPruner` deletes their refs, then (only if anything
+     * was actually deleted) a single `git gc --prune=now` reclaims the now-
+     * unreachable objects. This never touches compaction's boundary commits —
+     * they are tracked in an entirely separate `RetentionPolicy` instance
+     * (../../runtime/compaction) with no shared state.
+     *
+     * Reclamation only works because checkpoint commits are parentless (see
+     * `SideGitRunner.commitTree`): a pruned ref's commit has no descendant
+     * keeping it reachable via a git parent pointer, so once its ref is
+     * deleted it is genuinely unreachable and `--prune=now` frees it.
+     *
+     * Serialized against every other index/object-store-touching operation on
+     * this manager — see `withLock`. Without this, a `create()` racing this
+     * method could write a loose commit object that isn't ref'd yet at the
+     * moment `--prune=now` runs, and lose it.
+     */
+    async gc() {
+        await this.init();
+        return this.withLock(() => this.gcInternal());
+    }
+    async gcInternal() {
+        const result = await this.retentionPolicy.prune();
+        if (result.deletedCount > 0) {
+            await this.persistManifest();
+            await this.sideGit.gc();
+        }
+        return result;
+    }
+    /** Unsubscribe from the runtime bus. Does not touch anything on disk. */
+    dispose() {
+        for (const unsub of this.unsubscribers) {
+            try {
+                unsub();
+            }
+            catch {
+                // best-effort
+            }
+        }
+        this.unsubscribers.length = 0;
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    mostRecentCheckpoint() {
+        let latest = null;
+        for (const checkpoint of this.checkpoints.values()) {
+            if (!latest || checkpoint.createdAt > latest.createdAt) {
+                latest = checkpoint;
+            }
+        }
+        return latest;
+    }
+    requireCheckpoint(id) {
+        const checkpoint = this.checkpoints.get(id);
+        if (!checkpoint) {
+            throw new Error(`WorkspaceCheckpointManager: no checkpoint found with id "${id}"`);
+        }
+        return checkpoint;
+    }
+    defaultLabel(kind, id) {
+        if (kind === 'manual')
+            return id;
+        return `${kind} snapshot`;
+    }
+    /**
+     * Approximate incremental bytes introduced by a checkpoint: sum of on-disk
+     * sizes of the changed paths, read immediately after they were staged and
+     * committed (so they still reflect exactly the content just captured).
+     * Deleted paths (no longer on disk) contribute 0. This is deliberately not
+     * exact git object-store accounting — it exists for retention's `maxSizeBytes`
+     * bookkeeping, not for a byte-perfect audit.
+     */
+    async computeSizeBytes(paths) {
+        let total = 0;
+        for (const path of paths) {
+            const absolute = join(this.workspaceRoot, path);
+            if (!existsSync(absolute))
+                continue;
+            try {
+                const info = await stat(absolute);
+                if (info.isFile())
+                    total += info.size;
+            }
+            catch {
+                // Ignore races (file removed between listing and stat).
+            }
+        }
+        return total;
+    }
+    async persistManifest() {
+        await this.manifestStore.save({ checkpoints: Array.from(this.checkpoints.values()) });
+    }
+}

package/dist/platform/workspace/checkpoint/side-git.d.ts

@@ -0,0 +1,130 @@
+/**
+ * side-git.ts
+ *
+ * SideGitRunner — a hidden git repository ("side repo") whose object store
+ * (GIT_DIR) lives under <workspaceRoot>/.goodvibes/checkpoints/git while its
+ * GIT_WORK_TREE is the live workspace itself.
+ *
+ * This is the dotfiles-bare-repo trick (`git --git-dir=X --work-tree=Y`):
+ * git tracks arbitrary files in Y using an object store rooted at X,
+ * completely independent of whatever real .git directory Y may or may not
+ * already have. It gives us, for free:
+ *   - content-addressed, deduped storage (unchanged files cost ~nothing)
+ *   - `git diff` / `git diff --stat` between any two snapshots
+ *   - whole-tree restore via `read-tree` + `checkout-index`
+ *   - correct behavior in a workspace that is NOT itself a git repo
+ *
+ * DO NOT reuse GitService (../../git/service.ts) for this: it binds a single
+ * baseDir with no GIT_DIR support, and it fires Pre/Post hook events on
+ * every commit/add — automatic silent snapshots must never trigger a user's
+ * PreCommit/PostCommit hooks. AgentWorktree (../../agents/worktree.ts) already
+ * proves the `simpleGit(...).raw([...])` + explicit env pattern used here.
+ *
+ * Checkpoints are addressed entirely through our own ref namespace
+ * (refs/goodvibes/checkpoints/<id>) and through commit objects created via
+ * `commit-tree`, never through the side repo's HEAD/branch. There is no
+ * meaningful "current branch" in this design — parent/lineage is tracked in
+ * the manifest (manager.ts), not via git HEAD — so there is nothing to leave
+ * "detached" and no branch state to pollute.
+ */
+/** Git's well-known empty-tree object hash, valid in every repository. */
+export declare const EMPTY_TREE_HASH = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+/** Ref namespace all workspace checkpoints live under. */
+export declare const CHECKPOINT_REF_PREFIX = "refs/goodvibes/checkpoints/";
+export interface SideGitRunnerOptions {
+    /** Absolute path to the live workspace (GIT_WORK_TREE). */
+    readonly workspaceRoot: string;
+    /** Absolute path to the side repo's object store (GIT_DIR). */
+    readonly gitDir: string;
+}
+/**
+ * Thin runner around a `simple-git` instance permanently scoped (via `.env()`)
+ * to an isolated GIT_DIR/GIT_WORK_TREE pair. Every method here is a small,
+ * named wrapper around a raw git invocation — no hook emission, no shared
+ * state with the user's real repository.
+ */
+export declare class SideGitRunner {
+    readonly workspaceRoot: string;
+    readonly gitDir: string;
+    private readonly git;
+    constructor(opts: SideGitRunnerOptions);
+    /** Run an arbitrary raw git command against the side repo, returning stdout. */
+    raw(args: string[]): Promise<string>;
+    /**
+     * Idempotently initialize the side repo: `git init` the GIT_DIR if it does
+     * not already look initialized, set a local (side-repo-only) fallback
+     * identity so commits never depend on the user's global git config, and
+     * ensure `.goodvibes` is gitignored from the user's own repo's perspective.
+     */
+    init(): Promise<void>;
+    /**
+     * Ensure `<workspaceRoot>/.goodvibes/.gitignore` contains a bare `*` line so
+     * the side repo's own storage (and every other tool's state under
+     * `.goodvibes`) is invisible to the user's OWN git repo (if any). Without
+     * this, `git status`/`git add -A` in the user's real repo would see our
+     * GIT_DIR as an untracked directory and could accidentally stage it.
+     *
+     * This intentionally only ever writes inside `.goodvibes/` — it never
+     * touches the workspace's own top-level `.gitignore`.
+     */
+    private ensureGoodvibesIgnored;
+    /**
+     * Stage changes into the side index.
+     *
+     * @param paths When provided (non-empty), stage only these pathspecs
+     * (scoped snapshot). Otherwise sweep the whole work tree, always excluding
+     * `.goodvibes` (our own storage) via pathspec magic — the same
+     * `:(exclude)` pattern AgentWorktree already uses for the same reason.
+     * Beyond that exclusion, git's normal `.gitignore` handling already applies
+     * here: `.gitignore` matching is a work-tree-relative feature of git and
+     * works identically regardless of where GIT_DIR points, so the workspace's
+     * own `.gitignore` (node_modules, build output, etc.) is honored with no
+     * extra configuration.
+     */
+    stageAll(paths?: string[]): Promise<void>;
+    /** Write the currently-staged index out as a tree object, without committing. Returns the tree hash. */
+    writeTree(): Promise<string>;
+    /** Resolve `<commit>^{tree}` for an existing commit hash. */
+    treeOf(commit: string): Promise<string>;
+    /**
+     * Create a commit object from a tree, deliberately WITHOUT a git parent
+     * (no `-p`) and WITHOUT moving any branch/HEAD.
+     *
+     * Checkpoint lineage is tracked exclusively via the manifest's `parentId`
+     * field (manager.ts) — never via git ancestry. This isn't just a style
+     * choice: if checkpoint commits chained via `-p` the way a normal git
+     * history does, deleting an OLD checkpoint's ref in `gc()` would free
+     * nothing, because that commit stays reachable through every NEWER
+     * checkpoint's parent pointer — the ref is gone but the commit (and any
+     * tree/blob objects unique to it) is still walkable from every surviving
+     * descendant. Parentless commits mean a checkpoint's own ref is the ONLY
+     * thing keeping its commit reachable, so once that ref is deleted,
+     * `git gc --prune=now` can genuinely reclaim it.
+     *
+     * The returned hash is only reachable once a ref is pointed at it via
+     * `updateRef`.
+     */
+    commitTree(treeHash: string, message: string): Promise<string>;
+    updateRef(refName: string, commit: string): Promise<void>;
+    deleteRef(refName: string): Promise<void>;
+    /** List every ref under CHECKPOINT_REF_PREFIX as `{ id, commit }`. */
+    listCheckpointRefs(): Promise<{
+        id: string;
+        commit: string;
+    }[]>;
+    /** Files tracked in a commit's tree (recursive, name-only). */
+    listTrackedFiles(commitOrTree: string): Promise<string[]>;
+    /** Reset the side index to exactly match a commit's tree (does not touch the working tree). */
+    readTreeReset(commit: string): Promise<void>;
+    /** Write every file currently in the side index out to the working tree, overwriting existing files. */
+    checkoutIndexAll(): Promise<void>;
+    /** `git diff` between two commit-ish values. Omit `to` to diff against the live working tree. */
+    diff(from: string, to?: string): Promise<string>;
+    /** `git diff --stat` between two commit-ish values. Omit `to` to diff against the live working tree. */
+    diffStat(from: string, to?: string): Promise<string>;
+    /** `git diff --name-only` between two commit-ish values. Omit `to` to diff against the live working tree. */
+    diffNameOnly(from: string, to?: string): Promise<string[]>;
+    /** `git gc --prune=now` on the side repo. */
+    gc(): Promise<void>;
+}
+//# sourceMappingURL=side-git.d.ts.map

package/dist/platform/workspace/checkpoint/side-git.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"side-git.d.ts","sourceRoot":"","sources":["../../../../src/platform/workspace/checkpoint/side-git.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAQH,0EAA0E;AAC1E,eAAO,MAAM,eAAe,6CAA6C,CAAC;AAE1E,0DAA0D;AAC1D,eAAO,MAAM,qBAAqB,gCAAgC,CAAC;AA8CnE,MAAM,WAAW,oBAAoB;IACnC,2DAA2D;IAC3D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,qBAAa,aAAa;IACxB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAY;gBAEpB,IAAI,EAAE,oBAAoB;IAUtC,gFAAgF;IAC1E,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAI1C;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAkB3B;;;;;;;;;OASG;IACH,OAAO,CAAC,sBAAsB;IAuB9B;;;;;;;;;;;;OAYG;IACG,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAO/C,wGAAwG;IAClG,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC;IAIlC,6DAA6D;IACvD,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI7C;;;;;;;;;;;;;;;;;OAiBG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI9D,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzD,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/C,sEAAsE;IAChE,kBAAkB,IAAI,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAmBrE,+DAA+D;IACzD,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAK/D,+FAA+F;IACzF,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlD,wGAAwG;IAClG,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IAIvC,iGAAiG;IAC3F,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAItD,wGAAwG;IAClG,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI1D,6GAA6G;IACvG,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAKhE,6CAA6C;IACvC,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC;CAG1B"}