switchroom 0.19.39 → 0.19.40

package/dist/cli/switchroom.js

@@ -2120,7 +2120,7 @@ var init_esm = __esm(() => {
 });
 
 // src/build-info.ts
-var VERSION = "0.19.39", COMMIT_SHA = "4aff2bdd";
+var VERSION = "0.19.40", COMMIT_SHA = "89286b22";
 
 // src/cli/resolve-version.ts
 import { existsSync, readFileSync } from "node:fs";
@@ -13593,7 +13593,7 @@ function resolveObservationScope(configured, env2 = process.env) {
     return classifyObservationScope(configured);
   return classifyObservationScope(env2[OBSERVATION_SCOPES_ENV]);
 }
-var OBSERVATION_SCOPES, OBSERVATION_SCOPES_ENV = "HINDSIGHT_OBSERVATION_SCOPES";
+var OBSERVATION_SCOPES, OBSERVATION_SCOPES_ENV = "HINDSIGHT_OBSERVATION_SCOPES", OBSERVATION_SCOPE_STRATEGIES;
 var init_observation_scopes = __esm(() => {
   OBSERVATION_SCOPES = [
     "per_tag",
@@ -13601,13 +13601,19 @@ var init_observation_scopes = __esm(() => {
     "all_combinations",
     "shared"
   ];
+  OBSERVATION_SCOPE_STRATEGIES = [
+    "curated",
+    "shared",
+    "combined",
+    "off"
+  ];
 });
 
 // src/config/schema.ts
 function isValidTimezone(value) {
   return TIMEZONE_REGEX.test(value);
 }
-var CodeRepoEntrySchema, AgentBindMountSchema, HttpDiffPollSchema, PollSpecSchema, TelegramMessageActionSchema, WebhookActionSchema, ActionSpecSchema, ScheduleEntrySchema, AgentSoulSchema, AgentToolsSchema, ObservationScopesSchema, AgentMemorySchema, HookEntrySchema, AgentHooksSchema, SubagentSchema, SessionSchema, SessionContinuitySchema, webhookDispatchRule, TelegramChannelSchema, ChannelsSchema, TIMEZONE_REGEX, ApproverIdSchema, GoogleWorkspaceTierSchema, GoogleWorkspaceConfigSchema, LiteLLMConfigSchema, HindsightPerOpLlmSchema, HindsightConfigSchema, MicrosoftWorkspaceConfigSchema, NotionWorkspaceConfigSchema, AgentGoogleWorkspaceConfigSchema, MicrosoftAccountEmailSchema, MicrosoftToolTokenSchema, MicrosoftAccountBindingSchema, AgentMicrosoftWorkspaceConfigSchema, AgentNotionWorkspaceConfigSchema, ReactionsSchema, ReactionDispatchSchema, releaseBlockFields, ReleaseBlock, RootReleaseBlock, NetworkIsolationSchema, servesField, knowsField, profileFields, ProfileSchema, _omitExtends, defaultsFields, AgentDefaultsSchema, DEFAULT_PROFILE = "default", AgentSchema, TelegramConfigSchema, MemoryBackendConfigSchema, VaultConfigSchema, QuotaConfigSchema, AutoReleaseCheckSchema, HostControlConfigSchema, WebServiceConfigSchema, FleetHealthConfigSchema, HostdConfigSchema, CronEgressSchema, CronConfigSchema, UserSchema, SwitchroomConfigSchema;
+var CodeRepoEntrySchema, AgentBindMountSchema, HttpDiffPollSchema, PollSpecSchema, TelegramMessageActionSchema, WebhookActionSchema, ActionSpecSchema, ScheduleEntrySchema, AgentSoulSchema, AgentToolsSchema, ObservationScopesSchema, ObservationScopeStrategySchema, AgentMemorySchema, HookEntrySchema, AgentHooksSchema, SubagentSchema, SessionSchema, SessionContinuitySchema, webhookDispatchRule, TelegramChannelSchema, ChannelsSchema, TIMEZONE_REGEX, ApproverIdSchema, GoogleWorkspaceTierSchema, GoogleWorkspaceConfigSchema, LiteLLMConfigSchema, HindsightPerOpLlmSchema, HindsightConfigSchema, MicrosoftWorkspaceConfigSchema, NotionWorkspaceConfigSchema, AgentGoogleWorkspaceConfigSchema, MicrosoftAccountEmailSchema, MicrosoftToolTokenSchema, MicrosoftAccountBindingSchema, AgentMicrosoftWorkspaceConfigSchema, AgentNotionWorkspaceConfigSchema, ReactionsSchema, ReactionDispatchSchema, releaseBlockFields, ReleaseBlock, RootReleaseBlock, NetworkIsolationSchema, servesField, knowsField, profileFields, ProfileSchema, _omitExtends, defaultsFields, AgentDefaultsSchema, DEFAULT_PROFILE = "default", AgentSchema, TelegramConfigSchema, MemoryBackendConfigSchema, VaultConfigSchema, QuotaConfigSchema, AutoReleaseCheckSchema, HostControlConfigSchema, WebServiceConfigSchema, FleetHealthConfigSchema, HostdConfigSchema, CronEgressSchema, CronConfigSchema, UserSchema, SwitchroomConfigSchema;
 var init_schema = __esm(() => {
   init_zod();
   init_observation_scopes();
@@ -13722,7 +13728,8 @@ var init_schema = __esm(() => {
     allow: exports_external.array(exports_external.string()).default([]).describe("Allowed tools (use ['all'] for unrestricted)"),
     deny: exports_external.array(exports_external.string()).default([]).describe("Denied tools (overrides allow)")
   }).optional();
-  ObservationScopesSchema = exports_external.enum(OBSERVATION_SCOPES).optional().describe("Per-row observation scope stamped on every memory this agent " + `retains. "shared" makes Hindsight's consolidation write the ` + "resulting observations into ONE global untagged scope instead of a " + "scope per tag \u2014 what several agents pooling one bank need so their " + "observations actually merge rather than sitting in parallel " + "per-tag silos. OMITTED BY DEFAULT: unset means the field never goes " + "on the wire and the engine's own default stands, which is the " + "shipped behaviour. Applies to every retain path (Stop hook, " + "sidechain, boot reconcile, queue drain, backfill, session-handoff " + "mirror) and is carried on the queued payload, so a retain that fails " + "now and drains later still lands in this scope. Accepted values: " + `${OBSERVATION_SCOPES.join(", ")}. ` + "Cascade: override (per-agent wins over default).");
+  ObservationScopesSchema = exports_external.enum(OBSERVATION_SCOPES).optional().describe("Operator PIN for the per-row observation scope, overriding the " + 'default `curated` strategy (see docs/configuration.md). "shared" ' + "forces Hindsight's consolidation to write EVERY observation into ONE " + "global untagged scope \u2014 what several agents pooling one bank want so " + "their observations merge rather than sitting in parallel silos. " + '"combined" is the pin form of opting out (restores the pre-#4035 ' + "engine default). UNSET does NOT mean 'nothing on the wire': the " + "`curated` strategy still computes a scope per retain. Applies to " + "every retain path (Stop hook, " + "sidechain, boot reconcile, queue drain, backfill, session-handoff " + "mirror) and is carried on the queued payload, so a retain that fails " + "now and drains later still lands in this scope. Accepted values: " + `${OBSERVATION_SCOPES.join(", ")}. ` + "Cascade: override (per-agent wins over default).");
+  ObservationScopeStrategySchema = exports_external.enum(OBSERVATION_SCOPE_STRATEGIES).optional().describe("Per-retain strategy that decides how the observation scope is " + 'computed when no `observation_scopes` pin is set. "curated" ' + "(the default since #4035) strips volatile per-session provenance " + "tags from each retain's consolidation scope \u2014 keeping the stable " + "semantic ones on the source fact \u2014 so an agent's observations dedup " + "and merge across sessions instead of pocketing one-per-session. " + '"shared" sends every retain to the one global untagged scope. ' + '"combined" / "off" opt OUT: no per-row scope goes on the wire, ' + "restoring the pre-feature engine default (byte-identical to an " + "unconfigured client). OMITTED BY DEFAULT: unset leaves the plugin's " + "own default (`curated`) in force. A manual `observation_scopes` pin " + "wins over this strategy. Accepted values: " + `${OBSERVATION_SCOPE_STRATEGIES.join(", ")}. ` + "Cascade: override (per-agent wins over default).");
   AgentMemorySchema = exports_external.object({
     collection: exports_external.string().describe("Hindsight collection name for this agent"),
     auto_recall: exports_external.boolean().default(true).describe("Auto-search memories before each response"),
@@ -13758,6 +13765,7 @@ var init_schema = __esm(() => {
     }).optional().describe("Personality traits (1-5 each) steering how this bank frames recall, " + "reflect, and observation synthesis \u2014 a coach leans empathy-high, a " + "lawyer/analyst leans skepticism/literalism-high. Maps to the engine's " + "flat `disposition_skepticism`/`_literalism`/`_empathy` fields. " + "Cascade: per-key merge (an agent overrides individual traits and " + "inherits the rest, matching `recall`)."),
     directive_capture_nudge: exports_external.boolean().optional().describe("Deterministic directive-capture nudge (issue #2848 Stage B). When " + "on (switchroom default true \u2014 Stage A measured a ~55% miss rate on " + "durable corrections), the auto-recall hook regex-detects correction " + '/ standing-rule-shaped inbound ("always/never \u2026", "from now on \u2026", ' + `"stop doing \u2026", a stated preference, "that's wrong, it's \u2026") and ` + "appends a terse advisory to the turn's context telling the model to " + "persist the rule with mcp__hindsight__create_directive if it IS " + "durable. Detection is pure regex \u2014 the model does the judgment " + "in-session and calls create_directive itself (no model callsite, no " + "silent hook-side write). Set false to disable per-agent. " + "Cascade: override (per-agent wins over default)."),
     observation_scopes: ObservationScopesSchema,
+    observation_scope_strategy: ObservationScopeStrategySchema,
     recall: exports_external.object({
       max_memories: exports_external.number().int().min(0).optional().describe("Cap on the number of memories injected into the prompt by " + "auto-recall, regardless of token budget. Plugin default is 12. " + "0 disables the cap (all memories Hindsight returns are injected)."),
       cache_ttl_secs: exports_external.number().int().min(0).optional().describe("Per-session recall cache TTL in seconds. When > 0, identical " + "(prompt, bank) within the same session reuse the cached recall " + "result instead of round-tripping to Hindsight. 0 disables. " + "Default is 600 (10 min) for switchroom-managed agents."),
@@ -14158,6 +14166,7 @@ var init_schema = __esm(() => {
       isolation: exports_external.enum(["default", "strict"]).optional(),
       directive_capture_nudge: exports_external.boolean().optional(),
       observation_scopes: ObservationScopesSchema,
+      observation_scope_strategy: ObservationScopeStrategySchema,
       recall: exports_external.object({
         max_memories: exports_external.number().int().min(0).optional(),
         cache_ttl_secs: exports_external.number().int().min(0).optional(),
@@ -29102,6 +29111,7 @@ function buildWorkspaceContext(args) {
     hindsightRecallSkipTrivial,
     hindsightDirectiveCaptureNudge,
     hindsightObservationScopes,
+    hindsightObservationScopeStrategy,
     hindsightTopicAliasesJson,
     hindsightSenderBanksJson,
     hindsightTopicFilterMode
@@ -29156,6 +29166,7 @@ function buildWorkspaceContext(args) {
     hindsightRecallSkipTrivial,
     hindsightDirectiveCaptureNudge,
     hindsightObservationScopesQ: hindsightObservationScopes ? shellSingleQuote(hindsightObservationScopes) : undefined,
+    hindsightObservationScopeStrategyQ: hindsightObservationScopeStrategy ? shellSingleQuote(hindsightObservationScopeStrategy) : undefined,
     hindsightTopicAliasesJsonQ: hindsightTopicAliasesJson ? shellSingleQuote(hindsightTopicAliasesJson) : undefined,
     hindsightSenderBanksJsonQ: hindsightSenderBanksJson ? shellSingleQuote(hindsightSenderBanksJson) : undefined,
     hindsightTopicFilterMode,
@@ -29421,6 +29432,7 @@ function scaffoldAgent(name, agentConfigRaw, agentsDir, telegramConfig, switchro
   const hindsightRecallSkipTrivial = agentConfig.memory?.recall?.skip_trivial === undefined ? undefined : String(agentConfig.memory.recall.skip_trivial);
   const hindsightDirectiveCaptureNudge = agentConfig.memory?.directive_capture_nudge === undefined ? undefined : String(agentConfig.memory.directive_capture_nudge);
   const hindsightObservationScopes = agentConfig.memory?.observation_scopes;
+  const hindsightObservationScopeStrategy = agentConfig.memory?.observation_scope_strategy;
   const topicAliases = agentConfig.channels?.telegram?.topic_aliases;
   const hindsightTopicAliasesJson = topicAliases && Object.keys(topicAliases).length > 0 ? JSON.stringify(topicAliases) : undefined;
   const senderBanks = switchroomConfig ? resolveUsers(switchroomConfig, name).senderBanks : agentConfig.memory?.recall?.sender_banks ?? {};
@@ -29457,6 +29469,7 @@ function scaffoldAgent(name, agentConfigRaw, agentsDir, telegramConfig, switchro
     hindsightRecallSkipTrivial,
     hindsightDirectiveCaptureNudge,
     hindsightObservationScopes,
+    hindsightObservationScopeStrategy,
     hindsightTopicAliasesJson,
     hindsightSenderBanksJson,
     hindsightTopicFilterMode
@@ -30402,6 +30415,7 @@ function reconcileAgentInner(name, agentConfigRaw, agentsDir, telegramConfig, sw
   const hindsightRecallSkipTrivial = agentConfig.memory?.recall?.skip_trivial === undefined ? undefined : String(agentConfig.memory.recall.skip_trivial);
   const hindsightDirectiveCaptureNudge = agentConfig.memory?.directive_capture_nudge === undefined ? undefined : String(agentConfig.memory.directive_capture_nudge);
   const hindsightObservationScopes = agentConfig.memory?.observation_scopes;
+  const hindsightObservationScopeStrategy = agentConfig.memory?.observation_scope_strategy;
   const topicAliases = agentConfig.channels?.telegram?.topic_aliases;
   const hindsightTopicAliasesJson = topicAliases && Object.keys(topicAliases).length > 0 ? JSON.stringify(topicAliases) : undefined;
   const senderBanks = switchroomConfig ? resolveUsers(switchroomConfig, name).senderBanks : agentConfig.memory?.recall?.sender_banks ?? {};
@@ -30451,6 +30465,7 @@ function reconcileAgentInner(name, agentConfigRaw, agentsDir, telegramConfig, sw
       hindsightRecallSkipTrivial,
       hindsightDirectiveCaptureNudge,
       hindsightObservationScopesQ: hindsightObservationScopes ? shellSingleQuote(hindsightObservationScopes) : undefined,
+      hindsightObservationScopeStrategyQ: hindsightObservationScopeStrategy ? shellSingleQuote(hindsightObservationScopeStrategy) : undefined,
       hindsightTopicAliasesJsonQ: hindsightTopicAliasesJson ? shellSingleQuote(hindsightTopicAliasesJson) : undefined,
       hindsightSenderBanksJsonQ: hindsightSenderBanksJson ? shellSingleQuote(hindsightSenderBanksJson) : undefined,
       hindsightTopicFilterMode,
@@ -30874,6 +30889,7 @@ ${body}
       hindsightRecallSkipTrivial,
       hindsightDirectiveCaptureNudge,
       hindsightObservationScopes,
+      hindsightObservationScopeStrategy,
       hindsightTopicAliasesJson,
       hindsightSenderBanksJson,
       hindsightTopicFilterMode
@@ -39115,168 +39131,6 @@ var init_telegram_yaml = __esm(() => {
   import_yaml12 = __toESM(require_dist(), 1);
 });
 
-// src/memory/hindsight-tools.ts
-var HINDSIGHT_MIN_API_VERSION = "0.8.5", HINDSIGHT_REPAIR_MIN_API_VERSION = "0.8.5", EXPECTED_HINDSIGHT_TOOLS;
-var init_hindsight_tools = __esm(() => {
-  EXPECTED_HINDSIGHT_TOOLS = {
-    recall: { required: ["query"] },
-    reflect: { required: ["query"] },
-    retain: { required: ["content"] },
-    sync_retain: { required: ["content"] },
-    delete_document: { required: ["document_id"] },
-    create_directive: { required: ["content", "name"] },
-    list_directives: { required: [] },
-    delete_directive: { required: ["directive_id"] },
-    create_bank: { required: ["bank_id"] },
-    update_bank: { required: [] },
-    list_banks: { required: [] },
-    create_mental_model: { required: ["name", "source_query"] },
-    list_mental_models: { required: [] },
-    update_mental_model: { required: ["mental_model_id"] },
-    refresh_mental_model: { required: ["mental_model_id"] },
-    list_memories: { required: [] },
-    get_memory: { required: ["memory_id"] },
-    update_memory: { required: ["memory_id"] },
-    invalidate_memory: { required: ["memory_id"] }
-  };
-});
-
-// src/memory/hindsight-repair.ts
-function buildRepairBankArgv(opts) {
-  const hasBank = typeof opts.bank === "string" && opts.bank.length > 0;
-  if (hasBank === Boolean(opts.all)) {
-    throw new Error("pass exactly one of --bank <id> or --all");
-  }
-  const cmdArgs = ["repair-bank"];
-  if (hasBank)
-    cmdArgs.push("--bank", opts.bank);
-  if (opts.all)
-    cmdArgs.push("--all");
-  if (opts.schema)
-    cmdArgs.push("--schema", opts.schema);
-  if (opts.dryRun)
-    cmdArgs.push("--dry-run");
-  const script = `if command -v hindsight-admin >/dev/null 2>&1; then exec hindsight-admin "$@"; fi; ` + `exec ${HINDSIGHT_ADMIN_BIN} "$@"`;
-  return [
-    "exec",
-    opts.container ?? HINDSIGHT_CONTAINER_NAME,
-    "sh",
-    "-c",
-    script,
-    "--",
-    ...cmdArgs
-  ];
-}
-function parseRepairSummary(stdout) {
-  const m = stdout.match(/Done:\s*(\d+)\s+schema\(s\),\s*(\d+)\s+bank\(s\) scanned,\s*(\d+)\s+already present,\s*(\d+)\s+created,\s*(\d+)\s+to-create \(dry-run\),\s*(\d+)\s+failed/);
-  if (!m)
-    return null;
-  return {
-    schemas: Number(m[1]),
-    banksScanned: Number(m[2]),
-    alreadyPresent: Number(m[3]),
-    created: Number(m[4]),
-    toCreate: Number(m[5]),
-    failed: Number(m[6])
-  };
-}
-function compareApiVersion(a, b) {
-  const part = (v, i) => {
-    const raw = v.split(".")[i];
-    if (raw === undefined)
-      return 0;
-    const n = parseInt(raw, 10);
-    return Number.isFinite(n) ? n : 0;
-  };
-  const len = Math.max(a.split(".").length, b.split(".").length);
-  for (let i = 0;i < len; i++) {
-    const d = part(a, i) - part(b, i);
-    if (d !== 0)
-      return d;
-  }
-  return 0;
-}
-async function fetchHindsightApiVersion(mcpUrl, opts = {}) {
-  const doFetch = opts.fetchImpl ?? fetch;
-  const origin = mcpUrl.replace(/\/mcp\/?$/, "").replace(/\/$/, "");
-  const controller = new AbortController;
-  const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 4000);
-  try {
-    const res = await doFetch(`${origin}/version`, { signal: controller.signal });
-    if (!res.ok)
-      return null;
-    const body = await res.json();
-    return typeof body?.api_version === "string" ? body.api_version : null;
-  } catch {
-    return null;
-  } finally {
-    clearTimeout(timer);
-  }
-}
-function classifyRepairPreflight(liveVersion) {
-  if (liveVersion === null)
-    return { ok: true };
-  if (compareApiVersion(liveVersion, HINDSIGHT_REPAIR_MIN_API_VERSION) < 0) {
-    return {
-      ok: false,
-      reason: `hindsight ${liveVersion} has no \`repair-bank\` command \u2014 it lands in ` + `${HINDSIGHT_REPAIR_MIN_API_VERSION} (upstream #2645). Without it there is no ` + `supported way to rebuild a bank's vector-index coverage. Update the ` + `pinned image in docker/Dockerfile.hindsight and recreate the container ` + `with \`switchroom memory --update\`, then re-run this command.`
-    };
-  }
-  return { ok: true };
-}
-function classifyRepairOutcome(run) {
-  if (run.childExit !== 0) {
-    return {
-      exit: REPAIR_FAILED_EXIT,
-      level: "fail",
-      headline: `repair-bank exited ${run.childExit}.`,
-      detail: run.childExit === 2 ? "Exit 2 from the admin CLI is a usage error \u2014 check --bank / --schema spelling. " + "Nothing was repaired and coverage is unknown." : "Failed indexes are dropped, so a re-run is safe and is the documented retry."
-    };
-  }
-  if (run.summary === null) {
-    return {
-      exit: REPAIR_UNVERIFIED_EXIT,
-      level: "fail",
-      headline: "repair-bank exited 0 but printed no summary \u2014 coverage was NOT confirmed.",
-      detail: "Read its output above. This is not a pass: a backend with a single global " + "index, an aborted scan, or an output-format change upstream all look like " + "this, and none of them means coverage is complete."
-    };
-  }
-  if (run.summary.banksScanned === 0) {
-    return {
-      exit: REPAIR_UNVERIFIED_EXIT,
-      level: "fail",
-      headline: "repair-bank scanned 0 bank(s) \u2014 nothing was checked.",
-      detail: "A scan that examined no bank proves nothing about coverage. Usual cause is a " + "--bank id or --schema name that matches nothing; `switchroom memory banks` " + "lists the real ids."
-    };
-  }
-  if (run.summary.failed > 0) {
-    return {
-      exit: REPAIR_FAILED_EXIT,
-      level: "fail",
-      headline: `${run.summary.failed} index(es) failed to build.`,
-      detail: "Those banks still under-return on recall. Failed indexes are dropped, so " + "re-running is safe and is the documented retry; if it repeats, the hindsight " + "container logs carry the postgres error."
-    };
-  }
-  if (run.dryRun && run.summary.toCreate > 0) {
-    return {
-      exit: REPAIR_COVERAGE_MISSING_EXIT,
-      level: "fail",
-      headline: `${run.summary.toCreate} vector index(es) missing across ${run.summary.banksScanned} bank(s).`,
-      detail: "Recall on those banks silently under-returns. Re-run without --dry-run to fix."
-    };
-  }
-  return {
-    exit: 0,
-    level: "ok",
-    headline: "repair-bank finished.",
-    detail: run.dryRun ? `Coverage complete: ${run.summary.alreadyPresent} index(es) present across ` + `${run.summary.banksScanned} bank(s), nothing to create.` : `${run.summary.created} created, ${run.summary.alreadyPresent} already present ` + `across ${run.summary.banksScanned} bank(s). Re-run \`switchroom doctor\` to confirm.`
-  };
-}
-var HINDSIGHT_CONTAINER_NAME = "switchroom-hindsight", HINDSIGHT_ADMIN_BIN = "/app/api/.venv/bin/hindsight-admin", REPAIR_FAILED_EXIT = 1, REPAIR_COVERAGE_MISSING_EXIT = 3, REPAIR_UNVERIFIED_EXIT = 4;
-var init_hindsight_repair = __esm(() => {
-  init_hindsight_tools();
-});
-
 // src/memory/bank-health.ts
 function hindsightRestBase(mcpUrl) {
   return mcpUrl.replace(/\/mcp\/?$/, "").replace(/\/$/, "");
@@ -39446,6 +39300,168 @@ function recentUnextracted(docs, withinDays = 30, now = new Date, minTextLength
 }
 var DOCUMENTS_PAGE_LIMIT = 500;
 
+// src/memory/hindsight-tools.ts
+var HINDSIGHT_MIN_API_VERSION = "0.8.5", HINDSIGHT_REPAIR_MIN_API_VERSION = "0.8.5", EXPECTED_HINDSIGHT_TOOLS;
+var init_hindsight_tools = __esm(() => {
+  EXPECTED_HINDSIGHT_TOOLS = {
+    recall: { required: ["query"] },
+    reflect: { required: ["query"] },
+    retain: { required: ["content"] },
+    sync_retain: { required: ["content"] },
+    delete_document: { required: ["document_id"] },
+    create_directive: { required: ["content", "name"] },
+    list_directives: { required: [] },
+    delete_directive: { required: ["directive_id"] },
+    create_bank: { required: ["bank_id"] },
+    update_bank: { required: [] },
+    list_banks: { required: [] },
+    create_mental_model: { required: ["name", "source_query"] },
+    list_mental_models: { required: [] },
+    update_mental_model: { required: ["mental_model_id"] },
+    refresh_mental_model: { required: ["mental_model_id"] },
+    list_memories: { required: [] },
+    get_memory: { required: ["memory_id"] },
+    update_memory: { required: ["memory_id"] },
+    invalidate_memory: { required: ["memory_id"] }
+  };
+});
+
+// src/memory/hindsight-repair.ts
+function buildRepairBankArgv(opts) {
+  const hasBank = typeof opts.bank === "string" && opts.bank.length > 0;
+  if (hasBank === Boolean(opts.all)) {
+    throw new Error("pass exactly one of --bank <id> or --all");
+  }
+  const cmdArgs = ["repair-bank"];
+  if (hasBank)
+    cmdArgs.push("--bank", opts.bank);
+  if (opts.all)
+    cmdArgs.push("--all");
+  if (opts.schema)
+    cmdArgs.push("--schema", opts.schema);
+  if (opts.dryRun)
+    cmdArgs.push("--dry-run");
+  const script = `if command -v hindsight-admin >/dev/null 2>&1; then exec hindsight-admin "$@"; fi; ` + `exec ${HINDSIGHT_ADMIN_BIN} "$@"`;
+  return [
+    "exec",
+    opts.container ?? HINDSIGHT_CONTAINER_NAME,
+    "sh",
+    "-c",
+    script,
+    "--",
+    ...cmdArgs
+  ];
+}
+function parseRepairSummary(stdout) {
+  const m = stdout.match(/Done:\s*(\d+)\s+schema\(s\),\s*(\d+)\s+bank\(s\) scanned,\s*(\d+)\s+already present,\s*(\d+)\s+created,\s*(\d+)\s+to-create \(dry-run\),\s*(\d+)\s+failed/);
+  if (!m)
+    return null;
+  return {
+    schemas: Number(m[1]),
+    banksScanned: Number(m[2]),
+    alreadyPresent: Number(m[3]),
+    created: Number(m[4]),
+    toCreate: Number(m[5]),
+    failed: Number(m[6])
+  };
+}
+function compareApiVersion(a, b) {
+  const part = (v, i) => {
+    const raw = v.split(".")[i];
+    if (raw === undefined)
+      return 0;
+    const n = parseInt(raw, 10);
+    return Number.isFinite(n) ? n : 0;
+  };
+  const len = Math.max(a.split(".").length, b.split(".").length);
+  for (let i = 0;i < len; i++) {
+    const d = part(a, i) - part(b, i);
+    if (d !== 0)
+      return d;
+  }
+  return 0;
+}
+async function fetchHindsightApiVersion(mcpUrl, opts = {}) {
+  const doFetch = opts.fetchImpl ?? fetch;
+  const origin = mcpUrl.replace(/\/mcp\/?$/, "").replace(/\/$/, "");
+  const controller = new AbortController;
+  const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 4000);
+  try {
+    const res = await doFetch(`${origin}/version`, { signal: controller.signal });
+    if (!res.ok)
+      return null;
+    const body = await res.json();
+    return typeof body?.api_version === "string" ? body.api_version : null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function classifyRepairPreflight(liveVersion) {
+  if (liveVersion === null)
+    return { ok: true };
+  if (compareApiVersion(liveVersion, HINDSIGHT_REPAIR_MIN_API_VERSION) < 0) {
+    return {
+      ok: false,
+      reason: `hindsight ${liveVersion} has no \`repair-bank\` command \u2014 it lands in ` + `${HINDSIGHT_REPAIR_MIN_API_VERSION} (upstream #2645). Without it there is no ` + `supported way to rebuild a bank's vector-index coverage. Update the ` + `pinned image in docker/Dockerfile.hindsight and recreate the container ` + `with \`switchroom memory --update\`, then re-run this command.`
+    };
+  }
+  return { ok: true };
+}
+function classifyRepairOutcome(run) {
+  if (run.childExit !== 0) {
+    return {
+      exit: REPAIR_FAILED_EXIT,
+      level: "fail",
+      headline: `repair-bank exited ${run.childExit}.`,
+      detail: run.childExit === 2 ? "Exit 2 from the admin CLI is a usage error \u2014 check --bank / --schema spelling. " + "Nothing was repaired and coverage is unknown." : "Failed indexes are dropped, so a re-run is safe and is the documented retry."
+    };
+  }
+  if (run.summary === null) {
+    return {
+      exit: REPAIR_UNVERIFIED_EXIT,
+      level: "fail",
+      headline: "repair-bank exited 0 but printed no summary \u2014 coverage was NOT confirmed.",
+      detail: "Read its output above. This is not a pass: a backend with a single global " + "index, an aborted scan, or an output-format change upstream all look like " + "this, and none of them means coverage is complete."
+    };
+  }
+  if (run.summary.banksScanned === 0) {
+    return {
+      exit: REPAIR_UNVERIFIED_EXIT,
+      level: "fail",
+      headline: "repair-bank scanned 0 bank(s) \u2014 nothing was checked.",
+      detail: "A scan that examined no bank proves nothing about coverage. Usual cause is a " + "--bank id or --schema name that matches nothing; `switchroom memory banks` " + "lists the real ids."
+    };
+  }
+  if (run.summary.failed > 0) {
+    return {
+      exit: REPAIR_FAILED_EXIT,
+      level: "fail",
+      headline: `${run.summary.failed} index(es) failed to build.`,
+      detail: "Those banks still under-return on recall. Failed indexes are dropped, so " + "re-running is safe and is the documented retry; if it repeats, the hindsight " + "container logs carry the postgres error."
+    };
+  }
+  if (run.dryRun && run.summary.toCreate > 0) {
+    return {
+      exit: REPAIR_COVERAGE_MISSING_EXIT,
+      level: "fail",
+      headline: `${run.summary.toCreate} vector index(es) missing across ${run.summary.banksScanned} bank(s).`,
+      detail: "Recall on those banks silently under-returns. Re-run without --dry-run to fix."
+    };
+  }
+  return {
+    exit: 0,
+    level: "ok",
+    headline: "repair-bank finished.",
+    detail: run.dryRun ? `Coverage complete: ${run.summary.alreadyPresent} index(es) present across ` + `${run.summary.banksScanned} bank(s), nothing to create.` : `${run.summary.created} created, ${run.summary.alreadyPresent} already present ` + `across ${run.summary.banksScanned} bank(s). Re-run \`switchroom doctor\` to confirm.`
+  };
+}
+var HINDSIGHT_CONTAINER_NAME = "switchroom-hindsight", HINDSIGHT_ADMIN_BIN = "/app/api/.venv/bin/hindsight-admin", REPAIR_FAILED_EXIT = 1, REPAIR_COVERAGE_MISSING_EXIT = 3, REPAIR_UNVERIFIED_EXIT = 4;
+var init_hindsight_repair = __esm(() => {
+  init_hindsight_tools();
+});
+
 // src/host-control/audit-rotation-config.ts
 var DEFAULT_HOSTD_AUDIT_MAX_BYTES, DEFAULT_HOSTD_AUDIT_MAX_FILES = 3;
 var init_audit_rotation_config = __esm(() => {
@@ -45781,6 +45797,8 @@ function classifyObservationScopeSaturation(reports) {
   }
   const unreadable = reports.filter((r) => !r.ok);
   const readable = reports.filter((r) => r.ok);
+  const growing = readable.filter((r) => r.observationsEnabled && r.untaggedCount >= OBSERVATION_SCOPE_UNTAGGED_WARN_COUNT).sort((a, b) => b.untaggedCount - a.untaggedCount);
+  const growthNote = growing.length > 0 ? `${growing.length} bank(s) with an untagged global scope over ` + `${OBSERVATION_SCOPE_UNTAGGED_WARN_COUNT.toLocaleString()} observations ` + `(uncapped curated sink, growth watch): ` + growing.slice(0, OBSERVATION_SCOPE_MAX_LISTED).map((r) => `${r.bankId} ${r.untaggedCount.toLocaleString()}`).join(", ") + (growing.length > OBSERVATION_SCOPE_MAX_LISTED ? `; +${growing.length - OBSERVATION_SCOPE_MAX_LISTED} more` : "") : "";
   if (readable.length === 0) {
     return {
       name,
@@ -45803,7 +45821,11 @@ function classifyObservationScopeSaturation(reports) {
     notes.push(`${disabled.length} bank(s) have observations disabled: ` + disabled.map((r) => r.bankId).join(", "));
   }
   const suffix = notes.length > 0 ? ` \u00b7 ${notes.join(" \u00b7 ")}` : "";
+  const growthSuffix = growthNote ? ` \u00b7 ${growthNote}` : "";
   if (judged.length === 0) {
+    if (growing.length > 0) {
+      return { name, status: "warn", detail: `${growthNote}${suffix}` };
+    }
     return { name, status: "skip", detail: `no bank could be judged${suffix}` };
   }
   const closed = judged.filter((r) => r.cap === 0);
@@ -45835,17 +45857,14 @@ function classifyObservationScopeSaturation(reports) {
     return {
       name,
       status: "fail",
-      detail: `${failing.length} observation scope(s) at or over the cap \u2014 consolidation ` + `output is being discarded on them right now: ${list(failing)}` + (warning.length > 0 ? ` \u00b7 ${warning.length} more above ${Math.round(OBSERVATION_SCOPE_WARN_RATIO * 100)}%` : "") + backlog([...failing, ...warning]) + suffix,
+      detail: `${failing.length} observation scope(s) at or over the cap \u2014 consolidation ` + `output is being discarded on them right now: ${list(failing)}` + (warning.length > 0 ? ` \u00b7 ${warning.length} more above ${Math.round(OBSERVATION_SCOPE_WARN_RATIO * 100)}%` : "") + backlog([...failing, ...warning]) + growthSuffix + suffix,
       fix
     };
   }
-  if (warning.length > 0) {
-    return {
-      name,
-      status: "warn",
-      detail: `${warning.length} observation scope(s) above ` + `${Math.round(OBSERVATION_SCOPE_WARN_RATIO * 100)}% of the cap and still writable: ` + `${list(warning)}` + backlog(warning) + suffix,
-      fix
-    };
+  if (warning.length > 0 || growing.length > 0) {
+    const scopeClause = warning.length > 0 ? `${warning.length} observation scope(s) above ` + `${Math.round(OBSERVATION_SCOPE_WARN_RATIO * 100)}% of the cap and still writable: ` + `${list(warning)}` + backlog(warning) : "";
+    const detail = warning.length > 0 ? scopeClause + growthSuffix + suffix : `${growthNote}${suffix}`;
+    return { name, status: "warn", detail, ...warning.length > 0 ? { fix } : {} };
   }
   const totalScopes = capped.reduce((n, r) => n + r.scopeCount, 0);
   const detailBase = capped.length === 0 ? `no bank has a positive observation cap` : `${totalScopes} scope(s) across ${capped.length} bank(s) below ` + `${Math.round(OBSERVATION_SCOPE_WARN_RATIO * 100)}% of the cap`;
@@ -45862,7 +45881,7 @@ function classifyObservationScopeSaturation(reports) {
     detail: detailBase + (extra.length > 0 ? ` \u00b7 ${extra.join(" \u00b7 ")}` : "") + suffix
   };
 }
-async function getJson2(url, opts) {
+async function getJson3(url, opts) {
   const fetchImpl = opts?.fetchImpl ?? fetch;
   const timeoutMs = opts?.timeoutMs ?? 15000;
   const controller = new AbortController;
@@ -45891,10 +45910,11 @@ async function inspectBankScopes(apiUrl, bankId, opts) {
     observationsEnabled: false,
     hasScopeLimitRules: false,
     scopeCount: 0,
+    untaggedCount: 0,
     saturated: [],
     pendingConsolidation: null
   });
-  const cfg = await getJson2(`${base}/v1/default/banks/${bank}/config`, opts);
+  const cfg = await getJson3(`${base}/v1/default/banks/${bank}/config`, opts);
   if (!cfg.ok)
     return fail4(cfg.reason);
   const config = cfg.data?.config;
@@ -45907,7 +45927,7 @@ async function inspectBankScopes(apiUrl, bankId, opts) {
   const rules = config["observation_scope_limits"];
   const hasScopeLimitRules = Array.isArray(rules) && rules.length > 0;
   const observationsEnabled = config["enable_observations"] !== false;
-  const scopesResp = await getJson2(`${base}/v1/default/banks/${bank}/observations/scopes`, opts);
+  const scopesResp = await getJson3(`${base}/v1/default/banks/${bank}/observations/scopes`, opts);
   if (!scopesResp.ok)
     return fail4(scopesResp.reason);
   const rawScopes = scopesResp.data?.scopes;
@@ -45924,9 +45944,10 @@ async function inspectBankScopes(apiUrl, bankId, opts) {
     scopes.push({ tags, count });
   }
   const saturated = computeScopeSaturation(scopes, rawCap).filter((s) => s.status !== "ok");
+  const untaggedCount = scopes.filter((s) => s.tags.length === 0).reduce((n, s) => n + s.count, 0);
   let pendingConsolidation = null;
   if (saturated.length > 0 && !hasScopeLimitRules && observationsEnabled) {
-    const stats = await getJson2(`${base}/v1/default/banks/${bank}/stats`, opts);
+    const stats = await getJson3(`${base}/v1/default/banks/${bank}/stats`, opts);
     if (stats.ok && typeof stats.data?.pending_consolidation === "number") {
       pendingConsolidation = stats.data.pending_consolidation;
     }
@@ -45938,6 +45959,7 @@ async function inspectBankScopes(apiUrl, bankId, opts) {
     observationsEnabled,
     hasScopeLimitRules,
     scopeCount: scopes.length,
+    untaggedCount,
     saturated,
     pendingConsolidation
   };
@@ -45953,7 +45975,7 @@ async function checkObservationScopeSaturation(config, apiUrl, opts) {
   const reports = await Promise.all([...banks].map((bankId) => inspectBankScopes(apiUrl, bankId, opts)));
   return classifyObservationScopeSaturation(reports);
 }
-var OBSERVATION_SCOPE_CHECK_NAME = "hindsight observation scopes", OBSERVATION_SCOPE_WARN_RATIO = 0.8, OBSERVATION_SCOPE_MAX_LISTED = 6;
+var OBSERVATION_SCOPE_CHECK_NAME = "hindsight observation scopes", OBSERVATION_SCOPE_WARN_RATIO = 0.8, OBSERVATION_SCOPE_MAX_LISTED = 6, OBSERVATION_SCOPE_UNTAGGED_WARN_COUNT = 1e4;
 var init_doctor_observation_scopes = __esm(() => {
   init_merge();
   init_hindsight2();
@@ -85474,6 +85496,174 @@ function reflectAcrossAgents(config) {
   return { eligible, excluded, commands };
 }
 
+// src/memory/observation-scope-cleanup.ts
+var CLEANUP_VOLATILE_PATTERNS = [
+  /^parent_session:/,
+  /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}(-sub-.+)?$/
+];
+var CLEANUP_STALE_PATTERNS = [/^agent-[0-9a-f]{8,}$/];
+function matchesAny(tag, patterns) {
+  return patterns.some((p) => p.test(tag));
+}
+function scopeKey(tags) {
+  return tags.length === 0 ? "shared" : [...tags].sort().join(",");
+}
+function planScopeCleanup(bankId, scopes, options = {}) {
+  const volatilePatterns = options.volatilePatterns ?? CLEANUP_VOLATILE_PATTERNS;
+  const stalePatterns = options.stalePatterns ?? CLEANUP_STALE_PATTERNS;
+  const retireStale = options.retireStale ?? false;
+  const totalScopes = scopes.length;
+  const totalObservations = scopes.reduce((n, s) => n + s.count, 0);
+  const reclassified = [];
+  const breakdown = {
+    allVolatileScopes: 0,
+    allVolatileObservations: 0,
+    mixedScopes: 0,
+    mixedObservations: 0,
+    staleScopes: 0,
+    staleObservations: 0
+  };
+  const targets = new Map;
+  for (const s of scopes) {
+    const volatileTags = s.tags.filter((t) => matchesAny(t, volatilePatterns));
+    const staleTags = s.tags.filter((t) => matchesAny(t, stalePatterns));
+    const stripped = s.tags.filter((t) => {
+      if (matchesAny(t, volatilePatterns))
+        return false;
+      if (retireStale && matchesAny(t, stalePatterns))
+        return false;
+      return true;
+    });
+    const toKey = scopeKey(stripped);
+    const changed = scopeKey(s.tags) !== toKey;
+    const hasStable = s.tags.some((t) => !matchesAny(t, volatilePatterns) && !matchesAny(t, stalePatterns));
+    if (staleTags.length > 0) {
+      breakdown.staleScopes += 1;
+      breakdown.staleObservations += s.count;
+    }
+    if (volatileTags.length > 0 && !hasStable && staleTags.length === 0) {
+      breakdown.allVolatileScopes += 1;
+      breakdown.allVolatileObservations += s.count;
+    } else if (volatileTags.length > 0 && hasStable) {
+      breakdown.mixedScopes += 1;
+      breakdown.mixedObservations += s.count;
+    }
+    const entry = targets.get(toKey) ?? { sources: 0, observations: 0, changed: false };
+    entry.sources += 1;
+    entry.observations += s.count;
+    entry.changed = entry.changed || changed;
+    targets.set(toKey, entry);
+    if (changed) {
+      reclassified.push({
+        from: s.tags,
+        to: toKey,
+        count: s.count,
+        strippedVolatile: volatileTags,
+        strippedStale: retireStale ? staleTags : []
+      });
+    }
+  }
+  reclassified.sort((a, b) => b.count - a.count);
+  const merges = [...targets.entries()].filter(([, v]) => v.sources > 1 && v.changed).map(([target, v]) => ({ target, sourceScopes: v.sources, observations: v.observations })).sort((a, b) => b.observations - a.observations);
+  const affectedObservations = reclassified.reduce((n, r) => n + r.count, 0);
+  const resultingScopeCount = targets.size;
+  return {
+    bankId,
+    ok: true,
+    totalScopes,
+    totalObservations,
+    reclassified,
+    merges,
+    affectedScopes: reclassified.length,
+    affectedObservations,
+    resultingScopeCount,
+    scopeReduction: totalScopes - resultingScopeCount,
+    breakdown
+  };
+}
+async function getJson2(url, opts) {
+  const fetchImpl = opts?.fetchImpl ?? fetch;
+  const timeoutMs = opts?.timeoutMs ?? 15000;
+  const controller = new AbortController;
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const resp = await fetchImpl(url, { signal: controller.signal });
+    clearTimeout(timeout);
+    if (!resp.ok)
+      return { ok: false, reason: `HTTP ${resp.status}` };
+    return { ok: true, data: await resp.json() };
+  } catch (err) {
+    clearTimeout(timeout);
+    if (err.name === "AbortError")
+      return { ok: false, reason: "Timeout" };
+    return { ok: false, reason: String(err.message ?? err) };
+  }
+}
+async function planBankCleanup(apiUrl, bankId, options = {}, fetchOpts) {
+  const base = hindsightRestBase(apiUrl);
+  const bank = encodeURIComponent(bankId);
+  const resp = await getJson2(`${base}/v1/default/banks/${bank}/observations/scopes`, fetchOpts);
+  if (!resp.ok) {
+    return {
+      bankId,
+      ok: false,
+      reason: resp.reason,
+      totalScopes: 0,
+      totalObservations: 0,
+      reclassified: [],
+      merges: [],
+      affectedScopes: 0,
+      affectedObservations: 0,
+      resultingScopeCount: 0,
+      scopeReduction: 0,
+      breakdown: {
+        allVolatileScopes: 0,
+        allVolatileObservations: 0,
+        mixedScopes: 0,
+        mixedObservations: 0,
+        staleScopes: 0,
+        staleObservations: 0
+      }
+    };
+  }
+  const raw = resp.data?.scopes;
+  const scopes = [];
+  if (Array.isArray(raw)) {
+    for (const entry of raw) {
+      const tags = entry?.tags;
+      const count = entry?.count;
+      if (!Array.isArray(tags) || typeof count !== "number")
+        continue;
+      if (!tags.every((t) => typeof t === "string"))
+        continue;
+      scopes.push({ tags, count });
+    }
+  }
+  return planScopeCleanup(bankId, scopes, options);
+}
+function formatCleanupPlan(plan, maxMerges = 10) {
+  if (!plan.ok) {
+    return `bank ${plan.bankId}: UNREADABLE (${plan.reason ?? "unknown"})`;
+  }
+  const b = plan.breakdown;
+  const lines = [];
+  lines.push(`bank ${plan.bankId}`);
+  lines.push(`  today: ${plan.totalScopes} scopes, ${plan.totalObservations.toLocaleString()} observations`);
+  lines.push(`  legacy fragmentation:` + ` all-volatile ${b.allVolatileScopes} scopes / ${b.allVolatileObservations.toLocaleString()} obs;` + ` mixed ${b.mixedScopes} scopes / ${b.mixedObservations.toLocaleString()} obs;` + ` stale agent-<hex> ${b.staleScopes} scopes / ${b.staleObservations.toLocaleString()} obs`);
+  lines.push(`  WOULD change: ${plan.affectedScopes} scopes` + ` (${plan.affectedObservations.toLocaleString()} obs re-homed),` + ` ${plan.totalScopes} \u2192 ${plan.resultingScopeCount} scopes` + ` (\u2212${plan.scopeReduction})`);
+  if (plan.merges.length > 0) {
+    lines.push(`  top merges:`);
+    for (const m of plan.merges.slice(0, maxMerges)) {
+      lines.push(`    ${m.sourceScopes} scopes \u2192 ${m.target}  (${m.observations.toLocaleString()} obs)`);
+    }
+    if (plan.merges.length > maxMerges) {
+      lines.push(`    +${plan.merges.length - maxMerges} more merge targets`);
+    }
+  }
+  return lines.join(`
+`);
+}
+
 // src/cli/memory.ts
 init_helpers();
 init_hindsight();
@@ -86200,6 +86390,55 @@ Demoting memory ${source_default.cyan(memoryId)}`));
 ` + "  If the ID itself is suspect: `switchroom memory recall-log " + agent + " --json`."));
     process.exit(1);
   }));
+  memory.command("cleanup-scopes [agent]").description("Dry-run audit of legacy pre-#4035 observation-scope fragmentation " + "(per-session UUID islands, stale agent-<hex> scopes). Reads only; " + "prints the blast radius of a curated re-home. Pass an agent, or --all.").option("--all", "Audit every agent bank and profile bank").option("--retire-stale", "Also fold stale agent-<hex> producer scopes into shared (opt-in; not part of the #4035 heal)").option("--execute", "(refused) live mutation is not supported \u2014 see the printed reason").option("--json", "Emit the plans as JSON").action(withConfigError(async (agent, opts) => {
+    const config = getConfig(program3);
+    const apiUrl = config.memory?.config?.url ?? HINDSIGHT_DEFAULT_MCP_URL;
+    if (opts.execute) {
+      console.error(source_default.red("\u2717 --execute is not supported: legacy-scope healing is not mechanizable"));
+      console.error(source_default.gray(`  Hindsight exposes no per-memory tag-write (update_memory / PATCH memories/{id}
+` + "  silently drop a `tags` argument, #3772) and no per-scope delete (DELETE\n" + `  .../observations clears the WHOLE bank). So an observation's scope cannot be
+` + `  edited in place, and this tool stays a read-only audit. A live heal needs an
+` + `  upstream tag-write path or a deliberate, operator-approved enumerate-and-
+` + "  invalidate pass \u2014 neither is run from here."));
+      process.exit(1);
+    }
+    const banks = new Set;
+    if (agent) {
+      if (!config.agents[agent]) {
+        console.error(source_default.red(`Agent "${agent}" is not defined in switchroom.yaml`));
+        process.exit(1);
+      }
+      banks.add(getCollectionForAgent(agent, config));
+    } else if (opts.all) {
+      for (const name of Object.keys(config.agents)) {
+        banks.add(getCollectionForAgent(name, config));
+      }
+      for (const bank of collectProfileBanks(config))
+        banks.add(bank);
+    } else {
+      console.error(source_default.red("Pass an agent name, or --all to audit every bank."));
+      process.exit(1);
+    }
+    const plans = await Promise.all([...banks].map((bankId) => planBankCleanup(apiUrl, bankId, { retireStale: opts.retireStale })));
+    plans.sort((a, b) => b.affectedObservations - a.affectedObservations);
+    if (opts.json) {
+      console.log(JSON.stringify(plans, null, 2));
+      return;
+    }
+    console.log(source_default.bold(`
+Observation-scope cleanup \u2014 DRY RUN (no writes)
+`));
+    console.log(source_default.gray(`  api=${apiUrl}  retireStale=${Boolean(opts.retireStale)}
+`));
+    for (const plan of plans) {
+      console.log(formatCleanupPlan(plan));
+      console.log();
+    }
+    const totalObs = plans.reduce((n, p) => n + p.affectedObservations, 0);
+    const totalScopes = plans.reduce((n, p) => n + p.scopeReduction, 0);
+    console.log(source_default.cyan(`Fleet total (would change): ${totalObs.toLocaleString()} observations re-homed, ` + `${totalScopes.toLocaleString()} scopes removed.`));
+    console.log(source_default.gray("Nothing was written. Live execution is not supported from this tool " + "(--execute prints why)."));
+  }));
   const restBase = (url) => (url ?? HINDSIGHT_DEFAULT_MCP_URL).replace(/\/mcp\/?$/, "").replace(/\/$/, "");
   const VALID_BANK = /^[a-zA-Z0-9_.-]+$/;
   const profile = memory.command("profile").description("Author + inspect operator profile banks (shared/per-user memory; wire via memory.recall.additional_banks)");
@@ -93801,6 +94040,7 @@ init_atomic();
 init_resolve_version();
 init_audit_reader();
 init_hindsight();
+init_hindsight2();
 
 // src/cli/deploy-version-guard.ts
 import { spawnSync as spawnSync18 } from "node:child_process";
@@ -93848,22 +94088,31 @@ function checkDowngrade(opts) {
 init_agent_owned_tree();
 init_component_versions();
 var VERIFY_COMPONENTS_STEP = "verify-components";
+var ENSURE_BANKS_STEP = "ensure-banks";
 function normalizeVersion(v) {
   return v.trim().replace(/^v/, "");
 }
 function isVersionAssertable(target) {
   return /^v?\d+\.\d+\.\d+$/.test(target.trim());
 }
-function orderAgentsCanaryFirst(agents) {
+var ROLLOUT_PRIORITY_AGENTS = [
+  "overlord",
+  "carrie",
+  "finn"
+];
+function orderAgentsForRoll(agents) {
   const canary = agents.filter((a) => a === "test-harness");
-  const rest = agents.filter((a) => a !== "test-harness");
-  return [...canary, ...rest];
+  const priority = ROLLOUT_PRIORITY_AGENTS.filter((p) => p !== "test-harness" && agents.includes(p));
+  const prioritySet = new Set(priority);
+  const rest = agents.filter((a) => a !== "test-harness" && !prioritySet.has(a));
+  return [...canary, ...priority, ...rest];
 }
 function planRollout(agents, opts = {}) {
   const steps = [];
-  const ordered = orderAgentsCanaryFirst(agents);
+  const ordered = orderAgentsForRoll(agents);
   if (opts.hostdContext) {
     steps.push({ kind: "apply" });
+    steps.push({ kind: "refresh-hindsight" });
     const [canary, ...rest] = ordered;
     if (canary !== undefined) {
       steps.push({ kind: "restart-agent", agent: canary });
@@ -93879,23 +94128,26 @@ function planRollout(agents, opts = {}) {
     if (!opts.skipWeb) {
       steps.push({ kind: "refresh-web" });
     }
-    steps.push({ kind: "refresh-hindsight" });
     steps.push({ kind: "sweep" });
+    steps.push({ kind: "ensure-banks" });
     steps.push({ kind: "verify-components" });
     return steps;
   }
   if (opts.pinToPersist)
     steps.push({ kind: "persist-pin", pin: opts.pinToPersist });
   steps.push({ kind: "apply" });
+  if (!opts.skipWeb) {
+    steps.push({ kind: "refresh-hindsight" });
+  }
   for (const agent of ordered) {
     steps.push({ kind: "restart-agent", agent });
   }
   if (!opts.skipWeb) {
     steps.push({ kind: "refresh-web" });
     steps.push({ kind: "refresh-hostd" });
-    steps.push({ kind: "refresh-hindsight" });
   }
   steps.push({ kind: "sweep" });
+  steps.push({ kind: "ensure-banks" });
   steps.push({ kind: "verify-components" });
   return steps;
 }
@@ -93926,6 +94178,9 @@ function formatRolloutPlan(steps, target) {
       case "sweep":
         lines.push(`  ${n}. sweep \u2014 print per-agent version table`);
         break;
+      case "ensure-banks":
+        lines.push(`  ${n}. ensure-banks \u2014 create any missing agent Hindsight bank ` + `(idempotent backstop; structured failure if one stays missing)`);
+        break;
       case "verify-components":
         lines.push(`  ${n}. verify-components \u2014 assert EVERY in-scope component is on ${target} ` + `(same inventory \`switchroom update --check\` uses); non-zero exit if any is behind`);
         break;
@@ -93987,7 +94242,7 @@ function evaluateRolloutDrift(components, target, steps, hostdContext) {
   const { gated, exempt } = partitionDrift(report.behind, { owners, rolledAgents });
   return { gated, exempt, target: report.target };
 }
-function executeRollout(steps, target, deps, execOpts = {}) {
+async function executeRollout(steps, target, deps, execOpts = {}) {
   const targetNorm = normalizeVersion(target);
   const rolled = [];
   const warnings = [];
@@ -93996,6 +94251,7 @@ function executeRollout(steps, target, deps, execOpts = {}) {
   let agentIndex = 0;
   let pinPersisted = false;
   let driftVerdict = null;
+  const bankEnsureFailed = [];
   const fail4 = (partial) => {
     let pinReverted = false;
     if (pinPersisted && deps.revertPin) {
@@ -94100,6 +94356,10 @@ function executeRollout(steps, target, deps, execOpts = {}) {
           const webTag = deps.webImageTag?.();
           if (webTag !== undefined && webTag !== null && isVersionAssertable(webTag) && normalizeVersion(webTag) !== targetNorm) {
             warnings.push(`web refresh completed but switchroom-web is running ${webTag}, ` + `NOT the roll target ${target} (most likely its downgrade guard ` + `skipped the install). Finish it host-side: \`switchroom webd ` + `install --tag ${target} --allow-downgrade\`.`);
+            break;
+          }
+          if (webTag !== undefined && webTag !== null && isVersionAssertable(webTag) && normalizeVersion(webTag) === targetNorm) {
+            emit({ phase: "web-refresh-done", target });
           }
           break;
         }
@@ -94115,9 +94375,11 @@ function executeRollout(steps, target, deps, execOpts = {}) {
           const hindsightExists = deps.hindsightExists ?? isHindsightContainerExists;
           if (!hindsightExists()) {
             deps.log(`ROLL_STEP refresh-hindsight \u2014 no hindsight container on this host; skipping`);
+            emit({ phase: "hindsight-skipped", target });
             break;
           }
           deps.log(`ROLL_STEP refresh-hindsight \u2014 memory setup --recreate --tag ${target} (pull ${target} + recreate)`);
+          emit({ phase: "hindsight-refresh", target });
           const r = deps.run(["memory", "setup", "--recreate", "--tag", target]);
           if (r.status !== 0) {
             deps.log(`  \u2717 hindsight recreate FAILED \u2014 the memory backend is DOWN (the ` + `recreate stopped + removed the old container before the failed ` + `start). Run \`switchroom memory setup\` to bring it back. \u2014 STOPPING`);
@@ -94126,6 +94388,7 @@ function executeRollout(steps, target, deps, execOpts = {}) {
               ...r.timedOut ? { timedOut: true } : {}
             });
           }
+          emit({ phase: "hindsight-refresh-done", target });
           break;
         }
         case "sweep": {
@@ -94136,6 +94399,38 @@ function executeRollout(steps, target, deps, execOpts = {}) {
           }
           break;
         }
+        case "ensure-banks": {
+          const hindsightExists = deps.hindsightExists ?? isHindsightContainerExists;
+          if (!hindsightExists()) {
+            deps.log(`ROLL_STEP ensure-banks \u2014 no hindsight container on this host; skipping`);
+            break;
+          }
+          if (!deps.ensureBank) {
+            warnings.push(`ensure-banks ran with NO bank-ensure hook wired, so brand-new ` + `agents' Hindsight banks were NOT verified. If an agent's first ` + `\`retain\` fails with a foreign-key error, its bank was never ` + `created \u2014 recreate it by restarting that agent.`);
+            break;
+          }
+          deps.log(`ROLL_STEP ensure-banks \u2014 creating any missing agent bank (idempotent) for ${rolled.length} agent(s)`);
+          for (const a of rolled) {
+            let res;
+            try {
+              res = await deps.ensureBank(a);
+            } catch (e) {
+              res = { ok: false, reason: e.message };
+            }
+            if (res.ok) {
+              deps.log(`  ${a}: bank present`);
+              continue;
+            }
+            if (/unreachable|timeout/i.test(res.reason)) {
+              deps.log(`  ${a}: bank check ${res.reason.toLowerCase()} (degraded to warning)`);
+              warnings.push(`ensure-banks could not reach Hindsight to verify ${a}'s bank ` + `(${res.reason}). If ${a} is brand-new and its first \`retain\` ` + `fails with a foreign-key error, restart it to recreate the bank.`);
+              continue;
+            }
+            deps.log(`  \u2717 ${a}: bank could NOT be created \u2014 ${res.reason}`);
+            bankEnsureFailed.push(a);
+          }
+          break;
+        }
         case "verify-components": {
           deps.log(`ROLL_STEP verify-components \u2014 asserting every in-scope component is on ${target}`);
           if (!deps.collectComponents) {
@@ -94174,6 +94469,19 @@ function executeRollout(steps, target, deps, execOpts = {}) {
       warnings.push(`roll succeeded but committing the durable release.pin threw: ` + `${e.message}. The pin IS written; a stale rollout ` + `journal may cause a later boot to revert it \u2014 verify host-side.`);
     }
   }
+  if (bankEnsureFailed.length > 0) {
+    for (const a of bankEnsureFailed) {
+      warnings.push(`${a}'s Hindsight bank could NOT be created during the roll \u2014 its ` + `first \`retain\` will fail with a foreign-key error until the bank ` + `exists. Restart ${a} to re-run its bank creation now that Hindsight ` + `is back up.`);
+    }
+    deps.log(`  \u2717 ensure-banks FAILED \u2014 ${bankEnsureFailed.length} agent bank(s) ` + `could not be created: ${bankEnsureFailed.join(", ")}`);
+    return {
+      ok: false,
+      rolled,
+      warnings,
+      failedStep: ENSURE_BANKS_STEP,
+      drifted: bankEnsureFailed
+    };
+  }
   if (driftVerdict && driftVerdict.gated.length > 0) {
     const normalizedTarget = `v${normalizeVersion(target)}`;
     for (const c of driftVerdict.gated) {
@@ -94340,7 +94648,12 @@ function createRolloutDeps(params) {
 `);
       }
       return outcome.reverted;
-    }
+    },
+    ...params.hindsightApiUrl && params.resolveBankId ? {
+      ensureBank: (agent) => createBank(params.hindsightApiUrl, params.resolveBankId(agent), {
+        timeoutMs: 5000
+      })
+    } : {}
   };
 }
 function registerRolloutCommand(program3) {
@@ -94433,10 +94746,23 @@ function registerRolloutCommand(program3) {
     }
     const configPath = getConfigPath(program3);
     const scriptPath = process.argv[1] ?? "";
-    const deps = createRolloutDeps({ configPath, scriptPath, hostdCtx });
+    let hindsightApiUrl;
+    let resolveBankId;
+    if (isHindsightEnabled(config)) {
+      const rawUrl = config.memory?.config?.url;
+      hindsightApiUrl = rawUrl ? rawUrl.replace(/\/mcp\/?$/, "").replace(/\/$/, "") : HINDSIGHT_DEFAULT_API_BASE_URL;
+      resolveBankId = (agent) => config.agents?.[agent]?.memory?.collection ?? agent;
+    }
+    const deps = createRolloutDeps({
+      configPath,
+      scriptPath,
+      hostdCtx,
+      hindsightApiUrl,
+      resolveBankId
+    });
     process.stdout.write(`${opts.allowDowngrade ? "Rolling back" : "Rolling"} ${requested.length} agent(s) to ${target}\u2026
 `);
-    const result = executeRollout(steps, target, deps, {
+    const result = await executeRollout(steps, target, deps, {
       hostdContext: hostdCtx,
       allowDowngrade: opts.allowDowngrade
     });
@@ -94457,6 +94783,15 @@ function registerRolloutCommand(program3) {
 \u2717 Rollout INCOMPLETE \u2014 ${(result.drifted ?? []).length} component(s) ` + `still behind ${target}: ${(result.drifted ?? []).join(", ") || "unknown"}.
 ` + `  ${result.rolled.length} agent(s) DID reach ${target} and the pin is ` + `committed \u2014 re-running the agent roll will not fix this.
 ` + `  Run the per-component command named in the warning(s) above, then ` + `\`switchroom update --check\` to confirm the host is converged.
+`);
+      process.exitCode = 1;
+      return;
+    }
+    if (!result.ok && result.failedStep === ENSURE_BANKS_STEP) {
+      process.stderr.write(`
+\u2717 Rollout INCOMPLETE \u2014 ${(result.drifted ?? []).length} agent(s) ` + `reached ${target} but their Hindsight bank could NOT be created: ` + `${(result.drifted ?? []).join(", ") || "unknown"}.
+` + `  The pin is committed and the agents ARE on the target \u2014 re-running ` + `the agent roll will not fix this.
+` + `  Restart the named agent(s) to re-run bank creation now that ` + `Hindsight is back up (their first \`retain\` fails with a foreign-key ` + `error until the bank exists).
 `);
       process.exitCode = 1;
       return;