@aiwayds/dsh-tui-pi 2.6.0 → 2.7.0

package/lib/preset-dialog.js

@@ -0,0 +1,254 @@
+/**
+ * The preset-switch confirmation dialog + the switch orchestration.
+ *
+ * Switching presets is an EXPLICIT action with a visible cost: the preset is
+ * baked into a session at creation time, so applying a new selection means
+ * starting a NEW session — the current one is detached (and stays resumable
+ * via /resume). Whenever a live session exists, the switch therefore goes
+ * through this confirmation gate first (mirroring the /resume repair
+ * dialog's pure-reducer split, src/repair-dialog.ts, so the decision matrix
+ * stays unit-testable without a terminal); on a fresh TUI without a session
+ * there is nothing to leave behind and the selection applies directly.
+ *
+ * The dialog offers exactly three ways out: FORK the current conversation
+ * into the new session on the preset (context weight included), start FRESH
+ * (an empty session on the preset), or CANCEL. Title/body wording
+ * distinguishes a switch to a different preset from a restart on the
+ * current one. ↑↓ moves the selection, `1`/`2`/`3` select directly, Enter
+ * confirms, Esc = cancel. Framing/focus follow the shared overlay contract:
+ * PanelHost framing, close re-focuses the CURRENT editor instance through
+ * `restoreFocus`.
+ */
+import { getKeybindings } from '@earendil-works/pi-tui';
+import { PanelHost, panelThemeFns } from "./panels.js";
+import { BOLD, RESET, ansiFg } from "./theme/index.js";
+import { clipToWidth, wrapText } from "./text.js";
+/** The three choices in display order; index 0 is preselected. */
+export const PRESET_CONFIRM_OPTION_IDS = ['fork', 'fresh', 'cancel'];
+/** The dialog wording for `name`: `restart` marks a re-selection of the current preset. */
+export function presetConfirmWording(name, restart) {
+    return restart
+        ? {
+            title: `● Restart session on ${name}?`,
+            fork: `Fork & restart — new session on ${name}, carrying this conversation`,
+            fresh: `Restart now — new empty session on ${name}`,
+            firstPoint: `Restarting starts a NEW session on ${name}.`,
+        }
+        : {
+            title: `● Switch preset to ${name}?`,
+            fork: `Fork & switch — new session on ${name}, carrying this conversation`,
+            fresh: `Fresh start — new empty session on ${name}`,
+            firstPoint: `Switching starts a NEW session on ${name}.`,
+        };
+}
+/** The fixed option rows for one wording. */
+export function presetConfirmOptions(wording) {
+    return [
+        { id: 'fork', text: wording.fork },
+        { id: 'fresh', text: wording.fresh },
+        { id: 'cancel', text: 'Cancel — stay on the current session' },
+    ];
+}
+/** Accent-BOLD dialog title. */
+export function presetConfirmTitle(wording) {
+    return wording.title;
+}
+/**
+ * The fixed body points, one entry per bullet — each wrapped to the terminal
+ * width by the panel before painting.
+ */
+export function presetConfirmBody(wording) {
+    return [
+        wording.firstPoint,
+        'Fork carries this conversation into the new session (compacted context included) — fresh starts empty.',
+    ];
+}
+/** Footer hint — hardcoded like every other panel footer (English-only). */
+export const PRESET_CONFIRM_FOOTER = '↑↓ select · 1/2/3 pick · Enter confirm · Esc cancel';
+export function initialPresetConfirmState() {
+    return { selected: 0 };
+}
+/**
+ * Apply one raw key sequence to the dialog state. Unknown keys are no-ops;
+ * anything after a settle is ignored (single terminal outcome guard).
+ */
+export function updatePresetConfirm(state, data) {
+    if (state.settled !== undefined)
+        return state;
+    const kb = getKeybindings();
+    if (kb.matches(data, 'tui.select.cancel'))
+        return { ...state, settled: 'cancel' };
+    if (kb.matches(data, 'tui.input.submit'))
+        return { ...state, settled: 'confirm' };
+    if (kb.matches(data, 'tui.select.up')) {
+        return { ...state, selected: Math.max(0, state.selected - 1) };
+    }
+    if (kb.matches(data, 'tui.select.down')) {
+        return { ...state, selected: Math.min(PRESET_CONFIRM_OPTION_IDS.length - 1, state.selected + 1) };
+    }
+    // Digit direct-select (1-based): selects the row, Enter still confirms —
+    // same select-then-confirm split as the routing dialog.
+    const digit = /^([1-9])$/.exec(data);
+    if (digit !== null) {
+        const index = Number(digit[1]) - 1;
+        if (index < PRESET_CONFIRM_OPTION_IDS.length)
+            return { ...state, selected: index };
+    }
+    return state;
+}
+/** Resolved dialog outcome: the chosen action, or undefined on cancel. */
+export function presetConfirmOutcome(state) {
+    if (state.settled !== 'confirm')
+        return undefined;
+    return PRESET_CONFIRM_OPTION_IDS[state.selected];
+}
+/**
+ * The framed overlay component. Renders the title, the wrapped body points
+ * and the three option rows; every key goes through
+ * {@link updatePresetConfirm}, and the first terminal key fires `onFinish`
+ * exactly once.
+ */
+export class PresetConfirmPanel {
+    theme;
+    wording;
+    onFinish;
+    requestRenderFn;
+    state = initialPresetConfirmState();
+    constructor(theme, wording, onFinish, requestRender) {
+        this.theme = theme;
+        this.wording = wording;
+        this.onFinish = onFinish;
+        this.requestRenderFn = requestRender;
+    }
+    invalidate() { }
+    render(width) {
+        const fns = panelThemeFns(this.theme);
+        const wrap = Math.max(2, width - 2);
+        // Word-wrap the body FIRST, then paint (iron rule: width math runs on
+        // plain text, ANSI goes on after clipping).
+        const lines = [
+            fns.accent(BOLD + clipToWidth(presetConfirmTitle(this.wording), wrap) + RESET),
+            ...presetConfirmBody(this.wording).flatMap(point => wrapText(point, wrap).map(segment => fns.muted(clipToWidth(segment, wrap)))),
+            '',
+        ];
+        const options = presetConfirmOptions(this.wording);
+        for (let i = 0; i < options.length; i++) {
+            const option = options[i];
+            const marker = i === this.state.selected ? '▸' : ' ';
+            const row = clipToWidth(`${marker} ${i + 1}. ${option.text}`, wrap);
+            lines.push(i === this.state.selected
+                ? ansiFg(this.theme.palette.accent) + BOLD + row + RESET
+                : fns.muted(row));
+        }
+        lines.push('');
+        lines.push(fns.subtle(clipToWidth(PRESET_CONFIRM_FOOTER, wrap)));
+        return lines;
+    }
+    handleInput(data) {
+        const previous = this.state;
+        this.state = updatePresetConfirm(this.state, data);
+        if (this.state === previous)
+            return;
+        if (this.state.settled === undefined) {
+            this.requestRenderFn();
+            return;
+        }
+        this.onFinish(presetConfirmOutcome(this.state));
+    }
+}
+/**
+ * Open the preset-switch confirmation dialog for one target preset.
+ * Resolves the chosen action (`'fork'` / `'fresh'`) or `'cancelled'` (Esc,
+ * or an overlay that failed to mount — treated as cancel so a half-mounted
+ * dialog can never imply consent). Closing always hands focus back through
+ * `restoreFocus` before the promise settles.
+ */
+export function openPresetConfirmDialog(tui, theme, presetName, restart, restoreFocus) {
+    return new Promise(resolve => {
+        let settled = false;
+        const settle = (outcome) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(outcome);
+        };
+        // A half-mounted overlay must not strand the keyboard: PanelHost's
+        // onError closes + calls restoreFocus, then we settle as cancelled.
+        const host = new PanelHost(tui, theme, () => {
+            restoreFocus();
+            settle('cancelled');
+        });
+        const finish = (outcome) => {
+            host.close();
+            restoreFocus();
+            settle(outcome === 'fork' || outcome === 'fresh' ? outcome : 'cancelled');
+        };
+        const panel = new PresetConfirmPanel(theme, presetConfirmWording(presetName, restart), outcome => finish(outcome), () => tui.requestRender());
+        // maxHeight is a hard slice in pi-tui: title + 2 wrapped body points +
+        // 3 options + footer ≈ 9 content rows + 4 frame rows; 75% of the 24-row
+        // e2e floor is 18 (the /resume picker's headroom).
+        host.open(panel, '70%', '75%');
+    });
+}
+/**
+ * One preset switch, from any entry path (picker Enter, `/preset <name>`,
+ * `/preset next`): with a live session the confirmation dialog gates the
+ * switch — cancelling changes NOTHING (selection index untouched, no
+ * detach); `fresh` commits an empty new session (the /new path); `fork`
+ * commits a new session seeded with the current conversation. Without a
+ * live session the selection applies directly (the first submit already
+ * creates the session on it). Pure with respect to `state` apart from the
+ * commit-index write, and fully injectable.
+ */
+export async function performPresetSwitch(state, target, deps) {
+    if (deps.hasLiveSession()) {
+        const restart = state.roster[state.index]?.id === target.id;
+        const action = await deps.confirmSwitch(target.name, restart);
+        if (action === 'cancel') {
+            return { switched: false, message: 'Preset unchanged — still on the current session.' };
+        }
+        // Snapshot BEFORE the index write: a commit that throws must not leave
+        // the selection (and with it the footer) advertising a preset the live
+        // session is not on.
+        const previousIndex = state.index;
+        const index = state.roster.findIndex(preset => preset.id === target.id);
+        try {
+            if (index >= 0)
+                state.index = index;
+            if (action === 'fork') {
+                await deps.forkCommit(target.id);
+                return { switched: true, message: `Preset → ${target.name} — new session forked from this conversation.` };
+            }
+            await deps.commit(target.id);
+            return { switched: true, message: `Preset → ${target.name} — new empty session started on it.` };
+        }
+        catch (error) {
+            state.index = previousIndex;
+            throw error;
+        }
+    }
+    const index = state.roster.findIndex(preset => preset.id === target.id);
+    if (index >= 0)
+        state.index = index;
+    await deps.commit(target.id);
+    return { switched: true, message: `Preset → ${target.name} — new session started on it.` };
+}
+/**
+ * The balanced completed-turn prefix of a session snapshot: every event up
+ * to and including the last `turn/end` — the in-flight turn is unbalanced
+ * and cannot replay as a valid seed. Contiguous from seq 0 (live sequence
+ * numbers equal array indexes) and empty before any completed turn, in which
+ * case a fork degrades to a fresh session. The same slice the host's fork
+ * subagent backend (`dsh-subagent-fork-in-process`) takes.
+ */
+export function completedTurnSeed(events) {
+    let lastEnd = -1;
+    for (let i = events.length - 1; i >= 0; i--) {
+        if (events[i].type === 'turn/end') {
+            lastEnd = i;
+            break;
+        }
+    }
+    return lastEnd < 0 ? [] : events.slice(0, lastEnd + 1);
+}
+//# sourceMappingURL=preset-dialog.js.map

package/lib/preset-dialog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preset-dialog.js","sourceRoot":"","sources":["../src/preset-dialog.ts"],"names":[],"mappings":"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"}

package/lib/preset.d.ts

@@ -1,16 +1,16 @@
 /**
  * Agent-preset state manager — scans the filesystem for preset directories
  * (same discovery logic as @deepseek-ai/dsh-agent-presets), tracks the user's
- * Tab selection, and formats the footer label.
+ * /preset selection, and formats the footer label.
  *
  * Presets are a dsh deployment concept: each preset composes a session's agent
  * from a different set of plugins/tools. The TUI scans the preset roots once
- * at startup and lets the user cycle through them with Tab; the chosen preset
- * is applied to the next blank session on first submit.
+ * at startup and lets the user switch through /preset; a switch is an explicit,
+ * confirmed action that starts a NEW session on the chosen preset (a fresh TUI
+ * without a live session applies the selection directly).
  *
- * The roster is O(1) to read (an in-memory array); cycle is O(1) mutation of
- * the index. The module is pure except for the async `fetchPresetRoster` which
- * scans the filesystem.
+ * The roster is O(1) to read (an in-memory array). The module is pure except
+ * for the async `fetchPresetRoster` which scans the filesystem.
  */
 /** One preset entry from the deployment roster. */
 export interface PresetEntry {
@@ -55,8 +55,15 @@ export declare function resolvePresetRoots(): PresetRoot[];
  * presets are found.
  */
 export declare function fetchPresetRoster(): Promise<PresetEntry[]>;
-/** Cycle the preset index forward (default) or backward, wrapping around. */
-export declare function cyclePreset(state: PresetState, direction?: 1 | -1): void;
+/**
+ * The entry `/preset next` would switch to — the roster item after the
+ * current selection, wrapping around. PURE (no index mutation): the switch
+ * only commits through the confirmation flow, so `next` must be able to
+ * preview its target first. With 0 or 1 entries there is nothing to switch
+ * to (the caller short-circuits); with ≥2 the result always differs from
+ * the current selection.
+ */
+export declare function peekNextPreset(state: PresetState): PresetEntry | undefined;
 /** Return the currently selected preset, or undefined when the roster is empty. */
 export declare function currentPreset(state: PresetState): PresetEntry | undefined;
 /**
@@ -67,7 +74,7 @@ export declare function currentPreset(state: PresetState): PresetEntry | undefin
 export declare function findPresetByName(state: PresetState, name: string): PresetEntry | undefined;
 /** The preset id selected out of the box when the roster supplies it. It
  *  mirrors the dsh shipped default, but there is no mechanical binding:
- *  until the user interacts with /preset or Tab, the server-side
+ *  until the user switches via /preset, the server-side
  *  `agent-presets.default` setting still governs session creation. */
 export declare const DEFAULT_PRESET_ID = "standard";
 /**

package/lib/preset.js

@@ -1,16 +1,16 @@
 /**
  * Agent-preset state manager — scans the filesystem for preset directories
  * (same discovery logic as @deepseek-ai/dsh-agent-presets), tracks the user's
- * Tab selection, and formats the footer label.
+ * /preset selection, and formats the footer label.
  *
  * Presets are a dsh deployment concept: each preset composes a session's agent
  * from a different set of plugins/tools. The TUI scans the preset roots once
- * at startup and lets the user cycle through them with Tab; the chosen preset
- * is applied to the next blank session on first submit.
+ * at startup and lets the user switch through /preset; a switch is an explicit,
+ * confirmed action that starts a NEW session on the chosen preset (a fresh TUI
+ * without a live session applies the selection directly).
  *
- * The roster is O(1) to read (an in-memory array); cycle is O(1) mutation of
- * the index. The module is pure except for the async `fetchPresetRoster` which
- * scans the filesystem.
+ * The roster is O(1) to read (an in-memory array). The module is pure except
+ * for the async `fetchPresetRoster` which scans the filesystem.
  */
 import { access, readdir, readFile } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
@@ -151,11 +151,18 @@ export async function fetchPresetRoster() {
     }
     return roster;
 }
-/** Cycle the preset index forward (default) or backward, wrapping around. */
-export function cyclePreset(state, direction = 1) {
+/**
+ * The entry `/preset next` would switch to — the roster item after the
+ * current selection, wrapping around. PURE (no index mutation): the switch
+ * only commits through the confirmation flow, so `next` must be able to
+ * preview its target first. With 0 or 1 entries there is nothing to switch
+ * to (the caller short-circuits); with ≥2 the result always differs from
+ * the current selection.
+ */
+export function peekNextPreset(state) {
     if (state.roster.length <= 1)
-        return;
-    state.index = (state.index + direction + state.roster.length) % state.roster.length;
+        return undefined;
+    return state.roster[(state.index + 1) % state.roster.length];
 }
 /** Return the currently selected preset, or undefined when the roster is empty. */
 export function currentPreset(state) {
@@ -174,7 +181,7 @@ export function findPresetByName(state, name) {
 }
 /** The preset id selected out of the box when the roster supplies it. It
  *  mirrors the dsh shipped default, but there is no mechanical binding:
- *  until the user interacts with /preset or Tab, the server-side
+ *  until the user switches via /preset, the server-side
  *  `agent-presets.default` setting still governs session creation. */
 export const DEFAULT_PRESET_ID = 'standard';
 /**

package/lib/preset.js.map

@@ -1 +1 @@
-{"version":3,"file":"preset.js","sourceRoot":"","sources":["../src/preset.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"preset.js","sourceRoot":"","sources":["../src/preset.ts"],"names":[],"mappings":"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"}

package/lib/session.d.ts

@@ -334,6 +334,37 @@ export declare class DshSessionBridge {
      * point; switching away or exiting releases what we established.
      */
     private ownWithLock;
+    /**
+     * Tear down the current live binding — the shared prelude of every session
+     * switch (resume, fork): stop the remote watch, dispose the handle, clear
+     * the subagent tracker and re-seed the model selection (a live /model or
+     * /think choice survives the switch; otherwise the composed default
+     * applies). The renderer keeps its live snapshot across the teardown (it
+     * must survive theme-switch rebuilds), so an empty `onLive` emit is
+     * required to drop the previous session's agents block before the next
+     * session's events rebuild it.
+     */
+    private teardownLiveBinding;
+    /**
+     * Fork-and-switch: create a NEW session seeded with a balanced
+     * completed-turn prefix of the current session's log, then rebind this
+     * bridge to it — the resume lifecycle (teardown, tracker clear, rebind)
+     * over `agents.create` instead of `agents.resume`. The new session carries
+     * durable fork lineage (`parentSession` + `isSeeded` + the inherited
+     * prefix length) and composes under `presetId` (`meta.agentPreset`) — a
+     * seeded USER session, deliberately NOT a subagent child (no
+     * `origin`/delegationDepth, so /resume keeps it and the tracker ignores
+     * it). The seed must be sliced from the live session BEFORE calling this —
+     * the in-memory snapshot is the stable source. The teardown runs FIRST:
+     * `markTuiSurface` provides a cordis service on the agent scope and two
+     * live agents cannot coexist on it (the /new cycle only works because
+     * dispose reclaims the service before the next create). A failed create
+     * therefore leaves the old session DETACHED but fully resumable.
+     * @param seed contiguous-from-0 events ending at a `turn/end` (non-empty).
+     * @param parentSessionId the session the seed came from (durable lineage).
+     * @param presetId the preset id the new session composes under.
+     */
+    forkCurrentSession(seed: readonly SessionEvent[], parentSessionId: SessionId, presetId: string | undefined): Promise<AgentHandle>;
     /**
      * Resume a persisted session: tear down the live agent (disposers are kept —
      * the session-id filter re-binds to the resumed id) and load the persisted
@@ -397,6 +428,16 @@ export declare class DshSessionBridge {
     /** The composed global default (`agent-default-model`) as a plain selection. */
     private composedDefaultSelection;
     /** Create the agent with the composed default model selection. */
+    /**
+     * Create the agent with the composed default model selection. `fork`
+     * seeds the new session with a balanced completed-turn prefix of another
+     * session's log (the preset-switch "Fork & switch" path): durable lineage
+     * (`parentSession` + `isSeeded` + the inherited prefix length) plus the
+     * fork's own `agentPreset` — recording the preset is what keeps the
+     * session's history reconstructable (a cold read that dropped it would
+     * rebuild turns under the wrong composition, the same rule
+     * `childSessionMeta` documents for subagent children).
+     */
     private createSession;
     /** The model selection shown in the footer (live value after `/model`). */
     getSelection(): ModelSelection | undefined;

package/lib/session.js

@@ -12,7 +12,7 @@
 import { installModelSelection } from '@deepseek-ai/dsh-agent';
 import { createUserMessage } from '@deepseek-ai/dsh-llm';
 import { SettingsConflictError } from '@deepseek-ai/dsh-settings';
-import { SessionId } from '@deepseek-ai/dsh-session';
+import { SessionId, SessionLogOffset } from '@deepseek-ai/dsh-session';
 import { readAppendSystem } from "./append-system.js";
 import { join } from 'node:path';
 import { isAgentEnd, isAgentStart, isDcpCompactionNotice, isLlmRetry, isSubagentDescriptor, isTuiPluginInjection } from "./dsh-events.js";
@@ -880,6 +880,60 @@ export class DshSessionBridge {
         };
         return handle;
     }
+    /**
+     * Tear down the current live binding — the shared prelude of every session
+     * switch (resume, fork): stop the remote watch, dispose the handle, clear
+     * the subagent tracker and re-seed the model selection (a live /model or
+     * /think choice survives the switch; otherwise the composed default
+     * applies). The renderer keeps its live snapshot across the teardown (it
+     * must survive theme-switch rebuilds), so an empty `onLive` emit is
+     * required to drop the previous session's agents block before the next
+     * session's events rebuild it.
+     */
+    async teardownLiveBinding() {
+        await this.stopRemoteWatch();
+        const handle = this.handle;
+        this.handle = undefined;
+        this.sessionId = undefined;
+        this.running = false;
+        this.agentViews.clear();
+        this.childSessions.clear();
+        this.trackedSessions.clear();
+        this.runSeqToChild.clear();
+        this.emitLive();
+        if (handle !== undefined)
+            await handle.dispose();
+        this.seedSelectionFromDefault();
+    }
+    /**
+     * Fork-and-switch: create a NEW session seeded with a balanced
+     * completed-turn prefix of the current session's log, then rebind this
+     * bridge to it — the resume lifecycle (teardown, tracker clear, rebind)
+     * over `agents.create` instead of `agents.resume`. The new session carries
+     * durable fork lineage (`parentSession` + `isSeeded` + the inherited
+     * prefix length) and composes under `presetId` (`meta.agentPreset`) — a
+     * seeded USER session, deliberately NOT a subagent child (no
+     * `origin`/delegationDepth, so /resume keeps it and the tracker ignores
+     * it). The seed must be sliced from the live session BEFORE calling this —
+     * the in-memory snapshot is the stable source. The teardown runs FIRST:
+     * `markTuiSurface` provides a cordis service on the agent scope and two
+     * live agents cannot coexist on it (the /new cycle only works because
+     * dispose reclaims the service before the next create). A failed create
+     * therefore leaves the old session DETACHED but fully resumable.
+     * @param seed contiguous-from-0 events ending at a `turn/end` (non-empty).
+     * @param parentSessionId the session the seed came from (durable lineage).
+     * @param presetId the preset id the new session composes under.
+     */
+    async forkCurrentSession(seed, parentSessionId, presetId) {
+        // Teardown FIRST (see docblock): the old agent's scope holds the TUI
+        // surface service the new agent's setup must provide.
+        await this.teardownLiveBinding();
+        const handle = await this.createSession({ seed, parentSessionId, presetId });
+        this.handle = handle;
+        this.sessionId = handle.agent.session.id;
+        this.trackedSessions.add(String(this.sessionId));
+        return handle;
+    }
     /**
      * Resume a persisted session: tear down the live agent (disposers are kept —
      * the session-id filter re-binds to the resumed id) and load the persisted
@@ -900,25 +954,7 @@ export class DshSessionBridge {
         // touching this field, so it always names the id actually loading.
         this.resumeTargetId = sessionId;
         const task = (async () => {
-            await this.stopRemoteWatch();
-            const handle = this.handle;
-            this.handle = undefined;
-            this.sessionId = undefined;
-            this.running = false;
-            this.agentViews.clear();
-            this.childSessions.clear();
-            this.trackedSessions.clear();
-            this.runSeqToChild.clear();
-            // The renderer keeps its live snapshot across the resume teardown (it
-            // must survive theme-switch rebuilds), so an empty emit is required to
-            // drop the previous session's agents block before the resumed log's
-            // workflow events rebuild it.
-            this.emitLive();
-            if (handle !== undefined)
-                await handle.dispose();
-            // Same seeding rule as createSession: a live /model or /think choice
-            // survives the resume; otherwise the composed default applies.
-            this.seedSelectionFromDefault();
+            await this.teardownLiveBinding();
             // Attach arm: the session may already be LIVE in this process — e.g.
             // created by the feishu bot's /new or resumed by it. agents.resume
             // refuses live sessions ("cannot prepare session while it is live"),
@@ -1478,21 +1514,42 @@ export class DshSessionBridge {
             };
     }
     /** Create the agent with the composed default model selection. */
-    async createSession() {
+    /**
+     * Create the agent with the composed default model selection. `fork`
+     * seeds the new session with a balanced completed-turn prefix of another
+     * session's log (the preset-switch "Fork & switch" path): durable lineage
+     * (`parentSession` + `isSeeded` + the inherited prefix length) plus the
+     * fork's own `agentPreset` — recording the preset is what keeps the
+     * session's history reconstructable (a cold read that dropped it would
+     * rebuild turns under the wrong composition, the same rule
+     * `childSessionMeta` documents for subagent children).
+     */
+    async createSession(fork) {
         this.seedSelectionFromDefault();
         // Mint the id HERE so the pre-create lock covers exactly the directory
         // agents.create is about to persist into (same cold-arm guard as resume).
         const sessionId = crypto.randomUUID();
         const cwd = process.cwd();
         const lock = await this.acquireSessionLock(sessionId, cwd);
+        const meta = {
+            cwd,
+            ...this.agentPreset !== undefined ? { agentPreset: this.agentPreset } : {},
+        };
+        if (fork !== undefined) {
+            if (fork.presetId !== undefined)
+                meta.agentPreset = fork.presetId;
+            meta.parentSession = fork.parentSessionId;
+            meta.isSeeded = true;
+        }
         let handle;
         try {
             handle = await this.ctx.agents.create({
                 sessionId: SessionId(sessionId),
-                meta: {
-                    cwd,
-                    ...this.agentPreset !== undefined ? { agentPreset: this.agentPreset } : {},
-                },
+                meta,
+                ...(fork === undefined ? {} : {
+                    seed: fork.seed,
+                    inheritedEventCount: SessionLogOffset(fork.seed.length),
+                }),
                 agentOptions: this.selection ?? {},
                 // Install the mutable selection so `/model` can live-switch the route,
                 // the APPEND_SYSTEM.md section on this agent ONLY (never its