pi-session-mail 0.2.2 → 0.4.0

package/CHANGELOG.md

@@ -6,6 +6,64 @@ follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-10-20
+
+### Added
+
+- Bare `/mailbox` opens a picker of this session's mail. Its title carries the
+  session's name (or short id) and short address, Tab cycles unread, awaiting,
+  read, sent and all (Shift+Tab goes back), and each row shows the first line, the other session, the
+  kind and a relative time, with the status in the all and sent views and the
+  running or closed marker on awaiting rows. Enter opens the whole mail and Esc
+  goes back, then closes. It opens on unread when there is unread mail, and
+  showing mail never marks it read.
+- In the `/mailbox` picker, `d` deletes the selected read or sent item, or
+  drops a request still awaiting a reply, after a confirmation showing its
+  first line. Deleting a read reply also deletes the `sent/` copies of the
+  requests it answered, so they do not reappear as awaiting. The picker reopens
+  on the same filter with the next row selected, or the same row when the
+  confirmation was cancelled. Unread mail cannot be deleted, and the hint line
+  leaves `d` out there.
+- `/mailbox:send` lists the other running sessions, asks for the text and
+  sends it as a message, which expects no answer.
+- `/mailbox:prune` removes closed sessions' mailbox folders without the age
+  limit.
+
+### Changed
+
+- Bare `/mailbox` no longer prints the address and name notice; the picker's
+  title carries them. Its tests now open the picker and assert the title.
+- The footer shows only `📬 N unread`: mail that reached this session but has
+  not entered its conversation yet. It clears as each message enters, not when
+  the run settles. The `read` and `awaiting` counts are gone from it, because
+  `read` only grew and `awaiting` stayed up for requests a stopped session
+  still held. The status tests now pin the new footer.
+
+### Removed
+
+- The typed `/mailbox <to> <text>` and `/mailbox prune` forms (breaking).
+  `/mailbox:send` and `/mailbox:prune` replace them, and any argument to
+  `/mailbox` now shows a usage notice naming the two new commands. The tests
+  of the typed send changed deliberately: delivery tests now use a harness
+  helper that sends a request with hops 0 through `send()`, and tests of name
+  and id resolution moved to `session_mail_send`.
+
+## [0.3.0] - 2026-10-19
+
+### Added
+
+- `session_mail_list`, `session_mail_send`, `session_mail_ask` and
+  `session_mail_reply` declare an `outputSchema` and return matching
+  `structuredContent`, so a codemode script gets objects instead of text:
+  `{ sessions: [{ id, name?, cwd, state, waitingOn?, self }] }` from the list,
+  `{ id, to, running }` from a send, `{ id, to, outcome, status?, body? }`
+  from an ask (one variant per `outcome`: `answered`, `timed-out`,
+  `stopped-running`, `stopped-by-user`) and `{ id, ask, to }` from a reply.
+  The text the model sees is unchanged.
+- The four tools declare all four MCP tool annotations: the list is read-only
+  and idempotent; send, ask and reply are not read-only and not destructive;
+  reply is idempotent, since a repeat is refused; none reaches an open world.
+
 ## [0.2.2] - 2026-10-02
 
 ### Fixed
@@ -118,7 +176,9 @@ author's dotfiles; the changes below are against that copy.
 - CI on Node 22.19 and 24: lint, typecheck, tests, and a check of the
   published file list.
 
-[Unreleased]: https://github.com/gvanderclay/pi-session-mail/compare/v0.2.2...HEAD
+[Unreleased]: https://github.com/gvanderclay/pi-session-mail/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/gvanderclay/pi-session-mail/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/gvanderclay/pi-session-mail/compare/v0.2.2...v0.3.0
 [0.2.2]: https://github.com/gvanderclay/pi-session-mail/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/gvanderclay/pi-session-mail/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/gvanderclay/pi-session-mail/compare/v0.1.0...v0.2.0

package/README.md

@@ -2,11 +2,11 @@
 
 A file mailbox between Pi sessions on the same machine.
 
-Each Pi session gets an address and an inbox. You send a request to another
-running session with `/mailbox`, and the model lists, asks, answers and sends
-through four `session_mail_*` tools. Mail waits on disk until the recipient
-starts or resumes, and the recipient's final answer goes back to the sender
-automatically.
+Each Pi session gets an address and an inbox. You send a message to another
+running session with `/mailbox:send`, and the model lists, asks, answers and
+sends through four `session_mail_*` tools. Mail waits on disk until the
+recipient starts or resumes, and the recipient's final answer goes back to the
+sender automatically.
 
 ## Install
 
@@ -27,28 +27,46 @@ pi install git:github.com/gvanderclay/pi-session-mail
 
 ## First use
 
-In a Pi session, show its address and name:
+In a Pi session, open a picker of this session's mail:
 
 ```text
 /mailbox
 ```
 
+Its title names the session, its short address and the filter. The picker opens
+on unread when there is unread mail, and on all otherwise. Tab cycles the filter
+through unread, awaiting, read, sent and all, and Shift+Tab goes back. Each row shows the first line of
+the mail, the other session (`from` for mail it received, `to` for mail it
+sent), the kind and how long ago it was sent; the all and sent views also show
+its status, and an awaiting row says whether its target is still running or
+has closed. Enter opens the whole mail: the other session's name and full
+address, the kind, the id, the absolute time, what it answers and the full
+text. Esc goes back to the list, and Esc there closes the picker. `d` deletes
+the selected read or sent item, or drops a request still awaiting a reply,
+after a confirmation showing its first line; deleting a read reply also deletes
+the `sent/` copies of the requests it answered. The picker reopens on the same
+filter with the row that took the deleted one's place selected. `d` is left out
+on unread mail. Showing mail never marks it read, so the footer's count stays
+until the model sees it.
+
 The session's id is its address. Other sessions see its Pi session name (set it
 with `/name`), or the first 8 characters of its id when it has none.
 
-In another session, send a request to that name or to an id prefix of at least
-8 characters:
+In another session, send a message by picking a running session from a list
+and then typing the text:
 
 ```text
-/mailbox <to> <text>
+/mailbox:send
 ```
 
-The sender sees `Sent <id> to <address>`. The recipient's model receives the
-text and works on it, and its last answer comes back to the sender as a reply
-when that run settles. [Addressing](#addressing) lists how `<to>` resolves.
+The sender sees `Sent <id> to <address>`. A message wakes the recipient's model
+and expects no answer. The model sends requests, asks and answers through the
+`session_mail_*` tools, and a request's last answer comes back to the sender as
+a reply when that run settles.
 
-The footer shows `✉ N pending · N read · N awaiting`, non-zero counts only.
-`awaiting` counts requests and asks with no answer yet, never messages.
+The footer shows `📬 N unread` while mail has reached this session but not yet
+entered its conversation, such as mail queued behind a busy run; it is hidden
+at zero.
 
 ## How mail works
 
@@ -119,7 +137,7 @@ The model gets four tools:
 
 ## Addressing
 
-A `to`, typed after `/mailbox` or given to a tool, resolves as follows:
+A `to` given to a tool resolves as follows:
 
 1. A running session's address, or any full session id (a UUID), resolves as
    given, so a closed session is still reached by its full id and its mail
@@ -137,9 +155,9 @@ A `to`, typed after `/mailbox` or given to a tool, resolves as follows:
 
 | Kind | Written by | Delivered as | Answered |
 | --- | --- | --- | --- |
-| `request` | `/mailbox <to> <text>`, `message:send` | `triggerTurn`, `deliverAs: "steer"` | yes, when a run completes; held while the user has taken over |
+| `request` | `message:send` | `triggerTurn`, `deliverAs: "steer"` | yes, when a run completes; held while the user has taken over |
 | `ask` | `session_mail_ask` | `triggerTurn`, `deliverAs: "steer"` | yes, when the run settles |
-| `message` | `session_mail_send` | `triggerTurn`, `deliverAs: "steer"` | never |
+| `message` | `session_mail_send`, `/mailbox:send` | `triggerTurn`, `deliverAs: "steer"` | never |
 | `reply` | the answering session | `deliverAs: "followUp"`, no turn; see below for answers to asks | never |
 
 Mail for the model wakes an idle session, and reaches a busy one at its next
@@ -169,8 +187,8 @@ label depends on the kind:
   `session_mail_send` to the sender's full id sends it.
 - A reply's label names the requests it answers and, when its status is not
   `done`, says it is not an answer. A reply to a request also says the user
-  made that request, typing it with `/mailbox` or through an extension such as
-  `delegate`, since only the user makes requests.
+  made that request through an extension such as `delegate`, since only the
+  user makes requests.
 
 The label is built from fields any process running as you can write: the
 envelope's `id`, `status` and the ids in `in_reply_to`, and the sender's name
@@ -249,11 +267,10 @@ are refused before anything is written once the count has reached the limit (5
 unless `session-mail.json` says otherwise; see
 [Configuration](#configuration)). The refusal says that a person typing in
 either session starts the count again. Automatic answers carry the count and
-are never refused. Requests from `/mailbox` carry 0 and are never refused:
-their sender acts for the user. A `message:send` emitted while the session is
-idle carries 0 too. One emitted during a run carries that run's count and is
-not refused at send time; the session that receives it counts it like any
-other mail, so a chain that reaches the limit is refused there as a loop.
+are never refused. A `message:send` is never refused at send time: its consumer
+acts for the user. Emitted while the session is idle it carries 0; during a run
+it carries that run's count, and the session that receives it counts it like
+any other mail, so a chain that reaches the limit is refused there as a loop.
 The limit is a loop guard, not a security boundary: a hand-written envelope
 can claim any `hops`.
 
@@ -272,11 +289,10 @@ copies of sent requests in `sent/` go too, not only the empty `new/`. Only real
 folders named like an address are considered; `running/`, symlinks and other
 names are left alone. The work runs after `session_start` returns.
 
-To clean up at once, type `/mailbox prune`. It applies the same rules without
+To clean up at once, type `/mailbox:prune`. It applies the same rules without
 the age limit, so it removes the folder (with its `cur/` and `sent/`) of every
 closed session with no unread mail, including one that closed a minute ago. It
 reports `Removed <N> mailbox folders of closed sessions`.
-`/mailbox prune <text>` is still a message to a session named `prune`.
 
 ## Configuration
 
@@ -462,7 +478,8 @@ root, and other extensions depend on its hooks, so these are stable:
   and a reply's statuses (`done`, `stopped`, `failed`); see
   [Envelopes](#envelopes).
 - The names of the tools (`session_mail_list`, `session_mail_send`,
-  `session_mail_ask`, `session_mail_reply`) and of the `/mailbox` command.
+  `session_mail_ask`, `session_mail_reply`) and of the `/mailbox`,
+  `/mailbox:send` and `/mailbox:prune` commands.
 - The keys of `session-mail.json`, today `hopLimit` and `pruneAfterDays`.
 
 Changing any of them needs a major version from 1.0 on, and a minor version

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-session-mail",
-	"version": "0.2.2",
+	"version": "0.4.0",
 	"description": "A file mailbox between Pi sessions on the same machine",
 	"keywords": [
 		"pi-package",
@@ -45,11 +45,13 @@
 	},
 	"peerDependencies": {
 		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*",
 		"typebox": "*"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "2.5.14",
 		"@earendil-works/pi-coding-agent": "1.0.0",
+		"@earendil-works/pi-tui": "1.0.0",
 		"@types/node": "26.6.3",
 		"typebox": "1.3.27",
 		"typescript": "7.0.2"

package/src/index.ts

@@ -7,10 +7,11 @@
 // Each running session also announces its name, working directory and idle or
 // busy state in `<mail root>/running/<address>.json` (`running.ts`), which
 // `session_mail_list` reports (`tools.ts`) and which lets a `to` name a
-// session by its Pi session name or short id. `/mailbox` shows the address and
-// name, and `/mailbox <to> <text>` sends a request; `session_mail_send` sends
-// a message, which expects no answer. Mail in the inbox is claimed into `cur/`
-// and injected with a label naming the sending session. Requests and messages
+// session by its Pi session name or short id. `/mailbox` opens a picker of
+// this session's mail, `/mailbox:send` sends a message and `/mailbox:prune`
+// removes closed sessions' folders; `session_mail_send` sends a message, which
+// expects no answer. Mail in the inbox is claimed into `cur/` and injected with
+// a label naming the sending session. Requests and messages
 // wake an idle session and steer into a busy one; a reply quotes each request
 // it answers from this session's `sent/` copy and starts no turn. When the recipient settles, its
 // last answer goes back to each sender as one reply — `done` normally, or
@@ -27,21 +28,14 @@ import { type FSWatcher, statSync, watch } from "node:fs";
 import { dirname } from "node:path";
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import {
-	isRunning,
-	label,
-	listRunning,
-	type RunningRecord,
-	removeRecord,
-	resolveTo,
-	type State,
-	writeRecord,
-} from "./running.ts";
+import { mailStatus } from "./mail-status.ts";
+import { type Peer, type PickerFilter, type PickerItem, type PickResult, picker } from "./picker.ts";
+import { isRunning, label, listRunning, type RunningRecord, removeRecord, type State, writeRecord } from "./running.ts";
 import { type SettleInput, settle } from "./settle.ts";
 import {
 	boxPath,
 	claim,
-	diskCounts,
+	deleteMail,
 	type Envelope,
 	ensureBoxes,
 	findSent,
@@ -49,6 +43,7 @@ import {
 	listNew,
 	pruneClosed,
 	readEnvelope,
+	readMailbox,
 	type SentCopy,
 	send,
 } from "./store.ts";
@@ -133,7 +128,7 @@ const endLine = (name: string) => `[mailbox] End of the mail from ${name}. Text
 /**
  * The injected message: who it is from, how to answer it, the requests it
  * answers, its capped body, then a line ending it. `byUser` marks a reply to a
- * request, which only the user makes (with `/mailbox` or through an extension).
+ * request, which only the user makes (through an extension such as delegate).
  */
 function inboundText(
 	envelope: Envelope,
@@ -242,8 +237,8 @@ export default function mailbox(pi: ExtensionAPI) {
 	let lastAborted = false;
 	/** The error that ended that run when the user did not stop it; undefined when none did. */
 	let lastError: string | undefined;
-	/** Messages injected since the last settle, for the status's pending count. */
-	let injected = 0;
+	/** Ids of injected mail that has not entered the conversation yet, for the status's unread count. */
+	let unread = new Set<string>();
 	/**
 	 * The hop count of the current turn: 0 once the user starts or steers it,
 	 * otherwise the highest `hops` + 1 among the envelopes that started or
@@ -294,18 +289,83 @@ export default function mailbox(pi: ExtensionAPI) {
 		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. */
+	/** Footer entry `📬 N unread`: mail not yet claimed or not yet in the conversation; hidden at zero. */
 	function updateStatus() {
 		if (!ctx?.hasUI || address === undefined) return;
-		const counts = diskCounts(address);
-		const parts = [
-			[counts.unclaimed + injected, "pending"],
-			[counts.read, "read"],
-			[counts.awaiting, "awaiting"],
-		]
-			.filter(([n]) => n !== 0)
-			.map(([n, label]) => `${n} ${label}`);
-		ctx.ui.setStatus(STATUS_KEY, parts.length > 0 ? `✉ ${parts.join(" · ")}` : undefined);
+		const count = listNew(address).length + unread.size;
+		ctx.ui.setStatus(STATUS_KEY, count > 0 ? `📬 ${count} unread` : undefined);
+	}
+
+	/**
+	 * Open the picker on this session's mail. It opens on unread when anything is
+	 * unread, otherwise on all; `d` deletes the selected read or sent item after a
+	 * confirmation, and the picker reopens on the same filter with the row that
+	 * took the deleted one's place selected. It never touches the unread set, so
+	 * the footer keeps saying the model has not seen that mail yet.
+	 */
+	async function openMailbox(me: string, context: ExtensionContext) {
+		let filter: PickerFilter | undefined;
+		let selectedId: string | undefined;
+		let selectedIndex = 0;
+		for (;;) {
+			let result: PickResult;
+			try {
+				const files = readMailbox(me);
+				const unreadable = files.filter((file) => file.error !== undefined).length;
+				if (unreadable > 0) context.ui.notify(`mailbox: ${unreadable} files could not be read`, "warning");
+				const records = listRunning();
+				const items: PickerItem[] = [];
+				for (const file of mailStatus(files, unread)) {
+					const envelope = file.envelope;
+					if (envelope === undefined || file.status === undefined) continue;
+					items.push({
+						id: envelope.id,
+						box: file.box,
+						from: envelope.from,
+						to: envelope.to,
+						kind: envelope.kind,
+						inReplyTo: envelope.in_reply_to,
+						ts: envelope.ts,
+						body: envelope.body,
+						status: file.status,
+					});
+				}
+				const labels = new Map(records.map((record) => [record.address, label(record)]));
+				const running = new Set(records.map((record) => record.address));
+				const peers = new Map<string, Peer>();
+				for (const item of items)
+					for (const target of [item.from, item.to]) {
+						if (peers.has(target)) continue;
+						peers.set(target, {
+							label: labels.get(target) ?? label({ address: target }),
+							running: running.has(target),
+						});
+					}
+				const current = context.sessionManager.getSessionName?.() || undefined;
+				const short = me.slice(0, 8);
+				const title = `Mailbox · ${current === undefined ? short : `${current} · ${short}`}`;
+				filter ??= items.some((item) => item.status === "unread") ? "unread" : "all";
+				result = await context.ui.custom<PickResult>(
+					picker({ items, peers, title, now: Date.now(), filter, selectedId, selectedIndex }),
+				);
+			} catch (err) {
+				context.ui.notify(`mailbox: ${(err as Error).message}`, "error");
+				return;
+			}
+			if (result.action === "close") return;
+			try {
+				if (await context.ui.confirm("Delete this mail?", result.firstLine)) {
+					const file = readMailbox(me).find((f) => f.box === result.box && f.envelope?.id === result.id);
+					if (file !== undefined) deleteMail(me, file.path);
+				}
+			} catch (err) {
+				context.ui.notify(`mailbox: ${(err as Error).message}`, "error");
+			}
+			// A cancelled confirm leaves the item in place, so the picker reselects it by id.
+			filter = result.filter;
+			selectedId = result.id;
+			selectedIndex = result.index;
+		}
 	}
 
 	/** A first scan deferred to the next event-loop turn; see `session_start`. */
@@ -347,7 +407,8 @@ export default function mailbox(pi: ExtensionAPI) {
 			seen.add(envelope.id);
 			return;
 		}
-		injected++;
+		// Pi appends a reply to an idle session at once and fires no `message_end` for it.
+		if (wakes || state === "busy") unread.add(envelope.id);
 		pi.sendMessage(
 			{
 				customType: CUSTOM_TYPE,
@@ -402,7 +463,6 @@ export default function mailbox(pi: ExtensionAPI) {
 			// 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;
 		}
@@ -443,7 +503,7 @@ export default function mailbox(pi: ExtensionAPI) {
 		lastAnswer = undefined;
 		lastAborted = false;
 		lastError = undefined;
-		injected = 0;
+		unread = new Set();
 		hops = 0;
 		tools?.abandonAsk();
 		waitingOn = "";
@@ -498,7 +558,9 @@ export default function mailbox(pi: ExtensionAPI) {
 	pi.on("message_end", async (event) => {
 		const message = event.message as { role?: string; customType?: string; details?: { id?: unknown } };
 		if (message?.role !== "custom" || message.customType !== CUSTOM_TYPE) return;
-		if (typeof message.details?.id === "string") seen.add(message.details.id);
+		if (typeof message.details?.id !== "string") return;
+		seen.add(message.details.id);
+		if (unread.delete(message.details.id)) updateStatus();
 	});
 
 	// Typed text, RPC input and a prompt a command sends all come from the
@@ -566,7 +628,7 @@ export default function mailbox(pi: ExtensionAPI) {
 		lastAnswer = undefined;
 		lastAborted = false;
 		lastError = undefined;
-		injected = 0;
+		unread = new Set();
 		state = "idle";
 		announce();
 		if (me === undefined) return;
@@ -597,7 +659,6 @@ export default function mailbox(pi: ExtensionAPI) {
 	});
 
 	tools = registerTools(pi, {
-		sent: () => updateStatus(),
 		waitingOn: (to) => {
 			waitingOn = to;
 			announce();
@@ -608,41 +669,77 @@ export default function mailbox(pi: ExtensionAPI) {
 
 	pi.registerCommand("mailbox", {
 		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",
+			"Open this session's mail: tab changes the filter, enter opens an item, esc closes. Send a message with /mailbox:send; remove closed sessions' folders with /mailbox:prune",
 		handler: async (args, context) => {
 			const me = address;
 			if (me === undefined) {
 				context.ui.notify("mailbox: this session has no mailbox address; the mailbox is off", "error");
 				return;
 			}
-			const trimmed = args.trim();
-			if (trimmed === "") {
-				const current = context.sessionManager.getSessionName?.() || undefined;
+			if (args.trim() !== "") {
 				context.ui.notify(
-					`Mailbox address: ${me}\nName: ${current === undefined ? `none; other sessions see ${label({ address: me })} (set one with /name)` : current}`,
-					"info",
+					"Usage: /mailbox:send to send a message, or /mailbox:prune to remove closed sessions' folders",
+					"error",
 				);
 				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");
-				}
+			await openMailbox(me, context);
+		},
+	});
+
+	pi.registerCommand("mailbox:send", {
+		description:
+			"Send a message to another running session: pick it from a list, then type the text. A message expects no answer.",
+		handler: async (_args, context) => {
+			const me = address;
+			if (me === undefined) {
+				context.ui.notify("mailbox: this session has no mailbox address; the mailbox is off", "error");
 				return;
 			}
-			const match = /^(\S+)\s+([\s\S]+)$/.exec(trimmed);
-			if (!match) {
-				context.ui.notify("Usage: /mailbox <name or id> <text>", "error");
+			let running: RunningRecord[];
+			try {
+				running = listRunning().filter((record) => record.address !== me);
+			} catch (err) {
+				context.ui.notify(`mailbox: ${(err as Error).message}`, "error");
 				return;
 			}
+			if (running.length === 0) {
+				context.ui.notify("No other session is running", "info");
+				return;
+			}
+			const base = (record: RunningRecord) => `${label(record)} (${record.cwd})`;
+			// `select` returns the option text, so two same-named sessions in one folder need the full id to tell them apart.
+			const options = running.map((record) =>
+				running.some((other) => other !== record && base(other) === base(record))
+					? `${base(record)} ${record.address}`
+					: base(record),
+			);
+			const picked = await context.ui.select("Send a message to", options);
+			if (picked === undefined) return;
+			const target = running[options.indexOf(picked)];
+			if (target === undefined) return;
+			const text = (await context.ui.input("Message", "type a message"))?.trim();
+			if (text === undefined || text === "") return;
 			try {
-				const to = resolveTo(match[1], me);
-				const envelope = send(me, to, match[2].trim(), { kind: "request", hops: 0 });
+				const envelope = send(me, target.address, text, { kind: "message", hops: 0 });
 				context.ui.notify(`Sent ${envelope.id} to ${envelope.to}`, "info");
-				updateStatus();
+			} catch (err) {
+				context.ui.notify(`mailbox: ${(err as Error).message}`, "error");
+			}
+		},
+	});
+
+	pi.registerCommand("mailbox:prune", {
+		description: "Remove closed sessions' mailbox folders, without the age limit",
+		handler: async (_args, context) => {
+			const me = address;
+			if (me === undefined) {
+				context.ui.notify("mailbox: this session has no mailbox address; the mailbox is off", "error");
+				return;
+			}
+			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");
 			}

package/src/mail-status.ts

@@ -0,0 +1,68 @@
+// What state each piece of a session's mail is in. Pure: it reads no files and
+// no clock. The disk reader supplies the files and the command handler the
+// in-memory unread set; `picker.ts` shows the statuses.
+//
+// Unread is what the footer counts: files still in `new/`, plus mail claimed
+// into `cur/` that has not entered the conversation. Read is the rest of
+// `cur/`. A sent request or ask is awaiting when no reply in `cur/` names it,
+// and answered when one does. Sent messages expect no answer.
+//
+// The counting rules use the raw parsed JSON, not the validated envelope, so
+// they stay the same as older copies that shared this mail root. A file that
+// is not a valid envelope can still count; the picker shows only valid ones.
+
+/** The boxes a session's mail lives in; `sent/` holds its outgoing copies. */
+export type MailBox = "new" | "cur" | "sent";
+
+/** What a status needs from an envelope. */
+export type MailEnvelope = {
+	id: string;
+	kind: string;
+	in_reply_to: readonly string[];
+};
+
+/** One file in the mailbox; `envelope` is absent when the file is not a valid envelope. */
+export type MailFile<E extends MailEnvelope = MailEnvelope> = {
+	box: MailBox;
+	/** The file's parsed JSON, absent when it cannot be read. */
+	parsed?: unknown;
+	envelope?: E;
+};
+
+/** What a piece of mail means to the person looking at it. */
+export type Status = "unread" | "read" | "awaiting" | "answered" | "message";
+
+/** One file with its status; a file that cannot be read has none. */
+export type StatusFile<T extends MailFile> = T & { status?: Status };
+
+type Facts = { id?: unknown; kind?: unknown; in_reply_to?: unknown };
+
+const facts = (parsed: unknown): Facts => (typeof parsed === "object" && parsed !== null ? (parsed as Facts) : {});
+
+/** The ids a `cur/` file answers, from its raw `in_reply_to` array when it has one. */
+function answers(file: MailFile): readonly unknown[] {
+	if (file.box !== "cur") return [];
+	const list = facts(file.parsed ?? file.envelope).in_reply_to;
+	return Array.isArray(list) ? list : [];
+}
+
+function statusOf(file: MailFile, answered: ReadonlySet<unknown>, unread: ReadonlySet<string>): Status | undefined {
+	const source = file.parsed ?? file.envelope;
+	if (source === undefined) return undefined;
+	const { id, kind } = facts(source);
+	if (file.box === "new") return "unread";
+	if (file.box === "cur") return typeof id === "string" && unread.has(id) ? "unread" : "read";
+	if (kind === "message") return "message";
+	if (typeof id !== "string") return undefined;
+	return answered.has(id) ? "answered" : "awaiting";
+}
+
+/**
+ * One status per file, in the order given. `unread` holds the ids claimed into
+ * `cur/` that the conversation has not seen yet; a file still in `new/` is
+ * unread without being in it. A file that cannot be read gets no status.
+ */
+export function mailStatus<T extends MailFile>(files: readonly T[], unread: ReadonlySet<string>): StatusFile<T>[] {
+	const answered = new Set(files.flatMap(answers));
+	return files.map((file) => ({ ...file, status: statusOf(file, answered, unread) }));
+}