switchroom 0.21.11 → 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.11";
+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.11",
+  "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": {
@@ -57,6 +57,7 @@
     "lint:claude-cli-lockstep": "node scripts/check-claude-cli-lockstep.mjs",
     "lint:changelog-entry": "node scripts/check-changelog-entry.mjs",
     "changelog:generate": "node scripts/gen-changelog-entry.mjs",
+    "changelog:cut": "node scripts/cut-changelog-release.mjs",
     "lint:agent-attribution-trailers": "node scripts/check-agent-attribution-trailers.mjs",
     "lint:hostd-template-guard": "bun scripts/check-hostd-template-guard.ts",
     "lint:bench-baseline-anonymised": "node scripts/check-bench-baseline-anonymised.mjs",
@@ -83,6 +84,7 @@
     "@types/bun": "^1.3.11",
     "@types/node": "^22.0.0",
     "@vitest/coverage-v8": "3.2.4",
+    "commonmark": "0.31.2",
     "typescript": "^5.7.0",
     "vitest": "^3.2.4"
   },

package/skills/dev-protocol/SKILL.md

@@ -139,17 +139,21 @@ is not a rebuttal.
   `AWAITING_CHECKS` means a required workflow is not listening for
   `merge_group`; `.github/MERGE-QUEUE.md` owns that failure mode and the
   invariants that prevent it.
-- **Stage the CHANGELOG entry author-side, before `gh pr create`.** A PR that
-  changes shippable code must add a `## Unreleased` entry (#4469's
+- **Stage the changelog note author-side, before `gh pr create`.** A PR that
+  changes shippable code must add a NEW `changelog.d/` fragment file (#4469's
   `check-changelog-entry.mjs`, part of `npm run lint`, enforces it). Don't
-  hand-write it: run `bun run changelog:generate` in the repo — it derives the
-  entry from your conventional-commit title, appends it under `## Unreleased`
-  (idempotently — a second run is a no-op), and respects the escape hatches. Then
-  commit CHANGELOG.md so it lands in your own push. It runs AUTHOR-side, not in
-  CI, because a CI commit-back with the default `GITHUB_TOKEN` cannot re-trigger
-  the required checks and would wedge the PR (`.github/MERGE-QUEUE.md` §
-  "Author-side changelog generation"). Opt a docs/chore/test PR out with the
-  `no-changelog` label or a `[skip changelog]` token on its own line.
+  hand-edit `CHANGELOG.md`: run `bun run changelog:generate` in the repo — it
+  derives a per-PR fragment (`changelog.d/<pr>-<slug>.<type>.md`) from your
+  conventional-commit title (idempotently — a second run is a no-op) and
+  respects the escape hatches. Then commit the fragment so it lands in your
+  own push. Fragment files are per-PR, so they never conflict with another
+  in-flight PR — editing the shared `## Unreleased` section does, which is
+  exactly the conflict class fragments replace (see `changelog.d/README.md`).
+  It runs AUTHOR-side, not in CI, because a CI commit-back with the default
+  `GITHUB_TOKEN` cannot re-trigger the required checks and would wedge the PR
+  (`.github/MERGE-QUEUE.md` § "Author-side changelog generation"). Opt a
+  docs/chore/test PR out with the `no-changelog` label or a `[skip changelog]`
+  token on its own line.
 - **A test that wouldn't fail on the bug it guards is not a test.** Assert the
   observable outcome, not that the code path executed.
 - **Prefer a deterministic mechanism over prompt discipline.** If a check, a

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-release/SKILL.md

@@ -22,14 +22,20 @@ Cut a release of `switchroom/switchroom` and get it live on the fleet. This is a
 1. `git fetch origin`, confirm `main` is at the commit you want released.
 2. `gh pr list --state open` — confirm no PR meant for this release is still open. Ask the operator if unsure.
 3. Confirm CI on `main` is green (`gh run list --branch main --limit 3`).
-4. Read `CHANGELOG.md` — the `## Unreleased` section is the **continuously-maintained** staging area for this release's notes. Every PR since the last release stages its own entry there as it merges, enforced by `scripts/check-changelog-entry.mjs` (part of `npm run lint`), so by release time this section should already read as a near-complete draft — you tidy and summarise, you do NOT author it from scratch. **An empty (or missing) `## Unreleased` at release time is now an ANOMALY, not the normal state:** it means either there genuinely is nothing to release, OR the enforcement was bypassed (`no-changelog` labels / `[skip changelog]` tokens on their own line on PRs that should have staged entries). Before assuming the former, cross-check against `git log <last-tag>..origin/main` — if real shippable work landed but Unreleased is bare, investigate and reconstruct rather than shipping a hollow release (this is exactly the v0.20.12 failure mode the enforcement exists to prevent).
+4. Read the staged notes — they live in TWO places, both **continuously maintained** as PRs merge and both enforced by `scripts/check-changelog-entry.mjs` (part of `npm run lint`): the `changelog.d/` **fragment files** (the primary path — every shippable PR adds its own `<pr>-<slug>.<type>.md`; see `changelog.d/README.md`) and any legacy/hand-staged entries under `## Unreleased` in `CHANGELOG.md`. Together they should already read as a near-complete draft — you assemble and tidy, you do NOT author from scratch. **Nothing staged at release time (no fragments AND an empty `## Unreleased`) is an ANOMALY, not the normal state** — `bun run changelog:cut` refuses to cut it: it means either there genuinely is nothing to release, OR the enforcement was bypassed (`no-changelog` labels / `[skip changelog]` tokens on their own line on PRs that should have staged notes). Before assuming the former, cross-check against `git log <last-tag>..origin/main` — if real shippable work landed but nothing is staged, investigate and reconstruct rather than shipping a hollow release (this is exactly the v0.20.12 failure mode the enforcement exists to prevent).
 5. Pick the next version: read the latest tag (`git tag --list 'v*' --sort=-v:refname | head -1`) and bump the patch (or minor if the operator asks). Confirm with the operator which.
 
-## Step 1 — Consolidate the changelog (the release commit is CHANGELOG-only)
+## Step 1 — Assemble the changelog (the release commit is CHANGELOG + fragment deletions only)
 
-- The section is maintained continuously (see pre-flight 4), so this step is now a **rename + tidy**, not authorship: change the `## Unreleased` header to `## vX.Y.Z — <one-line summary>`, then read through the staged entries and lightly edit for grouping/summary. If Unreleased was empty or thin, STOP and resolve the anomaly (pre-flight 4) before proceeding — do not invent a release note.
-- **Re-seed a fresh empty `## Unreleased` block at the top** (header + the convention HTML comment) immediately below `# Changelog`, so the staging area exists for the next cycle and `scripts/check-changelog-entry.mjs` keeps enforcing it. (Copy the comment block from the section you just renamed.)
-- The release commit touches **CHANGELOG.md only**. Do NOT bump `package.json` (placeholder discipline).
+- The notes are staged continuously (see pre-flight 4), so this step is **one command + a review**, not authorship:
+
+  ```bash
+  bun run changelog:cut -- --version vX.Y.Z --summary "<one-line summary>"
+  ```
+
+  `scripts/cut-changelog-release.mjs` folds every `changelog.d/` fragment (plus anything hand-staged under `## Unreleased`) into a new `## vX.Y.Z — <summary>` section grouped by category, **re-seeds a fresh empty `## Unreleased` block** (header + convention comment) below `# Changelog`, and **deletes the consumed fragment files**. Use `--dry-run` first to preview the assembled section. It FAILS LOUDLY on a double cut or an empty cut — if it refuses for "nothing to release", STOP and resolve the anomaly (pre-flight 4); do not invent a release note.
+- Read through the assembled section and lightly edit for grouping/summary before committing.
+- The release commit touches **CHANGELOG.md and the deleted `changelog.d/` fragments only**. Do NOT bump `package.json` (placeholder discipline). (A CHANGELOG + fragment-deletion PR changes no shippable code, so `check-changelog-entry.mjs` passes it without a staged note of its own — deleting fragments never counts as staging one.)
 - Branch protection blocks direct push to `main`, so: create a `release/vX.Y.Z` branch, push it, open a `chore: release vX.Y.Z` PR (base `main`), arm auto-merge (squash, delete-branch) on green CI.
 
 ## Step 2 — Create the DRAFT release on a PINNED SHA, then push the tag