@yugabytedb/meko-mcp 2.1.0 → 2.3.0

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

@@ -1,23 +1,46 @@
 #!/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)
  *   MEKO_AGENT_ID      Agent identifier override; if unset, derived from the
- *                      session's cwd as `claude_code:<repo-basename>` (or
- *                      `meko_agent` if cwd is unknown). See deriveAgentId().
+ *                      session's cwd by walking parents for `.git` and taking
+ *                      the repo root's basename, as `claude_code:<repo>` (or
+ *                      the bare client name if the session is outside a repo,
+ *                      so sibling subdirectories in unrelated repos can't
+ *                      silently collide). See deriveAgentId().
  *   MEKO_API_KEY        API key for Cloud Meko auth (optional, omit for local)
  *   MEKO_API_TIMEOUT   Request timeout in seconds (default: 10)
+ *   MEKO_ADD_MESSAGE_TIMEOUT  Timeout for conversation_add_message in
+ *                      seconds (default: 60). Storing a large turn can take
+ *                      the server more than 15s. PreCompact runs in the
+ *                      foreground and keeps MEKO_API_TIMEOUT instead.
  *   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 +48,7 @@ const os = require("os");
 const path = require("path");
 const http = require("http");
 const https = require("https");
+const captureState = require("./capture-state");
 
 // --- Config ---
 
@@ -35,16 +59,73 @@ const MEKO_MCP_URL = process.env.MEKO_MCP_URL || "http://localhost:8000/mcp";
 const COMMON_BUCKET_AGENT_ID = "meko_agent";
 const AGENT_ID_MAX_LEN = 64;
 
+/**
+ * The user's home directory, read fresh so a re-pointed `$HOME` (tests,
+ * sandboxes) is honored. Mirror of `homeBoundary` in
+ * installer/lib/migrate/id.mjs.
+ */
+function homeBoundary() {
+  const fromEnv = (process.env.HOME || "").trim();
+  if (fromEnv) return path.resolve(fromEnv);
+  try {
+    const h = os.homedir();
+    return h ? path.resolve(h) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Walk parents of `cwd` looking for a `.git` entry (directory for a normal
+ * checkout, file for a submodule / linked worktree). Returns the absolute
+ * repo-root path, or `null` if none is found. Mirror of `resolveRepoRoot`
+ * in installer/lib/migrate/id.mjs.
+ *
+ * The walk stops at `$HOME` (from below only, so a git-tracked home is still
+ * its own repo root): without that bound, dotfiles-under-git would make every
+ * non-repo directory under home derive `claude_code:<username>`.
+ */
+function resolveRepoRoot(cwd) {
+  if (!cwd || typeof cwd !== "string") return null;
+  let dir;
+  try {
+    dir = path.resolve(cwd);
+  } catch {
+    return null;
+  }
+  const start = dir;
+  const home = homeBoundary();
+  let prev = null;
+  while (dir && dir !== prev) {
+    // A directory below a git-tracked home must not inherit home's `.git`.
+    if (home && dir === home && dir !== start) return null;
+    try {
+      fs.statSync(path.join(dir, ".git"));
+      return dir;
+    } catch {
+      // keep walking
+    }
+    // Check home itself for `.git`, then stop. A non-git home must not
+    // inherit repository state from /Users, /home, or /.
+    if (home && dir === home) return null;
+    prev = dir;
+    dir = path.dirname(dir);
+  }
+  return null;
+}
+
 /**
  * Derive an `agent_id` for a Meko write. Mirror of `deriveAgentId` in
  * installer/lib/migrate/id.mjs — kept inline because capture.js is published
  * 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>`,
- *     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).
+ *   - Coding clients (claude_code, cursor, codex, kiro, opencode) →
+ *     `<client>:<repo-basename>`, where the basename comes from the
+ *     nearest ancestor of `cwd` that contains `.git`. Lowercased,
+ *     non-`[a-z0-9-]` runs collapse to `-`. Outside a repo → bare
+ *     client name (keeps sibling `docs`/`src`/`webapp` directories in
+ *     unrelated repos from collapsing into one agent_id — MEKO-590).
  *   - Loose clients (claude-desktop) → `claude_desktop`.
  *   - Anything else → `meko_agent` (common cross-project bucket).
  */
@@ -53,10 +134,20 @@ 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;
-  const rawBase = opts && opts.cwd ? path.basename(opts.cwd) : "";
-  if (!rawBase || rawBase === "." || rawBase === "/") return client;
-  const project = rawBase.toLowerCase()
+  if (
+    client !== "claude_code" &&
+    client !== "cursor" &&
+    client !== "codex" &&
+    client !== "kiro" &&
+    client !== "opencode"
+  ) {
+    return COMMON_BUCKET_AGENT_ID;
+  }
+  const repoRoot = opts && Object.prototype.hasOwnProperty.call(opts, "repoRoot")
+    ? opts.repoRoot
+    : resolveRepoRoot(opts && opts.cwd);
+  if (!repoRoot) return client;
+  const project = path.basename(repoRoot).toLowerCase()
     .replace(/[^a-z0-9-]+/g, "-")
     .replace(/^-+|-+$/g, "")
     .slice(0, AGENT_ID_MAX_LEN);
@@ -64,6 +155,45 @@ function deriveAgentId(opts) {
   return `${client}:${project}`;
 }
 
+/**
+ * Pre-MEKO-590 coding-agent derivation. Existing pin filenames and session
+ * state may still use this cwd-leaf id, so it remains a read-only alias while
+ * new sessions use the repo-root id from `deriveAgentId`.
+ */
+function deriveLegacyAgentId(opts) {
+  const envOverride = opts && typeof opts.envOverride === "string"
+    ? opts.envOverride.trim()
+    : "";
+  if (envOverride) return envOverride;
+  const client = opts && opts.client ? String(opts.client).trim() : "";
+  if (client === "claude-desktop" || client === "claude_desktop") {
+    return "claude_desktop";
+  }
+  if (!["claude_code", "cursor", "codex", "kiro"].includes(client)) {
+    return COMMON_BUCKET_AGENT_ID;
+  }
+  const rawBase = opts && opts.cwd ? path.basename(opts.cwd) : "";
+  const project = rawBase.toLowerCase()
+    .replace(/[^a-z0-9-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, AGENT_ID_MAX_LEN);
+  return project ? `${client}:${project}` : client;
+}
+
+/**
+ * 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" || client === "opencode") 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
@@ -76,9 +206,7 @@ function deriveAgentId(opts) {
  *   4. cwd from the hook input.
  *   5. process.cwd() — last resort if no transcript metadata yet.
  */
-function resolveSessionAgentId(transcriptPath, hookInput = null) {
-  const envOverride = process.env.MEKO_AGENT_ID;
-  if (envOverride && envOverride.trim()) return envOverride.trim();
+function pickSessionCwd(transcriptPath, hookInput) {
   const meta = transcriptPath ? peekTranscriptMetadata(transcriptPath) : null;
   const nested = hookInput && hookInput.hookSpecificInput && typeof hookInput.hookSpecificInput === "object"
     ? hookInput.hookSpecificInput
@@ -89,7 +217,7 @@ function resolveSessionAgentId(transcriptPath, hookInput = null) {
   const nestedRoots = Array.isArray(nested.workspace_roots) ? nested.workspace_roots : [];
   const workspaceRoot = [...roots, ...nestedRoots]
     .find((item) => typeof item === "string" && item.trim());
-  const cwd =
+  return (
     (meta && meta.cwd) ||
     hookInput?.workspace_path ||
     hookInput?.workspacePath ||
@@ -100,12 +228,200 @@ function resolveSessionAgentId(transcriptPath, hookInput = null) {
     workspaceRoot ||
     hookInput?.cwd ||
     nested.cwd ||
-    process.cwd();
-  const client = process.env.MEKO_HOOK_CLIENT === "cursor" ? "cursor" : "claude_code";
+    process.cwd()
+  );
+}
+
+function resolveSessionAgentId(transcriptPath, hookInput = null, precomputedCwd = null) {
+  const envOverride = process.env.MEKO_AGENT_ID;
+  if (envOverride && envOverride.trim()) return envOverride.trim();
+  // SessionStart picks the cwd once and passes it in, so the transcript is
+  // peeked once per hook invocation rather than once per consumer.
+  const cwd = precomputedCwd || pickSessionCwd(transcriptPath, hookInput);
+  const client = resolveHookClient();
   return deriveAgentId({ client, cwd, envOverride });
 }
+
+/**
+ * Emit a one-line derivation log to stderr so future MEKO-590–class
+ * collisions ("why did session X land under agent_id Y?") are diagnosable
+ * from capture logs. Called once at SessionStart, not on every drain, so
+ * test assertions on downstream hooks stay stable.
+ *
+ * Takes the already-picked `cwd` so the log reports the SAME cwd the
+ * derivation actually used (Cursor's `workspace_roots` included — the
+ * hook's raw cwd is `~/.cursor`, which would print misleadingly) without
+ * a second transcript peek.
+ *
+ * Reports `derivedAgentId`, NOT necessarily the id this session writes
+ * under: the watermark-reuse and resume branches run
+ * `reconcileCachedAgentId` afterwards and may preserve a cached bucket.
+ * `logEffectiveAgentId` closes that gap on those paths.
+ */
+function logAgentIdDerivation(cwd, derivedAgentId) {
+  const envOverride = (process.env.MEKO_AGENT_ID || "").trim();
+  if (envOverride) {
+    process.stderr.write(
+      `[meko-capture] deriveAgentId: source=env-override derivedAgentId=${derivedAgentId}\n`,
+    );
+    return;
+  }
+  const client = resolveHookClient();
+  const repoRoot = resolveRepoRoot(cwd);
+  process.stderr.write(
+    `[meko-capture] deriveAgentId: client=${client} cwd=${cwd || ""} ` +
+    `resolvedRepoRoot=${repoRoot || "<none>"} derivedAgentId=${derivedAgentId}\n`,
+  );
+}
+
+/**
+ * Log the agent_id this session actually writes under, when a cached bucket
+ * won over the fresh derivation (`/clear`, `/compact`, resume, or a HOLD).
+ * Silent when it matches, so the common path stays one line.
+ *
+ * Without this, "why did session X land under agent_id Y?" is unanswerable
+ * from the logs in exactly the cases where the answer is not the derivation.
+ */
+function logEffectiveAgentId(derivedAgentId, effectiveAgentId, reason) {
+  if (!effectiveAgentId || effectiveAgentId === derivedAgentId) return;
+  process.stderr.write(
+    `[meko-capture] deriveAgentId: effectiveAgentId=${effectiveAgentId} ` +
+    `(overrides derivedAgentId=${derivedAgentId}; reason=${reason})\n`,
+  );
+}
+
+// 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", "opencode"];
+
+/**
+ * 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 MEKO_ADD_MESSAGE_TIMEOUT = (() => {
+  // A value that doesn't parse would reach the lease TTL as NaN and throw
+  // inside renewLease, so fall back to the default instead.
+  const n = Number.parseInt(process.env.MEKO_ADD_MESSAGE_TIMEOUT || "", 10);
+  return (Number.isFinite(n) && n > 0 ? n : 60) * 1000;
+})();
 const WATERMARK_DIR =
   process.env.MEKO_WATERMARK_DIR ||
   path.join(os.homedir(), ".claude", "meko-capture");
@@ -113,6 +429,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
@@ -228,89 +548,507 @@ function extractToolResultContent(msg) {
   return parts.length > 0 ? "TOOL RESULT:\n" + parts.join("\n") : "";
 }
 
+// Turn inputs that are Claude Code bookkeeping, not something the user typed.
+// A turn whose rendered input matches is never captured.
+const SKIP_INPUT_PATTERN =
+  /^<(system-reminder|command-|local-command|available-deferred)/;
+
+/**
+ * Render a Claude Code skill or prompt command entry as the command the user
+ * typed. Claude Code writes `/commit fix typo` as
+ * `<command-message>commit</command-message><command-name>/commit</command-name>`
+ * plus an optional `<command-args>fix typo</command-args>`, and writes the
+ * skill or command body as the `isMeta` entry that follows. Built-in commands
+ * (`/clear`, `/model`, `/compact`, …) lead with `<command-name>` instead and
+ * have no body; they return "" here, so they never pull a following `isMeta`
+ * entry into their turn and always keep their raw, filtered input.
+ */
+function skillCommandInput(text) {
+  if (typeof text !== "string" || !/^<command-message>/.test(text)) {
+    return "";
+  }
+  const name = /<command-name>([\s\S]*?)<\/command-name>/.exec(text);
+  if (!name) return "";
+  const args = /<command-args>([\s\S]*?)<\/command-args>/.exec(text);
+  return [name[1].trim(), args ? args[1].trim() : ""].filter(Boolean).join(" ");
+}
+
+/**
+ * Is this a Claude Code background-task or subagent notification? Claude Code
+ * writes these as plain (non-isMeta) `type: "user"` entries whose content is a
+ * `<task-notification>…<summary>…</summary>…</task-notification>` block, and
+ * newer versions also tag them `origin: { kind: "task-notification" }`.
+ */
+function isTaskNotification(entry) {
+  if (entry.type !== "user" || isToolResultMessage(entry)) return false;
+  if (entry.origin && entry.origin.kind === "task-notification") return true;
+  return /^\s*<task-notification>/.test(
+    extractText((entry.message || {}).content),
+  );
+}
+
+/**
+ * Render a task notification that has to open its own turn as a one-line
+ * input. The full block (which can carry a subagent's whole report in
+ * `<result>`) goes to reasoning instead, so it is never read as user input.
+ */
+function taskNotificationInput(text) {
+  const summary = /<summary>([\s\S]*?)<\/summary>/.exec(text || "");
+  return `Task notification: ${summary ? summary[1].trim() : "background task update"}`;
+}
+
+/**
+ * Is this a subagent's hand-back report? Claude Code delivers it as an
+ * `isMeta` user entry tagged `origin: { kind: "peer", handback: true }`, with
+ * text starting "Another Claude session sent a message: <agent-message …>".
+ * Like a task notification, it is not user input and belongs to the open
+ * turn. Other peer messages (a request from an independent session, with no
+ * `handback`) are real input and still open their own turn.
+ */
+function isSubagentHandback(entry) {
+  if (entry.type !== "user" || isToolResultMessage(entry)) return false;
+  const origin = entry.origin;
+  return !!origin && origin.kind === "peer" && origin.handback === true;
+}
+
+/** Render a hand-back that has to open its own turn as a one-line input. */
+function handbackInput(entry) {
+  const origin = entry.origin || {};
+  const name = origin.name || origin.from || "";
+  return name ? `Agent message: ${name}` : "Agent message";
+}
+
+const SKILL_BODY_PATTERN = /^Base directory for this skill: *(\S+)/;
+
+/**
+ * Is this an `isMeta` entry Claude Code injected while loading a skill (the
+ * skill body, or a notice such as "Skill /commit was loaded earlier")? The
+ * model-invoked shape carries `sourceToolUseID`; a body from a typed `/skill`
+ * is recognized by its "Base directory for this skill:" first line.
+ */
+function isSkillContext(entry) {
+  if (entry.type !== "user" || entry.isMeta !== true) return false;
+  if (isToolResultMessage(entry)) return false;
+  if (entry.sourceToolUseID) return true;
+  return SKILL_BODY_PATTERN.test(extractText((entry.message || {}).content));
+}
+
+/** Context injected into a turn rather than typed by the user. */
+function isInjectedContext(entry) {
+  return isTaskNotification(entry) || isSubagentHandback(entry) || isSkillContext(entry);
+}
+
+/**
+ * Render skill context that has to open its own turn (see isTurnStart) as a
+ * one-line input naming the skill. The body goes to reasoning instead.
+ */
+function skillContextInput(text) {
+  const dir = SKILL_BODY_PATTERN.exec(text || "");
+  const name = dir ? path.basename(dir[1].replace(/\/+$/, "")) : "";
+  return name ? `Skill loaded: ${name}` : "Skill context loaded";
+}
+
+/**
+ * The rendered input for a turn. Skill-loading commands are unwrapped, and
+ * a turn opened by injected context gets a one-line summary so that context
+ * is never sent as user input.
+ */
+function turnInput(turn) {
+  const text = extractText((turn.userMsg.message || {}).content);
+  if (isTaskNotification(turn.userMsg)) return taskNotificationInput(text);
+  if (isSubagentHandback(turn.userMsg)) return handbackInput(turn.userMsg);
+  if (isSkillContext(turn.userMsg)) return skillContextInput(text);
+  // Only a skill command that actually got its body is shown as `/name args`.
+  return turn.injectedEntries.some((e) => e.isMeta === true && !isSubagentHandback(e))
+    ? skillCommandInput(text) || text
+    : text;
+}
+
+/** Will a turn with this rendered input be captured? */
+function isCapturableInput(input) {
+  return !!input && !SKIP_INPUT_PATTERN.test(input);
+}
+
+/**
+ * Does this user entry open a new turn? `prev` is the parsed entry just
+ * before it, or null. `insideInjectedRun` is true while consecutive injected
+ * `isMeta` entries continue after a skill-loading command or tool call.
+ * `openTurn` is the `{ userMsg, injectedEntries }` of the turn an earlier entry
+ * in this parse window opened, or null.
+ *
+ * Claude Code injects skill bodies ("Base directory for this skill: …") as
+ * `type: "user"` entries with `isMeta: true`. They belong to the turn that
+ * loaded the skill, not to a new one:
+ *   - the model called the Skill tool → the entry carries `sourceToolUseID`;
+ *   - the user typed `/skill` → the entry follows the `<command-message>`
+ *     entry (see skillCommandInput).
+ * Other `isMeta` user entries (scheduled and /loop prompts, image captions,
+ * requests from other sessions) still open a turn.
+ *
+ * Task notifications (see isTaskNotification) and subagent hand-backs (see
+ * isSubagentHandback) are not user input either, so they also stay in the
+ * open turn and the assistant's reaction joins it — unless that turn is never
+ * captured (a `/compact` or `<local-command-…>` turn), which would drop the
+ * reaction with it.
+ */
+function isTurnStart(entry, { prev = null, insideInjectedRun = false, openTurn = null } = {}) {
+  if (entry.type !== "user" || isToolResultMessage(entry)) return false;
+  // Nothing to fold into: the turn this entry belongs to was captured by an
+  // earlier drain (a notification arriving after the checkpoint), or a cursor
+  // persisted by an older capture version points straight at an injected
+  // entry. Anchor a turn here so the assistant reply that follows is kept.
+  if (!openTurn) return true;
+  if (isTaskNotification(entry) || isSubagentHandback(entry)) {
+    return !isCapturableInput(turnInput(openTurn));
+  }
+  if (entry.isMeta !== true) return true;
+  if (entry.sourceToolUseID) return false;
+  if (insideInjectedRun) return false;
+  const prevIsSkillCommand =
+    prev != null &&
+    prev.type === "user" &&
+    skillCommandInput(extractText((prev.message || {}).content)) !== "";
+  return !prevIsSkillCommand;
+}
+
+/**
+ * Stateful wrapper over isTurnStart for a pass over parsed entries, so
+ * buildExchanges and realUserTurnLines apply the same turn-start rule.
+ * Returns `startsTurn(entry) → boolean`; call it once per entry, in order.
+ */
+function turnStartTracker() {
+  let prev = null;
+  let insideInjectedRun = false;
+  // Mirrors the turn buildExchanges is assembling, so turnInput can render it.
+  let openTurn = null;
+  return (entry) => {
+    const startsTurn = isTurnStart(entry, { prev, insideInjectedRun, openTurn });
+    const isUserText = entry.type === "user" && !isToolResultMessage(entry);
+    // A hand-back is isMeta too, but it never continues a skill's run.
+    const isMetaUser =
+      isUserText && entry.isMeta === true && !isSubagentHandback(entry);
+    insideInjectedRun =
+      isMetaUser && (entry.sourceToolUseID != null || !startsTurn);
+    if (startsTurn) {
+      openTurn = { userMsg: entry, injectedEntries: [] };
+    } else if (openTurn && isUserText) {
+      openTurn.injectedEntries.push(entry);
+    }
+    prev = entry;
+    return startsTurn;
+  };
+}
+
 // --- 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;
+}
+
+/**
+ * Render a turn's assistant side: assistant text becomes `output`; thinking,
+ * tool calls, tool results and injected entries become `reasoning`.
+ */
+function renderTurnBody(ex) {
+  const outputParts = [];
+  const reasoningParts = [];
+
+  for (const aEntry of ex.assistantEntries) {
+    const content = (aEntry.message || {}).content;
+    if (!Array.isArray(content)) continue;
+
+    const text = extractText(content);
+    if (text) outputParts.push(text);
+
+    const thinking = extractThinking(content);
+    if (thinking) reasoningParts.push("THINKING:\n" + thinking);
+
+    const toolCalls = extractToolCalls(content);
+    if (toolCalls) reasoningParts.push(toolCalls);
+  }
+
+  for (const trEntry of ex.toolResultEntries) {
+    const resultText = extractToolResultContent(trEntry);
+    if (resultText) reasoningParts.push(resultText);
+  }
+
+  const injected = isInjectedContext(ex.userMsg)
+    ? [ex.userMsg, ...ex.injectedEntries]
+    : ex.injectedEntries;
+  for (const injEntry of injected) {
+    const text = extractText((injEntry.message || {}).content);
+    if (text) {
+      const label = isTaskNotification(injEntry)
+        ? "TASK NOTIFICATION:\n"
+        : isSubagentHandback(injEntry)
+          ? "AGENT MESSAGE:\n"
+          : "INJECTED CONTEXT:\n";
+      reasoningParts.push(label + truncate(text, MAX_TOOL_RESULT_LEN));
+    }
   }
 
-  // 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 = [];
+  return {
+    output: outputParts.join("\n\n"),
+    reasoning: reasoningParts.join("\n---\n"),
+  };
+}
+
+/**
+ * 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. Skill bodies
+ * and related injected `isMeta` entries stay in the turn that loaded them, and
+ * task notifications stay in the open turn (see isTurnStart). Other user
+ * messages start the next exchange. Assistant lines and tool-result user lines
+ * belong to the current exchange.
+ *
+ * `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 turns = [];
   let current = null;
 
-  for (const entry of entries) {
-    if (entry.type === "user" && !isToolResultMessage(entry)) {
-      if (current) exchanges.push(current);
+  const startsTurn = turnStartTracker();
+  for (const { entry, line } of items) {
+    if (startsTurn(entry)) {
+      if (current) turns.push(current);
       current = {
         userMsg: entry,
+        userLine: line,
         assistantEntries: [],
         toolResultEntries: [],
+        // Skill bodies, other isMeta text and task notifications Claude Code
+        // writes as user entries inside this turn (see isTurnStart).
+        injectedEntries: [],
+        // A turn with injected context is incomplete until an assistant entry
+        // arrives after its latest injection. Assistant entries before that
+        // injection do not make the turn safe for a checkpoint to consume.
+        assistantAfterInjection: false,
+        // 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 (current.injectedEntries.length > 0) {
+          current.assistantAfterInjection = true;
+        }
+        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);
+      } else if (entry.type === "user") {
+        current.injectedEntries.push(entry);
+        // Each injection needs its own reply: a second skill body or
+        // notification re-opens the hold until an assistant entry follows it.
+        current.assistantAfterInjection = false;
       }
     }
   }
-  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.injectedEntries.length > 0 && !last.assistantAfterInjection) ||
+      (last.codexStreaming && !last.codexComplete)
+    : false;
+  if (last && lastIncomplete) {
+    const lastInput = turnInput(last);
+    if (isCapturableInput(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) {
-    const input = extractText((ex.userMsg.message || {}).content);
-    if (!input || skipPattern.test(input)) continue;
-    if (ex.assistantEntries.length === 0) continue;
-
-    const outputParts = [];
-    const reasoningParts = [];
+  for (let t = 0; t < turns.length; t++) {
+    const ex = turns[t];
+    const isPendingTrailing =
+      pendingFromLine !== null && t === turns.length - 1;
+    if (isPendingTrailing) continue;
 
-    for (const aEntry of ex.assistantEntries) {
-      const content = (aEntry.message || {}).content;
-      if (!Array.isArray(content)) continue;
-
-      const text = extractText(content);
-      if (text) outputParts.push(text);
-
-      const thinking = extractThinking(content);
-      if (thinking) reasoningParts.push("THINKING:\n" + thinking);
-
-      const toolCalls = extractToolCalls(content);
-      if (toolCalls) reasoningParts.push(toolCalls);
-    }
+    const input = turnInput(ex);
+    if (!isCapturableInput(input)) continue;
+    if (ex.assistantEntries.length === 0) continue;
 
-    for (const trEntry of ex.toolResultEntries) {
-      const resultText = extractToolResultContent(trEntry);
-      if (resultText) reasoningParts.push(resultText);
-    }
+    const { output, reasoning } = renderTurnBody(ex);
 
     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"),
+      output,
+      reasoning,
       timestamp:
         ex.assistantEntries[ex.assistantEntries.length - 1].timestamp ||
         ex.userMsg.timestamp ||
@@ -318,41 +1056,203 @@ 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,
+        consecutive_exchange_drops: 0,
+      };
+
   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 = [];
+  const startsTurn = turnStartTracker();
+  for (const { entry, line } of entries) {
+    if (startsTurn(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,
+    dropped: partial.dropped || 0,
+  };
 }
 
 /**
@@ -367,72 +1267,44 @@ 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.
  *
  * The pin is a sidecar file at `<WATERMARK_DIR>/pin-<slug(agent_id)>.json`
  * with shape `{ datapack_id, datapack_name, selected_at }`. Project-scoped:
  * keyed by the same `agent_id` the hook derives for memory writes
- * (`claude_code:<repo-basename>`), so a pin set in one Claude Code window
- * for a repo applies to every other window in that repo, and survives
- * `/clear`, `/compact`, and Claude Code restart.
+ * (`claude_code:<repo-basename>`, where the basename is the nearest
+ * ancestor of the session cwd containing `.git`), so a pin set in one
+ * Claude Code window for a repo applies to every other window in that
+ * repo, and survives `/clear`, `/compact`, and Claude Code restart.
  *
- * Hooks are read-only — only the skill writes this file. Returns null if
- * the file is absent, malformed, or missing required fields, so SessionStart
- * can proceed unchanged when no pin is set.
+ * Hooks are read-only — only the skill writes this file. The legacy id is
+ * checked only when the repo-root id has no valid pin, preserving pins written
+ * before MEKO-590 without preventing a newly written repo-root pin from
+ * taking precedence.
  */
-function readDatapackPin(agentId) {
-  const slug = datapackPinSlug(agentId);
-  if (!slug) return null;
-  const pinPath = path.join(WATERMARK_DIR, `pin-${slug}.json`);
-  try {
-    const obj = JSON.parse(fs.readFileSync(pinPath, "utf-8"));
-    const id = typeof obj.datapack_id === "string" ? obj.datapack_id.trim() : "";
-    const name = typeof obj.datapack_name === "string" ? obj.datapack_name.trim() : "";
-    if (!id || !name) return null;
-    return { datapack_id: id, datapack_name: name, selected_at: obj.selected_at || "" };
-  } catch {
-    return null;
+function readDatapackPin(agentId, legacyAgentId = null) {
+  const candidates = [...new Set([agentId, legacyAgentId].filter(Boolean))];
+  for (const candidate of candidates) {
+    const slug = datapackPinSlug(candidate);
+    if (!slug) continue;
+    const pinPath = path.join(WATERMARK_DIR, `pin-${slug}.json`);
+    try {
+      const obj = JSON.parse(fs.readFileSync(pinPath, "utf-8"));
+      const id = typeof obj.datapack_id === "string" ? obj.datapack_id.trim() : "";
+      const name = typeof obj.datapack_name === "string" ? obj.datapack_name.trim() : "";
+      if (!id || !name) continue;
+      if (candidate !== agentId) {
+        process.stderr.write(
+          `[meko-capture] datapack pin: using legacy agent_id alias ${candidate}\n`,
+        );
+      }
+      return { datapack_id: id, datapack_name: name, selected_at: obj.selected_at || "" };
+    } catch {
+      // Try the compatibility alias, if any.
+    }
   }
+  return null;
 }
 
 function datapackPinFromWatermark(watermark) {
@@ -471,9 +1343,14 @@ The user pinned datapack **${pin.datapack_name}** (\`${pin.datapack_id}\`) for t
  * Low-level HTTP POST to the MCP endpoint.
  * Returns { body: <parsed JSON>, headers: <response headers> }.
  */
-function mcpPost(jsonBody) {
+function mcpPost(jsonBody, options) {
   const body = JSON.stringify(jsonBody);
+  const timeoutMs =
+    options && Number(options.timeoutMs) > 0
+      ? Number(options.timeoutMs)
+      : MEKO_API_TIMEOUT;
   return new Promise((resolve, reject) => {
+    let deadline = null;
     const url = new URL(MEKO_MCP_URL);
     const transport = url.protocol === "https:" ? https : http;
     const headers = {
@@ -502,12 +1379,13 @@ function mcpPost(jsonBody) {
         path: url.pathname + url.search,
         method: "POST",
         headers,
-        timeout: MEKO_API_TIMEOUT,
+        timeout: timeoutMs,
       },
       (res) => {
         let data = "";
         res.on("data", (chunk) => (data += chunk));
         res.on("end", () => {
+          clearTimeout(deadline);
           inflightRequests.delete(req);
           if (res.statusCode >= 400) {
             const snippet = data.trim().replace(/\s+/g, " ").slice(0, 200);
@@ -539,15 +1417,25 @@ function mcpPost(jsonBody) {
     );
 
     inflightRequests.add(req);
-    req.on("error", (err) => {
-      inflightRequests.delete(req);
-      reject(err);
-    });
-    req.on("timeout", () => {
+    const timedOut = () => {
+      clearTimeout(deadline);
       inflightRequests.delete(req);
       req.destroy();
       reject(new Error("MCP request timed out"));
+    };
+    // The socket timeout only measures idle time, and SSE pings reset it, so
+    // also cap the whole request. unref() and the close listener keep an
+    // aborted request (SessionStart's preload budget) from holding the
+    // process open until the deadline.
+    deadline = setTimeout(timedOut, timeoutMs);
+    deadline.unref();
+    req.on("close", () => clearTimeout(deadline));
+    req.on("error", (err) => {
+      clearTimeout(deadline);
+      inflightRequests.delete(req);
+      reject(err);
     });
+    req.on("timeout", timedOut);
     req.write(body);
     req.end();
   });
@@ -557,7 +1445,10 @@ function parseMcpResponseBody(data) {
   const trimmed = data.trim();
   if (!trimmed) return null;
 
-  if (!trimmed.startsWith("event:") && !trimmed.startsWith("data:")) {
+  // An SSE stream may open with a comment line such as the server's
+  // keepalive `: ping - <timestamp>`, sent every 15s while a slow tool call
+  // is still running.
+  if (!/^(event|data|id|retry)?:/.test(trimmed)) {
     return JSON.parse(trimmed);
   }
 
@@ -584,24 +1475,78 @@ function parseMcpResponseBody(data) {
   return JSON.parse(payload);
 }
 
-function classifyPersistentCaptureFailure(err) {
-  const message = err && err.message ? String(err.message) : String(err || "");
-  const normalized = message.toLowerCase();
-  const statusCode = Number(err && err.statusCode);
-  const statusMatch = normalized.match(/\bmcp http (402|403)\b/);
-  let persistentStatus = null;
-  if (statusCode === 402 || statusCode === 403) {
-    persistentStatus = statusCode;
-  } else if (statusMatch) {
-    persistentStatus = Number(statusMatch[1]);
-  }
+/**
+ * Collapse a response body to a single-line snippet for error records.
+ * Display/persistence stays short; pattern matching uses the fuller body.
+ */
+function errorBodySnippet(err) {
+  const body = err && err.responseBody ? String(err.responseBody) : "";
+  return body.trim().replace(/\s+/g, " ").slice(0, 200);
+}
 
-  if (persistentStatus) {
-    return {
-      code: `http_${persistentStatus}`,
-      reason: `Meko rejected capture with HTTP ${persistentStatus}`,
-    };
+/**
+ * Full collapsed response body for classifier pattern matching.
+ * mcpPost keeps up to 1000 chars on err.responseBody; the message snippet
+ * is only 200, so reasons past that window are only visible here.
+ */
+function errorBodyForMatch(err) {
+  const body = err && err.responseBody ? String(err.responseBody) : "";
+  return body.trim().replace(/\s+/g, " ");
+}
+
+function isHtmlErrorDetail(detail) {
+  return /^\s*<|<html|<!doctype/i.test(String(detail || ""));
+}
+
+function persistentFailureText(persistent, fallback) {
+  if (!persistent || !persistent.reason) return fallback;
+  const detail = persistent.detail ? String(persistent.detail) : "";
+  if (
+    !detail ||
+    isHtmlErrorDetail(detail) ||
+    String(persistent.reason).includes(detail)
+  ) {
+    return persistent.reason;
   }
+  return `${persistent.reason}: ${detail}`;
+}
+
+/**
+ * Classify a capture failure that will not clear on retry.
+ *
+ * Returns null for transient failures. Otherwise:
+ *   { code, reason, scope, detail }
+ *
+ * `scope` says WHAT is rejected, which is what the caller needs to decide
+ * whether retrying can ever succeed:
+ *   - "account"  the account/plan is refusing all writes (quota, entitlement,
+ *                402). Every exchange would fail identically, so the caller
+ *                holds the queue: the block clears when billing does, and
+ *                dropping would lose the whole session.
+ *   - "exchange" the response looks like an edge proxy rejecting THIS
+ *                request's body (HTTP 403 with an HTML body — see #13). The
+ *                caller may skip one such exchange so later turns still
+ *                drain; a second consecutive exchange-scoped failure without
+ *                an intervening success is treated as request-wide and held,
+ *                because HTML 403 alone does not prove payload-specificity
+ *                (missing UA, IP/ASN, rate-limit pages share the shape).
+ *
+ * Body patterns are tested BEFORE the status code. An account-level rejection
+ * that arrives as 402/403 (the common case) would otherwise collapse into an
+ * opaque `http_403` and send the user off regenerating a token that was never
+ * at fault. `detail` is a short body snippet; `reason` is what callers persist
+ * into `last_error` / notices so the real cause survives.
+ * Pass `{ exchange: true }` only from the addMessage path. Initialize and
+ * conversation_create HTML 403s are request-wide, so they stay account-scoped.
+ */
+function classifyPersistentCaptureFailure(err, opts) {
+  const options = opts && typeof opts === "object" ? opts : {};
+  const forExchange = options.exchange === true;
+  const message = err && err.message ? String(err.message) : String(err || "");
+  const detail = errorBodySnippet(err);
+  // Search the fuller responseBody (up to mcpPost's 1000-char keep) so a
+  // reason that fell outside the 200-char message snippet is still matched.
+  const normalized = `${message} ${errorBodyForMatch(err)}`.toLowerCase();
 
   const persistentPatterns = [
     ["free_tier_limit_reached", /free[_\s-]?tier.*limit|free_tier_limit_reached/],
@@ -611,6 +1556,13 @@ function classifyPersistentCaptureFailure(err) {
     ["payment_required", /payment[_\s-]?required/],
     ["subscription_required", /subscription[_\s-]?(required|inactive|expired)/],
     ["entitlement_denied", /entitlement.*(denied|required|missing)|(?:denied|required|missing).*entitlement/],
+    // MEKO-656/MEKO-691: _resolve_datapack_id now returns this code (instead
+    // of raising) when the caller has no ownership/share grant on the
+    // datapack_id it supplied. Account-scoped like entitlement_denied above —
+    // every write against that same datapack_id would fail identically until
+    // access is (re-)granted out of band, so the caller should hold rather
+    // than retry forever or silently drop the turn.
+    ["datapack_access_denied", /datapack_access_denied/],
   ];
   for (const [code, pattern] of persistentPatterns) {
     if (pattern.test(normalized)) {
@@ -622,13 +1574,203 @@ function classifyPersistentCaptureFailure(err) {
         payment_required: "capture requires payment",
         subscription_required: "capture requires an active subscription",
         entitlement_denied: "the account is not entitled to capture conversations",
+        datapack_access_denied: "the account does not have access to the target datapack",
       };
-      return { code, reason: reasons[code] };
+      return { code, reason: reasons[code], scope: "account", detail };
     }
   }
+
+  const statusCode = Number(err && err.statusCode);
+  const statusMatch = normalized.match(/\bmcp http (402|403)\b/);
+  let persistentStatus = null;
+  if (statusCode === 402 || statusCode === 403) {
+    persistentStatus = statusCode;
+  } else if (statusMatch) {
+    persistentStatus = Number(statusMatch[1]);
+  }
+
+  if (persistentStatus === 402) {
+    return {
+      code: "http_402",
+      reason: "Meko rejected capture with HTTP 402 (payment required)",
+      scope: "account",
+      detail,
+    };
+  }
+
+  if (persistentStatus === 403) {
+    // A 403 whose body is an HTML error page never came from the MCP service —
+    // the service answers with JSON. Auth failures arrive as 401 with a JSON
+    // body, so this is not a credential problem. A JSON 403 with no recognized
+    // pattern stays account-scoped: it may apply to every write.
+    //
+    // HTML alone is only a candidate for exchange-scope. The drain loop still
+    // requires an intervening success before a second consecutive drop, because
+    // request-wide edge blocks (rate limit, IP, missing UA historically) share
+    // this shape and would otherwise discard the whole session.
+    const fromEdge = isHtmlErrorDetail(detail);
+    return {
+      code: fromEdge ? "content_rejected_403" : "http_403",
+      // Keep exchange reasons short and free of HTML so SessionStart notices
+      // and drop_reasons do not inject error-page markup into model context.
+      reason: fromEdge
+        ? forExchange
+          ? "edge filtering rejected the request body (HTTP 403); this exchange's content cannot be stored as-is"
+          : "edge filtering rejected the request (HTTP 403)"
+        : `Meko rejected capture with HTTP 403${detail ? `: ${detail}` : ""}`,
+      scope: fromEdge && forExchange ? "exchange" : "account",
+      detail,
+    };
+  }
+
   return null;
 }
 
+/**
+ * Grace period before a closed session whose transcript has vanished is
+ * finalized. Default 1 day; MEKO_TRANSCRIPT_MISSING_GRACE overrides (seconds).
+ */
+function transcriptMissingGraceSeconds() {
+  const raw = process.env.MEKO_TRANSCRIPT_MISSING_GRACE;
+  const n = raw == null || raw === "" ? NaN : Number.parseInt(String(raw), 10);
+  return Number.isFinite(n) && n >= 0 ? n : 86400;
+}
+
+function coerceQueued(state) {
+  const n = Number(state && state.queued_exchanges);
+  return Number.isFinite(n) && n > 0 ? n : 0;
+}
+
+/** Consecutive not_found drains required before opening a replacement. */
+const MISSING_CONVERSATION_RECOVERY_POLLS = 2;
+
+function missingConversationStreak(state) {
+  const n = Number(state && state.missing_conversation_streak);
+  return Number.isInteger(n) && n > 0 ? n : 0;
+}
+
+/**
+ * Clear failure fields after a drain delivers all outstanding work.
+ *
+ * These fields describe the last attempt. Leaving them set after the queue
+ * drains makes sessionHealthBucket() report a resolved failure as degraded.
+ */
+function clearResolvedFailure(state) {
+  state.failure_class = null;
+  state.last_error = null;
+  state.next_retry_at = null;
+  state.attempt_count = 0;
+  state.blocked_reason = null;
+  state.recovered_from_conversation_id = null;
+  state.missing_conversation_streak = null;
+  return state;
+}
+
+/**
+ * Detect a conversation the server no longer has.
+ *
+ * `conversation_add_message` answers `not_found` when its conversation id is
+ * gone: deleted server-side, expired, or created against a different Langfuse
+ * project than the one the current datapack resolves to. classifyFailure() has
+ * no pattern for it, so it falls through to the "transient" default and the
+ * outbox retries the same dead id forever: three sessions reached 609, 441 and
+ * 440 attempts holding 105 turns that could never land.
+ *
+ * Callers treat a match as a signal to open a fresh conversation and move the
+ * undelivered tail into it (see recoverMissingConversation).
+ *
+ * The match keys on the server's detail, `Conversation <id> not found`
+ * (src/tools.py). The tool name in the error prefix also contains
+ * "conversation", so matching on the word alone would catch every not_found.
+ * The server sends the same detail when a Langfuse lookup fails transiently or
+ * the trace is too large to read (MEKO-452, MEKO-714), so a match is not proof
+ * the conversation is gone. Recovery waits until the same detail persists
+ * across MISSING_CONVERSATION_RECOVERY_POLLS drains, preserves the cursor, and
+ * never copies turns that the old conversation already accepted.
+ */
+function isMissingConversationError(err) {
+  const message = err && err.message ? String(err.message) : String(err || "");
+  const normalized = message.toLowerCase();
+  if (!/not[_\s-]?found/.test(normalized)) return false;
+  return /conversation\s+\S+\s+not\s+found/.test(normalized);
+}
+
+/**
+ * Recover from a conversation the server no longer has by opening a new one and
+ * moving the undelivered tail to it.
+ *
+ * The server can also return the same not_found detail for a transient Langfuse
+ * lookup failure. drainSession() calls this only after that detail has persisted
+ * across two drains, and this function keeps last_line_number so turns already
+ * accepted by the old conversation are not copied. conversation_add_message
+ * checks ownership before storing a turn, so the failed exchange and the rest
+ * of the undelivered tail remain safe to move.
+ *
+ * The new conversation is created without `session_id`. The server derives the
+ * id from `session_id`, so passing it again would return the conversation that
+ * just failed, and recovery would keep retrying the dead id.
+ *
+ * On create failure the caller keeps its normal retry path, so a network blip
+ * here costs a retry rather than the queue.
+ *
+ * @returns {Promise<{ok: boolean, state?: object, convId?: string, error?: string}>}
+ */
+async function recoverMissingConversation({
+  state,
+  sessionId,
+  agentId,
+  transcriptPath,
+  datapackId = null,
+}) {
+  let newConvId = null;
+  try {
+    newConvId = await createConversation(
+      sessionId || "unknown",
+      agentId,
+      peekTranscriptMetadata(transcriptPath),
+      datapackId,
+      { freshId: true },
+    );
+  } catch (err) {
+    return { ok: false, error: `conversation_create failed: ${err.message}` };
+  }
+  if (!newConvId) {
+    return { ok: false, error: "conversation_create returned no ID" };
+  }
+  // A create that returns the failed id did not provide a recovery target.
+  const sameId = (a, b) =>
+    String(a || "").replace(/-/g, "").toLowerCase() ===
+    String(b || "").replace(/-/g, "").toLowerCase();
+  if (sameId(newConvId, state.conversation_id)) {
+    return {
+      ok: false,
+      error: `conversation_create returned the missing conversation ${newConvId}`,
+    };
+  }
+  const next = {
+    ...state,
+    conversation_id: newConvId,
+    conversation_epoch: Number(state.conversation_epoch || 0) + 1,
+    in_flight: { seed: null, user_line: null, user_turn_id: null },
+    delivery: "pending",
+    failure_class: null,
+    last_error: null,
+    blocked_reason: null,
+    next_retry_at: null,
+    attempt_count: 0,
+    missing_conversation_streak: null,
+  };
+  // Suppress another replacement until this conversation accepts a turn. A
+  // fresh trace may not be visible yet when the next request reaches a
+  // different server replica.
+  next.recovered_from_conversation_id = state.conversation_id || null;
+  const written = captureState.writeState(sessionId, next);
+  if (!written.ok) {
+    return { ok: false, error: `failed to persist recovered conversation: ${written.error}` };
+  }
+  return { ok: true, state: written.state || next, convId: newConvId };
+}
+
 /**
  * Abort all pending MCP requests. Used by the preload timeout path so the
  * SessionStart hook can return promptly instead of waiting for a slow server
@@ -678,14 +1820,17 @@ async function mcpInitialize() {
   });
 }
 
-async function mcpCall(toolName, args) {
+async function mcpCall(toolName, args, options) {
   mcpRequestId++;
-  const result = await mcpPost({
-    jsonrpc: "2.0",
-    method: "tools/call",
-    params: { name: toolName, arguments: args },
-    id: mcpRequestId,
-  });
+  const result = await mcpPost(
+    {
+      jsonrpc: "2.0",
+      method: "tools/call",
+      params: { name: toolName, arguments: args },
+      id: mcpRequestId,
+    },
+    options,
+  );
   return result.body;
 }
 
@@ -747,21 +1892,29 @@ function peekTranscriptMetadata(transcriptPath) {
  * best-effort enrichment, not a correctness requirement.
  */
 async function fetchRecentMemories(agentId, datapackId = null, { limit = 10, budget = 2000 } = {}) {
+  // memory_get_all takes no `limit`, and FastMCP rejects an unknown argument
+  // with an isError result, so `limit` caps the page client-side instead.
   const payload = {
     agent_id: agentId,
     conversation_id: "00000000-0000-0000-0000-000000000000",
-    limit,
   };
   if (datapackId) payload.datapack_id = datapackId;
   const response = await mcpCall("memory_get_all", payload);
+  if (response && response.result && response.result.isError) {
+    const detail = ((response.result.content || [])[0] || {}).text || "";
+    process.stderr.write(`[meko-capture] memory preload failed: ${truncate(detail.replace(/\s+/g, " "), 300)}\n`);
+    return [];
+  }
   const result = extractToolResult(response);
   if (!result) return [];
 
   const entries = Array.isArray(result) ? result : result.memories || result.results || [];
   const summaries = [];
   let used = 0;
-  for (const entry of entries) {
-    const text = entry.memory || entry.text || entry.content || "";
+  for (const entry of entries.slice(0, limit)) {
+    // The meko API returns the text as `data`; `memory` is the mem0 shape
+    // servers returned before MEKO-216.
+    const text = entry.data || entry.memory || entry.text || entry.content || "";
     if (!text) continue;
     const line = `- ${String(text).replace(/\s+/g, " ").trim()}`;
     if (used + line.length + 1 > budget) break;
@@ -771,12 +1924,31 @@ async function fetchRecentMemories(agentId, datapackId = null, { limit = 10, bud
   return summaries;
 }
 
-async function createConversation(sessionId, agentId, metadata = null, datapackId = null) {
+/**
+ * The server derives the conversation id from `session_id`, so the same session
+ * always maps to the same conversation. Pass `freshId: true` to omit
+ * `session_id` and have the server mint a new id instead. Recovery needs this:
+ * re-creating with the session id returns the conversation that just failed.
+ */
+async function createConversation(
+  sessionId,
+  agentId,
+  metadata = null,
+  datapackId = null,
+  { freshId = false } = {},
+) {
+  const clientLabel = {
+    claude_code: "Claude Code",
+    cursor: "Cursor",
+    codex: "Codex",
+    kiro: "Kiro",
+    opencode: "OpenCode",
+  }[resolveHookClient()] || "Coding agent";
   const payload = {
     agent_id: agentId,
-    title: "Claude Code session (auto-captured)",
-    session_id: sessionId,
+    title: `${clientLabel} session (auto-captured)`,
   };
+  if (!freshId) payload.session_id = sessionId;
   if (metadata) {
     payload.metadata = JSON.stringify({
       source: "hook",
@@ -788,10 +1960,122 @@ async function createConversation(sessionId, agentId, metadata = null, datapackI
   if (datapackId) payload.datapack_id = datapackId;
   const response = await mcpCall("conversation_create", payload);
   const result = extractToolResult(response);
+  // MEKO-592: the server now returns a structured error when no datapack_id
+  // resolves (missing pin, no server-side default). Before this guard the
+  // server returned a success payload with a fabricated conversation id and
+  // every subsequent add_message came back not_found — capture was silently
+  // dead. Propagate the error like conversation_add_message already does so
+  // callers can distinguish "server unreachable" from "action required (pin
+  // a datapack)".
+  if (result && result.error) {
+    const err = new Error(`conversation_create failed: ${JSON.stringify(result.error)}`);
+    err.code = result.error;
+    err.detail = result.detail || "";
+    // Distinguish a server-returned structured error from a Node system error
+    // (e.g. ECONNREFUSED off `fetch`), which also carries `.code`. The catch
+    // site branches on this to keep "MCP unavailable" reserved for transport
+    // failures.
+    err.isMcpToolError = true;
+    throw err;
+  }
   return result && result.id ? result.id : null;
 }
 
-async function addMessage(convId, agentId, exchange, datapackId = 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, timeoutMs = null) {
   const seed = `${convId}:${exchange.user_uuid}`;
   const payload = {
     conversation_id: convId,
@@ -802,7 +2086,15 @@ async function addMessage(convId, agentId, exchange, datapackId = null) {
     seed: seed,
   };
   if (datapackId) payload.datapack_id = datapackId;
-  const response = await mcpCall("conversation_add_message", payload);
+  if (exchange.metadata != null) {
+    payload.metadata =
+      typeof exchange.metadata === "string"
+        ? exchange.metadata
+        : JSON.stringify(exchange.metadata);
+  }
+  const response = await mcpCall("conversation_add_message", payload, {
+    timeoutMs: timeoutMs || MEKO_ADD_MESSAGE_TIMEOUT,
+  });
   // FAIL CLOSED. The MCP transport resolves successfully even when the tool
   // failed, and failures take several shapes: an `isError` result envelope, a
   // JSON body with an `error` field, or a non-JSON / missing-content / otherwise
@@ -823,7 +2115,22 @@ async function addMessage(convId, agentId, exchange, datapackId = null) {
     );
   }
   if (result.error) {
-    throw new Error(`conversation_add_message failed: ${JSON.stringify(result.error)}`);
+    // Keep the server's detail: isMissingConversationError() keys on it.
+    const detail = typeof result.detail === "string" && result.detail ? `: ${result.detail}` : "";
+    throw new Error(`conversation_add_message failed: ${JSON.stringify(result.error)}${detail}`);
+  }
+  // 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 +2196,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 +2234,6 @@ function workspaceKeyFromHookInput(hookInput, transcriptPath) {
   return cwd || process.cwd();
 }
 
-// --- Main ---
-
 // --- SessionStart: create conversation + watermark deterministically ---
 
 function findMostRecentProjectWatermark(transcriptPath, currentSessionId) {
@@ -938,6 +2254,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 +2272,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,11 +2290,10 @@ ${memories.join("\n")}`
   return `## Meko Session Active
 
 ${opening}
-${captureWarning}
 
 ### What you MUST do with Meko tools
 
-- **agent_id**: use "${resolvedAgentId}" verbatim for every Meko MCP tool call in this session. This was derived from the cwd as \`<client>:<repo-basename>\` so memories stay scoped to this project. For genuinely cross-project facts (user identity, global preferences) pass agent_id="${COMMON_BUCKET_AGENT_ID}" — that's the common bucket any agent can read regardless of project.
+- **agent_id**: use "${resolvedAgentId}" verbatim for every Meko MCP tool call in this session. Project-scoped ids have the shape \`<client>:<repo-basename>\`, where the repo root is found by walking parents of the session cwd for \`.git\`, so memories stay scoped to this repo; sessions outside any repo use the bare client name (e.g. \`claude_code\`) rather than a colliding directory basename. A resumed session, or one that re-fires SessionStart (\`/clear\`, \`/compact\`), keeps the bucket its conversation already belongs to, and \`MEKO_AGENT_ID\` overrides either — so take the value above as given rather than re-deriving it yourself. For genuinely cross-project facts (user identity, global preferences) pass agent_id="${COMMON_BUCKET_AGENT_ID}" — that's the common bucket any agent can read regardless of project.
 - **conversation_id**: Use "${convId}" for all MCP tool calls that accept it
 
 ### Memory capture is automatic only when hook delivery succeeds — do NOT proactively call memory_add
@@ -999,7 +2307,7 @@ Call memory_add (with the session's agent_id + conversation_id) ONLY for the nar
 
 ### Recall and before destructive actions
 
-- User asks "what do you know about X?" → call memory_search first.
+- User asks "what do you know about X?" → call context_search first (memory, knowledge base, and past conversations in one call). Confirm an empty memory or knowledge-base result with memory_search or knowledgebase_search before saying nothing is stored.
 - Before any action that deletes, overwrites, or restructures user content (Write-overwrite, large Edit deletions, rm, git reset --hard, destructive SQL), call memory_search for relevant feedback and confirm with the user if any prior guidance applies.
 
 ### Use Meko, not local storage
@@ -1010,9 +2318,17 @@ Never write memories to local files (e.g., ~/.claude/projects/.../memory/). Meko
 function buildSessionStartFallbackContext(agentId, opts) {
   const resolvedAgentId = agentId || COMMON_BUCKET_AGENT_ID;
   const datapackBlock = buildActiveDatapackBlock(opts && opts.datapackPin ? opts.datapackPin : null);
+  // MEKO-592: the "server unreachable" preamble is the wrong story when the
+  // server accepted the call and told us to pin a datapack. Callers pass
+  // reason:"datapack_required" to swap it for setup guidance the agent can
+  // act on.
+  const reason = opts && opts.reason;
+  const preamble = reason === "datapack_required"
+    ? "The SessionStart hook reached the Meko MCP server, but no datapack is pinned for this project, so the server declined to create a conversation. **Automatic conversation capture is idle**. Use `datapack_list` to find a datapack id, then invoke the `meko-select-datapack` skill (or your client's equivalent) to pin it. The next drain picks up the fresh pin and starts capturing this session's queued turns; until then, save facts explicitly."
+    : "The SessionStart hook could not reach the Meko MCP server to create a conversation. **Automatic conversation capture is NOT running this session**, so the server-side extraction that normally saves memories for you will not fire. Fall back to saving facts explicitly.";
   return `## Meko Memory Instructions
 
-The SessionStart hook could not reach the Meko MCP server to create a conversation. **Automatic conversation capture is NOT running this session**, so the server-side extraction that normally saves memories for you will not fire. Fall back to saving facts explicitly.
+${preamble}
 
 ### What you should do while capture is down
 
@@ -1024,7 +2340,7 @@ The SessionStart hook could not reach the Meko MCP server to create a conversati
 Because nothing is capturing this session, explicit saves are the only path — this is the exception, not the normal mode:
 - User shares personal info, preferences, or role → call memory_add immediately
 - User shares org conventions or team standards → call memory_add immediately
-- User asks "what do you know about X?" → call memory_search first
+- User asks "what do you know about X?" → call context_search first
 
 ### Use Meko, not local storage
 
@@ -1074,6 +2390,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 ||
@@ -1082,37 +2410,107 @@ async function handleSessionStart(hookInput) {
   const sessionId = extractSessionId(hookInput, transcriptPath);
 
   const source = hookInput.source || "";
-  const derivedAgentId = resolveSessionAgentId(transcriptPath, hookInput);
+  const sessionCwd = pickSessionCwd(transcriptPath, hookInput);
+  const derivedAgentId = resolveSessionAgentId(transcriptPath, hookInput, sessionCwd);
+  const legacyAgentId = deriveLegacyAgentId({
+    client: resolveHookClient(),
+    cwd: sessionCwd,
+    envOverride: process.env.MEKO_AGENT_ID,
+  });
+  logAgentIdDerivation(sessionCwd, derivedAgentId);
   const workspaceKey = workspaceKeyFromHookInput(hookInput, transcriptPath);
 
   // Check if watermark already exists (same session ID re-fires SessionStart, e.g. /clear, /compact)
   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, legacyAgentId),
+      }));
+      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) {
+        logEffectiveAgentId(derivedAgentId, existing.agent_id, "watermark-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;
+      logEffectiveAgentId(derivedAgentId, resumedAgentId, "watermark-reconcile");
+      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 +2530,75 @@ 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) {
+        logEffectiveAgentId(derivedAgentId, prior.agent_id, "resume-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;
+      logEffectiveAgentId(derivedAgentId, resumedAgentId, "resume-reconcile");
+      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 +2611,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 datapackPin = readDatapackPin(agentId, legacyAgentId);
+  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();
@@ -1188,16 +2644,49 @@ async function handleSessionStart(hookInput) {
       datapackPin && datapackPin.datapack_id,
     );
   } 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) });
+    // MEKO-592: distinguish "server unreachable" (network/init failure) from
+    // "server accepted the call and told us to pin a datapack". The latter
+    // is user action, not a server outage — logging it as "MCP unavailable"
+    // sends the reporter down the wrong troubleshooting path.
+    const isDatapackRequired = err && err.code === "datapack_id_required";
+    if (isDatapackRequired) {
+      process.stderr.write(
+        `[meko-capture] SessionStart: no datapack pinned; auto-capture is idle. Pin one with datapack_list + meko-select-datapack; the next drain picks up the fresh pin.\n`,
+      );
+    } else if (err && err.isMcpToolError) {
+      // Server accepted the call and returned a structured error (e.g.
+      // invalid_metadata, create_failed). It is not "MCP unavailable"; print
+      // the code so the reporter isn't sent down the network path. Node
+      // system errors (ECONNREFUSED, ETIMEDOUT) also carry `.code`, so we
+      // gate on the marker set by createConversation.
+      process.stderr.write(
+        `[meko-capture] SessionStart: server rejected conversation_create (${err.code}: ${err.detail || err.message}). Falling back to agent-driven setup.\n`,
+      );
+    } else {
+      process.stderr.write(`[meko-capture] SessionStart: MCP unavailable (${err.message}). Falling back to agent-driven setup.\n`);
+    }
+    const contextOpts = { datapackPin: readDatapackPin(agentId, legacyAgentId) };
+    if (isDatapackRequired) contextOpts.reason = "datapack_required";
+    let context = withHealthNotice(buildSessionStartFallbackContext(agentId, contextOpts));
     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,
-      });
+      // MEKO-592: state was written by writeSessionIntent above with
+      // `delivery: "needs_conversation"`, which is the Capture V2 marker
+      // that `recover` and drain look for. Don't overwrite it here - the
+      // first drain classifies the failure and updates the health bucket.
+      // The prior `status: "action_required"` cache write was dead code
+      // (nothing reads the session cache for `--capture-status`), so keep
+      // `"error"` and leave the health signal to state on the next drain.
+      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 +2694,21 @@ 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, legacyAgentId),
+    }));
     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 +2727,994 @@ 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_failure_scope: null,
+    recovered_from_conversation_id: null,
+    missing_conversation_streak: null,
+    last_success_at: new Date().toISOString(),
+    consecutive_exchange_drops:
+      extras.consecutive_exchange_drops != null
+        ? extras.consecutive_exchange_drops
+        : 0,
+    in_flight: { seed: null, user_line: null, user_turn_id: null },
+  };
+  if (extras.lifecycle) next.lifecycle = extras.lifecycle;
+  if (extras.dropped_exchanges != null) {
+    next.dropped_exchanges = extras.dropped_exchanges;
+  }
+  if (extras.last_drop_reason !== undefined) {
+    next.last_drop_reason = extras.last_drop_reason;
+  }
+  if (extras.last_success_at !== undefined) {
+    next.last_success_at = extras.last_success_at;
+  }
+  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 = turnInput(turn) || "";
+  // A turn held only because injected context (a skill body or a task
+  // notification) never got its follow-up reply already has a real answer.
+  // Keep it rather than replacing it with the interrupted marker.
+  if (
+    turn.assistantEntries.length > 0 &&
+    !(turn.codexStreaming && !turn.codexComplete)
+  ) {
+    const { output, reasoning } = renderTurnBody(turn);
+    if (output) {
+      return {
+        user_uuid: turn.userMsg.uuid || "unknown",
+        user_line: turn.userLine,
+        next_line_number: null,
+        input,
+        output,
+        reasoning,
+        timestamp:
+          turn.assistantEntries[turn.assistantEntries.length - 1].timestamp ||
+          turn.userMsg.timestamp ||
+          "",
+      };
+    }
+  }
+  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,
+          consecutive_exchange_drops: 0,
+        };
+    const transcriptPath =
+      opts.transcript_path ||
+      state.transcript_path ||
+      null;
+
+    const persistedLifecycle = state.lifecycle;
+    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;
+    const nowMs = Date.now();
+    const persistentRetryDue =
+      state.failure_class === "persistent" &&
+      state.last_failure_scope === "exchange" &&
+      Number.isFinite(retryAtMs) &&
+      retryAtMs <= nowMs;
+    if (
+      state.failure_class &&
+      Number.isFinite(retryAtMs) &&
+      retryAtMs > nowMs &&
+      !(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)) {
+      // The transcript is the only source of turns, so a closed session whose
+      // transcript is gone has nothing left to deliver — ever. Left alone it
+      // sits at "pending" forever and holds the health rollup below healthy:
+      // 26 such tombstones had accumulated, the oldest 16.7 days old, none of
+      // them carrying a single deliverable turn.
+      //
+      // Only a session that is closing/closed AND has been idle past the grace
+      // period is finalized. An ACTIVE session whose transcript has not
+      // appeared yet must stay pending so it can still deliver, and the grace
+      // period covers a transcript that is briefly unreadable (an unmounted
+      // volume, a permissions blip) rather than genuinely gone.
+      const idleMs = state.last_activity_at
+        ? Date.now() - Date.parse(state.last_activity_at)
+        : 0;
+      const graceMs = transcriptMissingGraceSeconds() * 1000;
+      const finalizable =
+        (persistedLifecycle === "closing" || persistedLifecycle === "closed") &&
+        Number.isFinite(idleMs) &&
+        idleMs >= graceMs &&
+        coerceQueued(state) === 0;
+      if (stateExisted && finalizable) {
+        state.lifecycle = "closed";
+        state.delivery = "complete";
+        state.queued_exchanges = 0;
+        clearResolvedFailure(state);
+        captureState.writeState(sessionId, state);
+        process.stderr.write(
+          `[meko-capture] Finalizing ${sessionId}: transcript is gone and the session ` +
+          `closed ${Math.round(idleMs / 86400000)}d ago with nothing queued; ` +
+          `nothing left to deliver.\n`,
+        );
+        return makeDrainResult({
+          status: "noop",
+          session_id: sessionId,
+          last_line_number: state.last_line_number || 0,
+          lifecycle: state.lifecycle,
+          delivery: state.delivery,
+          error: "transcript missing; finalized",
+        });
+      }
+      // A recovery sweep marks abandoned sessions as closing while it drains
+      // them. Do not persist that override when the transcript is absent: the
+      // stored active lifecycle is the evidence that this session may return.
+      if (mode === "recover" && persistedLifecycle === "active") {
+        state.lifecycle = persistedLifecycle;
+      }
+      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);
+    let datapackPin = datapackPinFromWatermark({
+      datapack_id: state.datapack_id,
+      datapack_name: state.datapack_name,
+    });
+
+    // MEKO-592: SessionStart freezes state.datapack_id at the value the pin
+    // resolved to when the session opened. If the session started before the
+    // user pinned a datapack, that value is null and every drain here would
+    // resend it, hitting datapack_id_required against the guarded server on
+    // every retry. Re-read the pin file when state has none so a mid-session
+    // pin actually recovers this session's queued turns instead of forcing
+    // the user to start a fresh session.
+    if (!datapackPin && (state.agent_id || "").trim()) {
+      const freshPin = readDatapackPin(state.agent_id);
+      if (freshPin && freshPin.datapack_id) {
+        datapackPin = freshPin;
+        state.datapack_id = freshPin.datapack_id;
+        state.datapack_name = freshPin.datapack_name || null;
+      }
+    }
+
+    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 persistent = classifyPersistentCaptureFailure(err);
+      const failureClass = persistent
+        ? "persistent"
+        : captureState.classifyFailure(err);
+      const failureText = persistentFailureText(persistent, err.message);
+      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 = failureText;
+        state.last_failure_scope = persistent ? persistent.scope : null;
+        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: ${failureText}\n`,
+      );
+      return makeDrainResult({
+        status: failureClass === "transient" ? "retry_wait" : "blocked",
+        session_id: sessionId,
+        queued_remaining: pendingExchanges,
+        failure_class: failureClass,
+        error: failureText,
+        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;
+        clearResolvedFailure(state);
+      }
+      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);
+    // PreCompact blocks the user, so it keeps the short timeout; background
+    // drains wait for a slow server to finish storing a large turn.
+    const addMessageTimeoutMs =
+      mode === "pre-compact" ? MEKO_API_TIMEOUT : MEKO_ADD_MESSAGE_TIMEOUT;
+    const leaseTtl = Math.max(
+      captureState.leaseTtlSeconds(),
+      Math.ceil(addMessageTimeoutMs / 1000) + 30,
+    );
+    // Set when renewal fails: "ownership" means another worker took the
+    // lease; anything else means this worker couldn't write it.
+    let leaseFailure = null;
+    let captured = 0;
+    let failed = 0;
+    let dropped = 0;
+    // Exchange-scoped HTML 403s may be payload-specific OR request-wide.
+    // Allow one consecutive drop without an intervening success so a single
+    // XSS turn cannot wedge the session; a second consecutive one holds the
+    // queue because it may be a session-wide edge block.
+    let consecutiveExchangeDrops = Number.isInteger(
+      state.consecutive_exchange_drops,
+    )
+      ? state.consecutive_exchange_drops
+      : 0;
+    // Consume the backoff drop on the first exchange of this drain, success
+    // or failure, so a later HTML 403 in the same batch cannot also skip.
+    let allowExchangeDropAfterBackoff = persistentRetryDue;
+    let cursorAdvanced = false;
+    let watermarkLine = extractFrom;
+    state.delivery = "draining";
+    state.queued_exchanges = allExchanges.length;
+    captureState.writeState(sessionId, state);
+
+    for (const exchange of exchanges) {
+      // Keep the lease ahead of a slow add_message so another drain can't
+      // reclaim it mid-batch. If renewal fails, stop without sending: either
+      // another drain owns the session, or this worker can't write the lease.
+      if (leaseToken) {
+        const renewed = captureState.renewLease(sessionId, leaseToken, {
+          ttlSeconds: leaseTtl,
+        });
+        if (!renewed.ok) {
+          leaseFailure = {
+            failure_class: renewed.failure_class === "ownership" ? "ownership" : "transient",
+            error: renewed.error || "lease renewal failed",
+          };
+          break;
+        }
+      }
+      const canDropAfterBackoff = allowExchangeDropAfterBackoff;
+      allowExchangeDropAfterBackoff = false;
+      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,
+          addMessageTimeoutMs,
+        );
+        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 - dropped - 1;
+        const ck = persistExchangeCheckpoint(sessionId, state, nextLine, {
+          delivery:
+            remainingAfter > 0 || allExchanges.length > maxBatch
+              ? "pending"
+              : "idle",
+          queued_exchanges: Math.max(0, remainingAfter),
+          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++;
+        consecutiveExchangeDrops = 0;
+        cursorAdvanced = true;
+      } catch (err) {
+        // A conversation the server no longer has never heals, so retrying the
+        // same id burns attempts and strands every queued turn. Open a fresh
+        // conversation and move the undelivered tail into it. Return immediately
+        // rather than falling through to the post-loop cursor advance.
+        //
+        // A single not_found can be a transient Langfuse lookup. Wait until the
+        // same detail persists across two drains before opening a replacement,
+        // so one blip does not fork a live conversation.
+        //
+        // Recover at most once before the replacement accepts a turn. If the
+        // replacement reports not_found first, the fresh trace may not be
+        // visible on another replica yet. Retry it rather than opening one
+        // conversation per attempt. A successful checkpoint clears the guard,
+        // so a later deletion can recover again.
+        const missingConversation = isMissingConversationError(err);
+        if (missingConversation) {
+          state.missing_conversation_streak = missingConversationStreak(state) + 1;
+        } else if (state.missing_conversation_streak) {
+          state.missing_conversation_streak = null;
+        }
+        const alreadyRecovered = Boolean(state.recovered_from_conversation_id);
+        const streakPersisted =
+          missingConversationStreak(state) >= MISSING_CONVERSATION_RECOVERY_POLLS;
+        if (missingConversation && alreadyRecovered) {
+          process.stderr.write(
+            `[meko-capture] Conversation ${convId} reports not_found, but it already replaced ` +
+            `${state.recovered_from_conversation_id}; retrying it instead of opening another.\n`,
+          );
+        } else if (missingConversation && !streakPersisted) {
+          process.stderr.write(
+            `[meko-capture] Conversation ${convId} reports not_found ` +
+            `(${missingConversationStreak(state)}/${MISSING_CONVERSATION_RECOVERY_POLLS}); ` +
+            `retrying it before opening a new conversation.\n`,
+          );
+        }
+        if (missingConversation && !alreadyRecovered && streakPersisted) {
+          const recovered = await recoverMissingConversation({
+            state,
+            sessionId,
+            agentId: effectiveAgentId,
+            transcriptPath,
+            datapackId: datapackPin && datapackPin.datapack_id,
+          });
+          if (recovered.ok) {
+            process.stderr.write(
+              `[meko-capture] Conversation ${convId} is gone server-side (${err.message}); ` +
+              `moving ${allExchanges.length - captured} queued exchange(s) into new conversation ` +
+              `${recovered.convId}.\n`,
+            );
+            return makeDrainResult({
+              status: "retry_wait",
+              session_id: sessionId,
+              captured,
+              queued_remaining: allExchanges.length - captured,
+              last_line_number: recovered.state.last_line_number || 0,
+              lifecycle: recovered.state.lifecycle,
+              delivery: recovered.state.delivery,
+            });
+          }
+          process.stderr.write(
+            `[meko-capture] Conversation ${convId} is gone server-side but recovery failed ` +
+            `(${recovered.error}); retrying.\n`,
+          );
+        }
+        const persistent = classifyPersistentCaptureFailure(err, {
+          exchange: true,
+        });
+
+        // An exchange-scoped persistent rejection *may* be deterministic for
+        // this exchange only (edge filtering matched a signature inside the
+        // transcript text). Holding forever behind a true payload rejection
+        // wedges the rest of the session (#13). HTML 403 alone is not proof
+        // it is payload-specific — request-wide edge blocks share that shape
+        // — so allow at most one consecutive drop without an intervening
+        // success; a second consecutive failure holds for retry.
+        if (
+          persistent &&
+          persistent.scope === "exchange" &&
+          (consecutiveExchangeDrops < 1 || canDropAfterBackoff)
+        ) {
+          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 - dropped - 1;
+          const drop = persistExchangeCheckpoint(sessionId, state, nextLine, {
+            delivery:
+              remainingAfter > 0 || allExchanges.length > maxBatch
+                ? "pending"
+                : "idle",
+            queued_exchanges: Math.max(0, remainingAfter),
+            // Nothing was stored, so the last-success stamp must not move.
+            last_success_at: state.last_success_at || null,
+            dropped_exchanges: (state.dropped_exchanges || 0) + 1,
+            last_drop_reason: persistent.reason,
+            consecutive_exchange_drops: consecutiveExchangeDrops + 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 (drop.ok) {
+            state = drop.state;
+            watermarkLine = state.last_line_number;
+            dropped++;
+            consecutiveExchangeDrops = state.consecutive_exchange_drops;
+            cursorAdvanced = true;
+            process.stderr.write(
+              `[meko-capture] Dropped un-storable exchange (uuid=${exchange.user_uuid}): ` +
+                `${persistent.reason}. Cursor advanced to line ${watermarkLine}; ` +
+                `capture continues for the rest of this session.\n`,
+            );
+            continue;
+          }
+          // Cursor advance itself failed — fall through and hold, rather than
+          // losing the exchange without a durable record that it was dropped.
+          process.stderr.write(
+            `[meko-capture] Could not record dropped exchange (uuid=${exchange.user_uuid}): ${drop.error}\n`,
+          );
+        } else if (persistent && persistent.scope === "exchange") {
+          process.stderr.write(
+            `[meko-capture] Holding after consecutive edge 403s (uuid=${exchange.user_uuid}): ` +
+              `${persistent.reason}. A second consecutive HTML 403 without an ` +
+              `intervening success may be request-wide; queue is held for retry.\n`,
+          );
+        }
+
+        failed++;
+        const failureClass = persistent
+          ? "persistent"
+          : captureState.classifyFailure(err);
+        state.delivery =
+          failureClass === "transient" ? "retry_wait" : "blocked";
+        state.failure_class = failureClass;
+        // Prefer the classifier reason so quota/entitlement text survives into
+        // state and SessionStart notices instead of an opaque http_403.
+        state.last_error = persistentFailureText(persistent, err.message);
+        state.last_failure_scope = persistent ? persistent.scope : null;
+        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 - dropped;
+        captureState.writeState(sessionId, state);
+        process.stderr.write(
+          `[meko-capture] Failed to add message (uuid=${exchange.user_uuid}): ${state.last_error}\n`,
+        );
+        break;
+      }
+    }
+
+    // Dropped exchanges are resolved, not held: they can never be stored, so
+    // they must not count as backlog or the session reads as permanently behind.
+    const held = allExchanges.length - captured - dropped;
+    if (leaseFailure) {
+      // Progress so far is already checkpointed. Nothing is recorded as a
+      // delivery failure: the server never saw the next exchange.
+      const lost = leaseFailure.failure_class === "ownership";
+      process.stderr.write(
+        lost
+          ? `[meko-capture] drain lease lost after ${captured} exchange(s); leaving the rest to its new owner.\n`
+          : `[meko-capture] could not renew the drain lease after ${captured} exchange(s): ${leaseFailure.error}; stopping this batch.\n`,
+      );
+      return makeDrainResult({
+        status: "retry_wait",
+        session_id: sessionId,
+        captured,
+        dropped,
+        queued_remaining: held,
+        failure_class: leaseFailure.failure_class,
+        error: lost
+          ? "drain lease lost to another worker"
+          : `drain lease renewal failed: ${leaseFailure.error}`,
+        cursor_advanced: cursorAdvanced,
+        last_line_number: state.last_line_number || 0,
+        lifecycle: state.lifecycle,
+        delivery: state.delivery,
+      });
+    }
+    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;
+      }
+      clearResolvedFailure(state);
+      captureState.writeState(sessionId, state);
+      cursorAdvanced =
+        captured > 0 || dropped > 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`,
+      );
+    }
+
+    if (dropped > 0) {
+      process.stderr.write(
+        `[meko-capture] ${dropped} exchange(s) could not be stored and were ` +
+          `skipped so the rest of the session still captures.\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,
+      dropped,
+      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 +3725,82 @@ 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,
+    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,
+  deriveLegacyAgentId,
+  drainSession,
+  makeDrainResult,
+  boundaryAfterExchange,
+  realUserTurnLines,
+  INTERRUPTED_ASSISTANT_OUTPUT,
+  buildExchanges,
+  buildInterruptedExchange,
+  extractExchanges,
+  addMessage,
+  isMissingConversationError,
+  recoverMissingConversation,
+};
+
+if (require.main === module) {
+  main().catch((err) => {
+    process.stderr.write(`[meko-capture] Fatal error: ${err.message}\n`);
+    process.stdout.write(hookOutput(""));
+  });
+}