@claude-transcripts/cli 0.7.1 → 0.8.0

package/dist/{cli-afbmvjwt.js → cli-3dqna555.js}

@@ -32,6 +32,11 @@ var ACTIONS = [
     summary: "Tell the user, in the transcript, whether and where this session is recorded",
     implemented: true
   },
+  {
+    key: "check-hook-compat",
+    summary: "Check the running Claude Code's hook spec against ours and report any drift",
+    implemented: true
+  },
   {
     key: "inject-recall-policy",
     summary: "Prime the session with the recall policy + how much history this cwd has",
@@ -52,8 +57,9 @@ var ACTIONS = [
   },
   {
     key: "reconcile-session",
-    summary: "Finalize a stale running session from chunks/S3",
-    implemented: false
+    summary: "Write the missing summary for a session that never fired SessionEnd, from its events (and S3 transcript)",
+    implemented: true,
+    triggers: { cli: "reconcile", follower: true }
   }
 ];
 var BINDINGS = [
@@ -63,6 +69,7 @@ var BINDINGS = [
       "seed-session-start",
       "write-event-marker",
       "announce-recording",
+      "check-hook-compat",
       "inject-recall-policy"
     ]
   },
@@ -746,6 +753,24 @@ var CLI_SPEC = {
       summary: "Rebuild the search indexes from CouchDB",
       examples: ["reindex"]
     },
+    {
+      name: "reconcile",
+      group: "admin",
+      summary: "Finalise sessions that never ended (write their missing summary)",
+      args: [
+        {
+          name: "session-id",
+          description: "sessions to finalise (repeatable); default: every session that reads as `incomplete`"
+        },
+        { name: "--dry-run", description: "say what would be written, write nothing" },
+        {
+          name: "--force",
+          description: "also finalise a named session that still reads as `running`"
+        },
+        { name: "--json", description: "print the outcomes as JSON (what the follower reads)" }
+      ],
+      examples: ["reconcile --dry-run", "reconcile 3f9a2c1e-\u2026 --force", "reconcile --json"]
+    },
     {
       name: "doctor",
       group: "admin",
@@ -753,6 +778,25 @@ var CLI_SPEC = {
       args: [{ name: "--keep", description: "leave the synthetic session behind for inspection" }],
       examples: ["doctor", "doctor --keep"]
     },
+    {
+      name: "compat",
+      group: "admin",
+      summary: "Check Claude Code's hook spec against this build's (exit 1 on drift)",
+      args: [
+        {
+          name: "action",
+          choices: ["check", "fetch"],
+          default: "check",
+          description: "`check` reports drift; `fetch` caches a version's spec from npm (SessionStart " + "starts it detached when it meets a version it doesn't know)"
+        },
+        {
+          name: "--cc-version",
+          type: "string",
+          description: "the Claude Code version to check (default: the installed one)"
+        }
+      ],
+      examples: ["compat", "compat --cc-version 2.1.300 --json"]
+    },
     {
       name: "hook",
       group: "admin",
@@ -1810,6 +1854,397 @@ var WORKLOAD_ROLES = new Set(["backing", "admin-ui", "app"]);
 function toStoreEnv(model) {
   return { FOSSIL_REPOSITORIES: Object.values(model.stores.repositories).join(",") };
 }
+// packages/shared/src/claude-code-hook-spec.json
+var claude_code_hook_spec_default = {
+  claudeCode: "2.1.310",
+  sdk: "0.3.310",
+  base: {
+    agent_id: [],
+    agent_type: [],
+    cwd: [],
+    effort: [],
+    permission_mode: [],
+    prompt_id: [],
+    session_id: [],
+    transcript_path: []
+  },
+  events: {
+    PreToolUse: {
+      mcp_server: [],
+      tool_input: [],
+      tool_name: [],
+      tool_use_id: []
+    },
+    PostToolUse: {
+      duration_ms: [],
+      mcp_server: [],
+      tool_input: [],
+      tool_name: [],
+      tool_response: [],
+      tool_use_id: []
+    },
+    PostToolUseFailure: {
+      duration_ms: [],
+      error: [],
+      is_interrupt: [],
+      mcp_server: [],
+      tool_input: [],
+      tool_name: [],
+      tool_use_id: []
+    },
+    PostToolBatch: {
+      tool_calls: []
+    },
+    Notification: {
+      message: [],
+      notification_type: [],
+      title: []
+    },
+    UserPromptSubmit: {
+      prompt: [],
+      session_title: [],
+      source: ["loop_wakeup", "poll_event", "schedule_wakeup", "sdk", "system", "user"]
+    },
+    UserPromptExpansion: {
+      command_args: [],
+      command_name: [],
+      command_source: [],
+      expansion_type: ["mcp_prompt", "slash_command"],
+      prompt: []
+    },
+    SessionStart: {
+      agent_type: [],
+      context_tokens: [],
+      estimated_cache_write_usd: [],
+      model: [],
+      prompt_cache_likely_expired: [],
+      seconds_since_last_response: [],
+      session_title: [],
+      source: ["clear", "compact", "fork", "resume", "startup"]
+    },
+    SessionEnd: {
+      reason: ["clear", "logout", "other", "prompt_input_exit", "resume"]
+    },
+    Stop: {
+      background_tasks: [],
+      last_assistant_message: [],
+      session_crons: [],
+      stop_hook_active: []
+    },
+    StopFailure: {
+      error: [
+        "account_on_hold",
+        "authentication_failed",
+        "billing_error",
+        "cloud_credential_error",
+        "invalid_request",
+        "max_output_tokens",
+        "model_not_found",
+        "oauth_org_not_allowed",
+        "overloaded",
+        "rate_limit",
+        "server_error",
+        "unknown",
+        "verification_required"
+      ],
+      error_details: [],
+      last_assistant_message: []
+    },
+    SubagentStart: {
+      agent_id: [],
+      agent_type: []
+    },
+    SubagentStop: {
+      agent_id: [],
+      agent_transcript_path: [],
+      agent_type: [],
+      background_tasks: [],
+      last_assistant_message: [],
+      session_crons: [],
+      stop_hook_active: []
+    },
+    PreCompact: {
+      custom_instructions: [],
+      trigger: ["auto", "manual"]
+    },
+    PostCompact: {
+      compact_summary: [],
+      trigger: ["auto", "manual"]
+    },
+    PreModelSwitch: {
+      cache_ttl: ["1h", "5m"],
+      context_tokens: [],
+      estimated_cache_write_usd: [],
+      from_model: [],
+      pricing: ["catalog", "configured", "default"],
+      prompt_cache_warm: [],
+      requested_model: [],
+      source: ["command", "picker", "sdk"],
+      to_model: []
+    },
+    PostModelSwitch: {
+      cache_ttl: ["1h", "5m"],
+      context_tokens: [],
+      estimated_cache_write_usd: [],
+      from_model: [],
+      pricing: ["catalog", "configured", "default"],
+      prompt_cache_warm: [],
+      requested_model: [],
+      source: ["auto", "command", "picker", "resume", "sdk"],
+      to_model: []
+    },
+    PermissionRequest: {
+      mcp_server: [],
+      permission_suggestions: [],
+      tool_input: [],
+      tool_name: []
+    },
+    PermissionDenied: {
+      mcp_server: [],
+      reason: [],
+      tool_input: [],
+      tool_name: [],
+      tool_use_id: []
+    },
+    Setup: {
+      trigger: ["init", "maintenance"]
+    },
+    TeammateIdle: {
+      team_name: [],
+      teammate_name: []
+    },
+    TaskCreated: {
+      task_description: [],
+      task_id: [],
+      task_subject: [],
+      team_name: [],
+      teammate_name: []
+    },
+    TaskCompleted: {
+      task_description: [],
+      task_id: [],
+      task_subject: [],
+      team_name: [],
+      teammate_name: []
+    },
+    Elicitation: {
+      elicitation_id: [],
+      mcp_server_name: [],
+      message: [],
+      mode: ["form", "url"],
+      requested_schema: [],
+      url: []
+    },
+    ElicitationResult: {
+      action: ["accept", "cancel", "decline"],
+      content: [],
+      elicitation_id: [],
+      mcp_server_name: [],
+      mode: ["form", "url"]
+    },
+    ConfigChange: {
+      file_path: [],
+      source: ["local_settings", "policy_settings", "project_settings", "skills", "user_settings"]
+    },
+    WorktreeCreate: {
+      name: []
+    },
+    WorktreeRemove: {
+      worktree_path: []
+    },
+    InstructionsLoaded: {
+      file_path: [],
+      globs: [],
+      load_reason: ["compact", "include", "nested_traversal", "path_glob_match", "session_start"],
+      memory_type: ["Local", "Managed", "Project", "User"],
+      parent_file_path: [],
+      trigger_file_path: []
+    },
+    CwdChanged: {
+      new_cwd: [],
+      old_cwd: []
+    },
+    FileChanged: {
+      event: ["add", "change", "unlink"],
+      file_path: []
+    },
+    DirectoryAdded: {
+      directory: [],
+      source: ["register_repo_root", "slash_command"]
+    },
+    MessageDisplay: {
+      delta: [],
+      final: [],
+      index: [],
+      message_id: [],
+      turn_id: []
+    }
+  }
+};
+
+// packages/shared/src/claude-code-spec.ts
+var VERIFIED_HOOK_SPEC = claude_code_hook_spec_default;
+function stripComments(src) {
+  return src.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^\s*\/\/.*$/gm, "");
+}
+function typeBody(dts, name) {
+  const head = `export declare type ${name} = `;
+  const start = dts.indexOf(head);
+  if (start < 0)
+    return null;
+  let depth = 0;
+  for (let i = start + head.length;i < dts.length; i++) {
+    const c = dts[i];
+    if (c === "{" || c === "(")
+      depth++;
+    else if (c === "}" || c === ")")
+      depth--;
+    else if (c === ";" && depth === 0)
+      return dts.slice(start + head.length, i);
+  }
+  return null;
+}
+var LIT = `(?:'[^']*'|"[^"]*")`;
+var LIT_UNION = new RegExp(`^${LIT}(?:\\s*\\|\\s*${LIT})*$`);
+function literalAliases(dts) {
+  const out = new Map;
+  const re = /^export declare type (\w+) = (.+);$/gm;
+  for (const m of dts.matchAll(re)) {
+    if (LIT_UNION.test(m[2]))
+      out.set(m[1], literals(m[2]));
+  }
+  return out;
+}
+function literals(src) {
+  return [...src.matchAll(/'([^']*)'|"([^"]*)"/g)].map((m) => m[1] ?? m[2]).sort();
+}
+function fieldsOf(body, aliases) {
+  const fields = {};
+  let depth = 0;
+  for (const line of body.split(`
+`)) {
+    if (depth === 1) {
+      const m = /^\s*(\w+)\??:\s*(.*)$/.exec(line);
+      if (m && m[1] !== "hook_event_name") {
+        const type = m[2].replace(/;\s*$/, "").trim();
+        if (LIT_UNION.test(type))
+          fields[m[1]] = literals(type);
+        else
+          fields[m[1]] = aliases.get(type) ?? [];
+      }
+    }
+    for (const c of line) {
+      if (c === "{")
+        depth++;
+      else if (c === "}")
+        depth--;
+    }
+  }
+  return Object.fromEntries(Object.entries(fields).sort(([a], [b]) => a.localeCompare(b)));
+}
+function parseSdkHookSpec(source, versions) {
+  const dts = stripComments(source.replace(/\r\n/g, `
+`));
+  const list = /export declare const HOOK_EVENTS: readonly \[([^\]]*)\]/.exec(dts);
+  if (!list)
+    throw new Error("sdk.d.ts declares no HOOK_EVENTS \u2014 the SDK's layout changed");
+  const baseBody = typeBody(dts, "BaseHookInput");
+  if (!baseBody)
+    throw new Error("sdk.d.ts declares no BaseHookInput \u2014 the SDK's layout changed");
+  const aliases = literalAliases(dts);
+  const events = {};
+  const names = [...list[1].matchAll(/'([^']+)'|"([^"]+)"/g)].map((m) => m[1] ?? m[2]);
+  if (!names.length)
+    throw new Error("sdk.d.ts lists no HOOK_EVENTS \u2014 the SDK's layout changed");
+  for (const event of names) {
+    const body = typeBody(dts, `${event}HookInput`);
+    events[event] = body ? fieldsOf(body, aliases) : {};
+  }
+  return { ...versions, base: fieldsOf(baseBody, aliases), events };
+}
+function flatten(fields) {
+  const out = new Set;
+  for (const [name, values] of Object.entries(fields)) {
+    out.add(name);
+    for (const v of values)
+      out.add(`${name}=${v}`);
+  }
+  return out;
+}
+function fieldDrift(event, before, after) {
+  const a = flatten(before);
+  const b = flatten(after);
+  const whole = (s, other) => !other.has(s.split("=")[0]);
+  const added = [...b].filter((f) => !a.has(f) && (!f.includes("=") || !whole(f, a))).sort();
+  const removed = [...a].filter((f) => !b.has(f) && (!f.includes("=") || !whole(f, b))).sort();
+  return added.length || removed.length ? { event, added, removed } : null;
+}
+function compareHookSpec(catalogue, verified, runningVersion, running) {
+  const wired = catalogue.filter((h) => h.wired);
+  const report = {
+    running: runningVersion,
+    verified: verified.claudeCode,
+    known: running !== null,
+    unlisted: [],
+    goneWired: [],
+    goneListed: [],
+    fields: [],
+    eventCount: running ? Object.keys(running.events).length : 0,
+    wiredCount: wired.length
+  };
+  if (!running)
+    return report;
+  const listed = new Set(catalogue.map((h) => h.event));
+  report.unlisted = Object.keys(running.events).filter((e) => !listed.has(e)).sort();
+  for (const h of catalogue) {
+    if (h.event in running.events)
+      continue;
+    (h.wired ? report.goneWired : report.goneListed).push(h.event);
+  }
+  const base = fieldDrift("*", verified.base, running.base);
+  if (base)
+    report.fields.push(base);
+  for (const h of wired) {
+    const after = running.events[h.event];
+    if (!after)
+      continue;
+    const drift = fieldDrift(h.event, verified.events[h.event] ?? {}, after);
+    if (drift)
+      report.fields.push(drift);
+  }
+  return report;
+}
+function hasDrift(r) {
+  return !r.known || r.unlisted.length > 0 || r.goneWired.length > 0 || r.goneListed.length > 0 || r.fields.length > 0;
+}
+function formatHookCompat(r) {
+  if (!r.known) {
+    return [
+      `? Hook spec for Claude Code ${r.running} not checked yet (this build knows ${r.verified}) \u2014 fetching it; the result shows next session`
+    ];
+  }
+  if (!hasDrift(r)) {
+    return [
+      `\u2713 Hook spec matches Claude Code ${r.running} (${r.eventCount} events, ${r.wiredCount} recorded)`
+    ];
+  }
+  const against = r.running === r.verified ? "" : ` (this build was checked against ${r.verified})`;
+  const lines = [`\u25B3 Hook spec drift with Claude Code ${r.running}${against}:`];
+  const list = (xs) => xs.join(", ");
+  if (r.goneWired.length)
+    lines.push(`  \xB7 recorded, but no longer fired: ${list(r.goneWired)}`);
+  if (r.unlisted.length)
+    lines.push(`  \xB7 new events we don't handle: ${list(r.unlisted)}`);
+  if (r.goneListed.length)
+    lines.push(`  \xB7 listed, but no longer fired: ${list(r.goneListed)}`);
+  for (const f of r.fields) {
+    const name = f.event === "*" ? "common fields" : f.event;
+    const parts = [...f.added.map((x) => `+${x}`), ...f.removed.map((x) => `\u2212${x}`)];
+    lines.push(`  \xB7 ${name}: ${parts.join(" ")}`);
+  }
+  lines.push("  Details: claude-transcripts compat");
+  return lines;
+}
 // packages/shared/src/couch-url.ts
 var DEFAULT_COUCHDB_HOST = "127.0.0.1";
 var DEFAULT_COUCHDB_PORT = "7652";
@@ -2563,6 +2998,14 @@ async function getOrNull(path) {
     return null;
   return await res.json();
 }
+async function getTextOrNull(path) {
+  const res = await fetch(`${base()}${path}`);
+  if (res.status === 404)
+    return null;
+  if (!res.ok)
+    throw new Error(`GET ${path} \u2192 ${res.status} ${res.statusText}${await errorDetail(res)}`);
+  return await res.text();
+}
 async function putStream(path, filePath, contentType) {
   const res = await fetch(`${base()}${path}`, {
     method: "PUT",
@@ -2730,6 +3173,27 @@ function buildSummaryDoc(facts, source, opts = {}) {
     ...opts.actor ? { actor: opts.actor } : {}
   };
 }
+function buildReconciledSummary(s, transcript, reconciledAt) {
+  return {
+    _id: `summary:${s.sessionId}`,
+    type: "summary",
+    event: "SessionEnd",
+    session_id: s.sessionId,
+    timestamp: s.lastActivity || s.timestamp,
+    hostname: s.hostname,
+    cwd: s.cwd,
+    ...s.model ? { model: s.model } : {},
+    end_reason: "unknown",
+    event_count: s.eventCount,
+    prompt_count: s.promptCount,
+    error_count: s.errorCount,
+    tool_counts: s.toolCounts,
+    transcript_bytes: transcript ? Buffer.byteLength(transcript) : s.transcriptSize ?? 0,
+    ...transcript ? { token_usage: sumTranscriptTokens(transcript) } : {},
+    source: "reconcile",
+    reconciled_at: reconciledAt
+  };
+}
 function buildChunkDocs(jsonl, facts, source, maxEntriesPerChunk, withContent = true) {
   const slices = sliceIntoChunks(jsonl, maxEntriesPerChunk);
   const allEntries = withContent ? buildChunkEntries(jsonl) : undefined;
@@ -3065,7 +3529,7 @@ class DryRunSink {
   }
   async putSummary(doc) {
     const tools = Object.keys(doc.tool_counts).length;
-    console.log(`  [dry-run] PUT ${doc._id}  (${doc.token_usage.total} tok, ${doc.prompt_count} prompts, ${tools} tools)`);
+    console.log(`  [dry-run] PUT ${doc._id}  (${doc.token_usage?.total ?? "?"} tok, ${doc.prompt_count} prompts, ${tools} tools)`);
   }
   async putEvents(docs) {
     if (docs.length)
@@ -3097,15 +3561,18 @@ class WebapiSink {
     return res.deleted;
   }
   async putSummary(doc) {
-    await ingestSummary(doc);
+    await ingestSummary({ ...doc });
   }
   async putEvents(docs) {
     if (docs.length)
       await ingestEvents({ docs });
   }
   async putChunks(docs) {
-    if (docs.length)
-      await ingestChunks({ docs });
+    if (!docs.length)
+      return;
+    await ingestChunks({
+      docs: docs.map((d) => ({ ...d, entries: d.entries?.map((e) => ({ ...e })) }))
+    });
   }
   async putTranscript(sessionId, bytes) {
     await putRaw(`/api/ingest/${encodeURIComponent(sessionId)}/transcript`, bytes, "application/x-ndjson");
@@ -3270,6 +3737,138 @@ async function runBackfill(argv) {
   return failed > 0 ? 1 : 0;
 }
 
+// packages/cli/src/lib/claude-code-spec.ts
+import { spawnSync } from "child_process";
+import { createHash } from "crypto";
+import { existsSync, mkdirSync, readFileSync as readFileSync2, writeFileSync } from "fs";
+import { join as join3 } from "path";
+import { gunzipSync } from "zlib";
+var SDK_PACKAGE = "@anthropic-ai/claude-agent-sdk";
+var REGISTRY = process.env.NPM_CONFIG_REGISTRY?.replace(/\/$/, "") ?? "https://registry.npmjs.org";
+function claudeCodeVersion(env = process.env) {
+  const candidates = [env.CLAUDE_CODE_EXECPATH, "claude"].filter(Boolean);
+  for (const bin of candidates) {
+    try {
+      const res = spawnSync(bin, ["--version"], { encoding: "utf8", timeout: 3000, cwd: "/" });
+      const m = /^(\d+\.\d+\.\d+)/.exec(res.stdout?.trim() ?? "");
+      if (m)
+        return m[1];
+    } catch {}
+  }
+  return null;
+}
+function cacheDir() {
+  return join3(installPaths().dataDir, "claude-code-specs");
+}
+function cacheFile(version) {
+  return join3(cacheDir(), `${version}.json`);
+}
+function knownHookSpec(version) {
+  if (version === VERIFIED_HOOK_SPEC.claudeCode)
+    return VERIFIED_HOOK_SPEC;
+  try {
+    const file = cacheFile(version);
+    return existsSync(file) ? JSON.parse(readFileSync2(file, "utf8")) : null;
+  } catch {
+    return null;
+  }
+}
+function cacheHookSpec(spec) {
+  mkdirSync(cacheDir(), { recursive: true });
+  writeFileSync(cacheFile(spec.claudeCode), `${JSON.stringify(spec, null, 2)}
+`);
+}
+async function getJson(url) {
+  const res = await fetch(url, { headers: { accept: "application/json" } });
+  if (!res.ok)
+    throw new Error(`GET ${url} \u2192 HTTP ${res.status}`);
+  return await res.json();
+}
+async function sdkReleases() {
+  const doc = await getJson(`${REGISTRY}/${SDK_PACKAGE.replace("/", "%2f")}`);
+  const releases = Object.values(doc.versions).sort((a, b) => (doc.time[a.version] ?? "").localeCompare(doc.time[b.version] ?? ""));
+  return { releases, latest: doc["dist-tags"].latest ?? "" };
+}
+function tarEntry(tgz, path) {
+  const tar = gunzipSync(tgz);
+  let off = 0;
+  while (off + 512 <= tar.length) {
+    const name = tar.subarray(off, off + 100).toString("utf8").replace(/\0.*$/s, "");
+    if (!name)
+      return null;
+    const size = Number.parseInt(tar.subarray(off + 124, off + 136).toString("utf8").trim(), 8);
+    const body = off + 512;
+    if (name === path)
+      return tar.subarray(body, body + size).toString("utf8");
+    off = body + Math.ceil(size / 512) * 512;
+  }
+  return null;
+}
+async function fetchHookSpec(version) {
+  const { releases } = await sdkReleases();
+  const release = releases.filter((r) => r.claudeCodeVersion === version).at(-1);
+  if (!release)
+    throw new Error(`no ${SDK_PACKAGE} release names Claude Code ${version}`);
+  const res = await fetch(release.dist.tarball);
+  if (!res.ok)
+    throw new Error(`GET ${release.dist.tarball} \u2192 HTTP ${res.status}`);
+  const tgz = new Uint8Array(await res.arrayBuffer());
+  const integrity = release.dist.integrity;
+  if (integrity?.startsWith("sha512-")) {
+    const got = `sha512-${createHash("sha512").update(tgz).digest("base64")}`;
+    if (got !== integrity)
+      throw new Error(`${SDK_PACKAGE}@${release.version}: integrity mismatch`);
+  }
+  const dts = tarEntry(tgz, "package/sdk.d.ts");
+  if (!dts)
+    throw new Error(`${SDK_PACKAGE}@${release.version} has no sdk.d.ts`);
+  return parseSdkHookSpec(dts, { claudeCode: version, sdk: release.version });
+}
+
+// packages/cli/src/commands/compat.ts
+async function specFor(version) {
+  const known = knownHookSpec(version);
+  if (known)
+    return known;
+  const spec = await fetchHookSpec(version);
+  cacheHookSpec(spec);
+  return spec;
+}
+async function runCompat(argv) {
+  const { positionals, options } = parseFlags(argv);
+  const action = positionals[0] ?? "check";
+  const version = strOpt(options, "cc-version") ?? claudeCodeVersion();
+  if (!version) {
+    console.error("compat: can't tell which Claude Code is installed \u2014 pass --cc-version");
+    return 2;
+  }
+  let spec;
+  try {
+    spec = await specFor(version);
+  } catch (err) {
+    console.error(`compat: no hook spec for Claude Code ${version}: ${err.message}`);
+    return 2;
+  }
+  if (action === "fetch") {
+    if (!options.json)
+      console.log(`compat: hook spec for Claude Code ${version} (${spec.sdk})`);
+    return 0;
+  }
+  const report = compareHookSpec(HOOK_TYPES, VERIFIED_HOOK_SPEC, version, spec);
+  if (options.json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    for (const line of formatHookCompat(report)) {
+      if (!line.includes("claude-transcripts compat"))
+        console.log(line);
+    }
+    console.log(`
+checked against: Claude Code ${version} via @anthropic-ai/claude-agent-sdk@${spec.sdk}` + `
+this build:      verified on Claude Code ${VERIFIED_HOOK_SPEC.claudeCode}`);
+  }
+  return hasDrift(report) ? 1 : 0;
+}
+
 // packages/cli/src/commands/completions.ts
 var BIN = "claude-transcripts";
 async function runCompletions(argv) {
@@ -3466,13 +4065,13 @@ async function runDoctor(argv) {
 }
 
 // packages/cli/src/commands/export.ts
-import { mkdirSync as mkdirSync2 } from "fs";
+import { mkdirSync as mkdirSync3 } from "fs";
 import { hostname as hostname3 } from "os";
-import { join as join5 } from "path";
+import { join as join6 } from "path";
 
 // packages/cli/src/lib/app-config.ts
-import { existsSync, readFileSync as readFileSync2 } from "fs";
-import { join as join3 } from "path";
+import { existsSync as existsSync2, readFileSync as readFileSync3 } from "fs";
+import { join as join4 } from "path";
 
 // packages/cli/src/lib/assets.generated.ts
 var EMBEDDED_ASSETS = {
@@ -3855,7 +4454,11 @@ exec fossil server "$@"
     "logging": {
       "chunk": { "maxEntriesPerChunk": 200, "flushIntervalMs": 15000 }
     },
-    "sessions": { "liveWindowMs": 86400000, "idleThresholdMs": 300000 },
+    "sessions": {
+      "liveWindowMs": 86400000,
+      "idleThresholdMs": 300000,
+      "reconcile": { "follower": true, "intervalMs": 3600000, "batchSize": 50 }
+    },
     "search": { "flushIntervalMs": 180000, "taskRetentionMs": 3600000 }
   },
   "couchdb": {
@@ -3913,10 +4516,10 @@ exec fossil server "$@"
 
 // packages/cli/src/lib/app-config.ts
 function repoConfig() {
-  const root = join3(import.meta.dir, "..", "..", "..", "..");
+  const root = join4(import.meta.dir, "..", "..", "..", "..");
   for (const name of ["config.json", "config.template.json"]) {
-    const p = join3(root, "config", name);
-    if (existsSync(p))
+    const p = join4(root, "config", name);
+    if (existsSync2(p))
       return p;
   }
   return null;
@@ -3926,16 +4529,16 @@ function loadAppConfig() {
   const candidates = [paths.appConfig, repoConfig()].filter((p) => Boolean(p));
   for (const path of candidates) {
     try {
-      if (existsSync(path))
-        return JSON.parse(readFileSync2(path, "utf8"));
+      if (existsSync2(path))
+        return JSON.parse(readFileSync3(path, "utf8"));
     } catch {}
   }
   return JSON.parse(EMBEDDED_ASSETS.appConfig.content);
 }
 
 // packages/cli/src/lib/bundle.ts
-import { chmodSync, existsSync as existsSync2, mkdirSync, readFileSync as readFileSync3, writeFileSync } from "fs";
-import { join as join4 } from "path";
+import { chmodSync, existsSync as existsSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync4, writeFileSync as writeFileSync2 } from "fs";
+import { join as join5 } from "path";
 var BUNDLE_FORMAT = 1;
 var MANIFEST_FILE = "manifest.json";
 var DOCS_FILE = "docs.ndjson";
@@ -3952,28 +4555,28 @@ function isExportableDoc(id, type) {
 function bundlePaths(dir) {
   return {
     dir,
-    manifest: join4(dir, MANIFEST_FILE),
-    docs: join4(dir, DOCS_FILE),
-    blobs: join4(dir, BLOBS_DIR),
-    blobDir: (sessionId) => join4(dir, BLOBS_DIR, sessionId)
+    manifest: join5(dir, MANIFEST_FILE),
+    docs: join5(dir, DOCS_FILE),
+    blobs: join5(dir, BLOBS_DIR),
+    blobDir: (sessionId) => join5(dir, BLOBS_DIR, sessionId)
   };
 }
 function prepareBundleDir(dir) {
-  mkdirSync(dir, { recursive: true, mode: 448 });
-  mkdirSync(join4(dir, BLOBS_DIR), { recursive: true, mode: 448 });
+  mkdirSync2(dir, { recursive: true, mode: 448 });
+  mkdirSync2(join5(dir, BLOBS_DIR), { recursive: true, mode: 448 });
 }
 function writeManifest(dir, manifest) {
-  writeFileSync(bundlePaths(dir).manifest, `${JSON.stringify(manifest, null, 2)}
+  writeFileSync2(bundlePaths(dir).manifest, `${JSON.stringify(manifest, null, 2)}
 `, {
     mode: 384
   });
 }
 function readManifest(dir) {
   const p = bundlePaths(dir).manifest;
-  if (!existsSync2(p)) {
+  if (!existsSync3(p)) {
     throw new Error(`no ${MANIFEST_FILE} in ${dir} \u2014 not a bundle, or the export was interrupted`);
   }
-  return JSON.parse(readFileSync3(p, "utf8"));
+  return JSON.parse(readFileSync4(p, "utf8"));
 }
 function toBundleDoc(doc) {
   const { _rev, ...rest } = doc;
@@ -4020,7 +4623,7 @@ function formatBytes(n) {
 
 // packages/cli/src/commands/export.ts
 var PAGE = 500;
-async function getJson(path) {
+async function getJson2(path) {
   const res = await fetch(`${webapiUrl()}${path}`);
   if (!res.ok)
     throw new Error(`GET ${path} \u2192 ${res.status} ${res.statusText}`);
@@ -4028,7 +4631,7 @@ async function getJson(path) {
 }
 async function schemaVersion() {
   try {
-    const s = await getJson("/api/migrate/status");
+    const s = await getJson2("/api/migrate/status");
     return s.currentVersion ?? 0;
   } catch {
     return 0;
@@ -4036,7 +4639,7 @@ async function schemaVersion() {
 }
 async function appVersion() {
   try {
-    const h = await getJson("/health");
+    const h = await getJson2("/health");
     return h.version ?? "unknown";
   } catch {
     return "unknown";
@@ -4075,7 +4678,7 @@ async function runExport(argv) {
       });
       if (startkey)
         params.set("startkey", JSON.stringify(startkey));
-      const page = await getJson(`/api/couch/${encodeURIComponent(db)}/_all_docs?${params}`);
+      const page = await getJson2(`/api/couch/${encodeURIComponent(db)}/_all_docs?${params}`);
       const rows = page.rows ?? [];
       const batch = rows.slice(0, PAGE);
       if (!batch.length)
@@ -4126,8 +4729,8 @@ async function runExport(argv) {
         const res = await fetch(`${webapiUrl()}/api/s3/sessions/${sid}/${name}`);
         if (!res.ok || !res.body)
           continue;
-        mkdirSync2(paths.blobDir(sid), { recursive: true, mode: 448 });
-        const target = join5(paths.blobDir(sid), name);
+        mkdirSync3(paths.blobDir(sid), { recursive: true, mode: 448 });
+        const target = join6(paths.blobDir(sid), name);
         const { bytes, sha256 } = await streamToFile(res.body, target);
         checksums[`blobs/${sid}/${name}`] = sha256;
         blobCount++;
@@ -4160,7 +4763,7 @@ async function runExport(argv) {
 }
 
 // packages/cli/src/commands/hook.ts
-import { existsSync as existsSync3, mkdirSync as mkdirSync3, readFileSync as readFileSync7, writeFileSync as writeFileSync3 } from "fs";
+import { existsSync as existsSync4, mkdirSync as mkdirSync4, readFileSync as readFileSync8, writeFileSync as writeFileSync4 } from "fs";
 import { dirname as dirname2 } from "path";
 
 // packages/cli/src/lib/statusline.ts
@@ -4349,11 +4952,11 @@ function osc8(url, text) {
 import {
   closeSync,
   openSync,
-  readFileSync as readFileSync4,
+  readFileSync as readFileSync5,
   readSync,
   statSync as statSync2,
   unlinkSync,
-  writeFileSync as writeFileSync2
+  writeFileSync as writeFileSync3
 } from "fs";
 import { hostname as hostname4 } from "os";
 var {S3Client } = globalThis.Bun;
@@ -4383,6 +4986,26 @@ function uploadArgv(sessionId, transcriptPath) {
   return [...cliArgv(), "hook", "upload", "--session", sessionId, "--transcript", transcriptPath];
 }
 
+// packages/cli/src/hook/compat.ts
+var REAL = {
+  version: () => claudeCodeVersion(),
+  spec: knownHookSpec,
+  fetch: (version) => spawnDetached([...cliArgv(), "compat", "fetch", "--cc-version", version])
+};
+function hookCompatLines(deps = REAL) {
+  try {
+    const version = deps.version();
+    if (!version)
+      return ["? Hook spec not checked \u2014 `claude --version` gave no answer"];
+    const spec = deps.spec(version);
+    if (!spec)
+      deps.fetch(version);
+    return formatHookCompat(compareHookSpec(HOOK_TYPES, VERIFIED_HOOK_SPEC, version, spec));
+  } catch {
+    return [];
+  }
+}
+
 // packages/cli/src/hook/mirror.ts
 var DEFAULT_TIMEOUT_MS = 2000;
 var DEFAULT_BLOB_TIMEOUT_MS = 60000;
@@ -4508,7 +5131,7 @@ function normalizeHookConfig(raw) {
 }
 function loadHookConfig(path) {
   try {
-    const raw = JSON.parse(readFileSync4(path, "utf8"));
+    const raw = JSON.parse(readFileSync5(path, "utf8"));
     if (!raw?.couch?.url)
       return null;
     return normalizeHookConfig(raw);
@@ -4619,14 +5242,14 @@ function makeCounts(sessionId) {
   const file = `/tmp/claude-transcripts-${sessionId}.counts`;
   const read = () => {
     try {
-      return JSON.parse(readFileSync4(file, "utf8"));
+      return JSON.parse(readFileSync5(file, "utf8"));
     } catch {
       return emptyCounts();
     }
   };
   const write = (c) => {
     try {
-      writeFileSync2(file, JSON.stringify(c));
+      writeFileSync3(file, JSON.stringify(c));
     } catch {}
   };
   return {
@@ -4656,14 +5279,14 @@ function makeTargets(sessionId) {
   const file = targetsFile(sessionId);
   const read = () => {
     try {
-      return JSON.parse(readFileSync4(file, "utf8"));
+      return JSON.parse(readFileSync5(file, "utf8"));
     } catch {
       return null;
     }
   };
   const write = (t) => {
     try {
-      writeFileSync2(file, JSON.stringify(t));
+      writeFileSync3(file, JSON.stringify(t));
     } catch {}
   };
   return {
@@ -4743,14 +5366,14 @@ function makeChunkState(sessionId) {
   const lockFile = `/tmp/claude-transcripts-${sessionId}.chunklock`;
   const load = () => {
     try {
-      return JSON.parse(readFileSync4(stateFile, "utf8"));
+      return JSON.parse(readFileSync5(stateFile, "utf8"));
     } catch {
       return { offset: 0, lastFlushMs: 0 };
     }
   };
   const save = (s) => {
     try {
-      writeFileSync2(stateFile, JSON.stringify(s));
+      writeFileSync3(stateFile, JSON.stringify(s));
     } catch {}
   };
   return {
@@ -4826,6 +5449,7 @@ function buildContext(payload, config) {
   const sessionsDb = config.couch.databases.sessions ?? DEFAULT_SESSIONS_DB;
   return {
     output: {},
+    hookCompat: () => hookCompatLines(),
     chunkHighWater: () => fetchChunkHighWater(config, sessionsDb, sessionId),
     event,
     sessionId,
@@ -4869,10 +5493,12 @@ function recordingBanner(targets, sessionId) {
 }
 var NOT_RECORDING_BANNER = "\u25CB Claude Transcripts not recording \u2014 no instance configured. Run `claude-transcripts install`.";
 function sessionStartEnvelope(out) {
-  if (!out.systemMessage && !out.additionalContext)
+  const systemMessage = [out.systemMessage, ...out.notices ?? []].filter(Boolean).join(`
+`);
+  if (!systemMessage && !out.additionalContext)
     return null;
   return {
-    ...out.systemMessage ? { systemMessage: out.systemMessage } : {},
+    ...systemMessage ? { systemMessage } : {},
     ...out.additionalContext ? {
       hookSpecificOutput: {
         hookEventName: "SessionStart",
@@ -4891,7 +5517,7 @@ function emitSessionStart(out) {
 }
 
 // packages/cli/src/hook/handlers.ts
-import { readFileSync as readFileSync5, statSync as statSync3 } from "fs";
+import { readFileSync as readFileSync6, statSync as statSync3 } from "fs";
 
 // packages/cli/src/hook/recall.ts
 var FACTS_TIMEOUT_MS = 2000;
@@ -4981,6 +5607,13 @@ var announceRecording = async (ctx) => {
   const targets = ctx.targets.read() ?? resolveTargets(ctx.config, safeWebapiUrl());
   ctx.output.systemMessage = recordingBanner(targets, ctx.sessionId);
 };
+var checkHookCompat = async (ctx) => {
+  if (ctx.payload?.source === "compact")
+    return;
+  const lines = ctx.hookCompat();
+  if (lines.length)
+    ctx.output.notices = [...ctx.output.notices ?? [], ...lines];
+};
 var injectRecallPolicy = async (ctx) => {
   const primer = await buildPrimer(ctx);
   if (primer)
@@ -5109,7 +5742,7 @@ var writeSummary = async (ctx) => {
   let transcriptBytes = 0;
   if (ctx.transcriptPath) {
     try {
-      jsonl = readFileSync5(ctx.transcriptPath, "utf8");
+      jsonl = readFileSync6(ctx.transcriptPath, "utf8");
       transcriptBytes = Buffer.byteLength(jsonl);
     } catch {}
   }
@@ -5135,7 +5768,7 @@ var writeSummary = async (ctx) => {
 async function uploadTranscript(blob, bucket, sessionId, transcriptPath) {
   let data;
   try {
-    data = readFileSync5(transcriptPath, "utf8");
+    data = readFileSync6(transcriptPath, "utf8");
   } catch {
     return;
   }
@@ -5151,6 +5784,7 @@ var uploadBlobs = async (ctx) => {
 var HANDLERS = {
   "seed-session-start": seedSessionStart,
   "announce-recording": announceRecording,
+  "check-hook-compat": checkHookCompat,
   "inject-recall-policy": injectRecallPolicy,
   "update-counts": updateCounts,
   "write-event-marker": writeEventMarker,
@@ -5215,35 +5849,35 @@ async function dispatch(raw, configPath) {
 }
 
 // packages/cli/src/lib/plugin.ts
-import { readFileSync as readFileSync6 } from "fs";
-import { dirname, join as join6 } from "path";
+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(readFileSync6(path, "utf8"));
+    const parsed = JSON.parse(readFileSync7(path, "utf8"));
     return parsed && typeof parsed === "object" ? parsed : null;
   } catch {
     return null;
   }
 }
 function pluginsDir(settingsPath) {
-  return join6(dirname(settingsPath), "plugins");
+  return join7(dirname(settingsPath), "plugins");
 }
 function pluginEvents(settingsPath, key) {
-  const installed = readJson(join6(pluginsDir(settingsPath), "installed_plugins.json"));
+  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 hooks = readJson(join6(installPath, "hooks", "hooks.json"));
+  const hooks = readJson(join7(installPath, "hooks", "hooks.json"));
   const events = hooks?.hooks;
   if (!events || typeof events !== "object")
     return;
   return Object.keys(events);
 }
 function pluginVersion(settingsPath, key) {
-  const installed = readJson(join6(pluginsDir(settingsPath), "installed_plugins.json"));
+  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;
@@ -5269,7 +5903,7 @@ function pluginRegistration(settingsPath, settings) {
 // packages/cli/src/commands/hook.ts
 function readSettings(path) {
   try {
-    return JSON.parse(readFileSync7(path, "utf8"));
+    return JSON.parse(readFileSync8(path, "utf8"));
   } catch {
     return {};
   }
@@ -5366,8 +6000,8 @@ function install(argv) {
     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(dirname2(paths.claudeSettings), { recursive: true });
-  writeFileSync3(paths.claudeSettings, `${JSON.stringify({ ...settings, hooks }, null, 2)}
+  mkdirSync4(dirname2(paths.claudeSettings), { recursive: true });
+  writeFileSync4(paths.claudeSettings, `${JSON.stringify({ ...settings, hooks }, null, 2)}
 `);
   const notes = [
     replaced ? `replaced ${replaced} stale registration(s)` : "",
@@ -5398,7 +6032,7 @@ function uninstall() {
     if (kept.length)
       hooks[event] = kept;
   }
-  writeFileSync3(paths.claudeSettings, `${JSON.stringify({ ...settings, hooks }, null, 2)}
+  writeFileSync4(paths.claudeSettings, `${JSON.stringify({ ...settings, hooks }, null, 2)}
 `);
   console.log(`hook: removed ${removed} registration(s) from ${paths.claudeSettings}`);
   const plugin = pluginRegistration(paths.claudeSettings, settings);
@@ -5408,7 +6042,7 @@ function uninstall() {
 }
 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 [];
@@ -5425,7 +6059,7 @@ function status() {
   const found = findRegistered(settings);
   const plugin = pluginRegistration(paths.claudeSettings, settings);
   console.log(`hook: settings   ${paths.claudeSettings}`);
-  console.log(`hook: config     ${paths.hookConfig} ${existsSync3(paths.hookConfig) ? "" : "(MISSING \u2014 run `install`)"}`);
+  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)}`);
@@ -5499,8 +6133,8 @@ async function runHook(argv) {
 }
 
 // packages/cli/src/commands/import.ts
-import { existsSync as existsSync4, statSync as statSync4 } from "fs";
-import { join as join7 } from "path";
+import { existsSync as existsSync5, statSync as statSync4 } from "fs";
+import { join as join8 } from "path";
 var BATCH = 500;
 function num(n) {
   return n.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ",");
@@ -5570,8 +6204,8 @@ function checkSchema(bundleVersion, target, registry = REAL_REGISTRY) {
 async function verifyChecksums(dir, manifest) {
   const bad = [];
   for (const [rel, expected] of Object.entries(manifest.checksums)) {
-    const path = join7(dir, rel);
-    if (!existsSync4(path)) {
+    const path = join8(dir, rel);
+    if (!existsSync5(path)) {
       bad.push(`${rel} (missing)`);
       continue;
     }
@@ -5704,7 +6338,7 @@ async function runImport(argv) {
   let blobs = 0;
   let blobBytes = 0;
   let skipped = 0;
-  if (withBlobs && existsSync4(paths.blobs)) {
+  if (withBlobs && existsSync5(paths.blobs)) {
     for (const rel of Object.keys(manifest.checksums)) {
       if (!rel.startsWith("blobs/"))
         continue;
@@ -5715,7 +6349,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 += statSync4(path).size;
@@ -5739,58 +6373,58 @@ async function runImport(argv) {
 }
 
 // packages/cli/src/commands/install.ts
-import { existsSync as existsSync8, readFileSync as readFileSync12 } from "fs";
-import { join as join9 } from "path";
+import { existsSync as existsSync9, readFileSync as readFileSync13 } from "fs";
+import { join as join10 } from "path";
 
 // packages/cli/src/lib/assets.ts
 import {
-  existsSync as existsSync5,
+  existsSync as existsSync6,
   lstatSync,
-  mkdirSync as mkdirSync4,
-  readFileSync as readFileSync8,
+  mkdirSync as mkdirSync5,
+  readFileSync as readFileSync9,
   symlinkSync,
   unlinkSync as unlinkSync2,
-  writeFileSync as writeFileSync4
+  writeFileSync as writeFileSync5
 } from "fs";
-import { dirname as dirname3, 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);
-    if (isUserOwned && existsSync5(target)) {
+    const target = isUserOwned ? paths.appConfig : join9(paths.dataDir, asset.path);
+    if (isUserOwned && existsSync6(target)) {
       out.push({ path: target, changed: false });
       continue;
     }
-    const previous = existsSync5(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(dirname3(target), { recursive: true });
-    writeFileSync4(target, asset.content);
+    mkdirSync5(dirname3(target), { recursive: true });
+    writeFileSync5(target, asset.content);
     out.push({ path: target, changed: true });
   }
   return out;
 }
 function linkInstanceEnv(paths) {
-  const link = join8(paths.dataDir, ".env");
+  const link = join9(paths.dataDir, ".env");
   try {
     if (lstatSync(link, { throwIfNoEntry: false }))
       unlinkSync2(link);
   } catch {}
-  mkdirSync4(paths.dataDir, { recursive: true });
+  mkdirSync5(paths.dataDir, { recursive: true });
   symlinkSync(paths.instanceEnv, link);
 }
 function writeVersionStamp(paths, version) {
-  mkdirSync4(dirname3(paths.versionFile), { recursive: true });
-  writeFileSync4(paths.versionFile, `${version}
+  mkdirSync5(dirname3(paths.versionFile), { recursive: true });
+  writeFileSync5(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;
 }
 
@@ -5858,7 +6492,7 @@ function healthTargets(env) {
 }
 
 // packages/cli/src/lib/hook-config.ts
-import { chmodSync as chmodSync2, mkdirSync as mkdirSync5, readFileSync as readFileSync9, writeFileSync as writeFileSync5 } from "fs";
+import { chmodSync as chmodSync2, mkdirSync as mkdirSync6, readFileSync as readFileSync10, writeFileSync as writeFileSync6 } from "fs";
 import { dirname as dirname4 } from "path";
 function buildHookConfig(app, env) {
   const user = env.COUCHDB_USER;
@@ -5892,7 +6526,7 @@ function webapiFromEnv(env) {
 var PRESERVED_KEYS = ["mirrors", "webapi"];
 function readExisting(path) {
   try {
-    const parsed = JSON.parse(readFileSync9(path, "utf8"));
+    const parsed = JSON.parse(readFileSync10(path, "utf8"));
     return parsed && typeof parsed === "object" ? parsed : {};
   } catch {
     return {};
@@ -5908,8 +6542,8 @@ function mergePreserved(next, existing) {
 }
 function writeHookConfig(path, config) {
   const merged = mergePreserved(config ?? {}, readExisting(path));
-  mkdirSync5(dirname4(path), { recursive: true });
-  writeFileSync5(path, `${JSON.stringify(merged, null, 2)}
+  mkdirSync6(dirname4(path), { recursive: true });
+  writeFileSync6(path, `${JSON.stringify(merged, null, 2)}
 `);
   chmodSync2(path, 384);
 }
@@ -5986,7 +6620,7 @@ function renderPruneReport(report, repo) {
 
 // packages/cli/src/lib/instance-env.ts
 import { randomBytes } from "crypto";
-import { chmodSync as chmodSync3, existsSync as existsSync6, mkdirSync as mkdirSync6, readFileSync as readFileSync10, writeFileSync as writeFileSync6 } from "fs";
+import { chmodSync as chmodSync3, existsSync as existsSync7, mkdirSync as mkdirSync7, readFileSync as readFileSync11, writeFileSync as writeFileSync7 } from "fs";
 import { dirname as dirname5 } from "path";
 var DEFAULT_PORT_BASE = 7650;
 var PORT_KEYS = [
@@ -6086,7 +6720,7 @@ function backfillPorts(existing) {
 }
 function loadOrCreateInstanceEnv(path, opts = {}) {
   const generated = buildInstanceEnv(opts);
-  const existing = existsSync6(path) ? parseEnv(readFileSync10(path, "utf8")) : {};
+  const existing = existsSync7(path) ? parseEnv(readFileSync11(path, "utf8")) : {};
   const merged = { ...generated, ...backfillPorts(existing), ...existing };
   for (const key of INSTALLER_OWNED) {
     if (generated[key] !== undefined)
@@ -6100,12 +6734,12 @@ function loadOrCreateInstanceEnv(path, opts = {}) {
   return merged;
 }
 function writeInstanceEnv(path, env) {
-  mkdirSync6(dirname5(path), { recursive: true });
-  writeFileSync6(path, formatEnv(env, HEADER));
+  mkdirSync7(dirname5(path), { recursive: true });
+  writeFileSync7(path, formatEnv(env, HEADER));
   chmodSync3(path, 384);
 }
 function updateInstanceEnv(path, patch) {
-  const env = existsSync6(path) ? parseEnv(readFileSync10(path, "utf8")) : {};
+  const env = existsSync7(path) ? parseEnv(readFileSync11(path, "utf8")) : {};
   const next = { ...env, ...patch };
   writeInstanceEnv(path, next);
   return next;
@@ -6387,11 +7021,11 @@ async function removeStaleKeys(api, keep) {
 }
 
 // packages/cli/src/commands/statusline.ts
-import { existsSync as existsSync7, mkdirSync as mkdirSync7, readFileSync as readFileSync11, writeFileSync as writeFileSync7 } from "fs";
+import { existsSync as existsSync8, mkdirSync as mkdirSync8, readFileSync as readFileSync12, writeFileSync as writeFileSync8 } from "fs";
 import { dirname as dirname6 } from "path";
 function readSettings2(path) {
   try {
-    return JSON.parse(readFileSync11(path, "utf8"));
+    return JSON.parse(readFileSync12(path, "utf8"));
   } catch {
     return {};
   }
@@ -6409,7 +7043,7 @@ async function render() {
     try {
       input = JSON.parse(await Bun.stdin.text());
     } catch {}
-    const configured = existsSync7(installPaths().hookConfig);
+    const configured = existsSync8(installPaths().hookConfig);
     const id = input.session_id;
     const targets = id ? makeTargets(id).read() : null;
     const line = renderStatusline({
@@ -6454,8 +7088,8 @@ function install2(argv) {
     console.log(`  ${JSON.stringify(next)}`);
     return 0;
   }
-  mkdirSync7(dirname6(paths.claudeSettings), { recursive: true });
-  writeFileSync7(paths.claudeSettings, `${JSON.stringify({ ...settings, statusLine: next }, null, 2)}
+  mkdirSync8(dirname6(paths.claudeSettings), { recursive: true });
+  writeFileSync8(paths.claudeSettings, `${JSON.stringify({ ...settings, statusLine: next }, null, 2)}
 `);
   console.log(`statusline: registered \u2192 ${paths.claudeSettings}`);
   console.log("statusline: restart any open Claude Code session for it to take effect.");
@@ -6473,7 +7107,7 @@ function uninstall2() {
     return 1;
   }
   const { statusLine: _drop, ...rest } = settings;
-  writeFileSync7(paths.claudeSettings, `${JSON.stringify(rest, null, 2)}
+  writeFileSync8(paths.claudeSettings, `${JSON.stringify(rest, null, 2)}
 `);
   console.log(`statusline: removed from ${paths.claudeSettings}`);
   return 0;
@@ -6597,7 +7231,7 @@ async function runInstall(argv) {
   const noPrune = options["no-prune"] === true;
   const portBaseOpt = strOpt(options, "port-base");
   const paths = installPaths();
-  const priorAppTag = existsSync8(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}`);
@@ -6625,8 +7259,8 @@ async function runInstall(argv) {
     portBase = found;
   }
   step(2, TOTAL, "Configuration");
-  const firstRun = !existsSync8(paths.instanceEnv);
-  const priorKeys = new Set(firstRun ? [] : Object.keys(parseEnv(readFileSync12(paths.instanceEnv, "utf8"))));
+  const firstRun = !existsSync9(paths.instanceEnv);
+  const priorKeys = new Set(firstRun ? [] : Object.keys(parseEnv(readFileSync13(paths.instanceEnv, "utf8"))));
   let env = loadOrCreateInstanceEnv(paths.instanceEnv, {
     portBase,
     appTag: VERSION === DEV_VERSION ? "main" : VERSION,
@@ -6730,7 +7364,7 @@ async function runInstall(argv) {
 install: done.`);
   console.log(`  UI       http://127.0.0.1:${env.WEBAPI_PORT}/app`);
   console.log(`  API      http://127.0.0.1:${env.WEBAPI_PORT}/api/docs`);
-  console.log(`  data     ${join9(paths.deployDir, "data")} (survives uninstall unless --purge)`);
+  console.log(`  data     ${join10(paths.deployDir, "data")} (survives uninstall unless --purge)`);
   console.log("  remove   claude-transcripts uninstall");
   return 0;
 }
@@ -6790,10 +7424,10 @@ async function runMigrate(argv) {
 }
 
 // packages/cli/src/commands/provision.ts
-import { existsSync as existsSync9 } from "fs";
+import { existsSync as existsSync10 } from "fs";
 async function runProvision(_argv) {
   const paths = installPaths();
-  if (!existsSync9(paths.instanceEnv)) {
+  if (!existsSync10(paths.instanceEnv)) {
     console.error("provision: this machine has no instance \u2014 run `claude-transcripts install` first.");
     return 1;
   }
@@ -6824,6 +7458,112 @@ async function runProvision(_argv) {
   return ok ? 0 : 1;
 }
 
+// packages/cli/src/commands/reconcile.ts
+var PAGE2 = 500;
+async function incompleteSessions() {
+  const out = [];
+  for (let skip = 0;; skip += PAGE2) {
+    const page = await listSessions({ status: "incomplete", limit: PAGE2, skip });
+    out.push(...page.sessions);
+    if (out.length >= page.totalCount || page.sessions.length === 0)
+      return out;
+  }
+}
+async function sessionOrNull(id) {
+  try {
+    return await getSession(id);
+  } catch (err) {
+    if (isConnectionError(err))
+      throw err;
+    return null;
+  }
+}
+async function reconcileOne(s, opts) {
+  const sessionId = s.sessionId;
+  if (s.status === "ended")
+    return { sessionId, result: "skipped", reason: "already ended" };
+  if (s.status === "running" && !opts.force) {
+    return { sessionId, result: "skipped", reason: "still running (--force to finalise it)" };
+  }
+  try {
+    const transcript = opts.blobs ? await getTextOrNull(`/api/s3/sessions/${encodeURIComponent(sessionId)}/transcript.jsonl`) : null;
+    const doc = buildReconciledSummary(s, transcript, opts.now);
+    if (!opts.dryRun)
+      await opts.sink.putSummary(doc);
+    return {
+      sessionId,
+      result: opts.dryRun ? "would-reconcile" : "reconciled",
+      tokens: transcript !== null
+    };
+  } catch (err) {
+    return { sessionId, result: "failed", reason: err.message };
+  }
+}
+function describe(o) {
+  const tokens = o.tokens === false ? "  (no S3 transcript \u2014 no token totals)" : "";
+  switch (o.result) {
+    case "reconciled":
+      return `  finalised  ${o.sessionId}${tokens}`;
+    case "would-reconcile":
+      return `  would finalise  ${o.sessionId}${tokens}`;
+    case "skipped":
+      return `  skipped    ${o.sessionId} \u2014 ${o.reason}`;
+    case "failed":
+      return `  FAILED     ${o.sessionId} \u2014 ${o.reason}`;
+  }
+}
+async function runReconcile(argv) {
+  const { positionals, options } = parseFlags(argv);
+  const webapi = strOpt(options, "webapi");
+  if (webapi)
+    setWebapiUrl(webapi);
+  const json = options.json === true;
+  const dryRun = options["dry-run"] === true;
+  const force = options.force === true;
+  if (!await webapiReachable()) {
+    console.error(unreachableHint("reconcile"));
+    return 1;
+  }
+  const outcomes = [];
+  const now = new Date().toISOString();
+  const sink = new WebapiSink;
+  try {
+    const manifest = await getOrNull("/");
+    const blobs = manifest?.features?.s3Blobs !== false;
+    const sessions = [];
+    if (positionals.length) {
+      for (const id of positionals) {
+        const s = await sessionOrNull(id);
+        if (s)
+          sessions.push(s);
+        else
+          outcomes.push({ sessionId: id, result: "failed", reason: "no such session" });
+      }
+    } else {
+      sessions.push(...await incompleteSessions());
+    }
+    for (const s of sessions) {
+      outcomes.push(await reconcileOne(s, { dryRun, force, now, blobs, sink }));
+    }
+  } catch (err) {
+    console.error(`reconcile: failed \u2014 ${err.message}`);
+    console.error(unreachableHint("reconcile"));
+    return 1;
+  }
+  const failed = outcomes.filter((o) => o.result === "failed").length;
+  if (json) {
+    console.log(JSON.stringify({ dryRun, outcomes }, null, 2));
+  } else if (!outcomes.length) {
+    console.log("reconcile: nothing to finalise \u2014 no session reads as incomplete");
+  } else {
+    for (const o of outcomes)
+      console.log(describe(o));
+    const done = outcomes.filter((o) => o.result === "reconciled" || o.result === "would-reconcile");
+    console.log(`reconcile: ${dryRun ? "would finalise" : "finalised"} ${done.length}, skipped ${outcomes.length - done.length - failed}, failed ${failed}`);
+  }
+  return failed ? 1 : 0;
+}
+
 // packages/cli/src/commands/reindex.ts
 function num2(n) {
   return n.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ",");
@@ -7142,18 +7882,18 @@ async function runSessions(argv) {
 }
 
 // packages/cli/src/commands/setup.ts
-import { existsSync as existsSync10, mkdirSync as mkdirSync8, readFileSync as readFileSync13, writeFileSync as writeFileSync8 } from "fs";
+import { existsSync as existsSync11, mkdirSync as mkdirSync9, readFileSync as readFileSync14, writeFileSync as writeFileSync9 } from "fs";
 import { homedir as homedir3 } from "os";
-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");
+import { dirname as dirname7, join as join11 } from "path";
+var REPO_ROOT = join11(import.meta.dir, "..", "..", "..", "..");
+var HOOK_DIR = join11(REPO_ROOT, "hooks");
+var HOOK_CONFIG_PATH = process.env.CT_HOOK_CONFIG ?? join11(homedir3(), ".config", "claude-transcripts", "config.json");
 var GLOBAL_SETTINGS = installPaths().claudeSettings;
-var PROJECT_SETTINGS = join10(process.cwd(), ".claude", "settings.json");
+var PROJECT_SETTINGS = join11(process.cwd(), ".claude", "settings.json");
 function loadRepoConfig() {
-  const live = join10(REPO_ROOT, "config", "config.json");
-  const template = join10(REPO_ROOT, "config", "config.template.json");
-  return JSON.parse(readFileSync13(existsSync10(live) ? live : template, "utf8"));
+  const live = join11(REPO_ROOT, "config", "config.json");
+  const template = join11(REPO_ROOT, "config", "config.template.json");
+  return JSON.parse(readFileSync14(existsSync11(live) ? live : template, "utf8"));
 }
 function couchHeaders(auth) {
   const h = { "Content-Type": "application/json" };
@@ -7203,7 +7943,7 @@ async function probeGarage(blob) {
 }
 function readSettings3(path) {
   try {
-    const parsed = JSON.parse(readFileSync13(path, "utf8"));
+    const parsed = JSON.parse(readFileSync14(path, "utf8"));
     return parsed && typeof parsed === "object" ? parsed : {};
   } catch {
     return {};
@@ -7212,7 +7952,7 @@ function readSettings3(path) {
 function globalRegistrationBlockedBy(settingsPath = GLOBAL_SETTINGS) {
   return pluginRegistration(settingsPath, readSettings3(settingsPath));
 }
-var DISPATCH_PATH = join10(HOOK_DIR, "scripts", "dispatch.ts");
+var DISPATCH_PATH = join11(HOOK_DIR, "scripts", "dispatch.ts");
 function dispatchCommand() {
   return hookLaunch(`bun run "${DISPATCH_PATH}"`);
 }
@@ -7223,7 +7963,7 @@ function isRegistered(path) {
 }
 function registerGlobal(dryRun) {
   const cmd = dispatchCommand();
-  const generated = JSON.parse(readFileSync13(join10(HOOK_DIR, "hooks", "hooks.json"), "utf8"));
+  const generated = JSON.parse(readFileSync14(join11(HOOK_DIR, "hooks", "hooks.json"), "utf8"));
   const settings = readSettings3(GLOBAL_SETTINGS);
   const hooks = settings.hooks ?? {};
   for (const [event, groups] of Object.entries(generated.hooks)) {
@@ -7243,8 +7983,8 @@ function registerGlobal(dryRun) {
     console.log(`  [check] would register ${Object.keys(generated.hooks).length} events in ${GLOBAL_SETTINGS}`);
     return;
   }
-  mkdirSync8(dirname7(GLOBAL_SETTINGS), { recursive: true });
-  writeFileSync8(GLOBAL_SETTINGS, `${JSON.stringify({ ...settings, hooks }, null, 2)}
+  mkdirSync9(dirname7(GLOBAL_SETTINGS), { recursive: true });
+  writeFileSync9(GLOBAL_SETTINGS, `${JSON.stringify({ ...settings, hooks }, null, 2)}
 `);
   console.log(`  registered ${Object.keys(generated.hooks).length} events (system-wide) in ${GLOBAL_SETTINGS}`);
 }
@@ -7253,7 +7993,7 @@ function registerProject() {
 }
 function reportExisting() {
   const g = isRegistered(GLOBAL_SETTINGS);
-  const p = existsSync10(PROJECT_SETTINGS) && isRegistered(PROJECT_SETTINGS);
+  const p = existsSync11(PROJECT_SETTINGS) && isRegistered(PROJECT_SETTINGS);
   console.log(`  existing registration \u2192 global: ${g ? "yes" : "no"}, this project: ${p ? "yes" : "no"}`);
   const plugin = globalRegistrationBlockedBy();
   if (plugin) {
@@ -7289,7 +8029,7 @@ async function runSetup(argv) {
   reportExisting();
   if (check) {
     console.log("setup --check (read-only):");
-    console.log(`  hook config: ${existsSync10(HOOK_CONFIG_PATH) ? "present" : "MISSING"} (${HOOK_CONFIG_PATH})`);
+    console.log(`  hook config: ${existsSync11(HOOK_CONFIG_PATH) ? "present" : "MISSING"} (${HOOK_CONFIG_PATH})`);
     console.log(`  couch: ${couch.url}`);
     await provisionCouch2(couch, true);
     await probeGarage(hookConfig.blob);
@@ -7320,12 +8060,12 @@ async function runSetup(argv) {
 }
 
 // packages/cli/src/commands/stack.ts
-import { existsSync as existsSync11 } from "fs";
+import { existsSync as existsSync12 } from "fs";
 async function runStack(argv) {
   const { positionals, options } = parseFlags(argv);
   const cmd = positionals[0] ?? "ps";
   const paths = installPaths();
-  if (!existsSync11(paths.instanceEnv)) {
+  if (!existsSync12(paths.instanceEnv)) {
     console.error("stack: this machine has no instance \u2014 run `claude-transcripts install` first.");
     return 1;
   }
@@ -7463,8 +8203,8 @@ async function runTurns(argv) {
 }
 
 // packages/cli/src/commands/uninstall.ts
-import { existsSync as existsSync12, readdirSync, rmSync } from "fs";
-import { join as join11 } from "path";
+import { existsSync as existsSync13, readdirSync, rmSync } from "fs";
+import { join as join12 } from "path";
 var DATA_SUBDIR = "data";
 function removeDeployDir(deployDir, purge) {
   if (purge) {
@@ -7479,7 +8219,7 @@ function removeDeployDir(deployDir, purge) {
   }
   for (const entry of entries) {
     if (entry !== DATA_SUBDIR)
-      rmSync(join11(deployDir, entry), { recursive: true, force: true });
+      rmSync(join12(deployDir, entry), { recursive: true, force: true });
   }
 }
 async function confirmPurge(auto) {
@@ -7502,7 +8242,7 @@ async function runUninstall(argv) {
   console.log("uninstall: deregistering the hook and the statusline");
   await runHook(["uninstall"]);
   await runStatusline(["uninstall"]);
-  if (existsSync12(paths.instanceEnv)) {
+  if (existsSync13(paths.instanceEnv)) {
     console.log("uninstall: stopping the stack");
     try {
       const env = loadOrCreateInstanceEnv(paths.instanceEnv);
@@ -7517,7 +8257,7 @@ async function runUninstall(argv) {
       rmSync(target, { recursive: true, force: true });
     } catch {}
   }
-  const dataDir = join11(paths.deployDir, DATA_SUBDIR);
+  const dataDir = join12(paths.deployDir, DATA_SUBDIR);
   try {
     removeDeployDir(paths.deployDir, purge);
   } catch (err) {
@@ -7554,6 +8294,8 @@ var COMMANDS = {
   migrate: runMigrate,
   reindex: runReindex,
   doctor: runDoctor,
+  reconcile: runReconcile,
+  compat: runCompat,
   sessions: runSessions,
   search: runSearch,
   turns: runTurns,