@piagent/platform 1.2.17 → 1.3.0-ie.8

package/packages/piagent-core/extensions/shell-write-targets.js

@@ -0,0 +1,114 @@
+import {
+  extractAttachedRedirectionPaths,
+  normalizePathCandidate,
+  redirectionTargetWords,
+  shellWords,
+  splitShellSegments
+} from "./policy-core.js";
+
+const MANY_TARGET_COMMANDS = new Set(["mkdir", "prename", "rename", "rm", "rmdir", "tee", "touch", "truncate"]);
+const SOURCE_DESTINATION_COMMANDS = new Set(["cp", "install", "ln", "mv"]);
+const SHELL_INTERPRETERS = new Set(["bash", "sh", "zsh"]);
+const FIND_FILE_OUTPUT_ACTIONS = new Set(["-fprint", "-fprint0", "-fprintf", "-fls"]);
+
+function commandName(value) {
+  return String(value ?? "").split("/").at(-1)?.toLowerCase() ?? "";
+}
+
+function expandAssignments(value, assignments) {
+  return String(value ?? "").replace(/\$(?:\{([A-Za-z_][A-Za-z0-9_]*)\}|([A-Za-z_][A-Za-z0-9_]*))/g, (match, braced, plain) => (
+    assignments.get(braced ?? plain) ?? match
+  ));
+}
+
+function executableWords(words) {
+  let index = 0;
+  while (index < words.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[index])) index += 1;
+  while (["command", "env", "nohup", "sudo", "time"].includes(commandName(words[index]))) {
+    index += 1;
+    while (index < words.length && words[index].startsWith("-")) index += 1;
+    while (index < words.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[index])) index += 1;
+  }
+  return words.slice(index);
+}
+
+function redirectionTargets(words) {
+  const targets = [];
+  for (let index = 0; index < words.length; index += 1) {
+    const token = words[index];
+    const match = token.match(/^\d*(>>?|>\|)(.*)$/);
+    if (!match || /^\d+$/.test(match[2])) continue;
+    const target = match[2] || words[index + 1];
+    if (target && !/^&?\d+$/.test(target)) targets.push(target);
+  }
+  return targets;
+}
+
+export function shellHasFileWriteRedirection(command) {
+  return splitShellSegments(String(command ?? "")).some((segment) => (
+    extractAttachedRedirectionPaths(segment)
+      .filter((redirect) => redirect.writesFile)
+      .flatMap(redirectionTargetWords)
+      .length > 0
+  ));
+}
+
+/** Return only statically visible write destinations; unknown values remain
+ * literal candidates so the task-scope guard rejects them fail closed. */
+export function extractShellWritePathCandidates(command) {
+  const candidates = [];
+  const assignments = new Map();
+  const pending = splitShellSegments(String(command ?? "")).map((segment) => ({ segment, depth: 0 }));
+  const add = (value) => {
+    const normalized = normalizePathCandidate(expandAssignments(value, assignments));
+    if (normalized) candidates.push(normalized);
+  };
+  for (const line of String(command ?? "").split(/\r?\n/)) {
+    const marker = line.match(/^\*\*\* (?:Add|Update|Delete) File:\s*(.+?)\s*$/)
+      ?? line.match(/^\*\*\* Move to:\s*(.+?)\s*$/);
+    if (marker?.[1]) add(marker[1]);
+  }
+  while (pending.length > 0) {
+    const { segment, depth } = pending.shift();
+    const words = shellWords(segment);
+    for (const word of words) {
+      const assignment = word.match(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+      if (assignment) assignments.set(assignment[1], expandAssignments(assignment[2], assignments));
+    }
+    for (const target of redirectionTargets(words)) add(target);
+    const executable = executableWords(words);
+    const name = commandName(executable[0]);
+    const operands = executable.slice(1).filter((word) => word && !word.startsWith("-") && !/^[<>]/.test(word));
+    if (MANY_TARGET_COMMANDS.has(name)) for (const operand of operands) add(operand);
+    // These commands can derive a destination from a source basename, target a
+    // directory selected by -t/--target-directory, and (for mv) remove the
+    // source. Returning every visible operand is intentionally conservative:
+    // an exact-path repair grant must reject any ungranted source/directory
+    // before the command can change the tree.
+    else if (SOURCE_DESTINATION_COMMANDS.has(name)) {
+      for (const operand of operands) add(operand);
+      for (const word of executable.slice(1)) {
+        const attachedTarget = word.match(/^--target-directory=(.+)$/)?.[1]
+          ?? (word !== "-T" ? word.match(/^-t(.+)$/)?.[1] : undefined);
+        if (attachedTarget) add(attachedTarget);
+      }
+    }
+    else if (["chmod", "chown"].includes(name)) for (const operand of operands.slice(1)) add(operand);
+    else if (name === "sed" && executable.some((word) => /^-[^-]*i/.test(word) || word === "--in-place" || word.startsWith("--in-place="))) {
+      for (const operand of operands.slice(1)) add(operand);
+    } else if (name === "dd") {
+      for (const word of executable.slice(1)) if (word.startsWith("of=")) add(word.slice(3));
+    } else if (name === "find") {
+      for (let index = 1; index < executable.length - 1; index += 1) {
+        if (FIND_FILE_OUTPUT_ACTIONS.has(executable[index])) add(executable[index + 1]);
+      }
+    }
+    if (depth < 16 && SHELL_INTERPRETERS.has(name)) {
+      const commandIndex = executable.findIndex((word) => word === "-c" || word === "-lc");
+      if (commandIndex >= 0 && executable[commandIndex + 1]) {
+        for (const nested of splitShellSegments(executable[commandIndex + 1])) pending.push({ segment: nested, depth: depth + 1 });
+      }
+    }
+  }
+  return [...new Set(candidates)];
+}

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

@@ -6,6 +6,46 @@ const LOCK_WAIT_MS = 500;
 const LOCK_STALE_MS = 5_000;
 const sleepBuffer = new Int32Array(new SharedArrayBuffer(4));
 
+function processAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === "EPERM";
+  }
+}
+
+function recoverDeadLock(lockPath) {
+  const recoveryPath = `${lockPath}.recovery`;
+  let recoveryDescriptor;
+  try {
+    recoveryDescriptor = fs.openSync(recoveryPath, "wx", 0o600);
+    let stat;
+    let owner = null;
+    try {
+      stat = fs.lstatSync(lockPath);
+      if (!stat.isFile() || stat.isSymbolicLink()) return false;
+      owner = Number.parseInt(fs.readFileSync(lockPath, "utf8").trim(), 10);
+    } catch (error) {
+      return error?.code === "ENOENT";
+    }
+    const validDeadOwner = Number.isInteger(owner) && owner > 0 && !processAlive(owner);
+    const malformedAndStale = (!Number.isInteger(owner) || owner <= 0) && Date.now() - stat.mtimeMs > LOCK_STALE_MS;
+    if (!validDeadOwner && !malformedAndStale) return false;
+    fs.rmSync(lockPath, { force: true });
+    return true;
+  } catch (error) {
+    if (error?.code === "EEXIST") return false;
+    throw error;
+  } finally {
+    if (recoveryDescriptor !== undefined) {
+      try { fs.closeSync(recoveryDescriptor); } catch {}
+      fs.rmSync(recoveryPath, { force: true });
+    }
+  }
+}
+
 function ensurePrivateParent(filePath, projectRoot) {
   const safeFilePath = projectRoot
     ? resolveLocalStatePath(projectRoot, filePath, { label: "Local JSONL state" })
@@ -30,14 +70,7 @@ function withFileLock(filePath, action) {
       fs.writeFileSync(descriptor, `${process.pid}\n`);
     } catch (error) {
       if (error?.code !== "EEXIST") throw error;
-      try {
-        if (Date.now() - fs.lstatSync(lockPath).mtimeMs > LOCK_STALE_MS) {
-          fs.rmSync(lockPath, { force: true });
-          continue;
-        }
-      } catch (statError) {
-        if (statError?.code === "ENOENT") continue;
-      }
+      if (recoverDeadLock(lockPath)) continue;
       if (Date.now() >= deadline) {
         throw new Error(`Timed out waiting for state lock: ${path.basename(filePath)}`);
       }

package/packages/piagent-core/extensions/task-authority-contract.js

@@ -0,0 +1,16 @@
+import { taskAuthoritySnapshotValidationErrors } from "../capabilities/authority-manifest.ts";
+
+export function taskAuthorityContractValidationErrors(task) {
+  if (task?.authoritySnapshot === undefined) return [];
+  const errors = taskAuthoritySnapshotValidationErrors(task.authoritySnapshot);
+  if (errors.length === 0 && (
+    task.authoritySnapshot.taskId !== task.taskId
+    || task.authoritySnapshot.taskRunId !== task.taskRunId
+    || task.authoritySnapshot.capturedAt !== task.createdAt
+  )) errors.push("task authority snapshot identity/time must match its Task Contract");
+  return errors.map((error) => `authoritySnapshot ${error}`);
+}
+
+export function normalizeTaskAuthoritySnapshot(value) {
+  return value === undefined ? undefined : structuredClone(value);
+}

package/packages/piagent-core/extensions/task-contract-view.js

@@ -0,0 +1,78 @@
+import { acceptanceReceiptProvenanceSummary, acceptanceReceiptSummary } from "./acceptance-receipt.js";
+import { runtimeLifecycleMode } from "./task-lifecycle.js";
+import { latestObservedVerificationEvidence, meaningfulVerificationCommands, verificationEvidenceProvesStableTree } from "./verification-intelligence.js";
+import { isCurrentWorkingTreeDigest, WORKING_TREE_DIGEST_ALGORITHM } from "./working-tree-digest.js";
+
+export function passingVerifyCommandsForDigest(task, digest) {
+  if (task?.workingTreeDigestAlgorithm !== WORKING_TREE_DIGEST_ALGORITHM || !isCurrentWorkingTreeDigest(digest)) return new Set();
+  return new Set([...latestObservedVerificationEvidence(task?.verifyEvidence).values()]
+    .filter((evidence) => verificationEvidenceProvesStableTree(evidence, digest))
+    .map((evidence) => String(evidence.command ?? "").trim()));
+}
+
+export function allVerifyCommandsPassCurrentTree(task, digest) {
+  const planned = meaningfulVerificationCommands(task?.verifyCommands ?? []);
+  if (planned.length === 0) return false;
+  const passing = passingVerifyCommandsForDigest(task, digest);
+  return planned.every((command) => passing.has(command.trim()));
+}
+
+export function compactTaskDetails(task) {
+  return {
+    schemaVersion: task.schemaVersion,
+    taskRunId: task.taskRunId,
+    taskId: task.taskId,
+    sessionId: task.sessionId,
+    sessionName: task.sessionName,
+    changeMode: task.changeMode,
+    attempt: task.attempt,
+    maxAttempts: task.maxAttempts,
+    previousAttempts: task.previousAttempts,
+    riskLane: task.riskLane,
+    intakeMode: task.intakeMode ?? "model",
+    scope: task.scope,
+    verifyGroup: task.verifyGroup,
+    verifyCommands: task.verifyCommands,
+    acceptanceReceipt: acceptanceReceiptSummary(task.acceptanceReceipt),
+    acceptanceProvenance: acceptanceReceiptProvenanceSummary(task.acceptanceReceipt),
+    criterionGraph: task.criterionGraph ? { mode: task.criterionGraph.mode, graphDigest: task.criterionGraph.graphDigest, nodes: task.criterionGraph.nodes.length } : null,
+    authoritySnapshot: task.authoritySnapshot ? { profile: task.authoritySnapshot.profile, manifestDigest: task.authoritySnapshot.manifestDigest, snapshotDigest: task.authoritySnapshot.snapshotDigest } : null,
+    workPlan: task.workPlan,
+    reviewLenses: task.reviewLenses,
+    orchestration: task.orchestration
+      ? {
+          mode: task.orchestration.mode,
+          subagents: task.orchestration.subagents,
+          reason: task.orchestration.reason
+        }
+      : undefined,
+    lifecycleMode: runtimeLifecycleMode(task)
+  };
+}
+
+export function mergeObservedTaskContext(task, entries, maxManifestFiles, redact = (value) => String(value ?? "")) {
+  const known = new Set((task.contextManifest ?? []).map((item) => item.path));
+  const added = [];
+  for (const entry of entries ?? []) {
+    if (task.contextManifest.length >= maxManifestFiles || known.has(entry.path)) continue;
+    task.contextManifest.push({ path: entry.path, reason: redact(entry.reason) });
+    known.add(entry.path);
+    added.push(entry.path);
+  }
+  return added;
+}
+
+export function changedSnapshotFiles(before, after) {
+  return [...new Set([...Object.keys(before ?? {}), ...Object.keys(after ?? {})])]
+    .filter((file) => before?.[file] !== after?.[file])
+    .sort();
+}
+
+/**
+ * Return the exact current task delta, including a task-start dirty file that
+ * was restored or deleted. Runtime mutation history is deliberately excluded:
+ * only the baseline/current evidence pair can authorize review or completion.
+ */
+export function taskDeltaFilesFromSnapshot(task, currentSnapshot) {
+  return changedSnapshotFiles(task?.baselineFileDigests ?? {}, currentSnapshot ?? {});
+}

package/packages/piagent-core/extensions/task-digest-contract.js

@@ -0,0 +1,75 @@
+import crypto from "node:crypto";
+
+import { DIGEST_MIGRATION_SOURCE, LEGACY_UNTRUSTED_DIGEST_ALGORITHM } from "./task-digest-migration.js";
+import { WORKING_TREE_DIGEST_ALGORITHM, workingTreeCarrierDigest } from "./working-tree-digest.js";
+
+const FIELDS = new Set(["status", "source", "reasonCode", "requiredAction", "archivePath", "archiveDigest", "archiveBytes", "baselineEvidenceDigest", "finalEvidenceDigest", "recordedAt", "refreshedAt"]);
+const STATUSES = new Set(["verification-refresh-required", "refreshed", "new-attempt-required", "historical-unverifiable"]);
+const ACTIONS = {
+  "verification-refresh-required": "rerun-exact-verifier", refreshed: "none",
+  "new-attempt-required": "start-new-attempt", "historical-unverifiable": "historical-only"
+};
+const REASONS = {
+  "verification-refresh-required": new Set(["clean-baseline-rebound"]), refreshed: new Set(["clean-baseline-rebound"]),
+  "new-attempt-required": new Set(["semantic-repair-state-present", "read-only-legacy-task", "exact-verifier-plan-missing", "baseline-not-provably-clean", "evidence-root-unavailable", "current-snapshot-unavailable", "legacy-carrier-key-mismatch", "active-task-binding-unavailable", "schema-v1-unversioned", "legacy-untrusted"]),
+  "historical-unverifiable": new Set(["terminal-legacy-evidence", "schema-v1-unversioned", "legacy-untrusted"])
+};
+
+function record(value) { return Boolean(value) && typeof value === "object" && !Array.isArray(value); }
+function timestamp(value) { return typeof value === "string" && value.trim().length > 0 && Number.isFinite(Date.parse(value)); }
+
+export function taskDigestContractValidationErrors(input) {
+  const errors = [], migration = input.workingTreeDigestMigration;
+  if (![WORKING_TREE_DIGEST_ALGORITHM, LEGACY_UNTRUSTED_DIGEST_ALGORITHM].includes(input.workingTreeDigestAlgorithm)) errors.push("workingTreeDigestAlgorithm is invalid or missing");
+  if (migration !== undefined) {
+    if (!record(migration) || Object.keys(migration).some((field) => !FIELDS.has(field)) || !STATUSES.has(migration.status)
+      || migration.source !== DIGEST_MIGRATION_SOURCE || !REASONS[migration.status]?.has(migration.reasonCode)
+      || ACTIONS[migration.status] !== migration.requiredAction || typeof migration.archivePath !== "string"
+      || migration.archivePath !== `.pi/piagent-state/digest-migrations/${input.taskRunId}.legacy.json`
+      || !/^[a-f0-9]{64}$/.test(migration.archiveDigest) || !Number.isInteger(migration.archiveBytes) || migration.archiveBytes < 1
+      || !/^[a-f0-9]{64}$/.test(migration.baselineEvidenceDigest) || !/^[a-f0-9]{64}$/.test(migration.finalEvidenceDigest)
+      || !timestamp(migration.recordedAt) || (migration.refreshedAt !== undefined && (!timestamp(migration.refreshedAt) || Date.parse(migration.refreshedAt) < Date.parse(migration.recordedAt)))) errors.push("workingTreeDigestMigration is invalid");
+  }
+  if (input.workingTreeDigestAlgorithm === LEGACY_UNTRUSTED_DIGEST_ALGORITHM) {
+    if (!migration || !["new-attempt-required", "historical-unverifiable"].includes(migration.status)) errors.push("legacy-untrusted digest tasks require a terminal migration disposition");
+    if (input.trace?.outcome === "pending") errors.push("legacy-untrusted digest tasks cannot remain pending");
+    if (["baselineChangedFiles", "observedChangedFiles", "finalWorkingTreeFiles", "changedFiles", "verifyEvidence"].some((field) => Array.isArray(input[field]) && input[field].length > 0)) errors.push("legacy-untrusted task proof carriers must be empty");
+    if (input.acceptanceReceipt?.provenance !== undefined || input.acceptanceReceipt?.criteria?.some((criterion) => criterion.status !== "pending" || criterion.evidence?.length > 0)) errors.push("legacy-untrusted acceptance proof must remain pending and empty");
+  }
+  if (migration?.status === "verification-refresh-required" && (input.workingTreeDigestAlgorithm !== WORKING_TREE_DIGEST_ALGORITHM || input.trace?.outcome !== "pending")) errors.push("digest refresh requires a pending current-algorithm task");
+  if (migration?.status === "refreshed" && (input.workingTreeDigestAlgorithm !== WORKING_TREE_DIGEST_ALGORITHM || !timestamp(migration.refreshedAt))) errors.push("refreshed digest migration is incomplete");
+  if (["new-attempt-required", "historical-unverifiable"].includes(migration?.status) && input.workingTreeDigestAlgorithm !== LEGACY_UNTRUSTED_DIGEST_ALGORITHM) errors.push("terminal digest migration requires legacy-untrusted algorithm");
+  if (migration?.status === "new-attempt-required" && input.trace?.outcome !== "blocked") errors.push("new-attempt-required migration must be terminal blocked");
+  if (migration?.status === "historical-unverifiable" && input.trace?.outcome === "pending") errors.push("historical-unverifiable migration cannot be pending");
+  return errors;
+}
+
+export function normalizedTaskDigestFields(input, context) {
+  const current = input.schemaVersion === context.schemaVersion && input.workingTreeDigestAlgorithm === WORKING_TREE_DIGEST_ALGORITHM;
+  const legacy = input.schemaVersion !== context.schemaVersion || input.workingTreeDigestAlgorithm === LEGACY_UNTRUSTED_DIGEST_ALGORITHM;
+  const versioned = input.schemaVersion === context.schemaVersion && [WORKING_TREE_DIGEST_ALGORITHM, LEGACY_UNTRUSTED_DIGEST_ALGORITHM].includes(input.workingTreeDigestAlgorithm);
+  const fallback = legacy ? {
+    status: context.trace.outcome === "pending" ? "new-attempt-required" : "historical-unverifiable",
+    source: DIGEST_MIGRATION_SOURCE,
+    reasonCode: input.schemaVersion === context.schemaVersion ? "legacy-untrusted" : "schema-v1-unversioned",
+    requiredAction: context.trace.outcome === "pending" ? "start-new-attempt" : "historical-only",
+    archivePath: `.pi/piagent-state/digest-migrations/${context.taskRunId}.legacy.json`,
+    archiveDigest: context.options.archiveDigest ?? crypto.createHash("sha256").update(JSON.stringify(input)).digest("hex"),
+    baselineEvidenceDigest: workingTreeCarrierDigest("baseline", [], {}), finalEvidenceDigest: workingTreeCarrierDigest("final", [], {}),
+    archiveBytes: context.options.archiveBytes ?? Buffer.byteLength(JSON.stringify(input)), recordedAt: context.updatedAt
+  } : undefined;
+  return {
+    current, legacy,
+    algorithm: current ? WORKING_TREE_DIGEST_ALGORITHM : LEGACY_UNTRUSTED_DIGEST_ALGORITHM,
+    migration: versioned && record(input.workingTreeDigestMigration)
+      ? Object.fromEntries(Object.entries(input.workingTreeDigestMigration).filter(([field]) => FIELDS.has(field)))
+      : fallback
+  };
+}
+
+export function acceptanceReceiptWithoutWorkingTreeProof(value, recordedAt) {
+  if (!record(value) || !Array.isArray(value.criteria)) return value;
+  const receipt = structuredClone(value); delete receipt.provenance;
+  receipt.criteria = receipt.criteria.map((criterion) => ({ ...criterion, status: "pending", evidence: [], updatedAt: recordedAt }));
+  return receipt;
+}

package/packages/piagent-core/extensions/task-digest-migration.js

@@ -0,0 +1,142 @@
+import { isCurrentWorkingTreeDigest, WORKING_TREE_DIGEST_ALGORITHM, workingTreeCarrierDigest } from "./working-tree-digest.js";
+import { latestObservedVerificationEvidence, verificationEvidenceProvesStableTree } from "./verification-intelligence.js";
+
+export const LEGACY_UNTRUSTED_DIGEST_ALGORITHM = "legacy-untrusted";
+export const DIGEST_MIGRATION_SOURCE = "legacy-unversioned";
+
+function pendingReceipt(receipt, recordedAt) {
+  if (!receipt || typeof receipt !== "object" || !Array.isArray(receipt.criteria)) return receipt;
+  const next = structuredClone(receipt);
+  delete next.provenance;
+  next.criteria = next.criteria.map((criterion) => ({
+    ...criterion,
+    status: "pending",
+    evidence: [],
+    updatedAt: recordedAt
+  }));
+  return next;
+}
+
+function pendingReviewPlan(workPlan, recordedAt) {
+  return Array.isArray(workPlan) ? workPlan.map((step) => (
+    step?.mode === "review" && step.status === "done"
+      ? { ...step, status: "pending", note: "Current verifier evidence is required after working-tree digest migration.", updatedAt: recordedAt }
+      : step
+  )) : [];
+}
+
+function migration(status, reasonCode, archivePath, archiveDigest, archiveBytes, recordedAt, task) {
+  const requiredAction = status === "verification-refresh-required"
+    ? "rerun-exact-verifier"
+    : status === "historical-unverifiable"
+      ? "historical-only"
+      : "start-new-attempt";
+  return { status, source: DIGEST_MIGRATION_SOURCE, reasonCode, requiredAction, archivePath, archiveDigest, archiveBytes, recordedAt,
+    baselineEvidenceDigest: workingTreeCarrierDigest("baseline", task.baselineChangedFiles, task.baselineFileDigests),
+    finalEvidenceDigest: workingTreeCarrierDigest("final", task.finalWorkingTreeFiles, task.finalFileDigests) };
+}
+
+function withoutLegacyProof(raw) {
+  const receipt = pendingReceipt(raw.acceptanceReceipt, raw.updatedAt ?? raw.createdAt ?? new Date().toISOString());
+  return {
+    ...raw,
+    baselineChangedFiles: [],
+    baselineFileDigests: {},
+    observedChangedFiles: [],
+    finalWorkingTreeFiles: [],
+    finalFileDigests: {},
+    changedFiles: [],
+    verifyEvidence: [],
+    acceptanceReceipt: receipt
+  };
+}
+
+/** Plan a one-time, fail-closed migration without reinterpreting any old hash. */
+export function planUnversionedTaskDigestMigration(raw, options) {
+  const recordedAt = options.recordedAt;
+  const archivePath = options.archivePath;
+  const terminal = raw?.trace?.outcome && raw.trace.outcome !== "pending";
+  const cleanBaseline = Array.isArray(raw?.baselineChangedFiles)
+    && raw.baselineChangedFiles.length === 0
+    && raw.baselineFileDigests
+    && typeof raw.baselineFileDigests === "object"
+    && !Array.isArray(raw.baselineFileDigests)
+    && Object.keys(raw.baselineFileDigests).length === 0;
+
+  if (terminal) {
+    const task = { ...withoutLegacyProof(raw), workingTreeDigestAlgorithm: LEGACY_UNTRUSTED_DIGEST_ALGORITHM };
+    task.workingTreeDigestMigration = migration("historical-unverifiable", "terminal-legacy-evidence", archivePath, options.archiveDigest, options.archiveBytes, recordedAt, task);
+    return {
+      task,
+      disposition: "historical"
+    };
+  }
+
+  if (!options.sourceChange || !options.verifierPlanSafe || !cleanBaseline || options.semanticRepairPresent || !options.evidenceRootSafe || !options.keyBindingSafe || !options.snapshotSafe || !options.activeBindingSafe) {
+    const reasonCode = options.semanticRepairPresent
+      ? "semantic-repair-state-present"
+      : !options.sourceChange
+        ? "read-only-legacy-task"
+        : !options.verifierPlanSafe
+          ? "exact-verifier-plan-missing"
+        : !cleanBaseline
+          ? "baseline-not-provably-clean"
+          : !options.evidenceRootSafe
+            ? "evidence-root-unavailable"
+            : !options.snapshotSafe
+              ? "current-snapshot-unavailable"
+              : !options.keyBindingSafe
+                ? "legacy-carrier-key-mismatch"
+                : "active-task-binding-unavailable";
+    const task = {
+        ...withoutLegacyProof(raw),
+        workingTreeDigestAlgorithm: LEGACY_UNTRUSTED_DIGEST_ALGORITHM,
+        failedAt: "verify",
+        failureReason: `Working-tree digest migration blocked: ${reasonCode}. Start a bounded new attempt.`,
+        trace: {
+          outcome: "blocked",
+          friction: `Legacy working-tree evidence is not replayable (${reasonCode}).`,
+          notes: "The original contract was archived without reinterpreting its digests.",
+          recordedAt
+        }
+      };
+    task.workingTreeDigestMigration = migration("new-attempt-required", reasonCode, archivePath, options.archiveDigest, options.archiveBytes, recordedAt, task);
+    return { task, disposition: "blocked" };
+  }
+
+  const currentFiles = Object.keys(options.currentSnapshot ?? {}).sort();
+  const task = {
+      ...raw,
+      workingTreeDigestAlgorithm: WORKING_TREE_DIGEST_ALGORITHM,
+      baselineChangedFiles: [],
+      baselineFileDigests: {},
+      observedChangedFiles: currentFiles,
+      finalWorkingTreeFiles: currentFiles,
+      finalFileDigests: { ...(options.currentSnapshot ?? {}) },
+      changedFiles: currentFiles,
+      verifyEvidence: [],
+      acceptanceReceipt: pendingReceipt(raw.acceptanceReceipt, recordedAt),
+      workPlan: pendingReviewPlan(raw.workPlan, recordedAt),
+      updatedAt: recordedAt
+    };
+  task.workingTreeDigestMigration = migration("verification-refresh-required", "clean-baseline-rebound", archivePath, options.archiveDigest, options.archiveBytes, recordedAt, task);
+  return { task, disposition: "refresh" };
+}
+
+export function completeTaskDigestRefresh(task, currentWorkingTreeDigest) {
+  if (task?.workingTreeDigestAlgorithm !== WORKING_TREE_DIGEST_ALGORITHM || !isCurrentWorkingTreeDigest(currentWorkingTreeDigest) || task?.workingTreeDigestMigration?.status !== "verification-refresh-required") return task;
+  const commands = [...new Set((task.verifyCommands ?? []).map((value) => String(value).trim()).filter(Boolean))];
+  const currentPassing = new Set([...latestObservedVerificationEvidence(task.verifyEvidence).values()]
+    .filter((entry) => verificationEvidenceProvesStableTree(entry, currentWorkingTreeDigest))
+    .map((entry) => String(entry.command).trim()));
+  if (commands.length === 0 || commands.some((command) => !currentPassing.has(command))) return task;
+  return {
+    ...task,
+    workingTreeDigestMigration: {
+      ...task.workingTreeDigestMigration,
+      status: "refreshed",
+      requiredAction: "none",
+      refreshedAt: new Date(Math.max(Date.now(), Date.parse(task.workingTreeDigestMigration.recordedAt) || 0)).toISOString()
+    }
+  };
+}