@kylecheng3146/agent-ops 0.5.2 → 0.6.0

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

@@ -1,13 +1,19 @@
+import { canonicalJson } from "../config/hash.js";
 import { randomUUID } from "node:crypto";
 import { TASK_SCHEMA_VERSION } from "../contracts.js";
 import { AgentOpsError } from "../fs/paths.js";
-import { validateEvidence, validateTask } from "../schema/validate.js";
+import { validateEvidence, validateTask, validateTaskAgainstConfig } from "../schema/validate.js";
 import { renderTaskMarkdown } from "./render.js";
 import { checkTaskCompletionEvidence, findIncompleteSubtask } from "./completion.js";
 import { calculateConfigHash, FileEvidenceStore, isPassingVerificationEvidence } from "../verify/evidence.js";
 import { resolveReviewScope } from "../review/scope.js";
 import { calculateSourceFingerprint } from "../verify/source-fingerprint.js";
+import { acceptanceCoverage } from "../verify/acceptance-coverage.js";
+import { loadFindingPin } from "./pin-finding.js";
+import { findReviewAttestation } from "../review/attestation.js";
 import { advanceFailureFingerprint } from "../verify/fingerprint.js";
+import { taskContractHash, treeContractHash } from "./contract.js";
+import { commitIdentity } from "../schema/acceptance.js";
 const SESSION_ID_PATTERN = /^[^\0\r\n]{1,256}$/u;
 function defaultTaskId() {
     return `task-${randomUUID()}`;
@@ -86,11 +92,25 @@ export class TaskService {
         if (input.sessionId !== undefined) {
             assertSessionId(input.sessionId);
         }
+        let createdSourceCommit = input.createdSourceCommit;
+        if (createdSourceCommit === undefined && this.#completion !== undefined) {
+            const head = await this.#completion.gitRunner.run(["rev-parse", "--verify", "HEAD"]);
+            const resolved = head.stdout.toString().trim();
+            if (head.exitCode === 0 && commitIdentity(resolved))
+                createdSourceCommit = resolved;
+        }
+        if (createdSourceCommit !== undefined && !commitIdentity(createdSourceCommit))
+            throw taskError("TASK_BASELINE_INVALID", "Task creation commit must be a resolved SHA.");
+        const criteria = structuredClone(input.criteria).map(criterion => ({ ...criterion,
+            ...(criterion.acceptance === undefined ? {} : { acceptance: { ...criterion.acceptance,
+                    baselineCommit: criterion.acceptance.baselineCommit ?? createdSourceCommit } }) }));
         const task = {
             schemaVersion: TASK_SCHEMA_VERSION,
             id: this.#generateId(),
             title: input.title,
-            criteria: [...input.criteria],
+            ...(input.intent === undefined ? {} : { intent: input.intent }),
+            criteria,
+            ...(input.goal === undefined ? {} : { goal: input.goal }),
             ...(input.parentTaskId === undefined
                 ? {}
                 : { parentTaskId: input.parentTaskId })
@@ -99,6 +119,16 @@ export class TaskService {
         if (!validation.ok) {
             throw taskError("TASK_INVALID", validation.errors[0]?.message ?? "Task input is invalid.");
         }
+        if (validation.value.criteria.some(c => c.finding !== undefined))
+            throw taskError("TASK_PIN_REQUIRED", "New finding identities must be validated with pin-finding against a saved failed review.");
+        if (validation.value.criteria.some(c => c.acceptance !== undefined)) {
+            if (this.#completion === undefined)
+                throw taskError("TASK_BASELINE_CONTEXT_REQUIRED", "Typed acceptance requires repository context.");
+            const configured = validateTaskAgainstConfig(validation.value, await this.#completion.loadConfig());
+            if (!configured.ok)
+                throw taskError("TASK_INVALID", configured.errors[0]?.message ?? "Invalid runner binding.");
+            await this.#retainBaselines(validation.value);
+        }
         const now = assertTimestamp(this.#now());
         return await this.#store.mutate((state) => {
             if (state.tasks.some((record) => record.task.id === validation.value.id)) {
@@ -114,9 +144,15 @@ export class TaskService {
                 if (parent.status !== "active") {
                     throw taskError("TASK_PARENT_NOT_ACTIVE", "Only an active task can take new subtasks.");
                 }
+                if (parent.task.goal !== undefined) {
+                    if (validation.value.goal !== undefined && validation.value.goal !== parent.task.goal)
+                        throw taskError("TASK_GOAL_IMMUTABLE", "Subtasks must retain their parent original goal.");
+                    validation.value.goal = parent.task.goal;
+                }
             }
             const record = {
                 task: validation.value,
+                ...(createdSourceCommit === undefined ? {} : { createdSourceCommit }),
                 status: "active",
                 evidence: {},
                 createdAt: now,
@@ -153,6 +189,230 @@ export class TaskService {
             return cloneRecord(record);
         });
     }
+    async #retainBaselines(task) {
+        if (this.#completion === undefined)
+            throw taskError("TASK_BASELINE_CONTEXT_REQUIRED", "Baseline retention needs Git context.");
+        for (const criterion of task.criteria) {
+            const sha = criterion.acceptance?.baselineCommit;
+            if (sha === undefined)
+                continue;
+            const result = await this.#completion.gitRunner.run(["rev-parse", "--verify", sha + "^{commit}"]);
+            if (result.exitCode !== 0 || result.stdout.toString().trim() !== sha)
+                throw taskError("BASELINE_UNAVAILABLE", "Criterion baseline is not the exact available commit.");
+            const retained = await this.#completion.gitRunner.run(["update-ref", "refs/agent-ops/baselines/" + task.id + "/" + criterion.id + "/" + sha, sha]);
+            if (retained.exitCode !== 0)
+                throw taskError("BASELINE_RETENTION_FAILED", "Could not retain criterion baseline.");
+        }
+    }
+    async revise(taskId, input) {
+        if (!/^[a-f0-9]{64}$/u.test(input.expectedContractHash) || input.reason.trim() === "" || input.reason.length > 8192 || input.reason.includes("\0") ||
+            (input.diagnostics ?? []).some(d => d.length > 4096 || d.includes("\0")))
+            throw taskError("TASK_REVISION_INVALID", "Revision requires expected contract and bounded reason/diagnostics.");
+        const previous = await this.status({ taskId });
+        if (previous.status !== "active")
+            throw taskError("TASK_NOT_ACTIVE", "Only active tasks can revise acceptance.");
+        if (taskContractHash(previous.task) !== input.expectedContractHash)
+            throw taskError("TASK_CONTRACT_CHANGED", "Task contract changed.");
+        const baseline = input.baseline ?? previous.createdSourceCommit;
+        const criteria = structuredClone(input.criteria).map(criterion => {
+            if (criterion.acceptance === undefined)
+                return criterion;
+            const sha = criterion.acceptance.baselineCommit ?? baseline;
+            if (sha === undefined)
+                throw taskError("BASELINE_REQUIRED", "Legacy tasks need an explicit baseline before typed acceptance.");
+            const old = previous.task.criteria.find(c => c.id === criterion.id)?.acceptance;
+            if (old !== undefined && sha !== old.baselineCommit)
+                throw taskError("BASELINE_IMMUTABLE", "Create a replacement criterion instead of changing its baseline.");
+            return { ...criterion, acceptance: { ...criterion.acceptance, baselineCommit: sha } };
+        });
+        const next = { ...previous.task, schemaVersion: TASK_SCHEMA_VERSION,
+            contractRevision: (previous.task.contractRevision ?? 0) + 1, criteria };
+        const checked = validateTask(next);
+        if (!checked.ok)
+            throw taskError("TASK_INVALID", checked.errors[0]?.message ?? "Invalid criterion revision.");
+        const records = (await this.#store.read()).tasks;
+        for (const criterion of next.criteria)
+            await this.#validateFindingSource(previous, criterion, records);
+        let policyConfigHash = previous.policyConfigHash;
+        if (this.#completion !== undefined) {
+            const config = await this.#completion.loadConfig();
+            const configured = validateTaskAgainstConfig(next, config);
+            if (!configured.ok)
+                throw taskError("TASK_INVALID", configured.errors[0]?.message ?? "Invalid binding.");
+            policyConfigHash = calculateConfigHash(config);
+        }
+        if (criteria.some(c => c.acceptance !== undefined))
+            await this.#retainBaselines(next);
+        const now = assertTimestamp(this.#now());
+        return await this.#store.mutate(state => {
+            const current = findTask(state, taskId);
+            if (current.status !== "active" || JSON.stringify(current) !== JSON.stringify(previous))
+                throw taskError("TASK_CONTRACT_CHANGED", "Concurrent revision preserved; retry from current task.");
+            const result = { ...current, task: next, evidence: {}, failureFingerprint: null,
+                policyConfigHash, completionBase: null, updatedAt: now,
+                revisions: [...(current.revisions ?? []), { previousTask: current.task, previousEvidence: current.evidence,
+                        previousFailure: current.failureFingerprint, previousHash: input.expectedContractHash,
+                        currentHash: taskContractHash(next), reason: input.reason, diagnostics: [...(input.diagnostics ?? [])], at: now }] };
+            const { reviewBase: _reviewBase, noChangePaths: _paths, ...withoutReview } = result;
+            replaceTask(state, withoutReview);
+            return cloneRecord(withoutReview);
+        });
+    }
+    async replan(taskId, input) {
+        if (input.reason.trim() === "" || input.reason.includes("\0") || input.reason.length > 8192 ||
+            input.tasks.length === 0 || input.tasks.length > 128)
+            throw taskError("TASK_REPLAN_INVALID", "Replan requires bounded children and a reason.");
+        const snapshot = await this.#store.read();
+        const root = findTask(snapshot, taskId);
+        if (root.status !== "active")
+            throw taskError("TASK_NOT_ACTIVE", "Only active roots can be replanned.");
+        const ids = new Set([taskId]);
+        for (let n = 0; n !== ids.size;) {
+            n = ids.size;
+            for (const r of snapshot.tasks)
+                if (r.supersededBy === undefined && r.task.parentTaskId !== undefined && ids.has(r.task.parentTaskId))
+                    ids.add(r.task.id);
+        }
+        const previous = snapshot.tasks.filter(r => ids.has(r.task.id) && r.supersededBy === undefined);
+        if (treeContractHash(previous.map(r => r.task)) !== input.expectedTreeContractHash)
+            throw taskError("TASK_CONTRACT_CHANGED", "Task tree changed.");
+        if (previous.some(r => r.status !== "active"))
+            throw taskError("TASK_REPLAN_INVALID", "Replan cannot replace completed or archived contracts.");
+        if (input.tasks.reduce((count, t) => count + t.replaces.length, 0) > 512)
+            throw taskError("TASK_REPLAN_MAPPING_INVALID", "Replan provenance exceeds its bounded history limit.");
+        const sources = new Map(previous.flatMap(r => r.task.criteria.map(c => [r.task.id + ":" + c.id, c])));
+        const covered = new Set();
+        const now = assertTimestamp(this.#now());
+        const children = [];
+        const config = this.#completion === undefined ? undefined : await this.#completion.loadConfig();
+        for (const planned of input.tasks) {
+            if (planned.replaces.length === 0 || new Set(planned.replaces).size !== planned.replaces.length ||
+                planned.replaces.some(ref => !sources.has(ref)))
+                throw taskError("TASK_REPLAN_MAPPING_INVALID", "Every child must reference existing criterion identities.");
+            for (const ref of planned.replaces)
+                covered.add(ref);
+            for (const c of planned.criteria) {
+                const originals = planned.replaces.map(ref => sources.get(ref)).filter(old => old.id === c.id);
+                if (originals.some(original => original.acceptance !== undefined && c.acceptance?.baselineCommit !== original.acceptance.baselineCommit))
+                    throw taskError("BASELINE_IMMUTABLE", "Replan must preserve criterion baselines.");
+            }
+            for (const criterion of planned.criteria) {
+                if (criterion.finding === undefined)
+                    continue;
+                const inherited = planned.replaces.map(ref => sources.get(ref)).find(c => c.finding?.pinId === criterion.finding.pinId);
+                if (inherited !== undefined) {
+                    if (canonicalJson(inherited.finding) !== canonicalJson(criterion.finding))
+                        throw taskError("TASK_PIN_IMMUTABLE", "Replan must retain immutable finding identity.");
+                }
+                else {
+                    let authorized = false;
+                    for (const record of previous.filter(r => planned.replaces.some(ref => ref.startsWith(r.task.id + ":")))) {
+                        try {
+                            await this.#validateFindingSource(record, criterion, snapshot.tasks);
+                            authorized = true;
+                            break;
+                        }
+                        catch { }
+                    }
+                    if (!authorized)
+                        throw taskError("TASK_PIN_REQUIRED", "New replan pins require a saved failed report bound to the replaced contracts.");
+                }
+            }
+            for (const ref of planned.replaces) {
+                const pin = sources.get(ref).finding?.pinId;
+                if (pin !== undefined && !planned.criteria.some(c => c.finding?.pinId === pin))
+                    throw taskError("TASK_REPLAN_PIN_REQUIRED", "Split contracts must preserve mapped regression pin identities.");
+            }
+            const task = { schemaVersion: TASK_SCHEMA_VERSION, id: planned.id ?? this.#generateId(),
+                title: planned.title, intent: planned.intent, goal: root.task.goal ?? root.task.intent ?? root.task.title,
+                criteria: structuredClone(planned.criteria), parentTaskId: taskId };
+            const checked = config === undefined ? validateTask(task) : validateTaskAgainstConfig(task, config);
+            if (!checked.ok)
+                throw taskError("TASK_INVALID", checked.errors[0]?.message ?? "Invalid split task.");
+            if (task.criteria.some(c => c.acceptance !== undefined))
+                await this.#retainBaselines(task);
+            children.push({ task, status: "active", evidence: {}, createdAt: now, updatedAt: now,
+                completedAt: null, archivedAt: null, failureFingerprint: null, completionBase: null,
+                policyConfigHash: config === undefined ? root.policyConfigHash : calculateConfigHash(config),
+                ...(root.createdSourceCommit === undefined ? {} : { createdSourceCommit: root.createdSourceCommit }) });
+        }
+        if ([...sources.keys()].some(ref => !covered.has(ref)))
+            throw taskError("TASK_REPLAN_COVERAGE_REQUIRED", "Split must account for every previous criterion.");
+        if (new Set(children.map(c => c.task.id)).size !== children.length || children.some(c => snapshot.tasks.some(r => r.task.id === c.task.id)))
+            throw taskError("TASK_ID_CONFLICT", "Split task IDs must be new and unique.");
+        return await this.#store.mutate(state => {
+            if (JSON.stringify(state.tasks) !== JSON.stringify(snapshot.tasks))
+                throw taskError("TASK_CONTRACT_CHANGED", "Concurrent tree change preserved.");
+            const updated = { ...root.task, schemaVersion: TASK_SCHEMA_VERSION, contractRevision: (root.task.contractRevision ?? 0) + 1 };
+            const newRoot = { ...root, task: updated, evidence: {}, failureFingerprint: null, updatedAt: now, completionBase: null,
+                revisions: [...(root.revisions ?? []), { previousTask: root.task, previousEvidence: root.evidence, previousFailure: root.failureFingerprint,
+                        previousHash: taskContractHash(root.task), currentHash: taskContractHash(updated), reason: input.reason, at: now,
+                        diagnostics: input.tasks.flatMap((t, i) => t.replaces.map(ref => ref + " -> " + children[i].task.id)) }] };
+            const { reviewBase: _base, noChangePaths: _paths, ...clearedRoot } = newRoot;
+            replaceTask(state, clearedRoot);
+            for (const old of previous.filter(r => r.task.id !== taskId)) {
+                const successors = children.filter((_child, i) => input.tasks[i].replaces.some(ref => ref.startsWith(old.task.id + ":"))).map(c => c.task.id);
+                replaceTask(state, { ...old, status: "archived", archivedAt: now, updatedAt: now, supersededBy: successors });
+            }
+            state.tasks.push(...children);
+            for (let i = 0; i < state.sessions.length; i++) {
+                const attachment = state.sessions[i];
+                if (ids.has(attachment.taskId))
+                    state.sessions[i] = { ...attachment, taskId, attachedAt: now };
+            }
+            return children.map(cloneRecord);
+        });
+    }
+    /** Import a child worktree's intent and criteria, never its source-bound proof. */
+    async importDelivery(parentTaskId, delivered) {
+        if (delivered.length === 0 || delivered.some(({ status, task }) => (status === "archived" && delivered.find(r => r.task.id === task.id)?.supersededBy === undefined) || task.intent === undefined || task.intent.trim() === "")) {
+            throw taskError("TASK_DELIVERY_INVALID", "Every delivered task needs a recorded intent and must not be archived.");
+        }
+        await this.#store.mutate((state) => {
+            const parent = findTask(state, parentTaskId);
+            if (parent.status !== "active") {
+                throw taskError("TASK_PARENT_NOT_ACTIVE", "Only an active parent can accept delivery.");
+            }
+            const ids = new Set(delivered.map(({ task }) => task.id));
+            if (ids.size !== delivered.length) {
+                throw taskError("TASK_DELIVERY_INVALID", "Delivered task IDs must be unique.");
+            }
+            for (const record of delivered) {
+                const task = {
+                    ...record.task,
+                    ...(record.task.parentTaskId === undefined ? { parentTaskId } : {})
+                };
+                if (task.parentTaskId !== parentTaskId && !ids.has(task.parentTaskId)) {
+                    throw taskError("TASK_DELIVERY_INVALID", `Task ${task.id} has a parent outside this delivery.`);
+                }
+                if (record.policyConfigHash !== parent.policyConfigHash || !validateTask(task).ok) {
+                    throw taskError("TASK_DELIVERY_INVALID", `Task ${task.id} has an incompatible policy or definition.`);
+                }
+                const existing = state.tasks.find((item) => item.task.id === task.id);
+                if (existing !== undefined) {
+                    if (JSON.stringify(existing.task) !== JSON.stringify(task)) {
+                        throw taskError("TASK_ID_CONFLICT", `Task ${task.id} conflicts with an existing task.`);
+                    }
+                    continue;
+                }
+                state.tasks.push({
+                    task,
+                    ...(record.createdSourceCommit === undefined ? {} : { createdSourceCommit: record.createdSourceCommit }),
+                    ...(record.revisions === undefined ? {} : { revisions: structuredClone(record.revisions) }),
+                    ...(record.supersededBy === undefined ? {} : { supersededBy: [...record.supersededBy] }),
+                    status: record.supersededBy === undefined ? "active" : "archived",
+                    evidence: {},
+                    createdAt: record.createdAt,
+                    updatedAt: this.#now(),
+                    completedAt: null,
+                    archivedAt: record.supersededBy === undefined ? null : record.archivedAt,
+                    failureFingerprint: null,
+                    policyConfigHash: record.policyConfigHash,
+                    completionBase: null
+                });
+            }
+        });
+    }
     async list(filter = {}) {
         const state = await this.#store.read();
         return state.tasks
@@ -251,7 +511,8 @@ export class TaskService {
         const fingerprint = async () => {
             try {
                 const scope = await resolveReviewScope({ root: completion.root, runner: completion.gitRunner,
-                    ...(completion.base === undefined ? {} : { base: completion.base }) });
+                    ...(completion.base === undefined ? {} : { base: completion.base }),
+                    ...((current.noChangePaths ?? completion.noChangePaths) === undefined ? {} : { noChangePaths: current.noChangePaths ?? completion.noChangePaths }) });
                 // Recorded so the completion gate can recompute this exact range once
                 // the work is committed and the worktree has nothing left to measure.
                 completionBase = scope.mode === "base" ? scope.resolvedBase : null;
@@ -317,7 +578,7 @@ export class TaskService {
      * A PASS review's base: set records it, null clears it (the review covered
      * uncommitted work), undefined leaves the record's value alone.
      */
-    reviewBase) {
+    reviewBase, noChangePaths) {
         const now = assertTimestamp(this.#now());
         return await this.#store.mutate((state) => {
             const current = findTask(state, taskId);
@@ -347,6 +608,7 @@ export class TaskService {
                 ...rest,
                 evidence,
                 updatedAt: now,
+                ...(noChangePaths === undefined ? {} : { noChangePaths: [...noChangePaths] }),
                 ...(base === undefined ? {} : { reviewBase: base })
             };
             replaceTask(state, updated);
@@ -374,12 +636,15 @@ export class TaskService {
             const validation = validateEvidence(value);
             return validation.ok && validation.value.taskId === snapshot.task.id &&
                 validation.value.criterionId === criterionId && validation.value.commandId === commandId &&
-                validation.value.configHash === configHash && validation.value.sourceFingerprint === sourceFingerprint
+                validation.value.configHash === configHash && validation.value.sourceFingerprint === sourceFingerprint &&
+                (!(snapshot.task.goal !== undefined || (snapshot.task.contractRevision ?? 0) > 0 || snapshot.task.criteria.some(c => c.acceptance !== undefined)) ||
+                    validation.value.taskContractHash === taskContractHash(snapshot.task))
                 ? validation.value : null;
         };
         for (const criterion of snapshot.task.criteria) {
-            const commands = config.verification.commands.filter(({ id, required }) => required && criterion.verifierIds.includes(id));
-            if (commands.length === 0)
+            const commands = config.verification.commands.filter(({ id, required }) => required &&
+                (criterion.acceptance !== undefined || criterion.verifierIds.includes(id)));
+            if (commands.length === 0 && criterion.acceptance === undefined)
                 throw taskError("TASK_REVERIFICATION_CHANGED", "Completed task criteria lack required coverage.");
             for (const command of commands) {
                 let original = false;
@@ -394,7 +659,7 @@ export class TaskService {
                 }
                 for (const reference of evidenceInput[criterion.id] ?? []) {
                     const evidence = matches(await store.load(reference), criterion.id, command.id);
-                    if (evidence !== null && evidence.schemaVersion === 3 &&
+                    if (evidence !== null && evidence.schemaVersion >= 3 &&
                         !snapshot.evidence[criterion.id]?.includes(reference) && isPassingVerificationEvidence(command, evidence))
                         fresh = true;
                 }
@@ -406,13 +671,25 @@ export class TaskService {
         for (const [criterionId, references] of Object.entries(appended)) {
             for (const reference of references) {
                 const validation = validateEvidence(await store.load(reference));
-                if (!validation.ok || !snapshot.task.criteria.find(({ id }) => id === criterionId)?.verifierIds.includes(validation.value.commandId) || matches(validation.value, criterionId, validation.value.commandId) === null) {
+                const criterion = snapshot.task.criteria.find(({ id }) => id === criterionId);
+                const permitted = validation.ok && criterion !== undefined && (criterion.acceptance === undefined
+                    ? criterion.verifierIds.includes(validation.value.commandId)
+                    : validation.value.acceptance === undefined
+                        ? config.verification.commands.some(command => command.id === validation.value.commandId)
+                        : criterion.acceptance.bindings.some(binding => binding.runnerId === validation.value.commandId));
+                if (!validation.ok || !permitted || matches(validation.value, criterionId, validation.value.commandId) === null) {
                     throw taskError("TASK_EVIDENCE_INVALID", "Fresh verification references must belong to this task, criterion, source and config.");
                 }
             }
         }
+        for (const record of [snapshot, { ...snapshot, evidence: appended }]) {
+            const rows = await acceptanceCoverage(record, config, sourceFingerprint, store);
+            if (rows.some(row => (row.mode === "behavioral" || row.mode === "invariant") && row.status !== "proven"))
+                throw taskError("TASK_REVERIFICATION_CHANGED", "Completed mechanical contracts require both original and fresh paired acceptance proof.");
+        }
         const scope = await resolveReviewScope({ root: completion.root, runner: completion.gitRunner,
-            ...(completion.base === undefined ? {} : { base: completion.base }) });
+            ...(completion.base === undefined ? {} : { base: completion.base }),
+            ...(snapshot.noChangePaths === undefined ? {} : { noChangePaths: snapshot.noChangePaths }) });
         if (sourceFingerprint !== await calculateSourceFingerprint(completion.root, scope, completion.gitRunner) ||
             configHash !== calculateConfigHash(await completion.loadConfig())) {
             throw taskError("TASK_REVERIFICATION_CHANGED", "Source or config changed during reverification.");
@@ -480,4 +757,78 @@ export class TaskService {
             });
         });
     }
+    async coverage(taskId) {
+        const record = await this.status({ taskId });
+        const originalMechanical = record.task.criteria.filter(c => {
+            const original = record.revisions?.map(r => r.previousTask.criteria.find(old => old.id === c.id)).find(Boolean) ?? c;
+            return original.acceptance?.mode === "behavioral" || original.acceptance?.mode === "invariant";
+        }).length;
+        const unavailable = () => ({ originalMechanical, reviewed: false, rows: record.task.criteria.map(c => ({ criterionId: c.id,
+                mode: c.acceptance?.mode ?? "legacy", status: "undischarged", evidenceReferences: [],
+                reason: "Current source-bound coverage is unavailable; verify and review the current contract." })) });
+        if (this.#completion === undefined)
+            return unavailable();
+        try {
+            const config = await this.#completion.loadConfig();
+            const base = this.#completion.base ?? record.reviewBase ?? record.completionBase ?? record.createdSourceCommit;
+            const scope = await resolveReviewScope({ root: this.#completion.root, runner: this.#completion.gitRunner,
+                ...(base === undefined ? {} : { base }), ...(record.noChangePaths === undefined ? {} : { noChangePaths: record.noChangePaths }) });
+            const fingerprint = await calculateSourceFingerprint(this.#completion.root, scope, this.#completion.gitRunner);
+            const rows = await acceptanceCoverage(record, config, fingerprint, new FileEvidenceStore(this.#completion.root, this.#completion.root));
+            const attestation = await findReviewAttestation(this.#completion.root, fingerprint, taskId);
+            const reviewed = attestation !== null && (attestation.schemaVersion === 3 ? attestation.taskContracts?.[taskId] === taskContractHash(record.task) :
+                record.task.goal === undefined && (record.task.contractRevision ?? 0) === 0 && record.task.criteria.every(c => c.acceptance === undefined));
+            return { rows, reviewed, originalMechanical };
+        }
+        catch {
+            return unavailable();
+        }
+    }
+    async #validateFindingSource(record, criterion, records) {
+        const finding = criterion.finding;
+        if (finding === undefined)
+            return;
+        const existing = record.task.criteria.find(c => c.finding?.pinId === finding.pinId);
+        if (existing !== undefined) {
+            if (canonicalJson(existing.finding) !== canonicalJson(finding))
+                throw taskError("TASK_PIN_IMMUTABLE", "Finding source identity cannot change.");
+            return;
+        }
+        if (this.#completion === undefined)
+            throw taskError("TASK_PIN_REQUIRED", "New pins require a saved review source.");
+        const { finding: _finding, ...unbound } = criterion;
+        const resolved = await loadFindingPin(this.#completion.root, record, finding.reportDigest + ":" + finding.findingIndex, unbound, records);
+        if (canonicalJson(resolved.finding) !== canonicalJson(finding) || resolved.acceptance?.baselineCommit !== criterion.acceptance?.baselineCommit)
+            throw taskError("TASK_PIN_REQUIRED", "Pin identity and baseline must match the saved failed report.");
+    }
+    async pinFinding(taskId, expectedContractHash, reference, criterion, reason) {
+        if (this.#completion === undefined)
+            throw taskError("TASK_COMPLETION_UNAVAILABLE", "Pin requires a repository and saved review artifacts.");
+        const state = await this.#store.read();
+        const record = findTask(state, taskId);
+        if (record.status !== "active" || taskContractHash(record.task) !== expectedContractHash)
+            throw taskError("TASK_CONTRACT_CHANGED", "Pin requires the current active contract.");
+        const pinned = await loadFindingPin(this.#completion.root, record, reference, criterion, state.tasks);
+        const existing = record.task.criteria.find(c => c.finding?.pinId === pinned.finding?.pinId);
+        if (existing === undefined && record.task.criteria.length === 5)
+            return { record: null, pendingCriterion: pinned };
+        if (existing === undefined && record.task.criteria.some(c => c.id === pinned.id))
+            throw taskError("TASK_CRITERION_ID_CONFLICT", "A new pin requires a new criterion ID.");
+        const criteria = existing === undefined ? [...record.task.criteria, pinned] : record.task.criteria.map(c => c.id === existing.id ? pinned : c);
+        const updated = await this.revise(taskId, { expectedContractHash, criteria,
+            reason: reason ?? "Pin saved review finding " + reference + " against the immutable original goal.", diagnostics: ["finding:" + reference, "pin:" + pinned.finding.pinId] });
+        return { record: updated, pendingCriterion: pinned };
+    }
+    async treeContract(taskId) {
+        const state = await this.#store.read();
+        findTask(state, taskId);
+        const ids = new Set([taskId]);
+        for (let size = 0; size !== ids.size;) {
+            size = ids.size;
+            for (const record of state.tasks)
+                if (record.supersededBy === undefined && record.task.parentTaskId !== undefined && ids.has(record.task.parentTaskId))
+                    ids.add(record.task.id);
+        }
+        return treeContractHash(state.tasks.filter(record => ids.has(record.task.id) && record.supersededBy === undefined).map(record => record.task));
+    }
 }

package/dist/runtime/src/task/store.js

@@ -3,6 +3,8 @@ import { TASK_SCHEMA_VERSION } from "../contracts.js";
 import { AgentOpsError } from "../fs/paths.js";
 import { validateTask } from "../schema/validate.js";
 import { readPrivateFile, withPrivateFileLock, writePrivateFile } from "../security/permissions.js";
+import { taskContractHash } from "./contract.js";
+import { commitIdentity, acceptanceSourcePath } from "../schema/acceptance.js";
 const DEFAULT_MAX_BYTES = 1024 * 1024;
 const SESSION_ID_PATTERN = /^[^\0\r\n]{1,256}$/u;
 function isMissing(error) {
@@ -66,12 +68,9 @@ function parseTaskRecord(value) {
     ];
     // Every record written before an optional field existed must still parse, so
     // the accepted shapes are every combination of them.
-    const optionalKeys = ["completionBase", "failureFingerprint", "policyConfigHash", "reviewBase"];
-    const allowedKeys = new Set(Array.from({ length: 1 << optionalKeys.length }, (_unused, mask) => [
-        ...baseKeys,
-        ...optionalKeys.filter((_key, position) => (mask & (1 << position)) !== 0)
-    ].sort().join("\0")));
-    if (!isRecord(value) || !allowedKeys.has(Object.keys(value).sort().join("\0"))) {
+    const optionalKeys = ["completionBase", "failureFingerprint", "policyConfigHash", "reviewBase", "createdSourceCommit", "revisions", "supersededBy", "noChangePaths"];
+    if (!isRecord(value) || !baseKeys.every(k => Object.hasOwn(value, k)) ||
+        Object.keys(value).some(k => !baseKeys.includes(k) && !optionalKeys.includes(k))) {
         return invalidState("Task state contains an invalid task record.");
     }
     const task = validateTask(value.task);
@@ -150,8 +149,43 @@ function parseTaskRecord(value) {
         (typeof value.reviewBase !== "string" || !/^[a-f0-9]{40,64}$/u.test(value.reviewBase))) {
         return invalidState("Task state contains an invalid review base.");
     }
+    if (value.noChangePaths !== undefined && (!Array.isArray(value.noChangePaths) || value.noChangePaths.length === 0 || value.noChangePaths.length > 128 ||
+        value.noChangePaths.some(p => typeof p !== "string" || !acceptanceSourcePath(p)) || new Set(value.noChangePaths).size !== value.noChangePaths.length))
+        return invalidState("Invalid no-change scope.");
+    if (value.supersededBy !== undefined && (!Array.isArray(value.supersededBy) || value.supersededBy.length === 0 || value.supersededBy.length > 128 ||
+        value.supersededBy.some(v => typeof v !== "string" || !/^[a-z][a-z0-9-]{0,127}$/u.test(v)) || new Set(value.supersededBy).size !== value.supersededBy.length || status !== "archived"))
+        return invalidState("Invalid supersession mapping.");
+    if (value.createdSourceCommit !== undefined && !commitIdentity(value.createdSourceCommit))
+        return invalidState("Invalid task creation commit.");
+    if (value.revisions !== undefined) {
+        if (!Array.isArray(value.revisions) || value.revisions.length > 1024)
+            return invalidState("Invalid revision history.");
+        let previousCurrent;
+        for (const revision of value.revisions) {
+            if (!isRecord(revision) || !hasExactKeys(revision, ["previousTask", "previousEvidence", "previousFailure", "previousHash", "currentHash", "reason", "at", "diagnostics"]) ||
+                typeof revision.reason !== "string" || revision.reason.trim() === "" || revision.reason.length > 8192 || revision.reason.includes("\0") ||
+                !isTimestamp(revision.at) || !Array.isArray(revision.diagnostics) || revision.diagnostics.length > 512 ||
+                revision.diagnostics.some(d => typeof d !== "string" || d.length > 4096 || d.includes("\0")) ||
+                typeof revision.currentHash !== "string" || !/^[a-f0-9]{64}$/u.test(revision.currentHash))
+                return invalidState("Invalid revision metadata.");
+            const before = validateTask(revision.previousTask);
+            if (!before.ok || before.value.id !== task.value.id || taskContractHash(before.value) !== revision.previousHash ||
+                (previousCurrent !== undefined && revision.previousHash !== previousCurrent))
+                return invalidState("Invalid revision chain.");
+            parseEvidence(revision.previousEvidence, before.value, false);
+            if (revision.previousFailure !== null && (!isRecord(revision.previousFailure) || typeof revision.previousFailure.value !== "string" || !/^[a-f0-9]{64}$/u.test(revision.previousFailure.value)))
+                return invalidState("Invalid revision failure provenance.");
+            previousCurrent = revision.currentHash;
+        }
+        if (previousCurrent !== undefined && previousCurrent !== taskContractHash(task.value))
+            return invalidState("Revision history does not match current contract.");
+    }
     return {
         task: task.value,
+        ...(value.noChangePaths === undefined ? {} : { noChangePaths: value.noChangePaths }),
+        ...(value.createdSourceCommit === undefined ? {} : { createdSourceCommit: value.createdSourceCommit }),
+        ...(value.revisions === undefined ? {} : { revisions: value.revisions }),
+        ...(value.supersededBy === undefined ? {} : { supersededBy: value.supersededBy }),
         status,
         evidence,
         createdAt: value.createdAt,
@@ -204,7 +238,7 @@ function parseState(source) {
     }
     if (!isRecord(value) ||
         !hasExactKeys(value, ["schemaVersion", "sessions", "tasks"]) ||
-        value.schemaVersion !== TASK_SCHEMA_VERSION ||
+        (value.schemaVersion !== 1 && value.schemaVersion !== TASK_SCHEMA_VERSION) ||
         !Array.isArray(value.tasks) ||
         !Array.isArray(value.sessions)) {
         return invalidState("Task state has an unsupported structure.");
@@ -217,6 +251,22 @@ function parseState(source) {
         return invalidState("Task and session identifiers must be unique.");
     }
     const tasksById = new Map(tasks.map((record) => [record.task.id, record]));
+    for (const old of tasks) {
+        for (const successor of old.supersededBy ?? []) {
+            if (successor === old.task.id || !tasksById.has(successor))
+                return invalidState("Supersession must name a distinct known task.");
+            const seen = new Set([old.task.id]);
+            const visit = (id) => {
+                if (seen.has(id))
+                    return invalidState("Cyclic task supersession.");
+                seen.add(id);
+                for (const next of tasksById.get(id)?.supersededBy ?? [])
+                    visit(next);
+                seen.delete(id);
+            };
+            visit(successor);
+        }
+    }
     if (sessions.some(({ taskId }) => {
         const record = tasksById.get(taskId);
         return record === undefined || record.status === "archived";