@anionex/dsh-turn-rewind 0.2.0 → 0.2.2

package/lib/rewind-host.js

@@ -2,11 +2,19 @@ import { randomUUID } from 'node:crypto';
 import { createDeadline } from './deadline.js';
 import { ChangeLedgerError, errorMessage } from './errors.js';
 import { discoverRepositoryRoot } from './git.js';
+function getSessionEvents(session) {
+    if (!session)
+        return [];
+    if (typeof session.snapshotEvents === 'function') {
+        return session.snapshotEvents();
+    }
+    return session.events ?? [];
+}
 export const REWIND_HTTP_PATH = '/turn-rewind';
 const BODY_LIMIT = 64 * 1024;
 const INITIAL_CHANGE_PREVIEW_LIMIT = 8;
 const MAX_CHANGE_PAGE_SIZE = 200;
-/** Capture each turn before its opening user message can trigger model or tool work. */
+/** Capture each turn beside model work and gate root tool side effects on its bounded outcome. */
 export class TurnCheckpointCoordinator {
     engine;
     captures = new Map();
@@ -17,11 +25,17 @@ export class TurnCheckpointCoordinator {
     constructor(engine) {
         this.engine = engine;
     }
-    /** Install the first-step gate; checkpoint failures are recorded but never reject the user turn. */
+    /** Keep sidecar checkpoint work out of the Agent response waterfall. */
     install(ctx) {
         ctx.on('agent/pre-step', async ({ agent, turn, step, signal }, next) => {
             if (step === 1)
-                await this.capture(ctx, agent, turn, signal);
+                this.startCapture(ctx, agent, turn, signal);
+            return next();
+        }, { prepend: true });
+        ctx.on('tools/execute', async (exec, next) => {
+            if (exec.agent !== undefined && exec.parent === undefined) {
+                await this.waitForOpenTurn(exec.agent, exec.signal);
+            }
             return next();
         }, { prepend: true });
     }
@@ -36,12 +50,22 @@ export class TurnCheckpointCoordinator {
         const error = this.failures.get(key);
         return error === undefined ? { status: 'missing' } : { status: 'failed', error };
     }
+    startCapture(ctx, agent, turn, signal) {
+        const key = checkpointKey(agent.id, turn);
+        if (this.captures.has(key))
+            return;
+        const capture = this.capture(ctx, agent, turn, signal).catch(async (error) => {
+            await this.recordFailure(ctx, agent.id, turn, error);
+        });
+        this.captures.set(key, capture);
+    }
     async capture(ctx, agent, turn, signal) {
         const key = checkpointKey(agent.id, turn);
         const cwd = agent.session.header.cwd;
         if (cwd === undefined)
             return;
-        const start = agent.session.events.findLast(event => event.type === 'turn/start' && event.data.turn === turn);
+        const events = getSessionEvents(agent.session);
+        const start = events.findLast(event => event.type === 'turn/start' && event.data.turn === turn);
         if (start === undefined) {
             await this.recordFailure(ctx, agent.id, turn, new Error('turn/start is unavailable before the first step'));
             return;
@@ -53,11 +77,6 @@ export class TurnCheckpointCoordinator {
         const captureDeadline = createDeadline(Math.max(1, timeoutMs - reserveMs));
         const captureSignal = AbortSignal.any([signal, captureDeadline.signal]);
         try {
-            const existing = this.captures.get(key);
-            if (existing !== undefined) {
-                await waitWithSignal(existing, captureSignal).catch(() => undefined);
-                return;
-            }
             this.pending.add(key);
             this.failures.delete(key);
             this.skips.delete(key);
@@ -86,7 +105,6 @@ export class TurnCheckpointCoordinator {
                     this.pending.delete(key);
                 }
             })();
-            this.captures.set(key, capture);
             try {
                 await waitWithSignal(capture, outcomeSignal);
             }
@@ -107,6 +125,30 @@ export class TurnCheckpointCoordinator {
             outcomeDeadline.cancel();
         }
     }
+    /** Wait only for the bounded checkpoint outcome of the Agent's open turn. */
+    async waitForOpenTurn(agent, signal) {
+        if (signal.aborted)
+            return;
+        const events = getSessionEvents(agent.session);
+        const boundary = events.findLast(event => event.type === 'turn/start' || event.type === 'turn/end');
+        if (boundary?.type !== 'turn/start')
+            return;
+        const turn = boundary.data.turn;
+        if (!Number.isSafeInteger(turn) || turn < 0)
+            return;
+        const capture = this.captures.get(checkpointKey(agent.id, turn));
+        if (capture === undefined)
+            return;
+        try {
+            await waitWithSignal(capture, signal);
+        }
+        catch (error) {
+            // Delegate caller cancellation so the DSH tool runtime preserves its
+            // canonical ABORTED_BEFORE_DISPATCH result instead of a wrapper error.
+            if (!signal.aborted)
+                throw error;
+        }
+    }
     async serializeWorkspace(workspace, signal, task) {
         const previous = this.workspaceTails.get(workspace) ?? Promise.resolve();
         const current = (async () => {
@@ -182,95 +224,6 @@ export function installRewindHttp(ctx, engine, coordinator) {
         handler: createRewindHttpHandler(ctx, engine, coordinator),
     }), 'change-ledger.rewindHttp');
 }
-export const MANAGE_HTTP_PATH = '/turn-rewind/manage';
-/** Register the same-origin storage-management endpoint consumed by the settings card. */
-export function installManageHttp(ctx, engine) {
-    ctx.effect(() => ctx.webServer.register({
-        kind: 'exact',
-        path: MANAGE_HTTP_PATH,
-        handler: createManageHttpHandler(engine),
-    }), 'change-ledger.manageHttp');
-}
-/** Build the storage-management route as a testable unit. */
-export function createManageHttpHandler(engine) {
-    return async (request, response) => {
-        try {
-            if (request.method === 'GET') {
-                const workspaces = await engine.listWorkspaces();
-                json(response, 200, {
-                    storageDir: engine.config.storageDir,
-                    totalBytes: workspaces.reduce((total, workspace) => total + workspace.totalBytes, 0),
-                    workspaces: workspaces.map((workspace) => ({
-                        workspace: workspace.workspace,
-                        totalBytes: workspace.totalBytes,
-                        recoveryCount: workspace.recoveryCount,
-                        restorePoints: workspace.restorePoints.map((point) => ({
-                            id: point.id,
-                            kind: point.kind,
-                            format: point.format,
-                            createdAt: point.createdAt,
-                            totalBytes: point.totalBytes,
-                            fileCount: point.fileCount,
-                            ...(point.sessionId === undefined ? {} : { sessionId: point.sessionId }),
-                            ...(point.turn === undefined ? {} : { turn: point.turn }),
-                            ...(point.label === undefined ? {} : { label: point.label }),
-                        })),
-                    })),
-                });
-                return;
-            }
-            if (request.method === 'POST') {
-                const body = objectBody(await readBody(request));
-                const action = requiredText(body.action, 'action');
-                if (action === 'delete') {
-                    const workspace = requiredText(body.workspace, 'workspace');
-                    const restorePointId = requiredText(body.restorePointId, 'restorePointId');
-                    const report = await engine.purgeWorkspace({ workspace, restorePointIds: [restorePointId] });
-                    if (report.deletedRestorePoints === 0) {
-                        throw new ChangeLedgerError(report.retainedRestorePoints > 0 ? 'RECOVERY_REFERENCE' : 'RESTORE_POINT_NOT_FOUND', report.retainedRestorePoints > 0
-                            ? 'restore point is required by an incomplete recovery journal'
-                            : `restore point ${restorePointId} does not exist`);
-                    }
-                    json(response, 200, { status: 'completed', action, ...report });
-                    return;
-                }
-                if (action === 'clear-workspace') {
-                    const workspace = requiredText(body.workspace, 'workspace');
-                    json(response, 200, { status: 'completed', action, ...await engine.purgeWorkspace({ workspace }) });
-                    return;
-                }
-                if (action === 'clear-all') {
-                    const reports = [];
-                    const failures = [];
-                    for (const overview of await engine.listWorkspaces()) {
-                        try {
-                            reports.push(await engine.purgeWorkspace({ workspace: overview.workspace }));
-                        }
-                        catch (error) {
-                            failures.push({ workspace: overview.workspace, error: errorMessage(error) });
-                        }
-                    }
-                    json(response, 200, {
-                        status: failures.length > 0 ? 'partial' : 'completed',
-                        action,
-                        reports,
-                        ...(failures.length > 0 ? { failures } : {}),
-                    });
-                    return;
-                }
-                throw new ChangeLedgerError('INVALID_ARGUMENTS', 'action must be "delete", "clear-workspace", or "clear-all"');
-            }
-            json(response, 405, { error: 'method not allowed' });
-        }
-        catch (error) {
-            const status = error instanceof ChangeLedgerError && error.code === 'RESTORE_POINT_NOT_FOUND' ? 404 : 409;
-            json(response, status, {
-                error: errorMessage(error),
-                code: error instanceof ChangeLedgerError ? error.code : 'MANAGE_FAILED',
-            });
-        }
-    };
-}
 /** Build the exact-route handler as a testable unit. */
 export function createRewindHttpHandler(ctx, engine, coordinator) {
     return async (request, response) => {
@@ -282,17 +235,7 @@ export function createRewindHttpHandler(ctx, engine, coordinator) {
                 const detailsOnly = url.searchParams.get('details') === '1';
                 const offset = nonNegativeInteger(url.searchParams.get('offset') ?? '0', 'offset');
                 const limit = pageSize(url.searchParams.get('limit'), detailsOnly ? MAX_CHANGE_PAGE_SIZE : INITIAL_CHANGE_PREVIEW_LIMIT);
-                const { session, target } = await resolveMessageTarget(ctx, sessionId, messageSeq);
-                let checkpoint;
-                try {
-                    checkpoint = await resolveMessageCheckpoint(ctx, engine, sessionId, session, target);
-                }
-                catch (error) {
-                    // File-checkpoint discovery is allowed to fail independently: the dialog
-                    // must still expose message-only rewind for a valid Session boundary.
-                    json(response, 200, { status: 'failed', error: errorMessage(error) });
-                    return;
-                }
+                const { target, checkpoint } = await resolveMessageCheckpoint(ctx, engine, sessionId, messageSeq);
                 if (checkpoint === undefined) {
                     const durableSkip = await engine.findTurnCheckpointSkip({
                         cwd: target.cwd,
@@ -348,20 +291,11 @@ 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' && mode !== 'messages') {
-                    throw new ChangeLedgerError('INVALID_ARGUMENTS', 'mode must be "code", "both", or "messages"');
+                if (mode !== 'code' && mode !== 'both') {
+                    throw new ChangeLedgerError('INVALID_ARGUMENTS', 'mode must be "code" or "both"');
                 }
                 const sessionId = requiredText(body.sessionId, 'sessionId');
                 const messageSeq = nonNegativeInteger(body.messageSeq, 'messageSeq');
-                if (mode === 'messages') {
-                    // Message-only rewind never mutates project files, so no checkpoint, no
-                    // restore plan, and no shared-workspace gate apply; the conversation
-                    // restart revalidates the message boundary itself.
-                    const { target } = await resolveMessageTarget(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);
@@ -419,18 +353,15 @@ async function readSession(ctx, sessionId) {
     const stored = await ctx.sessionQuery.readSession(sessionId);
     return { id: sessionId, header: stored.session, events: stored.events };
 }
-async function resolveMessageTarget(ctx, sessionId, messageSeq) {
-    const session = await readSession(ctx, sessionId);
-    return { session, target: messageTarget(session, messageSeq) };
-}
-async function resolveMessageCheckpoint(ctx, engine, sessionId, source, target) {
-    let current = source;
+async function resolveMessageCheckpoint(ctx, engine, sessionId, messageSeq) {
+    let current = await readSession(ctx, sessionId);
+    const target = messageTarget(current, messageSeq);
     const direct = await engine.findTurnCheckpoint({ cwd: target.cwd, sessionId, turn: target.turn });
     if (direct !== undefined) {
         if (direct.turnStartSeq !== target.turnStartSeq) {
             throw new ChangeLedgerError('PLAN_STALE', 'the message checkpoint no longer matches its turn start');
         }
-        return { ...target, id: direct.id };
+        return { target, checkpoint: { ...target, id: direct.id } };
     }
     const seen = new Set([sessionId]);
     while (true) {
@@ -441,7 +372,7 @@ async function resolveMessageCheckpoint(ctx, engine, sessionId, source, target)
         }
         if (parentId === undefined || seedLength === undefined
             || target.messageSeq >= seedLength || target.turnStartSeq >= seedLength) {
-            return undefined;
+            return { target };
         }
         if (seen.has(parentId)) {
             throw new ChangeLedgerError('PLAN_STALE', 'session fork lineage contains a cycle');
@@ -453,7 +384,7 @@ async function resolveMessageCheckpoint(ctx, engine, sessionId, source, target)
         catch (error) {
             throw new ChangeLedgerError('PLAN_STALE', `parent session ${parentId} is unavailable`, { cause: error });
         }
-        const parentTarget = messageTarget(current, target.messageSeq);
+        const parentTarget = messageTarget(current, messageSeq);
         if (parentTarget.turn !== target.turn
             || parentTarget.turnStartSeq !== target.turnStartSeq
             || parentTarget.previousTurnEndSeq !== target.previousTurnEndSeq) {
@@ -465,12 +396,11 @@ async function resolveMessageCheckpoint(ctx, engine, sessionId, source, target)
         if (inherited.turnStartSeq !== target.turnStartSeq) {
             throw new ChangeLedgerError('PLAN_STALE', 'the inherited message checkpoint no longer matches the fork boundary');
         }
-        return { ...target, id: inherited.id };
+        return { target, checkpoint: { ...target, id: inherited.id } };
     }
 }
 async function checkpointForRequest(ctx, engine, sessionId, messageSeq, requestedId) {
-    const { session, target } = await resolveMessageTarget(ctx, sessionId, messageSeq);
-    const checkpoint = await resolveMessageCheckpoint(ctx, engine, sessionId, session, target);
+    const { target, checkpoint } = await resolveMessageCheckpoint(ctx, engine, sessionId, messageSeq);
     if (checkpoint === undefined) {
         throw new ChangeLedgerError('RESTORE_POINT_NOT_FOUND', `message ${String(target.messageSeq)} has no rewind checkpoint`);
     }
@@ -479,22 +409,33 @@ async function checkpointForRequest(ctx, engine, sessionId, messageSeq, requeste
     }
     return checkpoint;
 }
-async function createConversationRestart(ctx, sourceId, target) {
+async function createConversationRestart(ctx, sourceId, checkpoint) {
     const source = await readSession(ctx, sourceId);
-    const current = messageTarget(source, target.messageSeq);
-    if (current.turn !== target.turn
-        || current.turnStartSeq !== target.turnStartSeq
-        || current.previousTurnEndSeq !== target.previousTurnEndSeq) {
+    const current = messageTarget(source, checkpoint.messageSeq);
+    if (current.turn !== checkpoint.turn
+        || current.turnStartSeq !== checkpoint.turnStartSeq
+        || current.previousTurnEndSeq !== checkpoint.previousTurnEndSeq) {
         throw new ChangeLedgerError('PLAN_STALE', 'the session no longer contains the selected message boundary');
     }
-    const response = target.previousTurnEndSeq === undefined
-        ? await ctx.apiProxy.sessions.create({
+    const controller = ctx.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;
+    if (apiProxy === undefined) {
+        throw new ChangeLedgerError('CONVERSATION_REWIND_FAILED', 'this DSH host exposes neither sessionController nor apiProxy, so a new conversation cannot be created');
+    }
+    const response = checkpoint.previousTurnEndSeq === undefined
+        ? await apiProxy.sessions.create({
             rpcId: randomUUID(),
-            payload: { cwd: target.cwd },
+            payload: { cwd: checkpoint.cwd },
         })
-        : await ctx.apiProxy.sessions.fork({
+        : await apiProxy.sessions.fork({
             rpcId: randomUUID(),
-            payload: { sessionId: sourceId, atSeq: target.previousTurnEndSeq },
+            payload: { sessionId: sourceId, atSeq: checkpoint.previousTurnEndSeq },
         });
     if (!response.result.ok) {
         throw new ChangeLedgerError('CONVERSATION_REWIND_FAILED', response.result.error.message);
@@ -505,27 +446,28 @@ function messageTarget(session, messageSeq) {
     const cwd = session.header.cwd;
     if (cwd === undefined)
         throw new ChangeLedgerError('WORKSPACE_REQUIRED', `session ${session.id} has no workspace`);
-    const message = session.events.find(event => event.type === 'user/message' && event.seq === messageSeq && isDirectUserMessage(event));
+    const events = getSessionEvents(session);
+    const message = events.find(event => event.type === 'user/message' && event.seq === messageSeq && isDirectUserMessage(event));
     if (message === undefined) {
         throw new ChangeLedgerError('RESTORE_POINT_NOT_FOUND', `session ${session.id} has no user message at ${String(messageSeq)}`);
     }
-    const start = session.events.findLast(event => event.type === 'turn/start' && event.seq < messageSeq);
+    const start = events.findLast(event => event.type === 'turn/start' && event.seq < messageSeq);
     const turn = start?.data.turn;
     if (start === undefined || !Number.isSafeInteger(turn) || turn < 0) {
         throw new ChangeLedgerError('PLAN_STALE', 'the selected user message has no valid turn start');
     }
-    const openingMessage = session.events.find(event => (event.type === 'user/message'
+    const openingMessage = events.find(event => (event.type === 'user/message'
         && event.seq > start.seq
         && event.seq <= messageSeq
         && isDirectUserMessage(event)));
     if (openingMessage?.seq !== messageSeq) {
         throw new ChangeLedgerError('RESTORE_POINT_NOT_FOUND', 'rewind is available only for the opening user message of a turn');
     }
-    const interveningEnd = session.events.find(event => event.type === 'turn/end' && event.seq > start.seq && event.seq < messageSeq);
+    const interveningEnd = events.find(event => event.type === 'turn/end' && event.seq > start.seq && event.seq < messageSeq);
     if (interveningEnd !== undefined) {
         throw new ChangeLedgerError('PLAN_STALE', 'the selected user message is outside its recorded turn');
     }
-    const previousEnd = session.events.findLast(event => event.type === 'turn/end' && event.seq < start.seq);
+    const previousEnd = events.findLast(event => event.type === 'turn/end' && event.seq < start.seq);
     return {
         messageSeq,
         turn: turn,
@@ -621,3 +563,66 @@ function json(response, status, value) {
     response.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
     response.end(`${JSON.stringify(value)}\n`);
 }
+export const MANAGE_HTTP_PATH = '/turn-rewind/manage';
+/** Register the same-origin storage-management endpoint consumed by the settings card. */
+export function installManageHttp(ctx, engine) {
+    ctx.effect(() => ctx.webServer.register({
+        kind: 'exact',
+        path: MANAGE_HTTP_PATH,
+        handler: createManageHttpHandler(engine),
+    }), 'change-ledger.manageHttp');
+}
+/** Build the storage-management route as a testable unit. */
+export function createManageHttpHandler(engine) {
+    return async (request, response) => {
+        try {
+            if (request.method === 'GET') {
+                const workspaces = await engine.listWorkspaces();
+                json(response, 200, {
+                    storageDir: engine.config.storageDir,
+                    totalBytes: workspaces.reduce((total, workspace) => total + workspace.totalBytes, 0),
+                    workspaces: workspaces.map((workspace) => ({
+                        workspace: workspace.workspace,
+                        totalBytes: workspace.totalBytes,
+                        recoveryCount: workspace.recoveryCount,
+                        restorePoints: workspace.restorePoints.map((point) => ({
+                            id: point.id,
+                            kind: point.kind,
+                            format: point.format,
+                            createdAt: point.createdAt,
+                            totalBytes: point.totalBytes,
+                            fileCount: point.fileCount,
+                            ...(point.sessionId === undefined ? {} : { sessionId: point.sessionId }),
+                            ...(point.turn === undefined ? {} : { turn: point.turn }),
+                            ...(point.label === undefined ? {} : { label: point.label }),
+                        })),
+                    })),
+                });
+                return;
+            }
+            if (request.method === 'POST') {
+                const body = objectBody(await readBody(request));
+                const action = requiredText(body.action, 'action');
+                if (action === 'delete') {
+                    const workspace = requiredText(body.workspace, 'workspace');
+                    const restorePointId = requiredText(body.restorePointId, 'restorePointId');
+                    const report = await engine.purgeWorkspace({ workspace, restorePointIds: [restorePointId] });
+                    if (report.deletedRestorePoints === 0) {
+                        throw new ChangeLedgerError(report.retainedRestorePoints > 0 ? 'RECOVERY_REFERENCE' : 'RESTORE_POINT_NOT_FOUND', report.retainedRestorePoints > 0
+                            ? 'restore point is required by an incomplete recovery journal'
+                            : `restore point ${restorePointId} does not exist`);
+                    }
+                    json(response, 200, { status: 'completed', action, ...report });
+                    return;
+                }
+                throw new ChangeLedgerError('INVALID_ARGUMENTS', `unsupported manage action ${action}`);
+            }
+            response.writeHead(405, { allow: 'GET, POST' });
+            response.end();
+        }
+        catch (error) {
+            const status = error instanceof ChangeLedgerError && error.code === 'RESTORE_POINT_NOT_FOUND' ? 404 : 409;
+            json(response, status, { error: errorMessage(error), code: error instanceof ChangeLedgerError ? error.code : 'MANAGE_FAILED' });
+        }
+    };
+}

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

@@ -12,14 +12,29 @@ interface ConversationChatNodeLike {
     readonly kind: string;
     readonly data: ConversationNodeLike;
 }
-interface ConversationSnapshotLike {
-    readonly nodes: readonly ConversationNodeLike[];
-    readonly chat?: {
-        readonly nodes: {
-            values(): readonly ConversationChatNodeLike[];
-        };
-    };
+/**
+ * Chat node store exposed by the Chat target. DSH 0.1.2+ publishes a mutable
+ * keyed store; older clients published a Map with the same `get` contract.
+ */
+interface ChatNodeStoreLike {
+    get(key: string): RewindNodeLike | undefined;
+    values?(): Iterable<RewindNodeLike>;
+}
+/** Chat projection shared by `session.chat` (0.1.1) and the `useChat` hook (0.1.2+). */
+interface ChatSnapshotLike {
+    readonly order?: readonly string[];
+    readonly nodes?: ChatNodeStoreLike | readonly RewindNodeLike[];
+}
+/**
+ * Snapshot seen by a session-scoped slot entry. 0.1.1 exposes the chat
+ * projection as `snapshot.chat`; 0.1.2+ moved it to the separate `useChat`
+ * hook, so the same snapshot is the chat projection itself.
+ */
+interface ConversationSnapshotLike extends ChatSnapshotLike {
+    readonly chat?: ChatSnapshotLike;
 }
+/** Selector hook shape shared by `useSession` and `useChat`. */
+type SnapshotSelectorHook = <T>(selector: (snapshot: ConversationSnapshotLike) => T) => T;
 type RewindNodeLike = ConversationNodeLike | ConversationChatNodeLike;
 interface RewindMatch {
     readonly messageSeq: number;
@@ -33,7 +48,8 @@ interface RewindMessageActionProps {
 interface RewindPortalBridgeProps {
     readonly sessionId: string;
     readonly openRestoredSession: (sessionId: string, promptText: string) => Promise<void>;
-    readonly useSession: <T>(selector: (snapshot: ConversationSnapshotLike) => T) => T;
+    readonly useSession: SnapshotSelectorHook;
+    readonly useChat?: SnapshotSelectorHook;
 }
 interface SlotsLike {
     inject(name: string, install: () => unknown): void;
@@ -127,8 +143,20 @@ export declare function selectRewindMessage(node: ConversationNodeLike): RewindM
 /** Browser plugin entry: bridge every direct user-message action row to the rewind UI. */
 export declare const inject: string[];
 export declare function apply(ctx: ClientContextLike): void;
+/**
+ * Resolve the ordered chat node list from one chat projection.
+ *
+ * Both inputs keep a stable identity across renders: `order` is republished only
+ * when the node set changes and the store is a mutable handle, so the caller can
+ * memoize the list instead of allocating a new array on every render (a fresh
+ * array per render makes `useSyncExternalStore` loop forever).
+ * @param order - ordered node keys, or null when the projection is absent.
+ * @param store - keyed node store, a legacy node array, or null.
+ * @returns the chat nodes in render order.
+ */
+export declare function collectChatNodes(order: readonly string[] | null, store: ChatNodeStoreLike | readonly RewindNodeLike[] | null): readonly RewindNodeLike[];
 /** Session-scoped bridge that portals rewind controls into direct user-message action rows. */
-export declare function RewindMessagePortals({ sessionId, openRestoredSession, useSession }: RewindPortalBridgeProps): ReactNode;
+export declare function RewindMessagePortals({ sessionId, openRestoredSession, useSession, useChat }: RewindPortalBridgeProps): ReactNode;
 /** User-message action and its review-first file/conversation restore dialog. */
 export declare function RewindMessageAction({ matched, sessionId, openRestoredSession }: RewindMessageActionProps): ReactNode;
 interface TurnRewindSettingsCardProps {
@@ -143,6 +171,26 @@ export declare function selectRewindMessageTarget(value: RewindNodeLike): {
     readonly matched: RewindMatch;
     readonly rowKey: string;
 } | null;
+/**
+ * Read one rewind response body without ever leaking a raw parse error.
+ *
+ * A missing route, a restarted Host, or a proxy answering before the plugin
+ * loads all produce a body that is not the plugin's JSON envelope; those must
+ * surface as an explained failure instead of `Failed to execute 'json' …`.
+ * @param response - fetch response from the rewind endpoint.
+ * @returns the decoded JSON body.
+ */
+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;
+/**
+ * Explain one recorded checkpoint failure in user terms.
+ *
+ * The Host records the raw `[CODE] diagnostic` line; a non-Git project
+ * directory is the common case and deserves a plain sentence instead of a
+ * `git rev-parse` transcript.
+ * @param message - recorded checkpoint failure message.
+ * @returns one user-facing sentence.
+ */
+export declare function explainCheckpointFailure(message: string): string;
 export {};

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

@@ -13,13 +13,19 @@ interface SessionHeaderLike {
 interface SessionLike {
     readonly id: string;
     readonly header: SessionHeaderLike;
-    readonly events: readonly SessionEventLike[];
+    readonly events?: readonly SessionEventLike[];
+    snapshotEvents?(fromSeq?: number, toSeqExclusive?: number): readonly SessionEventLike[];
 }
 interface AgentLike {
     readonly id: string;
     readonly status: 'idle' | 'running';
     readonly session: SessionLike;
 }
+interface ToolExecutionLike {
+    readonly agent?: AgentLike;
+    readonly parent?: symbol;
+    readonly signal: AbortSignal;
+}
 interface AgentsLike {
     list(): AgentLike[];
 }
@@ -91,6 +97,31 @@ interface ApiProxyLike {
         }>;
     };
 }
+/**
+ * Conversation create/fork capability of the Session controller service.
+ *
+ * DSH 0.1.2-alpha replaced the `apiProxy` RPC envelope with this plain service,
+ * so carriers without `apiProxy` (DSH Desktop 2.x) reach the same capability here.
+ */
+interface SessionControllerLike {
+    create(request: {
+        readonly cwd?: string;
+        readonly workspaceId?: string;
+    }): Promise<{
+        readonly sessionId: string;
+    }>;
+    fork(request: {
+        readonly sessionId: string;
+        readonly atSeq?: number;
+    }): Promise<{
+        readonly sessionId: string;
+    }>;
+}
+/** Services a conversation restart can be built on, in either carrier shape. */
+type ConversationRestartContext = Pick<Context, 'sessions' | 'sessionQuery'> & {
+    readonly apiProxy?: ApiProxyLike;
+    readonly sessionController?: SessionControllerLike;
+};
 declare module '@deepseek-ai/cordis' {
     interface Context {
         agents: AgentsLike;
@@ -98,6 +129,7 @@ declare module '@deepseek-ai/cordis' {
         sessionQuery: SessionQueryLike;
         webServer: HttpServerLike;
         apiProxy: ApiProxyLike;
+        sessionController: SessionControllerLike;
     }
     interface Events {
         'agent/pre-step'(payload: {
@@ -106,10 +138,11 @@ declare module '@deepseek-ai/cordis' {
             readonly step: number;
             readonly signal: AbortSignal;
         }, next: () => Promise<unknown>): Promise<unknown>;
+        'tools/execute'(exec: ToolExecutionLike, next: () => Promise<unknown>): Promise<unknown>;
     }
 }
 export declare const REWIND_HTTP_PATH = "/turn-rewind";
-/** Capture each turn before its opening user message can trigger model or tool work. */
+/** Capture each turn beside model work and gate root tool side effects on its bounded outcome. */
 export declare class TurnCheckpointCoordinator {
     private readonly engine;
     private readonly captures;
@@ -118,7 +151,7 @@ export declare class TurnCheckpointCoordinator {
     private readonly skips;
     private readonly workspaceTails;
     constructor(engine: ChangeLedgerEngine);
-    /** Install the first-step gate; checkpoint failures are recorded but never reject the user turn. */
+    /** Keep sidecar checkpoint work out of the Agent response waterfall. */
     install(ctx: Context): void;
     /** Current capture state for a session turn when no durable checkpoint exists yet. */
     state(sessionId: string, turn: number): {
@@ -126,19 +159,22 @@ export declare class TurnCheckpointCoordinator {
         readonly error?: string;
         readonly reason?: string;
     };
+    private startCapture;
     private capture;
+    /** Wait only for the bounded checkpoint outcome of the Agent's open turn. */
+    private waitForOpenTurn;
     private serializeWorkspace;
     private recordFailure;
 }
 /** Register the same-origin preview/apply endpoint consumed by the browser half. */
 export declare function installRewindHttp(ctx: Context, engine: ChangeLedgerEngine, coordinator: TurnCheckpointCoordinator): void;
+/** Build the exact-route handler as a testable unit. */
+export declare function createRewindHttpHandler(ctx: ConversationRestartContext & {
+    readonly agents?: AgentsLike;
+}, engine: ChangeLedgerEngine, coordinator: TurnCheckpointCoordinator): (request: HttpRequestLike, response: HttpResponseLike) => Promise<void>;
 export declare const MANAGE_HTTP_PATH = "/turn-rewind/manage";
 /** Register the same-origin storage-management endpoint consumed by the settings card. */
 export declare function installManageHttp(ctx: Context, engine: ChangeLedgerEngine): void;
 /** Build the storage-management route as a testable unit. */
 export declare function createManageHttpHandler(engine: ChangeLedgerEngine): (request: HttpRequestLike, response: HttpResponseLike) => Promise<void>;
-/** Build the exact-route handler as a testable unit. */
-export declare function createRewindHttpHandler(ctx: Pick<Context, 'sessions' | 'sessionQuery' | 'apiProxy'> & {
-    readonly agents?: AgentsLike;
-}, engine: ChangeLedgerEngine, coordinator: TurnCheckpointCoordinator): (request: HttpRequestLike, response: HttpResponseLike) => Promise<void>;
 export {};