@cjhyy/code-shell-core 0.5.0-rc.1 → 0.6.0-rc.1

package/dist/session/session-manager.js

@@ -7,10 +7,57 @@ import { homedir } from "node:os";
 import { nanoid } from "nanoid";
 import { Transcript } from "./transcript.js";
 import { SessionError } from "../exceptions.js";
+/**
+ * Validate a session ID before it is joined into a filesystem path.
+ *
+ * Internally generated IDs use `nanoid(16)` and are trusted by construction.
+ * But every public entry point (`create`'s explicitSessionId, `resume`,
+ * `exists`, `saveState`'s state.sessionId, `fork`'s sourceSessionId) accepts
+ * an ID from an outside caller — protocol clients, ChatSessionManager-driven
+ * cold starts, persisted state files — and join()'s it into `sessionsDir`.
+ * Without this check a value like "../etc/passwd" or "/tmp/x" would let the
+ * caller escape the sessions directory.
+ *
+ * Exported for direct unit testing.
+ */
+export function assertSafeSessionId(sessionId) {
+    if (typeof sessionId !== "string" || sessionId.length === 0) {
+        throw new SessionError(`invalid session id: must be a non-empty string`);
+    }
+    // basename check: reject any path-shaped value. Covers absolute paths,
+    // POSIX and Windows separators, parent-dir tokens, and the lone "..".
+    if (sessionId.includes("/") || sessionId.includes("\\")) {
+        throw new SessionError(`invalid session id: contains path separator: ${sessionId}`);
+    }
+    if (sessionId === "." || sessionId === ".." || sessionId.includes("..")) {
+        throw new SessionError(`invalid session id: contains parent-dir token: ${sessionId}`);
+    }
+    // Conservative character allow-list: letters, digits, and `-_.` only.
+    // This matches what nanoid emits plus the dotted variants in-house code
+    // already uses (e.g. "tui-main", "agent.foo"). Anything else (NUL,
+    // newline, control chars, shell metacharacters, glob chars) is rejected.
+    if (!/^[A-Za-z0-9_.-]+$/.test(sessionId)) {
+        throw new SessionError(`invalid session id: unexpected characters: ${sessionId}`);
+    }
+    // Cap the length to keep filesystem APIs happy and avoid disk-name DoS.
+    if (sessionId.length > 128) {
+        throw new SessionError(`invalid session id: too long (max 128 chars)`);
+    }
+}
+/**
+ * Resolve the `.code-shell` home dir. `CODE_SHELL_HOME` overrides the default
+ * `~/.code-shell` — mirrors Codex's `CODEX_HOME`. Tests set it to a temp dir
+ * (see bunfig.toml preload) so a `new Engine()` / `new SessionManager()` with
+ * no explicit storageDir doesn't pollute the user's real ~/.code-shell/sessions
+ * with throwaway test sessions (the rm-usage/test-model sidebar junk).
+ */
+export function codeShellHome() {
+    return process.env.CODE_SHELL_HOME || join(homedir(), ".code-shell");
+}
 export class SessionManager {
     sessionsDir;
     constructor(storageDir) {
-        this.sessionsDir = storageDir ?? join(homedir(), ".code-shell", "sessions");
+        this.sessionsDir = storageDir ?? join(codeShellHome(), "sessions");
         mkdirSync(this.sessionsDir, { recursive: true });
     }
     /**
@@ -20,7 +67,12 @@ export class SessionManager {
      * nanoid. Either way the on-disk directory is materialized and the
      * state.json + transcript.jsonl files are written before return.
      */
-    create(cwd, model, provider, explicitSessionId) {
+    create(cwd, model, provider, explicitSessionId, parentSessionId, origin) {
+        // External callers may pass any string; nanoid output is trusted. Either
+        // way the ID gets joined into a filesystem path, so the public entry
+        // point validates before that join.
+        if (explicitSessionId !== undefined)
+            assertSafeSessionId(explicitSessionId);
         const sessionId = explicitSessionId ?? nanoid(16);
         const sessionDir = join(this.sessionsDir, sessionId);
         mkdirSync(sessionDir, { recursive: true });
@@ -34,8 +86,19 @@ export class SessionManager {
             turnCount: 0,
             invokedSkills: [],
             status: "active",
+            // Always write the key: a sub-agent gets its parent sid; a top-level
+            // session gets explicit null. This lets the desktop disk-rebuild tell a
+            // new top-level session (key present, null) apart from a legacy session
+            // (key absent) and from a sub-agent (key present, non-empty string).
+            parentSessionId: parentSessionId ?? null,
+            ...(origin ? { origin } : {}),
         };
-        writeFileSync(join(sessionDir, "state.json"), JSON.stringify(state, null, 2), "utf-8");
+        // Atomic write (tmp+rename) like saveState, so a crash during this one-time
+        // create can't leave a torn state.json that resume() then fails to parse.
+        const stateTarget = join(sessionDir, "state.json");
+        const stateTmp = `${stateTarget}.${process.pid}.${Date.now()}.create.tmp`;
+        writeFileSync(stateTmp, JSON.stringify(state, null, 2), "utf-8");
+        renameSync(stateTmp, stateTarget);
         const transcript = new Transcript(join(sessionDir, "transcript.jsonl"));
         transcript.append("session_meta", {
             sessionId,
@@ -52,9 +115,115 @@ export class SessionManager {
      * without catching SessionError.
      */
     exists(sessionId) {
+        // exists() is a probe — callers use it to decide between resume and
+        // create-with-explicit-sid. Treat an invalid id as "not present"
+        // rather than letting the traversal-shaped string reach existsSync.
+        try {
+            assertSafeSessionId(sessionId);
+        }
+        catch {
+            return false;
+        }
         return existsSync(join(this.sessionsDir, sessionId));
     }
+    /**
+     * Cheap "what cwd is this session bound to?" probe — reads only state.json,
+     * NOT the transcript (unlike resume()). engine.run uses this to recover a
+     * resumed session's project directory when the caller omits options.cwd
+     * (e.g. a desktop host whose sidebar repo selection has drifted to null),
+     * so a project-bound session keeps loading its own agents/settings/memory
+     * instead of falling back to process.cwd(). Returns undefined for an
+     * unknown, malformed, or traversal-shaped id rather than throwing — the
+     * caller treats "no recoverable cwd" the same as "not given".
+     */
+    readCwd(sessionId) {
+        try {
+            assertSafeSessionId(sessionId);
+        }
+        catch {
+            return undefined;
+        }
+        const stateFile = join(this.sessionsDir, sessionId, "state.json");
+        if (!existsSync(stateFile))
+            return undefined;
+        try {
+            const state = JSON.parse(readFileSync(stateFile, "utf-8"));
+            return typeof state.cwd === "string" && state.cwd.length > 0 ? state.cwd : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Cheap "does this session have a persisted goal?" probe — reads only
+     * state.json, NOT the transcript (like readCwd). A persistent goal lives ONLY
+     * in state.activeGoal; it is never appended to the transcript as an event, so
+     * a session rebuilt from disk (e.g. localStorage wiped) can't recover the
+     * goal from its messages. The desktop host calls this on session load to
+     * re-surface the active-goal block + its Cancel button, which would otherwise
+     * be invisible (and thus uncancellable) after a reload of an aborted goal
+     * run. Returns undefined for an unknown / malformed / traversal-shaped id, or
+     * a session with no active goal — never throws.
+     */
+    readActiveGoal(sessionId) {
+        try {
+            assertSafeSessionId(sessionId);
+        }
+        catch {
+            return undefined;
+        }
+        const stateFile = join(this.sessionsDir, sessionId, "state.json");
+        if (!existsSync(stateFile))
+            return undefined;
+        try {
+            const state = JSON.parse(readFileSync(stateFile, "utf-8"));
+            return state.activeGoal;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Disk-only "wipe this session's persistent goal" — the counterpart to
+     * readActiveGoal. Reads state.json, removes state.activeGoal, and rewrites it
+     * atomically (via saveState). Returns true only if a goal was actually
+     * present (idempotent — clearing a session with no goal is a no-op returning
+     * false). Never throws on an unknown / malformed / traversal-shaped id
+     * (returns false), matching readActiveGoal's tolerance.
+     *
+     * Why it lives here and not only on Engine: a persistent goal can strand a
+     * session whose worker is NOT live (aborted/reloaded) — Engine.clearGoal
+     * needs a resumed in-RAM session and a matching in-flight hook, neither of
+     * which exists once the worker has exited. Hosts (the desktop bridge) call
+     * THIS to clear such a goal off disk without spinning up a full Engine.
+     * Engine.clearGoal also delegates its disk write here so the wipe logic lives
+     * in exactly one place.
+     */
+    clearActiveGoal(sessionId) {
+        try {
+            assertSafeSessionId(sessionId);
+        }
+        catch {
+            return false;
+        }
+        const stateFile = join(this.sessionsDir, sessionId, "state.json");
+        if (!existsSync(stateFile))
+            return false;
+        let state;
+        try {
+            state = JSON.parse(readFileSync(stateFile, "utf-8"));
+        }
+        catch {
+            return false;
+        }
+        if (state.activeGoal === undefined)
+            return false;
+        state.activeGoal = undefined;
+        this.saveState(state);
+        return true;
+    }
     resume(sessionId) {
+        assertSafeSessionId(sessionId);
         const sessionDir = join(this.sessionsDir, sessionId);
         if (!existsSync(sessionDir)) {
             throw new SessionError(`Session not found: ${sessionId}`);
@@ -63,13 +232,25 @@ export class SessionManager {
         if (!existsSync(stateFile)) {
             throw new SessionError(`Session state file not found: ${sessionId}`);
         }
-        const state = JSON.parse(readFileSync(stateFile, "utf-8"));
+        let state;
+        try {
+            state = JSON.parse(readFileSync(stateFile, "utf-8"));
+        }
+        catch (err) {
+            // A corrupt state.json (external tampering, disk corruption, or a crash
+            // during the one-time create() write) must surface as a clean SessionError
+            // — not a raw SyntaxError that escapes callers expecting SessionError.
+            throw new SessionError(`Session state is corrupt for ${sessionId}: ${err instanceof Error ? err.message : String(err)}`);
+        }
         const transcriptFile = join(sessionDir, "transcript.jsonl");
         const transcript = Transcript.loadFromFile(transcriptFile);
         state.status = "active";
         return { state, transcript };
     }
     saveState(state) {
+        // state.sessionId could come from a deserialized state.json that was
+        // tampered with on disk. Validate before joining.
+        assertSafeSessionId(state.sessionId);
         const sessionDir = join(this.sessionsDir, state.sessionId);
         mkdirSync(sessionDir, { recursive: true });
         // Atomic write: stage to .tmp, then rename. Protects against two processes
@@ -94,7 +275,7 @@ export class SessionManager {
         newBundle.state.parentSessionId = sourceSessionId;
         // Copy events up to the fork point
         for (const event of events) {
-            if (event.type === "turn_boundary" && event.data.turnNumber > forkTurn) {
+            if (event.type === "turn_boundary" && (event.data.turnNumber ?? -1) > forkTurn) {
                 break;
             }
             newBundle.transcript.append(event.type, event.data);

package/dist/session/simple-diff.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Minimal, dependency-free unified-diff for human-readable previews (e.g. the
+ * /undo confirmation). NOT a patch generator — it's for showing a user "here's
+ * what restoring will change" before they confirm. Uses a standard LCS so the
+ * output reads like a normal diff (unchanged context, -removed, +added).
+ *
+ * `from` is the content currently on disk; `to` is the snapshot we'd restore.
+ * So the preview answers "if I undo, these lines change."
+ */
+/** A single diff line with its marker. */
+export interface DiffLine {
+    marker: " " | "-" | "+";
+    text: string;
+}
+/** Longest-common-subsequence table → minimal -/+ line diff (Myers-equivalent
+ *  result via classic LCS; fine for preview-sized files). */
+export declare function diffLines(from: string, to: string): DiffLine[];
+/**
+ * Render a compact unified-diff string for a preview. Collapses long runs of
+ * unchanged context to at most `context` lines around each change so a small
+ * edit in a big file doesn't print the whole file. Returns "" when identical.
+ */
+export declare function renderDiffPreview(from: string, to: string, context?: number): string;

package/dist/session/simple-diff.js

@@ -0,0 +1,84 @@
+/**
+ * Minimal, dependency-free unified-diff for human-readable previews (e.g. the
+ * /undo confirmation). NOT a patch generator — it's for showing a user "here's
+ * what restoring will change" before they confirm. Uses a standard LCS so the
+ * output reads like a normal diff (unchanged context, -removed, +added).
+ *
+ * `from` is the content currently on disk; `to` is the snapshot we'd restore.
+ * So the preview answers "if I undo, these lines change."
+ */
+/** Longest-common-subsequence table → minimal -/+ line diff (Myers-equivalent
+ *  result via classic LCS; fine for preview-sized files). */
+export function diffLines(from, to) {
+    // Normalize CRLF → LF before splitting so a Windows (CRLF) snapshot vs. an
+    // LF edit doesn't render as every-line-changed in the /undo preview.
+    const a = from.replace(/\r\n/g, "\n").split("\n");
+    const b = to.replace(/\r\n/g, "\n").split("\n");
+    const n = a.length;
+    const m = b.length;
+    // LCS length table.
+    const lcs = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+    for (let i = n - 1; i >= 0; i--) {
+        for (let j = m - 1; j >= 0; j--) {
+            lcs[i][j] = a[i] === b[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+        }
+    }
+    const out = [];
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (a[i] === b[j]) {
+            out.push({ marker: " ", text: a[i] });
+            i++;
+            j++;
+        }
+        else if (lcs[i + 1][j] >= lcs[i][j + 1]) {
+            out.push({ marker: "-", text: a[i] });
+            i++;
+        }
+        else {
+            out.push({ marker: "+", text: b[j] });
+            j++;
+        }
+    }
+    while (i < n)
+        out.push({ marker: "-", text: a[i++] });
+    while (j < m)
+        out.push({ marker: "+", text: b[j++] });
+    return out;
+}
+/**
+ * Render a compact unified-diff string for a preview. Collapses long runs of
+ * unchanged context to at most `context` lines around each change so a small
+ * edit in a big file doesn't print the whole file. Returns "" when identical.
+ */
+export function renderDiffPreview(from, to, context = 3) {
+    const lines = diffLines(from, to);
+    if (lines.every((l) => l.marker === " "))
+        return "";
+    // Mark which lines are within `context` of a change; drop the rest, inserting
+    // a "⋯" gap marker where we elide.
+    const keep = new Array(lines.length).fill(false);
+    for (let k = 0; k < lines.length; k++) {
+        if (lines[k].marker !== " ") {
+            for (let d = -context; d <= context; d++) {
+                const idx = k + d;
+                if (idx >= 0 && idx < lines.length)
+                    keep[idx] = true;
+            }
+        }
+    }
+    const rows = [];
+    let elided = false;
+    for (let k = 0; k < lines.length; k++) {
+        if (keep[k]) {
+            rows.push(`${lines[k].marker}${lines[k].text}`);
+            elided = false;
+        }
+        else if (!elided) {
+            rows.push("⋯");
+            elided = true;
+        }
+    }
+    return rows.join("\n");
+}

package/dist/session/transcript.d.ts

@@ -10,10 +10,34 @@ export declare class Transcript {
     getFilePath(): string;
     constructor(filePath: string);
     append(type: TranscriptEventType, data: Record<string, unknown>): TranscriptEvent;
-    appendMessage(role: string, content: string | ContentBlock[]): TranscriptEvent;
+    /**
+     * Append a chat message to the transcript.
+     *
+     * `injected` marks a synthetic system-reminder turn (e.g. a background-job
+     * completion notification) that is submitted to the model as `role:"user"`
+     * but is NOT the user's own input. The disk reader uses this flag to skip
+     * rendering it as a user bubble on replay (matching the live UI, which never
+     * shows it as a bubble — only the assistant's reply). Real user input and
+     * step-gap steering messages are left unmarked so they render normally.
+     */
+    appendMessage(role: string, content: string | ContentBlock[], opts?: {
+        injected?: boolean;
+    }): TranscriptEvent;
     appendToolUse(toolName: string, toolCallId: string, args: Record<string, unknown>): TranscriptEvent;
     appendToolResult(toolCallId: string, toolName: string, result?: string, error?: string): TranscriptEvent;
+    /** Anchor for a spawned sub-agent (see TranscriptEventType "subagent").
+     *  Written at spawn time so replay can rebuild the sub-agent's card from
+     *  sessions/<agentId>/ — agentId === the sub-agent's session id. */
+    appendSubagent(agentId: string, name: string | undefined, description: string): TranscriptEvent;
     appendTurnBoundary(): TranscriptEvent;
+    /**
+     * Mark the in-flight turn as user-interrupted (Stop). Persisted so a resume
+     * rebuilds the renderer's "stopped" marker (foldTranscript) — otherwise the
+     * interrupted turn folds behind the process-card header on reload.
+     * Idempotent: a no-op if the last event is already a turn_stopped (the loop
+     * can hit more than one abort return for a single Stop).
+     */
+    appendTurnStopped(): TranscriptEvent | undefined;
     appendSummary(summary: string, compactedRange: {
         fromTurn: number;
         toTurn: number;

package/dist/session/transcript.js

@@ -29,8 +29,22 @@ export class Transcript {
         this.flush(event);
         return event;
     }
-    appendMessage(role, content) {
-        return this.append("message", { role, content });
+    /**
+     * Append a chat message to the transcript.
+     *
+     * `injected` marks a synthetic system-reminder turn (e.g. a background-job
+     * completion notification) that is submitted to the model as `role:"user"`
+     * but is NOT the user's own input. The disk reader uses this flag to skip
+     * rendering it as a user bubble on replay (matching the live UI, which never
+     * shows it as a bubble — only the assistant's reply). Real user input and
+     * step-gap steering messages are left unmarked so they render normally.
+     */
+    appendMessage(role, content, opts) {
+        return this.append("message", {
+            role,
+            content,
+            ...(opts?.injected ? { injected: true } : {}),
+        });
     }
     appendToolUse(toolName, toolCallId, args) {
         return this.append("tool_use", { toolName, toolCallId, args });
@@ -38,10 +52,29 @@ export class Transcript {
     appendToolResult(toolCallId, toolName, result, error) {
         return this.append("tool_result", { toolCallId, toolName, result, error });
     }
+    /** Anchor for a spawned sub-agent (see TranscriptEventType "subagent").
+     *  Written at spawn time so replay can rebuild the sub-agent's card from
+     *  sessions/<agentId>/ — agentId === the sub-agent's session id. */
+    appendSubagent(agentId, name, description) {
+        return this.append("subagent", { agentId, name, description });
+    }
     appendTurnBoundary() {
         this.currentTurn++;
         return this.append("turn_boundary", { turnNumber: this.currentTurn });
     }
+    /**
+     * Mark the in-flight turn as user-interrupted (Stop). Persisted so a resume
+     * rebuilds the renderer's "stopped" marker (foldTranscript) — otherwise the
+     * interrupted turn folds behind the process-card header on reload.
+     * Idempotent: a no-op if the last event is already a turn_stopped (the loop
+     * can hit more than one abort return for a single Stop).
+     */
+    appendTurnStopped() {
+        const last = this.events[this.events.length - 1];
+        if (last && last.type === "turn_stopped")
+            return undefined;
+        return this.append("turn_stopped", {});
+    }
     appendSummary(summary, compactedRange) {
         return this.append("summary", {
             summary,

package/dist/session/undo-target.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Pure selection of the "most recent file modification" to undo, given a
+ * FileHistory snapshot list. Kept fs-free so the "what does /undo target"
+ * decision is unit-testable and shared between the TUI command and any future
+ * desktop entry point.
+ *
+ * A snapshot is the *pre-modification* backup of a file (see file-history.ts:
+ * saveSnapshot runs before Write/Edit/ApplyPatch). So the newest snapshot's
+ * backup is the content to restore for a single-step undo: it is the state the
+ * file had immediately before the last edit.
+ */
+import type { FileSnapshot, RedoRecord } from "./file-history.js";
+/**
+ * The snapshot for the most recent modification. Returns the entry with the
+ * greatest `timestamp`; on a tie (same-millisecond snapshots of different
+ * files) the LAST such entry in array order wins — saveSnapshot pushes in
+ * chronological order, so the last pushed is the most recently recorded, which
+ * is the stable, predictable choice. Returns null for an empty history.
+ */
+export declare function latestUndoTarget(snapshots: FileSnapshot[]): FileSnapshot | null;
+/**
+ * For "/undo all": each tracked file's EARLIEST snapshot — its content before
+ * the *first* AI edit this session. Restoring all of these reverts the whole
+ * session's file changes (vs. latestUndoTarget, which is the single last step).
+ *
+ * Returns one snapshot per file path, ordered by that file's first-edit time
+ * (oldest first) so a preview reads chronologically. On a same-millisecond tie
+ * for a given file, the FIRST array entry wins (earliest recorded).
+ */
+export declare function earliestSnapshotsPerFile(snapshots: FileSnapshot[]): FileSnapshot[];
+/**
+ * For turn-level "/undo": the snapshots needed to revert just the MOST RECENT
+ * conversation turn (one user message = one turn, see SessionState.turnSeq).
+ *
+ * The latest turn = the greatest `turnSeq` present. A turn boundary is defined
+ * by turnSeq, NOT wall-clock — a clock skew must not move the boundary. Within
+ * that turn, each touched file is restored to its EARLIEST snapshot of the turn
+ * (its content before the *first* edit that turn), so re-editing a file twice
+ * in one turn still reverts to the pre-turn baseline — and edits from *earlier*
+ * turns are left intact (that's the whole point vs. earliestSnapshotsPerFile,
+ * which spans the whole session).
+ *
+ * Backward compatibility: snapshots written before this feature have no
+ * `turnSeq`. They share the `undefined` bucket. `undefined` sorts as the
+ * smallest "turn", so any real (tagged) turn supersedes the legacy bucket; a
+ * history that is ALL-legacy degrades to whole-session behaviour (each file's
+ * earliest) rather than throwing.
+ *
+ * Returns one snapshot per file, ordered by that file's first-edit time within
+ * the turn (oldest first) so a preview reads chronologically. Empty → [].
+ */
+export declare function latestTurnUndoTargets(snapshots: FileSnapshot[]): FileSnapshot[];
+/**
+ * For "/redo": the RedoRecord[] of the MOST RECENT undone turn — the turn that
+ * `redoLatestTurn` should re-apply — but ONLY when that turn is still the latest
+ * undone state (i.e. nothing newer happened since the undo). Otherwise [].
+ *
+ * Rule: let R = the greatest turnSeq present in `redoRecords` (a RedoRecord
+ * exists only for a turn that was undone and not yet redone). R is redoable iff
+ * NO snapshot belongs to a strictly newer LIVE (non-undone) turn — a fresh edit
+ * after the undo supersedes the redo and invalidates it (spec: "新轮使 redo
+ * 失效"). Created-only turns have no pre-turn snapshot, so the RedoRecord itself
+ * is the sole evidence and is honoured as long as nothing newer superseded it.
+ *
+ * Empty `redoRecords` → []. fs-free so /redo's target decision is unit-testable.
+ */
+export declare function latestRedoTargets(redoRecords: RedoRecord[], snapshots: FileSnapshot[]): RedoRecord[];

package/dist/session/undo-target.js

@@ -0,0 +1,144 @@
+/**
+ * Pure selection of the "most recent file modification" to undo, given a
+ * FileHistory snapshot list. Kept fs-free so the "what does /undo target"
+ * decision is unit-testable and shared between the TUI command and any future
+ * desktop entry point.
+ *
+ * A snapshot is the *pre-modification* backup of a file (see file-history.ts:
+ * saveSnapshot runs before Write/Edit/ApplyPatch). So the newest snapshot's
+ * backup is the content to restore for a single-step undo: it is the state the
+ * file had immediately before the last edit.
+ */
+/**
+ * The snapshot for the most recent modification. Returns the entry with the
+ * greatest `timestamp`; on a tie (same-millisecond snapshots of different
+ * files) the LAST such entry in array order wins — saveSnapshot pushes in
+ * chronological order, so the last pushed is the most recently recorded, which
+ * is the stable, predictable choice. Returns null for an empty history.
+ */
+export function latestUndoTarget(snapshots) {
+    let best = null;
+    for (const s of snapshots) {
+        // `>=` so a later array entry with an equal timestamp supersedes an
+        // earlier one (last-pushed wins on a tie).
+        if (best === null || s.timestamp >= best.timestamp)
+            best = s;
+    }
+    return best;
+}
+/**
+ * For "/undo all": each tracked file's EARLIEST snapshot — its content before
+ * the *first* AI edit this session. Restoring all of these reverts the whole
+ * session's file changes (vs. latestUndoTarget, which is the single last step).
+ *
+ * Returns one snapshot per file path, ordered by that file's first-edit time
+ * (oldest first) so a preview reads chronologically. On a same-millisecond tie
+ * for a given file, the FIRST array entry wins (earliest recorded).
+ */
+export function earliestSnapshotsPerFile(snapshots) {
+    const earliest = new Map();
+    for (const s of snapshots) {
+        // Undone snapshots belong to a reverted turn: their content is no longer on
+        // disk and they are not the session baseline, so skip them — otherwise an
+        // undone (earlier) snapshot could win the baseline and `/undo all` would
+        // restore stale content.
+        if (s.undone)
+            continue;
+        const cur = earliest.get(s.filePath);
+        // strict `<` so the first-seen entry wins on a tie (earliest recorded).
+        if (!cur || s.timestamp < cur.timestamp)
+            earliest.set(s.filePath, s);
+    }
+    return [...earliest.values()].sort((a, b) => a.timestamp - b.timestamp);
+}
+/**
+ * For turn-level "/undo": the snapshots needed to revert just the MOST RECENT
+ * conversation turn (one user message = one turn, see SessionState.turnSeq).
+ *
+ * The latest turn = the greatest `turnSeq` present. A turn boundary is defined
+ * by turnSeq, NOT wall-clock — a clock skew must not move the boundary. Within
+ * that turn, each touched file is restored to its EARLIEST snapshot of the turn
+ * (its content before the *first* edit that turn), so re-editing a file twice
+ * in one turn still reverts to the pre-turn baseline — and edits from *earlier*
+ * turns are left intact (that's the whole point vs. earliestSnapshotsPerFile,
+ * which spans the whole session).
+ *
+ * Backward compatibility: snapshots written before this feature have no
+ * `turnSeq`. They share the `undefined` bucket. `undefined` sorts as the
+ * smallest "turn", so any real (tagged) turn supersedes the legacy bucket; a
+ * history that is ALL-legacy degrades to whole-session behaviour (each file's
+ * earliest) rather than throwing.
+ *
+ * Returns one snapshot per file, ordered by that file's first-edit time within
+ * the turn (oldest first) so a preview reads chronologically. Empty → [].
+ */
+export function latestTurnUndoTargets(snapshots) {
+    if (snapshots.length === 0)
+        return [];
+    // Find the latest turn, SKIPPING undone turns: once a turn is undone (marked,
+    // not deleted) its snapshots stay on disk for redo but must not be re-selected
+    // by undo — so the next /undo peels the prior live turn ("onion" behaviour).
+    // undefined (legacy) is treated as the smallest turn so it loses to any tagged
+    // turn; a key of `-Infinity` models that ordering.
+    const turnKey = (s) => s.turnSeq ?? -Infinity;
+    let maxTurn = -Infinity;
+    let found = false;
+    for (const s of snapshots) {
+        if (s.undone)
+            continue;
+        const k = turnKey(s);
+        if (k > maxTurn)
+            maxTurn = k;
+        found = true;
+    }
+    if (!found)
+        return [];
+    // Within the latest live turn, each file's earliest snapshot = its pre-turn
+    // state. Undone snapshots are skipped here too (defensive: they share neither
+    // the selected turn nor the baseline).
+    const earliest = new Map();
+    for (const s of snapshots) {
+        if (s.undone)
+            continue;
+        if (turnKey(s) !== maxTurn)
+            continue;
+        const cur = earliest.get(s.filePath);
+        // strict `<` so the first-seen entry wins on a same-ms tie (earliest).
+        if (!cur || s.timestamp < cur.timestamp)
+            earliest.set(s.filePath, s);
+    }
+    return [...earliest.values()].sort((a, b) => a.timestamp - b.timestamp);
+}
+/**
+ * For "/redo": the RedoRecord[] of the MOST RECENT undone turn — the turn that
+ * `redoLatestTurn` should re-apply — but ONLY when that turn is still the latest
+ * undone state (i.e. nothing newer happened since the undo). Otherwise [].
+ *
+ * Rule: let R = the greatest turnSeq present in `redoRecords` (a RedoRecord
+ * exists only for a turn that was undone and not yet redone). R is redoable iff
+ * NO snapshot belongs to a strictly newer LIVE (non-undone) turn — a fresh edit
+ * after the undo supersedes the redo and invalidates it (spec: "新轮使 redo
+ * 失效"). Created-only turns have no pre-turn snapshot, so the RedoRecord itself
+ * is the sole evidence and is honoured as long as nothing newer superseded it.
+ *
+ * Empty `redoRecords` → []. fs-free so /redo's target decision is unit-testable.
+ */
+export function latestRedoTargets(redoRecords, snapshots) {
+    if (redoRecords.length === 0)
+        return [];
+    let maxRedoTurn = -Infinity;
+    for (const r of redoRecords) {
+        if (r.turnSeq > maxRedoTurn)
+            maxRedoTurn = r.turnSeq;
+    }
+    // If any LIVE snapshot belongs to a strictly newer turn, the redo turn is no
+    // longer the latest undone state → not redoable.
+    for (const s of snapshots) {
+        if (s.undone)
+            continue;
+        const k = s.turnSeq ?? -Infinity;
+        if (k > maxRedoTurn)
+            return [];
+    }
+    return redoRecords.filter((r) => r.turnSeq === maxRedoTurn);
+}