@nicknisi/pi-relay 0.3.5 → 0.4.1

package/README.md

@@ -21,7 +21,7 @@ The `@nicknisi/pi-relay/core` subpath exports a narrow record and alias registry
 
 ### 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` deletes that exact 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 descriptors, and empty completed claims are removed automatically.
+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.
 
 ## Audit log
 
@@ -51,10 +51,14 @@ main moved; rebase before you push.
 
 - **A mailbox outlives the process.** The address is a hash of the working directory and pi's session id, so a session resumed with `pi -c` answers to the same address. Mail sent to a closed session waits on disk and is read when it resumes — the common case when you're opening and closing terminals all day.
 - **The queue is inspectable.** Diagnosing delivery is `ls`, not instrumenting a transport.
-- **Delivery is the receipt.** The receiver detaches its inbox into a durable claim and deletes each exact full-message-id letter only after the session has accepted it — a failed delivery is requeued for retry, and a crash mid-delivery leaves the letter recoverable on the next start (redeliveries are deduped by message id, seeded from the transcript). The sender therefore learns _delivered_ vs _queued_ honestly: a claimed-but-unacknowledged letter still reads _queued_, never a false receipt.
+- **Delivery requires proof.** The receiver detaches its inbox into a durable claim and acknowledges each exact full-message-id letter only after the session has accepted it. Failed delivery is requeued, and a crash leaves the letter recoverable on the next start, with redelivery dedupe seeded from the active transcript branch. The sender learns _delivered_ from an exact ACK, _queued_ from a remaining inbox/claim letter, or _uncertain_ when neither exists. Removing mail or its root is not delivery. Older receivers without ACK support yield _uncertain_ once mail disappears; inspect before resending.
 
 ## Semantics
 
+- **Bounded discovery.** `list` and `list-cwd` return up to `limit` sessions (default 20, max 100), excluding self. All presence states are included by default — offline sessions still receive mail — but online sessions sort first, then most recently seen. Filter with `presence: "all" | "online" | "live" | "stalled" | "offline"`. `list-cwd` includes descendants by default; set `includeSubdirectories: false` for exact cwd matching. An explicit `cwd` filters `list` too. Each row includes the full address and Pi `sessionId`, with names and paths sanitized and capped. `sessionIds` accepts up to 64 exact IDs (self included when requested) and reports any that are unregistered or filtered out.
+- **Paging.** When more sessions match, the result includes `details.nextArguments` (the same filters plus the next `offset`). Results reflect current membership and presence, not a frozen snapshot.
+- **Targeting.** `send`, `ask`, and `watch` accept an exact case-sensitive full Pi `sessionId`, relay address, unique address prefix, case-insensitive name, or `@alias`. Collisions are reported with full IDs and addresses rather than choosing a peer.
+- **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.
 - **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.

package/core.ts

@@ -22,6 +22,7 @@ import {
   type InboxClaim,
   type Letter,
   type OutAsk,
+  type SendReceipt,
 } from './mailbox.js';
 import {
   claimAlias as claimAliasInternal,
@@ -46,6 +47,7 @@ export {
   type Letter,
   type LetterKind,
   type OutAsk,
+  type SendReceipt,
 } from './mailbox.js';
 export {
   BACKLOG_CAP,
@@ -258,7 +260,7 @@ export async function awaitReceipt(
   toAddr: string,
   letter: Letter,
   timeoutMs = 1500,
-): Promise<'delivered' | 'queued'> {
+): Promise<SendReceipt> {
   assertAddress(toAddr);
   assertLetter(letter);
   return awaitReceiptInternal(root, toAddr, letter, timeoutMs);

package/discovery.ts

@@ -0,0 +1,152 @@
+import * as path from 'node:path';
+import { listRecords, presenceOf, type Presence, type SessionRecord } from './registry.js';
+
+export type PresenceFilter = 'all' | 'online' | 'live' | 'stalled' | 'offline';
+
+export interface RelayDiscoveryArguments {
+  action: 'list' | 'list-cwd';
+  cwd?: string;
+  includeSubdirectories?: boolean;
+  sessionIds?: string[];
+  presence?: PresenceFilter;
+  limit?: number;
+  offset?: number;
+}
+
+export type RelayDiscoveryInput = RelayDiscoveryArguments & {
+  readonly root: string;
+  readonly selfAddress: string;
+  readonly activeCwd: string;
+  readonly now?: number;
+};
+
+export interface RelayDiscoverySession {
+  readonly sessionId: string;
+  readonly address: string;
+  readonly name: string;
+  readonly cwd: string;
+  readonly presence: Presence;
+  readonly activity: SessionRecord['status'];
+}
+
+export interface RelayDiscoveryDetails {
+  readonly outcome: 'success';
+  readonly action: 'list' | 'list-cwd';
+  readonly total: number;
+  readonly offset: number;
+  readonly returned: number;
+  readonly sessions: readonly RelayDiscoverySession[];
+  /** Requested sessionIds that are not registered or were excluded by cwd/presence. */
+  readonly missingSessionIds: readonly string[];
+  readonly hasMore: boolean;
+  readonly nextArguments?: Record<string, unknown>;
+}
+
+export const DISCOVERY_DEFAULT_LIMIT = 20;
+export const DISCOVERY_MAX_LIMIT = 100;
+const DISPLAY_MAX_CHARS = 96;
+const PRESENCE_RANK: Record<Presence, number> = { live: 0, stalled: 1, offline: 2 };
+
+/** Strip terminal escapes/control characters and cap length — names and cwds are peer-controlled. */
+function display(value: string): string {
+  // oxlint-disable-next-line no-control-regex
+  const cleaned = value.replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, '').replace(/[\u0000-\u001f\u007f]/g, ' ');
+  const collapsed = cleaned.replace(/\s+/g, ' ').trim();
+  return collapsed.length <= DISPLAY_MAX_CHARS ? collapsed : `${collapsed.slice(0, DISPLAY_MAX_CHARS - 1)}…`;
+}
+
+function matchesPresence(presence: Presence, filter: PresenceFilter): boolean {
+  if (filter === 'all') return true;
+  if (filter === 'online') return presence !== 'offline';
+  return presence === filter;
+}
+
+function inCwd(recordCwd: string, cwd: string, includeSubdirectories: boolean): boolean {
+  if (!includeSubdirectories) return recordCwd === cwd;
+  const relative = path.relative(path.resolve(cwd), path.resolve(recordCwd));
+  return relative === '' || (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+
+/**
+ * Bounded session discovery. Online sessions sort first, then most recently
+ * seen, so the default page shows reachable peers without hiding offline
+ * mailboxes (mail to a closed session is a first-class use case).
+ */
+export function discoverRelaySessions(input: RelayDiscoveryInput): { text: string; details: RelayDiscoveryDetails } {
+  const limit = input.limit ?? DISCOVERY_DEFAULT_LIMIT;
+  const offset = input.offset ?? 0;
+  if (!Number.isInteger(limit) || limit < 1 || limit > DISCOVERY_MAX_LIMIT)
+    throw new Error(`limit must be an integer from 1 to ${DISCOVERY_MAX_LIMIT}.`);
+  if (!Number.isInteger(offset) || offset < 0) throw new Error('offset must be a non-negative integer.');
+
+  const now = input.now ?? Date.now();
+  const cwd = input.action === 'list-cwd' ? (input.cwd ?? input.activeCwd) : input.cwd;
+  const includeSubdirectories = input.includeSubdirectories !== false;
+  const filter = input.presence ?? 'all';
+  const wanted = input.sessionIds ? new Set(input.sessionIds) : undefined;
+
+  const matching = listRecords(input.root)
+    .filter((r) => (wanted ? wanted.has(r.sessionId) : r.addr !== input.selfAddress))
+    .filter((r) => cwd === undefined || inCwd(r.cwd, cwd, includeSubdirectories))
+    .map((record) => ({ record, presence: presenceOf(record, now) }))
+    .filter(({ presence }) => matchesPresence(presence, filter))
+    .sort(
+      (a, b) =>
+        PRESENCE_RANK[a.presence] - PRESENCE_RANK[b.presence] ||
+        b.record.lastSeenAt - a.record.lastSeenAt ||
+        a.record.addr.localeCompare(b.record.addr),
+    );
+
+  const sessions = matching.slice(offset, offset + limit).map(({ record, presence }): RelayDiscoverySession => ({
+    sessionId: record.sessionId,
+    address: record.addr,
+    name: display(record.name),
+    cwd: display(record.cwd),
+    presence,
+    activity: record.status,
+  }));
+  const found = new Set(matching.map(({ record }) => record.sessionId));
+  const missingSessionIds = input.sessionIds?.filter((id) => !found.has(id)) ?? [];
+  const hasMore = offset + sessions.length < matching.length;
+  const nextArguments = hasMore
+    ? {
+        action: input.action,
+        ...(input.cwd !== undefined && { cwd: input.cwd }),
+        ...(input.includeSubdirectories !== undefined && { includeSubdirectories: input.includeSubdirectories }),
+        ...(input.sessionIds !== undefined && { sessionIds: input.sessionIds }),
+        ...(input.presence !== undefined && { presence: input.presence }),
+        limit,
+        offset: offset + sessions.length,
+      }
+    : undefined;
+
+  const scope =
+    cwd === undefined ? '' : ` in ${includeSubdirectories ? 'cwd subtree' : 'cwd'} ${JSON.stringify(display(cwd))}`;
+  const lines = [
+    `${matching.length} session${matching.length === 1 ? '' : 's'}${scope}${filter === 'all' ? '' : ` (presence=${filter})`}; showing ${sessions.length === 0 ? 'none' : `${offset + 1}-${offset + sessions.length}`}.`,
+    ...sessions.map(
+      (s) =>
+        `sessionId=${JSON.stringify(s.sessionId)} address=${s.address} presence=${s.presence} activity=${s.activity} name=${JSON.stringify(s.name)}${cwd === undefined || s.cwd !== cwd ? ` cwd=${JSON.stringify(s.cwd)}` : ''}`,
+    ),
+  ];
+  if (missingSessionIds.length > 0)
+    lines.push(
+      `Not found (unregistered or filtered out): ${missingSessionIds.map((id) => JSON.stringify(id)).join(', ')}`,
+    );
+  if (nextArguments) lines.push(`More sessions available. Continue with ${JSON.stringify(nextArguments)}.`);
+
+  return {
+    text: lines.join('\n'),
+    details: {
+      outcome: 'success',
+      action: input.action,
+      total: matching.length,
+      offset,
+      returned: sessions.length,
+      sessions,
+      missingSessionIds,
+      hasMore,
+      ...(nextArguments && { nextArguments }),
+    },
+  };
+}

package/dist/core.d.ts

@@ -1,7 +1,7 @@
 /** Pi-free relay registry, mailbox, and policy API for non-extension consumers. */
-import { type AuditRecord, type InboxClaim, type Letter, type OutAsk } from './mailbox.js';
+import { type AuditRecord, type InboxClaim, type Letter, type OutAsk, type SendReceipt } from './mailbox.js';
 import { type AliasRecord, type Presence, type SessionRecord } from './registry.js';
-export { MAX_BODY_CHARS, previewBody, type AuditRecord, type InboxClaim, type Letter, type LetterKind, type OutAsk, } from './mailbox.js';
+export { MAX_BODY_CHARS, previewBody, type AuditRecord, type InboxClaim, type Letter, type LetterKind, type OutAsk, type SendReceipt, } from './mailbox.js';
 export { BACKLOG_CAP, DEDUPE_WINDOW_MS, OutboundPolicy, RATE_LIMIT_MAX, RATE_LIMIT_WINDOW_MS, inboundAccepts, type OutboundVerdict, } from './policy.js';
 export { HEARTBEAT_STALE_MS, SWEEP_MAIL_KEEP_MS, deriveAddr, isValidAliasName, type AliasRecord, type Presence, type SessionRecord, } from './registry.js';
 export declare function readRecord(root: string, addr: string): SessionRecord | null;
@@ -21,7 +21,7 @@ export declare function readClaimedLetter(root: string, addr: string, claimToken
 export declare function ackClaimedLetter(root: string, addr: string, claimToken: string, fileToken: string): boolean;
 export declare function requeueClaimedLetter(root: string, addr: string, claimToken: string, fileToken: string): boolean;
 export declare function watchInbox(root: string, addr: string, onMail: () => void): () => void;
-export declare function awaitReceipt(root: string, toAddr: string, letter: Letter, timeoutMs?: number): Promise<'delivered' | 'queued'>;
+export declare function awaitReceipt(root: string, toAddr: string, letter: Letter, timeoutMs?: number): Promise<SendReceipt>;
 export declare function trackIncomingAsk(root: string, addr: string, letter: Letter): void;
 export declare function trackOutgoingAsk(root: string, addr: string, out: OutAsk): void;
 export declare function readIncomingAsk(root: string, addr: string, askId: string): Letter | null;

package/dist/core.test.js

@@ -322,8 +322,27 @@ it('builds, packs, installs, and imports the real core package without Pi or TUI
     const tarball = path.join(base, 'relay.tgz');
     const appDir = path.join(base, 'app');
     fs.mkdirSync(appDir);
-    execFileSync('pnpm', ['--filter', packageJson.name, 'build'], { cwd: repoRoot, stdio: 'pipe' });
-    execFileSync('pnpm', ['pack', '--out', tarball], { cwd: relayDir, stdio: 'pipe' });
+    // The repository build script rebuilds every package, even with --filter.
+    // Keep that mutation away from concurrent tests and their mocked workspace imports.
+    const sourceRoot = path.join(base, 'source');
+    const sourceRelay = path.join(sourceRoot, 'packages', 'relay');
+    fs.mkdirSync(path.join(sourceRoot, 'scripts'), { recursive: true });
+    fs.mkdirSync(sourceRelay, { recursive: true });
+    fs.writeFileSync(path.join(sourceRoot, 'package.json'), JSON.stringify({ private: true, type: 'module' }));
+    fs.copyFileSync(path.join(repoRoot, 'tsconfig.json'), path.join(sourceRoot, 'tsconfig.json'));
+    fs.copyFileSync(path.join(repoRoot, 'scripts', 'build.ts'), path.join(sourceRoot, 'scripts', 'build.ts'));
+    for (const entry of fs.readdirSync(relayDir, { withFileTypes: true })) {
+        if (entry.isFile() &&
+            (entry.name.endsWith('.ts') || ['package.json', 'README.md', 'LICENSE'].includes(entry.name))) {
+            fs.copyFileSync(path.join(relayDir, entry.name), path.join(sourceRelay, entry.name));
+        }
+    }
+    fs.symlinkSync(path.join(repoRoot, 'node_modules'), path.join(sourceRoot, 'node_modules'), 'dir');
+    if (fs.existsSync(path.join(relayDir, 'node_modules'))) {
+        fs.symlinkSync(path.join(relayDir, 'node_modules'), path.join(sourceRelay, 'node_modules'), 'dir');
+    }
+    execFileSync(process.execPath, [path.join(sourceRoot, 'scripts', 'build.ts')], { cwd: sourceRoot, stdio: 'pipe' });
+    execFileSync('pnpm', ['pack', '--out', tarball], { cwd: sourceRelay, stdio: 'pipe' });
     fs.writeFileSync(path.join(appDir, 'package.json'), JSON.stringify({
         private: true,
         type: 'module',
@@ -338,6 +357,8 @@ it('builds, packs, installs, and imports the real core package without Pi or TUI
         expect(fs.existsSync(path.join(installedDir, target))).toBe(true);
     }
     expect(fs.existsSync(path.join(installedDir, 'filesystem.ts'))).toBe(true);
+    expect(fs.existsSync(path.join(installedDir, 'discovery.ts'))).toBe(true);
+    expect(fs.existsSync(path.join(installedDir, 'routing.ts'))).toBe(true);
     expect(packageJson.peerDependenciesMeta['@earendil-works/pi-coding-agent']?.optional).toBe(true);
     expect(packageJson.peerDependenciesMeta['@earendil-works/pi-tui']?.optional).toBe(true);
     expect(fs.existsSync(path.join(appDir, 'node_modules', '@earendil-works', 'pi-coding-agent'))).toBe(false);

package/dist/discovery.d.ts

@@ -0,0 +1,48 @@
+import { type Presence, type SessionRecord } from './registry.js';
+export type PresenceFilter = 'all' | 'online' | 'live' | 'stalled' | 'offline';
+export interface RelayDiscoveryArguments {
+    action: 'list' | 'list-cwd';
+    cwd?: string;
+    includeSubdirectories?: boolean;
+    sessionIds?: string[];
+    presence?: PresenceFilter;
+    limit?: number;
+    offset?: number;
+}
+export type RelayDiscoveryInput = RelayDiscoveryArguments & {
+    readonly root: string;
+    readonly selfAddress: string;
+    readonly activeCwd: string;
+    readonly now?: number;
+};
+export interface RelayDiscoverySession {
+    readonly sessionId: string;
+    readonly address: string;
+    readonly name: string;
+    readonly cwd: string;
+    readonly presence: Presence;
+    readonly activity: SessionRecord['status'];
+}
+export interface RelayDiscoveryDetails {
+    readonly outcome: 'success';
+    readonly action: 'list' | 'list-cwd';
+    readonly total: number;
+    readonly offset: number;
+    readonly returned: number;
+    readonly sessions: readonly RelayDiscoverySession[];
+    /** Requested sessionIds that are not registered or were excluded by cwd/presence. */
+    readonly missingSessionIds: readonly string[];
+    readonly hasMore: boolean;
+    readonly nextArguments?: Record<string, unknown>;
+}
+export declare const DISCOVERY_DEFAULT_LIMIT = 20;
+export declare const DISCOVERY_MAX_LIMIT = 100;
+/**
+ * Bounded session discovery. Online sessions sort first, then most recently
+ * seen, so the default page shows reachable peers without hiding offline
+ * mailboxes (mail to a closed session is a first-class use case).
+ */
+export declare function discoverRelaySessions(input: RelayDiscoveryInput): {
+    text: string;
+    details: RelayDiscoveryDetails;
+};

package/dist/discovery.js

@@ -0,0 +1,97 @@
+import * as path from 'node:path';
+import { listRecords, presenceOf } from './registry.js';
+export const DISCOVERY_DEFAULT_LIMIT = 20;
+export const DISCOVERY_MAX_LIMIT = 100;
+const DISPLAY_MAX_CHARS = 96;
+const PRESENCE_RANK = { live: 0, stalled: 1, offline: 2 };
+/** Strip terminal escapes/control characters and cap length — names and cwds are peer-controlled. */
+function display(value) {
+    // oxlint-disable-next-line no-control-regex
+    const cleaned = value.replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, '').replace(/[\u0000-\u001f\u007f]/g, ' ');
+    const collapsed = cleaned.replace(/\s+/g, ' ').trim();
+    return collapsed.length <= DISPLAY_MAX_CHARS ? collapsed : `${collapsed.slice(0, DISPLAY_MAX_CHARS - 1)}…`;
+}
+function matchesPresence(presence, filter) {
+    if (filter === 'all')
+        return true;
+    if (filter === 'online')
+        return presence !== 'offline';
+    return presence === filter;
+}
+function inCwd(recordCwd, cwd, includeSubdirectories) {
+    if (!includeSubdirectories)
+        return recordCwd === cwd;
+    const relative = path.relative(path.resolve(cwd), path.resolve(recordCwd));
+    return relative === '' || (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+/**
+ * Bounded session discovery. Online sessions sort first, then most recently
+ * seen, so the default page shows reachable peers without hiding offline
+ * mailboxes (mail to a closed session is a first-class use case).
+ */
+export function discoverRelaySessions(input) {
+    const limit = input.limit ?? DISCOVERY_DEFAULT_LIMIT;
+    const offset = input.offset ?? 0;
+    if (!Number.isInteger(limit) || limit < 1 || limit > DISCOVERY_MAX_LIMIT)
+        throw new Error(`limit must be an integer from 1 to ${DISCOVERY_MAX_LIMIT}.`);
+    if (!Number.isInteger(offset) || offset < 0)
+        throw new Error('offset must be a non-negative integer.');
+    const now = input.now ?? Date.now();
+    const cwd = input.action === 'list-cwd' ? (input.cwd ?? input.activeCwd) : input.cwd;
+    const includeSubdirectories = input.includeSubdirectories !== false;
+    const filter = input.presence ?? 'all';
+    const wanted = input.sessionIds ? new Set(input.sessionIds) : undefined;
+    const matching = listRecords(input.root)
+        .filter((r) => (wanted ? wanted.has(r.sessionId) : r.addr !== input.selfAddress))
+        .filter((r) => cwd === undefined || inCwd(r.cwd, cwd, includeSubdirectories))
+        .map((record) => ({ record, presence: presenceOf(record, now) }))
+        .filter(({ presence }) => matchesPresence(presence, filter))
+        .sort((a, b) => PRESENCE_RANK[a.presence] - PRESENCE_RANK[b.presence] ||
+        b.record.lastSeenAt - a.record.lastSeenAt ||
+        a.record.addr.localeCompare(b.record.addr));
+    const sessions = matching.slice(offset, offset + limit).map(({ record, presence }) => ({
+        sessionId: record.sessionId,
+        address: record.addr,
+        name: display(record.name),
+        cwd: display(record.cwd),
+        presence,
+        activity: record.status,
+    }));
+    const found = new Set(matching.map(({ record }) => record.sessionId));
+    const missingSessionIds = input.sessionIds?.filter((id) => !found.has(id)) ?? [];
+    const hasMore = offset + sessions.length < matching.length;
+    const nextArguments = hasMore
+        ? {
+            action: input.action,
+            ...(input.cwd !== undefined && { cwd: input.cwd }),
+            ...(input.includeSubdirectories !== undefined && { includeSubdirectories: input.includeSubdirectories }),
+            ...(input.sessionIds !== undefined && { sessionIds: input.sessionIds }),
+            ...(input.presence !== undefined && { presence: input.presence }),
+            limit,
+            offset: offset + sessions.length,
+        }
+        : undefined;
+    const scope = cwd === undefined ? '' : ` in ${includeSubdirectories ? 'cwd subtree' : 'cwd'} ${JSON.stringify(display(cwd))}`;
+    const lines = [
+        `${matching.length} session${matching.length === 1 ? '' : 's'}${scope}${filter === 'all' ? '' : ` (presence=${filter})`}; showing ${sessions.length === 0 ? 'none' : `${offset + 1}-${offset + sessions.length}`}.`,
+        ...sessions.map((s) => `sessionId=${JSON.stringify(s.sessionId)} address=${s.address} presence=${s.presence} activity=${s.activity} name=${JSON.stringify(s.name)}${cwd === undefined || s.cwd !== cwd ? ` cwd=${JSON.stringify(s.cwd)}` : ''}`),
+    ];
+    if (missingSessionIds.length > 0)
+        lines.push(`Not found (unregistered or filtered out): ${missingSessionIds.map((id) => JSON.stringify(id)).join(', ')}`);
+    if (nextArguments)
+        lines.push(`More sessions available. Continue with ${JSON.stringify(nextArguments)}.`);
+    return {
+        text: lines.join('\n'),
+        details: {
+            outcome: 'success',
+            action: input.action,
+            total: matching.length,
+            offset,
+            returned: sessions.length,
+            sessions,
+            missingSessionIds,
+            hasMore,
+            ...(nextArguments && { nextArguments }),
+        },
+    };
+}

package/dist/discovery.test.d.ts

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

package/dist/discovery.test.js

@@ -0,0 +1,95 @@
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { afterEach, expect, it } from 'vitest';
+import { discoverRelaySessions } from './discovery.js';
+import { deriveAddr, writeRecord } from './registry.js';
+import { resolveReplyTarget, resolveSessionTarget } from './routing.js';
+const fixtures = [];
+afterEach(() => {
+    for (const root of fixtures.splice(0))
+        fs.rmSync(root, { recursive: true, force: true });
+});
+function fixture() {
+    const root = fs.realpathSync.native(fs.mkdtempSync(path.join(os.tmpdir(), 'relay-discovery-')));
+    fixtures.push(root);
+    return root;
+}
+function record(id, over = {}) {
+    return {
+        addr: deriveAddr('/work', id),
+        sessionId: id,
+        name: id,
+        cwd: '/work',
+        pid: process.pid,
+        startedAt: 100,
+        lastSeenAt: Date.now(),
+        status: 'idle',
+        ...over,
+    };
+}
+function input(root, over = {}) {
+    return { action: 'list-cwd', root, selfAddress: deriveAddr('/work', 'self'), activeCwd: '/work', ...over };
+}
+it('defaults to all peers sorted online-first, includes descendants, and supports exact lookups', () => {
+    const root = fixture();
+    const now = Date.now();
+    for (const r of [
+        record('self'),
+        record('offline', { offline: true, lastSeenAt: now }),
+        record('older', { lastSeenAt: now - 1000 }),
+        record('live', { lastSeenAt: now }),
+        record('child', { cwd: '/work/child', lastSeenAt: now - 2000 }),
+        record('sibling', { cwd: '/workspace' }),
+    ])
+        writeRecord(root, r);
+    const all = discoverRelaySessions(input(root, { now }));
+    expect(all.details.sessions.map((r) => r.sessionId)).toEqual(['live', 'older', 'child', 'offline']);
+    expect(discoverRelaySessions(input(root, { now, includeSubdirectories: false })).details.sessions.map((r) => r.sessionId)).toEqual(['live', 'older', 'offline']);
+    expect(discoverRelaySessions(input(root, { now, presence: 'online' })).details.sessions.map((r) => r.sessionId)).toEqual(['live', 'older', 'child']);
+    const exact = discoverRelaySessions(input(root, { now, sessionIds: ['offline', 'self', 'sibling', 'unknown'] }));
+    expect(exact.details.sessions.map((r) => r.sessionId)).toEqual(['self', 'offline']);
+    expect(exact.details.missingSessionIds).toEqual(['sibling', 'unknown']);
+    expect(discoverRelaySessions(input(root, { action: 'list', now })).details.sessions.map((r) => r.sessionId)).toContain('sibling');
+});
+it('pages with nextArguments and sanitizes peer-controlled display fields', () => {
+    const root = fixture();
+    for (let i = 0; i < 25; i++)
+        writeRecord(root, record(`session-${String(i).padStart(2, '0')}`, { name: `\u001b[31mname-${i}\u0007` }));
+    const first = discoverRelaySessions(input(root));
+    expect(first.details).toMatchObject({ returned: 20, total: 25, hasMore: true });
+    expect(first.text).not.toContain('\u001b');
+    expect(first.text).toContain(first.details.sessions[0].address);
+    const next = discoverRelaySessions(input(root, first.details.nextArguments));
+    expect(next.details).toMatchObject({ offset: 20, returned: 5, hasMore: false });
+    const seen = [...first.details.sessions, ...next.details.sessions].map((r) => r.sessionId);
+    expect(new Set(seen).size).toBe(25);
+    expect(() => discoverRelaySessions(input(root, { limit: 0 }))).toThrow(/limit/);
+    expect(() => discoverRelaySessions(input(root, { offset: -1 }))).toThrow(/offset/);
+    writeRecord(root, record('long', { name: 'x'.repeat(500) }));
+    const long = discoverRelaySessions(input(root, { sessionIds: ['long'] })).details.sessions[0];
+    expect(long.name.length).toBeLessThanOrEqual(96);
+});
+it('routes exact session IDs case-sensitively and refuses collisions instead of guessing', () => {
+    const peer = record('Exact-ID', { name: 'Human title' });
+    expect(resolveSessionTarget(peer.sessionId, [peer], 'self').record).toEqual(peer);
+    expect(resolveSessionTarget('exact-id', [peer], 'self').error).toBeDefined();
+    expect(resolveSessionTarget(peer.sessionId, [peer, record('other', { name: peer.sessionId })], 'self').error).toContain('ambiguous');
+    expect(resolveSessionTarget(peer.sessionId, [peer, { ...peer, addr: deriveAddr('/other', peer.sessionId) }], 'self').error).toContain('ambiguous');
+    expect(resolveSessionTarget(peer.sessionId, [peer], peer.addr).error).toBeDefined();
+});
+it('resolves ordinary replies from only the active branch and rejects conflicting senders and watcher entries', () => {
+    const id = 'ordinary-message';
+    const peer = record('peer');
+    const entry = {
+        type: 'custom_message',
+        customType: 'relay:delivery',
+        details: { id, kind: 'message', from: { addr: peer.addr } },
+    };
+    expect(resolveReplyTarget(id, [], [entry]).target).toEqual({ id, addr: peer.addr, ask: false });
+    expect(resolveReplyTarget(id, [], []).error).toContain('active conversation');
+    expect(resolveReplyTarget(id, [], [{ ...entry, details: { ...entry.details, kind: 'cancel' } }]).error).toBeDefined();
+    expect(resolveReplyTarget(id, [], [entry, { ...entry, details: { ...entry.details, from: { addr: record('other').addr } } }]).error).toContain('ambiguous');
+    expect(resolveReplyTarget(id, [], [entry, entry]).target?.addr).toBe(peer.addr);
+    expect(resolveReplyTarget(id, [], [entry, { ...entry, details: { ...entry.details, id: `${id}-longer` } }]).target?.id).toBe(id);
+});

package/dist/extension.test.d.ts

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