@claude-transcripts/cli 0.0.16 → 0.1.0

package/dist/cli.js

@@ -29899,7 +29899,18 @@ var CLI_SPEC = {
           description: "entries per chunk doc"
         },
         { name: "--no-content", description: "byte-range chunks only (no turn content)" },
-        { name: "--force", description: "re-process sessions already adopted" },
+        {
+          name: "--force",
+          description: "re-process adopted sessions (deletes their derived docs, then rebuilds)"
+        },
+        {
+          name: "--replace-live",
+          description: "with --force: also replace live-recorded sessions (loses hook provenance)"
+        },
+        {
+          name: "--repair",
+          description: "add missing chunk docs to adopted sessions; leaves summary + events alone"
+        },
         {
           name: "--session",
           type: "string",
@@ -29978,7 +29989,11 @@ var CLI_SPEC = {
           default: "status",
           description: "`run` reads one event payload from stdin (Claude Code calls this)"
         },
-        { name: "--dry-run", description: "with `install`: show the change without writing" }
+        { name: "--dry-run", description: "with `install`: show the change without writing" },
+        {
+          name: "--force",
+          description: "with `install`: register even if the plugin already does"
+        }
       ],
       examples: ["hook status", "hook install --dry-run"]
     },
@@ -39157,9 +39172,11 @@ async function errorDetail(res) {
     return "";
   }
 }
-async function exists(path) {
+async function getOrNull(path) {
   const res = await fetch(`${base2()}${path}`);
-  return res.ok;
+  if (!res.ok)
+    return null;
+  return await res.json();
 }
 async function putStream(path, filePath, contentType) {
   const res = await fetch(`${base2()}${path}`, {
@@ -39366,7 +39383,10 @@ var migrateDown = async (migrateDownBody, options) => {
 // packages/cli/src/lib/sink.ts
 class DryRunSink {
   label = "dry-run";
-  async hasSummary() {
+  async existingSession() {
+    return null;
+  }
+  async hasTurns() {
     return false;
   }
   async resetSession(sessionId) {
@@ -39392,8 +39412,12 @@ class DryRunSink {
 
 class WebapiSink {
   label = webapiUrl();
-  async hasSummary(sessionId) {
-    return exists(`/api/sessions/${encodeURIComponent(sessionId)}`);
+  async existingSession(sessionId) {
+    return getOrNull(`/api/sessions/${encodeURIComponent(sessionId)}`);
+  }
+  async hasTurns(sessionId) {
+    const res = await getOrNull(`/api/sessions/${encodeURIComponent(sessionId)}/turns?limit=1`);
+    return (res?.turns?.length ?? 0) > 0;
   }
   async resetSession(sessionId) {
     const res = await resetSession(sessionId);
@@ -39423,6 +39447,23 @@ function makeSink(opts) {
 }
 
 // packages/cli/src/commands/backfill.ts
+function planReingest(existing, opts) {
+  if (!existing)
+    return { action: "adopt" };
+  if (opts.repair) {
+    if (existing.status === "running")
+      return { action: "skip", reason: "running" };
+    if (opts.hasTurns)
+      return { action: "skip", reason: "has-turns" };
+    return { action: "repair" };
+  }
+  if (!opts.force)
+    return { action: "skip", reason: "already-adopted" };
+  if (existing.source === "live" && !opts.replaceLive) {
+    return { action: "skip", reason: "live-record" };
+  }
+  return { action: "adopt" };
+}
 async function runBackfill(argv) {
   const { options } = parseFlags(argv);
   const dryRun = options["dry-run"] === true;
@@ -39434,6 +39475,8 @@ async function runBackfill(argv) {
   const maxEntriesPerChunk = chunkSizeOpt ? Number(chunkSizeOpt) : undefined;
   const withContent = options["no-content"] !== true;
   const force = options.force === true;
+  const replaceLive = options["replace-live"] === true;
+  const repair = options.repair === true;
   const onlySession = strOpt(options, "session");
   const only = new Set(onlySession ? [onlySession] : []);
   const sink = makeSink({ dryRun, webapiUrl: strOpt(options, "webapi") });
@@ -39442,30 +39485,69 @@ async function runBackfill(argv) {
     console.error("backfill: adopted anyway and existing ones are skipped).");
     return 2;
   }
+  if (repair && (force || replaceLive)) {
+    console.error("backfill: --repair cannot be combined with --force or --replace-live \u2014");
+    console.error("backfill: repair adds what is missing, those replace what is there.");
+    return 2;
+  }
+  if (replaceLive && !force) {
+    console.error("backfill: --replace-live only applies with --force (it widens what --force");
+    console.error("backfill: may overwrite; on its own it would widen nothing).");
+    return 2;
+  }
   const who = `host=${host}${actor ? `, actor=${actor}` : ""}`;
   console.log(`backfill: scanning ${root} \u2192 ${sink.label}${dryRun ? " (dry-run)" : ""}  [${who}]`);
   const found = await discoverTranscripts(root);
   console.log(`backfill: ${found.length} transcript(s) found`);
+  if (repair) {
+    console.log("backfill: --repair \u2014 adding missing chunk docs only; summaries and event markers " + "are left untouched");
+  }
   if (force) {
     const scope = only.size ? `${only.size} named session(s)` : "every already-adopted session";
-    console.log(`backfill: --force \u2014 re-processing ${scope} (derived docs are replaced)`);
+    console.log(`backfill: --force \u2014 re-processing ${scope} (derived docs are deleted, then rebuilt)`);
+    console.log(replaceLive ? "backfill: --replace-live \u2014 live-recorded sessions WILL be replaced by reconstructions" : "backfill: live-recorded sessions are left alone (--replace-live overrides)");
   }
   let written = 0;
   let skipped = 0;
   let failed = 0;
   let sidechains = 0;
   let reprocessed = 0;
+  let refusedLive = 0;
+  let repaired = 0;
   for (const t of found) {
     try {
       if (only.size && !only.has(t.sessionId)) {
         skipped++;
         continue;
       }
-      if (!dryRun && await sink.hasSummary(t.sessionId)) {
-        if (!force) {
-          skipped++;
-          continue;
+      const existing = dryRun ? null : await sink.existingSession(t.sessionId);
+      const hasTurns = repair && existing ? await sink.hasTurns(t.sessionId) : false;
+      const plan = planReingest(existing, { force, replaceLive, repair, hasTurns });
+      if (plan.action === "skip") {
+        if (plan.reason === "live-record") {
+          console.warn(`  ! ${t.sessionId}: skipped \u2014 recorded live. --force would delete that record and ` + "rebuild it from the transcript, losing provenance only the hook had. Pass " + "--replace-live to do that deliberately.");
+          refusedLive++;
+        }
+        if (plan.reason === "running") {
+          console.log(`  \xB7 ${t.sessionId}: skipped \u2014 still running`);
+        }
+        if (plan.reason === "has-turns") {
+          console.log(`  \xB7 ${t.sessionId}: skipped \u2014 already has turn content`);
         }
+        skipped++;
+        continue;
+      }
+      if (plan.action === "repair") {
+        const jsonl2 = await readTranscript(t.path);
+        const facts2 = deriveSessionFacts(jsonl2, { hostname: host, sessionIdHint: t.sessionId });
+        const chunks = buildChunkDocs(jsonl2, facts2, "backfill", maxEntriesPerChunk, withContent);
+        await sink.putChunks(chunks);
+        await sink.putTranscript(t.sessionId, new TextEncoder().encode(jsonl2));
+        console.log(`  + ${t.sessionId}: added ${chunks.length} chunk doc(s)`);
+        repaired++;
+        continue;
+      }
+      if (existing) {
         const gone = await sink.resetSession(t.sessionId);
         console.log(`  ~ ${t.sessionId}: cleared ${gone.summary} summary, ${gone.events} event(s), ` + `${gone.chunks} chunk(s)`);
         reprocessed++;
@@ -39484,7 +39566,7 @@ async function runBackfill(argv) {
       console.error(`  ! ${t.sessionId}: ${err.message}`);
     }
   }
-  console.log(`backfill: ${written} backfilled${reprocessed ? ` (${reprocessed} re-processed)` : ""}, ` + `${skipped} skipped, ${failed} failed`);
+  console.log(`backfill: ${written} backfilled${repaired ? `, ${repaired} repaired` : ""}` + `${reprocessed ? ` (${reprocessed} re-processed)` : ""}, ` + `${skipped} skipped${refusedLive ? ` (${refusedLive} live, not replaced)` : ""}, ` + `${failed} failed`);
   console.log("backfill: NOTE \u2014 summary + per-event markers + chunk docs reconstructed" + `${sidechains ? `; subagent sub-transcripts (${sidechains} session(s) have them) still TODO` : ""}` + " (see docs/operate/tools.md).");
   if (reprocessed && !dryRun) {
     console.log("backfill: run `claude-transcripts reindex` \u2014 search still holds the old turns.");
@@ -40202,97 +40284,8 @@ async function runExport(argv) {
 }
 
 // packages/cli/src/commands/hook.ts
-import { existsSync as existsSync4, mkdirSync as mkdirSync3, readFileSync as readFileSync7, writeFileSync as writeFileSync3 } from "fs";
-import { dirname } from "path";
-
-// packages/cli/src/hook/announce.ts
-function sessionLink(webapiUrl2, sessionId) {
-  return webapiUrl2 ? `${webapiUrl2.replace(/\/$/, "")}/app/sessions/${sessionId}` : null;
-}
-function recordingBanner(targets, sessionId) {
-  const where = [`couchdb://${targets.couchUrl.replace(/^https?:\/\//, "")}/${targets.sessionsDb}`];
-  if (targets.bucket)
-    where.push(`s3://${targets.bucket}`);
-  if (targets.mirrors.length)
-    where.push(`${targets.mirrors.length} mirror(s)`);
-  const link2 = sessionLink(targets.webapiUrl, sessionId);
-  return `Claude Transcripts \u2014 recording to ${where.join(" + ")}${link2 ? ` \xB7 ${link2}` : ""}`;
-}
-var NOT_RECORDING_BANNER = "Claude Transcripts \u2014 not recording (no instance configured). Run `claude-transcripts install`.";
-function sessionStartEnvelope(out) {
-  if (!out.systemMessage && !out.additionalContext)
-    return null;
-  return {
-    ...out.systemMessage ? { systemMessage: out.systemMessage } : {},
-    ...out.additionalContext ? {
-      hookSpecificOutput: {
-        hookEventName: "SessionStart",
-        additionalContext: out.additionalContext
-      }
-    } : {}
-  };
-}
-function emitSessionStart(out) {
-  try {
-    const envelope = sessionStartEnvelope(out);
-    if (envelope)
-      process.stdout.write(`${JSON.stringify(envelope)}
-`);
-  } catch {}
-}
-
-// packages/cli/src/hook/handlers.ts
-import { readFileSync as readFileSync6 } from "fs";
-
-// packages/cli/src/hook/recall.ts
-var FACTS_TIMEOUT_MS = 2000;
-function isExcluded(cwd2, globs) {
-  for (const g of globs) {
-    try {
-      if (new Bun.Glob(g).match(cwd2))
-        return true;
-    } catch {}
-  }
-  return false;
-}
-async function corpusFacts(webapiUrl2, policy, cwd2, hostname4) {
-  const q = new URLSearchParams({ limit: "1" });
-  if (policy.scope === "project")
-    q.set("cwd", cwd2);
-  else if (policy.scope === "host")
-    q.set("hostname", hostname4);
-  try {
-    const res = await fetch(`${webapiUrl2}/api/sessions?${q}`, {
-      signal: AbortSignal.timeout(FACTS_TIMEOUT_MS)
-    });
-    if (!res.ok)
-      return null;
-    const body = await res.json();
-    return {
-      sessionCount: body.totalCount ?? 0,
-      mostRecent: body.sessions?.[0]?.timestamp
-    };
-  } catch {
-    return null;
-  }
-}
-async function buildPrimer(ctx) {
-  const policy = resolveRecall(ctx.config.recall, process.env);
-  if (policy.mode === "off" || !policy.primer.onSessionStart)
-    return null;
-  if (!ctx.cwd || isExcluded(ctx.cwd, policy.excludeCwdGlobs))
-    return null;
-  let webapi;
-  try {
-    webapi = resolveWebapiUrl();
-  } catch {
-    return null;
-  }
-  const facts = await corpusFacts(webapi, policy, ctx.cwd, ctx.hostname);
-  if (!facts)
-    return null;
-  return recallPrimer(policy, facts, { cwd: ctx.cwd, hostname: ctx.hostname });
-}
+import { existsSync as existsSync4, mkdirSync as mkdirSync3, readFileSync as readFileSync8, writeFileSync as writeFileSync3 } from "fs";
+import { dirname as dirname2 } from "path";
 
 // packages/cli/src/hook/runtime.ts
 import {
@@ -40329,7 +40322,7 @@ function ingestRoute(doc) {
       return null;
   }
 }
-function makeMirrorCouch(target) {
+function makeMirrorCouch(target, onWrite) {
   const base3 = baseUrl(target);
   const headers = { "Content-Type": "application/json", ...authHeaders(target) };
   const fallback = target.timeoutMs ?? DEFAULT_TIMEOUT_MS;
@@ -40338,13 +40331,16 @@ function makeMirrorCouch(target) {
     if (!route)
       return;
     try {
-      await fetch(`${base3}${route.path}`, {
+      const res = await fetch(`${base3}${route.path}`, {
         method: "POST",
         headers,
         body: JSON.stringify(route.body),
         signal: AbortSignal.timeout(timeoutMs)
       });
-    } catch {}
+      onWrite?.(res.ok);
+    } catch {
+      onWrite?.(false);
+    }
   };
   return {
     async postDoc(_db, doc) {
@@ -40404,9 +40400,29 @@ function fanOutBlob(clients) {
 }
 
 // packages/cli/src/hook/runtime.ts
+var DEFAULT_CHUNK = { maxEntriesPerChunk: 200, flushIntervalMs: 15000 };
+function normalizeHookConfig(raw) {
+  const chunk2 = raw.system?.logging?.chunk;
+  return {
+    ...raw,
+    system: {
+      ...raw.system,
+      logging: {
+        ...raw.system?.logging,
+        chunk: {
+          maxEntriesPerChunk: chunk2?.maxEntriesPerChunk ?? DEFAULT_CHUNK.maxEntriesPerChunk,
+          flushIntervalMs: chunk2?.flushIntervalMs ?? DEFAULT_CHUNK.flushIntervalMs
+        }
+      }
+    }
+  };
+}
 function loadHookConfig(path) {
   try {
-    return JSON.parse(readFileSync5(path, "utf8"));
+    const raw = JSON.parse(readFileSync5(path, "utf8"));
+    if (!raw?.couch?.url)
+      return null;
+    return normalizeHookConfig(raw);
   } catch {
     return null;
   }
@@ -40447,7 +40463,10 @@ function makeDirectCouch(config, onWrite) {
 }
 function makeCouch(config, onWrite) {
   const mirrors = config.mirrors ?? [];
-  return fanOutCouch([makeDirectCouch(config, onWrite), ...mirrors.map((m) => makeMirrorCouch(m))]);
+  return fanOutCouch([
+    makeDirectCouch(config, onWrite && ((ok) => onWrite(ok, 0))),
+    ...mirrors.map((m, i) => makeMirrorCouch(m, onWrite && ((ok) => onWrite(ok, i + 1))))
+  ]);
 }
 function makeDirectBlob(config) {
   const cfg = config.blob;
@@ -40527,15 +40546,25 @@ function makeTargets(sessionId) {
   return {
     read,
     write,
-    markWrite(ok) {
+    markWrite(ok, storeIndex = 0) {
       const t = read();
       if (!t)
         return;
+      const now2 = Date.now();
+      const store = t.stores?.[storeIndex];
+      if (store) {
+        if (ok) {
+          store.lastWriteMs = now2;
+          store.lastFailureMs = 0;
+        } else {
+          store.lastFailureMs = now2;
+        }
+      }
       if (ok) {
-        t.lastWriteMs = Date.now();
+        t.lastWriteMs = now2;
         t.lastFailureMs = 0;
-      } else {
-        t.lastFailureMs = Date.now();
+      } else if (!t.stores?.some((x) => x.lastWriteMs > x.lastFailureMs)) {
+        t.lastFailureMs = now2;
       }
       write(t);
     },
@@ -40556,6 +40585,9 @@ function redactUrl(url) {
     return url;
   }
 }
+function hostOf(url) {
+  return redactUrl(url).replace(/^https?:\/\//, "").replace(/\/.*$/, "");
+}
 function resolveTargets(config, webapiUrl2) {
   return {
     couchUrl: redactUrl(config.couch.url),
@@ -40564,6 +40596,20 @@ function resolveTargets(config, webapiUrl2) {
     webapiUrl: webapiUrl2,
     features: Object.entries(config.features ?? {}).filter(([, on]) => on).map(([k]) => k),
     mirrors: (config.mirrors ?? []).map((m) => redactUrl(m.url)),
+    stores: [
+      {
+        label: `${config.couch.databases.sessions ?? DEFAULT_SESSIONS_DB}@${hostOf(config.couch.url)}`,
+        kind: "direct",
+        lastWriteMs: 0,
+        lastFailureMs: 0
+      },
+      ...(config.mirrors ?? []).map((m) => ({
+        label: hostOf(m.url),
+        kind: "mirror",
+        lastWriteMs: 0,
+        lastFailureMs: 0
+      }))
+    ],
     lastWriteMs: 0,
     lastFailureMs: 0
   };
@@ -40647,7 +40693,7 @@ function buildContext(payload, config) {
     transcriptPath: payload?.transcript_path,
     payload,
     config,
-    couch: makeCouch(config, (ok) => targets.markWrite(ok)),
+    couch: makeCouch(config, (ok, storeIndex) => targets.markWrite(ok, storeIndex)),
     blob: makeBlob(config),
     counts: makeCounts(sessionId),
     targets,
@@ -40665,6 +40711,96 @@ function commonFields(ctx) {
   };
 }
 
+// packages/cli/src/hook/announce.ts
+function sessionLink(webapiUrl2, sessionId) {
+  return webapiUrl2 ? `${webapiUrl2.replace(/\/$/, "")}/app/sessions/${sessionId}` : null;
+}
+function recordingBanner(targets, sessionId) {
+  const where = [`couchdb://${targets.couchUrl.replace(/^https?:\/\//, "")}/${targets.sessionsDb}`];
+  if (targets.bucket)
+    where.push(`s3://${targets.bucket}`);
+  if (targets.mirrors.length) {
+    where.push(`mirrors: ${targets.mirrors.map(hostOf).join(", ")}`);
+  }
+  const link2 = sessionLink(targets.webapiUrl, sessionId);
+  return `Claude Transcripts \u2014 recording to ${where.join(" + ")}${link2 ? ` \xB7 ${link2}` : ""}`;
+}
+var NOT_RECORDING_BANNER = "Claude Transcripts \u2014 not recording (no instance configured). Run `claude-transcripts install`.";
+function sessionStartEnvelope(out) {
+  if (!out.systemMessage && !out.additionalContext)
+    return null;
+  return {
+    ...out.systemMessage ? { systemMessage: out.systemMessage } : {},
+    ...out.additionalContext ? {
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext: out.additionalContext
+      }
+    } : {}
+  };
+}
+function emitSessionStart(out) {
+  try {
+    const envelope = sessionStartEnvelope(out);
+    if (envelope)
+      process.stdout.write(`${JSON.stringify(envelope)}
+`);
+  } catch {}
+}
+
+// packages/cli/src/hook/handlers.ts
+import { readFileSync as readFileSync6 } from "fs";
+
+// packages/cli/src/hook/recall.ts
+var FACTS_TIMEOUT_MS = 2000;
+function isExcluded(cwd2, globs) {
+  for (const g of globs) {
+    try {
+      if (new Bun.Glob(g).match(cwd2))
+        return true;
+    } catch {}
+  }
+  return false;
+}
+async function corpusFacts(webapiUrl2, policy, cwd2, hostname5) {
+  const q = new URLSearchParams({ limit: "1" });
+  if (policy.scope === "project")
+    q.set("cwd", cwd2);
+  else if (policy.scope === "host")
+    q.set("hostname", hostname5);
+  try {
+    const res = await fetch(`${webapiUrl2}/api/sessions?${q}`, {
+      signal: AbortSignal.timeout(FACTS_TIMEOUT_MS)
+    });
+    if (!res.ok)
+      return null;
+    const body = await res.json();
+    return {
+      sessionCount: body.totalCount ?? 0,
+      mostRecent: body.sessions?.[0]?.timestamp
+    };
+  } catch {
+    return null;
+  }
+}
+async function buildPrimer(ctx) {
+  const policy = resolveRecall(ctx.config.recall, process.env);
+  if (policy.mode === "off" || !policy.primer.onSessionStart)
+    return null;
+  if (!ctx.cwd || isExcluded(ctx.cwd, policy.excludeCwdGlobs))
+    return null;
+  let webapi;
+  try {
+    webapi = resolveWebapiUrl();
+  } catch {
+    return null;
+  }
+  const facts = await corpusFacts(webapi, policy, ctx.cwd, ctx.hostname);
+  if (!facts)
+    return null;
+  return recallPrimer(policy, facts, { cwd: ctx.cwd, hostname: ctx.hostname });
+}
+
 // packages/cli/src/hook/handlers.ts
 var seedSessionStart = async (ctx) => {
   const source = ctx.payload?.source;
@@ -40873,6 +41009,10 @@ var LONG_TIMEOUT_EVENTS = new Set(["SessionStart", "SessionEnd"]);
 function hookTimeout(event) {
   return LONG_TIMEOUT_EVENTS.has(event) ? 180 : 5;
 }
+var SYNCHRONOUS_EVENTS = new Set(["SessionStart", "SessionEnd", "UserPromptSubmit"]);
+function hookAsync(event) {
+  return !SYNCHRONOUS_EVENTS.has(event);
+}
 async function dispatch(raw, configPath) {
   let payload;
   try {
@@ -40887,7 +41027,13 @@ async function dispatch(raw, configPath) {
     }
     return { ran: false, actions: [] };
   }
-  const ctx = buildContext(payload, config);
+  let ctx;
+  try {
+    ctx = buildContext(payload, config);
+  } catch (err) {
+    console.error("[hook] could not build context (ignored):", err);
+    return { ran: false, actions: [] };
+  }
   if (!ctx)
     return { ran: false, actions: [] };
   const actions2 = hookBindings()[ctx.event] ?? [];
@@ -40906,10 +41052,62 @@ async function dispatch(raw, configPath) {
   return { ran: true, event: ctx.event, actions: actions2 };
 }
 
+// packages/cli/src/lib/plugin.ts
+import { readFileSync as readFileSync7 } from "fs";
+import { dirname, join as join7 } from "path";
+var PLUGIN_NAME = "claude-transcripts";
+function readJson(path) {
+  try {
+    const parsed = JSON.parse(readFileSync7(path, "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+function pluginsDir(settingsPath) {
+  return join7(dirname(settingsPath), "plugins");
+}
+function pluginEvents(settingsPath, key) {
+  const installed = readJson(join7(pluginsDir(settingsPath), "installed_plugins.json"));
+  const entry = installed?.plugins?.[key];
+  const first = Array.isArray(entry) ? entry[0] : undefined;
+  const installPath = typeof first?.installPath === "string" ? first.installPath : undefined;
+  if (!installPath)
+    return;
+  const hooks2 = readJson(join7(installPath, "hooks", "hooks.json"));
+  const events = hooks2?.hooks;
+  if (!events || typeof events !== "object")
+    return;
+  return Object.keys(events);
+}
+function pluginVersion(settingsPath, key) {
+  const installed = readJson(join7(pluginsDir(settingsPath), "installed_plugins.json"));
+  const entry = installed?.plugins?.[key];
+  const first = Array.isArray(entry) ? entry[0] : undefined;
+  return typeof first?.version === "string" ? first.version : undefined;
+}
+function pluginRegistration(settingsPath, settings) {
+  const enabled = settings.enabledPlugins;
+  if (!enabled || typeof enabled !== "object")
+    return null;
+  for (const [key, on] of Object.entries(enabled)) {
+    if (on !== true)
+      continue;
+    if (key.split("@")[0] !== PLUGIN_NAME)
+      continue;
+    return {
+      key,
+      version: pluginVersion(settingsPath, key),
+      events: pluginEvents(settingsPath, key)
+    };
+  }
+  return null;
+}
+
 // packages/cli/src/commands/hook.ts
 function readSettings(path) {
   try {
-    return JSON.parse(readFileSync7(path, "utf8"));
+    return JSON.parse(readFileSync8(path, "utf8"));
   } catch {
     return {};
   }
@@ -40948,8 +41146,19 @@ function install(argv) {
   const settings = readSettings(paths.claudeSettings);
   const hooks2 = settings.hooks ?? {};
   const events = Object.keys(hookBindings());
+  const plugin = pluginRegistration(paths.claudeSettings, settings);
+  if (plugin && options.force !== true) {
+    console.error(`hook: the plugin ${plugin.key} already registers these events.`);
+    console.error("hook: registering here as well would write every event twice.");
+    console.error("hook: pick one route \u2014");
+    console.error(`hook:   keep the plugin  \u2192 nothing to do (\`hook status\` explains it)`);
+    console.error(`hook:   use this binary  \u2192 disable the plugin, then re-run`);
+    console.error("hook: --force registers anyway.");
+    return 1;
+  }
   let added = 0;
   let replaced = 0;
+  let corrected = 0;
   for (const event of events) {
     const existing = hooks2[event] ?? [];
     const cleaned = [];
@@ -40966,26 +41175,48 @@ function install(argv) {
       if (kept.length)
         cleaned.push({ ...g, hooks: kept });
     }
+    const timeout = hookTimeout(event);
+    const wantAsync = hookAsync(event);
     if (cleaned.some((g) => g.hooks?.some((h) => h.command === command))) {
+      for (const g of cleaned) {
+        for (const h of g.hooks ?? []) {
+          if (h.command !== command)
+            continue;
+          if (h.timeout !== timeout) {
+            h.timeout = timeout;
+            corrected++;
+          } else if (wantAsync ? h.async !== true : h.async !== undefined) {
+            corrected++;
+          }
+          if (wantAsync)
+            h.async = true;
+          else
+            delete h.async;
+        }
+      }
       hooks2[event] = cleaned;
       continue;
     }
     hooks2[event] = [
       ...cleaned,
-      { hooks: [{ type: "command", command, timeout: hookTimeout(event) }] }
+      { hooks: [{ type: "command", command, timeout, ...wantAsync ? { async: true } : {} }] }
     ];
     added++;
   }
   if (options["dry-run"] === true) {
-    console.log(`hook: would register ${added} event(s)` + `${replaced ? `, replacing ${replaced} stale one(s)` : ""} in ${paths.claudeSettings}`);
+    console.log(`hook: would register ${added} event(s)` + `${replaced ? `, replacing ${replaced} stale one(s)` : ""}` + `${corrected ? `, correcting ${corrected} existing one(s)` : ""} in ${paths.claudeSettings}`);
     return 0;
   }
-  mkdirSync3(dirname(paths.claudeSettings), { recursive: true });
+  mkdirSync3(dirname2(paths.claudeSettings), { recursive: true });
   writeFileSync3(paths.claudeSettings, `${JSON.stringify({ ...settings, hooks: hooks2 }, null, 2)}
 `);
-  const suffix = replaced ? ` (replaced ${replaced} stale registration(s))` : "";
+  const notes = [
+    replaced ? `replaced ${replaced} stale registration(s)` : "",
+    corrected ? `corrected ${corrected} existing registration(s)` : ""
+  ].filter(Boolean);
+  const suffix = notes.length ? ` (${notes.join(", ")})` : "";
   console.log(added ? `hook: registered ${added} event(s)${suffix} \u2192 ${paths.claudeSettings}` : `hook: already registered (${events.length} events)${suffix} \u2192 ${paths.claudeSettings}`);
-  if (added)
+  if (added || corrected)
     console.log("hook: restart any open Claude Code session for it to take effect.");
   return 0;
 }
@@ -41011,27 +41242,48 @@ function uninstall() {
   writeFileSync3(paths.claudeSettings, `${JSON.stringify({ ...settings, hooks: hooks2 }, null, 2)}
 `);
   console.log(`hook: removed ${removed} registration(s) from ${paths.claudeSettings}`);
+  const plugin = pluginRegistration(paths.claudeSettings, settings);
+  if (plugin)
+    console.log(`hook: still recording via the plugin ${plugin.key}.`);
   return 0;
 }
 function configuredMirrors(path) {
   try {
-    const parsed = JSON.parse(readFileSync7(path, "utf8"));
+    const parsed = JSON.parse(readFileSync8(path, "utf8"));
     return (parsed.mirrors ?? []).map((m) => m?.url ?? "(no url)");
   } catch {
     return [];
   }
 }
+function pluginSummary(plugin) {
+  const version = plugin.version ? ` v${plugin.version}` : "";
+  const count = plugin.events?.length;
+  return `${plugin.key}${version}${count ? ` \u2014 registers ${count} event(s)` : ""}`;
+}
 function status() {
   const paths = installPaths();
   const settings = readSettings(paths.claudeSettings);
   const found = findRegistered(settings);
+  const plugin = pluginRegistration(paths.claudeSettings, settings);
   console.log(`hook: settings   ${paths.claudeSettings}`);
   console.log(`hook: config     ${paths.hookConfig} ${existsSync4(paths.hookConfig) ? "" : "(MISSING \u2014 run `install`)"}`);
   console.log(`hook: command    ${hookCommand()}`);
+  if (plugin)
+    console.log(`hook: plugin     ${pluginSummary(plugin)}`);
   const mirrors = configuredMirrors(paths.hookConfig);
   for (const url of mirrors)
     console.log(`hook: mirror     ${url}`);
+  if (plugin && found.length) {
+    console.log(`hook: DOUBLE-REGISTERED \u2014 ${found.length} event(s) here AND via the plugin.`);
+    console.log("hook: every event is being written twice. Run `hook uninstall` to keep");
+    console.log("hook: the plugin's registration, or disable the plugin to keep this one.");
+    return 1;
+  }
   if (!found.length) {
+    if (plugin) {
+      console.log("hook: registered by the plugin (nothing in settings.json \u2014 correct).");
+      return 0;
+    }
     console.log("hook: not registered.");
     return 1;
   }
@@ -41066,7 +41318,7 @@ async function runHook(argv) {
 
 // packages/cli/src/commands/import.ts
 import { existsSync as existsSync5, statSync as statSync2 } from "fs";
-import { join as join7 } from "path";
+import { join as join8 } from "path";
 var BATCH = 500;
 function num(n) {
   return n.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ",");
@@ -41136,7 +41388,7 @@ function checkSchema(bundleVersion, target, registry2 = REAL_REGISTRY) {
 async function verifyChecksums(dir, manifest) {
   const bad = [];
   for (const [rel, expected] of Object.entries(manifest.checksums)) {
-    const path = join7(dir, rel);
+    const path = join8(dir, rel);
     if (!existsSync5(path)) {
       bad.push(`${rel} (missing)`);
       continue;
@@ -41281,7 +41533,7 @@ async function runImport(argv) {
         skipped++;
         continue;
       }
-      const path = join7(dir, rel);
+      const path = join8(dir, rel);
       await putStream(`/api/ingest/${sessionId}/transcript`, path, "application/x-ndjson");
       blobs++;
       blobBytes += statSync2(path).size;
@@ -41305,41 +41557,41 @@ async function runImport(argv) {
 }
 
 // packages/cli/src/commands/install.ts
-import { existsSync as existsSync9, readFileSync as readFileSync12 } from "fs";
+import { existsSync as existsSync9, readFileSync as readFileSync13 } from "fs";
 
 // packages/cli/src/lib/assets.ts
 import {
   existsSync as existsSync6,
   lstatSync,
   mkdirSync as mkdirSync4,
-  readFileSync as readFileSync8,
+  readFileSync as readFileSync9,
   symlinkSync,
   unlinkSync as unlinkSync2,
   writeFileSync as writeFileSync4
 } from "fs";
-import { dirname as dirname2, join as join8 } from "path";
+import { dirname as dirname3, join as join9 } from "path";
 function writeAssets(paths) {
   const out = [];
   for (const asset of Object.values(EMBEDDED_ASSETS)) {
     const isUserOwned = asset.path.startsWith("config/");
-    const target = isUserOwned ? paths.appConfig : join8(paths.dataDir, asset.path);
+    const target = isUserOwned ? paths.appConfig : join9(paths.dataDir, asset.path);
     if (isUserOwned && existsSync6(target)) {
       out.push({ path: target, changed: false });
       continue;
     }
-    const previous = existsSync6(target) ? readFileSync8(target, "utf8") : null;
+    const previous = existsSync6(target) ? readFileSync9(target, "utf8") : null;
     if (previous === asset.content) {
       out.push({ path: target, changed: false });
       continue;
     }
-    mkdirSync4(dirname2(target), { recursive: true });
+    mkdirSync4(dirname3(target), { recursive: true });
     writeFileSync4(target, asset.content);
     out.push({ path: target, changed: true });
   }
   return out;
 }
 function linkInstanceEnv(paths) {
-  const link2 = join8(paths.dataDir, ".env");
+  const link2 = join9(paths.dataDir, ".env");
   try {
     if (lstatSync(link2, { throwIfNoEntry: false }))
       unlinkSync2(link2);
@@ -41348,14 +41600,14 @@ function linkInstanceEnv(paths) {
   symlinkSync(paths.instanceEnv, link2);
 }
 function writeVersionStamp(paths, version) {
-  mkdirSync4(dirname2(paths.versionFile), { recursive: true });
+  mkdirSync4(dirname3(paths.versionFile), { recursive: true });
   writeFileSync4(paths.versionFile, `${version}
 `);
 }
 function composeFiles(paths, upstream) {
-  const files = [join8(paths.dataDir, EMBEDDED_ASSETS.compose.path)];
+  const files = [join9(paths.dataDir, EMBEDDED_ASSETS.compose.path)];
   if (upstream)
-    files.push(join8(paths.dataDir, EMBEDDED_ASSETS.composeUpstream.path));
+    files.push(join9(paths.dataDir, EMBEDDED_ASSETS.composeUpstream.path));
   return files;
 }
 
@@ -41420,13 +41672,13 @@ function healthTargets(env4) {
 }
 
 // packages/cli/src/lib/hook-config.ts
-import { chmodSync as chmodSync3, mkdirSync as mkdirSync6, readFileSync as readFileSync10, writeFileSync as writeFileSync6 } from "fs";
-import { dirname as dirname4 } from "path";
+import { chmodSync as chmodSync3, mkdirSync as mkdirSync6, readFileSync as readFileSync11, writeFileSync as writeFileSync6 } from "fs";
+import { dirname as dirname5 } from "path";
 
 // packages/cli/src/lib/instance-env.ts
 import { randomBytes } from "crypto";
-import { chmodSync as chmodSync2, existsSync as existsSync7, mkdirSync as mkdirSync5, readFileSync as readFileSync9, writeFileSync as writeFileSync5 } from "fs";
-import { dirname as dirname3 } from "path";
+import { chmodSync as chmodSync2, existsSync as existsSync7, mkdirSync as mkdirSync5, readFileSync as readFileSync10, writeFileSync as writeFileSync5 } from "fs";
+import { dirname as dirname4 } from "path";
 var DEFAULT_PORT_BASE = 7650;
 var PORT_KEYS = [
   "WEBAPI_PORT",
@@ -41508,7 +41760,7 @@ var HEADER = [
 var INSTALLER_OWNED = ["APP_TAG"];
 function loadOrCreateInstanceEnv(path, opts = {}) {
   const generated = buildInstanceEnv(opts);
-  const existing = existsSync7(path) ? parseEnv(readFileSync9(path, "utf8")) : {};
+  const existing = existsSync7(path) ? parseEnv(readFileSync10(path, "utf8")) : {};
   const merged = { ...generated, ...existing };
   for (const key of INSTALLER_OWNED) {
     if (generated[key] !== undefined)
@@ -41522,12 +41774,12 @@ function loadOrCreateInstanceEnv(path, opts = {}) {
   return merged;
 }
 function writeInstanceEnv(path, env4) {
-  mkdirSync5(dirname3(path), { recursive: true });
+  mkdirSync5(dirname4(path), { recursive: true });
   writeFileSync5(path, formatEnv(env4, HEADER));
   chmodSync2(path, 384);
 }
 function updateInstanceEnv(path, patch) {
-  const env4 = existsSync7(path) ? parseEnv(readFileSync9(path, "utf8")) : {};
+  const env4 = existsSync7(path) ? parseEnv(readFileSync10(path, "utf8")) : {};
   const next = { ...env4, ...patch };
   writeInstanceEnv(path, next);
   return next;
@@ -41692,7 +41944,7 @@ function buildHookConfig(app, env4) {
 var PRESERVED_KEYS = ["mirrors"];
 function readExisting(path) {
   try {
-    const parsed = JSON.parse(readFileSync10(path, "utf8"));
+    const parsed = JSON.parse(readFileSync11(path, "utf8"));
     return parsed && typeof parsed === "object" ? parsed : {};
   } catch {
     return {};
@@ -41708,7 +41960,7 @@ function mergePreserved(next, existing) {
 }
 function writeHookConfig(path, config) {
   const merged = mergePreserved(config ?? {}, readExisting(path));
-  mkdirSync6(dirname4(path), { recursive: true });
+  mkdirSync6(dirname5(path), { recursive: true });
   writeFileSync6(path, `${JSON.stringify(merged, null, 2)}
 `);
   chmodSync3(path, 384);
@@ -41872,8 +42124,8 @@ async function portsCheck(ports) {
 }
 async function claudeCheck(settingsPath) {
   const dir = settingsPath.replace(/\/[^/]+$/, "");
-  const exists2 = await Bun.file(settingsPath).exists().catch(() => false);
-  if (exists2)
+  const exists = await Bun.file(settingsPath).exists().catch(() => false);
+  if (exists)
     return { name: "claude code", status: "ok", detail: `settings at ${settingsPath}` };
   return {
     name: "claude code",
@@ -41910,8 +42162,8 @@ var DEV_VERSION = "0.0.0-dev";
 var VERSION = process.env.CT_VERSION ?? DEV_VERSION;
 
 // packages/cli/src/commands/statusline.ts
-import { existsSync as existsSync8, mkdirSync as mkdirSync7, readFileSync as readFileSync11, writeFileSync as writeFileSync7 } from "fs";
-import { dirname as dirname5 } from "path";
+import { existsSync as existsSync8, mkdirSync as mkdirSync7, readFileSync as readFileSync12, writeFileSync as writeFileSync7 } from "fs";
+import { dirname as dirname6 } from "path";
 
 // packages/cli/src/lib/statusline.ts
 var STALL_AFTER_MS = 60000;
@@ -41928,6 +42180,11 @@ function whereLabel(t) {
   const host = t.couchUrl.replace(/^https?:\/\//, "").replace(/\/.*$/, "");
   return `${t.sessionsDb}@${host}`;
 }
+function storeState(s, now2) {
+  if (s.lastFailureMs > s.lastWriteMs && now2 - s.lastWriteMs > STALL_AFTER_MS)
+    return "failing";
+  return s.lastWriteMs > 0 ? "healthy" : "idle";
+}
 function renderStatusline(state, now2 = Date.now()) {
   if (!state.configured)
     return "\u25CB ct off \xB7 no instance configured";
@@ -41937,21 +42194,41 @@ function renderStatusline(state, now2 = Date.now()) {
   const c = state.counts;
   const toolCalls = c ? Object.values(c.tools).reduce((a, b) => a + b, 0) : 0;
   const counts = c ? `${c.events} ev \xB7 ${toolCalls} tools` : "0 ev";
-  const written = t.lastWriteMs > 0;
-  const failing = t.lastFailureMs > t.lastWriteMs && now2 - t.lastWriteMs > STALL_AFTER_MS;
-  if (failing) {
-    const last2 = written ? `last write ${ago(t.lastWriteMs, now2)}` : "no write landed";
-    return `\u25D0 ct stalled \xB7 ${counts} \xB7 ${last2} \u2192 ${whereLabel(t)}`;
-  }
-  if (!written)
-    return `\u25CC ct ready \xB7 ${counts} \xB7 no write yet \u2192 ${whereLabel(t)}`;
-  return `\u25CF ct rec \xB7 ${counts} \xB7 ${ago(t.lastWriteMs, now2)} \u2192 ${whereLabel(t)}`;
+  const stores = t.stores?.length ? t.stores : null;
+  if (!stores) {
+    const written = t.lastWriteMs > 0;
+    const failing = t.lastFailureMs > t.lastWriteMs && now2 - t.lastWriteMs > STALL_AFTER_MS;
+    if (failing) {
+      const last2 = written ? `last write ${ago(t.lastWriteMs, now2)}` : "no write landed";
+      return `\u25D0 ct stalled \xB7 ${counts} \xB7 ${last2} \u2192 ${whereLabel(t)}`;
+    }
+    if (!written)
+      return `\u25CC ct ready \xB7 ${counts} \xB7 no write yet \u2192 ${whereLabel(t)}`;
+    return `\u25CF ct rec \xB7 ${counts} \xB7 ${ago(t.lastWriteMs, now2)} \u2192 ${whereLabel(t)}`;
+  }
+  const direct = stores.find((s) => s.kind === "direct") ?? stores[0];
+  const headline = direct ?? { label: whereLabel(t), lastWriteMs: 0, lastFailureMs: 0 };
+  if (direct && storeState(direct, now2) === "healthy") {
+    return `\u25CF ct rec \xB7 ${counts} \xB7 ${ago(direct.lastWriteMs, now2)} \u2192 ${direct.label}`;
+  }
+  const healthyMirrors = stores.filter((s) => s !== direct && storeState(s, now2) === "healthy");
+  const first = healthyMirrors[0];
+  if (first) {
+    const more = healthyMirrors.length > 1 ? ` +${healthyMirrors.length - 1}` : "";
+    return `\u25CF ct rec (mirror) \xB7 ${counts} \xB7 ${ago(first.lastWriteMs, now2)} \u2192 ${first.label}${more}`;
+  }
+  if (stores.some((s) => storeState(s, now2) === "failing")) {
+    const best = Math.max(...stores.map((s) => s.lastWriteMs));
+    const last2 = best > 0 ? `last write ${ago(best, now2)}` : "no write landed";
+    return `\u25D0 ct stalled \xB7 ${counts} \xB7 ${last2} \u2192 ${headline.label}`;
+  }
+  return `\u25CC ct ready \xB7 ${counts} \xB7 no write yet \u2192 ${headline.label}`;
 }
 
 // packages/cli/src/commands/statusline.ts
 function readSettings2(path) {
   try {
-    return JSON.parse(readFileSync11(path, "utf8"));
+    return JSON.parse(readFileSync12(path, "utf8"));
   } catch {
     return {};
   }
@@ -42008,7 +42285,7 @@ function install2(argv) {
     console.log(`  ${JSON.stringify(next)}`);
     return 0;
   }
-  mkdirSync7(dirname5(paths.claudeSettings), { recursive: true });
+  mkdirSync7(dirname6(paths.claudeSettings), { recursive: true });
   writeFileSync7(paths.claudeSettings, `${JSON.stringify({ ...settings, statusLine: next }, null, 2)}
 `);
   console.log(`statusline: registered \u2192 ${paths.claudeSettings}`);
@@ -42128,7 +42405,7 @@ async function runInstall(argv) {
   const noPrune = options["no-prune"] === true;
   const portBaseOpt = strOpt(options, "port-base");
   const paths = installPaths();
-  const priorAppTag = existsSync9(paths.instanceEnv) ? /^APP_TAG=(\S+)\s*$/m.exec(readFileSync12(paths.instanceEnv, "utf8"))?.[1] : undefined;
+  const priorAppTag = existsSync9(paths.instanceEnv) ? /^APP_TAG=(\S+)\s*$/m.exec(readFileSync13(paths.instanceEnv, "utf8"))?.[1] : undefined;
   const TOTAL = 8;
   console.log(`claude-transcripts install (${VERSION})`);
   console.log(`  config  ${paths.configDir}`);
@@ -42615,18 +42892,18 @@ async function runSessions(argv) {
 }
 
 // packages/cli/src/commands/setup.ts
-import { existsSync as existsSync11, mkdirSync as mkdirSync8, readFileSync as readFileSync13, writeFileSync as writeFileSync8 } from "fs";
+import { existsSync as existsSync11, mkdirSync as mkdirSync8, readFileSync as readFileSync14, writeFileSync as writeFileSync8 } from "fs";
 import { homedir as homedir3 } from "os";
-import { dirname as dirname6, join as join9 } from "path";
-var REPO_ROOT = join9(import.meta.dir, "..", "..", "..", "..");
-var HOOK_DIR = join9(REPO_ROOT, "hooks");
-var HOOK_CONFIG_PATH = process.env.CT_HOOK_CONFIG ?? join9(homedir3(), ".config", "claude-transcripts", "config.json");
-var GLOBAL_SETTINGS = join9(homedir3(), ".claude", "settings.json");
-var PROJECT_SETTINGS = join9(process.cwd(), ".claude", "settings.json");
+import { dirname as dirname7, join as join10 } from "path";
+var REPO_ROOT = join10(import.meta.dir, "..", "..", "..", "..");
+var HOOK_DIR = join10(REPO_ROOT, "hooks");
+var HOOK_CONFIG_PATH = process.env.CT_HOOK_CONFIG ?? join10(homedir3(), ".config", "claude-transcripts", "config.json");
+var GLOBAL_SETTINGS = join10(homedir3(), ".claude", "settings.json");
+var PROJECT_SETTINGS = join10(process.cwd(), ".claude", "settings.json");
 function loadRepoConfig() {
-  const live = join9(REPO_ROOT, "config", "config.json");
-  const template2 = join9(REPO_ROOT, "config", "config.template.json");
-  return JSON.parse(readFileSync13(existsSync11(live) ? live : template2, "utf8"));
+  const live = join10(REPO_ROOT, "config", "config.json");
+  const template2 = join10(REPO_ROOT, "config", "config.template.json");
+  return JSON.parse(readFileSync14(existsSync11(live) ? live : template2, "utf8"));
 }
 function buildHookConfig2(cfg) {
   const env4 = process.env;
@@ -42693,13 +42970,13 @@ async function probeGarage(blob) {
 }
 function readSettings3(path) {
   try {
-    return JSON.parse(readFileSync13(path, "utf8"));
+    return JSON.parse(readFileSync14(path, "utf8"));
   } catch {
     return {};
   }
 }
 function dispatchCommand() {
-  return `bun run ${join9(HOOK_DIR, "scripts", "dispatch.ts")}`;
+  return `bun run ${join10(HOOK_DIR, "scripts", "dispatch.ts")}`;
 }
 function isRegistered(path) {
   const cmd = dispatchCommand();
@@ -42708,7 +42985,7 @@ function isRegistered(path) {
 }
 function registerGlobal(dryRun) {
   const cmd = dispatchCommand();
-  const generated = JSON.parse(readFileSync13(join9(HOOK_DIR, "hooks", "hooks.json"), "utf8"));
+  const generated = JSON.parse(readFileSync14(join10(HOOK_DIR, "hooks", "hooks.json"), "utf8"));
   const settings = readSettings3(GLOBAL_SETTINGS);
   const hooks2 = settings.hooks ?? {};
   for (const [event, groups] of Object.entries(generated.hooks)) {
@@ -42723,7 +43000,7 @@ function registerGlobal(dryRun) {
     console.log(`  [check] would register ${Object.keys(generated.hooks).length} events in ${GLOBAL_SETTINGS}`);
     return;
   }
-  mkdirSync8(dirname6(GLOBAL_SETTINGS), { recursive: true });
+  mkdirSync8(dirname7(GLOBAL_SETTINGS), { recursive: true });
   writeFileSync8(GLOBAL_SETTINGS, `${JSON.stringify({ ...settings, hooks: hooks2 }, null, 2)}
 `);
   console.log(`  registered ${Object.keys(generated.hooks).length} events (system-wide) in ${GLOBAL_SETTINGS}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-transcripts/cli",
-  "version": "0.0.16",
+  "version": "0.1.0",
   "type": "module",
   "description": "Claude Transcripts CLI — browse, search, back up, and administer your self-hosted Claude Code session history.",
   "keywords": [