@piagent/platform 1.6.1 → 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-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,
@@ -21,15 +21,14 @@ import {
 export { taskDigestMigrationArchiveStatus } from "./task-digest-state.js";
 import { acceptanceReceiptWithoutWorkingTreeProof, normalizedTaskDigestFields, taskDigestContractValidationErrors } from "./task-digest-contract.js";
 import { unicodeCodePointLength } from "./verification-intelligence.js";
-import {
-  WORKING_TREE_DIGEST_ALGORITHM,
+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,
@@ -41,7 +40,6 @@ 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;
@@ -63,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()
@@ -75,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" });
@@ -113,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);
@@ -137,42 +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));
@@ -226,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));
@@ -329,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;
@@ -411,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 = {
@@ -421,7 +423,9 @@ 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)) : [],
@@ -463,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)
@@ -524,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 [];
@@ -619,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);
@@ -820,7 +856,7 @@ export function workingTreeSnapshot(cwd, options = {}) {
         paths.forEach((file) => protectedAliases.add(file));
     };
     try {
-      const hasHead = gitHasHead(root.cwd); for (const file of workingTreeFilesForGitRoot(root.cwd, observeRename)) {
+      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);
       }

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];

package/packages/piagent-core/extensions/verification-intelligence.js

@@ -11,7 +11,8 @@ import {
   validateFailureClassification,
   validateFailureEvidence
 } from "./failure-types.ts";
-import { isCurrentWorkingTreeDigest } from "./working-tree-digest.js";
+import { isCurrentWorkingTreeDigest, WORKING_TREE_DIGEST_ALGORITHM } from "./working-tree-digest.js";
+import { currentWorkspaceRevisionDigest, isWorkspaceRevisionDigest } from "./workspace-revision.js";
 
 export const MAX_VERIFY_COMMANDS = 2;
 export const MAX_VERIFY_COMMAND_CHARS = 900;
@@ -96,13 +97,18 @@ export function latestObservedVerification(evidence = []) {
   return latest;
 }
 
-export function verificationEvidenceProvesStableTree(entry, digest) {
+export function verificationEvidenceProvesStableTree(entry, digest, workspaceRevisionDigest) {
+  const revisionRequired = workspaceRevisionDigest !== undefined
+    || entry?.preWorkspaceRevisionDigest !== undefined || entry?.workspaceRevisionDigest !== undefined;
   return isCurrentWorkingTreeDigest(digest)
     && entry?.observed === true
     && entry.matchedProfileCommand === true
     && entry.exitCode === 0
+    && entry.isError !== true
     && entry.preWorkingTreeDigest === digest
-    && entry.workingTreeDigest === digest;
+    && entry.workingTreeDigest === digest
+    && (!revisionRequired || (isWorkspaceRevisionDigest(workspaceRevisionDigest)
+      && entry.preWorkspaceRevisionDigest === workspaceRevisionDigest && entry.workspaceRevisionDigest === workspaceRevisionDigest));
 }
 
 export function verificationRunIdentity(cwd, command, changedFiles = []) {
@@ -116,6 +122,24 @@ export function verificationRunIdentity(cwd, command, changedFiles = []) {
     .digest("hex");
 }
 
+export function verificationEvidenceProvesCurrentWorkspace(entry, digest, cwd) {
+  return verificationEvidenceProvesStableTree(entry, digest, currentWorkspaceRevisionDigest(cwd));
+}
+
+/** Historical projections are readable; they do not grant runtime completion/reuse. */
+export function verificationProjectionWorkspaceRevision(task, options = {}) {
+  return options.workspaceRevisionDigest !== undefined ? options.workspaceRevisionDigest
+    : task?.verifyEvidence?.some((entry) => entry.preWorkspaceRevisionDigest !== undefined || entry.workspaceRevisionDigest !== undefined)
+      ? currentWorkspaceRevisionDigest(options.cwd) : undefined;
+}
+
+export function allConfiguredVerifierEvidenceCurrent(task, digest, workspaceRevisionDigest) {
+  if (task?.workingTreeDigestAlgorithm !== WORKING_TREE_DIGEST_ALGORITHM || !isCurrentWorkingTreeDigest(digest)) return false;
+  const commands = meaningfulVerificationCommands(task?.verifyCommands ?? []);
+  const latest = latestObservedVerificationEvidence(task?.verifyEvidence);
+  return commands.length > 0 && commands.every((command) => verificationEvidenceProvesStableTree(latest.get(command.trim()), digest, workspaceRevisionDigest));
+}
+
 const STRUCTURED_SIGNALS = {
   "scope-violation": "structured-scope",
   "protected-path": "structured-protected-path",
@@ -125,7 +149,8 @@ const STRUCTURED_SIGNALS = {
   environment: "structured-environment",
   "flaky-infrastructure": "structured-flaky-infrastructure",
   "stale-verifier": "structured-stale-verifier",
-  "missing-verifier": "structured-missing-verifier"
+  "missing-verifier": "structured-missing-verifier",
+  "verification-gap": "structured-verification-gap"
 };
 
 function parsedSignals(text, exitCode, structuredEvents) {
@@ -189,6 +214,7 @@ function categoryForEvidence(evidence) {
   if (signals.has("structured-provider") || signals.has("provider-rate-limit") || signals.has("provider-transport")) return "provider-network";
   if (signals.has("structured-environment") || signals.has("environment-diagnostic")) return "environment";
   if (signals.has("structured-flaky-infrastructure") || signals.has("local-port-conflict") || signals.has("transient-infrastructure")) return "flaky-infrastructure";
+  if (signals.has("structured-verification-gap")) return "unknown";
   if (signals.has("structured-stale-verifier") || signals.has("structured-missing-verifier") || signals.has("dependency-config-diagnostic")) return "dependency-config";
   if (["typescript-diagnostic", "python-type-diagnostic", "go-compile-diagnostic", "rust-compile-diagnostic", "generic-compile-diagnostic"].some((signal) => signals.has(signal))) return "compile-typecheck";
   if (signals.has("test-assertion-diagnostic")) return "test-assertion";
@@ -250,16 +276,42 @@ export function classifyCompletionGateFailure(missing = [], summary = "", exitCo
     });
   }
   if (missingItems.some((item) => /^critical acceptance evidence\b/i.test(item))) {
-    return classifyVerificationFailure("AssertionError: critical acceptance behavioral proof is missing", 1);
+    // A missing proof is not an observed assertion failure. In particular,
+    // analyzer abstention cannot fabricate source-repair eligibility.
+    return classifyVerificationFailure("Completion gate lacks required behavioral verification evidence.", 1, {
+      structuredEvents: ["verification-gap"]
+    });
   }
   return classifyRecordedVerificationFailure(summary, exitCode);
 }
 
 export function selectCompletionRecoveryClassification(recordedClassification, missing = [], summary = "", exitCode = 1) {
   const gateClassification = classifyCompletionGateFailure(missing, summary, exitCode);
-  return gateClassification.category === "scope-protected-path"
-    ? gateClassification
-    : recordedClassification ?? gateClassification;
+  if (gateClassification.category === "scope-protected-path" || exitCode === 0) return gateClassification;
+  try { return recordedClassification ? validateFailureClassification(recordedClassification) : gateClassification; }
+  catch { return gateClassification; }
+}
+
+/** Reuse a checkpoint classification only for the exact current failed run. */
+export function recordedFailureForObservation(checkpoints, observed, currentTreeDigest, workspaceRevisionDigest) {
+  if (observed?.observed !== true || observed.matchedProfileCommand !== true || observed.exitCode === 0
+    || !isCurrentWorkingTreeDigest(observed.preWorkingTreeDigest) || observed.preWorkingTreeDigest !== observed.workingTreeDigest
+    || (currentTreeDigest !== undefined && currentTreeDigest !== observed.workingTreeDigest)) return undefined;
+  const revisionRequired = workspaceRevisionDigest !== undefined || observed.preWorkspaceRevisionDigest !== undefined || observed.workspaceRevisionDigest !== undefined;
+  if (revisionRequired && (!isWorkspaceRevisionDigest(workspaceRevisionDigest)
+    || observed.preWorkspaceRevisionDigest !== workspaceRevisionDigest || observed.workspaceRevisionDigest !== workspaceRevisionDigest)) return undefined;
+  const observedAt = observed.observedAt ?? observed.recordedAt;
+  if (typeof observedAt !== "string" || !Number.isFinite(Date.parse(observedAt))) return undefined;
+  const checkpoint = (Array.isArray(checkpoints) ? checkpoints : []).filter((item) => {
+    const binding = item?.evidence?.verificationObservation;
+    return item?.phase === "verify" && item.status === "failed" && binding
+      && binding.command === observed.command?.trim() && binding.observedAt === observedAt
+      && binding.exitCode === observed.exitCode && binding.preWorkingTreeDigest === observed.preWorkingTreeDigest
+      && binding.workingTreeDigest === observed.workingTreeDigest
+      && (!revisionRequired || (binding.preWorkspaceRevisionDigest === workspaceRevisionDigest && binding.workspaceRevisionDigest === workspaceRevisionDigest));
+  }).at(-1);
+  try { return checkpoint ? validateFailureClassification(checkpoint.evidence.failureClassification) : undefined; }
+  catch { return undefined; }
 }
 
 export function chooseVerificationScope(profileVerifyCommands = {}, changedFiles = []) {

package/packages/piagent-core/extensions/workflow-catalog.ts

@@ -0,0 +1,98 @@
+export const WORKFLOW_IDS = [
+  "task",
+  "scout",
+  "be-to-fe",
+  "discuss",
+  "plan",
+  "review",
+  "commit",
+  "pr",
+  "onboard",
+  "platform-improve"
+] as const;
+
+export type WorkflowId = typeof WORKFLOW_IDS[number];
+export type ContextWorkflow = "task" | "scout" | "discuss" | "plan" | "review" | "release" | "onboard"
+  | "usage" | "permission" | "context";
+
+export type WorkflowOption = {
+  id: WorkflowId;
+  aliases: readonly string[];
+  label: string;
+  description: string;
+  argumentHint: string;
+  requestRequired: boolean;
+  contextWorkflow: ContextWorkflow;
+  changeMode: "source-change" | "read-only" | "plan-only" | "clarification" | "git" | "onboarding" | "platform";
+  modelUse: "required";
+  recommendedFreshSession: boolean;
+};
+
+/** Surface-neutral workflow truth shared by context classification and runtime ingress. */
+export const WORKFLOW_OPTIONS: readonly WorkflowOption[] = [
+  { id: "task", aliases: ["task", "implement"], label: "Task", description: "Implement a bounded task", argumentHint: "<request>", requestRequired: true, contextWorkflow: "task", changeMode: "source-change", modelUse: "required", recommendedFreshSession: true },
+  { id: "scout", aliases: ["scout", "audit"], label: "Scout", description: "Read-only audit or research", argumentHint: "<area/spec/risk>", requestRequired: true, contextWorkflow: "scout", changeMode: "read-only", modelUse: "required", recommendedFreshSession: true },
+  { id: "be-to-fe", aliases: ["be-to-fe", "befe"], label: "BE → FE", description: "Implement frontend from a backend contract", argumentHint: "<BE spec/change + FE outcome>", requestRequired: true, contextWorkflow: "task", changeMode: "source-change", modelUse: "required", recommendedFreshSession: true },
+  { id: "discuss", aliases: ["discuss", "clarify"], label: "Discuss", description: "Clarify before planning or editing", argumentHint: "<rough idea>", requestRequired: true, contextWorkflow: "discuss", changeMode: "clarification", modelUse: "required", recommendedFreshSession: false },
+  { id: "plan", aliases: ["plan"], label: "Plan", description: "Create an implementation plan", argumentHint: "<goal>", requestRequired: true, contextWorkflow: "plan", changeMode: "plan-only", modelUse: "required", recommendedFreshSession: false },
+  { id: "review", aliases: ["review"], label: "Review", description: "Review a diff or source read-only", argumentHint: "<target or diff>", requestRequired: true, contextWorkflow: "review", changeMode: "read-only", modelUse: "required", recommendedFreshSession: false },
+  { id: "commit", aliases: ["commit"], label: "Commit", description: "Run the guarded local commit workflow", argumentHint: "[message]", requestRequired: false, contextWorkflow: "release", changeMode: "git", modelUse: "required", recommendedFreshSession: false },
+  { id: "pr", aliases: ["pr"], label: "PR", description: "Prepare a guarded pull request", argumentHint: "[title]", requestRequired: false, contextWorkflow: "release", changeMode: "git", modelUse: "required", recommendedFreshSession: false },
+  { id: "onboard", aliases: ["onboard", "onboard-project"], label: "Onboard", description: "Run first-read project onboarding", argumentHint: "[focus]", requestRequired: false, contextWorkflow: "onboard", changeMode: "onboarding", modelUse: "required", recommendedFreshSession: true },
+  { id: "platform-improve", aliases: ["platform-improve", "platform"], label: "Platform improve", description: "Improve Pi Agent Platform itself", argumentHint: "<goal + affected area>", requestRequired: true, contextWorkflow: "task", changeMode: "platform", modelUse: "required", recommendedFreshSession: true }
+] as const;
+
+export const WORKFLOW_ALIASES: Readonly<Record<string, WorkflowId>> = Object.freeze(Object.fromEntries(
+  WORKFLOW_OPTIONS.flatMap((option) => option.aliases.map((alias) => [alias, option.id] as const))
+));
+
+export function resolveWorkflowId(value: unknown): WorkflowId | null {
+  if (typeof value !== "string") return null;
+  return WORKFLOW_ALIASES[value.trim().toLowerCase()] ?? null;
+}
+
+export function workflowOption(value: unknown): WorkflowOption | null {
+  const id = resolveWorkflowId(value);
+  return id ? WORKFLOW_OPTIONS.find((option) => option.id === id) ?? null : null;
+}
+
+export function workflowCommandNames(options: { aliases?: boolean } = {}): string[] {
+  return options.aliases === false ? [...WORKFLOW_IDS] : Object.keys(WORKFLOW_ALIASES);
+}
+
+function escapedPattern(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** A regex fragment derived from the catalog, for command/projection boundaries. */
+export function workflowCommandPattern(options: { aliases?: boolean } = {}): string {
+  return workflowCommandNames(options).sort((left, right) => right.length - left.length)
+    .map(escapedPattern).join("|");
+}
+
+const NAMESPACED_WORKFLOW_COMMAND = new RegExp(
+  `^/(?:piagent-workflow|workflow)\\s+(${workflowCommandPattern()})(?=\\s|$)\\s*`, "i"
+);
+const DIRECT_WORKFLOW_COMMAND = new RegExp(
+  `^/(${workflowCommandPattern({ aliases: false })})(?=\\s|$)\\s*`, "i"
+);
+
+export function workflowIdFromCommand(input: unknown): WorkflowId | null {
+  const normalized = String(input ?? "").trim();
+  const match = NAMESPACED_WORKFLOW_COMMAND.exec(normalized) ?? DIRECT_WORKFLOW_COMMAND.exec(normalized);
+  return resolveWorkflowId(match?.[1]);
+}
+
+export function stripWorkflowCommand(input: string): string {
+  return String(input ?? "").replace(NAMESPACED_WORKFLOW_COMMAND, "").replace(DIRECT_WORKFLOW_COMMAND, "").trim();
+}
+
+export function workflowHelpLines(): string[] {
+  const aliasLines = WORKFLOW_OPTIONS.flatMap((option) => option.aliases.filter((alias) => alias !== option.id)
+    .map((alias) => `/workflow ${alias} → ${option.id}`));
+  return [
+    "namespace: /workflow",
+    ...WORKFLOW_OPTIONS.map((option) => `${option.id}: /workflow ${option.id} ${option.argumentHint} — ${option.description}`),
+    `aliases: ${aliasLines.join(" | ") || "none"}`
+  ];
+}