@xingular/harness 1.6.0-unstable → 2.0.1-unstable

package/dist/sdk/sessions/runner.js

@@ -10,6 +10,7 @@ import { CONTEXT_MESSAGE_TYPE, CONTEXT_SNAPSHOT_KEY } from "../prompt/compile.js
 import { PLAN_REPAIR_CUSTOM_TYPE, PLAN_REPAIR_INSTRUCTIONS, finalizePlanOutcome } from "./planMode.js";
 import { MAX_CHECKPOINT_CHECKS, MAX_CHECKPOINT_FILES, MAX_CHECKPOINT_SUMMARY } from "./contracts.js";
 import { withTransientRetry } from "../pi/retryPolicy.js";
+import { STALL_CHECK_MS, onlyWaitingForChildren, replyStalled } from "./stallWatch.js";
 import { activeToolBeat, derivedReason } from "./workSlice.js";
 import { goalStopOutcome, handoffFields, stopCheckpointReason, stopSummary } from "./goalStop.js";
 import { TODO_WRITE } from "../tools/todo.js";
@@ -53,6 +54,8 @@ export function resultSize(result) {
     return content.reduce((total, part) => total + (part?.type === 'text' && typeof part.text === 'string' ? part.text.length : 0), 0);
 }
 const MAX_EVIDENCE_CHARS = 24_000;
+/** How long a stalled turn gets to unwind after its abort before the session is closed under it. */
+const STALL_ABORT_GRACE_MS = 30_000;
 const MAX_SYSTEM_PROMPT_CHARS = 100_000;
 const MAX_TOOL_SPECS = 120;
 function limitedText(value, maximum = MAX_EVIDENCE_CHARS) {
@@ -197,20 +200,58 @@ export async function runTurn(run, session, params) {
     const slice = params.slice?.state ?? null;
     const ledger = { files: new Map(), checks: [], lastText: '', todo: [] };
     const bashCommands = new Map();
-    const heartbeat = slice
-        ? setInterval(() => {
-            run.emit('heartbeat', {
-                steps: slice.steps,
-                elapsedMs: Date.now() - slice.startedAt,
-                lastTool: slice.lastTool,
-                compactions: slice.compactions,
-                slice: slice.slice,
-                maxToolCalls: params.slice?.maxToolCalls ?? 0,
-                ...activeToolBeat(toolsInFlight)
-            });
-        }, 30_000)
-        : null;
-    heartbeat?.unref?.();
+    const startedAt = Date.now();
+    // Every reply reports liveness (INV-RUN-14): the sweep settles a record that went quiet, and a long
+    // tool or a person's pause must not look like one.
+    const heartbeat = setInterval(() => {
+        run.emit('heartbeat', {
+            steps: slice?.steps ?? 0,
+            elapsedMs: Date.now() - (slice?.startedAt ?? startedAt),
+            lastTool: slice?.lastTool ?? null,
+            compactions: slice?.compactions ?? 0,
+            slice: slice?.slice ?? 1,
+            maxToolCalls: params.slice?.maxToolCalls ?? 0,
+            ...activeToolBeat(toolsInFlight)
+        });
+    }, 30_000);
+    heartbeat.unref?.();
+    // A reply whose model request never came back, or whose tool never returned, is ended with the
+    // reason `stalled` instead of holding its session for ever (the provider's own timeout is longer).
+    // A person's pending decision and a wait for subagents (each watched by its own run) are not silence.
+    let progressAt = Date.now();
+    let stalled = false;
+    // The session goes back (or is disposed) once, by the run's end or, when a stalled turn will not unwind, by the grace timer.
+    let handedBack = false;
+    const handBack = (close) => {
+        if (handedBack)
+            return;
+        handedBack = true;
+        if (params.release)
+            params.release(close);
+        else
+            session.dispose();
+    };
+    let abortGrace = null;
+    const stallGuard = setInterval(() => {
+        if (run.finished || stalled)
+            return;
+        const at = Date.now();
+        const tools = [...toolsInFlight.values()];
+        if (run.waiting || onlyWaitingForChildren(tools.map((tool) => tool.name))) {
+            progressAt = at;
+            return;
+        }
+        if (!replyStalled({ now: at, progressAt, runningTools: tools.map((tool) => tool.at) }))
+            return;
+        stalled = true;
+        aborted = true;
+        run.finish('interrupted', undefined, 'stalled', 'stalled');
+        session.abortBash?.();
+        void Promise.resolve(session.abort()).catch(() => undefined);
+        abortGrace = setTimeout(() => handBack(true), STALL_ABORT_GRACE_MS);
+        abortGrace.unref?.();
+    }, STALL_CHECK_MS);
+    stallGuard.unref?.();
     const systemPrompt = limitedText(session.systemPrompt ?? params.system, MAX_SYSTEM_PROMPT_CHARS);
     const contextUpdate = limitedText(params.update?.content ?? '', MAX_SYSTEM_PROMPT_CHARS);
     const toolSpecs = contextToolSpecs(session);
@@ -294,6 +335,7 @@ export async function runTurn(run, session, params) {
         };
     }
     const unsubscribe = session.subscribe((event) => {
+        progressAt = Date.now();
         switch (event.type) {
             case 'message_start': {
                 const { message } = event;
@@ -468,6 +510,9 @@ export async function runTurn(run, session, params) {
             case 'auto_retry_end': {
                 const retry = event;
                 run.emit('retry.ended', { attempt: numberField(retry, 'attempt', 1), success: retry.success === true, ...(stringField(retry, 'finalError') ? { error: stringField(retry, 'finalError').slice(0, 1000) } : {}) });
+                // The request that failed was retried and answered: the reply did not fail.
+                if (retry.success === true)
+                    lastError = null;
                 break;
             }
             case 'compaction_start': {
@@ -510,6 +555,11 @@ export async function runTurn(run, session, params) {
             // The delivered snapshot is saved with the message, so the next turn compares against what Pi really holds.
             await session.sendCustomMessage({ customType: CONTEXT_MESSAGE_TYPE, content: params.update.content, display: false, details: { [CONTEXT_SNAPSHOT_KEY]: params.update.snapshot } }, { triggerTurn: false });
         }
+        for (const note of params.hiddenNotes ?? []) {
+            if (!session.sendCustomMessage)
+                throw new HarnessError('provider_error', 'The Pi session cannot receive a hidden note.');
+            await session.sendCustomMessage({ customType: note.customType, content: note.content, display: false, details: {} }, { triggerTurn: false });
+        }
         const command = /^\/(\S+)/.exec(params.text)?.[1];
         if (params.preamble && command) {
             if (!session.sendCustomMessage)
@@ -661,10 +711,12 @@ export async function runTurn(run, session, params) {
             run.finish('failed', { code: 'provider_error', message: error instanceof Error ? error.message : String(error) });
     }
     finally {
-        if (heartbeat)
-            clearInterval(heartbeat);
+        clearInterval(heartbeat);
+        clearInterval(stallGuard);
+        if (abortGrace)
+            clearTimeout(abortGrace);
         unsubscribe();
-        session.dispose();
+        handBack(stalled);
     }
 }
 /** Runs one session command and returns what to tell the person. */
@@ -764,7 +816,11 @@ export function registeredBy(loader) {
         .map((extension) => ({ path: extension.resolvedPath || extension.path, hooks: names(extension.handlers), tools: names(extension.tools), commands: names(extension.commands), flags: names(extension.flags), shortcuts: names(extension.shortcuts) }));
 }
 /** Opens a Pi session for one turn: the account's runtime, the compiled prompt, and the gated tools. */
-export const piSessionFactory = async ({ params, allow, gate, tools, runtime: loadRuntime, extensions: host }) => {
+export const piSessionFactory = async (input) => {
+    const { params, allow, runtime: loadRuntime, extensions: host } = input;
+    // What belongs to the current run. A live session (ADR-0083) swaps it at the start of every run,
+    // so everything below that is per run reads it here rather than closing over the first run's.
+    let bound = input;
     const pi = await loadPi();
     const { Type } = await import('typebox');
     const runtime = await loadRuntime();
@@ -778,9 +834,9 @@ export const piSessionFactory = async ({ params, allow, gate, tools, runtime: lo
         thinkingLevel ??= resolved.thinkingLevel;
     }
     const workspaceBash = createWorkspaceBashOperations(params.workspaceRoot, {
-        bypassWorkspaceBoundary: (request) => gate.workspaceBoundaryBypass?.('bash', { command: request.command, cwd: request.cwd, workspaceRoot: request.workspaceRoot }) ?? Promise.resolve(false),
-        requestWorkspaceWriteScope: (request) => gate.requestWorkspaceWriteScope?.('bash', { command: request.command, workspaceWriteScope: 'outside' }, request.reason) ?? Promise.resolve(false),
-        workspaceWriteScope: () => params.plan ? 'read-only' : undefined
+        bypassWorkspaceBoundary: (request) => bound.gate.workspaceBoundaryBypass?.('bash', { command: request.command, cwd: request.cwd, workspaceRoot: request.workspaceRoot }) ?? Promise.resolve(false),
+        requestWorkspaceWriteScope: (request) => bound.gate.requestWorkspaceWriteScope?.('bash', { command: request.command, workspaceWriteScope: 'outside' }, request.reason) ?? Promise.resolve(false),
+        workspaceWriteScope: () => bound.params.plan ? 'read-only' : undefined
     });
     const gatedExtension = (api) => {
         const writeAuthorizations = new Map();
@@ -807,10 +863,11 @@ export const piSessionFactory = async ({ params, allow, gate, tools, runtime: lo
                 }
                 catch (error) {
                     const reason = error instanceof Error ? error.message : 'The active project workspace could not be verified.';
-                    params.onRefusal?.(event.toolCallId, event.toolName, { code: 'workspace', reason });
+                    bound.params.onRefusal?.(event.toolCallId, event.toolName, { code: 'workspace', reason });
                     return { block: true, reason };
                 }
             }
+            const gate = bound.gate;
             const refusal = gate.checkDetailed ? await gate.checkDetailed(event.toolName, event.input) : null;
             if (!gate.checkDetailed) {
                 const reason = await gate.check(event.toolName, event.input);
@@ -818,7 +875,7 @@ export const piSessionFactory = async ({ params, allow, gate, tools, runtime: lo
                     return { block: true, reason };
             }
             if (refusal) {
-                params.onRefusal?.(event.toolCallId, event.toolName, refusal);
+                bound.params.onRefusal?.(event.toolCallId, event.toolName, refusal);
                 return { block: true, reason: refusal.reason };
             }
             if (authorization) {
@@ -831,22 +888,33 @@ export const piSessionFactory = async ({ params, allow, gate, tools, runtime: lo
     const agentDir = params.account.configDir;
     const automaticSettings = params.automatic ? pi.SettingsManager.inMemory({}) : undefined;
     const settingsManager = withTransientRetry(automaticSettings ?? pi.SettingsManager.create(params.cwd, agentDir));
-    const resourceLoader = await loadResources(pi, params, gatedExtension, automaticSettings);
+    // The run's own extensions (lineage, subagents, checkpoint, slice, goal, first-party hooks) are
+    // loaded in slots that can be emptied and filled with the next run's (ADR-0083).
+    const slots = (params.inline ?? []).map((extension) => runSlot(extension));
+    let activated = null;
+    const resourceLoader = await loadResources(pi, {
+        ...params,
+        inline: slots.map((slot) => slot.extension),
+        activatedPlugins: (ids) => { activated = ids; bound.params.activatedPlugins?.(ids); }
+    }, gatedExtension, automaticSettings);
     const loaded = registeredBy(resourceLoader);
     // A tool an extension brought is offered to the model, and asks before every call: the person
     // trusted the code to load, and still decides each thing it does through a tool.
     const extensionTools = [...new Set(loaded.flatMap((extension) => extension.tools))].filter((name) => !allow.includes(name) && !params.restrictTools);
-    gate.ask?.([...new Set(loaded.flatMap((extension) => extension.tools))]);
+    const askedTools = [...new Set(loaded.flatMap((extension) => extension.tools))];
+    bound.gate.ask?.(askedTools);
     let supportsImageInput = false;
-    const customTools = tools
+    const customTools = input.tools
         .filter((tool) => allow.includes(tool.name))
         .map((spec) => pi.defineTool({
         name: spec.name,
         label: spec.label,
         description: spec.description,
         parameters: spec.parameters(Type),
-        execute: async (_toolCallId, input) => {
-            const result = await spec.execute(input);
+        execute: async (_toolCallId, toolInput) => {
+            // The current run's tool of this name: it is bound to that run's record and gate.
+            const current = bound.tools.find((tool) => tool.name === spec.name) ?? spec;
+            const result = await current.execute(toolInput);
             const output = typeof result === 'string' ? { text: result } : result;
             const images = [...(output.image ? [output.image] : []), ...(output.images ?? [])];
             if (images.length && !supportsImageInput)
@@ -867,14 +935,21 @@ export const piSessionFactory = async ({ params, allow, gate, tools, runtime: lo
         customTools: customTools,
         resourceLoader,
         settingsManager,
-        sessionManager: params.historyFile ? pi.SessionManager.open(params.historyFile, params.sessionDir, params.cwd) : pi.SessionManager.continueRecent(params.cwd, params.sessionDir)
+        sessionManager: params.historyFile
+            ? pi.SessionManager.open(params.historyFile, params.sessionDir, params.cwd)
+            : params.newHistory ? pi.SessionManager.create(params.cwd, params.sessionDir) : pi.SessionManager.continueRecent(params.cwd, params.sessionDir)
     });
     if (loaded.length && host) {
+        // Dialogs and notices go to whichever run is current; between runs nobody can answer.
+        const current = {
+            ask: (question) => bound.extensions ? bound.extensions.ask(question) : Promise.reject(new HarnessError('run_not_active', 'No reply is running in this session.')),
+            notice: (notice) => bound.extensions?.notice(notice)
+        };
         // Without this an extension never hears that its session started and has nobody to ask.
         await session.bindExtensions({
-            uiContext: extensionUi(host),
+            uiContext: extensionUi(current),
             mode: 'rpc',
-            onError: (error) => host.notice({ kind: 'error', text: `${error.event}: ${error.error}`.slice(0, 1000), extension: error.extensionPath })
+            onError: (error) => current.notice({ kind: 'error', text: `${error.event}: ${error.error}`.slice(0, 1000), extension: error.extensionPath })
         });
     }
     const piSession = session;
@@ -896,5 +971,70 @@ export const piSessionFactory = async ({ params, allow, gate, tools, runtime: lo
             }
         });
     };
+    const rebindable = slots.every((slot) => slot.rebindable());
+    if (rebindable && !params.automatic) {
+        Object.defineProperty(piSession, 'rebind', {
+            configurable: true,
+            value: async (next) => {
+                const names = (next.params.inline ?? []).map((extension) => extension.name);
+                if (names.length !== slots.length || names.some((name, index) => name !== slots[index].name)) {
+                    throw new HarnessError('session_pin_mismatch', 'The next run loads different extensions than this live session.');
+                }
+                bound = next;
+                for (const [index, slot] of slots.entries())
+                    await slot.fill(next.params.inline[index]);
+                next.gate.ask?.(askedTools);
+                if (activated)
+                    next.params.activatedPlugins?.(activated);
+            }
+        });
+    }
     return piSession;
 };
+/**
+ * One run-scoped extension in a live session. Pi keeps an extension's handlers in its own table and
+ * `on` returns the way to remove one, so a slot removes the last run's handlers and runs the next
+ * run's factory against the same extension. Only `on` is tracked: a run-scoped extension that
+ * registers tools or commands keeps them, and makes the session one that is not reused.
+ */
+function runSlot(extension) {
+    let api = null;
+    let offs = [];
+    let registers = false;
+    const tracked = (target) => new Proxy(target, {
+        get(object, key, receiver) {
+            if (key === 'on') {
+                return (event, handler) => {
+                    const off = object.on(event, handler);
+                    if (typeof off === 'function')
+                        offs.push(off);
+                    else
+                        registers = true;
+                    return off;
+                };
+            }
+            if (typeof key === 'string' && key.startsWith('register'))
+                registers = true;
+            return Reflect.get(object, key, receiver);
+        }
+    });
+    return {
+        name: extension.name,
+        extension: {
+            name: extension.name,
+            factory: (target) => {
+                api = target;
+                return extension.factory(tracked(target));
+            }
+        },
+        rebindable: () => api !== null && !registers,
+        async fill(next) {
+            if (!api)
+                throw new HarnessError('session_pin_mismatch', 'This live session never loaded its run extensions.');
+            for (const off of offs.splice(0))
+                off();
+            offs = [];
+            await next.factory(tracked(api));
+        }
+    };
+}

package/dist/sdk/sessions/sessions.d.ts

@@ -15,6 +15,7 @@ import { type WorkSliceInput } from "./workSlice.js";
 import type { ToolPolicy } from "./policy.js";
 import type { ActiveRun, RunRegistry } from "./registry.js";
 import { type Effort, type SessionCommand, type SessionFactory, type ToolGate } from "./runner.js";
+import { LiveSessions, type LiveSessionStatus } from "./live.js";
 /** The fields of a run record the caller decides; the harness fills in the rest. */
 export type RunFields = Pick<RunRecord, 'id' | 'sessionId'> & Partial<Pick<RunRecord, 'mode' | 'harness' | 'sessionType' | 'projectId' | 'agentId' | 'trigger' | 'goal' | 'attachmentCount' | 'resumedFromRunId' | 'parentRunId' | 'relation' | 'worktreeId' | 'handoffId' | 'profile' | 'title'>>;
 export interface SessionRunInput {
@@ -116,6 +117,29 @@ export interface SessionRunInput {
      * with a summary of the branch left behind, or export it to HTML. It pins the account like a turn.
      */
     command?: SessionCommand;
+    /**
+     * Keep the Pi session open after this run (ADR-0083), and reuse an open one when this run's pins
+     * equal its own. Steer the running reply with `runs.steer`, queue the next message with
+     * `sessions.followUp`, and close it with `sessions.close`. Never for unattended or child runs.
+     */
+    live?: boolean;
+    /** Start a new native history in `sessionDir` instead of continuing its newest one. */
+    newHistory?: boolean;
+    /**
+     * How a plan run withholds what it may not use. `gate` (the default) keeps every tool in the
+     * request, so the prompt and its cache stay as they were, and refuses the calls at the gate.
+     * `active` sends only the plan's tools, as the terminal does (ADR-0083).
+     */
+    planTools?: 'gate' | 'active';
+    /**
+     * Hidden messages saved in the native history before the request, as the context update is: the
+     * skills a person required with `$name`, or a goal note. The person's own text reaches the model
+     * unchanged. At most 8, of at most 20,000 characters each.
+     */
+    hiddenNotes?: Array<{
+        customType: string;
+        content: string;
+    }>;
 }
 /** The connected-apps broker, as a session sees it. */
 export interface SessionBroker {
@@ -146,12 +170,37 @@ export interface SessionsOptions {
         acquire(id: string, holder: string): Promise<unknown>;
         release(id: string, holder: string): Promise<void>;
     } | null;
+    /** How long an idle live session stays open (ADR-0083). */
+    liveIdleMs?: number;
 }
 export declare class Sessions {
     private readonly options;
     private readonly providers;
     private readonly factory;
+    /** Pi sessions kept open between the runs of a conversation (ADR-0083). */
+    readonly live: LiveSessions;
+    /** The last live run's input per session, which a follow-up repeats with its own text. */
+    private readonly liveInputs;
     constructor(options: SessionsOptions);
+    /** The live sessions open now. */
+    liveSessions(): LiveSessionStatus[];
+    /**
+     * Sends a message as the next run of a live session: now when it is idle, or after its active
+     * run settles. The run repeats the last live run's input with this text.
+     */
+    followUp(sessionId: string, text: string): Promise<{
+        runId: string;
+    } | {
+        queued: number;
+    }>;
+    /** Closes a live session now, or as soon as its active run settles. */
+    closeLive(sessionId: string): {
+        closed: boolean;
+        afterRun: string | null;
+    };
+    /** Closes every live session; the harness calls it when it shuts down. */
+    close(): void;
+    private runFollowUp;
     private get env();
     /** Adds tools an application provides. Providers are asked in the order they were added. */
     provide(provider: ToolProvider): void;

package/dist/sdk/sessions/sessions.js

@@ -37,8 +37,9 @@ import { compactionCheckpoint, COMPACTION_CHECKPOINT_EXTENSION } from "./compact
 import { createSliceState, parseWorkSlice, sliceOf, workSliceGuard, WorkSliceError, WORK_SLICE_EXTENSION } from "./workSlice.js";
 import { piSessionFactory, runTurn, summarize } from "./runner.js";
 import { loadRun, readEvents, runDir, saveRun, updateRun } from "./runStore.js";
+import { livePin, LiveSessions } from "./live.js";
 import { combineWorkspaceScope, inspectRunWorkspaceWrite } from "./workspaceBoundary.js";
-import { PLAN_INSTRUCTIONS, PLAN_RESEARCH_SUBAGENT_INSTRUCTIONS, planRefusal, planSection } from "./planMode.js";
+import { PLAN_INSTRUCTIONS, PLAN_RESEARCH_SUBAGENT_INSTRUCTIONS, planModeTools, planRefusal, planSection } from "./planMode.js";
 import { CONTINUATION_SECTION_ID, continuationOf, continuationSection } from "./continuation.js";
 import { deliveredSnapshot } from "../prompt/compile.js";
 import { profileSection } from "../agents/profiles.js";
@@ -105,9 +106,79 @@ export class Sessions {
     options;
     providers = [];
     factory;
+    /** Pi sessions kept open between the runs of a conversation (ADR-0083). */
+    live;
+    /** The last live run's input per session, which a follow-up repeats with its own text. */
+    liveInputs = new Map();
     constructor(options) {
         this.options = options;
         this.factory = options.factory ?? piSessionFactory;
+        this.live = new LiveSessions({
+            idleMs: options.liveIdleMs,
+            record: (runId) => {
+                try {
+                    return loadRun(this.env.root, runId);
+                }
+                catch {
+                    return null;
+                }
+            },
+            followUp: async (sessionId, _lastRunId, text) => { await this.runFollowUp(sessionId, text); },
+            log: (message) => log(message)
+        });
+    }
+    /** The live sessions open now. */
+    liveSessions() {
+        return this.live.list();
+    }
+    /**
+     * Sends a message as the next run of a live session: now when it is idle, or after its active
+     * run settles. The run repeats the last live run's input with this text.
+     */
+    async followUp(sessionId, text) {
+        if (typeof sessionId !== 'string' || !sessionId)
+            throw invalid('A follow-up needs a session id.');
+        if (typeof text !== 'string')
+            throw invalid('A follow-up needs text.');
+        const queued = this.live.queue(sessionId, text);
+        if ('queued' in queued)
+            return queued;
+        return { runId: await this.runFollowUp(sessionId, text) };
+    }
+    /** Closes a live session now, or as soon as its active run settles. */
+    closeLive(sessionId) {
+        const result = this.live.close(sessionId);
+        if (!result.afterRun)
+            this.liveInputs.delete(sessionId);
+        return result;
+    }
+    /** Closes every live session; the harness calls it when it shuts down. */
+    close() {
+        this.live.closeAll();
+        this.liveInputs.clear();
+    }
+    async runFollowUp(sessionId, text) {
+        const template = this.liveInputs.get(sessionId);
+        if (!template)
+            throw new HarnessError('not_found', 'This session has no live run to follow.');
+        const status = this.live.status(sessionId);
+        const next = {
+            ...structuredClone(template),
+            run: { ...template.run, id: randomUUID(), resumedFromRunId: null },
+            text,
+            // The follow-up continues exactly the history the live session writes, once it has a file.
+            resume: status?.sessionFile ? { sessionFile: status.sessionFile, nativeSessionId: status.nativeSessionId } : template.resume ?? null,
+            live: true
+        };
+        next.initialBashCommand = undefined;
+        next.initialBashContext = undefined;
+        next.images = undefined;
+        next.command = undefined;
+        next.continueFrom = null;
+        next.goal = undefined;
+        next.workSlice = template.workSlice;
+        const { runId } = await this.run(next);
+        return runId;
     }
     get env() {
         return this.options.env;
@@ -353,6 +424,20 @@ export class Sessions {
     }
     async start(input) {
         const { root } = this.env;
+        if (input.live) {
+            if (input.automatic || input.run.relation || (input.depth ?? 0) > 0 || (input.run.trigger != null && input.run.trigger !== 'user')) {
+                throw invalid('A live session is only for a person\'s own attended top-level runs.');
+            }
+            if (this.live.busy(input.run.sessionId))
+                throw new HarnessError('session_busy', 'This session is already replying. Steer it with runs.steer, or queue the message with sessions.followUp.');
+        }
+        // A run that opens its own session on this conversation's history reads and writes the file the
+        // live session holds in memory: the live session yields first (ADR-0083).
+        else if (input.run.relation == null && (input.depth ?? 0) === 0)
+            this.live.yieldHistory({ sessionId: input.run.sessionId, sessionDir: input.sessionDir });
+        // A new conversation never continues the open one.
+        if (input.live && input.newHistory)
+            this.live.yieldHistory({ sessionId: input.run.sessionId });
         if ((input.initialBashCommand !== undefined && input.initialBashCommand !== null) || (input.initialBashContext !== undefined && input.initialBashContext !== null)) {
             const request = input.text.trimStart();
             const requestedCommand = /^!\s*([\s\S]+)$/u.exec(request)?.[1];
@@ -374,7 +459,9 @@ export class Sessions {
                 || input.initialBashContext.ok !== undefined && typeof input.initialBashContext.ok !== 'boolean')) {
                 throw invalid('A prior Bash result must be bounded and must not be combined with a new initial Bash command.');
             }
-            if (input.automatic || input.plan || input.resume || input.continueFrom || input.run.relation || input.run.trigger != null && input.run.trigger !== 'user') {
+            // A live session's turn is always a new turn on the saved history it resumes (ADR-0083); a
+            // host's retry of an earlier turn says so with initialBashContext instead.
+            if (input.automatic || input.plan || (input.resume && !input.live) || input.continueFrom || input.run.relation || input.run.trigger != null && input.run.trigger !== 'user') {
                 throw invalid('An initial Bash command is available only for a new interactive user turn.');
             }
         }
@@ -392,7 +479,12 @@ export class Sessions {
         const workspaceRoot = previousRun?.workspaceRoot
             ? verifyWorkspaceRoot(previousRun.workspaceRoot)
             : resolveWorkspaceRoot(previousRun?.workingDirectory ?? input.cwd);
-        const historyFile = selectHistory({ sessionDir: input.sessionDir, resume: input.resume });
+        if (input.newHistory && (input.resume || input.continueFrom || input.command))
+            throw invalid('A new history cannot also resume, continue or run a command on a saved one.');
+        if (input.hiddenNotes !== undefined && (!Array.isArray(input.hiddenNotes) || input.hiddenNotes.length > 8 || input.hiddenNotes.some((note) => !note || typeof note.customType !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(note.customType) || typeof note.content !== 'string' || !note.content || note.content.length > 20_000))) {
+            throw invalid('Hidden notes are at most 8 messages, each with a lower-case type and up to 20,000 characters.');
+        }
+        const historyFile = input.newHistory ? null : selectHistory({ sessionDir: input.sessionDir, resume: input.resume });
         if (input.command)
             checkCommand(input.command, historyFile, input);
         const account = this.options.accounts.resolve(input.accountId, input.poolId);
@@ -423,9 +515,10 @@ export class Sessions {
             ? await this.options.resolveCapabilities(caller, requestedTools, input.cwd)
             : { version: 1, tools: requestedTools, connectors: [], contributions: [] };
         const requested = input.capabilities ? parseCapabilitySet(input.capabilities) : available;
+        const allowedTools = available.tools.filter((tool) => requested.tools.includes(tool));
         const capabilities = {
             version: 1,
-            tools: available.tools.filter((tool) => requested.tools.includes(tool)),
+            tools: input.plan && input.planTools === 'active' ? planModeTools(allowedTools, [], [ASK_USER]) : allowedTools,
             connectors: available.connectors.filter((id) => requested.connectors.includes(id)),
             contributions: available.contributions.filter((id) => requested.contributions.includes(id))
         };
@@ -667,6 +760,7 @@ export class Sessions {
                 workspaceRoot,
                 sessionDir: input.sessionDir,
                 historyFile,
+                ...(input.newHistory ? { newHistory: true } : {}),
                 model: input.model ?? null,
                 effort: input.effort ?? null,
                 text: goalStart ?? input.text,
@@ -701,9 +795,10 @@ export class Sessions {
                 ...(goalController ? { goal: goalHandle } : {}),
                 // A command sends no request of its own, so the context update waits for the next turn.
                 update: input.command ? null : update,
+                ...(input.hiddenNotes?.length && !input.command ? { hiddenNotes: input.hiddenNotes } : {}),
                 ...(input.command ? { command: input.command } : {})
             };
-            pi = await this.factory({
+            const factoryInput = {
                 params,
                 allow,
                 gate,
@@ -711,15 +806,67 @@ export class Sessions {
                 runtime: () => this.options.accounts.runtime(context),
                 // An unattended run loads no extension, so it has nobody to relay for.
                 ...(input.automatic ? {} : { extensions: { ask: (question) => run.requestAnswer(question), notice: (notice) => run.emit('extension.notice', notice) } })
-            });
+            };
+            // A live session serves this run only when everything the run pins is what it was opened with.
+            const liveId = input.live ? input.run.sessionId : null;
+            const pin = liveId ? livePin({
+                account: account.id,
+                configDir: context.configDir,
+                variantScope: variant?.scope ?? null,
+                variantVersion: variant?.fingerprint ?? null,
+                variantExtensions: params.variantExtensions,
+                resources: params.resources,
+                capabilities,
+                cwd: input.cwd,
+                workspaceRoot,
+                sessionDir: input.sessionDir,
+                plan: Boolean(input.plan),
+                repairPlan: Boolean(params.repairPlan),
+                allow,
+                tools: tools.map((tool) => tool.name),
+                gated: input.tools.gated ?? [],
+                system,
+                model: input.model ?? null,
+                effort: input.effort ?? null,
+                inline: (params.inline ?? []).map((extension) => extension.name),
+                providers: input.providers !== false
+            }) : null;
+            const reused = liveId && pin ? this.live.claim(liveId, pin, runId, historyFile, input.resume?.nativeSessionId) : null;
+            if (reused) {
+                pi = reused;
+                try {
+                    await reused.rebind(factoryInput);
+                }
+                catch (error) {
+                    this.live.discard(liveId, reused);
+                    throw error;
+                }
+            }
+            else {
+                pi = await this.factory(factoryInput);
+                if (liveId && pin && pi.rebind)
+                    this.live.hold(liveId, pin, pi, runId, input.sessionDir);
+            }
+            const held = liveId && this.live.status(liveId)?.activeRunId === runId ? liveId : null;
+            const opened0 = pi;
+            const discard = () => {
+                if (held)
+                    this.live.discard(held, opened0);
+                else
+                    opened0.dispose();
+            };
             if (run.finished) {
-                pi.dispose();
+                discard();
                 return { runId, nativeSessionId: null };
             }
             if ((input.requiresImageInput || input.images?.length) && !pi.model?.input.includes('image')) {
+                discard();
+                pi = undefined;
                 throw new HarnessError('image_input_unsupported', 'Choose a model that supports images, or remove the image attachments and send again.');
             }
             if (input.resume?.nativeSessionId && pi.sessionId !== input.resume.nativeSessionId) {
+                discard();
+                pi = undefined;
                 run.finish('failed', { code: 'native_resume_unavailable', message: 'The saved conversation could not be restored.' });
                 throw new HarnessError('native_resume_unavailable', 'The saved conversation could not be restored.');
             }
@@ -750,11 +897,21 @@ export class Sessions {
             if (openedModel)
                 this.options.subagents.resolvedModel(runId, openedModel, pi.thinkingLevel);
             params.settle = () => this.options.subagents.verify(runId, opened.sessionManager ? subagentHistory(opened.sessionManager.getBranch()) : undefined);
+            if (held) {
+                this.live.started(held, runId);
+                this.liveInputs.set(held, structuredClone(input));
+                params.release = (close) => this.live.release(held, runId, close);
+            }
             void runTurn(run, pi, params).then(() => (sliceEnabled && !input.command ? this.continueSlice({ root, runId, source: input, policy: slicePolicy }) : undefined));
             return { runId, nativeSessionId: pi.sessionId };
         }
         catch (error) {
-            pi?.dispose();
+            if (pi) {
+                if (input.live && this.live.status(input.run.sessionId)?.activeRunId === runId)
+                    this.live.discard(input.run.sessionId, pi);
+                else
+                    pi.dispose();
+            }
             if (error instanceof HarnessError && error.code === 'native_resume_unavailable')
                 throw error;
             const message = error instanceof Error ? error.message : String(error);