@anionex/dsh-turn-rewind 0.1.1 → 0.2.0

package/lib/types/client/index.d.ts

@@ -37,14 +37,14 @@ interface RewindPortalBridgeProps {
 }
 interface SlotsLike {
     inject(name: string, install: () => unknown): void;
-    register(entry: {
+    register<I, P>(entry: {
         readonly name: string;
-        readonly id: string;
-        readonly order: number;
-        readonly inject: () => {
-            readonly openRestoredSession: (sessionId: string, promptText: string) => Promise<void>;
-        };
-    }, component: (props: RewindPortalBridgeProps) => ReactNode): () => void;
+        readonly id?: string;
+        readonly key?: string;
+        readonly order?: number;
+        readonly locale?: string;
+        readonly inject?: () => I;
+    }, component: (props: P) => ReactNode): () => void;
 }
 interface ClientContextLike {
     readonly slots: SlotsLike;
@@ -59,9 +59,69 @@ interface ClientContextLike {
             };
         };
     };
+    readonly settingsScope?: {
+        bind<T>(spec: {
+            readonly namespace: string;
+        }): SettingsScopeLike<T>;
+    };
     effect(setup: () => (() => void), label?: string): unknown;
 }
 type ChangeKind = 'added' | 'deleted' | 'modified' | 'mode-changed' | 'type-changed';
+/** Runtime-tunable Turn Rewind settings mirrored from the `turn-rewind` namespace. */
+export interface TurnRewindSettingsValue {
+    readonly maxRestorePoints: number;
+    readonly maxTurnCheckpointsPerSession: number;
+    readonly maxFiles: number;
+    readonly maxFileBytes: number;
+    readonly maxSnapshotBytes: number;
+    readonly planTtlMs: number;
+    readonly staleLockMs: number;
+    readonly turnCheckpointMode: 'off' | 'git-native' | 'legacy';
+    readonly turnCheckpointTimeoutMs: number;
+    readonly turnCheckpointMaxNewBytes: number;
+    readonly turnCheckpointTrust: 'fast' | 'strict';
+}
+/** Browser mirror of one settings namespace, as bound by `ctx.settingsScope`. */
+export interface SettingsScopeLike<T> {
+    getSnapshot(): SettingsScopeSnapshotLike<T>;
+    subscribe(listener: () => void): () => void;
+    set(field: string, value: unknown): Promise<void>;
+    unset(field: string): Promise<void>;
+}
+/** Sync snapshot shape shared by every settings scope. */
+export interface SettingsScopeSnapshotLike<T> {
+    readonly status: 'loading' | 'ready' | 'unavailable';
+    readonly value: T | undefined;
+    readonly base: unknown;
+    readonly user: unknown;
+    readonly revision: number | undefined;
+    readonly writable: boolean;
+    readonly mode: 'host' | 'memory';
+}
+/** One checkpoint row in the storage-management overview. */
+export interface ManageRestorePoint {
+    readonly id: string;
+    readonly kind: string;
+    readonly format: number;
+    readonly createdAt: number;
+    readonly totalBytes: number;
+    readonly fileCount: number;
+    readonly sessionId?: string;
+    readonly label?: string;
+}
+/** One workspace group in the storage-management overview. */
+export interface ManageWorkspace {
+    readonly workspace: string;
+    readonly totalBytes: number;
+    readonly recoveryCount: number;
+    readonly restorePoints: readonly ManageRestorePoint[];
+}
+/** Storage-management overview served by `/turn-rewind/manage`. */
+export interface ManageOverview {
+    readonly storageDir: string;
+    readonly totalBytes: number;
+    readonly workspaces: readonly ManageWorkspace[];
+}
 /** Return the rewind anchor and editable text owned by one direct user message. */
 export declare function selectRewindMessage(node: ConversationNodeLike): RewindMatch | null;
 /** Browser plugin entry: bridge every direct user-message action row to the rewind UI. */
@@ -71,6 +131,13 @@ export declare function apply(ctx: ClientContextLike): void;
 export declare function RewindMessagePortals({ sessionId, openRestoredSession, useSession }: RewindPortalBridgeProps): ReactNode;
 /** User-message action and its review-first file/conversation restore dialog. */
 export declare function RewindMessageAction({ matched, sessionId, openRestoredSession }: RewindMessageActionProps): ReactNode;
+interface TurnRewindSettingsCardProps {
+    readonly scope: SettingsScopeLike<TurnRewindSettingsValue> | undefined;
+}
+/** Settings card for the `turn-rewind` namespace: runtime options plus checkpoint management. */
+export declare function TurnRewindSettingsCard({ scope }: TurnRewindSettingsCardProps): ReactNode;
+/** Format one byte count with human-friendly units. */
+export declare function formatBytes(bytes: number): string;
 /** Resolve one conversation node to its DOM row key and rewind match. */
 export declare function selectRewindMessageTarget(value: RewindNodeLike): {
     readonly matched: RewindMatch;

package/lib/types/deadline.d.ts

@@ -0,0 +1,6 @@
+export interface Deadline {
+    readonly signal: AbortSignal;
+    cancel(): void;
+}
+/** Create a cancellable timeout whose timer keeps Node alive until it fires. */
+export declare function createDeadline(timeoutMs: number): Deadline;

package/lib/types/engine.d.ts

@@ -1,16 +1,29 @@
 import { LedgerStore } from './store.js';
-import { type ChangeLedgerConfig, type RecoverySummary, type ResolvedChangeLedgerConfig, type RestorePlan, type RestorePointInspection, type RestorePointManifest, type RestorePointSummary, type RestoreResult } from './types.js';
+import { type ChangeLedgerConfig, type RecoverySummary, type ResolvedChangeLedgerConfig, type RestorePlan, type RestorePointInspection, type RestorePointManifest, type RestorePointSummary, type RestoreResult, type WorkspaceOverview, type WorkspacePurgeReport } from './types.js';
 /** Persistent workspace change-set engine, independent of the DSH tool adapter. */
 export declare class ChangeLedgerEngine {
-    readonly config: ResolvedChangeLedgerConfig;
+    private readonly currentConfig;
     readonly store: LedgerStore;
     private readonly plans;
     private readonly activePlans;
     private readonly ready;
     /** Build an engine and start crash-journal reconciliation. */
     constructor(config?: ChangeLedgerConfig);
+    /** Currently resolved configuration; runtime-tunable fields update in place. */
+    get config(): ResolvedChangeLedgerConfig;
+    /**
+     * Swap runtime-tunable configuration (limits, modes, timeouts, trust) in place.
+     * The storage root must never move once the engine owns locks and journals.
+     */
+    updateConfig(config: ChangeLedgerConfig): void;
     /** Wait for startup reconciliation and return the number of interrupted journals found. */
     initialize(): Promise<number>;
+    private initializeStore;
+    private acquireWorkspace;
+    private reconcileGitCheckpointJournals;
+    private publishGitManifest;
+    private deleteManifestWithGit;
+    private tryReadManifest;
     /** Create a durable restore point for the current Git worktree. */
     create(options: {
         readonly cwd: string;
@@ -26,6 +39,25 @@ export declare class ChangeLedgerEngine {
         readonly turnStartSeq: number;
         readonly signal?: AbortSignal;
     }): Promise<RestorePointSummary>;
+    /** Persist one bounded automatic-checkpoint skip without blocking a later turn retry. */
+    recordTurnCheckpointSkip(options: {
+        readonly cwd: string;
+        readonly sessionId: string;
+        readonly turn: number;
+        readonly turnStartSeq: number;
+        readonly reason: string;
+        readonly signal?: AbortSignal;
+    }): Promise<void>;
+    /** Read a durable skip marker for one exact prompt boundary. */
+    findTurnCheckpointSkip(options: {
+        readonly cwd: string;
+        readonly sessionId: string;
+        readonly turn: number;
+        readonly turnStartSeq: number;
+        readonly signal?: AbortSignal;
+    }): Promise<{
+        readonly reason: string;
+    } | undefined>;
     /** Find the prompt-anchored checkpoint captured before one session turn. */
     findTurnCheckpoint(options: {
         readonly cwd: string;
@@ -80,9 +112,23 @@ export declare class ChangeLedgerEngine {
         readonly cwd: string;
         readonly signal?: AbortSignal;
     }): Promise<RecoverySummary[]>;
+    /** Inventory every workspace this storage root has ever persisted state for. */
+    listWorkspaces(options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<WorkspaceOverview[]>;
+    /** Delete unprotected restore points recorded for one workspace and collect unused blobs. */
+    purgeWorkspace(options: {
+        readonly workspace: string;
+        /** Restrict the purge to these restore points; protection rules still apply. */
+        readonly restorePointIds?: readonly string[];
+        readonly signal?: AbortSignal;
+    }): Promise<WorkspacePurgeReport>;
+    private purgeWorkspaceDir;
     private createLocked;
     private restorePaths;
+    private assertPathFresh;
     private verifyPaths;
+    private captureSelectedEntries;
     private assertStorageSeparated;
     private expirePlans;
 }

package/lib/types/git-checkpoint.d.ts

@@ -0,0 +1,46 @@
+import { type ResolvedChangeLedgerConfig, type RestorePointManifestV2 } from './types.js';
+interface CacheRecord {
+    readonly kind: 'file' | 'symlink';
+    readonly mode: number;
+    readonly size: string;
+    readonly mtimeNs: string;
+    readonly ctimeNs: string;
+    readonly dev: string;
+    readonly ino: string;
+    readonly indexOid?: string;
+    readonly attributes: string;
+    readonly oid: string;
+    readonly target?: string;
+}
+interface GitCache {
+    readonly version: 2;
+    readonly storeId: string;
+    readonly worktreeId: string;
+    readonly paths: Readonly<Record<string, CacheRecord>>;
+    readonly checksum: string;
+}
+export interface GitCheckpointCapture {
+    readonly manifest: RestorePointManifestV2;
+    readonly cache: GitCache;
+}
+/** Create a complete Git-native turn checkpoint without writing the real index. */
+export declare function captureGitTurnCheckpoint(options: {
+    readonly cwd: string;
+    readonly id: string;
+    readonly sessionId: string;
+    readonly turn: number;
+    readonly turnStartSeq: number;
+    readonly config: ResolvedChangeLedgerConfig;
+    readonly signal?: AbortSignal;
+}): Promise<GitCheckpointCapture>;
+/** Publish a prepared checkpoint under its exact private ref. */
+export declare function publishGitCheckpoint(manifest: RestorePointManifestV2, storageDir: string, signal?: AbortSignal): Promise<void>;
+/** Verify persisted Git metadata before exposing or restoring a v2 point. */
+export declare function verifyGitCheckpoint(manifest: RestorePointManifestV2, signal?: AbortSignal): Promise<void>;
+/** Compare-and-swap delete a v2 private ref. */
+export declare function deleteGitCheckpoint(manifest: RestorePointManifestV2, storageDir: string, signal?: AbortSignal): Promise<void>;
+/** Delete an exact private ref target, including during startup journal reconciliation. */
+export declare function deleteGitCheckpointRef(workspace: string, ref: string, commit: string, storageDir: string, signal?: AbortSignal): Promise<void>;
+/** Read one v2 Git blob for selective restore. */
+export declare function readGitBlob(workspace: string, oid: string, expectedSize: number, signal?: AbortSignal): Promise<Buffer>;
+export {};

package/lib/types/git.d.ts

@@ -4,11 +4,42 @@ export interface RepositorySnapshotSource {
     readonly state: RepositoryState;
     readonly paths: readonly string[];
 }
+/** Durable identity and shared lock location for one concrete Git worktree. */
+export interface GitWorktreeIdentity {
+    readonly root: string;
+    readonly gitDir: string;
+    readonly commonDir: string;
+    readonly worktreeId: string;
+    readonly lockPath: string;
+}
 /** Discover the Git worktree owning `cwd` and enumerate tracked/non-ignored paths. */
 export declare function discoverRepository(cwd: string, signal?: AbortSignal): Promise<RepositorySnapshotSource>;
 /** Resolve the canonical Git worktree root owning `cwd` without inventorying its files. */
 export declare function discoverRepositoryRoot(cwd: string, signal?: AbortSignal): Promise<string>;
+/** Create or read the per-worktree identity used by refs and cross-store locking. */
+export declare function ensureGitWorktreeIdentity(cwd: string, signal?: AbortSignal): Promise<GitWorktreeIdentity>;
+/** Resolve a moved linked worktree from its common directory and durable identity. */
+export declare function resolveGitWorktreeRoot(commonDir: string, worktreeId: string, fallback: string, signal?: AbortSignal): Promise<string>;
 /** Return true when two repository fences refer to the same checkout state. */
 export declare function sameRepositoryFence(left: RepositoryState, right: RepositoryState): boolean;
+/** Run Git with stable non-interactive defaults and return UTF-8 output. */
+export declare function runGit(cwd: string, args: readonly string[], signal?: AbortSignal, options?: {
+    readonly env?: NodeJS.ProcessEnv;
+    readonly maxBuffer?: number;
+}): Promise<string>;
+/** Run Git and return undefined for its ordinary "not found" exit status. */
+export declare function runGitOptional(cwd: string, args: readonly string[], signal?: AbortSignal, options?: {
+    readonly env?: NodeJS.ProcessEnv;
+    readonly maxBuffer?: number;
+}): Promise<string | undefined>;
+/** Run Git with binary stdin and return UTF-8 stdout. */
+export declare function runGitInput(cwd: string, args: readonly string[], input: Buffer | string, signal?: AbortSignal, options?: {
+    readonly env?: NodeJS.ProcessEnv;
+}): Promise<string>;
+/** Run Git and return raw stdout bytes. */
+export declare function runGitBuffer(cwd: string, args: readonly string[], signal?: AbortSignal, options?: {
+    readonly env?: NodeJS.ProcessEnv;
+    readonly maxBuffer?: number;
+}): Promise<Buffer>;
 /** Return the Git metadata directory for diagnostics. */
 export declare function gitMetadataParent(state: RepositoryState): string;

package/lib/types/index.d.ts

@@ -8,6 +8,7 @@ import type { ChangeLedgerConfig } from './types.js';
 export * from './engine.js';
 export * from './errors.js';
 export * from './rewind-host.js';
+export * from './settings.js';
 export * from './types.js';
 declare module '@deepseek-ai/cordis' {
     interface Context {
@@ -39,5 +40,11 @@ export declare class ChangeLedgerService {
     delete(options: Parameters<ChangeLedgerEngine['delete']>[0]): ReturnType<ChangeLedgerEngine['delete']>;
     /** List interrupted restore operations and their rescue points. */
     listRecovery(options: Parameters<ChangeLedgerEngine['listRecovery']>[0]): ReturnType<ChangeLedgerEngine['listRecovery']>;
+    /** Inventory every workspace this storage root has persisted state for. */
+    listWorkspaces(options?: Parameters<ChangeLedgerEngine['listWorkspaces']>[0]): ReturnType<ChangeLedgerEngine['listWorkspaces']>;
+    /** Delete unprotected restore points recorded for one workspace. */
+    purgeWorkspace(options: Parameters<ChangeLedgerEngine['purgeWorkspace']>[0]): ReturnType<ChangeLedgerEngine['purgeWorkspace']>;
+    /** Swap runtime-tunable configuration; the storage root must stay fixed. */
+    updateConfig(config: ChangeLedgerConfig): void;
 }
 export default ChangeLedgerService;

package/lib/types/path-utils.d.ts

@@ -16,6 +16,8 @@ export declare function readJson(path: string): Promise<unknown>;
 export declare function pathExists(path: string): Promise<boolean>;
 /** Ensure every existing parent below `root` is a real directory, never a symlink. */
 export declare function ensureSafeParents(root: string, target: string): Promise<void>;
+/** Validate existing parents without creating missing directories. */
+export declare function assertSafeParents(root: string, target: string): Promise<void>;
 /** Replace a path with a regular file using a sibling temporary file. */
 export declare function replaceRegularFile(path: string, content: Buffer, mode: number): Promise<void>;
 /** Replace a path with a symbolic link using a sibling temporary name. */

package/lib/types/rewind-host.d.ts

@@ -115,14 +115,16 @@ export declare class TurnCheckpointCoordinator {
     private readonly captures;
     private readonly pending;
     private readonly failures;
+    private readonly skips;
     private readonly workspaceTails;
     constructor(engine: ChangeLedgerEngine);
     /** Install the first-step gate; checkpoint failures are recorded but never reject the user turn. */
     install(ctx: Context): void;
     /** Current capture state for a session turn when no durable checkpoint exists yet. */
     state(sessionId: string, turn: number): {
-        readonly status: 'pending' | 'failed' | 'missing';
+        readonly status: 'pending' | 'failed' | 'skipped' | 'missing';
         readonly error?: string;
+        readonly reason?: string;
     };
     private capture;
     private serializeWorkspace;
@@ -130,6 +132,11 @@ export declare class TurnCheckpointCoordinator {
 }
 /** Register the same-origin preview/apply endpoint consumed by the browser half. */
 export declare function installRewindHttp(ctx: Context, engine: ChangeLedgerEngine, coordinator: TurnCheckpointCoordinator): void;
+export declare const MANAGE_HTTP_PATH = "/turn-rewind/manage";
+/** Register the same-origin storage-management endpoint consumed by the settings card. */
+export declare function installManageHttp(ctx: Context, engine: ChangeLedgerEngine): void;
+/** Build the storage-management route as a testable unit. */
+export declare function createManageHttpHandler(engine: ChangeLedgerEngine): (request: HttpRequestLike, response: HttpResponseLike) => Promise<void>;
 /** Build the exact-route handler as a testable unit. */
 export declare function createRewindHttpHandler(ctx: Pick<Context, 'sessions' | 'sessionQuery' | 'apiProxy'> & {
     readonly agents?: AgentsLike;

package/lib/types/settings.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Runtime settings surface for Turn Rewind on the DSH web settings page.
+ * @module @anionex/dsh-turn-rewind
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import { type ChangeLedgerEngine } from './engine.js';
+import type { ChangeLedgerConfig } from './types.js';
+/** Namespace join key shared by the host section and the browser settings card. */
+export declare const TURN_REWIND_SETTINGS_NAMESPACE: Branded<"SettingsNamespace">;
+/** Every runtime-tunable field of {@link ChangeLedgerConfig}; `storageDir` stays config-layer only. */
+export interface TurnRewindSettings {
+    /** Maximum user and rescue restore points retained per workspace. */
+    maxRestorePoints: number;
+    /** Maximum automatic turn checkpoints retained per session. */
+    maxTurnCheckpointsPerSession: number;
+    /** Maximum number of files in one restore point. */
+    maxFiles: number;
+    /** Maximum bytes read from one regular file. */
+    maxFileBytes: number;
+    /** Maximum aggregate regular-file bytes in one restore point. */
+    maxSnapshotBytes: number;
+    /** Restore-plan lifetime in milliseconds. */
+    planTtlMs: number;
+    /** Age after which a lock whose owner is gone may be reclaimed. */
+    staleLockMs: number;
+    /** Automatic turn-checkpoint implementation; `off` records durable skips instead. */
+    turnCheckpointMode: 'off' | 'git-native' | 'legacy';
+    /** Maximum time one automatic checkpoint may block the first Agent step. */
+    turnCheckpointTimeoutMs: number;
+    /** Maximum uncached worktree bytes read by one automatic Git-native checkpoint. */
+    turnCheckpointMaxNewBytes: number;
+    /** Fast trusts fenced Git/stat metadata; strict rereads every eligible path. */
+    turnCheckpointTrust: 'fast' | 'strict';
+}
+/** Schemastery schema for the `turn-rewind` settings namespace. */
+export declare const TurnRewindSettingsSchema: z<TurnRewindSettings>;
+/**
+ * Register the `turn-rewind` settings namespace and apply its resolved value to the
+ * running engine. The composition entry (from `cordis.patch.yml`) is the base layer;
+ * the user layer persists through the DSH settings provider. `storageDir` is never
+ * carried by the namespace: the storage root must not move while the engine runs.
+ */
+export declare function installTurnRewindSettings(ctx: Context, config: ChangeLedgerConfig, engine: ChangeLedgerEngine): void;

package/lib/types/snapshot.d.ts

@@ -5,6 +5,7 @@ import type { ResolvedChangeLedgerConfig, SnapshotEntry, WorkspaceChange } from
 export interface CapturedTree {
     readonly source: RepositorySnapshotSource;
     readonly entries: Readonly<Record<string, SnapshotEntry>>;
+    readonly gitEntries?: Readonly<Record<string, SnapshotEntry>>;
     readonly treeHash: string;
     readonly fileCount: number;
     readonly totalBytes: number;
@@ -14,6 +15,7 @@ export declare function captureTree(options: {
     readonly cwd: string;
     readonly config: ResolvedChangeLedgerConfig;
     readonly store?: LedgerStore;
+    readonly gitObjectFormat?: 'sha1' | 'sha256';
     readonly signal?: AbortSignal;
 }): Promise<CapturedTree>;
 /**
@@ -25,11 +27,14 @@ export declare function captureStableTree(options: {
     readonly cwd: string;
     readonly config: ResolvedChangeLedgerConfig;
     readonly store?: LedgerStore;
+    readonly gitObjectFormat?: 'sha1' | 'sha256';
     readonly signal?: AbortSignal;
 }): Promise<CapturedTree>;
 /** Compute stable path-level differences between two captured trees. */
-export declare function diffTrees(before: Readonly<Record<string, SnapshotEntry>>, after: Readonly<Record<string, SnapshotEntry>>): WorkspaceChange[];
+export declare function diffTrees(before: Readonly<Record<string, SnapshotEntry>>, after: Readonly<Record<string, SnapshotEntry>>, comparisonBefore?: Readonly<Record<string, SnapshotEntry>>, comparisonAfter?: Readonly<Record<string, SnapshotEntry>>): WorkspaceChange[];
 /** Return whether two snapshot entries are byte/type/mode equivalent. */
 export declare function entriesEqual(left: SnapshotEntry | undefined, right: SnapshotEntry | undefined): boolean;
 /** Hash a complete path map into a deterministic tree identity. */
 export declare function hashTree(entries: Readonly<Record<string, SnapshotEntry>>): string;
+/** Byte-verify one workspace-relative path without following a final symlink. */
+export declare function captureSnapshotEntry(root: string, path: string, maxFileBytes: number, signal?: AbortSignal, gitObjectFormat?: 'sha1' | 'sha256'): Promise<SnapshotEntry | undefined>;

package/lib/types/store.d.ts

@@ -1,12 +1,43 @@
-import type { ResolvedChangeLedgerConfig, RestoreOperation, RestorePointManifest } from './types.js';
+import type { ResolvedChangeLedgerConfig, RestoreOperation, RestorePointManifest, RestorePointManifestV2 } from './types.js';
+export interface GitCheckpointJournal {
+    readonly version: 1;
+    readonly action: 'publish' | 'delete';
+    readonly storeId: string;
+    readonly workspace: string;
+    readonly commonDir: string;
+    readonly worktreeId: string;
+    readonly restorePointId: string;
+    readonly ref: string;
+    readonly commit: string;
+    readonly createdAt: number;
+}
+export interface TurnCheckpointSkip {
+    readonly version: 1;
+    readonly sessionId: string;
+    readonly turn: number;
+    readonly turnStartSeq: number;
+    readonly reason: string;
+    readonly createdAt: number;
+}
 /** Durable content-addressed storage and per-workspace locking. */
 export declare class LedgerStore {
     readonly config: ResolvedChangeLedgerConfig;
+    private readonly workspaceKeys;
+    private storeIdValue;
     constructor(config: ResolvedChangeLedgerConfig);
     /** Create the state root and reconcile crash-interrupted operations. */
     initialize(): Promise<number>;
+    /** Durable owner of this storage root's private Git namespace. */
+    get storeId(): string;
     /** Acquire the exclusive lock for one canonical workspace. */
-    acquire(workspace: string): Promise<() => Promise<void>>;
+    acquire(workspace: string, sharedLockPath?: string, binding?: {
+        readonly commonDir: string;
+        readonly gitDir: string;
+        readonly worktreeId: string;
+    }, signal?: AbortSignal): Promise<() => Promise<void>>;
+    /** Acquire only the durable directory lock when the recorded worktree is no longer available. */
+    acquireWorkspaceDir(workspaceDir: string, workspace: string, signal?: AbortSignal): Promise<() => Promise<void>>;
+    private acquireOne;
     /** Persist a blob if it is not already present, and verify existing content. */
     putBlob(workspace: string, hash: string, content: Buffer): Promise<void>;
     /** Read and verify one content-addressed blob. */
@@ -16,24 +47,77 @@ export declare class LedgerStore {
     /** Load and validate one restore-point manifest. */
     readManifest(workspace: string, id: string): Promise<RestorePointManifest>;
     /** List all validated restore points for one workspace, newest first. */
-    listManifests(workspace: string): Promise<RestorePointManifest[]>;
+    listManifests(workspace: string, signal?: AbortSignal): Promise<RestorePointManifest[]>;
+    /** List validated manifests directly from one storage directory, newest first. */
+    listManifestsInDir(workspaceDir: string, signal?: AbortSignal): Promise<RestorePointManifest[]>;
     /** Delete one restore-point manifest. Blobs remain until garbage collection succeeds. */
     deleteManifest(workspace: string, id: string): Promise<void>;
+    /** Delete one restore-point manifest directly from its storage directory. */
+    deleteManifestInDir(workspaceDir: string, id: string): Promise<void>;
+    /** Persist the intent needed to finish or roll back a Git ref/manifest transition after a crash. */
+    writeGitCheckpointJournal(action: GitCheckpointJournal['action'], manifest: RestorePointManifestV2): Promise<void>;
+    /** List every persisted workspace directory under this storage root. */
+    listWorkspaceDirs(signal?: AbortSignal): Promise<string[]>;
+    /** List every pending Git checkpoint transition across this storage root. */
+    listGitCheckpointJournals(): Promise<GitCheckpointJournal[]>;
+    /** List pending Git checkpoint transitions directly from one storage directory. */
+    listGitCheckpointJournalsInDir(workspaceDir: string, signal?: AbortSignal): Promise<GitCheckpointJournal[]>;
+    /** Remove one completed Git checkpoint transition journal. */
+    deleteGitCheckpointJournal(workspace: string, id: string): Promise<void>;
+    /** Persist one explicit automatic-checkpoint skip so the UI survives restarts. */
+    writeTurnCheckpointSkip(workspace: string, skip: TurnCheckpointSkip): Promise<void>;
+    /** Read one durable automatic-checkpoint skip. */
+    readTurnCheckpointSkip(workspace: string, sessionId: string, turn: number, turnStartSeq: number): Promise<TurnCheckpointSkip | undefined>;
+    /** Remove a stale skip after the same turn obtains a ready checkpoint. */
+    deleteTurnCheckpointSkip(workspace: string, sessionId: string, turn: number, turnStartSeq: number): Promise<void>;
+    /** Mark a legacy capture whose unreferenced blobs need crash recovery. */
+    writeSnapshotCleanup(workspace: string): Promise<void>;
+    /** Clear a completed legacy-capture cleanup marker. */
+    deleteSnapshotCleanup(workspace: string): Promise<void>;
     /** Persist one restore-operation journal. */
     writeOperation(operation: RestoreOperation): Promise<void>;
     /** List validated restore operations for one workspace. */
     listOperations(workspace: string): Promise<RestoreOperation[]>;
+    /** List validated restore operations directly from one storage directory. */
+    listOperationsInDir(workspaceDir: string, signal?: AbortSignal): Promise<RestoreOperation[]>;
     /** Return whether an incomplete operation still references a restore point. */
     isReferencedByRecovery(workspace: string, restorePointId: string): Promise<boolean>;
     /** Delete blobs not referenced by any remaining manifest. */
-    collectGarbage(workspace: string, additionalReferenced?: Iterable<string>): Promise<{
+    collectGarbage(workspace: string, additionalReferenced?: Iterable<string>, signal?: AbortSignal): Promise<{
+        deletedBlobs: number;
+        retainedBlobs: number;
+    }>;
+    /** Delete blobs under one storage directory that no manifest in it references. */
+    collectGarbageInDir(workspaceDir: string, signal?: AbortSignal): Promise<{
         deletedBlobs: number;
         retainedBlobs: number;
     }>;
+    /** Remove every persisted automatic-checkpoint skip marker under one storage directory. */
+    clearTurnOutcomesInDir(workspaceDir: string): Promise<number>;
+    private sweepBlobs;
+    /** Finish a prior bounded legacy capture's orphan cleanup, if one is pending. */
+    reconcileSnapshotCleanup(workspace: string, signal?: AbortSignal): Promise<boolean>;
     private workspaceDir;
+    private assertManifestOwned;
+    private assertGitCheckpointJournalOwned;
+    private assertManifestWorkspaceIdentity;
+    private assertGitCheckpointJournalWorkspaceIdentity;
     private manifestPath;
     private operationPath;
+    private gitCheckpointJournalPath;
+    private turnCheckpointSkipPath;
     private blobPath;
-    private reclaimStaleLock;
-    private workspaceAppearsActive;
+    private bindGitWorkspace;
+    private reconcileWorkspaceMigrations;
+    private completeWorkspaceMigration;
+    private assertNoUnresolvedWorkspaceOwnership;
+    private ensureWorktreeClaim;
+    private completeWorkspaceRebind;
+    private rewriteWorkspaceRoot;
+    private prepareLockReclaim;
+    private completeLockReclaims;
+    private acquireLockReclaimOwnership;
+    private lockIsReclaimable;
 }
+/** Create or read the durable owner of one storage root's private Git namespace. */
+export declare function ensureStoreId(storageDir: string): Promise<string>;