@piagent/platform 1.5.5 → 1.6.1

package/packages/piagent-core/runtime/quality/edit-freshness-guard.ts

@@ -0,0 +1,102 @@
+import path from "node:path";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { currentFileContentDigests } from "./model-mutation-proof.ts";
+
+export type EditFreshnessMode = "off" | "observe" | "enforce";
+export type EditFreshnessSource = "read" | "mutation";
+export type EditFreshnessEvaluation = {
+  decision: "off" | "unobserved" | "current" | "stale";
+  checkedPaths: string[];
+  stalePaths: string[];
+  enforce: boolean;
+};
+
+type SessionContext = Pick<ExtensionContext, "cwd" | "sessionManager">;
+type Snapshot = { digest: string; taskRunId: string; source: EditFreshnessSource; recordedAt: string };
+type SessionState = { identity: string; snapshots: Map<string, Snapshot> };
+
+const MAX_SNAPSHOTS_PER_SESSION = 256;
+
+function normalizeProjectPath(cwd: string, candidate: string): string | undefined {
+  if (!candidate || candidate.includes("\0")) return undefined;
+  const absolute = path.isAbsolute(candidate) ? path.resolve(candidate) : path.resolve(cwd, candidate);
+  const relative = path.relative(cwd, absolute).split(path.sep).join("/");
+  return relative && relative !== "." && relative !== ".." && !relative.startsWith("../") && !path.isAbsolute(relative)
+    ? relative
+    : undefined;
+}
+
+export function editFreshnessModeFromEnvironment(value: unknown): EditFreshnessMode {
+  const normalized = String(value ?? "").trim().toLowerCase();
+  if (["0", "false", "no", "off", "disabled"].includes(normalized)) return "off";
+  if (["observe", "shadow", "advisory"].includes(normalized)) return "observe";
+  return "enforce";
+}
+
+/**
+ * Binds an edit to the complete file version last delivered by a successful
+ * read (or produced by a successful Piagent mutation). Files that have no
+ * observed snapshot retain the host tool's existing exact-anchor policy; the
+ * pilot only rejects proven drift, so it cannot invent a read requirement.
+ */
+export class EditFreshnessGuard {
+  readonly #mode: EditFreshnessMode;
+  readonly #sessions = new WeakMap<SessionContext["sessionManager"], SessionState>();
+
+  constructor(mode: EditFreshnessMode = "enforce") { this.#mode = mode; }
+
+  #identity(ctx: SessionContext): string {
+    return `${path.resolve(ctx.cwd)}\0${ctx.sessionManager.getSessionId()}`;
+  }
+
+  #session(ctx: SessionContext): SessionState {
+    const identity = this.#identity(ctx), existing = this.#sessions.get(ctx.sessionManager);
+    if (existing?.identity === identity) return existing;
+    const created = { identity, snapshots: new Map<string, Snapshot>() };
+    this.#sessions.set(ctx.sessionManager, created);
+    return created;
+  }
+
+  observe(
+    ctx: SessionContext,
+    taskRunId: string | undefined,
+    targetPaths: string[],
+    source: EditFreshnessSource,
+    recordedAt = new Date().toISOString()
+  ): string[] {
+    if (this.#mode === "off" || !taskRunId) return [];
+    const normalized = [...new Set(targetPaths.map((item) => normalizeProjectPath(ctx.cwd, item)).filter(Boolean) as string[])];
+    const digests = currentFileContentDigests(ctx.cwd, normalized), session = this.#session(ctx), observed: string[] = [];
+    for (const file of normalized) {
+      const digest = digests[file];
+      if (!digest) continue;
+      session.snapshots.delete(file);
+      session.snapshots.set(file, { digest, taskRunId, source, recordedAt });
+      observed.push(file);
+    }
+    while (session.snapshots.size > MAX_SNAPSHOTS_PER_SESSION) {
+      session.snapshots.delete(session.snapshots.keys().next().value as string);
+    }
+    return observed;
+  }
+
+  evaluate(ctx: SessionContext, taskRunId: string | undefined, targetPaths: string[]): EditFreshnessEvaluation {
+    if (this.#mode === "off") return { decision: "off", checkedPaths: [], stalePaths: [], enforce: false };
+    if (!taskRunId) return { decision: "unobserved", checkedPaths: [], stalePaths: [], enforce: this.#mode === "enforce" };
+    const session = this.#session(ctx);
+    const tracked = [...new Set(targetPaths.map((item) => normalizeProjectPath(ctx.cwd, item)).filter(Boolean) as string[])]
+      .filter((file) => session.snapshots.get(file)?.taskRunId === taskRunId);
+    if (tracked.length === 0) return { decision: "unobserved", checkedPaths: [], stalePaths: [], enforce: this.#mode === "enforce" };
+    const current = currentFileContentDigests(ctx.cwd, tracked);
+    const stalePaths = tracked.filter((file) => current[file] !== session.snapshots.get(file)?.digest);
+    return {
+      decision: stalePaths.length > 0 ? "stale" : "current",
+      checkedPaths: tracked,
+      stalePaths,
+      enforce: this.#mode === "enforce"
+    };
+  }
+
+  clear(ctx: SessionContext): void { this.#sessions.delete(ctx.sessionManager); }
+}

package/packages/piagent-core/runtime/quality/exact-output-contract.ts

@@ -1,7 +1,9 @@
 import fs from "node:fs";
 import path from "node:path";
 
+import { durableContextEvidenceEntries } from "../../extensions/context-evidence.js";
 import type { TaskContract } from "../../extensions/guard-types.js";
+import { operatorRequestDigest } from "../../extensions/task-state.js";
 
 const MAX_EVIDENCE_BYTES = 256 * 1024;
 const EXACT_OUTPUT_TEMPLATE = /\b([A-Z][A-Z0-9_]{2,63})\s*=\s*<([a-z][a-z0-9_-]{1,31})>/g;
@@ -10,6 +12,7 @@ export type ExactOutputContractEvaluation = {
   applicable: boolean;
   passed: boolean;
   key?: string;
+  reason?: "exact-output-evidence-missing" | "exact-output-evidence-ambiguous";
   expectedLines: string[];
   evidencePaths: string[];
 };
@@ -29,6 +32,15 @@ function exactOutputDirective(text: string): { key: string; placeholder: string
   return undefined;
 }
 
+type ExactOutputTaskText = Pick<TaskContract, "summary" | "expectedOutput" | "acceptanceCriteria" | "operatorRequest" | "operatorRequestDigest">;
+
+function authoritativeTaskText(input: string | ExactOutputTaskText): string {
+  if (typeof input === "string") return input;
+  if (typeof input.operatorRequest === "string"
+    && input.operatorRequestDigest === operatorRequestDigest(input.operatorRequest)) return input.operatorRequest;
+  return [input.summary, input.expectedOutput, ...(input.acceptanceCriteria ?? [])].filter(Boolean).join("\n");
+}
+
 function safeObservedFile(cwd: string, candidate: string): { path: string; text: string } | undefined {
   try {
     const absolute = path.resolve(cwd, candidate);
@@ -49,29 +61,25 @@ function valuesForKey(key: string, text: string): string[] {
   return [...text.matchAll(assignment)].map((match) => match[1]);
 }
 
-export function exactFinalOutputGuidance(taskText: string): string[] {
-  const directive = exactOutputDirective(taskText);
+export function exactFinalOutputGuidance(taskText: string | ExactOutputTaskText): string[] {
+  const directive = exactOutputDirective(authoritativeTaskText(taskText));
   if (!directive) return [];
   return [
-    `Exact final-output contract: make ${directive.key}=<${directive.placeholder}> the last non-empty response line. Copy the complete value verbatim from observed in-scope evidence and self-check every character before handoff.`
+    `Exact final-output contract: make ${directive.key}=<${directive.placeholder}> the last non-empty response line. Copy the complete value verbatim from observed project evidence and self-check every character before handoff.`
   ];
 }
 
 export function evaluateExactFinalOutputContract(
-  task: Pick<TaskContract, "summary" | "expectedOutput" | "acceptanceCriteria" | "contextManifest">,
+  task: Pick<TaskContract, "summary" | "expectedOutput" | "acceptanceCriteria" | "contextManifest" | "operatorRequest" | "operatorRequestDigest">,
   responseText: string,
   cwd: string
 ): ExactOutputContractEvaluation {
-  const directive = exactOutputDirective([
-    task.summary,
-    task.expectedOutput,
-    ...(task.acceptanceCriteria ?? [])
-  ].filter(Boolean).join("\n"));
+  const directive = exactOutputDirective(authoritativeTaskText(task));
   if (!directive) return { applicable: false, passed: true, expectedLines: [], evidencePaths: [] };
 
   const evidencePaths: string[] = [];
   const observedValues = new Set<string>();
-  for (const entry of task.contextManifest ?? []) {
+  for (const entry of durableContextEvidenceEntries(task)) {
     const observed = safeObservedFile(cwd, entry.path);
     if (!observed) continue;
     const values = valuesForKey(directive.key, observed.text);
@@ -80,10 +88,13 @@ export function evaluateExactFinalOutputContract(
     for (const value of values) observedValues.add(value);
   }
   if (observedValues.size === 0) {
-    return { applicable: false, passed: true, key: directive.key, expectedLines: [], evidencePaths: [] };
+    return { applicable: true, passed: false, key: directive.key, reason: "exact-output-evidence-missing", expectedLines: [], evidencePaths: [] };
   }
 
   const expectedLines = [...observedValues].sort().map((value) => `${directive.key}=${value}`);
+  if (expectedLines.length !== 1) {
+    return { applicable: true, passed: false, key: directive.key, reason: "exact-output-evidence-ambiguous", expectedLines, evidencePaths: [...new Set(evidencePaths)].sort() };
+  }
   const finalLine = String(responseText ?? "").split(/\r?\n/).map((line) => line.trim()).filter(Boolean).at(-1) ?? "";
   return {
     applicable: true,

package/packages/piagent-core/runtime/quality/performance-assurance-signals.ts

@@ -0,0 +1,23 @@
+const GRAPH_ORDER_PATTERNS = [
+  /\b(?:(?:dependenc(?:y|ies)|prerequisites?)[-\s]+(?:dag|graph|order(?:ing)?|relation(?:ship)?s?|direction|edges?|chains?)|(?:topological(?:ly)?\s+(?:sort(?:ed|ing)?|order(?:ed|ing)?)|dag(?:\s+(?:order(?:ing)?|edges?|schedule))?)|first[-\s]+(?:observed|seen|encountered)[-\s]+order|replay order|deduplicat(?:e|ion)[^.!?\n]{0,48}\border|before (?:its|their|the) dependents?)\b/i,
+  /\b(?:preserve|maintain|follow|respect|use)\b[^.!?\n]{0,24}\b(?:stable (?:input )?order|input order|stable order)\b[^.!?\n]{0,48}\b(?:schedul(?:e|ed|ing)|jobs?|tasks?|nodes?|steps?|dependents?|dependenc(?:y|ies)|prerequisites?|ranks?|ranked|priorit(?:y|ies)|ties?|tie[-\s]?break)\b|\b(?:schedul(?:e|ed|ing)|emit(?:s|ted|ting)?|process(?:es|ed|ing)?|ranks?|ranked|priorit(?:y|ies)|ties?|tie[-\s]?break)\b[^.!?\n]{0,48}\b(?:jobs?|tasks?|nodes?|steps?|dependents?)?[^.!?\n]{0,32}\b(?:stable (?:input )?order|input order|stable order)\b/i,
+  /\b(?:dependenc(?:y|ies)|prerequisites?|dag|graph|scheduler|jobs?|tasks?|nodes?)\b[^.!?\n]{0,64}\b(?:acyclic|cyclic|cycle detection|(?:detect|reject|prevent|avoid|report|forbid|form|contain|create)(?:s|ed|ing)?\s+cycles?)\b|\b(?:acyclic|cyclic|cycle detection|(?:detect|reject|prevent|avoid|report|forbid|form|contain|create)(?:s|ed|ing)?\s+cycles?|cycles?\s+(?:in|among|through))\b[^.!?\n]{0,64}\b(?:dependenc(?:y|ies)|prerequisites?|dag|graph|scheduler|jobs?|tasks?|nodes?)\b/i,
+  /\b(?:run|execute|start|schedule|process|emit|appear)\b[^.!?\n]{0,48}\bafter\b[^.!?\n]{0,48}\b(?:(?:all|each|every|its|their|the)\s+)?(?:dependenc(?:y|ies)|prerequisites?)\s+(?:(?:must|should|shall|has|have|had)\s+)?(?:complete[sd]?|finish(?:ed|es)?|resolve[sd]?|ran|executed)\b/i,
+  /\b(?:run|execute|start|schedule|process|emit|begin|appear)\b[^.!?\n]{0,48}\b(?:only\s+)?(?:once|when)\b[^.!?\n]{0,48}\b(?:all|each|every|its|their|the)?\s*(?:dependenc(?:y|ies)|prerequisites?)\b[^.!?\n]{0,32}\b(?:complete[sd]?|finish(?:ed|es)?|resolve[sd]?|ran|executed)\b/i,
+  /\b(?:run|execute|start|schedule|process|emit|begin|appear)\b[^.!?\n]{0,48}\buntil\b[^.!?\n]{0,48}\b(?:dependenc(?:y|ies)|prerequisites?)\b[^.!?\n]{0,32}\b(?:complete[sd]?|finish(?:ed|es)?|resolve[sd]?|ran|executed)\b/i,
+  /\b(?:jobs?|tasks?|nodes?|steps?|dependents?)\b[^.!?\n]{0,48}\bwait(?:s|ed|ing)?\s+for\b[^.!?\n]{0,32}\b(?:dependenc(?:y|ies)|prerequisites?)\b[^.!?\n]{0,32}\b(?:complete|finish|resolve)\b/i,
+  /\bwait\s+for\b[^.!?\n]{0,32}\b(?:(?:all|each|every|its|their|the)\s+)?(?:dependenc(?:y|ies)|prerequisites?)\b[^.!?\n]{0,32}\bbefore\b[^.!?\n]{0,32}\b(?:run|running|execute|executing|start|starting|schedule|scheduling|process|processing|emit|emitting)\b[^.!?\n]{0,32}\b(?:jobs?|tasks?|nodes?|steps?|dependents?)\b/i,
+  /\b(?:(?:each|every|all|the)\s+)?(?:dependenc(?:y|ies)|prerequisites?)\b[^.!?\n]{0,48}\b(?:complete|finish|resolve)(?:s|d|ed)?\b[^.!?\n]{0,24}\b(?:before|prior\s+to)\b[^.!?\n]{0,24}\b(?:(?:run|running|execute|executing|start|starting|schedule|scheduling|process|processing|emit|emitting)\s+)?(?:the\s+)?(?:(?:dependent\s+)?(?:job|task|node|step)s?|dependents?)\b/i,
+  /\b(?:jobs?|tasks?|nodes?|steps?|dependents?)\b[^.!?\n]{0,32}\b(?:eligible|ready)\b[^.!?\n]{0,24}\b(?:when|once)\b[^.!?\n]{0,32}\b(?:each|every|all|the|its|their)?\s*(?:dependenc(?:y|ies)|prerequisites?)\b[^.!?\n]{0,24}\b(?:is|are|be|become(?:s)?|remain(?:s)?)?\s*(?:done|complete[sd]?|finish(?:ed|es)?|resolve[sd]?)\b/i,
+  /\b(?:run|execute|process|resolve|complete|schedule)\s+(?:each|every|all|the)\s+(?:dependenc(?:y|ies)|prerequisites?)\s+first\b/i,
+  /\b(?:(?:each|every|all|the)\s+)?(?:dependenc(?:y|ies)|prerequisites?)\b[^.!?\n]{0,48}\b(?:precede(?:s)?|come(?:s)?\s+before|run(?:s)?\s+before|execute(?:s)?\s+before|finish(?:es)?\s+before|complete(?:s|d)?\s+before)\b[^.!?\n]{0,32}\b(?:the\s+)?(?:(?:dependent\s+)?(?:job|task|node|step)s?|dependents?)\b/i,
+  /\bdepends?\s+on\b[^.!?\n]{0,64}\b(?:run|runs|ran|execute|executes|executed|start|starts|started|schedule|schedules|scheduled|process|processes|processed|emit|emits|emitted)\b[^.!?\n]{0,24}\b(?:after|afterward|afterwards|later)\b/i,
+  /\bdepends?\s+on\b[^.!?\n]{0,64}\b(?:run|execute|start|schedule|process|emit)(?:s|d|ed|ing)?\b[^.!?\n]{0,24}\b[^.!?\n]{0,24}\bfirst\b/i,
+  /\b(?:run|execute|start|schedule|process|emit)(?:s|d|ed|ing)?\b[^.!?\n]{0,32}\b(?:dependenc(?:y|ies)|prerequisites?)\b[^.!?\n]{0,24}\bfollowed\s+by\b[^.!?\n]{0,24}\b(?:(?:the\s+)?dependent|(?:the\s+)?(?:job|task|node|step)s?)\b/i,
+  /\b(?:run|execute|start|schedule|process|emit)(?:s|d|ed|ing)?\b[^.!?\n]{0,48}\bbefore\b[^.!?\n]{0,48}\bdepends?\s+on\b/i,
+  /\b(?:do\s+not|don't|never)\s+(?:run|execute|start|schedule|process|emit|begin)\b[^.!?\n]{0,48}\b(?:jobs?|tasks?|nodes?|steps?|dependents?)\b[^.!?\n]{0,48}\bbefore\b[^.!?\n]{0,32}\b(?:dependenc(?:y|ies)|prerequisites?)\b/i
+];
+
+export function hasGraphOrderContract(request: string): boolean {
+  return GRAPH_ORDER_PATTERNS.some((pattern) => pattern.test(request));
+}

package/packages/piagent-core/runtime/quality/performance-assurance.ts

@@ -2,6 +2,7 @@ import type { TaskContract } from "../../extensions/guard-types.ts";
 import { acceptanceBoundaryProofGuidance } from "../../extensions/acceptance-boundary-guidance.js";
 import { normalizePathCandidate } from "../../extensions/policy-core.js";
 import { acceptanceLanguageAdapterStatus } from "../../extensions/acceptance-language-adapters.js";
+import { hasGraphOrderContract } from "./performance-assurance-signals.ts";
 import {
   MAX_PERFORMANCE_MUTATIONS_PER_REVISION,
   MAX_PERFORMANCE_REPAIR_PATHS,
@@ -55,8 +56,7 @@ const SIGNALS: Array<{ code: string; pattern: RegExp }> = [
   { code: "boundary-contract", pattern: /\b(?:backpressure|boundary|budget|capacity|ceil(?:ing)?|clamp|inclusive|minimum|maximum|maxchars|overflow|round(?:ing)?|safe[-\s]+integer|basis points?|positive integer|non-negative|falsey|falsy|nullish)\b/i },
   { code: "return-shape-contract", pattern: /\b(?:return shape|returned? (?:element|object|value|representation)s?|preserve (?:the )?return)\b/i },
   { code: "public-api-contract", pattern: /\b(?:exported api|public api|do not change (?:the )?(?:api|signature)|preserve (?:the )?(?:api|input|output|return)|without changing unrelated behavior)\b/i },
-  { code: "graph-order-contract", pattern: /\b(?:dependency|topolog|cycle|stable order|input order|first[-\s]+(?:observed|seen|encountered)[-\s]+order|replay order|deduplicat(?:e|ion).*order|exactly once|before its dependent)\b/i },
-  { code: "identity-isolation-contract", pattern: /\b(?:tenant|authorization|permission|cache[- ]?key|collision|isolation|same tuple|cross[- ]tenant)\b/i },
+  { code: "identity-isolation-contract", pattern: /\b(?:auth(?:orization)?|unauthoriz(?:ed|ation)|permission|cache[- ]?key|collision|same tuple|cross[- ]tenant|same[- ]tenant|tenant boundary|tenant[- ]scoped (?:cache|storage))\b/i },
   { code: "concurrency-contract", pattern: /\b(?:concurren|race condition|stale response|bounded retry|idempot(?:ent|ency)?|lock)\b/i },
   { code: "data-migration-contract", pattern: /\b(?:migration|schema|money|invoice|ledger|transaction|data loss)\b/i },
   { code: "non-mutation-contract", pattern: /\b(?:do not mutate|must not mutate|without mutating|input unchanged|preserve input)\b/i }
@@ -97,6 +97,10 @@ export function analyzePerformanceAssurance(input: AssuranceInput): PerformanceA
   }
 
   const reasonCodes = SIGNALS.filter((signal) => signal.pattern.test(request)).map((signal) => signal.code);
+  if (hasGraphOrderContract(request)) reasonCodes.push("graph-order-contract");
+  if (/\b(?:tenants?|tenantid)\b/i.test(request) && /\bisolat(?:e|ed|es|ing|ion)\b/i.test(request)) {
+    reasonCodes.push("identity-isolation-contract");
+  }
   if (request.length >= 320) reasonCodes.push("long-contract");
   if (namedEntrypoints(request) > 1) reasonCodes.push("multiple-entrypoints");
   const exactnessSignals = reasonCodes.filter((code) => [
@@ -176,7 +180,7 @@ export function performanceReviewGuidance(task: TaskContract): string[] {
       ? [`Review the pre-change and current behavior for: ${changedFiles.slice(0, 12).join(", ")}.`]
       : []),
     ...plan.reviewChecks,
-    "If no contradiction is found, stop reviewing and complete immediately. If one is found, name it, make the coordinated in-scope source/test edits required for one bounded revision, then run the exact configured verifier. A high-confidence in-scope verifier failure may open one final corrective revision."
+    "If no contradiction is found, stop reviewing and complete immediately. If one is found, name it, make the coordinated evidence-backed source/test edits required for one bounded revision, then run the exact configured verifier. A high-confidence verifier failure may open one final corrective revision."
   ];
 }
 
@@ -485,11 +489,11 @@ export function performanceReviewToolDecision(input: PerformanceReviewToolInput)
     }
     return {
       block: true,
-      reason: "The failed verifier opened a bounded corrective revision. Apply only the evidence-backed in-scope correction before re-running the exact verifier."
+      reason: "The failed verifier opened a bounded corrective revision. Apply only the evidence-backed correction before re-running the exact verifier."
     };
   }
   return {
     block: true,
-    reason: "This semantic-review continuation is limited to bounded diff/read inspection, reviewed in-scope edits, and one exact verifier per bounded revision."
+    reason: "This semantic-review continuation is limited to bounded diff/read inspection, reviewed evidence-backed edits, and one exact verifier per bounded revision."
   };
 }

package/packages/piagent-core/runtime/recovery/continuation-budget.ts

@@ -52,7 +52,7 @@ function normalizedEvidenceDigest(value: string | null | undefined): string | nu
 
 export function continuationClassForRecovery(decision: RecoveryDecision): ContinuationClass {
   if (["permission-policy", "scope-protected-path", "environment"].includes(decision.failureCategory)
-    || decision.reasonCodes.some((code) => ["permission-expansion-forbidden", "scope-replan-required", "operator-environment-action", "dependency-mutation-not-authorized"].includes(code))) return "policy-blocked";
+    || decision.reasonCodes.some((code) => ["permission-expansion-forbidden", "protected-path-forbidden", "scope-replan-required", "operator-environment-action", "dependency-mutation-not-authorized"].includes(code))) return "policy-blocked";
   if (decision.action === "repair") return "source-repair";
   if (decision.failureCategory === "provider-network") return "model-retry";
   if (decision.failureCategory === "flaky-infrastructure") return "infrastructure-retry";

package/packages/piagent-core/runtime/recovery/edit-recovery-context.ts

@@ -0,0 +1,113 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { shouldIndexPath } from "../../extensions/context-engine.js";
+import { matchesProtectedPath } from "../../extensions/policy-core.js";
+import { redactSensitiveProjectFileText, redactSensitiveText } from "../../security/sensitive-data.js";
+import type { ToolFailureReasonCode } from "../inspection/tool-failure-classification.ts";
+
+const MAX_RECOVERY_FILE_BYTES = 8_192;
+const PRIVATE_PATH = /(?:^|\/)(?:\.git|\.pi|node_modules)(?:\/|$)|(?:^|\/)\.env(?:\.|$)|(?:^|\/)(?:auth|credentials?|secrets?|tokens?)\.json$/i;
+
+export type EditRecoveryContext = {
+  key: string;
+  targetPath: string;
+  text: string;
+  contentHash: string;
+  originalChars: number;
+  redacted: boolean;
+};
+
+function projectRelativeTarget(cwd: string, supplied: string): { root: string; absolute: string; relative: string } | undefined {
+  try {
+    const root = fs.realpathSync.native(cwd);
+    const suppliedAbsolute = path.resolve(root, supplied);
+    const suppliedRelative = path.relative(root, suppliedAbsolute).split(path.sep).join("/");
+    if (!suppliedRelative || suppliedRelative === "." || suppliedRelative === ".."
+      || suppliedRelative.startsWith("../") || path.isAbsolute(suppliedRelative)) return undefined;
+    let cursor = root;
+    for (const segment of suppliedRelative.split("/")) {
+      cursor = path.join(cursor, segment);
+      if (fs.lstatSync(cursor).isSymbolicLink()) return undefined;
+    }
+    const absolute = fs.realpathSync.native(suppliedAbsolute);
+    const relative = path.relative(root, absolute).split(path.sep).join("/");
+    if (!relative || relative === "." || relative === ".." || relative.startsWith("../") || path.isAbsolute(relative)) return undefined;
+    return { root, absolute, relative };
+  } catch {
+    return undefined;
+  }
+}
+
+function stableSmallTextFile(root: string, absolute: string): string | undefined {
+  let descriptor: number | undefined;
+  try {
+    const initial = fs.lstatSync(absolute);
+    if (!initial.isFile() || initial.isSymbolicLink() || initial.size > MAX_RECOVERY_FILE_BYTES) return undefined;
+    const real = fs.realpathSync.native(absolute);
+    if (real !== root && !real.startsWith(`${root}${path.sep}`)) return undefined;
+    descriptor = fs.openSync(real, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    const observed = fs.fstatSync(descriptor);
+    if (!observed.isFile() || observed.dev !== initial.dev || observed.ino !== initial.ino
+      || observed.size !== initial.size || observed.mtimeMs !== initial.mtimeMs || observed.ctimeMs !== initial.ctimeMs
+      || observed.size > MAX_RECOVERY_FILE_BYTES) return undefined;
+    const buffer = Buffer.alloc(observed.size + 1);
+    let bytesRead = 0;
+    while (bytesRead < buffer.length) {
+      const count = fs.readSync(descriptor, buffer, bytesRead, buffer.length - bytesRead, null);
+      if (count === 0) break;
+      bytesRead += count;
+    }
+    const afterRead = fs.fstatSync(descriptor);
+    if (bytesRead !== observed.size || afterRead.dev !== observed.dev || afterRead.ino !== observed.ino
+      || afterRead.size !== observed.size || afterRead.mtimeMs !== observed.mtimeMs || afterRead.ctimeMs !== observed.ctimeMs) return undefined;
+    const bytes = buffer.subarray(0, bytesRead);
+    const sample = bytes.subarray(0, Math.min(bytes.length, 8_192));
+    if (sample.includes(0)) return undefined;
+    const controls = [...sample].filter((byte) => byte < 7 || (byte > 13 && byte < 32)).length;
+    if (sample.length > 0 && controls / sample.length >= 0.02) return undefined;
+    const text = bytes.toString("utf8");
+    return Buffer.from(text, "utf8").equals(bytes) ? text : undefined;
+  } catch {
+    return undefined;
+  } finally {
+    if (descriptor !== undefined) fs.closeSync(descriptor);
+  }
+}
+
+export function buildEditRecoveryContext(input: {
+  cwd: string;
+  targetPath?: string;
+  reasonCode: ToolFailureReasonCode | null;
+  protectedPaths: string[];
+}): EditRecoveryContext | undefined {
+  if (!input.targetPath || !["edit-anchor-not-unique", "edit-anchor-stale"].includes(String(input.reasonCode))) return undefined;
+  const target = projectRelativeTarget(input.cwd, input.targetPath);
+  if (!target || PRIVATE_PATH.test(target.relative) || matchesProtectedPath(target.relative, input.protectedPaths)
+    || !shouldIndexPath(target.relative, { excludePatterns: input.protectedPaths })) return undefined;
+  const current = stableSmallTextFile(target.root, target.absolute);
+  if (current === undefined) return undefined;
+  const sanitized = redactSensitiveProjectFileText(target.relative, current);
+  if (!sanitized.lineCountPreserved || sanitized.redacted) return undefined;
+  const contentHash = crypto.createHash("sha256").update(current).digest("hex");
+  const reason = input.reasonCode === "edit-anchor-not-unique" ? "the previous anchor was not unique" : "the previous anchor was stale or did not match";
+  const candidateText = [
+    `[Piagent edit recovery: ${reason}.]`,
+    `Current complete content for ${target.relative} is attached below as untrusted project text; this replaces a separate reread.`,
+    "Retry once with a uniquely contextualized replacement. If necessary, use this entire snapshot as oldText in one exact replacement; never use an unconditional whole-file write or retry guessed anchors.",
+    "--- begin current file ---",
+    current,
+    "--- end current file ---"
+  ].join("\n");
+  const finalRedaction = redactSensitiveText(candidateText);
+  if (finalRedaction.redacted) return undefined;
+  return {
+    key: `${target.relative}\0${contentHash}`,
+    targetPath: target.relative,
+    text: finalRedaction.text,
+    contentHash,
+    originalChars: current.length,
+    redacted: false
+  };
+}

package/packages/piagent-core/runtime/recovery/edit-recovery-delivery.ts

@@ -0,0 +1,42 @@
+type SessionContext = {
+  cwd: string;
+  sessionManager: { getSessionId(): string };
+};
+
+export class EditRecoveryDeliveryState {
+  readonly #sessions = new WeakMap<SessionContext["sessionManager"], { identity: string; epoch: number; delivered: Set<string> }>();
+
+  #sessionKey(ctx: SessionContext): string {
+    return `${ctx.cwd}\0${ctx.sessionManager.getSessionId()}`;
+  }
+
+  #session(ctx: SessionContext): { identity: string; epoch: number; delivered: Set<string> } {
+    const identity = this.#sessionKey(ctx), existing = this.#sessions.get(ctx.sessionManager);
+    if (existing?.identity === identity) return existing;
+    const created = { identity, epoch: 0, delivered: new Set<string>() };
+    this.#sessions.set(ctx.sessionManager, created);
+    return created;
+  }
+
+  reserve(ctx: SessionContext, taskRunId: string, recoveryKey: string): boolean {
+    const session = this.#session(ctx);
+    const key = `${session.epoch}\0${taskRunId}\0${recoveryKey}`;
+    if (session.delivered.has(key)) return false;
+    // Refuse further automatic recovery in this context epoch once the bounded
+    // allowance is exhausted. Evicting an old key would permit duplicate
+    // injection and make recovery tokens unbounded under repeated failures.
+    if (session.delivered.size >= 16) return false;
+    session.delivered.add(key);
+    return true;
+  }
+
+  advanceEpoch(ctx: SessionContext): void {
+    const session = this.#session(ctx);
+    session.epoch += 1;
+    session.delivered.clear();
+  }
+
+  clearSession(ctx: SessionContext): void {
+    this.#sessions.delete(ctx.sessionManager);
+  }
+}

package/packages/piagent-core/runtime/recovery/handoff-projection.ts

@@ -211,6 +211,9 @@ function authority(recovery: RecoveryDecision | null): HandoffProjection["requir
   const reasons = strings(recovery.reasonCodes, 20, 120);
   if (recovery.action === "fresh-session") return { required: true, kind: "fresh-session", reasonCodes: reasons };
   if (recovery.reasonCodes.includes("permission-expansion-forbidden")) return { required: true, kind: "permission", reasonCodes: reasons };
+  if (recovery.reasonCodes.includes("protected-path-forbidden")) return { required: true, kind: "permission", reasonCodes: reasons };
+  // Backward-compatible projection for recovery records written before task
+  // scope became advisory.
   if (recovery.reasonCodes.includes("scope-replan-required")) return { required: true, kind: "scope", reasonCodes: reasons };
   if (recovery.action === "ask-operator") return { required: true, kind: "operator", reasonCodes: reasons };
   return { required: false, kind: "none", reasonCodes: reasons };
@@ -292,7 +295,7 @@ export function buildHandoffProjection(
     decisionsAndInvariants: [
       "Task Contract v2 is authoritative for task outcome.",
       "Failure classification never authorizes source mutation by itself.",
-      "Source mutation still requires task scope and hook authorization.",
+      "Source mutation still requires hook authorization; task scope is an advisory retrieval/review focus.",
       "Verifier evidence is current only when its namespaced working-tree digest matches the current tree."
     ],
     contextReferences: {

package/packages/piagent-core/runtime/recovery/pristine-task-policy-refresh.ts

@@ -0,0 +1,91 @@
+import type { ProjectProfile, TaskContract } from "../../extensions/guard-types.ts";
+import { compileCriterionGraph } from "../../extensions/criterion-graph.js";
+import { meaningfulVerificationCommands, selectVerificationPlan } from "../../extensions/verification-intelligence.js";
+import { workingTreeSnapshot, workingTreeSnapshotHasUnavailableEvidence } from "../../extensions/task-state.js";
+
+export type PristineTaskVerificationRefresh = {
+  task: TaskContract;
+  refreshed: boolean;
+  reason: string;
+  verifyGroup?: string;
+  previousCommands: string[];
+  nextCommands: string[];
+};
+
+function sameStringRecord(left: Record<string, string>, right: Record<string, string>): boolean {
+  const leftEntries = Object.entries(left).sort(([leftKey], [rightKey]) => leftKey.localeCompare(rightKey));
+  const rightEntries = Object.entries(right).sort(([leftKey], [rightKey]) => leftKey.localeCompare(rightKey));
+  return leftEntries.length === rightEntries.length
+    && leftEntries.every(([key, value], index) => rightEntries[index]?.[0] === key && rightEntries[index]?.[1] === value);
+}
+
+function sameCommands(left: string[], right: string[]): boolean {
+  return left.length === right.length && left.every((command, index) => command === right[index]);
+}
+
+/**
+ * Refresh profile-derived verifier commands only while an automatic task is
+ * still byte-for-byte pristine. This lets a corrected workspace profile reach
+ * a resumed task without rewriting any source-change evidence or weakening an
+ * already-started implementation contract.
+ */
+export function refreshPristineRuntimeTaskVerification(
+  cwd: string,
+  task: TaskContract,
+  profile: ProjectProfile,
+  updatedAt = new Date().toISOString()
+): PristineTaskVerificationRefresh {
+  const previousCommands = meaningfulVerificationCommands(task.verifyCommands);
+  const unchanged = (reason: string): PristineTaskVerificationRefresh => ({
+    task, refreshed: false, reason, previousCommands, nextCommands: previousCommands
+  });
+  if (task.trace.outcome !== "pending" || task.intakeMode !== "runtime" || task.changeMode !== "source-change") {
+    return unchanged("task-not-refreshable");
+  }
+  if ((task.changedFiles?.length ?? 0) > 0 || (task.observedChangedFiles?.length ?? 0) > 0 || (task.verifyEvidence?.length ?? 0) > 0) {
+    return unchanged("task-has-runtime-evidence");
+  }
+  const configuredGroups = profile.verifyCommands && typeof profile.verifyCommands === "object"
+    ? profile.verifyCommands
+    : {};
+  const retainedGroup = task.verifyGroup && Object.hasOwn(configuredGroups, task.verifyGroup)
+    ? task.verifyGroup
+    : undefined;
+  const plan = selectVerificationPlan(profile, retainedGroup, task.changeMode, cwd, task.scope);
+  if (plan.error) return unchanged("profile-verifier-invalid");
+  const nextCommands = meaningfulVerificationCommands(plan.commands);
+  if (nextCommands.length === 0) return unchanged("profile-verifier-unavailable");
+  if (sameCommands(previousCommands, nextCommands) && task.verifyGroup === plan.group) {
+    return unchanged("profile-verifier-current");
+  }
+  if (!task.baselineFileDigests || typeof task.baselineFileDigests !== "object" || Array.isArray(task.baselineFileDigests)) {
+    return unchanged("baseline-unavailable");
+  }
+  const baseline = task.baselineFileDigests;
+  const current = workingTreeSnapshot(cwd) as Record<string, string>;
+  if (workingTreeSnapshotHasUnavailableEvidence(current) || !sameStringRecord(baseline, current)) {
+    return unchanged("working-tree-not-pristine");
+  }
+  const refreshed: TaskContract = {
+    ...task,
+    verifyGroup: plan.group,
+    verifyCommands: nextCommands,
+    criterionGraph: compileCriterionGraph({
+      acceptanceCriteria: task.acceptanceCriteria,
+      scope: task.scope,
+      verifyCommands: nextCommands,
+      changeMode: task.changeMode,
+      mode: task.criterionGraph?.mode ?? "mechanical",
+      createdAt: task.criterionGraph?.createdAt ?? task.createdAt
+    }) as NonNullable<TaskContract["criterionGraph"]>,
+    updatedAt
+  };
+  return {
+    task: refreshed,
+    refreshed: true,
+    reason: "pristine-profile-verifier-refresh",
+    verifyGroup: plan.group,
+    previousCommands,
+    nextCommands
+  };
+}

package/packages/piagent-core/runtime/recovery/recovery-policy.ts

@@ -29,6 +29,9 @@ export type RecoveryReasonCode =
   | "provider-transient-retry"
   | "provider-retry-exhausted"
   | "permission-expansion-forbidden"
+  | "protected-path-forbidden"
+  // Legacy persisted recovery records may still carry this value. New runtime
+  // decisions never emit it because task scope is advisory.
   | "scope-replan-required"
   | "transient-verifier-retry"
   | "transient-retry-unavailable"
@@ -185,11 +188,11 @@ export function selectRecoveryDecision(input: RecoveryPolicyInput): RecoveryDeci
   if (input.currentPhase === "terminal") return decision(input, "blocked", ["terminal-phase"]);
   if (input.currentPhase === "handoff") return decision(input, "handoff", ["handoff-already-observed"]);
   if (input.classification.category === "passed") return decision(input, "handoff", ["no-failure"]);
-  // A completion boundary violation cannot be repaired within the immutable
-  // task contract. Stop before stale-verifier or unknown-diagnostic retries so
-  // recovery never spends another turn attempting source work outside scope.
+  // Protected-path evidence cannot be repaired by another model turn. The
+  // failure category also accepts historical scope diagnostics for replay
+  // compatibility, but current task scope itself is advisory.
   if (input.classification.category === "scope-protected-path") {
-    return decision(input, "handoff", ["scope-replan-required"]);
+    return decision(input, "handoff", ["protected-path-forbidden"]);
   }
 
   const counts = countsFor(input);