fix: keep session token totals in sync (#1440) (thanks @robbyczgw-cla)

docs(gog): fix invalid service name in auth example

CHANGELOG.md

@@ -2,79 +2,80 @@
 
 Docs: https://docs.clawd.bot
 
-## 2026.1.22
-
-### Changes
-- Highlight: Lobster optional plugin tool for typed workflows + approval gates. https://docs.clawd.bot/tools/lobster
-- Agents: add identity avatar config support and Control UI avatar rendering. (#1329, #1424) Thanks @dlauer.
-- Memory: prevent CLI hangs by deferring vector probes, adding sqlite-vec/embedding timeouts, and showing sync progress early.
-- Docs: add troubleshooting entry for gateway.mode blocking gateway start. https://docs.clawd.bot/gateway/troubleshooting
-- Docs: add /model allowlist troubleshooting note. (#1405)
-- Docs: add per-message Gmail search example for gog. (#1220) Thanks @mbelinky.
-- UI: show per-session assistant identity in the Control UI. (#1420) Thanks @robbyczgw-cla.
-- Onboarding: remove the run setup-token auth option (paste setup-token or reuse CLI creds instead).
-- Signal: add typing indicators and DM read receipts via signal-cli.
-- MSTeams: add file uploads, adaptive cards, and attachment handling improvements. (#1410) Thanks @Evizero.
-- CLI: add `clawdbot update wizard` for interactive channel selection and restart prompts. https://docs.clawd.bot/cli/update
-
-### Breaking
-- **BREAKING:** Envelope and system event timestamps now default to host-local time (was UTC) so agents don’t have to constantly convert.
+## 2026.1.22 (unreleased)
 
 ### Fixes
-- Media: accept MEDIA paths with spaces/tilde and prefer the message tool hint for image replies.
-- Google Antigravity: drop unsigned thinking blocks for Claude models to avoid signature errors.
-- Config: avoid stack traces for invalid configs and log the config path.
-- CLI: read Codex CLI account_id for workspace billing. (#1422) Thanks @aj47.
-- Agents: include skills section in minimal prompts for subagents. (#1431) Thanks @robbyczgw-cla.
-- Doctor: avoid recreating WhatsApp config when only legacy routing keys remain. (#900)
-- Doctor: warn when gateway.mode is unset with configure/config guidance.
-- OpenCode Zen: route models to the Zen API shape per family so proxy endpoints are used. (#1416)
-- Browser: suppress Chrome restore prompts for managed profiles. (#1419) Thanks @jamesgroat.
-- Logs: align rolling log filenames with local time and fall back to latest file when today's log is missing. (#1343)
-- Models: inherit session model overrides in thread/topic sessions (Telegram topics, Slack/Discord threads). (#1376)
-- macOS: keep local auto bind loopback-first; only use tailnet when bind=tailnet.
-- macOS: include Textual syntax highlighting resources in packaged app to prevent chat crashes. (#1362)
-- macOS: keep chat pinned to bottom during streaming replies. (#1279)
-- Cron: cap reminder context history to 10 messages and honor `contextMessages`. (#1103) Thanks @mkbehr.
-- Exec approvals: treat main as the default agent + migrate legacy default allowlists. (#1417) Thanks @czekaj.
-- Exec: avoid defaulting to elevated mode when elevated is not allowed.
-- Exec approvals: align node/gateway allowlist prechecks and approval gating; avoid null optional params in approval requests. (#1425) Thanks @czekaj.
-- UI: refresh debug panel on route-driven tab changes. (#1373) Thanks @yazinsai.
+- BlueBubbles: stop typing indicator on idle/no-reply. (#1439) Thanks @Nicell.
+- Auto-reply: only report a model switch when session state is available. (#1465) Thanks @robbyczgw-cla.
+- Auto-reply: keep cached context token count in sync after compaction. (#1440) Thanks @robbyczgw-cla.
+- Control UI: resolve local avatar URLs with basePath across injection + identity RPC. (#1457) Thanks @dlauer.
+- Agents: surface concrete API error details instead of generic AI service errors.
+- Docs: fix gog auth services example to include docs scope. (#1454) Thanks @zerone0x.
+
+## 2026.1.21-2
+
+### Fixes
+- Control UI: ignore bootstrap identity placeholder text for avatar values and fall back to the default avatar. https://docs.clawd.bot/cli/agents https://docs.clawd.bot/web/control-ui
 
 ## 2026.1.21
 
+### Highlights
+- Lobster optional plugin tool for typed workflows + approval gates. https://docs.clawd.bot/tools/lobster
+- Custom assistant identity + avatars in the Control UI. https://docs.clawd.bot/cli/agents https://docs.clawd.bot/web/control-ui
+- Cache optimizations: cache-ttl pruning + defaults reduce token spend on cold requests. https://docs.clawd.bot/concepts/session-pruning
+- Exec approvals + elevated ask/full modes. https://docs.clawd.bot/tools/exec-approvals https://docs.clawd.bot/tools/elevated
+- Signal typing/read receipts + MSTeams attachments. https://docs.clawd.bot/channels/signal https://docs.clawd.bot/channels/msteams
+- `/models` UX refresh + `clawdbot update wizard`. https://docs.clawd.bot/cli/models https://docs.clawd.bot/cli/update
+
 ### Changes
-- Heartbeat: allow running heartbeats in an explicit session key. (#1256) Thanks @zknicker.
-- CLI: default exec approvals to the local host, add gateway/node targeting flags, and show target details in allowlist output.
-- CLI: exec approvals mutations render tables instead of raw JSON.
-- Exec approvals: support wildcard agent allowlists (`*`) across all agents.
-- Exec approvals: allowlist matches resolved binary paths only, add safe stdin-only bins, and tighten allowlist shell parsing.
-- Nodes: expose node PATH in status/describe and bootstrap PATH for node-host execution.
-- CLI: flatten node service commands under `clawdbot node` and remove `service node` docs.
-- CLI: move gateway service commands under `clawdbot gateway` and add `gateway probe` for reachability.
-- Sessions: add per-channel reset overrides via `session.resetByChannel`. (#1353) Thanks @cash-echo-bot.
+- Highlight: Lobster optional plugin tool for typed workflows + approval gates. https://docs.clawd.bot/tools/lobster (#1152) Thanks @vignesh07.
+- Agents/UI: add identity avatar config support and Control UI avatar rendering. (#1329, #1424) Thanks @dlauer. https://docs.clawd.bot/gateway/configuration https://docs.clawd.bot/cli/agents
+- Control UI: add custom assistant identity support and per-session identity display. (#1420) Thanks @robbyczgw-cla. https://docs.clawd.bot/web/control-ui
+- CLI: add `clawdbot update wizard` with interactive channel selection + restart prompts, plus preflight checks before rebasing. https://docs.clawd.bot/cli/update
+- Models/Commands: add `/models`, improve `/model` listing UX, and expand `clawdbot models` paging. (#1398) Thanks @vignesh07. https://docs.clawd.bot/cli/models
+- CLI: move gateway service commands under `clawdbot gateway`, flatten node service commands under `clawdbot node`, and add `gateway probe` for reachability. https://docs.clawd.bot/cli/gateway https://docs.clawd.bot/cli/node
+- Exec: add elevated ask/full modes, tighten allowlist gating, and render approvals tables on write. https://docs.clawd.bot/tools/elevated https://docs.clawd.bot/tools/exec-approvals
+- Exec approvals: default to local host, add gateway/node targeting + target details, support wildcard agent allowlists, and tighten allowlist parsing/safe bins. https://docs.clawd.bot/cli/approvals https://docs.clawd.bot/tools/exec-approvals
+- Heartbeat: allow explicit session keys and active hours. (#1256) Thanks @zknicker. https://docs.clawd.bot/gateway/heartbeat
+- Sessions: add per-channel idle durations via `sessions.channelIdleMinutes`. (#1353) Thanks @cash-echo-bot.
+- Nodes: run exec-style, expose PATH in status/describe, and bootstrap PATH for node-host execution. https://docs.clawd.bot/cli/node
+- Cache: add `cache.ttlPrune` mode and auth-aware defaults for cache TTL behavior.
+- Queue: add per-channel debounce overrides for auto-reply. https://docs.clawd.bot/concepts/queue
+- Discord: add wildcard channel config support. (#1334) Thanks @pvoo. https://docs.clawd.bot/channels/discord
+- Signal: add typing indicators and DM read receipts via signal-cli. https://docs.clawd.bot/channels/signal
+- MSTeams: add file uploads, adaptive cards, and attachment handling improvements. (#1410) Thanks @Evizero. https://docs.clawd.bot/channels/msteams
+- Onboarding: remove the run setup-token auth option (paste setup-token or reuse CLI creds instead).
+- macOS: refresh Settings (location access in Permissions, connection mode in menu, remove CLI install UI).
+- Diagnostics: add cache trace config for debugging. (#1370) Thanks @parubets.
+- Docs: Lobster guides + org URL updates, /model allowlist troubleshooting, Gmail message search examples, gateway.mode troubleshooting, prompt injection guidance, npm prefix/node CLI notes, control UI dev gatewayUrl note, tool_use FAQ, showcase video, and sharp/node-gyp workaround. (#1427, #1220, #1405) Thanks @vignesh07, @mbelinky.
 
 ### Breaking
 - **BREAKING:** Control UI now rejects insecure HTTP without device identity by default. Use HTTPS (Tailscale Serve) or set `gateway.controlUi.allowInsecureAuth: true` to allow token-only auth. https://docs.clawd.bot/web/control-ui#insecure-http
+- **BREAKING:** Envelope and system event timestamps now default to host-local time (was UTC) so agents don’t have to constantly convert.
 
 ### Fixes
+- Streaming/Typing/Media: keep reply tags across streamed chunks, start typing indicators at run start, and accept MEDIA paths with spaces/tilde while preferring the message tool hint for image replies.
+- Agents/Providers: drop unsigned thinking blocks for Claude models (Google Antigravity) and enforce alphanumeric tool call ids for strict providers (Mistral/OpenRouter). (#1372) Thanks @zerone0x.
+- Exec approvals: treat main as the default agent, align node/gateway allowlist prechecks, validate resolved paths, avoid allowlist resolve races, and avoid null optional params. (#1417, #1414, #1425) Thanks @czekaj.
+- Exec/Windows: resolve Windows exec paths with extensions and handle safe-bin exe names.
 - Nodes/macOS: prompt on allowlist miss for node exec approvals, persist allowlist decisions, and flatten node invoke errors. (#1394) Thanks @ngutman.
-- Gateway: keep auto bind loopback-first and add explicit tailnet binding to avoid Tailscale taking over local UI. (#1380)
-- Agents: enforce 9-char alphanumeric tool call ids for Mistral providers. (#1372) Thanks @zerone0x.
+- Gateway: prevent multiple gateways from sharing the same config/state (singleton lock), keep auto bind loopback-first with explicit tailnet binding, and improve SSH auth handling. (#1380)
+- Control UI: remove the chat stop button, keep the composer aligned to the bottom edge, stabilize session previews, and refresh the debug panel on route-driven tab changes. (#1373) Thanks @yazinsai.
+- UI/config: export `SECTION_META` for config form modules. (#1418) Thanks @MaudeBot.
+- macOS: keep chat pinned during streaming replies, include Textual resources, respect wildcard exec approvals, allow SSH agent auth, and default distribution builds to universal binaries. (#1279, #1362, #1384, #1396) Thanks @ameno-, @JustYannicc.
+- BlueBubbles: resolve short message IDs safely, expose full IDs in templates, and harden short-id fetch wrappers. (#1369, #1387) Thanks @tyler6204.
+- Models/Configure: inherit session model overrides in threads/topics, map OpenCode Zen models to the correct APIs, narrow Anthropic OAuth allowlist handling, seed allowlist fallbacks, list the full catalog when no allowlist is set, and limit `/model` list output. (#1376, #1416)
+- Memory: prevent CLI hangs by deferring vector probes, add sqlite-vec/embedding timeouts, and make session memory indexing async.
+- Cron: cap reminder context history to 10 messages and honor `contextMessages`. (#1103) Thanks @mkbehr.
+- Cache: restore the 1h cache TTL option and reset the pruning window.
+- Zalo Personal: tolerate ANSI/log-prefixed JSON output from `zca`. (#1379) Thanks @ptn1411.
+- Browser: suppress Chrome restore prompts for managed profiles. (#1419) Thanks @jamesgroat.
+- Infra: preserve fetch helper methods/preconnect when wrapping abort signals and normalize Telegram fetch aborts.
+- Config/Doctor: avoid stack traces for invalid configs, log the config path, avoid WhatsApp config resurrection, and warn when `gateway.mode` is unset. (#900)
+- CLI: read Codex CLI account_id for workspace billing. (#1422) Thanks @aj47.
+- Logs/Status: align rolling log filenames with local time and report sandboxed runtime in `clawdbot status`. (#1343)
 - Embedded runner: persist injected history images so attachments aren’t reloaded each turn. (#1374) Thanks @Nicell.
-- Nodes tool: include agent/node/gateway context in tool failure logs to speed approval debugging.
-- macOS: exec approvals now respect wildcard agent allowlists (`*`).
-- macOS: allow SSH agent auth when no identity file is set. (#1384) Thanks @ameno-.
-- Gateway: prevent multiple gateways from sharing the same config/state at once (singleton lock).
-- UI: remove the chat stop button and keep the composer aligned to the bottom edge.
-- Typing: start instant typing indicators at run start so DMs and mentions show immediately.
-- Configure: restrict the model allowlist picker to OAuth-compatible Anthropic models and preselect Opus 4.5.
-- Configure: seed model fallbacks from the allowlist selection when multiple models are chosen.
-- Model picker: list the full catalog when no model allowlist is configured.
-- Discord: honor wildcard channel configs via shared match helpers. (#1334) Thanks @pvoo.
-- BlueBubbles: resolve short message IDs safely and expose full IDs in templates. (#1387) Thanks @tyler6204.
-- Infra: preserve fetch helper methods when wrapping abort signals. (#1387)
-- macOS: default distribution packaging to universal binaries. (#1396) Thanks @JustYannicc.
+- Nodes/Subagents: include agent/node/gateway context in tool failure logs and ensure subagent list uses the command session.
 
 ## 2026.1.20
 

appcast.xml

@@ -2,6 +2,80 @@
 <rss xmlns:sparkle="http://www.andymatuschak.org/xml-namespaces/sparkle" version="2.0">
     <channel>
         <title>Clawdbot</title>
+        <item>
+            <title>2026.1.21</title>
+            <pubDate>Thu, 22 Jan 2026 12:22:35 +0000</pubDate>
+            <link>https://raw.githubusercontent.com/clawdbot/clawdbot/main/appcast.xml</link>
+            <sparkle:version>7374</sparkle:version>
+            <sparkle:shortVersionString>2026.1.21</sparkle:shortVersionString>
+            <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>
+            <description><![CDATA[<h2>Clawdbot 2026.1.21</h2>
+<h3>Highlights</h3>
+<ul>
+<li>Lobster optional plugin tool for typed workflows + approval gates. https://docs.clawd.bot/tools/lobster</li>
+<li>Custom assistant identity + avatars in the Control UI. https://docs.clawd.bot/cli/agents https://docs.clawd.bot/web/control-ui</li>
+<li>Cache optimizations: cache-ttl pruning + defaults reduce token spend on cold requests. https://docs.clawd.bot/concepts/session-pruning</li>
+<li>Exec approvals + elevated ask/full modes. https://docs.clawd.bot/tools/exec-approvals https://docs.clawd.bot/tools/elevated</li>
+<li>Signal typing/read receipts + MSTeams attachments. https://docs.clawd.bot/channels/signal https://docs.clawd.bot/channels/msteams</li>
+<li><code>/models</code> UX refresh + <code>clawdbot update wizard</code>. https://docs.clawd.bot/cli/models https://docs.clawd.bot/cli/update</li>
+</ul>
+<h3>Changes</h3>
+<ul>
+<li>Highlight: Lobster optional plugin tool for typed workflows + approval gates. https://docs.clawd.bot/tools/lobster (#1152) Thanks @vignesh07.</li>
+<li>Agents/UI: add identity avatar config support and Control UI avatar rendering. (#1329, #1424) Thanks @dlauer. https://docs.clawd.bot/gateway/configuration https://docs.clawd.bot/cli/agents</li>
+<li>Control UI: add custom assistant identity support and per-session identity display. (#1420) Thanks @robbyczgw-cla. https://docs.clawd.bot/web/control-ui</li>
+<li>CLI: add <code>clawdbot update wizard</code> with interactive channel selection + restart prompts, plus preflight checks before rebasing. https://docs.clawd.bot/cli/update</li>
+<li>Models/Commands: add <code>/models</code>, improve <code>/model</code> listing UX, and expand <code>clawdbot models</code> paging. (#1398) Thanks @vignesh07. https://docs.clawd.bot/cli/models</li>
+<li>CLI: move gateway service commands under <code>clawdbot gateway</code>, flatten node service commands under <code>clawdbot node</code>, and add <code>gateway probe</code> for reachability. https://docs.clawd.bot/cli/gateway https://docs.clawd.bot/cli/node</li>
+<li>Exec: add elevated ask/full modes, tighten allowlist gating, and render approvals tables on write. https://docs.clawd.bot/tools/elevated https://docs.clawd.bot/tools/exec-approvals</li>
+<li>Exec approvals: default to local host, add gateway/node targeting + target details, support wildcard agent allowlists, and tighten allowlist parsing/safe bins. https://docs.clawd.bot/cli/approvals https://docs.clawd.bot/tools/exec-approvals</li>
+<li>Heartbeat: allow explicit session keys and active hours. (#1256) Thanks @zknicker. https://docs.clawd.bot/gateway/heartbeat</li>
+<li>Sessions: add per-channel idle durations via <code>sessions.channelIdleMinutes</code>. (#1353) Thanks @cash-echo-bot.</li>
+<li>Nodes: run exec-style, expose PATH in status/describe, and bootstrap PATH for node-host execution. https://docs.clawd.bot/cli/node</li>
+<li>Cache: add <code>cache.ttlPrune</code> mode and auth-aware defaults for cache TTL behavior.</li>
+<li>Queue: add per-channel debounce overrides for auto-reply. https://docs.clawd.bot/concepts/queue</li>
+<li>Discord: add wildcard channel config support. (#1334) Thanks @pvoo. https://docs.clawd.bot/channels/discord</li>
+<li>Signal: add typing indicators and DM read receipts via signal-cli. https://docs.clawd.bot/channels/signal</li>
+<li>MSTeams: add file uploads, adaptive cards, and attachment handling improvements. (#1410) Thanks @Evizero. https://docs.clawd.bot/channels/msteams</li>
+<li>Onboarding: remove the run setup-token auth option (paste setup-token or reuse CLI creds instead).</li>
+<li>macOS: refresh Settings (location access in Permissions, connection mode in menu, remove CLI install UI).</li>
+<li>Diagnostics: add cache trace config for debugging. (#1370) Thanks @parubets.</li>
+<li>Docs: Lobster guides + org URL updates, /model allowlist troubleshooting, Gmail message search examples, gateway.mode troubleshooting, prompt injection guidance, npm prefix/node CLI notes, control UI dev gatewayUrl note, tool_use FAQ, showcase video, and sharp/node-gyp workaround. (#1427, #1220, #1405) Thanks @vignesh07, @mbelinky.</li>
+</ul>
+<h3>Breaking</h3>
+<ul>
+<li><strong>BREAKING:</strong> Control UI now rejects insecure HTTP without device identity by default. Use HTTPS (Tailscale Serve) or set <code>gateway.controlUi.allowInsecureAuth: true</code> to allow token-only auth. https://docs.clawd.bot/web/control-ui#insecure-http</li>
+<li><strong>BREAKING:</strong> Envelope and system event timestamps now default to host-local time (was UTC) so agents don’t have to constantly convert.</li>
+</ul>
+<h3>Fixes</h3>
+<ul>
+<li>Streaming/Typing/Media: keep reply tags across streamed chunks, start typing indicators at run start, and accept MEDIA paths with spaces/tilde while preferring the message tool hint for image replies.</li>
+<li>Agents/Providers: drop unsigned thinking blocks for Claude models (Google Antigravity) and enforce alphanumeric tool call ids for strict providers (Mistral/OpenRouter). (#1372) Thanks @zerone0x.</li>
+<li>Exec approvals: treat main as the default agent, align node/gateway allowlist prechecks, validate resolved paths, avoid allowlist resolve races, and avoid null optional params. (#1417, #1414, #1425) Thanks @czekaj.</li>
+<li>Exec/Windows: resolve Windows exec paths with extensions and handle safe-bin exe names.</li>
+<li>Nodes/macOS: prompt on allowlist miss for node exec approvals, persist allowlist decisions, and flatten node invoke errors. (#1394) Thanks @ngutman.</li>
+<li>Gateway: prevent multiple gateways from sharing the same config/state (singleton lock), keep auto bind loopback-first with explicit tailnet binding, and improve SSH auth handling. (#1380)</li>
+<li>Control UI: remove the chat stop button, keep the composer aligned to the bottom edge, stabilize session previews, and refresh the debug panel on route-driven tab changes. (#1373) Thanks @yazinsai.</li>
+<li>UI/config: export <code>SECTION_META</code> for config form modules. (#1418) Thanks @MaudeBot.</li>
+<li>macOS: keep chat pinned during streaming replies, include Textual resources, respect wildcard exec approvals, allow SSH agent auth, and default distribution builds to universal binaries. (#1279, #1362, #1384, #1396) Thanks @ameno-, @JustYannicc.</li>
+<li>BlueBubbles: resolve short message IDs safely, expose full IDs in templates, and harden short-id fetch wrappers. (#1369, #1387) Thanks @tyler6204.</li>
+<li>Models/Configure: inherit session model overrides in threads/topics, map OpenCode Zen models to the correct APIs, narrow Anthropic OAuth allowlist handling, seed allowlist fallbacks, list the full catalog when no allowlist is set, and limit <code>/model</code> list output. (#1376, #1416)</li>
+<li>Memory: prevent CLI hangs by deferring vector probes, add sqlite-vec/embedding timeouts, and make session memory indexing async.</li>
+<li>Cron: cap reminder context history to 10 messages and honor <code>contextMessages</code>. (#1103) Thanks @mkbehr.</li>
+<li>Cache: restore the 1h cache TTL option and reset the pruning window.</li>
+<li>Zalo Personal: tolerate ANSI/log-prefixed JSON output from <code>zca</code>. (#1379) Thanks @ptn1411.</li>
+<li>Browser: suppress Chrome restore prompts for managed profiles. (#1419) Thanks @jamesgroat.</li>
+<li>Infra: preserve fetch helper methods/preconnect when wrapping abort signals and normalize Telegram fetch aborts.</li>
+<li>Config/Doctor: avoid stack traces for invalid configs, log the config path, avoid WhatsApp config resurrection, and warn when <code>gateway.mode</code> is unset. (#900)</li>
+<li>CLI: read Codex CLI account_id for workspace billing. (#1422) Thanks @aj47.</li>
+<li>Logs/Status: align rolling log filenames with local time and report sandboxed runtime in <code>clawdbot status</code>. (#1343)</li>
+<li>Embedded runner: persist injected history images so attachments aren’t reloaded each turn. (#1374) Thanks @Nicell.</li>
+<li>Nodes/Subagents: include agent/node/gateway context in tool failure logs and ensure subagent list uses the command session.</li>
+</ul>
+<p><a href="https://github.com/clawdbot/clawdbot/blob/main/CHANGELOG.md">View full changelog</a></p>
+]]></description>
+            <enclosure url="https://github.com/clawdbot/clawdbot/releases/download/v2026.1.21/Clawdbot-2026.1.21.zip" length="22284796" type="application/octet-stream" sparkle:edSignature="pXji4NMA/cu35iMxln385d6LnsT4yIZtFtFiR7sIimKeSC2CsyeWzzSD0EhJsN98PdSoy69iEFZt4I2ZtNCECg=="/>
+        </item>
         <item>
             <title>2026.1.21</title>
             <pubDate>Wed, 21 Jan 2026 08:18:22 +0000</pubDate>
@@ -208,86 +282,5 @@ Thanks @AlexMikhalev, @CoreyH, @John-Rood, @KrauseFx, @MaudeBot, @Nachx639, @Nic
 ]]></description>
             <enclosure url="https://github.com/clawdbot/clawdbot/releases/download/v2026.1.16-2/Clawdbot-2026.1.16-2.zip" length="21399591" type="application/octet-stream" sparkle:edSignature="zelT+KzN32cXsihbFniPF5Heq0hkwFfL3Agrh/AaoKUkr7kJAFarkGSOZRTWZ9y+DvOluzn2wHHjVigRjMzrBA=="/>
         </item>
-        <item>
-            <title>2026.1.15</title>
-            <pubDate>Fri, 16 Jan 2026 10:31:53 +0000</pubDate>
-            <link>https://raw.githubusercontent.com/clawdbot/clawdbot/main/appcast.xml</link>
-            <sparkle:version>5998</sparkle:version>
-            <sparkle:shortVersionString>2026.1.15</sparkle:shortVersionString>
-            <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>
-            <description><![CDATA[<h2>Clawdbot 2026.1.15</h2>
-<h3>Highlights</h3>
-<ul>
-<li>Plugins: add provider auth registry + <code>clawdbot models auth login</code> for plugin-driven OAuth/API key flows.</li>
-<li>Browser: improve remote CDP/Browserless support (auth passthrough, <code>wss</code> upgrade, timeouts, clearer errors).</li>
-<li>Heartbeat: per-agent configuration + 24h duplicate suppression. (#980) — thanks @voidserf.</li>
-<li>Security: audit warns on weak model tiers; app nodes store auth tokens encrypted (Keychain/SecurePrefs).</li>
-</ul>
-<h3>Breaking</h3>
-<ul>
-<li><strong>BREAKING:</strong> iOS minimum version is now 18.0 to support Textual markdown rendering in native chat. (#702)</li>
-<li><strong>BREAKING:</strong> Microsoft Teams is now a plugin; install <code>@clawdbot/msteams</code> via <code>clawdbot plugins install @clawdbot/msteams</code>.</li>
-</ul>
-<h3>Changes</h3>
-<ul>
-<li>CLI: set process titles to <code>clawdbot-<command></code> for clearer process listings.</li>
-<li>CLI/macOS: sync remote SSH target/identity to config and let <code>gateway status</code> auto-infer SSH targets (ssh-config aware).</li>
-<li>Heartbeat: tighten prompt guidance + suppress duplicate alerts for 24h. (#980) — thanks @voidserf.</li>
-<li>Sessions/Security: add <code>session.dmScope</code> for multi-user DM isolation and audit warnings. (#948) — thanks @Alphonse-arianee.</li>
-<li>Plugins: add provider auth registry + <code>clawdbot models auth login</code> for plugin-driven OAuth/API key flows.</li>
-<li>Onboarding: switch channels setup to a single-select loop with per-channel actions and disabled hints in the picker.</li>
-<li>TUI: show provider/model labels for the active session and default model.</li>
-<li>Heartbeat: add per-agent heartbeat configuration and multi-agent docs example.</li>
-<li>UI: show gateway auth guidance + doc link on unauthorized Control UI connections.</li>
-<li>Security: warn on weak model tiers (Haiku, below GPT-5, below Claude 4.5) in <code>clawdbot security audit</code>.</li>
-<li>Apps: store node auth tokens encrypted (Keychain/SecurePrefs).</li>
-<li>Daemon: share profile/state-dir resolution across service helpers and honor <code>CLAWDBOT_STATE_DIR</code> for Windows task scripts.</li>
-<li>Docs: clarify multi-gateway rescue bot guidance. (#969) — thanks @bjesuiter.</li>
-<li>Agents: add Current Date & Time system prompt section with configurable time format (auto/12/24).</li>
-<li>Tools: normalize Slack/Discord message timestamps with <code>timestampMs</code>/<code>timestampUtc</code> while keeping raw provider fields.</li>
-<li>macOS: add <code>system.which</code> for prompt-free remote skill discovery (with gateway fallback to <code>system.run</code>).</li>
-<li>Docs: add Date & Time guide and update prompt/timezone configuration docs.</li>
-<li>Messages: debounce rapid inbound messages across channels with per-connector overrides. (#971) — thanks @juanpablodlc.</li>
-<li>Messages: allow media-only sends (CLI/tool) and show Telegram voice recording status for voice notes. (#957) — thanks @rdev.</li>
-<li>Auth/Status: keep auth profiles sticky per session (rotate on compaction/new), surface provider usage headers in <code>/status</code> and <code>clawdbot models status</code>, and update docs.</li>
-<li>CLI: add <code>--json</code> output for <code>clawdbot daemon</code> lifecycle/install commands.</li>
-<li>Memory: make <code>node-llama-cpp</code> an optional dependency (avoid Node 25 install failures) and improve local-embeddings fallback/errors.</li>
-<li>Browser: add <code>snapshot refs=aria</code> (Playwright aria-ref ids) for self-resolving refs across <code>snapshot</code> → <code>act</code>.</li>
-<li>Browser: <code>profile="chrome"</code> now defaults to host control and returns clearer “attach a tab” errors.</li>
-<li>Browser: prefer stable Chrome for auto-detect, with Brave/Edge fallbacks and updated docs. (#983) — thanks @cpojer.</li>
-<li>Browser: increase remote CDP reachability timeouts + add <code>remoteCdpTimeoutMs</code>/<code>remoteCdpHandshakeTimeoutMs</code>.</li>
-<li>Browser: preserve auth/query tokens for remote CDP endpoints and pass Basic auth for CDP HTTP/WS. (#895) — thanks @mukhtharcm.</li>
-<li>Telegram: add bidirectional reaction support with configurable notifications and agent guidance. (#964) — thanks @bohdanpodvirnyi.</li>
-<li>Telegram: allow custom commands in the bot menu (merged with native; conflicts ignored). (#860) — thanks @nachoiacovino.</li>
-<li>Discord: allow allowlisted guilds without channel lists to receive messages when <code>groupPolicy="allowlist"</code>. — thanks @thewilloftheshadow.</li>
-<li>Discord: allow emoji/sticker uploads + channel actions in config defaults. (#870) — thanks @JDIVE.</li>
-</ul>
-<h3>Fixes</h3>
-<ul>
-<li>Fix: list model picker entries as provider/model pairs for explicit selection. (#970) — thanks @mcinteerj.</li>
-<li>Fix: align OpenAI image-gen defaults with DALL-E 3 standard quality and document output formats. (#880) — thanks @mkbehr.</li>
-<li>Fix: persist <code>gateway.mode=local</code> after selecting Local run mode in <code>clawdbot configure</code>, even if no other sections are chosen.</li>
-<li>Daemon: fix profile-aware service label resolution (env-driven) and add coverage for launchd/systemd/schtasks. (#969) — thanks @bjesuiter.</li>
-<li>Agents: avoid false positives when logging unsupported Google tool schema keywords.</li>
-<li>Agents: skip Gemini history downgrades for google-antigravity to preserve tool calls. (#894) — thanks @mukhtharcm.</li>
-<li>Status: restore usage summary line for current provider when no OAuth profiles exist.</li>
-<li>Fix: guard model fallback against undefined provider/model values. (#954) — thanks @roshanasingh4.</li>
-<li>Fix: refactor session store updates, add chat.inject, and harden subagent cleanup flow. (#944) — thanks @tyler6204.</li>
-<li>Fix: clean up suspended CLI processes across backends. (#978) — thanks @Nachx639.</li>
-<li>Fix: support MiniMax coding plan usage responses with <code>model_remains</code>/<code>current_interval_*</code> payloads.</li>
-<li>Fix: suppress WhatsApp pairing replies for historical catch-up DMs on initial link. (#904)</li>
-<li>Browser: extension mode recovers when only one tab is attached (stale targetId fallback).</li>
-<li>Browser: fix <code>tab not found</code> for extension relay snapshots/actions when Playwright blocks <code>newCDPSession</code> (use the single available Page).</li>
-<li>Browser: upgrade <code>ws</code> → <code>wss</code> when remote CDP uses <code>https</code> (fixes Browserless handshake).</li>
-<li>Telegram: skip <code>message_thread_id=1</code> for General topic sends while keeping typing indicators. (#848) — thanks @azade-c.</li>
-<li>Fix: sanitize user-facing error text + strip <code><final></code> tags across reply pipelines. (#975) — thanks @ThomsenDrake.</li>
-<li>Fix: normalize pairing CLI aliases, allow extension channels, and harden Zalo webhook payload parsing. (#991) — thanks @longmaba.</li>
-<li>Fix: allow local Tailscale Serve hostnames without treating tailnet clients as direct. (#885) — thanks @oswalpalash.</li>
-<li>Fix: reset sessions after role-ordering conflicts to recover from consecutive user turns. (#998)</li>
-</ul>
-<p><a href="https://github.com/clawdbot/clawdbot/blob/main/CHANGELOG.md">View full changelog</a></p>
-]]></description>
-            <enclosure url="https://github.com/clawdbot/clawdbot/releases/download/v2026.1.15/Clawdbot-2026.1.15.zip" length="12127276" type="application/octet-stream" sparkle:edSignature="o79vwTbtW/d91NQFRVfUDhsv6D4zIw7IkhY0N1iLImMu94BURgLcecA6z7Smy3bMobPwOyzN8yfm6mA/Rt8FCA=="/>
-        </item>
     </channel>
-</rss>
+</rss>

apps/macos/Sources/Clawdbot/ExecApprovals.swift

@@ -475,8 +475,8 @@ enum ExecApprovalsStore {
 
     private static func mergeAgents(
         current: ExecApprovalsAgent,
-        legacy: ExecApprovalsAgent
-    ) -> ExecApprovalsAgent {
+        legacy: ExecApprovalsAgent) -> ExecApprovalsAgent
+    {
         var seen = Set<String>()
         var allowlist: [ExecAllowlistEntry] = []
         func append(_ entry: ExecAllowlistEntry) {
@@ -486,8 +486,12 @@ enum ExecApprovalsStore {
             seen.insert(key)
             allowlist.append(entry)
         }
-        for entry in current.allowlist ?? [] { append(entry) }
-        for entry in legacy.allowlist ?? [] { append(entry) }
+        for entry in current.allowlist ?? [] {
+            append(entry)
+        }
+        for entry in legacy.allowlist ?? [] {
+            append(entry)
+        }
 
         return ExecApprovalsAgent(
             security: current.security ?? legacy.security,

apps/macos/Sources/Clawdbot/ExecApprovalsGatewayPrompter.swift

@@ -1,5 +1,6 @@
 import ClawdbotKit
 import ClawdbotProtocol
+import CoreGraphics
 import Foundation
 import OSLog
 
@@ -44,6 +45,7 @@ final class ExecApprovalsGatewayPrompter {
         do {
             let data = try JSONEncoder().encode(payload)
             let request = try JSONDecoder().decode(GatewayApprovalRequest.self, from: data)
+            guard self.shouldPresent(request: request) else { return }
             let decision = ExecApprovalsPromptPresenter.prompt(request.request)
             try await GatewayConnection.shared.requestVoid(
                 method: .execApprovalResolve,
@@ -56,4 +58,66 @@ final class ExecApprovalsGatewayPrompter {
             self.logger.error("exec approval handling failed \(error.localizedDescription, privacy: .public)")
         }
     }
+
+    private func shouldPresent(request: GatewayApprovalRequest) -> Bool {
+        let mode = AppStateStore.shared.connectionMode
+        let activeSession = WebChatManager.shared.activeSessionKey?.trimmingCharacters(in: .whitespacesAndNewlines)
+        let requestSession = request.request.sessionKey?.trimmingCharacters(in: .whitespacesAndNewlines)
+        return Self.shouldPresent(
+            mode: mode,
+            activeSession: activeSession,
+            requestSession: requestSession,
+            lastInputSeconds: Self.lastInputSeconds(),
+            thresholdSeconds: 120)
+    }
+
+    private static func shouldPresent(
+        mode: AppState.ConnectionMode,
+        activeSession: String?,
+        requestSession: String?,
+        lastInputSeconds: Int?,
+        thresholdSeconds: Int) -> Bool
+    {
+        let active = activeSession?.trimmingCharacters(in: .whitespacesAndNewlines)
+        let requested = requestSession?.trimmingCharacters(in: .whitespacesAndNewlines)
+        let recentlyActive = lastInputSeconds.map { $0 <= thresholdSeconds } ?? (mode == .local)
+
+        if let session = requested, !session.isEmpty {
+            if let active, !active.isEmpty {
+                return active == session
+            }
+            return recentlyActive
+        }
+
+        if let active, !active.isEmpty {
+            return true
+        }
+        return mode == .local
+    }
+
+    private static func lastInputSeconds() -> Int? {
+        let anyEvent = CGEventType(rawValue: UInt32.max) ?? .null
+        let seconds = CGEventSource.secondsSinceLastEventType(.combinedSessionState, eventType: anyEvent)
+        if seconds.isNaN || seconds.isInfinite || seconds < 0 { return nil }
+        return Int(seconds.rounded())
+    }
 }
+
+#if DEBUG
+extension ExecApprovalsGatewayPrompter {
+    static func _testShouldPresent(
+        mode: AppState.ConnectionMode,
+        activeSession: String?,
+        requestSession: String?,
+        lastInputSeconds: Int?,
+        thresholdSeconds: Int = 120) -> Bool
+    {
+        self.shouldPresent(
+            mode: mode,
+            activeSession: activeSession,
+            requestSession: requestSession,
+            lastInputSeconds: lastInputSeconds,
+            thresholdSeconds: thresholdSeconds)
+    }
+}
+#endif

apps/macos/Sources/Clawdbot/ExecApprovalsSocket.swift

@@ -13,6 +13,7 @@ struct ExecApprovalPromptRequest: Codable, Sendable {
     var ask: String?
     var agentId: String?
     var resolvedPath: String?
+    var sessionKey: String?
 }
 
 private struct ExecApprovalSocketRequest: Codable {
@@ -412,7 +413,8 @@ private enum ExecHostExecutor {
                     security: context.security.rawValue,
                     ask: context.ask.rawValue,
                     agentId: context.trimmedAgent,
-                    resolvedPath: context.resolution?.resolvedPath))
+                    resolvedPath: context.resolution?.resolvedPath,
+                    sessionKey: request.sessionKey))
 
             switch decision {
             case .deny:

apps/macos/Sources/Clawdbot/GatewayConnection.swift

@@ -69,6 +69,7 @@ actor GatewayConnection {
         case channelsLogout = "channels.logout"
         case modelsList = "models.list"
         case chatHistory = "chat.history"
+        case sessionsPreview = "sessions.preview"
         case chatSend = "chat.send"
         case chatAbort = "chat.abort"
         case skillsStatus = "skills.status"
@@ -540,6 +541,30 @@ extension GatewayConnection {
         return try await self.requestDecoded(method: .skillsUpdate, params: params)
     }
 
+    // MARK: - Sessions
+
+    func sessionsPreview(
+        keys: [String],
+        limit: Int? = nil,
+        maxChars: Int? = nil,
+        timeoutMs: Int? = nil) async throws -> ClawdbotSessionsPreviewPayload
+    {
+        let resolvedKeys = keys
+            .map { self.canonicalizeSessionKey($0) }
+            .filter { !$0.isEmpty }
+        if resolvedKeys.isEmpty {
+            return ClawdbotSessionsPreviewPayload(ts: 0, previews: [])
+        }
+        var params: [String: AnyCodable] = ["keys": AnyCodable(resolvedKeys)]
+        if let limit { params["limit"] = AnyCodable(limit) }
+        if let maxChars { params["maxChars"] = AnyCodable(maxChars) }
+        let timeout = timeoutMs.map { Double($0) }
+        return try await self.requestDecoded(
+            method: .sessionsPreview,
+            params: params,
+            timeoutMs: timeout)
+    }
+
     // MARK: - Chat
 
     func chatHistory(

apps/macos/Sources/Clawdbot/GatewayEndpointStore.swift

@@ -560,13 +560,13 @@ actor GatewayEndpointStore {
     {
         switch bindMode {
         case "tailnet":
-            return tailscaleIP ?? "127.0.0.1"
+            tailscaleIP ?? "127.0.0.1"
         case "auto":
-            return "127.0.0.1"
+            "127.0.0.1"
         case "custom":
-            return customBindHost ?? "127.0.0.1"
+            customBindHost ?? "127.0.0.1"
         default:
-            return "127.0.0.1"
+            "127.0.0.1"
         }
     }
 }

apps/macos/Sources/Clawdbot/MenuSessionsInjector.swift

@@ -188,11 +188,19 @@ extension MenuSessionsInjector {
                 if rhs.key == mainKey { return false }
                 return (lhs.updatedAt ?? .distantPast) > (rhs.updatedAt ?? .distantPast)
             }
+            if !rows.isEmpty {
+                let previewKeys = rows.prefix(20).map(\.key)
+                let task = Task {
+                    await SessionMenuPreviewLoader.prewarm(sessionKeys: previewKeys, maxItems: 10)
+                }
+                self.previewTasks.append(task)
+            }
 
             let headerItem = NSMenuItem()
             headerItem.tag = self.tag
             headerItem.isEnabled = false
-            let statusText = self.cachedErrorText ?? (isConnected ? nil : self.controlChannelStatusText(for: channelState))
+            let statusText = self
+                .cachedErrorText ?? (isConnected ? nil : self.controlChannelStatusText(for: channelState))
             let hosted = self.makeHostedView(
                 rootView: AnyView(MenuSessionsHeaderView(
                     count: rows.count,

apps/macos/Sources/Clawdbot/NodeMode/MacNodeRuntime.swift

@@ -679,7 +679,8 @@ actor MacNodeRuntime {
                         security: context.security.rawValue,
                         ask: context.ask.rawValue,
                         agentId: context.agentId,
-                        resolvedPath: context.resolution?.resolvedPath))
+                        resolvedPath: context.resolution?.resolvedPath,
+                        sessionKey: context.sessionKey))
             }
             switch decision {
             case .deny:

apps/macos/Sources/Clawdbot/SessionMenuPreviewView.swift

@@ -1,5 +1,6 @@
 import ClawdbotChatUI
 import ClawdbotKit
+import ClawdbotProtocol
 import OSLog
 import SwiftUI
 
@@ -31,24 +32,24 @@ actor SessionPreviewCache {
     static let shared = SessionPreviewCache()
 
     private struct CacheEntry {
-        let items: [SessionPreviewItem]
+        let snapshot: SessionMenuPreviewSnapshot
         let updatedAt: Date
     }
 
     private var entries: [String: CacheEntry] = [:]
 
-    func cachedItems(for sessionKey: String, maxAge: TimeInterval) -> [SessionPreviewItem]? {
+    func cachedSnapshot(for sessionKey: String, maxAge: TimeInterval) -> SessionMenuPreviewSnapshot? {
         guard let entry = self.entries[sessionKey] else { return nil }
         guard Date().timeIntervalSince(entry.updatedAt) < maxAge else { return nil }
-        return entry.items
+        return entry.snapshot
     }
 
-    func store(items: [SessionPreviewItem], for sessionKey: String) {
-        self.entries[sessionKey] = CacheEntry(items: items, updatedAt: Date())
+    func store(snapshot: SessionMenuPreviewSnapshot, for sessionKey: String) {
+        self.entries[sessionKey] = CacheEntry(snapshot: snapshot, updatedAt: Date())
     }
 
-    func lastItems(for sessionKey: String) -> [SessionPreviewItem]? {
-        self.entries[sessionKey]?.items
+    func lastSnapshot(for sessionKey: String) -> SessionMenuPreviewSnapshot? {
+        self.entries[sessionKey]?.snapshot
     }
 }
 
@@ -99,8 +100,12 @@ actor SessionPreviewLimiter {
 
 #if DEBUG
 extension SessionPreviewCache {
-    func _testSet(items: [SessionPreviewItem], for sessionKey: String, updatedAt: Date = Date()) {
-        self.entries[sessionKey] = CacheEntry(items: items, updatedAt: updatedAt)
+    func _testSet(
+        snapshot: SessionMenuPreviewSnapshot,
+        for sessionKey: String,
+        updatedAt: Date = Date())
+    {
+        self.entries[sessionKey] = CacheEntry(snapshot: snapshot, updatedAt: updatedAt)
     }
 
     func _testReset() {
@@ -219,50 +224,44 @@ enum SessionMenuPreviewLoader {
     private static let logger = Logger(subsystem: "com.clawdbot", category: "SessionPreview")
     private static let previewTimeoutSeconds: Double = 4
     private static let cacheMaxAgeSeconds: TimeInterval = 30
+    private static let previewMaxChars = 240
 
     private struct PreviewTimeoutError: LocalizedError {
         var errorDescription: String? { "preview timeout" }
     }
 
+    static func prewarm(sessionKeys: [String], maxItems: Int) async {
+        let keys = self.uniqueKeys(sessionKeys)
+        guard !keys.isEmpty else { return }
+        do {
+            let payload = try await self.requestPreview(keys: keys, maxItems: maxItems)
+            await self.cache(payload: payload, maxItems: maxItems)
+        } catch {
+            if self.isUnknownMethodError(error) { return }
+            let errorDescription = String(describing: error)
+            Self.logger.debug(
+                "Session preview prewarm failed count=\(keys.count, privacy: .public) " +
+                    "error=\(errorDescription, privacy: .public)")
+        }
+    }
+
     static func load(sessionKey: String, maxItems: Int) async -> SessionMenuPreviewSnapshot {
-        if let cached = await SessionPreviewCache.shared.cachedItems(for: sessionKey, maxAge: cacheMaxAgeSeconds) {
-            return self.snapshot(from: cached)
-        }
-
-        let isConnected = await MainActor.run {
-            if case .connected = ControlChannel.shared.state { return true }
-            return false
-        }
-
-        guard isConnected else {
-            if let fallback = await SessionPreviewCache.shared.lastItems(for: sessionKey) {
-                return Self.snapshot(from: fallback)
-            }
-            return SessionMenuPreviewSnapshot(items: [], status: .error("Gateway disconnected"))
+        if let cached = await SessionPreviewCache.shared.cachedSnapshot(
+            for: sessionKey,
+            maxAge: cacheMaxAgeSeconds)
+        {
+            return cached
         }
 
         do {
-            let timeoutMs = Int(self.previewTimeoutSeconds * 1000)
-            let payload = try await SessionPreviewLimiter.shared.withPermit {
-                try await AsyncTimeout.withTimeout(
-                    seconds: self.previewTimeoutSeconds,
-                    onTimeout: { PreviewTimeoutError() },
-                    operation: {
-                        try await GatewayConnection.shared.chatHistory(
-                            sessionKey: sessionKey,
-                            limit: self.previewLimit(for: maxItems),
-                            timeoutMs: timeoutMs)
-                    })
-            }
-            let built = Self.previewItems(from: payload, maxItems: maxItems)
-            await SessionPreviewCache.shared.store(items: built, for: sessionKey)
-            return Self.snapshot(from: built)
+            let snapshot = try await self.fetchSnapshot(sessionKey: sessionKey, maxItems: maxItems)
+            await SessionPreviewCache.shared.store(snapshot: snapshot, for: sessionKey)
+            return snapshot
         } catch is CancellationError {
             return SessionMenuPreviewSnapshot(items: [], status: .loading)
         } catch {
-            let fallback = await SessionPreviewCache.shared.lastItems(for: sessionKey)
-            if let fallback {
-                return Self.snapshot(from: fallback)
+            if let fallback = await SessionPreviewCache.shared.lastSnapshot(for: sessionKey) {
+                return fallback
             }
             let errorDescription = String(describing: error)
             Self.logger.warning(
@@ -272,18 +271,120 @@ enum SessionMenuPreviewLoader {
         }
     }
 
+    private static func fetchSnapshot(sessionKey: String, maxItems: Int) async throws -> SessionMenuPreviewSnapshot {
+        do {
+            let payload = try await self.requestPreview(keys: [sessionKey], maxItems: maxItems)
+            if let entry = payload.previews.first(where: { $0.key == sessionKey }) ?? payload.previews.first {
+                return self.snapshot(from: entry, maxItems: maxItems)
+            }
+            return SessionMenuPreviewSnapshot(items: [], status: .error("Preview unavailable"))
+        } catch {
+            if self.isUnknownMethodError(error) {
+                return try await self.fetchHistorySnapshot(sessionKey: sessionKey, maxItems: maxItems)
+            }
+            throw error
+        }
+    }
+
+    private static func requestPreview(
+        keys: [String],
+        maxItems: Int) async throws -> ClawdbotSessionsPreviewPayload
+    {
+        let boundedItems = self.normalizeMaxItems(maxItems)
+        let timeoutMs = Int(self.previewTimeoutSeconds * 1000)
+        return try await SessionPreviewLimiter.shared.withPermit {
+            try await AsyncTimeout.withTimeout(
+                seconds: self.previewTimeoutSeconds,
+                onTimeout: { PreviewTimeoutError() },
+                operation: {
+                    try await GatewayConnection.shared.sessionsPreview(
+                        keys: keys,
+                        limit: boundedItems,
+                        maxChars: self.previewMaxChars,
+                        timeoutMs: timeoutMs)
+                })
+        }
+    }
+
+    private static func fetchHistorySnapshot(
+        sessionKey: String,
+        maxItems: Int) async throws -> SessionMenuPreviewSnapshot
+    {
+        let timeoutMs = Int(self.previewTimeoutSeconds * 1000)
+        let payload = try await SessionPreviewLimiter.shared.withPermit {
+            try await AsyncTimeout.withTimeout(
+                seconds: self.previewTimeoutSeconds,
+                onTimeout: { PreviewTimeoutError() },
+                operation: {
+                    try await GatewayConnection.shared.chatHistory(
+                        sessionKey: sessionKey,
+                        limit: self.previewLimit(for: maxItems),
+                        timeoutMs: timeoutMs)
+                })
+        }
+        let built = Self.previewItems(from: payload, maxItems: maxItems)
+        return Self.snapshot(from: built)
+    }
+
     private static func snapshot(from items: [SessionPreviewItem]) -> SessionMenuPreviewSnapshot {
         SessionMenuPreviewSnapshot(items: items, status: items.isEmpty ? .empty : .ready)
     }
 
+    private static func snapshot(
+        from entry: ClawdbotSessionPreviewEntry,
+        maxItems: Int) -> SessionMenuPreviewSnapshot
+    {
+        let items = self.previewItems(from: entry, maxItems: maxItems)
+        let normalized = entry.status.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+        switch normalized {
+        case "ok":
+            return SessionMenuPreviewSnapshot(items: items, status: items.isEmpty ? .empty : .ready)
+        case "empty":
+            return SessionMenuPreviewSnapshot(items: items, status: .empty)
+        case "missing":
+            return SessionMenuPreviewSnapshot(items: items, status: .error("Session missing"))
+        default:
+            return SessionMenuPreviewSnapshot(items: items, status: .error("Preview unavailable"))
+        }
+    }
+
+    private static func cache(payload: ClawdbotSessionsPreviewPayload, maxItems: Int) async {
+        for entry in payload.previews {
+            let snapshot = self.snapshot(from: entry, maxItems: maxItems)
+            await SessionPreviewCache.shared.store(snapshot: snapshot, for: entry.key)
+        }
+    }
+
     private static func previewLimit(for maxItems: Int) -> Int {
-        min(max(maxItems * 3, 20), 120)
+        let boundedItems = self.normalizeMaxItems(maxItems)
+        return min(max(boundedItems * 3, 20), 120)
+    }
+
+    private static func normalizeMaxItems(_ maxItems: Int) -> Int {
+        max(1, min(maxItems, 50))
+    }
+
+    private static func previewItems(
+        from entry: ClawdbotSessionPreviewEntry,
+        maxItems: Int) -> [SessionPreviewItem]
+    {
+        let boundedItems = self.normalizeMaxItems(maxItems)
+        let built: [SessionPreviewItem] = entry.items.enumerated().compactMap { index, item in
+            let text = item.text.trimmingCharacters(in: .whitespacesAndNewlines)
+            guard !text.isEmpty else { return nil }
+            let role = self.previewRoleFromRaw(item.role)
+            return SessionPreviewItem(id: "\(entry.key)-\(index)", role: role, text: text)
+        }
+
+        let trimmed = built.suffix(boundedItems)
+        return Array(trimmed.reversed())
     }
 
     private static func previewItems(
         from payload: ClawdbotChatHistoryPayload,
         maxItems: Int) -> [SessionPreviewItem]
     {
+        let boundedItems = self.normalizeMaxItems(maxItems)
         let raw: [ClawdbotKit.AnyCodable] = payload.messages ?? []
         let messages = self.decodeMessages(raw)
         let built = messages.compactMap { message -> SessionPreviewItem? in
@@ -294,7 +395,7 @@ enum SessionMenuPreviewLoader {
             return SessionPreviewItem(id: id, role: role, text: text)
         }
 
-        let trimmed = built.suffix(maxItems)
+        let trimmed = built.suffix(boundedItems)
         return Array(trimmed.reversed())
     }
 
@@ -307,12 +408,16 @@ enum SessionMenuPreviewLoader {
 
     private static func previewRole(_ raw: String, isTool: Bool) -> PreviewRole {
         if isTool { return .tool }
+        return self.previewRoleFromRaw(raw)
+    }
+
+    private static func previewRoleFromRaw(_ raw: String) -> PreviewRole {
         switch raw.lowercased() {
-        case "user": return .user
-        case "assistant": return .assistant
-        case "system": return .system
-        case "tool": return .tool
-        default: return .other
+        case "user": .user
+        case "assistant": .assistant
+        case "system": .system
+        case "tool": .tool
+        default: .other
         }
     }
 
@@ -375,4 +480,16 @@ enum SessionMenuPreviewLoader {
         }
         return result
     }
+
+    private static func uniqueKeys(_ keys: [String]) -> [String] {
+        let trimmed = keys.map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+        return self.dedupePreservingOrder(trimmed.filter { !$0.isEmpty })
+    }
+
+    private static func isUnknownMethodError(_ error: Error) -> Bool {
+        guard let response = error as? GatewayResponseError else { return false }
+        guard response.code == ErrorCode.invalidRequest.rawValue else { return false }
+        let message = response.message.lowercased()
+        return message.contains("unknown method")
+    }
 }

apps/macos/Sources/ClawdbotProtocol/GatewayModels.swift

@@ -925,6 +925,27 @@ public struct SessionsListParams: Codable, Sendable {
     }
 }
 
+public struct SessionsPreviewParams: Codable, Sendable {
+    public let keys: [String]
+    public let limit: Int?
+    public let maxchars: Int?
+
+    public init(
+        keys: [String],
+        limit: Int?,
+        maxchars: Int?
+    ) {
+        self.keys = keys
+        self.limit = limit
+        self.maxchars = maxchars
+    }
+    private enum CodingKeys: String, CodingKey {
+        case keys
+        case limit
+        case maxchars = "maxChars"
+    }
+}
+
 public struct SessionsResolveParams: Codable, Sendable {
     public let key: String?
     public let label: String?

apps/macos/Tests/ClawdbotIPCTests/ExecApprovalsGatewayPrompterTests.swift

@@ -0,0 +1,56 @@
+import Testing
+@testable import Clawdbot
+
+@Suite
+@MainActor
+struct ExecApprovalsGatewayPrompterTests {
+    @Test func sessionMatchPrefersActiveSession() {
+        let matches = ExecApprovalsGatewayPrompter._testShouldPresent(
+            mode: .remote,
+            activeSession: " main ",
+            requestSession: "main",
+            lastInputSeconds: nil)
+        #expect(matches)
+
+        let mismatched = ExecApprovalsGatewayPrompter._testShouldPresent(
+            mode: .remote,
+            activeSession: "other",
+            requestSession: "main",
+            lastInputSeconds: 0)
+        #expect(!mismatched)
+    }
+
+    @Test func sessionFallbackUsesRecentActivity() {
+        let recent = ExecApprovalsGatewayPrompter._testShouldPresent(
+            mode: .remote,
+            activeSession: nil,
+            requestSession: "main",
+            lastInputSeconds: 10,
+            thresholdSeconds: 120)
+        #expect(recent)
+
+        let stale = ExecApprovalsGatewayPrompter._testShouldPresent(
+            mode: .remote,
+            activeSession: nil,
+            requestSession: "main",
+            lastInputSeconds: 200,
+            thresholdSeconds: 120)
+        #expect(!stale)
+    }
+
+    @Test func defaultBehaviorMatchesMode() {
+        let local = ExecApprovalsGatewayPrompter._testShouldPresent(
+            mode: .local,
+            activeSession: nil,
+            requestSession: nil,
+            lastInputSeconds: 400)
+        #expect(local)
+
+        let remote = ExecApprovalsGatewayPrompter._testShouldPresent(
+            mode: .remote,
+            activeSession: nil,
+            requestSession: nil,
+            lastInputSeconds: 400)
+        #expect(!remote)
+    }
+}

apps/macos/Tests/ClawdbotIPCTests/GatewayProcessManagerTests.swift

@@ -1,3 +1,4 @@
+import ClawdbotKit
 import Foundation
 import os
 import Testing

apps/macos/Tests/ClawdbotIPCTests/SessionMenuPreviewTests.swift

@@ -7,20 +7,22 @@ struct SessionMenuPreviewTests {
     @Test func loaderReturnsCachedItems() async {
         await SessionPreviewCache.shared._testReset()
         let items = [SessionPreviewItem(id: "1", role: .user, text: "Hi")]
-        await SessionPreviewCache.shared._testSet(items: items, for: "main")
+        let snapshot = SessionMenuPreviewSnapshot(items: items, status: .ready)
+        await SessionPreviewCache.shared._testSet(snapshot: snapshot, for: "main")
 
-        let snapshot = await SessionMenuPreviewLoader.load(sessionKey: "main", maxItems: 10)
-        #expect(snapshot.status == .ready)
-        #expect(snapshot.items.count == 1)
-        #expect(snapshot.items.first?.text == "Hi")
+        let loaded = await SessionMenuPreviewLoader.load(sessionKey: "main", maxItems: 10)
+        #expect(loaded.status == .ready)
+        #expect(loaded.items.count == 1)
+        #expect(loaded.items.first?.text == "Hi")
     }
 
     @Test func loaderReturnsEmptyWhenCachedEmpty() async {
         await SessionPreviewCache.shared._testReset()
-        await SessionPreviewCache.shared._testSet(items: [], for: "main")
+        let snapshot = SessionMenuPreviewSnapshot(items: [], status: .empty)
+        await SessionPreviewCache.shared._testSet(snapshot: snapshot, for: "main")
 
-        let snapshot = await SessionMenuPreviewLoader.load(sessionKey: "main", maxItems: 10)
-        #expect(snapshot.status == .empty)
-        #expect(snapshot.items.isEmpty)
+        let loaded = await SessionMenuPreviewLoader.load(sessionKey: "main", maxItems: 10)
+        #expect(loaded.status == .empty)
+        #expect(loaded.items.isEmpty)
     }
 }

apps/shared/ClawdbotKit/Sources/ClawdbotChatUI/ChatModels.swift

@@ -235,6 +235,27 @@ public struct ClawdbotChatHistoryPayload: Codable, Sendable {
     public let thinkingLevel: String?
 }
 
+public struct ClawdbotSessionPreviewItem: Codable, Hashable, Sendable {
+    public let role: String
+    public let text: String
+}
+
+public struct ClawdbotSessionPreviewEntry: Codable, Sendable {
+    public let key: String
+    public let status: String
+    public let items: [ClawdbotSessionPreviewItem]
+}
+
+public struct ClawdbotSessionsPreviewPayload: Codable, Sendable {
+    public let ts: Int
+    public let previews: [ClawdbotSessionPreviewEntry]
+
+    public init(ts: Int, previews: [ClawdbotSessionPreviewEntry]) {
+        self.ts = ts
+        self.previews = previews
+    }
+}
+
 public struct ClawdbotChatSendResponse: Codable, Sendable {
     public let runId: String
     public let status: String

apps/shared/ClawdbotKit/Sources/ClawdbotProtocol/GatewayModels.swift

@@ -925,6 +925,27 @@ public struct SessionsListParams: Codable, Sendable {
     }
 }
 
+public struct SessionsPreviewParams: Codable, Sendable {
+    public let keys: [String]
+    public let limit: Int?
+    public let maxchars: Int?
+
+    public init(
+        keys: [String],
+        limit: Int?,
+        maxchars: Int?
+    ) {
+        self.keys = keys
+        self.limit = limit
+        self.maxchars = maxchars
+    }
+    private enum CodingKeys: String, CodingKey {
+        case keys
+        case limit
+        case maxchars = "maxChars"
+    }
+}
+
 public struct SessionsResolveParams: Codable, Sendable {
     public let key: String?
     public let label: String?

dist/control-ui/assets/index-BPDeGGxb.css

@@ -0,0 +1 @@
+@import"https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=Unbounded:wght@400;500;600&family=Work+Sans:wght@400;500;600;700&display=swap";:root{--bg: #0a0f14;--bg-accent: #111826;--bg-grad-1: #162031;--bg-grad-2: #1f2a22;--bg-overlay: rgba(255, 255, 255, .05);--bg-glow: rgba(245, 159, 74, .12);--panel: rgba(14, 20, 30, .88);--panel-strong: rgba(18, 26, 38, .96);--chrome: rgba(9, 14, 20, .72);--chrome-strong: rgba(9, 14, 20, .86);--text: rgba(244, 246, 251, .96);--chat-text: rgba(231, 237, 244, .92);--muted: rgba(156, 169, 189, .72);--border: rgba(255, 255, 255, .09);--border-strong: rgba(255, 255, 255, .16);--accent: #f59f4a;--accent-2: #34c7b7;--ok: #2bd97f;--warn: #f2c94c;--danger: #ff6b6b;--focus: rgba(245, 159, 74, .35);--grid-line: rgba(255, 255, 255, .04);--theme-switch-x: 50%;--theme-switch-y: 50%;--mono: "IBM Plex Mono", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;--font-body: "Work Sans", system-ui, sans-serif;--font-display: "Unbounded", "Times New Roman", serif;color-scheme:dark}:root[data-theme=light]{--bg: #f5f1ea;--bg-accent: #ffffff;--bg-grad-1: #f1e6d6;--bg-grad-2: #e5eef4;--bg-overlay: rgba(28, 32, 46, .05);--bg-glow: rgba(52, 199, 183, .14);--panel: rgba(255, 255, 255, .9);--panel-strong: rgba(255, 255, 255, .97);--chrome: rgba(255, 255, 255, .75);--chrome-strong: rgba(255, 255, 255, .88);--text: rgba(27, 36, 50, .98);--chat-text: rgba(36, 48, 66, .9);--muted: rgba(80, 94, 114, .7);--border: rgba(18, 24, 40, .12);--border-strong: rgba(18, 24, 40, .2);--accent: #e28a3f;--accent-2: #1ba99d;--ok: #1aa86c;--warn: #b3771c;--danger: #d44848;--focus: rgba(226, 138, 63, .35);--grid-line: rgba(18, 24, 40, .06);color-scheme:light}*{box-sizing:border-box}html,body{height:100%}body{margin:0;font:15px/1.5 var(--font-body);background:radial-gradient(1200px 900px at 15% -10%,var(--bg-grad-1) 0%,transparent 55%) fixed,radial-gradient(900px 700px at 80% 10%,var(--bg-grad-2) 0%,transparent 60%) fixed,linear-gradient(160deg,var(--bg) 0%,var(--bg-accent) 100%) fixed;color:var(--text)}body:before{content:"";position:fixed;inset:0;background:linear-gradient(140deg,var(--bg-overlay) 0%,rgba(255,255,255,0) 40%),radial-gradient(620px 420px at 75% 75%,var(--bg-glow),transparent 60%);pointer-events:none;z-index:0}@keyframes theme-circle-transition{0%{clip-path:circle(0% at var(--theme-switch-x, 50%) var(--theme-switch-y, 50%))}to{clip-path:circle(150% at var(--theme-switch-x, 50%) var(--theme-switch-y, 50%))}}html.theme-transition{view-transition-name:theme}html.theme-transition::view-transition-old(theme){mix-blend-mode:normal;animation:none;z-index:1}html.theme-transition::view-transition-new(theme){mix-blend-mode:normal;z-index:2;animation:theme-circle-transition .45s ease-out forwards}@media(prefers-reduced-motion:reduce){html.theme-transition::view-transition-old(theme),html.theme-transition::view-transition-new(theme){animation:none!important}}clawdbot-app{display:block;position:relative;z-index:1;min-height:100vh}a{color:inherit}button,input,textarea,select{font:inherit;color:inherit}@keyframes rise{0%{opacity:0;transform:translateY(6px)}to{opacity:1;transform:translateY(0)}}@keyframes dashboard-enter{0%{opacity:0;transform:translateY(12px)}to{opacity:1;transform:translateY(0)}}.shell{--shell-pad: 16px;--shell-gap: 16px;--shell-nav-width: 220px;--shell-topbar-height: 56px;--shell-focus-duration: .22s;--shell-focus-ease: cubic-bezier(.2, .85, .25, 1);min-height:100vh;display:grid;grid-template-columns:var(--shell-nav-width) minmax(0,1fr);grid-template-rows:var(--shell-topbar-height) 1fr;grid-template-areas:"topbar topbar" "nav content";gap:0;animation:dashboard-enter .6s ease-out;transition:grid-template-columns var(--shell-focus-duration) var(--shell-focus-ease)}.shell--chat{min-height:100vh;height:100vh;overflow:hidden}@supports (height: 100dvh){.shell--chat{height:100dvh}}.shell--nav-collapsed,.shell--chat-focus{grid-template-columns:0px minmax(0,1fr)}.shell--onboarding{grid-template-rows:0 1fr}.shell--onboarding .topbar{display:none}.shell--onboarding .content{padding-top:0}.shell--chat-focus .content{padding-top:0;gap:0}.topbar{grid-area:topbar;position:sticky;top:0;z-index:40;display:flex;justify-content:space-between;align-items:center;gap:16px;padding:0 20px;height:var(--shell-topbar-height);border-bottom:1px solid var(--border);background:var(--panel);-webkit-backdrop-filter:blur(18px);backdrop-filter:blur(18px)}.topbar-left{display:flex;align-items:center;gap:12px}.topbar .nav-collapse-toggle{width:44px;height:44px;margin-bottom:0}.topbar .nav-collapse-toggle__icon{font-size:22px}.brand{display:flex;flex-direction:column;gap:2px}.brand-title{font-family:var(--font-display);font-size:16px;letter-spacing:1px;text-transform:uppercase;font-weight:600;line-height:1.1}.brand-sub{font-size:10px;color:var(--muted);letter-spacing:.8px;text-transform:uppercase;line-height:1}.topbar-status{display:flex;align-items:center;gap:8px}.toLine truncated

dist/control-ui/assets/index-bYQnHP3a.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-bYQnHP3a.js","sources":["../../../node_modules/.pnpm/@lit+reactive-element@2.1.2/node_modules/@lit/reactive-element/css-tag.js","../../../node_modules/.pnpm/@lit+reactive-element@2.1.2/node_modules/@lit/reactive-element/reactive-element.js","../../../node_modules/.pnpm/lit-html@3.3.2/node_modules/lit-html/lit-html.js","../../../node_modules/.pnpm/lit-element@4.2.2/node_modules/lit-element/lit-element.js","../../../node_modules/.pnpm/@lit+reactive-element@2.1.2/node_modules/@lit/reactive-element/decorators/custom-element.js","../../../node_modules/.pnpm/@lit+reactive-element@2.1.2/node_modules/@lit/reactive-element/decorators/property.js","../../../node_modules/.pnpm/@lit+reactive-element@2.1.2/node_modules/@lit/reactive-element/decorators/state.js","../../../ui/src/ui/assistant-identity.ts","../../../ui/src/ui/storage.ts","../../../src/sessions/session-key-utils.ts","../../../ui/src/ui/navigation.ts","../../../ui/src/ui/format.ts","../../../ui/src/ui/chat/message-extract.ts","../../../ui/src/ui/uuid.ts","../../../ui/src/ui/controllers/chat.ts","../../../ui/src/ui/controllers/sessions.ts","../../../ui/src/ui/app-tool-stream.ts","../../../ui/src/ui/app-scroll.ts","../../../ui/src/ui/controllers/config/form-utils.ts","../../../ui/src/ui/controllers/config.ts","../../../ui/src/ui/controllers/cron.ts","../../../ui/src/ui/controllers/channels.ts","../../../ui/src/ui/controllers/debug.ts","../../../ui/src/ui/controllers/logs.ts","../../../node_modules/.pnpm/@noble+ed25519@3.0.0/node_modules/@noble/ed25519/index.js","../../../ui/src/ui/device-identity.ts","../../../ui/src/ui/device-auth.ts","../../../ui/src/ui/controllers/devices.ts","../../../ui/src/ui/controllers/nodes.ts","../../../ui/src/ui/controllers/exec-approvals.ts","../../../ui/src/ui/controllers/presence.ts","../../../ui/src/ui/controllers/skills.ts","../../../ui/src/ui/theme.ts","../../../ui/src/ui/theme-transition.ts","../../../ui/src/ui/app-polling.ts","../../../ui/src/ui/app-settings.ts","../../../ui/src/ui/app-chat.ts","../../../node_modules/.pnpm/lit-html@3.3.2/node_modules/lit-html/directive.js","../../../node_modules/.pnpm/lit-html@3.3.2/node_modules/lit-html/directive-helpers.js","../../../node_modules/.pnpm/lit-html@3.3.2/node_modules/lit-html/directives/repeat.js","../../../ui/src/ui/chat/message-normalizer.ts","../../../node_modules/.pnpm/lit-html@3.3.2/node_modules/lit-html/directives/unsafe-html.js","../../../node_modules/.pnpm/dompurify@3.3.1/node_modules/dompurify/dist/purify.es.mjs","../../../node_modules/.pnpm/marked@17.0.1/node_modules/marked/lib/marked.esm.js","../../../ui/src/ui/markdown.ts","../../../ui/src/ui/icons.ts","../../../ui/src/ui/chat/copy-as-markdown.ts","../../../ui/src/ui/tool-display.ts","../../../ui/src/ui/chat/constants.ts","../../../ui/src/ui/chat/tool-helpers.ts","../../../ui/src/ui/chat/tool-cards.ts","../../../ui/src/ui/chat/grouped-render.ts","../../../ui/src/ui/views/markdown-sidebar.ts","../../../ui/src/ui/components/resizable-divider.ts","../../../ui/src/ui/views/chat.ts","../../../ui/src/ui/views/config-form.shared.ts","../../../ui/src/ui/views/config-form.node.ts","../../../ui/src/ui/views/config-form.render.ts","../../../ui/src/ui/views/config-form.analyze.ts","../../../ui/src/ui/views/config.ts","../../../ui/src/ui/views/channels.shared.ts","../../../ui/src/ui/views/channels.config.ts","../../../ui/src/ui/views/channels.discord.ts","../../../ui/src/ui/views/channels.imessage.ts","../../../ui/src/ui/views/channels.nostr-profile-form.ts","../../../ui/src/ui/views/channels.nostr.ts","../../../ui/src/ui/views/channels.signal.ts","../../../ui/src/ui/views/channels.slack.ts","../../../ui/src/ui/views/channels.telegram.ts","../../../ui/src/ui/views/channels.whatsapp.ts","../../../ui/src/ui/views/channels.ts","../../../ui/src/ui/presenter.ts","../../../ui/src/ui/views/cron.ts","../../../ui/src/ui/views/debug.ts","../../../ui/src/ui/views/instances.ts","../../../ui/src/ui/views/logs.ts","../../../ui/src/ui/views/nodes.ts","../../../ui/src/ui/views/overview.ts","../../../ui/src/ui/views/sessions.ts","../../../ui/src/ui/views/exec-approval.ts","../../../ui/src/ui/views/skills.ts","../../../ui/src/ui/app-render.helpers.ts","../../../ui/src/ui/app-render.ts","../../../ui/src/ui/app-defaults.ts","../../../ui/src/ui/controllers/agents.ts","../../../src/gateway/protocol/client-info.ts","../../../src/gateway/device-auth.ts","../../../ui/src/ui/gateway.ts","../../../ui/src/ui/controllers/exec-approval.ts","../../../ui/src/ui/controllers/assistant-identity.ts","../../../ui/src/ui/app-gateway.ts","../../../ui/src/ui/app-lifecycle.ts","../../../ui/src/ui/app-channels.ts","../../../ui/src/ui/app.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2019 Google LLC\n * SPDX-License-Identifier: BSD-3-Clause\n */\nconst t=globalThis,e=t.ShadowRoot&&(void 0===t.ShadyCSS||t.ShadyCSS.nativeShadow)&&\"adoptedStyleSheets\"in Document.prototype&&\"replace\"in CSSStyleSheet.prototype,s=Symbol(),o=new WeakMapLine truncated

dist/control-ui/index.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Clawdbot Control</title>
+    <meta name="color-scheme" content="dark light" />
+    <link rel="icon" href="./favicon.ico" sizes="any" />
+    <script type="module" crossorigin src="./assets/index-bYQnHP3a.js"></script>
+    <link rel="stylesheet" crossorigin href="./assets/index-BPDeGGxb.css">
+  </head>
+  <body>
+    <clawdbot-app></clawdbot-app>
+  </body>
+</html>

docs/concepts/architecture.md

@@ -5,7 +5,7 @@ read_when:
 ---
 # Gateway architecture
 
-Last updated: 2026-01-19
+Last updated: 2026-01-22
 
 ## Overview
 
@@ -34,7 +34,8 @@ Last updated: 2026-01-19
 
 ### Nodes (macOS / iOS / Android / headless)
 - Connect to the **same WS server** with `role: node`.
-- Pair with the Gateway to receive a token.
+- Provide a device identity in `connect`; pairing is **device‑based** (role `node`) and
+  approval lives in the device pairing store.
 - Expose commands like `canvas.*`, `camera.*`, `screen.record`, `location.get`.
 
 Protocol details:

docs/concepts/presence.md

@@ -52,10 +52,10 @@ Instances list, `client.mode === "cli"` is **not** turned into a presence entry.
 Clients can send richer periodic beacons via the `system-event` method. The mac
 app uses this to report host name, IP, and `lastInputSeconds`.
 
-### 4) Node bridge beacons
+### 4) Node connects (role: node)
 
-When a node bridge connection authenticates, the Gateway emits a presence entry
-for that node and refreshes it periodically so it doesn’t expire.
+When a node connects over the Gateway WebSocket with `role: node`, the Gateway
+upserts a presence entry for that node (same flow as other WS clients).
 
 ## Merge + dedupe rules (why `instanceId` matters)
 

docs/gateway/pairing.md

@@ -11,6 +11,10 @@ In Gateway-owned pairing, the **Gateway** is the source of truth for which nodes
 are allowed to join. UIs (macOS app, future clients) are just frontends that
 approve or reject pending requests.
 
+**Important:** WS nodes use **device pairing** (role `node`) during `connect`.
+`node.pair.*` is a separate pairing store and does **not** gate the WS handshake.
+Only clients that explicitly call `node.pair.*` use this flow.
+
 ## Concepts
 
 - **Pending request**: a node asked to join; requires approval.

docs/nodes/index.md

@@ -8,9 +8,11 @@ read_when:
 
 # Nodes
 
-A **node** is a companion device (iOS/Android today) that connects to the Gateway over the **Bridge** and exposes a command surface (e.g. `canvas.*`, `camera.*`, `system.*`) via `node.invoke`. Bridge protocol details: [Bridge protocol](/gateway/bridge-protocol).
+A **node** is a companion device (macOS/iOS/Android/headless) that connects to the Gateway **WebSocket** (same port as operators) with `role: "node"` and exposes a command surface (e.g. `canvas.*`, `camera.*`, `system.*`) via `node.invoke`. Protocol details: [Gateway protocol](/gateway/protocol).
 
-macOS can also run in **node mode**: the menubar app connects to the Gateway’s bridge and exposes its local canvas/camera commands as a node (so `clawdbot nodes …` works against this Mac).
+Legacy transport: [Bridge protocol](/gateway/bridge-protocol) (TCP JSONL; for older node clients only).
+
+macOS can also run in **node mode**: the menubar app connects to the Gateway’s WS server and exposes its local canvas/camera commands as a node (so `clawdbot nodes …` works against this Mac).
 
 Notes:
 - Nodes are **peripherals**, not gateways. They don’t run the gateway service.
@@ -18,21 +20,23 @@ Notes:
 
 ## Pairing + status
 
-Pairing is gateway-owned and approval-based. See [Gateway pairing](/gateway/pairing) for the full flow.
+**WS nodes use device pairing.** Nodes present a device identity during `connect`; the Gateway
+creates a device pairing request for `role: node`. Approve via the devices CLI (or UI).
 
 Quick CLI:
 
 ```bash
-clawdbot nodes pending
-clawdbot nodes approve <requestId>
-clawdbot nodes reject <requestId>
+clawdbot devices list
+clawdbot devices approve <requestId>
+clawdbot devices reject <requestId>
 clawdbot nodes status
 clawdbot nodes describe --node <idOrNameOrIp>
-clawdbot nodes rename --node <idOrNameOrIp> --name "Kitchen iPad"
 ```
 
 Notes:
-- `nodes rename` stores a display name override in the gateway pairing store.
+- `nodes status` marks a node as **paired** when its device pairing role includes `node`.
+- `node.pair.*` (CLI: `clawdbot nodes pending/approve/reject`) is a separate gateway-owned
+  node pairing store; it does **not** gate the WS `connect` handshake.
 
 ## Remote node host (system.run)
 
@@ -275,7 +279,7 @@ Nodes may include a `permissions` map in `node.list` / `node.describe`, keyed by
 ## Headless node host (cross-platform)
 
 Clawdbot can run a **headless node host** (no UI) that connects to the Gateway
-bridge and exposes `system.run` / `system.which`. This is useful on Linux/Windows
+WebSocket and exposes `system.run` / `system.which`. This is useful on Linux/Windows
 or for running a minimal node alongside a server.
 
 Start it:
@@ -292,9 +296,9 @@ Notes:
 - On macOS, the headless node host prefers the companion app exec host when reachable and falls
   back to local execution if the app is unavailable. Set `CLAWDBOT_NODE_EXEC_HOST=app` to require
   the app, or `CLAWDBOT_NODE_EXEC_FALLBACK=0` to disable fallback.
-- Add `--tls` / `--tls-fingerprint` when the bridge requires TLS.
+- Add `--tls` / `--tls-fingerprint` when the Gateway WS uses TLS.
 
 ## Mac node mode
 
-- The macOS menubar app connects to the Gateway bridge as a node (so `clawdbot nodes …` works against this Mac).
-- In remote mode, the app opens an SSH tunnel for the bridge port and connects to `localhost`.
+- The macOS menubar app connects to the Gateway WS server as a node (so `clawdbot nodes …` works against this Mac).
+- In remote mode, the app opens an SSH tunnel for the Gateway port and connects to `localhost`.

docs/reference/templates/BOOTSTRAP.md

@@ -7,6 +7,8 @@ read_when:
 
 *You just woke up. Time to figure out who you are.*
 
+There is no memory yet. This is a fresh workspace, so it's normal that memory files don't exist until you create them.
+
 ## The Conversation
 
 Don't interrogate. Don't be robotic. Just... talk.

docs/start/faq.md

@@ -1067,6 +1067,17 @@ You can also force a specific auth profile for the provider (per session):
 Tip: `/model status` shows which agent is active, which `auth-profiles.json` file is being used, and which auth profile will be tried next.
 It also shows the configured provider endpoint (`baseUrl`) and API mode (`api`) when available.
 
+### How do I unpin a profile I set with `@profile`?
+
+Re-run `/model` **without** the `@profile` suffix:
+
+```
+/model anthropic/claude-opus-4-5
+```
+
+If you want to return to the default, pick it from `/model` (or send `/model <default provider/model>`).
+Use `/model status` to confirm which auth profile is active.
+
 ### Why do I see “Model … is not allowed” and then no reply?
 
 If `agents.defaults.models` is set, it becomes the **allowlist** for `/model` and any

docs/start/pairing.md

@@ -45,27 +45,29 @@ Stored under `~/.clawdbot/credentials/`:
 Treat these as sensitive (they gate access to your assistant).
 
 
-## 2) Node pairing (iOS/Android nodes joining the gateway)
+## 2) Node device pairing (iOS/Android/macOS/headless nodes)
 
-Nodes (iOS/Android, future hardware, etc.) connect to the Gateway and request to join.
-The Gateway keeps an authoritative allowlist; new nodes require explicit approve/reject.
+Nodes connect to the Gateway as **devices** with `role: node`. The Gateway
+creates a device pairing request that must be approved.
 
-### Approve a node
+### Approve a node device
 
 ```bash
-clawdbot nodes pending
-clawdbot nodes approve <requestId>
+clawdbot devices list
+clawdbot devices approve <requestId>
+clawdbot devices reject <requestId>
 ```
 
 ### Where the state lives
 
-Stored under `~/.clawdbot/nodes/`:
+Stored under `~/.clawdbot/devices/`:
 - `pending.json` (short-lived; pending requests expire)
-- `paired.json` (paired nodes + tokens)
+- `paired.json` (paired devices + tokens)
 
-### Details
+### Notes
 
-Full protocol + design notes: [Gateway pairing](/gateway/pairing)
+- The legacy `node.pair.*` API (CLI: `clawdbot nodes pending/approve`) is a
+  separate gateway-owned pairing store. WS nodes still require device pairing.
 
 
 ## Related docs

extensions/bluebubbles/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/bluebubbles",
-  "version": "2026.1.21",
+  "version": "2026.1.22",
   "type": "module",
   "description": "Clawdbot BlueBubbles channel plugin",
   "clawdbot": {

extensions/bluebubbles/src/monitor.test.ts

@@ -1563,6 +1563,100 @@ describe("BlueBubbles webhook monitor", () => {
         expect.any(Object),
       );
     });
+
+    it("stops typing on idle", async () => {
+      const { sendBlueBubblesTyping } = await import("./chat.js");
+      vi.mocked(sendBlueBubblesTyping).mockClear();
+
+      const account = createMockAccount();
+      const config: ClawdbotConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const payload = {
+        type: "new-message",
+        data: {
+          text: "hello",
+          handle: { address: "+15551234567" },
+          isGroup: false,
+          isFromMe: false,
+          guid: "msg-1",
+          chatGuid: "iMessage;-;+15551234567",
+          date: Date.now(),
+        },
+      };
+
+      mockDispatchReplyWithBufferedBlockDispatcher.mockImplementationOnce(async (params) => {
+        await params.dispatcherOptions.onReplyStart?.();
+        await params.dispatcherOptions.deliver({ text: "replying now" }, { kind: "final" });
+        await params.dispatcherOptions.onIdle?.();
+      });
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
+      const res = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(req, res);
+      await new Promise((resolve) => setTimeout(resolve, 50));
+
+      expect(sendBlueBubblesTyping).toHaveBeenCalledWith(
+        expect.any(String),
+        false,
+        expect.any(Object),
+      );
+    });
+
+    it("stops typing when no reply is sent", async () => {
+      const { sendBlueBubblesTyping } = await import("./chat.js");
+      vi.mocked(sendBlueBubblesTyping).mockClear();
+
+      const account = createMockAccount();
+      const config: ClawdbotConfig = {};
+      const core = createMockRuntime();
+      setBlueBubblesRuntime(core);
+
+      unregister = registerBlueBubblesWebhookTarget({
+        account,
+        config,
+        runtime: { log: vi.fn(), error: vi.fn() },
+        core,
+        path: "/bluebubbles-webhook",
+      });
+
+      const payload = {
+        type: "new-message",
+        data: {
+          text: "hello",
+          handle: { address: "+15551234567" },
+          isGroup: false,
+          isFromMe: false,
+          guid: "msg-1",
+          chatGuid: "iMessage;-;+15551234567",
+          date: Date.now(),
+        },
+      };
+
+      mockDispatchReplyWithBufferedBlockDispatcher.mockImplementationOnce(async () => undefined);
+
+      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
+      const res = createMockResponse();
+
+      await handleBlueBubblesWebhookRequest(req, res);
+      await new Promise((resolve) => setTimeout(resolve, 50));
+
+      expect(sendBlueBubblesTyping).toHaveBeenCalledWith(
+        expect.any(String),
+        false,
+        expect.any(Object),
+      );
+    });
   });
 
   describe("outbound message ids", () => {

extensions/bluebubbles/src/monitor.ts

@@ -1713,8 +1713,17 @@ async function processMessage(
             runtime.error?.(`[bluebubbles] typing start failed: ${String(err)}`);
           }
         },
-        onIdle: () => {
-          // BlueBubbles typing stop (DELETE) does not clear bubbles reliably; wait for timeout.
+        onIdle: async () => {
+          if (!chatGuidForActions) return;
+          if (!baseUrl || !password) return;
+          try {
+            await sendBlueBubblesTyping(chatGuidForActions, false, {
+              cfg: config,
+              accountId: account.accountId,
+            });
+          } catch (err) {
+            logVerbose(core, runtime, `typing stop failed: ${String(err)}`);
+          }
         },
         onError: (err, info) => {
           runtime.error?.(`BlueBubbles ${info.kind} reply failed: ${String(err)}`);
@@ -1754,7 +1763,13 @@ async function processMessage(
       });
     }
     if (chatGuidForActions && baseUrl && password && !sentMessage) {
-      // BlueBubbles typing stop (DELETE) does not clear bubbles reliably; wait for timeout.
+      // Stop typing indicator when no message was sent (e.g., NO_REPLY)
+      sendBlueBubblesTyping(chatGuidForActions, false, {
+        cfg: config,
+        accountId: account.accountId,
+      }).catch((err) => {
+        logVerbose(core, runtime, `typing stop (no reply) failed: ${String(err)}`);
+      });
     }
   }
 }

extensions/copilot-proxy/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/copilot-proxy",
-  "version": "2026.1.21",
+  "version": "2026.1.22",
   "type": "module",
   "description": "Clawdbot Copilot Proxy provider plugin",
   "clawdbot": {

extensions/diagnostics-otel/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/diagnostics-otel",
-  "version": "2026.1.21",
+  "version": "2026.1.22",
   "type": "module",
   "description": "Clawdbot diagnostics OpenTelemetry exporter",
   "clawdbot": {

extensions/discord/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/discord",
-  "version": "2026.1.21",
+  "version": "2026.1.22",
   "type": "module",
   "description": "Clawdbot Discord channel plugin",
   "clawdbot": {

extensions/google-antigravity-auth/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/google-antigravity-auth",
-  "version": "2026.1.21",
+  "version": "2026.1.22",
   "type": "module",
   "description": "Clawdbot Google Antigravity OAuth provider plugin",
   "clawdbot": {

extensions/google-gemini-cli-auth/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/google-gemini-cli-auth",
-  "version": "2026.1.21",
+  "version": "2026.1.22",
   "type": "module",
   "description": "Clawdbot Gemini CLI OAuth provider plugin",
   "clawdbot": {

extensions/imessage/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/imessage",
-  "version": "2026.1.21",
+  "version": "2026.1.22",
   "type": "module",
   "description": "Clawdbot iMessage channel plugin",
   "clawdbot": {

extensions/lobster/package.json

@@ -1,9 +1,11 @@
 {
   "name": "@clawdbot/lobster",
-  "version": "2026.1.17-1",
+  "version": "2026.1.22",
   "type": "module",
   "description": "Lobster workflow tool plugin (typed pipelines + resumable approvals)",
   "clawdbot": {
-    "extensions": ["./index.ts"]
+    "extensions": [
+      "./index.ts"
+    ]
   }
 }

extensions/matrix/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 2026.1.22
+
+### Changes
+- Version alignment with core Clawdbot release numbers.
+
 ## 2026.1.21
 
 ### Changes

extensions/matrix/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/matrix",
-  "version": "2026.1.21",
+  "version": "2026.1.22",
   "type": "module",
   "description": "Clawdbot Matrix channel plugin",
   "clawdbot": {

extensions/memory-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/memory-core",
-  "version": "2026.1.21",
+  "version": "2026.1.22",
   "type": "module",
   "description": "Clawdbot core memory search plugin",
   "clawdbot": {

extensions/memory-lancedb/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/memory-lancedb",
-  "version": "2026.1.21",
+  "version": "2026.1.22",
   "type": "module",
   "description": "Clawdbot LanceDB-backed long-term memory plugin with auto-recall/capture",
   "dependencies": {

extensions/msteams/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 2026.1.22
+
+### Changes
+- Version alignment with core Clawdbot release numbers.
+
 ## 2026.1.21
 
 ### Changes

extensions/msteams/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/msteams",
-  "version": "2026.1.21",
+  "version": "2026.1.22",
   "type": "module",
   "description": "Clawdbot Microsoft Teams channel plugin",
   "clawdbot": {

extensions/nextcloud-talk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/nextcloud-talk",
-  "version": "2026.1.21",
+  "version": "2026.1.22",
   "type": "module",
   "description": "Clawdbot Nextcloud Talk channel plugin",
   "clawdbot": {

extensions/nostr/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 2026.1.22
+
+### Changes
+- Version alignment with core Clawdbot release numbers.
+
 ## 2026.1.21
 
 ### Changes

extensions/nostr/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/nostr",
-  "version": "2026.1.21",
+  "version": "2026.1.22",
   "type": "module",
   "description": "Clawdbot Nostr channel plugin for NIP-04 encrypted DMs",
   "clawdbot": {

extensions/signal/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/signal",
-  "version": "2026.1.21",
+  "version": "2026.1.22",
   "type": "module",
   "description": "Clawdbot Signal channel plugin",
   "clawdbot": {

extensions/slack/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/slack",
-  "version": "2026.1.21",
+  "version": "2026.1.22",
   "type": "module",
   "description": "Clawdbot Slack channel plugin",
   "clawdbot": {

extensions/telegram/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/telegram",
-  "version": "2026.1.21",
+  "version": "2026.1.22",
   "type": "module",
   "description": "Clawdbot Telegram channel plugin",
   "clawdbot": {

extensions/voice-call/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 2026.1.22
+
+### Changes
+- Version alignment with core Clawdbot release numbers.
+
 ## 2026.1.21
 
 ### Changes

extensions/voice-call/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/voice-call",
-  "version": "2026.1.21",
+  "version": "2026.1.22",
   "type": "module",
   "description": "Clawdbot voice-call plugin",
   "dependencies": {

extensions/whatsapp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/whatsapp",
-  "version": "2026.1.21",
+  "version": "2026.1.22",
   "type": "module",
   "description": "Clawdbot WhatsApp channel plugin",
   "clawdbot": {

extensions/zalo/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 2026.1.22
+
+### Changes
+- Version alignment with core Clawdbot release numbers.
+
 ## 2026.1.21
 
 ### Changes

extensions/zalo/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/zalo",
-  "version": "2026.1.21",
+  "version": "2026.1.22",
   "type": "module",
   "description": "Clawdbot Zalo channel plugin",
   "clawdbot": {

extensions/zalouser/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 2026.1.22
+
+### Changes
+- Version alignment with core Clawdbot release numbers.
+
 ## 2026.1.21
 
 ### Changes

extensions/zalouser/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/zalouser",
-  "version": "2026.1.21",
+  "version": "2026.1.22",
   "type": "module",
   "description": "Clawdbot Zalo Personal Account plugin via zca-cli",
   "dependencies": {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawdbot",
-  "version": "2026.1.21",
+  "version": "2026.1.22",
   "description": "WhatsApp gateway CLI (Baileys web) with Pi RPC agent",
   "type": "module",
   "main": "dist/index.js",
@@ -73,7 +73,7 @@
   "scripts": {
     "dev": "node scripts/run-node.mjs",
     "postinstall": "node scripts/postinstall.js",
-    "prepack": "pnpm build",
+    "prepack": "pnpm build && pnpm ui:build",
     "docs:list": "node scripts/docs-list.js",
     "docs:bin": "node scripts/build-docs-list.mjs",
     "docs:dev": "cd docs && mint dev",

skills/gog/SKILL.md

@@ -11,7 +11,7 @@ Use `gog` for Gmail/Calendar/Drive/Contacts/Sheets/Docs. Requires OAuth setup.
 
 Setup (once)
 - `gog auth credentials /path/to/client_secret.json`
-- `gog auth add you@gmail.com --services gmail,calendar,drive,contacts,sheets,docs`
+- `gog auth add you@gmail.com --services gmail,calendar,drive,contacts,docs,sheets`
 - `gog auth list`
 
 Common commands

src/agents/bash-tools.exec.approval-id.test.ts

@@ -80,58 +80,44 @@ describe("exec approvals", () => {
     if (process.platform !== "win32") {
       await fs.chmod(exePath, 0o755);
     }
-    const prevPath = process.env.PATH;
-    const prevPathExt = process.env.PATHEXT;
-    process.env.PATH = binDir;
-    if (process.platform === "win32") {
-      process.env.PATHEXT = ".CMD";
-    }
-
-    try {
-      const approvalsFile = {
-        version: 1,
-        defaults: { security: "allowlist", ask: "on-miss", askFallback: "deny" },
-        agents: {
-          main: {
-            allowlist: [{ pattern: exePath }],
-          },
+    const approvalsFile = {
+      version: 1,
+      defaults: { security: "allowlist", ask: "on-miss", askFallback: "deny" },
+      agents: {
+        main: {
+          allowlist: [{ pattern: exePath }],
         },
-      };
+      },
+    };
 
-      const calls: string[] = [];
-      vi.mocked(callGatewayTool).mockImplementation(async (method) => {
-        calls.push(method);
-        if (method === "exec.approvals.node.get") {
-          return { file: approvalsFile };
-        }
-        if (method === "node.invoke") {
-          return { payload: { success: true, stdout: "ok" } };
-        }
-        if (method === "exec.approval.request") {
-          return { decision: "allow-once" };
-        }
-        return { ok: true };
-      });
-
-      const { createExecTool } = await import("./bash-tools.exec.js");
-      const tool = createExecTool({
-        host: "node",
-        ask: "on-miss",
-        approvalRunningNoticeMs: 0,
-      });
-
-      const result = await tool.execute("call2", { command: `${exeName} --help` });
-      expect(result.details.status).toBe("completed");
-      expect(calls).toContain("exec.approvals.node.get");
-      expect(calls).toContain("node.invoke");
-      expect(calls).not.toContain("exec.approval.request");
-    } finally {
-      process.env.PATH = prevPath;
-      if (prevPathExt === undefined) {
-        delete process.env.PATHEXT;
-      } else {
-        process.env.PATHEXT = prevPathExt;
+    const calls: string[] = [];
+    vi.mocked(callGatewayTool).mockImplementation(async (method) => {
+      calls.push(method);
+      if (method === "exec.approvals.node.get") {
+        return { file: approvalsFile };
       }
-    }
+      if (method === "node.invoke") {
+        return { payload: { success: true, stdout: "ok" } };
+      }
+      if (method === "exec.approval.request") {
+        return { decision: "allow-once" };
+      }
+      return { ok: true };
+    });
+
+    const { createExecTool } = await import("./bash-tools.exec.js");
+    const tool = createExecTool({
+      host: "node",
+      ask: "on-miss",
+      approvalRunningNoticeMs: 0,
+    });
+
+    const result = await tool.execute("call2", {
+      command: `"${exePath}" --help`,
+    });
+    expect(result.details.status).toBe("completed");
+    expect(calls).toContain("exec.approvals.node.get");
+    expect(calls).toContain("node.invoke");
+    expect(calls).not.toContain("exec.approval.request");
   });
 });

src/agents/pi-embedded-helpers.formatassistanterrortext.test.ts

@@ -43,8 +43,6 @@ describe("formatAssistantErrorText", () => {
     const msg = makeAssistantError(
       '{"type":"error","error":{"message":"Something exploded","type":"server_error"}}',
     );
-    expect(formatAssistantErrorText(msg)).toBe(
-      "The AI service returned an error. Please try again.",
-    );
+    expect(formatAssistantErrorText(msg)).toBe("LLM error server_error: Something exploded");
   });
 });

src/agents/pi-embedded-helpers.formatrawassistanterrorforui.test.ts

@@ -17,4 +17,10 @@ describe("formatRawAssistantErrorForUi", () => {
   it("renders a generic unknown error message when raw is empty", () => {
     expect(formatRawAssistantErrorForUi("")).toContain("unknown error");
   });
+
+  it("formats plain HTTP status lines", () => {
+    expect(formatRawAssistantErrorForUi("500 Internal Server Error")).toBe(
+      "HTTP 500: Internal Server Error",
+    );
+  });
 });

src/agents/pi-embedded-helpers.sanitizeuserfacingtext.test.ts

@@ -19,12 +19,12 @@ describe("sanitizeUserFacingText", () => {
 
   it("sanitizes HTTP status errors with error hints", () => {
     expect(sanitizeUserFacingText("500 Internal Server Error")).toBe(
-      "The AI service returned an error. Please try again.",
+      "HTTP 500: Internal Server Error",
     );
   });
 
   it("sanitizes raw API error payloads", () => {
     const raw = '{"type":"error","error":{"message":"Something exploded","type":"server_error"}}';
-    expect(sanitizeUserFacingText(raw)).toBe("The AI service returned an error. Please try again.");
+    expect(sanitizeUserFacingText(raw)).toBe("LLM error server_error: Something exploded");
   });
 });

src/agents/pi-embedded-helpers/errors.ts

@@ -201,6 +201,14 @@ export function formatRawAssistantErrorForUi(raw?: string): string {
   const trimmed = (raw ?? "").trim();
   if (!trimmed) return "LLM request failed with an unknown error.";
 
+  const httpMatch = trimmed.match(HTTP_STATUS_PREFIX_RE);
+  if (httpMatch) {
+    const rest = httpMatch[2].trim();
+    if (!rest.startsWith("{")) {
+      return `HTTP ${httpMatch[1]}: ${rest}`;
+    }
+  }
+
   const info = parseApiErrorInfo(trimmed);
   if (info?.message) {
     const prefix = info.httpCode ? `HTTP ${info.httpCode}` : "LLM error";
@@ -261,8 +269,8 @@ export function formatAssistantErrorText(
     return "The AI service is temporarily overloaded. Please try again in a moment.";
   }
 
-  if (isRawApiErrorPayload(raw)) {
-    return "The AI service returned an error. Please try again.";
+  if (isLikelyHttpErrorText(raw) || isRawApiErrorPayload(raw)) {
+    return formatRawAssistantErrorForUi(raw);
   }
 
   // Never return raw unhandled errors - log for debugging but return safe message
@@ -293,7 +301,7 @@ export function sanitizeUserFacingText(text: string): string {
   }
 
   if (isRawApiErrorPayload(trimmed) || isLikelyHttpErrorText(trimmed)) {
-    return "The AI service returned an error. Please try again.";
+    return formatRawAssistantErrorForUi(trimmed);
   }
 
   if (ERROR_PREFIX_RE.test(trimmed)) {
@@ -303,7 +311,7 @@ export function sanitizeUserFacingText(text: string): string {
     if (isTimeoutErrorMessage(trimmed)) {
       return "LLM request timed out.";
     }
-    return "The AI service returned an error. Please try again.";
+    return formatRawAssistantErrorForUi(trimmed);
   }
 
   return stripped;

src/agents/pi-embedded-runner/compact.ts

@@ -1,7 +1,12 @@
 import fs from "node:fs/promises";
 import os from "node:os";
 
-import { createAgentSession, SessionManager, SettingsManager } from "@mariozechner/pi-coding-agent";
+import {
+  createAgentSession,
+  estimateTokens,
+  SessionManager,
+  SettingsManager,
+} from "@mariozechner/pi-coding-agent";
 
 import { resolveHeartbeatPrompt } from "../../auto-reply/heartbeat.js";
 import type { ReasoningLevel, ThinkLevel } from "../../auto-reply/thinking.js";
@@ -370,6 +375,26 @@ export async function compactEmbeddedPiSession(params: {
               session.agent.replaceMessages(limited);
             }
             const result = await session.compact(params.customInstructions);
+            // Estimate tokens after compaction with the same context-usage heuristics.
+            let tokensAfter: number | undefined;
+            try {
+              const usage =
+                typeof session.getContextUsage === "function"
+                  ? session.getContextUsage()
+                  : undefined;
+              let estimate = usage?.tokens;
+              if (!Number.isFinite(estimate) || !estimate || estimate <= 0) {
+                estimate = 0;
+                for (const message of session.messages) {
+                  estimate += estimateTokens(message);
+                }
+              }
+              if (Number.isFinite(estimate) && estimate > 0 && estimate <= result.tokensBefore) {
+                tokensAfter = estimate;
+              }
+            } catch {
+              tokensAfter = undefined;
+            }
             return {
               ok: true,
               compacted: true,
@@ -377,6 +402,7 @@ export async function compactEmbeddedPiSession(params: {
                 summary: result.summary,
                 firstKeptEntryId: result.firstKeptEntryId,
                 tokensBefore: result.tokensBefore,
+                tokensAfter,
                 details: result.details,
               },
             };

src/agents/pi-embedded-runner/run/payloads.ts

@@ -6,6 +6,7 @@ import { formatToolAggregate } from "../../../auto-reply/tool-meta.js";
 import type { ClawdbotConfig } from "../../../config/config.js";
 import {
   formatAssistantErrorText,
+  formatRawAssistantErrorForUi,
   getApiErrorPayloadFingerprint,
   isRawApiErrorPayload,
   normalizeTextForComparison,
@@ -64,6 +65,12 @@ export function buildEmbeddedRunPayloads(params: {
   const rawErrorFingerprint = rawErrorMessage
     ? getApiErrorPayloadFingerprint(rawErrorMessage)
     : null;
+  const formattedRawErrorMessage = rawErrorMessage
+    ? formatRawAssistantErrorForUi(rawErrorMessage)
+    : null;
+  const normalizedFormattedRawErrorMessage = formattedRawErrorMessage
+    ? normalizeTextForComparison(formattedRawErrorMessage)
+    : null;
   const normalizedRawErrorText = rawErrorMessage
     ? normalizeTextForComparison(rawErrorMessage)
     : null;
@@ -116,10 +123,15 @@ export function buildEmbeddedRunPayloads(params: {
       if (trimmed === genericErrorText) return true;
     }
     if (rawErrorMessage && trimmed === rawErrorMessage) return true;
+    if (formattedRawErrorMessage && trimmed === formattedRawErrorMessage) return true;
     if (normalizedRawErrorText) {
       const normalized = normalizeTextForComparison(trimmed);
       if (normalized && normalized === normalizedRawErrorText) return true;
     }
+    if (normalizedFormattedRawErrorMessage) {
+      const normalized = normalizeTextForComparison(trimmed);
+      if (normalized && normalized === normalizedFormattedRawErrorMessage) return true;
+    }
     if (rawErrorFingerprint) {
       const fingerprint = getApiErrorPayloadFingerprint(trimmed);
       if (fingerprint && fingerprint === rawErrorFingerprint) return true;

src/agents/pi-embedded-runner/types.ts

@@ -59,6 +59,7 @@ export type EmbeddedPiCompactResult = {
     summary: string;
     firstKeptEntryId: string;
     tokensBefore: number;
+    tokensAfter?: number;
     details?: unknown;
   };
 };

src/agents/subagent-registry.ts

@@ -31,7 +31,8 @@ const subagentRuns = new Map<string, SubagentRunRecord>();
 let sweeper: NodeJS.Timeout | null = null;
 let listenerStarted = false;
 let listenerStop: (() => void) | null = null;
-let restoreAttempted = false;
+// Use var to avoid TDZ on circular init paths that can call restoreSubagentRunsOnce early.
+var restoreAttempted = false;
 
 function persistSubagentRuns() {
   try {

src/agents/system-prompt.test.ts

@@ -23,7 +23,7 @@ describe("buildAgentSystemPrompt", () => {
     expect(prompt).not.toContain("Owner numbers:");
   });
 
-  it("keeps skills but omits other extended sections in minimal prompt mode", () => {
+  it("omits extended sections in minimal prompt mode", () => {
     const prompt = buildAgentSystemPrompt({
       workspaceDir: "/tmp/clawd",
       promptMode: "minimal",
@@ -37,8 +37,7 @@ describe("buildAgentSystemPrompt", () => {
     });
 
     expect(prompt).not.toContain("## User Identity");
-    expect(prompt).toContain("## Skills (mandatory)");
-    expect(prompt).toContain("<available_skills>");
+    expect(prompt).not.toContain("## Skills");
     expect(prompt).not.toContain("## Memory Recall");
     expect(prompt).not.toContain("## Documentation");
     expect(prompt).not.toContain("## Reply Tags");

src/agents/system-prompt.ts

@@ -7,7 +7,7 @@ import type { EmbeddedContextFile } from "./pi-embedded-helpers.js";
 /**
  * Controls which hardcoded sections are included in the system prompt.
  * - "full": All sections (default, for main agent)
- * - "minimal": Reduced sections (Tooling, Skills, Workspace, Runtime) - used for subagents
+ * - "minimal": Reduced sections (Tooling, Workspace, Runtime) - used for subagents
  * - "none": Just basic identity line, no sections
  */
 export type PromptMode = "full" | "minimal" | "none";
@@ -17,6 +17,7 @@ function buildSkillsSection(params: {
   isMinimal: boolean;
   readToolName: string;
 }) {
+  if (params.isMinimal) return [];
   const trimmed = params.skillsPrompt?.trim();
   if (!trimmed) return [];
   return [
@@ -211,7 +212,7 @@ export function buildAgentSystemPrompt(params: {
     sessions_send: "Send a message to another session/sub-agent",
     sessions_spawn: "Spawn a sub-agent session",
     session_status:
-      "Show a /status-equivalent status card (usage + Reasoning/Verbose/Elevated); optional per-session model override",
+      "Show a /status-equivalent status card (usage + Reasoning/Verbose/Elevated); use for model-use questions (📊 session_status); optional per-session model override",
     image: "Analyze an image with the configured image model",
   };
 

src/agents/tools/session-status-tool.ts

@@ -215,7 +215,7 @@ export function createSessionStatusTool(opts?: {
     label: "Session Status",
     name: "session_status",
     description:
-      "Show a /status-equivalent session status card. Optional: set per-session model override (model=default resets overrides). Includes usage + cost when available.",
+      "Show a /status-equivalent session status card (usage + cost when available). Use for model-use questions (📊 session_status). Optional: set per-session model override (model=default resets overrides).",
     parameters: SessionStatusToolSchema,
     execute: async (_toolCallId, args) => {
       const params = args as Record<string, unknown>;

src/auto-reply/reply.block-streaming.test.ts

@@ -42,7 +42,7 @@ describe("block streaming", () => {
   });
 
   async function waitForCalls(fn: () => number, calls: number) {
-    const deadline = Date.now() + 1500;
+    const deadline = Date.now() + 15000;
     while (fn() < calls) {
       if (Date.now() > deadline) {
         throw new Error(`Expected ${calls} call(s), got ${fn()}`);

src/auto-reply/reply/commands-compact.ts

@@ -83,18 +83,13 @@ export const handleCompactCommand: CommandHandler = async (params) => {
     ownerNumbers: params.command.ownerList.length > 0 ? params.command.ownerList : undefined,
   });
 
-  const totalTokens =
-    params.sessionEntry.totalTokens ??
-    (params.sessionEntry.inputTokens ?? 0) + (params.sessionEntry.outputTokens ?? 0);
-  const contextSummary = formatContextUsageShort(
-    totalTokens > 0 ? totalTokens : null,
-    params.contextTokens ?? params.sessionEntry.contextTokens ?? null,
-  );
   const compactLabel = result.ok
     ? result.compacted
-      ? result.result?.tokensBefore
-        ? `Compacted (${formatTokenCount(result.result.tokensBefore)} before)`
-        : "Compacted"
+      ? result.result?.tokensBefore != null && result.result?.tokensAfter != null
+        ? `Compacted (${formatTokenCount(result.result.tokensBefore)} → ${formatTokenCount(result.result.tokensAfter)})`
+        : result.result?.tokensBefore
+          ? `Compacted (${formatTokenCount(result.result.tokensBefore)} before)`
+          : "Compacted"
       : "Compaction skipped"
     : "Compaction failed";
   if (result.ok && result.compacted) {
@@ -103,8 +98,20 @@ export const handleCompactCommand: CommandHandler = async (params) => {
       sessionStore: params.sessionStore,
       sessionKey: params.sessionKey,
       storePath: params.storePath,
+      // Update token counts after compaction
+      tokensAfter: result.result?.tokensAfter,
     });
   }
+  // Use the post-compaction token count for context summary if available
+  const tokensAfterCompaction = result.result?.tokensAfter;
+  const totalTokens =
+    tokensAfterCompaction ??
+    params.sessionEntry.totalTokens ??
+    (params.sessionEntry.inputTokens ?? 0) + (params.sessionEntry.outputTokens ?? 0);
+  const contextSummary = formatContextUsageShort(
+    totalTokens > 0 ? totalTokens : null,
+    params.contextTokens ?? params.sessionEntry.contextTokens ?? null,
+  );
   const reason = result.reason?.trim();
   const line = reason
     ? `${compactLabel}: ${reason} • ${contextSummary}`

src/auto-reply/reply/directive-handling.fast-lane.ts

@@ -15,8 +15,8 @@ export async function applyInlineDirectivesFastLane(params: {
   cfg: ClawdbotConfig;
   agentId?: string;
   isGroup: boolean;
-  sessionEntry?: SessionEntry;
-  sessionStore?: Record<string, SessionEntry>;
+  sessionEntry: SessionEntry;
+  sessionStore: Record<string, SessionEntry>;
   sessionKey: string;
   storePath?: string;
   elevatedEnabled: boolean;

src/auto-reply/reply/directive-handling.impl.model-persist.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, it, vi } from "vitest";
+
+import type { ModelAliasIndex } from "../../agents/model-selection.js";
+import type { ClawdbotConfig } from "../../config/config.js";
+import type { SessionEntry } from "../../config/sessions.js";
+import { parseInlineDirectives } from "./directive-handling.js";
+import { handleDirectiveOnly } from "./directive-handling.impl.js";
+
+// Mock dependencies
+vi.mock("../../agents/agent-scope.js", () => ({
+  resolveAgentConfig: vi.fn(() => ({})),
+  resolveAgentDir: vi.fn(() => "/tmp/agent"),
+  resolveSessionAgentId: vi.fn(() => "main"),
+}));
+
+vi.mock("../../agents/sandbox.js", () => ({
+  resolveSandboxRuntimeStatus: vi.fn(() => ({ sandboxed: false })),
+}));
+
+vi.mock("../../config/sessions.js", () => ({
+  updateSessionStore: vi.fn(async () => {}),
+}));
+
+vi.mock("../../infra/system-events.js", () => ({
+  enqueueSystemEvent: vi.fn(),
+}));
+
+function baseAliasIndex(): ModelAliasIndex {
+  return { byAlias: new Map(), byKey: new Map() };
+}
+
+function baseConfig(): ClawdbotConfig {
+  return {
+    commands: { text: true },
+    agents: { defaults: {} },
+  } as unknown as ClawdbotConfig;
+}
+
+describe("handleDirectiveOnly model persist behavior (fixes #1435)", () => {
+  const allowedModelKeys = new Set(["anthropic/claude-opus-4-5", "openai/gpt-4o"]);
+  const allowedModelCatalog = [
+    { provider: "anthropic", id: "claude-opus-4-5" },
+    { provider: "openai", id: "gpt-4o" },
+  ];
+
+  it("shows success message when session state is available", async () => {
+    const directives = parseInlineDirectives("/model openai/gpt-4o");
+    const sessionEntry: SessionEntry = {
+      sessionId: "s1",
+      updatedAt: Date.now(),
+    };
+    const sessionStore = { "agent:main:dm:1": sessionEntry };
+
+    const result = await handleDirectiveOnly({
+      cfg: baseConfig(),
+      directives,
+      sessionEntry,
+      sessionStore,
+      sessionKey: "agent:main:dm:1",
+      storePath: "/tmp/sessions.json",
+      elevatedEnabled: false,
+      elevatedAllowed: false,
+      defaultProvider: "anthropic",
+      defaultModel: "claude-opus-4-5",
+      aliasIndex: baseAliasIndex(),
+      allowedModelKeys,
+      allowedModelCatalog,
+      resetModelOverride: false,
+      provider: "anthropic",
+      model: "claude-opus-4-5",
+      initialModelLabel: "anthropic/claude-opus-4-5",
+      formatModelSwitchEvent: (label) => `Switched to ${label}`,
+    });
+
+    expect(result?.text).toContain("Model set to");
+    expect(result?.text).toContain("openai/gpt-4o");
+    expect(result?.text).not.toContain("failed");
+  });
+
+  it("shows no model message when no /model directive", async () => {
+    const directives = parseInlineDirectives("hello world");
+    const sessionEntry: SessionEntry = {
+      sessionId: "s1",
+      updatedAt: Date.now(),
+    };
+    const sessionStore = { "agent:main:dm:1": sessionEntry };
+
+    const result = await handleDirectiveOnly({
+      cfg: baseConfig(),
+      directives,
+      sessionEntry,
+      sessionStore,
+      sessionKey: "agent:main:dm:1",
+      storePath: "/tmp/sessions.json",
+      elevatedEnabled: false,
+      elevatedAllowed: false,
+      defaultProvider: "anthropic",
+      defaultModel: "claude-opus-4-5",
+      aliasIndex: baseAliasIndex(),
+      allowedModelKeys,
+      allowedModelCatalog,
+      resetModelOverride: false,
+      provider: "anthropic",
+      model: "claude-opus-4-5",
+      initialModelLabel: "anthropic/claude-opus-4-5",
+      formatModelSwitchEvent: (label) => `Switched to ${label}`,
+    });
+
+    // No model directive = no model message
+    expect(result?.text ?? "").not.toContain("Model set to");
+    expect(result?.text ?? "").not.toContain("failed");
+  });
+});

src/auto-reply/reply/directive-handling.impl.ts

@@ -62,8 +62,8 @@ function resolveExecDefaults(params: {
 export async function handleDirectiveOnly(params: {
   cfg: ClawdbotConfig;
   directives: InlineDirectives;
-  sessionEntry?: SessionEntry;
-  sessionStore?: Record<string, SessionEntry>;
+  sessionEntry: SessionEntry;
+  sessionStore: Record<string, SessionEntry>;
   sessionKey: string;
   storePath?: string;
   elevatedEnabled: boolean;
@@ -288,113 +288,111 @@ export async function handleDirectiveOnly(params: {
     nextThinkLevel === "xhigh" &&
     !supportsXHighThinking(resolvedProvider, resolvedModel);
 
-  if (sessionEntry && sessionStore && sessionKey) {
-    const prevElevatedLevel =
-      currentElevatedLevel ??
-      (sessionEntry.elevatedLevel as ElevatedLevel | undefined) ??
-      (elevatedAllowed ? ("on" as ElevatedLevel) : ("off" as ElevatedLevel));
-    const prevReasoningLevel =
-      currentReasoningLevel ?? (sessionEntry.reasoningLevel as ReasoningLevel | undefined) ?? "off";
-    let elevatedChanged =
-      directives.hasElevatedDirective &&
-      directives.elevatedLevel !== undefined &&
-      elevatedEnabled &&
-      elevatedAllowed;
-    let reasoningChanged =
-      directives.hasReasoningDirective && directives.reasoningLevel !== undefined;
-    if (directives.hasThinkDirective && directives.thinkLevel) {
-      if (directives.thinkLevel === "off") delete sessionEntry.thinkingLevel;
-      else sessionEntry.thinkingLevel = directives.thinkLevel;
+  const prevElevatedLevel =
+    currentElevatedLevel ??
+    (sessionEntry.elevatedLevel as ElevatedLevel | undefined) ??
+    (elevatedAllowed ? ("on" as ElevatedLevel) : ("off" as ElevatedLevel));
+  const prevReasoningLevel =
+    currentReasoningLevel ?? (sessionEntry.reasoningLevel as ReasoningLevel | undefined) ?? "off";
+  let elevatedChanged =
+    directives.hasElevatedDirective &&
+    directives.elevatedLevel !== undefined &&
+    elevatedEnabled &&
+    elevatedAllowed;
+  let reasoningChanged =
+    directives.hasReasoningDirective && directives.reasoningLevel !== undefined;
+  if (directives.hasThinkDirective && directives.thinkLevel) {
+    if (directives.thinkLevel === "off") delete sessionEntry.thinkingLevel;
+    else sessionEntry.thinkingLevel = directives.thinkLevel;
+  }
+  if (shouldDowngradeXHigh) {
+    sessionEntry.thinkingLevel = "high";
+  }
+  if (directives.hasVerboseDirective && directives.verboseLevel) {
+    applyVerboseOverride(sessionEntry, directives.verboseLevel);
+  }
+  if (directives.hasReasoningDirective && directives.reasoningLevel) {
+    if (directives.reasoningLevel === "off") delete sessionEntry.reasoningLevel;
+    else sessionEntry.reasoningLevel = directives.reasoningLevel;
+    reasoningChanged =
+      directives.reasoningLevel !== prevReasoningLevel && directives.reasoningLevel !== undefined;
+  }
+  if (directives.hasElevatedDirective && directives.elevatedLevel) {
+    // Unlike other toggles, elevated defaults can be "on".
+    // Persist "off" explicitly so `/elevated off` actually overrides defaults.
+    sessionEntry.elevatedLevel = directives.elevatedLevel;
+    elevatedChanged =
+      elevatedChanged ||
+      (directives.elevatedLevel !== prevElevatedLevel && directives.elevatedLevel !== undefined);
+  }
+  if (directives.hasExecDirective && directives.hasExecOptions) {
+    if (directives.execHost) {
+      sessionEntry.execHost = directives.execHost;
     }
-    if (shouldDowngradeXHigh) {
-      sessionEntry.thinkingLevel = "high";
+    if (directives.execSecurity) {
+      sessionEntry.execSecurity = directives.execSecurity;
     }
-    if (directives.hasVerboseDirective && directives.verboseLevel) {
-      applyVerboseOverride(sessionEntry, directives.verboseLevel);
+    if (directives.execAsk) {
+      sessionEntry.execAsk = directives.execAsk;
     }
-    if (directives.hasReasoningDirective && directives.reasoningLevel) {
-      if (directives.reasoningLevel === "off") delete sessionEntry.reasoningLevel;
-      else sessionEntry.reasoningLevel = directives.reasoningLevel;
-      reasoningChanged =
-        directives.reasoningLevel !== prevReasoningLevel && directives.reasoningLevel !== undefined;
+    if (directives.execNode) {
+      sessionEntry.execNode = directives.execNode;
     }
-    if (directives.hasElevatedDirective && directives.elevatedLevel) {
-      // Unlike other toggles, elevated defaults can be "on".
-      // Persist "off" explicitly so `/elevated off` actually overrides defaults.
-      sessionEntry.elevatedLevel = directives.elevatedLevel;
-      elevatedChanged =
-        elevatedChanged ||
-        (directives.elevatedLevel !== prevElevatedLevel && directives.elevatedLevel !== undefined);
+  }
+  if (modelSelection) {
+    applyModelOverrideToSessionEntry({
+      entry: sessionEntry,
+      selection: modelSelection,
+      profileOverride,
+    });
+  }
+  if (directives.hasQueueDirective && directives.queueReset) {
+    delete sessionEntry.queueMode;
+    delete sessionEntry.queueDebounceMs;
+    delete sessionEntry.queueCap;
+    delete sessionEntry.queueDrop;
+  } else if (directives.hasQueueDirective) {
+    if (directives.queueMode) sessionEntry.queueMode = directives.queueMode;
+    if (typeof directives.debounceMs === "number") {
+      sessionEntry.queueDebounceMs = directives.debounceMs;
     }
-    if (directives.hasExecDirective && directives.hasExecOptions) {
-      if (directives.execHost) {
-        sessionEntry.execHost = directives.execHost;
-      }
-      if (directives.execSecurity) {
-        sessionEntry.execSecurity = directives.execSecurity;
-      }
-      if (directives.execAsk) {
-        sessionEntry.execAsk = directives.execAsk;
-      }
-      if (directives.execNode) {
-        sessionEntry.execNode = directives.execNode;
-      }
+    if (typeof directives.cap === "number") {
+      sessionEntry.queueCap = directives.cap;
     }
-    if (modelSelection) {
-      applyModelOverrideToSessionEntry({
-        entry: sessionEntry,
-        selection: modelSelection,
-        profileOverride,
-      });
+    if (directives.dropPolicy) {
+      sessionEntry.queueDrop = directives.dropPolicy;
     }
-    if (directives.hasQueueDirective && directives.queueReset) {
-      delete sessionEntry.queueMode;
-      delete sessionEntry.queueDebounceMs;
-      delete sessionEntry.queueCap;
-      delete sessionEntry.queueDrop;
-    } else if (directives.hasQueueDirective) {
-      if (directives.queueMode) sessionEntry.queueMode = directives.queueMode;
-      if (typeof directives.debounceMs === "number") {
-        sessionEntry.queueDebounceMs = directives.debounceMs;
-      }
-      if (typeof directives.cap === "number") {
-        sessionEntry.queueCap = directives.cap;
-      }
-      if (directives.dropPolicy) {
-        sessionEntry.queueDrop = directives.dropPolicy;
-      }
-    }
-    sessionEntry.updatedAt = Date.now();
-    sessionStore[sessionKey] = sessionEntry;
-    if (storePath) {
-      await updateSessionStore(storePath, (store) => {
-        store[sessionKey] = sessionEntry;
-      });
-    }
-    if (modelSelection) {
-      const nextLabel = `${modelSelection.provider}/${modelSelection.model}`;
-      if (nextLabel !== initialModelLabel) {
-        enqueueSystemEvent(formatModelSwitchEvent(nextLabel, modelSelection.alias), {
-          sessionKey,
-          contextKey: `model:${nextLabel}`,
-        });
-      }
-    }
-    if (elevatedChanged) {
-      const nextElevated = (sessionEntry.elevatedLevel ?? "off") as ElevatedLevel;
-      enqueueSystemEvent(formatElevatedEvent(nextElevated), {
+  }
+  sessionEntry.updatedAt = Date.now();
+  sessionStore[sessionKey] = sessionEntry;
+  if (storePath) {
+    await updateSessionStore(storePath, (store) => {
+      store[sessionKey] = sessionEntry;
+    });
+  }
+  if (modelSelection) {
+    const nextLabel = `${modelSelection.provider}/${modelSelection.model}`;
+    if (nextLabel !== initialModelLabel) {
+      enqueueSystemEvent(formatModelSwitchEvent(nextLabel, modelSelection.alias), {
         sessionKey,
-        contextKey: "mode:elevated",
-      });
-    }
-    if (reasoningChanged) {
-      const nextReasoning = (sessionEntry.reasoningLevel ?? "off") as ReasoningLevel;
-      enqueueSystemEvent(formatReasoningEvent(nextReasoning), {
-        sessionKey,
-        contextKey: "mode:reasoning",
+        contextKey: `model:${nextLabel}`,
       });
     }
   }
+  if (elevatedChanged) {
+    const nextElevated = (sessionEntry.elevatedLevel ?? "off") as ElevatedLevel;
+    enqueueSystemEvent(formatElevatedEvent(nextElevated), {
+      sessionKey,
+      contextKey: "mode:elevated",
+    });
+  }
+  if (reasoningChanged) {
+    const nextReasoning = (sessionEntry.reasoningLevel ?? "off") as ReasoningLevel;
+    enqueueSystemEvent(formatReasoningEvent(nextReasoning), {
+      sessionKey,
+      contextKey: "mode:reasoning",
+    });
+  }
 
   const parts: string[] = [];
   if (directives.hasThinkDirective && directives.thinkLevel) {

src/auto-reply/reply/get-reply-directives-apply.ts

@@ -39,8 +39,8 @@ export async function applyInlineDirectiveOverrides(params: {
   agentId: string;
   agentDir: string;
   agentCfg: AgentDefaults;
-  sessionEntry?: SessionEntry;
-  sessionStore?: Record<string, SessionEntry>;
+  sessionEntry: SessionEntry;
+  sessionStore: Record<string, SessionEntry>;
   sessionKey: string;
   storePath?: string;
   sessionScope: Parameters<typeof buildStatusReply>[0]["sessionScope"];

src/auto-reply/reply/get-reply-directives.ts

@@ -89,8 +89,8 @@ export async function resolveReplyDirectives(params: {
   workspaceDir: string;
   agentCfg: AgentDefaults;
   sessionCtx: TemplateContext;
-  sessionEntry?: SessionEntry;
-  sessionStore?: Record<string, SessionEntry>;
+  sessionEntry: SessionEntry;
+  sessionStore: Record<string, SessionEntry>;
   sessionKey: string;
   storePath?: string;
   sessionScope: Parameters<typeof applyInlineDirectiveOverrides>[0]["sessionScope"];

src/auto-reply/reply/session-updates.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, it, vi } from "vitest";
 
 import type { ClawdbotConfig } from "../../config/config.js";
 import { enqueueSystemEvent, resetSystemEventsForTest } from "../../infra/system-events.js";
-import { prependSystemEvents } from "./session-updates.js";
+import { incrementCompactionCount, prependSystemEvents } from "./session-updates.js";
 
 describe("prependSystemEvents", () => {
   it("adds a local timestamp to queued system events by default", async () => {
@@ -29,3 +29,37 @@ describe("prependSystemEvents", () => {
     vi.useRealTimers();
   });
 });
+
+describe("incrementCompactionCount", () => {
+  it("updates cached total tokens after compaction without clearing input/output", async () => {
+    const sessionKey = "agent:main:main";
+    const sessionStore = {
+      [sessionKey]: {
+        sessionId: "s1",
+        updatedAt: 10,
+        compactionCount: 1,
+        totalTokens: 9_000,
+        inputTokens: 111,
+        outputTokens: 222,
+      },
+    };
+    const now = 1234;
+
+    const nextCount = await incrementCompactionCount({
+      sessionEntry: sessionStore[sessionKey],
+      sessionStore,
+      sessionKey,
+      now,
+      tokensAfter: 2_000,
+    });
+
+    expect(nextCount).toBe(2);
+    expect(sessionStore[sessionKey]).toMatchObject({
+      compactionCount: 2,
+      totalTokens: 2_000,
+      inputTokens: 111,
+      outputTokens: 222,
+      updatedAt: now,
+    });
+  });
+});

src/auto-reply/reply/session-updates.ts

@@ -237,23 +237,39 @@ export async function incrementCompactionCount(params: {
   sessionKey?: string;
   storePath?: string;
   now?: number;
+  /** Token count after compaction - if provided, updates cached context usage */
+  tokensAfter?: number;
 }): Promise<number | undefined> {
-  const { sessionEntry, sessionStore, sessionKey, storePath, now = Date.now() } = params;
+  const {
+    sessionEntry,
+    sessionStore,
+    sessionKey,
+    storePath,
+    now = Date.now(),
+    tokensAfter,
+  } = params;
   if (!sessionStore || !sessionKey) return undefined;
   const entry = sessionStore[sessionKey] ?? sessionEntry;
   if (!entry) return undefined;
   const nextCount = (entry.compactionCount ?? 0) + 1;
-  sessionStore[sessionKey] = {
-    ...entry,
+  // Build update payload with compaction count and optionally updated context usage.
+  const updates: Partial<SessionEntry> = {
     compactionCount: nextCount,
     updatedAt: now,
   };
+  // If tokensAfter is provided, update the cached total to reflect post-compaction context size.
+  if (tokensAfter != null && tokensAfter > 0) {
+    updates.totalTokens = tokensAfter;
+  }
+  sessionStore[sessionKey] = {
+    ...entry,
+    ...updates,
+  };
   if (storePath) {
     await updateSessionStore(storePath, (store) => {
       store[sessionKey] = {
         ...store[sessionKey],
-        compactionCount: nextCount,
-        updatedAt: now,
+        ...updates,
       };
     });
   }

src/daemon/program-args.ts

@@ -237,7 +237,7 @@ export async function resolveNodeProgramArguments(params: {
   runtime?: GatewayRuntimePreference;
   nodePath?: string;
 }): Promise<GatewayProgramArgs> {
-  const args = ["node", "start", "--host", params.host, "--port", String(params.port)];
+  const args = ["node", "run", "--host", params.host, "--port", String(params.port)];
   if (params.tls || params.tlsFingerprint) args.push("--tls");
   if (params.tlsFingerprint) args.push("--tls-fingerprint", params.tlsFingerprint);
   if (params.nodeId) args.push("--node-id", params.nodeId);

src/gateway/assistant-identity.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from "vitest";
+
+import type { ClawdbotConfig } from "../config/config.js";
+import { DEFAULT_ASSISTANT_IDENTITY, resolveAssistantIdentity } from "./assistant-identity.js";
+
+describe("resolveAssistantIdentity avatar normalization", () => {
+  it("drops sentence-like avatar placeholders", () => {
+    const cfg: ClawdbotConfig = {
+      ui: {
+        assistant: {
+          avatar: "workspace-relative path, http(s) URL, or data URI",
+        },
+      },
+    };
+
+    expect(resolveAssistantIdentity({ cfg, workspaceDir: "" }).avatar).toBe(
+      DEFAULT_ASSISTANT_IDENTITY.avatar,
+    );
+  });
+
+  it("keeps short text avatars", () => {
+    const cfg: ClawdbotConfig = {
+      ui: {
+        assistant: {
+          avatar: "PS",
+        },
+      },
+    };
+
+    expect(resolveAssistantIdentity({ cfg, workspaceDir: "" }).avatar).toBe("PS");
+  });
+
+  it("keeps path avatars", () => {
+    const cfg: ClawdbotConfig = {
+      ui: {
+        assistant: {
+          avatar: "avatars/clawd.png",
+        },
+      },
+    };
+
+    expect(resolveAssistantIdentity({ cfg, workspaceDir: "" }).avatar).toBe("avatars/clawd.png");
+  });
+});

src/gateway/assistant-identity.ts

@@ -26,6 +26,25 @@ function coerceIdentityValue(value: string | undefined, maxLength: number): stri
   return trimmed.slice(0, maxLength);
 }
 
+function isAvatarUrl(value: string): boolean {
+  return /^https?:\/\//i.test(value) || /^data:image\//i.test(value);
+}
+
+function looksLikeAvatarPath(value: string): boolean {
+  if (/[\\/]/.test(value)) return true;
+  return /\.(png|jpe?g|gif|webp|svg|ico)$/i.test(value);
+}
+
+function normalizeAvatarValue(value: string | undefined): string | undefined {
+  if (!value) return undefined;
+  const trimmed = value.trim();
+  if (!trimmed) return undefined;
+  if (isAvatarUrl(trimmed)) return trimmed;
+  if (looksLikeAvatarPath(trimmed)) return trimmed;
+  if (!/\s/.test(trimmed) && trimmed.length <= 4) return trimmed;
+  return undefined;
+}
+
 export function resolveAssistantIdentity(params: {
   cfg: ClawdbotConfig;
   agentId?: string | null;
@@ -43,12 +62,15 @@ export function resolveAssistantIdentity(params: {
     coerceIdentityValue(fileIdentity?.name, MAX_ASSISTANT_NAME) ??
     DEFAULT_ASSISTANT_IDENTITY.name;
 
+  const avatarCandidates = [
+    coerceIdentityValue(configAssistant?.avatar, MAX_ASSISTANT_AVATAR),
+    coerceIdentityValue(agentIdentity?.avatar, MAX_ASSISTANT_AVATAR),
+    coerceIdentityValue(agentIdentity?.emoji, MAX_ASSISTANT_AVATAR),
+    coerceIdentityValue(fileIdentity?.avatar, MAX_ASSISTANT_AVATAR),
+    coerceIdentityValue(fileIdentity?.emoji, MAX_ASSISTANT_AVATAR),
+  ];
   const avatar =
-    coerceIdentityValue(configAssistant?.avatar, MAX_ASSISTANT_AVATAR) ??
-    coerceIdentityValue(agentIdentity?.avatar, MAX_ASSISTANT_AVATAR) ??
-    coerceIdentityValue(agentIdentity?.emoji, MAX_ASSISTANT_AVATAR) ??
-    coerceIdentityValue(fileIdentity?.avatar, MAX_ASSISTANT_AVATAR) ??
-    coerceIdentityValue(fileIdentity?.emoji, MAX_ASSISTANT_AVATAR) ??
+    avatarCandidates.map((candidate) => normalizeAvatarValue(candidate)).find(Boolean) ??
     DEFAULT_ASSISTANT_IDENTITY.avatar;
 
   return { agentId, name, avatar };

src/gateway/control-ui.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from "vitest";
+
+import { resolveAssistantAvatarUrl } from "./control-ui.js";
+
+describe("resolveAssistantAvatarUrl", () => {
+  it("keeps remote and data URLs", () => {
+    expect(
+      resolveAssistantAvatarUrl({
+        avatar: "https://example.com/avatar.png",
+        agentId: "main",
+        basePath: "/ui",
+      }),
+    ).toBe("https://example.com/avatar.png");
+    expect(
+      resolveAssistantAvatarUrl({
+        avatar: "data:image/png;base64,abc",
+        agentId: "main",
+        basePath: "/ui",
+      }),
+    ).toBe("data:image/png;base64,abc");
+  });
+
+  it("prefixes basePath for /avatar endpoints", () => {
+    expect(
+      resolveAssistantAvatarUrl({
+        avatar: "/avatar/main",
+        agentId: "main",
+        basePath: "/ui",
+      }),
+    ).toBe("/ui/avatar/main");
+    expect(
+      resolveAssistantAvatarUrl({
+        avatar: "/ui/avatar/main",
+        agentId: "main",
+        basePath: "/ui",
+      }),
+    ).toBe("/ui/avatar/main");
+  });
+
+  it("maps local avatar paths to the avatar endpoint", () => {
+    expect(
+      resolveAssistantAvatarUrl({
+        avatar: "avatars/me.png",
+        agentId: "main",
+        basePath: "/ui",
+      }),
+    ).toBe("/ui/avatar/main");
+    expect(
+      resolveAssistantAvatarUrl({
+        avatar: "avatars/profile",
+        agentId: "main",
+        basePath: "/ui",
+      }),
+    ).toBe("/ui/avatar/main");
+  });
+
+  it("keeps short text avatars", () => {
+    expect(
+      resolveAssistantAvatarUrl({
+        avatar: "PS",
+        agentId: "main",
+        basePath: "/ui",
+      }),
+    ).toBe("PS");
+  });
+});

src/gateway/control-ui.ts

@@ -98,7 +98,7 @@ function sendJson(res: ServerResponse, status: number, body: unknown) {
   res.end(JSON.stringify(body));
 }
 
-function buildAvatarUrl(basePath: string, agentId: string): string {
+export function buildAvatarUrl(basePath: string, agentId: string): string {
   return basePath ? `${basePath}${AVATAR_PREFIX}/${agentId}` : `${AVATAR_PREFIX}/${agentId}`;
 }
 
@@ -206,11 +206,49 @@ interface ServeIndexHtmlOpts {
   agentId?: string;
 }
 
+function looksLikeLocalAvatarPath(value: string): boolean {
+  if (/[\\/]/.test(value)) return true;
+  return /\.(png|jpe?g|gif|webp|svg|ico)$/i.test(value);
+}
+
+export function resolveAssistantAvatarUrl(params: {
+  avatar?: string | null;
+  agentId?: string | null;
+  basePath?: string;
+}): string | undefined {
+  const avatar = params.avatar?.trim();
+  if (!avatar) return undefined;
+  if (/^https?:\/\//i.test(avatar) || /^data:image\//i.test(avatar)) return avatar;
+
+  const basePath = normalizeControlUiBasePath(params.basePath);
+  const baseAvatarPrefix = basePath ? `${basePath}${AVATAR_PREFIX}/` : `${AVATAR_PREFIX}/`;
+  if (basePath && avatar.startsWith(`${AVATAR_PREFIX}/`)) {
+    return `${basePath}${avatar}`;
+  }
+  if (avatar.startsWith(baseAvatarPrefix)) return avatar;
+
+  if (!params.agentId) return avatar;
+  if (looksLikeLocalAvatarPath(avatar)) {
+    return buildAvatarUrl(basePath, params.agentId);
+  }
+  return avatar;
+}
+
 function serveIndexHtml(res: ServerResponse, indexPath: string, opts: ServeIndexHtmlOpts) {
   const { basePath, config, agentId } = opts;
   const identity = config
     ? resolveAssistantIdentity({ cfg: config, agentId })
     : DEFAULT_ASSISTANT_IDENTITY;
+  const resolvedAgentId =
+    typeof (identity as { agentId?: string }).agentId === "string"
+      ? (identity as { agentId?: string }).agentId
+      : agentId;
+  const avatarValue =
+    resolveAssistantAvatarUrl({
+      avatar: identity.avatar,
+      agentId: resolvedAgentId,
+      basePath,
+    }) ?? identity.avatar;
   res.setHeader("Content-Type", "text/html; charset=utf-8");
   res.setHeader("Cache-Control", "no-cache");
   const raw = fs.readFileSync(indexPath, "utf8");
@@ -218,7 +256,7 @@ function serveIndexHtml(res: ServerResponse, indexPath: string, opts: ServeIndex
     injectControlUiConfig(raw, {
       basePath,
       assistantName: identity.name,
-      assistantAvatar: identity.avatar,
+      assistantAvatar: avatarValue,
     }),
   );
 }

src/gateway/protocol/index.ts

@@ -140,6 +140,8 @@ import {
   SessionsListParamsSchema,
   type SessionsPatchParams,
   SessionsPatchParamsSchema,
+  type SessionsPreviewParams,
+  SessionsPreviewParamsSchema,
   type SessionsResetParams,
   SessionsResetParamsSchema,
   type SessionsResolveParams,
@@ -229,6 +231,9 @@ export const validateNodeInvokeResultParams = ajv.compile<NodeInvokeResultParams
 );
 export const validateNodeEventParams = ajv.compile<NodeEventParams>(NodeEventParamsSchema);
 export const validateSessionsListParams = ajv.compile<SessionsListParams>(SessionsListParamsSchema);
+export const validateSessionsPreviewParams = ajv.compile<SessionsPreviewParams>(
+  SessionsPreviewParamsSchema,
+);
 export const validateSessionsResolveParams = ajv.compile<SessionsResolveParams>(
   SessionsResolveParamsSchema,
 );
@@ -376,6 +381,7 @@ export {
   NodeListParamsSchema,
   NodeInvokeParamsSchema,
   SessionsListParamsSchema,
+  SessionsPreviewParamsSchema,
   SessionsPatchParamsSchema,
   SessionsResetParamsSchema,
   SessionsDeleteParamsSchema,
@@ -488,6 +494,7 @@ export type {
   NodeInvokeResultParams,
   NodeEventParams,
   SessionsListParams,
+  SessionsPreviewParams,
   SessionsResolveParams,
   SessionsPatchParams,
   SessionsResetParams,

src/gateway/protocol/schema/protocol-schemas.ts

@@ -108,6 +108,7 @@ import {
   SessionsDeleteParamsSchema,
   SessionsListParamsSchema,
   SessionsPatchParamsSchema,
+  SessionsPreviewParamsSchema,
   SessionsResetParamsSchema,
   SessionsResolveParamsSchema,
 } from "./sessions.js";
@@ -155,6 +156,7 @@ export const ProtocolSchemas: Record<string, TSchema> = {
   NodeEventParams: NodeEventParamsSchema,
   NodeInvokeRequestEvent: NodeInvokeRequestEventSchema,
   SessionsListParams: SessionsListParamsSchema,
+  SessionsPreviewParams: SessionsPreviewParamsSchema,
   SessionsResolveParams: SessionsResolveParamsSchema,
   SessionsPatchParams: SessionsPatchParamsSchema,
   SessionsResetParams: SessionsResetParamsSchema,

src/gateway/protocol/schema/sessions.ts

@@ -26,6 +26,15 @@ export const SessionsListParamsSchema = Type.Object(
   { additionalProperties: false },
 );
 
+export const SessionsPreviewParamsSchema = Type.Object(
+  {
+    keys: Type.Array(NonEmptyString, { minItems: 1 }),
+    limit: Type.Optional(Type.Integer({ minimum: 1 })),
+    maxChars: Type.Optional(Type.Integer({ minimum: 20 })),
+  },
+  { additionalProperties: false },
+);
+
 export const SessionsResolveParamsSchema = Type.Object(
   {
     key: Type.Optional(NonEmptyString),

src/gateway/protocol/schema/types.ts

@@ -101,6 +101,7 @@ import type {
   SessionsDeleteParamsSchema,
   SessionsListParamsSchema,
   SessionsPatchParamsSchema,
+  SessionsPreviewParamsSchema,
   SessionsResetParamsSchema,
   SessionsResolveParamsSchema,
 } from "./sessions.js";
@@ -144,6 +145,7 @@ export type NodeInvokeParams = Static<typeof NodeInvokeParamsSchema>;
 export type NodeInvokeResultParams = Static<typeof NodeInvokeResultParamsSchema>;
 export type NodeEventParams = Static<typeof NodeEventParamsSchema>;
 export type SessionsListParams = Static<typeof SessionsListParamsSchema>;
+export type SessionsPreviewParams = Static<typeof SessionsPreviewParamsSchema>;
 export type SessionsResolveParams = Static<typeof SessionsResolveParamsSchema>;
 export type SessionsPatchParams = Static<typeof SessionsPatchParamsSchema>;
 export type SessionsResetParams = Static<typeof SessionsResetParamsSchema>;

src/gateway/server-methods-list.ts

@@ -34,6 +34,7 @@ const BASE_METHODS = [
   "voicewake.get",
   "voicewake.set",
   "sessions.list",
+  "sessions.preview",
   "sessions.patch",
   "sessions.reset",
   "sessions.delete",

src/gateway/server-methods.ts

@@ -59,6 +59,7 @@ const READ_METHODS = new Set([
   "skills.status",
   "voicewake.get",
   "sessions.list",
+  "sessions.preview",
   "cron.list",
   "cron.status",
   "cron.runs",

src/gateway/server-methods/agent.ts

@@ -38,6 +38,7 @@ import {
 import { loadSessionEntry } from "../session-utils.js";
 import { formatForLog } from "../ws-log.js";
 import { resolveAssistantIdentity } from "../assistant-identity.js";
+import { resolveAssistantAvatarUrl } from "../control-ui.js";
 import { waitForAgentJob } from "./agent-job.js";
 import type { GatewayRequestHandlers } from "./types.js";
 
@@ -407,7 +408,13 @@ export const agentHandlers: GatewayRequestHandlers = {
     }
     const cfg = loadConfig();
     const identity = resolveAssistantIdentity({ cfg, agentId });
-    respond(true, identity, undefined);
+    const avatarValue =
+      resolveAssistantAvatarUrl({
+        avatar: identity.avatar,
+        agentId: identity.agentId,
+        basePath: cfg.gateway?.controlUi?.basePath,
+      }) ?? identity.avatar;
+    respond(true, { ...identity, avatar: avatarValue }, undefined);
   },
   "agent.wait": async ({ params, respond }) => {
     if (!validateAgentWaitParams(params)) {

src/gateway/server-methods/sessions.ts

@@ -6,6 +6,7 @@ import { stopSubagentsForRequester } from "../../auto-reply/reply/abort.js";
 import { clearSessionQueues } from "../../auto-reply/reply/queue.js";
 import { loadConfig } from "../../config/config.js";
 import {
+  loadSessionStore,
   snapshotSessionOrigin,
   resolveMainSessionKey,
   type SessionEntry,
@@ -19,6 +20,7 @@ import {
   validateSessionsDeleteParams,
   validateSessionsListParams,
   validateSessionsPatchParams,
+  validateSessionsPreviewParams,
   validateSessionsResetParams,
   validateSessionsResolveParams,
 } from "../protocol/index.js";
@@ -27,9 +29,12 @@ import {
   listSessionsFromStore,
   loadCombinedSessionStoreForGateway,
   loadSessionEntry,
+  readSessionPreviewItemsFromTranscript,
   resolveGatewaySessionStoreTarget,
   resolveSessionTranscriptCandidates,
   type SessionsPatchResult,
+  type SessionsPreviewEntry,
+  type SessionsPreviewResult,
 } from "../session-utils.js";
 import { applySessionsPatchToStore } from "../sessions-patch.js";
 import { resolveSessionKeyFromResolveParams } from "../sessions-resolve.js";
@@ -59,6 +64,74 @@ export const sessionsHandlers: GatewayRequestHandlers = {
     });
     respond(true, result, undefined);
   },
+  "sessions.preview": ({ params, respond }) => {
+    if (!validateSessionsPreviewParams(params)) {
+      respond(
+        false,
+        undefined,
+        errorShape(
+          ErrorCodes.INVALID_REQUEST,
+          `invalid sessions.preview params: ${formatValidationErrors(
+            validateSessionsPreviewParams.errors,
+          )}`,
+        ),
+      );
+      return;
+    }
+    const p = params as import("../protocol/index.js").SessionsPreviewParams;
+    const keysRaw = Array.isArray(p.keys) ? p.keys : [];
+    const keys = keysRaw
+      .map((key) => String(key ?? "").trim())
+      .filter(Boolean)
+      .slice(0, 64);
+    const limit =
+      typeof p.limit === "number" && Number.isFinite(p.limit) ? Math.max(1, p.limit) : 12;
+    const maxChars =
+      typeof p.maxChars === "number" && Number.isFinite(p.maxChars)
+        ? Math.max(20, p.maxChars)
+        : 240;
+
+    if (keys.length === 0) {
+      respond(true, { ts: Date.now(), previews: [] } satisfies SessionsPreviewResult, undefined);
+      return;
+    }
+
+    const cfg = loadConfig();
+    const storeCache = new Map<string, Record<string, SessionEntry>>();
+    const previews: SessionsPreviewEntry[] = [];
+
+    for (const key of keys) {
+      try {
+        const target = resolveGatewaySessionStoreTarget({ cfg, key });
+        const store = storeCache.get(target.storePath) ?? loadSessionStore(target.storePath);
+        storeCache.set(target.storePath, store);
+        const entry =
+          target.storeKeys.map((candidate) => store[candidate]).find(Boolean) ??
+          store[target.canonicalKey];
+        if (!entry?.sessionId) {
+          previews.push({ key, status: "missing", items: [] });
+          continue;
+        }
+        const items = readSessionPreviewItemsFromTranscript(
+          entry.sessionId,
+          target.storePath,
+          entry.sessionFile,
+          target.agentId,
+          limit,
+          maxChars,
+        );
+        previews.push({
+          key,
+          status: items.length > 0 ? "ok" : "empty",
+          items,
+        });
+      } catch {
+        previews.push({ key, status: "error", items: [] });
+      }
+    }
+
+    respond(true, { ts: Date.now(), previews } satisfies SessionsPreviewResult, undefined);
+  },
   "sessions.resolve": ({ params, respond }) => {
     if (!validateSessionsResolveParams(params)) {
       respond(

src/gateway/server.sessions.gateway-server-sessions-a.test.ts

@@ -103,6 +103,7 @@ describe("gateway server sessions", () => {
     expect((hello as unknown as { features?: { methods?: string[] } }).features?.methods).toEqual(
       expect.arrayContaining([
         "sessions.list",
+        "sessions.preview",
         "sessions.patch",
         "sessions.reset",
         "sessions.delete",
@@ -338,6 +339,53 @@ describe("gateway server sessions", () => {
     await server.close();
   });
 
+  test("sessions.preview returns transcript previews", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-sessions-preview-"));
+    const storePath = path.join(dir, "sessions.json");
+    testState.sessionStorePath = storePath;
+    const sessionId = "sess-preview";
+    const transcriptPath = path.join(dir, `${sessionId}.jsonl`);
+    const lines = [
+      JSON.stringify({ type: "session", version: 1, id: sessionId }),
+      JSON.stringify({ message: { role: "user", content: "Hello" } }),
+      JSON.stringify({ message: { role: "assistant", content: "Hi" } }),
+      JSON.stringify({
+        message: { role: "assistant", content: [{ type: "toolcall", name: "weather" }] },
+      }),
+      JSON.stringify({ message: { role: "assistant", content: "Forecast ready" } }),
+    ];
+    await fs.writeFile(transcriptPath, lines.join("\n"), "utf-8");
+
+    await writeSessionStore({
+      entries: {
+        main: {
+          sessionId,
+          updatedAt: Date.now(),
+        },
+      },
+    });
+
+    const { server, ws } = await startServerWithClient();
+    await connectOk(ws);
+    const preview = await rpcReq<{
+      previews: Array<{
+        key: string;
+        status: string;
+        items: Array<{ role: string; text: string }>;
+      }>;
+    }>(ws, "sessions.preview", { keys: ["main"], limit: 3, maxChars: 120 });
+
+    expect(preview.ok).toBe(true);
+    const entry = preview.payload?.previews[0];
+    expect(entry?.key).toBe("main");
+    expect(entry?.status).toBe("ok");
+    expect(entry?.items.map((item) => item.role)).toEqual(["assistant", "tool", "assistant"]);
+    expect(entry?.items[1]?.text).toContain("call weather");
+
+    ws.close();
+    await server.close();
+  });
+
   test("sessions.delete rejects main and aborts active runs", async () => {
     const dir = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-sessions-"));
     const storePath = path.join(dir, "sessions.json");

src/gateway/session-utils.fs.test.ts

@@ -5,6 +5,7 @@ import { afterEach, beforeEach, describe, expect, test } from "vitest";
 import {
   readFirstUserMessageFromTranscript,
   readLastMessagePreviewFromTranscript,
+  readSessionPreviewItemsFromTranscript,
 } from "./session-utils.fs.js";
 
 describe("readFirstUserMessageFromTranscript", () => {
@@ -341,3 +342,65 @@ describe("readLastMessagePreviewFromTranscript", () => {
     expect(result).toBe("Valid UTF-8: 你好世界 🌍");
   });
 });
+
+describe("readSessionPreviewItemsFromTranscript", () => {
+  let tmpDir: string;
+  let storePath: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "clawdbot-session-preview-test-"));
+    storePath = path.join(tmpDir, "sessions.json");
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  test("returns recent preview items with tool summary", () => {
+    const sessionId = "preview-session";
+    const transcriptPath = path.join(tmpDir, `${sessionId}.jsonl`);
+    const lines = [
+      JSON.stringify({ type: "session", version: 1, id: sessionId }),
+      JSON.stringify({ message: { role: "user", content: "Hello" } }),
+      JSON.stringify({ message: { role: "assistant", content: "Hi" } }),
+      JSON.stringify({
+        message: { role: "assistant", content: [{ type: "toolcall", name: "weather" }] },
+      }),
+      JSON.stringify({ message: { role: "assistant", content: "Forecast ready" } }),
+    ];
+    fs.writeFileSync(transcriptPath, lines.join("\n"), "utf-8");
+
+    const result = readSessionPreviewItemsFromTranscript(
+      sessionId,
+      storePath,
+      undefined,
+      undefined,
+      3,
+      120,
+    );
+
+    expect(result.map((item) => item.role)).toEqual(["assistant", "tool", "assistant"]);
+    expect(result[1]?.text).toContain("call weather");
+  });
+
+  test("truncates preview text to max chars", () => {
+    const sessionId = "preview-truncate";
+    const transcriptPath = path.join(tmpDir, `${sessionId}.jsonl`);
+    const longText = "a".repeat(60);
+    const lines = [JSON.stringify({ message: { role: "assistant", content: longText } })];
+    fs.writeFileSync(transcriptPath, lines.join("\n"), "utf-8");
+
+    const result = readSessionPreviewItemsFromTranscript(
+      sessionId,
+      storePath,
+      undefined,
+      undefined,
+      1,
+      24,
+    );
+
+    expect(result).toHaveLength(1);
+    expect(result[0]?.text.length).toBe(24);
+    expect(result[0]?.text.endsWith("...")).toBe(true);
+  });
+});

src/gateway/session-utils.fs.ts

@@ -3,6 +3,8 @@ import os from "node:os";
 import path from "node:path";
 
 import { resolveSessionTranscriptPath } from "../config/sessions.js";
+import { stripEnvelope } from "./chat-sanitize.js";
+import type { SessionPreviewItem } from "./session-utils.types.js";
 
 export function readSessionMessages(
   sessionId: string,
@@ -189,3 +191,202 @@ export function readLastMessagePreviewFromTranscript(
   }
   return null;
 }
+
+const PREVIEW_READ_SIZES = [64 * 1024, 256 * 1024, 1024 * 1024];
+const PREVIEW_MAX_LINES = 200;
+
+type TranscriptContentEntry = {
+  type?: string;
+  text?: string;
+  name?: string;
+};
+
+type TranscriptPreviewMessage = {
+  role?: string;
+  content?: string | TranscriptContentEntry[];
+  text?: string;
+  toolName?: string;
+  tool_name?: string;
+};
+
+function normalizeRole(role: string | undefined, isTool: boolean): SessionPreviewItem["role"] {
+  if (isTool) return "tool";
+  switch ((role ?? "").toLowerCase()) {
+    case "user":
+      return "user";
+    case "assistant":
+      return "assistant";
+    case "system":
+      return "system";
+    case "tool":
+      return "tool";
+    default:
+      return "other";
+  }
+}
+
+function truncatePreviewText(text: string, maxChars: number): string {
+  if (maxChars <= 0 || text.length <= maxChars) return text;
+  if (maxChars <= 3) return text.slice(0, maxChars);
+  return `${text.slice(0, maxChars - 3)}...`;
+}
+
+function extractPreviewText(message: TranscriptPreviewMessage): string | null {
+  if (typeof message.content === "string") {
+    const trimmed = message.content.trim();
+    return trimmed ? trimmed : null;
+  }
+  if (Array.isArray(message.content)) {
+    const parts = message.content
+      .map((entry) => (typeof entry?.text === "string" ? entry.text : ""))
+      .filter((text) => text.trim().length > 0);
+    if (parts.length > 0) {
+      return parts.join("\n").trim();
+    }
+  }
+  if (typeof message.text === "string") {
+    const trimmed = message.text.trim();
+    return trimmed ? trimmed : null;
+  }
+  return null;
+}
+
+function isToolCall(message: TranscriptPreviewMessage): boolean {
+  if (message.toolName || message.tool_name) return true;
+  if (!Array.isArray(message.content)) return false;
+  return message.content.some((entry) => {
+    if (entry?.name) return true;
+    const raw = typeof entry?.type === "string" ? entry.type.toLowerCase() : "";
+    return raw === "toolcall" || raw === "tool_call";
+  });
+}
+
+function extractToolNames(message: TranscriptPreviewMessage): string[] {
+  const names: string[] = [];
+  if (Array.isArray(message.content)) {
+    for (const entry of message.content) {
+      if (typeof entry?.name === "string" && entry.name.trim()) {
+        names.push(entry.name.trim());
+      }
+    }
+  }
+  const toolName = typeof message.toolName === "string" ? message.toolName : message.tool_name;
+  if (typeof toolName === "string" && toolName.trim()) {
+    names.push(toolName.trim());
+  }
+  return names;
+}
+
+function extractMediaSummary(message: TranscriptPreviewMessage): string | null {
+  if (!Array.isArray(message.content)) return null;
+  for (const entry of message.content) {
+    const raw = typeof entry?.type === "string" ? entry.type.trim().toLowerCase() : "";
+    if (!raw || raw === "text" || raw === "toolcall" || raw === "tool_call") continue;
+    return `[${raw}]`;
+  }
+  return null;
+}
+
+function buildPreviewItems(
+  messages: TranscriptPreviewMessage[],
+  maxItems: number,
+  maxChars: number,
+): SessionPreviewItem[] {
+  const items: SessionPreviewItem[] = [];
+  for (const message of messages) {
+    const toolCall = isToolCall(message);
+    const role = normalizeRole(message.role, toolCall);
+    let text = extractPreviewText(message);
+    if (!text) {
+      const toolNames = extractToolNames(message);
+      if (toolNames.length > 0) {
+        const shown = toolNames.slice(0, 2);
+        const overflow = toolNames.length - shown.length;
+        text = `call ${shown.join(", ")}`;
+        if (overflow > 0) text += ` +${overflow}`;
+      }
+    }
+    if (!text) {
+      text = extractMediaSummary(message);
+    }
+    if (!text) continue;
+    let trimmed = text.trim();
+    if (!trimmed) continue;
+    if (role === "user") {
+      trimmed = stripEnvelope(trimmed);
+    }
+    trimmed = truncatePreviewText(trimmed, maxChars);
+    items.push({ role, text: trimmed });
+  }
+
+  if (items.length <= maxItems) return items;
+  return items.slice(-maxItems);
+}
+
+function readRecentMessagesFromTranscript(
+  filePath: string,
+  maxMessages: number,
+  readBytes: number,
+): TranscriptPreviewMessage[] {
+  let fd: number | null = null;
+  try {
+    fd = fs.openSync(filePath, "r");
+    const stat = fs.fstatSync(fd);
+    const size = stat.size;
+    if (size === 0) return [];
+
+    const readStart = Math.max(0, size - readBytes);
+    const readLen = Math.min(size, readBytes);
+    const buf = Buffer.alloc(readLen);
+    fs.readSync(fd, buf, 0, readLen, readStart);
+
+    const chunk = buf.toString("utf-8");
+    const lines = chunk.split(/\r?\n/).filter((l) => l.trim());
+    const tailLines = lines.slice(-PREVIEW_MAX_LINES);
+
+    const collected: TranscriptPreviewMessage[] = [];
+    for (let i = tailLines.length - 1; i >= 0; i--) {
+      const line = tailLines[i];
+      try {
+        const parsed = JSON.parse(line);
+        const msg = parsed?.message as TranscriptPreviewMessage | undefined;
+        if (msg && typeof msg === "object") {
+          collected.push(msg);
+          if (collected.length >= maxMessages) break;
+        }
+      } catch {
+        // skip malformed lines
+      }
+    }
+    return collected.reverse();
+  } catch {
+    return [];
+  } finally {
+    if (fd !== null) fs.closeSync(fd);
+  }
+}
+
+export function readSessionPreviewItemsFromTranscript(
+  sessionId: string,
+  storePath: string | undefined,
+  sessionFile: string | undefined,
+  agentId: string | undefined,
+  maxItems: number,
+  maxChars: number,
+): SessionPreviewItem[] {
+  const candidates = resolveSessionTranscriptCandidates(sessionId, storePath, sessionFile, agentId);
+  const filePath = candidates.find((p) => fs.existsSync(p));
+  if (!filePath) return [];
+
+  const boundedItems = Math.max(1, Math.min(maxItems, 50));
+  const boundedChars = Math.max(20, Math.min(maxChars, 2000));
+
+  for (const readSize of PREVIEW_READ_SIZES) {
+    const messages = readRecentMessagesFromTranscript(filePath, boundedItems, readSize);
+    if (messages.length > 0 || readSize === PREVIEW_READ_SIZES[PREVIEW_READ_SIZES.length - 1]) {
+      return buildPreviewItems(messages, boundedItems, boundedChars);
+    }
+  }
+
+  return [];
+}

src/gateway/session-utils.ts

@@ -38,6 +38,7 @@ export {
   capArrayByJsonBytes,
   readFirstUserMessageFromTranscript,
   readLastMessagePreviewFromTranscript,
+  readSessionPreviewItemsFromTranscript,
   readSessionMessages,
   resolveSessionTranscriptCandidates,
 } from "./session-utils.fs.js";
@@ -47,6 +48,8 @@ export type {
   GatewaySessionsDefaults,
   SessionsListResult,
   SessionsPatchResult,
+  SessionsPreviewEntry,
+  SessionsPreviewResult,
 } from "./session-utils.types.js";
 
 const DERIVED_TITLE_MAX_LEN = 60;

src/gateway/session-utils.types.ts

@@ -55,6 +55,22 @@ export type GatewayAgentRow = {
   };
 };
 
+export type SessionPreviewItem = {
+  role: "user" | "assistant" | "tool" | "system" | "other";
+  text: string;
+};
+
+export type SessionsPreviewEntry = {
+  key: string;
+  status: "ok" | "empty" | "missing" | "error";
+  items: SessionPreviewItem[];
+};
+
+export type SessionsPreviewResult = {
+  ts: number;
+  previews: SessionsPreviewEntry[];
+};
+
 export type SessionsListResult = {
   ts: number;
   path: string;

src/hooks/bundled/session-memory/handler.ts

@@ -160,11 +160,9 @@ const saveSessionToMemory: HookHandler = async (event) => {
     await fs.writeFile(memoryFilePath, entry, "utf-8");
     console.log("[session-memory] Memory file written successfully");
 
-    // Send confirmation message to user with filename
+    // Log completion (but don't send user-visible confirmation - it's internal housekeeping)
     const relPath = memoryFilePath.replace(os.homedir(), "~");
-    const confirmMsg = `💾 Session context saved to memory before reset.\n📄 ${relPath}`;
-    event.messages.push(confirmMsg);
-    console.log("[session-memory] Confirmation message queued:", confirmMsg);
+    console.log(`[session-memory] Session context saved to ${relPath}`);
   } catch (err) {
     console.error(
       "[session-memory] Failed to save session memory:",

src/infra/exec-approvals.ts

@@ -465,6 +465,21 @@ function matchesPattern(pattern: string, target: string): boolean {
   return regex.test(normalizedTarget);
 }
 
+function resolveAllowlistCandidatePath(
+  resolution: CommandResolution | null,
+  cwd?: string,
+): string | undefined {
+  if (!resolution) return undefined;
+  if (resolution.resolvedPath) return resolution.resolvedPath;
+  const raw = resolution.rawExecutable?.trim();
+  if (!raw) return undefined;
+  const expanded = raw.startsWith("~") ? expandHome(raw) : raw;
+  if (!expanded.includes("/") && !expanded.includes("\\")) return undefined;
+  if (path.isAbsolute(expanded)) return expanded;
+  const base = cwd && cwd.trim() ? cwd.trim() : process.cwd();
+  return path.resolve(base, expanded);
+}
+
 export function matchAllowlist(
   entries: ExecAllowlistEntry[],
   resolution: CommandResolution | null,
@@ -519,7 +534,7 @@ function splitShellPipeline(command: string): { ok: boolean; reason?: string; se
       escaped = false;
       continue;
     }
-    if (!inSingle && ch === "\\") {
+    if (!inSingle && !inDouble && ch === "\\") {
       escaped = true;
       buf += ch;
       continue;
@@ -595,7 +610,7 @@ function tokenizeShellSegment(segment: string): string[] | null {
       escaped = false;
       continue;
     }
-    if (!inSingle && ch === "\\") {
+    if (!inSingle && !inDouble && ch === "\\") {
       escaped = true;
       continue;
     }
@@ -770,7 +785,12 @@ export function evaluateExecAllowlist(params: {
   }
   const allowSkills = params.autoAllowSkills === true && (params.skillBins?.size ?? 0) > 0;
   const allowlistSatisfied = params.analysis.segments.every((segment) => {
-    const match = matchAllowlist(params.allowlist, segment.resolution);
+    const candidatePath = resolveAllowlistCandidatePath(segment.resolution, params.cwd);
+    const candidateResolution =
+      candidatePath && segment.resolution
+        ? { ...segment.resolution, resolvedPath: candidatePath }
+        : segment.resolution;
+    const match = matchAllowlist(params.allowlist, candidateResolution);
     if (match) allowlistMatches.push(match);
     const safe = isSafeBinUsage({
       argv: segment.argv,

ui/src/styles/layout.css

@@ -37,6 +37,18 @@
   grid-template-columns: 0px minmax(0, 1fr);
 }
 
+.shell--onboarding {
+  grid-template-rows: 0 1fr;
+}
+
+.shell--onboarding .topbar {
+  display: none;
+}
+
+.shell--onboarding .content {
+  padding-top: 0;
+}
+
 .shell--chat-focus .content {
   padding-top: 0;
   gap: 0;