@gamaze/hicortex 0.19.3 → 0.19.4

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,21 @@ 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 (#329 item 6): the ~6.3KB of static instructions come FIRST and the
+ * transcript LAST, so every distill call shares a byte-identical instruction
+ * prefix and provider-side prompt prefix caching can actually hit (per-session
+ * calls with the same project/date share everything up to the transcript; a
+ * multi-segment session — the common capture shape — re-uses the cached prefix
+ * for every segment after the first). The static block is the transcript-first
+ * block MOVED plus ONE deliberate addition in the same change: the #329 item-5
+ * [D]-override sentence in the NEVER-RECORD section ("a version bump, merge,
+ * or count is NEVER [D]"). Anyone diffing distill behavior across this change
+ * must baseline against BOTH the reorder and that wording addition. NOTE the
+ * prefix is only
+ * fully shared while project/date agree: "# Session Memory: ${date} -
+ * ${projectName}" and the (${date}) format examples interpolate inside the
+ * static block by design (the model needs the real date in its output format).
  */
 export declare function distillation(projectName: string, date: string, transcript: string): string;
 /**

package/dist/prompts.js

@@ -106,14 +106,26 @@ Respond with a JSON array. Empty array [] is a valid response.`;
 }
 /**
  * Distillation prompt. Extracts knowledge from a session transcript.
+ *
+ * LAYOUT (#329 item 6): the ~6.3KB of static instructions come FIRST and the
+ * transcript LAST, so every distill call shares a byte-identical instruction
+ * prefix and provider-side prompt prefix caching can actually hit (per-session
+ * calls with the same project/date share everything up to the transcript; a
+ * multi-segment session — the common capture shape — re-uses the cached prefix
+ * for every segment after the first). The static block is the transcript-first
+ * block MOVED plus ONE deliberate addition in the same change: the #329 item-5
+ * [D]-override sentence in the NEVER-RECORD section ("a version bump, merge,
+ * or count is NEVER [D]"). Anyone diffing distill behavior across this change
+ * must baseline against BOTH the reorder and that wording addition. NOTE the
+ * prefix is only
+ * fully shared while project/date agree: "# Session Memory: ${date} -
+ * ${projectName}" and the (${date}) format examples interpolate inside the
+ * static block by design (the model needs the real date in its output format).
  */
 function distillation(projectName, date, transcript) {
     return `You are a memory extraction agent. Analyze this AI session transcript and extract
 knowledge worth remembering long-term.
 
-SESSION TRANSCRIPT (project: ${projectName}, date: ${date}):
-${transcript}
-
 EXTRACT into this markdown format:
 
 # Session Memory: ${date} - ${projectName}
@@ -195,6 +207,9 @@ 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.
 
@@ -216,6 +231,9 @@ RULES:
   "[Strong Negative] User rejected per-agent billing"). The subject always comes first.
 - Omit any section that has zero items (don't include empty sections)
 - If nothing worth extracting, output ONLY: "NO_EXTRACT"
+
+SESSION TRANSCRIPT (project: ${projectName}, date: ${date}):
+${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

package/dist/recall-index.js

@@ -33,6 +33,19 @@
  * 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.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -68,7 +81,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_NOVELTY_FLOOR_SLOTS = void 0;
+exports.MAX_SESSION_ID_CHARS = exports.DEFAULT_NOVELTY_FLOOR_SLOTS = void 0;
 exports.resolveNoveltyFloorSlots = resolveNoveltyFloorSlots;
 exports.memoryTitle = memoryTitle;
 exports.formatIndexLine = formatIndexLine;
@@ -116,6 +129,16 @@ function resolveNoveltyFloorSlots(rawSlots, rawMaxItems) {
  *  gate is correct, not a defect); raise only if blocks are persistently
  *  under-filled in production. */
 const CANDIDATE_MULTIPLIER = 3;
+/**
+ * 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.
+ */
+exports.MAX_SESSION_ID_CHARS = 128;
 /** First content line, de-markdowned and truncated — the index line title. */
 function memoryTitle(content, maxLen = DEFAULT_TITLE_CHARS) {
     const firstLine = content
@@ -191,6 +214,15 @@ function passesRelevanceGate(r, minSimilarity) {
  *     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.
  */
 function createRecallRetrieveFn(deps) {
     let embMemo = null;
@@ -200,6 +232,21 @@ function createRecallRetrieveFn(deps) {
         }
         return embMemo.p;
     };
+    const ftsResolve = deps.ftsFn ?? storage.searchFts;
+    let ftsMemo = null;
+    const ftsOnce = (query, limit) => {
+        if (!ftsMemo || ftsMemo.query !== query || ftsMemo.limit !== limit) {
+            try {
+                ftsMemo = { query, limit, rows: ftsResolve(deps.db, query, limit) };
+            }
+            catch {
+                // Same degradation retrieve()'s own catch always produced — the FTS
+                // list is dropped and the search proceeds vector-only.
+                ftsMemo = { query, limit, rows: [] };
+            }
+        }
+        return ftsMemo.rows;
+    };
     return async (query, limit, filters, sessionId, purePrompt) => {
         const { weight, alpha } = (0, retrieval_js_1.getSessionIntent)();
         const promptEmb = await embedOnce(query);
@@ -216,6 +263,10 @@ function createRecallRetrieveFn(deps) {
             project: filters?.project,
             missionDomains: filters?.mission_domains,
             queryEmbedding: queryVec,
+            // #329: shared per-request FTS list. The recall path never passes
+            // sourceAgent, so the memo is keyed on (query, fetchLimit) only —
+            // exactly the two things retrieve() would pass to searchFts.
+            ftsCandidates: (fetchLimit) => ftsOnce(query, fetchLimit),
         });
     };
 }
@@ -242,6 +293,16 @@ async function handleRecallIndex(deps, body) {
     if (!sessionId) {
         return { status: 400, body: { error: "Missing 'session_id'" } };
     }
+    // Length cap (#328 item 2a) — BEFORE the reset branch so an oversized id
+    // never reaches ANY registry call (reset() itself only deletes, but the
+    // next non-reset call with the same id would beginTurn it into a retained
+    // Map key). Clear error so a misbehaving client can self-diagnose.
+    if (sessionId.length > exports.MAX_SESSION_ID_CHARS) {
+        return {
+            status: 400,
+            body: { error: `'session_id' too long (max ${exports.MAX_SESSION_ID_CHARS} chars, got ${sessionId.length})` },
+        };
+    }
     // Reset: SessionStart (startup/resume/clear/compact) — fresh context, so the
     // shown-set is stale by definition.
     if (req.reset === true) {
@@ -270,26 +331,30 @@ async function handleRecallIndex(deps, body) {
         project: typeof req.project === "string" && req.project ? req.project : undefined,
         mission_domains: parseStringListParam(req.mission_domains),
     };
-    // #324: when the floor is armed, TWO searches run per recall — the blended
-    // (session-intent) query that has always run, and a PURE-prompt query with
-    // no centroid blend. Issued together so the second adds no wall-clock
-    // latency beyond its own DB work (the prompt is embedded once — the closure
-    // memoizes). Same failure domain (same db + embedder): either failing fails
-    // the request explicitly; no silent blended-only degradation.
+    // #324 + #329 item 3: when the floor is armed AND would differ from the
+    // blended search, TWO searches run per recall — the blended (session-intent)
+    // query that has always run, and a PURE-prompt query with no centroid blend.
+    // Issued together so the second adds no wall-clock latency beyond its own DB
+    // work (the prompt is embedded once — the closure memoizes). Same failure
+    // domain (same db + embedder): either failing fails the request explicitly;
+    // no silent blended-only degradation.
     //
-    // The pure call fetches the SAME candidate window as the blended call
-    // (maxItems × 3). A narrower window would break the guarantee at the edge:
-    // sqlite-vec KNN candidates are fetched at limit × 3 and re-ranked by
-    // composite score, so a memory the fresh-session path ranks #1 by
-    // strength/recency but that sits at raw-vector rank 19+ would never enter
-    // a small window's candidate set — the #324 failure shape surviving at the
-    // edge. The guarantee is therefore: the top passing pure-prompt hit WITHIN
-    // the shared candidate window always survives into the index.
+    // The SKIP (#329 item 3): on turn 1 the registry has no centroid yet (the
+    // blended call reads-before-fold — recallQueryVector), and at
+    // sessionIntentWeight 0 the centroid is never read at all. In both cases
+    // the blended query vector IS the pure prompt vector, so the second search
+    // would return byte-identical candidates — skip it (the floor is trivially
+    // satisfied: every pure hit is by construction among the blended picks).
+    // The decision is made BEFORE any retrieveFn call, i.e. on the centroid
+    // state of the PREVIOUS turns — exactly the turn-1/turn-2 distinction.
+    const runPureSearch = noveltySlots > 0 &&
+        (0, retrieval_js_1.getSessionIntent)().weight > 0 &&
+        deps.registry.getCentroid(sessionId) !== undefined;
     let results;
     let pureResults;
     try {
         const blended = deps.retrieveFn(prompt, maxItems * CANDIDATE_MULTIPLIER, filters, sessionId);
-        const pure = noveltySlots > 0
+        const pure = runPureSearch
             ? deps.retrieveFn(prompt, maxItems * CANDIDATE_MULTIPLIER, filters, sessionId, true)
             : Promise.resolve([]);
         [results, pureResults] = await Promise.all([blended, pure]);
@@ -316,10 +381,14 @@ async function handleRecallIndex(deps, body) {
     // unchanged. Suppression applies BEFORE the guarantee (suppression wins:
     // the floor is about candidate inclusion, not forcing re-shows). FTS-sourced
     // pure hits pass the gate unconditionally, same as the blended path.
-    const blendedIds = new Set(blendedPicks.map((r) => r.id));
-    const noveltyPicks = pureResults
+    //
+    // The gate + suppression are applied ONCE to the pure list: the head feeds
+    // the novelty floor, the tail feeds the #329 backfill below.
+    const pureFiltered = pureResults
         .filter((r) => passesRelevanceGate(r, minSimilarity))
-        .filter((r) => deps.registry.isShowable(sessionId, r.id))
+        .filter((r) => deps.registry.isShowable(sessionId, r.id));
+    const blendedIds = new Set(blendedPicks.map((r) => r.id));
+    const noveltyPicks = pureFiltered
         .filter((r) => !blendedIds.has(r.id))
         .slice(0, noveltySlots);
     // The floor takes precedence (#324 vs #192 cold slots): novelty picks hold
@@ -329,10 +398,24 @@ async function handleRecallIndex(deps, body) {
     // exceeds maxItems. Render order: novelty picks FIRST — on a topic switch
     // they are the most relevant lines to the CURRENT turn, and the head of the
     // block carries the most weight for a reader scanning the menu.
-    const picked = [
+    let picked = [
         ...noveltyPicks,
         ...blendedPicks.slice(0, Math.max(0, maxItems - noveltyPicks.length)),
     ];
+    // #329 item 4 — backfill: a topic-switch turn dilutes the blended picks, so
+    // picked can land below maxItems even though FURTHER pure candidates have
+    // already passed the gate + suppression + dedup (they sit in the pure tail
+    // beyond the first noveltyFloorSlots). Fill the unclaimed slots from that
+    // tail — without it, the turn the floor exists for got the most truncated
+    // menu. Continuing-intent sessions are untouched: blended picks full →
+    // nothing to backfill (zero-delta output preserved).
+    if (picked.length < maxItems) {
+        const pickedIds = new Set(picked.map((r) => r.id));
+        const backfill = pureFiltered
+            .filter((r) => !pickedIds.has(r.id))
+            .slice(0, maxItems - picked.length);
+        picked = [...picked, ...backfill];
+    }
     if (picked.length === 0) {
         return { status: 200, body: { block: null, shown: [], turn } };
     }

package/dist/retrieval.d.ts

@@ -231,6 +231,17 @@ export declare function retrieve(db: Database.Database, embedFn: EmbedFn, query:
      *  and get pure-prompt behavior (the query string is embedded here). The
      *  FTS path still uses the raw `query` text regardless. */
     queryEmbedding?: Float32Array;
+    /** #329 CR finding 1b: caller-provided FTS candidate resolution, called
+     *  INSTEAD of running storage.searchFts here. The /recall-index closure
+     *  passes a per-request memoized provider so the blended and pure
+     *  searches of ONE request — same query text, same candidate window —
+     *  execute the FTS half exactly once and share the list. The provider
+     *  receives the fetchLimit/sourceAgent THIS call would have used, so the
+     *  shared list is always computed with the right window. Callers that
+     *  omit it get the previous behavior (retrieve runs searchFts itself). */
+    ftsCandidates?: (fetchLimit: number, sourceAgent?: string) => Array<Memory & {
+        rank: number;
+    }>;
 }): Promise<MemorySearchResult[]>;
 /**
  * Get recent context, optionally filtered by project.

package/dist/retrieval.js

@@ -556,8 +556,12 @@ async function retrieve(db, embedFn, query, options) {
     try {
         // sourceAgent is pushed into the FTS SQL (hard filter). project is NOT (it
         // is a soft affinity boost in computeScore as of #203). privacy is NOT
-        // (0.16.x: vestigial column, never filtered).
-        ftsCandidates = storage.searchFts(db, query, fetchLimit, sourceAgent);
+        // (0.16.x: vestigial column, never filtered). With a caller-provided
+        // provider (#329 request-level memo) the same list is shared across the
+        // retrieves of one recall request instead of re-executed.
+        ftsCandidates = options?.ftsCandidates
+            ? options.ftsCandidates(fetchLimit, sourceAgent)
+            : storage.searchFts(db, query, fetchLimit, sourceAgent);
     }
     catch {
         // FTS5 search can fail on special characters; fall back to vector-only

package/dist/storage.d.ts

@@ -137,6 +137,36 @@ export interface Bm25Weights {
 export declare function configureBm25Fts(config?: Record<string, unknown> | null): Bm25Weights;
 /** Current resolved weights (tests + status output). */
 export declare function getBm25Weights(): Bm25Weights;
+/**
+ * Cap on tokens fed to an FTS5 MATCH expression (#329 CR finding 1a).
+ * Quoting made pasted term lists LEGAL queries — and an all-common-tokens AND
+ * is expensive: measured at 100K rows, a 50-token AND runs ~518ms and a
+ * 200-token one 6.3s, and the /recall-index hot path would pay it twice per
+ * prompt. Beyond ~24 tokens the implicit AND is semantic noise anyway (a
+ * memory matching 24+ ANDed prompt tokens is either the exact text or
+ * nothing), so the FIRST 24 tokens are used. 24 is a shipped bound, not a
+ * config knob — change it deliberately, with a perf measurement.
+ */
+export declare const FTS_MATCH_MAX_TOKENS = 24;
+/**
+ * FTS5 MATCH-safety quoting (#329 item 1). The raw prompt is NOT valid FTS5
+ * query syntax: ordinary prompt punctuation (?, -, (, :, URLs, apostrophes, a
+ * leading AND/OR) crashes the FTS5 parser, and retrieval.retrieve's catch then
+ * silently drops the ENTIRE FTS candidate list — the perf sweep measured 8/12
+ * realistic prompts affected, and it is why relevance eval #3 saw 0 FTS rows
+ * in 2,208 candidates. Fix: tokenize on whitespace, strip embedded double
+ * quotes (a raw `"` would terminate our own quoting), and wrap each token in
+ * double quotes — a quoted token is a phrase of LITERAL strings, immune to
+ * FTS5 query syntax (`"what" "is" "the" "deployment" "status"`). Punctuation
+ * INSIDE a token is kept: the tokenizer strips it identically on both sides,
+ * so `"status?"` still matches content containing "status". Joined with spaces
+ * (implicit AND — the same semantics clean prompts always had; a PROSE prompt
+ * whose content holds only most of the tokens matches nothing, which is why
+ * FTS fires on short keyword prompts, not prose recall). Capped at the first
+ * FTS_MATCH_MAX_TOKENS tokens. A query that quotes away to nothing yields ""
+ * and the caller skips the SQL entirely.
+ */
+export declare function buildFtsMatchExpression(query: string): string;
 /**
  * Full-text search using FTS5 fielded BM25 (BM25F) ranking.
  * Returns memories with a rank field (lower is better — see sign note below).