@yugabytedb/meko-mcp 1.2.0 → 2.0.0

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

@@ -211,10 +211,18 @@ function extractToolResultContent(msg) {
   }
   // Fallback to toolUseResult summary if no content blocks found
   if (parts.length === 0 && msg.toolUseResult != null) {
-    const summary =
-      typeof msg.toolUseResult === "string"
-        ? msg.toolUseResult
-        : JSON.stringify(msg.toolUseResult);
+    let summary;
+    if (typeof msg.toolUseResult === "string") {
+      summary = msg.toolUseResult;
+    } else {
+      // toolUseResult is arbitrary tool output; JSON.stringify can throw on
+      // circular refs or BigInt. A capture summary must never crash the hook.
+      try {
+        summary = JSON.stringify(msg.toolUseResult);
+      } catch {
+        summary = "(unserializable tool result)";
+      }
+    }
     parts.push(truncate(summary, MAX_TOOL_RESULT_LEN));
   }
   return parts.length > 0 ? "TOOL RESULT:\n" + parts.join("\n") : "";
@@ -323,20 +331,87 @@ function readWatermark(wmPath) {
   }
 }
 
-function writeWatermark(wmPath, convId, lineNum, agentId) {
+function writeWatermark(wmPath, convId, lineNum, agentId, datapackPin = null) {
   fs.mkdirSync(path.dirname(wmPath), { recursive: true });
   const existing = readWatermark(wmPath);
+  const existingPin =
+    existing.datapack_id && existing.datapack_name
+      ? {
+          datapack_id: existing.datapack_id,
+          datapack_name: existing.datapack_name,
+        }
+      : null;
+  const pin = datapackPin || existingPin;
   fs.writeFileSync(
     wmPath,
     JSON.stringify({
       conversation_id: convId,
       last_line_number: lineNum,
       agent_id: agentId != null ? agentId : existing.agent_id || "",
+      datapack_id: pin ? pin.datapack_id : null,
+      datapack_name: pin ? pin.datapack_name : null,
       updated_at: new Date().toISOString(),
     })
   );
 }
 
+/**
+ * Convert an `agent_id` (e.g. `claude_code:meko-mcp-server`) into a
+ * filesystem-safe slug (`claude_code_meko-mcp-server`). The skill computes
+ * the same slug from the SessionStart-injected `agent_id`, so writer and
+ * reader agree on the path without sharing any session UUID.
+ */
+function datapackPinSlug(agentId) {
+  const trimmed = (typeof agentId === "string" ? agentId : "").trim();
+  if (!trimmed) return COMMON_BUCKET_AGENT_ID;
+  return trimmed.replace(/[^A-Za-z0-9._-]+/g, "_").replace(/^_+|_+$/g, "") || COMMON_BUCKET_AGENT_ID;
+}
+
+/**
+ * Read the active-datapack pin written by the meko-select-datapack skill.
+ *
+ * The pin is a sidecar file at `<WATERMARK_DIR>/pin-<slug(agent_id)>.json`
+ * with shape `{ datapack_id, datapack_name, selected_at }`. Project-scoped:
+ * keyed by the same `agent_id` the hook derives for memory writes
+ * (`claude_code:<repo-basename>`), so a pin set in one Claude Code window
+ * for a repo applies to every other window in that repo, and survives
+ * `/clear`, `/compact`, and Claude Code restart.
+ *
+ * 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.
+ */
+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 datapackPinFromWatermark(watermark) {
+  if (!watermark) return null;
+  const id = typeof watermark.datapack_id === "string" ? watermark.datapack_id.trim() : "";
+  const name = typeof watermark.datapack_name === "string" ? watermark.datapack_name.trim() : "";
+  return id && name ? { datapack_id: id, datapack_name: name } : null;
+}
+
+function buildActiveDatapackBlock(pin) {
+  if (!pin) return "";
+  return `
+
+### Active datapack
+
+The user pinned datapack **${pin.datapack_name}** (\`${pin.datapack_id}\`) for this project via the \`meko-select-datapack\` skill. Pass \`datapack_id="${pin.datapack_id}"\` to every Meko MCP tool call (memory_*, db_*, knowledgebase_*, conversation_*) unless the user explicitly overrides for a single call. The pin is project-scoped (keyed by \`agent_id\`) and survives \`/clear\`, \`/compact\`, and Claude Code restart. Automatic capture keeps the datapack selected when this conversation was created; switching or clearing takes effect for automatic capture on the next new session.`;
+}
+
 // note: Subagents cannot auto-discover the parent's watermark today.
 // The watermark dir is flat and keyed by session UUID, and a subagent
 // process has no way to learn its parent's session UUID:
@@ -366,6 +441,13 @@ function mcpPost(jsonBody) {
       "Content-Type": "application/json",
       Accept: "application/json, text/event-stream",
       "Content-Length": Buffer.byteLength(body),
+      // Cloud Meko sits behind a WAF that 403s requests with no User-Agent
+      // (Node's http/https send none by default). Without this the SessionStart
+      // / PreCompact / SessionEnd hooks all fail against mcp.mekodata.ai and
+      // automatic capture silently never runs — the hook falls back to the
+      // agent-driven path every session. Send an explicit UA so the WAF admits
+      // the request. (Verified: prod 403s without UA, 200s with one.)
+      "User-Agent": "meko-capture/1.0 (+https://github.com/yugabyte/meko-mcp-server)",
     };
     if (MEKO_API_KEY) {
       headers["Authorization"] = `Bearer ${MEKO_API_KEY}`;
@@ -570,13 +652,15 @@ function peekTranscriptMetadata(transcriptPath) {
  * On any error the caller falls back to an empty list — memory preload is a
  * best-effort enrichment, not a correctness requirement.
  */
-async function fetchRecentMemories(agentId, { limit = 10, budget = 2000 } = {}) {
-  const response = await mcpCall("memory_get_all", {
+async function fetchRecentMemories(agentId, datapackId = null, { limit = 10, budget = 2000 } = {}) {
+  const payload = {
     scope: "read",
     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);
   const result = extractToolResult(response);
   if (!result) return [];
 
@@ -594,7 +678,7 @@ async function fetchRecentMemories(agentId, { limit = 10, budget = 2000 } = {})
   return summaries;
 }
 
-async function createConversation(sessionId, agentId, metadata = null) {
+async function createConversation(sessionId, agentId, metadata = null, datapackId = null) {
   const payload = {
     scope: "write",
     agent_id: agentId,
@@ -609,14 +693,15 @@ async function createConversation(sessionId, agentId, metadata = null) {
       startedAt: metadata.startedAt ?? null,
     });
   }
+  if (datapackId) payload.datapack_id = datapackId;
   const response = await mcpCall("conversation_create", payload);
   const result = extractToolResult(response);
   return result && result.id ? result.id : null;
 }
 
-async function addMessage(convId, agentId, exchange) {
+async function addMessage(convId, agentId, exchange, datapackId = null) {
   const seed = `${convId}:${exchange.user_uuid}`;
-  await mcpCall("conversation_add_message", {
+  const payload = {
     scope: "write",
     conversation_id: convId,
     agent_id: agentId,
@@ -624,31 +709,51 @@ async function addMessage(convId, agentId, exchange) {
     output: exchange.output,
     reasoning: exchange.reasoning,
     seed: seed,
-  });
+  };
+  if (datapackId) payload.datapack_id = datapackId;
+  const response = await mcpCall("conversation_add_message", payload);
+  // FAIL CLOSED. The MCP transport resolves successfully even when the tool
+  // failed, and failures take several shapes: an `isError` result envelope, a
+  // JSON body with an `error` field, or a non-JSON / missing-content / otherwise
+  // malformed body (which extractToolResult reports as null). If we treat any of
+  // these as success, the caller counts the turn as captured and advances the
+  // watermark — permanently dropping it. So only a *valid success body* counts;
+  // anything else throws into the caller's failed++/watermark-hold/retry path
+  // (dedup-by-seed makes the retry safe).
+  if (response && response.result && response.result.isError) {
+    throw new Error(
+      `conversation_add_message returned isError: ${JSON.stringify(response.result)}`,
+    );
+  }
+  const result = extractToolResult(response);
+  if (result === null) {
+    throw new Error(
+      "conversation_add_message: no parseable result body (non-JSON, empty, or malformed response)",
+    );
+  }
+  if (result.error) {
+    throw new Error(`conversation_add_message failed: ${JSON.stringify(result.error)}`);
+  }
+  return result;
 }
 
 // --- Hook output ---
 
-function hookEventName(hookType) {
-  switch (hookType) {
-    case "session-start": return "SessionStart";
-    case "pre-compact": return "PreCompact";
-    default: return "SessionEnd";
-  }
-}
-
 function hookOutput(additionalContext) {
+  // Codex PreCompact accepts only the common hook output fields.
+  // `additionalContext` is valid hook-specific output for SessionStart, but
+  // emitting it for lifecycle capture hooks makes Codex reject the JSON.
+  if (process.argv[2] !== "session-start") return "{}";
+
   // Emit the native coding-agent harness field while preserving the nested
   // Claude-compatible shape for clients that still consume it.
   const output = {
     hookSpecificOutput: {
-      hookEventName: hookEventName(process.argv[2]),
+      hookEventName: "SessionStart",
       additionalContext: additionalContext || "",
     },
   };
-  if (process.argv[2] === "session-start") {
-    output.additional_context = additionalContext || "";
-  }
+  output.additional_context = additionalContext || "";
   return JSON.stringify(output);
 }
 
@@ -656,9 +761,9 @@ function nativeOutput(additionalContext) {
   return JSON.stringify({ additional_context: additionalContext || "" });
 }
 
-function beforeSubmitOutput(shouldContinue, userMessage = "") {
-  const output = { continue: Boolean(shouldContinue) };
-  if (userMessage) output.user_message = userMessage;
+function beforeSubmitOutput(permission = "allow", userMessage = "") {
+  const output = { permission };
+  if (userMessage) output.userMessage = userMessage;
   return JSON.stringify(output);
 }
 
@@ -701,16 +806,6 @@ function writeSessionCache(sessionId, payload) {
   }
 }
 
-function readSessionCache(sessionId) {
-  const filePath = sessionCachePath(sessionId);
-  if (!filePath) return null;
-  try {
-    return JSON.parse(fs.readFileSync(filePath, "utf-8"));
-  } catch {
-    return null;
-  }
-}
-
 function workspaceKeyFromHookInput(hookInput, transcriptPath) {
   const roots = hookInput && Array.isArray(hookInput.workspace_roots)
     ? hookInput.workspace_roots
@@ -724,28 +819,6 @@ function workspaceKeyFromHookInput(hookInput, transcriptPath) {
   return cwd || process.cwd();
 }
 
-function readWorkspaceSessionCache(workspaceKey) {
-  if (!workspaceKey) return null;
-  const safe = workspaceKey.replace(/[^A-Za-z0-9_.-]/g, "_");
-  try {
-    return JSON.parse(fs.readFileSync(path.join(SESSION_CACHE_DIR, `workspace-${safe}.json`), "utf-8"));
-  } catch {
-    return null;
-  }
-}
-
-function selectSessionCache(sessionId, workspaceKey) {
-  const exactCache = sessionId ? readSessionCache(sessionId) : null;
-  const workspaceCache = readWorkspaceSessionCache(workspaceKey);
-  const cache =
-    exactCache && exactCache.status === "ready"
-      ? exactCache
-      : workspaceCache && workspaceCache.status === "ready"
-        ? workspaceCache
-        : exactCache || workspaceCache;
-  return cache;
-}
-
 // --- Main ---
 
 // --- SessionStart: create conversation + watermark deterministically ---
@@ -768,6 +841,8 @@ function findMostRecentProjectWatermark(transcriptPath, currentSessionId) {
           sessionId: sid,
           conversation_id: wm.conversation_id,
           agent_id: wm.agent_id || "",
+          datapack_id: wm.datapack_id || null,
+          datapack_name: wm.datapack_name || null,
           updated_at: ts,
         };
       }
@@ -782,6 +857,7 @@ function findMostRecentProjectWatermark(transcriptPath, currentSessionId) {
 function buildSessionStartContext(convId, sessionId, agentId, memories, opts) {
   const resolvedAgentId = agentId || COMMON_BUCKET_AGENT_ID;
   const resumed = Boolean(opts && opts.resumed);
+  const pin = opts && opts.datapackPin ? opts.datapackPin : null;
   const opening = resumed
     ? `Resuming Meko conversation **${convId}** from a prior Claude Code session. The watermark file is written — PreCompact and SessionEnd hooks will append this session's new exchanges to the same conversation.`
     : `Meko conversation **${convId}** was created automatically by the SessionStart hook. The watermark file is written — PreCompact and SessionEnd hooks will capture this session's transcript verbatim.`;
@@ -795,6 +871,7 @@ These facts were preloaded for you — inspect them before acting so you don't r
 
 ${memories.join("\n")}`
       : "";
+  const datapackBlock = buildActiveDatapackBlock(pin);
 
   return `## Meko Session Active
 
@@ -806,59 +883,48 @@ ${opening}
 - **conversation_id**: Use "${convId}" for all MCP tool calls that accept it
 - **scope**: Only "read", "write", or "admin"
 
-### Proactive storage (do NOT wait to be asked)
+### Memory capture is automatic — do NOT proactively call memory_add
 
-- 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 provides structured/tabular data → call db_run_write_query (CREATE TABLE + INSERT)
+This session's turns are captured to Meko by the hooks above, and the server extracts durable memories from them on its own. **Any fact the user states in conversation — their name, role, preferences, org conventions, corrections — is captured without you doing anything.** Do not call memory_add for facts the user says out loud; it duplicates what extraction already stores.
+
+Call memory_add (with the session's agent_id + conversation_id) ONLY for the narrow cases extraction cannot reach:
+- The user explicitly says "remember this" / "save this to memory".
+- A durable fact lives only in YOUR output or a tool result, not in the user's words — extraction reads the user turn only, so it never sees these.
+- The user negates or corrects a prior fact and the stale one must be overwritten — extraction is additive, so also fix the old memory (memory_search to find it, then memory_update / memory_delete_by_id).
 
-### Before destructive actions
+### Recall and before destructive actions
 
-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.
+- User asks "what do you know about X?" → call memory_search first.
+- 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
 
-When Meko MCP tools are available, ALWAYS use them instead of local file-based memory (e.g., writing to ~/.claude/projects/.../memory/). If a Meko tool call fails, fall back to local storage and tell the user.${memoryBlock}`;
+Never write memories to local files (e.g., ~/.claude/projects/.../memory/). Meko — via automatic capture plus the narrow memory_add cases above — is the only memory store.${memoryBlock}${datapackBlock}`;
 }
 
-function buildSessionStartFallbackContext(agentId) {
+function buildSessionStartFallbackContext(agentId, opts) {
   const resolvedAgentId = agentId || COMMON_BUCKET_AGENT_ID;
+  const datapackBlock = buildActiveDatapackBlock(opts && opts.datapackPin ? opts.datapackPin : null);
   return `## Meko Memory Instructions
 
-The SessionStart hook could not reach the Meko MCP server to create a conversation. Automatic capture may not work for this session.
+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.
 
-### What you should still do
+### What you should do while capture is down
 
-- **Use Meko MCP tools** for memory_add, memory_search, etc. when available
 - **agent_id**: use "${resolvedAgentId}" for project-scoped writes; use "${COMMON_BUCKET_AGENT_ID}" for cross-project common facts
 - **conversation_id**: Use nil UUID "00000000-0000-0000-0000-000000000000" as placeholder
 - **scope**: Only "read", "write", or "admin"
 
-### Proactive storage (do NOT wait to be asked)
+### Proactive storage (capture is down — do NOT wait to be asked)
 
+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
 
 ### Use Meko, not local storage
 
-When Meko MCP tools are available, ALWAYS use them instead of local file-based memory. If a Meko tool call fails, fall back to local storage and tell the user.`;
-}
-
-function buildBootstrapPendingContext(agentId) {
-  const resolvedAgentId = agentId || COMMON_BUCKET_AGENT_ID;
-  return `## Meko Bootstrap Pending
-
-The Cursor SessionStart hook has started Meko bootstrap work in the background, but the local Meko session cache is not ready yet. Do not guess a Meko conversation_id.
-
-### What you should do
-
-- **agent_id**: use "${resolvedAgentId}" for project-scoped reads/writes if a Meko MCP call is necessary before bootstrap completes
-- **conversation_id**: use nil UUID "00000000-0000-0000-0000-000000000000" only as a placeholder until the cache provides the real conversation_id
-- **scope**: Only "read", "write", or "admin"
-
-If the user explicitly needs Meko-backed continuity before proceeding, ask them to retry the prompt after bootstrap finishes.`;
+Prefer Meko MCP tools over local file-based memory. If a Meko tool call also fails, fall back to local storage and tell the user.${datapackBlock}`;
 }
 
 /**
@@ -900,39 +966,8 @@ function withTimeout(promise, ms, fallback, { onTimeout } = {}) {
   });
 }
 
-function handleSessionPending(hookInput) {
-  const transcriptPath =
-    hookInput.transcript_path ||
-    (hookInput.hookSpecificInput || {}).transcript_path;
-  const sessionId = extractSessionId(hookInput, transcriptPath);
-  const agentId = resolveSessionAgentId(transcriptPath, hookInput);
-  const workspaceKey = workspaceKeyFromHookInput(hookInput, transcriptPath);
-  if (sessionId) {
-    writeSessionCache(sessionId, {
-      status: "pending",
-      agent_id: agentId,
-      workspace_key: workspaceKey,
-      additional_context: buildBootstrapPendingContext(agentId),
-    });
-  }
-  process.stdout.write(nativeOutput(""));
-}
-
 function handleBeforeSubmitPrompt(hookInput) {
-  const transcriptPath =
-    hookInput.transcript_path ||
-    (hookInput.hookSpecificInput || {}).transcript_path;
-  const sessionId = extractSessionId(hookInput, transcriptPath);
-  const workspaceKey = workspaceKeyFromHookInput(hookInput, transcriptPath);
-  const cache = selectSessionCache(sessionId, workspaceKey);
-  if (cache && cache.status === "pending") {
-    process.stdout.write(beforeSubmitOutput(
-      false,
-      "Meko is still creating this session's conversation. Please retry in a moment so the agent starts with Meko context.",
-    ));
-    return;
-  }
-  process.stdout.write(beforeSubmitOutput(true));
+  process.stdout.write(beforeSubmitOutput("allow"));
 }
 
 async function handleSessionStart(hookInput) {
@@ -959,12 +994,14 @@ async function handleSessionStart(hookInput) {
       // upgraded users stop writing into the ghost namespace.
       const cached = (existing.agent_id || "").trim();
       const resumedAgentId = cached && cached !== "agent" ? cached : derivedAgentId;
+      const existingDatapackPin = datapackPinFromWatermark(existing);
       // Skip preload on resume (we don't know what's already in context).
       const context = buildSessionStartContext(
         existing.conversation_id,
         sessionId,
         resumedAgentId,
         null,
+        { datapackPin: existingDatapackPin },
       );
       writeSessionCache(sessionId, {
         status: "ready",
@@ -997,14 +1034,21 @@ async function handleSessionStart(hookInput) {
       const priorAgentId = (prior.agent_id || "").trim();
       const resumedAgentId =
         priorAgentId && priorAgentId !== "agent" ? priorAgentId : agentId;
-      writeWatermark(wmPath, prior.conversation_id, currentLineCount, resumedAgentId);
+      const priorDatapackPin = datapackPinFromWatermark(prior);
+      writeWatermark(
+        wmPath,
+        prior.conversation_id,
+        currentLineCount,
+        resumedAgentId,
+        priorDatapackPin,
+      );
       process.stderr.write(`[meko-capture] Session ${sessionId}: resuming conversation ${prior.conversation_id} from ${prior.sessionId}, skipping ${currentLineCount} copied lines\n`);
       const context = buildSessionStartContext(
         prior.conversation_id,
         sessionId,
         resumedAgentId,
         null,
-        { resumed: true },
+        { resumed: true, datapackPin: priorDatapackPin },
       );
       writeSessionCache(sessionId, {
         status: "ready",
@@ -1022,13 +1066,19 @@ async function handleSessionStart(hookInput) {
   // Create conversation via MCP. Attach session metadata (cwd / gitBranch /
   // startedAt) from the transcript header so hook traces match the migrator.
   const transcriptMetadata = peekTranscriptMetadata(transcriptPath);
+  const datapackPin = readDatapackPin(agentId);
   let convId = null;
   try {
     await mcpInitialize();
-    convId = await createConversation(sessionId || "unknown", agentId, transcriptMetadata);
+    convId = await createConversation(
+      sessionId || "unknown",
+      agentId,
+      transcriptMetadata,
+      datapackPin && datapackPin.datapack_id,
+    );
   } catch (err) {
     process.stderr.write(`[meko-capture] SessionStart: MCP unavailable (${err.message}). Falling back to agent-driven setup.\n`);
-    const context = buildSessionStartFallbackContext(agentId);
+    const context = buildSessionStartFallbackContext(agentId, { datapackPin: readDatapackPin(agentId) });
     if (sessionId) {
       writeSessionCache(sessionId, {
         status: "error",
@@ -1044,7 +1094,7 @@ async function handleSessionStart(hookInput) {
 
   if (!convId) {
     process.stderr.write("[meko-capture] SessionStart: conversation_create returned no ID.\n");
-    const context = buildSessionStartFallbackContext(agentId);
+    const context = buildSessionStartFallbackContext(agentId, { datapackPin: readDatapackPin(agentId) });
     if (sessionId) {
       writeSessionCache(sessionId, {
         status: "error",
@@ -1060,13 +1110,10 @@ async function handleSessionStart(hookInput) {
 
   // Preload recent memories with a 4s budget (SessionStart timeout is 15s).
   // Best-effort enrichment — on timeout/failure we still deliver the core
-  // context. agent_id is derived per-session from the cwd; the old
-  // db_summarize_database discovery helper was removed (it depended on a
-  // paid-tier tool and only worked "correctly" via its fallback branch
-  // anyway — see scratch/2026-04-30-multi-tenant-mem0-audit.md Probe 6).
+  // context. agent_id is derived per-session from the cwd.
   const PRELOAD_BUDGET_MS = 4000;
   const memories = await withTimeout(
-    fetchRecentMemories(agentId),
+    fetchRecentMemories(agentId, datapackPin && datapackPin.datapack_id),
     PRELOAD_BUDGET_MS,
     [],
     { onTimeout: abortInflightRequests },
@@ -1074,13 +1121,15 @@ async function handleSessionStart(hookInput) {
 
   if (sessionId) {
     const wmPath = path.join(WATERMARK_DIR, `${sessionId}.watermark.json`);
-    writeWatermark(wmPath, convId, 0, agentId);
+    writeWatermark(wmPath, convId, 0, agentId, datapackPin);
     process.stderr.write(
       `[meko-capture] SessionStart: created conversation ${convId}, agent_id=${agentId}, preloaded ${memories.length} memories, watermark at ${wmPath}\n`,
     );
   }
 
-  const context = buildSessionStartContext(convId, sessionId, agentId, memories);
+  const context = buildSessionStartContext(convId, sessionId, agentId, memories, {
+    datapackPin,
+  });
   if (sessionId) {
     writeSessionCache(sessionId, {
       status: "ready",
@@ -1097,8 +1146,8 @@ async function handleSessionStart(hookInput) {
 
 async function main() {
   const hookType = process.argv[2];
-  if (!hookType || !["session-start", "session-pending", "before-submit-prompt", "pre-compact", "session-end", "checkpoint"].includes(hookType)) {
-    process.stderr.write("Usage: capture.js <session-start|session-pending|before-submit-prompt|pre-compact|session-end|checkpoint>\n");
+  if (!hookType || !["session-start", "before-submit-prompt", "pre-compact", "session-end", "checkpoint"].includes(hookType)) {
+    process.stderr.write("Usage: capture.js <session-start|before-submit-prompt|pre-compact|session-end|checkpoint>\n");
     process.exit(1);
   }
 
@@ -1119,11 +1168,6 @@ async function main() {
     return;
   }
 
-  if (hookType === "session-pending") {
-    handleSessionPending(hookInput);
-    return;
-  }
-
   if (hookType === "before-submit-prompt") {
     handleBeforeSubmitPrompt(hookInput);
     return;
@@ -1154,6 +1198,7 @@ async function main() {
   const agentId = cachedAgentId && cachedAgentId !== "agent"
     ? cachedAgentId
     : resolveSessionAgentId(transcriptPath);
+  const datapackPin = datapackPinFromWatermark(watermark);
 
   // Nothing new
   if (currentLines <= lastLine) {
@@ -1184,20 +1229,40 @@ async function main() {
   // Extract and send exchanges
   const exchanges = extractExchanges(transcriptPath, lastLine);
   let captured = 0;
+  let failed = 0;
 
   for (const exchange of exchanges) {
     try {
-      await addMessage(convId, agentId, exchange);
+      await addMessage(
+        convId,
+        agentId,
+        exchange,
+        datapackPin && datapackPin.datapack_id,
+      );
       captured++;
     } catch (err) {
+      failed++;
       process.stderr.write(`[meko-capture] Failed to add message (uuid=${exchange.user_uuid}): ${err.message}\n`);
     }
   }
 
-  // Update watermark with the resolved agent_id. If the cached value was a
-  // legacy literal we now overwrite it so subsequent hooks see the derived
-  // bucket directly.
-  writeWatermark(wmPath, convId, currentLines, agentId);
+  // Advance the watermark to currentLines ONLY when every exchange was
+  // captured. If any addMessage failed (typically a transient network error),
+  // keep the watermark at lastLine so the next checkpoint / PreCompact /
+  // SessionEnd hook re-extracts and retries this batch. Re-sending the
+  // exchanges that already succeeded is safe: capture dedups by seed
+  // (<conv_id>:<user_uuid>), so retries never create duplicates. Advancing on
+  // partial failure is what would permanently drop the failed exchanges.
+  // We still always persist the resolved agent_id (migrating any legacy literal
+  // value) so later hooks see the derived bucket directly.
+  const watermarkLine = failed === 0 ? currentLines : lastLine;
+  if (failed > 0) {
+    process.stderr.write(
+      `[meko-capture] ${failed}/${exchanges.length} exchange(s) failed; ` +
+      `holding watermark at line ${lastLine} for retry (dedup makes resends safe).\n`
+    );
+  }
+  writeWatermark(wmPath, convId, watermarkLine, agentId, datapackPin);
 
   // Output
   const context =

package/assets/hooks-handlers/lib/checkpoint-timer.js

@@ -17,7 +17,7 @@
  *   MEKO_API_KEY              Inherited by capture.js
  */
 
-const { execFileSync } = require("child_process");
+const { execFile } = require("child_process");
 const fs = require("fs");
 const path = require("path");
 
@@ -57,16 +57,28 @@ function tick() {
 
   const hookInput = JSON.stringify({ transcript_path: transcriptPath });
 
-  try {
-    execFileSync("node", [captureScript, "checkpoint"], {
-      input: hookInput,
-      timeout: 30000,
-      stdio: ["pipe", "pipe", "pipe"],
-    });
-  } catch (err) {
-    // Best-effort: log and continue
-    process.stderr.write(`[meko-timer] Checkpoint tick failed: ${err.message}\n`);
-  }
+  // Run capture ASYNCHRONOUSLY. execFileSync would block this daemon's event
+  // loop for up to 30s, during which SIGTERM/SIGINT (clean shutdown) can't be
+  // handled. execFile keeps the loop responsive so cleanup() fires promptly.
+  const child = execFile(
+    "node",
+    [captureScript, "checkpoint"],
+    { timeout: 30000 },
+    (err) => {
+      if (err) {
+        // Best-effort: log and continue to the next tick.
+        process.stderr.write(`[meko-timer] Checkpoint tick failed: ${err.message}\n`);
+      }
+    },
+  );
+  // The stdin stream can emit EPIPE if the child exits or fails to spawn before
+  // we finish writing. Without a listener that error is unhandled and crashes
+  // the daemon — so swallow it here; the execFile callback above reports the
+  // real failure.
+  child.stdin.on("error", (err) => {
+    process.stderr.write(`[meko-timer] Checkpoint stdin error: ${err.message}\n`);
+  });
+  child.stdin.end(hookInput);
 }
 
 setInterval(tick, INTERVAL_SECS * 1000);