pi-post 0.3.0 → 0.5.0

package/DESIGN.md

@@ -34,6 +34,22 @@ query, not an address**: it resolves to the session registered in that
 directory (live outranks offline; a remaining tie is refused with
 candidates listed). Nothing can be addressed that does not exist.
 
+**Every handle resolves; no identifier is a dead end.** The registry is
+a bidirectional directory: a target may be an address, a live session's
+name, a directory path, or pi's own session id (or a unique prefix of
+one — hex-looking strings fall through to name matching when no session
+id matches). In the other direction, listings carry each session's
+resume handle (`pi --session …`, three UUID groups: the UUIDv7
+timestamp plus random bits) beside its address, and `pi-post resolve
+<handle>` prints the full record — name, address, session id, presence,
+cwd, resume command. The address stays a hash on purpose: deriving it
+from the session id would couple the wire contract to pi's id format
+and, with UUIDv7, collide on prefixes for sessions started close
+together. Surfacing the mapping the registry already stores gives the
+same ergonomics without touching the contract. Printing a resume handle
+is directory information, not lifecycle management — pi-post still
+never spawns or resumes anything itself.
+
 v0.2.0 had a second kind — standing addresses, one per directory, so
 mail could wait for sessions that did not exist yet. Removed in v0.3.0:
 in a busy repository, directory identity is not task identity, so
@@ -100,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
@@ -125,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

@@ -44,14 +44,20 @@ resume. A directory path as a target is a *query* — it resolves to the
 session registered in that directory, live sessions first, ambiguity
 refused.
 
+**Every handle resolves.** Target a session by name, address, directory
+path, or pi's own session id (or a unique prefix). In the other
+direction, every listing carries the session's resume handle —
+`[pi --session …]`, run from its directory — so nothing pi-post shows
+you is a dead end: anything you can see, you can message *and* reopen.
+
 **Wake-on-idle delivery.** A message to an idle session starts its turn.
 Spawn a worker in its worktree, send the brief — the brief *is* the
 worker's first turn. No "check your mail" incantations.
 
-**Two tools.** `send_message` sends text to a session, path, or address and
-reports **delivered** (consumed now) or **queued** (waiting on disk).
-`list_sessions` shows known sessions, presence, and queued mail. `/inbox`
-peeks without consuming.
+**Two tools.** `send_message` sends text to a session, path, address, or
+session id and reports **delivered** (consumed now) or **queued** (waiting
+on disk). `list_sessions` shows known sessions, presence, queued mail, and
+resume handles. `/inbox` peeks without consuming.
 
 **A CLI for everything that isn't a pi session.** `pi-post send` lets an
 autonomous run's exit hook, a Claude Code hook, or any script mail a
@@ -74,12 +80,13 @@ Nothing to enable; every session registers itself on startup.
 
 | Surface | Effect |
 |---|---|
-| `send_message` (tool) | Send text to a session, path, or address; reports **delivered** or **queued** |
-| `list_sessions` (tool) | Known sessions, presence, queued mail counts |
+| `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 list` / `peek` / `whoami` (CLI) | Inspect the registry, a mailbox, or your own address |
+| `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 [--all]` / `peek` / `whoami` (CLI) | Inspect the registry, a mailbox, or your own address |
 
 Ask in words; the model picks the tool.
 
@@ -98,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
+
+Two patterns cover real use; pick by whether the worker exists yet.
 
-Spawn first, send second — the brief starts the worker's first turn:
+**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
@@ -110,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.
@@ -145,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,8 +7,9 @@
  * 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>
  *   pi-post whoami
  *
@@ -31,12 +32,15 @@ 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");
 
 const h12 = (input) => createHash("sha256").update(input).digest("hex").slice(0, 12);
 const sessionAddress = (sessionId) => `s-${h12(`session\0${sessionId}`)}`;
+const looksLikeSessionId = (t) => /^[0-9a-f]{8}[0-9a-f-]{0,28}$/i.test(t);
+const resumeHandle = (sessionId) => (sessionId.length > 18 ? sessionId.slice(0, 18) : sessionId);
 
 function canonicalPath(path) {
   let expanded = path;
@@ -118,21 +122,36 @@ function resolveTarget(target) {
     }
     return pick(t, matches);
   }
+  if (looksLikeSessionId(t)) {
+    const bySessionId = records.filter((r) => r.sessionId.toLowerCase().startsWith(t.toLowerCase()));
+    if (bySessionId.length > 0) return pick(t, bySessionId);
+    // fall through: a hex-looking string may still be a session name
+  }
   const byName = records.filter((r) => r.name === t);
   const matches = byName.length > 0 ? byName : records.filter((r) => basename(r.cwd) === t);
   if (matches.length === 0) {
-    fail(`"${t}" is not an address, a directory with a registered session, or a known session name`);
+    fail(`"${t}" is not an address, a session id, a directory with a registered session, or a known session name`);
   }
   return pick(t, matches);
 }
 
 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);
@@ -162,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 = {
@@ -171,59 +201,118 @@ 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}`);
+  }
+}
+
+function queuedCount(address) {
+  try {
+    return readdirSync(join(root, "inbox", address)).filter((n) => n.endsWith(".json")).length;
+  } catch {
+    return 0;
   }
-  console.log(`${consumed ? "delivered" : "queued"} ${target.address} ${message.id}`);
 }
 
-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 queued = (() => {
-      try {
-        return readdirSync(join(root, "inbox", record.address)).filter((n) => n.endsWith(".json")).length;
-      } catch {
-        return 0;
-      }
-    })();
+    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}`);
+    console.log(
+      `${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. */
+function resolveCmd(args) {
+  const targetArg = args._[1];
+  if (!targetArg) fail("resolve requires a target (address, session id, path, or session name)");
+  const target = resolveTarget(targetArg);
+  const record = target.record;
+  if (!record) {
+    console.log(`address:  ${target.address}`);
+    console.log("no registry record — the session never registered here, or its record was swept");
+    return;
+  }
+  const queued = queuedCount(record.address);
+  console.log(`name:     ${record.name}`);
+  console.log(`address:  ${record.address}`);
+  console.log(`session:  ${record.sessionId}`);
+  console.log(`presence: ${isLive(record) ? "live" : "offline"}${queued > 0 ? `, ${queued} queued` : ""}`);
+  console.log(`cwd:      ${record.cwd}`);
+  console.log(`resume:   cd ${record.cwd} && pi --session ${resumeHandle(record.sessionId)}`);
 }
 
 function peek(args) {
@@ -265,7 +354,10 @@ switch (command) {
     await send(args);
     break;
   case "list":
-    list();
+    list(args);
+    break;
+  case "resolve":
+    resolveCmd(args);
     break;
   case "peek":
     peek(args);
@@ -274,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 | 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,57 +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 " +
-      "(s-…), 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 " +
+      "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({
-        description: "Session name, address (s-…/w-…), or directory path (e.g. ~/dev/repo)",
+      to: Type.Union([Type.String(), Type.Array(Type.String())], {
+        description:
+          "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 },
       };
     },
   });
@@ -188,21 +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), and " +
-      "queued mail counts. Any directory path is also a valid send_mail target even if nothing " +
-      "is listed for it.",
-    promptSnippet: "List pi sessions reachable by message, with presence and queued mail",
-    parameters: Type.Object({}),
-    async execute() {
-      const text = formatListing(root, listRecords(root), selfAddress);
+      "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({
+      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.3.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/address.ts

@@ -35,6 +35,15 @@ export function isAddress(value: string): boolean {
   return ADDRESS_RE.test(value);
 }
 
+/**
+ * Heuristic: does this target look like a pi session id, or a prefix of one?
+ * At least 8 leading hex chars keeps short hex-looking names out; resolution
+ * still falls through to name matching when no session id matches.
+ */
+export function looksLikeSessionId(value: string): boolean {
+  return /^[0-9a-f]{8}[0-9a-f-]{0,28}$/i.test(value);
+}
+
 /** Heuristic: does this target string denote a path (a query for the session running there)? */
 export function looksLikePath(target: string): boolean {
   return (

package/src/format.ts

@@ -23,15 +23,73 @@ export function formatDelivery(message: Message): string {
   ].join("\n");
 }
 
-export function formatListing(root: string, records: SessionRecord[], selfAddress?: string): string {
+/**
+ * Short resume handle for a pi session id. Three UUID groups: the UUIDv7
+ * millisecond timestamp plus 12 random bits — unique in practice even for
+ * sessions spawned in the same second, short enough to read and copy.
+ */
+export function resumeHandle(sessionId: string): string {
+  return sessionId.length > 18 ? sessionId.slice(0, 18) : sessionId;
+}
+
+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}`);
+    lines.push(
+      `${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("", "A directory path as a target resolves to the session registered in it.");
+  lines.push(
+    "",
+    "A directory path as a target resolves to the session registered in it.",
+    "Reopen a session with its bracketed pi --session command, run from its directory.",
+  );
   return lines.join("\n");
 }

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

@@ -1,5 +1,5 @@
 import { basename } from "node:path";
-import { canonicalPath, isAddress, looksLikePath } from "./address.ts";
+import { canonicalPath, isAddress, looksLikePath, looksLikeSessionId } from "./address.ts";
 import { listRecords, presence, type SessionRecord } from "./registry.ts";
 
 export interface ResolvedTarget {
@@ -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");
@@ -36,9 +46,10 @@ function pick(target: string, matches: SessionRecord[]): ResolvedTarget {
 }
 
 /**
- * Resolve a target string to a session address. Targets name sessions that
- * exist — a directory path is a *query* for the session registered in it,
- * not an address of its own. Refuses rather than guesses.
+ * Resolve a target string to a session address. Every handle a session has
+ * resolves: an address, a directory path (a *query* for the session
+ * registered there), pi's own session id (or a unique prefix), or a name.
+ * Refuses rather than guesses.
  */
 export function resolveTarget(root: string, target: string, cwd?: string): ResolvedTarget {
   const trimmed = target.trim();
@@ -61,12 +72,35 @@ export function resolveTarget(root: string, target: string, cwd?: string): Resol
     return pick(trimmed, matches);
   }
 
+  if (looksLikeSessionId(trimmed)) {
+    const lower = trimmed.toLowerCase();
+    const bySessionId = records.filter((r) => r.sessionId.toLowerCase().startsWith(lower));
+    if (bySessionId.length > 0) return pick(trimmed, bySessionId);
+    // fall through: a hex-looking string may still be a session name
+  }
+
   const byName = records.filter((r) => r.name === trimmed);
   const matches = byName.length > 0 ? byName : records.filter((r) => basename(r.cwd) === trimmed);
   if (matches.length === 0) {
     throw new UnknownTargetError(
-      `"${trimmed}" is not an address, a directory with a registered session, or a known session name`,
+      `"${trimmed}" is not an address, a session id, a directory with a registered session, or a known session name`,
     );
   }
   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()];
+}