@yugabytedb/meko-mcp 2.0.0 → 2.1.0

package/README.md

@@ -108,7 +108,7 @@ Each client is installed sequentially. A failure on one does not abort the other
 
 ```bash
 npx @yugabytedb/meko-mcp \
-  --url https://your-mcp.mekodev.com/mcp \
+  --url https://mcp.mekodata.ai/mcp \
   --api-key "$MEKO_API_KEY" \
   --yes
 ```
@@ -121,7 +121,7 @@ The installer performs up to 5 steps (some are skippable via flags):
 |------|--------|------------------------|
 | 1 | Register MCP server | `claude mcp add meko <url> --transport http --scope user` (with `-H "Authorization: Bearer <key>"` for cloud) |
 | 2 | Set hook environment vars | Writes `MEKO_MCP_URL` and `MEKO_API_KEY` into `~/.claude/settings.json` under the `env` key. Also prunes any stale Meko hook entries in `settings.json.hooks` that point at a prior install path (e.g. a previous `npx` cache or homebrew-global copy) so only the current install's hooks fire. |
-| 3 | Register plugin marketplace | `claude plugin marketplace add yugabyte/meko-mcp-server --scope user` |
+| 3 | Register public plugin marketplace | `claude plugin marketplace add https://github.com/yugabyte/meko-skills.git --scope user` |
 | 4 | Install skills plugin | `claude plugin install meko-agent-skills --scope user` |
 | 5 | Validate setup | Config check via `claude mcp list`, MCP `initialize` handshake, `tools/list` verification, and a canary `datapack_list` call |
 
@@ -173,7 +173,7 @@ Usage:
 | Flag | Description | Default |
 |------|-------------|---------|
 | `--client <list>` | Target client(s): one or more of `claude-code`, `claude-desktop`, `cursor`, `codex`. Comma-separated, or `all`. `codex` covers both the OpenAI Codex CLI and the Codex Desktop App (they share `~/.codex/config.toml`). | `claude-code` |
-| `--url <url>` | MCP server URL (from app.mekodev.com > Datapacks > Connect) | _(interactive prompt)_ |
+| `--url <url>` | MCP server URL (from cloud.mekodata.ai > Datapacks > Connect) | Shared existing endpoint, otherwise production; conflicts prompt or require `--url` under `--yes` |
 | `--api-key <key>` | API key for Cloud Meko authentication. If a Cloud `--url` is supplied without this flag, the installer falls back to `$MEKO_API_KEY`, then to an interactive prompt on a TTY. Only fails hard when running under `--yes` or with no TTY attached. | _(interactive prompt or `$MEKO_API_KEY` env)_ |
 | `--local` | Use local Meko at `http://localhost:8000/mcp` (no API key needed) | `false` |
 | `--scope <scope>` | Config scope: `user` or `project` (`claude-desktop` uses user scope config) | `user` |
@@ -359,7 +359,7 @@ Cursor previously had a hybrid hook mode that also wrote Claude-compatible hooks
 
 | | Cloud Meko | Local Meko |
 |---|-----------|-----------|
-| **URL** | Provided by app.mekodev.com > Datapacks > Connect | `http://localhost:8000/mcp` |
+| **URL** | `https://mcp.mekodata.ai/mcp` (or the endpoint shown by cloud.mekodata.ai) | `http://localhost:8000/mcp` |
 | **Authentication** | Requires `--api-key` or `$MEKO_API_KEY` env var | None |
 | **MCP registration** | Includes `-H "Authorization: Bearer <key>"` header | No auth header |
 | **Hook env vars** | Both `MEKO_MCP_URL` and `MEKO_API_KEY` written to settings | Only `MEKO_MCP_URL` written |
@@ -505,6 +505,31 @@ which claude
 claude --version
 ```
 
+### MCP server `meko` already exists in the user config
+
+```
+[1/4] Failed to register MCP server.
+MCP server meko already exists in the user config
+Install for claude-code failed: MCP server registration failed.
+```
+
+Claude Code's `claude mcp add` refuses to overwrite an existing registration, so a re-run — or a previous install that failed partway through — aborts at step 1. Remove the stale entry, then re-run the installer:
+
+```bash
+claude mcp list                     # confirm the "meko" entry and which scope it is on
+claude mcp remove meko --scope user # or --scope local / --scope project, matching what `list` showed
+claude mcp list                     # confirm it is gone
+npx @yugabytedb/meko-mcp@latest     # re-run the installer
+```
+
+If `claude mcp remove` errors or you want to edit the file directly, the user-scope config lives at `~/.claude.json` — open it, find the `"mcpServers"` block, and delete the `"meko": { ... }` entry. Claude Desktop and Claude Code keep **separate** configs, so a clean Desktop install does not imply a clean Code install.
+
+Logs worth collecting before filing a bug:
+
+- **Installer log** — `ls -lt ~/.meko*/logs 2>/dev/null; ls -lt /tmp/meko-installer* 2>/dev/null` — share the newest file.
+- **Claude Code MCP log** (macOS) — `ls -lt ~/Library/Caches/claude-cli-nodejs/*/mcp-logs-meko/ 2>/dev/null` — most recent `*.txt` shows the registration attempt and any stderr from the spawned process.
+- **Current config snippet** — `grep -A 20 '"meko"' ~/.claude.json` — confirms what state Claude Code was in when the install was attempted.
+
 ### Connection refused
 
 ```
@@ -537,7 +562,7 @@ The MCP server is enforcing strict Streamable HTTP compliance: clients must adve
 Server returned 401. Verify your API key is correct and has not expired.
 ```
 
-- Confirm the API key at app.mekodev.com > Datapacks > Connect.
+- Confirm the API key at cloud.mekodata.ai > Datapacks > Connect.
 - If using `$MEKO_API_KEY` env var, ensure it is exported in the current shell.
 - Confirm the key environment matches the URL: PATs minted on `app.mekodev.com` only validate against `mcp.mekodev.com`; PATs minted on `cloud.mekodata.ai` only validate against `mcp.mekodata.ai`.
 - The installer normalizes API keys (trims surrounding whitespace and a single matching pair of quotes) so a paste with a trailing newline or a literal `"…"` from a `.env` file is fine — but your raw shell variable might still be contaminated. Echo it (`echo "[$MEKO_API_KEY]"`) and check the brackets bracket the key tightly with no extra characters.
@@ -714,7 +739,7 @@ npm run test:integration
 
 # Cloud round-trip tests (opt-in; regression coverage for MEKO-20).
 # Requires credentials in the shell:
-export MEKO_TEST_CLOUD_URL=https://<your-mcp>.mekodev.com/mcp
+export MEKO_TEST_CLOUD_URL=https://mcp.mekodata.ai/mcp
 export MEKO_TEST_API_KEY=<your-cloud-api-key>
 npm run test:integration:cloud
 

package/assets/hooks-handlers/codex-session-end.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+#
+# Codex SessionEnd hook.
+#
+# Codex caps SessionEnd hooks at three seconds. The foreground invocation
+# therefore persists the hook input, starts a detached worker, and exits
+# immediately. The worker reuses the shared capture.js implementation and
+# removes the persisted input when capture finishes.
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+CAPTURE_SCRIPT="$SCRIPT_DIR/lib/capture.js"
+STATE_DIR="${MEKO_WATERMARK_DIR:-$HOME/.claude/meko-capture}"
+JOB_DIR="$STATE_DIR/session-end-jobs"
+LOG_FILE="$STATE_DIR/session-end.log"
+
+run_worker() {
+  JOB_FILE="${1:-}"
+  if [ -z "$JOB_FILE" ] || [ ! -f "$JOB_FILE" ]; then
+    printf '[meko-capture] Codex SessionEnd worker received no readable job file\n' >&2
+    return 1
+  fi
+
+  trap 'rm -f "$JOB_FILE"' EXIT HUP INT TERM
+  node "$CAPTURE_SCRIPT" session-end <"$JOB_FILE"
+}
+
+if [ "${1:-}" = "--worker" ]; then
+  run_worker "${2:-}"
+  exit $?
+fi
+
+# Hook input can contain local paths and session metadata. Keep the spool
+# directory and files private to the current user.
+umask 077
+mkdir -p "$JOB_DIR"
+JOB_FILE="$(mktemp "$JOB_DIR/session-end.XXXXXX")" || {
+  printf '[meko-capture] Codex SessionEnd could not create a job file\n' >&2
+  printf '{}'
+  exit 0
+}
+
+if ! cat >"$JOB_FILE"; then
+  rm -f "$JOB_FILE"
+  printf '[meko-capture] Codex SessionEnd could not persist hook input\n' >&2
+  printf '{}'
+  exit 0
+fi
+
+# Stop the periodic timer before handing final capture to the worker. This is
+# deliberately best-effort: a missing or stale PID must not block SessionEnd.
+TRANSCRIPT_PATH="$(node - "$JOB_FILE" <<'NODE' 2>/dev/null
+const fs = require("fs");
+const d = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
+const p = d.transcript_path || (d.hookSpecificInput || {}).transcript_path || "";
+process.stdout.write(p);
+NODE
+)"
+
+if [ -n "$TRANSCRIPT_PATH" ]; then
+  SESSION_ID="$(basename "$TRANSCRIPT_PATH" .jsonl)"
+  PID_FILE="$STATE_DIR/${SESSION_ID}.timer.pid"
+  if [ -f "$PID_FILE" ]; then
+    kill "$(cat "$PID_FILE")" 2>/dev/null || true
+    rm -f "$PID_FILE"
+  fi
+fi
+
+# Redirect every inherited descriptor before returning to Codex. nohup keeps
+# the worker alive after the hook shell exits; disown is available in bash but
+# remains best-effort for non-interactive shells.
+nohup bash "$0" --worker "$JOB_FILE" \
+  </dev/null >>"$LOG_FILE" 2>&1 &
+WORKER_PID=$!
+disown "$WORKER_PID" 2>/dev/null || true
+
+printf '{}'

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

@@ -367,6 +367,45 @@ function datapackPinSlug(agentId) {
   return trimmed.replace(/[^A-Za-z0-9._-]+/g, "_").replace(/^_+|_+$/g, "") || COMMON_BUCKET_AGENT_ID;
 }
 
+function captureErrorPath(agentId) {
+  return path.join(WATERMARK_DIR, `last-capture-error-${datapackPinSlug(agentId)}.json`);
+}
+
+function readCaptureError(agentId) {
+  try {
+    const error = JSON.parse(fs.readFileSync(captureErrorPath(agentId), "utf-8"));
+    return error && typeof error === "object" ? error : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeCaptureError(agentId, error) {
+  try {
+    fs.mkdirSync(WATERMARK_DIR, { recursive: true });
+    fs.writeFileSync(
+      captureErrorPath(agentId),
+      JSON.stringify({
+        ...error,
+        agent_id: agentId,
+        occurred_at: new Date().toISOString(),
+      }),
+    );
+  } catch (err) {
+    process.stderr.write(`[meko-capture] Could not persist capture error: ${err.message}\n`);
+  }
+}
+
+function clearCaptureError(agentId) {
+  try {
+    fs.unlinkSync(captureErrorPath(agentId));
+  } catch (err) {
+    if (err && err.code !== "ENOENT") {
+      process.stderr.write(`[meko-capture] Could not clear capture error: ${err.message}\n`);
+    }
+  }
+}
+
 /**
  * Read the active-datapack pin written by the meko-select-datapack skill.
  *
@@ -409,7 +448,7 @@ function buildActiveDatapackBlock(pin) {
 
 ### 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.`;
+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 that accepts it (memory_*, knowledgebase_search, conversation_*, artifact_*) 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.
@@ -470,6 +509,16 @@ function mcpPost(jsonBody) {
         res.on("data", (chunk) => (data += chunk));
         res.on("end", () => {
           inflightRequests.delete(req);
+          if (res.statusCode >= 400) {
+            const snippet = data.trim().replace(/\s+/g, " ").slice(0, 200);
+            const err = new Error(
+              `MCP HTTP ${res.statusCode}${snippet ? `: ${snippet}` : ""}`,
+            );
+            err.statusCode = res.statusCode;
+            err.responseBody = data.slice(0, 1000);
+            reject(err);
+            return;
+          }
           // Notifications return 202/204 with no body — that's OK
           if (!data.trim()) {
             resolve({ body: null, headers: res.headers });
@@ -535,6 +584,51 @@ 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]);
+  }
+
+  if (persistentStatus) {
+    return {
+      code: `http_${persistentStatus}`,
+      reason: `Meko rejected capture with HTTP ${persistentStatus}`,
+    };
+  }
+
+  const persistentPatterns = [
+    ["free_tier_limit_reached", /free[_\s-]?tier.*limit|free_tier_limit_reached/],
+    ["quota_exceeded", /quota[_\s-]?(reached|exceeded)|(?:reached|exceeded).*quota/],
+    ["usage_limit_reached", /usage[_\s-]?limit[_\s-]?(reached|exceeded)/],
+    ["plan_limit_reached", /plan[_\s-]?limit[_\s-]?(reached|exceeded)/],
+    ["payment_required", /payment[_\s-]?required/],
+    ["subscription_required", /subscription[_\s-]?(required|inactive|expired)/],
+    ["entitlement_denied", /entitlement.*(denied|required|missing)|(?:denied|required|missing).*entitlement/],
+  ];
+  for (const [code, pattern] of persistentPatterns) {
+    if (pattern.test(normalized)) {
+      const reasons = {
+        free_tier_limit_reached: "the free-tier capture limit was reached",
+        quota_exceeded: "the capture quota was exceeded",
+        usage_limit_reached: "the capture usage limit was reached",
+        plan_limit_reached: "the current plan's capture limit was reached",
+        payment_required: "capture requires payment",
+        subscription_required: "capture requires an active subscription",
+        entitlement_denied: "the account is not entitled to capture conversations",
+      };
+      return { code, reason: reasons[code] };
+    }
+  }
+  return null;
+}
+
 /**
  * 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
@@ -654,7 +748,6 @@ function peekTranscriptMetadata(transcriptPath) {
  */
 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,
@@ -680,7 +773,6 @@ async function fetchRecentMemories(agentId, datapackId = null, { limit = 10, bud
 
 async function createConversation(sessionId, agentId, metadata = null, datapackId = null) {
   const payload = {
-    scope: "write",
     agent_id: agentId,
     title: "Claude Code session (auto-captured)",
     session_id: sessionId,
@@ -702,7 +794,6 @@ async function createConversation(sessionId, agentId, metadata = null, datapackI
 async function addMessage(convId, agentId, exchange, datapackId = null) {
   const seed = `${convId}:${exchange.user_uuid}`;
   const payload = {
-    scope: "write",
     conversation_id: convId,
     agent_id: agentId,
     input: exchange.input,
@@ -745,14 +836,20 @@ function hookOutput(additionalContext) {
   // 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.
+  // Codex rejects unknown top-level fields, so its SessionStart response must
+  // contain only the hook-specific output defined by the Codex wire schema.
   const output = {
     hookSpecificOutput: {
       hookEventName: "SessionStart",
       additionalContext: additionalContext || "",
     },
   };
+  if (process.env.MEKO_HOOK_CLIENT === "codex") {
+    return JSON.stringify(output);
+  }
+
+  // Preserve the native coding-agent harness field for clients that consume
+  // it alongside the nested Claude-compatible shape.
   output.additional_context = additionalContext || "";
   return JSON.stringify(output);
 }
@@ -858,9 +955,17 @@ function buildSessionStartContext(convId, sessionId, agentId, memories, opts) {
   const resolvedAgentId = agentId || COMMON_BUCKET_AGENT_ID;
   const resumed = Boolean(opts && opts.resumed);
   const pin = opts && opts.datapackPin ? opts.datapackPin : null;
+  const captureError = opts && opts.captureError ? opts.captureError : null;
   const opening = resumed
-    ? `Resuming Meko conversation **${convId}** from a prior Claude Code session. The watermark file is written — PreCompact and SessionEnd hooks will 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.`;
+    ? `Resuming Meko conversation **${convId}** from a prior Claude Code session. The watermark file is written — PreCompact and SessionEnd hooks will attempt to append this session's new exchanges to the same conversation.`
+    : `Meko conversation **${convId}** was created automatically by the SessionStart hook. The watermark file is written — PreCompact and SessionEnd hooks are configured to capture this session's transcript.`;
+  const captureWarning = captureError
+    ? `
+
+### Automatic capture warning — tell the user
+
+The last automatic capture attempt was persistently rejected because ${captureError.reason || "Meko rejected the write"}. **Do not claim that this session's turns are being saved.** The hook kept ${Number(captureError.held_exchanges || captureError.failed_exchanges) || 1} exchange(s) queued for retry instead of dropping them. Tell the user that automatic conversation capture is currently unhealthy and include this reason. This warning remains until a later hook write succeeds.`
+    : "";
   const memoryBlock =
     Array.isArray(memories) && memories.length > 0
       ? `
@@ -876,16 +981,16 @@ ${memories.join("\n")}`
   return `## Meko Session Active
 
 ${opening}
+${captureWarning}
 
 ### What you MUST do with Meko tools
 
 - **agent_id**: use "${resolvedAgentId}" verbatim for every Meko MCP tool call in this session. This was derived from the cwd as \`<client>:<repo-basename>\` so memories stay scoped to this project. For genuinely cross-project facts (user identity, global preferences) pass agent_id="${COMMON_BUCKET_AGENT_ID}" — that's the common bucket any agent can read regardless of project.
 - **conversation_id**: Use "${convId}" for all MCP tool calls that accept it
-- **scope**: Only "read", "write", or "admin"
 
-### Memory capture is automatic — do NOT proactively call memory_add
+### Memory capture is automatic only when hook delivery succeeds — do NOT proactively call memory_add
 
-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.
+The hooks above attempt to capture this session's turns, and the server extracts durable memories from successfully delivered turns on its own. Do not call memory_add for facts the user says out loud; when hook delivery succeeds, that would duplicate what extraction already stores. If the warning above is present, tell the user instead of pretending an explicit memory write will bypass the same server rejection.
 
 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".
@@ -913,7 +1018,6 @@ The SessionStart hook could not reach the Meko MCP server to create a conversati
 
 - **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 (capture is down — do NOT wait to be asked)
 
@@ -1001,7 +1105,10 @@ async function handleSessionStart(hookInput) {
         sessionId,
         resumedAgentId,
         null,
-        { datapackPin: existingDatapackPin },
+        {
+          datapackPin: existingDatapackPin,
+          captureError: readCaptureError(resumedAgentId),
+        },
       );
       writeSessionCache(sessionId, {
         status: "ready",
@@ -1048,7 +1155,11 @@ async function handleSessionStart(hookInput) {
         sessionId,
         resumedAgentId,
         null,
-        { resumed: true, datapackPin: priorDatapackPin },
+        {
+          resumed: true,
+          datapackPin: priorDatapackPin,
+          captureError: readCaptureError(resumedAgentId),
+        },
       );
       writeSessionCache(sessionId, {
         status: "ready",
@@ -1129,6 +1240,7 @@ async function handleSessionStart(hookInput) {
 
   const context = buildSessionStartContext(convId, sessionId, agentId, memories, {
     datapackPin,
+    captureError: readCaptureError(agentId),
   });
   if (sessionId) {
     writeSessionCache(sessionId, {
@@ -1210,6 +1322,20 @@ async function main() {
   try {
     await mcpInitialize();
   } catch (err) {
+    const persistent = classifyPersistentCaptureFailure(err);
+    if (persistent) {
+      const pendingExchanges = extractExchanges(transcriptPath, lastLine).length;
+      writeCaptureError(agentId, {
+        code: persistent.code,
+        reason: persistent.reason,
+        held_exchanges: pendingExchanges || 1,
+        session_id: sessionId,
+        conversation_id: convId || null,
+      });
+      process.stderr.write(
+        `[meko-capture] Persistent capture rejection recorded for the next SessionStart: ${persistent.reason}.\n`,
+      );
+    }
     process.stderr.write(`[meko-capture] Failed to initialize MCP session: ${err.message}\n`);
     process.stdout.write(hookOutput(""));
     return;
@@ -1230,6 +1356,7 @@ async function main() {
   const exchanges = extractExchanges(transcriptPath, lastLine);
   let captured = 0;
   let failed = 0;
+  const persistentFailures = [];
 
   for (const exchange of exchanges) {
     try {
@@ -1242,10 +1369,32 @@ async function main() {
       captured++;
     } catch (err) {
       failed++;
+      const persistent = classifyPersistentCaptureFailure(err);
+      if (persistent) persistentFailures.push(persistent);
       process.stderr.write(`[meko-capture] Failed to add message (uuid=${exchange.user_uuid}): ${err.message}\n`);
     }
   }
 
+  if (persistentFailures.length > 0) {
+    const persistent = persistentFailures[0];
+    writeCaptureError(agentId, {
+      code: persistent.code,
+      reason: persistent.reason,
+      // Every failed exchange remains held by the watermark, including any
+      // transient failures that happened in the same persistently rejected batch.
+      held_exchanges: failed,
+      session_id: sessionId,
+      conversation_id: convId,
+    });
+    process.stderr.write(
+      `[meko-capture] Persistent capture rejection recorded for the next SessionStart: ${persistent.reason}.\n`,
+    );
+  } else if (captured > 0) {
+    // A successful write proves the prior persistent rejection has cleared.
+    // Transient failures may still hold this batch's watermark independently.
+    clearCaptureError(agentId);
+  }
+
   // Advance the watermark to currentLines ONLY when every exchange was
   // captured. If any addMessage failed (typically a transient network error),
   // keep the watermark at lastLine so the next checkpoint / PreCompact /

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

@@ -12,6 +12,11 @@
  *
  * Environment:
  *   MEKO_CHECKPOINT_INTERVAL  Seconds between ticks (default: 600)
+ *   MEKO_TIMER_MAX_AGE        Hard self-exit age in seconds (default: 86400 = 24h)
+ *   MEKO_TIMER_IDLE_EXIT      Self-exit after the transcript is untouched this
+ *                             long, in seconds (default: 7200 = 2h)
+ *   MEKO_TIMER_STARTUP_GRACE  Wait this long for the transcript to appear
+ *                             before self-exiting (default: 1800 = 30min)
  *   MEKO_WATERMARK_DIR        Watermark directory (default: ~/.claude/meko-capture)
  *   MEKO_MCP_URL              Inherited by capture.js
  *   MEKO_API_KEY              Inherited by capture.js
@@ -22,6 +27,14 @@ const fs = require("fs");
 const path = require("path");
 
 const INTERVAL_SECS = parseInt(process.env.MEKO_CHECKPOINT_INTERVAL || "600", 10);
+// Self-exit backstops so an orphaned daemon (its pid file removed out of band,
+// a missed SessionEnd, a blocked SIGTERM) cannot tick forever. Both are
+// generous enough not to interrupt a genuinely long, active session.
+const MAX_AGE_SECS = parseInt(process.env.MEKO_TIMER_MAX_AGE, 10) || 86400;
+const IDLE_EXIT_SECS = parseInt(process.env.MEKO_TIMER_IDLE_EXIT, 10) || 7200;
+const STARTUP_GRACE_SECS =
+  parseInt(process.env.MEKO_TIMER_STARTUP_GRACE, 10) || 1800;
+const startedAt = Date.now();
 const WATERMARK_DIR =
   process.env.MEKO_WATERMARK_DIR ||
   path.join(process.env.HOME || "~", ".claude", "meko-capture");
@@ -49,8 +62,37 @@ process.on("SIGTERM", cleanup);
 process.on("SIGINT", cleanup);
 
 function tick() {
-  // Skip if transcript doesn't exist (session ended but we weren't killed yet)
-  if (!fs.existsSync(transcriptPath)) {
+  // Self-exit backstop: never outlive the hard max age. Guards against orphans
+  // whose pid file was removed out of band (so session-end.sh can't kill them)
+  // or whose SessionEnd never fired (force-quit / terminal closed).
+  if (Date.now() - startedAt >= MAX_AGE_SECS * 1000) {
+    process.stderr.write(
+      `[meko-timer] Max age (${MAX_AGE_SECS}s) reached; self-exiting to avoid orphan.\n`,
+    );
+    cleanup();
+    return;
+  }
+
+  // Exit if the transcript is gone (session ended but we weren't killed yet).
+  // SessionStart can precede transcript creation by up to 20 minutes, so a
+  // missing file during the startup grace period is expected.
+  let stat;
+  try {
+    stat = fs.statSync(transcriptPath);
+  } catch {
+    if (Date.now() - startedAt < STARTUP_GRACE_SECS * 1000) {
+      return;
+    }
+    cleanup();
+    return;
+  }
+
+  // Exit if the transcript has been idle far longer than a checkpoint window —
+  // the session is effectively over even though we were never signalled.
+  if (Date.now() - stat.mtimeMs >= IDLE_EXIT_SECS * 1000) {
+    process.stderr.write(
+      `[meko-timer] Transcript idle > ${IDLE_EXIT_SECS}s; self-exiting.\n`,
+    );
     cleanup();
     return;
   }

package/assets/hooks-handlers/session-end.sh

@@ -21,6 +21,16 @@ if [ -n "$TRANSCRIPT_PATH" ]; then
     kill "$(cat "$PID_FILE")" 2>/dev/null || true
     rm -f "$PID_FILE"
   fi
+  # Fallback: the pid file can go missing while the daemon lives (removed out of
+  # band, a missed/blocked signal). Match the running checkpoint-timer.js by the
+  # clean session id rather than the absolute transcript path, which may contain
+  # regex metacharacters that make pgrep fail or match incorrectly.
+  if command -v pgrep >/dev/null 2>&1; then
+    for pid in $(pgrep -f "checkpoint-timer.js .*${SESSION_ID}" 2>/dev/null); do
+      [ "$pid" = "$$" ] && continue
+      kill "$pid" 2>/dev/null || true
+    done
+  fi
 fi
 
 # Run final capture

package/assets/hooks-handlers/session-start.sh

@@ -16,7 +16,14 @@ TRANSCRIPT_PATH="$(printf '%s' "$HOOK_INPUT" | node -e '
 # Spawn background checkpoint timer (periodic capture without interrupting the agent).
 # Send the daemon's stderr to a log file instead of /dev/null so startup
 # failures and crashes are diagnosable; stdout is still discarded.
-if [ -n "$TRANSCRIPT_PATH" ] && [ -f "$TRANSCRIPT_PATH" ]; then
+#
+# NOTE: we deliberately do NOT gate on [ -f "$TRANSCRIPT_PATH" ]. SessionStart
+# fires before Claude Code writes the transcript .jsonl, so that file usually
+# does not exist yet at hook time (measured gaps of +3s to +20min). Gating on
+# its existence meant the timer never spawned and the whole session went
+# uncaptured. checkpoint-timer.js self-guards a missing transcript on each
+# tick(), so spawning unconditionally (when the path is known) is safe.
+if [ -n "$TRANSCRIPT_PATH" ]; then
   MEKO_LOG_DIR="${MEKO_WATERMARK_DIR:-$HOME/.claude/meko-capture}"
   mkdir -p "$MEKO_LOG_DIR"
   nohup node "$SCRIPT_DIR/lib/checkpoint-timer.js" "$TRANSCRIPT_PATH" \