agent-conveyor 0.1.6 → 0.1.8

package/docs/manager-recipes.md

@@ -28,6 +28,17 @@ Not allowed: merge without green CI; compact/clear before handoff; run two child
 User confirmed: yes
 ```
 
+## Runtime Notes
+
+On Node releases where `node:sqlite` is still experimental, Conveyor commands
+may print a SQLite `ExperimentalWarning` before otherwise valid JSON or status
+output. Treat the process exit code and parsed JSON payload as the command
+result, and keep the warning in receipts only when it obscures a real failure.
+
+If a dogfood run reports `database is locked`, prefer retrying the Conveyor CLI
+command after the active manager/worker write completes. Avoid direct SQLite
+inspection while Dispatch is writing to the same `--path` database.
+
 ## Recipe Summary
 
 | Recipe | Use When | Mode | Main Gates | Cleanup |
@@ -248,6 +259,31 @@ 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 the worker with fresh same-project `create_thread`, set a readable title
+with `set_thread_title`, and pass the resulting id/title into
+`conveyor create-disposable-binding` with
+`--worker-codex-app-thread-id` and `--worker-codex-app-thread-title`. Use
+`send_message_to_thread` only to deliver the generated `worker_handoff`
+bootstrap prompt; 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.
+
 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
@@ -275,6 +311,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.6",
+  "version": "0.1.8",
   "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,58 @@ 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. If running in the Codex app and thread tools are available, create a fresh
+   same-project worker thread with `create_thread`, name it with
+   `set_thread_title`, and keep the returned thread id/title. Use
+   `create_thread` for this flow; do not use `fork_thread` unless the user
+   explicitly asks to fork or resume this exact conversation.
+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 a worker thread id,
+   pass it through `--worker-codex-app-thread-id` and
+   `--worker-codex-app-thread-title` so Conveyor can surface the app identity
+   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 a
+   separate Codex app worker session 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
+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
+  idle/check-in command is the returned
+  `communication.poll_command` or generated `worker_handoff` command.
+- When a manager has `session_kind=codex_app` or `receive_style=pull`, its
+  idle/check-in command is the returned `communication.poll_command`.
+- 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.
+- 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 +110,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 +260,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 +478,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 +612,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 +621,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 +726,16 @@ 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 a fresh same-project worker, call
+  `set_thread_title`, run `conveyor create-disposable-binding` with
+  `--worker-codex-app-thread-id` and `--worker-codex-app-thread-title`, then
+  send the returned `worker_handoff` using `send_message_to_thread`. If those
+  tools are unavailable, run `create-disposable-binding` without thread
+  metadata and give the user the `worker_handoff` prompt to paste into a
+  manually opened worker. Keep Dispatch as the source of durable communication,
+  and make both Codex app sessions repeat their role-specific inbox poll while
+  idle.
 - "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>`.