@gamaze/hicortex 0.19.3 → 0.19.5

package/dist/distiller.js

@@ -8,11 +8,28 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.detectChunkSize = detectChunkSize;
 exports.extractConversationText = extractConversationText;
 exports.distillSession = distillSession;
+exports.isNoExtractResponse = isNoExtractResponse;
 exports.hasMinimalSubstance = hasMinimalSubstance;
+exports.typeFromTag = typeFromTag;
+exports.parseDistilledEntries = parseDistilledEntries;
 const prompts_js_1 = require("./prompts.js");
 const redact_js_1 = require("./redact.js");
 const MAX_TRANSCRIPT_CHARS = 80_000;
 const MIN_CONVERSATION_CHARS = 200;
+// #339 (2026-08-24 postmortem): NO_EXTRACT over-firing visibility threshold.
+// Real summary-led segments that the model wrongly abandoned ran 38-64K
+// denoised chars; genuine pure-status noise is ~2.6K. A segment larger than
+// this whose every chunk returns an empty LLM verdict is far more likely the
+// model pattern-matching a bookkeeping-heavy OPENING to the ephemera gate than
+// a legitimately empty segment — so it gets a warning line. Warning ONLY: no
+// auto-retry (cost); the goal is that silent segment loss shows up in the
+// nightly log instead of in a weeks-later eval.
+//
+// The threshold compares the PRE-CHUNKING conversation length, never the chunk
+// length: default ollama chunking (numCtx 8192 → ~19.6K chars) and the
+// small-model speed cap (20K) both keep every chunk at or below this number,
+// so a chunk-level check would be unreachable exactly where the incident lived.
+const NO_EXTRACT_WARN_MIN_CHARS = 20_000;
 // Chunk size limits by model parameter count (for local/CPU inference)
 // Small models are slow on CPU — cap input size to keep inference under ~60s
 const SMALL_MODEL_PARAMS = 8_000_000_000; // 8B — threshold for "small"
@@ -225,10 +242,16 @@ function extractConversationText(messages, redactionConfig) {
  * `droppedOut`, when provided, is filled with every entry the substance gate
  * discarded (full text). Callers use it to build a durable audit trail (#156);
  * omitting it leaves gate behaviour unchanged.
+ *
+ * `segmentLabel` (optional) identifies the caller's segment in the #339
+ * over-firing warning (e.g. the capture pipeline's segment_id). Purely for
+ * log correlation — omitting it falls back to "chunk".
  */
 async function distillSession(llm, conversation, projectName, date, chunkSizeChars, droppedOut, 
 /** Called with each chunk's token usage (#5 budget metering). Optional. */
-onUsage) {
+onUsage, 
+/** Segment identifier for the #339 NO_EXTRACT warning. Optional. */
+segmentLabel) {
     if (conversation.length < MIN_CONVERSATION_CHARS) {
         return [];
     }
@@ -241,9 +264,11 @@ onUsage) {
     const chunkSize = chunkSizeChars ?? MAX_TRANSCRIPT_CHARS;
     // If transcript fits in one chunk, distill directly (errors propagate)
     if (transcript.length <= chunkSize) {
-        const { entries, dropped } = await distillChunk(llm, transcript, projectName, date, onUsage);
+        const { entries, dropped, emptyVerdict } = await distillChunk(llm, transcript, projectName, date, onUsage);
         if (droppedOut)
             droppedOut.push(...dropped);
+        if (emptyVerdict)
+            warnSuspiciousEmptySegment(segmentLabel, conversation.length);
         return entries;
     }
     // Chunk large transcripts and distill each segment.
@@ -259,11 +284,14 @@ onUsage) {
     const allEntries = [];
     const seen = new Set();
     let chunkFailures = 0;
+    let emptyVerdicts = 0;
     let lastError = null;
     for (let i = 0; i < chunks.length; i++) {
         console.log(`[hicortex]     Chunk ${i + 1}/${chunks.length} (${chunks[i].length} chars)`);
         try {
-            const { entries, dropped } = await distillChunk(llm, chunks[i], projectName, date, onUsage);
+            const { entries, dropped, emptyVerdict } = await distillChunk(llm, chunks[i], projectName, date, onUsage);
+            if (emptyVerdict)
+                emptyVerdicts++;
             if (droppedOut)
                 droppedOut.push(...dropped);
             for (const entry of entries) {
@@ -292,8 +320,38 @@ onUsage) {
     if (chunkFailures > 0) {
         console.warn(`[hicortex]     Partial distillation: ${chunks.length - chunkFailures}/${chunks.length} chunks succeeded`);
     }
+    // #339 segment-level net (CR finding 1): fire when the WHOLE segment produced
+    // zero memories and every processed chunk returned an empty LLM verdict. Fires
+    // only with zero chunk failures — failed chunks are already loudly visible,
+    // and "all failed" throws above. The size gate lives INSIDE
+    // warnSuspiciousEmptySegment (strict >, pre-chunking conversation length).
+    if (allEntries.length === 0 &&
+        chunkFailures === 0 &&
+        emptyVerdicts === chunks.length) {
+        warnSuspiciousEmptySegment(segmentLabel, conversation.length);
+    }
     return allEntries;
 }
+/**
+ * #339 over-firing visibility net: an empty result this large is the silent-loss
+ * signature (real summary-led segments are 38-64K chars; legitimate pure-status
+ * noise is ~2.6K). Warning-only, content-free — segment id + size, nothing from
+ * the transcript. The empty SUCCESS semantics are unchanged (no throw, no
+ * retry): the cursor advances, but the loss is now VISIBLE in the nightly log
+ * instead of surfacing weeks later in an eval.
+ *
+ * The size check lives here, not at call sites, so no path can skip it. Strict
+ * comparison: exactly NO_EXTRACT_WARN_MIN_CHARS chars is a legitimate small
+ * segment and stays silent.
+ */
+function warnSuspiciousEmptySegment(segmentLabel, segmentChars) {
+    if (segmentChars <= NO_EXTRACT_WARN_MIN_CHARS)
+        return;
+    console.warn(`[hicortex]     Suspicious empty distillation: zero memories for a ${segmentChars}-char ` +
+        `${segmentLabel ? `segment ${segmentLabel}` : "segment"} ` +
+        `(every chunk returned NO_EXTRACT or nothing parseable) — segments this large almost always ` +
+        `contain extractable material; if this repeats, suspect gate over-firing (logged only, not retried)`);
+}
 /**
  * Distill a single chunk of conversation text.
  *
@@ -309,6 +367,13 @@ onUsage) {
  *
  * `dropped` carries entries the substance gate rejected (full text) so the
  * caller can surface them in a durable audit trail (#156).
+ *
+ * `emptyVerdict` is true when the chunk was processed successfully but the LLM's
+ * verdict contained nothing extractable: bare NO_EXTRACT, an empty response, or
+ * text that parses to zero bullets (prose — the silent twin of NO_EXTRACT,
+ * #339 CR finding 2). The caller aggregates these for the segment-level
+ * over-firing warning; entries extracted then dropped by the substance gate do
+ * NOT count (their drops are already logged).
  */
 async function distillChunk(llm, transcript, projectName, date, onUsage) {
     const prompt = (0, prompts_js_1.distillation)(projectName, date, transcript);
@@ -323,10 +388,8 @@ async function distillChunk(llm, transcript, projectName, date, onUsage) {
     // trip a budget.
     if (usage && onUsage)
         onUsage(usage);
-    if (!result)
-        return { entries: [], dropped: [] };
-    if (result === "NO_EXTRACT" || result.slice(0, 20).includes("NO_EXTRACT")) {
-        return { entries: [], dropped: [] };
+    if (!result || isNoExtractResponse(result)) {
+        return { entries: [], dropped: [], emptyVerdict: true };
     }
     const parsed = parseDistilledEntries(result);
     // Smoke alarm (PR #218 review): the prompt enforces topic-first, but models
@@ -356,7 +419,20 @@ async function distillChunk(llm, transcript, projectName, date, onUsage) {
         }
         console.log(`[hicortex]     Substance gate: dropped ${dropped.length}/${parsed.length} content-free fragment(s)`);
     }
-    return { entries, dropped };
+    // Parsed-zero bypass (#339 CR finding 2): a non-empty response with no
+    // NO_EXTRACT token that still parses to zero bullets is the silent twin of
+    // NO_EXTRACT — an empty verdict for the over-firing net.
+    return { entries, dropped, emptyVerdict: parsed.length === 0 };
+}
+/**
+ * The NO_EXTRACT check distillChunk applies to an LLM response. EXPORTED and
+ * shared (not copy-pasted) with scripts/distill-ab-check/, whose counts must
+ * classify empty verdicts exactly as production does (#339 CR finding 3).
+ * Tolerant by design: a literal NO_EXTRACT anywhere in the first 20 chars
+ * counts (models prepend stray whitespace or a short phrase).
+ */
+function isNoExtractResponse(result) {
+    return result === "NO_EXTRACT" || result.slice(0, 20).includes("NO_EXTRACT");
 }
 /**
  * Split transcript text into chunks at natural boundaries (double newlines).
@@ -445,6 +521,12 @@ function hasMinimalSubstance(entry) {
  * value changed in #264 (episode→experience, fact→knowledge, decision→
  * decisions). The tag letters stay stable so neither the prompt nor the
  * parser needs to change; only this mapping table moves.
+ *
+ * EXPORTED (with parseDistilledEntries) for scripts/distill-ab-check/ (#339 CR
+ * finding 3): the A/B harness computes its counts from each variant build's own
+ * parser instead of a copy-pasted mirror, so harness numbers are by construction
+ * the numbers that build's production would store. tests/distill-ab-parser-contract.test.ts
+ * pins the src and dist parsers against the same corpus.
  */
 function typeFromTag(letter) {
     switch (letter) {
@@ -467,7 +549,8 @@ function typeFromTag(letter) {
  * tag is extracted (→ memoryType), stripped from the stored content, and
  * passed to `insertMemory` via the `memoryType` option (#216). Bullets with
  * no tag default to "experience" (backward compatible with pre-#216 distiller
- * output that never carried a tag).
+ * output that never carried a tag). EXPORTED for the A/B harness — see
+ * typeFromTag's comment (#339 CR finding 3).
  */
 function parseDistilledEntries(markdown) {
     const entries = [];

package/dist/embedder.d.ts

@@ -25,6 +25,29 @@ export declare function embed(text: string): Promise<Float32Array>;
  * Embed multiple texts. Returns an array of Float32Array embeddings.
  */
 export declare function embedBatch(texts: string[]): Promise<Float32Array[]>;
+/**
+ * Fire-and-forget embedder warm-up (#329 item 2), called at the END of server
+ * boot. The ONNX pipeline lazy-loads inside the first embed() (~0.5-3s cold),
+ * so without this the FIRST /recall-index after every restart paid the model
+ * load inside its own latency budget — the 1s client hook budget blows and
+ * that turn silently loses recall.
+ *
+ * Contract (unit-pinned in tests/embedder-warm.test.ts):
+ *   - fires exactly ONE embed call ("warmup"), NEVER awaited — returns
+ *     synchronously so boot/listen is never blocked;
+ *   - a failing warm-up is logged once (console.warn) and swallowed —
+ *     warm-up is an optimization, never a boot dependency. The next real
+ *     embed() retries the lazy load on its own terms.
+ *
+ * `embedFn` is injectable for tests; production passes the module's embed().
+ *
+ * MEMORY NOTE (accepted trade-off, #329 CR finding 3): warming at boot makes
+ * the model (~150-300MB resident) load in every server process from startup —
+ * including idle hosted tenant containers, which previously never loaded it.
+ * Accepted at current hosted sizing (2g per-tenant caps; active tenants load
+ * it on first use anyway). See the warm-site comment in mcp-server.ts.
+ */
+export declare function warmEmbedder(embedFn?: (text: string) => Promise<Float32Array>): void;
 /**
  * Return the embedding dimension count.
  */

package/dist/embedder.js

@@ -11,6 +11,7 @@ exports.EMBEDDING_DIMENSIONS = void 0;
 exports.resolveModelCacheDir = resolveModelCacheDir;
 exports.embed = embed;
 exports.embedBatch = embedBatch;
+exports.warmEmbedder = warmEmbedder;
 exports.dimensions = dimensions;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
@@ -104,6 +105,34 @@ async function embedBatch(texts) {
     }
     return results;
 }
+/**
+ * Fire-and-forget embedder warm-up (#329 item 2), called at the END of server
+ * boot. The ONNX pipeline lazy-loads inside the first embed() (~0.5-3s cold),
+ * so without this the FIRST /recall-index after every restart paid the model
+ * load inside its own latency budget — the 1s client hook budget blows and
+ * that turn silently loses recall.
+ *
+ * Contract (unit-pinned in tests/embedder-warm.test.ts):
+ *   - fires exactly ONE embed call ("warmup"), NEVER awaited — returns
+ *     synchronously so boot/listen is never blocked;
+ *   - a failing warm-up is logged once (console.warn) and swallowed —
+ *     warm-up is an optimization, never a boot dependency. The next real
+ *     embed() retries the lazy load on its own terms.
+ *
+ * `embedFn` is injectable for tests; production passes the module's embed().
+ *
+ * MEMORY NOTE (accepted trade-off, #329 CR finding 3): warming at boot makes
+ * the model (~150-300MB resident) load in every server process from startup —
+ * including idle hosted tenant containers, which previously never loaded it.
+ * Accepted at current hosted sizing (2g per-tenant caps; active tenants load
+ * it on first use anyway). See the warm-site comment in mcp-server.ts.
+ */
+function warmEmbedder(embedFn = embed) {
+    embedFn("warmup").catch((err) => {
+        console.warn(`[hicortex] Embedder warm-up failed (first search will lazy-load instead): ` +
+            (err instanceof Error ? err.message : String(err)));
+    });
+}
 /**
  * Return the embedding dimension count.
  */

package/dist/index.d.ts

@@ -69,6 +69,16 @@ export declare function formatToolResults(results: MemorySearchResult[]): {
  * the plugin half-initialized.
  */
 export declare function resolveOcPluginConfig(raw: unknown): HicortexConfig;
+/**
+ * Resolve the agent workspace directory from the RAW gateway config (#326):
+ * OpenClaw's `agents.defaults.workspace`. Pure — no module state, no fs, no
+ * mutation, never throws. Absent/non-string/empty → null (the caller falls
+ * back to the OC default workspace). Deliberately does NOT read the plugin's
+ * own config section: the workspace is a gateway-level fact, not a plugin
+ * knob, so it is resolved from ctx.config directly (the whole openclaw.json,
+ * same object resolveOcPluginConfig walks).
+ */
+export declare function resolveOcWorkspaceDir(raw: unknown): string | null;
 declare const _default: {
     id: string;
     name: string;
@@ -76,3 +86,12 @@ declare const _default: {
     register(api: any): void;
 };
 export default _default;
+/**
+ * Normalize a gateway-config workspace path for WRITING (#326 CR1): a bare
+ * `~` or leading `~/` expands against the real home dir; anything still
+ * RELATIVE afterwards is rejected (null). OpenClaw's semantics for relative
+ * workspace values are not verifiable from the plugin, and writing under
+ * process.cwd() would place the guard where OC never reads it — a silent
+ * no-op safety — so the caller skips with a warning instead. Pure; no fs.
+ */
+export declare function normalizeWorkspacePath(ws: string): string | null;

package/dist/index.js

@@ -42,6 +42,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatToolResults = formatToolResults;
 exports.resolveOcPluginConfig = resolveOcPluginConfig;
+exports.resolveOcWorkspaceDir = resolveOcWorkspaceDir;
+exports.normalizeWorkspacePath = normalizeWorkspacePath;
 const paths_js_1 = require("./paths.js");
 const features_js_1 = require("./features.js");
 const extensions_js_1 = require("./extensions.js");
@@ -128,6 +130,14 @@ 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;
+/** Warn-once-per-PROCESS flag (#326): unpinned gateway plugins.allow. NOT
+ *  reset at start() — a gateway restart inside one process must not re-warn
+ *  (a new process starts with clean flags anyway). */
+let warnedUnpinnedPlugins = false;
+/** Warn-once-per-PROCESS bookkeeping (#326) for dead-man scaffold SKIPS and
+ *  failures — one warning per distinct cause (relative path, missing dir,
+ *  non-UTF-8 file, fs error), never reset at start(). */
+const warnedScaffoldSkips = new Set();
 /** 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
@@ -164,6 +174,22 @@ const sessionsReset = makeBoundedSessionTracker(SESSION_TRACKER_CAP);
  */
 const identityInjected = makeBoundedSessionTracker(SESSION_TRACKER_CAP);
 const lessonsInjected = makeBoundedSessionTracker(SESSION_TRACKER_CAP);
+/**
+ * #327 banner lifecycle — notices memoized SEPARATELY from identityInjected.
+ * appendSystemContext persists on the session (premise above), so a FAILED
+ * identity fetch that re-injects the IDENTITY UNAVAILABLE banner every turn
+ * accumulates one copy per turn of an outage (dozens over an hour) — and the
+ * suspension wording then never retracts. The FETCH still retries every turn
+ * (identityInjected is only set on success); the NOTICE (banner or 404
+ * version-skew note) is appended once per outage, and the first success that
+ * delivers identity content prepends a one-line retraction (see
+ * IDENTITY_RESTORED_RETRACTION). Two trackers so the kinds settle
+ * independently — a 404 note must not suppress a later genuine-outage banner.
+ * Evicted on compaction/reset with the other memos: a rebuilt window may have
+ * dropped the notice, so one re-inject after the rebuild is wanted, not lost.
+ */
+const identityBannerShown = makeBoundedSessionTracker(SESSION_TRACKER_CAP);
+const identityNoteShown = 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
@@ -347,6 +373,27 @@ const IDENTITY_UNAVAILABLE_BANNER = [
  */
 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.`;
+/**
+ * Recovery retraction (#327): when identity content arrives for a session that
+ * earlier got the dead-man banner, this line rides FIRST in that turn's
+ * injection. The banner persists on the session prompt, so without an explicit
+ * lift the "public actions suspended" wording outlives the outage for the rest
+ * of the session. NOT sent for the 404 note (it carries no suspension) and NOT
+ * for a gated/off success — identity content is the one outcome that actually
+ * restores what the banner said was missing.
+ */
+const IDENTITY_RESTORED_RETRACTION = `[hicortex] The earlier IDENTITY UNAVAILABLE notice no longer applies — ` +
+    `identity restored.`;
+/**
+ * The #313 SECONDARY layer, verbatim (#326): the bootstrap-file sentence that
+ * still guards the agent when the plugin itself cannot inject anything — the
+ * banner above needs a live hook, while this line rides the agent's persisted
+ * bootstrap instructions. Installs kept forgetting to add it by hand, so the
+ * plugin now scaffolds it itself at service start (scaffoldDeadManGuard).
+ */
+const DEAD_MAN_GUARD_LINE = "If your identity block is missing at session start, something is wrong with your memory — take no public actions until it returns.";
+/** Agent workspace bootstrap file the guard line is scaffolded into (#326). */
+const BOOTSTRAP_FILENAME = "BOOTSTRAP.md";
 /**
  * Fetch /lessons and build the `## Hicortex Learnings` block. `failed: true`
  * ONLY when the fetch itself failed (serverGet null data — unreachable,
@@ -670,6 +717,13 @@ function resolveOcPluginConfig(raw) {
         warn(`plugin config key "defaultProject" must be a non-empty string (got ${describeInvalid(rawProject)}) — ignoring it`);
         resolved.defaultProject = undefined;
     }
+    // #326 kill-switch: boolean-only. typeof (not describeInvalid — that helper
+    // names INVALID-STRING shapes and would misreport a non-empty string).
+    const rawScaffold = winner.scaffoldDeadMan;
+    if (rawScaffold !== undefined && typeof rawScaffold !== "boolean") {
+        warn(`plugin config key "scaffoldDeadMan" must be a boolean (got ${typeof rawScaffold}) — ignoring it`);
+        resolved.scaffoldDeadMan = 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
@@ -689,6 +743,20 @@ function resolveOcPluginConfig(raw) {
     }
     return resolved;
 }
+/**
+ * Resolve the agent workspace directory from the RAW gateway config (#326):
+ * OpenClaw's `agents.defaults.workspace`. Pure — no module state, no fs, no
+ * mutation, never throws. Absent/non-string/empty → null (the caller falls
+ * back to the OC default workspace). Deliberately does NOT read the plugin's
+ * own config section: the workspace is a gateway-level fact, not a plugin
+ * knob, so it is resolved from ctx.config directly (the whole openclaw.json,
+ * same object resolveOcPluginConfig walks).
+ */
+function resolveOcWorkspaceDir(raw) {
+    const agents = isRecord(isRecord(raw)?.agents);
+    const workspace = isRecord(agents?.defaults)?.workspace;
+    return isNonEmptyString(workspace) ? workspace : null;
+}
 // ---------------------------------------------------------------------------
 // Plugin export
 // ---------------------------------------------------------------------------
@@ -740,6 +808,8 @@ exports.default = {
                 sessionsReset.clear();
                 identityInjected.clear();
                 lessonsInjected.clear();
+                identityBannerShown.clear();
+                identityNoteShown.clear();
                 pendingResets.clear();
                 pluginLog = log;
                 log(`[hicortex] Thin-client mode — server: ${serverUrl}`);
@@ -792,6 +862,17 @@ exports.default = {
                         `Run \`npx @gamaze/hicortex init\` to start the server. ` +
                         `Capture and tool calls will fail until the server is available.`);
                 }
+                // #326 self-hardening — install hygiene, both fail-soft by design:
+                // keep the dead-man guard line (#313 secondary layer) present in the
+                // agent workspace bootstrap, and surface an unpinned gateway trust
+                // list. The kill-switch (config scaffoldDeadMan, default on) disables
+                // the scaffold entirely; the trust warning always runs.
+                scaffoldDeadManGuard({
+                    workspaceDir: resolveOcWorkspaceDir(ctx.config) ?? fallbackOcWorkspace(),
+                    enabled: config.scaffoldDeadMan !== false,
+                    log,
+                });
+                warnIfPluginsUnpinned(ctx.config, log);
                 ensureToolsAllowed(log);
             },
             async stop() {
@@ -869,11 +950,45 @@ exports.default = {
                 // 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;
+                //
+                // #327 lifecycle: the notice is appended ONCE per outage (appends
+                // persist on the session — every-turn copies accumulate), and the
+                // first success carrying identity content prepends the retraction so
+                // the suspension wording cannot linger. Without a sessionId there is
+                // no per-session key — inject per turn (pre-#316 shape), matching
+                // the standing-block behavior above.
+                let identityBlock;
+                if (identity !== null && identity.block !== null) {
+                    identityBlock = identity.block;
+                    if (sKey !== undefined && identityBannerShown.has(sKey)) {
+                        identityBlock = `${IDENTITY_RESTORED_RETRACTION}\n\n${identityBlock}`;
+                    }
+                    if (sKey !== undefined) {
+                        identityBannerShown.evict(sKey);
+                        identityNoteShown.evict(sKey);
+                    }
+                }
+                else if (identity !== null && identity.failed) {
+                    const isSkew = identity.status === 404;
+                    const shown = isSkew ? identityNoteShown : identityBannerShown;
+                    if (sKey === undefined || !shown.has(sKey)) {
+                        if (sKey !== undefined)
+                            shown.add(sKey);
+                        identityBlock = isSkew ? IDENTITY_VERSION_SKEW_NOTE : IDENTITY_UNAVAILABLE_BANNER;
+                    }
+                    else {
+                        // Already appended earlier in the outage — it persists on the
+                        // session; re-sending would duplicate it (see tracker docs).
+                        identityBlock = null;
+                    }
+                }
+                else {
+                    // Gated-null success (old server / oc ∉ clients / mode off): a
+                    // settled outcome with no content. A prior banner stays standing —
+                    // identity is still effectively missing to the agent, and the
+                    // bootstrap dead-man guard line keeps advising caution.
+                    identityBlock = null;
+                }
                 const lessonsBlock = lessons !== null ? lessons.block : null;
                 const blocks = [identityBlock, lessonsBlock, recallBlock].filter((b) => b !== null && b !== "");
                 if (blocks.length === 0)
@@ -911,6 +1026,10 @@ exports.default = {
             void resetRecallDedup(sid, key);
             identityInjected.evict(key);
             lessonsInjected.evict(key);
+            // #327: a rebuilt window may have dropped the notice too — evict so one
+            // re-inject (banner while still failing) can happen after the rebuild.
+            identityBannerShown.evict(key);
+            identityNoteShown.evict(key);
         };
         api.on("after_compaction", recallResetHook);
         api.on("before_reset", recallResetHook);
@@ -1212,6 +1331,168 @@ const HICORTEX_TOOLS = [
     "hicortex_update",
     "hicortex_delete",
 ];
+/**
+ * The OpenClaw home this plugin resolves against (#326). `HICORTEX_OC_HOME`
+ * redirects it for tests, mirroring how HICORTEX_HOME redirects the hicortex
+ * home (paths.ts) — one resolution shared by the workspace fallback and the
+ * unpinned-trust warning so they can never disagree.
+ */
+function ocHomeDir() {
+    return process.env.HICORTEX_OC_HOME ?? (0, node_path_1.join)((0, node_os_1.homedir)(), ".openclaw");
+}
+/**
+ * Normalize a gateway-config workspace path for WRITING (#326 CR1): a bare
+ * `~` or leading `~/` expands against the real home dir; anything still
+ * RELATIVE afterwards is rejected (null). OpenClaw's semantics for relative
+ * workspace values are not verifiable from the plugin, and writing under
+ * process.cwd() would place the guard where OC never reads it — a silent
+ * no-op safety — so the caller skips with a warning instead. Pure; no fs.
+ */
+function normalizeWorkspacePath(ws) {
+    let p = ws;
+    if (p === "~")
+        p = (0, node_os_1.homedir)();
+    else if (p.startsWith("~/"))
+        p = (0, node_path_1.join)((0, node_os_1.homedir)(), p.slice(2));
+    return (0, node_path_1.isAbsolute)(p) ? p : null;
+}
+/**
+ * Fallback workspace when the gateway config names none (#326): OpenClaw's
+ * default `<ocHome>/workspace`. Returned ONLY when a real OC install is
+ * present (`<ocHome>/openclaw.json` exists — the same touchpoint
+ * ensureToolsAllowed reads): outside a gateway (tests, CI, a bare import) the
+ * plugin must not conjure `~/.openclaw` into existence just to drop a
+ * bootstrap file.
+ */
+function fallbackOcWorkspace() {
+    const ocHome = ocHomeDir();
+    return (0, node_fs_1.existsSync)((0, node_path_1.join)(ocHome, "openclaw.json")) ? (0, node_path_1.join)(ocHome, "workspace") : null;
+}
+/** Per-cause warn-once for scaffold skips/failures (#326). */
+function warnScaffoldSkipOnce(cause, log, reason) {
+    if (warnedScaffoldSkips.has(cause))
+        return;
+    warnedScaffoldSkips.add(cause);
+    log(`[hicortex] WARNING: ${reason} — the dead-man guard line was not scaffolded.`);
+}
+/**
+ * Scaffold the dead-man guard line into the agent workspace bootstrap (#326 —
+ * the #313 SECONDARY layer; the primary layer is the injected
+ * IDENTITY UNAVAILABLE banner, which needs a live plugin hook). The sentence
+ * used to be a manual install step every public-agent setup could forget, so
+ * the plugin maintains it itself at service start:
+ *
+ *   - bootstrap absent            → created containing ONLY the guard line
+ *   - present without the line    → one-time .bak of the operator's original
+ *                                   BYTES, then the line appended exactly once
+ *   - present with the line       → untouched (idempotent: no write, no backup)
+ *
+ * Deliberately conservative (CR):
+ *   - the workspace DIRECTORY is never created — OC may scaffold workspaces
+ *     from templates, and a pre-created dir could interfere; absent dir →
+ *     warn once + skip (a gateway restart after the first agent run retries)
+ *   - a non-absolute workspace path (after ~ expansion) → warn once + skip
+ *     (never write somewhere speculative like process.cwd())
+ *   - a bootstrap that is not valid UTF-8 → warn once + skip; decoding would
+ *     be lossy and rewriting the file would mangle the operator's bytes
+ *
+ * Fail-soft by construction: any filesystem failure (unreadable path,
+ * permissions) warns ONCE per cause and never breaks plugin start. The
+ * kill-switch (config `scaffoldDeadMan: false`, default on) returns before a
+ * single fs call — no write, no file creation.
+ */
+function scaffoldDeadManGuard(opts) {
+    if (!opts.enabled)
+        return;
+    const rawWorkspace = opts.workspaceDir;
+    if (!rawWorkspace)
+        return; // no workspace resolvable — not an OC install / no workspace key
+    const log = opts.log;
+    const workspaceDir = normalizeWorkspacePath(rawWorkspace);
+    if (!workspaceDir) {
+        warnScaffoldSkipOnce("relative-workspace", log, `workspace path "${rawWorkspace}" in the gateway config is relative — OpenClaw's ` +
+            "resolution for it is unknown, so the plugin will not write speculatively");
+        return;
+    }
+    const bootstrapPath = (0, node_path_1.join)(workspaceDir, BOOTSTRAP_FILENAME);
+    try {
+        // CR3: never create the workspace dir itself (template interference).
+        if (!(0, node_fs_1.existsSync)(workspaceDir)) {
+            warnScaffoldSkipOnce("missing-workspace-dir", log, `workspace directory ${workspaceDir} does not exist yet (OpenClaw creates it; ` +
+                "restart the gateway after the first agent run to retry)");
+            return;
+        }
+        // Read BYTES (CR2): the .bak must hold the operator's original exactly,
+        // and an append must splice onto the original bytes, not a lossy decode.
+        let original = null;
+        try {
+            original = (0, node_fs_1.readFileSync)(bootstrapPath);
+        }
+        catch (err) {
+            // Only "does not exist" means "create it" — anything else (EACCES,
+            // EISDIR, …) is a genuine failure and must reach the warn below, not
+            // be mistaken for an absent file and overwritten.
+            if (err.code !== "ENOENT")
+                throw err;
+        }
+        if (original !== null) {
+            const decoded = original.toString("utf-8");
+            // Invalid UTF-8 (round-trip compare): appending would rewrite the file
+            // with mangled bytes — leave it untouched and say so once.
+            if (!Buffer.from(decoded, "utf-8").equals(original)) {
+                warnScaffoldSkipOnce("invalid-utf8", log, `${bootstrapPath} is not valid UTF-8 — leaving the file untouched`);
+                return;
+            }
+            if (decoded.includes(DEAD_MAN_GUARD_LINE))
+                return;
+        }
+        if (original === null) {
+            (0, node_fs_1.writeFileSync)(bootstrapPath, `${DEAD_MAN_GUARD_LINE}\n`);
+        }
+        else {
+            // One-time backup of the operator's original BYTES — never churned.
+            const bakPath = `${bootstrapPath}.bak`;
+            if (!(0, node_fs_1.existsSync)(bakPath))
+                (0, node_fs_1.writeFileSync)(bakPath, original);
+            // Separator at the BYTE level (0x0A), so a no-trailing-newline file is
+            // spliced correctly without decoding.
+            const needsSep = original.length > 0 && original[original.length - 1] !== 0x0a;
+            (0, node_fs_1.writeFileSync)(bootstrapPath, Buffer.concat([
+                original,
+                needsSep ? Buffer.from("\n", "utf-8") : Buffer.alloc(0),
+                Buffer.from(`${DEAD_MAN_GUARD_LINE}\n`, "utf-8"),
+            ]));
+        }
+        log(`[hicortex] Added the dead-man identity guard line to ${bootstrapPath}`);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        warnScaffoldSkipOnce("fs-error", log, `could not scaffold the dead-man guard line into ${bootstrapPath}: ${msg}`);
+    }
+}
+/**
+ * Warn once per process when the gateway's plugin trust list is unpinned
+ * (#326): while `plugins.allow` is absent or empty, OpenClaw auto-loads ANY
+ * extension dropped into the plugins directory. A plugin must not pin trust
+ * itself — a self-pinned list defeats the point of the list — so this only
+ * WARNS with the fix. It never writes plugins.allow (or any gateway config;
+ * ensureToolsAllowed's tools.allow edit is the one intentional config write).
+ * Any non-empty array counts as pinned → silent.
+ */
+function warnIfPluginsUnpinned(raw, log) {
+    if (warnedUnpinnedPlugins)
+        return;
+    const allow = isRecord(isRecord(raw)?.plugins)?.allow;
+    if (Array.isArray(allow) && allow.length > 0)
+        return;
+    warnedUnpinnedPlugins = true;
+    log("[hicortex] WARNING: the OpenClaw plugin trust list (plugins.allow) is not " +
+        "pinned — any extension dropped into the plugins directory loads " +
+        'automatically. Fix: set "plugins": { "allow": ["hicortex"] } in ' +
+        `${(0, node_path_1.join)(ocHomeDir(), "openclaw.json")} (list every plugin you trust). See ` +
+        "https://hicortex.gamaze.com/docs/installation.html — hicortex never " +
+        "edits the trust list itself.");
+}
 /**
  * Ensure hicortex tools are in tools.allow so they're visible to agents
  * regardless of the tools.profile setting.