@openparachute/vault 0.7.3-rc.11 → 0.7.3-rc.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.7.3-rc.11",
+  "version": "0.7.3-rc.13",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",

package/src/auth-hub-jwt.test.ts

@@ -28,7 +28,7 @@ import { tmpdir } from "os";
 import { generateKeyPair, exportJWK, SignJWT } from "jose";
 import { writeVaultConfig, readVaultConfig } from "./config.ts";
 import { getVaultStore, clearVaultStoreCache } from "./vault-store.ts";
-import { authenticateVaultRequest, authenticateGlobalRequest } from "./auth.ts";
+import { authenticateVaultRequest, authenticateGlobalRequest, deriveVaultFromToken } from "./auth.ts";
 import { resetJwksCache, resetRevocationCache } from "./hub-jwt.ts";
 
 interface Keypair {
@@ -705,3 +705,120 @@ describe("pvt_* DROP (vault#282 Stage 2 — unvalidatable)", () => {
     expect("error" in result).toBe(false);
   });
 });
+
+// ---------------------------------------------------------------------------
+// deriveVaultFromToken — the derivation precedence for the canonical root
+// `/mcp` endpoint (U1). This function READS a validated token's claims to name
+// the target vault; it never authorizes (the router re-dispatches through the
+// full per-vault machinery). These cases isolate the three naming sources —
+// narrowed scope / `aud=vault.<name>` / single-element `vault_scope` — and the
+// fail-closed rules (agree → one name; disagree or none → `not_derivable`).
+// The end-to-end routing.test.ts covers the wired behavior; this pins the
+// precedence logic directly.
+// ---------------------------------------------------------------------------
+describe("deriveVaultFromToken — root /mcp vault derivation (U1)", () => {
+  test("all three sources agree → that vault", async () => {
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "vault.journal",
+      scope: "vault:journal:write",
+      vaultScope: ["journal"],
+    });
+    expect(await deriveVaultFromToken(bearer(token))).toEqual({ vaultName: "journal" });
+  });
+
+  test("narrowed scope alone names the vault (non-vault aud, no vault_scope)", async () => {
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "urn:opaque-resource",
+      scope: "vault:journal:read",
+    });
+    expect(await deriveVaultFromToken(bearer(token))).toEqual({ vaultName: "journal" });
+  });
+
+  test("aud=vault.<name> alone names the vault (broad scope names nothing)", async () => {
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "vault.journal",
+      scope: "vault:read",
+    });
+    expect(await deriveVaultFromToken(bearer(token))).toEqual({ vaultName: "journal" });
+  });
+
+  test("single-element vault_scope alone names the vault", async () => {
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "urn:opaque-resource",
+      scope: "vault:read",
+      vaultScope: ["journal"],
+    });
+    expect(await deriveVaultFromToken(bearer(token))).toEqual({ vaultName: "journal" });
+  });
+
+  test("multi-element vault_scope is NOT a single name → not_derivable (nothing else names)", async () => {
+    // Phase-2 multi-vault shape: a multi-element vault_scope doesn't name ONE
+    // vault, so at the single-vault root it can't be the sole source.
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "urn:opaque-resource",
+      scope: "vault:read",
+      vaultScope: ["journal", "work"],
+    });
+    expect(await deriveVaultFromToken(bearer(token))).toEqual({ error: "not_derivable" });
+  });
+
+  test("sources disagree (scope vs aud) → not_derivable, never a guess", async () => {
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "vault.work",
+      scope: "vault:journal:write",
+    });
+    expect(await deriveVaultFromToken(bearer(token))).toEqual({ error: "not_derivable" });
+  });
+
+  test("no source names a vault → not_derivable", async () => {
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "urn:opaque-resource",
+      scope: "vault:read",
+    });
+    expect(await deriveVaultFromToken(bearer(token))).toEqual({ error: "not_derivable" });
+  });
+
+  test("no bearer → no_bearer", async () => {
+    const req = new Request("https://vault.test/mcp");
+    expect(await deriveVaultFromToken(req)).toEqual({ error: "no_bearer" });
+  });
+
+  test("non-JWT bearer (operator / legacy shape) names no vault → not_derivable", async () => {
+    // The operator VAULT_AUTH_TOKEN and legacy YAML keys are vault-agnostic —
+    // they can't route the token-derived root endpoint (they keep working at
+    // the per-vault URL).
+    expect(await deriveVaultFromToken(bearer("opaque-operator-secret"))).toEqual({
+      error: "not_derivable",
+    });
+  });
+
+  test("expired JWT → not_derivable (validated with the full trust kernel)", async () => {
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "vault.journal",
+      scope: "vault:journal:write",
+      ttlSeconds: -10, // already expired
+    });
+    expect(await deriveVaultFromToken(bearer(token))).toEqual({ error: "not_derivable" });
+  });
+
+  test("revoked JWT → not_derivable (revocation runs in derivation too)", async () => {
+    const jti = "u1-derive-revoked";
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "vault.journal",
+      scope: "vault:journal:write",
+      jti,
+    });
+    fixture.setRevoked([jti]);
+    resetRevocationCache();
+    expect(await deriveVaultFromToken(bearer(token))).toEqual({ error: "not_derivable" });
+  });
+});

package/src/auth.ts

@@ -30,6 +30,7 @@ import {
   hasScope,
   hasScopeForVault,
   legacyPermissionToScopes,
+  narrowedVaultNames,
   SCOPE_ADMIN,
   SCOPE_READ,
   SCOPE_WRITE,
@@ -712,3 +713,66 @@ export async function authenticateGlobalRequest(
   }
   return { error: Response.json({ error: "Unauthorized", message: "Invalid API key" }, { status: 401 }) };
 }
+
+/**
+ * Outcome of deriving a target vault from a request's bearer at the canonical
+ * root `/mcp` endpoint (U1). `vaultName` on success; a coarse failure `error`
+ * otherwise. Both failure reasons map to the SAME 401 + root-PRM challenge at
+ * the router — the distinction exists for logging/tests, never leaks to the
+ * client. `no_bearer` = no credential presented; `not_derivable` = a credential
+ * that names no single vault (non-JWT operator/legacy bearer, invalid /
+ * expired / revoked JWT, or a JWT whose scope / `aud` / `vault_scope` sources
+ * name zero or conflicting vaults).
+ */
+export type VaultDerivation =
+  | { vaultName: string }
+  | { error: "no_bearer" | "not_derivable" };
+
+/**
+ * Derive the target vault from a request's bearer token WITHOUT authorizing the
+ * request. The caller re-dispatches the derived name through the full per-vault
+ * auth machinery (`authenticateVaultRequest`), which re-validates the token
+ * WITH the audience pin — derive-then-redispatch, so a bad derivation FAILS the
+ * inner check rather than bypassing it (defense in depth). This function only
+ * reads the claims well enough to name the vault; it is never the authorization
+ * gate.
+ *
+ * Only hub-issued JWTs name a vault. The operator `VAULT_AUTH_TOKEN` and legacy
+ * YAML keys are vault-agnostic (they name no resource — see scopes.ts), so they
+ * return `not_derivable` here and keep working at the URL-addressed
+ * `/vault/<name>/*` surface. The JWT is validated with the SAME scope-guard
+ * trust kernel the per-vault path uses (signature, `iss` pin, `jti` +
+ * revocation, expiry) but WITHOUT `expectedAudience` — at the root we don't yet
+ * know which audience to expect; that pin is re-applied by the re-dispatch.
+ *
+ * From the validated claims, three independent sources can name a vault:
+ *   1. a narrowed `vault:<name>:<verb>` scope,
+ *   2. an `aud` of the form `vault.<name>`,
+ *   3. a single-element `vault_scope` claim.
+ * On a hub-minted token these AGREE. We collect every name any source provides
+ * and require EXACTLY ONE distinct name: zero (nothing named a vault) and
+ * two-or-more (the sources disagree) both fail closed with `not_derivable`. We
+ * never pick a winner from a precedence order — an ambiguous or unnamed token
+ * gets the discovery challenge, not a silent guess.
+ */
+export async function deriveVaultFromToken(req: Request): Promise<VaultDerivation> {
+  const key = extractApiKey(req);
+  if (!key) return { error: "no_bearer" };
+  if (!looksLikeJwt(key)) return { error: "not_derivable" };
+  let claims;
+  try {
+    // No `expectedAudience`: the per-vault trust kernel minus the aud pin
+    // (which the re-dispatch re-applies). A bad signature / iss / expiry /
+    // revoked jti throws here → not_derivable → the standard 401 challenge.
+    claims = await validateHubJwt(key, {});
+  } catch {
+    return { error: "not_derivable" };
+  }
+  const named = new Set<string>();
+  for (const name of narrowedVaultNames(claims.scopes)) named.add(name);
+  const audMatch = claims.aud?.match(/^vault\.(.+)$/);
+  if (audMatch) named.add(audMatch[1]!);
+  if (claims.vaultScope.length === 1) named.add(claims.vaultScope[0]!);
+  if (named.size !== 1) return { error: "not_derivable" };
+  return { vaultName: [...named][0]! };
+}

package/src/oauth-discovery.ts

@@ -27,6 +27,7 @@
  */
 
 import { getHubOrigin } from "./hub-jwt.ts";
+import { SCOPE_READ, SCOPE_WRITE } from "./scopes.ts";
 
 /**
  * OAuth scopes vault publishes through discovery, RESOURCE-NARROWED to the
@@ -87,6 +88,36 @@ export function handleProtectedResource(req: Request, vaultName: string): Respon
   });
 }
 
+/**
+ * Protected Resource Metadata (RFC 9728) for the CANONICAL ROOT `/mcp`
+ * endpoint (U1). Same document shape as `handleProtectedResource`, with two
+ * deliberate differences that follow from the root being vault-AGNOSTIC (the
+ * vault is derived from the token, not the URL):
+ *
+ *   - `resource` is the origin-root `<base>/mcp`, not a `/vault/<name>/mcp`.
+ *   - `scopes_supported` advertises the UN-NARROWED forms `vault:read` /
+ *     `vault:write` (there's no vault name to narrow to here). A spec-following
+ *     client reads these and requests the broad forms; the hub's consent picker
+ *     narrows the grant to a chosen vault at authorization time (that path
+ *     already exists hub-side), minting a token stamped with a
+ *     `vault:<name>:<verb>` scope + `aud=vault.<name>` — exactly what the root
+ *     endpoint derives the target vault from. `admin` is intentionally omitted:
+ *     the interactive connect flow grants read/write; admin is an operator
+ *     concern, not something the consent picker offers.
+ *
+ * Served at the RFC 9728 §3.1 path-insertion location for the root resource:
+ * `/.well-known/oauth-protected-resource/mcp`.
+ */
+export function handleRootProtectedResource(req: Request): Response {
+  const base = getBaseUrl(req);
+  return Response.json({
+    resource: `${base}/mcp`,
+    authorization_servers: [getHubOrigin()],
+    scopes_supported: [SCOPE_READ, SCOPE_WRITE],
+    bearer_methods_supported: ["header"],
+  });
+}
+
 /**
  * OAuth 2.0 Authorization Server Metadata (RFC 8414).
  *

package/src/routing.test.ts

@@ -10,8 +10,10 @@
  *  3. `/vault/<name>/...` — per-vault routing (OAuth, MCP, view, API).
  *  4. The RFC 9728 WWW-Authenticate challenge that decorates MCP 401s.
  *
- * No unscoped `/mcp`, `/api/*`, `/oauth/*` routes exist — every per-vault
- * resource must name the vault it targets.
+ * No unscoped `/api/*` or `/oauth/*` routes exist — those per-vault resources
+ * must name the vault in the URL. The canonical root `/mcp` (U1) is the one
+ * vault-agnostic exception: it derives the target vault from the token, then
+ * re-dispatches through the same per-vault machinery.
  *
  * Uses PARACHUTE_HOME override so each test's vaults live in a tmp dir and
  * never touch ~/.parachute.
@@ -706,14 +708,27 @@ describe("per-vault routing under /vault/<name>/", () => {
     }
   });
 
-  test("no /mcp, /api, /oauth unscoped routes — all 404", async () => {
+  test("no /api, /oauth unscoped routes — all 404", async () => {
     createVault("journal");
-    for (const path of ["/mcp", "/api/notes", "/oauth/register", "/oauth/authorize"]) {
+    for (const path of ["/api/notes", "/oauth/register", "/oauth/authorize"]) {
       const res = await route(new Request(`http://localhost:1940${path}`), path);
       expect(res.status).toBe(404);
     }
   });
 
+  test("root /mcp is NOT a 404 — it's the token-derived MCP endpoint (401 unauthenticated)", async () => {
+    // The old unscoped `/mcp` compat prefix returned 404. The canonical root
+    // `/mcp` (U1) replaces it: unauthenticated it 401s + carries the root PRM
+    // challenge, exactly like the per-vault endpoint but pointed at the root
+    // metadata document.
+    createVault("journal");
+    const res = await route(new Request("http://localhost:1940/mcp", { method: "POST" }), "/mcp");
+    expect(res.status).toBe(401);
+    expect(res.headers.get("WWW-Authenticate")).toBe(
+      'Bearer resource_metadata="http://localhost:1940/.well-known/oauth-protected-resource/mcp"',
+    );
+  });
+
   test("bare /vault/<name> returns metadata for authenticated callers", async () => {
     createVault("journal", "My journal vault");
     const path = "/vault/journal";
@@ -810,6 +825,216 @@ describe("MCP 401 WWW-Authenticate challenge (RFC 9728)", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Canonical root MCP endpoint — token-derived vault dispatch (U1).
+//
+// `/mcp` at the origin root derives the target vault from the TOKEN, not the
+// URL, then re-dispatches through the identical per-vault machinery. These
+// tests pin the two load-bearing properties: (1) a token for vault A behaves
+// byte-identically at root `/mcp` and at `/vault/A/mcp` (equivalence), and
+// (2) the vault is ALWAYS the one the token names — a token can't be steered
+// to another vault, and an unnameable/ambiguous token is refused with the root
+// discovery challenge rather than a guess (derivation honesty).
+// ---------------------------------------------------------------------------
+
+describe("canonical root /mcp — token-derived vault dispatch (U1)", () => {
+  const INIT = {
+    jsonrpc: "2.0",
+    id: 1,
+    method: "initialize",
+    params: {
+      protocolVersion: "2025-06-18",
+      capabilities: {},
+      clientInfo: { name: "u1-test", version: "0" },
+    },
+  };
+  const LIST = { jsonrpc: "2.0", id: 2, method: "tools/list" };
+  const QUERY = {
+    jsonrpc: "2.0",
+    id: 3,
+    method: "tools/call",
+    params: { name: "query-notes", arguments: {} },
+  };
+
+  async function mcpPost(path: string, token: string | null, rpc: object): Promise<Response> {
+    const headers: Record<string, string> = {
+      "content-type": "application/json",
+      accept: "application/json, text/event-stream",
+    };
+    if (token) headers.authorization = `Bearer ${token}`;
+    return route(
+      new Request(`http://localhost:1940${path}`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(rpc),
+      }),
+      path,
+    );
+  }
+
+  /** Parse a JSON-RPC frame off an MCP response, tolerating either the JSON
+   *  body (enableJsonResponse) or an SSE `data:` framing. */
+  async function rpcFrame(res: Response): Promise<unknown> {
+    const text = await res.text();
+    const trimmed = text.trimStart();
+    if (trimmed.startsWith("{") || trimmed.startsWith("[")) return JSON.parse(trimmed);
+    const dataLine = text.split("\n").find((l) => l.startsWith("data:"));
+    return JSON.parse(dataLine!.slice("data:".length).trim());
+  }
+
+  /** Sign a token directly (bypassing `mintJwt`'s `aud=vault.<name>` coupling)
+   *  so a test can craft a token whose sources name no vault, or disagree. */
+  async function signRaw(payload: Record<string, unknown>, aud: string): Promise<string> {
+    const iat = Math.floor(Date.now() / 1000);
+    return new SignJWT({ client_id: "u1-test", ...payload })
+      .setProtectedHeader({ alg: "RS256", kid: KID })
+      .setIssuer(`http://127.0.0.1:${hubServer.port}`)
+      .setSubject("u1-test-user")
+      .setAudience(aud)
+      .setIssuedAt(iat)
+      .setExpirationTime(iat + 60)
+      .setJti(`jti-${Math.random().toString(36).slice(2)}`)
+      .sign(signingKey);
+  }
+
+  test("root PRM mirrors the per-vault PRM shape (root resource, un-narrowed scopes)", async () => {
+    createVault("journal");
+    const path = "/.well-known/oauth-protected-resource/mcp";
+    const res = await route(new Request(`http://localhost:1940${path}`), path);
+    expect(res.status).toBe(200);
+    const prm = (await res.json()) as {
+      resource: string;
+      authorization_servers: string[];
+      scopes_supported: string[];
+      bearer_methods_supported: string[];
+    };
+    expect(prm.resource).toBe("http://localhost:1940/mcp");
+    // Un-narrowed forms — the hub's consent picker narrows them to a vault.
+    expect(prm.scopes_supported).toEqual(["vault:read", "vault:write"]);
+    expect(prm.bearer_methods_supported).toEqual(["header"]);
+    expect(Array.isArray(prm.authorization_servers)).toBe(true);
+    expect(prm.authorization_servers.length).toBe(1);
+  });
+
+  test("unauthenticated → 401 whose challenge names the root PRM (self-consistent pointer)", async () => {
+    createVault("journal");
+    const res = await mcpPost("/mcp", null, INIT);
+    expect(res.status).toBe(401);
+    const header = res.headers.get("WWW-Authenticate")!;
+    const prmUrl = header.match(/resource_metadata="([^"]+)"/)![1]!;
+    const prmPath = new URL(prmUrl).pathname;
+    expect(prmPath).toBe("/.well-known/oauth-protected-resource/mcp");
+    // The pointer resolves to a real PRM that names the root resource.
+    const prmRes = await route(new Request(prmUrl), prmPath);
+    expect(prmRes.status).toBe(200);
+    expect(((await prmRes.json()) as { resource: string }).resource).toBe(
+      "http://localhost:1940/mcp",
+    );
+  });
+
+  test("x-forwarded-* shape the root challenge URL", async () => {
+    createVault("journal");
+    const req = new Request("http://127.0.0.1:1940/mcp", {
+      method: "POST",
+      headers: {
+        "x-forwarded-host": "vault.example.com",
+        "x-forwarded-proto": "https",
+      },
+    });
+    const res = await route(req, "/mcp");
+    expect(res.status).toBe(401);
+    expect(res.headers.get("WWW-Authenticate")).toBe(
+      'Bearer resource_metadata="https://vault.example.com/.well-known/oauth-protected-resource/mcp"',
+    );
+  });
+
+  test("token for A at root /mcp === same token at /vault/A/mcp (initialize, tools/list, tool call)", async () => {
+    createVault("journal");
+    const store = getVaultStore("journal");
+    await store.createNote("root-mcp equivalence fixture", { path: "fixture", tags: ["probe"] });
+    const token = await mintJwt({ vaultName: "journal", scopes: ["vault:journal:admin"] });
+
+    for (const rpc of [INIT, LIST, QUERY]) {
+      const rootRes = await mcpPost("/mcp", token, rpc);
+      const perVaultRes = await mcpPost("/vault/journal/mcp", token, rpc);
+      expect(rootRes.status).toBe(200);
+      expect(perVaultRes.status).toBe(200);
+      // Byte-identical JSON-RPC frame — the root path derived `journal`, so the
+      // server name, tool list, and tool result all match the URL-addressed
+      // endpoint exactly.
+      expect(await rpcFrame(rootRes)).toEqual(await rpcFrame(perVaultRes));
+    }
+  });
+
+  test("a read-only token narrows the root tool list identically to the per-vault endpoint", async () => {
+    createVault("journal");
+    getVaultStore("journal");
+    const readToken = await mintJwt({ vaultName: "journal", scopes: ["vault:journal:read"] });
+    const rootList = await rpcFrame(await mcpPost("/mcp", readToken, LIST));
+    const perVaultList = await rpcFrame(await mcpPost("/vault/journal/mcp", readToken, LIST));
+    expect(rootList).toEqual(perVaultList);
+    // Sanity: a read token sees the read tools but not write/admin ones.
+    const names = (rootList as { result: { tools: { name: string }[] } }).result.tools.map(
+      (t) => t.name,
+    );
+    expect(names).toContain("query-notes");
+    expect(names).not.toContain("create-note");
+    expect(names).not.toContain("manage-token");
+  });
+
+  test("a vault-A token ALWAYS lands in A through root /mcp — never another vault's data", async () => {
+    createVault("alpha");
+    createVault("beta");
+    // Seed a secret in BETA. A token minted for ALPHA must never surface it.
+    await getVaultStore("beta").createNote("BETA-ONLY-SECRET", { path: "secret" });
+    getVaultStore("alpha");
+    const alphaToken = await mintJwt({ vaultName: "alpha", scopes: ["vault:alpha:admin"] });
+
+    const res = await mcpPost("/mcp", alphaToken, QUERY);
+    expect(res.status).toBe(200);
+    // The vault is derived from the token (alpha); beta's note is unreachable.
+    expect(JSON.stringify(await rpcFrame(res))).not.toContain("BETA-ONLY-SECRET");
+  });
+
+  test("scope and aud naming DIFFERENT vaults → 401 (disagreement, never guess)", async () => {
+    createVault("alpha");
+    createVault("beta");
+    // aud=vault.alpha (from vaultName) but the scope names beta — two sources
+    // disagree, so derivation refuses rather than picking a winner.
+    const token = await mintJwt({ vaultName: "alpha", scopes: ["vault:beta:admin"] });
+    const res = await mcpPost("/mcp", token, INIT);
+    expect(res.status).toBe(401);
+    expect(res.headers.get("WWW-Authenticate")).toContain("/.well-known/oauth-protected-resource/mcp");
+  });
+
+  test("a token that names NO vault (broad scope, non-vault aud, no vault_scope) → 401", async () => {
+    createVault("journal");
+    // Broad `vault:read` names no vault; aud is not `vault.<name>`; no
+    // vault_scope claim. Nothing derives a target → the discovery challenge.
+    const token = await signRaw({ scope: "vault:read" }, "some-other-resource");
+    const res = await mcpPost("/mcp", token, INIT);
+    expect(res.status).toBe(401);
+    expect(res.headers.get("WWW-Authenticate")).toContain("/.well-known/oauth-protected-resource/mcp");
+  });
+
+  test("an invalid / unverifiable token → 401 + root challenge (no vault leaked)", async () => {
+    createVault("journal");
+    const res = await mcpPost("/mcp", "not-a-real-jwt", INIT);
+    expect(res.status).toBe(401);
+    expect(res.headers.get("WWW-Authenticate")).toContain("/.well-known/oauth-protected-resource/mcp");
+  });
+
+  test("a validly-signed token naming a vault absent on THIS server → 404 (mirrors per-vault)", async () => {
+    createVault("journal");
+    // Token is real (signed by the fixture hub) but names a vault that isn't
+    // installed here. The per-vault URL 404s for a missing vault; root matches.
+    const token = await mintJwt({ vaultName: "ghost", scopes: ["vault:ghost:admin"] });
+    const res = await mcpPost("/mcp", token, INIT);
+    expect(res.status).toBe(404);
+    expect(((await res.json()) as { error: string }).error).toBe("Vault not found");
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Per-vault OAuth discovery (RFC 8414 / RFC 9728, path-append form).
 //

package/src/routing.ts

@@ -1,15 +1,23 @@
 /**
  * HTTP request router for the multi-vault server.
  *
- * All per-vault resources live under `/vault/<name>/...`. There is no
- * unscoped fallback — a request must name the vault it targets. A fresh
- * install creates a vault named `default`, so `/vault/default/...` is the
- * baseline URL for single-vault deployments.
+ * Per-vault resources live under `/vault/<name>/...` — a request names the
+ * vault it targets in the URL. The one exception is the canonical root `/mcp`
+ * endpoint (U1), which is vault-AGNOSTIC: the vault is derived from the token,
+ * not the URL. A fresh install creates a vault named `default`, so
+ * `/vault/default/...` is the baseline URL for single-vault deployments.
  *
  * Dispatch shape:
  *
  *   /.well-known/parachute.json        — NOT served here (CLI owns it at
  *                                        origin root; vault never handles it)
+ *   /.well-known/oauth-protected-resource/mcp
+ *                                      — root-endpoint PRM (RFC 9728) for the
+ *                                        canonical `/mcp` below (U1)
+ *   /mcp[/*]                           — canonical root MCP endpoint; the vault
+ *                                        is DERIVED FROM THE TOKEN, then the
+ *                                        request re-dispatches through the same
+ *                                        per-vault machinery (U1)
  *   /health                            — liveness ping, vault names leaked
  *                                        only to authenticated callers
  *   /vaults/list                       — public vault-name discovery (can be
@@ -21,15 +29,20 @@
  *   /vault/<name>/.well-known/oauth-*  — discovery forwarder; metadata names
  *                                        the hub as the authorization server
  *                                        (vault is resource-server only)
- *   /vault/<name>/mcp[/*]              — MCP endpoint (Bearer auth)
+ *   /vault/<name>/mcp[/*]              — MCP endpoint (Bearer auth); the
+ *                                        URL-addressed twin of root `/mcp`,
+ *                                        untouched and permanent
  *   /vault/<name>/view/<idOrPath>      — auth-aware HTML view
  *   /vault/<name>/public/<noteId>      — legacy alias → /view redirect
  *   /vault/<name>                      — vault metadata + stats (auth)
  *   /vault/<name>/api/...              — REST surface (auth)
  *
- * There is deliberately no compat for the old `/api/*`, `/mcp`, `/oauth/*`,
- * `/view/*`, or `/vaults/<name>/*` prefixes. Clients must re-authenticate
- * after the upgrade and point at the new URLs.
+ * The root `/mcp` here is NOT the old unscoped compat prefix (that pre-0.5.0
+ * `/mcp` — an alias for a single default vault — is gone). It's the token-
+ * derived door: same auth machinery as the per-vault endpoint, reached without
+ * the client having to know the vault's URL name. There is still deliberately
+ * no compat for the old `/api/*`, `/oauth/*`, `/view/*`, or `/vaults/<name>/*`
+ * prefixes; clients using those must re-authenticate and point at the new URLs.
  *
  * **No standalone OAuth issuer.** vault does not mint OAuth tokens or
  * render a consent UI. Hub is the issuer; vault validates hub-signed
@@ -50,6 +63,7 @@ import {
 import {
   authenticateVaultRequest,
   authenticateGlobalRequest,
+  deriveVaultFromToken,
   extractApiKey,
 } from "./auth.ts";
 import { hasScopeForVault, hasMigrateScopeForVault, SCOPE_ADMIN, SCOPE_READ, scopeForMethod, verbForMethod } from "./scopes.ts";
@@ -78,6 +92,7 @@ import { handleTriggers } from "./triggers-api.ts";
 import { expandTokenTagScope } from "./tag-scope.ts";
 import {
   handleProtectedResource,
+  handleRootProtectedResource,
   handleAuthorizationServer,
   getBaseUrl,
 } from "./oauth-discovery.ts";
@@ -135,6 +150,58 @@ async function withMcpChallenge(
   return new Response(body, { status: 401, headers });
 }
 
+/**
+ * 401 + RFC 9728 challenge for the canonical ROOT `/mcp` endpoint (U1), when
+ * the token is absent / invalid / names no single vault. Mirrors
+ * `withMcpChallenge` but points at the ROOT protected-resource metadata
+ * (`/.well-known/oauth-protected-resource/mcp`) rather than a vault-scoped one,
+ * since the root resource is vault-agnostic. A spec-following MCP client
+ * follows this pointer to the root PRM, discovers the hub, and requests the
+ * un-narrowed scopes the hub's consent picker narrows to a chosen vault.
+ */
+function rootMcpChallenge(req: Request): Response {
+  const base = getBaseUrl(req);
+  return Response.json(
+    { error: "Unauthorized", message: "API key required" },
+    {
+      status: 401,
+      headers: {
+        "WWW-Authenticate": `Bearer resource_metadata="${base}/.well-known/oauth-protected-resource/mcp"`,
+      },
+    },
+  );
+}
+
+/**
+ * Shared scoped-MCP dispatch tail used by BOTH the URL-addressed per-vault
+ * endpoint (`/vault/<name>/mcp`) and the token-derived root endpoint (`/mcp`,
+ * U1). Runs the FULL per-vault auth machinery via `authenticateVaultRequest`
+ * (audience strict-check, `vault_scope` pin, broad-scope rejection, tag-scope
+ * parse) and, on success, hands off to `handleScopedMcp`. A 401 is decorated
+ * with the per-vault RFC 9728 challenge. Because both entry points funnel
+ * through this one function, a root request behaves byte-identically to the
+ * same token at the per-vault URL — and, for the root, the re-validation here
+ * is the authoritative gate: a derivation that named the wrong vault fails the
+ * audience strict-check, it never bypasses it.
+ */
+async function dispatchScopedMcp(
+  req: Request,
+  vaultName: string,
+  vaultConfig: VaultConfig,
+): Promise<Response> {
+  const auth = await authenticateVaultRequest(req, vaultConfig);
+  if ("error" in auth) return withMcpChallenge(auth.error, req, vaultName);
+  // Thread the RAW caller bearer (the exact credential the session presented)
+  // into the MCP layer so the manage-token tool can forward it to hub's
+  // mint-token attenuation proxy (vault#403, MGT). Only the raw validated
+  // bearer — never a fabricated one. extractApiKey returns the same value
+  // `authenticateVaultRequest` validated above; non-forwardable credentials
+  // (env-var secret, legacy pvt_*) are handled by manage-token itself (it only
+  // forwards JWT-shaped bearers).
+  const callerBearer = extractApiKey(req);
+  return handleScopedMcp(req, vaultName, auth, callerBearer);
+}
+
 /**
  * Check if a /view request has a valid API key (header or ?key= query param).
  * Returns true if authenticated, false if not. Never rejects — unauthenticated
@@ -260,6 +327,18 @@ export async function route(
     return handleAuthorizationServer(req, vaultName);
   }
 
+  // Root-endpoint protected-resource metadata (RFC 9728 §3.1 path-insertion)
+  // for the canonical `/mcp` endpoint (U1). The root resource is vault-
+  // agnostic — the target vault is derived from the token, not the URL — so
+  // this document carries no vault name and advertises the un-narrowed
+  // `vault:read` / `vault:write` scopes; the hub's consent picker narrows them
+  // to a chosen vault at authorization time. Distinct from the per-vault
+  // insertion shapes above (which require a `/vault/<name>` segment), so there
+  // is no overlap. The `rootMcpChallenge` 401 points clients here.
+  if (path === "/.well-known/oauth-protected-resource/mcp") {
+    return handleRootProtectedResource(req);
+  }
+
   // ---------------------------------------------------------------------
   // Cross-vault / origin-root endpoints
   // ---------------------------------------------------------------------
@@ -368,6 +447,43 @@ export async function route(
     return Response.json({ vaults });
   }
 
+  // ---------------------------------------------------------------------
+  // Canonical root MCP endpoint — token-derived vault dispatch (U1).
+  //
+  // `POST /mcp` (plus the GET/DELETE the streamable-HTTP transport uses, and
+  // the `/mcp/*` subpaths) is the vault-AGNOSTIC entry point: the target vault
+  // is derived from the TOKEN, not the URL. We validate the bearer with the
+  // same scope-guard trust kernel the per-vault path uses, read the vault name
+  // from the token's claims, then RE-DISPATCH through the identical per-vault
+  // machinery (`dispatchScopedMcp` → `authenticateVaultRequest` →
+  // `handleScopedMcp`). The re-dispatch re-validates WITH the audience pin, so
+  // a bad derivation fails the inner check rather than bypassing it (defense in
+  // depth). The legacy URL-addressed `/vault/<name>/mcp` is untouched and lives
+  // forever.
+  //
+  // No / invalid / unnameable token → 401 whose `WWW-Authenticate` points at
+  // the ROOT PRM (`/.well-known/oauth-protected-resource/mcp`), so a spec-
+  // following MCP client discovers the hub and requests the un-narrowed scopes
+  // its consent picker narrows to a chosen vault.
+  if (path === "/mcp" || path.startsWith("/mcp/")) {
+    const derived = await deriveVaultFromToken(req);
+    if ("error" in derived) {
+      return rootMcpChallenge(req);
+    }
+    const vaultConfig = readVaultConfig(derived.vaultName);
+    if (!vaultConfig) {
+      // A validly-signed hub token naming a vault that isn't on THIS server.
+      // Mirror the per-vault 404 (`/vault/<name>/mcp` on a missing vault) — the
+      // holder knows which vault their token targets; nothing is leaked to an
+      // anonymous caller (they never validate a token to reach here).
+      return Response.json(
+        { error: "Vault not found", vault: derived.vaultName },
+        { status: 404 },
+      );
+    }
+    return dispatchScopedMcp(req, derived.vaultName, vaultConfig);
+  }
+
   // ---------------------------------------------------------------------
   // Per-vault routing: /vault/<name>/...
   // ---------------------------------------------------------------------
@@ -507,28 +623,24 @@ export async function route(
     return handleTicketSpend(req, ticketId, vaultName, store);
   }
 
+  // MCP (per-vault, single-vault session) — the URL names the vault. Shares
+  // the exact dispatch tail with the token-derived root `/mcp` (U1), so both
+  // behave identically. Handled BEFORE the shared authenticated-surface auth
+  // below because `dispatchScopedMcp` owns its own auth + 401 challenge; a
+  // non-MCP 401 further down never carries the RFC 9728 challenge (it's
+  // MCP-only).
+  if (subpath === "/mcp" || subpath.startsWith("/mcp/")) {
+    return dispatchScopedMcp(req, vaultName, vaultConfig);
+  }
+
   // ---------------------------------------------------------------------
   // Authenticated surface
   // ---------------------------------------------------------------------
 
   const store = getVaultStore(vaultName);
   const auth = await authenticateVaultRequest(req, vaultConfig);
-  const isScopedMcp = subpath === "/mcp" || subpath.startsWith("/mcp/");
   if ("error" in auth) {
-    return isScopedMcp ? withMcpChallenge(auth.error, req, vaultName) : auth.error;
-  }
-
-  // MCP (per-vault, single-vault session).
-  if (isScopedMcp) {
-    // Thread the RAW caller bearer (the exact credential the session
-    // presented) into the MCP layer so the manage-token tool can forward it
-    // to hub's mint-token attenuation proxy (vault#403, MGT). Only the raw
-    // validated bearer — never a fabricated one. extractApiKey returns the
-    // same value `authenticateVaultRequest` validated above; non-forwardable
-    // credentials (env-var secret, legacy pvt_*) are handled by manage-token
-    // itself (it only forwards JWT-shaped bearers).
-    const callerBearer = extractApiKey(req);
-    return handleScopedMcp(req, vaultName, auth, callerBearer);
+    return auth.error;
   }
 
   // Bare `/vault/<name>` — single-vault root. Returns name, description,

package/src/scopes.ts

@@ -263,6 +263,28 @@ export function validateMintedScopes(
   return { ok: true };
 }
 
+/**
+ * Distinct vault names NAMED by narrowed `vault:<name>:<verb>` scopes in the
+ * granted list. Broad `vault:<verb>` scopes name no vault (a legacy/operator
+ * shape) and are skipped; the `migrate` axis isn't a read/write/admin verb so
+ * `decomposeVaultScope` returns null for it and it too is skipped.
+ *
+ * Used by the canonical root `/mcp` endpoint (U1) to read the target vault
+ * from a token's scope claim — one of three agreeing sources (scope / `aud` /
+ * single-element `vault_scope`) that `deriveVaultFromToken` cross-checks. A
+ * hub-minted token carries scopes for exactly one vault, so this returns a
+ * single-element list in practice; a return of length ≠ 1 signals a
+ * malformed/multi-vault scope set the derivation treats as a disagreement.
+ */
+export function narrowedVaultNames(granted: string[]): string[] {
+  const names = new Set<string>();
+  for (const s of granted) {
+    const d = decomposeVaultScope(s);
+    if (d && d.vault !== null) names.add(d.vault);
+  }
+  return [...names];
+}
+
 /**
  * Detect a broad `vault:<verb>` scope in a granted list. Hub-issued JWTs
  * must NOT carry broad vault scopes — the hub mints `vault:<name>:<verb>` so

package/src/transcription-worker.test.ts

@@ -1627,3 +1627,154 @@ describe("transcription worker — legacy in-body memo content safety (finding F
     expect(note!.content).toContain("retry text with $& and $0 and $$ literal");
   });
 });
+
+// ---------------------------------------------------------------------------
+// voice W2 — segmented recordings. The app slices a long recording into
+// ~10-min segments, each linked as its own attachment on ONE note carrying a
+// client-set `segment_index` (0-based). The legacy in-body path targets that
+// part's markers — `_Transcript pending (part N)._` / `_Transcription
+// unavailable (part N)._`, N = segment_index + 1 — so each transcript lands in
+// its own pre-allocated slot regardless of completion order. Marker strings
+// are a BYTE-EXACT cross-door + cross-repo contract (the cloud worker ships
+// the identical text), so these assertions pin the exact bytes.
+// ---------------------------------------------------------------------------
+
+describe("transcription worker — segmented recordings (voice W2)", () => {
+  test("three parts completing OUT OF ORDER (2 ok, 0 fails, 1 ok) each land in their own slot", async () => {
+    // One note, three pre-allocated part slots + the shared stub opt-in.
+    const body =
+      "# 🎙️ Voice memo\n\n" +
+      "_Transcript pending (part 1)._\n\n" +
+      "_Transcript pending (part 2)._\n\n" +
+      "_Transcript pending (part 3)._\n";
+    await store.createNote(body, { id: "seg-note", metadata: { transcribe_stub: true } });
+
+    seedAudio("memos/seg0.webm");
+    seedAudio("memos/seg1.webm");
+    seedAudio("memos/seg2.webm");
+    const seg0 = await store.addAttachment("seg-note", "memos/seg0.webm", "audio/webm", {
+      transcribe_status: "pending",
+      segment_index: 0,
+    });
+    const seg1 = await store.addAttachment("seg-note", "memos/seg1.webm", "audio/webm", {
+      transcribe_status: "pending",
+      segment_index: 1,
+    });
+    const seg2 = await store.addAttachment("seg-note", "memos/seg2.webm", "audio/webm", {
+      transcribe_status: "pending",
+      segment_index: 2,
+    });
+
+    // Complete part 3 (segment_index 2) FIRST — success.
+    const w2 = makeWorker({ fetchImpl: mkFetchMock([{ text: "part three text" }]) });
+    try { await w2.kick("default", seg2); } finally { await w2.stop(); }
+
+    // Then part 1 (segment_index 0) — terminal failure (maxAttempts=1).
+    const w0 = makeWorker({
+      fetchImpl: mkFetchMock([{ error: "scribe down", status: 500 }]),
+      maxAttempts: 1,
+    });
+    try { await w0.kick("default", seg0); } finally { await w0.stop(); }
+
+    // Finally part 2 (segment_index 1) — success.
+    const w1 = makeWorker({ fetchImpl: mkFetchMock([{ text: "part two text" }]) });
+    try { await w1.kick("default", seg1); } finally { await w1.stop(); }
+
+    const note = await store.getNote("seg-note");
+    // Each part landed in its own slot: part 1 → failure marker, part 2/3 →
+    // their transcripts, despite completing 3 → 1 → 2.
+    expect(note!.content).toBe(
+      "# 🎙️ Voice memo\n\n" +
+      "_Transcription unavailable (part 1)._\n\n" +
+      "part two text\n\n" +
+      "part three text\n",
+    );
+    // Shared stub SURVIVES — sibling parts each needed the gate open; a
+    // per-part clear (the un-segmented behavior) would have blocked parts 2 & 3.
+    expect((note!.metadata as any)?.transcribe_stub).toBe(true);
+
+    // Attachment rows reflect their individual outcomes.
+    const atts = await store.getAttachments("seg-note");
+    const byIndex = Object.fromEntries(atts.map((a) => [a.metadata?.segment_index, a]));
+    expect(byIndex[0]!.metadata?.transcribe_status).toBe("failed");
+    expect(byIndex[1]!.metadata?.transcribe_status).toBe("done");
+    expect(byIndex[1]!.metadata?.transcript).toBe("part two text");
+    expect(byIndex[2]!.metadata?.transcribe_status).toBe("done");
+    expect(byIndex[2]!.metadata?.transcript).toBe("part three text");
+  });
+
+  test("un-segmented attachment → BARE markers, one-shot stub cleared (regression pin)", async () => {
+    // No `segment_index` → byte-for-byte the pre-W2 behavior: replace the bare
+    // placeholder, clear the stub. A stray `(part N)` marker in the body is
+    // left untouched (the bare path never targets part markers).
+    await store.createNote(
+      "# 🎙️ Voice memo\n\n_Transcript pending._\n\n_Transcript pending (part 2)._\n",
+      { id: "unseg-note", metadata: { transcribe_stub: true } },
+    );
+    seedAudio("memos/unseg.webm");
+    const att = await store.addAttachment("unseg-note", "memos/unseg.webm", "audio/webm", {
+      transcribe_status: "pending",
+    });
+
+    const worker = makeWorker({ fetchImpl: mkFetchMock([{ text: "bare transcript" }]) });
+    try { await worker.kick("default", att); } finally { await worker.stop(); }
+
+    const note = await store.getNote("unseg-note");
+    // Bare marker replaced; the part-2 marker is NOT touched by the bare path.
+    expect(note!.content).toBe(
+      "# 🎙️ Voice memo\n\nbare transcript\n\n_Transcript pending (part 2)._\n",
+    );
+    // One-shot stub cleared, exactly as today.
+    expect((note!.metadata as any)?.transcribe_stub).toBeUndefined();
+  });
+
+  test("malformed segment_index falls back to bare markers (contract: integer ≥ 0)", async () => {
+    // A non-integer / negative `segment_index` must NOT fabricate a `(part N)`
+    // marker — it degrades to the bare path (fully backward compatible).
+    await store.createNote(
+      "# 🎙️ Voice memo\n\n_Transcript pending._\n",
+      { id: "seg-bad", metadata: { transcribe_stub: true } },
+    );
+    seedAudio("memos/segbad.webm");
+    const att = await store.addAttachment("seg-bad", "memos/segbad.webm", "audio/webm", {
+      transcribe_status: "pending",
+      segment_index: -1, // invalid → bare path
+    });
+
+    const worker = makeWorker({ fetchImpl: mkFetchMock([{ text: "fallback transcript" }]) });
+    try { await worker.kick("default", att); } finally { await worker.stop(); }
+
+    const note = await store.getNote("seg-bad");
+    expect(note!.content).toBe("# 🎙️ Voice memo\n\nfallback transcript\n");
+    expect((note!.metadata as any)?.transcribe_stub).toBeUndefined();
+  });
+
+  test("segmented part whose marker was edited away → transcript appended (graceful fallback)", async () => {
+    // The user rewrote part 2's slot by hand, removing its pending marker.
+    // Mirror the un-segmented replace-or-append policy scoped to the part:
+    // with neither of part 2's markers present, append the transcript
+    // (no `(part N)` prefix) rather than destroying the user's edit.
+    const editedBody =
+      "# 🎙️ Voice memo\n\n" +
+      "_Transcript pending (part 1)._\n\n" +
+      "User rewrote part two by hand.\n";
+    await store.createNote(editedBody, { id: "seg-edit", metadata: { transcribe_stub: true } });
+    seedAudio("memos/segedit.webm");
+    const seg1 = await store.addAttachment("seg-edit", "memos/segedit.webm", "audio/webm", {
+      transcribe_status: "pending",
+      segment_index: 1, // part 2
+    });
+
+    const worker = makeWorker({ fetchImpl: mkFetchMock([{ text: "the real part two" }]) });
+    try { await worker.kick("default", seg1); } finally { await worker.stop(); }
+
+    const note = await store.getNote("seg-edit");
+    // Part 2's transcript appended; the user's edit + part 1's pending slot
+    // both survive untouched.
+    expect(note!.content).toBe(`${editedBody}\n\nthe real part two`);
+    expect(note!.content).toContain("User rewrote part two by hand.");
+    expect(note!.content).toContain("_Transcript pending (part 1)._");
+    // Segmented → shared stub preserved (part 1 still needs the gate open).
+    expect((note!.metadata as any)?.transcribe_stub).toBe(true);
+  });
+});

package/src/transcription-worker.ts

@@ -64,41 +64,57 @@ import {
 } from "../core/src/transcription/provider.ts";
 import { ScribeHttpProvider } from "./transcription/providers/scribe-http.ts";
 
-/** Placeholder pattern written by the voice-memo capture stub. */
-const TRANSCRIPT_PLACEHOLDER = /_Transcript pending\._/;
-
 /**
- * Body written when transcription reaches a terminal failure (maxAttempts
- * exhausted, or the audio file is missing). This used to be written by
- * Lens's now-removed scribe client; owning it here means a failed upload
- * stops reading "Transcript pending" forever regardless of which client
- * uploaded the audio.
+ * The in-body transcription markers.
+ *
+ * The BARE markers are the un-segmented default; voice W2 (segmented
+ * recordings) targets per-part variants built by `markersFor`. Both are a
+ * BYTE-EXACT cross-door + cross-repo contract — the cloud Workers-AI
+ * transcription path ships the identical strings, and the notes-ui status
+ * chip (parachute-surface TranscriptionStatus.tsx) keys off the failure
+ * marker's exact copy. Don't change any of this text without a coordinated
+ * change in both places. A friendlier "retry available" copy + chip
+ * affordance is a tracked parachute-surface follow-up.
  *
- * NOTE: the notes-ui status chip (parachute-surface TranscriptionStatus.tsx)
- * keys off this exact string, so don't change the copy without a coordinated
- * change there. A friendlier "retry available" copy + chip affordance is a
- * tracked parachute-surface follow-up.
+ * Owning the failure marker here (it used to be written by Lens's now-removed
+ * scribe client) means a failed upload stops reading "Transcript pending"
+ * forever regardless of which client uploaded the audio.
  */
-const TRANSCRIPT_UNAVAILABLE = "_Transcription unavailable._";
+const BARE_PENDING = "_Transcript pending._";
+const BARE_UNAVAILABLE = "_Transcription unavailable._";
+
+/** Escape a literal string for safe embedding in a `RegExp`. */
+function escapeRegExp(literal: string): string {
+  return literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 
 /**
- * On a successful (re)transcription of a legacy in-body memo, the transcript
- * replaces whichever marker is currently in the body — the original
- * `_Transcript pending._` on a first-try success, OR `_Transcription
- * unavailable._` if a prior attempt failed and we're now retrying. Matching
- * both means a retried success lands in the same spot a first-try success
- * would, preserving the surrounding capture body (the `![[memo]]` embed,
- * the `_Recorded …_` line, the header).
- *
- * Deliberately NO `/g` flag — `.replace` swaps only the FIRST match. A
- * canonical capture body holds exactly one marker, so first-match is the
- * correct target. `applyFailureMarker`'s includes-guard (no-op when the
- * marker is already present) prevents markers accumulating across repeated
- * terminal failures, so the body never carries two of the same marker. A
- * hand-edited body that somehow contains both markers patches only the
- * first — accepted (degenerate, operator-induced).
+ * The pending + terminal-failure markers for an attachment, honoring
+ * `segment_index` (voice W2 — segmented recordings). `undefined` yields the
+ * bare markers (fully backward compatible — un-segmented flows are byte-
+ * unchanged). An integer ≥ 0 yields this part's markers, with the human-
+ * facing part number N = segment_index + 1 (1-based, decimal):
+ *   `_Transcript pending (part N)._` / `_Transcription unavailable (part N)._`
  */
-const TRANSCRIPT_SUCCESS_TARGET = /_Transcript pending\._|_Transcription unavailable\._/;
+function markersFor(segmentIndex: number | undefined): { pending: string; unavailable: string } {
+  if (segmentIndex === undefined) return { pending: BARE_PENDING, unavailable: BARE_UNAVAILABLE };
+  const n = segmentIndex + 1;
+  return {
+    pending: `_Transcript pending (part ${n})._`,
+    unavailable: `_Transcription unavailable (part ${n})._`,
+  };
+}
+
+/**
+ * A valid segment index (integer ≥ 0) off attachment metadata, else
+ * `undefined` — the un-segmented path. Client-set at link time; anything that
+ * isn't a non-negative integer falls back to the bare markers rather than
+ * fabricating a `(part N)`.
+ */
+function segmentIndexOf(meta: { segment_index?: unknown }): number | undefined {
+  const raw = meta.segment_index;
+  return typeof raw === "number" && Number.isInteger(raw) && raw >= 0 ? raw : undefined;
+}
 
 /**
  * Default sweep cadence (ms). The sweep is the safety net for backoff-
@@ -195,6 +211,14 @@ interface PendingMeta {
    * worker preserves the original stub-patching behavior (Lens flow).
    */
   transcribe_origin?: "auto" | "legacy";
+  /**
+   * Voice W2 (segmented recordings): a client-set 0-based index marking this
+   * attachment as one segment of a longer recording sliced into ~10-min parts,
+   * all linked on ONE note. When present, the legacy in-body path targets this
+   * part's markers (`… (part N)._`, N = segment_index + 1) rather than the bare
+   * ones — making per-part ordering structurally guaranteed. See `markersFor`.
+   */
+  segment_index?: number;
   [k: string]: unknown;
 }
 
@@ -357,17 +381,28 @@ export function startTranscriptionWorker(opts: TranscriptionWorkerOpts): Transcr
    * attachment failure we're trying to record.
    *
    * Body policy (finding F — never destroy content):
-   *   - Placeholder PRESENT → surgical replace of `_Transcript pending._`
-   *     with the marker. The `![[memo]]` embed + any surrounding text survive.
-   *   - Marker ALREADY PRESENT → no-op (idempotent; a double-terminal-failure
-   *     must not stack markers).
-   *   - Otherwise (placeholder absent — the user edited the note while it was
-   *     pending) → APPEND `\n\n` + marker to the existing content. The old
-   *     code full-replaced the body here, destroying the embed AND the user's
-   *     edits. We append instead so nothing is lost. If the content is empty,
-   *     the marker alone becomes the body (avoids a leading blank line).
+   *   - Pending marker PRESENT → surgical replace of the pending marker with
+   *     the failure marker. The `![[memo]]` embed + any surrounding text
+   *     survive. For a segmented attachment (`segment_index` set) this is the
+   *     per-part `_Transcript pending (part N)._`; otherwise the bare marker.
+   *   - Failure marker ALREADY PRESENT → no-op (idempotent; a double-terminal-
+   *     failure must not stack markers).
+   *   - Otherwise (pending marker absent — the user edited the note while it
+   *     was pending) → APPEND `\n\n` + failure marker to the existing content.
+   *     The old code full-replaced the body here, destroying the embed AND the
+   *     user's edits. We append instead so nothing is lost. If the content is
+   *     empty, the marker alone becomes the body (avoids a leading blank line).
    */
-  async function applyFailureMarker(store: Store, noteId: string): Promise<void> {
+  async function applyFailureMarker(
+    store: Store,
+    noteId: string,
+    segmentIndex: number | undefined,
+  ): Promise<void> {
+    // Bare markers by default; this segment's `(part N)` markers when the
+    // attachment carries a `segment_index` (voice W2). String-search replace
+    // targets the FIRST occurrence (a canonical body holds exactly one), and
+    // the includes-guard below keeps a repeated terminal failure from stacking.
+    const { pending, unavailable } = markersFor(segmentIndex);
     // OC-guarded (vault#435): the read-transform-write below is re-run against
     // fresh content on a conflict so a concurrent user edit isn't clobbered.
     // The transform is pure w.r.t. the note it's handed; the stub-set and
@@ -381,17 +416,24 @@ export function startTranscriptionWorker(opts: TranscriptionWorkerOpts): Transcr
         if (noteMeta.transcribe_stub !== true) return null;
 
         let body: string;
-        if (TRANSCRIPT_PLACEHOLDER.test(note.content)) {
-          body = note.content.replace(TRANSCRIPT_PLACEHOLDER, TRANSCRIPT_UNAVAILABLE);
-        } else if (note.content.includes(TRANSCRIPT_UNAVAILABLE)) {
+        if (note.content.includes(pending)) {
+          // Function replacer so the search string is treated literally and the
+          // (fixed) failure marker is inserted verbatim.
+          body = note.content.replace(pending, () => unavailable);
+        } else if (note.content.includes(unavailable)) {
           // Marker already present — nothing to do. Clear the stub and
           // return without rewriting the body so we don't stack markers.
           body = note.content;
         } else {
           body = note.content.length > 0
-            ? `${note.content}\n\n${TRANSCRIPT_UNAVAILABLE}`
-            : TRANSCRIPT_UNAVAILABLE;
+            ? `${note.content}\n\n${unavailable}`
+            : unavailable;
         }
+        // Segmented: the stub is SHARED across this note's parts — keep it set
+        // so sibling parts still resolve their own slots. Return content only
+        // (leave note metadata untouched). Un-segmented: clear the one-shot
+        // stub as before (byte-unchanged).
+        if (segmentIndex !== undefined) return { content: body };
         const { transcribe_stub: _drop, ...restMeta } = noteMeta;
         return { content: body, metadata: restMeta };
       },
@@ -449,6 +491,12 @@ export function startTranscriptionWorker(opts: TranscriptionWorkerOpts): Transcr
     // vs. the legacy stub-patching path (Lens flow). Auto-write notes also
     // surface failures so the user can retry from the transcript note.
     const isAutoOrigin = meta.transcribe_origin === "auto";
+    // Voice W2: when this attachment is one segment of a longer recording
+    // (client-set `segment_index`), the legacy in-body path targets this
+    // part's markers instead of the bare ones. Undefined for un-segmented
+    // attachments — byte-unchanged behavior. Only the legacy path consults it;
+    // the auto/transcript-note path is untouched (segments are a memo concern).
+    const segmentIndex = segmentIndexOf(meta);
 
     // Honor backoff — we re-check here in case another tick queued this
     // attachment between the listing and now.
@@ -469,7 +517,7 @@ export function startTranscriptionWorker(opts: TranscriptionWorkerOpts): Transcr
       if (isAutoOrigin) {
         await writeFailureTranscriptNote(store, attachment, "audio file not found", undefined, undefined);
       } else {
-        await applyFailureMarker(store, attachment.noteId);
+        await applyFailureMarker(store, attachment.noteId, segmentIndex);
       }
       return;
     }
@@ -527,7 +575,7 @@ export function startTranscriptionWorker(opts: TranscriptionWorkerOpts): Transcr
         if (isAutoOrigin) {
           await writeFailureTranscriptNote(store, attachment, errMsg, apiErr?.code, undefined);
         } else {
-          await applyFailureMarker(store, attachment.noteId);
+          await applyFailureMarker(store, attachment.noteId, segmentIndex);
         }
         // retention=never drops the audio on any terminal state, including
         // failure. The user opted in to "I don't want the audio kept around
@@ -578,6 +626,16 @@ export function startTranscriptionWorker(opts: TranscriptionWorkerOpts): Transcr
       // before the transcript arrives opts out of the overwrite. OC-guarded
       // (vault#435): re-applied against fresh content on a conflict so a
       // concurrent user edit isn't clobbered.
+      //
+      // Success replaces whichever of THIS part's markers is present (bare, or
+      // `(part N)` when segmented). Built with no `/g` flag so `.replace`
+      // swaps only the FIRST match — a canonical capture body holds exactly
+      // one marker per part; alternation preserves positional-first semantics
+      // (a retried success replaces the failure marker where a first-try
+      // success replaced the pending one) so byte-for-byte matching today's
+      // un-segmented behavior.
+      const { pending, unavailable } = markersFor(segmentIndex);
+      const successTarget = new RegExp(`${escapeRegExp(pending)}|${escapeRegExp(unavailable)}`);
       await applyNoteTransformWithOC(
         store,
         attachment.noteId,
@@ -586,28 +644,31 @@ export function startTranscriptionWorker(opts: TranscriptionWorkerOpts): Transcr
           const noteMeta = (note.metadata as Record<string, unknown> | undefined) ?? {};
           if (noteMeta.transcribe_stub !== true) return null;
           // Body policy (finding F — never destroy content):
-          //   - placeholder OR failure-marker present → surgical replace in
-          //     place (a retried success replaces the `_Transcription
-          //     unavailable._` marker, landing exactly where a first-try
-          //     success would). The embed + surrounding capture body survive.
+          //   - pending OR failure marker present → surgical replace in place.
+          //     The embed + surrounding capture body survive.
           //   - neither present (user edited the note while pending) → APPEND
           //     the transcript instead of full-replacing the body, so the
           //     user's edits + the `![[memo]]` embed are preserved. The old
           //     code full-replaced here, which destroyed both.
           let body: string;
-          if (TRANSCRIPT_SUCCESS_TARGET.test(note.content)) {
+          if (successTarget.test(note.content)) {
             // Function replacer, NOT a string — speech-to-text is arbitrary
             // user content, and String.replace treats `$&`, `$\``, `$'`,
             // `$1`-`$9` as special patterns in a string replacement. A
             // transcript containing `$&` would otherwise inject the matched
             // marker text into the body. `() => transcript` returns the text
             // verbatim.
-            body = note.content.replace(TRANSCRIPT_SUCCESS_TARGET, () => transcript);
+            body = note.content.replace(successTarget, () => transcript);
           } else {
             body = note.content.length > 0
               ? `${note.content}\n\n${transcript}`
               : transcript;
           }
+          // Segmented: the stub is SHARED across this note's parts — keep it
+          // set so sibling parts still resolve their own slots. Return content
+          // only (leave note metadata untouched). Un-segmented: clear the
+          // one-shot stub as before (byte-unchanged).
+          if (segmentIndex !== undefined) return { content: body };
           const { transcribe_stub: _drop, ...restMeta } = noteMeta;
           return { content: body, metadata: restMeta };
         },