@pi-chamber/web 0.1.8

package/server/lib/pi/session-daemon/DOCUMENTATION.md

@@ -0,0 +1,41 @@
+# Pi Session Daemon
+
+## Purpose
+
+This module is the Pi-owned session-daemon foundation. A detached local daemon process creates an `AgentSessionRuntime` with the Pi SDK, tracks it in a registry keyed by Pi session identity and cwd, keeps it behind a private local socket, and maps a small event subset to the PiChamber IPC contract. Browsers never connect to it.
+
+## Entrypoints
+
+- `session-daemon.js`
+  - `createPiSessionRuntime({ cwd, agentDir })` creates a persistent Pi runtime using the selected server-side cwd and Pi agent directory. It uses Pi's normal settings, credentials, models, sessions, skills, prompts, and context discovery, with native extensions explicitly disabled for the core milestone. Sessions created outside PiChamber (Pi CLI or any other writer of the cwd-scoped JSONL directory) are the same records: `sessions.list`/`open` hydrate from `getEntries()`, and a later prompt must overlay live turns onto that log rather than replace it.
+  - `createSessionDaemon(options)` starts/stops the authenticated local socket daemon and validates its endpoint and setup inputs.
+- `daemon-process.js` is the detached private-process entrypoint. It reads the daemon credential from its owner-only sidecar, starts the socket, writes non-secret identity state only after readiness, and removes only its own state on signal shutdown.
+- `ipc-client.js` is the server-only authenticated request client. It owns JSONL framing and never exposes endpoint or credential values to callers.
+- `runtime-registry.js` owns active runtime identities and session-local subscriptions. It rebinds the subscription after an SDK session replacement, rejects identity conflicts rather than displacing another runtime, and attempts every tracked disposal even when another disposal fails.
+- `session-jsonl.js` validates the cwd-scoped Pi JSONL directory before session discovery. Pi's SDK deliberately skips malformed discovery entries; this boundary maps malformed, missing, and unreadable candidates to stable explicit failures instead of an empty result. Directory names match Pi's SessionManager encoding, including Windows drive letters and Git Bash/MSYS/Cygwin/WSL `/c/...` paths so PiChamber and the Pi CLI share the same JSONL sessions.
+- `supervisor.js` resolves server-only overrides, creates the credential, serializes start/reuse/stop through an owner-only lock, validates daemon identity through `runtime.health`, forwards server-owned commands only after that identity check, and starts or stops the detached process. When the parent is Electron, the child is spawned with `ELECTRON_RUN_AS_NODE=1` so packaged Windows/macOS/Linux apps run the daemon as Node instead of a hidden second Electron GUI process.
+- `../routes.js` registers authenticated public adapters before the generic proxy. It exposes only whitelisted runtime, project, session, provider-auth/configuration, settings, resource, and SSE event shapes; no browser response contains daemon paths, credentials, PIDs, headers, or socket framing. Session actions are path-selected, so an identity supplied in a request body cannot redirect a mutation. `archive-store.js` persists PiChamber-only opaque session archive metadata atomically beneath the PiChamber data root and never edits Pi JSONL. `settings-store.js` keeps PiChamber new-session defaults separate from Pi settings.json. `GET /api/pi/settings` copies leftover UI/desktop `defaultModel` / small / walkthrough strings into that sidecar when those sidecar fields are unset, then Sessions settings is the only editor. Sidecar `defaultThinkingByModel` is the per-model thinking map (`provider/model` keys). A stored global `defaultThinking` with a default model is copied onto that map key and dropped; global thinking without a default model remains a clamp-only fallback. `ui-settings-store.js` atomically owns shared PiChamber UI preferences at the data-root `settings.json`; it is exposed as `/api/pi/ui-settings`, not through removed `/api/config/*` aliases. `session-folders-store.js` validates and atomically persists the restored sidebar's folder snapshot at `/api/pi/session-folders`; a missing snapshot is distinct from an empty one. `custom-themes.js` serves validated custom-theme candidates from `/api/pi/themes` with per-file partial-failure isolation. `model-config-store.js` atomically updates Pi's credential-blind `models.json`; literal keys continue through Pi auth and headers are write-only. `providers.config.get` returns `config: null` for a provider that is not in `models.json` (built-in catalog entries) and fails only when that file is present but malformed.
+- `*.test.js` uses temporary cwd, agent, data, and runtime directories; it never loads a developer's Pi home, credentials, or sessions. On Windows the private endpoint is a named pipe, not a `.sock` file, and POSIX mode-bit assertions are skipped.
+
+## Protocol and security invariants
+
+- The endpoint is a Unix domain socket on POSIX or a Windows named pipe. TCP endpoints are rejected. Listeners and clients connect with IPC `path` options so Windows `\\.\pipe\pichamber-pi-session-daemon-<owner-key>` works the same as a POSIX socket path.
+- POSIX socket parent directories are mode `0700`; the socket is created mode `0600`. An existing endpoint fails startup rather than being unlinked without daemon-identity verification. Windows named-pipe ACLs are not yet equivalent owner-only OS permissions; credential authentication remains mandatory.
+- The daemon credential and non-secret state sidecars are mode `0600`; their PiChamber parent directory and the operation lock serialize start/reuse/stop. Exclusive lock create writes the owner pid in the same step. A leftover empty or malformed lock, a dead owner pid, or Windows `EPERM`/`EACCES` on exclusive create is retried and stolen after a short freshness window instead of failing as `DAEMON_LOCK_UNAVAILABLE`. Sidecar `chmod` failures on Windows are ignored after the file exists so readiness is still recorded. Health identity includes the daemon PID and must match the state sidecar before the supervisor reuses or signals a process.
+- The public health route deliberately whitelists its response fields. It never returns a daemon endpoint, credential, PID, cwd, agent directory, or transcript data. Public transcript and event projections preserve daemon-redacted assistant error messages so the UI can distinguish provider/runtime failures instead of reducing every failure to `ASSISTANT_ERROR`.
+- A client must send an `authenticate` frame carrying the host-private daemon credential before it can issue a request. Credentials are never logged or returned.
+- Frames are LF-delimited JSON. They have a 1 MiB maximum buffered size. A malformed, oversized, unauthenticated, or invalid request closes the connection.
+- The private core commands are `runtime.health`, `projects.list/select`, `providers.list/config.get/models.set/status/login/login.respond/login.status/logout`, `settings.get/set`, `resources.list/update/prompts.create/prompts.delete`, and session list/create/open/rename/delete/tree/navigate/fork/clone/prompt/steer/followUp/abort/model/thinking/compact operations. Resource lists use opaque IDs and never disclose server paths. Only top-level Pi prompt templates and applicable AGENTS.md sources are editable; package/path resources and skills are browse-only. Resource writes are rejected while a session streams, use an atomic replace, then recreate the idle runtime. Project trust changes are persisted in Pi trust.json and likewise recreate an idle runtime; extensions remain disabled regardless of trust. Provider login submits API keys only across authenticated private IPC or brokers Pi's OAuth/device/manual-code interaction; public projections contain only opaque login IDs, prompts, URLs/device codes, model catalog/configuration, and stable states, never credentials or write-only headers. `providers.models.set` is rejected while a session streams, atomically persists Pi's `models.json`, then rehydrates the idle runtime so the catalog is authoritative immediately. `providers.list` projects only catalog and authentication-status metadata, including Pi-supported `thinkingLevels` (`null` map entries hidden, `xhigh`/`max` opt-in). Session thinking overrides are clamped to the live model's supported levels. `sessions.list` revalidates the selected cwd's JSONL directory before SDK discovery and returns no JSONL paths. The browser explicitly selects an existing user-chosen project directory before listing it; the daemon's startup cwd is an internal fallback, not a user-visible default project. Unnamed persisted sessions use their first prompt as a readable list title when available. `sessions.open` and `getSession` project the last assistant `provider`/`model`/`thinkingLevel` onto the session record so reopening a chat keeps that cache identity. Session selection validates a persisted JSONL path before Pi opens it; inactive mutations are never directed by a browser-supplied path. Attachment paths originate in the server-local upload map and cross only private IPC into Pi's tool context. Pi may persist or echo those paths in its authoritative JSONL transcript, so every public projection redacts them recursively: session titles/previews, user and assistant text/thinking, tool arguments, errors, snapshots, and live message events never expose the server-local path. The daemon maps Pi message lifecycle, deltas, tools, queue changes, model/thinking, compaction, and interruption state to canonical events. Tool events carry redacted input arguments, cumulative partial-output snapshots, final output, error text, renderer metadata (edit diffs, truncation notes), and start/end timestamps. Persisted `toolResult` entries merge into their assistant `toolCall` parts as output/error/end time so hydrated sessions render complete tool cards; tool-result entries never surface as standalone messages. Assistant message projections and start events carry the owning user-message id so the restored turn renderer can group and display replies; all assistant entries in a tool loop remain attached to the latest user turn. Assistant message projections also pass through Pi's per-turn `Usage` (input, output, cacheRead, cacheWrite, totalTokens, and the same five numeric cost fields). The daemon sanitizes the raw payload through `projectUsage` before publication: every numeric must be finite and non-negative, the whole object is omitted when any field is missing or wrong type, and unknown keys are never copied. The `assistant.message.end` event carries the same sanitized usage so the last turn updates without waiting for a full `getSession` refetch. The public route whitelist re-applies the same sanitizer on each projection so a stale or malformed payload from a different daemon version cannot surface as `NaN` or `Infinity` in the reducer.
+- Each event and reconnect snapshot has a monotonic sequence. A reconnect receives a bounded contiguous replay after its cursor when available, otherwise an authoritative `session.snapshot`; unavailable runtimes are not represented as empty sessions.
+- Prompt, steer, and follow-up requests acknowledge acceptance immediately after Pi accepts the call; the daemon owns the still-running send promise and publishes any asynchronous rejection as `session.error`. A later prompt on the same session invalidates that rejection so it cannot error the new turn. If the rejected send left Pi streaming, the daemon aborts it. Steer/follow-up against an idle session starts a new prompt instead of `SESSION_NOT_RUNNING`. Agent completion is never held behind the 30-second public/private request budgets.
+- Registry keys combine the SDK session ID with its cwd. A replacement subscription is rebound to the replacement session so old-session events cannot be published under the new identity. A collision is a visible error; it never replaces or disposes an unrelated runtime.
+- After `agent_settled`, the daemon disposes an idle runtime after five minutes (injectable for tests). Disposal never deletes Pi JSONL; the daemon remembers the selected session file and recreates that runtime on the next private prompt. A new agent start cancels a pending disposal.
+- A startup validation failure writes only a stable failure code to the owner-only non-secret state sidecar. It never records a transcript, session path, or credential. The supervisor surfaces that code as unavailable instead of claiming an empty or idle session.
+- After a forced crash, the next health, request, or subscription probe re-runs supervised startup. Daemon readiness has its own 15-second bounded budget, separate from the shorter lock and shutdown budget, because loading Pi settings and provider/model catalogs can legitimately exceed five seconds. The supervisor removes an existing POSIX socket only when its recorded daemon PID is dead, the endpoint is a socket, and authenticated IPC deterministically refuses or times out. An endpoint that responds, authenticates incorrectly, returns malformed protocol data, or cannot be classified remains `DAEMON_ENDPOINT_UNVERIFIED`.
+- The daemon owns the runtime after clients disconnect. Disconnecting the web-server client cannot stop active Pi work.
+
+## Deliberate limits
+
+This module defines the authenticated session API boundary consumed by the Pi-native session UI. Resource configuration and richer attachment extraction remain owned by their dedicated workstreams. The session event stream is SSE over the existing authenticated runtime transport; WebSocket callers fall back to it, preserving direct and relay behavior without a second daemon listener.
+
+The Pi SDK is pinned exactly at `0.84.1`. Any Pi 0.x minor upgrade requires a deliberate SDK/release-note review and repeat of this module's disposable-runtime smoke validation.

package/server/lib/pi/session-daemon/daemon-process.js

@@ -0,0 +1,113 @@
+import { readFile, chmod, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+
+import { createSessionDaemon } from './session-daemon.js';
+
+const argument = (name) => {
+  const index = process.argv.indexOf(name);
+  return index === -1 ? undefined : process.argv[index + 1];
+};
+
+const endpoint = argument('--endpoint');
+const credentialFile = argument('--credential-file');
+const stateFile = argument('--state-file');
+const cwd = argument('--cwd');
+const agentDir = argument('--agent-dir');
+
+const exitWithFailure = (code) => {
+  // Do not log configuration paths, credentials, or session data from this
+  // private process. The parent maps startup failure to a stable error code.
+  process.exitCode = code;
+};
+
+const chmodIfPossible = async (filePath, mode) => {
+  try {
+    await chmod(filePath, mode);
+  } catch {
+    // Windows and some filesystems reject POSIX mode bits; the sidecar must
+    // still become the ready/failure record.
+  }
+};
+
+const writeState = async (state) => {
+  const temporaryPath = `${stateFile}.${process.pid}.tmp`;
+  await writeFile(temporaryPath, JSON.stringify(state), { mode: 0o600 });
+  await chmodIfPossible(temporaryPath, 0o600);
+  await rename(temporaryPath, stateFile);
+  await chmodIfPossible(stateFile, 0o600);
+};
+
+const writeReadyState = () => writeState({
+  protocolVersion: 1,
+  pid: process.pid,
+  endpoint,
+  startedAt: new Date().toISOString(),
+});
+
+const writeFailureState = (code) => writeState({
+  protocolVersion: 1,
+  pid: process.pid,
+  endpoint,
+  state: 'failed',
+  error: { code },
+});
+
+const removeOwnState = async () => {
+  try {
+    const state = JSON.parse(await readFile(stateFile, 'utf8'));
+    if (state?.pid === process.pid) await rm(stateFile, { force: true });
+  } catch {
+    // A missing or malformed state sidecar cannot block daemon shutdown.
+  }
+};
+
+if (!endpoint || !credentialFile || !stateFile || !cwd) {
+  exitWithFailure(64);
+} else {
+  let daemon;
+  let stopping = false;
+  try {
+    const credential = (await readFile(credentialFile, 'utf8')).trim();
+    daemon = createSessionDaemon({
+      endpoint,
+      credential,
+      cwd,
+      ...(agentDir ? { agentDir } : {}),
+      healthMetadata: { daemonPid: process.pid },
+    });
+    await daemon.start();
+    await writeReadyState();
+  } catch (error) {
+    try {
+      await daemon?.stop();
+    } catch {
+      // Process exit closes the local listener if startup cleanup also failed.
+    }
+    if (error?.code === 'MALFORMED_SESSION_JSONL' || error?.code === 'SESSION_JSONL_UNREADABLE') {
+      try {
+        await writeFailureState(error.code);
+      } catch {
+        // The supervisor will report the generic startup failure when the sidecar cannot be written.
+      }
+    } else {
+      await removeOwnState();
+    }
+    exitWithFailure(1);
+  }
+
+  const stop = async () => {
+    if (stopping) return;
+    stopping = true;
+    try {
+      await daemon?.stop();
+    } finally {
+      await removeOwnState();
+    }
+  };
+
+  for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+    process.once(signal, () => {
+      void stop().finally(() => process.exit(0));
+    });
+  }
+}

package/server/lib/pi/session-daemon/ipc-client.js

@@ -0,0 +1,144 @@
+import { randomUUID } from 'node:crypto';
+import { createConnection } from 'node:net';
+import { StringDecoder } from 'node:string_decoder';
+
+const PROTOCOL_VERSION = 1;
+const MAX_FRAME_BYTES = 16 * 1024 * 1024;
+
+export class SessionDaemonClientError extends Error {
+  constructor(code, message = 'The Pi session daemon is unavailable.') {
+    super(message);
+    this.code = code;
+  }
+}
+
+/**
+ * Send one authenticated request to the private daemon. This module is server
+ * infrastructure: callers must never return its endpoint or credential.
+ */
+export const requestSessionDaemon = ({ endpoint, credential, command, payload, timeoutMs = 30_000 }) => new Promise((resolve, reject) => {
+  const requestId = randomUUID();
+  const decoder = new StringDecoder('utf8');
+  let buffer = '';
+  let authenticated = false;
+  let settled = false;
+  let timer;
+
+  const socket = createConnection({ path: endpoint });
+  const finish = (callback, value) => {
+    if (settled) return;
+    settled = true;
+    clearTimeout(timer);
+    socket.destroy();
+    callback(value);
+  };
+  const fail = (code) => finish(reject, new SessionDaemonClientError(code));
+
+  timer = setTimeout(() => fail('DAEMON_UNAVAILABLE'), timeoutMs);
+  socket.once('error', (error) => fail(error?.code === 'ECONNREFUSED' ? 'DAEMON_CONNECTION_REFUSED' : 'DAEMON_UNAVAILABLE'));
+  socket.on('connect', () => {
+    socket.write(`${JSON.stringify({ kind: 'authenticate', credential })}\n`);
+  });
+  socket.on('data', (chunk) => {
+    buffer += decoder.write(chunk);
+    if (Buffer.byteLength(buffer) > MAX_FRAME_BYTES) {
+      fail('MALFORMED_DAEMON_RESPONSE');
+      return;
+    }
+
+    while (true) {
+      const newline = buffer.indexOf('\n');
+      if (newline === -1) return;
+      const line = buffer.slice(0, newline).replace(/\r$/, '');
+      buffer = buffer.slice(newline + 1);
+      if (!line) continue;
+
+      let message;
+      try {
+        message = JSON.parse(line);
+      } catch {
+        fail('MALFORMED_DAEMON_RESPONSE');
+        return;
+      }
+      if (message.protocolVersion !== PROTOCOL_VERSION) {
+        fail('UNSUPPORTED_DAEMON_PROTOCOL');
+        return;
+      }
+      if (!authenticated) {
+        if (message.kind !== 'authenticated') {
+          fail('DAEMON_AUTH_FAILED');
+          return;
+        }
+        authenticated = true;
+        socket.write(`${JSON.stringify({ protocolVersion: PROTOCOL_VERSION, kind: 'request', requestId, command, payload })}\n`);
+        continue;
+      }
+      if (message.kind === 'response' && message.requestId === requestId) {
+        finish(resolve, message.result);
+        return;
+      }
+      if (message.kind === 'error') {
+        fail(typeof message.error?.code === 'string' ? message.error.code : 'DAEMON_REQUEST_FAILED');
+        return;
+      }
+    }
+  });
+});
+
+/**
+ * Open an authenticated server-only event subscription. The caller owns the
+ * returned close function and must relay only projected frames to browsers.
+ */
+export const subscribeSessionDaemon = ({ endpoint, credential, sessionId, fromSequence, onEvent, onError, timeoutMs = 30_000 }) => {
+  const decoder = new StringDecoder('utf8');
+  let buffer = '';
+  let authenticated = false;
+  let closed = false;
+  const socket = createConnection({ path: endpoint });
+  const timer = setTimeout(() => fail(new SessionDaemonClientError('DAEMON_UNAVAILABLE')), timeoutMs);
+  const finish = () => {
+    clearTimeout(timer);
+    if (!closed) socket.destroy();
+  };
+  const fail = (error) => {
+    if (closed) return;
+    closed = true;
+    clearTimeout(timer);
+    socket.destroy();
+    onError?.(error);
+  };
+  socket.once('error', () => fail(new SessionDaemonClientError('DAEMON_UNAVAILABLE')));
+  socket.on('connect', () => {
+    socket.write(`${JSON.stringify({ kind: 'authenticate', credential, ...(sessionId ? { sessionId } : {}), ...(Number.isSafeInteger(fromSequence) && fromSequence >= 0 ? { fromSequence } : {}) })}\n`);
+  });
+  socket.on('data', (chunk) => {
+    buffer += decoder.write(chunk);
+    if (Buffer.byteLength(buffer) > MAX_FRAME_BYTES) return fail(new SessionDaemonClientError('MALFORMED_DAEMON_RESPONSE'));
+    while (true) {
+      const newline = buffer.indexOf('\n');
+      if (newline === -1) return;
+      const line = buffer.slice(0, newline).replace(/\r$/, '');
+      buffer = buffer.slice(newline + 1);
+      if (!line) continue;
+      let message;
+      try { message = JSON.parse(line); } catch { fail(new SessionDaemonClientError('MALFORMED_DAEMON_RESPONSE')); return; }
+      if (message.protocolVersion !== PROTOCOL_VERSION) { fail(new SessionDaemonClientError('UNSUPPORTED_DAEMON_PROTOCOL')); return; }
+      if (!authenticated) {
+        if (message.kind !== 'authenticated') { fail(new SessionDaemonClientError('DAEMON_AUTH_FAILED')); return; }
+        authenticated = true;
+        clearTimeout(timer);
+        continue;
+      }
+      if (message.kind === 'event') onEvent?.(message);
+      else if (message.kind === 'error') fail(new SessionDaemonClientError(message.error?.code ?? 'DAEMON_REQUEST_FAILED'));
+    }
+  });
+  socket.on('close', () => {
+    if (!closed) fail(new SessionDaemonClientError('DAEMON_UNAVAILABLE'));
+  });
+  return () => {
+    if (closed) return;
+    closed = true;
+    finish();
+  };
+};

package/server/lib/pi/session-daemon/runtime-registry.js

@@ -0,0 +1,149 @@
+import { resolve } from 'node:path';
+
+class SessionRuntimeRegistryError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+const identityKey = ({ cwd, sessionId }) => JSON.stringify([cwd, sessionId]);
+
+const getIdentity = (runtime, session, fallbackCwd) => {
+  const cwd = typeof runtime?.cwd === 'string' && runtime.cwd.length > 0 ? runtime.cwd : fallbackCwd;
+  const sessionId = session?.sessionId;
+  if (typeof cwd !== 'string' || cwd.length === 0 || typeof sessionId !== 'string' || sessionId.length === 0) {
+    throw new SessionRuntimeRegistryError('INVALID_SESSION_RUNTIME', 'The Pi session runtime identity is invalid.');
+  }
+  return { cwd, sessionId, key: identityKey({ cwd, sessionId }) };
+};
+
+/**
+ * Owns active Pi SDK runtime identities and session-local event subscriptions.
+ * Runtime replacement is serialized by the SDK; this registry rebinds only
+ * after the SDK has installed the replacement session.
+ */
+export function createSessionRuntimeRegistry({ onSessionEvent = () => {} } = {}) {
+  const recordsByKey = new Map();
+  const recordsByRuntime = new Map();
+
+  const subscribe = (record, session) => {
+    if (typeof session?.subscribe !== 'function') {
+      throw new SessionRuntimeRegistryError('INVALID_SESSION_RUNTIME', 'The Pi session runtime cannot subscribe to session events.');
+    }
+    record.session = session;
+    record.unsubscribe = session.subscribe((event) => {
+      onSessionEvent({ cwd: record.identity.cwd, sessionId: record.identity.sessionId }, event);
+    });
+  };
+
+  const rebind = async (record, session) => {
+    const nextIdentity = getIdentity(record.runtime, session, record.identity.cwd);
+    const conflictingRecord = recordsByKey.get(nextIdentity.key);
+    if (conflictingRecord && conflictingRecord !== record) {
+      throw new SessionRuntimeRegistryError('SESSION_RUNTIME_CONFLICT', 'A Pi runtime already owns this session and directory.');
+    }
+
+    record.unsubscribe?.();
+    recordsByKey.delete(record.identity.key);
+    record.identity = nextIdentity;
+    recordsByKey.set(nextIdentity.key, record);
+    subscribe(record, session);
+  };
+
+  const register = (runtime, { cwd } = {}) => {
+    const existingRecord = recordsByRuntime.get(runtime);
+    if (existingRecord) return { ...existingRecord.identity };
+
+    const identity = getIdentity(runtime, runtime?.session, cwd);
+    const conflictingRecord = recordsByKey.get(identity.key);
+    if (conflictingRecord && conflictingRecord.runtime !== runtime) {
+      throw new SessionRuntimeRegistryError('SESSION_RUNTIME_CONFLICT', 'A Pi runtime already owns this session and directory.');
+    }
+
+    const record = { runtime, identity, session: undefined, unsubscribe: undefined };
+    recordsByKey.set(identity.key, record);
+    recordsByRuntime.set(runtime, record);
+    try {
+      subscribe(record, runtime.session);
+      if (typeof runtime.setRebindSession === 'function') {
+        runtime.setRebindSession((session) => rebind(record, session));
+      }
+    } catch (error) {
+      record.unsubscribe?.();
+      recordsByKey.delete(identity.key);
+      recordsByRuntime.delete(runtime);
+      throw error;
+    }
+    return { ...identity };
+  };
+
+  const dispose = async (runtime) => {
+    const record = recordsByRuntime.get(runtime);
+    if (!record) return false;
+
+    record.unsubscribe?.();
+    try {
+      await runtime.dispose?.();
+    } catch (error) {
+      subscribe(record, record.session);
+      throw error;
+    }
+
+    runtime.setRebindSession?.(undefined);
+    recordsByKey.delete(record.identity.key);
+    recordsByRuntime.delete(runtime);
+    return true;
+  };
+
+  const disposeAll = async () => {
+    const errors = [];
+    for (const record of [...recordsByRuntime.values()]) {
+      try {
+        await dispose(record.runtime);
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+    if (errors.length > 0) {
+      throw new AggregateError(errors, 'One or more Pi session runtimes could not be disposed.');
+    }
+  };
+
+  return {
+    get({ cwd, sessionId } = {}) {
+      if (typeof cwd !== 'string' || typeof sessionId !== 'string') return undefined;
+      return recordsByKey.get(identityKey({ cwd, sessionId }))?.runtime;
+    },
+    findBySessionId(sessionId) {
+      if (typeof sessionId !== 'string' || sessionId.length === 0) return undefined;
+      for (const record of recordsByKey.values()) {
+        if (record.identity.sessionId === sessionId) return record.runtime;
+      }
+      return undefined;
+    },
+    listByDirectory(cwd) {
+      if (typeof cwd !== 'string' || cwd.length === 0) return [];
+      const normalized = resolve(cwd);
+      const results = [];
+      for (const record of recordsByKey.values()) {
+        if (resolve(record.identity.cwd) === normalized) {
+          results.push(record.runtime);
+        }
+      }
+      return results;
+    },
+    has({ cwd, sessionId } = {}) {
+      if (typeof cwd !== 'string' || typeof sessionId !== 'string') return false;
+      return recordsByKey.has(identityKey({ cwd, sessionId }));
+    },
+    register,
+    dispose,
+    disposeAll,
+    get size() {
+      return recordsByKey.size;
+    },
+  };
+}
+
+export { SessionRuntimeRegistryError };

package/server/lib/pi/session-daemon/runtime-registry.test.js

@@ -0,0 +1,109 @@
+import { describe, expect, it } from 'vitest';
+
+import { createSessionRuntimeRegistry, SessionRuntimeRegistryError } from './runtime-registry.js';
+
+class FakeSession {
+  constructor(sessionId) {
+    this.sessionId = sessionId;
+    this.listeners = new Set();
+  }
+
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  emit(event) {
+    for (const listener of this.listeners) listener(event);
+  }
+}
+
+class FakeRuntime {
+  constructor({ cwd, sessionId }) {
+    this.cwd = cwd;
+    this.session = new FakeSession(sessionId);
+    this.rebindSession = undefined;
+    this.disposed = false;
+  }
+
+  setRebindSession(rebindSession) {
+    this.rebindSession = rebindSession;
+  }
+
+  async replace({ cwd = this.cwd, sessionId }) {
+    this.cwd = cwd;
+    this.session = new FakeSession(sessionId);
+    await this.rebindSession?.(this.session);
+  }
+
+  async dispose() {
+    this.disposed = true;
+  }
+}
+
+describe('Pi session runtime registry', () => {
+  it('keys runtime ownership by session identity and cwd, then rebinds events after replacement', async () => {
+    const events = [];
+    const registry = createSessionRuntimeRegistry({
+      onSessionEvent: (identity, event) => events.push({ identity, event }),
+    });
+    const runtime = new FakeRuntime({ cwd: '/projects/one', sessionId: 'session-one' });
+    const originalSession = runtime.session;
+
+    expect(registry.register(runtime)).toEqual({
+      cwd: '/projects/one',
+      sessionId: 'session-one',
+      key: JSON.stringify(['/projects/one', 'session-one']),
+    });
+    originalSession.emit({ type: 'agent_start' });
+
+    await runtime.replace({ cwd: '/projects/two', sessionId: 'session-two' });
+    originalSession.emit({ type: 'agent_settled' });
+    runtime.session.emit({ type: 'agent_settled' });
+
+    expect(events).toEqual([
+      { identity: { cwd: '/projects/one', sessionId: 'session-one' }, event: { type: 'agent_start' } },
+      { identity: { cwd: '/projects/two', sessionId: 'session-two' }, event: { type: 'agent_settled' } },
+    ]);
+    expect(registry.size).toBe(1);
+  });
+
+  it('does not let a session replacement displace a separately tracked runtime', async () => {
+    const registry = createSessionRuntimeRegistry();
+    const firstRuntime = new FakeRuntime({ cwd: '/projects/one', sessionId: 'session-one' });
+    const secondRuntime = new FakeRuntime({ cwd: '/projects/two', sessionId: 'session-two' });
+    registry.register(firstRuntime);
+    registry.register(secondRuntime);
+
+    await expect(secondRuntime.replace({ cwd: '/projects/one', sessionId: 'session-one' })).rejects.toMatchObject({
+      code: 'SESSION_RUNTIME_CONFLICT',
+    });
+    expect(registry.size).toBe(2);
+  });
+
+  it('keeps a failed runtime tracked while disposing unrelated runtimes', async () => {
+    const registry = createSessionRuntimeRegistry();
+    const failingRuntime = new FakeRuntime({ cwd: '/projects/one', sessionId: 'session-one' });
+    failingRuntime.dispose = async () => { throw new Error('disposal failed'); };
+    const healthyRuntime = new FakeRuntime({ cwd: '/projects/two', sessionId: 'session-two' });
+    registry.register(failingRuntime);
+    registry.register(healthyRuntime);
+
+    await expect(registry.disposeAll()).rejects.toBeInstanceOf(AggregateError);
+    expect(failingRuntime.disposed).toBe(false);
+    expect(healthyRuntime.disposed).toBe(true);
+    expect(registry.size).toBe(1);
+  });
+
+  it('rejects invalid runtime identities', () => {
+    const registry = createSessionRuntimeRegistry();
+
+    expect(() => registry.register({ session: new FakeSession('session-one') })).toThrow(SessionRuntimeRegistryError);
+    try {
+      registry.register(new FakeRuntime({ cwd: '/projects/one', sessionId: '' }));
+      throw new Error('Expected invalid runtime identity to be rejected.');
+    } catch (error) {
+      expect(error).toMatchObject({ code: 'INVALID_SESSION_RUNTIME' });
+    }
+  });
+});