@piagent/platform 1.6.0 → 1.7.1

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

@@ -14,10 +14,14 @@ export type GatewayProtocolEvent = {
   payload: Record<string, unknown>;
 };
 
+export type GatewayTaskStatus = "pending" | "completed" | "refused" | "failed" | "unknown";
+
 export type GatewayTerminalSettlement = {
   sessionRef: string;
   operationRef: string;
+  messageRequestId?: string;
   settlement: "blocked" | "aborted" | "error" | "unknown";
+  taskStatus: GatewayTaskStatus;
   reasonCode: string;
   settledAt: string;
   sequence: number;
@@ -30,7 +34,12 @@ const SETTLEMENT_RETENTION_COUNT = 100;
 const SETTLEMENT_RETENTION_MS = 60 * 60_000;
 const MAX_SETTLEMENT_DECISION_COUNT = 10_000;
 type GatewaySettlementDecision = { settledAt: string; settlement: "completed" | GatewayTerminalSettlement["settlement"];
-  reasonCode: string | null };
+  taskStatus: GatewayTaskStatus; reasonCode: string | null };
+
+function settlementTaskStatus(value: unknown): GatewayTaskStatus {
+  return ["pending", "completed", "refused", "failed", "unknown"].includes(String(value))
+    ? value as GatewayTaskStatus : "unknown";
+}
 
 function settlementReason(settlement: GatewayTerminalSettlement["settlement"], value: unknown): string {
   if (typeof value === "string" && REASON_CODE_PATTERN.test(value) && !redactSensitiveText(value).redacted) return value;
@@ -84,7 +93,8 @@ export class GatewayEventStore {
     if (indexed) return indexed;
     const retained = this.#settlements.find((item) => item.sessionRef === sessionRef && item.operationRef === operationRef);
     if (!retained) return undefined;
-    const restored = { settledAt: retained.settledAt, settlement: retained.settlement, reasonCode: retained.reasonCode };
+    const restored = { settledAt: retained.settledAt, settlement: retained.settlement,
+      taskStatus: retained.taskStatus, reasonCode: retained.reasonCode };
     this.#settlementDecisions.set(key, restored);
     return restored;
   }
@@ -100,11 +110,16 @@ export class GatewayEventStore {
     if (this.#settlementDecision(sessionRef, operationRef)) return;
     this.#settlementDecisions.set(key, { settledAt: event.generatedAt,
       settlement: settlement as GatewaySettlementDecision["settlement"],
+      taskStatus: settlementTaskStatus(event.payload.taskStatus),
       reasonCode: settlement === "completed" ? null : String(event.payload.reasonCode) });
-    const retained = { sessionRef, operationRef, settledAt: event.generatedAt, sequence: event.sequence };
+    const messageRequestId = typeof event.payload.messageRequestId === "string" && OPAQUE_REF_PATTERN.test(event.payload.messageRequestId)
+      ? event.payload.messageRequestId : undefined;
+    const retained = { sessionRef, operationRef, ...(messageRequestId ? { messageRequestId } : {}),
+      settledAt: event.generatedAt, sequence: event.sequence };
     if (settlement !== "completed") {
       const outcome = settlement as GatewayTerminalSettlement["settlement"];
-      this.#settlements.push({ ...retained, settlement: outcome, reasonCode: settlementReason(outcome, event.payload.reasonCode) });
+      this.#settlements.push({ ...retained, settlement: outcome, taskStatus: settlementTaskStatus(event.payload.taskStatus),
+        reasonCode: settlementReason(outcome, event.payload.reasonCode) });
     }
     this.#pruneSettlements(now);
   }
@@ -112,6 +127,7 @@ export class GatewayEventStore {
   publish(kind: GatewayEventKind, payload: Record<string, unknown>, now = new Date()): GatewayProtocolEvent {
     if (!Number.isFinite(now.getTime())) throw new Error("gateway-event-time-invalid");
     if (kind === "operation.settled") {
+      payload = { ...payload, taskStatus: settlementTaskStatus(payload.taskStatus) };
       if (payload.settlement === "completed") payload = { ...payload, reasonCode: null };
       else {
         const settlement = ["blocked", "aborted", "error", "unknown"].includes(String(payload.settlement))
@@ -123,7 +139,8 @@ export class GatewayEventStore {
       if (typeof sessionRef === "string" && OPAQUE_REF_PATTERN.test(sessionRef)
         && typeof operationRef === "string" && OPAQUE_REF_PATTERN.test(operationRef)) {
         const canonical = this.#settlementDecision(sessionRef, operationRef);
-        if (canonical) payload = { ...payload, settlement: canonical.settlement, reasonCode: canonical.reasonCode };
+        if (canonical) payload = { ...payload, settlement: canonical.settlement,
+          taskStatus: canonical.taskStatus, reasonCode: canonical.reasonCode };
       }
     }
     this.#sequence += 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,10 @@ 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";
 
 const MAX_BUFFER = 65_536;
 const MAX_EVENTS = 128;
@@ -15,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, " ");
@@ -24,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;
@@ -67,87 +138,130 @@ 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;
   #eventCount = 0;
   #buffer = "";
   #truncated = false;
-  #started = false;
   #startListeners: Array<() => void> = [];
-  #settled = false;
   #runtimeRestartRequired = false;
   #lastMessageRef: string | null = null;
   #settlement: Settlement = { outcome: "unknown", reasonCode: "operation-settlement-unknown" };
   #forcedSettlement: Settlement | null = null;
   #lifecycleTerminationReasonCode: string | null = null;
-  #terminalEmitted = false;
   #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; }
+  get operationPhase(): SessionOperationPhase { return this.#lifecycle.phase; }
+  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 };
   }
   forceLifecycleTermination(reasonCode: string): void {
     this.#lifecycleTerminationReasonCode ??= reasonCode;
-    if (!this.#started) { this.#started = true; for (const resolve of this.#startListeners.splice(0)) resolve(); }
-    if (!this.#settled) { this.#settled = true; for (const resolve of this.#settleListeners.splice(0)) resolve(); }
+    const wasStarted = this.#lifecycle.started, wasSettled = this.#lifecycle.hostSettled;
+    this.#lifecycle.forceHostSettlement();
+    if (!wasStarted) for (const resolve of this.#startListeners.splice(0)) resolve();
+    if (!wasSettled) for (const resolve of this.#settleListeners.splice(0)) resolve();
+  }
+
+  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;
   }
 
-  constructor(options: { sessionRef: string; operationRef: string; events: GatewayEventStore }) {
-    this.sessionRef = options.sessionRef; this.operationRef = options.operationRef; this.#events = options.events;
+  #correlation(): { messageRequestId?: string } {
+    return this.messageRequestId ? { messageRequestId: this.messageRequestId } : {};
   }
 
   started(): Promise<void> {
-    if (this.#started) return Promise.resolve();
+    if (this.#lifecycle.started) return Promise.resolve();
     return new Promise((resolve) => this.#startListeners.push(resolve));
   }
 
   settled(): Promise<void> {
-    if (this.#settled) return Promise.resolve();
+    if (this.#lifecycle.hostSettled) return Promise.resolve();
     return new Promise((resolve) => this.#settleListeners.push(resolve));
   }
 
-  observe(event: any): void {
-    if (this.#terminalEmitted) return;
+  observe(event: any): SessionOperationObservation {
+    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");
     if (event?.type === "agent_start") {
-      this.#started = true; for (const resolve of this.#startListeners.splice(0)) resolve(); return;
+      return observation;
     }
     if (event?.type === "agent_settled") {
-      this.#settled = true; for (const resolve of this.#settleListeners.splice(0)) resolve(); return;
+      this.#settleActiveTools("operation-settled-before-tool-result");
+      return observation;
     }
     if (event?.type === "message_start" && event.message?.role === "assistant") {
-      this.#messageRef = ref("message"); this.#buffer = ""; return;
+      this.#messageRef = ref("message"); this.#buffer = ""; return observation;
     }
     if (event?.type === "message_update" && event.assistantMessageEvent?.type === "text_delta"
       && typeof event.assistantMessageEvent.delta === "string") {
       const remaining = MAX_BUFFER - this.#buffer.length;
-      if (remaining <= 0) { this.#truncated = true; return; }
+      if (remaining <= 0) { this.#truncated = true; return observation; }
       this.#buffer += event.assistantMessageEvent.delta.slice(0, remaining);
       if (event.assistantMessageEvent.delta.length > remaining) this.#truncated = true;
-      this.#flush(false); return;
+      this.#flush(false); return observation;
     }
     if (event?.type === "message_end" && event.message?.role === "assistant") {
-      this.#flush(true); this.#lastMessageRef = this.#messageRef; this.#settlement = assistantSettlement(event.message); return;
+      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 });
-      return;
+      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;
+      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 {
@@ -174,20 +288,43 @@ 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): void {
-    if (this.#terminalEmitted) return;
-    this.#terminalEmitted = true;
+  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" && sessionRevision === null) {
@@ -196,11 +333,12 @@ export class GatewaySessionStream {
       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.