@anionex/dsh-turn-rewind 0.2.3 → 0.3.1

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/rewind-host.d.ts

@@ -8,11 +8,22 @@ interface SessionEventLike {
 interface SessionHeaderLike {
     readonly cwd?: string;
     readonly parentSession?: string;
+    /**
+     * Fork-inherited prefix length on DSH releases before 0.1.5. 0.1.5 deleted the
+     * field — a stored header that still carries it is rejected outright — and moved
+     * the same quantity to {@link SessionLike.inheritedEventCount}.
+     */
     readonly seedLength?: number;
 }
 interface SessionLike {
     readonly id: string;
     readonly header: SessionHeaderLike;
+    /**
+     * Exact number of leading events inherited from the fork parent, as reported by
+     * DSH 0.1.5+ on the live session and on the stored session-log snapshot. `0` —
+     * never `undefined` — for a session with no inherited prefix.
+     */
+    readonly inheritedEventCount?: number;
     readonly events?: readonly SessionEventLike[];
     snapshotEvents?(fromSeq?: number, toSeqExclusive?: number): readonly SessionEventLike[];
 }
@@ -36,6 +47,7 @@ interface SessionQueryLike {
     readSession(id: string): Promise<{
         readonly session: SessionHeaderLike;
         readonly events: readonly SessionEventLike[];
+        readonly inheritedEventCount?: number;
     }>;
 }
 interface HttpRequestLike {

package/lib/types/settings.d.ts

@@ -6,8 +6,16 @@ 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">;
+/**
+ * Namespace join key shared by the host section and the browser settings card.
+ *
+ * DSH 0.1.5 removed the `settingsNamespace` helper and made `SettingsNamespace`
+ * a compile-time-only brand, so a plain lowercase literal is the entire runtime
+ * value — the upstream convention (`const CHAT_SETTINGS_NAMESPACE = 'ui-chat'`).
+ * The literal satisfies 0.1.5's registration grammar `/^[a-z][a-z0-9-]*$/` and is
+ * the exact key the browser card binds through `ctx.settingsScope.bind`.
+ */
+export declare const TURN_REWIND_SETTINGS_NAMESPACE = "turn-rewind";
 /** Every runtime-tunable field of {@link ChangeLedgerConfig}; `storageDir` stays config-layer only. */
 export interface TurnRewindSettings {
     /** Maximum user and rescue restore points retained per workspace. */
@@ -40,5 +48,9 @@ export declare const TurnRewindSettingsSchema: z<TurnRewindSettings>;
  * 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.
+ *
+ * `settings` is an optional service, so the whole wiring stays behind
+ * `ctx.inject(['settings'], …)`: a host without a provider keeps running on the
+ * composition entry alone.
  */
 export declare function installTurnRewindSettings(ctx: Context, config: ChangeLedgerConfig, engine: ChangeLedgerEngine): void;

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;

package/lib/types/workspace.d.ts

@@ -0,0 +1,37 @@
+import { type DirectorySnapshotSource } from './directory.js';
+import { type RepositorySnapshotSource } from './git.js';
+import type { ResolvedChangeLedgerConfig, WorkspaceState } from './types.js';
+/** Eligible snapshot source for either supported workspace mode. */
+export type WorkspaceSnapshotSource = RepositorySnapshotSource | DirectorySnapshotSource;
+/**
+ * Discover the owning Git worktree, or treat `cwd` itself as an ordinary
+ * directory when it is not inside any repository.
+ * @param cwd - working directory the Session runs in.
+ * @param config - capture limits applied to ordinary-directory enumeration.
+ * @param signal - optional caller cancellation.
+ * @returns the snapshot source for the owning workspace.
+ */
+export declare function discoverWorkspace(cwd: string, config: Pick<ResolvedChangeLedgerConfig, 'maxFiles' | 'maxFileBytes'>, signal?: AbortSignal): Promise<WorkspaceSnapshotSource>;
+/** Workspace mode and root resolved without inventorying any files. */
+export interface WorkspaceIdentity {
+    readonly type: WorkspaceState['type'];
+    readonly root: string;
+}
+/**
+ * Resolve the workspace mode and root without inventorying files, for callers
+ * that only need to address the workspace (locks, skip markers, storage purge).
+ * @param cwd - working directory the Session runs in.
+ * @param signal - optional caller cancellation.
+ * @returns the workspace mode and canonical root.
+ */
+export declare function discoverWorkspaceIdentity(cwd: string, signal?: AbortSignal): Promise<WorkspaceIdentity>;
+/** Resolve the workspace root without inventorying its files. */
+export declare function discoverWorkspaceRoot(cwd: string, signal?: AbortSignal): Promise<string>;
+/**
+ * Whether two fences still describe the same workspace.
+ *
+ * Git workspaces keep the full repository fence (HEAD, branch, operation);
+ * ordinary directories only own their canonical root, so a moved or recreated
+ * root is the only thing that can invalidate them.
+ */
+export declare function sameWorkspaceFence(left: WorkspaceState, right: WorkspaceState): boolean;

package/lib/validate.js

@@ -99,7 +99,9 @@ export function parseManifest(value) {
         return { version, ...common };
     if (restorePointKind !== 'turn')
         corrupt('Git-native v2 restore points are automatic turn checkpoints');
-    return { version, ...common, git: parseGitCheckpoint(record.git, id) };
+    if (repository.type !== 'git')
+        corrupt('Git-native v2 restore points must fence a Git workspace');
+    return { version, ...common, repository, git: parseGitCheckpoint(record.git, id) };
 }
 /** Parse an untrusted durable restore-operation journal. */
 export function parseOperation(value) {
@@ -155,9 +157,28 @@ export function validateBlobHash(value) {
     }
     return value;
 }
+/**
+ * Parse the durable workspace fence of one manifest.
+ *
+ * A missing `type` is the only legacy interpretation: manifests written before
+ * ordinary-directory support are always Git workspaces and are upgraded in
+ * memory. Directory fences must not carry Git-only fields.
+ * @param value - persisted `repository` field.
+ * @returns the validated workspace state.
+ */
 function parseRepository(value) {
     const record = objectRecord(value, 'repository state');
     const root = absoluteString(record, 'root');
+    if (record.type === 'directory') {
+        for (const key of ['commonDir', 'head', 'branch', 'operation', 'stagedPaths']) {
+            if (record[key] !== undefined)
+                corrupt(`directory workspace state must not contain ${key}`);
+        }
+        return { type: 'directory', root };
+    }
+    if (record.type !== undefined && record.type !== 'git') {
+        corrupt('workspace state type must be "git" or "directory"');
+    }
     const commonDir = absoluteString(record, 'commonDir');
     const head = optionalHash(record, 'head');
     const branch = optionalString(record, 'branch');
@@ -167,6 +188,7 @@ function parseRepository(value) {
         corrupt('repository stagedPaths must be an array');
     const stagedPaths = stagedValue.map((path) => validateRelativePath(requireString(path, 'staged path')));
     return {
+        type: 'git',
         root,
         commonDir,
         ...(head === undefined ? {} : { head }),

package/lib/workspace.js

@@ -0,0 +1,45 @@
+import { discoverDirectory, discoverDirectoryRoot } from './directory.js';
+import { discoverRepositoryOptional, discoverRepositoryRootOptional, sameRepositoryFence, } from './git.js';
+/**
+ * Discover the owning Git worktree, or treat `cwd` itself as an ordinary
+ * directory when it is not inside any repository.
+ * @param cwd - working directory the Session runs in.
+ * @param config - capture limits applied to ordinary-directory enumeration.
+ * @param signal - optional caller cancellation.
+ * @returns the snapshot source for the owning workspace.
+ */
+export async function discoverWorkspace(cwd, config, signal) {
+    const repository = await discoverRepositoryOptional(cwd, signal);
+    return repository ?? discoverDirectory(cwd, config, signal);
+}
+/**
+ * Resolve the workspace mode and root without inventorying files, for callers
+ * that only need to address the workspace (locks, skip markers, storage purge).
+ * @param cwd - working directory the Session runs in.
+ * @param signal - optional caller cancellation.
+ * @returns the workspace mode and canonical root.
+ */
+export async function discoverWorkspaceIdentity(cwd, signal) {
+    const root = await discoverRepositoryRootOptional(cwd, signal);
+    return root === undefined
+        ? { type: 'directory', root: await discoverDirectoryRoot(cwd) }
+        : { type: 'git', root };
+}
+/** Resolve the workspace root without inventorying its files. */
+export async function discoverWorkspaceRoot(cwd, signal) {
+    return (await discoverWorkspaceIdentity(cwd, signal)).root;
+}
+/**
+ * Whether two fences still describe the same workspace.
+ *
+ * Git workspaces keep the full repository fence (HEAD, branch, operation);
+ * ordinary directories only own their canonical root, so a moved or recreated
+ * root is the only thing that can invalidate them.
+ */
+export function sameWorkspaceFence(left, right) {
+    if (left.type !== right.type || left.root !== right.root)
+        return false;
+    if (left.type === 'directory' || right.type === 'directory')
+        return true;
+    return sameRepositoryFence(left, right);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anionex/dsh-turn-rewind",
-  "version": "0.2.3",
+  "version": "0.3.1",
   "description": "Turn-level conversation and workspace rewind for DeepSeek Harness, powered by a persistent Change Ledger",
   "repository": {
     "type": "git",
@@ -54,8 +54,10 @@
     "client": {
       "platform": "web",
       "inject": [
-        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-ui-renderer",
+        "@deepseek-ai/dsh-api-session-controller",
         "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-settings",
         "@deepseek-ai/dsh-client-ui-settings-plugins"
       ]
     },
@@ -68,7 +70,10 @@
         "0.1.2-alpha.1": "compatible",
         "0.1.2-alpha.3": "compatible",
         "0.1.2-alpha.4": "compatible",
-        "0.1.2-alpha.5": "compatible"
+        "0.1.2-alpha.5": "compatible",
+        "0.1.5-alpha.1": "compatible",
+        "0.1.5-alpha.2": "compatible",
+        "0.1.5-rc.1": "compatible"
       },
       "profiles": [
         "web"
@@ -94,12 +99,12 @@
   "license": "BSD-3-Clause",
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-settings": ">=0.1.0-rc.8 <0.2.0",
+    "@deepseek-ai/dsh-settings": ">=0.1.0-rc.8 <0.2.0 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1",
     "@deepseek-ai/schemastery": "^3.18.1"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-settings": ">=0.1.0-rc.8 <0.2.0",
+    "@deepseek-ai/dsh-settings": ">=0.1.0-rc.8 <0.2.0 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1",
     "@deepseek-ai/schemastery": "^3.18.1",
     "@types/node": "^24.0.0",
     "@types/react": "18.3.28",
@@ -109,5 +114,8 @@
   "engines": {
     "node": "^22.19.0 || >=24.0.0"
   },
-  "packageManager": "pnpm@11.7.0"
+  "packageManager": "pnpm@11.7.0",
+  "dependencies": {
+    "ignore": "^7.0.9"
+  }
 }

package/src/client/index.tsx

@@ -269,8 +269,15 @@ export function selectRewindMessage(node: ConversationNodeLike): RewindMatch | n
   return { messageSeq: node.seq, promptText }
 }
 
-/** Browser plugin entry: bridge every direct user-message action row to the rewind UI. */
-export const inject = ['slots', 'sessions', 'conversation']
+/**
+ * Browser plugin entry: bridge every direct user-message action row to the rewind UI.
+ *
+ * Every service read on `ctx` must be declared here: Cordis throws while reading an
+ * undeclared service off the context proxy, before optional chaining can apply.
+ * `settingsScope` is provided by `@deepseek-ai/dsh-client-ui-settings` and may be
+ * absent, which is what `ctx.settingsScope?.bind(…)` below relies on.
+ */
+export const inject = ['slots', 'sessions', 'conversation', 'settingsScope']
 export function apply(ctx: ClientContextLike): void {
   ctx.effect(() => {
     if (document.querySelector(`style[data-plugin-css="${STYLE_ID}"]`) !== null) return () => {}
@@ -1064,6 +1071,41 @@ export function selectRewindMessageTarget(value: RewindNodeLike): { readonly mat
   }
 }
 
+/** CSS-module class every DSH message action row matches (`<hash>_actions`). */
+const ACTIONS_SELECTOR = '[class*="actions"]'
+/**
+ * Wrapper that owned the hover chrome and the action row before DSH 0.1.5. The
+ * attribute is gone in 0.1.5 — the message row itself is the hover root now — so it
+ * is only a fallback for older clients.
+ */
+const LEGACY_HOVER_ROOT_SELECTOR = '[data-time-hover-root="true"]'
+
+/** Query one descendant, tolerating a row double that implements no `querySelector`. */
+function queryInside(root: Element, selector: string): Element | null {
+  const query = (root as Partial<Element>).querySelector
+  return typeof query === 'function' ? query.call(root, selector) : null
+}
+
+/**
+ * Resolve the container one rewind button is portalled into.
+ *
+ * DSH 0.1.5 renders the copy/branch icon row (`MessageIconActions`, class
+ * `<hash>_actions`) as a direct child of the user-message row and dropped
+ * `data-time-hover-root`; older clients nested that row under the removed wrapper.
+ * Both shapes are tried, current first. There is no official slot for user-message
+ * actions in 0.1.5 — only `conversation.chat.assistant-actions`, for finalized
+ * assistant turns — so this bridge stays DOM-based.
+ * @param row - the `[data-chat-flow-kind="user"]` row owning one message.
+ * @returns the actions container, or null when the row exposes none.
+ */
+function findActionsContainer(row: Element): Element | null {
+  const direct = queryInside(row, ACTIONS_SELECTOR)
+  if (direct !== null) return direct
+  const legacy = queryInside(row, LEGACY_HOVER_ROOT_SELECTOR)
+  if (legacy === null) return null
+  return queryInside(legacy, ACTIONS_SELECTOR) ?? legacy.lastElementChild
+}
+
 function collectPortalTargets(nodes: readonly RewindNodeLike[]): readonly RewindPortalTarget[] {
   const rows = new Map<string, HTMLElement>()
   for (const element of Array.from(document.querySelectorAll<HTMLElement>(
@@ -1077,11 +1119,7 @@ function collectPortalTargets(nodes: readonly RewindNodeLike[]): readonly Rewind
     const target = selectRewindMessageTarget(value)
     if (target === null) continue
     const row = rows.get(target.rowKey)
-    const messageRoot = row?.querySelector?.<HTMLElement>('[data-time-hover-root="true"]')
-    // Match the actions container by class or last child element
-    const actions = (typeof messageRoot?.querySelector === 'function'
-      ? messageRoot.querySelector<HTMLElement>('[class*="actions"]')
-      : undefined) ?? messageRoot?.lastElementChild
+    const actions = row === undefined ? null : findActionsContainer(row)
     if (!(actions instanceof HTMLElement)) continue
     targets.push({ container: actions, matched: target.matched })
   }
@@ -1214,9 +1252,12 @@ function friendlyError(error: unknown): string {
     case 'REWIND_ENDPOINT_UNAVAILABLE': return '回退服务没有响应。请确认 @anionex/dsh-turn-rewind 已挂载到当前 DSH，并重启 DSH 后重试。'
     case 'REWIND_INVALID_RESPONSE': return '回退服务返回了无法解析的内容。请重启 DSH 后重试。'
     case 'PLAN_STALE': return '项目文件在检查后又发生了变化。为避免覆盖新修改，请重新检查后再恢复。'
+    case 'PLAN_STALE_WORKSPACE': return '项目文件在检查后又发生了变化。为避免覆盖新修改，请重新检查后再恢复。'
     case 'PLAN_STALE_REPOSITORY': return 'Git 状态在检查后又发生了变化，恢复已失效。请重新检查后再试。'
     case 'WORKSPACE_IN_USE': return '这个项目目录还有别的对话正在运行。请等那些对话结束或停止后，再重新检查。'
     case 'WORKSPACE_LOCKED': return '另一个恢复操作正在处理这个项目目录。请等待它完成后重新检查。'
+    case 'WORKSPACE_CHANGED': return '这个项目目录已经不在原来的位置，旧的回退点无法再使用。'
+    case 'WORKSPACE_MODE_CHANGED': return '这个项目目录的工作区类型变了（例如从普通目录变成了 Git 仓库）。旧的回退点不再适用，请重新发送一条消息生成新的回退点。'
     case 'HEAD_CHANGED': return '项目的提交或分支已发生变化。为避免覆盖新改动，请重新检查后再恢复。'
     case 'REPOSITORY_CHANGED': return '这个项目目录已不属于原来的 Git 工作区，无法恢复。'
     case 'GIT_OPERATION_CHANGED': return 'Git 正在执行其他操作。请先完成或取消该操作，再重新检查。'
@@ -1248,6 +1289,10 @@ export function explainCheckpointFailure(message: string): string {
     case 'SNAPSHOT_TOO_LARGE':
     case 'TOO_MANY_FILES':
       return '本轮有文件超过检查点的大小或数量上限，没有保存文件检查点。仍可只回溯消息。'
+    case 'UNSUPPORTED_FILE_TYPE':
+      return '项目目录里有无法保存的特殊文件（如 socket、设备文件、FIFO），没有保存文件检查点。仍可只回溯消息。'
+    case 'IGNORE_FILE_INVALID':
+      return '项目目录里的 .dsh-rewindignore 内容无效，没有保存文件检查点。修正该文件后可重新发送消息。'
     case 'INVALID_PATH':
       return '项目目录里有无法安全保存的路径（例如嵌套的独立 Git 仓库），没有保存文件检查点。仍可只回溯消息。'
     default:

package/src/directory.ts

@@ -0,0 +1,194 @@
+import type { BigIntStats } from 'node:fs'
+import { lstat, readFile, readdir, realpath } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+import ignore, { type Ignore } from 'ignore'
+import { ChangeLedgerError } from './errors.js'
+import { canonicalDirectory, isNodeError, isWithin } from './path-utils.js'
+import type { DirectoryWorkspaceState, ResolvedChangeLedgerConfig } from './types.js'
+
+const IGNORE_FILE = '.dsh-rewindignore'
+const DEFAULT_IGNORE_PATTERNS = ['.git', 'node_modules'] as const
+
+/** 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 async function discoverDirectoryRoot(cwd: string): Promise<string> {
+  return canonicalDirectory(cwd)
+}
+
+/** Enumerate regular files and symlinks in an ordinary directory using rewind ignore rules. */
+export async function discoverDirectory(
+  cwd: string,
+  config: Pick<ResolvedChangeLedgerConfig, 'maxFiles' | 'maxFileBytes'>,
+  signal?: AbortSignal,
+): Promise<DirectorySnapshotSource> {
+  const root = await discoverDirectoryRoot(cwd)
+  const matcher = await loadIgnoreMatcher(root, config.maxFileBytes, signal)
+  const paths: string[] = []
+  await walkDirectory(root, root, '', matcher, paths, config.maxFiles, signal)
+  paths.sort(comparePaths)
+  return { state: { type: 'directory', root }, paths }
+}
+
+/**
+ * Read `.dsh-rewindignore` when present and combine it with the built-in
+ * exclusions. The built-in patterns are added last so user negation rules can
+ * never re-include the plugin's own metadata or dependency trees.
+ */
+async function loadIgnoreMatcher(root: string, maxFileBytes: number, signal?: AbortSignal): Promise<Ignore> {
+  const matcher = ignore()
+  const ignorePath = join(root, IGNORE_FILE)
+  throwIfAborted(signal)
+  let before: BigIntStats
+  try {
+    before = await lstat(ignorePath, { bigint: true })
+  } catch (error) {
+    if (isNodeError(error, 'ENOENT')) {
+      matcher.add(DEFAULT_IGNORE_PATTERNS)
+      return matcher
+    }
+    throw error
+  }
+  if (!before.isFile()) {
+    throw new ChangeLedgerError('IGNORE_FILE_INVALID', `${IGNORE_FILE} must be a regular file when present`)
+  }
+  if (before.size > BigInt(maxFileBytes)) {
+    throw new ChangeLedgerError(
+      'FILE_TOO_LARGE',
+      `${JSON.stringify(IGNORE_FILE)} is ${before.size.toString()} bytes; configured per-file maximum is ${maxFileBytes}`,
+    )
+  }
+  const content = await readFile(ignorePath, 'utf8')
+  let after: BigIntStats
+  try {
+    after = await lstat(ignorePath, { bigint: true })
+  } catch (error) {
+    if (isNodeError(error, 'ENOENT')) {
+      throw new ChangeLedgerError('WORKSPACE_CHANGED_DURING_CAPTURE', `${IGNORE_FILE} disappeared while its rules were being read`)
+    }
+    throw error
+  }
+  if (!sameStat(before, after)) {
+    throw new ChangeLedgerError('WORKSPACE_CHANGED_DURING_CAPTURE', `${IGNORE_FILE} changed while its rules were being read`)
+  }
+  try {
+    matcher.add(content)
+  } catch (error) {
+    throw new ChangeLedgerError('IGNORE_FILE_INVALID', `${IGNORE_FILE} contains invalid ignore rules`, { cause: error })
+  }
+  matcher.add(DEFAULT_IGNORE_PATTERNS)
+  return matcher
+}
+
+/** Walk one ordinary directory without following symlinks, rejecting unstable trees. */
+async function walkDirectory(
+  root: string,
+  directory: string,
+  directoryPath: string,
+  matcher: Ignore,
+  paths: string[],
+  maxFiles: number,
+  signal?: AbortSignal,
+): Promise<void> {
+  throwIfAborted(signal)
+  const before = await lstat(directory, { bigint: true })
+  await assertSafeDirectory(root, directory, before)
+  const entries = await readdir(directory, { withFileTypes: true })
+  const after = await lstat(directory, { bigint: true })
+  if (!sameStat(before, after)) {
+    throw new ChangeLedgerError(
+      'WORKSPACE_CHANGED_DURING_CAPTURE',
+      `directory changed while being enumerated: ${JSON.stringify(directoryPath || '.')}`,
+    )
+  }
+
+  entries.sort((left, right) => comparePaths(left.name, right.name))
+  for (const entry of entries) {
+    throwIfAborted(signal)
+    await assertSafeDirectory(root, directory, after)
+    const path = directoryPath === '' ? entry.name : `${directoryPath}/${entry.name}`
+    const target = join(directory, entry.name)
+    let info: BigIntStats
+    try {
+      info = await lstat(target, { bigint: true })
+    } catch (error) {
+      if (isNodeError(error, 'ENOENT')) continue
+      throw error
+    }
+    if (info.isDirectory() && !info.isSymbolicLink()) {
+      if (matcher.ignores(`${path}/`)) continue
+      await walkDirectory(root, target, path, matcher, paths, maxFiles, signal)
+      continue
+    }
+    if (path !== IGNORE_FILE && matcher.ignores(path)) continue
+    if (!info.isFile() && !info.isSymbolicLink()) {
+      throw new ChangeLedgerError(
+        'UNSUPPORTED_FILE_TYPE',
+        `ordinary-directory path is not a regular file or symlink: ${JSON.stringify(path)}`,
+      )
+    }
+    paths.push(path)
+    if (paths.length > maxFiles) {
+      throw new ChangeLedgerError(
+        'TOO_MANY_FILES',
+        `workspace has more than ${maxFiles} eligible paths; latest path is ${JSON.stringify(path)}`,
+      )
+    }
+  }
+}
+
+/**
+ * Re-prove that one traversed directory is still the same real directory inside
+ * the workspace root, so a swapped symlink or moved ancestor cannot redirect
+ * the inventory outside it.
+ */
+async function assertSafeDirectory(root: string, directory: string, expected: BigIntStats): Promise<void> {
+  if (!expected.isDirectory() || expected.isSymbolicLink()) {
+    throw new ChangeLedgerError('SYMLINK_PARENT', `directory traversal reached a symbolic link: ${JSON.stringify(directory)}`)
+  }
+  let canonical: string
+  try {
+    canonical = await realpath(directory)
+  } catch (error) {
+    if (isNodeError(error, 'ENOENT') || isNodeError(error, 'ELOOP')) {
+      throw new ChangeLedgerError('WORKSPACE_CHANGED_DURING_CAPTURE', `directory changed during traversal: ${JSON.stringify(directory)}`)
+    }
+    throw error
+  }
+  if (canonical !== resolve(directory) || !isWithin(root, canonical)) {
+    throw new ChangeLedgerError('UNSAFE_TARGET', `directory traversal escaped the workspace: ${JSON.stringify(directory)}`)
+  }
+  let current: BigIntStats
+  try {
+    current = await lstat(directory, { bigint: true })
+  } catch (error) {
+    if (isNodeError(error, 'ENOENT')) {
+      throw new ChangeLedgerError('WORKSPACE_CHANGED_DURING_CAPTURE', `directory disappeared during traversal: ${JSON.stringify(directory)}`)
+    }
+    throw error
+  }
+  if (!sameStat(expected, current)) {
+    throw new ChangeLedgerError('WORKSPACE_CHANGED_DURING_CAPTURE', `directory changed during traversal: ${JSON.stringify(directory)}`)
+  }
+}
+
+function sameStat(left: BigIntStats, right: BigIntStats): boolean {
+  return left.dev === right.dev
+    && left.ino === right.ino
+    && left.mode === right.mode
+    && left.size === right.size
+    && left.mtimeNs === right.mtimeNs
+    && left.ctimeNs === right.ctimeNs
+}
+
+function throwIfAborted(signal?: AbortSignal): void {
+  if (signal?.aborted === true) throw signal.reason
+}
+
+function comparePaths(left: string, right: string): number {
+  return Buffer.from(left).compare(Buffer.from(right))
+}