@piagent/platform 1.5.5 → 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-BZRFw1u6.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-events.ts

@@ -1,5 +1,7 @@
+import { redactSensitiveText } from "../../piagent-core/security/sensitive-data.js";
+
 export type GatewayEventKind = "catalog.changed" | "session.changed" | "runtime.changed" | "message.delta"
-  | "message.completed" | "tool.started" | "tool.completed";
+  | "message.completed" | "operation.settled" | "tool.started" | "tool.completed";
 
 export type GatewayProtocolEvent = {
   schemaVersion: 1;
@@ -12,16 +14,47 @@ export type GatewayProtocolEvent = {
   payload: Record<string, unknown>;
 };
 
+export type GatewayTerminalSettlement = {
+  sessionRef: string;
+  operationRef: string;
+  settlement: "blocked" | "aborted" | "error" | "unknown";
+  reasonCode: string;
+  settledAt: string;
+  sequence: number;
+};
+
+const OPAQUE_REF_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,159}$/;
+const REASON_CODE_PATTERN = /^[a-z0-9][a-z0-9.-]{0,95}$/;
+const TERMINAL_SETTLEMENTS = new Set(["completed", "blocked", "aborted", "error", "unknown"]);
+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 };
+
+function settlementReason(settlement: GatewayTerminalSettlement["settlement"], value: unknown): string {
+  if (typeof value === "string" && REASON_CODE_PATTERN.test(value) && !redactSensitiveText(value).redacted) return value;
+  if (settlement === "aborted") return "operation-aborted";
+  if (settlement === "blocked") return "operation-blocked";
+  if (settlement === "error") return "operation-failed";
+  return "operation-settlement-unknown";
+}
+
 export class GatewayEventStore {
   readonly #maximumCount: number;
   readonly #maximumAgeMs: number;
+  readonly #settlementDecisionCount: number;
   #events: GatewayProtocolEvent[] = [];
+  #settlements: GatewayTerminalSettlement[] = [];
+  #settlementDecisions = new Map<string, GatewaySettlementDecision>();
   #sequence = 0;
   #listeners = new Set<(event: GatewayProtocolEvent) => void>();
 
-  constructor(options: { maximumCount?: number; maximumAgeMs?: number } = {}) {
+  constructor(options: { maximumCount?: number; maximumAgeMs?: number; settlementDecisionCount?: number } = {}) {
     this.#maximumCount = Math.max(1, Math.min(10_000, options.maximumCount ?? 1_000));
     this.#maximumAgeMs = Math.max(1_000, Math.min(24 * 60 * 60_000, options.maximumAgeMs ?? 60 * 60_000));
+    this.#settlementDecisionCount = Math.max(1,
+      Math.min(MAX_SETTLEMENT_DECISION_COUNT, Math.floor(options.settlementDecisionCount ?? MAX_SETTLEMENT_DECISION_COUNT)));
   }
 
   get stateVersion(): number { return this.#sequence; }
@@ -31,14 +64,74 @@ export class GatewayEventStore {
     while (this.#events.length > this.#maximumCount || this.#events[0] && Date.parse(this.#events[0].generatedAt) < cutoff) this.#events.shift();
   }
 
+  #pruneSettlements(now: number): void {
+    const cutoff = now - SETTLEMENT_RETENTION_MS;
+    this.#settlements = this.#settlements.filter((item) => Date.parse(item.settledAt) >= cutoff);
+    if (this.#settlements.length > SETTLEMENT_RETENTION_COUNT) {
+      this.#settlements.splice(0, this.#settlements.length - SETTLEMENT_RETENTION_COUNT);
+    }
+    for (const [key, decision] of this.#settlementDecisions) {
+      if (Date.parse(decision.settledAt) < cutoff) this.#settlementDecisions.delete(key);
+    }
+    while (this.#settlementDecisions.size > this.#settlementDecisionCount) {
+      this.#settlementDecisions.delete(this.#settlementDecisions.keys().next().value as string);
+    }
+  }
+
+  #settlementDecision(sessionRef: string, operationRef: string): GatewaySettlementDecision | undefined {
+    const key = `${sessionRef}\u0000${operationRef}`;
+    const indexed = this.#settlementDecisions.get(key);
+    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 };
+    this.#settlementDecisions.set(key, restored);
+    return restored;
+  }
+
+  #recordSettlement(event: GatewayProtocolEvent, now: number): void {
+    if (event.kind !== "operation.settled") return;
+    const sessionRef = event.payload.sessionRef, operationRef = event.payload.operationRef, settlement = event.payload.settlement;
+    if (typeof sessionRef !== "string" || !OPAQUE_REF_PATTERN.test(sessionRef)
+      || typeof operationRef !== "string" || !OPAQUE_REF_PATTERN.test(operationRef)
+      || typeof settlement !== "string" || !TERMINAL_SETTLEMENTS.has(settlement)) return;
+    this.#pruneSettlements(now);
+    const key = `${sessionRef}\u0000${operationRef}`;
+    if (this.#settlementDecision(sessionRef, operationRef)) return;
+    this.#settlementDecisions.set(key, { settledAt: event.generatedAt,
+      settlement: settlement as GatewaySettlementDecision["settlement"],
+      reasonCode: settlement === "completed" ? null : String(event.payload.reasonCode) });
+    const retained = { sessionRef, operationRef, 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.#pruneSettlements(now);
+  }
+
   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") {
+      if (payload.settlement === "completed") payload = { ...payload, reasonCode: null };
+      else {
+        const settlement = ["blocked", "aborted", "error", "unknown"].includes(String(payload.settlement))
+          ? payload.settlement as GatewayTerminalSettlement["settlement"] : "unknown";
+        payload = { ...payload, settlement, reasonCode: settlementReason(settlement, payload.reasonCode) };
+      }
+      this.#pruneSettlements(now.getTime());
+      const sessionRef = payload.sessionRef, operationRef = payload.operationRef;
+      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 };
+      }
+    }
     this.#sequence += 1;
     const event: GatewayProtocolEvent = {
       schemaVersion: 1, version: "piagent-gateway-protocol-v1", messageType: "event",
       sequence: this.#sequence, stateVersion: this.#sequence, generatedAt: now.toISOString(), kind, payload
     };
-    this.#events.push(event); this.#prune(now.getTime());
+    this.#events.push(event); this.#prune(now.getTime()); this.#recordSettlement(event, now.getTime());
     for (const listener of this.#listeners) { try { listener(event); } catch { /* observers cannot block truth */ } }
     return event;
   }
@@ -48,10 +141,21 @@ export class GatewayEventStore {
     return () => { this.#listeners.delete(listener); };
   }
 
+  recentOperationSettlements(maximum = 100, now = new Date()): GatewayTerminalSettlement[] {
+    if (!Number.isFinite(now.getTime())) throw new Error("gateway-settlement-time-invalid");
+    const limit = Math.max(0, Math.min(100, Math.floor(maximum)));
+    if (limit === 0) return [];
+    this.#pruneSettlements(now.getTime());
+    return [...this.#settlements].sort((left, right) => right.sequence - left.sequence).slice(0, limit).map((item) => ({ ...item }));
+  }
+
   replay(after: number | null): { state: "current" | "resync-required"; events: GatewayProtocolEvent[]; earliestSequence: number; currentSequence: number } {
     this.#prune(Date.now());
-    const earliestSequence = this.#events[0]?.sequence ?? this.#sequence;
-    if (after !== null && after < Math.max(0, earliestSequence - 1)) {
+    // An empty retained ring after pruning contains no event at `#sequence`.
+    // Treat the next sequence as the retention boundary so a client one event
+    // behind must resync instead of silently receiving an empty replay.
+    const earliestSequence = this.#events[0]?.sequence ?? Math.min(Number.MAX_SAFE_INTEGER, this.#sequence + 1);
+    if (after !== null && (after > this.#sequence || after < Math.max(0, earliestSequence - 1))) {
       return { state: "resync-required", events: [], earliestSequence, currentSequence: this.#sequence };
     }
     return { state: "current", events: after === null ? [] : this.#events.filter((event) => event.sequence > after), earliestSequence,

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

@@ -21,6 +21,7 @@ import { SessionMetadataStore } from "./session-metadata-store.ts";
 import { GatewayProtocolService } from "./gateway-protocol-service.ts";
 import { SessionLeaseStore } from "./session-lease-store.ts";
 import { SessionRuntimeSupervisor } from "./session-runtime-supervisor.ts";
+import { buildSessionLiveState } from "./session-live-state.ts";
 import { SessionCommandStore } from "./session-command-store.ts";
 import { SessionCommandController } from "./session-command-controller.ts";
 import { RuntimeCommandController } from "./runtime-command-controller.ts";
@@ -192,6 +193,8 @@ export async function startPiagentGateway(options: {
       mode: "gateway",
       readCapabilities: () => capabilities(gatewayInstanceRef, true),
       readSessionCatalog: readCatalog,
+      readSessionLiveState: () => buildSessionLiveState({ gatewayInstanceRef, eventSequence: events.stateVersion,
+        operations: runtimes!.currentOperations(), settlements: events.recentOperationSettlements() }),
       readSessionCreationOptions: () => inspections.creationOptions(),
       readSessionModel: (sessionRef) => inspections.provider(sessionRef),
       readSessionConnections: (sessionRef) => inspections.connections(sessionRef),

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

@@ -1,16 +1,24 @@
 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;
 const MAX_DELTA = 16_384;
 const PRIVATE_BEGIN = /-----BEGIN [A-Z ]*PRIVATE KEY-----/;
 const PRIVATE_END = /-----END [A-Z ]*PRIVATE KEY-----/;
+const RUNTIME_DRIFT = /Installed Piagent runtime changed (?:during this session|while the capability lock was being re-pinned)/i;
+const COMPLETION_GATE = /^\[Piagent completion gate: (CONTINUING|NOT APPROVED)\]/i;
+
+export type GatewayOperationSettlement = "completed" | "blocked" | "aborted" | "error" | "unknown";
+type Settlement = { outcome: GatewayOperationSettlement; reasonCode: string | null };
 
 function clean(value: unknown): string {
-  return String(value ?? "").replace(/\u001b(?:[@-_]|\[[0-?]*[ -/]*[@-~])/g, "")
+  return String(value ?? "").replace(/\u001b(?:\[[0-?]*[ -/]*[@-~]|[@-_])/g, "")
     .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, " ");
 }
 function safeTool(value: unknown): string {
@@ -19,6 +27,44 @@ function safeTool(value: unknown): string {
   return safe.text.replace(/[^A-Za-z0-9._:-]/g, "-").replace(/^[^A-Za-z0-9]+/, "").slice(0, 160) || "tool";
 }
 function ref(prefix: string): string { return `${prefix}_${randomBytes(18).toString("base64url")}`; }
+function messageText(message: any): string {
+  if (typeof message?.content === "string") return message.content;
+  if (!Array.isArray(message?.content)) return "";
+  return message.content.filter((item: any) => item?.type === "text" && typeof item.text === "string")
+    .map((item: any) => item.text).join("\n");
+}
+function assistantSettlement(message: any): Settlement {
+  const stopReason = String(message?.stopReason ?? "");
+  if (stopReason === "aborted") return { outcome: "aborted", reasonCode: "operation-aborted" };
+  if (stopReason === "error") return { outcome: "error", reasonCode: "assistant-response-failed" };
+  if (stopReason === "length") return { outcome: "error", reasonCode: "assistant-output-incomplete" };
+  const gate = COMPLETION_GATE.exec(messageText(message).trimStart());
+  if (gate) return { outcome: "blocked", reasonCode: gate[1]?.toUpperCase() === "CONTINUING"
+    ? "completion-gate-continuing" : "completion-gate-not-approved" };
+  if (stopReason === "stop") return hasVisibleText(redactSensitiveText(clean(messageText(message))).text)
+    ? { outcome: "completed", reasonCode: null }
+    : { outcome: "unknown", reasonCode: "assistant-message-empty" };
+  if (["toolUse", "pending", "deferred"].includes(stopReason)) return { outcome: "unknown", reasonCode: "assistant-message-intermediate" };
+  return { outcome: "unknown", reasonCode: "operation-settlement-unknown" };
+}
+
+function containsRuntimeDrift(value: unknown, depth = 0, remaining = { value: 16_384 }): boolean {
+  if (depth > 5 || remaining.value <= 0 || value === null || value === undefined) return false;
+  if (typeof value === "string") {
+    const text = value.slice(0, remaining.value); remaining.value -= text.length;
+    return RUNTIME_DRIFT.test(text);
+  }
+  if (Array.isArray(value)) return value.some((item) => containsRuntimeDrift(item, depth + 1, remaining));
+  if (typeof value !== "object") return false;
+  const record = value as Record<string, unknown>;
+  return ["reason", "message", "text", "content", "result", "details"]
+    .some((key) => containsRuntimeDrift(record[key], depth + 1, remaining));
+}
+
+export function runtimeRestartReasonCode(event: unknown): "runtime-restart-required" | null {
+  if (!event || typeof event !== "object" || (event as Record<string, unknown>).isError !== true) return null;
+  return containsRuntimeDrift((event as Record<string, unknown>).result) ? "runtime-restart-required" : null;
+}
 
 export class GatewaySessionStream {
   readonly sessionRef: string;
@@ -29,57 +75,91 @@ 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;
   #settleListeners: Array<() => void> = [];
   readonly #toolRefs = new Map<string, string>();
+  readonly #lifecycle: SessionOperationLifecycle;
 
-  constructor(options: { sessionRef: string; operationRef: string; events: GatewayEventStore }) {
+  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 {
+    if (!this.#forcedSettlement) this.#forcedSettlement = { outcome: "error", reasonCode };
+  }
+  forceLifecycleTermination(reasonCode: string): void {
+    this.#lifecycleTerminationReasonCode ??= reasonCode;
+    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;
+    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 {
+  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 observation;
     }
-    if (event?.type === "message_end" && event.message?.role === "assistant") { this.#flush(true); return; }
     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 });
-      return;
+        toolLabel: safeTool(event.toolName), 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 });
+        toolLabel: safeTool(event.toolName), isError: event.isError === true, reasonCode });
       this.#toolRefs.delete(event.toolCallId);
     }
+    return observation;
   }
 
   #flush(final: boolean): void {
@@ -112,9 +192,31 @@ export class GatewaySessionStream {
     }
   }
 
-  complete(sessionRevision: string): void {
+  complete(sessionRevision: string | null, taskOutcome: string | null = null): void {
+    if (!this.#lifecycle.markTerminal()) return;
     this.#flush(true);
-    if (this.#messageRef) this.#events.publish("message.completed", { sessionRef: this.sessionRef, operationRef: this.operationRef,
-      messageRef: this.#messageRef, sessionRevision, truncated: this.#truncated });
+    let settlement = this.#forcedSettlement ?? (this.#runtimeRestartRequired
+      ? { outcome: "unknown" as const, reasonCode: "runtime-restart-required" }
+      : this.#settlement);
+    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.
+      settlement = { outcome: "unknown", reasonCode: "session-projection-unavailable" };
+    }
+    if (settlement.outcome === "completed" && messageRef && sessionRevision) {
+      this.#events.publish("message.completed", { sessionRef: this.sessionRef, operationRef: this.operationRef,
+        messageRef, sessionRevision, truncated: this.#truncated });
+    }
+    this.#events.publish("operation.settled", { sessionRef: this.sessionRef, operationRef: this.operationRef,
+      messageRef, sessionRevision, settlement: settlement.outcome,
+      reasonCode: settlement.outcome === "completed" ? null : settlement.reasonCode ?? "operation-settlement-unknown" });
   }
 }

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

@@ -154,8 +154,18 @@ export class SessionCommandController {
         | "renamed" | "pinned" | "unpinned" | "archived" | "unarchived" | "forked" | "no-change",
         operationRef: string | null = null;
       if (command.action === "session.create") {
-        targetSessionRef = await this.#runtimes.create(String(command.payload.projectRef), String(command.payload.placeRef),
-          command.payload.modelRef === null ? null : String(command.payload.modelRef), String(command.payload.thinkingLevel));
+        const createWithReadback = (this.#runtimes as any).createWithReadback;
+        if (typeof createWithReadback === "function") {
+          const created = await createWithReadback.call(this.#runtimes, String(command.payload.projectRef), String(command.payload.placeRef),
+            command.payload.modelRef === null ? null : String(command.payload.modelRef), String(command.payload.thinkingLevel));
+          targetSessionRef = String(created.sessionRef);
+          if (created.effectiveOptions?.state !== "confirmed") throw new Error(
+            typeof created.effectiveOptions?.reasonCode === "string" ? created.effectiveOptions.reasonCode : "session-create-options-effect-unknown");
+        } else {
+          // Compatibility with older embedded supervisors and test doubles.
+          targetSessionRef = await this.#runtimes.create(String(command.payload.projectRef), String(command.payload.placeRef),
+            command.payload.modelRef === null ? null : String(command.payload.modelRef), String(command.payload.thinkingLevel));
+        }
         if (command.payload.permissionMode !== undefined) {
           await this.#runtimes.setPermission(targetSessionRef, String(command.payload.permissionMode) as
             "read-only" | "workspace-write" | "trusted-full-access");
@@ -246,9 +256,14 @@ export class SessionCommandController {
       const code = /recovery/.test(message) ? "recovery-required"
         : /(owner-conflict|operation-conflict|runtime-busy)/.test(message) ? "owner-conflict"
           : noDispatchEffect || command.action === "session.send" && !sendAttempted ? "unavailable" : "effect-unknown";
-      const receipt = code === "effect-unknown" ? this.#uncertain(command, after, afterRow, "session-command-effect-unknown")
+      const specificCreateUncertainty = command.action === "session.create" && /^[a-z0-9][a-z0-9.-]{0,95}$/.test(message)
+        ? message : "session-command-effect-unknown";
+      const receipt = code === "effect-unknown" ? this.#uncertain(command, after, afterRow, specificCreateUncertainty)
         : this.#rejected(command, after, afterRow, code, message);
       try { this.#store.settle(command, receipt, this.#now()); } catch { /* intent remains uncertain */ }
+      if (command.action === "session.create" && afterRow) {
+        this.#events.publish("session.changed", { catalogRevision: after.catalogRevision, session: afterRow });
+      }
       return receipt;
     }
   }

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

@@ -0,0 +1,47 @@
+import { webUiModelRef } from "../../piagent-core/runtime/inspection/webui-snapshot.ts";
+
+export type EffectiveSessionOptions = {
+  state: "confirmed" | "mismatch" | "unknown";
+  modelRef: string | null;
+  thinkingLevel: string | null;
+  reasonCode: string | null;
+};
+
+const THINKING_LEVELS = new Set(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
+
+export function effectiveModelRef(session: any): string | null {
+  const model = session?.model;
+  if (!model || typeof model !== "object") return null;
+  const provider = String(model.provider ?? ""), id = String(model.id ?? model.modelId ?? "");
+  return provider && id ? webUiModelRef(provider, id) : null;
+}
+
+export function effectiveThinkingLevel(session: any): string | null {
+  let value: unknown;
+  try { value = typeof session?.getThinkingLevel === "function" ? session.getThinkingLevel() : undefined; }
+  catch { return null; }
+  if (value === undefined || value === null || value === "") value = session?.thinkingLevel;
+  const level = String(value ?? "");
+  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. */ }
+  const effectiveModel = effectiveModelRef(session), effectiveThinking = effectiveThinkingLevel(session);
+  if (!effectiveModel) return { state: "unknown", modelRef: null,
+    thinkingLevel: effectiveThinking, reasonCode: "session-model-effect-unknown" };
+  if (!effectiveThinking) return { state: "unknown", modelRef: effectiveModel,
+    thinkingLevel: null, reasonCode: "session-thinking-effect-unknown" };
+  if (modelRef && effectiveModel !== modelRef) return { state: "mismatch", modelRef: effectiveModel,
+    thinkingLevel: effectiveThinking, reasonCode: "session-model-mismatch" };
+  if (effectiveThinking !== thinkingLevel) return { state: "mismatch", modelRef: effectiveModel,
+    thinkingLevel: effectiveThinking, reasonCode: "session-thinking-mismatch" };
+  return { state: "confirmed", modelRef: effectiveModel, thinkingLevel: effectiveThinking, reasonCode: null };
+}

package/packages/piagent-webui/gateway/session-live-state.ts

@@ -0,0 +1,21 @@
+import type { PiagentWebUICanonicalVolatileSessionOperationStateV1 } from "../contracts/generated/session-live-state-v1.ts";
+import type { GatewayTerminalSettlement } from "./gateway-events.ts";
+import type { CurrentOperationProjection } from "./session-runtime-supervisor.ts";
+
+export function buildSessionLiveState(options: { gatewayInstanceRef: string; eventSequence: number;
+  operations: Array<CurrentOperationProjection & { sessionRef: string }>; settlements: GatewayTerminalSettlement[];
+  now?: Date }): PiagentWebUICanonicalVolatileSessionOperationStateV1 {
+  const now = options.now ?? new Date();
+  if (!Number.isFinite(now.getTime())) throw new Error("session-live-state-time-invalid");
+  return {
+    schemaVersion: 1,
+    version: "piagent-session-live-state-v1",
+    generatedAt: now.toISOString(),
+    gatewayInstanceRef: options.gatewayInstanceRef,
+    eventSequence: options.eventSequence,
+    state: "ready",
+    operations: [...options.operations].sort((left, right) => left.sessionRef.localeCompare(right.sessionRef)),
+    settlements: [...options.settlements].sort((left, right) => right.sequence - left.sequence).slice(0, 100),
+    reasonCode: null
+  };
+}