agent-conveyor 0.1.7 → 0.1.8

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,18 @@ 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.
 - `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 +439,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 +745,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 +754,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 +1017,27 @@ 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 long-poll with the returned `communication.poll_command`. 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 +1049,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 +1164,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 +1174,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 +1184,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:
 

package/dist/cli/typescript-runtime.js

@@ -425,6 +425,10 @@ function parseRuntimeArgs(args, env) {
         candidate: null,
         check: null,
         classifyPrompt: null,
+        workerCodexAppThreadId: null,
+        workerCodexAppThreadTitle: null,
+        managerCodexAppThreadId: null,
+        managerCodexAppThreadTitle: null,
         codexSession: null,
         create: null,
         createRun: null,
@@ -1947,6 +1951,31 @@ function parseRuntimeArgs(args, env) {
             flags.manager = value.value;
             index += 1;
         }
+        else if (arg === "--worker-codex-app-thread-id"
+            || arg === "--worker-codex-app-thread-title"
+            || arg === "--manager-codex-app-thread-id"
+            || arg === "--manager-codex-app-thread-title") {
+            if (command !== "create-disposable-binding") {
+                return { command, enabled, error: `Unsupported TypeScript runtime option: ${arg}`, explicit, flags, task };
+            }
+            const value = valueAfter(queue, index, arg);
+            if (value.error) {
+                return { command, enabled, error: value.error, explicit, flags, task };
+            }
+            if (arg === "--worker-codex-app-thread-id") {
+                flags.workerCodexAppThreadId = value.value;
+            }
+            else if (arg === "--worker-codex-app-thread-title") {
+                flags.workerCodexAppThreadTitle = value.value;
+            }
+            else if (arg === "--manager-codex-app-thread-id") {
+                flags.managerCodexAppThreadId = value.value;
+            }
+            else {
+                flags.managerCodexAppThreadTitle = value.value;
+            }
+            index += 1;
+        }
         else if (arg === "--template") {
             if (command !== "create-disposable-binding" && command !== "loop-templates") {
                 return { command, enabled, error: "Unsupported TypeScript runtime option: --template", explicit, flags, task };
@@ -3968,10 +3997,10 @@ function qaRunBuildClearLoop(context) {
     const artifactDir = qaArtifactDir(context, "build-clear-loop", slug, run.id);
     const buildReceipt = join(artifactDir, "build-passed.json");
     mkdirSync(dirname(buildReceipt), { recursive: true });
-    writeFileSync(buildReceipt, `${JSON.stringify(sortJson({ command: "scripts/run-unittests-isolated -k build_clear_loop", result: "pass", status: "build_passed" }), null, 2)}\n`);
+    writeFileSync(buildReceipt, `${JSON.stringify(sortJson({ command: "npm test -- --runInBand", result: "pass", status: "build_passed" }), null, 2)}\n`);
     qaRecordLoopEvidence(context, task, run.id, "build_passed", "qa-run-build-clear-build-passed", {
         artifactPath: buildReceipt,
-        metadata: { command: "scripts/run-unittests-isolated -k build_clear_loop", result: "Focused build/test command passed before retry." },
+        metadata: { command: "npm test -- --runInBand", result: "Focused build/test command passed before retry." },
     });
     enqueueQaContinue(context, task, run.id, "qa-run-build-clear-build-only", "Run after build evidence only.");
     const buildOnlyDispatch = qaDispatchContinueOnce(context, "qa-run-build-clear-build-only");
@@ -4884,19 +4913,14 @@ function dispatchWatchCommand(workerctlPath, dispatcherId, dbPath) {
 }
 function installableSkillSources() {
     const root = packageRootFromRuntimeModule();
-    const candidates = [
-        join(root, "skills"),
-        join(root, "workerctl", "assets", "skills"),
-    ];
-    for (const candidate of candidates) {
-        const skills = ["manage-codex-workers", "codex-review"]
-            .map((name) => ({ name, source: join(candidate, name) }))
-            .filter((skill) => existsSync(join(skill.source, "SKILL.md")));
-        if (skills.length === 2) {
-            return skills;
-        }
+    const candidate = join(root, "skills");
+    const skills = ["manage-codex-workers", "codex-review"]
+        .map((name) => ({ name, source: join(candidate, name) }))
+        .filter((skill) => existsSync(join(skill.source, "SKILL.md")));
+    if (skills.length === 2) {
+        return skills;
     }
-    throw new Error("Bundled Agent Conveyor skills not found in skills/ or workerctl/assets/skills.");
+    throw new Error("Bundled Agent Conveyor skills not found in skills/.");
 }
 function runBindCommand(parsed, options) {
     const unsupported = unsupportedBindOptions(parsed);
@@ -4997,6 +5021,8 @@ function runCreateDisposableBindingCommand(parsed, options) {
         const workerRollout = writeDisposableRollout(sessionDir, workerName, cwd);
         const managerRollout = writeDisposableRollout(sessionDir, managerName, cwd);
         const worker = registerSessionSync(database, {
+            codexAppThreadId: parsed.flags.workerCodexAppThreadId,
+            codexAppThreadTitle: parsed.flags.workerCodexAppThreadTitle,
             codexSessionPath: workerRollout.path,
             cwd,
             name: workerName,
@@ -5005,6 +5031,8 @@ function runCreateDisposableBindingCommand(parsed, options) {
             tmuxSession: null,
         });
         const manager = registerSessionSync(database, {
+            codexAppThreadId: parsed.flags.managerCodexAppThreadId,
+            codexAppThreadTitle: parsed.flags.managerCodexAppThreadTitle,
             codexSessionPath: managerRollout.path,
             cwd,
             name: managerName,
@@ -5043,6 +5071,8 @@ function runCreateDisposableBindingCommand(parsed, options) {
             db_path: dbPath,
             manager: {
                 communication: disposableSessionCommunication("manager", task.name, dbPath),
+                codex_app_thread_id: manager.codex_app_thread_id,
+                codex_app_thread_title: manager.codex_app_thread_title,
                 id: manager.session_id,
                 name: managerName,
                 rollout_path: managerRollout.path,
@@ -5068,11 +5098,14 @@ function runCreateDisposableBindingCommand(parsed, options) {
             },
             worker: {
                 communication: disposableSessionCommunication("worker", task.name, dbPath),
+                codex_app_thread_id: worker.codex_app_thread_id,
+                codex_app_thread_title: worker.codex_app_thread_title,
                 id: worker.session_id,
                 name: workerName,
                 rollout_path: workerRollout.path,
                 tmux_session: null,
             },
+            heartbeat_recommendations: disposableHeartbeatRecommendations(task.name, dbPath),
             worker_handoff: disposableWorkerHandoff(task.name, run?.name ?? null, dbPath),
         };
         if (parsed.flags.json) {
@@ -16581,6 +16614,9 @@ function disposableWorkerHandoff(taskName, runName, dbPath) {
         `You are the worker for task ${taskName}${loopClause}.`,
         "Keep polling your Conveyor worker inbox until there are no items left or the loop reaches max_iterations. Consume the next item now, treat each consumed item as the manager's next instruction, complete the requested work, and report changed files, exact commands run, evidence, and any residual risk.",
         "",
+        "Because this is a pull-required Codex app/no-tmux session, autonomous operation requires a heartbeat/wake layer that repeats this worker inbox poll while the thread is idle. If no heartbeat automation is available, report the loop as manual-poll only.",
+        "Do not delete, pause, or disable heartbeat automation just because an inbox poll is idle; the manager or operator owns terminal loop teardown.",
+        "",
         `Run: ${sessionPollCommand("worker", taskName, dbPath)}`,
     ].join("\n");
 }
@@ -16595,14 +16631,72 @@ function renderDisposableBindingText(result) {
     }
     lines.push("Replay commands:");
     lines.push(...result.replay_commands.map((command) => `  ${command}`));
+    if (result.heartbeat_recommendations) {
+        lines.push("Heartbeat recommendations:");
+        lines.push(`  interval: every ${result.heartbeat_recommendations.interval_minutes} minutes`);
+        lines.push(`  manager: ${result.heartbeat_recommendations.manager.poll_command}`);
+        lines.push(`  worker: ${result.heartbeat_recommendations.worker.poll_command}`);
+        lines.push(`  teardown: ${result.heartbeat_recommendations.teardown_policy.idle_poll}`);
+        lines.push(`  closeout: ${result.heartbeat_recommendations.teardown_policy.terminal_closeout_command}`);
+    }
     lines.push("Worker handoff:");
     lines.push(result.worker_handoff);
     return `${lines.join("\n")}\n`;
 }
+function disposableHeartbeatRecommendations(taskName, dbPath) {
+    const terminalCloseoutCommand = `${conveyorPollInvocation()} finish-task ${shellQuote(taskName)} --reason ${shellQuote("Verified terminal closeout")} --require-criteria-audit --path ${shellQuote(dbPath)}`;
+    return {
+        applies_when: {
+            can_receive_push: false,
+            delivery_mode: "pull_required",
+            receive_style: "pull",
+            session_kind: "codex_app",
+        },
+        interval_minutes: 2,
+        note: "Dispatch can deliver pull-required inbox items, but Codex app/no-tmux sessions still need a heartbeat or operator wake-up to poll while idle.",
+        teardown_policy: {
+            idle_poll: "Never delete, pause, or disable a manager or worker heartbeat because an inbox poll returned no item; that is only a quiet poll interval.",
+            owner: "manager_or_operator",
+            terminal_closeout: "Only the manager or operator should tear down heartbeats, and only after a terminal manager decision plus verified task closeout, or after explicit operator instruction.",
+            terminal_closeout_command: terminalCloseoutCommand,
+            worker_rule: "The worker must not own loop teardown and must not remove heartbeat automation based on idle polling.",
+        },
+        manager: {
+            kind: "thread_heartbeat",
+            poll_command: sessionPollCommand("manager", taskName, dbPath),
+            prompt: [
+                "Use the manage-codex-workers skill.",
+                `Poll the manager inbox for task ${taskName}.`,
+                `Run: ${sessionPollCommand("manager", taskName, dbPath)}`,
+                "If an item is consumed, execute only that manager instruction, verify worker claims before recording conclusions, update Conveyor state as appropriate, and produce exactly one next worker task.",
+                "If no item is consumed, stop after a one-line idle receipt.",
+                "Do not delete, pause, or disable manager or worker heartbeat automation after an idle poll; an idle poll is only a quiet interval.",
+                `If all accepted criteria are satisfied, deferred, or rejected and there is no next worker task, record the terminal manager decision, run or report the result of: ${terminalCloseoutCommand}`,
+                "After verified task closeout, explicitly report heartbeat teardown status; if the task remains managed/active, report that as a control-plane blocker instead of calling the loop complete.",
+            ].join("\n"),
+        },
+        worker: {
+            kind: "thread_heartbeat",
+            poll_command: sessionPollCommand("worker", taskName, dbPath),
+            prompt: [
+                "Use the manage-codex-workers skill.",
+                `Poll the worker inbox for task ${taskName}.`,
+                `Run: ${sessionPollCommand("worker", taskName, dbPath)}`,
+                "If an item is consumed, execute only that single worker instruction and return exact commands, compact evidence, blockers/residual risk, and exactly one next recommended worker task.",
+                "If no item is consumed, stop after a one-line idle receipt.",
+                "Do not delete, pause, or disable worker heartbeat automation after an idle poll; the manager or operator owns terminal loop teardown.",
+            ].join("\n"),
+        },
+    };
+}
 function sessionPollCommand(role, taskName, dbPath) {
     const inbox = role === "worker" ? "worker-inbox" : "manager-inbox";
     const task = taskName ? shellQuote(taskName) : "<task>";
-    return `conveyor ${inbox} ${task} --consume-next --wait --timeout 60 --path ${shellQuote(dbPath)} --json`;
+    return `${conveyorPollInvocation()} ${inbox} ${task} --consume-next --wait --timeout 60 --path ${shellQuote(dbPath)} --json`;
+}
+function conveyorPollInvocation() {
+    const binDir = join(packageRootFromRuntimeModule(), "bin");
+    return pathIsExecutable(join(binDir, "conveyor")) ? `PATH=${shellQuote(binDir)}:$PATH conveyor` : "conveyor";
 }
 function resolveCodexStartupOptions(options) {
     const defaults = {