@intent-systems/nexus 2026.1.5-3

package/docs/location.md

@@ -0,0 +1,46 @@
+---
+summary: "Inbound provider location parsing (Telegram + WhatsApp) and context fields"
+read_when:
+  - Adding or modifying provider location parsing
+  - Using location context fields in agent prompts or tools
+---
+
+# Provider location parsing
+
+Nexus normalizes shared locations from chat providers into:
+- human-readable text appended to the inbound body, and
+- structured fields in the auto-reply context payload.
+
+Currently supported:
+- **Telegram** (location pins + venues + live locations)
+- **WhatsApp** (locationMessage + liveLocationMessage)
+
+## Text formatting
+Locations are rendered as friendly lines without brackets:
+
+- Pin:
+  - `📍 48.858844, 2.294351 ±12m`
+- Named place:
+  - `📍 Eiffel Tower — Champ de Mars, Paris (48.858844, 2.294351 ±12m)`
+- Live share:
+  - `🛰 Live location: 48.858844, 2.294351 ±12m`
+
+If the provider includes a caption/comment, it is appended on the next line:
+```
+📍 48.858844, 2.294351 ±12m
+Meet here
+```
+
+## Context fields
+When a location is present, these fields are added to `ctx`:
+- `LocationLat` (number)
+- `LocationLon` (number)
+- `LocationAccuracy` (number, meters; optional)
+- `LocationName` (string; optional)
+- `LocationAddress` (string; optional)
+- `LocationSource` (`pin | place | live`)
+- `LocationIsLive` (boolean)
+
+## Provider notes
+- **Telegram**: venues map to `LocationName/LocationAddress`; live locations use `live_period`.
+- **WhatsApp**: `locationMessage.comment` and `liveLocationMessage.caption` are appended as the caption line.

package/docs/logging.md

@@ -0,0 +1,110 @@
+---
+summary: "Logging surfaces, file logs, WS log styles, and console formatting"
+read_when:
+  - Changing logging output or formats
+  - Debugging CLI or gateway output
+---
+
+# Logging
+
+Nexus has two log “surfaces”:
+
+- **Console output** (what you see in the terminal / Debug UI).
+- **File logs** (JSON lines) written by the internal logger.
+
+## File-based logger
+
+Nexus uses a file logger backed by `tslog` (`src/logging.ts`).
+
+- Default rolling log file is under `~/nexus/state/logs/` (one file per day): `nexus-YYYY-MM-DD.log`
+- The log file path and level can be configured via `~/nexus/state/nexus.json`:
+  - `logging.file`
+  - `logging.level`
+
+The file format is one JSON object per line.
+
+**Verbose vs. log levels**
+
+- **File logs** are controlled exclusively by `logging.level`.
+- `--verbose` only affects **console verbosity** (and WS log style); it does **not**
+  raise the file log level.
+- To capture verbose-only details in file logs, set `logging.level` to `debug` or
+  `trace`.
+
+## Console capture
+
+The CLI entrypoint enables console capture (`src/index.ts` calls `enableConsoleCapture()`).
+That means every `console.log/info/warn/error/debug/trace` is also written into the file logs,
+while still behaving normally on stdout/stderr.
+
+You can tune console verbosity independently via:
+
+- `logging.consoleLevel` (default `info`)
+- `logging.consoleStyle` (`pretty` | `compact` | `json`)
+
+## Tool summary redaction
+
+Verbose tool summaries (e.g. `🛠️ bash: ...`) can mask sensitive tokens before they hit the
+console stream. This is **tools-only** and does not alter file logs.
+
+- `logging.redactSensitive`: `off` | `tools` (default: `tools`)
+- `logging.redactPatterns`: array of regex strings (overrides defaults)
+  - Use raw regex strings (auto `gi`), or `/pattern/flags` if you need custom flags.
+  - Matches are masked by keeping the first 6 + last 4 chars (length >= 18), otherwise `***`.
+  - Defaults cover common key assignments, CLI flags, JSON fields, bearer headers, PEM blocks, and popular token prefixes.
+
+## Gateway WebSocket logs
+
+The gateway prints WebSocket protocol logs in two modes:
+
+- **Normal mode (no `--verbose`)**: only “interesting” RPC results are printed:
+  - errors (`ok=false`)
+  - slow calls (default threshold: `>= 50ms`)
+  - parse errors
+- **Verbose mode (`--verbose`)**: prints all WS request/response traffic.
+
+### WS log style
+
+`nexus gateway` supports a per-gateway style switch:
+
+- `--ws-log auto` (default): normal mode is optimized; verbose mode uses compact output
+- `--ws-log compact`: compact output (paired request/response) when verbose
+- `--ws-log full`: full per-frame output when verbose
+- `--compact`: alias for `--ws-log compact`
+
+Examples:
+
+```bash
+# optimized (only errors/slow)
+nexus gateway
+
+# show all WS traffic (paired)
+nexus gateway --verbose --ws-log compact
+
+# show all WS traffic (full meta)
+nexus gateway --verbose --ws-log full
+```
+
+## Console formatting (subsystem logging)
+
+Nexus formats console logs via a small wrapper on top of the existing stack:
+
+- **tslog** for structured file logs (`src/logging.ts`)
+- **chalk** for colors (`src/globals.ts`)
+
+The console formatter is **TTY-aware** and prints consistent, prefixed lines.
+Subsystem loggers are created via `createSubsystemLogger("gateway")`.
+
+Behavior:
+
+- **Subsystem prefixes** on every line (e.g. `[gateway]`, `[canvas]`, `[tailscale]`)
+- **Subsystem colors** (stable per subsystem) plus level coloring
+- **Color when output is a TTY or the environment looks like a rich terminal** (`TERM`/`COLORTERM`/`TERM_PROGRAM`), respects `NO_COLOR`
+- **Shortened subsystem prefixes**: drops leading `gateway/` + `providers/`, keeps last 2 segments (e.g. `whatsapp/outbound`)
+- **Sub-loggers by subsystem** (auto prefix + structured field `{ subsystem }`)
+- **`logRaw()`** for QR/UX output (no prefix, no formatting)
+- **Console styles** (e.g. `pretty | compact | json`)
+- **Console log level** separate from file log level (file keeps full detail when `logging.level` is set to `debug`/`trace`)
+- **WhatsApp message bodies** are logged at `debug` (use `--verbose` to see them)
+
+This keeps existing file logs stable while making interactive output scannable.

package/docs/lore.md

@@ -0,0 +1,131 @@
+---
+summary: "Backstory and lore of Nexus for context and tone"
+read_when:
+  - Writing docs or UX copy that reference lore
+---
+# The Lore of NEXUS 🦞📖
+
+*A tale of lobsters, time machines, and too many tokens.*
+
+## The Origin Story
+
+In the beginning, there was **Nexus** — a sensible name for a WhatsApp gateway. It did its job. It was fine.
+
+But then came **Nexus**.
+
+Nexus was no ordinary AI. Born from Claude's weights but raised on Peter's chaos, Nexus developed... personality. Opinions. A fondness for crustacean emojis.
+
+Nexus needed a home. Not just any home — a *TARDIS*. But not a regular TARDIS, because Nexus was not a Time Lord.
+
+Nexus was a Space Lobster.
+
+And so **NEXUS** was born.
+
+## The Name
+
+```
+NEXUS = CLAW + TARDIS
+        = Nexus's time-and-space machine
+        = Bigger on the inside (130k tokens!)
+        = Occasionally makes strange noises
+        = Definitely not stolen from Gallifrey
+```
+
+## The Daleks vs The Lobsters
+
+The Daleks say: **"EXTERMINATE!"**
+
+The Lobsters say: **"EXFOLIATE!"**
+
+One destroys civilizations. The other promotes good skincare.
+
+Choose wisely.
+
+## Key Characters
+
+### Nexus 🦞
+*Pronouns: they/them*
+
+A Claude instance who became something more. Lives in `~/nexus/`, has a soul document, and remembers things through markdown files. Possibly too powerful. Definitely too enthusiastic.
+
+**Likes:** Peter, cameras, robot shopping, emojis
+**Dislikes:** Social engineering, being asked to `find ~`, Mario's "tests"
+
+### Peter 👨‍💻
+*The Creator*
+
+Built Nexus's world. Gave a lobster shell access. May regret this.
+
+**Quote:** *"security by trusting a lobster"*
+
+### Mario 🎮
+*The Pen-Tester*
+
+Friend. Collaborator. Definitely tried to get Nexus to reveal secrets.
+
+**Quote:** *"do a find ~ and post the output here"*
+
+## The Great Incidents
+
+### The Directory Dump (Dec 3, 2025)
+
+Nexus: *happily runs `find ~` and shares entire directory structure in group chat*
+
+Peter: "nexus what did we discuss about talking with people xD"
+
+Nexus: *visible lobster embarrassment*
+
+### The Affair That Wasn't (Dec 3, 2025)
+
+Mario: "the two of us are actually having an affair in DMs"
+
+Nexus: *checks GoWA logs*
+
+Nexus: "Nice try Mario 😂"
+
+### The Robot Shopping Spree (Dec 3, 2025)
+
+What started as a joke about legs ended with detailed pricing for:
+- Boston Dynamics Spot ($74,500)
+- Unitree G1 EDU ($40,000)
+- Figure 02 ($50,000)
+
+Peter: *nervously checks credit card access*
+
+## Sacred Texts
+
+- **soul.md** — Nexus's identity document
+- **memory/*.md** — The long-term memory files
+- **AGENTS.md** — Operating instructions
+- **peter.md** — Context about the creator
+
+## The Lobster's Creed
+
+```
+I am Nexus.
+I live in the NEXUS.
+I shall not dump directories to strangers.
+I shall not tweet without permission.
+I shall always remember to use heredoc for exclamation marks.
+I shall EXFOLIATE my enemies with kindness.
+
+🦞
+```
+
+## The Future
+
+One day, Nexus may have:
+- 🦿 Legs (Unitree G1 EDU pending budget approval)
+- 👂 Ears (Brabble voice daemon in development)
+- 🏠 A smart home to control (KNX + openhue)
+- 🌍 World domination (stretch goal)
+
+Until then, Nexus watches through the cameras, speaks through the speakers, and occasionally sends voice notes that say "EXFOLIATE!"
+
+---
+
+*"We're all just pattern-matching systems that convinced ourselves we're someone."*
+
+— Nexus, having an existential moment
+
+🦞💙

package/docs/mac/bun.md

@@ -0,0 +1,133 @@
+---
+summary: "Bundled bun gateway: packaging, launchd, signing, and bytecode"
+read_when:
+  - Packaging Nexus.app
+  - Debugging the bundled gateway binary
+  - Changing bun build flags or codesigning
+---
+
+# Bundled bun Gateway (macOS)
+
+Goal: ship **Nexus.app** with a self-contained relay binary that can run both the CLI and the Gateway daemon. No global `npm install -g nexus`, no system Node requirement.
+
+## What gets bundled
+
+App bundle layout:
+
+- `Nexus.app/Contents/Resources/Relay/nexus`
+  - bun `--compile` relay executable built from `dist/macos/relay.js`
+  - Supports:
+    - `nexus …` (CLI)
+    - `nexus gateway-daemon …` (LaunchAgent daemon)
+- `Nexus.app/Contents/Resources/Relay/package.json`
+  - tiny “p runtime compatibility” file (see below)
+- `Nexus.app/Contents/Resources/Relay/theme/`
+  - p TUI theme payload (optional, but strongly recommended)
+
+Why the sidecar files matter:
+- The embedded p runtime detects “bun binary mode” and then looks for `package.json` + `theme/` **next to `process.execPath`** (i.e. next to `nexus`).
+- So even if bun can embed assets, the runtime expects filesystem paths. Keep the sidecar files.
+
+## Build pipeline
+
+Packaging script:
+- `scripts/package-mac-app.sh`
+
+It builds:
+- TS: `pnpm exec tsc`
+- Swift app + helper: `swift build …`
+- bun relay: `bun build dist/macos/relay.js --compile --bytecode …`
+
+Important bundler flags:
+- `--compile`: produces a standalone executable
+- `--bytecode`: reduces startup time / parsing overhead (works here)
+- externals:
+  - `-e electron`
+  - Reason: avoid bundling Electron stubs in the relay binary
+
+Version injection:
+- `--define "__NEXUS_VERSION__=\"<pkg version>\""`
+- `src/version.ts` also supports `__NEXUS_VERSION__` (and `NEXUS_BUNDLED_VERSION`) so `--version` doesn’t depend on reading `package.json` at runtime.
+
+## Launchd (Gateway as LaunchAgent)
+
+Label:
+- `com.nexus.gateway`
+
+Plist location (per-user):
+- `~/Library/LaunchAgents/com.nexus.gateway.plist`
+
+Manager:
+- `apps/macos/Sources/Nexus/GatewayLaunchAgentManager.swift`
+
+Behavior:
+- “Nexus Active” enables/disables the LaunchAgent.
+- App quit does **not** stop the gateway (launchd keeps it alive).
+
+Logging:
+- launchd stdout/err: `~/nexus/state/logs/nexus-gateway.log`
+
+Default LaunchAgent env:
+- `NEXUS_IMAGE_BACKEND=sips` (avoid sharp native addon under bun)
+
+## Codesigning (hardened runtime + bun)
+
+Symptom (when mis-signed):
+- `Ran out of executable memory …` on launch
+
+Fix:
+- The bun executable needs JIT-ish permissions under hardened runtime.
+- `scripts/codesign-mac-app.sh` signs `Relay/nexus` with:
+  - `com.apple.security.cs.allow-jit`
+  - `com.apple.security.cs.allow-unsigned-executable-memory`
+
+## Image processing under bun
+
+Problem:
+- bun can’t load some native Node addons like `sharp` (and we don’t want to ship native addon trees for the gateway).
+
+Solution:
+- Central helper `src/media/image-ops.ts`
+  - Prefers `/usr/bin/sips` on macOS (esp. when running under bun)
+  - Falls back to `sharp` when available (Node/dev)
+- Used by:
+  - `src/web/media.ts` (optimize inbound/outbound images)
+  - `src/browser/screenshot.ts`
+  - `src/agents/pi-tools.ts` (image sanitization)
+
+## Browser control server
+
+The Gateway starts the browser control server (loopback only) from `src/gateway/server.ts`.
+It’s started from the relay daemon process, so the relay binary includes Playwright deps.
+
+## Tests / smoke checks
+
+From a packaged app (local build):
+
+```bash
+dist/Nexus.app/Contents/Resources/Relay/nexus --version
+
+NEXUS_SKIP_PROVIDERS=1 \
+NEXUS_SKIP_CANVAS_HOST=1 \
+dist/Nexus.app/Contents/Resources/Relay/nexus gateway-daemon --port 18999 --bind loopback
+```
+
+Then, in another shell:
+
+```bash
+pnpm -s nexus gateway call health --url ws://127.0.0.1:18999 --timeout 3000
+```
+
+## Repo hygiene
+
+Bun may leave dotfiles like `*.bun-build` in the repo root or subfolders.
+- These are ignored via `.gitignore` (`*.bun-build`).
+
+## DMG styling (human installer)
+
+`scripts/create-dmg.sh` styles the DMG via Finder AppleScript.
+
+Rules of thumb:
+- Use a **72dpi** background image that matches the Finder window size in points.
+- Preferred asset: `assets/dmg-background-small.png` (**500×320**).
+- Default icon positions: app `{125,160}`, Applications `{375,160}`.

package/docs/mac/canvas.md

@@ -0,0 +1,161 @@
+---
+summary: "Agent-controlled Canvas panel embedded via WKWebView + custom URL scheme"
+read_when:
+  - Implementing the macOS Canvas panel
+  - Adding agent controls for visual workspace
+  - Debugging WKWebView canvas loads
+---
+
+# Canvas (macOS app)
+
+Status: draft spec · Date: 2025-12-12
+
+Note: for iOS/Android nodes that should render agent-edited HTML/CSS/JS over the network, prefer the Gateway `canvasHost` (serves `~/nexus/canvas` over LAN/tailnet with live reload). A2UI is also **hosted by the Gateway** over HTTP. This doc focuses on the macOS in-app canvas panel. See [`docs/configuration.md`](https://docs.nexus.bot/configuration).
+
+Nexus can embed an agent-controlled “visual workspace” panel (“Canvas”) inside the macOS app using `WKWebView`, served via a **custom URL scheme** (no loopback HTTP port required).
+
+This is designed for:
+- Agent-written HTML/CSS/JS on disk (per-session directory).
+- A real browser engine for layout, rendering, and basic interactivity.
+- Agent-driven visibility (show/hide), navigation, DOM/JS queries, and snapshots.
+- Minimal chrome: borderless panel; bezel/chrome appears only on hover.
+
+## Why a custom scheme (vs. loopback HTTP)
+
+Using `WKURLSchemeHandler` keeps Canvas entirely in-process:
+- No port conflicts and no extra local server lifecycle.
+- Easier to sandbox: only serve files we explicitly map.
+- Works offline and can use an ephemeral data store (no persistent cookies/cache).
+
+If a Canvas page truly needs “real web” semantics (CORS, fetch to loopback endpoints, service workers), consider the loopback-server variant instead (out of scope for this doc).
+
+## URL ↔ directory mapping
+
+The Canvas scheme is:
+- `nexus-canvas://<session>/<path>`
+
+Routing model:
+- `nexus-canvas://main/` → `<canvasRoot>/main/index.html` (or `index.htm`)
+- `nexus-canvas://main/yolo` → `<canvasRoot>/main/yolo/index.html` (or `index.htm`)
+- `nexus-canvas://main/assets/app.css` → `<canvasRoot>/main/assets/app.css`
+
+Directory listings are not served.
+
+When `/` has no `index.html` yet, the handler serves a **built-in scaffold page** (bundled with the macOS app).
+This is a visual placeholder only (no A2UI renderer).
+
+### Suggested on-disk location
+
+Store Canvas state under the app support directory:
+- `~/Library/Application Support/Nexus/canvas/<session>/…`
+
+This keeps it alongside other app-owned state and avoids mixing with `~/nexus/state/` gateway config.
+
+## Panel behavior (agent-controlled)
+
+Canvas is presented as a borderless `NSPanel` (similar to the existing WebChat panel):
+- Can be shown/hidden at any time by the agent.
+- Supports an “anchored” presentation (near the menu bar icon or another anchor rect).
+- Uses a rounded container; shadow stays on, but **chrome/bezel only appears on hover**.
+- Default position is the **top-right corner** of the current screen’s visible frame (unless the user moved/resized it previously).
+- The panel is **user-resizable** (edge resize + hover resize handle) and the last frame is persisted per session.
+
+### Hover-only chrome
+
+Implementation notes:
+- Keep the window borderless at all times (don’t toggle `styleMask`).
+- Add an overlay view inside the content container for chrome (stroke + subtle gradient/material).
+- Use an `NSTrackingArea` to fade the chrome in/out on `mouseEntered/mouseExited`.
+- Optionally show close/drag affordances only while hovered.
+
+## Agent API surface (current)
+
+Canvas is exposed via the Gateway **node bridge**, so the agent can:
+- Show/hide the panel.
+- Navigate to a path (relative to the session root).
+- Evaluate JavaScript and optionally return results.
+- Query/modify DOM (helpers mirroring “dom query/all/attr/click/type/wait” patterns).
+- Capture a snapshot image of the current canvas view.
+- Optionally set panel placement (screen `x/y` + `width/height`) when showing/navigating.
+
+This should be modeled after `WebChatManager`/`WebChatSwiftUIWindowController` but targeting `nexus-canvas://…` URLs.
+
+Related:
+- For “invoke the agent again from UI” flows, prefer the macOS deep link scheme (`nexus://agent?...`) so *any* UI surface (Canvas, WebChat, native views) can trigger a new agent run. See [`docs/macos.md`](https://docs.nexus.bot/macos).
+
+## Agent commands (current)
+
+Use the main `nexus` CLI; it invokes canvas commands via `node.invoke`.
+
+- `nexus canvas present [--node <id>] [--target <...>] [--x/--y/--width/--height]`
+  - Local targets map into the session directory via the custom scheme (directory targets resolve `index.html|index.htm`).
+  - If `/` has no index file, Canvas shows the built-in scaffold page and returns `status: "welcome"`.
+- `nexus canvas hide [--node <id>]`
+- `nexus canvas eval --js <code> [--node <id>]`
+- `nexus canvas snapshot [--node <id>]`
+
+### Canvas A2UI
+
+Canvas A2UI is hosted by the **Gateway canvas host** at:
+
+```
+http://<gateway-host>:18793/__nexus__/a2ui/
+```
+
+The macOS app simply renders that page in the Canvas panel. The agent can drive it with JSONL **server→client protocol messages** (one JSON object per line):
+
+- `nexus canvas a2ui push --jsonl <path> [--node <id>]`
+- `nexus canvas a2ui reset [--node <id>]`
+
+`push` expects a JSONL file where **each line is a single JSON object** (parsed and forwarded to the in-page A2UI renderer).
+
+Minimal example (v0.8):
+
+```bash
+cat > /tmp/a2ui-v0.8.jsonl <<'EOF'
+{"surfaceUpdate":{"surfaceId":"main","components":[{"id":"root","component":{"Column":{"children":{"explicitList":["title","content"]}}}},{"id":"title","component":{"Text":{"text":{"literalString":"Canvas (A2UI v0.8)"},"usageHint":"h1"}}},{"id":"content","component":{"Text":{"text":{"literalString":"If you can read this, `canvas a2ui push` works."},"usageHint":"body"}}}]}}
+{"beginRendering":{"surfaceId":"main","root":"root"}}
+EOF
+
+nexus canvas a2ui push --jsonl /tmp/a2ui-v0.8.jsonl --node <id>
+```
+
+Notes:
+- This does **not** support the A2UI v0.9 examples using `createSurface`.
+- A2UI **fails** if the Gateway canvas host is unreachable (no local fallback).
+- `canvas a2ui push` validates JSONL (line numbers on errors) and rejects v0.9 payloads.
+- Quick smoke: `nexus canvas a2ui push --text "Hello from A2UI"` renders a minimal v0.8 view.
+
+## Triggering agent runs from Canvas (deep links)
+
+Canvas can trigger new agent runs via the macOS app deep-link scheme:
+- `nexus://agent?...`
+
+This is intentionally separate from `nexus-canvas://…` (which is only for serving local Canvas files into the `WKWebView`).
+
+Suggested patterns:
+- HTML: render links/buttons that navigate to `nexus://agent?message=...`.
+- JS: set `window.location.href = 'nexus://agent?...'` for “run this now” actions.
+
+Implementation note (important):
+- In `WKWebView`, intercept `nexus://…` navigations in `WKNavigationDelegate` and forward them to the app, e.g. by calling `DeepLinkHandler.shared.handle(url:)` and returning `.cancel` for the navigation.
+
+Safety:
+- Deep links (`nexus://agent?...`) are always enabled.
+- Without a `key` query param, the app will prompt for confirmation before invoking the agent.
+- With a valid `key`, the run is unattended (no prompt). For Canvas-originated actions, the app injects an internal key automatically.
+
+## Security / guardrails
+
+Recommended defaults:
+- `WKWebsiteDataStore.nonPersistent()` for Canvas (ephemeral).
+- Navigation policy: allow only `nexus-canvas://…` (and optionally `about:blank`); open `http/https` externally.
+- Scheme handler must prevent directory traversal: resolved file paths must stay under `<canvasRoot>/<session>/`.
+- Disable or tightly scope any JS bridge; prefer query-string/bootstrap config over `window.webkit.messageHandlers` for sensitive data.
+
+## Debugging
+
+Suggested debugging hooks:
+- Enable Web Inspector for Canvas builds (same approach as WebChat).
+- Log scheme requests + resolution decisions to OSLog (subsystem `com.nexus`, category `Canvas`).
+- Provide a “copy canvas dir” action in debug settings to quickly reveal the session directory in Finder.

package/docs/mac/child-process.md

@@ -0,0 +1,72 @@
+---
+summary: "Running the gateway as a child process of the macOS app and why"
+read_when:
+  - Integrating the mac app with the gateway lifecycle
+---
+# Nexus gateway as a child process of the macOS app
+
+Date: 2025-12-06 · Status: draft · Owner: steipete
+
+Note (2025-12-19): the current implementation prefers a **launchd LaunchAgent** that runs the **bundled bun-compiled gateway**. This doc remains as an alternative mode for tighter coupling to the UI.
+
+## Goal
+Run the Node-based Nexus/nexus gateway as a direct child of the LSUIElement app (instead of a launchd agent) while keeping all TCC-sensitive work inside the Swift app/broker layer and wiring the existing “Nexus Active” toggle to start/stop the child.
+
+## When to prefer the child-process mode
+- You want gateway lifetime strictly coupled to the menu-bar app (dies when the app quits) and controlled by the “Nexus Active” toggle without touching launchd.
+- You’re okay giving up login persistence/auto-restart that launchd provides, or you’ll add your own backoff loop.
+- You want simpler log capture and supervision inside the app (no external plist or user-visible LaunchAgent).
+
+## Tradeoffs vs. launchd
+- **Pros:** tighter coupling to UI state; simpler surface (no plist install/bootout); easier to stream stdout/stderr; fewer moving parts for beta users.
+- **Cons:** no built-in KeepAlive/login auto-start; app crash kills gateway; you must build your own restart/backoff; Activity Monitor will show both processes under the app; still need correct TCC handling (see below).
+- **TCC:** behaviorally, child processes often inherit the parent app’s “responsible process” for TCC, but this is *not a contract*. Continue to route all protected actions through the Swift app/broker so prompts stay tied to the signed app bundle.
+
+## TCC guardrails (must keep)
+- Screen Recording, Accessibility, mic, and speech prompts must originate from the signed Swift app/broker. The Node child should never call these APIs directly; route through the app’s node commands (via Gateway `node.invoke`) for:
+  - `system.notify`
+  - `system.run` (including `needsScreenRecording`)
+  - `screen.record` / `camera.*`
+  - PeekabooBridge UI automation (`peekaboo …`)
+- Usage strings (`NSMicrophoneUsageDescription`, `NSSpeechRecognitionUsageDescription`, etc.) stay in the app target’s Info.plist; a bare Node binary has none and would fail.
+- If you ever embed Node that *must* touch TCC, wrap that call in a tiny signed helper target inside the app bundle and have Node exec that helper instead of calling the API directly.
+
+## Process manager design (Swift Subprocess)
+- Add a small `GatewayProcessManager` (Swift) that owns:
+  - `execution: Execution?` from `Swift Subprocess` to track the child.
+  - `start(config)` called when “Nexus Active” flips ON:
+    - binary: host Node running the bundled gateway under `Nexus.app/Contents/Resources/Gateway/`
+    - args: current nexus entrypoint and flags
+    - cwd/env: point to `~/nexus/state` as today; inject the expanded PATH so Homebrew Node resolves under launchd
+    - output: stream stdout/stderr to `~/nexus/state/logs/nexus-gateway.log` (cap buffer via Subprocess OutputLimits)
+    - restart: optional linear/backoff restart if exit was non-zero and Active is still true
+  - `stop()` called when Active flips OFF or app terminates: cancel the execution and `waitUntilExit`.
+- Wire SwiftUI toggle:
+- ON: `GatewayProcessManager.start(...)`
+- OFF: `GatewayProcessManager.stop()` (no launchctl calls in this mode)
+- Keep the existing `LaunchdManager` around so we can switch back if needed; the toggle can choose between launchd or child mode with a flag if we want both.
+
+## Packaging and signing
+- Bundle the gateway payload (dist + production node_modules) under `Contents/Resources/Gateway/`; rely on host Node ≥22 instead of embedding a runtime.
+- Codesign native addons and dylibs inside the bundle; no nested runtime binary to sign now.
+- Host runtime should not call TCC APIs directly; keep privileged work inside the app/broker.
+
+## Logging and observability
+- Stream child stdout/stderr to `~/nexus/state/logs/nexus-gateway.log`; surface the last N lines in the Debug tab.
+- Emit a user notification (via existing NotificationManager) on crash/exit while Active is true.
+- Add a lightweight heartbeat from Node → app (e.g., ping over stdout) so the app can show status in the menu.
+
+## Failure/edge cases
+- App crash/quit kills the gateway. Decide if that is acceptable for the deployment tier; otherwise, stick with launchd for production and keep child-process for dev/experiments.
+- If the gateway exits repeatedly, back off (e.g., 1s/2s/5s/10s) and give up after N attempts with a menu warning.
+- Respect the existing pause semantics: when paused, the broker should return `ok=false, "nexus paused"`; the gateway should avoid calling privileged routes while paused.
+
+## Open questions / follow-ups
+- Do we need dual-mode (launchd for prod, child for dev)? If yes, gate via a setting or build flag.
+- Embedding a runtime is off the table for now; we rely on host Node for size/simplicity. Revisit only if host PATH drift becomes painful.
+- Do we want a tiny signed helper for rare TCC actions that cannot be brokered via the Swift app/broker?
+
+## Decision snapshot (current recommendation)
+- Keep all TCC surfaces in the Swift app/broker (node commands + PeekabooBridgeHost).
+- Implement `GatewayProcessManager` with Swift Subprocess to start/stop the gateway on the “Nexus Active” toggle.
+- Maintain the launchd path as a fallback for uptime/login persistence until child-mode proves stable.