@openparachute/vault 0.7.3-rc.10 → 0.7.3-rc.12

package/src/routes.ts

@@ -143,7 +143,7 @@ import {
   type ExpandMode,
 } from "../core/src/expand.ts";
 import { join, extname, normalize } from "path";
-import { existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "fs";
+import { existsSync, mkdirSync, statSync, unlinkSync, writeFileSync } from "fs";
 import { assetsDir, readGlobalConfig, readVaultConfig } from "./config.ts";
 import { shouldAutoTranscribe } from "./auto-transcribe.ts";
 // usage.ts imports `assetsDir` from config.ts (neutral ground), so this import
@@ -4453,6 +4453,56 @@ export const MAX_REQUEST_BODY_BYTES = MAX_UPLOAD_BYTES + 20 * 1024 * 1024; // 12
 const BLOCKED_EXTENSIONS = BLOCKED_ATTACHMENT_EXTENSIONS;
 const MIME_TYPES = ATTACHMENT_MIME_TYPES;
 
+/**
+ * Parse a single-range `Range: bytes=a-b` header (RFC 7233 §2.1 — single
+ * range only, attachments-for-agents design D9, the REST twin of MCP's
+ * `content_offset`). Returns `null` — this function's own contract is
+ * "serve the full response, unranged" — for a missing header, a
+ * MALFORMED value, an unrecognized unit, a multi-range list
+ * (`bytes=0-10,20-30` — ignored, not an error, per D9), or a range this
+ * file can't satisfy (a `start` past EOF). `start`/`end` are both
+ * INCLUSIVE byte offsets; `end` is clamped to `total - 1` when the
+ * request left it open (`bytes=500-`) or asked past EOF.
+ *
+ * IMPORTANT — this `null` contract is NOT the last word for an
+ * unsatisfiable (syntactically-valid but out-of-bounds) range on a real
+ * `Bun.serve()` deployment. Live-verified against an actual socket (not
+ * the in-process `handleStorage()` call the test suite uses): when the
+ * response body is a `Bun.file()` — which `handleStorage`'s full-response
+ * branch below always hands back — Bun's OWN runtime transparently
+ * reinterprets the incoming request's `Range` header a second time and,
+ * for an out-of-bounds range, overrides our 200 with a native
+ * **416 Range Not Satisfiable**, regardless of what this function or
+ * `handleStorage` returned. That's RFC 7233-correct and is being KEPT,
+ * not fought — so in practice, `null` from an out-of-bounds `start`
+ * still results in a 200 from `handleStorage`'s own logic, but the byte
+ * that actually reaches a real client for that specific case is a 416
+ * courtesy of Bun itself. MALFORMED and multi-range headers are NOT
+ * range-shaped at all, so Bun's native layer doesn't touch them — those
+ * two cases genuinely serve the full 200, in-process harness and real
+ * socket alike.
+ */
+export function parseByteRangeHeader(header: string | null, total: number): { start: number; end: number } | null {
+  if (!header || total <= 0) return null;
+  const match = header.match(/^bytes=(\d*)-(\d*)$/);
+  if (!match) return null; // malformed, unrecognized unit, or a multi-range list
+  const [, startRaw, endRaw] = match;
+  if (startRaw === "" && endRaw === "") return null;
+
+  if (startRaw === "") {
+    // Suffix range: last N bytes (`bytes=-500`).
+    const suffixLength = Number(endRaw);
+    if (!Number.isSafeInteger(suffixLength) || suffixLength <= 0) return null;
+    return { start: Math.max(0, total - suffixLength), end: total - 1 };
+  }
+
+  const start = Number(startRaw);
+  if (!Number.isSafeInteger(start) || start < 0 || start >= total) return null;
+  const end = endRaw === "" ? total - 1 : Math.min(Number(endRaw), total - 1);
+  if (!Number.isSafeInteger(end) || end < start) return null;
+  return { start, end };
+}
+
 export async function handleStorage(
   req: Request,
   path: string,
@@ -4615,12 +4665,38 @@ export async function handleStorage(
     const stat = statSync(filePath);
     const ext = extname(filePath).toLowerCase();
     const contentType = MIME_TYPES[ext] ?? "application/octet-stream";
-    const fileBuffer = readFileSync(filePath);
+    const total = stat.size;
+
+    // vault attachments-for-agents design (D9) — the REST twin of MCP's
+    // `content_offset`. `Bun.file(filePath)` resolves lazily: `.slice()`
+    // creates a bounded view and only the requested bytes are actually read
+    // on `.arrayBuffer()`/streaming, replacing the prior whole-file
+    // `readFileSync` (a standing memory smell on a large attachment, e.g. a
+    // 90 MB video) on BOTH the ranged and full-file paths below.
+    const bunFile = Bun.file(filePath);
+    const range = parseByteRangeHeader(req.headers.get("range"), total);
+
+    if (range) {
+      const { start, end } = range; // inclusive
+      return new Response(bunFile.slice(start, end + 1), {
+        status: 206,
+        headers: {
+          "Content-Type": contentType,
+          "Content-Length": String(end - start + 1),
+          "Content-Range": `bytes ${start}-${end}/${total}`,
+          "Accept-Ranges": "bytes",
+          // Defense-in-depth: never let a browser MIME-sniff a stored asset
+          // into an active type — see the full-response branch below.
+          "X-Content-Type-Options": "nosniff",
+        },
+      });
+    }
 
-    return new Response(fileBuffer, {
+    return new Response(bunFile, {
       headers: {
         "Content-Type": contentType,
-        "Content-Length": String(stat.size),
+        "Content-Length": String(total),
+        "Accept-Ranges": "bytes",
         // Defense-in-depth: never let a browser MIME-sniff a stored asset into
         // an active type (e.g. an octet-stream body sniffed as text/html).
         // Combined with the upload blocklist (no .svg/.html) this closes the

package/src/server.ts

@@ -21,6 +21,7 @@ import { migrateVaultKeys } from "./token-store.ts";
 import { resolveFirstBootVaultName, reservedNameSquatWarnings } from "./vault-name.ts";
 import { getVaultStore, getVaultNameForStore, getSharedEmbeddingProvider } from "./vault-store.ts";
 import { EmbeddingWorker, registerEmbeddingHook } from "./embedding-worker.ts";
+import { startAttachmentTicketSweep, stopAttachmentTicketSweep } from "./attachment-tickets.ts";
 import { seedOnboardingNotesBestEffort } from "./onboarding-seed.ts";
 import { defaultHookRegistry } from "../core/src/hooks.ts";
 import { registerTriggers } from "./triggers.ts";
@@ -237,6 +238,11 @@ const embeddingWorker = new EmbeddingWorker({
 registerEmbeddingHook(defaultHookRegistry, embeddingWorker, (store) => getVaultNameForStore(store as never));
 embeddingWorker.start();
 
+// Attachment-ticket sweep (vault#612) — drops expired-unspent tickets from
+// the in-process store so an abandoned mint (an agent that never curls)
+// doesn't sit in memory forever. See src/attachment-tickets.ts.
+startAttachmentTicketSweep();
+
 if (process.env.VAULT_AUTH_TOKEN?.trim()) {
   console.log("[auth] VAULT_AUTH_TOKEN set — server-wide operator bearer active");
 }
@@ -619,6 +625,7 @@ async function shutdown(signal: string): Promise<void> {
         // Then drain hooks + stop the transcription/embedding workers in
         // parallel.
         embeddingWorker.stop();
+        stopAttachmentTicketSweep();
         await Promise.all([
           defaultHookRegistry.drain(),
           transcriptionWorker?.stop() ?? Promise.resolve(),

package/src/storage.test.ts

@@ -30,7 +30,7 @@ const testDir = join(
 process.env.PARACHUTE_HOME = testDir;
 process.env.ASSETS_DIR = join(testDir, "assets");
 
-const { handleStorage, MAX_UPLOAD_BYTES, MAX_REQUEST_BODY_BYTES } = await import("./routes.ts");
+const { handleStorage, MAX_UPLOAD_BYTES, MAX_REQUEST_BODY_BYTES, parseByteRangeHeader } = await import("./routes.ts");
 const { expandTokenTagScope } = await import("./tag-scope.ts");
 
 // The upload-allowlist tests never touch the store (POST /upload writes to
@@ -564,3 +564,202 @@ describe("storage POST parity (finding D)", () => {
     expect(res.status).toBe(404);
   });
 });
+
+// ---------------------------------------------------------------------------
+// REST Range (206) — vault attachments-for-agents design D9, the REST twin
+// of MCP's content_offset/content_length.
+// ---------------------------------------------------------------------------
+
+describe("parseByteRangeHeader", () => {
+  test("no header → null (full response)", () => {
+    expect(parseByteRangeHeader(null, 100)).toBeNull();
+  });
+
+  test("bytes=0-99 on a 100-byte file → the whole file as one satisfiable range", () => {
+    expect(parseByteRangeHeader("bytes=0-99", 100)).toEqual({ start: 0, end: 99 });
+  });
+
+  test("bytes=10-19 → an inclusive mid-file window", () => {
+    expect(parseByteRangeHeader("bytes=10-19", 100)).toEqual({ start: 10, end: 19 });
+  });
+
+  test("bytes=90- (open-ended) → reads to EOF", () => {
+    expect(parseByteRangeHeader("bytes=90-", 100)).toEqual({ start: 90, end: 99 });
+  });
+
+  test("bytes=-10 (suffix range) → the last 10 bytes", () => {
+    expect(parseByteRangeHeader("bytes=-10", 100)).toEqual({ start: 90, end: 99 });
+  });
+
+  test("bytes=-1000 (suffix longer than the file) → clamps to the whole file", () => {
+    expect(parseByteRangeHeader("bytes=-1000", 100)).toEqual({ start: 0, end: 99 });
+  });
+
+  test("bytes=50-1000 (end past EOF) → clamps end to the last byte", () => {
+    expect(parseByteRangeHeader("bytes=50-1000", 100)).toEqual({ start: 50, end: 99 });
+  });
+
+  test("start past EOF → null (this function's own contract; a real Bun.serve() socket overrides with a native 416 — see doc comment)", () => {
+    expect(parseByteRangeHeader("bytes=100-200", 100)).toBeNull();
+    expect(parseByteRangeHeader("bytes=1000-", 100)).toBeNull();
+  });
+
+  test("start > end → null (malformed)", () => {
+    expect(parseByteRangeHeader("bytes=50-10", 100)).toBeNull();
+  });
+
+  test("bytes=- (both empty) → null", () => {
+    expect(parseByteRangeHeader("bytes=-", 100)).toBeNull();
+  });
+
+  test("a multi-range list (bytes=0-10,20-30) → null (ignored per D9, not an error)", () => {
+    expect(parseByteRangeHeader("bytes=0-10,20-30", 100)).toBeNull();
+  });
+
+  test("an unrecognized unit → null", () => {
+    expect(parseByteRangeHeader("items=0-10", 100)).toBeNull();
+  });
+
+  test("garbage value → null, not a throw", () => {
+    expect(parseByteRangeHeader("bytes=abc-def", 100)).toBeNull();
+    expect(parseByteRangeHeader("nonsense", 100)).toBeNull();
+  });
+
+  test("a zero-byte file → null regardless of header (nothing to range over)", () => {
+    expect(parseByteRangeHeader("bytes=0-0", 0)).toBeNull();
+  });
+});
+
+describe("storage GET Range support (vault attachments-for-agents design D9)", () => {
+  const VAULT = "range-vault";
+  // 26 bytes, byte-identical to its own index — content[i] === i (0x00..0x19)
+  // — so any slice's bytes can be asserted exactly by index, not just length.
+  const CONTENT = Buffer.from(Array.from({ length: 26 }, (_, i) => i));
+
+  async function setup(): Promise<{ store: SqliteStore; assets: string; relPath: string }> {
+    const store = freshStore();
+    const assets = join(testDir, "assets", VAULT, "data");
+    mkdirSync(join(assets, "2026-05-28"), { recursive: true });
+    process.env.ASSETS_DIR = assets;
+
+    const relPath = "2026-05-28/ranged.bin";
+    writeFileSync(join(assets, relPath), CONTENT);
+    const note = await store.createNote("range note", { tags: ["misc"] });
+    await store.addAttachment(note.id, relPath, "application/octet-stream");
+
+    return { store, assets, relPath };
+  }
+
+  function getReq(reqPath: string, range?: string): Request {
+    const headers: Record<string, string> = {};
+    if (range !== undefined) headers.range = range;
+    return new Request(`http://localhost:1940/storage/${reqPath}`, { method: "GET", headers });
+  }
+
+  test("no Range header → 200, full body, Accept-Ranges advertised", async () => {
+    const { store, relPath } = await setup();
+    const res = await handleStorage(getReq(relPath), `/${relPath}`, VAULT, store);
+    expect(res.status).toBe(200);
+    expect(res.headers.get("Accept-Ranges")).toBe("bytes");
+    expect(res.headers.get("Content-Length")).toBe("26");
+    expect(res.headers.has("Content-Range")).toBe(false);
+    const body = Buffer.from(await res.arrayBuffer());
+    expect(body.equals(CONTENT)).toBe(true);
+  });
+
+  test("Range: bytes=0-9 → 206, first 10 bytes, correct Content-Range", async () => {
+    const { store, relPath } = await setup();
+    const res = await handleStorage(getReq(relPath, "bytes=0-9"), `/${relPath}`, VAULT, store);
+    expect(res.status).toBe(206);
+    expect(res.headers.get("Content-Range")).toBe("bytes 0-9/26");
+    expect(res.headers.get("Content-Length")).toBe("10");
+    expect(res.headers.get("Accept-Ranges")).toBe("bytes");
+    expect(res.headers.get("X-Content-Type-Options")).toBe("nosniff");
+    const body = Buffer.from(await res.arrayBuffer());
+    expect(body.equals(CONTENT.subarray(0, 10))).toBe(true);
+  });
+
+  test("Range: bytes=16-25 (to EOF) → 206, correct tail bytes", async () => {
+    const { store, relPath } = await setup();
+    const res = await handleStorage(getReq(relPath, "bytes=16-25"), `/${relPath}`, VAULT, store);
+    expect(res.status).toBe(206);
+    expect(res.headers.get("Content-Range")).toBe("bytes 16-25/26");
+    const body = Buffer.from(await res.arrayBuffer());
+    expect(body.equals(CONTENT.subarray(16, 26))).toBe(true);
+  });
+
+  test("Range: bytes=-5 (suffix) → 206, last 5 bytes", async () => {
+    const { store, relPath } = await setup();
+    const res = await handleStorage(getReq(relPath, "bytes=-5"), `/${relPath}`, VAULT, store);
+    expect(res.status).toBe(206);
+    expect(res.headers.get("Content-Range")).toBe("bytes 21-25/26");
+    const body = Buffer.from(await res.arrayBuffer());
+    expect(body.equals(CONTENT.subarray(21, 26))).toBe(true);
+  });
+
+  test("paging the whole file via sequential ranges reassembles byte-identical content", async () => {
+    const { store, relPath } = await setup();
+    const chunkSize = 7; // doesn't divide 26 evenly — exercises a short final chunk
+    const chunks: Buffer[] = [];
+    for (let start = 0; start < 26; start += chunkSize) {
+      const end = Math.min(start + chunkSize - 1, 25);
+      const res = await handleStorage(getReq(relPath, `bytes=${start}-${end}`), `/${relPath}`, VAULT, store);
+      expect(res.status).toBe(206);
+      chunks.push(Buffer.from(await res.arrayBuffer()));
+    }
+    expect(Buffer.concat(chunks).equals(CONTENT)).toBe(true);
+  });
+
+  test("a malformed Range header → 200 full response, not an error (D9: ignore, don't fail)", async () => {
+    const { store, relPath } = await setup();
+    const res = await handleStorage(getReq(relPath, "not-a-range"), `/${relPath}`, VAULT, store);
+    expect(res.status).toBe(200);
+    expect(res.headers.has("Content-Range")).toBe(false);
+    const body = Buffer.from(await res.arrayBuffer());
+    expect(body.equals(CONTENT)).toBe(true);
+  });
+
+  test("a multi-range Range header → 200 full response (multipart ranges unsupported, ignored per D9)", async () => {
+    const { store, relPath } = await setup();
+    const res = await handleStorage(getReq(relPath, "bytes=0-5,10-15"), `/${relPath}`, VAULT, store);
+    expect(res.status).toBe(200);
+    const body = Buffer.from(await res.arrayBuffer());
+    expect(body.equals(CONTENT)).toBe(true);
+  });
+
+  test("an unsatisfiable Range (start past EOF) → handleStorage's OWN logic returns 200 (parseByteRangeHeader's null contract)", async () => {
+    // IMPORTANT — this is NOT the whole live story. `handleStorage` is
+    // called here directly, in-process, so this only exercises OUR
+    // fallback logic (parseByteRangeHeader → null → the unranged 200
+    // branch). Live-verified against a real `Bun.serve()` socket (not
+    // this harness): Bun's own runtime independently reinterprets the
+    // incoming `Range` header on a `Bun.file()`-backed response body and
+    // overrides an out-of-bounds range with a native
+    // **416 Range Not Satisfiable** — RFC 7233-correct, and kept, not
+    // fought. This in-process harness has no socket for Bun's native
+    // layer to intercept, so it can only ever observe the 200 our own
+    // code returns — see `parseByteRangeHeader`'s doc comment
+    // (`src/routes.ts`) for the full explanation.
+    const { store, relPath } = await setup();
+    const res = await handleStorage(getReq(relPath, "bytes=1000-2000"), `/${relPath}`, VAULT, store);
+    expect(res.status).toBe(200);
+    const body = Buffer.from(await res.arrayBuffer());
+    expect(body.equals(CONTENT)).toBe(true);
+  });
+
+  test("Range is still honored for a tag-scoped in-scope request (206)", async () => {
+    const { store, relPath } = await setup();
+    const ctx = await tagScopeCtx(store, ["misc"]);
+    const res = await handleStorage(getReq(relPath, "bytes=0-3"), `/${relPath}`, VAULT, store, ctx);
+    expect(res.status).toBe(206);
+    const body = Buffer.from(await res.arrayBuffer());
+    expect(body.equals(CONTENT.subarray(0, 4))).toBe(true);
+  });
+
+  test("Range on an out-of-scope attachment still 404s (same confinement guard, byte-identical to the non-ranged path)", async () => {
+    const { store, relPath } = await setup();
+    const ctx = await tagScopeCtx(store, ["totally-unrelated-tag"]);
+    const res = await handleStorage(getReq(relPath, "bytes=0-3"), `/${relPath}`, VAULT, store, ctx);
+    expect(res.status).toBe(404);
+  });
+});

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);
+  });
+});