@openparachute/vault 0.6.5-rc.9 → 0.6.5

package/src/transcription/tiers.ts

@@ -0,0 +1,184 @@
+/**
+ * RAM/arch/OS tier selection for `transcription install` (scribe-fold
+ * Phase 2b — the ratified tier table, 2026-07-03).
+ *
+ * This is the PURE decision layer for the install verb's AUTO-DEFAULT: given
+ * host facts (OS, arch, total RAM), which local provider should this box run?
+ * No side effects — the CLI probes the host, prints the pick + footprint, and
+ * the operator confirms or overrides with `--provider`/`--model`.
+ *
+ * ## The ratified table
+ *
+ *   | Host                        | Default                                    |
+ *   |-----------------------------|--------------------------------------------|
+ *   | macOS Apple Silicon, 8GB+   | parakeet-mlx (parakeet-tdt-0.6b-v3;        |
+ *   |                             |   ~2.5GB disk, ~2.5–3GB peak)              |
+ *   | Linux 4GB+                  | onnx-asr (parakeet-0.6b int8; ~670MB disk, |
+ *   |                             |   ~1.2–2GB+ peak)                          |
+ *   | Linux ~2GB                  | transcribe-cpp + whisper-small GGUF — NOT  |
+ *   |                             |   Parakeet (scribe#82: Parakeet peak RAM   |
+ *   |                             |   exceeds 2GB on meeting-length audio)     |
+ *   | Linux ~1GB                  | REMOTE (scribe-http) by default; local     |
+ *   |                             |   whisper-tiny only as explicit opt-in     |
+ *   | Below floor / unknown host  | remote guidance — never force local        |
+ *
+ * Hosts the table doesn't name fall back to transcribe-cpp with its own
+ * Phase 2a RAM tiers (e.g. Intel macs; a hypothetical <8GB Apple-Silicon
+ * box) — that matrix already carries the scribe#82 Parakeet-at-4GB floor.
+ *
+ * ## Nominal-RAM slack
+ *
+ * Tier boundaries are NOMINAL sizes ("a 4GB droplet"), but the kernel/firmware
+ * reserve memory before userspace sees it — a nominal-4GB Linux box reports
+ * ~3.6–3.9GB via MemTotal. `NOMINAL_SLACK_GB` absorbs that so the box the
+ * table targets actually lands in its tier. The 1GB remote floor uses a
+ * smaller slack: below-floor boxes must steer remote, never get a local
+ * install forced on them.
+ */
+
+import {
+  MODELS,
+  selectAsset,
+  selectModelForRam,
+  type ModelChoice,
+} from "./install.ts";
+import { DEFAULT_ONNX_ASR_MODEL, DEFAULT_PARAKEET_MLX_MODEL } from "./select.ts";
+
+const GB = 2 ** 30;
+
+/** Kernel/firmware reservation tolerance on nominal tier boundaries. */
+export const NOMINAL_SLACK_GB = 0.4;
+
+/** Slack at the 1GB remote floor (a nominal-1GB box reports ~0.94–0.97GB). */
+const FLOOR_SLACK_GB = 0.1;
+
+/** A provider name the tier table can select. */
+export type TierProviderName = "parakeet-mlx" | "onnx-asr" | "transcribe-cpp" | "scribe-http";
+
+/** The resolved tier pick for a host. */
+export interface TierPlan {
+  /** The tier-default provider for this host. */
+  provider: TierProviderName;
+  platform: string;
+  arch: string;
+  /** Detected total RAM, GB (rounded to 1dp) for the human print. */
+  totalRamGb: number;
+  /**
+   * Model id for the pick: an HF repo (parakeet-mlx), an onnx-asr registry
+   * name, or a transcribe-cpp GGUF id from `MODELS`. Absent for scribe-http.
+   */
+  model?: string;
+  /** Approx download footprint, MB (model + runtime), for the confirm prompt. */
+  approxDiskMb?: number;
+  /** Human peak-RAM note for the confirm prompt. */
+  peakRamNote?: string;
+  /** One-line rationale for the pick (printed to the operator). */
+  reason: string;
+  /**
+   * Set on the remote-default tier when a local install is still POSSIBLE as
+   * an explicit opt-in (Linux ~1GB → transcribe-cpp + whisper-tiny). The CLI
+   * prints it as guidance; it is never auto-installed.
+   */
+  localOptIn?: { provider: "transcribe-cpp"; model: string; note: string };
+}
+
+/** Host facts the tier decision needs. */
+export interface TierInput {
+  /** Node `os.platform()` value ("darwin" / "linux" / …). */
+  platform: string;
+  /** Node `os.arch()` value ("arm64" / "x64" / …). */
+  arch: string;
+  /** Detected total physical RAM in bytes. */
+  totalRamBytes: number;
+}
+
+/**
+ * Pick the tier-default provider for a host. Pure — see the module header for
+ * the ratified table. The scribe#82 invariant this encodes: **no Parakeet
+ * variant is ever the default below 4GB** (and on Linux, below-4GB boxes get
+ * transcribe-cpp whisper models or the remote steer — never onnx-asr).
+ */
+export function selectDefaultProvider(input: TierInput): TierPlan {
+  const { platform, arch, totalRamBytes } = input;
+  const gb = totalRamBytes / GB;
+  const base = { platform, arch, totalRamGb: Math.round(gb * 10) / 10 };
+
+  // macOS Apple Silicon, 8GB+ → parakeet-mlx (MLX uses the GPU/unified memory;
+  // the best quality/speed on this hardware).
+  if (platform === "darwin" && arch === "arm64" && gb >= 8 - NOMINAL_SLACK_GB) {
+    return {
+      ...base,
+      provider: "parakeet-mlx",
+      model: DEFAULT_PARAKEET_MLX_MODEL,
+      approxDiskMb: 2500,
+      peakRamNote: "~2.5–3GB peak while transcribing",
+      reason: "Apple Silicon with 8GB+ RAM — parakeet-mlx (MLX) is the best local quality/speed here.",
+    };
+  }
+
+  // Linux 4GB+ → onnx-asr (Parakeet int8 ONNX — the proven scribe Linux
+  // path). Arch-gated: onnxruntime publishes wheels for x64/arm64 only.
+  if (platform === "linux" && (arch === "x64" || arch === "arm64") && gb >= 4 - NOMINAL_SLACK_GB) {
+    return {
+      ...base,
+      provider: "onnx-asr",
+      model: DEFAULT_ONNX_ASR_MODEL,
+      approxDiskMb: 670,
+      peakRamNote: "~1.2–2GB+ peak while transcribing (meeting-length audio uses the high end)",
+      reason: "Linux with 4GB+ RAM — onnx-asr runs Parakeet (int8 ONNX) comfortably at this size.",
+    };
+  }
+
+  // transcribe-cpp fallback tiers — only where a release asset exists for the
+  // host. Covers Linux ~2GB (whisper-small — NOT Parakeet, scribe#82) and the
+  // hosts the ratified table doesn't name (Intel macs etc.), reusing the
+  // Phase 2a RAM matrix (which already floors Parakeet-GGUF at 4GB).
+  const asset = selectAsset(platform, arch);
+  if (asset && gb >= 2 - NOMINAL_SLACK_GB) {
+    // Model pick: slack belongs to TIER-ENTRY boundaries, never to model-floor
+    // checks. The 4GB Parakeet-GGUF floor is checked against the UN-INFLATED
+    // RAM (adding slack here once picked a ~3.5GB-peak model for a real-3.6GB
+    // Intel Mac — ~0.1GB headroom, the scribe#82 OOM class resurrected).
+    // Below a true 4GB, the ratified "~2GB → small whisper" row covers the
+    // whole band (entry already vetted ≥ ~2GB nominal above).
+    const model: ModelChoice =
+      gb >= 4
+        ? (selectModelForRam(totalRamBytes) ?? MODELS["whisper-small.en"]!)
+        : MODELS["whisper-small.en"]!;
+    return {
+      ...base,
+      provider: "transcribe-cpp",
+      model: model.name,
+      approxDiskMb: model.approxSizeMb,
+      peakRamNote: `~${model.approxRuntimeGb}GB peak while transcribing`,
+      reason:
+        gb < 4
+          ? `~${base.totalRamGb}GB RAM — a small whisper GGUF via transcribe-cpp fits; Parakeet's peak RAM exceeds 2GB on meeting-length audio (scribe#82).`
+          : `${platform}/${arch} isn't a parakeet-mlx/onnx-asr tier host — transcribe-cpp with a RAM-tier GGUF is the local default.`,
+    };
+  }
+
+  // Linux ~1GB (and any asset-supported host just above the floor) → remote
+  // by default; whisper-tiny via transcribe-cpp only as an explicit opt-in.
+  if (asset && gb >= 1 - FLOOR_SLACK_GB) {
+    return {
+      ...base,
+      provider: "scribe-http",
+      reason: `only ~${base.totalRamGb}GB RAM — a remote provider is the reliable default at this size.`,
+      localOptIn: {
+        provider: "transcribe-cpp",
+        model: "whisper-tiny.en",
+        note: "a tiny local model is possible but slow/low-quality: `transcription install --provider transcribe-cpp --model whisper-tiny.en`",
+      },
+    };
+  }
+
+  // Below the floor, or a host with no local runtime at all → remote guidance.
+  return {
+    ...base,
+    provider: "scribe-http",
+    reason: asset
+      ? `only ~${base.totalRamGb}GB RAM — below the 1GB local floor; use a remote provider.`
+      : `no local transcription runtime for ${platform}/${arch} — use a remote provider.`,
+  };
+}

package/src/vault-create.test.ts

@@ -358,11 +358,11 @@ describe("vault create — services.json registration (#208)", () => {
  * Default-pack seeding on create (originally demo-prep Workstream A — A1/A3;
  * reshaped for named seed packs).
  *
- * A freshly-created vault must contain the `welcome` pack (three-note welcome
- * web + the one capture tag Notes requires) and the `getting-started` guide — and
- * NOT the `surface-starter` pack, which is opt-in via `add-pack` (ratified
- * 2026-07-02). Idempotent + best-effort: the seed never fails a create and
- * never clobbers an edited note.
+ * A freshly-created vault must contain the `welcome` pack (the five-guide
+ * welcome ring + the capture/guide tags) and the `getting-started`
+ * guide — and NOT the `surface-starter` pack, which is opt-in via `add-pack`
+ * (ratified 2026-07-02). Idempotent + best-effort: the seed never fails a
+ * create and never clobbers an edited note.
  */
 describe("vault create — default pack seeding (welcome + getting-started)", () => {
   /** Read all (path, content) rows from a created vault's SQLite DB. */
@@ -400,23 +400,28 @@ describe("vault create — default pack seeding (welcome + getting-started)", ()
     const notes = readNotes("guided");
     const gs = notes.find((n) => n.path === "Getting Started");
     const welcome = notes.find((n) => n.path === "Welcome to your vault 🪂");
-    const tryLinking = notes.find((n) => n.path === "Try linking notes");
+    const captureAnything = notes.find((n) => n.path === "Capture anything");
+    const tagsGraph = notes.find((n) => n.path === "Tags and the graph");
     const connectAi = notes.find((n) => n.path === "Connect your AI");
+    const yoursToKeep = notes.find((n) => n.path === "Yours to keep");
     expect(gs).toBeDefined();
     expect(welcome).toBeDefined();
-    expect(tryLinking).toBeDefined();
+    expect(captureAnything).toBeDefined();
+    expect(tagsGraph).toBeDefined();
     expect(connectAi).toBeDefined();
+    expect(yoursToKeep).toBeDefined();
     expect(gs!.content).toContain("# Getting Started");
     // Surface Starter is out of the default seed — no note, no dangling link.
     expect(notes.find((n) => n.path === "Surface Starter")).toBeUndefined();
     expect(gs!.content).not.toContain("[[Surface Starter]]");
-    expect(gs!.content).toContain("add-pack surface-starter");
-
-    // The ONE capture tag Notes requires arrives with the welcome pack —
-    // and nothing else (fresh-vault seed = 4 notes + 1 tag; the retired
-    // capture/text + capture/voice subtypes are no longer seeded).
-    expect(readTagNames("guided")).toEqual(["capture"]);
-    expect(notes).toHaveLength(4);
+    expect(gs!.content).toContain("add-pack");
+
+    // The capture tag Notes requires arrives with the welcome pack, alongside
+    // the guide (skill-file) tag — and nothing else (fresh-vault seed = 6 notes:
+    // the 5-guide ring + Getting Started. The retired capture/text + capture/voice
+    // subtypes and the vestigial #pinned seed are no longer seeded).
+    expect(readTagNames("guided").sort()).toEqual(["capture", "guide"]);
+    expect(notes).toHaveLength(6);
   });
 
   test("seeding doesn't break --json stdout (notes seeded silently)", () => {

package/src/vault.test.ts

@@ -1093,7 +1093,7 @@ describe("scoped MCP wrapper", async () => {
     close();
   });
 
-  // -- tag-scoped MCP wrappers (patterns/tag-scoped-tokens.md) ------------
+  // -- tag-scoped MCP wrappers (docs/contracts/tag-scoped-tokens.md) ------------
   //
   // These pin the behavior of `applyTagScopeWrappers` in mcp-tools.ts: each
   // wrapped tool's execute() honors the auth's scoped_tags allowlist. The

package/src/ws-server.ts

@@ -0,0 +1,408 @@
+/**
+ * Live-query WebSocket binding — the SELF-HOST (Bun.serve) integration
+ * (WS-hibernation migration, 2026-07-04; contract
+ * `parachute-cloud/workers/vault/docs/live-query-ws.md`).
+ *
+ * The cloud door runs this logic inside a per-vault Durable Object with
+ * Hibernatable WebSockets; the self-host door runs it in the single long-lived
+ * `Bun.serve` process (`server.ts`). Same wire contract, minus hibernation — a
+ * self-run Bun box has no per-connection duration bill, so a socket just lives
+ * in memory (free): no attachment / rehydration / eviction / sweep, no
+ * lifetime cap. Per-socket state lives on `ws.data` and is mutated in place.
+ *
+ * ## Where the pieces live
+ *   - `ws-subscribe.ts` — the PURE half (close codes, query validation, chunked
+ *     snapshot, message parsing, verb-rank) shared byte-shaped with cloud.
+ *   - `subscriptions.ts` — the transport-agnostic manager + `WsSink`
+ *     (`{ type, ...data }`), the sole live-transport sink since Phase 5.
+ *   - this module — the Bun.serve upgrade decision + `open`/`message`/`close`
+ *     handlers + the per-vault live-socket registry (the WS cap).
+ *
+ * ## First-message auth (fork 2, ratified)
+ * The socket is accepted pre-auth; the FIRST message must be
+ * `{"type":"auth","token"}` (browsers can't header-auth a WebSocket and the hub
+ * ws-bridge drops subprotocols). Auth reuses the FULL self-host auth seam by
+ * synthesizing a `Bearer` request — the WS token validates exactly as an HTTP
+ * `Authorization` header would (operator bearer / hub JWT / legacy YAML keys /
+ * dropped pvt_* → 401). A pending socket that never auths within ~10s is closed
+ * 4408. Re-auth on the open socket (client re-sends `auth` on token refresh) may
+ * only narrow-or-equal the granted verb (a widen → 4403); no re-snapshot.
+ */
+
+import type { Server, ServerWebSocket, WebSocketHandler } from "bun";
+import type { Store } from "../core/src/types.ts";
+import type { VaultConfig } from "./config.ts";
+import { readVaultConfig } from "./config.ts";
+import { getVaultStore } from "./vault-store.ts";
+import { authenticateVaultRequest, type AuthResult } from "./auth.ts";
+import { hasScopeForVault } from "./scopes.ts";
+import { expandTokenTagScope, filterNotesByTagScope } from "./tag-scope.ts";
+import { buildLiveMatcher } from "./live-match.ts";
+import {
+  subscriptionManager,
+  WsSink,
+  type SubscriptionHandle,
+  type SubscriptionManager,
+} from "./subscriptions.ts";
+import {
+  MAX_WS_SUBSCRIPTIONS,
+  WS_AUTH_DEADLINE_MS,
+  WS_CLOSE,
+  buildSnapshotFrames,
+  parseClientMessage,
+  sameTagScope,
+  subscriptionCapResponse,
+  urlFromQuery,
+  validateWsSubscribeQuery,
+  vaultVerbRank,
+} from "./ws-subscribe.ts";
+
+/** Per-connection state on `ws.data`. Mutated in place (no hibernation). */
+export interface SubscribeWsData {
+  vaultName: string;
+  /** Raw query string incl. leading `?` (e.g. `?tag=watch`). */
+  rawQuery: string;
+  state: "pending" | "ready";
+  /** Granted scopes recorded at auth (the re-auth narrow-or-equal check). */
+  grantedScopes: string[];
+  /** Granted tag-scope (`scoped_tags`) recorded at auth. The live matcher's
+   *  tag-scope is frozen at initial auth, so a re-auth that changes this is
+   *  refused (4403) rather than silently keeping the old scope. */
+  grantedTagScope: string[] | null;
+  /** Manager handle once the sub is live (null while pending). */
+  handle: SubscriptionHandle | null;
+  /** Pending-auth deadline timer (cleared on auth success / close). */
+  authTimer: ReturnType<typeof setTimeout> | null;
+}
+
+/** Upgrade decision returned to `server.ts`'s fetch. */
+export type WsUpgradeVerdict =
+  | { kind: "upgraded" }
+  | { kind: "response"; response: Response }
+  | { kind: "pass" };
+
+export interface SubscribeWsDeps {
+  /** Resolve a vault's store. Defaults to the process-wide `getVaultStore`. */
+  getStore?: (vaultName: string) => Store;
+  /** Read a vault's config. Defaults to `readVaultConfig`. */
+  getVaultConfig?: (vaultName: string) => VaultConfig | null;
+  /** The subscription manager. Defaults to the process-wide singleton. */
+  manager?: SubscriptionManager;
+  /**
+   * Authenticate a synthesized Bearer request. Defaults to
+   * `authenticateVaultRequest` (the full self-host auth seam). Injectable so
+   * tests can drive every close-code path (401 → 4401, 403 → 4403) without a
+   * live hub JWKS.
+   */
+  authenticate?: (
+    req: Request,
+    vaultConfig: VaultConfig,
+  ) => Promise<{ error: Response } | AuthResult>;
+  /** Per-vault concurrent WS-subscription cap. Defaults to
+   *  {@link MAX_WS_SUBSCRIPTIONS}; tests set it low to exercise the 503. */
+  maxSubscriptions?: number;
+  /** Pending-auth deadline (ms). Defaults to {@link WS_AUTH_DEADLINE_MS};
+   *  tests set it low to exercise the 4408 close without a 10s wait. */
+  authDeadlineMs?: number;
+}
+
+function json(data: unknown, status = 200): Response {
+  return Response.json(data, { status });
+}
+
+/** True iff the request is a WebSocket upgrade. */
+export function isWebSocketUpgrade(req: Request): boolean {
+  return (req.headers.get("upgrade") ?? "").toLowerCase() === "websocket";
+}
+
+const SUBSCRIBE_PATH = /^\/vault\/([^/]+)\/api\/subscribe$/;
+
+/**
+ * The self-host live-query WebSocket binding: an upgrade-decision function
+ * (called from `server.ts`'s fetch BEFORE the normal route pipeline) plus the
+ * `Bun.serve` `websocket` handlers. Both share the per-vault live-socket
+ * registry (closure state) that enforces the WS cap.
+ */
+export function createSubscribeWsBinding(deps: SubscribeWsDeps = {}): {
+  tryUpgrade: (req: Request, server: Server<SubscribeWsData>, path: string) => WsUpgradeVerdict;
+  handlers: WebSocketHandler<SubscribeWsData>;
+} {
+  const getStore = deps.getStore ?? getVaultStore;
+  const getVaultConfig = deps.getVaultConfig ?? readVaultConfig;
+  const manager = deps.manager ?? subscriptionManager;
+  const authenticate = deps.authenticate ?? authenticateVaultRequest;
+  const maxSubscriptions = deps.maxSubscriptions ?? MAX_WS_SUBSCRIPTIONS;
+  const authDeadlineMs = deps.authDeadlineMs ?? WS_AUTH_DEADLINE_MS;
+
+  // Per-vault live sockets (pending + ready) — the WS cap counts over these,
+  // mirroring the cloud door's `getWebSockets()` live count. A pending socket
+  // that never auths self-heals off this set via the ~10s deadline close.
+  const liveSockets = new Map<string, Set<ServerWebSocket<SubscribeWsData>>>();
+  const liveCount = (vaultName: string): number => liveSockets.get(vaultName)?.size ?? 0;
+  const addLiveSocket = (vaultName: string, ws: ServerWebSocket<SubscribeWsData>): void => {
+    let set = liveSockets.get(vaultName);
+    if (!set) {
+      set = new Set();
+      liveSockets.set(vaultName, set);
+    }
+    set.add(ws);
+  };
+  const removeLiveSocket = (vaultName: string, ws: ServerWebSocket<SubscribeWsData>): void => {
+    const set = liveSockets.get(vaultName);
+    if (!set) return;
+    set.delete(ws);
+    if (set.size === 0) liveSockets.delete(vaultName);
+  };
+
+  const clearAuthTimer = (ws: ServerWebSocket<SubscribeWsData>): void => {
+    if (ws.data.authTimer) {
+      clearTimeout(ws.data.authTimer);
+      ws.data.authTimer = null;
+    }
+  };
+
+  /** Drop a socket's manager subscription + registry slot (idempotent). */
+  const cleanupSocket = (ws: ServerWebSocket<SubscribeWsData>): void => {
+    clearAuthTimer(ws);
+    removeLiveSocket(ws.data.vaultName, ws);
+    if (ws.data.handle) {
+      ws.data.handle.close();
+      ws.data.handle = null;
+    }
+  };
+
+  /** Close a socket with an explicit application code, then tear down its sub
+   *  IMMEDIATELY (so no further event fans out to the closing socket). The
+   *  `close` handler re-runs cleanup idempotently. */
+  const closeWs = (ws: ServerWebSocket<SubscribeWsData>, code: number, reason: string): void => {
+    try {
+      ws.close(code, reason);
+    } catch {
+      /* already closing / closed */
+    }
+    cleanupSocket(ws);
+  };
+
+  const closeCodeForAuthError = (res: Response): number =>
+    res.status === 403 ? WS_CLOSE.FORBIDDEN : WS_CLOSE.UNAUTHORIZED;
+
+  /**
+   * First auth on a pending socket. On success: build the matcher + tag-scope +
+   * snapshot (all awaited), then SYNCHRONOUSLY flip → ready, register, and flush
+   * the chunked snapshot (no await between register and flush, so a deferred
+   * hook dispatch can't slip a live event ahead of the snapshot — the SSE
+   * ordering). Failure → 4401 (auth) / 4403 (scope) / 4400 (bad query).
+   */
+  async function authenticatePendingSocket(ws: ServerWebSocket<SubscribeWsData>, token: string): Promise<void> {
+    const { vaultName, rawQuery } = ws.data;
+    const vaultConfig = getVaultConfig(vaultName);
+    if (!vaultConfig) {
+      closeWs(ws, WS_CLOSE.PROTOCOL, "vault not found");
+      return;
+    }
+    let store: Store;
+    try {
+      store = getStore(vaultName);
+    } catch {
+      closeWs(ws, WS_CLOSE.PROTOCOL, "vault not available");
+      return;
+    }
+
+    // Reuse the FULL self-host auth seam via a synthesized Bearer request.
+    const authReq = new Request(`http://ws.local/vault/${vaultName}/api/subscribe${rawQuery}`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    const auth = await authenticate(authReq, vaultConfig);
+    if ("error" in auth) {
+      closeWs(ws, closeCodeForAuthError(auth.error), "auth failed");
+      return;
+    }
+    // Subscribe is a READ operation (admin ⊇ write ⊇ read).
+    if (!hasScopeForVault(auth.scopes, vaultName, "read")) {
+      closeWs(ws, WS_CLOSE.FORBIDDEN, "insufficient scope");
+      return;
+    }
+
+    // Query was validated at upgrade; re-validate from the stored raw string.
+    const validated = validateWsSubscribeQuery(urlFromQuery(rawQuery));
+    if ("error" in validated) {
+      closeWs(ws, WS_CLOSE.PROTOCOL, "invalid subscription query");
+      return;
+    }
+
+    let tagScopeAllowed: Set<string> | null;
+    let matcher;
+    let snapshotNotes;
+    try {
+      tagScopeAllowed = await expandTokenTagScope(store, auth.scoped_tags);
+      matcher = await buildLiveMatcher(store, validated.queryOpts);
+      // Snapshot = the COMPLETE scoped matching set — strip paging so snapshot ⊇ live.
+      const raw = await store.queryNotes({
+        ...validated.queryOpts,
+        limit: Number.MAX_SAFE_INTEGER,
+        offset: undefined,
+      });
+      snapshotNotes = filterNotesByTagScope(raw, tagScopeAllowed, auth.scoped_tags);
+    } catch {
+      closeWs(ws, WS_CLOSE.PROTOCOL, "snapshot query failed");
+      return;
+    }
+    const frames = buildSnapshotFrames(snapshotNotes);
+
+    // --- SYNCHRONOUS from here (no await) so no write interleaves between
+    //     register and the snapshot flush.
+    clearAuthTimer(ws);
+    ws.data.state = "ready";
+    ws.data.grantedScopes = auth.scopes;
+    ws.data.grantedTagScope = auth.scoped_tags;
+    const handle = manager.register({
+      vaultName,
+      matcher,
+      tagScopeAllowed,
+      tagScopeRaw: auth.scoped_tags,
+      sink: new WsSink(ws),
+      tracksFlush: false,
+      countsTowardCap: false,
+    });
+    if (!handle) {
+      closeWs(ws, WS_CLOSE.PROTOCOL, "could not register subscription");
+      return;
+    }
+    ws.data.handle = handle;
+
+    const sink = new WsSink(ws);
+    for (const frame of frames) if (!sink.sendRaw(frame)) break;
+  }
+
+  /**
+   * Re-auth on an open socket (client re-sends `auth` on token refresh):
+   * re-validate + enforce narrow-or-equal scope (a WIDEN → 4403), then update
+   * the recorded scopes. NO re-snapshot, NO re-register — the matcher + socket
+   * are unchanged (the self-host socket lives in memory regardless of exp; the
+   * re-auth check exists for wire-contract congruence with the cloud door).
+   *
+   * The live matcher's TAG-scope is frozen at initial auth (not re-derived per
+   * message), so a re-auth whose tag-scope differs in ANY way is refused (4403).
+   * The client reconnects fresh → the initial-connect path re-derives scope
+   * correctly. This closes a WS-only per-agent-isolation gap the SSE route can't
+   * have (SSE reconnects re-derive scope every time). See `sameTagScope`.
+   */
+  async function reauthReadySocket(ws: ServerWebSocket<SubscribeWsData>, token: string): Promise<void> {
+    const { vaultName, grantedScopes, grantedTagScope, rawQuery } = ws.data;
+    const vaultConfig = getVaultConfig(vaultName);
+    if (!vaultConfig) {
+      closeWs(ws, WS_CLOSE.PROTOCOL, "vault not found");
+      return;
+    }
+    const authReq = new Request(`http://ws.local/vault/${vaultName}/api/subscribe${rawQuery}`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    const auth = await authenticate(authReq, vaultConfig);
+    if ("error" in auth) {
+      closeWs(ws, closeCodeForAuthError(auth.error), "re-auth failed");
+      return;
+    }
+    if (vaultVerbRank(auth.scopes, vaultName) > vaultVerbRank(grantedScopes, vaultName)) {
+      closeWs(ws, WS_CLOSE.FORBIDDEN, "re-auth widens scope");
+      return;
+    }
+    // Tag-scope delta → force a clean reconnect (which re-derives scope). A
+    // narrowed/revoked/differently-scoped token must NOT keep the frozen matcher.
+    if (!sameTagScope(auth.scoped_tags, grantedTagScope)) {
+      closeWs(ws, WS_CLOSE.FORBIDDEN, "re-auth changes tag scope");
+      return;
+    }
+    ws.data.grantedScopes = auth.scopes;
+  }
+
+  function tryUpgrade(req: Request, server: Server<SubscribeWsData>, path: string): WsUpgradeVerdict {
+    const match = path.match(SUBSCRIBE_PATH);
+    if (!match) return { kind: "pass" };
+    const vaultName = match[1]!;
+
+    // WS upgrades are GET.
+    if (req.method !== "GET") {
+      return { kind: "response", response: json({ error: "Method not allowed", message: "subscribe is GET-only" }, 405) };
+    }
+    if (!getVaultConfig(vaultName)) {
+      return { kind: "response", response: json({ error: "Vault not found", vault: vaultName }, 404) };
+    }
+
+    const url = new URL(req.url);
+    // Same query rejects as the SSE route (byte-identical 400 body).
+    const validated = validateWsSubscribeQuery(url);
+    if ("error" in validated) return { kind: "response", response: validated.error };
+
+    // Per-vault WS cap (over the live sockets) — pending sockets count, and
+    // self-heal off the set via the ~10s auth-deadline close.
+    if (liveCount(vaultName) >= maxSubscriptions) {
+      return { kind: "response", response: subscriptionCapResponse() };
+    }
+
+    const data: SubscribeWsData = {
+      vaultName,
+      rawQuery: url.search,
+      state: "pending",
+      grantedScopes: [],
+      grantedTagScope: null,
+      handle: null,
+      authTimer: null,
+    };
+    const ok = server.upgrade(req, { data });
+    if (ok) return { kind: "upgraded" };
+    // Not a valid WS handshake (missing Sec-WebSocket-* headers).
+    return {
+      kind: "response",
+      response: json({ error: "Expected a WebSocket upgrade request" }, 426),
+    };
+  }
+
+  const handlers: WebSocketHandler<SubscribeWsData> = {
+    open(ws) {
+      addLiveSocket(ws.data.vaultName, ws);
+      // Pending-auth deadline: an accepted socket that never auths is closed
+      // 4408. `unref` so the timer never holds the process (or a test) open.
+      const timer = setTimeout(() => {
+        if (ws.data.state === "pending") closeWs(ws, WS_CLOSE.AUTH_TIMEOUT, "auth timeout");
+      }, authDeadlineMs);
+      (timer as { unref?: () => void }).unref?.();
+      ws.data.authTimer = timer;
+    },
+
+    async message(ws, message) {
+      // Client-driven liveness: the literal `ping` string → `pong`. Never JSON,
+      // so it short-circuits before `parseClientMessage`.
+      if (typeof message === "string" && message === "ping") {
+        try {
+          ws.send("pong");
+        } catch {
+          /* socket gone */
+        }
+        return;
+      }
+
+      const parsed = parseClientMessage(message as string | Uint8Array);
+      if (parsed.kind === "malformed") {
+        closeWs(ws, WS_CLOSE.PROTOCOL, "malformed message");
+        return;
+      }
+
+      if (ws.data.state === "pending") {
+        if (parsed.kind !== "auth") {
+          closeWs(ws, WS_CLOSE.PROTOCOL, "expected auth message");
+          return;
+        }
+        await authenticatePendingSocket(ws, parsed.token);
+      } else if (parsed.kind === "auth") {
+        await reauthReadySocket(ws, parsed.token);
+      }
+      // Any other message on a ready socket: ignored (forward-compat).
+    },
+
+    close(ws) {
+      cleanupSocket(ws);
+    },
+  };
+
+  return { tryUpgrade, handlers };
+}