@kylecheng3146/agent-ops 0.5.3 → 0.7.0

package/dist/packages/cli/src/cli.js

@@ -25,10 +25,12 @@ Commands:
   doctor     Diagnose an installation
   update     Update managed artifacts
   uninstall  Remove managed artifacts
-  task <create|status|attach|complete|archive|export>
+  task <create|status|attach|revise|replan|pin-finding|advance|complete|archive|export>
              Manage independent task acceptance state
   verify     Run configured verification
   review     Run an independent review or show recorded reports
+  run        Start or control a supervised Claude/Codex native goal
+  office     Open the local pixel office (Preview; opt-in)
   batch      Verify and review a parent task's subtasks together
   allow-stop Grant one fingerprint-bound completion-gate Stop permit (requires --session)
   agy-run    Run headless agy with a process-exit completion recheck
@@ -39,9 +41,10 @@ Options:
   --scope <project|user>
   --harness <all|both|agy|claude|codex|opencode|comma-separated>  Init/update/uninstall; review uses configured targets
   --hook-target <harness=surface-id>  Repeatable advanced init/update option
-  --profile <core|advisory|guardrails|loop>  Repeatable
+  --profile <core|advisory|guardrails|loop|run>  Repeatable
   --review-target <codex|agy|claude>  Repeatable init option; review pair order
   --completion-gate                  Init only: enable the project-loop completion gate
+  --office <on|off>                   Init/update: enable or disable Office (Preview)
   --worktree <auto|off>              Init/update: configure session worktree isolation
   --check-auth                        Doctor only: probe selected review targets'
                                       authentication with one real call
@@ -71,6 +74,28 @@ Options:
  * rejected.
  */
 export const COMMAND_HELP_TEXT = {
+    office: `Usage: agent-ops office [--json]
+
+Office (Preview) is opt-in: select it during init/update or run
+agent-ops update --office on. Disable with --office off. A missing choice is off.
+
+Print the URL of this repository's office: a read-only pixel page on
+127.0.0.1. All run teams and ordinary sessions appear in a single-screen room
+overview; walk the Supervisor with arrows/WASD or click a room for details.
+Switch Chinese/English in the header. Movement and animation run locally.
+When enabled, managed sessions start the shared server automatically. A new Office opens the
+browser once; later sessions reuse it. It exits after 10 minutes without active
+runs or sessions. Recently completed rooms remain for at most 2 hours.
+The URL carries an access token; do not share it.
+`,
+    run: `Usage: agent-ops run [start] "<goal>" --host <claude|codex> [--jobs <1|2>] [--time-budget <60m>] [--wait] [--json]
+       agent-ops run [start] --goal-file <path> --host <claude|codex>
+       agent-ops run <status|logs|resume|stop> <run-id> [--json]
+       agent-ops run respond <run-id> --question-id <id> <--answer <text>|--answer-file <path>> [--json]
+
+Native goal state is observational. Completion requires current verification,
+two fresh reviews, task completion and a target-bound integration receipt.
+`,
     init: `Usage: agent-ops init [options]
 
 Plan or install agent-ops into this repository.
@@ -79,9 +104,10 @@ Options:
   --scope <project|user>
   --harness <all|both|agy|claude|codex|opencode|comma-separated>
   --hook-target <harness=surface-id>   Repeatable
-  --profile <core|advisory|guardrails|loop>  Repeatable
+  --profile <core|advisory|guardrails|loop|run>  Repeatable
   --review-target <codex|agy|claude>   Repeatable, in fallback-chain order
   --completion-gate                    Enable the project-loop completion gate
+  --office <on|off>                   Office (Preview); default off, update preserves choice
   --worktree <auto|off>                Configure session worktree isolation
   --dry-run                            Print the plan without writing
   --json
@@ -125,6 +151,7 @@ Options:
   --scope <project|user>
   --harness <all|both|agy|claude|codex|opencode|comma-separated>
   --target-version <version>   Offline-capable update target
+  --office <on|off>           Office (Preview); preserve choice unless supplied
   --worktree <auto|off>        Configure session worktree isolation
   --dry-run
   --json
@@ -141,7 +168,7 @@ Options:
   --json
   --yes
 `,
-    task: `Usage: agent-ops task <create|status|attach|complete|archive|export|advance> [options]
+    task: `Usage: agent-ops task <create|status|attach|revise|replan|pin-finding|advance|complete|archive|export> [options]
 
 Manage independent task acceptance state. Task commands accept none of
 --harness, --profile or --dry-run. Only advance accepts --yes.
@@ -150,20 +177,38 @@ Options:
   --title <text>                        create
   --intent <text>                       create: intended behavior and constraints before editing
   --criterion <json>                    create, repeatable, two to five total
+  --criterion-file <path>               create: one criterion object, repeatable; pin-finding: exactly one
+  --criteria-file <path>                revise: replacement criterion array
+  --plan-file <path>                    replan: split-task array with requirement mappings
+  --expected-contract <hash>            revise, pin-finding: current task contract from status
+  --expected-tree-contract <hash>       replan: current tree contract from status
+  --reason <text>                       required for revise/replan; optional for pin-finding
+  --baseline <git-ref>                  create/revise: baseline for new mechanical requirements
   --parent <task-id>                    create: record a subtask; status: list subtasks
-  --task <id>                           status, attach, complete, archive, export, advance
+  --task <id>                           status, attach, revise, replan, pin-finding, complete, archive, export, advance
   --session <id>                        create, attach, status, advance
   --evidence <criterion-id=reference>   complete, repeatable
   --base <git-ref>                      complete: a clean committed range
   --yes                                 advance: authorize the two review sessions
   --json
 
-Each --criterion is one JSON object with exactly these keys:
+Each --criterion or --criterion-file supplies one criterion object. Legacy example:
 
   {"id":"kebab-id","description":"what must hold","verifierIds":["node-test"]}
 
-Every criterion needs at least one verifierIds entry naming a verification
-command id configured in .agent-ops/config.json. No other key is accepted.
+Each legacy criterion needs at least one verifierIds entry naming a verification
+command id configured in .agent-ops/config.json. Typed criteria additionally
+accept an acceptance object: mode (behavioral, invariant or review-only),
+bindings and optional baselineCommit/reviewOnlyReason. Mechanical bindings name
+configured acceptance runner IDs, checkIds, committed materials and optional
+redCheckIds; tasks cannot supply commands. Creation freezes the baseline.
+Review-only example (mandatory repository policy commands still run):
+
+  {"id":"judgment","description":"Meets the original goal","verifierIds":[],"acceptance":{"mode":"review-only","bindings":[],"reviewOnlyReason":"Requires independent judgment"}}
+
+Pin a saved finding with task pin-finding --task <id> <report-digest:index>
+--expected-contract <hash> --criterion-file <path>. Revise/replan preserve the
+original goal and immutable existing baselines; obtain new verify and review.
 `,
     verify: `Usage: agent-ops verify [options]
 

package/dist/packages/cli/src/codex-loop-process.js

@@ -1,4 +1,5 @@
-import { PROJECT_LOOP_EVENTS, runProjectLoop } from "../../../runtime/src/hooks/codex-loop.js";
+import { PROJECT_LOOP_EVENTS, resolveProjectLoopRoot, runProjectLoop } from "../../../runtime/src/hooks/codex-loop.js";
+import { officeEnabled, officeLoopPhaseHint } from "./office-entry.js";
 const MAX_LOOP_INPUT_BYTES = 64 * 1024;
 function isLoopHarness(value) {
     return value === "claude" || value === "codex";
@@ -43,10 +44,26 @@ export async function runLoopProcess(argv, io, dependencies = {}) {
         return 0;
     }
     try {
+        const input = parseInput(await readStdin(io.stdin));
+        const inputIsObject = typeof input === "object" && input !== null && !Array.isArray(input);
+        const managedRoot = inputIsObject
+            ? await resolveProjectLoopRoot(input, dependencies.root ?? process.cwd(), harness).catch(() => null)
+            : null;
+        if (dependencies.office !== undefined && managedRoot !== null && await officeEnabled(managedRoot)) {
+            const phase = officeLoopPhaseHint(input, managedRoot);
+            void dependencies.office({
+                root: managedRoot,
+                harness,
+                event,
+                input,
+                validated: true,
+                ...(phase === undefined ? {} : { phase })
+            }).catch(() => undefined);
+        }
         const result = await runProjectLoop({
             harness,
             event,
-            input: parseInput(await readStdin(io.stdin)),
+            input,
             root: dependencies.root ?? process.cwd(),
             ...(dependencies.now === undefined ? {} : { now: dependencies.now }),
             ...(dependencies.gitStatus === undefined

package/dist/packages/cli/src/commands/advance.js

@@ -9,6 +9,8 @@ import { renderReviewDetails, renderReviewHighlights } from "../../../../runtime
 import { calculateSourceFingerprint } from "../../../../runtime/src/verify/source-fingerprint.js";
 import { okEnvelope } from "../output.js";
 import { readFinishedReview } from "./review-show.js";
+import { criteriaProgress } from "../../../../runtime/src/run/phase.js";
+import { prepareRunIntegration, readRunIntegrationProof, abandonPreparedRunIntegration } from "../../../../runtime/src/run/integration.js";
 /** The child process runs the existing CLI in the candidate checkout. */
 export async function runAdvanceStep(cwd, args) {
     const bin = process.argv[1];
@@ -87,6 +89,13 @@ export async function runAdvanceCommand(options) {
     if (record === null || record.sessionId !== options.sessionId || record.agentId !== undefined) {
         throw new AgentOpsError("ADVANCE_WORKTREE_MISSING", `No coordinator worktree for session ${options.sessionId}.`);
     }
+    const savedProof = await readRunIntegrationProof(commonDir, record);
+    if (savedProof !== null && await git(deps, mainRoot, ["rev-parse", `${record.targetBranch}^{commit}`]) === savedProof.head) {
+        const finished = await finishWorktree(deps, { cwd: mainRoot, name, finalProof: { ...savedProof, recovery: true } });
+        return okEnvelope("TASK_ADVANCED", { ...finished, text: "Recovered the sealed integration without moving the target again." });
+    }
+    if (savedProof !== null && await git(deps, mainRoot, ["rev-parse", `${record.targetBranch}^{commit}`]) !== savedProof.target)
+        await abandonPreparedRunIntegration(commonDir, record, deps.git);
     const parent = await deps.tasks(record.path).status({ taskId: options.parentTaskId });
     if (parent.status !== "active" || parent.task.parentTaskId !== undefined) {
         throw new AgentOpsError("ADVANCE_PARENT_INVALID", "Advance requires an active root task in the coordinator worktree.");
@@ -120,16 +129,42 @@ export async function runAdvanceCommand(options) {
             throw new AgentOpsError("ADVANCE_TASK_TREE_INVALID", "The candidate has unrelated or already completed tasks; final proof must cover one active tree.");
         }
         const ordered = all.filter(({ task }) => selected.has(task.id));
+        const noChangePaths = head === target ? parent.noChangePaths : undefined;
+        if (noChangePaths !== undefined)
+            for (const task of ordered)
+                await deps.tasks(record.path).recordEvidence(task.task.id, {}, undefined, noChangePaths);
+        const onPhase = options.onPhase ?? (async () => { });
+        await onPhase("verifying");
         for (const task of ordered) {
-            requirePass(await step(record.path, ["verify", "--task", task.task.id, "--base", target]), `Verify ${task.task.id}`);
+            const verified = await step(record.path, ["verify", "--task", task.task.id, "--base", target]);
+            await onPhase("verifying", { taskId: task.task.id, update: { verify: verified.status === "ok" ? "PASS" : "FAIL",
+                    ...criteriaProgress(task.task.criteria, verified.data?.report ?? {}) } });
+            requirePass(verified, `Verify ${task.task.id}`);
+        }
+        await onPhase("reviewing");
+        let reviewMode;
+        try {
+            reviewMode = await reviewFinalTree(step, record.path, parent.task.id, ordered.map(({ task }) => task.id), target);
         }
-        const reviewMode = await reviewFinalTree(step, record.path, parent.task.id, ordered.map(({ task }) => task.id), target);
-        const scope = await resolveReviewScope({ root: record.path, runner: runner(deps, record.path), base: target });
+        catch (failure) {
+            for (const { task } of ordered)
+                await onPhase("reviewing", { taskId: task.id, update: { review: "FAIL" } });
+            throw failure;
+        }
+        for (const { task } of ordered)
+            await onPhase("integrating", { taskId: task.id, update: { review: "PASS", passed: task.criteria.length, total: task.criteria.length } });
+        const scope = await resolveReviewScope({ root: record.path, runner: runner(deps, record.path), base: target,
+            ...(noChangePaths === undefined ? {} : { noChangePaths }) });
         const sourceFingerprint = await calculateSourceFingerprint(record.path, scope, runner(deps, record.path));
+        const finalProof = { target, head, sourceFingerprint, children,
+            ...(noChangePaths === undefined ? {} : { noChange: { sourceCommit: head,
+                    contractDigest: await deps.tasks(record.path).treeContract(parent.task.id), reviewScope: scope,
+                    artifactRefs: Object.values((await deps.tasks(record.path).status({ taskId: parent.task.id })).evidence).flat() } }) };
+        await prepareRunIntegration(commonDir, record, finalProof);
         try {
             const finished = await finishWorktree(deps, {
                 cwd: mainRoot, name,
-                finalProof: { target, head, sourceFingerprint, children }
+                finalProof
             });
             if (finished.receipt === undefined)
                 throw new AgentOpsError("WORKTREE_RECEIPT_MISSING", "Finish returned without a final review receipt.");
@@ -144,8 +179,10 @@ export async function runAdvanceCommand(options) {
             });
         }
         catch (failure) {
-            if (failure instanceof AgentOpsError && failure.code === "WORKTREE_TARGET_MOVED" && attempt === 0)
+            if (failure instanceof AgentOpsError && failure.code === "WORKTREE_TARGET_MOVED" && attempt === 0) {
+                await abandonPreparedRunIntegration(commonDir, record, deps.git);
                 continue;
+            }
             throw failure;
         }
     }

package/dist/packages/cli/src/commands/init.js

@@ -13,6 +13,7 @@ export function formatInstallPlan(plan, trust, warnings = []) {
         title: "Installation plan",
         metadata: [
             `Scope: ${plan.scope}`,
+            `Office (Preview): ${plan.config.features.office?.enabled === true ? "enabled" : "disabled"}`,
             `Harness: ${plan.harness}`,
             `Profiles: ${plan.profiles.join(", ")}`,
             ...(plan.config.worktree === undefined
@@ -103,6 +104,7 @@ export async function runInitCommand(options) {
         scope: args.scope,
         harness: args.harness,
         profiles: args.profiles,
+        ...(args.office === undefined ? {} : { officeEnabled: args.office === "on" }),
         adapters: options.adapters,
         ...(options.toolkitVersion === undefined
             ? {}

package/dist/packages/cli/src/commands/office.js

@@ -0,0 +1,20 @@
+import { AgentOpsError } from "../../../../runtime/src/fs/paths.js";
+import { errorEnvelope, okEnvelope } from "../output.js";
+export async function runOfficeCommand(options) {
+    try {
+        const url = await options.ensure();
+        if (url !== null)
+            return okEnvelope("OFFICE_READY", { url, text: `Office (Preview): ${url}` });
+        let shown = "";
+        await options.foreground((served) => {
+            shown = served;
+            options.writeStdout(`Office (Preview): ${served}\nServing in the foreground; it exits 10 minutes after no run or session is active.\n`);
+        });
+        return okEnvelope("OFFICE_CLOSED", { url: shown, text: "Office closed: no run was active for 10 minutes." });
+    }
+    catch (cause) {
+        if (cause instanceof AgentOpsError)
+            return errorEnvelope(cause.code, cause.message);
+        throw cause;
+    }
+}

package/dist/packages/cli/src/commands/review-show.js

@@ -18,7 +18,7 @@ function checkedArtifact(value, fingerprint, taskId) {
     if (typeof value !== "object" || value === null)
         invalid("Review artifact is unreadable.");
     const artifact = value;
-    if (artifact.schemaVersion !== 1 || artifact.sourceFingerprint !== fingerprint ||
+    if (![1, 2].includes(artifact.schemaVersion) || artifact.sourceFingerprint !== fingerprint ||
         artifact.taskId !== taskId || !["PASS", "FAIL", "NOT_RUN"].includes(artifact.status) ||
         !Array.isArray(artifact.attempts) ||
         (artifact.report !== undefined && !validReport(artifact.report, artifact)) ||

package/dist/packages/cli/src/commands/review.js

@@ -4,6 +4,12 @@ import { renderReviewResult } from "../../../../runtime/src/review/render.js";
 import { reviewReportResults } from "../../../../runtime/src/review/report.js";
 import { findPriorFailingFindings, findReviewAttestation, invalidateReviewAttestation, readReviewReportArtifact, reviewReportDigest, saveReviewAttestation, saveReviewReportArtifact } from "../../../../runtime/src/review/attestation.js";
 import { detectHostTarget, planReviewTargets, resolveReviewRole } from "../../../../runtime/src/review/roles.js";
+import { taskContractHash, treeContractHash, goalHash } from "../../../../runtime/src/task/contract.js";
+import { acceptanceCoverage, coverageDigest } from "../../../../runtime/src/verify/acceptance-coverage.js";
+import { resolveGitCommit } from "../../../../runtime/src/verify/change-surface.js";
+import { sha256 } from "../../../../runtime/src/fs/hash.js";
+import { readPrivateFile, writePrivateFile } from "../../../../runtime/src/security/permissions.js";
+import { redactSecrets } from "../../../../runtime/src/security/redact.js";
 import { AgentOpsError } from "../../../../runtime/src/fs/paths.js";
 import { assertSafeSupportingPaths, isReviewerPolicyPath, resolveReviewScope, reviewScopeSignature } from "../../../../runtime/src/review/scope.js";
 import { calculateSourceFingerprint } from "../../../../runtime/src/verify/source-fingerprint.js";
@@ -70,6 +76,7 @@ async function taskContext(options) {
         throw new AgentOpsError("REVIEW_CRITERIA_NOT_FOUND", "Every requested review criterion must exist on the selected task.");
     }
     return {
+        records: [record],
         taskId: record.task.id,
         title: record.task.intent === undefined
             ? record.task.title
@@ -114,7 +121,16 @@ async function treeContext(options) {
     if (treeTasks.some(({ policyConfigHash }) => policyConfigHash !== root.policyConfigHash)) {
         throw new AgentOpsError("REVIEW_TREE_POLICY_MISMATCH", "Tree tasks must share one verifier policy.");
     }
+    const historical = new Set([root.task.id]);
+    for (let size = 0; size !== historical.size;) {
+        size = historical.size;
+        for (const record of all)
+            if (record.task.parentTaskId !== undefined && historical.has(record.task.parentTaskId))
+                historical.add(record.task.id);
+    }
     return {
+        historyRecords: all.filter(record => historical.has(record.task.id) && record.supersededBy !== undefined),
+        records: treeTasks,
         taskId: root.task.id,
         title: [root.task.title, ...treeTasks.map(({ task }) => `Task ${task.id}${task.parentTaskId === undefined ? "" : ` under ${task.parentTaskId}`}: ${task.title}\nModification intent: ${task.intent ?? task.title}`)].join("\n\n"),
         active: treeTasks.every(({ status }) => status === "active"),
@@ -163,7 +179,10 @@ async function currentEvidence(options, context, criterionId, commandId, configH
             evidence.criterionId !== (owner?.criterionId ?? criterionId) ||
             evidence.commandId !== commandId ||
             evidence.configHash !== configHash ||
-            evidence.sourceFingerprint !== sourceFingerprint) {
+            evidence.sourceFingerprint !== sourceFingerprint ||
+            (context.records.some(r => r.task.id === (owner?.taskId ?? context.taskId) &&
+                (r.task.goal !== undefined || (r.task.contractRevision ?? 0) > 0 || r.task.criteria.some(c => c.acceptance !== undefined))) &&
+                evidence.taskContractHash !== taskContractHash(context.records.find(r => r.task.id === (owner?.taskId ?? context.taskId)).task))) {
             stale = true;
             continue;
         }
@@ -190,14 +209,18 @@ async function preflightReview(options, context, sourceFingerprint) {
     const configHash = calculateConfigHash(options.config);
     const commands = [];
     for (const criterion of context.criteria) {
-        for (const commandId of criterion.verifierIds ?? []) {
+        const owner = context.criterionOwners?.get(criterion.id);
+        const typed = context.records.find(r => r.task.id === (owner?.taskId ?? context.taskId))?.task.criteria
+            .find(c => c.id === (owner?.criterionId ?? criterion.id))?.acceptance !== undefined;
+        for (const commandId of new Set([...(criterion.verifierIds ?? []),
+            ...(typed ? options.config.verification.commands.filter(c => c.required).map(c => c.id) : [])])) {
             const command = options.config.verification.commands.find((candidate) => candidate.id === commandId);
             if (command === undefined) {
                 return { ok: false, reason: "missing-verification-evidence" };
             }
             const found = await currentEvidence(options, context, criterion.id, commandId, configHash, sourceFingerprint);
             const compatible = command.evidence.kind === "test-count"
-                ? found.current.filter(({ evidence }) => evidence.schemaVersion === 3)
+                ? found.current.filter(({ evidence }) => evidence.schemaVersion >= 3)
                 : found.current;
             if (command.required && found.current.length > 0 && compatible.length === 0) {
                 return { ok: false, reason: "stale-verification" };
@@ -258,9 +281,11 @@ export async function hasFreshVerification(options, taskId, base) {
     if (context === undefined) {
         return false;
     }
+    options = { ...options, noChangePaths: options.noChangePaths ?? context.records.find(r => r.task.id === context.taskId)?.noChangePaths };
     const scope = await resolveReviewScope({
         root: options.root,
         runner: options.gitRunner,
+        ...(options.noChangePaths === undefined ? {} : { noChangePaths: options.noChangePaths }),
         ...(base === undefined ? {} : { base })
     });
     const fingerprint = await calculateSourceFingerprint(options.root, scope, options.gitRunner);
@@ -352,7 +377,10 @@ async function reusableReview(options, sourceFingerprint, context) {
         return null;
     }
     const attestation = await findReviewAttestation(options.root, sourceFingerprint, context?.taskId);
-    if (attestation === null || attestation.taskId !== context?.taskId) {
+    if (attestation === null || attestation.taskId !== context?.taskId ||
+        (context?.binding !== undefined && (attestation.schemaVersion !== 3 ||
+            JSON.stringify(attestation.taskContracts) !== JSON.stringify(context.binding.taskContracts) ||
+            attestation.coverageDigest !== context.binding.coverageDigest))) {
         return null;
     }
     if (context?.treeTasks !== undefined &&
@@ -420,7 +448,7 @@ async function persistReviewEvidence(options, result, sourceFingerprint, context
     const reportArtifacts = [];
     try {
         for (const taskId of taskIds) {
-            reportArtifacts.push({ taskId, path: await saveReviewReportArtifact(options.root, artifactResult, sourceFingerprint, taskId, complete ? tree : undefined) });
+            reportArtifacts.push({ taskId, path: await saveReviewReportArtifact(options.root, artifactResult, sourceFingerprint, taskId, complete ? tree : undefined, context?.binding === undefined ? undefined : { ...context.binding, taskContractHash: context.binding.taskContracts[taskId ?? context.taskId] }, context?.coverage) });
         }
     }
     catch {
@@ -441,7 +469,8 @@ async function persistReviewEvidence(options, result, sourceFingerprint, context
         const plannedTargets = result.plannedTargets;
         for (const artifact of reportArtifacts) {
             await saveReviewAttestation(options.root, {
-                schemaVersion: 2,
+                schemaVersion: context?.binding === undefined ? 2 : 3,
+                ...(context?.binding === undefined ? {} : { ...context.binding, taskContractHash: context.binding.taskContracts[artifact.taskId ?? context.taskId] }),
                 ...(artifact.taskId === undefined ? {} : { taskId: artifact.taskId }),
                 ...(tree === undefined ? {} : { tree }),
                 harness: result.harness,
@@ -502,6 +531,7 @@ export async function runReviewCommand(options) {
     const context = options.args.tree === true
         ? await treeContext(options)
         : await taskContext(options);
+    options = { ...options, noChangePaths: options.noChangePaths ?? context?.records.find(r => r.task.id === context.taskId)?.noChangePaths };
     const evidenceRequirements = (options.args.evidence ?? []).map((value) => {
         const separator = value.indexOf("=");
         return {
@@ -517,6 +547,7 @@ export async function runReviewCommand(options) {
             scope = await resolveReviewScope({
                 root: options.root,
                 runner: options.gitRunner,
+                ...(options.noChangePaths === undefined ? {} : { noChangePaths: options.noChangePaths }),
                 ...(options.args.base === undefined ? {} : { base: options.args.base })
             });
         }
@@ -574,7 +605,7 @@ export async function runReviewCommand(options) {
             // source was reviewed; it says nothing about the policy in force now or
             // about verification that has failed since, and both of those are
             // decided above.
-            const reused = options.args.rerun || context?.treeTasks !== undefined
+            const reused = options.args.rerun || context?.treeTasks !== undefined || context?.records.some(r => r.task.goal !== undefined || r.task.criteria.some(c => c.acceptance !== undefined) || (r.task.contractRevision ?? 0) > 0)
                 ? null
                 : await reusableReview(options, sourceFingerprint, context);
             if (reused !== null) {
@@ -593,6 +624,23 @@ export async function runReviewCommand(options) {
             pendingInvalidation = false;
         }
     }
+    if (context !== undefined && sourceFingerprint !== undefined && options.config !== undefined &&
+        options.evidenceStore !== undefined && options.gitRunner !== undefined) {
+        const rows = [];
+        for (const record of context.records) {
+            const coverage = await acceptanceCoverage(record, options.config, sourceFingerprint, options.evidenceStore);
+            rows.push(...coverage.map(row => ({ ...row, criterionId: context.treeTasks === undefined
+                    ? row.criterionId : record.task.id + ":" + row.criterionId })));
+        }
+        context.coverage = rows;
+        context.binding = {
+            taskContractHash: taskContractHash(context.records.find(r => r.task.id === context.taskId).task),
+            taskContracts: Object.fromEntries(context.records.map(r => [r.task.id, taskContractHash(r.task)])),
+            ...(context.treeTasks === undefined ? {} : { treeContractHash: treeContractHash(context.records.map(r => r.task)) }),
+            goalHash: goalHash(context.records.find(r => r.task.id === context.taskId).task),
+            candidateCommit: await resolveGitCommit(options.gitRunner, "HEAD"), coverageDigest: coverageDigest(rows)
+        };
+    }
     const criteria = [
         ...(context?.criteria ?? GENERIC_CRITERIA)
     ];
@@ -601,7 +649,44 @@ export async function runReviewCommand(options) {
     }
     let packet;
     try {
+        let contractManifest;
+        const contractArtifacts = [];
+        if (context?.binding !== undefined && options.root !== undefined) {
+            const historicalRefs = new Set([
+                ...[...context.records, ...(context.historyRecords ?? [])].flatMap(r => (r.revisions ?? []).flatMap(revision => Object.values(revision.previousEvidence).flat())),
+                ...(context.historyRecords ?? []).flatMap(r => Object.values(r.evidence).flat())
+            ]);
+            const refs = new Set([...context.records.flatMap(r => Object.values(r.evidence).flat()), ...historicalRefs].filter(ref => !ref.startsWith("review:")));
+            for (const path of refs) {
+                const loaded = await options.evidenceStore?.load(path);
+                if (loaded == null)
+                    continue;
+                if (!historicalRefs.has(path) && loaded.sourceFingerprint !== sourceFingerprint)
+                    continue;
+                const content = await readPrivateFile(options.root + "/" + path, options.root);
+                if (content !== null)
+                    contractArtifacts.push({ path, digest: sha256(content), content });
+                const executionPath = loaded.acceptance?.executionArtifact;
+                if (executionPath !== undefined && !contractArtifacts.some(artifact => artifact.path === executionPath)) {
+                    const execution = await readPrivateFile(options.root + "/" + executionPath, options.root);
+                    if (execution !== null)
+                        contractArtifacts.push({ path: executionPath, digest: sha256(execution), content: execution });
+                }
+            }
+            const content = redactSecrets(JSON.stringify({ binding: context.binding, coverage: context.coverage,
+                executionPolicy: options.config,
+                artifacts: contractArtifacts.map(({ path, digest }) => ({ path, digest })),
+                tasks: context.records.map(r => ({ task: r.task, revisions: r.revisions ?? [] })),
+                superseded: context.historyRecords ?? [] }, null, 2));
+            const digest = sha256(content);
+            const path = ".agent-ops/tasks/review-contracts/" + digest + ".json";
+            contractManifest = { path, digest, content };
+            // Validated before any manifest is written or handed to a snapshot.
+            buildReviewPacket({ request: context.title, criteria, artifactRefs: [], evidenceRequirements, contractManifest, contractArtifacts });
+            await writePrivateFile(options.root + "/" + path, content, options.root);
+        }
         packet = buildReviewPacket({
+            ...(contractManifest === undefined ? {} : { contractManifest, contractArtifacts }),
             request: context?.title ?? GENERIC_REQUEST,
             criteria,
             artifactRefs: scope?.changedFiles ?? [],
@@ -676,6 +761,7 @@ export async function runReviewCommand(options) {
             const postflight = await resolveReviewScope({
                 root: options.root,
                 runner: options.gitRunner,
+                ...(options.noChangePaths === undefined ? {} : { noChangePaths: options.noChangePaths }),
                 ...(options.args.base === undefined ? {} : { base: options.args.base })
             });
             const currentHash = options.currentPolicyConfigHash === undefined
@@ -684,7 +770,12 @@ export async function runReviewCommand(options) {
             const postflightFingerprint = await calculateSourceFingerprint(options.root, postflight, options.gitRunner);
             if (reviewScopeSignature(scope) !== reviewScopeSignature(postflight) ||
                 (options.policyConfigHash !== undefined && currentHash !== options.policyConfigHash) ||
-                postflightFingerprint !== sourceFingerprint) {
+                postflightFingerprint !== sourceFingerprint ||
+                (context?.binding?.treeContractHash !== undefined && options.tasks !== undefined &&
+                    await options.tasks.treeContract(context.taskId) !== context.binding.treeContractHash) ||
+                (context !== undefined && options.tasks !== undefined &&
+                    (await Promise.all(context.records.map(async (r) => taskContractHash((await options.tasks.status({ taskId: r.task.id })).task))))
+                        .some((hash, i) => hash !== taskContractHash(context.records[i].task)))) {
                 const changed = await persistReviewEvidence(options, sourceChangedResult(result), sourceFingerprint, context);
                 return notRunEnvelope(changed);
             }
@@ -712,7 +803,7 @@ export async function runReviewCommand(options) {
                     ? criterion.id : `${record.task.id}:${criterion.id}`;
                 const result = finalResult.results?.find((item) => item.criterionId === id);
                 return [criterion.id, (result?.evidence ?? []).map((reference) => `review:${finalResult.harness}:${reference}`)];
-            })), scope?.mode === "base" ? scope.resolvedBase : null);
+            })), scope?.mode === "base" ? scope.resolvedBase : null, scope?.mode === "base" && scope.noChange === true ? scope.changedFiles : undefined);
         }
     }
     const message = finalResult.status === "PASS"

package/dist/packages/cli/src/commands/run.js

@@ -0,0 +1,115 @@
+import { readFile } from "node:fs/promises";
+import { AgentOpsError, resolveContainedPath } from "../../../../runtime/src/fs/paths.js";
+import { errorEnvelope, okEnvelope } from "../output.js";
+function dynamic(args) {
+    return args;
+}
+function actionOf(args) {
+    const value = dynamic(args).runAction ?? dynamic(args).action;
+    if (value === undefined || value === "start")
+        return "start";
+    if (["status", "logs", "resume", "stop", "respond"].includes(String(value)))
+        return value;
+    throw new AgentOpsError("RUN_ACTION_INVALID", `Unsupported run action: ${String(value)}`);
+}
+function runIdOf(args) {
+    const runId = args.runId ?? dynamic(args).taskId;
+    if (typeof runId !== "string" || runId.length === 0)
+        throw new AgentOpsError("RUN_ID_REQUIRED", "This run action requires a run id.");
+    return runId;
+}
+function textFor(action, state, message) {
+    const active = state.workers.filter((worker) => ["assigned", "starting", "running", "idle", "handing-off"].includes(worker.status)).length;
+    return [
+        message,
+        `Status: ${state.status}`,
+        `Host: ${state.host}`,
+        `Workers: ${active}/${state.jobs}`,
+        `Budget: ${Math.max(0, state.budget.limitMs - state.budget.accumulatedMs)}ms remaining`,
+        `Usage: ${state.budget.usage.tokens ?? "unknown"} tokens; ${state.budget.usage.usd === null ? "unknown" : "$" + state.budget.usage.usd} cost (${state.budget.usage.completeness})`,
+        action === "logs" ? "" : "Native goal completion is not final proof; verify, review, task state, and receipt are still required."
+    ].filter((line) => line.length > 0).join("\n");
+}
+function data(action, result) {
+    return {
+        action,
+        runId: result.state.runId,
+        state: result.state,
+        message: result.message,
+        text: textFor(action, result.state, result.message)
+    };
+}
+function stateData(action, state, message) {
+    return { action, runId: state.runId, state, message, text: textFor(action, state, message) };
+}
+async function goalFromArgs(args, root) {
+    if (args.goal !== undefined && args.goalFile !== undefined)
+        throw new AgentOpsError("RUN_GOAL_CONFLICT", "Use either a positional goal or --goal-file, not both.");
+    if (args.goalFile !== undefined) {
+        const path = await resolveContainedPath(root, args.goalFile);
+        return (await readFile(path, "utf8")).trim();
+    }
+    if (args.goal === undefined || args.goal.trim() === "")
+        throw new AgentOpsError("RUN_GOAL_REQUIRED", "Run start requires a non-empty goal.");
+    return args.goal.trim();
+}
+async function answerFromArgs(args, root) {
+    if (args.answer !== undefined && args.answerFile !== undefined)
+        throw new AgentOpsError("RUN_ANSWER_CONFLICT", "Use either --answer or --answer-file, not both.");
+    if (args.answerFile !== undefined)
+        return (await readFile(await resolveContainedPath(root, args.answerFile), "utf8")).trim();
+    if (args.answer === undefined || args.answer.trim() === "")
+        throw new AgentOpsError("RUN_ANSWER_REQUIRED", "Run respond requires a non-empty answer.");
+    return args.answer.trim();
+}
+/**
+ * External lifecycle surface. The command only starts/controls a supervisor;
+ * it never marks the task complete or treats a native process exit as proof.
+ */
+async function withOffice(options, response) {
+    const url = await options.office?.().catch(() => null) ?? null;
+    return url === null ? response : { ...response, officeUrl: url, text: `${response.text}\nOffice (Preview): ${url}` };
+}
+export async function runRunCommand(options) {
+    const action = actionOf(options.args);
+    try {
+        if (action === "start") {
+            const result = await options.service.start({
+                root: options.root,
+                commonDir: options.commonDir,
+                targetBranch: options.targetBranch,
+                goal: await goalFromArgs(options.args, options.root),
+                host: options.args.host ?? "codex",
+                ownerSessionId: options.ownerSessionId,
+                jobs: options.args.jobs,
+                timeBudgetMs: options.args.timeBudgetMs
+            });
+            const state = options.args.wait === true && options.waitForCompletion !== undefined
+                ? await options.waitForCompletion(result.state.runId)
+                : result.state;
+            const response = await withOffice(options, data(action, { ...result, state }));
+            return okEnvelope(options.args.wait === true ? "RUN_FINISHED" : "RUN_STARTED", response);
+        }
+        const runId = runIdOf(options.args);
+        if (action === "status")
+            return okEnvelope("RUN_STATUS", await withOffice(options, stateData(action, await options.service.status(runId), `Read run ${runId}.`)));
+        if (action === "logs") {
+            const state = await options.service.status(runId);
+            const events = await options.service.logs(runId);
+            return okEnvelope("RUN_LOGS", { ...stateData(action, state, `Read ${events.length} event(s) for run ${runId}.`), events });
+        }
+        if (action === "resume")
+            return okEnvelope("RUN_RESUMED", data(action, await options.service.resume(runId)));
+        if (action === "stop")
+            return okEnvelope("RUN_STOP_REQUESTED", data(action, await options.service.stop(runId, options.args.answer ?? "user requested stop")));
+        const questionId = options.args.questionId;
+        if (questionId === undefined || questionId.trim() === "")
+            throw new AgentOpsError("RUN_QUESTION_REQUIRED", "Run respond requires --question-id.");
+        return okEnvelope("RUN_RESPONDED", data(action, await options.service.respond(runId, questionId, await answerFromArgs(options.args, options.root))));
+    }
+    catch (cause) {
+        if (cause instanceof AgentOpsError)
+            return errorEnvelope(cause.code, cause.message);
+        throw cause;
+    }
+}