pi-session-mail 0.1.0 → 0.2.0

package/{index.ts → src/index.ts}

@@ -23,10 +23,21 @@
 // `pi.events` (below).
 //
 // The hook contracts live in this package's README.
-import { type FSWatcher, watch } from "node:fs";
+import { type FSWatcher, statSync, watch } from "node:fs";
+import { dirname } from "node:path";
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { label, listRunning, removeRecord, resolveTo, type State, writeRecord } from "./running.ts";
+import {
+	isRunning,
+	label,
+	listRunning,
+	type RunningRecord,
+	removeRecord,
+	resolveTo,
+	type State,
+	writeRecord,
+} from "./running.ts";
+import { type SettleInput, settle } from "./settle.ts";
 import {
 	boxPath,
 	claim,
@@ -36,51 +47,45 @@ import {
 	findSent,
 	isAddress,
 	listNew,
+	pruneClosed,
 	readEnvelope,
 	type SentCopy,
 	send,
 } from "./store.ts";
-import { registerTools, type Tools } from "./tools.ts";
+import { readSettings, registerTools, type Tools } from "./tools.ts";
 
 const CUSTOM_TYPE = "mailbox";
 const STATUS_KEY = "mailbox";
+const DAY_MS = 24 * 60 * 60 * 1000;
 /** Fallback rescan interval; `fs.watch` on macOS drops and coalesces events. */
 const POLL_MS = 1000;
 /** Inbound bodies are cut at this many UTF-8 bytes. */
 const BODY_CAP = 32 * 1024;
 /** Each request quoted in a reply is cut at this many UTF-8 bytes. */
 const QUOTE_CAP = 2 * 1024;
-/** Reply body when the run ended with no assistant text. */
-const NO_ANSWER = "(The session settled with no answer text.)";
-/** Reply body of a run the user stopped, with any partial answer text after it. */
-const STOPPED = "(The user stopped this run before it finished; the text that follows, if any, is partial.)";
-/** Opening line of the reply body to a request held across a stop, before the answer of the run that completed it. */
-const TOOK_OVER =
-	"(The user stopped an earlier run partway and took over; the answer that follows is from the run that completed after that.)";
-/** Opening line of the reply body of a run that ended on an error. */
-const ERRORED = (error: string) =>
-	`(The run ended on an error before it finished: ${error}. The text that follows, if any, is partial.)`;
-/** Body of a `failed` reply to requests that never entered the conversation. */
-const UNSEEN =
-	"(The session was stopped before it read the message. Nothing was done; send it again if it is still needed.)";
-
 /** Cut `text` to at most `max` UTF-8 bytes on a character boundary; undefined when it already fits. */
 function cap(text: string, max: number): string | undefined {
-	const bytes = Buffer.from(text, "utf8");
-	if (bytes.length <= max) return undefined;
-	let end = max;
-	while (end > 0 && (bytes[end] & 0xc0) === 0x80) end--; // back off a split character
-	return bytes.subarray(0, end).toString("utf8");
+	// `encodeInto` stops before a character that does not fit, so the cut is on a boundary.
+	const { read } = new TextEncoder().encodeInto(text, new Uint8Array(max));
+	return read === text.length ? undefined : text.slice(0, read);
 }
 
+/**
+ * Text from outside this session (an id, a name, a working directory) with every
+ * control character (C0, DEL, C1) and the line and paragraph separators
+ * U+2028/U+2029 replaced by a space, so it cannot start a line of its own and
+ * pass for a `[mailbox]` line.
+ */
+const plain = (text: string): string => text.replace(/[\p{Cc}\u2028\u2029]/gu, " ");
+
 /** A reply quotes each request it answers: the id, the copy's path, then the capped body. */
 function quoteRequest(request: SentCopy): string {
 	const cut = cap(request.envelope.body, QUOTE_CAP);
 	const body =
 		cut === undefined
 			? request.envelope.body
-			: `${cut}\n[mailbox] Request cut at 2 KiB; the full copy is ${request.path}`;
-	return `[mailbox] Your request ${request.envelope.id}, quoted from ${request.path}:\n${body
+			: `${cut}\n[mailbox] Request cut at 2 KiB; the full copy is ${plain(request.path)}`;
+	return `[mailbox] Your request ${plain(request.envelope.id)}, quoted from ${plain(request.path)}:\n${body
 		.split("\n")
 		.map((line) => `> ${line}`)
 		.join("\n")}`;
@@ -93,10 +98,11 @@ function quoteRequest(request: SentCopy): string {
 function requestQuotes(me: string, ids: readonly string[]): { requests: SentCopy[]; quotes: string[] } {
 	const requests: SentCopy[] = [];
 	const quotes: string[] = [];
+	const copies = findSent(me, ids);
 	for (const id of ids) {
-		const copy = findSent(me, id);
+		const copy = copies.get(id);
 		if (copy === undefined) {
-			quotes.push(`[mailbox] Your request ${id} has no copy in sent/; only its id is known.`);
+			quotes.push(`[mailbox] Your request ${plain(id)} has no copy in sent/; only its id is known.`);
 			continue;
 		}
 		requests.push(copy);
@@ -111,10 +117,9 @@ function requestQuotes(me: string, ids: readonly string[]): { requests: SentCopy
  * directory. No distrust wording: with it, models refused every peer request
  * as a possible injection (spec Q37). Safety lives outside the model.
  */
-function senderLine(address: string): { line: string; name: string } {
-	const record = listRunning().find((r) => r.address === address);
-	const where = record === undefined ? "" : `, working in ${record.cwd}`;
-	const name = label(record ?? { address });
+function senderLine(address: string, record: RunningRecord | undefined): { line: string; name: string } {
+	const where = record === undefined ? "" : `, working in ${plain(record.cwd)}`;
+	const name = plain(label(record ?? { address }));
 	return { line: `[mailbox] From ${name} (${address}${where}), another Pi session on this machine.`, name };
 }
 
@@ -135,29 +140,30 @@ function inboundText(
 	path: string,
 	quotes: readonly string[],
 	opts: { lateAnswer: boolean; byUser: boolean },
+	senderRecord: RunningRecord | undefined,
 ): string {
 	const { lateAnswer, byUser } = opts;
-	const sender = senderLine(envelope.from);
+	const sender = senderLine(envelope.from, senderRecord);
+	const id = plain(envelope.id);
+	const replyIds = envelope.in_reply_to.map(plain);
 	const header = [sender.line];
 	if (envelope.kind === "request") header.push("Your final answer this turn goes back to it automatically.");
 	if (envelope.kind === "ask")
 		header.push(
-			`It is waiting for your answer to its ask ${envelope.id}. Answer with session_mail_reply (ask ${envelope.id}); otherwise this run's last message is sent as the answer.`,
+			`It is waiting for your answer to its ask ${id}. Answer with session_mail_reply (ask ${id}); otherwise this run's last message is sent as the answer.`,
 		);
 	if (lateAnswer) header.push("It answers an ask of yours that has stopped waiting, so it arrives as a message.");
 	if (envelope.kind === "message")
 		header.push(`It expects no answer; if one is wanted, send it with session_mail_send to ${envelope.from}.`);
 	if (envelope.in_reply_to.length > 0)
-		header.push(
-			`It is a reply to your request${envelope.in_reply_to.length > 1 ? "s" : ""} ${envelope.in_reply_to.join(", ")}.`,
-		);
+		header.push(`It is a reply to your request${envelope.in_reply_to.length > 1 ? "s" : ""} ${replyIds.join(", ")}.`);
 	if (byUser)
 		header.push("The user made that request, typing it with /mailbox or through an extension such as delegate.");
 	if (envelope.in_reply_to.length > 0 && envelope.status !== "done")
-		header.push(`Its status is "${envelope.status}", not "done": it is not an answer.`);
+		header.push(`Its status is "${plain(String(envelope.status))}", not "done": it is not an answer.`);
 	const cut = cap(envelope.body, BODY_CAP);
 	const body =
-		cut === undefined ? envelope.body : `${cut}\n\n[mailbox] Body cut at 32 KiB; the full envelope is ${path}`;
+		cut === undefined ? envelope.body : `${cut}\n\n[mailbox] Body cut at 32 KiB; the full envelope is ${plain(path)}`;
 	return [header.join(" "), ...quotes, body, endLine(sender.name)].join("\n\n");
 }
 
@@ -166,8 +172,9 @@ function inboundText(
  * synchronous code before `emit` returns; do all work before any `await`.
  *
  * - `message:send`: the caller emits `{ to, body }`; `pi-session-mail` writes a
- *   request and sets `envelope` (or `error`) on the same object. Neither set
- *   means no provider is installed.
+ *   request, stamped with the run's hop count during a run and 0 when idle,
+ *   and sets `envelope` (or `error`) on the same object. Neither set means no
+ *   provider is installed.
  * - `message:inbound`: emitted for every claimed envelope, requests and
  *   replies alike, before injection; `requests` holds a reply's request
  *   copies from this session's `sent/`, and a listener sets `handled` to show
@@ -185,22 +192,15 @@ type Message = { role?: string; content?: unknown; stopReason?: unknown; errorMe
 
 /** The last assistant message in a run's transcript, if any. */
 function lastAssistant(messages: readonly unknown[]): Message | undefined {
-	for (let i = messages.length - 1; i >= 0; i--) {
-		const message = messages[i] as Message;
-		if (message?.role === "assistant") return message;
-	}
-	return undefined;
+	return (messages as Message[]).findLast((message) => message?.role === "assistant");
 }
 
 /** The text of the last assistant message that has any; undefined when none has. */
 function lastAssistantText(messages: readonly unknown[]): string | undefined {
-	for (let i = messages.length - 1; i >= 0; i--) {
-		const message = messages[i] as Message;
-		if (message?.role !== "assistant") continue;
-		const text = assistantText(message);
-		if (text !== undefined) return text;
-	}
-	return undefined;
+	const message = (messages as Message[]).findLast(
+		(candidate) => candidate?.role === "assistant" && assistantText(candidate) !== undefined,
+	);
+	return message === undefined ? undefined : assistantText(message);
 }
 
 /** The text of an assistant message; undefined when it has none. */
@@ -227,12 +227,8 @@ export default function mailbox(pi: ExtensionAPI) {
 	let timer: ReturnType<typeof setInterval> | undefined;
 	/** Envelope ids already handed to Pi in this process. */
 	const delivered = new Set<string>();
-	/** The kind of each envelope this session has claimed, by id, so a reply can say why it is refused. */
-	const receivedKinds = new Map<string, Envelope["kind"]>();
 	/** Request ids awaiting this session's reply, keyed by sender. In memory only. */
 	let owed = new Map<string, string[]>();
-	/** Ask ids awaiting this session's answer, keyed by sender; answered apart from requests. */
-	let owedAsks = new Map<string, string[]>();
 	/** Owed request ids whose message entered the conversation (or a listener took over). */
 	let seen = new Set<string>();
 	/**
@@ -254,8 +250,8 @@ export default function mailbox(pi: ExtensionAPI) {
 	 * steered into it. Mail sent from the turn carries it.
 	 */
 	let hops = 0;
-	/** Whether this session has already warned about a broken `session-mail.json`. */
-	let configWarned = false;
+	/** The problems with `session-mail.json` this session has already warned about. */
+	let configWarned = new Set<string>();
 	/** What this session's running-session record says. */
 	let name: string | undefined;
 	let cwd = "";
@@ -285,6 +281,19 @@ export default function mailbox(pi: ExtensionAPI) {
 
 	const warn = (message: string) => ctx?.ui.notify(`mailbox: ${message}`, "warning");
 
+	/** The address folder is left as found; tell the user how to tighten it. */
+	function warnIfLoose(me: string) {
+		const folder = dirname(boxPath(me, "new"));
+		let mode: number;
+		try {
+			mode = statSync(folder).mode & 0o777;
+		} catch {
+			return;
+		}
+		if ((mode & 0o077) === 0) return;
+		warn(`${folder} is mode ${mode.toString(8)}, open to other users; run: chmod 700 ${folder}`);
+	}
+
 	/** Footer entry `✉ N pending · N read · N awaiting`, non-zero parts only; hidden when all are zero. */
 	function updateStatus() {
 		if (!ctx?.hasUI || address === undefined) return;
@@ -315,7 +324,7 @@ export default function mailbox(pi: ExtensionAPI) {
 
 	function deliver(me: string, envelope: Envelope, path: string) {
 		delivered.add(envelope.id);
-		receivedKinds.set(envelope.id, envelope.kind);
+		tools?.recordKind(envelope);
 		// The answer to a waiting ask is that tool call's result, and nothing else.
 		if (tools?.takeAnswer(envelope)) return;
 		const { requests, quotes } = requestQuotes(me, envelope.in_reply_to);
@@ -329,7 +338,7 @@ export default function mailbox(pi: ExtensionAPI) {
 		// Only requests arm an answer: replies are never answered, and messages
 		// expect none. A request arms one even when a listener took over its display.
 		if (envelope.kind === "request") owed.set(envelope.from, [...(owed.get(envelope.from) ?? []), envelope.id]);
-		if (envelope.kind === "ask") owedAsks.set(envelope.from, [...(owedAsks.get(envelope.from) ?? []), envelope.id]);
+		tools?.armAsk(envelope);
 		// Mail that wakes or steers the session raises its count; a reply shown
 		// quietly starts no turn, but one a listener took over may.
 		if (wakes || inbound.handled) hops = Math.max(hops, envelope.hops + 1);
@@ -342,7 +351,13 @@ export default function mailbox(pi: ExtensionAPI) {
 		pi.sendMessage(
 			{
 				customType: CUSTOM_TYPE,
-				content: inboundText(envelope, path, quotes, { lateAnswer, byUser }),
+				content: inboundText(
+					envelope,
+					path,
+					quotes,
+					{ lateAnswer, byUser },
+					listRunning().find((r) => r.address === envelope.from),
+				),
 				display: true,
 				details: { id: envelope.id },
 			},
@@ -382,8 +397,11 @@ export default function mailbox(pi: ExtensionAPI) {
 		try {
 			if (address === undefined) throw new Error("no active session has a mailbox address");
 			if (typeof payload.body !== "string") throw new Error("body must be a string");
-			// A `message:send` caller acts for the user, so its request starts a fresh chain.
-			payload.envelope = send(address, payload.to as string, payload.body, { kind: "request", hops: 0 });
+			// During a run the caller is the model acting through an extension, so the
+			// request continues the run's chain; idle, it acts for the user and starts a
+			// fresh one. It is never refused here: the receiving side enforces the limit.
+			const hopsNow = state === "busy" ? hops : 0;
+			payload.envelope = send(address, payload.to as string, payload.body, { kind: "request", hops: hopsNow });
 			updateStatus();
 		} catch (err) {
 			payload.error = (err as Error).message;
@@ -399,11 +417,27 @@ export default function mailbox(pi: ExtensionAPI) {
 		payload.scanned = true;
 	});
 
+	/** Warn about a problem with `session-mail.json`, once per session. */
+	function configProblem(message: string) {
+		if (configWarned.has(message)) return;
+		configWarned.add(message);
+		warn(message);
+	}
+
+	/** Remove closed sessions' folders that are older than `pruneAfterDays`; a failure warns and never throws. */
+	function pruneOld(me: string) {
+		try {
+			const { pruneAfterDays } = readSettings(configProblem);
+			pruneClosed({ own: me, isRunning, cutoffMs: Date.now() - pruneAfterDays * DAY_MS });
+		} catch (err) {
+			warn(`could not prune old mailbox folders: ${(err as Error).message}`);
+		}
+	}
+
 	pi.on("session_start", async (_event, context) => {
 		stop();
 		ctx = context;
 		owed = new Map();
-		owedAsks = new Map();
 		seen = new Set();
 		held = new Set();
 		lastAnswer = undefined;
@@ -413,15 +447,25 @@ export default function mailbox(pi: ExtensionAPI) {
 		hops = 0;
 		tools?.abandonAsk();
 		waitingOn = "";
-		configWarned = false;
+		configWarned = new Set();
 		const id = context.sessionManager.getSessionId();
 		if (!isAddress(id)) {
 			address = undefined;
+			tools?.setAddress(undefined);
 			warn(`session id ${JSON.stringify(id)} is not a usable address; the mailbox is off`);
 			return;
 		}
+		try {
+			ensureBoxes(id);
+		} catch (err) {
+			address = undefined;
+			tools?.setAddress(undefined);
+			warn(`mailbox is off: ${(err as Error).message}`);
+			return;
+		}
 		address = id;
-		ensureBoxes(id);
+		tools?.setAddress(id);
+		warnIfLoose(id);
 		name = context.sessionManager.getSessionName?.() || undefined;
 		cwd = context.cwd;
 		state = context.isIdle?.() === false ? "busy" : "idle";
@@ -435,6 +479,7 @@ export default function mailbox(pi: ExtensionAPI) {
 		pendingScan = setImmediate(() => {
 			pendingScan = undefined;
 			scan();
+			pruneOld(id);
 		});
 		pendingScan.unref?.();
 		try {
@@ -499,52 +544,25 @@ export default function mailbox(pi: ExtensionAPI) {
 	// queued follow-up after `agent_end` would otherwise get a premature answer.
 	pi.on("agent_settled", async () => {
 		const me = address;
-		// A stopped or errored run notes how it ended, then gives what it had.
-		const opening = lastAborted ? STOPPED : lastError !== undefined ? ERRORED(lastError) : undefined;
-		const body =
-			opening === undefined
-				? (lastAnswer ?? NO_ANSWER)
-				: lastAnswer === undefined
-					? opening
-					: `${opening}\n\n${lastAnswer}`;
-		const status = lastAborted ? "stopped" : lastError !== undefined ? "failed" : "done";
-		// A request held across a stop is answered by the run that completes it, saying the user took over.
-		const tookOverBody = `${TOOK_OVER}\n\n${lastAnswer ?? NO_ANSWER}`;
 		// Answers carry the settled turn's count; the next turn counts afresh.
 		const answerHops = hops;
 		hops = 0;
-		// A request the user stopped a run on is the user's to finish, not an
-		// answer yet: it stays owed, through stops and failed runs alike, until a
-		// run completes. Asks are never held; their asker is blocked waiting.
-		const requests = [...owed];
-		const asks = [...owedAsks];
-		const read = seen;
-		const wasHeld = held;
-		owed = new Map();
-		owedAsks = new Map();
+		const end: SettleInput["end"] = lastAborted
+			? { kind: "stopped" }
+			: lastError !== undefined
+				? { kind: "failed", error: lastError }
+				: { kind: "done" };
+		const decision = settle({
+			requests: owed,
+			asks: tools?.takeOwedAsks() ?? new Map(),
+			seen,
+			held,
+			end,
+			answer: lastAnswer,
+		});
+		owed = decision.owed;
+		held = decision.held;
 		seen = new Set();
-		held = new Set();
-		const replies: { to: string; ids: string[]; body: string; status: Envelope["status"] }[] = [];
-		for (const [to, ids] of requests) {
-			const unseen = ids.filter((id) => !read.has(id) && !wasHeld.has(id));
-			const keep = ids.filter(
-				(id) => !unseen.includes(id) && (lastAborted || (lastError !== undefined && wasHeld.has(id))),
-			);
-			const answer = ids.filter((id) => !unseen.includes(id) && !keep.includes(id));
-			if (keep.length > 0) owed.set(to, keep);
-			for (const id of keep) held.add(id);
-			const plain = answer.filter((id) => !wasHeld.has(id));
-			const tookOver = answer.filter((id) => wasHeld.has(id));
-			if (plain.length > 0) replies.push({ to, ids: plain, body, status });
-			if (tookOver.length > 0) replies.push({ to, ids: tookOver, body: tookOverBody, status: "done" });
-			if (unseen.length > 0) replies.push({ to, ids: unseen, body: UNSEEN, status: "failed" });
-		}
-		for (const [to, ids] of asks) {
-			const done = ids.filter((id) => read.has(id));
-			const failed = ids.filter((id) => !read.has(id));
-			if (done.length > 0) replies.push({ to, ids: done, body, status });
-			if (failed.length > 0) replies.push({ to, ids: failed, body: UNSEEN, status: "failed" });
-		}
 		lastAnswer = undefined;
 		lastAborted = false;
 		lastError = undefined;
@@ -552,7 +570,7 @@ export default function mailbox(pi: ExtensionAPI) {
 		state = "idle";
 		announce();
 		if (me === undefined) return;
-		for (const reply of replies) {
+		for (const reply of decision.replies) {
 			const { to } = reply;
 			try {
 				// Answers are never refused by the hop limit.
@@ -575,6 +593,7 @@ export default function mailbox(pi: ExtensionAPI) {
 			}
 		}
 		address = undefined;
+		tools?.setAddress(undefined);
 	});
 
 	tools = registerTools(pi, {
@@ -583,36 +602,13 @@ export default function mailbox(pi: ExtensionAPI) {
 			waitingOn = to;
 			announce();
 		},
-		reply: (id, body) => {
-			const me = address;
-			if (me === undefined) throw new Error("this session has no mailbox address; nothing was sent");
-			const kind = receivedKinds.get(id);
-			if (kind === undefined)
-				throw new Error(`no mail with id ${JSON.stringify(id)} reached this session; nothing was sent`);
-			if (kind !== "ask")
-				throw new Error(
-					`${id} is a ${kind}, not an ask; nothing was sent. ${kind === "request" ? "A request is answered automatically when this run settles." : kind === "message" ? "A message expects no answer; session_mail_send sends one if it is wanted." : "A reply is never answered."}`,
-				);
-			const from = [...owedAsks].find(([, ids]) => ids.includes(id))?.[0];
-			// An answered ask, by this tool or at settle, is no longer owed.
-			if (from === undefined) throw new Error(`ask ${id} is already answered; nothing was sent`);
-			// Answers carry the turn's count and are never refused by the hop limit.
-			const answer = send(me, from, body, { kind: "reply", hops, inReplyTo: [id], status: "done" });
-			const rest = (owedAsks.get(from) ?? []).filter((owedId) => owedId !== id);
-			if (rest.length > 0) owedAsks.set(from, rest);
-			else owedAsks.delete(from);
-			return answer;
-		},
 		hops: () => hops,
-		configProblem: (message) => {
-			if (configWarned) return;
-			configWarned = true;
-			warn(message);
-		},
+		configProblem,
 	});
 
 	pi.registerCommand("mailbox", {
-		description: "Show this session's mailbox address and name, or send a request: /mailbox <name or id> <text>",
+		description:
+			"Show this session's mailbox address and name, send a request: /mailbox <name or id> <text>, or remove closed sessions' empty mailbox folders: /mailbox prune",
 		handler: async (args, context) => {
 			const me = context.sessionManager.getSessionId();
 			const trimmed = args.trim();
@@ -624,6 +620,15 @@ export default function mailbox(pi: ExtensionAPI) {
 				);
 				return;
 			}
+			if (trimmed === "prune") {
+				try {
+					const removed = pruneClosed({ own: me, isRunning });
+					context.ui.notify(`Removed ${removed} mailbox folders of closed sessions`, "info");
+				} catch (err) {
+					context.ui.notify(`mailbox: ${(err as Error).message}`, "error");
+				}
+				return;
+			}
 			const match = /^(\S+)\s+([\s\S]+)$/.exec(trimmed);
 			if (!match) {
 				context.ui.notify("Usage: /mailbox <name or id> <text>", "error");

package/{running.ts → src/running.ts}

@@ -1,11 +1,14 @@
 // Running-session records and `to` resolution. Internal to `pi-session-mail`: tests
-// reach it only through the extension's registration function.
+// reach it through the extension's registration function, apart from the start-token
+// probe and its parsers, which `test/start-token.test.ts` tests directly.
 //
 // Each running session announces itself in `<root>/running/<address>.json`:
 // its address, Pi session name, working directory, process id, idle or busy,
 // the address it waits on, and when the record last changed. A record whose
-// process is gone counts as not running, and the reader that finds it deletes
-// it. The root is the mail root, so every agent directory sees every session.
+// process is gone, or whose pid now belongs to a process that started at
+// another time, counts as not running, and the reader that finds it deletes it.
+// The root is the mail root, so every agent directory sees every session.
+import { execFileSync } from "node:child_process";
 import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
@@ -19,6 +22,11 @@ export type RunningRecord = {
 	name?: string;
 	cwd: string;
 	pid: number;
+	/**
+	 * An opaque token for the process's start time, so a reused pid is told from the
+	 * original process. Absent in records written by 0.1.0 and where no probe works.
+	 */
+	started?: string;
 	state: State;
 	/** The address this session's pending ask waits on; empty when none. */
 	waitingOn: string;
@@ -27,12 +35,14 @@ export type RunningRecord = {
 };
 
 /** How many leading characters of a session id name it in lists and errors. */
-export const SHORT_ID = 8;
+const SHORT_ID = 8;
 
-export const shortId = (address: string) => address.slice(0, SHORT_ID);
+const shortId = (address: string) => address.slice(0, SHORT_ID);
 
 /** A record's display label: its session name, or its short id when it has none. */
-export const label = (record: Pick<RunningRecord, "address" | "name">) => record.name ?? shortId(record.address);
+export function label(record: Pick<RunningRecord, "address" | "name">): string {
+	return record.name ?? shortId(record.address);
+}
 
 const runningDir = () => join(mailRoot(), "running");
 
@@ -41,8 +51,78 @@ const recordPath = (address: string) => {
 	return join(runningDir(), `${address}.json`);
 };
 
-/** Write `record` owner-only, through a temporary file so a reader never sees half of it. */
-export function writeRecord(record: RunningRecord): void {
+/**
+ * The start-time token in a `/proc/<pid>/stat` line: field 22. The command name
+ * (field 2) is in parentheses and may itself hold spaces and parentheses, so
+ * the fields are counted from the last `)`.
+ */
+export function parseProcStat(line: string): string | undefined {
+	const rest = line.slice(line.lastIndexOf(")") + 1).trim();
+	if (rest === "" || !line.includes(")")) return undefined;
+	const token = rest.split(/\s+/)[19]; // field 3 is the first after the name
+	return token !== undefined && /^\d+$/.test(token) ? token : undefined;
+}
+
+/** Parse `ps -o pid=,lstart=` output into a pid -> start token map; unparseable lines are skipped. */
+export function parsePsStarts(output: string): Map<number, string> {
+	const out = new Map<number, string>();
+	for (const line of output.split("\n")) {
+		const match = /^\s*(\d+)\s+(\S.*?)\s*$/.exec(line);
+		if (match !== null) out.set(Number(match[1]), match[2]);
+	}
+	return out;
+}
+
+/**
+ * The start tokens of `pids`, for those the probe could read. Linux reads
+ * `/proc`; macOS runs one `ps` for all of them, in UTC and the C locale so
+ * every session renders a start time the same way; elsewhere, or on any error,
+ * the result lacks the pid, which callers treat as unknown.
+ */
+export function startTokens(pids: readonly number[]): Map<number, string> {
+	const out = new Map<number, string>();
+	if (pids.length === 0) return out;
+	if (process.platform === "linux") {
+		for (const pid of pids) {
+			try {
+				const token = parseProcStat(readFileSync(`/proc/${pid}/stat`, "utf8"));
+				if (token !== undefined) out.set(pid, token);
+			} catch {}
+		}
+	} else if (process.platform === "darwin") {
+		let stdout = "";
+		try {
+			stdout = execFileSync("ps", ["-o", "pid=,lstart=", "-p", pids.join(",")], {
+				encoding: "utf8",
+				timeout: 2000,
+				stdio: ["ignore", "pipe", "ignore"],
+				env: { ...process.env, LC_ALL: "C", TZ: "UTC" },
+			});
+		} catch (err) {
+			// ps exits 1 when some pid is gone but still prints the others.
+			const partial = (err as { stdout?: unknown }).stdout;
+			if (typeof partial === "string") stdout = partial;
+		}
+		for (const [pid, token] of parsePsStarts(stdout)) out.set(pid, token);
+	}
+	return out;
+}
+
+let ownToken: { value: string | undefined } | undefined;
+
+/** This process's start token, probed once; undefined when it cannot be read. */
+function ownStartToken(): string | undefined {
+	ownToken ??= { value: startTokens([process.pid]).get(process.pid) };
+	return ownToken.value;
+}
+
+/**
+ * Write `record` owner-only, through a temporary file so a reader never sees half of it.
+ * A record for this process gets this process's start token.
+ */
+export function writeRecord(given: RunningRecord): void {
+	const started = given.pid === process.pid && given.started === undefined ? ownStartToken() : undefined;
+	const record = started === undefined ? given : { ...given, started };
 	mkdirSync(runningDir(), { recursive: true, mode: 0o700 });
 	const path = recordPath(record.address);
 	const tmp = `${path}.${process.pid}.tmp`;
@@ -79,6 +159,7 @@ function readRecord(path: string): RunningRecord | undefined {
 			...(typeof value.name === "string" && value.name !== "" ? { name: value.name } : {}),
 			cwd: value.cwd,
 			pid: value.pid,
+			...(typeof value.started === "string" && value.started !== "" ? { started: value.started } : {}),
 			state: value.state === "busy" ? "busy" : "idle",
 			waitingOn: typeof value.waitingOn === "string" ? value.waitingOn : "",
 			updated: typeof value.updated === "string" ? value.updated : "",
@@ -88,6 +169,24 @@ function readRecord(path: string): RunningRecord | undefined {
 	}
 }
 
+/**
+ * Whether `address` has a live running record, read fresh from its one file. The
+ * rules are `listRunning`'s: the pid is alive and, when both tokens are known,
+ * the start token matches. A missing or unreadable record is not running; a
+ * failed probe falls back to the pid alone. Never throws and deletes nothing.
+ */
+export function isRunning(address: string): boolean {
+	try {
+		const record = readRecord(recordPath(address));
+		if (record === undefined || record.address !== address || !alive(record.pid)) return false;
+		if (record.started === undefined) return true;
+		const live = startTokens([record.pid]).get(record.pid);
+		return live === undefined || live === record.started;
+	} catch {
+		return false;
+	}
+}
+
 /** Every running session's record, sorted by label; records of dead processes are deleted. */
 export function listRunning(): RunningRecord[] {
 	let names: string[];
@@ -96,12 +195,21 @@ export function listRunning(): RunningRecord[] {
 	} catch {
 		return [];
 	}
-	const out: RunningRecord[] = [];
+	const found: { path: string; record: RunningRecord }[] = [];
 	for (const name of names) {
 		const path = join(runningDir(), name);
 		const record = readRecord(path);
 		if (record === undefined || `${record.address}.json` !== name) continue; // not ours to judge or delete
-		if (!alive(record.pid)) {
+		found.push({ path, record });
+	}
+	const tokens = startTokens(
+		found.filter(({ record }) => record.started !== undefined && alive(record.pid)).map(({ record }) => record.pid),
+	);
+	const out: RunningRecord[] = [];
+	for (const { path, record } of found) {
+		const live = tokens.get(record.pid);
+		// A token we cannot read is unknown, which falls back to the pid-only check.
+		if (!alive(record.pid) || (record.started !== undefined && live !== undefined && live !== record.started)) {
 			rmSync(path, { force: true });
 			continue;
 		}