@suwujs/king-ai 0.2.0

package/dist/src/host-control.js

@@ -0,0 +1,1279 @@
+import { collectDoctorResults, doctorExitCode, formatDoctorReport } from "./daemon.js";
+import { cronMatches } from "./cron.js";
+import { exportHostArtifacts, planHostExport } from "./host-export.js";
+import { formatHostFeedback, formatHostFeedbackSummary, listHostFeedback, recordHostFeedback, summarizeHostFeedback } from "./host-feedback.js";
+import { buildHostStatusSnapshot, formatHostStatusSnapshot } from "./host-api.js";
+import { buildHostAgenda, compactHostLedger, createHostCapsule, createHostTask, createHostWorkflowCard, formatHostAgenda, formatHostCapsules, formatHostLedgerCompact, formatHostTasks, formatHostWorkflowCards, listHostCapsules, listHostTasks, listHostWorkflowCards, updateHostCapsule, updateHostTask, updateHostWorkflowCard } from "./host-ledger.js";
+import { appendHostLoopEvent, formatHostLoopEvents, readHostLoopEvents, readHostLoopResults } from "./host-loop-events.js";
+import { formatHostRunHeartbeat, hostRunHeartbeatPathForOutputDir, readHostRunHeartbeat, writeHostRunHeartbeat } from "./host-run-heartbeat.js";
+import { formatHostRunMeta, hostRunMetaPathForOutputDir, readHostRunMeta, updateHostRunMeta } from "./host-run-meta.js";
+import { prepareHostRunLayout } from "./host-run-layout.js";
+import { executeNextHostRunRequest, formatHostRunExecuteResult } from "./host-run-executor.js";
+import { checkHostCommandPolicy, formatHostPolicyCheck } from "./host-policy.js";
+import { evaluateHostCommandPermission, resolveActorRole, resolveHumanApproval, resolveTeamSpec } from "./host-permission.js";
+import { normalizeReviewVerdict, planHandoff, selectOwnerRole } from "./team-routing.js";
+import { createHostLaunchPlan, toJsonSafeHostLaunchPlan } from "./host-run-spec.js";
+import { formatHostRunRequestSummary, formatHostRunRequests, getHostRunRequest, listHostRunRequests, submitHostRunRequest, updateHostRunRequest } from "./host-runs.js";
+import { appendHostTimelineEvent, formatHostTimeline, previewText, readHostTimeline, summarizeHostCommandJson } from "./host-timeline.js";
+import { readRunningState } from "./service.js";
+import { formatUsageExpenses, formatUsageSummary, listUsageExpenses, summarizeAgentUsage, tokenBudgetFromEnv, usagePricingFromEnv } from "./usage.js";
+import { buildUsageRuntimeData } from "./runtime-data.js";
+import { deleteRemoteDevice, findRemoteDevice, listRemoteDeviceSummaries, loadRemoteDevicesConfig, normalizeRemoteDevicesConfig, saveRemoteDevicesConfig, setDefaultRemoteDevice, summarizeRemoteDevice, upsertRemoteDevice } from "./remote-devices.js";
+import { formatRemoteDevices, formatRemoteResult, remoteFindLogs, remoteLogs, remotePg, remoteProbe, remoteProfile, remoteRedis, remoteRun } from "./remote-diagnostics.js";
+const COMMANDS = [
+    { name: "status", description: "Return the app-facing daemon status snapshot.", destructive: false },
+    { name: "usage", description: "Summarize local agent run and token usage.", destructive: false },
+    { name: "expenses", description: "List estimated local agent run expenses by agent.", destructive: false },
+    { name: "events", description: "Return recent daemon lifecycle events.", destructive: false },
+    { name: "timeline", description: "Return recent host command audit events.", destructive: false },
+    { name: "policy", description: "Check host command safety policy and confirmation requirements.", destructive: false },
+    { name: "doctor", description: "Probe local Claude/Codex engine availability.", destructive: false },
+    { name: "plan-run", description: "Normalize a host app run request into a reproducible run plan.", destructive: false },
+    { name: "preflight", description: "Check whether a host app run request is ready to launch.", destructive: false },
+    { name: "prepare-run-layout", description: "Materialize the local host run layout after explicit confirmation.", destructive: true },
+    { name: "submit-run", description: "Persist a pending host app run request for local execution.", destructive: false },
+    { name: "run-requests", description: "List pending host app run requests.", destructive: false },
+    { name: "run-request", description: "Return one host app run request by id.", destructive: false },
+    { name: "update-run", description: "Append a lifecycle status update for a host app run request.", destructive: false },
+    { name: "cancel-run", description: "Cancel a queued or active host app run request.", destructive: false },
+    { name: "execute-run", description: "Consume one pending host app run request with a safe local executor.", destructive: false },
+    { name: "task-create", description: "Append a local host task to the run ledger.", destructive: false },
+    { name: "task-list", description: "List local host tasks from the run ledger.", destructive: false },
+    { name: "task-update", description: "Append a local host task status or ownership update.", destructive: false },
+    { name: "agenda", description: "Build the dependency-aware host task agenda.", destructive: false },
+    { name: "capsule-create", description: "Append a repo work capsule to the run ledger.", destructive: false },
+    { name: "capsule-list", description: "List repo work capsules from the run ledger.", destructive: false },
+    { name: "capsule-update", description: "Append a repo work capsule update.", destructive: false },
+    { name: "workflow-create", description: "Append a first-class workflow object to the run ledger.", destructive: false },
+    { name: "workflow-list", description: "List first-class workflow objects from the run ledger.", destructive: false },
+    { name: "workflow-update", description: "Append a first-class workflow object update.", destructive: false },
+    { name: "initiative-create", description: "Append a long-running initiative workflow object.", destructive: false },
+    { name: "handoff-create", description: "Append a role handoff workflow object.", destructive: false },
+    { name: "review-create", description: "Append a review-request workflow object.", destructive: false },
+    { name: "decision-create", description: "Append a human or role decision workflow object.", destructive: false },
+    { name: "artifact-create", description: "Append an artifact workflow object.", destructive: false },
+    { name: "feedback-record", description: "Append run feedback and skill metric evidence.", destructive: false },
+    { name: "feedback-list", description: "List run feedback records.", destructive: false },
+    { name: "feedback-summary", description: "Summarize run feedback and skill metrics.", destructive: false },
+    { name: "cron-check", description: "Evaluate local cron schedules and emit matching run events.", destructive: false },
+    { name: "emit-run-event", description: "Append an app-facing event to a prepared host run output.", destructive: false },
+    { name: "watch-run", description: "Read King AI loop events from a prepared host run output.", destructive: false },
+    { name: "run-results", description: "Read King AI results.tsv rows from a prepared host run output.", destructive: false },
+    { name: "run-heartbeat", description: "Read a prepared or executing host run heartbeat file.", destructive: false },
+    { name: "run-meta", description: "Read prepared host run metadata from a run output.", destructive: false },
+    { name: "plan-export", description: "Preview host artifact and repo patch export outputs.", destructive: false },
+    { name: "export", description: "Write host artifact and repo patch exports to the output directory.", destructive: true },
+    { name: "compact-ledger", description: "Rewrite the append-only task/capsule/workflow ledgers into merged snapshots.", destructive: true },
+    { name: "remote-config-get", description: "Return the full remote test device JSON config.", destructive: false },
+    { name: "remote-config-save", description: "Replace the full remote test device JSON config.", destructive: false },
+    { name: "remote-list", description: "List configured remote test devices without secrets.", destructive: false },
+    { name: "remote-save-device", description: "Create or update a remote test device in the local config.", destructive: false },
+    { name: "remote-delete-device", description: "Delete a remote test device from the local config.", destructive: false },
+    { name: "remote-default-device", description: "Set the default remote test device.", destructive: false },
+    { name: "remote-probe", description: "Probe SSH connectivity and basic identity on a remote test device.", destructive: false },
+    { name: "remote-profile", description: "Collect a remote test device environment profile.", destructive: false },
+    { name: "remote-run", description: "Run a shell command on a remote test device.", destructive: false },
+    { name: "remote-logs", description: "Tail logs from a remote test device.", destructive: false },
+    { name: "remote-find-logs", description: "Search logs on a remote test device.", destructive: false },
+    { name: "remote-pg", description: "Run a PostgreSQL command on a remote test device.", destructive: false },
+    { name: "remote-redis", description: "Run a Redis command on a remote test device.", destructive: false }
+];
+export function listHostCommands() {
+    return COMMANDS.map((entry) => ({ ...entry }));
+}
+export function normalizeHostCommandName(raw) {
+    const value = raw.trim().toLowerCase();
+    return COMMANDS.some((entry) => entry.name === value) ? value : null;
+}
+function formatEvents(events) {
+    if (events.length === 0)
+        return "no recent daemon events";
+    return events.map((event) => `${event.at} ${event.kind}${event.detail ? ` ${event.detail}` : ""}`).join("\n");
+}
+export async function runHostCommand(request, deps = {}) {
+    const started = Date.now();
+    const actorRole = resolveActorRole(request);
+    let result;
+    try {
+        result = await executeHostCommand(request, deps);
+    }
+    catch (err) {
+        const command = normalizeHostCommandName(request.command) ?? request.command;
+        if (deps.recordTimeline) {
+            const message = err instanceof Error ? err.message : String(err);
+            await appendHostTimelineEvent({
+                at: (deps.now ?? (() => new Date()))().toISOString(),
+                type: "host.command",
+                command,
+                ok: false,
+                exitCode: 1,
+                destructive: listHostCommands().some((entry) => entry.name === command && entry.destructive),
+                durationMs: Date.now() - started,
+                actorRole,
+                textPreview: previewText(message),
+                error: message
+            }, deps.timelinePath);
+        }
+        throw err;
+    }
+    if (deps.recordTimeline) {
+        await appendHostTimelineEvent({
+            at: (deps.now ?? (() => new Date()))().toISOString(),
+            type: "host.command",
+            command: result.command,
+            ok: result.ok,
+            exitCode: result.exitCode,
+            destructive: listHostCommands().some((entry) => entry.name === result.command && entry.destructive),
+            durationMs: Date.now() - started,
+            actorRole,
+            textPreview: previewText(result.text),
+            jsonSummary: summarizeHostCommandJson(result.command, result.json),
+            error: result.error
+        }, deps.timelinePath);
+    }
+    return result;
+}
+async function executeHostCommand(request, deps = {}) {
+    const command = normalizeHostCommandName(request.command);
+    if (!command) {
+        return {
+            ok: false,
+            command: request.command,
+            exitCode: 64,
+            text: `unsupported host command: ${request.command}`,
+            error: "unsupported host command"
+        };
+    }
+    if (command === "policy") {
+        const input = normalizePolicyInput(request.input);
+        const target = normalizeHostCommandName(input.command);
+        if (!target) {
+            return {
+                ok: false,
+                command,
+                exitCode: 64,
+                text: `unsupported host command: ${input.command}`,
+                error: "unsupported host command"
+            };
+        }
+        const policy = checkHostCommandPolicy(target, isDestructiveHostCommand(target), input);
+        return {
+            ok: policy.decision === "allow",
+            command,
+            exitCode: policy.decision === "allow" ? 0 : 1,
+            text: formatHostPolicyCheck(policy),
+            json: policy
+        };
+    }
+    const policy = checkHostCommandPolicy(command, isDestructiveHostCommand(command), request.input);
+    if (policy.decision !== "allow") {
+        return {
+            ok: false,
+            command,
+            exitCode: 75,
+            text: formatHostPolicyCheck(policy),
+            json: policy,
+            error: "host command confirmation required"
+        };
+    }
+    const permission = deps.enforcePermission === false
+        ? { enforced: false, action: null }
+        : evaluateHostCommandPermission(command, request.input, request, { teamSpec: deps.teamSpec });
+    if (permission.enforced && permission.decision === "deny") {
+        return {
+            ok: false,
+            command,
+            exitCode: 77,
+            text: `role governance blocked ${permission.role} from ${permission.action} via ${command}`,
+            json: { permission },
+            error: "host command blocked by role governance"
+        };
+    }
+    if (permission.enforced && permission.decision === "human-decision") {
+        const approval = resolveHumanApproval(request.input, permission.role);
+        if (!approval.approved) {
+            const decision = await createHostWorkflowCard({
+                ...ledgerPathInput(request.input),
+                kind: "decision",
+                title: `Human decision marker required: ${command} (${permission.action})`,
+                ownerRole: permission.role,
+                decisionBy: permission.rule?.requireReviewBy ?? "human",
+                detail: `Role ${permission.role} requested ${permission.action} via ${command}; ${approval.reason ?? "human decision marker required"}. Retry with humanApproved=true and approvedBy=<approver different from ${permission.role}>. Role governance is opt-in for trusted local automation; omit actorRole/KING_AI_TEAM_ROLE when this command should run unattended.`,
+                metadata: { blockedCommand: command, action: permission.action, requestedRole: permission.role, reason: approval.reason }
+            }, deps.now);
+            return {
+                ok: false,
+                command,
+                exitCode: 75,
+                text: `human decision marker required before ${command}; created decision ${decision.id} (${approval.reason ?? "approval required"})`,
+                json: { permission, decision },
+                error: "host command blocked by human-decision governance"
+            };
+        }
+    }
+    if (command === "timeline") {
+        const events = await readHostTimeline({
+            path: deps.timelinePath,
+            limit: normalizeTimelineInput(request.input).limit
+        });
+        return {
+            ok: true,
+            command,
+            exitCode: 0,
+            text: formatHostTimeline(events),
+            json: { events }
+        };
+    }
+    if (command.startsWith("remote-")) {
+        const config = await loadRemoteDevicesConfig();
+        if (command === "remote-config-get") {
+            const input = normalizeRemoteConfigGetInput(request.input);
+            const safeConfig = input.revealSecrets
+                ? config
+                : { ...config, devices: listRemoteDeviceSummaries(config) };
+            return {
+                ok: true,
+                command,
+                exitCode: 0,
+                text: input.revealSecrets ? "remote devices config loaded" : formatRemoteDevices(config),
+                json: { config: safeConfig, defaultDevice: config.defaultDevice, devices: listRemoteDeviceSummaries(config) }
+            };
+        }
+        if (command === "remote-config-save") {
+            const next = await saveRemoteDevicesConfig(normalizeRemoteDevicesConfig(request.input));
+            return {
+                ok: true,
+                command,
+                exitCode: 0,
+                text: `remote devices config saved: ${next.devices.length} device${next.devices.length === 1 ? "" : "s"}`,
+                json: { config: next, defaultDevice: next.defaultDevice, devices: listRemoteDeviceSummaries(next) }
+            };
+        }
+        if (command === "remote-list") {
+            return {
+                ok: true,
+                command,
+                exitCode: 0,
+                text: formatRemoteDevices(config),
+                json: { defaultDevice: config.defaultDevice, devices: listRemoteDeviceSummaries(config) }
+            };
+        }
+        if (command === "remote-save-device") {
+            const input = normalizeRemoteSaveDeviceInput(request.input);
+            const next = await saveRemoteDevicesConfig(upsertRemoteDevice(config, input));
+            const device = findRemoteDevice(next, input.id);
+            return {
+                ok: true,
+                command,
+                exitCode: 0,
+                text: `remote device saved: ${device.id}`,
+                json: { defaultDevice: next.defaultDevice, device: summarizeRemoteDevice(device), devices: listRemoteDeviceSummaries(next) }
+            };
+        }
+        if (command === "remote-delete-device") {
+            const input = normalizeRemoteDeviceIdInput(request.input);
+            const next = await saveRemoteDevicesConfig(deleteRemoteDevice(config, input.id));
+            return {
+                ok: true,
+                command,
+                exitCode: 0,
+                text: `remote device deleted: ${input.id}`,
+                json: { defaultDevice: next.defaultDevice, devices: listRemoteDeviceSummaries(next) }
+            };
+        }
+        if (command === "remote-default-device") {
+            const input = normalizeRemoteDeviceIdInput(request.input);
+            const next = await saveRemoteDevicesConfig(setDefaultRemoteDevice(config, input.id));
+            return {
+                ok: true,
+                command,
+                exitCode: 0,
+                text: `default remote device: ${input.id}`,
+                json: { defaultDevice: next.defaultDevice, devices: listRemoteDeviceSummaries(next) }
+            };
+        }
+        const remoteDeps = { config };
+        const result = command === "remote-probe" ? await remoteProbe(request.input, remoteDeps)
+            : command === "remote-profile" ? await remoteProfile(request.input, remoteDeps)
+                : command === "remote-run" ? await remoteRun(request.input, remoteDeps)
+                    : command === "remote-logs" ? await remoteLogs(request.input, remoteDeps)
+                        : command === "remote-find-logs" ? await remoteFindLogs(request.input, remoteDeps)
+                            : command === "remote-pg" ? await remotePg(request.input, remoteDeps)
+                                : await remoteRedis(request.input, remoteDeps);
+        return {
+            ok: result.ok,
+            command,
+            exitCode: result.exitCode ?? (result.ok ? 0 : 1),
+            text: formatRemoteResult(result),
+            json: result,
+            error: result.error
+        };
+    }
+    const readState = deps.readState ?? readRunningState;
+    const tokenBudget = deps.tokenBudget ?? tokenBudgetFromEnv;
+    const usagePricing = deps.usagePricing ?? usagePricingFromEnv;
+    if (command === "plan-run" || command === "preflight") {
+        const plan = createHostLaunchPlan(normalizeRunInput(request.input), process.env, normalizeAvailableEngines(deps.availableEngines?.()));
+        return {
+            ok: plan.ready,
+            command,
+            exitCode: plan.ready ? 0 : 1,
+            text: plan.launchSummary,
+            json: toJsonSafeHostLaunchPlan(plan)
+        };
+    }
+    if (command === "prepare-run-layout") {
+        try {
+            const result = await prepareHostRunLayout(normalizeRunLayoutInput(request.input), {
+                env: process.env,
+                availableEngines: normalizeAvailableEngines(deps.availableEngines?.())
+            });
+            return {
+                ok: result.launchPlan.ready,
+                command,
+                exitCode: result.launchPlan.ready ? 0 : 1,
+                text: result.summary,
+                json: result
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                ok: false,
+                command,
+                exitCode: 1,
+                text: message,
+                error: message
+            };
+        }
+    }
+    if (command === "submit-run") {
+        const result = await submitHostRunRequest(withExecutorActorRole(normalizeSubmitRunInput(request.input), permission.role), {
+            path: deps.runsPath,
+            availableEngines: normalizeAvailableEngines(deps.availableEngines?.()),
+            now: deps.now
+        });
+        return {
+            ok: result.launchPlan.ready,
+            command,
+            exitCode: result.launchPlan.ready ? 0 : 1,
+            text: result.summary,
+            json: result
+        };
+    }
+    if (command === "run-requests") {
+        const requests = await listHostRunRequests(normalizeRunRequestsInput(request.input), deps.runsPath);
+        return {
+            ok: true,
+            command,
+            exitCode: 0,
+            text: formatHostRunRequests(requests),
+            json: { requests }
+        };
+    }
+    if (command === "run-request") {
+        const runRequest = await getHostRunRequest(normalizeRunRequestInput(request.input), deps.runsPath);
+        if (!runRequest) {
+            return {
+                ok: false,
+                command,
+                exitCode: 66,
+                text: "host run request not found",
+                error: "host run request not found"
+            };
+        }
+        return {
+            ok: true,
+            command,
+            exitCode: 0,
+            text: formatHostRunRequestSummary(runRequest),
+            json: { request: runRequest }
+        };
+    }
+    if (command === "update-run") {
+        const result = await updateHostRunRequest(normalizeUpdateRunInput(request.input), {
+            path: deps.runsPath,
+            now: deps.now
+        });
+        await syncRunRequestHeartbeat(result.request, deps.now);
+        await syncRunRequestMeta(result.request, deps.now);
+        await syncRunRequestLoopEvent(result.request, deps.now);
+        return {
+            ok: true,
+            command,
+            exitCode: 0,
+            text: result.summary,
+            json: result
+        };
+    }
+    if (command === "cancel-run") {
+        const result = await updateHostRunRequest(normalizeCancelRunInput(request.input), {
+            path: deps.runsPath,
+            now: deps.now
+        });
+        await syncRunRequestHeartbeat(result.request, deps.now);
+        await syncRunRequestMeta(result.request, deps.now);
+        await syncRunRequestLoopEvent(result.request, deps.now);
+        return {
+            ok: true,
+            command,
+            exitCode: 0,
+            text: result.summary,
+            json: result
+        };
+    }
+    if (command === "execute-run") {
+        const result = await executeNextHostRunRequest(normalizeExecuteRunInput(request.input), deps);
+        return {
+            ok: result.request ? result.request.status === "completed" : true,
+            command,
+            exitCode: result.request && result.request.status !== "completed" ? 1 : 0,
+            text: formatHostRunExecuteResult(result),
+            json: result
+        };
+    }
+    if (command === "task-create") {
+        const task = await createHostTask(normalizeTaskCreateInput(request.input), deps.now);
+        return {
+            ok: true,
+            command,
+            exitCode: 0,
+            text: formatHostTasks([task]),
+            json: { task }
+        };
+    }
+    if (command === "task-list") {
+        const tasks = await listHostTasks(normalizeTaskListInput(request.input));
+        return {
+            ok: true,
+            command,
+            exitCode: 0,
+            text: formatHostTasks(tasks),
+            json: { tasks }
+        };
+    }
+    if (command === "task-update") {
+        const task = await updateHostTask(normalizeTaskUpdateInput(request.input), deps.now);
+        return {
+            ok: true,
+            command,
+            exitCode: 0,
+            text: formatHostTasks([task]),
+            json: { task }
+        };
+    }
+    if (command === "agenda") {
+        const agenda = await buildHostAgenda(normalizeAgendaInput(request.input));
+        return {
+            ok: true,
+            command,
+            exitCode: 0,
+            text: formatHostAgenda(agenda),
+            json: agenda
+        };
+    }
+    if (command === "capsule-create") {
+        const capsule = await createHostCapsule(normalizeCapsuleCreateInput(request.input), deps.now);
+        return {
+            ok: true,
+            command,
+            exitCode: 0,
+            text: formatHostCapsules([capsule]),
+            json: { capsule }
+        };
+    }
+    if (command === "capsule-list") {
+        const capsules = await listHostCapsules(normalizeCapsuleListInput(request.input));
+        return {
+            ok: true,
+            command,
+            exitCode: 0,
+            text: formatHostCapsules(capsules),
+            json: { capsules }
+        };
+    }
+    if (command === "capsule-update") {
+        const capsule = await updateHostCapsule(normalizeCapsuleUpdateInput(request.input), deps.now);
+        return {
+            ok: true,
+            command,
+            exitCode: 0,
+            text: formatHostCapsules([capsule]),
+            json: { capsule }
+        };
+    }
+    if (command === "workflow-create") {
+        const card = await createHostWorkflowCard(applyCapabilityOwner(normalizeWorkflowCreateInput(request.input), deps), deps.now);
+        return {
+            ok: true,
+            command,
+            exitCode: 0,
+            text: formatHostWorkflowCards([card]),
+            json: { card }
+        };
+    }
+    if (command === "workflow-list") {
+        const cards = await listHostWorkflowCards(normalizeWorkflowListInput(request.input));
+        return {
+            ok: true,
+            command,
+            exitCode: 0,
+            text: formatHostWorkflowCards(cards),
+            json: { cards }
+        };
+    }
+    if (command === "workflow-update") {
+        const card = await updateHostWorkflowCard(normalizeWorkflowUpdateInput(request.input), deps.now);
+        const handoffs = await runAutoHandoff(card, request.input, deps);
+        return {
+            ok: true,
+            command,
+            exitCode: 0,
+            text: handoffs.length ? `${formatHostWorkflowCards([card])}\n${formatHandoffActions(handoffs)}` : formatHostWorkflowCards([card]),
+            json: handoffs.length ? { card, handoffs } : { card }
+        };
+    }
+    if (command === "initiative-create" || command === "handoff-create" || command === "review-create" || command === "decision-create" || command === "artifact-create") {
+        const card = await createHostWorkflowCard(normalizeKindedWorkflowCreateInput(command, request.input), deps.now);
+        return {
+            ok: true,
+            command,
+            exitCode: 0,
+            text: formatHostWorkflowCards([card]),
+            json: { card }
+        };
+    }
+    if (command === "feedback-record") {
+        const feedback = await recordHostFeedback(normalizeFeedbackRecordInput(request.input), deps.now);
+        return {
+            ok: true,
+            command,
+            exitCode: 0,
+            text: formatHostFeedback([feedback]),
+            json: { feedback }
+        };
+    }
+    if (command === "feedback-list") {
+        const feedback = await listHostFeedback(normalizeFeedbackListInput(request.input));
+        return {
+            ok: true,
+            command,
+            exitCode: 0,
+            text: formatHostFeedback(feedback),
+            json: { feedback }
+        };
+    }
+    if (command === "feedback-summary") {
+        const summary = await summarizeHostFeedback(normalizeFeedbackListInput(request.input));
+        return {
+            ok: true,
+            command,
+            exitCode: 0,
+            text: formatHostFeedbackSummary(summary),
+            json: summary
+        };
+    }
+    if (command === "cron-check") {
+        const result = await runHostCronCheck(normalizeCronCheckInput(request.input), deps.now);
+        return {
+            ok: true,
+            command,
+            exitCode: 0,
+            text: formatHostCronCheck(result),
+            json: result
+        };
+    }
+    if (command === "emit-run-event") {
+        const result = await emitHostRunEvent(await normalizeEmitRunEventInput(request.input, deps.runsPath), deps.now);
+        return {
+            ok: true,
+            command,
+            exitCode: 0,
+            text: `host run event emitted: ${result.file}\n${formatEmittedHostRunEvent(result.event)}`,
+            json: result
+        };
+    }
+    if (command === "watch-run") {
+        const result = await readHostLoopEvents(await normalizeLoopEventsInput(request.input, deps.runsPath));
+        return {
+            ok: true,
+            command,
+            exitCode: 0,
+            text: formatHostLoopEvents(result),
+            json: result
+        };
+    }
+    if (command === "run-results") {
+        const result = await readHostLoopResults(await normalizeLoopResultsInput(request.input, deps.runsPath));
+        return {
+            ok: true,
+            command,
+            exitCode: 0,
+            text: result.text ?? "",
+            json: result
+        };
+    }
+    if (command === "run-heartbeat") {
+        const result = await readHostRunHeartbeat(await normalizeRunHeartbeatInput(request.input, deps.runsPath));
+        return {
+            ok: result.exists && !!result.heartbeat,
+            command,
+            exitCode: result.exists && result.heartbeat ? 0 : 66,
+            text: formatHostRunHeartbeat(result),
+            json: result,
+            error: result.exists && result.heartbeat ? undefined : "host run heartbeat not found"
+        };
+    }
+    if (command === "run-meta") {
+        const result = await readHostRunMeta(await normalizeRunMetaInput(request.input, deps.runsPath));
+        return {
+            ok: result.exists && !!result.meta,
+            command,
+            exitCode: result.exists && result.meta ? 0 : 66,
+            text: formatHostRunMeta(result),
+            json: result,
+            error: result.exists && result.meta ? undefined : "host run meta not found"
+        };
+    }
+    if (command === "plan-export") {
+        const plan = await planHostExport(normalizeExportInput(request.input));
+        return {
+            ok: true,
+            command,
+            exitCode: 0,
+            text: plan.summary,
+            json: plan
+        };
+    }
+    if (command === "export") {
+        const result = await exportHostArtifacts(normalizeExportInput(request.input));
+        return {
+            ok: true,
+            command,
+            exitCode: 0,
+            text: `${result.summary}\nwritten files:\n${result.writtenFiles.map((file) => `  - ${file}`).join("\n") || "  (none)"}`,
+            json: result
+        };
+    }
+    if (command === "compact-ledger") {
+        const result = await compactHostLedger(normalizeCompactLedgerInput(request.input));
+        return {
+            ok: true,
+            command,
+            exitCode: 0,
+            text: formatHostLedgerCompact(result),
+            json: result
+        };
+    }
+    if (command === "doctor") {
+        const results = await (deps.collectDoctorResults ?? collectDoctorResults)();
+        const exitCode = doctorExitCode(results);
+        return {
+            ok: exitCode === 0,
+            command,
+            exitCode,
+            text: formatDoctorReport(results),
+            json: { results, exitCode }
+        };
+    }
+    const state = await readState();
+    const snapshot = buildHostStatusSnapshot(state, tokenBudget(), usagePricing());
+    if (command === "status") {
+        return {
+            ok: snapshot.ok,
+            command,
+            exitCode: snapshot.ok ? 0 : 1,
+            text: formatHostStatusSnapshot(snapshot),
+            json: snapshot
+        };
+    }
+    if (command === "usage") {
+        const summary = summarizeAgentUsage(state?.agents ?? [], tokenBudget(), usagePricing());
+        return {
+            ok: true,
+            command,
+            exitCode: 0,
+            text: formatUsageSummary(summary),
+            json: {
+                ...summary,
+                runtimeData: buildUsageRuntimeData(state, { budget: tokenBudget(), pricingRules: usagePricing() })
+            }
+        };
+    }
+    if (command === "expenses") {
+        const summary = summarizeAgentUsage(state?.agents ?? [], tokenBudget(), usagePricing());
+        const expenses = listUsageExpenses(summary);
+        return {
+            ok: true,
+            command,
+            exitCode: 0,
+            text: formatUsageExpenses(expenses),
+            json: {
+                expenses,
+                usage: summary
+            }
+        };
+    }
+    return {
+        ok: true,
+        command,
+        exitCode: 0,
+        text: formatEvents(snapshot.events),
+        json: { events: snapshot.events }
+    };
+}
+function isDestructiveHostCommand(command) {
+    return COMMANDS.some((entry) => entry.name === command && entry.destructive);
+}
+function ledgerPathInput(value) {
+    if (!value || typeof value !== "object")
+        return {};
+    const record = value;
+    return {
+        outputDir: typeof record.outputDir === "string" ? record.outputDir : undefined,
+        workflowFile: typeof record.workflowFile === "string" ? record.workflowFile : undefined
+    };
+}
+function normalizePolicyInput(value) {
+    if (!value || typeof value !== "object")
+        throw new Error("policy input must include a command");
+    const input = value;
+    if (typeof input.command !== "string" || !input.command.trim())
+        throw new Error("policy input must include a command");
+    return {
+        command: input.command,
+        confirmed: input.confirmed,
+        confirmation: input.confirmation
+    };
+}
+function normalizeTimelineInput(value) {
+    if (!value)
+        return {};
+    if (typeof value !== "object")
+        throw new Error("timeline input must be an object");
+    const raw = value.limit;
+    if (raw === undefined)
+        return {};
+    const limit = typeof raw === "number" ? raw : Number.parseInt(String(raw), 10);
+    if (!Number.isFinite(limit) || limit < 1)
+        throw new Error("timeline limit must be a positive integer");
+    return { limit };
+}
+function normalizeRemoteSaveDeviceInput(value) {
+    if (!value || typeof value !== "object")
+        throw new Error("remote-save-device input must include a device object");
+    const input = value;
+    if (typeof input.id !== "string" || !input.id.trim())
+        throw new Error("remote device id is required");
+    return { ...input, id: input.id.trim() };
+}
+function normalizeRemoteConfigGetInput(value) {
+    if (!value)
+        return { revealSecrets: false };
+    if (typeof value !== "object")
+        throw new Error("remote-config-get input must be an object");
+    return { revealSecrets: value.revealSecrets === true };
+}
+function normalizeRemoteDeviceIdInput(value) {
+    if (!value || typeof value !== "object")
+        throw new Error("remote device input must include an id");
+    const id = value.id;
+    if (typeof id !== "string" || !id.trim())
+        throw new Error("remote device id is required");
+    return { id: id.trim() };
+}
+function normalizeRunInput(value) {
+    if (value && typeof value === "object")
+        return value;
+    if (typeof value === "string")
+        return { goal: value };
+    throw new Error("plan-run input must include a goal");
+}
+function normalizeSubmitRunInput(value) {
+    if (value && typeof value === "object")
+        return value;
+    if (typeof value === "string")
+        return { goal: value };
+    throw new Error("submit-run input must include a goal");
+}
+function withExecutorActorRole(input, actorRole) {
+    if (!input.executor || input.executor.actorRole || !actorRole)
+        return input;
+    return {
+        ...input,
+        executor: {
+            ...input.executor,
+            actorRole
+        }
+    };
+}
+function normalizeRunLayoutInput(value) {
+    if (value && typeof value === "object")
+        return value;
+    if (typeof value === "string")
+        return { goal: value };
+    throw new Error("prepare-run-layout input must include a goal");
+}
+function normalizeRunRequestsInput(value) {
+    if (!value)
+        return {};
+    if (typeof value !== "object")
+        throw new Error("run-requests input must be an object");
+    return value;
+}
+function normalizeRunRequestInput(value) {
+    if (!value || typeof value !== "object")
+        throw new Error("run-request input must include an id");
+    return value;
+}
+function normalizeUpdateRunInput(value) {
+    if (!value || typeof value !== "object")
+        throw new Error("update-run input must include id and status");
+    return value;
+}
+function normalizeCancelRunInput(value) {
+    if (!value || typeof value !== "object")
+        throw new Error("cancel-run input must include an id");
+    const input = value;
+    return {
+        id: input.id,
+        status: "cancelled",
+        detail: input.detail
+    };
+}
+function normalizeExecuteRunInput(value) {
+    if (!value)
+        return {};
+    if (typeof value !== "object")
+        throw new Error("execute-run input must be an object");
+    return value;
+}
+function normalizeTaskCreateInput(value) {
+    if (!value || typeof value !== "object")
+        throw new Error("task-create input must include a title");
+    return value;
+}
+function normalizeTaskListInput(value) {
+    if (!value)
+        return {};
+    if (typeof value !== "object")
+        throw new Error("task-list input must be an object");
+    return value;
+}
+function normalizeTaskUpdateInput(value) {
+    if (!value || typeof value !== "object")
+        throw new Error("task-update input must include an id");
+    return value;
+}
+function normalizeAgendaInput(value) {
+    if (!value)
+        return {};
+    if (typeof value !== "object")
+        throw new Error("agenda input must be an object");
+    return value;
+}
+function normalizeCapsuleCreateInput(value) {
+    if (!value || typeof value !== "object")
+        throw new Error("capsule-create input must include a goal");
+    return value;
+}
+function normalizeCapsuleListInput(value) {
+    if (!value)
+        return {};
+    if (typeof value !== "object")
+        throw new Error("capsule-list input must be an object");
+    return value;
+}
+function normalizeCapsuleUpdateInput(value) {
+    if (!value || typeof value !== "object")
+        throw new Error("capsule-update input must include an id");
+    return value;
+}
+function normalizeWorkflowCreateInput(value) {
+    if (!value || typeof value !== "object")
+        throw new Error("workflow-create input must include kind and title");
+    return value;
+}
+function normalizeWorkflowListInput(value) {
+    if (!value)
+        return {};
+    if (typeof value !== "object")
+        throw new Error("workflow-list input must be an object");
+    return value;
+}
+function normalizeWorkflowUpdateInput(value) {
+    if (!value || typeof value !== "object")
+        throw new Error("workflow-update input must include an id");
+    return value;
+}
+function normalizeCompactLedgerInput(value) {
+    if (!value)
+        return {};
+    if (typeof value !== "object")
+        throw new Error("compact-ledger input must be an object");
+    return value;
+}
+/**
+ * Capability-first owner selection: when a workflow card is created without an explicit ownerRole but
+ * carries `requiredCapabilities`, route it to the best-matching team role per the routing policy.
+ */
+function applyCapabilityOwner(input, deps) {
+    if (cleanInputString(input.ownerRole))
+        return input;
+    const capabilities = input.requiredCapabilities;
+    if (!Array.isArray(capabilities))
+        return input;
+    const required = capabilities.filter((entry) => typeof entry === "string");
+    if (required.length === 0)
+        return input;
+    const owner = selectOwnerRole(resolveTeamSpec({ teamSpec: deps.teamSpec }), required);
+    return owner ? { ...input, ownerRole: owner } : input;
+}
+/**
+ * Execute the team routing policy when a workflow card reaches `done`: materialize the follow-up
+ * review/decision/handoff cards the policy requires. Opt out per call with `{ handoff: false }` or per
+ * runner with `deps.autoHandoff === false`.
+ */
+async function runAutoHandoff(card, rawInput, deps) {
+    if (deps.autoHandoff === false || handoffDisabled(rawInput) || card.status !== "done")
+        return [];
+    const source = card.sourceId ? await findWorkflowCard(card.sourceId, rawInput) : null;
+    const actions = planHandoff({
+        ...card,
+        sourceOwnerRole: source?.ownerRole
+    }, resolveTeamSpec({ teamSpec: deps.teamSpec }));
+    if (actions.length === 0)
+        return [];
+    const paths = ledgerPathInput(rawInput);
+    const existing = await listHostWorkflowCards(paths);
+    const created = [];
+    for (const action of actions) {
+        const reason = autoHandoffReason(action, card);
+        if (existing.some((entry) => entry.sourceId === card.id && entry.metadata?.autoHandoff === true && entry.metadata?.reason === reason))
+            continue;
+        const next = await createHostWorkflowCard({
+            ...paths,
+            kind: action.card.kind,
+            title: action.card.title,
+            status: action.card.status,
+            ownerRole: action.card.ownerRole,
+            reviewerRole: action.card.reviewerRole,
+            targetRole: action.card.targetRole,
+            dependsOn: action.card.dependsOn,
+            sourceId: action.card.sourceId,
+            decisionBy: action.card.decisionBy,
+            detail: action.card.detail,
+            handoffPolicy: action.card.handoffPolicy,
+            metadata: { autoHandoff: true, reason, sourceCard: card.id, reviewedCard: card.kind === "review" ? card.sourceId : undefined }
+        }, deps.now);
+        created.push({ reason: action.reason, card: next });
+    }
+    return created;
+}
+function handoffDisabled(input) {
+    return Boolean(input && typeof input === "object" && input.handoff === false);
+}
+async function findWorkflowCard(id, rawInput) {
+    return (await listHostWorkflowCards(ledgerPathInput(rawInput))).find((card) => card.id === id) ?? null;
+}
+function autoHandoffReason(action, sourceCard) {
+    return sourceCard.kind === "review" && normalizeReviewVerdict(sourceCard.result) === "changes_requested"
+        ? "changes-requested"
+        : action.reason;
+}
+function formatHandoffActions(handoffs) {
+    return handoffs
+        .map(({ reason, card }) => `auto-handoff (${reason}) -> ${card.id} ${card.kind} ${card.status}${card.ownerRole ? ` ownerRole=${card.ownerRole}` : ""}: ${card.title}`)
+        .join("\n");
+}
+function normalizeKindedWorkflowCreateInput(command, value) {
+    if (!value || typeof value !== "object")
+        throw new Error(`${command} input must include a title`);
+    const kind = command.replace(/-create$/, "");
+    if (kind !== "initiative" && kind !== "handoff" && kind !== "review" && kind !== "decision" && kind !== "artifact") {
+        throw new Error(`unsupported workflow create command: ${command}`);
+    }
+    return {
+        ...value,
+        kind,
+        status: kind === "decision" ? (value.status ?? "waiting_human") : value.status
+    };
+}
+function normalizeFeedbackRecordInput(value) {
+    if (!value || typeof value !== "object")
+        throw new Error("feedback-record input must be an object");
+    return value;
+}
+function normalizeFeedbackListInput(value) {
+    if (!value)
+        return {};
+    if (typeof value !== "object")
+        throw new Error("feedback input must be an object");
+    return value;
+}
+function normalizeCronCheckInput(value) {
+    if (!value || typeof value !== "object")
+        throw new Error("cron-check input must include schedules");
+    const input = value;
+    if (!Array.isArray(input.schedules))
+        throw new Error("cron-check schedules must be an array");
+    return {
+        outputDir: cleanInputString(input.outputDir),
+        file: cleanInputString(input.file),
+        runId: cleanInputString(input.runId),
+        now: cleanInputString(input.now),
+        schedules: input.schedules.map((entry) => {
+            if (!entry || typeof entry !== "object")
+                throw new Error("cron-check schedule entries must be objects");
+            const schedule = entry;
+            const cron = cleanInputString(schedule.cron);
+            if (!cron)
+                throw new Error("cron-check schedule cron is required");
+            return {
+                id: cleanInputString(schedule.id),
+                cron,
+                type: cleanInputString(schedule.type),
+                agent: cleanInputString(schedule.agent),
+                message: cleanInputString(schedule.message),
+                payload: schedule.payload
+            };
+        })
+    };
+}
+async function runHostCronCheck(input, now) {
+    if (!input.file && !input.outputDir)
+        throw new Error("cron-check requires a file or outputDir");
+    const date = input.now ? new Date(input.now) : (now ?? (() => new Date()))();
+    if (Number.isNaN(date.getTime()))
+        throw new Error("cron-check now must be a valid date");
+    const emitted = [];
+    for (const schedule of input.schedules) {
+        if (!cronMatches(schedule.cron, date))
+            continue;
+        const event = dropUndefined({
+            type: schedule.type ?? "cron.tick",
+            runId: input.runId,
+            timestamp: date.toISOString(),
+            agent: schedule.agent,
+            message: schedule.message,
+            payload: schedule.payload,
+            source: "cron-check"
+        });
+        const file = await appendHostLoopEvent({
+            file: input.file,
+            outputDir: input.outputDir,
+            event
+        });
+        emitted.push({ id: schedule.id, type: event.type ?? "cron.tick", file, event });
+    }
+    return {
+        now: date.toISOString(),
+        checked: input.schedules.length,
+        matched: emitted.length,
+        emitted
+    };
+}
+function formatHostCronCheck(result) {
+    const lines = [`cron-check: checked=${result.checked} matched=${result.matched} now=${result.now}`];
+    for (const entry of result.emitted)
+        lines.push(`  - ${entry.id ?? entry.type}: ${entry.file}`);
+    return lines.join("\n");
+}
+async function normalizeLoopEventsInput(value, runsPath) {
+    if (!value)
+        return {};
+    if (typeof value !== "object")
+        throw new Error("watch-run input must be an object");
+    const input = value;
+    const id = typeof input.id === "string" && input.id.trim() ? input.id.trim() : undefined;
+    if (!input.file && !input.outputDir && id) {
+        const request = await getHostRunRequest({ id }, runsPath);
+        const outputDir = request?.spec.options?.outputDir;
+        return {
+            ...input,
+            outputDir,
+            runId: input.runId ?? id
+        };
+    }
+    return input;
+}
+async function normalizeEmitRunEventInput(value, runsPath) {
+    if (!value || typeof value !== "object")
+        throw new Error("emit-run-event input must include an event object or type");
+    const input = value;
+    const id = typeof input.id === "string" && input.id.trim() ? input.id.trim() : undefined;
+    let outputDir = cleanInputString(input.outputDir);
+    if (!input.file && !outputDir && id) {
+        const request = await getHostRunRequest({ id }, runsPath);
+        outputDir = request?.spec.options?.outputDir;
+    }
+    const eventInput = input.event && typeof input.event === "object" ? input.event : {};
+    const type = cleanInputString(eventInput.type) ?? cleanInputString(input.type);
+    if (!type)
+        throw new Error("emit-run-event type is required");
+    return {
+        ...input,
+        id,
+        outputDir,
+        event: {
+            ...eventInput,
+            type,
+            runId: cleanInputString(eventInput.runId) ?? id,
+            loop: numberInput(eventInput.loop) ?? numberInput(input.loop),
+            agent: cleanInputString(eventInput.agent) ?? cleanInputString(input.agent),
+            classification: cleanInputString(eventInput.classification) ?? cleanInputString(input.classification),
+            detail: cleanInputString(eventInput.detail) ?? cleanInputString(input.detail),
+            message: cleanInputString(eventInput.message) ?? cleanInputString(input.message),
+            payload: eventInput.payload ?? input.payload
+        }
+    };
+}
+async function emitHostRunEvent(input, now) {
+    if (!input.file && !input.outputDir)
+        throw new Error("emit-run-event requires a file, outputDir, or run id with outputDir");
+    const event = dropUndefined({
+        ...input.event,
+        runId: typeof input.event.runId === "string" && input.event.runId.trim() ? input.event.runId.trim() : input.id,
+        timestamp: typeof input.event.timestamp === "string" && input.event.timestamp.trim() ? input.event.timestamp.trim() : (now ?? (() => new Date()))().toISOString(),
+        source: typeof input.event.source === "string" && input.event.source.trim() ? input.event.source.trim() : "host-app"
+    });
+    const file = await appendHostLoopEvent({
+        file: input.file,
+        outputDir: input.outputDir,
+        event
+    });
+    return { file, event };
+}
+function formatEmittedHostRunEvent(event) {
+    return `${event.timestamp ?? "no-time"} ${event.type ?? "unknown"} run=${event.runId ?? "?"}`;
+}
+async function normalizeLoopResultsInput(value, runsPath) {
+    if (!value)
+        return {};
+    if (typeof value !== "object")
+        throw new Error("run-results input must be an object");
+    const input = value;
+    const id = typeof input.id === "string" && input.id.trim() ? input.id.trim() : undefined;
+    if (!input.file && !input.outputDir && !input.resultsFile && id) {
+        const request = await getHostRunRequest({ id }, runsPath);
+        const outputDir = request?.spec.options?.outputDir;
+        return {
+            ...input,
+            outputDir
+        };
+    }
+    return input;
+}
+async function normalizeRunHeartbeatInput(value, runsPath) {
+    if (!value)
+        return {};
+    if (typeof value !== "object")
+        throw new Error("run-heartbeat input must be an object");
+    const input = value;
+    const id = typeof input.id === "string" && input.id.trim() ? input.id.trim() : undefined;
+    if (!input.file && !input.outputDir && id) {
+        const request = await getHostRunRequest({ id }, runsPath);
+        const outputDir = request?.spec.options?.outputDir;
+        return {
+            ...input,
+            outputDir
+        };
+    }
+    return input;
+}
+async function normalizeRunMetaInput(value, runsPath) {
+    if (!value)
+        return {};
+    if (typeof value !== "object")
+        throw new Error("run-meta input must be an object");
+    const input = value;
+    const id = typeof input.id === "string" && input.id.trim() ? input.id.trim() : undefined;
+    if (!input.file && !input.outputDir && id) {
+        const request = await getHostRunRequest({ id }, runsPath);
+        const outputDir = request?.spec.options?.outputDir;
+        return {
+            ...input,
+            outputDir
+        };
+    }
+    return input;
+}
+async function syncRunRequestHeartbeat(request, now) {
+    const outputDir = request.spec.options?.outputDir;
+    if (!outputDir || request.status === "pending")
+        return;
+    await writeHostRunHeartbeat({
+        path: hostRunHeartbeatPathForOutputDir(outputDir),
+        runId: request.id,
+        status: request.status,
+        outputDir,
+        pid: process.pid,
+        detail: request.detail,
+        command: request.result?.command,
+        exitCode: request.result?.exitCode,
+        loopCount: request.status === "running" ? 0 : 1,
+        now
+    });
+}
+async function syncRunRequestMeta(request, now) {
+    const outputDir = request.spec.options?.outputDir;
+    if (!outputDir || request.status === "pending")
+        return;
+    await updateHostRunMeta({
+        file: hostRunMetaPathForOutputDir(outputDir),
+        runId: request.id,
+        status: request.status,
+        actualLoops: request.status === "running" ? 0 : 1,
+        detail: request.detail,
+        command: request.result?.command,
+        exitCode: request.result?.exitCode,
+        now
+    });
+}
+async function syncRunRequestLoopEvent(request, now) {
+    const outputDir = request.spec.options?.outputDir;
+    if (!outputDir || request.status === "pending")
+        return;
+    await appendHostLoopEvent({
+        outputDir,
+        event: {
+            type: "run.status",
+            runId: request.id,
+            timestamp: (now ?? (() => new Date()))().toISOString(),
+            status: request.status,
+            detail: request.detail,
+            command: request.result?.command,
+            exitCode: request.result?.exitCode,
+            loop: request.status === "running" ? 0 : 1,
+            source: "update-run"
+        }
+    });
+}
+function normalizeExportInput(value) {
+    if (!value)
+        return {};
+    if (value && typeof value === "object")
+        return value;
+    throw new Error("export input must be an object");
+}
+function cleanInputString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function numberInput(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (typeof value === "string" && value.trim()) {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return undefined;
+}
+function dropUndefined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}
+function normalizeAvailableEngines(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    return value.filter((entry) => entry === "claude" || entry === "codex");
+}