@openparachute/vault 0.4.7-rc.2 → 0.4.8-rc.6

package/src/transcription-worker.ts

@@ -54,6 +54,7 @@ import type { Store, Attachment } from "../core/src/types.ts";
 import type { HookRegistry } from "../core/src/hooks.ts";
 import { appendContextPart, fetchContextEntries, type ContextPayload } from "./context.ts";
 import type { TriggerIncludeContext } from "./config.ts";
+import { upsertTranscriptNote } from "./transcript-note.ts";
 
 /** Placeholder pattern written by Lens's voice-memo stub. */
 const TRANSCRIPT_PLACEHOLDER = /_Transcript pending\._/;
@@ -139,9 +140,38 @@ interface PendingMeta {
   transcribe_error?: string;
   transcript?: string;
   transcribe_done_at?: string;
+  /**
+   * Marker stamped by the attachment-write code path (vault#353) when the
+   * audio attachment was queued via the auto-transcribe pipeline (mime-type
+   * matched `audio/*` AND `autoTranscribe.enabled === true`). When set to
+   * `"auto"`, the worker materializes a `<attachment-path>.transcript.md`
+   * note on terminal states (success OR failure) so the transcript surface
+   * is uniform regardless of outcome. Absent or set to `"legacy"`, the
+   * worker preserves the original stub-patching behavior (Lens flow).
+   */
+  transcribe_origin?: "auto" | "legacy";
   [k: string]: unknown;
 }
 
+/**
+ * Structured error thrown when scribe returns a 4xx with a recognized
+ * `error_code` — we surface the code on the transcript note's frontmatter
+ * so callers can branch on stable strings instead of regex-matching message
+ * text. Today the canonical code is `missing_provider` (scribe#47).
+ */
+class ScribeApiError extends Error {
+  readonly errorCode?: string;
+  readonly httpStatus: number;
+  readonly retriable: boolean;
+  constructor(message: string, opts: { errorCode?: string; httpStatus: number; retriable: boolean }) {
+    super(message);
+    this.name = "ScribeApiError";
+    this.errorCode = opts.errorCode;
+    this.httpStatus = opts.httpStatus;
+    this.retriable = opts.retriable;
+  }
+}
+
 /**
  * Start the worker loop. Returns a handle with `stop()` + `tick()`.
  * Tests should build the worker and call `tick()` directly; production
@@ -216,6 +246,38 @@ export function startTranscriptionWorker(opts: TranscriptionWorkerOpts): Transcr
     }
   }
 
+  /**
+   * On a terminal failure for an attachment with `transcribe_origin: "auto"`,
+   * write (or update) a `<attachment-path>.transcript.md` note with
+   * `transcript_status: failed` so the user has a queryable record of the
+   * failure and a target for the retry endpoint. Best-effort: any error
+   * materializing the transcript note is logged, never propagated — the
+   * attachment metadata write is the durable record of failure.
+   */
+  async function writeFailureTranscriptNote(
+    store: Store,
+    attachment: Attachment,
+    errMsg: string,
+    errorCode: string | undefined,
+    durationMs: number | undefined,
+  ): Promise<void> {
+    try {
+      await upsertTranscriptNote(store, {
+        attachmentPath: attachment.path,
+        attachmentId: attachment.id,
+        attachmentNoteId: attachment.noteId,
+        status: "failed",
+        error: errorCode ? `${errorCode}: ${errMsg}` : errMsg,
+        durationMs,
+      });
+    } catch (err) {
+      logger.error(
+        `[transcribe] failed to write failure transcript note for attachment ${attachment.id}:`,
+        err,
+      );
+    }
+  }
+
   async function processOneLocked(vault: string, attachment: Attachment): Promise<void> {
     const store = opts.getStore(vault);
     // Re-read metadata — the in-memory `attachment` may be stale (the hook
@@ -226,6 +288,10 @@ export function startTranscriptionWorker(opts: TranscriptionWorkerOpts): Transcr
     if (meta.transcribe_status !== "pending") return;
 
     const attempts = (meta.transcribe_attempts as number | undefined) ?? 0;
+    // Whether to materialize a transcript note (vault#353 auto-transcribe path)
+    // 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";
 
     // Honor backoff — we re-check here in case another tick queued this
     // attachment between the listing and now.
@@ -243,7 +309,11 @@ export function startTranscriptionWorker(opts: TranscriptionWorkerOpts): Transcr
         transcribe_status: "failed",
         transcribe_error: "audio file not found",
       });
-      await applyFailureMarker(store, attachment.noteId);
+      if (isAutoOrigin) {
+        await writeFailureTranscriptNote(store, attachment, "audio file not found", undefined, undefined);
+      } else {
+        await applyFailureMarker(store, attachment.noteId);
+      }
       return;
     }
 
@@ -256,9 +326,9 @@ export function startTranscriptionWorker(opts: TranscriptionWorkerOpts): Transcr
       context = await fetchContextEntries(store, predicates, logger);
     }
 
-    let transcript: string;
+    let scribeResult: { text: string; durationMs: number };
     try {
-      transcript = await callScribe({
+      scribeResult = await callScribe({
         url: opts.scribeUrl,
         token: opts.scribeToken,
         filePath,
@@ -269,17 +339,34 @@ export function startTranscriptionWorker(opts: TranscriptionWorkerOpts): Transcr
         fetchImpl,
       });
     } catch (err) {
-      const nextAttempts = attempts + 1;
       const errMsg = err instanceof Error ? err.message : String(err);
-      if (nextAttempts >= maxAttempts) {
-        logger.error(`[transcribe] giving up on attachment ${attachment.id} after ${nextAttempts} attempts:`, errMsg);
+      const apiErr = err instanceof ScribeApiError ? err : null;
+      // 4xx with structured error code → terminal immediately. Re-POSTing the
+      // same audio at a scribe with no provider configured (or that rejects
+      // our bearer) will keep failing — the operator has to act, retries don't
+      // help. This is the "graceful first-boot path" from design Q5.
+      const nonRetriable = apiErr !== null && !apiErr.retriable;
+      const nextAttempts = attempts + 1;
+      const terminal = nonRetriable || nextAttempts >= maxAttempts;
+
+      if (terminal) {
+        if (nonRetriable) {
+          logger.error(`[transcribe] non-retriable scribe error on attachment ${attachment.id} (status ${apiErr!.httpStatus}${apiErr!.errorCode ? `, ${apiErr!.errorCode}` : ""}):`, errMsg);
+        } else {
+          logger.error(`[transcribe] giving up on attachment ${attachment.id} after ${nextAttempts} attempts:`, errMsg);
+        }
         await store.setAttachmentMetadata(attachment.id, {
           ...meta,
           transcribe_status: "failed",
           transcribe_attempts: nextAttempts,
           transcribe_error: errMsg,
+          ...(apiErr?.errorCode ? { transcribe_error_code: apiErr.errorCode } : {}),
         });
-        await applyFailureMarker(store, attachment.noteId);
+        if (isAutoOrigin) {
+          await writeFailureTranscriptNote(store, attachment, errMsg, apiErr?.errorCode, undefined);
+        } else {
+          await applyFailureMarker(store, attachment.noteId);
+        }
         // retention=never drops the audio on any terminal state, including
         // failure. The user opted in to "I don't want the audio kept around
         // regardless of outcome" — honor it.
@@ -302,23 +389,46 @@ export function startTranscriptionWorker(opts: TranscriptionWorkerOpts): Transcr
       return;
     }
 
-    // Success. Apply to note if the caller still wants us to.
-    const note = await store.getNote(attachment.noteId);
-    if (note) {
-      const noteMeta = (note.metadata as Record<string, unknown> | undefined) ?? {};
-      if (noteMeta.transcribe_stub === true) {
-        const body = TRANSCRIPT_PLACEHOLDER.test(note.content)
-          ? note.content.replace(TRANSCRIPT_PLACEHOLDER, transcript)
-          : transcript;
-        const { transcribe_stub: _drop, ...restMeta } = noteMeta;
-        try {
-          await store.updateNote(note.id, {
-            content: body,
-            metadata: restMeta,
-            skipUpdatedAt: true,
-          });
-        } catch (err) {
-          logger.error(`[transcribe] failed to apply transcript to note ${note.id}:`, err);
+    const { text: transcript, durationMs } = scribeResult;
+
+    // Auto-origin success: materialize the transcript note (vault#353). The
+    // note's path is `<attachment-path>.transcript.md`, its frontmatter links
+    // back to the audio attachment via `transcript_of`.
+    if (isAutoOrigin) {
+      try {
+        await upsertTranscriptNote(store, {
+          attachmentPath: attachment.path,
+          attachmentId: attachment.id,
+          attachmentNoteId: attachment.noteId,
+          status: "complete",
+          text: transcript,
+          durationMs,
+        });
+      } catch (err) {
+        // Note write failure doesn't invalidate the transcript — it's still
+        // stored on the attachment row below. Log + continue so retention
+        // still applies and the attachment row reflects success.
+        logger.error(`[transcribe] failed to write transcript note for attachment ${attachment.id}:`, err);
+      }
+    } else {
+      // Legacy stub-patching path (Lens voice memo flow).
+      const note = await store.getNote(attachment.noteId);
+      if (note) {
+        const noteMeta = (note.metadata as Record<string, unknown> | undefined) ?? {};
+        if (noteMeta.transcribe_stub === true) {
+          const body = TRANSCRIPT_PLACEHOLDER.test(note.content)
+            ? note.content.replace(TRANSCRIPT_PLACEHOLDER, transcript)
+            : transcript;
+          const { transcribe_stub: _drop, ...restMeta } = noteMeta;
+          try {
+            await store.updateNote(note.id, {
+              content: body,
+              metadata: restMeta,
+              skipUpdatedAt: true,
+            });
+          } catch (err) {
+            logger.error(`[transcribe] failed to apply transcript to note ${note.id}:`, err);
+          }
         }
       }
     }
@@ -330,10 +440,12 @@ export function startTranscriptionWorker(opts: TranscriptionWorkerOpts): Transcr
       transcribe_status: "done",
       transcribe_attempts: attempts + 1,
       transcribe_done_at: new Date().toISOString(),
+      transcribe_duration_ms: durationMs,
       transcript,
     };
     delete doneMeta.transcribe_backoff_until;
     delete doneMeta.transcribe_error;
+    delete doneMeta.transcribe_error_code;
     await store.setAttachmentMetadata(attachment.id, doneMeta);
 
     // Retention: drop the file but keep the row so the transcript stays
@@ -458,6 +570,24 @@ export function registerTranscriptionHook(
   });
 }
 
+/**
+ * Call scribe's `POST /v1/audio/transcriptions` with the audio file + optional
+ * context part. Returns the transcript text plus the wall-clock duration of
+ * the request, so the worker can surface `transcript_duration_ms` on the
+ * transcript note.
+ *
+ * Failure modes (encoded as throws):
+ *   - 4xx with a JSON body carrying `error_code`: throws `ScribeApiError`
+ *     with the code (`missing_provider` etc.). Treated as a non-retriable
+ *     terminal failure — re-POSTing the same audio at the same broken scribe
+ *     would just fail the same way; the operator has to act.
+ *   - 4xx without `error_code` (auth, malformed multipart): throws
+ *     `ScribeApiError` with the body text. Non-retriable.
+ *   - 5xx, network error, or timeout: throws a plain `Error`. Retriable —
+ *     the worker's backoff path picks it up.
+ *   - 200 with missing/invalid `text` field: throws a plain `Error`.
+ *     Retriable (could be a transient provider-output glitch).
+ */
 async function callScribe(args: {
   url: string;
   token?: string;
@@ -467,9 +597,10 @@ async function callScribe(args: {
   context: ContextPayload | null;
   timeoutMs: number;
   fetchImpl: typeof fetch;
-}): Promise<string> {
+}): Promise<{ text: string; durationMs: number }> {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), args.timeoutMs);
+  const startedAt = Date.now();
   try {
     const fileBuffer = readFileSync(args.filePath);
     const file = new File([fileBuffer], args.filename, { type: args.mimeType });
@@ -488,14 +619,42 @@ async function callScribe(args: {
       signal: controller.signal,
     });
     if (!resp.ok) {
-      throw new Error(`scribe returned ${resp.status}: ${await resp.text().catch(() => "")}`);
+      const body = await resp.text().catch(() => "");
+      // Try to extract structured error_code from JSON body (scribe#47).
+      let errorCode: string | undefined;
+      let errorMessage: string | undefined;
+      try {
+        const parsed = JSON.parse(body) as { error?: string; error_code?: string; message?: string };
+        if (typeof parsed.error_code === "string") errorCode = parsed.error_code;
+        if (typeof parsed.error === "string") errorMessage = parsed.error;
+        else if (typeof parsed.message === "string") errorMessage = parsed.message;
+      } catch {
+        // Not JSON — leave errorCode undefined; the raw body becomes the message.
+      }
+      // 4xx is terminal (re-POSTing the same audio at the same broken scribe
+      // will just fail again). 5xx is retriable — provider hiccup, will likely
+      // succeed on backoff.
+      const retriable = resp.status >= 500;
+      const message = errorMessage
+        ?? (errorCode ? `scribe ${errorCode}` : `scribe returned ${resp.status}: ${body}`);
+      throw new ScribeApiError(message, {
+        errorCode,
+        httpStatus: resp.status,
+        retriable,
+      });
     }
     const result = await resp.json() as { text?: string };
     if (typeof result.text !== "string") {
       throw new Error("scribe response missing text field");
     }
-    return result.text;
+    return { text: result.text, durationMs: Date.now() - startedAt };
   } finally {
     clearTimeout(timer);
   }
 }
+
+/**
+ * Re-export the structured error type so tests + callers can `instanceof`-check
+ * for terminal-failure semantics.
+ */
+export { ScribeApiError };

package/src/vault.test.ts

@@ -1575,6 +1575,177 @@ describe("HTTP /notes", async () => {
     expect(body.map((n) => n.content)).toEqual(["modified"]);
   });
 
+  // ---- Cursor pagination (vault#313) ----
+  //
+  // Opaque cursors for since-last-checked agent loops. The full engine
+  // semantics live in core.test.ts; these tests pin the HTTP plumbing:
+  // wrapped {notes, next_cursor} envelope when ?cursor= is set, structured
+  // 400s on bad cursor, and end-to-end resume across calls.
+  test("GET /notes?cursor=... returns {notes, next_cursor} envelope", async () => {
+    await store.createNote("a", { id: "cur-rest-a" });
+    await store.createNote("b", { id: "cur-rest-b" });
+    db.prepare("UPDATE notes SET updated_at = ? WHERE id = ?")
+      .run("2026-04-01T00:00:00.000Z", "cur-rest-a");
+    db.prepare("UPDATE notes SET updated_at = ? WHERE id = ?")
+      .run("2026-04-02T00:00:00.000Z", "cur-rest-b");
+
+    // Mint a starting cursor via the store (we don't expose a "first cursor"
+    // endpoint — the first call's response carries the cursor). Simulate
+    // the first call by querying without a cursor and reading
+    // next_cursor from a follow-up call shape.
+    const seed = await store.queryNotesPaged({});
+    const cursor = seed.next_cursor;
+
+    // No new writes after seed → second call is empty but still returns
+    // an envelope.
+    const res = await handleNotes(
+      mkReq("GET", `/notes?cursor=${encodeURIComponent(cursor)}`),
+      store,
+      "",
+    );
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect(body).toHaveProperty("notes");
+    expect(body).toHaveProperty("next_cursor");
+    expect(Array.isArray(body.notes)).toBe(true);
+    expect(body.notes).toHaveLength(0);
+    expect(typeof body.next_cursor).toBe("string");
+  });
+
+  test("GET /notes (no cursor) returns legacy flat-array shape", async () => {
+    await store.createNote("a", { id: "noCur-a" });
+    const res = await handleNotes(mkReq("GET", "/notes"), store, "");
+    const body = await res.json();
+    expect(Array.isArray(body)).toBe(true);
+  });
+
+  test("GET /notes?cursor=<stale> returns 400 cursor_query_mismatch", async () => {
+    await store.createNote("a", { tags: ["x"], id: "cm-a" });
+    await store.createNote("b", { tags: ["y"], id: "cm-b" });
+    const seed = await store.queryNotesPaged({ tags: ["x"] });
+
+    // Reuse on a different tag — engine raises cursor_query_mismatch.
+    const res = await handleNotes(
+      mkReq("GET", `/notes?tag=y&cursor=${encodeURIComponent(seed.next_cursor)}`),
+      store,
+      "",
+    );
+    expect(res.status).toBe(400);
+    const body = await res.json() as any;
+    expect(body.code).toBe("cursor_query_mismatch");
+  });
+
+  test("GET /notes?cursor=<garbage> returns 400 cursor_invalid", async () => {
+    const res = await handleNotes(
+      mkReq("GET", `/notes?cursor=not-a-real-cursor`),
+      store,
+      "",
+    );
+    expect(res.status).toBe(400);
+    const body = await res.json() as any;
+    expect(body.code).toBe("cursor_invalid");
+  });
+
+  test("GET /notes?cursor=...&near[note_id]=x rejects with INVALID_QUERY", async () => {
+    const a = await store.createNote("anchor", { id: "n1" });
+    const seed = await store.queryNotesPaged({});
+    const res = await handleNotes(
+      mkReq("GET", `/notes?cursor=${encodeURIComponent(seed.next_cursor)}&near[note_id]=${a.id}`),
+      store,
+      "",
+    );
+    expect(res.status).toBe(400);
+    const body = await res.json() as any;
+    expect(body.code).toBe("INVALID_QUERY");
+  });
+
+  test("GET /notes?cursor=...&search=... rejects with INVALID_QUERY (vault#355 reviewer)", async () => {
+    // REST used to silently drop the cursor and route into the FTS branch.
+    // MCP rejects this combo explicitly at core/src/mcp.ts — REST now does
+    // the same. Surface parity, no silent corruption.
+    await store.createNote("the quick brown fox", { id: "s1" });
+    const seed = await store.queryNotesPaged({});
+    const res = await handleNotes(
+      mkReq("GET", `/notes?cursor=${encodeURIComponent(seed.next_cursor)}&search=fox`),
+      store,
+      "",
+    );
+    expect(res.status).toBe(400);
+    const body = await res.json() as any;
+    expect(body.code).toBe("INVALID_QUERY");
+  });
+
+  test("GET /notes?cursor=...&sort=desc rejects with INVALID_QUERY", async () => {
+    // Descending iteration with a watermark cursor would skip newly-written
+    // rows. queryNotesPaged surfaces this as a QueryError; the REST handler
+    // catches and translates to 400. Asserts the surface parity with MCP
+    // even though the guard sits at the core layer.
+    await store.createNote("a", { id: "sd-a" });
+    const seed = await store.queryNotesPaged({});
+    const res = await handleNotes(
+      mkReq("GET", `/notes?cursor=${encodeURIComponent(seed.next_cursor)}&sort=desc`),
+      store,
+      "",
+    );
+    expect(res.status).toBe(400);
+    const body = await res.json() as any;
+    expect(body.code).toBe("INVALID_QUERY");
+  });
+
+  test("GET /notes?cursor=...&order_by=... rejects with INVALID_QUERY", async () => {
+    // Cursor pagination forces order by updated_at; order_by is mutually
+    // exclusive. Same surface-parity assertion as the sort=desc test.
+    await store.createNote("a", { id: "ob-a" });
+    const seed = await store.queryNotesPaged({});
+    const res = await handleNotes(
+      mkReq("GET", `/notes?cursor=${encodeURIComponent(seed.next_cursor)}&order_by=created_at`),
+      store,
+      "",
+    );
+    expect(res.status).toBe(400);
+    const body = await res.json() as any;
+    expect(body.code).toBe("INVALID_QUERY");
+  });
+
+  test("GET /notes?search=fox (without cursor) still works after the cursor+search guard", async () => {
+    // Sanity check: the cursor+search guard must not regress plain FTS.
+    await store.createNote("the quick brown fox", { id: "ss-a" });
+    const res = await handleNotes(mkReq("GET", "/notes?search=fox"), store, "");
+    expect(res.status).toBe(200);
+    const body = await res.json() as any[];
+    expect(body).toHaveLength(1);
+    expect(body[0].id).toBe("ss-a");
+  });
+
+  test("GET /notes?cursor=... resumes correctly across calls (end-to-end)", async () => {
+    // Three notes spread across distinct updated_at watermarks. First
+    // call returns the first batch, second call (with cursor) returns
+    // only the note written after the cursor was minted.
+    const a = await store.createNote("first", { id: "e2e-a" });
+    db.prepare("UPDATE notes SET updated_at = ? WHERE id = ?")
+      .run("2026-04-01T00:00:00.000Z", a.id);
+    const b = await store.createNote("second", { id: "e2e-b" });
+    db.prepare("UPDATE notes SET updated_at = ? WHERE id = ?")
+      .run("2026-04-02T00:00:00.000Z", b.id);
+
+    const seed = await store.queryNotesPaged({});
+    expect(seed.notes.map((n) => n.id).sort()).toEqual(["e2e-a", "e2e-b"]);
+
+    // Write a third note that lands AFTER the cursor's watermark.
+    const c = await store.createNote("third", { id: "e2e-c" });
+    db.prepare("UPDATE notes SET updated_at = ? WHERE id = ?")
+      .run("2026-04-03T00:00:00.000Z", c.id);
+
+    const res = await handleNotes(
+      mkReq("GET", `/notes?cursor=${encodeURIComponent(seed.next_cursor)}&include_content=true`),
+      store,
+      "",
+    );
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect(body.notes.map((n: any) => n.id)).toEqual(["e2e-c"]);
+  });
+
   test("GET /notes?has_links=false returns only orphaned notes", async () => {
     const a = await store.createNote("src", { id: "qa" });
     const b = await store.createNote("tgt", { id: "qb" });
@@ -2543,6 +2714,182 @@ describe("HTTP /notes", async () => {
       expect(body.map((n) => n.content)).toEqual(["new"]);
     });
   });
+
+  // -------------------------------------------------------------------------
+  // POST /notes/:id/retry-transcription — vault#353 design Q5.
+  //
+  // The endpoint re-enqueues a failed transcript by flipping the matching
+  // attachment back to `transcribe_status: pending`. The worker (or sweep)
+  // picks it up. These tests exercise the request shape + error branches;
+  // the actual re-transcription is covered in transcription-worker.test.ts's
+  // auto-origin section.
+  // -------------------------------------------------------------------------
+  describe("POST /notes/:id/retry-transcription", async () => {
+    async function seedFailedTranscript(opts: {
+      audioPath?: string;
+      noteId?: string;
+      transcriptId?: string;
+      omitAttachmentId?: boolean;
+    } = {}): Promise<{ owner: { id: string }; attachmentId: string; transcriptId: string; audioPath: string }> {
+      const audioPath = opts.audioPath ?? `${opts.noteId ?? "src"}/voice.webm`;
+      const ownerId = opts.noteId ?? "src-note";
+      const owner = await store.createNote("# Voice\n", { id: ownerId });
+      const att = await store.addAttachment(owner.id, audioPath, "audio/webm", {
+        transcribe_status: "failed",
+        transcribe_origin: "auto",
+        transcribe_error: "no transcription provider configured",
+      });
+      // Seed the failed transcript note exactly as the worker would have.
+      const transcriptMeta: Record<string, unknown> = {
+        transcript_of: audioPath,
+        transcript_status: "failed",
+        transcript_error: "missing_provider: no transcription provider configured",
+      };
+      if (!opts.omitAttachmentId) transcriptMeta.transcript_attachment_id = att.id;
+      await store.createNote("", {
+        id: opts.transcriptId ?? "transcript-1",
+        path: `${audioPath}.transcript`,
+        tags: ["transcript", "capture"],
+        metadata: transcriptMeta,
+      });
+      // Audio file present on disk so the retry doesn't 404 on audio_missing.
+      const assetsRoot = join(tmpDir, "assets");
+      mkdirSync(join(assetsRoot, audioPath.split("/").slice(0, -1).join("/")), { recursive: true });
+      writeFileSync(join(assetsRoot, audioPath), Buffer.from([1, 2, 3]));
+      process.env.ASSETS_DIR = assetsRoot;
+      return { owner: { id: ownerId }, attachmentId: att.id, transcriptId: opts.transcriptId ?? "transcript-1", audioPath };
+    }
+
+    test("happy path: flips attachment to pending and returns 202", async () => {
+      const { attachmentId, transcriptId } = await seedFailedTranscript();
+      const res = await handleNotes(
+        mkReq("POST", `/notes/${transcriptId}/retry-transcription`),
+        store,
+        `/${transcriptId}/retry-transcription`,
+        "default",
+      );
+      expect(res.status).toBe(202);
+      const body = await res.json() as any;
+      expect(body.status).toBe("queued");
+      expect(body.attachment_id).toBe(attachmentId);
+      expect(body.transcript_note_id).toBe(transcriptId);
+
+      // Attachment metadata reset.
+      const att = await store.getAttachment(attachmentId);
+      expect(att?.metadata?.transcribe_status).toBe("pending");
+      expect(att?.metadata?.transcribe_origin).toBe("auto");
+      // Stale failure state cleared.
+      expect(att?.metadata?.transcribe_error).toBeUndefined();
+      expect(att?.metadata?.transcribe_attempts).toBeUndefined();
+
+      delete process.env.ASSETS_DIR;
+    });
+
+    test("404 when transcript note doesn't exist", async () => {
+      const res = await handleNotes(
+        mkReq("POST", "/notes/no-such-id/retry-transcription"),
+        store,
+        "/no-such-id/retry-transcription",
+        "default",
+      );
+      expect(res.status).toBe(404);
+    });
+
+    test("400 invalid_target when target is not a transcript note", async () => {
+      await store.createNote("regular note", { id: "regular" });
+      const res = await handleNotes(
+        mkReq("POST", "/notes/regular/retry-transcription"),
+        store,
+        "/regular/retry-transcription",
+        "default",
+      );
+      expect(res.status).toBe(400);
+      const body = await res.json() as any;
+      expect(body.error).toBe("invalid_target");
+    });
+
+    test("400 not_failed when transcript already succeeded", async () => {
+      const audioPath = "memo/done.webm";
+      const owner = await store.createNote("voice", { id: "src-done" });
+      const att = await store.addAttachment(owner.id, audioPath, "audio/webm");
+      await store.createNote("the spoken words", {
+        id: "transcript-done",
+        path: `${audioPath}.transcript`,
+        metadata: {
+          transcript_of: audioPath,
+          transcript_attachment_id: att.id,
+          transcript_status: "complete",
+        },
+      });
+      const res = await handleNotes(
+        mkReq("POST", "/notes/transcript-done/retry-transcription"),
+        store,
+        "/transcript-done/retry-transcription",
+        "default",
+      );
+      expect(res.status).toBe(400);
+      const body = await res.json() as any;
+      expect(body.error).toBe("not_failed");
+      expect(body.transcript_status).toBe("complete");
+    });
+
+    test("400 missing_attachment_id when frontmatter lacks the id", async () => {
+      await seedFailedTranscript({
+        transcriptId: "transcript-no-id",
+        noteId: "src-no-id",
+        omitAttachmentId: true,
+      });
+      const res = await handleNotes(
+        mkReq("POST", "/notes/transcript-no-id/retry-transcription"),
+        store,
+        "/transcript-no-id/retry-transcription",
+        "default",
+      );
+      expect(res.status).toBe(400);
+      const body = await res.json() as any;
+      expect(body.error).toBe("missing_attachment_id");
+      delete process.env.ASSETS_DIR;
+    });
+
+    test("404 attachment_missing when the attachment row no longer exists", async () => {
+      const owner = await store.createNote("voice", { id: "src-stale" });
+      await store.createNote("", {
+        id: "transcript-stale",
+        path: "memo/stale.webm.transcript",
+        metadata: {
+          transcript_of: "memo/stale.webm",
+          transcript_attachment_id: "deleted-attachment-id",
+          transcript_status: "failed",
+          transcript_error: "missing_provider",
+        },
+      });
+      const res = await handleNotes(
+        mkReq("POST", "/notes/transcript-stale/retry-transcription"),
+        store,
+        "/transcript-stale/retry-transcription",
+        "default",
+      );
+      expect(res.status).toBe(404);
+      const body = await res.json() as any;
+      expect(body.error).toBe("attachment_missing");
+    });
+
+    test("405 on GET (must POST)", async () => {
+      await seedFailedTranscript({
+        transcriptId: "transcript-405",
+        noteId: "src-405",
+        audioPath: "memo/405.webm",
+      });
+      const res = await handleNotes(
+        mkReq("GET", "/notes/transcript-405/retry-transcription"),
+        store,
+        "/transcript-405/retry-transcription",
+        "default",
+      );
+      expect(res.status).toBe(405);
+      delete process.env.ASSETS_DIR;
+    });
+  });
 });
 
 describe("HTTP GET /notes?format=graph", async () => {