switchroom 0.16.28 → 0.16.38

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

@@ -4180,19 +4180,30 @@ var init_schema = __esm(() => {
     stream_mode: exports_external.enum(["pty", "checklist"]).optional().describe("How live progress is streamed to Telegram during a turn. " + "'pty' (default) surfaces text snapshots of Claude Code's TUI — " + "compatible but can flicker as Ink re-renders. 'checklist' drives " + "a structured progress card from session-tail events — stable " + "order, per-tool status emojis, fires only on semantic transitions."),
     stream_throttle_ms: exports_external.number().int().nonnegative().optional().describe("Throttle window in ms between successive in-place stream edits " + "during a turn. Lower = more responsive stream, higher = fewer API " + "calls. Floored at 250 by draft-stream itself. Default 400 ms for DMs " + "and 1000 ms for groups/forums (respects Telegram's ~1 edit/sec/message " + "practical ceiling). Override per-agent if a particular agent needs " + "snappier or quieter streaming."),
     clear_status_on_completion: exports_external.boolean().optional().describe("When true, the live activity/status feed (the in-place 'what it's " + "doing' message — Reading X, Searching the web for Y, …) is DELETED " + "when the turn's final answer lands, so only the reply remains. " + "Default false: the status message is left in the chat as a record " + "(its last step marked done) — no post-then-delete. Per-agent " + "override; cascades defaults → profile → agent (per-key)."),
+    pin_status_while_working: exports_external.boolean().optional().describe("When true (default), the framework SILENTLY pins the already-" + "rendered status message while its work is in-flight and auto-unpins " + "it on completion — the per-turn activity/status message (foreground) " + "and the '\uD83D\uDEE0 Worker' background-worker message. Keeps in-flight work " + "in view when the conversation scrolls past it (fast turns, stacked " + "background workers, long turns). No new surface is rendered; it pins " + "a message the chat already owns. The pin never buzzes the device. " + "The ONE sanctioned pin under chat-is-the-single-source-of-truth. " + "Set false to disable. Per-agent override; cascades defaults → " + "profile → agent (per-key)."),
     hotReloadStable: exports_external.boolean().optional().describe("If true, the stable workspace prefix (AGENTS.md, SOUL.md, USER.md, " + "IDENTITY.md, TOOLS.md) is re-injected on every turn via " + "the UserPromptSubmit hook instead of baked into --append-system-prompt " + "at session start. Lets workspace edits propagate without a restart. " + "Costs ~5-10% per-turn latency/spend since the stable prefix is no " + "longer prompt-cached."),
     inject_on_change: exports_external.boolean().optional().describe("Context-efficiency gate for per-turn hook injection (default true). " + "When true (the default), the turn-pacing directive and dynamic " + "workspace content are only re-emitted when their content changes or " + "the session_id changes — suppressing redundant injection that " + "otherwise triples compaction frequency. Set to false to revert to " + "the legacy always-emit behaviour (every turn injects the full " + "content regardless of whether it changed)."),
     orphan_promotion_ms: exports_external.number().int().nonnegative().optional().describe("How long (ms) a parent turn waits for a sub-agent JSONL watcher " + "to deliver sub_agent_started before the heartbeat promotes the spawn " + "to a synthesised 'running' row. Default 5000. Set to 0 to disable " + "orphan promotion entirely."),
     cold_sub_agent_threshold_ms: exports_external.number().int().nonnegative().optional().describe("JSONL-cold threshold (ms). When a running sub-agent emits no events " + "for this long, the heartbeat synthesises a turn_end for it so the " + "deferred-completion path can proceed. Default 30000. Set to 0 to " + "disable the synthetic close."),
     deferred_completion_timeout_ms: exports_external.number().int().nonnegative().optional().describe("Force-close timeout (ms) for deferred sub-agent completion. After " + "the parent turn_end arrives while sub-agents are still running, the " + "card is force-closed after this many ms even if sub-agents never " + "finish. Watcher-disconnect safety net. Default 180000 (3 min)."),
+    approval_timeout_minutes: exports_external.number().int().nonnegative().optional().describe("Operator approval-card lifetime (minutes) for the tool-use 'Allow " + "once' card and the vault grant decision wait. After this long with " + "no operator tap, the card auto-denies (a TIMEOUT, not a denial — the " + "agent is told not to retry). Default 60. hostd-gated verbs " + "(mcp__hostd__*) keep their own longer window; the hostd " + "config-propose card is not governed by this key."),
     sub_agent_tick_interval_ms: exports_external.number().int().nonnegative().optional().describe("Heartbeat tick interval (ms) for sub-agent rendering. Forces a " + "re-render of the elapsed-time counter while sub-agents are running, " + "even during silent stretches between tool calls. Default 10000 (10 s). " + "Set to 0 to disable the elapsed-ticker path."),
     edit_budget_threshold: exports_external.number().int().nonnegative().optional().describe("Telegram API edit budget per minute before the progress-card driver " + "falls back to a slower coalesce window. When a chat accumulates more " + "than this many card edits in the trailing 60 s, the driver switches " + "to a wider coalesce interval until the rate drops back. Default 18. " + "Increase if your gateway frequently bumps the Telegram edit-rate ceiling " + "with many parallel sub-agents; decrease for a more conservative buffer."),
     stickers: exports_external.record(exports_external.string(), exports_external.string()).optional().describe("Sticker aliases for the `send_sticker` MCP tool (#576). Maps a " + "short alias name (e.g. 'happy', 'thinking') to a Telegram file_id. " + "Operator-curated — capture file_ids from inbound stickers the user " + "sends and add them here. The agent calls send_sticker(chat_id, " + "alias='happy') and the gateway resolves to the file_id at send " + "time. Aliases enable persona-flavored expressiveness without " + "exposing raw file_ids in the agent prompt. Personal-assistant / " + "health-coach personas benefit; coding agents typically don't " + "configure any."),
     voice_in: exports_external.object({
       enabled: exports_external.boolean().optional().describe("Master switch for voice-message transcription."),
       provider: exports_external.enum(["openai"]).optional().describe("Transcription provider. Only 'openai' (Whisper API) supported in the spike (#578); " + "Groq/Deepgram/local-whisper-cli are follow-up choices."),
-      language: exports_external.string().optional().describe("Optional ISO-639-1 language hint (e.g. 'en', 'fr'). Skips Whisper's auto-detection.")
-    }).optional().describe("Inbound voice-message transcription (#578). When enabled, voice/audio " + "messages from allowlisted users are downloaded, transcribed via the " + "configured provider, and surface to the agent as the user's text. " + "API key read from ~/.switchroom/openai-api-key (mode 0600). Off by " + "default — opt-in per agent. Cascades from defaults.channels.telegram.voice_in. " + "(Migrated from per-agent root in #596 — see consistency unification.)"),
+      language: exports_external.string().optional().describe("Optional ISO-639-1 language hint (e.g. 'en', 'fr'). Skips Whisper's auto-detection."),
+      api_key: exports_external.string().optional().describe("Transcription-provider API key, as a `vault:<key>` reference " + "(e.g. 'vault:openai/api-key' — the default if omitted). The " + "gateway resolves it through the vault broker at use-time and " + "never writes the resolved value to disk or the agent prompt. " + "`switchroom enable voice-in` vault-stores the key and writes " + "this reference for you. A literal key is accepted but " + "discouraged — keep secrets in the vault.")
+    }).optional().describe("Inbound voice-message transcription (#578). When enabled, voice/audio " + "messages from allowlisted users are downloaded, transcribed via the " + "configured provider, and surface to the agent as the user's text. " + "The provider API key is a `vault:` reference (`api_key`, default " + "`vault:openai/api-key`) resolved through the vault broker at " + "use-time — opt-in third-party key, honest-exception per the " + "subscription-honest outcome. Off by default — opt-in per agent. " + "Cascades from defaults.channels.telegram.voice_in. " + "(Migrated from per-agent root in #596 — see consistency unification.)"),
+    voice_out: exports_external.object({
+      enabled: exports_external.boolean().optional().describe("Master switch for spoken-reply (TTS) voice notes."),
+      engine: exports_external.enum(["kokoro", "openai"]).default("kokoro").describe("Synthesis engine. 'kokoro' = local voice sidecar (POST /tts, " + "subscription-honest, no third-party key); 'openai' = OpenAI TTS " + "cloud (honest-exception, requires an `api_key` vault ref). " + "'kokoro' is only active when the host voice verdict is local " + "(SWITCHROOM_VOICE_ENGINE === 'local'); otherwise voice-out is a " + "no-op and replies stay text-only."),
+      voice: exports_external.string().optional().describe("Engine-specific voice id (e.g. a Kokoro voice name or an OpenAI " + "voice like 'alloy'). Optional — the sidecar/engine has its own " + "default when omitted."),
+      reply_mode: exports_external.enum(["voice+text", "voice-only", "on-demand"]).default("voice+text").describe("How the spoken reply accompanies the text. 'voice+text' sends " + "both the normal text reply and a voice note; 'voice-only' sends " + "the voice note and suppresses the text body. 'on-demand' sends " + "the text reply with a single '\uD83D\uDD0A Listen' inline button and " + "synthesizes NO audio until the user taps it — zero GPU/sidecar " + "work unless requested, which keeps the voice pipeline " + "subscription-honest and visible (nothing is generated behind the " + "user's back). The Listen button is injected ONLY when the reply " + "carries no agent-authored buttons, to avoid colliding with the " + "single_use keyboard-strip that protects agent buttons from " + "double-fire. In every mode the text reply is ALWAYS still sent " + "when synthesis fails or the reply exceeds max_chars — the user's " + "answer is never dropped silently."),
+      max_chars: exports_external.number().int().positive().optional().describe("Per-voice-note chunk size (chars). Default 600; clamped to the " + "engine's hard cap (1200). A reply LONGER than this is NOT truncated " + "to text — it's split on sentence/paragraph boundaries and spoken " + "across several sequential voice notes, so the full answer is heard " + "even when the user can't read the screen (driving / cycling). Lower " + "it for snappier individual notes; raise it (up to 1200) for fewer, " + "longer notes."),
+      api_key: exports_external.string().optional().describe("OpenAI TTS API key as a `vault:<key>` reference (only used when " + "engine='openai'; default 'vault:openai/api-key'). Resolved through " + "the vault broker at use-time and never written to disk or the agent " + "prompt. Ignored for engine='kokoro' (the sidecar needs no key).")
+    }).optional().describe("Outbound spoken replies via TTS (PR-C2). When enabled, the gateway " + "synthesizes the agent's text reply into an OGG/Opus voice note and " + "sends it alongside (or instead of) the text, per reply_mode. The " + "'kokoro' engine uses the local voice sidecar (POST /tts) and is only " + "active when the host voice verdict is local; the 'openai' engine is " + "an honest-exception cloud path gated on an `api_key` vault ref. Voice " + "is best-effort and fully non-fatal — any TTS error falls back to the " + "text reply. Off by default — opt-in per agent. " + "Cascades from defaults.channels.telegram.voice_out."),
     telegraph: exports_external.object({
       enabled: exports_external.boolean().optional().describe("Master switch for Telegraph Instant View publishing."),
       threshold: exports_external.number().int().positive().optional().describe("Char count above which a reply is published to Telegraph instead of " + "HTML-chunked into multiple Telegram messages. Default 3000 (≈3 chunks)."),
@@ -5029,6 +5040,41 @@ var init_merge = __esm(() => {
   })(mergeAgentConfig ||= {});
 });
 
+// src/config/paths.ts
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+function home() {
+  return process.env.HOME ?? "/root";
+}
+function warnLegacyStateOnce(legacy) {
+  if (_legacyStateWarned)
+    return;
+  _legacyStateWarned = true;
+  process.stderr.write(`[switchroom] DEPRECATED: reading legacy state from ${legacy}. ` + "Run `mv ~/.clerk ~/.switchroom` (and rename any top-level `clerk:` " + "key in switchroom.yaml to `switchroom:`). This back-compat shim is " + `REMOVED in v0.13.0 — no automatic migration exists.
+`);
+}
+function resolveDualPath(pathStr) {
+  const h = home();
+  if (pathStr.startsWith("~/")) {
+    const rest = pathStr.slice(2);
+    const absolute = resolve(h, rest);
+    if (rest.startsWith(`${DEFAULT_STATE_DIR}/`)) {
+      const frag = rest.slice(DEFAULT_STATE_DIR.length + 1);
+      if (!existsSync(absolute)) {
+        const legacy = resolve(h, LEGACY_STATE_DIR, frag);
+        if (existsSync(legacy)) {
+          warnLegacyStateOnce(legacy);
+          return legacy;
+        }
+      }
+    }
+    return absolute;
+  }
+  return resolve(pathStr);
+}
+var DEFAULT_STATE_DIR = ".switchroom", LEGACY_STATE_DIR = ".clerk", _legacyStateWarned = false;
+var init_paths = () => {};
+
 // node_modules/.bun/yaml@2.8.3/node_modules/yaml/dist/nodes/identity.js
 var require_identity = __commonJS((exports) => {
   var ALIAS = Symbol.for("yaml.alias");
@@ -11993,41 +12039,6 @@ var init_dist = __esm(() => {
   $visitAsync = visit.visitAsync;
 });
 
-// src/config/paths.ts
-import { existsSync } from "node:fs";
-import { resolve } from "node:path";
-function home() {
-  return process.env.HOME ?? "/root";
-}
-function warnLegacyStateOnce(legacy) {
-  if (_legacyStateWarned)
-    return;
-  _legacyStateWarned = true;
-  process.stderr.write(`[switchroom] DEPRECATED: reading legacy state from ${legacy}. ` + "Run `mv ~/.clerk ~/.switchroom` (and rename any top-level `clerk:` " + "key in switchroom.yaml to `switchroom:`). This back-compat shim is " + `REMOVED in v0.13.0 — no automatic migration exists.
-`);
-}
-function resolveDualPath(pathStr) {
-  const h = home();
-  if (pathStr.startsWith("~/")) {
-    const rest = pathStr.slice(2);
-    const absolute = resolve(h, rest);
-    if (rest.startsWith(`${DEFAULT_STATE_DIR}/`)) {
-      const frag = rest.slice(DEFAULT_STATE_DIR.length + 1);
-      if (!existsSync(absolute)) {
-        const legacy = resolve(h, LEGACY_STATE_DIR, frag);
-        if (existsSync(legacy)) {
-          warnLegacyStateOnce(legacy);
-          return legacy;
-        }
-      }
-    }
-    return absolute;
-  }
-  return resolve(pathStr);
-}
-var DEFAULT_STATE_DIR = ".switchroom", LEGACY_STATE_DIR = ".clerk", _legacyStateWarned = false;
-var init_paths = () => {};
-
 // src/config/overlay-schema.ts
 var OverlayDocSchema;
 var init_overlay_schema = __esm(() => {
@@ -13182,6 +13193,9 @@ var DEFAULT_RETAIN_MISSION = "Extract user preferences, ongoing projects, recurr
 // src/agents/reconcile-default-skills.ts
 var warnedMissingPool = new Set;
 
+// src/setup/host-capabilities.ts
+init_paths();
+
 // src/agents/compose.ts
 var AGENT_UID_MIN = 10001;
 var AGENT_UID_MAX = 10999;

package/dist/vault/broker/server.js

@@ -4180,19 +4180,30 @@ var init_schema = __esm(() => {
     stream_mode: exports_external.enum(["pty", "checklist"]).optional().describe("How live progress is streamed to Telegram during a turn. " + "'pty' (default) surfaces text snapshots of Claude Code's TUI — " + "compatible but can flicker as Ink re-renders. 'checklist' drives " + "a structured progress card from session-tail events — stable " + "order, per-tool status emojis, fires only on semantic transitions."),
     stream_throttle_ms: exports_external.number().int().nonnegative().optional().describe("Throttle window in ms between successive in-place stream edits " + "during a turn. Lower = more responsive stream, higher = fewer API " + "calls. Floored at 250 by draft-stream itself. Default 400 ms for DMs " + "and 1000 ms for groups/forums (respects Telegram's ~1 edit/sec/message " + "practical ceiling). Override per-agent if a particular agent needs " + "snappier or quieter streaming."),
     clear_status_on_completion: exports_external.boolean().optional().describe("When true, the live activity/status feed (the in-place 'what it's " + "doing' message — Reading X, Searching the web for Y, …) is DELETED " + "when the turn's final answer lands, so only the reply remains. " + "Default false: the status message is left in the chat as a record " + "(its last step marked done) — no post-then-delete. Per-agent " + "override; cascades defaults → profile → agent (per-key)."),
+    pin_status_while_working: exports_external.boolean().optional().describe("When true (default), the framework SILENTLY pins the already-" + "rendered status message while its work is in-flight and auto-unpins " + "it on completion — the per-turn activity/status message (foreground) " + "and the '\uD83D\uDEE0 Worker' background-worker message. Keeps in-flight work " + "in view when the conversation scrolls past it (fast turns, stacked " + "background workers, long turns). No new surface is rendered; it pins " + "a message the chat already owns. The pin never buzzes the device. " + "The ONE sanctioned pin under chat-is-the-single-source-of-truth. " + "Set false to disable. Per-agent override; cascades defaults → " + "profile → agent (per-key)."),
     hotReloadStable: exports_external.boolean().optional().describe("If true, the stable workspace prefix (AGENTS.md, SOUL.md, USER.md, " + "IDENTITY.md, TOOLS.md) is re-injected on every turn via " + "the UserPromptSubmit hook instead of baked into --append-system-prompt " + "at session start. Lets workspace edits propagate without a restart. " + "Costs ~5-10% per-turn latency/spend since the stable prefix is no " + "longer prompt-cached."),
     inject_on_change: exports_external.boolean().optional().describe("Context-efficiency gate for per-turn hook injection (default true). " + "When true (the default), the turn-pacing directive and dynamic " + "workspace content are only re-emitted when their content changes or " + "the session_id changes — suppressing redundant injection that " + "otherwise triples compaction frequency. Set to false to revert to " + "the legacy always-emit behaviour (every turn injects the full " + "content regardless of whether it changed)."),
     orphan_promotion_ms: exports_external.number().int().nonnegative().optional().describe("How long (ms) a parent turn waits for a sub-agent JSONL watcher " + "to deliver sub_agent_started before the heartbeat promotes the spawn " + "to a synthesised 'running' row. Default 5000. Set to 0 to disable " + "orphan promotion entirely."),
     cold_sub_agent_threshold_ms: exports_external.number().int().nonnegative().optional().describe("JSONL-cold threshold (ms). When a running sub-agent emits no events " + "for this long, the heartbeat synthesises a turn_end for it so the " + "deferred-completion path can proceed. Default 30000. Set to 0 to " + "disable the synthetic close."),
     deferred_completion_timeout_ms: exports_external.number().int().nonnegative().optional().describe("Force-close timeout (ms) for deferred sub-agent completion. After " + "the parent turn_end arrives while sub-agents are still running, the " + "card is force-closed after this many ms even if sub-agents never " + "finish. Watcher-disconnect safety net. Default 180000 (3 min)."),
+    approval_timeout_minutes: exports_external.number().int().nonnegative().optional().describe("Operator approval-card lifetime (minutes) for the tool-use 'Allow " + "once' card and the vault grant decision wait. After this long with " + "no operator tap, the card auto-denies (a TIMEOUT, not a denial — the " + "agent is told not to retry). Default 60. hostd-gated verbs " + "(mcp__hostd__*) keep their own longer window; the hostd " + "config-propose card is not governed by this key."),
     sub_agent_tick_interval_ms: exports_external.number().int().nonnegative().optional().describe("Heartbeat tick interval (ms) for sub-agent rendering. Forces a " + "re-render of the elapsed-time counter while sub-agents are running, " + "even during silent stretches between tool calls. Default 10000 (10 s). " + "Set to 0 to disable the elapsed-ticker path."),
     edit_budget_threshold: exports_external.number().int().nonnegative().optional().describe("Telegram API edit budget per minute before the progress-card driver " + "falls back to a slower coalesce window. When a chat accumulates more " + "than this many card edits in the trailing 60 s, the driver switches " + "to a wider coalesce interval until the rate drops back. Default 18. " + "Increase if your gateway frequently bumps the Telegram edit-rate ceiling " + "with many parallel sub-agents; decrease for a more conservative buffer."),
     stickers: exports_external.record(exports_external.string(), exports_external.string()).optional().describe("Sticker aliases for the `send_sticker` MCP tool (#576). Maps a " + "short alias name (e.g. 'happy', 'thinking') to a Telegram file_id. " + "Operator-curated — capture file_ids from inbound stickers the user " + "sends and add them here. The agent calls send_sticker(chat_id, " + "alias='happy') and the gateway resolves to the file_id at send " + "time. Aliases enable persona-flavored expressiveness without " + "exposing raw file_ids in the agent prompt. Personal-assistant / " + "health-coach personas benefit; coding agents typically don't " + "configure any."),
     voice_in: exports_external.object({
       enabled: exports_external.boolean().optional().describe("Master switch for voice-message transcription."),
       provider: exports_external.enum(["openai"]).optional().describe("Transcription provider. Only 'openai' (Whisper API) supported in the spike (#578); " + "Groq/Deepgram/local-whisper-cli are follow-up choices."),
-      language: exports_external.string().optional().describe("Optional ISO-639-1 language hint (e.g. 'en', 'fr'). Skips Whisper's auto-detection.")
-    }).optional().describe("Inbound voice-message transcription (#578). When enabled, voice/audio " + "messages from allowlisted users are downloaded, transcribed via the " + "configured provider, and surface to the agent as the user's text. " + "API key read from ~/.switchroom/openai-api-key (mode 0600). Off by " + "default — opt-in per agent. Cascades from defaults.channels.telegram.voice_in. " + "(Migrated from per-agent root in #596 — see consistency unification.)"),
+      language: exports_external.string().optional().describe("Optional ISO-639-1 language hint (e.g. 'en', 'fr'). Skips Whisper's auto-detection."),
+      api_key: exports_external.string().optional().describe("Transcription-provider API key, as a `vault:<key>` reference " + "(e.g. 'vault:openai/api-key' — the default if omitted). The " + "gateway resolves it through the vault broker at use-time and " + "never writes the resolved value to disk or the agent prompt. " + "`switchroom enable voice-in` vault-stores the key and writes " + "this reference for you. A literal key is accepted but " + "discouraged — keep secrets in the vault.")
+    }).optional().describe("Inbound voice-message transcription (#578). When enabled, voice/audio " + "messages from allowlisted users are downloaded, transcribed via the " + "configured provider, and surface to the agent as the user's text. " + "The provider API key is a `vault:` reference (`api_key`, default " + "`vault:openai/api-key`) resolved through the vault broker at " + "use-time — opt-in third-party key, honest-exception per the " + "subscription-honest outcome. Off by default — opt-in per agent. " + "Cascades from defaults.channels.telegram.voice_in. " + "(Migrated from per-agent root in #596 — see consistency unification.)"),
+    voice_out: exports_external.object({
+      enabled: exports_external.boolean().optional().describe("Master switch for spoken-reply (TTS) voice notes."),
+      engine: exports_external.enum(["kokoro", "openai"]).default("kokoro").describe("Synthesis engine. 'kokoro' = local voice sidecar (POST /tts, " + "subscription-honest, no third-party key); 'openai' = OpenAI TTS " + "cloud (honest-exception, requires an `api_key` vault ref). " + "'kokoro' is only active when the host voice verdict is local " + "(SWITCHROOM_VOICE_ENGINE === 'local'); otherwise voice-out is a " + "no-op and replies stay text-only."),
+      voice: exports_external.string().optional().describe("Engine-specific voice id (e.g. a Kokoro voice name or an OpenAI " + "voice like 'alloy'). Optional — the sidecar/engine has its own " + "default when omitted."),
+      reply_mode: exports_external.enum(["voice+text", "voice-only", "on-demand"]).default("voice+text").describe("How the spoken reply accompanies the text. 'voice+text' sends " + "both the normal text reply and a voice note; 'voice-only' sends " + "the voice note and suppresses the text body. 'on-demand' sends " + "the text reply with a single '\uD83D\uDD0A Listen' inline button and " + "synthesizes NO audio until the user taps it — zero GPU/sidecar " + "work unless requested, which keeps the voice pipeline " + "subscription-honest and visible (nothing is generated behind the " + "user's back). The Listen button is injected ONLY when the reply " + "carries no agent-authored buttons, to avoid colliding with the " + "single_use keyboard-strip that protects agent buttons from " + "double-fire. In every mode the text reply is ALWAYS still sent " + "when synthesis fails or the reply exceeds max_chars — the user's " + "answer is never dropped silently."),
+      max_chars: exports_external.number().int().positive().optional().describe("Per-voice-note chunk size (chars). Default 600; clamped to the " + "engine's hard cap (1200). A reply LONGER than this is NOT truncated " + "to text — it's split on sentence/paragraph boundaries and spoken " + "across several sequential voice notes, so the full answer is heard " + "even when the user can't read the screen (driving / cycling). Lower " + "it for snappier individual notes; raise it (up to 1200) for fewer, " + "longer notes."),
+      api_key: exports_external.string().optional().describe("OpenAI TTS API key as a `vault:<key>` reference (only used when " + "engine='openai'; default 'vault:openai/api-key'). Resolved through " + "the vault broker at use-time and never written to disk or the agent " + "prompt. Ignored for engine='kokoro' (the sidecar needs no key).")
+    }).optional().describe("Outbound spoken replies via TTS (PR-C2). When enabled, the gateway " + "synthesizes the agent's text reply into an OGG/Opus voice note and " + "sends it alongside (or instead of) the text, per reply_mode. The " + "'kokoro' engine uses the local voice sidecar (POST /tts) and is only " + "active when the host voice verdict is local; the 'openai' engine is " + "an honest-exception cloud path gated on an `api_key` vault ref. Voice " + "is best-effort and fully non-fatal — any TTS error falls back to the " + "text reply. Off by default — opt-in per agent. " + "Cascades from defaults.channels.telegram.voice_out."),
     telegraph: exports_external.object({
       enabled: exports_external.boolean().optional().describe("Master switch for Telegraph Instant View publishing."),
       threshold: exports_external.number().int().positive().optional().describe("Char count above which a reply is published to Telegraph instead of " + "HTML-chunked into multiple Telegram messages. Default 3000 (≈3 chunks)."),
@@ -5029,6 +5040,41 @@ var init_merge = __esm(() => {
   })(mergeAgentConfig ||= {});
 });
 
+// src/config/paths.ts
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+function home() {
+  return process.env.HOME ?? "/root";
+}
+function warnLegacyStateOnce(legacy) {
+  if (_legacyStateWarned)
+    return;
+  _legacyStateWarned = true;
+  process.stderr.write(`[switchroom] DEPRECATED: reading legacy state from ${legacy}. ` + "Run `mv ~/.clerk ~/.switchroom` (and rename any top-level `clerk:` " + "key in switchroom.yaml to `switchroom:`). This back-compat shim is " + `REMOVED in v0.13.0 — no automatic migration exists.
+`);
+}
+function resolveDualPath(pathStr) {
+  const h = home();
+  if (pathStr.startsWith("~/")) {
+    const rest = pathStr.slice(2);
+    const absolute = resolve(h, rest);
+    if (rest.startsWith(`${DEFAULT_STATE_DIR}/`)) {
+      const frag = rest.slice(DEFAULT_STATE_DIR.length + 1);
+      if (!existsSync(absolute)) {
+        const legacy = resolve(h, LEGACY_STATE_DIR, frag);
+        if (existsSync(legacy)) {
+          warnLegacyStateOnce(legacy);
+          return legacy;
+        }
+      }
+    }
+    return absolute;
+  }
+  return resolve(pathStr);
+}
+var DEFAULT_STATE_DIR = ".switchroom", LEGACY_STATE_DIR = ".clerk", _legacyStateWarned = false;
+var init_paths = () => {};
+
 // node_modules/.bun/yaml@2.8.3/node_modules/yaml/dist/nodes/identity.js
 var require_identity = __commonJS((exports) => {
   var ALIAS = Symbol.for("yaml.alias");
@@ -11993,41 +12039,6 @@ var init_dist = __esm(() => {
   $visitAsync = visit.visitAsync;
 });
 
-// src/config/paths.ts
-import { existsSync as existsSync4 } from "node:fs";
-import { resolve as resolve2 } from "node:path";
-function home() {
-  return process.env.HOME ?? "/root";
-}
-function warnLegacyStateOnce(legacy) {
-  if (_legacyStateWarned)
-    return;
-  _legacyStateWarned = true;
-  process.stderr.write(`[switchroom] DEPRECATED: reading legacy state from ${legacy}. ` + "Run `mv ~/.clerk ~/.switchroom` (and rename any top-level `clerk:` " + "key in switchroom.yaml to `switchroom:`). This back-compat shim is " + `REMOVED in v0.13.0 — no automatic migration exists.
-`);
-}
-function resolveDualPath(pathStr) {
-  const h = home();
-  if (pathStr.startsWith("~/")) {
-    const rest = pathStr.slice(2);
-    const absolute = resolve2(h, rest);
-    if (rest.startsWith(`${DEFAULT_STATE_DIR}/`)) {
-      const frag = rest.slice(DEFAULT_STATE_DIR.length + 1);
-      if (!existsSync4(absolute)) {
-        const legacy = resolve2(h, LEGACY_STATE_DIR, frag);
-        if (existsSync4(legacy)) {
-          warnLegacyStateOnce(legacy);
-          return legacy;
-        }
-      }
-    }
-    return absolute;
-  }
-  return resolve2(pathStr);
-}
-var DEFAULT_STATE_DIR = ".switchroom", LEGACY_STATE_DIR = ".clerk", _legacyStateWarned = false;
-var init_paths = () => {};
-
 // src/config/overlay-schema.ts
 var OverlayDocSchema;
 var init_overlay_schema = __esm(() => {
@@ -12726,6 +12737,9 @@ var DEFAULT_RETAIN_MISSION = "Extract user preferences, ongoing projects, recurr
 // src/agents/reconcile-default-skills.ts
 var warnedMissingPool = new Set;
 
+// src/setup/host-capabilities.ts
+init_paths();
+
 // src/agents/compose.ts
 var AGENT_UID_MIN = 10001;
 var AGENT_UID_MAX = 10999;
@@ -12750,18 +12764,18 @@ import { randomBytes, scryptSync, createCipheriv, createDecipheriv } from "node:
 import {
   readFileSync as readFileSync3,
   writeFileSync,
-  existsSync as existsSync2,
+  existsSync as existsSync3,
   renameSync,
   mkdirSync,
   unlinkSync as unlinkSync2,
   lstatSync,
   realpathSync
 } from "node:fs";
-import { dirname, basename, resolve } from "node:path";
+import { dirname, basename, resolve as resolve2 } from "node:path";
 
 // src/vault/flock.ts
 import {
-  existsSync,
+  existsSync as existsSync2,
   openSync,
   closeSync,
   writeSync,
@@ -12795,7 +12809,7 @@ function readLockHolder(lockPath) {
 }
 function pidIsLive(pid) {
   if (process.platform === "linux") {
-    return existsSync(`/proc/${pid}`);
+    return existsSync2(`/proc/${pid}`);
   }
   try {
     process.kill(pid, 0);
@@ -12857,7 +12871,7 @@ function lockFileMtimeIsOlderThan(lockPath, budgetMs) {
 var SENTINEL_DIR_RECENT_WRITE_MS = 60000;
 function clearStaleSentinelDir(lockPath) {
   try {
-    if (!existsSync(lockPath))
+    if (!existsSync2(lockPath))
       return true;
     const s = statSync(lockPath);
     if (!s.isDirectory())
@@ -12990,18 +13004,18 @@ var SCRYPT_MAXMEM = 128 * 1024 * 1024;
 function atomicWriteFileSync(path, data, mode) {
   let effectivePath = path;
   try {
-    if (existsSync2(path) && lstatSync(path).isSymbolicLink()) {
+    if (existsSync3(path) && lstatSync(path).isSymbolicLink()) {
       effectivePath = realpathSync(path);
     }
   } catch {}
-  const dir = dirname(resolve(effectivePath));
-  const tmp = resolve(dir, `.${basename(effectivePath)}.${process.pid}.${Date.now()}.tmp`);
+  const dir = dirname(resolve2(effectivePath));
+  const tmp = resolve2(dir, `.${basename(effectivePath)}.${process.pid}.${Date.now()}.tmp`);
   try {
     writeFileSync(tmp, data, { encoding: "utf8", mode });
     renameSync(tmp, effectivePath);
   } catch (err) {
     try {
-      if (existsSync2(tmp))
+      if (existsSync3(tmp))
         unlinkSync2(tmp);
     } catch {}
     throw err;
@@ -13060,7 +13074,7 @@ function normalizeSecrets(raw) {
   return out;
 }
 function openVault(passphrase, vaultPath) {
-  if (!existsSync2(vaultPath)) {
+  if (!existsSync3(vaultPath)) {
     throw new VaultError(`Vault file not found: ${vaultPath}`);
   }
   let vaultFile;
@@ -13087,7 +13101,7 @@ function openVault(passphrase, vaultPath) {
   return normalizeSecrets(vaultData.secrets ?? {});
 }
 function saveVault(passphrase, vaultPath, secrets) {
-  if (!existsSync2(vaultPath)) {
+  if (!existsSync3(vaultPath)) {
     throw new VaultError(`Vault file not found: ${vaultPath}`);
   }
   let releaseLock = null;
@@ -13138,7 +13152,7 @@ function acquireVaultLock(vaultPath) {
 import {
   copyFileSync,
   chmodSync,
-  existsSync as existsSync3,
+  existsSync as existsSync4,
   fsyncSync as fsyncSync3,
   lstatSync as lstatSync2,
   mkdirSync as mkdirSync2,
@@ -13152,8 +13166,8 @@ import {
 } from "node:fs";
 import { createHash as createHash2 } from "node:crypto";
 import { basename as basename2, dirname as dirname2, join } from "node:path";
-function vaultLayoutPaths(home) {
-  const switchroomRoot = join(home, ".switchroom");
+function vaultLayoutPaths(home2) {
+  const switchroomRoot = join(home2, ".switchroom");
   return {
     oldPath: join(switchroomRoot, "vault.enc"),
     newPath: join(switchroomRoot, "vault", "vault.enc"),
@@ -13161,16 +13175,16 @@ function vaultLayoutPaths(home) {
     switchroomRoot
   };
 }
-function inspectVaultLayout(home) {
-  return runMigration(home, { dryRun: true });
+function inspectVaultLayout(home2) {
+  return runMigration(home2, { dryRun: true });
 }
-function runMigration(home, opts) {
-  const { oldPath, newPath, parent, switchroomRoot } = vaultLayoutPaths(home);
-  const lockTarget = existsSync3(newPath) ? newPath : existsSync3(oldPath) ? oldPath : null;
+function runMigration(home2, opts) {
+  const { oldPath, newPath, parent, switchroomRoot } = vaultLayoutPaths(home2);
+  const lockTarget = existsSync4(newPath) ? newPath : existsSync4(oldPath) ? oldPath : null;
   const release = !opts.dryRun && lockTarget !== null ? acquireVaultLock(lockTarget) : null;
   try {
     const oldStat = lstatSyncOrNull(oldPath);
-    const newExists = existsSync3(newPath);
+    const newExists = existsSync4(newPath);
     if (oldStat === null && !newExists) {
       return { kind: "no-vault" };
     }
@@ -13239,7 +13253,7 @@ function sha256File(path) {
 }
 function atomicReplaceWithSymlink(target, linkTarget) {
   const tmp = join(dirname2(target), `.${basename2(target)}.symlink-tmp`);
-  if (existsSync3(tmp)) {
+  if (existsSync4(tmp)) {
     try {
       unlinkSync3(tmp);
     } catch {}

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "switchroom",
-  "version": "0.16.28",
+  "//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.16.38",
   "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

@@ -43,7 +43,9 @@ tools is to let you do the edit yourself.
     still shares your memory + tools but drops your accumulated conversation
     context). A **daily/weekly** cron defaults to a **full turn in your live
     session** (Tier 2: your model, your whole context). So routine frequent
-    checks are already cheap without you doing anything.
+    checks are already cheap without you doing anything. Cron-fresh sessions
+    render rich markdown too, so scheduled/digest/daily-memory output should
+    use **bold** section headers + `code` for identifiers, just like a live reply.
   - *`model: "sonnet"` / `context: "fresh"`* — force the cheap Tier-1 session
     even for a **daily/weekly** self-contained job (summarise a feed, format a
     digest) — overrides the cadence default. *`context: "agent"`* does the
@@ -53,7 +55,10 @@ tools is to let you do the edit yourself.
     ping — text fully determined, no thinking) — ask the **operator** for a
     **`kind: action`**: it runs **model-free, zero tokens** (no session at all),
     posting your fixed/templated text or firing a fixed request. The cheapest
-    tier there is.
+    tier there is. The action `text` is rendered as full GFM markdown
+    (**bold**, _italic_, `code`, ~~strikethrough~~, links) — so a literal `*`
+    or `_` in fixed text becomes formatting unless you set `parse_mode: text`,
+    which sends the string verbatim (the escape hatch).
   - *"Only act when X changes"* — don't poll with a frequent prompt cron (every
     fire is a wasted turn when nothing changed). Ask the **operator** for a
     **`kind: poll`** (model-free check, e.g. a webpage/API — only a *change*