switchroom 0.19.24 → 0.19.25

package/dist/vault/broker/server.js

@@ -4164,7 +4164,11 @@ var init_schema = __esm(() => {
     recall: exports_external.object({
       max_memories: exports_external.number().int().min(0).optional().describe("Cap on the number of memories injected into the prompt by " + "auto-recall, regardless of token budget. Plugin default is 12. " + "0 disables the cap (all memories Hindsight returns are injected)."),
       cache_ttl_secs: exports_external.number().int().min(0).optional().describe("Per-session recall cache TTL in seconds. When > 0, identical " + "(prompt, bank) within the same session reuse the cached recall " + "result instead of round-tripping to Hindsight. 0 disables. " + "Default is 600 (10 min) for switchroom-managed agents."),
-      min_overlap: exports_external.number().min(0).max(1).optional().describe("Minimum containment token overlap [0.0–1.0] between the user " + "prompt and a memory's text for the memory to be injected. " + "A cheap FLOOR that removes candidates with (near-)zero lexical " + "relationship to the prompt — NOT a precision control: at the " + "recommended 0.10 the gate is near-passthrough, and the " + "effective precision control is the engine rerank plus the " + "max_memories head-slice. 0.0 disables (default — current " + "behaviour). Use 0.10; values at or above 0.20 measurably " + "starve recall — on production replay 0.20 leaves ~41.9% of " + "turns with NO memories at all, re-creating the bug #3541 " + "fixed. Observe the `overlap_dropped` field via " + "`switchroom memory recall-log`."),
+      query_max_tokens: exports_external.number().int().min(0).optional().describe("Cap on the number of DISTINCT BM25 terms the recall hook may " + "put on the wire. `recallMaxQueryChars` bounds characters, which " + "is not the cost driver: Hindsight OR-joins every query token " + "into one tsquery and Postgres native FTS ranks the entire " + "matched set before the top-60 heapsort, so cost tracks TERMS. " + "An 800-char composed query is ~96 distinct terms and matched " + "119,510 of 135,565 rows on the `overlord` bank (14.0s for the " + "3-arm " + "BM25 UNION), past the per-bank timeout — 96.8% of that agent's " + "own-bank recalls returned nothing. Plugin default is 24 " + "(measured 48,433 rows / 2.7s on the same bank). Terms are " + "chosen recency-first (the latest turn beats prior context), " + "then by selectivity. 0 disables shaping (rollback lever)."),
+      query_stop_terms: exports_external.array(exports_external.string().min(1).regex(/^[\w./-]+$/)).optional().describe("Extra terms dropped from the BM25 recall query, on top of the " + "built-in English stopword list. For BANK-SPECIFIC " + "high-document-frequency words a generic stoplist cannot know " + "about: on `overlord`, `switchroom` matches 20% of the bank and " + "`agent` another 20%, purely because that is what the corpus is " + "about, and each such term drags tens of thousands of rows into " + "the ranking. Defaults to []."),
+      request_timeout_seconds: exports_external.number().int().min(1).optional().describe("Per-bank HTTP read timeout, in seconds, for one recall " + "request. Plugin default is 12, matching the UserPromptSubmit " + "hook ceiling; the shared `recallParallelDeadlineSeconds` (10) " + "is the tighter outer guard in the default configuration, so " + "this is a per-request safety net. Was a hardcoded 8 in the " + "plugin before #3757."),
+      own_bank_min_slots: exports_external.number().int().min(0).optional().describe("Slots inside `max_memories` reserved as a FLOOR for the agent's " + "own bank when recall fans out to more than one bank. The merged " + "set is sorted globally by relevance and head-sliced, which is " + "winner-take-all across banks: when both banks return more " + "candidates than the cap, one bank's score distribution can fill " + "every slot and the agent gets a dossier about its operator with " + "none of its own session memory. A floor, not a quota: at most " + "this many slots, only if the own bank returned that many, and " + "only up to HALF the cap shared with `additional_bank_min_slots` " + "— the rest is always won on pure relevance, so composition still " + "moves with the scores. Fixes score-based crowd-out only; a " + "timed-out bank returns no candidates and reservation is a no-op " + "there. 0 disables (default). Switchroom-managed agents use 2 " + "against the fleet-deployed cap of 6."),
+      additional_bank_min_slots: exports_external.number().int().min(0).optional().describe("Slots inside `max_memories` reserved as a FLOOR for the " + "additional (profile / shared / sender) banks. Symmetric with " + "`own_bank_min_slots` — same floor-not-quota semantics, and the " + "two share the same half-of-cap reservation budget. When they sum " + "above that budget the own-bank floor is honoured first. 0 " + "disables (default). Switchroom-managed agents use 1 against the " + "fleet-deployed cap of 6. Observe `injected_own_bank_count` / " + "`injected_additional_bank_count` via " + "`switchroom memory recall-log`."),
       types: exports_external.array(exports_external.string()).optional().describe("Hindsight fact types to recall. Switchroom default is " + '["world", "experience", "observation"] — the synthesized ' + "`observation` tier is on by default. Set to " + '["world", "experience"] to opt out of observation-backed ' + "recall for this agent (or fleet-wide under defaults)."),
       additional_banks: exports_external.array(exports_external.string()).optional().describe("Extra Hindsight banks to recall from on every turn, merged into " + "the agent's own bank results — e.g. a shared operator/household " + "profile bank authored via `switchroom memory profile`. Each is " + "recalled with an 8s timeout and is non-fatal on failure. Stays " + "within the single tenant: all banks are the operator's data, in " + "the operator's Hindsight instance (see the `single-tenant` " + "invariant). Defaults to [] (no extra banks)."),
       sender_banks: exports_external.record(exports_external.string(), exports_external.string()).optional().describe("Per-speaker recall routing: a map of Telegram sender → extra " + "recall bank. When a message arrives, the agent also recalls the " + "speaker's bank (matched by Telegram username — a leading @ is " + "optional — or numeric user_id), merged " + "into its own results — so each trusted user gets their own " + "profile context. Additive recall scoping within the single " + "tenant: never an access boundary (who may drive an agent stays " + "the per-agent user assignment in `access.allowFrom`). Author the " + "banks via `switchroom memory profile`."),
@@ -4389,7 +4393,7 @@ var init_schema = __esm(() => {
       reflect: HindsightPerOpLlmSchema.optional().describe("Per-op override for the `reflect` LLM op (synthesis / mental-model " + "refresh). Emits `HINDSIGHT_API_REFLECT_LLM_*`. Absent → uses global."),
       consolidation: HindsightPerOpLlmSchema.optional().describe("Per-op override for the `consolidation` LLM op (background memory " + "merge). Emits `HINDSIGHT_API_CONSOLIDATION_LLM_*`. Absent → global.")
     }).optional().describe("LLM knob for the hindsight container. The flat `provider`/`model` set " + "the global default (backward-compatible); optional `retain`/`reflect`/" + "`consolidation` blocks override individual ops. All fields optional; " + "unset fields fall back to the hard-coded defaults."),
-    env: exports_external.record(exports_external.union([exports_external.string(), exports_external.number(), exports_external.boolean()])).optional().describe("Operator overrides for switchroom's capability-gated Hindsight " + "performance defaults. Only the keys switchroom actually manages are " + "honoured (`HINDSIGHT_PERF_ENV_KEYS` in " + "src/setup/hindsight-perf-defaults.ts: RERANKER_LOCAL_FP16, " + "RERANKER_LOCAL_BATCH_SIZE, LLM_MAX_CONCURRENT, " + "RETAIN/CONSOLIDATION_LLM_MAX_CONCURRENT, LLM_STRICT_SCHEMA, " + "LLM_MAX_RETRIES, CONSOLIDATION_LLM_PARALLELISM, " + "RECALL_MAX_CANDIDATES_PER_SOURCE, LINK_EXPANSION_PER_ENTITY_LIMIT, " + "LINK_EXPANSION_TIMEOUT, LLM_REASONING_EFFORT), the override-only keys " + "switchroom manages but ships NO default for " + "(`HINDSIGHT_PERF_OVERRIDE_ONLY_KEYS`: " + "HINDSIGHT_API_WORKER_CONSOLIDATION_BANK_PRIORITY — a per-deployment " + "`bank-pattern:priority,...` map; unset means upstream's flat " + "created_at FIFO across banks), plus the " + "embedded-PostgreSQL (pg0) sizing keys switchroom manages in " + "src/setup/hindsight-pg-defaults.ts (`HINDSIGHT_PG_ENV_KEYS`: " + "SWITCHROOM_HINDSIGHT_PG_EFFECTIVE_CACHE_SIZE, " + "SWITCHROOM_HINDSIGHT_PG_SHARED_BUFFERS — a postgres size string such " + "as `4GB`, or the sentinel `off` to leave pg0's own default for that " + "one knob). A value set here " + "REPLACES switchroom's default and is emitted even when the gating " + "capability is absent, so an operator can always force a knob. Other " + "`HINDSIGHT_API_*` keys are deliberately IGNORED — a blanket " + "passthrough would collide with the vars startHindsight() derives " + "itself (HINDSIGHT_API_PORT, the retain token/deadline budget).")
+    env: exports_external.record(exports_external.union([exports_external.string(), exports_external.number(), exports_external.boolean()])).optional().describe("Operator overrides for switchroom's capability-gated Hindsight " + "performance defaults. Only the keys switchroom actually manages are " + "honoured (`HINDSIGHT_PERF_ENV_KEYS` in " + "src/setup/hindsight-perf-defaults.ts: RERANKER_LOCAL_FP16, " + "RERANKER_LOCAL_BATCH_SIZE, LLM_MAX_CONCURRENT, " + "RETAIN/CONSOLIDATION_LLM_MAX_CONCURRENT, LLM_STRICT_SCHEMA, " + "LLM_MAX_RETRIES, CONSOLIDATION_LLM_PARALLELISM, " + "MAX_OBSERVATIONS_PER_SCOPE, " + "RECALL_MAX_CANDIDATES_PER_SOURCE, LINK_EXPANSION_PER_ENTITY_LIMIT, " + "LINK_EXPANSION_TIMEOUT, LLM_REASONING_EFFORT, " + "RERANKER_LOCAL_BUCKET_BATCHING, RERANKER_MAX_CANDIDATES, " + "RERANKER_LOCAL_MAX_CONCURRENT, RECALL_MAX_CONCURRENT, " + "REFLECT_WALL_TIMEOUT, WORKER_CONSOLIDATION_MAX_SLOTS, " + "WORKER_CONSOLIDATION_SLOT_LIMIT, " + "CONSOLIDATION_MAX_MEMORIES_PER_ROUND), the override-only keys " + "switchroom manages but ships NO default for " + "(`HINDSIGHT_PERF_OVERRIDE_ONLY_KEYS`: " + "HINDSIGHT_API_WORKER_CONSOLIDATION_BANK_PRIORITY — a per-deployment " + "`bank-pattern:priority,...` map; unset means upstream's flat " + "created_at FIFO across banks; and " + "HINDSIGHT_CE_DECISIVE_RELATIVE_GAP — the rollback knob for " + "switchroom's CE-saturation damping patch, a float; >= ~0.65 backs the " + "damping out entirely, unset means the patch's own derived gap), plus the " + "embedded-PostgreSQL (pg0) sizing keys switchroom manages in " + "src/setup/hindsight-pg-defaults.ts (`HINDSIGHT_PG_ENV_KEYS`: " + "SWITCHROOM_HINDSIGHT_PG_EFFECTIVE_CACHE_SIZE, " + "SWITCHROOM_HINDSIGHT_PG_SHARED_BUFFERS — a postgres size string such " + "as `4GB`, or the sentinel `off` to leave pg0's own default for that " + "one knob). A value set here " + "REPLACES switchroom's default and is emitted even when the gating " + "capability is absent, so an operator can always force a knob. Other " + "`HINDSIGHT_API_*` keys are deliberately IGNORED — a blanket " + "passthrough would collide with the vars startHindsight() derives " + "itself (HINDSIGHT_API_PORT, the retain token/deadline budget).")
   });
   MicrosoftWorkspaceConfigSchema = exports_external.object({
     microsoft_client_id: exports_external.string().min(1).optional().describe("Microsoft OAuth application (client) ID from Entra portal " + "(literal string or vault reference e.g. " + "'vault:microsoft-oauth-client-id'). OPTIONAL — omit it to use " + "switchroom's shipped default Microsoft app (zero-config). " + "Set it only to bring your own Entra app (BYO)."),
@@ -4525,7 +4529,11 @@ var init_schema = __esm(() => {
       recall: exports_external.object({
         max_memories: exports_external.number().int().min(0).optional(),
         cache_ttl_secs: exports_external.number().int().min(0).optional(),
-        min_overlap: exports_external.number().min(0).max(1).optional(),
+        query_max_tokens: exports_external.number().int().min(0).optional(),
+        query_stop_terms: exports_external.array(exports_external.string().min(1).regex(/^[\w./-]+$/)).optional(),
+        request_timeout_seconds: exports_external.number().int().min(1).optional(),
+        own_bank_min_slots: exports_external.number().int().min(0).optional(),
+        additional_bank_min_slots: exports_external.number().int().min(0).optional(),
         additional_banks: exports_external.array(exports_external.string()).optional(),
         sender_banks: exports_external.record(exports_external.string(), exports_external.string()).optional()
       }).optional()
@@ -4559,7 +4567,8 @@ var init_schema = __esm(() => {
       memory: exports_external.string().regex(/^\d+(\.\d+)?[kmgKMG]?$/, "memory must be a Docker size string like '6g', '512m', '1.5g'").optional().describe("Hard memory cap (Docker `mem_limit` → cgroup memory.max). When the " + "container exceeds this, the kernel OOM-kills processes in the cgroup. " + "Format: '6g', '1.5g', '512m'. When unset at every cascade layer the " + "compose generator falls back to the hard-coded per-profile defaults " + "in src/agents/compose.ts (klanker 6g, coding 2g, conversational 1.5g, " + "lightweight 1g, default 1.5g)."),
       memory_reservation: exports_external.string().regex(/^\d+(\.\d+)?[kmgKMG]?$/, "memory_reservation must be a Docker size string like '4g', '256m'").optional().describe("Soft memory floor (Docker `mem_reservation` → cgroup memory.low). " + "Under host-wide memory pressure, the kernel protects at least this " + "much from being reclaimed from the cgroup. Must be ≤ memory. Use to " + "keep an agent RAM-resident when the host has other tenants that " + "might push the box (Coolify apps, build jobs). Default: unset."),
       pids_limit: exports_external.number().int().positive().optional().describe("Max processes the cgroup can spawn (cgroup pids.max). Prevents " + "fork bombs and runaway test runners. Counts every process in the " + "cgroup including bash subprocesses, claude itself, sidecars, and " + "any test/build worker. A typical agent at idle uses ~30 PIDs; " + "`npm test`-style workloads can spike to 200+. Set generously " + "(2000 is a comfortable cap for test-running agents). Default: " + "unset (no cgroup pid cap)."),
-      cpus: exports_external.number().positive().optional().describe("CPU quota (Docker `cpus`). Fractional values OK (e.g. 0.5, 2.0). " + "When unset at every cascade layer the compose generator falls " + "back to the per-profile default (klanker/coding 2.0, default 1.0, " + "lightweight 0.5).")
+      cpus: exports_external.number().positive().optional().describe("CPU quota (Docker `cpus`). Fractional values OK (e.g. 0.5, 2.0). " + "When unset at every cascade layer the compose generator falls " + "back to the per-profile default (klanker/coding 2.0, default 1.0, " + "lightweight 0.5)."),
+      tmp_size: exports_external.string().regex(/^\d+(\.\d+)?[kmgKMG]?$/, "tmp_size must be a Docker size string like '1g', '4g', '512m'").refine((v) => parseFloat(v) > 0, "tmp_size must be greater than zero").optional().describe("Size of the agent container's RAM-backed `/tmp` (Docker " + "`tmpfs: - /tmp:size=<this>,mode=1777`). The container root FS is " + "read-only, so /tmp is the only scratch space the agent and its " + "sub-agents get for repo clones and toolchain caches (bunx/npx/pip) " + "— a fan-out of several sub-agents exhausts the 1g default. A tmpfs " + "only consumes host RAM for the pages actually written, so raising " + "the ceiling costs nothing until it is used; those pages are still " + "charged to the container's `memory` cap, so raise both together. " + "Format: '1g', '4g', '512m'. Default when unset at every cascade " + "layer: '1g'.")
     }).optional().describe("Per-agent resource limits. Cascades through defaults → profile → " + "per-agent with per-field merge (agent wins on each field independently). " + "Any field left unset at every layer falls back to the hard-coded " + "per-profile defaults in src/agents/compose.ts."),
     experimental: exports_external.object({
       legacy_pty: exports_external.boolean().optional().describe("Opt out of the default tmux supervisor (#725) and run the agent under " + "the legacy PTY supervisor instead. Default: false (tmux is the default)."),
@@ -4652,7 +4661,8 @@ var init_schema = __esm(() => {
       memory: exports_external.string().regex(/^\d+(\.\d+)?[kmgKMG]?$/).optional(),
       memory_reservation: exports_external.string().regex(/^\d+(\.\d+)?[kmgKMG]?$/).optional(),
       pids_limit: exports_external.number().int().positive().optional(),
-      cpus: exports_external.number().positive().optional()
+      cpus: exports_external.number().positive().optional(),
+      tmp_size: exports_external.string().regex(/^\d+(\.\d+)?[kmgKMG]?$/, "tmp_size must be a Docker size string like '1g', '4g', '512m'").refine((v) => parseFloat(v) > 0, "tmp_size must be greater than zero").optional()
     }).optional()
   }).superRefine((agent, ctx) => {
     if (agent.dm_only !== true)
@@ -18225,7 +18235,7 @@ var require_lib = __commonJS((exports, module) => {
 
 // src/vault/broker/server.ts
 import * as net from "node:net";
-import { mkdirSync as mkdirSync7, chmodSync as chmodSync5, chownSync, existsSync as existsSync12, readFileSync as readFileSync10, readdirSync as readdirSync5, statSync as statSync7, unlinkSync as unlinkSync6, writeFileSync as writeFileSync3, renameSync as renameSync8 } from "node:fs";
+import { mkdirSync as mkdirSync8, chmodSync as chmodSync5, chownSync as chownSync2, existsSync as existsSync12, readFileSync as readFileSync12, readdirSync as readdirSync5, statSync as statSync7, unlinkSync as unlinkSync6, writeFileSync as writeFileSync5 } from "node:fs";
 
 // src/agents/compose.ts
 init_schema();
@@ -18867,6 +18877,27 @@ function assertPositive(value, label) {
 // src/setup/host-capabilities.ts
 init_paths();
 
+// src/setup/hindsight-pg-defaults.ts
+var HINDSIGHT_PG_MEM_LIMIT_MIB_FOR_DERIVATION = 8 * 1024;
+var HINDSIGHT_PG_APP_ANON_MIB = 2560;
+var HINDSIGHT_PG_PAGE_CACHE_FLOOR_MIB = 2048;
+var HINDSIGHT_PG_SHARED_BUFFERS_BUDGET_MIB = HINDSIGHT_PG_MEM_LIMIT_MIB_FOR_DERIVATION - HINDSIGHT_PG_APP_ANON_MIB - HINDSIGHT_PG_PAGE_CACHE_FLOOR_MIB;
+var HINDSIGHT_PG_DEFAULT_SHARED_BUFFERS_MIB = 1536;
+var HINDSIGHT_PG_DEFAULT_EFFECTIVE_CACHE_SIZE_MIB = 4096;
+function pgMib(mib) {
+  return `${mib}MB`;
+}
+var HINDSIGHT_PG_EFFECTIVE_CACHE_SIZE_ENV = "SWITCHROOM_HINDSIGHT_PG_EFFECTIVE_CACHE_SIZE";
+var HINDSIGHT_PG_SHARED_BUFFERS_ENV = "SWITCHROOM_HINDSIGHT_PG_SHARED_BUFFERS";
+var HINDSIGHT_PG_DEFAULTS = [
+  [
+    HINDSIGHT_PG_EFFECTIVE_CACHE_SIZE_ENV,
+    pgMib(HINDSIGHT_PG_DEFAULT_EFFECTIVE_CACHE_SIZE_MIB)
+  ],
+  [HINDSIGHT_PG_SHARED_BUFFERS_ENV, pgMib(HINDSIGHT_PG_DEFAULT_SHARED_BUFFERS_MIB)]
+];
+var HINDSIGHT_PG_ENV_KEYS = new Set(HINDSIGHT_PG_DEFAULTS.map(([k]) => k));
+
 // src/setup/hindsight-perf-defaults.ts
 var HINDSIGHT_RERANKER_MAX_CANDIDATES_FOR_DERIVATION = 150;
 var HINDSIGHT_DEFAULT_RECALL_MAX_CANDIDATES_PER_SOURCE = Math.ceil(HINDSIGHT_RERANKER_MAX_CANDIDATES_FOR_DERIVATION * 0.4);
@@ -18881,6 +18912,15 @@ var HINDSIGHT_DEFAULT_RERANKER_LOCAL_BATCH_SIZE = 128;
 var HINDSIGHT_DEFAULT_LLM_STRICT_SCHEMA = "true";
 var HINDSIGHT_DEFAULT_LLM_MAX_RETRIES = 2;
 var HINDSIGHT_DEFAULT_CONSOLIDATION_LLM_PARALLELISM = 2;
+var HINDSIGHT_DEFAULT_MAX_OBSERVATIONS_PER_SCOPE = 1000;
+var HINDSIGHT_DEFAULT_RERANKER_BUCKET_BATCHING = "true";
+var HINDSIGHT_DEFAULT_RERANKER_MAX_CANDIDATES = 150;
+var HINDSIGHT_DEFAULT_RERANKER_LOCAL_MAX_CONCURRENT = 4;
+var HINDSIGHT_DEFAULT_RECALL_MAX_CONCURRENT = 8;
+var HINDSIGHT_DEFAULT_REFLECT_WALL_TIMEOUT_S = 600;
+var HINDSIGHT_DEFAULT_CONSOLIDATION_MAX_MEMORIES_PER_ROUND = 500;
+var HINDSIGHT_DEFAULT_CONSOLIDATION_SLOT_LIMIT = 6;
+var HINDSIGHT_DEFAULT_CONSOLIDATION_MAX_SLOTS = 1;
 var HINDSIGHT_PERF_DEFAULTS_UNGATED = [
   [
     "HINDSIGHT_API_RECALL_MAX_CANDIDATES_PER_SOURCE",
@@ -18898,6 +18938,42 @@ var HINDSIGHT_PERF_DEFAULTS_UNGATED = [
   [
     "HINDSIGHT_API_CONSOLIDATION_LLM_PARALLELISM",
     String(HINDSIGHT_DEFAULT_CONSOLIDATION_LLM_PARALLELISM)
+  ],
+  [
+    "HINDSIGHT_API_MAX_OBSERVATIONS_PER_SCOPE",
+    String(HINDSIGHT_DEFAULT_MAX_OBSERVATIONS_PER_SCOPE)
+  ],
+  [
+    "HINDSIGHT_API_RERANKER_LOCAL_BUCKET_BATCHING",
+    HINDSIGHT_DEFAULT_RERANKER_BUCKET_BATCHING
+  ],
+  [
+    "HINDSIGHT_API_RERANKER_MAX_CANDIDATES",
+    String(HINDSIGHT_DEFAULT_RERANKER_MAX_CANDIDATES)
+  ],
+  [
+    "HINDSIGHT_API_RERANKER_LOCAL_MAX_CONCURRENT",
+    String(HINDSIGHT_DEFAULT_RERANKER_LOCAL_MAX_CONCURRENT)
+  ],
+  [
+    "HINDSIGHT_API_RECALL_MAX_CONCURRENT",
+    String(HINDSIGHT_DEFAULT_RECALL_MAX_CONCURRENT)
+  ],
+  [
+    "HINDSIGHT_API_REFLECT_WALL_TIMEOUT",
+    String(HINDSIGHT_DEFAULT_REFLECT_WALL_TIMEOUT_S)
+  ],
+  [
+    "HINDSIGHT_API_WORKER_CONSOLIDATION_MAX_SLOTS",
+    String(HINDSIGHT_DEFAULT_CONSOLIDATION_MAX_SLOTS)
+  ],
+  [
+    "HINDSIGHT_API_WORKER_CONSOLIDATION_SLOT_LIMIT",
+    String(HINDSIGHT_DEFAULT_CONSOLIDATION_SLOT_LIMIT)
+  ],
+  [
+    "HINDSIGHT_API_CONSOLIDATION_MAX_MEMORIES_PER_ROUND",
+    String(HINDSIGHT_DEFAULT_CONSOLIDATION_MAX_MEMORIES_PER_ROUND)
   ]
 ];
 var HINDSIGHT_PERF_DEFAULTS_GPU = [
@@ -18921,7 +18997,8 @@ var HINDSIGHT_PERF_DEFAULTS_LOCAL_LLM = [
   ["HINDSIGHT_API_LLM_MAX_RETRIES", String(HINDSIGHT_DEFAULT_LLM_MAX_RETRIES)]
 ];
 var HINDSIGHT_PERF_OVERRIDE_ONLY_KEYS = new Set([
-  "HINDSIGHT_API_WORKER_CONSOLIDATION_BANK_PRIORITY"
+  "HINDSIGHT_API_WORKER_CONSOLIDATION_BANK_PRIORITY",
+  "HINDSIGHT_CE_DECISIVE_RELATIVE_GAP"
 ]);
 var HINDSIGHT_PERF_ENV_KEYS = new Set([
   ...[
@@ -18932,27 +19009,6 @@ var HINDSIGHT_PERF_ENV_KEYS = new Set([
   ...HINDSIGHT_PERF_OVERRIDE_ONLY_KEYS
 ]);
 
-// src/setup/hindsight-pg-defaults.ts
-var HINDSIGHT_PG_MEM_LIMIT_MIB_FOR_DERIVATION = 8 * 1024;
-var HINDSIGHT_PG_APP_ANON_MIB = 2560;
-var HINDSIGHT_PG_PAGE_CACHE_FLOOR_MIB = 2048;
-var HINDSIGHT_PG_SHARED_BUFFERS_BUDGET_MIB = HINDSIGHT_PG_MEM_LIMIT_MIB_FOR_DERIVATION - HINDSIGHT_PG_APP_ANON_MIB - HINDSIGHT_PG_PAGE_CACHE_FLOOR_MIB;
-var HINDSIGHT_PG_DEFAULT_SHARED_BUFFERS_MIB = 1536;
-var HINDSIGHT_PG_DEFAULT_EFFECTIVE_CACHE_SIZE_MIB = 4096;
-function pgMib(mib) {
-  return `${mib}MB`;
-}
-var HINDSIGHT_PG_EFFECTIVE_CACHE_SIZE_ENV = "SWITCHROOM_HINDSIGHT_PG_EFFECTIVE_CACHE_SIZE";
-var HINDSIGHT_PG_SHARED_BUFFERS_ENV = "SWITCHROOM_HINDSIGHT_PG_SHARED_BUFFERS";
-var HINDSIGHT_PG_DEFAULTS = [
-  [
-    HINDSIGHT_PG_EFFECTIVE_CACHE_SIZE_ENV,
-    pgMib(HINDSIGHT_PG_DEFAULT_EFFECTIVE_CACHE_SIZE_MIB)
-  ],
-  [HINDSIGHT_PG_SHARED_BUFFERS_ENV, pgMib(HINDSIGHT_PG_DEFAULT_SHARED_BUFFERS_MIB)]
-];
-var HINDSIGHT_PG_ENV_KEYS = new Set(HINDSIGHT_PG_DEFAULTS.map(([k]) => k));
-
 // src/setup/hindsight-context-budget.ts
 var HINDSIGHT_UPSTREAM_RETAIN_CHUNK_SIZE = 3000;
 var HINDSIGHT_RETAIN_MAX_COMPLETION_FLOOR = HINDSIGHT_UPSTREAM_RETAIN_CHUNK_SIZE + 72;
@@ -19892,6 +19948,73 @@ function migrateLegacyGrantsDbLocation(newDbPath = getGrantsDbPath(), deps) {
 // src/agents/compose.ts
 var BIND_MOUNT_EXACT_SOURCE_DENY = new Set(["/var/run/docker.sock"]);
 
+// src/vault/broker/write-token-file.ts
+import { chownSync, mkdirSync as mkdirSync4, readFileSync as readFileSync7, writeFileSync as writeFileSync2 } from "node:fs";
+import { join as join6 } from "node:path";
+class TokenFileWriteError extends Error {
+  tokenPath;
+  constructor(tokenPath, message, options) {
+    super(message, options);
+    this.name = "TokenFileWriteError";
+    this.tokenPath = tokenPath;
+  }
+}
+function writeAgentTokenFile(args, deps = {}) {
+  const { agentsDir, agent, token } = args;
+  const mkdir = deps.mkdir ?? ((p) => {
+    mkdirSync4(p, { recursive: true });
+  });
+  const writeFile = deps.writeFile ?? ((p, d) => {
+    writeFileSync2(p, d, { mode: 384 });
+  });
+  const readFile = deps.readFile ?? ((p) => readFileSync7(p, "utf8"));
+  const chown = deps.chown ?? ((p, uid, gid) => {
+    chownSync(p, uid, gid);
+  });
+  const agentUid = deps.agentUid ?? allocateAgentUid;
+  const tokenDir = join6(agentsDir, agent);
+  const tokenPath = join6(tokenDir, ".vault-token");
+  try {
+    mkdir(tokenDir);
+  } catch (err) {
+    throw new TokenFileWriteError(tokenPath, `cannot create agent token dir ${tokenDir}: ${errText(err)}`, { cause: err });
+  }
+  let preExisting;
+  try {
+    readFile(tokenPath);
+    preExisting = true;
+  } catch {
+    preExisting = false;
+  }
+  try {
+    writeFile(tokenPath, token);
+  } catch (err) {
+    throw new TokenFileWriteError(tokenPath, `cannot write token file ${tokenPath}: ${errText(err)}`, { cause: err });
+  }
+  let onDisk;
+  try {
+    onDisk = readFile(tokenPath);
+  } catch (err) {
+    throw new TokenFileWriteError(tokenPath, `token file ${tokenPath} is unreadable after write: ${errText(err)}`, { cause: err });
+  }
+  if (onDisk !== token) {
+    throw new TokenFileWriteError(tokenPath, `token file ${tokenPath} did not verify after write ` + `(${onDisk.length} bytes on disk, ${token.length} expected)`);
+  }
+  let chownWarning = null;
+  if (!preExisting) {
+    try {
+      const uid = agentUid(agent);
+      chown(tokenPath, uid, uid);
+    } catch (err) {
+      chownWarning = `token file ${tokenPath} created but chown to the agent UID failed: ` + `${errText(err)} (CAP_CHOWN missing?)`;
+    }
+  }
+  return { tokenPath, chownWarning };
+}
+function errText(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
 // src/vault/broker/server.ts
 import { dirname as dirname7, resolve as resolve9, basename as basename5 } from "node:path";
 import * as os3 from "node:os";
@@ -19904,23 +20027,23 @@ import {
   existsSync as existsSync8,
   fsyncSync as fsyncSync4,
   lstatSync as lstatSync2,
-  mkdirSync as mkdirSync4,
+  mkdirSync as mkdirSync5,
   openSync as openSync4,
   closeSync as closeSync4,
-  readFileSync as readFileSync7,
+  readFileSync as readFileSync8,
   renameSync as renameSync4,
   statSync as statSync4,
   symlinkSync,
   unlinkSync as unlinkSync3
 } from "node:fs";
 import { createHash as createHash2 } from "node:crypto";
-import { basename as basename3, dirname as dirname4, join as join6 } from "node:path";
+import { basename as basename3, dirname as dirname4, join as join7 } from "node:path";
 function vaultLayoutPaths(home2) {
-  const switchroomRoot = join6(home2, ".switchroom");
+  const switchroomRoot = join7(home2, ".switchroom");
   return {
-    oldPath: join6(switchroomRoot, "vault.enc"),
-    newPath: join6(switchroomRoot, "vault", "vault.enc"),
-    parent: join6(switchroomRoot, "vault"),
+    oldPath: join7(switchroomRoot, "vault.enc"),
+    newPath: join7(switchroomRoot, "vault", "vault.enc"),
+    parent: join7(switchroomRoot, "vault"),
     switchroomRoot
   };
 }
@@ -19969,7 +20092,7 @@ function runMigration(home2, opts) {
     if (oldStat?.isFile() && !newExists) {
       if (opts.dryRun)
         return { kind: "migrated" };
-      mkdirSync4(parent, { recursive: true, mode: 448 });
+      mkdirSync5(parent, { recursive: true, mode: 448 });
       const tempNew = `${newPath}.tmp`;
       copyFileSync2(oldPath, tempNew);
       chmodSync2(tempNew, 384);
@@ -19997,11 +20120,11 @@ function lstatSyncOrNull(path2) {
   }
 }
 function sha256File(path2) {
-  const data = readFileSync7(path2);
+  const data = readFileSync8(path2);
   return createHash2("sha256").update(data).digest("hex");
 }
 function atomicReplaceWithSymlink(target, linkTarget) {
-  const tmp = join6(dirname4(target), `.${basename3(target)}.symlink-tmp`);
+  const tmp = join7(dirname4(target), `.${basename3(target)}.symlink-tmp`);
   if (existsSync8(tmp)) {
     try {
       unlinkSync3(tmp);
@@ -20037,9 +20160,9 @@ import {
   closeSync as closeSync5,
   existsSync as existsSync9,
   fsyncSync as fsyncSync5,
-  mkdirSync as mkdirSync5,
+  mkdirSync as mkdirSync6,
   openSync as openSync5,
-  readFileSync as readFileSync8,
+  readFileSync as readFileSync9,
   renameSync as renameSync5,
   unlinkSync as unlinkSync4,
   writeSync as writeSync4
@@ -20078,7 +20201,7 @@ function readMachineId() {
   }
   for (const path2 of [MACHINE_ID_PRIMARY, MACHINE_ID_FALLBACK]) {
     try {
-      const id = readFileSync8(path2, "utf8").trim();
+      const id = readFileSync9(path2, "utf8").trim();
       if (id.length > 0)
         return id;
     } catch {}
@@ -20120,7 +20243,7 @@ function readAutoUnlockFile(filePath) {
   }
   let blob;
   try {
-    blob = readFileSync8(filePath);
+    blob = readFileSync9(filePath);
   } catch {
     throw new AutoUnlockDecryptError("io");
   }
@@ -20201,7 +20324,7 @@ function seedChain(path2) {
 // src/vault/broker/test-isolation-guard.ts
 import { mkdtempSync } from "node:fs";
 import { homedir as homedir5, tmpdir } from "node:os";
-import { join as join7, resolve as resolve8, sep } from "node:path";
+import { join as join8, resolve as resolve8, sep } from "node:path";
 function isTestRuntime() {
   return process.env.VITEST !== undefined;
 }
@@ -20222,7 +20345,7 @@ function safeVaultPath(requestedPath) {
     return requestedPath;
   if (!isUnderRealSwitchroomHome(requestedPath))
     return requestedPath;
-  const redirected = join7(mkdtempSync(join7(tmpdir(), "sw-test-vault-")), "vault.enc");
+  const redirected = join8(mkdtempSync(join8(tmpdir(), "sw-test-vault-")), "vault.enc");
   if (!warnedVault) {
     warnedVault = true;
     process.stderr.write(`[test-isolation guard] vault path redirected away from the ` + `production tree to an isolated tmpdir — a vault/broker test ` + `resolved its vault path inside ~/.switchroom. See CLAUDE.md ` + `"Vault & shared-state test discipline".
@@ -20238,7 +20361,7 @@ function safeAuditLogPath(requestedPath) {
   if (!isUnderRealSwitchroomHome(requestedPath))
     return requestedPath;
   if (!cachedTmpAuditLog) {
-    cachedTmpAuditLog = join7(mkdtempSync(join7(tmpdir(), "sw-test-audit-")), "vault-audit.log");
+    cachedTmpAuditLog = join8(mkdtempSync(join8(tmpdir(), "sw-test-audit-")), "vault-audit.log");
   }
   if (!warnedAudit) {
     warnedAudit = true;
@@ -22384,6 +22507,37 @@ function listGrants(db, agent_slug) {
   return rows.map(rowToGrant);
 }
 
+// src/vault/broker/reap-token-file.ts
+import { readFileSync as readFileSync11, writeFileSync as writeFileSync4 } from "node:fs";
+import { join as join11 } from "node:path";
+var REAPABLE_REASONS = new Set(["grant-invalid", "grant-expired"]);
+function reapUnusableGrantToken(args, deps = {}) {
+  const { agentsDir, agent, presentedToken, reason } = args;
+  if (!REAPABLE_REASONS.has(reason))
+    return "kept:reason-not-reapable";
+  if (!agent)
+    return "kept:no-agent-identity";
+  const readFile = deps.readFile ?? ((p) => readFileSync11(p, "utf8"));
+  const writeFile = deps.writeFile ?? ((p, d) => writeFileSync4(p, d, { mode: 384 }));
+  const tokenPath = join11(agentsDir, agent, ".vault-token");
+  let onDisk;
+  try {
+    onDisk = readFile(tokenPath);
+  } catch {
+    return "kept:nothing-on-disk";
+  }
+  if (onDisk.trim() === "")
+    return "kept:nothing-on-disk";
+  if (onDisk.trim() !== presentedToken.trim())
+    return "kept:superseded";
+  try {
+    writeFile(tokenPath, "");
+  } catch {
+    return "kept:io-error";
+  }
+  return "reaped";
+}
+
 // src/vault/admin-only-keys.ts
 function globToRegExp(pattern) {
   const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
@@ -22945,7 +23099,7 @@ class VaultBroker {
     }
     process.umask(63);
     const parentDir = dirname7(this.socketPath);
-    mkdirSync7(parentDir, { recursive: true, mode: 448 });
+    mkdirSync8(parentDir, { recursive: true, mode: 448 });
     try {
       chmodSync5(parentDir, 448);
     } catch {}
@@ -22985,7 +23139,7 @@ class VaultBroker {
       return;
     try {
       if (ready) {
-        writeFileSync3(p, "", { mode: 384 });
+        writeFileSync5(p, "", { mode: 384 });
       } else if (existsSync12(p)) {
         unlinkSync6(p);
       }
@@ -23063,7 +23217,7 @@ class VaultBroker {
         const dir = abs.slice(0, -"/sock".length);
         if (existsSync12(dir)) {
           try {
-            chownSync(dir, 0, 0);
+            chownSync2(dir, 0, 0);
           } catch {}
           try {
             chmodSync5(dir, 448);
@@ -23091,12 +23245,12 @@ class VaultBroker {
         try {
           agentUid = allocateAgentUid(agentName);
           try {
-            chownSync(abs, agentUid, agentUid);
+            chownSync2(abs, agentUid, agentUid);
           } catch {}
           if (abs.endsWith("/sock")) {
             const dir = abs.slice(0, -"/sock".length);
             try {
-              chownSync(dir, agentUid, agentUid);
+              chownSync2(dir, agentUid, agentUid);
             } catch {}
           }
         } catch {}
@@ -23123,7 +23277,7 @@ class VaultBroker {
           } catch {}
           if (agentUid !== null) {
             try {
-              chownSync(unlockAbs, agentUid, agentUid);
+              chownSync2(unlockAbs, agentUid, agentUid);
             } catch {}
           }
           this.agentServers.set(unlockAbs, { server: unlockServer, agentName });
@@ -23158,7 +23312,7 @@ class VaultBroker {
       return;
     try {
       if (existsSync12(this.vaultPath))
-        chownSync(this.vaultPath, uid, uid);
+        chownSync2(this.vaultPath, uid, uid);
     } catch {}
   }
   bindOperatorListener(socketPath, operatorUid) {
@@ -23172,7 +23326,7 @@ class VaultBroker {
       const dir = abs.slice(0, -"/sock".length);
       if (existsSync12(dir)) {
         try {
-          chownSync(dir, 0, 0);
+          chownSync2(dir, 0, 0);
         } catch {}
         try {
           chmodSync5(dir, 448);
@@ -23196,7 +23350,7 @@ class VaultBroker {
           chmodSync5(abs, 384);
         } catch {}
         try {
-          chownSync(abs, operatorUid, operatorUid);
+          chownSync2(abs, operatorUid, operatorUid);
         } catch {}
         const unlockServer = net.createServer((sock) => {
           this._handleUnlockConnection(sock, true);
@@ -23207,12 +23361,12 @@ class VaultBroker {
             chmodSync5(unlockAbs, 384);
           } catch {}
           try {
-            chownSync(unlockAbs, operatorUid, operatorUid);
+            chownSync2(unlockAbs, operatorUid, operatorUid);
           } catch {}
           if (abs.endsWith("/sock")) {
             const dir = abs.slice(0, -"/sock".length);
             try {
-              chownSync(dir, operatorUid, operatorUid);
+              chownSync2(dir, operatorUid, operatorUid);
             } catch {}
             try {
               chmodSync5(dir, 448);
@@ -23514,6 +23668,14 @@ class VaultBroker {
           socket.write(encodeResponse(errorResponse("DENIED", "grant-revoked")));
           return;
         }
+        if (!grantResult.ok) {
+          reapUnusableGrantToken({
+            agentsDir: this.config ? resolveAgentsDir(this.config) : path5.join(os3.homedir(), ".switchroom", "agents"),
+            agent: agentName,
+            presentedToken: req.token,
+            reason: grantResult.reason
+          });
+        }
       }
       if (isOperator) {
         const entry2 = this.secrets[req.key];
@@ -24104,22 +24266,39 @@ class VaultBroker {
       }
       try {
         const agentsDir = this.config ? resolveAgentsDir(this.config) : path5.join(os3.homedir(), ".switchroom", "agents");
-        const tokenDir = path5.join(agentsDir, agent);
-        mkdirSync7(tokenDir, { recursive: true });
-        const tokenPath = path5.join(tokenDir, ".vault-token");
-        const tmpPath = `${tokenPath}.tmp.${process.pid}`;
-        writeFileSync3(tmpPath, mintResult.token, { mode: 384 });
-        renameSync8(tmpPath, tokenPath);
-        try {
-          const uid = allocateAgentUid(agent);
-          chownSync(tokenPath, uid, uid);
-        } catch (chownErr) {
-          process.stderr.write(`[vault-broker] mint_grant: token written but chown failed for agent ${agent}: ${chownErr.message} (CAP_CHOWN missing?)
+        const { chownWarning } = writeAgentTokenFile({
+          agentsDir,
+          agent,
+          token: mintResult.token
+        });
+        if (chownWarning !== null) {
+          process.stderr.write(`[vault-broker] mint_grant: ${chownWarning} (agent ${agent})
 `);
         }
       } catch (err) {
-        process.stderr.write(`[vault-broker] mint_grant: failed to write token file for agent ${agent}: ${err.message}
+        const msg = err instanceof Error ? err.message : String(err);
+        let rolledBack = false;
+        let rollbackErr = null;
+        try {
+          rolledBack = revokeGrant(this.grantsDb, mintResult.id);
+        } catch (revokeError) {
+          rollbackErr = revokeError instanceof Error ? revokeError.message : String(revokeError);
+        }
+        const rollbackNote = rolledBack ? "grant rolled back (revoked)" : `GRANT ROLLBACK FAILED — revoke ${mintResult.id} manually${rollbackErr ? `: ${rollbackErr}` : ""}`;
+        process.stderr.write(`[vault-broker] mint_grant: failed to write token file for agent ${agent}: ${msg}; ${rollbackNote}
 `);
+        this.auditLogger.write({
+          ts: new Date().toISOString(),
+          op: "mint_grant",
+          caller: auditCaller,
+          pid: auditPid,
+          cgroup: auditCgroup,
+          result: `error:token-write-failed:${msg}`,
+          method: "grant",
+          grant_id: mintResult.id
+        });
+        socket.write(encodeResponse(errorResponse("INTERNAL", `Failed to write token file for agent ${agent}: ${msg} (${rollbackNote})`)));
+        return;
       }
       this.auditLogger.write({
         ts: new Date().toISOString(),
@@ -24395,7 +24574,7 @@ class VaultBroker {
   _writePidFile() {
     try {
       const pidPath = resolvePath(PID_FILE_DEFAULT);
-      writeFileSync3(pidPath, String(process.pid) + `
+      writeFileSync5(pidPath, String(process.pid) + `
 `, { mode: 384 });
     } catch {}
   }
@@ -24451,7 +24630,7 @@ class VaultBroker {
     const credPath = `${dir}/vault-passphrase`;
     let passphrase;
     try {
-      passphrase = readFileSync10(credPath, "utf8").replace(/\n+$/, "");
+      passphrase = readFileSync12(credPath, "utf8").replace(/\n+$/, "");
     } catch (err) {
       const code = err.code;
       if (code === "ENOENT") {

package/examples/switchroom.yaml

@@ -249,7 +249,7 @@ agents:
   #   topic_emoji: "💻"
   #   bot_token: "vault:telegram-dev-bot-token"     # its own bot
   #   extends: coder                      # inherits from inline profile above
-  #   model: claude-opus-4-8              # override defaults.model for this agent
+  #   model: opus                         # override defaults.model for this agent
   #   memory:
   #     collection: coding
   #   cli_args: ["--effort", "high"]      # escape hatch: extra exec claude flags

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "switchroom",
   "//version": "NOT the release version — source of truth is the git tag, resolved by scripts/build.mjs:resolveVersion() (see CLAUDE.md > Standard release process). This field is stale by design and only the Layer-4 dev/non-tag fallback for build.mjs + src/cli/resolve-version.ts; do NOT bump it expecting a release to pick it up. npm-pack tarball naming needs a real version — do that as an UNCOMMITTED pack-time bump (see release step 6), never a committed one.",
-  "version": "0.19.24",
+  "version": "0.19.25",
   "description": "Run Claude Code 24/7 on your Claude Pro/Max subscription over Telegram. Open-source alternative to OpenClaw and NanoClaw — no API keys.",
   "type": "module",
   "bin": {