@piagent/platform 1.6.0 → 1.7.1

package/packages/piagent-core/extensions/task-journal.js

@@ -4,6 +4,7 @@ import path from "node:path";
 
 import { redactForStorage } from "./redaction-core.js";
 import { ensurePrivateStateDirectory, resolveLocalStatePath } from "./local-state-path.js";
+import { recoveryDecisionValidationErrors } from "./recovery-decision-validation.ts";
 import { isCurrentWorkingTreeDigest } from "./working-tree-digest.js";
 
 export const TASK_JOURNAL_SCHEMA_VERSION = 1;
@@ -47,6 +48,30 @@ function compactId(value, fallback = "unknown") {
     .slice(0, 160) || fallback;
 }
 
+function checkpointMatchesTask(event, task) {
+  return typeof task?.taskId === "string" && task.taskId.length > 0
+    && typeof task?.taskRunId === "string" && task.taskRunId.length > 0
+    && typeof task?.sessionId === "string" && task.sessionId.length > 0
+    && event.taskRunId === compactId(task.taskRunId)
+    && event.taskId === compactId(task?.taskId)
+    && event.sessionId === String(task?.sessionId)
+    && event.data?.attempt === task?.attempt;
+}
+
+function terminalHandoffCheckpoint(checkpoint, task) {
+  const recovery = checkpoint?.evidence?.recovery;
+  return checkpoint?.checkpointId === "completion"
+    && ["failed", "blocked"].includes(String(checkpoint.status))
+    && recoveryDecisionValidationErrors(recovery).length === 0
+    && recovery.taskId === task?.taskId
+    && recovery.taskRunId === task?.taskRunId
+    && recovery.taskAttempt === task?.attempt
+    && recovery.action === "handoff"
+    && recovery.continuation === "none"
+    && recovery.nextPhase === null
+    && recovery.sourceMutationAllowed === false;
+}
+
 function safeData(value) {
   const redacted = redactForStorage(value ?? {});
   const serialized = JSON.stringify(redacted);
@@ -411,6 +436,9 @@ export function replayTaskCheckpoints(cwd, taskRunId, task) {
   const checkpoints = new Map();
   const idempotency = new Set();
   const corruptions = [...journal.corruptions];
+  if (task && compactId(taskRunId) !== compactId(task.taskRunId)) {
+    corruptions.push("checkpoint replay taskRunId does not match the Task Contract");
+  }
   const migrationEvents = journal.events.filter((event) => event.eventType === "digest-migrated");
   const invalidMigration = migrationEvents.find((event) => !validDigestMigrationBarrier(event));
   if (invalidMigration) corruptions.push(`digest migration sequence ${invalidMigration.sequence}: marker is invalid`);
@@ -422,8 +450,12 @@ export function replayTaskCheckpoints(cwd, taskRunId, task) {
     ? undefined
     : [...migrationEvents].reverse().find((event) => digestMigrationBarrierMatchesTask(event, task));
   for (const event of journal.events) {
-    if (migrationBarrier && event.sequence <= migrationBarrier.sequence) continue;
     if (event.eventType !== "checkpoint") continue;
+    if (task && !checkpointMatchesTask(event, task)) {
+      corruptions.push(`checkpoint sequence ${event.sequence}: identity does not match the Task Contract`);
+      continue;
+    }
+    if (migrationBarrier && event.sequence <= migrationBarrier.sequence) continue;
     const treeErrors = checkpointTreeDigestValidationErrors(event.data?.evidence);
     if (treeErrors.length > 0) {
       corruptions.push(`checkpoint sequence ${event.sequence}: ${treeErrors[0]}`);
@@ -432,14 +464,18 @@ export function replayTaskCheckpoints(cwd, taskRunId, task) {
     if (event.idempotencyKey && idempotency.has(event.idempotencyKey)) continue;
     if (event.idempotencyKey) idempotency.add(event.idempotencyKey);
     const checkpointId = event.checkpointId ?? "checkpoint";
-    checkpoints.set(checkpointId, {
+    const checkpoint = {
       checkpointId,
       taskRunId: event.taskRunId,
       sessionId: event.sessionId,
       sequence: event.sequence,
       recordedAt: event.recordedAt,
       ...event.data
-    });
+    };
+    const existing = checkpoints.get(checkpointId);
+    if (!terminalHandoffCheckpoint(existing, task) || terminalHandoffCheckpoint(checkpoint, task)) {
+      checkpoints.set(checkpointId, checkpoint);
+    }
   }
   return {
     taskRunId,
@@ -470,6 +506,15 @@ export function taskRecoveryDecision(task, replay = { checkpoints: [], corruptio
     };
   }
   const checkpoints = Array.isArray(replay.checkpoints) ? replay.checkpoints : [];
+  const terminalHandoff = checkpoints.findLast((checkpoint) => terminalHandoffCheckpoint(checkpoint, task));
+  if (terminalHandoff) {
+    return {
+      decision: "blocked",
+      retryAllowed: false,
+      checkpointId: terminalHandoff.checkpointId,
+      reason: `Checkpoint ${terminalHandoff.checkpointId} recorded a terminal recovery handoff; inspect that handoff before any retry.`
+    };
+  }
   const contractSteps = Array.isArray(task?.workPlan) ? task.workPlan : [];
   const contractOpen = contractSteps.findLast((step) => ["in-progress", "failed"].includes(String(step?.status)));
   const latestOpen = contractOpen

package/packages/piagent-core/extensions/task-lifecycle.js

@@ -195,3 +195,35 @@ export function applyRuntimeLifecycleObservation(task, observation, recordedAt =
   }
   return { changed, mode };
 }
+
+/**
+ * A default assisted read-only review is a presentation checkpoint, not a
+ * second reasoning pass. Once runtime-owned read evidence exists and the model
+ * emits its final handoff, completing this one exact checkpoint preserves the
+ * substantive answer instead of forcing a token-heavy retry. Custom/manual
+ * plans and every source-change review remain explicit.
+ */
+export function applyAssistedReadOnlyFinalHandoff(
+  task,
+  { durableReadEvidence = false, finalHandoffObserved = false } = {},
+  recordedAt = new Date().toISOString()
+) {
+  const mode = runtimeLifecycleMode(task);
+  if (mode !== "assisted-readonly" || !durableReadEvidence || !finalHandoffObserved) {
+    return { changed: false, mode };
+  }
+  const scout = task.workPlan.find((step) => step.id === "scout");
+  const review = task.workPlan.find((step) => step.id === "review");
+  if (scout?.status !== "done" || review?.status !== "in-progress") {
+    return { changed: false, mode };
+  }
+  return {
+    changed: setStep(
+      review,
+      "done",
+      "Runtime observed a final handoff grounded in durable read-only evidence.",
+      recordedAt
+    ),
+    mode
+  };
+}

package/packages/piagent-core/extensions/task-runtime-audit.js

@@ -34,7 +34,8 @@ export function recordMutationCheckpoint(ctx, task, evidence = {}) {
 export function recordVerificationCheckpoint(ctx, task, verification = {}) {
   const observation = verification.observedAt ?? task.updatedAt;
   const preTree = verification.preWorkingTreeDigest ?? verification.evidence?.preWorkingTreeDigest;
-  const identity = crypto.createHash("sha256").update(JSON.stringify([verification.commandHash, preTree, verification.workingTreeDigest, verification.exitCode, observation])).digest("hex");
+  const preRevision = verification.evidence?.preWorkspaceRevisionDigest, revision = verification.evidence?.workspaceRevisionDigest;
+  const identity = crypto.createHash("sha256").update(JSON.stringify([verification.commandHash, preTree, verification.workingTreeDigest, verification.exitCode, observation, preRevision, revision])).digest("hex");
   return recordRuntimeTaskCheckpoint(ctx, {
     taskRunId: task.taskRunId,
     taskId: task.taskId,
@@ -45,7 +46,12 @@ export function recordVerificationCheckpoint(ctx, task, verification = {}) {
     phase: "verify",
     status: verification.exitCode === 0 ? "done" : "failed",
     attempt: task.attempt,
-    evidence: verification.evidence
+    evidence: { ...verification.evidence, verificationObservation: {
+      command: String(verification.evidence?.command ?? "").trim(), observedAt: observation, exitCode: verification.exitCode,
+      ...(preTree ? { preWorkingTreeDigest: preTree } : {}),
+      ...(preRevision ? { preWorkspaceRevisionDigest: preRevision } : {}), ...(revision ? { workspaceRevisionDigest: revision } : {}),
+      ...(verification.workingTreeDigest ? { workingTreeDigest: verification.workingTreeDigest } : {})
+    } }
   });
 }
 

package/packages/piagent-core/extensions/task-state.js

@@ -3,8 +3,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { ensurePrivateStateDirectory, resolveLocalStatePath } from "./local-state-path.js";
 import { appendTaskJournalEvent, readTaskJournal } from "./task-journal.js";
-import {
-  acceptanceReceiptProvenanceSummary,
+import { acceptanceReceiptProvenanceSummary,
   acceptanceReceiptSummary,
   acceptanceReceiptValidationErrors,
   normalizeAcceptanceReceipt
@@ -12,6 +11,7 @@ import {
 import { LEGACY_UNTRUSTED_DIGEST_ALGORITHM } from "./task-digest-migration.js";
 import { criterionGraphValidationErrors, normalizeCriterionGraph } from "./criterion-graph.js";
 import { normalizeTaskAuthoritySnapshot, taskAuthorityContractValidationErrors } from "./task-authority-contract.js";
+import { normalizeTerminalDisposition, validTerminalDisposition } from "./task-terminal-disposition.js";
 import {
   commitLegacySchemaTaskDigestState,
   migrateUnversionedTaskDigestState,
@@ -20,15 +20,15 @@ import {
 } from "./task-digest-state.js";
 export { taskDigestMigrationArchiveStatus } from "./task-digest-state.js";
 import { acceptanceReceiptWithoutWorkingTreeProof, normalizedTaskDigestFields, taskDigestContractValidationErrors } from "./task-digest-contract.js";
-import {
-  WORKING_TREE_DIGEST_ALGORITHM,
+import { unicodeCodePointLength } from "./verification-intelligence.js";
+import { isWorkspaceRevisionDigest } from "./workspace-revision.js";
+import { WORKING_TREE_DIGEST_ALGORITHM,
   isCurrentWorkingTreeDigest,
   isUnavailableWorkingTreeDigest,
   unavailableWorkingTreeHash,
   versionWorkingTreeHash
 } from "./working-tree-digest.js";
-import {
-  directChildGitEvidenceRoots,
+import { directChildGitEvidenceRoots,
   gitEvidenceRootDetails,
   gitEvidenceRoots,
   gitOutput,
@@ -40,13 +40,17 @@ import {
   prefixedGitPath
 } from "./workspace-evidence-roots.js";
 export { isGitWorkingTree } from "./workspace-evidence-roots.js";
-
 export const TASK_CONTRACT_SCHEMA_VERSION = 2; export const DEFAULT_MAX_TASK_ATTEMPTS = 3;
+export const OPERATOR_REQUEST_MAX_CHARS = 8_000;
+export const TASK_SUMMARY_MAX_CHARS = 2_000;
+export const TASK_EXPECTED_OUTPUT_MAX_CHARS = 2_000;
+export const TASK_ACCEPTANCE_CRITERION_MAX_CHARS = 1_000;
+export const TASK_ACCEPTANCE_CRITERIA_MAX = 12;
 const TASK_OUTCOMES = ["pending", "completed", "blocked", "partial", "failed"], TERMINAL_TASK_OUTCOMES = new Set(["completed", "blocked", "partial", "failed"]);
 const REVIEW_LENSES = ["correctness", "tests", "scope", "security", "docs", "release", "package"];
 const TASK_CONTRACT_FIELDS = new Set([
   "schemaVersion", "taskRunId", "taskId", "sessionId", "sessionName", "changeMode", "mutationPolicy", "attempt", "maxAttempts",
-  "previousAttempts", "summary", "riskLane", "intakeMode", "expectedOutput", "acceptanceCriteria", "criterionGraph", "scope", "outOfScope",
+  "previousAttempts", "summary", "operatorRequest", "operatorRequestDigest", "riskLane", "intakeMode", "expectedOutput", "acceptanceCriteria", "criterionGraph", "scope", "outOfScope",
   "protectedPaths", "requiredContext", "contextManifest", "memoryCitations", "mcpCapabilities", "verifyGroup",
   "verifyCommands", "workPlan", "reviewLenses", "orchestration", "acceptanceReceipt", "authoritySnapshot", "workingTreeDigestAlgorithm", "workingTreeDigestMigration", "baselineChangedFiles", "baselineFileDigests",
   "observedChangedFiles", "finalWorkingTreeFiles", "finalFileDigests", "changedFiles", "verifyEvidence", "trace",
@@ -57,8 +61,8 @@ const CITATION_FIELDS = new Set(["path", "reason"]);
 const WORK_PLAN_FIELDS = new Set(["id", "title", "role", "mode", "status", "dependsOn", "note", "updatedAt"]);
 const ORCHESTRATION_FIELDS = new Set(["mode", "subagents", "reason", "fieldGuidePath", "modelRoles"]);
 const MODEL_ROLE_FIELDS = new Set(["planner", "worker", "reviewer", "watchdog"]);
-const VERIFY_EVIDENCE_FIELDS = new Set(["command", "exitCode", "summary", "recordedAt", "observed", "observedAt", "isError", "matchedProfileCommand", "preWorkingTreeDigest", "workingTreeDigest"]);
-const TRACE_FIELDS = new Set(["outcome", "friction", "notes", "recordedAt"]);
+const VERIFY_EVIDENCE_FIELDS = new Set(["command", "exitCode", "summary", "recordedAt", "observed", "observedAt", "isError", "matchedProfileCommand", "preWorkingTreeDigest", "workingTreeDigest", "preWorkspaceRevisionDigest", "workspaceRevisionDigest"]);
+const TRACE_FIELDS = new Set(["outcome", "terminalDisposition", "friction", "notes", "recordedAt"]);
 export function safeTaskId(value) {
   const normalized = String(value ?? "")
     .trim()
@@ -69,26 +73,21 @@ export function safeTaskId(value) {
     .replace(/-+$/g, "");
   return normalized || "task";
 }
-
 function stateRoot(cwd) { return path.join(cwd, ".pi", "piagent-state"); }
 function tasksRoot(cwd) { return path.join(stateRoot(cwd), "tasks"); }
 function sessionsRoot(cwd) { return path.join(stateRoot(cwd), "session-tasks"); }
-
 function taskRunPath(cwd, taskRunId) {
   return path.join(tasksRoot(cwd), `${safeTaskId(taskRunId)}.json`);
 }
-
 function sessionBindingPath(cwd, sessionId) {
   const digest = crypto.createHash("sha256").update(String(sessionId || "unknown")).digest("hex");
   return path.join(sessionsRoot(cwd), `${digest}.json`);
 }
-
 function readTaskRun(cwd, taskRunId) {
   const raw = readJson(cwd, taskRunPath(cwd, taskRunId));
   const task = normalizeTaskContract(raw, { sourceName: taskRunId });
   return task?.taskRunId === safeTaskId(taskRunId) ? task : undefined;
 }
-
 function readJson(cwd, filePath) {
   try {
     const safePath = resolveLocalStatePath(cwd, filePath, { label: "Task state", kind: "file" });
@@ -107,21 +106,34 @@ function readJson(cwd, filePath) {
     return undefined;
   }
 }
-
 function writeJsonAtomic(cwd, filePath, value) {
   const parent = ensurePrivateStateDirectory(cwd, path.dirname(filePath), "Task state directory");
   const safePath = resolveLocalStatePath(cwd, filePath, { label: "Task state" });
   const temporary = path.join(parent, `${path.basename(safePath)}.${process.pid}.${crypto.randomBytes(4).toString("hex")}.tmp`);
-  fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
-  fs.renameSync(temporary, safePath);
   try {
+    const bytes = Buffer.from(`${JSON.stringify(value, null, 2)}\n`);
+    const descriptor = fs.openSync(temporary, fs.constants.O_WRONLY | fs.constants.O_CREAT
+      | fs.constants.O_EXCL | (fs.constants.O_NOFOLLOW ?? 0), 0o600);
+    try {
+      for (let offset = 0; offset < bytes.length;) {
+        const written = fs.writeSync(descriptor, bytes, offset, bytes.length - offset);
+        if (written < 1) throw new Error("Task state write was incomplete");
+        offset += written;
+      }
+      fs.fsyncSync(descriptor);
+    } finally {
+      fs.closeSync(descriptor);
+    }
+    fs.renameSync(temporary, safePath);
     fs.chmodSync(parent, 0o700);
     fs.chmodSync(safePath, 0o600);
+    const directory = fs.openSync(parent, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    try { fs.fsyncSync(directory); } finally { fs.closeSync(directory); }
   } catch {
-    // Best effort on filesystems that do not expose POSIX modes.
+    try { fs.unlinkSync(temporary); } catch {}
+    throw new Error("Task state atomic persistence failed");
   }
 }
-
 function appendTaskStateJournalEvent(cwd, event) {
   try {
     return appendTaskJournalEvent(cwd, event);
@@ -131,34 +143,33 @@ function appendTaskStateJournalEvent(cwd, event) {
     return undefined;
   }
 }
-
 function stringArray(value) {
   return Array.isArray(value) ? [...new Set(value.filter((item) => typeof item === "string" && item.trim()).map((item) => item.trim()))] : [];
 }
-
+function exactCommandArray(value) {
+  return Array.isArray(value) ? [...new Set(value.filter((item) => typeof item === "string" && item.trim()))] : [];
+}
 function stringRecord(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return {};
   return Object.fromEntries(Object.entries(value)
     .filter(([key, item]) => key && typeof item === "string")
     .map(([key, item]) => [key.replaceAll("\\", "/"), item]));
 }
-
 function positiveInteger(value, fallback, maximum = Number.MAX_SAFE_INTEGER) {
   return Number.isInteger(value) && value > 0 ? Math.min(value, maximum) : fallback;
 }
-
 function validTimestamp(value) {
   return typeof value === "string" && value.trim().length > 0 && Number.isFinite(Date.parse(value));
 }
-
+export function operatorRequestDigest(value) {
+  return `operator-request-v1:${crypto.createHash("sha256").update(String(value ?? "")).digest("hex")}`;
+}
 function normalizedTimestamp(value, fallback) {
   return validTimestamp(value) ? value : fallback;
 }
-
 function isRecord(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
-
 function unsupportedObjectField(value, allowed) {
   if (!isRecord(value)) return undefined;
   return Object.keys(value).find((key) => !allowed.has(key));
@@ -191,6 +202,16 @@ export function taskContractValidationErrors(input) {
   if (typeof input.taskId === "string" && safeTaskId(input.taskId) !== input.taskId) errors.push("taskId must be normalized");
   if (typeof input.summary === "string" && input.summary.trim().length < 10) errors.push("summary must be at least 10 characters");
   if (typeof input.expectedOutput === "string" && input.expectedOutput.trim().length < 10) errors.push("expectedOutput must be at least 10 characters");
+  const hasOperatorRequest = input.operatorRequest !== undefined;
+  const hasOperatorRequestDigest = input.operatorRequestDigest !== undefined;
+  if (hasOperatorRequest !== hasOperatorRequestDigest) errors.push("operatorRequest and operatorRequestDigest must be present together");
+  if (hasOperatorRequest) {
+    if (typeof input.operatorRequest !== "string" || !input.operatorRequest.trim()) errors.push("operatorRequest must be a non-empty string");
+    else {
+      if (unicodeCodePointLength(input.operatorRequest) > OPERATOR_REQUEST_MAX_CHARS) errors.push(`operatorRequest must contain at most ${OPERATOR_REQUEST_MAX_CHARS} Unicode characters`);
+      if (input.operatorRequestDigest !== operatorRequestDigest(input.operatorRequest)) errors.push("operatorRequestDigest does not match operatorRequest");
+    }
+  }
   for (const field of ["createdAt", "updatedAt"]) {
     if (typeof input[field] === "string" && !validTimestamp(input[field])) errors.push(`${field} must be a valid timestamp`);
   }
@@ -202,8 +223,8 @@ export function taskContractValidationErrors(input) {
   }
   if (input.failedAt !== undefined && !["research", "plan", "execute", "verify", "review"].includes(input.failedAt)) errors.push("failedAt is invalid");
   if (!["source-change", "read-only"].includes(input.changeMode)) errors.push("changeMode is invalid");
-  if (input.mutationPolicy !== undefined && !["required", "forbidden"].includes(input.mutationPolicy)) errors.push("mutationPolicy is invalid");
-  if (input.changeMode === "read-only" && input.mutationPolicy === "required") errors.push("read-only tasks cannot require mutation");
+  if (input.mutationPolicy !== undefined && !["required", "allowed", "forbidden"].includes(input.mutationPolicy)) errors.push("mutationPolicy is invalid");
+  if (input.changeMode === "read-only" && input.mutationPolicy !== undefined && input.mutationPolicy !== "forbidden") errors.push("read-only tasks must forbid mutation");
   if (!["tiny", "normal", "high-risk"].includes(input.riskLane)) errors.push("riskLane is invalid");
   if (input.intakeMode !== undefined && !["model", "runtime"].includes(input.intakeMode)) errors.push("intakeMode is invalid");
   errors.push(...taskDigestContractValidationErrors(input));
@@ -305,13 +326,16 @@ export function taskContractValidationErrors(input) {
     || (item.matchedProfileCommand !== undefined && typeof item.matchedProfileCommand !== "boolean")
     || (item.preWorkingTreeDigest !== undefined && !isCurrentWorkingTreeDigest(item.preWorkingTreeDigest))
     || (item.workingTreeDigest !== undefined && !isCurrentWorkingTreeDigest(item.workingTreeDigest))
+    || (item.preWorkspaceRevisionDigest !== undefined && !isWorkspaceRevisionDigest(item.preWorkspaceRevisionDigest))
+    || (item.workspaceRevisionDigest !== undefined && !isWorkspaceRevisionDigest(item.workspaceRevisionDigest))
   ))) {
     errors.push("verifyEvidence entries are invalid");
   }
   if (!isRecord(input.trace) || unsupportedObjectField(input.trace, TRACE_FIELDS) || !TASK_OUTCOMES.includes(input.trace.outcome)) {
     errors.push("trace.outcome is invalid");
-  } else if (input.trace.recordedAt !== undefined && !validTimestamp(input.trace.recordedAt)) {
-    errors.push("trace.recordedAt must be a valid timestamp");
+  } else {
+    if (!validTerminalDisposition(input.trace)) errors.push("trace.terminalDisposition is invalid");
+    if (input.trace.recordedAt !== undefined && !validTimestamp(input.trace.recordedAt)) errors.push("trace.recordedAt must be a valid timestamp");
   }
   if (input.orchestration !== undefined) {
     const orchestration = input.orchestration;
@@ -387,7 +411,9 @@ export function normalizeTaskContract(input, options = {}) {
         isError: item.isError,
         matchedProfileCommand: item.matchedProfileCommand,
         preWorkingTreeDigest: item.preWorkingTreeDigest,
-        workingTreeDigest: item.workingTreeDigest
+        workingTreeDigest: item.workingTreeDigest,
+        preWorkspaceRevisionDigest: item.preWorkspaceRevisionDigest,
+        workspaceRevisionDigest: item.workspaceRevisionDigest
       } : item)
     : [];
   const normalized = {
@@ -397,11 +423,15 @@ export function normalizeTaskContract(input, options = {}) {
     sessionId,
     sessionName: String(input.sessionName ?? options.sessionName ?? "").trim() || undefined,
     changeMode: input.changeMode === "read-only" ? "read-only" : "source-change",
-    mutationPolicy: input.changeMode === "read-only" || input.mutationPolicy === "forbidden" ? "forbidden" : "required",
+    mutationPolicy: input.changeMode === "read-only" || input.mutationPolicy === "forbidden"
+      ? "forbidden"
+      : input.mutationPolicy === "allowed" ? "allowed" : "required",
     attempt: positiveInteger(input.attempt, 1, 100),
     maxAttempts: positiveInteger(input.maxAttempts, DEFAULT_MAX_TASK_ATTEMPTS, 10),
     previousAttempts: Array.isArray(input.previousAttempts) ? input.previousAttempts.slice(-10).map((item) => pickFields(item, PREVIOUS_ATTEMPT_FIELDS)) : [],
     summary: typeof input.summary === "string" ? input.summary : "",
+    operatorRequest: typeof input.operatorRequest === "string" && input.operatorRequest.trim() ? input.operatorRequest : undefined,
+    operatorRequestDigest: typeof input.operatorRequestDigest === "string" && input.operatorRequestDigest.trim() ? input.operatorRequestDigest : undefined,
     riskLane: ["tiny", "normal", "high-risk"].includes(input.riskLane) ? input.riskLane : "normal",
     intakeMode: ["model", "runtime"].includes(input.intakeMode) ? input.intakeMode : "model",
     expectedOutput: typeof input.expectedOutput === "string" ? input.expectedOutput : "", acceptanceCriteria: stringArray(input.acceptanceCriteria),
@@ -413,7 +443,7 @@ export function normalizeTaskContract(input, options = {}) {
     memoryCitations: Array.isArray(input.memoryCitations) ? input.memoryCitations.map((item) => pickFields(item, CITATION_FIELDS)) : [],
     mcpCapabilities: stringArray(input.mcpCapabilities),
     verifyGroup: typeof input.verifyGroup === "string" && input.verifyGroup.trim() ? input.verifyGroup.trim() : undefined,
-    verifyCommands: stringArray(input.verifyCommands),
+    verifyCommands: exactCommandArray(input.verifyCommands),
     workPlan: Array.isArray(input.workPlan) ? input.workPlan.map((item) => pickFields(item, WORK_PLAN_FIELDS)) : [],
     reviewLenses: stringArray(input.reviewLenses),
     acceptanceReceipt: normalizeAcceptanceReceipt(legacyDigestContract
@@ -437,6 +467,7 @@ export function normalizeTaskContract(input, options = {}) {
     verifyEvidence: legacyDigestContract ? [] : verifyEvidence,
     trace: {
       outcome: legacyDigestContract && trace.outcome === "pending" ? "blocked" : TASK_OUTCOMES.includes(trace.outcome) ? trace.outcome : "pending",
+      terminalDisposition: normalizeTerminalDisposition(trace),
       friction: legacyDigestContract && trace.outcome === "pending" ? "Legacy working-tree evidence is not replayable; start a new attempt." : typeof trace.friction === "string" ? trace.friction : undefined,
       notes: typeof trace.notes === "string" ? trace.notes : undefined,
       recordedAt: legacyDigestContract && trace.outcome === "pending" ? updatedAt : trace.recordedAt === undefined ? undefined : normalizedTimestamp(trace.recordedAt, updatedAt)
@@ -498,6 +529,37 @@ export function writeTaskContract(cwd, task) {
   return normalized;
 }
 
+/** Confirms the exact normalized task bytes through a stable, fsync-backed read. */
+export function durableTaskContractMatches(cwd, expected) {
+  try {
+    const normalized = normalizeTaskContract(expected);
+    if (!normalized || taskContractValidationErrors(normalized).length > 0) return false;
+    const safePath = resolveLocalStatePath(cwd, taskRunPath(cwd, normalized.taskRunId), {
+      label: "Task state", kind: "file"
+    });
+    const descriptor = fs.openSync(safePath, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    try {
+      fs.fsyncSync(descriptor);
+      const before = fs.fstatSync(descriptor, { bigint: true });
+      if (!before.isFile() || before.nlink !== 1n || before.size < 1n
+        || before.size > BigInt(8 * 1024 * 1024)) return false;
+      const bytes = fs.readFileSync(descriptor);
+      const after = fs.fstatSync(descriptor, { bigint: true });
+      const atPath = fs.lstatSync(safePath, { bigint: true });
+      const fields = ["dev", "ino", "mode", "nlink", "size", "mtimeNs", "ctimeNs"];
+      if (bytes.length !== Number(before.size) || atPath.isSymbolicLink()
+        || fields.some((field) => before[field] !== after[field] || after[field] !== atPath[field])) return false;
+      const observed = normalizeTaskContract(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)));
+      return observed?.taskRunId === normalized.taskRunId
+        && JSON.stringify(observed) === JSON.stringify(normalized);
+    } finally {
+      fs.closeSync(descriptor);
+    }
+  } catch {
+    return false;
+  }
+}
+
 export function listTaskContracts(cwd) {
   const root = resolveLocalStatePath(cwd, tasksRoot(cwd), { label: "Task state directory" });
   if (!fs.existsSync(root)) return [];
@@ -593,9 +655,9 @@ function gitHasHead(cwd) {
   }
 }
 
-function workingTreeFilesForGitRoot(cwd, observeRename) {
-  if (!isGitWorkingTree(cwd)) return [];
-  const changed = gitHasHead(cwd)
+function workingTreeFilesForGitRoot(cwd, observeRename, knownHead = null) {
+  if (knownHead === null && !isGitWorkingTree(cwd)) return [];
+  const changed = (knownHead ?? gitHasHead(cwd))
     ? changedPathsFromNameStatus(gitOutput(cwd, ["diff", "--name-status", "-z", "--find-renames", "--diff-filter=ACMRD", "HEAD", "--"]), observeRename)
     : gitOutput(cwd, ["ls-files", "-z"]).split("\0").filter(Boolean);
   const untracked = gitOutput(cwd, ["ls-files", "--others", "--exclude-standard", "-z"]).split("\0").filter(Boolean);
@@ -691,6 +753,10 @@ function changedPathsFromNameStatus(output, observeRename) {
 }
 
 const WORKING_TREE_STREAM_CHUNK_BYTES = 1024 * 1024;
+// This path cannot collide with enumerated project evidence because `.pi` is
+// intentionally excluded from workspace discovery. Its unavailable digest
+// turns a partial inventory into an explicitly non-proof-capable snapshot.
+const WORKING_TREE_ENUMERATION_EVIDENCE_PATH = ".pi/piagent-state/.working-tree-enumeration-unavailable";
 function unavailableWorkingTreeDigest(file, reason, stat) {
   return unavailableWorkingTreeHash(crypto.createHash("sha256")
     .update(`${file}\0${reason}\0${stat?.mode ?? ""}\0${stat?.size ?? ""}\0${stat?.mtimeMs ?? ""}\0${stat?.ctimeMs ?? ""}`)
@@ -770,7 +836,18 @@ function streamedWorkingTreeFileDigest(root, file, hasHead, protectedProjectPath
 export function workingTreeSnapshot(cwd, options = {}) {
   const snapshot = {};
   const isProtectedProjectPath = typeof options.isProtectedProjectPath === "function" ? options.isProtectedProjectPath : () => false;
-  const roots = gitEvidenceRoots(cwd);
+  let rootDetails;
+  try {
+    rootDetails = gitEvidenceRootDetails(cwd);
+  } catch (error) {
+    snapshot[WORKING_TREE_ENUMERATION_EVIDENCE_PATH] = unavailableWorkingTreeDigest(
+      WORKING_TREE_ENUMERATION_EVIDENCE_PATH,
+      `root-enumeration:${error?.code ?? "failed"}`
+    );
+    return snapshot;
+  }
+  const roots = rootDetails.roots;
+  const incompleteReasons = rootDetails.complete ? [] : ["root-enumeration-incomplete"];
   for (const root of roots) {
     const protectedAliases = new Set();
     const observeRename = (source, destination) => {
@@ -778,13 +855,33 @@ export function workingTreeSnapshot(cwd, options = {}) {
       if (paths.some((file) => file === ".pi/piagent-state" || file.startsWith(".pi/piagent-state/") || isProtectedProjectPath(prefixedGitPath(root.prefix, file))))
         paths.forEach((file) => protectedAliases.add(file));
     };
-    const hasHead = gitHasHead(root.cwd); for (const file of workingTreeFilesForGitRoot(root.cwd, observeRename)) {
-      const projectPath = prefixedGitPath(root.prefix, file);
-      snapshot[projectPath] = streamedWorkingTreeFileDigest(root.cwd, file, hasHead, isProtectedProjectPath(projectPath) || protectedAliases.has(file) ? projectPath : null);
+    try {
+      const hasHead = gitHasHead(root.cwd); for (const file of workingTreeFilesForGitRoot(root.cwd, observeRename, hasHead)) {
+        const projectPath = prefixedGitPath(root.prefix, file);
+        snapshot[projectPath] = streamedWorkingTreeFileDigest(root.cwd, file, hasHead, isProtectedProjectPath(projectPath) || protectedAliases.has(file) ? projectPath : null);
+      }
+    } catch {
+      incompleteReasons.push(`git-root-enumeration-incomplete:${root.prefix || "."}`);
     }
-  } if (!isGitWorkingTree(cwd) && roots.length > 0) for (const file of nonGitWorkspaceFiles(cwd, roots.map((root) => root.prefix))) {
+  }
+  if (!roots.some((root) => root.prefix === "") && roots.length > 0) {
+    const looseDetails = nonGitWorkspaceFileDetails(
+      cwd,
+      roots.map((root) => root.prefix),
+      options.maxNonGitWorkspaceFiles
+    );
+    for (const file of looseDetails.files) {
       snapshot[file] = nonGitWorkspaceFileDigest(cwd, file, isProtectedProjectPath(file) ? file : null);
-  } return snapshot;
+    }
+    if (!looseDetails.complete) incompleteReasons.push("non-git-enumeration-incomplete");
+  }
+  if (incompleteReasons.length > 0) {
+    snapshot[WORKING_TREE_ENUMERATION_EVIDENCE_PATH] = unavailableWorkingTreeDigest(
+      WORKING_TREE_ENUMERATION_EVIDENCE_PATH,
+      incompleteReasons.sort().join(",")
+    );
+  }
+  return snapshot;
 }
 
 export function taskStateMigrationStatus(cwd) {

package/packages/piagent-core/extensions/task-terminal-disposition.js

@@ -0,0 +1,10 @@
+/** @param {Record<string, unknown>} trace */
+export function validTerminalDisposition(trace) {
+  return trace.terminalDisposition === undefined
+    || trace.terminalDisposition === "refused" && trace.outcome === "blocked";
+}
+
+/** @param {Record<string, unknown>} trace @returns {"refused" | undefined} */
+export function normalizeTerminalDisposition(trace) {
+  return trace.terminalDisposition === "refused" && trace.outcome === "blocked" ? "refused" : undefined;
+}

package/packages/piagent-core/extensions/trajectory-contract.ts

@@ -0,0 +1,5 @@
+export const TRAJECTORY_PHASES = Object.freeze([
+  "intake", "scout", "plan", "execute", "verify", "repair", "review", "handoff", "terminal"
+] as const);
+
+export type TrajectoryPhase = typeof TRAJECTORY_PHASES[number];