@tuongaz/seeflow 0.1.102 → 0.1.104

package/src/share.ts

@@ -0,0 +1,1561 @@
+/**
+ * Live Share controller. Owns the state machine for a host-side share session:
+ * idle -> starting -> active -> stopping -> idle.
+ *
+ * This module is the local-API surface that the studio HTTP routes and toolbar
+ * UI delegate to. start() drives the relay handshake (POST /api/share/sessions)
+ * and boots a WebSocket transport; transport state events drive the controller
+ * state machine. stop() tears the session down cleanly (and aborts a mid-boot
+ * start), kick() sends a kick envelope to a peer, rotateUrl() stops + restarts
+ * so an abused share link can be invalidated.
+ *
+ * `node-patched` broadcasts include the originator — peer SPAs reconcile their
+ * optimistic state against the canonical diff; suppress reconcile-only
+ * re-renders via the rpc-result `id` correlation in US-041.
+ */
+
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { homedir, userInfo } from 'node:os';
+import { dirname, join } from 'node:path';
+import { z } from 'zod';
+import { writeFileAtomic } from './atomic-write.ts';
+import type { EventBus } from './events.ts';
+import {
+  ConnectorPatchBodySchema,
+  FLOW_BULK_NON_EMPTY_MESSAGE,
+  NodePatchBodySchema,
+  type OperationsDeps,
+  addConnectorImpl,
+  addFlowBulkImpl,
+  addNodeImpl,
+  deleteConnectorImpl,
+  deleteNodeImpl,
+  flowBulkNonEmpty,
+  moveNodeImpl,
+  patchConnectorImpl,
+  patchNodeImpl,
+  reorderNodeImpl,
+} from './operations.ts';
+import {
+  type AuditEntry,
+  type AuditLog,
+  type AuditLogOpts,
+  type AuditLogger,
+  type FrameAuditEntry,
+  type RpcAuditEntry,
+  appendShareAudit,
+  createAuditLog,
+  createAuditLogger,
+} from './share-audit.ts';
+import { type Envelope, makeEnvelope } from './share-envelope.ts';
+import {
+  type FileRequestHandler,
+  type PutToS3,
+  type RequestUploadIntent,
+  createFileRequestHandler,
+} from './share-file-request.ts';
+import {
+  type AppendFileUploadAudit,
+  type FileUploadHandler,
+  createFileUploadHandler,
+} from './share-file-upload.ts';
+import { type FilesManifestBuilder, createFilesManifestBuilder } from './share-files-manifest.ts';
+import { type RateLimiter, createRateLimiter } from './share-ratelimit.ts';
+import { RpcFrameSchema, type RpcOp, type RpcResultFrame } from './share-rpc-schema.ts';
+import {
+  type ShareTransport,
+  type ShareTransportOpts,
+  type ShareTransportState,
+  createShareTransport,
+} from './share-transport.ts';
+import type { SsePayload, SseSnapshotPayload } from './share/sse-frame.ts';
+import {
+  type PeerSseQueue,
+  type PeerSseQueueMetrics,
+  createPeerSseQueue,
+} from './share/sse-outbound-queue.ts';
+import type { RateLimitOptions } from './share/sse-rate-limit.ts';
+import { type SseTap, createSseTap } from './share/sse-tap.ts';
+
+// Presence frame payloads. We validate `kind` against the base shape, then
+// re-validate join/leave with their strict required fields so malformed
+// join/leave frames are dropped rather than treated as sideband. Cursor,
+// viewport, and any other future `kind` no-op in v1 per the design doc.
+const PresenceBaseSchema = z.object({ kind: z.string() }).passthrough();
+const PresenceJoinSchema = z.object({
+  kind: z.literal('join'),
+  peerId: z.string(),
+  displayName: z.string(),
+});
+const PresenceLeaveSchema = z.object({ kind: z.literal('leave'), peerId: z.string() });
+
+export interface PeerSummary {
+  peerId: string;
+  displayName: string;
+  joinedAt: number;
+  /**
+   * Per-peer SSE outbound queue metrics surfaced for the LiveShareDialog's
+   * "slow peer" warning (US-072). Absent when the peer has no SSE queue
+   * (e.g. before the bridge has wired up, or when the session was started
+   * without an `eventBus`).
+   */
+  outboundSse?: PeerSseQueueMetrics;
+}
+
+export type ShareState =
+  | { status: 'idle' }
+  | { status: 'starting' }
+  | {
+      status: 'active';
+      sessionId: string;
+      token: string;
+      url: string;
+      peers: PeerSummary[];
+      startedAt: number;
+      // Display label used as `attributedTo.displayName` for host-originated
+      // node-patched broadcasts. Derived from `ShareDeps.hostDisplayName`
+      // (defaults to 'Host') and exposed on state so the SSE bridge and local
+      // studio UI can render the host's own suppressed self-attribution.
+      hostDisplayName: string;
+      // US-082: count of sessions currently tracked in active.json. Surfaced
+      // on state so the apps/web LiveShareDialog can disable the kill-switch
+      // button (and render "Active sessions: N") without a side-channel fetch.
+      recentSessionCount: number;
+    }
+  | { status: 'stopping' }
+  | { status: 'error'; reason: string };
+
+export interface ShareController {
+  start(): Promise<{ url: string; sessionId: string }>;
+  stop(): Promise<void>;
+  kick(peerId: string): Promise<void>;
+  rotateUrl(): Promise<{ url: string }>;
+  /**
+   * Host kill-switch (US-081). Revokes every session this studio has ever
+   * opened — not just the currently active one. Tracked sessions live in
+   * `<auditDir>/active.json`; killAll POSTs `/api/share/end` to the relay
+   * for each entry, appends a `kill-switch` audit entry to each affected
+   * session's JSONL log, then truncates `active.json`. Returns counts so
+   * the UI toast can show "Ended N live sessions".
+   */
+  killAll(): Promise<{ revoked: number; failed: number }>;
+  state(): ShareState;
+  subscribe(fn: (s: ShareState) => void): () => void;
+  /**
+   * Dispatch an inbound `rpc` envelope as if it came from `fromPeerId`. Tests
+   * call this directly without driving the transport. When the originator is
+   * a known peer (registered via presence/join), pass `displayName` so the
+   * outgoing `node-patched` broadcast's `attributedTo` field carries the
+   * human-readable label; if omitted, `fromPeerId` is used as the fallback.
+   */
+  handleRpcFrame(frame: unknown, fromPeerId: string, displayName?: string): Promise<RpcResultFrame>;
+  /**
+   * Broadcast a `node-patched` frame for an edit applied by the host's own UI
+   * (no peer rpc). `attributedTo.peerId` is the literal `'host'` and
+   * `displayName` is the active state's `hostDisplayName`. No-ops when the
+   * controller is not active or the outcome was not `kind: 'ok'`. Returns the
+   * monotonic per-flow version assigned (or `null` when no broadcast fired).
+   */
+  broadcastHostEdit(op: RpcOp, outcome: RpcDispatchOutcome): number | null;
+  /**
+   * Subscribe to attribution events fired for every accepted op the host
+   * broadcasts (peer-originated AND host-originated). Used by the host
+   * studio's apps/web UI to render attribution toasts (US-053); the SSE
+   * bridge in `apps/studio/src/api.ts` fans these out to /api/share/attributions.
+   */
+  subscribeAttributions(fn: (event: AttributionEvent) => void): () => void;
+  /**
+   * Read access to the per-session `AuditEntry` JSONL stream (US-079). The
+   * /api/share/audit endpoint delegates to this; when no session is active
+   * `list()` returns an empty page so the endpoint can still answer 200
+   * (the endpoint itself gates on state before calling).
+   */
+  audit: {
+    list(opts?: {
+      limit?: number;
+      cursor?: number;
+    }): Promise<{ entries: AuditEntry[]; nextCursor: number | null }>;
+  };
+}
+
+export interface AttributionEvent {
+  flowId: string;
+  op: string;
+  diff: unknown;
+  version: number;
+  attributedTo: { peerId: string; displayName: string };
+  ts: number;
+}
+
+// Generic outcome shape returned by a dispatcher entry. Each operations.ts
+// impl already conforms (`{ kind: 'ok'; data?: ... } | { kind: ...; message?: ... }`),
+// so the default dispatcher passes them through. Tests inject custom
+// dispatchers that return whatever they want for the per-op happy paths.
+export interface RpcDispatchOutcome {
+  kind: string;
+  data?: unknown;
+  message?: string;
+}
+
+export type RpcDispatcher = (op: RpcOp) => Promise<RpcDispatchOutcome>;
+
+// Op allowlist — duplicated from `RpcOpSchema`'s discriminator literals as a
+// runtime defense-in-depth. The Zod schema rejects unknown ops up front; this
+// secondary gate catches a tampered runtime injection (e.g. a future code path
+// that skips the schema parse) before it reaches the impl.
+const ALLOWED_RPC_OPS = new Set<RpcOp['op']>([
+  'addNode',
+  'patchNode',
+  'moveNode',
+  'reorderNode',
+  'deleteNode',
+  'addConnector',
+  'patchConnector',
+  'deleteConnector',
+  'addBulk',
+]);
+
+export function createDefaultRpcDispatcher(deps: OperationsDeps): RpcDispatcher {
+  return async (op) => {
+    switch (op.op) {
+      case 'addNode':
+        return addNodeImpl(deps, op.flowId, op.node);
+      case 'patchNode': {
+        const parsed = NodePatchBodySchema.safeParse(op.patch);
+        if (!parsed.success) return { kind: 'badSchema', message: parsed.error.message };
+        return patchNodeImpl(deps, op.flowId, op.nodeId, parsed.data);
+      }
+      case 'moveNode':
+        return moveNodeImpl(deps, op.flowId, op.nodeId, op.position);
+      case 'reorderNode':
+        return reorderNodeImpl(deps, op.flowId, op.nodeId, op.reorder);
+      case 'deleteNode':
+        return deleteNodeImpl(deps, op.flowId, op.nodeId);
+      case 'addConnector':
+        return addConnectorImpl(deps, op.flowId, op.connector);
+      case 'patchConnector': {
+        const parsed = ConnectorPatchBodySchema.safeParse(op.patch);
+        if (!parsed.success) return { kind: 'badSchema', message: parsed.error.message };
+        return patchConnectorImpl(deps, op.flowId, op.connectorId, parsed.data);
+      }
+      case 'deleteConnector':
+        return deleteConnectorImpl(deps, op.flowId, op.connectorId);
+      case 'addBulk': {
+        const body = { nodes: op.nodes, connectors: op.connectors };
+        // The non-empty refine couldn't be expressed in the wire schema (a
+        // ZodEffects member can't participate in a discriminatedUnion). It's
+        // enforced here before dispatch so the wire stays loose.
+        if (!flowBulkNonEmpty(body)) {
+          return { kind: 'invalid', message: FLOW_BULK_NON_EMPTY_MESSAGE };
+        }
+        return addFlowBulkImpl(deps, op.flowId, body);
+      }
+    }
+  };
+}
+
+export interface ShareDeps {
+  relayHttpUrl: string;
+  shareUrlBase: string;
+  fetch?: typeof fetch;
+  transportFactory?: (opts: ShareTransportOpts) => ShareTransport;
+  // Rate-limiter is shared across the controller's lifetime so per-peer
+  // buckets survive across kick/rejoin within a single session. Defaults to
+  // 30 ops/sec / burst 30 per the design doc.
+  rateLimiter?: RateLimiter;
+  // Audit log lives one-per-session: created on transition to active, closed
+  // by stop(). Path defaults to ~/.seeflow/share-history.
+  auditDir?: string;
+  /**
+   * Path to the active-sessions tracking file (US-081 kill-switch). Defaults
+   * to `<auditDir>/active.json`. The host appends `{sessionId, hostKey}` on
+   * each start() and removes it on stop(); `killAll()` reads the file,
+   * revokes every entry via POST /api/share/end, then truncates.
+   */
+  activeSessionsPath?: string;
+  auditLogFactory?: (opts: AuditLogOpts) => AuditLog;
+  // Phase-8 audit logger (US-078 shape: AuditEntry with kind). Created on
+  // idle -> active alongside the legacy per-frame `auditLog`. Tests inject a
+  // capturing factory; production callers leave it undefined and the real
+  // `createAuditLogger` writes to `auditDir`.
+  auditLoggerFactory?: (sessionId: string, root?: string) => AuditLogger;
+  // Local EventBus to bridge onto outbound 'sse' envelopes so peers see live
+  // runtime events (node:running, node:done, etc.) the same way the studio's
+  // own SSE listeners do. On transition idle -> active we subscribe to each
+  // flowId returned by flowIdsForBroadcast() and forward every StudioEvent as
+  // makeEnvelope('sse', event, { to: 'all', from: 'host' }). Subscriptions are
+  // torn down on teardown(). If either dep is absent the bridge is a no-op.
+  eventBus?: EventBus;
+  flowIdsForBroadcast?: () => string[];
+  // OperationsDeps used by the default RPC dispatcher. Required when
+  // `rpcDispatcher` is omitted; tests inject `rpcDispatcher` directly and can
+  // skip this.
+  operationsDeps?: OperationsDeps;
+  // Per-op dispatcher invoked by `handleRpcFrame` after envelope validation.
+  // Defaults to `createDefaultRpcDispatcher(operationsDeps)`. Tests inject
+  // stubs to assert dispatch contract without touching the real impls.
+  rpcDispatcher?: RpcDispatcher;
+  // Injected for tests so they can capture audit writes without hitting disk.
+  // Defaults to the real `appendShareAudit` writing to `auditDir`.
+  appendShareAuditFn?: (sessionId: string, entry: RpcAuditEntry) => void;
+  // Outbound broadcast seam. Defaults to forwarding the envelope through the
+  // active transport when open. Tests inject a spy to assert the
+  // node-patched fan-out without standing up a relay.
+  broadcast?: (envelope: Envelope) => void;
+  // Display label used as `attributedTo.displayName` for host-originated
+  // node-patched broadcasts (and surfaced on `state().hostDisplayName` while
+  // active). Defaults to `'Host'`. US-054 supplies the real OS username.
+  hostDisplayName?: string;
+  // Optional S3 staging deps for the oversize file-request path (US-060).
+  // Both must be present to enable >256 KB file serving; otherwise the
+  // handler replies `too-large` for big files. Tests can wire stubs.
+  requestUploadIntent?: RequestUploadIntent;
+  putToS3?: PutToS3;
+  // Test seam: swap the entire file-request handler. Production callers
+  // leave this undefined and the controller builds one from registry +
+  // broadcast + the S3 deps above.
+  fileRequestHandler?: FileRequestHandler;
+  // Test seam: swap the entire file-upload handler. Production callers leave
+  // this undefined and the controller builds one from registry + broadcast +
+  // the active session id.
+  fileUploadHandler?: FileUploadHandler;
+  // Injected for tests so they can capture the upload audit entry without
+  // hitting disk. Defaults to `appendShareAudit` writing to `auditDir`.
+  appendFileUploadAuditFn?: AppendFileUploadAudit;
+  // Test seam: swap the entire files-manifest builder (US-062). Production
+  // callers leave this undefined and the controller builds one from
+  // `operationsDeps.registry`. Without a registry the manifest is empty.
+  filesManifestBuilder?: FilesManifestBuilder;
+  /**
+   * Per-peer outbound SSE send seam (US-072). Awaited per-frame inside the
+   * per-peer queue so a slow consumer creates backpressure HERE rather than
+   * in the producer. Defaults to a sync wrapper around `broadcast` that
+   * sends an `sse` envelope addressed to the peer's connId. Tests inject a
+   * delayed stub to exercise queue overflow + drop policy without standing
+   * up a transport.
+   */
+  outboundSseSend?: (payload: SsePayload, peerConnId: string) => Promise<void> | void;
+  /** Max in-queue frames per peer before eviction kicks in. Defaults to 256. */
+  outboundSseMaxFrames?: number;
+  /** Lifetime drops within this rolling window trigger a resync. Default 60000. */
+  outboundSseDropResyncWindowMs?: number;
+  /** Default 100. */
+  outboundSseDropResyncThreshold?: number;
+  /**
+   * Tap-level rate-limit override (US-068). Passed through to `createSseTap`
+   * as its `rateLimit` option. Defaults to the tap's own defaults (60/sec,
+   * burst 120). Pass `false` to disable when testing per-peer backpressure
+   * (US-072) so frames reach the queues without the tap's coalescer
+   * absorbing the storm first.
+   */
+  sseTapRateLimit?: false | Omit<RateLimitOptions, 'onEmit'>;
+}
+
+interface RelaySessionResponse {
+  sessionId: string;
+  token: string;
+  hostKey: string;
+  wsUrl: string;
+}
+
+interface BootHandle {
+  settled: boolean;
+  cancelTimer: () => void;
+  rejectStart: (err: Error) => void;
+}
+
+const BOOT_TIMEOUT_MS = 10_000;
+
+// Per-frame snapshot payload size cap. The host splits the snapshot into
+// per-flow chunks so no single `sse-snapshot` frame's serialized JSON exceeds
+// this size. A flow whose own snapshot is larger than the cap is still
+// emitted as one chunk — per-flow is the indivisible unit per the PRD.
+export const SSE_SNAPSHOT_CHUNK_BYTES = 256 * 1024;
+
+/**
+ * Split a per-flow snapshot map into chunks so each chunk's serialized JSON
+ * fits within `SSE_SNAPSHOT_CHUNK_BYTES`. Returns at least one chunk even
+ * when the input is empty (callers gate on that separately). Always preserves
+ * full flows — a single flow that overflows the cap occupies its own chunk
+ * regardless of size.
+ */
+export function chunkSnapshotByFlow<T>(
+  snap: Record<string, Record<string, T>>,
+): Record<string, Record<string, T>>[] {
+  const entries = Object.entries(snap);
+  if (entries.length === 0) return [];
+
+  const chunks: Record<string, Record<string, T>>[] = [];
+  let current: Record<string, Record<string, T>> = {};
+
+  for (const [flowId, nodes] of entries) {
+    const candidate: Record<string, Record<string, T>> = { ...current, [flowId]: nodes };
+    const candidateSize = JSON.stringify({ flows: candidate }).length;
+    const isCurrentEmpty = Object.keys(current).length === 0;
+    if (!isCurrentEmpty && candidateSize > SSE_SNAPSHOT_CHUNK_BYTES) {
+      chunks.push(current);
+      current = { [flowId]: nodes };
+      continue;
+    }
+    current = candidate;
+  }
+  if (Object.keys(current).length > 0) chunks.push(current);
+  return chunks;
+}
+
+/**
+ * Resolve the host's display label for `attributedTo.displayName` on
+ * host-originated `node-patched` broadcasts (US-054). Tries the running OS
+ * user's `username` first; falls back to literal `'Host'` if the syscall
+ * throws (sandboxed envs) or returns a blank value. Trimmed so a username
+ * with whitespace doesn't propagate through to UI.
+ */
+export function resolveHostDisplayName(): string {
+  try {
+    const name = userInfo().username;
+    if (typeof name === 'string') {
+      const trimmed = name.trim();
+      if (trimmed.length > 0) return trimmed;
+    }
+  } catch {
+    // userInfo() throws on some sandboxed runtimes (e.g. Bun in a sealed
+    // container with no /etc/passwd). Fall through to the literal default.
+  }
+  return 'Host';
+}
+
+// Fallback frame id surfaced when the inbound envelope failed validation
+// hard enough that we can't recover `frame.id`. Anything is fine as long as
+// it satisfies the wire schema's `min(1)` constraint on the `id` field.
+const INVALID_FRAME_ID = 'invalid';
+
+const extractFrameId = (frame: unknown): string => {
+  if (frame && typeof frame === 'object' && 'id' in frame) {
+    const raw = (frame as { id?: unknown }).id;
+    if (typeof raw === 'string' && raw.length > 0) return raw;
+  }
+  return INVALID_FRAME_ID;
+};
+
+const makeRpcResultFrame = (id: string, payload: RpcResultFrame['payload']): RpcResultFrame => ({
+  v: 1,
+  type: 'rpc-result',
+  id,
+  payload,
+});
+
+// Build the diff payload broadcast as `node-patched` after a successful op.
+// Each branch follows the contract documented on US-039:
+//   moveNode      -> { kind: 'move', nodeId, position }
+//   patchNode     -> { kind: 'patch', nodeId, patch }
+//   addNode       -> { kind: 'add', node }         (full new node from outcome)
+//   deleteNode    -> { kind: 'delete', nodeId }
+//   reorderNode   -> { kind: 'reorder', nodeId, op }
+// Connector variants mirror the same kinds with `connectorId` instead of
+// `nodeId`. `addBulk` reports `{ kind: 'bulk', result }` so peers can decide
+// whether to refetch or apply incrementally.
+function computeNodePatchedDiff(op: RpcOp, outcome: RpcDispatchOutcome): unknown {
+  switch (op.op) {
+    case 'moveNode':
+      return { kind: 'move', nodeId: op.nodeId, position: op.position };
+    case 'patchNode':
+      return { kind: 'patch', nodeId: op.nodeId, patch: op.patch };
+    case 'addNode': {
+      const data = outcome.data as { node?: unknown } | undefined;
+      return { kind: 'add', node: data?.node };
+    }
+    case 'deleteNode':
+      return { kind: 'delete', nodeId: op.nodeId };
+    case 'reorderNode':
+      return { kind: 'reorder', nodeId: op.nodeId, op: op.reorder };
+    case 'addConnector': {
+      const data = outcome.data as { id?: string } | undefined;
+      const connector =
+        data?.id !== undefined ? { ...op.connector, id: data.id } : { ...op.connector };
+      return { kind: 'add', connector };
+    }
+    case 'patchConnector':
+      return { kind: 'patch', connectorId: op.connectorId, patch: op.patch };
+    case 'deleteConnector':
+      return { kind: 'delete', connectorId: op.connectorId };
+    case 'addBulk':
+      return { kind: 'bulk', result: outcome.data };
+  }
+}
+
+export function createShareController(deps: ShareDeps): ShareController {
+  // current is mutated through setState() so subscribers fan-out on every
+  // transition. hostKey + transport live in closure scope — hostKey is never
+  // returned by state() or logged. bootHandle is non-null only while start()
+  // is in flight; stop() consults it to abort a mid-boot start.
+  let current: ShareState = { status: 'idle' };
+  const subscribers = new Set<(s: ShareState) => void>();
+  const attributionSubscribers = new Set<(event: AttributionEvent) => void>();
+  const fetchFn = deps.fetch ?? fetch;
+  const transportFactory = deps.transportFactory ?? createShareTransport;
+  const rateLimiter = deps.rateLimiter ?? createRateLimiter({ ratePerSec: 30, burst: 30 });
+  const auditDir = deps.auditDir ?? join(homedir(), '.seeflow', 'share-history');
+  const activeSessionsPath = deps.activeSessionsPath ?? join(auditDir, 'active.json');
+  const auditLogFactory = deps.auditLogFactory ?? createAuditLog;
+  const auditLoggerFactory = deps.auditLoggerFactory ?? createAuditLogger;
+  const hostDisplayName = deps.hostDisplayName ?? resolveHostDisplayName();
+  const rpcDispatcher: RpcDispatcher | null =
+    deps.rpcDispatcher ??
+    (deps.operationsDeps ? createDefaultRpcDispatcher(deps.operationsDeps) : null);
+  const appendShareAuditFn =
+    deps.appendShareAuditFn ??
+    ((sessionId, entry) => appendShareAudit(sessionId, entry, { dir: auditDir }));
+  // Per-flow monotonic counter bumped just before every accepted node-patched
+  // broadcast. Peers use this only for tie-breaking out-of-order frames in a
+  // future story; for now we only assert monotonic-increasing in tests.
+  const flowVersions = new Map<string, number>();
+
+  let hostKey: string | null = null;
+  let transport: ShareTransport | null = null;
+  let bootHandle: BootHandle | null = null;
+  let auditLog: AuditLog | null = null;
+  let auditLogger: AuditLogger | null = null;
+  // SSE tap (US-066/US-067): single per-controller instance owning the
+  // EventBus -> outbound `sse` envelope bridge. Created on idle -> active,
+  // torn down on stop()/teardown(). Null when inactive or when no eventBus
+  // dep was provided.
+  let sseTap: SseTap | null = null;
+  // Unsubscribe handle for the `__registry__` listener that drives
+  // `sseTap.refreshFlows()` on registry:reload events. Captured at active
+  // time so teardown can drop the subscription cleanly.
+  let registryUnsubscribe: (() => void) | null = null;
+  // peerId -> connId. Populated by presence/join frames; consulted by kick()
+  // so a host can address a peer by stable peerId while the relay routes on
+  // the per-connection connId. Cleared on teardown.
+  const peerConnIds = new Map<string, string>();
+  // connId -> peer info. Inverse of peerConnIds, kept in lockstep. Used by
+  // handleFrame to resolve env.from -> peerId before rate-limiting/auditing.
+  const connPeers = new Map<string, { peerId: string; displayName: string }>();
+  // Per-peer outbound SSE queues (US-072), keyed by connId. Created on
+  // presence/join, disposed on presence/leave + teardown. Absent before the
+  // first peer joins; the SSE bridge falls back to a `to: 'all'` broadcast
+  // when this map is empty so the relay's own fan-out still reaches
+  // unattributed peers (and so the legacy 0-peer tests keep passing).
+  const peerSseQueues = new Map<string, PeerSseQueue>();
+  const outboundSseMaxFrames = deps.outboundSseMaxFrames;
+  const outboundSseDropResyncThreshold = deps.outboundSseDropResyncThreshold;
+  const outboundSseDropResyncWindowMs = deps.outboundSseDropResyncWindowMs;
+
+  const broadcast =
+    deps.broadcast ??
+    ((envelope: Envelope) => {
+      if (!transport || !transport.isOpen()) return;
+      try {
+        transport.send(envelope);
+      } catch (err) {
+        console.warn('[share] broadcast send failed:', err);
+      }
+    });
+
+  // Default per-peer SSE send: emit an addressed `sse` envelope through the
+  // broadcast seam. Tests override with a stub that returns a delayed Promise
+  // to exercise queue backpressure without touching the transport.
+  const outboundSseSend: (payload: SsePayload, peerConnId: string) => Promise<void> | void =
+    deps.outboundSseSend ??
+    ((payload, peerConnId) => {
+      broadcast(makeEnvelope('sse', payload, { to: peerConnId, from: 'host' }));
+    });
+
+  // File-request handler (US-060). Instantiated lazily so test deps that pass
+  // an explicit `fileRequestHandler` win; otherwise we build one from the
+  // registry on `operationsDeps`. Without a registry there is no resolver
+  // surface and file-request envelopes are dropped with a warn.
+  const fileRequestHandler: FileRequestHandler | null =
+    deps.fileRequestHandler ??
+    (deps.operationsDeps
+      ? createFileRequestHandler({
+          registry: deps.operationsDeps.registry,
+          broadcast: (env) => broadcast(env),
+          requestUploadIntent: deps.requestUploadIntent,
+          putToS3: deps.putToS3,
+        })
+      : null);
+
+  // File-upload handler (US-061). Mirrors the file-request lazy-instantiation
+  // contract: tests supply an explicit `fileUploadHandler` to short-circuit;
+  // production callers thread `operationsDeps.registry`. Without a registry
+  // upload frames are dropped with a warn.
+  const appendFileUploadAuditFn: AppendFileUploadAudit =
+    deps.appendFileUploadAuditFn ??
+    ((sessionId, entry) => appendShareAudit(sessionId, entry, { dir: auditDir }));
+  const fileUploadHandler: FileUploadHandler | null =
+    deps.fileUploadHandler ??
+    (deps.operationsDeps
+      ? createFileUploadHandler({
+          registry: deps.operationsDeps.registry,
+          broadcast: (env) => broadcast(env),
+          getSessionId: () => (current.status === 'active' ? current.sessionId : null),
+          appendAudit: appendFileUploadAuditFn,
+        })
+      : null);
+
+  // Files-manifest builder (US-062). Lazy-instantiated from the registry, with
+  // the same test-seam pattern as file-request / file-upload handlers. The
+  // controller drives `init()` on transition idle -> active and emits one
+  // `files-manifest` frame per accepted presence/join.
+  const filesManifestBuilder: FilesManifestBuilder | null =
+    deps.filesManifestBuilder ??
+    (deps.operationsDeps
+      ? createFilesManifestBuilder({ registry: deps.operationsDeps.registry })
+      : null);
+  // Resolves when `filesManifestBuilder.init()` has finished for the current
+  // session. Set on idle -> active; cleared on teardown. A presence/join that
+  // races with init awaits this before broadcasting.
+  let filesManifestReady: Promise<void> | null = null;
+
+  // Enrich an active ShareState with current per-peer outbound SSE metrics
+  // (US-072) and the live tracked-session count (US-082). Idempotent —
+  // re-reading state() at any time picks up the latest queue depths/drops AND
+  // the latest `active.json` count without requiring a setState transition.
+  const enrichWithSseMetrics = (s: ShareState): ShareState => {
+    if (s.status !== 'active') return s;
+    const enrichedPeers = s.peers.map((p) => {
+      const connId = peerConnIds.get(p.peerId);
+      const queue = connId ? peerSseQueues.get(connId) : undefined;
+      if (!queue) return p;
+      return { ...p, outboundSse: queue.metrics() };
+    });
+    return {
+      ...s,
+      peers: enrichedPeers,
+      recentSessionCount: readTrackedSessions().length,
+    };
+  };
+
+  const setState = (next: ShareState) => {
+    current = next;
+    const enriched = enrichWithSseMetrics(next);
+    for (const fn of subscribers) {
+      try {
+        fn(enriched);
+      } catch (err) {
+        console.error('[share] subscriber threw on transition:', err);
+      }
+    }
+  };
+
+  const subscribeToEventBus = () => {
+    if (!deps.eventBus || !deps.flowIdsForBroadcast) return;
+    const flowIdsForBroadcast = deps.flowIdsForBroadcast;
+    // Build the SSE tap with a fresh per-session monotonic seq counter (owned
+    // by createSseTap). onEvent forwards the validated SsePayload as the
+    // `payload` of an outbound `sse` envelope; the buffer + snapshot are
+    // private to the tap and used by US-069 / US-070 for join replay.
+    const tap = createSseTap(deps.eventBus, {
+      flowIds: () => flowIdsForBroadcast(),
+      ...(deps.sseTapRateLimit !== undefined ? { rateLimit: deps.sseTapRateLimit } : {}),
+      onEvent: (payload) => {
+        // With at least one connected peer, fan out per-peer through bounded
+        // queues so a slow consumer can't stall the host event loop (US-072).
+        // With zero known peers, fall back to the legacy `to: 'all'` broadcast
+        // so the relay still fans out to any peer the host hasn't seen
+        // presence/join for yet (e.g. first frame after auth-peer races with
+        // the bridge).
+        if (peerSseQueues.size === 0) {
+          try {
+            broadcast(makeEnvelope('sse', payload, { to: 'all', from: 'host' }));
+          } catch (err) {
+            console.warn('[share] sse fan-out broadcast failed:', err);
+          }
+          return;
+        }
+        for (const queue of peerSseQueues.values()) {
+          try {
+            queue.enqueue(payload);
+          } catch (err) {
+            console.warn('[share] sse enqueue failed:', err);
+          }
+        }
+      },
+    });
+    sseTap = tap;
+    tap.start();
+    // Watch the registry channel so adds/removes flow through to the tap's
+    // subscription set without restarting the share session. Listens on the
+    // sentinel flowId used by `apps/studio/src/api.ts` registry mutators.
+    registryUnsubscribe = deps.eventBus.subscribe('__registry__', (event) => {
+      if (event.type !== 'registry:reload') return;
+      try {
+        tap.refreshFlows();
+      } catch (err) {
+        console.warn('[share] sse tap refreshFlows failed:', err);
+      }
+    });
+  };
+
+  const unsubscribeFromEventBus = () => {
+    const off = registryUnsubscribe;
+    registryUnsubscribe = null;
+    if (off) {
+      try {
+        off();
+      } catch (err) {
+        console.warn('[share] registry unsubscribe failed:', err);
+      }
+    }
+    const tap = sseTap;
+    sseTap = null;
+    if (tap) {
+      try {
+        tap.stop();
+      } catch (err) {
+        console.warn('[share] sse tap stop failed:', err);
+      }
+    }
+  };
+
+  // Build a per-peer SSE outbound queue (US-072). On threshold drops the queue
+  // fires our onResyncTriggered, which we use to emit a one-shot `sse-snapshot`
+  // addressed to the peer so its canvas catches back up after the host stops
+  // sending live frames (or, more typically, after the peer's network gets
+  // back enough headroom to drain).
+  const buildPeerSseQueue = (peerConnId: string): PeerSseQueue =>
+    createPeerSseQueue({
+      peerConnId,
+      send: outboundSseSend,
+      maxFrames: outboundSseMaxFrames,
+      dropResyncThreshold: outboundSseDropResyncThreshold,
+      dropResyncWindowMs: outboundSseDropResyncWindowMs,
+      onResyncTriggered: () => {
+        try {
+          emitSseSnapshotForPeer(peerConnId);
+        } catch (err) {
+          console.warn('[share] sse resync emit failed:', err);
+        }
+      },
+    });
+
+  const disposePeerSseQueue = (peerConnId: string): void => {
+    const q = peerSseQueues.get(peerConnId);
+    if (!q) return;
+    peerSseQueues.delete(peerConnId);
+    try {
+      q.dispose();
+    } catch (err) {
+      console.warn('[share] sse queue dispose failed:', err);
+    }
+  };
+
+  const teardown = () => {
+    const t = transport;
+    const log = auditLog;
+    const klogger = auditLogger;
+    transport = null;
+    hostKey = null;
+    auditLog = null;
+    auditLogger = null;
+    filesManifestReady = null;
+    unsubscribeFromEventBus();
+    for (const q of peerSseQueues.values()) {
+      try {
+        q.dispose();
+      } catch (err) {
+        console.warn('[share] sse queue dispose failed:', err);
+      }
+    }
+    peerSseQueues.clear();
+    peerConnIds.clear();
+    connPeers.clear();
+    if (t) {
+      try {
+        t.close('user');
+      } catch (err) {
+        console.warn('[share] close failed during teardown:', err);
+      }
+    }
+    if (log) {
+      log.close().catch((err) => {
+        console.warn('[share] audit log close failed:', err);
+      });
+    }
+    if (klogger) {
+      klogger.close().catch((err) => {
+        console.warn('[share] audit kind log close failed:', err);
+      });
+    }
+  };
+
+  const audit = (entry: FrameAuditEntry) => {
+    if (!auditLog) return;
+    try {
+      auditLog.append(entry);
+    } catch (err) {
+      console.warn('[share] audit append failed:', err);
+    }
+  };
+
+  // Fire-and-forget append of a Phase-8 `AuditEntry` to the per-session JSONL
+  // log. Errors only warn — auditing is best-effort; never block hot paths
+  // (RPC dispatch, kick, rotate) on disk I/O.
+  const auditKind = (entry: Omit<AuditEntry, 'ts'>): void => {
+    const logger = auditLogger;
+    if (!logger) return;
+    logger.append(entry).catch((err) => {
+      console.warn('[share] audit kind append failed:', err);
+    });
+  };
+
+  // Build + emit a `node-patched` envelope for an accepted op. Centralized so
+  // peer-rpc and host-local edits assemble the wire payload identically (only
+  // the `attributedTo` value differs). Returns the version assigned so callers
+  // can echo it back into rpc-result if needed.
+  const broadcastNodePatched = (
+    op: RpcOp,
+    outcome: RpcDispatchOutcome,
+    attributedTo: { peerId: string; displayName: string },
+  ): number => {
+    const nextVersion = (flowVersions.get(op.flowId) ?? 0) + 1;
+    flowVersions.set(op.flowId, nextVersion);
+    const diff = computeNodePatchedDiff(op, outcome);
+    try {
+      broadcast(
+        makeEnvelope(
+          'node-patched',
+          { flowId: op.flowId, op: op.op, diff, version: nextVersion, attributedTo },
+          { to: 'all' },
+        ),
+      );
+    } catch (err) {
+      console.warn('[share] node-patched broadcast failed:', err);
+    }
+    const event: AttributionEvent = {
+      flowId: op.flowId,
+      op: op.op,
+      diff,
+      version: nextVersion,
+      attributedTo,
+      ts: Date.now(),
+    };
+    for (const fn of attributionSubscribers) {
+      try {
+        fn(event);
+      } catch (err) {
+        console.error('[share] attribution subscriber threw:', err);
+      }
+    }
+    return nextVersion;
+  };
+
+  const dispatchRpcFrame = async (
+    frame: unknown,
+    actor: { peerId: string; displayName: string },
+  ): Promise<RpcResultFrame> => {
+    const fallbackId = extractFrameId(frame);
+    const parsed = RpcFrameSchema.safeParse(frame);
+    if (!parsed.success) {
+      // Never include payload in the log: a tampered envelope is hostile by
+      // assumption.
+      console.warn('[share] rpc frame rejected:', {
+        type: 'rpc',
+        from: actor.peerId,
+        reason: 'invalid_envelope',
+      });
+      return makeRpcResultFrame(fallbackId, { ok: false, reason: 'invalid_envelope' });
+    }
+    const op = parsed.data.payload;
+    if (!ALLOWED_RPC_OPS.has(op.op)) {
+      // Defense-in-depth: unreachable past the schema, but guards a future
+      // path that bypasses validation.
+      console.warn('[share] rpc frame rejected:', {
+        type: 'rpc',
+        from: actor.peerId,
+        reason: 'op_not_allowed',
+      });
+      return makeRpcResultFrame(parsed.data.id, { ok: false, reason: 'op_not_allowed' });
+    }
+    if (current.status !== 'active') {
+      return makeRpcResultFrame(parsed.data.id, { ok: false, reason: 'not_active' });
+    }
+    if (!rpcDispatcher) {
+      return makeRpcResultFrame(parsed.data.id, { ok: false, reason: 'no_dispatcher' });
+    }
+    const sessionId = current.sessionId;
+    let outcome: RpcDispatchOutcome;
+    try {
+      outcome = await rpcDispatcher(op);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      outcome = { kind: 'dispatcherThrew', message };
+    }
+    const ok = outcome.kind === 'ok';
+    const reason = ok ? undefined : outcome.kind + (outcome.message ? `: ${outcome.message}` : '');
+    const attributedTo = { peerId: actor.peerId, displayName: actor.displayName };
+    try {
+      const entry: RpcAuditEntry = {
+        ts: Date.now(),
+        peerId: actor.peerId,
+        op: op.op,
+        flowId: op.flowId,
+        ok,
+        ...(reason ? { reason } : {}),
+        attributedTo,
+      };
+      appendShareAuditFn(sessionId, entry);
+    } catch (err) {
+      console.warn('[share] rpc audit append failed:', err);
+    }
+    if (ok) {
+      // Phase-8 kind-shaped audit (US-079). Coexists with the RpcAuditEntry
+      // line written above so consumers can filter by either schema.
+      // `details` carries flowId + (for node-targeted ops) the nodeId so the
+      // audit drawer can render the target without re-reading the op union.
+      const rpcDetails: Record<string, unknown> = { flowId: op.flowId };
+      if ('nodeId' in op && typeof op.nodeId === 'string') {
+        rpcDetails.nodeId = op.nodeId;
+      }
+      auditKind({
+        kind: 'rpc-accept',
+        peerId: actor.peerId,
+        displayName: actor.displayName,
+        op: op.op,
+        details: rpcDetails,
+      });
+      // Broadcast the canonical diff BEFORE resolving rpc-result so peers
+      // (including the originator) see the patch first; the originator's
+      // optimistic reconcile then folds into a no-op.
+      broadcastNodePatched(op, outcome, attributedTo);
+      return makeRpcResultFrame(parsed.data.id, {
+        ok: true,
+        ...(outcome.data !== undefined ? { result: outcome.data } : {}),
+        attributedTo,
+      });
+    }
+    auditKind({
+      kind: 'rpc-reject',
+      peerId: actor.peerId,
+      displayName: actor.displayName,
+      op: op.op,
+      reason: reason ?? outcome.kind,
+    });
+    return makeRpcResultFrame(parsed.data.id, {
+      ok: false,
+      reason: reason ?? outcome.kind,
+    });
+  };
+
+  // Emit one or more `sse-snapshot` frames to a freshly-joined peer so its
+  // canvas badges / play-button rings match the host's live state without
+  // waiting for the next tick. Caps each frame's serialized payload at 256 KB
+  // by splitting per-flow into chunks (chunk + total stamped on each frame).
+  // A single flow whose own snapshot exceeds the cap is still emitted as one
+  // chunk — per the PRD, per-flow is the indivisible unit.
+  const emitSseSnapshotForPeer = (peerConnId: string): void => {
+    if (!sseTap) return;
+    let snap: Record<string, Record<string, SsePayload>>;
+    try {
+      snap = sseTap.snapshot();
+    } catch (err) {
+      console.warn('[share] sse-snapshot read failed:', err);
+      return;
+    }
+    const entries = Object.entries(snap);
+    if (entries.length === 0) return;
+
+    const chunks = chunkSnapshotByFlow(snap);
+    const total = chunks.length;
+    for (let i = 0; i < chunks.length; i += 1) {
+      const chunkFlows = chunks[i];
+      if (!chunkFlows) continue;
+      const payload: SseSnapshotPayload =
+        total === 1 ? { flows: chunkFlows } : { flows: chunkFlows, chunk: i, total };
+      try {
+        broadcast(makeEnvelope('sse-snapshot', payload, { to: peerConnId }));
+      } catch (err) {
+        console.warn('[share] sse-snapshot broadcast failed:', err);
+      }
+    }
+  };
+
+  // Emit the files-manifest frame to a freshly-joined peer. Awaits init() so a
+  // racing join (e.g. peer auth-peer'd before the walk completed) still gets a
+  // populated manifest. Errors only warn — the manifest is a hint, not a
+  // gating signal; the peer can fall back to file-request on cache miss.
+  const emitFilesManifestForPeer = async (peerConnId: string): Promise<void> => {
+    if (!filesManifestBuilder) return;
+    try {
+      if (filesManifestReady) await filesManifestReady;
+      const payload = filesManifestBuilder.build();
+      broadcast(makeEnvelope('files-manifest', payload, { to: peerConnId }));
+    } catch (err) {
+      console.warn('[share] files-manifest emit failed:', err);
+    }
+  };
+
+  const handleFrame = (env: Envelope) => {
+    if (env.type === 'presence') {
+      const base = PresenceBaseSchema.safeParse(env.payload);
+      if (!base.success) {
+        console.warn('[share] dropped presence frame: invalid payload');
+        return;
+      }
+      const kind = base.data.kind;
+      if (kind === 'join') {
+        const parsed = PresenceJoinSchema.safeParse(env.payload);
+        if (!parsed.success) {
+          console.warn('[share] dropped presence/join: invalid fields');
+          return;
+        }
+        const { peerId, displayName } = parsed.data;
+        peerConnIds.set(peerId, env.from);
+        connPeers.set(env.from, { peerId, displayName });
+        // Spin up the per-peer outbound SSE queue alongside the connId
+        // bookkeeping so any live frame that fires after presence/join lands
+        // on a bounded queue rather than hitting the legacy `to: 'all'` path.
+        if (!peerSseQueues.has(env.from)) {
+          peerSseQueues.set(env.from, buildPeerSseQueue(env.from));
+        }
+        // Join itself is always accepted — the peer becomes "known" only as
+        // a result of this frame, so rate-limiting it would be a chicken-and-
+        // egg problem. Audit it as accept so the trail shows who joined when.
+        audit({ ts: Date.now(), peerId, displayName, type: 'presence', verdict: 'accept' });
+        auditKind({ kind: 'peer-join', peerId, displayName });
+        if (current.status !== 'active') return;
+        if (current.peers.some((peer) => peer.peerId === peerId)) return;
+        setState({
+          ...current,
+          peers: [...current.peers, { peerId, displayName, joinedAt: Date.now() }],
+        });
+        // Prime the new peer with a one-shot files-manifest snapshot so its
+        // canvas can render placeholder sizing before any file-request fires.
+        // Fire-and-forget; emit failures are warned, never propagated.
+        void emitFilesManifestForPeer(env.from);
+        // Replay the SSE tap's last-seen per-node status so the joiner's
+        // canvas badges + play-button rings match the host within one render.
+        // Addressed to the joiner's connId only (not broadcast). Chunked
+        // per-flow when the serialized payload exceeds 256 KB.
+        emitSseSnapshotForPeer(env.from);
+        return;
+      }
+      if (kind === 'leave') {
+        const parsed = PresenceLeaveSchema.safeParse(env.payload);
+        if (!parsed.success) {
+          console.warn('[share] dropped presence/leave: invalid fields');
+          return;
+        }
+        const { peerId } = parsed.data;
+        const known = connPeers.get(env.from);
+        peerConnIds.delete(peerId);
+        connPeers.delete(env.from);
+        disposePeerSseQueue(env.from);
+        if (known) {
+          audit({
+            ts: Date.now(),
+            peerId: known.peerId,
+            displayName: known.displayName,
+            type: 'presence',
+            verdict: 'accept',
+          });
+          auditKind({
+            kind: 'peer-leave',
+            peerId: known.peerId,
+            displayName: known.displayName,
+          });
+        }
+        if (current.status !== 'active') return;
+        if (!current.peers.some((peer) => peer.peerId === peerId)) return;
+        setState({
+          ...current,
+          peers: current.peers.filter((peer) => peer.peerId !== peerId),
+        });
+        return;
+      }
+      // Other presence kinds (cursor, viewport, etc.) are sideband-only in v1.
+      return;
+    }
+
+    // Non-presence frames must come from a known peer (introduced earlier via
+    // presence/join). Frames from an unknown connId are dropped silently — we
+    // have no peerId/displayName to attribute the audit entry to.
+    const peer = connPeers.get(env.from);
+    if (!peer) {
+      console.debug('[share] dropped frame from unknown peer:', {
+        type: env.type,
+        from: env.from,
+      });
+      return;
+    }
+
+    const verdict = rateLimiter.check(peer.peerId);
+    if (!verdict.ok) {
+      audit({
+        ts: Date.now(),
+        peerId: peer.peerId,
+        displayName: peer.displayName,
+        type: env.type,
+        verdict: 'reject',
+        reason: 'rate-limited',
+      });
+      return;
+    }
+
+    audit({
+      ts: Date.now(),
+      peerId: peer.peerId,
+      displayName: peer.displayName,
+      type: env.type,
+      verdict: 'accept',
+    });
+
+    if (env.type === 'file-request') {
+      if (!fileRequestHandler) {
+        console.warn('[share] dropped file-request: no handler configured');
+        return;
+      }
+      fileRequestHandler.handle(env).catch((err) => {
+        console.warn('[share] file-request handler threw:', err);
+      });
+      return;
+    }
+
+    if (
+      env.type === 'file-upload-intent' ||
+      env.type === 'file-bytes' ||
+      env.type === 'file-upload-done'
+    ) {
+      if (!fileUploadHandler) {
+        console.warn(`[share] dropped ${env.type}: no upload handler configured`);
+        return;
+      }
+      const peerCtx = { peerId: peer.peerId, displayName: peer.displayName };
+      const dispatch =
+        env.type === 'file-upload-intent'
+          ? fileUploadHandler.handleIntent(env, peerCtx)
+          : env.type === 'file-bytes'
+            ? fileUploadHandler.handleBytes(env, peerCtx)
+            : fileUploadHandler.handleDone(env, peerCtx);
+      dispatch.catch((err) => {
+        console.warn(`[share] ${env.type} handler threw:`, err);
+      });
+      return;
+    }
+
+    if (env.type === 'rpc') {
+      // The wire-side `RpcFrameSchema` is strict, so strip envelope-only fields
+      // (`from`, `to`) before dispatch. Missing fields surface as
+      // 'invalid_envelope' below.
+      const wireFrame = {
+        v: env.v,
+        type: env.type,
+        id: env.id,
+        payload: env.payload,
+      };
+      const replyTo = env.from;
+      dispatchRpcFrame(wireFrame, { peerId: peer.peerId, displayName: peer.displayName })
+        .then((result) => {
+          if (!transport || !transport.isOpen()) return;
+          try {
+            transport.send(
+              makeEnvelope('rpc-result', result.payload, { to: replyTo, id: result.id }),
+            );
+          } catch (err) {
+            console.warn('[share] rpc-result send failed:', err);
+          }
+        })
+        .catch((err) => {
+          console.warn('[share] dispatchRpcFrame threw:', err);
+        });
+      return;
+    }
+
+    // All other envelope types are accepted-and-dropped in v1; real handling
+    // (file streaming, etc.) lands in phase 6+. Log type+from only — never
+    // the payload.
+    console.debug('[share] dropped frame:', { type: env.type, from: env.from });
+  };
+
+  // Active-sessions tracker (US-081). Persists `{sessionId, hostKey}` per
+  // session in `<auditDir>/active.json` so a single `killAll()` call can
+  // revoke every share link this studio has ever opened — not just the
+  // currently active one. Writes are atomic; reads tolerate a missing or
+  // corrupted file by returning an empty array.
+  interface TrackedSession {
+    sessionId: string;
+    hostKey: string;
+  }
+  const readTrackedSessions = (): TrackedSession[] => {
+    try {
+      if (!existsSync(activeSessionsPath)) return [];
+      const raw = readFileSync(activeSessionsPath, 'utf8');
+      const parsed = JSON.parse(raw) as unknown;
+      if (!Array.isArray(parsed)) return [];
+      return parsed.filter(
+        (s): s is TrackedSession =>
+          typeof s === 'object' &&
+          s !== null &&
+          typeof (s as { sessionId?: unknown }).sessionId === 'string' &&
+          typeof (s as { hostKey?: unknown }).hostKey === 'string',
+      );
+    } catch {
+      return [];
+    }
+  };
+  const writeTrackedSessions = (sessions: TrackedSession[]): void => {
+    try {
+      mkdirSync(dirname(activeSessionsPath), { recursive: true });
+      writeFileAtomic(activeSessionsPath, JSON.stringify(sessions));
+    } catch (err) {
+      console.warn('[share] active sessions write failed:', err);
+    }
+  };
+  const addTrackedSession = (sessionId: string, hk: string): void => {
+    const tracked = readTrackedSessions();
+    if (tracked.some((s) => s.sessionId === sessionId)) return;
+    writeTrackedSessions([...tracked, { sessionId, hostKey: hk }]);
+  };
+  const removeTrackedSession = (sessionId: string): void => {
+    const tracked = readTrackedSessions();
+    const next = tracked.filter((s) => s.sessionId !== sessionId);
+    if (next.length === tracked.length) return;
+    writeTrackedSessions(next);
+  };
+
+  const controller: ShareController = {
+    async start() {
+      if (current.status !== 'idle') {
+        throw new Error('share-already-active');
+      }
+      const res = await fetchFn(`${deps.relayHttpUrl}/api/share/sessions`, { method: 'POST' });
+      if (!res.ok) {
+        throw new Error(`share-relay-http-${res.status}`);
+      }
+      const body = (await res.json()) as RelaySessionResponse;
+
+      hostKey = body.hostKey;
+
+      return await new Promise<{ url: string; sessionId: string }>((resolve, reject) => {
+        let timeoutHandle: ReturnType<typeof setTimeout> | null = null;
+
+        const handle: BootHandle = {
+          settled: false,
+          cancelTimer: () => {
+            if (timeoutHandle !== null) {
+              clearTimeout(timeoutHandle);
+              timeoutHandle = null;
+            }
+          },
+          rejectStart: (err) => {
+            handle.settled = true;
+            reject(err);
+          },
+        };
+        bootHandle = handle;
+
+        timeoutHandle = setTimeout(() => {
+          if (handle.settled) return;
+          handle.settled = true;
+          timeoutHandle = null;
+          bootHandle = null;
+          teardown();
+          setState({ status: 'idle' });
+          reject(new Error('share-boot-timeout'));
+        }, BOOT_TIMEOUT_MS);
+
+        const onTransportState = (s: ShareTransportState) => {
+          if (handle.settled) return;
+          if (s === 'connecting' || s === 'reconnecting') {
+            if (current.status !== 'starting') setState({ status: 'starting' });
+            return;
+          }
+          if (s === 'open') {
+            handle.settled = true;
+            handle.cancelTimer();
+            bootHandle = null;
+            const url = `${deps.shareUrlBase}/${body.token}`;
+            // Open the per-session audit log before transitioning state so
+            // any frame that races in (e.g. immediate presence/join from a
+            // pre-connected peer) is captured.
+            try {
+              auditLog = auditLogFactory({ dir: auditDir, sessionId: body.sessionId });
+            } catch (err) {
+              console.warn('[share] audit log open failed:', err);
+              auditLog = null;
+            }
+            try {
+              auditLogger = auditLoggerFactory(body.sessionId, auditDir);
+            } catch (err) {
+              console.warn('[share] audit kind log open failed:', err);
+              auditLogger = null;
+            }
+            // host-start is the first kind-shaped entry written to the file
+            // so a consumer reading from cursor:0 sees the session boundary.
+            auditKind({ kind: 'host-start', peerId: null, displayName: null });
+            // Track the session in active.json so killAll() can revoke it
+            // later — even after the controller goes idle.
+            if (hostKey) addTrackedSession(body.sessionId, hostKey);
+            // Subscribe to local runtime events BEFORE transitioning state so
+            // any event that fires synchronously from a state subscriber finds
+            // the bridge wired up.
+            subscribeToEventBus();
+            // Kick off the files-manifest disk walk. presence/join handlers
+            // await this before emitting so the first joiner gets a populated
+            // payload even if it races init.
+            if (filesManifestBuilder) {
+              filesManifestReady = filesManifestBuilder.init().catch((err) => {
+                console.warn('[share] files-manifest init failed:', err);
+              });
+            }
+            setState({
+              status: 'active',
+              sessionId: body.sessionId,
+              token: body.token,
+              url,
+              peers: [],
+              startedAt: Date.now(),
+              hostDisplayName,
+              recentSessionCount: 0,
+            });
+            resolve({ url, sessionId: body.sessionId });
+            return;
+          }
+          // s === 'closed' before reaching 'open' => boot failed.
+          handle.settled = true;
+          handle.cancelTimer();
+          bootHandle = null;
+          transport = null;
+          hostKey = null;
+          setState({ status: 'idle' });
+          reject(new Error('share-transport-closed-during-boot'));
+        };
+
+        transport = transportFactory({
+          wsUrl: body.wsUrl,
+          sessionId: body.sessionId,
+          hostKey: body.hostKey,
+          onFrame: handleFrame,
+          onStateChange: onTransportState,
+        });
+      });
+    },
+    async stop() {
+      if (current.status === 'idle') return;
+
+      if (current.status === 'starting') {
+        // Abort the in-flight start: mark its boot settled BEFORE closing the
+        // transport so a synchronous 'closed' emit can't double-reject with
+        // 'share-transport-closed-during-boot'.
+        const handle = bootHandle;
+        bootHandle = null;
+        if (handle) {
+          handle.settled = true;
+          handle.cancelTimer();
+        }
+        setState({ status: 'stopping' });
+        teardown();
+        setState({ status: 'idle' });
+        if (handle) handle.rejectStart(new Error('share-stopped-during-start'));
+        return;
+      }
+
+      if (current.status === 'active') {
+        // host-stop fires BEFORE teardown so the audit append lands on the
+        // still-open logger; teardown closes it after.
+        auditKind({ kind: 'host-stop', peerId: null, displayName: null });
+        removeTrackedSession(current.sessionId);
+        setState({ status: 'stopping' });
+        teardown();
+        setState({ status: 'idle' });
+        return;
+      }
+
+      // status === 'stopping' or 'error' — treat as no-op; the in-flight
+      // stop will complete on its own and a fresh start() can follow.
+    },
+    handleRpcFrame: (frame, fromPeerId, displayName) =>
+      dispatchRpcFrame(frame, {
+        peerId: fromPeerId,
+        // Prefer the controller's known peer record so test/UI callers that
+        // only pass a peerId still attribute correctly when the peer is
+        // already known via presence/join. Falls back to the passed
+        // displayName, then the peerId itself, so attribution is always
+        // non-empty (AttributionSchema requires `displayName.min(1)`).
+        displayName:
+          [...connPeers.values()].find((p) => p.peerId === fromPeerId)?.displayName ??
+          displayName ??
+          fromPeerId,
+      }),
+    broadcastHostEdit(op, outcome) {
+      if (current.status !== 'active') return null;
+      if (outcome.kind !== 'ok') return null;
+      const attributedTo = { peerId: 'host', displayName: current.hostDisplayName };
+      // Audit the host-local edit so the JSONL file reflects every accepted
+      // mutation regardless of origin. peerId mirrors `attributedTo.peerId`
+      // ('host') so consumers can filter by attribution without a join.
+      try {
+        const entry: RpcAuditEntry = {
+          ts: Date.now(),
+          peerId: 'host',
+          op: op.op,
+          flowId: op.flowId,
+          ok: true,
+          attributedTo,
+        };
+        appendShareAuditFn(current.sessionId, entry);
+      } catch (err) {
+        console.warn('[share] host-edit audit append failed:', err);
+      }
+      return broadcastNodePatched(op, outcome, attributedTo);
+    },
+    async kick(peerId: string) {
+      if (current.status !== 'active' || !hostKey) {
+        throw new Error('share-not-active');
+      }
+      // Look up displayName from connPeers so the audit entry records the
+      // human-readable label even though the relay endpoint only takes a
+      // peerId. Falls back to null when the peer is unknown — but in that
+      // case we throw share-peer-not-found before issuing the RPC.
+      const known = [...connPeers.values()].find((p) => p.peerId === peerId);
+      if (!known) {
+        const reason = 'share-peer-not-found';
+        auditKind({
+          kind: 'rpc-reject',
+          peerId,
+          displayName: null,
+          op: 'kick',
+          reason,
+        });
+        throw new Error(reason);
+      }
+      const sessionId = current.sessionId;
+      try {
+        const res = await fetchFn(`${deps.relayHttpUrl}/api/share/kick`, {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({ sessionId, hostKey, peerId }),
+        });
+        if (!res.ok) {
+          throw new Error(`share-relay-http-${res.status}`);
+        }
+      } catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        auditKind({
+          kind: 'rpc-reject',
+          peerId,
+          displayName: known.displayName,
+          op: 'kick',
+          reason,
+        });
+        throw err;
+      }
+      auditKind({
+        kind: 'kick',
+        peerId,
+        displayName: known.displayName,
+      });
+    },
+    async rotateUrl() {
+      if (current.status !== 'active' || !hostKey) {
+        throw new Error('share-not-active');
+      }
+      const sessionId = current.sessionId;
+      const res = await fetchFn(`${deps.relayHttpUrl}/api/share/rotate`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ sessionId, hostKey }),
+      });
+      if (!res.ok) {
+        throw new Error(`share-relay-http-${res.status}`);
+      }
+      const body = (await res.json()) as { token: string };
+      const newUrl = `${deps.shareUrlBase}/${body.token}`;
+      // The relay's rotate endpoint kicks every peer connection as part of
+      // the rotation — none of them will reconnect with the old token. Clear
+      // our local peer book-keeping so state() reflects the empty roster the
+      // next subscriber tick will read.
+      for (const q of peerSseQueues.values()) {
+        try {
+          q.dispose();
+        } catch (err) {
+          console.warn('[share] sse queue dispose failed during rotate:', err);
+        }
+      }
+      peerSseQueues.clear();
+      peerConnIds.clear();
+      connPeers.clear();
+      if (current.status === 'active') {
+        setState({ ...current, token: body.token, url: newUrl, peers: [] });
+      }
+      auditKind({ kind: 'rotate', peerId: null, displayName: null });
+      return { url: newUrl };
+    },
+    async killAll() {
+      const tracked = readTrackedSessions();
+      let revoked = 0;
+      let failed = 0;
+      for (const { sessionId, hostKey: hk } of tracked) {
+        try {
+          const res = await fetchFn(`${deps.relayHttpUrl}/api/share/end`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ sessionId, hostKey: hk }),
+          });
+          if (!res.ok) {
+            failed += 1;
+            continue;
+          }
+          revoked += 1;
+        } catch {
+          failed += 1;
+        }
+      }
+      // Per-session audit append. Each session gets a `kill-switch` entry so
+      // a reader paging through that file sees the boundary. Use the factory
+      // (not the active controller's `auditLogger`) so we can target any
+      // tracked session — including ones whose controller is long since
+      // torn down.
+      for (const { sessionId } of tracked) {
+        try {
+          const logger = auditLoggerFactory(sessionId, auditDir);
+          await logger.append({
+            kind: 'kill-switch',
+            peerId: null,
+            displayName: null,
+            details: { revoked, failed },
+          });
+          await logger.close();
+        } catch (err) {
+          console.warn('[share] kill-switch audit append failed:', err);
+        }
+      }
+      writeTrackedSessions([]);
+      return { revoked, failed };
+    },
+    state() {
+      return enrichWithSseMetrics(current);
+    },
+    subscribe(fn) {
+      subscribers.add(fn);
+      try {
+        fn(enrichWithSseMetrics(current));
+      } catch (err) {
+        console.error('[share] subscriber threw on initial deliver, dropping:', err);
+      }
+      return () => {
+        subscribers.delete(fn);
+      };
+    },
+    subscribeAttributions(fn) {
+      attributionSubscribers.add(fn);
+      return () => {
+        attributionSubscribers.delete(fn);
+      };
+    },
+    audit: {
+      // Delegates to the per-session AuditLogger. Returns an empty page
+      // when no session is active so the endpoint can answer without a
+      // file-read; the endpoint itself returns 400 in that case before
+      // calling in, but stay safe-by-default here too.
+      async list(opts) {
+        const logger = auditLogger;
+        if (!logger) return { entries: [], nextCursor: null };
+        return logger.list(opts);
+      },
+    },
+  };
+
+  return controller;
+}