refactor: architecture elevation with broker, modular CLI, and comprehensive hardening

CLAUDE.md

@@ -16,14 +16,21 @@ codex-collab health
 
 | File | Purpose |
 |------|---------|
-| `src/cli.ts` | CLI commands, argument parsing, output formatting |
-| `src/protocol.ts` | JSON-RPC client for Codex app server (spawn, handshake, request routing) |
-| `src/threads.ts` | Thread lifecycle, short ID mapping |
+| `src/cli.ts` | CLI router, argument parsing, signal handlers |
+| `src/client.ts` | JSON-RPC client for Codex app server (spawn, handshake, request routing) |
+| `src/commands/` | CLI command handlers (run, review, threads, kill, config, approve) |
+| `src/threads.ts` | Thread index, run ledger, short ID mapping |
 | `src/turns.ts` | Turn lifecycle (runTurn, runReview), event wiring |
 | `src/events.ts` | Event dispatcher (progress lines, log writer, output accumulator) |
 | `src/approvals.ts` | Approval handler abstraction (auto-approve, interactive IPC) |
 | `src/types.ts` | Protocol types (JSON-RPC, threads, turns, items, approvals) |
-| `src/config.ts` | Configuration constants |
+| `src/config.ts` | Configuration constants, workspace resolution |
+| `src/broker.ts` | Shared app-server lifecycle (connection pooling) |
+| `src/broker-client.ts` | Socket-based client for connecting to the broker server |
+| `src/broker-server.ts` | Detached broker server process (multiplexes JSON-RPC between clients and app-server) |
+| `src/process.ts` | Process spawn/lifecycle utilities |
+| `src/git.ts` | Git operations (diff, log, status) |
+| `src/reviews.ts` | Review validation, structured output parsing |
 | `SKILL.md` | Claude Code skill definition |
 
 ## Dependencies
@@ -33,10 +40,10 @@ codex-collab health
 ## Architecture Notes
 
 - Communicates with Codex via `codex app-server` JSON-RPC protocol over stdio
-- Threads stored in `~/.codex-collab/threads.json` as short ID → full ID mapping
-- Logs stored in `~/.codex-collab/logs/` per thread
+- Per-workspace state under `~/.codex-collab/workspaces/{slug}-{hash}/` (threads, logs, runs, approvals, kill signals, PIDs)
 - User defaults stored in `~/.codex-collab/config.json` (model, reasoning, sandbox, approval, timeout)
-- Approval requests use file-based IPC in `~/.codex-collab/approvals/`
+- Broker manages a shared app-server per workspace via Unix socket / named pipe; falls back to direct connection when broker is busy (parallel execution) or unavailable
 - Short IDs are 8-char hex, support prefix resolution
+- Run ledger tracks per-invocation state (status, timing, output) under `runs/`
 - Bun is the TypeScript runtime — never use npm/yarn/pnpm for running
 - Skill installed to `~/.claude/skills/codex-collab/` via `install.sh` (build + copy; `--dev` for symlinks)

CONTRIBUTING.md

@@ -41,14 +41,21 @@ The codebase is organized into focused modules:
 
 | File | Purpose |
 |------|---------|
-| `src/cli.ts` | CLI commands, argument parsing, output formatting |
-| `src/protocol.ts` | JSON-RPC client for Codex app server |
-| `src/threads.ts` | Thread lifecycle, short ID mapping |
-| `src/turns.ts` | Turn lifecycle, event wiring |
-| `src/events.ts` | Event dispatcher, log writer |
+| `src/cli.ts` | CLI router, signal handlers |
+| `src/client.ts` | JSON-RPC client for Codex app server (spawn, handshake, request routing) |
+| `src/commands/` | CLI command handlers (run, review, threads, kill, config, approve) |
+| `src/broker.ts` | Shared app-server lifecycle (connection pooling, busy fallback) |
+| `src/broker-server.ts` | Detached broker process (multiplexes JSON-RPC between clients and app-server) |
+| `src/broker-client.ts` | Socket-based client for connecting to the broker server |
+| `src/threads.ts` | Thread index, run ledger, short ID mapping |
+| `src/turns.ts` | Turn lifecycle (runTurn, runReview), event wiring |
+| `src/events.ts` | Event dispatcher, log writer, output accumulator |
 | `src/approvals.ts` | Approval handler abstraction |
-| `src/types.ts` | Protocol types |
-| `src/config.ts` | Configuration constants |
+| `src/types.ts` | Protocol types (JSON-RPC, threads, turns, items, approvals) |
+| `src/config.ts` | Configuration constants, workspace resolution |
+| `src/process.ts` | Process spawn/lifecycle utilities |
+| `src/git.ts` | Git operations (diff, log, status) |
+| `src/reviews.ts` | Review validation, structured output parsing |
 
 ## Pull Requests
 

README.md

@@ -80,10 +80,11 @@ codex-collab run --resume <id> "now check error handling" --content-only
 |---------|-------------|
 | `run "prompt" [opts]` | Start thread, send prompt, wait, print output |
 | `review [opts]` | Code review (PR, uncommitted, commit) |
-| `jobs [--json] [--all]` | List threads (`--limit <n>` to cap) |
+| `threads [--json] [--all]` | List threads (`--limit <n>` to cap, `--discover` to scan server) |
 | `kill <id>` | Interrupt running thread |
 | `output <id>` | Full log for thread |
 | `progress <id>` | Recent activity (tail of log) |
+| `config [key] [value]` | Show or set persistent defaults |
 | `models` | List available models |
 | `health` | Check dependencies |
 
@@ -112,6 +113,7 @@ codex-collab run --resume <id> "now check error handling" --content-only
 | `--ref <hash>` | Commit ref for `--mode commit` |
 | `--resume <id>` | Resume existing thread |
 | `--approval <policy>` | Approval policy: never, on-request, on-failure, untrusted (default: never) |
+| `--template <name>` | Prompt template for run command (user `~/.codex-collab/templates/` or built-in) |
 | `--content-only` | Suppress progress lines; with `output`, return only extracted content |
 | `--timeout <sec>` | Turn timeout (default: 1200) |
 | `--base <branch>` | Base branch for PR review (default: main) |

README.zh-CN.md

@@ -80,10 +80,11 @@ codex-collab run --resume <id> "现在检查错误处理" --content-only
 |------|------|
 | `run "prompt" [opts]` | 新建会话、发送提示、等待完成并输出结果 |
 | `review [opts]` | 代码审查（PR、未提交更改、指定 commit） |
-| `jobs [--json] [--all]` | 列出会话（`--limit <n>` 限制数量） |
+| `threads [--json] [--all]` | 列出会话（`--limit <n>` 限制数量，`--discover` 扫描服务器） |
 | `kill <id>` | 中断运行中的会话 |
 | `output <id>` | 查看会话完整日志 |
 | `progress <id>` | 查看近期活动（日志尾部） |
+| `config [key] [value]` | 查看或设置持久化默认值 |
 | `models` | 列出可用模型 |
 | `health` | 检查依赖项 |
 
@@ -112,6 +113,7 @@ codex-collab run --resume <id> "现在检查错误处理" --content-only
 | `--ref <hash>` | 指定 commit 哈希（配合 `--mode commit`） |
 | `--resume <id>` | 恢复已有会话 |
 | `--approval <policy>` | 审批策略: never, on-request, on-failure, untrusted（默认: never） |
+| `--template <name>` | 提示词模板（run 命令；优先使用 `~/.codex-collab/templates/`，然后使用内置模板） |
 | `--content-only` | 隐藏进度输出；配合 `output` 时仅返回正文内容 |
 | `--timeout <sec>` | 单轮超时时间，单位秒（默认: 1200） |
 | `--base <branch>` | PR 审查的基准分支（默认: main） |

SKILL.md

@@ -11,7 +11,7 @@ codex-collab is a bridge between Claude and Codex. It communicates with Codex vi
 
 - **Run** — Single-command `run` for any prompted task (research, analysis, implementation). Starts a thread, sends prompt, waits for completion, returns output.
 - **Code review** — Single-command `review` for PR-style, uncommitted, or commit-level review.
-- **Parallel work** — You and Codex work on different parts simultaneously. Start multiple jobs.
+- **Parallel work** — You and Codex work on different parts simultaneously. Start multiple threads.
 - **Research** — Spin up a read-only Codex session to investigate something while you continue other work.
 
 ## Run Command (Recommended for Prompted Tasks)
@@ -32,20 +32,17 @@ codex-collab run --resume <id> "now check the error handling" --content-only
 codex-collab run "investigate the auth module" -d /path/to/project --content-only
 ```
 
-**IMPORTANT: Always use `dangerouslyDisableSandbox=true`** for all `codex-collab` Bash commands — the tool writes to `~/.codex-collab/` which is outside the sandbox allowlist.
+**IMPORTANT — Execution rules for ALL `codex-collab` Bash commands:**
+- Always use `dangerouslyDisableSandbox=true` — the tool writes to `~/.codex-collab/` which is outside the sandbox allowlist.
+- For `run` and `review`: also use `run_in_background=true` — these take minutes. After launching, tell the user it's running and end your turn. **While running**: do NOT poll, block, wait, or spawn an agent to monitor — you will be notified automatically when the task finishes. If other tasks complete while Codex is running, handle them normally without checking on Codex. **When notified**: read the completed task's output (the notification includes it or use `Read` on the output file), then present the results to the user.
+- For all other commands (`kill`, `threads`, `progress`, `output`, `approve`, `decline`, `clean`, `delete`, `models`, `health`): run in the **foreground** — they complete in seconds.
 
-For **`run` and `review`** commands, also use `run_in_background=true` — these take minutes. You will be notified automatically when the command finishes. After launching, tell the user it's running and end your turn. Do NOT use TaskOutput, block, poll, wait, or spawn an agent to monitor the result — the background task notification handles this automatically. If other background tasks complete while a Codex task is still running, handle those completed tasks normally — do NOT proactively check on, wait for, or poll the still-running Codex task. It will notify you when it finishes.
-
-For **all other commands** (`kill`, `jobs`, `progress`, `output`, `approve`, `decline`, `clean`, `delete`, `models`, `health`), run in the **foreground** — they complete in seconds.
-
-If the user asks about progress mid-task, use `progress` to check the recent activity:
+If the user asks about progress mid-task, use `TaskOutput(block=false)` to read the background output stream, or:
 
 ```bash
 codex-collab progress <id>
 ```
 
-Or use `TaskOutput(block=false)` to check the current output stream without blocking.
-
 ## Code Review (Recommended: Single Command)
 
 The `review` command handles the entire review workflow in one call.
@@ -69,9 +66,7 @@ codex-collab review "Focus on security issues" -d /path/to/project --content-onl
 codex-collab review --resume <id> -d /path/to/project --content-only
 ```
 
-Review modes: `pr` (default), `uncommitted`, `commit`
-
-**IMPORTANT: Use `run_in_background=true` and `dangerouslyDisableSandbox=true`** — reviews typically take 5-20 minutes. You will be notified automatically when done. After launching, tell the user it's running and end your turn. Do NOT use TaskOutput, block, poll, wait, or spawn an agent to monitor the result — the background task notification handles this automatically. If other background tasks complete while a review is still running, handle those completed tasks normally — do NOT proactively check on or wait for the review.
+Review modes: `pr` (default), `uncommitted`, `commit`, `custom`
 
 ## Context Efficiency
 
@@ -83,14 +78,20 @@ Review modes: `pr` (default), `uncommitted`, `commit`
 
 When consecutive tasks relate to the same project, resume the existing thread. Codex retains the conversation history, so follow-ups like "now fix what you found" or "check the tests too" work better when Codex already has context from the previous exchange. Start a fresh thread when the task is unrelated or targets a different project.
 
+**Before starting a new thread for a follow-up**, run `codex-collab resume-candidate --json` first. If it returns `{ "available": true, "threadId": "...", "shortId": "...", "name": "..." }`, use `--resume <shortId>` instead of starting fresh. This finds the best resumable thread across the current session, prior sessions, and TUI-created threads.
+
+The `--resume` flag accepts both ID formats:
+- `--resume <short-id>` — 8-char hex short ID (supports prefix matching, e.g., `a1b2`)
+- `--resume <thread-id>` — Full Codex thread ID (UUID, e.g., `019d680c-7b23-7f22-ab99-6584214a2bed`)
+
 | Situation | Action |
 |-----------|--------|
 | Same project, new prompt | `codex-collab run --resume <id> "prompt"` |
 | Same project, want review | `codex-collab review --resume <id>` |
 | Different project | Start new thread |
 | Thread stuck / errored | `codex-collab kill <id>` then start new |
 
-If you've lost track of the thread ID, use `codex-collab jobs` to find active threads.
+If you've lost track of the thread ID, use `codex-collab threads` to find active threads.
 
 ## Checking Progress
 
@@ -100,7 +101,7 @@ If the user asks about a running task, use `TaskOutput(block=false)` to read the
 codex-collab progress <thread-id>
 ```
 
-Note: `<thread-id>` is the codex-collab thread short ID (8-char hex from the output), not the Claude Code background task ID. If you don't have it, run `codex-collab jobs`.
+Note: `<thread-id>` is the codex-collab thread short ID (8-char hex from the output), not the Claude Code background task ID. If you don't have it, run `codex-collab threads`.
 
 Progress lines stream in real-time during execution:
 ```
@@ -165,13 +166,18 @@ codex-collab progress <id>              # Recent activity (tail of log)
 ### Thread Management
 
 ```bash
-codex-collab jobs                       # List threads
-codex-collab jobs --json                # List threads (JSON)
+codex-collab threads                    # List threads (current session)
+codex-collab threads --all              # List all threads (no display limit)
+codex-collab threads --discover         # Discover threads from Codex server
+codex-collab threads --json             # List threads (JSON)
+codex-collab resume-candidate --json    # Find best resumable thread
 codex-collab kill <id>                  # Stop a running thread
 codex-collab delete <id>               # Archive thread, delete local files
 codex-collab clean                      # Delete old logs and stale mappings
 ```
 
+Note: `jobs` still works as a deprecated alias for `threads`.
+
 ### Utility
 
 ```bash
@@ -190,32 +196,49 @@ codex-collab health                     # Check prerequisites
 | Flag | Description |
 |------|-------------|
 | `-m, --model <model>` | Model name (default: auto — latest available) |
-| `-r, --reasoning <level>` | Reasoning effort: low, medium, high, xhigh (default: auto — highest for model) |
+| `-r, --reasoning <level>` | Reasoning effort: none, minimal, low, medium, high, xhigh (default: auto — highest for model) |
 | `-s, --sandbox <mode>` | Sandbox: read-only, workspace-write, danger-full-access (default: workspace-write; review always uses read-only) |
 | `-d, --dir <path>` | Working directory (default: cwd) |
 | `--resume <id>` | Resume existing thread (run and review) |
-| `--timeout <sec>` | Turn timeout in seconds (default: 1200) |
+| `--timeout <sec>` | Turn timeout in seconds (default: 1200). Do not lower this — Codex tasks routinely take 5-15 minutes. Increase for large reviews or complex tasks. |
 | `--approval <policy>` | Approval policy: never, on-request, on-failure, untrusted (default: never) |
-| `--mode <mode>` | Review mode: pr, uncommitted, commit |
+| `--mode <mode>` | Review mode: pr, uncommitted, commit, custom |
 | `--ref <hash>` | Commit ref for --mode commit |
-| `--json` | JSON output (jobs command) |
+| `--all` | List all threads with no display limit (threads command) |
+| `--discover` | Query Codex server for threads not in local index (threads command) |
+| `--json` | JSON output (threads, resume-candidate commands) |
+| `--template <name>` | Prompt template for run command (checks `~/.codex-collab/templates/` first, then built-in) |
 | `--content-only` | Print only result text (no progress lines) |
 | `--limit <n>` | Limit items shown |
 
+## Templates
+
+Use `--template <name>` with the `run` command to wrap your prompt in a structured template.
+
+<!-- TEMPLATES -->
+
+Custom templates: place `.md` files with frontmatter in `~/.codex-collab/templates/`, then re-run the installer.
+
+## TUI Handoff
+
+To hand off a thread to the Codex TUI, look up the full thread ID with `codex-collab threads --json` and then run `codex resume <full-thread-id>` in the terminal.
+
 ## Tips
 
 - **`run --resume` requires a prompt.** `review --resume` works without one (it uses the review workflow), but `run --resume <id>` will error if no prompt is given.
 - **Omit `-d` if already in the project directory** — it defaults to cwd. Only pass `-d` when the target project differs from your current directory.
-- **Multiple concurrent threads** are supported. Each gets its own Codex app-server process and thread ID.
+- **Multiple concurrent threads** are supported. Threads share a per-workspace broker for efficient resource usage.
 - **Validate Codex's findings.** After reading Codex's review or analysis output, verify each finding against the actual source code before presenting to the user. Drop false positives, note which findings you verified.
+- **Per-workspace scoping.** Threads and state are scoped per workspace (git repo root). Different repos have independent thread lists.
+- **First invocation per workspace** may take slightly longer to initialize; subsequent calls in the same session reuse the connection context.
 
 ## Error Recovery
 
 | Symptom | Fix |
 |---------|-----|
 | "codex CLI not found" | Install: `npm install -g @openai/codex` |
-| Turn timed out | Increase `--timeout` or check if the task is too large |
-| Thread not found | Use `codex-collab jobs` to list active threads |
+| Turn timed out | Increase `--timeout` (e.g., `--timeout 1800` for 30 min). Large reviews and complex tasks often need more than the 20-min default. |
+| Thread not found | Use `codex-collab threads` to list active threads |
 | Process crashed mid-task | Resume with `--resume <id>` — thread state is persisted |
 | Approval request hanging | Run `codex-collab approve <id>` or `codex-collab decline <id>` |