@piagent/platform 1.5.5 → 1.6.0

package/packages/piagent-core/runtime/inspection/task-handoff-history.ts

@@ -60,7 +60,7 @@ export function projectTaskHandoffHistory(input: { cwd: string; task: Task; iden
     const matching = inspected.records.flatMap((record: any, ordinal: number) => {
       if (record?.event !== "handoff_projection_written" || record.taskId !== input.task.taskId
         || record.taskRunId !== input.task.taskRunId || record.sessionId !== input.task.sessionId) return [];
-      if (record.schemaVersion !== 1 || !timestamp(record.recordedAt) || typeof record.completionApproved !== "boolean") { malformed += 1; return []; }
+      if (![1, 2].includes(record.schemaVersion) || !timestamp(record.recordedAt) || typeof record.completionApproved !== "boolean") { malformed += 1; return []; }
       const action = display(record.recoveryAction, 80) || "unknown", phase = display(record.phase, 64) || null;
       return [{ ordinal, recordedAt: record.recordedAt, phase, completionApproved: record.completionApproved, projectedAction: action }];
     });

package/packages/piagent-core/runtime/inspection/tool-failure-classification.ts

@@ -0,0 +1,53 @@
+export type ToolFailureReasonCode =
+  | "target-not-found"
+  | "search-target-missing"
+  | "edit-anchor-not-unique"
+  | "edit-anchor-stale"
+  | "tool-result-failed";
+
+function boundedText(content: unknown): string {
+  const text = typeof content === "string" ? content : Array.isArray(content)
+    ? content.filter((item) => item && typeof item === "object" && (item as { type?: unknown }).type === "text")
+      .map((item) => String((item as { text?: unknown }).text ?? "")).join("\n")
+    : "";
+  return text.slice(0, 8_192);
+}
+
+function commandFromInput(input: unknown): string {
+  if (!input || typeof input !== "object") return "";
+  const direct = (input as { command?: unknown }).command;
+  if (typeof direct === "string") return direct;
+  const args = (input as { args?: unknown }).args;
+  return args && typeof args === "object" && typeof (args as { command?: unknown }).command === "string"
+    ? (args as { command: string }).command : "";
+}
+
+export function classifyToolFailure(toolName: string, isError: boolean, content: unknown, input?: unknown): ToolFailureReasonCode | null {
+  if (!isError) return null;
+  const text = boundedText(content);
+  // Only the registered, policy-governed `edit` tool may receive an automatic
+  // current-file recovery snapshot. A similarly named third-party `replace`
+  // tool is not necessarily covered by Piagent's mutation guard.
+  if (/^edit$/i.test(toolName)) {
+    if (/\b(?:oldtext|old text)\b[^\n]{0,240}\b(?:unique|occurrences?)\b|\bfound\s+\d+\s+occurrences?\b/i.test(text)) {
+      return "edit-anchor-not-unique";
+    }
+    if (/could not find (?:the )?exact text|\b(?:oldtext|old text)\b[^\n]{0,240}\b(?:match|mismatch|stale|changed|find)\b|\b(?:generation|content) drift\b/i.test(text)) {
+      return "edit-anchor-stale";
+    }
+  }
+  const readLike = /(?:^|[._-])(?:read|document[_-]?read)(?:$|[._-])/i.test(toolName);
+  if (readLike && /\bENOENT\b|no such file or directory|file (?:does not exist|not found)|cannot find the (?:file|path)/i.test(text)) {
+    return "target-not-found";
+  }
+  const shellLike = /^(?:bash|shell|exec|command)$/i.test(toolName);
+  const searchCommand = /^\s*(?:rg|grep|git\s+grep)\b/.test(commandFromInput(input));
+  const missingTarget = /no such file or directory|cannot find the (?:file|path)|\bos error 2\b/i.test(text);
+  const usefulMatches = text.split(/\r?\n/).some((line) => !/^\s*(?:rg|grep):/i.test(line) && /^.+?:\d+:/.test(line));
+  if (shellLike && searchCommand && missingTarget && usefulMatches) return "search-target-missing";
+  return "tool-result-failed";
+}
+
+export function handledToolFailure(reasonCode: unknown): boolean {
+  return reasonCode === "search-target-missing";
+}

package/packages/piagent-core/runtime/inspection/webui-snapshot.ts

@@ -8,6 +8,8 @@ import { workingTreeEvidenceDigest, workingTreeSnapshotUsesCurrentAlgorithm } fr
 import { inspectTaskContinuationBudget } from "../recovery/continuation-budget.ts";
 import { readHandoffProjection } from "../recovery/handoff-projection.ts";
 import type { ActivityInspectorEvent, CurrentActivity } from "../product/activity-inspector.ts";
+import { recoveredToolCalls } from "./activity-recovery.ts";
+import { classifyToolFailure, handledToolFailure } from "./tool-failure-classification.ts";
 import { projectCriteriaFileVerifier, type CriteriaLinkProjection } from "./criteria-links.ts";
 import { collectSourceChangeViews, type SourceChangeDocument, type WebUiIdentity } from "./source-change-projection.ts";
 
@@ -82,6 +84,27 @@ function scopedEvents(events: ActivityInspectorEvent[], sessionId: string, task?
   return [...deduped.values()].sort((left, right) => String(left.recordedAt).localeCompare(String(right.recordedAt))).slice(-2_000);
 }
 
+function enrichedFailureReasons(events: ActivityInspectorEvent[], sessionEntries: unknown[]): ActivityInspectorEvent[] {
+  const inputs = new Map<string, unknown>(), results = new Map<string, { content: unknown; isError: boolean; toolName: string }>();
+  for (const entry of sessionEntries) {
+    if (!entry || typeof entry !== "object" || (entry as any).type !== "message") continue;
+    const message = (entry as any).message;
+    if (message?.role === "assistant" && Array.isArray(message.content)) {
+      for (const block of message.content) if (block?.type === "toolCall" && typeof block.id === "string") inputs.set(block.id, block.arguments);
+    }
+    if (message?.role === "toolResult" && typeof message.toolCallId === "string") {
+      results.set(message.toolCallId, { content: message.content, isError: message.isError === true, toolName: String(message.toolName ?? "unknown") });
+    }
+  }
+  return events.map((event) => {
+    if (event.event !== "tool_result" || !event.toolCallId || !event.isError) return event;
+    const raw = results.get(event.toolCallId);
+    if (!raw) return event;
+    const reasonCode = classifyToolFailure(raw.toolName, raw.isError, raw.content, inputs.get(event.toolCallId));
+    return reasonCode ? { ...event, reasonCode } : event;
+  });
+}
+
 function sourceSummary(document: SourceChangeDocument | null, view: "task" | "working-tree" | "staged") {
   if (!document || document.availability.state === "unavailable") return {
     view, base: view === "task" ? "task-baseline" : "HEAD", state: "unavailable", revision: null,
@@ -109,21 +132,26 @@ function sourceSummary(document: SourceChangeDocument | null, view: "task" | "wo
 function activityProjection(events: ActivityInspectorEvent[], current: CurrentActivity[]) {
   const results = new Map(events.filter((event) => event.event === "tool_result").map((event) => [event.toolCallId, event]));
   const decisions = new Map(events.filter((event) => event.event === "tool_decision").map((event) => [event.toolCallId, event]));
+  const recoveries = recoveredToolCalls(events);
   const calls = events.filter((event) => event.event === "tool_call").slice(-200);
   const projected = calls.map((call) => {
     const result = results.get(call.toolCallId), decision = decisions.get(call.toolCallId);
     const blocked = decision?.decision === "blocked";
-    const failed = !blocked && Boolean(result && (result.isError === true || (typeof result.exitCode === "number" && result.exitCode !== 0)));
-    const state = blocked ? "blocked" : !result ? "running" : failed ? "failed" : "passed";
+    const handled = Boolean(result && handledToolFailure(result.reasonCode));
+    const failed = !blocked && !handled && Boolean(result && (result.isError === true || (typeof result.exitCode === "number" && result.exitCode !== 0)));
+    const recovery = call.toolCallId ? recoveries.get(call.toolCallId) : undefined;
+    const state = blocked ? "blocked" : !result ? "running" : failed && !recovery ? "failed" : "passed";
     const toolName = display(call.toolName ?? "unknown", 80).replace(/[^A-Za-z0-9._:@~-]/g, "-") || "unknown";
     const rawId = String(call.toolCallId ?? call.activityId ?? `${call.recordedAt}:${toolName}`);
     const command = display(call.command ?? call.targetPath ?? toolName, 65_536);
     return {
       activityRef: token("activity", [rawId, call.recordedAt]), kind: ["bash", "shell", "exec"].includes(toolName) ? "command" : "tool", state,
-      label: display(state === "running" ? `${toolName} running` : `${toolName} ${state}`, 500), preview: command,
+      label: display(recovery ? `${toolName} recovered` : handled ? `${toolName} warning` : state === "running" ? `${toolName} running` : `${toolName} ${state}`, 500), preview: command,
       toolCallId: token("tool", rawId), toolName, commandDigest: call.command ? `sha256:${hash(call.command)}` : null,
-      logRef: null, exitCode: typeof result?.exitCode === "number" ? result.exitCode : null, exitCodeExact: result?.exitCodeExact === true,
-      startedAt: timestamp(call.recordedAt), finishedAt: result || blocked ? timestamp(result?.recordedAt ?? decision?.recordedAt, timestamp(call.recordedAt)) : null
+      logRef: null, exitCode: recovery?.exitCode ?? (typeof result?.exitCode === "number" ? result.exitCode : null),
+      exitCodeExact: recovery?.exitCodeExact ?? (result?.exitCodeExact === true),
+      startedAt: timestamp(call.recordedAt), finishedAt: recovery ? timestamp(recovery.recoveredAt, timestamp(call.recordedAt))
+        : result || blocked ? timestamp(result?.recordedAt ?? decision?.recordedAt, timestamp(call.recordedAt)) : null
     };
   });
   const callIds = new Set(calls.map((call) => String(call.toolCallId ?? "")));
@@ -274,7 +302,7 @@ export async function buildWebUiInspectionProjection(input: {
   const taskRevision = input.task ? webUiTaskRevision(input.task) : null;
   const views = await collectSourceChangeViews({ cwd: input.cwd, identity, generatedAt, taskRevision,
     isProtectedPath: (_root, repoPath) => Boolean(matchesProtectedPath(repoPath, effectiveProtectedPaths)) });
-  const events = scopedEvents(input.events ?? [], input.sessionId, input.task);
+  const events = enrichedFailureReasons(scopedEvents(input.events ?? [], input.sessionId, input.task), input.sessionEntries ?? []);
   const linked = projectCriteriaFileVerifier({ cwd: input.cwd, task: input.task, sourceViews: views, currentSnapshot,
     protectedPaths: input.protectedPaths, events, at: new Date(generatedAt) });
   const sourceChanges = { task: sourceSummary(linked.sourceViews.task, "task"), workingTree: sourceSummary(linked.sourceViews.workingTree, "working-tree"), staged: sourceSummary(linked.sourceViews.staged, "staged") };

package/packages/piagent-core/runtime/model/authenticated-catalog.ts

@@ -50,14 +50,22 @@ function positiveInteger(value: unknown): number | null {
   return Number.isInteger(value) && Number(value) > 0 && Number(value) <= 10_000_000 ? Number(value) : null;
 }
 
-function thinkingLevels(value: unknown): string[] | null {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
-  const levels = Object.entries(value)
-    .filter(([, mapped]) => mapped !== null && mapped !== false)
-    .map(([level]) => text(level))
-    .filter(Boolean)
-    .sort();
-  return levels.length > 0 ? [...new Set(levels)].slice(0, 16) : [];
+const PI_THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+
+function thinkingLevels(value: ModelLike): string[] | null {
+  if (typeof value.reasoning !== "boolean") return null;
+  if (!value.reasoning) return ["off"];
+  const mapping = value.thinkingLevelMap && typeof value.thinkingLevelMap === "object" && !Array.isArray(value.thinkingLevelMap)
+    ? value.thinkingLevelMap as Record<string, unknown>
+    : {};
+  // Match Pi's getSupportedThinkingLevels semantics. Reasoning models support
+  // the standard host levels through `high` unless a model explicitly marks a
+  // level null. `xhigh` and `max` are opt-in capabilities.
+  return PI_THINKING_LEVELS.filter((level) => {
+    const mapped = mapping[level];
+    if (mapped === null) return false;
+    return level === "xhigh" || level === "max" ? mapped !== undefined : true;
+  });
 }
 
 function boundedModel(value: ModelLike): AuthenticatedModelCatalogEntry | undefined {
@@ -71,7 +79,7 @@ function boundedModel(value: ModelLike): AuthenticatedModelCatalogEntry | undefi
     contextWindow: positiveInteger(value.contextWindow),
     reasoning: typeof value.reasoning === "boolean" ? value.reasoning : null,
     imageInput: input ? input.includes("image") : null,
-    supportedThinkingLevels: thinkingLevels(value.thinkingLevelMap)
+    supportedThinkingLevels: thinkingLevels(value)
   };
 }
 

package/packages/piagent-core/runtime/model/openai-codex-reasoning.ts

@@ -0,0 +1,83 @@
+type ProviderPayload = Record<string, unknown>;
+
+const GPT56_CODEX_MODEL = /^gpt-5\.6-(?:luna|sol|terra)$/;
+const PROVIDER_EFFORT_BY_HOST_LEVEL: Readonly<Record<string, string>> = Object.freeze({
+  off: "none",
+  minimal: "low",
+  low: "low",
+  medium: "medium",
+  high: "high",
+  xhigh: "xhigh",
+  max: "max"
+});
+
+export type OpenAiCodexReasoningNormalization = {
+  payload: unknown;
+  applicable: boolean;
+  changed: boolean;
+  hostThinkingLevel: string;
+  expectedProviderEffort: string | null;
+  providerEffort: string | null;
+  reasonCode: "not-applicable" | "observed" | "off-normalized-to-none" | "minimal-normalized-to-low" | "provider-effort-normalized";
+};
+
+function record(value: unknown): ProviderPayload | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value as ProviderPayload : null;
+}
+
+function effortFromPayload(payload: ProviderPayload): string | null {
+  const reasoning = record(payload.reasoning);
+  return typeof reasoning?.effort === "string" ? reasoning.effort : null;
+}
+
+/**
+ * Compatibility bridge for the pinned Pi host's OpenAI Codex serializer.
+ *
+ * Pi names the provider's `none` effort `off`. Pi 0.84.1 currently drops
+ * `off` before its request builder, which omits the reasoning object and lets
+ * GPT-5.6 use its server default. Enforce the same-model/effort invariant for
+ * every host level, while keeping the correction deliberately narrow to the
+ * three authenticated GPT-5.6 Codex models whose capability map we audit.
+ */
+export function normalizeOpenAiCodexReasoningPayload(input: {
+  payload: unknown;
+  provider: unknown;
+  modelId: unknown;
+  hostThinkingLevel: unknown;
+}): OpenAiCodexReasoningNormalization {
+  const provider = String(input.provider ?? "");
+  const modelId = String(input.modelId ?? "");
+  const hostThinkingLevel = String(input.hostThinkingLevel ?? "");
+  const payload = record(input.payload);
+  const expectedProviderEffort = PROVIDER_EFFORT_BY_HOST_LEVEL[hostThinkingLevel] ?? null;
+  const applicable = provider === "openai-codex" && GPT56_CODEX_MODEL.test(modelId)
+    && payload !== null && payload.model === modelId && expectedProviderEffort !== null;
+  if (!applicable || !payload) {
+    return { payload: input.payload, applicable: false, changed: false, hostThinkingLevel,
+      expectedProviderEffort, providerEffort: payload ? effortFromPayload(payload) : null, reasonCode: "not-applicable" };
+  }
+
+  const currentEffort = effortFromPayload(payload);
+  if (currentEffort === expectedProviderEffort) {
+    return { payload: input.payload, applicable: true, changed: false, hostThinkingLevel,
+      expectedProviderEffort, providerEffort: currentEffort, reasonCode: "observed" };
+  }
+
+  const currentReasoning = record(payload.reasoning) ?? {};
+  const normalizedReasoning = {
+    ...currentReasoning,
+    effort: expectedProviderEffort,
+    ...(typeof currentReasoning.summary === "string" ? {} : { summary: "auto" })
+  };
+  return {
+    payload: { ...payload, reasoning: normalizedReasoning },
+    applicable: true,
+    changed: true,
+    hostThinkingLevel,
+    expectedProviderEffort,
+    providerEffort: expectedProviderEffort,
+    reasonCode: hostThinkingLevel === "off" ? "off-normalized-to-none"
+      : hostThinkingLevel === "minimal" ? "minimal-normalized-to-low"
+        : "provider-effort-normalized"
+  };
+}

package/packages/piagent-core/runtime/model/provider-wire-fingerprint.ts

@@ -0,0 +1,238 @@
+import crypto from "node:crypto";
+
+type JsonRecord = Record<string, unknown>;
+type BoundReason = "instructions-unavailable" | "instructions-too-large" | "tools-invalid" | "tools-too-large"
+  | "input-invalid" | "input-too-large" | "deferred-tools-invalid" | "deferred-tools-too-large"
+  | "surface-too-deep" | "surface-too-large" | "surface-not-json" | "surface-cyclic";
+
+const MAX_INSTRUCTIONS_CHARS = 1_000_000;
+const MAX_TOOLS = 512;
+const MAX_INPUT_ITEMS = 4_096;
+const MAX_SURFACE_DEPTH = 32;
+const MAX_SURFACE_NODES = 50_000;
+const MAX_SURFACE_STRING_CHARS = 2_000_000;
+const MAX_CONTAINER_ITEMS = 4_096;
+const PUBLIC_ID = /^[A-Za-z0-9][A-Za-z0-9._:@~-]{0,159}$/;
+const CONTROL_VALUE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/;
+
+export type ProviderWireFingerprint = {
+  applicable: boolean;
+  state: "known" | "unavailable";
+  reasonCode: BoundReason | "not-applicable" | null;
+  modelId: string | null;
+  instructionsHash: string | null;
+  baseInstructionsHash: string | null;
+  instructionNormalization: "host-relocation-v1" | "none" | null;
+  instructionChars: number | null;
+  orderedToolSurfaceHash: string | null;
+  toolCount: number | null;
+  deferredToolSurfaceHash: string | null;
+  deferredToolCount: number | null;
+  deferredToolBatchCount: number | null;
+  reasoningEffort: string | null;
+  textVerbosity: string | null;
+  toolChoiceKind: string | null;
+  toolChoiceHash: string | null;
+  requestPrefixFingerprint: string | null;
+};
+
+class SurfaceBoundError extends Error {
+  readonly reasonCode: BoundReason;
+  constructor(reasonCode: BoundReason) { super(reasonCode); this.reasonCode = reasonCode; }
+}
+
+function record(value: unknown): JsonRecord | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value as JsonRecord : null;
+}
+
+function hash(value: string): string {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function control(value: unknown): string | null {
+  return typeof value === "string" && CONTROL_VALUE.test(value) ? value : null;
+}
+
+function canonicalJson(value: unknown): string {
+  const budget = { nodes: 0, stringChars: 0, active: new WeakSet<object>() };
+  const visit = (item: unknown, depth: number, inArray: boolean): unknown => {
+    budget.nodes += 1;
+    if (budget.nodes > MAX_SURFACE_NODES) throw new SurfaceBoundError("surface-too-large");
+    if (depth > MAX_SURFACE_DEPTH) throw new SurfaceBoundError("surface-too-deep");
+    if (item === null || typeof item === "boolean") return item;
+    if (typeof item === "string") {
+      budget.stringChars += item.length;
+      if (budget.stringChars > MAX_SURFACE_STRING_CHARS) throw new SurfaceBoundError("surface-too-large");
+      return item;
+    }
+    if (typeof item === "number") return Number.isFinite(item) ? item : null;
+    if (["undefined", "function", "symbol"].includes(typeof item)) return inArray ? null : undefined;
+    if (typeof item === "bigint" || typeof item !== "object") throw new SurfaceBoundError("surface-not-json");
+    if (budget.active.has(item)) throw new SurfaceBoundError("surface-cyclic");
+    budget.active.add(item);
+    try {
+      if (Array.isArray(item)) {
+        if (item.length > MAX_CONTAINER_ITEMS) throw new SurfaceBoundError("surface-too-large");
+        return item.map((entry) => visit(entry, depth + 1, true));
+      }
+      const entries = Object.entries(item as JsonRecord)
+        .filter(([, entry]) => !["undefined", "function", "symbol"].includes(typeof entry));
+      if (entries.length > MAX_CONTAINER_ITEMS) throw new SurfaceBoundError("surface-too-large");
+      entries.sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0);
+      const output: JsonRecord = {};
+      for (const [key, entry] of entries) {
+        budget.stringChars += key.length;
+        if (budget.stringChars > MAX_SURFACE_STRING_CHARS) throw new SurfaceBoundError("surface-too-large");
+        output[key] = visit(entry, depth + 1, false);
+      }
+      return output;
+    } finally {
+      budget.active.delete(item);
+    }
+  };
+  return JSON.stringify(visit(value, 0, false));
+}
+
+function unavailable(modelId: string, reasonCode: BoundReason): ProviderWireFingerprint {
+  return { applicable: true, state: "unavailable", reasonCode, modelId, instructionsHash: null,
+    baseInstructionsHash: null, instructionNormalization: null, instructionChars: null,
+    orderedToolSurfaceHash: null, toolCount: null, deferredToolSurfaceHash: null, deferredToolCount: null,
+    deferredToolBatchCount: null, reasoningEffort: null, textVerbosity: null, toolChoiceKind: null,
+    toolChoiceHash: null, requestPrefixFingerprint: null };
+}
+
+function xmlEscape(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+function boundedHostPaths(value: unknown): string[] {
+  if (typeof value !== "string" || value.length === 0 || value.length > 32_768 || value.includes("\0")) return [];
+  if (/^[\\/]+$/.test(value) || /^[A-Za-z]:[\\/]?$/.test(value)) return [];
+  const native = value.replace(/[\\/]+$/, "");
+  const slash = native.replace(/\\/g, "/");
+  return [...new Set([native, slash].filter(Boolean))];
+}
+
+function normalizeSkillLocations(instructions: string, platformRoot: unknown): string {
+  const roots = boundedHostPaths(platformRoot);
+  if (roots.length === 0) return instructions;
+  const startTag = "<available_skills>";
+  const endTag = "</available_skills>";
+  let cursor = 0;
+  let output = "";
+  while (cursor < instructions.length) {
+    const start = instructions.indexOf(startTag, cursor);
+    if (start < 0) return output + instructions.slice(cursor);
+    const endStart = instructions.indexOf(endTag, start + startTag.length);
+    if (endStart < 0) return output + instructions.slice(cursor);
+    const end = endStart + endTag.length;
+    let section = instructions.slice(start, end);
+    for (const root of roots) {
+      const locationPrefix = `<location>${xmlEscape(root)}`;
+      section = section
+        .replaceAll(`${locationPrefix}/`, "<location>[PIAGENT_PLATFORM_ROOT]/")
+        .replaceAll(`${locationPrefix}\\`, "<location>[PIAGENT_PLATFORM_ROOT]/")
+        .replaceAll(`${locationPrefix}</location>`, "<location>[PIAGENT_PLATFORM_ROOT]</location>");
+    }
+    output += instructions.slice(cursor, start) + section;
+    cursor = end;
+  }
+  return output;
+}
+
+function normalizeHostOwnedRelocation(instructions: string, workingDirectory: unknown, platformRoot: unknown): {
+  value: string;
+  mode: "host-relocation-v1" | "none";
+} {
+  const cwdVariants = boundedHostPaths(workingDirectory);
+  let value = normalizeSkillLocations(instructions, platformRoot);
+  for (const cwd of cwdVariants) {
+    const cwdLine = `Current working directory: ${cwd}`;
+    if (value.endsWith(cwdLine)) {
+      value = `${value.slice(0, -cwdLine.length)}Current working directory: [PIAGENT_PROJECT_ROOT]`;
+    }
+    value = value
+      .replaceAll(`<project_instructions path="${cwd}">`, '<project_instructions path="[PIAGENT_PROJECT_ROOT]">')
+      .replaceAll(`<project_instructions path="${cwd}/`, '<project_instructions path="[PIAGENT_PROJECT_ROOT]/')
+      .replaceAll(`<project_instructions path="${cwd}\\`, '<project_instructions path="[PIAGENT_PROJECT_ROOT]/');
+  }
+  return value === instructions
+    ? { value, mode: "none" }
+    : { value, mode: "host-relocation-v1" };
+}
+
+export function buildOpenAiCodexWireFingerprint(input: {
+  payload: unknown;
+  provider: unknown;
+  modelId: unknown;
+  workingDirectory?: unknown;
+  platformRoot?: unknown;
+}): ProviderWireFingerprint {
+  const payload = record(input.payload);
+  const provider = typeof input.provider === "string" ? input.provider : "";
+  const modelId = typeof input.modelId === "string" && PUBLIC_ID.test(input.modelId) ? input.modelId : "";
+  if (provider !== "openai-codex" || !payload || !modelId || payload.model !== modelId) {
+    return { ...unavailable("", "surface-not-json"), applicable: false, state: "unavailable",
+      reasonCode: "not-applicable", modelId: null };
+  }
+  if (typeof payload.instructions !== "string") return unavailable(modelId, "instructions-unavailable");
+  if (payload.instructions.length > MAX_INSTRUCTIONS_CHARS) return unavailable(modelId, "instructions-too-large");
+  const tools = payload.tools === undefined ? [] : payload.tools;
+  if (!Array.isArray(tools)) return unavailable(modelId, "tools-invalid");
+  if (tools.length > MAX_TOOLS) return unavailable(modelId, "tools-too-large");
+  const requestInput = payload.input === undefined ? [] : payload.input;
+  if (!Array.isArray(requestInput)) return unavailable(modelId, "input-invalid");
+  if (requestInput.length > MAX_INPUT_ITEMS) return unavailable(modelId, "input-too-large");
+
+  const deferredBatches: Array<{ inputIndex: number; tools: unknown[] }> = [];
+  let deferredToolCount = 0;
+  for (let index = 0; index < requestInput.length; index += 1) {
+    const item = record(requestInput[index]);
+    if (item?.type !== "tool_search_output") continue;
+    if (!Array.isArray(item.tools)) return unavailable(modelId, "deferred-tools-invalid");
+    deferredToolCount += item.tools.length;
+    if (deferredToolCount > MAX_TOOLS) return unavailable(modelId, "deferred-tools-too-large");
+    deferredBatches.push({ inputIndex: index, tools: item.tools });
+  }
+
+  try {
+    const instructionsHash = hash(payload.instructions);
+    const normalizedInstructions = normalizeHostOwnedRelocation(payload.instructions, input.workingDirectory, input.platformRoot);
+    const baseInstructionsHash = hash(normalizedInstructions.value);
+    // Object keys are canonicalized because their order is semantic noise;
+    // arrays are preserved so changing provider-visible tool order is detected.
+    const orderedToolSurfaceHash = hash(canonicalJson(tools));
+    const deferredToolSurfaceHash = hash(canonicalJson(deferredBatches));
+    const toolChoice = payload.tool_choice ?? null;
+    const toolChoiceHash = hash(canonicalJson(toolChoice));
+    const reasoningEffort = control(record(payload.reasoning)?.effort);
+    const textVerbosity = control(record(payload.text)?.verbosity);
+    const toolChoiceKind = typeof toolChoice === "string" ? control(toolChoice) : record(toolChoice) ? "structured" : "none";
+    const requestPrefixFingerprint = hash(JSON.stringify({
+      schemaVersion: 1,
+      modelId,
+      instructionsHash,
+      baseInstructionsHash,
+      orderedToolSurfaceHash,
+      toolCount: tools.length,
+      deferredToolSurfaceHash,
+      deferredToolCount,
+      deferredToolBatchCount: deferredBatches.length,
+      reasoningEffort,
+      textVerbosity,
+      toolChoiceHash
+    }));
+    return { applicable: true, state: "known", reasonCode: null, modelId, instructionsHash,
+      baseInstructionsHash, instructionNormalization: normalizedInstructions.mode,
+      instructionChars: payload.instructions.length, orderedToolSurfaceHash, toolCount: tools.length,
+      deferredToolSurfaceHash, deferredToolCount, deferredToolBatchCount: deferredBatches.length,
+      reasoningEffort, textVerbosity, toolChoiceKind, toolChoiceHash, requestPrefixFingerprint };
+  } catch (error) {
+    return unavailable(modelId, error instanceof SurfaceBoundError ? error.reasonCode : "surface-not-json");
+  }
+}

package/packages/piagent-core/runtime/orchestration/role-policy.ts

@@ -87,7 +87,7 @@ export function defaultRolePolicy(role: HelperRole, scope: string[] = ["**"]): R
   const readOnly = role !== "worker";
   const policy: RolePolicy = {
     schemaVersion: 1, policyVersion: ROLE_POLICY_VERSION, role, authority: readOnly ? "read-only" : "single-writer",
-    enabledByDefault: readOnly, readScope: [...scope], writeScope: [], allowedTools: readOnly ? [...READ_TOOLS] : [...READ_TOOLS, "bash", "edit", "write", "contact_supervisor"],
+    enabledByDefault: readOnly, readScope: [...scope], writeScope: [], allowedTools: readOnly ? [...READ_TOOLS] : [...READ_TOOLS, "bash", "edit", "write", "apply_patch", "contact_supervisor"],
     modelSelectionSource: "runtime-catalog", effortSelectionSource: "runtime-snapshot", contextBudget: role === "oracle" ? 12000 : role === "reviewer" ? 9000 : 6000,
     ceilings: { timeSeconds: role === "oracle" ? 900 : 600, calls: role === "retriever" ? 20 : 40, retries: 0 },
     outputSchema: `${role}-result-v1`, stoppingRule: "Stop when the bounded objective is answered or evidence is insufficient; return uncertainty.",

package/packages/piagent-core/runtime/product/activity-inspector.ts

@@ -3,6 +3,8 @@ import {
   buildWebUiInspectionProjection,
   type WebUiInspectionProjection
 } from "../inspection/webui-snapshot.ts";
+import { recoveredToolCalls } from "../inspection/activity-recovery.ts";
+import { handledToolFailure } from "../inspection/tool-failure-classification.ts";
 
 export const ACTIVITY_INSPECTOR_VERSION = "activity-inspector-v2" as const;
 
@@ -18,6 +20,7 @@ export type ActivityInspectorEvent = {
   command?: string;
   decision?: string;
   reason?: string;
+  reasonCode?: string;
   warningKind?: string;
   isError?: boolean;
   exitCode?: number;
@@ -46,13 +49,15 @@ function isTestPath(file: string): boolean { return /(^|\/)(?:test|tests|spec|__
 function failedToolResult(event: ActivityInspectorEvent): boolean { return event.isError === true || (typeof event.exitCode === "number" && event.exitCode !== 0); }
 
 function commandProjection(events: ActivityInspectorEvent[]) {
+  const recoveries = recoveredToolCalls(events);
   const calls = events.filter((event) => event.event === "tool_call" && ["bash", "shell", "exec"].includes(String(event.toolName)));
   const results = new Map(events.filter((event) => event.event === "tool_result").map((event) => [event.toolCallId, event]));
   const decisions = new Map(events.filter((event) => event.event === "tool_decision").map((event) => [event.toolCallId, event]));
   const entries = calls.map((call) => {
     const decision = decisions.get(call.toolCallId), result = results.get(call.toolCallId);
     const blocked = decision?.decision === "blocked";
-    const failed = !blocked && Boolean(result && failedToolResult(result));
+    const recovered = Boolean(call.toolCallId && recoveries.has(call.toolCallId));
+    const failed = !blocked && !recovered && !handledToolFailure(result?.reasonCode) && Boolean(result && failedToolResult(result));
     return { toolCallId: call.toolCallId ?? "unknown", command: call.command ?? "[redacted or unavailable]",
       status: blocked ? "blocked" : !result ? "running" : failed ? "failed" : "passed",
       exitCode: result?.exitCode ?? null, exitCodeExact: result?.exitCodeExact === true,
@@ -121,7 +126,7 @@ export async function buildActivityInspector(input: {
       phase: snapshot.session.operation.hostPhase.state === "known" && snapshot.session.operation.hostPhase.value !== "idle" ? snapshot.session.operation.hostPhase.value : null,
       outcome: snapshot.task?.outcome ?? "idle", running: snapshot.activity.running.length, current: input.current ?? [] },
     criteria: snapshot.task?.criteria ?? [], sourceChanges: snapshot.sourceChanges, files,
-    tools: { calls: calls.length, results: results.length, failed: results.filter(failedToolResult).length,
+    tools: { calls: calls.length, results: results.length, failed: results.filter((event) => failedToolResult(event) && !handledToolFailure(event.reasonCode)).length,
       blocked: events.filter((event) => event.event === "tool_decision" && event.decision === "blocked").length, byName,
       perToolTokens: null, perToolTokensReason: "Pi reports model usage by response/turn; built-in tool calls do not carry attributable model-token totals." },
     commands, safety,

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

@@ -1,5 +1,6 @@
 import crypto from "node:crypto";
 
+import { durableContextEvidenceEntries } from "../../extensions/context-evidence.js";
 import type { TaskContract } from "../../extensions/guard-types.ts";
 import { readSolverShadowEvents } from "../solver/solver-shadow.ts";
 import { readTrajectoryStore } from "../trajectory/trajectory-store.ts";
@@ -52,8 +53,9 @@ export function buildTaskEfficiencyMetrics(
   const decision = solverEvent?.decision;
   const helperUsage = task.acceptanceReceipt?.helperUsage;
   const provenance = task.acceptanceReceipt?.provenance;
+  const contextEvidence = durableContextEvidenceEntries(task);
   const relevantEvent = trajectory.events.find((event) => event.cause === "context-observed");
-  const relevantFileMs = relevantEvent && task.contextManifest.length > 0 ? duration(task.createdAt, relevantEvent.observedAt) : null;
+  const relevantFileMs = relevantEvent && contextEvidence.length > 0 ? duration(task.createdAt, relevantEvent.observedAt) : null;
   const recommendedTools = decision?.toolGroups ?? [];
   const activeTools = [...new Set(input.activeToolGroups ?? [])].sort();
   const exactUsage = input.exactUsage && (input.exactUsage.tokens !== null || input.exactUsage.cost !== null)
@@ -83,7 +85,7 @@ export function buildTaskEfficiencyMetrics(
     },
     context: {
       requiredFiles: task.requiredContext.length,
-      manifestedFiles: task.contextManifest.length,
+      manifestedFiles: contextEvidence.length,
       memoryCitations: task.memoryCitations.length,
       recommendedBudget: decision?.context.budgetBand ?? "unknown",
       timeToRelevantFileMs: relevantFileMs,

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

@@ -1,6 +1,7 @@
 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";
 
 const MAX_EVIDENCE_BYTES = 256 * 1024;
@@ -71,7 +72,7 @@ export function evaluateExactFinalOutputContract(
 
   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);

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));
+}