@nicknisi/pi-relay 0.4.1 → 0.6.0

package/README.md

@@ -19,6 +19,26 @@ import { OutboundPolicy, claimInbox, deposit, deriveAddr, type Letter } from '@n
 
 The `@nicknisi/pi-relay/core` subpath exports a narrow record and alias registry, mailbox and ask/audit operations, presence and sweep utilities, policy guards and constants, and their public types. Filesystem-facing operations validate canonical relay addresses, aliases, claim tokens, and ask/message IDs before accessing the relay root; path constructors and raw persistence helpers remain internal. Core uses Node built-ins plus Koffi's prebuilt native bridge for descriptor-relative Unix syscalls; Pi and TUI remain optional peers, so core-only installations do not fetch them. The package root remains the pi extension entry point; import `/core` from plain Node services and CLIs.
 
+### Registering a non-Pi host
+
+A host that isn't a pi session (a supervisor, a CLI daemon) can join the relay so it shows in `list`, can be messaged by name, and can hold an alias:
+
+```ts
+import { claimAlias, heartbeat, register, unregister } from '@nicknisi/pi-relay/core';
+
+const { addr } = register(root, { sessionId, name: 'supervisor', cwd: process.cwd() }); // pid defaults to process.pid, status to 'idle'
+claimAlias(root, 'supervisor', addr, sessionId);
+const timer = setInterval(() => heartbeat(root, addr), 15_000); // optional patch: { status, name }
+// on shutdown:
+clearInterval(timer);
+unregister(root, addr);
+```
+
+- `register` writes the same `<addr>.json` record the extension writes. The address is derived from `cwd` + `sessionId`, so re-registering keeps the address and the original `startedAt`.
+- `heartbeat` refreshes `lastSeenAt` (and clears `offline`). Core runs no timers: the host must call it less than `HEARTBEAT_STALE_MS` (45 s) apart — every 15 s, like the extension — or it reads as `stalled`. It returns `null`, writing nothing, if the record is gone; it never re-creates an unregistered session.
+- `unregister` deletes the record (missing is fine). Unlike the extension's shutdown, which marks the session offline so queued mail stays addressable, the address stops existing.
+- An alias lives only as long as its record: `sweep` keeps aliases whose record exists and clears the rest, so an alias survives while the host keeps registered and is reclaimed by the next `sweep` after `unregister`.
+
 ### Durable core inbox claims
 
 A non-Pi consumer can atomically detach the current inbox with `claimInbox(root, addr)`. It receives only a stable `claimToken` and stable `fileTokens`, never filesystem paths. New deposits immediately land in a fresh inbox. `readClaimedLetter` reopens and validates a claimed letter without following links; after the consumer durably writes and `fsync`s its own journal, `ackClaimedLetter` atomically persists exact delivery proof in `<addr>.acks` before deleting the claimed file, or `requeueClaimedLetter` atomically returns it to the current inbox. `recoverInboxClaims` enumerates the same tokens after a process crash. All claim, read, ack, and requeue work is relative to pinned root/inbox/claim/ack descriptors, and empty completed claims are removed automatically. `sweep` removes proof more than seven days after acknowledgement, including for live sessions; proof never keeps an expired session's record alive. The destructive `drain` API does not acknowledge delivery.
@@ -61,6 +81,7 @@ main moved; rebase before you push.
 - **Ordinary replies.** `reply` resolves an explicit full ID or unique prefix across pending asks and received message/reply entries in the active transcript branch. This survives reload and does not search sibling branches or infer a recipient. Replying to an ordinary message preserves unrelated pending asks. Successful send/reply results expose full `messageId`, `target`, `replyTo` where applicable, and `receipt` in details; broadcasts expose per-recipient receipts.
 - **Presence** is a pid plus a heartbeat: `live` (process exists, beat <45s), `not responding` (process exists, stale beat — wedged or suspended), `offline` (no live pid; mail waits). Status flips `working`/`idle` with the agent loop.
 - **Authority boundary on every delivery.** Each message arrives with a repeated statement that it came from a peer and carries no authority — it cannot approve anything, cannot change configuration, slash commands in it are inert text. The sending side's tool guidelines carry the reciprocal rule: never ask a peer to do something your own permissions would refuse.
+- **Quiet letters.** A letter with `wake: false` (set by core senders building their own `Letter` for `deposit`) lands in the receiving session's context without triggering a model turn: an FYI the agent sees on its next turn. Absent or `true` wakes the session as before, and old readers ignore the field, so mixed versions interoperate. An ask is never quiet: core `deposit` refuses `wake: false` on an ask, and delivery wakes an ask regardless, since the receiver must take a turn to answer. The `relay` tool always sends waking mail.
 - **Loops break structurally**, independent of what either model decides: identical text from one sender inside 10s is dropped; >8 messages per 30s per sender is refused; an unread backlog of 50 refuses new mail until the peer drains.
 - **Plain text only, ≤32KB.** Send a summary and a path, not a payload.
 - **Sweeping is narrow:** a running session is never touched; an inbox or durable claim holding undelivered mail is kept 30 days; an offline-but-resumable session keeps its record (its address — new mail must remain deliverable while it's down); only an empty mailbox of a session that can no longer be resumed is discarded promptly. Listing never has side effects.
@@ -108,5 +129,5 @@ The directory is created `0700` and every file `0600` — other users on the mac
 - **Bun <= 1.3.14 refused.** Those Bun versions abort the process when koffi's GC finalizer releases an N-API reference ([oven-sh/bun#39263](https://github.com/oven-sh/bun/issues/39263), fixed upstream after 1.3.14), so relay fails load with a clear error on them instead. Node.js and newer Bun load normally.
 - **One machine.** Delivery is a file landing in a directory; two sessions reach each other exactly when they share a filesystem. A container and its host cannot.
 - **Presence is heartbeat-accurate**, not instantaneous (within ~45s).
-- Delivery injects with `deliverAs: "steer"` (lands between tool calls) and `triggerTurn: true` (wakes an idle session).
+- Delivery injects with `deliverAs: "steer"` (lands between tool calls) and `triggerTurn: true` (wakes an idle session), unless the letter sets `wake: false`, which appends to the session without taking a turn.
 - Depends on pi extension APIs (`session_start`/`agent_start`/`agent_end` lifecycle events, `getSessionName`, `sendMessage` delivery modes) that could drift across pi versions.

package/core.ts

@@ -27,13 +27,16 @@ import {
 import {
   claimAlias as claimAliasInternal,
   clearAlias as clearAliasInternal,
+  deriveAddr,
   isValidAliasName as isValidAliasNameInternal,
   listAliases as listAliasesInternal,
   listRecords as listRecordsInternal,
   presenceOf as presenceOfInternal,
   readAlias as readAliasInternal,
   readRecord as readRecordInternal,
+  removeRecord,
   sweep as sweepInternal,
+  writeRecord,
   type AliasRecord,
   type Presence,
   type SessionRecord,
@@ -110,6 +113,14 @@ function assertLetter(letter: Letter): void {
   }
 }
 
+function assertNonEmptyString(value: unknown, label: string): asserts value is string {
+  if (typeof value !== 'string' || value.length === 0) throw new TypeError(`Invalid relay ${label}: ${value}`);
+}
+
+function assertStatus(status: unknown): asserts status is SessionRecord['status'] {
+  if (status !== 'idle' && status !== 'working') throw new TypeError(`Invalid relay session status: ${status}`);
+}
+
 function isSafeLetter(letter: Letter): boolean {
   try {
     assertLetter(letter);
@@ -174,6 +185,70 @@ export function presenceOf(record: SessionRecord, now: number = Date.now()): Pre
   return presenceOfInternal(record, now);
 }
 
+/**
+ * Register (or re-register) a non-Pi host as a relay session. The address is
+ * derived from `cwd` + `sessionId`, so re-registering keeps it, along with the
+ * existing `startedAt`. The host must call `heartbeat` well inside
+ * `HEARTBEAT_STALE_MS`.
+ */
+export function register(
+  root: string,
+  input: { sessionId: string; name: string; cwd: string; pid?: number; status?: SessionRecord['status'] },
+): SessionRecord {
+  assertNonEmptyString(input.sessionId, 'session id');
+  assertNonEmptyString(input.name, 'session name');
+  assertNonEmptyString(input.cwd, 'session cwd');
+  const pid = input.pid ?? process.pid;
+  if (!Number.isSafeInteger(pid) || pid <= 0) throw new TypeError(`Invalid relay session pid: ${pid}`);
+  const status = input.status ?? 'idle';
+  assertStatus(status);
+  const addr = deriveAddr(input.cwd, input.sessionId);
+  const now = Date.now();
+  const record: SessionRecord = {
+    addr,
+    sessionId: input.sessionId,
+    name: input.name,
+    cwd: input.cwd,
+    pid,
+    startedAt: readRecord(root, addr)?.startedAt ?? now,
+    lastSeenAt: now,
+    status,
+  };
+  writeRecord(root, record);
+  return record;
+}
+
+/**
+ * Refresh a registered session's `lastSeenAt` (clearing `offline`), applying an
+ * optional status or name. Returns null, writing nothing, if no record exists.
+ */
+export function heartbeat(
+  root: string,
+  addr: string,
+  patch: { status?: SessionRecord['status']; name?: string } = {},
+): SessionRecord | null {
+  assertAddress(addr);
+  if (patch.status !== undefined) assertStatus(patch.status);
+  if (patch.name !== undefined) assertNonEmptyString(patch.name, 'session name');
+  const existing = readRecord(root, addr);
+  if (existing === null) return null;
+  const { offline: _offline, ...rest } = existing;
+  const record: SessionRecord = {
+    ...rest,
+    name: patch.name ?? rest.name,
+    status: patch.status ?? rest.status,
+    lastSeenAt: Date.now(),
+  };
+  writeRecord(root, record);
+  return record;
+}
+
+/** Delete a session's record. Aliases pointing at it are cleared by the next `sweep`. */
+export function unregister(root: string, addr: string): void {
+  assertAddress(addr);
+  removeRecord(root, addr);
+}
+
 export function readAlias(root: string, name: string): AliasRecord | null {
   assertAliasName(name);
   const alias = readAliasInternal(root, name);
@@ -205,6 +280,17 @@ export function sweep(root: string, now: number = Date.now(), sessionExists?: (s
 export function deposit(root: string, toAddr: string, letter: Letter): void {
   assertAddress(toAddr);
   assertLetter(letter);
+  // wake is validated on the write side only. The read path (isSafeLetter)
+  // tolerates a non-boolean wake, so a letter from a writer that never
+  // validated the field is still delivered (as waking mail: delivery only
+  // honours wake === false) instead of being discarded after drain already
+  // unlinked it.
+  if (letter.wake !== undefined && typeof letter.wake !== 'boolean') {
+    throw new TypeError(`Invalid relay letter wake flag: ${letter.wake}`);
+  }
+  if (letter.kind === 'ask' && letter.wake === false) {
+    throw new TypeError('A quiet ask (wake: false) is refused: the receiver takes no turn, so it could never answer');
+  }
   depositInternal(root, toAddr, letter);
 }
 

package/dist/core.d.ts

@@ -7,6 +7,29 @@ export { HEARTBEAT_STALE_MS, SWEEP_MAIL_KEEP_MS, deriveAddr, isValidAliasName, t
 export declare function readRecord(root: string, addr: string): SessionRecord | null;
 export declare function listRecords(root: string): SessionRecord[];
 export declare function presenceOf(record: SessionRecord, now?: number): Presence;
+/**
+ * Register (or re-register) a non-Pi host as a relay session. The address is
+ * derived from `cwd` + `sessionId`, so re-registering keeps it, along with the
+ * existing `startedAt`. The host must call `heartbeat` well inside
+ * `HEARTBEAT_STALE_MS`.
+ */
+export declare function register(root: string, input: {
+    sessionId: string;
+    name: string;
+    cwd: string;
+    pid?: number;
+    status?: SessionRecord['status'];
+}): SessionRecord;
+/**
+ * Refresh a registered session's `lastSeenAt` (clearing `offline`), applying an
+ * optional status or name. Returns null, writing nothing, if no record exists.
+ */
+export declare function heartbeat(root: string, addr: string, patch?: {
+    status?: SessionRecord['status'];
+    name?: string;
+}): SessionRecord | null;
+/** Delete a session's record. Aliases pointing at it are cleared by the next `sweep`. */
+export declare function unregister(root: string, addr: string): void;
 export declare function readAlias(root: string, name: string): AliasRecord | null;
 export declare function listAliases(root: string): AliasRecord[];
 export declare function claimAlias(root: string, name: string, addr: string, sessionId: string): AliasRecord;

package/dist/core.js

@@ -1,6 +1,6 @@
 /** Pi-free relay registry, mailbox, and policy API for non-extension consumers. */
 import { ackClaimedLetter as ackClaimedLetterInternal, awaitReceipt as awaitReceiptInternal, claimInbox as claimInboxInternal, clearAsk as clearAskInternal, deposit as depositInternal, drain as drainInternal, pendingAsks as pendingAsksInternal, readAudit as readAuditInternal, readClaimedLetter as readClaimedLetterInternal, readIncomingAsk as readIncomingAskInternal, readOutgoingAsk as readOutgoingAskInternal, recoverInboxClaims as recoverInboxClaimsInternal, requeueClaimedLetter as requeueClaimedLetterInternal, resolveAskByRef as resolveAskByRefInternal, trackIncomingAsk as trackIncomingAskInternal, trackOutgoingAsk as trackOutgoingAskInternal, unreadCount as unreadCountInternal, watchInbox as watchInboxInternal, } from './mailbox.js';
-import { claimAlias as claimAliasInternal, clearAlias as clearAliasInternal, isValidAliasName as isValidAliasNameInternal, listAliases as listAliasesInternal, listRecords as listRecordsInternal, presenceOf as presenceOfInternal, readAlias as readAliasInternal, readRecord as readRecordInternal, sweep as sweepInternal, } from './registry.js';
+import { claimAlias as claimAliasInternal, clearAlias as clearAliasInternal, deriveAddr, isValidAliasName as isValidAliasNameInternal, listAliases as listAliasesInternal, listRecords as listRecordsInternal, presenceOf as presenceOfInternal, readAlias as readAliasInternal, readRecord as readRecordInternal, removeRecord, sweep as sweepInternal, writeRecord, } from './registry.js';
 export { MAX_BODY_CHARS, previewBody, } from './mailbox.js';
 export { BACKLOG_CAP, DEDUPE_WINDOW_MS, OutboundPolicy, RATE_LIMIT_MAX, RATE_LIMIT_WINDOW_MS, inboundAccepts, } from './policy.js';
 export { HEARTBEAT_STALE_MS, SWEEP_MAIL_KEEP_MS, deriveAddr, isValidAliasName, } from './registry.js';
@@ -47,6 +47,14 @@ function assertLetter(letter) {
         throw new TypeError(`Invalid relay letter timestamp: ${letter.ts}`);
     }
 }
+function assertNonEmptyString(value, label) {
+    if (typeof value !== 'string' || value.length === 0)
+        throw new TypeError(`Invalid relay ${label}: ${value}`);
+}
+function assertStatus(status) {
+    if (status !== 'idle' && status !== 'working')
+        throw new TypeError(`Invalid relay session status: ${status}`);
+}
 function isSafeLetter(letter) {
     try {
         assertLetter(letter);
@@ -108,6 +116,64 @@ export function presenceOf(record, now = Date.now()) {
     assertAddress(record.addr);
     return presenceOfInternal(record, now);
 }
+/**
+ * Register (or re-register) a non-Pi host as a relay session. The address is
+ * derived from `cwd` + `sessionId`, so re-registering keeps it, along with the
+ * existing `startedAt`. The host must call `heartbeat` well inside
+ * `HEARTBEAT_STALE_MS`.
+ */
+export function register(root, input) {
+    assertNonEmptyString(input.sessionId, 'session id');
+    assertNonEmptyString(input.name, 'session name');
+    assertNonEmptyString(input.cwd, 'session cwd');
+    const pid = input.pid ?? process.pid;
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        throw new TypeError(`Invalid relay session pid: ${pid}`);
+    const status = input.status ?? 'idle';
+    assertStatus(status);
+    const addr = deriveAddr(input.cwd, input.sessionId);
+    const now = Date.now();
+    const record = {
+        addr,
+        sessionId: input.sessionId,
+        name: input.name,
+        cwd: input.cwd,
+        pid,
+        startedAt: readRecord(root, addr)?.startedAt ?? now,
+        lastSeenAt: now,
+        status,
+    };
+    writeRecord(root, record);
+    return record;
+}
+/**
+ * Refresh a registered session's `lastSeenAt` (clearing `offline`), applying an
+ * optional status or name. Returns null, writing nothing, if no record exists.
+ */
+export function heartbeat(root, addr, patch = {}) {
+    assertAddress(addr);
+    if (patch.status !== undefined)
+        assertStatus(patch.status);
+    if (patch.name !== undefined)
+        assertNonEmptyString(patch.name, 'session name');
+    const existing = readRecord(root, addr);
+    if (existing === null)
+        return null;
+    const { offline: _offline, ...rest } = existing;
+    const record = {
+        ...rest,
+        name: patch.name ?? rest.name,
+        status: patch.status ?? rest.status,
+        lastSeenAt: Date.now(),
+    };
+    writeRecord(root, record);
+    return record;
+}
+/** Delete a session's record. Aliases pointing at it are cleared by the next `sweep`. */
+export function unregister(root, addr) {
+    assertAddress(addr);
+    removeRecord(root, addr);
+}
 export function readAlias(root, name) {
     assertAliasName(name);
     const alias = readAliasInternal(root, name);
@@ -134,6 +200,17 @@ export function sweep(root, now = Date.now(), sessionExists) {
 export function deposit(root, toAddr, letter) {
     assertAddress(toAddr);
     assertLetter(letter);
+    // wake is validated on the write side only. The read path (isSafeLetter)
+    // tolerates a non-boolean wake, so a letter from a writer that never
+    // validated the field is still delivered (as waking mail: delivery only
+    // honours wake === false) instead of being discarded after drain already
+    // unlinked it.
+    if (letter.wake !== undefined && typeof letter.wake !== 'boolean') {
+        throw new TypeError(`Invalid relay letter wake flag: ${letter.wake}`);
+    }
+    if (letter.kind === 'ask' && letter.wake === false) {
+        throw new TypeError('A quiet ask (wake: false) is refused: the receiver takes no turn, so it could never answer');
+    }
     depositInternal(root, toAddr, letter);
 }
 export function drain(root, addr) {

package/dist/core.test.js

@@ -5,6 +5,7 @@ import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { afterEach, describe, expect, it } from 'vitest';
 import * as core from './core.js';
+import { deposit as mailboxDeposit } from './mailbox.js';
 const relayDir = path.dirname(fileURLToPath(import.meta.url));
 const repoRoot = path.resolve(relayDir, '../..');
 const packageJson = JSON.parse(fs.readFileSync(path.join(relayDir, 'package.json'), 'utf8'));
@@ -313,6 +314,24 @@ describe('/core filesystem boundary', () => {
         expect(fs.readdirSync(base)).toEqual(['relay']);
     });
 });
+it('threads wake through core deposit and rejects a non-boolean flag and a quiet ask', () => {
+    const root = path.join(fixture(), 'relay');
+    const addr = core.deriveAddr('/receiver', 'session');
+    core.deposit(root, addr, letter({ id: 'wake-core', kind: 'message', wake: false }));
+    expect(core.drain(root, addr).map((l) => [l.id, l.wake])).toEqual([['wake-core', false]]);
+    expect(() => core.deposit(root, addr, letter({ kind: 'message', wake: 'no' }))).toThrow(TypeError);
+    // A quiet ask could never be answered: the receiver takes no turn.
+    expect(() => core.deposit(root, addr, letter({ kind: 'ask', wake: false }))).toThrow(TypeError);
+});
+it('drains rather than discards a letter whose wake flag is not boolean', () => {
+    const root = path.join(fixture(), 'relay');
+    const addr = core.deriveAddr('/receiver', 'session');
+    // An old writer stringifies the whole letter without validating wake, so a
+    // non-boolean flag can land on disk. Drain unlinks before parsing; the read
+    // path must deliver the letter (as waking mail), not silently drop it.
+    mailboxDeposit(root, addr, letter({ id: 'wake-odd', kind: 'message', wake: 'no' }));
+    expect(core.drain(root, addr).map((l) => l.id)).toEqual(['wake-odd']);
+});
 it('keeps the Pi extension entry importable', async () => {
     const entry = await import('./index.js');
     expect(typeof entry.default).toBe('function');

package/dist/extension.test.js

@@ -45,6 +45,7 @@ function start() {
     const handlers = new Map();
     let execute;
     let branch = [];
+    const sends = [];
     const ctx = {
         cwd: '/work',
         sessionManager: { getSessionId: () => 'self', getCwd: () => '/work', getBranch: () => branch },
@@ -60,7 +61,8 @@ function start() {
         registerCommand: () => { },
         registerMessageRenderer: () => { },
         registerEntryRenderer: () => { },
-        sendMessage: (message) => {
+        sendMessage: (message, options) => {
+            sends.push({ message, options });
             branch.push({ ...message, type: 'custom_message' });
         },
     };
@@ -76,6 +78,7 @@ function start() {
             branch = entries;
         },
         emit,
+        sends,
     };
 }
 function delivery(l) {
@@ -164,6 +167,32 @@ it('restores an offline queued letter and emits an exact durable receipt', async
     const { awaitReceipt } = await import('./mailbox.js');
     expect(await awaitReceipt(root, self, l, 1800)).toBe('delivered');
 });
+it('delivers wake:false mail without triggering a turn, waking mail with one, and an ask always wakes', async () => {
+    const root = fixture();
+    const p = peer();
+    writeRecord(root, p);
+    const self = deriveAddr('/work', 'self');
+    const from = { addr: p.addr, name: p.name, cwd: p.cwd };
+    const quiet = { id: 'quiet-letter', kind: 'message', body: 'fyi only', ts: Date.now(), wake: false, from };
+    const loud = { id: 'loud-letter', kind: 'message', body: 'wake up', ts: Date.now() + 1, from };
+    // The mailbox layer does not validate wake, so a quiet ask can land on
+    // disk; delivery must wake it anyway or it would never be answered.
+    const quietAsk = { id: 'quiet-ask', kind: 'ask', body: 'answer me', ts: Date.now() + 2, wake: false, from };
+    deposit(root, self, quiet);
+    deposit(root, self, loud);
+    deposit(root, self, quietAsk);
+    const host = start();
+    const { awaitReceipt } = await import('./mailbox.js');
+    // All three letters are acked, so all landed in the session's context.
+    expect(await awaitReceipt(root, self, quiet, 3000)).toBe('delivered');
+    expect(await awaitReceipt(root, self, loud, 3000)).toBe('delivered');
+    expect(await awaitReceipt(root, self, quietAsk, 3000)).toBe('delivered');
+    const byId = (id) => host.sends.find((s) => s.message.details?.id === id);
+    expect(byId(quiet.id).options).toEqual({ triggerTurn: false });
+    expect(byId(loud.id).options).toEqual({ triggerTurn: true, deliverAs: 'steer' });
+    expect(byId(quietAsk.id).options).toEqual({ triggerTurn: true, deliverAs: 'steer' });
+    expect(pendingAsks(root, self).map((l) => l.id)).toEqual([quietAsk.id]);
+});
 it('settles a waiting ask on shutdown and clears tracking for the original sender', async () => {
     const root = fixture();
     const p = peer();

package/dist/index.js

@@ -201,6 +201,24 @@ export default function relay(pi) {
             display: true,
             details,
         };
+        // wake === false: an FYI letter. It must land in the session's context
+        // (triggerTurn: false appends to the session, or queues until the
+        // current turn ends when the agent is streaming) without taking a model
+        // turn. Absent or true keeps the wake path below. An ask always wakes,
+        // whatever its flag says (core deposit refuses quiet asks, but the
+        // mailbox layer does not validate): without a turn the receiver could
+        // never answer and the asker would wait out its timeout.
+        if (letter.wake === false && letter.kind !== 'ask') {
+            try {
+                pi.sendMessage(message, { triggerTurn: false });
+                auditDelivery('deliver');
+                return true;
+            }
+            catch {
+                auditDelivery('deliver-failed');
+                return false;
+            }
+        }
         // steer lands between tool calls mid-run; triggerTurn wakes an idle
         // session. A busy agent rejects triggerTurn ("Agent is already
         // processing") — fall back to queueing for the next turn instead of

package/dist/mailbox.d.ts

@@ -26,6 +26,17 @@ export interface Letter {
     kind: LetterKind;
     body: string;
     replyTo?: string;
+    /**
+     * `false` delivers quietly: the letter still lands in the receiving
+     * session's context, but does not trigger a model turn. Absent or `true`
+     * wakes the session as before. An ask is never quiet: core `deposit`
+     * refuses `wake: false` on kind `ask`, and delivery wakes an ask
+     * regardless, because without a turn the receiver could never answer.
+     * Backward compatible: letters are stored as whole-JSON files and readers
+     * only require `id`/`body`, so old readers ignore the field and old
+     * writers never set it.
+     */
+    wake?: boolean;
     ts: number;
 }
 export declare const MAX_BODY_CHARS: number;

package/dist/mailbox.js

@@ -372,6 +372,8 @@ export function readClaimedLetter(root, addr, claimToken, fileToken) {
         relay.close();
     }
 }
+/** Content digest for delivery proof. `wake` is delivery mode, not content,
+ * and is excluded so old and new receivers compute matching digests. */
 function letterDigest(letter) {
     return createHash('sha256')
         .update(JSON.stringify([

package/dist/registration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/registration.test.js

@@ -0,0 +1,93 @@
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import * as core from './core.js';
+const fixtures = [];
+function relayRoot() {
+    const dir = fs.realpathSync.native(fs.mkdtempSync(path.join(os.tmpdir(), 'pi-relay-registration-')));
+    fixtures.push(dir);
+    return path.join(dir, 'relay');
+}
+const host = { sessionId: 'riker-supervisor', name: 'riker', cwd: '/work/riker' };
+afterEach(() => {
+    vi.useRealTimers();
+    while (fixtures.length > 0)
+        fs.rmSync(fixtures.pop(), { recursive: true, force: true });
+});
+describe('/core session registration', () => {
+    it('registers a live session visible in listRecords', () => {
+        const root = relayRoot();
+        const record = core.register(root, host);
+        expect(record).toMatchObject({
+            addr: core.deriveAddr(host.cwd, host.sessionId),
+            sessionId: host.sessionId,
+            name: 'riker',
+            cwd: host.cwd,
+            pid: process.pid,
+            status: 'idle',
+        });
+        expect(record.startedAt).toBe(record.lastSeenAt);
+        expect(core.listRecords(root)).toEqual([record]);
+        expect(core.presenceOf(record)).toBe('live');
+    });
+    it('heartbeat refreshes lastSeenAt and applies the patch; unknown addresses stay unknown', () => {
+        vi.useFakeTimers({ now: 1_000_000 });
+        const root = relayRoot();
+        const { addr } = core.register(root, host);
+        vi.setSystemTime(1_015_000);
+        const beat = core.heartbeat(root, addr, { status: 'working', name: 'riker-2' });
+        expect(beat).toMatchObject({
+            addr,
+            lastSeenAt: 1_015_000,
+            startedAt: 1_000_000,
+            status: 'working',
+            name: 'riker-2',
+        });
+        expect(core.readRecord(root, addr)).toEqual(beat);
+        const unknown = core.deriveAddr('/nowhere', 'ghost');
+        expect(core.heartbeat(root, unknown)).toBeNull();
+        expect(core.readRecord(root, unknown)).toBeNull();
+        expect(core.listRecords(root)).toHaveLength(1);
+    });
+    it('keeps a heartbeating session alias through sweep, and sweep clears it after unregister', () => {
+        const root = relayRoot();
+        const { addr } = core.register(root, host);
+        core.claimAlias(root, 'riker', addr, host.sessionId);
+        core.heartbeat(root, addr);
+        core.sweep(root);
+        expect(core.readAlias(root, 'riker')).toMatchObject({ addr });
+        core.unregister(root, addr);
+        expect(core.listRecords(root)).toEqual([]);
+        core.sweep(root);
+        expect(core.readAlias(root, 'riker')).toBeNull();
+        expect(() => core.unregister(root, addr)).not.toThrow();
+    });
+    it('re-registering keeps addr and startedAt', () => {
+        vi.useFakeTimers({ now: 2_000_000 });
+        const root = relayRoot();
+        const first = core.register(root, host);
+        vi.setSystemTime(2_060_000);
+        const second = core.register(root, { ...host, name: 'renamed', status: 'working' });
+        expect(second).toMatchObject({ addr: first.addr, startedAt: 2_000_000, lastSeenAt: 2_060_000, name: 'renamed' });
+        expect(core.listRecords(root)).toEqual([second]);
+    });
+    it('rejects invalid input', () => {
+        const root = relayRoot();
+        const { addr } = core.register(root, host);
+        const calls = [
+            () => core.register(root, { ...host, sessionId: '' }),
+            () => core.register(root, { ...host, name: 42 }),
+            () => core.register(root, { ...host, cwd: '' }),
+            () => core.register(root, { ...host, pid: 0 }),
+            () => core.register(root, { ...host, pid: 1.5 }),
+            () => core.register(root, { ...host, status: 'busy' }),
+            () => core.heartbeat(root, '../../escaped'),
+            () => core.heartbeat(root, addr, { status: 'busy' }),
+            () => core.heartbeat(root, addr, { name: '' }),
+            () => core.unregister(root, '../../escaped'),
+        ];
+        for (const call of calls)
+            expect(call).toThrow(TypeError);
+    });
+});

package/dist/registry.d.ts

@@ -70,6 +70,8 @@ export declare function listAliases(root: string): AliasRecord[];
 export declare function claimAlias(root: string, name: string, addr: string, sessionId: string): AliasRecord;
 export declare function clearAlias(root: string, name: string): void;
 export declare function writeRecord(root: string, record: SessionRecord): void;
+/** Delete `<addr>.json`. A missing record or relay root is fine. */
+export declare function removeRecord(root: string, addr: string): void;
 export declare function readRecord(root: string, addr: string): SessionRecord | null;
 /** Read-only listing, oldest first. Never mutates anything. */
 export declare function listRecords(root: string): SessionRecord[];

package/dist/registry.js

@@ -223,6 +223,19 @@ export function writeRecord(root, record) {
         relay.close();
     }
 }
+/** Delete `<addr>.json`. A missing record or relay root is fine. */
+export function removeRecord(root, addr) {
+    assertPathSegment(addr, 'relay address');
+    const relay = openRelayRoot(root);
+    if (relay === null)
+        return;
+    try {
+        relay.unlinkFile(`${addr}.json`);
+    }
+    finally {
+        relay.close();
+    }
+}
 function readRecordFromDirectory(directory, addr) {
     const raw = directory.readFile(`${addr}.json`);
     if (raw === null)

package/dist/relay.test.js

@@ -170,6 +170,26 @@ describe('mailbox', () => {
         expect(drain(root, addr)).toEqual([]); // nothing twice
         expect(unreadCount(root, addr)).toBe(0);
     });
+    it('wake survives deposit intact, stays absent when unset, and does not break delivery proof', async () => {
+        const root = tmpRoot();
+        const addr = 'inbox0000006';
+        deposit(root, addr, letter({ id: 'quiet-1', ts: 1000, wake: false }));
+        deposit(root, addr, letter({ id: 'plain-1', ts: 2000 }));
+        const drained = drain(root, addr);
+        expect(drained.map((l) => [l.id, l.wake])).toEqual([
+            ['quiet-1', false],
+            ['plain-1', undefined],
+        ]);
+        expect('wake' in drained[1]).toBe(false); // old writers never set it; nothing invents it
+        // The durable claim flow preserves the field, and the acknowledgement
+        // digest (which excludes wake) still proves delivery to the sender.
+        const quiet = letter({ id: 'quiet-2', ts: 3000, wake: false });
+        deposit(root, addr, quiet);
+        const claim = claimInbox(root, addr);
+        expect(readClaimedLetter(root, addr, claim.claimToken, claim.fileTokens[0])?.wake).toBe(false);
+        expect(ackClaimedLetter(root, addr, claim.claimToken, claim.fileTokens[0])).toBe(true);
+        expect(await awaitReceipt(root, addr, quiet, 400)).toBe('delivered');
+    });
     it('discards corrupt letters without poisoning future drains', () => {
         const root = tmpRoot();
         const addr = 'inbox0000002';

package/index.ts

@@ -270,6 +270,23 @@ export default function relay(pi: ExtensionAPI) {
       display: true,
       details,
     };
+    // wake === false: an FYI letter. It must land in the session's context
+    // (triggerTurn: false appends to the session, or queues until the
+    // current turn ends when the agent is streaming) without taking a model
+    // turn. Absent or true keeps the wake path below. An ask always wakes,
+    // whatever its flag says (core deposit refuses quiet asks, but the
+    // mailbox layer does not validate): without a turn the receiver could
+    // never answer and the asker would wait out its timeout.
+    if (letter.wake === false && letter.kind !== 'ask') {
+      try {
+        pi.sendMessage(message, { triggerTurn: false });
+        auditDelivery('deliver');
+        return true;
+      } catch {
+        auditDelivery('deliver-failed');
+        return false;
+      }
+    }
     // steer lands between tool calls mid-run; triggerTurn wakes an idle
     // session. A busy agent rejects triggerTurn ("Agent is already
     // processing") — fall back to queueing for the next turn instead of

package/mailbox.ts

@@ -35,6 +35,17 @@ export interface Letter {
   kind: LetterKind;
   body: string;
   replyTo?: string;
+  /**
+   * `false` delivers quietly: the letter still lands in the receiving
+   * session's context, but does not trigger a model turn. Absent or `true`
+   * wakes the session as before. An ask is never quiet: core `deposit`
+   * refuses `wake: false` on kind `ask`, and delivery wakes an ask
+   * regardless, because without a turn the receiver could never answer.
+   * Backward compatible: letters are stored as whole-JSON files and readers
+   * only require `id`/`body`, so old readers ignore the field and old
+   * writers never set it.
+   */
+  wake?: boolean;
   ts: number;
 }
 
@@ -375,6 +386,8 @@ interface DeliveryAcknowledgement {
   acknowledgedAt: number;
 }
 
+/** Content digest for delivery proof. `wake` is delivery mode, not content,
+ * and is excluded so old and new receivers compute matching digests. */
 function letterDigest(letter: Letter): string {
   return createHash('sha256')
     .update(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nicknisi/pi-relay",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Brokerless session-to-session messaging for pi — a file mailbox that outlives the process, with ask/reply coordination. Formerly @nicknisi/pi-intercom.",
   "keywords": [
     "pi",

package/registry.ts

@@ -244,6 +244,18 @@ export function writeRecord(root: string, record: SessionRecord): void {
   }
 }
 
+/** Delete `<addr>.json`. A missing record or relay root is fine. */
+export function removeRecord(root: string, addr: string): void {
+  assertPathSegment(addr, 'relay address');
+  const relay = openRelayRoot(root);
+  if (relay === null) return;
+  try {
+    relay.unlinkFile(`${addr}.json`);
+  } finally {
+    relay.close();
+  }
+}
+
 function readRecordFromDirectory(directory: RelayDirectoryHandle, addr: string): SessionRecord | null {
   const raw = directory.readFile(`${addr}.json`);
   if (raw === null) return null;