@pellux/goodvibes-sdk 0.36.0 → 0.37.0

package/dist/platform/workspace/checkpoint/manager.d.ts

@@ -0,0 +1,163 @@
+/**
+ * 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 type { RuntimeEventBus } from '../../runtime/events/index.js';
+import { type RetentionConfig, type RetentionClass, type PruneResult } from '../../runtime/retention/index.js';
+import type { WorkspaceCheckpoint, CheckpointKind, CheckpointDiff, RestoreResult } from './types.js';
+export interface CreateCheckpointOptions {
+    readonly kind: CheckpointKind;
+    readonly label?: string | undefined;
+    readonly retentionClass?: RetentionClass | undefined;
+    readonly turnId?: string | undefined;
+    readonly agentId?: string | undefined;
+    /** Scope the snapshot to these paths instead of sweeping the whole workspace. */
+    readonly paths?: string[] | undefined;
+}
+export interface RestoreOptions {
+    /** Restrict restore to these paths instead of the whole workspace. */
+    readonly paths?: string[] | undefined;
+    /** Take a safety checkpoint of the current state before restoring. Defaults to true. */
+    readonly safetyCheckpoint?: boolean | undefined;
+}
+export interface ListCheckpointsFilter {
+    readonly kind?: CheckpointKind | undefined;
+    readonly since?: number | undefined;
+    readonly limit?: number | undefined;
+}
+export interface WorkspaceCheckpointManagerOptions {
+    readonly workspaceRoot: string;
+    /** Override the side repo's GIT_DIR. Defaults to `<workspaceRoot>/.goodvibes/checkpoints/git`. */
+    readonly checkpointDir?: string | undefined;
+    /** When provided, the manager subscribes to TURN_COMPLETED/TURN_ERROR/TURN_CANCEL/AGENT_COMPLETED for automatic snapshots. */
+    readonly runtimeBus?: RuntimeEventBus | undefined;
+    readonly retention?: Partial<RetentionConfig> | undefined;
+    /** Clock override for deterministic tests. */
+    readonly now?: (() => number) | undefined;
+}
+/**
+ * WorkspaceCheckpointManager — create/list/diff/restore/gc for whole-workspace
+ * git-backed snapshots, plus automatic snapshotting on existing turn/agent
+ * lifecycle events.
+ */
+export declare class WorkspaceCheckpointManager {
+    readonly workspaceRoot: string;
+    private readonly checkpointRootDir;
+    private readonly sideGit;
+    private readonly manifestStore;
+    private readonly retentionPolicy;
+    private readonly now;
+    private readonly runtimeBus;
+    private readonly unsubscribers;
+    private checkpoints;
+    private initialized;
+    private initPromise;
+    constructor(opts: WorkspaceCheckpointManagerOptions);
+    /**
+     * 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.
+     */
+    init(): Promise<void>;
+    private _init;
+    /**
+     * 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.
+     */
+    private subscribeToAutomaticSnapshots;
+    /**
+     * 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.
+     */
+    create(opts: CreateCheckpointOptions): Promise<WorkspaceCheckpoint | null>;
+    /** List checkpoints, newest-first. `list()[0]` is always the most recent checkpoint. */
+    list(filter?: ListCheckpointsFilter): Promise<WorkspaceCheckpoint[]>;
+    /**
+     * Diff two checkpoints, or a checkpoint against the live working tree when
+     * `b` is omitted.
+     */
+    diff(a: string, b?: string): Promise<CheckpointDiff>;
+    /**
+     * 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.
+     */
+    restore(id: string, opts?: RestoreOptions): Promise<RestoreResult>;
+    /**
+     * 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.
+     */
+    gc(): Promise<PruneResult>;
+    /** Unsubscribe from the runtime bus. Does not touch anything on disk. */
+    dispose(): void;
+    private mostRecentCheckpoint;
+    private requireCheckpoint;
+    private defaultLabel;
+    /**
+     * 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.
+     */
+    private computeSizeBytes;
+    private persistManifest;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/platform/workspace/checkpoint/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../../../src/platform/workspace/checkpoint/manager.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,473 @@
+/**
+ * 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;
+    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.
+     */
+    async create(opts) {
+        await this.init();
+        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, parent?.commit ?? null);
+        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.
+     */
+    async diff(a, b) {
+        await this.init();
+        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.
+     */
+    async restore(id, opts) {
+        await this.init();
+        const target = this.requireCheckpoint(id);
+        const wantSafety = opts?.safetyCheckpoint ?? true;
+        let beforeFiles;
+        let safetyCheckpointId = null;
+        if (wantSafety) {
+            const safety = await this.create({ 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.
+     */
+    async gc() {
+        await this.init();
+        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()) });
+    }
+}