@kylecheng3146/agent-ops 0.5.3 → 0.6.0

package/dist/runtime/src/run/transport.js

@@ -0,0 +1,159 @@
+import { nativeProcessGroupAlive, signalNativeProcessGroup } from "./hosts/util.js";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { AgentOpsError } from "../fs/paths.js";
+const exec = promisify(execFile);
+export async function nativeProcessIdentity(pid) {
+    if (!Number.isSafeInteger(pid) || pid < 1)
+        return null;
+    try {
+        const { stdout } = await exec("ps", ["-p", String(pid), "-o", "lstart="], { maxBuffer: 8192 });
+        return stdout.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Adapt the native transport without activating a writer before its lease is saved. */
+export class NativeRunTransport {
+    transport;
+    repository;
+    onEvent;
+    processIdentity;
+    host;
+    #sessions = new Map();
+    constructor(transport, repository, onEvent = async () => { }, processIdentity = nativeProcessIdentity) {
+        this.transport = transport;
+        this.repository = repository;
+        this.onEvent = onEvent;
+        this.processIdentity = processIdentity;
+        this.host = transport.kind;
+    }
+    async start(input) {
+        if (input.worktree === null || input.contractHash === null)
+            throw new AgentOpsError("RUN_NATIVE_CONTEXT_REQUIRED", "Native workers require a worktree and current contract hash.");
+        const saved = (await this.repository.read(input.runId))?.workers.find(w => w.workerId === input.workerId);
+        const request = { runId: input.runId, workerId: input.workerId, generation: input.generation,
+            contractHash: input.contractHash, cwd: input.worktree,
+            env: { AGENT_OPS_SESSION_ID: input.ownerSessionId, AGENT_OPS_HOST: this.host,
+                CODEX_THREAD_ID: undefined, AGENT_OPS_AGENT_ID: undefined,
+                AGENT_OPS_RUN_ID: input.runId, AGENT_OPS_WORKER_ID: input.workerId,
+                AGENT_OPS_WORKER_GENERATION: String(input.generation) },
+            sessionId: saved?.nativeSessionId ?? input.ownerSessionId,
+            registerProcess: async (pid) => {
+                const identity = await this.processIdentity(pid);
+                if (identity === null)
+                    throw new AgentOpsError("RUN_PROCESS_IDENTITY_REQUIRED", "Cannot register provisional native process identity.");
+                await this.repository.mutate(input.runId, current => {
+                    const worker = current.workers.find(w => w.workerId === input.workerId);
+                    if (current.status !== "active" || current.disableRestart || worker?.status !== "starting" || worker.generation !== input.generation)
+                        throw new AgentOpsError("RUN_START_DISABLED", "Stop fenced provisional native registration.");
+                    return { ...current, workers: current.workers.map(w => w.workerId === input.workerId ? { ...w,
+                            nativeSessionId: saved?.nativeSessionId ?? input.ownerSessionId, processId: pid, processIdentity: identity } : w) };
+                });
+            } };
+        const incompleteCodex = saved?.nativeSessionId != null && this.host === "codex" && saved.nativeJobId === null;
+        if (incompleteCodex && (saved.nativeGoalState !== "inactive" || saved.stopIntent?.confirmedDeadAt == null))
+            throw new AgentOpsError("RUN_NATIVE_THREAD_REQUIRED", "Missing Codex thread identity needs confirmed provisional process death before fresh initialization.");
+        const handle = saved?.nativeSessionId == null || incompleteCodex ? await this.transport.start(request)
+            : await this.transport.resume(request, this.host === "codex" ? saved.nativeJobId : saved.nativeSessionId);
+        const identity = handle.processId === null ? null : await this.processIdentity(handle.processId);
+        if (identity === null) {
+            await this.transport.stop(handle, handle);
+            throw new AgentOpsError("RUN_PROCESS_IDENTITY_REQUIRED", "Cannot register an unidentified native process.");
+        }
+        const entry = { handle, observation: { nativeGoalState: "inactive",
+                processAlive: true, processIdentity: identity, stateDigest: null } };
+        this.#sessions.set(handle.sessionId, entry);
+        // Drain output immediately, but the host has no goal and cannot start a turn yet.
+        void this.consume(entry).catch(async () => {
+            entry.observation = { ...entry.observation, nativeGoalState: "unknown" };
+            await this.repository.appendEvent(handle.runId, { type: "diagnostic", code: "RUN_NATIVE_STREAM_FAILED",
+                workerId: handle.workerId, taskId: null, detail: "Native event stream failed; completion remains unproven." }).catch(() => { });
+        });
+        return { nativeSessionId: handle.sessionId, nativeJobId: handle.threadId, processId: handle.processId,
+            processIdentity: identity, instance: handle.nativeVersion };
+    }
+    async activateRegistered(runId, worker, objective) {
+        const current = await this.repository.read(runId);
+        const saved = current?.workers.find(w => w.workerId === worker.workerId);
+        const entry = worker.nativeSessionId === null ? undefined : this.#sessions.get(worker.nativeSessionId);
+        if (current?.status !== "active" || saved?.status !== "running" || saved.generation !== worker.generation ||
+            saved.nativeSessionId !== worker.nativeSessionId || saved.stopIntent !== null || entry === undefined)
+            throw new AgentOpsError("RUN_WORKER_STALE", "Native activation requires a saved current writer lease.");
+        await this.transport.activate(entry.handle, objective, entry.handle);
+    }
+    async inspect(input) {
+        const entry = this.#sessions.get(input.nativeSessionId);
+        const identity = input.processId === null ? null : await this.processIdentity(input.processId);
+        const groupAlive = input.processId !== null && process.platform !== "win32" && nativeProcessGroupAlive(input.processId);
+        const alive = identity !== null || groupAlive;
+        if (identity !== null && identity !== input.processIdentity)
+            throw new AgentOpsError("RUN_PROCESS_IDENTITY_CHANGED", "A native PID has been reused; preserve the worktree and reconcile ownership.");
+        return { ...(entry?.observation ?? { nativeGoalState: "unknown", stateDigest: null }),
+            processAlive: alive, processIdentity: identity };
+    }
+    async resume(_input) {
+        throw new AgentOpsError("RUN_RECONCILE_REQUIRED", "Resume requires a new fenced lease and persisted native identity before activation.");
+    }
+    async send(input) {
+        const entry = this.#sessions.get(input.nativeSessionId);
+        if (entry === undefined || entry.handle.generation !== input.generation)
+            throw new AgentOpsError("RUN_WORKER_STALE", "Cannot update an unowned native session.");
+        await this.transport.update(entry.handle, { ...entry.handle, objective: input.message });
+        entry.observation = { ...entry.observation, nativeGoalState: "active" };
+    }
+    async stop(input) {
+        const runId = input.runId ?? this.#sessions.get(input.nativeSessionId)?.handle.runId;
+        const state = runId === undefined ? null : await this.repository.read(runId);
+        const worker = state?.workers.find(w => w.nativeSessionId === input.nativeSessionId && w.generation === input.generation);
+        if (worker?.proofProcess != null) {
+            const proof = worker.proofProcess;
+            await this.stop({ ...input, nativeSessionId: "worker-proof:" + worker.workerId, nativeJobId: null, ...proof });
+            await this.repository.mutate(state.runId, current => ({ ...current, workers: current.workers.map(w => w.workerId === worker.workerId &&
+                    w.generation === input.generation && w.proofProcess?.processId === proof.processId ? { ...w, proofProcess: null } : w) }));
+        }
+        const entry = this.#sessions.get(input.nativeSessionId);
+        if (entry === undefined) {
+            const observation = await this.inspect(input);
+            if (!observation.processAlive)
+                return;
+            if (input.processId === null || observation.processIdentity === null || observation.processIdentity !== input.processIdentity)
+                throw new AgentOpsError("RUN_PROCESS_RECONCILE_REQUIRED", "Cannot identify surviving native descendants; takeover is refused.");
+            // A crash lost the in-memory transport, but the saved PID/start time still identifies this owned group.
+            const pid = input.processId;
+            await signalNativeProcessGroup(pid, "SIGTERM");
+            for (let i = 0; i < 30 && (await this.inspect(input)).processAlive; i++)
+                await new Promise(resolve => setTimeout(resolve, 100));
+            if ((await this.inspect(input)).processAlive) {
+                await signalNativeProcessGroup(pid, "SIGKILL");
+                for (let i = 0; i < 30 && (await this.inspect(input)).processAlive; i++)
+                    await new Promise(resolve => setTimeout(resolve, 100));
+            }
+            if ((await this.inspect(input)).processAlive)
+                throw new AgentOpsError("RUN_WRITER_STILL_ALIVE", "The registered process group has not stopped; takeover is refused.");
+            return;
+        }
+        if (entry.handle.generation !== input.generation)
+            throw new AgentOpsError("RUN_WORKER_STALE", "Cannot stop a different writer generation.");
+        await this.inspect(input);
+        await this.transport.stop(entry.handle, entry.handle);
+        entry.observation = { ...entry.observation, processAlive: false, nativeGoalState: "cleared" };
+    }
+    async consume(entry) {
+        for await (const event of this.transport.observe(entry.handle)) {
+            const state = await this.repository.read(event.runId);
+            const worker = state?.workers.find(w => w.workerId === event.workerId);
+            if (worker?.generation !== event.generation || worker.nativeSessionId !== entry.handle.sessionId || worker.status === "fenced") {
+                await this.repository.appendEvent(event.runId, { type: "diagnostic", code: "RUN_NATIVE_STALE_EVENT", workerId: event.workerId,
+                    taskId: null, detail: "Late native event rejected; no usage, authorization or delivery was accepted." });
+                continue;
+            }
+            entry.observation = { ...entry.observation,
+                nativeGoalState: ["active", "paused", "complete"].includes(event.nativeStatus)
+                    ? event.nativeStatus : "unknown",
+                ...(event.type === "closed" ? { processAlive: false } : {}) };
+            await this.onEvent(event);
+        }
+    }
+}

package/dist/runtime/src/run/types.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/src/run/usage.js

@@ -0,0 +1,81 @@
+import { extractUsage } from "../review/usage.js";
+import { recordUsage } from "./budget.js";
+import { sha256 } from "../fs/hash.js";
+import { readReviewReportArtifact, REVIEW_ATTESTATION_DIRECTORY } from "../review/attestation.js";
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+const plain = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const count = (v) => typeof v === "number" && Number.isSafeInteger(v) && v >= 0 ? v : null;
+function appendUsage(current, incoming) {
+    const usage = recordUsage(current.usage ?? [], incoming);
+    const total = (key) => usage.some(u => u[key] !== null)
+        ? usage.reduce((sum, u) => sum + (u[key] ?? 0), 0) : null;
+    return { ...current, usage, budget: { ...current.budget, usage: { ...current.budget.usage,
+                tokens: total("totalTokens"), usd: total("costUsd"), completeness: "partial", source: "native-and-review-epoch-ledger",
+                highWaterMark: total("totalTokens") ?? 0 } } };
+}
+/** Copies of a tree report charge each fresh reviewer session only once. */
+export async function recordReviewRunUsage(repository, runId, report) {
+    for (const attempt of Array.isArray(report.attempts) ? report.attempts : []) {
+        if (typeof attempt.sessionId !== "string" || !plain(attempt.metrics?.usage))
+            continue;
+        const value = attempt.metrics.usage;
+        await repository.mutate(runId, current => appendUsage(current, { source: "review",
+            epoch: sha256(attempt.target + ":" + attempt.sessionId), observedAt: report.createdAt,
+            inputTokens: value.inputTokens ?? null, outputTokens: value.outputTokens ?? null,
+            totalTokens: value.totalTokens ?? null, costUsd: value.costUsd ?? null, completeness: "partial" }));
+    }
+}
+export async function recordSavedReviewRunUsage(repository, runId, root) {
+    const state = await repository.read(runId);
+    if (state === null)
+        return;
+    let names;
+    try {
+        names = await readdir(join(root, REVIEW_ATTESTATION_DIRECTORY));
+    }
+    catch (cause) {
+        if (cause.code === "ENOENT")
+            return;
+        throw cause;
+    }
+    for (const name of names.filter(name => /^[a-f0-9]{64}\.[a-z][a-z0-9-]{0,127}\.reports\.json$/u.test(name))) {
+        const fingerprint = name.slice(0, 64);
+        const taskId = name.slice(65, -".reports.json".length);
+        const artifact = await readReviewReportArtifact(root, fingerprint, taskId);
+        if (artifact !== null && artifact.goalHash === state.goalHash && Date.parse(artifact.createdAt) >= Date.parse(state.createdAt))
+            await recordReviewRunUsage(repository, runId, artifact);
+    }
+}
+/** Only explicit native counters are consumed. Unknown cost never becomes zero. */
+export async function recordNativeRunUsage(repository, event) {
+    if (!plain(event.payload))
+        return;
+    const state = await repository.read(event.runId);
+    const worker = state?.workers.find(w => w.workerId === event.workerId);
+    if (state === null || state === undefined || worker === undefined || worker.generation !== event.generation || worker.nativeSessionId === null)
+        return;
+    let incoming;
+    const payload = plain(event.payload.params) ? event.payload.params : event.payload;
+    if (event.host === "claude" && event.payload.type === "result" && typeof event.payload.uuid === "string") {
+        const usage = extractUsage("claude", JSON.stringify(event.payload), "");
+        if (usage !== undefined)
+            incoming = { source: "claude", epoch: `${worker.workerId}:${worker.nativeSessionId}:${event.payload.uuid}`,
+                inputTokens: usage.inputTokens ?? null, outputTokens: usage.outputTokens ?? null, totalTokens: usage.totalTokens ?? null,
+                costUsd: usage.costUsd ?? null, completeness: "partial", observedAt: event.at };
+    }
+    else if (event.host === "codex" && plain(payload.tokenUsage) && plain(payload.tokenUsage.total)) {
+        const usage = payload.tokenUsage.total;
+        incoming = { source: "codex", epoch: `${worker.workerId}:${worker.nativeSessionId}:thread`, inputTokens: count(usage.inputTokens),
+            outputTokens: count(usage.outputTokens), totalTokens: count(usage.totalTokens), costUsd: null,
+            completeness: "partial", observedAt: event.at };
+    }
+    if (incoming === undefined)
+        return;
+    await repository.mutate(event.runId, current => {
+        const saved = current.workers.find(w => w.workerId === event.workerId);
+        if (saved?.generation !== event.generation || saved.nativeSessionId !== worker.nativeSessionId)
+            return current;
+        return appendUsage(current, incoming);
+    });
+}

package/dist/runtime/src/run/verification.js

@@ -0,0 +1,64 @@
+import { join } from "node:path";
+import { canonicalJson } from "../config/hash.js";
+import { sha256 } from "../fs/hash.js";
+import { AgentOpsError } from "../fs/paths.js";
+import { readPrivateFile, writePrivateFile } from "../security/permissions.js";
+import { redactSecrets } from "../security/redact.js";
+import { taskContractHash } from "../task/contract.js";
+import { FileEvidenceStore } from "../verify/evidence.js";
+import { deriveFailureObservation } from "./convergence.js";
+/** Preserve actual failed command reports, which are not completion evidence. */
+export async function recordRunVerification(repository, state, workerId, task, report) {
+    if (state.policyBinding === undefined)
+        return;
+    const worker = state.workers.find(w => w.workerId === workerId);
+    if (worker === undefined || task.task.id !== report.taskId)
+        throw new AgentOpsError("RUN_WORKER_STALE", "Verifier report has no current worker identity.");
+    const content = redactSecrets(canonicalJson({ schemaVersion: 1, report, taskContractHash: taskContractHash(task.task),
+        policyArtifactDigest: state.policyBinding.artifactDigest }));
+    const digest = sha256(content);
+    const path = join(state.commonDir, "agent-ops/runs", state.runId, "verification", digest + ".json");
+    await repository.mutate(state.runId, async (current) => {
+        const saved = current.workers.find(w => w.workerId === workerId);
+        if (current.status !== "active" || current.disableRestart || saved?.generation !== worker.generation ||
+            current.policyBinding?.artifactDigest !== state.policyBinding.artifactDigest)
+            throw new AgentOpsError("RUN_VERIFICATION_STALE", "Verifier observation belongs to a stale run generation or policy.");
+        await writePrivateFile(path, content, current.commonDir);
+        return { ...current, events: [...current.events, { id: "verify-" + digest, at: new Date().toISOString(), type: "diagnostic",
+                    code: "RUN_VERIFICATION_OBSERVED", workerId, taskId: report.taskId, detail: canonicalJson({ digest }) }].slice(-2000) };
+    });
+}
+/** Read current-contract observations; saved raw source fingerprints never identify failures. */
+export async function observeRunFailure(state, root, records, taskId, code, pendingPinIds) {
+    const results = new Map();
+    const acceptance = [];
+    const evidence = new FileEvidenceStore(root, root);
+    for (const record of records.filter(r => r.status !== "archived" && r.supersededBy === undefined)) {
+        const events = state.events.filter(e => e.code === "RUN_VERIFICATION_OBSERVED" && e.taskId === record.task.id).reverse();
+        for (const event of events) {
+            const { digest } = JSON.parse(event.detail);
+            if (typeof digest !== "string" || !/^[a-f0-9]{64}$/u.test(digest))
+                throw new AgentOpsError("RUN_VERIFICATION_CHANGED", "Verifier observation digest is invalid.");
+            const source = await readPrivateFile(join(state.commonDir, "agent-ops/runs", state.runId, "verification", digest + ".json"), state.commonDir);
+            if (source === null || sha256(source) !== digest)
+                throw new AgentOpsError("RUN_VERIFICATION_CHANGED", "Verifier observation is missing or changed.");
+            const saved = JSON.parse(source);
+            if (saved.taskContractHash !== taskContractHash(record.task) || saved.policyArtifactDigest !== state.policyBinding?.artifactDigest)
+                continue;
+            for (const result of saved.report.results)
+                results.set(record.task.id + ":" + result.commandId, { ...result, commandId: record.task.id + ":" + result.commandId });
+            for (const phase of saved.report.acceptance ?? []) {
+                const proof = await evidence.load(phase.reference);
+                const criterion = record.task.criteria.find(c => c.id === phase.criterionId);
+                if (proof?.acceptance === undefined || proof.taskContractHash !== taskContractHash(record.task) || criterion?.acceptance === undefined || criterion.acceptance.mode === "review-only")
+                    continue;
+                const bindings = criterion.acceptance.bindings.filter(b => b.runnerId === phase.runnerId);
+                acceptance.push({ ...phase, criterionId: record.task.id + ":" + phase.criterionId, checks: proof.acceptance.checks,
+                    requiredCheckIds: bindings.flatMap(b => b.checkIds), redCheckIds: bindings.flatMap(b => b.redCheckIds ?? []) });
+            }
+            break;
+        }
+    }
+    return deriveFailureObservation({ taskId, status: "FAIL", results: results.size === 0 && acceptance.length === 0 && pendingPinIds.length === 0
+            ? [{ commandId: code, required: true, status: "FAIL", failureClass: code }] : [...results.values()], acceptance }, { pendingPinIds });
+}

package/dist/runtime/src/run/worker-gate.js

@@ -0,0 +1,48 @@
+import { readWorktreeRecord } from "../parallel/service.js";
+function blocked(code, remedy) {
+    return { action: "block", status: "FAIL", code, remedy };
+}
+/**
+ * A worker may stop after its coordinator-issued handoff is fenced. This is a
+ * narrow local delivery gate: it does not complete the task, grant root Stop,
+ * or accept a native goal's `complete` status as proof.
+ */
+export async function validateWorkerStopHandoff(repository, input, recordReader = readWorktreeRecord) {
+    const record = await recordReader(input.root);
+    if (record === null || record.runId !== input.runId || record.workerId !== input.workerId ||
+        record.workerGeneration !== input.generation ||
+        (record.agentId !== undefined && input.agentId !== undefined && record.agentId !== input.agentId)) {
+        return blocked("RUN_WORKER_HANDOFF_UNREGISTERED", "This Stop is not a coordinator-registered run worker handoff. Preserve the task and use the normal completion gate.");
+    }
+    const state = await repository.read(input.runId);
+    if (state === null)
+        return blocked("RUN_WORKER_RUN_MISSING", "The run ledger is unavailable; do not stop a writer without reconciliation.");
+    const worker = state.workers.find((candidate) => candidate.workerId === input.workerId);
+    if (worker?.workerId === state.coordinatorId)
+        return null;
+    if (worker === undefined || worker.worktree !== input.root || worker.ownerSessionId !== record.ownerSessionId ||
+        (input.sessionId !== worker.ownerSessionId && input.sessionId !== worker.nativeSessionId) ||
+        (record.coordinatorId !== undefined && record.coordinatorId !== state.coordinatorId))
+        return blocked("RUN_WORKER_HANDOFF_UNREGISTERED", "The native actor does not match this registered child checkout.");
+    if (worker === undefined || worker.generation !== input.generation)
+        return blocked("RUN_WORKER_GENERATION_STALE", "The worker lease is stale; reconcile the run before stopping this session.");
+    const intent = worker.stopIntent;
+    if (intent === null || intent.reason !== "handoff" || intent.runId !== state.runId ||
+        intent.nativeSessionId !== worker.nativeSessionId || intent.generation !== input.generation || intent.workerId !== input.workerId ||
+        (input.deliveryDigest !== undefined && intent.deliveryDigest !== input.deliveryDigest) ||
+        (input.contractDigest !== undefined && intent.contractDigest !== input.contractDigest)) {
+        return blocked("RUN_WORKER_HANDOFF_REQUIRED", "Native completion is not final proof. Ask the coordinator to create a matching handoff intent first.");
+    }
+    if (intent.confirmedDeadAt === null && (worker.status !== "handing-off" || Date.parse(intent.expiresAt) <= (input.nowMs ?? Date.now()))) {
+        return blocked("RUN_WORKER_HANDOFF_PENDING", "A live child needs a current coordinator-issued handoff intent before Stop.");
+    }
+    if (!["handing-off", "fenced", "delivered", "stopped"].includes(worker.status))
+        return blocked("RUN_WORKER_HANDOFF_PENDING", "Stop requires a fenced handoff; native completion alone is insufficient.");
+    return {
+        action: "continue",
+        status: "PASS",
+        code: "RUN_WORKER_HANDOFF_ALLOWED",
+        decision: "allow",
+        remedy: "Local worker handoff accepted. The task remains active until the coordinator completes final verify, dual review, and receipt proof."
+    };
+}

package/dist/runtime/src/schema/acceptance.js

@@ -0,0 +1,91 @@
+const record = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const text = (v) => typeof v === "string" && v.trim().length > 0 && v.length <= 4096 && !v.includes("\0");
+const id = (v) => typeof v === "string" && /^[a-z][a-z0-9-]{0,127}$/u.test(v);
+const keys = (v, allowed) => Object.keys(v).every(k => allowed.includes(k));
+const dense = (v) => Array.isArray(v) &&
+    Array.from({ length: v.length }, (_, i) => Object.hasOwn(v, i)).every(Boolean);
+const strings = (v) => dense(v) && v.length <= 512 && v.every(text) && new Set(v).size === v.length;
+export const commitIdentity = (v) => typeof v === "string" && /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/u.test(v);
+export function acceptanceSourcePath(v) {
+    return text(v) && !v.startsWith("/") && !/[\\<>:"|?*\x00-\x1f\x7f]/u.test(v) &&
+        v.split("/").every(p => p !== "" && p !== "." && p !== ".." && !/[. ]$/u.test(p) &&
+            !/^(?:CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(?:\.|$)/iu.test(p) &&
+            ![".git", ".agent-ops"].includes(p.toLowerCase()));
+}
+export function materialPath(v) {
+    return acceptanceSourcePath(v) && !v.split("/").includes("node_modules") &&
+        !/^(?:dist|build|\.tmp)\//u.test(v) &&
+        !/^(?:package\.json|package-lock\.json|pnpm-lock\.yaml|yarn\.lock|Cargo\.(?:toml|lock)|pyproject\.toml)$/u.test(v);
+}
+export function acceptanceError(v) {
+    if (!record(v) || !keys(v, ["mode", "baselineCommit", "bindings", "reviewOnlyReason"]) ||
+        !["behavioral", "invariant", "review-only"].includes(String(v.mode)) ||
+        !commitIdentity(v.baselineCommit) || !dense(v.bindings) || v.bindings.length > 64)
+        return "Acceptance requires a mode, immutable commit SHA and bounded bindings.";
+    if (v.mode === "review-only")
+        return v.bindings.length === 0 && text(v.reviewOnlyReason)
+            ? undefined : "Review-only requires an explicit bounded reason and no mechanical bindings.";
+    if (v.reviewOnlyReason !== undefined)
+        return "Only review-only contracts carry a fallback reason.";
+    if (v.bindings.length === 0)
+        return "Mechanical acceptance requires a binding.";
+    const identities = new Set();
+    let red = 0;
+    for (const binding of v.bindings) {
+        if (!record(binding) || !keys(binding, ["runnerId", "checkIds", "redCheckIds", "materials"]) ||
+            !id(binding.runnerId) || !strings(binding.checkIds) || binding.checkIds.length === 0 ||
+            !dense(binding.materials) || binding.materials.length === 0 || binding.materials.length > 512)
+            return "Binding requires a runner, unique check IDs and explicit materials.";
+        if (binding.redCheckIds !== undefined &&
+            (!strings(binding.redCheckIds) || binding.redCheckIds.some(c => !binding.checkIds.includes(c))))
+            return "Red checks must be unique members of checkIds.";
+        red += binding.redCheckIds?.length ?? 0;
+        const paths = new Set();
+        for (const material of binding.materials) {
+            if (!record(material) || !keys(material, ["path", "role"]) || !materialPath(material.path) ||
+                !["test", "fixture", "helper"].includes(String(material.role)) || paths.has(material.path))
+                return "Materials must be unique safe relative test, fixture or helper files.";
+            paths.add(material.path);
+        }
+        for (const check of binding.checkIds) {
+            const identity = binding.runnerId + "\0" + check;
+            if (identities.has(identity))
+                return "Duplicate runner/check binding.";
+            identities.add(identity);
+        }
+    }
+    if (v.mode === "behavioral" && red === 0)
+        return "Behavioral acceptance requires at least one designated red check.";
+    if (v.mode === "invariant" && red !== 0)
+        return "Invariant acceptance does not designate red checks.";
+    return undefined;
+}
+export function runnerError(v) {
+    if (!record(v) || !keys(v, ["id", "command", "args", "cwd", "adapter", "timeoutMs", "setup", "build", "testBuild"]) ||
+        !id(v.id) || !text(v.command) || !dense(v.args) || v.args.length > 512 ||
+        !v.args.every(a => typeof a === "string" && !a.includes("\0") && a.length <= 4096 &&
+            (a === "{materials}" || !/[{}]/u.test(a))) ||
+        !(v.cwd === "." || materialPath(v.cwd)) ||
+        !["generic", "node", "jest", "vitest", "pytest", "rust"].includes(String(v.adapter)))
+        return "Acceptance runner requires fixed executable/argv, safe cwd and supported adapter.";
+    const timeout = (t) => t === undefined ||
+        (Number.isSafeInteger(t) && t > 0 && t <= 3_600_000);
+    if (!timeout(v.timeoutMs))
+        return "Runner timeout is invalid.";
+    for (const phase of ["setup", "build", "testBuild"]) {
+        if (v[phase] === undefined)
+            continue;
+        if (!dense(v[phase]) || v[phase].length > 64)
+            return "Runner setup/build must be bounded.";
+        for (const step of v[phase]) {
+            if (!record(step) || !keys(step, ["command", "args", "timeoutMs"]) || !text(step.command) ||
+                !dense(step.args) || step.args.length > 512 ||
+                !step.args.every(a => typeof a === "string" && !a.includes("\0") && a.length <= 4096) ||
+                !timeout(step.timeoutMs))
+                return "Setup/build steps require fixed command/argv and timeout.";
+        }
+    }
+    return undefined;
+}
+export function isAcceptance(v) { return acceptanceError(v) === undefined; }
+export function isAcceptanceRunner(v) { return runnerError(v) === undefined; }

package/dist/runtime/src/schema/validate.js

@@ -1,4 +1,5 @@
 import { CONFIG_SCHEMA_VERSION, EVIDENCE_SCHEMA_VERSION, MANIFEST_SCHEMA_VERSION, TASK_SCHEMA_VERSION } from "../contracts.js";
+import { acceptanceError, runnerError, commitIdentity } from "./acceptance.js";
 const ID_PATTERN = /^[a-z][a-z0-9-]{0,127}$/;
 const HASH_PATTERN = /^[a-f0-9]{64}$/;
 const WINDOWS_RESERVED_SEGMENT = /^(?:aux|com[1-9]|con|lpt[1-9]|nul|prn)(?:\..*)?$/i;
@@ -356,7 +357,7 @@ export function validateConfig(value) {
     if (!isRecord(root.verification)) {
         return failure("INVALID_TYPE", "$.verification", "verification must be an object.");
     }
-    const verificationUnknown = unknownFieldFailure(root.verification, ["commands"], "$.verification");
+    const verificationUnknown = unknownFieldFailure(root.verification, ["commands", "acceptanceRunners"], "$.verification");
     if (verificationUnknown !== undefined) {
         return verificationUnknown;
     }
@@ -374,6 +375,20 @@ export function validateConfig(value) {
         }
         commandIds.add(command.value.id);
     }
+    if (root.verification.acceptanceRunners !== undefined) {
+        if (!Array.isArray(root.verification.acceptanceRunners) || root.verification.acceptanceRunners.length > 128)
+            return failure("INVALID_ACCEPTANCE_RUNNER", "$.verification.acceptanceRunners", "Expected bounded runner array.");
+        const runnerIds = new Set();
+        for (const runner of root.verification.acceptanceRunners) {
+            const issue = runnerError(runner);
+            if (issue !== undefined)
+                return failure("INVALID_ACCEPTANCE_RUNNER", "$.verification.acceptanceRunners", issue);
+            const runnerId = runner.id;
+            if (runnerIds.has(runnerId) || commandIds.has(runnerId))
+                return failure("DUPLICATE_ID", "$.verification.acceptanceRunners", "Runner IDs must be unique and distinct from policy commands.");
+            runnerIds.add(runnerId);
+        }
+    }
     if (root.features.stopVerification.enabled === true &&
         root.verification.commands.length === 0) {
         return failure("STOP_VERIFICATION_COMMANDS_REQUIRED", "$.features.stopVerification.enabled", "Stop verification requires at least one verification command.");
@@ -498,11 +513,11 @@ function validateReviewRole(value, path) {
     }
     return success(value);
 }
-function validateCriterion(value, path) {
+export function validateCriterion(value, path) {
     if (!isRecord(value)) {
         return failure("INVALID_TYPE", path, "Expected a criterion object.");
     }
-    const unknown = unknownFieldFailure(value, ["description", "id", "verifierIds"], path);
+    const unknown = unknownFieldFailure(value, ["description", "id", "verifierIds", "acceptance", "finding"], path);
     if (unknown !== undefined) {
         return unknown;
     }
@@ -513,20 +528,43 @@ function validateCriterion(value, path) {
         return failure("INVALID_DESCRIPTION", `${path}.description`, "Criterion description is required.");
     }
     if (!isStringArray(value.verifierIds) ||
-        value.verifierIds.length === 0 ||
+        (value.verifierIds.length === 0 && value.acceptance === undefined) ||
         !value.verifierIds.every(isIdentifier)) {
         return failure("INVALID_VERIFIER_REFERENCE", `${path}.verifierIds`, "A criterion requires at least one valid verifier ID.");
     }
     if (!hasUniqueStrings(value.verifierIds)) {
         return failure("DUPLICATE_ID", `${path}.verifierIds`, "Criterion verifier IDs must be unique.");
     }
+    if (value.acceptance !== undefined) {
+        const issue = acceptanceError(value.acceptance);
+        if (issue !== undefined)
+            return failure("INVALID_ACCEPTANCE", path + ".acceptance", issue);
+    }
+    if (value.finding !== undefined) {
+        const f = value.finding;
+        if (!isRecord(f) || unknownFieldFailure(f, ["pinId", "reportDigest", "findingIndex", "candidateCommit", "criterionIds"], path + ".finding") !== undefined ||
+            typeof f.pinId !== "string" || !HASH_PATTERN.test(f.pinId) || typeof f.reportDigest !== "string" || !HASH_PATTERN.test(f.reportDigest) ||
+            !Number.isSafeInteger(f.findingIndex) || f.findingIndex < 0 || !commitIdentity(f.candidateCommit) ||
+            !isStringArray(f.criterionIds) || !f.criterionIds.every(id => typeof id === "string" && id.split(":").length <= 2 && id.split(":").every(isIdentifier)) || !hasUniqueStrings(f.criterionIds))
+            return failure("INVALID_FINDING_REFERENCE", path + ".finding", "Invalid immutable finding identity.");
+        if (value.acceptance === undefined || !isRecord(value.acceptance) || value.acceptance.mode === "invariant" ||
+            value.acceptance.baselineCommit !== f.candidateCommit)
+            return failure("INVALID_FINDING_BASELINE", path + ".finding", "A finding retains its failed-candidate baseline and behavioral or explicit review-only mode.");
+    }
     return success(value);
 }
 export function validateTask(value) {
-    const root = validateRoot(value, ["criteria", "id", "intent", "parentTaskId", "schemaVersion", "title"], TASK_SCHEMA_VERSION);
+    const root = validateRoot(value, ["criteria", "id", "intent", "goal", "contractRevision", "parentTaskId", "schemaVersion", "title"], isRecord(value) && value.schemaVersion === 1 ? 1 : TASK_SCHEMA_VERSION);
     if (isFailure(root)) {
         return root;
     }
+    if (root.contractRevision !== undefined && (!Number.isSafeInteger(root.contractRevision) || root.contractRevision < 0))
+        return failure("INVALID_CONTRACT_REVISION", "$.contractRevision", "Invalid contract revision.");
+    if (root.goal !== undefined && (!isNonEmptyString(root.goal) || Buffer.byteLength(root.goal, "utf8") > 65536))
+        return failure("INVALID_GOAL", "$.goal", "Goal must be non-empty and at most 64 KiB.");
+    if (root.schemaVersion === 1 && (root.goal !== undefined || root.contractRevision !== undefined ||
+        (Array.isArray(root.criteria) && root.criteria.some(c => isRecord(c) && (c.acceptance !== undefined || c.finding !== undefined)))))
+        return failure("WRONG_SCHEMA_VERSION", "$.schemaVersion", "Typed acceptance requires task schema 2.");
     if (!isIdentifier(root.id)) {
         return failure("INVALID_ID", "$.id", "Invalid task ID.");
     }
@@ -578,6 +616,13 @@ export function validateTaskAgainstConfig(taskValue, configValue) {
             return failure("UNKNOWN_VERIFIER_REFERENCE", `$.criteria[${criterionIndex}].verifierIds`, `Unknown verifier reference: ${unknownReference}`);
         }
     }
+    const runnerIds = new Set(config.value.verification.acceptanceRunners?.map(r => r.id) ?? []);
+    for (const criterion of task.value.criteria) {
+        for (const binding of criterion.acceptance?.bindings ?? []) {
+            if (!runnerIds.has(binding.runnerId))
+                return failure("UNKNOWN_ACCEPTANCE_RUNNER", "$.criteria", "Unknown acceptance runner: " + binding.runnerId);
+        }
+    }
     return task;
 }
 export function validateEvidence(value) {
@@ -597,11 +642,26 @@ export function validateEvidence(value) {
         "status",
         "taskId",
         "testCount",
-        "toolVersions"
-    ], isRecord(value) && value.schemaVersion === 2 ? 2 : EVIDENCE_SCHEMA_VERSION);
+        "toolVersions", "taskContractHash", "acceptance"
+    ], isRecord(value) && (value.schemaVersion === 2 || value.schemaVersion === 3) ? value.schemaVersion : EVIDENCE_SCHEMA_VERSION);
     if (isFailure(root)) {
         return root;
     }
+    if (root.taskContractHash !== undefined && (root.schemaVersion !== 4 || typeof root.taskContractHash !== "string" || !HASH_PATTERN.test(root.taskContractHash)))
+        return failure("INVALID_CONTRACT_HASH", "$.taskContractHash", "Contract evidence requires schema 4 and a digest.");
+    if (root.acceptance !== undefined) {
+        const a = root.acceptance;
+        if (root.schemaVersion !== 4 || !isRecord(a) || root.taskContractHash === undefined ||
+            unknownFieldFailure(a, ["criterionContractHash", "phase", "commit", "pairedCommit", "bindingHash", "materialDigest", "executionDigest", "executionArtifact", "checks"], "$.acceptance") !== undefined ||
+            !["baseline", "candidate"].includes(String(a.phase)) || !commitIdentity(a.commit) || !commitIdentity(a.pairedCommit) ||
+            ![a.criterionContractHash, a.bindingHash, a.materialDigest, a.executionDigest].every(h => typeof h === "string" && HASH_PATTERN.test(h)) ||
+            typeof a.executionArtifact !== "string" || !/^\.agent-ops\/tasks\/acceptance\/[a-f0-9]{64}\.json$/u.test(a.executionArtifact) ||
+            !Array.isArray(a.checks) || a.checks.length === 0 || a.checks.length > 512 ||
+            a.checks.some(c => !isRecord(c) || unknownFieldFailure(c, ["checkId", "status", "failureClass"], "$.acceptance.checks") !== undefined ||
+                !isNonEmptyString(c.checkId) || !["PASS", "FAIL", "UNKNOWN"].includes(String(c.status)) || !isNonEmptyString(c.failureClass)) ||
+            new Set(a.checks.map(c => c.checkId)).size !== a.checks.length)
+            return failure("INVALID_ACCEPTANCE_EVIDENCE", "$.acceptance", "Invalid phase/check evidence.");
+    }
     for (const field of ["taskId", "criterionId", "commandId"]) {
         if (!isIdentifier(root[field])) {
             return failure("INVALID_ID", `$.${field}`, `Invalid ${field}.`);