@nicknisi/pi-relay 0.3.1 → 0.3.2

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/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.2",
   "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();