switchroom 0.19.19 → 0.19.23

package/dist/host-control/main.js

@@ -19443,7 +19443,8 @@ var HindsightConfigSchema = exports_external.object({
     retain: HindsightPerOpLlmSchema.optional().describe("Per-op override for the `retain` LLM op (memory ingestion). Emits " + "`HINDSIGHT_API_RETAIN_LLM_*`. Absent → uses the global model/provider."),
     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.")
+  }).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, " + "LLM_MAX_CONCURRENT, RETAIN/CONSOLIDATION_LLM_MAX_CONCURRENT, " + "RECALL_MAX_CANDIDATES_PER_SOURCE, LINK_EXPANSION_PER_ENTITY_LIMIT, " + "LINK_EXPANSION_TIMEOUT, LLM_REASONING_EFFORT), 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).")
 });
 var 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)."),
@@ -21120,7 +21121,7 @@ function allocateAgentUid(name) {
 }
 
 // src/build-info.ts
-var VERSION = "0.19.19";
+var VERSION = "0.19.23";
 
 // src/cli/agent-config.ts
 import { join as join2 } from "node:path";
@@ -21172,6 +21173,113 @@ for (const name of SHARED_FRAGMENTS) {
   }
 }
 
+// src/litellm/timeout-budget.ts
+var LITELLM_ROUTER_MARGIN_S = 10;
+var LITELLM_TIMEOUT_TIERS = {
+  interactive: {
+    group: "gpt-oss-20b",
+    localTimeoutS: 90,
+    fallbackGroup: "gpt-oss-20b-openrouter",
+    fallbackTimeoutS: 60
+  },
+  retain: {
+    group: "gpt-oss-20b-retain",
+    localTimeoutS: 200,
+    fallbackGroup: "gpt-oss-20b-retain-openrouter",
+    fallbackTimeoutS: 90
+  },
+  consolidation: {
+    group: "gpt-oss-20b-consolidation",
+    localTimeoutS: 200,
+    fallbackGroup: "gpt-oss-20b-consolidation-openrouter",
+    fallbackTimeoutS: 90
+  }
+};
+function litellmChainSeconds(tier) {
+  assertPositive(tier.localTimeoutS, `${tier.group} localTimeoutS`);
+  if (tier.fallbackGroup === null)
+    return tier.localTimeoutS;
+  assertPositive(tier.fallbackTimeoutS, `${tier.fallbackGroup} fallbackTimeoutS`);
+  return tier.localTimeoutS + tier.fallbackTimeoutS;
+}
+function minimumClientBudgetSeconds(tier, marginS = LITELLM_ROUTER_MARGIN_S) {
+  return litellmChainSeconds(tier) + marginS;
+}
+function clientBudgetSeconds(tier, floorS = 0, marginS = LITELLM_ROUTER_MARGIN_S) {
+  return Math.max(Math.ceil(floorS), minimumClientBudgetSeconds(tier, marginS));
+}
+function assertPositive(value, label) {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(`litellm timeout budget: ${label} must be a positive number, got ${value}`);
+  }
+}
+
+// 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);
+var HINDSIGHT_DEFAULT_LINK_EXPANSION_PER_ENTITY_LIMIT = 50;
+var HINDSIGHT_DEFAULT_LINK_EXPANSION_TIMEOUT_S = 2;
+var HINDSIGHT_DEFAULT_LLM_REASONING_EFFORT = "low";
+var HINDSIGHT_DEFAULT_LLM_MAX_CONCURRENT = 4;
+var HINDSIGHT_DEFAULT_RETAIN_LLM_MAX_CONCURRENT = 1;
+var HINDSIGHT_DEFAULT_CONSOLIDATION_LLM_MAX_CONCURRENT = 1;
+var HINDSIGHT_DEFAULT_RERANKER_LOCAL_FP16 = "true";
+var HINDSIGHT_PERF_DEFAULTS_UNGATED = [
+  [
+    "HINDSIGHT_API_RECALL_MAX_CANDIDATES_PER_SOURCE",
+    String(HINDSIGHT_DEFAULT_RECALL_MAX_CANDIDATES_PER_SOURCE)
+  ],
+  [
+    "HINDSIGHT_API_LINK_EXPANSION_PER_ENTITY_LIMIT",
+    String(HINDSIGHT_DEFAULT_LINK_EXPANSION_PER_ENTITY_LIMIT)
+  ],
+  [
+    "HINDSIGHT_API_LINK_EXPANSION_TIMEOUT",
+    String(HINDSIGHT_DEFAULT_LINK_EXPANSION_TIMEOUT_S)
+  ],
+  ["HINDSIGHT_API_LLM_REASONING_EFFORT", HINDSIGHT_DEFAULT_LLM_REASONING_EFFORT]
+];
+var HINDSIGHT_PERF_DEFAULTS_GPU = [
+  ["HINDSIGHT_API_RERANKER_LOCAL_FP16", HINDSIGHT_DEFAULT_RERANKER_LOCAL_FP16]
+];
+var HINDSIGHT_PERF_DEFAULTS_LOCAL_LLM = [
+  ["HINDSIGHT_API_LLM_MAX_CONCURRENT", String(HINDSIGHT_DEFAULT_LLM_MAX_CONCURRENT)],
+  [
+    "HINDSIGHT_API_RETAIN_LLM_MAX_CONCURRENT",
+    String(HINDSIGHT_DEFAULT_RETAIN_LLM_MAX_CONCURRENT)
+  ],
+  [
+    "HINDSIGHT_API_CONSOLIDATION_LLM_MAX_CONCURRENT",
+    String(HINDSIGHT_DEFAULT_CONSOLIDATION_LLM_MAX_CONCURRENT)
+  ]
+];
+var HINDSIGHT_PERF_ENV_KEYS = new Set([
+  ...HINDSIGHT_PERF_DEFAULTS_UNGATED,
+  ...HINDSIGHT_PERF_DEFAULTS_GPU,
+  ...HINDSIGHT_PERF_DEFAULTS_LOCAL_LLM
+].map(([k]) => k));
+
+// 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.ts
 var HINDSIGHT_DEFAULT_API_PORT = 18888;
 var HINDSIGHT_DEFAULT_MCP_URL = `http://127.0.0.1:${HINDSIGHT_DEFAULT_API_PORT}/mcp/`;
@@ -21181,6 +21289,18 @@ var HINDSIGHT_IMAGE_REPO = "ghcr.io/switchroom/switchroom-hindsight";
 var HINDSIGHT_IMAGE = `${HINDSIGHT_IMAGE_REPO}:latest`;
 var HINDSIGHT_BROKER_SOCK_VOLUME = `auth-broker-${HINDSIGHT_CONSUMER_NAME}-sock`;
 var HINDSIGHT_CREDS_MIRROR_VOLUME = `consumer-creds-${HINDSIGHT_CONSUMER_NAME}`;
+var HINDSIGHT_DEFAULT_RETAIN_MAX_COMPLETION_TOKENS = 16384;
+var HINDSIGHT_RETAIN_MIN_TOKENS_PER_SECOND = 80.6;
+function hindsightRetainLlmTimeoutSeconds(maxCompletionTokens = HINDSIGHT_DEFAULT_RETAIN_MAX_COMPLETION_TOKENS, tokensPerSecond = HINDSIGHT_RETAIN_MIN_TOKENS_PER_SECOND) {
+  if (!(maxCompletionTokens > 0) || !(tokensPerSecond > 0)) {
+    throw new Error(`hindsight retain budget: maxCompletionTokens (${maxCompletionTokens}) and ` + `tokensPerSecond (${tokensPerSecond}) must both be positive`);
+  }
+  return Math.ceil(maxCompletionTokens / tokensPerSecond);
+}
+function hindsightRetainClientTimeoutSeconds() {
+  return clientBudgetSeconds(LITELLM_TIMEOUT_TIERS.retain, hindsightRetainLlmTimeoutSeconds());
+}
+var HINDSIGHT_RETAIN_CLIENT_DEADLINE_S = hindsightRetainClientTimeoutSeconds() + LITELLM_ROUTER_MARGIN_S;
 var HINDSIGHT_HEALTHCHECK_PY = 'import urllib.request,sys; sys.exit(0 if urllib.request.urlopen("http://localhost:8888/health",timeout=4).getcode()==200 else 1)';
 var HINDSIGHT_HEALTHCHECK_CMD = `python3 -c '${HINDSIGHT_HEALTHCHECK_PY}'`;
 var DOCKER_PROBE_TIMEOUT_MS = 60 * 1000;

package/dist/vault/approvals/kernel-server.js

@@ -4386,7 +4386,8 @@ var init_schema = __esm(() => {
       retain: HindsightPerOpLlmSchema.optional().describe("Per-op override for the `retain` LLM op (memory ingestion). Emits " + "`HINDSIGHT_API_RETAIN_LLM_*`. Absent → uses the global model/provider."),
       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.")
+    }).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, " + "LLM_MAX_CONCURRENT, RETAIN/CONSOLIDATION_LLM_MAX_CONCURRENT, " + "RECALL_MAX_CANDIDATES_PER_SOURCE, LINK_EXPANSION_PER_ENTITY_LIMIT, " + "LINK_EXPANSION_TIMEOUT, LLM_REASONING_EFFORT), 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)."),
@@ -19147,6 +19148,116 @@ for (const name of SHARED_FRAGMENTS) {
   }
 }
 
+// src/litellm/timeout-budget.ts
+var LITELLM_ROUTER_MARGIN_S = 10;
+var LITELLM_TIMEOUT_TIERS = {
+  interactive: {
+    group: "gpt-oss-20b",
+    localTimeoutS: 90,
+    fallbackGroup: "gpt-oss-20b-openrouter",
+    fallbackTimeoutS: 60
+  },
+  retain: {
+    group: "gpt-oss-20b-retain",
+    localTimeoutS: 200,
+    fallbackGroup: "gpt-oss-20b-retain-openrouter",
+    fallbackTimeoutS: 90
+  },
+  consolidation: {
+    group: "gpt-oss-20b-consolidation",
+    localTimeoutS: 200,
+    fallbackGroup: "gpt-oss-20b-consolidation-openrouter",
+    fallbackTimeoutS: 90
+  }
+};
+function litellmChainSeconds(tier) {
+  assertPositive(tier.localTimeoutS, `${tier.group} localTimeoutS`);
+  if (tier.fallbackGroup === null)
+    return tier.localTimeoutS;
+  assertPositive(tier.fallbackTimeoutS, `${tier.fallbackGroup} fallbackTimeoutS`);
+  return tier.localTimeoutS + tier.fallbackTimeoutS;
+}
+function minimumClientBudgetSeconds(tier, marginS = LITELLM_ROUTER_MARGIN_S) {
+  return litellmChainSeconds(tier) + marginS;
+}
+function clientBudgetSeconds(tier, floorS = 0, marginS = LITELLM_ROUTER_MARGIN_S) {
+  return Math.max(Math.ceil(floorS), minimumClientBudgetSeconds(tier, marginS));
+}
+function assertPositive(value, label) {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(`litellm timeout budget: ${label} must be a positive number, got ${value}`);
+  }
+}
+
+// src/setup/host-capabilities.ts
+init_paths();
+
+// 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);
+var HINDSIGHT_DEFAULT_LINK_EXPANSION_PER_ENTITY_LIMIT = 50;
+var HINDSIGHT_DEFAULT_LINK_EXPANSION_TIMEOUT_S = 2;
+var HINDSIGHT_DEFAULT_LLM_REASONING_EFFORT = "low";
+var HINDSIGHT_DEFAULT_LLM_MAX_CONCURRENT = 4;
+var HINDSIGHT_DEFAULT_RETAIN_LLM_MAX_CONCURRENT = 1;
+var HINDSIGHT_DEFAULT_CONSOLIDATION_LLM_MAX_CONCURRENT = 1;
+var HINDSIGHT_DEFAULT_RERANKER_LOCAL_FP16 = "true";
+var HINDSIGHT_PERF_DEFAULTS_UNGATED = [
+  [
+    "HINDSIGHT_API_RECALL_MAX_CANDIDATES_PER_SOURCE",
+    String(HINDSIGHT_DEFAULT_RECALL_MAX_CANDIDATES_PER_SOURCE)
+  ],
+  [
+    "HINDSIGHT_API_LINK_EXPANSION_PER_ENTITY_LIMIT",
+    String(HINDSIGHT_DEFAULT_LINK_EXPANSION_PER_ENTITY_LIMIT)
+  ],
+  [
+    "HINDSIGHT_API_LINK_EXPANSION_TIMEOUT",
+    String(HINDSIGHT_DEFAULT_LINK_EXPANSION_TIMEOUT_S)
+  ],
+  ["HINDSIGHT_API_LLM_REASONING_EFFORT", HINDSIGHT_DEFAULT_LLM_REASONING_EFFORT]
+];
+var HINDSIGHT_PERF_DEFAULTS_GPU = [
+  ["HINDSIGHT_API_RERANKER_LOCAL_FP16", HINDSIGHT_DEFAULT_RERANKER_LOCAL_FP16]
+];
+var HINDSIGHT_PERF_DEFAULTS_LOCAL_LLM = [
+  ["HINDSIGHT_API_LLM_MAX_CONCURRENT", String(HINDSIGHT_DEFAULT_LLM_MAX_CONCURRENT)],
+  [
+    "HINDSIGHT_API_RETAIN_LLM_MAX_CONCURRENT",
+    String(HINDSIGHT_DEFAULT_RETAIN_LLM_MAX_CONCURRENT)
+  ],
+  [
+    "HINDSIGHT_API_CONSOLIDATION_LLM_MAX_CONCURRENT",
+    String(HINDSIGHT_DEFAULT_CONSOLIDATION_LLM_MAX_CONCURRENT)
+  ]
+];
+var HINDSIGHT_PERF_ENV_KEYS = new Set([
+  ...HINDSIGHT_PERF_DEFAULTS_UNGATED,
+  ...HINDSIGHT_PERF_DEFAULTS_GPU,
+  ...HINDSIGHT_PERF_DEFAULTS_LOCAL_LLM
+].map(([k]) => k));
+
+// 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.ts
 var HINDSIGHT_DEFAULT_API_PORT = 18888;
 var HINDSIGHT_DEFAULT_MCP_URL = `http://127.0.0.1:${HINDSIGHT_DEFAULT_API_PORT}/mcp/`;
@@ -19156,6 +19267,18 @@ var HINDSIGHT_IMAGE_REPO = "ghcr.io/switchroom/switchroom-hindsight";
 var HINDSIGHT_IMAGE = `${HINDSIGHT_IMAGE_REPO}:latest`;
 var HINDSIGHT_BROKER_SOCK_VOLUME = `auth-broker-${HINDSIGHT_CONSUMER_NAME}-sock`;
 var HINDSIGHT_CREDS_MIRROR_VOLUME = `consumer-creds-${HINDSIGHT_CONSUMER_NAME}`;
+var HINDSIGHT_DEFAULT_RETAIN_MAX_COMPLETION_TOKENS = 16384;
+var HINDSIGHT_RETAIN_MIN_TOKENS_PER_SECOND = 80.6;
+function hindsightRetainLlmTimeoutSeconds(maxCompletionTokens = HINDSIGHT_DEFAULT_RETAIN_MAX_COMPLETION_TOKENS, tokensPerSecond = HINDSIGHT_RETAIN_MIN_TOKENS_PER_SECOND) {
+  if (!(maxCompletionTokens > 0) || !(tokensPerSecond > 0)) {
+    throw new Error(`hindsight retain budget: maxCompletionTokens (${maxCompletionTokens}) and ` + `tokensPerSecond (${tokensPerSecond}) must both be positive`);
+  }
+  return Math.ceil(maxCompletionTokens / tokensPerSecond);
+}
+function hindsightRetainClientTimeoutSeconds() {
+  return clientBudgetSeconds(LITELLM_TIMEOUT_TIERS.retain, hindsightRetainLlmTimeoutSeconds());
+}
+var HINDSIGHT_RETAIN_CLIENT_DEADLINE_S = hindsightRetainClientTimeoutSeconds() + LITELLM_ROUTER_MARGIN_S;
 var HINDSIGHT_HEALTHCHECK_PY = 'import urllib.request,sys; sys.exit(0 if urllib.request.urlopen("http://localhost:8888/health",timeout=4).getcode()==200 else 1)';
 var HINDSIGHT_HEALTHCHECK_CMD = `python3 -c '${HINDSIGHT_HEALTHCHECK_PY}'`;
 var DOCKER_PROBE_TIMEOUT_MS = 60 * 1000;
@@ -19247,9 +19370,6 @@ var DOCKER_HOOKS_PATH = `${DOCKER_TELEGRAM_PLUGIN_PATH}/hooks`;
 init_merge();
 init_timezone();
 
-// src/setup/host-capabilities.ts
-init_paths();
-
 // src/vault/grants-db-path.ts
 var GRANTS_DB_DIRNAME = "vault-broker";
 var GRANTS_DB_FILENAME = "vault-grants.db";

package/dist/vault/broker/server.js

@@ -4386,7 +4386,8 @@ var init_schema = __esm(() => {
       retain: HindsightPerOpLlmSchema.optional().describe("Per-op override for the `retain` LLM op (memory ingestion). Emits " + "`HINDSIGHT_API_RETAIN_LLM_*`. Absent → uses the global model/provider."),
       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.")
+    }).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, " + "LLM_MAX_CONCURRENT, RETAIN/CONSOLIDATION_LLM_MAX_CONCURRENT, " + "RECALL_MAX_CANDIDATES_PER_SOURCE, LINK_EXPANSION_PER_ENTITY_LIMIT, " + "LINK_EXPANSION_TIMEOUT, LLM_REASONING_EFFORT), 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)."),
@@ -18820,6 +18821,116 @@ for (const name of SHARED_FRAGMENTS) {
   }
 }
 
+// src/litellm/timeout-budget.ts
+var LITELLM_ROUTER_MARGIN_S = 10;
+var LITELLM_TIMEOUT_TIERS = {
+  interactive: {
+    group: "gpt-oss-20b",
+    localTimeoutS: 90,
+    fallbackGroup: "gpt-oss-20b-openrouter",
+    fallbackTimeoutS: 60
+  },
+  retain: {
+    group: "gpt-oss-20b-retain",
+    localTimeoutS: 200,
+    fallbackGroup: "gpt-oss-20b-retain-openrouter",
+    fallbackTimeoutS: 90
+  },
+  consolidation: {
+    group: "gpt-oss-20b-consolidation",
+    localTimeoutS: 200,
+    fallbackGroup: "gpt-oss-20b-consolidation-openrouter",
+    fallbackTimeoutS: 90
+  }
+};
+function litellmChainSeconds(tier) {
+  assertPositive(tier.localTimeoutS, `${tier.group} localTimeoutS`);
+  if (tier.fallbackGroup === null)
+    return tier.localTimeoutS;
+  assertPositive(tier.fallbackTimeoutS, `${tier.fallbackGroup} fallbackTimeoutS`);
+  return tier.localTimeoutS + tier.fallbackTimeoutS;
+}
+function minimumClientBudgetSeconds(tier, marginS = LITELLM_ROUTER_MARGIN_S) {
+  return litellmChainSeconds(tier) + marginS;
+}
+function clientBudgetSeconds(tier, floorS = 0, marginS = LITELLM_ROUTER_MARGIN_S) {
+  return Math.max(Math.ceil(floorS), minimumClientBudgetSeconds(tier, marginS));
+}
+function assertPositive(value, label) {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(`litellm timeout budget: ${label} must be a positive number, got ${value}`);
+  }
+}
+
+// src/setup/host-capabilities.ts
+init_paths();
+
+// 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);
+var HINDSIGHT_DEFAULT_LINK_EXPANSION_PER_ENTITY_LIMIT = 50;
+var HINDSIGHT_DEFAULT_LINK_EXPANSION_TIMEOUT_S = 2;
+var HINDSIGHT_DEFAULT_LLM_REASONING_EFFORT = "low";
+var HINDSIGHT_DEFAULT_LLM_MAX_CONCURRENT = 4;
+var HINDSIGHT_DEFAULT_RETAIN_LLM_MAX_CONCURRENT = 1;
+var HINDSIGHT_DEFAULT_CONSOLIDATION_LLM_MAX_CONCURRENT = 1;
+var HINDSIGHT_DEFAULT_RERANKER_LOCAL_FP16 = "true";
+var HINDSIGHT_PERF_DEFAULTS_UNGATED = [
+  [
+    "HINDSIGHT_API_RECALL_MAX_CANDIDATES_PER_SOURCE",
+    String(HINDSIGHT_DEFAULT_RECALL_MAX_CANDIDATES_PER_SOURCE)
+  ],
+  [
+    "HINDSIGHT_API_LINK_EXPANSION_PER_ENTITY_LIMIT",
+    String(HINDSIGHT_DEFAULT_LINK_EXPANSION_PER_ENTITY_LIMIT)
+  ],
+  [
+    "HINDSIGHT_API_LINK_EXPANSION_TIMEOUT",
+    String(HINDSIGHT_DEFAULT_LINK_EXPANSION_TIMEOUT_S)
+  ],
+  ["HINDSIGHT_API_LLM_REASONING_EFFORT", HINDSIGHT_DEFAULT_LLM_REASONING_EFFORT]
+];
+var HINDSIGHT_PERF_DEFAULTS_GPU = [
+  ["HINDSIGHT_API_RERANKER_LOCAL_FP16", HINDSIGHT_DEFAULT_RERANKER_LOCAL_FP16]
+];
+var HINDSIGHT_PERF_DEFAULTS_LOCAL_LLM = [
+  ["HINDSIGHT_API_LLM_MAX_CONCURRENT", String(HINDSIGHT_DEFAULT_LLM_MAX_CONCURRENT)],
+  [
+    "HINDSIGHT_API_RETAIN_LLM_MAX_CONCURRENT",
+    String(HINDSIGHT_DEFAULT_RETAIN_LLM_MAX_CONCURRENT)
+  ],
+  [
+    "HINDSIGHT_API_CONSOLIDATION_LLM_MAX_CONCURRENT",
+    String(HINDSIGHT_DEFAULT_CONSOLIDATION_LLM_MAX_CONCURRENT)
+  ]
+];
+var HINDSIGHT_PERF_ENV_KEYS = new Set([
+  ...HINDSIGHT_PERF_DEFAULTS_UNGATED,
+  ...HINDSIGHT_PERF_DEFAULTS_GPU,
+  ...HINDSIGHT_PERF_DEFAULTS_LOCAL_LLM
+].map(([k]) => k));
+
+// 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.ts
 var HINDSIGHT_DEFAULT_API_PORT = 18888;
 var HINDSIGHT_DEFAULT_MCP_URL = `http://127.0.0.1:${HINDSIGHT_DEFAULT_API_PORT}/mcp/`;
@@ -18829,6 +18940,18 @@ var HINDSIGHT_IMAGE_REPO = "ghcr.io/switchroom/switchroom-hindsight";
 var HINDSIGHT_IMAGE = `${HINDSIGHT_IMAGE_REPO}:latest`;
 var HINDSIGHT_BROKER_SOCK_VOLUME = `auth-broker-${HINDSIGHT_CONSUMER_NAME}-sock`;
 var HINDSIGHT_CREDS_MIRROR_VOLUME = `consumer-creds-${HINDSIGHT_CONSUMER_NAME}`;
+var HINDSIGHT_DEFAULT_RETAIN_MAX_COMPLETION_TOKENS = 16384;
+var HINDSIGHT_RETAIN_MIN_TOKENS_PER_SECOND = 80.6;
+function hindsightRetainLlmTimeoutSeconds(maxCompletionTokens = HINDSIGHT_DEFAULT_RETAIN_MAX_COMPLETION_TOKENS, tokensPerSecond = HINDSIGHT_RETAIN_MIN_TOKENS_PER_SECOND) {
+  if (!(maxCompletionTokens > 0) || !(tokensPerSecond > 0)) {
+    throw new Error(`hindsight retain budget: maxCompletionTokens (${maxCompletionTokens}) and ` + `tokensPerSecond (${tokensPerSecond}) must both be positive`);
+  }
+  return Math.ceil(maxCompletionTokens / tokensPerSecond);
+}
+function hindsightRetainClientTimeoutSeconds() {
+  return clientBudgetSeconds(LITELLM_TIMEOUT_TIERS.retain, hindsightRetainLlmTimeoutSeconds());
+}
+var HINDSIGHT_RETAIN_CLIENT_DEADLINE_S = hindsightRetainClientTimeoutSeconds() + LITELLM_ROUTER_MARGIN_S;
 var HINDSIGHT_HEALTHCHECK_PY = 'import urllib.request,sys; sys.exit(0 if urllib.request.urlopen("http://localhost:8888/health",timeout=4).getcode()==200 else 1)';
 var HINDSIGHT_HEALTHCHECK_CMD = `python3 -c '${HINDSIGHT_HEALTHCHECK_PY}'`;
 var DOCKER_PROBE_TIMEOUT_MS = 60 * 1000;
@@ -19675,9 +19798,6 @@ var DOCKER_HOOKS_PATH = `${DOCKER_TELEGRAM_PLUGIN_PATH}/hooks`;
 init_merge();
 init_timezone();
 
-// src/setup/host-capabilities.ts
-init_paths();
-
 // src/vault/grants-db-path.ts
 import * as os from "node:os";
 import * as path from "node:path";

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.19",
+  "version": "0.19.23",
   "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": {
@@ -24,22 +24,25 @@
     "build": "node scripts/build.mjs",
     "build:cli": "node scripts/build.mjs && bun build --compile --target=bun-linux-x64 --minify bin/switchroom.ts --outfile switchroom-linux-amd64",
     "pretest": "npm run build",
-    "test": "vitest run && bun test telegram-plugin/tests/catch-all-forwarded-history.test.ts telegram-plugin/tests/history.test.ts telegram-plugin/tests/cross-turn-card-gate.test.ts telegram-plugin/tests/emission-authority-open-gate.test.ts telegram-plugin/tests/emission-authority-ping-gate.test.ts telegram-plugin/tests/emission-authority-card-drain-gate.test.ts telegram-plugin/tests/per-topic-current-turn.test.ts telegram-plugin/tests/history-reaper.test.ts telegram-plugin/tests/ipc-server-client.test.ts telegram-plugin/tests/ipc-server-race.test.ts telegram-plugin/tests/ipc-server-query-pending-permission.test.ts telegram-plugin/tests/ipc-server-check-pre-approved.test.ts telegram-plugin/tests/gateway-bridge.test.ts telegram-plugin/tests/gateway-startup-mutex.test.ts telegram-plugin/tests/gateway-clean-shutdown-marker.test.ts telegram-plugin/tests/boot-card-dedupe.test.ts telegram-plugin/tests/boot-card-reason.test.ts telegram-plugin/tests/progress-update.test.ts telegram-plugin/tests/quota-cache.test.ts telegram-plugin/tests/unhandled-rejection-policy.test.ts telegram-plugin/tests/registry-turns.test.ts telegram-plugin/registry/subagents.test.ts telegram-plugin/registry/subagents-bugs.test.ts telegram-plugin/tests/subagent-watcher-parent-turn-key.test.ts telegram-plugin/tests/subagent-nested-dispatch.test.ts telegram-plugin/tests/nested-worker-visibility-harness.test.ts telegram-plugin/tests/turns-writer.test.ts telegram-plugin/tests/resume-inbound-builder.test.ts telegram-plugin/registry/api-registry.test.ts telegram-plugin/registry/turns-schema.test.ts telegram-plugin/tests/idle-footer-wiring.test.ts telegram-plugin/tests/subagent-tracker-hooks.test.ts telegram-plugin/tests/gateway-update-placeholder-dispatch.test.ts telegram-plugin/tests/status-query-telemetry.test.ts telegram-plugin/tests/reaction-trigger.test.ts telegram-plugin/tests/reaction-trigger-flow.test.ts telegram-plugin/gateway/webhook-ingest-server.test.ts telegram-plugin/tests/skill-proposal-card.test.ts",
+    "test": "vitest run && bun test telegram-plugin/tests/agent-state-dir-preload.test.ts telegram-plugin/tests/catch-all-forwarded-history.test.ts telegram-plugin/tests/history.test.ts telegram-plugin/tests/cross-turn-card-gate.test.ts telegram-plugin/tests/emission-authority-open-gate.test.ts telegram-plugin/tests/emission-authority-ping-gate.test.ts telegram-plugin/tests/emission-authority-card-drain-gate.test.ts telegram-plugin/tests/per-topic-current-turn.test.ts telegram-plugin/tests/history-reaper.test.ts telegram-plugin/tests/ipc-server-client.test.ts telegram-plugin/tests/ipc-server-race.test.ts telegram-plugin/tests/ipc-server-query-pending-permission.test.ts telegram-plugin/tests/ipc-server-check-pre-approved.test.ts telegram-plugin/tests/gateway-bridge.test.ts telegram-plugin/tests/gateway-startup-mutex.test.ts telegram-plugin/tests/gateway-clean-shutdown-marker.test.ts telegram-plugin/tests/boot-card-dedupe.test.ts telegram-plugin/tests/boot-card-reason.test.ts telegram-plugin/tests/progress-update.test.ts telegram-plugin/tests/quota-cache.test.ts telegram-plugin/tests/unhandled-rejection-policy.test.ts telegram-plugin/tests/registry-turns.test.ts telegram-plugin/registry/subagents.test.ts telegram-plugin/registry/subagents-bugs.test.ts telegram-plugin/tests/subagent-watcher-parent-turn-key.test.ts telegram-plugin/tests/subagent-nested-dispatch.test.ts telegram-plugin/tests/nested-worker-visibility-harness.test.ts telegram-plugin/tests/turns-writer.test.ts telegram-plugin/tests/resume-inbound-builder.test.ts telegram-plugin/registry/api-registry.test.ts telegram-plugin/registry/turns-schema.test.ts telegram-plugin/tests/idle-footer-wiring.test.ts telegram-plugin/tests/subagent-tracker-hooks.test.ts telegram-plugin/tests/gateway-update-placeholder-dispatch.test.ts telegram-plugin/tests/status-query-telemetry.test.ts telegram-plugin/tests/reaction-trigger.test.ts telegram-plugin/tests/reaction-trigger-flow.test.ts telegram-plugin/gateway/webhook-ingest-server.test.ts telegram-plugin/tests/skill-proposal-card.test.ts",
     "test:vitest": "vitest run",
-    "test:bun": "bun test telegram-plugin/tests/catch-all-forwarded-history.test.ts src/vault/grants.test.ts src/vault/grants-db.test.ts src/vault/write-grants.test.ts src/vault/broker/server-grants.test.ts src/vault/broker/server-write-grants.test.ts src/vault/broker/server-scope-persist.test.ts src/vault/broker/server-tokenless-scope.test.ts src/vault/broker/server-mint-grant-passphrase-attest.test.ts src/vault/broker/server-passphrase-attest.test.ts src/vault/broker/server-mint-grant-posture-attest.test.ts src/vault/broker/server-admin-only-keys.test.ts src/vault/broker/client-token.test.ts src/vault/broker/server-unlock.test.ts src/vault/broker/auto-unlock.test.ts src/vault/broker/drift-detection.test.ts tests/vault-broker-passphrase.test.ts src/cli/vault-get-broker.test.ts src/vault/resolver-via-broker.test.ts src/vault/broker/scope.test.ts src/vault/broker/server.test.ts src/litellm/provision-apply-e2e.test.ts src/drive/disconnect.test.ts src/drive/grants.test.ts src/drive/oauth.test.ts src/drive/onboarding.test.ts src/drive/reconciler.test.ts src/drive/vault-slots.test.ts src/drive/wrapper.test.ts src/vault/approvals/kernel.test.ts src/vault/approvals/approval-origin.test.ts src/vault/approvals/self-approval-bypass.test.ts src/vault/approvals/schema-idempotent.test.ts src/vault/broker/server-approvals.test.ts telegram-plugin/tests/boot-probes.test.ts telegram-plugin/tests/boot-version-string.test.ts telegram-plugin/tests/history.test.ts telegram-plugin/tests/cross-turn-card-gate.test.ts telegram-plugin/tests/emission-authority-open-gate.test.ts telegram-plugin/tests/emission-authority-ping-gate.test.ts telegram-plugin/tests/emission-authority-card-drain-gate.test.ts telegram-plugin/tests/per-topic-current-turn.test.ts telegram-plugin/tests/history-reaper.test.ts telegram-plugin/tests/ipc-server-client.test.ts telegram-plugin/tests/ipc-server-race.test.ts telegram-plugin/tests/ipc-server-query-pending-permission.test.ts telegram-plugin/tests/ipc-server-check-pre-approved.test.ts telegram-plugin/tests/gateway-bridge.test.ts telegram-plugin/tests/gateway-startup-mutex.test.ts telegram-plugin/tests/gateway-clean-shutdown-marker.test.ts telegram-plugin/tests/boot-card-dedupe.test.ts telegram-plugin/tests/boot-card-reason.test.ts telegram-plugin/tests/progress-update.test.ts telegram-plugin/tests/quota-cache.test.ts telegram-plugin/tests/silent-reply-guard.test.ts telegram-plugin/tests/unhandled-rejection-policy.test.ts telegram-plugin/tests/registry-turns.test.ts telegram-plugin/registry/subagents.test.ts telegram-plugin/registry/subagents-bugs.test.ts telegram-plugin/tests/subagent-watcher-parent-turn-key.test.ts telegram-plugin/tests/subagent-nested-dispatch.test.ts telegram-plugin/tests/nested-worker-visibility-harness.test.ts telegram-plugin/tests/turns-writer.test.ts telegram-plugin/tests/resume-inbound-builder.test.ts telegram-plugin/tests/subagent-tracker-hooks.test.ts telegram-plugin/tests/resolve-calling-subagent.test.ts telegram-plugin/tests/gateway-update-placeholder-dispatch.test.ts telegram-plugin/tests/status-query-telemetry.test.ts telegram-plugin/tests/reaction-trigger.test.ts telegram-plugin/tests/reaction-trigger-flow.test.ts telegram-plugin/tests/subagent-watcher-workflow-visibility.test.ts telegram-plugin/uat/load-env.test.ts telegram-plugin/uat/feed-matcher.test.ts telegram-plugin/uat/uat-driver.test.ts telegram-plugin/gateway/webhook-ingest-server.test.ts telegram-plugin/tests/skill-proposal-card.test.ts",
+    "test:bun": "bun test telegram-plugin/tests/agent-state-dir-preload.test.ts telegram-plugin/tests/catch-all-forwarded-history.test.ts src/vault/grants.test.ts src/vault/grants-db.test.ts src/vault/write-grants.test.ts src/vault/broker/server-grants.test.ts src/vault/broker/server-write-grants.test.ts src/vault/broker/server-scope-persist.test.ts src/vault/broker/server-tokenless-scope.test.ts src/vault/broker/server-mint-grant-passphrase-attest.test.ts src/vault/broker/server-passphrase-attest.test.ts src/vault/broker/server-mint-grant-posture-attest.test.ts src/vault/broker/server-admin-only-keys.test.ts src/vault/broker/client-token.test.ts src/vault/broker/server-unlock.test.ts src/vault/broker/auto-unlock.test.ts src/vault/broker/drift-detection.test.ts tests/vault-broker-passphrase.test.ts src/cli/vault-get-broker.test.ts src/vault/resolver-via-broker.test.ts src/vault/broker/scope.test.ts src/vault/broker/server.test.ts src/litellm/provision-apply-e2e.test.ts src/drive/disconnect.test.ts src/drive/grants.test.ts src/drive/oauth.test.ts src/drive/onboarding.test.ts src/drive/reconciler.test.ts src/drive/vault-slots.test.ts src/drive/wrapper.test.ts src/vault/approvals/kernel.test.ts src/vault/approvals/approval-origin.test.ts src/vault/approvals/self-approval-bypass.test.ts src/vault/approvals/schema-idempotent.test.ts src/vault/broker/server-approvals.test.ts telegram-plugin/tests/boot-probes.test.ts telegram-plugin/tests/boot-version-string.test.ts telegram-plugin/tests/history.test.ts telegram-plugin/tests/cross-turn-card-gate.test.ts telegram-plugin/tests/emission-authority-open-gate.test.ts telegram-plugin/tests/emission-authority-ping-gate.test.ts telegram-plugin/tests/emission-authority-card-drain-gate.test.ts telegram-plugin/tests/per-topic-current-turn.test.ts telegram-plugin/tests/history-reaper.test.ts telegram-plugin/tests/ipc-server-client.test.ts telegram-plugin/tests/ipc-server-race.test.ts telegram-plugin/tests/ipc-server-query-pending-permission.test.ts telegram-plugin/tests/ipc-server-check-pre-approved.test.ts telegram-plugin/tests/gateway-bridge.test.ts telegram-plugin/tests/gateway-startup-mutex.test.ts telegram-plugin/tests/gateway-clean-shutdown-marker.test.ts telegram-plugin/tests/boot-card-dedupe.test.ts telegram-plugin/tests/boot-card-reason.test.ts telegram-plugin/tests/progress-update.test.ts telegram-plugin/tests/quota-cache.test.ts telegram-plugin/tests/silent-reply-guard.test.ts telegram-plugin/tests/unhandled-rejection-policy.test.ts telegram-plugin/tests/registry-turns.test.ts telegram-plugin/registry/subagents.test.ts telegram-plugin/registry/subagents-bugs.test.ts telegram-plugin/tests/subagent-watcher-parent-turn-key.test.ts telegram-plugin/tests/subagent-nested-dispatch.test.ts telegram-plugin/tests/nested-worker-visibility-harness.test.ts telegram-plugin/tests/turns-writer.test.ts telegram-plugin/tests/resume-inbound-builder.test.ts telegram-plugin/tests/subagent-tracker-hooks.test.ts telegram-plugin/tests/resolve-calling-subagent.test.ts telegram-plugin/tests/gateway-update-placeholder-dispatch.test.ts telegram-plugin/tests/status-query-telemetry.test.ts telegram-plugin/tests/reaction-trigger.test.ts telegram-plugin/tests/reaction-trigger-flow.test.ts telegram-plugin/tests/subagent-watcher-workflow-visibility.test.ts telegram-plugin/uat/load-env.test.ts telegram-plugin/uat/feed-matcher.test.ts telegram-plugin/uat/uat-driver.test.ts telegram-plugin/gateway/webhook-ingest-server.test.ts telegram-plugin/tests/skill-proposal-card.test.ts",
     "test:watch": "vitest",
-    "lint": "tsc --noEmit && node scripts/check-plugin-references.mjs && bash scripts/check-bot-api-wrapping.sh && node scripts/check-bun-test-imports.mjs && node scripts/check-no-pii-secrets.mjs && node scripts/check-vault-test-hermeticity.mjs && node scripts/check-auth-test-hermeticity.mjs && node scripts/check-no-broadcast-delivery.mjs && node scripts/check-stale-tool-descriptions.mjs && node scripts/check-mcp-instructions-budget.mjs && node scripts/check-web-subscription-honest.mjs && node scripts/check-no-unpinned-npx-playwright.mjs && node scripts/check-gateway-line-ratchet.mjs && node scripts/check-litellm-config-guard.mjs",
+    "lint": "tsc --noEmit && node scripts/check-plugin-references.mjs && bash scripts/check-bot-api-wrapping.sh && node scripts/check-bun-test-imports.mjs && node scripts/check-bun-module-mock-scope.mjs && node scripts/check-no-pii-secrets.mjs && node scripts/check-vault-test-hermeticity.mjs && node scripts/check-auth-test-hermeticity.mjs && node scripts/check-agent-state-dir-hermeticity.mjs && node scripts/check-no-broadcast-delivery.mjs && node scripts/check-stale-tool-descriptions.mjs && node scripts/check-mcp-instructions-budget.mjs && node scripts/check-web-subscription-honest.mjs && node scripts/check-no-unpinned-npx-playwright.mjs && node scripts/check-gateway-line-ratchet.mjs && node scripts/check-litellm-config-guard.mjs && node scripts/check-release-asset-names.mjs",
     "lint:tsc": "tsc --noEmit",
     "lint:plugin-references": "node scripts/check-plugin-references.mjs",
     "lint:bot-api-wrapping": "bash scripts/check-bot-api-wrapping.sh",
     "lint:bun-test-imports": "node scripts/check-bun-test-imports.mjs",
+    "lint:bun-module-mock-scope": "node scripts/check-bun-module-mock-scope.mjs",
     "lint:no-pii": "node scripts/check-no-pii-secrets.mjs",
     "lint:auth-test-hermeticity": "node scripts/check-auth-test-hermeticity.mjs",
+    "lint:agent-state-dir-hermeticity": "node scripts/check-agent-state-dir-hermeticity.mjs",
     "lint:web-subscription-honest": "node scripts/check-web-subscription-honest.mjs",
     "lint:no-broadcast-delivery": "node scripts/check-no-broadcast-delivery.mjs",
     "lint:gateway-line-ratchet": "node scripts/check-gateway-line-ratchet.mjs",
     "lint:mcp-instructions-budget": "node scripts/check-mcp-instructions-budget.mjs",
     "lint:litellm-config-guard": "node scripts/check-litellm-config-guard.mjs",
+    "lint:release-asset-contract": "node scripts/check-release-asset-names.mjs",
     "prepublishOnly": "npm run build && npm run lint && npm test"
   },
   "dependencies": {

package/profiles/_base/start.sh.hbs

@@ -458,6 +458,107 @@ x-litellm-tags: agent:$SWITCHROOM_AGENT_NAME,profile:${SWITCHROOM_AGENT_PROFILE:
   fi
 {{/if}}
 
+{{#if hindsightEnabled}}
+  # 5) hindsight backlog drain — the memory queue's only real consumer.
+  #
+  #    WHY THIS EXISTS. `pending-retains` is written whenever a retain
+  #    fails, but before this the ONLY automatic thing that drained it was
+  #    the SessionStart hook (`session_start.py`), which runs once per
+  #    session boot under a hard ~9s latency budget against work measured
+  #    at 85-280s per entry. So an agent that simply stays up never drained
+  #    at all: on this fleet 8 of 11 agents had not drained a single entry
+  #    and the queue reached 1,060 files. A memory sitting in that queue is
+  #    a memory the agent cannot recall — the job this feature exists for.
+  #
+  #    A sidecar, not a cron entry: cron fires cost a model turn and depend
+  #    on the agent remembering to keep the entry. This is a deterministic
+  #    mechanism — it runs because the container is up, needs no LLM turn of
+  #    its own, and cannot be prompted away.
+  #
+  #    SERIALISED. `flock -n` on a per-agent lockfile makes overlapping runs
+  #    impossible: a run that overshoots the interval causes the next tick to
+  #    SKIP, never to stack. The lock path is deliberately the one the
+  #    out-of-band recovery tooling also takes, so a manual sweep and this
+  #    loop mutually exclude instead of double-processing an entry.
+  #
+  #    LANE-RESPECTING. Retain extraction is served by a small fixed pool of
+  #    LLM lanes (4 on this fleet, 2 boxes x 2 slots) SHARED with live
+  #    retains, reflect and consolidation, already near saturation. So:
+  #    `HINDSIGHT_DRAIN_CONCURRENCY` is left at its default of 1 (one
+  #    in-flight POST per agent — do not raise it here), `drain_pending`'s
+  #    own inter-retain sleep and p95 backoff still apply, and the first
+  #    tick is delayed by a per-agent offset derived from the agent NAME so
+  #    the fleet does not all wake together. The offset is a `cksum` of the
+  #    name modulo the interval: deterministic (same agent, same offset,
+  #    every boot) and evenly spread, with no shared coordinator.
+  #    HONEST LIMIT: N agents x 1 lane still exceeds 4 lanes when every
+  #    agent has a backlog. The offset spreads the START times; it does not
+  #    cap fleet-wide demand. Sustained oversubscription is absorbed by the
+  #    p95 backoff, and the real fix is more lanes.
+  #
+  #    WHY NO `HINDSIGHT_DRAIN_BACKLOG_TIMEOUT` HERE, given the measurement.
+  #    A host-side stopgap measured, on the SHIPPED defaults:
+  #      timeout=310 conc=1, busy lane  ->  drained 0 of 2
+  #      timeout=310 conc=3, FREE lane  ->  drained 0 of 3, stalled
+  #      timeout=900 conc=1, free lane  ->  drained 5 of 5
+  #    It failed on an IDLE lane, so scheduling and contention were never the
+  #    whole story. The reading that matters is the third row's concurrency,
+  #    not its timeout: raising concurrency made it WORSE, which is why 1 is
+  #    the value above and is not a knob this sidecar exposes.
+  #    The timeout is deliberately left DERIVED rather than pinned at 900.
+  #    `_backlog_timeout()` defaults to `retain_client_deadline()` and the
+  #    content bound is sized against that same number — they must stay one
+  #    number, and hard-coding 900 here would silently unpick that. What
+  #    those runs actually measured was the bound consuming ~100% of the
+  #    deadline, so a maximally-sized part could never finish; that is fixed
+  #    at its root in #3693 (the bound is now a FRACTION of the deadline),
+  #    which brings a max part to 202s inside a 310s deadline. Entries
+  #    already queued ABOVE the current bound are recovered by re-splitting
+  #    them, not by waiting longer. An operator who still wants a longer
+  #    deadline moves HINDSIGHT_RETAIN_CLIENT_DEADLINE_S, which moves both.
+  #
+  #    Failure is never terminal: the drain exits non-zero only when it
+  #    promoted entries to `.dead`, and the loop below ignores the status
+  #    and waits for the next tick. `--backlog` reads api_url/token/bank
+  #    from each queue ENTRY, so this sidecar needs no HINDSIGHT_* env
+  #    (those are exported later, in the inner pass) — only $HOME, to find
+  #    the queue.
+  #
+  #    Kill switch: SWITCHROOM_HINDSIGHT_DRAIN=0 at the container level.
+  #    Interval: SWITCHROOM_HINDSIGHT_DRAIN_INTERVAL_S (default 900s).
+  _hs_drain_script="{{agentDir}}/.claude/plugins/hindsight-memory/scripts/drain_pending.py"
+  if [ "$SWITCHROOM_HINDSIGHT_DRAIN" != "0" ] \
+     && [ -f "$_hs_drain_script" ] \
+     && command -v python3 >/dev/null 2>&1 \
+     && command -v flock >/dev/null 2>&1; then
+    _switchroom_hindsight_drain_loop() {
+      local _script="$1"
+      local _interval="${SWITCHROOM_HINDSIGHT_DRAIN_INTERVAL_S:-900}"
+      # Reject a non-numeric or too-eager interval rather than busy-looping
+      # against the LLM lane. 60s is the floor.
+      case "$_interval" in ''|*[!0-9]*) _interval=900 ;; esac
+      [ "$_interval" -lt 60 ] && _interval=60
+      local _lock="$HOME/.hindsight/drain.lock"
+      mkdir -p "$HOME/.hindsight" 2>/dev/null || true
+      # Deterministic per-agent phase offset (see the note above).
+      local _offset=0
+      if command -v cksum >/dev/null 2>&1; then
+        _offset=$(( $(printf '%s' "{{name}}" | cksum | cut -d' ' -f1) % _interval ))
+      fi
+      echo "[hindsight-drain] starting: interval=${_interval}s offset=${_offset}s lock=${_lock}"
+      sleep "$_offset"
+      while true; do
+        # -n: if a drain (ours or an operator sweep) already holds the
+        # lock, skip this tick entirely instead of queueing behind it.
+        flock -n "$_lock" python3 "$_script" --backlog || true
+        sleep "$_interval"
+      done
+    }
+    _switchroom_supervise hindsight-drain /var/log/switchroom/hindsight-drain.log \
+      _switchroom_hindsight_drain_loop "$_hs_drain_script" &
+  fi
+{{/if}}
+
   export SWITCHROOM_DOCKER_TMUX_INNER=1
   exec tmux -L "switchroom-{{name}}" \
     new-session -A -s "{{name}}" -x 400 -y 50 \