agent-conveyor 0.1.11 → 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
@@ -404,6 +411,21 @@ tmux attach -t codex-live-test
   `sent` is accepted only when the referenced `app-wakeup-dispatch` receipt has
   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]
+  [--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
+  bounded Dispatch watch command. A plain shell CLI cannot call Codex app
+  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
@@ -631,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
@@ -784,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

@@ -5,7 +5,7 @@ import { homedir, tmpdir } from "node:os";
 import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { taskAuditSync } from "../runtime/audit.js";
-import { appLoopStatusSync, appWakeupDispatchPlanSync, appWakeupPlanSync, directInboxPollCommand, } from "../runtime/app-autonomy.js";
+import { appAutopilotPlanSync, appLoopStatusSync, appWakeupDispatchPlanSync, appWakeupPlanSync, directInboxPollCommand, } from "../runtime/app-autonomy.js";
 import { classifyBusyWait, classifyStartupOutput } from "../runtime/classify.js";
 import { exportTaskSync } from "../runtime/export.js";
 import { ingestSessionSync } from "../runtime/ingest.js";
@@ -134,6 +134,9 @@ export function runTypescriptRuntimeCommand(options) {
         if (parsed.command === "app-wakeup-record-delivery") {
             return runAppWakeupRecordDeliveryCommand(parsed, options);
         }
+        if (parsed.command === "app-autopilot") {
+            return runAppAutopilotCommand(parsed, options);
+        }
         if (parsed.command === "qa-plan") {
             return runQaPlanCommand(parsed);
         }
@@ -385,6 +388,17 @@ function commandHelpText(program, command) {
             `  ${program} enqueue-nudge-worker my-task --message "Status and evidence?" --path /tmp/work/workerctl.db`,
             `  ${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] [--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.",
+            "",
+            "Examples:",
+            `  ${program} app-autopilot start dogfood --dispatcher-id dispatch-local --path /tmp/work/workerctl.db --json`,
+            `  ${program} app-autopilot status dogfood --path /tmp/work/workerctl.db`,
+            `  ${program} app-autopilot stop dogfood --path /tmp/work/workerctl.db --json`,
+        ],
         pair: [
             `usage: ${program} pair --task <task> --worker-name <worker> --manager-name <manager> [options] ${path}`,
             "",
@@ -514,6 +528,7 @@ function parseRuntimeArgs(args, env) {
         source: null,
         proof: null,
         purpose: null,
+        quietAfterCycles: 3,
         questions: false,
         rationale: null,
         receiptOutput: null,
@@ -1496,7 +1511,8 @@ function parseRuntimeArgs(args, env) {
                 && command !== "app-heartbeat"
                 && command !== "app-loop-status"
                 && command !== "app-wakeup-plan"
-                && command !== "app-wakeup-dispatch") {
+                && command !== "app-wakeup-dispatch"
+                && command !== "app-autopilot") {
                 return { command, enabled, error: "Unsupported TypeScript runtime option: --dispatcher-id", explicit, flags, task };
             }
             const value = valueAfter(queue, index, arg);
@@ -2463,7 +2479,11 @@ function parseRuntimeArgs(args, env) {
             index += 1;
         }
         else if (arg === "--stale-after") {
-            if (command !== "app-heartbeat" && command !== "app-loop-status" && command !== "app-wakeup-plan" && command !== "app-wakeup-dispatch") {
+            if (command !== "app-heartbeat"
+                && command !== "app-loop-status"
+                && command !== "app-wakeup-plan"
+                && command !== "app-wakeup-dispatch"
+                && command !== "app-autopilot") {
                 return { command, enabled, error: "Unsupported TypeScript runtime option: --stale-after", explicit, flags, task };
             }
             const parsedValue = valueAfter(queue, index, arg);
@@ -2477,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 };
@@ -2676,7 +2711,7 @@ function parseRuntimeArgs(args, env) {
             index += 1;
         }
         else if (arg === "--interval") {
-            if (command !== "dispatch" && command !== "session-inbox" && command !== "manager-inbox" && command !== "worker-inbox") {
+            if (command !== "dispatch" && command !== "session-inbox" && command !== "manager-inbox" && command !== "worker-inbox" && command !== "app-autopilot") {
                 return { command, enabled, error: "Unsupported TypeScript runtime option: --interval", explicit, flags, task };
             }
             const parsedValue = valueAfter(queue, index, arg);
@@ -2691,7 +2726,7 @@ function parseRuntimeArgs(args, env) {
             index += 1;
         }
         else if (arg === "--watch-iterations") {
-            if (command !== "dispatch") {
+            if (command !== "dispatch" && command !== "app-autopilot") {
                 return { command, enabled, error: "Unsupported TypeScript runtime option: --watch-iterations", explicit, flags, task };
             }
             const parsedValue = valueAfter(queue, index, arg);
@@ -2824,6 +2859,12 @@ function parseRuntimeArgs(args, env) {
             }
             flags.subtype = arg;
         }
+        else if (command === "app-autopilot" && flags.action === null) {
+            if (!["start", "stop", "status"].includes(arg)) {
+                return { command, enabled, error: `Unsupported app-autopilot action: ${arg}`, explicit, flags, task };
+            }
+            flags.action = arg;
+        }
         else if ((command === "qa-plan" || command === "qa-run") && flags.subtype === null) {
             flags.subtype = arg;
         }
@@ -3693,6 +3734,90 @@ function runAppWakeupRecordDeliveryCommand(parsed, options) {
         database.close();
     }
 }
+function runAppAutopilotCommand(parsed, options) {
+    const action = parsed.flags.action;
+    if (action !== "start" && action !== "stop" && action !== "status") {
+        return errorResult("app-autopilot requires an action: start, stop, or status");
+    }
+    const taskName = requireTask(parsed);
+    const database = openRuntimeDatabase(parsed, options);
+    try {
+        const timestamp = nowIsoSeconds(options);
+        const dbPath = runtimeDbPath(parsed, options);
+        const dispatcherId = parsed.flags.dispatcherId ?? "dispatch-local";
+        const desiredState = action === "start" ? "active" : action === "stop" ? "stopped" : null;
+        let plan = appAutopilotPlanSync(database, {
+            dbPath,
+            dispatchIntervalSeconds: parsed.flags.intervalSeconds,
+            dispatcherId,
+            desiredState,
+            heartbeatIntervalMinutes: 2,
+            heartbeatStaleSeconds: parsed.flags.appStaleAfterSeconds,
+            now: timestamp,
+            quietAfterCycles: parsed.flags.quietAfterCycles,
+            taskName,
+            watchIterations: parsed.flags.watchIterations ?? 1000000,
+        });
+        let receipt = null;
+        if (action === "start" || action === "stop") {
+            const eventType = action === "start" ? "app_autopilot_started" : "app_autopilot_stopped";
+            const eventId = emitTelemetrySync(database, {
+                actor: "operator",
+                attributes: {
+                    automation_specs: plan.automation_specs.map((spec) => ({
+                        can_create: spec.can_create,
+                        interval_minutes: spec.interval_minutes,
+                        name: spec.name,
+                        role: spec.role,
+                        target_thread_id: spec.target_thread_id,
+                        target_thread_title: spec.target_thread_title,
+                    })),
+                    desired_state: desiredState,
+                    dispatcher_command: plan.control.dispatcher_command,
+                    dispatcher_id: dispatcherId,
+                    interval_minutes: plan.interval_minutes,
+                    quiescence: plan.quiescence,
+                    summary: plan.summary,
+                },
+                correlation: {
+                    action,
+                    command: "app-autopilot",
+                    dispatcher_id: dispatcherId,
+                },
+                eventType,
+                severity: plan.summary.blocked_automations > 0 ? "warning" : "info",
+                summary: `App autopilot ${action} for ${plan.task.name}.`,
+                taskId: plan.task.id,
+                timestamp,
+            });
+            receipt = {
+                event_id: eventId,
+                event_type: eventType,
+                recorded_at: timestamp,
+            };
+            plan = {
+                ...plan,
+                last_policy_event: receipt,
+            };
+        }
+        const output = {
+            action,
+            plan,
+            receipt,
+        };
+        if (parsed.flags.json) {
+            return jsonResult(output);
+        }
+        return {
+            exitCode: 0,
+            handled: true,
+            stdout: renderAppAutopilotText(output),
+        };
+    }
+    finally {
+        database.close();
+    }
+}
 function parseAppWakeupDeliveryStatus(value) {
     if (value === "sent" || value === "skipped" || value === "blocked") {
         return value;
@@ -3803,6 +3928,39 @@ function renderAppWakeupPlanText(plan) {
     }
     return `${lines.join("\n")}\n`;
 }
+function renderAppAutopilotText(result) {
+    const lines = [
+        `App autopilot ${result.action} for ${result.plan.task.name}: ${result.plan.desired_state}`,
+        `Loop status: ${result.plan.status.ok ? "ok" : "attention required"}`,
+        `Dispatch: ${result.plan.dispatcher.state}${result.plan.dispatcher.required ? " required" : ""}`,
+        `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}`);
+    }
+    else if (result.plan.last_policy_event) {
+        lines.push(`Last policy: ${result.plan.last_policy_event.event_type} ${result.plan.last_policy_event.event_id}`);
+    }
+    else {
+        lines.push("Last policy: unconfigured");
+    }
+    for (const spec of result.plan.automation_specs) {
+        lines.push(`${spec.role} automation: ${spec.can_create ? "ready" : "blocked"} ${spec.name}`, `  thread: ${spec.target_thread_title ?? "(untitled)"} ${spec.target_thread_id ?? "(missing)"}`, `  schedule: ${spec.rrule}`);
+        if (spec.blocker) {
+            lines.push(`  blocker: ${spec.blocker}`);
+        }
+    }
+    lines.push(result.plan.control.note);
+    return `${lines.join("\n")}\n`;
+}
 function boundAppSessionForRoleSync(database, options) {
     const sessionJoin = options.role === "manager" ? "manager_session_id" : "worker_session_id";
     const row = database.prepare(`
@@ -14099,6 +14257,7 @@ function isDefaultRuntimeCommand(command) {
         || command === "app-wakeup-plan"
         || command === "app-wakeup-dispatch"
         || command === "app-wakeup-record-delivery"
+        || command === "app-autopilot"
         || command === "loop-templates"
         || command === "loop-triggers"
         || command === "ralph-loop-presets"
@@ -17084,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.",
@@ -17129,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 {
@@ -17182,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"),
@@ -17201,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>";