@piagent/platform 1.6.1 → 1.7.1

package/packages/piagent-webui/gateway/gateway-service.ts

@@ -32,6 +32,7 @@ import { ProjectRegistry } from "./project-registry.ts";
 import { pickNativeProjectFolders } from "./native-project-picker.ts";
 import { ProviderAuthBroker } from "./provider-auth-broker.ts";
 import { McpAuthBroker } from "./mcp-auth-broker.ts";
+import type { ScopedBrokerRouter } from "./session-runtime-factory.ts";
 
 function unavailable(reasonCode: string) {
   return { status: "unavailable" as const, version: null, reasonCode };
@@ -80,6 +81,8 @@ export async function startPiagentGateway(options: {
   packageRoot: string;
   expectedPiVersion: string;
   agentDir?: string;
+  staticRoot?: string;
+  scopedBrokerRouter?: ScopedBrokerRouter;
 }): Promise<{ descriptor: GatewayDescriptor; wait(): Promise<void>; close(): Promise<void> }> {
   const state = gatewayProfileState(options.agentDir);
   process.env.PI_CODING_AGENT_DIR = state.agentDir;
@@ -87,7 +90,7 @@ export async function startPiagentGateway(options: {
   const metadata = new SessionMetadataStore(state.root, key);
   const projects = new ProjectRegistry(state.root, key);
   const gatewayInstanceRef = `gateway_${process.pid}_${randomBytes(24).toString("base64url")}`;
-  const staticRoot = path.join(options.packageRoot, "packages", "piagent-webui", "dist", "client");
+  const staticRoot = options.staticRoot ?? path.join(options.packageRoot, "packages", "piagent-webui", "dist", "client");
   if (!fs.existsSync(path.join(staticRoot, "index.html"))) throw new Error("gateway-webui-build-missing");
 
   let descriptor: GatewayDescriptor | null = null;
@@ -145,6 +148,7 @@ export async function startPiagentGateway(options: {
     runtimes = new SessionRuntimeSupervisor({
       gatewayInstanceRef, key, leases, listSessions: () => host.SessionManager.listAll(),
       host, agentDir: state.agentDir, packageRoot: options.packageRoot, modelRuntime: inspectionModels, events,
+      scopedBrokerRouter: options.scopedBrokerRouter,
       resolveProject: (projectRef) => projects.resolve(projectRef)
     });
     const readCatalog = () => buildSessionCatalog({
@@ -182,7 +186,8 @@ export async function startPiagentGateway(options: {
       events, command: commands });
     const inspections = new SessionInspectionRegistry({ gatewayInstanceRef, host, key, packageRoot: options.packageRoot, agentDir: state.agentDir,
       models: inspectionModels, projects, mcpAuth, listSessions: () => runtimes!.listSessions(),
-      openLiveSession: (sessionRef) => runtimes!.liveSessionManager(sessionRef) });
+      openLiveSession: (sessionRef) => runtimes!.liveSessionManager(sessionRef),
+      operationLiveness: (sessionRef) => runtimes!.currentOperation(sessionRef) ? "running" : "idle" });
     // Staged bytes live beside the inspection projection they were checked
     // against, so both read the same session through the same registry.
     attachments = new SessionAttachmentRegistry({

package/packages/piagent-webui/gateway/gateway-session-stream.ts

@@ -2,7 +2,8 @@ import { randomBytes } from "node:crypto";
 
 import { redactSensitiveText } from "../../piagent-core/security/sensitive-data.js";
 import { hasVisibleText } from "../shared/text-visibility.ts";
-import { GatewayEventStore } from "./gateway-events.ts";
+import type { TerminalDeliveryReceipt } from "../server/terminal-delivery-receipt.ts";
+import { GatewayEventStore, type GatewayTaskStatus } from "./gateway-events.ts";
 import { SessionOperationLifecycle, type SessionOperationObservation,
   type SessionOperationPhase, type SessionOperationRetryPolicyOptions } from "./session-operation-lifecycle.ts";
 
@@ -17,6 +18,14 @@ const COMPLETION_GATE = /^\[Piagent completion gate: (CONTINUING|NOT APPROVED)\]
 export type GatewayOperationSettlement = "completed" | "blocked" | "aborted" | "error" | "unknown";
 type Settlement = { outcome: GatewayOperationSettlement; reasonCode: string | null };
 
+function projectedTaskStatus(taskOutcome: string | null, override: GatewayTaskStatus | null): GatewayTaskStatus {
+  if (override) return override;
+  if (taskOutcome === "pending") return "pending";
+  if (taskOutcome === "completed") return "completed";
+  if (["blocked", "partial", "failed"].includes(String(taskOutcome))) return "failed";
+  return "unknown";
+}
+
 function clean(value: unknown): string {
   return String(value ?? "").replace(/\u001b(?:\[[0-?]*[ -/]*[@-~]|[@-_])/g, "")
     .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, " ");
@@ -26,6 +35,66 @@ function safeTool(value: unknown): string {
   if (safe.redacted) return "redacted-tool";
   return safe.text.replace(/[^A-Za-z0-9._:-]/g, "-").replace(/^[^A-Za-z0-9]+/, "").slice(0, 160) || "tool";
 }
+
+const DIRECT_FILE_KEYS = ["file", "filePath", "file_path", "filename", "targetFile", "target_file"] as const;
+const PATH_KEYS = ["path", "targetPath", "target_path"] as const;
+const FILE_MUTATION_OR_READ_TOOL = /(?:^|[._:-])(read|write|edit|patch|apply)(?:[._:-]|$)/i;
+const FILE_SEARCH_TOOL = /(?:^|[._:-])(grep|search|find|glob|list|ls)(?:[._:-]|$)/i;
+const FILE_LIKE_BASENAME = /(?:^\.[^./\\]+$)|(?:\.[A-Za-z0-9][A-Za-z0-9+_-]{0,15}$)|^(?:Dockerfile|Containerfile|Makefile|README|LICENSE|CHANGELOG)$/i;
+const PATCH_FILE_HEADER = /^\*\*\* (?:Update|Add|Delete) File:\s*(.+)$/m;
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : null;
+}
+
+function firstString(records: readonly Record<string, unknown>[], keys: readonly string[]): string | null {
+  for (const source of records) for (const key of keys) {
+    const value = source[key];
+    if (typeof value === "string" && value.trim()) return value;
+    if (Array.isArray(value)) {
+      const first = value.find((item) => typeof item === "string" && item.trim());
+      if (typeof first === "string") return first;
+    }
+  }
+  return null;
+}
+
+function safeBasename(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const source = clean(value).trim();
+  if (!source || source.includes("\n") || source.includes("\r") || /(?:^|\s)(?:https?|data):\/\//i.test(source)) return null;
+  const parts = source.replace(/\\/g, "/").replace(/\/+$/, "").split("/");
+  const basename = (parts.at(-1) ?? "").trim().replace(/^["']|["']$/g, "");
+  if (!basename || basename === "." || basename === "..") return null;
+  const projected = redactSensitiveText(basename);
+  if (projected.redacted || projected.text !== basename || /[\u0000-\u001f\u007f/\\]/.test(basename)) return null;
+  return basename.slice(0, 160);
+}
+
+/**
+ * Returns only a redaction-checked basename suitable for the compact chat
+ * progress row. Raw arguments and full paths remain confined to the runtime;
+ * the Activity inspector keeps its independent, richer projection.
+ */
+export function safeToolFileLabel(toolName: unknown, args: unknown): string | null {
+  const tool = safeTool(toolName), direct = record(args); if (!direct) return null;
+  const nested = record(direct.args), input = record(direct.input);
+  const records = [direct, ...(nested ? [nested] : []), ...(input ? [input] : [])];
+  const explicitFile = firstString(records, DIRECT_FILE_KEYS);
+  if (explicitFile) return safeBasename(explicitFile);
+  const path = firstString(records, PATH_KEYS);
+  if (path) {
+    const basename = safeBasename(path);
+    if (basename && (FILE_MUTATION_OR_READ_TOOL.test(tool)
+      || FILE_SEARCH_TOOL.test(tool) && FILE_LIKE_BASENAME.test(basename))) return basename;
+  }
+  if (FILE_MUTATION_OR_READ_TOOL.test(tool)) {
+    const patch = firstString(records, ["patch"]);
+    const headerPath = typeof patch === "string" ? PATCH_FILE_HEADER.exec(patch)?.[1] : null;
+    if (headerPath) return safeBasename(headerPath);
+  }
+  return null;
+}
 function ref(prefix: string): string { return `${prefix}_${randomBytes(18).toString("base64url")}`; }
 function messageText(message: any): string {
   if (typeof message?.content === "string") return message.content;
@@ -69,6 +138,7 @@ export function runtimeRestartReasonCode(event: unknown): "runtime-restart-requi
 export class GatewaySessionStream {
   readonly sessionRef: string;
   readonly operationRef: string;
+  readonly messageRequestId: string | null;
   readonly #events: GatewayEventStore;
   #messageRef: string | null = null;
   #messageSequence = 0;
@@ -83,7 +153,12 @@ export class GatewaySessionStream {
   #lifecycleTerminationReasonCode: string | null = null;
   #settleListeners: Array<() => void> = [];
   readonly #toolRefs = new Map<string, string>();
+  readonly #toolLabels = new Map<string, string>();
+  readonly #toolFileLabels = new Map<string, string | null>();
   readonly #lifecycle: SessionOperationLifecycle;
+  readonly #commitTerminalDeliveryReceipt: ((message: unknown) => TerminalDeliveryReceipt | undefined) | undefined;
+  #terminalDeliveryMessage: unknown;
+  #receiptOnly = true;
 
   get runtimeRestartRequired(): boolean { return this.#runtimeRestartRequired; }
   get lifecycleTerminationReasonCode(): string | null { return this.#lifecycleTerminationReasonCode; }
@@ -91,6 +166,9 @@ export class GatewaySessionStream {
   get retryAbortRequired(): boolean { return this.#lifecycle.retryAbortRequired; }
 
   markAborted(reasonCode = "operation-aborted"): void { this.#forcedSettlement = { outcome: "aborted", reasonCode }; }
+  markBlocked(reasonCode = "operation-blocked"): void {
+    if (!this.#forcedSettlement) this.#forcedSettlement = { outcome: "blocked", reasonCode };
+  }
   markError(reasonCode = "operation-failed"): void {
     if (!this.#forcedSettlement) this.#forcedSettlement = { outcome: "error", reasonCode };
   }
@@ -102,10 +180,17 @@ export class GatewaySessionStream {
     if (!wasSettled) for (const resolve of this.#settleListeners.splice(0)) resolve();
   }
 
-  constructor(options: { sessionRef: string; operationRef: string; events: GatewayEventStore;
-    retryPolicy?: SessionOperationRetryPolicyOptions }) {
-    this.sessionRef = options.sessionRef; this.operationRef = options.operationRef; this.#events = options.events;
+  constructor(options: { sessionRef: string; operationRef: string; messageRequestId?: string | null; events: GatewayEventStore;
+    retryPolicy?: SessionOperationRetryPolicyOptions;
+    commitTerminalDeliveryReceipt?: (message: unknown) => TerminalDeliveryReceipt | undefined }) {
+    this.sessionRef = options.sessionRef; this.operationRef = options.operationRef;
+    this.messageRequestId = options.messageRequestId ?? null; this.#events = options.events;
     this.#lifecycle = new SessionOperationLifecycle({ operationRef: options.operationRef, retryPolicy: options.retryPolicy });
+    this.#commitTerminalDeliveryReceipt = options.commitTerminalDeliveryReceipt;
+  }
+
+  #correlation(): { messageRequestId?: string } {
+    return this.messageRequestId ? { messageRequestId: this.messageRequestId } : {};
   }
 
   started(): Promise<void> {
@@ -122,6 +207,9 @@ export class GatewaySessionStream {
     const wasStarted = this.#lifecycle.started, wasSettled = this.#lifecycle.hostSettled;
     const observation = this.#lifecycle.observe(event);
     if (!observation.accepted) return observation;
+    if (event?.type === "agent_start" || event?.message?.role === "assistant" || event?.assistantMessageEvent
+      || String(event?.type ?? "").startsWith("tool_execution_")) this.#receiptOnly = false;
+    if (event?.type === "message_end" && event.message?.role === "custom") this.#terminalDeliveryMessage = event.message;
     if (!wasStarted && this.#lifecycle.started) for (const resolve of this.#startListeners.splice(0)) resolve();
     if (!wasSettled && this.#lifecycle.hostSettled) for (const resolve of this.#settleListeners.splice(0)) resolve();
     if (observation.retry === "abort") this.markError(observation.reasonCode ?? "automatic-retry-blocked");
@@ -129,6 +217,7 @@ export class GatewaySessionStream {
       return observation;
     }
     if (event?.type === "agent_settled") {
+      this.#settleActiveTools("operation-settled-before-tool-result");
       return observation;
     }
     if (event?.type === "message_start" && event.message?.role === "assistant") {
@@ -146,22 +235,35 @@ export class GatewaySessionStream {
       this.#flush(true); this.#lastMessageRef = this.#messageRef; this.#settlement = assistantSettlement(event.message); return observation;
     }
     if (event?.type === "tool_execution_start" && typeof event.toolCallId === "string") {
-      const toolCallRef = ref("tool"); this.#toolRefs.set(event.toolCallId, toolCallRef);
-      this.#events.publish("tool.started", { sessionRef: this.sessionRef, operationRef: this.operationRef, toolCallRef,
-        toolLabel: safeTool(event.toolName), isError: null, reasonCode: null });
+      const toolCallRef = ref("tool"), toolLabel = safeTool(event.toolName), fileLabel = safeToolFileLabel(event.toolName, event.args);
+      this.#toolRefs.set(event.toolCallId, toolCallRef); this.#toolLabels.set(event.toolCallId, toolLabel);
+      this.#toolFileLabels.set(event.toolCallId, fileLabel);
+      this.#events.publish("tool.started", { sessionRef: this.sessionRef, operationRef: this.operationRef, ...this.#correlation(), toolCallRef,
+        toolLabel, fileLabel, isError: null, reasonCode: null });
       return observation;
     }
     if (event?.type === "tool_execution_end" && typeof event.toolCallId === "string") {
       const toolCallRef = this.#toolRefs.get(event.toolCallId); if (!toolCallRef) return observation;
       const reasonCode = runtimeRestartReasonCode(event);
       if (reasonCode) this.#runtimeRestartRequired = true;
-      this.#events.publish("tool.completed", { sessionRef: this.sessionRef, operationRef: this.operationRef, toolCallRef,
-        toolLabel: safeTool(event.toolName), isError: event.isError === true, reasonCode });
-      this.#toolRefs.delete(event.toolCallId);
+      this.#events.publish("tool.completed", { sessionRef: this.sessionRef, operationRef: this.operationRef, ...this.#correlation(), toolCallRef,
+        toolLabel: safeTool(event.toolName), fileLabel: this.#toolFileLabels.get(event.toolCallId) ?? null,
+        isError: event.isError === true, reasonCode });
+      this.#toolRefs.delete(event.toolCallId); this.#toolLabels.delete(event.toolCallId); this.#toolFileLabels.delete(event.toolCallId);
     }
+    if (event?.type === "turn_end") this.#settleActiveTools("turn-ended-before-tool-result");
     return observation;
   }
 
+  #settleActiveTools(reasonCode: string): void {
+    for (const [toolCallId, toolCallRef] of this.#toolRefs) {
+      this.#events.publish("tool.completed", { sessionRef: this.sessionRef, operationRef: this.operationRef, ...this.#correlation(), toolCallRef,
+        toolLabel: this.#toolLabels.get(toolCallId) ?? "tool", fileLabel: this.#toolFileLabels.get(toolCallId) ?? null,
+        isError: true, reasonCode });
+    }
+    this.#toolRefs.clear(); this.#toolLabels.clear(); this.#toolFileLabels.clear();
+  }
+
   #flush(final: boolean): void {
     if (!this.#messageRef || !this.#buffer || this.#eventCount >= MAX_EVENTS) {
       if (this.#eventCount >= MAX_EVENTS) this.#truncated = true;
@@ -186,37 +288,57 @@ export class GatewaySessionStream {
   #emit(value: string): void {
     for (let offset = 0; offset < value.length; offset += MAX_DELTA) {
       if (this.#eventCount >= MAX_EVENTS) { this.#truncated = true; break; }
-      this.#events.publish("message.delta", { sessionRef: this.sessionRef, operationRef: this.operationRef,
+      this.#events.publish("message.delta", { sessionRef: this.sessionRef, operationRef: this.operationRef, ...this.#correlation(),
         messageRef: this.#messageRef!, messageSequence: this.#messageSequence++, delta: value.slice(offset, offset + MAX_DELTA) });
       this.#eventCount += 1;
     }
   }
 
-  complete(sessionRevision: string | null, taskOutcome: string | null = null): void {
+  complete(sessionRevision: string | null, taskOutcome: string | null = null,
+    taskStatusOverride: GatewayTaskStatus | null = null): void {
     if (!this.#lifecycle.markTerminal()) return;
+    const receipt = this.#receiptOnly && !this.#forcedSettlement && !this.#runtimeRestartRequired
+      && sessionRevision !== null && taskOutcome !== null && taskOutcome !== "pending"
+      ? this.#commitTerminalDeliveryReceipt?.(this.#terminalDeliveryMessage) : undefined;
+    if (receipt) {
+      // The canonical transcript renders a custom receipt. Never stream it as
+      // assistant text or open a model turn just to supply a final message.
+      this.#lastMessageRef = ref("receipt");
+      const diagnostic = receipt.details.diagnosticDelivery as { mode?: string; qualityClaim?: string } | undefined;
+      const diagnosticDelivered = taskOutcome === "completed" && receipt.details.completionApproved === false
+        && diagnostic?.mode === "diagnostic" && diagnostic.qualityClaim === "withheld";
+      const completedTask = receipt.details.outcome === "completed" && (receipt.details.completionApproved || diagnosticDelivered)
+        && receipt.details.gateDecision === "pass";
+      // Delivery of an already refused task is a completed operation, never
+      // approval to perform the refused action. Both the committed receipt
+      // and the supervisor's current native task projection must agree.
+      const refusedTask = taskOutcome === "blocked" && taskStatusOverride === "refused"
+        && receipt.details.outcome === "blocked" && receipt.details.completionApproved === false
+        && receipt.details.gateDecision === "fail";
+      this.#settlement = completedTask || refusedTask ? { outcome: "completed", reasonCode: null }
+        : { outcome: "blocked", reasonCode: "terminal-receipt-not-approved" };
+    }
     this.#flush(true);
+    this.#settleActiveTools("operation-settled-before-tool-result");
     let settlement = this.#forcedSettlement ?? (this.#runtimeRestartRequired
       ? { outcome: "unknown" as const, reasonCode: "runtime-restart-required" }
       : this.#settlement);
     const messageRef = this.#lastMessageRef ?? this.#messageRef;
+    const taskStatus = projectedTaskStatus(taskOutcome, taskStatusOverride);
     if (settlement.outcome === "completed" && !messageRef) {
       settlement = { outcome: "unknown", reasonCode: "assistant-message-unavailable" };
-    } else if (settlement.outcome === "completed" && taskOutcome === "pending") {
-      // Provider completion is not governed-task completion. The durable task
-      // contract is authoritative, so withhold both success settlement and the
-      // durable assistant-success event until that contract becomes terminal.
-      settlement = { outcome: "unknown", reasonCode: "task-completion-pending" };
     } else if (settlement.outcome === "completed" && sessionRevision === null) {
       // Streaming text is not durable success until the canonical session
       // projection confirms it. Still terminate the UI, but do not show draft.
       settlement = { outcome: "unknown", reasonCode: "session-projection-unavailable" };
     }
     if (settlement.outcome === "completed" && messageRef && sessionRevision) {
-      this.#events.publish("message.completed", { sessionRef: this.sessionRef, operationRef: this.operationRef,
+      this.#events.publish("message.completed", { sessionRef: this.sessionRef, operationRef: this.operationRef, ...this.#correlation(),
         messageRef, sessionRevision, truncated: this.#truncated });
     }
-    this.#events.publish("operation.settled", { sessionRef: this.sessionRef, operationRef: this.operationRef,
+    this.#events.publish("operation.settled", { sessionRef: this.sessionRef, operationRef: this.operationRef, ...this.#correlation(),
       messageRef, sessionRevision, settlement: settlement.outcome,
+      taskStatus,
       reasonCode: settlement.outcome === "completed" ? null : settlement.reasonCode ?? "operation-settlement-unknown" });
   }
 }

package/packages/piagent-webui/gateway/rpc-ui-context.ts

@@ -16,13 +16,38 @@ export function rpcUiContext(): object {
     getThinkingBorderColor: () => plain,
     getBashModeBorderColor: () => plain
   });
-  return new Proxy({}, {
-    get(_target, property) {
-      if (property === GATEWAY_RUNTIME_UI_MARKER) return true;
-      if (property === "theme") return theme;
-      if (property === "confirm") return () => new Promise<boolean>(() => undefined);
-      if (property === "select" || property === "input") return async () => undefined;
-      return () => undefined;
-    }
-  });
+  const noop = () => undefined;
+  // Pi copies this context when wrapping prompts. Keep methods and the ownership
+  // marker enumerable so notification delivery and gateway detection survive.
+  return {
+    [GATEWAY_RUNTIME_UI_MARKER]: true,
+    theme,
+    confirm: () => new Promise<boolean>(() => undefined),
+    select: async () => undefined,
+    input: async () => undefined,
+    editor: async () => undefined,
+    custom: async () => undefined,
+    notify: noop,
+    onTerminalInput: () => noop,
+    setStatus: noop,
+    setWorkingMessage: noop,
+    setWorkingVisible: noop,
+    setWorkingIndicator: noop,
+    setHiddenThinkingLabel: noop,
+    setWidget: noop,
+    setFooter: noop,
+    setHeader: noop,
+    setTitle: noop,
+    pasteToEditor: noop,
+    setEditorText: noop,
+    getEditorText: () => "",
+    addAutocompleteProvider: noop,
+    setEditorComponent: noop,
+    getEditorComponent: noop,
+    getAllThemes: () => [],
+    getTheme: noop,
+    setTheme: () => ({ success: false, error: "UI not available" }),
+    getToolsExpanded: () => false,
+    setToolsExpanded: noop
+  };
 }

package/packages/piagent-webui/gateway/runtime-command-controller.ts

@@ -5,8 +5,12 @@ import {
   buildWebUiRuntimeCommand,
   isWebUiRuntimeActionId
 } from "../../piagent-core/runtime/workflows/webui-runtime-command.ts";
+import {
+  PIAGENT_SERVICE_TIER_RECEIPT_ENTRY_TYPE,
+  parseServiceTierReceipt
+} from "../../piagent-core/runtime/model/service-tier-runtime.ts";
 import type { Catalog } from "../contracts/generated/session-catalog-v1.ts";
-import type { Action, Command, Receipt } from "../contracts/generated/runtime-command-v1.ts";
+import type { Action, Command, Output, Receipt } from "../contracts/generated/runtime-command-v1.ts";
 import { GatewayEventStore } from "./gateway-events.ts";
 import { SessionRuntimeSupervisor } from "./session-runtime-supervisor.ts";
 
@@ -15,6 +19,9 @@ const REVISION = /^[A-Za-z0-9][A-Za-z0-9._:~-]{0,159}$/;
 const MAX_REPLAYS = 200;
 
 type Replay = { digest: string; receipt: Receipt };
+type FastControlAssessment = Pick<Receipt, "state" | "resultCode" | "reasonCode">;
+
+const FAST_ACTIONS = new Set<Action>(["runtime.fast-status", "runtime.fast-on", "runtime.fast-off"]);
 
 function record(value: unknown): value is Record<string, unknown> {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
@@ -41,6 +48,33 @@ function commandDigest(command: Command): string {
     argument: command.argument, confirmed: command.confirmed })).digest("hex");
 }
 
+function normalizedOutputs(value: unknown): Receipt["outputs"] {
+  if (!Array.isArray(value)) return [];
+  return value.slice(0, 8).map((item) => {
+    if (!record(item)) return item;
+    const { details: _details, ...base } = item;
+    if (item.customType !== PIAGENT_SERVICE_TIER_RECEIPT_ENTRY_TYPE) return base;
+    const details = parseServiceTierReceipt(item.details);
+    return details ? { ...base, details } : base;
+  }) as Receipt["outputs"];
+}
+
+function assessFastControl(action: Action, outputs: readonly Output[]): FastControlAssessment | null {
+  if (!FAST_ACTIONS.has(action)) return null;
+  const candidates = outputs.filter((output) => output.customType === PIAGENT_SERVICE_TIER_RECEIPT_ENTRY_TYPE);
+  if (candidates.length === 0) return { state: "uncertain", resultCode: "effect-unknown", reasonCode: "fast-service-tier-receipt-missing" };
+  if (candidates.length !== 1) return { state: "uncertain", resultCode: "effect-unknown", reasonCode: "fast-service-tier-receipt-ambiguous" };
+  const details = parseServiceTierReceipt(candidates[0]?.details);
+  if (!details) return { state: "uncertain", resultCode: "effect-unknown", reasonCode: "fast-service-tier-receipt-invalid" };
+  if (action === "runtime.fast-on" && !details.enabled || action === "runtime.fast-off" && details.enabled) {
+    return { state: "uncertain", resultCode: "effect-unknown", reasonCode: "fast-service-tier-receipt-state-mismatch" };
+  }
+  if (details.reasonCode === "provider-not-supported") {
+    return { state: "rejected", resultCode: "unavailable", reasonCode: "provider-not-supported" };
+  }
+  return { state: "settled", resultCode: "completed", reasonCode: null };
+}
+
 export class RuntimeCommandController {
   readonly #catalog: () => Promise<Catalog>;
   readonly #runtimes: SessionRuntimeSupervisor;
@@ -89,11 +123,17 @@ export class RuntimeCommandController {
       const result = await this.#runtimes.runRuntimeCommand(command.sessionRef, built.command);
       const after = await this.#readyCatalog();
       const afterRow = after.sessions.find((session) => session.sessionRef === command.sessionRef);
-      const zeroTurnViolation = built.spec.effect === "read-only" && result.modelCallObserved;
-      const receipt = this.#receipt(command, zeroTurnViolation ? "uncertain" : "settled",
-        zeroTurnViolation ? "effect-unknown" : "completed",
-        zeroTurnViolation ? "read-only-command-started-model-call" : null,
-        afterRow?.sessionRevision ?? null, result.modelCallObserved, result.outputs as Receipt["outputs"]);
+      const outputs = normalizedOutputs(result.outputs);
+      const fastControl = assessFastControl(command.action, outputs);
+      const zeroTurnExpected = built.spec.effect === "read-only" || built.spec.effect === "session-setting";
+      const zeroTurnViolation = zeroTurnExpected && result.modelCallObserved;
+      const zeroTurnReason = built.spec.effect === "session-setting"
+        ? "session-setting-command-started-model-call"
+        : "read-only-command-started-model-call";
+      const receipt = this.#receipt(command, zeroTurnViolation ? "uncertain" : fastControl?.state ?? "settled",
+        zeroTurnViolation ? "effect-unknown" : fastControl?.resultCode ?? "completed",
+        zeroTurnViolation ? zeroTurnReason : fastControl?.reasonCode ?? null,
+        afterRow?.sessionRevision ?? null, result.modelCallObserved, outputs);
       this.#events.publish("session.changed", { catalogRevision: after.catalogRevision, session: afterRow ?? row });
       return this.#settle(command, digest, receipt);
     } catch (error) {

package/packages/piagent-webui/gateway/runtime-session-controls.ts

@@ -1,4 +1,17 @@
 import { redactSensitiveText } from "../../piagent-core/security/sensitive-data.js";
+import {
+  PIAGENT_SERVICE_TIER_RECEIPT_ENTRY_TYPE,
+  parseServiceTierReceipt,
+  type ServiceTierReceipt
+} from "../../piagent-core/runtime/model/service-tier-runtime.ts";
+
+type RuntimeCommandOutput = {
+  customType: string;
+  content: string;
+  truncated: boolean;
+  redacted: boolean;
+  details?: ServiceTierReceipt;
+};
 
 export async function executePermissionCommand(session: any,
   permissionMode: "read-only" | "workspace-write" | "trusted-full-access"): Promise<void> {
@@ -12,7 +25,7 @@ export async function executePermissionCommand(session: any,
 }
 
 export async function executeRuntimeCommand(session: any, command: string): Promise<{
-  outputs: Array<{ customType: string; content: string; truncated: boolean; redacted: boolean }>;
+  outputs: RuntimeCommandOutput[];
   modelCallObserved: boolean;
 }> {
   const before = Array.isArray(session.messages) ? session.messages.length : 0;
@@ -22,8 +35,10 @@ export async function executeRuntimeCommand(session: any, command: string): Prom
     const source = typeof message.content === "string" ? message.content : JSON.stringify(message.content ?? "");
     const bounded = source.slice(0, 12_000), redacted = redactSensitiveText(bounded);
     const rawType = String(message.customType ?? "runtime-output");
+    const details = rawType === PIAGENT_SERVICE_TIER_RECEIPT_ENTRY_TYPE
+      ? parseServiceTierReceipt(message.details) : null;
     return { customType: /^[A-Za-z0-9._-]{1,120}$/.test(rawType) ? rawType : "runtime-output", content: redacted.text,
-      truncated: source.length > bounded.length, redacted: redacted.redacted };
+      truncated: source.length > bounded.length, redacted: redacted.redacted, ...(details ? { details } : {}) };
   });
   return { outputs, modelCallObserved: added.some((message: any) => message?.role === "assistant") };
 }

package/packages/piagent-webui/gateway/session-catalog.ts

@@ -2,6 +2,7 @@ import { createHmac } from "node:crypto";
 import path from "node:path";
 
 import { redactSensitiveText } from "../../piagent-core/security/sensitive-data.js";
+import { workflowCommandPattern } from "../../piagent-core/runtime/workflows/webui-workflow.ts";
 import type { Catalog, SessionRow } from "../contracts/generated/session-catalog-v1.ts";
 import type { MetadataSnapshot, SessionMetadata } from "./session-metadata-store.ts";
 import { projectRefForCwd, sessionRefForPath } from "../ownership/session-refs.ts";
@@ -54,7 +55,12 @@ function display(value: unknown, maximum: number, fallback: string): string {
   return (clean || fallback).slice(0, maximum);
 }
 
-const INTERNAL_FRESH_TRANSITION = /(?:^|\b)(?:\/fresh\s+(?:task|scout|be-to-fe)|(?:task|scout|be-to-fe):)\b[\s\S]{0,180}\bRead task intake from \.pi\/task-inbox\//i;
+const WORKFLOW_PATTERN = workflowCommandPattern({ aliases: false });
+const INTERNAL_FRESH_TRANSITION = new RegExp(
+  `(?:^|\\b)(?:\\/fresh\\s+(?:${WORKFLOW_PATTERN})|(?:${WORKFLOW_PATTERN}):)\\b[\\s\\S]{0,180}\\bRead task intake from \\.pi\\/task-inbox\\/`, "i"
+);
+const LEADING_WORKFLOW = new RegExp(`^\\/(?:fresh\\s+)?(?:${WORKFLOW_PATTERN})\\s+`, "i");
+const LEADING_WORKFLOW_LABEL = new RegExp(`^(?:${WORKFLOW_PATTERN}):\\s*`, "i");
 
 function atWordBoundary(value: string, maximum: number): string {
   if (value.length <= maximum) return value;
@@ -78,8 +84,8 @@ export function projectedSessionTitle(info: Pick<PiSessionInfo, "name" | "firstM
   const internal = INTERNAL_FRESH_TRANSITION.test(source) || INTERNAL_FRESH_TRANSITION.test(first)
     || /\.pi\/task-inbox\//i.test(source);
   const cleaned = display(source, 500, "")
-    .replace(/^\/(?:fresh\s+)?(?:task|scout|be-to-fe)\s+/i, "")
-    .replace(/^(?:task|scout|be-to-fe):\s*/i, "")
+    .replace(LEADING_WORKFLOW, "")
+    .replace(LEADING_WORKFLOW_LABEL, "")
     .replace(/^[-#*>\s]+/, "")
     // Keep underscores: the shared redactor deliberately emits
     // [REDACTED_SECRET], and title cleanup must not mutate that proof marker.

package/packages/piagent-webui/gateway/session-command-controller.ts

@@ -6,6 +6,7 @@ import { buildWebUiWorkflowCommand, isWebUiWorkflowId, type WebUiWorkflowId } fr
 import { GatewayEventStore } from "./gateway-events.ts";
 import { SessionCommandStore, type SessionAction, type SessionCommandIdentity } from "./session-command-store.ts";
 import { SessionRuntimeSupervisor } from "./session-runtime-supervisor.ts";
+import type { SessionSendResult } from "./session-prompt-dispatch.ts";
 import { SessionMetadataStore } from "./session-metadata-store.ts";
 
 const REF = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,159}$/;
@@ -125,9 +126,9 @@ export class SessionCommandController {
   }
 
   async #execute(command: SessionCommand): Promise<Receipt> {
-    const current = await this.#readyCatalog(), row = command.sessionRef ? current.sessions.find((item) => item.sessionRef === command.sessionRef) : null;
     const replay = this.#store.lookup(command);
     if (replay.state === "settled") return { ...replay.receipt!, deduplicated: true };
+    const current = await this.#readyCatalog(), row = command.sessionRef ? current.sessions.find((item) => item.sessionRef === command.sessionRef) : null;
     if (replay.state === "conflict") return this.#rejected(command, current, row, "invalid-command", "idempotency-payload-mismatch");
     if (replay.state === "unavailable") return this.#rejected(command, current, row, "unavailable", "session-command-journal-unavailable");
     if (replay.state === "pending") {
@@ -148,7 +149,9 @@ export class SessionCommandController {
     catch { return this.#rejected(command, current, row, "unavailable", "session-command-admission-failed"); }
     let targetSessionRef = command.sessionRef;
     let attachmentReservation: { commit(): void; release(): void } | null = null;
-    let sendAttempted = false;
+    let sendAttempted = false, dispatchCommitted = false;
+    let deferredDispatch: Pick<SessionSendResult, "dispatch" | "cancel"> | null = null;
+    let observedCatalog = current, observedRow = row;
     try {
       let resultCode: "created" | "acquired" | "released" | "started" | "queued" | "steered" | "aborted" | "model-changed" | "thinking-changed" | "permission-changed"
         | "renamed" | "pinned" | "unpinned" | "archived" | "unarchived" | "forked" | "no-change",
@@ -172,12 +175,15 @@ export class SessionCommandController {
         }
         const created = await this.#readyCatalog(), createdRow = created.sessions.find((item) => item.sessionRef === targetSessionRef);
         if (!createdRow) throw new Error("session-catalog-refresh-failed");
+        observedCatalog = created; observedRow = createdRow;
         if (command.payload.deferInitialMessage === true) resultCode = "created";
         else {
           const message = buildWebUiWorkflowCommand((command.payload.workflow as WebUiWorkflowId | undefined) ?? null,
             String(command.payload.message));
           const sent = await this.#runtimes.send(targetSessionRef, { delivery: "new-operation", message,
-            expectedOperationRef: null }, createdRow.sessionRevision);
+            messageRequestId: String(command.payload.messageRequestId), expectedOperationRef: null },
+          createdRow.sessionRevision, { deferDispatch: true });
+          deferredDispatch = sent;
           resultCode = sent.resultCode === "started" ? "started" : sent.resultCode; operationRef = sent.operationRef;
         }
       } else if (command.action === "session.acquire") { await this.#runtimes.acquire(command.sessionRef!); resultCode = "acquired"; }
@@ -186,6 +192,7 @@ export class SessionCommandController {
         await this.#runtimes.acquire(command.sessionRef!);
         const acquired = await this.#readyCatalog(), acquiredRow = acquired.sessions.find((item) => item.sessionRef === command.sessionRef);
         if (!acquiredRow) throw new Error("session-catalog-refresh-failed");
+        observedCatalog = acquired; observedRow = acquiredRow;
         const payload = command.payload as { delivery: "new-operation" | "follow-up" | "steer"; message: string;
           expectedOperationRef: string | null; messageRequestId: string; attachmentRefs: string[]; workflow?: WebUiWorkflowId };
         // Staged refs are claimed once, here, before the runtime is asked to
@@ -198,9 +205,10 @@ export class SessionCommandController {
         if (!this.#prepareAttachments && payload.attachmentRefs.length > 0) throw new Error("session-attachment-unavailable");
         sendAttempted = true;
         const message = buildWebUiWorkflowCommand(payload.workflow ?? null, prepared.text);
-        const sent = await this.#runtimes.send(command.sessionRef!, { ...payload, message, images: prepared.images },
-          acquiredRow.sessionRevision);
-        prepared.commit();
+        const sent = await this.#runtimes.send(command.sessionRef!, { ...payload, message,
+          messageRequestId: payload.messageRequestId, images: prepared.images },
+          acquiredRow.sessionRevision, { deferDispatch: true });
+        deferredDispatch = sent;
         resultCode = sent.resultCode; operationRef = sent.operationRef;
       } else if (command.action === "session.abort") {
         operationRef = String(command.payload.operationRef);
@@ -239,15 +247,27 @@ export class SessionCommandController {
       }
       const after = await this.#readyCatalog(), afterRow = after.sessions.find((item) => item.sessionRef === targetSessionRef);
       if (!afterRow) throw new Error("session-catalog-refresh-failed");
+      observedCatalog = after; observedRow = afterRow;
       const receipt = this.#settled(command, after, afterRow, resultCode, operationRef);
       try { this.#store.settle(command, receipt, this.#now()); }
-      catch { return this.#uncertain(command, after, afterRow, "session-command-settlement-not-durable"); }
+      catch {
+        deferredDispatch?.cancel?.(); try { attachmentReservation?.release(); } catch { /* staged refs remain unavailable to this command */ }
+        return this.#uncertain(command, after, afterRow, "session-command-settlement-not-durable");
+      }
+      if (attachmentReservation) {
+        try { attachmentReservation.commit(); } catch { /* prepared bytes remain dispatchable; the one-shot registry fails closed */ }
+        attachmentReservation = null;
+      }
       this.#events.publish("session.changed", { catalogRevision: after.catalogRevision, session: afterRow });
+      dispatchCommitted = true; deferredDispatch?.dispatch?.();
       return receipt;
     } catch (cause) {
-      const after = await this.#readyCatalog(), afterRow = after.sessions.find((item) => item.sessionRef === targetSessionRef) ?? row;
+      if (!dispatchCommitted) deferredDispatch?.cancel?.();
+      let after = observedCatalog;
+      try { after = await this.#readyCatalog(); } catch { /* the last proven catalog remains authoritative */ }
+      const afterRow = after.sessions.find((item) => item.sessionRef === targetSessionRef) ?? observedRow;
       const message = cause instanceof Error ? cause.message : "session-command-failed";
-      const noDispatchEffect = command.action === "session.send" && (!sendAttempted
+      const noDispatchEffect = command.action === "session.send" && (!sendAttempted || Boolean(deferredDispatch && !dispatchCommitted)
         || /^(session-runtime-unavailable|session-operation-conflict|session-owner-conflict|session-runtime-busy)$/.test(message));
       if (attachmentReservation) {
         try { if (noDispatchEffect) attachmentReservation.release(); else attachmentReservation.commit(); }

package/packages/piagent-webui/gateway/session-effective-options.ts

@@ -25,15 +25,8 @@ export function effectiveThinkingLevel(session: any): string | null {
   return THINKING_LEVELS.has(level) ? level : null;
 }
 
-export async function configureSessionOptions(session: any, modelRef: string | null,
-  thinkingLevel: string): Promise<EffectiveSessionOptions> {
-  if (modelRef) {
-    const models = session.modelRuntime?.getAvailableSnapshot?.() ?? [];
-    const model = models.find((value: any) => webUiModelRef(String(value.provider ?? ""),
-      String(value.id ?? value.modelId ?? "")) === modelRef);
-    try { if (model) await session.setModel(model); } catch { /* Canonical read-back below decides the effect. */ }
-  }
-  try { await session.setThinkingLevel(thinkingLevel); } catch { /* Canonical read-back below decides the effect. */ }
+export function inspectEffectiveSessionOptions(session: any, modelRef: string | null,
+  thinkingLevel: string): EffectiveSessionOptions {
   const effectiveModel = effectiveModelRef(session), effectiveThinking = effectiveThinkingLevel(session);
   if (!effectiveModel) return { state: "unknown", modelRef: null,
     thinkingLevel: effectiveThinking, reasonCode: "session-model-effect-unknown" };