pi-straw-boss 0.7.2 → 0.8.0

package/src/dialogs.ts

@@ -1,7 +1,8 @@
 import { randomUUID } from "node:crypto";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { type Pending, type Relayed, SEVERAL } from "./ask.ts";
-import { type Ack, type AnswerMessage, type Bridge, type Dialogs, guiNamespace, type LocalHub, REGISTER, type ToHub } from "./bridge.ts";
+import { type Ack, type AnswerMessage, type Bridge, type Dialogs, type FormMessage, type FormReply, guiNamespace, type LocalHub, REGISTER, type ToHub } from "./bridge.ts";
+import { createCaps, type Doc, docsOf, type Fields, fieldsOk, type FormResult, type Shelf } from "./documents.ts";
 import type { Session } from "./herdr.ts";
 import { canonical } from "./history.ts";
 import type { Ref } from "./net.ts";
@@ -12,9 +13,10 @@ import { checkProbe, type Editor } from "./probe.ts";
 // bridge's pane, decides whether the page may answer it, and carries an answer to that bridge. A list counts only from the session intercom
 // places on that pane, for the unit whose session file it names. The page may answer a dialog only when it is the session's one open dialog,
 // with no answer on its way, belonging to the file's one open call (never a secret_drop), with a digest that matches its content.
-// The same binding, for every bridge whether it holds a dialog or not, tells where to ask what a session's editor would submit (`probe`).
+// The same binding, for every bridge whether it holds a dialog or not, tells where to ask what a session's editor would submit (`probe`), and
+// gives the unit the documents its bridge lists, each by a capability (documents.ts), and carries a form answer for one to that bridge.
 
-const ACK_MS = 5000, PROBE_MS = 1000, KEEP_MS = 600_000, KEEP = 256, MAX_TEXT = 8192, MAX_NOTE = 2048, MAX_ALL = 12_288;
+const ACK_MS = 5000, PROBE_MS = 1000, FORM_MS = 5000, KEEP_MS = 600_000, KEEP = 256, MAX_TEXT = 8192, MAX_NOTE = 2048, MAX_ALL = 12_288;
 export const ANSWER_ID = /^[A-Za-z0-9_-]{16,64}$/, CONTROL = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/;
 interface Channel { snapshot(): { connected: boolean; owner?: { sessionId: string; epoch: string } }; publish(payload: unknown, options?: { audience?: "owner" | "capable"; ownerOnly?: boolean }): void }
 type Event = { type: string; fromSessionId?: string; sessionId?: string; owner?: { sessionId: string; epoch: string }; payload?: unknown };
@@ -25,6 +27,11 @@ export type Hub = ReturnType<typeof createHub>;
 
 const str = (v: unknown): v is string => typeof v === "string";
 const opt = (v: unknown) => v === undefined || str(v);
+/** Waits up to `ms` for the reply filed under `k`; undefined when none came (or the hub stopped). */
+const wait = <T>(map: Map<string, (x?: T) => void>, k: string, ms: number) => new Promise<T | undefined>((resolve) => {
+	const timer = setTimeout(() => settle(), ms), settle = (x?: T) => (clearTimeout(timer), map.delete(k), resolve(x));
+	map.set(k, settle);
+});
 /** A relayed dialog, checked so a malformed message cannot break the net reading. */
 const valid = (d: Dialog) => str(d?.owner) && str(d.id) && d.id.length <= 64 && /^[0-9a-f]{64}$/.test(String(d.digest)) && opt(d.toolCallId) &&
 	(d.select === undefined || (str(d.select?.title) && Array.isArray(d.select.choices) && d.select.choices.every((c) => str(c?.label) && opt(c.note)) && opt(d.select.copy))) &&
@@ -57,6 +64,8 @@ export function createHub(pi: ExtensionAPI, me: string, local: Bridge) {
 	let channel: Channel | undefined, epoch: string | undefined, active = false, change = () => {};
 	let bound = new Map<string, { from: string; b: Dialogs }>(), targets = new Map<string, Target>(), reach = new Map<string, { from: string; bridgeId: string }>();
 	const bridges = new Map<string, Dialogs>(), waiting = new Map<string, (ack?: Ack) => void>(), done = new Map<string, { key: string; at: number; sent: Sent }>(), probes = new Map<string, (e?: Editor) => void>();
+	const caps = createCaps(), forms = new Map<string, (r?: FormReply) => void>();
+	let shelves = new Map<string, Shelf>();
 	const owner = () => channel?.snapshot().owner?.sessionId === me;
 	const sync = () => {
 		local.sync();
@@ -65,9 +74,11 @@ export function createHub(pi: ExtensionAPI, me: string, local: Bridge) {
 	const receive = (from: string, msg: ToHub) => {
 		if (!active || msg?.version !== 1 || !str(msg.bridgeId)) return;
 		const closed = msg.type === "dialogs" && Array.isArray(msg.closed) && msg.closed.length <= 16 && msg.closed.every((c) => str(c?.id) && str(c.by) && opt(c.answerId));
-		if (closed && str(msg.pane) && (msg.file === null || str(msg.file)) && Array.isArray(msg.dialogs) && msg.dialogs.every(valid)) (bridges.set(from, msg), change());
+		const docs = msg.type === "dialogs" && (msg.documents === undefined ? [] : docsOf({ version: 1, documents: msg.documents })); // documents out of shape go alone, as if cut
+		if (closed && str(msg.pane) && (msg.file === null || str(msg.file)) && Array.isArray(msg.dialogs) && msg.dialogs.every(valid)) (bridges.set(from, docs ? { ...msg, documents: docs } : { ...msg, documents: [], docsCut: true }), change());
 		if (msg.type === "ack") waiting.get([from, msg.bridgeId, msg.id, msg.answerId].join("\n"))?.(msg);
 		if (msg.type === "probe-result") probes.get([from, msg.bridgeId, msg.probeId].join("\n"))?.(checkProbe({ ...msg }));
+		if (msg.type === "form-result" && typeof msg.accepted === "boolean" && opt(msg.reason) && (msg.reason?.length ?? 0) <= 512) forms.get([from, msg.bridgeId, msg.id, msg.answerId].join("\n"))?.(msg);
 	};
 	const onEvent = (e: Event) => {
 		if (e.type === "owner" && e.owner?.sessionId === me && e.owner.epoch !== epoch && (epoch = e.owner.epoch) && active) sync();
@@ -90,7 +101,7 @@ export function createHub(pi: ExtensionAPI, me: string, local: Bridge) {
 	const hub: LocalHub & {
 		readonly running: boolean; readonly me: string; start(onChange: () => void): void; stop(): void; relayed(sessions: Session[], refs: Map<string, Ref>): Relayed; target(key: string): Target | undefined;
 		replay(answerId: string, key: string): Sent | undefined; ended(key: string, dialog: string, answerId: string): Sent | undefined; send(key: string, t: Target, a: Omit<AnswerMessage, "version" | "type" | "to">): Promise<Sent>;
-		probe(key: string): Promise<Editor | undefined>;
+		probe(key: string): Promise<Editor | undefined>; doc(cap: string): { key: string; doc: Doc } | undefined; form(cap: string, answerId: string, fields: Fields): Promise<FormResult | undefined>;
 	} = {
 		receive,
 		get running() { return active; },
@@ -108,19 +119,23 @@ export function createHub(pi: ExtensionAPI, me: string, local: Bridge) {
 		},
 		stop() {
 			active = false;
-			[bridges, bound, targets, reach].forEach((m) => m.clear());
-			[...waiting.values(), ...probes.values()].forEach((w) => w());
+			[bridges, bound, targets, reach, shelves].forEach((m) => m.clear());
+			caps.clear(); // a capability lives as long as its server
+			[...waiting.values(), ...probes.values(), ...forms.values()].forEach((w) => w());
 		},
 		/** Binds each relayed list to a unit, from this net reading's sessions and registry. */
 		relayed(sessions, refs) {
 			[bound, targets, reach] = [new Map(), new Map(), new Map()];
+			const shelved: { key: string; from: string; bridgeId: string; docs: Doc[] }[] = [], cut = new Set<string>();
 			for (const [from, b] of bridges) {
 				const file = sessions.find((s) => s.id === from)?.herdrLocation?.paneId === b.pane ? canonical(b.file ?? undefined) : undefined;
 				const ref = file && [...refs.values()].find((r) => r.pane === b.pane && r.file === file);
-				if (ref) reach.set(ref.key, { from, bridgeId: b.bridgeId });
+				if (ref) (reach.set(ref.key, { from, bridgeId: b.bridgeId }), shelved.push({ key: ref.key, from, bridgeId: b.bridgeId, docs: b.documents ?? [] }), b.docsCut && cut.add(ref.key));
 				if (ref && (b.dialogs.length || b.closed.length)) bound.set(ref.key, { from, b });
 			}
-			return { dialogsOf: (key) => bound.get(key)?.b.dialogs, merge };
+			const cards = caps.bind(shelved, new Set([...bridges].flatMap(([from, b]) => (b.documents ?? []).map((d) => `${from}\n${b.bridgeId}\n${d.id}`))));
+			shelves = new Map([...cards].flatMap(([key, docs]): [string, Shelf][] => (docs.length || cut.has(key) ? [[key, { ...(docs.length ? { docs } : {}), ...(cut.has(key) ? { docsCut: true as const } : {}) }]] : [])));
+			return { dialogsOf: (key) => bound.get(key)?.b.dialogs, merge, docsOf: (key) => shelves.get(key) };
 		},
 		/** How a dialog that is no longer open here ended: `accepted` for the answer that won it, else `stale` with who closed it. */
 		ended(key, dialog, answerId) {
@@ -135,10 +150,7 @@ export function createHub(pi: ExtensionAPI, me: string, local: Bridge) {
 		/** Publishes the answer to its bridge (or calls this session's) and waits up to 5 s for the bridge's ack. */
 		async send(key, t, a) {
 			const msg: AnswerMessage = { version: 1, type: "answer", to: t.bridgeId, ...a }, k = [t.from, t.bridgeId, a.id, a.answerId].join("\n");
-			const ack = new Promise<Ack | undefined>((resolve) => {
-				const timer = setTimeout(() => settle(), ACK_MS), settle = (x?: Ack) => (clearTimeout(timer), waiting.delete(k), resolve(x));
-				waiting.set(k, settle);
-			});
+			const ack = wait(waiting, k, ACK_MS);
 			try {
 				if (t.from === me) local.deliver(msg, (x) => receive(me, x));
 				else if (owner()) channel!.publish(msg, { audience: "capable", ownerOnly: true });
@@ -159,11 +171,7 @@ export function createHub(pi: ExtensionAPI, me: string, local: Bridge) {
 			const t = reach.get(key);
 			if (!t || !active) return undefined;
 			if (t.from === me) return checkProbe({ ...local.probe() });
-			const probeId = randomUUID(), k = [t.from, t.bridgeId, probeId].join("\n");
-			const got = new Promise<Editor | undefined>((resolve) => {
-				const timer = setTimeout(() => settle(), PROBE_MS), settle = (e?: Editor) => (clearTimeout(timer), probes.delete(k), resolve(e));
-				probes.set(k, settle);
-			});
+			const probeId = randomUUID(), k = [t.from, t.bridgeId, probeId].join("\n"), got = wait(probes, k, PROBE_MS);
 			try {
 				if (!owner()) throw new Error("not the owner");
 				channel!.publish({ version: 1, type: "probe", to: t.bridgeId, probeId }, { audience: "capable", ownerOnly: true });
@@ -172,6 +180,27 @@ export function createHub(pi: ExtensionAPI, me: string, local: Bridge) {
 			}
 			return got;
 		},
+		/** A listed document by its capability, as its bridge lists it now (a list that changed since the reading counts, a bridge that left does not). */
+		doc(cap) {
+			const at = caps.find(cap), b = at && bridges.get(at.from), doc = at && b?.bridgeId === at.bridgeId ? b.documents?.find((d) => d.id === at.id) : undefined;
+			return doc && { key: at!.key, doc };
+		},
+		/** A form answer for the document `cap`, to its bridge (or this session's), waiting up to 5 s for the owner's result. One answerId is sent once (docs.ts spends its nonce first). */
+		async form(cap, answerId, fields) {
+			const at = caps.find(cap), k = at && [at.from, at.bridgeId, at.id, answerId].join("\n");
+			if (!ANSWER_ID.test(answerId) || !fieldsOk(fields)) return { accepted: false, reason: "invalid" };
+			if (!at || !k || !active || !hub.doc(cap)) return { accepted: false, reason: "closed" };
+			const msg: FormMessage = { version: 1, type: "form", to: at.bridgeId, id: at.id, answerId, fields }, got = wait(forms, k, FORM_MS);
+			try {
+				if (at.from === me) local.form(msg, (r) => receive(me, r));
+				else if (owner()) channel!.publish(msg, { audience: "capable", ownerOnly: true });
+				else throw new Error("not the owner");
+			} catch {
+				forms.get(k)?.(); // unreachable: not confirmed
+			}
+			const r = await got;
+			return r && { accepted: r.accepted, ...(str(r.reason) ? { reason: r.reason } : {}) };
+		},
 	};
 	return hub;
 }

package/src/docs.ts

@@ -0,0 +1,103 @@
+import { randomBytes } from "node:crypto";
+import { createReadStream, readFileSync, realpathSync, statSync } from "node:fs";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { pipeline } from "node:stream";
+import { dirname, extname, resolve, sep } from "node:path";
+import type { Hub } from "./dialogs.ts";
+import type { Fields } from "./documents.ts";
+
+// Serving the documents a session shows (documents.ts) to the page, by capability: the hub's current binding is the allow list, and paths never
+// come from the browser. GET /<t>/doc/<cap>/ is an HTML document, rewritten so its pi-answer forms submit here; GET /<t>/doc/<cap>/<path> an
+// image, stylesheet, or font under its own directory; GET /<t>/doc/<cap>/answer/<nonce>?<fields> takes one form answer to the owner;
+// GET /<t>/api/doc/<cap> a text document as JSON, which the page renders. Every /doc/ response carries a CSP `sandbox` without scripts, so a
+// document (or an SVG opened on its own) runs no script and has an opaque origin: it cannot read the API or the cookie. The sources name the
+// server's origin, because WebKit does not match 'self' in a sandboxed document; Chrome loads fonts there in CORS mode with Origin: null,
+// so fonts allow any origin. Answers are never logged. A remote request reaches /doc/ with the Tailscale identity and the capability only:
+// Chrome withholds the SameSite=Strict cookie from a sandboxed frame's requests (remote.ts).
+
+const SIBLING: Record<string, string> = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif", ".webp": "image/webp", ".svg": "image/svg+xml", ".css": "text/css; charset=utf-8", ".woff": "font/woff", ".woff2": "font/woff2", ".ttf": "font/ttf", ".otf": "font/otf" };
+const MAX_DOC = 2 * 1024 * 1024, MAX_FILE = 8 * 1024 * 1024, NONCE_MS = 30 * 60_000, MAX_NONCES = 256, MAX_QUERY = 16 * 1024, MAX_ANSWER = 12 * 1024, CAP = /^[0-9a-f]{32}$/;
+const CONTROL = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/; // tab, newline, and CR (a textarea's line break) stay, as Chawan sends them
+export const docCsp = (origin: string) => `sandbox allow-forms allow-popups allow-popups-to-escape-sandbox; default-src 'none'; img-src ${origin} data:; style-src ${origin} 'unsafe-inline'; font-src ${origin} data:; form-action ${origin}; base-uri 'none'; frame-ancestors ${origin}`;
+const escape = (s: string) => s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+
+/** The document as served: other <base> tags dropped, links opening in a new tab, each `cgi-bin:pi-answer` form posting (GET) to this page's nonce,
+ *  and what could undo that dropped: a referrer policy of its own (the URL holds the token) and the buttons' formaction, formmethod, formtarget.
+ *  Regexes over HTML text are a best effort (an entity or a quoted `>` gets past them); the sandbox and the CSP are what hold. */
+export function rewrite(html: string, nonce: string) {
+	const forms = html.replace(/<base\b[^>]*>|<meta\b[^>]*\bname\s*=\s*["']?referrer\b[^>]*>/gi, "").replace(/<[a-z][^>]*>/gi, (tag) => tag.replace(/\s(?:referrerpolicy|formaction|formmethod|formtarget)\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]*)/gi, "")).replace(/<form\b[^>]*>/gi, (tag) => (/\saction\s*=\s*(?:"\s*cgi-bin:pi-answer\s*"|'\s*cgi-bin:pi-answer\s*'|cgi-bin:pi-answer(?=[\s>/]))/i.test(tag) ? tag.replace(/\s(?:action|method|target)\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]*)/gi, "").replace(/^<form/i, `<form action="answer/${nonce}" method="get" target="_self"`) : tag));
+	const at = /<head\b[^>]*>/i.exec(forms) ?? /<html\b[^>]*>/i.exec(forms) ?? /<!doctype[^>]*>/i.exec(forms), cut = at ? at.index + at[0].length : 0;
+	return `${forms.slice(0, cut)}<base target="_blank">${forms.slice(cut)}`;
+}
+/** A form's fields as the answer route takes them: at most 64, the query at most 16 KB and the answer 12 KB, no control characters. */
+export function fieldsOf(query: string): Fields | string {
+	if (query.length > MAX_QUERY) return "The answers are longer than 16 KB.";
+	const fields = [...new URLSearchParams(query)];
+	if (fields.length > 64) return "The form has more than 64 fields.";
+	if (fields.some(([name, value]) => CONTROL.test(name) || CONTROL.test(value))) return "The answers hold control characters.";
+	return Buffer.byteLength(JSON.stringify(fields)) > MAX_ANSWER ? "The answers are longer than 12 KB together." : fields;
+}
+
+export function createDocs(hub: Pick<Hub, "doc" | "form">, name: (key: string) => string) {
+	const nonces = new Map<string, { cap: string; until: number }>();
+	/** A file the document may use: the listed one itself, or one under its directory, as its real path, within `max` bytes. */
+	const file = (path: string, max: number, under?: string) => {
+		try {
+			const real = realpathSync(path), root = under && realpathSync(under);
+			return (root ? real.startsWith(root + sep) : real === path) && statSync(real).isFile() && statSync(real).size <= max ? real : undefined;
+		} catch {
+			return undefined;
+		}
+	};
+	return {
+		/** `parts` is the path after doc/; `origin` the page's own origin, which the document's policy names. */
+		async serve(req: IncomingMessage, res: ServerResponse, [cap = "", ...rest]: string[], origin: string) {
+			const h = req.headers, base = { "cache-control": "no-store", "referrer-policy": "no-referrer", "x-content-type-options": "nosniff", "content-security-policy": docCsp(origin) };
+			const page = (status: number, title: string, text: string) => res.writeHead(status, { ...base, "content-type": "text/html; charset=utf-8" }).end(`<!doctype html><meta charset="utf-8"><title>${escape(title)}</title><style>body{margin:0;padding:24px;background:#0b1222;color:#dbe6ff;font:15px/1.5 system-ui,sans-serif}h1{margin:0 0 6px;font-size:17px;color:#ffd27a}p{margin:0;color:#8b99ba}</style><h1>${escape(title)}</h1><p>${escape(text)}</p>`);
+			const found = req.method === "GET" && CAP.test(cap) ? hub.doc(cap) : undefined;
+			if (!found) return void page(404, "Not found", "This document is not open in the net any more.");
+			const { doc, key } = found, dest = h["sec-fetch-dest"], site = h["sec-fetch-site"];
+			if (!rest.length) return void res.writeHead(308, { ...base, location: `${cap}/` }).end();
+			if (rest.length === 1 && rest[0] === "") {
+				// The document itself: a navigation of the page's frame or tab (Sec-Fetch-*, when the browser sends them), never another site's.
+				const real = doc.kind === "html" ? file(doc.path, MAX_DOC) : undefined;
+				if (!real || (dest && dest !== "iframe" && dest !== "document")) return void page(404, "Not found", "This document cannot be shown here.");
+				// From the document's own frame (WebKit's Back after an answer, a link to itself), never with a fresh nonce: a form is never sent twice.
+				if (site && site !== "same-origin" && site !== "none") return void page(409, "Reload the document", "Use Reload on its tile, or open it again, to see it and send its form again.");
+				const nonce = randomBytes(16).toString("hex"), now = Date.now();
+				for (const [n, v] of nonces) if (v.until < now || nonces.size >= MAX_NONCES) nonces.delete(n);
+				nonces.set(nonce, { cap, until: now + NONCE_MS });
+				// Back and Forward show this copy again (its nonce is spent once sent); a reload fetches a fresh one.
+				return void res.writeHead(200, { ...base, "cache-control": "private, no-cache", "content-type": "text/html; charset=utf-8" }).end(rewrite(readFileSync(real, "utf8"), nonce));
+			}
+			if (rest[0] === "answer" && rest.length === 2) {
+				const n = nonces.get(rest[1]!), url = req.url ?? "", query = url.includes("?") ? url.slice(url.indexOf("?") + 1) : "";
+				if ((h["sec-fetch-mode"] && h["sec-fetch-mode"] !== "navigate") || (dest && dest !== "iframe" && dest !== "document")) return void page(403, "Not sent", "A form answer comes only from the document's own form.");
+				nonces.delete(rest[1]!); // one answer per served page, whatever happens next
+				if (!n || n.cap !== cap) return void page(409, "Already sent", "This page's answer was already sent. Reload the document to send again.");
+				if (n.until < Date.now()) return void page(409, "Expired", "This page was served more than 30 minutes ago. Reload the document to send again.");
+				const fields = fieldsOf(query);
+				if (typeof fields === "string") return void page(400, "Not sent", fields);
+				const r = await hub.form(cap, rest[1]!, fields);
+				if (!r) return void page(504, "Not confirmed", "Check the terminal: the session did not confirm the answer, so it may or may not have arrived.");
+				if (r.accepted) return void page(200, `Sent to ${name(key)}`, "The agent has your answers.");
+				return void page(409, "Not sent", r.reason === "closed" ? "The document is no longer open in its session." : r.reason === "empty" ? "The form has no fields to send." : `The session refused it (${r.reason ?? "no reason"}).`);
+			}
+			let rel: string;
+			try {
+				rel = rest.map(decodeURIComponent).join("/");
+			} catch {
+				return void page(404, "Not found", "No such file.");
+			}
+			const type = SIBLING[extname(rel).toLowerCase()], real = doc.kind === "html" && type && !rel.includes("\0") ? file(resolve(dirname(doc.path), rel), MAX_FILE, dirname(doc.path)) : undefined;
+			if (!real) return void page(404, "Not found", "No such file beside the document.");
+			res.writeHead(200, { ...base, "content-type": type!, ...(type!.startsWith("font/") ? { "access-control-allow-origin": "*" } : {}) });
+			pipeline(createReadStream(real), res, () => {}); // a file that went meanwhile, or a reader that left, closes both ends
+		},
+		/** GET /<t>/api/doc/<cap>: a text document for the page's renderer. */
+		text(cap: string): { status: number; body: unknown } {
+			const found = CAP.test(cap) ? hub.doc(cap) : undefined, real = found?.doc.kind === "text" ? file(found.doc.path, MAX_DOC) : undefined;
+			return real ? { status: 200, body: { kind: "text", display: found!.doc.display, revision: found!.doc.revision, text: readFileSync(real, "utf8") } } : { status: 404, body: { error: "not_found", reason: "This document is not open in the net any more." } };
+		},
+	};
+}

package/src/documents.ts

@@ -0,0 +1,76 @@
+import { randomBytes } from "node:crypto";
+import type { Bus } from "./owners.ts";
+
+// Document contract v1 (pi-herdr-doc-review ≥ 0.4.0, its README's "Browser viewers"): the package that shows a session's documents (its
+// owner) publishes the full list on pi's event bus at every change and delivers form answers itself, exactly as a Chawan submission. The
+// bridge (bridge.ts) relays the list with its dialogs; the hub (dialogs.ts) binds it to the unit with the dialog binding rule and gives each
+// document a capability, 128 random bits per server; the page gets the capability and never a path; the server serves by it (docs.ts).
+
+export const LIST = "doc-review:documents", REQUEST = "doc-review:documents-request", FORM = "doc-review:form", RESULT = "doc-review:form-result";
+const MAX_DOCS = 32, FORM_MS = 4000;
+export const MAX_FIELDS = 64;
+export interface Doc { id: string; path: string; kind: "html" | "text"; display: string; reason: string; revision: number; onScreen: boolean }
+/** A document as the page sees it: its capability instead of its path and owner id. */
+export interface DocCard { cap: string; display: string; kind: "html" | "text"; reason: string; revision: number; onScreen: boolean }
+/** A unit's documents in the snapshot; `docsCut` when its list was too long to relay (they stay in the terminal). */
+export interface Shelf { docs?: DocCard[]; docsCut?: true }
+export interface FormResult { accepted: boolean; reason?: string }
+export type Fields = [string, string][];
+
+const str = (v: unknown, max: number): v is string => typeof v === "string" && v.length <= max;
+/** One entry; its display and reason are cut to 1024 and 2048 characters (show_doc's reason has no limit), anything else out of shape refuses it. */
+const docOf = (d: Record<string, unknown> | undefined): Doc | undefined => {
+	if (!str(d?.id, 64) || !str(d.path, 4096) || !d.path.startsWith("/") || (d.kind !== "html" && d.kind !== "text") || typeof d.display !== "string" || typeof d.reason !== "string" || !Number.isSafeInteger(d.revision) || (d.revision as number) < 1 || typeof d.onScreen !== "boolean") return;
+	return { id: d.id, path: d.path, kind: d.kind, display: d.display.slice(0, 1024), reason: d.reason.slice(0, 2048), revision: d.revision as number, onScreen: d.onScreen };
+};
+/** A contract-v1 list, or undefined (another version or shape: a relay never guesses at one). Ids are unique. */
+export function docsOf(raw: unknown): Doc[] | undefined {
+	const p = raw as { version?: unknown; documents?: unknown };
+	if (p?.version !== 1 || !Array.isArray(p.documents) || p.documents.length > MAX_DOCS) return;
+	const docs = p.documents.map(docOf);
+	return docs.every(Boolean) && new Set(docs.map((d) => d!.id)).size === docs.length ? (docs as Doc[]) : undefined;
+}
+export const fieldsOk = (f: unknown): f is Fields => Array.isArray(f) && f.length <= MAX_FIELDS && f.every((x) => Array.isArray(x) && x.length === 2 && x.every((s) => typeof s === "string"));
+
+/** The owner's list as it changes. A v1 list out of shape counts as none, so an older list never stays; another version is ignored. A viewer that starts late asks for the list once. */
+export function listenDocs(bus: Bus, list: (docs: Doc[]) => void): () => void {
+	const off = bus.on(LIST, (raw) => (raw as { version?: unknown })?.version === 1 && list(docsOf(raw) ?? []));
+	bus.emit(REQUEST, { version: 1 });
+	return off;
+}
+/** Hands one form answer to the owner and reports its result once (nothing when the owner stays silent for 4 s). */
+export function submitForm(bus: Bus, id: string, answerId: string, fields: Fields, done: (r: FormResult) => void) {
+	let finished = false;
+	const finish = (r?: FormResult) => (finished || ((finished = true), off(), clearTimeout(timer), r && done(r)));
+	const off = bus.on(RESULT, (raw) => {
+		const r = raw as { version?: unknown; id?: unknown; answerId?: unknown; accepted?: unknown; reason?: unknown };
+		if (r?.version === 1 && r.id === id && r.answerId === answerId && typeof r.accepted === "boolean") finish({ accepted: r.accepted, ...(str(r.reason, 512) ? { reason: r.reason } : {}) });
+	});
+	const timer = setTimeout(finish, FORM_MS);
+	timer.unref?.();
+	bus.emit(FORM, { version: 1, id, answerId, fields });
+}
+
+/** The hub's capabilities: one per (session, bridge, document) while its bridge lists that document, new for every server (`clear`). A list cut
+ *  for size lists nothing meanwhile, so its documents get new capabilities when they fit again. */
+export function createCaps() {
+	let caps = new Map<string, string>(), held = new Map<string, { key: string; from: string; bridgeId: string; id: string }>();
+	return {
+		/** One reading: each bound unit's lists by key; `listed` holds `from\nbridgeId\nid` of every relayed document, and a capability not in it goes. */
+		bind(units: { key: string; from: string; bridgeId: string; docs: Doc[] }[], listed: Set<string>): Map<string, DocCard[]> {
+			const cards = new Map<string, DocCard[]>();
+			for (const k of caps.keys()) if (!listed.has(k)) caps.delete(k);
+			held = new Map();
+			for (const { key, from, bridgeId, docs } of units)
+				cards.set(key, docs.map(({ id, kind, display, reason, revision, onScreen }) => {
+					const k = `${from}\n${bridgeId}\n${id}`, cap = caps.get(k) ?? randomBytes(16).toString("hex");
+					caps.set(k, cap);
+					held.set(cap, { key, from, bridgeId, id });
+					return { cap, display, kind, reason, revision, onScreen };
+				}));
+			return cards;
+		},
+		find: (cap: string) => held.get(cap),
+		clear: () => ((caps = new Map()), (held = new Map())),
+	};
+}

package/src/gui.ts

@@ -9,6 +9,7 @@ import { waitsForSecret } from "./ask.ts";
 import { createControl, type Reply } from "./control.ts";
 import type { HerdrCall } from "./herdr.ts";
 import type { Hub } from "./dialogs.ts";
+import { createDocs } from "./docs.ts";
 import { canonical, readers } from "./history.ts";
 import { createMirrors } from "./mirror.ts";
 import type { Found, Net, Ref } from "./net.ts";
@@ -32,7 +33,8 @@ const HEADERS = {
 	"cache-control": "no-store",
 	"referrer-policy": "no-referrer",
 	"x-content-type-options": "nosniff",
-	"content-security-policy": "default-src 'none'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self'; base-uri 'self'; frame-ancestors 'none'",
+	"cross-origin-opener-policy": "same-origin", // a page a document's link opens cannot steer this tab
+	"content-security-policy": "default-src 'none'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self'; frame-src 'self'; base-uri 'self'; frame-ancestors 'none'",
 };
 
 export interface Gui { url: string; port: number; token: string; csrf: string; access: Access; stop(): Promise<void> }
@@ -52,7 +54,7 @@ export async function startGui({ read, net, call, hub, dir = BUNDLE, port = 0, t
 	// Turning remote access off ends the streams of remote pages; their next request finds the cookie void.
 	const clients = new Map<ServerResponse, Watch | undefined>(), remotes = new Set<ServerResponse>(), access = createAccess(token, () => remotes.forEach((c) => c.end()));
 	const pair = (code = access.pair(), host = access.remote?.host, url = `https://${host}/${token}/pair/${code}`) => (code && host ? { url, rows: qr(url).map((row) => row.map(Number).join("")) } : undefined);
-	const mirrors = createMirrors({ call, lookup: (key) => net?.lookup(key), secret: waitsForSecret, canonical });
+	const mirrors = createMirrors({ call, lookup: (key) => net?.lookup(key), secret: waitsForSecret, canonical }), docs = hub && createDocs(hub, (key) => net?.lookup(key)?.name ?? key);
 	const control = createControl({ lookup: (key) => net?.lookup(key), call, csrf, canonical, pair, mirrors, secret: waitsForSecret, answers: hub && { replay: hub.replay, ended: hub.ended, send: hub.send, probe: hub.probe, target: async (key) => (await tick(), hub.target(key)) } });
 	let last: string | undefined, problem: string | undefined, inflight: Promise<void> | undefined;
 	let poll: ReturnType<typeof setInterval> | undefined, beat: ReturnType<typeof setInterval> | undefined;
@@ -110,6 +112,7 @@ export async function startGui({ read, net, call, hub, dir = BUNDLE, port = 0, t
 		if ("status" in who) return void (who.status === 403 ? fail(403) : res.writeHead(401, { ...HEADERS, "content-type": "text/plain" }).end("This device is not paired: scan a new QR code from /boss gui remote."));
 		// A pairing code was just exchanged: the cookie is set, and the page reloads itself, so the cookie also rides on a same-site navigation.
 		if ("cookie" in who) return void res.writeHead(200, { ...HEADERS, "content-type": TYPES[".html"], "set-cookie": cookieFor(token, who.cookie) }).end(`<!doctype html><meta http-equiv="refresh" content="0;url=/${token}/"><p>Paired. Opening the straw net…</p>`);
+		if (path[0] === "doc") return void (docs ? docs.serve(req, res, path.slice(1), who.origin).catch(() => res.destroy()) : fail(404)); // the documents sessions show (docs.ts)
 		if (path[0] === "api") {
 			let parts: string[];
 			try {
@@ -118,7 +121,7 @@ export async function startGui({ read, net, call, hub, dir = BUNDLE, port = 0, t
 				return void fail(404);
 			}
 			if (parts[0] === "sessions" || parts[0] === "remote") return void control(req, who.origin, parts).then(answer, () => answer({ status: 500, body: { error: "internal", reason: "The request could not be handled." } }));
-			if (req.method === "GET") return void api(files, parts, url.searchParams).then(answer, () => fail(404));
+			if (req.method === "GET") return void (parts[0] === "doc" && docs ? answer(docs.text(parts[1] ?? "")) : api(files, parts, url.searchParams).then(answer, () => fail(404)));
 		}
 		if (req.method !== "GET") return void fail(403);
 		// The page loads its assets and the stream relative to its own URL, so that URL must end with a slash.

package/src/index.ts

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -10,6 +11,7 @@ import { createHub, type Hub } from "./dialogs.ts";
 import { answers, type Gui, openBrowser, readRecord, sharedGui, startGui, urlOf } from "./gui.ts";
 import { netSource } from "./net.ts";
 import { clearOrder, markKids, netTokens } from "./order.ts";
+import { orphans } from "./orphan.ts";
 import { copyText, pairingKeys, showLines } from "./pairing.ts";
 import { type Run, switchRemote, tailscale } from "./remote.ts";
 import { ensureTower, headOf, towerModel, herdrApi, type HerdrApi, herdrCall, type HerdrCall, herdrRun, type HerdrRun, isSub, type Pane, panes, parentOf, place, type Place, report, type Session, type Sleep, waitFor, workspaces, type Workspace } from "./herdr.ts";
@@ -22,6 +24,8 @@ const NAMESPACE = /^[a-z0-9][a-z0-9._/-]{0,63}$/;
 const ENTRY = "straw-boss";
 const PROMPTS = ["main", "tower", "member", "member-no-main"];
 const REFRESH_MS = 4 * 60_000;
+const KID_MARK_MS = [3_000, 15_000];
+const NUDGE_MS = 15_000;
 const CLAIM_MS = 5000;
 const CONNECT_MS = 15_000;
 const SEND_MS = 30_000;
@@ -38,7 +42,7 @@ interface Saved { tower?: boolean }
 type Role = "tower" | "main" | "member";
 type Scope = "tab" | "workspace" | "towers" | "all";
 type Member = ReturnType<typeof netMembers>[number];
-export interface Deps { run?: HerdrRun; api?: HerdrApi; call?: HerdrCall; tailscale?: Run; copy?: (text: string) => Promise<void>; env?: NodeJS.ProcessEnv; sleep?: Sleep; promptDir?: string; bundle?: string; openUrl?: (url: string) => Promise<void>; stateDir?: string; autoTower?: boolean }
+export interface Deps { run?: HerdrRun; api?: HerdrApi; call?: HerdrCall; tailscale?: Run; copy?: (text: string) => Promise<void>; env?: NodeJS.ProcessEnv; sleep?: Sleep; promptDir?: string; bundle?: string; openUrl?: (url: string) => Promise<void>; stateDir?: string; autoTower?: boolean; nudgeMs?: number }
 
 /** Live sessions whose pane carries an `sb_role` token: the sessions that joined the net, and towers. */
 function netMembers(sessions: Session[], ps: Pane[]) {
@@ -50,7 +54,7 @@ function netMembers(sessions: Session[], ps: Pane[]) {
 }
 const nameOf = (s?: Session) => (s ? (s.name ?? s.id) : "");
 
-export function createStrawBoss({ run = herdrRun, api = herdrApi(), call = herdrCall(), tailscale: ts = tailscale, copy = copyText, env = process.env, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), promptDir = fileURLToPath(new URL("../prompts", import.meta.url)), bundle, openUrl = openBrowser, stateDir, autoTower = true }: Deps = {}) {
+export function createStrawBoss({ run = herdrRun, api = herdrApi(), call = herdrCall(), tailscale: ts = tailscale, copy = copyText, env = process.env, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), promptDir = fileURLToPath(new URL("../prompts", import.meta.url)), bundle, openUrl = openBrowser, stateDir, autoTower = true, nudgeMs = NUDGE_MS }: Deps = {}) {
 	return function strawBoss(pi: ExtensionAPI): void {
 		// Outside Herdr there is no tab to coordinate. Every session in Herdr relays its dialogs to the GUI (bridge.ts), subagents too: they ask
 		// questions as well. A pi-herdr-agents worker never joins: its parent represents it.
@@ -61,6 +65,7 @@ export function createStrawBoss({ run = herdrRun, api = herdrApi(), call = herdr
 		if (env.PI_SUBAGENT_ID) return;
 		let isTower = env.STRAW_BOSS_ROLE === "tower";
 		let joined = false, isMain = false, holdsTower = false, requests = 0;
+		const nonce = randomUUID().slice(0, 8);
 		// The tab's live main agent as of the last refresh, and the main this session pinned as owner before the broker echoes it back.
 		let mainId: string | undefined, pinned: string | undefined, joining: Promise<void> | undefined;
 		// Why this session cannot join: it sits in a sub workspace, or Herdr could not say whether it does.
@@ -71,6 +76,8 @@ export function createStrawBoss({ run = herdrRun, api = herdrApi(), call = herdr
 		let queue: Promise<void> = Promise.resolve();
 		// This session's intercom name, which the subagents it launched show as their launcher, and the subagent panes it has marked.
 		let ownName = "", kids = new Set<string>();
+		// Watches for subagents this session launched whose result can no longer reach it (orphan.ts).
+		let nudges: ReturnType<typeof orphans> | undefined, nudgeTimer: ReturnType<typeof setInterval> | undefined;
 		const me = () => env.PI_INTERCOM_SESSION_ID ?? "";
 		const role = (): Role | undefined => {
 			if (isTower) return "tower";
@@ -219,7 +226,8 @@ export function createStrawBoss({ run = herdrRun, api = herdrApi(), call = herdr
 		};
 		const send = (to: string, message: string) =>
 			new Promise<SendResult>((resolve) => {
-				const requestId = `straw-boss-${me()}-${++requests}`;
+				// pi-intercom keeps a message id per sender session and refuses it again with other content, and a restarted pi keeps its session id: the id carries this process's own nonce.
+				const requestId = `straw-boss-${me()}-${nonce}-${++requests}`;
 				const done = (result: SendResult) => {
 					off();
 					clearTimeout(timeout);
@@ -356,6 +364,11 @@ export function createStrawBoss({ run = herdrRun, api = herdrApi(), call = herdr
 			prompts = Object.fromEntries(PROMPTS.map((name) => [name, readFileSync(join(promptDir, `${name}.md`), "utf8").trim()]));
 			saved = Object.assign({}, ...ctx.sessionManager.getBranch().flatMap((e) => (e.type === "custom" && e.customType === ENTRY ? [e.data] : [])));
 			isTower ||= Boolean(saved.tower);
+			const log = ctx.sessionManager;
+			clearInterval(nudgeTimer);
+			nudges?.stop();
+			nudges = orphans({ run, file: () => log.getSessionFile(), entries: () => log.getEntries(), sessions, send, type: ENTRY, remember: (key) => pi.appendEntry(ENTRY, { nudged: key }), me, tell });
+			nudgeTimer = setInterval(() => void nudges?.poll().catch(() => {}), nudgeMs).unref();
 			// Starting runs in the background: pi awaits session_start handlers in turn, and pi-intercom connects in its own, after this one.
 			let starting: Promise<void> | undefined;
 			if (isTower) {
@@ -390,6 +403,11 @@ export function createStrawBoss({ run = herdrRun, api = herdrApi(), call = herdr
 			}
 		});
 
+		// A launched subagent is marked within seconds, once its pane shows its session file, instead of at the next 4 minute refresh.
+		pi.on("tool_result", (event) => {
+			if (["subagent", "subagent_resume"].includes(event.toolName) && !isTower && !barred && role()) for (const ms of KID_MARK_MS) setTimeout(() => void publish(), ms).unref();
+		});
+
 		pi.on("session_shutdown", async () => {
 			if (gui) await switchRemote(gui, false, guiDir, ts).catch(() => {});
 			await gui?.stop();
@@ -398,6 +416,8 @@ export function createStrawBoss({ run = herdrRun, api = herdrApi(), call = herdr
 			dashboard = undefined;
 			clearInterval(timer);
 			timer = undefined;
+			clearInterval(nudgeTimer);
+			nudges?.stop();
 			stopped = true; // a refresh still in flight must not write tokens after they are cleared
 			await publishing;
 			const held = holdsTower;

package/src/net.ts

@@ -3,16 +3,17 @@ import { basename, join, sep } from "node:path";
 import { type Mark, markOf, type Row, sessionMark, subagents } from "./dashboard.ts";
 import { headOf, type HerdrRun, isSub, type Pane, panes, parentOf, type Session, workspaces, type Workspace } from "./herdr.ts";
 import { type Pending, type Relayed, withPending } from "./ask.ts";
+import type { Shelf } from "./documents.ts";
 import { canonical } from "./history.ts";
 
 // The whole straw net as one JSON-able snapshot for the browser view: every workspace as a base with its tower, tabs, agents,
 // and subagents (linked to their launcher the way the tower dashboard links them), and sub workspaces as outposts.
 
 /** `key` names the unit in routes and the API; `control` says a live pi pane backs it. `outside` units are pi panes the net does not hold (D1). */
-export interface Unit { id: string; key: string; control: boolean; name: string; role: "main" | "member" | "subagent" | "outside"; mark: Mark; note?: string; subs: Unit[]; pending?: Pending }
+export interface Unit extends Shelf { id: string; key: string; control: boolean; name: string; role: "main" | "member" | "subagent" | "outside"; mark: Mark; note?: string; subs: Unit[]; pending?: Pending }
 export interface Tab { id: string; label: string; units: Unit[] }
 export interface Outpost { id: string; label: string; mark: Mark }
-export interface Base { id: string; label: string; mark: Mark; head: boolean; tower: { name: string; mark: Mark; key: string; control: boolean; pending?: Pending } | null; tabs: Tab[]; outposts: Outpost[]; outside: Unit[] }
+export interface Base { id: string; label: string; mark: Mark; head: boolean; tower: ({ name: string; mark: Mark; key: string; control: boolean; pending?: Pending } & Shelf) | null; tabs: Tab[]; outposts: Outpost[]; outside: Unit[] }
 export interface Net { bases: Base[] }
 /** What the server may read for a key: the registry entry is the allow list, and paths never come from the browser. */
 export interface Ref { key: string; base: string; name: string; role: string; file?: string; pane?: string }

package/src/orphan.ts

@@ -0,0 +1,115 @@
+import { readdirSync } from "node:fs";
+import { basename, join } from "node:path";
+import { artifacts, ownFile, readJson } from "./dashboard.ts";
+import { type HerdrRun, panes, type Session } from "./herdr.ts";
+
+// A subagent that has finished, while the session that launched it can no longer receive its result, is asked once to report over intercom.
+//
+// pi-herdr-agents delivers a child's result from the launcher's own process: its watchers, and its registry of launched children (`runningSubagents`, kept
+// in the global `Symbol.for("pi-subagents/runtime")` slot so that a reloaded module adopts the map), live in that process's memory. /reload, /new, /resume
+// and /fork keep them. Quitting pi suppresses the delivery, and a crash or restart drops them for good: a restarted pi does not adopt the children it launched
+// before ("V1 does not automatically recover watchers after a full process restart", docs/tools.md). So a child of this session that the registry no longer
+// holds, and whose result is not in the transcript, can no longer be delivered. A registry that cannot be read proves nothing, so nothing is sent then.
+
+export interface Entry { type: string; customType?: string; data?: unknown; details?: unknown }
+export interface Orphans {
+	run: HerdrRun;
+	/** This session's file, and every entry of its transcript. */
+	file(): string | undefined;
+	entries(): Entry[];
+	sessions(): Promise<Session[]>;
+	send(to: string, message: string): Promise<{ status: string; code?: string; detail?: string }>;
+	/** The session entry type that records a nudge, and the write of one. */
+	type: string;
+	remember(key: string): void;
+	me(): string;
+	tell(text: string, level?: "info" | "warning"): void;
+}
+
+const REGISTRY = Symbol.for("pi-subagents/runtime");
+// The messages that carry a finished child's result into the launcher's transcript; their details name the child's session file.
+const FINAL = ["subagent_result", "subagent_ping"];
+const GIVE_UP = 4;
+
+/** The ids of the runs this process's pi-herdr-agents still tracks, or undefined when the registry cannot be read. */
+export function tracked(): Set<string> | undefined {
+	const map = (globalThis as Record<symbol, { runningSubagents?: unknown } | undefined>)[REGISTRY]?.runningSubagents;
+	return map instanceof Map ? new Set(map.keys() as Iterable<string>) : undefined;
+}
+
+export function orphans(d: Orphans) {
+	const nudged = new Set(d.entries().flatMap((e) => (e.type === "custom" && e.customType === d.type && typeof (e.data as { nudged?: unknown } | undefined)?.nudged === "string" ? [(e.data as { nudged: string }).nudged] : [])));
+	// A child counts as a miss when its pane (running its own launch script) or its intercom session cannot be found; after GIVE_UP misses it is left alone.
+	const misses = new Map<string, number>();
+	let before = new Set<string>(), busy = false, stopped = false;
+	const miss = (id: string) => void misses.set(id, (misses.get(id) ?? 0) + 1);
+	/**
+	 * Whether the foreground process of `pane` runs the launch script this session wrote for run `id`. A pane that only reuses the run's session file
+	 * (a run another session resumed, or a pi someone started on that file) is not the run, and the run's activity file says nothing about it.
+	 */
+	async function runs(pane: string, id: string, session: string): Promise<boolean> {
+		const quote = (text: string) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), script = new RegExp(`/artifacts/${quote(session)}/subagent-scripts/[^/]*-${quote(id)}\\.sh$`);
+		try {
+			const info = JSON.parse(await d.run(["pane", "process-info", "--pane", pane])).result.process_info.foreground_processes as { argv?: string[] }[];
+			return info.some((p) => p.argv?.some((arg) => script.test(arg)));
+		} catch {
+			return false;
+		}
+	}
+
+	async function poll(): Promise<void> {
+		if (busy || stopped) return;
+		const file = d.file(), live = tracked();
+		// Without its own session id, a session file, or a readable registry there is nothing to say or to judge by.
+		if (!file || !live || !d.me()) return void (before = new Set());
+		busy = true;
+		try {
+			const dir = join(artifacts(file), "subagent-activity");
+			let ids: string[] = [];
+			try {
+				ids = readdirSync(dir).filter((name) => name.endsWith(".json")).map((name) => name.slice(0, -5));
+			} catch {} // no subagent was ever launched from this session
+			ids = ids.filter((id) => !live.has(id) && !nudged.has(id) && (misses.get(id) ?? 0) < GIVE_UP);
+			const reported = ids.length ? d.entries().flatMap((e) => (e.type === "custom_message" && FINAL.includes(e.customType ?? "") ? [String((e.details as { sessionFile?: unknown } | undefined)?.sessionFile ?? "")] : [])) : [];
+			const open = ids.filter((id) => !reported.some((f) => ownFile(f, id)));
+			// Only a child whose own activity says it ended its turn and waits is looked up, and the broker has to list this session under its own
+			// id first (the report is asked for there): that is cheaper than Herdr.
+			const waiting = open.filter((id) => readJson(join(dir, `${id}.json`)).phase === "waiting");
+			const list = waiting.length ? await d.sessions().catch(() => undefined) : undefined, self = list?.find((s) => s.id === d.me());
+			const ps = self ? await panes(d.run) : [];
+			const found: { id: string; pane: string; name: string }[] = [];
+			for (const id of self ? waiting : []) {
+				const pane = ps.find((p) => p.agent === "pi" && ownFile(p.agent_session?.value, id));
+				if (!pane) miss(id);
+				// Working or asking a question is not finished; a pane someone has looked at is idle, not done.
+				else if (["done", "idle"].includes(pane.agent_status ?? "")) found.push({ id, pane: pane.pane_id, name: pane.label ?? id.slice(0, 8) });
+			}
+			// A child has to be found finished twice in a row, so that a delivery that is just going out is not mistaken for a lost one.
+			const ripe = found.filter((c) => before.has(c.id));
+			before = new Set(found.map((c) => c.id));
+			if (!list || !self) return;
+			for (const c of ripe) {
+				const kid = list.find((s) => s.herdrLocation?.paneId === c.pane && s.id !== self.id);
+				if (!kid) {
+					miss(c.id);
+					continue;
+				}
+				// Its own intercom status says it is idle; a child that went back to work is not asked.
+				if (kid.status !== "idle" || stopped) continue;
+				const own = await runs(c.pane, c.id, basename(artifacts(file)));
+				if (!own) miss(c.id);
+				// The session may have ended while Herdr was asked.
+				if (!own || stopped) continue;
+				// Written down before it is sent: a nudge is sent at most once per run, even when the send fails or this process ends meanwhile.
+				nudged.add(c.id);
+				d.remember(c.id);
+				const result = await d.send(kid.id, `Straw Boss: the session that launched you ("${self.name ?? self.id}", intercom session ${self.id}) can no longer receive your result by itself; for example, its pi was restarted after it launched you. Send your final report to that session now, with the intercom tool (action "send", to "${self.id}"): the outcome, what changed, and the evidence. Then stop; start no new work. This is sent once and needs no reply.`);
+				if (result.status === "sent") d.tell(`Straw Boss: asked ${c.name} to send its report here over intercom, because its result could no longer reach this session`);
+				else d.tell(`Straw Boss: could not ask ${c.name} to send its report: ${result.status} ${result.code ?? ""} ${result.detail ?? ""}`.trim(), "warning");
+			}
+		} finally {
+			busy = false;
+		}
+	}
+	return { poll, stop: () => void (stopped = true) };
+}