typeclaw 0.9.0 → 0.9.2

package/src/skills/typeclaw-codex-cli/references/tmux-driving.md

@@ -0,0 +1,239 @@
+# Tmux driving — full reference (Codex CLI)
+
+Deep dive for driving `codex` (interactive) through tmux. Read it when the main `SKILL.md` workflow hits an edge case: a hung session, a missing JSONL, an unexpected ANSI burst, a "tmux says session exists but codex isn't responsive" situation.
+
+The shape of this reference is intentionally a mirror of `typeclaw-claude-code`'s `references/tmux-driving.md`. The differences are noted inline; everything not flagged is the same.
+
+## Why tmux
+
+The agent process has no TTY. `codex` (interactive) is a TUI built on `ratatui` + `crossterm` that uses raw terminal modes — it reads stdin one byte at a time with echo off, draws with ANSI escapes, and refuses to start sensibly if stdin/stdout aren't terminals. Piping into `codex` doesn't work; the CLI detects the absence of a TTY and either falls back to non-interactive semantics or fails outright.
+
+`tmux` solves this by spawning the process with a pty allocated by tmux itself. You then drive the pty via `send-keys` (write) and `capture-pane` (read).
+
+## Why `/tmp/cx-<id>` and not `workspace/cx-<id>`
+
+Same reasoning as Claude Code's `cc-<id>`:
+
+1. **Worktree-vs-scratch:** the `cx-<id>` directory is a real git checkout managed by `git worktree`, with refs in `/agent/.git/worktrees/cx-<id>/`. Putting it under `workspace/` would mean the agent folder contains a worktree of itself, which works mechanically but is recursive and confusing.
+2. **The global SessionStart and Stop hooks write their per-session files into cwd.** Both hook scripts read `$PWD` (the literal cwd Codex CLI was invoked with) and write into it: SessionStart writes `.session-id` containing the UUID; Stop writes `sentinel-<uuid>.json` and `.done-<uuid>`. `$PWD` resolves to the worktree because `tmux new-session -c /tmp/cx-<id>` sets codex's cwd there.
+3. **The worktree IS the codebase.** Codex can read every file at `HEAD` directly — it doesn't need a separate scratch area.
+
+The `cx-` prefix (vs Claude Code's `cc-`) keeps the two CLIs' worktrees, branches, and tmux sessions in parallel namespaces. An agent running both can delegate concurrently without collision; `git worktree list` shows both kinds clearly; `tmux ls` is unambiguous.
+
+## Spawning the session
+
+The canonical spawn (per `SKILL.md`):
+
+```sh
+tmux new-session -d -s cx-<task-id> -c /tmp/cx-<task-id> codex
+```
+
+Flags worth knowing:
+
+- `-d` — detached. The session runs in the background; your shell doesn't attach.
+- `-s cx-<task-id>` — explicit session name. Required. Without `-s`, tmux picks `0`, `1`, … and a sibling delegation will clobber yours.
+- `-c /tmp/cx-<task-id>` — start directory. Must be the worktree path. The global Stop hook at `~/.codex/hooks.json` always fires regardless of cwd, but the hook script writes its sentinel to `$PWD`; if cwd is wrong, the sentinel lands somewhere your polling loop isn't watching.
+- `codex` — the command. Just `codex`, not `codex exec`. The interactive TUI is the whole point.
+
+Common mistakes:
+
+- Forgetting `-c` and getting cwd `/agent` by default. The Stop hook still fires (it's global), but `sentinel.json` + `.done` end up under `/agent/`, your polling loop watches `/tmp/cx-<id>/`, and the loop times out at its wall-clock budget. Worse: codex in `/agent` operates on the live working tree instead of the worktree.
+- Passing flags Codex CLI doesn't recognize. Codex is a Rust binary with a strict clap parser — unknown flags fail at startup, not silently.
+
+### Alternate-screen vs inline mode
+
+Codex CLI's TUI defaults to **alternate-screen mode** (the same mode `vim` uses) — it takes over the entire terminal and restores the previous screen on exit. This means `tmux capture-pane -S -` only captures what's currently visible, not the full conversation history.
+
+For our workflow this is fine: we use the Stop sentinel as the done-signal, not pane-content parsing. But if you ever need to capture the full TUI history (e.g. for a post-mortem when the JSONL is missing), spawn codex with `--no-alt-screen`:
+
+```sh
+tmux new-session -d -s cx-<id> -c /tmp/cx-<id> codex --no-alt-screen
+```
+
+`--no-alt-screen` runs the TUI inline, preserving terminal scrollback. The trade-off is that the rendering is slightly less stable (the TUI's redraws collide with normal scrollback flow), but `capture-pane -S -` will then see the full history.
+
+Default to alternate-screen mode (no flag); reach for `--no-alt-screen` only when you genuinely need scrollback capture for debugging.
+
+## The init wait
+
+`codex` prints a brief Welcome animation, then renders its TUI. The animation takes ~1 second; after that the input composer appears immediately if no dialogs fire, or one or more dialog modals appear in sequence. You must wait for the input composer (and clear any dialogs) before sending the first prompt.
+
+The skill body's flow uses dialog-polling rather than a fixed sleep: every 500ms, `tmux capture-pane -t cx-<id> -p -S -15` and check for the input composer (bottom-of-pane prompt indicator) OR a known dialog (Auth picker / TrustDirectory / hook trust). Clear dialogs as they appear, exit the loop when the input composer is visible. Give up after ~10s and surface to the user.
+
+Unlike Claude Code, Codex's `.session-id` IS a reliable readiness signal in most cases: Codex's SessionStart hook does NOT get suppressed while the TrustDirectory dialog is pending (different upstream architecture than Claude Code's #11519 issue). The fast path — read `.session-id` after ~1 second — usually wins. But the dialog-polling loop is still required to clear TrustDirectory before sending the first prompt; otherwise the prompt is interpreted as a dialog answer.
+
+## Sending input
+
+```sh
+tmux send-keys -t cx-<id> "<text>" Enter
+```
+
+Notes:
+
+- **Quote carefully.** The text is interpreted by tmux's send-keys before reaching the pty. Embedded `"` and `\` need escaping. For complex prompts, write the prompt to a file and use `tmux load-buffer + paste-buffer` instead of `send-keys`:
+
+  ```sh
+  echo "<prompt>" > prompt.txt
+  tmux load-buffer -t cx-<id> prompt.txt
+  tmux paste-buffer -t cx-<id>
+  tmux send-keys -t cx-<id> Enter
+  ```
+
+- **Bracketed paste is enabled** by default in Codex's TUI (`EnableBracketedPaste` in `tui.rs`), so `paste-buffer` content arrives intact even with newlines.
+
+- **`Enter` is the literal key name**, not the text "Enter". Other useful key names: `Escape`, `Tab`, `BSpace`, `Up`, `Down`, `C-c` (Ctrl+C), `C-d` (Ctrl+D for EOF). Codex's composer also honors `Ctrl-M` as submit (configurable per `tui.keymap.composer.submit` in `~/.codex/config.toml`, but our flow assumes the default).
+
+- **Multi-line prompts**: send the body, then `Enter`. Codex's composer treats Enter as submit by default, so newlines in your text become submitted lines. For genuinely multi-line input, use the paste-buffer flow above — bracketed paste passes the newlines through to the composer's input buffer without submitting until you press Enter explicitly.
+
+## Discovering `cx_session_id` and polling for `.done-<session_id>`
+
+Same edge-triggered polling pattern as Claude Code. Track which sentinels you've already processed by UUID; on every poll, enumerate ALL `.done-*` files, ignore the ones you've already processed, and pick the **newest by mtime** of what remains.
+
+### Phase 1 — first-turn discovery
+
+Fast path: after spawning codex and waiting ~1s, check `/tmp/cx-<id>/.session-id`. If it exists and contains a real UUID, that's `cx_session_id`. Otherwise fall through to the same first-turn polling as Claude Code (translate to your tool calls; the shell snippet is illustrative):
+
+```sh
+budget=600
+elapsed=0
+processed=""
+cx_session_id=""
+# Fast path
+if [ -f /tmp/cx-<id>/.session-id ]; then
+  candidate="$(cat /tmp/cx-<id>/.session-id 2>/dev/null)"
+  case "$candidate" in
+    [0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f]-*) cx_session_id="$candidate" ;;
+    malformed) echo "SessionStart fired but session_id was bad" ; exit 1 ;;
+  esac
+fi
+# Discovery path (fallback or wait for the first Stop)
+while [ -z "$cx_session_id" ]; do
+  newest=""
+  for f in $(ls -t /tmp/cx-<id>/.done-* 2>/dev/null); do
+    [ -f "$f" ] || continue
+    uuid="${f##*/.done-}"
+    case " $processed " in *" $uuid "*) continue ;; esac
+    if [ "$uuid" = "malformed" ]; then
+      malformed_fallback="$f"
+      continue
+    fi
+    newest="$f"
+    cx_session_id="$uuid"
+    break
+  done
+  if [ -n "$cx_session_id" ]; then break; fi
+  if [ -n "${malformed_fallback:-}" ]; then
+    echo "Stop hook fired but couldn't extract a UUID-shape session_id"
+    exit 1
+  fi
+  if [ "$elapsed" -ge "$budget" ]; then echo "Timeout reached"; break; fi
+  if ! tmux has-session -t cx-<id> 2>/dev/null; then echo "tmux session died"; break; fi
+  sleep 0.5
+  elapsed=$((elapsed + 1))
+done
+```
+
+### Phase 2 — per-turn polling (turns 2 onward)
+
+Same shape as Claude Code's phase 2. `processed` carries over from phase 1; add the just-consumed UUID before entering phase 2. On every iteration, glob `.done-*`, pick newest unprocessed real-UUID, update `cx_session_id` if it differs (rotation), read the sentinel, `rm` ONLY the specific `.done-<uuid>` you processed.
+
+```sh
+budget=600
+elapsed=0
+processed="$processed $cx_session_id"
+new_sid=""
+while [ -z "$new_sid" ]; do
+  for f in $(ls -t /tmp/cx-<id>/.done-* 2>/dev/null); do
+    [ -f "$f" ] || continue
+    uuid="${f##*/.done-}"
+    case " $processed " in *" $uuid "*) continue ;; esac
+    if [ "$uuid" = "malformed" ]; then echo "bad session_id"; exit 1; fi
+    new_sid="$uuid"
+    break
+  done
+  if [ -n "$new_sid" ]; then break; fi
+  if [ "$elapsed" -ge "$budget" ]; then echo "Timeout"; break; fi
+  if ! tmux has-session -t cx-<id> 2>/dev/null; then echo "tmux died"; break; fi
+  sleep 0.5
+  elapsed=$((elapsed + 1))
+done
+
+if [ "$new_sid" != "$cx_session_id" ]; then
+  echo "Detected session_id rotation: ${cx_session_id} → ${new_sid}"
+  cx_session_id="$new_sid"
+fi
+cat "/tmp/cx-<id>/sentinel-${cx_session_id}.json"
+rm -f "/tmp/cx-<id>/.done-${cx_session_id}"
+```
+
+### Why edge-triggered, not level-triggered
+
+Same reasoning as Claude Code. Level-triggered polling on a fixed `.done-<sid>` filename breaks on session rotation and on the "old marker still exists when new one arrives" race. Newest-by-mtime + processed-set is the only correct pattern.
+
+### Why 500ms cadence
+
+- Faster polling (50–100ms) wastes CPU and is invisible to the user.
+- Slower polling (2s+) adds visible latency.
+- 500ms is the sweet spot — same calibration as Claude Code, same reasoning.
+
+### Session-died recovery
+
+`tmux has-session` returns non-zero when the session is gone. Three reasons:
+
+1. **Codex crashed**: panic, segfault. `capture-pane` before tmux GC'd would show the panic message.
+2. **Auth failed**: `codex` exited cleanly with "Unauthorized" or similar. Pane would have shown the error briefly.
+3. **User killed it externally**: someone ran `tmux kill-session -t cx-<id>` outside your control.
+
+Recovery: surface to the user with whatever you have — `git diff main..cx-<id>` (which still works because the branch exists), `sentinel.json` from any prior turn, the JSONL if it exists. Then clean up: `git worktree remove --force /tmp/cx-<id>` + `git branch -D cx-<id>`. Ask whether to retry.
+
+## Capturing the pane (fallback path)
+
+When the JSONL is missing or you need to see what the TUI showed:
+
+```sh
+tmux capture-pane -t cx-<id> -p -S - -E -
+```
+
+Flags:
+
+- `-p` — print to stdout.
+- `-S -` — start from the beginning of the scrollback.
+- `-E -` — end at the current line.
+
+If codex was spawned in alternate-screen mode (the default), `-S -` only captures the current screen. For full history, spawn with `--no-alt-screen`.
+
+### ANSI gotchas
+
+- **Codex uses crossterm + ratatui** with bracketed paste, focus tracking, and keyboard enhancement modes enabled. Captures will contain ANSI escapes for color, cursor positioning, and bracketed-paste markers (`\x1b[200~` / `\x1b[201~`).
+- **Progress indicators** in Codex's tool-use UI redraw in place. Captures show the final state of each cell.
+- **Box-drawing characters** for input frames are Unicode (`╭ ╮ ╰ ╯ │ ─`). Preserve as UTF-8.
+- **Color codes**: standard 8-color and 256-color. Strip with `s/\x1b\[[0-9;]*[a-zA-Z]//g` if you need plain text.
+
+## Cleaning up
+
+```sh
+tmux send-keys -t cx-<id> "/exit" Enter
+sleep 1
+tmux kill-session -t cx-<id> 2>/dev/null || true
+git -C /agent worktree remove --force /tmp/cx-<id>
+git -C /agent branch -D cx-<id>
+```
+
+- `/exit` is Codex CLI's built-in exit command. Cleaner than `C-c` — it lets the CLI flush the JSONL and close cleanly.
+- `sleep 1` gives the CLI time to flush. Skip it and you may lose the last few JSONL lines.
+- `kill-session ... || true` because the session may have already exited cleanly after `/exit`.
+- `worktree remove --force` because the working tree has un-cherry-picked changes. `--force` is correct here because we're explicitly discarding.
+- `branch -D` to delete the throwaway branch.
+
+## Things you must not do in tmux driving
+
+- **Do not omit `-s <name>` on `new-session`.** Anonymous sessions race across delegations.
+- **Do not omit `-c /tmp/cx-<id>` on `new-session`.** The global Stop hook writes its sentinel into `$PWD`; wrong cwd means the sentinel lands somewhere your polling loop isn't watching. Worse: codex in `/agent` operates on the live working tree instead of the worktree.
+- **Do not skip the init wait.** Sending input before the TUI is ready loses the input silently — or worse, the input lands inside a dialog modal and gets interpreted as a yes/no answer.
+- **Do not use `send-keys` with raw user-supplied strings without escaping.** Tmux's send-keys is mildly shell-like; embedded special chars get interpreted. Use `load-buffer + paste-buffer` for anything untrusted or complex.
+- **Do not poll `capture-pane` as your primary done-signal.** Use the sentinel. `capture-pane` is for content retrieval, not lifecycle.
+- **Do not kill the session with `C-c` if you can avoid it.** `/exit` is cleaner.
+- **Do not assume `tmux has-session` returning success means codex is responsive.** A session can exist while codex is wedged. Pair with a wall-clock budget.
+- **Do not `rm -rf /tmp/cx-<id>` instead of `git worktree remove`.** Pure rm leaves orphan refs and a dangling branch.
+- **Do not mix `cx-` and `cc-` prefixes within one delegation.** They're parallel namespaces by design — Codex sessions use `cx-`, Claude Code sessions use `cc-`. Cross-using leaves orphans in both worktree lists.
+- **Do not pass `codex --no-alt-screen` reflexively.** Alternate-screen mode is the default for good reason (cleaner TUI rendering). Reach for the flag only when you need full-scrollback capture for debugging.

package/src/skills/typeclaw-config/SKILL.md

@@ -39,18 +39,18 @@ You yourself cannot run `typeclaw restart` — that is a host-stage command and
 
 `typeclaw.json` is a single JSON object with these fields:
 
-| Field         | Required | Type             | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| ------------- | -------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `$schema`     | no       | string           | Path to `typeclaw.schema.json` for editor autocompletion. Scaffolded as `./node_modules/typeclaw/typeclaw.schema.json`. Leave it alone unless the user moves it.                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `port`        | no       | integer          | 1–65535. Defaults to `8973` (T9 spelling of "TYPE"). Change only if the default collides with something on the user's host. **Restart-required.**                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `model`       | no       | string           | Must be one of the values listed in the **Allowed models** section below. Defaults to `openai/gpt-5.4-nano`. **Live-reloadable.**                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `mounts`      | no       | array of objects | Host directories bind-mounted into your container. Defaults to `[]` (no host paths exposed). Omitted from scaffolded `typeclaw.json` — add it only when the user wants host paths exposed. See **Mounts** section below. **Restart-required.**                                                                                                                                                                                                                                                                                                                       |
-| `plugins`     | no       | array of strings | Plugin package names loaded at server boot. Defaults to `[]`. **Restart-required.** Plugin-owned config blocks live alongside as additional top-level keys; see **Plugin config blocks**.                                                                                                                                                                                                                                                                                                                                                                            |
-| `alias`       | no       | array of strings | Additional names the agent answers to in channel engagement, on top of the implicit `basename(agentDir)`. Each entry is a non-empty trimmed string matched case-insensitively as a substring of the inbound text. Defaults to `[]`. Hatching populates this with the agent's chosen name. See **Alias** section below. **Live-reloadable.**                                                                                                                                                                                                                          |
-| `channels`    | no       | object           | Per-adapter engagement triggers and history-prefetch knobs for external messengers. Defaults to `{}` (no adapters configured). `typeclaw init` scaffolds an empty block per requested adapter (e.g. `"discord-bot": {}`) and the schema fills in defaults. Channel access control lives in `roles` — see the `typeclaw-permissions` skill. **Live-reloadable.** See **Channels** section below.                                                                                                                                                                      |
-| `portForward` | no       | object           | Allow/deny policy for the host-stage portbroker that auto-forwards container LISTEN ports to `127.0.0.1` on the host. Defaults to `{ "allow": "*" }` (forward everything). Omitted from scaffolded `typeclaw.json`. **Restart-required.** See **portForward** section below.                                                                                                                                                                                                                                                                                         |
-| `docker`      | no       | object           | Namespace for Docker-related blocks. Today the only child is `docker.file` — toggles (`tmux`, `gh`, `python`, `ffmpeg`, `cjkFonts`, `cloudflared`, `claudeCode`) gate opinionated package installs; `append` adds custom Dockerfile lines just before `ENTRYPOINT`. `docker.file` defaults to `{ ffmpeg: false, gh: true, python: true, tmux: true, cjkFonts: true, cloudflared: true, claudeCode: false, append: [] }`. Omitted from scaffolded `typeclaw.json`. **Restart-required** (next `typeclaw start` rebuilds the image). See **Dockerfile** section below. |
-| `git`         | no       | object           | Namespace for git-related blocks. Today the only child is `git.ignore` — extra patterns spliced into the autogenerated `.gitignore` before TypeClaw's protected rules. `git.ignore` defaults to `{ "append": [] }`. Omitted from scaffolded `typeclaw.json`. **Restart-required** (next `typeclaw start` refreshes `.gitignore`). See **Gitignore** section below.                                                                                                                                                                                                   |
+| Field         | Required | Type             | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| ------------- | -------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `$schema`     | no       | string           | Path to `typeclaw.schema.json` for editor autocompletion. Scaffolded as `./node_modules/typeclaw/typeclaw.schema.json`. Leave it alone unless the user moves it.                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `port`        | no       | integer          | 1–65535. Defaults to `8973` (T9 spelling of "TYPE"). Change only if the default collides with something on the user's host. **Restart-required.**                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `model`       | no       | string           | Must be one of the values listed in the **Allowed models** section below. Defaults to `openai/gpt-5.4-nano`. **Live-reloadable.**                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `mounts`      | no       | array of objects | Host directories bind-mounted into your container. Defaults to `[]` (no host paths exposed). Omitted from scaffolded `typeclaw.json` — add it only when the user wants host paths exposed. See **Mounts** section below. **Restart-required.**                                                                                                                                                                                                                                                                                                                                                    |
+| `plugins`     | no       | array of strings | Plugin package names loaded at server boot. Defaults to `[]`. **Restart-required.** Plugin-owned config blocks live alongside as additional top-level keys; see **Plugin config blocks**.                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `alias`       | no       | array of strings | Additional names the agent answers to in channel engagement, on top of the implicit `basename(agentDir)`. Each entry is a non-empty trimmed string matched case-insensitively as a substring of the inbound text. Defaults to `[]`. Hatching populates this with the agent's chosen name. See **Alias** section below. **Live-reloadable.**                                                                                                                                                                                                                                                       |
+| `channels`    | no       | object           | Per-adapter engagement triggers and history-prefetch knobs for external messengers. Defaults to `{}` (no adapters configured). `typeclaw init` scaffolds an empty block per requested adapter (e.g. `"discord-bot": {}`) and the schema fills in defaults. Channel access control lives in `roles` — see the `typeclaw-permissions` skill. **Live-reloadable.** See **Channels** section below.                                                                                                                                                                                                   |
+| `portForward` | no       | object           | Allow/deny policy for the host-stage portbroker that auto-forwards container LISTEN ports to `127.0.0.1` on the host. Defaults to `{ "allow": "*" }` (forward everything). Omitted from scaffolded `typeclaw.json`. **Restart-required.** See **portForward** section below.                                                                                                                                                                                                                                                                                                                      |
+| `docker`      | no       | object           | Namespace for Docker-related blocks. Today the only child is `docker.file` — toggles (`tmux`, `gh`, `python`, `ffmpeg`, `cjkFonts`, `cloudflared`, `claudeCode`, `codexCli`) gate opinionated package installs; `append` adds custom Dockerfile lines just before `ENTRYPOINT`. `docker.file` defaults to `{ ffmpeg: false, gh: true, python: true, tmux: true, cjkFonts: true, cloudflared: true, claudeCode: false, codexCli: false, append: [] }`. Omitted from scaffolded `typeclaw.json`. **Restart-required** (next `typeclaw start` rebuilds the image). See **Dockerfile** section below. |
+| `git`         | no       | object           | Namespace for git-related blocks. Today the only child is `git.ignore` — extra patterns spliced into the autogenerated `.gitignore` before TypeClaw's protected rules. `git.ignore` defaults to `{ "append": [] }`. Omitted from scaffolded `typeclaw.json`. **Restart-required** (next `typeclaw start` refreshes `.gitignore`). See **Gitignore** section below.                                                                                                                                                                                                                                |
 
 > **Top-level keys not in this table are not "ignored unknowns" anymore** — they are reserved for **plugin config blocks**. The schema's `catchall(z.unknown())` preserves them, and the plugin loader hands each block to its owning plugin's `configSchema` for validation. The bundled memory plugin owns `memory` at the top level — see the `typeclaw-memory` skill for that block's semantics. Do not write a top-level key unless you know which plugin owns it.
 
@@ -138,7 +138,7 @@ Each entry in `channels` is keyed by adapter id and has this shape:
 
 | Field        | Required | Type    | Notes                                                                                                                                                                                    |
 | ------------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `engagement` | no       | object  | When the agent should auto-reply vs. stay silent. Defaults to mention/reply/dm with 5-minute reply stickiness. See **Engagement** below.                                                 |
+| `engagement` | no       | object  | When the agent should auto-reply vs. stay silent. Defaults to mention/reply/dm with 15-minute reply stickiness. See **Engagement** below.                                                |
 | `history`    | no       | object  | Cold-start prefetch windows for `(thread.head, thread.tail, channel.tail)`. Set any to `0` to disable that side. Defaults to `{ thread: { head: 3, tail: 10 }, channel: { tail: 10 } }`. |
 | `enabled`    | no       | boolean | Defaults to `true`. Set `false` to disable the adapter entirely without removing its config.                                                                                             |
 
@@ -151,7 +151,7 @@ To stop the agent answering in a specific channel, narrow the `roles` block so t
 ```json
 "engagement": {
   "trigger": ["mention", "reply", "dm"],
-  "stickiness": { "perReply": { "window": 300000 } }
+  "stickiness": { "perReply": { "window": 900000 } }
 }
 ```
 
@@ -159,7 +159,7 @@ To stop the agent answering in a specific channel, narrow the `roles` block so t
   - `mention` — explicit `@bot` mentions.
   - `reply` — message is a Discord reply pointed at the agent's own message.
   - `dm` — any message in a DM channel.
-- **`stickiness`** — either the literal string `"off"`, or `{ perReply: { window: <ms> } }`. Default: 5-minute reply stickiness (`window: 300000`).
+- **`stickiness`** — either the literal string `"off"`, or `{ perReply: { window: <ms> } }`. Default: 15-minute reply stickiness (`window: 900000`).
   - `perReply` means: after the agent replies to a user, follow-up messages from that same user in that same channel within the window also wake the loop, even without a mention. The window is bounded server-side (`1` to `86_400_000` ms — 1 ms to 24 hours).
   - `"off"` disables stickiness — the agent only wakes on explicit triggers.
 
@@ -174,7 +174,7 @@ There is also a **solo-human fallback** built into the runtime that is **not con
   "discord-bot": {
     "engagement": {
       "trigger": ["mention", "reply", "dm"],
-      "stickiness": { "perReply": { "window": 300000 } }
+      "stickiness": { "perReply": { "window": 900000 } }
     },
     "enabled": true
   }
@@ -337,22 +337,23 @@ Off switch — the broker is constructed but never opens a WS, no LISTEN gets fo
 
 The `docker.file` block has two layers of customization:
 
-1. **Toggles** for opinionated package installs typeclaw knows how to layer correctly (`tmux`, `gh`, `python`, `ffmpeg`, `cjkFonts`, `cloudflared`, `claudeCode`). Most are apt packages — boolean for on/off, version string for an apt pin (e.g. `"gh": "2.40.0"` → `gh=2.40.0`) — and benefit from BuildKit cache mounts. `cloudflared` and `claudeCode` are the exceptions: `cloudflared` downloads the pinned GitHub release, `claudeCode` runs Anthropic's `curl | bash` installer; both are boolean-only. Use a toggle whenever it covers what the user wants over a hand-rolled `append` entry.
+1. **Toggles** for opinionated package installs typeclaw knows how to layer correctly (`tmux`, `gh`, `python`, `ffmpeg`, `cjkFonts`, `cloudflared`, `claudeCode`, `codexCli`). Most are apt packages — boolean for on/off, version string for an apt pin (e.g. `"gh": "2.40.0"` → `gh=2.40.0`) — and benefit from BuildKit cache mounts. `cloudflared`, `claudeCode`, and `codexCli` are the exceptions: `cloudflared` downloads the pinned GitHub release, `claudeCode` runs Anthropic's `curl | bash` installer, `codexCli` `bun install`s the `@openai/codex` npm package; all three are boolean-only. Use a toggle whenever it covers what the user wants over a hand-rolled `append` entry.
 2. **`append`** is the escape hatch for everything the toggles don't cover. An array of single-line Dockerfile instructions spliced in right before `ENTRYPOINT`, prefixed with a `# Custom lines from typeclaw.json#docker.file.append.` comment.
 
 ### Fields
 
-| Field         | Required | Type              | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| ------------- | -------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `tmux`        | no       | boolean \| string | Default `true`. `false` omits tmux from the apt install. String pins the Debian package version (e.g. `"3.3a-3"` → `tmux=3.3a-3`).                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `gh`          | no       | boolean \| string | Default `true`. `false` omits **both** the `gh` package and the GitHub CLI keyring bootstrap layer (skipping the network roundtrip on cold builds). String pins the version.                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `python`      | no       | boolean           | Default `true`. Fans out to `python3 python3-pip python3-venv python-is-python3` (the bundle that makes `python` and `pip` resolve correctly inside the container). Boolean-only — no version pin, because Debian's `python3` is a meta-package that doesn't accept a useful pin.                                                                                                                                                                                                                                                                                                   |
-| `ffmpeg`      | no       | boolean \| string | Default `false`. `true` apt-installs ffmpeg (~80 MB of codecs). String pins the version.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `cjkFonts`    | no       | boolean           | Default `true`. Installs `fonts-noto-cjk` (~56 MB) so Chromium (used by `agent-browser`) renders Korean/Japanese/Chinese glyphs correctly in screenshots, `page.pdf()`, and other raster output. `false` skips the layer entirely (DOM/innerText scraping is unaffected by font absence — only raster output shows tofu boxes). Boolean-only: the package is a metapackage tracking upstream Noto, no useful apt pin.                                                                                                                                                               |
-| `cloudflared` | no       | boolean           | Default `true`. Downloads the pinned `cloudflared` GitHub release (~35 MB) into the image so `cloudflare-quick` tunnels work on the next `start` without a separate Dockerfile edit. `false` skips the layer entirely on agents that don't use tunnels. Boolean-only — pinning is owned by the typeclaw release.                                                                                                                                                                                                                                                                    |
-| `xvfb`        | no       | boolean           | Default `true`. Installs `xvfb` (~5 MB) so the entrypoint shim can spawn a virtual X server and export `DISPLAY=:99`, giving headed Chrome (agent-browser `--headed`, headful Playwright) a real X11 display to defeat headless-mode WAF fingerprinting. `false` skips the layer; the shim self-heals (no `Xvfb` on PATH → execs the agent without `DISPLAY`). Boolean-only — xvfb tracks the upstream X server release with no useful apt pin.                                                                                                                                     |
-| `claudeCode`  | no       | boolean           | Default `false`. `true` runs Anthropic's official `curl -fsSL https://claude.ai/install.sh \| bash` in a dedicated layer (between agent-browser and the entrypoint shim) and pre-seeds `~/.claude.json` to skip the TTY-only theme picker on first launch (without it the agent's `tmux send-keys` would be eaten by the picker). Not apt: no version-pin variant; the upstream installer manages channels via env vars. Pairs with the `typeclaw-claude-code` skill, which documents the auth + tmux-driven usage flow including how to clear the post-seed API-key/trust dialogs. |
-| `append`      | no       | array of strings  | Each entry is a single Dockerfile line — schema **rejects** entries containing `\n` or `\r`. Defaults to `[]`. Splice happens just before `ENTRYPOINT`, after `ENV NODE_ENV=production`.                                                                                                                                                                                                                                                                                                                                                                                            |
+| Field         | Required | Type              | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| ------------- | -------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tmux`        | no       | boolean \| string | Default `true`. `false` omits tmux from the apt install. String pins the Debian package version (e.g. `"3.3a-3"` → `tmux=3.3a-3`).                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `gh`          | no       | boolean \| string | Default `true`. `false` omits **both** the `gh` package and the GitHub CLI keyring bootstrap layer (skipping the network roundtrip on cold builds). String pins the version.                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `python`      | no       | boolean           | Default `true`. Fans out to `python3 python3-pip python3-venv python-is-python3` (the bundle that makes `python` and `pip` resolve correctly inside the container). Boolean-only — no version pin, because Debian's `python3` is a meta-package that doesn't accept a useful pin.                                                                                                                                                                                                                                                                                                           |
+| `ffmpeg`      | no       | boolean \| string | Default `false`. `true` apt-installs ffmpeg (~80 MB of codecs). String pins the version.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `cjkFonts`    | no       | boolean           | Default `true`. Installs `fonts-noto-cjk` (~56 MB) so Chromium (used by `agent-browser`) renders Korean/Japanese/Chinese glyphs correctly in screenshots, `page.pdf()`, and other raster output. `false` skips the layer entirely (DOM/innerText scraping is unaffected by font absence — only raster output shows tofu boxes). Boolean-only: the package is a metapackage tracking upstream Noto, no useful apt pin.                                                                                                                                                                       |
+| `cloudflared` | no       | boolean           | Default `true`. Downloads the pinned `cloudflared` GitHub release (~35 MB) into the image so `cloudflare-quick` tunnels work on the next `start` without a separate Dockerfile edit. `false` skips the layer entirely on agents that don't use tunnels. Boolean-only — pinning is owned by the typeclaw release.                                                                                                                                                                                                                                                                            |
+| `xvfb`        | no       | boolean           | Default `true`. Installs `xvfb` (~5 MB) so the entrypoint shim can spawn a virtual X server and export `DISPLAY=:99`, giving headed Chrome (agent-browser `--headed`, headful Playwright) a real X11 display to defeat headless-mode WAF fingerprinting. `false` skips the layer; the shim self-heals (no `Xvfb` on PATH → execs the agent without `DISPLAY`). Boolean-only — xvfb tracks the upstream X server release with no useful apt pin.                                                                                                                                             |
+| `claudeCode`  | no       | boolean           | Default `false`. `true` runs Anthropic's official `curl -fsSL https://claude.ai/install.sh \| bash` in a dedicated layer (between agent-browser and the entrypoint shim) and pre-seeds `~/.claude.json` to skip the TTY-only theme picker on first launch (without it the agent's `tmux send-keys` would be eaten by the picker). Not apt: no version-pin variant; the upstream installer manages channels via env vars. Pairs with the `typeclaw-claude-code` skill, which documents the auth + tmux-driven usage flow including how to clear the post-seed API-key/trust dialogs.         |
+| `codexCli`    | no       | boolean           | Default `false`. `true` runs `bun install -g @openai/codex` in a dedicated layer (after `claudeCode`, before the entrypoint shim) and pre-writes `~/.codex/hooks.json` registering `SessionStart` + `Stop` hooks so the operator can detect turn boundaries the same way as Claude Code (sentinel files, `.session-id` discovery). Not apt: no version-pin variant. Codex CLI has NO theme picker so no onboarding seed is needed, but auth (`codex login` or `OPENAI_API_KEY`) and the per-project trust dialog are still required at runtime — handled by the `typeclaw-codex-cli` skill. |
+| `append`      | no       | array of strings  | Each entry is a single Dockerfile line — schema **rejects** entries containing `\n` or `\r`. Defaults to `[]`. Splice happens just before `ENTRYPOINT`, after `ENV NODE_ENV=production`.                                                                                                                                                                                                                                                                                                                                                                                                    |
 
 Toggle version strings reject whitespace and `=` (apt-injection guard) — pass just the version, not `pkg=ver`.
 
@@ -400,7 +401,7 @@ The toggle-driven apt install benefits from BuildKit `--mount=type=cache` on `/v
 ### When the user asks "install <package> in the container" / "add a Dockerfile line"
 
 1. **Read `typeclaw.json`.**
-2. **Check if a toggle covers it.** If the package is `tmux`, `gh`, `python`, `ffmpeg`, `cjkFonts` (CJK glyph rendering for `agent-browser` screenshots), `cloudflared` (Cloudflare Quick tunnels), or Anthropic's Claude Code CLI (`claudeCode`), prefer the toggle: `"docker": { "file": { "ffmpeg": true } }`. For a pinned version of an apt toggle, pass the version string: `"gh": "2.40.0"`. This is faster (BuildKit cache mount) and clearer than `append`. `cjkFonts`, `cloudflared`, and `claudeCode` are boolean-only — no version-pin variant.
+2. **Check if a toggle covers it.** If the package is `tmux`, `gh`, `python`, `ffmpeg`, `cjkFonts` (CJK glyph rendering for `agent-browser` screenshots), `cloudflared` (Cloudflare Quick tunnels), Anthropic's Claude Code CLI (`claudeCode`), or OpenAI's Codex CLI (`codexCli`), prefer the toggle: `"docker": { "file": { "ffmpeg": true } }`. For a pinned version of an apt toggle, pass the version string: `"gh": "2.40.0"`. This is faster (BuildKit cache mount) and clearer than `append`. `cjkFonts`, `cloudflared`, `claudeCode`, and `codexCli` are boolean-only — no version-pin variant.
 3. **Otherwise, use `append`.** Decide on a single-line entry — for apt installs, prefer one `RUN apt-get update && apt-get install -y --no-install-recommends <pkg> && rm -rf /var/lib/apt/lists/*` line. For env vars, one `ENV` line per variable.
 4. **Validate no embedded newlines** (`append` only). Multi-step logic must be `&&`-chained on one line, not split across array entries unless those entries are independent Dockerfile instructions.
 5. **Append to `docker.file.append`** (creating the field if it doesn't exist). Preserve existing entries.
@@ -626,7 +627,7 @@ Never echo, log, or commit values from `secrets.json` or `.env`. Both are gitign
 - `channels.<adapter>.allow` (legacy) is silently dropped on parse; `migrateLegacyConfigShape` lifts it into `roles.member.match` on load. See the `typeclaw-permissions` skill.
 - If `portForward` is set: `allow` is either `"*"` or an array of integers (1–65535); `deny`, if present, is an array of integers and **only valid when `allow` is `"*"`** (the schema rejects `deny` paired with a number-array `allow`)
 - If `docker.file.append` is set: array of strings, each with no embedded `\n` or `\r` (multi-step shell logic goes in a single `&&`-chained `RUN` entry)
-- If any `docker.file` toggle is set: `tmux`/`gh`/`ffmpeg` are boolean or version string (no whitespace, no `=`); `python`, `cjkFonts`, `cloudflared`, and `claudeCode` are boolean only
+- If any `docker.file` toggle is set: `tmux`/`gh`/`ffmpeg` are boolean or version string (no whitespace, no `=`); `python`, `cjkFonts`, `cloudflared`, `claudeCode`, and `codexCli` are boolean only
 - No unknown top-level keys you invented — keys outside the well-known ten are interpreted as **plugin config blocks** and only do something if a plugin owns them. Inventing one means the user thinks it took effect and it did not.
 
 ## Things you must not do
@@ -645,7 +646,7 @@ Never echo, log, or commit values from `secrets.json` or `.env`. Both are gitign
 - **Do not promise to post to a channel the speaker's role does not cover.** The router drops every inbound where the speaking author resolves to a role without `channel.respond`. If the user wants you to post somewhere new, the prerequisite is a `roles` edit + restart, not a retry.
 - **Do not conflate "stop replying" with "remove the role's match-rule".** Removing the match-rule cuts off both inbound visibility and outbound posting. If the user just wants quieter behavior, edit `engagement` instead.
 - **Do not edit the `Dockerfile` directly.** It is autogenerated and rewritten on every `typeclaw start` from `src/init/dockerfile.ts` in the typeclaw repo. Manual edits will be silently overwritten (and auto-committed away if the working tree is dirty). Customizations belong in the `docker.file` block (toggles or `append`).
-- **Do not reach for `docker.file.append` when a toggle covers it.** If the user wants tmux, gh, python, ffmpeg, fonts-noto-cjk (cjkFonts), cloudflared, or Anthropic's Claude Code CLI (claudeCode) installed (or removed, or pinned), use the toggle. The apt toggles are the cache-mounted path; `cloudflared` and `claudeCode` are non-apt boolean toggles, and the `claudeCode` toggle pairs with the `typeclaw-claude-code` skill that documents auth + usage. `append` for any of these is slower and harder to read.
+- **Do not reach for `docker.file.append` when a toggle covers it.** If the user wants tmux, gh, python, ffmpeg, fonts-noto-cjk (cjkFonts), cloudflared, Anthropic's Claude Code CLI (claudeCode), or OpenAI's Codex CLI (codexCli) installed (or removed, or pinned), use the toggle. The apt toggles are the cache-mounted path; `cloudflared`, `claudeCode`, and `codexCli` are non-apt boolean toggles, and the `claudeCode`/`codexCli` toggles pair with the `typeclaw-claude-code`/`typeclaw-codex-cli` skills that document auth + usage. `append` for any of these is slower and harder to read.
 - **Do not use `docker.file.append` for things that belong in the template.** If the user wants a system package _every_ typeclaw user should have, that's a typeclaw release, not a per-agent `append`. Suggest filing an issue.
 - **Do not put multiline strings in `docker.file.append`.** The schema rejects entries with embedded `\n`/`\r`. Use one entry per Dockerfile instruction; chain shell logic with `&&` on one line.
 - **Do not pass `pkg=ver` as a toggle version string.** The schema rejects `=` in version strings. Pass just the version (`"gh": "2.40.0"`); the renderer prepends `pkg=` itself. Same for whitespace — version strings cannot contain spaces.

package/src/test-helpers/wait-for.ts

@@ -4,13 +4,21 @@ export type WaitForOptions = {
   description?: string
 }
 
-// 5s, not 1s. 1s was tight enough to be the dominant cause of `bun test --parallel`
-// flakes on macOS: under 18-worker concurrent shell-spawn load, the kernel can
-// take >1s to drain a child process's stderr pipe past the libuv → JS boundary,
-// so a `waitFor` for "fake-cloudflared printed a URL" loses the race. 5s costs
-// nothing on the happy path (the polled predicate returns truthy as soon as it
-// can; this is just the timeout, not the wait), and absorbs realistic load.
-const DEFAULT_TIMEOUT_MS = 5_000
+// 30s, not 5s. 5s was tight enough to flake on heavy-load callers (the WS
+// pipeline assembly in src/portbroker/broker.test.ts is the canonical case:
+// host-side `Bun.listen` accept → broker connect → port discovery → snapshot
+// fanout → data round-trip is a 5-hop chain across two event loops, and the
+// 5s deadline was reached when libuv contention queued one of those hops).
+// The original 1s → 5s bump (commit b6a3ef9-era) acknowledged the same
+// failure mode for fake-cloudflared stderr drain; the WS pipeline pushed
+// the bound one tier higher. 30s costs nothing on the happy path (the
+// polled predicate returns truthy as soon as it can; this is just the
+// timeout, not the wait), absorbs realistic 18-worker contention, and
+// matches the global `setDefaultTimeout(30_000)` in
+// scripts/require-parallel.ts so a wedged waitFor surfaces as a clear
+// "waitFor: ... did not become truthy within 30000ms" message before the
+// outer test-level timeout fires with no context.
+const DEFAULT_TIMEOUT_MS = 30_000
 const DEFAULT_INTERVAL_MS = 1
 
 export async function waitFor<T>(

package/typeclaw.schema.json

@@ -134,7 +134,7 @@
                 ],
                 "stickiness": {
                   "perReply": {
-                    "window": 300000
+                    "window": 900000
                   }
                 }
               },
@@ -159,7 +159,7 @@
                 "stickiness": {
                   "default": {
                     "perReply": {
-                      "window": 300000
+                      "window": 900000
                     }
                   },
                   "anyOf": [
@@ -275,7 +275,7 @@
                 ],
                 "stickiness": {
                   "perReply": {
-                    "window": 300000
+                    "window": 900000
                   }
                 }
               },
@@ -300,7 +300,7 @@
                 "stickiness": {
                   "default": {
                     "perReply": {
-                      "window": 300000
+                      "window": 900000
                     }
                   },
                   "anyOf": [
@@ -448,7 +448,7 @@
                 ],
                 "stickiness": {
                   "perReply": {
-                    "window": 300000
+                    "window": 900000
                   }
                 }
               },
@@ -473,7 +473,7 @@
                 "stickiness": {
                   "default": {
                     "perReply": {
-                      "window": 300000
+                      "window": 900000
                     }
                   },
                   "anyOf": [
@@ -589,7 +589,7 @@
                 ],
                 "stickiness": {
                   "perReply": {
-                    "window": 300000
+                    "window": 900000
                   }
                 }
               },
@@ -614,7 +614,7 @@
                 "stickiness": {
                   "default": {
                     "perReply": {
-                      "window": 300000
+                      "window": 900000
                     }
                   },
                   "anyOf": [
@@ -730,7 +730,7 @@
                 ],
                 "stickiness": {
                   "perReply": {
-                    "window": 300000
+                    "window": 900000
                   }
                 }
               },
@@ -755,7 +755,7 @@
                 "stickiness": {
                   "default": {
                     "perReply": {
-                      "window": 300000
+                      "window": 900000
                     }
                   },
                   "anyOf": [
@@ -932,6 +932,7 @@
           "cloudflared": true,
           "xvfb": true,
           "claudeCode": false,
+          "codexCli": false,
           "append": []
         }
       },
@@ -947,6 +948,7 @@
             "cloudflared": true,
             "xvfb": true,
             "claudeCode": false,
+            "codexCli": false,
             "append": []
           },
           "type": "object",
@@ -1007,6 +1009,10 @@
               "default": false,
               "type": "boolean"
             },
+            "codexCli": {
+              "default": false,
+              "type": "boolean"
+            },
             "append": {
               "default": [],
               "type": "array",
@@ -1177,7 +1183,8 @@
         "idleMs": 60000,
         "bufferBytes": 500000,
         "injectionBudgetBytes": 16384,
-        "spawnTimeoutMs": 50000
+        "spawnTimeoutMs": 50000,
+        "retrievalSpawnTimeoutMs": 30000
       },
       "type": "object",
       "properties": {
@@ -1205,6 +1212,12 @@
           "minimum": 1,
           "maximum": 9007199254740991
         },
+        "retrievalSpawnTimeoutMs": {
+          "default": 30000,
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 9007199254740991
+        },
         "dreaming": {
           "type": "object",
           "properties": {