agent-conveyor 0.1.7 → 0.1.9

package/docs/manager-recipes.md

@@ -259,6 +259,61 @@ conveyor worker-inbox "$TASK" --consume-next --wait --timeout 60 --json
 conveyor manager-inbox "$TASK" --consume-next --wait --timeout 60 --json
 ```
 
+Dispatch delivery is not a wake-up mechanism for idle Codex app threads. When
+`communication.requires_polling=true`, install or verify a thread heartbeat for
+each pull-required manager and worker session. The default heartbeat should run
+about every two minutes, poll the role-specific inbox once with a short wait,
+execute only a consumed item, and otherwise stop after a one-line idle receipt.
+Do not delete or pause heartbeat automation because an inbox poll is idle; idle
+polling is only a quiet interval. The manager or operator owns terminal loop
+teardown. When all accepted criteria are satisfied, deferred, or rejected and
+there is no next worker task, the manager should record the terminal decision,
+run `conveyor finish-task "$TASK" --require-criteria-audit`, and explicitly
+report heartbeat teardown status. If the task or binding still appears active,
+report that as a control-plane blocker instead of calling the loop complete.
+
+When the manager is running in the Codex app and thread tools are available,
+create fresh same-project manager and worker threads with `create_thread`, set
+readable titles, and pass both ids/titles into `conveyor
+create-disposable-binding` with `--manager-codex-app-thread-id`,
+`--manager-codex-app-thread-title`, `--worker-codex-app-thread-id`, and
+`--worker-codex-app-thread-title`. Use `send_message_to_thread` for bootstrap
+prompts only; ongoing manager/worker communication should still be routed
+through Dispatch and consumed from inboxes. If app thread tools are unavailable,
+open the worker session manually and paste the same `worker_handoff` prompt.
+Do not use `fork_thread` for this recipe unless the user explicitly wants a
+fork of the current conversation.
+
+### Codex App Native Manager/Worker Loop
+
+```bash
+conveyor doctor
+conveyor db-doctor
+conveyor create-disposable-binding "$TASK" \
+  --worker "$WORKER" \
+  --manager "$MANAGER" \
+  --worker-codex-app-thread-id "$WORKER_THREAD_ID" \
+  --worker-codex-app-thread-title "$WORKER_THREAD_TITLE" \
+  --manager-codex-app-thread-id "$MANAGER_THREAD_ID" \
+  --manager-codex-app-thread-title "$MANAGER_THREAD_TITLE" \
+  --adversarial \
+  --json
+conveyor dispatch --watch --dispatcher-id dispatch-local
+conveyor app-heartbeat "$TASK" --role manager --json
+conveyor app-heartbeat "$TASK" --role worker --json
+conveyor app-loop-status "$TASK" --json
+conveyor app-wakeup-plan "$TASK" --json
+conveyor app-wakeup-dispatch "$TASK" --json
+```
+
+Use `app-loop-status` as the operator status surface. If it reports stale
+manager, worker, or Dispatch leases, use `app-wakeup-plan` to get the exact
+thread prompt to send through Codex app automation or `send_message_to_thread`.
+Use `app-wakeup-dispatch` when the manager needs a durable Conveyor receipt for
+which app wake actions were prepared, skipped, or blocked. It only prepares
+adapter-ready actions; direct app-thread delivery remains an app/operator
+action, and Dispatch/inboxes remain the durable task state.
+
 The saved dogfood example is
 `docs/goals/live-codex-app-inbox-drill/notes/T001-live-drill.md`. It proves
 manager-to-worker `nudge_worker` delivery and worker-to-manager
@@ -286,6 +341,59 @@ acceptance criteria, command attempts, routed notifications, inbox backlog, and
 telemetry before deciding whether to wait, nudge, continue, compact, clear, or
 finish.
 
+## Package Dogfood Command
+
+Use a disposable workspace and explicit database path when checking the
+package-facing `goalbuddy-conveyor` recipe flow. The point is to prove the
+published package, not a local checkout.
+
+```bash
+mkdir -p /tmp/agent-conveyor-dogfood/workspace
+git -C /tmp/agent-conveyor-dogfood/workspace init
+
+conveyor pair \
+  --task dogfood-goalbuddy \
+  --worker-name dogfood-worker \
+  --manager-name dogfood-manager \
+  --task-goal "Dogfood the published package GoalBuddy conveyor recipe." \
+  --task-prompt "Create docs/dogfood-note.md with a short received-task note and report a concise receipt." \
+  --manager-recipe goalbuddy-conveyor \
+  --manager-mode strict \
+  --manager-objective "Run a one-child-at-a-time GoalBuddy conveyor until the disposable task is proven satisfied or blocked with evidence." \
+  --manager-guideline "Keep exactly one child board active at a time." \
+  --manager-guideline "Before activating the next child, update the parent receipt." \
+  --manager-acceptance "The disposable worker task has a receipt showing the note file was created or a blocker was recorded." \
+  --manager-acceptance "Manager config records the selected goalbuddy-conveyor recipe." \
+  --manager-allow-worker-compact-clear \
+  --manager-allow-pr \
+  --manager-allow-merge-green \
+  --manager-tool verification.run_tests \
+  --manager-tool context.fetch_prs \
+  --manager-epilogue draft-pr \
+  --manager-epilogue record-handoff \
+  --cwd /tmp/agent-conveyor-dogfood/workspace \
+  --path /tmp/agent-conveyor-dogfood/workerctl.db \
+  --accept-trust
+```
+
+Expected clean transcript shape:
+
+```text
+pair exits 0
+dispatcher watch starts from an executable shipped with the package
+manager_config.recipe_name = goalbuddy-conveyor
+manager-ack and worker-ack are recorded against the same --path database
+cycle shows worker_receipt for docs/dogfood-note.md
+criteria --list shows all accepted criteria satisfied
+finish-task --require-criteria-audit marks the task done
+```
+
+If a dogfood run needs an operator to add `--path`, find the active database, or
+replace a missing source-tree path with the installed `workerctl` bin, the
+package setup is not yet ready for unattended dogfooding. Record the friction in
+the dogfood board so the next recipe or prompt pass has something concrete to
+fix.
+
 ## What The Database Records
 
 The SQLite control plane is the audit surface for these recipes.

package/docs/typescript-migration/cli-contract.md

@@ -1,26 +1,23 @@
 # TypeScript Migration CLI Contract
 
-This contract freezes the current Python CLI surface before TypeScript migration.
-The TypeScript CLI must preserve this surface unless a Judge receipt explicitly
-approves and documents a diff.
+This contract records the archived Python CLI surface from before the
+TypeScript migration. The TypeScript CLI must preserve this surface unless a
+Judge receipt explicitly approves and documents a diff.
 
 ## Public Entry Points
 
-- `conveyor` package-installed command from `pyproject.toml`.
-- `workerctl` package-installed compatibility command from `pyproject.toml`.
+- `conveyor` package-installed command from `package.json`.
+- `workerctl` package-installed compatibility command from `package.json`.
 - `bin/conveyor` local wrapper.
 - `bin/workerctl` local wrapper.
 - `scripts/workerctl` repository-local entry point.
-- `python -m workerctl` until Python compatibility is retired by an explicit
-  migration decision.
 
-Program name behavior must preserve both `conveyor` and `workerctl`. The Python
-implementation currently selects the name from `CONVEYOR_CLI_PROG`, the
-invoked filename, or defaults to `conveyor`.
+Program name behavior must preserve both `conveyor` and `workerctl`.
 
 ## Command Inventory
 
-Source of truth: `scripts/workerctl --help` and `workerctl/cli.py`.
+Source of truth: `scripts/workerctl --help` and the archived command inventory
+at `docs/archive/python-runtime/cli-command-inventory.json`.
 
 The top-level command inventory to preserve is:
 
@@ -139,9 +136,9 @@ artifact for:
 scripts/workerctl --help
 CONVEYOR_CLI_PROG=conveyor scripts/workerctl --help
 CONVEYOR_CLI_PROG=workerctl scripts/workerctl --help
-rg -n "add_parser\\(|set_defaults\\(" workerctl/cli.py
+node scripts/ts-migration-audit.mjs --require-zero-python
 ```
 
 The TypeScript implementation must have an adjudicated command/flag diff against
-the Python surface. Unreviewed missing commands, missing aliases, changed JSON
-shape, or changed help program name block migration completion.
+the archived Python surface. Unreviewed missing commands, missing aliases,
+changed JSON shape, or changed help program name block migration completion.

package/docs/typescript-migration/package-install-contract.md

@@ -26,7 +26,7 @@ The historical Python metadata exposed:
 - package name `agent-conveyor`
 - console script `conveyor`
 - compatibility console script `workerctl`
-- bundled `workerctl/assets/skills/**/*`
+- bundled `workerctl/assets/skills/**/*` in the historical wheel
 
 The historical Python/PyPI release path is archived in
 `docs/archive/python-package-history.md`.

package/docs/typescript-migration/qa-gate-matrix.md

@@ -6,32 +6,26 @@ run or inspect evidence that would expose it, and record residual risk.
 
 ## Deterministic Local Gates
 
-Current baseline before the migration board:
+Current post-archive baseline:
 
 | Gate | Command | Current baseline |
 | --- | --- | --- |
-| Python unit tests | `python3 -m unittest discover -s tests -v` | pass, 645 tests |
-| ResourceWarning gate | `scripts/check-resource-warnings` | pass, 645 tests |
-| Python compile gate | `python3 -m py_compile scripts/workerctl scripts/check-resource-warnings workerctl/*.py` | pass |
+| Node test ResourceWarning gate | `scripts/check-resource-warnings -- npm test -- --runInBand` | pass |
 | Node/dashboard tests | `npm test -- --runInBand` | pass, 161 tests |
 | Dashboard build | `npm run build` | pass |
 | TypeScript migration audit | `npm run migration:audit:final` | pass after package cutover; npm tarball has no Python runtime/bridge files |
 | Shell syntax | `bash -n scripts/live-smoke scripts/live-smoke-repeat scripts/package-smoke scripts/release-check scripts/rc-check` | pass |
 
-While Python remains in the repository, the Python gates remain required. A
-TypeScript replacement may retire them only after equivalent TypeScript gates
-and package smoke prove the migrated command surface no longer imports or
-executes Python for the migrated paths.
+The archived Python runtime lives under `docs/archive/python-runtime` for
+historical inspection only. Active gates must use the TypeScript runtime and
+Node-based release helpers.
 
 ## Release-Candidate Gate
 
 `scripts/rc-check --skip-live-smoke-repeat` currently runs:
 
-- Python unittest.
-- ResourceWarning gate.
-- Python compile gate.
-- TypeScript migration audit.
-- Dashboard tests.
+- Node test ResourceWarning gate.
+- TypeScript migration final audit.
 - Dashboard build.
 - Smoke script syntax checks.
 

package/docs/typescript-migration/sqlite-state-contract.md

@@ -84,9 +84,8 @@ Useful commands:
 
 ```bash
 WORKERCTL_STATE_ROOT="$(mktemp -d)" scripts/workerctl db-doctor --json
-python3 -m unittest tests.test_workerctl.DatabaseTests tests.test_workerctl.SessionsSchemaTests tests.test_workerctl.CodexEventsSchemaTests -v
-python3 -m py_compile workerctl/*.py
+npm test -- --runInBand
 ```
 
 Completion is blocked if the TypeScript-created schema differs from the
-Python-created schema without a recorded Judge decision.
+archived schema contract without a recorded Judge decision.

package/docs/typescript-migration/t005-runtime-parity.md

@@ -8,16 +8,16 @@ away from the compatibility bridge yet.
 
 | Python source | TypeScript source | Proof |
 | --- | --- | --- |
-| `workerctl/tmux.py` command builders, permission text, paste-buffer cleanup, session pane targeting | `src/runtime/tmux.ts` | `src/runtime/runtime.test.ts` covers argument order, liveness checks, permission normalization, cleanup on failure, pane targets, and side-effect audit flags. |
-| `workerctl/codex_session.py` session metadata, native pid selection, lsof rollout lookup, discovery result shape | `src/runtime/codex-session.ts` | `src/runtime/runtime.test.ts` covers metadata parsing, lsof path extraction, pid-to-native-child selection, and end-to-end discovery with fixtures. |
-| `workerctl/ingest.py` JSONL parser and one-session ingest cycle | `src/runtime/ingest.ts` | `src/runtime/runtime.test.ts` covers offsets, malformed complete lines, partial trailing lines, event persistence, heartbeat/offset update, telemetry, idempotent re-ingest, appended partial completion, and shrink refusal. |
-| `workerctl/classify.py` startup and busy-wait classifier | `src/runtime/classify.ts` | `src/runtime/runtime.test.ts` covers Python classifier scenarios: trust, ready, working, empty, error, MCP startup, rate limit, Enter confirmation, trust prompt, plan prompt, active approval, historical approval negative control, fresh status suppression, and recent-event long-running suppression. |
+| archived `workerctl/tmux.py` command builders, permission text, paste-buffer cleanup, session pane targeting | `src/runtime/tmux.ts` | `src/runtime/runtime.test.ts` covers argument order, liveness checks, permission normalization, cleanup on failure, pane targets, and side-effect audit flags. |
+| archived `workerctl/codex_session.py` session metadata, native pid selection, lsof rollout lookup, discovery result shape | `src/runtime/codex-session.ts` | `src/runtime/runtime.test.ts` covers metadata parsing, lsof path extraction, pid-to-native-child selection, and end-to-end discovery with fixtures. |
+| archived `workerctl/ingest.py` JSONL parser and one-session ingest cycle | `src/runtime/ingest.ts` | `src/runtime/runtime.test.ts` covers offsets, malformed complete lines, partial trailing lines, event persistence, heartbeat/offset update, telemetry, idempotent re-ingest, appended partial completion, and shrink refusal. |
+| archived `workerctl/classify.py` startup and busy-wait classifier | `src/runtime/classify.ts` | `src/runtime/runtime.test.ts` covers classifier scenarios: trust, ready, working, empty, error, MCP startup, rate limit, Enter confirmation, trust prompt, plan prompt, active approval, historical approval negative control, fresh status suppression, and recent-event long-running suppression. |
 
 ## Bridge Decision
 
-Public `conveyor` and `workerctl` command handlers still intentionally route
-through `src/cli/python-bridge.ts` for T005. That preserves the frozen CLI
-contract while the runtime modules move to TypeScript in testable pieces.
+This note records the historical T005 bridge decision. The public `conveyor`
+and `workerctl` command handlers now use the TypeScript runtime; the Python
+runtime is archived under `docs/archive/python-runtime`.
 
 The remaining command-handler migration belongs to T006/T007:
 
@@ -26,9 +26,9 @@ The remaining command-handler migration belongs to T006/T007:
 - T007 owns npm package/install/release/CI/docs conversion and final tarball
   behavior.
 
-This means T005 is complete when the TypeScript runtime helpers pass local
-gates and the Python compatibility suite still passes. It does not claim that
-the public CLI no longer executes Python.
+T005 was complete when the TypeScript runtime helpers passed local gates while
+the compatibility bridge was still present. Later migration stages removed the
+bridge and archived the Python runtime.
 
 ## Strongest Failure Mode
 
@@ -40,8 +40,8 @@ or CLI error behavior.
 Disproof evidence:
 
 - Node runtime tests exercise the TypeScript behavior directly.
-- The full Python compatibility suite still passes under an isolated state
-  root, proving the bridge-backed public CLI behavior was not regressed.
+- The archived command inventory and TypeScript migration audit preserve the
+  historical CLI contract without executing Python.
 - `npm run build` proves the TypeScript helper API compiles into the package.
 - The GoalBuddy board keeps T006/T007 queued for public command-handler and
   package-routing migration before final completion.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-conveyor",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Local agent manager/worker conveyor control plane for Codex sessions.",
   "license": "MIT",
   "type": "module",

package/skills/manage-codex-workers/SKILL.md

@@ -6,8 +6,8 @@ description: Use when the user asks to set up an Agent Conveyor Ralph loop, regi
 # Manage Codex Workers
 
 Use `conveyor ...` as the primary CLI. It is installed by the `agent-conveyor`
-Python package. The legacy `workerctl` command remains a compatibility alias,
-but skill-driven flows should prefer `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
 
@@ -35,25 +35,71 @@ Skill behavior:
    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. Create the no-tmux binding with `conveyor create-disposable-binding`
+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`
    using `--template` when a template is known, `--adversarial`, a bounded
-   `--max-iterations`, and `--json`.
-5. Ensure Dispatch is running or tell the user the single command to start it:
+   `--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`.
-6. Read the returned `communication` blocks. A worker or manager with
+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 inbox command.
-7. Give the worker Codex app session the generated `worker_handoff` prompt.
-   It should keep polling `conveyor worker-inbox <task> --consume-next --wait
-   --timeout 60 --json` through the bounded loop until no inbox item remains
-   or `max_iterations` is reached.
-8. After each worker pass, require concrete evidence and structured
+   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.
+9. After each worker pass, require concrete evidence and structured
    `loop-evidence adversarial-check` proof before queueing another
    `enqueue-continue-iteration`.
-9. Use `conveyor loop-status <task> --run <run> --json` and telemetry/audit
+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.
+- 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.
+- 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
@@ -77,6 +123,9 @@ Supervision is built on three primitives: **sessions**, **tasks**, and
   `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.
 
@@ -224,6 +273,15 @@ 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
@@ -433,7 +491,7 @@ manager decision, then run:
 ```bash
 decision_id=$(conveyor record-decision my-task nudge \
   --reason "Worker context should be compacted after handoff" \
-  | python3 -c 'import json,sys; print(json.load(sys.stdin)["id"])')
+  | node -e 'const fs = require("fs"); console.log(JSON.parse(fs.readFileSync(0, "utf8")).id)')
 conveyor request-worker-compact my-task \
   --decision-id "$decision_id" --strict-decisions
 ```
@@ -567,7 +625,7 @@ Criteria command examples:
 conveyor criteria my-task --list
 conveyor criteria my-task --add --criterion "..." --source worker_proposed --status proposed
 conveyor criteria my-task --accept 12 --rationale "Must-have for this task"
-conveyor criteria my-task --satisfy 12 --evidence-json '{"command":"python3 -m unittest tests.test_workerctl.ManagerBootstrapPromptTests -v","status":"pass"}'
+conveyor criteria my-task --satisfy 12 --evidence-json '{"command":"npm test -- --runInBand","status":"pass"}'
 conveyor criteria my-task --defer 13 --rationale "Follow-up after this task"
 conveyor criteria my-task --reject 14 --rationale "Duplicate or out of scope"
 ```
@@ -576,8 +634,8 @@ Replace placeholder `...` values with the actual criterion and verification
 command. To add a criterion and satisfy that same row after verification:
 
 ```bash
-criterion_id=$(conveyor criteria my-task --add --criterion "Targeted prompt tests pass" --source worker_proposed --status proposed | python3 -c 'import json,sys; print(json.load(sys.stdin)["affected_criterion"]["id"])')
-conveyor criteria my-task --satisfy "$criterion_id" --evidence-json '{"command":"python3 -m unittest tests.test_workerctl.ManagerBootstrapPromptTests -v","status":"pass"}'
+criterion_id=$(conveyor criteria my-task --add --criterion "Targeted prompt tests pass" --source worker_proposed --status proposed | node -e 'const fs = require("fs"); console.log(JSON.parse(fs.readFileSync(0, "utf8")).affected_criterion.id)')
+conveyor criteria my-task --satisfy "$criterion_id" --evidence-json '{"command":"npm test -- --runInBand","status":"pass"}'
 ```
 
 When making multiple criteria changes, use each mutation response's
@@ -681,6 +739,20 @@ etc.) run `conveyor db-doctor --live`.
 
 ## Natural-Language Command Mapping
 
+- "set up a Codex app Ralph loop": if the current session has Codex app thread
+  tools, call `create_thread` for fresh same-project manager and worker
+  threads unless the current thread is explicitly the manager, set readable
+  titles, run `conveyor create-disposable-binding` with both
+  `--manager-codex-app-thread-id`/`--manager-codex-app-thread-title` and
+  `--worker-codex-app-thread-id`/`--worker-codex-app-thread-title`, then send
+  the returned bootstrap prompts using `send_message_to_thread`. If those tools
+  are unavailable, run `create-disposable-binding` without thread metadata and
+  give the user the handoff prompts to paste into manually opened sessions. Keep
+  Dispatch as the source of durable communication, and make both Codex app
+  sessions repeat their role-specific `app-heartbeat` command while idle. Use
+  `app-loop-status` and `app-wakeup-plan` for operator status and stale-thread
+  recovery, and `app-wakeup-dispatch` when the manager needs an auditable
+  prepared/skipped/blocked wake receipt.
 - "register this Codex session as the worker for dashboard setup <CODE>":
   derive `dashboard-<CODE>-worker`, run `conveyor doctor-self`, then
   `conveyor register-worker --name dashboard-<CODE>-worker --pid <PID> --cwd <CWD> --tmux-session <SESSION>`.