@openparachute/vault 0.5.1-rc.2 → 0.5.2-rc.1

package/src/routes.ts

@@ -13,11 +13,13 @@
 
 import type { Store, Note } from "../core/src/types.ts";
 import { listUnresolvedWikilinks } from "../core/src/wikilinks.ts";
-import { toNoteIndex, filterMetadata, MAX_BATCH_SIZE, validateExtension, ExtensionValidationError } from "../core/src/notes.ts";
+import { getNote, toNoteIndex, filterMetadata, MAX_BATCH_SIZE, validateExtension, ExtensionValidationError } from "../core/src/notes.ts";
 import { attachValidationStatus } from "../core/src/mcp.ts";
 import * as linkOps from "../core/src/links.ts";
 import * as tagSchemaOps from "../core/src/tag-schemas.ts";
 import {
+  buildExpandVisibility,
+  filterHydratedLinksByTagScope,
   filterNotesByTagScope,
   noteWithinTagScope,
   tagScopeForbidden,
@@ -44,8 +46,16 @@ import {
 } from "../core/src/expand.ts";
 import { join, extname, normalize } from "path";
 import { existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "fs";
-import { vaultDir } from "./config.ts";
+import { assetsDir } from "./config.ts";
 import { shouldAutoTranscribe } from "./auto-transcribe.ts";
+// usage.ts imports `assetsDir` from config.ts (neutral ground), so this import
+// of invalidateUsageCache does NOT form a cycle — routes.ts → usage.ts only.
+import { invalidateUsageCache } from "./usage.ts";
+
+// Re-export `assetsDir` (now defined in config.ts) so the existing callers
+// that import it from this module — mirror-deps, mirror-routes, server,
+// triggers, cli — keep working unchanged.
+export { assetsDir };
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -71,6 +81,22 @@ function parseQuery(url: URL, key: string): string | null {
   return url.searchParams.get(key);
 }
 
+/**
+ * Parse `link_count_direction` (vault feedback #4). Defaults to "both";
+ * anything other than the three known values falls back to "both" so a
+ * typo silently degrades to the documented default rather than erroring.
+ *
+ * Tag-scope note (symmetric with the MCP param description): `linkCount`
+ * is a raw degree that MAY include edges to notes a tag-scoped token can't
+ * see — the tag-scope filter runs post-query, over the result notes, not
+ * their neighbors. Only the number leaks, not the neighbor.
+ */
+function parseLinkCountDirection(url: URL): "both" | "outbound" | "inbound" {
+  const v = url.searchParams.get("link_count_direction");
+  if (v === "outbound" || v === "inbound") return v;
+  return "both";
+}
+
 function parseQueryList(url: URL, key: string): string[] | undefined {
   const val = url.searchParams.get(key);
   return val ? val.split(",") : undefined;
@@ -353,6 +379,62 @@ function parseMetaBrackets(url: URL): {
   return result;
 }
 
+/**
+ * Parse the `?metadata=<json>` alias on GET /api/notes — the JSON-object form
+ * of the metadata filter, symmetric with the nested `metadata` object MCP
+ * forwards verbatim (`core/src/mcp.ts`). The value is a JSON object of the form
+ * `{"field":{"op":value}}` (operator query) or `{"field":value}` (shorthand
+ * equality via the engine's json_extract fallback).
+ *
+ * This exists because the bracket grammar (`?meta[field][op]=value`) couldn't
+ * see a `metadata=` param at all — it was silently dropped, and the query
+ * returned ALL tag-matching notes (a silent wrong result, not an error).
+ *
+ * We do NOT validate operators here — the parsed object lowers straight into
+ * `queryNotes`, where `validateOperatorObject` raises a loud 400 on unknown
+ * operators (caught by the QueryError handler in handleNotes). We only enforce
+ * that the param parses and is a non-null, non-array plain object; anything
+ * else is a malformed filter the engine can't consume.
+ *
+ * An empty object (`metadata={}`) carries no filter intent, so it's treated as
+ * absent: it sets no metadata filter AND doesn't trip the both-forms guard, so
+ * it composes harmlessly with bracket params.
+ *
+ * Returns `{ metadata?, error? }`. When `error` is set the caller returns it
+ * directly (already shaped as a 400 with `error` + `code`).
+ */
+function parseMetadataJsonAlias(url: URL): {
+  metadata?: Record<string, unknown>;
+  error?: Response;
+} {
+  const raw = parseQuery(url, "metadata");
+  if (raw === null) return {};
+
+  const malformed = (detail: string): Response =>
+    json(
+      {
+        error: `metadata query param must be a JSON object of the form {"field":{"op":value}} — ${detail}`,
+        code: "INVALID_QUERY",
+      },
+      400,
+    );
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    return { error: malformed(`failed to parse: ${e instanceof Error ? e.message : String(e)}`) };
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    const got = Array.isArray(parsed) ? "array" : parsed === null ? "null" : typeof parsed;
+    return { error: malformed(`got ${got}`) };
+  }
+  // Empty object → no filter intent. Return absent so it neither sets a
+  // metadata filter nor trips the both-forms guard in the handler.
+  if (Object.keys(parsed).length === 0) return {};
+  return { metadata: parsed as Record<string, unknown> };
+}
+
 /**
  * Parse include_metadata query param.
  * - absent/null → undefined (all metadata, default)
@@ -373,10 +455,20 @@ function parseIncludeMetadata(url: URL): boolean | string[] | undefined {
 /**
  * Parse expand_links/expand_depth/expand_mode from query params, returning
  * an (ExpandContext, depth) pair if expansion is requested, else null.
+ *
+ * `tagScope` (security review): when the caller is tag-scoped, an `isVisible`
+ * predicate is built from the SAME tag-scope allowlist the rest of the
+ * handler uses and injected into the expand context. The expander then
+ * leaves any `[[wikilink]]` whose target is out of scope UNRESOLVED — so
+ * `expand_links=true` can never inline out-of-scope note content (and the
+ * out-of-scope case is byte-indistinguishable from a missing target). For
+ * an unscoped token the predicate is `undefined` and expansion behaves
+ * exactly as before.
  */
 function parseExpandParams(
   url: URL,
   db: any,
+  tagScope: TagScopeCtx = NO_TAG_SCOPE,
 ): { ctx: ExpandContext; depth: number } | null {
   if (!parseBool(parseQuery(url, "expand_links"), false)) return null;
   const modeRaw = parseQuery(url, "expand_mode");
@@ -388,7 +480,8 @@ function parseExpandParams(
       MAX_EXPAND_DEPTH,
     ),
   );
-  return { ctx: { db, mode, expanded: new Set() }, depth };
+  const isVisible = buildExpandVisibility(tagScope.allowed, tagScope.raw);
+  return { ctx: { db, mode, expanded: new Set(), ...(isVisible ? { isVisible } : {}) }, depth };
 }
 
 
@@ -495,18 +588,30 @@ async function handleNotesInner(
         }
         const includeContent = parseBool(parseQuery(url, "include_content"), true);
         let result: any = includeContent ? { ...note } : toNoteIndex(note);
-        const expand = parseExpandParams(url, db);
+        const expand = parseExpandParams(url, db, tagScope);
         if (expand && includeContent && typeof result.content === "string") {
           expand.ctx.expanded.add(note.id);
           result.content = expandContent(result.content, expand.ctx, expand.depth);
         }
         result = filterMetadata(result, parseIncludeMetadata(url));
         if (parseBool(parseQuery(url, "include_links"), false)) {
-          result.links = linkOps.getLinksHydrated(db, note.id);
+          // Tag-scope: drop links whose neighbor is out of scope so the
+          // hydrated sourceNote/targetNote summaries can't leak out-of-scope
+          // ids/paths/tags. No-op for unscoped tokens.
+          result.links = filterHydratedLinksByTagScope(
+            linkOps.getLinksHydrated(db, note.id),
+            tagScope.allowed,
+            tagScope.raw,
+          );
         }
         if (parseBool(parseQuery(url, "include_attachments"), false)) {
           result.attachments = await store.getAttachments(note.id);
         }
+        // linkCount injected after filterMetadata on purpose — same as
+        // links/attachments above; filterMetadata only touches `metadata`.
+        if (parseBool(parseQuery(url, "include_link_count"), false)) {
+          result.linkCount = linkOps.getLinkCounts(db, [note.id], parseLinkCountDirection(url)).get(note.id) ?? 0;
+        }
         return json(result);
       }
 
@@ -537,7 +642,7 @@ async function handleNotesInner(
         const includeContent = parseBool(parseQuery(url, "include_content"), false);
         const inclMeta = parseIncludeMetadata(url);
         let output: any[] = includeContent ? results.map((n) => ({ ...n })) : results.map(toNoteIndex);
-        const expand = parseExpandParams(url, db);
+        const expand = parseExpandParams(url, db, tagScope);
         if (expand && includeContent) {
           for (const n of output) expand.ctx.expanded.add(n.id);
           for (const n of output) {
@@ -549,6 +654,18 @@ async function handleNotesInner(
         if (inclMeta !== undefined && inclMeta !== true) {
           output = output.map((n: any) => filterMetadata(n, inclMeta));
         }
+        // Opt-in link degree (vault feedback #4) — one batch count, same as
+        // the structured-query path. Runs AFTER filterMetadata on purpose
+        // (filterMetadata only touches `metadata`, so linkCount survives —
+        // don't casually swap the order).
+        if (parseBool(parseQuery(url, "include_link_count"), false)) {
+          const counts = linkOps.getLinkCounts(
+            db,
+            output.map((n: any) => n.id),
+            parseLinkCountDirection(url),
+          );
+          for (const n of output) n.linkCount = counts.get(n.id) ?? 0;
+        }
         return json(output);
       }
 
@@ -580,6 +697,27 @@ async function handleNotesInner(
       const tags = parseQueryList(url, "tag");
       const bracket = parseMetaBrackets(url);
       if (bracket.error) return bracket.error;
+      // `?metadata=<json>` alias — the JSON-object form of the metadata
+      // filter, symmetric with the nested object MCP forwards. Before this,
+      // a `metadata=` param was silently dropped (the bracket grammar never
+      // matched it), so the query returned ALL tag-matching notes.
+      const metadataAlias = parseMetadataJsonAlias(url);
+      if (metadataAlias.error) return metadataAlias.error;
+      // Reject "both forms" loudly. If a caller passes BOTH the JSON
+      // `metadata=` param AND any `meta[...]` bracket param, there's no
+      // well-defined merge and silently picking a winner is exactly the
+      // class of bug we're fixing. Symmetric with the mixed shorthand/
+      // operator rejection inside parseMetaBrackets. Guard stays narrow —
+      // only the named `metadata` param triggers it.
+      if (metadataAlias.metadata && bracket.metadata) {
+        return json(
+          {
+            error: "pass metadata filters as either the JSON `metadata=` param or bracket `meta[field][op]=` form, not both.",
+            code: "INVALID_QUERY",
+          },
+          400,
+        );
+      }
       // Opaque cursor for "since last checked" agent loops (vault#313).
       // When present, switches the response shape to {notes, next_cursor}
       // and routes through queryNotesPaged for keyset pagination. Mutually
@@ -612,7 +750,9 @@ async function handleNotesInner(
         // are present, so the filter is silently skipped on a plain
         // GET without the extension query.
         extension: parseExtensionFilter(url),
-        metadata: bracket.metadata,
+        // Bracket form and JSON-alias form are mutually exclusive (guarded
+        // above), so at most one of these is set.
+        metadata: bracket.metadata ?? metadataAlias.metadata,
         // Date-range precedence chain (highest to lowest):
         //   1. Bracket-style `meta[created_at][gte]=…` (canonical).
         //   2. Flat `date_field=…&date_from=…&date_to=…` (deprecated).
@@ -677,6 +817,15 @@ async function handleNotesInner(
         }
         const depth = Math.min(parseInt10(parseQuery(url, "near[depth]")) ?? 2, 5);
         const relationship = parseQuery(url, "near[relationship]") ?? undefined;
+        // Tag-scope policy for `near[]` (output-filter, not hop-guard): the
+        // BFS walks the FULL graph from the anchor, including out-of-scope
+        // intermediate hops, then the RESULT set is tag-scope-filtered below
+        // (`filterNotesByTagScope`). No out-of-scope content or ids leak —
+        // out-of-scope notes never survive into the response. This is
+        // ASYMMETRIC with `find-path`, which guards every hop (it returns the
+        // path itself, so an out-of-scope intermediary would be a leak there).
+        // The asymmetry is deliberate; tracked at vault#439 should we ever want
+        // `near[]` to also constrain traversal hops.
         const traversed = linkOps.traverseLinks(db, anchor.id, { max_depth: depth, relationship });
         const nearScope = new Set([anchor.id, ...traversed.map((t) => t.noteId)]);
         results = results.filter((n) => nearScope.has(n.id));
@@ -690,9 +839,10 @@ async function handleNotesInner(
       const includeContent = parseBool(parseQuery(url, "include_content"), false);
       const includeLinks = parseBool(parseQuery(url, "include_links"), false);
       const includeAttachments = parseBool(parseQuery(url, "include_attachments"), false);
+      const includeLinkCount = parseBool(parseQuery(url, "include_link_count"), false);
       const inclMeta = parseIncludeMetadata(url);
       let output: any[] = includeContent ? results.map((n) => ({ ...n })) : results.map(toNoteIndex);
-      const expand = parseExpandParams(url, db);
+      const expand = parseExpandParams(url, db, tagScope);
       if (expand && includeContent) {
         for (const n of output) expand.ctx.expanded.add(n.id);
         for (const n of output) {
@@ -704,6 +854,24 @@ async function handleNotesInner(
       if (inclMeta !== undefined && inclMeta !== true) {
         output = output.map((n: any) => filterMetadata(n, inclMeta));
       }
+      // Opt-in link degree (vault feedback #4). ONE batch count over all
+      // result ids — NOT a per-note query — so the field stays O(2 index
+      // scans) per request regardless of page size. Mutates `output` in
+      // place; injected on the same objects the enrichment loop below
+      // touches, the same way `links`/`attachments` are surfaced.
+      // Ordering: this runs AFTER the filterMetadata pass above on purpose —
+      // filterMetadata only touches the `metadata` key, so a linkCount
+      // injected here survives. Don't casually swap the order; injecting
+      // before filterMetadata would still survive today but couples the two
+      // to filterMetadata's current narrow behavior.
+      if (includeLinkCount) {
+        const counts = linkOps.getLinkCounts(
+          db,
+          output.map((n: any) => n.id),
+          parseLinkCountDirection(url),
+        );
+        for (const n of output) n.linkCount = counts.get(n.id) ?? 0;
+      }
 
       // Graph format — reshape into { nodes, edges }
       if (parseQuery(url, "format") === "graph") {
@@ -727,7 +895,14 @@ async function handleNotesInner(
         const enrichedOut: any[] = [];
         for (const n of output) {
           const enriched: any = { ...n };
-          if (includeLinks) enriched.links = linkOps.getLinksHydrated(db, n.id);
+          if (includeLinks) {
+            // Tag-scope: strip out-of-scope-neighbor links (no-op unscoped).
+            enriched.links = filterHydratedLinksByTagScope(
+              linkOps.getLinksHydrated(db, n.id),
+              tagScope.allowed,
+              tagScope.raw,
+            );
+          }
           if (includeAttachments) enriched.attachments = await store.getAttachments(n.id);
           enrichedOut.push(enriched);
         }
@@ -942,22 +1117,26 @@ async function handleNotesInner(
     return json({ error: "Method not allowed" }, 405);
   }
 
-  // POST /notes/:idOrPath/retry-transcription — vault#353 design Q5.
+  // POST /notes/:idOrPath/retry-transcription — vault#353 design Q5 + finding F.
   //
-  // Re-runs the auto-transcribe pipeline against the original audio
-  // attachment recorded in the transcript note's `transcript_attachment_id`
-  // frontmatter. Only valid on transcript notes (the target idOrPath must
-  // be a transcript note with `transcript_status: "failed"`); calling on
-  // anything else returns 400 with a clear reason.
+  // Re-runs transcription against a failed audio attachment. Two target
+  // shapes, dispatched in handleRetryTranscription by whether the note carries
+  // `transcript_status` frontmatter:
+  //   - Auto-flow (vault#353): target is a `<audio>.transcript.md` note with
+  //     `transcript_status: "failed"`; audio located via
+  //     `transcript_attachment_id`, origin preserved as "auto".
+  //   - Legacy in-body memo (finding F): target is the memo note itself (no
+  //     `transcript_status`); finds its own failed attachment, resets it
+  //     preserving `transcribe_origin: "legacy"`, and re-arms `transcribe_stub`.
   //
   // Wire shape:
   //   POST .../notes/<idOrPath>/retry-transcription
-  //   →  202 { attachment_id, transcript_path } when re-enqueued
-  //      400 invalid_target          (not a transcript note)
-  //      400 not_failed              (transcript already succeeded; nothing to retry)
-  //      404 attachment_missing      (transcript_attachment_id row deleted)
+  //   →  202 { attachment_id, attachment_path, transcript_note_id, worker }
+  //      400 not_failed              (auto-flow: transcript already succeeded)
+  //      400 missing_attachment_id   (auto-flow: transcript_attachment_id absent)
+  //      400 no_failed_attachment    (legacy: no failed audio attachment to retry)
+  //      404 attachment_missing      (auto-flow: transcript_attachment_id row deleted)
   //      404 audio_missing           (audio file unlinked from disk)
-  //      503 scribe_unavailable      (no worker configured this boot)
   if (sub === "/retry-transcription") {
     if (method !== "POST") return json({ error: "Method not allowed" }, 405);
     if (!vault) return json({ error: "Vault context required" }, 400);
@@ -980,18 +1159,26 @@ async function handleNotesInner(
     }
     const includeContent = parseBool(parseQuery(url, "include_content"), true);
     let result: any = includeContent ? { ...note } : toNoteIndex(note);
-    const expand = parseExpandParams(url, db);
+    const expand = parseExpandParams(url, db, tagScope);
     if (expand && includeContent && typeof result.content === "string") {
       expand.ctx.expanded.add(note.id);
       result.content = expandContent(result.content, expand.ctx, expand.depth);
     }
     result = filterMetadata(result, parseIncludeMetadata(url));
     if (parseBool(parseQuery(url, "include_links"), false)) {
-      result.links = linkOps.getLinksHydrated(db, note.id);
+      // Tag-scope: drop out-of-scope-neighbor links (no-op unscoped).
+      result.links = filterHydratedLinksByTagScope(
+        linkOps.getLinksHydrated(db, note.id),
+        tagScope.allowed,
+        tagScope.raw,
+      );
     }
     if (parseBool(parseQuery(url, "include_attachments"), false)) {
       result.attachments = await store.getAttachments(note.id);
     }
+    if (parseBool(parseQuery(url, "include_link_count"), false)) {
+      result.linkCount = linkOps.getLinkCounts(db, [note.id], parseLinkCountDirection(url)).get(note.id) ?? 0;
+    }
     return json(result);
   }
 
@@ -1256,7 +1443,27 @@ async function handleNotesInner(
       // `toNoteIndex` drops unknown fields).
       const updatedNote = await store.getNote(note.id);
       if (updatedNote === null) return json({ error: "Note disappeared" }, 404);
-      const validated = attachValidationStatus(store, db, updatedNote);
+      const validated: any = attachValidationStatus(store, db, updatedNote);
+      // Echo hydrated links when a link mutation was part of this request,
+      // OR the caller explicitly asked for them via `?include_links=true`
+      // (vault feedback #8). Previously the update response omitted links
+      // entirely (`getNote` populates tags but not links), forcing callers
+      // to re-GET with `?include_links=true` just to confirm a link they
+      // had just added/removed. Additive field, scoped to UPDATE: present
+      // only when mutated or requested. Mirrors the GET / query-notes
+      // hydration call form exactly (`linkOps.getLinksHydrated`).
+      const linkMutated = body.links?.add !== undefined || body.links?.remove !== undefined;
+      const includeLinksResp = linkMutated || parseBool(parseQuery(url, "include_links"), false);
+      if (includeLinksResp) {
+        // Tag-scope: strip out-of-scope-neighbor links from the echoed set
+        // (no-op unscoped). A write token tag-scoped to #work mustn't learn
+        // about a #personal note it happened to link to.
+        validated.links = filterHydratedLinksByTagScope(
+          linkOps.getLinksHydrated(db, updatedNote.id),
+          tagScope.allowed,
+          tagScope.raw,
+        );
+      }
       const includeContentResp = body.include_content !== false;
       // `created: false` is appended to every update-path response so
       // sync-loop callers using `if_missing: "create"` can distinguish
@@ -1266,6 +1473,9 @@ async function handleNotesInner(
       const lean: any = toNoteIndex(validated);
       const vs = (validated as any).validation_status;
       if (vs !== undefined) lean.validation_status = vs;
+      // Carry the link echo across the lean conversion — `toNoteIndex`
+      // drops unknown fields, same as the `validation_status` recipe above.
+      if (validated.links !== undefined) lean.links = validated.links;
       lean.created = false;
       return json(lean);
     } catch (e: any) {
@@ -1513,10 +1723,12 @@ export async function handleTags(
       parent_names?: unknown;
     };
 
-    // Validate relationships shape + cardinality vocabulary up front so
-    // a bad payload returns 400, not a thrown 500.
+    // Validate the relationships payload up front so a bad payload returns
+    // 400, not a thrown 500. `relationships` is an opaque vocabulary map
+    // (relationship-name → arbitrary JSON the app interprets); we only check
+    // that it's a JSON object (a map), then persist verbatim.
     let relationshipsPatch:
-      | Record<string, tagSchemaOps.TagRelationship>
+      | tagSchemaOps.TagRelationshipMap
       | null
       | undefined;
     if (body.relationships === null) {
@@ -1729,12 +1941,32 @@ export async function handleVault(
 // Unresolved wikilinks — REST-only (admin/maintenance)
 // ---------------------------------------------------------------------------
 
-export function handleUnresolvedWikilinks(req: Request, store: Store): Response {
+export function handleUnresolvedWikilinks(
+  req: Request,
+  store: Store,
+  tagScope: TagScopeCtx = NO_TAG_SCOPE,
+): Response {
   const url = new URL(req.url);
   const limitStr = url.searchParams.get("limit");
   const limit = limitStr ? parseInt(limitStr, 10) : 50;
   const db = (store as any).db;
-  return Response.json(listUnresolvedWikilinks(db, limit));
+  const result = listUnresolvedWikilinks(db, limit);
+
+  // Unscoped token → return as-is (unchanged behavior).
+  if (tagScope.raw === null) return Response.json(result);
+
+  // Tag-scope confidentiality (security review): each unresolved row carries
+  // a `source_id` (+ `source_path`) plus the raw `target_path` wikilink
+  // string. For a tag-scoped token, surface ONLY rows whose SOURCE note is
+  // within the token's tag scope — otherwise we'd leak out-of-scope note IDs
+  // and the wikilink target strings those notes contain. Filter the page and
+  // recompute `count` from the filtered set so the aggregate total of
+  // out-of-scope rows doesn't leak either.
+  const filtered = result.unresolved.filter((row) => {
+    const note = getNote(db, row.source_id);
+    return note !== null && noteWithinTagScope(note, tagScope.allowed, tagScope.raw);
+  });
+  return Response.json({ unresolved: filtered, count: filtered.length });
 }
 
 // ---------------------------------------------------------------------------
@@ -1923,21 +2155,35 @@ ${rendered}
 // ---------------------------------------------------------------------------
 
 /**
- * Re-enqueue the original audio attachment for a `transcript_status: failed`
- * transcript note. Steps:
+ * Re-enqueue the original audio attachment for a failed transcription.
  *
- *   1. Validate target is a transcript note (`transcript_status` set in
- *      metadata) AND that status is `failed`.
- *   2. Find the original audio attachment by id from
- *      `transcript_attachment_id` frontmatter. 404 if the row's gone.
- *   3. Validate the audio file still exists on disk (retention=keep is
- *      assumed by the retry contract; retention=until_transcribed unlinks
- *      only on success, retention=never unlinks on failure — that last one
- *      explicitly breaks retry, by design).
- *   4. Reset `transcribe_status = "pending"`, clear backoff + error fields.
- *      The auto-origin marker is preserved so the worker writes a transcript
- *      note (overwriting this one in place).
- *   5. Kick the worker if registered; otherwise the sweep picks it up.
+ * Two target shapes are accepted:
+ *
+ *   - **Auto-flow (vault#353):** the target is a `<audio>.transcript.md` note
+ *     carrying `transcript_status` frontmatter. Requires that status be
+ *     `failed`; locates the audio via `transcript_attachment_id`; preserves
+ *     `transcribe_origin: "auto"` so a retried success overwrites this
+ *     transcript note in place. Behavior is byte-identical to the original
+ *     vault#353 contract.
+ *
+ *   - **Legacy in-body memo (finding F):** the target is the memo note
+ *     itself — no `transcript_status` frontmatter. The original capture body
+ *     holds `![[<audio>]]` + a `_Transcription unavailable._` marker (written
+ *     by the worker on terminal failure). We find the note's own failed audio
+ *     attachment, reset it to pending **preserving `transcribe_origin:
+ *     "legacy"`** (forcing "auto" would switch to the sibling-transcript-note
+ *     shape and orphan the in-body embed), and **re-stamp `transcribe_stub:
+ *     true`** on the note. The stub re-arm is load-bearing: the legacy success
+ *     path early-returns unless `transcribe_stub === true`, so without it the
+ *     retried success would never write the transcript back into the body.
+ *     On success the worker replaces the `_Transcription unavailable._` marker
+ *     with the transcript in place, yielding the same final shape a first-try
+ *     success would.
+ *
+ * Common steps for both: validate the audio attachment row exists (404 if
+ * gone) and its file is still on disk (404 if unlinked — e.g. retention=never
+ * already dropped it), reset the transcribe_status fields, then kick the
+ * worker if registered (otherwise the sweep picks it up).
  */
 async function handleRetryTranscription(
   store: Store,
@@ -1945,15 +2191,13 @@ async function handleRetryTranscription(
   vault: string,
 ): Promise<Response> {
   const meta = (note.metadata as Record<string, unknown> | undefined) ?? {};
+
+  // Legacy in-body memo: no `transcript_status` frontmatter. The note owns
+  // the failed audio attachment directly; there's no sibling transcript note.
   if (typeof meta.transcript_status !== "string") {
-    return json(
-      {
-        error: "invalid_target",
-        message: "Target note is not a transcript note (no transcript_status frontmatter).",
-      },
-      400,
-    );
+    return handleRetryLegacyInBody(store, note, vault);
   }
+
   if (meta.transcript_status !== "failed") {
     return json(
       {
@@ -2040,13 +2284,171 @@ async function handleRetryTranscription(
   );
 }
 
+/**
+ * Retry path for a legacy in-body voice memo (finding F). The target note is
+ * the memo itself (no `transcript_status` frontmatter); it directly owns the
+ * audio attachment whose transcription failed.
+ *
+ * Steps:
+ *   1. Find the note's own audio attachment with `transcribe_status ===
+ *      "failed"`. 400 `no_failed_attachment` if none — there's nothing to
+ *      retry.
+ *   2. Validate the audio file is still on disk (404 `audio_missing`).
+ *   3. Reset the attachment to pending, **preserving `transcribe_origin:
+ *      "legacy"`** (never force "auto" — that switches to the sibling-
+ *      transcript-note shape and orphans the in-body `![[memo]]` embed).
+ *   4. **Re-stamp `transcribe_stub: true`** on the note. The legacy worker
+ *      success path early-returns unless the note carries this flag (it was
+ *      cleared when the failure marker was written), so re-arming it is what
+ *      lets the retried success replace the `_Transcription unavailable._`
+ *      marker with the transcript.
+ *   5. Kick the worker if registered; otherwise the sweep picks it up.
+ */
+async function handleRetryLegacyInBody(
+  store: Store,
+  note: Note,
+  vault: string,
+): Promise<Response> {
+  const attachments = await store.getAttachments(note.id);
+  const failed = attachments.find((a) => {
+    const m = (a.metadata as Record<string, unknown> | undefined) ?? {};
+    return m.transcribe_status === "failed";
+  });
+  if (!failed) {
+    return json(
+      {
+        error: "no_failed_attachment",
+        message:
+          "Target note is not a transcript note and has no audio attachment with a failed transcription to retry.",
+      },
+      400,
+    );
+  }
+
+  // Audio file existence + safety: defense-in-depth against a bad attachment
+  // row pointing outside the vault assets dir. Same guard as the worker.
+  const assetsRoot = assetsDir(vault);
+  const audioFilePath = normalize(join(assetsRoot, failed.path));
+  if (!audioFilePath.startsWith(normalize(assetsRoot)) || !existsSync(audioFilePath)) {
+    return json(
+      {
+        error: "audio_missing",
+        message: `Original audio file at "${failed.path}" no longer exists on disk.`,
+      },
+      404,
+    );
+  }
+
+  // Reset the attachment back to pending. Preserve `transcribe_origin:
+  // "legacy"` (a default of `undefined` is also legacy, but make it explicit
+  // so a retried row reads unambiguously) — forcing "auto" here would make
+  // the worker materialize a sibling transcript note instead of patching the
+  // in-body embed, orphaning the memo.
+  const attMeta = { ...(failed.metadata ?? {}) } as Record<string, unknown>;
+  attMeta.transcribe_status = "pending";
+  attMeta.transcribe_requested_at = new Date().toISOString();
+  attMeta.transcribe_origin = "legacy";
+  delete attMeta.transcribe_backoff_until;
+  delete attMeta.transcribe_error;
+  delete attMeta.transcribe_error_code;
+  delete attMeta.transcribe_attempts;
+  await store.setAttachmentMetadata(failed.id, attMeta);
+
+  // Re-arm the stub on the note. The worker's legacy success path gates on
+  // `transcribe_stub === true` and CLEARED it when it wrote the failure
+  // marker; without re-stamping it the retried success early-returns and
+  // never writes the transcript back into the body. Use skipUpdatedAt so the
+  // note's modification time still reflects user intent, matching the
+  // worker's own note writes.
+  //
+  // OC-guarded (vault#435): this read-transform-write would otherwise clobber
+  // a user edit landing between `resolveNote` (above) and this write. Thread
+  // `if_updated_at` and retry once on conflict — re-read, re-apply the
+  // metadata-only re-stamp against the fresh note, write with the fresh
+  // precondition. A second conflict surfaces as 409 so the user can retry.
+  // Only the `transcribe_stub` flag is stamped (never content), so re-applying
+  // against the fresh note is always the correct surgical transform.
+  const restampStub = (current: Note): Record<string, unknown> => ({
+    ...((current.metadata as Record<string, unknown> | undefined) ?? {}),
+    transcribe_stub: true,
+  });
+  try {
+    try {
+      await store.updateNote(note.id, {
+        metadata: restampStub(note),
+        skipUpdatedAt: true,
+        if_updated_at: note.updatedAt,
+      });
+    } catch (err: any) {
+      if (!err || err.code !== "CONFLICT") throw err;
+      // Conflict — re-read, re-apply the stub re-stamp, retry once.
+      const fresh = await store.getNote(note.id);
+      if (!fresh) {
+        return json(
+          { error: "note_missing", message: "Target note disappeared during retry." },
+          404,
+        );
+      }
+      await store.updateNote(fresh.id, {
+        metadata: restampStub(fresh),
+        skipUpdatedAt: true,
+        if_updated_at: fresh.updatedAt,
+      });
+    }
+  } catch (err: any) {
+    if (err && err.code === "CONFLICT") {
+      // Double conflict — the note kept changing under us. It's a user-facing
+      // request; return 409 so the caller can retry against fresh state. The
+      // attachment was already reset to pending above; a successful re-stamp
+      // on the user's next retry (or the next sweep, if they re-arm the stub)
+      // will let the worker patch the transcript in.
+      return json(
+        {
+          error_type: "conflict",
+          error: "conflict",
+          note_id: note.id,
+          current_updated_at: err.current_updated_at ?? null,
+          your_updated_at: err.expected_updated_at,
+          // Mirror the standard PATCH 409 shape (see the notes-update handler
+          // above) — both `your_updated_at` and `expected_updated_at` carry the
+          // same value, kept for shape-congruence with existing callers.
+          expected_updated_at: err.expected_updated_at,
+          message:
+            "Note was modified concurrently while arming the retry; re-fetch and try again.",
+        },
+        409,
+      );
+    }
+    throw err;
+  }
+
+  const { getTranscriptionWorker } = await import("./transcription-registry.ts");
+  const worker = getTranscriptionWorker();
+  if (worker) {
+    const fresh = await store.getAttachment(failed.id) ?? failed;
+    void worker.kick(vault, fresh);
+  }
+
+  return json(
+    {
+      status: "queued",
+      attachment_id: failed.id,
+      attachment_path: failed.path,
+      transcript_note_id: note.id,
+      worker: worker ? "kicked" : "sweep-only",
+    },
+    202,
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Storage (file upload/serve) — kept as-is, Daily needs it
+//
+// `assetsDir` moved to config.ts (next to the other path helpers) to break the
+// usage.ts↔routes.ts import cycle; it's re-exported from this module's top so
+// existing importers are unaffected.
 // ---------------------------------------------------------------------------
 
-export function assetsDir(vault: string): string {
-  return process.env.ASSETS_DIR ?? join(vaultDir(vault), "assets");
-}
 const MAX_UPLOAD_BYTES = 100 * 1024 * 1024; // 100MB
 
 // Storage allowlist policy:
@@ -2112,10 +2514,41 @@ export async function handleStorage(
     const relativePath = `${date}/${filename}`;
     const mimeType = MIME_TYPES[ext] ?? "application/octet-stream";
 
+    // Invalidate the usage dir-walk cache for this vault — the new attachment
+    // changed the assets-directory footprint, so the next /.parachute/usage
+    // read must re-walk rather than report a stale (smaller) number. Without
+    // this hook the cache's 60s TTL would briefly under-report after an
+    // upload. (usage.ts:invalidateUsageCache is a no-op-cheap map delete.)
+    invalidateUsageCache(vault);
+
     return json({ path: relativePath, size: buffer.length, mimeType }, 201);
   }
 
-  const fileMatch = path.match(/^\/([^/]+)\/(.+)$/);
+  // Decode percent-encoding BEFORE matching. `path` arrives from
+  // `url.pathname`, which (per WHATWG) keeps an encoded `%2F` slash literal —
+  // so a caller requesting `/api/storage/<date>%2F<file>` would never satisfy
+  // the literal-slash match below and would fall through to the 404. Decoding
+  // first accepts both the literal-slash and `%2F`-encoded forms, and yields
+  // the literal-slash path that the DB stores (`${date}/${filename}`) so the
+  // tag-scope reverse-lookup matches. This intentionally diverges from the
+  // single-note routes, which decode their *first* segment only and therefore
+  // REQUIRE `%2F` for slashes-in-an-id — a trap-grade asymmetry we accept here
+  // because storage paths are always multi-segment date/file pairs.
+  //
+  // Guard-safety (verified): the traversal guard below operates on the
+  // post-`normalize(join())` filesystem path, so a decoded `..` is still
+  // caught → 403. Decode is idempotent for today's unencoded callers
+  // (filenames are `<Date.now()>-<uuid>.<ext>` — no stray `%`). A malformed
+  // `%` (e.g. `2026%2`) throws → 404, consistent with the no-existence-oracle
+  // stance (and an improvement over the prior catch-all 500).
+  let decodedPath: string;
+  try {
+    decodedPath = decodeURIComponent(path);
+  } catch {
+    return json({ error: "Not found" }, 404);
+  }
+
+  const fileMatch = decodedPath.match(/^\/([^/]+)\/(.+)$/);
   if (req.method === "GET" && fileMatch) {
     const reqPath = `${fileMatch[1]}/${fileMatch[2]}`;
     const filePath = normalize(join(assets, reqPath));