agent-conveyor 0.1.10 → 0.1.12

package/README.md

@@ -372,9 +372,13 @@ tmux attach -t codex-live-test
   `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.
+  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
+  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
@@ -400,6 +404,15 @@ 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] [--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.
 - `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
@@ -1045,10 +1058,12 @@ Current dispatch state:
   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.
+  not delete or pause heartbeats because an inbox poll is idle. Use generated
+  `heartbeat_recommendations.wakeup_dispatch_command` and
+  `heartbeat_recommendations.delivery_receipt_commands` for stale-thread wake
+  recovery receipts. 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

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] ${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}`,
             "",
@@ -1496,7 +1510,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 +2478,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);
@@ -2676,7 +2695,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 +2710,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 +2843,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 +3718,88 @@ 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,
+            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,
+                    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 +3910,32 @@ 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.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 +14232,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"
@@ -17114,6 +17248,8 @@ function renderDisposableBindingText(result) {
         lines.push(`  worker: ${result.heartbeat_recommendations.worker.poll_command}`);
         lines.push(`  status: ${result.heartbeat_recommendations.status_command}`);
         lines.push(`  wakeup plan: ${result.heartbeat_recommendations.wakeup_plan_command}`);
+        lines.push(`  wakeup dispatch: ${result.heartbeat_recommendations.wakeup_dispatch_command}`);
+        lines.push(`  delivery sent: ${result.heartbeat_recommendations.delivery_receipt_commands.sent}`);
         lines.push(`  teardown: ${result.heartbeat_recommendations.teardown_policy.idle_poll}`);
         lines.push(`  closeout: ${result.heartbeat_recommendations.teardown_policy.terminal_closeout_command}`);
     }
@@ -17127,6 +17263,8 @@ function disposableHeartbeatRecommendations(taskName, dbPath) {
     const workerHeartbeatCommand = disposableAppHeartbeatCommand("worker", taskName, dbPath);
     const managerInboxCommand = sessionPollCommand("manager", taskName, dbPath);
     const workerInboxCommand = sessionPollCommand("worker", taskName, dbPath);
+    const wakeupDispatchCommand = `${conveyorPollInvocation()} app-wakeup-dispatch ${shellQuote(taskName)} --path ${shellQuote(dbPath)} --json`;
+    const deliveryReceiptCommands = disposableDeliveryReceiptCommands(taskName, dbPath);
     return {
         applies_when: {
             can_receive_push: false,
@@ -17134,6 +17272,7 @@ function disposableHeartbeatRecommendations(taskName, dbPath) {
             receive_style: "pull",
             session_kind: "codex_app",
         },
+        delivery_receipt_commands: deliveryReceiptCommands,
         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.",
         status_command: `${conveyorPollInvocation()} app-loop-status ${shellQuote(taskName)} --path ${shellQuote(dbPath)} --json`,
@@ -17144,6 +17283,7 @@ function disposableHeartbeatRecommendations(taskName, dbPath) {
             terminal_closeout_command: terminalCloseoutCommand,
             worker_rule: "The worker must not own loop teardown and must not remove heartbeat automation based on idle polling.",
         },
+        wakeup_dispatch_command: wakeupDispatchCommand,
         wakeup_plan_command: `${conveyorPollInvocation()} app-wakeup-plan ${shellQuote(taskName)} --path ${shellQuote(dbPath)} --json`,
         manager: {
             direct_inbox_command: managerInboxCommand,
@@ -17154,6 +17294,11 @@ function disposableHeartbeatRecommendations(taskName, dbPath) {
                 `Run the manager app heartbeat for task ${taskName}.`,
                 `Run: ${managerHeartbeatCommand}`,
                 `If the heartbeat output asks for direct inbox polling, run: ${managerInboxCommand}`,
+                `For stale app-thread recovery with an auditable receipt, run: ${wakeupDispatchCommand}`,
+                "Send app-thread wake prompts only for actions where `send_ready=true`; direct app-thread delivery is not task completion.",
+                `After a successful app-thread send, record it with: ${deliveryReceiptCommands.sent}`,
+                `For healthy skipped actions, record: ${deliveryReceiptCommands.skipped}`,
+                `For missing-thread blocked actions, record: ${deliveryReceiptCommands.blocked}`,
                 "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.",
@@ -17170,13 +17315,23 @@ function disposableHeartbeatRecommendations(taskName, dbPath) {
                 `Run the worker app heartbeat for task ${taskName}.`,
                 `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, blockers/residual risk, and exactly one next recommended worker task.",
+                "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.",
                 "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 disposableDeliveryReceiptCommands(taskName, dbPath) {
+    const base = `${conveyorPollInvocation()} app-wakeup-record-delivery ${shellQuote(taskName)} --role <role> --dispatch-receipt <receipt.event_id>`;
+    const pathAndJson = ` --path ${shellQuote(dbPath)} --json`;
+    return {
+        blocked: `${base} --delivery-status blocked${pathAndJson}`,
+        note: "Run these only after app-wakeup-dispatch. Replace <role>, <receipt.event_id>, and <action.thread.id> from the dispatch JSON; sent is valid only for send_ready=true actions.",
+        sent: `${base} --delivery-status sent --thread-id <action.thread.id>${pathAndJson}`,
+        skipped: `${base} --delivery-status skipped${pathAndJson}`,
+    };
+}
 function disposableAppHeartbeatCommand(role, taskName, dbPath) {
     return `${conveyorPollInvocation()} app-heartbeat ${shellQuote(taskName)} --role ${role} --path ${shellQuote(dbPath)} --json`;
 }