@alphacoder-v0/pi-loops 0.24.0 → 0.24.2

package/src/engine.ts

@@ -1079,8 +1079,9 @@ export function deadLetterText(why: string, prompt: string): string {
 	return `could not be delivered (${why}): ${prompt}`;
 }
 
-/** The parts of a finding `deadLetterText` wrote, or undefined for any other finding. */
-export function deadLetterParts(text: string): { why: string; prompt: string } | undefined {
+/** The parts of a dead letter's text, or undefined for any other finding: the engine's mark decides, never the text. */
+export function deadLetterParts(entry: { text: string; undelivered?: true }, text = entry.text): { why: string; prompt: string } | undefined {
+	if (!entry.undelivered) return undefined;
 	const m = /^could not be delivered \((.*?)\): ([\s\S]*)$/.exec(text);
 	return m ? { why: m[1], prompt: m[2] } : undefined;
 }
@@ -1098,7 +1099,7 @@ async function deadLetter(store: RequestStore, sinks: EngineSinks, sessionId: st
 	if (rule !== undefined) {
 		if (!checkDecidedFinding(sinks.audit, row.id)) await sinks.inbox.appendOnce({ source: `trigger:${rule}`, run_id: row.id, job_id: rule, cwd, text: text || `rule result ${row.id}`, session_id: sessionId }, { run_id: row.id, source: `trigger:${rule}` });
 	}
-	else await sinks.inbox.append({ source: row.source, run_id: row.id, cwd, text: deadLetterText(why, text.slice(0, DEAD_LETTER_CHARS) || `${row.kind} request ${row.id}`), session_id: sessionId });
+	else await sinks.inbox.append({ source: row.source, run_id: row.id, cwd, text: deadLetterText(why, text.slice(0, DEAD_LETTER_CHARS) || `${row.kind} request ${row.id}`), session_id: sessionId, undelivered: true });
 	sinks.audit.appendAudit({ cwd, type: "request", traceId: row.id, state: "dead", sourceLabel: row.source, eventLabel: row.session_id, summary: text, details: { session_id: row.session_id, kind: row.kind, attempts: row.attempts, last_error: row.last_error, reason: why } });
 	store.remove(sessionId, [row.id]);
 }

package/src/host-control-channel.ts

@@ -16,6 +16,7 @@ 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 { plural } from "./plural.ts";
 import { type LeaseStore, type ProcessProbe, holderAlive, sessionFileName } from "./lease.ts";
 import { conversationLabel, shortSessionId } from "./session-head.ts";
 import { previewRedacted, redact } from "./redact.ts";
@@ -205,7 +206,7 @@ export function requestLines(queues: readonly RequestQueue[], now: number, opts:
 	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)}` : ""}`;
+	const head = `  ${plural(total, "message")} waiting for ${plural(queues.length, "conversation")}${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)}`}`)];
 }
 

package/src/host-control.ts

@@ -604,6 +604,12 @@ export interface EnsureHostOptions extends SpawnHostOptions {
 	page?: true;
 	/** How long an upgrade waits for the old process to leave; `LEAVE_WAIT_MS` unless a test says. */
 	leaveWaitMs?: number;
+	/**
+	 * Called once when an upgrade is still waiting for the old process after `leaveNoticeMs` (2 s):
+	 * it is letting a turn in the page finish, and a person waiting on this call is told why.
+	 */
+	onLeaveWait?: () => void;
+	leaveNoticeMs?: number;
 	/**
 	 * Whether a start waits for the process to record itself (up to 10 s). Every caller waits but a
 	 * window that is quitting: it has nothing to do with the answer, and waiting made quitting slow.
@@ -645,13 +651,22 @@ export async function ensureHost(opts: EnsureHostOptions): Promise<{ action: Ens
 	if (action.kind === "upgrade") {
 		recordUpgrader(opts.dir, { pid: process.pid, version: opts.myVersion, procStart: procStart(process.pid) });
 		await askHost(opts.dir, { op: "upgrade" });
+		// A quitting window asks and goes. The claim above holds older windows back; the next window,
+		// or the next `pi-loops`, starts this version once the old process has left.
+		if (opts.wait === false) return { action };
 		// Wait for it to go and start this version at once: the gap until the next tick is where an
 		// older window used to start the old code again. It may first let a turn in the page finish.
 		const old = rec!.pid;
-		const deadline = Date.now() + (opts.leaveWaitMs ?? LEAVE_WAIT_MS);
+		const began = Date.now();
+		const deadline = began + (opts.leaveWaitMs ?? LEAVE_WAIT_MS);
+		let told = false;
 		while (Date.now() < deadline) {
 			const now = readHostService(opts.dir);
 			if (!now || now.pid !== old || !hostServiceAlive(now)) break;
+			if (!told && Date.now() - began >= (opts.leaveNoticeMs ?? 2_000)) {
+				told = true;
+				opts.onLeaveWait?.();
+			}
 			await new Promise((r) => setTimeout(r, 100));
 		}
 		const still = readHostService(opts.dir);

package/src/host-runtime.ts

@@ -185,13 +185,13 @@ export function createHostRuntime(deps: HostRuntimeDeps): HostRuntime {
 		// What the page's waiting line calls it: a job's id is 32 characters no person typed.
 		const open = { requestId: runId, startedAt: scheduler.runningRuns().find((r) => r.runId === runId)?.startedAt ?? stamp(), label: job.name ?? runId.slice(0, 12) };
 		turnOpen.set(held.sessionId, { ...open, writing: false });
-		log(`cron ${job.name ?? job.id}: turn ${runId.slice(0, 12)} in session ${held.sessionId.slice(0, 8)}`);
+		log(`cron ${job.name ?? job.id}: turn ${runId.slice(0, 12)} in session ${shortSessionId(held.sessionId)}`);
 		let result: RunnerResult;
 		try {
 			try {
 				await drainInto(held);
 			} catch (err: any) {
-				log(`requests for session ${held.sessionId.slice(0, 8)}: ${err?.message ?? err}`);
+				log(`requests for session ${shortSessionId(held.sessionId)}: ${err?.message ?? err}`);
 			}
 			if (signal.aborted) {
 				// Stopped before it began: nothing to run, and no model call to start for a turn already over.
@@ -222,7 +222,7 @@ export function createHostRuntime(deps: HostRuntimeDeps): HostRuntime {
 		try {
 			landed = conversationHas(SessionManager.open(held.sessionFile).getEntries(), runId);
 		} catch (err: any) {
-			log(`cron ${job.name ?? job.id}: could not read session ${held.sessionId.slice(0, 8)} after its turn: ${err?.message ?? err}`);
+			log(`cron ${job.name ?? job.id}: could not read session ${shortSessionId(held.sessionId)} after its turn: ${err?.message ?? err}`);
 		}
 		return { preempted, result, landed };
 	}
@@ -377,10 +377,10 @@ export function createHostRuntime(deps: HostRuntimeDeps): HostRuntime {
 			await drainInto(held);
 			if (traceId === undefined) return true;
 			const delivered = conversationHas(SessionManager.open(held.sessionFile).getEntries(), traceId);
-			if (delivered) log(`trigger ${traceId.slice(0, 8)}: appended to session ${sessionId.slice(0, 8)}`);
+			if (delivered) log(`trigger ${traceId.slice(0, 8)}: appended to session ${shortSessionId(sessionId)}`);
 			return delivered;
 		} catch (err: any) {
-			log(`requests for session ${sessionId.slice(0, 8)}: ${err?.message ?? err}`);
+			log(`requests for session ${shortSessionId(sessionId)}: ${err?.message ?? err}`);
 			// Giving the lease back below rings this process again; with the same failure waiting
 			// (an inbox it cannot write), that ring would fail the same way, for ever.
 			quietUntilTick.add(sessionId);
@@ -402,9 +402,9 @@ export function createHostRuntime(deps: HostRuntimeDeps): HostRuntime {
 			if (!lease.holder || !busy || !sameHolder(lease.holder, me()) || running.has(busy.runId) || now - Date.parse(busy.since) < 60_000) continue;
 			try {
 				leases.release(lease.sessionId, me(), { epoch: lease.epoch, fileMtimeMs: fileMtime(lease.sessionFile) });
-				log(`gave back session ${lease.sessionId.slice(0, 8)}, held for run ${busy.runId} that is no longer running`);
+				log(`gave back session ${shortSessionId(lease.sessionId)}, held for run ${busy.runId} that is no longer running`);
 			} catch (err: any) {
-				log(`lease ${lease.sessionId.slice(0, 8)}: ${err?.message ?? err}`);
+				log(`lease ${shortSessionId(lease.sessionId)}: ${err?.message ?? err}`);
 			}
 		}
 	}
@@ -437,7 +437,7 @@ export function createHostRuntime(deps: HostRuntimeDeps): HostRuntime {
 			const file = leases.read(sessionId)?.sessionFile;
 			if (file && fs.existsSync(file)) return; // there, only busy or recently written: a later tick
 			const buried = await bury(sessionId, requests, sinks(), "its conversation is gone");
-			if (buried.length) log(`${buried.length} queued request(s) for session ${sessionId.slice(0, 8)} went to the inbox: its conversation is gone`);
+			if (buried.length) log(`${buried.length} queued request(s) for session ${shortSessionId(sessionId)} went to the inbox: its conversation is gone`);
 			return;
 		}
 		// The same decision the drain makes, read without the lease (a read needs none). Marked before
@@ -475,7 +475,7 @@ export function createHostRuntime(deps: HostRuntimeDeps): HostRuntime {
 			try {
 				await deliverSession(sessionId);
 			} catch (err: any) {
-				log(`requests for session ${sessionId.slice(0, 8)}: ${err?.message ?? err}`);
+				log(`requests for session ${shortSessionId(sessionId)}: ${err?.message ?? err}`);
 			}
 		}
 	}
@@ -503,7 +503,7 @@ export function createHostRuntime(deps: HostRuntimeDeps): HostRuntime {
 		rungSinceTick.set(sessionId, rung);
 		if (rung > RINGS_PER_TICK) {
 			quietUntilTick.add(sessionId);
-			log(`doorbell for session ${sessionId.slice(0, 8)}: rang ${RINGS_PER_TICK} times since the last tick; left to the tick`);
+			log(`doorbell for session ${shortSessionId(sessionId)}: rang ${RINGS_PER_TICK} times since the last tick; left to the tick`);
 			return;
 		}
 		if (delivering.has(sessionId)) {
@@ -512,7 +512,7 @@ export function createHostRuntime(deps: HostRuntimeDeps): HostRuntime {
 		}
 		delivering.add(sessionId);
 		deliverSession(sessionId)
-			.catch((err: any) => log(`requests for session ${sessionId.slice(0, 8)}: ${err?.message ?? err}`))
+			.catch((err: any) => log(`requests for session ${shortSessionId(sessionId)}: ${err?.message ?? err}`))
 			.then(() => {
 				delivering.delete(sessionId);
 				if (ringAgain.delete(sessionId)) ring(sessionId);

package/src/inbox-card.ts

@@ -137,7 +137,7 @@ export function ruleResultText(text: string): string {
 export function inboxCard(entry: InboxEntry, ctx: CardContext): InboxCard | undefined {
 	if (!entry.id || !entry.text) return undefined;
 	const text = capChars(redact(screenText(entry.text)).replace(/\s+/g, " "), INBOX_TEXT_MAX_CHARS);
-	const origin = entry.source.startsWith("trigger:") ? "rule" : deadLetterParts(entry.text) ? "undelivered" : "loop";
+	const origin = entry.source.startsWith("trigger:") ? "rule" : deadLetterParts(entry) ? "undelivered" : "loop";
 	const loopId = origin === "loop" ? entry.job_id : undefined;
 	const loopName = loopId ? ctx.loopName(loopId) : undefined;
 	// A rule check files its result with the first matched rule's id (src/trigger-runtime.ts); a push
@@ -248,7 +248,7 @@ export function claimPrompt(e: InboxEntry): string {
 	// person's yes, so the turn carries the decision out rather than re-investigating it.
 	const checkpoint = e.kind === "checkpoint" ? "\nThis finding is a checkpoint: claiming it is the person's approval of the decision it recommends — carry that decision out, and stop where the finding says a person acts." : "";
 	// A prompt that never reached the chat: claiming it is asking for it now, not investigating why it was late.
-	const late = deadLetterParts(text);
+	const late = deadLetterParts(e, text);
 	if (late) return `This prompt (${source}, for ${cwd}) could not be delivered earlier (${late.why}). Do what it asks now:\n${late.prompt}`;
 	return `A recurring loop (${source}, running in ${cwd}) reported this finding — investigate and address it:\n${text}${verified}${checkpoint}`;
 }

package/src/inbox.ts

@@ -61,6 +61,11 @@ export interface InboxEntry {
 	dismissed_at?: string;
 	/** The transcript of the run that filed this finding (RunRecord.sessionFile). */
 	transcript?: string;
+	/**
+	 * Set by the engine's dead letter alone: a prompt that never reached its conversation. The text
+	 * says so too, but the text is anyone's to write, and a claim of this finding carries it out.
+	 */
+	undelivered?: true;
 }
 
 /** The fields a finding is, in their order — CONTRACT.md §2.2 and docs/downstream.md §3. */
@@ -136,6 +141,7 @@ export class Inbox {
 			dismissed_at: entry.dismissed_at,
 			...(entry.session_id === undefined ? {} : { session_id: entry.session_id }),
 			...(entry.transcript === undefined ? {} : { transcript: entry.transcript }),
+			...(entry.undelivered ? { undelivered: true as const } : {}),
 		};
 	}
 
@@ -336,6 +342,7 @@ function readFinding(raw: any): InboxEntry | undefined {
 		verified_reason: str("verified_reason", "verifiedReason"),
 		dismissed_at: str("dismissed_at"),
 		transcript: str("transcript"),
+		...(raw.undelivered === true ? { undelivered: true as const } : {}),
 	};
 }
 

package/src/job-lines.ts

@@ -12,6 +12,7 @@ import { shortSessionId } from "./session-head.ts";
 import type { InboxEntry } from "./inbox.ts";
 import { asleepNote, runsSomewhere, type OwnerView } from "./job-owner.ts";
 import { QUIET_MARK_AFTER, SIGNAL_WINDOW_MS, loopSignal, signalSummary } from "./job-signal.ts";
+import { plural } from "./plural.ts";
 import { previewRedacted } from "./redact.ts";
 import type { SessionRequest } from "./requests.ts";
 import { computeNext, formatLocal, formatSchedule } from "./schedule.ts";
@@ -104,11 +105,6 @@ export function pickQueued(rows: readonly SessionRequest[], ref: string): Sessio
 	return prefixed.length === 1 ? prefixed[0] : undefined;
 }
 
-/** `1 loop`, `2 loops`: a count a person reads, never `loop(s)`. */
-export function plural(n: number, one: string, many = `${one}s`): string {
-	return `${n} ${n === 1 ? one : many}`;
-}
-
 /**
  * The one-time line a session start says when plain jobs carry `--tools`: 0.22.8 stored the list
  * and never used it, and since 0.23 a turn in a window asks before a tool outside it. Undefined when

package/src/job-signal.ts

@@ -9,6 +9,7 @@
  */
 import type { InboxEntry } from "./inbox.ts";
 import type { RunRecord } from "./store.ts";
+import { plural } from "./plural.ts";
 
 export interface LoopSignal {
 	/** Runs that finished in the window (failed ones included: they cost, and they are what `quiet` is measured against). */
@@ -71,7 +72,7 @@ export function loopSignal(jobId: string, runs: RunRecord[], inbox: InboxEntry[]
  */
 export function signalSummary(s: LoopSignal): string | undefined {
 	if (!s.findings) return undefined;
-	const parts = [`${s.findings} finding${s.findings === 1 ? "" : "s"}`];
+	const parts = [`${plural(s.findings, "finding")}`];
 	if (s.claimed) parts.push(`${s.claimed} claimed`);
 	if (s.dismissed) parts.push(`${s.dismissed} dismissed${s.dismissedWithReason ? ` (${s.dismissedWithReason} with a reason)` : ""}`);
 	return parts.join(" · ");

package/src/mcp.ts

@@ -769,6 +769,8 @@ export class McpSource {
 				if (f.method === "ping") send({ jsonrpc: "2.0", id: f.id, result: {} });
 				else send({ jsonrpc: "2.0", id: f.id, error: { code: -32601, message: `pi-loops is a notification-only client; ${f.method} is not supported` } });
 			} else if (typeof f.method === "string") {
+				// A line read before the stop and parsed after it: whoever owned this source has let it go.
+				if (this.stopped) continue;
 				this.status.lastEventAt = stamp();
 				this.status.queuedCount++;
 				this.status.lastError = undefined; // A successful push clears the last error

package/src/page-children.ts

@@ -18,6 +18,7 @@ import { DELIVERY_JOB_ID, holderAlive, type ProcessProbe, procStart, type Sessio
 import { withFileLockSync, writeFileAtomic } from "./lock.ts";
 import { realpathish } from "./paths.ts";
 import { stamp } from "./schedule.ts";
+import { readSessionHead, shortSessionId } from "./session-head.ts";
 
 /**
  * Run one of the page's callbacks so that nothing it throws, or rejects with, leaves it.
@@ -200,62 +201,6 @@ export function claimPageChild(env: NodeJS.ProcessEnv = process.env, proc: objec
  */
 export const COMMANDS_TTL_MS = 30_000;
 
-const SESSION_HEAD = 64 * 1024;
-
-/** The header, a name if one was set early, and the first thing a person said. */
-export function readHead(file: string) {
-	let text;
-	let readBytes = 0;
-	try {
-		const fd = fs.openSync(file, "r");
-		try {
-			const buf = Buffer.alloc(SESSION_HEAD);
-			// `SESSION_HEAD` is a byte window, so the decision to cut is the byte count read, not the
-			// decoded string's length: a multi-byte character makes those differ.
-			readBytes = fs.readSync(fd, buf, 0, SESSION_HEAD, 0);
-			text = buf.toString("utf8", 0, readBytes);
-		} finally {
-			fs.closeSync(fd);
-		}
-	} catch {
-		return undefined;
-	}
-	const lines = text.split("\n");
-	let header;
-	try {
-		header = JSON.parse(lines[0] ?? "");
-	} catch {
-		return undefined;
-	}
-	if (header?.type !== "session" || typeof header.id !== "string") return undefined;
-	const cut = readBytes >= SESSION_HEAD;
-	let name;
-	let first;
-	let messages = 0;
-	// The last line of a partial read is half a line. A file that fitted has no such line, and
-	// dropping one there loses a message from a count that could have been exact.
-	for (const line of lines.slice(1, cut ? -1 : undefined)) {
-		if (!line.trim()) continue;
-		let entry;
-		try {
-			entry = JSON.parse(line);
-		} catch {
-			continue;
-		}
-		// Written by whatever set it — a person, a model, an extension — so it is bounded here the
-		// way the first message is, rather than carrying 64KB into the picker.
-		if (entry?.type === "session_info" && typeof entry.name === "string") name = entry.name.slice(0, 200);
-		if (entry?.type !== "message") continue;
-		messages++;
-		if (first || entry.message?.role !== "user") continue;
-		const content = entry.message.content;
-		const said = typeof content === "string" ? content : (content ?? []).map((c: any) => (typeof c?.text === "string" ? c.text : "")).join(" ");
-		// A mention is expanded before it is sent, so the first user message can be a whole file.
-		if (said.trim()) first = said.trim().slice(0, 200);
-	}
-	return { id: header.id, startedAt: header.timestamp, name, first, messages, truncated: cut };
-}
-
 /**
  * The model a session was last using, as pi would read it back.
  *
@@ -765,7 +710,7 @@ export class PageChild {
 		// the open session is otherwise a way to be offered the one destination that is refused.
 		const open = this.sessionFile ? realpathish(this.sessionFile) : undefined;
 		for (const entry of out.slice(0, limit)) {
-			const head = readHead(entry.file);
+			const head = readSessionHead(entry.file);
 			if (!head) continue; // not a session file, or not a readable one
 			sessions.push({ ...entry, ...head, current: realpathish(entry.file) === open });
 		}
@@ -1207,7 +1152,7 @@ export class ChildPool {
 		// there. `--session` on that path starts another conversation in it; without it, pi starts a
 		// new one in the project, in a file of its own, and the pool follows it there (`moved`).
 		const resumable = how.sessionFile !== undefined && fs.existsSync(how.sessionFile);
-		if (how.sessionFile && !resumable) this.opts.log(`pi-loops page: ${how.sessionId?.slice(0, 8) ?? "a conversation"} has no file yet (${how.sessionFile}); pi starts a new conversation in ${how.cwd}`);
+		if (how.sessionFile && !resumable) this.opts.log(`pi-loops page: ${how.sessionId ? shortSessionId(how.sessionId) : "a conversation"} has no file yet (${how.sessionFile}); pi starts a new conversation in ${how.cwd}`);
 		const argv = [...args, "--mode", "rpc", ...(resumable ? ["--session", how.sessionFile as string] : []), ...how.piArgs];
 		// A process group of its own (POSIX): a terminal's Ctrl-C goes to the whole foreground group,
 		// and pi in rpc mode has no SIGINT handler, so it died before anyone could ask it to quit. pi

package/src/page-server.ts

@@ -20,7 +20,7 @@ import { COPY_KEY_MS, type HostSnapshot, type PageOpened, type PageOpenRequest,
 import { buildSessionProjection, migrateSessionEntries, parseSessionEntries, type SessionEntry } from "@earendil-works/pi-coding-agent";
 import { DELIVERY_JOB_ID, holderAlive, holderDelivers, type LeaseHolder, LeaseStore, procStart, type SessionLease, sessionFileName, shouldReadAgain } from "./lease.ts";
 import { ACTIVITY_WINDOW_MS, activityFrom, attentionFrom, machineWide } from "./activity.ts";
-import { formatSchedule, stamp } from "./schedule.ts";
+import { formatSchedule, scheduleWords, stamp } from "./schedule.ts";
 import { type Look, lookLine, watchOf } from "./path-precheck.ts";
 import { loopSignal, type LoopSignal, SIGNAL_WINDOW_MS } from "./job-signal.ts";
 import { applyTune, rowSignal, scheduleAudit, suggestTune } from "./job-tune.ts";
@@ -29,13 +29,14 @@ import { Inbox, type InboxEntry, inProject } from "./inbox.ts";
 import { type ClaimDelivery, type InboxCard, DISMISS_CHIPS, cardsOf, claimLine, claimPrompt, dismissLine, dismissOutcome, screenText } from "./inbox-card.ts";
 import { INBOX_TEXT_MAX_CHARS } from "./protocol.ts";
 import { redact } from "./redact.ts";
-import { readSessionHead } from "./session-head.ts";
+import { readSessionHead, shortSessionId } from "./session-head.ts";
 import { JobStore, type LoopJob, MAX_PROMPT_BYTES } from "./store.ts";
 import { summarizeSessionFile } from "./transcript.ts";
 import { conversationLabel } from "./session-head.ts";
-import { pidAlive } from "./lock.ts";
+import { pidAlive, withFileLockSync } from "./lock.ts";
 import { asleepNote, type OwnerView, runsSomewhere, whereRuns } from "./job-owner.ts";
 import { loopLabel, snapshotLoopLabel } from "./job-lines.ts";
+import { plural } from "./plural.ts";
 import {
 	type ChildPool,
 	type ChildView,
@@ -50,7 +51,6 @@ import {
 	PAGE_STREAMS_PER_CHILD,
 	PAGE_STREAMS_TOTAL,
 	type PageChild,
-	readHead,
 } from "./page-children.ts";
 import { removeOpenFile, sweepOpenFiles, writeOpenFile } from "./open-file.ts";
 import { DEVICE_COOKIE, DEVICE_STORAGE_KEY, DeviceStore, KEY_KINDS, type KeyKind, UrlKeys } from "./page-devices.ts";
@@ -124,12 +124,40 @@ export interface PageServer {
  * to do). You will not have to type it: a browser is remembered after its first visit.
  */
 export function webToken(dir: string, fail: (message: string) => never): string {
+	fs.mkdirSync(dir, { recursive: true });
+	// Two windows opening together may both start pi-loops, and both get here before either claims
+	// the service: under the lock, the second reads the token the first wrote instead of replacing it.
+	// `fail` is called after the lock is released: the host's `fail` exits, and a lock left behind
+	// would hold the next start for its whole stale window.
+	try {
+		return withFileLockSync(path.join(dir, "web-token.lock"), () =>
+			readOrMakeToken(dir, (message) => {
+				throw new TokenRefused(message);
+			}),
+		);
+	} catch (err: any) {
+		return fail(err instanceof TokenRefused ? err.message : `pi-loops web: ${err?.message ?? err}`);
+	}
+}
+
+class TokenRefused extends Error {}
+
+function readOrMakeToken(dir: string, fail: (message: string) => never): string {
 	const file = path.join(dir, "web-token");
 	// 0.22.8 kept its token in a cookie that every port on 127.0.0.1 receives for a year, so the
 	// first 0.24 start replaces a token it finds without this marker, once. A token written after
 	// the marker is the person's own and is kept.
 	const marker = path.join(dir, "web-token.v024");
-	const rotated = fs.existsSync(marker);
+	// lstat, as for the token file: a dangling symlink here is not "not rotated yet", and reading
+	// it as that rotated the token on every start and then failed on the marker.
+	let markerStat: fs.Stats | undefined;
+	try {
+		markerStat = fs.lstatSync(marker);
+	} catch (err: any) {
+		if (err?.code !== "ENOENT") fail(`pi-loops web: ${err?.message ?? err}`);
+	}
+	if (markerStat && !markerStat.isFile()) fail(`pi-loops web: ${marker} is not a regular file`);
+	const rotated = !!markerStat;
 	try {
 		// lstat, not stat: a symlink here is not a token file, it is someone else choosing where
 		// this process reads and writes. LOOPS_DIR can be pointed anywhere with --loops-dir.
@@ -149,7 +177,6 @@ export function webToken(dir: string, fail: (message: string) => never): string
 		}
 	}
 	const made = randomBytes(16).toString("hex");
-	fs.mkdirSync(dir, { recursive: true });
 	fs.writeFileSync(file, `${made}\n`, { mode: 0o600, flag: "w" });
 	fs.chmodSync(file, 0o600);
 	if (!rotated) {
@@ -981,8 +1008,7 @@ export function renderHostPage(s: HostStatus): string {
 	const snap = s.snapshot;
 	/** A stamp as the page's clock writes it (CLOCK_SCRIPT); the stamp itself until then. */
 	const time = (iso: unknown) => `<time datetime="${e(iso)}">${e(iso)}</time>`;
-	const count = (n: number, one: string) => `${n} ${one}${n === 1 ? "" : "s"}`;
-	const since = ({ sinceYouLooked: y }: SessionRow) => (y.runs === 0 && y.findings === 0 ? "—" : `${count(y.runs, "run")}${y.failed ? `, ${y.failed} failed` : ""}, ${count(y.findings, "finding")}${y.mine && y.mine !== y.findings ? `, ${y.mine} from this conversation` : ""}`);
+	const since = ({ sinceYouLooked: y }: SessionRow) => (y.runs === 0 && y.findings === 0 ? "—" : `${plural(y.runs, "run")}${y.failed ? `, ${y.failed} failed` : ""}, ${plural(y.findings, "finding")}${y.mine && y.mine !== y.findings ? `, ${y.mine} from this conversation` : ""}`);
 	// A title and a path are what someone typed or named: drawn as text, as the page's list draws them.
 	const rows = s.sessions.map((row) => `<tr><td>${e(plainText(conversationLabel(row.sessionId, row.title)))}</td><td>${e(plainText(row.cwd ?? "—"))}</td><td>${e(openIn(row.holder))}</td><td>${e(row.plainJobs)}</td><td>${e(row.rules)}</td><td>${e(row.mailbox)}</td><td>${e(since(row))}</td></tr>`).join("");
 	const table = `<div class="scroll"><table><thead><tr><th>conversation</th><th>project</th><th>where</th><th>loops</th><th>rules</th><th>waiting</th><th>since you looked</th></tr></thead><tbody>${rows}</tbody></table></div>`;
@@ -1046,11 +1072,21 @@ export async function openForLaunch(
 /** This package's root: what an `-e` that loads pi-loops names. */
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 
-/** Whether `args` carry `-e <path>` or `--extension <path>` naming this package's root, a relative path read from `base`. */
+/**
+ * Whether `args` carry `-e <path>`, `--extension <path>` or `--extension=<path>` naming this
+ * package: its root, or its entry file `src/extension-entry.ts` (package.json `pi.extensions`). A
+ * relative path is read from `base`.
+ */
 function loadsPiLoops(args: readonly string[], base: string): boolean {
-	for (let i = 0; i + 1 < args.length; i++) {
+	const ours = [PACKAGE_ROOT, path.join(PACKAGE_ROOT, "src", "extension-entry.ts")].map(realpathish);
+	const names = (p: string) => ours.includes(realpathish(path.resolve(base, p)));
+	for (let i = 0; i < args.length; i++) {
+		if (args[i].startsWith("--extension=")) {
+			if (names(args[i].slice("--extension=".length))) return true;
+			continue;
+		}
 		if (args[i] !== "-e" && args[i] !== "--extension") continue;
-		if (realpathish(path.resolve(base, args[i + 1])) === realpathish(PACKAGE_ROOT)) return true;
+		if (i + 1 < args.length && names(args[i + 1])) return true;
 		i++;
 	}
 	return false;
@@ -1199,7 +1235,7 @@ export function startPageServer(opts: PageServerOptions): Promise<PageServer> {
 		// whether that is this one, and the panel says "resume it" rather than promising a time.
 		// pi's own word first: before the first message there is no session file to read a header from,
 		// and the window's own plain job was marked as another session's.
-		const currentSession = sessionId || (child.sessionFile ? readHead(child.sessionFile)?.id : undefined);
+		const currentSession = sessionId || (child.sessionFile ? readSessionHead(child.sessionFile)?.id : undefined);
 		const jobsFile = readJson(path.join(LOOPS_DIR, "jobs.json"), { jobs: [] });
 		/**
 		 * This project's jobs, and the count of everything in other projects goes with it, because a
@@ -1221,8 +1257,8 @@ export function startPageServer(opts: PageServerOptions): Promise<PageServer> {
 			id: j.id,
 			name: j.name,
 			label: loopLabel({ id: String(j.id), name: typeof j.name === "string" ? j.name : undefined }),
-			// The terminal's words for it (src/schedule.ts): `every 1d` on both. A hand-written job may carry no schedule.
-			schedule: j.schedule && typeof j.schedule === "object" ? (formatSchedule(j.schedule) ?? "?") : "?",
+			// In words for the common cron shapes (src/schedule.ts scheduleWords). A hand-written job may carry no schedule.
+			schedule: j.schedule && typeof j.schedule === "object" ? (scheduleWords(j.schedule) ?? "?") : "?",
 			stateful: !!j.stateful,
 			enabled: !!j.enabled,
 			prompt: maskSecrets(j.prompt),
@@ -1471,8 +1507,8 @@ export function startPageServer(opts: PageServerOptions): Promise<PageServer> {
 		caughtUpAt.set(child, Date.now());
 		child
 			.swapSession(undefined, { restoreModel: true, reopen: true })
-			.then((answer: any) => opts.log(answer?.success ? `page: ${sessionId.slice(0, 8)} read again from disk; it is current` : `page: ${sessionId.slice(0, 8)} could not be read again: ${answer?.error ?? "no answer"}`))
-			.catch((err: any) => opts.log(`page: ${sessionId.slice(0, 8)} could not be read again: ${err?.message ?? err}`));
+			.then((answer: any) => opts.log(answer?.success ? `page: ${shortSessionId(sessionId)} read again from disk; it is current` : `page: ${shortSessionId(sessionId)} could not be read again: ${answer?.error ?? "no answer"}`))
+			.catch((err: any) => opts.log(`page: ${shortSessionId(sessionId)} could not be read again: ${err?.message ?? err}`));
 	}
 	/** When each page pi last tried to catch up, so one that stays aside is not reloaded on every poll. */
 	const caughtUpAt = new WeakMap<PageChild, number>();
@@ -1832,7 +1868,15 @@ export function startPageServer(opts: PageServerOptions): Promise<PageServer> {
 		const all = inbox.list();
 		const fresh = all.filter((e) => e.status === "new");
 		const cwd = cwdAsked || (here ? (leaseOf(here)?.cwd ?? conversationThere(here)?.cwd) : undefined) || undefined;
-		const scoped = (entries: InboxEntry[]) => (cwd ? inProject(entries, cwd, sameProject) : entries);
+		// Resolved on disk once per distinct cwd in this request, not once per finding: 2000 findings took
+		// about 24 ms a pass, for a handful of projects. `b` is always `cwd` here, so `a` is the key.
+		const matched = new Map<string, boolean>();
+		const sameAsked = (a: string, b: string) => {
+			let yes = matched.get(a);
+			if (yes === undefined) matched.set(a, (yes = sameProject(a, b)));
+			return yes;
+		};
+		const scoped = (entries: InboxEntry[]) => (cwd ? inProject(entries, cwd, sameAsked) : entries);
 		const queued = queuedClaims();
 		const jobs = jobNames();
 		const rules = new Map(objectsIn(readJson(path.join(LOOPS_DIR, "triggers.json"), { rules: [] }).rules).map((r) => [String(r.id), r.condition]));
@@ -2121,7 +2165,7 @@ export function startPageServer(opts: PageServerOptions): Promise<PageServer> {
 		// The time goes as a stamp: the page writes it in the browser's local time, as it does the rest of the row.
 		if (applied.op === "disable") return { status: 200, body: { ok: true, op: applied.op, line: "paused" } };
 		const next = applied.nextRun.kind === "at" ? { nextAt: stamp(applied.nextRun.at) } : applied.nextRun.kind === "due" ? { due: true } : {};
-		return { status: 200, body: { ok: true, op: applied.op, line: `now ${formatSchedule(after.schedule)}`, schedule: formatSchedule(after.schedule), ...next } };
+		return { status: 200, body: { ok: true, op: applied.op, line: `now ${scheduleWords(after.schedule)}`, schedule: scheduleWords(after.schedule), ...next } };
 	}
 
 	/**
@@ -2351,7 +2395,9 @@ export function startPageServer(opts: PageServerOptions): Promise<PageServer> {
 			secret = device.secret;
 			res.appendHeader("set-cookie", deviceCookie(device.id));
 		}
-		if (pathId === null) return void json(res, NO_SUCH, 404);
+		// A person opened this address: the answer is a page with a way back, never JSON.
+		const noSuch = () => plainPage(res, 404, '<p>No such conversation.</p><p><a href="/">Back</a></p>', { secret });
+		if (pathId === null) return void noSuch();
 
 		let sessionId = pathId ?? keyed;
 		if (sessionId === undefined) {
@@ -2381,8 +2427,8 @@ export function startPageServer(opts: PageServerOptions): Promise<PageServer> {
 				return void plainPage(res, 503, `<p>${escapeHtml(crashLine)}.</p>${words ? `<pre>${escapeHtml(words)}</pre>` : ""}<p><a href="/c/${encodeURIComponent(sessionId)}/?again=1">Start again</a></p>`, { secret });
 			}
 			// pi could not be started: every one of the page's six is busy, say. A person reads this.
-			if (opened.status === 503) return void plainPage(res, 503, `<p>${escapeHtml(opened.body.error)}.</p><p><a href="/">Back</a></p>`, { secret });
-			return void json(res, opened.body, opened.status);
+			if (opened.status === 404) return void noSuch();
+			return void plainPage(res, opened.status, `<p>${escapeHtml(opened.body.error)}.</p><p><a href="/">Back</a></p>`, { secret });
 		}
 		pool.touch(sessionId);
 		opts.rememberPage?.(sessionId);
@@ -2868,9 +2914,10 @@ export function startPageServer(opts: PageServerOptions): Promise<PageServer> {
 				if (route === "/session/new" && req.method === "POST") {
 					await snapshot(child);
 					const answer = await child.swapSession(child.newSessionPath());
-					// The pool re-keys the child to the new id and its pages are told, before this answers.
+					// The pool re-keys the child to the new id and its pages are told, before this answers. The
+					// answer carries the id too: the page moves on it before it reloads (src/web.mjs swap).
 					await snapshot(child);
-					return void json(res, answer);
+					return void json(res, { ...answer, sessionId: child.sessionId });
 				}
 				if (route === "/session/switch" && req.method === "POST") {
 					const { file } = await body(req);
@@ -2888,7 +2935,7 @@ export function startPageServer(opts: PageServerOptions): Promise<PageServer> {
 					// so a relative path would be checked here and opened somewhere else.
 					const answer = await child.swapSession(path.resolve(match.file), { restoreModel: true });
 					await snapshot(child);
-					return void json(res, answer);
+					return void json(res, { ...answer, sessionId: child.sessionId });
 				}
 				if (route === "/queue/clear" && req.method === "POST") {
 					// Everything "queued N ✕" counts: every input row, the person's and pi-loops', as each one's

package/src/path-precheck.ts

@@ -62,6 +62,8 @@ export function pathOnlyCondition(condition: string, at: { cwd: string; home: st
 	const token = pathToken(s);
 	if ("why" in token) return token;
 	const rest = token.rest.trim();
+	// No aside in parentheses is dropped: "exists (or ~/b appears)" is true while this path is absent,
+	// and no word list can tell such an aside from "(a build finished)". The model reads those.
 	const verbWhy = verbOnly(rest);
 	if (verbWhy) return { why: verbWhy };
 	const bad = badPath(token.path);

package/src/paths.ts

@@ -33,9 +33,12 @@ export function realpathish(p: string): string {
 	}
 }
 
-/** A root so broad that containment would mean "everything": never treated as one project. */
+/**
+ * A root so broad that containment would mean "everything": never treated as one project. `dir` is
+ * resolved, so `$HOME` is too: a HOME reached through a symlink is still HOME.
+ */
 function tooBroad(dir: string): boolean {
-	return dir === "/" || dir === os.homedir() || path.dirname(dir) === dir;
+	return dir === "/" || dir === realpathish(os.homedir()) || path.dirname(dir) === dir;
 }
 
 /** True when `p` is the project rooted at `root` or a directory inside it, symlinks resolved. */
@@ -55,3 +58,13 @@ export function withinProject(root: string, p: string): boolean {
 export function sameProject(a: string, b: string): boolean {
 	return withinProject(b, a) || withinProject(a, b);
 }
+
+/** pi's own normalisation: resolved, then through symlinks where the path exists. */
+export function canonicalDir(dir: string): string {
+	const resolved = path.resolve(dir);
+	try {
+		return fs.realpathSync(resolved);
+	} catch {
+		return resolved;
+	}
+}