@piagent/platform 1.6.1 → 1.8.0

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

@@ -6,7 +6,7 @@ import { redactSensitiveText } from "../../extensions/redaction-core.js";
 import { workingTreeSnapshot } from "../../extensions/task-state.js";
 import { workingTreeEvidenceDigest, workingTreeSnapshotUsesCurrentAlgorithm } from "../../extensions/working-tree-digest.js";
 import { inspectTaskContinuationBudget } from "../recovery/continuation-budget.ts";
-import { readHandoffProjection } from "../recovery/handoff-projection.ts";
+import { handoffIdentityMatchesTask, 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";
@@ -129,7 +129,7 @@ function reconciledToolResults(events: ActivityInspectorEvent[], evidence: Retur
     const raw = evidence.results.get(call.toolCallId);
     if (!raw) continue;
     const reasonCode = classifyToolFailure(raw.toolName || call.toolName, raw.isError, raw.content, evidence.inputs.get(call.toolCallId));
-    const effectiveError = raw.isError || Boolean(reasonCode && !handledToolFailure(reasonCode));
+    const effectiveError = raw.isError || Boolean(reasonCode && !handledToolFailure(reasonCode, raw.toolName || call.toolName));
     reconciled.push({ activityId: `canonical-result:${call.toolCallId}`, event: "tool_result",
       recordedAt: raw.recordedAt ?? call.recordedAt, sessionId: call.sessionId, taskRunId: call.taskRunId,
       toolCallId: call.toolCallId, toolName: raw.toolName || call.toolName, isError: effectiveError,
@@ -162,29 +162,64 @@ function sourceSummary(document: SourceChangeDocument | null, view: "task" | "wo
   };
 }
 
-function activityProjection(events: ActivityInspectorEvent[], current: CurrentActivity[]) {
+function sourceProjectionRevision(views: CriteriaLinkProjection["sourceViews"]): string {
+  const content = (["task", "workingTree", "staged"] as const).map((key) => {
+    const document = views[key];
+    if (!document) return null;
+    const { generatedAt: _generatedAt, identity: _identity, snapshotBinding: _snapshotBinding, ...stable } = document;
+    const bases = Array.isArray(stable.bases) ? stable.bases.map((value) => {
+      if (!value || typeof value !== "object") return value;
+      const { taskRevision: _taskRevision, ...sourceBasis } = value as Record<string, unknown>;
+      return sourceBasis;
+    }) : stable.bases;
+    return { ...stable, bases };
+  });
+  return token("source-projection-rev", content);
+}
+
+function activityProjection(events: ActivityInspectorEvent[], current: CurrentActivity[], generatedAt: string,
+  operationLiveness?: "idle" | "running" | "unknown") {
   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);
+  // Tool-call telemetry is deliberately written before execution. A missing
+  // result therefore cannot remain authoritative forever: compaction, abrupt
+  // host replacement, or an older runtime may have lost the matching result.
+  // A later host lifecycle boundary proves only that the call is no longer
+  // running, not that it passed or failed, so project it as terminal/unknown.
+  let lastLifecycleBoundary = -1;
+  for (let index = events.length - 1; index >= 0; index -= 1) {
+    if (!["turn_end", "agent_settled", "session_shutdown"].includes(String(events[index]?.event))) continue;
+    lastLifecycleBoundary = index;
+    break;
+  }
   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 handled = Boolean(result && handledToolFailure(result.reasonCode));
+    const handled = Boolean(result && handledToolFailure(result.reasonCode, result.toolName ?? call.toolName));
     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 lifecycleSettled = !result && !blocked && (operationLiveness === "idle"
+      || lastLifecycleBoundary > events.indexOf(call));
+    const state = blocked ? "blocked" : lifecycleSettled ? "unknown" : !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);
+    const boundaryAt = lastLifecycleBoundary > events.indexOf(call)
+      ? timestamp(events[lastLifecycleBoundary]?.recordedAt, timestamp(call.recordedAt, generatedAt))
+      : timestamp(events.at(-1)?.recordedAt, timestamp(call.recordedAt, generatedAt));
     return {
       activityRef: token("activity", [rawId, call.recordedAt]), kind: ["bash", "shell", "exec"].includes(toolName) ? "command" : "tool", state,
-      label: display(recovery ? `${toolName} recovered` : handled ? `${toolName} warning` : state === "running" ? `${toolName} running` : `${toolName} ${state}`, 500), preview: command,
+      label: display(recovery ? `${toolName} recovered` : handled ? `${toolName} warning`
+        : state === "unknown" ? `${toolName} ended · result unavailable`
+          : 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: 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
+        : result || blocked ? timestamp(result?.recordedAt ?? decision?.recordedAt, timestamp(call.recordedAt))
+          : lifecycleSettled ? boundaryAt : null
     };
   });
   const callIds = new Set(calls.map((call) => String(call.toolCallId ?? "")));
@@ -213,7 +248,7 @@ function capabilities(identity: WebUiIdentity, generatedAt: string, resyncRequir
     capabilities: {
       inspect: { status: "available", version: 1, reason: null, sourceViews: ["task", "working-tree", "staged"] },
       "control.chat": unavailableCapability("chat-control-not-enabled", "The same-session bridge exists, but transcript, queue, server control and browser UX are not enabled"),
-      "control.lifecycle": unavailableCapability("lifecycle-contract-incomplete", "Pi 0.84.1 lacks semantic Pause and an acknowledged phase-complete Stop contract"),
+      "control.lifecycle": unavailableCapability("lifecycle-contract-incomplete", "Pi host lacks semantic Pause and an acknowledged phase-complete Stop contract"),
       "control.resumeAndContinue": unavailableCapability("compound-control-unavailable", "Resume is unavailable until a durable acknowledged Pause contract exists"),
       "control.sessionOptions": unavailableCapability("effect-scope-not-productionized", "Model and thinking APIs exist but lifecycle and persistence scope enforcement is not enabled"),
       attachments: unavailableCapability("attachments-not-implemented", "Attachments are not implemented"),
@@ -299,7 +334,7 @@ function handoff(cwd: string, task: TaskContract | undefined, currentDigest: str
   if (!task) return null;
   let value;
   try { value = readHandoffProjection(cwd, task.taskRunId); } catch { return null; }
-  if (!value) return null;
+  if (!value || !handoffIdentityMatchesTask(value.identity, task)) return null;
   const stale = Boolean(currentDigest && value.tree.currentDigest && currentDigest !== value.tree.currentDigest);
   return { handoffRef: token("handoff", task.taskRunId), state: stale ? "stale" : "ready", summary: display(value.goal.summary, 500),
     blocker: value.failure.warnings[0] ? display(value.failure.warnings[0], 500) : null,
@@ -324,6 +359,7 @@ export async function buildWebUiInspectionProjection(input: {
   eventReplay?: { eventRetentionCount: number; eventRetentionSeconds: number };
   model?: WebUiRuntimeModel;
   thinkingLevel?: unknown;
+  operationLiveness?: "idle" | "running" | "unknown";
 }): Promise<WebUiInspectionProjection> {
   const generatedAt = timestamp(input.generatedAt);
   const identity: WebUiIdentity = { projectRef: webUiProjectRef(input.cwd), runtimeInstanceId: input.runtimeInstanceId ?? WEBUI_RUNTIME_INSTANCE_REF,
@@ -339,14 +375,18 @@ export async function buildWebUiInspectionProjection(input: {
   const events = reconciledToolResults(scopedEvents(input.events ?? [], input.sessionId, input.task), canonicalEvidence);
   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") };
+  const sourceChanges = { projectionRevision: sourceProjectionRevision(linked.sourceViews),
+    task: sourceSummary(linked.sourceViews.task, "task"), workingTree: sourceSummary(linked.sourceViews.workingTree, "working-tree"),
+    staged: sourceSummary(linked.sourceViews.staged, "staged") };
   const currentDigest = workingTreeSnapshotUsesCurrentAlgorithm(currentSnapshot) ? workingTreeEvidenceDigest(currentSnapshot) : null;
-  const current = (input.current ?? []).filter((item) => (item.status ?? "running") !== "running" || !canonicalEvidence.results.has(item.toolCallId));
+  const current = (input.current ?? []).filter((item) => ((item.status ?? "running") !== "running" || input.operationLiveness !== "idle")
+    && ((item.status ?? "running") !== "running" || !canonicalEvidence.results.has(item.toolCallId)));
   const runningCurrent = current.find((item) => (item.status ?? "running") === "running");
   const controlState = input.task?.trace.outcome === "pending" ? "active" as const : "terminal" as const;
   const context = contextProjection(input.contextUsage, generatedAt), usageFacts = usage(input.sessionEntries ?? []);
   const eventCursor = input.eventCursor ?? token("event-cursor", events.map((event) => event.activityId ?? [event.event, event.toolCallId, event.recordedAt]));
-  const runtimeRevision = token("runtime-rev", [taskRevision, sourceChanges.workingTree.revision, sourceChanges.staged.revision, eventCursor, current]);
+  const runtimeRevision = token("runtime-rev", [taskRevision, sourceChanges.workingTree.revision, sourceChanges.staged.revision,
+    eventCursor, current, input.operationLiveness ?? null]);
   const approvals = { state: "unknown", pending: [], recent: [], health: { state: "unavailable", reasonCode: "approval-projection-unavailable", message: "Current host approval state is not exposed to the read-only projector" } };
   const task = input.task ? taskProjection(input.task, linked.criteria, controlState) : null;
   const issues = [
@@ -364,8 +404,8 @@ export async function buildWebUiInspectionProjection(input: {
     capabilities: capabilities(identity, generatedAt, input.resyncRequired === true, input.eventReplay),
     session: {
       connectionState: input.resyncRequired ? "resync-required" : "connected", connectionReason: input.resyncRequired ? "event-replay-gap" : null, displayName: input.task?.sessionName ?? null,
-      operation: runningCurrent
-        ? { liveness: "running", operationRef: null, hostPhase: { state: "known", value: "tool", evidence: "derived", reasonCode: null }, startedAt: timestamp(runningCurrent.startedAt, generatedAt), settledAt: null, reasonCode: null }
+      operation: input.operationLiveness === "running" || runningCurrent
+        ? { liveness: "running", operationRef: null, hostPhase: { state: "known", value: runningCurrent ? "tool" : "other", evidence: "derived", reasonCode: null }, startedAt: runningCurrent ? timestamp(runningCurrent.startedAt, generatedAt) : null, settledAt: null, reasonCode: null }
         : { liveness: "idle", operationRef: null, hostPhase: { state: "known", value: "idle", evidence: "derived", reasonCode: null }, startedAt: null, settledAt: null, reasonCode: null },
       controlState: input.task ? controlState : "active", taskOutcome: input.task?.trace.outcome ?? null, approvalState: approvals.state,
       verificationState: linked.verification.state, permissionProfile: { state: "unavailable", value: null, evidence: null, reasonCode: "permission-profile-not-projected" },
@@ -373,12 +413,18 @@ export async function buildWebUiInspectionProjection(input: {
       thinking: thinkingFact(input.thinkingLevel),
       queue: { state: "unavailable", hasPending: null, heldCount: null, revision: null, reasonCode: "host-queue-api-unavailable" }, context
     },
-    task, sourceChanges, activity: activityProjection(events, current), approvals, verification: linked.verification,
+    task, sourceChanges, activity: activityProjection(events, current, generatedAt, input.operationLiveness), approvals, verification: linked.verification,
     usage: { context, latestTurn: usageCounter(usageFacts.latest, "no-assistant-turn"), sessionTotal: usageCounter(usageFacts.observed ? usageFacts.totals : null, "host-total-usage-unavailable"),
       taskTotal: usageCounter(null, input.task ? "task-usage-boundary-unavailable" : "no-active-task"), capturedAt: generatedAt,
       health: { state: "degraded", reasonCode: "partial-usage-only", message: "Task-attributed usage is not available" } },
     continuation: continuation(input.cwd, input.task), handoff: handoff(input.cwd, input.task, currentDigest),
     health: { state: issues.length ? "degraded" : "ok", issues, resyncRequired: input.resyncRequired === true, generatedFromRevision: runtimeRevision }
   };
+  const snapshotBinding = { sourceProjectionRevision: snapshot.sourceChanges.projectionRevision,
+    taskViewRevision: snapshot.sourceChanges.task.revision, workspaceRevision: snapshot.sourceChanges.workingTree.revision,
+    indexRevision: snapshot.sourceChanges.staged.revision };
+  for (const document of Object.values(linked.sourceViews)) {
+    if (document) (document as SourceChangeDocument & { snapshotBinding: typeof snapshotBinding }).snapshotBinding = snapshotBinding;
+  }
   return { snapshot, sourceViews: linked.sourceViews, relations: linked.relations, verifierAttempts: linked.verifierAttempts, scopedEvents: events };
 }

package/packages/piagent-core/runtime/inspection/workspace-file-reader.ts

@@ -1,132 +1,2 @@
-import { createHash } from "node:crypto";
-import fs from "node:fs";
-import path from "node:path";
-
-export class WorkspaceReadError extends Error {
-  readonly code: "outside-root" | "symlink-ancestor" | "not-file" | "oversized" | "changed-during-read";
-
-  constructor(code: WorkspaceReadError["code"], message: string) {
-    super(message);
-    this.name = "WorkspaceReadError";
-    this.code = code;
-  }
-}
-
-type SafeCandidate = { root: string; absolute: string; parent: string };
-
-function inside(root: string, candidate: string): boolean {
-  const relative = path.relative(root, candidate);
-  return relative === "" || (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
-}
-
-function safeCandidate(repoRoot: string, repoPath: string): SafeCandidate {
-  const root = fs.realpathSync.native(repoRoot);
-  const segments = repoPath.split("/");
-  if (!repoPath || path.posix.isAbsolute(repoPath) || segments.includes("..") || segments.includes("")) {
-    throw new WorkspaceReadError("outside-root", "Workspace path is not a safe repository-relative path");
-  }
-  let parent = root;
-  for (const segment of segments.slice(0, -1)) {
-    parent = path.join(parent, segment);
-    const stat = fs.lstatSync(parent);
-    if (stat.isSymbolicLink()) throw new WorkspaceReadError("symlink-ancestor", "Workspace path traverses a symbolic link");
-    if (!stat.isDirectory()) throw new WorkspaceReadError("not-file", "Workspace path has a non-directory ancestor");
-  }
-  const canonicalParent = fs.realpathSync.native(parent);
-  if (!inside(root, canonicalParent)) throw new WorkspaceReadError("outside-root", "Workspace path resolves outside its repository root");
-  const absolute = path.join(canonicalParent, segments.at(-1) as string);
-  if (!inside(root, absolute)) throw new WorkspaceReadError("outside-root", "Workspace path escapes its repository root");
-  return { root, absolute, parent: canonicalParent };
-}
-
-function sameFile(left: fs.Stats, right: fs.Stats): boolean {
-  return left.dev === right.dev && left.ino === right.ino && left.mode === right.mode;
-}
-
-function openRegularFile(repoRoot: string, repoPath: string): { descriptor: number; stat: fs.Stats; candidate: SafeCandidate } {
-  const candidate = safeCandidate(repoRoot, repoPath);
-  const descriptor = fs.openSync(candidate.absolute, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
-  try {
-    const stat = fs.fstatSync(descriptor);
-    if (!stat.isFile()) throw new WorkspaceReadError("not-file", "Workspace entry is not a regular file");
-    const canonical = fs.realpathSync.native(candidate.absolute);
-    const current = fs.lstatSync(candidate.absolute);
-    if (!inside(candidate.root, canonical) || !sameFile(stat, current)) {
-      throw new WorkspaceReadError("changed-during-read", "Workspace path changed while it was opened");
-    }
-    return { descriptor, stat, candidate };
-  } catch (error) {
-    fs.closeSync(descriptor);
-    throw error;
-  }
-}
-
-function verifyAfterRead(descriptor: number, before: fs.Stats, candidate: SafeCandidate): void {
-  const after = fs.fstatSync(descriptor);
-  const current = fs.lstatSync(candidate.absolute);
-  const canonical = fs.realpathSync.native(candidate.absolute);
-  if (
-    !sameFile(before, after)
-    || !sameFile(after, current)
-    || before.size !== after.size
-    || before.mtimeMs !== after.mtimeMs
-    || before.ctimeMs !== after.ctimeMs
-    || !inside(candidate.root, canonical)
-  ) {
-    throw new WorkspaceReadError("changed-during-read", "Workspace file changed during inspection");
-  }
-}
-
-export function inspectWorkspaceEntry(repoRoot: string, repoPath: string): fs.Stats {
-  const candidate = safeCandidate(repoRoot, repoPath);
-  return fs.lstatSync(candidate.absolute);
-}
-
-export function readWorkspaceLink(repoRoot: string, repoPath: string): string {
-  const candidate = safeCandidate(repoRoot, repoPath);
-  const before = fs.lstatSync(candidate.absolute);
-  if (!before.isSymbolicLink()) throw new WorkspaceReadError("not-file", "Workspace entry is not a symbolic link");
-  const target = fs.readlinkSync(candidate.absolute);
-  const after = fs.lstatSync(candidate.absolute);
-  if (!sameFile(before, after) || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) {
-    throw new WorkspaceReadError("changed-during-read", "Workspace link changed during inspection");
-  }
-  return target;
-}
-
-export function readWorkspaceFile(repoRoot: string, repoPath: string, maxBytes: number): Buffer {
-  const opened = openRegularFile(repoRoot, repoPath);
-  try {
-    if (opened.stat.size > maxBytes) throw new WorkspaceReadError("oversized", "Workspace file exceeds its read cap");
-    const content = Buffer.allocUnsafe(opened.stat.size);
-    let position = 0;
-    while (position < content.length) {
-      const count = fs.readSync(opened.descriptor, content, position, content.length - position, position);
-      if (count <= 0) throw new WorkspaceReadError("changed-during-read", "Workspace file ended during inspection");
-      position += count;
-    }
-    verifyAfterRead(opened.descriptor, opened.stat, opened.candidate);
-    return content;
-  } finally {
-    fs.closeSync(opened.descriptor);
-  }
-}
-
-export function hashWorkspaceFile(repoRoot: string, repoPath: string): string {
-  const opened = openRegularFile(repoRoot, repoPath);
-  try {
-    const state = createHash("sha256");
-    const buffer = Buffer.allocUnsafe(256 * 1024);
-    let position = 0;
-    while (position < opened.stat.size) {
-      const count = fs.readSync(opened.descriptor, buffer, 0, Math.min(buffer.length, opened.stat.size - position), position);
-      if (count <= 0) throw new WorkspaceReadError("changed-during-read", "Workspace file ended during hashing");
-      state.update(buffer.subarray(0, count));
-      position += count;
-    }
-    verifyAfterRead(opened.descriptor, opened.stat, opened.candidate);
-    return state.digest("hex");
-  } finally {
-    fs.closeSync(opened.descriptor);
-  }
-}
+// Compatibility entrypoint; core and runtime share the same bounded file reader.
+export * from "../../security/workspace-file-reader.ts";

package/packages/piagent-core/runtime/model/model-route-policy.ts

@@ -4,8 +4,11 @@ import {
   authenticatedCatalogDigest,
   CAPABILITY_BANDS,
   createModelRouteDecision,
+  LEGACY_OPENAI_CODEX_MODEL_ROUTE_MAPPING_VERSION,
+  OPENAI_CODEX_MODEL_ROUTE_MAPPING_VERSION,
   type CapabilityBand,
   type ModelRouteDecision,
+  type ModelRouteMappingVersion,
   type ModelSelectionSource,
   type ParentRoutingMode,
   type RoutingObjective
@@ -22,33 +25,47 @@ export type ModelRoutePolicyInput = {
   current: { provider: string | null; modelId: string | null; effort: string | null };
   freshTaskBoundary: boolean;
   hostBoundary: ModelRouteHostBoundary;
+  mappingVersion?: ModelRouteMappingVersion;
 };
 
 type Candidate = { provider: "openai-codex"; modelId: string; effort: string };
 
-const BAND_CANDIDATES: Record<CapabilityBand, Candidate[]> = {
+const LEGACY_BAND_CANDIDATES: Record<CapabilityBand, Candidate[]> = {
   low: [{ provider: "openai-codex", modelId: "gpt-5.6-luna", effort: "medium" }],
   medium: [{ provider: "openai-codex", modelId: "gpt-5.6-terra", effort: "medium" }],
   high: [{ provider: "openai-codex", modelId: "gpt-5.6-sol", effort: "high" }],
   ultra: [{ provider: "openai-codex", modelId: "gpt-5.6-sol", effort: "xhigh" }]
 };
+const BAND_CANDIDATES: Record<CapabilityBand, Candidate[]> = {
+  low: [{ provider: "openai-codex", modelId: "gpt-6-luna", effort: "medium" }, ...LEGACY_BAND_CANDIDATES.low],
+  medium: [{ provider: "openai-codex", modelId: "gpt-6-sol", effort: "medium" }, ...LEGACY_BAND_CANDIDATES.medium],
+  high: [{ provider: "openai-codex", modelId: "gpt-6-sol", effort: "high" }, ...LEGACY_BAND_CANDIDATES.high],
+  ultra: [{ provider: "openai-codex", modelId: "gpt-6-astra", effort: "xhigh" }, ...LEGACY_BAND_CANDIDATES.ultra]
+};
 const BAND_INDEX = new Map(CAPABILITY_BANDS.map((band, index) => [band, index]));
 
-function exactCandidate(catalog: AuthenticatedModelCatalog, band: CapabilityBand): { model: AuthenticatedModelCatalogEntry; effort: string } | undefined {
-  for (const candidate of BAND_CANDIDATES[band]) {
+function exactCandidate(catalog: AuthenticatedModelCatalog, band: CapabilityBand, mappingVersion: ModelRouteMappingVersion): { model: AuthenticatedModelCatalogEntry; effort: string; legacyFallback: boolean } | undefined {
+  const candidates = mappingVersion === LEGACY_OPENAI_CODEX_MODEL_ROUTE_MAPPING_VERSION ? LEGACY_BAND_CANDIDATES[band] : BAND_CANDIDATES[band];
+  for (const [index, candidate] of candidates.entries()) {
     const model = catalog.models.find((entry) => entry.provider === candidate.provider
       && entry.modelId === candidate.modelId
       && (entry.supportedThinkingLevels === null || entry.supportedThinkingLevels.includes(candidate.effort)));
-    if (model) return { model, effort: candidate.effort };
+    if (model) return { model, effort: candidate.effort, legacyFallback: mappingVersion === OPENAI_CODEX_MODEL_ROUTE_MAPPING_VERSION && index > 0 };
   }
   return undefined;
 }
 
-function currentBand(modelId: string | null): CapabilityBand | undefined {
-  return modelId === "gpt-5.6-luna" ? "low"
-    : modelId === "gpt-5.6-terra" ? "medium"
-      : modelId === "gpt-5.6-sol" ? "high"
-        : undefined;
+function currentBand(modelId: string | null, effort: string | null): CapabilityBand | undefined {
+  if (modelId === "gpt-6-luna" || modelId === "gpt-5.6-luna") return "low";
+  if (modelId === "gpt-6-astra") return "ultra";
+  if (modelId === "gpt-6-sol") {
+    if (effort === "medium") return "medium";
+    if (effort === "xhigh" || effort === "max") return "ultra";
+    return "high";
+  }
+  if (modelId === "gpt-5.6-terra") return "medium";
+  if (modelId === "gpt-5.6-sol") return "high";
+  return undefined;
 }
 
 function maxBand(left: CapabilityBand, right: CapabilityBand): CapabilityBand {
@@ -102,6 +119,7 @@ function downgradeSteps(current: CapabilityBand | undefined, target: CapabilityB
 }
 
 export function routeParentModel(input: ModelRoutePolicyInput): ModelRouteDecision {
+  const mappingVersion = input.mappingVersion ?? OPENAI_CODEX_MODEL_ROUTE_MAPPING_VERSION;
   const floor = safetyFloor(input.features);
   const desired = objectiveBand(floor.band, input.objective);
   const catalogDigest = authenticatedCatalogDigest(input.catalog);
@@ -114,7 +132,8 @@ export function routeParentModel(input: ModelRoutePolicyInput): ModelRouteDecisi
     currentModelId: input.current.modelId,
     currentEffort: input.current.effort,
     selectionSource: input.selectionSource,
-    catalogDigest
+    catalogDigest,
+    mappingVersion
   } as const;
   if (input.mode === "off") return createModelRouteDecision({
     ...common, capabilityBand: "abstain", fallbackBand: desired, provider: input.current.provider,
@@ -136,14 +155,15 @@ export function routeParentModel(input: ModelRoutePolicyInput): ModelRouteDecisi
     confidence: "low", disposition: "unavailable", reasonCodes: ["authenticated-catalog-unavailable", ...floor.reasons],
     downgradeSteps: 0, enforced: false
   });
-  const candidate = exactCandidate(input.catalog, desired);
+  const candidate = exactCandidate(input.catalog, desired, mappingVersion);
   if (!candidate) return createModelRouteDecision({
     ...common, capabilityBand: "abstain", fallbackBand: desired, provider: null, modelId: null, effort: null,
     confidence: "low", disposition: "unavailable", reasonCodes: ["preferred-model-or-effort-unavailable", "no-silent-substitution", ...floor.reasons],
     downgradeSteps: 0, enforced: false
   });
-  const reasons = [...floor.reasons, `objective-${input.objective}`, `candidate-${desired}`, "runtime-catalog-match"];
-  const steps = downgradeSteps(currentBand(input.current.modelId), desired);
+  const reasons = [...floor.reasons, `objective-${input.objective}`, `candidate-${desired}`, "runtime-catalog-match",
+    ...(candidate.legacyFallback ? ["legacy-model-fallback"] : [])];
+  const steps = downgradeSteps(currentBand(input.current.modelId, input.current.effort), desired);
   if (input.mode === "shadow") return createModelRouteDecision({
     ...common, capabilityBand: desired, fallbackBand: null, provider: candidate.model.provider, modelId: candidate.model.modelId,
     effort: candidate.effort, confidence: floor.band === "low" || floor.band === "ultra" ? "high" : "medium",

package/packages/piagent-core/runtime/model/model-route-types.ts

@@ -4,7 +4,9 @@ import type { AuthenticatedModelCatalog } from "./authenticated-catalog.ts";
 
 export const MODEL_ROUTE_DECISION_SCHEMA_VERSION = 1 as const;
 export const MODEL_ROUTE_POLICY_VERSION = "model-route-v1" as const;
-export const OPENAI_CODEX_MODEL_ROUTE_MAPPING_VERSION = "openai-codex-model-route-map-v1" as const;
+export const LEGACY_OPENAI_CODEX_MODEL_ROUTE_MAPPING_VERSION = "openai-codex-model-route-map-v1" as const;
+export const OPENAI_CODEX_MODEL_ROUTE_MAPPING_VERSION = "openai-codex-model-route-map-v2" as const;
+export type ModelRouteMappingVersion = typeof LEGACY_OPENAI_CODEX_MODEL_ROUTE_MAPPING_VERSION | typeof OPENAI_CODEX_MODEL_ROUTE_MAPPING_VERSION;
 
 export const PARENT_ROUTING_MODES = Object.freeze(["off", "shadow", "recommend", "auto"] as const);
 export const ROUTING_OBJECTIVES = Object.freeze(["intelligence", "balance", "cost"] as const);
@@ -26,7 +28,7 @@ export type ModelRouteDisposition = "preserved" | "shadowed" | "recommended" | "
 export type ModelRouteDecision = {
   schemaVersion: typeof MODEL_ROUTE_DECISION_SCHEMA_VERSION;
   policyVersion: typeof MODEL_ROUTE_POLICY_VERSION;
-  mappingVersion: typeof OPENAI_CODEX_MODEL_ROUTE_MAPPING_VERSION;
+  mappingVersion: ModelRouteMappingVersion;
   featureHash: string;
   mode: ParentRoutingMode;
   objective: RoutingObjective;
@@ -88,13 +90,14 @@ export function authenticatedCatalogDigest(catalog: AuthenticatedModelCatalog):
 }
 
 export function createModelRouteDecision(
-  input: Omit<ModelRouteDecision, "schemaVersion" | "policyVersion" | "mappingVersion" | "decisionDigest">
+  input: Omit<ModelRouteDecision, "schemaVersion" | "policyVersion" | "mappingVersion" | "decisionDigest"> & { mappingVersion?: ModelRouteMappingVersion }
 ): ModelRouteDecision {
+  const { mappingVersion = OPENAI_CODEX_MODEL_ROUTE_MAPPING_VERSION, ...decisionInput } = input;
   const payload = {
     schemaVersion: MODEL_ROUTE_DECISION_SCHEMA_VERSION,
     policyVersion: MODEL_ROUTE_POLICY_VERSION,
-    mappingVersion: OPENAI_CODEX_MODEL_ROUTE_MAPPING_VERSION,
-    ...structuredClone(input)
+    mappingVersion,
+    ...structuredClone(decisionInput)
   } satisfies Omit<ModelRouteDecision, "decisionDigest">;
   return validateModelRouteDecision({ ...payload, decisionDigest: digestPayload(payload) });
 }
@@ -108,7 +111,8 @@ export function modelRouteDecisionValidationErrors(input: unknown): string[] {
   ];
   if (value.schemaVersion !== MODEL_ROUTE_DECISION_SCHEMA_VERSION
     || value.policyVersion !== MODEL_ROUTE_POLICY_VERSION
-    || value.mappingVersion !== OPENAI_CODEX_MODEL_ROUTE_MAPPING_VERSION) errors.push("model route schema/policy/mapping version is invalid");
+    || (value.mappingVersion !== LEGACY_OPENAI_CODEX_MODEL_ROUTE_MAPPING_VERSION
+      && value.mappingVersion !== OPENAI_CODEX_MODEL_ROUTE_MAPPING_VERSION)) errors.push("model route schema/policy/mapping version is invalid");
   if (typeof value.featureHash !== "string" || !HASH.test(value.featureHash)) errors.push("featureHash must be sha256 hex");
   if (!PARENT_ROUTING_MODES.includes(value.mode as ParentRoutingMode)) errors.push("mode is invalid");
   if (!ROUTING_OBJECTIVES.includes(value.objective as RoutingObjective)) errors.push("objective is invalid");

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

@@ -236,3 +236,23 @@ export function buildOpenAiCodexWireFingerprint(input: {
     return unavailable(modelId, error instanceof SurfaceBoundError ? error.reasonCode : "surface-not-json");
   }
 }
+
+// Measurement remains outside the signed fingerprint contract. A new telemetry
+// field must not silently change an existing signed-receipt schema.
+export function measureProviderPayload(payload: unknown) {
+  if (!record(payload)) return null;
+  try {
+    // Validate the entire payload within the existing bounds before measuring.
+    // This is the JSON at this hook, not HTTP bytes or proof of a cache hit.
+    canonicalJson(payload);
+    const serialized = JSON.stringify(payload);
+    const measured = JSON.parse(serialized);
+    const bytes = (value: unknown) => Buffer.byteLength(JSON.stringify(value) ?? "", "utf8");
+    const instructionsBytes = bytes(measured.instructions);
+    const toolsBytes = bytes(measured.tools);
+    const inputBytes = bytes(measured.input);
+    const totalBytes = Buffer.byteLength(serialized, "utf8");
+    return { basis: "hook-json-utf8" as const, instructionsBytes, toolsBytes, inputBytes,
+      remainingBytes: totalBytes - instructionsBytes - toolsBytes - inputBytes, totalBytes, cacheHit: null };
+  } catch { return null; }
+}