@tea-agent/loop-agent 0.16.25 → 0.17.0

package/dist/executors/shell-executor.js

@@ -1,6 +1,6 @@
 import { spawn } from "node:child_process";
 import { appendFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { readFile, writeFile } from "node:fs/promises";
+import { readFile, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { writeDagNodeTextArtifact } from "../infrastructure/harness/artifact-store.js";
 import { truncateOutput } from "../shared/output-truncation.js";
@@ -19,6 +19,8 @@ import { buildBackendTestCanonicalResultFromInitialShellSnippet, materializeBack
 import { backendTestSemanticReviewSchema, materializeBackendTestSemanticReview, } from "../workflows/dag/backend-test-semantic-review-contract.js";
 import { pathsChangedDuringRun, readGitStatusPorcelain, snapshotGitStatusPorcelain, validateShellWriteGuard, } from "./shell-write-guard.js";
 import { buildShellProcessEnv } from "./shell-verification.js";
+import { readRunState } from "../workflows/dag/run-store.js";
+import { readProjectGovernanceContext } from "../workflows/dag/project-governance-context.js";
 const DEFAULT_SHELL_TIMEOUT_MS = 300_000;
 const SUMMARY_STDOUT_MAX = 4_000;
 const SUMMARY_STDERR_MAX = 2_000;
@@ -52,6 +54,28 @@ export function resolveShellCwd(root, requestedCwd) {
     }
     return resolved;
 }
+async function resolveJsonArtifactSourceNodeId(input) {
+    const candidates = [
+        input.fromNodeId,
+        ...new Set((input.fallbackFromNodeIds ?? []).filter((nodeId) => nodeId !== input.fromNodeId)),
+    ];
+    for (const nodeId of candidates) {
+        try {
+            await stat(path.join(input.runDir, `${nodeId}.json`));
+            return nodeId;
+        }
+        catch (error) {
+            if (error &&
+                typeof error === "object" &&
+                "code" in error &&
+                error.code === "ENOENT") {
+                continue;
+            }
+            throw error;
+        }
+    }
+    throw new Error(`missing jsonArtifactGate node output (tried: ${candidates.join(", ")})`);
+}
 /** Preset commands first, then explicit shell.commands, then verdictGate (deterministic ordering). */
 export function resolveShellCommands(shell) {
     const fromPreset = shell.preset ? expandShellPreset(shell.preset) : [];
@@ -419,12 +443,30 @@ async function executeBackendTestPipeline(input, meta) {
             const selected = await executePipelineCommands(input, meta, [buildBackendTestCanonicalResultFromInitialShellSnippet()]);
             if (!selected.every((result) => result.ok))
                 throw new Error(selected.find((result) => !result.ok)?.stderr || "canonical result materialization failed");
+            const readNodeOutput = async (nodeId) => {
+                const record = JSON.parse(await readFile(path.join(meta.runDir, `${nodeId}.json`), "utf8"));
+                const text = record.assistantText?.trim() || record.stdout?.trim() || "";
+                if (!text)
+                    throw new Error(`missing auditable node output: ${nodeId}`);
+                return text;
+            };
+            const caseReview = await readNodeOutput("review-backend-cases-pi");
+            const reviewVerdicts = caseReview.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.startsWith("VERDICT:"));
+            if (reviewVerdicts.length !== 1 || !["VERDICT: pass", "VERDICT: request-revision"].includes(reviewVerdicts[0])) {
+                throw new Error("invalid advisory case review evidence: expected exactly one auditable VERDICT line");
+            }
+            const traceability = await readNodeOutput("backend-test-traceability-gate-shell");
+            if (!traceability.includes("Traceability gate: pass") || !/Matched symbols:\s*\d+/.test(traceability)) {
+                throw new Error("invalid traceability evidence: deterministic pass summary is missing");
+            }
             const contracts = path.join(meta.runDir, "contracts");
             const context = {
                 schemaVersion: 1,
                 result: JSON.parse(await readFile(path.join(contracts, "backend-test-result.json"), "utf8")),
                 manifest: JSON.parse(await readFile(path.join(contracts, "backend-test-case-manifest.json"), "utf8")),
                 classification: JSON.parse(await readFile(path.join(contracts, "backend-test-classification.json"), "utf8")),
+                caseReview: { verdict: reviewVerdicts[0].slice("VERDICT: ".length), evidence: caseReview },
+                traceability: { status: "pass", evidence: traceability },
             };
             outputs.push(`classification=${classification.path}`, ...selected.map((result) => result.stdout), JSON.stringify(context, null, 2));
         }
@@ -508,13 +550,20 @@ export async function executeDagShellNode(input, meta) {
         const started = Date.now();
         try {
             const gate = shell.jsonArtifactGate;
+            const sourceNodeId = gate.fallbackFromNodeIds?.length
+                ? await resolveJsonArtifactSourceNodeId({
+                    runDir: meta.runDir,
+                    fromNodeId: gate.fromNodeId,
+                    fallbackFromNodeIds: gate.fallbackFromNodeIds,
+                })
+                : gate.fromNodeId;
             let artifact;
             switch (gate.schemaId) {
                 case "backend-test-analysis-v1":
                 case "backend-test-analysis-v2":
                     artifact = await materializeBackendTestAnalysisContract({
                         runDir: meta.runDir,
-                        fromNodeId: gate.fromNodeId,
+                        fromNodeId: sourceNodeId,
                         artifactName: gate.artifactName,
                         outputDir: gate.outputDir,
                         sourceBinding: meta.spec.sourceBinding,
@@ -523,7 +572,7 @@ export async function executeDagShellNode(input, meta) {
                 case "backend-test-execution-v1":
                     artifact = await materializeBackendTestExecutionContract({
                         runDir: meta.runDir,
-                        fromNodeId: gate.fromNodeId,
+                        fromNodeId: sourceNodeId,
                         artifactName: gate.artifactName,
                         outputDir: gate.outputDir,
                     });
@@ -531,7 +580,7 @@ export async function executeDagShellNode(input, meta) {
                 case "backend-test-result-v1":
                     artifact = await materializeBackendTestResultFromRunDir({
                         runDir: meta.runDir,
-                        fromNodeId: gate.fromNodeId,
+                        fromNodeId: sourceNodeId,
                         artifactName: gate.artifactName,
                         outputDir: gate.outputDir,
                         junitRelativePath: gate.junitRelativePath,
@@ -540,7 +589,7 @@ export async function executeDagShellNode(input, meta) {
                 case "backend-test-classification-v1":
                     artifact = await materializeBackendTestClassification({
                         runDir: meta.runDir,
-                        fromNodeId: gate.fromNodeId,
+                        fromNodeId: sourceNodeId,
                         artifactName: gate.artifactName,
                         outputDir: gate.outputDir,
                     });
@@ -548,7 +597,7 @@ export async function executeDagShellNode(input, meta) {
                 case "backend-test-semantic-review-v1":
                     artifact = await materializeBackendTestSemanticReview({
                         runDir: meta.runDir,
-                        fromNodeId: gate.fromNodeId,
+                        fromNodeId: sourceNodeId,
                         artifactName: gate.artifactName,
                         outputDir: gate.outputDir,
                     });
@@ -556,7 +605,7 @@ export async function executeDagShellNode(input, meta) {
                 case "backend-test-case-manifest-v1":
                     artifact = await materializeBackendTestCaseManifest({
                         runDir: meta.runDir,
-                        fromNodeId: gate.fromNodeId,
+                        fromNodeId: sourceNodeId,
                         artifactName: gate.artifactName,
                         outputDir: gate.outputDir,
                         sourceBinding: meta.spec.sourceBinding,
@@ -565,7 +614,7 @@ export async function executeDagShellNode(input, meta) {
                 case "frontend-implementation-contract-v1":
                     artifact = await materializeFrontendImplementationContract({
                         runDir: meta.runDir,
-                        fromNodeId: gate.fromNodeId,
+                        fromNodeId: sourceNodeId,
                         artifactName: gate.artifactName,
                         outputDir: gate.outputDir,
                         sourceBinding: meta.spec.sourceBinding,
@@ -733,6 +782,34 @@ export async function executeDagShellNode(input, meta) {
             };
         }
     }
+    if (shell?.projectGovernanceGate) {
+        const started = Date.now();
+        try {
+            const state = await readRunState(meta.runDir);
+            if (!state.projectGovernanceContextRef) {
+                throw new Error("project governance gate requires projectGovernanceContextRef in run state");
+            }
+            const context = await readProjectGovernanceContext(meta.runDir, state.projectGovernanceContextRef, { expectedRunId: meta.runId });
+            if (!context.applicable) {
+                return {
+                    ok: true,
+                    stdout: "Project governance gate: not applicable for this writer changeset.",
+                    stderr: "",
+                    failureCategory: "success",
+                    durationMs: Date.now() - started,
+                };
+            }
+        }
+        catch (error) {
+            return {
+                ok: false,
+                stdout: "",
+                stderr: error instanceof Error ? error.message : String(error),
+                failureCategory: "invalid-output",
+                durationMs: Date.now() - started,
+            };
+        }
+    }
     const commands = shell ? resolveShellCommands(shell) : [];
     if (!shell || commands.length === 0) {
         throw new Error(`shell task ${input.task.id} requires shell.preset, shell.verdictGate, and/or non-empty shell.commands`);

package/dist/executors/shell-presets.js

@@ -60,12 +60,25 @@ export function buildVerdictGateShellCommand(gate) {
 export function buildRequirementCoverageGateShellCommand(gate) {
     const label = gate.label ?? "requirement coverage";
     const requiredJson = escapeShellSingleQuoted(JSON.stringify(gate.requiredIds.map((id) => id.toUpperCase())));
-    const fileArgs = gate.fromNodeIds.map((nodeId) => `"\${HARNESS_DAG_RUN_DIR}/${nodeId}.json"`).join(" ");
+    const sourceConfig = {
+        primary: gate.fromNodeIds,
+        fallback: [
+            ...new Set((gate.fallbackFromNodeIds ?? []).filter((nodeId) => !gate.fromNodeIds.includes(nodeId))),
+        ],
+    };
     const program = [
         'const fs=require("fs");',
+        'const path=require("path");',
         "const required=JSON.parse(process.argv[1]);",
+        `const sources=${JSON.stringify(sourceConfig)};`,
+        "let files=sources.primary.map((id)=>path.join(process.env.HARNESS_DAG_RUN_DIR,id+'.json'));",
+        "if(sources.fallback.length){",
+        " files=[]; const candidates=[sources.primary[0],...sources.fallback];",
+        " for(const id of candidates){const file=path.join(process.env.HARNESS_DAG_RUN_DIR,id+'.json'); try{fs.statSync(file);files=[file];break;}catch(error){if(error&&error.code==='ENOENT')continue;throw error;}}",
+        ` if(!files.length){console.error(${JSON.stringify(`${label} gate blocked: missing node output (tried: `)}+[sources.primary[0],...sources.fallback].join(', ')+')');process.exit(1);}`,
+        "}",
         "let text='';",
-        "for(const file of process.argv.slice(2)){",
+        "for(const file of files){",
         " if(!fs.existsSync(file)){console.error('missing requirement coverage node output: '+file);process.exit(1);}",
         " const raw=JSON.parse(fs.readFileSync(file,'utf8')); text+='\\n'+String(raw.assistantText ?? raw.stdout ?? '');",
         "}",
@@ -74,5 +87,5 @@ export function buildRequirementCoverageGateShellCommand(gate) {
         `if(missing.length){console.error(${JSON.stringify(`${label} gate blocked: missing `)}+missing.join(', '));process.exit(1);}`,
         `console.log(${JSON.stringify(`${label} gate passed: `)}+required.join(', '));`,
     ].join("");
-    return `test -n "\${HARNESS_DAG_RUN_DIR:-}" || { echo "missing HARNESS_DAG_RUN_DIR for ${label} gate" >&2; exit 1; }; node -e '${escapeShellSingleQuoted(program)}' '${requiredJson}' ${fileArgs}`;
+    return `test -n "\${HARNESS_DAG_RUN_DIR:-}" || { echo "missing HARNESS_DAG_RUN_DIR for ${label} gate" >&2; exit 1; }; node -e '${escapeShellSingleQuoted(program)}' '${requiredJson}'`;
 }

package/dist/executors/shell-write-guard.js

@@ -1,5 +1,16 @@
 import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { lstat, readlink } from "node:fs/promises";
+import path from "node:path";
 import { pathMatchesPattern } from "../shared/git-progress.js";
+async function sha256File(filePath) {
+    const hash = createHash("sha256");
+    for await (const chunk of createReadStream(filePath)) {
+        hash.update(chunk);
+    }
+    return hash.digest("hex");
+}
 export function snapshotGitStatusPorcelain(porcelain) {
     const snapshot = new Map();
     for (const line of porcelain.split("\n")) {
@@ -14,11 +25,15 @@ export function snapshotGitStatusPorcelain(porcelain) {
     }
     return snapshot;
 }
-export function pathsChangedDuringRun(before, after) {
+export function pathsChangedDuringRun(before, after, beforeFingerprints, afterFingerprints) {
     const changed = new Set();
     for (const [filePath, afterCode] of after) {
         const beforeCode = before.get(filePath);
-        if (beforeCode === undefined || beforeCode !== afterCode) {
+        if (beforeCode === undefined ||
+            beforeCode !== afterCode ||
+            (beforeFingerprints !== undefined &&
+                afterFingerprints !== undefined &&
+                beforeFingerprints.get(filePath) !== afterFingerprints.get(filePath))) {
             changed.add(filePath);
         }
     }
@@ -29,6 +44,53 @@ export function pathsChangedDuringRun(before, after) {
     }
     return Array.from(changed).sort();
 }
+/**
+ * Capture content-aware fingerprints for every path already present in a
+ * porcelain snapshot. Status codes alone cannot detect a writer editing a file
+ * that was `M` or `??` before the node and remains so afterwards.
+ *
+ * Symlinks are hashed by link target without following them, keeping the
+ * snapshot repository-contained. Missing paths and non-files receive stable
+ * sentinels so deletions and type changes remain observable.
+ */
+export async function snapshotGitStatusPathFingerprints(cwd, status) {
+    const root = path.resolve(cwd);
+    const entries = await Promise.all([...status.keys()].map(async (filePath) => {
+        const candidate = path.resolve(root, filePath);
+        const relative = path.relative(root, candidate);
+        if (relative.startsWith("..") ||
+            path.isAbsolute(relative)) {
+            return [filePath, "outside-repository"];
+        }
+        try {
+            const info = await lstat(candidate);
+            if (info.isSymbolicLink()) {
+                const target = await readlink(candidate);
+                return [
+                    filePath,
+                    `symlink:${createHash("sha256").update(target).digest("hex")}`,
+                ];
+            }
+            if (info.isFile()) {
+                return [
+                    filePath,
+                    `file:${await sha256File(candidate)}`,
+                ];
+            }
+            return [
+                filePath,
+                `other:${info.mode}:${info.size}:${info.mtimeMs}`,
+            ];
+        }
+        catch (error) {
+            const code = error && typeof error === "object" && "code" in error
+                ? String(error.code)
+                : "unknown";
+            return [filePath, `unreadable:${code}`];
+        }
+    }));
+    return new Map(entries);
+}
 const DAG_RUNS_PREFIX = ".harness/dag-runs/";
 /**
  * Ephemeral interpreter/tool caches that writers may create while drafting tests.

package/dist/shared/operator/capabilities.js

@@ -0,0 +1,255 @@
+import { OPERATOR_ERROR_CODES_V1, OPERATOR_OUTCOMES_V1 } from "./registry.js";
+/** Shared constants so dag + dagSpecVersions cannot diverge. */
+const DAG_SPEC_SUPPORTED_PARSE = [1, 2, 3, 4];
+const DAG_SPEC_NEW_WRITER_DEFAULT = 4;
+const DAG_SPEC_HISTORICAL_TERMINAL_READ_ONLY = [1, 2, 3];
+const TASK_CONTRACT_BINDING_SCHEMA_VERSION = 1;
+const REQUIRES_TASK_CONTRACT_BINDING = true;
+const COMMON_MUTATION_ERRORS = [
+    "INVALID_INPUT",
+    "REQUEST_ID_REUSE_CONFLICT",
+    "REVISION_CONFLICT",
+    "OBSERVED_HASH_CONFLICT",
+    "LEASE_HELD",
+    "TRANSACTION_INCOMPLETE",
+    "NOT_FOUND",
+];
+export function buildOperatorCapabilitiesDocument() {
+    const actions = [
+        {
+            action: "operatorCapabilities",
+            cli: "loop-agent operator capabilities --json",
+            kind: "read",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: ["UNSUPPORTED_SCHEMA_VERSION", "INVALID_INPUT"],
+            description: "Publish action/schema/error registry for Console negotiation.",
+        },
+        {
+            action: "contractShow",
+            cli: "loop-agent task contract show <taskId> --json",
+            kind: "read",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: ["NOT_FOUND", "INVALID_INPUT"],
+            description: "Return TaskContractStateV1 + observed hashes.",
+        },
+        {
+            action: "contractValidate",
+            cli: "loop-agent task contract validate --task <id> --input <path> --json",
+            kind: "read",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: ["INVALID_INPUT", "NOT_FOUND", "PATH_OUTSIDE_REPO"],
+            description: "Schema/path/traceability validation for a Draft (read-only).",
+        },
+        {
+            action: "contractDiff",
+            cli: "loop-agent task contract diff --task <id> --input <path> --json",
+            kind: "read",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: ["INVALID_INPUT", "NOT_FOUND", "PATH_OUTSIDE_REPO"],
+            description: "Risk-classified diff against current managed/legacy state.",
+        },
+        {
+            action: "contractApply",
+            cli: "loop-agent task contract apply --task <id> --input <path> --expected-revision <n> --expected-observed-hash <sha256> --request-id <id> --request-payload-sha256 <sha256> --json",
+            kind: "mutation",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: [...COMMON_MUTATION_ERRORS, "EXTERNALLY_MODIFIED"],
+            description: "Journaled apply of Draft to canonical task facts.",
+        },
+        {
+            action: "newTask",
+            cli: "loop-agent new-task <id> <title> --json",
+            kind: "mutation",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: [...COMMON_MUTATION_ERRORS],
+            description: "Create a new task harness skeleton via sibling CLI.",
+        },
+        {
+            action: "importPrd",
+            cli: "loop-agent import-prd <id> --file <server-staged-path> --json",
+            kind: "mutation",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: [...COMMON_MUTATION_ERRORS, "PATH_OUTSIDE_REPO"],
+            description: "Import immutable PRD/source reference via sibling CLI (server-staged file).",
+        },
+        {
+            action: "sourceInstructions",
+            cli: "loop-agent instructions source --task <id> --json",
+            kind: "read",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: ["NOT_FOUND", "INVALID_INPUT"],
+            description: "Read source instruction contract for a task.",
+        },
+        {
+            action: "contractDraftSave",
+            cli: "console application-data draft save (non-canonical)",
+            kind: "mutation",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: ["INVALID_INPUT"],
+            description: "Save TaskContractDraftV1 to Console application data only (not repo .harness).",
+        },
+        {
+            action: "prepareDagConfirmation",
+            cli: "console aggregate confirmation receipt (server-side)",
+            kind: "read",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: [
+                "INVALID_INPUT",
+                "BINDING_DRIFT",
+                "HUMAN_CONFIRMATION_REQUIRED",
+            ],
+            description: "Prepare server-side DagConfirmationV1 receipt for human challenge.",
+        },
+        {
+            action: "confirmDagConfirmation",
+            cli: "console aggregate confirmation human challenge (server-side)",
+            kind: "mutation",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: [
+                "INVALID_INPUT",
+                "NOT_FOUND",
+                "CONFIRMATION_STALE",
+                "CONFIRMATION_EXPIRED",
+                "CONFIRMATION_CONSUMED",
+                "HUMAN_CONFIRMATION_REQUIRED",
+            ],
+            description: "Human challenge confirm of DagConfirmationV1 using server-derived current bindings.",
+        },
+        {
+            action: "observeLink",
+            cli: "console observe deep-link builder (read-only navigation)",
+            kind: "read",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: ["INVALID_INPUT"],
+            description: "Build Observe deep link from stable object identity.",
+        },
+        {
+            action: "inspect",
+            cli: "loop-agent inspect --json",
+            kind: "read",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: ["INVALID_INPUT"],
+            description: "Repo preflight (registry entry; envelope migration follow-up).",
+        },
+        {
+            action: "doctor",
+            cli: "loop-agent doctor --json",
+            kind: "read",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: ["INVALID_INPUT", "OPERATION_NEEDS_RECONCILE"],
+            description: "Repo doctor (registry entry; envelope migration follow-up).",
+        },
+        {
+            action: "status",
+            cli: "loop-agent status <taskId> --json",
+            kind: "read",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: ["NOT_FOUND", "INVALID_INPUT"],
+            description: "Task status (registry entry).",
+        },
+        {
+            action: "spineCheck",
+            cli: "loop-agent spine audit <taskId> --json",
+            kind: "read",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: ["NOT_FOUND", "INVALID_INPUT"],
+            description: "Spine audit (registry entry).",
+        },
+        {
+            action: "dagRunTask",
+            cli: "loop-agent dag run-task <taskId> --profile auto",
+            kind: "long-running",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: [
+                "NOT_MANAGED",
+                "BINDING_DRIFT",
+                "EXTERNALLY_MODIFIED",
+                "INVALID_INPUT",
+            ],
+            description: "Generate DagSpec v4 with taskContractBinding (managed required).",
+        },
+        {
+            action: "dagValidate",
+            cli: "loop-agent dag validate --dag <path> --json",
+            kind: "read",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: ["INVALID_INPUT", "BINDING_DRIFT"],
+            description: "Validate DAG including taskContractBinding drift checks.",
+        },
+        {
+            action: "runDag",
+            cli: "loop-agent run-dag --dag <path>",
+            kind: "long-running",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: [
+                "BINDING_DRIFT",
+                "CONTROLLER_MISMATCH",
+                "INVALID_INPUT",
+            ],
+            description: "Execute reviewed DAG; revalidate binding before writer start.",
+        },
+    ];
+    return {
+        schemaVersion: 1,
+        envelopeSchemaVersion: 1,
+        outcomes: OPERATOR_OUTCOMES_V1,
+        errorCodes: OPERATOR_ERROR_CODES_V1,
+        dagSpecVersions: {
+            supportedParse: DAG_SPEC_SUPPORTED_PARSE,
+            newWriterDefault: DAG_SPEC_NEW_WRITER_DEFAULT,
+            historicalTerminalReadOnly: DAG_SPEC_HISTORICAL_TERMINAL_READ_ONLY,
+        },
+        dag: {
+            supportedSpecVersions: DAG_SPEC_SUPPORTED_PARSE,
+            generatedSpecVersion: DAG_SPEC_NEW_WRITER_DEFAULT,
+            requiresTaskContractBinding: REQUIRES_TASK_CONTRACT_BINDING,
+            taskContractBindingSchemaVersion: TASK_CONTRACT_BINDING_SCHEMA_VERSION,
+        },
+        taskContract: {
+            draftSchemaVersion: 1,
+            refSchemaVersion: 1,
+            projectionVersion: 1,
+            canonicalizerVersion: 1,
+            taskConfigSchemaVersion: 1,
+        },
+        actions,
+    };
+}

package/dist/shared/operator/envelope.js

@@ -0,0 +1,59 @@
+export function buildOperatorResult(input) {
+    const envelope = {
+        schemaVersion: 1,
+        command: input.command,
+        ok: input.ok,
+        outcome: input.outcome,
+        warnings: input.warnings ?? [],
+    };
+    if (input.result !== undefined) {
+        envelope.result = input.result;
+    }
+    if (input.error !== undefined) {
+        envelope.error = input.error;
+    }
+    return envelope;
+}
+export function operatorSucceeded(command, result, warnings = []) {
+    return buildOperatorResult({
+        command,
+        ok: true,
+        outcome: "succeeded",
+        result,
+        warnings,
+    });
+}
+export function operatorFailed(input) {
+    return buildOperatorResult({
+        command: input.command,
+        ok: false,
+        outcome: input.outcome,
+        warnings: input.warnings ?? [],
+        error: {
+            code: input.code,
+            message: input.message,
+            ...(input.details ? { details: input.details } : {}),
+        },
+    });
+}
+/** Write a single complete JSON document to stdout (never JSONL). */
+export function writeOperatorJson(result) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+export function processExitCodeForOutcome(outcome) {
+    switch (outcome) {
+        case "succeeded":
+            return 0;
+        case "not-found":
+            return 2;
+        case "invalid":
+        case "rejected":
+        case "conflict":
+        case "blocked":
+        case "timed-out":
+        case "needs-reconcile":
+            return 1;
+        default:
+            return 1;
+    }
+}

package/dist/shared/operator/index.js

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./registry.js";
+export * from "./envelope.js";
+export * from "./capabilities.js";

package/dist/shared/operator/registry.js

@@ -0,0 +1,38 @@
+export const OPERATOR_OUTCOMES_V1 = [
+    "succeeded",
+    "rejected",
+    "conflict",
+    "blocked",
+    "not-found",
+    "invalid",
+    "timed-out",
+    "needs-reconcile",
+];
+export const OPERATOR_ERROR_CODES_V1 = [
+    "UNSUPPORTED_SCHEMA_VERSION",
+    "CAPABILITY_MISMATCH",
+    "INVALID_INPUT",
+    "PATH_OUTSIDE_REPO",
+    "REQUEST_ID_REUSE_CONFLICT",
+    "REVISION_CONFLICT",
+    "OBSERVED_HASH_CONFLICT",
+    "LEASE_HELD",
+    "TRANSACTION_INCOMPLETE",
+    "BINDING_DRIFT",
+    "CONTROLLER_MISMATCH",
+    "HUMAN_CONFIRMATION_REQUIRED",
+    "OPERATION_NEEDS_RECONCILE",
+    "EVENT_CURSOR_EXPIRED",
+    "NOT_FOUND",
+    "NOT_MANAGED",
+    "EXTERNALLY_MODIFIED",
+    "INTERNAL_ERROR",
+    "PI_SETUP_REQUIRED",
+    "CONFIRMATION_EXPIRED",
+    "CONFIRMATION_STALE",
+    "CONFIRMATION_CONSUMED",
+];
+export const OPERATOR_ERROR_CODE_SET = new Set(OPERATOR_ERROR_CODES_V1);
+export function isOperatorErrorCode(code) {
+    return OPERATOR_ERROR_CODE_SET.has(code);
+}

package/dist/shared/operator/types.js

@@ -0,0 +1,5 @@
+/**
+ * Operator machine envelope types (design §5.1).
+ * Physical path: src/shared/operator (allowed via src/shared/**).
+ */
+export {};