eagle-mem 4.12.0 → 4.12.1

package/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to the **Eagle Mem** project are documented here.
 
 ---
 
+## v4.12.1 Deploy-Path Fixes for v4.12.0
+
+Two install/update-path bugs that defeated or destabilized the v4.12.0 rollout:
+
+- **CLAUDE.md capture doctrine never updated (critical)**: `eagle_patch_claude_md` detected the outdated section with `grep -qF 'request: \[what user asked\] | completed:'`. Under `grep -F` the backslashes are literal, so the pattern never matched the real `[what user asked]` text — the installed CLAUDE.md kept telling agents to emit `<eagle-summary>`, silently defeating the whole clean-capture feature. Detection now keys on the *absence* of the current section's unique `session save --session-id` sentinel, so any pre-CLI-first section is rewritten (and the rewrite is idempotent). New regression test `tests/test_claude_md_capture_doctrine.sh`.
+- **Migration runner fail-open on lock**: `db/migrate.sh`'s "already applied?" guard ran a fresh `sqlite3` without `busy_timeout`; a momentary `SQLITE_BUSY` (a hook touching the DB mid-update) made it exit non-zero, the `|| echo 0` fail-open then re-ran an already-applied migration and the body errored with `duplicate column` / UNIQUE-constraint failures. The guard now sets `busy_timeout=5000` and waits for the lock instead of guessing.
+- Registered `tests/test_clean_session_capture.sh` and the new doctrine test in `scripts/test.sh` (both were running only when invoked directly).
+
+---
+
 ## v4.12.0 Clean, Branded Session Capture
 
 Session endings are now clean across every agent — no more raw `<eagle-summary>` XML blocks in the visible reply.

package/db/migrate.sh

@@ -33,8 +33,14 @@ run_migration() {
     local name="$1"
     local file="$2"
 
+    # The guard query MUST set busy_timeout: without it a momentary SQLITE_BUSY
+    # (a hook touching the DB mid-update) makes sqlite3 exit non-zero, the `|| echo 0`
+    # fail-open then re-runs an already-applied migration and the body explodes with
+    # "duplicate column" / UNIQUE-constraint errors. busy_timeout makes the guard wait
+    # for the lock instead of guessing. tail -n1 drops the PRAGMA echo line.
     local already_applied
-    already_applied=$("$SQLITE_BIN" "$DB" "SELECT COUNT(*) FROM _migrations WHERE name = '$name';" 2>/dev/null || echo "0")
+    already_applied=$("$SQLITE_BIN" "$DB" "PRAGMA busy_timeout=5000; SELECT COUNT(*) FROM _migrations WHERE name = '$name';" 2>/dev/null | tail -n1)
+    [ -z "$already_applied" ] && already_applied="0"
 
     if [ "$already_applied" = "0" ]; then
         # Strip PRAGMAs from migration body (they can't run inside transactions

package/docs/agent-compatibility/claude-code.md

@@ -28,6 +28,7 @@ Last verified: 2026-06-10
 - The installer adds `permissions.allow: ["Bash(eagle-mem session save:*)"]` to Claude settings so the capture runs without a permission prompt. The instruction must use that exact command prefix (no leading path, no `cd &&`) for the permission to match.
 - Agent-authored captures are authoritative (`capture_source = agent`). The `Stop` hook still parses any `<eagle-summary>` block for backward compatibility, but when an agent row already exists its heuristics only fill empty fields and background enrichment is skipped — neither can clobber agent data.
 - `UserPromptSubmit` context-pressure nudges (≥20 / ≥30 turns) also point at `eagle-mem session save`, not the raw block.
+- On install/update the managed `## Eagle Mem — Persistent Memory` section in `~/.claude/CLAUDE.md` is rewritten to this CLI-first doctrine whenever it predates it. Detection keys on the absence of the current section's `session save --session-id` sentinel (v4.12.1 fixed a `grep -F` escaping bug that left the section — and therefore the clean-capture behavior — un-updated). Covered by `tests/test_claude_md_capture_doctrine.sh`.
 
 ## Eagle Mem Files Depending On This
 

package/lib/common.sh

@@ -1919,11 +1919,13 @@ eagle_patch_claude_md() {
     mkdir -p "$HOME/.claude"
 
     if [ -f "$claude_md" ] && grep -qF "$marker" "$claude_md" 2>/dev/null; then
-        # Rewrite when the section uses an outdated capture doctrine:
-        #   - the old pipe-separated <eagle-summary> template, or
-        #   - the superseded "collapsed <details>" recommendation (pre-CLI-first).
-        if grep -qF 'request: \[what user asked\] | completed:' "$claude_md" 2>/dev/null \
-            || grep -qF 'collapsed `<details>` element' "$claude_md" 2>/dev/null; then
+        # Rewrite whenever the section predates the CLI-first capture doctrine.
+        # The current section is the only one that mentions `session save --session-id`,
+        # so its ABSENCE is a reliable "this section is outdated" signal — this catches
+        # the old `<eagle-summary>` template AND the superseded `<details>` recommendation
+        # without fragile fixed-string matching (the prior `grep -F '...\[...\]...'` never
+        # matched because -F treats the backslashes literally).
+        if ! grep -qF 'session save --session-id' "$claude_md" 2>/dev/null; then
             # Replace the outdated section: remove old, append new
             local tmp_md
             tmp_md=$(mktemp)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eagle-mem",
-  "version": "4.12.0",
+  "version": "4.12.1",
   "description": "Shared memory, release guardrails, RTK token protection, and worker lanes for Claude Code, Codex, OpenCode, Grok, and Google Antigravity",
   "bin": {
     "eagle-mem": "bin/eagle-mem"

package/scripts/test.sh

@@ -68,6 +68,8 @@ run_check "Trust Surfaces (DB integrity, JSON errors, statusline)" "bash \"$SCRI
 run_check "Recall Observability (UserPromptSubmit recall event)" "bash \"$SCRIPTS_DIR/../tests/test_recall_observability.sh\""
 run_check "Eagle Event Log (hook/action observability)" "bash \"$SCRIPTS_DIR/../tests/test_eagle_events.sh\""
 run_check "Dashboard Surface (local HTML memory view)" "bash \"$SCRIPTS_DIR/../tests/test_dashboard.sh\""
+run_check "Clean Session Capture (capture_source, fill-only upsert, no clobber)" "bash \"$SCRIPTS_DIR/../tests/test_clean_session_capture.sh\""
+run_check "CLAUDE.md Capture Doctrine (installer rewrites outdated section)" "bash \"$SCRIPTS_DIR/../tests/test_claude_md_capture_doctrine.sh\""
 
 echo ""
 if [ "$errors" -eq 0 ]; then

package/tests/test_claude_md_capture_doctrine.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# ═══════════════════════════════════════════════════════════
+# Regression: eagle_patch_claude_md must rewrite an outdated
+# Eagle Mem capture section to the CLI-first doctrine.
+#
+# Guards against the v4.12.0 bug where the detection used
+# `grep -qF 'request: \[what user asked\] | completed:'` — under
+# grep -F the backslashes are literal, so it never matched the
+# real `[what user asked]` text and the section was never updated,
+# silently defeating the clean-capture feature on every install.
+# ═══════════════════════════════════════════════════════════
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+pass=0
+fail=0
+ok()   { echo "  ok: $1"; pass=$((pass+1)); }
+bad()  { echo "  FAIL: $1"; fail=$((fail+1)); }
+
+run_case() {
+    local label="$1" body="$2"
+    local tmp; tmp=$(mktemp -d)
+    mkdir -p "$tmp/.claude"
+    printf '%s\n' "$body" > "$tmp/.claude/CLAUDE.md"
+
+    ( export HOME="$tmp"; . "$REPO_DIR/lib/common.sh" >/dev/null 2>&1; eagle_patch_claude_md >/dev/null 2>&1 )
+
+    if grep -qF 'session save --session-id' "$tmp/.claude/CLAUDE.md"; then
+        ok "$label: CLI-first doctrine present after patch"
+    else
+        bad "$label: section was NOT rewritten to CLI-first"
+    fi
+    if [ "$(grep -c '## Eagle Mem — Persistent Memory' "$tmp/.claude/CLAUDE.md")" = "1" ]; then
+        ok "$label: exactly one Eagle Mem section (no duplication)"
+    else
+        bad "$label: section count != 1"
+    fi
+    rm -rf "$tmp"
+}
+
+# Case 1: old <eagle-summary>-emit section with surrounding user content.
+run_case "old-eagle-summary" '# Custom global instructions
+
+Pre-section user content.
+
+---
+
+## Eagle Mem — Persistent Memory
+
+**Rule:** Before your final response, emit an `<eagle-summary>` block.
+
+```
+<eagle-summary>
+request: [what user asked] | completed: [what shipped]
+</eagle-summary>
+```
+
+---
+
+## Behavioral Rules
+
+Post-section user content that must survive.'
+
+# Verify surrounding content survives the rewrite (separate explicit check).
+TMP=$(mktemp -d); mkdir -p "$TMP/.claude"
+printf '%s\n' '# Custom
+
+KEEP_BEFORE_MARKER
+
+---
+
+## Eagle Mem — Persistent Memory
+
+**Rule:** emit an `<eagle-summary>` block.
+
+---
+
+## Behavioral Rules
+
+KEEP_AFTER_MARKER' > "$TMP/.claude/CLAUDE.md"
+( export HOME="$TMP"; . "$REPO_DIR/lib/common.sh" >/dev/null 2>&1; eagle_patch_claude_md >/dev/null 2>&1 )
+grep -q 'KEEP_BEFORE_MARKER' "$TMP/.claude/CLAUDE.md" && ok "preserve: content before section kept" || bad "preserve: clobbered content before section"
+grep -q 'KEEP_AFTER_MARKER'  "$TMP/.claude/CLAUDE.md" && ok "preserve: content after section kept"  || bad "preserve: clobbered content after section"
+grep -q 'emit an `<eagle-summary>` block' "$TMP/.claude/CLAUDE.md" && bad "preserve: stale emit instruction still present" || ok "preserve: stale emit instruction removed"
+
+# Idempotency: rewriting again must not add a second section.
+before=$(cksum "$TMP/.claude/CLAUDE.md" | awk '{print $1}')
+( export HOME="$TMP"; . "$REPO_DIR/lib/common.sh" >/dev/null 2>&1; eagle_patch_claude_md >/dev/null 2>&1 )
+[ "$(grep -c '## Eagle Mem — Persistent Memory' "$TMP/.claude/CLAUDE.md")" = "1" ] && ok "idempotent: still one section after 2nd run" || bad "idempotent: section duplicated on 2nd run"
+rm -rf "$TMP"
+
+echo ""
+echo "test_claude_md_capture_doctrine: $pass passed, $fail failed"
+[ "$fail" -eq 0 ] || exit 1