@piagent/platform 1.6.1 → 1.7.1

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 0.86.1 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/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; }
+}

package/packages/piagent-core/runtime/model/service-tier-runtime.ts

@@ -0,0 +1,242 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export const PIAGENT_FAST_MODE_STATE_ENTRY_TYPE = "piagent-fast-mode-state";
+export const PIAGENT_SERVICE_TIER_RECEIPT_ENTRY_TYPE = "piagent-service-tier-receipt";
+export const PIAGENT_FAST_SERVICE_TIER = "fast" as const;
+export const PIAGENT_FAST_PROVIDER_SERVICE_TIER = "priority" as const;
+
+type FastModeSource = "default" | "environment" | "session-command" | "session-state";
+
+export type ServiceTierReceipt = {
+  schemaVersion: 1;
+  enabled: boolean;
+  mode: "standard" | "fast";
+  source: FastModeSource;
+  requestedServiceTier: "fast" | null;
+  observedRequestServiceTier: "priority" | null;
+  providerResponseServiceTier: null;
+  providerResponseEvidence: "unavailable-host-api";
+  provider: string | null;
+  modelId: string | null;
+  applied: boolean;
+  reasonCode: "fast-mode-disabled" | "provider-not-supported" | "fast-request-pending" | "fast-request-observed";
+};
+
+type SessionState = {
+  enabled: boolean;
+  source: FastModeSource;
+  observedRequestServiceTier: "priority" | null;
+  provider: string | null;
+  modelId: string | null;
+  observationPersisted: boolean;
+};
+
+type StateEntry = { type?: unknown; customType?: unknown; data?: unknown };
+
+const SERVICE_TIER_RECEIPT_KEYS = [
+  "schemaVersion", "enabled", "mode", "source", "requestedServiceTier", "observedRequestServiceTier",
+  "providerResponseServiceTier", "providerResponseEvidence", "provider", "modelId", "applied", "reasonCode"
+] as const;
+const FAST_MODE_SOURCES = new Set<FastModeSource>(["default", "environment", "session-command", "session-state"]);
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : null;
+}
+
+function sessionId(ctx: ExtensionContext): string {
+  return ctx.sessionManager.getSessionId();
+}
+
+function environmentOverride(value: unknown): boolean | null {
+  if (typeof value !== "string" || !value.trim()) return null;
+  const normalized = value.trim().toLowerCase();
+  if (["1", "true", "yes", "on", "fast"].includes(normalized)) return true;
+  if (["0", "false", "no", "off", "standard", "default"].includes(normalized)) return false;
+  return null;
+}
+
+function restoredState(ctx: ExtensionContext): boolean | null {
+  let entries: StateEntry[] = [];
+  try { entries = ctx.sessionManager.getBranch() as StateEntry[]; } catch { return null; }
+  for (let index = entries.length - 1; index >= 0; index -= 1) {
+    const entry = entries[index], data = record(entry.data);
+    if (entry.type !== "custom" || entry.customType !== PIAGENT_FAST_MODE_STATE_ENTRY_TYPE || data?.schemaVersion !== 1) continue;
+    if (typeof data.enabled === "boolean") return data.enabled;
+  }
+  return null;
+}
+
+function isOpenAiCodex(provider: unknown): boolean {
+  return String(provider ?? "") === "openai-codex";
+}
+
+function boundedIdentity(value: unknown): value is string | null {
+  return value === null || typeof value === "string" && value.length <= 512 && !value.includes("\0");
+}
+
+export function parseServiceTierReceipt(value: unknown): ServiceTierReceipt | null {
+  const candidate = record(value);
+  if (!candidate || Object.keys(candidate).length !== SERVICE_TIER_RECEIPT_KEYS.length
+    || !SERVICE_TIER_RECEIPT_KEYS.every((key) => Object.hasOwn(candidate, key))) return null;
+  if (candidate.schemaVersion !== 1 || typeof candidate.enabled !== "boolean"
+    || !["standard", "fast"].includes(String(candidate.mode))
+    || !FAST_MODE_SOURCES.has(candidate.source as FastModeSource)
+    || ![null, PIAGENT_FAST_SERVICE_TIER].includes(candidate.requestedServiceTier as null | "fast")
+    || ![null, PIAGENT_FAST_PROVIDER_SERVICE_TIER].includes(candidate.observedRequestServiceTier as null | "priority")
+    || candidate.providerResponseServiceTier !== null || candidate.providerResponseEvidence !== "unavailable-host-api"
+    || !boundedIdentity(candidate.provider) || !boundedIdentity(candidate.modelId)
+    || typeof candidate.applied !== "boolean"
+    || !["fast-mode-disabled", "provider-not-supported", "fast-request-pending", "fast-request-observed"].includes(String(candidate.reasonCode))) return null;
+
+  const receipt = candidate as ServiceTierReceipt;
+  const expectedMode = receipt.enabled ? "fast" : "standard";
+  const expectedRequested = receipt.enabled ? PIAGENT_FAST_SERVICE_TIER : null;
+  const supported = isOpenAiCodex(receipt.provider);
+  const expectedReason = !receipt.enabled ? "fast-mode-disabled" : !supported ? "provider-not-supported"
+    : receipt.observedRequestServiceTier === PIAGENT_FAST_PROVIDER_SERVICE_TIER ? "fast-request-observed" : "fast-request-pending";
+  const expectedApplied = receipt.enabled && supported
+    && receipt.observedRequestServiceTier === PIAGENT_FAST_PROVIDER_SERVICE_TIER;
+  if (receipt.mode !== expectedMode || receipt.requestedServiceTier !== expectedRequested
+    || receipt.reasonCode !== expectedReason || receipt.applied !== expectedApplied
+    || (!receipt.enabled || !supported) && receipt.observedRequestServiceTier !== null) return null;
+  return { ...receipt };
+}
+
+export class ServiceTierRuntime {
+  readonly #environmentValue: string | undefined;
+  readonly #states = new Map<string, SessionState>();
+
+  constructor(options: { environmentValue?: string } = {}) {
+    this.#environmentValue = options.environmentValue;
+  }
+
+  restore(ctx: ExtensionContext): ServiceTierReceipt {
+    const environment = environmentOverride(this.#environmentValue);
+    const restored = environment === null ? restoredState(ctx) : null;
+    const enabled = environment ?? restored ?? false;
+    const source: FastModeSource = environment !== null ? "environment" : restored !== null ? "session-state" : "default";
+    this.#states.set(sessionId(ctx), {
+      enabled, source, observedRequestServiceTier: null, provider: null, modelId: null, observationPersisted: false
+    });
+    return this.receipt(ctx);
+  }
+
+  forget(ctx: ExtensionContext): void {
+    this.#states.delete(sessionId(ctx));
+  }
+
+  set(pi: ExtensionAPI, ctx: ExtensionContext, enabled: boolean): ServiceTierReceipt {
+    const state: SessionState = {
+      enabled, source: "session-command", observedRequestServiceTier: null, provider: null, modelId: null, observationPersisted: false
+    };
+    this.#states.set(sessionId(ctx), state);
+    pi.appendEntry(PIAGENT_FAST_MODE_STATE_ENTRY_TYPE, {
+      schemaVersion: 1,
+      enabled,
+      requestedServiceTier: enabled ? PIAGENT_FAST_SERVICE_TIER : null,
+      source: state.source
+    });
+    return this.receipt(ctx);
+  }
+
+  receipt(ctx: ExtensionContext): ServiceTierReceipt {
+    const state = this.#state(ctx);
+    const provider = typeof ctx.model?.provider === "string" ? ctx.model.provider : null;
+    const modelId = typeof ctx.model?.id === "string" ? ctx.model.id : null;
+    const supported = isOpenAiCodex(provider);
+    const observationMatchesCurrentModel = state.observedRequestServiceTier === PIAGENT_FAST_PROVIDER_SERVICE_TIER
+      && state.provider === provider && state.modelId === modelId;
+    const observed = observationMatchesCurrentModel ? PIAGENT_FAST_PROVIDER_SERVICE_TIER : null;
+    return {
+      schemaVersion: 1,
+      enabled: state.enabled,
+      mode: state.enabled ? "fast" : "standard",
+      source: state.source,
+      requestedServiceTier: state.enabled ? PIAGENT_FAST_SERVICE_TIER : null,
+      observedRequestServiceTier: observed,
+      providerResponseServiceTier: null,
+      providerResponseEvidence: "unavailable-host-api",
+      provider,
+      modelId,
+      applied: state.enabled && supported && observed === PIAGENT_FAST_PROVIDER_SERVICE_TIER,
+      reasonCode: !state.enabled ? "fast-mode-disabled" : !supported ? "provider-not-supported"
+        : observed === PIAGENT_FAST_PROVIDER_SERVICE_TIER ? "fast-request-observed" : "fast-request-pending"
+    };
+  }
+
+  applyProviderRequest(pi: ExtensionAPI, ctx: ExtensionContext, payloadValue: unknown): {
+    payload: unknown;
+    changed: boolean;
+    receipt: ServiceTierReceipt;
+    observationChanged: boolean;
+  } {
+    const state = this.#state(ctx), payload = record(payloadValue);
+    if (!state.enabled || !isOpenAiCodex(ctx.model?.provider) || !payload) {
+      return { payload: payloadValue, changed: false, receipt: this.receipt(ctx), observationChanged: false };
+    }
+    const next = payload.service_tier === PIAGENT_FAST_PROVIDER_SERVICE_TIER
+      ? payloadValue
+      : { ...payload, service_tier: PIAGENT_FAST_PROVIDER_SERVICE_TIER };
+    const observationChanged = state.observedRequestServiceTier !== PIAGENT_FAST_PROVIDER_SERVICE_TIER
+      || state.provider !== String(ctx.model?.provider ?? "") || state.modelId !== String(ctx.model?.id ?? "");
+    state.observedRequestServiceTier = PIAGENT_FAST_PROVIDER_SERVICE_TIER;
+    state.provider = String(ctx.model?.provider ?? "") || null;
+    state.modelId = String(ctx.model?.id ?? "") || null;
+    const receipt = this.receipt(ctx);
+    if (observationChanged && !state.observationPersisted) {
+      pi.appendEntry(PIAGENT_SERVICE_TIER_RECEIPT_ENTRY_TYPE, receipt);
+      state.observationPersisted = true;
+    }
+    return { payload: next, changed: next !== payloadValue, receipt, observationChanged };
+  }
+
+  #state(ctx: ExtensionContext): SessionState {
+    const id = sessionId(ctx), found = this.#states.get(id);
+    if (found) return found;
+    this.restore(ctx);
+    return this.#states.get(id)!;
+  }
+}
+
+function receiptText(receipt: ServiceTierReceipt): string {
+  return [
+    `fastMode: ${receipt.mode}`,
+    `provider/model: ${receipt.provider && receipt.modelId ? `${receipt.provider}/${receipt.modelId}` : "unknown"}`,
+    `requestedServiceTier: ${receipt.requestedServiceTier ?? "no Piagent override (host/provider configuration applies)"}`,
+    `observedRequestServiceTier: ${receipt.observedRequestServiceTier ?? "not-observed"}`,
+    `providerMapping: Fast mode uses OpenAI service_tier=priority`,
+    `providerResponseServiceTier: unavailable (Pi host API does not expose response.service_tier)`,
+    `state: ${receipt.reasonCode}`,
+    "modelThinkingParity: unchanged",
+    "note: Fast service can consume provider quota or cost differently; Fast mode never changes model or thinking"
+  ].join("\n");
+}
+
+export function registerFastModeCommand(pi: ExtensionAPI, runtime: ServiceTierRuntime): void {
+  pi.registerCommand("fast", {
+    description: "Show or switch OpenAI Codex Fast service tier without changing model/thinking",
+    getArgumentCompletions: (prefix: string) => ["status", "on", "off"]
+      .filter((value) => value.startsWith(String(prefix ?? "").trim().toLowerCase()))
+      .map((value) => ({ value, label: value })),
+    handler: async (args, ctx) => {
+      const action = String(args ?? "").trim().toLowerCase() || "status";
+      if (!["status", "on", "off"].includes(action)) {
+        ctx.ui.notify("Usage: /fast status|on|off", "warning");
+        return;
+      }
+      let receipt = action === "status" ? runtime.receipt(ctx) : runtime.set(pi, ctx, action === "on");
+      if (action === "on" && receipt.reasonCode === "provider-not-supported") {
+        ctx.ui.notify("Fast mode is enabled for the session, but the active provider is not OpenAI Codex.", "warning");
+      } else {
+        ctx.ui.notify(`Piagent Fast override: ${receipt.enabled ? "on" : "off"}`, receipt.enabled ? "info" : "warning");
+      }
+      receipt = runtime.receipt(ctx);
+      pi.sendMessage({
+        customType: "piagent-service-tier-receipt",
+        content: receiptText(receipt),
+        display: true,
+        details: receipt
+      }, { triggerTurn: false });
+    }
+  });
+}