@compr/opscontext-mcp 2.11.0 → 2.12.0

package/CHANGELOG.md

@@ -4,6 +4,39 @@ All notable changes to OpsContext for AI Agents (previously ContextEngine — MC
 
 > Entries for 2.2.0 through 2.4.0 were not backfilled here; see `docs/sessions/SESSION_19` through `SESSION_21` for those releases.
 
+## [2.12.0] 2026-09-27: phase B, second half (liveness, the learnings store, two decisions)
+
+### Servers and locks
+
+- **A crashed process no longer holds a lock for seconds or minutes.** The audit log, rotation,
+  daily-check and learnings-store locks name their holder; a lock whose holder is gone, or an empty lock
+  older than a second, is broken at once. A writer killed inside the audit lock used to cost every
+  other writer about four entries (it happened on the author's machine on 2026-09-27); a saver killed
+  inside the store lock made saves fail for 20 s. Temp copies left by dead writers are removed.
+  LOCKs `[A-DEAD-HOLDER-LOSES-THE-LOCK-AT-ONCE]`, `[A-DEAD-STORE-HOLDER-LOSES-THE-LOCK-AT-ONCE]`. (B1-2, B4-2)
+- **A registry record belongs to its own process.** A crashed server's record whose process number was
+  reused by another program froze the indexer election and silenced the event port. A record is now
+  alive only if its process started no later than the record says. LOCK `[A-RECORD-BELONGS-TO-ITS-OWN-PROCESS]`. (B5-1)
+- **A chat server ends with its chat.** A server whose client died used to live on, still indexing and
+  holding the event port. It now stops when its input closes (the launchd agent excepted). A server with
+  the embedding model loaded stops without the model runtime's native abort, which used to leave a macOS
+  crash report on every stop. LOCK `[A-CHAT-SERVER-ENDS-WITH-ITS-CHAT]`. (B5-2)
+
+### Learnings
+
+- **A read never writes the store without the lock.** A read that found a bundled default missing used
+  to rewrite the whole store unlocked (a concurrent save could be lost), and a deleted default came back at
+  the next read. Now the read takes the lock or only shows the default; a deleted default stays deleted,
+  and a re-add is recorded. LOCK `[A-READ-NEVER-WRITES-THE-STORE]`. (B4-1)
+
+### Firewall and compliance
+
+- **A failed `git status` reads "unknown", never "clean"** in the firewall's git check (a repository git
+  could not read was reported clean). LOCK `[GIT-FAILURE-IS-UNKNOWN-NOT-CLEAN]`. (B6-2)
+- **`audit-verify` shows every redaction acknowledgement it relied on** (time, actor, reason), and the
+  compliance pages say what an acknowledgement cannot prove. Four claims on those pages that had stopped
+  being true since June are corrected (rotation, verification, file permissions, restore). (B3-2)
+
 ## [2.11.0] 2026-09-27: the end-to-end review, phase B (the evidence stays true when things go wrong)
 
 Fixes from the end-to-end review, phase B (`docs/audits/E2E_REVIEW_2026-09.md`, section "Phase B").

package/dist/audit.d.ts

@@ -155,6 +155,16 @@ export interface IntegrityReport {
     /** Records whose hash already appeared earlier in the history: a second copy of a record,
      *  counted once and never relinked. Not tampering, not a fork. [LOCK] [VERIFY-FORK-IS-NOT-TAMPER] */
     duplicateIndices?: number[];
+    /** The acknowledgements that turned altered records into redacted ones: who said so, when, why.
+     *  An acknowledgement is a statement by whoever ran it, so the verifier shows every one it used.
+     *  [LOCK] [REDACTION-IS-A-CHAINED-RECORD] */
+    acknowledgements?: Array<{
+        index: number;
+        ts: string;
+        actor: string;
+        reason: string;
+        records: number;
+    }>;
     /** Lines that are not records: file, line number, and the history index they sit before.
      *  Non-empty makes `ok` false; every other record is still checked. [LOCK] [VERIFY-READS-PAST-AN-UNREADABLE-LINE] */
     unreadable?: UnreadableLine[];

package/dist/audit.js

@@ -102,14 +102,10 @@ function acquireLockSync() {
             // Lockfile exists. Check if it's stale.
             try {
                 const st = statSync(path);
-                if (Date.now() - st.mtimeMs > STALE_LOCK_MS) {
-                    // Orphaned — force-unlink and retry.
-                    try {
-                        unlinkSync(path);
-                    }
-                    catch {
-                        /* another process just cleaned it; retry */
-                    }
+                // [LOCK] [A-DEAD-HOLDER-LOSES-THE-LOCK-AT-ONCE]
+                if (lockHolderIsGone(path, st) || Date.now() - st.mtimeMs > STALE_LOCK_MS) {
+                    // Orphaned — force-unlink and retry, only if it is still the file we judged.
+                    unlinkIfUnchanged(path, st);
                     continue;
                 }
             }
@@ -121,6 +117,51 @@ function acquireLockSync() {
     }
     throw new Error(`Failed to acquire audit lock at ${path} within ${LOCK_TIMEOUT_MS}ms`);
 }
+/**
+ * [LOCKED] [A-DEAD-HOLDER-LOSES-THE-LOCK-AT-ONCE] - 2026-09-27
+ * [NEVER] make writers wait out STALE_LOCK_MS for a holder that is provably gone.
+ * WHY: a writer killed while holding the append lock left it for 10 s; every other writer waited 2 s
+ *      per entry and lost it (4 per writer per crash, 3 of 3 runs, E2E_REVIEW_2026-09 B1-2; 448 such
+ *      losses in the launchd log before 2.5.8). It happened again on 2026-09-27 at 17:01Z: a chat
+ *      server died holding the lock and a new server lost two entries. The lock file names its
+ *      holder's pid; nothing read it.
+ * FIX: a lock whose pid no longer exists, or an empty lock older than a second (its holder died
+ *      between creating it and writing its pid; a live holder writes it at once), is broken now. A
+ *      live pid, even a reused one, keeps today's 10 s rule. The file is removed only if it is still
+ *      the one judged (same inode and time), which narrows the gap where two waiters both break it.
+ *      [LOCK] [AUDIT-001-WRITE-RACE-FIX]: the lock stays; only the stale test is sharper.
+ */
+function lockHolderIsGone(path, st) {
+    let body = "";
+    try {
+        body = readFileSync(path, "utf-8");
+    }
+    catch {
+        return false;
+    }
+    const pid = parseInt(body.split("\n")[0], 10);
+    if (!Number.isInteger(pid) || pid <= 0)
+        return Date.now() - st.mtimeMs > 1000;
+    if (pid === process.pid)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return false; // alive (or not ours to signal): wait as before
+    }
+    catch (e) {
+        return e.code === "ESRCH";
+    }
+}
+function unlinkIfUnchanged(path, judged) {
+    try {
+        const now = statSync(path);
+        if (now.ino === judged.ino && now.mtimeMs === judged.mtimeMs)
+            unlinkSync(path);
+    }
+    catch {
+        /* already gone: another waiter broke it */
+    }
+}
 function auditDir() {
     // CONTEXTENGINE_HOME lets tests run against a temp dir without touching ~/.contextengine
     return process.env.CONTEXTENGINE_HOME || join(homedir(), ".contextengine");
@@ -944,16 +985,18 @@ function acquireRotateLock() {
         catch (e) {
             if (e.code !== "EEXIST")
                 throw e;
-            let age;
+            let st;
             try {
-                age = Date.now() - statSync(lock).mtimeMs;
+                st = statSync(lock);
             }
             catch {
                 continue; // released between our open and our stat: try again
             }
-            if (age < ROTATE_LOCK_STALE_MS)
+            const age = Date.now() - st.mtimeMs;
+            // [LOCK] [A-DEAD-HOLDER-LOSES-THE-LOCK-AT-ONCE]: a crashed rotation no longer blocks the next for 10 minutes.
+            if (age < ROTATE_LOCK_STALE_MS && !lockHolderIsGone(lock, st))
                 return { heldMs: age };
-            safeUnlink(lock);
+            unlinkIfUnchanged(lock, st);
             continue;
         }
         try {
@@ -1298,19 +1341,29 @@ export function verifyChain() {
             continue;
         for (const e of list) {
             if (typeof e.hash === "string" && typeof e.content_hash === "string")
-                acks.set(e.hash, e.content_hash);
+                acks.set(e.hash, { contentHash: e.content_hash, ackIndex: i });
         }
     }
     const redacted = [];
     const stillTampered = [];
+    const usedAcks = new Map(); // ack record index -> records it covers here
     for (const i of tampered) {
         const r = records[i];
         const bound = acks.get(r.hash);
-        if (bound && bound === computeHash(r.prev_hash, r.ts, r.event, r.actor, r.payload))
+        if (bound && bound.contentHash === computeHash(r.prev_hash, r.ts, r.event, r.actor, r.payload)) {
             redacted.push(i);
+            usedAcks.set(bound.ackIndex, (usedAcks.get(bound.ackIndex) ?? 0) + 1);
+        }
         else
             stillTampered.push(i);
     }
+    const acknowledgements = [...usedAcks.entries()].sort((a, b) => a[0] - b[0]).map(([index, n]) => ({
+        index,
+        ts: records[index].ts,
+        actor: records[index].actor,
+        reason: String(records[index].payload.reason ?? ""),
+        records: n,
+    }));
     tampered.length = 0;
     tampered.push(...stillTampered);
     const ok = tampered.length === 0 && orphans.length === 0 && unreadable.length === 0;
@@ -1334,6 +1387,7 @@ export function verifyChain() {
         orphanIndices: orphans,
         forkIndices: forks,
         duplicateIndices: duplicates,
+        acknowledgements,
         unreadable,
         redactedIndices: redacted,
     };
@@ -1423,14 +1477,17 @@ export function acquireVerifyLock() {
         catch (e) {
             if (e.code !== "EEXIST")
                 return null;
+            let st;
             try {
-                if (Date.now() - statSync(lock).mtimeMs < 2 * 3_600_000)
-                    return null;
+                st = statSync(lock);
             }
             catch {
                 continue;
             }
-            safeUnlink(lock);
+            // [LOCK] [A-DEAD-HOLDER-LOSES-THE-LOCK-AT-ONCE]
+            if (Date.now() - st.mtimeMs < 2 * 3_600_000 && !lockHolderIsGone(lock, st))
+                return null;
+            unlinkIfUnchanged(lock, st);
         }
     }
     return null;

package/dist/cli.js

@@ -2165,11 +2165,23 @@ async function cliAuditVerify() {
         console.log(`   Counted once. Content intact, nothing missing. Usually a log trim that was interrupted or`);
         console.log(`   ran while entries arrived. At: ${dups.slice(0, 8).join(", ")}${dups.length > 8 ? `, … (+${dups.length - 8} more)` : ""}`);
     };
+    // [LOCK] [REDACTION-IS-A-CHAINED-RECORD]: an acknowledgement is a statement by whoever ran it; show each one used.
+    const acksNote = (log) => {
+        const acks = report.acknowledgements ?? [];
+        if (acks.length === 0)
+            return;
+        log(`   Acknowledged by (a statement by whoever ran it; the chain cannot tell a removal from a rewrite):`);
+        for (const a of acks.slice(0, 10))
+            log(`     ${a.ts.slice(0, 19).replace("T", " ")}Z  ${a.actor}  ${a.records} record(s)  "${a.reason.slice(0, 80)}"`);
+        if (acks.length > 10)
+            log(`     … (+${acks.length - 10} more)`);
+    };
     if (report.ok) {
         console.log(`✅ Audit chain verified — ${report.total - dups.length} record(s).`);
         console.log(redacted.length === 0
             ? `   No record was altered, and no history is missing.`
             : `   No history is missing. ${redacted.length} record(s) redacted and acknowledged on the chain (indices ${redacted.slice(0, 8).join(", ")}${redacted.length > 8 ? ", …" : ""}), 0 altered.`);
+        acksNote((x) => console.log(x));
         if (forks.length > 0) {
             // [VERIFY-FORK-IS-NOT-TAMPER] — surface this, but do not call it tampering.
             console.log(`\n⚠️  ${forks.length} concurrent-append fork(s) detected (not tampering).`);
@@ -2195,6 +2207,7 @@ async function cliAuditVerify() {
     }
     if (redacted.length > 0) {
         console.error(`\n   Also ${redacted.length} redacted record(s), acknowledged on the chain, not counted above.`);
+        acksNote((x) => console.error(x));
     }
     // [LOCK] [VERIFY-READS-PAST-AN-UNREADABLE-LINE]: say where, and that the rest was checked.
     const unreadable = report.unreadable ?? [];

package/dist/firewall.js

@@ -11,7 +11,7 @@
 //
 // This is the first MCP server that enforces agent behavior
 // through progressive response degradation.
-import { execSync } from "child_process";
+import { execSync, execFileSync } from "child_process";
 import { existsSync, readFileSync, statSync, writeFileSync, mkdirSync } from "fs";
 import { join } from "path";
 import { homedir } from "os";
@@ -513,19 +513,29 @@ export class ProtocolFirewall {
             this.gitCache.timestamp = now;
             this.gitCache.data = [];
             for (const dir of this.projectDirs.slice(0, 5)) {
+                // [LOCKED] [GIT-FAILURE-IS-UNKNOWN-NOT-CLEAN] - 2026-09-27 (Yan's GO for this one line, file under DO NOT RE-AUDIT)
+                // [NEVER] count dirty files through a shell pipe that turns a failed git into "0".
+                // WHY: `git status --porcelain 2>/dev/null | wc -l` printed 0 when git failed, so a repository
+                //      git could not read (a corrupt index: exit 128, 8 changed files) was reported "Git: ok,
+                //      clean" (E2E_REVIEW_2026-09 B6-2). [EXEC-FAILURE-IS-NOT-EMPTY] fixed the same shape in agents.ts.
+                // FIX: git by argument list, lines counted here; a folder that is not a repository is skipped as
+                //      before; any other failure (unreadable repo, timeout) is reported as unknown, never clean.
                 try {
-                    const out = execSync("git status --porcelain 2>/dev/null | wc -l", {
+                    const out = execFileSync("git", ["status", "--porcelain"], {
                         cwd: dir.path,
                         encoding: "utf-8",
                         timeout: 3000,
-                        stdio: ["pipe", "pipe", "pipe"],
-                    }).trim();
-                    const n = parseInt(out);
+                        stdio: ["ignore", "pipe", "pipe"],
+                    });
+                    const n = out.split("\n").filter(Boolean).length;
                     if (n > 0)
                         this.gitCache.data.push(`${dir.name}(${n})`);
                 }
-                catch {
-                    /* skip */
+                catch (e) {
+                    const stderr = String(e.stderr ?? "");
+                    if (/not a git repository/i.test(stderr))
+                        continue;
+                    this.gitCache.data.push(`${dir.name}(unknown: git could not read it)`);
                 }
             }
         }

package/dist/index.js

@@ -461,6 +461,28 @@ function evaluateRole(reason) {
 }
 let healthTick = 0;
 let lastStaleCount = -1;
+let stopRegistry = null;
+let ending = false;
+/**
+ * End this server. Everything that matters is already on disk (audit appends and store writes are
+ * synchronous); the registry record is removed first. With the embedding model loaded, a normal exit
+ * aborts in the model runtime's native teardown ("libc++abi: ... mutex lock failed", SIGABRT, 3 of 3
+ * runs, releasing the model does not help) and leaves a macOS crash report per exit, so such a server
+ * ends with SIGKILL, which skips that teardown. [LOCK] [A-CHAT-SERVER-ENDS-WITH-ITS-CHAT]
+ */
+function endThisServer() {
+    if (ending)
+        return;
+    ending = true;
+    try {
+        stopRegistry?.();
+    }
+    catch { /* the lister removes a dead record anyway */ }
+    if (isEmbeddingsReady())
+        process.kill(process.pid, "SIGKILL");
+    else
+        process.exit(0);
+}
 const SERVER_STARTED_AT = Date.now();
 let lastChainCheckSpawn = 0;
 /**
@@ -1394,7 +1416,8 @@ async function main() {
         }
     }
     try {
-        const reg = registerServer({ version: PKG_VERSION, script: fileURLToPath(import.meta.url), corpus, role: corpus ? "reader" : undefined, daemon: process.env.OPSCONTEXT_DAEMON === "1" });
+        const reg = registerServer({ version: PKG_VERSION, script: fileURLToPath(import.meta.url), corpus, role: corpus ? "reader" : undefined, daemon: process.env.OPSCONTEXT_DAEMON === "1", onSignal: endThisServer });
+        stopRegistry = reg.stop;
         setRegistryRole = reg.setRole;
         setRegistryEventPort = reg.setEventPort;
         const fleet = listServers();
@@ -1453,6 +1476,26 @@ async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error("[ContextEngine] 🚀 MCP server running on stdio (keyword search ready)");
+    // [LOCKED] [A-CHAT-SERVER-ENDS-WITH-ITS-CHAT] - 2026-09-27
+    // [NEVER] let a server whose client closed its stdin keep running, unless it is the launchd agent.
+    // WHY: the file watchers and the event receiver keep the event loop alive, and nothing listened for
+    //      the end of stdin. When a chat's client died without stopping its server (3 of 3 runs,
+    //      E2E_REVIEW_2026-09 B5-2), the server lived on, adopted by launchd, still the indexer, still
+    //      holding the event port, running its build for good; new servers became its readers.
+    // FIX: stdin's end or close ends a chat server (its registry record goes with it, and a reader takes
+    //      over the index within one role poll, 15 s). The launchd agent (OPSCONTEXT_DAEMON=1) has
+    //      stdin on /dev/null by design and is exempt. [LOCK] [AUTOSTART-IS-THE-STANDING-INDEXER]
+    //      Ending goes through endThisServer(): with the embedding model loaded, a normal exit aborts in
+    //      native code and leaves a macOS crash report each time, so such a server ends with SIGKILL
+    //      after its record is removed; the stop signals (SIGTERM, SIGINT, SIGHUP) take the same path.
+    if (process.env.OPSCONTEXT_DAEMON !== "1") {
+        const leave = () => {
+            console.error("[ContextEngine] 👋 the client closed the connection: this server stops");
+            endThisServer();
+        };
+        process.stdin.once("end", leave);
+        process.stdin.once("close", leave);
+    }
     // 3a. Audit log auto-rotation. Deferred so the first requests are answered before the
     // synchronous verify + rewrite (a few seconds on a 500k-record chain) blocks the loop.
     // [LOCK] [AUTO-ROTATE-HYSTERESIS-AND-ONE-RUNNER]

package/dist/learnings.d.ts

@@ -15,6 +15,9 @@ export interface LearningsStore {
     version: number;
     count: number;
     learnings: Learning[];
+    /** Bundled default rules (lowercased, trimmed) the owner deleted: never merged back.
+     *  [LOCK] [A-READ-NEVER-WRITES-THE-STORE] */
+    dismissed_defaults?: string[];
 }
 /** Valid categories for learnings */
 export declare const LEARNING_CATEGORIES: readonly ["deployment", "api", "database", "frontend", "backend", "devops", "security", "performance", "testing", "debugging", "tooling", "git", "dependencies", "architecture", "data", "infrastructure", "mobile", "other"];

package/dist/learnings.js

@@ -76,10 +76,13 @@ function loadBundledDefaults() {
 function mergeDefaults(store) {
     const bundled = loadBundledDefaults();
     if (bundled.length === 0)
-        return false;
+        return 0;
     const existingRules = new Set(store.learnings
         .filter((l) => typeof l.rule === "string")
         .map((l) => l.rule.toLowerCase().trim()));
+    // A default the owner deleted stays deleted. [LOCK] [A-READ-NEVER-WRITES-THE-STORE]
+    for (const r of store.dismissed_defaults ?? [])
+        existingRules.add(r);
     let added = 0;
     const now = new Date().toISOString();
     for (const def of bundled) {
@@ -97,7 +100,12 @@ function mergeDefaults(store) {
         existingRules.add(def.rule.toLowerCase().trim());
         added++;
     }
-    return added > 0;
+    return added;
+}
+/** Is this rule text one of the bundled defaults? */
+function isBundledDefault(rule) {
+    const key = rule.toLowerCase().trim();
+    return loadBundledDefaults().some((d) => d.rule.toLowerCase().trim() === key);
 }
 // [LOCKED] [STORE-NEVER-STARTS-FRESH-OVER-DATA] 2026-09-05
 // [NEVER] turn an unreadable learnings.json into an empty store, write the store with a
@@ -127,6 +135,55 @@ let batchDirty = false;
 function sleepMs(ms) {
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
+// [LOCKED] [A-DEAD-STORE-HOLDER-LOSES-THE-LOCK-AT-ONCE] 2026-09-27
+// [NEVER] make a save wait out LOCK_STALE_MS for a holder that is provably gone, or leave a dead
+//         writer's full copy of the store on disk.
+// WHY: a saver killed inside the lock made every other save in the next ~20 s wait 10 s and fail
+//      with "locked by another process" (6 per run, 3 of 3, E2E_REVIEW_2026-09 B4-2), and left its
+//      temp copy of the whole store behind for good. The lock directory names its holder's pid;
+//      nothing read it.
+// FIX: a lock whose pid no longer exists, or a lock directory older than a second with no pid in
+//      it, is taken over at once; a live pid keeps the 30 s rule. Inside the lock, temp copies
+//      written by a pid that no longer exists are removed.
+function storeHolderIsGone(age) {
+    let pid = NaN;
+    try {
+        pid = parseInt(readFileSync(join(STORE_LOCK_DIR, "pid"), "utf-8"), 10);
+    }
+    catch { /* no pid yet */ }
+    if (!Number.isInteger(pid) || pid <= 0)
+        return age > 1000;
+    if (pid === process.pid)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return false;
+    }
+    catch (e) {
+        return e.code === "ESRCH";
+    }
+}
+function removeDeadWritersTemps() {
+    try {
+        const dir = dirname(LEARNINGS_PATH);
+        for (const f of readdirSync(dir)) {
+            const m = /^learnings\.json\.tmp-(\d+)-\d+$/.exec(f);
+            if (!m)
+                continue;
+            const pid = Number(m[1]);
+            if (pid === process.pid)
+                continue;
+            try {
+                process.kill(pid, 0);
+            }
+            catch (e) {
+                if (e.code === "ESRCH")
+                    unlinkSync(join(dir, f));
+            }
+        }
+    }
+    catch { /* cleanup is a courtesy; the store is untouched either way */ }
+}
 /** Cross-process, re-entrant (within this process) lock around the store file. */
 export function withStoreLock(fn) {
     if (lockDepth > 0) {
@@ -160,7 +217,8 @@ export function withStoreLock(fn) {
             catch {
                 age = 0;
             }
-            if (age > LOCK_STALE_MS) {
+            // [LOCK] [A-DEAD-STORE-HOLDER-LOSES-THE-LOCK-AT-ONCE]
+            if (age > LOCK_STALE_MS || storeHolderIsGone(age)) {
                 // Holder died (or hung) without releasing: take it over.
                 try {
                     rmSync(STORE_LOCK_DIR, { recursive: true, force: true });
@@ -176,6 +234,7 @@ export function withStoreLock(fn) {
     }
     lockDepth = 1;
     try {
+        removeDeadWritersTemps();
         return fn();
     }
     finally {
@@ -237,14 +296,42 @@ function readStoreFromDisk() {
     else {
         store = { version: 1, count: 0, learnings: [] };
     }
-    // Auto-merge bundled defaults on first load or when new defaults are added
-    if (mergeDefaults(store)) {
+    // [LOCKED] [A-READ-NEVER-WRITES-THE-STORE] - 2026-09-27
+    // [NEVER] write the store from a read that does not hold the store lock, and never merge back a
+    //         bundled default the owner deleted.
+    // WHY: a plain read (listLearnings, searchLearnings, the index build) merged a missing bundled
+    //      default and wrote the whole store WITHOUT the lock. With that read held 1.5 s before its
+    //      write, a concurrent saver's 5 learnings, each saved with success, were gone (3 of 3,
+    //      E2E_REVIEW_2026-09 B4-1); at natural speed the window is milliseconds and opens after every
+    //      release that adds a default. And a deleted default came back at the next read, with a new id
+    //      and no audit record: the delete never stuck. [LOCK] [STORE-NEVER-STARTS-FRESH-OVER-DATA]
+    //      already said "never let two processes write it without the lock".
+    // FIX: holding the lock (a save, a delete, a batch), the merge is written as before. A plain read
+    //      takes the lock for it (re-reading inside), and if the lock is busy only shows the defaults,
+    //      writing nothing. A deleted default is remembered in `dismissed_defaults`; every persisted
+    //      merge is recorded as a learning.import of the bundled defaults.
+    if (!hasMissingDefaults(store))
+        return store;
+    if (lockDepth > 0) {
+        const added = mergeDefaults(store);
         if (batchStore)
             batchDirty = true;
         else
             writeStoreToDisk(store);
+        safeAppend("learning.import", { source: "bundled defaults", format: "json", imported: added, updated: 0, skipped: 0 });
+        return store;
+    }
+    try {
+        return withStoreLock(() => readStoreFromDisk());
     }
-    return store;
+    catch {
+        mergeDefaults(store); // the lock is busy: show them, persist at the next locked read or write
+        return store;
+    }
+}
+function hasMissingDefaults(store) {
+    const probe = { version: store.version, count: 0, learnings: store.learnings.slice(), dismissed_defaults: store.dismissed_defaults };
+    return mergeDefaults(probe) > 0;
 }
 function loadStore() {
     if (batchStore)
@@ -517,12 +604,19 @@ function deleteLearningUnlocked(id) {
         return false;
     const removed = store.learnings[index];
     store.learnings.splice(index, 1);
+    // A deleted bundled default stays deleted. [LOCK] [A-READ-NEVER-WRITES-THE-STORE]
+    const dismissed = typeof removed.rule === "string" && isBundledDefault(removed.rule);
+    if (dismissed) {
+        const key = removed.rule.toLowerCase().trim();
+        store.dismissed_defaults = [...new Set([...(store.dismissed_defaults ?? []), key])];
+    }
     saveStore(store);
     safeAppend("learning.delete", {
         id: removed.id,
         category: removed.category,
         project: removed.project,
         rule_length: typeof removed.rule === "string" ? removed.rule.length : 0,
+        ...(dismissed ? { default_dismissed: true } : {}),
     });
     return true;
 }

package/dist/server-registry.d.ts

@@ -42,6 +42,8 @@ export declare const SERVER_COUNT_WARN = 3;
  */
 export declare function buildHashOf(scriptPath: string): string | null;
 export declare function isAlive(pid: number): boolean;
+/** The record's own process is still running. [LOCK] [A-RECORD-BELONGS-TO-ITS-OWN-PROCESS] */
+export declare function recordIsLive(rec: Pick<ServerRecord, "pid" | "started">): boolean;
 /**
  * Register the running server. Returns a stop() that removes the record; exit handlers call it too.
  */
@@ -51,6 +53,7 @@ export declare function registerServer(opts: {
     corpus?: string;
     role?: "indexer" | "reader";
     daemon?: boolean;
+    onSignal?: () => void;
 }): {
     record: ServerRecord;
     stop: () => void;

package/dist/server-registry.js

@@ -76,6 +76,60 @@ export function isAlive(pid) {
         return e?.code === "EPERM"; // exists, not ours
     }
 }
+/**
+ * [LOCKED] [A-RECORD-BELONGS-TO-ITS-OWN-PROCESS] - 2026-09-27
+ * [NEVER] treat a registry record as a live server because its pid exists.
+ * WHY: pids are reused. A dead launchd agent's record pointed at a live unrelated process (3 of 3
+ *      valid runs, E2E_REVIEW_2026-09 B5-1): for as long as that process lived, no reader took over
+ *      indexing (a doc change never reached the index), nobody answered on the event port, a new chat
+ *      server did not take it, and `contextengine servers` listed the unrelated process as the
+ *      current launchd agent holding the port. Records survive a crash or a power cut, and pids wrap.
+ * FIX: a record is alive when its pid exists AND that process started no later than the record says
+ *      the server did (the server registers after its process starts; a reused pid belongs to a
+ *      process that started later). Start times come from one `ps -o pid=,lstart=` for all uncached
+ *      pids of a listing, cached 60 s per pid. When ps cannot answer, the pid test alone decides, as
+ *      before. A record that fails is dead: removed by the lister, never elected, never the daemon.
+ */
+const START_CACHE_MS = 60_000;
+const startCache = new Map();
+function refreshStartTimes(pids) {
+    const now = Date.now();
+    const need = pids.filter((p) => { const c = startCache.get(p); return !c || now - c.at > START_CACHE_MS; });
+    if (need.length === 0)
+        return;
+    let out = "";
+    try {
+        // Hardcoded argv, no shell: the only variables are numbers.
+        out = execFileSync("ps", ["-o", "pid=,lstart=", "-p", need.join(",")], { encoding: "utf8", timeout: 2000, stdio: ["ignore", "pipe", "ignore"] });
+    }
+    catch (e) {
+        const stdout = e.stdout;
+        out = typeof stdout === "string" ? stdout : ""; // ps exits 1 when some pid is gone; keep what it printed
+    }
+    const seen = new Set();
+    for (const line of out.split("\n")) {
+        const m = /^\s*(\d+)\s+(.+?)\s*$/.exec(line);
+        if (!m)
+            continue;
+        const t = Date.parse(m[2]);
+        seen.add(Number(m[1]));
+        startCache.set(Number(m[1]), { startedMs: Number.isNaN(t) ? null : t, at: now });
+    }
+    for (const p of need)
+        if (!seen.has(p))
+            startCache.set(p, { startedMs: null, at: now });
+}
+/** The record's own process is still running. [LOCK] [A-RECORD-BELONGS-TO-ITS-OWN-PROCESS] */
+export function recordIsLive(rec) {
+    if (!isAlive(rec.pid))
+        return false;
+    refreshStartTimes([rec.pid]);
+    const startedMs = startCache.get(rec.pid)?.startedMs ?? null;
+    const registered = Date.parse(rec.started);
+    if (startedMs === null || Number.isNaN(registered))
+        return true; // cannot tell: the pid test decides
+    return startedMs <= registered + 5_000; // lstart has one-second resolution
+}
 /**
  * Register the running server. Returns a stop() that removes the record; exit handlers call it too.
  */
@@ -119,7 +173,11 @@ export function registerServer(opts) {
     };
     process.on("exit", stop);
     for (const sig of ["SIGTERM", "SIGINT", "SIGHUP"]) {
-        process.on(sig, () => { stop(); process.exit(0); });
+        // The record goes first; the caller may end the process its own way. [LOCK] [A-CHAT-SERVER-ENDS-WITH-ITS-CHAT]
+        process.on(sig, () => { stop(); if (opts.onSignal)
+            opts.onSignal();
+        else
+            process.exit(0); });
     }
     const setRole = (role) => { record.role = role; write(); };
     const setEventPort = (port) => {
@@ -141,7 +199,7 @@ export function liveDaemonPid(exceptPid = process.pid) {
             continue;
         try {
             const rec = JSON.parse(readFileSync(join(dir, f), "utf8"));
-            if (rec.daemon && rec.pid !== exceptPid && isAlive(rec.pid))
+            if (rec.daemon && rec.pid !== exceptPid && recordIsLive(rec))
                 return rec.pid;
         }
         catch {
@@ -156,6 +214,7 @@ export function listServers() {
     const report = { servers: [], removed: 0, warnings: [] };
     if (!existsSync(dir))
         return report;
+    const records = [];
     for (const f of readdirSync(dir)) {
         if (!f.endsWith(".json"))
             continue;
@@ -172,7 +231,12 @@ export function listServers() {
             report.removed++;
             continue;
         }
-        if (!isAlive(rec.pid)) {
+        records.push({ path, rec });
+    }
+    refreshStartTimes(records.filter(({ rec }) => isAlive(rec.pid)).map(({ rec }) => rec.pid)); // one ps for the listing
+    for (const { path, rec } of records) {
+        // [LOCK] [A-RECORD-BELONGS-TO-ITS-OWN-PROCESS]
+        if (!recordIsLive(rec)) {
             try {
                 unlinkSync(path);
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compr/opscontext-mcp",
-  "version": "2.11.0",
+  "version": "2.12.0",
   "description": "OpsContext for AI Agents — read-only fleet visibility (PM2/nginx/Docker/git/cron) + tamper-evident audit log + policy-as-code hooks. The ops + compliance layer Claude Code can't grow natively.",
   "type": "module",
   "main": "dist/index.js",