@pikiloom/kernel 0.3.11 → 0.3.12

package/dist/contracts/driver.d.ts

@@ -3,6 +3,9 @@ export interface AgentTurnInput {
     prompt: string;
     attachments?: string[];
     sessionId?: string | null;
+    fork?: {
+        anchor?: string | null;
+    } | null;
     workdir: string;
     model?: string | null;
     effort?: string | null;
@@ -68,6 +71,7 @@ export interface DriverResult {
     stopReason?: string | null;
     sessionId?: string | null;
     usage?: UniversalUsage | null;
+    anchor?: string | null;
 }
 export interface TuiInput {
     workdir: string;
@@ -101,6 +105,7 @@ export interface AgentDriver {
         interact?: boolean;
         resume?: boolean;
         tui?: boolean;
+        fork?: boolean;
     };
     run(input: AgentTurnInput, ctx: DriverContext): Promise<DriverResult>;
     tui?(input: TuiInput): TuiSpec;
@@ -108,4 +113,8 @@ export interface AgentDriver {
         workdir: string;
         limit?: number;
     }): NativeSessionInfo[] | Promise<NativeSessionInfo[]>;
+    resolveNativeAnchor?(opts: {
+        sessionId: string;
+        workdir: string;
+    }): string | null | Promise<string | null>;
 }

package/dist/contracts/ports.d.ts

@@ -16,6 +16,15 @@ export interface CoreSessionRecord {
     runDetail?: string | null;
     runPid?: number | null;
     runStartedAt?: number | null;
+    forkedFrom?: {
+        sessionKey: string;
+        taskId?: string | null;
+    } | null;
+    pendingFork?: {
+        parentNativeSessionId: string | null;
+        anchor: string | null;
+        mode: 'native' | 'seed';
+    } | null;
 }
 export interface SessionStore {
     ensure(agent: string, opts: {

package/dist/contracts/surface.d.ts

@@ -9,11 +9,20 @@ export interface PromptInput {
     effort?: string | null;
     attachments?: string[];
 }
+export interface ForkSessionInput {
+    fromSessionKey: string;
+    atTaskId?: string | null;
+    anchor?: string | null;
+    title?: string | null;
+}
 export interface LoomIO {
     prompt(input: PromptInput): Promise<{
         sessionKey: string;
         taskId: string;
     }>;
+    forkSession(input: ForkSessionInput): Promise<{
+        sessionKey: string;
+    }>;
     stop(sessionKey: string): boolean;
     steer(taskId: string, prompt: string, attachments?: string[]): Promise<boolean>;
     interact(promptId: string, action: 'select' | 'text' | 'skip' | 'cancel', value?: string): boolean;

package/dist/drivers/claude.d.ts

@@ -8,6 +8,7 @@ export declare class ClaudeDriver implements AgentDriver {
         interact: boolean;
         resume: boolean;
         tui: boolean;
+        fork: boolean;
     };
     constructor(bin?: string);
     tui(input: TuiInput): TuiSpec;
@@ -17,7 +18,14 @@ export declare class ClaudeDriver implements AgentDriver {
     }): NativeSessionInfo[];
     run(input: AgentTurnInput, ctx: DriverContext): Promise<DriverResult>;
     private usage;
+    resolveNativeAnchor(opts: {
+        sessionId: string;
+        workdir: string;
+    }): string | null;
 }
+export declare function claudeResumeArgs(sessionId: string, fork?: {
+    anchor?: string | null;
+} | null): string[];
 export declare function handleClaudeEvent(ev: any, s: any, emit: (e: DriverEvent) => void): void;
 export declare function claudeBgHoldCapMs(): number;
 export declare function claudeBgAgentHoldCapMs(): number;
@@ -34,6 +42,7 @@ export declare function claudeResumeNoopRetryLimit(): number;
 export declare function claudeUserEventHasToolResult(ev: any): boolean;
 export declare function isTerminalTaskStatus(status: unknown): boolean;
 export declare function trackClaudeBackgroundTask(ev: any, s: any): void;
+export declare function sameClaudeText(a: string, b: string): boolean;
 export declare function markClaudeTaskNotificationTerminal(content: any, s: any): void;
 export declare function pendingClaudeBackgroundTasks(s: any): number;
 export declare function claudeTurnEndedDangling(s: any): boolean;

package/dist/drivers/claude.js

@@ -1,6 +1,6 @@
 import { spawn } from 'node:child_process';
 import { readFileSync } from 'node:fs';
-import { discoverClaudeNativeSessions } from './native.js';
+import { claudeTranscriptTailAnchor, discoverClaudeNativeSessions } from './native.js';
 import { attachedFileNote, contextPercent, createLineBuffer, imageMimeForFile, parseJsonLine, sigterm, wireAbort } from './shared.js';
 // Real driver: shells the local `claude` CLI in stream-json mode and normalizes its
 // events into kernel DriverEvents. Faithful to pikiloom's claude.ts event shapes
@@ -9,7 +9,7 @@ import { attachedFileNote, contextPercent, createLineBuffer, imageMimeForFile, p
 export class ClaudeDriver {
     bin;
     id = 'claude';
-    capabilities = { steer: true, interact: false, resume: true, tui: true };
+    capabilities = { steer: true, interact: false, resume: true, tui: true, fork: true };
     constructor(bin = 'claude') {
         this.bin = bin;
     }
@@ -43,7 +43,7 @@ export class ClaudeDriver {
         if (input.effort)
             args.push('--effort', input.effort === 'ultra' ? 'max' : input.effort); // request extended thinking (ultra is a display-only alias for max)
         if (input.sessionId)
-            args.push('--resume', input.sessionId);
+            args.push(...claudeResumeArgs(input.sessionId, input.fork));
         if (input.systemPrompt)
             args.push('--append-system-prompt', input.systemPrompt);
         if (input.mcpConfigPath)
@@ -62,6 +62,9 @@ export class ClaudeDriver {
             // Wall-clock of the last parsed stream event — the hold cap defers while this is fresh.
             lastEventAt: Date.now(),
             sessionId: null, model: null,
+            // Fork anchor: uuid of the latest REAL assistant transcript record seen this turn —
+            // the inclusive keep-boundary a later fork of this session passes to --resume-session-at.
+            anchor: null,
             stopReason: null, error: null,
             input: null, output: null, cached: null,
             cacheCreation: null,
@@ -138,7 +141,7 @@ export class ClaudeDriver {
             };
             const settleResult = (opts = {}) => finish({
                 ok: opts.ok ?? !state.error, text: state.text, reasoning: state.reasoning || undefined,
-                error: state.error, stopReason: opts.stopReason ?? state.stopReason, sessionId: state.sessionId, usage: usageOf(),
+                error: state.error, stopReason: opts.stopReason ?? state.stopReason, sessionId: state.sessionId, anchor: state.anchor, usage: usageOf(),
             }, opts.kill ?? true);
             // Cap while holding for a still-running background task (stopReason marks it as
             // "still running in the background" so the terminal presentation reads right). Idempotent —
@@ -336,7 +339,7 @@ export class ClaudeDriver {
                 if (settled)
                     return;
                 if (ctx.signal.aborted) {
-                    finish({ ok: false, text: state.text, reasoning: state.reasoning, error: 'Interrupted by user.', stopReason: 'interrupted', sessionId: state.sessionId, usage: usageOf() }, false);
+                    finish({ ok: false, text: state.text, reasoning: state.reasoning, error: 'Interrupted by user.', stopReason: 'interrupted', sessionId: state.sessionId, anchor: state.anchor, usage: usageOf() }, false);
                     return;
                 }
                 const ok = !state.error && code === 0;
@@ -345,7 +348,7 @@ export class ClaudeDriver {
                 // (state.stopReason is typically the tool round's leftover 'tool_use' here, so the
                 // dangling check must win over it.)
                 const stopReason = (ok && claudeTurnEndedDangling(state)) ? 'truncated' : state.stopReason;
-                finish({ ok, text: state.text, reasoning: state.reasoning || undefined, error: state.error || (ok ? null : `claude exited ${code}${stderr ? `: ${stderr.slice(0, 300)}` : ''}`), stopReason, sessionId: state.sessionId, usage: usageOf() }, false);
+                finish({ ok, text: state.text, reasoning: state.reasoning || undefined, error: state.error || (ok ? null : `claude exited ${code}${stderr ? `: ${stderr.slice(0, 300)}` : ''}`), stopReason, sessionId: state.sessionId, anchor: state.anchor, usage: usageOf() }, false);
             });
             try {
                 // Send the prompt as a stream-json user message and keep stdin OPEN (do not end it here):
@@ -358,6 +361,23 @@ export class ClaudeDriver {
     usage(s) {
         return claudeUsageOf(s);
     }
+    // Current tail keep-boundary of a native session: the uuid of the last user/assistant
+    // record in its transcript. Pins a tail fork at fork time (see AgentDriver contract).
+    resolveNativeAnchor(opts) {
+        return claudeTranscriptTailAnchor(opts.workdir, opts.sessionId);
+    }
+}
+// The --resume flag family for one turn: plain resume appends to the session; a fork branches
+// a NEW session off it (--fork-session), optionally cut at an inclusive keep-boundary record
+// uuid (--resume-session-at). Pure so tests can pin the arg contract without spawning.
+export function claudeResumeArgs(sessionId, fork) {
+    const args = ['--resume', sessionId];
+    if (fork) {
+        args.push('--fork-session');
+        if (fork.anchor)
+            args.push('--resume-session-at', fork.anchor);
+    }
+    return args;
 }
 function claudeUsageOf(s) {
     // While a message is still streaming, the CLI's live thinking estimate (system/thinking_tokens)
@@ -557,6 +577,10 @@ export function handleClaudeEvent(ev, s, emit) {
             }
             return;
         }
+        // A real assistant event's uuid IS its persisted transcript record uuid — track the
+        // latest as this turn's fork anchor (inclusive keep-boundary for --resume-session-at).
+        if (typeof ev.uuid === 'string' && ev.uuid)
+            s.anchor = ev.uuid;
         const contents = ev.message?.content || [];
         for (const b of contents) {
             if (b?.type !== 'tool_use')
@@ -728,6 +752,15 @@ export function handleClaudeEvent(ev, s, emit) {
                 : (typeof ev.result === 'string' && ev.result.trim() ? ev.result.trim()
                     : `claude ended the turn with an error result${subtype ? ` (${subtype})` : ''}`);
         }
+        // When the WHOLE assistant body is that same error notice — a spend/usage-limit hit or a
+        // permission refusal the CLI narrates as a message AND flags the `result` an error, so the
+        // identical text lands in BOTH s.text and s.error — the turn is a single notice, not an
+        // answer-plus-red-echo. Drop the duplicate body so it renders once (as the error notice).
+        // Only exact-equal collapses: a real reply that merely ENDS with an error keeps both.
+        if (s.error && s.text.trim() && sameClaudeText(s.text, s.error)) {
+            s.text = '';
+            s.streamedText = false;
+        }
         if (!isErrorResult && typeof ev.result === 'string' && ev.result.trim()) {
             if (!s.text.trim())
                 s.text = ev.result;
@@ -909,6 +942,12 @@ function claudeContentText(content) {
         return content.filter((b) => b?.type === 'text' && typeof b.text === 'string').map((b) => b.text).join('\n');
     return '';
 }
+// Whitespace-insensitive text equality — the error notice (a trimmed `result` string) and the
+// streamed body (may carry trailing newlines / soft breaks) can differ only in whitespace yet be
+// the same message. Used to collapse an error that IS the whole body (see the result handler).
+export function sameClaudeText(a, b) {
+    return a.replace(/\s+/g, ' ').trim() === b.replace(/\s+/g, ' ').trim();
+}
 // Extra completion signal (mirrors the legacy driver): Claude delivers a background wake-up as a
 // `type:'user'` message carrying a `<task-notification>` tag (<task-id>/<tool-use-id>/<status>).
 // Mark that task terminal too, so a missed/absent system task_notification still lets pending

package/dist/drivers/codex.d.ts

@@ -27,6 +27,7 @@ export declare class CodexDriver implements AgentDriver {
         interact: boolean;
         resume: boolean;
         tui: boolean;
+        fork: boolean;
     };
     constructor(bin?: string);
     run(input: AgentTurnInput, ctx: DriverContext): Promise<DriverResult>;
@@ -35,4 +36,8 @@ export declare class CodexDriver implements AgentDriver {
         workdir: string;
         limit?: number;
     }): NativeSessionInfo[];
+    resolveNativeAnchor(opts: {
+        sessionId: string;
+        workdir: string;
+    }): string | null;
 }

package/dist/drivers/codex.js

@@ -1,4 +1,4 @@
-import { discoverCodexNativeSessions } from './native.js';
+import { codexRolloutTailAnchor, discoverCodexNativeSessions } from './native.js';
 import { StdioRpcClient } from './rpc.js';
 import { attachedFileNote, contextPercent, imageMimeForFile, wireAbort } from './shared.js';
 function planFromUpdate(params) {
@@ -237,7 +237,7 @@ export function codexFinalReasoning(s) {
 export class CodexDriver {
     bin;
     id = 'codex';
-    capabilities = { steer: true, interact: false, resume: true, tui: true };
+    capabilities = { steer: true, interact: false, resume: true, tui: true, fork: true };
     constructor(bin = 'codex') {
         this.bin = bin;
     }
@@ -306,11 +306,15 @@ export class CodexDriver {
                 threadParams.approvalPolicy = 'never';
                 threadParams.sandbox = 'danger-full-access';
             }
+            // Fork-on-dispatch: thread/fork copies the parent's stored history into a NEW thread
+            // (inclusive cut at lastTurnId when an anchor is pinned) and never mutates the parent.
             const threadResp = input.sessionId
-                ? await srv.request('thread/resume', { threadId: input.sessionId, ...threadParams })
+                ? (input.fork
+                    ? await srv.request('thread/fork', { threadId: input.sessionId, ...threadParams, ...(input.fork.anchor ? { lastTurnId: input.fork.anchor } : {}) })
+                    : await srv.request('thread/resume', { threadId: input.sessionId, ...threadParams }))
                 : await srv.request('thread/start', threadParams);
             if (threadResp.error)
-                return { ok: false, text: '', error: threadResp.error.message || 'thread/start failed', stopReason: 'error' };
+                return { ok: false, text: '', error: threadResp.error.message || (input.fork ? 'thread/fork failed' : 'thread/start failed'), stopReason: 'error' };
             const threadId = threadResp.result?.thread?.id ?? input.sessionId ?? null;
             if (threadId && threadId !== state.sessionId) {
                 state.sessionId = threadId;
@@ -495,6 +499,8 @@ export class CodexDriver {
                 error: state.error || (ctx.signal.aborted ? 'Interrupted by user.' : null),
                 stopReason: ctx.signal.aborted ? 'interrupted' : (state.status || 'end_turn'),
                 sessionId: state.sessionId,
+                // Fork anchor: the turn id is the inclusive keep-boundary thread/fork's lastTurnId takes.
+                anchor: state.turnId,
                 usage,
             };
         }
@@ -513,6 +519,11 @@ export class CodexDriver {
     listNativeSessions(opts) {
         return discoverCodexNativeSessions(opts.workdir, { limit: opts.limit });
     }
+    // Current tail keep-boundary of a native thread: the last turn id in its rollout.
+    // Pins a tail fork at fork time (see AgentDriver contract).
+    resolveNativeAnchor(opts) {
+        return codexRolloutTailAnchor(opts.sessionId);
+    }
 }
 function buildTurnInput(prompt, attachments) {
     const input = [];

package/dist/drivers/native.d.ts

@@ -11,3 +11,7 @@ export declare function encodeClaudeProjectDir(workdir: string): string;
 export declare function discoverClaudeNativeSessions(workdir: string, opts?: DiscoverOptions): NativeSessionInfo[];
 export declare function discoverCodexNativeSessions(workdir: string, opts?: DiscoverOptions): NativeSessionInfo[];
 export declare function discoverGeminiNativeSessions(workdir: string, opts?: DiscoverOptions): NativeSessionInfo[];
+/** Claude: uuid of the last user/assistant record in the session's transcript. */
+export declare function claudeTranscriptTailAnchor(workdir: string, sessionId: string, opts?: DiscoverOptions): string | null;
+/** Codex: the last turn id recorded in the session's rollout. */
+export declare function codexRolloutTailAnchor(sessionId: string, opts?: DiscoverOptions): string | null;

package/dist/drivers/native.js

@@ -505,3 +505,98 @@ export function discoverGeminiNativeSessions(workdir, opts = {}) {
     const out = [...byId.values()].sort((a, b) => Date.parse(b.updatedAt || '') - Date.parse(a.updatedAt || ''));
     return typeof opts.limit === 'number' ? out.slice(0, Math.max(0, opts.limit)) : out;
 }
+// ---- Fork anchors: the CURRENT tail keep-boundary of a native transcript ----
+// Same terms as AgentTurnInput.fork.anchor: claude = transcript record uuid, codex = turn id.
+// Used by fork-capable drivers' resolveNativeAnchor so Hub.forkSession can pin a tail cut at
+// fork time (the branch must not absorb turns the parent runs afterwards). Bounded tail reads.
+/** Claude: uuid of the last user/assistant record in the session's transcript. */
+export function claudeTranscriptTailAnchor(workdir, sessionId, opts = {}) {
+    const home = homeOf(opts);
+    const filePath = path.join(home, '.claude', 'projects', encodeClaudeProjectDir(workdir), `${sessionId}.jsonl`);
+    const stat = statSafe(filePath);
+    if (!stat)
+        return null;
+    let anchor = null;
+    try {
+        const start = Math.max(0, stat.size - TAIL_BYTES);
+        for (const line of readRegion(filePath, start, Math.min(TAIL_BYTES, stat.size)).split('\n')) {
+            const t = line.trim();
+            if (!t || t[0] !== '{')
+                continue;
+            let ev;
+            try {
+                ev = JSON.parse(t);
+            }
+            catch {
+                continue;
+            }
+            if ((ev.type === 'assistant' || ev.type === 'user') && typeof ev.uuid === 'string' && ev.uuid)
+                anchor = ev.uuid;
+        }
+    }
+    catch {
+        return null;
+    }
+    return anchor;
+}
+/** Codex: the last turn id recorded in the session's rollout. */
+export function codexRolloutTailAnchor(sessionId, opts = {}) {
+    const filePath = findCodexRolloutPath(homeOf(opts), sessionId);
+    const stat = filePath ? statSafe(filePath) : null;
+    if (!filePath || !stat)
+        return null;
+    let anchor = null;
+    try {
+        const start = Math.max(0, stat.size - TAIL_BYTES);
+        for (const line of readRegion(filePath, start, Math.min(TAIL_BYTES, stat.size)).split('\n')) {
+            const t = line.trim();
+            if (!t || t[0] !== '{' || !t.includes('turn_id'))
+                continue;
+            let ev;
+            try {
+                ev = JSON.parse(t);
+            }
+            catch {
+                continue;
+            }
+            const tid = ev.payload?.turn_id;
+            if (typeof tid === 'string' && tid)
+                anchor = tid;
+        }
+    }
+    catch {
+        return null;
+    }
+    return anchor;
+}
+/** Locate a codex rollout by session id (filenames end in `-<sessionId>.jsonl`). */
+function findCodexRolloutPath(home, sessionId) {
+    const suffix = `${sessionId}.jsonl`;
+    let found = null;
+    const walk = (dir) => {
+        if (found)
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (found)
+                return;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+                continue;
+            }
+            if (entry.name.startsWith('rollout-') && entry.name.endsWith(suffix)) {
+                found = full;
+                return;
+            }
+        }
+    };
+    walk(path.join(home, '.codex', 'sessions'));
+    return found;
+}

package/dist/protocol/index.d.ts

@@ -93,6 +93,7 @@ export interface UniversalSnapshot {
     incomplete?: boolean;
     startedAt?: number;
     updatedAt: number;
+    anchor?: string | null;
 }
 export interface SessionMeta {
     sessionKey: string;

package/dist/protocol/index.js

@@ -17,7 +17,7 @@ export function emptySnapshot() {
 }
 const APPEND_FIELDS = ['text', 'reasoning'];
 const STRUCT_FIELDS = ['plan', 'toolCalls', 'subAgents', 'usage', 'artifacts', 'interactions', 'queued'];
-const SCALAR_FIELDS = ['phase', 'taskId', 'sessionId', 'agent', 'model', 'effort', 'prompt', 'activity', 'error', 'incomplete', 'startedAt', 'updatedAt'];
+const SCALAR_FIELDS = ['phase', 'taskId', 'sessionId', 'agent', 'model', 'effort', 'prompt', 'activity', 'error', 'incomplete', 'startedAt', 'updatedAt', 'anchor'];
 export function diffSnapshot(prev, next) {
     const patch = {};
     let set;

package/dist/runtime/fork.d.ts

@@ -0,0 +1,2 @@
+import type { UniversalSnapshot } from '../protocol/index.js';
+export declare function buildForkSeed(turns: UniversalSnapshot[], budget?: number): string | null;

package/dist/runtime/fork.js

@@ -0,0 +1,35 @@
+// Context replay for a SEED-mode fork — the fallback for drivers without native fork
+// (capabilities.fork unset) or forks whose cut point could not be pinned to a native
+// anchor. The branch starts a FRESH native session whose first prompt is prefixed with
+// the copied transcript, role-tagged and tail-truncated. Native-mode forks never see
+// this: their context comes from the agent's own store via resume+fork.
+const FORK_SEED_BUDGET_CHARS = 60_000;
+export function buildForkSeed(turns, budget = FORK_SEED_BUDGET_CHARS) {
+    const messages = [];
+    for (const t of turns) {
+        const prompt = (t.prompt || '').trim();
+        const text = (t.text || '').trim();
+        if (prompt)
+            messages.push(`User: ${prompt}`);
+        if (text)
+            messages.push(`Assistant: ${text}`);
+    }
+    if (!messages.length)
+        return null;
+    // Tail-truncate whole messages into the budget — the most recent context matters most.
+    const kept = [];
+    let used = 0;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const cost = messages[i].length + 1;
+        if (used + cost > budget && kept.length)
+            break;
+        kept.unshift(messages[i]);
+        used += cost;
+    }
+    return [
+        `<fork-context turns=${turns.length}>`,
+        '[This conversation was forked from an earlier session; the transcript so far follows. Continue from this context — do not re-answer it. The next user message follows the closing tag.]',
+        ...kept,
+        '</fork-context>',
+    ].join('\n');
+}

package/dist/runtime/hub.d.ts

@@ -1,7 +1,7 @@
 import { type UniversalSnapshot, type SnapshotPatch, type SessionMeta, type AgentInfo, type ModelDescriptor, type EffortOption, type ToolDescriptor, type SkillDescriptor } from '../protocol/index.js';
 import type { AgentDriver, TuiSpec } from '../contracts/driver.js';
 import type { SessionStore, ModelResolver, ToolProvider, SystemPromptBuilder, InteractionHandler, Catalog } from '../contracts/ports.js';
-import type { LoomIO, PromptInput, Plugin } from '../contracts/surface.js';
+import type { LoomIO, PromptInput, ForkSessionInput, Plugin } from '../contracts/surface.js';
 export interface HubDeps {
     drivers: Map<string, AgentDriver>;
     defaultAgent: string;
@@ -43,6 +43,9 @@ export declare class Hub implements LoomIO {
         sessionKey: string;
         taskId: string;
     }>;
+    forkSession(input: ForkSessionInput): Promise<{
+        sessionKey: string;
+    }>;
     private enqueue;
     private runNow;
     private promoteNext;

package/dist/runtime/hub.js

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { diffSnapshot, emptySnapshot, makeSessionKey, splitSessionKey, } from '../protocol/index.js';
 import { SessionRunner } from './session-runner.js';
+import { buildForkSeed } from './fork.js';
 export class Hub {
     deps;
     sessions = new Map();
@@ -74,6 +75,74 @@ export class Hub {
         }
         return { sessionKey, taskId };
     }
+    // Branch `fromSessionKey` at a turn boundary into a NEW managed session. Copies the kept
+    // transcript prefix, pins the native keep-boundary NOW (so the branch is immune to the
+    // parent continuing afterwards), and stamps a pendingFork the first prompt() dispatch
+    // consumes (fork-on-dispatch). The parent — record, transcript, native store — is never
+    // mutated. Works for sessions the kernel never ran: a native-only session's id IS its
+    // native id (the same assumption prompt() makes when resuming one).
+    async forkSession(input) {
+        const { agent, sessionId: fromId } = splitSessionKey(input.fromSessionKey);
+        const driver = this.deps.drivers.get(agent);
+        if (!driver)
+            throw new Error(`No driver registered for agent "${agent}"`);
+        const parent = await this.deps.sessionStore.get(agent, fromId);
+        const parentNativeId = parent?.nativeSessionId || fromId;
+        const workdir = parent?.workdir || this.deps.workdir;
+        // Kept transcript prefix: through atTaskId inclusive (default: the whole transcript).
+        const turns = this.deps.sessionStore.history
+            ? await this.deps.sessionStore.history(agent, fromId).catch(() => [])
+            : [];
+        let kept = turns;
+        if (input.atTaskId) {
+            const cut = turns.findIndex(t => t.taskId === input.atTaskId);
+            if (cut < 0)
+                throw new Error(`fork point ${input.atTaskId} not found in ${input.fromSessionKey}`);
+            kept = turns.slice(0, cut + 1);
+        }
+        const cutIsTail = kept.length === turns.length;
+        // Pin the native keep-boundary at fork time: explicit override → the kept turn's recorded
+        // anchor → the parent's CURRENT tail (tail cuts only). A mid cut that can't be anchored
+        // falls back to a seed fork — a tail-anchored native fork there would silently absorb the
+        // dropped turns, which is worse than the seed's lower fidelity.
+        let anchor = input.anchor ?? kept[kept.length - 1]?.anchor ?? null;
+        if (!anchor && cutIsTail && driver.resolveNativeAnchor) {
+            try {
+                anchor = (await driver.resolveNativeAnchor({ sessionId: parentNativeId, workdir })) ?? null;
+            }
+            catch {
+                anchor = null;
+            }
+        }
+        const mode = driver.capabilities?.fork && parentNativeId && (anchor || cutIsTail) ? 'native' : 'seed';
+        const { sessionId: newId } = await this.deps.sessionStore.ensure(agent, {
+            workdir, title: input.title ?? parent?.title ?? null,
+        });
+        for (const turn of kept) {
+            try {
+                await this.deps.sessionStore.appendTurn?.(agent, newId, turn);
+            }
+            catch (e) {
+                this.deps.log?.(`[hub] fork transcript copy failed ${newId}: ${e?.message || e}`);
+            }
+        }
+        const rec = await this.deps.sessionStore.get(agent, newId);
+        if (rec) {
+            const last = kept[kept.length - 1];
+            rec.model = parent?.model ?? last?.model ?? null;
+            rec.effort = parent?.effort ?? last?.effort ?? null;
+            rec.preview = parent?.preview ?? null;
+            // ensure() stamps fresh records 'running' (prompt() marks them properly right after);
+            // a fork has not dispatched anything yet — settle it so it can't read as a live turn.
+            rec.runState = 'completed';
+            rec.runDetail = null;
+            rec.forkedFrom = { sessionKey: input.fromSessionKey, taskId: input.atTaskId ?? last?.taskId ?? null };
+            rec.pendingFork = { parentNativeSessionId: parentNativeId, anchor, mode };
+            await this.deps.sessionStore.save(rec);
+        }
+        this.deps.log?.(`[hub] forked ${input.fromSessionKey} -> ${agent}:${newId} (${mode}${anchor ? `, anchor ${anchor}` : ''}, ${kept.length}/${turns.length} turns)`);
+        return { sessionKey: makeSessionKey(agent, newId) };
+    }
     enqueue(item) {
         const q = this.waiting.get(item.sessionKey) ?? [];
         q.push(item);
@@ -101,6 +170,10 @@ export class Hub {
         // Resolve injection / tools / resume-target at run time so a promoted turn sees the
         // prior turn's native session id and any refreshed credentials/tools.
         const rec = await this.deps.sessionStore.get(agent, sessionId);
+        // Fork-on-dispatch: a pendingFork rides every dispatch until a native id lands (a failed
+        // first turn keeps the intent, so the retry forks again). Native mode resumes the PARENT's
+        // native id with the fork flag; seed mode starts fresh and replays the copied transcript.
+        const pendingFork = rec && !rec.nativeSessionId ? rec.pendingFork ?? null : null;
         const injection = await this.deps.modelResolver.resolve(agent, { model: input.model, profileId: null }).catch(() => null);
         const model = injection?.model ?? input.model ?? null;
         const effort = input.effort ?? null;
@@ -113,11 +186,29 @@ export class Hub {
             { env: tools.env },
             ...pluginParts,
         ]);
-        const systemPrompt = await this.composeSystemPrompt(agent, workdir, !preExisted);
+        // A seed fork opens a brand-new native session, so it takes the first-turn system prompt;
+        // a native fork is resume-shaped (the parent's opening turn already carried it).
+        const systemPrompt = await this.composeSystemPrompt(agent, workdir, !preExisted || pendingFork?.mode === 'seed');
+        let driverSessionId = rec?.nativeSessionId || (input.sessionKey ? sessionId : null);
+        let driverFork = null;
+        let driverPrompt = input.prompt;
+        if (pendingFork) {
+            if (pendingFork.mode === 'native' && pendingFork.parentNativeSessionId) {
+                driverSessionId = pendingFork.parentNativeSessionId;
+                driverFork = { anchor: pendingFork.anchor };
+            }
+            else {
+                driverSessionId = null;
+                const seed = buildForkSeed(await this.getHistory(sessionKey));
+                if (seed)
+                    driverPrompt = `${seed}\n\n${input.prompt}`;
+            }
+        }
         const turnInput = {
-            prompt: input.prompt,
+            prompt: driverPrompt,
             attachments: input.attachments,
-            sessionId: rec?.nativeSessionId || (input.sessionKey ? sessionId : null),
+            sessionId: driverSessionId,
+            fork: driverFork,
             workdir,
             model, effort, systemPrompt,
             env: spawn.env,
@@ -134,6 +225,20 @@ export class Hub {
         runner.run(driver, turnInput, input.prompt, model, effort)
             .then(async (result) => {
             await this.deps.sessionStore.recordResult(agent, sessionId, result);
+            // The branch materialized natively (recordResult stored its id) — consume the fork
+            // intent. A turn that died before a native id landed keeps it, so the retry re-forks.
+            if (pendingFork && result.sessionId) {
+                try {
+                    const settled = await this.deps.sessionStore.get(agent, sessionId);
+                    if (settled?.pendingFork) {
+                        settled.pendingFork = null;
+                        await this.deps.sessionStore.save(settled);
+                    }
+                }
+                catch (e) {
+                    this.deps.log?.(`[hub] pendingFork clear failed ${sessionKey}: ${e?.message || e}`);
+                }
+            }
             // Persist the completed turn's final snapshot as a transcript entry. The runner's
             // snapshot is stable once done (a follow-up prompt spawns a fresh runner+snapshot).
             try {

package/dist/runtime/session-runner.js

@@ -60,6 +60,8 @@ export class SessionRunner {
             this.snapshot.reasoning = result.reasoning;
         if (result.sessionId)
             this.snapshot.sessionId = result.sessionId;
+        if (result.anchor)
+            this.snapshot.anchor = result.anchor;
         if (result.usage)
             this.snapshot.usage = result.usage;
         this.snapshot.error = result.error ?? null;

package/dist/workspace/sessions.d.ts

@@ -17,6 +17,11 @@ export interface ManagedSessionInfo {
     createdAt: string | null;
     updatedAt: string | null;
     messageCount?: number | null;
+    /** Fork lineage when this session was branched off another (see CoreSessionRecord.forkedFrom). */
+    forkedFrom?: {
+        sessionKey: string;
+        taskId?: string | null;
+    } | null;
 }
 export interface ListSessionsOptions {
     /**

package/dist/workspace/sessions.js

@@ -25,6 +25,7 @@ function managedToInfo(agent, rec) {
         createdAt: rec.createdAt ?? null,
         updatedAt: rec.updatedAt ?? null,
         messageCount: null, // managed records don't track a turn count; native rows carry the head-approx one
+        forkedFrom: rec.forkedFrom ?? null,
     };
 }
 function nativeToInfo(agent, n) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikiloom/kernel",
-  "version": "0.3.11",
+  "version": "0.3.12",
   "description": "Heterogeneous coding agents (Claude / Codex / Gemini / ACP) -> an interaction-friendly, accumulating session snapshot + control handle, over pluggable surfaces (IM, Web, tunnel, TUI). The reusable core pikiloom itself is built on.",
   "type": "module",
   "license": "MIT",