@yugabytedb/meko-mcp 2.2.0 → 2.5.0

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

@@ -13,6 +13,10 @@
  *   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)
+ *   node capture.js move           # stdin {"session_id"} → move the unsent
+ *                                  # tail to a new conversation; stdout
+ *                                  # {ok, from, to, last_line_number} or
+ *                                  # {ok:false, busy?, error}
  *
  * drain / recover stdin contract (Workstream C):
  *   {
@@ -28,10 +32,17 @@
  * 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)
  */
@@ -52,16 +63,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, codex, kiro) → `<client>:<repo-basename>`,
- *     with the basename lowercased and non-`[a-z0-9-]` runs collapsed to `-`.
- *     Outside a repo → bare client name (keeps coding-agent traffic out of
- *     the common bucket).
+ *   - 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).
  */
@@ -74,13 +142,16 @@ function deriveAgentId(opts) {
     client !== "claude_code" &&
     client !== "cursor" &&
     client !== "codex" &&
-    client !== "kiro"
+    client !== "kiro" &&
+    client !== "opencode"
   ) {
     return COMMON_BUCKET_AGENT_ID;
   }
-  const rawBase = opts && opts.cwd ? path.basename(opts.cwd) : "";
-  if (!rawBase || rawBase === "." || rawBase === "/") return client;
-  const project = rawBase.toLowerCase()
+  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);
@@ -88,6 +159,31 @@ 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>`;
@@ -98,7 +194,7 @@ function deriveAgentId(opts) {
  */
 function resolveHookClient() {
   const client = (process.env.MEKO_HOOK_CLIENT || "").trim();
-  if (client === "cursor" || client === "codex" || client === "kiro") return client;
+  if (client === "cursor" || client === "codex" || client === "kiro" || client === "opencode") return client;
   return "claude_code";
 }
 
@@ -114,9 +210,7 @@ function resolveHookClient() {
  *   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
@@ -127,7 +221,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 ||
@@ -138,14 +232,71 @@ function resolveSessionAgentId(transcriptPath, hookInput = null) {
     workspaceRoot ||
     hookInput?.cwd ||
     nested.cwd ||
-    process.cwd();
+    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"];
+const CODING_CLIENTS = ["claude_code", "cursor", "codex", "kiro", "opencode"];
 
 /**
  * Extract the client segment of an agent_id: the part before the first `:`,
@@ -269,6 +420,12 @@ function ownerChanged(cachedAgentId, resolvedAgentId, convId) {
 
 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");
@@ -395,6 +552,197 @@ 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 ---
 
 // Codex turn-completion boundary discriminator.
@@ -524,13 +872,63 @@ function parseTranscriptEntries(filePath, startLine) {
   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));
+    }
+  }
+
+  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. All
- * subsequent assistant lines and tool-result user lines belong to that
- * exchange until the next real user message.
+ * 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 }`:
@@ -549,19 +947,25 @@ function parseTranscriptEntries(filePath, startLine) {
  *     complete trailing turn, which advances fully.
  */
 function buildExchanges(items) {
-  const skipPattern =
-    /^<(system-reminder|command-|local-command|available-deferred)/;
   const turns = [];
   let current = null;
 
+  const startsTurn = turnStartTracker();
   for (const { entry, line } of items) {
-    if (entry.type === "user" && !isToolResultMessage(entry)) {
+    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
@@ -574,6 +978,9 @@ function buildExchanges(items) {
     } 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) {
@@ -583,6 +990,11 @@ function buildExchanges(items) {
         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;
       }
     }
   }
@@ -602,11 +1014,12 @@ function buildExchanges(items) {
   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 = extractText((last.userMsg.message || {}).content);
-    if (lastInput && !skipPattern.test(lastInput)) {
+    const lastInput = turnInput(last);
+    if (isCapturableInput(lastInput)) {
       pendingFromLine = last.userLine;
     }
   }
@@ -622,31 +1035,11 @@ function buildExchanges(items) {
       pendingFromLine !== null && t === turns.length - 1;
     if (isPendingTrailing) continue;
 
-    const input = extractText((ex.userMsg.message || {}).content);
-    if (!input || skipPattern.test(input)) continue;
+    const input = turnInput(ex);
+    if (!isCapturableInput(input)) continue;
     if (ex.assistantEntries.length === 0) continue;
 
-    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 { output, reasoning } = renderTurnBody(ex);
 
     results.push({
       user_uuid: ex.userMsg.uuid || "unknown",
@@ -658,8 +1051,8 @@ function buildExchanges(items) {
       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 ||
@@ -767,6 +1160,7 @@ function writeWatermark(wmPath, convId, lineNum, agentId, datapackPin = null, ag
         last_error: null,
         last_success_at: null,
         blocked_reason: null,
+        consecutive_exchange_drops: 0,
       };
 
   const existingPin =
@@ -828,10 +1222,9 @@ function writeWatermark(wmPath, convId, lineNum, agentId, datapackPin = null, ag
 /** 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 (entry.type === "user" && !isToolResultMessage(entry)) {
-      lines.push(line);
-    }
+    if (startsTurn(entry)) lines.push(line);
   }
   return lines;
 }
@@ -862,6 +1255,7 @@ function makeDrainResult(partial) {
     lifecycle: partial.lifecycle || "active",
     delivery: partial.delivery || "idle",
     next_retry_at: partial.next_retry_at || null,
+    dropped: partial.dropped || 0,
   };
 }
 
@@ -883,27 +1277,38 @@ function datapackPinSlug(agentId) {
  * 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) {
@@ -942,9 +1347,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 = {
@@ -973,12 +1383,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);
@@ -1010,15 +1421,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();
   });
@@ -1028,7 +1449,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);
   }
 
@@ -1055,24 +1479,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/],
@@ -1082,6 +1560,16 @@ 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/],
+    // MEKO-876: a viewer of a shared datapack can't record conversations.
+    // Account-scoped like the above: it stays refused until the role changes.
+    ["read_only_access", /read_only_access/],
   ];
   for (const [code, pattern] of persistentPatterns) {
     if (pattern.test(normalized)) {
@@ -1093,13 +1581,309 @@ 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",
+        read_only_access: "the account has viewer (read-only) 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 };
+}
+
+/**
+ * Move a session's unsent turns to a new conversation on request, without
+ * waiting for capture to see `not_found` twice. Used by
+ * `--capture-cleanup fix` when the recorded conversation can't be served:
+ * its owner reads as `None`, its lookup keeps failing, or a replay loop
+ * bloated it. Holds the drain lease for the whole move, keeps the cursor,
+ * and creates the conversation under the session's recorded owner and
+ * datapack.
+ *
+ * The caller can pass `expected_conversation_id`. Under the lease, the move
+ * is refused (`changed: true`) when the session's conversation no longer
+ * matches it, or when a previous move is still waiting for its new
+ * conversation to accept a turn (`recovered_from_conversation_id`): a hook
+ * drain may have recovered or delivered the session while the caller waited.
+ *
+ * @param {{ session_id: string, expected_conversation_id?: string }} options
+ * @returns {Promise<{ok: boolean, busy?: boolean, changed?: boolean, from?: string, to?: string, last_line_number?: number, error?: string}>}
+ */
+async function moveSessionToNewConversation(options) {
+  const sessionId = String((options && options.session_id) || "").trim();
+  if (!sessionId) return { ok: false, error: "session_id required" };
+  const lease = captureState.acquireLease(sessionId);
+  if (!lease.ok) {
+    return {
+      ok: false,
+      busy: lease.failure_class === "ownership",
+      error: lease.error || "drain lease unavailable",
+    };
+  }
+  try {
+    const read = captureState.readState(sessionId);
+    if (!read.ok) return { ok: false, error: read.error || "watermark unreadable" };
+    let state = read.state;
+    if (!state.agent_id) return { ok: false, error: "recorded owner missing" };
+    const expected = options && options.expected_conversation_id;
+    // An automatic cleanup run must not end a park the user set with `stop`
+    // after that run scanned the session.
+    if (
+      options &&
+      options.respect_stop &&
+      state.parked &&
+      state.parked.reason === "stop" &&
+      state.failure_class &&
+      state.next_retry_at === captureState.CLEANUP_PARK_UNTIL
+    ) {
+      return { ok: false, paused: true, error: "paused by the user with stop" };
+    }
+    if (state.recovered_from_conversation_id) {
+      return {
+        ok: false,
+        changed: true,
+        error: "a previous move is waiting for its new conversation to accept a turn",
+      };
+    }
+    if (expected && state.conversation_id !== expected) {
+      return {
+        ok: false,
+        changed: true,
+        error: `the session moved to conversation ${state.conversation_id} while waiting`,
+      };
+    }
+    // Checked again here, under the lease: the session may have become live
+    // after --capture-cleanup planned the move. SessionStart gave a live
+    // session's agent its conversation_id, and a move can't tell it the new one.
+    if (options && options.defer_if_live && captureState.sessionLooksLive(state)) {
+      return { ok: false, deferred: true, error: "the session is still open" };
+    }
+    // MEKO-592: a session that started before the user pinned a datapack has
+    // none in its watermark. Re-read the pin the way drainSession does, so
+    // the new conversation is created in the datapack its turns will go to.
+    if (!state.datapack_id) {
+      const pin = readDatapackPin(state.agent_id);
+      if (pin && pin.datapack_id) {
+        state = { ...state, datapack_id: pin.datapack_id, datapack_name: pin.datapack_name || null };
+      }
+    }
+    await mcpInitialize();
+    const moved = await recoverMissingConversation({
+      // cleanup_moved_epoch lets --capture-cleanup count epochs since its own
+      // last move, not the session's lifetime total. The move also ends any
+      // park the cleanup tool set (the retry fields are reset here).
+      state: {
+        ...state,
+        parked: null,
+        cleanup_moved_epoch: Number(state.conversation_epoch || 0) + 1,
+      },
+      sessionId,
+      agentId: state.agent_id,
+      transcriptPath: state.transcript_path,
+      datapackId: state.datapack_id || null,
+    });
+    if (!moved.ok) return { ok: false, error: moved.error };
+    return {
+      ok: true,
+      from: state.conversation_id || null,
+      to: moved.convId,
+      last_line_number: moved.state.last_line_number,
+    };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  } finally {
+    captureState.releaseLease(sessionId, lease.lease.token);
+  }
+}
+
 /**
  * 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
@@ -1149,14 +1933,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;
 }
 
@@ -1218,21 +2005,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;
@@ -1242,18 +2037,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: `${clientLabel} session (auto-captured)`,
-    session_id: sessionId,
   };
+  if (!freshId) payload.session_id = sessionId;
   if (metadata) {
     payload.metadata = JSON.stringify({
       source: "hook",
@@ -1265,6 +2073,24 @@ 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;
 }
 
@@ -1362,7 +2188,7 @@ async function ensureConversationOwner({
   return { convId, agentId: cachedOwner, source: "derived", rebucketed: false };
 }
 
-async function addMessage(convId, agentId, exchange, datapackId = null) {
+async function addMessage(convId, agentId, exchange, datapackId = null, timeoutMs = null) {
   const seed = `${convId}:${exchange.user_uuid}`;
   const payload = {
     conversation_id: convId,
@@ -1379,7 +2205,9 @@ async function addMessage(convId, agentId, exchange, datapackId = null) {
         ? exchange.metadata
         : JSON.stringify(exchange.metadata);
   }
-  const response = await mcpCall("conversation_add_message", payload);
+  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
@@ -1400,7 +2228,9 @@ 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).
@@ -1576,7 +2406,7 @@ ${opening}
 
 ### 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
@@ -1590,7 +2420,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
@@ -1601,9 +2431,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_search(query=...)` (or `datapack_list` on a server without it) 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
 
@@ -1615,7 +2453,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
 
@@ -1685,7 +2523,14 @@ 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)
@@ -1697,7 +2542,7 @@ async function handleSessionStart(hookInput) {
         `[meko-capture] SessionStart: corrupt watermark for ${sessionId} (${existing.error}); blocking.\n`,
       );
       const context = withHealthNotice(buildSessionStartFallbackContext(derivedAgentId, {
-        datapackPin: readDatapackPin(derivedAgentId),
+        datapackPin: readDatapackPin(derivedAgentId, legacyAgentId),
       }));
       process.stdout.write(hookOutput(context));
       return;
@@ -1737,6 +2582,7 @@ async function handleSessionStart(hookInput) {
       // 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,
@@ -1750,6 +2596,7 @@ async function handleSessionStart(hookInput) {
         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
@@ -1823,6 +2670,7 @@ async function handleSessionStart(hookInput) {
       // 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,
@@ -1837,6 +2685,7 @@ async function handleSessionStart(hookInput) {
         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
@@ -1878,7 +2727,7 @@ async function handleSessionStart(hookInput) {
   // 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, {
@@ -1908,9 +2757,38 @@ 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`);
-    let context = withHealthNotice(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_search (or 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) {
+      // 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",
@@ -1929,7 +2807,9 @@ async function handleSessionStart(hookInput) {
 
   if (!convId) {
     process.stderr.write("[meko-capture] SessionStart: conversation_create returned no ID.\n");
-    let context = withHealthNotice(buildSessionStartFallbackContext(agentId, { datapackPin: readDatapackPin(agentId) }));
+    let context = withHealthNotice(buildSessionStartFallbackContext(agentId, {
+      datapackPin: readDatapackPin(agentId, legacyAgentId),
+    }));
     if (sessionId) {
       try {
         writeSessionCache(sessionId, {
@@ -2006,10 +2886,26 @@ function persistExchangeCheckpoint(sessionId, state, nextLine, extras) {
     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;
@@ -2032,7 +2928,30 @@ function persistExchangeCheckpoint(sessionId, state, nextLine, extras) {
  * Build a synthetic interrupted exchange for a trailing incomplete user turn.
  */
 function buildInterruptedExchange(turn, sessionId) {
-  const input = extractText((turn.userMsg.message || {}).content) || "";
+  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,
@@ -2146,12 +3065,14 @@ async function drainSession(options) {
           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") {
@@ -2164,10 +3085,16 @@ async function drainSession(options) {
     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 > Date.now() &&
+      retryAtMs > nowMs &&
       !(Boolean(opts.force_retry) && state.failure_class === "persistent")
     ) {
       return makeDrainResult({
@@ -2184,6 +3111,52 @@ async function drainSession(options) {
     }
 
     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",
@@ -2198,11 +3171,27 @@ async function drainSession(options) {
     let convId = state.conversation_id || "";
     let lastLine = state.last_line_number || 0;
     const currentLines = countLines(transcriptPath);
-    const datapackPin = datapackPinFromWatermark({
+    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 || "";
 
@@ -2270,14 +3259,19 @@ async function drainSession(options) {
         }
       }
     } catch (err) {
-      const failureClass = captureState.classifyFailure(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 = err.message;
+        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,
@@ -2287,14 +3281,14 @@ async function drainSession(options) {
         captureState.writeState(sessionId, state);
       }
       process.stderr.write(
-        `[meko-capture] Failed to initialize MCP session: ${err.message}\n`,
+        `[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: err.message,
+        error: failureText,
         last_line_number: lastLine,
         lifecycle: state.lifecycle,
         delivery: stateExisted ? state.delivery : "needs_conversation",
@@ -2391,6 +3385,7 @@ async function drainSession(options) {
           state.lifecycle = "closed";
         }
         state.queued_exchanges = 0;
+        clearResolvedFailure(state);
       }
       state.agent_id = effectiveAgentId;
       state.agent_id_source = effectiveSource;
@@ -2414,8 +3409,32 @@ async function drainSession(options) {
     }
 
     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";
@@ -2423,6 +3442,23 @@ async function drainSession(options) {
     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,
@@ -2438,6 +3474,7 @@ async function drainSession(options) {
           effectiveAgentId,
           exchange,
           datapackPin && datapackPin.datapack_id,
+          addMessageTimeoutMs,
         );
         const boundary = boundaryAfterExchange(turnLines, exchange.user_line);
         const nextLine =
@@ -2446,13 +3483,13 @@ async function drainSession(options) {
             : exchange.next_line_number != null
               ? exchange.next_line_number
               : safeLine;
-        const remainingAfter = allExchanges.length - captured - 1;
+        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, allExchanges.length - captured - 1),
+          queued_exchanges: Math.max(0, remainingAfter),
           agent_id: effectiveAgentId,
           agent_id_source: effectiveSource,
           conversation_id: convId,
@@ -2485,32 +3522,194 @@ async function drainSession(options) {
         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 persistent = classifyPersistentCaptureFailure(err);
         const failureClass = persistent
           ? "persistent"
           : captureState.classifyFailure(err);
         state.delivery =
           failureClass === "transient" ? "retry_wait" : "blocked";
         state.failure_class = failureClass;
-        state.last_error = err.message;
+        // 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;
+        state.queued_exchanges = allExchanges.length - captured - dropped;
         captureState.writeState(sessionId, state);
         process.stderr.write(
-          `[meko-capture] Failed to add message (uuid=${exchange.user_uuid}): ${err.message}\n`,
+          `[meko-capture] Failed to add message (uuid=${exchange.user_uuid}): ${state.last_error}\n`,
         );
         break;
       }
     }
 
-    const held = allExchanges.length - captured;
+    // 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) {
@@ -2527,8 +3726,10 @@ async function drainSession(options) {
         state.delivery = "idle";
         state.queued_exchanges = 0;
       }
+      clearResolvedFailure(state);
       captureState.writeState(sessionId, state);
-      cursorAdvanced = captured > 0 || cursorAdvanced || synthesizedInterrupted;
+      cursorAdvanced =
+        captured > 0 || dropped > 0 || cursorAdvanced || synthesizedInterrupted;
     } else if (failed === 0 && allExchanges.length > maxBatch) {
       state.delivery = "pending";
       state.queued_exchanges = held;
@@ -2544,6 +3745,13 @@ async function drainSession(options) {
       );
     }
 
+    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";
@@ -2562,6 +3770,7 @@ async function drainSession(options) {
       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,
@@ -2587,10 +3796,11 @@ async function main() {
     "checkpoint",
     "drain",
     "recover",
+    "move",
   ];
   if (!hookType || !known.includes(hookType)) {
     process.stderr.write(
-      "Usage: capture.js <session-start|before-submit-prompt|pre-compact|session-end|checkpoint|drain|recover>\n",
+      "Usage: capture.js <session-start|before-submit-prompt|pre-compact|session-end|checkpoint|drain|recover|move>\n",
     );
     process.exit(1);
   }
@@ -2603,7 +3813,11 @@ async function main() {
     process.stderr.write(
       `[meko-capture] Failed to parse hook input from stdin: ${err.message}\n`,
     );
-    if (hookType === "drain" || hookType === "recover") {
+    if (hookType === "move") {
+      process.stdout.write(
+        `${JSON.stringify({ ok: false, error: `invalid stdin JSON: ${err.message}` })}\n`,
+      );
+    } else if (hookType === "drain" || hookType === "recover") {
       process.stdout.write(
         JSON.stringify(
           makeDrainResult({
@@ -2624,6 +3838,12 @@ async function main() {
     return;
   }
 
+  if (hookType === "move") {
+    const result = await moveSessionToNewConversation(hookInput);
+    process.stdout.write(JSON.stringify(result) + "\n");
+    return;
+  }
+
   if (hookType === "before-submit-prompt") {
     handleBeforeSubmitPrompt(hookInput);
     return;
@@ -2641,7 +3861,7 @@ async function main() {
   const drainOpts = {
     session_id: sessionId,
     transcript_path: transcriptPath,
-    mode: hookType === "recover" ? "drain" : hookType,
+    mode: hookType,
     lifecycle: hookInput.lifecycle,
     confirmed_dead: Boolean(hookInput.confirmed_dead),
     recorded_owner_only: Boolean(hookInput.recorded_owner_only),
@@ -2688,14 +3908,19 @@ async function main() {
 
 module.exports = {
   deriveAgentId,
+  deriveLegacyAgentId,
   drainSession,
   makeDrainResult,
   boundaryAfterExchange,
   realUserTurnLines,
   INTERRUPTED_ASSISTANT_OUTPUT,
   buildExchanges,
+  buildInterruptedExchange,
   extractExchanges,
   addMessage,
+  isMissingConversationError,
+  recoverMissingConversation,
+  moveSessionToNewConversation,
 };
 
 if (require.main === module) {