@yugabytedb/meko-mcp 2.1.0 → 2.2.0

package/assets/hooks-handlers/lib/capture.js

@@ -1,14 +1,29 @@
 #!/usr/bin/env node
 /**
- * capture.js — Unified conversation capture for Meko MCP plugin.
+ * capture.js — Unified conversation capture for Meko MCP plugin (Capture V2).
  *
- * Handles transcript parsing, watermark management, and MCP API calls.
- * No external dependencies — uses only Node.js built-ins (fs, http/https, crypto).
+ * Handles transcript parsing, durable outbox state, and MCP API calls.
+ * Drain engine (`drainSession`) is shared by checkpoint, pre-compact,
+ * session-end, and CLI recovery. State/leases live in `./capture-state`.
  *
- * Usage (called by hook shell wrappers):
- *   node capture.js session-start # creates conversation + watermark, outputs additionalContext
- *   node capture.js pre-compact   # reads hook input from stdin
- *   node capture.js session-end   # reads hook input from stdin
+ * Usage (called by hook shell wrappers / Workstream C scheduler):
+ *   node capture.js session-start  # intent-first create + watermark
+ *   node capture.js pre-compact    # stdin hook JSON → drainSession
+ *   node capture.js session-end    # stdin hook JSON → drainSession (closing)
+ *   node capture.js checkpoint     # stdin hook JSON → drainSession
+ *   node capture.js drain          # stdin JSON → drain one session; stdout DrainResult
+ *   node capture.js recover        # alias of drain (single-session recovery)
+ *
+ * drain / recover stdin contract (Workstream C):
+ *   {
+ *     "session_id": "<id>",                 // required (or derived from transcript_path)
+ *     "transcript_path": "<path>",          // optional if state already has it
+ *     "lifecycle": "active|closing|closed", // optional; session-end forces closing
+ *     "confirmed_dead": true,               // optional; finalize interrupted trailing turn
+ *     "recorded_owner_only": true,          // optional; no rebucket (recovery)
+ *     "max_exchanges": <int>                // optional; else MEKO_MAX_CAPTURE_BATCH_SIZE
+ *   }
+ *   stdout: one JSON DrainResult object (see docs/plans/meko-capture-v2-contracts.md)
  *
  * Environment:
  *   MEKO_MCP_URL       MCP server URL (default: http://localhost:8000/mcp)
@@ -18,6 +33,7 @@
  *   MEKO_API_KEY        API key for Cloud Meko auth (optional, omit for local)
  *   MEKO_API_TIMEOUT   Request timeout in seconds (default: 10)
  *   MEKO_WATERMARK_DIR Watermark directory (default: ~/.claude/meko-capture)
+ *   MEKO_MAX_CAPTURE_BATCH_SIZE  Max exchanges per drain (default 5, min 1)
  */
 
 const fs = require("fs");
@@ -25,6 +41,7 @@ const os = require("os");
 const path = require("path");
 const http = require("http");
 const https = require("https");
+const captureState = require("./capture-state");
 
 // --- Config ---
 
@@ -41,7 +58,7 @@ const AGENT_ID_MAX_LEN = 64;
  * in a separate package with no module dependencies on the installer.
  *
  *   - `envOverride` (typically MEKO_AGENT_ID) wins if non-empty.
- *   - Coding clients (claude_code, cursor) → `<client>:<repo-basename>`,
+ *   - Coding clients (claude_code, cursor, codex, kiro) → `<client>:<repo-basename>`,
  *     with the basename lowercased and non-`[a-z0-9-]` runs collapsed to `-`.
  *     Outside a repo → bare client name (keeps coding-agent traffic out of
  *     the common bucket).
@@ -53,7 +70,14 @@ function deriveAgentId(opts) {
   if (override) return override;
   const client = (opts && opts.client ? String(opts.client) : "").trim();
   if (client === "claude-desktop" || client === "claude_desktop") return "claude_desktop";
-  if (client !== "claude_code" && client !== "cursor") return COMMON_BUCKET_AGENT_ID;
+  if (
+    client !== "claude_code" &&
+    client !== "cursor" &&
+    client !== "codex" &&
+    client !== "kiro"
+  ) {
+    return COMMON_BUCKET_AGENT_ID;
+  }
   const rawBase = opts && opts.cwd ? path.basename(opts.cwd) : "";
   if (!rawBase || rawBase === "." || rawBase === "/") return client;
   const project = rawBase.toLowerCase()
@@ -64,6 +88,20 @@ function deriveAgentId(opts) {
   return `${client}:${project}`;
 }
 
+/**
+ * Map MEKO_HOOK_CLIENT to a known coding-client identity. The installer
+ * prefixes each client's hook commands with `MEKO_HOOK_CLIENT=<client>`;
+ * cursor and codex are first-class coding clients, everything else (including
+ * an unset value) defaults to claude_code. Keeping this in one place means
+ * every call path — SessionStart, watermark write, PreCompact/SessionEnd
+ * re-derivation — resolves the same identity for a given client.
+ */
+function resolveHookClient() {
+  const client = (process.env.MEKO_HOOK_CLIENT || "").trim();
+  if (client === "cursor" || client === "codex" || client === "kiro") return client;
+  return "claude_code";
+}
+
 /**
  * Resolve the agent_id for the current session. Frozen at SessionStart;
  * subsequent hook invocations re-derive from the watermark + env, not
@@ -101,9 +139,134 @@ function resolveSessionAgentId(transcriptPath, hookInput = null) {
     hookInput?.cwd ||
     nested.cwd ||
     process.cwd();
-  const client = process.env.MEKO_HOOK_CLIENT === "cursor" ? "cursor" : "claude_code";
+  const client = resolveHookClient();
   return deriveAgentId({ client, cwd, envOverride });
 }
+
+// Coding clients that derive a `<client>:<repo>` agent_id. Kept in
+// sync with deriveAgentId's coding-client branch.
+const CODING_CLIENTS = ["claude_code", "cursor", "codex", "kiro"];
+
+/**
+ * Extract the client segment of an agent_id: the part before the first `:`,
+ * or the whole string for a bare client name. `codex:my-repo` → `codex`,
+ * `claude_code` → `claude_code`, `custom_bucket` → `custom_bucket`.
+ */
+function clientOfAgentId(agentId) {
+  const id = (typeof agentId === "string" ? agentId : "").trim();
+  return id.includes(":") ? id.slice(0, id.indexOf(":")) : id;
+}
+
+/**
+ * True if `agentId` looks like an auto-derived coding-client identity, i.e.
+ * `<coding-client>:<something>` or the bare client name. Used to tell a
+ * stale auto-derived value (safe to re-derive) apart from a user-chosen
+ * bucket (must be preserved).
+ */
+function isDerivedCodingAgentId(agentId) {
+  return CODING_CLIENTS.includes(clientOfAgentId(agentId));
+}
+
+/**
+ * Reconcile a cached watermark agent_id with the current hook invocation.
+ *
+ * Upgrade path (MEKO-385): a watermark written by the OLD Codex hook holds
+ * `claude_code:<repo>` because the pre-fix hook collapsed every non-cursor
+ * client to claude_code. After upgrade, a SessionStart re-fire (/clear,
+ * /compact) or a checkpoint/PreCompact/SessionEnd hook must NOT keep writing
+ * into that wrong namespace. So when the current client derives a different
+ * coding-client identity than the cached one, and the cached value is a
+ * plain auto-derived coding id (not a user bucket), we re-derive.
+ *
+ * Resolution order:
+ *   1. Current MEKO_AGENT_ID override wins verbatim — it is the live source of
+ *      truth and equals `derivedAgentId` (resolveSessionAgentId returns the
+ *      override first). This applies regardless of what the watermark cached,
+ *      including a source-less legacy watermark whose stale value must NOT be
+ *      preserved when a differing override is set now.
+ *   2. No usable cached value, or the legacy ghost literal "agent" → fresh
+ *      derivation.
+ *   3. A previously-recorded explicit override (agent_id_source==="explicit",
+ *      with no current env override to supersede it) → preserved verbatim.
+ *   4. Auto-derived cached value → re-derive ONLY when the CLIENT segment is
+ *      stale for the current client (claude_code:<repo> under a now-codex
+ *      session). We compare the client, not the whole id: a differing repo
+ *      basename alone (same client) is NOT a reason to re-derive — that would
+ *      clobber a legitimately preserved project bucket on resume.
+ *
+ * The returned agent_id may differ from the conversation's current owner; when
+ * it does the caller must open a NEW conversation under it (see
+ * needsRebucket / rebucketConversation) because the server pins the owner at
+ * creation and rejects mismatched agent_id on an existing conversation.
+ *
+ * @param {string} cachedAgentId   agent_id read from the watermark.
+ * @param {string} cachedSource    watermark.agent_id_source ("" if legacy).
+ * @param {string} derivedAgentId  freshly derived identity for this session.
+ * @returns {{agentId: string, source: "explicit"|"derived"}}
+ */
+function reconcileCachedAgentId(cachedAgentId, cachedSource, derivedAgentId) {
+  const cached = (typeof cachedAgentId === "string" ? cachedAgentId : "").trim();
+  const envOverride = (process.env.MEKO_AGENT_ID || "").trim();
+
+  // (1) A current env override always wins. derivedAgentId already equals the
+  // override (resolveSessionAgentId honors MEKO_AGENT_ID first), so applying it
+  // here never preserves a stale cached value against the live override.
+  if (envOverride) {
+    return { agentId: derivedAgentId, source: "explicit" };
+  }
+  // (2) No usable cached value, or the legacy ghost literal → fresh derivation.
+  if (!cached || cached === "agent") {
+    return { agentId: derivedAgentId, source: "derived" };
+  }
+  // (3) A previously-recorded explicit override (no current env override to
+  // supersede it) is preserved verbatim.
+  if (cachedSource === "explicit") {
+    return { agentId: cached, source: "explicit" };
+  }
+  // (4) Auto-derived cached value: re-derive only on a stale CLIENT segment.
+  if (
+    isDerivedCodingAgentId(cached)
+    && isDerivedCodingAgentId(derivedAgentId)
+    && clientOfAgentId(cached) !== clientOfAgentId(derivedAgentId)
+  ) {
+    return { agentId: derivedAgentId, source: "derived" };
+  }
+  // Otherwise keep the cached derived value (non-coding custom bucket, or
+  // already the right client).
+  return { agentId: cached, source: "derived" };
+}
+
+/**
+ * True when the existing conversation may NOT be owned by the agent_id we
+ * resolved for this invocation, so the caller must open a fresh conversation
+ * under the resolved id before writing. The server pins the owner at creation
+ * and rejects a mismatched agent_id on an existing conversation (src/tools.py:
+ * conversation_add_message returns `agent_id_mismatch`), so reusing a
+ * wrong-owner conversation would make every future write fail closed and wedge
+ * the watermark forever.
+ *
+ * Two triggering cases, given a non-empty conversation_id:
+ *   - the cached owner differs from the resolved id (a real client-mismatch
+ *     upgrade, e.g. claude_code:<repo> → codex:<repo>); or
+ *   - the cached owner is EMPTY/unknown. A legacy or partially-written
+ *     watermark can carry a conversation_id with no agent_id; we don't know
+ *     who owns that conversation, and silently reusing it under the resolved
+ *     id risks agent_id_mismatch on every write with no way to self-heal. So
+ *     unknown-owner is treated as "needs a conversation we know we own".
+ *
+ * @param {string} cachedAgentId    watermark.agent_id (the conversation owner).
+ * @param {string} resolvedAgentId  agent_id resolved for this invocation.
+ * @param {string} convId           watermark.conversation_id (may be empty).
+ * @returns {boolean}
+ */
+function ownerChanged(cachedAgentId, resolvedAgentId, convId) {
+  const conv = (typeof convId === "string" ? convId : "").trim();
+  if (!conv) return false; // no existing conversation → nothing to reconcile
+  const cached = (typeof cachedAgentId === "string" ? cachedAgentId : "").trim();
+  if (!cached) return true; // conversation exists but owner unknown → reconcile
+  return cached !== resolvedAgentId;
+}
+
 const MEKO_API_KEY = process.env.MEKO_API_KEY || "";
 const MEKO_API_TIMEOUT = parseInt(process.env.MEKO_API_TIMEOUT || "10", 10) * 1000;
 const WATERMARK_DIR =
@@ -113,6 +276,10 @@ const SESSION_CACHE_DIR =
   process.env.MEKO_SESSION_CACHE_DIR ||
   path.join(os.homedir(), ".cursor", "meko-session-cache");
 
+/** Exact interrupted-turn assistant marker (contracts). */
+const INTERRUPTED_ASSISTANT_OUTPUT =
+  "[Meko capture: assistant response was interrupted before completion.]";
+
 let mcpRequestId = 0;
 let mcpSessionId = null; // MCP Streamable HTTP session ID
 const inflightRequests = new Set(); // tracked so preload timeouts can abort
@@ -230,56 +397,231 @@ function extractToolResultContent(msg) {
 
 // --- Turn-assembly exchange extraction ---
 
-function extractExchanges(filePath, startLine) {
+// Codex turn-completion boundary discriminator.
+//
+// A single Codex task emits MULTIPLE assistant `response_item` messages within
+// one turn: `phase: "commentary"` progress updates stream first, and the turn
+// ends with the `phase: "final_answer"` reply, after which Codex writes an
+// `event_msg` whose `payload.type` is `"task_complete"`. A checkpoint can fire
+// after commentary but before the final answer, so a mid-stream turn is only
+// safe to consume once one of these boundaries has arrived — otherwise the
+// trailing (still-streaming) assistant messages would be read on a later run
+// without their user and dropped.
+//
+// The in-progress SIGNAL is a `commentary`-phase assistant message with no
+// following completion boundary. A turn whose assistant message carries no
+// phase at all is the legacy/simple shape (no streaming): it's complete as
+// soon as any assistant message exists, exactly as before — so we never hold
+// such a turn forever waiting for a boundary it will never emit.
+//
+// These are named constants so the Codex migrator adapter (PR #232,
+// installer/lib/migrate/adapters/codex.mjs) can mirror the SAME definition:
+// in-progress = a CODEX_COMMENTARY_PHASE assistant message with no boundary;
+// boundary = an assistant message with phase === CODEX_FINAL_ANSWER_PHASE, or
+// an event_msg with payload.type === CODEX_TASK_COMPLETE_TYPE.
+const CODEX_COMMENTARY_PHASE = "commentary";
+const CODEX_FINAL_ANSWER_PHASE = "final_answer";
+const CODEX_TASK_COMPLETE_TYPE = "task_complete";
+
+/**
+ * Normalize a Codex rollout record into the Claude-shaped entry the
+ * turn-assembly below expects. Codex wraps each turn in a `response_item`
+ * envelope with `payload.type === "message"` and role-specific content
+ * blocks (`input_text` for the user, `output_text` for the assistant).
+ *
+ * Two record kinds are surfaced:
+ *   - `response_item` messages → user/assistant entries (assistant entries
+ *     carry `codexPhase` so turn-assembly can tell an in-progress `commentary`
+ *     message from the `final_answer` that ends the turn).
+ *   - the `event_msg` whose `payload.type` is `task_complete` → a lightweight
+ *     `{ type: "codex_task_complete" }` boundary marker, so turn-assembly
+ *     knows the trailing assistant sequence is finished.
+ *
+ * Every other `event_msg` mirrors `response_item` text as a UI event and is
+ * dropped (returns null), so each turn is captured exactly once. Returns null
+ * for non-Codex input too, so Claude Code / Cursor records fall through to
+ * their own branch in parseTranscriptEntries untouched.
+ */
+function normalizeCodexEntry(obj, lineIndex) {
+  if (!obj || typeof obj !== "object") return null;
+  if (obj.type === "event_msg") {
+    const p = obj.payload;
+    if (p && p.type === CODEX_TASK_COMPLETE_TYPE) {
+      return { type: "codex_task_complete" };
+    }
+    return null;
+  }
+  if (obj.type !== "response_item") return null;
+  const payload = obj.payload;
+  if (!payload || payload.type !== "message") return null;
+  const role = payload.role;
+  if (role !== "user" && role !== "assistant") return null;
+  const wantType = role === "user" ? "input_text" : "output_text";
+  const blocks = Array.isArray(payload.content) ? payload.content : [];
+  const text = blocks
+    .filter((b) => b && (b.type === wantType || b.type === "text"))
+    .map((b) => (typeof b.text === "string" ? b.text : ""))
+    .filter(Boolean)
+    .join("\n");
+  const explicitId = obj.id || payload.id || obj.uuid;
+  const timestamp = obj.timestamp || payload.timestamp || "";
+  // Real Codex rollout records frequently omit id/payload.id/uuid on
+  // response_item messages. Falling back to a constant ("unknown") gave every
+  // user turn the same addMessage dedup seed (`${convId}:unknown`), so all but
+  // the first were collapsed as duplicates. When no explicit id exists, derive
+  // a stable, unique-per-turn id from fields real records DO carry: the
+  // record's timestamp plus its line position in the transcript. Position is
+  // deterministic across re-parses of the same file (so PreCompact/SessionEnd
+  // retries stay idempotent) yet distinct per turn (so turns aren't collapsed).
+  const uuid = explicitId || `codex-${timestamp || "no-ts"}-line${lineIndex}`;
+  const entry = {
+    type: role,
+    uuid,
+    timestamp,
+    codex: true,
+    message: { role, content: [{ type: "text", text }] },
+  };
+  if (role === "assistant") {
+    // Codex may put the phase on the payload or the envelope; check both.
+    const phase = payload.phase || obj.phase;
+    entry.codexPhase = typeof phase === "string" ? phase : "";
+  }
+  return entry;
+}
+
+/**
+ * Parse the transcript lines after `startLine` into the user/assistant
+ * entries turn-assembly consumes. Recognizes both Claude Code / Cursor
+ * records (top-level `type` of `user`/`assistant`) and Codex `response_item`
+ * message records (via normalizeCodexEntry). Each element is
+ * `{ entry, line }`, pairing the normalized entry with its 0-based line index
+ * in the transcript so buildExchanges can report the last safely-consumed
+ * line. Returns the raw entry list so callers can distinguish "no eligible
+ * records" from "records present but zero exchanges" when deciding whether to
+ * advance the watermark.
+ */
+function parseTranscriptEntries(filePath, startLine) {
   const data = fs.readFileSync(filePath, "utf-8");
   const lines = data.split("\n");
 
-  // Step 1: Parse relevant lines
   const entries = [];
   for (let i = startLine; i < lines.length; i++) {
     const line = lines[i].trim();
     if (!line) continue;
+    let obj;
     try {
-      const obj = JSON.parse(line);
-      if (obj.type === "user" || obj.type === "assistant") {
-        entries.push(obj);
-      }
+      obj = JSON.parse(line);
     } catch {
       continue;
     }
+    if (obj.type === "user" || obj.type === "assistant") {
+      entries.push({ entry: obj, line: i });
+      continue;
+    }
+    const codexEntry = normalizeCodexEntry(obj, i);
+    if (codexEntry) entries.push({ entry: codexEntry, line: i });
   }
+  return entries;
+}
 
-  // Step 2: Group into exchanges using turn-assembly.
-  // A real user message (no toolUseResult) starts a new exchange.
-  // All subsequent assistant lines and tool-result user lines belong
-  // to that exchange until the next real user message.
-  const exchanges = [];
+/**
+ * Group parsed entries into exchanges using turn-assembly, then render each
+ * exchange to the { input, output, reasoning } shape addMessage sends.
+ *
+ * A real user message (no toolUseResult) starts a new exchange. All
+ * subsequent assistant lines and tool-result user lines belong to that
+ * exchange until the next real user message.
+ *
+ * `items` is the `{ entry, line }` list from parseTranscriptEntries. Returns
+ * `{ exchanges, pendingFromLine }`:
+ *   - `exchanges` — the renderable exchange list (unchanged contract). All
+ *     assistant messages of a turn (Codex `commentary` … `final_answer`) are
+ *     folded into the single assistant side, not just the first.
+ *   - `pendingFromLine` — the 0-based transcript line index of a trailing
+ *     user turn that is renderable but NOT yet safe to consume, or `null`
+ *     otherwise. A turn is not safe to consume when it is still awaiting its
+ *     assistant reply, or — for Codex — when its assistant sequence has not
+ *     reached the completion boundary yet (no `phase: final_answer` message
+ *     and no `task_complete` marker). Callers advance the watermark only up to
+ *     this line so the in-progress turn is re-read and captured whole once it
+ *     finishes. `null` for a filtered/never-renderable trailing turn (e.g.
+ *     `<system-reminder>` only) so the watermark can advance past it, and for a
+ *     complete trailing turn, which advances fully.
+ */
+function buildExchanges(items) {
+  const skipPattern =
+    /^<(system-reminder|command-|local-command|available-deferred)/;
+  const turns = [];
   let current = null;
 
-  for (const entry of entries) {
+  for (const { entry, line } of items) {
     if (entry.type === "user" && !isToolResultMessage(entry)) {
-      if (current) exchanges.push(current);
+      if (current) turns.push(current);
       current = {
         userMsg: entry,
+        userLine: line,
         assistantEntries: [],
         toolResultEntries: [],
+        // Codex streaming turns end at a completion boundary (phase:
+        // final_answer, or a task_complete event_msg). `codexStreaming` marks a
+        // turn that emitted commentary and is therefore mid-stream until a
+        // boundary arrives. A Codex turn with no phase info at all is the
+        // legacy/simple shape — complete as soon as any assistant message
+        // exists, like non-Codex turns.
+        codexStreaming: false,
+        codexComplete: false,
       };
     } else if (current) {
       if (entry.type === "assistant") {
         current.assistantEntries.push(entry);
+        if (entry.codexPhase === CODEX_FINAL_ANSWER_PHASE) {
+          current.codexComplete = true;
+        } else if (entry.codexPhase === CODEX_COMMENTARY_PHASE) {
+          current.codexStreaming = true;
+        }
+      } else if (entry.type === "codex_task_complete") {
+        current.codexComplete = true;
       } else if (entry.type === "user" && isToolResultMessage(entry)) {
         current.toolResultEntries.push(entry);
       }
     }
   }
-  if (current) exchanges.push(current);
+  if (current) turns.push(current);
+
+  // Decide whether the TRAILING turn is safe to consume. A checkpoint can fire
+  // mid-turn (after the user, after some assistant commentary, but before the
+  // final answer / task_complete). Consuming it then would advance the
+  // watermark past the in-progress turn, so the later assistant messages get
+  // read without their user and dropped. A trailing turn is NOT safe to consume
+  // when it has no assistant reply yet, OR when it is a Codex turn still
+  // streaming commentary with no completion boundary. Hold only when that turn
+  // is actually renderable (real input, not a filtered marker); a filtered or
+  // never-renderable trailing turn produces no exchange regardless, so we let
+  // the watermark advance past it rather than reparse it forever.
+  let pendingFromLine = null;
+  const last = turns.length > 0 ? turns[turns.length - 1] : null;
+  const lastIncomplete = last
+    ? last.assistantEntries.length === 0 ||
+      (last.codexStreaming && !last.codexComplete)
+    : false;
+  if (last && lastIncomplete) {
+    const lastInput = extractText((last.userMsg.message || {}).content);
+    if (lastInput && !skipPattern.test(lastInput)) {
+      pendingFromLine = last.userLine;
+    }
+  }
 
-  // Step 3: Build output for each exchange
-  const skipPattern =
-    /^<(system-reminder|command-|local-command|available-deferred)/;
+  // Build output for each COMPLETE turn. The trailing turn is skipped while it
+  // is still pending (pendingFromLine set) so its partial assistant content is
+  // not captured early — it is captured whole on a later run.
   const results = [];
 
-  for (const ex of exchanges) {
+  for (let t = 0; t < turns.length; t++) {
+    const ex = turns[t];
+    const isPendingTrailing =
+      pendingFromLine !== null && t === turns.length - 1;
+    if (isPendingTrailing) continue;
+
     const input = extractText((ex.userMsg.message || {}).content);
     if (!input || skipPattern.test(input)) continue;
     if (ex.assistantEntries.length === 0) continue;
@@ -308,6 +650,13 @@ function extractExchanges(filePath, startLine) {
 
     results.push({
       user_uuid: ex.userMsg.uuid || "unknown",
+      // PR #262: line-keyed boundary so missing/duplicate uuids cannot skip
+      // remaining exchanges. Prefer this over uuid/index for cursor advances.
+      user_line: ex.userLine,
+      // PR #254: next user turn line, or null for the final complete turn
+      // (caller substitutes safeLine when draining the full suffix).
+      next_line_number:
+        t + 1 < turns.length ? turns[t + 1].userLine : null,
       input: input,
       output: outputParts.join("\n\n"),
       reasoning: reasoningParts.join("\n---\n"),
@@ -318,41 +667,202 @@ function extractExchanges(filePath, startLine) {
     });
   }
 
-  return results;
+  return { exchanges: results, pendingFromLine, turns };
+}
+
+/**
+ * Extract renderable exchanges from a transcript starting at `startLine`.
+ * Thin wrapper over parseTranscriptEntries + buildExchanges kept for the
+ * callers that only need the exchange list.
+ */
+function extractExchanges(filePath, startLine) {
+  return buildExchanges(parseTranscriptEntries(filePath, startLine)).exchanges;
 }
 
-// --- Watermark ---
+// --- Watermark / outbox (bridged to capture-state v2) ---
 
+/**
+ * Compatibility reader used by SessionStart resume/rebucket paths.
+ * Returns a flat object with the classic watermark fields. Corrupt files are
+ * surfaced via `__corrupt` so callers never invent a zero cursor.
+ */
 function readWatermark(wmPath) {
-  try {
-    return JSON.parse(fs.readFileSync(wmPath, "utf-8"));
-  } catch {
-    return { conversation_id: "", last_line_number: 0, agent_id: "" };
+  const sessionId = path.basename(wmPath, ".watermark.json");
+  const result = captureState.readState(sessionId);
+  if (result.ok && result.state) {
+    const s = result.state;
+    return {
+      conversation_id: s.conversation_id || "",
+      last_line_number: s.last_line_number || 0,
+      agent_id: s.agent_id || "",
+      agent_id_source: s.agent_id_source || "",
+      datapack_id: s.datapack_id || null,
+      datapack_name: s.datapack_name || null,
+      updated_at: s.updated_at || "",
+      lifecycle: s.lifecycle,
+      delivery: s.delivery,
+      schema_version: s.schema_version,
+      session_id: s.session_id,
+    };
   }
+  if (result.missing) {
+    return {
+      conversation_id: "",
+      last_line_number: 0,
+      agent_id: "",
+      agent_id_source: "",
+    };
+  }
+  return {
+    __corrupt: true,
+    failure_class: result.failure_class || "state_corrupt",
+    error: result.error || "corrupt watermark",
+    conversation_id: "",
+    last_line_number: 0,
+    agent_id: "",
+    agent_id_source: "",
+  };
 }
 
-function writeWatermark(wmPath, convId, lineNum, agentId, datapackPin = null) {
-  fs.mkdirSync(path.dirname(wmPath), { recursive: true });
-  const existing = readWatermark(wmPath);
+/**
+ * Persist outbox fields via capture-state. Never silently replaces a corrupt
+ * file. Conversation-id changes go through rebucket() so the epoch resets
+ * correctly instead of a non-monotonic cursor write.
+ */
+function writeWatermark(wmPath, convId, lineNum, agentId, datapackPin = null, agentIdSource = null) {
+  const sessionId = path.basename(wmPath, ".watermark.json");
+  const existing = captureState.readState(sessionId);
+  if (!existing.ok && !existing.missing && existing.failure_class === "state_corrupt") {
+    process.stderr.write(
+      `[meko-capture] refusing to overwrite corrupt watermark for ${sessionId}: ${existing.error}\n`,
+    );
+    return existing;
+  }
+
+  const now = new Date().toISOString();
+  let state = existing.ok
+    ? { ...existing.state }
+    : {
+        schema_version: 2,
+        session_id: sessionId,
+        client: resolveHookClient() || "",
+        agent_id: "",
+        agent_id_source: "",
+        transcript_path: null,
+        datapack_id: null,
+        datapack_name: null,
+        created_at: now,
+        updated_at: now,
+        last_activity_at: now,
+        conversation_id: null,
+        conversation_epoch: 0,
+        last_line_number: 0,
+        in_flight: { seed: null, user_line: null, user_turn_id: null },
+        lifecycle: "active",
+        delivery: "needs_conversation",
+        queued_exchanges: 0,
+        attempt_count: 0,
+        next_retry_at: null,
+        failure_class: null,
+        last_error: null,
+        last_success_at: null,
+        blocked_reason: null,
+      };
+
   const existingPin =
-    existing.datapack_id && existing.datapack_name
-      ? {
-          datapack_id: existing.datapack_id,
-          datapack_name: existing.datapack_name,
-        }
+    state.datapack_id && state.datapack_name
+      ? { datapack_id: state.datapack_id, datapack_name: state.datapack_name }
       : null;
   const pin = datapackPin || existingPin;
-  fs.writeFileSync(
-    wmPath,
-    JSON.stringify({
-      conversation_id: convId,
-      last_line_number: lineNum,
-      agent_id: agentId != null ? agentId : existing.agent_id || "",
-      datapack_id: pin ? pin.datapack_id : null,
-      datapack_name: pin ? pin.datapack_name : null,
-      updated_at: new Date().toISOString(),
-    })
-  );
+  const source =
+    agentIdSource != null ? agentIdSource : state.agent_id_source || "";
+
+  const prevConv = state.conversation_id || "";
+  const nextConv = convId || "";
+  const conversationChanged = Boolean(nextConv) && nextConv !== prevConv;
+
+  if (conversationChanged && prevConv) {
+    const rb = captureState.rebucket(state, nextConv);
+    if (!rb.ok) {
+      process.stderr.write(
+        `[meko-capture] rebucket failed for ${sessionId}: ${rb.error}\n`,
+      );
+      return rb;
+    }
+    state = rb.state;
+    if (lineNum > 0) {
+      const adv = captureState.advanceCursor(state, lineNum, { clearSeed: true });
+      if (adv.ok) state = adv.state;
+    }
+  } else {
+    state.conversation_id = nextConv || null;
+    const targetLine = Number(lineNum) || 0;
+    if (targetLine > state.last_line_number) {
+      const adv = captureState.advanceCursor(state, targetLine, { clearSeed: true });
+      if (adv.ok) state = adv.state;
+    } else if (targetLine === state.last_line_number) {
+      // no-op cursor; still refresh identity/datapack below
+    } else if (!existing.ok || existing.missing) {
+      state.last_line_number = targetLine;
+    } else if (conversationChanged && !prevConv) {
+      // First conversation bind on an intent-only outbox — cursor may be 0.
+      state.last_line_number = targetLine;
+    }
+  }
+
+  state.agent_id = agentId != null ? agentId : state.agent_id || "";
+  state.agent_id_source = source;
+  state.datapack_id = pin ? pin.datapack_id : null;
+  state.datapack_name = pin ? pin.datapack_name : null;
+  if (state.conversation_id) {
+    if (state.delivery === "needs_conversation" || !state.delivery) {
+      state.delivery = "idle";
+    }
+  }
+  state.last_activity_at = now;
+  state.updated_at = now;
+
+  return captureState.writeState(sessionId, state);
+}
+
+/** Real user-turn line indexes from a parseTranscriptEntries result (PR #262). */
+function realUserTurnLines(entries) {
+  const lines = [];
+  for (const { entry, line } of entries) {
+    if (entry.type === "user" && !isToolResultMessage(entry)) {
+      lines.push(line);
+    }
+  }
+  return lines;
+}
+
+/**
+ * First line that must remain unread after the exchange opening at `userLine`
+ * is durably captured — the next real user turn — or null when none remains.
+ */
+function boundaryAfterExchange(turnLines, userLine) {
+  if (typeof userLine !== "number") return null;
+  for (const line of turnLines) {
+    if (line > userLine) return line;
+  }
+  return null;
+}
+
+function makeDrainResult(partial) {
+  return {
+    status: partial.status || "noop",
+    session_id: partial.session_id || "",
+    captured: partial.captured || 0,
+    queued_remaining: partial.queued_remaining || 0,
+    failure_class: partial.failure_class != null ? partial.failure_class : null,
+    error: partial.error != null ? partial.error : null,
+    cursor_advanced: Boolean(partial.cursor_advanced),
+    last_line_number:
+      partial.last_line_number != null ? partial.last_line_number : 0,
+    lifecycle: partial.lifecycle || "active",
+    delivery: partial.delivery || "idle",
+    next_retry_at: partial.next_retry_at || null,
+  };
 }
 
 /**
@@ -367,45 +877,6 @@ function datapackPinSlug(agentId) {
   return trimmed.replace(/[^A-Za-z0-9._-]+/g, "_").replace(/^_+|_+$/g, "") || COMMON_BUCKET_AGENT_ID;
 }
 
-function captureErrorPath(agentId) {
-  return path.join(WATERMARK_DIR, `last-capture-error-${datapackPinSlug(agentId)}.json`);
-}
-
-function readCaptureError(agentId) {
-  try {
-    const error = JSON.parse(fs.readFileSync(captureErrorPath(agentId), "utf-8"));
-    return error && typeof error === "object" ? error : null;
-  } catch {
-    return null;
-  }
-}
-
-function writeCaptureError(agentId, error) {
-  try {
-    fs.mkdirSync(WATERMARK_DIR, { recursive: true });
-    fs.writeFileSync(
-      captureErrorPath(agentId),
-      JSON.stringify({
-        ...error,
-        agent_id: agentId,
-        occurred_at: new Date().toISOString(),
-      }),
-    );
-  } catch (err) {
-    process.stderr.write(`[meko-capture] Could not persist capture error: ${err.message}\n`);
-  }
-}
-
-function clearCaptureError(agentId) {
-  try {
-    fs.unlinkSync(captureErrorPath(agentId));
-  } catch (err) {
-    if (err && err.code !== "ENOENT") {
-      process.stderr.write(`[meko-capture] Could not clear capture error: ${err.message}\n`);
-    }
-  }
-}
-
 /**
  * Read the active-datapack pin written by the meko-select-datapack skill.
  *
@@ -772,9 +1243,15 @@ async function fetchRecentMemories(agentId, datapackId = null, { limit = 10, bud
 }
 
 async function createConversation(sessionId, agentId, metadata = null, datapackId = null) {
+  const clientLabel = {
+    claude_code: "Claude Code",
+    cursor: "Cursor",
+    codex: "Codex",
+    kiro: "Kiro",
+  }[resolveHookClient()] || "Coding agent";
   const payload = {
     agent_id: agentId,
-    title: "Claude Code session (auto-captured)",
+    title: `${clientLabel} session (auto-captured)`,
     session_id: sessionId,
   };
   if (metadata) {
@@ -791,6 +1268,100 @@ async function createConversation(sessionId, agentId, metadata = null, datapackI
   return result && result.id ? result.id : null;
 }
 
+/**
+ * Ensure the conversation we are about to write to is owned by `resolvedAgentId`.
+ *
+ * The server pins a conversation's owner at `conversation_create` and rejects
+ * `conversation_add_message` / `conversation_update` whose agent_id differs
+ * (src/tools.py → `agent_id_mismatch`). There is no owner-reassign tool. So
+ * when MEKO-385 reconciliation changes the identity (e.g. a conversation the
+ * OLD Codex hook created under `claude_code:<repo>` must now be `codex:<repo>`),
+ * we CANNOT keep writing to the old conversation — every future write would
+ * fail closed and wedge the watermark. Instead we open a NEW conversation
+ * under the corrected agent_id and repoint the watermark at it (approach (a);
+ * no server reassign exists).
+ *
+ * The invariant this preserves: a watermark's `agent_id` always equals the
+ * owner of its `conversation_id`. So callers can detect a stale owner simply
+ * by comparing the cached agent_id against the freshly resolved one.
+ *
+ * On rebucket-create FAILURE the fallback depends on WHY the rebucket was
+ * demanded:
+ *   - EXPLICIT override (resolvedSource === "explicit", i.e. the user set
+ *     MEKO_AGENT_ID): do NOT fall back to capturing under the stale owner —
+ *     that would silently attribute turns to the wrong namespace in direct
+ *     violation of the explicit override. Instead HOLD: return `{ hold: true }`
+ *     so the caller sends no turns and does not advance the watermark, and a
+ *     later hook retries the rebucket. A visible diagnostic is emitted.
+ *   - DERIVED (auto-derived id): fall back to the ORIGINAL owner (old
+ *     conversation + old agent_id) so writes still succeed and the watermark
+ *     advances — strictly better than failing closed; a later hook retries.
+ *
+ * The invariant this preserves: a watermark's `agent_id` always equals the
+ * owner of its `conversation_id`.
+ *
+ * @returns {Promise<{convId: string, agentId: string, source: string,
+ *   rebucketed: boolean, hold?: boolean}>}
+ */
+async function ensureConversationOwner({
+  convId,
+  cachedOwner,
+  resolvedAgentId,
+  resolvedSource,
+  sessionId,
+  metadata = null,
+  datapackId = null,
+  mcpReady = false,
+}) {
+  if (!ownerChanged(cachedOwner, resolvedAgentId, convId)) {
+    return { convId, agentId: resolvedAgentId, source: resolvedSource, rebucketed: false };
+  }
+  try {
+    if (!mcpReady) await mcpInitialize();
+    const newId = await createConversation(
+      sessionId || "unknown",
+      resolvedAgentId,
+      metadata,
+      datapackId,
+    );
+    if (newId) {
+      process.stderr.write(
+        `[meko-capture] Rebucketed conversation ${convId} (owner ${cachedOwner || "unknown"}) -> ` +
+        `new ${newId} owned by ${resolvedAgentId} (server pins owner at create).\n`,
+      );
+      return { convId: newId, agentId: resolvedAgentId, source: resolvedSource, rebucketed: true };
+    }
+    process.stderr.write("[meko-capture] Rebucket conversation_create returned no ID.\n");
+  } catch (err) {
+    process.stderr.write(`[meko-capture] Rebucket conversation_create failed (${err.message}).\n`);
+  }
+  // Create failed. An EXPLICIT override must never be captured under the stale
+  // owner — hold and retry rather than write to the wrong namespace.
+  if (resolvedSource === "explicit") {
+    process.stderr.write(
+      `[meko-capture] Explicit MEKO_AGENT_ID override requires rebucketing to ` +
+      `${resolvedAgentId}, but conversation_create failed; HOLDING (no turns sent, ` +
+      `watermark not advanced) so a later hook retries — will not capture under the ` +
+      `stale owner ${cachedOwner || "unknown"}.\n`,
+    );
+    return { convId, agentId: resolvedAgentId, source: resolvedSource, rebucketed: false, hold: true };
+  }
+  // Derived case: fall back to the original owner so writes still succeed.
+  // (When the owner is unknown/empty there is nothing safe to fall back to —
+  // hold instead, since writing under an unknown owner risks agent_id_mismatch.)
+  if (!(cachedOwner || "").trim()) {
+    process.stderr.write(
+      "[meko-capture] Unknown-owner conversation and rebucket create failed; " +
+      "HOLDING (no turns sent) so a later hook retries.\n",
+    );
+    return { convId, agentId: resolvedAgentId, source: resolvedSource, rebucketed: false, hold: true };
+  }
+  process.stderr.write(
+    `[meko-capture] Keeping original owner ${cachedOwner} so writes still succeed.\n`,
+  );
+  return { convId, agentId: cachedOwner, source: "derived", rebucketed: false };
+}
+
 async function addMessage(convId, agentId, exchange, datapackId = null) {
   const seed = `${convId}:${exchange.user_uuid}`;
   const payload = {
@@ -802,6 +1373,12 @@ async function addMessage(convId, agentId, exchange, datapackId = null) {
     seed: seed,
   };
   if (datapackId) payload.datapack_id = datapackId;
+  if (exchange.metadata != null) {
+    payload.metadata =
+      typeof exchange.metadata === "string"
+        ? exchange.metadata
+        : JSON.stringify(exchange.metadata);
+  }
   const response = await mcpCall("conversation_add_message", payload);
   // FAIL CLOSED. The MCP transport resolves successfully even when the tool
   // failed, and failures take several shapes: an `isError` result envelope, a
@@ -825,6 +1402,19 @@ async function addMessage(convId, agentId, exchange, datapackId = null) {
   if (result.error) {
     throw new Error(`conversation_add_message failed: ${JSON.stringify(result.error)}`);
   }
+  // Contracts: advance only after a structurally valid accepted response that
+  // contains a message ID (server returns message_id; tolerate `id` aliases).
+  const messageId = result.message_id || result.id || null;
+  if (!messageId) {
+    throw new Error(
+      "conversation_add_message: accepted response missing message_id (fail-closed)",
+    );
+  }
+  if (result.status !== "accepted") {
+    throw new Error(
+      `conversation_add_message: unexpected status ${JSON.stringify(result.status)}`,
+    );
+  }
   return result;
 }
 
@@ -889,17 +1479,28 @@ function sessionCachePath(sessionId) {
 function writeSessionCache(sessionId, payload) {
   const filePath = sessionCachePath(sessionId);
   if (!filePath) return;
-  const workspaceKey = payload.workspace_key || "";
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  const record = {
-    session_id: sessionId,
-    updated_at: new Date().toISOString(),
-    ...payload,
-  };
-  fs.writeFileSync(filePath, JSON.stringify(record));
-  if (workspaceKey) {
-    const safe = workspaceKey.replace(/[^A-Za-z0-9_.-]/g, "_");
-    fs.writeFileSync(path.join(SESSION_CACHE_DIR, `workspace-${safe}.json`), JSON.stringify(record));
+  try {
+    const workspaceKey = payload.workspace_key || "";
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const record = {
+      session_id: sessionId,
+      updated_at: new Date().toISOString(),
+      ...payload,
+    };
+    fs.writeFileSync(filePath, JSON.stringify(record));
+    if (workspaceKey) {
+      const safe = workspaceKey.replace(/[^A-Za-z0-9_.-]/g, "_");
+      fs.writeFileSync(
+        path.join(SESSION_CACHE_DIR, `workspace-${safe}.json`),
+        JSON.stringify(record),
+      );
+    }
+  } catch (err) {
+    // Cursor's session cache is a rebuildable convenience; it must never turn
+    // a valid SessionStart context into an empty fallback response.
+    process.stderr.write(
+      `[meko-capture] SessionStart cache write skipped: ${err.message}\n`,
+    );
   }
 }
 
@@ -916,8 +1517,6 @@ function workspaceKeyFromHookInput(hookInput, transcriptPath) {
   return cwd || process.cwd();
 }
 
-// --- Main ---
-
 // --- SessionStart: create conversation + watermark deterministically ---
 
 function findMostRecentProjectWatermark(transcriptPath, currentSessionId) {
@@ -938,6 +1537,7 @@ function findMostRecentProjectWatermark(transcriptPath, currentSessionId) {
           sessionId: sid,
           conversation_id: wm.conversation_id,
           agent_id: wm.agent_id || "",
+          agent_id_source: wm.agent_id_source || "",
           datapack_id: wm.datapack_id || null,
           datapack_name: wm.datapack_name || null,
           updated_at: ts,
@@ -955,17 +1555,9 @@ function buildSessionStartContext(convId, sessionId, agentId, memories, opts) {
   const resolvedAgentId = agentId || COMMON_BUCKET_AGENT_ID;
   const resumed = Boolean(opts && opts.resumed);
   const pin = opts && opts.datapackPin ? opts.datapackPin : null;
-  const captureError = opts && opts.captureError ? opts.captureError : null;
   const opening = resumed
     ? `Resuming Meko conversation **${convId}** from a prior Claude Code session. The watermark file is written — PreCompact and SessionEnd hooks will attempt to append this session's new exchanges to the same conversation.`
     : `Meko conversation **${convId}** was created automatically by the SessionStart hook. The watermark file is written — PreCompact and SessionEnd hooks are configured to capture this session's transcript.`;
-  const captureWarning = captureError
-    ? `
-
-### Automatic capture warning — tell the user
-
-The last automatic capture attempt was persistently rejected because ${captureError.reason || "Meko rejected the write"}. **Do not claim that this session's turns are being saved.** The hook kept ${Number(captureError.held_exchanges || captureError.failed_exchanges) || 1} exchange(s) queued for retry instead of dropping them. Tell the user that automatic conversation capture is currently unhealthy and include this reason. This warning remains until a later hook write succeeds.`
-    : "";
   const memoryBlock =
     Array.isArray(memories) && memories.length > 0
       ? `
@@ -981,7 +1573,6 @@ ${memories.join("\n")}`
   return `## Meko Session Active
 
 ${opening}
-${captureWarning}
 
 ### What you MUST do with Meko tools
 
@@ -1074,6 +1665,18 @@ function handleBeforeSubmitPrompt(hookInput) {
   process.stdout.write(beforeSubmitOutput("allow"));
 }
 
+function withHealthNotice(context) {
+  try {
+    const { injectHealthNotice } = require("./capture-notices");
+    return injectHealthNotice(context);
+  } catch (err) {
+    process.stderr.write(
+      `[meko-capture] SessionStart health notice skipped: ${err && err.message ? err.message : err}\n`,
+    );
+    return context;
+  }
+}
+
 async function handleSessionStart(hookInput) {
   const transcriptPath =
     hookInput.transcript_path ||
@@ -1089,30 +1692,91 @@ async function handleSessionStart(hookInput) {
   if (sessionId) {
     const wmPath = path.join(WATERMARK_DIR, `${sessionId}.watermark.json`);
     const existing = readWatermark(wmPath);
+    if (existing.__corrupt) {
+      process.stderr.write(
+        `[meko-capture] SessionStart: corrupt watermark for ${sessionId} (${existing.error}); blocking.\n`,
+      );
+      const context = withHealthNotice(buildSessionStartFallbackContext(derivedAgentId, {
+        datapackPin: readDatapackPin(derivedAgentId),
+      }));
+      process.stdout.write(hookOutput(context));
+      return;
+    }
     if (existing.conversation_id) {
       process.stderr.write(`[meko-capture] Session ${sessionId}: reusing existing conversation ${existing.conversation_id}\n`);
       // Prefer the watermark's cached agent_id so a user-set bucket survives
-      // re-fires of SessionStart (e.g. /clear, /compact). The exception is
-      // the legacy literal "agent" left by pre-contract installers — we
-      // override that with the freshly derived `claude_code:<repo>` so
-      // upgraded users stop writing into the ghost namespace.
-      const cached = (existing.agent_id || "").trim();
-      const resumedAgentId = cached && cached !== "agent" ? cached : derivedAgentId;
+      // re-fires of SessionStart (e.g. /clear, /compact), BUT re-derive when
+      // the cached value is a stale auto-derived coding identity that no
+      // longer matches the current client — e.g. an old Codex hook wrote
+      // `claude_code:<repo>` before MEKO-385. reconcileCachedAgentId honors
+      // an explicit MEKO_AGENT_ID override (agent_id_source) and upgrades the
+      // legacy literal "agent". See its doc for existing-conversation
+      // consistency (same conversation_id; only future turns re-namespace).
+      const reconciled = reconcileCachedAgentId(
+        existing.agent_id,
+        existing.agent_id_source || "",
+        derivedAgentId,
+      );
       const existingDatapackPin = datapackPinFromWatermark(existing);
+      // If the reconciled identity differs from the conversation's owner (the
+      // cached agent_id), open a NEW conversation under it — the server pins
+      // the owner at create and rejects mismatched writes, so keeping the old
+      // conversation_id would wedge every future capture. ensureConversationOwner
+      // is a no-op (no MCP) when the owner is unchanged.
+      const owned = await ensureConversationOwner({
+        convId: existing.conversation_id,
+        cachedOwner: existing.agent_id,
+        resolvedAgentId: reconciled.agentId,
+        resolvedSource: reconciled.source,
+        sessionId,
+        metadata: peekTranscriptMetadata(transcriptPath),
+        datapackId: existingDatapackPin && existingDatapackPin.datapack_id,
+      });
+      // HOLD: rebucket required but conversation_create failed. Leave the
+      // existing watermark untouched (agent_id still equals the owner of its
+      // conversation_id) and inject context under the actual owner so nothing
+      // is written to the wrong namespace; a later hook retries the rebucket.
+      if (owned.hold) {
+        const holdContext = buildSessionStartContext(
+          existing.conversation_id,
+          sessionId,
+          existing.agent_id,
+          null,
+          {
+            datapackPin: existingDatapackPin,
+          },
+        );
+        process.stdout.write(hookOutput(withHealthNotice(holdContext)));
+        return;
+      }
+      const resumedAgentId = owned.agentId;
+      const resumedConvId = owned.convId;
+      // Persist the corrected identity + conversation (+ provenance) so the
+      // checkpoint / PreCompact / SessionEnd hooks read a consistent watermark
+      // (agent_id always equals the owner of conversation_id). On a rebucket
+      // reset last_line_number to 0 so this session's turns replay into the
+      // new conversation; otherwise preserve the prior line count.
+      writeWatermark(
+        wmPath,
+        resumedConvId,
+        owned.rebucketed ? 0 : (existing.last_line_number || 0),
+        resumedAgentId,
+        existingDatapackPin,
+        owned.source,
+      );
       // Skip preload on resume (we don't know what's already in context).
-      const context = buildSessionStartContext(
-        existing.conversation_id,
+      let context = withHealthNotice(buildSessionStartContext(
+        resumedConvId,
         sessionId,
         resumedAgentId,
         null,
         {
           datapackPin: existingDatapackPin,
-          captureError: readCaptureError(resumedAgentId),
         },
-      );
+      ));
       writeSessionCache(sessionId, {
         status: "ready",
-        conversation_id: existing.conversation_id,
+        conversation_id: resumedConvId,
         agent_id: resumedAgentId,
         workspace_key: workspaceKey,
         additional_context: context,
@@ -1132,38 +1796,73 @@ async function handleSessionStart(hookInput) {
     if (prior && prior.conversation_id) {
       const currentLineCount = fs.existsSync(transcriptPath) ? countLines(transcriptPath) : 0;
       const wmPath = path.join(WATERMARK_DIR, `${sessionId}.watermark.json`);
-      // Preserve a non-legacy cached agent_id from the prior watermark so a
-      // user-set bucket (e.g. MEKO_AGENT_ID=foo, or a project-scoped
-      // claude_code:<other-repo> from the original session) survives the
-      // resume. Mirrors the same-session reuse branch above. The legacy
-      // literal "agent" is overridden with the freshly derived per-project
-      // bucket so upgraded users stop writing into the ghost namespace.
-      const priorAgentId = (prior.agent_id || "").trim();
-      const resumedAgentId =
-        priorAgentId && priorAgentId !== "agent" ? priorAgentId : agentId;
+      // Preserve a user-set bucket (explicit MEKO_AGENT_ID, or a project-scoped
+      // id from the original session) across the resume, but re-derive a stale
+      // auto-derived coding identity that no longer matches the current client
+      // (e.g. an old Codex hook wrote claude_code:<repo> pre-MEKO-385) and
+      // upgrade the legacy literal "agent". Mirrors the same-session reuse
+      // branch above via reconcileCachedAgentId.
+      const reconciled = reconcileCachedAgentId(
+        prior.agent_id,
+        prior.agent_id_source || "",
+        agentId,
+      );
       const priorDatapackPin = datapackPinFromWatermark(prior);
+      // Rebucket to a new conversation when the reconciled identity differs
+      // from the prior conversation's owner (server pins owner at create).
+      const owned = await ensureConversationOwner({
+        convId: prior.conversation_id,
+        cachedOwner: prior.agent_id,
+        resolvedAgentId: reconciled.agentId,
+        resolvedSource: reconciled.source,
+        sessionId,
+        metadata: peekTranscriptMetadata(transcriptPath),
+        datapackId: priorDatapackPin && priorDatapackPin.datapack_id,
+      });
+      // HOLD: rebucket required but conversation_create failed. Do not write a
+      // watermark for this resumed session (no owner we can safely write under)
+      // — inject context under the prior owner and let a later hook retry.
+      if (owned.hold) {
+        const holdContext = buildSessionStartContext(
+          prior.conversation_id,
+          sessionId,
+          prior.agent_id,
+          null,
+          {
+            resumed: true,
+            datapackPin: priorDatapackPin,
+          },
+        );
+        process.stdout.write(hookOutput(withHealthNotice(holdContext)));
+        return;
+      }
+      const resumedAgentId = owned.agentId;
+      const resumedConvId = owned.convId;
+      // On a fresh rebucketed conversation, start the watermark at 0 so this
+      // session's turns replay into it. Otherwise keep currentLineCount so the
+      // replayed copied history isn't re-ingested.
       writeWatermark(
         wmPath,
-        prior.conversation_id,
-        currentLineCount,
+        resumedConvId,
+        owned.rebucketed ? 0 : currentLineCount,
         resumedAgentId,
         priorDatapackPin,
+        owned.source,
       );
-      process.stderr.write(`[meko-capture] Session ${sessionId}: resuming conversation ${prior.conversation_id} from ${prior.sessionId}, skipping ${currentLineCount} copied lines\n`);
-      const context = buildSessionStartContext(
-        prior.conversation_id,
+      process.stderr.write(`[meko-capture] Session ${sessionId}: resuming conversation ${resumedConvId} from ${prior.sessionId}, skipping ${owned.rebucketed ? 0 : currentLineCount} copied lines\n`);
+      let context = withHealthNotice(buildSessionStartContext(
+        resumedConvId,
         sessionId,
         resumedAgentId,
         null,
         {
           resumed: true,
           datapackPin: priorDatapackPin,
-          captureError: readCaptureError(resumedAgentId),
         },
-      );
+      ));
       writeSessionCache(sessionId, {
         status: "ready",
-        conversation_id: prior.conversation_id,
+        conversation_id: resumedConvId,
         agent_id: resumedAgentId,
         workspace_key: workspaceKey,
         additional_context: context,
@@ -1176,8 +1875,29 @@ async function handleSessionStart(hookInput) {
 
   // Create conversation via MCP. Attach session metadata (cwd / gitBranch /
   // startedAt) from the transcript header so hook traces match the migrator.
+  // Intent-first: durable outbox BEFORE any network call so create failures
+  // leave a recoverable needs_conversation state (Capture V2).
   const transcriptMetadata = peekTranscriptMetadata(transcriptPath);
   const datapackPin = readDatapackPin(agentId);
+  const agentIdSource = (process.env.MEKO_AGENT_ID || "").trim() ? "explicit" : "derived";
+  if (sessionId) {
+    const intent = captureState.writeSessionIntent(sessionId, {
+      client: resolveHookClient() || "",
+      agent_id: agentId,
+      agent_id_source: agentIdSource,
+      transcript_path: transcriptPath || null,
+      datapack_id: datapackPin ? datapackPin.datapack_id : null,
+      datapack_name: datapackPin ? datapackPin.datapack_name : null,
+    });
+    if (!intent.ok) {
+      process.stderr.write(
+        `[meko-capture] SessionStart: writeSessionIntent failed (${intent.failure_class}: ${intent.error}).\n`,
+      );
+      const context = withHealthNotice(buildSessionStartFallbackContext(agentId, { datapackPin }));
+      process.stdout.write(hookOutput(context));
+      return;
+    }
+  }
   let convId = null;
   try {
     await mcpInitialize();
@@ -1189,15 +1909,19 @@ async function handleSessionStart(hookInput) {
     );
   } catch (err) {
     process.stderr.write(`[meko-capture] SessionStart: MCP unavailable (${err.message}). Falling back to agent-driven setup.\n`);
-    const context = buildSessionStartFallbackContext(agentId, { datapackPin: readDatapackPin(agentId) });
+    let context = withHealthNotice(buildSessionStartFallbackContext(agentId, { datapackPin: readDatapackPin(agentId) }));
     if (sessionId) {
-      writeSessionCache(sessionId, {
-        status: "error",
-        agent_id: agentId,
-        workspace_key: workspaceKey,
-        error: err && err.message ? String(err.message).slice(0, 240) : "MCP unavailable",
-        additional_context: context,
-      });
+      try {
+        writeSessionCache(sessionId, {
+          status: "error",
+          agent_id: agentId,
+          workspace_key: workspaceKey,
+          error: err && err.message ? String(err.message).slice(0, 240) : "MCP unavailable",
+          additional_context: context,
+        });
+      } catch (cacheErr) {
+        process.stderr.write(`[meko-capture] SessionStart cache write skipped: ${cacheErr.message}\n`);
+      }
     }
     process.stdout.write(hookOutput(context));
     return;
@@ -1205,15 +1929,19 @@ async function handleSessionStart(hookInput) {
 
   if (!convId) {
     process.stderr.write("[meko-capture] SessionStart: conversation_create returned no ID.\n");
-    const context = buildSessionStartFallbackContext(agentId, { datapackPin: readDatapackPin(agentId) });
+    let context = withHealthNotice(buildSessionStartFallbackContext(agentId, { datapackPin: readDatapackPin(agentId) }));
     if (sessionId) {
-      writeSessionCache(sessionId, {
-        status: "error",
-        agent_id: agentId,
-        workspace_key: workspaceKey,
-        error: "conversation_create returned no ID",
-        additional_context: context,
-      });
+      try {
+        writeSessionCache(sessionId, {
+          status: "error",
+          agent_id: agentId,
+          workspace_key: workspaceKey,
+          error: "conversation_create returned no ID",
+          additional_context: context,
+        });
+      } catch (cacheErr) {
+        process.stderr.write(`[meko-capture] SessionStart cache write skipped: ${cacheErr.message}\n`);
+      }
     }
     process.stdout.write(hookOutput(context));
     return;
@@ -1232,49 +1960,665 @@ async function handleSessionStart(hookInput) {
 
   if (sessionId) {
     const wmPath = path.join(WATERMARK_DIR, `${sessionId}.watermark.json`);
-    writeWatermark(wmPath, convId, 0, agentId, datapackPin);
+    writeWatermark(wmPath, convId, 0, agentId, datapackPin, agentIdSource);
     process.stderr.write(
       `[meko-capture] SessionStart: created conversation ${convId}, agent_id=${agentId}, preloaded ${memories.length} memories, watermark at ${wmPath}\n`,
     );
   }
 
-  const context = buildSessionStartContext(convId, sessionId, agentId, memories, {
+  let context = withHealthNotice(buildSessionStartContext(convId, sessionId, agentId, memories, {
     datapackPin,
-    captureError: readCaptureError(agentId),
-  });
+  }));
   if (sessionId) {
-    writeSessionCache(sessionId, {
-      status: "ready",
-      conversation_id: convId,
-      agent_id: agentId,
-      workspace_key: workspaceKey,
-      additional_context: context,
-    });
+    try {
+      writeSessionCache(sessionId, {
+        status: "ready",
+        conversation_id: convId,
+        agent_id: agentId,
+        workspace_key: workspaceKey,
+        additional_context: context,
+      });
+    } catch (cacheErr) {
+      process.stderr.write(`[meko-capture] SessionStart cache write skipped: ${cacheErr.message}\n`);
+    }
   }
   process.stdout.write(hookOutput(context));
 }
 
+// --- Drain engine (Capture V2) ---
+
+/**
+ * Persist a post-accept cursor advance. Returns writeState result.
+ * Used after structurally valid addMessage acceptance only.
+ */
+function persistExchangeCheckpoint(sessionId, state, nextLine, extras) {
+  const adv = captureState.advanceCursor(state, nextLine, { clearSeed: true });
+  if (!adv.ok) return adv;
+  const next = {
+    ...adv.state,
+    delivery: extras.delivery != null ? extras.delivery : "pending",
+    queued_exchanges:
+      extras.queued_exchanges != null
+        ? extras.queued_exchanges
+        : Math.max(0, (state.queued_exchanges || 0) - 1),
+    attempt_count: 0,
+    next_retry_at: null,
+    failure_class: null,
+    last_error: null,
+    blocked_reason: null,
+    last_success_at: new Date().toISOString(),
+    in_flight: { seed: null, user_line: null, user_turn_id: null },
+  };
+  if (extras.lifecycle) next.lifecycle = extras.lifecycle;
+  if (extras.agent_id != null) next.agent_id = extras.agent_id;
+  if (extras.agent_id_source != null) next.agent_id_source = extras.agent_id_source;
+  if (extras.conversation_id != null) next.conversation_id = extras.conversation_id;
+  if (extras.datapack_id !== undefined) next.datapack_id = extras.datapack_id;
+  if (extras.datapack_name !== undefined) next.datapack_name = extras.datapack_name;
+  // Crash-injection hook for tests: server accepted, local checkpoint skipped.
+  if (process.env.MEKO_CAPTURE_TEST_CRASH_AFTER_ACCEPT === "1") {
+    return {
+      ok: false,
+      failure_class: "transient",
+      error: "MEKO_CAPTURE_TEST_CRASH_AFTER_ACCEPT",
+      state: next,
+      crashed_after_accept: true,
+    };
+  }
+  return captureState.writeState(sessionId, next);
+}
+
+/**
+ * Build a synthetic interrupted exchange for a trailing incomplete user turn.
+ */
+function buildInterruptedExchange(turn, sessionId) {
+  const input = extractText((turn.userMsg.message || {}).content) || "";
+  return {
+    user_uuid: turn.userMsg.uuid || "unknown",
+    user_line: turn.userLine,
+    next_line_number: null,
+    input,
+    output: INTERRUPTED_ASSISTANT_OUTPUT,
+    reasoning: "",
+    metadata: {
+      capture_status: "interrupted",
+      session_id: sessionId,
+      user_line: turn.userLine,
+    },
+    timestamp: turn.userMsg.timestamp || "",
+  };
+}
+
+/**
+ * Unified drain entry used by checkpoint, pre-compact, session-end, and CLI
+ * recover/drain. Acquires a drain lease, delivers sequentially with batch
+ * limits, and advances the cursor only after valid accepted message IDs.
+ *
+ * @param {object} options
+ * @param {string} options.session_id
+ * @param {string} [options.transcript_path]
+ * @param {"checkpoint"|"pre-compact"|"session-end"|"drain"|"recover"} [options.mode]
+ * @param {"active"|"closing"|"closed"} [options.lifecycle]
+ * @param {boolean} [options.confirmed_dead]
+ * @param {boolean} [options.recorded_owner_only]
+ * @param {number} [options.max_exchanges]
+ * @param {boolean} [options.force_retry] One-shot daemon-start override for
+ * persistent failures only.
+ * @returns {Promise<object>} DrainResult
+ */
+async function drainSession(options) {
+  const opts = options && typeof options === "object" ? options : {};
+  const sessionId = String(opts.session_id || "").trim();
+  if (!sessionId) {
+    return makeDrainResult({
+      status: "blocked",
+      failure_class: "persistent",
+      error: "session_id required",
+    });
+  }
+
+  const mode = opts.mode || "drain";
+  const configuredBatch = captureState.maxCaptureBatchSize();
+  const maxBatch =
+    opts.max_exchanges != null
+      ? Math.min(
+          configuredBatch,
+          Math.max(1, Number(opts.max_exchanges) || 1),
+        )
+      : configuredBatch;
+  const recordedOwnerOnly = Boolean(opts.recorded_owner_only);
+  const finalizeInterrupted =
+    Boolean(opts.confirmed_dead) ||
+    opts.lifecycle === "closing" ||
+    opts.lifecycle === "closed" ||
+    mode === "session-end";
+
+  const leaseAcq = captureState.acquireLease(sessionId);
+  if (!leaseAcq.ok) {
+    return makeDrainResult({
+      status: "retry_wait",
+      session_id: sessionId,
+      failure_class: leaseAcq.failure_class || "ownership",
+      error: leaseAcq.error || "lease held",
+      delivery: "retry_wait",
+    });
+  }
+  const leaseToken = leaseAcq.lease && leaseAcq.lease.token;
+
+  try {
+    const loaded = captureState.readState(sessionId);
+    if (!loaded.ok && !loaded.missing) {
+      return makeDrainResult({
+        status: "blocked",
+        session_id: sessionId,
+        failure_class: loaded.failure_class || "state_corrupt",
+        error: loaded.error || "corrupt state",
+        delivery: "blocked",
+      });
+    }
+
+    const stateExisted = Boolean(loaded.ok);
+    const nowIso = new Date().toISOString();
+    let state = loaded.ok
+      ? { ...loaded.state }
+      : {
+          schema_version: 2,
+          session_id: sessionId,
+          client: "",
+          agent_id: "",
+          agent_id_source: "",
+          transcript_path: null,
+          datapack_id: null,
+          datapack_name: null,
+          created_at: nowIso,
+          updated_at: nowIso,
+          last_activity_at: nowIso,
+          conversation_id: null,
+          conversation_epoch: 0,
+          last_line_number: 0,
+          in_flight: { seed: null, user_line: null, user_turn_id: null },
+          lifecycle: "active",
+          delivery: "needs_conversation",
+          queued_exchanges: 0,
+          attempt_count: 0,
+          next_retry_at: null,
+          failure_class: null,
+          last_error: null,
+          last_success_at: null,
+          blocked_reason: null,
+        };
+    const transcriptPath =
+      opts.transcript_path ||
+      state.transcript_path ||
+      null;
+
+    if (opts.lifecycle && opts.lifecycle !== state.lifecycle) {
+      state.lifecycle = opts.lifecycle;
+    } else if (mode === "session-end" && state.lifecycle === "active") {
+      state.lifecycle = "closing";
+    }
+    if (transcriptPath && !state.transcript_path) {
+      state.transcript_path = transcriptPath;
+    }
+
+    const retryAtMs = state.next_retry_at
+      ? Date.parse(state.next_retry_at)
+      : NaN;
+    if (
+      state.failure_class &&
+      Number.isFinite(retryAtMs) &&
+      retryAtMs > Date.now() &&
+      !(Boolean(opts.force_retry) && state.failure_class === "persistent")
+    ) {
+      return makeDrainResult({
+        status: "retry_wait",
+        session_id: sessionId,
+        queued_remaining: state.queued_exchanges || 0,
+        failure_class: state.failure_class,
+        error: state.last_error || "retry not due",
+        last_line_number: state.last_line_number || 0,
+        lifecycle: state.lifecycle,
+        delivery: state.delivery,
+        next_retry_at: state.next_retry_at,
+      });
+    }
+
+    if (!transcriptPath || !fs.existsSync(transcriptPath)) {
+      if (stateExisted) captureState.writeState(sessionId, state);
+      return makeDrainResult({
+        status: "noop",
+        session_id: sessionId,
+        last_line_number: state.last_line_number || 0,
+        lifecycle: state.lifecycle,
+        delivery: state.delivery,
+        error: "transcript missing",
+      });
+    }
+
+    let convId = state.conversation_id || "";
+    let lastLine = state.last_line_number || 0;
+    const currentLines = countLines(transcriptPath);
+    const datapackPin = datapackPinFromWatermark({
+      datapack_id: state.datapack_id,
+      datapack_name: state.datapack_name,
+    });
+
+    let effectiveAgentId = state.agent_id || "";
+    let effectiveSource = state.agent_id_source || "";
+
+    if (!recordedOwnerOnly) {
+      const reconciled = reconcileCachedAgentId(
+        state.agent_id,
+        state.agent_id_source || "",
+        resolveSessionAgentId(transcriptPath),
+      );
+      effectiveAgentId = reconciled.agentId;
+      effectiveSource = reconciled.source;
+    } else if (!(state.agent_id || "").trim()) {
+      return makeDrainResult({
+        status: "noop",
+        session_id: sessionId,
+        last_line_number: lastLine,
+        lifecycle: state.lifecycle,
+        delivery: state.delivery,
+        error: "recorded owner missing",
+      });
+    }
+
+    // Nothing-new early exit BEFORE network (preserve quiet skip for EOF hooks).
+    if (convId && currentLines <= lastLine && !finalizeInterrupted) {
+      if (
+        stateExisted &&
+        !recordedOwnerOnly &&
+        effectiveAgentId !== state.agent_id
+      ) {
+        state.agent_id = effectiveAgentId;
+        state.agent_id_source = effectiveSource;
+        captureState.writeState(sessionId, state);
+      }
+      return makeDrainResult({
+        status: "noop",
+        session_id: sessionId,
+        last_line_number: lastLine,
+        lifecycle: state.lifecycle,
+        delivery: state.delivery || "idle",
+      });
+    }
+
+    try {
+      await mcpInitialize();
+      if (!convId) {
+        convId = await createConversation(
+          sessionId,
+          effectiveAgentId,
+          peekTranscriptMetadata(transcriptPath),
+          datapackPin && datapackPin.datapack_id,
+        );
+        if (!convId) {
+          throw new Error("conversation_create returned no ID");
+        }
+        state.conversation_id = convId;
+        state.delivery = currentLines > lastLine ? "pending" : "idle";
+        state.failure_class = null;
+        state.last_error = null;
+        state.next_retry_at = null;
+        const created = captureState.writeState(sessionId, state);
+        if (!created.ok) {
+          throw new Error(
+            `failed to persist created conversation: ${created.error}`,
+          );
+        }
+      }
+    } catch (err) {
+      const failureClass = captureState.classifyFailure(err);
+      const pendingExchanges = extractExchanges(transcriptPath, lastLine).length;
+      // Only persist failure onto an existing outbox — never invent a watermark
+      // just because initialize failed (SessionStart owns intent creation).
+      if (stateExisted) {
+        state.delivery = failureClass === "transient" ? "retry_wait" : "blocked";
+        state.failure_class = failureClass;
+        state.last_error = err.message;
+        state.attempt_count = (state.attempt_count || 0) + 1;
+        state.next_retry_at = captureState.nextRetryAt({
+          failure_class: failureClass,
+          attempt_count: state.attempt_count,
+        });
+        state.queued_exchanges = pendingExchanges;
+        captureState.writeState(sessionId, state);
+      }
+      process.stderr.write(
+        `[meko-capture] Failed to initialize MCP session: ${err.message}\n`,
+      );
+      return makeDrainResult({
+        status: failureClass === "transient" ? "retry_wait" : "blocked",
+        session_id: sessionId,
+        queued_remaining: pendingExchanges,
+        failure_class: failureClass,
+        error: err.message,
+        last_line_number: lastLine,
+        lifecycle: state.lifecycle,
+        delivery: stateExisted ? state.delivery : "needs_conversation",
+      });
+    }
+
+    let extractFrom = lastLine;
+    if (!recordedOwnerOnly) {
+      const owned = await ensureConversationOwner({
+        convId,
+        cachedOwner: state.agent_id,
+        resolvedAgentId: effectiveAgentId,
+        resolvedSource: effectiveSource,
+        sessionId,
+        metadata: peekTranscriptMetadata(transcriptPath),
+        datapackId: datapackPin && datapackPin.datapack_id,
+        mcpReady: true,
+      });
+      if (owned.hold) {
+        return makeDrainResult({
+          status: "retry_wait",
+          session_id: sessionId,
+          failure_class: "ownership",
+          error: "rebucket hold",
+          last_line_number: lastLine,
+          lifecycle: state.lifecycle,
+          delivery: state.delivery,
+        });
+      }
+      effectiveAgentId = owned.agentId;
+      effectiveSource = owned.source;
+      if (owned.rebucketed) {
+        const rb = captureState.rebucket(state, owned.convId);
+        if (!rb.ok) {
+          return makeDrainResult({
+            status: "blocked",
+            session_id: sessionId,
+            failure_class: rb.failure_class || "persistent",
+            error: rb.error,
+            last_line_number: lastLine,
+            lifecycle: state.lifecycle,
+            delivery: "blocked",
+          });
+        }
+        state = rb.state;
+        state.agent_id = effectiveAgentId;
+        state.agent_id_source = effectiveSource;
+        captureState.writeState(sessionId, state);
+        convId = owned.convId;
+        extractFrom = 0;
+        lastLine = 0;
+      } else {
+        convId = owned.convId;
+        state.agent_id = effectiveAgentId;
+        state.agent_id_source = effectiveSource;
+      }
+    }
+
+    const entries = parseTranscriptEntries(transcriptPath, extractFrom);
+    const built = buildExchanges(entries);
+    let allExchanges = built.exchanges.slice();
+    let pendingFromLine = built.pendingFromLine;
+    const turns = built.turns || [];
+    const turnLines = realUserTurnLines(entries);
+    let safeLine = pendingFromLine !== null ? pendingFromLine : currentLines;
+
+    // Closing / dead: finalize trailing incomplete user turn exactly once.
+    let synthesizedInterrupted = false;
+    if (finalizeInterrupted && pendingFromLine !== null && turns.length > 0) {
+      const trailing = turns[turns.length - 1];
+      if (trailing && trailing.userLine === pendingFromLine) {
+        allExchanges.push(buildInterruptedExchange(trailing, sessionId));
+        synthesizedInterrupted = true;
+        pendingFromLine = null;
+        safeLine = currentLines;
+      }
+    }
+
+    if (allExchanges.length === 0) {
+      if (pendingFromLine !== null) {
+        process.stderr.write(
+          `[meko-capture] ${mode}: session ${sessionId} produced zero ` +
+            `exchanges but a trailing turn is still awaiting completion; holding ` +
+            `watermark at line ${safeLine} so it is captured whole on a later run.\n`,
+        );
+        state.delivery = "pending";
+        state.queued_exchanges = 1;
+      } else {
+        state.delivery =
+          finalizeInterrupted || state.lifecycle === "closing"
+            ? "complete"
+            : "idle";
+        if (finalizeInterrupted || state.lifecycle === "closing") {
+          state.lifecycle = "closed";
+        }
+        state.queued_exchanges = 0;
+      }
+      state.agent_id = effectiveAgentId;
+      state.agent_id_source = effectiveSource;
+      state.conversation_id = convId;
+      if (safeLine >= state.last_line_number) {
+        const adv = captureState.advanceCursor(state, safeLine, { clearSeed: true });
+        if (adv.ok) state = adv.state;
+      }
+      const written = captureState.writeState(sessionId, state);
+      const s = written.ok ? written.state : state;
+      return makeDrainResult({
+        status: "ok",
+        session_id: sessionId,
+        captured: 0,
+        queued_remaining: s.queued_exchanges || 0,
+        cursor_advanced: (s.last_line_number || 0) > lastLine,
+        last_line_number: s.last_line_number || 0,
+        lifecycle: s.lifecycle,
+        delivery: s.delivery,
+      });
+    }
+
+    const exchanges = allExchanges.slice(0, maxBatch);
+    let captured = 0;
+    let failed = 0;
+    let cursorAdvanced = false;
+    let watermarkLine = extractFrom;
+    state.delivery = "draining";
+    state.queued_exchanges = allExchanges.length;
+    captureState.writeState(sessionId, state);
+
+    for (const exchange of exchanges) {
+      const seed = `${convId}:${exchange.user_uuid}`;
+      state.in_flight = {
+        seed,
+        user_line:
+          typeof exchange.user_line === "number" ? exchange.user_line : null,
+        user_turn_id: exchange.user_uuid || null,
+      };
+      captureState.writeState(sessionId, state);
+
+      try {
+        await addMessage(
+          convId,
+          effectiveAgentId,
+          exchange,
+          datapackPin && datapackPin.datapack_id,
+        );
+        const boundary = boundaryAfterExchange(turnLines, exchange.user_line);
+        const nextLine =
+          boundary != null
+            ? boundary
+            : exchange.next_line_number != null
+              ? exchange.next_line_number
+              : safeLine;
+        const remainingAfter = allExchanges.length - captured - 1;
+        const ck = persistExchangeCheckpoint(sessionId, state, nextLine, {
+          delivery:
+            remainingAfter > 0 || allExchanges.length > maxBatch
+              ? "pending"
+              : "idle",
+          queued_exchanges: Math.max(0, allExchanges.length - captured - 1),
+          agent_id: effectiveAgentId,
+          agent_id_source: effectiveSource,
+          conversation_id: convId,
+          datapack_id: datapackPin ? datapackPin.datapack_id : null,
+          datapack_name: datapackPin ? datapackPin.datapack_name : null,
+        });
+        if (!ck.ok) {
+          failed++;
+          const failureClass = ck.failure_class || "transient";
+          state.delivery = "retry_wait";
+          state.failure_class = failureClass;
+          state.last_error = ck.error;
+          state.attempt_count = (state.attempt_count || 0) + 1;
+          state.next_retry_at = captureState.nextRetryAt({
+            failure_class: failureClass,
+            attempt_count: state.attempt_count,
+          });
+          state.in_flight = {
+            seed,
+            user_line:
+              typeof exchange.user_line === "number" ? exchange.user_line : null,
+            user_turn_id: exchange.user_uuid || null,
+          };
+          captureState.writeState(sessionId, state);
+          process.stderr.write(
+            `[meko-capture] Accepted but checkpoint failed (uuid=${exchange.user_uuid}): ${ck.error}\n`,
+          );
+          break;
+        }
+        state = ck.state;
+        watermarkLine = state.last_line_number;
+        captured++;
+        cursorAdvanced = true;
+      } catch (err) {
+        failed++;
+        const persistent = classifyPersistentCaptureFailure(err);
+        const failureClass = persistent
+          ? "persistent"
+          : captureState.classifyFailure(err);
+        state.delivery =
+          failureClass === "transient" ? "retry_wait" : "blocked";
+        state.failure_class = failureClass;
+        state.last_error = err.message;
+        state.attempt_count = (state.attempt_count || 0) + 1;
+        state.next_retry_at = captureState.nextRetryAt({
+          failure_class: failureClass,
+          attempt_count: state.attempt_count,
+        });
+        state.queued_exchanges = allExchanges.length - captured;
+        captureState.writeState(sessionId, state);
+        process.stderr.write(
+          `[meko-capture] Failed to add message (uuid=${exchange.user_uuid}): ${err.message}\n`,
+        );
+        break;
+      }
+    }
+
+    const held = allExchanges.length - captured;
+    if (failed === 0 && allExchanges.length <= maxBatch && pendingFromLine === null) {
+      watermarkLine = safeLine;
+      if (watermarkLine >= state.last_line_number) {
+        const adv = captureState.advanceCursor(state, watermarkLine, {
+          clearSeed: true,
+        });
+        if (adv.ok) state = adv.state;
+      }
+      if (finalizeInterrupted || state.lifecycle === "closing") {
+        state.lifecycle = "closed";
+        state.delivery = "complete";
+        state.queued_exchanges = 0;
+      } else {
+        state.delivery = "idle";
+        state.queued_exchanges = 0;
+      }
+      captureState.writeState(sessionId, state);
+      cursorAdvanced = captured > 0 || cursorAdvanced || synthesizedInterrupted;
+    } else if (failed === 0 && allExchanges.length > maxBatch) {
+      state.delivery = "pending";
+      state.queued_exchanges = held;
+      captureState.writeState(sessionId, state);
+      process.stderr.write(
+        `[meko-capture] captured batch of ${captured}/${allExchanges.length} exchange(s); ` +
+          `checkpointed through line ${watermarkLine}.\n`,
+      );
+    } else if (failed > 0) {
+      process.stderr.write(
+        `[meko-capture] capture stopped at first failure; ` +
+          `holding watermark at line ${state.last_line_number} for retry.\n`,
+      );
+    }
+
+    const finalState = captureState.readState(sessionId);
+    const s = finalState.ok ? finalState.state : state;
+    let status = "ok";
+    if (failed > 0) {
+      status =
+        s.failure_class === "transient" || s.delivery === "retry_wait"
+          ? "retry_wait"
+          : s.delivery === "blocked"
+            ? "blocked"
+            : "partial";
+    } else if (held > 0) {
+      status = "partial";
+    }
+
+    return makeDrainResult({
+      status,
+      session_id: sessionId,
+      captured,
+      queued_remaining: held,
+      failure_class: failed > 0 ? s.failure_class || null : null,
+      error: failed > 0 ? s.last_error || null : null,
+      cursor_advanced: cursorAdvanced,
+      last_line_number: s.last_line_number || watermarkLine,
+      lifecycle: s.lifecycle,
+      delivery: s.delivery,
+    });
+  } finally {
+    if (leaseToken) captureState.releaseLease(sessionId, leaseToken);
+  }
+}
+
 // --- Main ---
 
 async function main() {
   const hookType = process.argv[2];
-  if (!hookType || !["session-start", "before-submit-prompt", "pre-compact", "session-end", "checkpoint"].includes(hookType)) {
-    process.stderr.write("Usage: capture.js <session-start|before-submit-prompt|pre-compact|session-end|checkpoint>\n");
+  const known = [
+    "session-start",
+    "before-submit-prompt",
+    "pre-compact",
+    "session-end",
+    "checkpoint",
+    "drain",
+    "recover",
+  ];
+  if (!hookType || !known.includes(hookType)) {
+    process.stderr.write(
+      "Usage: capture.js <session-start|before-submit-prompt|pre-compact|session-end|checkpoint|drain|recover>\n",
+    );
     process.exit(1);
   }
 
-  // Read hook input from stdin
   let hookInput;
   try {
     const stdin = fs.readFileSync(0, "utf-8");
-    hookInput = JSON.parse(stdin);
+    hookInput = JSON.parse(stdin || "{}");
   } catch (err) {
-    process.stderr.write(`[meko-capture] Failed to parse hook input from stdin: ${err.message}\n`);
-    process.stdout.write(hookOutput(""));
+    process.stderr.write(
+      `[meko-capture] Failed to parse hook input from stdin: ${err.message}\n`,
+    );
+    if (hookType === "drain" || hookType === "recover") {
+      process.stdout.write(
+        JSON.stringify(
+          makeDrainResult({
+            status: "blocked",
+            failure_class: "persistent",
+            error: `invalid stdin JSON: ${err.message}`,
+          }),
+        ) + "\n",
+      );
+    } else {
+      process.stdout.write(hookOutput(""));
+    }
     return;
   }
 
-  // SessionStart: create conversation + watermark, output context
   if (hookType === "session-start") {
     await handleSessionStart(hookInput);
     return;
@@ -1285,143 +2629,78 @@ async function main() {
     return;
   }
 
-  // PreCompact / SessionEnd: capture transcript exchanges
   const transcriptPath =
     hookInput.transcript_path ||
-    (hookInput.hookSpecificInput || {}).transcript_path;
-
-  if (!transcriptPath || !fs.existsSync(transcriptPath)) {
-    process.stdout.write(hookOutput(""));
-    return;
-  }
+    (hookInput.hookSpecificInput || {}).transcript_path ||
+    null;
+  const sessionId =
+    (hookInput.session_id && String(hookInput.session_id)) ||
+    (transcriptPath ? path.basename(transcriptPath, ".jsonl") : "") ||
+    extractSessionId(hookInput, transcriptPath);
+
+  const drainOpts = {
+    session_id: sessionId,
+    transcript_path: transcriptPath,
+    mode: hookType === "recover" ? "drain" : hookType,
+    lifecycle: hookInput.lifecycle,
+    confirmed_dead: Boolean(hookInput.confirmed_dead),
+    recorded_owner_only: Boolean(hookInput.recorded_owner_only),
+    max_exchanges:
+      hookInput.max_exchanges != null
+        ? Number(hookInput.max_exchanges)
+        : undefined,
+    force_retry: Boolean(hookInput.force_retry),
+  };
 
-  const sessionId = path.basename(transcriptPath, ".jsonl");
-  const wmPath = path.join(WATERMARK_DIR, `${sessionId}.watermark.json`);
-  const watermark = readWatermark(wmPath);
-  let convId = watermark.conversation_id || "";
-  const lastLine = watermark.last_line_number || 0;
-  const currentLines = countLines(transcriptPath);
-
-  // Resolve agent_id for this hook invocation. Prefer the value the
-  // SessionStart hook persisted in the watermark; if it's missing or a
-  // legacy literal ("agent"), fall back to a fresh derivation from the
-  // transcript's cwd so writes land in the right bucket.
-  const cachedAgentId = (watermark.agent_id || "").trim();
-  const agentId = cachedAgentId && cachedAgentId !== "agent"
-    ? cachedAgentId
-    : resolveSessionAgentId(transcriptPath);
-  const datapackPin = datapackPinFromWatermark(watermark);
-
-  // Nothing new
-  if (currentLines <= lastLine) {
-    process.stdout.write(hookOutput(""));
-    return;
+  // recover alias: single-session drain under recorded owner + dead finalization
+  if (hookType === "recover") {
+    drainOpts.recorded_owner_only =
+      hookInput.recorded_owner_only !== undefined
+        ? Boolean(hookInput.recorded_owner_only)
+        : true;
+    drainOpts.confirmed_dead =
+      hookInput.confirmed_dead !== undefined
+        ? Boolean(hookInput.confirmed_dead)
+        : true;
   }
 
-  // Initialize MCP session
-  try {
-    await mcpInitialize();
-  } catch (err) {
-    const persistent = classifyPersistentCaptureFailure(err);
-    if (persistent) {
-      const pendingExchanges = extractExchanges(transcriptPath, lastLine).length;
-      writeCaptureError(agentId, {
-        code: persistent.code,
-        reason: persistent.reason,
-        held_exchanges: pendingExchanges || 1,
-        session_id: sessionId,
-        conversation_id: convId || null,
-      });
-      process.stderr.write(
-        `[meko-capture] Persistent capture rejection recorded for the next SessionStart: ${persistent.reason}.\n`,
-      );
-    }
-    process.stderr.write(`[meko-capture] Failed to initialize MCP session: ${err.message}\n`);
-    process.stdout.write(hookOutput(""));
+  if (hookType === "drain" || hookType === "recover") {
+    const result = await drainSession(drainOpts);
+    process.stdout.write(JSON.stringify(result) + "\n");
     return;
   }
 
-  // Only SessionStart creates conversations. All other modes require
-  // an existing watermark. Skip gracefully if missing.
-  if (!convId) {
-    process.stderr.write(
-      `[meko-capture] ${hookType}: No conversation in watermark for session ${sessionId}. ` +
-      `SessionStart hook may not have run yet.\n`
-    );
+  if (!transcriptPath || !fs.existsSync(transcriptPath)) {
     process.stdout.write(hookOutput(""));
     return;
   }
-
-  // Extract and send exchanges
-  const exchanges = extractExchanges(transcriptPath, lastLine);
-  let captured = 0;
-  let failed = 0;
-  const persistentFailures = [];
-
-  for (const exchange of exchanges) {
-    try {
-      await addMessage(
-        convId,
-        agentId,
-        exchange,
-        datapackPin && datapackPin.datapack_id,
-      );
-      captured++;
-    } catch (err) {
-      failed++;
-      const persistent = classifyPersistentCaptureFailure(err);
-      if (persistent) persistentFailures.push(persistent);
-      process.stderr.write(`[meko-capture] Failed to add message (uuid=${exchange.user_uuid}): ${err.message}\n`);
-    }
-  }
-
-  if (persistentFailures.length > 0) {
-    const persistent = persistentFailures[0];
-    writeCaptureError(agentId, {
-      code: persistent.code,
-      reason: persistent.reason,
-      // Every failed exchange remains held by the watermark, including any
-      // transient failures that happened in the same persistently rejected batch.
-      held_exchanges: failed,
-      session_id: sessionId,
-      conversation_id: convId,
-    });
-    process.stderr.write(
-      `[meko-capture] Persistent capture rejection recorded for the next SessionStart: ${persistent.reason}.\n`,
-    );
-  } else if (captured > 0) {
-    // A successful write proves the prior persistent rejection has cleared.
-    // Transient failures may still hold this batch's watermark independently.
-    clearCaptureError(agentId);
-  }
-
-  // Advance the watermark to currentLines ONLY when every exchange was
-  // captured. If any addMessage failed (typically a transient network error),
-  // keep the watermark at lastLine so the next checkpoint / PreCompact /
-  // SessionEnd hook re-extracts and retries this batch. Re-sending the
-  // exchanges that already succeeded is safe: capture dedups by seed
-  // (<conv_id>:<user_uuid>), so retries never create duplicates. Advancing on
-  // partial failure is what would permanently drop the failed exchanges.
-  // We still always persist the resolved agent_id (migrating any legacy literal
-  // value) so later hooks see the derived bucket directly.
-  const watermarkLine = failed === 0 ? currentLines : lastLine;
-  if (failed > 0) {
-    process.stderr.write(
-      `[meko-capture] ${failed}/${exchanges.length} exchange(s) failed; ` +
-      `holding watermark at line ${lastLine} for retry (dedup makes resends safe).\n`
-    );
+  if (hookType === "session-end") {
+    drainOpts.lifecycle = "closing";
   }
-  writeWatermark(wmPath, convId, watermarkLine, agentId, datapackPin);
 
-  // Output
+  const result = await drainSession(drainOpts);
   const context =
-    hookType === "pre-compact"
-      ? `Pre-compact: captured ${captured} exchanges to Meko conversation ${convId}`
+    hookType === "pre-compact" && result.captured > 0
+      ? `Pre-compact: captured ${result.captured} exchanges to Meko conversation`
       : "";
   process.stdout.write(hookOutput(context));
 }
 
-main().catch((err) => {
-  process.stderr.write(`[meko-capture] Fatal error: ${err.message}\n`);
-  process.stdout.write(hookOutput(""));
-});
+module.exports = {
+  deriveAgentId,
+  drainSession,
+  makeDrainResult,
+  boundaryAfterExchange,
+  realUserTurnLines,
+  INTERRUPTED_ASSISTANT_OUTPUT,
+  buildExchanges,
+  extractExchanges,
+  addMessage,
+};
+
+if (require.main === module) {
+  main().catch((err) => {
+    process.stderr.write(`[meko-capture] Fatal error: ${err.message}\n`);
+    process.stdout.write(hookOutput(""));
+  });
+}