agent-conveyor 0.1.9 → 0.1.11

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
@@ -394,6 +398,12 @@ tmux attach -t codex-live-test
   for prepared, skipped, and blocked role wakeups. This command does not send
   `send_message_to_thread`; the Codex app/operator layer sends prompts whose
   actions report `send_ready=true`.
+- `app-wakeup-record-delivery TASK --role manager|worker --dispatch-receipt ID
+  --delivery-status sent|skipped|blocked [--thread-id ID] [--reason TEXT]
+  [--json]` — Record what the Codex app/operator layer did with a wake action.
+  `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`.
 - `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
@@ -1039,10 +1049,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

@@ -131,6 +131,9 @@ export function runTypescriptRuntimeCommand(options) {
         if (parsed.command === "app-wakeup-dispatch") {
             return runAppWakeupDispatchCommand(parsed, options);
         }
+        if (parsed.command === "app-wakeup-record-delivery") {
+            return runAppWakeupRecordDeliveryCommand(parsed, options);
+        }
         if (parsed.command === "qa-plan") {
             return runQaPlanCommand(parsed);
         }
@@ -546,9 +549,12 @@ function parseRuntimeArgs(args, env) {
         captureTranscriptLines: DEFAULT_HISTORY_LINES,
         captureTranscriptMode: "segment",
         decisionId: null,
+        deliveryStatus: null,
+        dispatchReceipt: null,
         force: false,
         message: null,
         reason: null,
+        threadId: null,
         consumeNext: false,
         wait: false,
         requireAcks: false,
@@ -1833,7 +1839,7 @@ function parseRuntimeArgs(args, env) {
             index = queue.length;
         }
         else if (arg === "--reason") {
-            if (command !== "finish-task" && command !== "stop-task" && command !== "record-decision" && command !== "compact-worker") {
+            if (command !== "finish-task" && command !== "stop-task" && command !== "record-decision" && command !== "compact-worker" && command !== "app-wakeup-record-delivery") {
                 return { command, enabled, error: "Unsupported TypeScript runtime option: --reason", explicit, flags, task };
             }
             const value = valueAfter(queue, index, arg);
@@ -1843,6 +1849,39 @@ function parseRuntimeArgs(args, env) {
             flags.reason = value.value;
             index += 1;
         }
+        else if (arg === "--dispatch-receipt") {
+            if (command !== "app-wakeup-record-delivery") {
+                return { command, enabled, error: "Unsupported TypeScript runtime option: --dispatch-receipt", explicit, flags, task };
+            }
+            const value = valueAfter(queue, index, arg);
+            if (value.error) {
+                return { command, enabled, error: value.error, explicit, flags, task };
+            }
+            flags.dispatchReceipt = value.value;
+            index += 1;
+        }
+        else if (arg === "--delivery-status") {
+            if (command !== "app-wakeup-record-delivery") {
+                return { command, enabled, error: "Unsupported TypeScript runtime option: --delivery-status", explicit, flags, task };
+            }
+            const value = valueAfter(queue, index, arg);
+            if (value.error) {
+                return { command, enabled, error: value.error, explicit, flags, task };
+            }
+            flags.deliveryStatus = value.value;
+            index += 1;
+        }
+        else if (arg === "--thread-id") {
+            if (command !== "app-wakeup-record-delivery") {
+                return { command, enabled, error: "Unsupported TypeScript runtime option: --thread-id", explicit, flags, task };
+            }
+            const value = valueAfter(queue, index, arg);
+            if (value.error) {
+                return { command, enabled, error: value.error, explicit, flags, task };
+            }
+            flags.threadId = value.value;
+            index += 1;
+        }
         else if (arg === "--message") {
             if (command !== "finish-task"
                 && command !== "stop-task"
@@ -3552,6 +3591,175 @@ function runAppWakeupDispatchCommand(parsed, options) {
         database.close();
     }
 }
+function runAppWakeupRecordDeliveryCommand(parsed, options) {
+    const taskName = requireTask(parsed);
+    if (parsed.flags.role !== "manager" && parsed.flags.role !== "worker") {
+        return errorResult("app-wakeup-record-delivery requires --role manager|worker");
+    }
+    const role = parsed.flags.role;
+    if (!parsed.flags.dispatchReceipt) {
+        return errorResult("app-wakeup-record-delivery requires --dispatch-receipt");
+    }
+    const deliveryStatus = parseAppWakeupDeliveryStatus(parsed.flags.deliveryStatus);
+    if (deliveryStatus instanceof Error) {
+        return errorResult(deliveryStatus.message);
+    }
+    const database = openRuntimeDatabase(parsed, options);
+    try {
+        const task = taskRowForDiagnostics(database, taskName);
+        const source = database.prepare(`
+      select id, task_id, event_type, attributes_json
+      from telemetry_events
+      where id = ?
+      limit 1
+    `).get(parsed.flags.dispatchReceipt);
+        if (!source) {
+            throw new Error(`Unknown app wakeup dispatch receipt: ${parsed.flags.dispatchReceipt}`);
+        }
+        if (source.event_type !== "app_wakeup_dispatch_planned") {
+            throw new Error(`Receipt ${source.id} is ${source.event_type}, expected app_wakeup_dispatch_planned.`);
+        }
+        if (source.task_id !== task.id) {
+            throw new Error(`Receipt ${source.id} does not belong to task ${task.name}.`);
+        }
+        const attributes = parseAppWakeupDispatchAttributes(source.attributes_json, source.id);
+        const action = attributes.actions.find((candidate) => candidate.role === role);
+        if (!action) {
+            throw new Error(`Receipt ${source.id} has no ${role} wake action.`);
+        }
+        validateAppWakeupDelivery({ action, deliveryStatus, role, threadId: parsed.flags.threadId });
+        const timestamp = nowIsoSeconds(options);
+        const eventId = emitTelemetrySync(database, {
+            actor: "manager",
+            attributes: {
+                delivery_status: deliveryStatus,
+                dispatch_receipt: source.id,
+                dispatch_required: attributes.summary.dispatcher_required,
+                reason: parsed.flags.reason,
+                role,
+                source_action_status: action.status,
+                source_send_ready: action.send_ready === true,
+                thread_id: parsed.flags.threadId ?? action.thread_id ?? null,
+                thread_title: action.thread_title ?? null,
+            },
+            correlation: {
+                command: "app-wakeup-record-delivery",
+                dispatch_receipt: source.id,
+                role,
+                thread_id: parsed.flags.threadId ?? action.thread_id ?? null,
+            },
+            eventType: "app_wakeup_delivery_recorded",
+            severity: deliveryStatus === "sent" ? "info" : "warning",
+            summary: `App wakeup delivery ${deliveryStatus} for ${role} on ${task.name}.`,
+            taskId: task.id,
+            timestamp,
+        });
+        const output = {
+            delivery: {
+                reason: parsed.flags.reason,
+                role,
+                source_action_status: action.status,
+                source_send_ready: action.send_ready === true,
+                status: deliveryStatus,
+                thread_id: parsed.flags.threadId ?? action.thread_id ?? null,
+            },
+            receipt: {
+                event_id: eventId,
+                event_type: "app_wakeup_delivery_recorded",
+                recorded_at: timestamp,
+            },
+            source: {
+                dispatch_receipt: source.id,
+                dispatch_required: attributes.summary.dispatcher_required,
+                dispatcher: attributes.dispatcher,
+            },
+            task: { id: task.id, name: task.name },
+        };
+        if (parsed.flags.json) {
+            return jsonResult(output);
+        }
+        return {
+            exitCode: 0,
+            handled: true,
+            stdout: [
+                `App wakeup delivery ${deliveryStatus} recorded for ${role} on ${task.name}.`,
+                `Source receipt: ${source.id}`,
+                `Receipt: ${eventId}`,
+                attributes.summary.dispatcher_required ? "Dispatch still required by source receipt." : "Dispatch healthy in source receipt.",
+            ].join("\n") + "\n",
+        };
+    }
+    finally {
+        database.close();
+    }
+}
+function parseAppWakeupDeliveryStatus(value) {
+    if (value === "sent" || value === "skipped" || value === "blocked") {
+        return value;
+    }
+    return new Error("app-wakeup-record-delivery requires --delivery-status sent|skipped|blocked");
+}
+function parseAppWakeupDispatchAttributes(value, receiptId) {
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        throw new Error(`Receipt ${receiptId} has invalid attributes JSON.`);
+    }
+    if (!parsed || typeof parsed !== "object") {
+        throw new Error(`Receipt ${receiptId} has invalid attributes shape.`);
+    }
+    const attributes = parsed;
+    if (!Array.isArray(attributes.actions)) {
+        throw new Error(`Receipt ${receiptId} is missing actions.`);
+    }
+    const summary = attributes.summary;
+    if (!summary || typeof summary !== "object" || typeof summary.dispatcher_required !== "boolean") {
+        throw new Error(`Receipt ${receiptId} is missing dispatcher_required summary.`);
+    }
+    const dispatcher = attributes.dispatcher && typeof attributes.dispatcher === "object"
+        ? attributes.dispatcher
+        : {};
+    return {
+        actions: attributes.actions,
+        dispatcher,
+        summary: { dispatcher_required: Boolean(summary.dispatcher_required) },
+    };
+}
+function validateAppWakeupDelivery(options) {
+    const sourceStatus = parseAppWakeupSourceActionStatus(options.action.status);
+    if (sourceStatus instanceof Error) {
+        throw sourceStatus;
+    }
+    if (options.deliveryStatus === "sent") {
+        if (sourceStatus !== "ready_to_send" || options.action.send_ready !== true) {
+            throw new Error(`Cannot record sent wakeup for ${options.role}; source action is ${sourceStatus}.`);
+        }
+        if (!options.threadId) {
+            throw new Error("app-wakeup-record-delivery --delivery-status sent requires --thread-id.");
+        }
+        if (options.action.thread_id !== options.threadId) {
+            throw new Error(`Thread id mismatch for ${options.role}; source action targets ${options.action.thread_id ?? "(none)"}.`);
+        }
+        return;
+    }
+    if (options.deliveryStatus === "skipped") {
+        if (sourceStatus !== "skipped_healthy") {
+            throw new Error(`Cannot record skipped wakeup for ${options.role}; source action is ${sourceStatus}.`);
+        }
+        return;
+    }
+    if (sourceStatus !== "blocked_missing_thread") {
+        throw new Error(`Cannot record blocked wakeup for ${options.role}; source action is ${sourceStatus}.`);
+    }
+}
+function parseAppWakeupSourceActionStatus(value) {
+    if (value === "ready_to_send" || value === "skipped_healthy" || value === "blocked_missing_thread") {
+        return value;
+    }
+    return new Error(`Unsupported app wakeup source action status: ${value ?? "(missing)"}.`);
+}
 function renderAppLoopStatusText(status) {
     const lines = [
         `App loop ${status.task.name}: ${status.ok ? "ok" : "attention required"}`,
@@ -13890,6 +14098,7 @@ function isDefaultRuntimeCommand(command) {
         || command === "app-loop-status"
         || command === "app-wakeup-plan"
         || command === "app-wakeup-dispatch"
+        || command === "app-wakeup-record-delivery"
         || command === "loop-templates"
         || command === "loop-triggers"
         || command === "ralph-loop-presets"
@@ -16905,6 +17114,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}`);
     }
@@ -16918,6 +17129,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,
@@ -16925,6 +17138,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`,
@@ -16935,6 +17149,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,
@@ -16945,6 +17160,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.",
@@ -16961,13 +17181,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`;
 }