pi-post 0.6.3 → 0.7.1

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
@@ -74,7 +76,7 @@ inert.
 pi install npm:pi-post
 ```
 
-Nothing to enable; every session registers itself on startup.
+Nothing to enable; every session registers itself on startup. Once a session has started, the CLI is also available at `~/.pi/agent/post/bin/pi-post` for hooks and scripts on hosts where `pi-post` is not on `PATH`.
 
 ## Use
 
@@ -181,9 +183,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 +246,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

@@ -6,6 +6,8 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import type { FSWatcher } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
 import { canonicalPath, sessionAddress } from "../src/address.ts";
 import { createMessage, type Message } from "../src/message.ts";
 import {
@@ -31,8 +33,10 @@ import {
   writeRecord,
 } from "../src/registry.ts";
 import { resolveTargets } from "../src/resolve.ts";
+import { ensureCliShim } from "../src/cli-shim.ts";
 
 const HEARTBEAT_MS = 30_000;
+const CLI_TARGET = resolve(dirname(fileURLToPath(import.meta.url)), "../bin/pi-post.mjs");
 
 export default function (pi: ExtensionAPI) {
   const root = postRoot();
@@ -94,6 +98,7 @@ export default function (pi: ExtensionAPI) {
     process.env.PI_SESSION_ADDRESS = selfAddress;
 
     ensureDirs(root, selfAddress);
+    ensureCliShim(root, CLI_TARGET);
     writeRecord(root, {
       v: 1,
       address: selfAddress,

package/package.json

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

package/src/cli-shim.ts

@@ -0,0 +1,25 @@
+import { existsSync, lstatSync, mkdirSync, readlinkSync, symlinkSync, unlinkSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+/** Ensure the mailbox-owned CLI path points at the package's own executable. */
+export function ensureCliShim(baseDir: string, targetPath: string): void {
+  const shimDir = join(baseDir, "bin");
+  const shimPath = join(shimDir, "pi-post");
+  try {
+    mkdirSync(shimDir, { recursive: true, mode: 0o700 });
+
+    try {
+      if (lstatSync(shimPath).isSymbolicLink()) {
+        const linkTarget = readlinkSync(shimPath);
+        if (resolve(dirname(shimPath), linkTarget) === resolve(targetPath) && existsSync(targetPath)) return;
+      }
+      unlinkSync(shimPath);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    }
+
+    symlinkSync(targetPath, shimPath);
+  } catch {
+    // A CLI convenience must never prevent a session from starting.
+  }
+}