switchroom 0.13.54 → 0.13.56

package/dist/host-control/main.js

@@ -13876,6 +13876,16 @@ var MicrosoftWorkspaceConfigSchema = exports_external.object({
   authority: exports_external.string().url().optional().describe("Microsoft authority endpoint. Defaults to " + "'https://login.microsoftonline.com/common' which accepts both " + "personal MSA and work/school tenants. Override only for " + "single-tenant deployments."),
   org_mode: exports_external.boolean().optional().describe("Opt-in to Teams + SharePoint surfaces (RFC §6.4). When true, " + "the v1 scope set adds Sites.ReadWrite.All AND the launcher " + "spawns softeria with --org-mode. Defaults to false — personal " + "MSA + standard work surfaces only. Flipping for an existing " + "consented account requires re-running 'auth microsoft account " + "add --replace' to consent the additional scope.")
 }).optional();
+var NotionWorkspaceConfigSchema = exports_external.object({
+  vault_key: exports_external.string().min(1).default("notion/integration-token").describe("Vault key holding the Notion internal-integration token. Default " + "`notion/integration-token`. Override only for non-standard vault " + "layouts. The broker's --allow ACL on this key is the authoritative " + "list of which agents may receive the token."),
+  databases: exports_external.record(exports_external.string().regex(/^[a-z0-9][a-z0-9_-]{0,62}$/, {
+    message: "notion_workspace.databases friendly names must match " + "/^[a-z0-9][a-z0-9_-]{0,62}$/ — lowercase letters, digits, " + "hyphens, underscores. Got: '%s'."
+  }), exports_external.string().regex(/^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-9a-fA-F]{4}-?[0-9a-fA-F]{4}-?[0-9a-fA-F]{12}$/, {
+    message: "notion_workspace.databases values must be Notion database " + "UUIDs (32 hex characters, optional dashes)."
+  })).default({}).describe("Friendly-name → Notion database UUID map. Operator-managed; agents " + "reference databases by friendly name only — they never see or type " + "UUIDs. Populate via `switchroom notion list-dbs` (PR 4) after " + "vault-putting the integration token and sharing DBs with the " + "integration in Notion's UI."),
+  mcp_version: exports_external.string().min(1).optional().describe("Optional pin for the upstream `@notionhq/notion-mcp-server` npm " + "package version. Default is the build-time `NOTION_MCP_PINNED_VERSION` " + "constant. Override only when reproducing operator-specific bugs."),
+  rate_limit_rps: exports_external.number().int().positive().max(10).optional().describe("Optional global rate-limit budget in requests per second across all " + "switchroom agents sharing this integration token. Defaults to 3 " + "(Notion's documented public-API limit). Lower it if you also use " + "the integration token from outside switchroom and need to share " + "budget. Higher than 10 is rejected — if you think you need it, " + "your usage probably needs a workspace-tier upgrade with Notion.")
+}).optional();
 var AgentGoogleWorkspaceConfigSchema = exports_external.object({
   account: exports_external.string().regex(/^[^@\s:]+@[^@\s:]+\.[^@\s:]+$/, {
     message: "google_workspace.account must be a Google account email like " + "'alice@example.com' (colons not allowed)"
@@ -13889,6 +13899,13 @@ var AgentMicrosoftWorkspaceConfigSchema = exports_external.object({
   }).transform((v) => v.trim().toLowerCase()).optional().describe("RFC #1873: the Microsoft account this agent uses for the M365 MCP. " + "Must be a key in top-level `microsoft_accounts:` with this agent " + "listed in its `enabled_for[]`. Read by the auth-broker " + "(get-credentials, provider=microsoft) and by the scaffold to " + "decide whether to emit the `ms-365` MCP entry. Normalized to " + "lowercase so it matches the microsoft_accounts key (which is " + "also normalized)."),
   org_mode: exports_external.boolean().optional().describe("Per-agent org_mode override (RFC #1873 §6.4). When set, replaces " + "the top-level microsoft_workspace.org_mode for this agent. " + "Defaults to top-level value (which defaults to false).")
 }).optional();
+var AgentNotionWorkspaceConfigSchema = exports_external.object({
+  databases: exports_external.array(exports_external.string().regex(/^[a-z0-9][a-z0-9_-]{0,62}$/, {
+    message: "notion_workspace.databases entries must be friendly names " + "matching /^[a-z0-9][a-z0-9_-]{0,62}$/ — these must appear as " + "keys in top-level notion_workspace.databases."
+  })).min(1, {
+    message: "notion_workspace.databases must list at least one friendly " + "name. An empty list rejects every Notion tool call — if you " + "want to remove this agent's Notion access, delete the entire " + "notion_workspace block instead."
+  }).optional().describe("Optional per-agent allowlist of database friendly names this " + "agent may read/write. Each name must exist as a key in top-level " + "notion_workspace.databases. Omit the field (or leave it undefined) " + "to grant access to every DB the upstream integration can see — " + "appropriate for an admin/orchestrator agent. Set the list to " + "narrow access for specialist agents.")
+}).optional();
 var ReactionsSchema = exports_external.object({
   enabled: exports_external.boolean().optional().describe("Master switch for the reaction-trigger path. When false, " + "reactions are still persisted via recordReaction but never " + "dispatched to the agent as synthetic inbound turns. Default true."),
   trigger_emojis: exports_external.array(exports_external.string()).optional().describe("Emoji allowlist that triggers a synthetic inbound when reacted " + "to a bot message. Default ['\uD83D\uDC4E', '❌', '\uD83D\uDC4D', '✅']. Cascade " + "mode: REPLACE (not union) — setting this at a layer replaces " + "lower layers entirely, so an operator can narrow to [] to " + "disable triggering without flipping `enabled`."),
@@ -14025,6 +14042,7 @@ var AgentSchema = exports_external.object({
   drive: AgentGoogleWorkspaceConfigSchema.describe("RFC D legacy key — use `google_workspace:` instead. Per-agent " + "google_workspace overrides (currently approvers + tier). When set, " + "replaces the top-level approvers list for this agent. " + "google_client_id/secret are not per-agent — they live at the top level."),
   google_workspace: AgentGoogleWorkspaceConfigSchema.describe("RFC G canonical key. Per-agent Google Workspace overrides — currently " + "approvers (replaces, does not extend the top-level list) and tier " + "(`core` | `extended` | `complete`, replaces top-level default). " + "google_client_id/secret are not per-agent — they live at the top level. " + "Mutually exclusive with `drive:` on the same agent (loader fails fast " + "if both are set)."),
   microsoft_workspace: AgentMicrosoftWorkspaceConfigSchema.describe("RFC #1873 (Microsoft 365 integration). Per-agent Microsoft Workspace " + "override — pins the Microsoft account this agent reads via the " + "auth-broker (must be a key in top-level `microsoft_accounts:` with " + "this agent in its `enabled_for[]`) and optionally overrides org_mode. " + "microsoft_client_id/secret are not per-agent."),
+  notion_workspace: AgentNotionWorkspaceConfigSchema.describe("RFC docs/rfcs/notion-integration.md. Per-agent Notion access. " + "Presence opts the agent IN (launcher scaffolded, MCP entry emitted, " + "broker grants the integration token). Optional `databases:` filter " + "narrows which DBs this agent may read/write — names must resolve in " + "top-level notion_workspace.databases. Absence opts the agent OUT."),
   repos: exports_external.record(exports_external.string().regex(/^[a-z0-9][a-z0-9-]*$/, "Repo slug must be kebab-case ASCII: start with a lowercase letter or digit, contain only lowercase letters, digits, and hyphens"), exports_external.object({
     url: exports_external.string().min(1).describe("Git remote URL for the repo (e.g. 'git@github.com:org/repo.git' or " + "'https://github.com/org/repo.git'). Used verbatim for git clone."),
     branch_default: exports_external.string().optional().describe("Default branch to track (defaults to the remote's HEAD, typically 'main'). " + "The per-agent branch 'agent/<agentName>/main' fast-forwards to this branch " + "when the worktree is clean on session start.")
@@ -14148,6 +14166,7 @@ var SwitchroomConfigSchema = exports_external.object({
   drive: GoogleWorkspaceConfigSchema.describe("RFC D legacy key — use `google_workspace:` instead. Optional Google " + "Workspace onboarding configuration. When set, supplies Google OAuth " + "client credentials, the approver allowlist for `switchroom drive " + "connect`, and the optional tier knob. Env vars " + "(SWITCHROOM_GOOGLE_CLIENT_ID, SWITCHROOM_GOOGLE_CLIENT_SECRET, " + "SWITCHROOM_APPROVER_USER_ID) take precedence over this block when " + "set, preserving back-compat with the env-only flow shipped in #766."),
   google_workspace: GoogleWorkspaceConfigSchema.describe("RFC G canonical key. Top-level Google Workspace configuration — " + "OAuth client credentials, approver allowlist, and tier knob (`core` " + "| `extended` | `complete`, default `core`). Mutually exclusive with " + "`drive:` at the top level (loader fails fast if both are set)."),
   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 docs/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."),
   host_control: HostControlConfigSchema.default({}).describe("Host-control daemon configuration. Defaults to enabled=true since " + "RFC C Phase 2 (docs/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. Currently scopes the opt-in flag and rate cap for the new " + "`config_propose_edit` verb (PR 1a — disabled by default)."),
@@ -14653,6 +14672,34 @@ function mergeAgentConfig(defaultsIn, agentIn) {
   mergeAgentConfig.notifiedWorkerIsolationMove = false;
 })(mergeAgentConfig ||= {});
 
+// src/config/notion-workspace-acl.ts
+function validateNotionWorkspaceConfig(config) {
+  const issues = [];
+  const dbMap = config.notion_workspace?.databases ?? {};
+  const known = new Set(Object.keys(dbMap));
+  for (const [agentName, agentRaw] of Object.entries(config.agents ?? {})) {
+    if (!agentRaw)
+      continue;
+    const dbFilter = agentRaw.notion_workspace?.databases;
+    if (dbFilter === undefined)
+      continue;
+    if (dbFilter.length === 0) {
+      issues.push(`  agents.${agentName}.notion_workspace.databases is an empty ` + `list. Delete the entire notion_workspace block to remove Notion ` + `access, or list at least one database friendly name.`);
+      continue;
+    }
+    if (config.notion_workspace === undefined) {
+      issues.push(`  agents.${agentName}.notion_workspace is set but the top-level ` + `notion_workspace block is missing. Configure the integration ` + `globally first (vault_key + databases map), then grant per-agent ` + `access.`);
+      continue;
+    }
+    for (const name of dbFilter) {
+      if (!known.has(name)) {
+        issues.push(`  agents.${agentName}.notion_workspace.databases references ` + `unknown database "${name}". Add it to top-level ` + `notion_workspace.databases (run \`switchroom notion list-dbs\` ` + `to see the UUIDs the integration can read), or remove the ` + `reference.`);
+      }
+    }
+  }
+  return issues;
+}
+
 // src/config/loader.ts
 class ConfigError extends Error {
   details;
@@ -14772,6 +14819,10 @@ function loadConfig(configPath) {
   }
   applyAgentOverlays(config);
   validateAllCronTopicAliases(config, filePath);
+  const notionIssues = validateNotionWorkspaceConfig(config);
+  if (notionIssues.length > 0) {
+    throw new ConfigError(`Invalid notion_workspace configuration in ${filePath}`, notionIssues);
+  }
   return config;
 }
 function validateAllCronTopicAliases(config, filePath) {

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

@@ -11259,7 +11259,7 @@ var init_dist = __esm(() => {
 });
 
 // src/config/schema.ts
-var CodeRepoEntrySchema, AgentBindMountSchema, ScheduleEntrySchema, AgentSoulSchema, AgentToolsSchema, AgentMemorySchema, HookEntrySchema, AgentHooksSchema, SubagentSchema, SessionSchema, SessionContinuitySchema, TelegramChannelSchema, ChannelsSchema, TIMEZONE_REGEX, ApproverIdSchema, GoogleWorkspaceTierSchema, GoogleWorkspaceConfigSchema, MicrosoftWorkspaceConfigSchema, AgentGoogleWorkspaceConfigSchema, AgentMicrosoftWorkspaceConfigSchema, ReactionsSchema, ReleaseBlock, NetworkIsolationSchema, profileFields, ProfileSchema, _omitExtends, defaultsFields, AgentDefaultsSchema, AgentSchema, TelegramConfigSchema, MemoryBackendConfigSchema, VaultConfigSchema, QuotaConfigSchema, AutoReleaseCheckSchema, HostControlConfigSchema, HostdConfigSchema, SwitchroomConfigSchema;
+var CodeRepoEntrySchema, AgentBindMountSchema, ScheduleEntrySchema, AgentSoulSchema, AgentToolsSchema, AgentMemorySchema, HookEntrySchema, AgentHooksSchema, SubagentSchema, SessionSchema, SessionContinuitySchema, TelegramChannelSchema, ChannelsSchema, TIMEZONE_REGEX, ApproverIdSchema, GoogleWorkspaceTierSchema, GoogleWorkspaceConfigSchema, MicrosoftWorkspaceConfigSchema, NotionWorkspaceConfigSchema, AgentGoogleWorkspaceConfigSchema, AgentMicrosoftWorkspaceConfigSchema, AgentNotionWorkspaceConfigSchema, ReactionsSchema, ReleaseBlock, NetworkIsolationSchema, profileFields, ProfileSchema, _omitExtends, defaultsFields, AgentDefaultsSchema, AgentSchema, TelegramConfigSchema, MemoryBackendConfigSchema, VaultConfigSchema, QuotaConfigSchema, AutoReleaseCheckSchema, HostControlConfigSchema, HostdConfigSchema, SwitchroomConfigSchema;
 var init_schema = __esm(() => {
   init_zod();
   CodeRepoEntrySchema = exports_external.object({
@@ -11444,6 +11444,16 @@ var init_schema = __esm(() => {
     authority: exports_external.string().url().optional().describe("Microsoft authority endpoint. Defaults to " + "'https://login.microsoftonline.com/common' which accepts both " + "personal MSA and work/school tenants. Override only for " + "single-tenant deployments."),
     org_mode: exports_external.boolean().optional().describe("Opt-in to Teams + SharePoint surfaces (RFC §6.4). When true, " + "the v1 scope set adds Sites.ReadWrite.All AND the launcher " + "spawns softeria with --org-mode. Defaults to false — personal " + "MSA + standard work surfaces only. Flipping for an existing " + "consented account requires re-running 'auth microsoft account " + "add --replace' to consent the additional scope.")
   }).optional();
+  NotionWorkspaceConfigSchema = exports_external.object({
+    vault_key: exports_external.string().min(1).default("notion/integration-token").describe("Vault key holding the Notion internal-integration token. Default " + "`notion/integration-token`. Override only for non-standard vault " + "layouts. The broker's --allow ACL on this key is the authoritative " + "list of which agents may receive the token."),
+    databases: exports_external.record(exports_external.string().regex(/^[a-z0-9][a-z0-9_-]{0,62}$/, {
+      message: "notion_workspace.databases friendly names must match " + "/^[a-z0-9][a-z0-9_-]{0,62}$/ — lowercase letters, digits, " + "hyphens, underscores. Got: '%s'."
+    }), exports_external.string().regex(/^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-9a-fA-F]{4}-?[0-9a-fA-F]{4}-?[0-9a-fA-F]{12}$/, {
+      message: "notion_workspace.databases values must be Notion database " + "UUIDs (32 hex characters, optional dashes)."
+    })).default({}).describe("Friendly-name → Notion database UUID map. Operator-managed; agents " + "reference databases by friendly name only — they never see or type " + "UUIDs. Populate via `switchroom notion list-dbs` (PR 4) after " + "vault-putting the integration token and sharing DBs with the " + "integration in Notion's UI."),
+    mcp_version: exports_external.string().min(1).optional().describe("Optional pin for the upstream `@notionhq/notion-mcp-server` npm " + "package version. Default is the build-time `NOTION_MCP_PINNED_VERSION` " + "constant. Override only when reproducing operator-specific bugs."),
+    rate_limit_rps: exports_external.number().int().positive().max(10).optional().describe("Optional global rate-limit budget in requests per second across all " + "switchroom agents sharing this integration token. Defaults to 3 " + "(Notion's documented public-API limit). Lower it if you also use " + "the integration token from outside switchroom and need to share " + "budget. Higher than 10 is rejected — if you think you need it, " + "your usage probably needs a workspace-tier upgrade with Notion.")
+  }).optional();
   AgentGoogleWorkspaceConfigSchema = exports_external.object({
     account: exports_external.string().regex(/^[^@\s:]+@[^@\s:]+\.[^@\s:]+$/, {
       message: "google_workspace.account must be a Google account email like " + "'alice@example.com' (colons not allowed)"
@@ -11457,6 +11467,13 @@ var init_schema = __esm(() => {
     }).transform((v) => v.trim().toLowerCase()).optional().describe("RFC #1873: the Microsoft account this agent uses for the M365 MCP. " + "Must be a key in top-level `microsoft_accounts:` with this agent " + "listed in its `enabled_for[]`. Read by the auth-broker " + "(get-credentials, provider=microsoft) and by the scaffold to " + "decide whether to emit the `ms-365` MCP entry. Normalized to " + "lowercase so it matches the microsoft_accounts key (which is " + "also normalized)."),
     org_mode: exports_external.boolean().optional().describe("Per-agent org_mode override (RFC #1873 §6.4). When set, replaces " + "the top-level microsoft_workspace.org_mode for this agent. " + "Defaults to top-level value (which defaults to false).")
   }).optional();
+  AgentNotionWorkspaceConfigSchema = exports_external.object({
+    databases: exports_external.array(exports_external.string().regex(/^[a-z0-9][a-z0-9_-]{0,62}$/, {
+      message: "notion_workspace.databases entries must be friendly names " + "matching /^[a-z0-9][a-z0-9_-]{0,62}$/ — these must appear as " + "keys in top-level notion_workspace.databases."
+    })).min(1, {
+      message: "notion_workspace.databases must list at least one friendly " + "name. An empty list rejects every Notion tool call — if you " + "want to remove this agent's Notion access, delete the entire " + "notion_workspace block instead."
+    }).optional().describe("Optional per-agent allowlist of database friendly names this " + "agent may read/write. Each name must exist as a key in top-level " + "notion_workspace.databases. Omit the field (or leave it undefined) " + "to grant access to every DB the upstream integration can see — " + "appropriate for an admin/orchestrator agent. Set the list to " + "narrow access for specialist agents.")
+  }).optional();
   ReactionsSchema = exports_external.object({
     enabled: exports_external.boolean().optional().describe("Master switch for the reaction-trigger path. When false, " + "reactions are still persisted via recordReaction but never " + "dispatched to the agent as synthetic inbound turns. Default true."),
     trigger_emojis: exports_external.array(exports_external.string()).optional().describe("Emoji allowlist that triggers a synthetic inbound when reacted " + "to a bot message. Default ['\uD83D\uDC4E', '❌', '\uD83D\uDC4D', '✅']. Cascade " + "mode: REPLACE (not union) — setting this at a layer replaces " + "lower layers entirely, so an operator can narrow to [] to " + "disable triggering without flipping `enabled`."),
@@ -11593,6 +11610,7 @@ var init_schema = __esm(() => {
     drive: AgentGoogleWorkspaceConfigSchema.describe("RFC D legacy key — use `google_workspace:` instead. Per-agent " + "google_workspace overrides (currently approvers + tier). When set, " + "replaces the top-level approvers list for this agent. " + "google_client_id/secret are not per-agent — they live at the top level."),
     google_workspace: AgentGoogleWorkspaceConfigSchema.describe("RFC G canonical key. Per-agent Google Workspace overrides — currently " + "approvers (replaces, does not extend the top-level list) and tier " + "(`core` | `extended` | `complete`, replaces top-level default). " + "google_client_id/secret are not per-agent — they live at the top level. " + "Mutually exclusive with `drive:` on the same agent (loader fails fast " + "if both are set)."),
     microsoft_workspace: AgentMicrosoftWorkspaceConfigSchema.describe("RFC #1873 (Microsoft 365 integration). Per-agent Microsoft Workspace " + "override — pins the Microsoft account this agent reads via the " + "auth-broker (must be a key in top-level `microsoft_accounts:` with " + "this agent in its `enabled_for[]`) and optionally overrides org_mode. " + "microsoft_client_id/secret are not per-agent."),
+    notion_workspace: AgentNotionWorkspaceConfigSchema.describe("RFC docs/rfcs/notion-integration.md. Per-agent Notion access. " + "Presence opts the agent IN (launcher scaffolded, MCP entry emitted, " + "broker grants the integration token). Optional `databases:` filter " + "narrows which DBs this agent may read/write — names must resolve in " + "top-level notion_workspace.databases. Absence opts the agent OUT."),
     repos: exports_external.record(exports_external.string().regex(/^[a-z0-9][a-z0-9-]*$/, "Repo slug must be kebab-case ASCII: start with a lowercase letter or digit, contain only lowercase letters, digits, and hyphens"), exports_external.object({
       url: exports_external.string().min(1).describe("Git remote URL for the repo (e.g. 'git@github.com:org/repo.git' or " + "'https://github.com/org/repo.git'). Used verbatim for git clone."),
       branch_default: exports_external.string().optional().describe("Default branch to track (defaults to the remote's HEAD, typically 'main'). " + "The per-agent branch 'agent/<agentName>/main' fast-forwards to this branch " + "when the worktree is clean on session start.")
@@ -11716,6 +11734,7 @@ var init_schema = __esm(() => {
     drive: GoogleWorkspaceConfigSchema.describe("RFC D legacy key — use `google_workspace:` instead. Optional Google " + "Workspace onboarding configuration. When set, supplies Google OAuth " + "client credentials, the approver allowlist for `switchroom drive " + "connect`, and the optional tier knob. Env vars " + "(SWITCHROOM_GOOGLE_CLIENT_ID, SWITCHROOM_GOOGLE_CLIENT_SECRET, " + "SWITCHROOM_APPROVER_USER_ID) take precedence over this block when " + "set, preserving back-compat with the env-only flow shipped in #766."),
     google_workspace: GoogleWorkspaceConfigSchema.describe("RFC G canonical key. Top-level Google Workspace configuration — " + "OAuth client credentials, approver allowlist, and tier knob (`core` " + "| `extended` | `complete`, default `core`). Mutually exclusive with " + "`drive:` at the top level (loader fails fast if both are set)."),
     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 docs/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."),
     host_control: HostControlConfigSchema.default({}).describe("Host-control daemon configuration. Defaults to enabled=true since " + "RFC C Phase 2 (docs/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. Currently scopes the opt-in flag and rate cap for the new " + "`config_propose_edit` verb (PR 1a — disabled by default)."),
@@ -11912,6 +11931,34 @@ var init_overlay_loader = __esm(() => {
   OVERLAY_SOURCE = Symbol.for("switchroom.config.overlay-source");
 });
 
+// src/config/notion-workspace-acl.ts
+function validateNotionWorkspaceConfig(config) {
+  const issues = [];
+  const dbMap = config.notion_workspace?.databases ?? {};
+  const known = new Set(Object.keys(dbMap));
+  for (const [agentName, agentRaw] of Object.entries(config.agents ?? {})) {
+    if (!agentRaw)
+      continue;
+    const dbFilter = agentRaw.notion_workspace?.databases;
+    if (dbFilter === undefined)
+      continue;
+    if (dbFilter.length === 0) {
+      issues.push(`  agents.${agentName}.notion_workspace.databases is an empty ` + `list. Delete the entire notion_workspace block to remove Notion ` + `access, or list at least one database friendly name.`);
+      continue;
+    }
+    if (config.notion_workspace === undefined) {
+      issues.push(`  agents.${agentName}.notion_workspace is set but the top-level ` + `notion_workspace block is missing. Configure the integration ` + `globally first (vault_key + databases map), then grant per-agent ` + `access.`);
+      continue;
+    }
+    for (const name of dbFilter) {
+      if (!known.has(name)) {
+        issues.push(`  agents.${agentName}.notion_workspace.databases references ` + `unknown database "${name}". Add it to top-level ` + `notion_workspace.databases (run \`switchroom notion list-dbs\` ` + `to see the UUIDs the integration can read), or remove the ` + `reference.`);
+      }
+    }
+  }
+  return issues;
+}
+
 // src/config/loader.ts
 var exports_loader = {};
 __export(exports_loader, {
@@ -12034,6 +12081,10 @@ function loadConfig(configPath) {
   }
   applyAgentOverlays(config);
   validateAllCronTopicAliases(config, filePath);
+  const notionIssues = validateNotionWorkspaceConfig(config);
+  if (notionIssues.length > 0) {
+    throw new ConfigError(`Invalid notion_workspace configuration in ${filePath}`, notionIssues);
+  }
   return config;
 }
 function validateAllCronTopicAliases(config, filePath) {

package/dist/vault/broker/server.js

@@ -11259,7 +11259,7 @@ var init_zod = __esm(() => {
 });
 
 // src/config/schema.ts
-var CodeRepoEntrySchema, AgentBindMountSchema, ScheduleEntrySchema, AgentSoulSchema, AgentToolsSchema, AgentMemorySchema, HookEntrySchema, AgentHooksSchema, SubagentSchema, SessionSchema, SessionContinuitySchema, TelegramChannelSchema, ChannelsSchema, TIMEZONE_REGEX, ApproverIdSchema, GoogleWorkspaceTierSchema, GoogleWorkspaceConfigSchema, MicrosoftWorkspaceConfigSchema, AgentGoogleWorkspaceConfigSchema, AgentMicrosoftWorkspaceConfigSchema, ReactionsSchema, ReleaseBlock, NetworkIsolationSchema, profileFields, ProfileSchema, _omitExtends, defaultsFields, AgentDefaultsSchema, AgentSchema, TelegramConfigSchema, MemoryBackendConfigSchema, VaultConfigSchema, QuotaConfigSchema, AutoReleaseCheckSchema, HostControlConfigSchema, HostdConfigSchema, SwitchroomConfigSchema;
+var CodeRepoEntrySchema, AgentBindMountSchema, ScheduleEntrySchema, AgentSoulSchema, AgentToolsSchema, AgentMemorySchema, HookEntrySchema, AgentHooksSchema, SubagentSchema, SessionSchema, SessionContinuitySchema, TelegramChannelSchema, ChannelsSchema, TIMEZONE_REGEX, ApproverIdSchema, GoogleWorkspaceTierSchema, GoogleWorkspaceConfigSchema, MicrosoftWorkspaceConfigSchema, NotionWorkspaceConfigSchema, AgentGoogleWorkspaceConfigSchema, AgentMicrosoftWorkspaceConfigSchema, AgentNotionWorkspaceConfigSchema, ReactionsSchema, ReleaseBlock, NetworkIsolationSchema, profileFields, ProfileSchema, _omitExtends, defaultsFields, AgentDefaultsSchema, AgentSchema, TelegramConfigSchema, MemoryBackendConfigSchema, VaultConfigSchema, QuotaConfigSchema, AutoReleaseCheckSchema, HostControlConfigSchema, HostdConfigSchema, SwitchroomConfigSchema;
 var init_schema = __esm(() => {
   init_zod();
   CodeRepoEntrySchema = exports_external.object({
@@ -11444,6 +11444,16 @@ var init_schema = __esm(() => {
     authority: exports_external.string().url().optional().describe("Microsoft authority endpoint. Defaults to " + "'https://login.microsoftonline.com/common' which accepts both " + "personal MSA and work/school tenants. Override only for " + "single-tenant deployments."),
     org_mode: exports_external.boolean().optional().describe("Opt-in to Teams + SharePoint surfaces (RFC §6.4). When true, " + "the v1 scope set adds Sites.ReadWrite.All AND the launcher " + "spawns softeria with --org-mode. Defaults to false — personal " + "MSA + standard work surfaces only. Flipping for an existing " + "consented account requires re-running 'auth microsoft account " + "add --replace' to consent the additional scope.")
   }).optional();
+  NotionWorkspaceConfigSchema = exports_external.object({
+    vault_key: exports_external.string().min(1).default("notion/integration-token").describe("Vault key holding the Notion internal-integration token. Default " + "`notion/integration-token`. Override only for non-standard vault " + "layouts. The broker's --allow ACL on this key is the authoritative " + "list of which agents may receive the token."),
+    databases: exports_external.record(exports_external.string().regex(/^[a-z0-9][a-z0-9_-]{0,62}$/, {
+      message: "notion_workspace.databases friendly names must match " + "/^[a-z0-9][a-z0-9_-]{0,62}$/ — lowercase letters, digits, " + "hyphens, underscores. Got: '%s'."
+    }), exports_external.string().regex(/^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-9a-fA-F]{4}-?[0-9a-fA-F]{4}-?[0-9a-fA-F]{12}$/, {
+      message: "notion_workspace.databases values must be Notion database " + "UUIDs (32 hex characters, optional dashes)."
+    })).default({}).describe("Friendly-name → Notion database UUID map. Operator-managed; agents " + "reference databases by friendly name only — they never see or type " + "UUIDs. Populate via `switchroom notion list-dbs` (PR 4) after " + "vault-putting the integration token and sharing DBs with the " + "integration in Notion's UI."),
+    mcp_version: exports_external.string().min(1).optional().describe("Optional pin for the upstream `@notionhq/notion-mcp-server` npm " + "package version. Default is the build-time `NOTION_MCP_PINNED_VERSION` " + "constant. Override only when reproducing operator-specific bugs."),
+    rate_limit_rps: exports_external.number().int().positive().max(10).optional().describe("Optional global rate-limit budget in requests per second across all " + "switchroom agents sharing this integration token. Defaults to 3 " + "(Notion's documented public-API limit). Lower it if you also use " + "the integration token from outside switchroom and need to share " + "budget. Higher than 10 is rejected — if you think you need it, " + "your usage probably needs a workspace-tier upgrade with Notion.")
+  }).optional();
   AgentGoogleWorkspaceConfigSchema = exports_external.object({
     account: exports_external.string().regex(/^[^@\s:]+@[^@\s:]+\.[^@\s:]+$/, {
       message: "google_workspace.account must be a Google account email like " + "'alice@example.com' (colons not allowed)"
@@ -11457,6 +11467,13 @@ var init_schema = __esm(() => {
     }).transform((v) => v.trim().toLowerCase()).optional().describe("RFC #1873: the Microsoft account this agent uses for the M365 MCP. " + "Must be a key in top-level `microsoft_accounts:` with this agent " + "listed in its `enabled_for[]`. Read by the auth-broker " + "(get-credentials, provider=microsoft) and by the scaffold to " + "decide whether to emit the `ms-365` MCP entry. Normalized to " + "lowercase so it matches the microsoft_accounts key (which is " + "also normalized)."),
     org_mode: exports_external.boolean().optional().describe("Per-agent org_mode override (RFC #1873 §6.4). When set, replaces " + "the top-level microsoft_workspace.org_mode for this agent. " + "Defaults to top-level value (which defaults to false).")
   }).optional();
+  AgentNotionWorkspaceConfigSchema = exports_external.object({
+    databases: exports_external.array(exports_external.string().regex(/^[a-z0-9][a-z0-9_-]{0,62}$/, {
+      message: "notion_workspace.databases entries must be friendly names " + "matching /^[a-z0-9][a-z0-9_-]{0,62}$/ — these must appear as " + "keys in top-level notion_workspace.databases."
+    })).min(1, {
+      message: "notion_workspace.databases must list at least one friendly " + "name. An empty list rejects every Notion tool call — if you " + "want to remove this agent's Notion access, delete the entire " + "notion_workspace block instead."
+    }).optional().describe("Optional per-agent allowlist of database friendly names this " + "agent may read/write. Each name must exist as a key in top-level " + "notion_workspace.databases. Omit the field (or leave it undefined) " + "to grant access to every DB the upstream integration can see — " + "appropriate for an admin/orchestrator agent. Set the list to " + "narrow access for specialist agents.")
+  }).optional();
   ReactionsSchema = exports_external.object({
     enabled: exports_external.boolean().optional().describe("Master switch for the reaction-trigger path. When false, " + "reactions are still persisted via recordReaction but never " + "dispatched to the agent as synthetic inbound turns. Default true."),
     trigger_emojis: exports_external.array(exports_external.string()).optional().describe("Emoji allowlist that triggers a synthetic inbound when reacted " + "to a bot message. Default ['\uD83D\uDC4E', '❌', '\uD83D\uDC4D', '✅']. Cascade " + "mode: REPLACE (not union) — setting this at a layer replaces " + "lower layers entirely, so an operator can narrow to [] to " + "disable triggering without flipping `enabled`."),
@@ -11593,6 +11610,7 @@ var init_schema = __esm(() => {
     drive: AgentGoogleWorkspaceConfigSchema.describe("RFC D legacy key — use `google_workspace:` instead. Per-agent " + "google_workspace overrides (currently approvers + tier). When set, " + "replaces the top-level approvers list for this agent. " + "google_client_id/secret are not per-agent — they live at the top level."),
     google_workspace: AgentGoogleWorkspaceConfigSchema.describe("RFC G canonical key. Per-agent Google Workspace overrides — currently " + "approvers (replaces, does not extend the top-level list) and tier " + "(`core` | `extended` | `complete`, replaces top-level default). " + "google_client_id/secret are not per-agent — they live at the top level. " + "Mutually exclusive with `drive:` on the same agent (loader fails fast " + "if both are set)."),
     microsoft_workspace: AgentMicrosoftWorkspaceConfigSchema.describe("RFC #1873 (Microsoft 365 integration). Per-agent Microsoft Workspace " + "override — pins the Microsoft account this agent reads via the " + "auth-broker (must be a key in top-level `microsoft_accounts:` with " + "this agent in its `enabled_for[]`) and optionally overrides org_mode. " + "microsoft_client_id/secret are not per-agent."),
+    notion_workspace: AgentNotionWorkspaceConfigSchema.describe("RFC docs/rfcs/notion-integration.md. Per-agent Notion access. " + "Presence opts the agent IN (launcher scaffolded, MCP entry emitted, " + "broker grants the integration token). Optional `databases:` filter " + "narrows which DBs this agent may read/write — names must resolve in " + "top-level notion_workspace.databases. Absence opts the agent OUT."),
     repos: exports_external.record(exports_external.string().regex(/^[a-z0-9][a-z0-9-]*$/, "Repo slug must be kebab-case ASCII: start with a lowercase letter or digit, contain only lowercase letters, digits, and hyphens"), exports_external.object({
       url: exports_external.string().min(1).describe("Git remote URL for the repo (e.g. 'git@github.com:org/repo.git' or " + "'https://github.com/org/repo.git'). Used verbatim for git clone."),
       branch_default: exports_external.string().optional().describe("Default branch to track (defaults to the remote's HEAD, typically 'main'). " + "The per-agent branch 'agent/<agentName>/main' fast-forwards to this branch " + "when the worktree is clean on session start.")
@@ -11716,6 +11734,7 @@ var init_schema = __esm(() => {
     drive: GoogleWorkspaceConfigSchema.describe("RFC D legacy key — use `google_workspace:` instead. Optional Google " + "Workspace onboarding configuration. When set, supplies Google OAuth " + "client credentials, the approver allowlist for `switchroom drive " + "connect`, and the optional tier knob. Env vars " + "(SWITCHROOM_GOOGLE_CLIENT_ID, SWITCHROOM_GOOGLE_CLIENT_SECRET, " + "SWITCHROOM_APPROVER_USER_ID) take precedence over this block when " + "set, preserving back-compat with the env-only flow shipped in #766."),
     google_workspace: GoogleWorkspaceConfigSchema.describe("RFC G canonical key. Top-level Google Workspace configuration — " + "OAuth client credentials, approver allowlist, and tier knob (`core` " + "| `extended` | `complete`, default `core`). Mutually exclusive with " + "`drive:` at the top level (loader fails fast if both are set)."),
     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 docs/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."),
     host_control: HostControlConfigSchema.default({}).describe("Host-control daemon configuration. Defaults to enabled=true since " + "RFC C Phase 2 (docs/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. Currently scopes the opt-in flag and rate cap for the new " + "`config_propose_edit` verb (PR 1a — disabled by default)."),
@@ -11912,6 +11931,34 @@ var init_overlay_loader = __esm(() => {
   OVERLAY_SOURCE = Symbol.for("switchroom.config.overlay-source");
 });
 
+// src/config/notion-workspace-acl.ts
+function validateNotionWorkspaceConfig(config) {
+  const issues = [];
+  const dbMap = config.notion_workspace?.databases ?? {};
+  const known = new Set(Object.keys(dbMap));
+  for (const [agentName, agentRaw] of Object.entries(config.agents ?? {})) {
+    if (!agentRaw)
+      continue;
+    const dbFilter = agentRaw.notion_workspace?.databases;
+    if (dbFilter === undefined)
+      continue;
+    if (dbFilter.length === 0) {
+      issues.push(`  agents.${agentName}.notion_workspace.databases is an empty ` + `list. Delete the entire notion_workspace block to remove Notion ` + `access, or list at least one database friendly name.`);
+      continue;
+    }
+    if (config.notion_workspace === undefined) {
+      issues.push(`  agents.${agentName}.notion_workspace is set but the top-level ` + `notion_workspace block is missing. Configure the integration ` + `globally first (vault_key + databases map), then grant per-agent ` + `access.`);
+      continue;
+    }
+    for (const name of dbFilter) {
+      if (!known.has(name)) {
+        issues.push(`  agents.${agentName}.notion_workspace.databases references ` + `unknown database "${name}". Add it to top-level ` + `notion_workspace.databases (run \`switchroom notion list-dbs\` ` + `to see the UUIDs the integration can read), or remove the ` + `reference.`);
+      }
+    }
+  }
+  return issues;
+}
+
 // src/config/loader.ts
 var exports_loader = {};
 __export(exports_loader, {
@@ -12034,6 +12081,10 @@ function loadConfig(configPath) {
   }
   applyAgentOverlays(config);
   validateAllCronTopicAliases(config, filePath);
+  const notionIssues = validateNotionWorkspaceConfig(config);
+  if (notionIssues.length > 0) {
+    throw new ConfigError(`Invalid notion_workspace configuration in ${filePath}`, notionIssues);
+  }
   return config;
 }
 function validateAllCronTopicAliases(config, filePath) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchroom",
-  "version": "0.13.54",
+  "version": "0.13.56",
   "description": "Run Claude Code 24/7 on your Claude Pro/Max subscription over Telegram. Open-source alternative to OpenClaw and NanoClaw — no API keys.",
   "type": "module",
   "bin": {

package/skills/notion/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: notion
+version: 0.1.0
+description: |
+  Use when the user wants to read, search, write, or update content in
+  their Notion workspace. The agent has access via the `notion` MCP
+  server (`@notionhq/notion-mcp-server`) configured by the operator
+  with a per-database allowlist.
+
+  Triggers on phrasings including: "add this to Notion", "what's on my
+  Notion tasks", "find that page about X in Notion", "create a Notion
+  page for this", "update the notion entry for X", "search Notion
+  for…", "append this to my Notion notes", "show me what's in the
+  essays database", "log this in Notion".
+
+  Do NOT use to create new Notion databases — that's disabled in v1
+  (operators create DBs via Notion's UI). Do NOT use to scan or
+  enumerate the operator's whole workspace ad-hoc — the per-database
+  allowlist scopes what the agent can see, and brute-forcing past it
+  is a defence-in-depth violation.
+
+  Also do not use this skill to file bugs against a GitHub repo
+  (that's `file-bug`) or to search the web (Notion search is workspace-
+  scoped only).
+---
+
+# Notion
+
+This skill is your interface to the operator's Notion workspace. The
+operator has registered an integration in Notion's settings and
+shared specific pages/databases with it. Your access is gated at two
+layers:
+
+1. **Notion's upstream share-list** — the integration can only see
+   pages and databases the operator explicitly shared with it in
+   Notion's UI.
+2. **switchroom's per-agent allowlist** — within what the upstream
+   integration can see, the operator can further restrict YOU to a
+   subset via `agents.<your-name>.notion_workspace.databases:`.
+
+Both layers are enforced at the broker / hook level. You don't have
+to compute the intersection — if you call a tool against a
+disallowed database, you'll get a clean block reason naming the DB.
+
+## Tool surface
+
+The Notion MCP exposes the standard set:
+
+- **Search.** `search` finds pages or databases by title/content
+  across what the integration can see. **In switchroom v1, `search`
+  is BLOCKED for any agent with a non-empty
+  `notion_workspace.databases:` allowlist** — the post-filter that
+  would strip out-of-allowlist results isn't wired yet. Use
+  `query_database` against your allowed DBs instead. Admin-shaped
+  agents (no per-DB filter) can search normally.
+- **Database queries.** `query_database` runs a filter+sort against
+  a database. You need the database's UUID (operator gives these
+  via friendly names in `notion_workspace.databases` — ask the
+  operator for "what's the UUID for X" if needed).
+- **Page reads.** `get_page` and `get_block_children` walk a page's
+  structure. Both go through the allowlist gate.
+- **Page writes.** `create_page` (with `parent.database_id`),
+  `update_page`, `update_block`, `append_block_children`,
+  `delete_block`, `create_comment`. The allowlist gate runs first;
+  blocked tool calls return a reason you can surface to the operator.
+- **Database writes.** `update_database` — schema changes,
+  rename, etc. Gated.
+
+## Tools NOT available
+
+- **`create_database`** — disabled in v1 (operators create
+  databases via Notion's UI). If the user asks you to "create a new
+  database for X", say so and offer to populate an existing one or
+  prompt the operator to make the DB first.
+- **`delete_database`** — same posture.
+
+## Common workflows
+
+### "What's on my tasks?"
+
+1. Ask the operator (or use `config_get` to check your own
+   `notion_workspace.databases`) for the friendly name of the tasks
+   DB. The friendly name resolves to a UUID via
+   `notion_workspace.databases` in switchroom.yaml.
+2. `query_database` with that UUID. Default filter: `not done`.
+3. Format results as a brief markdown list. Don't dump the full
+   property soup — operators want titles + status, not raw IDs.
+
+### "Add `<thing>` to Notion"
+
+1. Default destination is the database whose friendly name matches
+   the user's intent (`tasks`, `notes`, `essays`). Ask if it's
+   ambiguous.
+2. Use `create_page` with `parent.database_id: <uuid>`. The page's
+   properties need to match the target DB's schema — call
+   `retrieve_database` first if you're unsure of the property
+   names.
+3. After creation, confirm to the user with the page title and
+   the Notion URL.
+
+### "Find that thing about X"
+
+1. If you have full search access (no `databases:` filter): `search`
+   with the query, take the top result unless ambiguous.
+2. If `search` is blocked for you (the hook will return a clear
+   message naming the v1 limitation): `query_database` against
+   each of your allowed DBs in turn, with a title-contains or
+   property filter. List your allowed DBs by checking
+   `notion_workspace.databases:` in your config via `config_get`.
+
+### "Update the page about X"
+
+1. `search` or `query_database` to find the page.
+2. `update_page` (for properties — status, tags, dates) or
+   `append_block_children` (for body content).
+3. **Be careful** with `update_block` and `delete_block` — these
+   modify the page's body irreversibly. Prefer `append_block_children`
+   when the user's intent is "add a note to this page", not
+   "replace what's there".
+
+## Limits and behaviours
+
+- **Rate limit**: Notion's public API is ~3 rps per integration.
+  Multi-step turns with many writes may slow down (the hook makes
+  resolver calls per write). If you see "Notion API failed: 429",
+  back off and retry once.
+- **No `create_database`**: if the user asks for a new database,
+  say "I can write into existing DBs but the operator creates new
+  ones in Notion's UI." Then offer the closest existing DB.
+- **Standalone pages denied**: pages without a database parent
+  (workspace root pages, personal sub-pages) are hard-denied in
+  v1. The block reason names this when it fires; pass it through
+  to the user.
+
+## When the allowlist denies you
+
+If a tool call returns "DB <uuid> is not in your allowlist", that's
+the operator's intended scope — don't try to work around it. Surface
+the message to the user honestly: "I'm not configured to access that
+database. You can add it to my allowlist with
+`agents.<my-name>.notion_workspace.databases` in switchroom.yaml."
+
+## Authoring small notes vs full pages
+
+For one-line "log this thought" intents, prefer `append_block_children`
+to an existing daily-notes / inbox page rather than creating a new
+page per note. Operators usually have an inbox DB; ask if you're
+unsure.

package/telegram-plugin/ack-flag.ts

@@ -0,0 +1,66 @@
+/**
+ * Ack-first state flag — load-bearing for the ack-first-pretool hook
+ * (see `src/cli/ack-first-pretool.ts` and
+ * `reference/conversational-pacing.md` beat 1).
+ *
+ * The gateway is the source of truth for "has the model called reply
+ * yet this turn?". The PreToolUse hook runs as a short-lived child
+ * process so it can't read gateway in-memory state; the hand-off is
+ * a single file inside `$TELEGRAM_STATE_DIR`:
+ *
+ *   - `markAckSent()` touches the file on the first reply per turn.
+ *   - `clearAckSent()` removes it at turn_started.
+ *   - The hook checks `existsSync(path)` → allow / block.
+ *
+ * Per-agent isolation is built-in: `$TELEGRAM_STATE_DIR` is the
+ * agent's per-container state dir (~/.switchroom/agents/<name>/telegram,
+ * bind-mounted into /state/agent/home/.switchroom/agents/<name>/telegram
+ * inside the container).
+ *
+ * All operations are best-effort: a write or unlink failure logs to
+ * stderr and returns; the gate is informational UX, not a safety
+ * primitive, so a broken state-dir must never wedge reply itself.
+ */
+
+import { closeSync, existsSync, openSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+
+export const ACK_SENT_MARKER = "ack-sent.flag";
+
+function markerPath(): string | null {
+  const dir = process.env.TELEGRAM_STATE_DIR;
+  if (!dir) return null;
+  return join(dir, ACK_SENT_MARKER);
+}
+
+/** Create the ack-sent marker. Idempotent (no-op if it exists). */
+export function markAckSent(): void {
+  const path = markerPath();
+  if (path == null) return;
+  if (existsSync(path)) return;
+  try {
+    const fd = openSync(path, "w");
+    closeSync(fd);
+  } catch (err) {
+    process.stderr.write(
+      `ack-flag: markAckSent failed path=${path}: ${err}\n`,
+    );
+  }
+}
+
+/** Remove the ack-sent marker. Idempotent. */
+export function clearAckSent(): void {
+  const path = markerPath();
+  if (path == null) return;
+  try {
+    unlinkSync(path);
+  } catch (err: unknown) {
+    // ENOENT is the common case (turn started before any prior turn
+    // ran a reply); silently swallow.
+    const code = (err as { code?: string } | undefined)?.code;
+    if (code === "ENOENT") return;
+    process.stderr.write(
+      `ack-flag: clearAckSent failed path=${path}: ${err}\n`,
+    );
+  }
+}