@piagent/platform 1.5.5 → 1.6.1

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

@@ -1,8 +1,5 @@
 import { createHmac, randomBytes } from "node:crypto";
-import path from "node:path";
-
-import { webUiModelRef } from "../../piagent-core/runtime/inspection/webui-snapshot.ts";
-import { webUiTaskRevision } from "../../piagent-core/runtime/inspection/webui-snapshot.ts";
+import { webUiModelRef, webUiTaskRevision } from "../../piagent-core/runtime/inspection/webui-snapshot.ts";
 import { activeSessionTask } from "../../piagent-core/extensions/task-state.js";
 import { inspectTaskControlState } from "../../piagent-core/runtime/inspection/task-control-journal.ts";
 import { piApprovalBroker, type ApprovalAuthority, type ApprovalBrokerEvent } from "../../piagent-core/runtime/inspection/approval-broker.ts";
@@ -11,52 +8,23 @@ import { isUserConversationSession, projectRefForCwd, sessionRefForPath } from "
 import { SessionLeaseStore, type SessionLeaseSnapshot } from "./session-lease-store.ts";
 import { GatewayEventStore } from "./gateway-events.ts";
 import { GatewaySessionStream } from "./gateway-session-stream.ts";
-import { preferAuthoritativePiagentGuard } from "./extension-authority.ts";
 import { executePermissionCommand, executeRuntimeCommand } from "./runtime-session-controls.ts";
-import { rpcUiContext } from "./rpc-ui-context.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";
+import { createProductionRuntimeFactory, type RuntimeFactory, type RuntimeHandle } from "./session-runtime-factory.ts";
 const MAX_WARM_RUNTIMES = 10;
-
-type RuntimeHandle = { dispose(): Promise<void>; session?: any };
-type RuntimeFactory = (info: PiSessionInfo, runtimeInstanceRef: string, sessionManager?: any) => Promise<RuntimeHandle>;
 type ActiveRuntime = { runtime: RuntimeHandle; lease: SessionLeaseSnapshot; info: PiSessionInfo; operationRef: string | null;
-  unsubscribe: (() => void) | null; completion: Promise<void> | null; settling: boolean; approvalWaiting: boolean;
-  unbindApproval: (() => void) | null; unsubscribeApproval: (() => void) | null; sessionManager: any | null };
+  stream: GatewaySessionStream | null; unsubscribe: (() => void) | null; completion: Promise<void> | null; settling: boolean; approvalWaiting: boolean;
+  unbindApproval: (() => void) | null; unsubscribeApproval: (() => void) | null; sessionManager: any | null;
+  watchdog: SessionOperationWatchdog | null; lastSessionRevision: string | null };
 type Projection = { sessionRevision: string; liveState: "offline" | "idle" | "running" | "paused" | "waiting-approval" | "uncertain" };
 type RuntimeCommandResult = Awaited<ReturnType<typeof executeRuntimeCommand>>;
-
-function productionRuntimeFactory(options: { host: any; agentDir: string; packageRoot: string; modelRuntime?: any }): RuntimeFactory {
-  return async (info, _runtimeInstanceRef, sessionManager) => {
-    const guard = path.join(options.packageRoot, "packages", "piagent-core", "extensions", "piagent-guard.ts");
-    const createRuntime = async ({ cwd, agentDir, sessionManager, sessionStartEvent }: any) => {
-      const services = await options.host.createAgentSessionServices({
-        cwd, agentDir, modelRuntime: options.modelRuntime,
-        resourceLoaderOptions: {
-          additionalExtensionPaths: [guard],
-          extensionsOverride: preferAuthoritativePiagentGuard(guard)
-        }
-      });
-      const extensionErrors = services.resourceLoader.getExtensions().errors;
-      if (extensionErrors.length) throw new Error("session-runtime-extension-load-failed");
-      const created = await options.host.createAgentSessionFromServices({ services, sessionManager, sessionStartEvent });
-      return { ...created, services, diagnostics: services.diagnostics };
-    };
-    const manager = sessionManager ?? options.host.SessionManager.open(info.path);
-    const runtime = await options.host.createAgentSessionRuntime(createRuntime, {
-      cwd: info.cwd,
-      agentDir: options.agentDir,
-      sessionManager: manager,
-      sessionStartEvent: { type: "session_start", reason: "resume", previousSessionFile: info.path }
-    });
-    const bind = async (session: any) => session.bindExtensions({ mode: "rpc", uiContext: rpcUiContext() });
-    runtime.setRebindSession(bind);
-    try { await bind(runtime.session); }
-    catch (error) { await runtime.dispose().catch(() => undefined); throw error; }
-    return runtime;
-  };
-}
-
+export type { EffectiveSessionOptions } from "./session-effective-options.ts";
+export type SessionCreateResult = { sessionRef: string; effectiveOptions: EffectiveSessionOptions };
+export type CurrentOperationProjection = { operationRef: string; state: "running" | "waiting-approval" | "settling";
+  abortable: boolean };
 export class SessionRuntimeSupervisor {
   readonly #gatewayInstanceRef: string;
   readonly #key: Buffer;
@@ -65,13 +33,13 @@ export class SessionRuntimeSupervisor {
   readonly #runtimeFactory: RuntimeFactory;
   readonly #events: GatewayEventStore;
   readonly #host: any | null;
+  readonly #operationDeadlinePolicy: SessionOperationDeadlinePolicy;
   readonly #resolveProject: ((projectRef: string) => string | null) | null;
   readonly #active = new Map<string, ActiveRuntime>();
   readonly #opening = new Map<string, Promise<SessionLeaseSnapshot>>();
   readonly #created = new Map<string, PiSessionInfo>();
   #closed = false;
   #readProjection: ((sessionRef: string) => Promise<Projection>) | null = null;
-
   constructor(options: {
     gatewayInstanceRef: string;
     key: Buffer;
@@ -83,6 +51,7 @@ export class SessionRuntimeSupervisor {
     packageRoot?: string;
     modelRuntime?: any;
     events?: GatewayEventStore;
+    operationWatchdog?: SessionOperationWatchdogOptions;
     resolveProject?(projectRef: string): string | null;
   }) {
     this.#gatewayInstanceRef = options.gatewayInstanceRef;
@@ -91,19 +60,17 @@ export class SessionRuntimeSupervisor {
     this.#listSessions = options.listSessions;
     this.#events = options.events ?? new GatewayEventStore();
     this.#host = options.host ?? null;
+    this.#operationDeadlinePolicy = sessionOperationDeadlinePolicy(options.operationWatchdog);
     this.#resolveProject = options.resolveProject ?? null;
     if (options.runtimeFactory) this.#runtimeFactory = options.runtimeFactory;
     else {
       if (!options.host || !options.agentDir || !options.packageRoot) throw new Error("session-runtime-factory-unavailable");
-      this.#runtimeFactory = productionRuntimeFactory({ host: options.host, agentDir: options.agentDir,
+      this.#runtimeFactory = createProductionRuntimeFactory({ host: options.host, agentDir: options.agentDir,
         packageRoot: options.packageRoot, modelRuntime: options.modelRuntime });
     }
   }
-
   get activeCount(): number { return this.#active.size; }
-
   setProjectionReader(reader: (sessionRef: string) => Promise<Projection>): void { this.#readProjection = reader; }
-
   async listSessions(): Promise<PiSessionInfo[]> {
     const persisted = (await this.#listSessions()).filter(isUserConversationSession);
     const paths = new Set(persisted.map((info) => info.path));
@@ -112,8 +79,11 @@ export class SessionRuntimeSupervisor {
     }
     return [...persisted, ...[...this.#created.values()].filter((info) => !paths.has(info.path))];
   }
-
   async create(projectRef: string, placeRef: string, modelRef: string | null, thinkingLevel: string): Promise<string> {
+    return (await this.createWithReadback(projectRef, placeRef, modelRef, thinkingLevel)).sessionRef;
+  }
+  async createWithReadback(projectRef: string, placeRef: string, modelRef: string | null,
+    thinkingLevel: string): Promise<SessionCreateResult> {
     if (this.#closed || !this.#host) throw new Error("session-create-unavailable");
     if (placeRef !== projectRef) throw new Error("session-place-mismatch");
     const sessions = (await this.#listSessions()).filter(isUserConversationSession);
@@ -128,22 +98,19 @@ export class SessionRuntimeSupervisor {
     const created: PiSessionInfo = { path: sessionFile, id: manager.getSessionId(), cwd: candidates[0], created: createdAt,
       modified: createdAt, messageCount: 0, firstMessage: "(no messages)", allMessagesText: "" };
     const sessionRef = sessionRefForPath(this.#key, sessionFile);
-    await this.#activate(sessionRef, created, manager);
-    const active = this.#active.get(sessionRef), session = active?.runtime.session;
-    if (!session) throw new Error("session-runtime-unavailable");
-    if (modelRef) {
-      const models = session.modelRuntime?.getAvailableSnapshot?.() ?? [];
-      const model = models.find((value: any) => webUiModelRef(String(value.provider ?? ""), String(value.id ?? "")) === modelRef);
-      if (!model) throw new Error("session-model-unavailable");
-      await session.setModel(model);
-    }
-    session.setThinkingLevel(thinkingLevel);
+    // Retain identity before fallible runtime work so create receipts never point at an orphan.
     this.#created.set(sessionRef, created);
-    return sessionRef;
+    try { await this.#activate(sessionRef, created, manager); }
+    catch {
+      return { sessionRef, effectiveOptions: { state: "unknown", modelRef: null, thinkingLevel: null,
+        reasonCode: "session-runtime-open-failed" } };
+    }
+    const active = this.#active.get(sessionRef), session = active?.runtime.session;
+    if (!session) return { sessionRef, effectiveOptions: { state: "unknown", modelRef: null, thinkingLevel: null,
+      reasonCode: "session-runtime-unavailable" } };
+    return { sessionRef, effectiveOptions: await configureSessionOptions(session, modelRef, thinkingLevel) };
   }
-
   liveSessionManager(sessionRef: string): any | null { return this.#active.get(sessionRef)?.sessionManager ?? null; }
-
   async acquire(sessionRef: string): Promise<SessionLeaseSnapshot> {
     if (this.#closed) throw new Error("session-runtime-supervisor-closed");
     const active = this.#active.get(sessionRef);
@@ -154,7 +121,6 @@ export class SessionRuntimeSupervisor {
     this.#opening.set(sessionRef, opening);
     return await opening;
   }
-
   async #acquire(sessionRef: string): Promise<SessionLeaseSnapshot> {
     if (this.#active.size + this.#opening.size > MAX_WARM_RUNTIMES) throw new Error("session-runtime-capacity");
     const found = (await this.#listSessions()).filter(isUserConversationSession)
@@ -162,12 +128,11 @@ export class SessionRuntimeSupervisor {
     if (found.length !== 1) throw new Error(found.length ? "session-ref-ambiguous" : "session-not-found");
     return await this.#activate(sessionRef, found[0]!);
   }
-
   async #activate(sessionRef: string, info: PiSessionInfo, sessionManager?: any): Promise<SessionLeaseSnapshot> {
     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);
@@ -179,9 +144,9 @@ export class SessionRuntimeSupervisor {
         await runtime.dispose().catch(() => undefined);
         throw new Error("session-owner-continuity-lost");
       }
-      const active: ActiveRuntime = { runtime, lease: current, info, operationRef: null, unsubscribe: null, completion: null,
+      const active: ActiveRuntime = { runtime, lease: current, info, operationRef: null, stream: null, unsubscribe: null, completion: null,
         settling: false, approvalWaiting: false, unbindApproval: null, unsubscribeApproval: null,
-        sessionManager: sessionManager ?? runtime.session?.sessionManager ?? null };
+        sessionManager: sessionManager ?? runtime.session?.sessionManager ?? null, watchdog: null, lastSessionRevision: null };
       this.#active.set(sessionRef, active);
       this.#bindApproval(sessionRef, active);
       return current;
@@ -191,7 +156,6 @@ export class SessionRuntimeSupervisor {
       throw error;
     }
   }
-
   async release(sessionRef: string): Promise<SessionLeaseSnapshot> {
     const active = this.#active.get(sessionRef);
     if (!active) {
@@ -203,7 +167,7 @@ export class SessionRuntimeSupervisor {
     if (active.settling && active.completion) await active.completion;
     if (active.operationRef || active.settling) throw new Error("session-runtime-busy");
     this.#active.delete(sessionRef);
-    active.unsubscribeApproval?.(); active.unbindApproval?.();
+    bestEffortUnsubscribe(active.unsubscribeApproval); bestEffortUnsubscribe(active.unbindApproval);
     try { await active.runtime.dispose(); }
     catch (error) {
       try { this.#leases.requireRecovery(sessionRef, active.lease.ownerEpoch!, this.#gatewayInstanceRef,
@@ -215,7 +179,28 @@ export class SessionRuntimeSupervisor {
     if (transient && !(await this.#listSessions()).some((info) => info.path === transient.path)) this.#created.delete(sessionRef);
     return released;
   }
-
+  async restart(sessionRef: string): Promise<SessionLeaseSnapshot> {
+    const active = this.#active.get(sessionRef);
+    if (!active) return await this.acquire(sessionRef);
+    if (active.operationRef || active.settling || !active.runtime.session?.isIdle) throw new Error("session-runtime-busy");
+    const info = active.info, manager = active.sessionManager; await this.release(sessionRef);
+    return await this.#activate(sessionRef, info, manager ?? undefined);
+  }
+  currentOperation(sessionRef: string): CurrentOperationProjection | null {
+    const active = this.#active.get(sessionRef);
+    if (!active?.operationRef) return null;
+    return { operationRef: active.operationRef,
+      state: active.settling ? "settling" : active.approvalWaiting ? "waiting-approval" : "running",
+      abortable: !active.settling };
+  }
+  currentOperations(): Array<CurrentOperationProjection & { sessionRef: string }> {
+    const result: Array<CurrentOperationProjection & { sessionRef: string }> = [];
+    for (const sessionRef of this.#active.keys()) {
+      const operation = this.currentOperation(sessionRef);
+      if (operation) result.push({ sessionRef, ...operation });
+    }
+    return result;
+  }
   ownership(sessionRef: string): SessionOwnerProjection {
     const lease = this.#leases.inspect(sessionRef);
     const active = this.#active.get(sessionRef);
@@ -225,7 +210,7 @@ export class SessionRuntimeSupervisor {
       reasonCode: null
     };
     if (lease.state === "gateway-owned" && active && active.lease.ownerEpoch === lease.ownerEpoch
-      && lease.gatewayInstanceRef === this.#gatewayInstanceRef) return {
+      && lease.gatewayInstanceRef === this.#gatewayInstanceRef && active.lease.runtimeInstanceRef === lease.runtimeInstanceRef) return {
       state: "gateway-owned", liveState: active.approvalWaiting ? "waiting-approval" : active.operationRef ? "running" : "idle",
       composerAvailable: true, needsAttention: active.approvalWaiting,
       owner: { kind: "gateway", ownerEpoch: lease.ownerEpoch!, gatewayInstanceRef: lease.gatewayInstanceRef!,
@@ -250,10 +235,6 @@ export class SessionRuntimeSupervisor {
       reasonCode: lease.reasonCode ?? "session-owner-continuity-unknown"
     };
   }
-
-  // `message` arrives already carrying any attached document text, and `images`
-  // already split out: the command controller claims staged refs before it calls
-  // here, so this layer only forwards what the host prompt takes.
   async send(sessionRef: string, payload: { delivery: "new-operation" | "follow-up" | "steer"; message: string;
     expectedOperationRef: string | null; images?: unknown[] }, sessionRevision: string):
   Promise<{ resultCode: "started" | "queued" | "steered"; operationRef: string }> {
@@ -261,7 +242,7 @@ export class SessionRuntimeSupervisor {
     const active = this.#active.get(sessionRef), session = active?.runtime.session;
     if (!active || !session) throw new Error("session-runtime-unavailable");
     if (payload.delivery !== "new-operation") {
-      if (!active.operationRef || active.operationRef !== payload.expectedOperationRef || !session.isStreaming) throw new Error("session-operation-conflict");
+      if (!active.operationRef || active.operationRef !== payload.expectedOperationRef || active.settling || !session.isStreaming) throw new Error("session-operation-conflict");
       const images = payload.images?.length ? payload.images : undefined;
       if (payload.delivery === "follow-up") { await session.followUp(payload.message, images); return { resultCode: "queued", operationRef: active.operationRef }; }
       await session.steer(payload.message, images); return { resultCode: "steered", operationRef: active.operationRef };
@@ -269,8 +250,14 @@ export class SessionRuntimeSupervisor {
     if (payload.expectedOperationRef !== null || active.operationRef || active.settling || !session.isIdle) throw new Error("session-operation-conflict");
     const operationRef = `operation_${randomBytes(24).toString("base64url")}`;
     const stream = new GatewaySessionStream({ sessionRef, operationRef, events: this.#events });
-    active.operationRef = operationRef;
-    active.unsubscribe = session.subscribe((event: unknown) => stream.observe(event));
+    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), 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");
+      await this.#quarantineRuntime(sessionRef, operationRef, active, stream, "session-operation-start-failed"); throw error; }
     this.#events.publish("runtime.changed", { sessionRef, sessionRevision, liveState: "running", operationRef, reasonCode: null });
     const created = this.#created.get(sessionRef);
     if (created && created.firstMessage === "(no messages)") {
@@ -278,35 +265,51 @@ export class SessionRuntimeSupervisor {
     }
     let prompt: Promise<void>;
     try { prompt = session.prompt(payload.message, payload.images?.length ? { images: payload.images } : undefined); }
-    catch (error) { await this.#finishOperation(sessionRef, operationRef, stream); throw error; }
+    catch (error) { stream.markError(); await this.#finishOperation(sessionRef, operationRef, stream); throw error; }
     const started = waitForOperationStart(stream, prompt);
-    // A normal prompt resolves after the agent settles. A workflow extension
-    // command resolves before its nested agent turn starts. In both cases the
-    // canonical completion boundary is `agent_settled`, not the outer promise.
+    // `agent_settled` is canonical even when a workflow's outer prompt resolves first.
     const lifecycle = started.then(async (mode) => {
       if (mode === "deferred") await stream.settled();
       else await Promise.race([stream.settled(), prompt]);
     });
     active.completion = lifecycle.then(() => this.#finishOperation(sessionRef, operationRef, stream),
-      () => this.#finishOperation(sessionRef, operationRef, stream));
+      () => { stream.markError(); return this.#finishOperation(sessionRef, operationRef, stream); });
     try { await started; }
     catch (error) { await active.completion; throw error; }
     return { resultCode: "started", operationRef };
   }
-
   async abort(sessionRef: string, operationRef: string, clearQueued: boolean): Promise<void> {
-    const active = this.#active.get(sessionRef), session = active?.runtime.session;
-    if (!active || !session || active.operationRef !== operationRef) throw new Error("session-operation-conflict");
-    const completion = active.completion;
-    // Extension hooks do not receive the Agent abort signal while awaiting a
-    // human approval. Resolve the exact operation's broker promise first so a
-    // stop request can reach the host instead of waiting for approval expiry.
-    piApprovalBroker.cancelForOperation(active.info.cwd, active.info.id, operationRef);
-    await session.abort();
-    if (clearQueued) session.clearQueue();
-    await completion;
+    await this.#terminateOperation(sessionRef, operationRef, "aborted", "operation-aborted", "operation-abort-timeout", clearQueued);
+  }
+  async #terminateOperation(sessionRef: string, operationRef: string, settlement: "aborted" | "error",
+    reasonCode: string, forcedReasonCode: string, clearQueued: boolean): Promise<void> {
+    const active = this.#active.get(sessionRef), session = active?.runtime.session, stream = active?.stream, watchdog = active?.watchdog;
+    if (!active || !session || !stream || !watchdog || active.operationRef !== operationRef) throw new Error("session-operation-conflict");
+    if (active.settling && !watchdog.terminating) throw new Error("session-operation-conflict");
+    active.settling = true; active.approvalWaiting = false;
+    const result = await terminateWatchedSessionOperation({ watchdog, settlement, reasonCode, forcedReasonCode, stream,
+      completion: () => active.completion,
+      settledCleanly: () => this.#active.get(sessionRef) === active && active.operationRef !== operationRef
+        && session.isIdle === true && session.isStreaming !== true,
+      cancelApproval: (reason) => { piApprovalBroker.cancelForOperation(active.info.cwd, active.info.id, operationRef, reason); },
+      abortHost: () => session.abort(), clearQueue: clearQueued ? () => session.clearQueue() : undefined
+    });
+    if (result.state === "quarantine") await this.#quarantineRuntime(sessionRef, operationRef, active, stream, result.reasonCode);
+    else if (this.#active.get(sessionRef) === active) { active.stream = null; active.watchdog = null; active.settling = false; }
+  }
+  async #quarantineRuntime(sessionRef: string, operationRef: string, active: ActiveRuntime,
+    stream: GatewaySessionStream, reasonCode: string): Promise<void> {
+    if (this.#active.get(sessionRef) !== active) return;
+    bestEffortUnsubscribe(active.unsubscribe); active.unsubscribe = null; active.watchdog?.close(); active.watchdog = null;
+    if (active.operationRef === operationRef) { active.operationRef = null; stream.complete(null); }
+    active.stream = null; active.completion = null; active.settling = false; active.approvalWaiting = false;
+    this.#active.delete(sessionRef); bestEffortUnsubscribe(active.unsubscribeApproval); bestEffortUnsubscribe(active.unbindApproval);
+    try { this.#leases.requireRecovery(sessionRef, active.lease.ownerEpoch!, this.#gatewayInstanceRef,
+      active.lease.runtimeInstanceRef!, reasonCode); } catch { /* continuity remains fail closed */ }
+    if (active.lastSessionRevision) this.#events.publish("runtime.changed", { sessionRef,
+      sessionRevision: active.lastSessionRevision, liveState: "uncertain", operationRef: null, reasonCode });
+    await boundedResult(Promise.resolve().then(() => active.runtime.dispose()), this.#operationDeadlinePolicy.terminationTimeoutMs);
   }
-
   #bindApproval(sessionRef: string, active: ActiveRuntime): void {
     const authority = (): ApprovalAuthority => {
       if (!active.operationRef || active.lease.state !== "gateway-owned" || !active.lease.revision) return null;
@@ -331,50 +334,53 @@ export class SessionRuntimeSupervisor {
     active.unbindApproval = piApprovalBroker.bind({ cwd: active.info.cwd, rawSessionId: active.info.id,
       runtimeInstanceId: active.lease.runtimeInstanceRef!, authority });
     active.unsubscribeApproval = piApprovalBroker.subscribe(active.info.cwd, active.info.id, (event: ApprovalBrokerEvent) => {
+      active.watchdog?.progress();
       const projection = piApprovalBroker.projection(active.info.cwd, active.info.id);
       active.approvalWaiting = projection.summary.state === "waiting";
       void this.#publishApprovalState(sessionRef, active, event);
     });
   }
-
   async #publishApprovalState(sessionRef: string, active: ActiveRuntime, event: ApprovalBrokerEvent): Promise<void> {
     try {
       const projection = await this.#readProjection?.(sessionRef);
       if (!projection || this.#active.get(sessionRef) !== active) return;
+      active.lastSessionRevision = projection.sessionRevision;
       this.#events.publish("runtime.changed", { sessionRef, sessionRevision: projection.sessionRevision,
         liveState: active.approvalWaiting ? "waiting-approval" : active.operationRef ? "running" : projection.liveState,
         operationRef: active.operationRef, reasonCode: `approval-${event.kind}` });
     } catch { /* approval truth remains available through the canonical inspection route */ }
   }
-
   async setModel(sessionRef: string, modelRef: string): Promise<"model-changed" | "no-change"> {
     await this.acquire(sessionRef);
     const active = this.#active.get(sessionRef), session = active?.runtime.session;
     if (!active || !session) throw new Error("session-runtime-unavailable");
     if (active.operationRef || !session.isIdle) throw new Error("session-runtime-busy");
-    const current = session.model && typeof session.model === "object"
-      ? webUiModelRef(String(session.model.provider ?? ""), String(session.model.id ?? session.model.modelId ?? "")) : null;
+    const current = effectiveModelRef(session);
     if (current === modelRef) return "no-change";
     const models = session.modelRuntime?.getAvailableSnapshot?.() ?? [];
-    const model = models.find((value: any) => webUiModelRef(String(value.provider ?? ""), String(value.id ?? "")) === modelRef);
+    const model = models.find((value: any) => webUiModelRef(String(value.provider ?? ""), String(value.id ?? value.modelId ?? "")) === modelRef);
     if (!model) throw new Error("session-model-unavailable");
     await session.setModel(model);
+    const effective = effectiveModelRef(session);
+    if (!effective) throw new Error("session-model-effect-unknown");
+    if (effective !== modelRef) throw new Error("session-model-mismatch");
     this.#touchCreated(sessionRef);
     return "model-changed";
   }
-
   async setThinking(sessionRef: string, thinkingLevel: string): Promise<"thinking-changed" | "no-change"> {
     await this.acquire(sessionRef);
     const active = this.#active.get(sessionRef), session = active?.runtime.session;
     if (!active || !session) throw new Error("session-runtime-unavailable");
     if (active.operationRef || !session.isIdle) throw new Error("session-runtime-busy");
-    const current = String(session.thinkingLevel ?? session.getThinkingLevel?.() ?? "unknown");
+    const current = effectiveThinkingLevel(session);
     if (current === thinkingLevel) return "no-change";
-    session.setThinkingLevel(thinkingLevel);
+    await session.setThinkingLevel(thinkingLevel);
+    const effective = effectiveThinkingLevel(session);
+    if (!effective) throw new Error("session-thinking-effect-unknown");
+    if (effective !== thinkingLevel) throw new Error("session-thinking-mismatch");
     this.#touchCreated(sessionRef);
     return "thinking-changed";
   }
-
   async setPermission(sessionRef: string, permissionMode: "read-only" | "workspace-write" | "trusted-full-access"): Promise<"permission-changed"> {
     await this.acquire(sessionRef);
     const active = this.#active.get(sessionRef), session = active?.runtime.session;
@@ -384,7 +390,6 @@ export class SessionRuntimeSupervisor {
     this.#touchCreated(sessionRef);
     return "permission-changed";
   }
-
   async runRuntimeCommand(sessionRef: string, command: string): Promise<RuntimeCommandResult> {
     await this.acquire(sessionRef);
     const active = this.#active.get(sessionRef), session = active?.runtime.session;
@@ -398,12 +403,10 @@ export class SessionRuntimeSupervisor {
       health: { state: "unavailable", reasonCode: "approval-broker-unavailable", message: "Approval broker is unavailable" } } };
     return piApprovalBroker.projection(active.info.cwd, active.info.id);
   }
-
   approvalDetail(sessionRef: string, approvalRef: string): unknown | null {
     const active = this.#active.get(sessionRef);
     return active ? piApprovalBroker.detail(active.info.cwd, active.info.id, approvalRef) : null;
   }
-
   async decideApproval(approvalRef: string, decision: unknown): Promise<unknown> {
     for (const active of this.#active.values()) {
       if (piApprovalBroker.detail(active.info.cwd, active.info.id, approvalRef)) {
@@ -412,7 +415,6 @@ export class SessionRuntimeSupervisor {
     }
     throw new Error("approval-not-pending");
   }
-
   async rename(sessionRef: string, title: string): Promise<"renamed" | "no-change"> {
     await this.acquire(sessionRef);
     const active = this.#active.get(sessionRef), session = active?.runtime.session;
@@ -424,7 +426,6 @@ export class SessionRuntimeSupervisor {
     this.#touchCreated(sessionRef);
     return "renamed";
   }
-
   async fork(sessionRef: string, entryRef: string | null, title: string | null): Promise<string> {
     if (!this.#host) throw new Error("session-fork-unavailable");
     await this.acquire(sessionRef);
@@ -451,28 +452,43 @@ export class SessionRuntimeSupervisor {
     this.#created.set(forkRef, created);
     return forkRef;
   }
-
-  #touchCreated(sessionRef: string): void {
-    const created = this.#created.get(sessionRef);
-    if (created) created.modified = new Date();
-  }
-
+  #touchCreated(sessionRef: string): void { const created = this.#created.get(sessionRef); if (created) created.modified = new Date(); }
   async #finishOperation(sessionRef: string, operationRef: string, stream: GatewaySessionStream): Promise<void> {
     const active = this.#active.get(sessionRef);
     if (!active || active.operationRef !== operationRef) return;
-    active.unsubscribe?.(); active.unsubscribe = null; active.operationRef = null; active.settling = true;
+    const restartRequired = stream.runtimeRestartRequired; let projection: Projection | null = null;
+    bestEffortUnsubscribe(active.unsubscribe); active.unsubscribe = null; active.watchdog?.close(); active.settling = true;
     try {
-      const projection = await this.#readProjection?.(sessionRef);
-      if (!projection) return;
-      stream.complete(projection.sessionRevision);
-      this.#events.publish("runtime.changed", { sessionRef, sessionRevision: projection.sessionRevision,
-        liveState: projection.liveState, operationRef: null, reasonCode: null });
+      if (this.#readProjection) {
+        const read = await boundedResult(this.#readProjection(sessionRef), this.#operationDeadlinePolicy.projectionTimeoutMs);
+        if (read.state === "settled") projection = read.value;
+        else if (read.state === "timeout") stream.markError("session-projection-timeout");
+      }
     } catch { /* Canonical refresh failure cannot be replaced by an invented revision. */ }
-    finally {
-      if (this.#active.get(sessionRef) === active) { active.settling = false; active.completion = null; }
+    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; }
+    // 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;
+    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" : 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; } }
+    if (!restartRequired || !projection || this.#active.get(sessionRef) !== active) return;
+    let restartAuthority: ActiveRuntime | null = active;
+    try {
+      await this.restart(sessionRef); restartAuthority = this.#active.get(sessionRef) ?? null;
+      const projection = await this.#readProjection?.(sessionRef);
+      if (!projection || !restartAuthority || this.#active.get(sessionRef) !== restartAuthority || this.ownership(sessionRef).state !== "gateway-owned") return;
+      this.#events.publish("runtime.changed", { sessionRef, sessionRevision: projection.sessionRevision, liveState: projection.liveState, operationRef: null, reasonCode: null });
+    } catch {
+      if (!restartAuthority || this.#active.get(sessionRef) !== restartAuthority || this.ownership(sessionRef).state !== "gateway-owned") return;
+      this.#events.publish("runtime.changed", { sessionRef, sessionRevision: projection.sessionRevision, liveState: "uncertain", operationRef: null, reasonCode: "runtime-restart-failed" });
     }
   }
-
   async close(): Promise<void> {
     if (this.#closed) return;
     this.#closed = true;

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" });

package/packages/piagent-webui/server/core-inspection-provider.ts

@@ -236,6 +236,7 @@ export class CoreInspectionProvider implements WebUiReadModelProvider {
   }
   async transcript(beforeCursor: string | null, limit: number): Promise<unknown> {
     const snapshot = await this.snapshot() as any;
+    const activeTask = this.#input.task?.() as any;
     return projectTranscript({ identity: { projectRef: snapshot.identity.projectRef, runtimeInstanceId: snapshot.identity.runtimeInstanceId,
       sessionRef: snapshot.identity.sessionRef, taskId: snapshot.identity.taskId, taskRunId: snapshot.identity.taskRunId, agentOperationId: null, toolCallId: null },
       revision: { runtimeRevision: snapshot.revision.runtimeRevision, taskRevision: snapshot.revision.taskRevision,
@@ -243,7 +244,7 @@ export class CoreInspectionProvider implements WebUiReadModelProvider {
         indexRevision: snapshot.revision.indexRevision, approvalRevision: snapshot.revision.approvalRevision,
         sessionOptionRevision: snapshot.revision.sessionOptionRevision, queueRevision: snapshot.revision.queueRevision },
       eventCursor: snapshot.revision.eventCursor, entries: this.#input.sessionEntries?.() ?? [], beforeCursor, limit,
-      generatedAt: snapshot.generatedAt });
+      generatedAt: snapshot.generatedAt, taskOutcome: typeof activeTask?.trace?.outcome === "string" ? activeTask.trace.outcome : null });
   }
   async queue(): Promise<unknown> {
     if (!this.#input.queueProjection) throw new ReadModelNotFound();

package/packages/piagent-webui/server/loopback-server.ts

@@ -56,6 +56,7 @@ export async function startLoopbackServer(options: {
   mode?: "session" | "gateway";
   readCapabilities: ReadCapabilities;
   readSessionCatalog?: () => unknown | Promise<unknown>;
+  readSessionLiveState?: () => unknown | Promise<unknown>;
   readSessionCreationOptions?: () => unknown | Promise<unknown>;
   readSessionModel?: (sessionRef: string) => WebUiReadModelProvider | Promise<WebUiReadModelProvider>;
   executeSessionAttachment?: (sessionRef: string, command: unknown) => unknown | Promise<unknown>;
@@ -296,6 +297,13 @@ export async function startLoopbackServer(options: {
       catch { return errorResponse(response, 503, "session-catalog-unavailable"); }
     }
 
+    if (request.method === "GET" && url.pathname === "/api/v1/session-live-state" && options.readSessionLiveState) {
+      if (!auth.authenticate(request)) return errorResponse(response, 401, "authentication-required");
+      if (url.search) return errorResponse(response, 400, "invalid-session-live-state-query");
+      try { return jsonResponse(response, 200, await options.readSessionLiveState()); }
+      catch { return errorResponse(response, 503, "session-live-state-unavailable"); }
+    }
+
     if (request.method === "GET" && url.pathname === "/api/v1/session-creation-options" && options.readSessionCreationOptions) {
       if (!auth.authenticate(request)) return errorResponse(response, 401, "authentication-required");
       if (url.search) return errorResponse(response, 400, "invalid-session-creation-query");