@kylecheng3146/agent-ops 0.5.3 → 0.7.0

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/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.

package/docs/en/spec/harness-adapters.md

@@ -41,7 +41,7 @@ capabilities and MUST track generated source as one whole-file artifact.
 - Action: For opencode, manage `.opencode/plugins/agent-ops.js` in a project or `.config/opencode/plugins/agent-ops.js` at user scope (`$XDG_CONFIG_HOME/opencode/plugins/agent-ops.js` when configured inside the managed user root, or `$OPENCODE_CONFIG_DIR/plugins/agent-ops.js` when that native config directory is configured), leave `opencode.json` untouched, and deduplicate a project `AGENTS.md` contribution by path.
 - Evidence: The manifest contains the plugin hash, the generated source contains only the selected hook registrations, and shared project markers occur once.
 - Positive: `codex,opencode` produces one project AGENTS route and one hashed opencode plugin.
-- Negative: `Add an opencode.json instructions entry or register a plugin for a core-only profile.`
+- Negative: `Add an opencode.json instructions entry or register a plugin for a core-only profile with Office disabled.`
 
 ## HARNESS-ADAPTER-004
 
@@ -106,6 +106,7 @@ The current registration matrix is intentionally asymmetric:
 
 | Capability | agy | Codex | Claude Code | OpenCode |
 | --- | --- | --- | --- | --- |
+| office-presence (Preview) | degraded | degraded | supported | degraded |
 | lifecycle-summary | degraded | supported | supported | degraded |
 | command-policy | supported | unknown | supported | supported |
 | completion-gate | supported | unsupported | unsupported | unsupported |
@@ -137,3 +138,114 @@ stores only bounded local event metadata, returns bounded redacted session
 context, and preserves local goal, state, telemetry, and Codex TOML files on
 update or uninstall. A clearly parsed `[features]` / `hooks = false` in an
 existing Codex configuration MUST reject loop planning before any write.
+
+## HARNESS-ADAPTER-007
+
+The `run` profile MUST be opt-in, select `core` and `loop` with it, and add only
+the `auto-run` capability. With it, the Claude Code and Codex managed rules hand
+a change that needs more than five acceptance criteria to `agent-ops run`; five
+or fewer stay in the session. agy rules, and every rule file without `auto-run`,
+MUST stay byte-identical to the rules without the profile.
+
+- Trigger: A project selects `run`, and a Claude Code or Codex session meets a
+  change that needs more than five acceptance criteria.
+- Action: From the main checkout and before any `task create`, the agent writes
+  the user's prompt verbatim and its proposed acceptance criteria, marked as
+  proposals, to the gitignored `.agent-ops/state/run-goal.md`, then starts
+  `agent-ops run --goal-file .agent-ops/state/run-goal.md --host <claude|codex> --wait`
+  as a background shell command. Codex starts it like review: an outer request
+  with `sandbox_permissions: "require_escalated"` and
+  `env -u CODEX_SANDBOX_NETWORK_DISABLED`. An awaiting-input result is relayed
+  to the user and answered with `agent-ops run respond`. A start refused with
+  `RUN_TARGET_REQUIRED`, `RUN_BACKGROUND_UNSUPPORTED`, `RUN_TARGET_DIRTY` or
+  `WORKTREE_NESTED` is reported in one line naming the code and falls back to
+  the subtask flow; `RUN_REPO_UNTRUSTED` stops and asks the user. A run that
+  ends without completing (blocked, budget exhausted, stopped, failing review)
+  is reported with its `run status` state and code, its last `run logs` events,
+  and the exact `agent-ops run resume <id>` and `agent-ops run stop <id>`
+  commands, and is never resumed automatically or taken over by the session.
+  With worktree auto mode, the Claude `PreToolUse` worktree guard allows a
+  write to exactly `.agent-ops/state/run-goal.md` in the main checkout without
+  creating a worktree. Confirmed init/update pre-authorizes `agent-ops run`:
+  `Bash(agent-ops run *)` for Claude Code, and an escalated prefix rule for
+  `env -u CODEX_SANDBOX_NETWORK_DISABLED agent-ops run` for Codex.
+- Evidence: Profile, managed-rule digest, pre-authorization, and worktree-guard
+  tests cover the resolved profiles, the unchanged rules, the added entries, and
+  the single exempt path.
+- Positive: `A Claude Code session with the run profile writes .agent-ops/state/run-goal.md in the main checkout and starts agent-ops run --host claude --wait in the background.`
+- Negative: `Split an eight-criteria change into subtasks while the run profile is active, add auto-run text to GEMINI.md, or resume a blocked run without the user.`
+
+## HARNESS-ADAPTER-008
+
+`agent-ops office` (Preview) MUST show progress read-only from agent-ops state alone. The
+supervisor records an optional phase per run and worker (`planning`,
+`implementing`, `verifying`, `reviewing`, `integrating`) at deterministic
+transitions, and each task's latest verify and review result with passed/total
+criteria. Run state written before phases existed MUST still validate and show
+as `unknown`. Changed files come from each worktree's own `git diff` against its
+base; narration uses paths only (`docs/**` is "writing docs", `tests/**` is
+"writing tests", otherwise "editing <file>"). The office MUST NOT read native
+Claude or Codex transcripts or file contents.
+
+- Office Preview is opt-in via `features.office.enabled`. Init MUST offer an
+  off-by-default choice; interactive update MUST default to the existing choice.
+  Non-interactive update MUST preserve it unless `--office on|off` is supplied.
+  Older configs without the optional field remain valid and mean disabled.
+  Enabling Office MUST install its presence hooks even with only `core`; this
+  MUST NOT opt into command policy, Stop verification or lifecycle summaries.
+  Office-only OpenCode runtime failure MUST remain fail-open; adding Office to
+  command policy MUST preserve policy denial and unavailable-runtime behavior.
+  Agy startup is per invocation, OpenCode startup is app-scoped, and Codex
+  Stop delivery is unavailable in some execution modes; stale presence expires
+  using the bounded hook-activity timeout rather than assuming native Stop.
+  Features retain their existing whole-object layer precedence. Disabled hooks
+  MUST NOT record Office presence or start/open Office; the explicit command
+  MUST explain how to enable it. A running server MUST close after observing a
+  disabled choice on its next 15-second lifecycle check.
+- Trigger: When enabled, a managed ordinary session starts or reports activity, or a user runs
+  `agent-ops office`, `agent-ops run start` or `agent-ops run status`.
+- Action: The command reuses the live server recorded in
+  `<git common dir>/agent-ops/office.json`, or starts one, and prints its URL.
+  Ordinary session hooks also start or reuse it, including before a task or
+  worktree exists. Only the successful new-server owner opens the browser;
+  other sessions share the same Office. Session metadata contains bounded
+  identifiers, known work state and activity times, never native transcripts,
+  prompts or tool/file contents. Startup and observation failures are advisory.
+  The server binds
+  127.0.0.1 on a random port, requires the URL's unguessable token, refuses any
+  Host other than that address and port, answers every non-GET with 405, and
+  exits 10 minutes after neither a run nor an ordinary session is active.
+  Ordinary-session liveness follows hooks, with stale presence expiring after
+  30 minutes without activity; it does not inspect native host processes.
+  Its single inline page uses cozy cream, oak and sage in-code 16-color scene
+  sprites with no image assets. Each 32×48 character uses its own fixed skin,
+  hair and clothing palette, four-direction walking, and localized role labels.
+  The viewer's badge displays `You` in English and `你` in Chinese; its overview size matches the largest room's
+  characters. The fixed-viewport overview
+  fills the available page below the header and shows all furnished work-unit
+  rooms, shrinking rooms as necessary without document scrolling. A shared
+  hallway connects the rooms. The user controls a local Supervisor with arrow
+  keys or WASD, can walk into every room and return to the overview, without
+  model requests or network mutations. Each run team shares a room; each ordinary session has its own,
+  and running reviews remain visible. Clicking a room enters a larger detail
+  view with a return control. Every room contains planning, development,
+  verification, review and integration areas. Characters walk to their known
+  phase's zone, use light phase-driven animation, and have short name/status
+  labels; unknown state is not inferred from dialogue. Whiteboards show task
+  criteria progress, verify/review outcomes and pending questions, with `!` for
+  unanswered questions. Clicking a whiteboard or progress board opens the room
+  work list; workstations and phase areas show the known work in that phase.
+  Pending markers open complete questions with the existing copyable commands.
+  The same paged views are available with `L` (work list), `1–5` (phases) and
+  `Q` (questions). Clicking an actor opens bounded, paged status details
+  with copyable commands. Completed rooms are available through Recently
+  completed for at most two hours. Chinese/English switching remembers the
+  choice, and keyboard navigation and reduced motion are supported. A failure
+  to start the office never fails a hook, `run start` or `run status`.
+- Evidence: Phase, snapshot, server, scene and CLI tests cover legacy state,
+  aggregation and narration, ordinary-session registration and startup-once,
+  the two-hour completion boundary, token/Host/method guards, reuse and the
+  injected-clock idle exit, viewport/room navigation, localization, and the
+  printed URL. A browser read-back checks the rendered single-page layout.
+- Positive: `An ordinary session opens the shared Office, where its room is visible before it creates a worktree; entering a team room shows the coordinator at the verification bench and a whiteboard with 2 of 6 criteria passed.`
+- Negative: `Serve the office on 0.0.0.0, accept a POST, read a worker's transcript to narrate it, or bundle a PNG sprite sheet.`

package/docs/en/spec/loop-engineering.md

@@ -1,5 +1,54 @@
 # Loop Engineering
 
+## LOOP-RUN-001
+
+`run` MUST preserve the original user goal and require current agent-ops proof.
+
+- Trigger: Starting, repairing or recovering a native goal run.
+- Action: Bind writers to current leases and require final verification, dual review and receipt proof.
+- Evidence: The run ledger and sealed receipt bind the current candidate and original goal.
+- Positive: Recovering interrupted cleanup preserves the target and saved final proof.
+- Negative: Native goal completion alone changes run state to complete.
+
+- The macOS supervisor registers Claude/Codex native identities before activating
+  goals. Same-host writers use isolated worktrees and current generation leases;
+  the coordinator counts toward the maximum two writers. Dependencies become
+  available only through frozen deliveries; child baselines follow those commits.
+- The default 60-minute budget counts the union of active intervals, including
+  setup, proof, review and integration. Resume keeps elapsed time and usage epochs.
+  Missing counters remain UNKNOWN; partial usage is not a complete cost estimate.
+- Questions pause work and require an explicit answer. Repair preserves the goal
+  and records failures; two identical rounds without progress stop that worker
+  and its dependents. Independent tasks remain eligible. Review findings require
+  regression pins or recorded review-only fallback before another final gate.
+- Native completion is observational. Finalization requires mandatory verification,
+  both fresh reviews, completed task state and a receipt bound to the target.
+  Integration seals the candidate before moving the target and records task,
+  receipt, note and cleanup progress. Recovery validates that seal and does not
+  repeat a successful target mutation. Inconsistent targets remain blocked.
+- Stop persists disabled continuation before confirming registered process-group
+  death. Crash recovery cannot replace a live or unidentified writer. Dirty
+  checkouts, version drift and restart storms preserve the scene for diagnosis.
+  Reboot/login changes require explicit resume; no global host policy is changed.
+  Startup process identities are saved before the native handshake; a stopped,
+  unopened Codex session may initialize afresh only after process death is proved.
+
+- Setup and native-issued local proof commands MUST register dormant process
+  groups before execution; Stop also reconciles their descendants. Interrupted
+  setup requires explicit resume and retains its checkout and failure artifact.
+- A coordinator may assess additional fixed non-dangerous capabilities only under
+  a run-scoped policy bound to the original repository trust, executable runtime
+  and remaining budget. Explicit native or organization denial cannot be bypassed.
+  Policy changes fence all writers, preserve frozen deliveries and journal contract
+  synchronization before new generations acquire leases. This never grants global
+  repository trust. Native decisions retain redacted command scope and rationale;
+  absent provider evidence remains UNKNOWN.
+  Explicit resume renews expired authorization from the remaining budget and
+  reconciles immutable renewal lineage before policy synchronization. An answer
+  uses the same recovery checks; neither action can revive an explicit denial.
+- Convergence compares actual per-check statuses and outstanding finding pins.
+  Source fingerprints, timing and diagnostics alone cannot establish progress.
+
 This module defines the bounded loop used to plan, implement, verify, and hand off work.
 
 ## LOOP-START-001