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

package/src/module-manifest.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { readSelfManifest, resolvePackageRoot } from "./module-manifest.ts";
+
+function withTempPackageRoot(
+  manifest: unknown | undefined,
+  fn: (root: string) => void,
+): void {
+  const root = mkdtempSync(join(tmpdir(), "pvault-manifest-"));
+  try {
+    if (manifest !== undefined) {
+      mkdirSync(join(root, ".parachute"), { recursive: true });
+      writeFileSync(
+        join(root, ".parachute", "module.json"),
+        typeof manifest === "string" ? manifest : JSON.stringify(manifest),
+      );
+    }
+    fn(root);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+describe("module-manifest", () => {
+  test("resolvePackageRoot returns the directory containing package.json", () => {
+    // In the test env, this module lives at <repo>/src/module-manifest.test.ts —
+    // so the resolved root is the repo root. We don't pin the exact path
+    // (tests run from various cwds); we just sanity-check it's an absolute
+    // directory ending in the vault repo's name.
+    const root = resolvePackageRoot();
+    expect(root.startsWith("/")).toBe(true);
+    expect(root.endsWith("/src")).toBe(false);
+  });
+
+  test("readSelfManifest returns null when .parachute/module.json is missing", () => {
+    withTempPackageRoot(undefined, (root) => {
+      expect(readSelfManifest(root)).toBeNull();
+    });
+  });
+
+  test("readSelfManifest parses a valid manifest (no kind — hub#301 Phase B)", () => {
+    withTempPackageRoot(
+      {
+        name: "vault",
+        manifestName: "parachute-vault",
+        displayName: "Vault",
+        tagline: "Test tagline",
+        port: 1940,
+        paths: ["/vault/default"],
+        health: "/vault/default/health",
+      },
+      (root) => {
+        const m = readSelfManifest(root);
+        expect(m).not.toBeNull();
+        expect(m?.name).toBe("vault");
+        expect(m?.manifestName).toBe("parachute-vault");
+        expect(m?.displayName).toBe("Vault");
+        expect(m?.kind).toBeUndefined();
+        expect(m?.port).toBe(1940);
+        expect(m?.paths).toEqual(["/vault/default"]);
+      },
+    );
+  });
+
+  test("readSelfManifest tolerates a legacy manifest that still includes kind", () => {
+    // hub#301 Phase B retired the `kind` field, but legacy manifests on
+    // pinned installs may still include it. The reader accepts it without
+    // erroring; the field is never branched on.
+    withTempPackageRoot(
+      {
+        name: "vault",
+        manifestName: "parachute-vault",
+        kind: "api",
+        port: 1940,
+        paths: ["/vault/default"],
+        health: "/vault/default/health",
+      },
+      (root) => {
+        const m = readSelfManifest(root);
+        expect(m).not.toBeNull();
+        expect(m?.kind).toBe("api");
+      },
+    );
+  });
+
+  test("readSelfManifest throws on malformed JSON", () => {
+    withTempPackageRoot("{ not valid json", (root) => {
+      expect(() => readSelfManifest(root)).toThrow();
+    });
+  });
+
+  test("readSelfManifest throws when required field missing", () => {
+    withTempPackageRoot(
+      { name: "vault" /* missing manifestName / port / paths / health */ },
+      (root) => {
+        expect(() => readSelfManifest(root)).toThrow(/missing required/);
+      },
+    );
+  });
+
+  test("readSelfManifest reads the actual shipped manifest in the repo", () => {
+    // Smoke test the real shipped file — guards against ever shipping a
+    // malformed manifest. Uses the real resolvePackageRoot (which finds
+    // the repo root in tests). Post hub#301 Phase B, the shipped manifest
+    // no longer includes `kind`.
+    const m = readSelfManifest();
+    expect(m).not.toBeNull();
+    expect(m?.manifestName).toBe("parachute-vault");
+    expect(m?.kind).toBeUndefined();
+    expect(m?.port).toBe(1940);
+  });
+});

package/src/module-manifest.ts

@@ -0,0 +1,104 @@
+/**
+ * Reader for the package's own `.parachute/module.json`.
+ *
+ * Vault ships `module.json` alongside `package.json` at the package root.
+ * This module locates the file via `import.meta.url` (which works for both
+ * `bun src/cli.ts …` dev runs and the published-package `parachute-vault`
+ * binary — the file ships in `package.json` `files` next to `src/`).
+ *
+ * Used by `self-register.ts` on server boot: vault reads its own manifest
+ * + computes the package's `installDir` so the services.json row carries
+ * the same metadata that hub's `FIRST_PARTY_FALLBACKS[vault]` provides
+ * today. The endgame is that hub's vendored fallback retires once every
+ * first-party module self-registers reliably — this is the POC for the
+ * pattern.
+ *
+ * Shape mirrors `parachute-hub/src/module-manifest.ts`. Kept narrow: we
+ * only consume the fields vault stamps onto services.json
+ * (displayName, tagline, stripPrefix). The full manifest validator lives
+ * on the hub side; vault treats its own manifest as authored-by-us +
+ * trusts the shape.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export type ModuleKind = "api" | "frontend" | "tool";
+
+/**
+ * Subset of the full manifest schema (see `parachute-hub/src/module-manifest.ts`)
+ * — only the fields vault's self-registration consumes today. Adding more is
+ * a one-line edit when the surface widens.
+ */
+export interface VaultModuleManifest {
+  readonly name: string;
+  readonly manifestName: string;
+  readonly displayName?: string;
+  readonly tagline?: string;
+  /**
+   * Deprecated as of hub#301 Phase B (kind retirement, 2026-05-23). Hub's
+   * validator dropped `kind` from required-fields in hub#327; vault no
+   * longer ships the field in `.parachute/module.json`. Kept here as
+   * optional only so an older shipped manifest (pinned legacy install)
+   * still parses without throwing — the field is never branched on.
+   */
+  readonly kind?: ModuleKind;
+  readonly port: number;
+  readonly paths: readonly string[];
+  readonly health: string;
+  readonly stripPrefix?: boolean;
+}
+
+/**
+ * Resolve the path to the package root — the directory containing both
+ * `package.json` and `.parachute/module.json`. Walks up from
+ * `import.meta.url` so the answer is correct under both:
+ *
+ *   - dev:  `bun src/cli.ts serve` → `src/module-manifest.ts` → parent = repo root
+ *   - prod: published package → `src/module-manifest.ts` → parent = installed
+ *           package dir (e.g. `~/.bun/install/global/node_modules/@openparachute/vault`)
+ *
+ * Exported for tests + the self-register flow that needs to stamp this as
+ * `installDir` on the services.json row.
+ */
+export function resolvePackageRoot(): string {
+  const here = dirname(fileURLToPath(import.meta.url));
+  // `src/module-manifest.ts` lives one level under the package root.
+  return resolve(here, "..");
+}
+
+/**
+ * Read `<packageRoot>/.parachute/module.json` if present. Returns null when
+ * the file is missing (e.g. during local dev before the file was committed)
+ * — callers treat that as "self-registration unavailable, log + continue."
+ *
+ * Throws on malformed JSON: a corrupt manifest is a deploy bug we want to
+ * surface, not silently swallow. The self-register caller catches + logs
+ * so a bad manifest doesn't crash server boot.
+ */
+export function readSelfManifest(
+  packageRoot: string = resolvePackageRoot(),
+): VaultModuleManifest | null {
+  const path = join(packageRoot, ".parachute", "module.json");
+  if (!existsSync(path)) return null;
+  const raw = readFileSync(path, "utf8");
+  const parsed = JSON.parse(raw) as Record<string, unknown>;
+  // Minimal shape validation. Only the fields we actually consume — anything
+  // else passes through untouched. Strict full-shape validation is the hub's
+  // job (it'll fail an install on a malformed manifest); vault treats its
+  // own shipped file as authored-by-us.
+  if (typeof parsed.name !== "string" || typeof parsed.manifestName !== "string") {
+    throw new Error(`${path}: manifest missing required "name" / "manifestName"`);
+  }
+  if (typeof parsed.port !== "number" || !Array.isArray(parsed.paths)) {
+    throw new Error(`${path}: manifest missing required "port" / "paths"`);
+  }
+  if (typeof parsed.health !== "string") {
+    throw new Error(`${path}: manifest missing required "health"`);
+  }
+  // `kind` is retired as of hub#301 Phase B — hub#327 made it optional in
+  // the hub-side validator, and vault no longer ships it. If a legacy
+  // manifest still includes the field, accept it; just don't require it.
+  return parsed as unknown as VaultModuleManifest;
+}

package/src/routes.ts

@@ -45,6 +45,7 @@ import {
 import { join, extname, normalize } from "path";
 import { existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "fs";
 import { vaultDir } from "./config.ts";
+import { shouldAutoTranscribe } from "./auto-transcribe.ts";
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -509,6 +510,21 @@ async function handleNotesInner(
         return json(result);
       }
 
+      // Cursor + full-text search is mutually exclusive (vault#313 reviewer).
+      // FTS owns its own ordering (relevance, not updated_at), so a cursor
+      // would skip rows. MCP rejects this combo at `core/src/mcp.ts`; REST
+      // would otherwise route into the `if (search)` branch below and
+      // silently drop the cursor. Reject here for surface parity.
+      if (search && parseQuery(url, "cursor")) {
+        return json(
+          {
+            error: "cursor is incompatible with full-text search — FTS has its own ordering. Use date_filter on updated_at for since-last-checked search.",
+            code: "INVALID_QUERY",
+          },
+          400,
+        );
+      }
+
       // Full-text search
       if (search) {
         const searchTags = parseQueryList(url, "tag");
@@ -564,49 +580,74 @@ async function handleNotesInner(
       const tags = parseQueryList(url, "tag");
       const bracket = parseMetaBrackets(url);
       if (bracket.error) return bracket.error;
+      // 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
+      // exclusive with the `near` graph-neighborhood scope (rebuilding the
+      // neighborhood per page isn't stable) — rejected below.
+      const cursorParam = parseQuery(url, "cursor");
+      const nearNoteIdEarly = parseQuery(url, "near[note_id]");
+      if (cursorParam && nearNoteIdEarly) {
+        return json(
+          {
+            error: "cursor is incompatible with near (graph neighborhood). Resolve the neighborhood first, then iterate with cursor over the resulting note set.",
+            code: "INVALID_QUERY",
+          },
+          400,
+        );
+      }
       let results: Note[];
+      let nextCursor: string | null = null;
+      const queryOpts = {
+        tags,
+        tagMatch: (parseQuery(url, "tag_match") as "all" | "any") ?? (tags && tags.length > 1 ? "any" : undefined),
+        excludeTags: parseQueryList(url, "exclude_tag"),
+        hasTags: parseBoolOrUndef(parseQuery(url, "has_tags")),
+        hasLinks: parseBoolOrUndef(parseQuery(url, "has_links")),
+        path: parseQuery(url, "path") ?? undefined,
+        pathPrefix: parseQuery(url, "path_prefix") ?? undefined,
+        // Extension filter (vault#328). Accepts repeated `extension=`
+        // params for the array form: `?extension=csv&extension=yaml`.
+        // `parseQueryList` already returns undefined when no params
+        // are present, so the filter is silently skipped on a plain
+        // GET without the extension query.
+        extension: parseExtensionFilter(url),
+        metadata: bracket.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).
+        //   3. Legacy `date_from=…&date_to=…` (no date_field, deprecated)
+        //      — filters on `n.created_at` by definition.
+        // The engine rejects combinations of `dateFilter` with the legacy
+        // `dateFrom`/`dateTo`, so we never set both shapes simultaneously.
+        ...(bracket.dateFilter
+          ? { dateFilter: bracket.dateFilter }
+          : parseQuery(url, "date_field")
+            ? {
+                dateFilter: {
+                  field: parseQuery(url, "date_field")!,
+                  from: parseQuery(url, "date_from") ?? undefined,
+                  to: parseQuery(url, "date_to") ?? undefined,
+                },
+              }
+            : {
+                dateFrom: parseQuery(url, "date_from") ?? undefined,
+                dateTo: parseQuery(url, "date_to") ?? undefined,
+              }),
+        sort: (parseQuery(url, "sort") as "asc" | "desc") ?? undefined,
+        orderBy: parseQuery(url, "order_by") ?? undefined,
+        limit: parseInt10(parseQuery(url, "limit")) ?? 50,
+        offset: parseInt10(parseQuery(url, "offset")),
+        cursor: cursorParam ?? undefined,
+      };
       try {
-        results = await store.queryNotes({
-          tags,
-          tagMatch: (parseQuery(url, "tag_match") as "all" | "any") ?? (tags && tags.length > 1 ? "any" : undefined),
-          excludeTags: parseQueryList(url, "exclude_tag"),
-          hasTags: parseBoolOrUndef(parseQuery(url, "has_tags")),
-          hasLinks: parseBoolOrUndef(parseQuery(url, "has_links")),
-          path: parseQuery(url, "path") ?? undefined,
-          pathPrefix: parseQuery(url, "path_prefix") ?? undefined,
-          // Extension filter (vault#328). Accepts repeated `extension=`
-          // params for the array form: `?extension=csv&extension=yaml`.
-          // `parseQueryList` already returns undefined when no params
-          // are present, so the filter is silently skipped on a plain
-          // GET without the extension query.
-          extension: parseExtensionFilter(url),
-          metadata: bracket.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).
-          //   3. Legacy `date_from=…&date_to=…` (no date_field, deprecated)
-          //      — filters on `n.created_at` by definition.
-          // The engine rejects combinations of `dateFilter` with the legacy
-          // `dateFrom`/`dateTo`, so we never set both shapes simultaneously.
-          ...(bracket.dateFilter
-            ? { dateFilter: bracket.dateFilter }
-            : parseQuery(url, "date_field")
-              ? {
-                  dateFilter: {
-                    field: parseQuery(url, "date_field")!,
-                    from: parseQuery(url, "date_from") ?? undefined,
-                    to: parseQuery(url, "date_to") ?? undefined,
-                  },
-                }
-              : {
-                  dateFrom: parseQuery(url, "date_from") ?? undefined,
-                  dateTo: parseQuery(url, "date_to") ?? undefined,
-                }),
-          sort: (parseQuery(url, "sort") as "asc" | "desc") ?? undefined,
-          orderBy: parseQuery(url, "order_by") ?? undefined,
-          limit: parseInt10(parseQuery(url, "limit")) ?? 50,
-          offset: parseInt10(parseQuery(url, "offset")),
-        });
+        if (cursorParam) {
+          const page = await store.queryNotesPaged(queryOpts);
+          results = page.notes;
+          nextCursor = page.next_cursor;
+        } else {
+          results = await store.queryNotes(queryOpts);
+        }
       } catch (e: any) {
         // QueryError (non-indexed order_by, unknown operator, ...) surfaces
         // here. Duck-type on `name` + `code` — core is a separate module, so
@@ -614,6 +655,14 @@ async function handleNotesInner(
         if (e && e.name === "QueryError") {
           return json({ error: e.message, code: e.code ?? "INVALID_QUERY" }, 400);
         }
+        // CursorError carries a structured code (cursor_invalid /
+        // cursor_query_mismatch) so the agent loop can distinguish a
+        // malformed cursor from a hash-mismatch and react appropriately
+        // (the latter typically means the agent changed its filter and
+        // should drop the cursor + restart from scratch).
+        if (e && e.name === "CursorError") {
+          return json({ error: e.message, code: e.code ?? "cursor_invalid" }, 400);
+        }
         throw e;
       }
 
@@ -682,9 +731,14 @@ async function handleNotesInner(
           if (includeAttachments) enriched.attachments = await store.getAttachments(n.id);
           enrichedOut.push(enriched);
         }
+        // Cursor mode wraps the list in {notes, next_cursor} so an agent
+        // loop can chain calls without tracking a watermark client-side.
+        // Legacy callers (no `cursor` param) still get the flat array.
+        if (cursorParam) return json({ notes: enrichedOut, next_cursor: nextCursor });
         return json(enrichedOut);
       }
 
+      if (cursorParam) return json({ notes: output, next_cursor: nextCursor });
       return json(output);
     }
 
@@ -813,19 +867,33 @@ async function handleNotesInner(
       const body = await req.json() as { path: string; mimeType: string; transcribe?: boolean };
       if (!body.path || !body.mimeType) return json({ error: "path and mimeType are required" }, 400);
 
-      // `transcribe: true` asks the transcription worker to read this audio
-      // file and replace the note's content with the transcript. The caller
-      // is declaring "overwrite my current content when the transcript lands"
-      // — we persist that as `transcribe_stub: true` on the note so a later
-      // user edit (which clears the marker) can opt out before the worker
-      // runs.
-      const attMeta = body.transcribe
-        ? { transcribe_status: "pending" as const, transcribe_requested_at: new Date().toISOString() }
+      // Decide whether to enqueue this attachment for transcription. Two paths:
+      //
+      // - **Explicit caller opt-in (legacy path, Lens flow):** `transcribe: true`
+      //   on the POST. The note already has a `_Transcript pending._` stub the
+      //   worker replaces on success — `transcribe_origin: "legacy"` preserves
+      //   the stub-patching behavior.
+      // - **Auto-transcribe (vault#353):** mime-type is `audio/*` AND the
+      //   operator has flipped `auto_transcribe.enabled = true` AND scribe is
+      //   reachable. The caller didn't opt in explicitly; we infer from the
+      //   audio mime-type. `transcribe_origin: "auto"` tells the worker to
+      //   materialize a `<attachment-path>.transcript.md` note on completion.
+      //
+      // Explicit `transcribe: true` wins — if the caller asked, we honor that
+      // regardless of the auto-transcribe toggle (back-compat).
+      const explicitOptIn = body.transcribe === true;
+      const autoOptIn = !explicitOptIn && shouldAutoTranscribe(body.mimeType);
+      const attMeta = (explicitOptIn || autoOptIn)
+        ? {
+            transcribe_status: "pending" as const,
+            transcribe_requested_at: new Date().toISOString(),
+            transcribe_origin: (explicitOptIn ? "legacy" : "auto") as "legacy" | "auto",
+          }
         : undefined;
 
       const attachment = await store.addAttachment(note.id, body.path, body.mimeType, attMeta);
 
-      if (body.transcribe) {
+      if (explicitOptIn) {
         const noteMeta = (note.metadata as Record<string, unknown> | undefined) ?? {};
         if (noteMeta.transcribe_stub !== true) {
           await store.updateNote(note.id, {
@@ -874,6 +942,33 @@ async function handleNotesInner(
     return json({ error: "Method not allowed" }, 405);
   }
 
+  // POST /notes/:idOrPath/retry-transcription — vault#353 design Q5.
+  //
+  // 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.
+  //
+  // 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)
+  //      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);
+    const note = await resolveNote(store, idOrPath);
+    if (!note) return json({ error: "Not found" }, 404);
+    if (!noteWithinTagScope(note, tagScope.allowed, tagScope.raw)) {
+      return json({ error: "Not found" }, 404);
+    }
+    return handleRetryTranscription(store, note, vault);
+  }
+
   if (sub !== "") return json({ error: "Not found" }, 404);
 
   // GET /notes/:idOrPath — single note
@@ -1213,7 +1308,7 @@ async function handleNotesInner(
     }
   }
 
-  // DELETE /notes/:idOrPath — admin only (enforced at server level)
+  // DELETE /notes/:idOrPath — vault:write (no admin gate; consistent with verbForMethod)
   if (method === "DELETE") {
     const note = await resolveNote(store, idOrPath);
     if (!note) return json({ error: "Not found" }, 404);
@@ -1823,6 +1918,128 @@ ${rendered}
   });
 }
 
+// ---------------------------------------------------------------------------
+// Retry transcription (vault#353 design Q5)
+// ---------------------------------------------------------------------------
+
+/**
+ * Re-enqueue the original audio attachment for a `transcript_status: failed`
+ * transcript note. Steps:
+ *
+ *   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.
+ */
+async function handleRetryTranscription(
+  store: Store,
+  note: Note,
+  vault: string,
+): Promise<Response> {
+  const meta = (note.metadata as Record<string, unknown> | undefined) ?? {};
+  if (typeof meta.transcript_status !== "string") {
+    return json(
+      {
+        error: "invalid_target",
+        message: "Target note is not a transcript note (no transcript_status frontmatter).",
+      },
+      400,
+    );
+  }
+  if (meta.transcript_status !== "failed") {
+    return json(
+      {
+        error: "not_failed",
+        message: `Transcript note status is "${meta.transcript_status}" — only failed transcripts can be retried.`,
+        transcript_status: meta.transcript_status,
+      },
+      400,
+    );
+  }
+  const attachmentId = typeof meta.transcript_attachment_id === "string"
+    ? meta.transcript_attachment_id
+    : undefined;
+  if (!attachmentId) {
+    return json(
+      {
+        error: "missing_attachment_id",
+        message: "Transcript note has no `transcript_attachment_id` — can't locate the original audio.",
+      },
+      400,
+    );
+  }
+  const attachment = await store.getAttachment(attachmentId);
+  if (!attachment) {
+    return json(
+      {
+        error: "attachment_missing",
+        message: `Original audio attachment ${attachmentId} no longer exists in the vault.`,
+      },
+      404,
+    );
+  }
+  // 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, attachment.path));
+  if (!audioFilePath.startsWith(normalize(assetsRoot)) || !existsSync(audioFilePath)) {
+    return json(
+      {
+        error: "audio_missing",
+        message: `Original audio file at "${attachment.path}" no longer exists on disk.`,
+      },
+      404,
+    );
+  }
+
+  // Reset transcribe_status. Worker reads this row, sees "pending", processes
+  // it. Preserve `transcribe_origin: "auto"` so the worker materializes the
+  // transcript note (overwriting this failed note in place).
+  const attMeta = { ...(attachment.metadata ?? {}) } as Record<string, unknown>;
+  attMeta.transcribe_status = "pending";
+  attMeta.transcribe_requested_at = new Date().toISOString();
+  attMeta.transcribe_origin = "auto";
+  delete attMeta.transcribe_backoff_until;
+  delete attMeta.transcribe_error;
+  delete attMeta.transcribe_error_code;
+  delete attMeta.transcribe_attempts;
+  await store.setAttachmentMetadata(attachment.id, attMeta);
+
+  // Kick the worker for an event-driven re-run (no 30s sweep wait). The
+  // worker re-reads the row + processes immediately. If the worker isn't
+  // registered (scribe not configured this boot), we still reset the row;
+  // the next boot's sweep will pick it up. The 503 path is for callers that
+  // want certainty — but for v0.6 the sweep guarantee is enough.
+  const { getTranscriptionWorker } = await import("./transcription-registry.ts");
+  const worker = getTranscriptionWorker();
+  if (worker) {
+    // Refresh the attachment after the metadata write so the worker's
+    // in-process dedupe check sees pending.
+    const fresh = await store.getAttachment(attachment.id) ?? attachment;
+    // Fire-and-forget — the response shouldn't wait on transcription.
+    void worker.kick(vault, fresh);
+  }
+
+  return json(
+    {
+      status: "queued",
+      attachment_id: attachment.id,
+      attachment_path: attachment.path,
+      transcript_note_id: note.id,
+      worker: worker ? "kicked" : "sweep-only",
+    },
+    202,
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Storage (file upload/serve) — kept as-is, Daily needs it
 // ---------------------------------------------------------------------------

package/src/routing.test.ts

@@ -911,7 +911,6 @@ describe("/.parachute/info + /.parachute/icon.svg", () => {
       tagline: string;
       version: string;
       iconUrl: string;
-      kind: string;
     };
     expect(body).toEqual({
       name: "parachute-vault",
@@ -919,8 +918,11 @@ describe("/.parachute/info + /.parachute/icon.svg", () => {
       tagline: expect.stringContaining("knowledge graph"),
       version: pkg.version,
       iconUrl: "/vault/journal/.parachute/icon.svg",
-      kind: "api",
     });
+    // `kind` retired from the info-endpoint response per hub#330 (companion
+    // to vault#359's module.json drop). Pin its absence so regressions are
+    // surfaced — the shape is a locked contract with the hub.
+    expect(body).not.toHaveProperty("kind");
   });
 
   test("info iconUrl is vault-scoped and points at a live icon handler", async () => {

package/src/routing.ts

@@ -132,11 +132,11 @@ function handleParachuteInfo(vaultName: string): Response {
     tagline: "Agent-native knowledge graph — notes, tags, links, attachments over REST + MCP",
     version: pkg.version,
     iconUrl: `/vault/${vaultName}/.parachute/icon.svg`,
-    // Hub renders `kind: "api"` cards as an expandable detail panel (MCP URL,
-    // OAuth link, version) rather than navigating to the API's root. Vault
-    // has no browser UI, so navigating to it shows raw JSON — not useful.
-    kind: "api",
   };
+  // `kind` was previously emitted here (and matched module.json) to let the
+  // hub branch its card rendering on api vs ui. Retired per hub#330 — the hub
+  // now infers presentation from the response shape itself. Companion to
+  // vault#359 (manifest drop); closes part of hub#340.
   return Response.json(body, {
     headers: { "Access-Control-Allow-Origin": "*" },
   });