@piagent/platform 1.7.1 → 1.9.0

package/packages/piagent-core/runtime/hooks/input-hook.ts

@@ -5,34 +5,12 @@ import { matchesProtectedPath } from "../../extensions/policy-core.js";
 import type { TaskContract } from "../../extensions/guard-types.js";
 import { attachLocalImagesFromText, extractLocalImagePathCandidates } from "../input/chat-images.ts";
 import type { ChatImageAccessPolicy } from "../input/chat-images.ts";
-import { LONG_INPUT_CHARS } from "../runtime-limits.ts";
 import type { AuthorityResumeDecision } from "../policy/authority-resume-policy.ts";
-import { buildHandoffProjection, writeHandoffProjection } from "../recovery/handoff-projection.ts";
-import {
-  isUncertainSendContinuation,
-  terminalUncertainSendReceipt
-} from "../session/uncertain-send-continuation.ts";
-import { buildContextPreflight, buildUsageSnapshot } from "../session/usage.ts";
 import { registerAdaptiveContextGovernor } from "../session/adaptive-context-governor.ts";
-import { activeTaskToolGroups, toolGroupsForPrompt, PIAGENT_TOOL_NAMES, PIAGENT_TOOL_ORDER, PIAGENT_TOOL_GROUPS } from "../tools/tool-groups.ts";
+import { toolGroupsForPrompt, PIAGENT_TOOL_NAMES, PIAGENT_TOOL_ORDER, PIAGENT_TOOL_GROUPS } from "../tools/tool-groups.ts";
 import type { PiagentToolGroup } from "../tools/tool-groups.ts";
 import type { RuntimeSessionState } from "../session/runtime-state.ts";
 import { observeHostWireInput } from "../session/runtime-state.ts";
-import {
-  buildFreshCommand,
-  agentStartTaskRequest,
-  chooseFreshWorkflow,
-  extractTaskRequest,
-  isFreshOrUtilityInput,
-  isPiagentWorkflowInput,
-  looksLikeGovernedBoilerplate,
-  trimTaskForInline
-} from "../workflows/input-routing.ts";
-import {
-  automaticTaskIntakeMode,
-  isLightweightNonAuthorizingChangeContinuation,
-  manualTaskIntakeEligible
-} from "../workflows/task-intake.ts";
 
 type InputHookDependencies = {
   state: RuntimeSessionState;
@@ -54,191 +32,52 @@ export function projectPiagentWireInput(input: {
   const blocked = (reason: string) => ({ disposition: "blocked", reason });
   if (input.activeTask === undefined || !Array.isArray(input.readProtectedPaths)
     || typeof input.replacementIntake !== "boolean" || typeof input.dynamicToolsEnabled !== "boolean") return blocked("input-state-unfrozen");
-  const text = input.text.trim();
+  const text = input.text;
   if (input.hasImages !== false || extractLocalImagePathCandidates(text, "/").length > 0) return blocked("input-images-unprojected");
-  if (!text || isFreshOrUtilityInput(text) || /^\/piagent-workflow\b/i.test(text)) return blocked("input-transform-unprojected");
+  if (!text.trim()) return blocked("input-empty");
   if (!["rpc", "interactive", "extension"].includes(input.source)) return blocked("input-source-unfrozen");
-  if (input.source !== "extension" && (looksLikeGovernedBoilerplate(text) || isPiagentWorkflowInput(text)
-    || text.length >= LONG_INPUT_CHARS)) return blocked("input-preflight-unfrozen");
-  const signal = classifyContextTask(text), activeTask = input.activeTask?.trace.outcome === "pending" ? input.activeTask : undefined;
-  const onlyProtected = signal.paths.length > 0 && signal.paths.every((p) => matchesProtectedPath(p, input.readProtectedPaths));
-  const runtimeMode = !activeTask ? automaticTaskIntakeMode(text, input.readProtectedPaths) : undefined;
-  const manual = !activeTask && !runtimeMode && manualTaskIntakeEligible(text, input.readProtectedPaths);
-  const groups = onlyProtected ? [] : toolGroupsForPrompt(text).filter((group) => !runtimeMode || group !== "intake" && group !== "task");
-  if (manual && !groups.includes("intake")) groups.push("intake");
-  const selectedGroups = activeTask ? [...groups.filter((group) => input.replacementIntake || group !== "intake"),
-    ...(input.replacementIntake ? ["intake" as const] : activeTaskToolGroups(activeTask))] : groups;
+  const signal = classifyContextTask(text);
+  const protectedOnly = signal.paths.length > 0 && signal.paths.every((p) => matchesProtectedPath(p, input.readProtectedPaths));
+  const groups = protectedOnly ? [] : toolGroupsForPrompt(text).filter((g) => !["intake", "task", "recovery"].includes(g));
   const builtins = input.currentTools.filter((name) => !PIAGENT_TOOL_NAMES.has(name));
   if (builtins.includes("apply_patch")) {
-    const firstWriter = builtins.findIndex((name) => name === "edit" || name === "write");
-    if (firstWriter >= 0) { builtins.splice(builtins.indexOf("apply_patch"), 1); builtins.splice(builtins.findIndex((name) => name === "edit" || name === "write"), 0, "apply_patch"); }
+    const writer = builtins.findIndex((n) => n === "edit" || n === "write");
+    if (writer >= 0) { builtins.splice(builtins.indexOf("apply_patch"), 1); builtins.splice(builtins.findIndex((n) => n === "edit" || n === "write"), 0, "apply_patch"); }
   }
   const selectedTools = input.dynamicToolsEnabled ? [...builtins, ...PIAGENT_TOOL_ORDER.filter((name) =>
-    selectedGroups.some((group) => PIAGENT_TOOL_GROUPS[group].includes(name as never)))] : [...input.currentTools];
+    groups.some((group) => PIAGENT_TOOL_GROUPS[group].includes(name as never)))] : [...input.currentTools];
   if (selectedTools.some((name) => !input.availableToolNames.includes(name))) return blocked("tool-definition-missing");
-  const query = agentStartTaskRequest(input.expandedPrompt ?? text), querySignal = classifyContextTask(query);
-  const protectedQuery = querySignal.paths.length > 0 && querySignal.paths.every((p) => matchesProtectedPath(p, input.readProtectedPaths));
-  const agentStartRuntimeMode = !activeTask ? automaticTaskIntakeMode(query, input.readProtectedPaths) : undefined;
-  if (runtimeMode || agentStartRuntimeMode || input.replacementIntake) return blocked("automatic-task-state-unprojected");
-  if (activeTask && !input.phase) return blocked("current-task-phase-unfrozen");
-  return { disposition: "known", reason: null, groups: selectedGroups, selectedTools,
-    compactMode: protectedQuery ? "protected" : activeTask?.intakeMode === "runtime" ? "automatic" : null,
-    taskPresence: activeTask ? "current" : "none", phase: activeTask ? input.phase : null,
+  return { disposition: "known", reason: null, groups, selectedTools,
+    compactMode: protectedOnly ? "protected" : null, taskPresence: "none", phase: null,
     inputHash: signal.promptHash, inputText: text };
+
 }
 
 export function registerInputHook(pi: ExtensionAPI, dependencies: InputHookDependencies): void {
-  registerAdaptiveContextGovernor(pi, {
-    activeTask: dependencies.activeTask,
-    telemetry: dependencies.telemetry
-  });
-
+  registerAdaptiveContextGovernor(pi, { activeTask: () => undefined, telemetry: dependencies.telemetry });
   pi.on("input", async (event, ctx) => {
-    const text = event.text.trim();
-    if (!text || isFreshOrUtilityInput(text)) return { action: "continue" };
-    if (/^\/piagent-workflow\b/i.test(text)) {
-      return { action: "transform", text: text.replace(/^\/piagent-workflow\b/i, "/workflow") };
-    }
-
-    const taskSignal = classifyContextTask(text);
-    const sessionTask = dependencies.activeTask(ctx);
-    const uncertainSendContinuation = (!Array.isArray(event.images) || event.images.length === 0)
-      && isUncertainSendContinuation(text);
-    const terminalReceipt = uncertainSendContinuation
-      ? terminalUncertainSendReceipt(ctx.cwd, sessionTask)
-      : undefined;
-    if (terminalReceipt && event.source !== "extension") {
-      dependencies.telemetry(ctx, {
-        event: "uncertain_send_terminal_receipt_reemitted",
-        source: event.source,
-        promptHash: taskSignal.promptHash,
-        taskId: terminalReceipt.details.taskId,
-        taskRunId: terminalReceipt.details.taskRunId,
-        outcome: terminalReceipt.details.outcome,
-        completionApproved: terminalReceipt.details.completionApproved,
-        replacementTaskStarted: false,
-        replayed: false,
-        modelTurnStarted: false
-      });
-      pi.sendMessage(
-        {
-          customType: terminalReceipt.customType,
-          content: terminalReceipt.content,
-          display: true,
-          details: terminalReceipt.details
-        },
-        { triggerTurn: false }
-      );
-      return { action: "handled" };
-    }
-    if (!uncertainSendContinuation) {
-      if (sessionTask && sessionTask.trace.outcome !== "pending") dependencies.state.clearTaskBoundary(ctx, sessionTask.taskRunId);
-      else if (!sessionTask) {
-        const cachedTask = dependencies.state.taskIdentity(ctx);
-        if (cachedTask) dependencies.state.clearTaskBoundary(ctx, cachedTask.taskRunId);
-      }
-    }
-    const activeTask = sessionTask?.trace.outcome === "pending" ? sessionTask : undefined;
-    const turn = dependencies.state.beginTurn(ctx, taskSignal.promptHash, {
-      lightweightNonAuthorizingChange: isLightweightNonAuthorizingChangeContinuation(text)
-    });
-    observeHostWireInput(ctx.cwd, ctx.sessionManager.getSessionId(), { turnId: turn.turnId,
-      promptHash: taskSignal.promptHash, text, source: event.source,
-      hasImages: Boolean(event.images?.length || extractLocalImagePathCandidates(text, ctx.cwd).length) });
-    const authorityPolicy = activeTask?.trace.outcome === "pending" ? dependencies.authorityPolicy(ctx, activeTask) : undefined;
-    let authorityHandoffReady = false;
-    if (activeTask && authorityPolicy?.disposition === "new-attempt-required") {
-      try {
-        writeHandoffProjection(ctx.cwd, buildHandoffProjection(ctx.cwd, activeTask, {
-          gate: { decision: "fail", missing: [`authority policy handoff: ${authorityPolicy.reason}`], missingVerifyCommands: [] },
-          recovery: null
-        }));
-        authorityHandoffReady = true;
-      } catch (error) {
-        ctx.ui.notify(`Piagent authority-policy handoff could not be written: ${error instanceof Error ? error.message : String(error)}`, "warning");
-      }
-    }
-    const replacementIntake = Boolean(activeTask && (
-      activeTask.workingTreeDigestMigration?.status === "new-attempt-required" || authorityHandoffReady
-    ));
-    const readProtectedPaths = dependencies.readProtectedPaths(ctx);
-    const protectedTarget = taskSignal.paths.some((candidate) => matchesProtectedPath(candidate, readProtectedPaths));
-    const protectedOnlyTarget = taskSignal.paths.length > 0
-      && taskSignal.paths.every((candidate) => matchesProtectedPath(candidate, readProtectedPaths));
-    const runtimeIntakeMode = !activeTask ? automaticTaskIntakeMode(text, readProtectedPaths) : undefined;
-    const runtimeIntake = Boolean(runtimeIntakeMode);
-    const manualIntake = !activeTask && !runtimeIntake && manualTaskIntakeEligible(text, readProtectedPaths);
-    const promptGroups = protectedOnlyTarget
-      ? []
-      : toolGroupsForPrompt(text).filter((group) => (
-          runtimeIntake ? group !== "intake" && group !== "task" : true
-        ));
-    if (manualIntake && !promptGroups.includes("intake")) promptGroups.push("intake");
-    dependencies.activateToolGroups(ctx, activeTask?.trace.outcome === "pending"
-      ? [...promptGroups.filter((group) => replacementIntake || group !== "intake"), ...(replacementIntake ? ["intake" as const] : activeTaskToolGroups(activeTask))]
-      : promptGroups);
-    dependencies.telemetry(ctx, {
-      event: "user_input",
-      turnId: turn.turnId,
-      source: event.source,
-      promptHash: taskSignal.promptHash,
-      promptChars: taskSignal.promptChars,
-      workflow: taskSignal.workflow,
-      riskLane: taskSignal.lane,
-      intakeMode: runtimeIntake ? "runtime" : "model",
-      taskMode: runtimeIntakeMode,
-      protectedTarget,
-      protectedOnlyTarget,
-      manualIntake,
-      explicitPathCount: taskSignal.paths.length,
-      termCount: taskSignal.terms.length
+    // Preserve the actual message, including whitespace and slash-like text.
+    // Session/run lifecycle belongs to the host, not to prompt rewriting.
+    const text = event.text;
+    if (!text.trim()) return { action: "continue" };
+    const signal = classifyContextTask(text);
+    const cached = dependencies.state.taskIdentity(ctx);
+    if (cached) dependencies.state.clearTaskBoundary(ctx, cached.taskRunId);
+    const turn = dependencies.state.beginTurn(ctx, signal.promptHash);
+    observeHostWireInput(ctx.cwd, ctx.sessionManager.getSessionId(), {
+      turnId: turn.turnId, promptHash: signal.promptHash, text, source: event.source,
+      hasImages: Boolean(event.images?.length || extractLocalImagePathCandidates(text, ctx.cwd).length)
     });
-
-    const imageAttachment = attachLocalImagesFromText(
-      text,
-      event.images,
-      ctx.cwd,
-      () => dependencies.imageAccess(ctx)
-    );
-    if (imageAttachment?.attached.length) {
-      ctx.ui.notify(`Piagent image input: attached ${imageAttachment.attached.map((item) => item.marker).join(", ")}`, "info");
-    } else if (imageAttachment?.skipped.length) {
-      ctx.ui.notify(`Piagent image input: skipped ${imageAttachment.skipped.length} local image path(s)`, "warning");
-    }
-
-    const inputText = imageAttachment?.text ?? text;
-    const canRewriteWorkflow = event.source !== "extension";
-    const snapshot = buildUsageSnapshot(ctx, String(pi.getThinkingLevel()));
-    const preflight = buildContextPreflight(snapshot, chooseFreshWorkflow(inputText, inputText), inputText.length);
-    const hasBoilerplate = looksLikeGovernedBoilerplate(inputText);
-    const shouldFreshen = canRewriteWorkflow
-      && preflight.recommendation === "fresh-session"
-      && (hasBoilerplate || isPiagentWorkflowInput(inputText) || inputText.length >= LONG_INPUT_CHARS);
-    const shouldCollapseBoilerplate = canRewriteWorkflow
-      && hasBoilerplate
-      && inputText.length >= dependencies.boilerplateCollapseChars;
-    const outgoingImages = [
-      ...(Array.isArray(event.images) ? event.images : []),
-      ...(imageAttachment?.images ?? [])
-    ];
-
-    if (!shouldFreshen && !shouldCollapseBoilerplate) {
-      if (imageAttachment?.attached.length) return { action: "transform", text: inputText, images: outgoingImages };
-      return { action: "continue" };
-    }
-
-    const task = extractTaskRequest(inputText);
-    const workflow = chooseFreshWorkflow(inputText, task);
-    const reason = shouldFreshen
-      ? "Current session is near context limits; use a fresh governed session."
-      : "Mandatory flow boilerplate is already part of the platform; collapse it to the task request.";
-    const command = shouldFreshen
-      ? buildFreshCommand(ctx.cwd, workflow, inputText, reason)
-      : `/${workflow} ${trimTaskForInline(task)}`;
-
-    ctx.ui.notify(`Piagent preflight: ${reason}`, "warning");
-    return outgoingImages.length > 0
-      ? { action: "transform", text: command, images: outgoingImages }
-      : { action: "transform", text: command };
+    const protectedPaths = dependencies.readProtectedPaths(ctx);
+    const protectedOnly = signal.paths.length > 0 && signal.paths.every((p) => matchesProtectedPath(p, protectedPaths));
+    dependencies.activateToolGroups(ctx, protectedOnly ? [] : toolGroupsForPrompt(text)
+      .filter((group) => !["intake", "task", "recovery"].includes(group)));
+    dependencies.telemetry(ctx, { event: "user_input", turnId: turn.turnId, source: event.source,
+      promptHash: signal.promptHash, promptChars: text.length, inputMode: "freeform" });
+    const attachment = attachLocalImagesFromText(text, event.images, ctx.cwd, () => dependencies.imageAccess(ctx));
+    if (attachment?.attached.length) return { action: "transform", text: attachment.text,
+      images: [...(event.images ?? []), ...attachment.images] };
+    if (attachment?.skipped.length) ctx.ui.notify(`Skipped ${attachment.skipped.length} inaccessible image(s)`, "warning");
+    return { action: "continue" };
   });
 }

package/packages/piagent-core/runtime/hooks/session-start-hook.ts

@@ -5,6 +5,7 @@ import { contextIndexV2Status } from "../../extensions/context-engine.js";
 import { resolveExecutionBackend } from "../../extensions/execution-backend.js";
 import type { ProjectProfile, TaskContract } from "../../extensions/guard-types.js";
 import { pruneCaptureFiles } from "../../extensions/state-retention.js";
+import { ensureStateRootIgnored } from "../../extensions/local-state-path.js";
 import { migrateTaskState, readSessionTaskBinding } from "../../extensions/task-state.js";
 import {
   pruneTaskJournal
@@ -71,6 +72,7 @@ type SessionStartHookDependencies = {
 
 export function registerSessionStartHook(pi: ExtensionAPI, dependencies: SessionStartHookDependencies): void {
   pi.on("session_start", async (_event, ctx) => {
+    ensureStateRootIgnored(ctx.cwd);
     dependencies.activateToolGroups(ctx, []);
     const projectTrusted = ctx.isProjectTrusted();
     const explicitProfile = Boolean(process.env.PIAGENT_PROFILE?.trim());

package/packages/piagent-core/runtime/inspection/approval-broker.ts

@@ -210,7 +210,15 @@ export class PiApprovalBroker {
   #action(binding: Binding, draft: ApprovalActionDraft, cwd: string): Record<string, unknown> {
     const command = draft.commandPreview === null || draft.commandPreview === undefined ? null : safe(draft.commandPreview, 4_000);
     const parameter = safe(draft.parameterPreview ?? "No additional parameters", 4_000);
-    const targetPaths = (draft.targetPaths ?? []).slice(0, 32).map((item) => safe(item, 500)).filter((item) => item.text).map((item) => item.text);
+    // Shown to the member: a path inside the project is written relative to it
+    // ("." is the project folder itself), so the card does not repeat the
+    // home directory; a path outside the project stays absolute.
+    const shown = (item: string) => {
+      if (!path.isAbsolute(item)) return item;
+      const relative = path.relative(cwd, item);
+      return relative === "" ? "." : !relative.startsWith("..") && !path.isAbsolute(relative) ? relative : item;
+    };
+    const targetPaths = (draft.targetPaths ?? []).slice(0, 32).map((item) => safe(shown(item), 500)).filter((item) => item.text).map((item) => item.text);
     const targetSummaries = (draft.targetSummaries ?? []).slice(0, 32).map((item) => safe(item, 500)).filter((item) => item.text).map((item) => item.text);
     const removed = [command, parameter].filter((item) => item?.redacted).length;
     const truncated = Boolean(command?.truncated || parameter.truncated || (draft.targetPaths?.length ?? 0) > 32 || (draft.targetSummaries?.length ?? 0) > 32);

package/packages/piagent-core/runtime/inspection/same-process-bridge-proof.ts

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 
-export const PINNED_BRIDGE_HOST_VERSION = "0.86.1" as const;
+export const PINNED_BRIDGE_HOST_VERSION = "0.87.1" as const;
 export const SAME_PROCESS_BRIDGE_PROOF_VERSION = "piagent-webui-same-process-bridge-v1" as const;
 
 const HOST_EVENTS = Object.freeze([

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

@@ -248,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.86.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"),

package/packages/piagent-core/runtime/managed-failure.d.mts

@@ -0,0 +1,10 @@
+export type ManagedFailure = { role: "main" | "research" | "review"; code: string; kind: string; requestId: string | null; local: boolean };
+export function failureKind(code: string): string;
+export function failureIsLocal(code: string): boolean;
+export function failureCode(raw: unknown): string;
+export function describeFailure(role: string, raw: unknown): string;
+export function parseFailure(raw: unknown): ManagedFailure | null;
+export function failureIsAdmissionRefusal(code: string): boolean;
+export function failureReason(code: string): string;
+export function unnamedFailureText(raw: unknown): string | null;
+export function failureIsBriefRefusal(code: string): boolean;

package/packages/piagent-core/runtime/managed-failure.mjs

@@ -0,0 +1,164 @@
+// Why a company request failed, as one stable code and one sentence a member
+// can act on. Studio answers with a machine code; the broker and this runtime
+// have their own. The Terminal shows the sentence, the WebUI maps the code to
+// its own copy, and nothing here names the harness model.
+//
+// Kinds: refused (the model's provider declined the request under its usage
+// policy), quota (this key's token budget), provider-limit (the company's model
+// account), account (that account must sign in again), busy (retry shortly),
+// trial-limit (Studio's live-test ceiling), key (import the key again),
+// policy (model or thinking not allowed),
+// new-session (this conversation cannot continue), rejected (the request
+// itself), unreachable (no connection to Studio), service (Studio answered
+// but its model gateway failed), config-changed (key or harness changed while
+// running), update (this Piagent is too old for the harness), tool (a tool's
+// own failure), failed (anything else).
+import { redactSensitiveText } from '../security/sensitive-data.js';
+
+const CODES = {
+  token_quota_exhausted: ['quota', "this key's token quota is used up"],
+  upstream_rate_limited: ['provider-limit', "the company's model account is rate limited or out of usage at the provider"],
+  account_capacity_unavailable: ['provider-limit', 'no company model account has capacity for this model right now'],
+  concurrency_limit: ['busy', 'this key already runs its maximum number of requests'],
+  request_rate_limit: ['busy', 'this key sends requests too fast'],
+  helper_capacity_exhausted: ['busy', 'this key already runs its maximum number of subagents'],
+  connector_busy: ['busy', "Studio's model gateway is at capacity"],
+  operation_unavailable: ['busy', 'Studio could not check this request in time'],
+  account_recovering: ['busy', 'the company model account is being checked after an earlier failure'],
+  session_account_busy_retry_later: ['busy', "this conversation's model account is busy"],
+  session_account_not_ready_retry_later: ['busy', "this conversation's model account is not ready yet"],
+  live_trial_limit_reached: ['trial-limit', "Studio's live-test request ceiling is used up; an administrator has to raise it"],
+  authentication_required: ['key', 'the company key is no longer valid'],
+  invalid_run_grant: ['key', 'the company key or this run is no longer valid'],
+  run_grant_required: ['key', 'this key only works through Agent Watch'],
+  policy_denied: ['policy', 'this key may not use this model, thinking level or output size'],
+  thinking_level_unavailable: ['policy', 'this thinking level is not available for the harness'],
+  harness_model_unsupported: ['policy', 'the harness uses a model Studio cannot run'],
+  harness_profile_unavailable: ['policy', 'the team has no usable harness'],
+  execution_capability_unavailable: ['policy', 'no company model account can run this model'],
+  session_account_unavailable_start_new_session: ['new-session', "this conversation's model account is gone"],
+  run_state_conflict: ['config-changed', 'this run was closed or replaced'],
+  run_recovery_pending_usage: ['busy', "an earlier request of this run is still being accounted"],
+  invalid_request: ['rejected', 'Studio rejected the request as invalid'],
+  upstream_request_rejected: ['rejected', 'the model rejected the request (too long or not valid for it)'],
+  upstream_policy_refusal: ['refused', "the model's provider declined this request under its usage policy"],
+  request_too_large: ['rejected', 'the conversation is larger than Studio accepts in one request (4 MiB)'],
+  execution_precondition_failed: ['service', 'the chosen company model account changed before the request started'],
+  connector_unavailable: ['service', "Studio's model gateway is not available"],
+  connector_execution_failed: ['service', "Studio's model gateway failed"],
+  inference_unavailable: ['service', 'Studio could not run the request'],
+  managed_service_unavailable: ['service', 'Studio could not start the run'],
+  upstream_interrupted: ['service', 'the model response was interrupted'],
+  upstream_incomplete: ['service', 'the model returned no response'],
+  upstream_timeout: ['service', 'the model did not answer in time'],
+  upstream_unavailable: ['service', 'the model provider is not answering'],
+  upstream_auth_required: ['account', "the company's model account has to sign in again in Studio"],
+  'studio-unreachable': ['unreachable', 'Studio could not be reached'],
+  'managed-broker:offline': ['unreachable', 'Agent Watch could not reach Studio'],
+  'managed-broker-timeout': ['unreachable', 'Agent Watch did not answer in time'],
+  'managed-broker-disconnected': ['unreachable', 'the Agent Watch helper stopped'],
+  'managed-broker:serverUnavailable': ['service', 'Studio could not start the run'],
+  'managed-broker:upstreamUnavailable': ['service', 'Studio could not start the run'],
+  'managed-broker:invalidKey': ['key', 'the company key is no longer valid'],
+  'managed-broker:permissionDenied': ['key', 'Agent Watch no longer holds a usable company key'],
+  'managed-broker:keychainApprovalRequired': ['key', 'macOS has not allowed Agent Watch to read the company key'],
+  'managed-broker:quotaExceeded': ['quota', "this key's token quota is used up"],
+  'managed-broker:rateLimited': ['busy', 'Studio is limiting this key right now'],
+  'managed-broker:identityChanged': ['config-changed', 'the key, harness or run changed in Studio'],
+  'managed-broker:invalidResponse': ['config-changed', 'Studio refused to start the run with the current harness'],
+  'managed-route-changed': ['config-changed', 'the harness model changed while this run was active'],
+  'managed-grant-invalid': ['config-changed', 'the harness changed and this conversation still has the old one'],
+  'managed-configuration-unavailable': ['config-changed', 'the key has no usable harness'],
+  'managed-main-model-unavailable': ['policy', 'the harness main model is not available to this key'],
+  'managed-native-catalog-update-required': ['update', 'this Piagent does not know the harness model; update Piagent'],
+  'managed-session-scope-changed': ['new-session', 'this conversation belongs to another member or another Studio'],
+  'managed-run-required': ['config-changed', 'no company run is active'],
+  'managed-helper-unavailable': ['busy', 'this subagent is already running'],
+  'managed-helper-used': ['tool', 'this subagent already ran for this message; each runs once per message'],
+  'managed-helper-limit': ['tool', 'this subagent already ran 8 times for this message'],
+  helper_run_limit_reached: ['tool', 'this subagent already ran 8 times for this message'],
+  'managed-helper-cancelled': ['tool', 'the subagent was stopped'],
+  'managed-helper-failed': ['failed', 'the subagent ended without an answer'],
+  'web-search-empty': ['tool', 'the search returned nothing'],
+  'managed-web-search-unavailable': ['tool', 'web search runs only on a Claude or Codex model; use web_fetch with a known address'],
+  'managed-session-open-elsewhere': ['new-session', 'this conversation is running in the Piagent WebUI; continue it there or start a new one'],
+  'managed-session-lease-unavailable': ['failed', 'Piagent could not record which process runs this conversation'],
+  'managed-plan-required': ['tool', 'for a complex task the Harness asks for a checklist (update_plan) before the first file edit'],
+  'managed-plan-invalid': ['tool', 'the checklist was not in the expected form'],
+  'managed-request-failed': ['failed', 'the request could not be sent'],
+  'studio-request-failed': ['failed', 'Studio answered with an error'],
+};
+const ROLES = { main: 'main agent', research: 'research subagent', review: 'review subagent' };
+const REQUEST = /\b([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\b/;
+const NETWORK = /fetch failed|econnrefused|econnreset|enotfound|ehostunreach|etimedout|socket hang up|network|connection error|terminated|timed? ?out|aborted due to timeout/i;
+
+export function failureKind(code) { return CODES[code]?.[0] ?? 'failed'; }
+// Studio said no at admission, before any model account was asked: the same
+// request can be asked again later, and nothing reaches the model twice. A
+// failure after admission (the model's own error, an interrupted answer) is
+// never in this list: replaying it could repeat billed work.
+const ADMISSION_REFUSALS = new Set(['session_account_busy_retry_later', 'session_account_not_ready_retry_later',
+  'concurrency_limit', 'account_capacity_unavailable', 'request_rate_limit']);
+export function failureIsAdmissionRefusal(code) { return ADMISSION_REFUSALS.has(code); }
+// Refused before the model did any work, for a reason that passes in seconds:
+// the account's sign-in was being renewed (the provider refused the old one)
+// or changed just before the request started, or the run's two-minute grant
+// lapsed under the request (after the Mac slept, Studio's clock catches up
+// at once), or Studio could not check the request's grant in its 5 s (many
+// requests of one member at once); each ask renews the grant first. Asked
+// again a few times only: an account that really has to sign in again, or a
+// run that was closed, still says so.
+const BRIEF_REFUSALS = new Set(['execution_precondition_failed', 'upstream_auth_required', 'invalid_run_grant', 'operation_unavailable']);
+export function failureIsBriefRefusal(code) { return BRIEF_REFUSALS.has(code); }
+// The words of a failure no code names, redacted, for a record nobody is
+// shown; null for a named failure.
+export function unnamedFailureText(raw) {
+  return ['managed-request-failed', 'studio-request-failed'].includes(failureCode(raw)) ? redactSensitiveText(String(raw ?? '')).text.slice(0, 600) : null;
+}
+// The sentence alone, for a status line that already says who is waiting.
+export function failureReason(code) { return (CODES[code] ?? CODES['managed-request-failed'])[1]; }
+// A failure Studio never saw: nothing was sent, so it is not a model request.
+export function failureIsLocal(code) { return code.startsWith('managed-') || code === 'studio-unreachable'; }
+
+function known(code) { return typeof code === 'string' && Object.hasOwn(CODES, code) ? code : null; }
+
+// The stable code inside any error text this runtime can produce or receive.
+export function failureCode(raw) {
+  const text = String(raw ?? '');
+  const tagged = /\[([A-Za-z0-9_:.-]{1,80})\](?: \(request [0-9a-f-]{36}\))?\s*$/.exec(text)?.[1];
+  if (known(tagged)) return tagged;
+  const studio = /"code"\s*:\s*"([a-z0-9_]{1,80})"/.exec(text)?.[1] ?? /web-search-failed: ([a-z0-9_-]{1,80})/.exec(text)?.[1];
+  if (studio === 'initial_request_limit_reached') return 'live_trial_limit_reached';
+  if (known(studio)) return studio;
+  const local = /(managed-broker:[A-Za-z_]{1,80}|managed-[a-z-]{1,80}|web-search-empty)/.exec(text)?.[1];
+  if (known(local)) return local;
+  if (studio || /\bAPI error \(\d{3}\)|^\d{3} \{/.test(text)) return 'studio-request-failed';
+  // The provider declined the request itself (its usage policy), not Studio:
+  // the same request is declined again, so it is said in words.
+  if (/usage policy|violative|refusals-and-fallback/i.test(text)) return 'upstream_policy_refusal';
+  // The provider library's words for an answer stream that ended empty: Studio
+  // admitted the request and nothing came back. It is not asked again.
+  if (/stream ended without a (terminal event|stop reason)|response has no body/i.test(text)) return 'upstream_incomplete';
+  if (NETWORK.test(text)) return 'studio-unreachable';
+  return 'managed-request-failed';
+}
+
+// "Agent Watch main agent: <what failed> [code] (request <id>)". The role says
+// who failed; the model behind it is the harness's business, not the reader's.
+export function describeFailure(role, raw) {
+  const code = failureCode(raw), request = REQUEST.exec(String(raw ?? ''))?.[1];
+  return `Agent Watch ${ROLES[role] ?? ROLES.main}: ${CODES[code][1]} [${code}]${request && !failureIsLocal(code) ? ` (request ${request})` : ''}`;
+}
+
+// What a reader of a stored error message needs: who, what kind, which code
+// and Studio's request id when there is one. Null when it is not a company
+// failure this module recognises the shape of.
+export function parseFailure(raw) {
+  const text = String(raw ?? '');
+  if (!text.trim()) return null;
+  const code = failureCode(text);
+  const role = /^Agent Watch (main agent|research subagent|review subagent): /.exec(text)?.[1]?.split(' ')[0]
+    ?? /(research|review) subagent/.exec(text)?.[1] ?? 'main';
+  const request = failureIsLocal(code) ? null : REQUEST.exec(text)?.[1] ?? null;
+  return { role, code, kind: failureKind(code), requestId: request, local: failureIsLocal(code) };
+}

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",