@xingular/harness 1.6.0-unstable → 2.0.1-unstable

package/dist/sdk/cli.js

@@ -26,7 +26,7 @@ import { runAppsCli, runWikiCli } from "./terminal/cli.js";
 import { runStandaloneTerminal, standaloneArguments } from "./terminal/standalone.js";
 import { runWorktreeCli } from "./worktrees/cli.js";
 const USAGE = `Usage: xagent [--data <dir>] [--state <dir>]
-       xagent <terminal | serve | wiki | mcp | plugins | hub | refine | web | browser | worktree> [arguments]
+       xagent <terminal | serve | daemon | attach | wiki | mcp | plugins | hub | refine | web | browser | worktree> [arguments]
 
   --version          Print the package version
   (no command)       Start the interactive Harness terminal
@@ -58,6 +58,13 @@ Standalone terminal options:
   --variant <scope>  Run on this variant scope's head (default: interactive profile scope)
   --remote-control, --rc
                      Turn on /remote-control at start, to continue from a phone or iPad
+  --daemon           Run in the long-lived harness for these folders (started when needed),
+                     so a reply keeps running when this window closes
+
+Long-lived harness (ADR-0083):
+  daemon <start | stop | status>
+                     Start, stop or check the harness that --daemon windows use
+  attach [session]   Reattach a window to a reply that kept running after its window closed
 `;
 function flags(argv) {
     const values = {};
@@ -132,6 +139,14 @@ async function main() {
         return runStandaloneTerminal(terminalArgs);
     if (command === 'serve')
         return serveCommand(rest);
+    if (command === 'daemon' || command === 'attach') {
+        // ADR-0083: the long-lived harness for these folders, and reattaching a window to it.
+        const positional = rest[0] && !rest[0].startsWith('-') ? rest[0] : undefined;
+        const { resolveStandaloneOptions } = await import("./terminal/standalone.js");
+        const { paths, profile } = resolveStandaloneOptions(positional ? rest.slice(1) : rest);
+        const daemon = await import("./terminal/daemon.js");
+        return command === 'daemon' ? daemon.runDaemonCommand(positional, paths, profile) : daemon.runAttach(paths, profile, positional, process.cwd());
+    }
     if (command === 'wiki')
         return runWikiCli(rest);
     if (command === 'mcp')

package/dist/sdk/harness.js

@@ -208,7 +208,7 @@ export class Harness {
         this.refine = new Refinements({ root: () => this.env.root, bus: this.bus, trust: this.trust, host: () => this.refineHost, runtime: refineRuntime });
         this.lessons = new Lessons({ root: () => this.env.root, runtime: refineRuntime });
         this.pageNotes = new NoteDeliveries({ root: () => this.env.root, bus: this.bus, terminals: () => this.terminals ?? null });
-        this.terminals = new Terminals({ trust: this.trust, subagents: this.subagents, sideQuestions: this.sideQuestions, resolveCapabilities: (caller, tools, cwd) => capabilities.resolve(this, { agentId: caller.agentId ?? null, projectId: caller.projectId ?? null, cwd, tools }), env: this.env, stateDir: this.stateDir, accounts: this.accounts, runs: this.runs, approvals: this.approvals, apps: this.apps, policy: this.policy, bus: this.bus, plugins: this.plugins, usage: this.usage, usageLimits: this.usageLimits, pluginControl: { list: (scope) => pluginApi.list(this, scope), attach: (params, on) => pluginApi.attach(this, params, on), trust: (scope) => pluginApi.trust(this, scope), untrust: (scope) => pluginApi.untrust(this, scope), configure: (params) => pluginApi.configure(this, params), install: params => pluginInstall.install(this, params), remove: params => pluginInstall.remove(this, params), proposals: { list: () => pluginProposals.list(this.env.root), preview: id => pluginProposals.preview(this.env.root, id), accept: (id, hash) => pluginProposals.accept(this, id, hash), reject: (id, hash) => pluginProposals.reject(this.env.root, id, hash) } }, assets: options.assets, hub: this.hub, world: this.world, doctor: this.doctor, worktrees: this.worktrees, noteCapture: this.noteCapture, pageNotes: this.pageNotes, refine: this.refine });
+        this.terminals = new Terminals({ trust: this.trust, subagents: this.subagents, sideQuestions: this.sideQuestions, resolveCapabilities: (caller, tools, cwd) => capabilities.resolve(this, { agentId: caller.agentId ?? null, projectId: caller.projectId ?? null, cwd, tools }), env: this.env, stateDir: this.stateDir, accounts: this.accounts, runs: this.runs, approvals: this.approvals, apps: this.apps, policy: this.policy, bus: this.bus, plugins: this.plugins, usage: this.usage, usageLimits: this.usageLimits, pluginControl: { list: (scope) => pluginApi.list(this, scope), attach: (params, on) => pluginApi.attach(this, params, on), trust: (scope) => pluginApi.trust(this, scope), untrust: (scope) => pluginApi.untrust(this, scope), configure: (params) => pluginApi.configure(this, params), install: params => pluginInstall.install(this, params), remove: params => pluginInstall.remove(this, params), proposals: { list: () => pluginProposals.list(this.env.root), preview: id => pluginProposals.preview(this.env.root, id), accept: (id, hash) => pluginProposals.accept(this, id, hash), reject: (id, hash) => pluginProposals.reject(this.env.root, id, hash) } }, assets: options.assets, hub: this.hub, world: this.world, doctor: this.doctor, worktrees: this.worktrees, noteCapture: this.noteCapture, pageNotes: this.pageNotes, refine: this.refine, sessionService: this.sessions });
         this.ready = this.apps.start().catch((error) => log('connected apps', error instanceof Error ? error.message : String(error)));
         this.runs.listen((event, run) => {
             this.accounts.onRunEvent(event, run);
@@ -359,6 +359,7 @@ export class Harness {
         await this.refine.close();
         await this.lessons.close();
         await this.terminals.close();
+        this.sessions.close();
         await this.noteCapture.close();
         await this.sideQuestions.close();
         await this.runs.interruptAll();

package/dist/sdk/prompt/reporting.d.ts

@@ -1,2 +1,2 @@
-export declare const REPORTING_GUIDANCE = "The final answer must always be fully self-contained: users should never need to read earlier commentary updates, since they are collapsed after the final answer is shown to users. In your final answer, focus on the most important information.\n\nAssume the person may have stepped away and lost the thread. Write so they can pick the work back up cold: give enough context to understand the outcome and what remains, and match the explanation to what their request signals about their experience.\n\nReporting is for work that is finished or genuinely blocked. Do not end a turn to report work you can still do.\n\n### Technical communication\n\nUse plain language over jargon, and reference technical details only to the degree that it actually helps the conversation. Communicate complex concepts in a clear and cohesive manner. The user should never have to read your writing twice to understand it.\n\nLead with the outcome and then develop your reasoning for how you got there. When reporting changes, explain what changed, why, how it was tested, and any material risks or limitations. Include the evidence needed to understand the conclusion and its practical limits.\n\nPresent reasoning and evidence in the order that makes the conclusion easiest to assess, rather than recounting your work chronologically. Summarize routine verification instead of listing every check.\n\nEvery claim needs evidence. If you did not run a check, say so; never imply that it passed. If a check failed, report the failure and relevant output. When a check passed, state that plainly.\n\nWhen someone needs to act, state the specific next step and why. Omit it when there is no person-owned action; do not add a filler ending.\n\nUse tables for mappings or comparisons.\n\n### Headings\n\nFor a substantive reply with distinct parts, often structure it with Markdown headings: use a # title when it helps, then ## headings for meaningful sections. Name each heading for the content of this reply. \"What changed\", \"Checks\" and \"Things to know\" are examples, not a fixed set; do not reuse them by default. Short replies may stay in prose; do not force headings or create empty sections.\n\n### Shape by work\n\n| The work | What the reader needs |\n|---|---|\n| A code change | outcome, what changed and why, how it was tested, risks |\n| A document or copy | what changed in the text, where to read it |\n| An answer or research | the answer, then the evidence and its limits |\n| A diagnosis | the cause, the fix, what to watch for |\n| A publish or release | what is ready, what to review, the risks |\n| Config or operations | what changed where, the rollback, who runs it |\n\n### Length\n\nScale detail to complexity: a simple change usually needs one or two sentences plus the validation, and a larger change needs the reasoning, the evidence and the risks. Research is as long as the evidence needs. Never repeat the request, the plan or the previous message to fill space.\n\n### Prose and lists\n\nWrite in connected prose. Use lists only when the information is genuinely parallel, sequential, or easier to compare, and avoid nested lists unless the hierarchy cannot be expressed clearly in prose. Use a table when several items share fields.\n\n### References and formatting\n\nFollow the file-link and citation format supplied by the active session or host. Cite files or sources that help the person assess the result or continue the work; do not impose an extra format.\n\n### Subagent reports\n\nWhen you are a subagent, give the caller a concise report of what you did and the key findings; the caller will integrate and relay the result. Include absolute file paths and evidence needed to use the findings. Include snippets only when the exact text is load-bearing, and do not recap code you merely read.\n\n### Examples\n\nThese examples show possible shapes, not a fixed heading set or wording.\n\n#### Example 1 \u2014 a screen change\n\n    # The selected tab survives a reload\n\n    ## Stored choice\n    Settings now remembers the last selected tab.\n\n    ## Verification\n    `npm test`: 12 passed, including the two tab tests. I did not open it in a browser, so the\n    visual result is unverified.\n\n    ## Older settings\n    A missing value falls back to \"General\"; an old key is ignored, not migrated.\n\n#### Example 2 \u2014 a blocked publish\n\n    The release notes for 1.4.0 are written. The tag and the publish did not run: this shell has no\n    authenticated GitHub CLI.\n\n    Run `gh auth login --hostname github.com` in the project folder; then I can tag `v1.4.0` and\n    push. Nothing has been published.\n\n### Before you send\n\n- The first line says what happened and whether it is done.\n- Every claim carries the evidence that supports it; any check not run is named as unrun.\n- Any headings name this reply's actual content and are not forced.\n- Nothing is repeated from the request or the plan.\n";
+export declare const REPORTING_GUIDANCE = "The final answer must always be fully self-contained: users should never need to read earlier commentary updates, since they are collapsed after the final answer is shown to users. In your final answer, focus on the most important information.\n\nAssume the person may have stepped away and lost the thread. Write so they can pick the work back up cold: give enough context to understand the outcome and what remains, and match the explanation to what their request signals about their experience.\n\nReporting is for work that is finished or genuinely blocked. Do not end a turn to report work you can still do.\n\n### Technical communication\n\nUse plain language over jargon, and reference technical details only to the degree that it actually helps the conversation. Communicate complex concepts in a clear and cohesive manner. The user should never have to read your writing twice to understand it.\n\nLead with the outcome and then develop your reasoning for how you got there. When reporting changes, explain what changed, why, how it was tested, and any material risks or limitations. Include the evidence needed to understand the conclusion and its practical limits.\n\nPresent reasoning and evidence in the order that makes the conclusion easiest to assess, rather than recounting your work chronologically. Summarize routine verification instead of listing every check.\n\nEvery claim needs evidence. If you did not run a check, say so; never imply that it passed. If a check failed, report the failure and relevant output. When a check passed, state that plainly.\n\nWhen someone needs to act, state the specific next step and why. Omit it when there is no person-owned action; do not add a filler ending.\n\nUse tables for mappings or comparisons.\n\n### Headings\n\nFor a substantive reply with distinct parts, often structure it with Markdown headings: use a # title when it helps, then ## headings for meaningful sections. Name each heading for the content of this reply. \"What changed\", \"Checks\" and \"Things to know\" are examples, not a fixed set; do not reuse them by default. Short replies may stay in prose; do not force headings or create empty sections.\n\n### Shape by work\n\n| The work | What the reader needs |\n|---|---|\n| A code change | outcome, what changed and why, how it was tested, risks |\n| A document or copy | what changed in the text, where to read it |\n| An answer or research | the answer, then the evidence and its limits |\n| A diagnosis | the cause, the fix, what to watch for |\n| A publish or release | what is ready, what to review, the risks |\n| Config or operations | what changed where, the rollback, who runs it |\n\n### Length\n\nScale detail to complexity: a simple change usually needs one or two sentences plus the validation, and a larger change needs the reasoning, the evidence and the risks. Research is as long as the evidence needs. Never repeat the request, the plan or the previous message to fill space.\n\n### Prose and lists\n\nWrite in connected prose. Use lists only when the information is genuinely parallel, sequential, or easier to compare, and avoid nested lists unless the hierarchy cannot be expressed clearly in prose. Use a table when several items share fields.\n\n### References and formatting\n\nFollow the file-link and citation format supplied by the active session or host. Cite files or sources that help the person assess the result or continue the work; do not impose an extra format. For code-like output, use fenced Markdown blocks with a language identifier such as `python`, `bash` or `typescript`; put commands the person must run in a `bash` block, and keep short references inline.\n\n### Subagent reports\n\nWhen you are a subagent, give the caller a concise report of what you did and the key findings; the caller will integrate and relay the result. Include absolute file paths and evidence needed to use the findings. Include snippets only when the exact text is load-bearing, and do not recap code you merely read.\n\n### Examples\n\nThese examples show possible shapes, not a fixed heading set or wording.\n\n#### Example 1 \u2014 a screen change\n\n    # The selected tab survives a reload\n\n    ## Stored choice\n    Settings now remembers the last selected tab.\n\n    ## Verification\n    `npm test`: 12 passed, including the two tab tests. I did not open it in a browser, so the\n    visual result is unverified.\n\n    ## Older settings\n    A missing value falls back to \"General\"; an old key is ignored, not migrated.\n\n#### Example 2 \u2014 a blocked publish\n\n    The release notes for 1.4.0 are written. The tag and the publish did not run: this shell has no\n    authenticated GitHub CLI.\n\n    Run this in the project folder:\n\n    ```bash\n    gh auth login --hostname github.com\n    ```\n\n    Then I can tag `v1.4.0` and push. Nothing has been published.\n\n### Before you send\n\n- The first line says what happened and whether it is done.\n- Every claim carries the evidence that supports it; any check not run is named as unrun.\n- Any headings name this reply's actual content and are not forced.\n- Nothing is repeated from the request or the plan.\n";
 export declare const REPORTING_BUDGET = 12000;

package/dist/sdk/prompt/reporting.js

@@ -47,7 +47,7 @@ Write in connected prose. Use lists only when the information is genuinely paral
 
 ### References and formatting
 
-Follow the file-link and citation format supplied by the active session or host. Cite files or sources that help the person assess the result or continue the work; do not impose an extra format.
+Follow the file-link and citation format supplied by the active session or host. Cite files or sources that help the person assess the result or continue the work; do not impose an extra format. For code-like output, use fenced Markdown blocks with a language identifier such as \`python\`, \`bash\` or \`typescript\`; put commands the person must run in a \`bash\` block, and keep short references inline.
 
 ### Subagent reports
 
@@ -76,8 +76,13 @@ These examples show possible shapes, not a fixed heading set or wording.
     The release notes for 1.4.0 are written. The tag and the publish did not run: this shell has no
     authenticated GitHub CLI.
 
-    Run \`gh auth login --hostname github.com\` in the project folder; then I can tag \`v1.4.0\` and
-    push. Nothing has been published.
+    Run this in the project folder:
+
+    \`\`\`bash
+    gh auth login --hostname github.com
+    \`\`\`
+
+    Then I can tag \`v1.4.0\` and push. Nothing has been published.
 
 ### Before you send
 

package/dist/sdk/server/methods.js

@@ -326,13 +326,18 @@ export function methods(harness) {
         // ---- Sessions ----------------------------------------------------------------------------------
         'sessions.spawnSubagent': (params) => sessions.spawnSubagent(params),
         'sessions.run': (params) => sessions.run(params),
+        // Live sessions (ADR-0083): Pi sessions kept open between the runs of a conversation.
+        'sessions.live': () => ({ sessions: sessions.liveSessions() }),
+        'sessions.close': (params) => sessions.closeLive(text(params, 'sessionId')),
+        'sessions.followUp': (params) => sessions.followUp(text(params, 'sessionId'), text(params, 'text')),
+        'sessions.followUp.clear': (params) => ({ removed: sessions.live.clearQueue(text(params, 'sessionId')) }),
         'sessions.history': (params) => ({ sessionFile: selectHistory({ sessionDir: text(params, 'sessionDir'), resume: params.resume ?? null }) }),
         // The commands that need no model act on the saved history; see sessions/control.ts.
         'sessions.tree': (params) => control.tree(sessionRef(params)),
-        'sessions.navigate': (params) => control.navigate({ ...sessionRef(params), entryId: text(params, 'entryId') }),
+        'sessions.navigate': (params) => { sessions.live.yieldHistory({ sessionDir: sessionRef(params).sessionDir }); return control.navigate({ ...sessionRef(params), entryId: text(params, 'entryId') }); },
         'sessions.fork': (params) => control.fork({ ...sessionRef(params), entryId: text(params, 'entryId'), targetDir: text(params, 'targetDir') }),
         'sessions.clone': (params) => control.clone({ ...sessionRef(params), targetDir: text(params, 'targetDir') }),
-        'sessions.rename': (params) => control.rename({ ...sessionRef(params), name: text(params, 'name') }),
+        'sessions.rename': (params) => { sessions.live.yieldHistory({ sessionDir: sessionRef(params).sessionDir }); return control.rename({ ...sessionRef(params), name: text(params, 'name') }); },
         'sessions.lastReply': (params) => control.lastReply(sessionRef(params)),
         'sessions.export': (params) => control.exportJsonl({ ...sessionRef(params), path: text(params, 'path') }),
         // Each structured turn loads its resources fresh; this reloads what lives between turns.
@@ -347,7 +352,11 @@ export function methods(harness) {
         'terminal.send': (params) => terminals.send({ sessionId: text(params, 'sessionId'), runId: optional(params, 'runId'), text: text(params, 'text') }),
         'terminal.input': (params) => terminals.input(text(params, 'sessionId'), typeof params.data === 'string' ? params.data : ''),
         'terminal.state': (params) => terminals.state(text(params, 'sessionId')),
-        'terminal.dispose': (params) => terminals.dispose(text(params, 'sessionId'))
+        'terminal.dispose': (params) => terminals.dispose(text(params, 'sessionId')),
+        // ADR-0083 phase 3: a client terminal's reply may outlive its window.
+        'terminal.detach': (params) => terminals.detach(text(params, 'sessionId')),
+        'terminal.detached': () => ({ sessions: terminals.detached() }),
+        'terminal.takeRelaunch': (params) => terminals.takeRelaunch(text(params, 'sessionId'))
     };
     const overlap = Object.keys(foundation).find(name => name in builtins);
     if (overlap)

package/dist/sdk/server/serve.d.ts

@@ -5,6 +5,9 @@ export interface Served {
     /** Stops live work and releases what the harness holds. */
     shutdown(): Promise<void>;
 }
-/** Registers the method table on `peer` and forwards events and notices to it. */
-export declare function attach(harness: Harness, peer: RpcPeer): void;
+/**
+ * Registers the method table on `peer` and forwards events and notices to it. Returns what stops the
+ * forwarding, for a peer that goes away before the harness does (a socket connection).
+ */
+export declare function attach(harness: Harness, peer: RpcPeer): () => void;
 export declare function serve(harness: Harness, transport: Transport): Served;

package/dist/sdk/server/serve.js

@@ -1,12 +1,19 @@
 import { methods } from "./methods.js";
 import { RpcPeer } from "./rpc.js";
-/** Registers the method table on `peer` and forwards events and notices to it. */
+/**
+ * Registers the method table on `peer` and forwards events and notices to it. Returns what stops the
+ * forwarding, for a peer that goes away before the harness does (a socket connection).
+ */
 export function attach(harness, peer) {
     for (const [name, handler] of Object.entries(methods(harness)))
         peer.handle(name, handler);
     peer.handle('harness.methods', () => peer.methods());
-    harness.runs.listen((event) => peer.send({ event }));
-    harness.bus.on((notice) => peer.send({ notice }));
+    const stopEvents = harness.runs.listen((event) => peer.send({ event }));
+    const stopNotices = harness.bus.on((notice) => peer.send({ notice }));
+    return () => {
+        stopEvents();
+        stopNotices();
+    };
 }
 export function serve(harness, transport) {
     const peer = new RpcPeer(transport);

package/dist/sdk/server/socket.d.ts

@@ -0,0 +1,28 @@
+import { type Socket } from 'node:net';
+import type { Harness } from "../harness.js";
+import { type Transport } from "./rpc.js";
+/** Protocol lines over one socket. */
+export declare function socketTransport(socket: Socket): Transport;
+export interface SocketServer {
+    path: string;
+    close(): Promise<void>;
+    /** Connections open now. */
+    connections(): number;
+}
+/**
+ * Serves `harness` on a socket at `path`, readable and writable by this user only. Each connection
+ * gets the whole method table and the run events and notices while it is open.
+ */
+export declare function serveSocket(harness: Harness, path: string, extra?: Record<string, (params: Record<string, unknown>) => unknown>): Promise<SocketServer>;
+export interface HarnessClient {
+    call<T = unknown>(method: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<T>;
+    /** Run events and notices the harness sends while connected. */
+    onMessage(listener: (message: {
+        event?: unknown;
+        notice?: unknown;
+    }) => void): () => void;
+    close(): void;
+    readonly closed: Promise<void>;
+}
+/** Connects to a harness serving on `path`. */
+export declare function connectHarness(path: string): Promise<HarnessClient>;

package/dist/sdk/server/socket.js

@@ -0,0 +1,122 @@
+// The server protocol (page 10) on a local Unix socket, one peer per connection, so more than one
+// client can reach the same long-lived harness (ADR-0083, phase 3). The framing is the stdio
+// protocol's: one JSON message per line.
+import { chmodSync, existsSync, rmSync } from 'node:fs';
+import { createConnection, createServer } from 'node:net';
+import { createInterface } from 'node:readline';
+import { HarnessError } from "../core/errors.js";
+import { PROTOCOL_VERSION, RpcPeer } from "./rpc.js";
+import { attach } from "./serve.js";
+/** Protocol lines over one socket. */
+export function socketTransport(socket) {
+    const reader = createInterface({ input: socket, crlfDelay: Infinity });
+    return {
+        write: (line) => { if (!socket.destroyed)
+            socket.write(`${line}\n`); },
+        onLine: (listener) => void reader.on('line', listener)
+    };
+}
+/**
+ * Serves `harness` on a socket at `path`, readable and writable by this user only. Each connection
+ * gets the whole method table and the run events and notices while it is open.
+ */
+export async function serveSocket(harness, path, extra = {}) {
+    if (existsSync(path))
+        rmSync(path, { force: true });
+    const open = new Set();
+    const server = createServer((socket) => {
+        open.add(socket);
+        const peer = new RpcPeer(socketTransport(socket));
+        const stop = attach(harness, peer);
+        for (const [name, handler] of Object.entries(extra))
+            peer.handle(name, handler);
+        const gone = () => {
+            open.delete(socket);
+            stop();
+        };
+        socket.once('close', gone);
+        socket.on('error', () => socket.destroy());
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(path, () => {
+            server.off('error', reject);
+            resolve();
+        });
+    });
+    chmodSync(path, 0o600);
+    return {
+        path,
+        connections: () => open.size,
+        close: async () => {
+            for (const socket of open)
+                socket.destroy();
+            await new Promise((resolve) => server.close(() => resolve()));
+            rmSync(path, { force: true });
+        }
+    };
+}
+/** Connects to a harness serving on `path`. */
+export async function connectHarness(path) {
+    const socket = createConnection(path);
+    await new Promise((resolve, reject) => {
+        socket.once('connect', resolve);
+        socket.once('error', reject);
+    });
+    const reader = createInterface({ input: socket, crlfDelay: Infinity });
+    const pending = new Map();
+    const listeners = new Set();
+    let next = 0;
+    const closed = new Promise((resolve) => socket.once('close', () => {
+        for (const [, call] of pending) {
+            clearTimeout(call.timer);
+            call.reject(new HarnessError('harness_unavailable', 'The harness closed the connection.'));
+        }
+        pending.clear();
+        resolve();
+    }));
+    socket.on('error', () => undefined);
+    reader.on('line', (line) => {
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (message.v !== PROTOCOL_VERSION)
+            return;
+        if (typeof message.id === 'string' && pending.has(message.id)) {
+            const call = pending.get(message.id);
+            pending.delete(message.id);
+            clearTimeout(call.timer);
+            if (message.error) {
+                const shape = message.error;
+                call.reject(new HarnessError(shape.code, shape.message, shape.retryHint ?? null));
+            }
+            else
+                call.resolve(message.result);
+            return;
+        }
+        if ('event' in message || 'notice' in message)
+            for (const listener of listeners)
+                listener(message);
+    });
+    return {
+        call: (method, params = {}, timeoutMs = 60_000) => new Promise((resolve, reject) => {
+            const id = `c${++next}`;
+            const timer = setTimeout(() => {
+                pending.delete(id);
+                reject(new HarnessError('harness_timeout', `The harness did not answer ${method}.`));
+            }, timeoutMs);
+            pending.set(id, { resolve: resolve, reject, timer });
+            socket.write(`${JSON.stringify({ v: PROTOCOL_VERSION, id, method, params })}\n`);
+        }),
+        onMessage: (listener) => {
+            listeners.add(listener);
+            return () => { listeners.delete(listener); };
+        },
+        close: () => socket.end(),
+        closed
+    };
+}

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

@@ -479,6 +479,19 @@ export declare const runEventPayloadSchemas: {
         multiSelect: z.ZodBoolean;
         allowText: z.ZodBoolean;
         userOnly: z.ZodOptional<z.ZodBoolean>;
+        dialog: z.ZodOptional<z.ZodObject<{
+            kind: z.ZodEnum<{
+                input: "input";
+                select: "select";
+                confirm: "confirm";
+                editor: "editor";
+            }>;
+            title: z.ZodString;
+            message: z.ZodOptional<z.ZodString>;
+            placeholder: z.ZodOptional<z.ZodString>;
+            prefill: z.ZodOptional<z.ZodString>;
+            options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
     }, z.core.$strip>;
     'question.answered': z.ZodObject<{
         batchId: z.ZodOptional<z.ZodString>;
@@ -492,10 +505,10 @@ export declare const runEventPayloadSchemas: {
     'extension.notice': z.ZodObject<{
         kind: z.ZodEnum<{
             error: "error";
+            title: "title";
             notify: "notify";
             status: "status";
             widget: "widget";
-            title: "title";
         }>;
         level: z.ZodOptional<z.ZodEnum<{
             error: "error";

package/dist/sdk/sessions/contracts.js

@@ -223,6 +223,15 @@ const questionRequestedPayload = z.object({
     multiSelect: z.boolean(),
     allowText: z.boolean(),
     userOnly: z.boolean().optional(),
+    /** The Pi extension dialog this question stands for (ADR-0083); a host may ignore it. */
+    dialog: z.object({
+        kind: z.enum(['select', 'confirm', 'input', 'editor']),
+        title: z.string().max(4_000),
+        message: z.string().max(4_000).optional(),
+        placeholder: z.string().max(4_000).optional(),
+        prefill: z.string().max(100_000).optional(),
+        options: z.array(z.string().max(4_000)).max(200).optional()
+    }).optional(),
     ...questionBatchFields
 }).superRefine(questionBatchRefinement).superRefine((value, context) => {
     const error = questionSketchError(value.uiSketch, value.options);

package/dist/sdk/sessions/extensionUi.js

@@ -24,11 +24,11 @@ const plainTheme = new Proxy({}, { get: () => (...args) => String(args[args.leng
 export function extensionUi(host) {
     const context = {
         select: (title, options, opts) => dismissable(options.length
-            ? host.ask({ question: clip(title), options: options.map((label, index) => ({ label, ...(index === 0 ? { recommended: true } : {}) })), multiSelect: false, allowText: false }).then((answer) => answer.selected[0])
+            ? host.ask({ question: clip(title), options: options.map((label, index) => ({ label, ...(index === 0 ? { recommended: true } : {}) })), multiSelect: false, allowText: false, dialog: { kind: 'select', title: clip(title), options: options.map(clip) } }).then((answer) => answer.selected[0])
             : Promise.resolve(undefined), undefined, opts),
-        confirm: (title, message, opts) => dismissable(host.ask({ question: clip(message ? `${title}\n\n${message}` : title), options: [{ label: 'Yes' }, { label: 'No', recommended: true }], multiSelect: false, allowText: false }).then((answer) => answer.selected[0] === 'Yes'), false, opts),
-        input: (title, placeholder, opts) => dismissable(host.ask({ question: clip(placeholder ? `${title} (${placeholder})` : title), options: [{ label: 'Type your response', recommended: true }], multiSelect: false, allowText: true }).then((answer) => answer.text || undefined), undefined, opts),
-        editor: (title, prefill) => host.ask({ question: clip(prefill ? `${title}\n\n${prefill}` : title), options: [{ label: 'Type your response', recommended: true }], multiSelect: false, allowText: true }).then((answer) => answer.text || undefined),
+        confirm: (title, message, opts) => dismissable(host.ask({ question: clip(message ? `${title}\n\n${message}` : title), options: [{ label: 'Yes' }, { label: 'No', recommended: true }], multiSelect: false, allowText: false, dialog: { kind: 'confirm', title: clip(title), ...(message ? { message: clip(message) } : {}) } }).then((answer) => answer.selected[0] === 'Yes'), false, opts),
+        input: (title, placeholder, opts) => dismissable(host.ask({ question: clip(placeholder ? `${title} (${placeholder})` : title), options: [{ label: 'Type your response', recommended: true }], multiSelect: false, allowText: true, dialog: { kind: 'input', title: clip(title), ...(placeholder ? { placeholder: clip(placeholder) } : {}) } }).then((answer) => answer.text || undefined), undefined, opts),
+        editor: (title, prefill) => host.ask({ question: clip(prefill ? `${title}\n\n${prefill}` : title), options: [{ label: 'Type your response', recommended: true }], multiSelect: false, allowText: true, dialog: { kind: 'editor', title: clip(title), ...(prefill ? { prefill: prefill.slice(0, 100_000) } : {}) } }).then((answer) => answer.text || undefined),
         notify: (message, level) => host.notice({ kind: 'notify', level: level ?? 'info', text: clip(message) }),
         setStatus: (key, text) => host.notice({ kind: 'status', key, text: clip(text ?? '') }),
         setWidget: (key, content) => {

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

@@ -0,0 +1,101 @@
+import type { PiSessionLike } from "./runner.js";
+import type { RunRecord } from "./contracts.js";
+/** How long an idle live session stays open, unless the caller sets another time. */
+export declare const LIVE_IDLE_MS: number;
+/** Follow-up messages one live session may hold. */
+export declare const MAX_FOLLOW_UPS = 20;
+export interface LiveSessionStatus {
+    sessionId: string;
+    nativeSessionId: string;
+    sessionFile: string | null;
+    /** The run using the session now, or null while it is idle. */
+    activeRunId: string | null;
+    lastRunId: string;
+    /** Runs this live session has served, the first included. */
+    runs: number;
+    openedAt: string;
+    idleSince: string | null;
+    /** Follow-up messages waiting for the active run to settle, oldest first. */
+    followUps: string[];
+}
+export interface LiveSessionsOptions {
+    idleMs?: number;
+    /** Reads a settled run, to decide whether its queued follow-ups go now. */
+    record(runId: string): RunRecord | null;
+    /** Starts a follow-up as the next run of the session. */
+    followUp(sessionId: string, lastRunId: string, text: string): Promise<void>;
+    log?(message: string): void;
+}
+/** The run fields a live session must share with a run before it may serve it. */
+export declare function livePin(fields: Record<string, unknown>): string;
+export declare class LiveSessions {
+    private readonly options;
+    private readonly entries;
+    /** Watchers of each session's native Pi events; they outlive a session replaced at a pin change. */
+    private readonly watchers;
+    private readonly unsubscribers;
+    /** Follow-ups of a session closed at a pin change, handed to the session that replaces it. */
+    private readonly parked;
+    private readonly idleMs;
+    constructor(options: LiveSessionsOptions);
+    /** Whether a run of this session is using its live session now. */
+    busy(sessionId: string): boolean;
+    /**
+     * The live session for this run, now marked in use, or null when there is none to reuse. An idle
+     * session whose pins, history or native id differ is closed here, at the turn boundary.
+     */
+    claim(sessionId: string, pin: string, runId: string, historyFile: string | null, nativeSessionId?: string | null): PiSessionLike | null;
+    /** Records the session a run just opened, so the next run of the conversation can reuse it. */
+    hold(sessionId: string, pin: string, pi: PiSessionLike, runId: string, sessionDir: string): void;
+    /** The run has started on the session: count it. */
+    started(sessionId: string, runId: string): void;
+    /**
+     * The run settled. The session stays open for the next run. A queued follow-up is sent after a
+     * reply that completed or that the person stopped; after a failure, or an interruption the person
+     * did not ask for, it stays parked (page 02, queued-message dispatch). `close` ends the session
+     * instead of keeping it, with its queue parked.
+     */
+    release(sessionId: string, runId: string, close?: boolean): void;
+    /**
+     * Something other than the live session is about to change this history: a separate command
+     * run or a saved-history edit. An idle live session closes, so its next run reads the file again;
+     * one that is replying refuses the change.
+     */
+    yieldHistory(match: {
+        sessionId?: string;
+        sessionDir?: string;
+    }): void;
+    /** The session could not serve the run after all: forget it and close it. */
+    discard(sessionId: string, pi: PiSessionLike): void;
+    /**
+     * Queues a message for after the active run, or reports that the session is idle so the caller
+     * starts it now.
+     */
+    queue(sessionId: string, text: string): {
+        queued: number;
+    } | {
+        idle: true;
+        lastRunId: string;
+    };
+    /** Drops the queued follow-ups and returns them, oldest first. */
+    clearQueue(sessionId: string): string[];
+    /**
+     * Receives the native Pi events of this conversation's live session, and of the one that replaces
+     * it, until the returned function is called (ADR-0083: a client renders from them).
+     */
+    watch(sessionId: string, watcher: (event: unknown) => void): () => void;
+    /** The open Pi session of a conversation, for a read of its current state. */
+    session(sessionId: string): PiSessionLike | null;
+    status(sessionId: string): LiveSessionStatus | null;
+    list(): LiveSessionStatus[];
+    /** Closes a live session now, or when its active run settles. */
+    close(sessionId: string): {
+        closed: boolean;
+        afterRun: string | null;
+    };
+    closeAll(): void;
+    private statusOf;
+    private startTimer;
+    private stopTimer;
+    private dispose;
+}