agent-conveyor 0.1.24 → 0.1.26

package/README.md

@@ -122,7 +122,10 @@ PATH="$tmp_prefix/bin:$PATH" conveyor --help
 PATH="$tmp_prefix/bin:$PATH" workerctl --help
 ```
 
-`conveyor doctor` reports local dependency health (tmux, codex, etc.).
+`conveyor doctor --json` reports local dependency health (tmux, codex, etc.),
+package/bin resolution, Codex home, installed operator plugin version, installed
+operator skills, and an `operator_ready` summary for Codex app manager/worker
+setup.
 `conveyor db-doctor` initializes and checks the SQLite control-plane
 database.
 On Node versions where `node:sqlite` is still marked experimental, SQLite
@@ -151,6 +154,13 @@ static landing page. From the repo, `npm run docs:landing` serves it at
 `http://127.0.0.1:8765/`.
 The GitHub Pages version lives at
 [`neonwatty.github.io/agent-conveyor`](https://neonwatty.github.io/agent-conveyor/).
+Pages deploys from the protected `landing-page` branch through the
+`Pages` GitHub Actions workflow; propose public landing-page edits against
+that branch rather than relying on ordinary `main` package PRs to publish the
+site.
+Pull requests into `landing-page` run the `Landing Page PR` workflow, which
+checks linting, unused exports/files, tests, build output, the landing-page
+screenshot gate, and a diff-scoped max-lines guard for changed text files.
 Use `node scripts/check-landing-page.mjs` for a docs-only desktop/mobile
 screenshot gate; this does not run the full package release smoke.
 
@@ -163,7 +173,7 @@ and inspect the plugin:
 ```bash
 npm install -g agent-conveyor
 conveyor install-plugin
-conveyor plugin-status
+conveyor doctor --json
 ```
 
 The per-project default ledger for operator sessions is
@@ -189,15 +199,19 @@ the no-tmux binding with `create-disposable-binding`, point the worker at
 that the loop is ready. Pair and worker-set skills run
 `conveyor-smoke-app-connections` before real task work by default. Required
 smoke first checks package/plugin/ledger/thread metadata, then starts a
-nonce-scoped `app-smoke` session and blocks real work until the manager and each
-worker have visible app-thread send receipts, fresh app heartbeats, durable
-received/accepted acknowledgements, and an `app-smoke status` result with
-`real_work_allowed=true`. The plain CLI records and evaluates receipts; the
-Codex app skill/operator layer must perform live `send_message_to_thread`
-delivery and record `sent`, `blocked`, or skipped/advisory evidence. After
-required smoke passes, pair and worker-set skills start `app-autopilot` before
-real work so the just-proved sessions keep polling. A setup is autonomous only
-when the emitted heartbeat automation specs have been applied, or explicitly
+nonce-scoped `app-smoke` session and blocks real work until the worker has
+accepted smoke and delivered the manager report, then the manager validates
+that report. Both roles need visible app-thread send receipts, fresh app
+heartbeats, durable received/accepted acknowledgements, and an
+`app-smoke status` result with `real_work_allowed=true`. The plain CLI records
+and evaluates receipts; the Codex app skill/operator layer must perform live
+`send_message_to_thread` delivery and record `sent`, `blocked`, or
+skipped/advisory evidence. If a smoke role blocks and later succeeds, the later
+accepted receipt for the same smoke id/nonce becomes the current terminal role
+state. After required smoke passes, pair and worker-set skills start
+`app-autopilot` before real work so the just-proved sessions keep polling. A
+setup is autonomous only when the emitted heartbeat automation specs have been
+applied and recorded with `app-autopilot record-automation`, or explicitly
 deferred as `manual-poll only`; smoke-passed by itself only proves connection
 plumbing at that moment.
 When the manager is itself running in the Codex app and
@@ -538,16 +552,19 @@ stay out of receipts.
   a matching `ready_to_send` action with `send_ready=true` and the same thread
   id; healthy roles must be recorded as `skipped`; missing-thread blockers and
   failed app-thread sends must be recorded as `blocked` with a reason.
-- `app-autopilot start|stop|status TASK [--dispatcher-id ID]
+- `app-autopilot start|stop|status|record-automation TASK [--dispatcher-id ID]
   [--interval SECONDS] [--watch-iterations N] [--stale-after N]
-  [--quiet-after N] [--json]` —
+  [--quiet-after N] [--role manager|worker --automation-id ID] [--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.
+  operator session using the emitted specs, then run `record-automation` once
+  per created role automation. Conveyor remains the durable source of truth
+  through Dispatch, inboxes, automation-applied receipts, wake receipts, and app
+  heartbeat status. `status` reports `plan.readiness`; do not call a loop
+  autonomous unless `plan.readiness.autonomous_ready=true`.
   `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

package/dist/cli/typescript-runtime.js

@@ -444,13 +444,14 @@ function commandHelpText(program, command) {
             `  ${program} dispatch --once --type nudge_worker --path /tmp/work/workerctl.db`,
         ],
         "app-autopilot": [
-            `usage: ${program} app-autopilot start|stop|status <task> [--dispatcher-id ID] [--interval SECONDS] [--watch-iterations N] [--stale-after N] [--quiet-after N] ${path} [--json]`,
+            `usage: ${program} app-autopilot start|stop|status|record-automation <task> [--dispatcher-id ID] [--interval SECONDS] [--watch-iterations N] [--stale-after N] [--quiet-after N] [--role manager|worker --automation-id ID] ${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 record-automation dogfood --role worker --automation-id conveyor-dogfood-worker-heartbeat --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`,
         ],
@@ -544,6 +545,7 @@ function parseRuntimeArgs(args, env) {
         all: false,
         allowAdditionalReceipt: false,
         action: null,
+        automationId: null,
         artifactPath: null,
         assetType: null,
         assignment: null,
@@ -1128,7 +1130,7 @@ function parseRuntimeArgs(args, env) {
             index += 1;
         }
         else if (arg === "--codex-home") {
-            if (command !== "install-skills" && command !== "install-plugin" && command !== "plugin-status" && command !== "plugin-path") {
+            if (command !== "install-skills" && command !== "install-plugin" && command !== "plugin-status" && command !== "plugin-path" && command !== "doctor") {
                 return { command, enabled, error: "Unsupported TypeScript runtime option: --codex-home", explicit, flags, task };
             }
             const value = valueAfter(queue, index, arg);
@@ -1450,6 +1452,17 @@ function parseRuntimeArgs(args, env) {
             flags.codexProfile = value.value;
             index += 1;
         }
+        else if (arg === "--automation-id") {
+            if (command !== "app-autopilot") {
+                return { command, enabled, error: "Unsupported TypeScript runtime option: --automation-id", explicit, flags, task };
+            }
+            const value = valueAfter(queue, index, arg);
+            if (value.error) {
+                return { command, enabled, error: value.error, explicit, flags, task };
+            }
+            flags.automationId = value.value;
+            index += 1;
+        }
         else if (arg === "--session-dir") {
             if (command !== "create-disposable-binding") {
                 return { command, enabled, error: "Unsupported TypeScript runtime option: --session-dir", explicit, flags, task };
@@ -3130,7 +3143,7 @@ function parseRuntimeArgs(args, env) {
             flags.subtype = arg;
         }
         else if (command === "app-autopilot" && flags.action === null) {
-            if (!["start", "stop", "status"].includes(arg)) {
+            if (!["record-automation", "start", "stop", "status"].includes(arg)) {
                 return { command, enabled, error: `Unsupported app-autopilot action: ${arg}`, explicit, flags, task };
             }
             flags.action = arg;
@@ -4349,8 +4362,8 @@ function renderAppWorkerRotationPlanText(plan) {
 }
 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");
+    if (action !== "record-automation" && action !== "start" && action !== "stop" && action !== "status") {
+        return errorResult("app-autopilot requires an action: start, stop, status, or record-automation");
     }
     const taskName = requireTask(parsed);
     const database = openRuntimeDatabase(parsed, options);
@@ -4358,7 +4371,39 @@ function runAppAutopilotCommand(parsed, options) {
         const timestamp = nowIsoSeconds(options);
         const dbPath = runtimeDbPath(parsed, options);
         const dispatcherId = parsed.flags.dispatcherId ?? "dispatch-local";
+        const task = taskRowForDiagnostics(database, taskName);
         const desiredState = action === "start" ? "active" : action === "stop" ? "stopped" : null;
+        let receipt = null;
+        if (action === "record-automation") {
+            const role = parseAppSmokeRole(parsed.flags.role);
+            if (role instanceof Error) {
+                return errorResult(role.message);
+            }
+            const automationId = requiredStringFlag(parsed.flags.automationId, "--automation-id");
+            const eventId = emitTelemetrySync(database, {
+                actor: "operator",
+                attributes: {
+                    automation_id: automationId,
+                    role,
+                },
+                correlation: {
+                    action,
+                    command: "app-autopilot",
+                    dispatcher_id: dispatcherId,
+                    role,
+                },
+                eventType: "app_autopilot_automation_applied",
+                severity: "info",
+                summary: `App autopilot ${role} automation applied for ${task.name}.`,
+                taskId: task.id,
+                timestamp,
+            });
+            receipt = {
+                event_id: eventId,
+                event_type: "app_autopilot_automation_applied",
+                recorded_at: timestamp,
+            };
+        }
         let plan = appAutopilotPlanSync(database, {
             dbPath,
             dispatchIntervalSeconds: parsed.flags.intervalSeconds,
@@ -4371,12 +4416,12 @@ function runAppAutopilotCommand(parsed, options) {
             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_state: plan.automation_state,
                     automation_specs: plan.automation_specs.map((spec) => ({
                         can_create: spec.can_create,
                         interval_minutes: spec.interval_minutes,
@@ -4390,6 +4435,7 @@ function runAppAutopilotCommand(parsed, options) {
                     dispatcher_id: dispatcherId,
                     interval_minutes: plan.interval_minutes,
                     quiescence: plan.quiescence,
+                    readiness: plan.readiness,
                     summary: plan.summary,
                 },
                 correlation: {
@@ -4662,8 +4708,10 @@ function appSmokeRoleStatus(role, session, receipts, smoke, options) {
     const roleReceipts = receipts.filter((receipt) => receipt.role === role && receipt.nonce === smoke.nonce);
     const sent = roleReceipts.some((receipt) => receipt.status === "sent");
     const received = roleReceipts.some((receipt) => receipt.status === "received");
-    const accepted = roleReceipts.some((receipt) => receipt.status === "accepted");
-    const blockedReceipt = roleReceipts.find((receipt) => receipt.status === "blocked");
+    const terminalReceipts = roleReceipts.filter((receipt) => receipt.status === "accepted" || receipt.status === "blocked");
+    const terminalReceipt = terminalReceipts.at(-1);
+    const accepted = terminalReceipt?.status === "accepted";
+    const blockedReceipt = terminalReceipt?.status === "blocked" ? terminalReceipt : undefined;
     const heartbeatFresh = session.last_heartbeat_at !== null
         && session.last_heartbeat_at >= smoke.recorded_at
         && secondsBetweenIso(session.last_heartbeat_at, options.now) <= options.staleAfterSeconds;
@@ -4739,14 +4787,18 @@ function latestAppSmokeSessionSync(database, options) {
 }
 function appSmokeReceiptsSync(database, options) {
     const rows = database.prepare(`
-    select attributes_json
+    select id, timestamp, attributes_json
     from telemetry_events
     where task_id = ?
       and event_type = 'app_smoke_receipt_recorded'
       and json_extract(attributes_json, '$.smoke_id') = ?
     order by timestamp, id
   `).all(options.taskId, options.smokeId);
-    return rows.map((row) => JSON.parse(row.attributes_json));
+    return rows.map((row) => ({
+        ...JSON.parse(row.attributes_json),
+        event_id: row.id,
+        recorded_at: row.timestamp,
+    }));
 }
 function appSmokeBoundSessionsSync(database, taskId) {
     const row = database.prepare(`
@@ -4952,6 +5004,7 @@ function renderAppWakeupPlanText(plan) {
 function renderAppAutopilotText(result) {
     const lines = [
         `App autopilot ${result.action} for ${result.plan.task.name}: ${result.plan.desired_state}`,
+        `Readiness: ${result.plan.readiness.state}${result.plan.readiness.autonomous_ready ? " (autonomous)" : " (setup required)"}`,
         `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}`,
@@ -4973,12 +5026,19 @@ function renderAppAutopilotText(result) {
     else {
         lines.push("Last policy: unconfigured");
     }
+    for (const blocker of result.plan.readiness.blockers) {
+        lines.push(`Readiness blocker: ${blocker}`);
+    }
     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}`);
         }
     }
+    for (const role of result.plan.automation_state.applied_roles) {
+        const receipt = result.plan.automation_state.receipts.find((item) => item.role === role);
+        lines.push(`${role} automation applied: ${receipt?.automation_id ?? "(unknown)"}`);
+    }
     lines.push(result.plan.control.note);
     return `${lines.join("\n")}\n`;
 }
@@ -11892,9 +11952,20 @@ function runDoctorCommand(parsed, options) {
     const root = stateRoot({ cwd: targetCwd, env: options.env });
     const tmuxPath = commandPath("tmux", options);
     const codexPath = options.codexCommandResolver?.("codex") ?? commandPath("codex", options);
+    const conveyorPath = commandPath("conveyor", options);
+    const workerctlPath = commandPath("workerctl", options);
+    const packageRoot = packageRootFromRuntimeModule();
+    const packageVersion = packageVersionFromRoot(packageRoot);
+    const plugin = agentConveyorPluginStatus(parsed, options);
+    const pluginSkillsInstalled = plugin.skills.every((skill) => skill.installed);
     const checks = [
         { name: "tmux", ok: Boolean(tmuxPath), path: tmuxPath },
         { name: "codex", ok: Boolean(codexPath), path: codexPath },
+        { name: "conveyor_on_path", ok: Boolean(conveyorPath), path: conveyorPath },
+        { name: "workerctl_on_path", ok: Boolean(workerctlPath), path: workerctlPath },
+        { name: "plugin_installed", ok: plugin.installed, installed_version: plugin.installed_version },
+        { name: "plugin_version_matches", ok: plugin.version_matches, package_version: packageVersion, plugin_version: plugin.plugin_version },
+        { name: "plugin_skills_installed", ok: pluginSkillsInstalled, missing: plugin.skills.filter((skill) => !skill.installed).map((skill) => skill.name) },
     ];
     if (tmuxPath) {
         const proc = runProcess(["tmux", "-V"], options);
@@ -11906,8 +11977,44 @@ function runDoctorCommand(parsed, options) {
     }
     checks.push({ name: "target_cwd_exists", ok: pathIsDirectory(targetCwd), path: targetCwd });
     checks.push({ name: "state_root_exists", ok: existsSync(root), path: root });
-    const ok = checks.every((check) => check.name === "state_root_exists" || check.ok === true);
-    return { ...jsonResult({ checks, ok, project_root: packageRootFromRuntimeModule(), workers: doctorWorkerSummaries(root) }), exitCode: ok ? 0 : 1 };
+    const commandReady = Boolean(conveyorPath) && Boolean(workerctlPath) && Boolean(codexPath) && Boolean(tmuxPath);
+    const operatorReady = commandReady && plugin.installed && plugin.version_matches && pluginSkillsInstalled;
+    const ok = checks.every((check) => check.name === "state_root_exists"
+        || check.name === "conveyor_on_path"
+        || check.name === "workerctl_on_path"
+        || check.name === "plugin_installed"
+        || check.name === "plugin_version_matches"
+        || check.name === "plugin_skills_installed"
+        || check.ok === true);
+    return {
+        ...jsonResult({
+            checks,
+            codex_home: plugin.paths.codex_home,
+            commands: {
+                codex: { ok: Boolean(codexPath), path: codexPath },
+                conveyor: { ok: Boolean(conveyorPath), path: conveyorPath },
+                tmux: { ok: Boolean(tmuxPath), path: tmuxPath },
+                workerctl: { ok: Boolean(workerctlPath), path: workerctlPath },
+            },
+            ok,
+            operator_ready: operatorReady,
+            package: {
+                name: "agent-conveyor",
+                root: packageRoot,
+                version: packageVersion,
+            },
+            platform: process.platform,
+            plugin,
+            project_root: packageRoot,
+            runtime: {
+                node: process.version,
+                state_root: root,
+                target_cwd: targetCwd,
+            },
+            workers: doctorWorkerSummaries(root),
+        }),
+        exitCode: ok ? 0 : 1,
+    };
 }
 function runDoctorSelfCommand(parsed, options) {
     if (parsed.task !== null) {
@@ -18966,6 +19073,7 @@ function telemetryEventsForRunSync(database, options) {
 }
 function appTaskDispatchSummarySync(database, options) {
     const taskDispatchEventTypes = [
+        "app_autopilot_automation_applied",
         "app_autopilot_started",
         "app_autopilot_stopped",
         "app_heartbeat",