@anionex/dsh-turn-rewind 0.3.2 → 0.3.4

package/lib/rewind-host.js

@@ -253,6 +253,11 @@ export function createRewindHttpHandler(ctx, engine, coordinator) {
                 const changes = inspection.changes.slice(offset, offset + limit);
                 const common = {
                     status: 'ready', sessionId, messageSeq, turn: checkpoint.turn, checkpointId: checkpoint.id,
+                    // A restore point that could not store every eligible path stays usable;
+                    // the browser shows what was left out instead of blocking the rewind.
+                    skippedCount: inspection.restorePoint.skippedCount,
+                    ...(inspection.restorePoint.skipped === undefined ? {} : { skipped: inspection.restorePoint.skipped }),
+                    ...(inspection.restorePoint.truncated === undefined ? {} : { captureTruncated: inspection.restorePoint.truncated }),
                     turnStartSeq: checkpoint.turnStartSeq,
                     totalChanges: inspection.changes.length,
                     changes: changes.map(change => ({ path: change.path, kind: change.kind })),
@@ -452,14 +457,18 @@ async function createConversationRestart(ctx, sourceId, checkpoint) {
         || current.previousTurnEndSeq !== checkpoint.previousTurnEndSeq) {
         throw new ChangeLedgerError('PLAN_STALE', 'the session no longer contains the selected message boundary');
     }
-    const controller = ctx.sessionController;
+    // Cordis throws when a context reads a service property it did not inject, and
+    // no single inject list covers both carriers: 0.1.1 provides `apiProxy` while
+    // 0.1.2-alpha provides `sessionController`. `ctx.get` is the optional accessor
+    // that returns undefined instead of failing the request.
+    const controller = ctx.get('sessionController');
     if (controller !== undefined) {
         const created = checkpoint.previousTurnEndSeq === undefined
             ? await controller.create({ cwd: checkpoint.cwd })
             : await controller.fork({ sessionId: sourceId, atSeq: checkpoint.previousTurnEndSeq });
         return { sessionId: requiredText(created.sessionId, 'sessionController sessionId') };
     }
-    const apiProxy = ctx.apiProxy;
+    const apiProxy = ctx.get('apiProxy');
     if (apiProxy === undefined) {
         throw new ChangeLedgerError('CONVERSATION_REWIND_FAILED', 'this DSH host exposes neither sessionController nor apiProxy, so a new conversation cannot be created');
     }

package/lib/snapshot.js

@@ -5,13 +5,29 @@ import { ChangeLedgerError } from './errors.js';
 import { isNodeError, resolveWorkspacePath } from './path-utils.js';
 import { discoverWorkspace, sameWorkspaceFence } from './workspace.js';
 const COMPARISON_READ_BUDGET_BYTES = 128 * 1024 * 1024;
+const MAX_RECORDED_SKIPS = 50;
 /** Capture the current tracked and non-ignored Git working tree. */
 export async function captureTree(options) {
     throwIfAborted(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}`);
-    }
+    // Limits never discard an entire restore point: an over-limit path is left out
+    // and reported, and the remaining eligible paths are still captured. A restore
+    // only ever rewrites captured paths, so a partial point stays safe to apply.
+    const skipped = [...source.skipped];
+    let skippedCount = source.skippedCount;
+    let truncated = source.truncated;
+    const recordSkip = (path, reason) => {
+        skippedCount += 1;
+        if (skipped.length < MAX_RECORDED_SKIPS)
+            skipped.push({ path, reason });
+        else
+            truncated ??= reason === 'snapshot-limit' ? 'snapshot-limit' : 'file-limit';
+    };
+    const paths = source.paths.length > options.config.maxFiles
+        ? source.paths.slice(0, options.config.maxFiles)
+        : source.paths;
+    if (source.paths.length > options.config.maxFiles)
+        truncated ??= 'file-limit';
     const entries = Object.create(null);
     // Git-object capture only applies to a Git worktree; an ordinary directory
     // always stores its own content-addressed blobs.
@@ -23,16 +39,40 @@ export async function captureTree(options) {
             entries: Object.create(null),
         };
     let totalBytes = 0;
+    let budgetSpent = false;
     const capturePath = async (path) => {
         throwIfAborted(options.signal);
-        const entry = await captureEntry(source.state.root, path, options.config.maxFileBytes, options.signal);
+        if (budgetSpent) {
+            // The aggregate budget is gone, but the path is still recorded so a
+            // restore can prove this point never observed it.
+            recordSkip(path, 'snapshot-limit');
+            return;
+        }
+        let entry;
+        try {
+            entry = await captureEntry(source.state.root, path, options.config.maxFileBytes, options.signal);
+        }
+        catch (error) {
+            if (error instanceof ChangeLedgerError && error.code === 'FILE_TOO_LARGE') {
+                recordSkip(path, 'file-too-large');
+                return;
+            }
+            if (error instanceof ChangeLedgerError && error.code === 'UNSUPPORTED_FILE_TYPE') {
+                recordSkip(path, 'unsupported-file-type');
+                return;
+            }
+            throw error;
+        }
         if (entry === undefined)
             return;
         if (entry.kind === 'file') {
-            totalBytes += entry.content.length;
-            if (totalBytes > options.config.maxSnapshotBytes) {
-                throw new ChangeLedgerError('SNAPSHOT_TOO_LARGE', `eligible files exceed configured aggregate limit of ${options.config.maxSnapshotBytes} bytes`);
+            if (budgetSpent || totalBytes + entry.content.length > options.config.maxSnapshotBytes) {
+                budgetSpent = true;
+                truncated ??= 'snapshot-limit';
+                recordSkip(path, 'snapshot-limit');
+                return;
             }
+            totalBytes += entry.content.length;
             if (options.store !== undefined) {
                 await options.store.putBlob(source.state.root, entry.snapshot.blob, entry.content);
             }
@@ -46,20 +86,19 @@ export async function captureTree(options) {
         if (gitCapture !== undefined)
             gitCapture.entries[path] = entry.snapshot;
     };
-    if (gitCapture === undefined) {
-        for (const path of source.paths)
-            await capturePath(path);
-    }
-    else {
+    {
+        // Reading one file at a time makes a real project directory take minutes, so
+        // every capture runs through a bounded worker pool. Per-file stability stats
+        // and the synchronous budget check keep the result identical to a serial run.
         let next = 0;
         let failed = false;
         let firstError = new ChangeLedgerError('WORKSPACE_CHANGED_DURING_CAPTURE', 'parallel comparison capture failed');
-        const concurrency = Math.min(32, source.paths.length, Math.max(1, Math.floor(COMPARISON_READ_BUDGET_BYTES / options.config.maxFileBytes)));
+        const concurrency = Math.min(32, paths.length, Math.max(1, Math.floor(COMPARISON_READ_BUDGET_BYTES / options.config.maxFileBytes)));
         const workers = Array.from({ length: concurrency }, async () => {
-            while (!failed && next < source.paths.length) {
+            while (!failed && next < paths.length) {
                 const index = next;
                 next += 1;
-                const path = source.paths[index];
+                const path = paths[index];
                 if (path === undefined)
                     continue;
                 try {
@@ -81,6 +120,10 @@ export async function captureTree(options) {
         source,
         entries,
         ...(gitCapture === undefined ? {} : { gitEntries: gitCapture.entries }),
+        skipped,
+        skippedCount,
+        skippedListTruncated: skippedCount > skipped.length,
+        ...(truncated === undefined ? {} : { truncated }),
         treeHash: hashTree(entries),
         fileCount: Object.keys(entries).length,
         totalBytes,

package/lib/store.js

@@ -180,6 +180,11 @@ export class LedgerStore {
             throw new ChangeLedgerError('BLOB_HASH_MISMATCH', `refusing to store content whose SHA-256 does not match ${hash}`);
         }
         const path = this.blobPath(workspace, hash);
+        // Content addressing makes an existing blob identical by construction, and
+        // re-writing it costs one fsync per file: a full-tree capture of a large
+        // workspace otherwise spends minutes proving it already stored the content.
+        if (await pathExists(path))
+            return;
         const directory = join(this.workspaceDir(workspace), 'blobs', hash.slice(0, 2));
         await mkdir(directory, { recursive: true, mode: 0o700 });
         const temporary = join(directory, `.${randomUUID()}.tmp`);

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

@@ -83,6 +83,41 @@ interface ClientContextLike {
     effect(setup: () => (() => void), label?: string): unknown;
 }
 type ChangeKind = 'added' | 'deleted' | 'modified' | 'mode-changed' | 'type-changed';
+interface ReadyPreview {
+    readonly status: 'ready';
+    readonly sessionId: string;
+    readonly messageSeq: number;
+    readonly turn: number;
+    readonly checkpointId: string;
+    readonly turnStartSeq: number;
+    readonly totalChanges: number;
+    readonly changes: readonly {
+        readonly path: string;
+        readonly kind: ChangeKind;
+    }[];
+    readonly offset: number;
+    readonly truncated: boolean;
+    /** Eligible paths the checkpoint could not store; a restore never touches them. */
+    readonly skippedCount: number;
+    readonly skipped: readonly {
+        readonly path: string;
+        readonly reason: string;
+    }[];
+    /** Set when limits stopped the capture before every eligible path was read. */
+    readonly captureTruncated?: 'file-limit' | 'snapshot-limit';
+    readonly headChanged: boolean;
+    readonly operationChanged: boolean;
+    readonly checkpointHead?: string;
+    readonly checkpointBranch?: string;
+    readonly checkpointOperation?: string;
+    readonly currentHead?: string;
+    readonly currentBranch?: string;
+    readonly currentOperation?: string;
+    readonly activeSessionIds: readonly string[];
+    readonly restoreBlocked: boolean;
+    readonly planId?: string;
+    readonly confirmation?: string;
+}
 /** Runtime-tunable Turn Rewind settings mirrored from the `turn-rewind` namespace. */
 export interface TurnRewindSettingsValue {
     readonly maxRestorePoints: number;
@@ -190,6 +225,25 @@ export declare function selectRewindMessageTarget(value: RewindNodeLike): {
 export declare function responseJson(response: Response): Promise<unknown>;
 /** Describe the user-visible result of restoring one changed file. */
 export declare function fileRecoveryLabel(kind: ChangeKind): string;
+/**
+ * Describe what a checkpoint could not store, in one user-facing sentence.
+ *
+ * Limits leave a restore point partial rather than failing it, so the dialog has
+ * to say which files stay untouched when the restore runs.
+ * @param ready - decoded ready preview, or null.
+ * @returns the warning text, or null when the checkpoint is complete.
+ */
+export declare function describeCaptureNotice(ready: ReadyPreview | null): string | null;
+/**
+ * Explain one recorded checkpoint skip in user terms.
+ *
+ * A skip is not a failure of the message: the turn ran normally and only the
+ * file snapshot is missing, so the text names the actual cause and the two
+ * levers that fix it.
+ * @param reason - reason recorded by the Host, usually a `[CODE] detail` line.
+ * @returns one user-facing sentence.
+ */
+export declare function explainCheckpointSkip(reason: string): string;
 /**
  * Explain one recorded checkpoint failure in user terms.
  *

package/lib/types/directory.d.ts

@@ -1,8 +1,13 @@
-import type { DirectoryWorkspaceState, ResolvedChangeLedgerConfig } from './types.js';
+import type { CaptureSkip, CaptureTruncation, DirectoryWorkspaceState, ResolvedChangeLedgerConfig } from './types.js';
 /** Ordinary-directory discovery result plus its eligible path inventory. */
 export interface DirectorySnapshotSource {
     readonly state: DirectoryWorkspaceState;
     readonly paths: readonly string[];
+    /** Eligible paths that cannot be stored at all, such as sockets. */
+    readonly skipped: readonly CaptureSkip[];
+    readonly skippedCount: number;
+    /** Set when the file-count limit stopped the walk early. */
+    readonly truncated?: CaptureTruncation;
 }
 /** Resolve the canonical ordinary directory used as a non-Git workspace root. */
 export declare function discoverDirectoryRoot(cwd: string): Promise<string>;

package/lib/types/git.d.ts

@@ -1,8 +1,12 @@
-import type { GitWorkspaceState } from './types.js';
+import type { CaptureSkip, CaptureTruncation, GitWorkspaceState } from './types.js';
 /** Repository discovery result plus the eligible path inventory. */
 export interface RepositorySnapshotSource {
     readonly state: GitWorkspaceState;
     readonly paths: readonly string[];
+    /** Git discovery never skips a path; per-file limits are reported by capture. */
+    readonly skipped: readonly CaptureSkip[];
+    readonly skippedCount: number;
+    readonly truncated?: CaptureTruncation;
 }
 /** Durable identity and shared lock location for one concrete Git worktree. */
 export interface GitWorktreeIdentity {

package/lib/types/index.d.ts

@@ -1,7 +1,3 @@
-/**
- * DSH Turn Rewind, powered by persistent, inspectable, approval-gated Change Ledger restore points.
- * @module @anionex/dsh-turn-rewind
- */
 import type { Context } from '@deepseek-ai/cordis';
 import { ChangeLedgerEngine } from './engine.js';
 import type { ChangeLedgerConfig } from './types.js';

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

@@ -130,7 +130,7 @@ interface SessionControllerLike {
     }>;
 }
 /** Services a conversation restart can be built on, in either carrier shape. */
-type ConversationRestartContext = Pick<Context, 'sessions' | 'sessionQuery'> & {
+type ConversationRestartContext = Pick<Context, 'sessions' | 'sessionQuery' | 'get'> & {
     readonly apiProxy?: ApiProxyLike;
     readonly sessionController?: SessionControllerLike;
 };

package/lib/types/snapshot.d.ts

@@ -1,11 +1,18 @@
 import type { LedgerStore } from './store.js';
 import { type WorkspaceSnapshotSource } from './workspace.js';
-import type { ResolvedChangeLedgerConfig, SnapshotEntry, WorkspaceChange } from './types.js';
+import type { CaptureSkip, CaptureTruncation, ResolvedChangeLedgerConfig, SnapshotEntry, WorkspaceChange } from './types.js';
 /** One captured tree, optionally persisted into the blob store. */
 export interface CapturedTree {
     readonly source: WorkspaceSnapshotSource;
     readonly entries: Readonly<Record<string, SnapshotEntry>>;
     readonly gitEntries?: Readonly<Record<string, SnapshotEntry>>;
+    /** Eligible paths this capture could not store; a restore never touches them. */
+    readonly skipped: readonly CaptureSkip[];
+    readonly skippedCount: number;
+    /** Set when a limit stopped the capture before every eligible path was read. */
+    readonly truncated?: CaptureTruncation;
+    /** True when the recorded skip list is shorter than `skippedCount`. */
+    readonly skippedListTruncated: boolean;
     readonly treeHash: string;
     readonly fileCount: number;
     readonly totalBytes: number;

package/lib/types/types.d.ts

@@ -25,6 +25,15 @@ export interface SymlinkSnapshotEntry {
 }
 /** One path captured by a restore point. */
 export type SnapshotEntry = FileSnapshotEntry | SymlinkSnapshotEntry;
+/** Why one eligible path was left out of a restore point. */
+export type CaptureSkipReason = 'file-too-large' | 'unsupported-file-type' | 'snapshot-limit';
+/** One eligible path that a restore point could not store. */
+export interface CaptureSkip {
+    readonly path: string;
+    readonly reason: CaptureSkipReason;
+}
+/** Why a capture stopped before it enumerated every eligible path. */
+export type CaptureTruncation = 'file-limit' | 'snapshot-limit';
 /** Git facts that fence a restore point to the repository state it observed. */
 export interface GitWorkspaceState {
     readonly type: 'git';
@@ -67,6 +76,15 @@ export interface RestorePointManifestV1 {
     readonly fileCount: number;
     readonly totalBytes: number;
     readonly entries: Readonly<Record<string, SnapshotEntry>>;
+    /**
+     * Eligible paths this restore point could not store, bounded for storage.
+     * A restore never touches them, so a partial point stays safe to apply.
+     */
+    readonly skipped?: readonly CaptureSkip[];
+    /** Total skipped paths, including any beyond the bounded list. */
+    readonly skippedCount?: number;
+    /** Set when limits stopped the capture before every eligible path was read. */
+    readonly truncated?: CaptureTruncation;
     readonly restoreCount: number;
     readonly lastRestoredAt?: number;
 }
@@ -133,6 +151,9 @@ export interface RestorePointSummary {
     readonly treeHash: string;
     readonly fileCount: number;
     readonly totalBytes: number;
+    readonly skipped?: readonly CaptureSkip[];
+    readonly skippedCount: number;
+    readonly truncated?: CaptureTruncation;
     readonly restoreCount: number;
     readonly lastRestoredAt?: number;
     readonly head?: string;

package/lib/validate.js

@@ -76,11 +76,24 @@ export function parseManifest(value) {
         corrupt('only turn restore points may carry turn metadata');
     }
     const lastRestoredAt = optionalNonNegativeInteger(record, 'lastRestoredAt');
+    const skipped = parseCaptureSkips(record.skipped);
+    const skippedCount = optionalNonNegativeInteger(record, 'skippedCount');
+    if (skippedCount !== undefined && skippedCount < (skipped?.length ?? 0)) {
+        corrupt('skippedCount cannot be smaller than the recorded skipped paths');
+    }
+    const truncatedValue = record.truncated;
+    if (truncatedValue !== undefined && truncatedValue !== 'file-limit' && truncatedValue !== 'snapshot-limit') {
+        corrupt('truncated must be "file-limit" or "snapshot-limit"');
+    }
+    const truncated = truncatedValue;
     const common = {
         id,
         kind: restorePointKind,
         workspace,
         repository,
+        ...(skipped === undefined ? {} : { skipped }),
+        ...(skippedCount === undefined ? {} : { skippedCount }),
+        ...(truncated === undefined ? {} : { truncated }),
         ...(sessionId === undefined ? {} : { sessionId }),
         ...(label === undefined ? {} : { label }),
         ...(parentRestorePoint === undefined ? {} : { parentRestorePoint }),
@@ -166,6 +179,26 @@ export function validateBlobHash(value) {
  * @param value - persisted `repository` field.
  * @returns the validated workspace state.
  */
+/**
+ * Parse the optional bounded list of eligible paths a restore point could not store.
+ * @param value - persisted `skipped` field.
+ * @returns the validated list, or undefined when the manifest carries none.
+ */
+function parseCaptureSkips(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value))
+        corrupt('skipped must be an array');
+    return value.map((entry) => {
+        const record = objectRecord(entry, 'skipped path');
+        const path = validateRelativePath(requireString(record.path, 'skipped path'));
+        const reason = record.reason;
+        if (reason !== 'file-too-large' && reason !== 'unsupported-file-type') {
+            corrupt('skipped reason must be "file-too-large" or "unsupported-file-type"');
+        }
+        return { path, reason };
+    });
+}
 function parseRepository(value) {
     const record = objectRecord(value, 'repository state');
     const root = absoluteString(record, 'root');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anionex/dsh-turn-rewind",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Turn-level conversation and workspace rewind for DeepSeek Harness, powered by a persistent Change Ledger",
   "repository": {
     "type": "git",

package/src/client/index.tsx

@@ -116,6 +116,11 @@ interface ReadyPreview {
   readonly changes: readonly { readonly path: string; readonly kind: ChangeKind }[]
   readonly offset: number
   readonly truncated: boolean
+  /** Eligible paths the checkpoint could not store; a restore never touches them. */
+  readonly skippedCount: number
+  readonly skipped: readonly { readonly path: string; readonly reason: string }[]
+  /** Set when limits stopped the capture before every eligible path was read. */
+  readonly captureTruncated?: 'file-limit' | 'snapshot-limit'
   readonly headChanged: boolean
   readonly operationChanged: boolean
   readonly checkpointHead?: string
@@ -567,6 +572,7 @@ export function RewindMessageAction({ matched, sessionId, openRestoredSession }:
     }
   }
 
+  const captureNotice = describeCaptureNotice(ready)
   const actionLabel = mode === 'both' ? '恢复并从这里继续' : mode === 'code' ? '恢复文件' : '只回溯消息'
   const radioName = `dcl-rewind-${sessionId}-${String(matched.messageSeq)}`
   const branchChanged = ready !== null && ready.checkpointBranch !== ready.currentBranch
@@ -599,7 +605,7 @@ export function RewindMessageAction({ matched, sessionId, openRestoredSession }:
           {loading && <p className="dcl-rewind-status">正在检查可以恢复的项目文件…</p>}
           {preview?.status === 'pending' && <p className="dcl-rewind-status">这条消息发送前的文件还在保存，请稍后再试。</p>}
           {preview?.status === 'missing' && <p className="dcl-rewind-error">没有保存这条消息发送前的文件。可能是当时还没启用回退功能、记录已超过保留期限，或已关闭自动检查点。仍可只回溯消息。</p>}
-          {preview?.status === 'skipped' && <p className="dcl-rewind-status">为避免阻塞消息发送，本轮没有自动保存文件：{preview.reason}仍可只回溯消息。</p>}
+          {preview?.status === 'skipped' && <p className="dcl-rewind-status">{explainCheckpointSkip(preview.reason)}</p>}
           {preview?.status === 'failed' && <p className="dcl-rewind-error">{explainCheckpointFailure(preview.error)}</p>}
           {preview !== null && (
             <div className="dcl-rewind-options">
@@ -619,6 +625,7 @@ export function RewindMessageAction({ matched, sessionId, openRestoredSession }:
           )}
           {ready !== null && (
             <>
+              {captureNotice !== null && <p className="dcl-rewind-warning">{captureNotice}</p>}
               <div className="dcl-rewind-summary">
                 {mode === 'messages'
                   ? <strong>项目文件保持不变</strong>
@@ -1045,6 +1052,16 @@ function decodePreview(value: unknown): Preview {
     changes,
     offset: requiredInteger(record.offset, 'offset'),
     truncated: requiredBoolean(record.truncated, 'truncated'),
+    skippedCount: typeof record.skippedCount === 'number' ? record.skippedCount : 0,
+    skipped: Array.isArray(record.skipped)
+      ? record.skipped.map((entry) => {
+          const skip = recordOf(entry)
+          return { path: requiredString(skip.path, 'path'), reason: requiredString(skip.reason, 'reason') }
+        })
+      : [],
+    ...(record.captureTruncated === 'file-limit' || record.captureTruncated === 'snapshot-limit'
+      ? { captureTruncated: record.captureTruncated as 'file-limit' | 'snapshot-limit' }
+      : {}),
     headChanged: requiredBoolean(record.headChanged, 'headChanged'),
     operationChanged: requiredBoolean(record.operationChanged, 'operationChanged'),
     ...optionalRecordString(record, 'checkpointHead'),
@@ -1269,6 +1286,52 @@ function friendlyError(error: unknown): string {
   }
 }
 
+/**
+ * Describe what a checkpoint could not store, in one user-facing sentence.
+ *
+ * Limits leave a restore point partial rather than failing it, so the dialog has
+ * to say which files stay untouched when the restore runs.
+ * @param ready - decoded ready preview, or null.
+ * @returns the warning text, or null when the checkpoint is complete.
+ */
+export function describeCaptureNotice(ready: ReadyPreview | null): string | null {
+  if (ready === null) return null
+  const example = (ready.skipped ?? [])[0]?.path
+  if (ready.captureTruncated === 'snapshot-limit') {
+    return '本轮要保存的文件总量超过上限，剩下的文件没有纳入检查点。恢复时不会改动它们。'
+  }
+  if (ready.captureTruncated === 'file-limit') {
+    return '本轮文件数量超过上限，多出来的文件没有纳入检查点。恢复时不会改动它们。'
+  }
+  if (ready.skippedCount > 0) {
+    return `有 ${String(ready.skippedCount)} 个文件因为超过单文件大小上限或类型不受支持，没有纳入检查点${example === undefined ? '' : `（例如 ${example}）`}。恢复时不会改动它们。`
+  }
+  return null
+}
+
+/**
+ * Explain one recorded checkpoint skip in user terms.
+ *
+ * A skip is not a failure of the message: the turn ran normally and only the
+ * file snapshot is missing, so the text names the actual cause and the two
+ * levers that fix it.
+ * @param reason - reason recorded by the Host, usually a `[CODE] detail` line.
+ * @returns one user-facing sentence.
+ */
+export function explainCheckpointSkip(reason: string): string {
+  const code = /^\[([A-Z_]+)\]/.exec(reason)?.[1]
+  if (code === 'TURN_CHECKPOINT_TIMEOUT') {
+    return '这个项目目录太大，在检查点时间上限内没保存完文件快照，所以本轮没有回退点（消息本身没有受影响）。可以在插件设置里调大「检查点时间上限」，或在目录根用 .dsh-rewindignore 排除大目录（例如 node_modules、构建产物、数据集）。仍可只回溯消息。'
+  }
+  if (code === 'TURN_CHECKPOINT_DISABLED') {
+    return '自动文件检查点已在设置里关闭，本轮没有回退点。仍可只回溯消息。'
+  }
+  if (code === 'TURN_CHECKPOINT_NEW_CONTENT_LIMIT') {
+    return '这一轮新增的内容超过检查点预算，没有保存文件快照。仍可只回溯消息。'
+  }
+  return `本轮没有保存文件检查点：${reason}仍可只回溯消息。`
+}
+
 /**
  * Explain one recorded checkpoint failure in user terms.
  *

package/src/directory.ts

@@ -4,15 +4,34 @@ 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'
+import type {
+  CaptureSkip,
+  CaptureTruncation,
+  DirectoryWorkspaceState,
+  ResolvedChangeLedgerConfig,
+} from './types.js'
 
 const IGNORE_FILE = '.dsh-rewindignore'
+const MAX_RECORDED_SKIPS = 50
 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[]
+  /** Eligible paths that cannot be stored at all, such as sockets. */
+  readonly skipped: readonly CaptureSkip[]
+  readonly skippedCount: number
+  /** Set when the file-count limit stopped the walk early. */
+  readonly truncated?: CaptureTruncation
+}
+
+/** Mutable walk accumulator shared by one directory enumeration. */
+interface DirectoryWalk {
+  readonly paths: string[]
+  readonly skipped: CaptureSkip[]
+  skippedCount: number
+  truncated?: CaptureTruncation
 }
 
 /** Resolve the canonical ordinary directory used as a non-Git workspace root. */
@@ -28,10 +47,16 @@ export async function discoverDirectory(
 ): 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 }
+  const walk: DirectoryWalk = { paths: [], skipped: [], skippedCount: 0 }
+  await walkDirectory(root, root, '', matcher, walk, config.maxFiles, signal)
+  walk.paths.sort(comparePaths)
+  return {
+    state: { type: 'directory', root },
+    paths: walk.paths,
+    skipped: walk.skipped,
+    skippedCount: walk.skippedCount,
+    ...(walk.truncated === undefined ? {} : { truncated: walk.truncated }),
+  }
 }
 
 /**
@@ -90,7 +115,7 @@ async function walkDirectory(
   directory: string,
   directoryPath: string,
   matcher: Ignore,
-  paths: string[],
+  walk: DirectoryWalk,
   maxFiles: number,
   signal?: AbortSignal,
 ): Promise<void> {
@@ -108,6 +133,7 @@ async function walkDirectory(
 
   entries.sort((left, right) => comparePaths(left.name, right.name))
   for (const entry of entries) {
+    if (walk.truncated !== undefined) return
     throwIfAborted(signal)
     await assertSafeDirectory(root, directory, after)
     const path = directoryPath === '' ? entry.name : `${directoryPath}/${entry.name}`
@@ -121,26 +147,28 @@ async function walkDirectory(
     }
     if (info.isDirectory() && !info.isSymbolicLink()) {
       if (matcher.ignores(`${path}/`)) continue
-      await walkDirectory(root, target, path, matcher, paths, maxFiles, signal)
+      await walkDirectory(root, target, path, matcher, walk, 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)}`,
-      )
+      recordSkip(walk, path, 'unsupported-file-type')
+      continue
     }
-    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)}`,
-      )
+    if (walk.paths.length >= maxFiles) {
+      walk.truncated = 'file-limit'
+      return
     }
+    walk.paths.push(path)
   }
 }
 
+/** Record one skipped path, bounding the durable list while counting every entry. */
+function recordSkip(walk: DirectoryWalk, path: string, reason: CaptureSkip['reason']): void {
+  walk.skippedCount += 1
+  if (walk.skipped.length < MAX_RECORDED_SKIPS) walk.skipped.push({ path, reason })
+}
+
 /**
  * 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