@remnic/plugin-codex 9.3.689 → 9.3.690

package/README.md

@@ -31,7 +31,7 @@ The package is **data + one small runtime materializer** (no runtime JS beyond t
 | File / dir | Purpose |
 |---|---|
 | `.codex-plugin/plugin.json` | Plugin manifest |
-| `hooks/hooks.json` + `hooks/bin/remnic-codex-hook.{cjs,sh,ps1}` | Codex session-lifecycle hooks (recall, observe, session-end). A single cross-platform Node.js runner (`.cjs`) with thin POSIX (`.sh`) and Windows PowerShell (`.ps1`) launchers; `hooks.json` wires each event with both `command` and `commandWindows` so hooks work on macOS, Linux, and Windows. |
+| `hooks/hooks.json` + `hooks/bin/remnic-codex-hook.{cjs,sh,ps1}` | Codex session-lifecycle hooks (recall, observe, session-end, **pre-compact LCM flush**). A single cross-platform Node.js runner (`.cjs`) with thin POSIX (`.sh`) and Windows PowerShell (`.ps1`) launchers; `hooks.json` wires each event with both `command` and `commandWindows` so hooks work on macOS, Linux, and Windows. |
 | `skills/` | `remnic-recall`, `remnic-remember`, `remnic-search`, `remnic-status`, `remnic-entities`, `remnic-memory-workflow` — invocable from Codex chats |
 | `memories_extensions/remnic/` | Codex phase-2 consolidation instructions — tells the Codex compactor sub-agent to treat Remnic's on-disk Markdown as an authoritative local memory source when it builds `MEMORY.md`. Local-only (no MCP, no network); runtime recall/observe still flow through the hooks above. |
 | `.mcp.json` | MCP server config pointing Codex at `http://localhost:4318/mcp` |
@@ -43,6 +43,7 @@ Once installed and a Remnic daemon is running (`remnic daemon start`):
 
 - **Auto-recall** on `SessionStart` and on every `UserPromptSubmit` — relevant memories are injected before Codex's first turn and before each subsequent user turn.
 - **Auto-observe** on `PostToolUse` for the `Bash` tool and on `Stop` (session end) — new facts, decisions, and entities touched by shell work (or accumulated through the session) are buffered for extraction automatically.
+- **Compaction coordination** on `PreCompact` — before Codex summarizes the conversation, the hook POSTs `/engram/v1/lcm/compaction/flush` so the daemon drains the in-flight observe buffer into long-term memory first. This mirrors `@remnic/plugin-pi`'s `session_before_compact` handler and is fail-open: a flush failure never blocks compaction.
 - **Memory skills** — invoke `/remnic-recall`, `/remnic-search`, `/remnic-remember`, `/remnic-entities`, `/remnic-status` directly in Codex chats.
 - **Cross-agent sharing** — the same memory store is shared with every other Remnic-connected agent (Claude Code, OpenClaw, Replit, Hermes, etc.), so what one agent learns is available to all.
 
@@ -82,6 +83,56 @@ export REMNIC_AUTH_TOKEN=$(remnic token generate codex-cli | awk '/^ *Token:/ {p
 
 See `docs/integration/connector-setup.md` in the Remnic repo for the canonical snippet.
 
+## Remote / network daemon
+
+The hooks default to a local daemon at `127.0.0.1:4318`, but the whole point of
+this plugin is that a Codex host can talk to a **shared central Remnic daemon**
+over Tailscale, a LAN, or a VPN — the same remote/central topology
+`@remnic/plugin-pi` supports. Set `REMNIC_DAEMON_URL` (full base URL) and the
+hooks route every recall / observe / compaction call there:
+
+```bash
+# Point this Codex install at the central daemon on `macstudio` over Tailscale.
+export REMNIC_DAEMON_URL="http://macstudio.tail-XXXX.ts.net:4318"
+```
+
+- `REMNIC_DAEMON_URL` (primary) / `ENGRAM_DAEMON_URL` (legacy alias) — full base
+  URL, e.g. `http://host:4318` or `https://remnic.internal:443`. An explicit
+  `http:` / `https:` scheme is required; an HTTPS URL selects the TLS transport
+  so daemons behind a reverse proxy work without extra config.
+- `REMNIC_HOST` / `REMNIC_PORT` (and `ENGRAM_*` aliases) — still honored as a
+  backward-compat fallback when no full URL is set. Existing installs and CI
+  that set only the host/port pair keep working unchanged.
+- `REMNIC_NAMESPACE` / `ENGRAM_NAMESPACE` — optional. When set, attaches a
+  namespace to the compaction flush (parity with `@remnic/plugin-pi`'s
+  `config.namespace`). Unset → the daemon resolves the default namespace.
+
+The bearer token still comes from the per-plugin token store
+(`remnic connectors install codex-cli` writes `~/.remnic/tokens.json`) or the
+`OPENCLAW_REMNIC_ACCESS_TOKEN` / `OPENCLAW_ENGRAM_ACCESS_TOKEN` env vars.
+
+## Hook trust (one-time review)
+
+Codex does not run non-managed command hooks until a human reviews and trusts
+them. The first time these hooks are enabled, Codex prints a startup warning
+directing you to run `/hooks` in the CLI; review the four Remnic entries
+(SessionStart / UserPromptSubmit / Stop / PreCompact) and approve them. Codex
+records trust against the current hook hash, so updates to `hooks.json` will
+re-trigger a review.
+
+For fleet / headless automation there is no non-interactive trust CLI today;
+pick one of:
+
+- **Managed / pre-trusted hooks** (enterprise/MDM) — ship the hooks under a
+  `managed_dir` declared in `requirements.toml`. Codex marks managed hooks as
+  trusted by policy. This is the supported path for rolling the integration out
+  across many machines.
+- **`--dangerously-bypass-hook-trust`** per invocation — runs enabled hooks
+  without persisted trust for that one run. Useful for a spike, not a fleet.
+
+The hooks themselves are fail-open everywhere, so an untrusted hook is a
+no-op (Codex skips it), never a crash.
+
 ## Agent note
 
 If you're an AI agent scaffolding a Codex integration: **do not** hand-edit `~/.codex/` directly. The full setup has three components:

package/hooks/bin/remnic-codex-hook.cjs

@@ -26,28 +26,88 @@ const fs = require("fs");
 const os = require("os");
 const path = require("path");
 const http = require("http");
+const https = require("https");
 const { execFileSync, spawn, spawnSync } = require("child_process");
 
 const HOME = process.env.HOME || process.env.USERPROFILE || os.homedir();
+
+// Daemon base URL resolution (issue #1571 — remote/network parity with
+// @remnic/plugin-pi's `remnicDaemonUrl`). A full REMNIC_DAEMON_URL
+// (e.g. "http://macstudio.tailnet:4318" or "https://remnic.internal:443")
+// takes precedence and lets a Codex host talk to a shared central daemon
+// over Tailscale/LAN/VPN. The legacy REMNIC_HOST/REMNIC_PORT pair remains
+// supported as a backward-compat fallback so existing installs and the
+// test harness (which spins a mock on 127.0.0.1:<port>) keep working.
+const RAW_DAEMON_URL = process.env.REMNIC_DAEMON_URL || process.env.ENGRAM_DAEMON_URL || "";
 const HOST = process.env.REMNIC_HOST || process.env.ENGRAM_HOST || "127.0.0.1";
 const PORT = process.env.REMNIC_PORT || process.env.ENGRAM_PORT || "4318";
 
+// Parse once. `protocol` is "http:" or "https:" so https.request is selected
+// for TLS daemons (common for remote/private deployments behind a proxy).
+//
+// An EXPLICIT but invalid REMNIC_DAEMON_URL (missing scheme, typo, e.g.
+// "macstudio:4318") must NOT silently fall through to REMNIC_HOST/REMNIC_PORT —
+// that would route recall/observe/flush to a local daemon and corrupt the wrong
+// memory store. Instead we disable the daemon entirely (all HTTP calls fail
+// open) and surface the misconfiguration once on stderr so the operator fixes
+// the URL rather than debugging silent cross-store writes (#1571 review).
+let DAEMON_CONFIG_ERROR = "";
+const DAEMON_URL = (function resolveDaemonUrl() {
+  if (RAW_DAEMON_URL) {
+    try {
+      const parsed = new URL(RAW_DAEMON_URL);
+      // Require an explicit scheme — a bare "macstudio:4318" parses with
+      // protocol "macstudio:" and would otherwise silently route to localhost.
+      if (parsed.protocol === "http:" || parsed.protocol === "https:") return parsed;
+    } catch {
+      /* handled below */
+    }
+    DAEMON_CONFIG_ERROR =
+      'REMNIC_DAEMON_URL="' + RAW_DAEMON_URL + '" is not a valid http(s) URL — ' +
+      "daemon disabled (recall/observe/flush will no-op). Set a valid " +
+      "http(s):// URL or unset REMNIC_DAEMON_URL to use REMNIC_HOST/REMNIC_PORT.";
+    if (process.env.REMNIC_HOOK_QUIET !== "1") {
+      try { process.stderr.write("[remnic-codex-hook] " + DAEMON_CONFIG_ERROR + "\n"); } catch {}
+    }
+    return null;
+  }
+  try {
+    return new URL(`http://${HOST}:${PORT}`);
+  } catch {
+    return new URL("http://127.0.0.1:4318");
+  }
+})();
+
 // Internal re-entrant mode: post-tool-observe spawns a detached copy of itself
 // so the (slow) observe runs in the background and never blocks Codex past the
 // short PostToolUse timeout — mirroring the original `( … ) & disown`.
 const OBSERVE_WORKER = "__observe-worker__";
 
+// PreCompact tail-drain lock-wait budget (100ms each → ~15s). Bounds how long
+// handlePreCompact waits for a detached PostToolUse observe worker (whose own
+// /observe can run up to 120s) to release the session lock before skipping the
+// drain+flush. 15s covers a typical observe round-trip on a healthy daemon; a
+// pathologically slow worker that outlasts this is left for the next cycle
+// rather than blocking compaction indefinitely. The hooks.json PreCompact
+// timeout accommodates this budget plus the drain observe + LCM flush.
+const _pcRaw = process.env.REMNIC_PRECOMPACT_LOCK_RETRIES;
+const _pcParsed = _pcRaw != null && _pcRaw !== "" ? Number.parseInt(_pcRaw, 10) : 150;
+// 0 is honored (immediate busy-skip); NaN/negative falls back to the 150 default.
+const PRECOMPACT_LOCK_RETRIES = Number.isFinite(_pcParsed) && _pcParsed >= 0 ? _pcParsed : 150;
+
 const LOG_FILES = {
   "session-start": "remnic-session-recall.log",
   "user-prompt-recall": "remnic-user-prompt-recall.log",
   "post-tool-observe": "remnic-post-tool-observe.log",
   "session-end": "remnic-codex-session-end.log",
+  "pre-compact": "remnic-pre-compact.log",
 };
 const LOG_TAGS = {
   "session-start": "codex-session-start",
   "user-prompt-recall": "codex-user-prompt",
   "post-tool-observe": "codex-post-tool",
   "session-end": "codex-stop",
+  "pre-compact": "codex-pre-compact",
 };
 
 function makeLogger(event) {
@@ -190,9 +250,43 @@ function resolveToken() {
   );
 }
 
+// ── Namespace chokepoint (#1571) ─────────────────────────────────────────────
+// Single source of truth for the optional namespace override. EVERY observe and
+// flush body MUST go through withNamespace() so a namespaced Codex install
+// archives + flushes under one key — without it, buffered observations land on
+// the default key while a namespaced flush drains a different (empty) queue, and
+// most in-session memory never flushes before compaction.
+function resolveNamespace() {
+  return process.env.REMNIC_NAMESPACE || process.env.ENGRAM_NAMESPACE || "";
+}
+function withNamespace(body) {
+  const ns = resolveNamespace();
+  if (ns) body.namespace = ns;
+  return body;
+}
+
+// Base path from the daemon URL (for reverse-proxy subpath mounts, e.g.
+// REMNIC_DAEMON_URL=http://gw/remnic). Mirrors plugin-pi's daemon-URL + route
+// concatenation — without this, a path-qualified base URL has its prefix
+// silently dropped and requests hit the host root (#1571 review). Trailing
+// slashes are stripped so "/remnic/" + "/engram/v1/observe" becomes
+// "/remnic/engram/v1/observe"; a bare root ("/") yields "" (no prefix).
+const DAEMON_BASE_PATH = DAEMON_URL ? DAEMON_URL.pathname.replace(/\/+$/, "") : "";
+
 // ── HTTP helpers — return a real success signal (2xx) so callers can decide
-// whether to advance/clear the cursor (fixes the data-loss bug in #1442). ───
+// whether to advance/clear the cursor (fixes the data-loss bug in #1442).
+//
+// All requests route through the parsed DAEMON_URL (#1571), so a Codex host
+// can target a remote/central daemon (Tailscale/LAN/VPN, plain or TLS) by
+// setting REMNIC_DAEMON_URL — same transport contract as @remnic/plugin-pi. ─
+
 function httpPost(urlPath, token, bodyObj, timeoutMs) {
+  if (DAEMON_URL === null) {
+    // Explicit-but-invalid REMNIC_DAEMON_URL — disabled, fail open (see
+    // resolveDaemonUrl). Callers treat this like a dead daemon.
+    return Promise.resolve({ ok: false, status: 0, body: "" });
+  }
+  const transport = DAEMON_URL.protocol === "https:" ? https : http;
   return new Promise((resolve) => {
     let data;
     try {
@@ -201,11 +295,12 @@ function httpPost(urlPath, token, bodyObj, timeoutMs) {
       resolve({ ok: false, status: 0, body: "" });
       return;
     }
-    const req = http.request(
+    const req = transport.request(
       {
-        host: HOST,
-        port: PORT,
-        path: urlPath,
+        protocol: DAEMON_URL.protocol,
+        hostname: DAEMON_URL.hostname,
+        port: DAEMON_URL.port || (DAEMON_URL.protocol === "https:" ? 443 : 80),
+        path: DAEMON_BASE_PATH + urlPath,
         method: "POST",
         headers: {
           Authorization: `Bearer ${token}`,
@@ -240,9 +335,17 @@ function httpPost(urlPath, token, bodyObj, timeoutMs) {
 }
 
 function httpHealthy(timeoutMs) {
+  if (DAEMON_URL === null) return Promise.resolve(false);
+  const transport = DAEMON_URL.protocol === "https:" ? https : http;
   return new Promise((resolve) => {
-    const req = http.request(
-      { host: HOST, port: PORT, path: "/engram/v1/health", method: "GET" },
+    const req = transport.request(
+      {
+        protocol: DAEMON_URL.protocol,
+        hostname: DAEMON_URL.hostname,
+        port: DAEMON_URL.port || (DAEMON_URL.protocol === "https:" ? 443 : 80),
+        path: DAEMON_BASE_PATH + "/engram/v1/health",
+        method: "GET",
+      },
       (res) => {
         res.resume();
         resolve(res.statusCode >= 200 && res.statusCode < 300);
@@ -492,8 +595,17 @@ function migrateTmpCursor(sessionId, cursorFile, log) {
 }
 
 // mkdir-based mutex with stale-lock reaping (10 min). Returns true if acquired.
-function acquireLock(lockFile, log) {
-  for (let i = 0; i < 50; i++) {
+// `retries` bounds the synchronous wait (100ms each). The default (50 → ~5s)
+// suits foreground hooks; PreCompact's tail drain passes a larger budget so it
+// can outlast a detached PostToolUse observe worker holding the lock, ensuring
+// the subsequent flush sees the worker's queued messages instead of racing.
+// 0 means "try once, don't wait/retry" — a free lock is still taken; only a
+// busy lock is skipped immediately (used by the 0-retry test/fleet path). This
+// avoids the degenerate "0 retries skips acquisition entirely" case (#1571
+// review) where a free lock would be wastefully bypassed.
+function acquireLock(lockFile, log, retries = 50) {
+  const attempts = Math.max(1, retries);
+  for (let i = 0; i < attempts; i++) {
     try {
       fs.mkdirSync(lockFile);
       return true;
@@ -605,7 +717,7 @@ async function handleSessionStart(input, token, log) {
   let res = await httpPost(
     "/engram/v1/recall",
     token,
-    { query, sessionKey: sessionId, topK: 12, mode: "auto", codingContext },
+    withNamespace({ query, sessionKey: sessionId, topK: 12, mode: "auto", codingContext }),
     45000,
   );
   if (!res.ok || !res.body) {
@@ -613,7 +725,7 @@ async function handleSessionStart(input, token, log) {
     res = await httpPost(
       "/engram/v1/recall",
       token,
-      { query, sessionKey: sessionId, topK: 8, mode: "minimal", codingContext },
+      withNamespace({ query, sessionKey: sessionId, topK: 8, mode: "minimal", codingContext }),
       20000,
     );
     log(res.ok && res.body ? "minimal recall succeeded" : "minimal recall also failed");
@@ -662,7 +774,7 @@ async function handleUserPromptRecall(input, token, log) {
   const res = await httpPost(
     "/engram/v1/recall",
     token,
-    { query: prompt, sessionKey: sessionId, topK: 8, mode: "minimal" },
+    withNamespace({ query: prompt, sessionKey: sessionId, topK: 8, mode: "minimal" }),
     20000,
   );
   if (!res.ok || !res.body) {
@@ -736,7 +848,7 @@ async function observeWorker(input, token, log) {
     const res = await httpPost(
       "/engram/v1/observe",
       token,
-      { sessionKey: sessionId, messages: newMessages },
+      withNamespace({ sessionKey: sessionId, messages: newMessages }),
       120000,
     );
     if (res.ok) {
@@ -809,7 +921,7 @@ async function handleSessionEnd(input, token, log) {
         const res = await httpPost(
           "/engram/v1/observe",
           token,
-          { sessionKey: sessionId, messages: newMessages },
+          withNamespace({ sessionKey: sessionId, messages: newMessages }),
           30000,
         );
         if (res.ok) {
@@ -849,6 +961,139 @@ async function handleSessionEnd(input, token, log) {
   runMaterialize(log);
 }
 
+// Drain any unobserved transcript tail to /engram/v1/observe under the
+// session's cursor/lock, advancing the cursor only on a successful observe.
+// Shared mid-session drain used by handlePreCompact (the session-end path in
+// handleSessionEnd has its own cursor-removal cleanup and is intentionally not
+// refactored onto this helper to avoid perturbing its retention semantics).
+//
+// Why this exists separately from the LCM flush: /engram/v1/lcm/compaction/flush
+// can only drain work ALREADY queued by prior /observe calls. If a turn landed
+// after the last PostToolUse (e.g. a long user prompt that triggers auto
+// compaction without a Bash tool call in between), that tail is still only in
+// the transcript and would be lost when Codex summarizes/replaces context. So
+// PreCompact must observe the delta FIRST, then ask LCM to flush.
+//
+// Returns "busy" when the session lock could not be acquired within the
+// caller's budget (a detached PostToolUse observe worker is still holding it),
+// so handlePreCompact can SKIP the flush instead of letting it drain nothing
+// and race the worker; true when the tail was observed (or nothing pending);
+// false on parse/observe failure (cursor retained) so the caller can still
+// flush already-queued work. Always fail-open.
+//
+// `lockRetries` (100ms each) bounds how long to wait for a busy worker.
+// The observe body is scoped via withNamespace() so the tail lands on the same
+// key the LCM flush drains (see the namespace chokepoint above).
+async function drainTranscriptTail(sessionId, transcriptPath, token, log, lockRetries = 50) {
+  const safe = sessionId !== "" && !/[^A-Za-z0-9._-]/.test(sessionId);
+  if (!safe || !token || !transcriptPath || !fs.existsSync(transcriptPath)) {
+    return false;
+  }
+  const state = resolveState(sessionId, log);
+  if (!state) return false;
+  const { cursorFile, lockFile } = state;
+  // The lock guards against the detached post-tool observe worker racing this
+  // drain. Wait up to the caller's budget for the worker to finish its /observe
+  // and release the lock — once it does, either the worker already advanced the
+  // cursor (nothing left to drain) or we observe the remaining delta, and in
+  // both cases the subsequent flush sees all queued work. Only if the worker
+  // outlasts our budget do we return "busy" so handlePreCompact SKIPS the flush
+  // rather than racing ahead of the worker's in-flight /observe.
+  if (!acquireLock(lockFile, log, lockRetries)) {
+    log(`transcript tail drain skipped for ${sessionId}: lock busy (worker still running)`);
+    return "busy";
+  }
+  try {
+    migrateTmpCursor(sessionId, cursorFile, log);
+    const lastCount = readCursor(cursorFile, log);
+    if (lastCount === null) {
+      log(`transcript tail drain skipped for ${sessionId}: unsafe cursor`);
+      return false;
+    }
+    let newMessages;
+    try {
+      newMessages = parseTranscript(transcriptPath).slice(lastCount);
+    } catch {
+      log(`transcript tail parse failed for ${sessionId}; cursor retained`);
+      return false;
+    }
+    if (newMessages.length === 0) return true;
+    log(`transcript tail drain: ${newMessages.length} new message(s) for ${sessionId}`);
+    const res = await httpPost(
+      "/engram/v1/observe",
+      token,
+      withNamespace({ sessionKey: sessionId, messages: newMessages }),
+      30000,
+    );
+    if (res.ok) {
+      // Advance (not remove) the cursor — the session continues after compaction,
+      // so the post-compact transcript must not re-observe this tail.
+      writeCursor(cursorFile, lastCount + newMessages.length, log);
+      return true;
+    }
+    log(`transcript tail drain failed for ${sessionId} (http=${res.status}); cursor retained`);
+    return false;
+  } finally {
+    releaseLock(lockFile);
+  }
+}
+
+// PreCompact (#1571) — coordinate with Remnic's LCM layer before Codex
+// compacts the conversation. Mirrors @remnic/plugin-pi's session_before_compact
+// handler, with one Codex-specific addition: because Codex observes
+// asynchronously (PostToolUse on Bash + Stop), an unobserved transcript tail
+// can exist when compaction fires mid-session. So we drain that tail to
+// /engram/v1/observe FIRST, then POST /engram/v1/lcm/compaction/flush so the
+// daemon flushes the now-complete observe buffer into long-term memory before
+// the transcript is summarized. ALWAYS returns continue:true — a hook failure
+// must never block Codex's compaction (the upstream contract notes
+// continue:false stops the compact entirely), so this handler is fail-open
+// end to end.
+async function handlePreCompact(input, token, log) {
+  const sessionId = input.session_id || "";
+  const transcriptPath = input.transcript_path || "";
+  const trigger = input.trigger || "auto";
+  // Acknowledge first so Codex never waits on the network for compaction to
+  // proceed — the drain + flush are best-effort coordination, not a gate.
+  emit({ continue: true });
+  if (!token) {
+    log(`skipping pre-compact drain+flush: no token (session=${sessionId} trigger=${trigger})`);
+    return;
+  }
+  // 1. Drain any unobserved transcript tail so it's archived before compaction.
+  //    Wait up to PRECOMPACT_LOCK_RETRIES for a concurrent observe worker to
+  //    release the session lock, so the flush below sees the worker's queued
+  //    messages. If the worker outlasts us, drain returns "busy" and we SKIP
+  //    the flush entirely — flushing now would drain nothing and the worker's
+  //    in-flight observe would miss this compaction, so we defer to the next
+  //    PreCompact/Stop rather than race.
+  const drainResult = await drainTranscriptTail(
+    sessionId,
+    transcriptPath,
+    token,
+    log,
+    PRECOMPACT_LOCK_RETRIES,
+  );
+  if (drainResult === "busy") {
+    log(`skipping LCM flush: tail drain lock busy (session=${sessionId} trigger=${trigger}); deferring to next cycle`);
+    return;
+  }
+  // 2. Ask the LCM layer to flush the (now-complete) observe buffer. The body is
+  //    scoped via withNamespace() so it drains the same key the observes wrote.
+  const res = await httpPost(
+    "/engram/v1/lcm/compaction/flush",
+    token,
+    withNamespace({ sessionKey: sessionId }),
+    20000,
+  );
+  if (res.ok) {
+    log(`LCM compaction flush OK (session=${sessionId} trigger=${trigger})`);
+  } else {
+    // Fail-open: log and move on. Compaction proceeds regardless.
+    log(`LCM compaction flush failed (http=${res.status}) — compaction proceeds`);
+  }
+}
+
 // ── Codex-native memory materialization (#378) ─────────────────────────────
 function runMaterialize(log) {
   if (process.env.REMNIC_CODEX_MATERIALIZE === "0") return;
@@ -952,6 +1197,9 @@ async function main() {
       case "session-end":
         await handleSessionEnd(input, token, log);
         break;
+      case "pre-compact":
+        await handlePreCompact(input, token, log);
+        break;
     }
   } catch (err) {
     log(`unhandled error in ${event}: ${err && err.message}`);

package/hooks/bin/remnic-codex-hook.test.cjs

@@ -48,6 +48,13 @@ function mkHome() {
 // stays free to answer the runner's requests while it runs.
 function runHook(event, input, { port, home, env = {} } = {}) {
   return new Promise((resolve) => {
+    // When a test asks for "no token" (env.token === null) we must clear BOTH
+    // token env vars — the runner's resolveToken() falls through from
+    // OPENCLAW_REMNIC_ACCESS_TOKEN to OPENCLAW_ENGRAM_ACCESS_TOKEN, and the
+    // parent process (a real dev shell) often has the latter set, which
+    // previously leaked through `...process.env` and made the no-token
+    // assertions fail outside CI (#1571 test-harness hygiene).
+    const noToken = env.token === null;
     const child = spawn(process.execPath, [RUNNER, event], {
       env: {
         ...process.env,
@@ -57,8 +64,13 @@ function runHook(event, input, { port, home, env = {} } = {}) {
         REMNIC_HOST: "127.0.0.1",
         REMNIC_PORT: String(port),
         REMNIC_CODEX_MATERIALIZE: "0",
-        // Default to an env token unless a test overrides it.
-        OPENCLAW_REMNIC_ACCESS_TOKEN: env.token === null ? "" : env.token || "test-token",
+        OPENCLAW_REMNIC_ACCESS_TOKEN: noToken ? "" : env.token || "test-token",
+        OPENCLAW_ENGRAM_ACCESS_TOKEN: noToken ? "" : "",
+        // Clear daemon URL env so a developer shell with REMNIC_DAEMON_URL set
+        // can't route tests away from the mock server. Tests that WANT a daemon
+        // URL override it via env.extra (which spreads last).
+        REMNIC_DAEMON_URL: "",
+        ENGRAM_DAEMON_URL: "",
         ...env.extra,
       },
       stdio: ["pipe", "pipe", "pipe"],
@@ -338,7 +350,7 @@ test("hooks.json: every event resolves via ${PLUGIN_ROOT} and uses powershell (#
   const cfg = JSON.parse(
     fs.readFileSync(path.join(__dirname, "..", "hooks.json"), "utf8"),
   );
-  for (const event of ["SessionStart", "PostToolUse", "UserPromptSubmit", "Stop"]) {
+  for (const event of ["SessionStart", "PostToolUse", "UserPromptSubmit", "Stop", "PreCompact"]) {
     for (const matcher of cfg.hooks[event]) {
       for (const hook of matcher.hooks) {
         // Codex runs plugin hooks from the session cwd via sh -lc / cmd /C and
@@ -510,3 +522,573 @@ test("post-tool worker reads its payload from STDIN end-to-end", async () => {
     fs.rmSync(home, { recursive: true, force: true });
   }
 });
+
+// ── #1571: PreCompact LCM flush + remote/network daemon URL ────────────────
+
+test("pre-compact: POSTs /engram/v1/lcm/compaction/flush and returns continue:true (#1571)", async () => {
+  const home = mkHome();
+  const { server, port, calls } = await startServer((req, res) => {
+    if (req.url === "/engram/v1/lcm/compaction/flush") {
+      return res.writeHead(200, { "Content-Type": "application/json" }).end(
+        JSON.stringify({ ok: true, flushed: 3 }),
+      );
+    }
+    res.writeHead(404).end();
+  });
+  try {
+    const { json } = await runHook(
+      "pre-compact",
+      { session_id: "compact-1", trigger: "manual", turn_id: "t1", cwd: home },
+      { port, home },
+    );
+    assert.deepEqual(json, { continue: true });
+    const flush = calls.find((c) => c.url === "/engram/v1/lcm/compaction/flush");
+    assert.ok(flush, "compaction/flush was called");
+    assert.equal(flush.body.sessionKey, "compact-1");
+    assert.equal(flush.method, "POST");
+    // Auth gating is covered by the no-token test below; the mock helper
+    // does not record headers, so we assert the call happened, not the header.
+  } finally {
+    server.close();
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("pre-compact: no token → bare continue, no flush call (#1571)", async () => {
+  const home = mkHome();
+  const { server, port, calls } = await startServer((req, res) =>
+    res.writeHead(200).end("{}"),
+  );
+  try {
+    const { json } = await runHook(
+      "pre-compact",
+      { session_id: "compact-2", trigger: "auto", cwd: home },
+      { port, home, env: { token: null } },
+    );
+    assert.deepEqual(json, { continue: true });
+    assert.equal(
+      calls.filter((c) => c.url === "/engram/v1/lcm/compaction/flush").length,
+      0,
+      "no flush call without a token",
+    );
+  } finally {
+    server.close();
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("pre-compact: HTTP failure still returns continue:true — never blocks compaction (#1571)", async () => {
+  const home = mkHome();
+  // Daemon up but flush endpoint 500s.
+  const { server, port, calls } = await startServer((req, res) => {
+    if (req.url === "/engram/v1/lcm/compaction/flush") {
+      return res.writeHead(500).end(JSON.stringify({ error: "boom" }));
+    }
+    res.writeHead(404).end();
+  });
+  try {
+    const { json } = await runHook(
+      "pre-compact",
+      { session_id: "compact-3", trigger: "auto", cwd: home },
+      { port, home },
+    );
+    // Critical invariant: a flush failure MUST NOT set continue:false, which
+    // (per the upstream Codex contract) would stop compaction entirely.
+    assert.deepEqual(json, { continue: true });
+    assert.equal(
+      calls.filter((c) => c.url === "/engram/v1/lcm/compaction/flush").length,
+      1,
+      "flush was attempted",
+    );
+  } finally {
+    server.close();
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("pre-compact: dead daemon still returns continue:true (#1571)", async () => {
+  const home = mkHome();
+  const dead = await startServer(() => {});
+  const port = dead.port;
+  dead.server.close();
+  await new Promise((r) => setTimeout(r, 50));
+  const { json } = await runHook(
+    "pre-compact",
+    { session_id: "compact-4", trigger: "auto", cwd: home },
+    { port, home },
+  );
+  assert.deepEqual(json, { continue: true });
+  fs.rmSync(home, { recursive: true, force: true });
+});
+
+test("pre-compact: REMNIC_NAMESPACE attaches a namespace to the flush (#1571)", async () => {
+  const home = mkHome();
+  const { server, port, calls } = await startServer((req, res) =>
+    res.writeHead(200, { "Content-Type": "application/json" }).end('{"ok":true}'),
+  );
+  try {
+    await runHook(
+      "pre-compact",
+      { session_id: "compact-ns", trigger: "manual", cwd: home },
+      { port, home, env: { extra: { REMNIC_NAMESPACE: "team/fleet" } } },
+    );
+    const flush = calls.find((c) => c.url === "/engram/v1/lcm/compaction/flush");
+    assert.ok(flush, "flush called");
+    assert.equal(flush.body.namespace, "team/fleet");
+  } finally {
+    server.close();
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("session-start: REMNIC_DAEMON_URL routes recall to the remote base URL (#1571)", async () => {
+  const home = mkHome();
+  const { server, port, calls } = await startServer((req, res) => {
+    if (req.url === "/engram/v1/health") return res.writeHead(200).end("ok");
+    if (req.url === "/engram/v1/recall") {
+      return res.writeHead(200, { "Content-Type": "application/json" }).end(
+        JSON.stringify({ context: "remote recall", count: 1, mode: "auto" }),
+      );
+    }
+    res.writeHead(404).end();
+  });
+  try {
+    // A full REMNIC_DAEMON_URL must take precedence over the (wrong) PORT.
+    // This proves a Codex host can reach a remote/central daemon over
+    // Tailscale/LAN/VPN — the core #1571 parity ask.
+    const { json } = await runHook(
+      "session-start",
+      { session_id: "remote-1", cwd: home },
+      {
+        port: 1, // deliberately unused; daemon URL wins
+        home,
+        env: { extra: { REMNIC_DAEMON_URL: `http://127.0.0.1:${port}` } },
+      },
+    );
+    assert.equal(json.continue, true);
+    assert.match(json.hookSpecificOutput.additionalContext, /remote recall/);
+    assert.ok(
+      calls.some((c) => c.url === "/engram/v1/recall"),
+      "recall reached the REMNIC_DAEMON_URL host",
+    );
+  } finally {
+    server.close();
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("pre-compact: REMNIC_DAEMON_URL routes the flush to the remote base URL (#1571)", async () => {
+  const home = mkHome();
+  const { server, port, calls } = await startServer((req, res) =>
+    res.writeHead(200, { "Content-Type": "application/json" }).end('{"ok":true}'),
+  );
+  try {
+    await runHook(
+      "pre-compact",
+      { session_id: "remote-flush", trigger: "auto", cwd: home },
+      {
+        port: 1,
+        home,
+        env: { extra: { REMNIC_DAEMON_URL: `http://127.0.0.1:${port}` } },
+      },
+    );
+    assert.ok(
+      calls.some((c) => c.url === "/engram/v1/lcm/compaction/flush"),
+      "flush reached the REMNIC_DAEMON_URL host",
+    );
+  } finally {
+    server.close();
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("runner source: DAEMON_URL honors https:// remotes and falls back to HOST/PORT (#1571)", () => {
+  const src = fs.readFileSync(path.join(__dirname, "remnic-codex-hook.cjs"), "utf8");
+  // Both transports are wired so a TLS remote daemon is reachable.
+  assert.match(src, /const https = require\("https"\)/, "https transport is required");
+  assert.match(
+    src,
+    /DAEMON_URL\.protocol === "https:" \? https : http/,
+    "transport selection honors the daemon URL protocol",
+  );
+  // REMNIC_DAEMON_URL is the primary knob; ENGRAM_DAEMON_URL is the legacy alias.
+  assert.match(src, /REMNIC_DAEMON_URL \|\| process\.env\.ENGRAM_DAEMON_URL/, "daemon URL env precedence");
+  // HOST/PORT remain as a backward-compat fallback.
+  assert.match(src, /new URL\(`http:\/\/\$\{HOST\}:\$\{PORT\}`\)/, "HOST/PORT fallback preserved");
+});
+
+test("pre-compact: drains the unobserved transcript tail to /observe BEFORE the LCM flush (#1571 review)", async () => {
+  // The codex bot pointed out that /lcm/compaction/flush only drains work
+  // already queued by prior /observe calls — if a turn landed after the last
+  // PostToolUse, its tail is still only in the transcript and would be lost
+  // when Codex summarizes. PreCompact must observe the delta first.
+  const home = mkHome();
+  const sessionId = "compact-tail";
+  const tpath = transcript(home, [
+    { role: "user", content: "first turn already observed" },
+    { role: "assistant", content: "response one" },
+    { role: "user", content: "second turn — the unobserved tail" },
+    { role: "assistant", content: "response two" },
+  ]);
+  // Seed a cursor at 2 so the last two messages are the pending tail.
+  fs.mkdirSync(path.join(home, "state", "remnic", "hooks"), { recursive: true });
+  fs.writeFileSync(cursorPath(home, sessionId), "2\n");
+  const order = [];
+  const { server, port, calls } = await startServer((req, res) => {
+    order.push(req.url);
+    if (req.url === "/engram/v1/observe") {
+      return res.writeHead(200, { "Content-Type": "application/json" }).end('{"ok":true}');
+    }
+    if (req.url === "/engram/v1/lcm/compaction/flush") {
+      return res.writeHead(200, { "Content-Type": "application/json" }).end('{"ok":true}');
+    }
+    res.writeHead(404).end();
+  });
+  try {
+    const { json } = await runHook(
+      "pre-compact",
+      { session_id: sessionId, transcript_path: tpath, trigger: "auto", cwd: home },
+      { port, home },
+    );
+    assert.deepEqual(json, { continue: true });
+    // Critical: the observe must precede the LCM flush.
+    const observeIdx = order.indexOf("/engram/v1/observe");
+    const flushIdx = order.indexOf("/engram/v1/lcm/compaction/flush");
+    assert.ok(observeIdx !== -1, "observe (tail drain) was called");
+    assert.ok(flushIdx !== -1, "LCM flush was called");
+    assert.ok(observeIdx < flushIdx, "observe (tail drain) runs BEFORE the LCM flush");
+    // The tail was the 2 unobserved messages.
+    const observe = calls.find((c) => c.url === "/engram/v1/observe");
+    assert.equal(observe.body.messages.length, 2, "exactly the pending tail was observed");
+    // Cursor advanced past the drained tail (not removed — session continues).
+    assert.equal(fs.readFileSync(cursorPath(home, sessionId), "utf8").trim(), "4");
+  } finally {
+    server.close();
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("pre-compact: retains the cursor when the tail-drain observe fails (#1571 review)", async () => {
+  const home = mkHome();
+  const sessionId = "compact-tail-fail";
+  const tpath = transcript(home, [
+    { role: "user", content: "tail that won't drain this time" },
+    { role: "assistant", content: "response" },
+  ]);
+  fs.mkdirSync(path.join(home, "state", "remnic", "hooks"), { recursive: true });
+  fs.writeFileSync(cursorPath(home, sessionId), "0\n");
+  const { server, port } = await startServer((req, res) => {
+    if (req.url === "/engram/v1/observe") return res.writeHead(500).end('{"error":"x"}');
+    if (req.url === "/engram/v1/lcm/compaction/flush") return res.writeHead(200).end('{"ok":true}');
+    res.writeHead(404).end();
+  });
+  try {
+    const { json } = await runHook(
+      "pre-compact",
+      { session_id: sessionId, transcript_path: tpath, trigger: "manual", cwd: home },
+      { port, home },
+    );
+    // Fail-open: compaction still proceeds.
+    assert.deepEqual(json, { continue: true });
+    // Cursor retained at 0 so the tail is retried on the next observe/compact.
+    assert.equal(fs.readFileSync(cursorPath(home, sessionId), "utf8").trim(), "0");
+  } finally {
+    server.close();
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("pre-compact: REMNIC_NAMESPACE also scopes the tail-drain /observe to the same key (#1571 review)", async () => {
+  // chatgpt-codex-connector: the drain posted /observe WITHOUT the namespace
+  // while the flush used it, so a namespaced install queued the tail under the
+  // default key and the flush drained the namespaced key — leaving the tail
+  // unflushed. Both must target the same key.
+  const home = mkHome();
+  const sessionId = "compact-ns-drain";
+  const tpath = transcript(home, [
+    { role: "user", content: "turn one" },
+    { role: "assistant", content: "reply one" },
+    { role: "user", content: "turn two (unobserved tail)" },
+    { role: "assistant", content: "reply two" },
+  ]);
+  fs.mkdirSync(path.join(home, "state", "remnic", "hooks"), { recursive: true });
+  fs.writeFileSync(cursorPath(home, sessionId), "2\n");
+  const { server, port, calls } = await startServer((req, res) =>
+    res.writeHead(200, { "Content-Type": "application/json" }).end('{"ok":true}'),
+  );
+  try {
+    const { json } = await runHook(
+      "pre-compact",
+      { session_id: sessionId, transcript_path: tpath, trigger: "auto", cwd: home },
+      { port, home, env: { extra: { REMNIC_NAMESPACE: "team/fleet" } } },
+    );
+    assert.deepEqual(json, { continue: true });
+    const observe = calls.find((c) => c.url === "/engram/v1/observe");
+    assert.ok(observe, "tail drain observed");
+    assert.equal(observe.body.namespace, "team/fleet", "drain observe carries the namespace");
+    assert.equal(observe.body.messages.length, 2, "drained the pending tail");
+    const flush = calls.find((c) => c.url === "/engram/v1/lcm/compaction/flush");
+    assert.ok(flush, "flush called");
+    assert.equal(flush.body.namespace, "team/fleet", "flush carries the same namespace");
+  } finally {
+    server.close();
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("pre-compact: an invalid explicit REMNIC_DAEMON_URL disables the daemon instead of falling back to localhost (#1571 review)", async () => {
+  // chatgpt-codex-connector: a typo'd URL (no scheme) must NOT silently route to
+  // the REMNIC_HOST/REMNIC_PORT default — that would corrupt the wrong store.
+  // It should disable (fail open) and warn.
+  const home = mkHome();
+  const { server, port, calls } = await startServer((req, res) =>
+    res.writeHead(200).end('{"ok":true}'),
+  );
+  try {
+    const { json, stderr } = await runHook(
+      "pre-compact",
+      { session_id: "bad-url", trigger: "auto", cwd: home },
+      {
+        port, // the localhost fallback target — must NOT be reached
+        home,
+        env: {
+          extra: {
+            REMNIC_DAEMON_URL: "macstudio:4318", // missing scheme → invalid
+            REMNIC_HOOK_QUIET: "1",
+          },
+        },
+      },
+    );
+    // Fail-open: compaction proceeds.
+    assert.deepEqual(json, { continue: true });
+    // No traffic reached the localhost mock server.
+    assert.equal(calls.length, 0, "invalid daemon URL did not fall back to localhost");
+  } finally {
+    server.close();
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("pre-compact: when the session lock stays held, the drain returns busy and the LCM flush is skipped (#1571 review)", async () => {
+  // cursor bugbot: if PreCompact cannot acquire the session observe lock (a
+  // detached PostToolUse worker is still running), flushing now would drain
+  // nothing while the worker's in-flight observe misses this compaction.
+  // Fix: wait a bounded budget, and if still busy, SKIP the flush (defer to the
+  // next cycle) rather than race. Use a tiny budget so the test is fast.
+  const home = mkHome();
+  const sessionId = "compact-busy";
+  const tpath = transcript(home, [
+    { role: "user", content: "turn while worker holds the lock" },
+    { role: "assistant", content: "reply" },
+  ]);
+  const lockDir = path.join(home, "state", "remnic", "hooks", `remnic-lock-${sessionId}.d`);
+  fs.mkdirSync(path.dirname(lockDir), { recursive: true });
+  fs.mkdirSync(lockDir); // simulate the detached worker holding the lock
+  const { server, port, calls } = await startServer((req, res) =>
+    res.writeHead(200, { "Content-Type": "application/json" }).end('{"ok":true}'),
+  );
+  try {
+    const { json } = await runHook(
+      "pre-compact",
+      { session_id: sessionId, transcript_path: tpath, trigger: "auto", cwd: home },
+      { port, home, env: { extra: { REMNIC_PRECOMPACT_LOCK_RETRIES: "2" } } },
+    );
+    assert.deepEqual(json, { continue: true });
+    // Neither the tail drain /observe NOR the LCM flush should have run.
+    assert.ok(
+      !calls.some((c) => c.url === "/engram/v1/lcm/compaction/flush"),
+      "LCM flush was skipped because the drain could not acquire the lock",
+    );
+    assert.ok(
+      !calls.some((c) => c.url === "/engram/v1/observe"),
+      "tail drain /observe was skipped because the lock was held",
+    );
+  } finally {
+    server.close();
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("observe worker: REMNIC_NAMESPACE scopes the PostToolUse /observe (#1571 review)", async () => {
+  // The namespace chokepoint (withNamespace) must cover EVERY observe path, not
+  // just PreCompact. The PostToolUse detached worker archives the bulk of
+  // in-session turns — if it omits namespace while the flush uses it, those
+  // turns land on the default key and never flush before compaction.
+  const home = mkHome();
+  const { server, port, calls } = await startServer((req, res) => res.writeHead(200).end("{}"));
+  try {
+    const tpath = transcript(home, [
+      { role: "user", content: "tool turn one" },
+      { role: "assistant", content: "tool reply one" },
+    ]);
+    await runHook(
+      "__observe-worker__",
+      JSON.stringify({ session_id: "sObsNs", transcript_path: tpath }),
+      { port, home, env: { extra: { REMNIC_NAMESPACE: "fleet/alpha" } } },
+    );
+    const observe = calls.find((c) => c.url === "/engram/v1/observe");
+    assert.ok(observe, "observe was called");
+    assert.equal(observe.body.namespace, "fleet/alpha", "worker observe carries the namespace");
+  } finally {
+    server.close();
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("session-end: REMNIC_NAMESPACE scopes the final-flush /observe (#1571 review)", async () => {
+  // The Stop/session-end final flush must also carry the namespace so the
+  // last tail is archived on the same key everything else uses.
+  const home = mkHome();
+  const { server, port, calls } = await startServer((req, res) => res.writeHead(200).end("{}"));
+  try {
+    const tpath = transcript(home, [{ role: "user", content: "pending tail at session end" }]);
+    fs.mkdirSync(path.join(home, "state", "remnic", "hooks"), { recursive: true });
+    fs.writeFileSync(cursorPath(home, "sEndNs"), "0\n");
+    await runHook(
+      "session-end",
+      { session_id: "sEndNs", transcript_path: tpath },
+      { port, home, env: { extra: { REMNIC_NAMESPACE: "fleet/beta" } } },
+    );
+    const observe = calls.find((c) => c.url === "/engram/v1/observe");
+    assert.ok(observe, "final flush observed");
+    assert.equal(observe.body.namespace, "fleet/beta", "session-end observe carries the namespace");
+  } finally {
+    server.close();
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("pre-compact: REMNIC_PRECOMPACT_LOCK_RETRIES=0 is honored, not coerced to 150 (#1571 kilo review)", async () => {
+  // Number.parseInt(... || "150") || 150 would treat 0 as falsy and fall back
+  // to 150. The explicit finite-check must honor 0 (immediate busy-skip). Hold
+  // the lock and set 0 retries — the hook must return near-instantly without
+  // the ~15s wait a coerced 150 would impose.
+  const home = mkHome();
+  const sessionId = "compact-zero-retries";
+  const tpath = transcript(home, [
+    { role: "user", content: "x" },
+    { role: "assistant", content: "y" },
+  ]);
+  const lockDir = path.join(home, "state", "remnic", "hooks", `remnic-lock-${sessionId}.d`);
+  fs.mkdirSync(path.dirname(lockDir), { recursive: true });
+  fs.mkdirSync(lockDir);
+  const { server, port, calls } = await startServer((req, res) =>
+    res.writeHead(200, { "Content-Type": "application/json" }).end('{"ok":true}'),
+  );
+  try {
+    const start = Date.now();
+    const { json } = await runHook(
+      "pre-compact",
+      { session_id: sessionId, transcript_path: tpath, trigger: "auto", cwd: home },
+      { port, home, env: { extra: { REMNIC_PRECOMPACT_LOCK_RETRIES: "0" } } },
+    );
+    const elapsed = Date.now() - start;
+    assert.deepEqual(json, { continue: true });
+    assert.ok(!calls.some((c) => c.url === "/engram/v1/lcm/compaction/flush"), "flush skipped (busy)");
+    // 0 retries ⇒ no 100ms-poll loop; must be well under the 15s a coerced 150 would add.
+    assert.ok(elapsed < 5000, `0-retries returned in ${elapsed}ms (not coerced to 150)`);
+  } finally {
+    server.close();
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("session-start: a path-prefixed REMNIC_DAEMON_URL routes under the prefix (#1571 review)", async () => {
+  // cursor: a reverse-proxy mount (e.g. http://gw/remnic) must keep its path
+  // prefix — httpPost/httpHealthy prepend DAEMON_BASE_PATH so requests hit
+  // /remnic/engram/v1/... not /engram/v1/... at the host root (parity with
+  // plugin-pi's daemon-URL + route concatenation).
+  const home = mkHome();
+  const { server, port, calls } = await startServer((req, res) => {
+    if (req.url === "/remnic/engram/v1/health") return res.writeHead(200).end("ok");
+    if (req.url === "/remnic/engram/v1/recall") {
+      return res.writeHead(200, { "Content-Type": "application/json" }).end(
+        JSON.stringify({ context: "prefixed recall", count: 1, mode: "auto" }),
+      );
+    }
+    res.writeHead(404).end();
+  });
+  try {
+    const { json } = await runHook(
+      "session-start",
+      { session_id: "prefixed-1", cwd: home },
+      {
+        port: 1,
+        home,
+        env: { extra: { REMNIC_DAEMON_URL: `http://127.0.0.1:${port}/remnic` } },
+      },
+    );
+    assert.equal(json.continue, true);
+    assert.match(json.hookSpecificOutput.additionalContext, /prefixed recall/);
+    assert.ok(
+      calls.some((c) => c.url === "/remnic/engram/v1/recall"),
+      "recall honored the /remnic path prefix",
+    );
+    assert.ok(
+      calls.some((c) => c.url === "/remnic/engram/v1/health"),
+      "health check honored the /remnic path prefix",
+    );
+  } finally {
+    server.close();
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("session-start: REMNIC_NAMESPACE scopes the recall body (#1571 review, parity with plugin-pi)", async () => {
+  // plugin-pi's recall() sets namespace: this.config.namespace on every recall
+  // body. For parity, the Codex recall paths must too — otherwise a namespaced
+  // install recalls from the default key while observing to the namespaced key.
+  const home = mkHome();
+  const { server, port, calls } = await startServer((req, res) => {
+    if (req.url === "/engram/v1/health") return res.writeHead(200).end("ok");
+    if (req.url === "/engram/v1/recall") {
+      return res.writeHead(200, { "Content-Type": "application/json" }).end(
+        JSON.stringify({ context: "namespaced recall", count: 1, mode: "auto" }),
+      );
+    }
+    res.writeHead(404).end();
+  });
+  try {
+    await runHook(
+      "session-start",
+      { session_id: "recall-ns", cwd: home },
+      { port, home, env: { extra: { REMNIC_NAMESPACE: "fleet/gamma" } } },
+    );
+    const recall = calls.find((c) => c.url === "/engram/v1/recall");
+    assert.ok(recall, "recall was called");
+    assert.equal(recall.body.namespace, "fleet/gamma", "recall body carries the namespace (parity with plugin-pi)");
+  } finally {
+    server.close();
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("pre-compact: REMNIC_PRECOMPACT_LOCK_RETRIES=0 still takes a FREE lock (does not skip acquisition) (#1571 review)", async () => {
+  // 0 retries must mean "try once, don't wait" — a free lock is taken and the
+  // drain+flush proceed normally; only a busy lock is skipped immediately.
+  const home = mkHome();
+  const sessionId = "compact-zero-free";
+  const tpath = transcript(home, [
+    { role: "user", content: "free-lock turn" },
+    { role: "assistant", content: "reply" },
+  ]);
+  fs.mkdirSync(path.join(home, "state", "remnic", "hooks"), { recursive: true });
+  fs.writeFileSync(cursorPath(home, sessionId), "0\n");
+  const { server, port, calls } = await startServer((req, res) =>
+    res.writeHead(200, { "Content-Type": "application/json" }).end('{"ok":true}'),
+  );
+  try {
+    const { json } = await runHook(
+      "pre-compact",
+      { session_id: sessionId, transcript_path: tpath, trigger: "auto", cwd: home },
+      { port, home, env: { extra: { REMNIC_PRECOMPACT_LOCK_RETRIES: "0" } } },
+    );
+    assert.deepEqual(json, { continue: true });
+    // Lock was FREE → acquired on the single attempt → drain + flush ran.
+    assert.ok(calls.some((c) => c.url === "/engram/v1/lcm/compaction/flush"), "flush ran (free lock taken despite 0 retries)");
+    assert.ok(calls.some((c) => c.url === "/engram/v1/observe"), "tail drain ran (free lock taken despite 0 retries)");
+  } finally {
+    server.close();
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});

package/hooks/hooks.json

@@ -8,7 +8,7 @@
             "type": "command",
             "command": "\"${PLUGIN_ROOT}/hooks/bin/remnic-codex-hook.sh\" session-start",
             "commandWindows": "powershell -NoProfile -ExecutionPolicy Bypass -File \"${PLUGIN_ROOT}\\hooks\\bin\\remnic-codex-hook.ps1\" session-start",
-            "timeout": 45000
+            "timeout": 45
           }
         ]
       }
@@ -21,7 +21,7 @@
             "type": "command",
             "command": "\"${PLUGIN_ROOT}/hooks/bin/remnic-codex-hook.sh\" post-tool-observe",
             "commandWindows": "powershell -NoProfile -ExecutionPolicy Bypass -File \"${PLUGIN_ROOT}\\hooks\\bin\\remnic-codex-hook.ps1\" post-tool-observe",
-            "timeout": 10000
+            "timeout": 10
           }
         ]
       }
@@ -34,7 +34,7 @@
             "type": "command",
             "command": "\"${PLUGIN_ROOT}/hooks/bin/remnic-codex-hook.sh\" user-prompt-recall",
             "commandWindows": "powershell -NoProfile -ExecutionPolicy Bypass -File \"${PLUGIN_ROOT}\\hooks\\bin\\remnic-codex-hook.ps1\" user-prompt-recall",
-            "timeout": 20000
+            "timeout": 20
           }
         ]
       }
@@ -47,7 +47,20 @@
             "type": "command",
             "command": "\"${PLUGIN_ROOT}/hooks/bin/remnic-codex-hook.sh\" session-end",
             "commandWindows": "powershell -NoProfile -ExecutionPolicy Bypass -File \"${PLUGIN_ROOT}\\hooks\\bin\\remnic-codex-hook.ps1\" session-end",
-            "timeout": 30000
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "manual|auto",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${PLUGIN_ROOT}/hooks/bin/remnic-codex-hook.sh\" pre-compact",
+            "commandWindows": "powershell -NoProfile -ExecutionPolicy Bypass -File \"${PLUGIN_ROOT}\\hooks\\bin\\remnic-codex-hook.ps1\" pre-compact",
+            "timeout": 90
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remnic/plugin-codex",
-  "version": "9.3.689",
+  "version": "9.3.690",
   "description": "Remnic memory plugin for Codex CLI — hooks, skills, MCP integration",
   "type": "module",
   "license": "MIT",
@@ -30,6 +30,6 @@
     ".mcp.json"
   ],
   "dependencies": {
-    "@remnic/core": "^9.3.689"
+    "@remnic/core": "^9.3.690"
   }
 }