@kylecheng3146/agent-ops 0.5.2 → 0.6.0

package/dist/runtime/src/verify/adapters/rust.js

@@ -0,0 +1,84 @@
+import { parseJsonDocument, parseJsonLines, stableCheckId } from "../acceptance-protocol.js";
+import { attempts, lower, object, result, run, string, terminal, terminalEvidence } from "./shared.js";
+function inputEvents(input) {
+    if (Array.isArray(input))
+        return { events: input, diagnostics: [] };
+    if (typeof input !== "string") {
+        const value = object(input);
+        return value === undefined
+            ? { events: [], diagnostics: ["malformed-output"] }
+            : { events: [value], diagnostics: [] };
+    }
+    const document = parseJsonDocument(input);
+    if (Array.isArray(document))
+        return { events: document, diagnostics: [] };
+    if (object(document) !== undefined)
+        return { events: [document], diagnostics: [] };
+    const lines = parseJsonLines(input);
+    return {
+        events: lines.values,
+        diagnostics: lines.invalidLines.map((line) => `invalid-json-line:${line}`)
+    };
+}
+function status(value) {
+    const normalized = lower(value);
+    if (normalized === "pass" || normalized === "passed" || normalized === "ok")
+        return "PASS";
+    if (normalized === "fail" || normalized === "failed")
+        return "FAIL";
+    return "UNKNOWN";
+}
+/**
+ * Collect the stdlib harness' JSON-lines output. Native libtest text without
+ * this explicit protocol is intentionally unsupported instead of guessed.
+ */
+export function collectRustAcceptance(input, options) {
+    const parsed = inputEvents(input);
+    const results = [];
+    const diagnostics = [...parsed.diagnostics];
+    let completed = false;
+    let completionEvidence = [];
+    for (const raw of parsed.events) {
+        const value = object(raw);
+        if (value === undefined) {
+            diagnostics.push("malformed-event");
+            continue;
+        }
+        const type = lower(value.type ?? value.event ?? value.kind);
+        if (terminal(value) || type === "completed" || type === "complete") {
+            completed = true;
+            completionEvidence = [terminalEvidence(value, options.executionId)];
+            continue;
+        }
+        if (type !== "check" && type !== "assertion" && type !== "result") {
+            diagnostics.push(`unsupported-event:${type ?? "unknown"}`);
+            continue;
+        }
+        const rawId = string(value.checkId ?? value.testId ?? value.name);
+        if (rawId === undefined) {
+            diagnostics.push("missing-check-id");
+            continue;
+        }
+        let checkId;
+        try {
+            checkId = stableCheckId([rawId]);
+        }
+        catch {
+            diagnostics.push("missing-check-id");
+            continue;
+        }
+        const checkStatus = status(value.status ?? value.outcome ?? value.state);
+        const failureClass = lower(value.failureClass ?? value.failureKind) ??
+            (checkStatus === "PASS" ? "none" : checkStatus === "FAIL" ? "infrastructure-error" : "unsupported-output");
+        const evidence = Array.isArray(value.evidence)
+            ? value.evidence.filter((item) => typeof item === "string")
+            : [`rust:${checkId}`];
+        try {
+            results.push(result(options, "rust-harness", checkId, checkStatus, evidence, failureClass, attempts(value.attempts, null)));
+        }
+        catch {
+            diagnostics.push(`malformed-result:${checkId}`);
+        }
+    }
+    return run(options, "rust-harness", results, completed, completionEvidence, diagnostics);
+}

package/dist/runtime/src/verify/adapters/shared.js

@@ -0,0 +1,82 @@
+import { ACCEPTANCE_FAILURE, makeAcceptanceCheck, makeAcceptanceRun } from "../acceptance-protocol.js";
+export function object(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+export function string(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+export function number(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) ? value : undefined;
+}
+export function array(value) {
+    return Array.isArray(value) ? value : undefined;
+}
+export function attempts(value, fallback = 1) {
+    const parsed = number(value);
+    return parsed === undefined ? fallback : parsed;
+}
+export function result(options, framework, checkId, status, evidence, failureClass = status === "PASS" ? "none" : ACCEPTANCE_FAILURE.infrastructure, attemptCount = 1) {
+    return makeAcceptanceCheck({
+        executionId: options.executionId,
+        framework,
+        frameworkVersion: options.frameworkVersion,
+        checkId,
+        phase: options.phase,
+        status,
+        failureClass,
+        attempts: attemptCount,
+        evidence
+    });
+}
+export function unknownResult(options, framework, checkId, failureClass, evidence = ["adapter:unknown"], attemptCount = 1) {
+    return result(options, framework, checkId, "UNKNOWN", evidence, failureClass, attemptCount);
+}
+export function run(options, framework, results, completed, completionEvidence, diagnostics = []) {
+    return makeAcceptanceRun({
+        executionId: options.executionId,
+        framework,
+        frameworkVersion: options.frameworkVersion,
+        phase: options.phase,
+        results,
+        completed,
+        completionEvidence,
+        diagnostics
+    });
+}
+export function lower(value) {
+    const text = string(value);
+    return text?.toLowerCase();
+}
+export function hasRetry(value) {
+    if (value.retry === true || value.retried === true)
+        return true;
+    const retryCount = number(value.retryCount);
+    if (retryCount !== undefined && retryCount > 0)
+        return true;
+    const repeatCount = number(value.repeatCount);
+    if (repeatCount !== undefined && repeatCount > 0)
+        return true;
+    const rerun = number(value.rerun);
+    if (rerun !== undefined && rerun > 0)
+        return true;
+    const invocations = number(value.invocations);
+    if (invocations !== undefined && invocations > 1)
+        return true;
+    if (Array.isArray(value.retryReasons) && value.retryReasons.length > 0)
+        return true;
+    const attemptsValue = number(value.attempts);
+    return attemptsValue !== undefined && attemptsValue > 1;
+}
+export function terminal(value) {
+    if (value.completed === true || value.complete === true || value.terminal === true)
+        return true;
+    const type = lower(value.type ?? value.event);
+    return type === "complete" || type === "completed" || type === "finished" ||
+        type === "session-finished" || type === "run-complete";
+}
+export function terminalEvidence(value, fallback) {
+    const id = string(value.executionId) ?? string(value.id) ?? fallback;
+    return `terminal:${id}`;
+}

package/dist/runtime/src/verify/adapters/vitest.js

@@ -0,0 +1,218 @@
+import { makeAcceptanceCheck, makeAcceptanceRun, parseJsonDocument, parseJsonLines, stableCheckId } from "../acceptance-protocol.js";
+import { collectJestAcceptance } from "./jest.js";
+import { array, hasRetry, lower, number, object, result, run, string, terminalEvidence } from "./shared.js";
+function mapFramework(runValue, options) {
+    const results = runValue.results.map((item) => makeAcceptanceCheck({
+        executionId: options.executionId,
+        framework: "vitest",
+        frameworkVersion: options.frameworkVersion,
+        checkId: item.checkId,
+        phase: options.phase,
+        status: item.status,
+        failureClass: item.failureClass,
+        attempts: item.attempts,
+        evidence: item.evidence.map((reference) => reference.replace(/^jest:/u, "vitest:"))
+    }));
+    return makeAcceptanceRun({
+        executionId: options.executionId,
+        framework: "vitest",
+        frameworkVersion: options.frameworkVersion,
+        phase: options.phase,
+        results,
+        completed: runValue.completed,
+        completionEvidence: runValue.completionEvidence.map((reference) => reference.replace(/^jest:/u, "vitest:")),
+        diagnostics: runValue.diagnostics
+    });
+}
+function eventInput(input) {
+    if (Array.isArray(input))
+        return { events: input, diagnostics: [] };
+    if (typeof input !== "string")
+        return undefined;
+    const document = parseJsonDocument(input);
+    if (Array.isArray(document))
+        return { events: document, diagnostics: [] };
+    const lines = parseJsonLines(input);
+    const events = lines.values.length === 1 && Array.isArray(lines.values[0]) ? lines.values[0] : lines.values;
+    return events.length > 0 ? { events, diagnostics: lines.invalidLines.map(line => `invalid-json-line:${line}`) } : undefined;
+}
+function flattenTasks(tasks, file, ancestors, assertions, lifecycleErrors) {
+    for (const raw of tasks) {
+        const task = object(raw);
+        if (task === undefined) {
+            assertions.push(null);
+            continue;
+        }
+        const name = string(task.name ?? task.title);
+        const nextAncestors = name === undefined ? ancestors : [...ancestors, name];
+        const children = array(task.tasks ?? task.children);
+        const state = object(task.result) ?? object(task.state);
+        if (children !== undefined && children.length > 0) {
+            const errors = array(state?.errors);
+            const hooks = object(state?.hooks ?? task.hooks);
+            if (errors !== undefined && errors.length > 0)
+                lifecycleErrors.push(...errors);
+            if (task.hookErrors != null || state?.hookErrors != null ||
+                (hooks !== undefined && Object.values(hooks).some(value => value !== "pass" && value !== "passed"))) {
+                lifecycleErrors.push("suite-hook-error");
+            }
+            flattenTasks(children, file, nextAncestors, assertions, lifecycleErrors);
+            continue;
+        }
+        if (task.type === "suite")
+            continue;
+        const status = state === undefined ? task.status ?? task.state : state.state ?? state.status;
+        const retryValue = state === undefined ? task.retry ?? task.retries : state.retry ?? state.retries;
+        const retryCount = number(state?.retryCount);
+        const repeatCount = number(state?.repeatCount);
+        // Native errors and hooks omit fixture cleanup/onTestFinished provenance.
+        // Even AssertionError with passing hooks is ambiguous without classified
+        // collector metadata, just as in Jest-compatible JSON.
+        const assertion = task.assertion === true || state?.assertion === true || state?.failureClass === "assertion-failed";
+        assertions.push({
+            name,
+            ancestorTitles: ancestors,
+            status: task.fails === true ? "xfail" : status,
+            attempts: number(task.attempts) ?? (retryCount !== undefined && repeatCount !== undefined ? retryCount + repeatCount + 1 : null),
+            retry: hasRetry(task) || (state !== undefined && hasRetry(state)) || (typeof retryValue === "number" && retryValue > 0),
+            assertion,
+            hooks: state?.hooks ?? task.hooks,
+            hookErrors: state?.hookErrors ?? task.hookErrors,
+            location: task.location
+        });
+    }
+}
+function structuredReport(input) {
+    const value = typeof input === "string" ? parseJsonDocument(input) : input;
+    const report = object(value);
+    if (report === undefined)
+        return undefined;
+    if (array(report.testResults) !== undefined) {
+        return report;
+    }
+    const testFiles = array(report.testFiles);
+    if (testFiles !== undefined && testFiles.some((file) => {
+        const value = object(file);
+        return value !== undefined && array(value.assertionResults) !== undefined;
+    })) {
+        return { ...report, testResults: testFiles };
+    }
+    const files = array(report.files ?? report.testFiles);
+    if (files === undefined)
+        return undefined;
+    const suites = [];
+    for (const rawFile of files) {
+        const file = object(rawFile);
+        if (file === undefined) {
+            suites.push(null);
+            continue;
+        }
+        const assertions = [];
+        const lifecycleErrors = [];
+        const tasks = array(file.tasks ?? file.children);
+        if (tasks !== undefined) {
+            flattenTasks(tasks, string(file.filepath ?? file.file ?? file.name) ?? "<vitest-file>", [], assertions, lifecycleErrors);
+        }
+        suites.push({
+            testFilePath: string(file.filepath ?? file.file ?? file.name) ?? "<vitest-file>",
+            assertionResults: assertions,
+            testExecError: file.error ?? file.hookErrors ?? object(file.result)?.errors,
+            runtimeError: lifecycleErrors
+        });
+    }
+    return { ...report, testResults: suites };
+}
+function collectEvents(events, options, initialDiagnostics) {
+    const results = [];
+    const diagnostics = [...initialDiagnostics];
+    let completed = false;
+    let completionEvidence = [];
+    for (const raw of events) {
+        const value = object(raw);
+        if (value === undefined) {
+            diagnostics.push("malformed-event");
+            continue;
+        }
+        const type = lower(value.type ?? value.event ?? value.kind);
+        if ((type === "complete" || type === "completed" || type === "finished") &&
+            value.completed !== false && value.interrupted !== true) {
+            completed = true;
+            completionEvidence = [terminalEvidence(value, options.executionId)];
+            continue;
+        }
+        if (type !== "test-end" && type !== "test:pass" && type !== "test:fail" &&
+            type !== "test:skip" && type !== "test:todo" && type !== "test-result") {
+            diagnostics.push(`unsupported-event:${type ?? "unknown"}`);
+            continue;
+        }
+        const ancestors = array(value.ancestorTitles)?.filter((item) => typeof item === "string") ?? [];
+        const name = string(value.title ?? value.name) ??
+            (ancestors.length === 0 ? string(value.fullName) : undefined);
+        if (name === undefined) {
+            diagnostics.push("missing-check-id");
+            continue;
+        }
+        const file = string(value.file ?? value.filepath) ?? "<vitest>";
+        const location = object(value.location);
+        const line = number(location?.line);
+        const column = number(location?.column);
+        let id;
+        try {
+            id = stableCheckId([
+                file,
+                ...ancestors,
+                name,
+                ...(line === undefined || column === undefined ? [] : [`@${line}:${column}`])
+            ]);
+        }
+        catch {
+            diagnostics.push("missing-check-id");
+            continue;
+        }
+        const status = lower(value.status ?? value.state ?? (type === "test:pass" ? "passed" : type === "test:fail" ? "failed" : type === "test:skip" ? "skipped" : type === "test:todo" ? "todo" : undefined));
+        const refs = [`vitest:assertion:${id}`];
+        const observedAttempts = number(value.attempts);
+        const attemptCount = observedAttempts !== undefined && observedAttempts > 0 ? observedAttempts : null;
+        const hooks = object(value.hooks);
+        const hookFailure = value.hookErrors != null || (hooks !== undefined && Object.values(hooks).some(state => state !== "pass" && state !== "passed"));
+        if (hasRetry(value)) {
+            results.push(result(options, "vitest", id, "UNKNOWN", refs, "retry", attemptCount));
+        }
+        else if (hookFailure) {
+            results.push(result(options, "vitest", id, "UNKNOWN", refs, "hook-error", attemptCount));
+        }
+        else if (status === "passed" || status === "pass") {
+            results.push(result(options, "vitest", id, "PASS", refs, "none", attemptCount));
+        }
+        else if (status === "failed" || status === "fail") {
+            results.push(value.assertion === true || value.failureClass === "assertion-failed"
+                ? result(options, "vitest", id, "FAIL", refs, "assertion-failed", attemptCount)
+                : result(options, "vitest", id, "UNKNOWN", refs, "infrastructure-error", attemptCount));
+        }
+        else if (status === "skipped" || status === "pending") {
+            results.push(result(options, "vitest", id, "UNKNOWN", refs, "skipped", attemptCount));
+        }
+        else if (status === "todo") {
+            results.push(result(options, "vitest", id, "UNKNOWN", refs, "todo", attemptCount));
+        }
+        else {
+            results.push(result(options, "vitest", id, "UNKNOWN", refs, "malformed-output", attemptCount));
+        }
+    }
+    return run(options, "vitest", results, completed, completionEvidence, diagnostics);
+}
+/** Collect Vitest reporter events or its Jest-compatible JSON output. */
+export function collectVitestAcceptance(input, options) {
+    const events = eventInput(input);
+    if (events !== undefined && events.events.some((event) => {
+        const value = object(event);
+        const type = value === undefined ? undefined : lower(value.type ?? value.event ?? value.kind);
+        return type !== undefined && type.startsWith("test");
+    })) {
+        return collectEvents(events.events, options, events.diagnostics);
+    }
+    const report = structuredReport(input);
+    if (report === undefined)
+        return run(options, "vitest", [], false, [], ["malformed-output"]);
+    return mapFramework(collectJestAcceptance(report, options), options);
+}

package/dist/runtime/src/verify/evidence.js

@@ -24,7 +24,9 @@ function validateBuiltEvidence(value) {
 }
 export function buildVerificationEvidence(input) {
     return validateBuiltEvidence({
-        schemaVersion: EVIDENCE_SCHEMA_VERSION,
+        schemaVersion: input.taskContractHash === undefined && input.acceptance === undefined ? 3 : EVIDENCE_SCHEMA_VERSION,
+        ...(input.taskContractHash === undefined ? {} : { taskContractHash: input.taskContractHash }),
+        ...(input.acceptance === undefined ? {} : { acceptance: input.acceptance }),
         taskId: input.taskId,
         criterionId: input.criterionId,
         commandId: input.command.id,
@@ -54,7 +56,7 @@ export function isPassingVerificationEvidence(command, evidence) {
         return false;
     }
     return command.evidence.kind !== "test-count" ||
-        (evidence.schemaVersion === EVIDENCE_SCHEMA_VERSION &&
+        (evidence.schemaVersion >= 3 &&
             evaluateTestCount(evidence.testCount, command.evidence.minimum).status === "PASS");
 }
 export class FileEvidenceStore {
@@ -64,6 +66,7 @@ export class FileEvidenceStore {
         this.#root = root;
         this.#anchorDirectory = anchorDirectory;
     }
+    get root() { return this.#root; }
     async save(value) {
         const evidence = validateBuiltEvidence(value);
         const content = `${JSON.stringify(evidence, null, 2)}\n`;

package/dist/runtime/src/verify/service.js

@@ -1,3 +1,5 @@
+import { taskContractHash } from "../task/contract.js";
+import { replayAcceptance } from "./acceptance-replay.js";
 import { AgentOpsError, resolveContainedPath } from "../fs/paths.js";
 import { validateTaskAgainstConfig } from "../schema/validate.js";
 import { collectChangeSurface } from "./change-surface.js";
@@ -23,7 +25,7 @@ function exitCategory(result) {
     return result.exitCode === 0 ? "exit-zero" : "nonzero-exit";
 }
 function relevantCriteria(task, commandId) {
-    return task.criteria.filter((criterion) => criterion.verifierIds.includes(commandId));
+    return task.criteria.filter((criterion) => criterion.verifierIds.includes(commandId) || criterion.acceptance !== undefined);
 }
 function commandById(config, commandId) {
     const command = config.verification.commands.find((candidate) => candidate.id === commandId);
@@ -59,6 +61,7 @@ export class VerificationService {
                 failureClass: result.failureClass,
                 sourceFingerprint,
                 toolVersions: this.#options.toolVersions ?? {},
+                ...(task.goal === undefined && (task.contractRevision ?? 0) === 0 && task.criteria.every(c => c.acceptance === undefined) ? {} : { taskContractHash: taskContractHash(task) }),
                 config: this.#options.config
             });
             references.push(await this.#options.evidenceStore.save(evidence));
@@ -113,13 +116,14 @@ export class VerificationService {
             throw verificationError("VERIFICATION_INPUT_INVALID", validation.errors[0]?.message ??
                 "Task and verification configuration are incompatible.");
         }
-        const missingCriteria = validation.value.criteria.filter((criterion) => !this.#options.config.verification.commands.some(({ id, required }) => required && criterion.verifierIds.includes(id)));
+        const missingCriteria = validation.value.criteria.filter((criterion) => criterion.acceptance === undefined && !this.#options.config.verification.commands.some(({ id, required }) => required && criterion.verifierIds.includes(id)));
         if (missingCriteria.length > 0) {
             throw verificationError("VERIFICATION_UNKNOWN", `Criteria without required coverage: ${missingCriteria.map(({ id }) => id).join(", ")}. Configure at least one required verifier for each criterion and recreate the task; no verifier commands were run.`);
         }
         const reviewScope = await resolveReviewScope({
             root: this.#options.root,
             runner: this.#options.gitRunner,
+            ...(this.#options.noChangePaths === undefined && stored.noChangePaths === undefined ? {} : { noChangePaths: this.#options.noChangePaths ?? stored.noChangePaths }),
             ...(this.#options.base === undefined ? {} : { base: this.#options.base })
         });
         const sourceFingerprint = await calculateSourceFingerprint(this.#options.root, reviewScope, this.#options.gitRunner);
@@ -133,29 +137,38 @@ export class VerificationService {
             ...mappedSelection,
             verifierIds: [...new Set([...mappedSelection.verifierIds,
                     ...this.#options.config.verification.commands
-                        .filter(({ id, required }) => required && taskVerifierIds.has(id))
+                        .filter(({ id, required }) => required && (validation.value.criteria.some(c => c.acceptance !== undefined) || taskVerifierIds.has(id)))
                         .map(({ id }) => id)])]
         };
         const results = [];
         for (const commandId of selection.verifierIds) {
             results.push(await this.#runCommand(validation.value, commandById(this.#options.config, commandId)));
         }
-        let status = aggregateVerificationStatus(results);
+        const acceptance = validation.value.criteria.some(c => c.acceptance !== undefined && c.acceptance.mode !== "review-only")
+            ? await replayAcceptance({ ...this.#options, task: validation.value, sourceFingerprint }) : [];
+        let status = aggregateVerificationStatus([...results, ...acceptance.map(a => ({ required: true, status: a.status }))]);
         let sourceChanged = false;
         const postflightScope = await resolveReviewScope({
             root: this.#options.root,
             runner: this.#options.gitRunner,
+            ...(this.#options.noChangePaths === undefined && stored.noChangePaths === undefined ? {} : { noChangePaths: this.#options.noChangePaths ?? stored.noChangePaths }),
             ...(this.#options.base === undefined ? {} : { base: this.#options.base })
         });
         const postflightFingerprint = await calculateSourceFingerprint(this.#options.root, postflightScope, this.#options.gitRunner);
         if (reviewScopeSignature(reviewScope) !== reviewScopeSignature(postflightScope) ||
-            sourceFingerprint !== postflightFingerprint) {
+            sourceFingerprint !== postflightFingerprint ||
+            taskContractHash((await this.#options.taskService.status({ taskId })).task) !== taskContractHash(stored.task)) {
             status = "UNKNOWN";
             sourceChanged = true;
         }
+        const acceptanceEvidence = {};
+        for (const proof of acceptance)
+            acceptanceEvidence[proof.criterionId] = [...(acceptanceEvidence[proof.criterionId] ?? []), proof.reference];
+        if (status !== "PASS" && stored.status === "active" && acceptance.length > 0)
+            await this.#options.taskService.recordEvidence(taskId, acceptanceEvidence);
         let signal = null;
         if (status === "PASS") {
-            const taskEvidence = {};
+            const taskEvidence = { ...acceptanceEvidence };
             for (const [index, result] of results.entries()) {
                 const command = commandById(this.#options.config, result.commandId);
                 const references = await this.#persistEvidence(validation.value, command, result.startedAt, result.finishedAt, result, sourceFingerprint);
@@ -175,7 +188,9 @@ export class VerificationService {
             }
         }
         else {
-            const required = results.filter((result) => result.required);
+            const required = [...results.filter((result) => result.required), ...acceptance.map(a => ({ commandId: a.runnerId, required: true,
+                    status: a.status, failureClass: a.failureClass, exitCode: null, timedOut: false, testCount: null,
+                    diagnostic: a.criterionId + ":" + a.phase + ":" + a.failureClass, evidenceReferences: [a.reference], startedAt: "", finishedAt: "" }))];
             const gating = required;
             const failed = gating.find((result) => result.status !== "PASS");
             if (failed === undefined) {
@@ -189,7 +204,7 @@ export class VerificationService {
                     diagnostics: "source changed during verification"
                 }));
                 signal = advanced.signal;
-                return { taskId, status, surface, selection, results, signal, reviewScope, sourceFingerprint };
+                return { taskId, status, surface, selection, results, signal, reviewScope, sourceFingerprint, acceptance };
             }
             const advanced = await this.#options.taskService.recordFailure(taskId, createFailureFingerprint({
                 commandId: failed.commandId,
@@ -200,6 +215,7 @@ export class VerificationService {
             signal = advanced.signal;
         }
         return {
+            acceptance,
             taskId,
             status,
             surface,

package/dist/runtime/src/verify/source-fingerprint.js

@@ -8,7 +8,7 @@ export async function calculateSourceFingerprint(root, scope, runner) {
     if (scope.mode === "base") {
         return sha256(JSON.stringify({
             domain: "agent-ops-source-v1",
-            mode: "base",
+            mode: scope.noChange === true ? "goal-no-change" : "base",
             head,
             base: scope.resolvedBase,
             paths: [...scope.changedFiles]

package/dist/runtime/src/verify/spawn.js

@@ -146,16 +146,20 @@ async function defaultTerminateWindowsTree(processId, graceMs) {
 }
 export class NodeVerificationProcessRunner {
     #platform;
+    #processGroupId;
     #terminateWindowsTree;
     constructor(options = {}) {
         this.#platform = options.platform ?? process.platform;
+        this.#processGroupId = options.processGroupId;
+        if (this.#processGroupId !== undefined && (!Number.isSafeInteger(this.#processGroupId) || this.#processGroupId < 1 || this.#platform === "win32"))
+            throw new Error("Registered proof group must be a positive POSIX process group ID.");
         this.#terminateWindowsTree =
             options.terminateWindowsTree ?? defaultTerminateWindowsTree;
     }
     start(request) {
         const child = spawn(request.command, [...request.args], {
             cwd: request.cwd,
-            detached: this.#platform !== "win32",
+            detached: this.#platform !== "win32" && this.#processGroupId === undefined,
             env: {
                 ...(request.replaceEnv === true ? {} : process.env),
                 ...(request.env ?? {})
@@ -204,7 +208,7 @@ export class NodeVerificationProcessRunner {
                     await this.#terminateWindowsTree(processId, graceMs);
                     return;
                 }
-                await terminatePosixTree(processId, completion, graceMs);
+                await terminatePosixTree(this.#processGroupId ?? processId, completion, graceMs);
             }
         };
     }
@@ -375,3 +379,10 @@ export async function runVerificationCommand(command, options) {
         stderrTruncated: capturedStderr.truncated
     };
 }
+/** CLI-only opt-in. The dormant entry sets this after the supervisor records its PID. */
+export function registeredRunProofRunner() {
+    const value = process.env.AGENT_OPS_RUN_PROOF_PID;
+    if (value !== undefined && !/^[1-9][0-9]{0,9}$/u.test(value))
+        throw new Error("Invalid registered run proof PID.");
+    return new NodeVerificationProcessRunner(value === undefined ? {} : { processGroupId: Number(value) });
+}

package/docs/en/guides/configuration.md

@@ -265,6 +265,16 @@ evidence. Give each editing conversation its own worktree instead:
   Creating a subtask keeps the session attached to the top of its tree, and
   each task keeps its own review record, so a parent and a subtask reviewed
   on the same source do not overwrite each other.
+- When writing subagents use separate worktrees, create each child task with
+  `--intent` before editing, then commit and verify locally. From the main
+  checkout run `agent-ops task advance --task <parent-id> --session <id> --yes`
+  through the trusted outer host runner. It integrates all child commits and
+  intents into the coordinator worktree, reruns each task's required verifier
+  on the same candidate, and performs one two-round tree review. Only an
+  explicit `NOT_RUN / scope-too-large` falls back to per-task two-round review.
+  After PASS it saves a complete receipt under `.git/agent-ops/receipts/` and
+  calls finish; a moved target may trigger one repeat of the final gate.
+  A direct finish of one child while siblings exist is refused.
 - `agent-ops worktree finish <name>` merges by fast-forward only, one finish
   at a time. When the main checkout is on the target branch the merge updates
   its files, so uncommitted changes there block it. When the main checkout is

package/docs/en/spec/acceptance-and-evidence.md

@@ -1,5 +1,53 @@
 # Acceptance and Evidence
 
+## EVIDENCE-CONTRACT-001
+
+Executable acceptance MUST bind the current contract to immutable replay evidence.
+
+- Trigger: Verifying or completing a typed acceptance contract.
+- Action: Replay trusted checks against the immutable baseline and current candidate, then obtain fresh review.
+- Evidence: Digest-bound phase results and current contract coverage enter both reviewer packets.
+- Positive: Baseline assertion FAIL and candidate PASS prove a behavioral check.
+- Negative: A fixture error is counted as red, or an old review proves revised criteria.
+
+- `behavioral`: every designated red check fails by assertion on the baseline;
+  every required candidate check passes. `invariant`: required candidate checks
+  pass; baseline PASS is valid. `review-only`: two fresh reviewers discharge the
+  requirement against the original goal; no mechanical proof is claimed.
+- Trusted repository `verification.acceptanceRunners` define argv, setup, product
+  build and test build. Tasks provide stable check IDs and explicit committed
+  test/fixture/helper materials. Each checkout installs and builds its own version
+  before candidate materials are overlaid. Tasks cannot override runner commands.
+- Fixture, collection, build, timeout, cancellation, truncated output, missing or
+  duplicate IDs, retries and skips MUST NOT establish red or green. Complete raw
+  execution artifacts are digest-bound to the contract, materials and commits.
+- Native Jest JSON and Vitest task errors lack complete test-call versus
+  hook/fixture-cleanup provenance. Failed rows MUST remain UNKNOWN unless a
+  reviewed repository collector supplies explicit assertion classification;
+  AssertionError names, matcher details and passing hook states are insufficient.
+  Green requires explicit single-attempt evidence: attempts, Jest invocations,
+  or both Vitest retryCount and repeatCount. Native Vitest JSON omits these
+  counters and cannot supply mechanical proof by itself. Pytest requires one
+  ordered setup/call/teardown lifecycle per nodeid; the Rust protocol requires
+  explicit attempts. Missing metadata MUST NOT default to a successful attempt.
+- Baselines are immutable creation commits, or failed candidates for finding pins.
+  Revise/replan preserve the original goal, every mapped requirement and previous
+  contracts/evidence. New contracts require new proof and both fresh reviews.
+- `task pin-finding` validates saved report digest/index provenance. Recurrence
+  explicitly names an existing pin. A sixth criterion returns a replan obligation
+  without changing state; the mapped replan must retain the pin and all requirements.
+- Reviewer packets include original goal, revision history, coverage and verifier
+  materials. Review checks the assertions themselves and explicit fallback reasons.
+  Mechanical green never removes mandatory policy commands or either fresh review.
+
+Task state writes version 2 and reads version 1. Evidence version 4 reads earlier
+evidence; attestation version 3 binds contracts and coverage. Legacy criteria keep
+the verifier rules below; typed or revised contracts cannot reuse an old review.
+Coverage separates mechanical proof, review-only and legacy; a runner binding alone
+is not proof. Explicit no-change proof names existing committed regular source files
+at the frozen candidate; integration re-resolves them. Ordinary empty-diff review
+and empty-branch direct finish remain rejected.
+
 ## EVIDENCE-CRITERION-001
 
 Every acceptance criterion MUST map to observable evidence.
@@ -10,6 +58,16 @@ Every acceptance criterion MUST map to observable evidence.
 - Positive: `criterion tests → npm test (354 passing tests)`.
 - Negative: `The implementation looks correct, so no evidence is needed.`
 
+## EVIDENCE-INTENT-001
+
+Each child worktree MUST record its modification intent before editing.
+
+- Trigger: A subagent will edit in its own worktree.
+- Action: Use `task create --intent <text>` to record the user-approved behavior, constraints and integration points. The coordinator imports the intent with the child task and re-runs verification on the integrated candidate.
+- Evidence: The child task and final receipt contain the intent, with final verifier evidence bound to the integrated candidate.
+- Positive: `A child records its planned API change, commits it, and the final receipt includes that intent and integrated verification.`
+- Negative: `A child edits first and supplies a retrospective one-line intent at delivery.`
+
 ## EVIDENCE-AGGREGATE-001
 
 The verifier MUST return FAIL when a criterion is missing, duplicated, unknown, or has empty evidence.