@anionex/dsh-turn-rewind 0.2.2 → 0.3.0

package/lib/engine.js

@@ -4,11 +4,12 @@ import { join, resolve } from 'node:path';
 import { lstat, realpath } from 'node:fs/promises';
 import { createDeadline } from './deadline.js';
 import { ChangeLedgerError, errorMessage } from './errors.js';
-import { discoverRepository, discoverRepositoryRoot, ensureGitWorktreeIdentity, resolveGitWorktreeRoot, sameRepositoryFence, } from './git.js';
+import { ensureGitWorktreeIdentity, resolveGitWorktreeRoot } from './git.js';
 import { captureGitTurnCheckpoint, deleteGitCheckpoint, deleteGitCheckpointRef, publishGitCheckpoint, readGitBlob, verifyGitCheckpoint, } from './git-checkpoint.js';
 import { assertSafeParents, ensureSafeParents, expandHome, isNodeError, isWithin, pruneEmptyParents, removeRestoreTarget, replaceRegularFile, replaceSymbolicLink, resolveWorkspacePath, validateRelativePath, } from './path-utils.js';
 import { captureSnapshotEntry, captureStableTree, diffTrees, entriesEqual } from './snapshot.js';
 import { LedgerStore } from './store.js';
+import { discoverWorkspace, discoverWorkspaceIdentity, sameWorkspaceFence } from './workspace.js';
 import { LEDGER_FORMAT_VERSION, } from './types.js';
 const DEFAULTS = {
     maxRestorePoints: 50,
@@ -59,12 +60,21 @@ export class ChangeLedgerEngine {
         const restoredOperations = await this.store.initialize();
         return restoredOperations + await this.reconcileGitCheckpointJournals();
     }
+    /**
+     * Acquire the exclusive lock for one workspace.
+     *
+     * A Git worktree also binds the shared per-worktree lock derived from its Git
+     * identity; an ordinary directory owns only the durable directory lock.
+     */
     async acquireWorkspace(workspace, signal) {
-        const identity = await ensureGitWorktreeIdentity(workspace, signal);
-        if (identity.root !== workspace) {
-            throw new ChangeLedgerError('GIT_ROOT_INVALID', `workspace moved while acquiring its lock: ${JSON.stringify(workspace)}`);
+        if (workspace.type === 'directory') {
+            return this.store.acquire(workspace.root, undefined, undefined, signal);
+        }
+        const identity = await ensureGitWorktreeIdentity(workspace.root, signal);
+        if (identity.root !== workspace.root) {
+            throw new ChangeLedgerError('GIT_ROOT_INVALID', `workspace moved while acquiring its lock: ${JSON.stringify(workspace.root)}`);
         }
-        return this.store.acquire(workspace, identity.lockPath, {
+        return this.store.acquire(workspace.root, identity.lockPath, {
             commonDir: identity.commonDir,
             gitDir: identity.gitDir,
             worktreeId: identity.worktreeId,
@@ -75,7 +85,7 @@ export class ChangeLedgerEngine {
         for (const journal of await this.store.listGitCheckpointJournals()) {
             const workspace = await resolveGitWorktreeRoot(journal.commonDir, journal.worktreeId, journal.workspace);
             const activeJournal = workspace === journal.workspace ? journal : { ...journal, workspace };
-            const release = await this.acquireWorkspace(workspace);
+            const release = await this.acquireWorkspace({ type: 'git', root: workspace });
             try {
                 const manifest = await this.tryReadManifest(workspace, journal.restorePointId);
                 if (journal.action === 'publish') {
@@ -167,9 +177,9 @@ export class ChangeLedgerEngine {
     /** Create a durable restore point for the current Git worktree. */
     async create(options) {
         await this.ready;
-        const source = await discoverRepository(options.cwd, options.signal);
+        const source = await discoverWorkspace(options.cwd, this.config, options.signal);
         await this.assertStorageSeparated(source.state.root);
-        const release = await this.acquireWorkspace(source.state.root, options.signal);
+        const release = await this.acquireWorkspace(source.state, options.signal);
         try {
             const label = normalizeLabel(options.label);
             const manifest = await this.createLocked({
@@ -206,9 +216,9 @@ export class ChangeLedgerEngine {
                 throw new ChangeLedgerError('INVALID_ARGUMENTS', 'turnStartSeq must be a non-negative safe integer');
             }
             try {
-                const source = await discoverRepository(options.cwd, signal);
+                const source = await discoverWorkspace(options.cwd, this.config, signal);
                 await this.assertStorageSeparated(source.state.root);
-                const release = await this.acquireWorkspace(source.state.root, signal);
+                const release = await this.acquireWorkspace(source.state, signal);
                 try {
                     const existing = await waitWithSignal(this.store.listManifests(source.state.root, signal), signal);
                     const duplicate = existing.find(manifest => manifest.kind === 'turn'
@@ -223,7 +233,9 @@ export class ChangeLedgerEngine {
                     }
                     throwIfAborted(signal);
                     let manifest;
-                    if (this.config.turnCheckpointMode === 'legacy') {
+                    // Git-native checkpoints live in the repository object database, so an
+                    // ordinary directory always uses the ledger's own content-addressed store.
+                    if (this.config.turnCheckpointMode === 'legacy' || source.state.type === 'directory') {
                         manifest = await this.createLocked({
                             cwd: source.state.root,
                             kind: 'turn',
@@ -278,20 +290,20 @@ export class ChangeLedgerEngine {
     /** Persist one bounded automatic-checkpoint skip without blocking a later turn retry. */
     async recordTurnCheckpointSkip(options) {
         await waitWithSignal(this.ready, options.signal);
-        const workspace = await discoverRepositoryRoot(options.cwd, options.signal);
-        await this.assertStorageSeparated(workspace);
+        const workspace = await discoverWorkspaceIdentity(options.cwd, options.signal);
+        await this.assertStorageSeparated(workspace.root);
         const release = await this.acquireWorkspace(workspace, options.signal);
         try {
             throwIfAborted(options.signal);
-            const existing = (await this.store.listManifests(workspace, options.signal)).some(manifest => manifest.kind === 'turn'
+            const existing = (await this.store.listManifests(workspace.root, options.signal)).some(manifest => manifest.kind === 'turn'
                 && manifest.sessionId === options.sessionId
                 && manifest.turn === options.turn
                 && manifest.turnStartSeq === options.turnStartSeq);
             if (existing) {
-                await this.store.deleteTurnCheckpointSkip(workspace, options.sessionId, options.turn, options.turnStartSeq);
+                await this.store.deleteTurnCheckpointSkip(workspace.root, options.sessionId, options.turn, options.turnStartSeq);
                 return;
             }
-            await this.store.writeTurnCheckpointSkip(workspace, {
+            await this.store.writeTurnCheckpointSkip(workspace.root, {
                 version: 1,
                 sessionId: options.sessionId,
                 turn: options.turn,
@@ -307,11 +319,11 @@ export class ChangeLedgerEngine {
     /** Read a durable skip marker for one exact prompt boundary. */
     async findTurnCheckpointSkip(options) {
         await this.ready;
-        const workspace = await discoverRepositoryRoot(options.cwd, options.signal);
-        await this.assertStorageSeparated(workspace);
+        const workspace = await discoverWorkspaceIdentity(options.cwd, options.signal);
+        await this.assertStorageSeparated(workspace.root);
         const release = await this.acquireWorkspace(workspace, options.signal);
         try {
-            const skip = await this.store.readTurnCheckpointSkip(workspace, options.sessionId, options.turn, options.turnStartSeq);
+            const skip = await this.store.readTurnCheckpointSkip(workspace.root, options.sessionId, options.turn, options.turnStartSeq);
             return skip === undefined ? undefined : { reason: skip.reason };
         }
         finally {
@@ -321,9 +333,9 @@ export class ChangeLedgerEngine {
     /** Find the prompt-anchored checkpoint captured before one session turn. */
     async findTurnCheckpoint(options) {
         await this.ready;
-        const source = await discoverRepository(options.cwd, options.signal);
+        const source = await discoverWorkspace(options.cwd, this.config, options.signal);
         await this.assertStorageSeparated(source.state.root);
-        const release = await this.acquireWorkspace(source.state.root, options.signal);
+        const release = await this.acquireWorkspace(source.state, options.signal);
         try {
             const manifest = (await this.store.listManifests(source.state.root)).find(point => point.kind === 'turn'
                 && point.sessionId === options.sessionId
@@ -340,9 +352,9 @@ export class ChangeLedgerEngine {
     /** List restore points for the current worktree. */
     async list(options) {
         await this.ready;
-        const source = await discoverRepository(options.cwd, options.signal);
+        const source = await discoverWorkspace(options.cwd, this.config, options.signal);
         await this.assertStorageSeparated(source.state.root);
-        const release = await this.acquireWorkspace(source.state.root, options.signal);
+        const release = await this.acquireWorkspace(source.state, options.signal);
         try {
             const manifests = await this.store.listManifests(source.state.root);
             return manifests
@@ -358,9 +370,9 @@ export class ChangeLedgerEngine {
     /** Compare one restore point with the current worktree. */
     async inspect(options) {
         await this.ready;
-        const source = await discoverRepository(options.cwd, options.signal);
+        const source = await discoverWorkspace(options.cwd, this.config, options.signal);
         await this.assertStorageSeparated(source.state.root);
-        const release = await this.acquireWorkspace(source.state.root, options.signal);
+        const release = await this.acquireWorkspace(source.state, options.signal);
         try {
             const manifest = await this.store.readManifest(source.state.root, options.restorePointId);
             if (manifest.version === 2)
@@ -374,15 +386,17 @@ export class ChangeLedgerEngine {
             const currentEntries = manifest.version === 2 ? current.gitEntries : current.entries;
             if (currentEntries === undefined)
                 throw new ChangeLedgerError('STATE_CORRUPT', 'Git comparison entries are unavailable');
+            const currentState = current.source.state;
+            assertWorkspaceIdentityCompatible(manifest.repository, currentState);
             return {
                 restorePoint: summarize(manifest),
                 currentTreeHash: current.treeHash,
-                currentRepository: current.source.state,
-                ...(current.source.state.head === undefined ? {} : { currentHead: current.source.state.head }),
-                ...(current.source.state.branch === undefined ? {} : { currentBranch: current.source.state.branch }),
-                ...(current.source.state.operation === undefined ? {} : { currentOperation: current.source.state.operation }),
-                headChanged: repositoryHeadChanged(manifest.repository, current.source.state),
-                operationChanged: manifest.repository.operation !== current.source.state.operation,
+                currentRepository: currentState,
+                ...(currentState.type === 'git' && currentState.head !== undefined ? { currentHead: currentState.head } : {}),
+                ...(currentState.type === 'git' && currentState.branch !== undefined ? { currentBranch: currentState.branch } : {}),
+                ...(currentState.type === 'git' && currentState.operation !== undefined ? { currentOperation: currentState.operation } : {}),
+                headChanged: repositoryHeadChanged(manifest.repository, currentState),
+                operationChanged: workspaceOperationChanged(manifest.repository, currentState),
                 changes: diffTrees(manifest.entries, current.entries, manifest.entries, currentEntries),
             };
         }
@@ -394,9 +408,9 @@ export class ChangeLedgerEngine {
     async planRestore(options) {
         await this.ready;
         this.expirePlans();
-        const source = await discoverRepository(options.cwd, options.signal);
+        const source = await discoverWorkspace(options.cwd, this.config, options.signal);
         await this.assertStorageSeparated(source.state.root);
-        const release = await this.acquireWorkspace(source.state.root, options.signal);
+        const release = await this.acquireWorkspace(source.state, options.signal);
         try {
             const manifest = await this.store.readManifest(source.state.root, options.restorePointId);
             if (manifest.version === 2)
@@ -413,8 +427,8 @@ export class ChangeLedgerEngine {
             if (options.expectedCurrentTreeHash !== undefined && options.expectedCurrentTreeHash !== current.treeHash) {
                 throw new ChangeLedgerError('PLAN_STALE', 'workspace changed after inspection; inspect and plan again');
             }
-            if (options.expectedRepository !== undefined && !sameRepositoryFence(options.expectedRepository, current.source.state)) {
-                throw new ChangeLedgerError('PLAN_STALE_REPOSITORY', 'Git repository state changed after inspection; inspect and plan again');
+            if (options.expectedRepository !== undefined && !sameWorkspaceFence(options.expectedRepository, current.source.state)) {
+                throw workspaceStaleError(options.expectedRepository, current.source.state, 'inspection');
             }
             assertRepositoryCompatible(manifest, current.source.state, options.allowHeadChange === true);
             const changes = diffTrees(manifest.entries, current.entries, manifest.entries, currentEntries);
@@ -467,7 +481,7 @@ export class ChangeLedgerEngine {
         this.activePlans.add(plan.id);
         try {
             await this.assertStorageSeparated(plan.workspace);
-            const release = await this.acquireWorkspace(plan.workspace, options.signal);
+            const release = await this.acquireWorkspace(plan.repository, options.signal);
             try {
                 const manifest = await this.store.readManifest(plan.workspace, plan.restorePointId);
                 if (manifest.version === 2)
@@ -590,9 +604,9 @@ export class ChangeLedgerEngine {
         if (options.confirmation !== `DELETE ${options.restorePointId}`) {
             throw new ChangeLedgerError('CONFIRMATION_MISMATCH', `confirmation must exactly equal "DELETE ${options.restorePointId}"`);
         }
-        const source = await discoverRepository(options.cwd, options.signal);
+        const source = await discoverWorkspace(options.cwd, this.config, options.signal);
         await this.assertStorageSeparated(source.state.root);
-        const release = await this.acquireWorkspace(source.state.root, options.signal);
+        const release = await this.acquireWorkspace(source.state, options.signal);
         try {
             const manifest = await this.store.readManifest(source.state.root, options.restorePointId);
             if (await this.store.isReferencedByRecovery(source.state.root, options.restorePointId)) {
@@ -609,9 +623,9 @@ export class ChangeLedgerEngine {
     /** List restore operations that were interrupted or require manual recovery. */
     async listRecovery(options) {
         await this.ready;
-        const source = await discoverRepository(options.cwd, options.signal);
+        const source = await discoverWorkspace(options.cwd, this.config, options.signal);
         await this.assertStorageSeparated(source.state.root);
-        const release = await this.acquireWorkspace(source.state.root, options.signal);
+        const release = await this.acquireWorkspace(source.state, options.signal);
         try {
             return (await this.store.listOperations(source.state.root))
                 .filter((operation) => operation.state === 'interrupted' || operation.state === 'recovery-required')
@@ -698,10 +712,10 @@ export class ChangeLedgerEngine {
         let liveRepository = false;
         let release;
         try {
-            const root = await discoverRepositoryRoot(workspace, signal);
-            if (root === workspace) {
-                await this.assertStorageSeparated(root);
-                release = await this.acquireWorkspace(root, signal);
+            const identity = await discoverWorkspaceIdentity(workspace, signal);
+            if (identity.root === workspace) {
+                await this.assertStorageSeparated(identity.root);
+                release = await this.acquireWorkspace(identity, signal);
                 liveRepository = true;
             }
             else {
@@ -938,11 +952,13 @@ export function resolveConfig(config) {
     };
 }
 function summarize(manifest) {
+    const workspace = manifest.repository;
     return {
         format: manifest.version,
         id: manifest.id,
         kind: manifest.kind,
         workspace: manifest.workspace,
+        workspaceType: workspace.type,
         ...(manifest.sessionId === undefined ? {} : { sessionId: manifest.sessionId }),
         ...(manifest.label === undefined ? {} : { label: manifest.label }),
         ...(manifest.parentRestorePoint === undefined ? {} : { parentRestorePoint: manifest.parentRestorePoint }),
@@ -955,17 +971,29 @@ function summarize(manifest) {
         totalBytes: manifest.totalBytes,
         restoreCount: manifest.restoreCount,
         ...(manifest.lastRestoredAt === undefined ? {} : { lastRestoredAt: manifest.lastRestoredAt }),
-        ...(manifest.repository.head === undefined ? {} : { head: manifest.repository.head }),
-        ...(manifest.repository.branch === undefined ? {} : { branch: manifest.repository.branch }),
-        ...(manifest.repository.operation === undefined ? {} : { operation: manifest.repository.operation }),
-        stagedPathCount: manifest.repository.stagedPaths.length,
+        ...(workspace.type === 'git' && workspace.head !== undefined ? { head: workspace.head } : {}),
+        ...(workspace.type === 'git' && workspace.branch !== undefined ? { branch: workspace.branch } : {}),
+        ...(workspace.type === 'git' && workspace.operation !== undefined ? { operation: workspace.operation } : {}),
+        stagedPathCount: workspace.type === 'git' ? workspace.stagedPaths.length : 0,
         ...(manifest.version === 2 ? { trust: manifest.git.trust } : {}),
     };
 }
-function assertRepositoryCompatible(manifest, current, allowHeadChange) {
-    if (manifest.repository.root !== current.root || manifest.repository.commonDir !== current.commonDir) {
+/** Reject a fence that now describes a different workspace or workspace mode. */
+function assertWorkspaceIdentityCompatible(before, after) {
+    if (before.type !== after.type) {
+        throw new ChangeLedgerError('WORKSPACE_MODE_CHANGED', `workspace mode changed from ${before.type} to ${after.type}`);
+    }
+    if (before.root !== after.root) {
+        throw new ChangeLedgerError('WORKSPACE_CHANGED', 'restore point no longer belongs to this workspace root');
+    }
+    if (before.type === 'git' && after.type === 'git' && before.commonDir !== after.commonDir) {
         throw new ChangeLedgerError('REPOSITORY_CHANGED', 'restore point no longer belongs to this Git worktree');
     }
+}
+function assertRepositoryCompatible(manifest, current, allowHeadChange) {
+    assertWorkspaceIdentityCompatible(manifest.repository, current);
+    if (manifest.repository.type !== 'git' || current.type !== 'git')
+        return;
     if (manifest.repository.operation !== current.operation) {
         throw new ChangeLedgerError('GIT_OPERATION_CHANGED', `Git operation changed from ${manifest.repository.operation ?? 'none'} to ${current.operation ?? 'none'}`);
     }
@@ -974,16 +1002,26 @@ function assertRepositoryCompatible(manifest, current, allowHeadChange) {
     }
 }
 function repositoryHeadChanged(before, after) {
+    if (before.type !== 'git' || after.type !== 'git')
+        return false;
     return before.head !== after.head || before.branch !== after.branch;
 }
+function workspaceOperationChanged(before, after) {
+    if (before.type !== 'git' || after.type !== 'git')
+        return false;
+    return before.operation !== after.operation;
+}
 function assertPlanRepositoryFresh(planned, current) {
-    if (planned.root !== current.root
-        || planned.commonDir !== current.commonDir
-        || planned.head !== current.head
-        || planned.branch !== current.branch
-        || planned.operation !== current.operation) {
-        throw new ChangeLedgerError('PLAN_STALE_REPOSITORY', 'Git repository state changed after restore planning; inspect and plan again');
+    if (!sameWorkspaceFence(planned, current)) {
+        throw workspaceStaleError(planned, current, 'restore planning');
+    }
+}
+/** Stable stale-plan error for the workspace mode that actually drifted. */
+function workspaceStaleError(before, after, phase) {
+    if (before.type === 'git' && after.type === 'git') {
+        return new ChangeLedgerError('PLAN_STALE_REPOSITORY', `Git repository state changed after ${phase}; inspect and plan again`);
     }
+    return new ChangeLedgerError('PLAN_STALE_WORKSPACE', `workspace state changed after ${phase}; inspect and plan again`);
 }
 function assertJournalMatchesManifest(journal, manifest) {
     if (manifest.version !== 2

package/lib/git.js

@@ -37,6 +37,7 @@ export async function discoverRepository(cwd, signal) {
     const operation = await gitOperation(gitDir);
     return {
         state: {
+            type: 'git',
             root,
             commonDir,
             ...(head === undefined ? {} : { head }),
@@ -47,6 +48,47 @@ export async function discoverRepository(cwd, signal) {
         paths,
     };
 }
+/**
+ * Discover the owning Git worktree, or return undefined when `cwd` is not
+ * inside any repository. Every other discovery failure still throws, so a
+ * broken repository never silently degrades into an ordinary directory.
+ * @param cwd - candidate working directory.
+ * @param signal - optional caller cancellation.
+ * @returns the snapshot source, or undefined outside every repository.
+ */
+export async function discoverRepositoryOptional(cwd, signal) {
+    try {
+        return await discoverRepository(cwd, signal);
+    }
+    catch (error) {
+        if (isNotRepositoryError(error))
+            return undefined;
+        throw error;
+    }
+}
+/** Resolve the Git worktree root, or undefined when `cwd` is outside every repository. */
+export async function discoverRepositoryRootOptional(cwd, signal) {
+    try {
+        return await discoverRepositoryRoot(cwd, signal);
+    }
+    catch (error) {
+        if (isNotRepositoryError(error))
+            return undefined;
+        throw error;
+    }
+}
+/**
+ * Whether one discovery failure is Git's plain "not a git repository" verdict.
+ *
+ * `gitEnvironment` pins the C locale, so the message text is stable and this
+ * three-way check (code, exit status, message) cannot swallow a real failure.
+ */
+function isNotRepositoryError(error) {
+    return error instanceof ChangeLedgerError
+        && error.code === 'GIT_COMMAND_FAILED'
+        && gitExitCode(error.cause) === 128
+        && error.message.includes('not a git repository');
+}
 /** Resolve the canonical Git worktree root owning `cwd` without inventorying its files. */
 export async function discoverRepositoryRoot(cwd, signal) {
     const canonicalCwd = await canonicalDirectory(cwd);
@@ -237,6 +279,10 @@ function gitEnvironment(extra) {
         ...extra,
         GIT_OPTIONAL_LOCKS: '0',
         GIT_TERMINAL_PROMPT: '0',
+        // Git's diagnostics are matched for the "not a git repository" verdict that
+        // selects ordinary-directory mode; pin the C locale so that stays stable.
+        LC_ALL: 'C',
+        LANG: 'C',
     };
 }
 function gitExitCode(error) {

package/lib/rewind-host.js

@@ -1,7 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { createDeadline } from './deadline.js';
 import { ChangeLedgerError, errorMessage } from './errors.js';
-import { discoverRepositoryRoot } from './git.js';
+import { discoverWorkspaceRoot } from './workspace.js';
 function getSessionEvents(session) {
     if (!session)
         return [];
@@ -82,7 +82,7 @@ export class TurnCheckpointCoordinator {
             this.skips.delete(key);
             const capture = (async () => {
                 try {
-                    const workspace = await discoverRepositoryRoot(cwd, captureSignal);
+                    const workspace = await discoverWorkspaceRoot(cwd, captureSignal);
                     await this.serializeWorkspace(workspace, captureSignal, async () => {
                         try {
                             await this.engine.createTurnCheckpoint({
@@ -291,11 +291,20 @@ export function createRewindHttpHandler(ctx, engine, coordinator) {
             if (request.method === 'POST') {
                 const body = objectBody(await readBody(request));
                 const mode = body.mode;
-                if (mode !== 'code' && mode !== 'both') {
-                    throw new ChangeLedgerError('INVALID_ARGUMENTS', 'mode must be "code" or "both"');
+                if (mode !== 'code' && mode !== 'both' && mode !== 'messages') {
+                    throw new ChangeLedgerError('INVALID_ARGUMENTS', 'mode must be "code", "both", or "messages"');
                 }
                 const sessionId = requiredText(body.sessionId, 'sessionId');
                 const messageSeq = nonNegativeInteger(body.messageSeq, 'messageSeq');
+                // Messages-only rewind never reads or writes project files, so it needs
+                // neither a checkpoint nor an exclusive workspace: it resolves the turn
+                // boundary straight from the Session log and forks there.
+                if (mode === 'messages') {
+                    const target = messageTarget(await readSession(ctx, sessionId), messageSeq);
+                    const fork = await createConversationRestart(ctx, sessionId, target);
+                    json(response, 200, { status: 'completed', mode, sessionId: fork.sessionId });
+                    return;
+                }
                 const checkpointId = requiredText(body.checkpointId, 'checkpointId');
                 const checkpoint = await checkpointForRequest(ctx, engine, sessionId, messageSeq, checkpointId);
                 const activeSessionIds = await sharedWorkspaceSessions(ctx.agents, checkpoint.cwd);
@@ -512,7 +521,7 @@ async function sharedWorkspaceSessions(agents, cwd) {
     const listed = agents?.list() ?? [];
     if (listed.length === 0)
         return [];
-    const root = await discoverRepositoryRoot(cwd);
+    const root = await discoverWorkspaceRoot(cwd);
     const shared = [];
     for (const agent of listed) {
         if (agent.status !== 'running')
@@ -521,11 +530,11 @@ async function sharedWorkspaceSessions(agents, cwd) {
         if (session.header.cwd === undefined)
             continue;
         try {
-            if (await discoverRepositoryRoot(session.header.cwd) === root)
+            if (await discoverWorkspaceRoot(session.header.cwd) === root)
                 shared.push(session.id);
         }
         catch {
-            // A live Session whose cwd is not a valid Git worktree cannot share this worktree.
+            // A live Session whose cwd cannot be resolved cannot share this workspace.
         }
     }
     return shared.sort();

package/lib/snapshot.js

@@ -2,18 +2,20 @@ import { createHash } from 'node:crypto';
 import { constants } from 'node:fs';
 import { lstat, open, readlink } from 'node:fs/promises';
 import { ChangeLedgerError } from './errors.js';
-import { discoverRepository, sameRepositoryFence } from './git.js';
 import { isNodeError, resolveWorkspacePath } from './path-utils.js';
+import { discoverWorkspace, sameWorkspaceFence } from './workspace.js';
 const COMPARISON_READ_BUDGET_BYTES = 128 * 1024 * 1024;
 /** Capture the current tracked and non-ignored Git working tree. */
 export async function captureTree(options) {
     throwIfAborted(options.signal);
-    const source = await discoverRepository(options.cwd, options.signal);
+    const source = await discoverWorkspace(options.cwd, options.config, options.signal);
     if (source.paths.length > options.config.maxFiles) {
         throw new ChangeLedgerError('TOO_MANY_FILES', `workspace has ${source.paths.length} eligible paths; configured maximum is ${options.config.maxFiles}`);
     }
     const entries = Object.create(null);
-    const gitObjectFormat = options.gitObjectFormat;
+    // Git-object capture only applies to a Git worktree; an ordinary directory
+    // always stores its own content-addressed blobs.
+    const gitObjectFormat = source.state.type === 'git' ? options.gitObjectFormat : undefined;
     const gitCapture = gitObjectFormat === undefined
         ? undefined
         : {
@@ -99,14 +101,20 @@ export async function captureStableTree(options) {
         });
         const second = await captureTree(options);
         if (first.treeHash === second.treeHash
-            && sameRepositoryFence(first.source.state, second.source.state)
-            && arraysEqual(first.source.state.stagedPaths, second.source.state.stagedPaths)
+            && sameWorkspaceFence(first.source.state, second.source.state)
+            && sameStagedPaths(first.source, second.source)
             && arraysEqual(first.source.paths, second.source.paths)) {
             return second;
         }
     }
     throw new ChangeLedgerError('WORKSPACE_CHANGED_DURING_CAPTURE', 'workspace did not remain stable across repeated full-tree captures');
 }
+/** Whether two captures observed the same index state; ordinary directories have none. */
+function sameStagedPaths(left, right) {
+    if (left.state.type !== 'git' || right.state.type !== 'git')
+        return true;
+    return arraysEqual(left.state.stagedPaths, right.state.stagedPaths);
+}
 /** Compute stable path-level differences between two captured trees. */
 export function diffTrees(before, after, comparisonBefore = before, comparisonAfter = after) {
     const paths = [...new Set([...Object.keys(before), ...Object.keys(after)])].sort(comparePaths);

package/lib/types/directory.d.ts

@@ -0,0 +1,10 @@
+import type { DirectoryWorkspaceState, ResolvedChangeLedgerConfig } from './types.js';
+/** Ordinary-directory discovery result plus its eligible path inventory. */
+export interface DirectorySnapshotSource {
+    readonly state: DirectoryWorkspaceState;
+    readonly paths: readonly string[];
+}
+/** Resolve the canonical ordinary directory used as a non-Git workspace root. */
+export declare function discoverDirectoryRoot(cwd: string): Promise<string>;
+/** Enumerate regular files and symlinks in an ordinary directory using rewind ignore rules. */
+export declare function discoverDirectory(cwd: string, config: Pick<ResolvedChangeLedgerConfig, 'maxFiles' | 'maxFileBytes'>, signal?: AbortSignal): Promise<DirectorySnapshotSource>;

package/lib/types/engine.d.ts

@@ -19,6 +19,12 @@ export declare class ChangeLedgerEngine {
     /** Wait for startup reconciliation and return the number of interrupted journals found. */
     initialize(): Promise<number>;
     private initializeStore;
+    /**
+     * Acquire the exclusive lock for one workspace.
+     *
+     * A Git worktree also binds the shared per-worktree lock derived from its Git
+     * identity; an ordinary directory owns only the durable directory lock.
+     */
     private acquireWorkspace;
     private reconcileGitCheckpointJournals;
     private publishGitManifest;

package/lib/types/git.d.ts

@@ -1,7 +1,7 @@
-import type { RepositoryState } from './types.js';
+import type { GitWorkspaceState } from './types.js';
 /** Repository discovery result plus the eligible path inventory. */
 export interface RepositorySnapshotSource {
-    readonly state: RepositoryState;
+    readonly state: GitWorkspaceState;
     readonly paths: readonly string[];
 }
 /** Durable identity and shared lock location for one concrete Git worktree. */
@@ -14,6 +14,17 @@ export interface GitWorktreeIdentity {
 }
 /** Discover the Git worktree owning `cwd` and enumerate tracked/non-ignored paths. */
 export declare function discoverRepository(cwd: string, signal?: AbortSignal): Promise<RepositorySnapshotSource>;
+/**
+ * Discover the owning Git worktree, or return undefined when `cwd` is not
+ * inside any repository. Every other discovery failure still throws, so a
+ * broken repository never silently degrades into an ordinary directory.
+ * @param cwd - candidate working directory.
+ * @param signal - optional caller cancellation.
+ * @returns the snapshot source, or undefined outside every repository.
+ */
+export declare function discoverRepositoryOptional(cwd: string, signal?: AbortSignal): Promise<RepositorySnapshotSource | undefined>;
+/** Resolve the Git worktree root, or undefined when `cwd` is outside every repository. */
+export declare function discoverRepositoryRootOptional(cwd: string, signal?: AbortSignal): Promise<string | undefined>;
 /** 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. */
@@ -21,7 +32,7 @@ export declare function ensureGitWorktreeIdentity(cwd: string, signal?: AbortSig
 /** 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;
+export declare function sameRepositoryFence(left: GitWorkspaceState, right: GitWorkspaceState): 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;
@@ -42,4 +53,4 @@ export declare function runGitBuffer(cwd: string, args: readonly string[], signa
     readonly maxBuffer?: number;
 }): Promise<Buffer>;
 /** Return the Git metadata directory for diagnostics. */
-export declare function gitMetadataParent(state: RepositoryState): string;
+export declare function gitMetadataParent(state: GitWorkspaceState): string;

package/lib/types/snapshot.d.ts

@@ -1,9 +1,9 @@
-import { type RepositorySnapshotSource } from './git.js';
 import type { LedgerStore } from './store.js';
+import { type WorkspaceSnapshotSource } from './workspace.js';
 import type { ResolvedChangeLedgerConfig, SnapshotEntry, WorkspaceChange } from './types.js';
 /** One captured tree, optionally persisted into the blob store. */
 export interface CapturedTree {
-    readonly source: RepositorySnapshotSource;
+    readonly source: WorkspaceSnapshotSource;
     readonly entries: Readonly<Record<string, SnapshotEntry>>;
     readonly gitEntries?: Readonly<Record<string, SnapshotEntry>>;
     readonly treeHash: string;

package/lib/types/types.d.ts

@@ -26,7 +26,8 @@ export interface SymlinkSnapshotEntry {
 /** One path captured by a restore point. */
 export type SnapshotEntry = FileSnapshotEntry | SymlinkSnapshotEntry;
 /** Git facts that fence a restore point to the repository state it observed. */
-export interface RepositoryState {
+export interface GitWorkspaceState {
+    readonly type: 'git';
     readonly root: string;
     readonly commonDir: string;
     readonly head?: string;
@@ -34,6 +35,15 @@ export interface RepositoryState {
     readonly operation?: string;
     readonly stagedPaths: readonly string[];
 }
+/** Identity of an ordinary directory workspace captured without Git. */
+export interface DirectoryWorkspaceState {
+    readonly type: 'directory';
+    readonly root: string;
+}
+/** Workspace facts that fence a restore point to the state it observed. */
+export type WorkspaceState = GitWorkspaceState | DirectoryWorkspaceState;
+/** @deprecated Use `WorkspaceState`; the durable manifest field keeps its original name. */
+export type RepositoryState = WorkspaceState;
 /** Why a restore point exists. */
 export type RestorePointKind = 'user' | 'rescue' | 'turn';
 /** Durable workspace restore point. */
@@ -77,8 +87,10 @@ export interface GitCheckpointMetadata {
     readonly newlyStoredBytes: number;
 }
 /** Automatic turn checkpoint whose content is stored in the repository object database. */
-export interface RestorePointManifestV2 extends Omit<RestorePointManifestV1, 'version' | 'treeHash'> {
+export interface RestorePointManifestV2 extends Omit<RestorePointManifestV1, 'version' | 'treeHash' | 'repository'> {
     readonly version: typeof GIT_CHECKPOINT_FORMAT_VERSION;
+    /** Git-native checkpoints only exist for a Git worktree. */
+    readonly repository: GitWorkspaceState;
     /** Deterministic sidecar identity; Git tree integrity is verified separately. */
     readonly treeHash: string;
     readonly git: GitCheckpointMetadata;
@@ -110,6 +122,7 @@ export interface RestorePointSummary {
     readonly id: RestorePointId;
     readonly kind: RestorePointKind;
     readonly workspace: string;
+    readonly workspaceType: WorkspaceState['type'];
     readonly sessionId?: string;
     readonly label?: string;
     readonly parentRestorePoint?: RestorePointId;