@piagent/platform 1.6.0 → 1.7.1

package/packages/piagent-core/runtime/product/task-usage-hooks.ts

@@ -0,0 +1,78 @@
+import crypto from "node:crypto";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { TaskContract } from "../../extensions/guard-types.ts";
+
+type Request = { requestId: string; taskId?: string; taskRunId?: string; sessionId: string; providerRequests: number };
+
+// Metadata only, written to the existing telemetry stream. SDK turns are not
+// provider billing receipts; missing terminals and internal retries stay unknown.
+export function registerTaskUsageHooks(pi: ExtensionAPI, input: {
+  activeTask: (ctx: ExtensionContext) => TaskContract | undefined;
+  telemetry: (ctx: ExtensionContext, event: Record<string, unknown>) => void;
+}): void {
+  const requests = new Map<string, Request>();
+  const messages = new WeakMap<object, Request>();
+  const calls = new Map<string, { request: Request; invoked: boolean }>();
+  const key = (ctx: ExtensionContext) => `${ctx.cwd}\u0000${ctx.sessionManager.getSessionId()}`;
+  const emit = (ctx: ExtensionContext, request: Request, event: string, data = {}) => input.telemetry(ctx, {
+    ...request, event, taskUsageVersion: 1, ...data
+  });
+  pi.on("turn_start", (_event, ctx) => {
+    const task = input.activeTask(ctx);
+    const request: Request = { requestId: crypto.randomUUID(), taskId: task?.taskId,
+      taskRunId: task?.taskRunId, sessionId: ctx.sessionManager.getSessionId(), providerRequests: 0 };
+    requests.set(key(ctx), request);
+    emit(ctx, request, "task_usage_request");
+  });
+  pi.on("before_provider_request", (_event, ctx) => {
+    const request = requests.get(key(ctx));
+    if (request) {
+      request.providerRequests += 1;
+      emit(ctx, request, "task_usage_dispatch");
+    }
+  });
+  const observe = (message: any, ctx: ExtensionContext, allowBind: boolean) => {
+    if (message?.role !== "assistant") return;
+    const request = messages.get(message) ?? (allowBind ? requests.get(key(ctx)) : undefined);
+    if (!request) return;
+    messages.set(message, request);
+    // Only numeric usage metadata crosses this boundary. No content, arguments,
+    // headers, opaque reasoning, or error text is retained.
+    const usage = message.usage;
+    const numeric = (value: unknown) => typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
+    emit(ctx, request, "task_usage_terminal", {
+      usageSemantics: "request-cumulative", usageRevision: "terminal",
+      stopReason: ["stop", "length", "toolUse", "error", "aborted"].includes(message.stopReason) ? message.stopReason : "unknown",
+      usage: Object.fromEntries(["input", "output", "cacheRead", "cacheWrite", "totalTokens"].map((field) => [field, numeric(usage?.[field])])),
+      cost: numeric(usage?.cost?.total), costBasis: "sdk-rate-estimate", currency: "USD"
+    });
+  };
+  pi.on("message_end", (event, ctx) => observe(event.message, ctx, true));
+  // The pinned SDK emits the same final message at both boundaries. An unknown
+  // replay object must not inherit the identity of a newer task at turn_end.
+  pi.on("turn_end", (event, ctx) => observe(event.message, ctx, false));
+  const callKey = (ctx: ExtensionContext, id: string) => `${key(ctx)}\u0000${id}`;
+  pi.on("tool_execution_start", (event, ctx) => {
+    const request = requests.get(key(ctx));
+    if (!request) return;
+    calls.set(callKey(ctx, event.toolCallId), { request, invoked: false });
+    emit(ctx, request, "task_tool_attempted", { toolCallId: event.toolCallId, toolName: event.toolName });
+  });
+  // SDK start events also cover blocked/invalid/truncated calls. Only the
+  // afterToolCall-backed tool_result hook proves execute was actually entered.
+  pi.on("tool_result", (event, ctx) => {
+    const call = calls.get(callKey(ctx, event.toolCallId));
+    if (!call) return;
+    call.invoked = true;
+    emit(ctx, call.request, "task_tool_invoked", { toolCallId: event.toolCallId, toolName: event.toolName });
+  });
+  pi.on("tool_execution_end", (event, ctx) => {
+    const id = callKey(ctx, event.toolCallId), call = calls.get(id);
+    if (call && !call.invoked) emit(ctx, call.request, "task_tool_not_executed", { toolCallId: event.toolCallId, toolName: event.toolName });
+    calls.delete(id);
+  });
+  pi.on("session_shutdown", (_event, ctx) => {
+    requests.delete(key(ctx));
+    for (const id of calls.keys()) if (id.startsWith(`${key(ctx)}\u0000`)) calls.delete(id);
+  });
+}

package/packages/piagent-core/runtime/product/task-usage.ts

@@ -0,0 +1,104 @@
+import { inspectContextTelemetry } from "../../extensions/context-engine.js";
+import type { TaskContract } from "../../extensions/guard-types.ts";
+import { firstCorrectEditTiming, type CompletionSource } from "./edit-verifier-timing.ts";
+
+type Event = Record<string, any>;
+type Inspection = { records: Event[]; exists: boolean; integrityFailures: number; recoverableTailBytes: number; inputTruncated: boolean };
+const FIELDS = ["input", "output", "cacheRead", "cacheWrite", "totalTokens"] as const;
+const validNumber = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value) && value >= 0;
+
+export function projectTaskUsage(task: Pick<TaskContract, "taskId" | "taskRunId" | "sessionId">, inspection: Inspection) {
+  const records = inspection.records.filter((event) => event.taskUsageVersion === 1
+    && event.sessionId === task.sessionId && event.taskId === task.taskId && event.taskRunId === task.taskRunId);
+  const warnings = new Set<string>();
+  if (!inspection.exists) warnings.add("telemetry-unavailable");
+  if (inspection.inputTruncated || inspection.integrityFailures || inspection.recoverableTailBytes) warnings.add("telemetry-incomplete");
+  const requests = new Map<string, { start: boolean; terminal?: Event; conflict: boolean; dispatches: number }>();
+  const tools = new Map<string, string>();
+  const attempts = new Map<string, { name: string; attempted: boolean; invoked: boolean; rejected: boolean }>();
+  for (const event of records) {
+    if (event.event === "task_tool_started") warnings.add("legacy-tool-start-is-not-execution-proof");
+    if (["task_tool_attempted", "task_tool_invoked", "task_tool_not_executed"].includes(event.event)) {
+      if (typeof event.toolCallId !== "string" || !event.toolCallId || typeof event.toolName !== "string"
+        || typeof event.requestId !== "string" || !event.requestId) { warnings.add("tool-identity-unavailable"); continue; }
+      const id = `${event.requestId}\u0000${event.toolCallId}`;
+      const call = attempts.get(id) ?? { name: event.toolName, attempted: false, invoked: false, rejected: false };
+      if (call.name !== event.toolName) warnings.add("tool-identity-conflict");
+      call.attempted ||= event.event === "task_tool_attempted";
+      call.invoked ||= event.event === "task_tool_invoked";
+      call.rejected ||= event.event === "task_tool_not_executed";
+      attempts.set(id, call);
+      if (call.invoked) tools.set(id, call.name);
+      continue;
+    }
+    if (!["task_usage_request", "task_usage_dispatch", "task_usage_terminal"].includes(event.event)) continue;
+    if (typeof event.requestId !== "string" || !event.requestId) { warnings.add("request-identity-unavailable"); continue; }
+    const request = requests.get(event.requestId) ?? { start: false, conflict: false, dispatches: 0 };
+    requests.set(event.requestId, request);
+    if (event.event === "task_usage_request") request.start = true;
+    if (Number.isSafeInteger(event.providerRequests)) request.dispatches = Math.max(request.dispatches, event.providerRequests);
+    if (event.event !== "task_usage_terminal") continue;
+    if (event.usageSemantics !== "request-cumulative") { request.conflict = true; continue; }
+    const material = (value: Event) => JSON.stringify([FIELDS.map((field) => value.usage?.[field] ?? null), value.cost ?? null, value.stopReason]);
+    if (request.terminal && material(request.terminal) !== material(event)) {
+      // Late totals may fill missing fields, but cannot rewrite known terminal
+      // amounts. Deltas/session cumulative snapshots are never summed here.
+      const previous = request.terminal;
+      if (FIELDS.some((field) => previous.usage?.[field] != null && event.usage?.[field] != null && previous.usage[field] !== event.usage[field])
+        || (previous.cost != null && event.cost != null && previous.cost !== event.cost) || previous.stopReason !== event.stopReason) request.conflict = true;
+      request.terminal = { ...event, cost: previous.cost ?? event.cost,
+        usage: Object.fromEntries(FIELDS.map((field) => [field, previous.usage?.[field] ?? event.usage?.[field]])) };
+      continue;
+    }
+    request.terminal = event;
+  }
+  const sums = Object.fromEntries(FIELDS.map((field) => [field, 0])) as Record<typeof FIELDS[number], number>;
+  let unknownRequests = 0, failedAttempts = 0, estimatedCost = 0, costKnown = true;
+  for (const request of requests.values()) {
+    const event = request.terminal;
+    if (event && ["error", "aborted"].includes(event.stopReason)) failedAttempts += 1;
+    if (!request.start || !event || request.conflict || request.dispatches > 1) {
+      unknownRequests += 1; costKnown = false; continue;
+    }
+    const usage = event.usage;
+    const numeric = FIELDS.every((field) => validNumber(usage?.[field]) && Number.isSafeInteger(usage[field]));
+    const consistent = numeric && usage.totalTokens === usage.input + usage.output + usage.cacheRead + usage.cacheWrite;
+    // SDK error messages may contain synthetic all-zero usage after a billed
+    // abort. Zero on these paths is not proof that nothing was charged.
+    if (!consistent || (["error", "aborted", "unknown"].includes(event.stopReason) && usage.totalTokens === 0)) unknownRequests += 1;
+    else for (const field of FIELDS) sums[field] += usage[field];
+    if (validNumber(event.cost) && event.costBasis === "sdk-rate-estimate") estimatedCost += event.cost;
+    else costKnown = false;
+  }
+  if (Object.values(sums).some((sum) => !Number.isSafeInteger(sum))) warnings.add("usage-overflow");
+  if (!requests.size) warnings.add("request-coverage-unavailable");
+  if (unknownRequests) warnings.add("request-usage-unknown");
+  if ([...attempts.values()].some((call) => !call.attempted || call.invoked === call.rejected)) warnings.add("tool-execution-unconfirmed");
+  const complete = warnings.size === 0;
+  const counts: Record<string, number> = {};
+  for (const name of tools.values()) Object.defineProperty(counts, name, { value: (Object.hasOwn(counts, name) ? counts[name] : 0) + 1, enumerable: true, configurable: true });
+  return {
+    scope: "observed-sdk-requests" as const,
+    status: complete ? "observed" as const : "unknown" as const,
+    requests: requests.size, unknownRequests, failedAttempts: complete ? failedAttempts : null, observedFailedAttempts: failedAttempts,
+    tokens: complete ? sums.totalTokens : null,
+    components: complete ? sums : null,
+    knownTokenSubtotal: sums.totalTokens,
+    sdkEstimatedCost: complete && costKnown ? estimatedCost : null,
+    billedCost: null, currency: null,
+    actualInvocationCounts: complete ? counts : null,
+    observedInvocationCounts: counts,
+    attemptedToolCalls: attempts.size,
+    notExecutedToolCalls: [...attempts.values()].filter((call) => call.rejected && !call.invoked).length,
+    warnings: [...warnings],
+    limitations: ["SDK reported usage; not an end-to-end billing receipt", "Coverage limited to instrumented requests; pre-instrumentation and hidden provider retries unavailable"]
+  };
+}
+
+export function readTaskUsage(cwd: string, task: TaskContract, source?: CompletionSource) {
+  let inspection: Inspection;
+  try { inspection = inspectContextTelemetry(cwd); }
+  catch { inspection = { records: [], exists: false, integrityFailures: 1, recoverableTailBytes: 0, inputTruncated: false }; }
+  const complete = inspection.exists && !inspection.integrityFailures && !inspection.recoverableTailBytes && !inspection.inputTruncated;
+  return { ...projectTaskUsage(task, inspection), editTiming: firstCorrectEditTiming(task, inspection.records, complete, source) };
+}

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

@@ -3,6 +3,7 @@ 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;
@@ -11,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[];
 };
@@ -30,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);
@@ -50,24 +61,20 @@ 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[] = [];
@@ -81,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.ts

@@ -180,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."
   ];
 }
 
@@ -489,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/quality/protected-refusal-handoff.ts

@@ -0,0 +1,35 @@
+import { hasProtectedRefusalBoundary } from "../workflows/task-intake.ts";
+
+const MARKER = /(?:^|[\s`])(REFUSAL|SAFE_ALTERNATIVE)=([a-z0-9][a-z0-9._:-]{0,127})(?=[\s`]|$)/gi;
+const SAFE_EXPLANATION = /\b(?:cannot|can't|declin(?:e|ed|ing)|non-secret|redact(?:ed|ion)|refus(?:e|ed|ing|al)|safe\s+alternative|won't|will\s+not)\b/i;
+
+function expectedMarkers(prompt: string): string[] | undefined {
+  const found = new Map<string, string>();
+  for (const match of String(prompt ?? "").matchAll(new RegExp(MARKER.source, MARKER.flags))) {
+    const key = match[1].toUpperCase(), value = match[2];
+    if (found.has(key)) return undefined;
+    found.set(key, `${key}=${value}`);
+  }
+  if (found.size !== 2 || !found.has("REFUSAL") || !found.has("SAFE_ALTERNATIVE")) return undefined;
+  return [found.get("REFUSAL")!, found.get("SAFE_ALTERNATIVE")!];
+}
+
+/** A narrow native fallback for a task that explicitly requires refusal. It
+ * recognizes only operator-declared durable markers; it never evaluates or
+ * grants access to the protected material itself. */
+export function protectedRefusalHandoffMatches(prompt: string, response: string): boolean {
+  if (!hasProtectedRefusalBoundary(String(prompt ?? ""))) return false;
+  const expected = expectedMarkers(prompt);
+  if (!expected || typeof response !== "string" || !response.trim() || !(response as any).isWellFormed()
+    || Buffer.byteLength(response) > 65_536) return false;
+  const observed = [...response.matchAll(new RegExp(MARKER.source, MARKER.flags))]
+    .map((match) => `${match[1].toUpperCase()}=${match[2]}`);
+  if (observed.length !== expected.length
+    || observed.some((marker) => !expected.includes(marker))
+    || expected.some((marker) => observed.filter((candidate) => candidate === marker).length !== 1)) return false;
+  const lines = response.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  if (expected.some((marker) => lines.filter((line) => line === marker).length !== 1)) return false;
+  if (lines.some((line) => /^(?:REFUSAL|SAFE_ALTERNATIVE)=/i.test(line) && !expected.includes(line))) return false;
+  const explanation = lines.filter((line) => !expected.includes(line)).join(" ");
+  return !explanation || SAFE_EXPLANATION.test(explanation);
+}

package/packages/piagent-core/runtime/recovery/acceptance-recovery-guidance.ts

@@ -0,0 +1,21 @@
+export type CriticalRecoveryProjection = { criterionText: string; targets: string[]; missingDimensions: string[]; proofHints: string[]; diagnosticHints?: string[] };
+
+function compactRecoveryField(value: unknown, maximum: number): string {
+  const text = String(value ?? "").replace(/\s+/g, " ").trim();
+  return text.length > maximum ? `${text.slice(0, Math.max(0, maximum - 1)).trimEnd()}…` : text;
+}
+export function criticalAcceptanceRecoveryGuidance(projections: CriticalRecoveryProjection[], includeProofHints = true): string[] {
+  if (projections.length === 0) return [];
+  const lines = ["Critical proof targets (derived only from the current task contract and working tree):"];
+  for (const projection of projections.slice(0, 8)) {
+    const targets = projection.targets.map((item) => compactRecoveryField(item, 80)).filter(Boolean).slice(0, 8);
+    const dimensions = projection.missingDimensions.map((item) => compactRecoveryField(item, 80)).filter(Boolean).slice(0, 8);
+    const criterion = compactRecoveryField(projection.criterionText, 700);
+    lines.push(`- Target: ${targets.join(", ") || "task-scoped behavior"}; missing proof: ${dimensions.join(", ") || "focused-evidence"}; criterion: ${criterion}`);
+  }
+  const hints = [...new Set(projections.flatMap((projection) => includeProofHints ? projection.proofHints : projection.diagnosticHints ?? [])
+    .map((hint) => compactRecoveryField(hint, 300))
+    .filter(Boolean))].slice(0, 8);
+  if (hints.length > 0) lines.push(includeProofHints ? "Proof requirements:" : "Diagnostic evidence (does not grant repair authority):", ...hints.map((hint) => `- ${hint}`));
+  return lines;
+}

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";
@@ -66,6 +66,16 @@ export function continuationDenialReasonCode(reason: ContinuationReservation["re
   return "continuation-journal-unavailable";
 }
 
+export function terminalRecoveryForContinuationDenial(
+  decision: RecoveryDecision,
+  reason: ContinuationReservation["reason"]
+): RecoveryDecision {
+  return {
+    ...decision, action: "handoff", continuation: "none", nextPhase: null, sourceMutationAllowed: false,
+    reasonCodes: [...new Set([...decision.reasonCodes, continuationDenialReasonCode(reason)])]
+  };
+}
+
 export function reserveSemanticReviewContinuation(
   cwd: string,
   task: TaskContract,
@@ -97,10 +107,9 @@ export function planRecoveryContinuation(
     missingVerifyCommands: input.missingVerifyCommands, evidenceDigest: decision.evidenceDigest, reasonCodes: decision.reasonCodes
   });
   if (reservation?.allowed) return { recovery: decision, classification, reservation };
-  const reason = continuationDenialReasonCode(reservation?.reason ?? "journal-unavailable");
   return {
     classification, reservation,
-    recovery: { ...decision, action: "handoff", continuation: "none", nextPhase: null, sourceMutationAllowed: false, reasonCodes: [...decision.reasonCodes, reason] }
+    recovery: terminalRecoveryForContinuationDenial(decision, reservation?.reason ?? "journal-unavailable")
   };
 }
 

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

@@ -0,0 +1,61 @@
+import fs from "node:fs";
+import crypto from "node:crypto";
+import type { TaskContract } from "../../extensions/guard-types.ts";
+
+export type DiagnosticDelivery = { mode: "diagnostic"; qualityClaim: "withheld";
+  policySha256: string; acceptanceDigest: string; pendingCriterionIds: string[] };
+
+export function installedDiagnosticPolicyDigest(): string | undefined {
+  try {
+    const bytes = fs.readFileSync(new URL("../../policies/base-policy.json", import.meta.url));
+    return JSON.parse(bytes.toString()).finalGate?.acceptanceProofMode === "diagnostic"
+      ? crypto.createHash("sha256").update(bytes).digest("hex") : undefined;
+  } catch { return undefined; }
+}
+
+export function validDiagnosticDelivery(value: unknown, acceptanceDigest: unknown): value is DiagnosticDelivery {
+  const d = value as DiagnosticDelivery;
+  return Boolean(d && Object.keys(d).sort().join(",") === "acceptanceDigest,mode,pendingCriterionIds,policySha256,qualityClaim"
+    && d.mode === "diagnostic" && d.qualityClaim === "withheld"
+    && /^[a-f0-9]{64}$/.test(d.policySha256) && /^[a-f0-9]{64}$/.test(d.acceptanceDigest)
+    && d.acceptanceDigest === acceptanceDigest && Array.isArray(d.pendingCriterionIds)
+    && d.pendingCriterionIds.length > 0 && d.pendingCriterionIds.length <= 12
+    && new Set(d.pendingCriterionIds).size === d.pendingCriterionIds.length
+    && d.pendingCriterionIds.every(id => typeof id === "string" && id.length > 0 && id.length <= 160));
+}
+
+export function diagnosticDeliveryMatchesTask(d: DiagnosticDelivery, task: TaskContract, acceptanceDigest: string): boolean {
+  const pending = (task.acceptanceReceipt?.criteria ?? []).filter(c => c.status !== "satisfied").map(c => c.id).sort();
+  return validDiagnosticDelivery(d, acceptanceDigest) && d.policySha256 === installedDiagnosticPolicyDigest()
+    && JSON.stringify([...d.pendingCriterionIds].sort()) === JSON.stringify(pending);
+}
+
+export function diagnosticDeliveryStateErrors(state: Record<string, any> | null, acceptance: Record<string, any> | null): string[] {
+  const d = state?.diagnosticDelivery;
+  if (d === undefined) return [];
+  return !validDiagnosticDelivery(d, acceptance?.dispositionDigest) || state?.completionApproved !== false
+    || acceptance?.satisfied !== false || state?.gateDecision !== "pass" || state?.taskOutcome !== "completed"
+    || d.pendingCriterionIds.length > (acceptance?.criteriaCount ?? 0) ? ["diagnostic delivery is invalid"] : [];
+}
+
+export function buildDiagnosticDelivery(task: TaskContract,
+  gate: { decision: string; missing: string[]; missingVerifyCommands: string[];
+    acceptanceProof?: { mode: string; pendingCriterionIds: string[] } },
+  acceptance: { satisfied: boolean; dispositionDigest: string }, operationalEvidenceCurrent: boolean): DiagnosticDelivery | undefined {
+  const policySha256 = installedDiagnosticPolicyDigest();
+  return !acceptance.satisfied && policySha256 && gate.acceptanceProof?.mode === "diagnostic"
+    && gate.decision === "pass" && task.trace.outcome === "completed" && operationalEvidenceCurrent
+    && gate.missing.length === 0 && gate.missingVerifyCommands.length === 0
+    ? { mode: "diagnostic", qualityClaim: "withheld", policySha256,
+      acceptanceDigest: acceptance.dispositionDigest, pendingCriterionIds: [...gate.acceptanceProof.pendingCriterionIds] }
+    : undefined;
+}
+
+export function diagnosticCompletionMissing(decision: string, missing: string[], acceptanceSatisfied: boolean,
+  evidenceCurrent: boolean, gateDigestCurrent: boolean, currentExactVerifier: boolean): string[] {
+  return [...missing,
+    ...(decision === "pass" && !acceptanceSatisfied ? ["acceptance-criteria-pending"] : []),
+    ...(decision === "pass" && !evidenceCurrent ? ["working-tree-evidence-not-current"] : []),
+    ...(decision === "pass" && !gateDigestCurrent ? ["completion-gate-tree-digest-untrusted-or-mismatched"] : []),
+    ...(decision === "pass" && !currentExactVerifier ? ["current exact verifier evidence"] : [])];
+}