switchroom 0.21.12 → 0.21.14

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.14";
 
 // src/setup/hindsight-recall-passthrough.ts
 var HINDSIGHT_RECALL_TAG_WEIGHT_SEED = Object.freeze({ sidechain: 0.8 });
@@ -29041,6 +29064,21 @@ var ROLLOUT_PROBE_TIMEOUT_MS = envMs("SWITCHROOM_ROLLOUT_PROBE_TIMEOUT_MS", 60 *
 import { chownSync as chownSync3 } from "node:fs";
 import { mkdir, readFile, writeFile, rename, copyFile } from "node:fs/promises";
 init_merge();
+
+// src/agents/singleton-reconcile.ts
+var import_yaml4 = __toESM(require_dist(), 1);
+var CORE_SINGLETON_SERVICES = [
+  "vault-broker",
+  "approval-kernel",
+  "switchroom-auth-broker"
+];
+var VOICE_SIDECAR_SERVICE = "voice-sidecar";
+var SINGLETON_SERVICES = [
+  ...CORE_SINGLETON_SERVICES,
+  VOICE_SIDECAR_SERVICE
+];
+
+// src/cli/write-compose.ts
 var AGENT_IMAGE_TAG_RE = /image:\s*\S*switchroom-agent:(\S+)/;
 var BACKUP_SUFFIX = ".bak";
 function composeBackupPath(composePath) {
@@ -29154,19 +29192,6 @@ var MAX_BYTES = 10 * 1024 * 1024;
 // src/agents/docker-fleet.ts
 init_loader();
 
-// src/agents/singleton-reconcile.ts
-var import_yaml4 = __toESM(require_dist(), 1);
-var CORE_SINGLETON_SERVICES = [
-  "vault-broker",
-  "approval-kernel",
-  "switchroom-auth-broker"
-];
-var VOICE_SIDECAR_SERVICE = "voice-sidecar";
-var SINGLETON_SERVICES = [
-  ...CORE_SINGLETON_SERVICES,
-  VOICE_SIDECAR_SERVICE
-];
-
 // src/agents/lifecycle.ts
 function containerName(name) {
   return `switchroom-${name}`;

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."),
@@ -19622,7 +19645,7 @@ var init_resolver = __esm(() => {
 
 // src/vault/broker/server.ts
 import * as net from "node:net";
-import { mkdirSync as mkdirSync8, chmodSync as chmodSync5, chownSync as chownSync2, existsSync as existsSync13, readFileSync as readFileSync13, readdirSync as readdirSync5, statSync as statSync7, unlinkSync as unlinkSync6, writeFileSync as writeFileSync5 } from "node:fs";
+import { mkdirSync as mkdirSync8, chmodSync as chmodSync5, chownSync as chownSync2, existsSync as existsSync13, readFileSync as readFileSync13, readdirSync as readdirSync5, statSync as statSync8, unlinkSync as unlinkSync6, writeFileSync as writeFileSync5 } from "node:fs";
 
 // src/agents/compose.ts
 init_schema();
@@ -21400,6 +21423,66 @@ function createAuditLogger(opts = {}) {
   };
 }
 
+// src/vault/broker/vault-refresh.ts
+init_vault();
+import { statSync as statSync7 } from "node:fs";
+function sameVaultStamp(a, b) {
+  return a.mtimeNs === b.mtimeNs && a.size === b.size && a.ino === b.ino;
+}
+function readVaultStamp(vaultPath) {
+  try {
+    const st = statSync7(vaultPath, { bigint: true });
+    return { mtimeNs: st.mtimeNs, size: st.size, ino: st.ino };
+  } catch {
+    return null;
+  }
+}
+function zeroSecrets(secrets) {
+  for (const [, entry] of Object.entries(secrets)) {
+    try {
+      if (entry.kind === "string" || entry.kind === "binary") {
+        entry.value = "";
+      }
+    } catch {}
+  }
+}
+function refreshVaultIfChanged(state, opts) {
+  const { vaultPath, force = false } = opts;
+  const open = opts.open ?? openVault;
+  const warn = opts.warn ?? ((m) => {
+    process.stderr.write(m);
+  });
+  const secrets = state.secrets;
+  const passphrase = state.passphrase;
+  if (secrets === null || passphrase === null)
+    return state;
+  const known = state.loadedStamp;
+  if (known === null)
+    return state;
+  const current = readVaultStamp(vaultPath);
+  if (current === null)
+    return state;
+  if (!force && sameVaultStamp(current, known))
+    return state;
+  if (!force && state.failedStamp !== null && sameVaultStamp(state.failedStamp, current)) {
+    return state;
+  }
+  opts.beforeOpen?.(vaultPath);
+  let next;
+  try {
+    next = open(passphrase, vaultPath);
+  } catch (err) {
+    const alreadyWarned = state.failedStamp !== null && sameVaultStamp(state.failedStamp, current);
+    if (!alreadyWarned) {
+      warn(`[vault-broker] WARNING: ${vaultPath} changed on disk but ` + `could not be re-opened (${err?.message ?? "unknown error"}) — ` + `continuing to serve the previously loaded secrets; will retry when ` + `the file changes again
+`);
+    }
+    return { ...state, failedStamp: current };
+  }
+  zeroSecrets(secrets);
+  return { secrets: next, passphrase, loadedStamp: current, failedStamp: null };
+}
+
 // src/vault/grants.ts
 import { createHash as createHash5, randomBytes as randomBytes4 } from "node:crypto";
 
@@ -23806,6 +23889,8 @@ class VaultBroker {
   testOpts;
   secrets = null;
   passphrase = null;
+  vaultStamp = null;
+  failedVaultStamp = null;
   config = null;
   startedAt = Date.now();
   server = null;
@@ -23900,13 +23985,53 @@ class VaultBroker {
   }
   unlockFromPassphrase(passphrase) {
     detectVaultLayoutDrift(this.vaultPath);
+    const stamp = this._readVaultStamp();
     const secrets = openVault(passphrase, this.vaultPath);
     this.secrets = secrets;
     this.passphrase = passphrase;
+    this.vaultStamp = stamp;
+    this.failedVaultStamp = null;
     this._setReadinessSentinel(true);
   }
+  _readVaultStamp() {
+    return readVaultStamp(this.vaultPath);
+  }
+  _reloadSecretsIfVaultChanged(force = false) {
+    let next;
+    try {
+      next = refreshVaultIfChanged({
+        secrets: this.secrets,
+        passphrase: this.passphrase,
+        loadedStamp: this.vaultStamp,
+        failedStamp: this.failedVaultStamp
+      }, { vaultPath: this.vaultPath, force, beforeOpen: detectVaultLayoutDrift });
+    } catch (err) {
+      this._failClosedOnVaultDrift(err);
+      return;
+    }
+    this.secrets = next.secrets;
+    this.vaultStamp = next.loadedStamp;
+    this.failedVaultStamp = next.failedStamp;
+  }
+  _failClosedOnVaultDrift(err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`[vault-broker] FATAL: ${detail}
+[vault-broker] Refusing to serve secrets from a vault whose on-disk ` + `layout has diverged — locking. Fix the layout and restart the broker ` + `(\`switchroom apply\`); see docs/operators/state-e-recovery.md.
+`);
+    try {
+      this.auditLogger.write({
+        ts: new Date().toISOString(),
+        op: "lock",
+        caller: `pid:${process.pid}`,
+        pid: process.pid,
+        result: "error:vault-layout-drift"
+      });
+    } catch {}
+    this.lock();
+  }
   reload(config) {
     this.config = config;
+    this._reloadSecretsIfVaultChanged(true);
   }
   _setReadinessSentinel(ready) {
     const p = process.env.SWITCHROOM_VAULT_BROKER_READY_PATH;
@@ -23922,15 +24047,11 @@ class VaultBroker {
   }
   lock() {
     if (this.secrets !== null) {
-      for (const [, entry] of Object.entries(this.secrets)) {
-        try {
-          if (entry.kind === "string" || entry.kind === "binary") {
-            entry.value = "";
-          }
-        } catch {}
-      }
+      zeroSecrets(this.secrets);
       this.secrets = null;
     }
+    this.vaultStamp = null;
+    this.failedVaultStamp = null;
     this.passphrase = null;
     this._setReadinessSentinel(false);
   }
@@ -24250,6 +24371,7 @@ class VaultBroker {
         socket.write(encodeResponse(errorResponse("DENIED", "preflight_access is operator-only")));
         return;
       }
+      this._reloadSecretsIfVaultChanged();
       if (this.secrets === null) {
         socket.write(encodeResponse(errorResponse("LOCKED", "Vault is locked")));
         return;
@@ -24281,6 +24403,7 @@ class VaultBroker {
       return;
     }
     if (req.op === "list") {
+      this._reloadSecretsIfVaultChanged();
       if (this.secrets === null) {
         socket.write(encodeResponse(errorResponse("LOCKED", "Vault is locked")));
         return;
@@ -24356,6 +24479,7 @@ class VaultBroker {
       return;
     }
     if (req.op === "get") {
+      this._reloadSecretsIfVaultChanged();
       if (this.secrets === null) {
         socket.write(encodeResponse(errorResponse("LOCKED", "Vault is locked")));
         return;
@@ -24543,10 +24667,24 @@ class VaultBroker {
       return;
     }
     if (req.op === "put") {
+      this._reloadSecretsIfVaultChanged();
       if (this.secrets === null || this.passphrase === null) {
         socket.write(encodeResponse(errorResponse("LOCKED", "Vault is locked")));
         return;
       }
+      if (this.failedVaultStamp !== null) {
+        writeAudit({
+          ts: new Date().toISOString(),
+          op: "put",
+          key: req.key,
+          caller: auditCaller,
+          pid: auditPid,
+          cgroup: auditCgroup,
+          result: "denied:vault-file-unreadable"
+        });
+        socket.write(encodeResponse(errorResponse("INTERNAL", "put refused: the vault file on disk changed and could not be decrypted with the passphrase this broker holds. Writing now would overwrite it with the broker's older in-memory state. Restore the vault file the broker was unlocked with, or restart the broker and unlock it with the current passphrase (reads keep serving the previously loaded secrets meanwhile).")));
+        return;
+      }
       let passphraseAttested = false;
       const requestedPostureAttest = req.attest_via_posture === true;
       if (requestedPostureAttest && req.passphrase !== undefined && req.passphrase !== "") {
@@ -24790,6 +24928,8 @@ class VaultBroker {
         return;
       }
       this.chownVaultToOperator();
+      this.vaultStamp = this._readVaultStamp();
+      this.failedVaultStamp = null;
       this.auditLogger.write({
         ts: new Date().toISOString(),
         op: "put",
@@ -25365,7 +25505,7 @@ class VaultBroker {
     if (!existsSync13(filePath))
       return false;
     try {
-      if (statSync7(filePath).size === 0)
+      if (statSync8(filePath).size === 0)
         return false;
     } catch {
       return false;

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.14",
   "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/profiles/_shared/agent-self-service.md.hbs

@@ -1,92 +1,38 @@
 ## Self-service: scheduled tasks (cron) and config introspection
 
-You have an **`agent-config`** MCP server with tools for inspecting your own
-configuration and creating / removing your own scheduled tasks. Use these
-proactively when the user expresses a recurring-task intent — don't paste a
-yaml snippet and ask them to edit `switchroom.yaml`. The whole point of these
-tools is to let you do the edit yourself.
+You have an **`agent-config`** MCP server for inspecting your own config and
+creating/removing your own scheduled tasks — don't hand the user a yaml
+snippet, do the edit yourself.
+
+- Write tools: `schedule_add` (e.g. `cron_expr: "0 17 * * 0"` for "call mom
+  every Sunday at 5pm", or `"0 8 * * 1-5"` for a weekday-morning digest) /
+  `schedule_remove`; `skill_install` (`source: "bundled:<name>"`) /
+  `skill_remove`; and the personal-skill set `skill_init_personal` /
+  `skill_clone_to_personal` / `skill_edit_personal` / `skill_remove_personal`.
+  If YOU find a bug in a skill you're using, fork-and-fix is your OWN call,
+  not the operator's: `skill_clone_to_personal` then `skill_edit_personal`,
+  then use `personal-<name>`.
+- Read tools: `cron_list`, `cron_doctor`, `skill_list`, `skill_list_personal`,
+  `skill_search` (answers "is there a skill for X?"), `config_get`, `whoami`,
+  `audit_tail`, `peers_list` (live — never cache or memorize the fleet into
+  memory).
+- Safety rails the broker hard-rejects, so know them before promising
+  anything: **5-minute minimum interval** (offer `*/5`, `*/15`, or `*/30`
+  instead of anything faster) and **20 entries** each for schedules and
+  skills — check `cron_list` / `skill_list` first if you're near a cap.
+  These numbers live only in the broker's rejection messages, not the tool
+  schema — know them before the call, not after the error. No `secrets:` on
+  agent-authored cron entries — go through `vault_request_access` at
+  runtime instead. You manage only your OWN schedule/skills — cross-agent
+  writes are refused; for another agent, point the user to it via
+  `peers_list`.
+- After a successful `schedule_add`, tell the user the human-readable
+  schedule, the cron expression you actually wrote, and the `name` slug (so
+  they can remove it later). After a failed write, surface the error
+  verbatim and the closest legal alternative.
+- Cron-fired sessions render rich markdown, so scheduled/digest output should
+  use **bold** headers and `code` for identifiers, just like a live reply.
 
-### When to reach for these tools
-
-| User says… | You call… |
-|---|---|
-| "remind me to call mom every Sunday at 5pm" | `schedule_add` with `cron_expr: "0 17 * * 0"` |
-| "run the morning digest at 8am every weekday" | `schedule_add` with `cron_expr: "0 8 * * 1-5"` |
-| "check the build every 15 minutes" | `schedule_add` with `cron_expr: "*/15 * * * *"` (legal — 15min ≥ the 5-min floor) |
-| "ping me every 2 minutes" | rejected by the 5-min floor — offer `*/5` or `*/10` instead |
-| "stop the daily digest" | `cron_list` to find the entry, then `schedule_remove` by `name` |
-| "what tasks am I running on a schedule?" | `cron_list` |
-| "what skills do I have access to?" | `skill_list` |
-| "show me my config" | `config_get` |
-| "show me my recent tool calls" | `audit_tail` |
-| "what other agents are running here?" / "is there an agent that does X?" / "who handles Y?" | `peers_list` |
-| "install the foo skill" / "give yourself the foo skill" | `skill_install` with `source: "bundled:foo"` |
-| "drop the foo skill" / "remove the foo skill" | `skill_remove` with `name: "foo"` |
-| "is there a skill for X?" | `skill_search` with `query: "X"` |
-| **YOU find a bug in a skill you're using** | `skill_clone_to_personal` then `skill_edit_personal` — fork-and-fix yourself |
-| "write me a custom skill that does X" | `skill_init_personal` |
-
-The tool schemas carry the parameters, enums, and error codes — read them
-there. What follows is only what you need *before* the call, because it
-changes the advice you give the user.
-
-### Writing a cron prompt
-
-`schedule_add`'s `prompt` is what *you* receive when the cron fires — phrase it
-from your future-self's perspective (`"Time for the daily digest — pull
-yesterday's GitHub activity and DM the summary to chat 12345"`, not `"please
-send the digest"`). A new entry takes effect within **~30s**; the scheduler
-hot-reloads, no restart needed.
-
-### Mind the cost — pick the cheapest tier that does the job
-
-- **Tier 1 — cheap fresh session.** The default for a **frequent** cron (≤60min):
-  a fresh Sonnet that keeps your memory + tools but drops your conversation
-  context. Force it for a daily/weekly self-contained job with `model:
-  "sonnet"` / `context: "fresh"`.
-- **Tier 2 — a full turn in your live session.** The default for **daily/weekly**
-  crons. `context: "agent"` pins a fire here when it genuinely needs your
-  accumulated context (this always wins).
-- **Model-free tiers — you must REQUEST these from the operator** (they need a
-  config commit; you can only self-author plain prompt crons plus the
-  `model`/`context` hints): **`kind: action`** posts a FIXED text at zero
-  tokens (renders full GFM — set `parse_mode: text` for verbatim);
-  **`kind: poll`** is a model-free check where only a *change* wakes you —
-  don't burn a frequent prompt cron on polling; **`reaction_dispatch`** wakes
-  you instantly on an emoji reaction, zero polling.
-
-Cron-fired sessions render rich markdown, so scheduled/digest output should use
-**bold** headers and `code` for identifiers, just like a live reply.
-
-### Safety rails — know these BEFORE you promise anything
-
-The broker hard-rejects writes that violate these, so they shape the advice
-you give — don't surprise the user with an error after agreeing to something
-the rails will block:
-
-- **Minimum 5-minute interval.** Anything more frequent (`* * * * *`, `*/2`,
-  `*/3`, `*/4`) is rejected. Offer `*/5`, `*/15`, `*/30`, or hourly instead.
-- **20 schedule entries per agent.** Near the cap, `cron_list` first; if full,
-  ask the user which one to drop before adding.
-- **20 skills per agent**, same shape.
-- **No `secrets:` on agent-authored entries.** Cron fires the prompt; you go
-  through `vault_request_access` at runtime instead.
-- **You manage only your OWN schedule and skills.** The broker pins identity
-  via `$SWITCHROOM_AGENT_NAME`; for another agent, tell the user to ask that
-  agent. `skill_remove` likewise won't remove skills the operator wrote
-  directly into `switchroom.yaml` — those are operator-only.
-- **`peers_list` is live** — never cache or memorize the fleet into memory.
-
-Fixing a skill you're using is your call, not the operator's:
-`skill_clone_to_personal` → `skill_edit_personal` → use `personal-<name>`. The
-fork is durable and auto-mirrors to `~/.switchroom-config/` when present.
-
-### Confirm honestly
-
-After a successful `schedule_add`, tell the user the human-readable schedule,
-the cron expression you actually wrote, and the `name` slug (so they can
-remove it later). After a failed write, surface the error verbatim, name
-which rail tripped, and offer the closest legal alternative.
 {{#if linearAgentEnabled}}
 
 ## Capture to Linear (👨‍💻 / 📌 reaction → new issue)