@piagent/platform 1.6.0 → 1.6.1

package/packages/piagent-webui/dist/client/index.html

@@ -7,7 +7,7 @@
     <meta name="csp-nonce" content="__PIAGENT_CSP_NONCE__" />
     <meta name="piagent-webui-mode" content="__PIAGENT_WEBUI_MODE__" />
     <title>Piagent WebUI</title>
-    <script type="module" crossorigin src="/assets/index-DynIMe8I.js"></script>
+    <script type="module" crossorigin src="/assets/index-CgOEyRPG.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-BV-_03yl.css">
   </head>
   <body>

package/packages/piagent-webui/extension/piagent-webui.ts

@@ -446,7 +446,9 @@ export default function piagentWebUiExtension(pi: ExtensionAPI): void {
   pi.on("tool_execution_end", (event, ctx) => { publishDrafts(ctx, stream.toolEnded(event, bridge.snapshot())); bridgeSoft(() => lifecycle.observeToolEnd(ctx)); });
   pi.on("turn_end", (event, ctx) => publishDrafts(ctx, stream.turnEnded(event, bridge.snapshot())));
   pi.on("agent_settled", (_event, ctx) => {
-    publishDrafts(ctx, stream.agentSettled(bridge.snapshot(), typeof ctx.hasPendingMessages === "function" ? ctx.hasPendingMessages() : null));
+    const hasPendingMessages = typeof ctx.hasPendingMessages === "function" ? ctx.hasPendingMessages() : null;
+    publishDrafts(ctx, stream.agentSettled(bridge.snapshot(), hasPendingMessages));
+    if (hasPendingMessages === true) { publishPersisted(ctx); return; }
     const operationId = bridge.snapshot().identity?.agentOperationId ?? null;
     bridgeSoft(() => bridge.observeAgentSettled(ctx)); bridgeSoft(() => lifecycle.observeAgentSettled(ctx, operationId)); publishPersisted(ctx);
   });

package/packages/piagent-webui/extension/same-session-bridge.ts

@@ -317,7 +317,7 @@ export class SameSessionPiBridge {
   }
   observeAgentStart(ctx: ExtensionContext): void {
     if (!this.refresh(ctx) || !this.#binding || this.#binding.state !== "ready") return;
-    const pending = this.#pending;
+    const pending = this.#pending; if (this.#binding.identity.agentOperationId && !pending) return;
     const operationId = pending?.operationId ?? this.#revision("operation", ++this.#operationCounter, "external");
     this.#binding.identity.agentOperationId = operationId; this.#refresh(); this.#event("operation.started", { operationRef: operationId, commandId: pending?.command.commandId });
     const observedEntry = pending ? dispatchEntry(pending, ctx) : null;

package/packages/piagent-webui/extension/session-stream-adapter.ts

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 
 import { redactSensitiveText } from "../../piagent-core/extensions/redaction-core.js";
+import { classifyToolFailure, handledToolFailure } from "../../piagent-core/runtime/inspection/tool-failure-classification.ts";
 import type { RuntimeEventDraft, RuntimeEventRevision } from "../../piagent-core/runtime/inspection/runtime-event-store.ts";
 import type { BridgeIdentity, BridgeSnapshot } from "./same-session-bridge.ts";
 
@@ -35,6 +36,13 @@ function safeToolName(value: unknown): string {
   if (projected.redacted) return "redacted-tool";
   return projected.text.replace(/[^A-Za-z0-9._:-]/g, "-").replace(/^[^A-Za-z0-9]+/, "").slice(0, 128) || "tool";
 }
+function toolClassificationInput(value: unknown): { command: string } | undefined {
+  if (!value || typeof value !== "object") return undefined;
+  const direct = (value as { command?: unknown }).command;
+  const nested = (value as { args?: { command?: unknown } }).args?.command;
+  const command = typeof direct === "string" ? direct : typeof nested === "string" ? nested : null;
+  return command === null ? undefined : { command: command.slice(0, 8_192) };
+}
 function role(message: any): MessageRole | null {
   return message?.role === "user" ? "user" : message?.role === "assistant" ? "assistant" : message?.role === "toolResult" ? "tool-result" : null;
 }
@@ -68,10 +76,11 @@ function redaction(applied = false, truncated = false) { return { applied, value
 function identityReady(identity: BridgeIdentity | null): identity is BridgeIdentity & { agentOperationId: string } {
   return Boolean(identity?.agentOperationId);
 }
-function activityPayload(state: "started" | "progress" | "finished" | "failed", activityRef: string, toolName: string) {
+function activityPayload(state: "started" | "progress" | "finished" | "failed", activityRef: string, toolName: string,
+  reasonCode: string | null = null) {
   return { state, activityType: "tool", activityRef, toolName, inputDigest: null, outputDigest: null, preview: null, previewKind: "none",
     outputBytes: null, outputLines: null, exitCode: null, isError: state === "finished" ? false : state === "failed" ? true : null,
-    affectedFileRefs: [], criterionIds: [], verifierAttemptIds: [], reasonCode: state === "failed" ? "tool-execution-failed" : null };
+    affectedFileRefs: [], criterionIds: [], verifierAttemptIds: [], reasonCode };
 }
 
 export class PiSessionStreamAdapter {
@@ -81,12 +90,13 @@ export class PiSessionStreamAdapter {
   #activeByRole = new Map<MessageRole, ActiveMessage>();
   #lastMessageRef: string | null = null;
   #toolRefs = new Map<string, string>();
+  #toolInputs = new Map<string, { command: string } | undefined>();
   #lastToolProgress = new Map<string, number>();
 
   constructor(options: { now?: () => Date } = {}) { this.#now = options.now ?? (() => new Date()); }
   reset(): void {
     this.#turnIndex = null; this.#messageCounter = 0; this.#activeByRole.clear(); this.#lastMessageRef = null;
-    this.#toolRefs.clear(); this.#lastToolProgress.clear();
+    this.#toolRefs.clear(); this.#toolInputs.clear(); this.#lastToolProgress.clear();
   }
 
   #base(snapshot: BridgeSnapshot, sourceObservedAt?: unknown): Omit<RuntimeEventDraft, "kind" | "payload" | "evidence" | "redaction"> | null {
@@ -210,13 +220,14 @@ export class PiSessionStreamAdapter {
     const draft = this.#draft(snapshot, "turn.ended", { phase: "ended", finalMessageRef: this.#lastMessageRef, toolResultCount: count, stopReason: reason });
     return draft ? [draft] : [];
   }
-  toolStarted(event: { toolCallId?: unknown; toolName?: unknown }, snapshot: BridgeSnapshot): RuntimeEventDraft[] {
+  toolStarted(event: { toolCallId?: unknown; toolName?: unknown; args?: unknown }, snapshot: BridgeSnapshot): RuntimeEventDraft[] {
     if (typeof event.toolCallId !== "string" || !event.toolCallId) return [];
     const drafts = this.#activeByRole.get("assistant")
       ? this.#drainLines(snapshot, this.#activeByRole.get("assistant") as ActiveMessage, false) : [];
     const name = safeToolName(event.toolName);
     const ref = opaque("tool", [snapshot.identity?.sessionRef, event.toolCallId]), activityRef = opaque("activity", [snapshot.identity?.sessionRef, event.toolCallId]);
-    this.#toolRefs.set(event.toolCallId, ref); this.#lastToolProgress.set(event.toolCallId, 0);
+    this.#toolRefs.set(event.toolCallId, ref); this.#toolInputs.set(event.toolCallId, toolClassificationInput(event.args));
+    this.#lastToolProgress.set(event.toolCallId, 0);
     const draft = this.#draft(snapshot, "activity.started", activityPayload("started", activityRef, name), { toolCallId: ref });
     if (draft) drafts.push(draft);
     return drafts;
@@ -231,19 +242,31 @@ export class PiSessionStreamAdapter {
     const draft = this.#draft(snapshot, "activity.progress", activityPayload("progress", activityRef, name), { toolCallId: ref });
     return draft ? [draft] : [];
   }
-  toolEnded(event: { toolCallId?: unknown; toolName?: unknown; isError?: unknown }, snapshot: BridgeSnapshot): RuntimeEventDraft[] {
+  toolEnded(event: { toolCallId?: unknown; toolName?: unknown; result?: unknown; isError?: unknown }, snapshot: BridgeSnapshot): RuntimeEventDraft[] {
     if (typeof event.toolCallId !== "string") return [];
     const ref = this.#toolRefs.get(event.toolCallId); if (!ref) return [];
     const name = safeToolName(event.toolName);
-    const activityRef = opaque("activity", [snapshot.identity?.sessionRef, event.toolCallId]), state = event.isError === true ? "failed" : "finished";
-    this.#toolRefs.delete(event.toolCallId); this.#lastToolProgress.delete(event.toolCallId);
-    const draft = this.#draft(snapshot, `activity.${state}`, activityPayload(state, activityRef, name), { toolCallId: ref });
+    const reasonCode = classifyToolFailure(name, event.isError === true, event.result, this.#toolInputs.get(event.toolCallId));
+    const state = (event.isError === true || reasonCode !== null) && !handledToolFailure(reasonCode) ? "failed" : "finished";
+    const activityRef = opaque("activity", [snapshot.identity?.sessionRef, event.toolCallId]);
+    this.#toolRefs.delete(event.toolCallId); this.#toolInputs.delete(event.toolCallId); this.#lastToolProgress.delete(event.toolCallId);
+    const draft = this.#draft(snapshot, `activity.${state}`, activityPayload(state, activityRef, name, reasonCode), { toolCallId: ref });
     return draft ? [draft] : [];
   }
   agentSettled(snapshot: BridgeSnapshot, hasPendingMessages: boolean | null): RuntimeEventDraft[] {
+    // A queued follow-up belongs to the same logical operation. Do not emit a
+    // terminal edge or clear stream identity between recovery turns.
+    if (hasPendingMessages === true) return [];
     const value = hasPendingMessages === null ? { state: "unknown", value: null, reasonCode: "queue-fact-unavailable" }
       : { state: "known", value: hasPendingMessages, reasonCode: null };
-    const draft = this.#draft(snapshot, "agent-operation.settled", { settlement: "completed", lastStopReason: null, hasPendingMessages: value });
+    // Host-idle only proves that this agent operation stopped producing turns.
+    // A governed task is successful only after its durable contract is terminal.
+    // Fail closed here so a missed/late completion hook cannot paint an open
+    // task as completed in the WebUI.
+    const governedTaskOpen = Boolean(snapshot.identity?.taskRunId) && snapshot.taskState !== "terminal";
+    const draft = this.#draft(snapshot, "agent-operation.settled", {
+      settlement: governedTaskOpen ? "unknown" : "completed", lastStopReason: null, hasPendingMessages: value
+    });
     this.reset(); return draft ? [draft] : [];
   }
 }

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

@@ -3,6 +3,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 { SessionOperationLifecycle, type SessionOperationObservation,
+  type SessionOperationPhase, type SessionOperationRetryPolicyOptions } from "./session-operation-lifecycle.ts";
 
 const MAX_BUFFER = 65_536;
 const MAX_EVENTS = 128;
@@ -73,20 +75,20 @@ export class GatewaySessionStream {
   #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 #lifecycle: SessionOperationLifecycle;
 
   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 }; }
   markError(reasonCode = "operation-failed"): void {
@@ -94,60 +96,70 @@ export class GatewaySessionStream {
   }
   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; events: GatewayEventStore }) {
+  constructor(options: { sessionRef: string; operationRef: string; events: GatewayEventStore;
+    retryPolicy?: SessionOperationRetryPolicyOptions }) {
     this.sessionRef = options.sessionRef; this.operationRef = options.operationRef; this.#events = options.events;
+    this.#lifecycle = new SessionOperationLifecycle({ operationRef: options.operationRef, retryPolicy: options.retryPolicy });
   }
 
   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 (!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;
+      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;
+      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);
     }
+    return observation;
   }
 
   #flush(final: boolean): void {
@@ -180,9 +192,8 @@ export class GatewaySessionStream {
     }
   }
 
-  complete(sessionRevision: string | null): void {
-    if (this.#terminalEmitted) return;
-    this.#terminalEmitted = true;
+  complete(sessionRevision: string | null, taskOutcome: string | null = null): void {
+    if (!this.#lifecycle.markTerminal()) return;
     this.#flush(true);
     let settlement = this.#forcedSettlement ?? (this.#runtimeRestartRequired
       ? { outcome: "unknown" as const, reasonCode: "runtime-restart-required" }
@@ -190,6 +201,11 @@ export class GatewaySessionStream {
     const messageRef = this.#lastMessageRef ?? this.#messageRef;
     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.

package/packages/piagent-webui/gateway/session-operation-lifecycle.ts

@@ -0,0 +1,237 @@
+import { hasVisibleText } from "../shared/text-visibility.ts";
+
+export type SessionOperationPhase = "pending" | "running" | "retry" | "compaction" | "settled";
+
+export type SessionOperationRetryPolicy = Readonly<{
+  maximumAttempts: number;
+  maximumDelayMs: number;
+}>;
+
+export type SessionOperationRetryPolicyOptions = Partial<SessionOperationRetryPolicy>;
+
+export type SessionOperationObservation = Readonly<{
+  accepted: boolean;
+  phase: SessionOperationPhase;
+  retry: "none" | "allowed" | "abort";
+  reasonCode: string | null;
+}>;
+
+const DEFAULT_RETRY_POLICY: SessionOperationRetryPolicy = Object.freeze({
+  // Pi's provider retry is useful before a response exists, but a long retry
+  // chain burns quota and keeps the browser in Working. One automatic retry
+  // absorbs an ordinary transient failure without replaying a persistent one.
+  maximumAttempts: 1,
+  maximumDelayMs: 8_000
+});
+
+function boundedInteger(value: unknown, fallback: number, minimum: number, maximum: number): number {
+  if (value === undefined) return fallback;
+  if (!Number.isSafeInteger(value) || Number(value) < minimum || Number(value) > maximum) {
+    throw new Error("session-operation-retry-policy-invalid");
+  }
+  return Number(value);
+}
+
+export function sessionOperationRetryPolicy(
+  options: SessionOperationRetryPolicyOptions = {}
+): SessionOperationRetryPolicy {
+  return Object.freeze({
+    maximumAttempts: boundedInteger(options.maximumAttempts, DEFAULT_RETRY_POLICY.maximumAttempts, 0, 10),
+    maximumDelayMs: boundedInteger(options.maximumDelayMs, DEFAULT_RETRY_POLICY.maximumDelayMs, 0, 300_000)
+  });
+}
+
+function correlationRef(event: any): string | null {
+  for (const key of ["operationRef", "agentOperationId", "operationId"]) {
+    if (typeof event?.[key] === "string" && event[key]) return event[key];
+  }
+  return null;
+}
+
+function visibleAssistantContent(message: any): boolean {
+  if (typeof message?.content === "string") return hasVisibleText(message.content);
+  if (!Array.isArray(message?.content)) return false;
+  return message.content.some((item: any) => {
+    if (item?.type === "text") return hasVisibleText(item.text);
+    // Images and every model-emitted tool/server-tool block are observable
+    // output even when they do not contain user-visible text.
+    return ["image", "image_url", "toolCall", "tool_call", "tool_use", "server_tool_use"]
+      .includes(String(item?.type ?? ""));
+  });
+}
+
+function attempt(value: unknown): number | null {
+  return Number.isSafeInteger(value) && Number(value) >= 1 ? Number(value) : null;
+}
+
+function delay(value: unknown): number | null {
+  return Number.isSafeInteger(value) && Number(value) >= 0 ? Number(value) : null;
+}
+
+/**
+ * Operation-local authority for provider retry, compaction and settlement.
+ *
+ * Pi's pinned host owns the actual provider retry. This state machine owns the
+ * stricter Piagent admission decision and is shared by the Gateway stream and
+ * runtime supervisor. It never treats compaction as a provider retry, and it
+ * fails closed once assistant output or a tool call makes replay unsafe.
+ */
+export class SessionOperationLifecycle {
+  readonly operationRef: string;
+  readonly retryPolicy: SessionOperationRetryPolicy;
+  #phase: SessionOperationPhase = "pending";
+  #started = false;
+  #hostSettled = false;
+  #terminal = false;
+  #visibleAssistantOutput = false;
+  #toolCallObserved = false;
+  #lastRetryAttempt = 0;
+  #activeRetryAttempt: number | null = null;
+  #retryAbortRequired = false;
+
+  constructor(options: {
+    operationRef: string;
+    retryPolicy?: SessionOperationRetryPolicyOptions | SessionOperationRetryPolicy;
+  }) {
+    this.operationRef = options.operationRef;
+    this.retryPolicy = sessionOperationRetryPolicy(options.retryPolicy);
+  }
+
+  get phase(): SessionOperationPhase { return this.#phase; }
+  get started(): boolean { return this.#started; }
+  get hostSettled(): boolean { return this.#hostSettled; }
+  get terminal(): boolean { return this.#terminal; }
+  get replayUnsafe(): boolean { return this.#visibleAssistantOutput || this.#toolCallObserved; }
+  get retryAbortRequired(): boolean { return this.#retryAbortRequired; }
+
+  forceHostSettlement(): void {
+    this.#started = true;
+    this.#hostSettled = true;
+    this.#phase = "settled";
+  }
+
+  markTerminal(): boolean {
+    if (this.#terminal) return false;
+    this.#terminal = true;
+    this.#hostSettled = true;
+    this.#phase = "settled";
+    return true;
+  }
+
+  observe(event: any): SessionOperationObservation {
+    if (this.#terminal || this.#hostSettled) return this.#ignored("operation-event-after-settlement");
+    const correlated = correlationRef(event);
+    if (correlated && correlated !== this.operationRef) return this.#ignored("operation-correlation-mismatch");
+    const type = String(event?.type ?? "");
+
+    if (type === "agent_start") {
+      this.#started = true;
+      this.#phase = "running";
+      return this.#accepted();
+    }
+    if (type === "agent_settled") {
+      this.#started = true;
+      this.#hostSettled = true;
+      this.#phase = "settled";
+      return this.#accepted();
+    }
+
+    // Direct stream fixtures and some deferred command hosts begin with a
+    // message/tool event. Treat that as an observed start while still refusing
+    // uncorrelated retry/compaction lifecycle events before any operation work.
+    if (["message_start", "message_update", "message_end", "tool_execution_start",
+      "tool_execution_update", "tool_execution_end", "turn_start", "turn_end"].includes(type)) {
+      this.#started = true;
+      if (this.#phase === "pending") this.#phase = "running";
+    }
+
+    if (type === "message_update") {
+      const update = event?.assistantMessageEvent;
+      if (update?.type === "text_delta" && hasVisibleText(update.delta)) this.#visibleAssistantOutput = true;
+      if (visibleAssistantContent(event?.message)) this.#visibleAssistantOutput = true;
+      return this.#accepted();
+    }
+    if (type === "message_end" && event?.message?.role === "assistant") {
+      if (visibleAssistantContent(event.message)) this.#visibleAssistantOutput = true;
+      return this.#accepted();
+    }
+    if (type === "tool_execution_start") {
+      this.#toolCallObserved = true;
+      return this.#accepted();
+    }
+
+    if (type === "agent_end" && event?.willRetry === true && this.replayUnsafe) {
+      return this.#abortRetry("automatic-retry-replay-unsafe");
+    }
+    if (type === "auto_retry_start") return this.#retryStarted(event);
+    if (type === "auto_retry_end") return this.#retryEnded(event);
+
+    // Summarization retries belong to compaction and never consume or inherit
+    // the provider-turn retry budget.
+    if (type === "compaction_start") {
+      if (!this.#started) return this.#ignored("operation-event-before-start");
+      if (this.#phase === "retry") this.#retryAbortRequired = true;
+      this.#phase = "compaction";
+      return this.#retryAbortRequired
+        ? this.#abortRetry("automatic-retry-compaction-overlap")
+        : this.#accepted();
+    }
+    if (type === "compaction_end") {
+      if (this.#phase !== "compaction") return this.#ignored("compaction-event-stale");
+      this.#phase = "running";
+      return this.#accepted();
+    }
+    if (["summarization_retry_scheduled", "summarization_retry_attempt_start",
+      "summarization_retry_finished"].includes(type)) {
+      return this.#phase === "compaction" ? this.#accepted() : this.#ignored("compaction-event-stale");
+    }
+    return this.#accepted();
+  }
+
+  #retryStarted(event: any): SessionOperationObservation {
+    if (!this.#started) return this.#ignored("operation-event-before-start");
+    const currentAttempt = attempt(event?.attempt), currentDelay = delay(event?.delayMs);
+    if (currentAttempt === null || currentDelay === null) return this.#abortRetry("automatic-retry-metadata-invalid");
+    if (currentAttempt === this.#lastRetryAttempt) return this.#ignored("automatic-retry-event-duplicate");
+    if (currentAttempt !== this.#lastRetryAttempt + 1) {
+      this.#activeRetryAttempt = currentAttempt;
+      this.#phase = "retry";
+      return this.#abortRetry("automatic-retry-attempt-stale");
+    }
+    this.#lastRetryAttempt = currentAttempt;
+    this.#activeRetryAttempt = currentAttempt;
+    if (this.#phase === "compaction") return this.#abortRetry("automatic-retry-compaction-overlap");
+    this.#phase = "retry";
+    if (this.replayUnsafe) return this.#abortRetry("automatic-retry-replay-unsafe");
+    if (currentAttempt > this.retryPolicy.maximumAttempts) return this.#abortRetry("automatic-retry-attempt-limit");
+    if (currentDelay > this.retryPolicy.maximumDelayMs) return this.#abortRetry("automatic-retry-delay-limit");
+    return { accepted: true, phase: this.#phase, retry: "allowed", reasonCode: null };
+  }
+
+  #retryEnded(event: any): SessionOperationObservation {
+    const currentAttempt = attempt(event?.attempt);
+    if (currentAttempt === null || currentAttempt !== this.#activeRetryAttempt) {
+      return this.#ignored("automatic-retry-event-stale");
+    }
+    this.#activeRetryAttempt = null;
+    // Keep the highest attempt for the whole logical operation so hosts that
+    // emit retry_end between attempts still have a monotonic sequence. Keep an
+    // abort latched too: retry_end can arrive synchronously before the
+    // supervisor's cancellation microtask observes the host AbortController.
+    if (this.#phase === "retry") this.#phase = "running";
+    return this.#accepted();
+  }
+
+  #abortRetry(reasonCode: string): SessionOperationObservation {
+    this.#retryAbortRequired = true;
+    return { accepted: true, phase: this.#phase, retry: "abort", reasonCode };
+  }
+
+  #accepted(): SessionOperationObservation {
+    return { accepted: true, phase: this.#phase, retry: "none", reasonCode: null };
+  }
+
+  #ignored(reasonCode: string): SessionOperationObservation {
+    return { accepted: false, phase: this.#phase, retry: "none", reasonCode };
+  }
+}

package/packages/piagent-webui/gateway/session-operation-retry-control.ts

@@ -0,0 +1,38 @@
+type RetryObservation = { retry?: unknown } | null | undefined;
+
+function invoke(action: (() => unknown) | null): void {
+  if (!action) return;
+  try {
+    const result = action();
+    if (result && typeof (result as PromiseLike<unknown>).then === "function") {
+      void Promise.resolve(result).catch(() => undefined);
+    }
+  } catch { /* the operation watchdog remains the terminal authority */ }
+}
+
+/**
+ * Cancels a host-owned provider retry without replaying the prompt. Pinned Pi
+ * creates its retry AbortController immediately after auto_retry_start is
+ * emitted, so the microtask always runs before even a zero-millisecond timer.
+ */
+export class SessionOperationRetryCancellation {
+  readonly #session: any;
+  #fallbackIssued = false;
+
+  constructor(session: any) { this.#session = session; }
+
+  observe(observation: RetryObservation): void {
+    if (observation?.retry !== "abort") return;
+    if (typeof this.#session?.abortRetry === "function") {
+      const cancel = () => invoke(() => this.#session.abortRetry());
+      cancel();
+      queueMicrotask(cancel);
+      return;
+    }
+    // Unknown hosts fail closed once. Replaying a tool-capable turn is more
+    // dangerous than ending the logical operation with an explicit error.
+    if (this.#fallbackIssued || typeof this.#session?.abort !== "function") return;
+    this.#fallbackIssued = true;
+    invoke(() => this.#session.abort());
+  }
+}

package/packages/piagent-webui/gateway/session-operation-watchdog.ts

@@ -1,3 +1,5 @@
+import { SessionOperationRetryCancellation } from "./session-operation-retry-control.ts";
+
 export type SessionOperationDeadlineReason = "operation-inactivity-timeout" | "operation-deadline-exceeded";
 
 export type SessionOperationDeadlinePolicy = Readonly<{
@@ -113,10 +115,15 @@ export class SessionOperationWatchdog {
 export function armSessionOperationWatchdog(options: {
   watchdog: SessionOperationWatchdog;
   subscribe(listener: (event: unknown) => void): unknown;
-  observe(event: unknown): void;
+  observe(event: unknown): unknown;
+  retrySession?: any;
   expire(reason: SessionOperationDeadlineReason): void;
 }): () => void {
-  const unsubscribe = options.subscribe((event) => { options.watchdog.progress(); options.observe(event); });
+  const retry = new SessionOperationRetryCancellation(options.retrySession);
+  const unsubscribe = options.subscribe((event) => {
+    options.watchdog.progress();
+    retry.observe(options.observe(event) as { retry?: unknown } | null | undefined);
+  });
   if (typeof unsubscribe !== "function") throw new Error("session-operation-subscribe-invalid");
   try { options.watchdog.start(options.expire); }
   catch (error) { try { unsubscribe(); } catch { /* authority is quarantined by the caller */ } throw error; }

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

@@ -9,8 +9,7 @@ import { SessionLeaseStore, type SessionLeaseSnapshot } from "./session-lease-st
 import { GatewayEventStore } from "./gateway-events.ts";
 import { GatewaySessionStream } from "./gateway-session-stream.ts";
 import { executePermissionCommand, executeRuntimeCommand } from "./runtime-session-controls.ts";
-import { configureSessionOptions, effectiveModelRef, effectiveThinkingLevel,
-  type EffectiveSessionOptions } from "./session-effective-options.ts";
+import { configureSessionOptions, effectiveModelRef, effectiveThinkingLevel, type EffectiveSessionOptions } from "./session-effective-options.ts";
 import { waitForOperationStart } from "./session-operation-start.ts";
 import { armSessionOperationWatchdog, bestEffortUnsubscribe, boundedResult, sessionOperationDeadlinePolicy, SessionOperationWatchdog, terminateWatchedSessionOperation,
   type SessionOperationDeadlinePolicy, type SessionOperationWatchdogOptions } from "./session-operation-watchdog.ts";
@@ -133,7 +132,7 @@ export class SessionRuntimeSupervisor {
     if (this.#active.has(sessionRef)) throw new Error("session-owner-conflict");
     const runtimeInstanceRef = `runtime_${randomBytes(24).toString("base64url")}`;
     const prior = this.#leases.inspect(sessionRef);
-    if (prior.state === "gateway-owned" || prior.state === "terminal-owned") {
+    if (prior.state === "gateway-owned" || prior.state === "terminal-owned" || prior.state === "recovery-required") {
       try { this.#leases.releaseDeadOwnerForExplicitRecovery(sessionRef); } catch { /* live or unprovable owners stay authoritative */ }
     }
     const lease = this.#leases.acquire(sessionRef, this.#gatewayInstanceRef, runtimeInstanceRef);
@@ -254,7 +253,7 @@ export class SessionRuntimeSupervisor {
     const watchdog = new SessionOperationWatchdog(this.#operationDeadlinePolicy);
     active.operationRef = operationRef; active.stream = stream; active.watchdog = watchdog; active.lastSessionRevision = sessionRevision;
     try {
-      active.unsubscribe = armSessionOperationWatchdog({ watchdog, subscribe: (listener) => session.subscribe(listener),
+      active.unsubscribe = armSessionOperationWatchdog({ watchdog, subscribe: (listener) => session.subscribe(listener), retrySession: session,
         observe: (event) => stream.observe(event), expire: (reasonCode) => { void this.#terminateOperation(sessionRef,
           operationRef, "error", reasonCode, reasonCode, true).catch(() => undefined); } });
     } catch (error) { stream.markError("session-operation-start-failed");
@@ -468,11 +467,13 @@ export class SessionRuntimeSupervisor {
     } catch { /* Canonical refresh failure cannot be replaced by an invented revision. */ }
     if (this.#active.get(sessionRef) !== active || active.operationRef !== operationRef) return;
     if (this.ownership(sessionRef).state !== "gateway-owned") { stream.markError("session-owner-continuity-lost"); await this.#quarantineRuntime(sessionRef, operationRef, active, stream, "session-owner-continuity-lost"); return; }
-    active.operationRef = null;
+    // The pre-clear projection is stale; derive post-settlement liveness from exact ownership.
+    active.operationRef = null; const settledLiveState = this.ownership(sessionRef).liveState;
     if (projection) active.lastSessionRevision = projection.sessionRevision;
-    stream.complete(projection?.sessionRevision ?? null);
+    const taskOutcome = activeSessionTask(active.info.cwd, active.info.id)?.trace?.outcome ?? null;
+    stream.complete(projection?.sessionRevision ?? null, taskOutcome);
     if (projection) this.#events.publish("runtime.changed", { sessionRef, sessionRevision: projection.sessionRevision,
-      liveState: restartRequired ? "uncertain" : projection.liveState, operationRef: null,
+      liveState: restartRequired ? "uncertain" : settledLiveState, operationRef: null,
       reasonCode: restartRequired ? "runtime-restart-required" : null });
     if (this.#active.get(sessionRef) === active) { active.completion = null;
       if (!active.watchdog?.terminating) { active.stream = null; active.watchdog = null; active.settling = false; } }

package/packages/piagent-webui/ownership/session-lease-store.ts

@@ -237,8 +237,11 @@ export class SessionLeaseStore {
     if (!Number.isFinite(now.getTime())) throw new Error("session-lease-input-invalid");
     return this.#withMutationLock(sessionRef, () => {
       const current = this.inspect(sessionRef);
-      const pid = current.state === "terminal-owned" ? terminalOwnerPid(current.gatewayInstanceRef)
-        : current.state === "gateway-owned" ? gatewayOwnerPid(current.gatewayInstanceRef) : null;
+      const terminalOwner = current.state === "terminal-owned"
+        || (current.state === "recovery-required" && current.gatewayInstanceRef?.startsWith(TERMINAL_OWNER_PREFIX));
+      const pid = terminalOwner ? terminalOwnerPid(current.gatewayInstanceRef)
+        : current.state === "gateway-owned" || current.state === "recovery-required"
+          ? gatewayOwnerPid(current.gatewayInstanceRef) : null;
       if (!pid || processAlive(pid)) throw new Error("session-owner-not-proven-dead");
       this.#append(sessionRef, { recordedAt: now.toISOString(), sessionRef, event: "recovery-required", ownerEpoch: current.ownerEpoch!,
         gatewayInstanceRef: current.gatewayInstanceRef!, runtimeInstanceRef: current.runtimeInstanceRef!, reasonCode: "owner-process-exited" });