pikiloom 0.4.68 → 0.4.70

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pikiloom",
-  "version": "0.4.68",
+  "version": "0.4.70",
   "description": "Put the world's smartest AI agents in your pocket. Command local Claude & Gemini via IM. | 让最好用的 IM 变成你电脑上的顶级 Agent 控制台",
   "type": "module",
   "bin": {

package/packages/kernel/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/packages/kernel/dist/contracts/ports.d.ts

@@ -14,6 +14,17 @@ export interface CoreSessionRecord {
     effort?: string | null;
     runState?: 'running' | 'completed' | 'incomplete';
     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: {
@@ -30,6 +41,11 @@ export interface SessionStore {
         limit?: number;
     }): Promise<CoreSessionRecord[]>;
     recordResult(agent: string, sessionId: string, result: DriverResult): Promise<void>;
+    markRunning?(agent: string, sessionId: string, owner: {
+        pid: number;
+        startedAt: number;
+    }): Promise<void>;
+    reconcileRunning?(isAlive: (pid: number) => boolean): Promise<number>;
     appendTurn?(agent: string, sessionId: string, turn: UniversalSnapshot): Promise<void>;
     history?(agent: string, sessionId: string): Promise<UniversalSnapshot[]>;
 }

package/packages/kernel/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/packages/kernel/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/packages/kernel/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/packages/kernel/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/packages/kernel/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;
     }
@@ -263,8 +263,25 @@ export class CodexDriver {
         let steerRegistered = false;
         if (!srv.start())
             return { ok: false, text: '', error: 'failed to start codex app-server', stopReason: 'error' };
-        let settle = () => { };
-        const turnDone = new Promise((res) => { settle = res; });
+        let settled = false;
+        let resolveTurn = () => { };
+        const turnDone = new Promise((res) => { resolveTurn = res; });
+        // Idempotent: turnDone can be settled from three racing sources (turn/completed, abort,
+        // process death); the first wins and the rest are no-ops.
+        const settle = () => { if (settled)
+            return; settled = true; resolveTurn(); };
+        // If the app-server process dies WITHOUT a turn/completed (crash, kill, disconnect), the
+        // `await turnDone` below would otherwise hang forever — run() never resolves, recordResult
+        // never fires, and the session is stranded runState:"running" in the orchestrator even though
+        // the codex process is already dead. Settle it as a failed turn so the orchestrator can
+        // finalize it (mirrors the claude driver's child.on('close') settle).
+        srv.onClose(() => {
+            if (settled)
+                return;
+            state.error = state.error || srv.stderrText().trim().split('\n').pop() || 'codex app-server exited before the turn completed';
+            state.status = 'error';
+            settle();
+        });
         // On abort: gracefully interrupt the running turn, then settle turnDone OURSELVES. A bare
         // srv.kill() (SIGTERM) never produces a turn/completed notification, so without this explicit
         // settle() the `await turnDone` below hangs forever — run() never resolves and the task stays
@@ -289,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;
@@ -478,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,
             };
         }
@@ -496,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/packages/kernel/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/packages/kernel/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/packages/kernel/dist/drivers/rpc.d.ts

@@ -25,12 +25,19 @@ export declare class StdioRpcClient {
     private readonly pending;
     private notifyCb?;
     private requestCb?;
+    private closeCb?;
     private readonly stderrTail;
     private readonly label;
     constructor(opts: StdioRpcOptions);
     onNotification(cb: (method: string, params: any) => void): void;
     /** Serve peer->client requests. Throw RpcError for a coded error; anything else answers -32603. */
     onRequest(cb: (method: string, params: any, id: number | string) => any | Promise<any>): void;
+    /**
+     * Fires once when the child process exits/closes. A driver awaiting a terminal *notification*
+     * (not a pending request) MUST use this to settle its turn — otherwise a process that dies
+     * without emitting its completion notification leaves the turn hanging forever.
+     */
+    onClose(cb: () => void): void;
     /** Rolling tail of the process' stderr — startup/crash diagnostics. */
     stderrText(): string;
     start(): boolean;

package/packages/kernel/dist/drivers/rpc.js

@@ -16,6 +16,7 @@ export class StdioRpcClient {
     pending = new Map();
     notifyCb;
     requestCb;
+    closeCb;
     stderrTail = [];
     label;
     constructor(opts) {
@@ -25,6 +26,12 @@ export class StdioRpcClient {
     onNotification(cb) { this.notifyCb = cb; }
     /** Serve peer->client requests. Throw RpcError for a coded error; anything else answers -32603. */
     onRequest(cb) { this.requestCb = cb; }
+    /**
+     * Fires once when the child process exits/closes. A driver awaiting a terminal *notification*
+     * (not a pending request) MUST use this to settle its turn — otherwise a process that dies
+     * without emitting its completion notification leaves the turn hanging forever.
+     */
+    onClose(cb) { this.closeCb = cb; }
     /** Rolling tail of the process' stderr — startup/crash diagnostics. */
     stderrText() { return this.stderrTail.join('\n'); }
     start() {
@@ -55,6 +62,7 @@ export class StdioRpcClient {
             for (const cb of this.pending.values())
                 cb({ error: { message: `${this.label} exited` } });
             this.pending.clear();
+            this.closeCb?.();
         });
         this.proc.on('error', () => { });
         return true;

package/packages/kernel/dist/ports/defaults.d.ts

@@ -25,9 +25,21 @@ export declare class FsSessionStore implements SessionStore {
         text?: string;
         sessionId?: string | null;
     }): Promise<void>;
+    markRunning(agent: string, sessionId: string, owner: {
+        pid: number;
+        startedAt: number;
+    }): Promise<void>;
+    reconcileRunning(isAlive: (pid: number) => boolean): Promise<number>;
     appendTurn(agent: string, sessionId: string, turn: UniversalSnapshot): Promise<void>;
     history(agent: string, sessionId: string): Promise<UniversalSnapshot[]>;
 }
+/**
+ * Is a pid currently a live process? `signal 0` probes without delivering a signal: ESRCH =>
+ * no such process (dead); EPERM => alive but owned by someone we can't signal (treat as alive).
+ * The conservative bias (unknown => alive) is deliberate — reconciliation must never reap a turn
+ * that might still be running.
+ */
+export declare function isProcessAlive(pid: number): boolean;
 export declare function defaultBaseDir(appNamespace: string): string;
 export declare class NullModelResolver implements ModelResolver {
     resolve(): Promise<null>;

package/packages/kernel/dist/ports/defaults.js

@@ -74,6 +74,7 @@ export class FsSessionStore {
             return;
         rec.runState = result.ok ? 'completed' : 'incomplete';
         rec.runDetail = result.error ?? null;
+        rec.runPid = null; // turn is over — drop the owner so reconciliation ignores it
         if (result.sessionId)
             rec.nativeSessionId = result.sessionId;
         if (result.text && !rec.title)
@@ -82,6 +83,43 @@ export class FsSessionStore {
             rec.preview = result.text.replace(/\s+/g, ' ').trim().slice(0, 200) || rec.preview || null;
         await this.save(rec);
     }
+    async markRunning(agent, sessionId, owner) {
+        const rec = await this.get(agent, sessionId);
+        if (!rec)
+            return;
+        rec.runState = 'running';
+        rec.runDetail = null;
+        rec.runPid = owner.pid;
+        rec.runStartedAt = owner.startedAt;
+        await this.save(rec);
+    }
+    async reconcileRunning(isAlive) {
+        let agents = [];
+        try {
+            agents = fs.readdirSync(this.baseDir, { withFileTypes: true }).filter(d => d.isDirectory()).map(d => d.name);
+        }
+        catch {
+            return 0;
+        }
+        let repaired = 0;
+        for (const agent of agents) {
+            for (const rec of await this.list(agent)) {
+                if (rec.runState !== 'running')
+                    continue;
+                // Only reap a KNOWN-dead owner. No pid (legacy record) or a live pid (possibly a turn
+                // running in another process against this shared store) is left alone — never clobber a
+                // turn that might still be live elsewhere.
+                if (typeof rec.runPid !== 'number' || isAlive(rec.runPid))
+                    continue;
+                rec.runState = 'incomplete';
+                rec.runDetail = rec.runDetail || 'interrupted: owner process exited';
+                rec.runPid = null;
+                await this.save(rec);
+                repaired++;
+            }
+        }
+        return repaired;
+    }
     async appendTurn(agent, sessionId, turn) {
         const p = this.turnsPath(agent, sessionId);
         fs.mkdirSync(path.dirname(p), { recursive: true });
@@ -108,6 +146,23 @@ export class FsSessionStore {
         return out;
     }
 }
+/**
+ * Is a pid currently a live process? `signal 0` probes without delivering a signal: ESRCH =>
+ * no such process (dead); EPERM => alive but owned by someone we can't signal (treat as alive).
+ * The conservative bias (unknown => alive) is deliberate — reconciliation must never reap a turn
+ * that might still be running.
+ */
+export function isProcessAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e?.code === 'EPERM';
+    }
+}
 export function defaultBaseDir(appNamespace) {
     return path.join(os.homedir(), `.${appNamespace}`, 'sessions');
 }

package/packages/kernel/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/packages/kernel/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/packages/kernel/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/packages/kernel/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/packages/kernel/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/packages/kernel/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);
@@ -94,9 +163,17 @@ export class Hub {
         };
         this.sessions.set(sessionKey, entry);
         this.emitSessionsChanged();
+        // Stamp the persisted record as running under THIS process, so runState is authoritative for
+        // the whole turn (new AND resumed) and a crash strands an owner pid that boot reconciliation
+        // can reap. Best-effort: a store without markRunning just won't be reconcilable.
+        await this.deps.sessionStore.markRunning?.(agent, sessionId, { pid: process.pid, startedAt: Date.now() }).catch(() => { });
         // 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;
@@ -109,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,
@@ -130,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/packages/kernel/dist/runtime/loom.js

@@ -1,4 +1,4 @@
-import { FsSessionStore, NullModelResolver, NoopToolProvider, PassthroughSystemPromptBuilder, NoopCatalog, DeferToTerminalInteractionHandler, defaultBaseDir, } from '../ports/defaults.js';
+import { FsSessionStore, NullModelResolver, NoopToolProvider, PassthroughSystemPromptBuilder, NoopCatalog, DeferToTerminalInteractionHandler, defaultBaseDir, isProcessAlive, } from '../ports/defaults.js';
 import { Hub } from './hub.js';
 import { PtyBridge } from './pty.js';
 import { attachTui } from './tui.js';
@@ -59,6 +59,17 @@ export function createLoom(config = {}) {
             if (started)
                 return;
             started = true;
+            // Repair sessions stranded at runState:'running' by a previous process that died mid-turn
+            // (crash / kill / power loss) before its driver could settle. Safe under a shared store:
+            // only records whose owner pid is dead are reaped (see reconcileRunning). Best-effort.
+            try {
+                const repaired = await sessionStore.reconcileRunning?.(isProcessAlive);
+                if (repaired)
+                    log(`[loom] reconciled ${repaired} orphaned running session(s) at startup`);
+            }
+            catch (e) {
+                log(`[loom] startup reconcile failed: ${e?.message || e}`);
+            }
             for (const t of surfaces) {
                 await t.start(hub, { openTui }); // hub = Lane S (LoomIO); openTui = Lane R
                 log(`[loom] terminal started: ${t.id}`);

package/packages/kernel/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/packages/kernel/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/packages/kernel/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) {