@tshu-w/pi-agents 0.1.0 → 0.2.0

package/src/agents/agents.ts

@@ -18,6 +18,8 @@ import { fileURLToPath } from "node:url";
 import {
 	customMessage,
 	deliver,
+	addProgramSpend,
+	addSpend,
 	label,
 	messageText,
 	MESSAGE_TYPE,
@@ -32,6 +34,7 @@ import {
 	type AgentState,
 	type Delivery,
 	type Entry,
+	type Spend,
 	type TreeMetadata,
 } from "./registry.ts";
 
@@ -121,8 +124,8 @@ function lastAnswer(session: AgentSession, before: number): { outcome: Outcome;
 	return { outcome: "completed", result: text };
 }
 
-/** Takes this extension's messages left in the agent queues after a run settles. */
-function takeQueued(agent: AgentSession["agent"]) {
+/** Takes this extension's messages out of the agent queues. */
+export function takeQueued(agent: AgentSession["agent"]) {
 	// peekQueuedMessages returns one message in one-at-a-time mode; read the queues whole.
 	const queues = agent as unknown as Record<"steeringQueue" | "followUpQueue", { messages: QueuedMessage[] }>;
 	const steering = queues.steeringQueue.messages.slice();
@@ -135,6 +138,19 @@ function takeQueued(agent: AgentSession["agent"]) {
 	return [...steering, ...followUps].filter(ours);
 }
 
+/** Whether a steer, which this turn must take in before its next model call, waits in the agent's queue; a write does not count. */
+export function steerQueued(agent: AgentSession["agent"] | undefined): boolean {
+	if (!agent) return false;
+	const queue = (agent as unknown as { steeringQueue: { messages: QueuedMessage[] } }).steeringQueue.messages;
+	return queue.some((message) => !(message.role === "custom" && message.customType === MESSAGE_TYPE
+		&& (message as { details?: { delivery?: string } }).details?.delivery === "write"));
+}
+
+// Pi does not report steers queued by extensions, so a wait checks the queue this often.
+export const STEER_POLL_MS = 250;
+
+export const WAIT_INTERRUPTED = "Stopped waiting for a new message. Wait again to keep waiting.";
+
 export interface Deferred {
 	promise: Promise<void>;
 	resolve(): void;
@@ -187,7 +203,7 @@ function ended(input: InputRecord): boolean {
 
 interface Input {
 	text: string;
-	/** The user's input from the Agent viewer. */
+	/** The user's input from the task viewer. */
 	user?: boolean;
 	record?: InputRecord;
 	permit?: symbol;
@@ -208,6 +224,10 @@ interface Turn {
 	started: boolean;
 	/** Whether the turn holds a scheduler slot. */
 	slot: boolean;
+	/** When the turn got its slot, in milliseconds. */
+	since?: number;
+	/** What the turn's replies have cost. */
+	spent: Spend;
 	finished: boolean;
 	done: Deferred;
 }
@@ -226,6 +246,8 @@ interface Owned {
 	loading?: Promise<AgentSession>;
 	prepared?: Prepared;
 	waiters: number;
+	/** Its turn was stopped: messages from other Agents become writes until its owner's or user's next input. */
+	stopped?: boolean;
 }
 
 export interface SpawnRequest {
@@ -246,6 +268,8 @@ export interface WaitResult {
 export interface WaitOutcome {
 	results: WaitResult[];
 	pending: AgentRecord[];
+	/** A steer ended the wait. */
+	interrupted?: boolean;
 }
 
 /** The Agents owned by one loaded Agent. */
@@ -287,11 +311,11 @@ export class Agents {
 		return [...this.agents.values()].some((agent) => agent.turn !== undefined || agent.queue.length > 0);
 	}
 
-	/** An owned Agent's state, and its inputs pending behind its current or next turn. */
-	counts(id: string): { state: AgentState; pending: number } | undefined {
+	/** An owned Agent's state, its inputs pending behind its current or next turn, when its turn got a slot, and what the turn has cost. */
+	counts(id: string): { state: AgentState; pending: number; since?: number; spent?: Spend } | undefined {
 		const agent = this.agents.get(id);
 		if (!agent) return undefined;
-		return { state: this.state(agent), pending: agent.queue.length };
+		return { state: this.state(agent), pending: agent.queue.length, since: agent.turn?.since, spent: agent.turn?.spent };
 	}
 
 	private state(agent: Owned): AgentState {
@@ -393,14 +417,25 @@ export class Agents {
 	/**
 	 * Sends an input from the owner and resolves when it ends. With a schema, the Agent must call
 	 * `submit_result` with a matching value, which becomes the input's `value`; `text` tells it so.
+	 * An input not ended within `timeoutMs` is aborted alone, and `timedOut` is set.
 	 */
-	async request(id: string, text: string, delivery: "followUp" | "steer", schema?: unknown): Promise<InputRecord> {
+	async request(id: string, text: string, delivery: "followUp" | "steer", schema?: unknown, timeoutMs?: number): Promise<{ record: InputRecord; timedOut: boolean }> {
 		const agent = this.agent(id);
 		const input: Input = { text, permit: this.reserve(), record: this.newRecord(agent), done: deferred() };
 		if (schema !== undefined) input.schema = schema;
 		this.add(agent, input, delivery);
-		await input.done!.promise;
-		return input.record!;
+		let stopping: Promise<void> | undefined;
+		const timer = timeoutMs === undefined ? undefined : setTimeout(() => {
+			stopping = this.cancel(agent, input);
+			stopping.catch(() => {});
+		}, timeoutMs);
+		try {
+			await input.done!.promise;
+		} finally {
+			clearTimeout(timer);
+		}
+		await stopping;
+		return { record: input.record!, timedOut: stopping !== undefined && input.record!.state === "aborted" };
 	}
 
 	/** Records a value from `submit_result` for the Agent's current input with a schema. */
@@ -416,6 +451,7 @@ export class Agents {
 
 	accept(id: string, text: string, delivery: Delivery, options: { fromOwner: boolean; notification: boolean }): { queued: boolean } {
 		const agent = this.agent(id);
+		if (agent.stopped && !options.fromOwner) delivery = "write";
 		if (delivery === "write") {
 			this.write(agent, text);
 			return { queued: false };
@@ -426,7 +462,7 @@ export class Agents {
 		return { queued: this.add(agent, input, delivery) };
 	}
 
-	async wait(targets: Owned[] | undefined, history: number, timeoutSeconds: number, signal?: AbortSignal): Promise<WaitOutcome> {
+	async wait(targets: Owned[] | undefined, history: number, timeoutSeconds: number, signal?: AbortSignal, steered?: () => boolean): Promise<WaitOutcome> {
 		const selected = targets ?? [...this.agents.values()].filter((agent) =>
 			this.pending(agent) || agent.record.inputs.some((input) => ended(input) && !input.read));
 		const unique = [...new Set(selected)];
@@ -438,13 +474,18 @@ export class Agents {
 		const suspended = blocking && this.self.ownerId !== undefined && scheduler.suspend(this.self.rootId, this.self.id);
 		if (blocking) this.markWaiting(1);
 		let returned = false;
+		let interrupted = false;
 		try {
 			const deadline = Date.now() + timeoutSeconds * 1000;
 			while (unique.some((agent) => this.pending(agent))) {
 				const remaining = deadline - Date.now();
 				if (remaining <= 0) break;
+				if (steered?.()) {
+					interrupted = true;
+					break;
+				}
 				signal?.throwIfAborted();
-				await waitForChange(this.change.promise, remaining, signal);
+				await waitForChange(this.change.promise, steered ? Math.min(remaining, STEER_POLL_MS) : remaining, signal);
 			}
 			signal?.throwIfAborted();
 			const results: WaitResult[] = [];
@@ -455,7 +496,7 @@ export class Agents {
 				}
 			}
 			returned = true;
-			return { results, pending: unique.filter((agent) => this.pending(agent)).map((agent) => agent.record) };
+			return { results, pending: unique.filter((agent) => this.pending(agent)).map((agent) => agent.record), ...(interrupted && { interrupted }) };
 		} finally {
 			if (blocking) this.markWaiting(-1);
 			if (suspended) await scheduler.resume(this.self.rootId, this.self.id, this.limits.maxConcurrent, signal);
@@ -494,22 +535,38 @@ export class Agents {
 		if (silent) for (const input of [...agent.queue, ...(turn?.inputs ?? [])]) input.silent = true;
 		for (const input of agent.queue.splice(0)) this.end(agent, input, "aborted", "");
 		this.changed();
-		if (turn) {
-			turn.abort.abort();
-			const stopping = (async () => {
-				if (turn.started && agent.session) {
-					agent.session.abortCompaction();
-					agent.session.abortRetry();
-					await agent.session.abort();
-				}
-				await turn.done.promise;
-			})();
-			if (!await settlesBy(stopping, deadline)) {
-				this.finish(agent, turn, { outcome: "aborted", result: "" });
-				throw new Error(`Agent ${label(agent.record, this.ids())} did not stop within the timeout and may still be running.`);
+		if (turn) await this.stop(agent, turn, deadline);
+		return true;
+	}
+
+	/** Ends one input as aborted: withdraws it if queued, or else stops its turn, as `abort` does. */
+	private async cancel(agent: Owned, input: Input): Promise<void> {
+		const index = agent.queue.indexOf(input);
+		if (index !== -1) {
+			agent.queue.splice(index, 1);
+			this.end(agent, input, "aborted", "");
+			this.changed();
+		} else if (agent.turn?.inputs.includes(input)) {
+			await this.stop(agent, agent.turn, Date.now() + SHUTDOWN_TIMEOUT_MS);
+		}
+	}
+
+	/** Stops a turn; one that has not stopped by `deadline` is abandoned: its inputs end as aborted, and this throws. */
+	private async stop(agent: Owned, turn: Turn, deadline: number): Promise<void> {
+		agent.stopped = true;
+		turn.abort.abort();
+		const stopping = (async () => {
+			if (turn.started && agent.session) {
+				agent.session.abortCompaction();
+				agent.session.abortRetry();
+				await agent.session.abort();
 			}
+			await turn.done.promise;
+		})();
+		if (!await settlesBy(stopping, deadline)) {
+			this.finish(agent, turn, { outcome: "aborted", result: "" });
+			throw new Error(`Agent ${label(agent.record, this.ids())} did not stop within the timeout and may still be running.`);
 		}
-		return true;
 	}
 
 	restore(ctx: ExtensionContext): void {
@@ -539,9 +596,7 @@ export class Agents {
 		const deadline = Date.now() + SHUTDOWN_TIMEOUT_MS;
 		const agents = [...this.agents.values()];
 		const aborted = await Promise.allSettled(agents.map((agent) => this.abort(agent, { deadline })));
-		const closed = await Promise.allSettled(agents.map(async (agent) => {
-			const session = agent.session ?? await agent.loading?.catch(() => undefined);
-			if (!session) return;
+		const close = async (agent: Owned, session: AgentSession) => {
 			try {
 				if (!await settlesBy(session.extensionRunner.emit({ type: "session_shutdown", reason: "quit" }), deadline)) {
 					throw new Error(`Agent ${label(agent.record, this.ids())} did not shut down within the timeout and may still be running.`);
@@ -550,6 +605,16 @@ export class Agents {
 				session.dispose();
 				agent.session = undefined;
 			}
+		};
+		const closed = await Promise.allSettled(agents.map(async (agent) => {
+			const loading = agent.loading;
+			if (!agent.session && loading && !await settlesBy(loading, deadline)) {
+				// A Session that loads after the timeout is closed once it does.
+				void loading.then((late) => close(agent, late).catch(() => {}), () => {});
+				throw new Error(`Agent ${label(agent.record, this.ids())} did not shut down within the timeout and may still be running.`);
+			}
+			const session = agent.session ?? await loading?.catch(() => undefined);
+			if (session) await close(agent, session);
 		}));
 		const errors = [...aborted, ...closed].flatMap((result) => result.status === "rejected" ? [result.reason] : []);
 		if (errors.length > 0) throw new Error(errors.map((error) => error instanceof Error ? error.message : String(error)).join("\n"));
@@ -584,6 +649,8 @@ export class Agents {
 
 	/** A steer joins the current turn; other inputs queue. Returns whether the input waits for a slot. */
 	private add(agent: Owned, input: Input, delivery: "followUp" | "steer"): boolean {
+		// While stopped, other senders' messages become writes, so this is the owner's or user's next input.
+		agent.stopped = false;
 		if (delivery !== "steer" || !agent.turn) return this.enqueue(agent, input);
 		this.join(agent, agent.turn, input);
 		return false;
@@ -606,7 +673,7 @@ export class Agents {
 		if (agent.turn || this.closing) return;
 		const head = agent.queue.shift();
 		if (!head) return;
-		const turn: Turn = { inputs: [head], pending: [], abort: new AbortController(), started: false, slot: false, finished: false, done: deferred() };
+		const turn: Turn = { inputs: [head], pending: [], abort: new AbortController(), started: false, slot: false, spent: { cost: 0, tokens: 0, unpriced: false }, finished: false, done: deferred() };
 		agent.turn = turn;
 		void this.runTurn(agent, turn);
 	}
@@ -616,6 +683,7 @@ export class Agents {
 		try {
 			await scheduler.acquireQueued(this.self.rootId, agent.record.id, this.limits.maxConcurrent, turn.abort.signal);
 			turn.slot = true;
+			turn.since = Date.now();
 			const session = await this.load(agent);
 			turn.abort.signal.throwIfAborted();
 			const before = session.getSessionStats().assistantMessages;
@@ -877,6 +945,11 @@ export class Agents {
 			finally { session.dispose(); }
 			throw error;
 		}
+		session.subscribe((event) => {
+			if (event.type !== "message_end" || event.message.role !== "assistant") return;
+			if (agent.turn) addSpend(agent.turn.spent, event.message.usage);
+			addProgramSpend(this.self.id, event.message.usage);
+		});
 		return session;
 	}
 }

package/src/agents/registry.ts

@@ -1,4 +1,5 @@
 /** The Agents loaded in this process, shared across trees: who sees whom, how targets resolve, and how messages are addressed. */
+import type { Usage } from "@earendil-works/pi-ai";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { Agents } from "./agents.ts";
 import { TreeScheduler } from "./scheduler.ts";
@@ -16,12 +17,14 @@ export interface AgentNode {
 	/** The node whose tree this node sees: its root, or the Program its Agents belong to. */
 	scopeId: string;
 	ownerId?: string;
-	/** A Program that owns Agents; no Agent sees it, but the user sees it in the task panel and the Agent viewer. */
+	/** A Program that owns Agents; no Agent sees it, but the user sees it in the task panel and the task viewer. */
 	program?: boolean;
 	/** Whether a Program runs in the background. */
 	background?: boolean;
 	/** When a Program started. */
 	createdAt?: string;
+	/** What the replies of a Program's Agents and the Agents under them have cost since it started. */
+	spent?: Spend;
 	name(): string | undefined;
 	cwd(): string;
 	busy(): boolean;
@@ -29,6 +32,8 @@ export interface AgentNode {
 	agents: Agents;
 	/** Delivers a message to this node; used only for root Agents. */
 	receive(text: string, delivery: Delivery, messageId?: string): void;
+	/** A root Agent's turn was stopped: messages from other Agents become writes until the user's next input. */
+	stopped?: boolean;
 }
 
 export interface Entry {
@@ -86,6 +91,26 @@ export function trackTreeWork(rootId: string): () => void {
 	};
 }
 
+/** What replies cost: dollars, input and output tokens, and whether a reply had no price. */
+export interface Spend {
+	cost: number;
+	tokens: number;
+	unpriced: boolean;
+}
+
+export function addSpend(spend: Spend, usage: Usage): void {
+	spend.cost += usage.cost.total;
+	spend.tokens += usage.input + usage.output;
+	if (usage.cost.total === 0 && usage.input + usage.output + usage.cacheRead + usage.cacheWrite > 0) spend.unpriced = true;
+}
+
+/** Adds a reply of an Agent owned by `ownerId` to the Programs above it. */
+export function addProgramSpend(ownerId: string, usage: Usage): void {
+	for (let node = shared.nodes.get(ownerId); node; node = node.ownerId === undefined ? undefined : shared.nodes.get(node.ownerId)) {
+		if (node.spent) addSpend(node.spent, usage);
+	}
+}
+
 /** The Programs a node runs, oldest first. */
 export function programsOf(node: AgentNode): AgentNode[] {
 	return [...shared.nodes.values()]
@@ -169,7 +194,9 @@ export function treeMetadata(ctx: ExtensionContext): TreeMetadata | undefined {
 export function treeEntries(scopeId: string): Entry[] {
 	const root = shared.nodes.get(scopeId);
 	if (!root) return [];
-	const entries: Entry[] = root.program ? [] : [{
+	// A Program's Agent heads its own scope; it stays owned, so messages to it go through its owner.
+	const owned = root.ownerId === undefined ? undefined : shared.nodes.get(root.ownerId)?.agents.owned().find((agent) => agent.id === root.id);
+	const entries: Entry[] = root.program ? [] : [owned ? { ...owned, ownerId: root.ownerId } : {
 		id: root.id,
 		name: root.name(),
 		cwd: root.cwd(),
@@ -236,7 +263,7 @@ export function messageText(from: { id: string; name?: string }, fromOwner: bool
 
 /**
  * `messageId` marks a message from a root Agent in another process, so it is added once; `user`
- * marks the user's input from the Agent viewer.
+ * marks the user's input from the task viewer.
  */
 export function customMessage(text: string, delivery: Delivery, messageId?: string, user?: boolean) {
 	return { customType: MESSAGE_TYPE, content: text, display: true, details: { delivery, ...(messageId ? { messageId } : {}), ...(user ? { user } : {}) } };

package/src/agents/search.ts

@@ -4,6 +4,8 @@ import { entryLine, MESSAGE_TAG, MESSAGE_TYPE, type Entry } from "./registry.ts"
 interface SearchText {
 	time: number;
 	text: string;
+	/** A user message or an input, not a summary, write, or notification. */
+	request?: boolean;
 }
 
 /** Parsed texts by Session file, reused while the file is unchanged. */
@@ -32,9 +34,10 @@ function sessionTexts(sessionFile: string | undefined): SearchText[] {
 			const text = typeof content === "string"
 				? content
 				: Array.isArray(content) ? content.flatMap((part: any) => part?.type === "text" ? [part.text] : []).join("\n") : "";
-			if (text) texts.push({ time, text });
+			if (text) texts.push({ time, text, request: true });
 		} else if (entry.type === "custom_message" && entry.customType === MESSAGE_TYPE && typeof entry.content === "string") {
-			texts.push({ time, text: entry.content });
+			const request = entry.details?.delivery !== "write" && (entry.content.startsWith(`<${MESSAGE_TAG} `) || entry.details?.user === true);
+			texts.push({ time, text: entry.content, request });
 		}
 	}
 	cache.set(sessionFile, { stamp, texts });
@@ -85,9 +88,23 @@ export function searchEntries(entries: Entry[], query: string | undefined): List
 	return items.sort((left, right) => right.time - left.time).map(({ time: _time, ...item }) => item);
 }
 
+/** An entry with its latest matching excerpt, else its latest request, and its time. */
 export function listLine(item: ListItem, ids: Iterable<string>): string {
 	const line = entryLine(item.entry, ids);
-	return item.match ? `${line}\n  ${formatTime(item.match.time)}  ${item.match.excerpt}` : line;
+	const detail = item.match ?? latestRequest(item.entry.sessionFile);
+	return detail ? `${line}\n  ${formatTime(detail.time)}  ${detail.excerpt}` : line;
+}
+
+function latestRequest(sessionFile: string | undefined): { time: number; excerpt: string } | undefined {
+	const text = sessionTexts(sessionFile).findLast((text) => text.request);
+	if (!text) return undefined;
+	const flat = messageBody(text.text).replace(/\s+/g, " ").trim();
+	return { time: text.time, excerpt: flat.length > 120 ? `${flat.slice(0, 120)}…` : flat };
+}
+
+/** A message's body without its `agent-message` element. */
+function messageBody(content: string): string {
+	return content.startsWith(`<${MESSAGE_TAG} `) ? content.slice(content.indexOf("\n") + 1, content.lastIndexOf("\n")) : content;
 }
 
 /**
@@ -103,7 +120,7 @@ export function latestActivity(sessionFile: string | undefined): string | undefi
 		let entry: Record<string, any>;
 		try { entry = JSON.parse(line); } catch { continue; }
 		if (input === undefined && entry.type === "custom_message" && entry.customType === MESSAGE_TYPE && typeof entry.content === "string") {
-			input = entry.content.startsWith(`<${MESSAGE_TAG} `) ? entry.content.slice(entry.content.indexOf("\n") + 1, entry.content.lastIndexOf("\n")) : entry.content;
+			input = messageBody(entry.content);
 		}
 		if (input !== undefined && entry.type === "message" && entry.message?.role === "assistant" && Array.isArray(entry.message.content)) {
 			activity = replyActivity(entry.message.content) ?? activity;

package/src/agents/tool.ts

@@ -4,9 +4,12 @@ import { Type } from "typebox";
 import { boundBlocks, boundText } from "../output.ts";
 import { rejectFields } from "../params.ts";
 import { renderTextResult, renderToolCall, startDuration, type DurationState } from "../render-call.ts";
+import { agentSession } from "../roots/rpc.ts";
 import type { RootRuntime } from "../roots/runtime.ts";
 import {
+	steerQueued,
 	THINKING_LEVELS,
+	WAIT_INTERRUPTED,
 	type Limits,
 	type WaitOutcome,
 	type WaitResult,
@@ -34,9 +37,10 @@ function resultDetails({ agent, input, history }: WaitResult, result?: string) {
 
 /** Renders wait results; returns the text and the results the caller has now read. */
 function renderWait(outcome: WaitOutcome, ids: string[]): { text: string; read: WaitResult[]; details: Record<string, unknown> } {
-	const { results, pending } = outcome;
-	const pendingLine = pending.length > 0 ? `Still pending: ${pending.map((agent) => label(agent, ids)).join(", ")}` : "";
-	if (results.length === 0) return { text: pendingLine || "No results.", read: [], details: { results: [], pending: pending.map((agent) => agent.id) } };
+	const { results, pending, interrupted } = outcome;
+	const pendingLine = pending.length > 0 ? `Still pending: ${pending.map((agent) => label(agent, ids)).join(", ")}${interrupted ? `\n${WAIT_INTERRUPTED}` : ""}` : "";
+	const flag = interrupted ? { interrupted } : {};
+	if (results.length === 0) return { text: pendingLine || "No results.", read: [], details: { results: [], pending: pending.map((agent) => agent.id), ...flag } };
 	const only = results[0]!;
 	if (results.length === 1 && pending.length === 0 && !only.history && only.input.state === "completed") {
 		const bounded = boundText(only.input.result ?? "", "pi-agents-wait");
@@ -56,7 +60,7 @@ function renderWait(outcome: WaitOutcome, ids: string[]): { text: string; read:
 	const omitted = results.slice(bounded.shown);
 	if (omitted.length > 0) text += `\n\n[Results omitted: ${omitted.map((result) => label(result.agent, ids)).join(", ")}. Use wait with fewer targets.]`;
 	if (pendingLine) text += `\n\n${pendingLine}`;
-	return { text, read, details: { results: details, pending: pending.map((agent) => agent.id), ...bounded.details } };
+	return { text, read, details: { results: details, pending: pending.map((agent) => agent.id), ...flag, ...bounded.details } };
 }
 
 /** Registers the `agent` tool. */
@@ -168,7 +172,8 @@ export function registerAgentTool(
 					const selected = targets?.map((target) => agents.ownedTarget(target));
 					// An empty partial result lets the row show the elapsed time.
 					onUpdate?.({ content: [], details: undefined });
-					const outcome = await agents.wait(selected, params.history ?? 0, params.timeout ?? 30, signal);
+					const session = agentSession(current.sessionManager);
+					const outcome = await agents.wait(selected, params.history ?? 0, params.timeout ?? 30, signal, () => steerQueued(session?.agent));
 					const rendered = renderWait(outcome, ids());
 					agents.markRead(rendered.read);
 					return { content: [{ type: "text", text: rendered.text }], details: rendered.details };

package/src/daemon/client.mjs

@@ -42,13 +42,16 @@ export async function ensureDaemon(paths, { sessionDir, signal }) {
       if (code !== 0) launchError = new Error(`Daemon exited (${code}). See ${paths.daemonLog}`);
     });
     child.unref();
+    // The new daemon sets its socket's mode just after binding; a mode that stays wrong is an error.
+    let modeWait = 0;
     for (;;) {
       signal?.throwIfAborted();
       if (launchError) throw launchError;
       try {
         return await request(paths.daemon, { action: 'status' }, { signal, timeoutMs: 1000 });
       } catch (failure) {
-        if (!['ENOENT', 'ECONNREFUSED', ...RETRY].includes(failure.code)) throw failure;
+        if (failure.code === 'SOCKET_MODE' && ++modeWait > 20) throw failure;
+        if (!['ENOENT', 'ECONNREFUSED', 'SOCKET_MODE', ...RETRY].includes(failure.code)) throw failure;
         // Another daemon holds the lock; it answers once its socket is up.
         if (child.exitCode === 0) break;
       }

package/src/daemon/sessions.mjs

@@ -87,6 +87,13 @@ export async function createSessions(paths, sessionDir) {
       (marks[id] ??= {}).listed = true;
       save();
     },
+    /** Marks a Session's last turn seen, as when the user previews it. */
+    see(id) {
+      const mark = marks[id];
+      if (!mark?.last || (mark.seen ?? 0) >= mark.last.at) return;
+      mark.seen = mark.last.at;
+      save();
+    },
     /** Removes a Session from the workbench list and clears its unseen turn; its file stays. */
     hide(id) {
       const mark = marks[id];

package/src/host/client.mjs

@@ -16,7 +16,7 @@ const ALT_SCREEN = /\x1b\[\?1049([hl])/g;
 // Splits terminal input into key sequences: CSI and SS3 sequences, Alt+key, or a single character.
 const KEYS = /\x1b\[[0-?]*[ -/]*[@-~]|\x1bO[\s\S]|\x1b?[\s\S]/g;
 
-function hostStatus(path) {
+export function hostStatus(path) {
   return new Promise((resolve, reject) => {
     const socket = net.connect(path);
     socket.setTimeout(1000, () => socket.destroy(Object.assign(new Error('Host status timed out'), { code: 'ETIMEDOUT' })));
@@ -27,7 +27,7 @@ function hostStatus(path) {
   });
 }
 
-function alive(pid) {
+export function alive(pid) {
   try { process.kill(pid, 0); return true; }
   catch (error) { return error.code !== 'ESRCH'; }
 }
@@ -50,6 +50,19 @@ export async function listHosts(paths) {
   return hosts;
 }
 
+/**
+ * Running hosts once `found` matches one or no host `starting` remains, waiting at most `timeoutMs`:
+ * a host whose Pi has not reported its Session yet may be starting the Session a caller looks for.
+ */
+export async function settledHosts(paths, found, { starting = host => !host.session, timeoutMs = START_TIMEOUT_MS } = {}) {
+  const deadline = performance.now() + timeoutMs;
+  for (;;) {
+    const hosts = await listHosts(paths);
+    if (hosts.some(found) || !hosts.some(starting) || performance.now() > deadline) return hosts;
+    await delay(100);
+  }
+}
+
 /**
  * Starts a detached host running `pi args` in `cwd` and resolves to its socket once it accepts connections.
  * With `waitForTerminal`, Pi starts when the first terminal attaches.
@@ -88,9 +101,10 @@ export async function startHost(paths, { pi, args, cwd, cols = 120, rows = 40, e
 /**
  * Attaches this process's terminal to a host until the host detaches it or Pi exits.
  * The detach key detaches here, before Pi sees it, so it works whatever Pi shows.
+ * `onAttach` runs once the host has attached the terminal and told Pi.
  * Resolves to { reason: 'detach' | 'takeover' | 'exited' | 'closed', session }.
  */
-export function attach(socketPath, { isDetach, stdin = process.stdin, stdout = process.stdout }) {
+export function attach(socketPath, { isDetach, onAttach, stdin = process.stdin, stdout = process.stdout }) {
   return new Promise((resolve, reject) => {
     const socket = net.connect(socketPath);
     const size = () => ({ cols: stdout.columns, rows: stdout.rows });
@@ -104,7 +118,7 @@ export function attach(socketPath, { isDetach, stdin = process.stdin, stdout = p
       if (at > 0) socket.write(frame(FRAME.data, Buffer.from(keys.slice(0, at).join(''), encoding)));
       socket.write(frame(FRAME.detached));
     };
-    let result, connected = false, altScreen = false;
+    let result, connected = false, altScreen = false, attached = false;
     function finish() {
       stdout.off('resize', onResize);
       stdin.off('data', onInput);
@@ -113,7 +127,8 @@ export function attach(socketPath, { isDetach, stdin = process.stdin, stdout = p
         stdin.pause();
         // An exiting Pi restores the terminal itself.
         // Leaving the alternate screen returns the cursor to the line below the command; otherwise it ends a line.
-        if (result?.reason !== 'exited') stdout.write(altScreen ? `\x1b[?1049l${RESET}` : `${RESET}\r\n`);
+        // Terminals keep a keyboard mode stack per screen, so the reset comes before leaving it.
+        if (result?.reason !== 'exited') stdout.write(altScreen ? `${RESET}\x1b[?1049l` : `${RESET}\r\n`);
       }
       resolve(result ?? { reason: 'closed' });
     }
@@ -129,6 +144,11 @@ export function attach(socketPath, { isDetach, stdin = process.stdin, stdout = p
       if (type === FRAME.data) {
         for (const [, mode] of body.toString('latin1').matchAll(ALT_SCREEN)) altScreen = mode === 'h';
         stdout.write(body);
+        // The host sends the screen only after it has told Pi that a terminal is attached.
+        if (!attached) {
+          attached = true;
+          onAttach?.();
+        }
       }
       else if (type === FRAME.detached) result = { ...json(body) };
       else if (type === FRAME.exited) result = { reason: 'exited', ...json(body) };