@openparachute/vault 0.4.8 → 0.4.9-rc.10

package/src/module-config.ts

@@ -19,8 +19,11 @@
  *   - port:                 GlobalConfig.port, exposed read-only.
  *   - autoTranscribe.*:     vault↔scribe handoff (vault#353, design 2026-05-21
  *                           Part 2). Three nested fields per design Q4:
- *       - enabled:          boolean toggle, default false (persisted in
- *                           GlobalConfig.auto_transcribe.enabled).
+ *       - enabled:          boolean toggle, default true when scribe is
+ *                           reachable (persisted in
+ *                           GlobalConfig.auto_transcribe.enabled). Default
+ *                           flipped from off → on so installing scribe is
+ *                           the only opt-in signal needed.
  *       - scribeUrl:        readOnly — resolved per-process from
  *                           `~/.parachute/services.json` via
  *                           `scribe-discovery.ts`. Operators can't point at an
@@ -69,10 +72,10 @@ export function buildConfigSchema(): ModuleConfigSchema {
         properties: {
           enabled: {
             type: "boolean",
-            default: false,
+            default: true,
             title: "Enable auto-transcription",
             description:
-              "Master toggle. When false, audio uploads land normally without any scribe interaction. Global — persisted in `GlobalConfig.auto_transcribe.enabled` and applies to every vault on this server. Per-vault control is a future enhancement when multi-vault deployments need it.",
+              "Master toggle. Default on — audio uploads transcribe automatically when scribe is reachable. Set to false to disable. Global — persisted in `GlobalConfig.auto_transcribe.enabled` and applies to every vault on this server. Per-vault control is a future enhancement when multi-vault deployments need it.",
           },
           scribeUrl: {
             type: "string",
@@ -139,7 +142,10 @@ export function buildConfigValues(
   return {
     audio_retention: vaultConfig.audio_retention ?? "keep",
     autoTranscribe: {
-      enabled: globalConfig.auto_transcribe?.enabled ?? false,
+      // Match shouldAutoTranscribe's `?? true` so the admin SPA displays
+      // the same value runtime uses. An unset config row shows `true`
+      // because that's what vault will actually do on the next audio upload.
+      enabled: globalConfig.auto_transcribe?.enabled ?? true,
       scribeUrl,
     },
     // Legacy alias mirrors `autoTranscribe.scribeUrl` so hubs reading the

package/src/routing.test.ts

@@ -17,7 +17,7 @@
  * never touch ~/.parachute.
  */
 
-import { describe, test, expect, beforeEach, afterEach, afterAll } from "bun:test";
+import { describe, test, expect, beforeAll, beforeEach, afterEach, afterAll } from "bun:test";
 import { rmSync, existsSync, mkdirSync, writeFileSync } from "fs";
 import { join } from "path";
 import { tmpdir } from "os";
@@ -606,6 +606,24 @@ describe("MCP 401 WWW-Authenticate challenge (RFC 9728)", () => {
 
 const HUB_ORIGIN = "http://127.0.0.1:1939";
 
+// Process-env isolation: sibling test files (tokens-routes.test.ts,
+// auth-hub-jwt.test.ts) set PARACHUTE_HUB_ORIGIN in their own beforeAll
+// hooks. Bun's test runner shares a single process across test files,
+// and when file-ordering puts those before this one, their hook-set
+// value can still be live when our tests run. Restore the default
+// (unset) here so we test against `DEFAULT_HUB_LOOPBACK`. Caught when
+// vault rc.1 release CI failed with "Received: http://127.0.0.1:34295"
+// — a leaked ephemeral port from another test's fixture.
+let _prevHubOriginRouting: string | undefined;
+beforeAll(() => {
+  _prevHubOriginRouting = process.env.PARACHUTE_HUB_ORIGIN;
+  delete process.env.PARACHUTE_HUB_ORIGIN;
+});
+afterAll(() => {
+  if (_prevHubOriginRouting === undefined) delete process.env.PARACHUTE_HUB_ORIGIN;
+  else process.env.PARACHUTE_HUB_ORIGIN = _prevHubOriginRouting;
+});
+
 describe("per-vault OAuth discovery (hub-rooted after workstream E)", () => {
   test("AS metadata names the hub as issuer + endpoints", async () => {
     createVault("journal");
@@ -1804,3 +1822,76 @@ describe("/vault/<name>/.parachute/mirror — auth + dispatch", () => {
     expect([405, 503]).toContain(res.status);
   });
 });
+
+// ---------------------------------------------------------------------------
+// /vault/<name>/.parachute/mirror/run-now — manual-trigger endpoint added
+// alongside the SPA UI. Tests pin the auth gate matches the parent
+// endpoint; handler-shape coverage lives in mirror-routes.test.ts.
+// ---------------------------------------------------------------------------
+
+describe("/vault/<name>/.parachute/mirror/run-now — auth + dispatch", () => {
+  test("unauthenticated → 401", async () => {
+    createVault("journal");
+    const p = "/vault/journal/.parachute/mirror/run-now";
+    const res = await route(
+      new Request(`http://localhost:1940${p}`, { method: "POST" }),
+      p,
+    );
+    expect(res.status).toBe(401);
+  });
+
+  test("vault:read token → 403 insufficient_scope", async () => {
+    createVault("journal");
+    const store = getVaultStore("journal");
+    const { fullToken } = generateToken();
+    createToken(store.db, fullToken, {
+      label: "reader",
+      permission: "read",
+      scopes: ["vault:read"],
+    });
+    const p = "/vault/journal/.parachute/mirror/run-now";
+    const res = await route(
+      new Request(`http://localhost:1940${p}`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${fullToken}` },
+      }),
+      p,
+    );
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error_type?: string; required_scope?: string };
+    expect(body.error_type).toBe("insufficient_scope");
+    expect(body.required_scope).toBe("vault:admin");
+  });
+
+  test("admin token reaches the handler — 503 when manager not wired, 400 when wired+disabled", async () => {
+    // Mirrors the parent endpoint's harness behavior: test ordering
+    // determines whether a previous test wired a manager. Either way
+    // the auth gate passed, which is what this routing-level test pins.
+    createVault("journal");
+    const token = createAdminToken("journal");
+    const p = "/vault/journal/.parachute/mirror/run-now";
+    const res = await route(
+      new Request(`http://localhost:1940${p}`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${token}` },
+      }),
+      p,
+    );
+    expect([400, 503]).toContain(res.status);
+  });
+
+  test("non-POST methods return 405 when manager is wired", async () => {
+    createVault("journal");
+    const token = createAdminToken("journal");
+    const p = "/vault/journal/.parachute/mirror/run-now";
+    const res = await route(
+      new Request(`http://localhost:1940${p}`, {
+        method: "GET",
+        headers: { authorization: `Bearer ${token}` },
+      }),
+      p,
+    );
+    // 503 short-circuits the method check when no manager is wired.
+    expect([405, 503]).toContain(res.status);
+  });
+});

package/src/routing.ts

@@ -72,7 +72,21 @@ import {
 } from "./oauth-discovery.ts";
 import { handleConfigSchema, handleConfig } from "./module-config.ts";
 import { buildAuthStatus } from "./auth-status.ts";
-import { handleMirrorGet, handleMirrorPut } from "./mirror-routes.ts";
+import {
+  handleAuthDelete,
+  handleAuthGet,
+  handleAuthGithubCreateRepo,
+  handleAuthGithubDeviceCode,
+  handleAuthGithubPoll,
+  handleAuthGithubRepos,
+  handleAuthGithubSelectRepo,
+  handleAuthPat,
+  handleMirrorGet,
+  handleMirrorImport,
+  handleMirrorPushNow,
+  handleMirrorPut,
+  handleMirrorRunNow,
+} from "./mirror-routes.ts";
 import { getMirrorManager } from "./mirror-registry.ts";
 
 /**
@@ -511,6 +525,156 @@ export async function route(
     return Response.json({ error: "Method not allowed" }, { status: 405 });
   }
 
+  // /.parachute/mirror/run-now — fire a one-shot export+commit+push pass.
+  // Same admin gate as the GET/PUT above; same manager presence check.
+  // POST-only — a GET would imply "read the result of running" which
+  // isn't the verb (the rolling status is already available on the
+  // parent GET endpoint).
+  if (subpath === "/.parachute/mirror/run-now") {
+    if (!hasScopeForVault(auth.scopes, vaultName, "admin")) {
+      return Response.json(
+        {
+          error: "Forbidden",
+          error_type: "insufficient_scope",
+          message: `This endpoint requires the '${SCOPE_ADMIN}' scope (or '${SCOPE_ADMIN.replace("vault:", `vault:${vaultName}:`)}').`,
+          required_scope: SCOPE_ADMIN,
+          granted_scopes: auth.scopes,
+        },
+        { status: 403 },
+      );
+    }
+    const manager = getMirrorManager();
+    if (!manager) {
+      return Response.json(
+        {
+          error: "Mirror manager not initialized",
+          message:
+            "The vault server hasn't wired a mirror manager yet (no vaults exist, or boot failed). Check logs for [mirror] entries.",
+        },
+        { status: 503 },
+      );
+    }
+    if (req.method === "POST") return handleMirrorRunNow(manager);
+    return Response.json({ error: "Method not allowed" }, { status: 405 });
+  }
+
+  // /.parachute/mirror/push-now — fire `git push` against committed state.
+  // Cut 6 of vault#392. Same admin gate + manager check as run-now;
+  // POST-only. Distinguished from /run-now in that this skips export +
+  // commit, only pushes — for "did my credentials actually work?" flow.
+  if (subpath === "/.parachute/mirror/push-now") {
+    if (!hasScopeForVault(auth.scopes, vaultName, "admin")) {
+      return Response.json(
+        {
+          error: "Forbidden",
+          error_type: "insufficient_scope",
+          message: `This endpoint requires the '${SCOPE_ADMIN}' scope (or '${SCOPE_ADMIN.replace("vault:", `vault:${vaultName}:`)}').`,
+          required_scope: SCOPE_ADMIN,
+          granted_scopes: auth.scopes,
+        },
+        { status: 403 },
+      );
+    }
+    const manager = getMirrorManager();
+    if (!manager) {
+      return Response.json(
+        {
+          error: "Mirror manager not initialized",
+          message:
+            "The vault server hasn't wired a mirror manager yet (no vaults exist, or boot failed). Check logs for [mirror] entries.",
+        },
+        { status: 503 },
+      );
+    }
+    if (req.method === "POST") return handleMirrorPushNow(manager);
+    return Response.json({ error: "Method not allowed" }, { status: 405 });
+  }
+
+  // /.parachute/mirror/import — clone a vault export from git + import.
+  // Admin-gated. POST-only. Synchronous (imports finish in <30s for
+  // typical vaults). See mirror-routes.ts:handleMirrorImport for the
+  // request/response shape + error map. Symmetric counterpart to the
+  // export-to-git flow vault#382 + vault#384 shipped.
+  if (subpath === "/.parachute/mirror/import") {
+    if (!hasScopeForVault(auth.scopes, vaultName, "admin")) {
+      return Response.json(
+        {
+          error: "Forbidden",
+          error_type: "insufficient_scope",
+          message: `This endpoint requires the '${SCOPE_ADMIN}' scope (or '${SCOPE_ADMIN.replace("vault:", `vault:${vaultName}:`)}').`,
+          required_scope: SCOPE_ADMIN,
+          granted_scopes: auth.scopes,
+        },
+        { status: 403 },
+      );
+    }
+    if (req.method !== "POST") {
+      return Response.json({ error: "Method not allowed" }, { status: 405 });
+    }
+    return handleMirrorImport(req, vaultName);
+  }
+
+  // /.parachute/mirror/auth/* — UI-configurable git push credentials.
+  // GitHub OAuth Device Flow + PAT fallback. All admin-gated; the
+  // routes themselves don't carry secrets in their responses
+  // (mirror-routes.ts redacts via sanitizeCredentials).
+  if (subpath.startsWith("/.parachute/mirror/auth")) {
+    if (!hasScopeForVault(auth.scopes, vaultName, "admin")) {
+      return Response.json(
+        {
+          error: "Forbidden",
+          error_type: "insufficient_scope",
+          message: `This endpoint requires the '${SCOPE_ADMIN}' scope (or '${SCOPE_ADMIN.replace("vault:", `vault:${vaultName}:`)}').`,
+          required_scope: SCOPE_ADMIN,
+          granted_scopes: auth.scopes,
+        },
+        { status: 403 },
+      );
+    }
+    const manager = getMirrorManager();
+    if (!manager) {
+      return Response.json(
+        {
+          error: "Mirror manager not initialized",
+          message:
+            "The vault server hasn't wired a mirror manager yet (no vaults exist, or boot failed). Check logs for [mirror] entries.",
+        },
+        { status: 503 },
+      );
+    }
+
+    if (subpath === "/.parachute/mirror/auth") {
+      if (req.method === "GET") return handleAuthGet();
+      if (req.method === "DELETE") return handleAuthDelete(manager);
+      return Response.json({ error: "Method not allowed" }, { status: 405 });
+    }
+    if (subpath === "/.parachute/mirror/auth/github/device-code") {
+      if (req.method === "POST") return handleAuthGithubDeviceCode();
+      return Response.json({ error: "Method not allowed" }, { status: 405 });
+    }
+    if (subpath === "/.parachute/mirror/auth/github/poll") {
+      if (req.method === "POST") return handleAuthGithubPoll(req, manager);
+      return Response.json({ error: "Method not allowed" }, { status: 405 });
+    }
+    if (subpath === "/.parachute/mirror/auth/github/repos") {
+      if (req.method === "GET") return handleAuthGithubRepos();
+      return Response.json({ error: "Method not allowed" }, { status: 405 });
+    }
+    if (subpath === "/.parachute/mirror/auth/github/create-repo") {
+      if (req.method === "POST") return handleAuthGithubCreateRepo(req);
+      return Response.json({ error: "Method not allowed" }, { status: 405 });
+    }
+    if (subpath === "/.parachute/mirror/auth/github/select-repo") {
+      if (req.method === "POST") return handleAuthGithubSelectRepo(req, manager);
+      return Response.json({ error: "Method not allowed" }, { status: 405 });
+    }
+    if (subpath === "/.parachute/mirror/auth/pat") {
+      if (req.method === "POST") return handleAuthPat(req, manager);
+      return Response.json({ error: "Method not allowed" }, { status: 405 });
+    }
+    return Response.json({ error: "Not found" }, { status: 404 });
+  }
+
   const apiMatch = subpath.match(/^\/api(\/.*)?$/);
   if (!apiMatch) {
     return Response.json({ error: "Not found" }, { status: 404 });

package/src/server.ts

@@ -315,18 +315,31 @@ const server = Bun.serve({
 console.log(`Parachute Vault server listening on http://${hostname}:${server.port}`);
 
 // Graceful shutdown — best-effort drain of in-flight note-mutation hooks.
+//
+// Order matters under the event-driven mirror shape (vault#382):
+//   1. MirrorManager.stop() runs FIRST so it can unsubscribe from hooks
+//      cleanly + cancel its debounce timer. Otherwise the registry drain
+//      below would wait on the manager's hook handler that just queued
+//      itself after a final mutation.
+//   2. Then drain hooks + stop the transcription worker in parallel —
+//      neither depends on the other.
+//
+// The whole thing races a 5s timeout so a stuck handler doesn't hang
+// shutdown indefinitely.
 async function shutdown(signal: string): Promise<void> {
   console.log(`\n[${signal}] shutting down; in-flight hooks: ${defaultHookRegistry.inFlightCount}`);
   try {
     await Promise.race([
-      Promise.all([
-        defaultHookRegistry.drain(),
-        transcriptionWorker?.stop() ?? Promise.resolve(),
-        // Mirror manager: cancel the watch interval + let any in-flight
-        // export cycle settle. `stop` already has its own brief timeout
-        // (250ms) so this doesn't block the larger shutdown race.
-        mirrorManager?.stop() ?? Promise.resolve(),
-      ]),
+      (async () => {
+        // Mirror stop first — unsubscribes + cancels its debounce. Its
+        // internal soft-settle timeout (250ms) bounds the wait.
+        await (mirrorManager?.stop() ?? Promise.resolve());
+        // Then drain hooks + stop the transcription worker in parallel.
+        await Promise.all([
+          defaultHookRegistry.drain(),
+          transcriptionWorker?.stop() ?? Promise.resolve(),
+        ]);
+      })(),
       new Promise<void>((resolve) => setTimeout(resolve, 5000)),
     ]);
   } catch (err) {

package/src/token-store.ts

@@ -63,6 +63,26 @@ export interface Token {
   expires_at: string | null;
   created_at: string;
   last_used_at: string | null;
+  /**
+   * Provenance (v19). 'mcp_mint' = minted via manage-token MCP tool;
+   * NULL = pre-v19 / CLI / REST / YAML-import. Used by manage-token list
+   * to restrict the surface to MCP-session-managed tokens. See vault#376.
+   */
+  created_via: string | null;
+  /**
+   * Session pin (v19). When this token was minted via manage-token, this
+   * is the display id (`t_<prefix>`) of the calling session's token (for
+   * pvt_* MCP sessions) or the hub JWT's jti claim (for hub-issued
+   * sessions). NULL otherwise.
+   */
+  parent_jti: string | null;
+  /**
+   * Soft-revoke timestamp (v19). When set, `resolveToken` returns null
+   * and the row stays in place for audit history. manage-token revoke is
+   * idempotent — calling revoke a second time on the same jti is a no-op
+   * with ok=true. NULL = active.
+   */
+  revoked_at: string | null;
 }
 
 export interface ResolvedToken {
@@ -88,6 +108,12 @@ export interface ResolvedToken {
    * vault. See vault#257.
    */
   vault_name: string | null;
+  /**
+   * Display id (`t_<hashprefix>`) of THIS token. Surfaced so callers that
+   * later mint child tokens (manage-token MCP tool) can stamp parent_jti
+   * without re-derivation. Pre-v19 lookups still compute this on the fly.
+   */
+  jti: string;
 }
 
 /**
@@ -149,6 +175,17 @@ export function createToken(
      */
     vault_name?: string | null;
     expires_at?: string | null;
+    /**
+     * Provenance tag (v19). `'mcp_mint'` for tokens minted via the
+     * manage-token MCP tool; omit/null for CLI / REST / YAML paths.
+     */
+    created_via?: string | null;
+    /**
+     * Session pin (v19). Display id (`t_<prefix>`) or hub JWT `jti` of the
+     * caller that minted this token via manage-token. Used by the
+     * manage-token list/revoke surface to scope itself to one session.
+     */
+    parent_jti?: string | null;
   },
 ): Token {
   const tokenHash = hashKey(fullToken);
@@ -159,10 +196,12 @@ export function createToken(
   const scopedTags = opts.scoped_tags && opts.scoped_tags.length > 0 ? opts.scoped_tags : null;
   const scopedTagsStr = scopedTags ? JSON.stringify(scopedTags) : null;
   const vaultName = opts.vault_name ?? null;
+  const createdVia = opts.created_via ?? null;
+  const parentJti = opts.parent_jti ?? null;
 
   db.prepare(`
-    INSERT INTO tokens (token_hash, label, permission, scopes, scoped_tags, scope_tag, scope_path_prefix, expires_at, created_at, vault_name)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    INSERT INTO tokens (token_hash, label, permission, scopes, scoped_tags, scope_tag, scope_path_prefix, expires_at, created_at, vault_name, created_via, parent_jti)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
   `).run(
     tokenHash,
     opts.label,
@@ -174,6 +213,8 @@ export function createToken(
     opts.expires_at ?? null,
     now,
     vaultName,
+    createdVia,
+    parentJti,
   );
 
   return {
@@ -187,6 +228,9 @@ export function createToken(
     expires_at: opts.expires_at ?? null,
     created_at: now,
     last_used_at: null,
+    created_via: createdVia,
+    parent_jti: parentJti,
+    revoked_at: null,
   };
 }
 
@@ -200,8 +244,15 @@ export function resolveToken(db: Database, providedToken: string): ResolvedToken
   // preimage, which is computationally infeasible regardless of timing leaks.
   const candidateHash = hashKey(providedToken);
 
+  // Defensive SELECT for revoked_at: the column exists post-v19, but a
+  // freshly-opened ResolvedToken-only test fixture might run on a DB the
+  // migration hasn't touched. SQLite returns NULL for missing columns when
+  // the table is queried via prepared statements only after migration; here
+  // initSchema fires on every store-open path, so the column is guaranteed
+  // present in production. Tests instantiating bare DBs against this
+  // module are expected to call initSchema first.
   const row = db.prepare(`
-    SELECT token_hash, permission, scopes, scoped_tags, expires_at, vault_name
+    SELECT token_hash, permission, scopes, scoped_tags, expires_at, vault_name, revoked_at
     FROM tokens WHERE token_hash = ?
   `).get(candidateHash) as {
     token_hash: string;
@@ -210,10 +261,16 @@ export function resolveToken(db: Database, providedToken: string): ResolvedToken
     scoped_tags: string | null;
     expires_at: string | null;
     vault_name: string | null;
+    revoked_at: string | null;
   } | null;
 
   if (!row) return null;
 
+  // Soft-revoked tokens never authenticate (v19). The row stays in place
+  // for audit; resolveToken just treats it as not-found from the caller's
+  // perspective.
+  if (row.revoked_at) return null;
+
   // Check expiry
   if (row.expires_at && new Date(row.expires_at) < new Date()) {
     return null;
@@ -229,8 +286,9 @@ export function resolveToken(db: Database, providedToken: string): ResolvedToken
   const scopes = hasVaultScope ? parsed : legacyPermissionToScopes(permission);
   const legacyDerived = !hasVaultScope;
   const scoped_tags = parseScopedTags(row.scoped_tags);
+  const jti = `t_${row.token_hash.slice(7, 19)}`;
 
-  return { permission, scopes, legacyDerived, scoped_tags, vault_name: row.vault_name };
+  return { permission, scopes, legacyDerived, scoped_tags, vault_name: row.vault_name, jti };
 }
 
 /**
@@ -252,7 +310,8 @@ export function listTokens(
   const params = opts.vaultName ? [opts.vaultName] : [];
   const rows = db.prepare(`
     SELECT token_hash, label, permission, scope_tag, scope_path_prefix,
-           scoped_tags, vault_name, expires_at, created_at, last_used_at
+           scoped_tags, vault_name, expires_at, created_at, last_used_at,
+           created_via, parent_jti, revoked_at
     FROM tokens ${where}
     ORDER BY created_at DESC
   `).all(...params) as (Omit<Token, "scoped_tags"> & { scoped_tags: string | null })[];
@@ -266,6 +325,100 @@ export function listTokens(
   }));
 }
 
+/**
+ * List tokens minted via the manage-token MCP tool by a given session
+ * (parent_jti). Used by `manage-token` action="list" to scope its surface
+ * to its own session's mints — operators with multiple MCP sessions open
+ * don't see each other's tokens, and CLI/REST-minted tokens never appear.
+ *
+ * Returns metadata only (no token-hash exposure beyond the display id);
+ * the display id is what the caller uses to revoke. Includes `revoked_at`
+ * so the UI can render a tombstone for soft-revoked rows.
+ */
+export function listMcpMintedTokens(
+  db: Database,
+  parentJti: string,
+  vaultName: string,
+): Array<{
+  jti: string;
+  label: string;
+  scopes: string[];
+  scoped_tags: string[] | null;
+  created_at: string;
+  expires_at: string | null;
+  revoked_at: string | null;
+}> {
+  const rows = db.prepare(`
+    SELECT token_hash, label, scopes, scoped_tags, created_at, expires_at, revoked_at
+    FROM tokens
+    WHERE created_via = 'mcp_mint'
+      AND parent_jti = ?
+      AND vault_name = ?
+    ORDER BY created_at DESC
+  `).all(parentJti, vaultName) as {
+    token_hash: string;
+    label: string;
+    scopes: string | null;
+    scoped_tags: string | null;
+    created_at: string;
+    expires_at: string | null;
+    revoked_at: string | null;
+  }[];
+  return rows.map((r) => ({
+    jti: `t_${r.token_hash.slice(7, 19)}`,
+    label: r.label,
+    scopes: parseScopes(r.scopes),
+    scoped_tags: parseScopedTags(r.scoped_tags),
+    created_at: r.created_at,
+    expires_at: r.expires_at,
+    revoked_at: r.revoked_at,
+  }));
+}
+
+/**
+ * Soft-revoke a token minted via manage-token, scoped to the session that
+ * minted it. Idempotent: revoking an already-revoked or never-existent jti
+ * returns the same shape; second-call to revoke is intentionally still
+ * ok=true so the AI's revoke step doesn't surface a confusing failure on a
+ * retry after a network blip. The row stays in place for audit trail —
+ * resolveToken treats revoked_at-set rows as not-found.
+ *
+ * `parentJti` + `vaultName` scope the lookup: a token minted by a
+ * different MCP session (or against a different vault) returns ok=false.
+ * Returns { ok: true, already_revoked? } when the operation matched a row.
+ */
+export function softRevokeMcpToken(
+  db: Database,
+  jti: string,
+  parentJti: string,
+  vaultName: string,
+): { ok: true; already_revoked: boolean } | { ok: false; reason: "not_found" } {
+  if (!jti.startsWith("t_")) {
+    return { ok: false, reason: "not_found" };
+  }
+  const hashPrefix = jti.slice(2);
+  const row = db.prepare(`
+    SELECT token_hash, revoked_at FROM tokens
+    WHERE token_hash LIKE ?
+      AND created_via = 'mcp_mint'
+      AND parent_jti = ?
+      AND vault_name = ?
+    LIMIT 1
+  `).get(`sha256:${hashPrefix}%`, parentJti, vaultName) as {
+    token_hash: string;
+    revoked_at: string | null;
+  } | null;
+
+  if (!row) return { ok: false, reason: "not_found" };
+  if (row.revoked_at) {
+    // Second revoke: idempotent — already done, surface true with the flag.
+    return { ok: true, already_revoked: true };
+  }
+  db.prepare("UPDATE tokens SET revoked_at = ? WHERE token_hash = ?")
+    .run(new Date().toISOString(), row.token_hash);
+  return { ok: true, already_revoked: false };
+}
+
 /**
  * Find tokens whose `scoped_tags` allowlist references the given root tag.
  * Used by tag-delete and tag-merge to fail-closed (409) when removing a

package/src/transcription-worker.ts

@@ -554,10 +554,15 @@ export function registerTranscriptionHook(
   return registry.onAttachment({
     name: "transcription-kickoff",
     event: "created",
-    when: (att) =>
-      (att.metadata as { transcribe_status?: string } | undefined)
-        ?.transcribe_status === "pending",
-    handler: async (attachment, store) => {
+    when: (att) => {
+      // Only "created" payloads reach this predicate (we don't subscribe
+      // to "deleted"), so `metadata` is populated. The union widening
+      // post-deletion-events just means we narrow here defensively.
+      const meta = (att as Attachment).metadata as { transcribe_status?: string } | undefined;
+      return meta?.transcribe_status === "pending";
+    },
+    handler: async (payload, store) => {
+      const attachment = payload as Attachment;
       const vault = resolveVault(store);
       if (!vault) {
         logger.error(

package/src/triggers.ts

@@ -29,7 +29,7 @@ import { join, normalize } from "path";
 import { mkdirSync, readFileSync, writeFileSync, existsSync } from "fs";
 import crypto from "node:crypto";
 import type { Note, Store, Attachment } from "../core/src/types.ts";
-import type { HookRegistry, HookEvent } from "../core/src/hooks.ts";
+import type { HookRegistry, HookEvent, NoteHookPayload } from "../core/src/hooks.ts";
 import type { TriggerConfig, TriggerWhen } from "./config.ts";
 import { getVaultNameForStore } from "./vault-store.ts";
 import { assetsDir } from "./routes.ts";
@@ -56,6 +56,10 @@ export function buildPredicate(when: TriggerWhen, triggerName: string): (note: N
   const pendingKey = `${triggerName}_pending_at`;
   const renderedKey = `${triggerName}_rendered_at`;
 
+  // Hook dispatcher passes `NoteHookPayload` (Note | DeletedNoteRef). All
+  // triggers default to events `["created", "updated"]` so deleted shapes
+  // never reach this predicate, but we still type the parameter as Note
+  // — narrowing here keeps the rest of the predicate body unchanged.
   return (note: Note) => {
     const meta = note.metadata as Record<string, unknown> | undefined;
 
@@ -310,8 +314,17 @@ export function registerTriggers(
     const unregister = hooks.onNote({
       name: trigger.name,
       event: events,
-      when: predicate,
-      handler: async (note: Note, store: Store, hookEvent?: HookEvent) => {
+      when: (payload: NoteHookPayload) => {
+        // Triggers don't subscribe to "deleted"; if the union ever
+        // widens via config, the predicate sees a partial shape that
+        // simply doesn't match anything tag/metadata-based and returns
+        // false. Safe by construction.
+        return predicate(payload as Note);
+      },
+      handler: async (payload: NoteHookPayload, store: Store, hookEvent?: HookEvent) => {
+        // Same shape contract as the predicate — triggers don't
+        // subscribe to deleted events, so narrow back to Note.
+        const note = payload as Note;
         const existingMeta = (note.metadata as Record<string, unknown> | undefined) ?? {};
 
         // Handler-side re-check (same race-window protection as the old hooks)