agent-conveyor 0.1.8 → 0.1.9

package/dist/index.d.ts

@@ -7,6 +7,8 @@ export { configureConnectionSync, databaseHealthSync, initializeDatabaseSync, op
 export type { DatabaseCheck, DatabaseHealth } from "./state/database.js";
 export { taskAuditSync, TaskAuditError } from "./runtime/audit.js";
 export type { TaskAuditCorrelationChain, TaskAuditEvent, TaskAuditManagerDecision, TaskAuditResult, TaskAuditRoutedNotification, TaskAuditTask, } from "./runtime/audit.js";
+export { appHeartbeatPollCommand, appLoopStatusCommand, appLoopStatusSync, appWakeupDispatchPlanSync, appWakeupPlanCommand, appWakeupPlanSync, directInboxPollCommand, } from "./runtime/app-autonomy.js";
+export type { AppLoopDispatchState, AppLoopLeaseState, AppLoopNextAction, AppLoopRole, AppLoopRoleStatus, AppLoopStatus, AppWakeup, AppWakeupDispatchAction, AppWakeupDispatchActionStatus, AppWakeupDispatchPlan, AppWakeupPlan, } from "./runtime/app-autonomy.js";
 export { exportTaskAuditSubsetSync, exportTaskSync, TaskExportError } from "./runtime/export.js";
 export type { TaskExportManifest, TaskExportResult } from "./runtime/export.js";
 export { replayEntriesFromAudit, replayResultFromAudit } from "./runtime/replay.js";

package/dist/index.js

@@ -3,6 +3,7 @@ export { captureMetaPath, configPath, defaultDbPath, eventsPath, loadJsonSync, s
 export { latestStatusSync } from "./state/status.js";
 export { configureConnectionSync, databaseHealthSync, initializeDatabaseSync, openDatabaseSync, WorkerctlDatabaseError, } from "./state/database.js";
 export { taskAuditSync, TaskAuditError } from "./runtime/audit.js";
+export { appHeartbeatPollCommand, appLoopStatusCommand, appLoopStatusSync, appWakeupDispatchPlanSync, appWakeupPlanCommand, appWakeupPlanSync, directInboxPollCommand, } from "./runtime/app-autonomy.js";
 export { exportTaskAuditSubsetSync, exportTaskSync, TaskExportError } from "./runtime/export.js";
 export { replayEntriesFromAudit, replayResultFromAudit } from "./runtime/replay.js";
 export { classifyBusyWait, classifyStartupOutput } from "./runtime/classify.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAE5D,OAAO,EACL,eAAe,EACf,UAAU,EACV,aAAa,EACb,UAAU,EACV,YAAY,EACZ,SAAS,EACT,UAAU,EACV,cAAc,EACd,kBAAkB,EAClB,SAAS,EACT,mBAAmB,EACnB,aAAa,GACd,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,EACL,uBAAuB,EACvB,kBAAkB,EAClB,sBAAsB,EACtB,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AASnE,OAAO,EAAE,yBAAyB,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEjG,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAEpF,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAEhF,OAAO,EACL,6BAA6B,EAC7B,4BAA4B,EAC5B,iBAAiB,EACjB,wBAAwB,EACxB,uCAAuC,EACvC,8BAA8B,EAC9B,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,mCAAmC,EACnC,0BAA0B,EAC1B,+BAA+B,EAC/B,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,8BAA8B,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAEhG,OAAO,EACL,+BAA+B,EAC/B,yBAAyB,EACzB,wBAAwB,EACxB,2BAA2B,GAC5B,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,+BAA+B,EAC/B,2CAA2C,EAC3C,gCAAgC,EAChC,4BAA4B,EAC5B,4BAA4B,EAC5B,2CAA2C,EAC3C,uBAAuB,EACvB,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,4BAA4B,CAAC;AAOpC,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAEhJ,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAEjH,OAAO,EACL,6BAA6B,EAC7B,qBAAqB,EACrB,iCAAiC,EACjC,sBAAsB,EACtB,gCAAgC,EAChC,iBAAiB,GAClB,MAAM,4BAA4B,CAAC;AASpC,OAAO,EAAE,qBAAqB,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAEhG,OAAO,EACL,wBAAwB,EACxB,gBAAgB,EAChB,cAAc,EACd,+BAA+B,EAC/B,aAAa,EACb,cAAc,EACd,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,eAAe,EACf,cAAc,EACd,qBAAqB,EACrB,aAAa,EACb,6BAA6B,EAC7B,uBAAuB,EACvB,2BAA2B,EAC3B,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,EACb,yBAAyB,EACzB,0BAA0B,EAC1B,WAAW,EACX,kBAAkB,EAClB,UAAU,GACX,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAE5D,OAAO,EACL,eAAe,EACf,UAAU,EACV,aAAa,EACb,UAAU,EACV,YAAY,EACZ,SAAS,EACT,UAAU,EACV,cAAc,EACd,kBAAkB,EAClB,SAAS,EACT,mBAAmB,EACnB,aAAa,GACd,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,EACL,uBAAuB,EACvB,kBAAkB,EAClB,sBAAsB,EACtB,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AASnE,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,iBAAiB,EACjB,yBAAyB,EACzB,oBAAoB,EACpB,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,2BAA2B,CAAC;AAcnC,OAAO,EAAE,yBAAyB,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEjG,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAEpF,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAEhF,OAAO,EACL,6BAA6B,EAC7B,4BAA4B,EAC5B,iBAAiB,EACjB,wBAAwB,EACxB,uCAAuC,EACvC,8BAA8B,EAC9B,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,mCAAmC,EACnC,0BAA0B,EAC1B,+BAA+B,EAC/B,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,8BAA8B,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAEhG,OAAO,EACL,+BAA+B,EAC/B,yBAAyB,EACzB,wBAAwB,EACxB,2BAA2B,GAC5B,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,+BAA+B,EAC/B,2CAA2C,EAC3C,gCAAgC,EAChC,4BAA4B,EAC5B,4BAA4B,EAC5B,2CAA2C,EAC3C,uBAAuB,EACvB,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,4BAA4B,CAAC;AAOpC,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAEhJ,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAEjH,OAAO,EACL,6BAA6B,EAC7B,qBAAqB,EACrB,iCAAiC,EACjC,sBAAsB,EACtB,gCAAgC,EAChC,iBAAiB,GAClB,MAAM,4BAA4B,CAAC;AASpC,OAAO,EAAE,qBAAqB,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAEhG,OAAO,EACL,wBAAwB,EACxB,gBAAgB,EAChB,cAAc,EACd,+BAA+B,EAC/B,aAAa,EACb,cAAc,EACd,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,eAAe,EACf,cAAc,EACd,qBAAqB,EACrB,aAAa,EACb,6BAA6B,EAC7B,uBAAuB,EACvB,2BAA2B,EAC3B,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,EACb,yBAAyB,EACzB,0BAA0B,EAC1B,WAAW,EACX,kBAAkB,EAClB,UAAU,GACX,MAAM,mBAAmB,CAAC"}

package/dist/runtime/app-autonomy.d.ts

@@ -0,0 +1,109 @@
+import type { DatabaseSync } from "node:sqlite";
+export type AppLoopLeaseState = "healthy" | "missing" | "stale";
+export type AppLoopDispatchState = "healthy" | "missing" | "stale";
+export type AppLoopRole = "manager" | "worker";
+export interface AppLoopRoleStatus {
+    codex_app_thread_id: string | null;
+    codex_app_thread_title: string | null;
+    direct_inbox_command: string | null;
+    lease: {
+        age_seconds: number | null;
+        last_heartbeat_at: string | null;
+        stale_after_seconds: number;
+        state: AppLoopLeaseState;
+    };
+    name: string | null;
+    poll_command: string | null;
+    receive_style: "pull" | "push" | null;
+    session_id: string | null;
+    session_kind: "codex_app" | "no_tmux" | "tmux" | null;
+}
+export interface AppLoopNextAction {
+    kind: "start_dispatch" | "wake_manager" | "wake_worker";
+    prompt?: string;
+    reason: string;
+    role?: AppLoopRole;
+}
+export interface AppLoopStatus {
+    dispatch: {
+        dispatcher_id: string;
+        last_heartbeat_at: string | null;
+        state: AppLoopDispatchState;
+    };
+    manager: AppLoopRoleStatus;
+    next_actions: AppLoopNextAction[];
+    ok: boolean;
+    task: {
+        id: string;
+        name: string;
+    };
+    worker: AppLoopRoleStatus;
+}
+export interface AppWakeupPlan {
+    dispatcher: {
+        command: string;
+        required: boolean;
+        state: AppLoopDispatchState;
+    };
+    status: AppLoopStatus;
+    wakeups: AppWakeup[];
+}
+export interface AppWakeup {
+    prompt: string;
+    reason: string;
+    role: AppLoopRole;
+    thread: {
+        id: string | null;
+        title: string | null;
+    };
+}
+export type AppWakeupDispatchActionStatus = "blocked_missing_thread" | "ready_to_send" | "skipped_healthy";
+export interface AppWakeupDispatchAction {
+    blocker: string | null;
+    prompt: string | null;
+    reason: string;
+    role: AppLoopRole;
+    send_ready: boolean;
+    status: AppWakeupDispatchActionStatus;
+    thread: {
+        id: string | null;
+        title: string | null;
+    };
+}
+export interface AppWakeupDispatchPlan {
+    actions: AppWakeupDispatchAction[];
+    dispatcher: AppWakeupPlan["dispatcher"];
+    status: AppLoopStatus;
+    summary: {
+        blocked: number;
+        dispatcher_required: boolean;
+        ready_to_send: number;
+        skipped: number;
+        total_actions: number;
+    };
+}
+export declare function appLoopStatusSync(database: DatabaseSync, options: {
+    dbPath?: string | null;
+    dispatcherId: string;
+    heartbeatStaleSeconds: number;
+    now: string;
+    taskName: string;
+}): AppLoopStatus;
+export declare function appWakeupPlanSync(database: DatabaseSync, options: {
+    dbPath?: string | null;
+    dispatcherId: string;
+    heartbeatStaleSeconds: number;
+    now: string;
+    taskName: string;
+}): AppWakeupPlan;
+export declare function appWakeupDispatchPlanSync(database: DatabaseSync, options: {
+    dbPath?: string | null;
+    dispatcherId: string;
+    heartbeatStaleSeconds: number;
+    now: string;
+    taskName: string;
+}): AppWakeupDispatchPlan;
+export declare function appHeartbeatPollCommand(role: AppLoopRole, taskName: string, dbPath?: string | null): string;
+export declare function appLoopStatusCommand(taskName: string, dbPath?: string | null): string;
+export declare function appWakeupPlanCommand(taskName: string, dbPath?: string | null): string;
+export declare function directInboxPollCommand(role: AppLoopRole, taskName: string, dbPath?: string | null): string;

package/dist/runtime/app-autonomy.js

@@ -0,0 +1,263 @@
+export function appLoopStatusSync(database, options) {
+    const task = database.prepare("select id, name from tasks where name = ?").get(options.taskName);
+    if (!task) {
+        throw new Error(`Task not found: ${options.taskName}`);
+    }
+    const binding = database.prepare(`
+    select ws.id as worker_session_id,
+           ws.name as worker_name,
+           ws.last_heartbeat_at as worker_last_heartbeat_at,
+           ws.codex_app_thread_id as worker_thread_id,
+           ws.codex_app_thread_title as worker_thread_title,
+           ws.tmux_session as worker_tmux_session,
+           ms.id as manager_session_id,
+           ms.name as manager_name,
+           ms.last_heartbeat_at as manager_last_heartbeat_at,
+           ms.codex_app_thread_id as manager_thread_id,
+           ms.codex_app_thread_title as manager_thread_title,
+           ms.tmux_session as manager_tmux_session
+    from bindings
+    left join sessions ws on ws.id = bindings.worker_session_id
+    left join sessions ms on ms.id = bindings.manager_session_id
+    where bindings.task_id = ? and bindings.state in ('active', 'ending')
+    order by bindings.created_at desc
+    limit 1
+  `).get(task.id);
+    if (!binding) {
+        throw new Error(`No active binding for task: ${options.taskName}`);
+    }
+    const dispatchHeartbeat = database.prepare(`
+    select timestamp
+    from telemetry_events
+    where actor = 'dispatch'
+      and event_type = 'dispatch_watch_heartbeat'
+      and json_extract(correlation_json, '$.dispatcher_id') = ?
+    order by timestamp desc, id desc
+    limit 1
+  `).get(options.dispatcherId);
+    const manager = roleStatus({
+        dbPath: options.dbPath ?? null,
+        heartbeatStaleSeconds: options.heartbeatStaleSeconds,
+        lastHeartbeatAt: binding.manager_last_heartbeat_at,
+        name: binding.manager_name,
+        now: options.now,
+        role: "manager",
+        sessionId: binding.manager_session_id,
+        taskName: options.taskName,
+        threadId: binding.manager_thread_id,
+        threadTitle: binding.manager_thread_title,
+        tmuxSession: binding.manager_tmux_session,
+    });
+    const worker = roleStatus({
+        dbPath: options.dbPath ?? null,
+        heartbeatStaleSeconds: options.heartbeatStaleSeconds,
+        lastHeartbeatAt: binding.worker_last_heartbeat_at,
+        name: binding.worker_name,
+        now: options.now,
+        role: "worker",
+        sessionId: binding.worker_session_id,
+        taskName: options.taskName,
+        threadId: binding.worker_thread_id,
+        threadTitle: binding.worker_thread_title,
+        tmuxSession: binding.worker_tmux_session,
+    });
+    const dispatchState = dispatchLeaseState(dispatchHeartbeat?.timestamp ?? null, options.now, options.heartbeatStaleSeconds);
+    const dispatch = {
+        dispatcher_id: options.dispatcherId,
+        last_heartbeat_at: dispatchHeartbeat?.timestamp ?? null,
+        state: dispatchState,
+    };
+    const nextActions = [];
+    if (dispatch.state !== "healthy") {
+        nextActions.push({
+            kind: "start_dispatch",
+            prompt: `Run: conveyor dispatch --watch --dispatcher-id ${shellQuote(options.dispatcherId)}${pathFlag(options.dbPath ?? null)}`,
+            reason: `Dispatch ${options.dispatcherId} is ${dispatch.state}.`,
+        });
+    }
+    if (manager.lease.state !== "healthy") {
+        nextActions.push({
+            kind: "wake_manager",
+            prompt: manager.poll_command ?? undefined,
+            reason: `Manager heartbeat is ${manager.lease.state}.`,
+            role: "manager",
+        });
+    }
+    if (worker.lease.state !== "healthy") {
+        nextActions.push({
+            kind: "wake_worker",
+            prompt: worker.poll_command ?? undefined,
+            reason: `Worker heartbeat is ${worker.lease.state}.`,
+            role: "worker",
+        });
+    }
+    return {
+        dispatch,
+        manager,
+        next_actions: nextActions,
+        ok: dispatch.state === "healthy" && manager.lease.state === "healthy" && worker.lease.state === "healthy",
+        task,
+        worker,
+    };
+}
+export function appWakeupPlanSync(database, options) {
+    const status = appLoopStatusSync(database, options);
+    const wakeups = [];
+    if (status.manager.lease.state !== "healthy") {
+        wakeups.push(roleWakeup("manager", status.manager, status.task.name, options.dbPath ?? null, status.manager.lease.state));
+    }
+    if (status.worker.lease.state !== "healthy") {
+        wakeups.push(roleWakeup("worker", status.worker, status.task.name, options.dbPath ?? null, status.worker.lease.state));
+    }
+    return {
+        dispatcher: {
+            command: `conveyor dispatch --watch --dispatcher-id ${shellQuote(options.dispatcherId)}${pathFlag(options.dbPath ?? null)}`,
+            required: status.dispatch.state !== "healthy",
+            state: status.dispatch.state,
+        },
+        status,
+        wakeups,
+    };
+}
+export function appWakeupDispatchPlanSync(database, options) {
+    const plan = appWakeupPlanSync(database, options);
+    const wakeupsByRole = new Map(plan.wakeups.map((wakeup) => [wakeup.role, wakeup]));
+    const actions = ["manager", "worker"].map((role) => {
+        const roleStatus = role === "manager" ? plan.status.manager : plan.status.worker;
+        const wakeup = wakeupsByRole.get(role);
+        if (!wakeup) {
+            return {
+                blocker: null,
+                prompt: null,
+                reason: `${role} heartbeat is healthy.`,
+                role,
+                send_ready: false,
+                status: "skipped_healthy",
+                thread: {
+                    id: roleStatus.codex_app_thread_id,
+                    title: roleStatus.codex_app_thread_title,
+                },
+            };
+        }
+        if (!wakeup.thread.id) {
+            return {
+                blocker: `No Codex app thread id is registered for the ${role}; use the prompt manually or register app thread metadata before calling send_message_to_thread.`,
+                prompt: wakeup.prompt,
+                reason: wakeup.reason,
+                role,
+                send_ready: false,
+                status: "blocked_missing_thread",
+                thread: wakeup.thread,
+            };
+        }
+        return {
+            blocker: null,
+            prompt: wakeup.prompt,
+            reason: wakeup.reason,
+            role,
+            send_ready: true,
+            status: "ready_to_send",
+            thread: wakeup.thread,
+        };
+    });
+    const ready = actions.filter((action) => action.status === "ready_to_send").length;
+    const blocked = actions.filter((action) => action.status === "blocked_missing_thread").length;
+    const skipped = actions.filter((action) => action.status === "skipped_healthy").length;
+    return {
+        actions,
+        dispatcher: plan.dispatcher,
+        status: plan.status,
+        summary: {
+            blocked,
+            dispatcher_required: plan.dispatcher.required,
+            ready_to_send: ready,
+            skipped,
+            total_actions: actions.length,
+        },
+    };
+}
+export function appHeartbeatPollCommand(role, taskName, dbPath) {
+    return `conveyor app-heartbeat ${shellQuote(taskName)} --role ${role}${pathFlag(dbPath ?? null)} --json`;
+}
+export function appLoopStatusCommand(taskName, dbPath) {
+    return `conveyor app-loop-status ${shellQuote(taskName)}${pathFlag(dbPath ?? null)} --json`;
+}
+export function appWakeupPlanCommand(taskName, dbPath) {
+    return `conveyor app-wakeup-plan ${shellQuote(taskName)}${pathFlag(dbPath ?? null)} --json`;
+}
+export function directInboxPollCommand(role, taskName, dbPath) {
+    const inbox = role === "manager" ? "manager-inbox" : "worker-inbox";
+    return `conveyor ${inbox} ${shellQuote(taskName)} --consume-next --wait --timeout 60${pathFlag(dbPath ?? null)} --json`;
+}
+function roleStatus(options) {
+    const hasTmux = Boolean(options.tmuxSession);
+    return {
+        codex_app_thread_id: options.threadId,
+        codex_app_thread_title: options.threadTitle,
+        direct_inbox_command: directInboxPollCommand(options.role, options.taskName, options.dbPath),
+        lease: {
+            age_seconds: ageSeconds(options.lastHeartbeatAt, options.now),
+            last_heartbeat_at: options.lastHeartbeatAt,
+            stale_after_seconds: options.heartbeatStaleSeconds,
+            state: leaseState(options.lastHeartbeatAt, options.now, options.heartbeatStaleSeconds),
+        },
+        name: options.name,
+        poll_command: appHeartbeatPollCommand(options.role, options.taskName, options.dbPath),
+        receive_style: hasTmux ? "push" : "pull",
+        session_id: options.sessionId,
+        session_kind: hasTmux ? "tmux" : options.threadId ? "codex_app" : "no_tmux",
+    };
+}
+function roleWakeup(role, status, taskName, dbPath, state) {
+    const pollCommand = appHeartbeatPollCommand(role, taskName, dbPath);
+    const directInboxCommand = directInboxPollCommand(role, taskName, dbPath);
+    const roleInstruction = role === "manager"
+        ? "If an item is consumed, verify worker claims before recording conclusions, require concrete evidence, update Conveyor state as appropriate, and produce exactly one next worker task."
+        : "If an item is consumed, execute only that single worker instruction and return exact commands, compact evidence, blockers or residual risk, and exactly one next recommended worker task.";
+    return {
+        prompt: [
+            "Use the manage-codex-workers skill.",
+            `This is the ${role} heartbeat wakeup for task ${taskName}.`,
+            `Run: ${pollCommand}`,
+            `If the heartbeat result asks for direct inbox polling, run: ${directInboxCommand}`,
+            roleInstruction,
+            "If no item is consumed, stop after a one-line idle receipt.",
+            "Idle polling is not completion and does not authorize heartbeat teardown.",
+        ].join("\n"),
+        reason: `${role} heartbeat is ${state}.`,
+        role,
+        thread: {
+            id: status.codex_app_thread_id,
+            title: status.codex_app_thread_title,
+        },
+    };
+}
+function dispatchLeaseState(value, now, staleSeconds) {
+    const state = leaseState(value, now, staleSeconds);
+    return state === "healthy" ? "healthy" : state === "stale" ? "stale" : "missing";
+}
+function leaseState(value, now, staleSeconds) {
+    if (!value) {
+        return "missing";
+    }
+    const age = ageSeconds(value, now);
+    return age !== null && age <= staleSeconds ? "healthy" : "stale";
+}
+function ageSeconds(value, now) {
+    if (!value) {
+        return null;
+    }
+    const parsedNow = Date.parse(now);
+    const parsedValue = Date.parse(value);
+    if (!Number.isFinite(parsedNow) || !Number.isFinite(parsedValue)) {
+        return null;
+    }
+    return Math.max(0, Math.floor((parsedNow - parsedValue) / 1000));
+}
+function pathFlag(dbPath) {
+    return dbPath ? ` --path ${shellQuote(dbPath)}` : "";
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, "'\"'\"'")}'`;
+}
+//# sourceMappingURL=app-autonomy.js.map

package/dist/runtime/app-autonomy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-autonomy.js","sourceRoot":"","sources":["../../src/runtime/app-autonomy.ts"],"names":[],"mappings":"AA2FA,MAAM,UAAU,iBAAiB,CAC/B,QAAsB,EACtB,OAMC;IAED,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,2CAA2C,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,CAElF,CAAC;IACd,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CAAC,mBAAmB,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IACzD,CAAC;IAED,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC;;;;;;;;;;;;;;;;;;;GAmBhC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAA8C,CAAC;IAC7D,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,+BAA+B,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IACrE,CAAC;IAED,MAAM,iBAAiB,GAAG,QAAQ,CAAC,OAAO,CAAC;;;;;;;;GAQ1C,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,YAAY,CAAsC,CAAC;IAElE,MAAM,OAAO,GAAG,UAAU,CAAC;QACzB,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,IAAI;QAC9B,qBAAqB,EAAE,OAAO,CAAC,qBAAqB;QACpD,eAAe,EAAE,OAAO,CAAC,yBAAyB;QAClD,IAAI,EAAE,OAAO,CAAC,YAAY;QAC1B,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,IAAI,EAAE,SAAS;QACf,SAAS,EAAE,OAAO,CAAC,kBAAkB;QACrC,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,QAAQ,EAAE,OAAO,CAAC,iBAAiB;QACnC,WAAW,EAAE,OAAO,CAAC,oBAAoB;QACzC,WAAW,EAAE,OAAO,CAAC,oBAAoB;KAC1C,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,UAAU,CAAC;QACxB,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,IAAI;QAC9B,qBAAqB,EAAE,OAAO,CAAC,qBAAqB;QACpD,eAAe,EAAE,OAAO,CAAC,wBAAwB;QACjD,IAAI,EAAE,OAAO,CAAC,WAAW;QACzB,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,IAAI,EAAE,QAAQ;QACd,SAAS,EAAE,OAAO,CAAC,iBAAiB;QACpC,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,QAAQ,EAAE,OAAO,CAAC,gBAAgB;QAClC,WAAW,EAAE,OAAO,CAAC,mBAAmB;QACxC,WAAW,EAAE,OAAO,CAAC,mBAAmB;KACzC,CAAC,CAAC;IACH,MAAM,aAAa,GAAG,kBAAkB,CAAC,iBAAiB,EAAE,SAAS,IAAI,IAAI,EAAE,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC3H,MAAM,QAAQ,GAAG;QACf,aAAa,EAAE,OAAO,CAAC,YAAY;QACnC,iBAAiB,EAAE,iBAAiB,EAAE,SAAS,IAAI,IAAI;QACvD,KAAK,EAAE,aAAa;KACrB,CAAC;IACF,MAAM,WAAW,GAAwB,EAAE,CAAC;IAC5C,IAAI,QAAQ,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QACjC,WAAW,CAAC,IAAI,CAAC;YACf,IAAI,EAAE,gBAAgB;YACtB,MAAM,EAAE,kDAAkD,UAAU,CAAC,OAAO,CAAC,YAAY,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC,EAAE;YAC/H,MAAM,EAAE,YAAY,OAAO,CAAC,YAAY,OAAO,QAAQ,CAAC,KAAK,GAAG;SACjE,CAAC,CAAC;IACL,CAAC;IACD,IAAI,OAAO,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QACtC,WAAW,CAAC,IAAI,CAAC;YACf,IAAI,EAAE,cAAc;YACpB,MAAM,EAAE,OAAO,CAAC,YAAY,IAAI,SAAS;YACzC,MAAM,EAAE,wBAAwB,OAAO,CAAC,KAAK,CAAC,KAAK,GAAG;YACtD,IAAI,EAAE,SAAS;SAChB,CAAC,CAAC;IACL,CAAC;IACD,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QACrC,WAAW,CAAC,IAAI,CAAC;YACf,IAAI,EAAE,aAAa;YACnB,MAAM,EAAE,MAAM,CAAC,YAAY,IAAI,SAAS;YACxC,MAAM,EAAE,uBAAuB,MAAM,CAAC,KAAK,CAAC,KAAK,GAAG;YACpD,IAAI,EAAE,QAAQ;SACf,CAAC,CAAC;IACL,CAAC;IAED,OAAO;QACL,QAAQ;QACR,OAAO;QACP,YAAY,EAAE,WAAW;QACzB,EAAE,EAAE,QAAQ,CAAC,KAAK,KAAK,SAAS,IAAI,OAAO,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS;QACzG,IAAI;QACJ,MAAM;KACP,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,QAAsB,EACtB,OAMC;IAED,MAAM,MAAM,GAAG,iBAAiB,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACpD,MAAM,OAAO,GAAgB,EAAE,CAAC;IAChC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC7C,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,SAAS,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,MAAM,IAAI,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;IAC5H,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC5C,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,MAAM,IAAI,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;IACzH,CAAC;IACD,OAAO;QACL,UAAU,EAAE;YACV,OAAO,EAAE,6CAA6C,UAAU,CAAC,OAAO,CAAC,YAAY,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC,EAAE;YAC3H,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,KAAK,KAAK,SAAS;YAC7C,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,KAAK;SAC7B;QACD,MAAM;QACN,OAAO;KACR,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,yBAAyB,CACvC,QAAsB,EACtB,OAMC;IAED,MAAM,IAAI,GAAG,iBAAiB,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAClD,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IACnF,MAAM,OAAO,GAAI,CAAC,SAAS,EAAE,QAAQ,CAAW,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QAC5D,MAAM,UAAU,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;QACjF,MAAM,MAAM,GAAG,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACvC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,MAAM,EAAE,IAAI;gBACZ,MAAM,EAAE,GAAG,IAAI,wBAAwB;gBACvC,IAAI;gBACJ,UAAU,EAAE,KAAK;gBACjB,MAAM,EAAE,iBAA0B;gBAClC,MAAM,EAAE;oBACN,EAAE,EAAE,UAAU,CAAC,mBAAmB;oBAClC,KAAK,EAAE,UAAU,CAAC,sBAAsB;iBACzC;aACF,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;YACtB,OAAO;gBACL,OAAO,EAAE,gDAAgD,IAAI,kGAAkG;gBAC/J,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,IAAI;gBACJ,UAAU,EAAE,KAAK;gBACjB,MAAM,EAAE,wBAAiC;gBACzC,MAAM,EAAE,MAAM,CAAC,MAAM;aACtB,CAAC;QACJ,CAAC;QACD,OAAO;YACL,OAAO,EAAE,IAAI;YACb,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,IAAI;YACJ,UAAU,EAAE,IAAI;YAChB,MAAM,EAAE,eAAwB;YAChC,MAAM,EAAE,MAAM,CAAC,MAAM;SACtB,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,KAAK,eAAe,CAAC,CAAC,MAAM,CAAC;IACnF,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,KAAK,wBAAwB,CAAC,CAAC,MAAM,CAAC;IAC9F,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,KAAK,iBAAiB,CAAC,CAAC,MAAM,CAAC;IACvF,OAAO;QACL,OAAO;QACP,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,OAAO,EAAE;YACP,OAAO;YACP,mBAAmB,EAAE,IAAI,CAAC,UAAU,CAAC,QAAQ;YAC7C,aAAa,EAAE,KAAK;YACpB,OAAO;YACP,aAAa,EAAE,OAAO,CAAC,MAAM;SAC9B;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,IAAiB,EAAE,QAAgB,EAAE,MAAsB;IACjG,OAAO,0BAA0B,UAAU,CAAC,QAAQ,CAAC,WAAW,IAAI,GAAG,QAAQ,CAAC,MAAM,IAAI,IAAI,CAAC,SAAS,CAAC;AAC3G,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,QAAgB,EAAE,MAAsB;IAC3E,OAAO,4BAA4B,UAAU,CAAC,QAAQ,CAAC,GAAG,QAAQ,CAAC,MAAM,IAAI,IAAI,CAAC,SAAS,CAAC;AAC9F,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,QAAgB,EAAE,MAAsB;IAC3E,OAAO,4BAA4B,UAAU,CAAC,QAAQ,CAAC,GAAG,QAAQ,CAAC,MAAM,IAAI,IAAI,CAAC,SAAS,CAAC;AAC9F,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,IAAiB,EAAE,QAAgB,EAAE,MAAsB;IAChG,MAAM,KAAK,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,cAAc,CAAC;IACpE,OAAO,YAAY,KAAK,IAAI,UAAU,CAAC,QAAQ,CAAC,sCAAsC,QAAQ,CAAC,MAAM,IAAI,IAAI,CAAC,SAAS,CAAC;AAC1H,CAAC;AAED,SAAS,UAAU,CAAC,OAYnB;IACC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC7C,OAAO;QACL,mBAAmB,EAAE,OAAO,CAAC,QAAQ;QACrC,sBAAsB,EAAE,OAAO,CAAC,WAAW;QAC3C,oBAAoB,EAAE,sBAAsB,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC;QAC5F,KAAK,EAAE;YACL,WAAW,EAAE,UAAU,CAAC,OAAO,CAAC,eAAe,EAAE,OAAO,CAAC,GAAG,CAAC;YAC7D,iBAAiB,EAAE,OAAO,CAAC,eAAe;YAC1C,mBAAmB,EAAE,OAAO,CAAC,qBAAqB;YAClD,KAAK,EAAE,UAAU,CAAC,OAAO,CAAC,eAAe,EAAE,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,qBAAqB,CAAC;SACvF;QACD,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,YAAY,EAAE,uBAAuB,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC;QACrF,aAAa,EAAE,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM;QACxC,UAAU,EAAE,OAAO,CAAC,SAAS;QAC7B,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS;KAC5E,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CACjB,IAAiB,EACjB,MAAyB,EACzB,QAAgB,EAChB,MAAqB,EACrB,KAAwB;IAExB,MAAM,WAAW,GAAG,uBAAuB,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IACpE,MAAM,kBAAkB,GAAG,sBAAsB,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC1E,MAAM,eAAe,GAAG,IAAI,KAAK,SAAS;QACxC,CAAC,CAAC,uLAAuL;QACzL,CAAC,CAAC,2LAA2L,CAAC;IAChM,OAAO;QACL,MAAM,EAAE;YACN,qCAAqC;YACrC,eAAe,IAAI,8BAA8B,QAAQ,GAAG;YAC5D,QAAQ,WAAW,EAAE;YACrB,+DAA+D,kBAAkB,EAAE;YACnF,eAAe;YACf,6DAA6D;YAC7D,2EAA2E;SAC5E,CAAC,IAAI,CAAC,IAAI,CAAC;QACZ,MAAM,EAAE,GAAG,IAAI,iBAAiB,KAAK,GAAG;QACxC,IAAI;QACJ,MAAM,EAAE;YACN,EAAE,EAAE,MAAM,CAAC,mBAAmB;YAC9B,KAAK,EAAE,MAAM,CAAC,sBAAsB;SACrC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAoB,EAAE,GAAW,EAAE,YAAoB;IACjF,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,EAAE,GAAG,EAAE,YAAY,CAAC,CAAC;IACnD,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;AACnF,CAAC;AAED,SAAS,UAAU,CAAC,KAAoB,EAAE,GAAW,EAAE,YAAoB;IACzE,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,GAAG,GAAG,UAAU,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACnC,OAAO,GAAG,KAAK,IAAI,IAAI,GAAG,IAAI,YAAY,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC;AACnE,CAAC;AAED,SAAS,UAAU,CAAC,KAAoB,EAAE,GAAW;IACnD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAClC,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACtC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;QACjE,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,SAAS,GAAG,WAAW,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;AACnE,CAAC;AAED,SAAS,QAAQ,CAAC,MAAqB;IACrC,OAAO,MAAM,CAAC,CAAC,CAAC,WAAW,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AACvD,CAAC;AAED,SAAS,UAAU,CAAC,KAAa;IAC/B,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,SAAS,CAAC,GAAG,CAAC;AAC/C,CAAC"}

package/docs/manager-recipes.md

@@ -273,17 +273,47 @@ report heartbeat teardown status. If the task or binding still appears active,
 report that as a control-plane blocker instead of calling the loop complete.
 
 When the manager is running in the Codex app and thread tools are available,
-create the worker with fresh same-project `create_thread`, set a readable title
-with `set_thread_title`, and pass the resulting id/title into
-`conveyor create-disposable-binding` with
-`--worker-codex-app-thread-id` and `--worker-codex-app-thread-title`. Use
-`send_message_to_thread` only to deliver the generated `worker_handoff`
-bootstrap prompt; ongoing manager/worker communication should still be routed
+create fresh same-project manager and worker threads with `create_thread`, set
+readable titles, and pass both ids/titles into `conveyor
+create-disposable-binding` with `--manager-codex-app-thread-id`,
+`--manager-codex-app-thread-title`, `--worker-codex-app-thread-id`, and
+`--worker-codex-app-thread-title`. Use `send_message_to_thread` for bootstrap
+prompts only; ongoing manager/worker communication should still be routed
 through Dispatch and consumed from inboxes. If app thread tools are unavailable,
 open the worker session manually and paste the same `worker_handoff` prompt.
 Do not use `fork_thread` for this recipe unless the user explicitly wants a
 fork of the current conversation.
 
+### Codex App Native Manager/Worker Loop
+
+```bash
+conveyor doctor
+conveyor db-doctor
+conveyor create-disposable-binding "$TASK" \
+  --worker "$WORKER" \
+  --manager "$MANAGER" \
+  --worker-codex-app-thread-id "$WORKER_THREAD_ID" \
+  --worker-codex-app-thread-title "$WORKER_THREAD_TITLE" \
+  --manager-codex-app-thread-id "$MANAGER_THREAD_ID" \
+  --manager-codex-app-thread-title "$MANAGER_THREAD_TITLE" \
+  --adversarial \
+  --json
+conveyor dispatch --watch --dispatcher-id dispatch-local
+conveyor app-heartbeat "$TASK" --role manager --json
+conveyor app-heartbeat "$TASK" --role worker --json
+conveyor app-loop-status "$TASK" --json
+conveyor app-wakeup-plan "$TASK" --json
+conveyor app-wakeup-dispatch "$TASK" --json
+```
+
+Use `app-loop-status` as the operator status surface. If it reports stale
+manager, worker, or Dispatch leases, use `app-wakeup-plan` to get the exact
+thread prompt to send through Codex app automation or `send_message_to_thread`.
+Use `app-wakeup-dispatch` when the manager needs a durable Conveyor receipt for
+which app wake actions were prepared, skipped, or blocked. It only prepares
+adapter-ready actions; direct app-thread delivery remains an app/operator
+action, and Dispatch/inboxes remain the durable task state.
+
 The saved dogfood example is
 `docs/goals/live-codex-app-inbox-drill/notes/T001-live-drill.md`. It proves
 manager-to-worker `nudge_worker` delivery and worker-to-manager

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-conveyor",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Local agent manager/worker conveyor control plane for Codex sessions.",
   "license": "MIT",
   "type": "module",

package/skills/manage-codex-workers/SKILL.md

@@ -35,25 +35,29 @@ Skill behavior:
    report blockers.
 3. Choose concise task, worker, manager, and run names when the user does not
    provide them. Do not ask the user to invent generated names.
-4. If running in the Codex app and thread tools are available, create a fresh
-   same-project worker thread with `create_thread`, name it with
-   `set_thread_title`, and keep the returned thread id/title. Use
-   `create_thread` for this flow; do not use `fork_thread` unless the user
-   explicitly asks to fork or resume this exact conversation.
+4. Preferred fully app-native setup: if running in the Codex app and thread
+   tools are available, create fresh same-project manager and worker threads
+   with `create_thread`, give both readable titles, and keep both returned
+   thread ids/titles. Use `create_thread` for this flow; do not use
+   `fork_thread` unless the user explicitly asks to fork or resume this exact
+   conversation. If the current thread is explicitly acting as the manager,
+   use the current thread as manager and create only the worker thread.
 5. Create the no-tmux binding with `conveyor create-disposable-binding`
    using `--template` when a template is known, `--adversarial`, a bounded
-   `--max-iterations`, and `--json`. When step 4 produced a worker thread id,
-   pass it through `--worker-codex-app-thread-id` and
-   `--worker-codex-app-thread-title` so Conveyor can surface the app identity
-   in `sessions`, `discover`, and setup JSON. If app thread tools are not
-   available, create the binding without those flags and ask the user to open a
-   separate Codex app worker session manually.
+   `--max-iterations`, and `--json`. When step 4 produced app thread ids, pass
+   them through `--manager-codex-app-thread-id`,
+   `--manager-codex-app-thread-title`, `--worker-codex-app-thread-id`, and
+   `--worker-codex-app-thread-title` so Conveyor can surface app identities in
+   `sessions`, `discover`, and setup JSON. If app thread tools are not
+   available, create the binding without those flags and ask the user to open
+   separate Codex app sessions manually.
 6. Ensure Dispatch is running or tell the user the single command to start it:
    `conveyor dispatch --watch --dispatcher-id dispatch-local`.
 7. Read the returned `communication` blocks. A worker or manager with
    `session_kind=tmux` and `receive_style=push` can receive direct tmux pushes;
    one with `session_kind=codex_app` and `receive_style=pull` must poll the
-   printed inbox command.
+   printed `app-heartbeat` command, using direct inbox commands only when the
+   heartbeat output or setup JSON provides them as fallbacks.
 8. Give the worker Codex app session the generated `worker_handoff` prompt.
    If step 4 created a fresh worker thread, use `send_message_to_thread` only
    to deliver that bootstrap prompt. Durable manager/worker communication still
@@ -72,10 +76,12 @@ Skill behavior:
 Idle polling rule for Codex app/no-tmux sessions:
 
 - When a worker has `session_kind=codex_app` or `receive_style=pull`, its
-  idle/check-in command is the returned
-  `communication.poll_command` or generated `worker_handoff` command.
+  default idle/check-in command is the returned `app-heartbeat` worker command.
+  Use `communication.poll_command` or the generated `worker_handoff` command as
+  fallback/direct inbox polling.
 - When a manager has `session_kind=codex_app` or `receive_style=pull`, its
-  idle/check-in command is the returned `communication.poll_command`.
+  default idle/check-in command is the returned `app-heartbeat` manager command.
+  Use `communication.poll_command` as fallback/direct inbox polling.
 - The printed command may include a local `PATH=.../bin:$PATH conveyor` prefix;
   preserve that prefix when giving the command to a Codex app thread.
 - Repeat the appropriate command whenever the session is idle, after finishing
@@ -83,6 +89,13 @@ Idle polling rule for Codex app/no-tmux sessions:
   A timeout is not completion; it is only a quiet poll interval.
 - Keep `conveyor dispatch --watch --dispatcher-id dispatch-local` running so
   Dispatch can route new messages into those inboxes.
+- Use `conveyor app-loop-status <task> --json` as the operator status surface,
+  and `conveyor app-wakeup-plan <task> --json` to produce exact stale-thread
+  wake prompts for Codex app automation or `send_message_to_thread`.
+- Use `conveyor app-wakeup-dispatch <task> --json` when the manager needs an
+  auditable wake orchestration receipt. It prepares adapter-ready app-thread
+  actions, reports skipped and blocked roles, and records telemetry; it does
+  not send direct app-thread messages itself.
 - For bounded Ralph loops, treat `ralph_loop_iteration_advanced` telemetry as
   the receipt that a worker actually consumed and began the requested
   iteration.
@@ -727,15 +740,19 @@ etc.) run `conveyor db-doctor --live`.
 ## Natural-Language Command Mapping
 
 - "set up a Codex app Ralph loop": if the current session has Codex app thread
-  tools, call `create_thread` for a fresh same-project worker, call
-  `set_thread_title`, run `conveyor create-disposable-binding` with
-  `--worker-codex-app-thread-id` and `--worker-codex-app-thread-title`, then
-  send the returned `worker_handoff` using `send_message_to_thread`. If those
-  tools are unavailable, run `create-disposable-binding` without thread
-  metadata and give the user the `worker_handoff` prompt to paste into a
-  manually opened worker. Keep Dispatch as the source of durable communication,
-  and make both Codex app sessions repeat their role-specific inbox poll while
-  idle.
+  tools, call `create_thread` for fresh same-project manager and worker
+  threads unless the current thread is explicitly the manager, set readable
+  titles, run `conveyor create-disposable-binding` with both
+  `--manager-codex-app-thread-id`/`--manager-codex-app-thread-title` and
+  `--worker-codex-app-thread-id`/`--worker-codex-app-thread-title`, then send
+  the returned bootstrap prompts using `send_message_to_thread`. If those tools
+  are unavailable, run `create-disposable-binding` without thread metadata and
+  give the user the handoff prompts to paste into manually opened sessions. Keep
+  Dispatch as the source of durable communication, and make both Codex app
+  sessions repeat their role-specific `app-heartbeat` command while idle. Use
+  `app-loop-status` and `app-wakeup-plan` for operator status and stale-thread
+  recovery, and `app-wakeup-dispatch` when the manager needs an auditable
+  prepared/skipped/blocked wake receipt.
 - "register this Codex session as the worker for dashboard setup <CODE>":
   derive `dashboard-<CODE>-worker`, run `conveyor doctor-self`, then
   `conveyor register-worker --name dashboard-<CODE>-worker --pid <PID> --cwd <CWD> --tmux-session <SESSION>`.