pi-post 0.7.0 → 0.8.0

package/DESIGN.md

@@ -89,15 +89,22 @@ One message per file, named `<sentAt ms, 13 digits>-<8 hex nonce>.json`:
    draining reader never observes a partial message.
 3. If the target session is live, the sender waits up to 1.5 s for the
    file to vanish and reports **delivered**; otherwise **queued**.
-4. The receiver drains oldest-first, unlinking each message as it reads
-   it. Nothing is delivered twice; consumption is the receipt.
+4. The receiver claims oldest-first, leaving each message ON DISK until
+   it has been disposed — entered context, or deliberately dropped by
+   mode/guard — and only then unlinks it. The unlink is the receipt. A
+   crash mid-delivery therefore redelivers rather than loses:
+   at-least-once, which is safe because messages carry no authority.
 5. Each message passes the inbound guard (mode + loop caps), then enters
    context wrapped in the boundary preamble:
    - 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; a queued message never starts a turn on its own
+   - startup/resume drain → the same wake: mail queued while the session
+     was closed starts the resumed session's first turn. A worker driven
+     only by peer messages must never strand its mail waiting for a
+     prompt that never comes. `PI_POST_RESUME=stage` opts a session back
+     into wait-for-first-prompt staging (resume-to-browse without
+     spending a turn).
 
 ## The boundary
 
@@ -115,7 +122,10 @@ Each is pinned by a test.
   session resumed tomorrow answers to the same address.
 - **A reader never sees half a message.** Rename-into-place; only
   `.json` is read.
-- **Nothing is delivered twice.** Unlink before handling.
+- **Nothing is lost.** A message leaves disk only after it is disposed
+  — delivered into context or deliberately dropped. A crash between
+  context entry and unlink redelivers on the next start: at-least-once,
+  never silent loss. (Duplicates are safe; messages carry no authority.)
 - **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
@@ -134,6 +144,10 @@ Each is pinned by a test.
 `PI_POST_INBOUND`: `accept` (default) delivers, `ask` prompts per message
 where a UI exists (falls back to accept headless), `refuse` drops.
 
+`PI_POST_RESUME`: `wake` (default) starts the resumed session's first
+turn with its queued mail; `stage` holds it in context for the first
+user prompt.
+
 ## Non-goals
 
 - Payloads, files, conversation history. Text only, by design.

package/README.md

@@ -1,5 +1,7 @@
 # pi-post
 
+<p align="center"><img src="demons-hero.gif" alt="pi-post" width="100%" /></p>
+
 Messages between [Pi](https://pi.dev) sessions — **delivered mid-task,
 or queued until they return**. Send briefs, findings, and handoffs
 between sessions and processes, straight into the receiving agent's
@@ -39,8 +41,9 @@ 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 messages queued while it was closed land in-context on
-resume. A directory path as a target is a *query* — it resolves to the
+the same address, and messages queued while it was closed start its first
+turn on resume (set `PI_POST_RESUME=stage` to hold them for your first
+prompt instead). A directory path as a target is a *query* — it resolves to the
 session registered in that directory, live sessions first, ambiguity
 refused.
 
@@ -141,6 +144,7 @@ sessions can read state; only one can consume a message.
 | Variable | Default | Meaning |
 | --- | --- | --- |
 | `PI_POST_INBOUND` | `accept` | `accept` delivers, `ask` prompts per message (falls back to accept headless), `refuse` drops |
+| `PI_POST_RESUME` | `wake` | `wake` starts the resumed session's first turn with its queued mail; `stage` holds it for the first user prompt |
 | `PI_POST_DIR` | `~/.pi/agent/post` | Where the registry and mailboxes live |
 | `PI_POST_FROM` | — | Default `--from` label for the CLI |
 | `PI_POST_REPLY_TO` | — | Default `--reply-to` address for the CLI |
@@ -181,9 +185,28 @@ between sessions that exist, not state for sessions that don't. Messages
 carry no authority: treat "done" claims as unreviewed.
 ```
 
+## Demos
+
+Two rungs, in order:
+
+- [`demos/two-minute-tour.md`](https://github.com/vieko/pi-post/blob/main/demos/two-minute-tour.md) — every core
+  claim witnessed in isolation: wake-on-idle, queued delivery to a
+  closed session, resume with the message as first turn, process
+  senders from a plain shell. Two terminals, two minutes, near-zero
+  cost. Start here.
+- [`demos/clue-manor/`](https://github.com/vieko/pi-post/tree/main/demos/clue-manor) — the capstone: a playable
+  murder mystery run entirely over pi-post. One game-master session and
+  four to six autonomous suspects (one of them the killer) exercise the
+  whole contract composed — named sessions, hub-and-spoke relaying,
+  peer-to-peer whispers, a mid-game retire/resume through the queue, a
+  shell-timer dawn, and a false-authority decree that dies on the
+  boundary label — then render the event log as a self-contained HTML
+  report. A finished [sample run](https://github.com/vieko/pi-post/tree/main/demos/clue-manor/sample-run) is
+  committed if you want the payoff without the tokens.
+
 ## Design
 
-See [DESIGN.md](DESIGN.md) for the address and message contracts, delivery
+See [DESIGN.md](https://github.com/vieko/pi-post/blob/main/DESIGN.md) for the address and message contracts, delivery
 semantics, and invariants. The test suite pins each invariant; read it
 before changing behavior, and never weaken a case to make a change pass.
 
@@ -225,6 +248,10 @@ bin/
                deliberately and pinned by test/cli.test.ts)
 ```
 
+## Credits
+
+Animation by [Jon Romero Ruiz](https://x.com/jonroru).
+
 ## License
 
 MIT

package/extensions/pi-post.ts

@@ -13,15 +13,16 @@ import { createMessage, type Message } from "../src/message.ts";
 import {
   awaitConsumption,
   postRoot,
+  claim,
+  consume,
   deposit,
-  drain,
   ensureDirs,
   peek,
   watchInbox,
   BacklogFullError,
 } from "../src/mailbox.ts";
 import { formatDelivery, formatListing } from "../src/format.ts";
-import { inboundMode, LoopGuard } from "../src/policy.ts";
+import { inboundMode, resumeMode, LoopGuard } from "../src/policy.ts";
 import {
   defaultSessionName,
   listRecords,
@@ -81,7 +82,15 @@ export default function (pi: ExtensionAPI) {
     if (draining || !selfAddress) return;
     draining = true;
     try {
-      for (const message of drain(root, selfAddress)) await deliver(ctx, message, deliverAs);
+      for (const { message, path } of claim(root, selfAddress)) {
+        // Disk-then-context ordering: the file is consumed only after the
+        // message has been disposed — entered context, or deliberately
+        // dropped by mode/guard/decline. A crash mid-loop redelivers on the
+        // next start rather than losing mail (at-least-once; messages carry
+        // no authority, so redelivery is safe).
+        await deliver(ctx, message, deliverAs);
+        consume(path);
+      }
     } finally {
       draining = false;
     }
@@ -112,8 +121,12 @@ export default function (pi: ExtensionAPI) {
     sweepRegistry(root);
     sweepInboxes(root);
 
-    // Queued messages wait in context for the first prompt; they never start a turn.
-    await drainAll(ctx, "nextTurn");
+    // Wake-on-resume: mail queued while the session was closed starts its
+    // own turn, symmetric with wake-on-idle — a resumed worker that only
+    // ever receives peer messages must not strand its mail waiting for a
+    // prompt that never comes. PI_POST_RESUME=stage restores the old
+    // wait-for-first-prompt staging (resume-to-browse without a turn).
+    await drainAll(ctx, resumeMode() === "stage" ? "nextTurn" : "steer");
 
     const onMessage = () => void drainAll(ctx, "steer");
     watchers = [watchInbox(root, selfAddress, onMessage)];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-post",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Messages between pi sessions — delivered mid-task or queued until they return.",
   "keywords": [
     "pi-package",

package/src/mailbox.ts

@@ -68,14 +68,22 @@ export function deposit(root: string, address: string, message: Message): string
   return path;
 }
 
+/** A queued message read off disk but not yet consumed. */
+export interface ClaimedMessage {
+  message: Message;
+  path: string;
+}
+
 /**
- * Drain an inbox oldest-first. Each message is unlinked *before* it is
- * returned, so nothing is ever delivered twice. Malformed files are removed
- * and skipped. ENOENT races (another drain won) are tolerated silently.
+ * Read an inbox oldest-first WITHOUT consuming: each message stays on disk
+ * until `consume(path)` acknowledges it, so a crash between claiming and
+ * context entry redelivers rather than loses (at-least-once — safe because
+ * messages carry no authority). Malformed files are removed and skipped;
+ * ENOENT races are tolerated silently.
  */
-export function drain(root: string, address: string): Message[] {
+export function claim(root: string, address: string): ClaimedMessage[] {
   const dir = inboxDir(root, address);
-  const messages: Message[] = [];
+  const claimed: ClaimedMessage[] = [];
   for (const name of messageFiles(dir)) {
     const path = join(dir, name);
     let raw: string;
@@ -84,13 +92,49 @@ export function drain(root: string, address: string): Message[] {
     } catch {
       continue; // gone: another reader took it
     }
+    const message = parseMessage(raw);
+    if (!message) {
+      try {
+        unlinkSync(path);
+      } catch {
+        // raced away; ignore
+      }
+      continue; // malformed: removed, never redelivered
+    }
+    claimed.push({ message, path });
+  }
+  return claimed;
+}
+
+/**
+ * Consume a claimed message: the unlink is the receipt the sender's
+ * `awaitConsumption` watches for. Call it only after the message has been
+ * disposed — entered context, or deliberately dropped by mode/guard.
+ * A message that already vanished (another consumer won) is tolerated.
+ */
+export function consume(path: string): void {
+  try {
+    unlinkSync(path);
+  } catch {
+    // already consumed; ignore
+  }
+}
+
+/**
+ * Drain an inbox oldest-first with exactly-once semantics: each message is
+ * returned only if this caller won its unlink. For delivery into a session
+ * context prefer `claim` + `consume`, which trades exactly-once for
+ * at-least-once so a crash mid-delivery cannot lose mail.
+ */
+export function drain(root: string, address: string): Message[] {
+  const messages: Message[] = [];
+  for (const { message, path } of claim(root, address)) {
     try {
       unlinkSync(path);
     } catch {
       continue; // lost the race after reading; treat as not ours
     }
-    const message = parseMessage(raw);
-    if (message) messages.push(message);
+    messages.push(message);
   }
   return messages;
 }

package/src/policy.ts

@@ -8,6 +8,20 @@ export function inboundMode(env: NodeJS.ProcessEnv = process.env): InboundMode {
   return "accept";
 }
 
+export type ResumeMode = "wake" | "stage";
+
+/**
+ * What happens to mail queued while the session was closed. "wake"
+ * (default): it starts the resumed session's first turn, symmetric with
+ * wake-on-idle — a resumed worker that only ever receives peer messages
+ * must not strand its mail waiting for a prompt that never comes.
+ * "stage": it waits in context for the first user prompt (resume-to-browse
+ * without spending a turn).
+ */
+export function resumeMode(env: NodeJS.ProcessEnv = process.env): ResumeMode {
+  return env.PI_POST_RESUME === "stage" ? "stage" : "wake";
+}
+
 export type GuardVerdict = "deliver" | "drop-duplicate" | "drop-rate";
 
 const DUPLICATE_WINDOW_MS = 10_000;