agent-conveyor 0.1.7 → 0.1.9

package/README.md

@@ -131,6 +131,10 @@ successful JSON. Treat that warning as expected Node runtime noise when the
 command exits 0 and the JSON result reports `"ok": true`.
 Before publishing `agent-conveyor` to npm, use
 [`docs/package-release.md`](docs/package-release.md).
+The preferred publish path is the manual GitHub Actions `publish.yml` workflow
+with npm Trusted Publishing enabled for the `npm-production` environment. Use
+`publish=false` for artifact review and `publish=true` only for an approved
+release version that is not already on npm.
 
 For common manager setups, start with
 [`docs/manager-recipes.md`](docs/manager-recipes.md). It maps natural-language
@@ -144,6 +148,10 @@ For a package-facing overview of these modes, open
 [`docs/landing-page.html`](docs/landing-page.html) locally or host it as a
 static landing page. From the repo, `npm run docs:landing` serves it at
 `http://127.0.0.1:8765/`.
+The GitHub Pages version lives at
+[`neonwatty.github.io/agent-conveyor`](https://neonwatty.github.io/agent-conveyor/).
+Use `node scripts/check-landing-page.mjs` for a docs-only desktop/mobile
+screenshot gate; this does not run the full package release smoke.
 
 After install, the intended Codex app entry point is natural language. Open a
 new Codex app session in the target repo and say:
@@ -158,7 +166,15 @@ Require adversarial proof before another worker iteration.
 The installed skill should call the `conveyor` CLI, choose names, create the
 no-tmux binding with `create-disposable-binding`, point the worker at
 `worker-inbox`, and use `loop-status` plus telemetry receipts before reporting
-that the loop is ready.
+that the loop is ready. When the manager is itself running in the Codex app and
+thread tools are available, the skill should first call `create_thread` for a
+fresh same-project worker, name it with `set_thread_title`, pass the returned
+thread identity through `--worker-codex-app-thread-id` and
+`--worker-codex-app-thread-title`, and use `send_message_to_thread` only to
+deliver the generated `worker_handoff` bootstrap prompt. The raw terminal
+`conveyor` CLI does not create Codex app threads by itself; if app thread tools
+are unavailable, open a separate Codex app worker manually and paste the
+`worker_handoff` prompt.
 
 Dispatch is core infrastructure for supervised worker/manager pairs. The
 `pair` workflow starts a detached Dispatch watch process by default so worker
@@ -309,16 +325,21 @@ tmux attach -t codex-live-test
   Use `--accept-trust` only for directories you intentionally trust; it retries
   Enter during startup discovery so fresh workspaces do not stall before
   registration.
-- `register-worker --name N [--pid P | --codex-session PATH] [--cwd D] [--tmux-session S]` —
+- `register-worker --name N [--pid P | --codex-session PATH] [--cwd D] [--tmux-session S] [--codex-app-thread-id ID] [--codex-app-thread-title TITLE]` —
   Register an already-running Codex session as a worker. Rollout JSONL is
   auto-discovered from the pid via `lsof` unless `--codex-session` is given.
+  The optional Codex app thread flags are metadata supplied by the Codex app
+  skill/tool layer; they help humans identify the app thread but do not change
+  rollout ingest or Dispatch delivery.
 - `register-manager --name N ...` — Same arguments; tmux is not required.
   Both registration commands print a `communication` object. When
   `--tmux-session` is present, `communication.session_kind='tmux'`,
   `receive_style='push'`, and `delivery_mode='push'`; without tmux but with a
   Codex rollout identity, `session_kind='codex_app'`, `receive_style='pull'`,
   and `delivery_mode='pull_required'`, with the role-specific inbox polling
-  command template.
+  command template. The generated command may include a local
+  `PATH=.../bin:$PATH conveyor` prefix; preserve that prefix when sending the
+  command to a Codex app thread.
 - `deregister <name>` — Mark a session gone. Refuses if the session is bound
   to an active task.
 - `sessions [--role worker|manager] [--state active|gone|all] [--include-legacy]
@@ -338,7 +359,7 @@ tmux attach -t codex-live-test
   registration, so managers can detect whether a worker or manager is
   tmux-push capable or must poll its mailbox.
 - `tasks [--create NAME --goal G --summary S]` — List or create tasks.
-- `create-disposable-binding TASK [--worker NAME] [--manager NAME] [--template TEMPLATE | --required-before-continue TYPE] [--adversarial]` —
+- `create-disposable-binding TASK [--worker NAME] [--manager NAME] [--template TEMPLATE | --required-before-continue TYPE] [--adversarial] [--worker-codex-app-thread-id ID] [--worker-codex-app-thread-title TITLE] [--manager-codex-app-thread-id ID] [--manager-codex-app-thread-title TITLE]` —
   Create a no-tmux manager/worker binding for real Ralph-loop slices. The
   helper creates the task when missing, marks it managed, writes valid Codex
   rollout JSONL files, registers worker and manager sessions with
@@ -346,7 +367,33 @@ tmux attach -t codex-live-test
   custom Ralph-loop policy run, and prints replay commands for Dispatch,
   `loop-status`, per-session `communication` metadata, plus a `worker_handoff`
   prompt that tells Codex app workers to keep polling their worker inbox
-  through the bounded loop.
+  through the bounded loop using the exact generated command. For pull-required
+  Codex app sessions, the JSON output also includes
+  `heartbeat_recommendations` with role-specific poll prompts; Dispatch can
+  deliver into those inboxes, but a heartbeat or operator wake-up is still
+  required to make an idle app thread poll autonomously. Those recommendations
+  include a `teardown_policy`: an idle poll is only a quiet interval, not a
+  reason to delete or pause heartbeat automation; heartbeat teardown belongs to
+  the manager/operator after terminal closeout or explicit operator instruction.
+  The optional
+  Codex app thread metadata is normally supplied after a Codex app manager has
+  used `create_thread` and `set_thread_title`; terminal-only users can omit it
+  and still use the manual no-tmux handoff.
+- `app-heartbeat TASK --role manager|worker [--dispatcher-id ID]
+  [--stale-after N] [--json]` — Record a Codex app/no-tmux manager or worker
+  heartbeat for the active binding and return that role's next poll commands.
+  Use this as the recurring heartbeat command for pull-required app sessions.
+- `app-loop-status TASK [--dispatcher-id ID] [--stale-after N] [--json]` —
+  Summarize manager lease, worker lease, Dispatch heartbeat, and next required
+  actions for an app-native Conveyor loop.
+- `app-wakeup-plan TASK [--dispatcher-id ID] [--stale-after N] [--json]` —
+  Emit exact manager and worker thread wake prompts, including app thread ids
+  and titles when present, for an operator or Codex app automation to send.
+- `app-wakeup-dispatch TASK [--dispatcher-id ID] [--stale-after N] [--json]` —
+  Prepare adapter-ready Codex app wake actions and record a telemetry receipt
+  for prepared, skipped, and blocked role wakeups. This command does not send
+  `send_message_to_thread`; the Codex app/operator layer sends prompts whose
+  actions report `send_ready=true`.
 - `discover [QUERY] [--all] [--limit N]` / `search [QUERY]` — Search tasks,
   registered sessions, active bindings, and recent telemetry in one JSON result.
   Use this for conversational setup when a manager or Codex session needs to
@@ -407,8 +454,8 @@ tmux attach -t codex-live-test
   or manager inspection; `manager_config` is not a valid criteria source.
   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"}'
   ```
   For mutation responses, treat `affected_criterion` as the authoritative
   receipt for the row changed by that command. When a manager applies multiple
@@ -713,7 +760,7 @@ tmux attach -t codex-live-test
 - `loop-status TASK --run RUN [--json]` — Summarize a Ralph-loop run for manager
   review: policy template, iteration bounds, command states, routed
   notifications, worker inbox backlog, evidence types, consumed-inbox
-  telemetry, failure counts, and a recommendation.
+  and iteration-advanced telemetry, failure counts, and a recommendation.
 
 For real vertical slices, start with the Ralph loop operator guide in
 `docs/qa/ralph-loop-operator-guide.md`. It explains the controlled
@@ -722,7 +769,12 @@ required evidence, adversarial proof, `loop-status`, and telemetry review pass
 bar.
 Use `create-disposable-binding` when the manager and worker are Codex app or
 other no-tmux sessions and you want the same Dispatch rails without manual
-task/session/bind setup.
+task/session/bind setup. In a Codex app manager session, prefer a fresh
+same-project `create_thread` worker plus `set_thread_title` before creating the
+binding, then pass the worker thread id/title into Conveyor. Use `fork_thread`
+only when the user explicitly asks to fork or resume this conversation. If app
+thread tools are unavailable, create the binding anyway and paste the returned
+`worker_handoff` prompt into a manually opened worker session.
 - `enqueue-continue-iteration TASK --loop-run RUN --requested-iteration N` —
   Queue a manager-requested next loop pass for Dispatch. The command refuses
   same/current iteration requests before they become pending queue rows, while
@@ -980,16 +1032,28 @@ Current dispatch state:
   in `routed_notifications`, and threaded with `correlation_id`.
 - The session inbox is the same `routed_notifications` stream addressed by
   `target_session_id`: tmux push is optional transport. Codex app-based sessions
-  should long-poll with `manager-inbox --consume-next --wait --json` or
-  `worker-inbox --consume-next --wait --json`. For disposable Ralph loops, use
-  the generated `worker_handoff` prompt so the worker keeps polling until no
-  inbox item remains or the loop reaches `max_iterations`.
+  should run `app-heartbeat` as their recurring heartbeat, using the direct
+  `communication.poll_command` only as a fallback or when returned in heartbeat
+  guidance. For disposable Ralph loops, use the generated `worker_handoff`
+  prompt so the worker keeps polling until no inbox item remains or the loop
+  reaches `max_iterations`. For no-tmux Codex app sessions, treat
+  `communication.requires_polling=true` as requiring a heartbeat/wake layer:
+  a delivered pull inbox item does not by itself wake an idle app thread. Do
+  not delete or pause heartbeats because an inbox poll is idle. A terminal
+  manager decision should be followed by `finish-task --require-criteria-audit`
+  or by an explicit blocker explaining why the task/binding still appears
+  active.
 - `register-worker`, `register-manager`, `sessions`, `discover`, and
   `create-disposable-binding --json` expose a `communication` block per
   session. Treat `session_kind='tmux'` plus `receive_style='push'` as direct
   tmux-delivery capable; treat `session_kind='codex_app'` plus
   `receive_style='pull'` as mailbox polling required for that worker or
   manager.
+- App-assisted setup may also expose `codex_app_thread_id` and
+  `codex_app_thread_title` for sessions created or identified by Codex app
+  thread tools. Treat those fields as human/app navigation metadata; the
+  durable communication record is still `routed_notifications` plus inbox
+  consumption telemetry.
 - Template-backed `continue_iteration` deliveries include `loop_policy` in the
   inbox payload, with template name, current/max iteration, cleanup policy,
   required evidence, artifact requirements, and recommended tools. Codex
@@ -1001,6 +1065,10 @@ Current dispatch state:
 - Consuming a mailbox item records `dispatch_inbox_consumed` telemetry with the
   notification id, signal type, delivery mode, target session role, and poll
   count, so manager/worker dispatcher handoffs are visible in audit evidence.
+  When the item is `continue_iteration`, Conveyor also advances the run
+  metadata's durable `current_iteration` to the requested iteration and records
+  `ralph_loop_iteration_advanced` telemetry keyed to the run, notification,
+  command, and consuming session.
 - If `doctor-self --json` reports `workerctl_on_path=false` inside a Codex app
   session, run `conveyor ...` from the repository root or install the
   local wrapper with `scripts/install-local --write`. Its `inside_tmux` check
@@ -1112,9 +1180,8 @@ scripts/rc-check --with-live-smoke-repeat
 Underlying deterministic checks:
 
 ```bash
-python3 -m unittest discover -s tests -v
-scripts/check-resource-warnings
-python3 -m py_compile scripts/workerctl scripts/check-resource-warnings workerctl/*.py
+scripts/check-resource-warnings -- npm test -- --runInBand
+npm run build
 npm run migration:audit:final
 scripts/package-smoke
 scripts/release-check
@@ -1123,10 +1190,9 @@ scripts/release-check
 For local parallel experiments, prefer:
 
 ```bash
-scripts/run-unittests-isolated
+npm test
 ```
 
-This gives the process a temporary `WORKERCTL_STATE_ROOT` and a test namespace.
 The standard CI job remains serial.
 
 GitHub Actions runs `scripts/rc-check --skip-live-smoke-repeat` and
@@ -1134,7 +1200,7 @@ GitHub Actions runs `scripts/rc-check --skip-live-smoke-repeat` and
 remains local/manual because hosted runners may not have `codex`.
 The ResourceWarning gate intentionally fails on any `ResourceWarning` text in
 test output so finalization-time resource warnings cannot be hidden by a zero
-`unittest` exit status.
+test exit status.
 
 Live local smoke gate: