loudmouth-ai 0.1.0

package/docs/gateway/authentication.md

@@ -0,0 +1,143 @@
+---
+summary: "Model authentication: OAuth, API keys, and setup-token"
+read_when:
+  - Debugging model auth or OAuth expiry
+  - Documenting authentication or credential storage
+---
+# Authentication
+
+Clawdbot supports OAuth and API keys for model providers. For Anthropic
+accounts, we recommend using an **API key**. For Claude subscription access,
+use the long‑lived token created by `claude setup-token`.
+
+See [/concepts/oauth](/concepts/oauth) for the full OAuth flow and storage
+layout.
+
+## Recommended Anthropic setup (API key)
+
+If you’re using Anthropic directly, use an API key.
+
+1) Create an API key in the Anthropic Console.
+2) Put it on the **gateway host** (the machine running `clawdbot gateway`).
+
+```bash
+export ANTHROPIC_API_KEY="..."
+clawdbot models status
+```
+
+3) If the Gateway runs under systemd/launchd, prefer putting the key in
+`~/.clawdbot/.env` so the daemon can read it:
+
+```bash
+cat >> ~/.clawdbot/.env <<'EOF'
+ANTHROPIC_API_KEY=...
+EOF
+```
+
+Then restart the daemon (or restart your Gateway process) and re-check:
+
+```bash
+clawdbot models status
+clawdbot doctor
+```
+
+If you’d rather not manage env vars yourself, the onboarding wizard can store
+API keys for daemon use: `clawdbot onboard`.
+
+See [Help](/help) for details on env inheritance (`env.shellEnv`,
+`~/.clawdbot/.env`, systemd/launchd).
+
+## Anthropic: setup-token (subscription auth)
+
+For Anthropic, the recommended path is an **API key**. If you’re using a Claude
+subscription, the setup-token flow is also supported. Run it on the **gateway host**:
+
+```bash
+claude setup-token
+```
+
+Then paste it into Clawdbot:
+
+```bash
+clawdbot models auth setup-token --provider anthropic
+```
+
+If the token was created on another machine, paste it manually:
+
+```bash
+clawdbot models auth paste-token --provider anthropic
+```
+
+If you see an Anthropic error like:
+
+```
+This credential is only authorized for use with Claude Code and cannot be used for other API requests.
+```
+
+…use an Anthropic API key instead.
+
+Manual token entry (any provider; writes `auth-profiles.json` + updates config):
+
+```bash
+clawdbot models auth paste-token --provider anthropic
+clawdbot models auth paste-token --provider openrouter
+```
+
+Automation-friendly check (exit `1` when expired/missing, `2` when expiring):
+
+```bash
+clawdbot models status --check
+```
+
+Optional ops scripts (systemd/Termux) are documented here:
+[/automation/auth-monitoring](/automation/auth-monitoring)
+
+> `claude setup-token` requires an interactive TTY.
+
+## Checking model auth status
+
+```bash
+clawdbot models status
+clawdbot doctor
+```
+
+## Controlling which credential is used
+
+### Per-session (chat command)
+
+Use `/model <alias-or-id>@<profileId>` to pin a specific provider credential for the current session (example profile ids: `anthropic:default`, `anthropic:work`).
+
+Use `/model` (or `/model list`) for a compact picker; use `/model status` for the full view (candidates + next auth profile, plus provider endpoint details when configured).
+
+### Per-agent (CLI override)
+
+Set an explicit auth profile order override for an agent (stored in that agent’s `auth-profiles.json`):
+
+```bash
+clawdbot models auth order get --provider anthropic
+clawdbot models auth order set --provider anthropic anthropic:default
+clawdbot models auth order clear --provider anthropic
+```
+
+Use `--agent <id>` to target a specific agent; omit it to use the configured default agent.
+
+## Troubleshooting
+
+### “No credentials found”
+
+If the Anthropic token profile is missing, run `claude setup-token` on the
+**gateway host**, then re-check:
+
+```bash
+clawdbot models status
+```
+
+### Token expiring/expired
+
+Run `clawdbot models status` to confirm which profile is expiring. If the profile
+is missing, rerun `claude setup-token` and paste the token again.
+
+## Requirements
+
+- Claude Max or Pro subscription (for `claude setup-token`)
+- Claude Code CLI installed (`claude` command available)

package/docs/gateway/background-process.md

@@ -0,0 +1,82 @@
+---
+summary: "Background exec execution and process management"
+read_when:
+  - Adding or modifying background exec behavior
+  - Debugging long-running exec tasks
+---
+
+# Background Exec + Process Tool
+
+Clawdbot runs shell commands through the `exec` tool and keeps long‑running tasks in memory. The `process` tool manages those background sessions.
+
+## exec tool
+
+Key parameters:
+- `command` (required)
+- `yieldMs` (default 10000): auto‑background after this delay
+- `background` (bool): background immediately
+- `timeout` (seconds, default 1800): kill the process after this timeout
+- `elevated` (bool): run on host if elevated mode is enabled/allowed
+- Need a real TTY? Set `pty: true`.
+- `workdir`, `env`
+
+Behavior:
+- Foreground runs return output directly.
+- When backgrounded (explicit or timeout), the tool returns `status: "running"` + `sessionId` and a short tail.
+- Output is kept in memory until the session is polled or cleared.
+- If the `process` tool is disallowed, `exec` runs synchronously and ignores `yieldMs`/`background`.
+
+## Child process bridging
+
+When spawning long-running child processes outside the exec/process tools (for example, CLI respawns or gateway helpers), attach the child-process bridge helper so termination signals are forwarded and listeners are detached on exit/error. This avoids orphaned processes on systemd and keeps shutdown behavior consistent across platforms.
+
+Environment overrides:
+- `PI_BASH_YIELD_MS`: default yield (ms)
+- `PI_BASH_MAX_OUTPUT_CHARS`: in‑memory output cap (chars)
+- `CLAWDBOT_BASH_PENDING_MAX_OUTPUT_CHARS`: pending stdout/stderr cap per stream (chars)
+- `PI_BASH_JOB_TTL_MS`: TTL for finished sessions (ms, bounded to 1m–3h)
+
+Config (preferred):
+- `tools.exec.backgroundMs` (default 10000)
+- `tools.exec.timeoutSec` (default 1800)
+- `tools.exec.cleanupMs` (default 1800000)
+ - `tools.exec.notifyOnExit` (default true): enqueue a system event + request heartbeat when a backgrounded exec exits.
+
+## process tool
+
+Actions:
+- `list`: running + finished sessions
+- `poll`: drain new output for a session (also reports exit status)
+- `log`: read the aggregated output (supports `offset` + `limit`)
+- `write`: send stdin (`data`, optional `eof`)
+- `kill`: terminate a background session
+- `clear`: remove a finished session from memory
+- `remove`: kill if running, otherwise clear if finished
+
+Notes:
+- Only backgrounded sessions are listed/persisted in memory.
+- Sessions are lost on process restart (no disk persistence).
+- Session logs are only saved to chat history if you run `process poll/log` and the tool result is recorded.
+- `process` is scoped per agent; it only sees sessions started by that agent.
+- `process list` includes a derived `name` (command verb + target) for quick scans.
+- `process log` uses line-based `offset`/`limit` (omit `offset` to grab the last N lines).
+
+## Examples
+
+Run a long task and poll later:
+```json
+{"tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000}
+```
+```json
+{"tool": "process", "action": "poll", "sessionId": "<id>"}
+```
+
+Start immediately in background:
+```json
+{"tool": "exec", "command": "npm run build", "background": true}
+```
+
+Send stdin:
+```json
+{"tool": "process", "action": "write", "sessionId": "<id>", "data": "y\n"}
+```

package/docs/gateway/bonjour.md

@@ -0,0 +1,162 @@
+---
+summary: "Bonjour/mDNS discovery + debugging (Gateway beacons, clients, and common failure modes)"
+read_when:
+  - Debugging Bonjour discovery issues on macOS/iOS
+  - Changing mDNS service types, TXT records, or discovery UX
+---
+# Bonjour / mDNS discovery
+
+Clawdbot uses Bonjour (mDNS / DNS‑SD) as a **LAN‑only convenience** to discover
+an active Gateway (WebSocket endpoint). It is best‑effort and does **not** replace SSH or
+Tailnet-based connectivity.
+
+## Wide‑area Bonjour (Unicast DNS‑SD) over Tailscale
+
+If the node and gateway are on different networks, multicast mDNS won’t cross the
+boundary. You can keep the same discovery UX by switching to **unicast DNS‑SD**
+("Wide‑Area Bonjour") over Tailscale.
+
+High‑level steps:
+
+1) Run a DNS server on the gateway host (reachable over Tailnet).
+2) Publish DNS‑SD records for `_clawdbot-gw._tcp` under a dedicated zone
+   (example: `clawdbot.internal.`).
+3) Configure Tailscale **split DNS** so `clawdbot.internal` resolves via that
+   DNS server for clients (including iOS).
+
+Clawdbot standardizes on `clawdbot.internal.` for this mode. iOS/Android nodes
+browse both `local.` and `clawdbot.internal.` automatically.
+
+### Gateway config (recommended)
+
+```json5
+{
+  gateway: { bind: "tailnet" }, // tailnet-only (recommended)
+  discovery: { wideArea: { enabled: true } } // enables clawdbot.internal DNS-SD publishing
+}
+```
+
+### One‑time DNS server setup (gateway host)
+
+```bash
+clawdbot dns setup --apply
+```
+
+This installs CoreDNS and configures it to:
+- listen on port 53 only on the gateway’s Tailscale interfaces
+- serve `clawdbot.internal.` from `~/.clawdbot/dns/clawdbot.internal.db`
+
+Validate from a tailnet‑connected machine:
+
+```bash
+dns-sd -B _clawdbot-gw._tcp clawdbot.internal.
+dig @<TAILNET_IPV4> -p 53 _clawdbot-gw._tcp.clawdbot.internal PTR +short
+```
+
+### Tailscale DNS settings
+
+In the Tailscale admin console:
+
+- Add a nameserver pointing at the gateway’s tailnet IP (UDP/TCP 53).
+- Add split DNS so the domain `clawdbot.internal` uses that nameserver.
+
+Once clients accept tailnet DNS, iOS nodes can browse
+`_clawdbot-gw._tcp` in `clawdbot.internal.` without multicast.
+
+### Gateway listener security (recommended)
+
+The Gateway WS port (default `18789`) binds to loopback by default. For LAN/tailnet
+access, bind explicitly and keep auth enabled.
+
+For tailnet‑only setups:
+- Set `gateway.bind: "tailnet"` in `~/.clawdbot/clawdbot.json`.
+- Restart the Gateway (or restart the macOS menubar app).
+
+## What advertises
+
+Only the Gateway advertises `_clawdbot-gw._tcp`.
+
+## Service types
+
+- `_clawdbot-gw._tcp` — gateway transport beacon (used by macOS/iOS/Android nodes).
+
+## TXT keys (non‑secret hints)
+
+The Gateway advertises small non‑secret hints to make UI flows convenient:
+
+- `role=gateway`
+- `displayName=<friendly name>`
+- `lanHost=<hostname>.local`
+- `gatewayPort=<port>` (Gateway WS + HTTP)
+- `gatewayTls=1` (only when TLS is enabled)
+- `gatewayTlsSha256=<sha256>` (only when TLS is enabled and fingerprint is available)
+- `canvasPort=<port>` (only when the canvas host is enabled; default `18793`)
+- `sshPort=<port>` (defaults to 22 when not overridden)
+- `transport=gateway`
+- `cliPath=<path>` (optional; absolute path to a runnable `clawdbot` entrypoint)
+- `tailnetDns=<magicdns>` (optional hint when Tailnet is available)
+
+## Debugging on macOS
+
+Useful built‑in tools:
+
+- Browse instances:
+  ```bash
+  dns-sd -B _clawdbot-gw._tcp local.
+  ```
+- Resolve one instance (replace `<instance>`):
+  ```bash
+  dns-sd -L "<instance>" _clawdbot-gw._tcp local.
+  ```
+
+If browsing works but resolving fails, you’re usually hitting a LAN policy or
+mDNS resolver issue.
+
+## Debugging in Gateway logs
+
+The Gateway writes a rolling log file (printed on startup as
+`gateway log file: ...`). Look for `bonjour:` lines, especially:
+
+- `bonjour: advertise failed ...`
+- `bonjour: ... name conflict resolved` / `hostname conflict resolved`
+- `bonjour: watchdog detected non-announced service ...`
+
+## Debugging on iOS node
+
+The iOS node uses `NWBrowser` to discover `_clawdbot-gw._tcp`.
+
+To capture logs:
+- Settings → Gateway → Advanced → **Discovery Debug Logs**
+- Settings → Gateway → Advanced → **Discovery Logs** → reproduce → **Copy**
+
+The log includes browser state transitions and result‑set changes.
+
+## Common failure modes
+
+- **Bonjour doesn’t cross networks**: use Tailnet or SSH.
+- **Multicast blocked**: some Wi‑Fi networks disable mDNS.
+- **Sleep / interface churn**: macOS may temporarily drop mDNS results; retry.
+- **Browse works but resolve fails**: keep machine names simple (avoid emojis or
+  punctuation), then restart the Gateway. The service instance name derives from
+  the host name, so overly complex names can confuse some resolvers.
+
+## Escaped instance names (`\032`)
+
+Bonjour/DNS‑SD often escapes bytes in service instance names as decimal `\DDD`
+sequences (e.g. spaces become `\032`).
+
+- This is normal at the protocol level.
+- UIs should decode for display (iOS uses `BonjourEscapes.decode`).
+
+## Disabling / configuration
+
+- `CLAWDBOT_DISABLE_BONJOUR=1` disables advertising.
+- `gateway.bind` in `~/.clawdbot/clawdbot.json` controls the Gateway bind mode.
+- `CLAWDBOT_SSH_PORT` overrides the SSH port advertised in TXT.
+- `CLAWDBOT_TAILNET_DNS` publishes a MagicDNS hint in TXT.
+- `CLAWDBOT_CLI_PATH` overrides the advertised CLI path.
+
+## Related docs
+
+- Discovery policy and transport selection: [Discovery](/gateway/discovery)
+- Node pairing + approvals: [Gateway pairing](/gateway/pairing)

package/docs/gateway/bridge-protocol.md

@@ -0,0 +1,85 @@
+---
+summary: "Bridge protocol (legacy nodes): TCP JSONL, pairing, scoped RPC"
+read_when:
+  - Building or debugging node clients (iOS/Android/macOS node mode)
+  - Investigating pairing or bridge auth failures
+  - Auditing the node surface exposed by the gateway
+---
+
+# Bridge protocol (legacy node transport)
+
+The Bridge protocol is a **legacy** node transport (TCP JSONL). New node clients
+should use the unified Gateway WebSocket protocol instead.
+
+If you are building an operator or node client, use the
+[Gateway protocol](/gateway/protocol).
+
+**Note:** Current Clawdbot builds no longer ship the TCP bridge listener; this document is kept for historical reference.
+Legacy `bridge.*` config keys are no longer part of the config schema.
+
+## Why we have both
+
+- **Security boundary**: the bridge exposes a small allowlist instead of the
+  full gateway API surface.
+- **Pairing + node identity**: node admission is owned by the gateway and tied
+  to a per-node token.
+- **Discovery UX**: nodes can discover gateways via Bonjour on LAN, or connect
+  directly over a tailnet.
+- **Loopback WS**: the full WS control plane stays local unless tunneled via SSH.
+
+## Transport
+
+- TCP, one JSON object per line (JSONL).
+- Optional TLS (when `bridge.tls.enabled` is true).
+- Legacy default listener port was `18790` (current builds do not start a TCP bridge).
+
+When TLS is enabled, discovery TXT records include `bridgeTls=1` plus
+`bridgeTlsSha256` so nodes can pin the certificate.
+
+## Handshake + pairing
+
+1) Client sends `hello` with node metadata + token (if already paired).  
+2) If not paired, gateway replies `error` (`NOT_PAIRED`/`UNAUTHORIZED`).  
+3) Client sends `pair-request`.  
+4) Gateway waits for approval, then sends `pair-ok` and `hello-ok`.
+
+`hello-ok` returns `serverName` and may include `canvasHostUrl`.
+
+## Frames
+
+Client → Gateway:
+- `req` / `res`: scoped gateway RPC (chat, sessions, config, health, voicewake, skills.bins)
+- `event`: node signals (voice transcript, agent request, chat subscribe, exec lifecycle)
+
+Gateway → Client:
+- `invoke` / `invoke-res`: node commands (`canvas.*`, `camera.*`, `screen.record`,
+  `location.get`, `sms.send`)
+- `event`: chat updates for subscribed sessions
+- `ping` / `pong`: keepalive
+
+Legacy allowlist enforcement lived in `src/gateway/server-bridge.ts` (removed).
+
+## Exec lifecycle events
+
+Nodes can emit `exec.finished` or `exec.denied` events to surface system.run activity.
+These are mapped to system events in the gateway. (Legacy nodes may still emit `exec.started`.)
+
+Payload fields (all optional unless noted):
+- `sessionKey` (required): agent session to receive the system event.
+- `runId`: unique exec id for grouping.
+- `command`: raw or formatted command string.
+- `exitCode`, `timedOut`, `success`, `output`: completion details (finished only).
+- `reason`: denial reason (denied only).
+
+## Tailnet usage
+
+- Bind the bridge to a tailnet IP: `bridge.bind: "tailnet"` in
+  `~/.clawdbot/clawdbot.json`.
+- Clients connect via MagicDNS name or tailnet IP.
+- Bonjour does **not** cross networks; use manual host/port or wide-area DNS‑SD
+  when needed.
+
+## Versioning
+
+Bridge is currently **implicit v1** (no min/max negotiation). Backward‑compat
+is expected; add a bridge protocol version field before any breaking changes.

package/docs/gateway/cli-backends.md

@@ -0,0 +1,221 @@
+---
+summary: "CLI backends: text-only fallback via local AI CLIs"
+read_when:
+  - You want a reliable fallback when API providers fail
+  - You are running Claude Code CLI or other local AI CLIs and want to reuse them
+  - You need a text-only, tool-free path that still supports sessions and images
+---
+# CLI backends (fallback runtime)
+
+Clawdbot can run **local AI CLIs** as a **text-only fallback** when API providers are down,
+rate-limited, or temporarily misbehaving. This is intentionally conservative:
+
+- **Tools are disabled** (no tool calls).
+- **Text in → text out** (reliable).
+- **Sessions are supported** (so follow-up turns stay coherent).
+- **Images can be passed through** if the CLI accepts image paths.
+
+This is designed as a **safety net** rather than a primary path. Use it when you
+want “always works” text responses without relying on external APIs.
+
+## Beginner-friendly quick start
+
+You can use Claude Code CLI **without any config** (Clawdbot ships a built-in default):
+
+```bash
+clawdbot agent --message "hi" --model claude-cli/opus-4.5
+```
+
+Codex CLI also works out of the box:
+
+```bash
+clawdbot agent --message "hi" --model codex-cli/gpt-5.2-codex
+```
+
+If your gateway runs under launchd/systemd and PATH is minimal, add just the
+command path:
+
+```json5
+{
+  agents: {
+    defaults: {
+      cliBackends: {
+        "claude-cli": {
+          command: "/opt/homebrew/bin/claude"
+        }
+      }
+    }
+  }
+}
+```
+
+That’s it. No keys, no extra auth config needed beyond the CLI itself.
+
+## Using it as a fallback
+
+Add a CLI backend to your fallback list so it only runs when primary models fail:
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: {
+        primary: "anthropic/claude-opus-4-5",
+        fallbacks: [
+          "claude-cli/opus-4.5"
+        ]
+      },
+      models: {
+        "anthropic/claude-opus-4-5": { alias: "Opus" },
+        "claude-cli/opus-4.5": {}
+      }
+    }
+  }
+}
+```
+
+Notes:
+- If you use `agents.defaults.models` (allowlist), you must include `claude-cli/...`.
+- If the primary provider fails (auth, rate limits, timeouts), Clawdbot will
+  try the CLI backend next.
+
+## Configuration overview
+
+All CLI backends live under:
+
+```
+agents.defaults.cliBackends
+```
+
+Each entry is keyed by a **provider id** (e.g. `claude-cli`, `my-cli`).
+The provider id becomes the left side of your model ref:
+
+```
+<provider>/<model>
+```
+
+### Example configuration
+
+```json5
+{
+  agents: {
+    defaults: {
+      cliBackends: {
+        "claude-cli": {
+          command: "/opt/homebrew/bin/claude"
+        },
+        "my-cli": {
+          command: "my-cli",
+          args: ["--json"],
+          output: "json",
+          input: "arg",
+          modelArg: "--model",
+          modelAliases: {
+            "claude-opus-4-5": "opus",
+            "claude-sonnet-4-5": "sonnet"
+          },
+          sessionArg: "--session",
+          sessionMode: "existing",
+          sessionIdFields: ["session_id", "conversation_id"],
+          systemPromptArg: "--system",
+          systemPromptWhen: "first",
+          imageArg: "--image",
+          imageMode: "repeat",
+          serialize: true
+        }
+      }
+    }
+  }
+}
+```
+
+## How it works
+
+1) **Selects a backend** based on the provider prefix (`claude-cli/...`).
+2) **Builds a system prompt** using the same Clawdbot prompt + workspace context.
+3) **Executes the CLI** with a session id (if supported) so history stays consistent.
+4) **Parses output** (JSON or plain text) and returns the final text.
+5) **Persists session ids** per backend, so follow-ups reuse the same CLI session.
+
+## Sessions
+
+- If the CLI supports sessions, set `sessionArg` (e.g. `--session-id`) or
+  `sessionArgs` (placeholder `{sessionId}`) when the ID needs to be inserted
+  into multiple flags.
+- If the CLI uses a **resume subcommand** with different flags, set
+  `resumeArgs` (replaces `args` when resuming) and optionally `resumeOutput`
+  (for non-JSON resumes).
+- `sessionMode`:
+  - `always`: always send a session id (new UUID if none stored).
+  - `existing`: only send a session id if one was stored before.
+  - `none`: never send a session id.
+
+## Images (pass-through)
+
+If your CLI accepts image paths, set `imageArg`:
+
+```json5
+imageArg: "--image",
+imageMode: "repeat"
+```
+
+Clawdbot will write base64 images to temp files. If `imageArg` is set, those
+paths are passed as CLI args. If `imageArg` is missing, Clawdbot appends the
+file paths to the prompt (path injection), which is enough for CLIs that auto-
+load local files from plain paths (Claude Code CLI behavior).
+
+## Inputs / outputs
+
+- `output: "json"` (default) tries to parse JSON and extract text + session id.
+- `output: "jsonl"` parses JSONL streams (Codex CLI `--json`) and extracts the
+  last agent message plus `thread_id` when present.
+- `output: "text"` treats stdout as the final response.
+
+Input modes:
+- `input: "arg"` (default) passes the prompt as the last CLI arg.
+- `input: "stdin"` sends the prompt via stdin.
+- If the prompt is very long and `maxPromptArgChars` is set, stdin is used.
+
+## Defaults (built-in)
+
+Clawdbot ships a default for `claude-cli`:
+
+- `command: "claude"`
+- `args: ["-p", "--output-format", "json", "--dangerously-skip-permissions"]`
+- `resumeArgs: ["-p", "--output-format", "json", "--dangerously-skip-permissions", "--resume", "{sessionId}"]`
+- `modelArg: "--model"`
+- `systemPromptArg: "--append-system-prompt"`
+- `sessionArg: "--session-id"`
+- `systemPromptWhen: "first"`
+- `sessionMode: "always"`
+
+Clawdbot also ships a default for `codex-cli`:
+
+- `command: "codex"`
+- `args: ["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]`
+- `resumeArgs: ["exec","resume","{sessionId}","--color","never","--sandbox","read-only","--skip-git-repo-check"]`
+- `output: "jsonl"`
+- `resumeOutput: "text"`
+- `modelArg: "--model"`
+- `imageArg: "--image"`
+- `sessionMode: "existing"`
+
+Override only if needed (common: absolute `command` path).
+
+## Limitations
+
+- **No Clawdbot tools** (the CLI backend never receives tool calls). Some CLIs
+  may still run their own agent tooling.
+- **No streaming** (CLI output is collected then returned).
+- **Structured outputs** depend on the CLI’s JSON format.
+- **Codex CLI sessions** resume via text output (no JSONL), which is less
+  structured than the initial `--json` run. Clawdbot sessions still work
+  normally.
+
+## Troubleshooting
+
+- **CLI not found**: set `command` to a full path.
+- **Wrong model name**: use `modelAliases` to map `provider/model` → CLI model.
+- **No session continuity**: ensure `sessionArg` is set and `sessionMode` is not
+  `none` (Codex CLI currently cannot resume with JSON output).
+- **Images ignored**: set `imageArg` (and verify CLI supports file paths).