@piagent/platform 1.5.5 → 1.6.0

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-DynIMe8I.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-BV-_03yl.css">
   </head>
   <body>

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,6 +1,7 @@
 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";
 
 const MAX_BUFFER = 65_536;
@@ -8,9 +9,14 @@ 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 +25,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;
@@ -32,9 +76,28 @@ export class GatewaySessionStream {
   #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>();
 
+  get runtimeRestartRequired(): boolean { return this.#runtimeRestartRequired; }
+  get lifecycleTerminationReasonCode(): string | null { return this.#lifecycleTerminationReasonCode; }
+
+  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;
+    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(); }
+  }
+
   constructor(options: { sessionRef: string; operationRef: string; events: GatewayEventStore }) {
     this.sessionRef = options.sessionRef; this.operationRef = options.operationRef; this.#events = options.events;
   }
@@ -50,6 +113,7 @@ export class GatewaySessionStream {
   }
 
   observe(event: any): void {
+    if (this.#terminalEmitted) return;
     if (event?.type === "agent_start") {
       this.#started = true; for (const resolve of this.#startListeners.splice(0)) resolve(); return;
     }
@@ -67,17 +131,21 @@ export class GatewaySessionStream {
       if (event.assistantMessageEvent.delta.length > remaining) this.#truncated = true;
       this.#flush(false); return;
     }
-    if (event?.type === "message_end" && event.message?.role === "assistant") { this.#flush(true); return; }
+    if (event?.type === "message_end" && event.message?.role === "assistant") {
+      this.#flush(true); this.#lastMessageRef = this.#messageRef; this.#settlement = assistantSettlement(event.message); 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 });
+        toolLabel: safeTool(event.toolName), isError: null, reasonCode: null });
       return;
     }
     if (event?.type === "tool_execution_end" && typeof event.toolCallId === "string") {
       const toolCallRef = this.#toolRefs.get(event.toolCallId); if (!toolCallRef) return;
+      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);
     }
   }
@@ -112,9 +180,27 @@ export class GatewaySessionStream {
     }
   }
 
-  complete(sessionRevision: string): void {
+  complete(sessionRevision: string | null): void {
+    if (this.#terminalEmitted) return;
+    this.#terminalEmitted = true;
     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" && 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
+  };
+}

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

@@ -12,7 +12,10 @@ export async function waitForOperationStart(
     prompt.then(() => ({ state: "prompt-resolved" as const }),
       (error: unknown) => ({ state: "prompt-rejected" as const, error }))
   ]);
-  if (first.state === "started") return "prompt-owned";
+  if (first.state === "started") {
+    if (stream.lifecycleTerminationReasonCode) throw new Error(stream.lifecycleTerminationReasonCode);
+    return "prompt-owned";
+  }
   if (first.state === "prompt-rejected") throw first.error;
 
   // Extension commands such as `/workflow` launch their agent turn through
@@ -27,6 +30,7 @@ export async function waitForOperationStart(
           DEFERRED_OPERATION_START_GRACE_MS);
       })
     ]);
+    if (stream.lifecycleTerminationReasonCode) throw new Error(stream.lifecycleTerminationReasonCode);
     return "deferred";
   } finally {
     if (timer) clearTimeout(timer);

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

@@ -0,0 +1,158 @@
+export type SessionOperationDeadlineReason = "operation-inactivity-timeout" | "operation-deadline-exceeded";
+
+export type SessionOperationDeadlinePolicy = Readonly<{
+  inactivityTimeoutMs: number;
+  maximumDurationMs: number;
+  terminationTimeoutMs: number;
+  projectionTimeoutMs: number;
+}>;
+
+export type SessionOperationWatchdogOptions = Partial<SessionOperationDeadlinePolicy>;
+export type BoundedResult<T> = { state: "settled"; value: T } | { state: "rejected"; error: unknown } | { state: "timeout" };
+export type SessionOperationTerminationResult = { state: "settled" } | { state: "quarantine"; reasonCode: string };
+
+export function bestEffortUnsubscribe(unsubscribe: (() => void) | null): void {
+  try { unsubscribe?.(); } catch { /* broken host cleanup cannot retain operation authority */ }
+}
+
+// A silent tool/provider gets 15 minutes. Any observed host event refreshes that
+// allowance, while the six-hour ceiling prevents an endless stream of progress
+// events from retaining runtime authority forever. Cleanup itself is separately
+// bounded so Stop and watchdog recovery cannot inherit the original hang.
+const DEFAULT_POLICY: SessionOperationDeadlinePolicy = Object.freeze({
+  inactivityTimeoutMs: 15 * 60_000,
+  maximumDurationMs: 6 * 60 * 60_000,
+  terminationTimeoutMs: 5_000,
+  projectionTimeoutMs: 2_500
+});
+const MAX_TIMEOUT_MS = 24 * 60 * 60_000;
+const TERMINATION_CLEANUP_FAILED = "operation-termination-cleanup-failed";
+
+function duration(value: unknown, fallback: number): number {
+  if (value === undefined) return fallback;
+  if (!Number.isSafeInteger(value) || Number(value) < 1 || Number(value) > MAX_TIMEOUT_MS) {
+    throw new Error("session-operation-watchdog-config-invalid");
+  }
+  return Number(value);
+}
+
+export function sessionOperationDeadlinePolicy(options: SessionOperationWatchdogOptions = {}): SessionOperationDeadlinePolicy {
+  const policy = {
+    inactivityTimeoutMs: duration(options.inactivityTimeoutMs, DEFAULT_POLICY.inactivityTimeoutMs),
+    maximumDurationMs: duration(options.maximumDurationMs, DEFAULT_POLICY.maximumDurationMs),
+    terminationTimeoutMs: duration(options.terminationTimeoutMs, DEFAULT_POLICY.terminationTimeoutMs),
+    projectionTimeoutMs: duration(options.projectionTimeoutMs, DEFAULT_POLICY.projectionTimeoutMs)
+  };
+  if (policy.projectionTimeoutMs > policy.terminationTimeoutMs) throw new Error("session-operation-watchdog-config-invalid");
+  return Object.freeze(policy);
+}
+
+export async function boundedResult<T>(promise: PromiseLike<T>, timeoutMs: number): Promise<BoundedResult<T>> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      Promise.resolve(promise).then((value) => ({ state: "settled" as const, value }),
+        (error: unknown) => ({ state: "rejected" as const, error })),
+      new Promise<{ state: "timeout" }>((resolve) => { timer = setTimeout(() => resolve({ state: "timeout" }), timeoutMs); })
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+export class SessionOperationWatchdog {
+  readonly policy: SessionOperationDeadlinePolicy;
+  #idleTimer: ReturnType<typeof setTimeout> | null = null;
+  #maximumTimer: ReturnType<typeof setTimeout> | null = null;
+  #expire: ((reason: SessionOperationDeadlineReason) => void) | null = null;
+  #closed = false;
+  #termination: Promise<unknown> | null = null;
+
+  constructor(policy: SessionOperationDeadlinePolicy) { this.policy = policy; }
+  get terminating(): boolean { return this.#termination !== null; }
+
+  start(expire: (reason: SessionOperationDeadlineReason) => void): void {
+    if (this.#expire || this.#closed) throw new Error("session-operation-watchdog-state-invalid");
+    this.#expire = expire;
+    this.#armIdle();
+    this.#maximumTimer = setTimeout(() => this.#deadline("operation-deadline-exceeded"), this.policy.maximumDurationMs);
+    // An accepted operation owns live runtime work until it settles. Keep both
+    // deadline timers referenced so a headless Gateway cannot let Node exit
+    // while the provider promise is pending and silently skip recovery.
+  }
+
+  progress(): void {
+    if (this.#closed || !this.#expire) return;
+    this.#armIdle();
+  }
+
+  close(): void {
+    if (this.#closed) return;
+    this.#closed = true;
+    if (this.#idleTimer) clearTimeout(this.#idleTimer);
+    if (this.#maximumTimer) clearTimeout(this.#maximumTimer);
+    this.#idleTimer = null; this.#maximumTimer = null; this.#expire = null;
+  }
+
+  terminate<T>(run: () => Promise<T>): Promise<T> {
+    if (!this.#termination) { this.close(); this.#termination = Promise.resolve().then(run); }
+    return this.#termination as Promise<T>;
+  }
+
+  #armIdle(): void {
+    if (this.#idleTimer) clearTimeout(this.#idleTimer);
+    this.#idleTimer = setTimeout(() => this.#deadline("operation-inactivity-timeout"), this.policy.inactivityTimeoutMs);
+  }
+
+  #deadline(reason: SessionOperationDeadlineReason): void {
+    if (this.#closed) return;
+    const expire = this.#expire; this.close(); expire?.(reason);
+  }
+}
+
+export function armSessionOperationWatchdog(options: {
+  watchdog: SessionOperationWatchdog;
+  subscribe(listener: (event: unknown) => void): unknown;
+  observe(event: unknown): void;
+  expire(reason: SessionOperationDeadlineReason): void;
+}): () => void {
+  const unsubscribe = options.subscribe((event) => { options.watchdog.progress(); options.observe(event); });
+  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; }
+  return () => { unsubscribe(); };
+}
+
+export async function terminateWatchedSessionOperation(options: {
+  watchdog: SessionOperationWatchdog;
+  settlement: "aborted" | "error";
+  reasonCode: string;
+  forcedReasonCode: string;
+  stream: { markAborted(reasonCode: string): void; markError(reasonCode: string): void;
+    forceLifecycleTermination(reasonCode: string): void };
+  completion(): Promise<void> | null;
+  settledCleanly(): boolean;
+  cancelApproval(reasonCode: string): void;
+  abortHost(): unknown;
+  clearQueue?(): void;
+}): Promise<SessionOperationTerminationResult> {
+  return await options.watchdog.terminate(async () => {
+    const mark = (reasonCode: string) => options.settlement === "aborted"
+      ? options.stream.markAborted(reasonCode) : options.stream.markError(reasonCode);
+    let cleanupFailed = false;
+    try { options.cancelApproval(options.reasonCode); } catch { cleanupFailed = true; }
+    try { options.clearQueue?.(); } catch { cleanupFailed = true; }
+    const terminalReason = cleanupFailed ? TERMINATION_CLEANUP_FAILED : options.reasonCode;
+    mark(terminalReason);
+    void Promise.resolve().then(options.abortHost).catch(() => undefined);
+    const completion = options.completion();
+    const completed = completion ? await boundedResult(completion, options.watchdog.policy.terminationTimeoutMs)
+      : { state: "timeout" as const };
+    if (!cleanupFailed && completed.state === "settled" && options.settledCleanly()) return { state: "settled" as const };
+    const quarantineReason = cleanupFailed ? TERMINATION_CLEANUP_FAILED : options.forcedReasonCode;
+    mark(quarantineReason); options.stream.forceLifecycleTermination(quarantineReason);
+    const forcedCompletion = options.completion();
+    if (forcedCompletion) await boundedResult(forcedCompletion, options.watchdog.policy.projectionTimeoutMs);
+    return { state: "quarantine" as const, reasonCode: quarantineReason };
+  });
+}