pi-post 0.3.0 → 0.4.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

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,11 +80,12 @@ 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 a session, path, address, or session id; reports **delivered** or **queued** |
+| `list_sessions` (tool) | Known sessions, presence, queued mail counts, resume handles |
 | `/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 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 |
 
 Ask in words; the model picks the tool.

package/bin/pi-post.mjs

@@ -9,6 +9,7 @@
  *
  *   pi-post send --to <target> [--body <text>] [--from <label>] [--reply-to <addr>|none]
  *   pi-post list
+ *   pi-post resolve <target>
  *   pi-post peek <target>
  *   pi-post whoami
  *
@@ -37,6 +38,8 @@ 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,10 +121,15 @@ 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);
 }
@@ -207,6 +215,14 @@ async function send(args) {
   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;
+  }
+}
+
 function list() {
   const records = listRecords().sort((a, b) => b.lastSeen - a.lastSeen);
   if (records.length === 0) {
@@ -214,16 +230,33 @@ function list() {
     return;
   }
   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 queued = queuedCount(record.address);
     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} (${isLive(record) ? "live" : "offline"}${mail}) ${record.cwd} ` +
+        `[pi --session ${resumeHandle(record.sessionId)}]`,
+    );
+  }
+}
+
+/** 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) {
@@ -267,6 +300,9 @@ switch (command) {
   case "list":
     list();
     break;
+  case "resolve":
+    resolveCmd(args);
+    break;
   case "peek":
     peek(args);
     break;
@@ -275,6 +311,6 @@ switch (command) {
     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("       pi-post list | resolve <target> | peek <target> | whoami");
     process.exit(command ? 1 : 0);
 }

package/extensions/pi-post.ts

@@ -130,8 +130,8 @@ export default function (pi: ExtensionAPI) {
     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 " +
+      "(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 " +
@@ -143,7 +143,8 @@ export default function (pi: ExtensionAPI) {
     ],
     parameters: Type.Object({
       to: Type.String({
-        description: "Session name, address (s-…/w-…), or directory path (e.g. ~/dev/repo)",
+        description:
+          "Session name, address (s-…), session id (or unique prefix), or directory path (e.g. ~/dev/repo)",
       }),
       body: Type.String({ description: "Plain-text message body (≤ 32 KiB)" }),
       reply_to: Type.Optional(
@@ -188,10 +189,12 @@ 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",
+      "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.",
+    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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-post",
-  "version": "0.3.0",
+  "version": "0.4.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,31 @@ export function formatDelivery(message: Message): string {
   ].join("\n");
 }
 
+/**
+ * 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;
+}
+
 export function formatListing(root: string, records: SessionRecord[], selfAddress?: string): string {
   const lines: string[] = [];
   for (const record of [...records].sort((a, b) => b.lastSeen - a.lastSeen)) {
     const self = record.address === selfAddress ? " [self]" : "";
     const queued = queuedCount(root, record.address);
     const mail = queued > 0 ? `, ${queued} queued` : "";
-    lines.push(`${record.name} — ${record.address} (${presence(record)}${mail})${self} ${record.cwd}`);
+    lines.push(
+      `${record.name} — ${record.address} (${presence(record)}${mail})${self} ${record.cwd} ` +
+        `[pi --session ${resumeHandle(record.sessionId)}]`,
+    );
   }
   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/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 {
@@ -36,9 +36,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,11 +62,18 @@ 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);