@nicknisi/pi-relay 0.3.1 → 0.3.3

package/README.md

@@ -101,6 +101,7 @@ The directory is created `0700` and every file `0600` — other users on the mac
 ## Caveats
 
 - **Mailbox semantics support Linux and macOS only.** Relay rejects user-controlled symlinks in configured-root components, permits protected root-owned system aliases such as macOS `/var`, pins root, mailbox, and durable-claim descriptors for each operation, and uses descriptor-relative `openat`/`renameat`/`unlinkat` calls, atomic renames, descriptor polling for watches, and `0600`/`0700` permission bits. Windows is unsupported.
+- **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).

package/dist/filesystem.js

@@ -1,11 +1,22 @@
 /** Descriptor-relative, symlink-safe filesystem operations for the relay store. Pi-free. */
 import { randomBytes } from 'node:crypto';
 import * as fs from 'node:fs';
+import { createRequire } from 'node:module';
 import * as path from 'node:path';
-import koffi from 'koffi';
 if (process.platform !== 'darwin' && process.platform !== 'linux') {
     throw new Error(`Relay filesystem operations are unsupported on ${process.platform}`);
 }
+// Bun <= 1.3.14 aborts the whole process when koffi's GC finalizer releases
+// an N-API reference (oven-sh/bun#39263, fixed after 1.3.14). Fail extension
+// load cleanly on those versions instead.
+const bunVersion = globalThis.Bun?.version;
+if (bunVersion !== undefined) {
+    const [major = 0, minor = 0, patch = 0] = bunVersion.split('-')[0].split('.').map(Number);
+    if (major < 1 || (major === 1 && (minor < 3 || (minor === 3 && patch <= 14)))) {
+        throw new Error(`Relay requires Node.js or Bun > 1.3.14: koffi crashes Bun ${bunVersion} (oven-sh/bun#39263)`);
+    }
+}
+const koffi = createRequire(import.meta.url)('koffi');
 const NOFOLLOW = fs.constants.O_NOFOLLOW ?? 0;
 const DIRECTORY = fs.constants.O_DIRECTORY ?? 0;
 const CLOEXEC = process.platform === 'darwin' ? 0x01000000 : 0x00080000;

package/dist/index.js

@@ -20,7 +20,13 @@ import { Type } from 'typebox';
 import { formatAudit, formatDelivery, formatListing, formatPendingAsk, refusalAmbiguous, refusalUnknown, shortAddr, } from './format.js';
 import { ackClaimedLetter, appendAudit, awaitReceipt, claimInbox, clearAsk, deposit, outgoingAskIds, pendingAsks, previewBody, readAudit, readClaimedLetter, readOutgoingAsk, recoverInboxClaims, requeueClaimedLetter, resolveAskByRef, trackIncomingAsk, trackOutgoingAsk, unreadCount, watchInbox, } from './mailbox.js';
 import { OutboundPolicy, inboundAccepts } from './policy.js';
-import { claimAlias, deriveAddr, ensureRoot, isValidAliasName, listAliases, listRecords, presenceOf, readAlias, readRecord, sweep, writeRecord, } from './registry.js';
+import { claimAlias, deriveAddr, ensureRoot, resolveRelayRoot, isValidAliasName, listAliases, listRecords, presenceOf, readAlias, readRecord, sweep, writeRecord, } from './registry.js';
+/** What to tell the caller when there is no session record to work with. */
+function describeUninitialized(startupError, root) {
+    return startupError
+        ? `Relay failed to start: ${startupError} (relay root: ${root})`
+        : 'Relay is not initialized (no session_start yet).';
+}
 function toolResult(text, details = {}) {
     return { content: [{ type: 'text', text }], details };
 }
@@ -93,9 +99,18 @@ function collectResumableSessionIds() {
     return ids;
 }
 export default function relay(pi) {
-    const root = process.env.PI_RELAY_DIR ?? path.join(getAgentDir(), 'relay');
+    // Resolve before any relay I/O: pi's home is commonly a dotfiles symlink,
+    // and the traversal hardening (rightly) refuses user-controlled ancestor
+    // symlinks on every operation. See resolveRelayRoot.
+    const root = resolveRelayRoot(process.env.PI_RELAY_DIR ?? path.join(getAgentDir(), 'relay'));
     const policy = new OutboundPolicy();
     let self;
+    // Why registration failed, if it did. Without this a startup failure is
+    // indistinguishable from "session_start hasn't fired yet", and the whole
+    // extension goes quietly inert -- which is exactly how a symlinked pi home
+    // disabled relay machine-wide for a day and a half before anyone noticed.
+    let startupError;
+    const uninitializedText = () => describeUninitialized(startupError, root);
     let unwatch;
     let heartbeat;
     const askWaiters = new Map();
@@ -411,6 +426,7 @@ export default function relay(pi) {
     }
     pi.on('session_start', (_event, ctx) => {
         try {
+            startupError = undefined;
             ensureRoot(root);
             const sessionId = ctx.sessionManager.getSessionId();
             const cwd = ctx.sessionManager.getCwd() ?? ctx.cwd;
@@ -461,8 +477,11 @@ export default function relay(pi) {
             const initialDrain = setTimeout(checkInbox, 1200);
             initialDrain.unref();
         }
-        catch {
-            // registration failure never breaks the session
+        catch (error) {
+            // A failure here must never break the session -- but it must not be
+            // invisible either. Record it so every tool can say what actually
+            // happened instead of implying session_start simply hasn't run.
+            startupError = error instanceof Error ? error.message : String(error);
         }
     });
     pi.on('agent_start', () => writeSelf({ status: 'working' }));
@@ -515,7 +534,7 @@ export default function relay(pi) {
         }),
         async execute(_toolCallId, params, signal, _onUpdate, ctx) {
             if (!self)
-                return toolResult('Relay is not initialized (no session_start yet).');
+                return toolResult(uninitializedText());
             switch (params.action) {
                 case 'list':
                     return toolResult(formatListing(listRecords(root), self.addr, (r) => presenceOf(r)));
@@ -748,7 +767,7 @@ export default function relay(pi) {
             if (sub === 'log') {
                 const limit = Math.max(1, Math.min(500, Number(rest[0] ?? 50)));
                 const entries = self ? readAudit(root, limit) : [];
-                const text = self ? formatAudit(entries) : 'Relay is not initialized (no session_start yet).';
+                const text = self ? formatAudit(entries) : uninitializedText();
                 if (!self || !ctx.hasUI) {
                     pi.sendMessage({ customType: AUDIT_TYPE, content: text, display: true, details: { kind: 'relay-audit' } });
                     return;
@@ -758,9 +777,7 @@ export default function relay(pi) {
             }
             if (!self || !ctx.hasUI) {
                 // Plain-text fallback (print/rpc mode): the entry renderer never runs there.
-                const text = self
-                    ? formatListing(listRecords(root), self.addr, (r) => presenceOf(r))
-                    : 'Relay is not initialized (no session_start yet).';
+                const text = self ? formatListing(listRecords(root), self.addr, (r) => presenceOf(r)) : uninitializedText();
                 pi.sendMessage({
                     customType: LIST_TYPE,
                     content: text,

package/dist/registry.d.ts

@@ -30,6 +30,25 @@ export declare const HEARTBEAT_STALE_MS = 45000;
 /** A mailbox holding undelivered mail is kept this long after last contact. */
 export declare const SWEEP_MAIL_KEEP_MS: number;
 export declare function deriveAddr(cwd: string, sessionId: string): string;
+/**
+ * Pin the relay root to its real location, once, before any relay I/O.
+ *
+ * The traversal hardening refuses *user-controlled* ancestor symlinks, because
+ * a user-writable symlink can be swapped between the check and the use. That
+ * is the right rule for every operation after startup — but it also rejects a
+ * legitimate, stable arrangement: a dotfiles setup where `~/.pi` is a symlink
+ * into a managed repo. Since pi keeps everything under `~/.pi`, that made the
+ * relay root unopenable and the whole extension silently inert.
+ *
+ * Resolving once at startup keeps the property that matters. Every later
+ * operation traverses only real directories, so there is no user symlink left
+ * in the path to swap; repointing `~/.pi` afterwards cannot redirect this
+ * process. It is a pin, not a bypass.
+ *
+ * The root may not exist yet on a first run, so resolve the deepest ancestor
+ * that does and re-apply the remainder.
+ */
+export declare function resolveRelayRoot(root: string): string;
 export declare function ensureRoot(root: string): void;
 export declare function recordPath(root: string, addr: string): string;
 export declare function inboxDir(root: string, addr: string): string;

package/dist/registry.js

@@ -15,6 +15,7 @@
  * - Listing has NO side effects: reading the directory never deletes.
  */
 import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { assertPathSegment, openRelayRoot, rethrowFilesystemError, RelayDirectoryHandle, RelayFilesystemError, } from './filesystem.js';
 export const HEARTBEAT_STALE_MS = 45_000;
@@ -23,6 +24,44 @@ export const SWEEP_MAIL_KEEP_MS = 30 * 24 * 60 * 60 * 1000;
 export function deriveAddr(cwd, sessionId) {
     return crypto.createHash('sha256').update(`${cwd}${sessionId}`).digest('hex').slice(0, 12);
 }
+/**
+ * Pin the relay root to its real location, once, before any relay I/O.
+ *
+ * The traversal hardening refuses *user-controlled* ancestor symlinks, because
+ * a user-writable symlink can be swapped between the check and the use. That
+ * is the right rule for every operation after startup — but it also rejects a
+ * legitimate, stable arrangement: a dotfiles setup where `~/.pi` is a symlink
+ * into a managed repo. Since pi keeps everything under `~/.pi`, that made the
+ * relay root unopenable and the whole extension silently inert.
+ *
+ * Resolving once at startup keeps the property that matters. Every later
+ * operation traverses only real directories, so there is no user symlink left
+ * in the path to swap; repointing `~/.pi` afterwards cannot redirect this
+ * process. It is a pin, not a bypass.
+ *
+ * The root may not exist yet on a first run, so resolve the deepest ancestor
+ * that does and re-apply the remainder.
+ */
+export function resolveRelayRoot(root) {
+    const absolute = path.resolve(root);
+    const tail = [];
+    let current = absolute;
+    for (;;) {
+        try {
+            return path.join(fs.realpathSync(current), ...tail);
+        }
+        catch (error) {
+            if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT'))
+                throw error;
+            const parent = path.dirname(current);
+            // Filesystem root does not exist: nothing sane left to resolve against.
+            if (parent === current)
+                return absolute;
+            tail.unshift(path.basename(current));
+            current = parent;
+        }
+    }
+}
 export function ensureRoot(root) {
     const directory = openRelayRoot(root, true);
     directory.close();

package/dist/relay.test.js

@@ -10,7 +10,7 @@ import { afterEach, describe, expect, it } from 'vitest';
 import { BOUNDARY_PREAMBLE, formatAudit, formatDelivery, formatListing, refusalAmbiguous, refusalUnknown, } from './format.js';
 import { ackClaimedLetter, appendAudit, auditLogPath, awaitReceipt, claimInbox, clearAsk, deposit, drain, pendingAsks, previewBody, readAudit, readClaimedLetter, readIncomingAsk, readOutgoingAsk, recoverInboxClaims, requeueClaimedLetter, resolveAskByRef, trackIncomingAsk, trackOutgoingAsk, unreadCount, watchInbox, } from './mailbox.js';
 import { BACKLOG_CAP, OutboundPolicy, inboundAccepts } from './policy.js';
-import { claimAlias, clearAlias, deriveAddr, isValidAliasName, listAliases, listRecords, presenceOf, readAlias, readRecord, sweep, writeAlias, writeRecord, } from './registry.js';
+import { claimAlias, clearAlias, deriveAddr, ensureRoot, resolveRelayRoot, isValidAliasName, listAliases, listRecords, presenceOf, readAlias, readRecord, sweep, writeAlias, writeRecord, } from './registry.js';
 const require = createRequire(import.meta.url);
 const dirs = [];
 function tmpRoot() {
@@ -615,3 +615,35 @@ describe('format', () => {
         expect(refusalAmbiguous('al', ['"alpha" (aaaa11)', '"alpine" (bbbb22)'])).toContain('ambiguous');
     });
 });
+describe('relay root resolution', () => {
+    // pi's home is commonly a dotfiles symlink (`~/.pi -> ~/Developer/dotfiles/home/.pi`).
+    // The traversal hardening refuses user-controlled ancestor symlinks, so an
+    // unresolved root made every relay operation throw -- and because
+    // session_start swallowed it, relay went silently inert machine-wide.
+    // Note the rest of this suite calls fs.realpathSync.native() on its temp
+    // dirs, which is exactly why that path was never covered.
+    it('resolves a user-symlinked ancestor so the hardened root can be opened', () => {
+        const real = tmpRoot();
+        const link = path.join(tmpRoot(), 'link');
+        fs.symlinkSync(real, link, 'dir');
+        const root = path.join(link, 'relay');
+        // The hardening rejects the symlinked path itself -- deliberately.
+        expect(() => ensureRoot(root)).toThrow(/symlink/i);
+        // Resolving first yields the same directory by its real path, which opens.
+        const resolved = resolveRelayRoot(root);
+        expect(resolved).toBe(path.join(real, 'relay'));
+        expect(() => ensureRoot(resolved)).not.toThrow();
+    });
+    it('resolves a root whose directories do not exist yet', () => {
+        const real = tmpRoot();
+        const link = path.join(tmpRoot(), 'link');
+        fs.symlinkSync(real, link, 'dir');
+        // First run: nothing under the root exists, so the deepest existing
+        // ancestor is resolved and the missing tail re-applied.
+        expect(resolveRelayRoot(path.join(link, 'a', 'b', 'relay'))).toBe(path.join(real, 'a', 'b', 'relay'));
+    });
+    it('leaves an already-real path unchanged', () => {
+        const real = tmpRoot();
+        expect(resolveRelayRoot(path.join(real, 'relay'))).toBe(path.join(real, 'relay'));
+    });
+});

package/filesystem.ts

@@ -1,13 +1,26 @@
 /** Descriptor-relative, symlink-safe filesystem operations for the relay store. Pi-free. */
 import { randomBytes } from 'node:crypto';
 import * as fs from 'node:fs';
+import { createRequire } from 'node:module';
 import * as path from 'node:path';
-import koffi from 'koffi';
 
 if (process.platform !== 'darwin' && process.platform !== 'linux') {
   throw new Error(`Relay filesystem operations are unsupported on ${process.platform}`);
 }
 
+// Bun <= 1.3.14 aborts the whole process when koffi's GC finalizer releases
+// an N-API reference (oven-sh/bun#39263, fixed after 1.3.14). Fail extension
+// load cleanly on those versions instead.
+const bunVersion = (globalThis as { Bun?: { version?: string } }).Bun?.version;
+if (bunVersion !== undefined) {
+  const [major = 0, minor = 0, patch = 0] = bunVersion.split('-')[0]!.split('.').map(Number);
+  if (major < 1 || (major === 1 && (minor < 3 || (minor === 3 && patch <= 14)))) {
+    throw new Error(`Relay requires Node.js or Bun > 1.3.14: koffi crashes Bun ${bunVersion} (oven-sh/bun#39263)`);
+  }
+}
+
+const koffi = createRequire(import.meta.url)('koffi') as typeof import('koffi');
+
 const NOFOLLOW = fs.constants.O_NOFOLLOW ?? 0;
 const DIRECTORY = fs.constants.O_DIRECTORY ?? 0;
 const CLOEXEC = process.platform === 'darwin' ? 0x01000000 : 0x00080000;

package/index.ts

@@ -55,6 +55,7 @@ import {
   claimAlias,
   deriveAddr,
   ensureRoot,
+  resolveRelayRoot,
   isValidAliasName,
   listAliases,
   listRecords,
@@ -69,6 +70,13 @@ import {
 
 type AskOutcome = { replied: true; body: string; from: string } | { replied: false; reason: string };
 
+/** What to tell the caller when there is no session record to work with. */
+function describeUninitialized(startupError: string | undefined, root: string): string {
+  return startupError
+    ? `Relay failed to start: ${startupError} (relay root: ${root})`
+    : 'Relay is not initialized (no session_start yet).';
+}
+
 function toolResult(text: string, details: Record<string, unknown> = {}) {
   return { content: [{ type: 'text' as const, text }], details };
 }
@@ -166,10 +174,19 @@ function collectResumableSessionIds(): Set<string> {
 }
 
 export default function relay(pi: ExtensionAPI) {
-  const root = process.env.PI_RELAY_DIR ?? path.join(getAgentDir(), 'relay');
+  // Resolve before any relay I/O: pi's home is commonly a dotfiles symlink,
+  // and the traversal hardening (rightly) refuses user-controlled ancestor
+  // symlinks on every operation. See resolveRelayRoot.
+  const root = resolveRelayRoot(process.env.PI_RELAY_DIR ?? path.join(getAgentDir(), 'relay'));
   const policy = new OutboundPolicy();
 
   let self: SessionRecord | undefined;
+  // Why registration failed, if it did. Without this a startup failure is
+  // indistinguishable from "session_start hasn't fired yet", and the whole
+  // extension goes quietly inert -- which is exactly how a symlinked pi home
+  // disabled relay machine-wide for a day and a half before anyone noticed.
+  let startupError: string | undefined;
+  const uninitializedText = (): string => describeUninitialized(startupError, root);
   let unwatch: (() => void) | undefined;
   let heartbeat: ReturnType<typeof setInterval> | undefined;
   const askWaiters = new Map<string, (outcome: AskOutcome) => void>();
@@ -478,6 +495,7 @@ export default function relay(pi: ExtensionAPI) {
 
   pi.on('session_start', (_event, ctx: ExtensionContext) => {
     try {
+      startupError = undefined;
       ensureRoot(root);
       const sessionId = ctx.sessionManager.getSessionId();
       const cwd = ctx.sessionManager.getCwd() ?? ctx.cwd;
@@ -524,8 +542,11 @@ export default function relay(pi: ExtensionAPI) {
       // processing"); by the time this fires, steer/triggerTurn work.
       const initialDrain = setTimeout(checkInbox, 1200);
       initialDrain.unref();
-    } catch {
-      // registration failure never breaks the session
+    } catch (error) {
+      // A failure here must never break the session -- but it must not be
+      // invisible either. Record it so every tool can say what actually
+      // happened instead of implying session_start simply hasn't run.
+      startupError = error instanceof Error ? error.message : String(error);
     }
   });
 
@@ -588,7 +609,7 @@ export default function relay(pi: ExtensionAPI) {
     }),
 
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-      if (!self) return toolResult('Relay is not initialized (no session_start yet).');
+      if (!self) return toolResult(uninitializedText());
 
       switch (params.action) {
         case 'list':
@@ -823,7 +844,7 @@ export default function relay(pi: ExtensionAPI) {
       if (sub === 'log') {
         const limit = Math.max(1, Math.min(500, Number(rest[0] ?? 50)));
         const entries = self ? readAudit(root, limit) : [];
-        const text = self ? formatAudit(entries) : 'Relay is not initialized (no session_start yet).';
+        const text = self ? formatAudit(entries) : uninitializedText();
         if (!self || !ctx.hasUI) {
           pi.sendMessage({ customType: AUDIT_TYPE, content: text, display: true, details: { kind: 'relay-audit' } });
           return;
@@ -833,9 +854,7 @@ export default function relay(pi: ExtensionAPI) {
       }
       if (!self || !ctx.hasUI) {
         // Plain-text fallback (print/rpc mode): the entry renderer never runs there.
-        const text = self
-          ? formatListing(listRecords(root), self.addr, (r) => presenceOf(r))
-          : 'Relay is not initialized (no session_start yet).';
+        const text = self ? formatListing(listRecords(root), self.addr, (r) => presenceOf(r)) : uninitializedText();
         pi.sendMessage({
           customType: LIST_TYPE,
           content: text,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nicknisi/pi-relay",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "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

@@ -16,6 +16,7 @@
  */
 
 import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {
   assertPathSegment,
@@ -47,6 +48,42 @@ export function deriveAddr(cwd: string, sessionId: string): string {
   return crypto.createHash('sha256').update(`${cwd}${sessionId}`).digest('hex').slice(0, 12);
 }
 
+/**
+ * Pin the relay root to its real location, once, before any relay I/O.
+ *
+ * The traversal hardening refuses *user-controlled* ancestor symlinks, because
+ * a user-writable symlink can be swapped between the check and the use. That
+ * is the right rule for every operation after startup — but it also rejects a
+ * legitimate, stable arrangement: a dotfiles setup where `~/.pi` is a symlink
+ * into a managed repo. Since pi keeps everything under `~/.pi`, that made the
+ * relay root unopenable and the whole extension silently inert.
+ *
+ * Resolving once at startup keeps the property that matters. Every later
+ * operation traverses only real directories, so there is no user symlink left
+ * in the path to swap; repointing `~/.pi` afterwards cannot redirect this
+ * process. It is a pin, not a bypass.
+ *
+ * The root may not exist yet on a first run, so resolve the deepest ancestor
+ * that does and re-apply the remainder.
+ */
+export function resolveRelayRoot(root: string): string {
+  const absolute = path.resolve(root);
+  const tail: string[] = [];
+  let current = absolute;
+  for (;;) {
+    try {
+      return path.join(fs.realpathSync(current), ...tail);
+    } catch (error) {
+      if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) throw error;
+      const parent = path.dirname(current);
+      // Filesystem root does not exist: nothing sane left to resolve against.
+      if (parent === current) return absolute;
+      tail.unshift(path.basename(current));
+      current = parent;
+    }
+  }
+}
+
 export function ensureRoot(root: string): void {
   const directory = openRelayRoot(root, true)!;
   directory.close();