switchroom 0.21.12 → 0.21.13

package/dist/host-control/main.js

@@ -10994,7 +10994,7 @@ var init_observation_scopes = __esm(() => {
 });
 
 // src/config/schema.ts
-var CodeRepoEntrySchema, AgentBindMountSchema, HttpDiffPollSchema, PollSpecSchema, TelegramMessageActionSchema, WebhookActionSchema, ActionSpecSchema, ScheduleEntrySchema, AgentSoulSchema, AgentToolsSchema, ObservationScopesSchema, ObservationScopeStrategySchema, AntiConfabulationDirectiveSchema, AgentMemorySchema, HookEntrySchema, AgentHooksSchema, SubagentSchema, SessionSchema, SessionContinuitySchema, webhookDispatchRule, TelegramChannelSchema, BuzzChannelSchema, ChannelsSchema, TIMEZONE_REGEX, ApproverIdSchema, GoogleWorkspaceTierSchema, GoogleServiceTokenSchema, 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, AgentSchema, TelegramConfigSchema, MemoryBackendConfigSchema, VaultConfigSchema, QuotaConfigSchema, AutoReleaseCheckSchema, HostControlConfigSchema, WebServiceConfigSchema, FleetHealthConfigSchema, HostdConfigSchema, CronEgressSchema, CronConfigSchema, UserSchema, ConfigRepoConfigSchema, SwitchroomConfigSchema;
+var CodeRepoEntrySchema, AgentBindMountSchema, HttpDiffPollSchema, PollSpecSchema, TelegramMessageActionSchema, WebhookActionSchema, ActionSpecSchema, ScheduleEntrySchema, AgentSoulSchema, AgentToolsSchema, ObservationScopesSchema, ObservationScopeStrategySchema, AntiConfabulationDirectiveSchema, AgentMemorySchema, HookEntrySchema, AgentHooksSchema, SubagentSchema, SessionSchema, SessionContinuitySchema, webhookDispatchRule, TelegramChannelSchema, BuzzChannelSchema, ChannelsSchema, TIMEZONE_REGEX, ApproverIdSchema, GoogleWorkspaceTierSchema, GoogleServiceTokenSchema, 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, AgentSchema, TelegramConfigSchema, MemoryBackendConfigSchema, VaultConfigSchema, QuotaConfigSchema, AutoReleaseCheckSchema, ScratchConfigSchema, DiskConfigSchema, HostControlConfigSchema, WebServiceConfigSchema, FleetHealthConfigSchema, HostdConfigSchema, CronEgressSchema, CronConfigSchema, UserSchema, ConfigRepoConfigSchema, SwitchroomConfigSchema;
 var init_schema = __esm(() => {
   init_zod();
   init_observation_scopes();
@@ -11867,6 +11867,27 @@ var init_schema = __esm(() => {
     notify_on_detect: exports_external.boolean().default(false).describe("KEN-129 — operator-in-the-loop update prompt. Only consulted " + "when apply_on_detect is false (auto-apply supersedes notify): " + "a newly detected release posts ONE operator approval card " + "('fleet is behind — tap to apply') via an admin agent's " + "gateway; Approve runs hostd's update_apply path (fleet-" + "mutation-locked, durable status rows, get_status-pollable). " + "Dedup on release id: the last-notified id persists in " + "~/.switchroom/release-notify-state.json, so a card that " + "reached the operator is never re-posted for the same release."),
     image_ref: exports_external.string().default("ghcr.io/switchroom/switchroom-agent:latest").describe("Image reference whose remote digest is compared to the local " + "image digest. Defaults to the agent image's :latest tag, which " + "is the canonical signal that a release has been promoted.")
   });
+  ScratchConfigSchema = exports_external.object({
+    enabled: exports_external.boolean().default(true).describe("Whether agents get a scratch mount at /scratch with their package " + "caches redirected there. Default: true — but the feature only " + "engages when `volume` actually exists on the host, so a single-disk " + "machine is unaffected. Set false to opt out even where it does."),
+    volume: exports_external.string().refine((v) => v.startsWith("/"), {
+      message: "scratch.volume must be an absolute host path"
+    }).default("/mnt/bulkdata").describe("Absolute host path of the bulk device's mountpoint. MUST already " + "exist — its presence is the single probe that turns the feature on, " + "so a typo degrades to the pre-existing behaviour rather than " + "quietly relocating caches somewhere that is still the root disk. " + "Default: /mnt/bulkdata."),
+    subdir: exports_external.string().refine((v) => !v.startsWith("/") && !v.split("/").includes(".."), {
+      message: "scratch.subdir must be a relative path without '..' segments"
+    }).default("switchroom/scratch").describe("Relative path under `volume` holding the per-agent scratch " + "directories (`<volume>/<subdir>/<agent>`). Default: " + "switchroom/scratch.")
+  });
+  DiskConfigSchema = exports_external.object({
+    warn_pct: exports_external.number().int().min(1).max(99).default(80).describe("Used-percentage at or above which `switchroom doctor` WARNs about " + "the filesystem holding the agents directory. Default 80 — the " + "reference fleet was at 85% when the condition was found by hand."),
+    fail_pct: exports_external.number().int().min(2).max(100).default(90).describe("Used-percentage at or above which `switchroom doctor` FAILs. Must " + "be greater than `warn_pct`. Default 90."),
+    reap_report: exports_external.object({
+      enabled: exports_external.boolean().default(true).describe("Whether doctor checks that the report-only worktree sweep " + "(`switchroom worktree reap-report --append <file>`) is actually " + "running. Set false on a host that deliberately does not run it."),
+      log: exports_external.string().min(1).default("/var/log/switchroom/reap-report.jsonl").describe("Path of the JSONL evidence log the scheduled `worktree " + "reap-report --append` writes. Doctor reads the newest record's " + "`generatedAt` — it detects the sweep by its OUTPUT, so it is " + "agnostic about whether an operator crontab, /etc/cron.d, or a " + "systemd timer drives it. Default " + "/var/log/switchroom/reap-report.jsonl (the path documented in " + "docs/operators/worktree-gc.md)."),
+      max_age_hours: exports_external.number().int().min(1).max(720).default(48).describe("How old the newest record in `log` may be before doctor WARNs " + "that the sweep has stopped running. Default 48 — twice the " + "documented daily cadence, so a single missed run is not noise.")
+    }).default({}).describe("Liveness check for the report-only worktree sweep. REPORT-ONLY by " + "construction: doctor reads an evidence log and never invokes any " + "reclaim path.")
+  }).refine((v) => v.fail_pct > v.warn_pct, {
+    message: "disk.fail_pct must be greater than disk.warn_pct",
+    path: ["fail_pct"]
+  });
   HostControlConfigSchema = exports_external.object({
     enabled: exports_external.boolean().default(true).describe("Whether the host-control daemon is in use. Default: true (since " + "RFC C Phase 2 default-flip — the gateway's /restart, /new, /reset, " + "and /update apply slash-commands all dispatch through hostd, and " + "without it those verbs fail on docker-mode installs because the " + "agent container has no docker binary/socket). " + "When true, the compose generator emits per-agent bind mounts " + "at `~/.switchroom/hostd/<name>/sock` for every admin-flagged " + "agent. Install the daemon with `switchroom hostd install` — " + "it runs as a docker container in its own compose project " + "(`switchroom-hostd`), separate from the agent fleet's compose " + "project so `up -d --remove-orphans` cycles of the fleet " + "can't recreate the daemon mid-RPC. See RFC C §5.1. " + "Set enabled: false only on legacy systemd-mode installs that " + "still rely on the in-container `spawnSwitchroomDetached` " + "shellout (removal is tracked as RFC C Phase 3)."),
     auto_release_check: AutoReleaseCheckSchema.default({}).describe("Pull-based release-triggered fleet restart (#1743). hostd polls " + "the remote release tag on a fixed interval and applies + " + "restarts the fleet (graceful) when a new release is detected. " + "Opt-in: default enabled=false.")
@@ -11941,6 +11962,8 @@ var init_schema = __esm(() => {
     microsoft_workspace: MicrosoftWorkspaceConfigSchema.describe("RFC #1873 (Microsoft 365 integration). Top-level Microsoft Workspace " + "configuration — OAuth client credentials (Entra app), authority " + "endpoint (defaults to /common for personal MSA + work), and the " + "org_mode opt-in for Teams/SharePoint surfaces. Block is optional; " + "when omitted the broker does not register the Microsoft provider."),
     notion_workspace: NotionWorkspaceConfigSchema.describe("RFC reference/rfcs/notion-integration.md. Top-level Notion integration " + "config — vault key for the integration token, friendly-name → " + "database UUID map, optional MCP-package version pin, and optional " + "global rate-limit override (default 3 rps, Notion's documented " + "public-API limit). Block is optional; when omitted no agent gets a " + "Notion MCP entry regardless of per-agent config."),
     quota: QuotaConfigSchema.optional().describe("Optional weekly/monthly USD spend budgets rendered in the session " + "greeting. Usage is read from ccusage at runtime; no network calls."),
+    scratch: ScratchConfigSchema.optional().describe("Per-agent scratch volume. Relocates every agent's build/package " + "caches (uv, npm, bun, playwright, puppeteer, pip user-site) off the " + "root disk onto a bulk device, bind-mounted at /scratch inside each " + "container. Framework-injected for EVERY agent — not routed through " + "the admin-only `bind_mounts:` escalation, because the biggest cache " + "consumers are ordinary non-admin agents. Omit the block to accept " + "defaults; the feature is a no-op unless `scratch.volume` exists on " + "the host."),
+    disk: DiskConfigSchema.default({}).describe("Root-disk headroom thresholds for `switchroom doctor`. Measured " + "against the filesystem holding the agents directory (and the scratch " + "volume when that feature is engaged), not against `/`. Omit the block " + "to accept the defaults (WARN at 80% used, FAIL at 90%)."),
     host_control: HostControlConfigSchema.default({}).describe("Host-control daemon configuration. Defaults to enabled=true since " + "RFC C Phase 2 (reference/rfcs/host-control-daemon.md). Omit the block " + "to accept defaults; set `enabled: false` only on legacy systemd-" + "mode installs (removal tracked as RFC C Phase 3)."),
     hostd: HostdConfigSchema.default({}).describe("hostd verb-level knobs (RFC admin-agent-config-edit). Distinct " + "from `host_control:` which governs whether the daemon runs at " + "all. Scopes the opt-in flag and rate cap for the " + "`config_propose_edit` verb (disabled by default)."),
     fleet_health: FleetHealthConfigSchema.default({}).describe("Fleet Health — job-spec-anchored, operator-facing issue tracker (RFC " + "fleet-health.md, serves fleet-stays-healthy). Assigns the owner agent " + "that runs the nightly model-free sensor + weekly deep-dive. Default " + "unset owner_agent → inert; the admin page renders an empty state."),
@@ -21565,7 +21588,7 @@ function allocateAgentUid(name) {
 }
 
 // src/build-info.ts
-var VERSION = "0.21.12";
+var VERSION = "0.21.13";
 
 // src/setup/hindsight-recall-passthrough.ts
 var HINDSIGHT_RECALL_TAG_WEIGHT_SEED = Object.freeze({ sidechain: 0.8 });

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

@@ -4434,7 +4434,7 @@ var init_observation_scopes = __esm(() => {
 });
 
 // src/config/schema.ts
-var CodeRepoEntrySchema, AgentBindMountSchema, HttpDiffPollSchema, PollSpecSchema, TelegramMessageActionSchema, WebhookActionSchema, ActionSpecSchema, ScheduleEntrySchema, AgentSoulSchema, AgentToolsSchema, ObservationScopesSchema, ObservationScopeStrategySchema, AntiConfabulationDirectiveSchema, AgentMemorySchema, HookEntrySchema, AgentHooksSchema, SubagentSchema, SessionSchema, SessionContinuitySchema, webhookDispatchRule, TelegramChannelSchema, BuzzChannelSchema, ChannelsSchema, TIMEZONE_REGEX, ApproverIdSchema, GoogleWorkspaceTierSchema, GoogleServiceTokenSchema, 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, AgentSchema, TelegramConfigSchema, MemoryBackendConfigSchema, VaultConfigSchema, QuotaConfigSchema, AutoReleaseCheckSchema, HostControlConfigSchema, WebServiceConfigSchema, FleetHealthConfigSchema, HostdConfigSchema, CronEgressSchema, CronConfigSchema, UserSchema, ConfigRepoConfigSchema, SwitchroomConfigSchema;
+var CodeRepoEntrySchema, AgentBindMountSchema, HttpDiffPollSchema, PollSpecSchema, TelegramMessageActionSchema, WebhookActionSchema, ActionSpecSchema, ScheduleEntrySchema, AgentSoulSchema, AgentToolsSchema, ObservationScopesSchema, ObservationScopeStrategySchema, AntiConfabulationDirectiveSchema, AgentMemorySchema, HookEntrySchema, AgentHooksSchema, SubagentSchema, SessionSchema, SessionContinuitySchema, webhookDispatchRule, TelegramChannelSchema, BuzzChannelSchema, ChannelsSchema, TIMEZONE_REGEX, ApproverIdSchema, GoogleWorkspaceTierSchema, GoogleServiceTokenSchema, 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, AgentSchema, TelegramConfigSchema, MemoryBackendConfigSchema, VaultConfigSchema, QuotaConfigSchema, AutoReleaseCheckSchema, ScratchConfigSchema, DiskConfigSchema, HostControlConfigSchema, WebServiceConfigSchema, FleetHealthConfigSchema, HostdConfigSchema, CronEgressSchema, CronConfigSchema, UserSchema, ConfigRepoConfigSchema, SwitchroomConfigSchema;
 var init_schema = __esm(() => {
   init_zod();
   init_observation_scopes();
@@ -5307,6 +5307,27 @@ var init_schema = __esm(() => {
     notify_on_detect: exports_external.boolean().default(false).describe("KEN-129 — operator-in-the-loop update prompt. Only consulted " + "when apply_on_detect is false (auto-apply supersedes notify): " + "a newly detected release posts ONE operator approval card " + "('fleet is behind — tap to apply') via an admin agent's " + "gateway; Approve runs hostd's update_apply path (fleet-" + "mutation-locked, durable status rows, get_status-pollable). " + "Dedup on release id: the last-notified id persists in " + "~/.switchroom/release-notify-state.json, so a card that " + "reached the operator is never re-posted for the same release."),
     image_ref: exports_external.string().default("ghcr.io/switchroom/switchroom-agent:latest").describe("Image reference whose remote digest is compared to the local " + "image digest. Defaults to the agent image's :latest tag, which " + "is the canonical signal that a release has been promoted.")
   });
+  ScratchConfigSchema = exports_external.object({
+    enabled: exports_external.boolean().default(true).describe("Whether agents get a scratch mount at /scratch with their package " + "caches redirected there. Default: true — but the feature only " + "engages when `volume` actually exists on the host, so a single-disk " + "machine is unaffected. Set false to opt out even where it does."),
+    volume: exports_external.string().refine((v) => v.startsWith("/"), {
+      message: "scratch.volume must be an absolute host path"
+    }).default("/mnt/bulkdata").describe("Absolute host path of the bulk device's mountpoint. MUST already " + "exist — its presence is the single probe that turns the feature on, " + "so a typo degrades to the pre-existing behaviour rather than " + "quietly relocating caches somewhere that is still the root disk. " + "Default: /mnt/bulkdata."),
+    subdir: exports_external.string().refine((v) => !v.startsWith("/") && !v.split("/").includes(".."), {
+      message: "scratch.subdir must be a relative path without '..' segments"
+    }).default("switchroom/scratch").describe("Relative path under `volume` holding the per-agent scratch " + "directories (`<volume>/<subdir>/<agent>`). Default: " + "switchroom/scratch.")
+  });
+  DiskConfigSchema = exports_external.object({
+    warn_pct: exports_external.number().int().min(1).max(99).default(80).describe("Used-percentage at or above which `switchroom doctor` WARNs about " + "the filesystem holding the agents directory. Default 80 — the " + "reference fleet was at 85% when the condition was found by hand."),
+    fail_pct: exports_external.number().int().min(2).max(100).default(90).describe("Used-percentage at or above which `switchroom doctor` FAILs. Must " + "be greater than `warn_pct`. Default 90."),
+    reap_report: exports_external.object({
+      enabled: exports_external.boolean().default(true).describe("Whether doctor checks that the report-only worktree sweep " + "(`switchroom worktree reap-report --append <file>`) is actually " + "running. Set false on a host that deliberately does not run it."),
+      log: exports_external.string().min(1).default("/var/log/switchroom/reap-report.jsonl").describe("Path of the JSONL evidence log the scheduled `worktree " + "reap-report --append` writes. Doctor reads the newest record's " + "`generatedAt` — it detects the sweep by its OUTPUT, so it is " + "agnostic about whether an operator crontab, /etc/cron.d, or a " + "systemd timer drives it. Default " + "/var/log/switchroom/reap-report.jsonl (the path documented in " + "docs/operators/worktree-gc.md)."),
+      max_age_hours: exports_external.number().int().min(1).max(720).default(48).describe("How old the newest record in `log` may be before doctor WARNs " + "that the sweep has stopped running. Default 48 — twice the " + "documented daily cadence, so a single missed run is not noise.")
+    }).default({}).describe("Liveness check for the report-only worktree sweep. REPORT-ONLY by " + "construction: doctor reads an evidence log and never invokes any " + "reclaim path.")
+  }).refine((v) => v.fail_pct > v.warn_pct, {
+    message: "disk.fail_pct must be greater than disk.warn_pct",
+    path: ["fail_pct"]
+  });
   HostControlConfigSchema = exports_external.object({
     enabled: exports_external.boolean().default(true).describe("Whether the host-control daemon is in use. Default: true (since " + "RFC C Phase 2 default-flip — the gateway's /restart, /new, /reset, " + "and /update apply slash-commands all dispatch through hostd, and " + "without it those verbs fail on docker-mode installs because the " + "agent container has no docker binary/socket). " + "When true, the compose generator emits per-agent bind mounts " + "at `~/.switchroom/hostd/<name>/sock` for every admin-flagged " + "agent. Install the daemon with `switchroom hostd install` — " + "it runs as a docker container in its own compose project " + "(`switchroom-hostd`), separate from the agent fleet's compose " + "project so `up -d --remove-orphans` cycles of the fleet " + "can't recreate the daemon mid-RPC. See RFC C §5.1. " + "Set enabled: false only on legacy systemd-mode installs that " + "still rely on the in-container `spawnSwitchroomDetached` " + "shellout (removal is tracked as RFC C Phase 3)."),
     auto_release_check: AutoReleaseCheckSchema.default({}).describe("Pull-based release-triggered fleet restart (#1743). hostd polls " + "the remote release tag on a fixed interval and applies + " + "restarts the fleet (graceful) when a new release is detected. " + "Opt-in: default enabled=false.")
@@ -5381,6 +5402,8 @@ var init_schema = __esm(() => {
     microsoft_workspace: MicrosoftWorkspaceConfigSchema.describe("RFC #1873 (Microsoft 365 integration). Top-level Microsoft Workspace " + "configuration — OAuth client credentials (Entra app), authority " + "endpoint (defaults to /common for personal MSA + work), and the " + "org_mode opt-in for Teams/SharePoint surfaces. Block is optional; " + "when omitted the broker does not register the Microsoft provider."),
     notion_workspace: NotionWorkspaceConfigSchema.describe("RFC reference/rfcs/notion-integration.md. Top-level Notion integration " + "config — vault key for the integration token, friendly-name → " + "database UUID map, optional MCP-package version pin, and optional " + "global rate-limit override (default 3 rps, Notion's documented " + "public-API limit). Block is optional; when omitted no agent gets a " + "Notion MCP entry regardless of per-agent config."),
     quota: QuotaConfigSchema.optional().describe("Optional weekly/monthly USD spend budgets rendered in the session " + "greeting. Usage is read from ccusage at runtime; no network calls."),
+    scratch: ScratchConfigSchema.optional().describe("Per-agent scratch volume. Relocates every agent's build/package " + "caches (uv, npm, bun, playwright, puppeteer, pip user-site) off the " + "root disk onto a bulk device, bind-mounted at /scratch inside each " + "container. Framework-injected for EVERY agent — not routed through " + "the admin-only `bind_mounts:` escalation, because the biggest cache " + "consumers are ordinary non-admin agents. Omit the block to accept " + "defaults; the feature is a no-op unless `scratch.volume` exists on " + "the host."),
+    disk: DiskConfigSchema.default({}).describe("Root-disk headroom thresholds for `switchroom doctor`. Measured " + "against the filesystem holding the agents directory (and the scratch " + "volume when that feature is engaged), not against `/`. Omit the block " + "to accept the defaults (WARN at 80% used, FAIL at 90%)."),
     host_control: HostControlConfigSchema.default({}).describe("Host-control daemon configuration. Defaults to enabled=true since " + "RFC C Phase 2 (reference/rfcs/host-control-daemon.md). Omit the block " + "to accept defaults; set `enabled: false` only on legacy systemd-" + "mode installs (removal tracked as RFC C Phase 3)."),
     hostd: HostdConfigSchema.default({}).describe("hostd verb-level knobs (RFC admin-agent-config-edit). Distinct " + "from `host_control:` which governs whether the daemon runs at " + "all. Scopes the opt-in flag and rate cap for the " + "`config_propose_edit` verb (disabled by default)."),
     fleet_health: FleetHealthConfigSchema.default({}).describe("Fleet Health — job-spec-anchored, operator-facing issue tracker (RFC " + "fleet-health.md, serves fleet-stays-healthy). Assigns the owner agent " + "that runs the nightly model-free sensor + weekly deep-dive. Default " + "unset owner_agent → inert; the admin page renders an empty state."),

package/dist/vault/broker/server.js

@@ -4030,7 +4030,7 @@ var init_observation_scopes = __esm(() => {
 });
 
 // src/config/schema.ts
-var CodeRepoEntrySchema, AgentBindMountSchema, HttpDiffPollSchema, PollSpecSchema, TelegramMessageActionSchema, WebhookActionSchema, ActionSpecSchema, ScheduleEntrySchema, AgentSoulSchema, AgentToolsSchema, ObservationScopesSchema, ObservationScopeStrategySchema, AntiConfabulationDirectiveSchema, AgentMemorySchema, HookEntrySchema, AgentHooksSchema, SubagentSchema, SessionSchema, SessionContinuitySchema, webhookDispatchRule, TelegramChannelSchema, BuzzChannelSchema, ChannelsSchema, TIMEZONE_REGEX, ApproverIdSchema, GoogleWorkspaceTierSchema, GoogleServiceTokenSchema, 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, AgentSchema, TelegramConfigSchema, MemoryBackendConfigSchema, VaultConfigSchema, QuotaConfigSchema, AutoReleaseCheckSchema, HostControlConfigSchema, WebServiceConfigSchema, FleetHealthConfigSchema, HostdConfigSchema, CronEgressSchema, CronConfigSchema, UserSchema, ConfigRepoConfigSchema, SwitchroomConfigSchema;
+var CodeRepoEntrySchema, AgentBindMountSchema, HttpDiffPollSchema, PollSpecSchema, TelegramMessageActionSchema, WebhookActionSchema, ActionSpecSchema, ScheduleEntrySchema, AgentSoulSchema, AgentToolsSchema, ObservationScopesSchema, ObservationScopeStrategySchema, AntiConfabulationDirectiveSchema, AgentMemorySchema, HookEntrySchema, AgentHooksSchema, SubagentSchema, SessionSchema, SessionContinuitySchema, webhookDispatchRule, TelegramChannelSchema, BuzzChannelSchema, ChannelsSchema, TIMEZONE_REGEX, ApproverIdSchema, GoogleWorkspaceTierSchema, GoogleServiceTokenSchema, 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, AgentSchema, TelegramConfigSchema, MemoryBackendConfigSchema, VaultConfigSchema, QuotaConfigSchema, AutoReleaseCheckSchema, ScratchConfigSchema, DiskConfigSchema, HostControlConfigSchema, WebServiceConfigSchema, FleetHealthConfigSchema, HostdConfigSchema, CronEgressSchema, CronConfigSchema, UserSchema, ConfigRepoConfigSchema, SwitchroomConfigSchema;
 var init_schema = __esm(() => {
   init_zod();
   init_observation_scopes();
@@ -4903,6 +4903,27 @@ var init_schema = __esm(() => {
     notify_on_detect: exports_external.boolean().default(false).describe("KEN-129 — operator-in-the-loop update prompt. Only consulted " + "when apply_on_detect is false (auto-apply supersedes notify): " + "a newly detected release posts ONE operator approval card " + "('fleet is behind — tap to apply') via an admin agent's " + "gateway; Approve runs hostd's update_apply path (fleet-" + "mutation-locked, durable status rows, get_status-pollable). " + "Dedup on release id: the last-notified id persists in " + "~/.switchroom/release-notify-state.json, so a card that " + "reached the operator is never re-posted for the same release."),
     image_ref: exports_external.string().default("ghcr.io/switchroom/switchroom-agent:latest").describe("Image reference whose remote digest is compared to the local " + "image digest. Defaults to the agent image's :latest tag, which " + "is the canonical signal that a release has been promoted.")
   });
+  ScratchConfigSchema = exports_external.object({
+    enabled: exports_external.boolean().default(true).describe("Whether agents get a scratch mount at /scratch with their package " + "caches redirected there. Default: true — but the feature only " + "engages when `volume` actually exists on the host, so a single-disk " + "machine is unaffected. Set false to opt out even where it does."),
+    volume: exports_external.string().refine((v) => v.startsWith("/"), {
+      message: "scratch.volume must be an absolute host path"
+    }).default("/mnt/bulkdata").describe("Absolute host path of the bulk device's mountpoint. MUST already " + "exist — its presence is the single probe that turns the feature on, " + "so a typo degrades to the pre-existing behaviour rather than " + "quietly relocating caches somewhere that is still the root disk. " + "Default: /mnt/bulkdata."),
+    subdir: exports_external.string().refine((v) => !v.startsWith("/") && !v.split("/").includes(".."), {
+      message: "scratch.subdir must be a relative path without '..' segments"
+    }).default("switchroom/scratch").describe("Relative path under `volume` holding the per-agent scratch " + "directories (`<volume>/<subdir>/<agent>`). Default: " + "switchroom/scratch.")
+  });
+  DiskConfigSchema = exports_external.object({
+    warn_pct: exports_external.number().int().min(1).max(99).default(80).describe("Used-percentage at or above which `switchroom doctor` WARNs about " + "the filesystem holding the agents directory. Default 80 — the " + "reference fleet was at 85% when the condition was found by hand."),
+    fail_pct: exports_external.number().int().min(2).max(100).default(90).describe("Used-percentage at or above which `switchroom doctor` FAILs. Must " + "be greater than `warn_pct`. Default 90."),
+    reap_report: exports_external.object({
+      enabled: exports_external.boolean().default(true).describe("Whether doctor checks that the report-only worktree sweep " + "(`switchroom worktree reap-report --append <file>`) is actually " + "running. Set false on a host that deliberately does not run it."),
+      log: exports_external.string().min(1).default("/var/log/switchroom/reap-report.jsonl").describe("Path of the JSONL evidence log the scheduled `worktree " + "reap-report --append` writes. Doctor reads the newest record's " + "`generatedAt` — it detects the sweep by its OUTPUT, so it is " + "agnostic about whether an operator crontab, /etc/cron.d, or a " + "systemd timer drives it. Default " + "/var/log/switchroom/reap-report.jsonl (the path documented in " + "docs/operators/worktree-gc.md)."),
+      max_age_hours: exports_external.number().int().min(1).max(720).default(48).describe("How old the newest record in `log` may be before doctor WARNs " + "that the sweep has stopped running. Default 48 — twice the " + "documented daily cadence, so a single missed run is not noise.")
+    }).default({}).describe("Liveness check for the report-only worktree sweep. REPORT-ONLY by " + "construction: doctor reads an evidence log and never invokes any " + "reclaim path.")
+  }).refine((v) => v.fail_pct > v.warn_pct, {
+    message: "disk.fail_pct must be greater than disk.warn_pct",
+    path: ["fail_pct"]
+  });
   HostControlConfigSchema = exports_external.object({
     enabled: exports_external.boolean().default(true).describe("Whether the host-control daemon is in use. Default: true (since " + "RFC C Phase 2 default-flip — the gateway's /restart, /new, /reset, " + "and /update apply slash-commands all dispatch through hostd, and " + "without it those verbs fail on docker-mode installs because the " + "agent container has no docker binary/socket). " + "When true, the compose generator emits per-agent bind mounts " + "at `~/.switchroom/hostd/<name>/sock` for every admin-flagged " + "agent. Install the daemon with `switchroom hostd install` — " + "it runs as a docker container in its own compose project " + "(`switchroom-hostd`), separate from the agent fleet's compose " + "project so `up -d --remove-orphans` cycles of the fleet " + "can't recreate the daemon mid-RPC. See RFC C §5.1. " + "Set enabled: false only on legacy systemd-mode installs that " + "still rely on the in-container `spawnSwitchroomDetached` " + "shellout (removal is tracked as RFC C Phase 3)."),
     auto_release_check: AutoReleaseCheckSchema.default({}).describe("Pull-based release-triggered fleet restart (#1743). hostd polls " + "the remote release tag on a fixed interval and applies + " + "restarts the fleet (graceful) when a new release is detected. " + "Opt-in: default enabled=false.")
@@ -4977,6 +4998,8 @@ var init_schema = __esm(() => {
     microsoft_workspace: MicrosoftWorkspaceConfigSchema.describe("RFC #1873 (Microsoft 365 integration). Top-level Microsoft Workspace " + "configuration — OAuth client credentials (Entra app), authority " + "endpoint (defaults to /common for personal MSA + work), and the " + "org_mode opt-in for Teams/SharePoint surfaces. Block is optional; " + "when omitted the broker does not register the Microsoft provider."),
     notion_workspace: NotionWorkspaceConfigSchema.describe("RFC reference/rfcs/notion-integration.md. Top-level Notion integration " + "config — vault key for the integration token, friendly-name → " + "database UUID map, optional MCP-package version pin, and optional " + "global rate-limit override (default 3 rps, Notion's documented " + "public-API limit). Block is optional; when omitted no agent gets a " + "Notion MCP entry regardless of per-agent config."),
     quota: QuotaConfigSchema.optional().describe("Optional weekly/monthly USD spend budgets rendered in the session " + "greeting. Usage is read from ccusage at runtime; no network calls."),
+    scratch: ScratchConfigSchema.optional().describe("Per-agent scratch volume. Relocates every agent's build/package " + "caches (uv, npm, bun, playwright, puppeteer, pip user-site) off the " + "root disk onto a bulk device, bind-mounted at /scratch inside each " + "container. Framework-injected for EVERY agent — not routed through " + "the admin-only `bind_mounts:` escalation, because the biggest cache " + "consumers are ordinary non-admin agents. Omit the block to accept " + "defaults; the feature is a no-op unless `scratch.volume` exists on " + "the host."),
+    disk: DiskConfigSchema.default({}).describe("Root-disk headroom thresholds for `switchroom doctor`. Measured " + "against the filesystem holding the agents directory (and the scratch " + "volume when that feature is engaged), not against `/`. Omit the block " + "to accept the defaults (WARN at 80% used, FAIL at 90%)."),
     host_control: HostControlConfigSchema.default({}).describe("Host-control daemon configuration. Defaults to enabled=true since " + "RFC C Phase 2 (reference/rfcs/host-control-daemon.md). Omit the block " + "to accept defaults; set `enabled: false` only on legacy systemd-" + "mode installs (removal tracked as RFC C Phase 3)."),
     hostd: HostdConfigSchema.default({}).describe("hostd verb-level knobs (RFC admin-agent-config-edit). Distinct " + "from `host_control:` which governs whether the daemon runs at " + "all. Scopes the opt-in flag and rate cap for the " + "`config_propose_edit` verb (disabled by default)."),
     fleet_health: FleetHealthConfigSchema.default({}).describe("Fleet Health — job-spec-anchored, operator-facing issue tracker (RFC " + "fleet-health.md, serves fleet-stays-healthy). Assigns the owner agent " + "that runs the nightly model-free sensor + weekly deep-dive. Default " + "unset owner_agent → inert; the admin page renders an empty state."),

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.21.12",
+  "version": "0.21.13",
   "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": {

package/skills/switchroom-architecture/SKILL.md

@@ -12,13 +12,15 @@ Switchroom is a multi-agent orchestrator built on Claude Code. It manages multip
 
 **One `switchroom.yaml` to rule them all.** All agents are configured from a single file using a three-layer cascade. See [cascade.md](cascade.md) for full merge semantics.
 
-**Agents as Docker containers.** Each agent runs as a long-lived `claude` process inside its own container (`switchroom-<name>`), supervised by Docker Compose with `restart: unless-stopped` and a healthcheck. The `start.sh` script sets environment variables and execs into `claude`. Claude Code handles session persistence and tool execution.
+**Agents as Docker containers.** Each agent runs as a long-lived `claude` process inside its own container (`switchroom-<name>`), supervised by Docker Compose with `restart: always` (`src/agents/compose.ts`). The agent service itself has NO healthcheck — it `depends_on` `vault-broker` (`service_started`), `approval-kernel` (`service_started`), and `switchroom-auth-broker` (`service_healthy`), so it waits on the auth-broker's healthcheck before booting. Healthchecks exist on `vault-broker`, `approval-kernel`, `switchroom-auth-broker`, and `voice-sidecar` — not on the agent container. The `start.sh` script sets environment variables and execs into `claude`. Claude Code handles session persistence and tool execution.
 
-**Telegram as the primary interface.** The `switchroom-telegram` MCP plugin connects Claude Code to Telegram, providing 10 tools for message handling. See [telegram.md](telegram.md) for details.
+**Telegram as the primary interface.** The `switchroom-telegram` MCP plugin connects Claude Code to Telegram, providing message-handling tools (see [telegram.md](telegram.md) for the current tool list and categories — don't hard-code a count here, it drifts).
 
 **Hindsight for memory.** Cross-session memory uses the Hindsight MCP server — a semantic vector store with knowledge graphs, mental models, and directives. Each agent has its own named collection.
 
-**Skills as reusable behavior.** Shared skills live in `~/.switchroom/skills/` (or `switchroom.skills_dir`). Scaffold symlinks selected skills into each agent's `skills/` directory. Claude Code loads them at session start.
+**Skills as reusable behavior.** Shared skills live in `~/.switchroom/skills/` (or `switchroom.skills_dir`). Scaffold symlinks selected skills into each agent's `.claude/skills/` directory (`src/agents/scaffold.ts`; `migrateLegacySkillsDir` migrates any pre-existing symlinks from the old `<agentDir>/skills/` location). Claude Code loads them at session start.
+
+**Beyond the agent containers.** The agent fleet's compose file (`generateCompose`, `src/agents/compose.ts`) emits the per-agent `switchroom-<name>` services plus three shared services every agent depends on: `vault-broker`, `approval-kernel`, and `switchroom-auth-broker` (agent `depends_on`, `src/agents/compose.ts` around `emitAgentService`'s `depends_on` block). Optionally, per-agent `voice-sidecar` services are emitted too. `hostd` (`src/cli/hostd.ts`) and `web` (`src/cli/webd.ts`) run as their OWN separate compose projects (`switchroom-hostd`, `switchroom-web`) — not part of the agent fleet compose file, and not self-healing on an image-pin bump the way agents are.
 
 ## Directory layout
 
@@ -34,10 +36,12 @@ Switchroom is a multi-agent orchestrator built on Claude Code. It manages multip
         ├── start.sh        # launcher (sets env, execs claude)
         ├── settings.json   # Claude Code settings
         ├── .mcp.json       # MCP server config
-        ├── CLAUDE.md       # agent identity (never overwritten by reconcile)
-        ├── skills/         # symlinks to ~/.switchroom/skills/<name>/
+        ├── CLAUDE.md       # agent identity (reconcile rewrites content ABOVE the
+        │                   # `# --- Yours ---` marker; below it always survives.
+        │                   # `--preserve-claude-md` opts out of the rewrite.)
         ├── .claude/
-        │   └── agents/     # sub-agent definition files
+        │   ├── agents/     # sub-agent definition files
+        │   └── skills/     # symlinks to ~/.switchroom/skills/<name>/
         └── telegram/
             ├── history.db  # SQLite message buffer
             └── access.json # per-agent access control
@@ -52,7 +56,7 @@ Switchroom is a multi-agent orchestrator built on Claude Code. It manages multip
 5. MCP servers connect (Hindsight, switchroom-telegram, others)
 6. Telegram plugin polls for messages
 7. User sends message → plugin fires `UserPromptSubmit` hook → Claude responds
-8. `switchroom agent reconcile <name>` — re-apply switchroom.yaml (no CLAUDE.md touch)
+8. `switchroom agent reconcile <name>` — re-apply switchroom.yaml (rewrites `.mcp.json` + `settings.json` + `start.sh` + CLAUDE.md's managed section above the `# --- Yours ---` marker; pass `--preserve-claude-md` to skip the CLAUDE.md rewrite)
 
 ## Deep dives
 

package/skills/switchroom-architecture/cascade.md

@@ -16,13 +16,16 @@ The resolved value at any field is determined by the **merge type** for that fie
 
 | Merge type | Fields | Behavior |
 |---|---|---|
-| **Union** | `tools.allow`, `tools.deny`, `skills` | Combine across all layers, dedup |
+| **Union** | `tools.allow`, `tools.deny`, `skills`, `secrets`, `allowed_tools`, `disallowed_tools`, `extra_stable_files` | Combine across all layers, dedup-preserving-order (defaults first) |
 | **Override** | `model`, `extends`, `dangerous_mode`, most scalars | Agent wins entirely |
-| **Per-key merge** | `mcp_servers`, `env`, `subagents` | Agent wins on key conflict, others preserved |
-| **Per-field merge** | `soul`, `memory`, `session`, `channels` | Agent wins per sub-field |
-| **Per-event concat** | `hooks` | Defaults appended first, then agent |
+| **Per-key merge** | `mcp_servers`, `env`, `bundled_skills` | Agent wins on key conflict, others preserved |
+| **Per-key merge with field-level merge on conflict** | `subagents` | Agent wins per key; on a key present at both layers, fields are merged field-by-field (not a whole-definition replacement — that was the pre-#682 bug) |
+| **Per-field merge** | `soul`, `session`, `session_continuity`, `channels`, `reactions`, `reaction_dispatch` | Agent wins per sub-field. `channels` and `reactions`/`reaction_dispatch` sub-arrays (e.g. `trigger_emojis`) use REPLACE semantics, not union. |
+| **One-level-deep merge** | `memory` (`recall`/`retain`/`disposition` sub-objects), `litellm` (scalars + per-key `tags`) | Top-level fields override; the named sub-object merges one level deep instead of replacing wholesale, so overriding one knob doesn't drop its siblings |
+| **Per-event concat** | `hooks` | Defaults appended first, then agent (no dedup — identical entries may be intentional) |
 | **Concatenate** | `schedule`, `system_prompt_append`, `claude_md_raw`, `cli_args` | Defaults prepended |
 | **Deep merge** | `settings_raw` | Recursive object merge, agent wins |
+| **Replace-if-unset** | `release` | Whole-block replace; an agent-declared `release` is NOT field-merged with defaults (deliberate — a pinned agent must not silently inherit a channel/pin from the fleet, or vice versa) |
 
 ## Examples
 
@@ -65,7 +68,7 @@ Prefer TypeScript.
 Never use `any`.
 ```
 
-### subagents per-key merge
+### subagents per-key merge with field-level merge on conflict
 ```yaml
 defaults:
   subagents:
@@ -77,11 +80,16 @@ agents:
   dev:
     subagents:
       worker:
-        description: "Code implementation with tests"  # replaces default worker
-        model: sonnet
-        tools: [Read, Edit, Write, Bash]
+        description: "Code implementation with tests"  # overrides only this field
+        tools: [Read, Edit, Write, Bash]                # added; model still inherited
     # researcher and reviewer inherited from defaults unchanged
 ```
+`worker`'s resolved definition is `{ description: "Code implementation with
+tests", model: sonnet, tools: [Read, Edit, Write, Bash] }` — the agent layer
+merges field-by-field onto the matching default key, it does not replace the
+whole `worker` definition (`src/config/merge.ts`, `subagents: per-key merge,
+with field-level merge on conflict`; whole-def replacement was the pre-#682
+bug this fixed).
 
 ### hooks per-event concat
 ```yaml
@@ -103,10 +111,21 @@ agents:
 Profiles can be defined in two places (inline takes priority):
 
 1. **Inline** in `profiles:` section of switchroom.yaml
-2. **Filesystem** at `profiles/<name>/` — contains `CLAUDE.md.hbs`, `SOUL.md.hbs`, optional `skills/`
+2. **Filesystem** at `profiles/<name>/` — contains `CLAUDE.md.hbs`, plus optional `SOUL.md.hbs` and `skills/`
 
 An agent inherits from at most one profile via `extends: <name>`. Profiles themselves do not chain.
 
 ## Vault references
 
-Secrets in switchroom.yaml use `vault:key-name` syntax. They're resolved at scaffold/reconcile time from `~/.switchroom/vault.enc`. Vault values are written into `start.sh` as environment variables — never stored in plaintext in switchroom.yaml.
+Secrets in switchroom.yaml use `vault:key-name` syntax; `vault:<key>#<filename>`
+additionally inlines one named file's contents as a string from a
+`kind: "files"` vault entry (`src/vault/resolver.ts:194`,
+`resolveSingleReference`). At scaffold/reconcile time these are resolved
+from `~/.switchroom/vault.enc` and written into `start.sh` as environment
+variables — never stored in plaintext in switchroom.yaml.
+
+In production, agent-runtime vault reads do NOT go through that scaffold-time
+decrypt path — they go through the vault-broker daemon over a local socket
+(`resolveVaultReferencesViaBroker`, `src/vault/resolver.ts:288`), which is
+what enforces the per-agent grant/deny model (`VAULT-BROKER-DENIED`,
+`vault_request_access`) documented for agents at runtime.

package/skills/switchroom-architecture/sub-agents.md

@@ -2,9 +2,15 @@
 
 Switchroom generates Claude Code custom sub-agent files (`.claude/agents/<name>.md`) from `switchroom.yaml`. This enables the "Opus plans, Sonnet implements" pattern: the main agent delegates to cheaper models running in the background.
 
-## Default sub-agents
+## Default sub-agents (starter template, not a hard-coded default)
 
-Switchroom ships three default sub-agents that every agent inherits:
+`subagents` is `.optional()` with no schema-level `.default()`
+(`src/config/schema.ts`), and nothing in `src/agents/scaffold.ts` injects a
+worker/researcher/reviewer set — an agent with no `subagents` block anywhere
+in its cascade simply has none. The three-sub-agent pattern below is the
+**starter template** shipped in `examples/switchroom.yaml` (`worker` at
+`:111`, `researcher` at `:137`, `reviewer` at `:149`), not something
+switchroom ships by default:
 
 | Sub-agent | Model | Purpose |
 |-----------|-------|---------|
@@ -12,7 +18,9 @@ Switchroom ships three default sub-agents that every agent inherits:
 | **researcher** | Haiku | Exploration — codebase search, docs, investigation |
 | **reviewer** | Sonnet | Quality review — correctness, completeness, security |
 
-These are defined in `defaults.subagents` and flow through the cascade to every agent.
+If you want this pattern, declare it under `defaults.subagents` (or a
+profile) yourself — copy it from `examples/switchroom.yaml` — and it will
+then flow through the cascade to every agent.
 
 ## How delegation works
 
@@ -30,15 +38,15 @@ Each sub-agent supports the full Claude Code frontmatter spec:
 
 | Field | Description |
 |-------|-------------|
-| `description` | (required) When the main agent should delegate here |
+| `description` | Schema-optional (a partial override, e.g. `isolation` only, need not restate it — the cascade retains the base definition's description on merge) but effectively required for a fresh, non-overriding definition: when the main agent should delegate here |
 | `model` | `sonnet`, `opus`, `haiku`, full model ID, or `inherit` |
 | `background` | Run non-blocking. Default: false |
 | `isolation` | `worktree` — own git branch for file work |
 | `tools` | Tool allowlist (inherits all if omitted) |
 | `disallowedTools` | Tool denylist |
 | `maxTurns` | Auto-stop after N turns |
-| `permissionMode` | `default`, `acceptEdits`, `auto`, `bypassPermissions`, `plan` |
-| `effort` | `low`, `medium`, `high`, `max` |
+| `permissionMode` | `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, `plan` |
+| `effort` | `low`, `medium`, `high`, `xhigh`, `max` |
 | `color` | Display color in task list |
 | `memory` | `user`, `project`, or `local` for persistent learning |
 | `skills` | Skills to preload |
@@ -46,7 +54,7 @@ Each sub-agent supports the full Claude Code frontmatter spec:
 
 ## Cascade behavior
 
-Sub-agents are **per-key merged**. An agent overrides a specific sub-agent by declaring one with the same name:
+Sub-agents are **per-key merged, with field-level merge on conflict** (`src/config/merge.ts`) — see [cascade.md](cascade.md). An agent overrides a specific sub-agent by declaring one with the same name; only the fields it sets are replaced, everything else is inherited from the base definition:
 
 ```yaml
 defaults:
@@ -66,22 +74,15 @@ agents:
       # researcher and reviewer inherited unchanged from defaults
 ```
 
-## Model resolution order (highest wins)
-
-1. `CLAUDE_CODE_SUBAGENT_MODEL` env var — switchroom deliberately doesn't set this (it would override ALL sub-agents including Claude Code built-ins)
-2. Per-invocation `model` parameter (user/main-agent override)
-3. Sub-agent file's `model` frontmatter (what switchroom sets)
-4. Main conversation's model
-
-## Coexistence with Claude Code built-ins
-
-| Agent | Model | Origin |
-|-------|-------|--------|
-| Explore | Haiku | Claude Code built-in |
-| Plan | Inherit | Claude Code built-in |
-| general-purpose | Inherit | Claude Code built-in |
-| worker | Sonnet | Switchroom default |
-| researcher | Haiku | Switchroom default |
-| reviewer | Sonnet | Switchroom default |
-
-All sub-agents share the same `.claude/agents/` directory. Switchroom-generated files don't conflict with Claude Code's built-ins.
+## Model resolution and Claude Code's built-in sub-agents
+
+How Claude Code itself resolves a sub-agent's model (env var precedence,
+per-invocation overrides) and how switchroom-generated `.claude/agents/*.md`
+files coexist with Claude Code's own built-in sub-agents (e.g. Explore,
+Plan, general-purpose) is upstream Claude Code CLI behaviour — this repo's
+`src/` has no code that reads or sets a `CLAUDE_CODE_SUBAGENT_MODEL` env var,
+so switchroom's own source cannot confirm or deny any specific precedence
+order or built-in roster here. Consult Anthropic's Claude Code documentation
+for the authoritative answer; all switchroom does is render one `.md` file
+per configured sub-agent into `.claude/agents/<name>.md` and let Claude Code
+own everything downstream of that file.

package/skills/switchroom-architecture/telegram.md

@@ -2,32 +2,45 @@
 
 Switchroom ships an enhanced `switchroom-telegram` MCP plugin that replaces the official marketplace plugin. It is the default — no configuration needed.
 
-## 9 MCP tools
-
-| Tool | What it does |
-|------|-------------|
-| `reply` | Send text, photos, or documents — the single final-answer tool. Chunks anything over the 32768-char rich-message cap (4096 applies only to plain-text degradations). Supports threading, topic routing, file attachments. |
-| `react` | Add emoji reactions to messages (Telegram whitelist: 👍 👎 ❤️ 🔥 👀 🎉 etc). |
-| `edit_message` | Update a previously sent message. Edits are silent (no push notification). |
-| `delete_message` | Remove a bot-sent message (48h Telegram API limit). |
-| `forward_message` | Quote/resurface earlier messages with thread support. |
-| `send_typing` | Show typing indicator (5s auto-expire). Use during long operations. |
-| `download_attachment` | Fetch files attached to inbound messages. |
-| `get_recent_messages` | Query SQLite history buffer with pagination and thread filtering. |
+## MCP tools
+
+The plugin's tool count changes as features land — don't hard-code a number
+here; `telegram-plugin/bridge/bridge.ts`'s `TOOL_SCHEMAS` array is the source
+of truth. As of this writing it defines 21 tool schemas, grouped by purpose:
+
+| Category | Tools | What it does |
+|----------|-------|-------------|
+| Messaging | `reply`, `edit_message`, `delete_message`, `forward_message`, `progress_update` | `reply` is the single final-answer tool — send text, photos, or documents. Chunks anything over the 32768-char rich-message cap (4096 applies only to plain-text degradations). Supports threading, topic routing, file attachments. `edit_message` updates a previously sent message silently (no push notification). `delete_message` removes a bot-sent message (48h Telegram API limit). `forward_message` quotes/resurfaces earlier messages with thread support. `progress_update` posts a short interim status line mid-turn. |
+| Interactivity | `react`, `send_typing`, `ask_user`, `send_checklist`, `update_checklist`, `send_sticker`, `send_gif` | `react` adds emoji reactions (Telegram whitelist). `send_typing` shows a typing indicator (5s auto-expire). `ask_user` blocks for a structured reply. `send_checklist`/`update_checklist` render and mutate a tappable checklist card. `send_sticker`/`send_gif` send media. |
+| History & attachments | `download_attachment`, `get_recent_messages` | Fetch files attached to inbound messages; query the SQLite history buffer with pagination and thread filtering. |
+| Vault & secrets | `vault_request_save`, `vault_request_access`, `request_secret` | Post approval cards for saving/granting/requesting vault-backed secrets. |
+| Memory | `mental_model_propose` | Post an approval card to create/refresh a Hindsight mental model. |
+| Linear (conditional) | `linear_agent_activity`, `linear_create_issue`, `linear_agent_setup` | Only registered when Linear integration is configured for the agent. |
 
 ## Emoji status lifecycle
 
-The plugin automatically reacts to inbound messages with a lifecycle progression:
+The plugin automatically reacts to inbound messages with a state machine
+(`telegram-plugin/status-reactions.ts`) tracking CURRENT TURN ACTIVITY, not
+delivery state. The real state set: `queued, thinking, coding, web,
+compacting, awaiting, undelivered, error, stallSoft, stallHard`. Working
+states (`thinking`, `tool`, `coding`, `web`, `compacting`) cycle freely and
+bidirectionally within one turn — none is "higher" than another. The only
+terminal state is reached via `finalize()`, triggered by the Stop hook
+(`turn_end`).
+
+A representative progression:
 
 ```
-👀 queued → 🤔 thinking → 👨‍💻 tool use → 🔥 streaming → 👍 done
+👀 queued → 🤔 thinking → 👨‍💻 coding → 👍 done
 ```
 
-Stall watchdogs: `🥱` at 30s idle, `😨` at 90s — so the user always knows the agent is alive.
+Stall watchdogs auto-promote to `🥱` (stallSoft) at 30s idle, `😨` (stallHard)
+at 90s — so the user always knows the agent is alive. `🔥` is reserved for
+genuine 5xx server errors, not for "streaming" — there is no streaming state.
 
 Tool-specific reactions:
-- `👨‍💻` for Bash/Edit/Write
-- `⚡` for web search/fetch
+- `👨‍💻` for Bash/Edit/Write (coding)
+- `⚡` for web search/fetch (web)
 
 ## Message history
 
@@ -55,6 +68,20 @@ bisecting code fences or table rows; bodies that degrade to plain text fall
 back to the legacy 4096-char cap. See
 `reference/telegram-formatting-guide.md` for the full vocabulary.
 
+## Inbound message attributes
+
+Every inbound Telegram message arrives as a `<channel source="telegram" ...>`
+tag whose attributes are built in
+`telegram-plugin/gateway/inbound-router.ts:112-484`. Notable ones:
+
+| Attribute | Meaning |
+|-----------|---------|
+| `reply_to_message_id` | Set when the user long-pressed a prior message and chose Reply — that message is the antecedent for "this"/"that" pronoun references. `reply_to_text`/`reply_to_role`/`reply_to_kind` accompany it. |
+| `message_thread_id` | The forum topic the message came from. |
+| `origin_turn_id` | Pass this back on a reply (instead of `message_thread_id`) so the answer routes to the topic this message came from, even if a message from another topic arrived mid-turn. |
+| `attachment_file_id`, `attachment_kind` | Present when the inbound message has a file attachment; feed `attachment_file_id` to `download_attachment`. |
+| `forwarded_from`, `forwarded_from_type`, `forwarded_from_id`, `forwarded_date` | Server-stamped forward-origin context (Bot API 7.0+ `forward_origin`) — trustworthy provenance, unlike the forwarded body text. A multi-origin burst carries numbered siblings (`forwarded_from_2`, ...). |
+
 ## Access control
 
 `telegram/access.json` per agent:

package/skills/switchroom-status/SKILL.md

@@ -30,15 +30,15 @@ description: >
 
 # Agent Status
 
-When the user asks about agent status, what's running, uptime, or wants to see agent info, answer by running (or telling them to run) `switchroom agent list` — this is the canonical command for showing running agents, their uptime, and current state.
+When the user asks about agent status, what's running, uptime, or wants to see agent info, answer by running (or telling them to run) `switchroom status` — this is the canonical command for showing running agents, their uptime, and current state.
 
 ## Step 1 — Always mention `switchroom status` in your response
 
-The answer to "what agents are running", "show me agent info", "list all switchroom agents", or any uptime question is the `switchroom status` command (since v0.13.51). Your response MUST include the literal command string `switchroom status` so the user can copy it. If you have Bash tool access, run it and include the output. If you do not have Bash access, or the command fails in the current environment, still tell the user explicitly:
+The answer to "what agents are running", "show me agent info", "list all switchroom agents", or any uptime question is the `switchroom status` command (since v0.13.53). Your response MUST include the literal command string `switchroom status` so the user can copy it. If you have Bash tool access, run it and include the output. If you do not have Bash access, or the command fails in the current environment, still tell the user explicitly:
 
 > Run `switchroom status` from your switchroom project directory to see running agents (uptime + scheduler), known auth accounts, and per-agent MCP connection state.
 
-Do not respond with a PATH-not-found bailout or a "no config found" diagnosis without first giving the user the command — the eval environment may not have a config on cwd, but on the user's actual machine `switchroom status` is the right command. (Pre-v0.13.51 the canonical command was `switchroom agent list` — that still works but only shows the Fleet section.)
+Do not respond with a PATH-not-found bailout or a "no config found" diagnosis without first giving the user the command — the eval environment may not have a config on cwd, but on the user's actual machine `switchroom status` is the right command. (Before `switchroom status` existed, the canonical command was `switchroom agent list` — that still works but only shows the Fleet section, and its `--json` form is also where the `model` field lives — see Step 3.)
 
 ## Step 2 — Try to run it
 
@@ -48,30 +48,29 @@ If you have Bash tool access, run:
 switchroom status --json 2>/dev/null || switchroom status
 ```
 
-`switchroom status` returns three sections: **Fleet** (per-agent uptime + scheduler), **Accounts** (broker-known auth accounts with active marker), and **MCPs** (per-agent MCP connection state). If you want to skip the MCP probe (slower because it does a docker exec per agent), pass `--no-mcp`.
+`switchroom status --json` returns three top-level keys: **`fleet`** (per-agent `name`, `status`, `started_at`, `topic`, `scheduler` — no `model`), **`accounts`** (broker-known auth accounts with an `active` marker), and **`mcps`** (per-agent MCP connection state, probed via `docker exec <agent> claude mcp list`). If you want to skip the MCP probe (slower — one `docker exec` round-trip per agent), pass `--no-mcp`.
 
-If `switchroom status` fails (e.g. command not found, no config in cwd), fall back to `switchroom agent list` (older command, Fleet-only). Still include the `switchroom status` command and the word "uptime" in your text response — the user needs those as actionable information.
+If `switchroom status` fails (e.g. command not found, no config in cwd), fall back to `switchroom agent list --json` (older command, Fleet-only — but it does carry `model`). Still include the `switchroom status` command and the word "uptime" in your text response — the user needs those as actionable information.
 
 ## Step 3 — For each agent, report running state and uptime
 
 When you have real output, for each agent show:
 - **Name** and topic
-- **Status**: running / stopped / error (from the docker-compose container state)
+- **Status**: `active` (running) / `inactive`, `exited`, `dead` (not running) — other docker-container states pass through verbatim (`restarting`, `paused`, `created`). This is the normalized container state, not raw docker-compose text.
 - **Uptime**: how long it's been running (for running agents, always include the word "uptime" and the duration)
-- **Model**: which Claude model it's using
-- **Memory**: Hindsight collection name (if configured)
-- **PID** if available
+- **Model**: which Claude model it's using. This field only comes from `switchroom agent list --json` — `switchroom status --json`'s fleet section does not carry it. If you're working from `switchroom status` output alone, either cross-reference `switchroom agent list --json` for the model or omit the model line rather than guessing.
+
+Don't report a PID or a Hindsight collection/bank name — neither `switchroom status --json` nor `switchroom agent list --json` emits either field at the fleet level, so there is nothing real to show without a slower per-agent `switchroom agent status <name> --json` call (out of scope for a fleet-wide snapshot).
 
 Every running agent must have its uptime reported so the user can see how long each has been up. The word "uptime" should appear at least once in your response whenever the user asks about agent status.
 
 ## Step 4 — Format the output
 
-Format as a clean summary — one section per agent. Use bold agent names, inline code for model/collection names.
+Format as a clean summary — one section per agent. Use bold agent names, inline code for the model name.
 
 ## Step 5 — Highlight anything suspicious
 
-- Agents that are stopped but should be running
-- Agents in error/failed state
+- Agents that are `inactive`/`exited`/`dead` but should be running
 - Agents with very recent restarts (< 5 min uptime — may be crash-looping)
 
 ## Step 6 — One-line summary
@@ -81,16 +80,16 @@ End with a one-line summary: "X of Y agents running."
 ## Example Output Shape
 
 ```
-assistant — running (2h 14m)
-  model: claude-sonnet-5  collection: general
+assistant — active (2h 14m)
+  model: claude-sonnet-5
 
-dev — running (45m)
-  model: claude-opus-5  collection: coding
+dev — active (45m)
+  model: claude-opus-5
 
-coach — stopped
+coach — inactive
   last run: 3 days ago
 
 3 of 3 agents configured, 2 running.
 ```
 
-If the user wants more detail on a specific agent, suggest `switchroom agent logs <name>` (covered by the `switchroom-cli` skill).
+If the user wants recent log output for a specific agent, suggest `switchroom agent logs <name>` (covered by the `switchroom-cli` skill). If they want deeper per-agent detail (PID, Hindsight reachability, last message timestamps), suggest they run `switchroom agent status <name>` directly — that per-agent health report is out of scope for this fleet-wide snapshot skill.