@gamaze/hicortex 0.19.2 → 0.19.4

package/README.md

@@ -70,6 +70,11 @@ The plugin connects to `http://127.0.0.1:8787` by default. For a remote server,
 
 Bare top-level keys (`"serverUrl": …` at the root of `openclaw.json`) still work — legacy compat — but the nested form above is canonical. An empty nested `config` object is ignored rather than shadowing top-level keys.
 
+**Public-facing agents are hardened automatically.** On startup the plugin:
+
+1. Adds the 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."* — to the agent workspace bootstrap file (`BOOTSTRAP.md` in the workspace from `agents.defaults.workspace`, default `~/.openclaw/workspace`), creating the file if absent. This is the secondary layer under the hard `IDENTITY UNAVAILABLE` suspension banner the plugin injects whenever the identity fetch fails; it keeps guarding the agent even when the plugin itself cannot inject anything. The write is idempotent: the `.bak` backup is written once and never touched again. Scope: the shared default workspace only — per-agent workspace overrides are not covered yet. The workspace directory itself is never created (OpenClaw scaffolds it); a non-UTF-8 or relative-path bootstrap is left untouched with a warning. Disable the write with `"scaffoldDeadMan": false` in the plugin config.
+2. Warns once at startup while the gateway's plugin trust list is unpinned — with no `plugins.allow`, OpenClaw auto-loads any extension dropped into the plugins directory. Pin it by setting `"plugins": { "allow": ["hicortex"] }` in `~/.openclaw/openclaw.json` (list every plugin you trust). The plugin never edits the trust list itself; see [the install docs](https://hicortex.gamaze.com/docs/installation.html).
+
 ## Requirements
 
 - Node.js 20+
@@ -232,6 +237,8 @@ Config at `~/.hicortex/config.json`. Created by `init`. Key options:
 | `authToken` | Bearer token for endpoint auth. Generated on first `init` in server mode. Find the active token with `hicortex status` or in `~/.hicortex/config.json`. |
 | `corsAllowedOrigins` | Browser origins allowed to read cross-origin responses, e.g. `["https://ui.example.com"]`. **Empty by default** — the server sends no `Access-Control-Allow-Origin` and never `Allow-Credentials`, so no external web page can read its data. The bundled `/viz` and `/identity/ui` pages are same-origin and need no entry. |
 | `licenseKey` | Commercial license key (optional; for display in `hicortex status`) |
+| `backupRetention` | How many of the newest backup artifacts (`hicortex-*.tar.gz`) the backup dir keeps after each successful write (default: 7; `0` keeps all). See [Backups](#backups) |
+| _env_ `HICORTEX_DISTILL_BODY_LIMIT_MB` | Environment override for the `/distill` body limit — **wins over the `distillBodyLimitMb` config key in every mode** (that is the point: a deployment operator pins it so tenant-writable config cannot raise it). Unset = config/default applies. |
 | `domains` | Your memory domain list (`[{name, description}]`). Scaffolded by `init`; edit freely — see [Memory Domains & Tags](#memory-domains--tags) |
 | `weakPrimaryFloor` | Minimum similarity for a no-fit memory to keep a weak domain association (default: 0.45) |
 | `moduleIndexTokenBudget` | Max tokens for domain index in lessons context (default: 500) |
@@ -260,11 +267,12 @@ Config at `~/.hicortex/config.json`. Created by `init`. Key options:
 | `searchLimit` / `recentLimit` | Default result counts for search (8) and recent (12) |
 | `recentWindowDays` | Candidate window for recent recall (default: 180) |
 | `coldExposureSlots` | Top-k slots reservable for never-accessed memories so the long tail gets exposure (default: 2) |
-| `recallMaxItems` | Max lines in the pushed recall index (default: 6) |
-| `recallMinSimilarity` | Relevance floor for index entries (default: 0.55; text-search matches always pass) |
+| `recallMaxItems` | Max lines in the pushed recall index (default: 5) |
+| `noveltyFloorSlots` | Slots of `recallMaxItems` guaranteed to the top passing hit(s) of the pure-prompt (unblended) search — the novelty floor. Keeps a session whose earlier turns set a strong intent from burying a topic-switching prompt's best matches: the floor's picks render first, turn-based re-show suppression still applies, and the total never exceeds `recallMaxItems` (default: 2; set 0 to disable) |
+| `recallMinSimilarity` | Relevance floor for index entries (default: 0.62; text-search matches always pass) |
 | `recallReshowTurns` | Turns before an already-shown memory may reappear in the same session (default: 30) |
 | `recallMinPromptChars` | Prompts shorter than this skip the recall index (default: 20) |
-| `recallTitleChars` | Chars of each memory's first line shown in an index entry (default: 150, range 40–400). Raised from 100 on 2026-08-02: with topic-first memory titles, 150 chars carries the subject *and* its claim, where 100 cut the claim mid-sentence. Costs roughly +74 tokens per 6-line block |
+| `recallTitleChars` | Chars of each memory's first line shown in an index entry (default: 100, range 40–400). Reverted from 150 on 2026-08-03: a full-corpus relevance eval found 100 and 150 statistically identical while 100 saves ~13% of the block's tokens |
 | `sessionIntentWeight` | Blend weight of the session-intent rolling centroid in the recall search vector: `query = (1-w)·prompt + w·centroid` (default: 0.33; set 0 to disable — pure-prompt recall, the kill-switch). The first turn of a session searches with pure prompt and seeds the centroid; subsequent turns blend so recall follows the session's intent instead of being query-literal. The EMA rate (0.4) is a shipped constant, not configurable |
 | `dedupMergeThreshold` | Minimum cosine similarity for `hicortex dedup` to cluster memories as near-duplicates (default: 0.92) |
 | `supersessionMinSimilarity` | Minimum cosine similarity for a nightly supersession candidate pair (default: 0.80) |
@@ -316,6 +324,7 @@ Optional config (add to plugin entry in `~/.openclaw/openclaw.json`):
 | `authToken` | _(none)_ | Bearer token. Localhost bypasses auth; required for remote servers. Get the token from `hicortex status` on the server. |
 | `defaultProject` | _(none)_ | Project name sent on recall, search, recent, and ingest whenever the gateway supplies no project (Hermes `default_project` parity). |
 | `recallLimit` | `8` | Max memories per recall on the pre-0.14 `/search` fallback. The pushed recall index is sized by SERVER config (`recallMaxItems`) — the server accepts no client limit. |
+| `scaffoldDeadMan` | `true` | Auto-scaffold the dead-man identity-guard line into the agent workspace bootstrap (`BOOTSTRAP.md`) at startup. Set `false` to disable the write and any file creation entirely. |
 
 If `serverUrl`/`authToken` are absent from the config, the `HICORTEX_URL` and `HICORTEX_AUTH_TOKEN` environment variables are used as fallbacks (config always wins).
 
@@ -354,10 +363,13 @@ The artifact contains the irreplaceable data only: `hicortex.db`, the whole `ide
 ```jsonc
 {
   "backupDir": "/mnt/backups/hicortex",          // optional; default <home>/backups
-  "backupCommand": "rclone copyto"               // invoked: rclone copyto <path> remote:hicortex/
+  "backupCommand": "rclone copyto",              // invoked: rclone copyto <path> remote:hicortex/
+  "backupRetention": 7                           // keep the N newest artifacts (default 7; 0 = keep all)
 }
 ```
 
+**Retention.** After every successful write, the backup dir is pruned to the `backupRetention` newest artifacts — without it each nightly adds a tar.gz forever. Only files matching the product's own `hicortex-*.tar.gz` pattern are ever removed; anything else you keep in the dir is untouched. That pattern is the pruner's — **do not name your own copies `hicortex-*.tar.gz`**: a manual copy kept in the backup dir under that shape counts against retention and will be deleted once it falls past the boundary. Name operator copies differently (e.g. `manual-2026-08-19.tar.gz`). Applies to the nightly stage and `hicortex backup` alike (not to `--stdout`, which writes nothing on disk).
+
 A failing, missing, or timed-out hook (5 min) reports failure and **never throws** — the artifact is already on disk; only the offsite copy didn't land. Both `hicortex backup` (non-zero exit) and the nightly stage surface the failure.
 
 **Stream to stdout** (pipe to any offsite transport, no on-disk artifact):
@@ -368,7 +380,7 @@ npx @gamaze/hicortex backup --stdout | rclone rcat remote:hicortex/$(date -I).ta
 
 `--stdout` is mutually exclusive with `--out`/`backupDir`.
 
-**Nightly stage.** Every full nightly run (not `--capture-only`) takes a backup automatically after consolidation and runs the hook if configured. Backup failure does NOT fail the nightly — capture + consolidation have already succeeded; the failure surfaces as `backupOk:false` in the dashboard snapshot and telemetry for alerting.
+**Nightly stage.** Every full nightly run takes a backup automatically after consolidation and runs the hook if configured — and prunes per `backupRetention`. `--consolidate-only` runs back up too, but at most once a day: the stage is skipped only while the newest existing artifact is younger than ~20 hours (so a timer that fires several times a day still yields exactly one backup per day, bounded by retention). `--capture-only` never backs up (it is frequent and stateless). Backup failure does NOT fail the nightly — capture + consolidation have already succeeded; the failure surfaces as `backupOk:false` in the dashboard snapshot and telemetry for alerting.
 
 **Restore (manual):**
 

package/dist/backup.d.ts

@@ -31,6 +31,13 @@
  * `memories.content` via the embedder — non-destructive either way.
  */
 import type Database from "better-sqlite3";
+/**
+ * Default number of backup artifacts kept in the backup dir (#327). The
+ * nightly backup stage writes one `hicortex-<ISO>.tar.gz` per run with no
+ * pruning — unbounded growth (per hosted tenant too). Configurable via
+ * `backupRetention`; 0 keeps everything.
+ */
+export declare const DEFAULT_BACKUP_RETENTION = 7;
 export interface CreateBackupOptions {
     /** Open live DB handle (caller manages lifetime). Backed up via db.backup(). */
     db: Database.Database;
@@ -46,12 +53,27 @@ export interface CreateBackupOptions {
      * set. Configurable via `config.backupDir`.
      */
     outDir?: string;
+    /**
+     * Directory for the transient DB snapshot (defaults to the OS tmpdir).
+     * Injectable so tests observe a PRIVATE dir — vitest runs files in parallel,
+     * and a sibling test's in-flight snapshot in the shared tmpdir reads as a
+     * "leak" to a before/after diff (final consolidation CR finding 1).
+     */
+    snapshotDir?: string;
     /**
      * Stream the tar.gz to `process.stdout` instead of writing a file (the
      * offsite pattern: `hicortex backup --stdout | rclone rcat ...`). Mutually
      * exclusive with `outFile`/`outDir`.
      */
     stdout?: boolean;
+    /**
+     * Retention (#327): how many of the newest `hicortex-*.tar.gz` artifacts to
+     * keep in the (dir-managed) output dir after a successful write. 0 keeps
+     * all. Defaults to DEFAULT_BACKUP_RETENTION; callers resolve the
+     * `backupRetention` config key. Only consulted when the artifact goes to
+     * `outDir`/the default dir — an explicit `outFile` is caller-owned.
+     */
+    retention?: number;
 }
 export interface CreateBackupResult {
     /** Absolute path of the written artifact; undefined when `stdout:true`. */
@@ -60,6 +82,11 @@ export interface CreateBackupResult {
     bytes: number;
     /** Number of files packaged (DB snapshot + identity tree + state files). */
     files: number;
+    /**
+     * Old artifacts removed by the retention pass (#327). Undefined when no
+     * retention pass ran (stdout / explicit outFile); 0 = nothing to prune.
+     */
+    pruned?: number;
 }
 export interface BackupHookResult {
     ok: boolean;
@@ -92,6 +119,29 @@ export declare function createBackup(opts: CreateBackupOptions): Promise<CreateB
  * here is deliberately dumb to avoid re-implementing a shell parser.
  */
 export declare function runBackupHook(artifactPath: string, command: string | undefined): Promise<BackupHookResult>;
+/**
+ * mtime (ms) of the NEWEST `hicortex-*.tar.gz` in `dir`, or undefined when the
+ * dir has none / cannot be read. The nightly consolidate-only artifact-age
+ * gate (#327 CR) uses this to bound the hosted backup cadence to ~1/day
+ * without a new state file: the newest artifact on disk IS the
+ * "last backed up" marker. Same product-owned filename pattern the pruner
+ * matches, so the gate and the pruner can never disagree about what counts.
+ */
+export declare function newestBackupArtifactMs(dir: string): number | undefined;
+/**
+ * Prune a backup dir to the `retention` newest artifacts (#327). Matches ONLY
+ * files named `hicortex-*.tar.gz` (the nightly/CLI artifact pattern) — anything
+ * else in the dir (operator copies, notes) is never touched. Keeps the newest
+ * `retention` by mtime, with the ISO filename (time-ordered by construction)
+ * as a DESCENDING tie-break so equal mtimes resolve deterministically (the
+ * just-written artifact is the newest and always survives); deletes the rest,
+ * oldest first. `retention <= 0` keeps all.
+ *
+ * Best-effort by design: a per-file unlink failure logs and continues (a
+ * stale extra artifact is cheap; failing the nightly AFTER a good backup was
+ * written is not). Returns the number actually removed.
+ */
+export declare function pruneBackupArtifacts(dir: string, retention: number): number;
 export interface BackupCliOptions {
     /** `--out <dir>` — output directory (the artifact is auto-named). Takes precedence over `config.backupDir`. Mutually exclusive with stdout. */
     outDir?: string;

package/dist/backup.js

@@ -32,8 +32,11 @@
  * `memories.content` via the embedder — non-destructive either way.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_BACKUP_RETENTION = void 0;
 exports.createBackup = createBackup;
 exports.runBackupHook = runBackupHook;
+exports.newestBackupArtifactMs = newestBackupArtifactMs;
+exports.pruneBackupArtifacts = pruneBackupArtifacts;
 exports.runBackupCli = runBackupCli;
 const node_child_process_1 = require("node:child_process");
 const node_crypto_1 = require("node:crypto");
@@ -45,6 +48,7 @@ const tar_stream_1 = require("tar-stream");
 const paths_js_1 = require("./paths.js");
 const db_js_1 = require("./db.js");
 const init_js_1 = require("./init.js");
+const config_read_js_1 = require("./config-read.js");
 /**
  * Hook timeout — a stuck offsite upload (rclone/aws/B2 hung on a dead network)
  * must NOT hang the nightly. 5 min is generous for typical tarball uploads; the
@@ -52,6 +56,13 @@ const init_js_1 = require("./init.js");
  * block forever" discipline.
  */
 const HOOK_TIMEOUT_MS = 5 * 60 * 1000;
+/**
+ * Default number of backup artifacts kept in the backup dir (#327). The
+ * nightly backup stage writes one `hicortex-<ISO>.tar.gz` per run with no
+ * pruning — unbounded growth (per hosted tenant too). Configurable via
+ * `backupRetention`; 0 keeps everything.
+ */
+exports.DEFAULT_BACKUP_RETENTION = 7;
 /**
  * Create a backup artifact. Snapshots the live DB via the online-backup API,
  * packages it with the identity tree + state into a single `tar.gz`, and writes
@@ -69,7 +80,7 @@ async function createBackup(opts) {
     // 1. Snapshot the live DB via the WAL-safe online-backup API (proven at
     //    dedup.ts:499). Runs concurrently with the live DB — no writer blocking,
     //    no torn copy. The temp file is cleaned up in `finally` below.
-    const snapshotPath = (0, node_path_1.join)((0, node_os_1.tmpdir)(), `hicortex-backup-${(0, node_crypto_1.randomBytes)(6).toString("hex")}.db`);
+    const snapshotPath = (0, node_path_1.join)(opts.snapshotDir ?? (0, node_os_1.tmpdir)(), `hicortex-backup-${(0, node_crypto_1.randomBytes)(6).toString("hex")}.db`);
     await opts.db.backup(snapshotPath);
     let totalBytes = 0;
     let fileCount = 0;
@@ -144,7 +155,14 @@ async function createBackup(opts) {
         }
         packStream.finalize();
         await sinkFinished;
-        return { path: outFile, bytes: totalBytes, files: fileCount };
+        // Retention (#327) — only after a SUCCESSFUL write (a failed one removed
+        // its own partial artifact above), and only for dir-managed targets: an
+        // explicit outFile is caller-owned, and --stdout writes nothing to prune.
+        let pruned;
+        if (!opts.stdout && opts.outFile === undefined) {
+            pruned = pruneBackupArtifacts((0, node_path_1.dirname)(outFile), opts.retention ?? exports.DEFAULT_BACKUP_RETENTION);
+        }
+        return { path: outFile, bytes: totalBytes, files: fileCount, pruned };
     }
     catch (err) {
         // Never leave a truncated/half-written artifact on disk masquerading as a
@@ -231,6 +249,101 @@ async function runBackupHook(artifactPath, command) {
 // ---------------------------------------------------------------------------
 // File-set helpers
 // ---------------------------------------------------------------------------
+/**
+ * mtime (ms) of the NEWEST `hicortex-*.tar.gz` in `dir`, or undefined when the
+ * dir has none / cannot be read. The nightly consolidate-only artifact-age
+ * gate (#327 CR) uses this to bound the hosted backup cadence to ~1/day
+ * without a new state file: the newest artifact on disk IS the
+ * "last backed up" marker. Same product-owned filename pattern the pruner
+ * matches, so the gate and the pruner can never disagree about what counts.
+ */
+function newestBackupArtifactMs(dir) {
+    let names;
+    try {
+        names = (0, node_fs_1.readdirSync)(dir);
+    }
+    catch {
+        // Missing/unreadable dir — no artifact, no gate (a fresh install backs up).
+        return undefined;
+    }
+    let newest;
+    for (const n of names) {
+        if (!/^hicortex-.*\.tar\.gz$/.test(n))
+            continue;
+        try {
+            const ms = (0, node_fs_1.statSync)((0, node_path_1.join)(dir, n)).mtimeMs;
+            if (newest === undefined || ms > newest)
+                newest = ms;
+        }
+        catch {
+            // Raced/unreadable — an unknown-age artifact cannot inform the gate.
+        }
+    }
+    return newest;
+}
+/**
+ * Prune a backup dir to the `retention` newest artifacts (#327). Matches ONLY
+ * files named `hicortex-*.tar.gz` (the nightly/CLI artifact pattern) — anything
+ * else in the dir (operator copies, notes) is never touched. Keeps the newest
+ * `retention` by mtime, with the ISO filename (time-ordered by construction)
+ * as a DESCENDING tie-break so equal mtimes resolve deterministically (the
+ * just-written artifact is the newest and always survives); deletes the rest,
+ * oldest first. `retention <= 0` keeps all.
+ *
+ * Best-effort by design: a per-file unlink failure logs and continues (a
+ * stale extra artifact is cheap; failing the nightly AFTER a good backup was
+ * written is not). Returns the number actually removed.
+ */
+function pruneBackupArtifacts(dir, retention) {
+    if (!Number.isFinite(retention) || retention <= 0)
+        return 0;
+    let names;
+    try {
+        names = (0, node_fs_1.readdirSync)(dir);
+    }
+    catch {
+        // Missing/unreadable dir — nothing to prune (e.g. a fresh install).
+        return 0;
+    }
+    const artifacts = names
+        .filter((n) => /^hicortex-.*\.tar\.gz$/.test(n))
+        .map((n) => {
+        const abs = (0, node_path_1.join)(dir, n);
+        let mtimeMs = 0;
+        try {
+            mtimeMs = (0, node_fs_1.statSync)(abs).mtimeMs;
+        }
+        catch {
+            // Raced/unreadable — sort it oldest so the prune attempt happens
+            // anyway (force-unlink below may still succeed).
+        }
+        return { name: n, abs, mtimeMs };
+    })
+        // Newest first; the ISO filename (`hicortex-<ISO>.tar.gz`) is time-ordered
+        // by construction, so it is the tie-break in DESCENDING order — identical
+        // mtimes (same-second writes, or an operator restoring a copy) otherwise
+        // leave the retention boundary to readdir order, which is FS-arbitrary
+        // and can differ run to run (#327 CR).
+        .sort((a, b) => b.mtimeMs - a.mtimeMs ||
+        (a.name < b.name ? 1 : a.name > b.name ? -1 : 0));
+    const doomed = artifacts.slice(Math.floor(retention));
+    let pruned = 0;
+    for (const a of doomed) {
+        try {
+            (0, node_fs_1.rmSync)(a.abs, { force: true });
+            pruned++;
+        }
+        catch (err) {
+            console.error(`[hicortex] backup retention: could not prune ${a.abs}: ` +
+                `${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    if (pruned > 0) {
+        console.log(`[hicortex] Backup retention: pruned ${pruned} old artifact(s), ` +
+            `keeping ${artifacts.length - pruned}`);
+    }
+    return pruned;
+}
 /**
  * Recursively append every regular file under `absDir` to `entries`, with
  * in-tar paths rooted at `relRoot`. Symlinks are SKIPPED (security — a symlink
@@ -304,6 +417,8 @@ async function runBackupCli(opts) {
     const backupCommand = typeof config.backupCommand === "string" && config.backupCommand.trim()
         ? config.backupCommand
         : undefined;
+    // Same reader + default as the nightly stage (#327) — one knob everywhere.
+    const retention = (0, config_read_js_1.readNonNegativeConfig)(config, "backupRetention", exports.DEFAULT_BACKUP_RETENTION);
     const db = (0, db_js_1.initDb)((0, db_js_1.resolveDbPath)());
     try {
         const result = await createBackup({
@@ -315,6 +430,7 @@ async function runBackupCli(opts) {
             // exclusivity check would otherwise reject it).
             outDir: opts.stdout ? undefined : (opts.outDir ?? backupDir),
             stdout: opts.stdout,
+            retention,
         });
         if (result.path) {
             console.log(`[hicortex] Backup written: ${result.path} ` +

package/dist/capture.d.ts

@@ -71,6 +71,12 @@ export interface PostResult {
     dropped?: string[];
     skipped?: boolean;
     error?: string;
+    /**
+     * Parsed `Retry-After` of a 429 response, in ms (#327). Absent when the
+     * response carried no parseable header. Honored (capped) by the in-run
+     * rate-limit retry; a token-budget 429 ignores it (terminal, not transient).
+     */
+    retryAfterMs?: number;
     /**
      * The segment's metered LLM usage from the 201 body (#287). Absent on a
      * pre-#287 daemon (or any non-201) — callers must treat absent as zero.
@@ -106,9 +112,20 @@ export interface CaptureResult {
     hadTransientFailure: boolean;
     /**
      * Set when the loop stopped early on a terminal server response: "limit"
-     * (429 memory cap) or "auth" (401). The caller decides watermark handling.
+     * (token-budget 429, mcp-server.ts's `"token budget exceeded"` gate) or
+     * "auth" (401). A rate-limit 429 never sets this — it is transient (#327).
+     * The caller decides watermark handling.
      */
     stopped?: "limit" | "auth";
+    /**
+     * Run-global rate-429 latch (#327 CR): true when at least one session
+     * SURRENDERED to a rate-limit 429 (the transient kind — postWithRateRetry
+     * exhausted its in-run retries) and the remaining sessions were skipped
+     * without POSTing. Mirrors `stopped`'s role but is transient, not terminal:
+     * hadTransientFailure is also set, so the watermark holds and every skipped
+     * session retries next run with its cursor untouched.
+     */
+    rateLimited: boolean;
     /**
      * Sum of the successful segments' reported LLM usage (#287) — the run's
      * distill spend, for the dashboard snapshot's token totals. Zero-filled when
@@ -138,11 +155,19 @@ export declare function hardSplitText(text: string, maxChars?: number): string[]
  * hard-split pieces (A2).
  */
 export declare function packSegments(entries: unknown[], startCursor: number, entryCursors: number[], maxChars?: number): Segment[];
+/** True when a 429 result is the tenant token-budget gate (terminal). */
+export declare function isTokenBudget429(result: PostResult): boolean;
+/** In-run retries for a rate-limit 429 before giving up as transient. */
+export declare const RATE_LIMIT_RETRIES = 3;
 /**
  * Capture a list of session delta batches: pack, POST in order, advance
  * per-session cursors on success. Segments of one session POST in order; the
  * first hard failure stops THAT session (cursor holds at the last confirmed
- * boundary) while other sessions continue. A 429/401 stops the whole loop.
+ * boundary) while other sessions continue. A budget-429/401 stops the whole
+ * loop; a rate-429 is retried in-run before giving up as transient — and a
+ * SURRENDERED rate-429 latches the whole run: remaining sessions skip
+ * without POSTing (their cursors hold; next run retries) instead of each
+ * re-paying the Retry-After ladder (#327).
  */
 export declare function captureBatches(batches: TranscriptBatch[], opts: CaptureOptions): Promise<CaptureResult>;
 /**

package/dist/capture.js

@@ -14,9 +14,10 @@
  * multi-night simulation can run as a pure unit test with no HTTP listener.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MIN_SEGMENT_CHARS = exports.SEGMENT_MAX_CHARS = void 0;
+exports.RATE_LIMIT_RETRIES = exports.MIN_SEGMENT_CHARS = exports.SEGMENT_MAX_CHARS = void 0;
 exports.hardSplitText = hardSplitText;
 exports.packSegments = packSegments;
+exports.isTokenBudget429 = isTokenBudget429;
 exports.captureBatches = captureBatches;
 exports.acquireCaptureLock = acquireCaptureLock;
 const node_fs_1 = require("node:fs");
@@ -127,11 +128,80 @@ function packSegments(entries, startCursor, entryCursors, maxChars = exports.SEG
     flushGroup(entries.length);
     return segments;
 }
+// ---------------------------------------------------------------------------
+// 429 taxonomy (#327) — two producers share one status code
+// ---------------------------------------------------------------------------
+//   - The tenant server's token-budget gate (mcp-server.ts:1205) answers
+//     429 `{"error":"token budget exceeded"}` — TERMINAL for the billing
+//     period; retrying cannot help, so capture stops with stopped:"limit".
+//   - A rate limit (e.g. a hosted router's per-token limiter answering
+//     429 `{"error":"rate limit exceeded"}` + Retry-After) is TRANSIENT —
+//     the window passes in seconds/minutes. Treating it as the terminal
+//     limit-stop left nightlies failing forever with the wrong diagnosis.
+// The body's error string is the discriminator: only the budget gate says
+// "token budget".
+/** True when a 429 result is the tenant token-budget gate (terminal). */
+function isTokenBudget429(result) {
+    return typeof result.error === "string" && /token budget/i.test(result.error);
+}
+/** In-run retries for a rate-limit 429 before giving up as transient. */
+exports.RATE_LIMIT_RETRIES = 3;
+/**
+ * Backoff schedule (ms) between rate-429 retries: 5s, 15s, 30s — short enough
+ * to ride out a per-token limiter window inside one nightly, long enough to
+ * let a busy shared backend drain. Overridable via
+ * HICORTEX_RATE_LIMIT_BACKOFF_MS (comma-separated ms list — tests only).
+ */
+const RATE_LIMIT_BACKOFF_MS = [5_000, 15_000, 30_000];
+/**
+ * Cap on an honored Retry-After. The header is advisory and can name a window
+ * far beyond one nightly (an hourly limiter saying 3600); waiting it out
+ * in-run would stall the run for hours with the capture lock held. Past the
+ * cap we give up as transient — the cursor holds and the next run retries.
+ */
+const RATE_LIMIT_RETRY_AFTER_CAP_MS = 5 * 60 * 1000;
+function rateLimitBackoffSchedule() {
+    const env = process.env.HICORTEX_RATE_LIMIT_BACKOFF_MS;
+    if (env && env.trim()) {
+        const parsed = env.split(",").map((s) => Number(s.trim()));
+        if (parsed.length > 0 && parsed.every((n) => Number.isFinite(n) && n >= 0)) {
+            return parsed;
+        }
+    }
+    return RATE_LIMIT_BACKOFF_MS;
+}
+/**
+ * POST one segment, retrying in-run while the answer is a TRANSIENT
+ * (non-budget) 429. Returns the final result — a budget-429 passes through
+ * untouched (the caller's terminal branch) and a rate-429 that survived every
+ * retry is returned as-is for the caller's transient branch. Network errors
+ * propagate to the caller's existing catch (message preserved).
+ */
+async function postWithRateRetry(post, body) {
+    const schedule = rateLimitBackoffSchedule();
+    for (let attempt = 0;; attempt++) {
+        const result = await post(body);
+        if (result.status !== 429 || isTokenBudget429(result))
+            return result;
+        if (attempt >= exports.RATE_LIMIT_RETRIES || attempt >= schedule.length)
+            return result;
+        const waitMs = result.retryAfterMs != null && result.retryAfterMs > 0
+            ? Math.min(result.retryAfterMs, RATE_LIMIT_RETRY_AFTER_CAP_MS)
+            : schedule[attempt];
+        console.log(`[hicortex]     Rate limited (${result.error ?? "429"}) — retrying segment in ` +
+            `${Math.round(waitMs / 1000)}s (retry ${attempt + 1}/${exports.RATE_LIMIT_RETRIES})`);
+        await sleep(waitMs);
+    }
+}
 /**
  * Capture a list of session delta batches: pack, POST in order, advance
  * per-session cursors on success. Segments of one session POST in order; the
  * first hard failure stops THAT session (cursor holds at the last confirmed
- * boundary) while other sessions continue. A 429/401 stops the whole loop.
+ * boundary) while other sessions continue. A budget-429/401 stops the whole
+ * loop; a rate-429 is retried in-run before giving up as transient — and a
+ * SURRENDERED rate-429 latches the whole run: remaining sessions skip
+ * without POSTing (their cursors hold; next run retries) instead of each
+ * re-paying the Retry-After ladder (#327).
  */
 async function captureBatches(batches, opts) {
     const { post, cursorStore, dryRun = false, segmentMaxChars = exports.SEGMENT_MAX_CHARS, sourceAgentId, sourceDomain } = opts;
@@ -139,10 +209,16 @@ async function captureBatches(batches, opts) {
     let sessionsSent = 0;
     let hadTransientFailure = false;
     let stopped;
+    // Run-global rate-429 latch (#327 CR): once one session has paid the full
+    // Retry-After ladder and surrendered, the limiter window is exhausted for
+    // THIS run — letting each remaining session re-pay the ladder (worst case
+    // ~15 min each at the 5-min cap, with the capture lock held) can stretch a
+    // 20-session run to hours for zero accepted segments.
+    let rateLimited = false;
     // #287: distill tokens reported by successful 201s only — skips (200) and
     // failures metered nothing client-side.
     const distillUsage = { prompt: 0, completion: 0, total: 0 };
-    for (const batch of batches) {
+    for (const [batchIdx, batch] of batches.entries()) {
         const short = batch.sessionId.slice(0, 8);
         const segments = packSegments(batch.entries, batch.startCursor, batch.entryCursors, segmentMaxChars);
         if (segments.length === 0)
@@ -198,7 +274,7 @@ async function captureBatches(batches, opts) {
             };
             let result;
             try {
-                result = await post(body);
+                result = await postWithRateRetry(post, body);
             }
             catch (err) {
                 console.error(`[hicortex]     Capture failed: ${err instanceof Error ? err.message : String(err)} — will retry next run`);
@@ -228,11 +304,24 @@ async function captureBatches(batches, opts) {
                 if (result.skipped)
                     console.log(`[hicortex]     Segment ${body.segment_id} already ingested`);
             }
-            else if (result.status === 429) {
+            else if (result.status === 429 && isTokenBudget429(result)) {
                 console.log(`[hicortex]   Memory limit reached: ${result.error}. Stopping capture.`);
                 stopped = "limit";
                 break;
             }
+            else if (result.status === 429) {
+                // Rate-limit 429 that already burned its in-run retries (postWithRateRetry).
+                // Transient, NOT a limit stop (#327): hold the cursor, let the next run
+                // retry — a misdiagnosed "memory limit" here failed nightlies forever.
+                console.error(`[hicortex]     Rate limited: ${result.error ?? "429"} — giving up this run, ` +
+                    `will retry next run (cursor held)`);
+                hadTransientFailure = true;
+                // Latch the WHOLE run (see the declaration above): remaining sessions
+                // are skipped below, cursors untouched — they retry next run instead
+                // of each re-paying the full Retry-After ladder.
+                rateLimited = true;
+                break;
+            }
             else if (result.status === 401) {
                 console.error(`[hicortex]     Auth failed. Check authToken in ~/.hicortex/config.json`);
                 stopped = "auth";
@@ -265,8 +354,16 @@ async function captureBatches(batches, opts) {
         }
         if (stopped)
             break;
+        if (rateLimited) {
+            const remaining = batches.length - batchIdx - 1;
+            if (remaining > 0) {
+                console.error(`[hicortex]   Rate limited earlier this run — skipping ${remaining} remaining ` +
+                    `session(s); they retry next run (cursors untouched)`);
+            }
+            break;
+        }
     }
-    return { memoriesIngested, sessionsSent, hadTransientFailure, stopped, distillUsage };
+    return { memoriesIngested, sessionsSent, hadTransientFailure, stopped, rateLimited, distillUsage };
 }
 // ---------------------------------------------------------------------------
 // Single-flight guard (A5)

package/dist/embedder.d.ts

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

package/dist/embedder.js

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

package/dist/index.d.ts

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