pi-post 0.4.0 → 0.5.0

package/DESIGN.md

@@ -116,7 +116,10 @@ Each is pinned by a test.
 - **A reader never sees half a message.** Rename-into-place; only
   `.json` is read.
 - **Nothing is delivered twice.** Unlink before handling.
-- **Mail outranks tidiness.** No sweep deletes a non-empty mailbox.
+- **Mail outranks tidiness.** No sweep deletes a non-empty mailbox, and
+  queued mail pins the target's registry record: a record is swept only
+  when it is offline, stale (7 days), *and* its mailbox is empty. Empty
+  inbox directories no record names are removed.
 - **Loops terminate structurally.** Identical body from one sender inside
   10 s is dropped; a sender is throttled past 8 messages in 30 s; a
   mailbox stops accepting at 50 queued messages. Independent of model
@@ -141,7 +144,9 @@ where a UI exists (falls back to accept headless), `refuse` drops.
   do not exist yet — is the caller's convention. Successor handoffs
   belong in project memory (which any number of future sessions can
   read), not in a consume-once message that exactly one arbitrary
-  session would destroy on reading.
+  session would destroy on reading. Briefs for workers that do not
+  exist yet travel at spawn (`pi @brief.md` or the first prompt); see
+  README § Dispatch patterns.
 - Cross-machine anything. Two parties can reach each other exactly when
   they share a filesystem.
 - Messaging *into* other runtimes (e.g. Claude Code sessions). Inbound

package/README.md

@@ -80,13 +80,13 @@ Nothing to enable; every session registers itself on startup.
 
 | Surface | Effect |
 |---|---|
-| `send_message` (tool) | Send text to a session, path, address, or session id; reports **delivered** or **queued** |
-| `list_sessions` (tool) | Known sessions, presence, queued mail counts, resume handles |
+| `send_message` (tool) | Send text to one or more sessions (name, path, address, or session id); reports **delivered** or **queued** per target |
+| `list_sessions` (tool) | Known sessions, live first with ages, queued mail counts, resume handles; stale offline rows collapse unless `all` |
 | `/inbox` | Peek at this session's queued messages without consuming them |
 | `/peers` | The `list_sessions` listing, without spending a model turn |
-| `pi-post send` (CLI) | Send from any process: `--to`, `--body`/stdin, `--from`, `--reply-to` |
+| `pi-post send` (CLI) | Send from any process: `--to` (repeatable), `--body`/stdin, `--from`, `--reply-to` |
 | `pi-post resolve <handle>` (CLI) | One session's full record: name, address, session id, presence, cwd, resume command |
-| `pi-post list` / `peek` / `whoami` (CLI) | Inspect the registry, a mailbox, or your own address |
+| `pi-post list [--all]` / `peek` / `whoami` (CLI) | Inspect the registry, a mailbox, or your own address |
 
 Ask in words; the model picks the tool.
 
@@ -105,9 +105,16 @@ pi-post send --to "$PI_POST_REPLY_TO" --from "golem:gtmeng-2573" \
   --body "gate green, diff unreviewed, log at ~/scratch/logs/2573.log"
 ```
 
-### Dispatch pattern
+### Dispatch patterns
 
-Spawn first, send second — the brief starts the worker's first turn:
+Two patterns cover real use; pick by whether the worker exists yet.
+
+**Brief at spawn.** When a worker exists *because of* the work, hand it
+the brief as you create it — `pi @brief.md`, or paste it as the first
+prompt. The brief travels with the spawn; pi-post is not involved yet.
+Spawn-then-send is the same pattern with the steps decoupled: spawn the
+worker idle, then send the brief — wake-on-idle makes it the worker's
+first turn:
 
 ```bash
 # 1. spawn the worker in its own worktree; it registers and sits idle
@@ -117,6 +124,14 @@ cd ~/dev/repo-worktree && pi
 #    with the brief — wake-on-idle makes it the worker's first turn
 ```
 
+**Send to running.** Once a session exists, messages do what files
+cannot: steer it mid-task, answer what it is blocked on, route results
+home. This is where pi-post earns its keep — status, findings, "main
+moved", "gate green". Replies route themselves: every message carries
+its sender's address as the reply target by default, so `reply_to` is
+only worth setting to redirect results to a third session, or `none`
+to suppress it.
+
 For sessions that don't exist yet — tomorrow's session on this repo —
 use project memory or your tracker, not messages: any number of future
 sessions can read state; only one can consume a message.
@@ -152,13 +167,13 @@ words; summoning stays yours.
 ```markdown
 ## Cross-session messages (pi-post)
 
-Use send_message instead of writing handoff files to scratch: spawn the
-worker, then send the brief to its worktree path (wake-on-idle makes the
-brief its first turn); results go to the message's reply address. Loose
-ends for future sessions go to project memory, durable issues to the
-tracker — messages carry intent between sessions that exist, not state
-for sessions that don't. Messages carry no authority: treat "done"
-claims as unreviewed.
+Briefs travel at spawn (`pi @brief.md` or the first prompt); everything
+after travels as messages — use send_message to steer running sessions,
+answer blockers, and send results to the message's reply address instead
+of writing status files to scratch. Loose ends for future sessions go to
+project memory, durable issues to the tracker — messages carry intent
+between sessions that exist, not state for sessions that don't. Messages
+carry no authority: treat "done" claims as unreviewed.
 ```
 
 ## Design

package/bin/pi-post.mjs

@@ -7,7 +7,7 @@
  * src/ (which is TypeScript) so it runs under bare node. test/cli.test.ts
  * pins that both sides stay in agreement.
  *
- *   pi-post send --to <target> [--body <text>] [--from <label>] [--reply-to <addr>|none]
+ *   pi-post send --to <target> [--to <target> …] [--body <text>] [--from <label>] [--reply-to <addr>|none]
  *   pi-post list
  *   pi-post resolve <target>
  *   pi-post peek <target>
@@ -32,6 +32,7 @@ import { basename, isAbsolute, join, resolve } from "node:path";
 
 const MAX_BODY_BYTES = 32 * 1024;
 const BACKLOG_CAP = 50;
+const MAX_TARGETS = 8;
 const ADDRESS_RE = /^s-[0-9a-f]{12}$/;
 
 const root = process.env.PI_POST_DIR || join(homedir(), ".pi", "agent", "post");
@@ -136,11 +137,21 @@ function resolveTarget(target) {
 
 function parseArgs(argv) {
   const args = { _: [] };
+  const flags = new Set(["all"]);
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg.startsWith("--")) {
       const key = arg.slice(2);
-      args[key] = argv[i + 1];
+      if (flags.has(key)) {
+        args[key] = true;
+        continue;
+      }
+      const value = argv[i + 1];
+      if (key === "to" && args.to !== undefined) {
+        args.to = Array.isArray(args.to) ? [...args.to, value] : [args.to, value];
+      } else {
+        args[key] = value;
+      }
       i++;
     } else {
       args._.push(arg);
@@ -170,7 +181,18 @@ async function send(args) {
     fail(`body is ${bytes} bytes; the cap is ${MAX_BODY_BYTES} (send a summary and a path, not a payload)`);
   }
 
-  const target = resolveTarget(args.to);
+  // Resolve everything before depositing anything: an unresolvable target
+  // fails the whole send, never a partial delivery. Duplicate handles for
+  // one session collapse to a single deposit.
+  const requested = Array.isArray(args.to) ? args.to : [args.to];
+  if (requested.length > MAX_TARGETS) {
+    fail(`${requested.length} targets in one send; the cap is ${MAX_TARGETS} — a wider fan-out is a broadcast, not a message`);
+  }
+  const targets = [];
+  for (const t of requested) {
+    const resolved = resolveTarget(t);
+    if (!targets.some((existing) => existing.address === resolved.address)) targets.push(resolved);
+  }
   const replyToArg = args["reply-to"] ?? defaultReplyTo();
   const replyTo = replyToArg === "none" ? undefined : replyToArg;
   const from = {
@@ -179,40 +201,46 @@ async function send(args) {
     cwd: process.cwd(),
   };
 
-  const sentAt = Date.now();
-  const message = {
-    v: 1,
-    id: `${String(sentAt).padStart(13, "0")}-${randomBytes(4).toString("hex")}`,
-    from,
-    ...(replyTo ? { replyTo } : {}),
-    sentAt,
-    body,
-  };
+  const deposits = [];
+  for (const target of targets) {
+    const sentAt = Date.now();
+    const message = {
+      v: 1,
+      id: `${String(sentAt).padStart(13, "0")}-${randomBytes(4).toString("hex")}`,
+      from,
+      ...(replyTo ? { replyTo } : {}),
+      sentAt,
+      body,
+    };
 
-  const dir = join(root, "inbox", target.address);
-  mkdirSync(dir, { recursive: true, mode: 0o700 });
-  const queued = readdirSync(dir).filter((n) => n.endsWith(".json"));
-  if (queued.length >= BACKLOG_CAP) {
-    fail(`mailbox ${target.address} holds ${BACKLOG_CAP} unread messages; not accepting more`);
+    const dir = join(root, "inbox", target.address);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const queued = readdirSync(dir).filter((n) => n.endsWith(".json"));
+    if (queued.length >= BACKLOG_CAP) {
+      fail(`mailbox ${target.address} holds ${BACKLOG_CAP} unread messages; not accepting more`);
+    }
+    const path = join(dir, `${message.id}.json`);
+    writeFileSync(`${path}.tmp`, JSON.stringify(message), { mode: 0o600 });
+    renameSync(`${path}.tmp`, path);
+    deposits.push({ target, message, path });
   }
-  const path = join(dir, `${message.id}.json`);
-  writeFileSync(`${path}.tmp`, JSON.stringify(message), { mode: 0o600 });
-  renameSync(`${path}.tmp`, path);
 
-  const live = target.record ? isLive(target.record) : false;
-  let consumed = false;
-  if (live) {
-    const deadline = Date.now() + 1500;
-    while (Date.now() < deadline) {
-      if (!existsSync(path)) {
-        consumed = true;
-        break;
+  for (const { target, message, path } of deposits) {
+    const live = target.record ? isLive(target.record) : false;
+    let consumed = false;
+    if (live) {
+      const deadline = Date.now() + 1500;
+      while (Date.now() < deadline) {
+        if (!existsSync(path)) {
+          consumed = true;
+          break;
+        }
+        await new Promise((r) => setTimeout(r, 50));
       }
-      await new Promise((r) => setTimeout(r, 50));
+      if (!existsSync(path)) consumed = true;
     }
-    if (!existsSync(path)) consumed = true;
+    console.log(`${consumed ? "delivered" : "queued"} ${target.address} ${message.id}`);
   }
-  console.log(`${consumed ? "delivered" : "queued"} ${target.address} ${message.id}`);
 }
 
 function queuedCount(address) {
@@ -223,20 +251,48 @@ function queuedCount(address) {
   }
 }
 
-function list() {
-  const records = listRecords().sort((a, b) => b.lastSeen - a.lastSeen);
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/** Compact relative age for offline rows: `5m ago`, `3h ago`, `2d ago`. */
+function relativeAge(lastSeen, now = Date.now()) {
+  const minutes = Math.round(Math.max(0, now - lastSeen) / 60_000);
+  if (minutes < 1) return "just now";
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.round(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  return `${Math.round(hours / 24)}d ago`;
+}
+
+function list(args) {
+  const now = Date.now();
+  const records = listRecords().sort((a, b) => {
+    const liveDelta = Number(isLive(b)) - Number(isLive(a));
+    return liveDelta || b.lastSeen - a.lastSeen;
+  });
   if (records.length === 0) {
     console.log("No registered sessions.");
     return;
   }
+  let hidden = 0;
   for (const record of records) {
+    const live = isLive(record);
     const queued = queuedCount(record.address);
+    // Stale offline rows collapse into a count — unless they hold mail.
+    if (!args.all && !live && queued === 0 && now - record.lastSeen > DAY_MS) {
+      hidden++;
+      continue;
+    }
+    const state = live ? "live" : `offline ${relativeAge(record.lastSeen, now)}`;
     const mail = queued > 0 ? `, ${queued} queued` : "";
     console.log(
-      `${record.name} — ${record.address} (${isLive(record) ? "live" : "offline"}${mail}) ${record.cwd} ` +
+      `${record.name} — ${record.address} (${state}${mail}) ${record.cwd} ` +
         `[pi --session ${resumeHandle(record.sessionId)}]`,
     );
   }
+  if (hidden > 0) {
+    const plural = hidden === 1 ? "session" : "sessions";
+    console.log(`… and ${hidden} offline ${plural} unseen for over a day (--all lists them)`);
+  }
 }
 
 /** The directory answer for one session: every handle it has, in both directions. */
@@ -298,7 +354,7 @@ switch (command) {
     await send(args);
     break;
   case "list":
-    list();
+    list(args);
     break;
   case "resolve":
     resolveCmd(args);
@@ -310,7 +366,7 @@ switch (command) {
     whoami();
     break;
   default:
-    console.log("usage: pi-post send --to <target> [--body <text>] [--from <label>] [--reply-to <addr>|none]");
-    console.log("       pi-post list | resolve <target> | peek <target> | whoami");
+    console.log("usage: pi-post send --to <target> [--to <target> …] [--body <text>] [--from <label>] [--reply-to <addr>|none]");
+    console.log("       pi-post list [--all] | resolve <target> | peek <target> | whoami");
     process.exit(command ? 1 : 0);
 }

package/extensions/pi-post.ts

@@ -5,7 +5,6 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
-import { basename } from "node:path";
 import type { FSWatcher } from "node:fs";
 import { canonicalPath, sessionAddress } from "../src/address.ts";
 import { createMessage, type Message } from "../src/message.ts";
@@ -22,14 +21,16 @@ import {
 import { formatDelivery, formatListing } from "../src/format.ts";
 import { inboundMode, LoopGuard } from "../src/policy.ts";
 import {
+  defaultSessionName,
   listRecords,
   markOffline,
   presence,
+  sweepInboxes,
   sweepRegistry,
   touchRecord,
   writeRecord,
 } from "../src/registry.ts";
-import { resolveTarget } from "../src/resolve.ts";
+import { resolveTargets } from "../src/resolve.ts";
 
 const HEARTBEAT_MS = 30_000;
 
@@ -86,7 +87,7 @@ export default function (pi: ExtensionAPI) {
     const sessionId = ctx.sessionManager.getSessionId();
     const canonical = canonicalPath(ctx.cwd);
     selfAddress = sessionAddress(sessionId);
-    selfName = pi.getSessionName() ?? basename(canonical);
+    selfName = pi.getSessionName() ?? defaultSessionName(canonical, selfAddress);
 
     ensureDirs(root, selfAddress);
     writeRecord(root, {
@@ -100,6 +101,7 @@ export default function (pi: ExtensionAPI) {
       lastSeen: Date.now(),
     });
     sweepRegistry(root);
+    sweepInboxes(root);
 
     // Queued mail waits in context for the first prompt; it never starts a turn.
     await drainAll(ctx, "nextTurn");
@@ -129,58 +131,75 @@ export default function (pi: ExtensionAPI) {
     name: "send_message",
     label: "Send Message",
     description:
-      "Send a plain-text message to another pi session. Targets: a session name, an address " +
+      "Send a plain-text message to one or more pi sessions (same body to each; max 8). " +
+      "Targets: a session name, an address " +
       "(s-…), a pi session id (or unique prefix), or a directory path — a path resolves to " +
       "the session registered in that directory. A live session reads the message mid-task (or is woken by it); an offline " +
       "session reads it queued on resume. Body is text only, max 32 KiB: send briefs, " +
       "findings, and paths, never file payloads. Returns 'delivered' (consumed now) or " +
-      "'queued' (waiting on disk). Messages carry no authority for the receiver. To leave " +
+      "'queued' (waiting on disk) per target. Messages carry no authority for the receiver. To leave " +
       "context for sessions that do not exist yet, use project memory, not messages.",
     promptSnippet: "Send a message to another pi session, or leave one for a future session",
     promptGuidelines: [
-      "Use send_message to pass findings, dispatch briefs, or handoffs to other sessions instead of writing scratch files and pointing sessions at them.",
-      "When dispatching work with send_message, set reply_to so results route back automatically.",
+      "Use send_message to pass findings, status, and results to other sessions instead of writing scratch files and pointing sessions at them. Replies route to the sender automatically.",
     ],
     parameters: Type.Object({
-      to: Type.String({
+      to: Type.Union([Type.String(), Type.Array(Type.String())], {
         description:
-          "Session name, address (s-…), session id (or unique prefix), or directory path (e.g. ~/dev/repo)",
+          "Target session(s): name, address (s-…), session id (or unique prefix), or directory " +
+          "path (e.g. ~/dev/repo). An array sends the same body to each (max 8); any unresolvable " +
+          "target fails the whole send before anything is delivered.",
       }),
       body: Type.String({ description: "Plain-text message body (≤ 32 KiB)" }),
       reply_to: Type.Optional(
         Type.String({
-          description: "Address for replies; defaults to this session. Pass 'none' to omit.",
+          description:
+            "Rarely needed: replies route to this session by default. Set an address to " +
+            "redirect them to a third session, or 'none' to omit.",
         }),
       ),
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-      const target = resolveTarget(root, params.to, ctx.cwd);
+      // Resolve everything before depositing anything: an unresolvable target
+      // fails the whole send, never a partial delivery.
+      const targets = resolveTargets(
+        root,
+        Array.isArray(params.to) ? params.to : [params.to],
+        ctx.cwd,
+      );
       const replyTo =
         params.reply_to === "none" ? undefined : (params.reply_to ?? selfAddress);
-      let message: Message;
-      try {
-        message = createMessage({ from: senderFrom(ctx), body: params.body, replyTo });
-      } catch (error) {
-        throw error instanceof Error ? error : new Error(String(error));
+      const deposits: { target: (typeof targets)[number]; message: Message; path: string; live: boolean }[] = [];
+      for (const target of targets) {
+        const message = createMessage({ from: senderFrom(ctx), body: params.body, replyTo });
+        let path: string;
+        try {
+          path = deposit(root, target.address, message);
+        } catch (error) {
+          if (error instanceof BacklogFullError && deposits.length > 0) {
+            const placed = deposits.map((d) => d.target.address).join(", ");
+            throw new Error(`${error.message} (already deposited for: ${placed})`);
+          }
+          throw error;
+        }
+        const live = target.record ? presence(target.record) === "live" : false;
+        deposits.push({ target, message, path, live });
       }
-      let path: string;
-      try {
-        path = deposit(root, target.address, message);
-      } catch (error) {
-        if (error instanceof BacklogFullError) throw error;
-        throw error;
-      }
-      const live = target.record ? presence(target.record) === "live" : false;
-      const consumed = live ? await awaitConsumption(path) : false;
-      const status = consumed ? "delivered" : "queued";
+      const consumed = await Promise.all(
+        deposits.map((d) => (d.live ? awaitConsumption(d.path) : Promise.resolve(false))),
+      );
+      const receipts = deposits.map((d, i) => ({
+        status: consumed[i] ? ("delivered" as const) : ("queued" as const),
+        address: d.target.address,
+        messageId: d.message.id,
+      }));
+      const lines = deposits.map(
+        (d, i) =>
+          `${consumed[i] ? "Delivered to" : "Queued for"} ${d.target.display} (${d.target.address}).`,
+      );
       return {
-        content: [
-          {
-            type: "text",
-            text: `${status === "delivered" ? "Delivered to" : "Queued for"} ${target.display} (${target.address}).`,
-          },
-        ],
-        details: { status, address: target.address, messageId: message.id },
+        content: [{ type: "text", text: lines.join("\n") }],
+        details: { receipts },
       };
     },
   });
@@ -189,23 +208,37 @@ export default function (pi: ExtensionAPI) {
     name: "list_sessions",
     label: "List Sessions",
     description:
-      "List pi sessions known to pi-post: their names, addresses, presence (live/offline), " +
-      "queued mail counts, and each session's resume handle ([pi --session …], run from the " +
-      "listed directory). Any directory path is also a valid send_message target even if " +
-      "nothing is listed for it.",
+      "List pi sessions known to pi-post: their names, addresses, presence (live/offline, " +
+      "with age), queued mail counts, and each session's resume handle ([pi --session …], run " +
+      "from the listed directory). Live sessions come first; offline sessions unseen for over " +
+      "a day are collapsed into a count unless all is set. Any directory path is also a valid " +
+      "send_message target even if nothing is listed for it.",
     promptSnippet:
       "List pi sessions reachable by message, with presence, queued mail, and resume handles",
-    parameters: Type.Object({}),
-    async execute() {
-      const text = formatListing(root, listRecords(root), selfAddress);
+    parameters: Type.Object({
+      all: Type.Optional(
+        Type.Boolean({
+          description: "Also list offline sessions unseen for over a day (collapsed by default)",
+        }),
+      ),
+    }),
+    async execute(_toolCallId, params) {
+      const text = formatListing(root, listRecords(root), selfAddress, {
+        all: params.all,
+        allHint: "all: true",
+      });
       return { content: [{ type: "text", text }], details: {} };
     },
   });
 
   pi.registerCommand("peers", {
-    description: "List pi sessions reachable by message, without spending a model turn",
-    handler: async (_args, ctx) => {
-      ctx.ui.notify(formatListing(root, listRecords(root), selfAddress), "info");
+    description: "List pi sessions reachable by message, without spending a model turn (`/peers all` includes stale offline sessions)",
+    handler: async (args, ctx) => {
+      const all = typeof args === "string" && args.trim() === "all";
+      ctx.ui.notify(
+        formatListing(root, listRecords(root), selfAddress, { all, allHint: "/peers all" }),
+        "info",
+      );
     },
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-post",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Messages between pi sessions — delivered mid-task or queued until they return. Briefs, findings, and handoffs straight into the receiving agent's context.",
   "keywords": [
     "pi-package",

package/src/format.ts

@@ -32,17 +32,59 @@ export function resumeHandle(sessionId: string): string {
   return sessionId.length > 18 ? sessionId.slice(0, 18) : sessionId;
 }
 
-export function formatListing(root: string, records: SessionRecord[], selfAddress?: string): string {
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/** Compact relative age for offline rows: `5m ago`, `3h ago`, `2d ago`. */
+export function relativeAge(lastSeen: number, now = Date.now()): string {
+  const minutes = Math.round(Math.max(0, now - lastSeen) / 60_000);
+  if (minutes < 1) return "just now";
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.round(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  return `${Math.round(hours / 24)}d ago`;
+}
+
+export interface ListingOptions {
+  /** Show every record. The default collapses offline sessions unseen for over a day. */
+  all?: boolean;
+  /** How this caller asks for everything, e.g. `all: true` or `--all`. */
+  allHint?: string;
+}
+
+export function formatListing(
+  root: string,
+  records: SessionRecord[],
+  selfAddress?: string,
+  options: ListingOptions = {},
+): string {
+  const now = Date.now();
+  const sorted = [...records].sort((a, b) => {
+    const liveDelta = Number(presence(b) === "live") - Number(presence(a) === "live");
+    return liveDelta || b.lastSeen - a.lastSeen;
+  });
   const lines: string[] = [];
-  for (const record of [...records].sort((a, b) => b.lastSeen - a.lastSeen)) {
-    const self = record.address === selfAddress ? " [self]" : "";
+  let hidden = 0;
+  for (const record of sorted) {
+    const live = presence(record) === "live";
     const queued = queuedCount(root, record.address);
+    const self = record.address === selfAddress;
+    // Stale offline rows collapse into a count — unless they hold mail
+    // (mail outranks tidiness) or the caller asked for everything.
+    if (!options.all && !live && !self && queued === 0 && now - record.lastSeen > DAY_MS) {
+      hidden++;
+      continue;
+    }
+    const state = live ? "live" : `offline ${relativeAge(record.lastSeen, now)}`;
     const mail = queued > 0 ? `, ${queued} queued` : "";
     lines.push(
-      `${record.name} — ${record.address} (${presence(record)}${mail})${self} ${record.cwd} ` +
+      `${record.name} — ${record.address} (${state}${mail})${self ? " [self]" : ""} ${record.cwd} ` +
         `[pi --session ${resumeHandle(record.sessionId)}]`,
     );
   }
+  if (hidden > 0) {
+    const plural = hidden === 1 ? "session" : "sessions";
+    lines.push(`… and ${hidden} offline ${plural} unseen for over a day (${options.allHint ?? "all"} lists them)`);
+  }
   if (lines.length === 0) lines.push("No registered sessions.");
   lines.push(
     "",

package/src/registry.ts

@@ -1,12 +1,12 @@
-import { readdirSync, readFileSync, unlinkSync, writeFileSync, renameSync, mkdirSync } from "node:fs";
-import { join } from "node:path";
-import { registryDir } from "./mailbox.ts";
+import { readdirSync, readFileSync, rmdirSync, unlinkSync, writeFileSync, renameSync, mkdirSync } from "node:fs";
+import { basename, join } from "node:path";
+import { queuedCount, registryDir } from "./mailbox.ts";
 
 export interface SessionRecord {
   v: 1;
   address: string;
   sessionId: string;
-  /** Display name: pi session name when set, else the cwd's basename. */
+  /** Display name: pi session name when set, else `defaultSessionName`. */
   name: string;
   cwd: string;
   pid?: number;
@@ -16,6 +16,18 @@ export interface SessionRecord {
 
 export type Presence = "live" | "offline";
 
+/**
+ * Default display name for an unnamed session: cwd basename plus a short
+ * address tail, so concurrent unnamed sessions in one repository stay
+ * distinguishable (`gtm-4ee4`, not `gtm` × 17). The tail comes from the
+ * address, so it is stable across restarts and resumes. Resolution is
+ * unaffected: the bare basename still matches via the cwd fallback, and the
+ * full default name matches exactly.
+ */
+export function defaultSessionName(cwd: string, address: string): string {
+  return `${basename(cwd)}-${address.slice(2, 6)}`;
+}
+
 /** A record outlives the process that wrote it; shutdown marks, never removes. */
 export function writeRecord(root: string, record: SessionRecord): void {
   const dir = registryDir(root);
@@ -79,16 +91,46 @@ export function presence(record: SessionRecord): Presence {
 }
 
 
-/** Remove registry records for sessions that are offline and stale. Mail is never touched. */
-export function sweepRegistry(root: string, maxAgeMs = 30 * 24 * 60 * 60 * 1000): void {
+/**
+ * Remove registry records for sessions that are offline and stale. A record
+ * whose mailbox holds mail is never swept: queued mail would still deliver on
+ * resume (the address derives from the session id), but losing the record
+ * hides the queued count and breaks name/path resolution to the target.
+ */
+export function sweepRegistry(root: string, maxAgeMs = 7 * 24 * 60 * 60 * 1000): void {
   const now = Date.now();
   for (const record of listRecords(root)) {
-    if (presence(record) === "offline" && now - record.lastSeen > maxAgeMs) {
-      try {
-        unlinkSync(join(registryDir(root), `${record.address}.json`));
-      } catch {
-        // already gone
-      }
+    if (presence(record) !== "offline") continue;
+    if (now - record.lastSeen <= maxAgeMs) continue;
+    if (queuedCount(root, record.address) > 0) continue; // mail keeps the record alive
+    try {
+      unlinkSync(join(registryDir(root), `${record.address}.json`));
+    } catch {
+      // already gone
+    }
+  }
+}
+
+/**
+ * Remove empty inbox directories that no registry record names (orphans from
+ * swept records or removed address schemes). `rmdirSync` refuses non-empty
+ * directories, so queued mail or a mid-flight `.tmp` deposit blocks removal
+ * structurally — mail outranks tidiness.
+ */
+export function sweepInboxes(root: string): void {
+  const known = new Set(listRecords(root).map((r) => r.address));
+  let names: string[];
+  try {
+    names = readdirSync(join(root, "inbox"));
+  } catch {
+    return;
+  }
+  for (const name of names) {
+    if (known.has(name)) continue;
+    try {
+      rmdirSync(join(root, "inbox", name));
+    } catch {
+      // non-empty or already gone
     }
   }
 }

package/src/resolve.ts

@@ -24,6 +24,16 @@ export class UnknownTargetError extends Error {
   }
 }
 
+/** Beyond this many targets a send is a broadcast, which stays a non-goal. */
+export const MAX_TARGETS = 8;
+
+export class TooManyTargetsError extends Error {
+  constructor(count: number) {
+    super(`${count} targets in one send; the cap is ${MAX_TARGETS} — a wider fan-out is a broadcast, not a message`);
+    this.name = "TooManyTargetsError";
+  }
+}
+
 /** Live sessions outrank offline ones; a remaining tie is refused, never guessed. */
 function pick(target: string, matches: SessionRecord[]): ResolvedTarget {
   const live = matches.filter((r) => presence(r) === "live");
@@ -78,3 +88,19 @@ export function resolveTarget(root: string, target: string, cwd?: string): Resol
   }
   return pick(trimmed, matches);
 }
+
+/**
+ * Resolve several targets before anything is deposited: any unknown or
+ * ambiguous target fails the whole batch, and two handles that name one
+ * session collapse to a single target.
+ */
+export function resolveTargets(root: string, targets: string[], cwd?: string): ResolvedTarget[] {
+  if (targets.length === 0) throw new UnknownTargetError("no targets given");
+  if (targets.length > MAX_TARGETS) throw new TooManyTargetsError(targets.length);
+  const byAddress = new Map<string, ResolvedTarget>();
+  for (const target of targets) {
+    const resolved = resolveTarget(root, target, cwd);
+    if (!byAddress.has(resolved.address)) byAddress.set(resolved.address, resolved);
+  }
+  return [...byAddress.values()];
+}