manage-codex-workers

# Manage Codex Workers Use `conveyor ...` as the primary CLI. It is installed by the `agent-conveyor` Node/TypeScript package. The legacy `workerctl` command remains a compatibility alias, but skill-driven flows should prefer `conveyor`. ## One-Prompt Codex App Ralph Loop This is the preferred entry point when the user has installed Agent Conveyor and wants to use another Codex app session without learning the low-level command sequence. User prompt: ```text Use the manage-codex-workers skill. Set up a Codex app Ralph loop for issue CTL. Worker session: <worker-name or choose one> Manager session: <manager-name or choose one> Template: <template name, or choose the best one> Max iterations: <number, default 3> Require adversarial proof before another worker iteration. ``` For repo delivery where the user explicitly grants branch, PR, CI, conflict, and merge authority, use the `ship-it-loop` recipe and `ship_it_loop` template instead of a generic Ralph loop: ```text Use the manage-codex-workers skill. Set up a Codex app autonomous ship-it loop for <bounded repo task>. Manager may push a branch, open a PR, monitor CI, resolve bounded conflicts, and merge only after explicit manager merge evidence. Max iterations: <number, default 2> ``` For creative-ops work where the user wants one manager to supervise multiple Codex app workers across channels such as YouTube, TikTok, LinkedIn, Facebook, image generation, HyperFrames, or copy drafts, use the Creative Ops Campaign recipe. It should create campaign records, worker slots, channel briefs, slot-scoped assignments, asset receipts, and dashboard status proof. It must not imply public publishing or scheduling without explicit human approval. Skill behavior: 1. Work from `/Users/neonwatty/Desktop/codex-terminal-manager`. 2. Run `conveyor doctor` and `conveyor db-doctor`; fix or report blockers. 3. Choose concise task, worker, manager, and run names when the user does not provide them. Do not ask the user to invent generated names. 4. Preferred fully app-native setup: if running in the Codex app and thread tools are available, create fresh same-project manager and worker threads with `create_thread`, give both readable titles, and keep both returned thread ids/titles. Use `create_thread` for this flow; do not use `fork_thread` unless the user explicitly asks to fork or resume this exact conversation. If the current thread is explicitly acting as the manager, use the current thread as manager and create only the worker thread. 5. Create the no-tmux binding with `conveyor create-disposable-binding`. For same-thread Codex app visible-session loops, prefer `--template app_visible_build_loop` for build/test dogfood or a custom `--required-before-continue adversarial_check` gate; do not choose cleanup-gated templates such as `build_then_clear` or `compact_then_continue` unless the setup creates a fresh worker thread per iteration or has a concrete app-session cleanup receipt path. For an operator-approved ship-it loop, use `--template ship_it_loop`, save the `ship-it-loop` manager recipe, and require branch, push, PR, CI, mergeability, manager merge decision, merge, post-merge, and `adversarial_check` receipts before merge or closeout. Use `--adversarial`, a bounded `--max-iterations`, and `--json`. When step 4 produced app thread ids, pass them through `--manager-codex-app-thread-id`, `--manager-codex-app-thread-title`, `--worker-codex-app-thread-id`, and `--worker-codex-app-thread-title` so Conveyor can surface app identities in `sessions`, `discover`, and setup JSON. If app thread tools are not available, create the binding without those flags and ask the user to open separate Codex app sessions manually. 6. Ensure Dispatch is running or tell the user the single command to start it: `conveyor dispatch --watch --dispatcher-id dispatch-local`. 7. Read the returned `communication` blocks. A worker or manager with `session_kind=tmux` and `receive_style=push` can receive direct tmux pushes; one with `session_kind=codex_app` and `receive_style=pull` must poll the printed `app-heartbeat` command, using direct inbox commands only when the heartbeat output or setup JSON provides them as fallbacks. 8. Give the worker Codex app session the generated `worker_handoff` prompt. If step 4 created a fresh worker thread, use `send_message_to_thread` only to deliver that bootstrap prompt. Durable manager/worker communication still goes through Dispatch and `worker-inbox`/`manager-inbox`; direct app-thread messages are not Dispatch receipts. The worker should keep polling the exact command printed in the `worker_handoff` prompt through the bounded loop until no inbox item remains or `max_iterations` is reached. Consuming a `continue_iteration` inbox item advances the Ralph-loop run's durable `current_iteration` and writes `ralph_loop_iteration_advanced` telemetry. After completing or blocking on any consumed item, the worker must run the generated `conveyor enqueue-notify-manager ... --json` command and then run the generated one-iteration `conveyor dispatch --watch ... --json` command before its final app-thread answer. If either command fails, treat that as the blocker; a direct app-thread final answer alone is not manager notification and is not task completion. 9. After each worker pass, require concrete evidence and structured `loop-evidence adversarial-check` proof before queueing another `enqueue-continue-iteration`. 10. Use `conveyor loop-status <task> --run <run> --json` and telemetry/audit receipts before declaring the loop ready for manager review. Idle polling rule for Codex app/no-tmux sessions: - When a worker has `session_kind=codex_app` or `receive_style=pull`, its default idle/check-in command is the returned `app-heartbeat` worker command. Use `communication.poll_command` or the generated `worker_handoff` command as fallback/direct inbox polling. - When a manager has `session_kind=codex_app` or `receive_style=pull`, its default idle/check-in command is the returned `app-heartbeat` manager command. Use `communication.poll_command` as fallback/direct inbox polling. - The printed command may include a local `PATH=.../bin:$PATH conveyor` prefix; preserve that prefix when giving the command to a Codex app thread. - Repeat the appropriate command whenever the session is idle, after finishing a received instruction, and before deciding there is nothing more to do. A timeout is not completion; it is only a quiet poll interval. - Keep `conveyor dispatch --watch --dispatcher-id dispatch-local` running so Dispatch can route new messages into those inboxes. - After a worker consumes and acts on a manager instruction, require a durable `conveyor enqueue-notify-manager <task> --message ... --json` receipt plus a one-iteration Dispatch run before treating the worker pass as reported. A direct Codex app final answer is local thread text; it does not notify the manager inbox or prove the manager saw the result. - The actual manager and worker sessions are the primary human-reviewable transcript. SQLite, replay, and status commands are audit proof, not a substitute for visible work. When a manager or worker consumes an inbox item, it must print live session sections before acting and before final answer: `CONVEYOR POLL`, `CONVEYOR RECEIVED`, `WORK`, `CONVEYOR SEND`, and `DISPATCH`. Idle polls may end with one short `CONVEYOR IDLE` receipt, but consumed work must never be handled silently or only summarized later. - Prefer `conveyor app-autopilot start <task> --json` from the operator or manager session when setting up a Codex app/no-tmux pair for autonomous heartbeat management. It records a durable pair-level heartbeat policy and emits manager/worker Codex app heartbeat automation specs plus the bounded Dispatch watch command. Use `conveyor app-autopilot status <task> --json` to inspect the current policy, loop health, and `plan.quiescence`. If `plan.quiescence.recommended_action` is `stop_autopilot`, the operator should record `conveyor app-autopilot stop <task> --json` and pause/delete the Codex app heartbeat automations instead of sending another idle pulse. Use `--quiet-after N` to tune the number of paired manager/worker idle heartbeats required before that recommendation. The CLI cannot create or delete Codex app automations by itself; apply the emitted automation specs through Codex app automation tools. - Use `conveyor app-loop-status <task> --json` as the operator status surface, and `conveyor app-wakeup-plan <task> --json` to produce exact stale-thread wake prompts for Codex app automation or `send_message_to_thread`. - Use `conveyor app-wakeup-dispatch <task> --json` when the manager needs an auditable wake orchestration receipt. It prepares adapter-ready app-thread actions, reports skipped and blocked roles, and records telemetry; it does not send direct app-thread messages itself. - If `create-disposable-binding --json` returned `heartbeat_recommendations.wakeup_dispatch_command` and `heartbeat_recommendations.delivery_receipt_commands`, prefer those exact generated commands when waking app threads and recording sent/skipped/blocked outcomes. - In a Codex app manager with thread tools available, use the native `send_message_to_thread` tool only for `app-wakeup-dispatch` actions where `send_ready=true`. After each send, run `conveyor app-wakeup-record-delivery <task> --role <role> --dispatch-receipt <receipt.event_id> --delivery-status sent --thread-id <action.thread.id> --json`. For `skipped_healthy` actions, record `--delivery-status skipped`; for `blocked_missing_thread`, record `--delivery-status blocked`. These delivery receipts audit app-thread wake attempts; they do not replace Dispatch inbox, heartbeat, or task evidence. - For Codex app/no-tmux worker cleanup, do not rely on sending `/compact` or `/clear` with `send_message_to_thread`; that arrives as ordinary prompt text. Prefer `conveyor app-worker-rotation-plan <task> --old-worker-thread-id <active-worker-thread-id> --require-handoff --json`. Only if the plan reports `eligible=true`, create the replacement worker thread from the emitted `create_replacement_worker_thread.prompt`, archive exactly the emitted `archive_old_worker_thread.thread.id`, then run the emitted `app-worker-rotation-record` command with the new thread id/title. The manager must never archive a thread that is not the active bound worker in the current plan. - For bounded Ralph loops, treat `ralph_loop_iteration_advanced` telemetry as the receipt that a worker actually consumed and began the requested iteration. Reference docs: - `README.md` command reference - `docs/qa/ralph-loop-operator-guide.md` - `docs/agent-evidence-playbook.md` ## Supervision Model Supervision is built on three primitives: **sessions**, **tasks**, and **bindings**. - A **worker session** is a Codex session registered with Agent Conveyor. It may be a tmux-backed session or a Codex app/no-tmux session. Its rollout JSONL on disk (`~/.codex/sessions/.../rollout-*.jsonl`, or a disposable rollout file) is the source of truth for ingest. - A **manager session** is a Codex session that can run anywhere — Ghostty, iTerm2, Terminal.app, a web terminal. The manager does not need tmux. Its job is to call `conveyor` commands, read their JSON output, and decide what to do next. - Registration, `sessions`, `discover`, and disposable binding JSON include a `communication` block. Use it to decide the receive style for both worker and manager: tmux sessions are push-capable, while Codex app/no-tmux sessions receive through `manager-inbox` or `worker-inbox` polling. - App-assisted setup may also record optional `codex_app_thread_id` and `codex_app_thread_title` metadata. This identifies the human-readable Codex app thread; it does not replace rollout ingest or Dispatch inbox receipts. - A **task** is a unit of supervised work with a goal. - A **binding** ties one worker session and one manager session to one task. The manager Codex drives the supervision loop by calling `conveyor cycle <task>` repeatedly. Each cycle ingests new rollout events, captures the worker's tmux pane as a shadow signal, persists a `manager_cycles` row, and returns structured JSON. The manager reads that JSON and decides. Dispatch is core infrastructure for supervised pairs. The `pair` workflow starts a detached Dispatch watch process by default after worker/manager setup and bind. For manually bound pairs, keep Dispatch running in another shell with: ```bash conveyor dispatch --watch --dispatcher-id dispatch-local ``` Dispatch wakes the bound manager on worker completion and executes queued `notify_manager` / `nudge_worker` commands. It does not decide whether the task is correct or finished. ## Preflight 1. Work from the control repo: ```bash cd /Users/neonwatty/Desktop/codex-terminal-manager ``` 2. Verify dependencies: ```bash conveyor doctor ``` 3. Verify the SQLite control plane is healthy: ```bash conveyor db-doctor ``` 4. From the current Codex session, check whether it can register itself: ```bash conveyor doctor-self ``` `supported: true` means the session is inside a live tmux session and can be registered as a worker. A non-tmux session can still be registered as a manager. ## Discovery For Q&A When the user asks which worker, manager, task, or binding to connect, search the control plane first and present likely choices instead of asking for generated names: ```bash conveyor discover <query> conveyor search <query> ``` Use an empty query to list active candidates. Add `--all` only when the user is looking for completed tasks or gone sessions. The JSON output includes `tasks`, `sessions`, `bindings`, `telemetry`, and `suggestions`; use `suggestions` to offer concise next steps such as a `conveyor bind` command or the prompt to register a missing worker or manager. ## Preferred Manual Handoff Workflow When the user wants to hand off an already-open Codex session, do not start with a long `pair` command. Use the skill in each session: 1. In the intended worker session, ask Codex: ```text Use the manage-codex-workers skill. Register this current Codex session as the worker for this dashboard setup. Dashboard setup code: <setup-code> Working directory: <target-repo> Let the skill derive the task and session names from the setup code. Do not ask me to type generated worker, manager, or task names. After registration, wait for the manager. Do not start work until the manager has created or bound the task and provided acceptance criteria. ``` 2. In a separate manager session, ask Codex: ```text Use the manage-codex-workers skill. Register this current Codex session as the manager for this dashboard setup. Dashboard setup code: <setup-code> Working directory: <target-repo> Goal: <goal> Let the skill derive the task and session names from the setup code, find the matching worker, create/configure the task if needed, and bind the worker and manager. Run cycles, inspect criteria and telemetry, nudge only when useful, require evidence, and finish/export the task when done. ``` 3. The manager session should then drive the loop with: ```bash conveyor cycle <task-name> conveyor criteria <task-name> --list conveyor telemetry --summary --task <task-name> conveyor telemetry --task <task-name> conveyor replay <task-name> ``` For `pair`-started workflows, Dispatch is started automatically unless `--no-dispatch` is passed. For manually bound pairs, keep `conveyor dispatch --watch --dispatcher-id dispatch-local` running in a separate shell while the pair is active, or run a bounded verification pass with `conveyor dispatch --watch --watch-iterations 2 --dry-run --json`. The skill should translate those prompts into explicit `conveyor` commands. For the worker, run `doctor-self`; if supported, register the current session with `register-worker`. For the manager, register the current session with `register-manager`, create/configure the task if needed, then `bind`. When the prompt includes a dashboard setup code, derive names without asking the user: ```text task: dashboard-<setup-code> worker: dashboard-<setup-code>-worker manager: dashboard-<setup-code>-manager ``` If there is already a registered worker for the derived worker name, reuse it when binding the manager. If the derived name collides with an active unrelated session, append a short suffix yourself and continue; do not ask the user to invent names. If the prompt has no setup code and no explicit names, choose concise names from the task goal or current date yourself. Ask the user only when the target repo or goal is missing or ambiguous. This is the ergonomic manual workflow. Use `pair` only when the user wants conveyor to spawn both sessions in one automated command. ## Register Sessions Register an already-running Codex worker (rollout JSONL is auto-discovered from the pid via `lsof`): ```bash conveyor register-worker --name foo --pid <WORKER_PID> \ --cwd "$PWD" --tmux-session codex-foo ``` When a Codex app tool created or identified the thread, preserve that identity with optional metadata flags: ```bash conveyor register-worker --name foo --pid <WORKER_PID> \ --cwd "$PWD" --codex-app-thread-id <THREAD_ID> \ --codex-app-thread-title "Human readable title" ``` If `lsof` discovery fails, pass the rollout path explicitly: ```bash conveyor register-worker --name foo --pid <WORKER_PID> \ --cwd "$PWD" --tmux-session codex-foo \ --codex-session ~/.codex/sessions/.../rollout-...-<uuid>.jsonl ``` Register a manager (tmux not required): ```bash conveyor register-manager --name foo-mgr --pid <MGR_PID> --cwd "$PWD" ``` For new manager sessions started by Agent Conveyor, prefer `start-manager` or `pair`. These send a manager bootstrap prompt to Codex so the rollout JSONL is opened during startup and the manager has setup context. In `pair`, the manager prompt includes the task name, goal, worker session, `manager-config <task> --questions`, and `cycle <task>`. For late attach, pass the known task context directly: ```bash conveyor start-manager --name foo-mgr --cwd "$PWD" \ --task foo-task --task-goal "..." --worker foo-worker ``` That bootstrap starts with concrete `manager-config`, `cycle`, `manager-ack`, and `worker-ack` commands instead of `<task>` placeholders. If manager config has already been recorded for the task, the bootstrap tells the manager to start with `cycle`. List registered sessions: ```bash conveyor sessions conveyor sessions --role worker conveyor sessions --role manager ``` ## Create A Task And Bind For automated bootstrap of a fresh supervised worker/manager pair, use `pair` instead of manually starting and binding sessions: ```bash conveyor pair \ --task <task-slug> \ --worker-name <worker-name> \ --manager-name <manager-name> \ --dispatcher-id dispatch-pair \ --cwd <target-repo> \ --codex-profile yolo \ --manager-mode strict \ --task-goal "<one-line goal>" \ --task-prompt "<worker prompt>" \