@gamaze/hicortex 0.19.0 → 0.19.2

package/dist/index.js

@@ -9,14 +9,29 @@
  * Install once: `openclaw plugins install @gamaze/hicortex`
  * Run server:   `npx @gamaze/hicortex init`
  *
- * Responsibilities (recall-only adapter, like the Hermes plugin):
- *   - before_agent_start  → GET /identity + GET /lessons + POST /recall-index
- *     (fail-soft, 3s timeout each, concurrent) → inject identity + lessons. In
- *     OpenClaw every inbound message spawns an embedded run, so this hook fires
- *     PER TURN with the current prompt and session id — it is the per-turn
- *     /recall-index surface, not just session start.
+ * Responsibilities (recall-only adapter, behaviorally aligned with the Hermes
+ * reference plugin — hermes-plugin/hicortex/provider.py — since #316):
+ *   - before_agent_start  → GET /identity + GET /lessons once per SESSION
+ *     (#316: standing blocks are not re-sent every turn; a FAILED identity
+ *     fetch is retried next turn — only success memoizes, so the #313 dead-man
+ *     banner keeps firing until identity returns) + POST /recall-index EVERY
+ *     turn (fail-soft, concurrent; recall hot path capped at 1.5 s like
+ *     Hermes). The FIRST recall fetch of a session is preceded by an AWAITED
+ *     {reset:true} so a gateway restart resuming a session cannot inherit a
+ *     stale server-side shown-set, and no reset can land after a fetch and
+ *     wipe what it built. In OpenClaw every inbound message spawns an embedded
+ *     run, so this hook fires PER TURN — it is the per-turn /recall-index
+ *     surface, not just session start.
+ *   - 404 on /recall-index → 600 s TTL latch + GET /search fallback that
+ *     renders CONTENT (Hermes's legacy `_format_hits` shape — the pushed
+ *     index's `hicortex_get(id)` menu is useless against the pre-0.14 servers
+ *     the fallback exists for) — old servers keep full-content recall instead
+ *     of degrading to nothing. Auth/5xx errors do NOT latch-fallback (they
+ *     are errors, not version skew): fail soft per turn + warn ONCE per HTTP
+ *     status.
  *   - after_compaction / before_reset → POST /recall-index {reset:true}
- *     (context window rebuilt → the server's per-session shown-set is stale)
+ *     (context window rebuilt → the server's per-session shown-set is stale
+ *     AND the standing blocks may have been dropped → re-injected next turn)
  *   - Tools               → HTTP proxies to /search, /memory, /recent, /ingest, /lessons
  *
  * CAPTURE IS NOT THIS PLUGIN'S JOB. OpenClaw persists sessions at
@@ -26,6 +41,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatToolResults = formatToolResults;
+exports.resolveOcPluginConfig = resolveOcPluginConfig;
 const paths_js_1 = require("./paths.js");
 const features_js_1 = require("./features.js");
 const extensions_js_1 = require("./extensions.js");
@@ -42,7 +58,35 @@ const type_labels_js_1 = require("./type-labels.js");
 const DEFAULT_SERVER_URL = "http://127.0.0.1:8787";
 const LESSONS_TIMEOUT_MS = 3000;
 const IDENTITY_TIMEOUT_MS = 3000;
-const RECALL_TIMEOUT_MS = 3000;
+/**
+ * Recall hot-path ceiling (#316): /recall-index (and /memory via hicortex_get)
+ * run inside every turn / tool call, so a slow or wedged server must cost at
+ * most this much — matching the Hermes reference (client.py RECALL_TIMEOUT
+ * 1.5 s), NOT the general tool ceilings (5–15 s) meant for interactive use.
+ */
+const RECALL_TIMEOUT_MS = 1500;
+/**
+ * Pre-0.14 /search fallback ceiling (#316 CR): its own budget, NOT the pushed-
+ * index hot path — /search runs a server-side embed of the prompt (a cold
+ * embedder loads the ONNX model), which the 1.5 s ceiling can starve. Hermes
+ * gives this exact path its 5 s client default; we match it.
+ */
+const SEARCH_FALLBACK_TIMEOUT_MS = 5000;
+/** Content cap per line in the pre-0.14 /search fallback block — Hermes's
+ *  `_INJECT_CONTENT_CAP` (provider.py): the fallback renders CONTENT (the
+ *  pushed index's one-liner menu is useless here — its `hicortex_get(id)`
+ *  instruction points at a 0.14+ endpoint that 404s on these servers). */
+const LEGACY_CONTENT_CAP = 500;
+/** Default max memories per recall on the legacy /search fallback (config
+ *  `recallLimit`, #316). The pushed /recall-index is sized by SERVER config
+ *  (`recallMaxItems`) — the server accepts no client limit — so this knob
+ *  applies where a client limit actually exists: the pre-0.14 fallback. */
+const DEFAULT_RECALL_LIMIT = 8;
+/** Cap for the per-session LRU trackers (#316 CR: raised from 50 — a
+ *  multi-agent gateway fans sessions across agents; evicting a live session's
+ *  memo only costs ONE re-injection / re-reset, never per-turn spam, so a
+ *  generous cap is cheap insurance. Eviction is accepted behavior.) */
+const SESSION_TRACKER_CAP = 200;
 const HICORTEX_HOME = (0, paths_js_1.hicortexHome)();
 /** Harness name this plugin injects for — used to self-gate on GET /identity `clients`. */
 const THIS_HARNESS = "oc";
@@ -53,14 +97,20 @@ let serverUrl = DEFAULT_SERVER_URL;
 let authToken;
 let hicortexHome = HICORTEX_HOME;
 /** Resolved plugin config captured at service start — used for tunable knobs
- *  (e.g. lessonsLimit) that injected context blocks read at hook time. */
+ *  (e.g. lessonsLimit, recallLimit) that injected context blocks read at hook
+ *  time. */
 let pluginConfig = null;
+/** `defaultProject` from plugin config (#316): sent as the `project` fallback
+ *  on recall-index, the /search fallback, and the search/recent/ingest tools
+ *  whenever the gateway supplies no project (Hermes `default_project`). */
+let defaultProject;
 /** Old-server guard (F2): 0 = not latched; otherwise the Date.now() epoch-ms
- *  until which /recall-index is skipped after a 404 (pre-0.14 server). The
- *  latch EXPIRES so a client-first rollout heals itself once the server is
- *  upgraded — a permanent latch would silently disable recall on a
- *  long-running gateway until restart. OC has no pre-0.14 per-turn recall to
- *  fall back to, so "skip" IS the old behavior. */
+ *  until which /recall-index is skipped after a 404 (pre-0.14 server) and the
+ *  legacy /search fallback is used instead (#316 — full Hermes parity: recall
+ *  degrades to full-content /search injection, not to nothing). The latch
+ *  EXPIRES so a client-first rollout heals itself once the server is
+ *  upgraded — a permanent latch would pin the legacy path on a long-running
+ *  gateway until restart. */
 let recallIndexRetryAtMs = 0;
 /** How long a 404 latches the guard before re-probing. Long enough not to
  *  hammer an old server every turn, short enough that a server upgrade is
@@ -70,11 +120,124 @@ const RECALL_REPROBE_INTERVAL_MS = 600_000;
  *  gateway; if a gateway variant doesn't pass it the feature must not run
  *  silently dead. */
 let warnedMissingSessionId = false;
+/** Warn-once bookkeeping for /recall-index HTTP errors (#316, mirrors Hermes
+ *  review F3): a persistent non-404 error — especially 401/403 from a bad
+ *  token — surfaces at WARNING once per DISTINCT status, then fails soft per
+ *  turn. Without this, a bad token kills per-turn recall with zero logging. */
+const warnedRecallStatuses = new Set();
+/** Warn-once flag for /search fallback failures (#316 CR finding 3): fires on
+ *  the first failure of a streak, re-armed by any successful fallback fetch. */
+let warnedLegacyFallbackFailure = false;
 /** Plugin logger captured at service start (ctx.logger or console). */
 let pluginLog = console.log;
+/** Sessions whose server-side recall dedup was already reset this process
+ *  (#316): the reset rides BEFORE the session's first recall fetch so a
+ *  gateway restart resuming a live session cannot inherit a stale shown-set
+ *  (suppression otherwise persists for recallReshowTurns turns). */
+const sessionsReset = makeBoundedSessionTracker(SESSION_TRACKER_CAP);
+/**
+ * #316 once-per-session standing blocks — per-turn injection is the recall
+ * block ONLY. Two INDEPENDENT memos (#316 CR finding 4): identity and lessons
+ * settle separately (an OK identity + a failed /lessons must not memoize the
+ * lessons away for the whole session), so each block memoizes on its own
+ * success and is skipped only when ITS memo holds.
+ *
+ * PERSISTENCE PREMISE (verified live against the gateway dist on the fleet,
+ * reply-Bm8VrLQh.js, #316 CR finding 1): the gateway composes hook results as
+ * `prependSystemContext + baseSystemPrompt + appendSystemContext` and applies
+ * them via `applySystemPromptOverrideToSession(activeSession, composed)` — the
+ * append PERSISTS on the session across turns. So the once-per-session memo
+ * is not just token hygiene, it is CORRECTNESS: re-sending identity/lessons
+ * every turn would duplicate them into the stored prompt.
+ *
+ * Residual (accepted): after a gateway RESTART resumes a persisted session the
+ * memos are empty while the session may already carry an overridden prompt —
+ * one duplicate append per restart is possible. Whether the override persists
+ * to disk was not determined (no local dist to verify); even in the worst case
+ * the cost is a single duplicated block per restart, never per turn.
+ *
+ * Residual (delta CR N5, accepted): two OVERLAPPING before_agent_start runs
+ * for the same session can both pass has() before either add() — one duplicate
+ * standing append. OC embedded runs are serialized per session in practice;
+ * if that ever changes, an in-flight promise per key (pendingResets shape)
+ * closes it. Not a regression: pre-#316 injected every turn.
+ */
+const identityInjected = makeBoundedSessionTracker(SESSION_TRACKER_CAP);
+const lessonsInjected = makeBoundedSessionTracker(SESSION_TRACKER_CAP);
+/** In-flight {reset:true} POSTs by session key (#316). A compaction hook fires
+ *  a reset fire-and-forget (F9 — no latency on compaction); the NEXT recall
+ *  fetch for that session AWAITS the entry here, so a slow reset can never
+ *  land after the fetch and wipe the shown-set the fetch just built. */
+const pendingResets = new Map();
+/**
+ * Tracker key: `${agentId}:${sessionId}` (#316 CR finding 7) — the trackers
+ * are process-global, and a multi-agent gateway can reuse a session id across
+ * agents; keying on the bare sessionId would let one agent's memo suppress
+ * another's injection. The sanitized agent id charset ([a-z0-9_-]) makes ":"
+ * an unambiguous separator; null id (symbols-only / absent) → "" prefix.
+ */
+function sessionKey(agentId, sessionId) {
+    return `${agentId ?? ""}:${sessionId}`;
+}
+/**
+ * Insertion-ordered Map used as a bounded LRU set of session ids. `has`
+ * touches (re-inserts) the entry; `add` evicts the least-recently-used when
+ * over cap. Long-running gateways see unbounded sessions — the plugin's view
+ * of them must stay bounded.
+ */
+function makeBoundedSessionTracker(cap) {
+    const seen = new Map();
+    return {
+        has(id) {
+            if (!seen.has(id))
+                return false;
+            seen.delete(id);
+            seen.set(id, true);
+            return true;
+        },
+        add(id) {
+            seen.delete(id);
+            seen.set(id, true);
+            if (seen.size > cap) {
+                const oldest = seen.keys().next().value;
+                if (oldest !== undefined)
+                    seen.delete(oldest);
+            }
+        },
+        evict(id) {
+            seen.delete(id);
+        },
+        clear() {
+            seen.clear();
+        },
+    };
+}
 function recallIndexLatched() {
     return recallIndexRetryAtMs !== 0 && Date.now() < recallIndexRetryAtMs;
 }
+/** Recall limit for the legacy /search fallback (#316): config `recallLimit`
+ *  (a POSITIVE INTEGER, default 8). Validated at the boundary like
+ *  readPositiveConfig, but integer-strict (#316 CR 8b): readPositiveConfig +
+ *  Math.floor accepts 0.5 and floors it to 0 — an empty (header-only) fallback
+ *  block. A non-integer or non-positive value warns once and uses 8. */
+let warnedRecallLimitInvalid = false;
+function recallLimit(config) {
+    if (!config)
+        return DEFAULT_RECALL_LIMIT;
+    const v = config.recallLimit;
+    if (v === undefined)
+        return DEFAULT_RECALL_LIMIT;
+    if (typeof v === "number" && Number.isInteger(v) && v > 0)
+        return v;
+    // Warn ONCE (delta CR N2): recallLimit() runs per fallback fetch — a raw
+    // per-turn console.warn on a latched pre-0.14 server is stderr spam, and it
+    // bypassed the gateway's plugin-log capture like no other #316 warning.
+    if (!warnedRecallLimitInvalid) {
+        warnedRecallLimitInvalid = true;
+        pluginLog(`[hicortex] WARNING: config "recallLimit" = ${String(v)} is not a positive integer — using default ${DEFAULT_RECALL_LIMIT}.`);
+    }
+    return DEFAULT_RECALL_LIMIT;
+}
 // ---------------------------------------------------------------------------
 // HTTP helpers
 // ---------------------------------------------------------------------------
@@ -131,33 +294,72 @@ async function serverPost(path, body, timeoutMs) {
         return { ok: false, status: 0, data: null };
     }
 }
-// ---------------------------------------------------------------------------
-// Identity layer — per-agent standing identity (0.13; renamed from context
-// layer in 0.18 #264)
-// ---------------------------------------------------------------------------
 /**
  * Fetch GET /identity (per-agent when an id is supplied) and build the
- * `## Identity` block via the shared gate (gateAndRenderIdentity), or null when
- * nothing should be injected. The old-server guard is required only when an
- * agent id was actually sent (amendment A2 — a bare fetch skips it). The server
- * does the merge; the plugin stays dumb (no client-side mode logic).
+ * `## Identity` block via the shared gate (gateAndRenderIdentity). The
+ * old-server guard is required only when an agent id was actually sent
+ * (amendment A2 — a bare fetch skips it). The server does the merge; the
+ * plugin stays dumb (no client-side mode logic). `failed: true` ONLY when the
+ * fetch itself failed (serverGet null data) — gating to null stays `failed:
+ * false` (the guard fired, or the harness is not in `clients`).
  */
-async function fetchOcIdentityBlock(agentId) {
+async function fetchOcIdentity(agentId) {
     const path = agentId ? `/identity?agent=${encodeURIComponent(agentId)}` : "/identity";
-    const { data } = await serverGet(path, IDENTITY_TIMEOUT_MS);
+    const { data, status } = await serverGet(path, IDENTITY_TIMEOUT_MS);
     if (!data)
-        return null;
-    return (0, learnings_identity_js_1.gateAndRenderIdentity)(data, THIS_HARNESS, { requireAgentEcho: agentId !== null });
+        return { block: null, failed: true, status };
+    return {
+        block: (0, learnings_identity_js_1.gateAndRenderIdentity)(data, THIS_HARNESS, { requireAgentEcho: agentId !== null }),
+        failed: false,
+        status,
+    };
 }
 /**
- * Fetch /lessons and build the `## Hicortex Learnings` block, or null on any
- * failure or when no lessons survive selection. Preserves the pre-0.13 lesson
- * output; the caller prepends the `## Identity` block and adds separators.
+ * Dead-man banner (#313): injected INSTEAD of nothing when the /identity fetch
+ * fails at session start. OC agents are PUBLIC-facing — an agent whose
+ * standing identity (who it is + its conduct rules) could not be fetched must
+ * be told so mechanically, not run voiceless on silence: suspend public
+ * actions until identity returns. A prompt-only sentence is weak; as plugin
+ * behavior it is testable, and the next successful turn replaces it
+ * automatically (the hook re-fetches per turn). Scope: OC plugin only — CC and
+ * Hermes keep plain fail-soft (they are operator-facing harnesses, not
+ * autonomous public agents). A 404 is NOT a banner-worthy failure — version
+ * skew gets IDENTITY_VERSION_SKEW_NOTE (CR2).
+ */
+const IDENTITY_UNAVAILABLE_BANNER = [
+    "## IDENTITY UNAVAILABLE — public actions suspended",
+    "",
+    "The standing identity layer (who this agent is, and its conduct rules) could not be fetched from the memory server. Until it returns:",
+    "- Do NOT take public-facing actions (posting, replying, messaging, purchasing — anything visible to third parties).",
+    "- Do NOT speak or act in the agent persona's voice.",
+    "- Limit yourself to private, reversible work.",
+    "",
+    "This banner stands in for the missing identity block. Restore the Hicortex server; identity is re-fetched on the next turn.",
+].join("\n");
+/**
+ * Version-skew note (#313 CR2): the dead-man banner must NOT fire on a 404.
+ * A plugin pinned in a gateway against a pre-0.12 server (no /identity
+ * route) would otherwise inject "public actions suspended" on EVERY turn —
+ * permanent self-suspension from version skew, with the wrong remediation
+ * (the server is not down, it is old). One diagnostic line, reusing
+ * describeGetFailure's wording; identity injection resumes once the server
+ * is upgraded.
+ */
+const IDENTITY_VERSION_SKEW_NOTE = `[hicortex] Identity layer skipped — ${describeGetFailure(404, "/identity")}. ` +
+    `This is version skew, not an outage: no action suspension applies; identity returns once the server is upgraded.`;
+/**
+ * Fetch /lessons and build the `## Hicortex Learnings` block. `failed: true`
+ * ONLY when the fetch itself failed (serverGet null data — unreachable,
+ * non-2xx, parse error); a successful fetch that selects zero lessons is
+ * `failed: false` with a null block. Preserves the pre-0.13 lesson output;
+ * the caller prepends the `## Identity` block and adds separators.
  */
 async function buildLessonsBlock(project) {
     const { data } = await serverGet("/lessons", LESSONS_TIMEOUT_MS);
-    if (!data || !data.lessons || data.lessons.length === 0)
-        return null;
+    if (!data)
+        return { block: null, failed: true };
+    if (!data.lessons || data.lessons.length === 0)
+        return { block: null, failed: false };
     const maxLessons = (0, features_js_1.lessonsLimit)(pluginConfig);
     const state = (0, state_js_1.loadState)(hicortexHome);
     const moduleIndex = data.moduleIndex ?? state.moduleIndex;
@@ -167,7 +369,7 @@ async function buildLessonsBlock(project) {
         moduleIndex,
     });
     if (selected.length === 0)
-        return null;
+        return { block: null, failed: false };
     const formatted = selected.map((l) => {
         const typeMatch = l.content.match(/\*\*Type:\*\* (\w+)/);
         const severityMatch = l.content.match(/\*\*Severity:\*\* (\w+)/);
@@ -177,23 +379,99 @@ async function buildLessonsBlock(project) {
         const meta = [severityMatch?.[1], typeMatch?.[1]].filter(Boolean).join(", ");
         return `- ${title}${meta ? ` (${meta})` : ""}`;
     });
-    return (`## Hicortex Learnings (auto-injected from long-term memory)\n` +
-        `These are actionable Learnings from past sessions:\n\n` +
-        formatted.join("\n"));
+    return {
+        block: `## Hicortex Learnings (auto-injected from long-term memory)\n` +
+            `These are actionable Learnings from past sessions:\n\n` +
+            formatted.join("\n"),
+        failed: false,
+    };
 }
 // ---------------------------------------------------------------------------
 // Pushed recall index (#193) — per-turn POST /recall-index
 // ---------------------------------------------------------------------------
+/** Arm the pre-0.14 latch and log it — called only on a definitive 404. The
+ *  guard makes the log fire at most ONCE per latch window: two probes can see
+ *  the same 404 inside one turn (session-start reset + recall fetch), and
+ *  while latched no further probe runs to 404 again. Hermes parity (#316):
+ *  the latch note must be visible, not a silent skip to nothing. */
+function latchRecallIndex() {
+    if (recallIndexLatched())
+        return;
+    recallIndexRetryAtMs = Date.now() + RECALL_REPROBE_INTERVAL_MS;
+    pluginLog("[hicortex] /recall-index not on the server (pre-0.14) — recall falls " +
+        "back to /search; re-probing in 10 min.");
+}
 /**
- * Fetch the pushed recall index for this turn, or null when there is nothing
- * to inject (null block, no session id, failure, or a pre-0.14 server). The
- * server does all relevance gating and per-session TURN-based dedup — the
- * plugin sends every turn and carries no tuning constants. A 404 flips the
- * module-level guard so an old server is probed once per gateway process.
+ * Pre-0.14 fallback recall (#316, Hermes parity): GET /search with the turn's
+ * prompt and render CONTENT, not the pushed index's one-liner menu — Hermes's
+ * legacy `_format_hits` shape (`provider.py`): the index shape is useless
+ * here because its `hicortex_get(id)` instruction points at a 0.14+ endpoint
+ * that 404s on exactly the servers this fallback exists for (#316 CR
+ * finding 2). So an old server degrades to full-content recall, not nothing.
+ * Timeout: 5 s (its OWN ceiling — /search embeds the prompt server-side and a
+ * cold embedder loads the ONNX model; this is not the pushed-index hot path).
+ * No per-session dedup exists on this path (same as Hermes's legacy
+ * prefetch); a latched plugin re-probes /recall-index when the TTL expires.
  */
-async function fetchRecallIndexBlock(sessionId, prompt, project) {
-    if (recallIndexLatched())
+async function legacySearchRecallBlock(prompt, project) {
+    const limit = recallLimit(pluginConfig);
+    const params = new URLSearchParams({ query: prompt, limit: String(limit) });
+    const effectiveProject = project ?? defaultProject;
+    if (effectiveProject)
+        params.set("project", effectiveProject);
+    const { data, status } = await serverGet(`/search?${params}`, SEARCH_FALLBACK_TIMEOUT_MS);
+    if (!data || !Array.isArray(data.results)) {
+        // Warn ONCE per failure streak (#316 CR finding 3 — this path was totally
+        // silent): a server old enough to latch the fallback can also be broken
+        // for /search, and a permanently-empty recall must be diagnosable. A
+        // SUCCESSFUL fetch re-arms the warning so a later regression is heard.
+        // Delta CR N4: carry the status (and the token hint for 401/403) so the
+        // operator isn't always told to "check server health" on an auth problem.
+        if (!warnedLegacyFallbackFailure) {
+            warnedLegacyFallbackFailure = true;
+            const tokenHint = status === 401 || status === 403 ? " — check the authToken config" : "";
+            const statusNote = status ? `; last status ${status}` : "";
+            pluginLog("[hicortex] WARNING: /search recall fallback failed — recall is empty " +
+                `while this persists (the server predates /recall-index; check its health${statusNote}${tokenHint}).`);
+        }
         return null;
+    }
+    warnedLegacyFallbackFailure = false;
+    if (data.results.length === 0)
+        return null;
+    // Hermes's `_format_hits` line: `- [YYYY-MM-DD, project] content…` — content
+    // flattened (newlines → spaces) and capped at LEGACY_CONTENT_CAP.
+    const lines = data.results.slice(0, limit).map((r) => {
+        const date = (r.created_at ?? "").slice(0, 10);
+        const proj = r.project || "global";
+        let content = (r.content ?? "").trim().replace(/\n+/g, " ");
+        if (content.length > LEGACY_CONTENT_CAP) {
+            // Code-point truncation (Hermes slices a Python str): a UTF-16 cut at
+            // exactly 500 can split an astral char (emoji are common in chat-derived
+            // memories) and inject a lone surrogate at the boundary.
+            content = `${Array.from(content).slice(0, LEGACY_CONTENT_CAP).join("")}…`;
+        }
+        return `- [${date}, ${proj}] ${content}`;
+    });
+    return [
+        "## Memory recall (auto)",
+        "Relevant prior context from your long-term memory (verify before relying on these — each shows date and project):",
+        ...lines,
+    ].join("\n");
+}
+/**
+ * Fetch the pushed recall index for this turn, or null when there is nothing
+ * to inject (null block, no session id, failure, or a pre-0.14 server on the
+ * /search fallback). The server does all relevance gating and per-session
+ * TURN-based dedup — the plugin sends every turn and carries no tuning
+ * constants. Error taxonomy (#316, Hermes parity):
+ *   - 404   → version skew: latch the TTL guard + fall back to /search THIS
+ *             turn and until the latch expires.
+ *   - other !ok → an error, not a version signal: warn ONCE per distinct
+ *             status (401/403 with a token hint) and fail soft this turn —
+ *             the /search fallback would hit the same wall anyway.
+ */
+async function fetchRecallIndexBlock(sessionId, prompt, project, resetKey) {
     if (!sessionId || !prompt) {
         // Verified against the installed OpenClaw gateway dist (auth-profiles
         // bundle, runEmbeddedPiAgent → hookCtx): before_agent_start receives
@@ -208,40 +486,93 @@ async function fetchRecallIndexBlock(sessionId, prompt, project) {
         }
         return null;
     }
+    if (recallIndexLatched())
+        return legacySearchRecallBlock(prompt, project);
+    // #316 ordering: a pending {reset:true} for THIS session (session-start or
+    // compaction) registered BEFORE this fetch must complete first — a reset
+    // landing after the fetch would wipe the shown-set/turn state the fetch
+    // just built. Awaited by the composite agentId:sessionId key (finding 7)
+    // so concurrent agents on one gateway never wait on each other's resets.
+    // Residual (delta CR N3, accepted): a compaction reset registered WHILE a
+    // same-session fetch is already in flight, or under a degraded compaction
+    // ctx (missing agentId → ":sid" key mismatch), can still land after it —
+    // one turn of re-show, never suppression; sequential turns are covered.
+    await pendingResets.get(resetKey ?? sessionId);
+    // The awaited reset may itself have 404-latched (that is often how the
+    // latch is first discovered) — skip the doomed probe and go to fallback.
+    if (recallIndexLatched())
+        return legacySearchRecallBlock(prompt, project);
     // #203 scope: send the gateway-supplied project so retrieval can apply a soft
     // project-affinity boost (no hard filter — "no hard filters in brains").
-    // Absent ⇒ no scope sent ⇒ no-op (preserves pre-#203 behavior).
+    // Absent ⇒ defaultProject (if configured) ⇒ else no scope sent.
     const body = {
         session_id: sessionId,
         prompt,
     };
-    if (project)
-        body.project = project;
+    const effectiveProject = project ?? defaultProject;
+    if (effectiveProject)
+        body.project = effectiveProject;
     const { ok, status, data } = await serverPost("/recall-index", body, RECALL_TIMEOUT_MS);
     if (status === 404) {
-        recallIndexRetryAtMs = Date.now() + RECALL_REPROBE_INTERVAL_MS;
+        latchRecallIndex();
+        return legacySearchRecallBlock(prompt, project);
+    }
+    if (!ok) {
+        // Warn once per distinct status; network errors (status 0) stay silent —
+        // the server-down case is already surfaced by the startup probe and the
+        // #313 identity banner (Hermes logs those at debug too). Routed through
+        // pluginLog (#316 CR 8a), not raw console.warn: a gateway capturing plugin
+        // logs must not lose the one warning that explains dead recall.
+        if (status > 0 && !warnedRecallStatuses.has(status)) {
+            warnedRecallStatuses.add(status);
+            const hint = status === 401 || status === 403
+                ? " — check the authToken config (or the HICORTEX_AUTH_TOKEN env var)"
+                : "";
+            pluginLog(`[hicortex] WARNING: /recall-index returned HTTP ${status}; recall ` +
+                `injection is disabled while this persists${hint}.`);
+        }
         return null;
     }
-    if (!ok || !data)
+    if (!data)
         return null;
     recallIndexRetryAtMs = 0;
     return typeof data.block === "string" && data.block.trim() !== "" ? data.block : null;
 }
 /**
- * Reset the session's server-side recall dedup — the context window was
- * rebuilt (compaction or session reset), so the shown-set is stale by
- * definition. Fire-and-forget fail-soft: a reset that is lost only means some
- * memories stay suppressed until the re-show window (`recallReshowTurns`)
- * passes.
+ * POST {session_id, reset:true}. Fail-soft: a reset that is lost only means
+ * some memories stay suppressed until the re-show window
+ * (`recallReshowTurns`) passes. The wire session_id stays the RAW gateway
+ * session id (the server registry's key — unchanged contract); only the
+ * LOCAL in-flight map uses the composite agentId:sessionId key.
  */
 async function postRecallReset(sessionId) {
     if (recallIndexLatched())
         return;
-    if (!sessionId)
-        return;
     const { status } = await serverPost("/recall-index", { session_id: sessionId, reset: true }, RECALL_TIMEOUT_MS);
     if (status === 404)
-        recallIndexRetryAtMs = Date.now() + RECALL_REPROBE_INTERVAL_MS;
+        latchRecallIndex();
+}
+/**
+ * Reset the session's server-side recall dedup, deduplicated per session:
+ * concurrent callers share ONE in-flight POST (registered in pendingResets so
+ * the next recall fetch for the session awaits it — see fetchRecallIndexBlock).
+ * `key` is the composite agentId:sessionId (#316 CR finding 7) used for the
+ * LOCAL map only; the wire body carries the raw `sessionId`. Never rejects.
+ */
+function resetRecallDedup(sessionId, key) {
+    const inFlight = pendingResets.get(key);
+    if (inFlight)
+        return inFlight;
+    const p = postRecallReset(sessionId)
+        .catch(() => {
+        /* fail-soft — never surface into the gateway */
+    })
+        .finally(() => {
+        if (pendingResets.get(key) === p)
+            pendingResets.delete(key);
+    });
+    pendingResets.set(key, p);
+    return p;
 }
 // ---------------------------------------------------------------------------
 // Tool result formatter
@@ -256,6 +587,109 @@ function formatToolResults(results) {
     return { content: [{ type: "text", text }] };
 }
 // ---------------------------------------------------------------------------
+// Config resolution
+// ---------------------------------------------------------------------------
+/** Object (not null, not array) → itself as a record; anything else → undefined. */
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v)
+        ? v
+        : undefined;
+}
+function isNonEmptyString(v) {
+    return typeof v === "string" && v.length > 0;
+}
+/** Human name for a config value that failed validation. Only ever called
+ *  with INVALID values (non-strings and empty strings), so the string branch
+ *  means "empty string". */
+function describeInvalid(v) {
+    if (v === null)
+        return "null";
+    if (Array.isArray(v))
+        return "an array";
+    if (typeof v === "string")
+        return "an empty string";
+    return typeof v === "object" ? "an object" : `a ${typeof v}`;
+}
+/**
+ * Resolve the plugin's config from the raw `ctx.config` OC hands the service
+ * (the ENTIRE openclaw.json — verified against gateway-cli createServiceContext:
+ * config = params.cfg — not a per-plugin section). Stateless: touches no module
+ * state, never mutates the input, never throws (console.warn is its only side
+ * effect). Three branches, first match wins:
+ *
+ *   1. `plugins.entries.hicortex.config` — the canonical OC per-plugin
+ *      section. Only eligible when it is a non-null object with ≥1 OWN key:
+ *      OC scaffolds `config: {}` for an installed-but-unconfigured plugin,
+ *      and that empty object must not shadow real config further down.
+ *   2. `hicortex` at the top level — but only when `typeof === "object"`:
+ *      a string/bool/number there (e.g. `"hicortex": true` as a feature
+ *      toggle) is not a config and is skipped, not cast.
+ *   3. the top level itself — bare keys (`serverUrl`, `authToken`, …) at the
+ *      root of openclaw.json; the pre-0.19 shape, kept for backcompat.
+ *
+ * `serverUrl` and `authToken` are validated at this boundary: a present but
+ * non-string (or empty-string) value warns naming the key and degrades —
+ * serverUrl falls back to DEFAULT_SERVER_URL, authToken to undefined. No
+ * throw paths: a malformed config degrades to defaults instead of leaving
+ * the plugin half-initialized.
+ */
+function resolveOcPluginConfig(raw) {
+    const warn = (msg) => console.warn(`[hicortex] WARNING: ${msg}`);
+    const full = isRecord(raw) ?? {};
+    // Branch 1 — isRecord at every level: a missing key, string, array, or
+    // null anywhere in the chain just falls through to the next branch.
+    const plugins = isRecord(full.plugins);
+    const entries = isRecord(plugins?.entries);
+    const entry = isRecord(entries?.hicortex);
+    const entryConfig = isRecord(entry?.config);
+    const nested = entryConfig !== undefined && Object.keys(entryConfig).length > 0
+        ? entryConfig
+        : undefined;
+    // Branch 2 — top-level `hicortex`, object-guarded (see doc block).
+    const hicortexObj = isRecord(full.hicortex);
+    const winner = nested ?? hicortexObj ?? full;
+    const winnerPath = nested !== undefined
+        ? "plugins.entries.hicortex.config"
+        : hicortexObj !== undefined ? "hicortex" : "the top level of openclaw.json";
+    // Copy, never the caller's object: sanitizing below must not mutate
+    // ctx.config, and pluginConfig must not alias OC's config state.
+    const resolved = { ...winner };
+    const rawUrl = winner.serverUrl;
+    if (rawUrl !== undefined && !isNonEmptyString(rawUrl)) {
+        warn(`plugin config key "serverUrl" must be a non-empty string (got ${describeInvalid(rawUrl)}) ` +
+            `— falling back to ${DEFAULT_SERVER_URL}`);
+        resolved.serverUrl = DEFAULT_SERVER_URL;
+    }
+    const rawToken = winner.authToken;
+    if (rawToken !== undefined && !isNonEmptyString(rawToken)) {
+        warn(`plugin config key "authToken" must be a non-empty string (got ${describeInvalid(rawToken)}) — ignoring it`);
+        resolved.authToken = undefined;
+    }
+    const rawProject = winner.defaultProject;
+    if (rawProject !== undefined && !isNonEmptyString(rawProject)) {
+        warn(`plugin config key "defaultProject" must be a non-empty string (got ${describeInvalid(rawProject)}) — ignoring it`);
+        resolved.defaultProject = undefined;
+    }
+    // Shadow detection (F2) — two configs disagreeing, surfaced instead of
+    // silently honoring one of them. Case 1: an OC-scaffolded EMPTY
+    // plugins.entries.hicortex.config was skipped while a bare top-level
+    // serverUrl exists (the exact shape the ≥1-own-key rule exists for).
+    // Gate on the ACTUAL winner (re-CR F1): in the compound shape (empty
+    // nested config + a top-level hicortex object + bare serverUrl) the hicortex
+    // object wins — the warn must not claim the bare key is being used.
+    if (nested === undefined && entryConfig !== undefined && winner === full && isNonEmptyString(full.serverUrl)) {
+        warn(`plugins.entries.hicortex.config is empty, so the top-level serverUrl is used instead — ` +
+            `remove the empty config section or move serverUrl into it`);
+    }
+    // Case 2: a real nested/hicortex section won the chain but carries no valid
+    // serverUrl, while a bare top-level serverUrl is set and will NOT be read.
+    if (winner !== full && !isNonEmptyString(rawUrl) && isNonEmptyString(full.serverUrl)) {
+        warn(`top-level serverUrl is set but ${winnerPath} takes precedence and has no valid serverUrl — ` +
+            `the plugin will NOT use the top-level value; move serverUrl into ${winnerPath}`);
+    }
+    return resolved;
+}
+// ---------------------------------------------------------------------------
 // Plugin export
 // ---------------------------------------------------------------------------
 exports.default = {
@@ -269,20 +703,44 @@ exports.default = {
         api.registerService({
             id: "hicortex-service",
             async start(ctx) {
-                const config = (ctx.config ?? {});
+                // OC passes the ENTIRE openclaw.json as ctx.config (verified against
+                // gateway-cli createServiceContext: config = params.cfg), not a
+                // per-plugin section. resolveOcPluginConfig picks our section out of
+                // it (branch order documented on the function) and validates the
+                // scalar keys at the boundary. It never throws, so a malformed config
+                // can only degrade (warn + default), never half-initialize the plugin.
+                const config = resolveOcPluginConfig(ctx.config);
                 pluginConfig = config;
                 const log = ctx.logger
                     ? (msg) => ctx.logger.info(msg)
                     : console.log;
-                // Resolve server URL and auth token from plugin config
-                serverUrl = (config.serverUrl ?? DEFAULT_SERVER_URL).replace(/\/+$/, "");
-                authToken = config.authToken;
+                // Resolve server URL and auth token: plugin config first, then the
+                // HICORTEX_URL / HICORTEX_AUTH_TOKEN env vars as FALLBACKS when config
+                // omits them (#316). Deliberate divergence from Hermes (whose env
+                // OVERRIDES its config file): openclaw.json is operator-managed via
+                // the gateway UI, so an env var silently winning over it would
+                // surprise; here env only fills gaps (empty env values = unset).
+                const envUrl = process.env.HICORTEX_URL?.trim();
+                const envToken = process.env.HICORTEX_AUTH_TOKEN?.trim();
+                serverUrl = (config.serverUrl ?? (envUrl || undefined) ?? DEFAULT_SERVER_URL)
+                    .replace(/\/+$/, "");
+                authToken = config.authToken ?? (envToken || undefined);
+                defaultProject = config.defaultProject;
                 // Use stateDir from context so tests can redirect state writes
                 hicortexHome = ctx.stateDir ?? HICORTEX_HOME;
                 // Re-probe /recall-index support on every (re)start — the server may
-                // have been upgraded while the gateway was down.
+                // have been upgraded while the gateway was down. Session trackers
+                // reset too: a restarted gateway re-injects standing blocks and re-
+                // resets the dedup for any session it resumes.
                 recallIndexRetryAtMs = 0;
                 warnedMissingSessionId = false;
+                warnedRecallStatuses.clear();
+                warnedLegacyFallbackFailure = false;
+                warnedRecallLimitInvalid = false;
+                sessionsReset.clear();
+                identityInjected.clear();
+                lessonsInjected.clear();
+                pendingResets.clear();
                 pluginLog = log;
                 log(`[hicortex] Thin-client mode — server: ${serverUrl}`);
                 // License: init feature cache (only needs licenseKey, no DB access)
@@ -297,10 +755,13 @@ exports.default = {
                     // header when a token actually exists — an empty `Bearer ` header
                     // is worse than absent (it can trip strict middlewares and signals
                     // a misconfigured client). When there's no token, fall straight to
-                    // the public /health liveness probe below.
+                    // the public /health liveness probe below. Uses the RESOLVED token
+                    // (config ?? env, #316 CR finding 5) — an env-token deployment must
+                    // not probe unauthenticated and log a misleading "diagnostics
+                    // gated" line every start.
                     const headers = {};
-                    if (config.authToken)
-                        headers.Authorization = `Bearer ${config.authToken}`;
+                    if (authToken)
+                        headers.Authorization = `Bearer ${authToken}`;
                     const resp = await fetch(`${serverUrl}/health/detail`, {
                         signal: AbortSignal.timeout(5000),
                         headers,
@@ -352,15 +813,68 @@ exports.default = {
                 // sanitizes to null → bare /identity → global set). Null id never sends
                 // ?agent=, so an old server behaves exactly as before.
                 const agentId = (0, identity_store_js_1.sanitizeAgentId)(ctx?.agentId ?? "");
-                // Fetch all three concurrently with INDEPENDENT fail-soft: no block
-                // may ever cost another. Order in the injected output: `## Identity`
-                // (standing identity, 0.13) → `## Hicortex Learnings` → the per-turn
-                // `## Memory recall (auto)` index (#193, closest to the prompt).
-                const [identityBlock, lessonsBlock, recallBlock] = await Promise.all([
-                    fetchOcIdentityBlock(agentId).catch(() => null),
-                    buildLessonsBlock(ctx?.project).catch(() => null),
-                    fetchRecallIndexBlock(ctx?.sessionId, event?.prompt, ctx?.project).catch(() => null),
+                const sessionId = ctx?.sessionId || undefined;
+                const prompt = event?.prompt;
+                // Composite tracker/reset key (#316 CR finding 7): agentId + sessionId.
+                const sKey = sessionId !== undefined ? sessionKey(agentId, sessionId) : undefined;
+                // #316 session-start dedup reset (Hermes initialize parity): the
+                // FIRST recall fetch of a session is preceded by an {reset:true} —
+                // a gateway restart resuming a live session would otherwise inherit
+                // a stale server-side shown-set (suppression for up to
+                // recallReshowTurns turns). Registered SYNCHRONOUSLY here (before
+                // the fetch below) and awaited by fetchRecallIndexBlock, so it can
+                // never land after the fetch and wipe what it built. Gated on a
+                // real prompt+session: no recall traffic without a real turn.
+                if (sessionId && sKey !== undefined && prompt && !sessionsReset.has(sKey)) {
+                    sessionsReset.add(sKey);
+                    void resetRecallDedup(sessionId, sKey);
+                }
+                // #316 once-per-session standing blocks: `## Identity` +
+                // `## Hicortex Learnings` are injected on a session's FIRST turn
+                // only (they PERSIST on the session prompt — see the tracker docs);
+                // subsequent turns inject the per-turn recall block alone. The two
+                // blocks memoize INDEPENDENTLY (CR finding 4): identity on identity
+                // success, lessons on a successful lessons fetch — an OK identity +
+                // a failed /lessons must not bury the learnings for the session.
+                // Without a sessionId there is no per-session key — inject per turn
+                // (pre-#316 shape) rather than never.
+                const skipIdentity = sKey !== undefined && identityInjected.has(sKey);
+                const skipLessons = sKey !== undefined && lessonsInjected.has(sKey);
+                const [identity, lessons, recallBlock] = await Promise.all([
+                    skipIdentity
+                        ? Promise.resolve(null)
+                        : fetchOcIdentity(agentId).catch(() => ({ block: null, failed: true, status: null })),
+                    skipLessons
+                        ? Promise.resolve(null)
+                        : buildLessonsBlock(ctx?.project).catch(() => ({ block: null, failed: true })),
+                    fetchRecallIndexBlock(sessionId, prompt, ctx?.project, sKey).catch(() => null),
                 ]);
+                // Memoize each block ONLY on its own success (#313 + #316): a
+                // FAILED identity fetch (banner / version-skew note) must retry next
+                // turn — the banner's "identity is re-fetched on the next turn"
+                // promise stays true — and a failed /lessons fetch must retry too.
+                // A gated identity response (no echo, oc ∉ clients, mode off) and
+                // an empty-but-successful lessons fetch are settled outcomes and
+                // memoize like any other success.
+                if (!skipIdentity && sKey !== undefined && identity !== null && !identity.failed) {
+                    identityInjected.add(sKey);
+                }
+                if (!skipLessons && sKey !== undefined && lessons !== null && !lessons.failed) {
+                    lessonsInjected.add(sKey);
+                }
+                // Dead-man enforcement (#313): a FAILED identity fetch injects the
+                // hard banner in the identity slot — never silence. Two non-failure
+                // exceptions: a gated-null (old-server guard, harness not in
+                // clients) stays silent, and a 404 is version skew — the one-line
+                // note, NOT the banner (CR2: a pinned plugin on an old server must
+                // not self-suspend every turn). Lessons/recall keep their own
+                // independent fail-soft.
+                const identityBlock = identity !== null && identity.block !== null
+                    ? identity.block
+                    : identity !== null && identity.failed
+                        ? (identity.status === 404 ? IDENTITY_VERSION_SKEW_NOTE : IDENTITY_UNAVAILABLE_BANNER)
+                        : null;
+                const lessonsBlock = lessons !== null ? lessons.block : null;
                 const blocks = [identityBlock, lessonsBlock, recallBlock].filter((b) => b !== null && b !== "");
                 if (blocks.length === 0)
                     return {};
@@ -371,18 +885,32 @@ exports.default = {
             }
         });
         // -----------------------------------------------------------------------
-        // Hooks: after_compaction / before_reset — reset the session's recall
-        // dedup (#193). Both rebuild the context window, so the server's
-        // per-session shown-set no longer reflects what the agent can see.
-        // Unknown hook names are ignored by older gateways (typed-hook registry
-        // warns and drops them), so registering both is safe everywhere.
+        // Hooks: after_compaction / before_reset — the context window was
+        // rebuilt (#193): the server's per-session shown-set no longer reflects
+        // what the agent can see, and the standing blocks injected on earlier
+        // turns may have been dropped from the rebuilt window — so the session's
+        // memo is evicted and the next turn re-injects them (#316; once per
+        // rebuild, never per turn). Unknown hook names are ignored by older
+        // gateways (typed-hook registry warns and drops them), so registering
+        // both is safe everywhere.
         // -----------------------------------------------------------------------
         const recallResetHook = (_event, ctx) => {
+            const sid = ctx?.sessionId || undefined;
+            if (!sid)
+                return;
+            // Same composite key as before_agent_start (finding 7) — an agent id
+            // absent from the compaction ctx degrades to the bare-session key, and
+            // the eviction may miss (accepted: one duplicate standing injection).
+            const key = sessionKey((0, identity_store_js_1.sanitizeAgentId)(ctx?.agentId ?? ""), sid);
             // Genuinely fire-and-forget (F9): no await — a slow server must never
-            // add latency to compaction or session reset in the gateway.
-            void postRecallReset(ctx?.sessionId).catch(() => {
-                /* fail-soft — never surface into the gateway */
-            });
+            // add latency to compaction or session reset in the gateway. The race
+            // with the next turn's recall fetch is closed by ORDERING (#316), not
+            // by awaiting here: resetRecallDedup registers the POST in
+            // pendingResets, and fetchRecallIndexBlock awaits that entry before
+            // fetching — the reset can no longer land after the fetch.
+            void resetRecallDedup(sid, key);
+            identityInjected.evict(key);
+            lessonsInjected.evict(key);
         };
         api.on("after_compaction", recallResetHook);
         api.on("before_reset", recallResetHook);
@@ -406,8 +934,9 @@ exports.default = {
                     const params = new URLSearchParams({ query: args.query });
                     if (args.limit)
                         params.set("limit", String(args.limit));
-                    if (args.project)
-                        params.set("project", args.project);
+                    const projectFilter = args.project ?? defaultProject;
+                    if (projectFilter)
+                        params.set("project", projectFilter);
                     const { data, status } = await serverGet(`/search?${params}`, 10000);
                     if (!data)
                         return { error: `Search failed: ${describeGetFailure(status, "/search")}` };
@@ -433,7 +962,7 @@ exports.default = {
                     if (!args?.id)
                         return { error: "id is required" };
                     const params = new URLSearchParams({ id: String(args.id) });
-                    const { data, status } = await serverGet(`/memory?${params}`, 10000);
+                    const { data, status } = await serverGet(`/memory?${params}`, RECALL_TIMEOUT_MS);
                     if (status === 404) {
                         // Either no such memory (0.14+) or a pre-0.14 server with no
                         // /memory endpoint — the id hint covers the common case.
@@ -464,8 +993,9 @@ exports.default = {
             async execute(_callId, args, _ctx) {
                 try {
                     const params = new URLSearchParams();
-                    if (args?.project)
-                        params.set("project", args.project);
+                    const projectFilter = args?.project ?? defaultProject;
+                    if (projectFilter)
+                        params.set("project", projectFilter);
                     if (args?.limit)
                         params.set("limit", String(args.limit));
                     const qs = params.toString();
@@ -500,7 +1030,7 @@ exports.default = {
                     const result = await serverPost("/ingest", {
                         content: args.content,
                         source_agent: `openclaw/${context?.agentId ?? "manual"}`,
-                        project: args.project,
+                        project: args.project ?? defaultProject,
                         memory_type: args.memory_type ? (0, type_labels_js_1.normalizeMemoryType)(args.memory_type) : "experience",
                     }, 15000);
                     if (!result.ok) {