@gamaze/hicortex 0.19.1 → 0.19.2

package/README.md

@@ -314,7 +314,10 @@ Optional config (add to plugin entry in `~/.openclaw/openclaw.json`):
 |-------|---------|-------------|
 | `serverUrl` | `http://127.0.0.1:8787` | Hicortex server URL. Change for remote servers. |
 | `authToken` | _(none)_ | Bearer token. Localhost bypasses auth; required for remote servers. Get the token from `hicortex status` on the server. |
-| `licenseKey` | _(none)_ | Commercial license key. Optional; only affects the display in `hicortex status`. |
+| `defaultProject` | _(none)_ | Project name sent on recall, search, recent, and ingest whenever the gateway supplies no project (Hermes `default_project` parity). |
+| `recallLimit` | `8` | Max memories per recall on the pre-0.14 `/search` fallback. The pushed recall index is sized by SERVER config (`recallMaxItems`) — the server accepts no client limit. |
+
+If `serverUrl`/`authToken` are absent from the config, the `HICORTEX_URL` and `HICORTEX_AUTH_TOKEN` environment variables are used as fallbacks (config always wins).
 
 ## LLM Configuration
 

package/assets/identity.html

@@ -291,6 +291,17 @@
     }
   })();
 
+  // Deep link (#313): /identity/ui?agent=<id> opens the editor in that
+  // agent's scope. The param STAYS in the URL (shareable bookmark; unlike
+  // ?token= it is not a secret). It cannot be adopted before the first load —
+  // the bare GET is what populates the `agents` map the scope selector needs —
+  // so it is stashed here and applied in load()'s success path.
+  var pendingScope = null;
+  (function initScopeParam() {
+    var p = new URLSearchParams(window.location.search).get("agent");
+    if (p) pendingScope = p;
+  })();
+
   // Shared console nav (#249): append ?token= to internal nav links on click
   // so navigation between pages doesn't re-authenticate. Reads token from any
   // page-scoped localStorage key (each page historically used its own).
@@ -374,23 +385,32 @@
   var active = null;        // active section name
 
   // Display labels for known sections (the API key stays lowercase; the UI
-  // shows a friendlier name). Unknown sections display their raw name.
+  // shows a friendlier name). Unknown sections display their raw name. The
+  // three #313 scope labels mirror SECTION_LABELS in identity-store.ts —
+  // keep in sync ("Global rules" marks the section as fleet-wide).
   var DISPLAY_LABELS = {
+    "agent_identity": "Agent identity",
     "user": "User",
-    "rules": "Rules",
+    "rules": "Global rules",
     "memory": "Memory instructions",
   };
   // Preferred tab order — known sections first in this order, then any custom
-  // sections alphabetically.
-  var TAB_PRIORITY = ["user", "rules", "memory"];
+  // sections alphabetically. Mirrors the #313 served precedence
+  // (SECTION_PRECEDENCE in identity-store.ts): the agent's own identity
+  // first, then the principal, then fleet rules.
+  var TAB_PRIORITY = ["agent_identity", "user", "rules", "memory"];
   var afterAuth = null;     // action to retry after a successful token prompt
 
   // Per-agent scope (0.13). scope = null → the global set; otherwise an agent
   // id, and edits target PUT /identity?agent=<id>. `agents` is the id -> mode
   // map from the bare (global) GET; `origins` is the id -> "global"|"agent"
   // provenance from an agent-scope GET (used to dim inherited tabs).
+  // `agents` is PROTOTYPE-LESS (Object.create(null)): a lookup like
+  // agents["constructor"] must miss so a bogus ?agent= id cannot slip through
+  // the registration check via the Object.prototype chain (CR5). Every
+  // assignment from server data re-sanitizes into a fresh prototype-less map.
   var scope = null;
-  var agents = {};
+  var agents = Object.create(null);
   var origins = {};
 
   // ?agent= query for the active scope. Written so the literal fetch("/identity"
@@ -425,7 +445,12 @@
       var inherited = scope && origins[name] === "global";
       b.className = "tab" + (name === active ? " active" : "") + (inherited ? " inherited" : "");
       b.type = "button";
-      b.appendChild(document.createTextNode(DISPLAY_LABELS[name] || name));
+      // Own-property lookup (CR-A): a section legitimately named "constructor"
+      // must display its raw name — DISPLAY_LABELS[name] would resolve through
+      // the Object.prototype chain.
+      b.appendChild(document.createTextNode(
+        Object.prototype.hasOwnProperty.call(DISPLAY_LABELS, name) ? DISPLAY_LABELS[name] : name
+      ));
       if (inherited) {
         var inh = document.createElement("span");
         inh.className = "inh";
@@ -505,8 +530,12 @@
         overlay.classList.remove("open");
         // The bare (global) response carries the `agents` map; an agent-scope
         // response carries `origins`. Retain the last-known agents list when the
-        // current response omits it so the selector stays populated.
-        if (scope === null && data.agents && typeof data.agents === "object") agents = data.agents;
+        // current response omits it so the selector stays populated. Copied
+        // into a PROTOTYPE-LESS map (CR5): `agents` is keyed by client- and
+        // server-supplied ids, and lookups must never hit Object.prototype.
+        if (scope === null && data.agents && typeof data.agents === "object") {
+          agents = Object.assign(Object.create(null), data.agents);
+        }
         origins = (data.origins && typeof data.origins === "object") ? data.origins : {};
         var incoming = data.sections || {};
         var names = Object.keys(incoming).sort(function (a, b) {
@@ -529,9 +558,27 @@
         populateScopeOptions();
         renderTabs();
         setMsg(order.length ? "" : "", "dim");
+        // Deep link (#313): adopt the stashed ?agent= scope now that the
+        // agents map is loaded. An unknown-but-valid id registers locally as
+        // "override" (same as Add agent — the dir is created on first Save);
+        // an INVALID id is dropped, landing on Global rather than erroring.
+        if (pendingScope) {
+          var want = pendingScope;
+          pendingScope = null;
+          if (validName(want)) {
+            if (!agents[want]) agents[want] = "override";
+            switchScope(want);
+          }
+        }
       })
       .catch(function (err) {
+        // unauthorized: load() is retried after the token prompt (afterAuth)
+        // — the deep link may still adopt on that retry, so keep pendingScope.
         if (err.message === "unauthorized") return;
+        // A FAILED load must not leave the deep link armed: the user may
+        // manually switch scope meanwhile, and the next successful load would
+        // yank them back to the ?agent= scope (CR5). Cancel it here.
+        pendingScope = null;
         setMsg("Failed to load: " + err.message, "err");
       });
   }
@@ -624,6 +671,10 @@
   }
 
   function switchScope(next) {
+    // A manual switch CANCELS a pending ?agent= deep link (CR5): the deep
+    // link only ever applies to the FIRST successful load. The adoption path
+    // also routes through here, after clearing pendingScope itself.
+    pendingScope = null;
     if (anyDirty() && !window.confirm("Discard unsaved changes and switch scope?")) {
       scopeSel.value = scope || "";
       return;

package/dist/identity-store.d.ts

@@ -26,6 +26,12 @@
  * `context/`), reads ADDITIVELY MERGE: per-section `identity/` wins, and
  * legacy-only sections are included so nothing is lost — at both the global
  * and the per-agent (`agents/<id>/`) level.
+ *
+ * #313 adds the per-agent `agent_identity` section (who THIS agent is + its
+ * role conduct; per-agent ONLY, never global) and makes the served section
+ * order a defined contract — see SECTION_PRECEDENCE below. `user` remains the
+ * PRINCIPAL (global) and `rules` the fleet-wide house rules (never
+ * overridden per-agent: section-level replacement would shadow them).
  */
 /** A valid section name: lowercase alnum start, then alnum / `_` / `-`. */
 export declare const SECTION_NAME_RE: RegExp;
@@ -116,6 +122,49 @@ export declare function migrateIdentityDir(home: string): {
     to: string;
     reason?: string;
 };
+/**
+ * The order sections are SERVED in (#313): `agent_identity` → `user` →
+ * `rules`, then every other section alphabetically. Semantics behind the
+ * order:
+ *  - `agent_identity` — who THIS agent is (name, origin, character, voice,
+ *    genuine interests) plus its role conduct; per-agent only, at
+ *    `identity/agents/<id>/agent_identity.md`. It leads so the agent reads
+ *    its own self before anything else.
+ *  - `user` — the PRINCIPAL the whole fleet serves (global, never the agent).
+ *  - `rules` — fleet-wide house rules. Global only: section-level replacement
+ *    means a per-agent rules.md would SHADOW house rules, so role-specific
+ *    conduct lives INSIDE agent_identity.md (additive by construction).
+ * Before #313 this ordering rode on file-read order (readdirSync, FS-dependent)
+ * where it existed at all — now it is a defined, tested contract. The SAME
+ * list is shared by the client renderers (orderSectionNames in
+ * learnings-identity.ts imports it; the Hermes plugin mirrors it) so server
+ * and clients can never drift: the precedence is defined ONCE, here.
+ */
+export declare const SECTION_PRECEDENCE: readonly ["agent_identity", "user", "rules"];
+/**
+ * Scope display labels (#313): ONE map, consumed by the injected-block
+ * renderer (renderIdentityBlock — CC hook + OC plugin + MCP tool), the UI
+ * editor (DISPLAY_LABELS mirrors it), and the Hermes plugin (mirror in
+ * provider.py). "Global rules" says what the section IS (fleet-wide house
+ * rules), distinguishing it from per-agent content. Unknown section names
+ * fall back to title-case (titleCaseSection) — no file renames, the API keys
+ * stay the section names on disk.
+ */
+export declare const SECTION_LABELS: Readonly<Record<string, string>>;
+/**
+ * Rebuild a sections record with its keys inserted in SECTION_PRECEDENCE
+ * order, then the rest alphabetically. Pure: same values, same (string) keys,
+ * deterministic order — JSON serialisation preserves insertion order, so this
+ * IS the wire contract. Idempotent; a map with no known primaries is just
+ * alphabetised.
+ *
+ * DOCUMENTED EXCEPTION: a canonically-numeric section name (e.g. "42") is an
+ * integer-index key in JS and serialises BEFORE every string key regardless
+ * of insertion order — it escapes the contract by engine semantics, not by
+ * our choice. That is why writeSections rejects purely-numeric names on new
+ * writes (reads keep serving existing numeric files).
+ */
+export declare function orderSections(sections: Record<string, string>): Record<string, string>;
 export interface ReadResult {
     sections: Record<string, string>;
     /** ISO timestamp of the latest included file's mtime, or null when none. */
@@ -143,7 +192,10 @@ export declare function readSectionsWithFallback(identityDir: string): ReadResul
 /**
  * Partial upsert of the named sections. Contract (spec §1):
  *  - Validate ALL names first; any invalid → throw InvalidSectionNameError and
- *    write NOTHING (atomic request semantics).
+ *    write NOTHING (atomic request semantics). Purely-numeric names are
+ *    rejected here too (NUMERIC_SECTION_RE): they serialize ahead of the
+ *    precedence contract (see orderSections), so no new ones may be created —
+ *    existing numeric files remain readable, just no longer writable.
  *  - Only the named sections are touched; omitted sections stay untouched
  *    (omission is not deletion — deletion is filesystem-only).
  *  - Each write goes temp-file-then-rename in the same dir (no half-applied
@@ -281,6 +333,18 @@ export interface HandlerResult {
  * paramless legacy caller is covered by the migration docs, not this guard.)
  */
 export declare function handleIdentityGet(identityDir: string, clients: string[], query: Record<string, unknown>, identityAgents?: Record<string, AgentMode>): HandlerResult;
+/**
+ * Compose the served GET /identity (and /context alias) body — the ONE
+ * composition site (#313 CR3): take a handleIdentityGet HandlerResult, inject
+ * the synthetic product-owned `memory` section (#192, when enabled and mode
+ * ≠ off), then apply the SECTION_PRECEDENCE order (injectMemorySection
+ * APPENDS the section last, so the order must be re-applied after it). Used
+ * by both REST adapters and buildIdentityToolResult so the final wire key
+ * order — including memory's alphabetical slot among "rest" — can never drift
+ * between them. Non-200 results pass through untouched. Mutates and returns
+ * the SAME HandlerResult (the body object is shared with the caller).
+ */
+export declare function serveIdentityBody(handlerResult: HandlerResult, memoryEnabled: boolean): HandlerResult;
 /**
  * PUT /identity. Validates the body shape and section content types, then
  * delegates to writeSections (which owns the name allowlist + atomicity +

package/dist/identity-store.js

@@ -27,14 +27,21 @@
  * `context/`), reads ADDITIVELY MERGE: per-section `identity/` wins, and
  * legacy-only sections are included so nothing is lost — at both the global
  * and the per-agent (`agents/<id>/`) level.
+ *
+ * #313 adds the per-agent `agent_identity` section (who THIS agent is + its
+ * role conduct; per-agent ONLY, never global) and makes the served section
+ * order a defined contract — see SECTION_PRECEDENCE below. `user` remains the
+ * PRINCIPAL (global) and `rules` the fleet-wide house rules (never
+ * overridden per-agent: section-level replacement would shadow them).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.KNOWN_CONTEXT_CLIENTS = exports.KNOWN_IDENTITY_CLIENTS = exports.CONTEXT_SIZE_WARN_BYTES = exports.IDENTITY_SIZE_WARN_BYTES = exports.isValidAgentId = exports.AGENTS_DIR = exports.InvalidSectionNameError = exports.SECTION_NAME_MAX = exports.SECTION_NAME_RE = void 0;
+exports.KNOWN_CONTEXT_CLIENTS = exports.KNOWN_IDENTITY_CLIENTS = exports.CONTEXT_SIZE_WARN_BYTES = exports.IDENTITY_SIZE_WARN_BYTES = exports.SECTION_LABELS = exports.SECTION_PRECEDENCE = exports.isValidAgentId = exports.AGENTS_DIR = exports.InvalidSectionNameError = exports.SECTION_NAME_MAX = exports.SECTION_NAME_RE = void 0;
 exports.isValidSectionName = isValidSectionName;
 exports.sanitizeAgentId = sanitizeAgentId;
 exports.resolveAgentIdentity = resolveAgentIdentity;
 exports.resolveIdentityAgents = resolveIdentityAgents;
 exports.migrateIdentityDir = migrateIdentityDir;
+exports.orderSections = orderSections;
 exports.readSections = readSections;
 exports.readSectionsWithFallback = readSectionsWithFallback;
 exports.writeSections = writeSections;
@@ -47,10 +54,12 @@ exports.resolveAgentMode = resolveAgentMode;
 exports.listAgents = listAgents;
 exports.readResolvedSections = readResolvedSections;
 exports.handleIdentityGet = handleIdentityGet;
+exports.serveIdentityBody = serveIdentityBody;
 exports.handleIdentityPut = handleIdentityPut;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const node_crypto_1 = require("node:crypto");
+const memory_instructions_js_1 = require("./memory-instructions.js");
 // ---------------------------------------------------------------------------
 // Section-name allowlist (security contract)
 // ---------------------------------------------------------------------------
@@ -77,6 +86,15 @@ class InvalidSectionNameError extends Error {
     }
 }
 exports.InvalidSectionNameError = InvalidSectionNameError;
+/**
+ * A purely-numeric section name (`^\d+$`). Allowlist-VALID (reads must keep
+ * serving existing numeric files) but rejected on writes: integer-index
+ * object keys serialise before every string key, so a numeric section escapes
+ * the SECTION_PRECEDENCE wire contract entirely (see orderSections' documented
+ * exception). Enforced in writeSections only — never in isValidSectionName,
+ * which gates READS as well.
+ */
+const NUMERIC_SECTION_RE = /^\d+$/;
 /** Reserved subdir under <identity>/ holding per-agent sections. NOT a section. */
 exports.AGENTS_DIR = "agents";
 /**
@@ -185,6 +203,64 @@ function migrateIdentityDir(home) {
         return { renamed: false, from, to, reason: `rename failed: ${err instanceof Error ? err.message : String(err)}` };
     }
 }
+// ---------------------------------------------------------------------------
+// Section precedence — the served ordering contract (#313)
+// ---------------------------------------------------------------------------
+/**
+ * The order sections are SERVED in (#313): `agent_identity` → `user` →
+ * `rules`, then every other section alphabetically. Semantics behind the
+ * order:
+ *  - `agent_identity` — who THIS agent is (name, origin, character, voice,
+ *    genuine interests) plus its role conduct; per-agent only, at
+ *    `identity/agents/<id>/agent_identity.md`. It leads so the agent reads
+ *    its own self before anything else.
+ *  - `user` — the PRINCIPAL the whole fleet serves (global, never the agent).
+ *  - `rules` — fleet-wide house rules. Global only: section-level replacement
+ *    means a per-agent rules.md would SHADOW house rules, so role-specific
+ *    conduct lives INSIDE agent_identity.md (additive by construction).
+ * Before #313 this ordering rode on file-read order (readdirSync, FS-dependent)
+ * where it existed at all — now it is a defined, tested contract. The SAME
+ * list is shared by the client renderers (orderSectionNames in
+ * learnings-identity.ts imports it; the Hermes plugin mirrors it) so server
+ * and clients can never drift: the precedence is defined ONCE, here.
+ */
+exports.SECTION_PRECEDENCE = ["agent_identity", "user", "rules"];
+/**
+ * Scope display labels (#313): ONE map, consumed by the injected-block
+ * renderer (renderIdentityBlock — CC hook + OC plugin + MCP tool), the UI
+ * editor (DISPLAY_LABELS mirrors it), and the Hermes plugin (mirror in
+ * provider.py). "Global rules" says what the section IS (fleet-wide house
+ * rules), distinguishing it from per-agent content. Unknown section names
+ * fall back to title-case (titleCaseSection) — no file renames, the API keys
+ * stay the section names on disk.
+ */
+exports.SECTION_LABELS = {
+    agent_identity: "Agent identity",
+    user: "User",
+    rules: "Global rules",
+};
+/**
+ * Rebuild a sections record with its keys inserted in SECTION_PRECEDENCE
+ * order, then the rest alphabetically. Pure: same values, same (string) keys,
+ * deterministic order — JSON serialisation preserves insertion order, so this
+ * IS the wire contract. Idempotent; a map with no known primaries is just
+ * alphabetised.
+ *
+ * DOCUMENTED EXCEPTION: a canonically-numeric section name (e.g. "42") is an
+ * integer-index key in JS and serialises BEFORE every string key regardless
+ * of insertion order — it escapes the contract by engine semantics, not by
+ * our choice. That is why writeSections rejects purely-numeric names on new
+ * writes (reads keep serving existing numeric files).
+ */
+function orderSections(sections) {
+    const names = Object.keys(sections);
+    const primaries = exports.SECTION_PRECEDENCE.filter((p) => names.includes(p));
+    const rest = names.filter((n) => !exports.SECTION_PRECEDENCE.includes(n)).sort();
+    const ordered = {};
+    for (const name of [...primaries, ...rest])
+        ordered[name] = sections[name];
+    return ordered;
+}
 /**
  * Enumerate the identity dir and return the served sections. Only regular files
  * whose basename (sans `.md`) passes the allowlist are included; symlinks are
@@ -285,7 +361,10 @@ function readSectionsWithFallback(identityDir) {
 /**
  * Partial upsert of the named sections. Contract (spec §1):
  *  - Validate ALL names first; any invalid → throw InvalidSectionNameError and
- *    write NOTHING (atomic request semantics).
+ *    write NOTHING (atomic request semantics). Purely-numeric names are
+ *    rejected here too (NUMERIC_SECTION_RE): they serialize ahead of the
+ *    precedence contract (see orderSections), so no new ones may be created —
+ *    existing numeric files remain readable, just no longer writable.
  *  - Only the named sections are touched; omitted sections stay untouched
  *    (omission is not deletion — deletion is filesystem-only).
  *  - Each write goes temp-file-then-rename in the same dir (no half-applied
@@ -310,7 +389,7 @@ function readSectionsWithFallback(identityDir) {
  *    written THROUGH (never-follow-symlinks-on-write).
  */
 function writeSections(dir, sections) {
-    const invalid = Object.keys(sections).filter((n) => !isValidSectionName(n));
+    const invalid = Object.keys(sections).filter((n) => !isValidSectionName(n) || NUMERIC_SECTION_RE.test(n));
     if (invalid.length > 0)
         throw new InvalidSectionNameError(invalid);
     (0, node_fs_1.mkdirSync)(dir, { recursive: true });
@@ -596,7 +675,9 @@ function listAgents(identityDir, identityAgents) {
 function readResolvedSections(identityDir, agentId, identityAgents) {
     if (agentId === null) {
         const g = readSectionsWithFallback(identityDir);
-        return { sections: g.sections, updatedAt: g.updatedAt };
+        // #313: every served read carries the precedence contract — the bare
+        // global set is ordered exactly like a resolved per-agent set.
+        return { sections: orderSections(g.sections), updatedAt: g.updatedAt };
     }
     const mode = resolveAgentMode(identityDir, agentId, identityAgents);
     if (mode === "off") {
@@ -604,22 +685,26 @@ function readResolvedSections(identityDir, agentId, identityAgents) {
     }
     const global = readSectionsWithFallback(identityDir);
     if (mode === "global") {
-        return { sections: global.sections, updatedAt: global.updatedAt, agent: agentId, mode };
+        return { sections: orderSections(global.sections), updatedAt: global.updatedAt, agent: agentId, mode };
     }
     // override — read the agent dir (identity + legacy fallback merged so the
     // both-dirs edge case doesn't lose legacy-only agent sections).
     const agentRead = readAgentSectionsWithFallback(identityDir, agentId);
-    const sections = { ...global.sections, ...agentRead.sections };
+    // #313: build the merged map, then serve it in precedence order
+    // (agent_identity → user → rules → rest alphabetical) — one ordering for
+    // every read, so what the client renders is defined server-side.
+    const merged = { ...global.sections, ...agentRead.sections };
+    const sections = orderSections(merged);
     const origins = {};
     let latestMtimeMs = 0;
-    for (const name of Object.keys(sections)) {
+    for (const name of Object.keys(merged)) {
         const fromAgent = name in agentRead.sections;
         origins[name] = fromAgent ? "agent" : "global";
         const mt = fromAgent ? agentRead.mtimes[name] : global.mtimes[name];
         if (mt && mt > latestMtimeMs)
             latestMtimeMs = mt;
     }
-    const updatedAt = Object.keys(sections).length > 0 ? new Date(latestMtimeMs).toISOString() : null;
+    const updatedAt = Object.keys(merged).length > 0 ? new Date(latestMtimeMs).toISOString() : null;
     return { sections, updatedAt, agent: agentId, mode, origins };
 }
 // ---------------------------------------------------------------------------
@@ -667,7 +752,10 @@ function handleIdentityGet(identityDir, clients, query, identityAgents = {}) {
     // No agent → the plain global read plus the additive `agents` map the UI
     // selector needs (backward compatible: existing callers ignore unknown keys).
     if (agentId === null) {
-        const { sections, updatedAt } = readSectionsWithFallback(identityDir);
+        // #313: route through readResolvedSections so the bare read serves the
+        // SAME precedence-ordered sections as a per-agent read (it also drops the
+        // duplicated readSectionsWithFallback call this handler used to carry).
+        const { sections, updatedAt } = readResolvedSections(identityDir, null, identityAgents);
         return {
             status: 200,
             body: { sections, updated_at: updatedAt, clients, agents: listAgents(identityDir, identityAgents) },
@@ -685,6 +773,26 @@ function handleIdentityGet(identityDir, clients, query, identityAgents = {}) {
         body.origins = resolved.origins;
     return { status: 200, body };
 }
+/**
+ * Compose the served GET /identity (and /context alias) body — the ONE
+ * composition site (#313 CR3): take a handleIdentityGet HandlerResult, inject
+ * the synthetic product-owned `memory` section (#192, when enabled and mode
+ * ≠ off), then apply the SECTION_PRECEDENCE order (injectMemorySection
+ * APPENDS the section last, so the order must be re-applied after it). Used
+ * by both REST adapters and buildIdentityToolResult so the final wire key
+ * order — including memory's alphabetical slot among "rest" — can never drift
+ * between them. Non-200 results pass through untouched. Mutates and returns
+ * the SAME HandlerResult (the body object is shared with the caller).
+ */
+function serveIdentityBody(handlerResult, memoryEnabled) {
+    if (handlerResult.status !== 200)
+        return handlerResult;
+    const body = handlerResult.body;
+    (0, memory_instructions_js_1.injectMemorySection)(body, memoryEnabled);
+    if (body.sections)
+        body.sections = orderSections(body.sections);
+    return handlerResult;
+}
 /**
  * PUT /identity. Validates the body shape and section content types, then
  * delegates to writeSections (which owns the name allowlist + atomicity +
@@ -703,6 +811,21 @@ function handleIdentityPut(identityDir, body, query = {}, identityAgents = {}) {
             return { status: 400, body: { error: `Section '${name}' content must be a string` } };
         }
     }
+    // CR3: numeric names get their OWN 400 message, not the generic
+    // invalid-name one. The name passes every other check (it even GETs fine —
+    // reads keep serving existing numeric files), so "invalid section name"
+    // would read as a bug rather than policy. writeSections enforces the same
+    // rejection for direct callers (defense in depth).
+    const numeric = Object.keys(sections).filter((n) => NUMERIC_SECTION_RE.test(n));
+    if (numeric.length > 0) {
+        return {
+            status: 400,
+            body: {
+                error: `Section name(s) ${numeric.map((n) => `'${n}'`).join(", ")}: purely-numeric names are read-only via the API ` +
+                    `(integer-index keys break the served section ordering); existing numeric files stay readable — write a renamed section instead`,
+            },
+        };
+    }
     const targetDir = agentId === null ? identityDir : (0, node_path_1.join)(identityDir, exports.AGENTS_DIR, agentId);
     if (agentId !== null) {
         // A1 write-path guard: never write through a symlinked/non-dir root or leaf

package/dist/index.d.ts

@@ -8,14 +8,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