docs: clarify macOS node service IPC plan

CHANGELOG.md

@@ -2,30 +2,29 @@
 
 Docs: https://docs.clawd.bot
 
-## 2026.1.18-4
+## 2026.1.17-7
 
 ### Changes
+- Docs: outline planned macOS node-service IPC and app-owned exec flow.
 - Memory: add Gemini native embeddings support and auto-select providers when keys are available. (#1167) — thanks @gumadeiras.
 - Memory: add Gemini batch indexing and atomic reindexing for memory stores. (#1167) — thanks @gumadeiras.
+- CLI: show memory status/index across agents with richer source detail. (#1167) — thanks @gumadeiras.
+- Docs: refresh FAQ for node approvals, session resets, and memory provider defaults. (#1167) — thanks @gumadeiras.
+- Exec approvals: add `clawdbot approvals` CLI for viewing and updating gateway/node allowlists.
+- CLI: add `clawdbot service` gateway/node management and a `clawdbot node status` alias.
+- Status: show gateway + node service summaries in `clawdbot status` and `status --all`.
+- Control UI: add gateway/node target selector for exec approvals.
+- Docs: add approvals/service references and refresh node/control UI docs.
+- Dependencies: update core + plugin deps (grammy, vitest, openai, Microsoft agents hosting, etc.).
 - macOS: switch PeekabooBridge integration to the tagged Swift Package Manager release (no submodule).
 - macOS: stop syncing Peekaboo as a git submodule in postinstall.
 - Swabble: use the tagged Commander Swift package release.
 - CLI: add `clawdbot acp client` interactive ACP harness for debugging.
 - Plugins: route command detection/text chunking helpers through the plugin runtime and drop runtime exports from the SDK.
-- CLI: show memory status/index across agents with richer source detail. (#1167) — thanks @gumadeiras.
 - Memory: add native Gemini embeddings provider for memory search. (#1151) — thanks @gumadeiras.
-- Docs: refresh FAQ for node approvals, session resets, and memory provider defaults. (#1167) — thanks @gumadeiras.
+- Agents: add local docs path resolution and include docs/mirror/source/community pointers in the system prompt.
-
+- Slack: add HTTP webhook mode via Bolt HTTP receiver for Events API deployments. (#1143) — thanks @jdrhyne.
-### Fixes
+- Nodes: report core/ui versions in node list + presence; surface both in CLI + macOS UI.
-- Tools: clamp bash foreground duration using shared helpers. (#1167) — thanks @gumadeiras.
-- Auth profiles: keep auto-pinned preference while allowing rotation on failover; user pins stay locked. (#1138) — thanks @cheeeee.
-- macOS: avoid touching launchd in Remote over SSH so quitting the app no longer disables the remote gateway. (#1105)
-- Memory: index atomically so failed reindex preserves the previous memory database. (#1151) — thanks @gumadeiras.
-- Exec approvals: fix command token parsing for PATH resolution. (#1167) — thanks @gumadeiras.
-
-## 2026.1.18-3
-
-### Changes
 - Exec: add host/security/ask routing for gateway + node exec.
 - Exec: add `/exec` directive for per-session exec defaults (host/security/ask/node).
 - macOS: migrate exec approvals to `~/.clawdbot/exec-approvals.json` with per-agent allowlists and skill auto-allow toggle.
@@ -39,12 +38,20 @@ Docs: https://docs.clawd.bot
 - Docs: refresh exec/elevated/exec-approvals docs for the new flow. https://docs.clawd.bot/tools/exec-approvals
 - Docs: add node host CLI + update exec approvals/bridge protocol docs. https://docs.clawd.bot/cli/node
 - ACP: add experimental ACP support for IDE integrations (`clawdbot acp`). Thanks @visionik.
+- Tools: allow `sessions_spawn` to override thinking level for sub-agent runs.
+- Channels: unify thread/topic allowlist matching + command/mention gating helpers across core providers.
+- Models: add Qwen Portal OAuth provider support. (#1120) — thanks @mukhtharcm.
+- Memory: add `--verbose` logging for memory status + batch indexing details.
+- Memory: allow parallel OpenAI batch indexing jobs (default concurrency: 2).
+- macOS: add per-agent exec approvals with allowlists, skill CLI auto-allow, and settings UI.
+- Docs: add exec approvals guide and link from tools index. https://docs.clawd.bot/tools/exec-approvals
 
 ### Fixes
+- Tools: clamp bash foreground duration using shared helpers. (#1167) — thanks @gumadeiras.
 - Auth profiles: keep auto-pinned preference while allowing rotation on failover; user pins stay locked. (#1138) — thanks @cheeeee.
 - Agents: sanitize oversized image payloads before send and surface image-dimension errors.
 - macOS: avoid touching launchd in Remote over SSH so quitting the app no longer disables the remote gateway. (#1105)
-- Memory: index atomically so failed reindex preserves the previous memory database. (#1151)
+- Memory: index atomically so failed reindex preserves the previous memory database. (#1151) — thanks @gumadeiras.
 - Memory: avoid sqlite-vec unique constraint failures when reindexing duplicate chunk ids. (#1151)
 - Skills: improve remote bin probe logging with node labels + connectivity hints.
 - Exec approvals: enforce allowlist when ask is off; prefer raw command for node approvals/events.
@@ -52,11 +59,10 @@ Docs: https://docs.clawd.bot
 - Tools: return a companion-app-required message when node exec is requested with no paired node.
 - Streaming: emit assistant deltas for OpenAI-compatible SSE chunks. (#1147) — thanks @alauppe.
 - Model fallback: treat timeout aborts as failover while preserving user aborts. (#1137) — thanks @cheeeee.
-
-## 2026.1.18-2
-
-### Fixes
 - Tests: stabilize plugin SDK resolution and embedded agent timeouts.
+- Memory: apply OpenAI batch defaults even without explicit remote config.
+- macOS: bundle Textual resources in packaged app builds to avoid code block crashes. (#1006)
+- Discord: only emit slow listener warnings after 30s.
 
 ## 2026.1.17-6
 

docs/platforms/mac/xpc.md

@@ -7,6 +7,8 @@ read_when:
 
 **Current model:** there is **no local control socket** and no `clawdbot-mac` CLI. All agent actions go through the Gateway WebSocket and `node.invoke`. UI automation still uses PeekabooBridge.
 
+**Planned model:** add a local Unix socket between the **node service** and the **macOS app**. The app owns `system.run` (UI/TCC context); the node service forwards exec requests over IPC.
+
 ## Goals
 - Single GUI app instance that owns all TCC-facing work (notifications, screen recording, mic, speech, AppleScript).
 - A small surface for automation: Gateway + node commands, plus PeekabooBridge for UI automation.
@@ -17,6 +19,19 @@ read_when:
 - The app runs the Gateway (local mode) and connects to it as a node.
 - Agent actions are performed via `node.invoke` (e.g. `system.run`, `system.notify`, `canvas.*`).
 
+### Node service + app IPC (planned)
+- A headless node service connects to the Gateway bridge.
+- `system.run` requests are forwarded to the macOS app over a local Unix socket.
+- The app performs the exec in UI context, prompts if needed, and returns output.
+
+Diagram (SCI):
+```
+Agent -> Gateway -> Bridge -> Node Service (TS)
+                         |  IPC (UDS + token + HMAC + TTL)
+                         v
+                     Mac App (UI + TCC + system.run)
+```
+
 ### PeekabooBridge (UI automation)
 - UI automation uses a separate UNIX socket named `bridge.sock` and the PeekabooBridge JSON protocol.
 - Host preference order (client-side): Peekaboo.app → Claude.app → Clawdbot.app → local execution.
@@ -25,6 +40,7 @@ read_when:
 
 ### Mach/XPC
 - Not required for automation; `node.invoke` + PeekabooBridge cover current needs.
+- Planned IPC keeps Unix sockets (no XPC helper).
 
 ## Operational flows
 - Restart/rebuild: `SIGN_IDENTITY="Apple Development: <Developer Name> (<TEAMID>)" scripts/restart-mac.sh`
@@ -38,3 +54,4 @@ read_when:
 - PeekabooBridge: `PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1` (DEBUG-only) may allow same-UID callers for local development.
 - All communication remains local-only; no network sockets are exposed.
 - TCC prompts originate only from the GUI app bundle; keep the signed bundle ID stable across rebuilds.
+- Planned IPC hardening: socket mode `0600`, token, peer-UID checks, HMAC challenge/response, short TTL.

docs/platforms/macos.md

@@ -20,6 +20,10 @@ node.
 - Optionally hosts **PeekabooBridge** for UI automation.
 - Installs the global CLI (`clawdbot`) via npm/pnpm on request (bun not recommended for the Gateway runtime).
 
+Planned:
+- Run a headless **node service** locally (launchd).
+- Keep `system.run` in the app (UI/TCC context), with the node service forwarding via IPC.
+
 ## Local vs remote mode
 
 - **Local** (default): the app ensures a local Gateway is running via launchd.
@@ -54,6 +58,18 @@ The macOS app presents itself as a node. Common commands:
 
 The node reports a `permissions` map so agents can decide what’s allowed.
 
+Planned split:
+- Node service advertises the node surface to the Gateway.
+- macOS app performs `system.run` in UI context over IPC.
+
+Diagram (SCI):
+```
+Gateway -> Bridge -> Node Service (TS)
+                 |  IPC (UDS + token + HMAC + TTL)
+                 v
+             Mac App (UI + TCC + system.run)
+```
+
 ## Exec approvals (system.run)
 
 `system.run` is controlled by **Exec approvals** in the macOS app (Settings → Exec approvals).

docs/refactor/exec-host.md

@@ -30,6 +30,8 @@ read_when:
 - **Node identity:** use existing `nodeId`.
 - **Socket auth:** Unix socket + token (cross-platform); split later if needed.
 - **Node host state:** `~/.clawdbot/node.json` (node id + pairing token).
+- **macOS exec host:** run `system.run` inside the macOS app; node service forwards requests over local IPC.
+- **No XPC helper:** stick to Unix socket + token + peer checks.
 
 ## Key concepts
 ### Host
@@ -139,19 +141,30 @@ Notes:
 
 ## UI integration (macOS app)
 ### IPC
-- Unix socket at `~/.clawdbot/exec-approvals.sock`.
+- Unix socket at `~/.clawdbot/exec-approvals.sock` (0600).
-- Runner connects and sends an approval request; UI responds with a decision.
+- Token stored in `exec-approvals.json` (0600).
-- Token stored in `exec-approvals.json`.
+- Peer checks: same-UID only.
+- Challenge/response: nonce + HMAC(token, request-hash) to prevent replay.
+- Short TTL (e.g., 10s) + max payload + rate limit.
 
-### Ask flow
+### Ask flow (macOS app exec host)
-1) Runner receives `system.run` from gateway.
+1) Node service receives `system.run` from gateway.
-2) If ask required, runner connects to the socket and sends a prompt request.
+2) Node service connects to the local socket and sends the prompt/exec request.
-3) UI shows dialog; returns decision.
+3) App validates peer + token + HMAC + TTL, then shows dialog if needed.
-4) Runner enforces decision and proceeds.
+4) App executes the command in UI context and returns output.
+5) Node service returns output to gateway.
 
 If UI missing:
 - Apply `askFallback` (`deny|allowlist|full`).
 
+### Diagram (SCI)
+```
+Agent -> Gateway -> Bridge -> Node Service (TS)
+                         |  IPC (UDS + token + HMAC + TTL)
+                         v
+                     Mac App (UI + TCC + system.run)
+```
+
 ## Node identity + binding
 - Use existing `nodeId` from Bridge pairing.
 - Binding model:

docs/tools/exec-approvals.md

@@ -22,6 +22,10 @@ Exec approvals are enforced locally on the execution host:
 - **gateway host** → `clawdbot` process on the gateway machine
 - **node host** → node runner (macOS companion app or headless node host)
 
+Planned macOS split:
+- **node service** forwards `system.run` to the **macOS app** over local IPC.
+- **macOS app** enforces approvals + executes the command in UI context.
+
 ## Settings and storage
 
 Approvals live in a local JSON file on the execution host:
@@ -128,6 +132,19 @@ Actions:
 - **Always allow** → add to allowlist + run
 - **Deny** → block
 
+### macOS IPC flow (planned)
+```
+Gateway -> Bridge -> Node Service (TS)
+                    |  IPC (UDS + token + HMAC + TTL)
+                    v
+                Mac App (UI + approvals + system.run)
+```
+
+Security notes:
+- Unix socket mode `0600`, token stored in `exec-approvals.json`.
+- Same-UID peer check.
+- Challenge/response (nonce + HMAC token + request hash) + short TTL.
+
 ## System events
 
 Exec lifecycle is surfaced as system messages: