@tea-agent/loop-agent 0.23.1 → 0.24.0

package/dist/shared/operator/capabilities.js

@@ -1,4 +1,82 @@
 import { OPERATOR_ERROR_CODES_V1, OPERATOR_OUTCOMES_V1 } from "./registry.js";
+const officialAction = (action, cli, kind, coverage) => ({
+    action,
+    cli,
+    kind,
+    inputSchemaVersion: 1,
+    resultSchemaVersion: 1,
+    envelopeSchemaVersion: 1,
+    requiredErrorCodes: kind === "read"
+        ? ["INVALID_INPUT", "NOT_FOUND"]
+        : ["INVALID_INPUT", "REQUEST_ID_REUSE_CONFLICT", "REVISION_CONFLICT", "OBSERVED_HASH_CONFLICT", "LEASE_HELD", "TRANSACTION_INCOMPLETE", "NOT_FOUND"],
+    description: `Official CLI action coverage for ${cli}.`,
+    inputParams: [
+        { name: "args", type: "array", itemsType: "string", required: false, description: "validated trailing CLI arguments" },
+        ...(coverage === "human-gated-required" ? [{ name: "confirmationId", type: "string", required: true, description: "human confirmation receipt id" }] : []),
+    ],
+    modelCallable: coverage === "human-gated-required"
+        ? "prepare-only"
+        : coverage === "advanced" && kind !== "read"
+            ? "never"
+            : "always",
+    humanConfirmation: coverage === "human-gated-required" ? "required" : "none",
+});
+const OFFICIAL_ACTIONS = [
+    ...[
+        ["dagDoctor", "loop-agent dag doctor", "read", "model-callable"],
+        ["dagStatus", "loop-agent dag status", "read", "model-callable"],
+        ["dagDecisionInspect", "loop-agent dag decision inspect", "read", "model-callable"],
+        ["dagDecisionValidate", "loop-agent dag decision validate", "read", "model-callable"],
+        ["dagCloseoutDraft", "loop-agent dag closeout-draft", "read", "model-callable"],
+        ["dagApprove", "loop-agent dag approve", "mutation", "human-gated-required"],
+        ["dagReject", "loop-agent dag reject", "mutation", "human-gated-required"],
+        ["dagResume", "loop-agent dag resume", "long-running", "human-gated-required"],
+        ["dagReconcileRun", "loop-agent dag reconcile-run", "mutation", "human-gated-required"],
+        ["dagReconcileTasks", "loop-agent dag reconcile-tasks", "mutation", "human-gated-required"],
+        ["dagFinalVerification", "loop-agent dag final-verification", "long-running", "human-gated-required"],
+        ["dagInitHybrid", "loop-agent dag init-hybrid", "mutation", "advanced"],
+        ["dagWorkflowPlan", "loop-agent dag workflow-plan", "read", "advanced"],
+        ["dagWorkflowValidate", "loop-agent dag workflow-validate", "read", "advanced"],
+        ["dagWorkflowCompile", "loop-agent dag workflow-compile", "mutation", "advanced"],
+        ["planList", "loop-agent plan list", "read", "model-callable"],
+        ["planCreate", "loop-agent plan create", "mutation", "model-callable"],
+        ["planComplete", "loop-agent plan complete", "mutation", "model-callable"],
+        ["planCheck", "loop-agent plan check", "read", "model-callable"],
+        ["docsAudit", "loop-agent docs audit", "read", "model-callable"],
+        ["docsArchive", "loop-agent docs archive", "mutation", "advanced"],
+        ["handoffCheck", "loop-agent handoff check", "read", "model-callable"],
+        ["handoffCoverage", "loop-agent handoff coverage", "read", "model-callable"],
+        ["coverageReport", "loop-agent coverage report", "read", "model-callable"],
+        ["stats", "loop-agent stats", "read", "model-callable"],
+        ["promoteRun", "loop-agent promote-run", "mutation", "model-callable"],
+        ["closeoutTask", "loop-agent closeout task", "mutation", "model-callable"],
+        ["piReuseBenchmark", "loop-agent pi-reuse-benchmark", "read", "advanced"],
+        ["loopBenchmark", "loop-agent loop-benchmark", "read", "advanced"],
+        ["knowledgeCurate", "loop-agent knowledge curate", "read", "model-callable"],
+        ["knowledgeQuery", "loop-agent knowledge query", "read", "model-callable"],
+        ["knowledgeGraphInit", "loop-agent knowledge graph-init", "mutation", "advanced"],
+        ["knowledgeGraphMaterialize", "loop-agent knowledge graph-materialize", "mutation", "advanced"],
+        ["knowledgeGraphPromote", "loop-agent knowledge graph-promote", "mutation", "advanced"],
+        ["knowledgeGraphIncrementalPrepare", "loop-agent knowledge graph-incremental-prepare", "mutation", "advanced"],
+        ...["init", "status", "run", "record-round", "add-signal", "closeout"].map((leaf) => [`loop${leaf.replace(/(^|-)(.)/g, (_m, _d, c) => c.toUpperCase())}`, `loop-agent loop ${leaf}`, leaf === "status" ? "read" : "mutation", "advanced"]),
+        ...["list", "inspect", "save", "run", "diff", "replay"].map((leaf) => [`workflow${leaf[0].toUpperCase()}${leaf.slice(1)}`, `loop-agent workflow ${leaf}`, ["list", "inspect", "diff"].includes(leaf) ? "read" : "mutation", "advanced"]),
+        ["workerFeatureReview", "agent-worker feature review", "read", "model-callable"],
+        ["workerFeatureRun", "agent-worker feature run", "long-running", "human-gated-required"],
+        ["workerFeatureVerifyFinal", "agent-worker feature verify-final", "long-running", "human-gated-required"],
+        ["workerFeatureDelivery", "agent-worker feature delivery", "mutation", "human-gated-required"],
+        ["workerFeatureCloseout", "agent-worker feature closeout", "mutation", "human-gated-required"],
+        ["workerTaskValidate", "agent-worker task validate", "read", "model-callable"],
+        ["workerTaskReconcile", "agent-worker task reconcile", "mutation", "human-gated-required"],
+        ["workerTaskDraftFollowup", "agent-worker task draft-followup", "mutation", "advanced"],
+        ["workerFeatureApproveFollowup", "agent-worker feature approve-followup", "mutation", "advanced"],
+        ["workerBatchPlanReady", "agent-worker batch plan-ready", "read", "model-callable"],
+        ["workerBatchRunReady", "agent-worker batch run-ready", "long-running", "advanced"],
+        ["workerPoolDoctor", "agent-worker pool doctor", "read", "model-callable"],
+        ["workerPoolMarkFailed", "agent-worker pool mark-failed", "mutation", "human-gated-required"],
+        ["workerReportMorning", "agent-worker report morning", "read", "model-callable"],
+        ["workerReportMetrics", "agent-worker report metrics", "read", "model-callable"],
+    ]
+].map(([action, cli, kind, coverage]) => officialAction(action, cli, kind, coverage));
 /** Shared constants so dag + dagSpecVersions cannot diverge. */
 const DAG_SPEC_SUPPORTED_PARSE = [1, 2, 3, 4];
 const DAG_SPEC_NEW_WRITER_DEFAULT = 4;
@@ -25,6 +103,60 @@ export function buildOperatorCapabilitiesDocument() {
             envelopeSchemaVersion: 1,
             requiredErrorCodes: ["UNSUPPORTED_SCHEMA_VERSION", "INVALID_INPUT"],
             description: "Publish action/schema/error registry for Console negotiation.",
+            inputParams: [],
+            modelCallable: "always",
+            humanConfirmation: "none",
+        },
+        {
+            action: "operationGet",
+            cli: "console canonical operation read model (single operation)",
+            kind: "read",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            resultPolicy: { readOnly: true, bounded: true, redacted: true },
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: ["NOT_FOUND", "INVALID_INPUT"],
+            description: "Read one canonical Console operation as a bounded redacted projection.",
+            inputParams: [
+                { name: "operationId", type: "string", required: true, description: "canonical operation id" },
+            ],
+            modelCallable: "always",
+            humanConfirmation: "none",
+        },
+        {
+            action: "operationList",
+            cli: "console canonical operation read model (bounded list)",
+            kind: "read",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            resultPolicy: { readOnly: true, bounded: true, redacted: true },
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: ["INVALID_INPUT"],
+            description: "List canonical Console operations using bounded read-only filters.",
+            inputParams: [
+                { name: "limit", type: "number", required: false, description: "maximum results (1-50, default 20)" },
+                { name: "state", type: "string", required: false, description: "optional operation state filter" },
+                { name: "action", type: "string", required: false, description: "optional exact action filter" },
+            ],
+            modelCallable: "always",
+            humanConfirmation: "none",
+        },
+        {
+            action: "operationEventSummary",
+            cli: "console canonical operation event store (bounded summary)",
+            kind: "read",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            resultPolicy: { readOnly: true, bounded: true, redacted: true },
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: ["NOT_FOUND", "INVALID_INPUT"],
+            description: "Read a bounded redacted summary from the canonical operation event ring.",
+            inputParams: [
+                { name: "operationId", type: "string", required: true, description: "canonical operation id" },
+                { name: "limit", type: "number", required: false, description: "maximum newest events (1-100, default 20)" },
+            ],
+            modelCallable: "always",
+            humanConfirmation: "none",
         },
         {
             action: "contractShow",
@@ -35,6 +167,11 @@ export function buildOperatorCapabilitiesDocument() {
             envelopeSchemaVersion: 1,
             requiredErrorCodes: ["NOT_FOUND", "INVALID_INPUT"],
             description: "Return TaskContractStateV1 + observed hashes.",
+            inputParams: [
+                { name: "taskId", type: "string", required: true, description: "task id" },
+            ],
+            modelCallable: "always",
+            humanConfirmation: "none",
         },
         {
             action: "contractValidate",
@@ -45,6 +182,20 @@ export function buildOperatorCapabilitiesDocument() {
             envelopeSchemaVersion: 1,
             requiredErrorCodes: ["INVALID_INPUT", "NOT_FOUND", "PATH_OUTSIDE_REPO"],
             description: "Schema/path/traceability validation for a Draft (read-only).",
+            // Dispatcher reads draftJson/inputText (a JSON string staged to a file),
+            // NOT a `draft` object. draftJson is optional — dispatcher falls back to
+            // the saved draft.
+            inputParams: [
+                { name: "taskId", type: "string", required: true, description: "task id" },
+                {
+                    name: "draftJson",
+                    type: "string",
+                    required: false,
+                    description: "draft JSON string (optional; omit to validate the saved draft)",
+                },
+            ],
+            modelCallable: "always",
+            humanConfirmation: "none",
         },
         {
             action: "contractDiff",
@@ -55,6 +206,17 @@ export function buildOperatorCapabilitiesDocument() {
             envelopeSchemaVersion: 1,
             requiredErrorCodes: ["INVALID_INPUT", "NOT_FOUND", "PATH_OUTSIDE_REPO"],
             description: "Risk-classified diff against current managed/legacy state.",
+            inputParams: [
+                { name: "taskId", type: "string", required: true, description: "task id" },
+                {
+                    name: "draftJson",
+                    type: "string",
+                    required: false,
+                    description: "draft JSON string (optional; omit to diff the saved draft)",
+                },
+            ],
+            modelCallable: "always",
+            humanConfirmation: "none",
         },
         {
             action: "contractApply",
@@ -65,6 +227,14 @@ export function buildOperatorCapabilitiesDocument() {
             envelopeSchemaVersion: 1,
             requiredErrorCodes: [...COMMON_MUTATION_ERRORS, "EXTERNALLY_MODIFIED"],
             description: "Journaled apply of Draft to canonical task facts.",
+            inputParams: [
+                { name: "taskId", type: "string", required: true, description: "task id" },
+                { name: "assessmentId", type: "string", required: false, description: "assessment id binding (defaults to the draft's bound assessment)" },
+                { name: "expectedRevision", type: "string", required: false, description: "expected contract revision (defaults to live observed)" },
+                { name: "expectedObservedHash", type: "string", required: false, description: "expected observed hash (defaults to live observed)" },
+            ],
+            modelCallable: "always",
+            humanConfirmation: "conditional",
         },
         {
             action: "newTask",
@@ -75,6 +245,12 @@ export function buildOperatorCapabilitiesDocument() {
             envelopeSchemaVersion: 1,
             requiredErrorCodes: [...COMMON_MUTATION_ERRORS],
             description: "Create a new task harness skeleton via sibling CLI.",
+            inputParams: [
+                { name: "taskId", type: "string", required: true, description: "task id" },
+                { name: "title", type: "string", required: false, description: "task title (defaults to taskId)" },
+            ],
+            modelCallable: "always",
+            humanConfirmation: "none",
         },
         {
             action: "importPrd",
@@ -85,6 +261,12 @@ export function buildOperatorCapabilitiesDocument() {
             envelopeSchemaVersion: 1,
             requiredErrorCodes: [...COMMON_MUTATION_ERRORS, "PATH_OUTSIDE_REPO"],
             description: "Import immutable PRD/source reference via sibling CLI (server-staged file).",
+            inputParams: [
+                { name: "taskId", type: "string", required: true, description: "task id" },
+                { name: "content", type: "string", required: true, description: "PRD markdown content" },
+            ],
+            modelCallable: "always",
+            humanConfirmation: "none",
         },
         {
             action: "sourceInstructions",
@@ -95,6 +277,11 @@ export function buildOperatorCapabilitiesDocument() {
             envelopeSchemaVersion: 1,
             requiredErrorCodes: ["NOT_FOUND", "INVALID_INPUT"],
             description: "Read source instruction contract for a task.",
+            inputParams: [
+                { name: "taskId", type: "string", required: true, description: "task id" },
+            ],
+            modelCallable: "always",
+            humanConfirmation: "none",
         },
         {
             action: "contractDraftSave",
@@ -105,6 +292,17 @@ export function buildOperatorCapabilitiesDocument() {
             envelopeSchemaVersion: 1,
             requiredErrorCodes: ["INVALID_INPUT"],
             description: "Save TaskContractDraftV1 to Console application data only (not repo .harness).",
+            inputParams: [
+                { name: "taskId", type: "string", required: false, description: "task id (defaults to draft.taskId)" },
+                {
+                    name: "draft",
+                    type: "object",
+                    required: true,
+                    description: "TaskContractDraftV1 object",
+                },
+            ],
+            modelCallable: "always",
+            humanConfirmation: "none",
         },
         {
             action: "prepareDagConfirmation",
@@ -119,6 +317,14 @@ export function buildOperatorCapabilitiesDocument() {
                 "HUMAN_CONFIRMATION_REQUIRED",
             ],
             description: "Prepare server-side DagConfirmationV1 receipt for human challenge.",
+            inputParams: [
+                { name: "taskId", type: "string", required: true, description: "task id" },
+                { name: "dagPath", type: "string", required: false, description: "staged DAG path (optional; resolved from the last dagRunTask result)" },
+                { name: "operatorAction", type: "string", required: false, description: "required official action to bind to this single-use human confirmation receipt" },
+                { name: "operatorActionArgs", type: "array", itemsType: "string", required: false, description: "exact trailing CLI arguments bound to the official action receipt" },
+            ],
+            modelCallable: "always",
+            humanConfirmation: "none",
         },
         {
             action: "confirmDagConfirmation",
@@ -136,6 +342,15 @@ export function buildOperatorCapabilitiesDocument() {
                 "HUMAN_CONFIRMATION_REQUIRED",
             ],
             description: "Human challenge confirm of DagConfirmationV1 using server-derived current bindings.",
+            // M0-B: confirmDagConfirmation is NEVER model-callable. It IS the human
+            // confirmation — the model cannot self-confirm (roadmap G03). The model
+            // only prepares via prepareDagConfirmation; the browser mutation gate
+            // executes the confirm with a server-signed confirmationToken.
+            inputParams: [
+                { name: "confirmationId", type: "string", required: true, description: "confirmation id from prepareDagConfirmation" },
+            ],
+            modelCallable: "never",
+            humanConfirmation: "required",
         },
         {
             action: "observeLink",
@@ -146,6 +361,9 @@ export function buildOperatorCapabilitiesDocument() {
             envelopeSchemaVersion: 1,
             requiredErrorCodes: ["INVALID_INPUT"],
             description: "Build Observe deep link from stable object identity.",
+            inputParams: [],
+            modelCallable: "always",
+            humanConfirmation: "none",
         },
         {
             action: "inspect",
@@ -156,6 +374,9 @@ export function buildOperatorCapabilitiesDocument() {
             envelopeSchemaVersion: 1,
             requiredErrorCodes: ["INVALID_INPUT"],
             description: "Repo preflight (registry entry; envelope migration follow-up).",
+            inputParams: [],
+            modelCallable: "always",
+            humanConfirmation: "none",
         },
         {
             action: "doctor",
@@ -166,6 +387,9 @@ export function buildOperatorCapabilitiesDocument() {
             envelopeSchemaVersion: 1,
             requiredErrorCodes: ["INVALID_INPUT", "OPERATION_NEEDS_RECONCILE"],
             description: "Repo health doctor with machine-readable report and read-only context audit (--context).",
+            inputParams: [],
+            modelCallable: "always",
+            humanConfirmation: "none",
         },
         {
             action: "statsContext",
@@ -176,6 +400,9 @@ export function buildOperatorCapabilitiesDocument() {
             envelopeSchemaVersion: 1,
             requiredErrorCodes: ["INVALID_INPUT"],
             description: "Bounded skill-resolution / node-outcome telemetry over recent DAG runs (not compliance rates).",
+            inputParams: [],
+            modelCallable: "always",
+            humanConfirmation: "none",
         },
         {
             action: "dagReport",
@@ -186,6 +413,11 @@ export function buildOperatorCapabilitiesDocument() {
             envelopeSchemaVersion: 1,
             requiredErrorCodes: ["NOT_FOUND", "INVALID_INPUT"],
             description: "DAG run handoff report by run id.",
+            inputParams: [
+                { name: "runId", type: "string", required: true, description: "dag run id" },
+            ],
+            modelCallable: "always",
+            humanConfirmation: "none",
         },
         {
             action: "status",
@@ -196,6 +428,11 @@ export function buildOperatorCapabilitiesDocument() {
             envelopeSchemaVersion: 1,
             requiredErrorCodes: ["NOT_FOUND", "INVALID_INPUT"],
             description: "Task status (registry entry).",
+            inputParams: [
+                { name: "taskId", type: "string", required: true, description: "task id" },
+            ],
+            modelCallable: "always",
+            humanConfirmation: "none",
         },
         {
             action: "spineCheck",
@@ -206,6 +443,11 @@ export function buildOperatorCapabilitiesDocument() {
             envelopeSchemaVersion: 1,
             requiredErrorCodes: ["NOT_FOUND", "INVALID_INPUT"],
             description: "Spine audit (registry entry).",
+            inputParams: [
+                { name: "taskId", type: "string", required: true, description: "task id" },
+            ],
+            modelCallable: "always",
+            humanConfirmation: "none",
         },
         {
             action: "dagRunTask",
@@ -221,6 +463,12 @@ export function buildOperatorCapabilitiesDocument() {
                 "INVALID_INPUT",
             ],
             description: "Generate DagSpec v4 with taskContractBinding (managed required).",
+            inputParams: [
+                { name: "taskId", type: "string", required: true, description: "task id to run as a DAG" },
+                { name: "profile", type: "string", required: false, description: "DAG profile (defaults to auto)" },
+            ],
+            modelCallable: "always",
+            humanConfirmation: "none",
         },
         {
             action: "dagValidate",
@@ -231,6 +479,12 @@ export function buildOperatorCapabilitiesDocument() {
             envelopeSchemaVersion: 1,
             requiredErrorCodes: ["INVALID_INPUT", "BINDING_DRIFT"],
             description: "Validate DAG including taskContractBinding drift checks.",
+            inputParams: [
+                { name: "dagPath", type: "string", required: true, description: "DAG file path to validate" },
+                { name: "taskId", type: "string", required: false, description: "spine task id (optional, for strict-governance spine check)" },
+            ],
+            modelCallable: "always",
+            humanConfirmation: "none",
         },
         {
             action: "runDag",
@@ -245,6 +499,13 @@ export function buildOperatorCapabilitiesDocument() {
                 "INVALID_INPUT",
             ],
             description: "Execute reviewed DAG; revalidate binding before writer start.",
+            inputParams: [
+                { name: "confirmationId", type: "string", required: true, description: "confirmation id (from prepareDagConfirmation) — raw dag path is never accepted from the model" },
+            ],
+            // prepare-only: the model can invoke runDag but it MUST carry a
+            // confirmationId that was consumed by a human-origin confirm (M0-B).
+            modelCallable: "prepare-only",
+            humanConfirmation: "required",
         },
         {
             action: "dagRerunPlan",
@@ -255,6 +516,12 @@ export function buildOperatorCapabilitiesDocument() {
             envelopeSchemaVersion: 1,
             requiredErrorCodes: ["INVALID_INPUT", "NOT_FOUND"],
             description: "Read-only subgraph rerun plan for confirmation (no mutation).",
+            inputParams: [
+                { name: "runId", type: "string", required: true, description: "dag run id" },
+                { name: "fromNode", type: "string", required: true, description: "node id to rerun from" },
+            ],
+            modelCallable: "always",
+            humanConfirmation: "none",
         },
         {
             action: "dagRerun",
@@ -269,6 +536,30 @@ export function buildOperatorCapabilitiesDocument() {
                 "INVALID_INPUT",
             ],
             description: "Execute continuation run from effective node with confirmed plan hash.",
+            inputParams: [
+                { name: "runId", type: "string", required: true, description: "dag run id" },
+                { name: "fromNode", type: "string", required: true, description: "node id to rerun from" },
+                { name: "planHash", type: "string", required: true, description: "rerun plan hash" },
+                { name: "reason", type: "string", required: true, description: "rerun reason" },
+            ],
+            modelCallable: "prepare-only",
+            humanConfirmation: "required",
+        },
+        {
+            action: "prepareMutationGate",
+            cli: "console prepare-mutation-gate",
+            kind: "mutation",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: ["INVALID_INPUT", "NOT_FOUND"],
+            description: "Prepare a one-shot Human Gate receipt for standaloneTaskRerun / workerTaskRetry. Model may prepare; only the browser mutation gate may consume.",
+            inputParams: [
+                { name: "action", type: "string", required: true, description: "target action: standaloneTaskRerun | workerTaskRetry" },
+                { name: "actionParams", type: "object", required: true, description: "params that will be bound into the receipt hash" },
+            ],
+            modelCallable: "always",
+            humanConfirmation: "none",
         },
         {
             action: "standaloneTaskRerun",
@@ -277,8 +568,16 @@ export function buildOperatorCapabilitiesDocument() {
             inputSchemaVersion: 1,
             resultSchemaVersion: 1,
             envelopeSchemaVersion: 1,
-            requiredErrorCodes: [...COMMON_MUTATION_ERRORS, "INVALID_INPUT"],
+            requiredErrorCodes: [...COMMON_MUTATION_ERRORS, "INVALID_INPUT", "HUMAN_CONFIRMATION_REQUIRED"],
             description: "Full standalone task regenerate → validate → execute with parent lineage.",
+            inputParams: [
+                { name: "runId", type: "string", required: true, description: "dag run id" },
+                { name: "reason", type: "string", required: true, description: "rerun reason" },
+                { name: "confirmationId", type: "string", required: true, description: "mutation-gate receipt id from prepareMutationGate" },
+                { name: "humanGateToken", type: "object", required: true, description: "server-signed human-gate token from prepareMutationGate" },
+            ],
+            modelCallable: "prepare-only",
+            humanConfirmation: "required",
         },
         {
             action: "workerTaskRetry",
@@ -287,9 +586,19 @@ export function buildOperatorCapabilitiesDocument() {
             inputSchemaVersion: 1,
             resultSchemaVersion: 1,
             envelopeSchemaVersion: 1,
-            requiredErrorCodes: [...COMMON_MUTATION_ERRORS, "INVALID_INPUT"],
+            requiredErrorCodes: [...COMMON_MUTATION_ERRORS, "INVALID_INPUT", "HUMAN_CONFIRMATION_REQUIRED"],
             description: "Requeue failed Task Pool task (Failed → Ready) via in-package pool store.",
+            inputParams: [
+                { name: "taskId", type: "string", required: true, description: "task id" },
+                { name: "featureId", type: "string", required: false, description: "feature id (canonical retry carries Feature identity; passed to the CLI as --feature-id when present)" },
+                { name: "reason", type: "string", required: true, description: "retry reason" },
+                { name: "confirmationId", type: "string", required: true, description: "mutation-gate receipt id from prepareMutationGate" },
+                { name: "humanGateToken", type: "object", required: true, description: "server-signed human-gate token from prepareMutationGate" },
+            ],
+            modelCallable: "prepare-only",
+            humanConfirmation: "required",
         },
+        ...OFFICIAL_ACTIONS,
     ];
     return {
         schemaVersion: 1,
@@ -317,3 +626,167 @@ export function buildOperatorCapabilitiesDocument() {
         actions,
     };
 }
+export const OPERATOR_COMMAND_COVERAGE = Object.freeze([
+    { command: "loop-agent inspect", coverage: "model-callable", action: "inspect", source: "loop-agent" },
+    { command: "loop-agent doctor", coverage: "model-callable", action: "doctor", source: "loop-agent" },
+    { command: "loop-agent new-task", coverage: "model-callable", action: "newTask", source: "loop-agent" },
+    { command: "loop-agent import-prd", coverage: "model-callable", action: "importPrd", source: "loop-agent" },
+    { command: "loop-agent status", coverage: "model-callable", action: "status", source: "loop-agent" },
+    { command: "loop-agent promote-run", coverage: "model-callable", action: "promoteRun", source: "loop-agent" },
+    { command: "loop-agent pi-reuse-benchmark", coverage: "advanced", action: "piReuseBenchmark", source: "loop-agent" },
+    { command: "loop-agent loop-benchmark", coverage: "advanced", action: "loopBenchmark", source: "loop-agent" },
+    { command: "loop-agent run-dag", coverage: "human-gated-required", action: "runDag", source: "loop-agent" },
+    { command: "loop-agent cursor-prompt", coverage: "excluded", action: null, source: "loop-agent", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "loop-agent pi-prompt", coverage: "excluded", action: null, source: "loop-agent", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "loop-agent delegate", coverage: "excluded", action: null, source: "loop-agent", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "loop-agent harvest", coverage: "excluded", action: null, source: "loop-agent", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "loop-agent goal", coverage: "excluded", action: null, source: "loop-agent", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "loop-agent docs audit", coverage: "model-callable", action: "docsAudit", source: "loop-agent" },
+    { command: "loop-agent docs archive", coverage: "advanced", action: "docsArchive", source: "loop-agent" },
+    { command: "loop-agent init instructions", coverage: "excluded", action: null, source: "loop-agent", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "loop-agent init doctor", coverage: "excluded", action: null, source: "loop-agent", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "loop-agent init check-update", coverage: "excluded", action: null, source: "loop-agent", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "loop-agent init update", coverage: "excluded", action: null, source: "loop-agent", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "loop-agent init reconcile", coverage: "excluded", action: null, source: "loop-agent", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "loop-agent examples list", coverage: "excluded", action: null, source: "loop-agent", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "loop-agent examples show", coverage: "excluded", action: null, source: "loop-agent", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "loop-agent examples copy", coverage: "excluded", action: null, source: "loop-agent", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "loop-agent eval replay", coverage: "excluded", action: null, source: "loop-agent", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "loop-agent eval report", coverage: "excluded", action: null, source: "loop-agent", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "loop-agent eval candidate", coverage: "excluded", action: null, source: "loop-agent", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "loop-agent eval alias", coverage: "excluded", action: null, source: "loop-agent", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "loop-agent eval promote", coverage: "excluded", action: null, source: "loop-agent", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "loop-agent eval rollback", coverage: "excluded", action: null, source: "loop-agent", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "loop-agent eval corpus", coverage: "excluded", action: null, source: "loop-agent", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "loop-agent eval context-policy", coverage: "excluded", action: null, source: "loop-agent", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "loop-agent eval budget", coverage: "excluded", action: null, source: "loop-agent", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "loop-agent eval private-verifier", coverage: "excluded", action: null, source: "loop-agent", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "loop-agent eval campaign", coverage: "excluded", action: null, source: "loop-agent", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "loop-agent eval experiment", coverage: "excluded", action: null, source: "loop-agent", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "loop-agent eval propose", coverage: "excluded", action: null, source: "loop-agent", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "loop-agent eval outer-loop", coverage: "excluded", action: null, source: "loop-agent", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "loop-agent eval ignition", coverage: "excluded", action: null, source: "loop-agent", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "loop-agent closeout task", coverage: "model-callable", action: "closeoutTask", source: "loop-agent" },
+    { command: "loop-agent plan list", coverage: "model-callable", action: "planList", source: "loop-agent" },
+    { command: "loop-agent plan create", coverage: "model-callable", action: "planCreate", source: "loop-agent" },
+    { command: "loop-agent plan complete", coverage: "model-callable", action: "planComplete", source: "loop-agent" },
+    { command: "loop-agent plan check", coverage: "model-callable", action: "planCheck", source: "loop-agent" },
+    { command: "loop-agent spine audit", coverage: "model-callable", action: "spineCheck", source: "loop-agent" },
+    { command: "loop-agent handoff check", coverage: "model-callable", action: "handoffCheck", source: "loop-agent" },
+    { command: "loop-agent handoff coverage", coverage: "model-callable", action: "handoffCoverage", source: "loop-agent" },
+    { command: "loop-agent coverage report", coverage: "model-callable", action: "coverageReport", source: "loop-agent" },
+    { command: "loop-agent reference index", coverage: "excluded", action: null, source: "loop-agent", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "loop-agent study init", coverage: "excluded", action: null, source: "loop-agent", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "loop-agent worktree create", coverage: "excluded", action: null, source: "loop-agent", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "loop-agent worktree list", coverage: "excluded", action: null, source: "loop-agent", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "loop-agent worktree remove", coverage: "excluded", action: null, source: "loop-agent", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "loop-agent knowledge curate", coverage: "model-callable", action: "knowledgeCurate", source: "loop-agent" },
+    { command: "loop-agent knowledge query", coverage: "model-callable", action: "knowledgeQuery", source: "loop-agent" },
+    { command: "loop-agent knowledge graph-init", coverage: "advanced", action: "knowledgeGraphInit", source: "loop-agent" },
+    { command: "loop-agent knowledge graph-materialize", coverage: "advanced", action: "knowledgeGraphMaterialize", source: "loop-agent" },
+    { command: "loop-agent knowledge graph-promote", coverage: "advanced", action: "knowledgeGraphPromote", source: "loop-agent" },
+    { command: "loop-agent knowledge graph-incremental-prepare", coverage: "advanced", action: "knowledgeGraphIncrementalPrepare", source: "loop-agent" },
+    { command: "loop-agent dag init-hybrid", coverage: "advanced", action: "dagInitHybrid", source: "loop-agent" },
+    { command: "loop-agent dag run-task", coverage: "model-callable", action: "dagRunTask", source: "loop-agent" },
+    { command: "loop-agent dag validate", coverage: "model-callable", action: "dagValidate", source: "loop-agent" },
+    { command: "loop-agent dag workflow-plan", coverage: "advanced", action: "dagWorkflowPlan", source: "loop-agent" },
+    { command: "loop-agent dag workflow-validate", coverage: "advanced", action: "dagWorkflowValidate", source: "loop-agent" },
+    { command: "loop-agent dag workflow-compile", coverage: "advanced", action: "dagWorkflowCompile", source: "loop-agent" },
+    { command: "loop-agent dag approve", coverage: "human-gated-required", action: "dagApprove", source: "loop-agent" },
+    { command: "loop-agent dag reject", coverage: "human-gated-required", action: "dagReject", source: "loop-agent" },
+    { command: "loop-agent dag resume", coverage: "human-gated-required", action: "dagResume", source: "loop-agent" },
+    { command: "loop-agent dag status", coverage: "model-callable", action: "dagStatus", source: "loop-agent" },
+    { command: "loop-agent dag doctor", coverage: "model-callable", action: "dagDoctor", source: "loop-agent" },
+    { command: "loop-agent dag report", coverage: "model-callable", action: "dagReport", source: "loop-agent" },
+    { command: "loop-agent dag closeout-draft", coverage: "model-callable", action: "dagCloseoutDraft", source: "loop-agent" },
+    { command: "loop-agent dag reconcile-run", coverage: "human-gated-required", action: "dagReconcileRun", source: "loop-agent" },
+    { command: "loop-agent dag rerun", coverage: "human-gated-required", action: "dagRerun", source: "loop-agent" },
+    { command: "loop-agent dag rerun-task", coverage: "human-gated-required", action: "standaloneTaskRerun", source: "loop-agent" },
+    { command: "loop-agent dag reconcile-tasks", coverage: "human-gated-required", action: "dagReconcileTasks", source: "loop-agent" },
+    { command: "loop-agent dag final-verification", coverage: "human-gated-required", action: "dagFinalVerification", source: "loop-agent" },
+    { command: "loop-agent workflow list", coverage: "advanced", action: "workflowList", source: "loop-agent" },
+    { command: "loop-agent workflow inspect", coverage: "advanced", action: "workflowInspect", source: "loop-agent" },
+    { command: "loop-agent workflow save", coverage: "advanced", action: "workflowSave", source: "loop-agent" },
+    { command: "loop-agent workflow run", coverage: "advanced", action: "workflowRun", source: "loop-agent" },
+    { command: "loop-agent workflow diff", coverage: "advanced", action: "workflowDiff", source: "loop-agent" },
+    { command: "loop-agent workflow replay", coverage: "advanced", action: "workflowReplay", source: "loop-agent" },
+    { command: "loop-agent loop init", coverage: "advanced", action: "loopInit", source: "loop-agent" },
+    { command: "loop-agent loop status", coverage: "advanced", action: "loopStatus", source: "loop-agent" },
+    { command: "loop-agent loop run", coverage: "advanced", action: "loopRun", source: "loop-agent" },
+    { command: "loop-agent loop record-round", coverage: "advanced", action: "loopRecordRound", source: "loop-agent" },
+    { command: "loop-agent loop add-signal", coverage: "advanced", action: "loopAddSignal", source: "loop-agent" },
+    { command: "loop-agent loop closeout", coverage: "advanced", action: "loopCloseout", source: "loop-agent" },
+    { command: "loop-agent dag decision inspect", coverage: "model-callable", action: "dagDecisionInspect", source: "loop-agent" },
+    { command: "loop-agent dag decision validate", coverage: "model-callable", action: "dagDecisionValidate", source: "loop-agent" },
+    { command: "loop-agent task contract show", coverage: "model-callable", action: "contractShow", source: "loop-agent" },
+    { command: "loop-agent task contract validate", coverage: "model-callable", action: "contractValidate", source: "loop-agent" },
+    { command: "loop-agent task contract diff", coverage: "model-callable", action: "contractDiff", source: "loop-agent" },
+    { command: "loop-agent task contract apply", coverage: "human-gated-conditional", action: "contractApply", source: "loop-agent" },
+    { command: "loop-agent task contract adopt", coverage: "excluded", action: null, source: "loop-agent", exclusionReason: "Managed recovery face remains outside Chat in M5." },
+    { command: "loop-agent task contract doctor", coverage: "excluded", action: null, source: "loop-agent", exclusionReason: "Managed recovery face remains outside Chat in M5." },
+    { command: "loop-agent task contract recover", coverage: "excluded", action: null, source: "loop-agent", exclusionReason: "Managed recovery face remains outside Chat in M5." },
+    { command: "loop-agent operator capabilities", coverage: "model-callable", action: "operatorCapabilities", source: "loop-agent" },
+    { command: "loop-agent instructions source", coverage: "model-callable", action: "sourceInstructions", source: "loop-agent" },
+    { command: "loop-agent instructions dag-draft", coverage: "excluded", action: null, source: "loop-agent", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "loop-agent instructions task-artifacts", coverage: "excluded", action: null, source: "loop-agent", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "loop-agent instructions promotion", coverage: "excluded", action: null, source: "loop-agent", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "loop-agent instructions closeout", coverage: "excluded", action: null, source: "loop-agent", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "loop-agent stats", coverage: "model-callable", action: "stats", source: "loop-agent" },
+    { command: "loop-agent stats context", coverage: "model-callable", action: "statsContext", source: "loop-agent" },
+    { command: "agent-worker feature review", coverage: "model-callable", action: "workerFeatureReview", source: "agent-worker" },
+    { command: "agent-worker feature run", coverage: "human-gated-required", action: "workerFeatureRun", source: "agent-worker" },
+    { command: "agent-worker feature verify-final", coverage: "human-gated-required", action: "workerFeatureVerifyFinal", source: "agent-worker" },
+    { command: "agent-worker feature delivery", coverage: "human-gated-required", action: "workerFeatureDelivery", source: "agent-worker" },
+    { command: "agent-worker feature closeout", coverage: "human-gated-required", action: "workerFeatureCloseout", source: "agent-worker" },
+    { command: "agent-worker feature approve-followup", coverage: "advanced", action: "workerFeatureApproveFollowup", source: "agent-worker" },
+    { command: "agent-worker task validate", coverage: "model-callable", action: "workerTaskValidate", source: "agent-worker" },
+    { command: "agent-worker task explain-profile", coverage: "excluded", action: null, source: "agent-worker", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "agent-worker task validate-feature", coverage: "excluded", action: null, source: "agent-worker", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "agent-worker task reconcile", coverage: "human-gated-required", action: "workerTaskReconcile", source: "agent-worker" },
+    { command: "agent-worker task retry", coverage: "human-gated-required", action: "workerTaskRetry", source: "agent-worker" },
+    { command: "agent-worker task draft-followup", coverage: "advanced", action: "workerTaskDraftFollowup", source: "agent-worker" },
+    { command: "agent-worker batch plan-ready", coverage: "model-callable", action: "workerBatchPlanReady", source: "agent-worker" },
+    { command: "agent-worker batch run-ready", coverage: "advanced", action: "workerBatchRunReady", source: "agent-worker" },
+    { command: "agent-worker pool mark-failed", coverage: "human-gated-required", action: "workerPoolMarkFailed", source: "agent-worker" },
+    { command: "agent-worker pool doctor", coverage: "model-callable", action: "workerPoolDoctor", source: "agent-worker" },
+    { command: "agent-worker pool migrate-state", coverage: "excluded", action: null, source: "agent-worker", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "agent-worker feature git advance-checkpoint", coverage: "excluded", action: null, source: "agent-worker", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "agent-worker report morning", coverage: "model-callable", action: "workerReportMorning", source: "agent-worker" },
+    { command: "agent-worker report metrics", coverage: "model-callable", action: "workerReportMetrics", source: "agent-worker" },
+    { command: "agent-worker observe serve", coverage: "excluded", action: null, source: "agent-worker", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "agent-worker observe snapshot", coverage: "excluded", action: null, source: "agent-worker", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "agent-worker console serve", coverage: "excluded", action: null, source: "agent-worker", exclusionReason: "Not exposed to Operator Chat in M5." },
+    { command: "agent-worker console doctor", coverage: "excluded", action: null, source: "agent-worker", exclusionReason: "Not exposed to Operator Chat in M5." },
+]);
+export function assertCoverageManifestConsistent() {
+    const actions = new Map(buildOperatorCapabilitiesDocument().actions.map((entry) => [entry.action, entry]));
+    const seen = new Set();
+    for (const entry of OPERATOR_COMMAND_COVERAGE) {
+        if (seen.has(entry.command))
+            throw new Error(`duplicate operator command coverage: ${entry.command}`);
+        seen.add(entry.command);
+        if (entry.action === null) {
+            if (entry.coverage !== "excluded")
+                throw new Error(`non-excluded command has no action: ${entry.command}`);
+            continue;
+        }
+        const capability = actions.get(entry.action);
+        if (!capability)
+            throw new Error(`coverage references unknown action: ${entry.action}`);
+        if (entry.coverage === "excluded" && capability.modelCallable !== "never")
+            throw new Error(`excluded action is model-callable: ${entry.action}`);
+        if (entry.coverage === "model-callable" && (capability.modelCallable !== "always" || capability.humanConfirmation !== "none"))
+            throw new Error(`invalid model-callable classification: ${entry.action}`);
+        if (entry.coverage === "human-gated-conditional" && (capability.modelCallable !== "always" || capability.humanConfirmation !== "conditional"))
+            throw new Error(`invalid conditional gate classification: ${entry.action}`);
+        if (entry.coverage === "human-gated-required" && (capability.modelCallable !== "prepare-only" || capability.humanConfirmation !== "required"))
+            throw new Error(`invalid required gate classification: ${entry.action}`);
+        if (entry.coverage === "advanced") {
+            const expected = capability.kind === "read" ? "always" : "never";
+            if (capability.modelCallable !== expected) {
+                throw new Error(`invalid advanced classification: ${entry.action} (expected modelCallable=${expected} for kind=${capability.kind})`);
+            }
+        }
+    }
+}
+assertCoverageManifestConsistent();