@gamaze/hicortex 0.19.3 → 0.19.5

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) {
@@ -680,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
@@ -726,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
@@ -1141,7 +1198,14 @@ async function startServer(options = {}) {
                 distillUsage.prompt += u.prompt_tokens ?? 0;
                 distillUsage.completion += u.completion_tokens ?? 0;
                 distillUsage.total += u.total_tokens ?? 0;
-            });
+            }, 
+            // #339: identify this POST in the NO_EXTRACT over-firing warning —
+            // segment_id (incremental capture), else session_id (legacy), else none.
+            typeof segment_id === "string" && segment_id
+                ? segment_id
+                : typeof session_id === "string" && session_id
+                    ? session_id
+                    : undefined);
             // Phase 1 — embed every chunk up front (async). If ANY embed fails we
             // never reach the insert, so nothing is stored.
             const createdAt = new Date(date).toISOString();
@@ -1566,6 +1630,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;

package/dist/nightly.js

@@ -45,6 +45,8 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeSince = computeSince;
+exports.parseRetryAfterMs = parseRetryAfterMs;
 exports.runNightly = runNightly;
 const paths_js_1 = require("./paths.js");
 const node_fs_1 = require("node:fs");
@@ -77,6 +79,17 @@ const telemetry_js_1 = require("./telemetry.js");
 const init_js_1 = require("./init.js");
 const backup_js_1 = require("./backup.js");
 const HICORTEX_HOME = (0, paths_js_1.hicortexHome)();
+/**
+ * Consolidate-only backup gate (#327 CR blocker). Hosted tenants run ONLY
+ * `nightly --consolidate-only` several times a day (hicortex-consolidate@.timer)
+ * and the provisioner has no backup job of its own, so those runs DO run the
+ * backup stage — but at most once per day, keyed on the newest existing
+ * artifact's age (the artifact IS the marker; no extra state file). 20h is
+ * slightly under a day so a timer firing at a drifting clock hour still gets
+ * exactly one backup per day; with `backupRetention` (default 7) the artifact
+ * count stays bounded.
+ */
+const CONSOLIDATE_ONLY_BACKUP_MIN_AGE_MS = 20 * 60 * 60 * 1000;
 function readNightlyConfig(stateDir) {
     const configPath = (0, node_path_1.join)(stateDir, "config.json");
     let loaded;
@@ -125,14 +138,30 @@ function readLastRun(stateDir = HICORTEX_HOME) {
  * 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.
  */
-function computeSince(stateDir, recaptureWindowDays) {
+function computeSince(stateDir, recaptureWindowDays, now = new Date()) {
     const lastRun = readLastRun(stateDir);
+    let effective = lastRun;
+    if (lastRun.getTime() > now.getTime()) {
+        console.warn(`[hicortex] state lastNightly (${lastRun.toISOString()}) is ahead of the clock ` +
+            `(${now.toISOString()}) — clamping discovery to now. A future watermark permanently ` +
+            `skips quiet sessions once the clock corrects; check the machine's clock/NTP. ` +
+            `Run \`hicortex nightly --recapture-window <days>\` to recover sessions missed ` +
+            `while the clock was wrong.`);
+        effective = now;
+    }
     if (recaptureWindowDays && recaptureWindowDays > 0) {
-        const windowStart = new Date(Date.now() - recaptureWindowDays * 24 * 60 * 60 * 1000);
-        return windowStart < lastRun ? windowStart : lastRun;
+        const windowStart = new Date(now.getTime() - recaptureWindowDays * 24 * 60 * 60 * 1000);
+        return windowStart < effective ? windowStart : effective;
     }
-    return lastRun;
+    return effective;
 }
 /** POST /distill transport for server mode — localhost. Sends authToken so
  *  self-capture works regardless of the localhost-bypass marker (#271 root-cause fix). */
@@ -185,7 +214,32 @@ async function normalizePostResult(resp) {
         return { status: 200, skipped: Boolean(data.skipped) };
     }
     const data = (await resp.json().catch(() => ({})));
-    return { status: resp.status, error: data.error ?? "unknown error" };
+    const retryAfterMs = parseRetryAfterMs(resp);
+    return {
+        status: resp.status,
+        error: data.error ?? "unknown error",
+        // #327: surface Retry-After so a rate-limit 429 backs off as the server
+        // asked (absent on the tenant's terminal budget-429, which ignores it).
+        ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+    };
+}
+/**
+ * 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).
+ */
+function parseRetryAfterMs(resp) {
+    const v = resp.headers.get("retry-after");
+    if (!v)
+        return undefined;
+    const secs = Number(v);
+    if (Number.isFinite(secs) && secs >= 0)
+        return secs * 1000;
+    const at = new Date(v).getTime();
+    if (Number.isFinite(at))
+        return Math.max(0, at - Date.now());
+    return undefined;
 }
 /** Strict {prompt, completion, total} parser for /distill's usage field (#287);
  *  undefined on anything malformed — the caller then treats it as unmetered. */
@@ -296,7 +350,15 @@ async function runNightly(options = {}) {
         const cooldownH = (0, config_read_js_1.readNonNegativeConfig)(savedConfig ?? {}, "captureCooldownHours", 6);
         const last = (0, state_js_1.loadState)(stateDir).lastNightly;
         if (last) {
-            const ageH = (Date.now() - new Date(last).getTime()) / 3_600_000;
+            // #327 clamp: a FUTURE-dated stamp (clock error at write time) reads as
+            // a NEGATIVE age raw, and `negative < cooldownH` is true even at the
+            // cooldown-0 opt-in ("capture every poll") — the watchdog would stay
+            // silent until real time passed the future stamp, exactly when catch-up
+            // ticks are most needed. Clamped, the worst honest reading is "captured
+            // just now", which the normal cooldown handles (and discovery applies
+            // the same clamp in computeSince).
+            const lastMs = Math.min(new Date(last).getTime(), Date.now());
+            const ageH = (Date.now() - lastMs) / 3_600_000;
             if (ageH < cooldownH) {
                 console.log(`[hicortex] watchdog: last capture ${ageH.toFixed(1)}h ago (< ${cooldownH}h cooldown) — skipping`);
                 return;
@@ -668,21 +730,52 @@ async function runNightly(options = {}) {
         // Backup stage (#6, Phase 0B) — a transactionally-consistent snapshot of
         // the irreplaceable data (DB + identity + state), packaged as one tar.gz
         // the operator ships offsite via the optional `backupCommand` hook. Runs
-        // ONLY on a full nightly (capture-only is frequent + stateless; dry-run
-        // writes nothing). Backup failure must NOT fail the nightly — capture +
-        // consolidation have already succeeded; the snapshot is on disk and the
-        // failure surfaces as `backupOk:false` in the dashboard snapshot + telemetry
-        // for alerting (the operator's hook owns active alerting; no in-product
+        // on every full nightly and on consolidate-only runs (capture-only is
+        // frequent + stateless; dry-run writes nothing). Consolidate-only MUST
+        // back up (#327 CR blocker): hosted tenants run ONLY --consolidate-only
+        // several times a day (hicortex-consolidate@.timer) and the provisioner
+        // has no backup job of its own — skipping the stage left them with NO
+        // recurring backup. Their cadence is bounded by the artifact-age gate
+        // below (~1/day) instead, so `backupRetention` keeps the dir bounded.
+        // Backup failure must NOT fail the nightly — capture + consolidation
+        // have already succeeded; the snapshot is on disk and the failure
+        // surfaces as `backupOk:false` in the dashboard snapshot + telemetry for
+        // alerting (the operator's hook owns active alerting; no in-product
         // channel yet — Phase 3).
         let backupPath;
         let backupBytes;
         let backupOk;
-        if (!dryRun && !captureOnly) {
+        // Artifact-age gate for consolidate-only runs: skip only while the newest
+        // existing artifact is younger than ~20h. 20h (not 24) so a timer firing
+        // at a drifting clock hour still gets exactly one backup per day, and
+        // robust to an hour of clock skew either way. Keyed on the artifact, not
+        // a state timestamp — no new state file to drift out of sync with the
+        // disk it describes.
+        const effectiveBackupDir = typeof savedConfig?.backupDir === "string" && savedConfig.backupDir.trim()
+            ? savedConfig.backupDir
+            : (0, node_path_1.join)(stateDir, "backups");
+        let skipBackup = false;
+        let newestArtifactMs;
+        if (consolidateOnly) {
+            newestArtifactMs = (0, backup_js_1.newestBackupArtifactMs)(effectiveBackupDir);
+            skipBackup =
+                newestArtifactMs !== undefined &&
+                    Date.now() - newestArtifactMs < CONSOLIDATE_ONLY_BACKUP_MIN_AGE_MS;
+        }
+        if (!dryRun && !captureOnly && !skipBackup) {
             try {
-                const backupDir = typeof savedConfig?.backupDir === "string" && savedConfig.backupDir.trim()
-                    ? savedConfig.backupDir
-                    : undefined;
-                const bRes = await (0, backup_js_1.createBackup)({ db, home: stateDir, outDir: backupDir });
+                const bRes = await (0, backup_js_1.createBackup)({
+                    db,
+                    home: stateDir,
+                    // undefined falls back to <home>/backups inside createBackup — the
+                    // same resolution effectiveBackupDir above uses for the age gate.
+                    outDir: typeof savedConfig?.backupDir === "string" && savedConfig.backupDir.trim()
+                        ? savedConfig.backupDir
+                        : undefined,
+                    // Same reader + default as the CLI (#327): keep the N newest
+                    // artifacts, 0 = keep all.
+                    retention: (0, config_read_js_1.readNonNegativeConfig)(savedConfig ?? {}, "backupRetention", backup_js_1.DEFAULT_BACKUP_RETENTION),
+                });
                 backupPath = bRes.path;
                 backupBytes = bRes.bytes;
                 backupOk = true;
@@ -712,6 +805,15 @@ async function runNightly(options = {}) {
                 console.error(`[hicortex] Backup FAILED: ${err instanceof Error ? err.message : String(err)}`);
             }
         }
+        else if (consolidateOnly && !dryRun) {
+            // #327: explicit log line so a hosted consolidation timer's log doesn't
+            // read as a silently-missing backup stage — and names WHY (age gate), so
+            // an operator reading "skipped" can tell a healthy cadence gate from a
+            // dead one.
+            const ageH = newestArtifactMs !== undefined ? (Date.now() - newestArtifactMs) / 3_600_000 : -1;
+            console.log(`[hicortex] Backup stage skipped — consolidate-only run: newest backup is ` +
+                `${ageH.toFixed(1)}h old (< ${Math.round(CONSOLIDATE_ONLY_BACKUP_MIN_AGE_MS / 3_600_000)}h gate).`);
+        }
         // Dashboard snapshot (#224) — full nightly only. The snapshot reflects
         // corpus state regardless of whether consolidation/LLM ran, so it is
         // ALWAYS written here (the use case is history; an LLM-less install still
@@ -771,9 +873,11 @@ async function runNightly(options = {}) {
                     budgetExhausted,
                     budgetDeferredByStage,
                     // #6 backup stage — hoisted from the block above. Present whenever
-                    // the backup stage ran (full nightly); undefined on capture-only /
-                    // dry-run. backupOk flips to false on snapshot OR hook failure so the
-                    // dashboard digest can flag a night the offsite copy didn't complete.
+                    // the backup stage ran (full nightly, and consolidate-only runs past
+                    // the artifact-age gate); undefined on capture-only / dry-run / a
+                    // gated-skip consolidate-only run. backupOk flips to false on
+                    // snapshot OR hook failure so the dashboard digest can flag a night
+                    // the offsite copy didn't complete.
                     backupPath,
                     backupBytes,
                     backupOk,
@@ -826,7 +930,8 @@ async function runNightly(options = {}) {
                 // #6 backup stage outcome — forwarded only when the backup stage ran
                 // (full nightly). `ok` is false on snapshot OR hook failure; the fleet
                 // aggregate surfaces a sustained drop in backup_ok as a data-loss risk.
-                // Absent on capture-only / dry-run / client runs (no backup ran).
+                // Absent on capture-only / consolidate-only / dry-run / client runs
+                // (no backup ran).
                 ...(backupOk !== undefined
                     ? { backup: { ok: backupOk === true, bytes: backupBytes ?? 0 } }
                     : {}),

package/dist/prompts.d.ts

@@ -18,6 +18,24 @@ export declare function importanceScoring(memoriesBlock: string): string;
 export declare function reflection(memoriesBlock: string, recentLessons?: string): string;
 /**
  * Distillation prompt. Extracts knowledge from a session transcript.
+ *
+ * LAYOUT (REVERTED 2026-08-24): transcript BEFORE the static instruction
+ * block — the pre-0.19.4 order. The #329 item-6 reorder (static-first, for
+ * provider prefix caching) was REVERTED after a deterministic A/B on real
+ * segments: with instructions first, the model over-fires NO_EXTRACT on
+ * summary-led and long mixed sessions (a real coding segment: 15 memories →
+ * 0; a real Hermes session: rich → 0; isolation proved the LAYOUT caused it,
+ * not the item-5 sentence, which is KEPT). Silent shape-dependent segment
+ * loss beats any caching win. Re-attempting instructions-first requires a
+ * gate fix that passes the A/B matrix harness first.
+ *
+ * #339 gate hardening (same day): the NO_EXTRACT rule now carries an explicit
+ * whole-transcript guard + counter-example (a summary-led session that
+ * contains later decisions MUST be extracted) — the over-firing mechanism was
+ * the model pattern-matching a bookkeeping-heavy OPENING to the ephemera gate
+ * and abandoning the whole segment. Companion visibility net (warning on
+ * large empty results) lives in distiller.ts; the release-gate harness is
+ * scripts/distill-ab-check/.
  */
 export declare function distillation(projectName: string, date: string, transcript: string): string;
 /**

package/dist/prompts.js

@@ -106,6 +106,24 @@ Respond with a JSON array. Empty array [] is a valid response.`;
 }
 /**
  * Distillation prompt. Extracts knowledge from a session transcript.
+ *
+ * LAYOUT (REVERTED 2026-08-24): transcript BEFORE the static instruction
+ * block — the pre-0.19.4 order. The #329 item-6 reorder (static-first, for
+ * provider prefix caching) was REVERTED after a deterministic A/B on real
+ * segments: with instructions first, the model over-fires NO_EXTRACT on
+ * summary-led and long mixed sessions (a real coding segment: 15 memories →
+ * 0; a real Hermes session: rich → 0; isolation proved the LAYOUT caused it,
+ * not the item-5 sentence, which is KEPT). Silent shape-dependent segment
+ * loss beats any caching win. Re-attempting instructions-first requires a
+ * gate fix that passes the A/B matrix harness first.
+ *
+ * #339 gate hardening (same day): the NO_EXTRACT rule now carries an explicit
+ * whole-transcript guard + counter-example (a summary-led session that
+ * contains later decisions MUST be extracted) — the over-firing mechanism was
+ * the model pattern-matching a bookkeeping-heavy OPENING to the ephemera gate
+ * and abandoning the whole segment. Companion visibility net (warning on
+ * large empty results) lives in distiller.ts; the release-gate harness is
+ * scripts/distill-ab-check/.
  */
 function distillation(projectName, date, transcript) {
     return `You are a memory extraction agent. Analyze this AI session transcript and extract
@@ -195,9 +213,29 @@ do not score it lower and write it anyway: OMIT it. A closed category of never-r
 The durable part of the same event may still qualify — the CHOICE a change
 embodies ("standardize on model X", user-confirmed) is [D], a configuration
 that holds going forward is [K]; the version bump, merge, or count itself never is.
+Override for the [D] "actually carried out" test: even if carried out by the
+user, a version bump, merge, or count is NEVER [D] — only the durable
+user-confirmed standardization it embodies qualifies.
 If EVERY item in the transcript is never-record ephemera, output ONLY:
 "NO_EXTRACT" — zero memories is the correct result for a pure-status segment.
 
+NO_EXTRACT guard (a verdict on the WHOLE transcript, never on its opening):
+"NO_EXTRACT" requires that NO durable decision, knowledge, or correction
+appears ANYWHERE in the transcript — including after long bookkeeping
+stretches. The opening is not evidence about the rest: real sessions often
+OPEN with bookkeeping (a compaction summary, a task notification, a status
+recap) and CONTAIN extractable material later. Read to the END of the
+transcript before deciding; NO_EXTRACT on a long, mixed session is almost
+always a mistake — when in doubt, extract the durable items.
+Counter-example (MUST be extracted, never NO_EXTRACT): a session opens with
+"Session summary: continuing the API migration; prior PR merged, tests
+green" but later the user confirms "standardize on the queue-based worker —
+make it the documented default" and corrects the assistant: "no, don't gate
+retries behind a flag — remove the flag entirely". That session yields at
+least a [D] standardization and an [E] correction; the summary opening
+changes nothing. Emitting NO_EXTRACT there would lose the only record of
+both.
+
 RULES:
 - Extract MAX 20 items total (quality over quantity)
 - Use EXACT names/versions/paths/numbers as they appear in the transcript —

package/dist/recall-index.d.ts

@@ -32,9 +32,23 @@
  * unchanged. Turn suppression still wins: a recently shown novelty pick is
  * suppressed like any other (the guarantee is about candidate inclusion, not
  * forcing re-shows).
+ *
+ * #329 item 3 — the pure search is SKIPPED when it would be byte-identical
+ * to the blended one: turn 1 (no centroid yet — nothing to blend) or
+ * sessionIntentWeight 0 (blend disabled). The blended result IS the pure
+ * result there, so the floor is trivially satisfied by the blended picks and
+ * the second search (embeds aside, its whole DB + FTS half) is pure waste.
+ *
+ * #329 item 4 — novelty backfill: when the blended picks are empty/short,
+ * unclaimed maxItems slots are filled from the remaining filtered
+ * pure-prompt tail (gate + suppression already applied). Without it the
+ * topic-switch turn — the one the floor exists for — got the MOST truncated
+ * menu: novelty slots + a diluted remainder, while further pure candidates
+ * that had already passed every gate sat unused.
  */
 import type Database from "better-sqlite3";
 import type { MemorySearchResult } from "./types.js";
+import * as storage from "./storage.js";
 import { SessionRecallRegistry } from "./recall-registry.js";
 export interface RecallIndexOptions {
     /** Minimum measured cosine for vector-only candidates (config
@@ -88,6 +102,16 @@ export interface RecallIndexResult {
     status: number;
     body: Record<string, unknown>;
 }
+/**
+ * Hard cap on `session_id` length (#328 item 2a). The id is retained as a Map
+ * key by SessionRecallRegistry for the process lifetime (maxSessions=500 LRU
+ * + a per-session shown-set + intent centroid), so an unbounded id is an OOM
+ * vector: ~4.9MB ids × 500 sessions ≈ 2.4GB of retained keys from an
+ * authenticated-but-hostile tenant. Real session ids (CC UUIDs, plugin
+ * session keys) are ≤64 chars — 128 is generous headroom. Longer → 400 with
+ * a clear error; the client treats it like any bad request.
+ */
+export declare const MAX_SESSION_ID_CHARS = 128;
 /** First content line, de-markdowned and truncated — the index line title. */
 export declare function memoryTitle(content: string, maxLen?: number): string;
 /**
@@ -166,11 +190,22 @@ export interface RecallIndexDeps {
  *     fold, or the pure prompt with NO centroid state for #324);
  *   - retrieve() with noStrengthen (exposure is recorded by
  *     handleRecallIndex via touchMemoriesShown, never here).
+ *
+ * #329 CR finding 1b: the FTS candidate list is ALSO computed once per
+ * request (ftsOnce, keyed on query + candidate window) and threaded into both
+ * retrieve() calls via the ftsCandidates provider — the blended and pure
+ * searches of one request carry identical query text and window, so their FTS
+ * halves were byte-identical SQL executed twice. `ftsFn` is the DI seam for
+ * tests (production: storage.searchFts); a throwing FTS computation memoizes
+ * to an empty shared list — the same vector-only degradation retrieve()'s
+ * catch always produced, never an error.
  */
 export declare function createRecallRetrieveFn(deps: {
     db: Database.Database;
     registry: SessionRecallRegistry;
     embedFn: (text: string) => Promise<Float32Array>;
+    /** FTS resolution override (tests). Defaults to storage.searchFts. */
+    ftsFn?: typeof storage.searchFts;
 }): RecallRetrieveFn;
 /** Normalize a request-supplied string-list param: array of strings or a CSV
  *  string → string[] | undefined. Anything else (or an empty result) means