@piagent/platform 1.6.0 → 1.6.1

package/packages/piagent-core/runtime/orchestration/subagent-tool-policy.ts

@@ -0,0 +1,329 @@
+import crypto from "node:crypto";
+import path from "node:path";
+
+import type { TaskContract } from "../../extensions/guard-types.js";
+import { taskAuthorityMode } from "../policy/task-authority-runtime.ts";
+import { MINIMAL_DELEGATION_LIMITS } from "./minimal-delegation-policy.ts";
+
+const SUBAGENT_TOOL = /(?:^|[_-])subagents?(?:[_-]|$)/i;
+const NON_DISPATCH_ACTIONS = new Set(["cancel", "kill", "list", "status", "stop", "wait"]);
+const READ_ONLY_AGENTS = new Set([
+  "piagent-oracle",
+  "piagent-planner",
+  "piagent-reviewer",
+  "piagent-scout"
+]);
+const URL = /\bhttps?:\/\/[^\s<>)\]}]+/i;
+const PROVIDED_SOURCE = /\b(?:provided|supplied|attached|pasted)\s+(?:evidence|source|text)|\busing only (?:the )?(?:evidence|source|text) below|\bdo not (?:fetch|open|retrieve)|\bn[oộ]i dung (?:đ[aã] )?(?:cung c[aấ]p|d[aá]n|đ[ií]nh k[eè]m)/i;
+
+type PlainRecord = Record<string, unknown>;
+
+export type DirectSubagentDispatchPreflight = {
+  applicable: boolean;
+  dispatch: boolean;
+  allowed: boolean;
+  reasonCode: string | null;
+  reason: string | null;
+  role: string | null;
+  requestCount: number;
+};
+
+export type DirectSubagentResult = {
+  applicable: boolean;
+  spawned: boolean;
+  failed: boolean;
+  reasonCode: string | null;
+  disposition: string;
+  role: "retriever" | "scout" | "planner" | "worker" | "reviewer" | "oracle" | "researcher";
+  requestRef: string;
+  outputDigest: string | null;
+  calls: number;
+  tokens: number;
+};
+
+type DirectSubagentTaskPersistence = {
+  now: () => string;
+  persist: (task: TaskContract) => TaskContract;
+  trace: (payload: Record<string, unknown>) => void;
+  sessionTrace?: (payload: Record<string, unknown>) => void;
+};
+
+export function taskHelperUsageMode(task: TaskContract): "off" | "recommend" | "on" {
+  const boundMode = taskAuthorityMode(task, "CAP-14");
+  return boundMode === "on" || boundMode === "recommend" ? boundMode : "off";
+}
+
+export function reserveDirectSubagentDispatch(
+  task: TaskContract | undefined,
+  toolCallId: string,
+  persistence: DirectSubagentTaskPersistence
+): TaskContract | undefined {
+  if (!task || task.trace.outcome !== "pending" || task.orchestration?.subagents !== "not-used") return task;
+  task.orchestration = {
+    ...(task.orchestration ?? {
+      mode: "solo-first" as const,
+      subagents: "not-used" as const,
+      reason: "Parent works directly by default."
+    }),
+    subagents: "optional",
+    reason: "One bounded read-only helper dispatch is authorized and awaiting a durable result."
+  };
+  task.updatedAt = persistence.now();
+  const written = persistence.persist(task);
+  persistence.trace({
+    event: "helper_dispatch_reserved",
+    taskId: written.taskId,
+    taskRunId: written.taskRunId,
+    sessionId: written.sessionId,
+    toolCallId
+  });
+  return written;
+}
+
+export function recordDirectSubagentResult(
+  task: TaskContract | undefined,
+  event: { toolCallId?: string; toolName: string },
+  result: DirectSubagentResult,
+  persistence: DirectSubagentTaskPersistence
+): TaskContract | undefined {
+  if (!task || task.trace.outcome !== "pending") return task;
+  const existingUsage = task.acceptanceReceipt?.helperUsage;
+  const helper = {
+    role: result.role,
+    disposition: result.disposition,
+    requestRef: result.requestRef,
+    outputDigest: result.outputDigest,
+    calls: result.calls,
+    tokens: result.tokens
+  };
+  const helpers = result.spawned
+    ? [...(existingUsage?.helpers ?? []).filter((item) => item.requestRef !== result.requestRef), helper].slice(-3)
+    : existingUsage?.helpers ?? [];
+  const used = helpers.length > 0 || existingUsage?.used === true;
+  const reasonCodes = [...new Set([
+    ...(existingUsage?.reasonCodes ?? []),
+    result.reasonCode ?? (result.spawned ? "helper-result-accepted" : "helper-dispatch-rejected")
+  ])].slice(-16);
+  if (task.acceptanceReceipt) {
+    task.acceptanceReceipt.helperUsage = {
+      mode: taskHelperUsageMode(task),
+      used,
+      decision: result.spawned ? "dispatch" : "skip",
+      projectedSavingsRatio: existingUsage?.projectedSavingsRatio ?? null,
+      reasonCodes,
+      helpers,
+      recordedAt: persistence.now()
+    };
+  }
+  if (task.orchestration) {
+    task.orchestration.subagents = used ? "used" : "not-used";
+    task.orchestration.reason = result.spawned
+      ? `A bounded read-only helper ran with disposition ${result.disposition}; its digest-only usage is recorded in the acceptance receipt.`
+      : `Helper dispatch did not start (${result.reasonCode ?? "helper-dispatch-rejected"}); the parent remains the sole execution owner.`;
+  }
+  task.updatedAt = persistence.now();
+  const written = persistence.persist(task);
+  const trace = {
+    event: "helper_result_recorded",
+    taskId: written.taskId,
+    taskRunId: written.taskRunId,
+    sessionId: written.sessionId,
+    toolCallId: event.toolCallId,
+    toolName: event.toolName,
+    spawned: result.spawned,
+    disposition: result.disposition,
+    reasonCode: result.reasonCode,
+    calls: result.calls,
+    tokens: result.tokens
+  };
+  persistence.trace(trace);
+  persistence.sessionTrace?.(trace);
+  return written;
+}
+
+function record(value: unknown): PlainRecord {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as PlainRecord : {};
+}
+
+function finiteInteger(value: unknown, fallback = 0): number {
+  return typeof value === "number" && Number.isFinite(value)
+    ? Math.max(0, Math.trunc(value))
+    : fallback;
+}
+
+function helperRole(value: unknown): DirectSubagentResult["role"] {
+  const normalized = String(value ?? "").trim().toLowerCase().replace(/^piagent-/, "");
+  return ["retriever", "scout", "planner", "worker", "reviewer", "oracle", "researcher"].includes(normalized)
+    ? normalized as DirectSubagentResult["role"]
+    : "scout";
+}
+
+function dispatchRequests(input: PlainRecord): PlainRecord[] {
+  if (Array.isArray(input.tasks)) {
+    return input.tasks.filter((item): item is PlainRecord => Boolean(item && typeof item === "object" && !Array.isArray(item)))
+      .map((item) => ({ ...input, ...item, tasks: undefined }));
+  }
+  return typeof input.agent === "string" && input.agent.trim() ? [input] : [];
+}
+
+function boundedNumber(input: PlainRecord, nestedField: string, field: string): number | undefined {
+  const nested = record(input[nestedField]);
+  const value = nested[field];
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function sameProjectRoot(currentCwd: string, requested: unknown): boolean {
+  if (typeof requested !== "string" || !requested.trim()) return true;
+  return path.resolve(currentCwd) === path.resolve(currentCwd, requested);
+}
+
+function blocked(reasonCode: string, reason: string, role: string | null, requestCount: number): DirectSubagentDispatchPreflight {
+  return { applicable: true, dispatch: true, allowed: false, reasonCode, reason, role, requestCount };
+}
+
+/**
+ * The optional pi-subagents tool is a second execution backend. It must not be
+ * able to bypass the task-bound CAP-14 snapshot merely because the model knows
+ * the tool name. This preflight is deliberately conservative: one fresh,
+ * read-only, locally capable helper, with the same hard ceilings as Piagent's
+ * owned helper runtime.
+ */
+export function evaluateDirectSubagentDispatch(input: {
+  toolName: string;
+  toolInput: unknown;
+  cwd: string;
+  helpersMode: "off" | "recommend" | "on";
+  taskPending: boolean;
+  dispatchAuthority: boolean;
+  durableSubagentState?: "not-used" | "optional" | "used";
+}): DirectSubagentDispatchPreflight {
+  if (!SUBAGENT_TOOL.test(input.toolName)) {
+    return { applicable: false, dispatch: false, allowed: true, reasonCode: null, reason: null, role: null, requestCount: 0 };
+  }
+  const toolInput = record(input.toolInput);
+  const requests = dispatchRequests(toolInput);
+  const action = String(toolInput.action ?? "").trim().toLowerCase();
+  if (requests.length === 0 && NON_DISPATCH_ACTIONS.has(action)) {
+    return { applicable: true, dispatch: false, allowed: true, reasonCode: null, reason: null, role: null, requestCount: 0 };
+  }
+  if (requests.length === 0) return blocked("helper-dispatch-shape-invalid", "Subagent dispatch requires exactly one named read-only helper.", null, 0);
+  const role = String(requests[0].agent ?? "").trim();
+  if (requests.length !== 1) return blocked("helper-count-exceeds-one", `Piagent permits at most one helper for the entire task; ${requests.length} were requested.`, role || null, requests.length);
+  if (!input.taskPending) return blocked("helper-task-authority-missing", "A pending session-bound task is required before helper dispatch.", role || null, 1);
+  if (input.helpersMode !== "on" || !input.dispatchAuthority) {
+    return blocked("helper-dispatch-authority-disabled", "Task-bound helper authority is not on; continue in the parent model.", role || null, 1);
+  }
+  if (input.durableSubagentState === "optional" || input.durableSubagentState === "used") {
+    return blocked("helper-retry-forbidden", "This task already reserved or used its one helper; helper retries are disabled.", role || null, 1);
+  }
+  if (role === "piagent-worker" || !READ_ONLY_AGENTS.has(role)) {
+    return blocked("automatic-helper-role-disabled", `Automatic helper ${role || "(unknown)"} is not an enabled read-only Piagent role.`, role || null, 1);
+  }
+  const request = requests[0];
+  if (request.context !== undefined && request.context !== "fresh") {
+    return blocked("helper-parent-history-forbidden", "Helpers must use fresh isolated context and cannot fork the parent transcript.", role, 1);
+  }
+  if (!sameProjectRoot(input.cwd, request.cwd)) {
+    return blocked("helper-cwd-outside-project", "Helper cwd must remain the current project root.", role, 1);
+  }
+  const timeoutMs = typeof request.timeoutMs === "number" ? request.timeoutMs : undefined;
+  if (timeoutMs === undefined) {
+    return blocked("helper-time-budget-missing", "Helper dispatch requires an explicit timeoutMs no greater than 300 seconds.", role, 1);
+  }
+  if (!Number.isFinite(timeoutMs) || timeoutMs > 300_000 || timeoutMs < 1) {
+    return blocked("helper-time-budget-exceeded", "Helper timeout must be between 1 ms and the 300 second Piagent ceiling.", role, 1);
+  }
+  const maxTurns = boundedNumber(request, "turnBudget", "maxTurns");
+  if (maxTurns === undefined) {
+    return blocked("helper-turn-budget-missing", "Helper dispatch requires an explicit turnBudget.maxTurns no greater than 8.", role, 1);
+  }
+  if (maxTurns < 1 || maxTurns > 8) {
+    return blocked("helper-turn-budget-exceeded", "Helper maxTurns exceeds the bounded 8-turn ceiling.", role, 1);
+  }
+  const hardCalls = boundedNumber(request, "toolBudget", "hard");
+  if (hardCalls === undefined) {
+    return blocked("helper-call-budget-missing", `Helper dispatch requires an explicit toolBudget.hard no greater than ${MINIMAL_DELEGATION_LIMITS.maxHelperCalls}.`, role, 1);
+  }
+  if (hardCalls < 1 || hardCalls > MINIMAL_DELEGATION_LIMITS.maxHelperCalls) {
+    return blocked("helper-call-budget-exceeded", `Helper hard tool budget exceeds the ${MINIMAL_DELEGATION_LIMITS.maxHelperCalls}-call ceiling.`, role, 1);
+  }
+  const objective = String(request.task ?? "").trim();
+  if (!objective) return blocked("helper-objective-missing", "Helper dispatch requires a bounded objective.", role, 1);
+  if (URL.test(objective) && !PROVIDED_SOURCE.test(objective)) {
+    return blocked("helper-source-access-unavailable", "The selected helper has local read tools only and cannot retrieve the remote URL; inspect it in the parent or provide a local checkout/evidence bundle.", role, 1);
+  }
+  return { applicable: true, dispatch: true, allowed: true, reasonCode: null, reason: null, role, requestCount: 1 };
+}
+
+function textContent(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content.filter((item) => item && typeof item === "object" && (item as { type?: unknown }).type === "text")
+    .map((item) => String((item as { text?: unknown }).text ?? "")).join("\n");
+}
+
+function childAcceptanceFailed(result: PlainRecord): boolean {
+  const acceptance = record(result.acceptance);
+  const report = record(acceptance.childReport);
+  const criteria = Array.isArray(report.criteriaSatisfied) ? report.criteriaSatisfied : [];
+  return criteria.some((item) => record(item).status === "not-satisfied")
+    || ["failed", "rejected", "not-satisfied"].includes(String(acceptance.status ?? "").toLowerCase());
+}
+
+function totalUsage(details: PlainRecord, results: PlainRecord[]): number {
+  const aggregate = record(details.totalChildUsage);
+  const sources = Object.keys(aggregate).length > 0 ? [aggregate] : results.map((result) => record(result.usage));
+  return Math.min(100_000_000, sources.reduce((total, usage) => total
+    + finiteInteger(usage.input)
+    + finiteInteger(usage.output)
+    + finiteInteger(usage.cacheRead)
+    + finiteInteger(usage.cacheWrite), 0));
+}
+
+/** Convert a pi-subagents provider result into fail-closed, digest-only truth. */
+export function classifyDirectSubagentResult(input: {
+  toolName: string;
+  toolInput: unknown;
+  content: unknown;
+  details: unknown;
+  isError?: boolean;
+}): DirectSubagentResult | undefined {
+  if (!SUBAGENT_TOOL.test(input.toolName)) return undefined;
+  const toolInput = record(input.toolInput);
+  if (dispatchRequests(toolInput).length === 0) return undefined;
+  const details = record(input.details);
+  const results = Array.isArray(details.results)
+    ? details.results.filter((item): item is PlainRecord => Boolean(item && typeof item === "object" && !Array.isArray(item)))
+    : [];
+  const spawned = results.length > 0 || typeof details.runId === "string" && details.runId.length > 0;
+  const resultFailures = results.some((result) => finiteInteger(result.exitCode) !== 0 || childAcceptanceFailed(result));
+  const content = textContent(input.content);
+  const insufficientEvidence = results.some(childAcceptanceFailed)
+    || /\bscope inspected:\s*none\b|\bno source (?:content|evidence) (?:was|could be) (?:accessible|collected)|\bcriteria?[^\n]{0,80}not-satisfied\b/i.test(content);
+  const failed = input.isError === true || !spawned || resultFailures || insufficientEvidence;
+  const reasonCode = input.isError === true
+    ? "helper-tool-error"
+    : !spawned
+      ? "helper-dispatch-rejected"
+      : insufficientEvidence
+        ? "helper-insufficient-evidence"
+        : resultFailures
+          ? "helper-run-failed"
+          : null;
+  const firstResult = results[0] ?? {};
+  const agent = firstResult.agent ?? dispatchRequests(toolInput)[0]?.agent;
+  const finalOutput = results.map((result) => String(result.finalOutput ?? "")).filter(Boolean).join("\n");
+  const calls = Math.min(100, results.reduce((total, result) => total + finiteInteger(result.toolCount), 0));
+  return {
+    applicable: true,
+    spawned,
+    failed,
+    reasonCode,
+    disposition: failed ? reasonCode ?? "failed" : "succeeded",
+    role: helperRole(agent),
+    requestRef: crypto.createHash("sha256").update(JSON.stringify(toolInput)).digest("hex"),
+    outputDigest: !failed && finalOutput ? crypto.createHash("sha256").update(finalOutput).digest("hex") : null,
+    calls,
+    tokens: totalUsage(details, results)
+  };
+}

package/packages/piagent-core/runtime/policy/block-remedy.ts

@@ -43,10 +43,6 @@ const REMEDIES: Array<{ match: RegExp; remedy: string }> = [
     match: /outside resolved filesystem scope/i,
     remedy: "Work inside the project, or widen the filesystem scope in the active profile and reapply it."
   },
-  {
-    match: /cannot mutate paths outside its declared scope|semantic repair must stay inside its declared task scope/i,
-    remedy: "Start a new attempt with `piagent_task_start` listing this path in the scope; a running task cannot widen its own."
-  },
   {
     match: /Task Implementation Contract is required/i,
     remedy: "Call `piagent_task_start` once with explicit project-relative scope, then retry."

package/packages/piagent-core/runtime/product/efficiency-metrics.ts

@@ -112,6 +112,9 @@ export function buildTaskEfficiencyMetrics(
     helpers: {
       mode: helperUsage?.mode ?? "unknown",
       used: helperUsage?.used ?? false,
+      decision: helperUsage?.decision ?? (helperUsage?.used ? "dispatch" : "skip"),
+      projectedSavingsRatio: helperUsage?.projectedSavingsRatio ?? null,
+      reasonCodes: helperUsage?.reasonCodes ?? ["parent-direct-default"],
       entries: (helperUsage?.helpers ?? []).map((item) => ({
         role: item.role,
         model: null,

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/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/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: {