agent-conveyor 0.1.12 → 0.1.13

package/README.md

@@ -174,7 +174,10 @@ thread identity through `--worker-codex-app-thread-id` and
 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.
+`worker_handoff` prompt. After a worker consumes a manager instruction, its
+completion or blocker report must go back through the generated
+`enqueue-notify-manager` command and a bounded Dispatch watch tick; a direct
+Codex app final answer is not a durable manager receipt.
 
 Dispatch is core infrastructure for supervised worker/manager pairs. The
 `pair` workflow starts a detached Dispatch watch process by default so worker
@@ -371,8 +374,12 @@ tmux attach -t codex-live-test
   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
-  also include `wakeup_dispatch_command` and `delivery_receipt_commands` for
+  required to make an idle app thread poll autonomously. The worker handoff and
+  worker heartbeat prompt also include the exact durable
+  `enqueue-notify-manager` and one-iteration `dispatch --watch` commands that a
+  worker must run after completing or blocking on a consumed item. Those
+  recommendations also include `wakeup_dispatch_command` and
+  `delivery_receipt_commands` for
   app-thread wake recovery. Use them to record sent, skipped, and blocked wake
   outcomes after `app-wakeup-dispatch`; an app-thread send is not task
   completion. The recommendations include a `teardown_policy`: an idle poll is
@@ -405,7 +412,8 @@ tmux attach -t codex-live-test
   a matching `ready_to_send` action with `send_ready=true` and the same thread
   id; healthy and blocked roles must be recorded as `skipped` or `blocked`.
 - `app-autopilot start|stop|status TASK [--dispatcher-id ID]
-  [--interval SECONDS] [--watch-iterations N] [--stale-after N] [--json]` —
+  [--interval SECONDS] [--watch-iterations N] [--stale-after N]
+  [--quiet-after N] [--json]` —
   Manage the pair-level app-native heartbeat policy for the active
   manager/worker binding. `start` and `stop` write telemetry receipts and emit
   the exact manager/worker Codex app heartbeat automation specs plus the
@@ -413,6 +421,11 @@ tmux attach -t codex-live-test
   thread tools, so create/pause those heartbeat automations from a Codex app
   operator session using the emitted specs; Conveyor remains the durable source
   of truth through Dispatch, inboxes, wake receipts, and app heartbeat status.
+  `status` also reports `plan.quiescence`: when the loop is healthy, has no
+  `next_actions`, and both roles have produced `--quiet-after` paired
+  heartbeats since the last command or inbox-consumption receipt, it recommends
+  `stop_autopilot` so operators can quiesce blocked/no-progress loops instead
+  of repeating idle pulses.
 - `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
@@ -640,7 +653,10 @@ tmux attach -t codex-live-test
   recovery; `--once` performs one pass.
 - `enqueue-notify-manager <task> --message "..." [--correlation-id C]
   [--required-permission P] [--idempotency-key K] [--json]` — Queue a `notify_manager` command row for
-  Dispatch to claim and deliver to the bound manager.
+  Dispatch to claim and deliver to the bound manager. Codex app/no-tmux
+  workers must use this route for completion and blocker reports after
+  consuming a manager instruction; direct app-thread final answers are local
+  text, not manager inbox receipts.
 - `enqueue-nudge-worker <task> --message "..." [--correlation-id C]
   [--required-permission P] [--idempotency-key K] [--json]` — Queue a `nudge_worker` command row for
   Dispatch to claim and deliver to the bound worker. Use this dispatcher-backed
@@ -793,7 +809,10 @@ 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.
+`worker_handoff` prompt into a manually opened worker session. The handoff
+requires a worker to report completion/blockers through
+`enqueue-notify-manager` plus a bounded Dispatch watch run before treating the
+manager as notified.
 - `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

package/dist/cli/typescript-runtime.js

@@ -389,7 +389,7 @@ function commandHelpText(program, command) {
             `  ${program} dispatch --once --type nudge_worker --path /tmp/work/workerctl.db`,
         ],
         "app-autopilot": [
-            `usage: ${program} app-autopilot start|stop|status <task> [--dispatcher-id ID] [--interval SECONDS] [--watch-iterations N] [--stale-after N] ${path} [--json]`,
+            `usage: ${program} app-autopilot start|stop|status <task> [--dispatcher-id ID] [--interval SECONDS] [--watch-iterations N] [--stale-after N] [--quiet-after N] ${path} [--json]`,
             "",
             "Manage the app-native heartbeat policy for a bound manager/worker pair.",
             "The CLI records policy receipts and emits Codex app heartbeat automation specs; app-thread automation creation still happens through Codex app tools.",
@@ -528,6 +528,7 @@ function parseRuntimeArgs(args, env) {
         source: null,
         proof: null,
         purpose: null,
+        quietAfterCycles: 3,
         questions: false,
         rationale: null,
         receiptOutput: null,
@@ -2496,6 +2497,21 @@ function parseRuntimeArgs(args, env) {
             flags.appStaleAfterSeconds = value;
             index += 1;
         }
+        else if (arg === "--quiet-after") {
+            if (command !== "app-autopilot") {
+                return { command, enabled, error: "Unsupported TypeScript runtime option: --quiet-after", explicit, flags, task };
+            }
+            const parsedValue = valueAfter(queue, index, arg);
+            if (parsedValue.error) {
+                return { command, enabled, error: parsedValue.error, explicit, flags, task };
+            }
+            const value = Number(parsedValue.value);
+            if (!Number.isInteger(value) || value < 0) {
+                return { command, enabled, error: "--quiet-after must be a non-negative integer.", explicit, flags, task };
+            }
+            flags.quietAfterCycles = value;
+            index += 1;
+        }
         else if (arg === "--terminal-stale-seconds") {
             if (command !== "idle-check") {
                 return { command, enabled, error: "Unsupported TypeScript runtime option: --terminal-stale-seconds", explicit, flags, task };
@@ -3738,6 +3754,7 @@ function runAppAutopilotCommand(parsed, options) {
             heartbeatIntervalMinutes: 2,
             heartbeatStaleSeconds: parsed.flags.appStaleAfterSeconds,
             now: timestamp,
+            quietAfterCycles: parsed.flags.quietAfterCycles,
             taskName,
             watchIterations: parsed.flags.watchIterations ?? 1000000,
         });
@@ -3759,6 +3776,7 @@ function runAppAutopilotCommand(parsed, options) {
                     dispatcher_command: plan.control.dispatcher_command,
                     dispatcher_id: dispatcherId,
                     interval_minutes: plan.interval_minutes,
+                    quiescence: plan.quiescence,
                     summary: plan.summary,
                 },
                 correlation: {
@@ -3918,6 +3936,13 @@ function renderAppAutopilotText(result) {
         `Dispatch command: ${result.plan.control.dispatcher_command}`,
         `Wake dispatch: ${result.plan.control.wakeup_dispatch_command}`,
     ];
+    if (result.plan.quiescence.recommended_action === "stop_autopilot") {
+        lines.push(`Quiescence: stop recommended - ${result.plan.quiescence.reason}`);
+        lines.push(`Stop command: ${result.plan.control.stop_command}`);
+    }
+    else {
+        lines.push(`Quiescence: ${result.plan.quiescence.state} (${result.plan.quiescence.quiet_cycles}/${result.plan.quiescence.threshold_cycles} quiet cycles)`);
+    }
     if (result.receipt) {
         lines.push(`Receipt: ${result.receipt.event_type} ${result.receipt.event_id}`);
     }
@@ -17218,11 +17243,17 @@ function disposableWorkerHandoff(taskName, runName, dbPath) {
     const loopClause = runName
         ? ` for Ralph loop run ${runName}`
         : " for this disposable no-tmux binding";
+    const notifyCommand = durableWorkerNotifyManagerCommand(taskName, dbPath);
+    const dispatchCommand = durableWorkerNotifyDispatchCommand(dbPath);
     return [
         "Use the manage-codex-workers skill.",
         "",
         `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.",
+        "After completing or blocking on a consumed item, send the manager a durable Conveyor notification before your final answer. A direct app-thread final answer is not a manager receipt and is not task completion.",
+        `Run: ${notifyCommand}`,
+        `Then run: ${dispatchCommand}`,
+        "If either notify/dispatch command fails, include that failure as the blocker and do not claim the manager was notified.",
         "",
         "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.",
@@ -17263,6 +17294,8 @@ function disposableHeartbeatRecommendations(taskName, dbPath) {
     const workerHeartbeatCommand = disposableAppHeartbeatCommand("worker", taskName, dbPath);
     const managerInboxCommand = sessionPollCommand("manager", taskName, dbPath);
     const workerInboxCommand = sessionPollCommand("worker", taskName, dbPath);
+    const workerNotifyCommand = durableWorkerNotifyManagerCommand(taskName, dbPath);
+    const workerNotifyDispatchCommand = durableWorkerNotifyDispatchCommand(dbPath);
     const wakeupDispatchCommand = `${conveyorPollInvocation()} app-wakeup-dispatch ${shellQuote(taskName)} --path ${shellQuote(dbPath)} --json`;
     const deliveryReceiptCommands = disposableDeliveryReceiptCommands(taskName, dbPath);
     return {
@@ -17316,6 +17349,10 @@ function disposableHeartbeatRecommendations(taskName, dbPath) {
                 `Run: ${workerHeartbeatCommand}`,
                 `If the heartbeat output asks for direct inbox polling, run: ${workerInboxCommand}`,
                 "If an item is consumed, execute only that single worker instruction and return exact commands, compact evidence for any completion claim, blockers/residual risk, and exactly one next recommended worker task.",
+                "Before your final answer after any consumed item, notify the manager durably; a direct app-thread final answer is not a manager receipt and is not task completion.",
+                `Run: ${workerNotifyCommand}`,
+                `Then run: ${workerNotifyDispatchCommand}`,
+                "If either notify/dispatch command fails, include that failure as the blocker and do not claim the manager was notified.",
                 "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"),
@@ -17335,6 +17372,12 @@ function disposableDeliveryReceiptCommands(taskName, dbPath) {
 function disposableAppHeartbeatCommand(role, taskName, dbPath) {
     return `${conveyorPollInvocation()} app-heartbeat ${shellQuote(taskName)} --role ${role} --path ${shellQuote(dbPath)} --json`;
 }
+function durableWorkerNotifyManagerCommand(taskName, dbPath) {
+    return `${conveyorPollInvocation()} enqueue-notify-manager ${shellQuote(taskName)} --message ${shellQuote("<compact completion/blocker report with files, commands, evidence, residual risk, and next recommended worker task>")} --correlation-id ${shellQuote("<worker-result-id>")} --path ${shellQuote(dbPath)} --json`;
+}
+function durableWorkerNotifyDispatchCommand(dbPath) {
+    return `${conveyorPollInvocation()} dispatch --watch --watch-iterations 1 --interval 2 --dispatcher-id dispatch-local --path ${shellQuote(dbPath)} --json`;
+}
 function sessionPollCommand(role, taskName, dbPath) {
     const inbox = role === "worker" ? "worker-inbox" : "manager-inbox";
     const task = taskName ? shellQuote(taskName) : "<task>";