pi-post 0.6.1 → 0.6.3

package/DESIGN.md

@@ -51,9 +51,9 @@ 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:
+messages 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
-standing mail raced among concurrent sessions, delivered to the wrong
+standing messages raced among concurrent sessions, delivered to the wrong
 successor, and — because consumption is the receipt — misdelivered
 *silently and destructively*. The lesson is recorded as a non-goal
 below: how sessions come to exist is not the transport's business.
@@ -93,11 +93,11 @@ One message per file, named `<sentAt ms, 13 digits>-<8 hex nonce>.json`:
    it. Nothing is delivered twice; consumption is the receipt.
 5. Each message passes the inbound guard (mode + loop caps), then enters
    context wrapped in the boundary preamble:
-   - live mail → `deliverAs: "steer"`, `triggerTurn: true` — lands between
+   - live messages → `deliverAs: "steer"`, `triggerTurn: true` — land between
      tool calls; **wakes an idle session**, so a freshly spawned worker's
      first turn can be the brief itself
    - startup/resume drain → `deliverAs: "nextTurn"` — waits in context for
-     the next prompt; queued mail never starts a turn on its own
+     the next prompt; a queued message never starts a turn on its own
 
 ## The boundary
 
@@ -116,8 +116,8 @@ 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, and
-  queued mail pins the target's registry record: a record is swept only
+- **Messages outrank tidiness.** No sweep deletes a non-empty mailbox, and
+  queued messages pin 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

package/README.md

@@ -39,7 +39,7 @@ smuggling state between sessions.
 
 **An address that outlives the process.** A session address names a
 conversation, not a process: the same session resumed tomorrow answers to
-the same address, and mail queued while it was closed lands in-context on
+the same address, and messages queued while it was closed land in-context on
 resume. A directory path as a target is a *query* — it resolves to the
 session registered in that directory, live sessions first, ambiguity
 refused.
@@ -52,15 +52,15 @@ 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.
+worker's first turn. No "check your messages" incantations.
 
 **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
+on disk). `list_sessions` shows known sessions, presence, queued messages, 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
+autonomous run's exit hook, a Claude Code hook, or any script message a
 session. `--reply-to` defaults from `PI_SESSION_ID`, so a message sent from
 inside a pi bash tool routes replies home automatically.
 
@@ -81,7 +81,7 @@ Nothing to enable; every session registers itself on startup.
 | Surface | Effect |
 |---|---|
 | `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` |
+| `list_sessions` (tool) | Known sessions, live first with ages, queued message counts, resume handles; stale offline rows collapse unless `all` |
 | `/inbox` | Peek at this session's queued messages without consuming them |
 | `/sessions` | The `list_sessions` listing, without spending a model turn |
 | `pi-post send` (CLI) | Send from any process: `--to` (repeatable), `--body`/stdin, `--from`, `--reply-to` |
@@ -145,6 +145,11 @@ sessions can read state; only one can consume a message.
 | `PI_POST_FROM` | — | Default `--from` label for the CLI |
 | `PI_POST_REPLY_TO` | — | Default `--reply-to` address for the CLI |
 
+The extension also *sets* one variable: `PI_SESSION_ADDRESS`, the session's
+own `s-…` address, exported at session start so child processes (bash tools,
+spawned scripts) can capture a reply target without shelling out to
+`pi-post whoami`.
+
 The directory is created `0700` and messages `0600`.
 
 ## Limits
@@ -195,7 +200,8 @@ before changing behavior, and never weaken a case to make a change pass.
 - [pi-intercom](https://www.npmjs.com/package/pi-intercom) -- broker-based
   1:1 session messaging with a TUI overlay and pi-subagents integration.
 - [pi-messenger](https://www.npmjs.com/package/pi-messenger) -- a shared
-  chat room with file reservations, built for swarms rather than mail.
+  chat room with file reservations, built for swarms rather than
+  point-to-point messaging.
 
 ## Development
 

package/bin/pi-post.mjs

@@ -277,15 +277,15 @@ function list(args) {
   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.
+    // Stale offline rows collapse into a count — unless they hold messages.
     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` : "";
+    const queuedNote = queued > 0 ? `, ${queued} queued` : "";
     console.log(
-      `${record.name} — ${record.address} (${state}${mail}) ${record.cwd} ` +
+      `${record.name} — ${record.address} (${state}${queuedNote}) ${record.cwd} ` +
         `[pi --session ${resumeHandle(record.sessionId)}]`,
     );
   }

package/extensions/pi-post.ts

@@ -88,6 +88,10 @@ export default function (pi: ExtensionAPI) {
     const canonical = canonicalPath(ctx.cwd);
     selfAddress = sessionAddress(sessionId);
     selfName = pi.getSessionName() ?? defaultSessionName(canonical, selfAddress);
+    // Expose the address to child processes (bash tools inherit process.env),
+    // so scripts can capture a send_message target without shelling out to
+    // `pi-post whoami` or re-deriving the hash from PI_SESSION_ID.
+    process.env.PI_SESSION_ADDRESS = selfAddress;
 
     ensureDirs(root, selfAddress);
     writeRecord(root, {
@@ -103,11 +107,11 @@ export default function (pi: ExtensionAPI) {
     sweepRegistry(root);
     sweepInboxes(root);
 
-    // Queued mail waits in context for the first prompt; it never starts a turn.
+    // Queued messages wait in context for the first prompt; they never start a turn.
     await drainAll(ctx, "nextTurn");
 
-    const onMail = () => void drainAll(ctx, "steer");
-    watchers = [watchInbox(root, selfAddress, onMail)];
+    const onMessage = () => void drainAll(ctx, "steer");
+    watchers = [watchInbox(root, selfAddress, onMessage)];
     heartbeat = setInterval(() => selfAddress && touchRecord(root, selfAddress), HEARTBEAT_MS);
     heartbeat.unref?.();
   });
@@ -209,12 +213,12 @@ export default function (pi: ExtensionAPI) {
     label: "List Sessions",
     description:
       "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 " +
+      "with age), queued message 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",
+      "List pi sessions reachable by message, with presence, queued messages, and resume handles",
     parameters: Type.Object({
       all: Type.Optional(
         Type.Boolean({

package/package.json

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

package/src/format.ts

@@ -68,16 +68,16 @@ export function formatListing(
     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.
+    // Stale offline rows collapse into a count — unless they hold messages
+    // (messages outrank 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` : "";
+    const queuedNote = queued > 0 ? `, ${queued} queued` : "";
     lines.push(
-      `${record.name} — ${record.address} (${state}${mail})${self ? " [self]" : ""} ${record.cwd} ` +
+      `${record.name} — ${record.address} (${state}${queuedNote})${self ? " [self]" : ""} ${record.cwd} ` +
         `[pi --session ${resumeHandle(record.sessionId)}]`,
     );
   }

package/src/registry.ts

@@ -93,7 +93,7 @@ export function presence(record: SessionRecord): Presence {
 
 /**
  * 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
+ * whose mailbox holds messages is never swept: queued messages 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.
  */
@@ -102,7 +102,7 @@ export function sweepRegistry(root: string, maxAgeMs = 7 * 24 * 60 * 60 * 1000):
   for (const record of listRecords(root)) {
     if (presence(record) !== "offline") continue;
     if (now - record.lastSeen <= maxAgeMs) continue;
-    if (queuedCount(root, record.address) > 0) continue; // mail keeps the record alive
+    if (queuedCount(root, record.address) > 0) continue; // queued messages keep the record alive
     try {
       unlinkSync(join(registryDir(root), `${record.address}.json`));
     } catch {
@@ -114,8 +114,8 @@ export function sweepRegistry(root: string, maxAgeMs = 7 * 24 * 60 * 60 * 1000):
 /**
  * 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.
+ * directories, so a queued message or a mid-flight `.tmp` deposit blocks removal
+ * structurally — messages outrank tidiness.
  */
 export function sweepInboxes(root: string): void {
   const known = new Set(listRecords(root).map((r) => r.address));