@alphacoder-v0/pi-loops 0.22.8 → 0.24.0

package/src/host-control-channel.ts

@@ -1,5 +1,5 @@
 /**
- * A window into the headless host, and a way to interrupt it.
+ * A window into the always-on host, and a way to interrupt it.
  *
  * The answer to "I am away and want to look in" would normally be that its process is still open: `--web` serves
  * a loopback UI and `/web-connect` relays it. pi-loops' host has no chat at all, so it publishes
@@ -14,12 +14,21 @@ import * as fs from "node:fs";
 import * as net from "node:net";
 import * as os from "node:os";
 import * as path from "node:path";
+import { DEAD_AFTER_ATTEMPTS, formatWait, heldTurnFor, stopRow } from "./engine.ts";
+import { snapshotLoopLabel } from "./job-lines.ts";
+import { type LeaseStore, type ProcessProbe, holderAlive, sessionFileName } from "./lease.ts";
+import { conversationLabel, shortSessionId } from "./session-head.ts";
+import { previewRedacted, redact } from "./redact.ts";
+import type { RequestStore, SessionRequest } from "./requests.ts";
+import { formatLocal, stamp } from "./schedule.ts";
+import type { RunRecord, RunRequester } from "./store.ts";
 
-export const HOST_SOCKET = "host.sock";
+/** A new name on purpose: a 0.22 pi-loops talks to `host.sock`, and only to its own kind of host. */
+export const HOST_SOCKET = "host-service.sock";
 const MAX_UNIX_SOCKET_PATH = 100; // 104 on macOS, minus headroom so a rename or a longer socket name cannot cross it
 
 /**
- * Where the host listens. Normally `<dir>/host.sock`, but a unix socket path is capped at 108
+ * Where the host listens. Normally `<dir>/host-service.sock`, but a unix socket path is capped at 108
  * bytes on Linux (104 on macOS) — the whole `sockaddr_un.sun_path` — and a loops directory nested
  * a few levels deep goes past that. `listen()` then fails with EINVAL, the host runs on with no
  * control channel, and `pi-loops host status|abort|stop` report a host that "is not answering"
@@ -36,7 +45,7 @@ export function hostSocketPath(dir: string): string {
 	// A byte count, not a character count: the kernel measures bytes.
 	if (Buffer.byteLength(preferred) <= MAX_UNIX_SOCKET_PATH) return preferred;
 	const digest = createHash("sha256").update(path.resolve(dir)).digest("hex").slice(0, 16);
-	return path.join(os.tmpdir(), `pi-loops-${process.getuid?.() ?? "u"}`, `host-${digest}.sock`);
+	return path.join(os.tmpdir(), `pi-loops-${process.getuid?.() ?? "u"}`, `host-service-${digest}.sock`);
 }
 
 /**
@@ -83,39 +92,366 @@ function ownedSocket(socketPath: string): boolean {
 	}
 }
 
+/** One of the last few runs. `stopped`: a person, a quit or a restart stopped it; `byPerson`: a person did. */
+export interface RecentRun {
+	job: string;
+	at: string;
+	ok: boolean;
+	stopped?: true;
+	byPerson?: true;
+	error?: string;
+	cost?: number;
+}
+
+/** A run record as the snapshot's recent runs carry it: a stopped run is neither ok nor a failure. */
+export function recentRun(r: RunRecord): RecentRun {
+	const stopped = r.stoppedBy === "person" || r.aborted === true;
+	return {
+		job: r.jobName ?? r.jobId,
+		at: r.finishedAt,
+		ok: r.ok,
+		...(stopped ? { stopped: true as const, ...(r.stoppedBy === "person" ? { byPerson: true as const } : {}) } : { error: r.error ? previewRedacted(r.error, 100) : undefined }),
+		cost: r.usage?.cost,
+	};
+}
+
 export interface HostSnapshot {
 	pid: number;
 	host: string;
 	startedAt: string;
+	/** Who started it, whose environment (keys exported in its shell, PATH) it has. */
+	startedBy?: string;
 	model?: string;
-	leader: boolean;
-	runs: Array<{ runId: string; label: string; jobId: string; startedAt: string; promptPreview: string }>;
+	/** PI_LOOPS_VERSION of the host. */
+	version?: string;
+	/**
+	 * The conversations a window holds right now, from the leases: where their plain jobs and results
+	 * go. `page` when the holder is a conversation open in the browser page: its tabs, and how long
+	 * since one of them asked for anything.
+	 */
+	/** `title`: the conversation's name or first message (src/session-head.ts sessionTitle), when its file says. */
+	sessions?: Array<{ sessionId: string; pid: number; mode?: string; page?: { tabs: number; idleMs: number }; title?: string }>;
+	runs: Array<{ runId: string; label: string; jobId: string; startedAt: string; promptPreview: string; sessionFile?: string }>;
 	checks: Array<{ traceId: string; sourceLabel: string; eventLabel: string; startedAt: string; cwd: string }>;
 	jobs: { enabled: number; total: number };
 	rules: { enabled: number; total: number };
 	inboxNew: number;
 	mcp: Array<{ name: string; state: string; lastError?: string }>;
 	/** The last few runs, newest first: a host that has been failing for hours must not look idle. */
-	recent?: Array<{ job: string; at: string; ok: boolean; error?: string; cost?: number }>;
+	recent?: RecentRun[];
 	/** Jobs currently carrying an error, and when anything is next due. */
 	failing?: Array<{ job: string; error: string }>;
 	nextDue?: string;
 	/** Today's spend against the cap, when one is configured. */
 	budget?: { spent: number; cap: number };
+	/** The browser page's address, without its token, once its port is bound. */
+	page?: string;
+	/** Conversations open in the page right now. */
+	pageOpen?: number;
+	/** Why the page is not served yet, as the status line says it after `page: `. */
+	pageWaiting?: string;
+	/** The host's last rule check: windows show it in /triggers status and the panel, since checks run here. */
+	/** The latest rule check of each project. */
+	lastPolls?: Array<{ at: string; cwd: string; outcome: string; traceId: string; sourceLabel: string; eventLabel: string; summary: string }>;
+	/** The latest warnings from the background process, numbered from 1 per process (see `noticesToShow`). */
+	notices?: Notice[];
+	/** Every conversation with rows in `requests/`, read from the files (`requestQueues`). */
+	requests?: RequestQueue[];
+}
+
+/** A conversation's request queue as `pi-loops status` and the status page show it: depth, age, dead rows, who would run them. */
+export interface RequestQueue {
+	sessionId: string;
+	count: number;
+	/** The oldest row's `created_at`. */
+	oldest: string;
+	/** Rows at the dead-letter limit, in the file until a drain buries them. */
+	dead: number;
+	holder: { kind: "terminal"; pid: number } | { kind: "host" } | { kind: "nobody" };
+}
+
+/**
+ * Each session's queue, from the files alone, so the CLI can say it while pi-loops is down. A
+ * session with nothing queued is left out. Nothing of a row's text is read into it.
+ */
+export function requestQueues(store: Pick<RequestStore, "sessions" | "list">, leases: Pick<LeaseStore, "read">, probe?: ProcessProbe): RequestQueue[] {
+	return store
+		.sessions()
+		.sort()
+		.flatMap((sessionId): RequestQueue[] => {
+			const rows = store.list(sessionId);
+			if (!rows.length) return [];
+			const holder = leases.read(sessionId)?.holder;
+			const live = holder && holderAlive(holder, probe) ? holder : undefined;
+			return [
+				{
+					sessionId,
+					count: rows.length,
+					oldest: rows.map((r) => r.created_at).sort((a, b) => Date.parse(a) - Date.parse(b))[0],
+					dead: rows.filter((r) => r.attempts >= DEAD_AFTER_ATTEMPTS).length,
+					holder: !live ? { kind: "nobody" } : live.kind === "host" ? { kind: "host" } : { kind: "terminal", pid: live.pid },
+				},
+			];
+		});
+}
+
+/**
+ * What waits for each conversation, in plain words: a total, then one line per conversation. None
+ * when nothing waits. `where: false` leaves out where each is open, for a view that says it already.
+ */
+export function requestLines(queues: readonly RequestQueue[], now: number, opts: { where?: boolean } = {}): string[] {
+	if (!queues.length) return [];
+	const total = queues.reduce((n, q) => n + q.count, 0);
+	const dead = queues.reduce((n, q) => n + q.dead, 0);
+	const undelivered = (n: number) => `${n} could not be delivered`;
+	const where = (q: RequestQueue) => (q.holder.kind === "terminal" ? `open in pid ${line(q.holder.pid)}` : q.holder.kind === "host" ? "in the background" : "closed");
+	const head = `  ${total} message${total === 1 ? "" : "s"} waiting for ${queues.length} conversation${queues.length === 1 ? "" : "s"}${dead ? `, ${undelivered(dead)}` : ""}`;
+	return [head, ...queues.map((q) => `    ${shortSessionId(line(q.sessionId))}: ${line(q.count)} waiting · oldest ${formatWait(now - Date.parse(q.oldest))}${q.dead ? ` · ${undelivered(q.dead)}` : ""}${opts.where === false ? "" : ` · ${where(q)}`}`)];
+}
+
+/** A warning from the background process: a job disabled or parked, a state write that failed, the budget reached. */
+export interface Notice {
+	seq: number;
+	at: string;
+	text: string;
+	/** The project it is about; none for the machine's (the budget, the store). */
+	cwd?: string;
+}
+
+/** How many warnings the background process keeps, and how long a repeat of one stays quiet. */
+export const NOTICES_KEPT = 50;
+const NOTICE_REPEAT_MS = 60 * 60 * 1000;
+/** On a window's first look, warnings this recent are still news (one parked at startup, say). */
+const NOTICE_RECENT_MS = 10 * 60 * 1000;
+
+/**
+ * Keep a warning for windows to fetch, redacted, and return the next sequence number. The same text
+ * within the hour is kept once: a store that cannot be read says so on every tick.
+ */
+export function keepNotice(kept: Notice[], seq: number, text: string, cwd: string | undefined, now: number): number {
+	const clean = redact(text);
+	if (kept.some((n) => n.text === clean && n.cwd === cwd && now - Date.parse(n.at) < NOTICE_REPEAT_MS)) return seq;
+	kept.push({ seq: seq + 1, at: stamp(now), text: clean, ...(cwd ? { cwd } : {}) });
+	while (kept.length > NOTICES_KEPT) kept.shift();
+	return seq + 1;
+}
+
+/**
+ * Which of the background process's warnings a window shows: its own project's and the machine's,
+ * each once. On its first look, only the recent ones: a window opened after something was said
+ * still hears it, and one opened a day later is not handed a backlog.
+ */
+export function noticesToShow(notices: Notice[], seen: { pid: number; seq: number } | undefined, pid: number, cwd: string, sameProject: (a: string, b: string) => boolean, now: number = Date.now()): { show: Notice[]; seen: { pid: number; seq: number } } {
+	const last = notices.reduce((max, n) => Math.max(max, n.seq), 0);
+	const mine = (n: Notice) => !n.cwd || sameProject(n.cwd, cwd);
+	if (!seen) return { show: notices.filter((n) => mine(n) && now - Date.parse(n.at) < NOTICE_RECENT_MS), seen: { pid, seq: last } };
+	const after = seen.pid === pid ? seen.seq : 0;
+	return { show: notices.filter((n) => n.seq > after && mine(n)), seen: { pid, seq: Math.max(after, last) } };
+}
+
+/**
+ * `stop` carries why: `restart` and `upgrade` wait for the page's turns to finish (src/host.ts), a
+ * plain `stop` does not; one without a reason is a plain stop, as every sender before 0.24 sends it.
+ * `upgrade` comes from a window running a newer pi-loops: the host leaves, and that window starts the
+ * new code. `ring` is the doorbell: a producer wrote a row for a conversation it does not hold
+ * (`request:<session>`), or gave a conversation back (`lease:<session>`), and the host delivers
+ * without waiting for its tick. It is answered before the delivery runs, and ignored when lost.
+ */
+export type HostRequest =
+	| { op: "status" }
+	| { op: "abort"; runId?: string; traceId?: string }
+	| { op: "stop"; reason?: StopReason }
+	| { op: "upgrade" }
+	| { op: "run"; jobId: string; requestedBy?: RunRequester }
+	| { op: "ring"; note: string }
+	| PageOpenRequest
+	| { op: "page-key"; sessionId: string }
+	| { op: "pair" };
+/**
+ * Open a conversation in the browser page: `sessionId` and `sessionFile` for one that exists, neither
+ * for a new one in `cwd`. `piArgs` go to that conversation's pi when it is started for this.
+ */
+export type PageOpenRequest = { op: "page-open"; cwd: string; sessionId?: string; sessionFile?: string; piArgs: string[]; openFile?: boolean; copyKey?: boolean };
+/** How long the one-use key `pi-loops` prints for another browser (`copyKey`) works: long enough to copy it there. */
+export const COPY_KEY_MS = 10 * 60_000;
+/**
+ * `ran` is `true`, or why the loop did not start (the same refusal `/cron run` prints). `page-open`
+ * answers `url` (the conversation's page, no token), `sessionId` and `openKey` (one load, a minute),
+ * and with `openFile` the path of a 0600 file that sends a browser to the keyed page; with `copyKey`
+ * a second one-use key, good for `COPY_KEY_MS`, for the address the launcher prints;
+ * `reused` when the page already had it open, and `ignoredArgs`, the pi arguments that open pi never
+ * saw. `page-key` answers `openKey`. `pair` answers `code` and `addresses`, the page's addresses on
+ * the machine's networks (none while it listens on loopback only).
+ */
+/** Why the process is asked to leave. */
+export type StopReason = "stop" | "restart" | "upgrade";
+
+/**
+ * What a second stop or upgrade is told while the first one is still leaving: it is not started
+ * again. A plain stop that arrives while a restart or an upgrade waits ends that wait instead.
+ */
+export const ALREADY_LEAVING = "already leaving";
+
+export type HostResponse =
+	| { ok: true; note?: typeof ALREADY_LEAVING; snapshot?: HostSnapshot; aborted?: boolean; stopping?: "run" | "row"; ran?: true | string; url?: string; sessionId?: string; openKey?: string; openFile?: string; copyKey?: string; reused?: true; ignoredArgs?: string[]; code?: string; addresses?: string[] }
+	| { ok: false; error: string };
+/** What the page answers to `page-open`: everything but `ok`, or why not. */
+export type PageOpened = { url: string; sessionId: string; openKey: string; openFile?: string; copyKey?: string; reused?: true; ignoredArgs?: string[] } | { error: string };
+
+/**
+ * What `page-open` says to `--api-key`. A page's pi arguments are kept in `pages/` so the
+ * conversation reopens the same way after an idle stop or a restart; a key there is a secret on disk.
+ */
+export const API_KEY_REFUSAL = "--api-key would be kept on disk with the page's pi arguments; set the provider's environment variable (for example ANTHROPIC_API_KEY or OPENAI_API_KEY) before pi-loops starts, or log in with pi's /login in a terminal";
+
+/** pi arguments that would make a page's pi something other than a window: never passed through. */
+const NOT_A_WINDOW = ["--mode", "-p", "--print", "--session-dir"];
+
+/**
+ * What `page-open` refuses before anything is started, or undefined. The request came over the
+ * socket: `cwd` has to be a directory that exists, named absolutely, and every pi argument a string.
+ */
+export function pageOpenRefusal(req: Partial<PageOpenRequest>): string | undefined {
+	if (typeof req.cwd !== "string" || !path.isAbsolute(req.cwd) || !isDirectory(req.cwd)) return "page-open needs cwd, an absolute path to a directory";
+	if (!Array.isArray(req.piArgs) || !req.piArgs.every((a) => typeof a === "string")) return "page-open needs piArgs, a list of strings";
+	for (const arg of req.piArgs) {
+		if (arg === "--api-key" || arg.startsWith("--api-key=")) return API_KEY_REFUSAL;
+		const flag = NOT_A_WINDOW.find((f) => arg === f || arg.startsWith(`${f}=`));
+		if (flag) return `${flag} would make the child something other than a window`;
+	}
+	if (req.sessionId !== undefined && typeof req.sessionId !== "string") return "page-open: sessionId must be a string";
+	if (req.sessionFile !== undefined && (typeof req.sessionFile !== "string" || !path.isAbsolute(req.sessionFile))) return "page-open: sessionFile must be an absolute path";
+	if (req.openFile !== undefined && typeof req.openFile !== "boolean") return "page-open: openFile must be true or false";
+	if (req.copyKey !== undefined && typeof req.copyKey !== "boolean") return "page-open: copyKey must be true or false";
+	return undefined;
+}
+
+function isDirectory(p: string): boolean {
+	try {
+		return fs.statSync(p).isDirectory();
+	} catch {
+		return false; // not there, or not ours to look at: not a directory to start pi in
+	}
 }
 
-export type HostRequest = { op: "status" } | { op: "abort"; runId?: string; traceId?: string } | { op: "stop" };
-export type HostResponse = { ok: true; snapshot?: HostSnapshot; aborted?: boolean } | { ok: false; error: string };
+/** What a stop asked of pi-loops in the background came to: the run is being stopped, its conversation's queue has the stop, or nothing was running. */
+export type StopAnswer = { stopping: "run" | "row" } | { finished: true };
+
+export interface StopDeps {
+	/** The runs in flight here (`scheduler.runningRuns()`). */
+	runs: () => ReadonlyArray<{ runId: string }>;
+	/** The closed conversation this process holds for `runId`'s turn, when the run is a held turn. */
+	heldSession: (runId: string) => string | undefined;
+	/** Abort a loop run as a person asked (`scheduler.abortRun`, STOPPED_BY_PERSON). */
+	abortRun: (runId: string) => boolean;
+	/** Append a stop row for `runId` to the conversation's queue and ring it. */
+	stopThroughRow: (sessionId: string, runId: string) => void;
+}
+
+/**
+ * The one stop decision, for the control socket's `abort` and the page's Stop this run. A held turn
+ * in a closed conversation is stopped through a stop row in its queue, which is what leaves the
+ * `request` audit row saying so; a loop run is aborted at once. `prefix` lets a typed id be the
+ * shortened one the status lines show; the page sends whole ids only.
+ */
+export function stopRun(ref: string, deps: StopDeps, opts: { prefix: boolean }): StopAnswer {
+	const runs = deps.runs();
+	const match = runs.find((r) => r.runId === ref) ?? (opts.prefix && ref ? runs.find((r) => r.runId.startsWith(ref)) : undefined);
+	if (!match) return { finished: true };
+	const sessionId = deps.heldSession(match.runId);
+	if (sessionId) {
+		deps.stopThroughRow(sessionId, match.runId);
+		return { stopping: "row" };
+	}
+	return deps.abortRun(match.runId) ? { stopping: "run" } : { finished: true };
+}
+
+/** What `stopRunFrom` needs of the background process: its scheduler, its held turns, its leases and its queue. */
+export interface StopHost {
+	scheduler: { runningRuns(): ReadonlyArray<{ runId: string }>; abortRun(runId: string, from: "page" | "cli"): boolean; noteStopFrom(runId: string, from: "page" | "cli"): void };
+	heldTurn(sessionId: string): { runId: string } | undefined;
+	ring(sessionId: string): void;
+	leases: () => Parameters<typeof heldTurnFor>[0];
+	append: (row: SessionRequest) => void;
+	createdBy: () => SessionRequest["created_by"];
+}
+
+/**
+ * The one stop the background process offers, wired: the socket's `abort` (`source` "cli", a typed
+ * prefix allowed) and the page's Stop this run and the waiting page's Stop it (`source` "person",
+ * the whole id). A held turn gets a stop row in its conversation's queue, rung at once, and its
+ * holder's drain aborts the turn; the record says where the stop came from either way.
+ */
+export function stopRunFrom(source: "cli" | "person", prefix: boolean, host: StopHost): (runId: string) => StopAnswer {
+	const from = source === "person" ? "page" : "cli";
+	return (runId) =>
+		stopRun(runId, {
+			runs: () => host.scheduler.runningRuns(),
+			heldSession: (id) => {
+				const turn = heldTurnFor(host.leases(), id);
+				return turn?.kind === "turn" && turn.runId === id && host.heldTurn(turn.sessionId)?.runId === id ? turn.sessionId : undefined;
+			},
+			abortRun: (id) => host.scheduler.abortRun(id, from),
+			stopThroughRow: (sessionId, id) => {
+				host.scheduler.noteStopFrom(id, from);
+				host.append(stopRow(sessionId, { id }, source, host.createdBy()));
+				host.ring(sessionId);
+			},
+		}, { prefix });
+}
 
 export interface HostChannelHandlers {
 	status: () => HostSnapshot;
 	abortRun: (runId: string) => boolean;
+	/** When given, `abort` with a run id goes through here instead of `abortRun` (src/host.ts). */
+	stopRun?: (runId: string) => StopAnswer;
 	abortCheck: (traceId: string) => boolean;
-	stop: () => void;
+	/**
+	 * Called once per leave, and once more with `stop` when a plain stop cuts short the wait of a
+	 * restart or an upgrade. Every stop or upgrade after the first is answered `ALREADY_LEAVING`.
+	 */
+	stop: (reason: StopReason) => void;
+	/** `requestedBy` is the conversation a person asked from; absent from an older window, and then the run is as before. */
+	run: (jobId: string, requestedBy?: RunRequester) => Promise<true | string>;
+	/** Deliver what is queued for the session, now; returns at once. */
+	ring: (sessionId: string) => void;
+	/** Open a conversation in the browser page; the request has passed `pageOpenRefusal`. */
+	pageOpen: (req: Omit<PageOpenRequest, "op">) => Promise<PageOpened>;
+	/** A fresh one-shot key for a conversation's page, or why there is none. */
+	pageKey: (sessionId: string) => { openKey: string } | { error: string };
+	/** A pairing code for another device and the addresses it can open, or why there is none. */
+	pair: () => { code: string; addresses: string[] } | { error: string };
 }
 
+/** What a doorbell note may say: which store changed, and for which session. */
+export type RingNote = { kind: "request" | "lease"; sessionId: string };
+const MAX_RING_NOTE = 200;
+
+/**
+ * A note arrives over the socket, or is a file name a watcher saw: the session id in it becomes a
+ * path under the loops directory, so anything `sessionFileName` refuses is refused here, and the
+ * note never reaches the stores.
+ */
+export function parseRingNote(note: unknown): RingNote | undefined {
+	if (typeof note !== "string" || note.length > MAX_RING_NOTE) return undefined;
+	const m = /^(request|lease):(.+)$/s.exec(note);
+	if (!m) return undefined;
+	try {
+		return { kind: m[1] as RingNote["kind"], sessionId: sessionFileName(m[2]) };
+	} catch {
+		return undefined; // not a session id: a path, an empty name
+	}
+}
+
+/**
+ * How long a connection may stay open, by op. `page-open` may wait 15 s for an orphaned pi to stop
+ * and as long again for the new one to name its conversation; nothing else waits on pi.
+ */
+export const CONTROL_TIMEOUT_MS = { "page-open": 30_000, other: 10_000 } as const;
+export type ControlTimeouts = { [op in keyof typeof CONTROL_TIMEOUT_MS]: number };
+
 /** One newline-delimited JSON request per connection, answered and closed. */
-export function serveHostChannel(dir: string, handlers: HostChannelHandlers, log?: (message: string) => void): net.Server {
+export function serveHostChannel(dir: string, handlers: HostChannelHandlers, log?: (message: string) => void, timeouts: ControlTimeouts = CONTROL_TIMEOUT_MS): net.Server {
 	const socketPath = hostSocketPath(dir);
 	if (!prepareSocketDir(socketPath, log)) return net.createServer();
 	// The directory holds prompts, findings, transcripts and now a control socket: it is the
@@ -136,6 +472,10 @@ export function serveHostChannel(dir: string, handlers: HostChannelHandlers, log
 		log?.(`control channel: ${err?.message ?? err}`);
 		return net.createServer(); // an unbound server: the host runs, `host status` falls back to the pid
 	}
+	// One leave per process: a window that finds an older version keeps asking it to make way every
+	// tick, and none of those may start the wait for the page's turns again. A person's plain stop
+	// may still end that wait, once: it must not sit out two minutes and then meet the CLI's SIGKILL.
+	let leaving: StopReason | undefined;
 	const server = net.createServer((socket) => {
 		socket.setEncoding("utf8");
 		let buf = "";
@@ -146,24 +486,66 @@ export function serveHostChannel(dir: string, handlers: HostChannelHandlers, log
 				if (buf.length > 4096) socket.destroy();
 				return;
 			}
-			let response: HostResponse;
-			try {
-				const req = JSON.parse(buf.slice(0, nl)) as HostRequest;
-				if (req.op === "status") response = { ok: true, snapshot: handlers.status() };
-				else if (req.op === "abort") response = { ok: true, aborted: req.runId ? handlers.abortRun(req.runId) : req.traceId ? handlers.abortCheck(req.traceId) : false };
-				else if (req.op === "stop") {
-					response = { ok: true };
-					setTimeout(() => handlers.stop(), 50).unref?.();
-				} else response = { ok: false, error: `unknown op ${JSON.stringify((req as any).op)}` };
-			} catch (err: any) {
-				response = { ok: false, error: err?.message ?? String(err) };
-			}
-			socket.end(`${JSON.stringify(response)}\n`, () => socket.destroy());
+			const raw = buf.slice(0, nl);
 			buf = "";
 			socket.removeAllListeners("data"); // one request per connection, never replayed
+			const answer = async (): Promise<HostResponse> => {
+				const req = JSON.parse(raw) as HostRequest;
+				if (req.op === "page-open") socket.setTimeout(timeouts["page-open"]);
+				if (req.op === "status") return { ok: true, snapshot: handlers.status() };
+				if (req.op === "abort") {
+					if (req.runId && handlers.stopRun) {
+						const answer = handlers.stopRun(req.runId);
+						return "stopping" in answer ? { ok: true, aborted: true, stopping: answer.stopping } : { ok: true, aborted: false };
+					}
+					return { ok: true, aborted: req.runId ? handlers.abortRun(req.runId) : req.traceId ? handlers.abortCheck(req.traceId) : false };
+				}
+				if (req.op === "run") {
+					if (typeof req.jobId !== "string") return { ok: false, error: "run needs a jobId" };
+					const by: unknown = req.requestedBy;
+					if (by === undefined) return { ok: true, ran: await handlers.run(req.jobId) };
+					const sessionId = by && typeof by === "object" ? (by as { sessionId?: unknown }).sessionId : undefined;
+					if (typeof sessionId !== "string" || !sessionId) return { ok: false, error: "run's requestedBy needs a sessionId" };
+					return { ok: true, ran: await handlers.run(req.jobId, { sessionId }) };
+				}
+				if (req.op === "ring") {
+					const note = parseRingNote(req.note);
+					if (!note) return { ok: false, error: "ring needs a note of the form request:<session> or lease:<session>" };
+					handlers.ring(note.sessionId);
+					return { ok: true };
+				}
+				if (req.op === "page-open") {
+					const refused = pageOpenRefusal(req);
+					if (refused) return { ok: false, error: refused };
+					const opened = await handlers.pageOpen({ cwd: req.cwd, sessionId: req.sessionId, sessionFile: req.sessionFile, piArgs: req.piArgs, ...(req.openFile ? { openFile: true } : {}), ...(req.copyKey ? { copyKey: true } : {}) });
+					return "error" in opened ? { ok: false, error: opened.error } : { ok: true, ...opened };
+				}
+				if (req.op === "page-key") {
+					if (typeof req.sessionId !== "string") return { ok: false, error: "page-key needs a sessionId" };
+					const key = handlers.pageKey(req.sessionId);
+					return "error" in key ? { ok: false, error: key.error } : { ok: true, openKey: key.openKey };
+				}
+				if (req.op === "pair") {
+					const paired = handlers.pair();
+					return "error" in paired ? { ok: false, error: paired.error } : { ok: true, code: paired.code, addresses: paired.addresses };
+				}
+				if (req.op === "stop" || req.op === "upgrade") {
+					const reason: StopReason = req.op === "upgrade" ? "upgrade" : req.reason === "restart" || req.reason === "upgrade" ? req.reason : "stop";
+					const first = !leaving;
+					if (!first && !(reason === "stop" && leaving !== "stop")) return { ok: true, note: ALREADY_LEAVING };
+					leaving = reason;
+					setTimeout(() => handlers.stop(reason), 50).unref?.();
+					return first ? { ok: true } : { ok: true, note: ALREADY_LEAVING };
+				}
+				return { ok: false, error: `unknown op ${JSON.stringify((req as any).op)}` };
+			};
+			answer()
+				.catch((err: any): HostResponse => ({ ok: false, error: err?.message ?? String(err) }))
+				.then((response) => socket.end(`${JSON.stringify(response)}\n`, () => socket.destroy()))
+				.catch(() => socket.destroy());
 		});
 		socket.on("error", () => socket.destroy());
-		socket.setTimeout(10_000, () => socket.destroy());
+		socket.setTimeout(timeouts.other, () => socket.destroy());
 	});
 	server.on("error", (err: any) => log?.(`control channel: ${err?.message ?? err}`));
 	server.listen(socketPath, () => {
@@ -188,32 +570,46 @@ export function askHost(dir: string, request: HostRequest, timeoutMs = 2000): Pr
 		if (!ownedSocket(socketPath)) return resolve(undefined);
 		const socket = net.createConnection(socketPath);
 		let buf = "";
+		let timer: NodeJS.Timeout | undefined;
 		const done = (value: HostResponse | undefined) => {
+			clearTimeout(timer);
 			socket.destroy();
 			resolve(value);
 		};
-		const timer = setTimeout(() => done(undefined), timeoutMs);
-		timer.unref?.();
+		timer = setTimeout(() => done(undefined), timeoutMs);
+		// `pi-loops` has nothing else to wait on during a page-open: with the timer unref'd, Node would
+		// exit mid-wait with "unsettled top-level await". A window's asks must not hold pi open.
+		if (request.op !== "page-open") timer.unref?.();
 		socket.setEncoding("utf8");
 		socket.on("connect", () => socket.write(`${JSON.stringify(request)}\n`));
 		socket.on("data", (chunk) => {
 			buf += chunk;
 			const nl = buf.indexOf("\n");
 			if (nl < 0) return;
-			clearTimeout(timer);
 			try {
 				done(JSON.parse(buf.slice(0, nl)) as HostResponse);
 			} catch {
 				done(undefined);
 			}
 		});
-		socket.on("error", () => {
-			clearTimeout(timer);
-			done(undefined);
-		});
+		socket.on("error", () => done(undefined));
+		// Closed with no answer (it gave up on the request): no answer, now, not at our own timeout.
+		socket.on("close", () => done(undefined));
 	});
 }
 
+/**
+ * Ring the host's doorbell, if one is listening: the row is in the file already, so the answer and
+ * every failure are ignored, and the caller never waits longer than `askHost`'s timeout. The tick
+ * is the floor for a ring that is lost.
+ */
+export function ringHost(dir: string, note: string): Promise<void> {
+	return askHost(dir, { op: "ring", note }).then(
+		() => undefined,
+		() => undefined,
+	);
+}
+
 /**
  * Everything here arrived over a socket and is printed to a terminal. Even with the socket
  * ownership-checked, a snapshot is data from another process: escape sequences would repaint the
@@ -222,22 +618,41 @@ export function askHost(dir: string, request: HostRequest, timeoutMs = 2000): Pr
 function line(text: unknown): string {
 	return String(text ?? "").replace(/[\u0000-\u001f\u007f-\u009f]/g, " ");
 }
+/** A stamp in the one local format every terminal line uses; the text itself when it is not a time. */
+function localTime(text: unknown): string {
+	const ms = Date.parse(String(text ?? ""));
+	return Number.isNaN(ms) ? line(text) : formatLocal(ms);
+}
 function money(n: unknown, digits: number): string {
 	return Number.isFinite(Number(n)) ? Number(n).toFixed(digits) : "?";
 }
 
-/** The lines `/cron host` shows for a live host. */
-export function renderHostSnapshot(s: HostSnapshot): string[] {
+export function openConversations(n: number): string {
+	return n === 0 ? "no conversation open" : n === 1 ? "1 open conversation" : `${n} open conversations`;
+}
+
+/** The lines `/cron host` shows for a live host. `now` is for the ages of the queued requests. */
+export function renderHostSnapshot(s: HostSnapshot, now = Date.now()): string[] {
 	const lines = [
-		`  pid ${line(s.pid)} on ${line(s.host)}, started ${line(s.startedAt)}${s.model ? `, model ${line(s.model)}` : ""}`,
-		`  ${s.leader ? "owns the clock" : "standby"} · ${line(s.jobs?.enabled)}/${line(s.jobs?.total)} loop(s), ${line(s.rules?.enabled)}/${line(s.rules?.total)} rule(s) enabled · inbox: ${line(s.inboxNew)} new`,
+		`  pid ${line(s.pid)} on ${line(s.host)}, started ${localTime(s.startedAt)}${s.model ? `, model ${line(s.model)}` : ""}`,
+		`  ${s.version ? `pi-loops ${line(s.version)} · ` : ""}${line(s.jobs?.enabled)}/${line(s.jobs?.total)} loops, ${line(s.rules?.enabled)}/${line(s.rules?.total)} rules enabled · inbox: ${line(s.inboxNew)} new`,
+		...(s.startedBy ? [`  started by ${line(s.startedBy)}`] : []),
 	];
-	for (const r of s.runs ?? []) lines.push(`  running ${line(r.label)} (${line(r.runId).slice(0, 12)}) since ${line(r.startedAt)}: ${line(r.promptPreview)}`);
+	for (const h of s.sessions ?? []) {
+		const which = line(conversationLabel(String(h.sessionId ?? ""), typeof h.title === "string" ? h.title : undefined));
+		if (h.page) lines.push(`  conversation ${which} open in the page (pid ${line(h.pid)}, ${line(h.page.tabs)} ${Number(h.page.tabs) === 1 ? "tab" : "tabs"}, idle ${formatWait(Number(h.page.idleMs))})`);
+		else lines.push(`  conversation ${which} open in pid ${line(h.pid)}${h.mode ? ` (${line(h.mode)})` : ""}`);
+	}
+	for (const r of s.runs ?? []) lines.push(`  running ${line(r.label)} (${line(r.runId).slice(0, 12)}) since ${localTime(r.startedAt)}: ${line(r.promptPreview)}`);
 	for (const c of s.checks ?? []) lines.push(`  checking ${line(c.sourceLabel)}/${line(c.eventLabel)} (${line(c.traceId).slice(0, 8)}) in ${line(c.cwd)}`);
 	for (const m of s.mcp ?? []) lines.push(`  mcp ${line(m.name)}: ${line(m.state)}${m.lastError ? ` — ${line(m.lastError)}` : ""}`);
-	if (!s.runs?.length && !s.checks?.length) lines.push(`  nothing running right now${s.nextDue ? ` · next due ${line(s.nextDue)}` : ""}`);
+	if (!s.runs?.length && !s.checks?.length) lines.push(`  nothing running right now${s.nextDue ? ` · next due ${localTime(s.nextDue)}` : ""}`);
 	if (s.budget && Number(s.budget.cap) > 0) lines.push(`  spent today: $${money(s.budget.spent, 2)} of $${money(s.budget.cap, 2)}${Number(s.budget.spent) >= Number(s.budget.cap) ? " — dispatching is paused" : ""}`);
-	for (const f of s.failing ?? []) lines.push(`  ! ${line(f.job)}: ${line(f.error)}`);
-	for (const r of s.recent ?? []) lines.push(`  ${r.ok ? "ok  " : "FAIL"} ${line(r.at)}  ${line(r.job)}${r.cost ? ` · $${money(r.cost, 3)}` : ""}${r.error ? ` — ${line(r.error)}` : ""}`);
+	for (const f of s.failing ?? []) lines.push(`  ! ${line(snapshotLoopLabel(String(f.job ?? "")))}: ${line(f.error)}`);
+	if (s.page) lines.push(`  page: ${line(s.page)}${s.pageOpen === undefined ? "" : ` · ${openConversations(Number(s.pageOpen) || 0)}`}`);
+	else if (s.pageWaiting) lines.push(`  page: ${line(s.pageWaiting)}`);
+	// A stopped run is neither ok nor a failure.
+	for (const r of s.recent ?? []) lines.push(`  ${r.ok ? "ok  " : r.stopped ? "stop" : "FAIL"} ${localTime(r.at)}  ${line(snapshotLoopLabel(String(r.job ?? "")))}${r.cost ? ` · $${money(r.cost, 3)}` : ""}${r.byPerson ? " — stopped by you" : r.error ? ` — ${line(r.error)}` : ""}`);
+	lines.push(...requestLines(s.requests ?? [], now));
 	return lines;
 }