switchroom 0.20.12 → 0.20.13

package/dist/cli/switchroom.js

@@ -2120,7 +2120,7 @@ var init_esm = __esm(() => {
 });
 
 // src/build-info.ts
-var VERSION = "0.20.12", COMMIT_SHA = "298e1e15";
+var VERSION = "0.20.13", COMMIT_SHA = "a73b0fd2";
 
 // src/cli/resolve-version.ts
 import { existsSync, readFileSync } from "node:fs";
@@ -14034,6 +14034,7 @@ var init_schema = __esm(() => {
   }).describe("Per-operation LLM override. Every field optional; an unset field (or " + "an omitted op block) inherits the global `hindsight.llm.*`, which is " + "already the engine's fallback \u2014 switchroom emits only the vars set.");
   HindsightConfigSchema = exports_external.object({
     gpu: exports_external.boolean().optional().describe("Force GPU passthrough for the hindsight container on (`true`) or off " + "(`false`), overriding host autodetection in BOTH directions. Absent " + "(the default) \u2192 autodetect from the persisted host-capabilities " + "verdict (`~/.switchroom/host-capabilities.json`), which enables " + "`--gpus all` only when that file proves BOTH a GPU and the nvidia " + "container toolkit. Set `true` when that verdict is wrong or unreadable " + "and you know the host has a working toolkit \u2014 switchroom cannot verify " + "it for you, and `docker run --gpus all` hard-fails container create on " + "a host without one. Set `false` to pin the container to CPU on a GPU " + "host. This is also the declarative opt-out for the recreate-time GPU " + "drop guard (`switchroom memory setup --recreate` refuses to silently " + "turn a GPU container into a CPU one). `--gpu`/`--no-gpu` on `memory " + "setup` override this for a single run."),
+    mem_limit: exports_external.string().regex(/^\d+(\.\d+)?\s*[bkmgt]?b?$/i, "hindsight.mem_limit must be a docker memory size, e.g. `24g` or `16384m`").optional().describe("Hard memory cap for the hindsight container \u2014 docker `--memory` on the " + "`memory setup` path and `mem_limit:` in the emitted compose snippet. A " + "docker size string (`24g`, `16384m`). Absent \u2192 switchroom's default " + "(`HINDSIGHT_DEFAULT_MEM_LIMIT`, 16g). This is a docker HostConfig flag, " + "not a container env var, which is why it is a first-class field here " + "rather than an `env:` key. **Move it together with " + "`env.SWITCHROOM_HINDSIGHT_PG_SHARED_BUFFERS`**: Postgres pins the " + "buffer pool as unreclaimable shared memory inside this cap, so a cap " + "that does not clear `shared_buffers` by the container's app working " + "set plus its page-cache floor puts Postgres in a near-OOM " + "configuration. switchroom warns, naming both numbers, when it does " + "not. A value below the container's memory RESERVATION (4g) is " + "rejected outright \u2014 docker will not create such a container."),
     cp_access_key: exports_external.string().min(1).optional().describe("Access key for the hindsight control-plane DASHBOARD (upstream " + "`HINDSIGHT_CP_ACCESS_KEY`, port 9999). Literal or \u2014 strongly preferred " + "\u2014 a `vault:` reference such as `vault:hindsight_cp_access_key`, read " + "through the broker at container-launch time. This is the ONLY thing " + "that arms the dashboard's login: upstream's middleware short-circuits " + "to `next()` when the var is unset, so an unset key means the dashboard " + "has no authentication at all, not weak authentication. Because of that, " + "leaving it unset is FAIL-CLOSED: switchroom pins " + "`HINDSIGHT_CP_HOSTNAME=127.0.0.1` so the loginless dashboard is " + "reachable only from the host, and warns. Set this to serve the " + "dashboard on the LAN/tailnet."),
     llm: exports_external.object({
       provider: exports_external.string().min(1).optional().describe("Hindsight LLM provider (upstream `HINDSIGHT_API_LLM_PROVIDER`). " + "Defaults to `claude-code` (subscription-honest, broker-fed OAuth). " + "Any litellm-routable provider the upstream image supports is valid. " + "Serves as the GLOBAL default for every op absent a per-op override."),
@@ -16005,6 +16006,66 @@ var init_host_capabilities = __esm(() => {
 function pgMib(mib) {
   return `${mib}MB`;
 }
+function parseDockerSizeToMib(size) {
+  const m = size.trim().match(/^(\d+(?:\.\d+)?)\s*([bkmgt])?b?$/i);
+  if (!m)
+    return null;
+  const n = Number(m[1]);
+  if (!Number.isFinite(n))
+    return null;
+  switch ((m[2] ?? "b").toLowerCase()) {
+    case "b":
+      return n / (1024 * 1024);
+    case "k":
+      return n / 1024;
+    case "m":
+      return n;
+    case "g":
+      return n * 1024;
+    case "t":
+      return n * 1024 * 1024;
+    default:
+      return null;
+  }
+}
+function parsePgSizeToMib(value) {
+  const raw = value.trim();
+  if (raw.toLowerCase() === "off")
+    return HINDSIGHT_PG0_FALLBACK_SHARED_BUFFERS_MIB;
+  const m = raw.match(/^(\d+(?:\.\d+)?)\s*(kB|MB|GB|TB)?$/i);
+  if (!m)
+    return null;
+  const n = Number(m[1]);
+  if (!Number.isFinite(n))
+    return null;
+  switch ((m[2] ?? "").toUpperCase()) {
+    case "":
+      return n * 8 / 1024;
+    case "KB":
+      return n / 1024;
+    case "MB":
+      return n;
+    case "GB":
+      return n * 1024;
+    case "TB":
+      return n * 1024 * 1024;
+    default:
+      return null;
+  }
+}
+function mib(n) {
+  return n >= 1024 && n % 1024 === 0 ? `${n / 1024} GiB` : `${Math.round(n)} MiB`;
+}
+function hindsightMemBudgetWarning(input) {
+  const capMib = parseDockerSizeToMib(input.memLimit);
+  const bufMib = parsePgSizeToMib(input.sharedBuffers);
+  if (capMib === null || bufMib === null)
+    return null;
+  const headroom = capMib - bufMib;
+  if (headroom >= HINDSIGHT_PG_MIN_NON_BUFFER_MIB)
+    return null;
+  return `hindsight: container memory cap ${input.memLimit} (${mib(capMib)}) leaves only ` + `${mib(Math.max(headroom, 0))} above shared_buffers ${input.sharedBuffers} ` + `(${mib(bufMib)}) \u2014 Postgres pins that buffer pool as unreclaimable shared ` + `memory, so the container needs at least ${mib(HINDSIGHT_PG_MIN_NON_BUFFER_MIB)} ` + `beyond it (${mib(HINDSIGHT_PG_APP_ANON_MIB)} app working set + ` + `${mib(HINDSIGHT_PG_PAGE_CACHE_FLOOR_MIB)} page-cache floor). Raise ` + `\`hindsight.mem_limit\` to at least ` + `${mib(Math.ceil((bufMib + HINDSIGHT_PG_MIN_NON_BUFFER_MIB) / 1024) * 1024)}, or lower ` + "`hindsight.env.SWITCHROOM_HINDSIGHT_PG_SHARED_BUFFERS`.";
+}
 function resolveHindsightPgOverrides(configEnv, processEnv = process.env) {
   const out = new Map;
   for (const key of HINDSIGHT_PG_ENV_KEYS) {
@@ -16034,10 +16095,11 @@ function hindsightPgEnv(overrides = new Map) {
   }
   return out;
 }
-var HINDSIGHT_PG_MEM_LIMIT_MIB_FOR_DERIVATION, HINDSIGHT_PG_APP_ANON_MIB = 2560, HINDSIGHT_PG_PAGE_CACHE_FLOOR_MIB = 2048, HINDSIGHT_PG_SHARED_BUFFERS_BUDGET_MIB, HINDSIGHT_PG_DEFAULT_SHARED_BUFFERS_MIB = 6144, HINDSIGHT_PG_DEFAULT_EFFECTIVE_CACHE_SIZE_MIB = 12288, HINDSIGHT_PG_EFFECTIVE_CACHE_SIZE_ENV = "SWITCHROOM_HINDSIGHT_PG_EFFECTIVE_CACHE_SIZE", HINDSIGHT_PG_SHARED_BUFFERS_ENV = "SWITCHROOM_HINDSIGHT_PG_SHARED_BUFFERS", HINDSIGHT_PG_FSYNC_ENV = "SWITCHROOM_HINDSIGHT_PG_FSYNC", HINDSIGHT_PG_DEFAULT_FSYNC = "on", HINDSIGHT_PG_DEFAULTS, HINDSIGHT_PG_ENV_KEYS;
+var HINDSIGHT_PG_MEM_LIMIT_MIB_FOR_DERIVATION, HINDSIGHT_PG_APP_ANON_MIB = 2560, HINDSIGHT_PG_PAGE_CACHE_FLOOR_MIB = 2048, HINDSIGHT_PG_SHARED_BUFFERS_BUDGET_MIB, HINDSIGHT_PG_DEFAULT_SHARED_BUFFERS_MIB = 6144, HINDSIGHT_PG_DEFAULT_EFFECTIVE_CACHE_SIZE_MIB = 12288, HINDSIGHT_PG0_FALLBACK_SHARED_BUFFERS_MIB = 256, HINDSIGHT_PG_MIN_NON_BUFFER_MIB, HINDSIGHT_PG_EFFECTIVE_CACHE_SIZE_ENV = "SWITCHROOM_HINDSIGHT_PG_EFFECTIVE_CACHE_SIZE", HINDSIGHT_PG_SHARED_BUFFERS_ENV = "SWITCHROOM_HINDSIGHT_PG_SHARED_BUFFERS", HINDSIGHT_PG_FSYNC_ENV = "SWITCHROOM_HINDSIGHT_PG_FSYNC", HINDSIGHT_PG_DEFAULT_FSYNC = "on", HINDSIGHT_PG_DEFAULTS, HINDSIGHT_PG_ENV_KEYS;
 var init_hindsight_pg_defaults = __esm(() => {
   HINDSIGHT_PG_MEM_LIMIT_MIB_FOR_DERIVATION = 16 * 1024;
   HINDSIGHT_PG_SHARED_BUFFERS_BUDGET_MIB = HINDSIGHT_PG_MEM_LIMIT_MIB_FOR_DERIVATION - HINDSIGHT_PG_APP_ANON_MIB - HINDSIGHT_PG_PAGE_CACHE_FLOOR_MIB;
+  HINDSIGHT_PG_MIN_NON_BUFFER_MIB = HINDSIGHT_PG_APP_ANON_MIB + HINDSIGHT_PG_PAGE_CACHE_FLOOR_MIB;
   HINDSIGHT_PG_DEFAULTS = [
     [
       HINDSIGHT_PG_EFFECTIVE_CACHE_SIZE_ENV,
@@ -16128,7 +16190,7 @@ function hindsightPerfEnv(caps, overrides = new Map) {
 function findUnmanagedHindsightEnvKeys(configEnv) {
   return Object.keys(configEnv ?? {}).filter((key) => !HINDSIGHT_PERF_ENV_KEYS.has(key) && !HINDSIGHT_PG_ENV_KEYS.has(key)).sort();
 }
-var HINDSIGHT_RERANKER_MAX_CANDIDATES_FOR_DERIVATION = 150, HINDSIGHT_DEFAULT_RECALL_MAX_CANDIDATES_PER_SOURCE, HINDSIGHT_DEFAULT_LINK_EXPANSION_PER_ENTITY_LIMIT = 50, HINDSIGHT_DEFAULT_LINK_EXPANSION_TIMEOUT_S = 2, HINDSIGHT_DEFAULT_LLM_REASONING_EFFORT = "low", HINDSIGHT_DEFAULT_LLM_MAX_CONCURRENT = 4, HINDSIGHT_DEFAULT_RETAIN_LLM_MAX_CONCURRENT = 1, HINDSIGHT_DEFAULT_CONSOLIDATION_LLM_MAX_CONCURRENT, HINDSIGHT_DEFAULT_RERANKER_LOCAL_FP16 = "true", HINDSIGHT_DEFAULT_RERANKER_LOCAL_BATCH_SIZE = 128, HINDSIGHT_DEFAULT_LLM_STRICT_SCHEMA = "true", HINDSIGHT_DEFAULT_LLM_MAX_RETRIES = 2, HINDSIGHT_DEFAULT_CONSOLIDATION_LLM_PARALLELISM = 2, HINDSIGHT_DEFAULT_MAX_OBSERVATIONS_PER_SCOPE = 1000, HINDSIGHT_DEFAULT_RERANKER_BUCKET_BATCHING = "true", HINDSIGHT_DEFAULT_RERANKER_MAX_CANDIDATES = 150, HINDSIGHT_DEFAULT_RERANKER_LOCAL_MAX_CONCURRENT = 4, HINDSIGHT_DEFAULT_RECALL_MAX_CONCURRENT = 8, HINDSIGHT_DEFAULT_REFLECT_WALL_TIMEOUT_S = 600, HINDSIGHT_DEFAULT_CONSOLIDATION_MAX_MEMORIES_PER_ROUND = 250, HINDSIGHT_DEFAULT_CONSOLIDATION_SLOT_LIMIT = 6, HINDSIGHT_DEFAULT_CONSOLIDATION_RESERVED_SLOTS = 1, HINDSIGHT_DEFAULT_GRAPH_SEED_MIN_SIMILARITY = 0.3, HINDSIGHT_DEFAULT_LLM_SUPPORTS_MAX_ITEMS = "false", HINDSIGHT_DEFAULT_RECENCY_DECAY_FUNCTION = "exponential", HINDSIGHT_DEFAULT_RECENCY_DECAY_HALFLIFE_DAYS = 30, HINDSIGHT_PERF_DEFAULTS_UNGATED, HINDSIGHT_PERF_DEFAULTS_GPU, HINDSIGHT_PERF_DEFAULTS_LOCAL_LLM, HINDSIGHT_PERF_OVERRIDE_ONLY_KEYS, HINDSIGHT_WORKER_SLOT_TYPES, HINDSIGHT_WORKER_RESERVED_SLOT_ALIASES, HINDSIGHT_PERF_ENV_KEYS;
+var HINDSIGHT_RERANKER_MAX_CANDIDATES_FOR_DERIVATION = 150, HINDSIGHT_DEFAULT_RECALL_MAX_CANDIDATES_PER_SOURCE, HINDSIGHT_DEFAULT_LINK_EXPANSION_PER_ENTITY_LIMIT = 50, HINDSIGHT_DEFAULT_LINK_EXPANSION_TIMEOUT_S = 2, HINDSIGHT_DEFAULT_LLM_REASONING_EFFORT = "low", HINDSIGHT_DEFAULT_LLM_MAX_CONCURRENT = 4, HINDSIGHT_DEFAULT_RETAIN_LLM_MAX_CONCURRENT = 1, HINDSIGHT_DEFAULT_CONSOLIDATION_LLM_MAX_CONCURRENT, HINDSIGHT_DEFAULT_RERANKER_LOCAL_FP16 = "true", HINDSIGHT_DEFAULT_RERANKER_LOCAL_BATCH_SIZE = 128, HINDSIGHT_DEFAULT_LLM_STRICT_SCHEMA = "true", HINDSIGHT_DEFAULT_LLM_MAX_RETRIES = 2, HINDSIGHT_DEFAULT_CONSOLIDATION_LLM_PARALLELISM = 2, HINDSIGHT_DEFAULT_MAX_OBSERVATIONS_PER_SCOPE = 1000, HINDSIGHT_DEFAULT_RERANKER_BUCKET_BATCHING = "true", HINDSIGHT_DEFAULT_RERANKER_MAX_CANDIDATES = 150, HINDSIGHT_DEFAULT_RERANKER_LOCAL_MAX_CONCURRENT = 4, HINDSIGHT_DEFAULT_RECALL_MAX_CONCURRENT = 8, HINDSIGHT_DEFAULT_REFLECT_WALL_TIMEOUT_S = 600, HINDSIGHT_DEFAULT_CONSOLIDATION_MAX_MEMORIES_PER_ROUND = 250, HINDSIGHT_DEFAULT_CONSOLIDATION_SLOT_LIMIT = 6, HINDSIGHT_DEFAULT_CONSOLIDATION_RESERVED_SLOTS = 1, HINDSIGHT_DEFAULT_GRAPH_SEED_MIN_SIMILARITY = 0.3, HINDSIGHT_DEFAULT_LLM_SUPPORTS_MAX_ITEMS = "false", HINDSIGHT_DEFAULT_RECENCY_DECAY_FUNCTION = "exponential", HINDSIGHT_DEFAULT_RECENCY_DECAY_HALFLIFE_DAYS = 30, HINDSIGHT_DEFAULT_TEXT_SEARCH_EXTENSION = "pg_search", HINDSIGHT_PERF_DEFAULTS_UNGATED, HINDSIGHT_PERF_DEFAULTS_GPU, HINDSIGHT_PERF_DEFAULTS_LOCAL_LLM, HINDSIGHT_PERF_OVERRIDE_ONLY_KEYS, HINDSIGHT_WORKER_SLOT_TYPES, HINDSIGHT_WORKER_RESERVED_SLOT_ALIASES, HINDSIGHT_PERF_ENV_KEYS;
 var init_hindsight_perf_defaults = __esm(() => {
   init_hindsight_pg_defaults();
   HINDSIGHT_DEFAULT_RECALL_MAX_CANDIDATES_PER_SOURCE = Math.ceil(HINDSIGHT_RERANKER_MAX_CANDIDATES_FOR_DERIVATION * 0.4);
@@ -16198,7 +16260,8 @@ var init_hindsight_perf_defaults = __esm(() => {
     [
       "HINDSIGHT_API_GRAPH_SEED_MIN_SIMILARITY",
       String(HINDSIGHT_DEFAULT_GRAPH_SEED_MIN_SIMILARITY)
-    ]
+    ],
+    ["HINDSIGHT_API_TEXT_SEARCH_EXTENSION", HINDSIGHT_DEFAULT_TEXT_SEARCH_EXTENSION]
   ];
   HINDSIGHT_PERF_DEFAULTS_GPU = [
     ["HINDSIGHT_API_RERANKER_LOCAL_FP16", HINDSIGHT_DEFAULT_RERANKER_LOCAL_FP16],
@@ -18733,17 +18796,20 @@ function hindsightCpAuthEnvPairs(opts) {
   return pairs;
 }
 async function resolveHindsightCpAccessKey(config, deps = {}) {
-  const ref = config?.hindsight?.cp_access_key?.trim();
-  if (!ref)
+  return resolveHindsightVaultString(config?.hindsight?.cp_access_key, deps);
+}
+async function resolveHindsightVaultString(ref, deps = {}) {
+  const trimmed = ref?.trim();
+  if (!trimmed)
     return;
   const { isVaultReference: isVaultReference2, parseVaultReference: parseVaultReference2 } = await Promise.resolve().then(() => (init_resolver(), exports_resolver));
-  if (!isVaultReference2(ref))
-    return ref;
+  if (!isVaultReference2(trimmed))
+    return trimmed;
   const brokerClient = await Promise.resolve().then(() => (init_client(), exports_client));
   const get = deps.getViaBrokerStructured ?? brokerClient.getViaBrokerStructured;
   const agentSlug = process.env.SWITCHROOM_AGENT_NAME;
   const token = agentSlug ? brokerClient.readVaultTokenFile(agentSlug) ?? undefined : undefined;
-  const resolved = await get(parseVaultReference2(ref), {
+  const resolved = await get(parseVaultReference2(trimmed), {
     ...token ? { token } : {}
   }).catch(() => null);
   if (!resolved || resolved.kind !== "ok" || resolved.entry.kind !== "string") {
@@ -18752,6 +18818,64 @@ async function resolveHindsightCpAccessKey(config, deps = {}) {
   const value = resolved.entry.value.trim();
   return value.length > 0 ? value : undefined;
 }
+async function resolveHindsightLiteLlm(config, deps = {}) {
+  const top = config?.litellm;
+  if (!top?.enabled || !top.base_url?.trim())
+    return {};
+  const ref = `vault:${HINDSIGHT_LITELLM_KEY_VAULT_REF}`;
+  const apiKey = await resolveHindsightVaultString(ref, deps);
+  if (!apiKey)
+    return { droppedRef: ref };
+  return {
+    litellm: {
+      baseUrl: top.base_url,
+      apiKey,
+      model: config?.memory?.config?.llm_model
+    }
+  };
+}
+function hindsightLiteLlmDroppedKeyWarning(ref) {
+  return `hindsight: LiteLLM routing key \`${ref}\` did not resolve through the ` + "vault broker (denied, missing, or broker down) \u2014 ANTHROPIC_BASE_URL and " + "ANTHROPIC_CUSTOM_HEADERS were DROPPED, so hindsight's LLM traffic will bypass the proxy entirely and its spend will NOT be metered under `end_user=hindsight`. Check the broker grant for the reference above, then re-run. If an ENV DRIFT report above named those two vars, THIS is " + "why \u2014 it is NOT operator env drift.";
+}
+async function resolveHindsightLlmSecrets(llm, deps = {}) {
+  if (!llm)
+    return llm;
+  const out = { ...llm };
+  if (llm.api_key !== undefined) {
+    out.api_key = await resolveHindsightVaultString(llm.api_key, deps);
+  }
+  for (const op of HINDSIGHT_LLM_OPS) {
+    const cfg = llm[op];
+    if (cfg?.api_key !== undefined) {
+      out[op] = {
+        ...cfg,
+        api_key: await resolveHindsightVaultString(cfg.api_key, deps)
+      };
+    }
+  }
+  return out;
+}
+async function diffDroppedHindsightLlmVaultKeys(original, resolved) {
+  if (!original)
+    return [];
+  const { isVaultReference: isVaultReference2 } = await Promise.resolve().then(() => (init_resolver(), exports_resolver));
+  const drops = [];
+  const check = (lane, origKey, resolvedKey) => {
+    const ref = origKey?.trim();
+    if (ref && isVaultReference2(ref) && !resolvedKey)
+      drops.push({ lane, ref });
+  };
+  check("global", original.api_key, resolved?.api_key);
+  for (const op of HINDSIGHT_LLM_OPS) {
+    check(op, original[op]?.api_key, resolved?.[op]?.api_key);
+  }
+  return drops;
+}
+function hindsightLlmDroppedKeyWarning(drop) {
+  const where = drop.lane === "global" ? "the global LLM lane" : `the \`${drop.lane}\` LLM op`;
+  const fallback = drop.lane === "global" ? "every op inherits" : "the op inherits";
+  return `hindsight: ${where} api_key \`${drop.ref}\` did not resolve through the ` + "vault broker (denied, missing, or broker down) \u2014 the key was DROPPED, so " + `${fallback} the provider-default credential and fact extraction on that lane may fail. Check the broker grant for the reference above, then re-run.`;
+}
 function hindsightLocalLlmEnabled(llm, litellm, override) {
   if (override !== undefined)
     return override;
@@ -18859,6 +18983,29 @@ function deviceRequestsHaveGpu(reqs) {
     return (r.Count ?? 0) !== 0;
   });
 }
+function resolveHindsightMemLimit(perf) {
+  const raw = perf?.memLimit?.trim();
+  if (!raw)
+    return HINDSIGHT_DEFAULT_MEM_LIMIT;
+  const capMib = parseDockerSizeToMib(raw);
+  if (capMib === null) {
+    throw new Error(`hindsight.mem_limit: \`${raw}\` is not a docker memory size. Use a number with an optional b/k/m/g suffix, e.g. \`24g\` or \`16384m\`.`);
+  }
+  const reservationMib = parseDockerSizeToMib(HINDSIGHT_DEFAULT_MEM_RESERVATION);
+  if (reservationMib !== null && capMib < reservationMib) {
+    throw new Error(`hindsight.mem_limit: \`${raw}\` is below the container's memory reservation (${HINDSIGHT_DEFAULT_MEM_RESERVATION}) \u2014 docker refuses ` + "to create a container whose memory limit is under its reservation.");
+  }
+  return raw;
+}
+function hindsightMemBudgetWarningFor(perf) {
+  const sharedBuffers = hindsightPgEnvPairs(perf).find(([k]) => k === HINDSIGHT_PG_SHARED_BUFFERS_ENV)?.[1];
+  if (!sharedBuffers)
+    return null;
+  return hindsightMemBudgetWarning({
+    memLimit: resolveHindsightMemLimit(perf),
+    sharedBuffers
+  });
+}
 function hindsightPerfEnvPairs(llm, litellm, gpu, perf) {
   return hindsightPerfEnv({
     gpu: hindsightGpuEnabled(gpu),
@@ -18868,6 +19015,23 @@ function hindsightPerfEnvPairs(llm, litellm, gpu, perf) {
 function hindsightPgEnvPairs(perf) {
   return hindsightPgEnv(resolveHindsightPgOverrides(perf?.env, perf?.processEnv));
 }
+function hindsightLiteLlmEnvPairs(litellm, llmModel) {
+  const baseUrl = litellm?.baseUrl?.trim();
+  const apiKey = litellm?.apiKey?.trim();
+  if (!baseUrl || !apiKey)
+    return [];
+  const litellmRoot = baseUrl.replace(/\/+$/, "");
+  const anthropicBaseUrl = isClaudeModel(llmModel) ? `${litellmRoot}/anthropic` : litellmRoot;
+  return [
+    ["ANTHROPIC_BASE_URL", anthropicBaseUrl],
+    [
+      "ANTHROPIC_CUSTOM_HEADERS",
+      `x-litellm-api-key: Bearer ${apiKey}
+x-litellm-customer-id: ${HINDSIGHT_LITELLM_CUSTOMER_ID}
+x-litellm-tags: service:${HINDSIGHT_LITELLM_CUSTOMER_ID}`
+    ]
+  ];
+}
 function hindsightContainerEnvPairs(opts) {
   const { apiPort, litellm, llm, gpu, perf, cpAccessKey } = opts;
   const { provider: llmProvider, model: llmModel } = resolveHindsightLlm(llm, litellm);
@@ -18895,16 +19059,7 @@ function hindsightContainerEnvPairs(opts) {
     accessKey: cpAccessKey,
     hostNetwork: hindsightNeedsHostNetwork(llm, litellm)
   }));
-  if (litellm) {
-    const litellmRoot = litellm.baseUrl.replace(/\/+$/, "");
-    const anthropicBaseUrl = isClaudeModel(llmModel) ? `${litellmRoot}/anthropic` : litellmRoot;
-    pairs.push(["ANTHROPIC_BASE_URL", anthropicBaseUrl], [
-      "ANTHROPIC_CUSTOM_HEADERS",
-      `x-litellm-api-key: Bearer ${litellm.apiKey}
-x-litellm-customer-id: hindsight
-x-litellm-tags: service:hindsight`
-    ]);
-  }
+  pairs.push(...hindsightLiteLlmEnvPairs(litellm, llmModel));
   return pairs;
 }
 function startHindsight(ports, litellm, imageTag, llm, mirrorDir, gpu, perf, cpAccessKey) {
@@ -18918,6 +19073,9 @@ function startHindsight(ports, litellm, imageTag, llm, mirrorDir, gpu, perf, cpA
     gpu,
     perf
   }).flatMap(([k, v]) => ["-e", `${k}=${v}`]);
+  const memBudgetWarning = hindsightMemBudgetWarningFor(perf);
+  if (memBudgetWarning)
+    console.warn(`  ! ${memBudgetWarning}`);
   const args = [
     "run",
     "-d",
@@ -18925,7 +19083,7 @@ function startHindsight(ports, litellm, imageTag, llm, mirrorDir, gpu, perf, cpA
     "switchroom-hindsight",
     "--restart",
     "always",
-    `--memory=${HINDSIGHT_DEFAULT_MEM_LIMIT}`,
+    `--memory=${resolveHindsightMemLimit(perf)}`,
     `--memory-reservation=${HINDSIGHT_DEFAULT_MEM_RESERVATION}`,
     `--pids-limit=${HINDSIGHT_DEFAULT_PIDS_LIMIT}`,
     `--shm-size=${HINDSIGHT_DEFAULT_SHM_SIZE}`,
@@ -19111,11 +19269,7 @@ function generateHindsightComposeSnippet(llm, mirrorDir, litellm, gpu, perf, cpA
     ...hostNetwork ? hindsightHostNetworkBindEnvPairs(apiPort).map(([k, v]) => `      - ${k}=${v}`) : [`      - HINDSIGHT_CP_DATAPLANE_API_URL=http://localhost:8888`],
     ...hindsightCpAuthEnvPairs({ accessKey: cpAccessKey, hostNetwork }).map(([k, v]) => `      - ${k}=${v}`)
   ];
-  if (litellm?.baseUrl?.trim() && litellm.apiKey?.trim()) {
-    const litellmRoot = litellm.baseUrl.replace(/\/+$/, "");
-    const anthropicBaseUrl = isClaudeModel(llmModel) ? `${litellmRoot}/anthropic` : litellmRoot;
-    environment.push(`      - ANTHROPIC_BASE_URL=${anthropicBaseUrl}`, `      - ANTHROPIC_CUSTOM_HEADERS=x-litellm-api-key: Bearer ${litellm.apiKey}\\nx-litellm-customer-id: hindsight\\nx-litellm-tags: service:hindsight`);
-  }
+  environment.push(...hindsightLiteLlmEnvPairs(litellm, llmModel).map(([k, v]) => `      - ${k}=${v.replace(/\n/g, "\\n")}`));
   const initService = mirrorDir ? [
     "  switchroom-hindsight-creds-init:",
     `    image: ${HINDSIGHT_IMAGE}`,
@@ -19156,7 +19310,7 @@ function generateHindsightComposeSnippet(llm, mirrorDir, litellm, gpu, perf, cpA
     ...hindsightPgEnvPairs(perf).map(([k, v]) => `      - ${k}=${v}`),
     `      - SWITCHROOM_HINDSIGHT_REQUEUE_DEAD_LETTERS=${HINDSIGHT_DEFAULT_REQUEUE_DEAD_LETTERS}`,
     `      - SWITCHROOM_HINDSIGHT_REQUEUE_MAX=${HINDSIGHT_DEFAULT_REQUEUE_MAX}`,
-    `    mem_limit: ${HINDSIGHT_DEFAULT_MEM_LIMIT}`,
+    `    mem_limit: ${resolveHindsightMemLimit(perf)}`,
     `    mem_reservation: ${HINDSIGHT_DEFAULT_MEM_RESERVATION}`,
     `    pids_limit: ${HINDSIGHT_DEFAULT_PIDS_LIMIT}`,
     `    shm_size: ${HINDSIGHT_DEFAULT_SHM_SIZE}`,
@@ -19265,7 +19419,7 @@ var HINDSIGHT_DEFAULT_API_PORT = 18888, HINDSIGHT_DEFAULT_UI_PORT = 9999, HINDSI
   } catch {
     return null;
   }
-}, HINDSIGHT_LLM_OPS, HINDSIGHT_HOST_NETWORK_BIND_ADDR = "127.0.0.1", HINDSIGHT_CP_UNAUTHENTICATED_BIND_ADDR = "127.0.0.1", HINDSIGHT_CP_AUTHENTICATED_BIND_ADDR = "0.0.0.0", HINDSIGHT_CP_NO_ACCESS_KEY_WARNING;
+}, HINDSIGHT_LLM_OPS, HINDSIGHT_HOST_NETWORK_BIND_ADDR = "127.0.0.1", HINDSIGHT_CP_UNAUTHENTICATED_BIND_ADDR = "127.0.0.1", HINDSIGHT_CP_AUTHENTICATED_BIND_ADDR = "0.0.0.0", HINDSIGHT_CP_NO_ACCESS_KEY_WARNING, HINDSIGHT_LITELLM_KEY_VAULT_REF = "litellm/hindsight/api-key", HINDSIGHT_LITELLM_CUSTOMER_ID = "hindsight";
 var init_hindsight = __esm(() => {
   init_model_command();
   init_timeout_budget();
@@ -32857,8 +33011,8 @@ function parseMemToMib(s) {
   return Math.round(n * mult);
 }
 function bumpMem(s, addMib) {
-  const mib = parseMemToMib(s);
-  return mib == null ? s : `${mib + addMib}m`;
+  const mib2 = parseMemToMib(s);
+  return mib2 == null ? s : `${mib2 + addMib}m`;
 }
 function resolveResourceDefaults(agentName, profile, overrides, opts) {
   let base;
@@ -47577,12 +47731,12 @@ function classifyDirectiveCount(count, bankLabel) {
   return null;
 }
 function classifyShmSize(bytes) {
-  const mib = Math.round(bytes / 1024 / 1024);
+  const mib2 = Math.round(bytes / 1024 / 1024);
   if (bytes < MIN_HINDSIGHT_SHM_BYTES) {
     return {
       name: "hindsight shm-size",
       status: "fail",
-      detail: `${mib}MB \u2014 PostgreSQL needs ~533MB+ for shared segments; writes will ` + `fail with "No space left on device"`,
+      detail: `${mib2}MB \u2014 PostgreSQL needs ~533MB+ for shared segments; writes will ` + `fail with "No space left on device"`,
       fix: "Recreate hindsight with a larger shm. The launch path now sets " + "--shm-size=2g (#2190); pull a release that includes it and run " + "`switchroom memory --restart`, or recreate the container manually " + "preserving the `switchroom-hindsight-data` volume."
     };
   }
@@ -106656,7 +106810,7 @@ function formatDroppedHindsightEnvReport(dropped, caps) {
 
 // src/cli/memory.ts
 init_hindsight_repair();
-init_client();
+init_resolver();
 init_atomic();
 init_loader();
 init_hindsight();
@@ -106706,22 +106860,32 @@ function resolveMemorySetupTag(input) {
     return { tag: pin, reason: "pin" };
   return { tag: undefined, reason: "latest" };
 }
-async function resolveLiteLLMForHindsight(config) {
-  const topLiteLLM = config.litellm;
-  if (!topLiteLLM?.enabled || !topLiteLLM.base_url)
-    return;
-  const agentSlug = process.env.SWITCHROOM_AGENT_NAME;
-  const token = agentSlug ? readVaultTokenFile(agentSlug) ?? undefined : undefined;
-  const result = await getViaBrokerStructured("litellm/hindsight/api-key", {
-    ...token ? { token } : {}
-  }).catch(() => null);
-  if (!result || result.kind !== "ok" || result.entry.kind !== "string")
-    return;
-  return {
-    baseUrl: topLiteLLM.base_url,
-    apiKey: result.entry.value,
-    model: config.memory?.config?.llm_model
+function hindsightSecretValues(input) {
+  const out = [];
+  const push = (v) => {
+    if (typeof v === "string" && v.trim().length > 0)
+      out.push(v.trim());
   };
+  push(input.cpAccessKey);
+  push(input.llm?.api_key);
+  for (const op of ["retain", "reflect", "consolidation"]) {
+    push(input.llm?.[op]?.api_key);
+  }
+  return out;
+}
+function hasUnresolvedHindsightVaultRef(config) {
+  const hindsight = config.hindsight;
+  return hindsightSecretValues({
+    llm: hindsight?.llm,
+    cpAccessKey: hindsight?.cp_access_key
+  }).some((v) => isVaultReference(v));
+}
+function emitsCleartextHindsightSecret(input) {
+  return hindsightSecretValues(input).some((v) => !isVaultReference(v));
+}
+var HINDSIGHT_COMPOSE_CLEARTEXT_SECRETS_WARNING = "This snippet embeds secrets in CLEARTEXT (LLM api_key and/or cp_access_key)." + " Treat the output as sensitive \u2014 do not paste it into shared channels or" + " commit it unredacted.";
+async function resolveLiteLLMForHindsight(config) {
+  return resolveHindsightLiteLlm(config);
 }
 function readRecallLog(agentDir, limit) {
   const path7 = join80(agentDir, ".claude", "plugins", "data", "hindsight-memory-inline", "state", "recall_log.jsonl");
@@ -106933,6 +107097,13 @@ Cross-agent reflection plan
       process.exit(1);
     }
     const recreate = opts.recreate === true;
+    let resolvedLlmPromise;
+    const getResolvedLlm = () => {
+      if (!resolvedLlmPromise) {
+        resolvedLlmPromise = resolveHindsightLlmSecrets(getConfig(program3).hindsight?.llm);
+      }
+      return resolvedLlmPromise;
+    };
     let releasePin;
     try {
       releasePin = getConfig(program3).release?.pin ?? undefined;
@@ -107001,18 +107172,19 @@ Cross-agent reflection plan
         const liveEnv = getHindsightContainerEnv();
         if (liveEnv) {
           const driftConfig = getConfig(program3);
-          const driftLitellm = await resolveLiteLLMForHindsight(driftConfig);
+          const driftLitellm = (await resolveLiteLLMForHindsight(driftConfig)).litellm;
           const driftPerf = { env: driftConfig.hindsight?.env };
+          const driftLlm = await getResolvedLlm();
           const nextEnv = hindsightContainerEnvPairs({
             apiPort: reusePorts?.apiPort ?? HINDSIGHT_DEFAULT_API_PORT,
             litellm: driftLitellm,
-            llm: driftConfig.hindsight?.llm,
+            llm: driftLlm,
             gpu: gpuDecision.enabled,
             perf: driftPerf,
             cpAccessKey: await resolveHindsightCpAccessKey(driftConfig)
           });
           const dropped = diffDroppedHindsightEnv(liveEnv, nextEnv, getHindsightImageEnv() ?? []);
-          envDriftLines = formatDroppedHindsightEnvReport(dropped, hindsightResolvedCapabilities(driftConfig.hindsight?.llm, driftLitellm, gpuDecision.enabled, driftPerf));
+          envDriftLines = formatDroppedHindsightEnvReport(dropped, hindsightResolvedCapabilities(driftLlm, driftLitellm, gpuDecision.enabled, driftPerf));
         }
       } catch (err) {
         console.log(source_default.gray(`  (env-drift check skipped: ${err.message})`));
@@ -107115,11 +107287,21 @@ Cross-agent reflection plan
     console.log(source_default.gray("  Starting Hindsight Docker container..."));
     try {
       const hindsightConfig = getConfig(program3);
-      const litellmCfg = await resolveLiteLLMForHindsight(hindsightConfig);
+      const { litellm: litellmCfg, droppedRef: litellmDroppedRef } = await resolveLiteLLMForHindsight(hindsightConfig);
+      if (litellmDroppedRef) {
+        console.log(source_default.yellow(`  ! ${hindsightLiteLlmDroppedKeyWarning(litellmDroppedRef)}`));
+      }
       const cpAccessKey = await resolveHindsightCpAccessKey(hindsightConfig);
       if (!cpAccessKey)
         console.log(source_default.yellow(`  ! ${HINDSIGHT_CP_NO_ACCESS_KEY_WARNING}`));
-      startHindsight(ports, litellmCfg, effectiveTag, hindsightConfig.hindsight?.llm, hindsightConsumerMirrorDir(hindsightConfig), gpuDecision.enabled, { env: hindsightConfig.hindsight?.env }, cpAccessKey);
+      const resolvedLlm = await getResolvedLlm();
+      for (const drop of await diffDroppedHindsightLlmVaultKeys(hindsightConfig.hindsight?.llm, resolvedLlm)) {
+        console.log(source_default.yellow(`  ! ${hindsightLlmDroppedKeyWarning(drop)}`));
+      }
+      startHindsight(ports, litellmCfg, effectiveTag, resolvedLlm, hindsightConsumerMirrorDir(hindsightConfig), gpuDecision.enabled, {
+        env: hindsightConfig.hindsight?.env,
+        memLimit: hindsightConfig.hindsight?.mem_limit
+      }, cpAccessKey);
       if (litellmCfg) {
         console.log(source_default.gray("  LiteLLM routing enabled for hindsight (--network host)."));
       }
@@ -107144,17 +107326,47 @@ Cross-agent reflection plan
 ` + `  Add memory.config.url: ${url} manually.`));
     }
   });
-  memory.command("docker-compose").description("Output a docker-compose snippet for Hindsight (broker-fed mode)").action(withConfigError(async () => {
+  memory.command("docker-compose").description("Output a docker-compose snippet for Hindsight (broker-fed mode)").option("--resolve-secrets", "Resolve `vault:` refs (the LLM api_key fields and cp_access_key) to their " + "live secret values before printing the snippet. Without this flag (the " + "default) the `vault:` refs are printed literally \u2014 this is an " + "operator-invoked command whose stdout routinely ends up pasted into " + "terminals, files, and chat, and a live `sk-\u2026` key has no business " + "landing there by accident (#4487). Pass this when you genuinely want a " + "runnable compose file, and treat the output as a secret once you do.").action(withConfigError(async (opts) => {
     console.log(source_default.bold(`
 # Add this to your docker-compose.yml:
 `));
     {
       const snippetConfig = getConfig(program3);
-      const cpAccessKey = await resolveHindsightCpAccessKey(snippetConfig);
-      if (!cpAccessKey) {
-        console.error(source_default.yellow(`# ! ${HINDSIGHT_CP_NO_ACCESS_KEY_WARNING}`));
+      const resolveSecrets = opts.resolveSecrets === true;
+      let cpAccessKey;
+      let snippetLlm;
+      if (resolveSecrets) {
+        cpAccessKey = await resolveHindsightCpAccessKey(snippetConfig);
+        if (!cpAccessKey) {
+          console.error(source_default.yellow(`# ! ${HINDSIGHT_CP_NO_ACCESS_KEY_WARNING}`));
+        }
+        snippetLlm = await resolveHindsightLlmSecrets(snippetConfig.hindsight?.llm);
+      } else {
+        cpAccessKey = snippetConfig.hindsight?.cp_access_key;
+        snippetLlm = snippetConfig.hindsight?.llm;
+        if (hasUnresolvedHindsightVaultRef(snippetConfig)) {
+          console.log(source_default.yellow("# NOTE: `vault:` references below are left UNRESOLVED (default) \u2014 this\n" + `#       snippet is not runnable as-is. Resolve them yourself before use, or
+` + `#       re-run with --resolve-secrets to print the live secret values
+` + `#       instead. If you do, treat this command's output as a secret: don't
+` + `#       paste it into chat, logs, or an unencrypted file.
+`));
+        }
       }
-      console.log(generateHindsightComposeSnippet(snippetConfig.hindsight?.llm, hindsightConsumerMirrorDir(snippetConfig), undefined, hindsightGpuDecision(resolveHindsightGpuOverride({ config: snippetConfig.hindsight?.gpu })).enabled, { env: snippetConfig.hindsight?.env }, cpAccessKey));
+      {
+        const memWarning = hindsightMemBudgetWarningFor({
+          env: snippetConfig.hindsight?.env,
+          memLimit: snippetConfig.hindsight?.mem_limit
+        });
+        if (memWarning)
+          console.error(source_default.yellow(`# ! ${memWarning}`));
+      }
+      if (emitsCleartextHindsightSecret({ llm: snippetLlm, cpAccessKey })) {
+        console.error(source_default.yellow(`# ! ${HINDSIGHT_COMPOSE_CLEARTEXT_SECRETS_WARNING}`));
+      }
+      console.log(generateHindsightComposeSnippet(snippetLlm, hindsightConsumerMirrorDir(snippetConfig), undefined, hindsightGpuDecision(resolveHindsightGpuOverride({ config: snippetConfig.hindsight?.gpu })).enabled, {
+        env: snippetConfig.hindsight?.env,
+        memLimit: snippetConfig.hindsight?.mem_limit
+      }, cpAccessKey));
     }
     console.log();
   }));
@@ -111810,7 +112022,6 @@ init_onboarding();
 init_gpu_detect();
 init_host_capabilities();
 init_hindsight();
-init_client();
 init_posthog();
 
 // src/cli/setup-posture-rewrite.ts
@@ -112634,22 +112845,8 @@ async function stepCreateTopics(config, botToken, nonInteractive) {
     }
   }
 }
-async function resolveLiteLLMForHindsight2(config) {
-  const topLiteLLM = config.litellm;
-  if (!topLiteLLM?.enabled || !topLiteLLM.base_url)
-    return;
-  const agentSlug = process.env.SWITCHROOM_AGENT_NAME;
-  const token = agentSlug ? readVaultTokenFile(agentSlug) ?? undefined : undefined;
-  const result = await getViaBrokerStructured("litellm/hindsight/api-key", {
-    ...token ? { token } : {}
-  }).catch(() => null);
-  if (!result || result.kind !== "ok" || result.entry.kind !== "string")
-    return;
-  return {
-    baseUrl: topLiteLLM.base_url,
-    apiKey: result.entry.value,
-    model: config.memory?.config?.llm_model
-  };
+async function resolveLiteLLMForHindsight2(config, deps = {}) {
+  return resolveHindsightLiteLlm(config, deps);
 }
 function isMemoryBackendDisabled(config) {
   const memoryBackend = config.memory?.backend ?? "hindsight";
@@ -112748,13 +112945,20 @@ async function stepMemoryBackend(config, nonInteractive, switchroomConfigPath, d
   }
   const spin = spinner("Starting Hindsight Docker container...");
   try {
-    const litellmCfg = await resolveLiteLLMForHindsight2(config);
+    const { litellm: litellmCfg, droppedRef: litellmDroppedRef } = await resolveLiteLLMForHindsight2(config, deps.getViaBrokerStructured ? { getViaBrokerStructured: deps.getViaBrokerStructured } : {});
+    if (litellmDroppedRef) {
+      console.log(source_default.yellow(`  ! ${hindsightLiteLlmDroppedKeyWarning(litellmDroppedRef)}`));
+    }
     const cpAccessKey = await resolveHindsightCpAccessKey(config);
     if (!cpAccessKey) {
       console.log(source_default.yellow(`  ! ${HINDSIGHT_CP_NO_ACCESS_KEY_WARNING}`));
     }
+    const resolvedLlm = await resolveHindsightLlmSecrets(config.hindsight?.llm, deps.getViaBrokerStructured ? { getViaBrokerStructured: deps.getViaBrokerStructured } : {});
+    for (const drop of await diffDroppedHindsightLlmVaultKeys(config.hindsight?.llm, resolvedLlm)) {
+      console.log(source_default.yellow(`  ! ${hindsightLlmDroppedKeyWarning(drop)}`));
+    }
     const startContainer = deps.startContainer ?? startHindsight;
-    startContainer(ports, litellmCfg, undefined, config.hindsight?.llm, hindsightConsumerMirrorDir(config), undefined, undefined, cpAccessKey);
+    startContainer(ports, litellmCfg, undefined, resolvedLlm, hindsightConsumerMirrorDir(config), undefined, { env: config.hindsight?.env, memLimit: config.hindsight?.mem_limit }, cpAccessKey);
     if (litellmCfg) {
       console.log(source_default.gray("  LiteLLM routing enabled (--network host, ANTHROPIC_BASE_URL set)."));
     }
@@ -128564,15 +128768,1193 @@ async function notifyOperator(agentsDir, text, log) {
   return agent !== null;
 }
 
+// src/cli/hindsight-bench.ts
+init_source();
+import { mkdirSync as mkdirSync71, readFileSync as readFileSync113, writeFileSync as writeFileSync52 } from "node:fs";
+import { dirname as dirname51, resolve as resolve67 } from "node:path";
+
+// src/hindsight-bench/anonymise.ts
+function pseudonym(n, width) {
+  return `bank-${String(n).padStart(width, "0")}`;
+}
+function buildBankMap(result) {
+  const ordered = [];
+  const seen = new Set;
+  const push = (b) => {
+    if (b !== "" && !seen.has(b)) {
+      seen.add(b);
+      ordered.push(b);
+    }
+  };
+  for (const r of result.db?.bankRows ?? [])
+    push(r.bank);
+  for (const b of result.config?.banks ?? [])
+    push(b);
+  for (const c of result.cells ?? [])
+    push(c.bank);
+  for (const a of result.arms ?? [])
+    push(a.bank);
+  const width = Math.max(2, String(ordered.length).length);
+  const map2 = new Map;
+  ordered.forEach((bank, i2) => map2.set(bank, pseudonym(i2 + 1, width)));
+  return map2;
+}
+function anonymiseResult(result) {
+  const mapping = buildBankMap(result);
+  const sub = (b) => mapping.get(b) ?? b;
+  return {
+    mapping,
+    result: {
+      ...result,
+      config: { ...result.config, banks: (result.config?.banks ?? []).map(sub) },
+      db: {
+        ...result.db,
+        bankRows: (result.db?.bankRows ?? []).map((r) => ({ ...r, bank: sub(r.bank) }))
+      },
+      cells: (result.cells ?? []).map((c) => ({ ...c, bank: sub(c.bank) })),
+      arms: result.arms === null ? null : result.arms.map((a) => ({ ...a, bank: sub(a.bank) }))
+    }
+  };
+}
+function formatBankMapping(mapping) {
+  return [...mapping.entries()].map(([real, pseudo]) => `  ${pseudo}  ${real}`).join(`
+`);
+}
+
+// src/hindsight-bench/banks.ts
+class BankSelectionError extends Error {
+}
+function selectBanks(available, spec) {
+  const nonEmpty = available.filter((b) => b.rows > 0).sort((a, b) => b.rows - a.rows);
+  const trimmed = spec.trim();
+  if (trimmed === "all")
+    return nonEmpty.map((b) => b.bank);
+  const top = /^top:(\d+)$/.exec(trimmed);
+  if (top !== null)
+    return nonEmpty.slice(0, Math.max(1, Number(top[1]))).map((b) => b.bank);
+  const spread = /^spread:(\d+)$/.exec(trimmed);
+  if (spread !== null) {
+    const n = Math.max(1, Number(spread[1]));
+    if (nonEmpty.length <= n)
+      return nonEmpty.map((b) => b.bank);
+    const asc = [...nonEmpty].sort((a, b) => a.rows - b.rows);
+    const lo = Math.log10(asc[0].rows);
+    const hi = Math.log10(asc[asc.length - 1].rows);
+    const chosen = new Set;
+    for (let i2 = 0;i2 < n; i2++) {
+      const target = lo + (hi - lo) * i2 / (n - 1);
+      let best = null;
+      let bestD = Infinity;
+      for (const b of asc) {
+        if (chosen.has(b.bank))
+          continue;
+        const d = Math.abs(Math.log10(b.rows) - target);
+        if (d < bestD) {
+          bestD = d;
+          best = b;
+        }
+      }
+      if (best !== null)
+        chosen.add(best.bank);
+    }
+    return nonEmpty.filter((b) => chosen.has(b.bank)).map((b) => b.bank);
+  }
+  const named = trimmed.split(",").map((s) => s.trim()).filter((s) => s !== "");
+  if (named.length === 0)
+    throw new BankSelectionError(`--banks "${spec}" selected nothing`);
+  const known = new Set(available.map((b) => b.bank));
+  const missing = named.filter((n) => !known.has(n));
+  if (missing.length > 0) {
+    throw new BankSelectionError(`--banks names ${missing.join(", ")}, which ${missing.length === 1 ? "is" : "are"} not in this instance ` + `(known: ${available.map((b) => b.bank).join(", ")})`);
+  }
+  return named;
+}
+function parseConcurrency(spec) {
+  const out = new Set;
+  for (const part of spec.split(",")) {
+    const n = Number(part.trim());
+    if (!Number.isInteger(n) || n < 1) {
+      throw new BankSelectionError(`--concurrency "${spec}": "${part.trim()}" is not a positive integer`);
+    }
+    out.add(n);
+  }
+  if (out.size === 0)
+    throw new BankSelectionError("--concurrency selected nothing");
+  return [...out].sort((a, b) => a - b);
+}
+
+// src/hindsight-bench/contention.ts
+import { spawn as spawn8 } from "node:child_process";
+
+// src/hindsight-bench/db.ts
+import { spawnSync as spawnSync33 } from "node:child_process";
+var DEFAULT_CONTAINER2 = "switchroom-hindsight";
+var defaultRunner5 = (cmd, args, stdin) => {
+  const r = spawnSync33(cmd, args, {
+    stdio: "pipe",
+    input: stdin,
+    timeout: 120000,
+    encoding: "utf8",
+    maxBuffer: 16 * 1024 * 1024
+  });
+  if (r.error)
+    return { status: null, stdout: "", stderr: r.error.message };
+  return { status: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
+};
+function bootstrapSh(readOnly) {
+  return `
+set -e
+B="$(ls -d /home/hindsight/.pg0/installation/*/bin 2>/dev/null | head -1)"
+PSQL="$(command -v psql 2>/dev/null || echo "\${B:-/nonexistent}/psql")"
+[ -x "$PSQL" ] || { echo "hindsight-bench: no psql in container" >&2; exit 3; }
+D=/home/hindsight/.pg0/instances/hindsight/instance.json
+[ -r "$D" ] || { echo "hindsight-bench: no pg0 instance descriptor" >&2; exit 3; }
+eval "$(python3 -c 'import json,shlex,sys
+d=json.load(open(sys.argv[1]))
+q=lambda k,dflt: shlex.quote(str(d.get(k) or dflt))
+print("U=%s DB=%s P=%s PW=%s"%(q("username","hindsight"),q("database","hindsight"),q("port",5432),q("password","")))' "$D")"
+[ -n "$PW" ] || { echo "hindsight-bench: pg0 descriptor carries no password" >&2; exit 3; }
+PGPASSWORD="$PW" PGOPTIONS='-c default_transaction_read_only=${readOnly ? "on" : "off"}' \\
+  "$PSQL" -U "$U" -h /tmp -p "$P" -d "$DB" -v ON_ERROR_STOP=1 -tAF'|' -f -
+`;
+}
+
+class SqlError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SqlError";
+  }
+}
+function sql(script, opts = {}) {
+  const run = opts.run ?? defaultRunner5;
+  const container = opts.container ?? DEFAULT_CONTAINER2;
+  const r = run("docker", ["exec", "-i", container, "sh", "-c", bootstrapSh(opts.writable !== true)], script);
+  if (r.status !== 0) {
+    throw new SqlError(`psql in ${container} exited ${r.status}: ${r.stderr.trim() || "no stderr"}`);
+  }
+  return r.stdout.split(`
+`).map((l) => l.trim()).filter((l) => l !== "");
+}
+function assertReadOnlyOrWritesAllowed(allowWrites, opts = {}) {
+  const rows = sql(`DO $$
+     BEGIN
+       CREATE TEMP TABLE hindsight_bench_ro_probe(x int);
+     EXCEPTION WHEN others THEN
+       NULL;
+     END $$;
+     SELECT current_setting('transaction_read_only') || '|' ||
+            (to_regclass('pg_temp.hindsight_bench_ro_probe') IS NOT NULL)::text;`, opts);
+  const [declared, landed] = (rows[rows.length - 1] ?? "").split("|");
+  const declaredReadOnly = declared === "on";
+  const writeLanded = landed === "t";
+  const writable = !declaredReadOnly || writeLanded;
+  if (writable && !allowWrites) {
+    throw new SqlError("refusing to run: the harness's database session is WRITABLE " + `(transaction_read_only=${declared ?? "?"}, temp-table write ${writeLanded ? "succeeded" : "failed"}). ` + "This harness measures a read path and must not be able to mutate a bank. " + "Pass --allow-writes only if you genuinely intend a writable session " + "(contention profile `write` needs one for its own scratch table).");
+  }
+}
+function resetStats(opts = {}) {
+  sql("SELECT pg_stat_reset();", { ...opts, writable: true });
+}
+function readInstanceState(opts = {}) {
+  const run = opts.run ?? defaultRunner5;
+  const container = opts.container ?? DEFAULT_CONTAINER2;
+  const one = (args) => {
+    const r = run("docker", args);
+    if (r.status !== 0)
+      return null;
+    const v = r.stdout.trim();
+    return v === "" ? null : v;
+  };
+  const imageTag = one(["inspect", "--format", "{{.Config.Image}}", container]);
+  const cand = one(["exec", container, "printenv", "HINDSIGHT_API_RERANKER_MAX_CANDIDATES"]);
+  const candNum = cand === null ? NaN : Number(cand);
+  return { imageTag, rerankerMaxCandidates: Number.isFinite(candNum) ? candNum : null };
+}
+function num3(v) {
+  const n = Number(v);
+  return Number.isFinite(n) ? n : NaN;
+}
+function readDbState(opts = {}) {
+  const settings = sql(`SELECT
+       (SELECT setting::bigint * 8192 FROM pg_settings WHERE name = 'shared_buffers'),
+       (SELECT setting::bigint * 8192 FROM pg_settings WHERE name = 'effective_cache_size'),
+       (SELECT setting FROM pg_settings WHERE name = 'hnsw.ef_search'),
+       pg_total_relation_size('memory_units'),
+       pg_table_size('memory_units'),
+       pg_indexes_size('memory_units'),
+       (SELECT stats_reset::text FROM pg_stat_database WHERE datname = current_database()),
+       (SELECT CASE WHEN heap_blks_hit + heap_blks_read = 0 THEN NULL
+                    ELSE heap_blks_hit::float8 / (heap_blks_hit + heap_blks_read) END
+          FROM pg_statio_user_tables WHERE relname = 'memory_units'),
+       version();`, opts);
+  const f = (settings[0] ?? "").split("|");
+  if (f.length < 9) {
+    throw new SqlError(`unexpected settings row shape: ${JSON.stringify(settings[0] ?? "")}`);
+  }
+  const bankRows = sql(`SELECT bank_id, count(*) FROM memory_units GROUP BY bank_id ORDER BY 2 DESC;`, opts).map((l) => {
+    const [bank, rows] = l.split("|");
+    return { bank: bank ?? "", rows: num3(rows) };
+  }).filter((b) => b.bank !== "" && Number.isFinite(b.rows));
+  const largestIndexes = sql(`SELECT c.relname, pg_relation_size(c.oid), coalesce(s.idx_scan, 0)
+       FROM pg_index i
+       JOIN pg_class c ON c.oid = i.indexrelid
+       LEFT JOIN pg_stat_user_indexes s ON s.indexrelid = c.oid
+      WHERE i.indrelid = 'memory_units'::regclass
+      ORDER BY pg_relation_size(c.oid) DESC
+      LIMIT 8;`, opts).map((l) => {
+    const [name, bytes, scans] = l.split("|");
+    return { name: name ?? "", bytes: num3(bytes), scans: num3(scans) };
+  }).filter((x) => x.name !== "");
+  const efRaw = f[2] ?? "";
+  return {
+    sharedBuffersBytes: num3(f[0]),
+    effectiveCacheSizeBytes: num3(f[1]),
+    hnswEfSearch: efRaw === "" ? null : num3(efRaw),
+    memoryUnitsTotalBytes: num3(f[3]),
+    memoryUnitsHeapBytes: num3(f[4]),
+    memoryUnitsIndexBytes: num3(f[5]),
+    bankRows,
+    largestIndexes,
+    statsResetAt: (f[6] ?? "") === "" ? null : f[6],
+    heapHitRatio: (f[7] ?? "") === "" ? null : num3(f[7]),
+    serverVersion: f.slice(8).join("|")
+  };
+}
+
+// src/hindsight-bench/contention.ts
+var CONTENTION_APP_NAME = "hindsight-bench-contention";
+var SCRATCH_TABLE = "hindsight_bench_scratch";
+var DEFAULT_CONTENTION = {
+  workers: 2,
+  scanPct: 2,
+  maxSeconds: 900
+};
+function clampInt(v, lo, hi, dflt) {
+  const n = Math.floor(Number(v));
+  if (!Number.isFinite(n))
+    return dflt;
+  return Math.min(hi, Math.max(lo, n));
+}
+function clampFloat(v, lo, hi, dflt) {
+  const n = Number(v);
+  if (!Number.isFinite(n))
+    return dflt;
+  return Math.min(hi, Math.max(lo, n));
+}
+function contentionSql(profile, scanPct, maxSeconds) {
+  const pct2 = clampFloat(scanPct, 0.1, 100, DEFAULT_CONTENTION.scanPct);
+  const secs = clampInt(maxSeconds, 1, 3600, DEFAULT_CONTENTION.maxSeconds);
+  const churn = `PERFORM sum(length(m.text)) FROM memory_units m TABLESAMPLE SYSTEM (${pct2});`;
+  const writes = profile === "write" ? `
+    INSERT INTO ${SCRATCH_TABLE} (payload)
+      SELECT repeat('x', 2048) FROM generate_series(1, 2000);
+    UPDATE ${SCRATCH_TABLE} SET payload = payload || 'y' WHERE id % 3 = 0;
+    DELETE FROM ${SCRATCH_TABLE}
+     WHERE id < (SELECT coalesce(max(id), 0) - 20000 FROM ${SCRATCH_TABLE});` : "";
+  return `
+DO $$
+DECLARE deadline timestamptz := clock_timestamp() + interval '${secs} seconds';
+BEGIN
+  WHILE clock_timestamp() < deadline LOOP
+    ${churn}${writes}
+  END LOOP;
+END $$;
+`;
+}
+function noContention() {
+  return { profile: "off", workers: 0, liveBackends: 0, stop: () => {} };
+}
+function countContentionBackends(opts = {}) {
+  const rows = sql(`SELECT count(*) FROM pg_stat_activity WHERE application_name = '${CONTENTION_APP_NAME}';`, opts);
+  const n = Number(rows[0]);
+  return Number.isFinite(n) ? n : 0;
+}
+function workerSh(readOnly) {
+  return `
+set -e
+B="$(ls -d /home/hindsight/.pg0/installation/*/bin 2>/dev/null | head -1)"
+PSQL="$(command -v psql 2>/dev/null || echo "\${B:-/nonexistent}/psql")"
+[ -x "$PSQL" ] || exit 3
+D=/home/hindsight/.pg0/instances/hindsight/instance.json
+[ -r "$D" ] || exit 3
+eval "$(python3 -c 'import json,shlex,sys
+d=json.load(open(sys.argv[1]))
+q=lambda k,dflt: shlex.quote(str(d.get(k) or dflt))
+print("U=%s DB=%s P=%s PW=%s"%(q("username","hindsight"),q("database","hindsight"),q("port",5432),q("password","")))' "$D")"
+PGPASSWORD="$PW" PGAPPNAME='${CONTENTION_APP_NAME}' \\
+  PGOPTIONS='-c default_transaction_read_only=${readOnly ? "on" : "off"}' \\
+  "$PSQL" -U "$U" -h /tmp -p "$P" -d "$DB" -q -v ON_ERROR_STOP=1 -f - >/dev/null
+`;
+}
+
+class ContentionError extends Error {
+}
+var sleep4 = (ms) => new Promise((r) => setTimeout(r, ms));
+async function startContention(opts) {
+  if (opts.profile === "off")
+    return noContention();
+  const container = opts.container ?? DEFAULT_CONTAINER2;
+  const sqlOpts = { container, run: opts.run };
+  const workers = clampInt(opts.workers, 1, 64, DEFAULT_CONTENTION.workers);
+  const readOnly = opts.profile !== "write";
+  if (opts.profile === "write") {
+    sql(`CREATE TABLE IF NOT EXISTS ${SCRATCH_TABLE} (id bigserial PRIMARY KEY, payload text);
+       TRUNCATE ${SCRATCH_TABLE};`, { ...sqlOpts, writable: true });
+  }
+  const script = contentionSql(opts.profile, opts.scanPct, opts.maxSeconds);
+  const children = [];
+  let workerStderr = "";
+  for (let i2 = 0;i2 < workers; i2++) {
+    const child = spawn8("docker", ["exec", "-i", container, "sh", "-c", workerSh(readOnly)], {
+      stdio: ["pipe", "ignore", "pipe"],
+      detached: false
+    });
+    child.stdin?.end(script);
+    child.stderr?.on("data", (d) => {
+      if (workerStderr.length < 4000)
+        workerStderr += d.toString();
+    });
+    child.on("error", (e) => {
+      workerStderr += `${e.message}
+`;
+    });
+    children.push(child);
+  }
+  let stopped = false;
+  const killAll = () => {
+    for (const c of children) {
+      try {
+        c.kill("SIGKILL");
+      } catch {}
+    }
+  };
+  let liveBackends = 0;
+  for (let attempt = 0;attempt < 10 && liveBackends === 0; attempt++) {
+    await sleep4(500);
+    liveBackends = countContentionBackends(sqlOpts);
+  }
+  if (liveBackends === 0) {
+    killAll();
+    throw new ContentionError(`contention profile "${opts.profile}" started ${workers} worker(s) but none attached to ` + `PostgreSQL within 5s \u2014 the measurement would be of an IDLE system. ` + `worker stderr: ${workerStderr.trim() || "(none)"}`);
+  }
+  return {
+    profile: opts.profile,
+    workers,
+    liveBackends,
+    stop: () => {
+      if (stopped)
+        return;
+      stopped = true;
+      killAll();
+      try {
+        sql(`SELECT pg_terminate_backend(pid) FROM pg_stat_activity
+            WHERE application_name = '${CONTENTION_APP_NAME}' AND pid <> pg_backend_pid();`, sqlOpts);
+      } catch {}
+      if (opts.profile === "write") {
+        try {
+          sql(`DROP TABLE IF EXISTS ${SCRATCH_TABLE};`, { ...sqlOpts, writable: true });
+        } catch {}
+      }
+    }
+  };
+}
+
+// src/hindsight-bench/plot.ts
+var W2 = 900;
+var H = 520;
+var PAD = { top: 46, right: 210, bottom: 56, left: 76 };
+var COLOURS = ["#0072B2", "#D55E00", "#009E73", "#CC79A7", "#E69F00", "#56B4E9", "#F0E442", "#000000"];
+function escapeXml(s) {
+  return s.replace(/[<>&"']/g, (c) => `&#${c.charCodeAt(0)};`);
+}
+function buildSeries(results) {
+  const series = [];
+  for (const r of results) {
+    const byConc = new Map;
+    for (const c of r.cells) {
+      if (!Number.isFinite(c.stats.p95) || c.rows <= 0)
+        continue;
+      const arr = byConc.get(c.concurrency) ?? [];
+      arr.push({ x: c.rows, y: c.stats.p95 });
+      byConc.set(c.concurrency, arr);
+    }
+    const tag = r.config.label || r.config.startedAt;
+    for (const conc of [...byConc.keys()].sort((a, b) => a - b)) {
+      const pts = byConc.get(conc).sort((a, b) => a.x - b.x);
+      series.push({ label: `${tag} \u00b7 c=${conc}`, points: pts });
+    }
+  }
+  return series;
+}
+function renderPlot(results, title = "Hindsight recall p95 vs bank size") {
+  const series = buildSeries(results);
+  const all = series.flatMap((s) => s.points);
+  if (all.length === 0) {
+    return `<svg xmlns="http://www.w3.org/2000/svg" width="${W2}" height="80"><text x="16" y="44" font-family="sans-serif" font-size="14">no plottable cells (every p95 was non-finite)</text></svg>`;
+  }
+  const xs = all.map((p) => Math.log10(p.x));
+  const ys = all.map((p) => p.y);
+  const x0 = Math.min(...xs);
+  const x1 = Math.max(...xs);
+  const y1 = Math.max(...ys);
+  const xSpan = x1 - x0 === 0 ? 1 : x1 - x0;
+  const ySpan = y1 === 0 ? 1 : y1 * 1.08;
+  const px = (v) => PAD.left + (Math.log10(v) - x0) / xSpan * (W2 - PAD.left - PAD.right);
+  const py = (v) => H - PAD.bottom - v / ySpan * (H - PAD.top - PAD.bottom);
+  const parts = [];
+  parts.push(`<svg xmlns="http://www.w3.org/2000/svg" width="${W2}" height="${H}" viewBox="0 0 ${W2} ${H}">`);
+  parts.push(`<rect width="${W2}" height="${H}" fill="#ffffff"/>`);
+  parts.push(`<text x="${PAD.left}" y="26" font-family="sans-serif" font-size="16" font-weight="600">${escapeXml(title)}</text>`);
+  for (let i2 = 0;i2 <= 4; i2++) {
+    const v = ySpan / 4 * i2;
+    const y = py(v);
+    parts.push(`<line x1="${PAD.left}" y1="${y}" x2="${W2 - PAD.right}" y2="${y}" stroke="#e6e6e6"/>`);
+    parts.push(`<text x="${PAD.left - 8}" y="${y + 4}" text-anchor="end" font-family="sans-serif" font-size="11" fill="#555">${Math.round(v)}</text>`);
+  }
+  for (let d = Math.floor(x0);d <= Math.ceil(x1); d++) {
+    const v = 10 ** d;
+    if (Math.log10(v) < x0 || Math.log10(v) > x1)
+      continue;
+    const x = px(v);
+    parts.push(`<line x1="${x}" y1="${PAD.top}" x2="${x}" y2="${H - PAD.bottom}" stroke="#f0f0f0"/>`);
+    parts.push(`<text x="${x}" y="${H - PAD.bottom + 18}" text-anchor="middle" font-family="sans-serif" font-size="11" fill="#555">10^${d}</text>`);
+  }
+  parts.push(`<line x1="${PAD.left}" y1="${H - PAD.bottom}" x2="${W2 - PAD.right}" y2="${H - PAD.bottom}" stroke="#333"/>`);
+  parts.push(`<line x1="${PAD.left}" y1="${PAD.top}" x2="${PAD.left}" y2="${H - PAD.bottom}" stroke="#333"/>`);
+  parts.push(`<text x="${(PAD.left + W2 - PAD.right) / 2}" y="${H - 14}" text-anchor="middle" font-family="sans-serif" font-size="12" fill="#333">memory_units rows in bank (log scale)</text>`);
+  parts.push(`<text x="18" y="${(PAD.top + H - PAD.bottom) / 2}" text-anchor="middle" font-family="sans-serif" font-size="12" fill="#333" transform="rotate(-90 18 ${(PAD.top + H - PAD.bottom) / 2})">recall p95 (ms)</text>`);
+  series.forEach((s, i2) => {
+    const colour = COLOURS[i2 % COLOURS.length];
+    const d = s.points.map((p, j) => `${j === 0 ? "M" : "L"}${px(p.x).toFixed(1)},${py(p.y).toFixed(1)}`).join(" ");
+    parts.push(`<path d="${d}" fill="none" stroke="${colour}" stroke-width="2"/>`);
+    for (const p of s.points) {
+      parts.push(`<circle cx="${px(p.x).toFixed(1)}" cy="${py(p.y).toFixed(1)}" r="3" fill="${colour}"/>`);
+    }
+    const ly = PAD.top + 6 + i2 * 18;
+    parts.push(`<line x1="${W2 - PAD.right + 12}" y1="${ly}" x2="${W2 - PAD.right + 32}" y2="${ly}" stroke="${colour}" stroke-width="2"/>`);
+    parts.push(`<text x="${W2 - PAD.right + 38}" y="${ly + 4}" font-family="sans-serif" font-size="11" fill="#333">${escapeXml(s.label)}</text>`);
+  });
+  parts.push("</svg>");
+  return parts.join(`
+`);
+}
+
+// src/hindsight-bench/recall.ts
+var QUERY_SET_ID = "generic-v1";
+var RECALL_QUERIES = [
+  "what did we decide about the deployment process",
+  "open issues that are still blocked",
+  "postgres configuration and tuning decisions",
+  "how does authentication work here",
+  "what went wrong in the last incident",
+  "preferences about how to write reports",
+  "recent changes to the build pipeline",
+  "who is responsible for the review process",
+  "outstanding follow-up work and commitments",
+  "container restart and rollout procedure",
+  "why was that approach rejected",
+  "measurement results and benchmark numbers",
+  "scheduling and cron behaviour",
+  "known limitations of the current design",
+  "what changed in the most recent release",
+  "error handling and retry behaviour",
+  "naming conventions used in this project",
+  "cost and quota considerations",
+  "notes about testing and coverage",
+  "security constraints that must not be crossed"
+];
+function restBase(url) {
+  return url.replace(/\/mcp\/?$/, "").replace(/\/$/, "");
+}
+async function recallOnce(bank, query, opts) {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const url = `${restBase(opts.apiUrl)}/v1/default/banks/${encodeURIComponent(bank)}/memories/recall`;
+  const body = JSON.stringify({
+    query,
+    types: ["world", "experience"],
+    budget: opts.budget,
+    max_tokens: opts.maxTokens,
+    trace: opts.trace === true
+  });
+  const started = performance.now();
+  try {
+    const res = await fetchImpl(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body,
+      redirect: "error",
+      signal: AbortSignal.timeout(opts.timeoutMs)
+    });
+    const text = await res.text();
+    const ms = performance.now() - started;
+    if (!res.ok)
+      return { ok: false, ms, results: 0, error: `HTTP ${res.status}` };
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      return { ok: false, ms, results: 0, error: "unparseable JSON body" };
+    }
+    const results = Array.isArray(parsed.results) ? parsed.results.length : 0;
+    return opts.trace === true ? { ok: true, ms, results, trace: parsed.trace } : { ok: true, ms, results };
+  } catch (e) {
+    return {
+      ok: false,
+      ms: performance.now() - started,
+      results: 0,
+      error: e.name === "TimeoutError" ? `timeout >${opts.timeoutMs}ms` : e.message
+    };
+  }
+}
+
+// src/hindsight-bench/stats.ts
+function percentile2(values, p) {
+  if (values.length === 0)
+    return NaN;
+  if (!(p > 0) || p > 1)
+    throw new RangeError(`percentile p must be in (0, 1], got ${p}`);
+  const sorted = [...values].sort((a, b) => a - b);
+  const rank = Math.min(sorted.length, Math.max(1, Math.ceil(p * sorted.length)));
+  return sorted[rank - 1];
+}
+var BOOTSTRAP_REPS = 2000;
+function mulberry32(seed) {
+  let a = seed >>> 0;
+  return () => {
+    a = a + 1831565813 >>> 0;
+    let t = Math.imul(a ^ a >>> 15, 1 | a);
+    t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t;
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+}
+function bootstrapP95Ci(values, reps = BOOTSTRAP_REPS) {
+  const n = values.length;
+  if (n === 0)
+    return [NaN, NaN];
+  if (n === 1)
+    return [values[0], values[0]];
+  const pool = [...values].sort((a, b) => a - b);
+  const seed = n * 2654435761 + Math.round(pool.reduce((a, b) => a + b, 0));
+  const rnd = mulberry32(seed);
+  const reduced = new Array(reps);
+  const draw = new Array(n);
+  for (let r = 0;r < reps; r++) {
+    for (let i2 = 0;i2 < n; i2++)
+      draw[i2] = pool[Math.floor(rnd() * n)];
+    reduced[r] = percentile2(draw, 0.95);
+  }
+  reduced.sort((a, b) => a - b);
+  const lo = reduced[Math.max(0, Math.floor(0.025 * reps) - 1)];
+  const hi = reduced[Math.min(reps - 1, Math.ceil(0.975 * reps) - 1)];
+  return [lo, hi];
+}
+function summarize(samplesMs, errors4) {
+  const n = samplesMs.length;
+  if (n === 0) {
+    return {
+      n: 0,
+      errors: errors4,
+      min: NaN,
+      p50: NaN,
+      p95: NaN,
+      p99: NaN,
+      max: NaN,
+      mean: NaN,
+      stddev: NaN,
+      cv: NaN,
+      p95CiLow: NaN,
+      p95CiHigh: NaN
+    };
+  }
+  const sorted = [...samplesMs].sort((a, b) => a - b);
+  const sum = sorted.reduce((a, b) => a + b, 0);
+  const mean = sum / n;
+  const variance = sorted.reduce((a, v) => a + (v - mean) ** 2, 0) / n;
+  const stddev = Math.sqrt(variance);
+  const [p95CiLow, p95CiHigh] = bootstrapP95Ci(sorted);
+  return {
+    n,
+    errors: errors4,
+    min: sorted[0],
+    p50: percentile2(sorted, 0.5),
+    p95: percentile2(sorted, 0.95),
+    p99: percentile2(sorted, 0.99),
+    max: sorted[n - 1],
+    mean,
+    stddev,
+    cv: mean === 0 ? 0 : stddev / mean,
+    p95CiLow,
+    p95CiHigh
+  };
+}
+function round(v, dp = 1) {
+  if (!Number.isFinite(v))
+    return v;
+  const f = 10 ** dp;
+  return Math.round(v * f) / f;
+}
+
+// src/hindsight-bench/report.ts
+var DEFAULT_TOLERANCE = 0.1;
+var cellKey = (bank, concurrency) => `${bank}@c${concurrency}`;
+function duplicateCellKeys(cells) {
+  const seen = new Set;
+  const dupes = new Set;
+  for (const c of cells) {
+    const key = cellKey(c.bank, c.concurrency);
+    if (seen.has(key))
+      dupes.add(key);
+    seen.add(key);
+  }
+  return [...dupes];
+}
+var MAX_CELL_ERROR_RATE = 0.1;
+function ungradeable(r) {
+  const out = [];
+  for (const c of r.cells) {
+    const { n, errors: errors4 } = c.stats;
+    const key = cellKey(c.bank, c.concurrency);
+    if (n === 0 || !Number.isFinite(c.stats.p95)) {
+      out.push({ key, label: `${key} (no-samples, ${errors4} errors)` });
+    } else if (errors4 / (n + errors4) > MAX_CELL_ERROR_RATE) {
+      out.push({ key, label: `${key} (error-rate ${round(errors4 / (n + errors4) * 100, 0)}%, n=${n})` });
+    }
+  }
+  return out;
+}
+function compareRuns(a, b, tolerance = DEFAULT_TOLERANCE) {
+  const bByKey = new Map(b.cells.map((c) => [cellKey(c.bank, c.concurrency), c]));
+  const seen = new Set;
+  const cells = [];
+  const unmatched = [];
+  const bad = [...ungradeable(a), ...ungradeable(b)];
+  const badKeys = new Set(bad.map((u) => u.key));
+  for (const ca of a.cells) {
+    const key = cellKey(ca.bank, ca.concurrency);
+    seen.add(key);
+    const cb = bByKey.get(key);
+    if (badKeys.has(key))
+      continue;
+    if (cb === undefined || !Number.isFinite(ca.stats.p95) || !Number.isFinite(cb.stats.p95) || ca.stats.p95 === 0) {
+      unmatched.push(key);
+      continue;
+    }
+    const relDelta = Math.abs(cb.stats.p95 - ca.stats.p95) / ca.stats.p95;
+    const ciLow = ca.stats.p95CiLow;
+    const ciHigh = ca.stats.p95CiHigh;
+    const noiseFloor = Number.isFinite(ciLow) && Number.isFinite(ciHigh) ? (ciHigh - ciLow) / 2 / ca.stats.p95 : NaN;
+    cells.push({
+      bank: ca.bank,
+      concurrency: ca.concurrency,
+      p95A: ca.stats.p95,
+      p95B: cb.stats.p95,
+      relDelta,
+      within: relDelta <= tolerance,
+      noiseFloor,
+      explainedByNoise: Number.isFinite(noiseFloor) && relDelta <= noiseFloor
+    });
+  }
+  for (const key of bByKey.keys())
+    if (!seen.has(key) && !badKeys.has(key))
+      unmatched.push(key);
+  const worstRelDelta = cells.reduce((m, c) => Math.max(m, c.relDelta), 0);
+  const ungradeableLabels = [...new Set(bad.map((u) => u.label))];
+  return {
+    tolerance,
+    cells,
+    unmatched,
+    ungradeable: ungradeableLabels,
+    worstRelDelta,
+    pass: unmatched.length === 0 && ungradeableLabels.length === 0 && cells.length > 0 && cells.every((c) => c.within)
+  };
+}
+var CONTENTION_MIN_REL_DELTA = 0.1;
+function compareContention(idle, loaded, minRelDelta = CONTENTION_MIN_REL_DELTA) {
+  const loadedByKey = new Map(loaded.cells.map((c) => [cellKey(c.bank, c.concurrency), c]));
+  const cells = [];
+  const bad = [...ungradeable(idle), ...ungradeable(loaded)];
+  const badKeys = new Set(bad.map((u) => u.key));
+  for (const ci of idle.cells) {
+    if (badKeys.has(cellKey(ci.bank, ci.concurrency)))
+      continue;
+    const cl = loadedByKey.get(cellKey(ci.bank, ci.concurrency));
+    if (cl === undefined || !Number.isFinite(ci.stats.p95) || ci.stats.p95 === 0 || !Number.isFinite(cl.stats.p95)) {
+      continue;
+    }
+    cells.push({
+      bank: ci.bank,
+      concurrency: ci.concurrency,
+      idleP95: ci.stats.p95,
+      loadedP95: cl.stats.p95,
+      relDelta: (cl.stats.p95 - ci.stats.p95) / ci.stats.p95
+    });
+  }
+  const raised = cells.filter((c) => c.relDelta > 0).length;
+  const sorted = cells.map((c) => c.relDelta).sort((a, b) => a - b);
+  const medianRelDelta = sorted.length === 0 ? 0 : sorted[Math.floor((sorted.length - 1) / 2)];
+  const ungradeableLabels = [...new Set(bad.map((u) => u.label))];
+  return {
+    cells,
+    raised,
+    medianRelDelta,
+    minRelDelta,
+    ungradeable: ungradeableLabels,
+    pass: cells.length > 0 && ungradeableLabels.length === 0 && raised > cells.length / 2 && medianRelDelta >= minRelDelta
+  };
+}
+var mb = (bytes) => Number.isFinite(bytes) ? `${Math.round(bytes / 1024 / 1024)} MB` : "?";
+function pad5(s, n) {
+  return s.length >= n ? s : s + " ".repeat(n - s.length);
+}
+function padL(s, n) {
+  return s.length >= n ? s : " ".repeat(n - s.length) + s;
+}
+function formatSummary(r) {
+  const L = [];
+  const c = r.config;
+  L.push(`hindsight recall bench \u2014 ${c.label || "(unlabelled)"}`);
+  L.push(`  started ${c.startedAt}  \u00b7  ${round(r.durationS, 0)}s  \u00b7  schema v${r.schema}`);
+  L.push(`  banks=${c.banks.length} concurrency=${c.concurrency.join(",")} samples=${c.samples} ` + `warmup=${c.warmup} query-set=${c.querySet} budget=${c.budget}`);
+  L.push(`  contention=${c.contention}${c.contention === "off" ? "" : ` workers=${c.contentionWorkers}`}` + `  stats-reset=${c.statsReset}  allow-writes=${c.allowWrites}`);
+  L.push("");
+  L.push(`  instance image=${r.instance.imageTag ?? "unknown"}  ` + `reranker_max_candidates=${r.instance.rerankerMaxCandidates ?? "unset"}`);
+  L.push("");
+  L.push("  db state");
+  L.push(`    shared_buffers=${mb(r.db.sharedBuffersBytes)}  effective_cache_size=${mb(r.db.effectiveCacheSizeBytes)}` + `  hnsw.ef_search=${r.db.hnswEfSearch ?? "unset"}`);
+  L.push(`    memory_units total=${mb(r.db.memoryUnitsTotalBytes)} (heap ${mb(r.db.memoryUnitsHeapBytes)} + ` + `indexes ${mb(r.db.memoryUnitsIndexBytes)})`);
+  const fit = r.db.memoryUnitsTotalBytes / r.db.sharedBuffersBytes;
+  L.push(`    working set / shared_buffers = ${round(fit * 100, 1)}%`);
+  L.push(`    stats_reset=${r.db.statsResetAt ?? "NEVER (cache-hit ratios are cumulative since initdb)"}` + `  heap_hit=${r.db.heapHitRatio === null ? "n/a" : `${round(r.db.heapHitRatio * 100, 2)}%`}`);
+  L.push("");
+  L.push(`  ${pad5("bank", 16)}${padL("rows", 8)}${padL("conc", 6)}${padL("n", 6)}${padL("err", 5)}` + `${padL("p50", 9)}${padL("p95", 9)}${padL("p99", 9)}${padL("max", 9)}${padL("cv", 7)}${padL("hits", 7)}`);
+  for (const cell of r.cells) {
+    const s = cell.stats;
+    L.push(`  ${pad5(cell.bank, 16)}${padL(String(cell.rows), 8)}${padL(String(cell.concurrency), 6)}` + `${padL(String(s.n), 6)}${padL(String(s.errors), 5)}` + `${padL(Number.isFinite(s.p50) ? s.p50.toFixed(0) : "-", 9)}` + `${padL(Number.isFinite(s.p95) ? s.p95.toFixed(0) : "-", 9)}` + `${padL(Number.isFinite(s.p99) ? s.p99.toFixed(0) : "-", 9)}` + `${padL(Number.isFinite(s.max) ? s.max.toFixed(0) : "-", 9)}` + `${padL(Number.isFinite(s.cv) ? s.cv.toFixed(2) : "-", 7)}` + `${padL(cell.meanResults.toFixed(1), 7)}`);
+  }
+  const empties = r.cells.filter((c2) => c2.zeroResultCalls > 0);
+  if (empties.length > 0) {
+    L.push("");
+    L.push("  ! cells with zero-result recalls (latency there is not measuring retrieval):");
+    for (const c2 of empties)
+      L.push(`      ${c2.bank} c=${c2.concurrency}: ${c2.zeroResultCalls}/${c2.stats.n} empty`);
+  }
+  if (r.arms !== null && r.arms.length > 0) {
+    L.push("");
+    L.push("  arm attribution (SEPARATE traced pass \u2014 not comparable to the latency table above)");
+    L.push(`  ${pad5("bank", 16)}${pad5("method", 12)}${pad5("fact_type", 12)}${padL("n", 5)}${padL("p50", 9)}${padL("p95", 9)}`);
+    for (const a of r.arms) {
+      L.push(`  ${pad5(a.bank, 16)}${pad5(a.method, 12)}${pad5(a.fact_type, 12)}${padL(String(a.n), 5)}` + `${padL(a.p50.toFixed(1), 9)}${padL(a.p95.toFixed(1), 9)}`);
+    }
+  }
+  return L.join(`
+`);
+}
+function formatReproducibility(rep) {
+  const L = [];
+  L.push(`reproducibility (AC1) \u2014 tolerance \u00b1${round(rep.tolerance * 100, 0)}% on p95 per cell`);
+  L.push(`  ${pad5("bank", 16)}${padL("conc", 6)}${padL("p95 A", 10)}${padL("p95 B", 10)}` + `${padL("delta", 9)}${padL("\u00b1noise", 9)}   verdict`);
+  for (const c of rep.cells) {
+    L.push(`  ${pad5(c.bank, 16)}${padL(String(c.concurrency), 6)}${padL(c.p95A.toFixed(0), 10)}` + `${padL(c.p95B.toFixed(0), 10)}${padL(`${round(c.relDelta * 100, 1)}%`, 9)}` + `${padL(Number.isFinite(c.noiseFloor) ? `${round(c.noiseFloor * 100, 1)}%` : "-", 9)}   ` + `${c.within ? "ok" : c.explainedByNoise ? "OUT*" : "OUT"}`);
+  }
+  for (const u of rep.unmatched)
+    L.push(`  ${u}: UNMATCHED (present in only one run, or no usable p95)`);
+  for (const u of rep.ungradeable)
+    L.push(`  ${u}: UNGRADEABLE \u2014 the measurement failed here`);
+  L.push(`  worst delta ${round(rep.worstRelDelta * 100, 1)}%  \u2192  ${rep.pass ? "PASS" : "FAIL"}`);
+  const noisy = rep.cells.filter((c) => c.explainedByNoise).length;
+  const floors = rep.cells.map((c) => c.noiseFloor).filter((v) => Number.isFinite(v));
+  if (floors.length > 0) {
+    const median2 = [...floors].sort((a, b) => a - b)[Math.floor(floors.length / 2)];
+    L.push(`  median \u00b1noise ${round(median2 * 100, 1)}% \u2014 the smallest delta this sample count can ` + `distinguish from luck; ${noisy}/${rep.cells.length} cells (OUT*) are inside it`);
+    if (median2 > rep.tolerance) {
+      L.push(`  NOTE: the median noise floor EXCEEDS the \u00b1${round(rep.tolerance * 100, 0)}% gate \u2014 ` + `at this sample count the gate is not attainable regardless of how stable the ` + `system is. Raise --samples or grade a lower percentile; do not widen the tolerance to fit.`);
+    }
+  }
+  return L.join(`
+`);
+}
+function formatContention(rep) {
+  const L = [];
+  L.push(`contention (AC4) \u2014 contended p95 must exceed idle p95 in a majority of cells, ` + `median movement \u2265 ${round(rep.minRelDelta * 100, 0)}%`);
+  L.push(`  ${pad5("bank", 16)}${padL("conc", 6)}${padL("idle p95", 11)}${padL("load p95", 11)}${padL("delta", 9)}`);
+  for (const c of rep.cells) {
+    L.push(`  ${pad5(c.bank, 16)}${padL(String(c.concurrency), 6)}${padL(c.idleP95.toFixed(0), 11)}` + `${padL(c.loadedP95.toFixed(0), 11)}${padL(`${round(c.relDelta * 100, 1)}%`, 9)}`);
+  }
+  for (const u of rep.ungradeable)
+    L.push(`  ${u}: UNGRADEABLE \u2014 the measurement failed here`);
+  L.push(`  raised in ${rep.raised}/${rep.cells.length} cells, median ${round(rep.medianRelDelta * 100, 1)}%  \u2192  ` + `${rep.pass ? "PASS" : "FAIL"}`);
+  if (rep.ungradeable.length > 0) {
+    L.push(`  FAIL is on the MEASUREMENT, not the generator: ${rep.ungradeable.length} cell(s) could not ` + `be graded, so the cells above are whichever ones survived. Re-run before concluding anything.`);
+  }
+  return L.join(`
+`);
+}
+function toCsv(r) {
+  const head = "label,bank,rows,concurrency,n,errors,p50_ms,p95_ms,p95_ci_low_ms,p95_ci_high_ms,p99_ms,max_ms,mean_ms,stddev_ms,cv,mean_results,zero_result_calls,contention";
+  const rows = r.cells.map((c) => [
+    JSON.stringify(r.config.label),
+    c.bank,
+    c.rows,
+    c.concurrency,
+    c.stats.n,
+    c.stats.errors,
+    round(c.stats.p50, 2),
+    round(c.stats.p95, 2),
+    round(c.stats.p95CiLow, 2),
+    round(c.stats.p95CiHigh, 2),
+    round(c.stats.p99, 2),
+    round(c.stats.max, 2),
+    round(c.stats.mean, 2),
+    round(c.stats.stddev, 2),
+    round(c.stats.cv, 4),
+    round(c.meanResults, 2),
+    c.zeroResultCalls,
+    r.config.contention
+  ].join(","));
+  return [head, ...rows].join(`
+`);
+}
+
+// src/hindsight-bench/run.ts
+var MAX_ERROR_SAMPLES = 5;
+var realSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function driveCell(bank, concurrency, count, recall) {
+  const out = [];
+  let cursor = 0;
+  const worker = async () => {
+    for (;; ) {
+      const i2 = cursor++;
+      if (i2 >= count)
+        return;
+      const query = RECALL_QUERIES[i2 % RECALL_QUERIES.length];
+      out.push(await recall(bank, query));
+    }
+  };
+  await Promise.all(Array.from({ length: Math.max(1, concurrency) }, () => worker()));
+  return out;
+}
+async function runSweep(opts) {
+  const { config: config2, db } = opts;
+  const deps = opts.deps ?? {};
+  const sleep5 = deps.sleep ?? realSleep;
+  const log = deps.log ?? (() => {});
+  const settleMs = opts.settleMs ?? 2000;
+  const recall = deps.recall ?? ((bank, query) => recallOnce(bank, query, {
+    apiUrl: config2.apiUrl,
+    timeoutMs: config2.timeoutMs,
+    budget: config2.budget,
+    maxTokens: config2.maxTokens
+  }));
+  const rowsFor = new Map(db.bankRows.map((b) => [b.bank, b.rows]));
+  const cells = [];
+  for (const bank of config2.banks) {
+    for (const concurrency of [...config2.concurrency].sort((a, b) => a - b)) {
+      if (config2.warmup > 0) {
+        await driveCell(bank, concurrency, config2.warmup, recall);
+      }
+      const raw = await driveCell(bank, concurrency, config2.samples, recall);
+      const ok = raw.filter((s) => s.ok);
+      const okMs = ok.map((s) => s.ms);
+      const errs = raw.filter((s) => !s.ok);
+      const errorSamples = [...new Set(errs.map((e) => e.error ?? "unknown"))].slice(0, MAX_ERROR_SAMPLES);
+      const stats = summarize(okMs, errs.length);
+      cells.push({
+        bank,
+        rows: rowsFor.get(bank) ?? 0,
+        concurrency,
+        stats,
+        meanResults: ok.length === 0 ? 0 : ok.reduce((a, s) => a + s.results, 0) / ok.length,
+        zeroResultCalls: ok.filter((s) => s.results === 0).length,
+        samplesMs: okMs,
+        errorSamples
+      });
+      log(`  ${bank} c=${concurrency}: n=${stats.n} err=${stats.errors} ` + `p50=${stats.p50.toFixed(0)}ms p95=${stats.p95.toFixed(0)}ms p99=${stats.p99.toFixed(0)}ms`);
+      if (settleMs > 0)
+        await sleep5(settleMs);
+    }
+  }
+  return cells;
+}
+function extractArms(trace) {
+  const rr = trace?.retrieval_results;
+  if (!Array.isArray(rr))
+    return [];
+  const out = [];
+  for (const entry of rr) {
+    const method = typeof entry?.method_name === "string" ? entry.method_name : null;
+    const factType = typeof entry?.fact_type === "string" ? entry.fact_type : "";
+    const secs = Number(entry?.duration_seconds);
+    if (method === null || !Number.isFinite(secs))
+      continue;
+    out.push({ method, fact_type: factType, ms: secs * 1000 });
+  }
+  return out;
+}
+async function runArmSweep(opts) {
+  const { config: config2 } = opts;
+  const log = opts.deps?.log ?? (() => {});
+  const recall = opts.deps?.recall ?? ((bank, query) => recallOnce(bank, query, {
+    apiUrl: config2.apiUrl,
+    timeoutMs: config2.timeoutMs,
+    budget: config2.budget,
+    maxTokens: config2.maxTokens,
+    trace: true
+  }));
+  const buckets = new Map;
+  for (const bank of config2.banks) {
+    for (let i2 = 0;i2 < opts.samples; i2++) {
+      const query = RECALL_QUERIES[i2 % RECALL_QUERIES.length];
+      const sample = await recall(bank, query);
+      if (!sample.ok)
+        continue;
+      for (const arm of extractArms(sample.trace)) {
+        const key = `${bank}\x00${arm.method}\x00${arm.fact_type}`;
+        const b = buckets.get(key) ?? { bank, method: arm.method, fact_type: arm.fact_type, ms: [] };
+        b.ms.push(arm.ms);
+        buckets.set(key, b);
+      }
+    }
+    log(`  arms: ${bank} traced ${opts.samples}x`);
+  }
+  const rows = [];
+  for (const b of buckets.values()) {
+    const s = summarize(b.ms, 0);
+    rows.push({ bank: b.bank, method: b.method, fact_type: b.fact_type, n: s.n, p50: s.p50, p95: s.p95, max: s.max });
+  }
+  rows.sort((a, b) => a.bank.localeCompare(b.bank) || b.p50 - a.p50);
+  return rows;
+}
+
+// src/hindsight-bench/types.ts
+var BENCH_SCHEMA_VERSION = 2;
+
+// src/cli/hindsight-bench.ts
+var DEFAULT_API_URL = "http://127.0.0.1:18888";
+function fail9(msg) {
+  process.stderr.write(source_default.red(`hindsight-bench: ${msg}
+`));
+  process.exit(2);
+}
+function readResult(path10) {
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync113(path10, "utf8"));
+  } catch (e) {
+    fail9(`cannot read ${path10}: ${e.message}`);
+  }
+  if (!Array.isArray(parsed.cells) || parsed.config === undefined) {
+    fail9(`${path10} is not a hindsight-bench result file (no cells/config)`);
+  }
+  if (parsed.schema !== BENCH_SCHEMA_VERSION) {
+    fail9(`${path10} is schema v${parsed.schema}, this build reads v${BENCH_SCHEMA_VERSION}`);
+  }
+  const dupes = duplicateCellKeys(parsed.cells);
+  if (dupes.length > 0) {
+    fail9(`${path10} has duplicate cells (${dupes.join(", ")}) \u2014 cannot be graded`);
+  }
+  return parsed;
+}
+function writeOut(path10, body) {
+  const abs = resolve67(path10);
+  mkdirSync71(dirname51(abs), { recursive: true });
+  writeFileSync52(abs, body);
+  process.stderr.write(`${source_default.green("\u2713")} wrote ${abs}
+`);
+}
+function resolveProfile(v) {
+  if (v === undefined || v === false)
+    return "off";
+  if (v === true || v === "")
+    return "read";
+  if (v === "off" || v === "read" || v === "write")
+    return v;
+  fail9(`--contention must be one of off|read|write (got "${String(v)}")`);
+}
+function intOpt(raw, name) {
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n < 0)
+    fail9(`${name} must be a non-negative integer (got "${raw}")`);
+  return n;
+}
+function registerHindsightBenchCommand(program3) {
+  program3.command("hindsight-bench").description("Measure Hindsight recall latency as a function of bank size and concurrency. " + "Percentiles, not means. Read-only by default; --contention degrades the live box.").option("--api-url <url>", "Hindsight REST base", DEFAULT_API_URL).option("--container <name>", "hindsight container for the psql probes", DEFAULT_CONTAINER2).option("--banks <spec>", "all | top:<n> | spread:<n> | comma list", "spread:5").option("--concurrency <list>", "comma-separated concurrency levels", "1,4,8,16").option("--samples <n>", "recorded recalls per cell", "60").option("--warmup <n>", "discarded recalls per cell before recording", "8").option("--timeout-ms <ms>", "per-recall timeout", "30000").option("--settle-ms <ms>", "quiet period between cells", "2000").option("--budget <budget>", "recall budget", "mid").option("--max-tokens <n>", "recall max_tokens", "4096").option("--contention [profile]", "run the sweep under synthetic load: read (cache churn, SELECT-only) or " + "write (adds a WAL storm against a harness-owned scratch table; needs --allow-writes)").option("--contention-workers <n>", "concurrent load backends", String(DEFAULT_CONTENTION.workers)).option("--contention-scan-pct <pct>", "TABLESAMPLE percentage per churn scan", String(DEFAULT_CONTENTION.scanPct)).option("--contention-max-seconds <s>", "absolute in-SQL deadline for every load backend (orphan guard)", String(DEFAULT_CONTENTION.maxSeconds)).option("--reset-stats", "call pg_stat_reset() before the sweep (never implicit)", false).option("--allow-writes", "authorise a writable database session (AC5 gate)", false).option("--arms [n]", "additionally run a traced per-arm attribution pass (n samples/bank, default 5)").option("--label <text>", "free-form label recorded in the result file", "").option("--out <path>", "write the JSON result file (or the SVG in --plot mode)").option("--csv <path>", "also write a flat per-cell CSV").option("--plot <files...>", "render the chart from result files instead of measuring").option("--compare <files...>", "AC1 reproducibility verdict over two result files").option("--contention-compare <files...>", "AC4 contention verdict over two result files").option("--tolerance <fraction>", "AC1 tolerance", String(DEFAULT_TOLERANCE)).option("--json", "emit machine-readable JSON for the verdict modes", false).action(async (opts) => {
+    if (opts.plot !== undefined)
+      return runPlotMode(opts);
+    if (opts.compare !== undefined)
+      return runCompareMode(opts);
+    if (opts.contentionCompare !== undefined)
+      return runContentionCompareMode(opts);
+    await runMeasureMode(opts);
+  });
+}
+function expectTwo(files, flag) {
+  if (files.length !== 2)
+    fail9(`${flag} takes exactly two result files (got ${files.length})`);
+  return [files[0], files[1]];
+}
+function runPlotMode(opts) {
+  const results = opts.plot.map(readResult);
+  const svg = renderPlot(results);
+  if (opts.out === undefined) {
+    process.stdout.write(svg + `
+`);
+    return;
+  }
+  writeOut(opts.out, svg + `
+`);
+}
+function runCompareMode(opts) {
+  const [pa, pb] = expectTwo(opts.compare, "--compare");
+  const tolerance = Number(opts.tolerance);
+  if (!Number.isFinite(tolerance) || tolerance < 0)
+    fail9(`--tolerance must be a non-negative number`);
+  const rep = compareRuns(readResult(pa), readResult(pb), tolerance);
+  process.stdout.write((opts.json ? JSON.stringify(rep, null, 2) : formatReproducibility(rep)) + `
+`);
+  if (!rep.pass)
+    process.exitCode = 1;
+}
+function runContentionCompareMode(opts) {
+  const [pi, pl] = expectTwo(opts.contentionCompare, "--contention-compare");
+  const rep = compareContention(readResult(pi), readResult(pl));
+  process.stdout.write((opts.json ? JSON.stringify(rep, null, 2) : formatContention(rep)) + `
+`);
+  if (!rep.pass)
+    process.exitCode = 1;
+}
+async function runMeasureMode(opts) {
+  const profile = resolveProfile(opts.contention);
+  const container = opts.container;
+  const sqlOpts = { container };
+  if (profile === "write" && !opts.allowWrites) {
+    fail9("--contention write opens a writable session for its scratch table; pass --allow-writes to authorise it");
+  }
+  try {
+    assertReadOnlyOrWritesAllowed(opts.allowWrites, sqlOpts);
+  } catch (e) {
+    fail9(e.message);
+  }
+  let db;
+  try {
+    db = readDbState(sqlOpts);
+  } catch (e) {
+    fail9(`could not read database state: ${e.message}`);
+  }
+  const instance = readInstanceState(sqlOpts);
+  let banks;
+  let concurrency;
+  try {
+    banks = selectBanks(db.bankRows, opts.banks);
+    concurrency = parseConcurrency(opts.concurrency);
+  } catch (e) {
+    if (e instanceof BankSelectionError)
+      fail9(e.message);
+    throw e;
+  }
+  if (opts.resetStats) {
+    try {
+      resetStats(sqlOpts);
+      process.stderr.write(`${source_default.yellow("!")} pg_stat_reset() called \u2014 cumulative statistics were discarded
+`);
+    } catch (e) {
+      fail9(`--reset-stats failed: ${e.message}`);
+    }
+  }
+  const config2 = {
+    startedAt: new Date().toISOString(),
+    apiUrl: opts.apiUrl,
+    container,
+    banks,
+    concurrency,
+    samples: intOpt(opts.samples, "--samples"),
+    warmup: intOpt(opts.warmup, "--warmup"),
+    timeoutMs: intOpt(opts.timeoutMs, "--timeout-ms"),
+    contention: profile,
+    contentionWorkers: profile === "off" ? 0 : intOpt(opts.contentionWorkers, "--contention-workers"),
+    statsReset: opts.resetStats,
+    allowWrites: opts.allowWrites,
+    querySet: QUERY_SET_ID,
+    budget: opts.budget,
+    maxTokens: intOpt(opts.maxTokens, "--max-tokens"),
+    label: opts.label
+  };
+  const armSamples = opts.arms === undefined ? 0 : opts.arms === true || opts.arms === "" ? 5 : Number(opts.arms);
+  if (!Number.isFinite(armSamples) || armSamples < 0)
+    fail9(`--arms must be a non-negative integer`);
+  process.stderr.write(`sweeping ${banks.length} bank(s) \u00d7 ${concurrency.length} concurrency level(s) = ` + `${banks.length * concurrency.length} cells, ${config2.samples} samples each ` + `(+${config2.warmup} warm-up) \u00b7 contention=${profile}
+`);
+  const t0 = Date.now();
+  let load = noContention();
+  let result;
+  try {
+    if (profile !== "off") {
+      load = await startContention({
+        profile,
+        workers: config2.contentionWorkers,
+        scanPct: Number(opts.contentionScanPct),
+        maxSeconds: intOpt(opts.contentionMaxSeconds, "--contention-max-seconds"),
+        container
+      });
+      process.stderr.write(`${source_default.yellow("!")} contention "${profile}" running: ${load.liveBackends} of ` + `${load.workers} worker(s) confirmed attached to PostgreSQL \u2014 ` + `the live fleet is degraded until this finishes
+`);
+      const onSignal = () => {
+        load.stop();
+        process.exit(130);
+      };
+      process.once("SIGINT", onSignal);
+      process.once("SIGTERM", onSignal);
+      await new Promise((r) => setTimeout(r, 5000));
+    }
+    const cells = await runSweep({
+      config: config2,
+      db,
+      settleMs: intOpt(opts.settleMs, "--settle-ms"),
+      deps: { log: (m) => process.stderr.write(`${m}
+`) }
+    });
+    const arms = armSamples > 0 ? await runArmSweep({ config: config2, samples: armSamples, deps: { log: (m) => process.stderr.write(`${m}
+`) } }) : null;
+    result = {
+      schema: BENCH_SCHEMA_VERSION,
+      config: config2,
+      db,
+      instance,
+      cells,
+      arms,
+      durationS: (Date.now() - t0) / 1000
+    };
+  } finally {
+    load.stop();
+  }
+  process.stdout.write(formatSummary(result) + `
+`);
+  const { result: safeResult, mapping } = anonymiseResult(result);
+  if (opts.out !== undefined || opts.csv !== undefined) {
+    process.stderr.write(`${source_default.cyan("i")} bank names are pseudonymised in the written file(s); this mapping is NOT persisted:
+` + `${formatBankMapping(mapping)}
+`);
+  }
+  if (opts.out !== undefined)
+    writeOut(opts.out, JSON.stringify(safeResult, null, 2) + `
+`);
+  if (opts.csv !== undefined)
+    writeOut(opts.csv, toCsv(safeResult) + `
+`);
+  if (opts.out === undefined && opts.csv === undefined) {
+    process.stderr.write(source_default.yellow(`! no --out given \u2014 this run's samples were not persisted and cannot be diffed later
+`));
+  }
+}
+
 // src/cli/openrouter-watch.ts
 init_source();
 import { existsSync as existsSync127, readdirSync as readdirSync51 } from "node:fs";
 import { homedir as homedir71 } from "node:os";
-import { join as join126, resolve as resolve68 } from "node:path";
+import { join as join126, resolve as resolve69 } from "node:path";
 
 // src/openrouter/install-cron.ts
-import { existsSync as existsSync126, mkdirSync as mkdirSync71, readFileSync as readFileSync113, renameSync as renameSync33, writeFileSync as writeFileSync52 } from "node:fs";
-import { dirname as dirname51 } from "node:path";
+import { existsSync as existsSync126, mkdirSync as mkdirSync72, readFileSync as readFileSync114, renameSync as renameSync33, writeFileSync as writeFileSync53 } from "node:fs";
+import { dirname as dirname52 } from "node:path";
 var CRON_PATH3 = "/etc/cron.d/openrouter-watch";
 var CRON_SCHEDULE2 = "17 * * * *";
 var CRON_LOG_PATH3 = "/var/log/openrouter-watch.log";
@@ -128591,28 +129973,28 @@ function installCron3(opts) {
   const content = renderCron3(opts);
   if (existsSync126(path10)) {
     try {
-      if (readFileSync113(path10, "utf8") === content) {
+      if (readFileSync114(path10, "utf8") === content) {
         return { status: "unchanged", path: path10, content };
       }
     } catch {}
   }
-  mkdirSync71(dirname51(path10), { recursive: true });
+  mkdirSync72(dirname52(path10), { recursive: true });
   const tmp = `${path10}.${process.pid}.tmp`;
-  writeFileSync52(tmp, content, { mode: 420 });
+  writeFileSync53(tmp, content, { mode: 420 });
   renameSync33(tmp, path10);
   return { status: "installed", path: path10, content };
 }
 // src/openrouter/state.ts
-import { mkdirSync as mkdirSync72, readFileSync as readFileSync114, renameSync as renameSync34, writeFileSync as writeFileSync53 } from "node:fs";
+import { mkdirSync as mkdirSync73, readFileSync as readFileSync115, renameSync as renameSync34, writeFileSync as writeFileSync54 } from "node:fs";
 import { homedir as homedir70 } from "node:os";
-import { dirname as dirname52, resolve as resolve67 } from "node:path";
+import { dirname as dirname53, resolve as resolve68 } from "node:path";
 function defaultStatePath3(home2 = process.env.SWITCHROOM_HOME ?? process.env.HOME ?? homedir70()) {
-  return resolve67(home2, ".switchroom", "openrouter-watch", "state.json");
+  return resolve68(home2, ".switchroom", "openrouter-watch", "state.json");
 }
 function loadState2(path10) {
   let parsed;
   try {
-    parsed = JSON.parse(readFileSync114(path10, "utf8"));
+    parsed = JSON.parse(readFileSync115(path10, "utf8"));
   } catch {
     return {};
   }
@@ -128632,10 +130014,10 @@ function loadState2(path10) {
   return out;
 }
 function saveState2(path10, state) {
-  mkdirSync72(dirname52(path10), { recursive: true, mode: 448 });
+  mkdirSync73(dirname53(path10), { recursive: true, mode: 448 });
   const tmp = `${path10}.${process.pid}.tmp`;
   const payload = { v: 1, ...state };
-  writeFileSync53(tmp, JSON.stringify(payload, null, 2) + `
+  writeFileSync54(tmp, JSON.stringify(payload, null, 2) + `
 `, { mode: 384 });
   renameSync34(tmp, path10);
 }
@@ -128821,7 +130203,7 @@ async function notifyOperator2(agentsDir, text, log) {
   const candidates = [];
   try {
     for (const name of readdirSync51(agentsDir).sort()) {
-      const sock = resolve68(agentsDir, name, "telegram", "gateway.sock");
+      const sock = resolve69(agentsDir, name, "telegram", "gateway.sock");
       if (existsSync127(sock))
         candidates.push({ agent: name, sock });
     }
@@ -129079,6 +130461,7 @@ registerWebdCommand(program3);
 registerHostCommand(program3);
 registerFleetHealthCommand(program3);
 registerHindsightWatchCommand(program3);
+registerHindsightBenchCommand(program3);
 registerOpenRouterWatchCommand(program3);
 registerConfigRepoCommand(program3);