@gamaze/hicortex 0.19.2 → 0.19.4

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.

package/dist/mcp-server.d.ts

@@ -13,10 +13,11 @@
 import express from "express";
 import type { MemorySearchResult } from "./types.js";
 /**
- * Resolve the request body-size limit in MB (#7). Pure — exported for tests.
- * Precedence: an explicit config value > hosted-mode default (5) > self-hosted
- * default (25, the historical fixed value → no regression). A finite positive
- * config value wins; invalid/absent falls through.
+ * Resolve the request body-size limit in MB (#7, #328 item 2b). Pure —
+ * exported for tests. Precedence: HICORTEX_DISTILL_BODY_LIMIT_MB env >
+ * explicit config value > hosted-mode default (5) > self-hosted default (25,
+ * the historical fixed value → no regression). A finite positive value wins
+ * at each step; invalid/absent falls through.
  */
 export declare function resolveBodyLimitMb(configVal: unknown, hostedMode: boolean): number;
 /**
@@ -29,6 +30,26 @@ export declare function resolveBodyLimitMb(configVal: unknown, hostedMode: boole
  * on top of that ordering. Exported so tests exercise the real handler.
  */
 export declare function makeBodyLimitErrorHandler(limitMb: number): express.ErrorRequestHandler;
+/**
+ * #328 item 4 (package-server half, CR-corrected ORDERING): a Content-Length
+ * pre-check that MUST be registered BEFORE express.json. Registered after the
+ * parser (the first #328 pass had it inside createAuthMiddleware, which sits
+ * after the parser) it is inert as a bounding measure — body-parser buffers
+ * the body up to its own limit BEFORE auth runs and refuses oversize itself,
+ * so the check only ever saw bodies the parser had already accepted and
+ * buffered. Registered FIRST it refuses a DECLARED-oversize body before a
+ * single byte is read and before any route/auth work, on every path. The
+ * twin check inside createAuthMiddleware (viz.ts) is kept as a belt — but the
+ * GATE here is the one that actually bounds pre-auth buffering.
+ *
+ * RESIDUAL RISK (deliberate, documented): chunked transfer-encoding sends no
+ * Content-Length, so this gate cannot see it — those requests still buffer up
+ * to the parser limit inside express.json (bounded per request, no
+ * concurrency cap here). Full pre-auth bounding lives in the hosted router's
+ * webhook path (stripe.ts); the tenant data plane trusts its bearer
+ * (self-hosted threat model) or sits behind the provider's edge (hosted).
+ */
+export declare function makeContentLengthGate(limitBytes: number): express.RequestHandler;
 export declare function startServer(options?: {
     port?: number;
     host?: string;

package/dist/mcp-server.js

@@ -50,6 +50,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveBodyLimitMb = resolveBodyLimitMb;
 exports.makeBodyLimitErrorHandler = makeBodyLimitErrorHandler;
+exports.makeContentLengthGate = makeContentLengthGate;
 exports.startServer = startServer;
 exports.formatResults = formatResults;
 const express_1 = __importDefault(require("express"));
@@ -410,12 +411,26 @@ function createMcpServer() {
 // HTTP server with SSE transport
 // ---------------------------------------------------------------------------
 /**
- * Resolve the request body-size limit in MB (#7). Pure — exported for tests.
- * Precedence: an explicit config value > hosted-mode default (5) > self-hosted
- * default (25, the historical fixed value → no regression). A finite positive
- * config value wins; invalid/absent falls through.
+ * Env override for the body limit (#328 item 2b — hosted tenant-immutable
+ * pin, same ENV-WINS pattern as HICORTEX_TOKEN_CAP in token-budget.ts). The
+ * hosted tenant's /data is tenant-writable, so a `distillBodyLimitMb` in the
+ * tenant's own config.json could raise the limit the provider intended; an
+ * env baked into the container (`-e`, provisioner-written .env) cannot be
+ * mutated by the tenant process. Self-hosted installs may also use it as an
+ * operator knob — precedence below puts it above config in every mode.
+ */
+const DISTILL_BODY_LIMIT_MB_ENV = "HICORTEX_DISTILL_BODY_LIMIT_MB";
+/**
+ * Resolve the request body-size limit in MB (#7, #328 item 2b). Pure —
+ * exported for tests. Precedence: HICORTEX_DISTILL_BODY_LIMIT_MB env >
+ * explicit config value > hosted-mode default (5) > self-hosted default (25,
+ * the historical fixed value → no regression). A finite positive value wins
+ * at each step; invalid/absent falls through.
  */
 function resolveBodyLimitMb(configVal, hostedMode) {
+    const envCap = Number(process.env[DISTILL_BODY_LIMIT_MB_ENV]);
+    if (Number.isFinite(envCap) && envCap > 0)
+        return envCap;
     const cfg = Number(configVal);
     if (Number.isFinite(cfg) && cfg > 0)
         return cfg;
@@ -441,6 +456,36 @@ function makeBodyLimitErrorHandler(limitMb) {
         next(err);
     };
 }
+/**
+ * #328 item 4 (package-server half, CR-corrected ORDERING): a Content-Length
+ * pre-check that MUST be registered BEFORE express.json. Registered after the
+ * parser (the first #328 pass had it inside createAuthMiddleware, which sits
+ * after the parser) it is inert as a bounding measure — body-parser buffers
+ * the body up to its own limit BEFORE auth runs and refuses oversize itself,
+ * so the check only ever saw bodies the parser had already accepted and
+ * buffered. Registered FIRST it refuses a DECLARED-oversize body before a
+ * single byte is read and before any route/auth work, on every path. The
+ * twin check inside createAuthMiddleware (viz.ts) is kept as a belt — but the
+ * GATE here is the one that actually bounds pre-auth buffering.
+ *
+ * RESIDUAL RISK (deliberate, documented): chunked transfer-encoding sends no
+ * Content-Length, so this gate cannot see it — those requests still buffer up
+ * to the parser limit inside express.json (bounded per request, no
+ * concurrency cap here). Full pre-auth bounding lives in the hosted router's
+ * webhook path (stripe.ts); the tenant data plane trusts its bearer
+ * (self-hosted threat model) or sits behind the provider's edge (hosted).
+ */
+function makeContentLengthGate(limitBytes) {
+    return (req, res, next) => {
+        const declared = req.headers["content-length"];
+        const declaredNum = typeof declared === "string" ? Number(declared) : NaN;
+        if (Number.isFinite(declaredNum) && declaredNum > limitBytes) {
+            res.status(413).json({ error: "request body too large" });
+            return;
+        }
+        next();
+    };
+}
 async function startServer(options = {}) {
     const port = options.port ?? 8787;
     const host = options.host ?? "0.0.0.0";
@@ -527,12 +572,20 @@ async function startServer(options = {}) {
     // env (provider-set, tenant-immutable) which takes precedence. Initialised here
     // (after stateDir + savedConfig are known) so the warn-dedup can seed from state.
     (0, token_budget_js_1.initTokenBudget)(stateDir, savedConfig?.llmTokensPerMonth);
-    // #7: request body-size limit. Config key wins; else 5 MB hosted / 25 MB
-    // self-hosted (the prior fixed value → no regression). Guards the OOM vector
-    // (the body is fully parsed into memory before the distiller truncates to 80K
-    // chars). Legitimate capture segments are ≤60K chars (~200KB), so this never
+    // #7: request body-size limit. Env (HICORTEX_DISTILL_BODY_LIMIT_MB) wins;
+    // else the config key; else 5 MB hosted / 25 MB self-hosted (the prior
+    // fixed value → no regression). Guards the OOM vector (the body is fully
+    // parsed into memory before the distiller truncates to 80K chars).
+    // Legitimate capture segments are ≤60K chars (~200KB), so this never
     // constrains real flow — it's an abuse/backstop. Oversized → 413.
+    // #328 item 2b: in HOSTED mode the env is the provider's tenant-immutable
+    // pin — the tenant-writable /data/config.json must not be able to raise it.
     const bodyLimitMb = resolveBodyLimitMb(savedConfig?.distillBodyLimitMb, hostedMode);
+    // Label the source truthfully (token-budget.ts pattern): only claim env
+    // when the env value was actually used (a malformed env falls through).
+    if (Number(process.env.HICORTEX_DISTILL_BODY_LIMIT_MB) === bodyLimitMb) {
+        console.log(`[hicortex] Body limit: ${bodyLimitMb} MB (HICORTEX_DISTILL_BODY_LIMIT_MB env — overrides config)`);
+    }
     if (savedConfig?.llmBackend === "claude-cli") {
         const claudePath = (0, llm_js_1.findClaudeBinary)();
         if (claudePath) {
@@ -643,7 +696,9 @@ async function startServer(options = {}) {
     const scoringCfg = retrieval.configureScoring(savedConfig);
     const sessionIntentCfg = retrieval.configureSessionIntent(savedConfig);
     console.log(`[hicortex] Recall: k=${recallCfg.searchLimit}/recent=${recallCfg.recentLimit}` +
-        `/window=${recallCfg.recentWindowDays}d/cold=${recallCfg.coldExposureSlots} · ` +
+        `/window=${recallCfg.recentWindowDays}d/cold=${recallCfg.coldExposureSlots}` +
+        `/novelty=${(0, recall_index_js_1.resolveNoveltyFloorSlots)(savedConfig?.noveltyFloorSlots, savedConfig?.recallMaxItems)}` +
+        ` · ` +
         `score sim=${scoringCfg.similarity}/str=${scoringCfg.strength}/conn=${scoringCfg.connections}` +
         `/rec=${scoringCfg.recency}, fresh=${scoringCfg.freshnessBoostWeight}@${scoringCfg.freshnessBoostDays}d, ` +
         `superseded×${scoringCfg.supersededDemotion}` +
@@ -657,6 +712,9 @@ async function startServer(options = {}) {
         maxItems: savedConfig?.recallMaxItems,
         minPromptLength: savedConfig?.recallMinPromptChars,
         titleChars: savedConfig?.recallTitleChars,
+        // #324 novelty floor: slots of recallMaxItems guaranteed to the
+        // pure-prompt (unblended) search's top passing hit(s). 0 disables.
+        noveltyFloorSlots: savedConfig?.noveltyFloorSlots,
     };
     memoryInstructionsEnabled = savedConfig?.memoryInstructions !== false;
     if (resolvedAgents.dropped.length > 0) {
@@ -675,6 +733,10 @@ async function startServer(options = {}) {
     }
     // Express app
     const app = (0, express_1.default)();
+    // #328 item 4: the Content-Length pre-check MUST precede express.json (the
+    // parser buffers unauthenticated bodies up to its own limit; refusing the
+    // DECLARED oversize first bounds that). See makeContentLengthGate.
+    app.use(makeContentLengthGate(bodyLimitMb * 1024 * 1024));
     // Raise the body limit — whole-session denoised transcripts exceed the 100 kB default.
     app.use(express_1.default.json({ limit: `${bodyLimitMb}mb` }));
     // #7: JSON 413 on body-limit exceed (see makeBodyLimitErrorHandler). Server-side
@@ -721,7 +783,7 @@ async function startServer(options = {}) {
     // /dashboard has its own shell-exemption pattern. Gives the console one entry
     // point: http://<host>:8787/ → /dashboard.
     app.get("/", (_req, res) => res.redirect("/dashboard"));
-    app.use((0, viz_js_1.createAuthMiddleware)(authToken, authTokenPrevious, bypassMarkerPresent));
+    app.use((0, viz_js_1.createAuthMiddleware)(authToken, authTokenPrevious, bypassMarkerPresent, bodyLimitMb * 1024 * 1024));
     // SSE transport management — each connection gets its own McpServer instance
     const transports = new Map();
     // Health endpoint — PUBLIC minimal probe. Unauthenticated (the auth
@@ -877,37 +939,23 @@ async function startServer(options = {}) {
             res.status(503).json({ error: "Server not initialized" });
             return;
         }
+        // Client-pushed project/privacy scoping (F1) rides through to retrieval,
+        // which handles the filtered over-fetch itself. The search closure itself
+        // lives in recall-index.ts (createRecallRetrieveFn): per-request prompt
+        // embed memo (ONE embed for the blended + pure-prompt searches), the
+        // session-intent centroid blend/EMA fold via retrieval.recallQueryVector
+        // (#192 session-intent keying, 0.15.3), and the #324 pure-prompt branch
+        // that searches unblended and touches no centroid state. Extracted so the
+        // exact behavior is unit-testable without HTTP (blendQueryVector
+        // precedent); this adapter stays thin.
         const r = await (0, recall_index_js_1.handleRecallIndex)({
             db,
             registry: recallRegistry,
-            // Client-pushed project/privacy scoping (F1) rides through to
-            // retrieval, which handles the filtered over-fetch itself.
-            // #192 session-intent keying (0.15.3): embed the prompt ONCE here,
-            // blend with the session's rolling centroid, and pass the blended
-            // vector to retrieve() via queryEmbedding so retrieve() does NOT
-            // re-embed. Turn 1 (no centroid yet) and weight=0 both reduce to a
-            // pure-prompt search (the kill-switch). The centroid is updated AFTER
-            // reading the prior one — so turn 1 searches with pure prompt, then
-            // seeds the centroid for turn 2+ to blend against.
-            retrieveFn: async (query, limit, filters, sessionId) => {
-                const { weight, alpha } = retrieval.getSessionIntent();
-                const promptEmb = await (0, embedder_js_1.embed)(query);
-                // weight=0 (kill-switch): the centroid is neither read nor written.
-                const centroid = weight > 0 ? recallRegistry.getCentroid(sessionId) : undefined;
-                const queryVec = retrieval.blendQueryVector(promptEmb, centroid, weight);
-                if (weight > 0)
-                    recallRegistry.updateCentroid(sessionId, promptEmb, alpha);
-                return retrieval.retrieve(db, embedder_js_1.embed, query, {
-                    limit,
-                    noStrengthen: true,
-                    // #203: project + mission_domains are SOFT affinity (zero-boost
-                    // neutral), threaded into computeScore. 0.16.x: privacy is no
-                    // longer threaded (vestigial column, never filtered).
-                    project: filters?.project,
-                    missionDomains: filters?.mission_domains,
-                    queryEmbedding: queryVec,
-                });
-            },
+            retrieveFn: (0, recall_index_js_1.createRecallRetrieveFn)({
+                db,
+                registry: recallRegistry,
+                embedFn: embedder_js_1.embed,
+            }),
             options: recallIndexOptions,
         }, req.body);
         res.status(r.status).json(r.body);
@@ -1575,6 +1623,21 @@ async function startServer(options = {}) {
     };
     process.on("SIGINT", shutdown);
     process.on("SIGTERM", shutdown);
+    // #329 item 2: warm the embedder NOW, in the background. The ONNX pipeline
+    // lazy-loads inside the first embed() (~0.5-3s cold) — without this, the
+    // first /recall-index after every restart paid that load inside its own
+    // latency budget and the 1s client hook failed soft (silent recall loss).
+    // Fire-and-forget AFTER listen: never blocks boot, never fatal (a failed
+    // warm-up just logs once; the next real embed lazy-loads as before).
+    //
+    // HOSTED MEMORY IMPLICATION (accepted, #329 CR finding 3): this makes the
+    // embedding model (~150-300MB resident) load in EVERY tenant container from
+    // boot, idle tenants included — previously an idle tenant never loaded it.
+    // Accepted for the current single-tenant-VPS sizing: containers run under
+    // 2g caps, and any ACTIVE tenant loaded the model on first use anyway. If
+    // tenant density grows, revisit (e.g. warm on first authenticated request
+    // instead of boot). Capacity math: hosted/README.md (TENANT_MEMORY_LIMIT).
+    (0, embedder_js_1.warmEmbedder)(embedder_js_1.embed);
 }
 // ---------------------------------------------------------------------------
 // Helpers

package/dist/nightly.d.ts

@@ -10,6 +10,31 @@
  * Every machine (server + clients) uses the same capture path: denoise locally,
  * POST to /distill. No local LLM required for capture; distillation is server-side.
  */
+/**
+ * Discovery watermark. Normally the last-nightly timestamp; with
+ * `--recapture-window <days>` (#189 Tier-2 recovery) the window may only
+ * WIDEN — since = min(lastNightly, now−N days). Taking the earlier of the two
+ * means a machine that was offline longer than N days still re-discovers every
+ * session it missed; using now−N unconditionally would NARROW the window and
+ * skip (then, via writeLastRun, permanently lose) the 8-to-N-day-old sessions
+ * (#189 review, fix 3). Per-session cursors keep the wide re-scan cheap: an
+ * already-captured session yields an empty delta.
+ *
+ * Clock-jump clamp (#327): a FUTURE-dated lastNightly (client clock error —
+ * NTP not yet synced at write time) would, once the clock corrects, sit ahead
+ * of every session mtime and permanently skip quiet sessions (their mtimes
+ * never re-cross a future watermark). Clamped to `now` with a warn; the warn
+ * fires once per affected run (this function runs once per nightly).
+ * `now` is injectable for tests.
+ */
+export declare function computeSince(stateDir: string, recaptureWindowDays?: number, now?: Date): Date;
+/**
+ * Parse a `Retry-After` header into ms (#327). Handles both RFC forms —
+ * delay-seconds (`"30"`) and HTTP-date — and returns undefined for anything
+ * unparseable (the caller then falls back to its own backoff schedule).
+ * Exported for unit tests (pure on the header value).
+ */
+export declare function parseRetryAfterMs(resp: Response): number | undefined;
 export declare function runNightly(options?: {
     dryRun?: boolean;
     captureOnly?: boolean;