@piagent/platform 1.6.1 → 1.8.0

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

@@ -1,45 +1,38 @@
+import { closeSessionRuntimes } from "./session-runtime-close.ts";
 import { createHmac, randomBytes } from "node:crypto";
 import { webUiModelRef, webUiTaskRevision } from "../../piagent-core/runtime/inspection/webui-snapshot.ts";
 import { activeSessionTask } from "../../piagent-core/extensions/task-state.js";
+import { createSessionOperationSettlement } from "./session-operation-settlement.ts";
 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";
-import type { SessionOwnerProjection, PiSessionInfo } from "./session-catalog.ts";
-import { isUserConversationSession, projectRefForCwd, sessionRefForPath } from "./session-catalog.ts";
+import { isUserConversationSession, projectRefForCwd, sessionRefForPath, type SessionOwnerProjection, type PiSessionInfo } from "./session-catalog.ts";
 import { SessionLeaseStore, type SessionLeaseSnapshot } from "./session-lease-store.ts";
 import { GatewayEventStore } from "./gateway-events.ts";
 import { GatewaySessionStream } from "./gateway-session-stream.ts";
 import { executePermissionCommand, executeRuntimeCommand } from "./runtime-session-controls.ts";
-import { configureSessionOptions, effectiveModelRef, effectiveThinkingLevel, type EffectiveSessionOptions } from "./session-effective-options.ts";
-import { 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";
+import { inspectEffectiveSessionOptions, effectiveModelRef, effectiveThinkingLevel, type EffectiveSessionOptions } from "./session-effective-options.ts";
+import { launchSessionPrompt, type LaunchedSessionPrompt, type SessionSendResult } from "./session-prompt-dispatch.ts";
+import { WEBUI_MESSAGE_CORRELATION_ENTRY_TYPE } from "../shared/message-correlation.ts";
+import { terminalDeliveryRequest, terminalDeliveryReceiptCommitter, terminalDeliverySessionEntries } from "../server/terminal-delivery-receipt.ts";
+import { armSessionOperationWatchdog, bestEffortUnsubscribe, boundedResult, sessionOperationDeadlinePolicy, SessionOperationWatchdog, terminateWatchedSessionOperation, type SessionOperationDeadlinePolicy, type SessionOperationWatchdogOptions } from "./session-operation-watchdog.ts";
+import { createProductionRuntimeFactory, type RuntimeFactory, type ScopedBrokerRouter } from "./session-runtime-factory.ts";
+import { projectSessionRuntimeOwnership } from "./session-runtime-ownership.ts";
 const MAX_WARM_RUNTIMES = 10;
-type ActiveRuntime = { runtime: RuntimeHandle; lease: SessionLeaseSnapshot; info: PiSessionInfo; operationRef: string | 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>>;
+import type { ActiveRuntime } from "./session-runtime-state.ts";
+type Projection = { sessionRevision: string; liveState: "offline" | "idle" | "running" | "paused" | "waiting-approval" | "uncertain" }; type RuntimeCommandResult = Awaited<ReturnType<typeof executeRuntimeCommand>>;
 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 };
+  abortable: boolean; messageRequestId?: string };
 export class SessionRuntimeSupervisor {
-  readonly #gatewayInstanceRef: string;
-  readonly #key: Buffer;
-  readonly #leases: SessionLeaseStore;
-  readonly #listSessions: () => Promise<PiSessionInfo[]>;
-  readonly #runtimeFactory: RuntimeFactory;
-  readonly #events: GatewayEventStore;
-  readonly #host: any | null;
-  readonly #operationDeadlinePolicy: SessionOperationDeadlinePolicy;
+  readonly #gatewayInstanceRef: string; readonly #key: Buffer;
+  readonly #leases: SessionLeaseStore; readonly #listSessions: () => Promise<PiSessionInfo[]>;
+  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;
+  readonly #settleOperation: ReturnType<typeof createSessionOperationSettlement>;
+  readonly #active = new Map<string, ActiveRuntime>(); readonly #opening = new Map<string, Promise<SessionLeaseSnapshot>>();
+  readonly #created = new Map<string, PiSessionInfo>(); #closed = false; #closing: Promise<void> | null = null; #readProjection: ((sessionRef: string) => Promise<Projection>) | null = null;
   constructor(options: {
     gatewayInstanceRef: string;
     key: Buffer;
@@ -50,9 +43,11 @@ export class SessionRuntimeSupervisor {
     agentDir?: string;
     packageRoot?: string;
     modelRuntime?: any;
+    scopedBrokerRouter?: ScopedBrokerRouter;
     events?: GatewayEventStore;
     operationWatchdog?: SessionOperationWatchdogOptions;
     resolveProject?(projectRef: string): string | null;
+    compositeSettlementEvidence?(): unknown | Promise<unknown>;
   }) {
     this.#gatewayInstanceRef = options.gatewayInstanceRef;
     this.#key = options.key;
@@ -62,21 +57,20 @@ export class SessionRuntimeSupervisor {
     this.#host = options.host ?? null;
     this.#operationDeadlinePolicy = sessionOperationDeadlinePolicy(options.operationWatchdog);
     this.#resolveProject = options.resolveProject ?? null;
+    this.#settleOperation = createSessionOperationSettlement(options);
     if (options.runtimeFactory) this.#runtimeFactory = options.runtimeFactory;
     else {
       if (!options.host || !options.agentDir || !options.packageRoot) throw new Error("session-runtime-factory-unavailable");
       this.#runtimeFactory = createProductionRuntimeFactory({ host: options.host, agentDir: options.agentDir,
-        packageRoot: options.packageRoot, modelRuntime: options.modelRuntime });
+        packageRoot: options.packageRoot, modelRuntime: options.modelRuntime,
+        scopedBrokerRouter: options.scopedBrokerRouter });
     }
   }
-  get activeCount(): number { return this.#active.size; }
-  setProjectionReader(reader: (sessionRef: string) => Promise<Projection>): void { this.#readProjection = reader; }
+  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));
-    for (const [sessionRef, info] of this.#created) {
-      if (paths.has(info.path)) this.#created.delete(sessionRef);
-    }
+    for (const [sessionRef, info] of this.#created) if (paths.has(info.path)) this.#created.delete(sessionRef);
     return [...persisted, ...[...this.#created.values()].filter((info) => !paths.has(info.path))];
   }
   async create(projectRef: string, placeRef: string, modelRef: string | null, thinkingLevel: string): Promise<string> {
@@ -100,7 +94,7 @@ export class SessionRuntimeSupervisor {
     const sessionRef = sessionRefForPath(this.#key, sessionFile);
     // Retain identity before fallible runtime work so create receipts never point at an orphan.
     this.#created.set(sessionRef, created);
-    try { await this.#activate(sessionRef, created, manager); }
+    try { await this.#activate(sessionRef, created, manager, { modelRef, thinkingLevel }); }
     catch {
       return { sessionRef, effectiveOptions: { state: "unknown", modelRef: null, thinkingLevel: null,
         reasonCode: "session-runtime-open-failed" } };
@@ -108,7 +102,7 @@ export class SessionRuntimeSupervisor {
     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) };
+    return { sessionRef, effectiveOptions: inspectEffectiveSessionOptions(session, modelRef, thinkingLevel) };
   }
   liveSessionManager(sessionRef: string): any | null { return this.#active.get(sessionRef)?.sessionManager ?? null; }
   async acquire(sessionRef: string): Promise<SessionLeaseSnapshot> {
@@ -128,7 +122,8 @@ 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> {
+  async #activate(sessionRef: string, info: PiSessionInfo, sessionManager?: any,
+    initialOptions?: { modelRef: string | null; thinkingLevel: string }): 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);
@@ -137,14 +132,15 @@ export class SessionRuntimeSupervisor {
     }
     const lease = this.#leases.acquire(sessionRef, this.#gatewayInstanceRef, runtimeInstanceRef);
     try {
-      const runtime = await this.#runtimeFactory(info, runtimeInstanceRef, sessionManager);
+      const runtime = await this.#runtimeFactory(info, runtimeInstanceRef, sessionManager, initialOptions);
       const current = this.#leases.inspect(sessionRef);
       if (current.state !== "gateway-owned" || current.ownerEpoch !== lease.ownerEpoch
         || current.gatewayInstanceRef !== this.#gatewayInstanceRef || current.runtimeInstanceRef !== runtimeInstanceRef) {
         await runtime.dispose().catch(() => undefined);
         throw new Error("session-owner-continuity-lost");
       }
-      const active: ActiveRuntime = { runtime, lease: current, info, operationRef: null, stream: null, unsubscribe: null, completion: null,
+      const active: ActiveRuntime = { runtime, lease: current, info, operationRef: null, messageRequestId: null, cancelWire: null,
+        stream: null, unsubscribe: null, completion: null,
         settling: false, approvalWaiting: false, unbindApproval: null, unsubscribeApproval: null,
         sessionManager: sessionManager ?? runtime.session?.sessionManager ?? null, watchdog: null, lastSessionRevision: null };
       this.#active.set(sessionRef, active);
@@ -191,7 +187,7 @@ export class SessionRuntimeSupervisor {
     if (!active?.operationRef) return null;
     return { operationRef: active.operationRef,
       state: active.settling ? "settling" : active.approvalWaiting ? "waiting-approval" : "running",
-      abortable: !active.settling };
+      abortable: !active.settling, ...(active.messageRequestId ? { messageRequestId: active.messageRequestId } : {}) };
   }
   currentOperations(): Array<CurrentOperationProjection & { sessionRef: string }> {
     const result: Array<CurrentOperationProjection & { sessionRef: string }> = [];
@@ -202,80 +198,69 @@ export class SessionRuntimeSupervisor {
     return result;
   }
   ownership(sessionRef: string): SessionOwnerProjection {
-    const lease = this.#leases.inspect(sessionRef);
-    const active = this.#active.get(sessionRef);
-    if (lease.state === "released") return {
-      state: "offline", liveState: "offline", composerAvailable: true, needsAttention: false,
-      owner: { kind: "none", ownerEpoch: null, gatewayInstanceRef: null, runtimeInstanceRef: null, continuity: "released" },
-      reasonCode: null
-    };
-    if (lease.state === "gateway-owned" && active && active.lease.ownerEpoch === lease.ownerEpoch
-      && 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!,
-        runtimeInstanceRef: lease.runtimeInstanceRef!, continuity: "exact" }, reasonCode: null
-    };
-    if (lease.state === "unavailable") return {
-      state: "recovery-required", liveState: "uncertain", composerAvailable: false, needsAttention: true,
-      owner: { kind: "none", ownerEpoch: null, gatewayInstanceRef: null, runtimeInstanceRef: null, continuity: "unknown" },
-      reasonCode: lease.reasonCode ?? "session-lease-unavailable"
-    };
-    if (lease.state === "terminal-owned") return {
-      state: "terminal-owned", liveState: "uncertain", composerAvailable: false, needsAttention: false,
-      owner: { kind: "terminal", ownerEpoch: lease.ownerEpoch!,
-        gatewayInstanceRef: `terminal_${createHmac("sha256", this.#key).update(lease.gatewayInstanceRef!).digest("base64url").slice(0, 43)}`,
-        runtimeInstanceRef: lease.runtimeInstanceRef!, continuity: "exact" },
-      reasonCode: "terminal-owner-active"
-    };
-    return {
-      state: "recovery-required", liveState: "uncertain", composerAvailable: false, needsAttention: true,
-      owner: { kind: "gateway", ownerEpoch: lease.ownerEpoch!, gatewayInstanceRef: lease.gatewayInstanceRef!,
-        runtimeInstanceRef: lease.runtimeInstanceRef!, continuity: "uncertain" },
-      reasonCode: lease.reasonCode ?? "session-owner-continuity-unknown"
-    };
+    return projectSessionRuntimeOwnership({ lease: this.#leases.inspect(sessionRef), active: this.#active.get(sessionRef),
+      gatewayInstanceRef: this.#gatewayInstanceRef, key: this.#key });
   }
   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 }> {
+    expectedOperationRef: string | null; messageRequestId?: string; images?: unknown[] }, sessionRevision: string, options: { deferDispatch?: boolean } = {}):
+  Promise<SessionSendResult> {
     await this.acquire(sessionRef);
     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.runtime.beginWireOperation) throw new Error("provider-wire-queued-input-unsupported");
       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 };
     }
     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 });
+    const operationRef = `operation_${randomBytes(24).toString("base64url")}`, messageRequestId = payload.messageRequestId ?? null;
+    const recoveryRequest = terminalDeliveryRequest(payload.message, payload.images);
+    const stream = new GatewaySessionStream({ sessionRef, operationRef, messageRequestId, events: this.#events,
+      commitTerminalDeliveryReceipt: terminalDeliveryReceiptCommitter({ cwd: active.info.cwd, sessionId: active.info.id,
+        operationRef, messageRequestId, request: recoveryRequest,
+        entries: () => (active.sessionManager ?? session.sessionManager)?.getBranch?.() ?? [],
+        persistedEntries: () => terminalDeliverySessionEntries(active.info.path, active.info.id),
+        // The committer fails closed on missing/throwing persistence methods.
+        appendCustomEntry: (type, data) => (active.sessionManager ?? session.sessionManager).appendCustomEntry(type, data) }) });
     const watchdog = new SessionOperationWatchdog(this.#operationDeadlinePolicy);
-    active.operationRef = operationRef; active.stream = stream; active.watchdog = watchdog; active.lastSessionRevision = sessionRevision;
+    active.operationRef = operationRef; active.messageRequestId = messageRequestId;
+    active.stream = stream; active.watchdog = watchdog; active.lastSessionRevision = sessionRevision;
     try {
+      active.cancelWire = active.runtime.beginWireOperation?.({ operationRef, messageRequestId, inputText: payload.message }) ?? null;
       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)") {
-      created.firstMessage = payload.message; created.allMessagesText = payload.message; created.messageCount = 1; created.modified = new Date();
-    }
-    let prompt: Promise<void>;
-    try { prompt = session.prompt(payload.message, payload.images?.length ? { images: payload.images } : undefined); }
-    catch (error) { stream.markError(); await this.#finishOperation(sessionRef, operationRef, stream); throw error; }
-    const started = waitForOperationStart(stream, prompt);
-    // `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),
-      () => { stream.markError(); return this.#finishOperation(sessionRef, operationRef, stream); });
-    try { await started; }
-    catch (error) { await active.completion; throw error; }
+    let launched: LaunchedSessionPrompt | null = null, cancelled = false;
+    const dispatch = () => {
+      if (launched || cancelled) return;
+      this.#events.publish("runtime.changed", { sessionRef, sessionRevision, liveState: "running", operationRef,
+        ...(messageRequestId ? { messageRequestId } : {}), reasonCode: null });
+      const created = this.#created.get(sessionRef); if (created && created.firstMessage === "(no messages)") { created.firstMessage = payload.message;
+        created.allMessagesText = payload.message; created.messageCount = 1; created.modified = new Date(); }
+      launched = launchSessionPrompt({ stream, canInvoke: () => !cancelled && this.#active.get(sessionRef) === active
+        && active.operationRef === operationRef, invoke: () => {
+          const manager = active.sessionManager ?? session.sessionManager;
+          if (messageRequestId && typeof manager?.appendCustomEntry === "function") {
+            manager.appendCustomEntry(WEBUI_MESSAGE_CORRELATION_ENTRY_TYPE,
+              { schemaVersion: 1, messageRequestId, operationRef,
+                ...(recoveryRequest !== undefined ? { terminalDeliveryRequest: recoveryRequest } : {}) });
+          }
+          return session.prompt(payload.message, payload.images?.length ? { images: payload.images } : undefined);
+        }, finish: () => this.#finishOperation(sessionRef, operationRef, stream) }); active.completion = launched.completion;
+    };
+    const cancel = () => {
+      if (launched || cancelled || this.#active.get(sessionRef) !== active || active.operationRef !== operationRef) return false;
+      cancelled = true; active.cancelWire?.("cancelled-before-dispatch"); active.cancelWire = null;
+      bestEffortUnsubscribe(active.unsubscribe); active.unsubscribe = null; watchdog.close();
+      active.operationRef = null; active.messageRequestId = null;
+      active.stream = null; active.watchdog = null; active.settling = false; return true;
+    };
+    if (options.deferDispatch) return { resultCode: "started", operationRef, dispatch, cancel };
+    dispatch(); try { await launched!.started; } catch (error) { await launched!.completion; throw error; }
     return { resultCode: "started", operationRef };
   }
   async abort(sessionRef: string, operationRef: string, clearQueued: boolean): Promise<void> {
@@ -286,7 +271,7 @@ export class SessionRuntimeSupervisor {
     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;
+    active.cancelWire?.(reasonCode); active.cancelWire = null; 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
@@ -297,17 +282,19 @@ export class SessionRuntimeSupervisor {
     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> {
+  async #quarantineRuntime(sessionRef: string, operationRef: string, active: ActiveRuntime, stream: GatewaySessionStream, reasonCode: string): Promise<void> {
     if (this.#active.get(sessionRef) !== active) return;
+    active.cancelWire?.(reasonCode); active.cancelWire = null;
     bestEffortUnsubscribe(active.unsubscribe); active.unsubscribe = null; active.watchdog?.close(); active.watchdog = null;
-    if (active.operationRef === operationRef) { active.operationRef = null; stream.complete(null); }
+    const messageRequestId = active.messageRequestId;
+    if (active.operationRef === operationRef) { active.operationRef = null; active.messageRequestId = null; stream.complete(null, activeSessionTask(active.info.cwd, active.info.id)?.trace?.outcome ?? 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 });
+      sessionRevision: active.lastSessionRevision, liveState: "uncertain", operationRef: null,
+      ...(messageRequestId ? { messageRequestId } : {}), reasonCode });
     await boundedResult(Promise.resolve().then(() => active.runtime.dispose()), this.#operationDeadlinePolicy.terminationTimeoutMs);
   }
   #bindApproval(sessionRef: string, active: ActiveRuntime): void {
@@ -347,7 +334,8 @@ export class SessionRuntimeSupervisor {
       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}` });
+        operationRef: active.operationRef, ...(active.messageRequestId ? { messageRequestId: active.messageRequestId } : {}),
+        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"> {
@@ -456,8 +444,13 @@ export class SessionRuntimeSupervisor {
   async #finishOperation(sessionRef: string, operationRef: string, stream: GatewaySessionStream): Promise<void> {
     const active = this.#active.get(sessionRef);
     if (!active || active.operationRef !== operationRef) return;
-    const restartRequired = stream.runtimeRestartRequired; let projection: Projection | null = null;
+    active.cancelWire?.("operation-settled"); active.cancelWire = null;
+    const restartRequired = stream.runtimeRestartRequired, messageRequestId = active.messageRequestId; let projection: Projection | null = null;
     bestEffortUnsubscribe(active.unsubscribe); active.unsubscribe = null; active.watchdog?.close(); active.settling = true;
+    const task = activeSessionTask(active.info.cwd, active.info.id);
+    const settlement = await this.#settleOperation(active.info.cwd, task, {
+      sessionId: active.info.id, operationRef, messageRequestId, stream,
+      manager: active.sessionManager ?? active.runtime.session?.sessionManager });
     try {
       if (this.#readProjection) {
         const read = await boundedResult(this.#readProjection(sessionRef), this.#operationDeadlinePolicy.projectionTimeoutMs);
@@ -468,13 +461,14 @@ export class SessionRuntimeSupervisor {
     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;
+    active.operationRef = null; active.messageRequestId = 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);
+    const terminalTask = activeSessionTask(active.info.cwd, active.info.id), taskOutcome = terminalTask?.trace?.outcome ?? null, nativeTaskStatus = terminalTask?.trace?.outcome === "blocked" && terminalTask.trace.terminalDisposition === "refused" ? "refused" : null;
+    stream.complete(projection?.sessionRevision ?? null, taskOutcome,
+      settlement.status === "not-applicable" ? nativeTaskStatus : settlement.taskStatus);
     if (projection) this.#events.publish("runtime.changed", { sessionRef, sessionRevision: projection.sessionRevision,
       liveState: restartRequired ? "uncertain" : settledLiveState, operationRef: null,
-      reasonCode: restartRequired ? "runtime-restart-required" : null });
+      ...(messageRequestId ? { messageRequestId } : {}), 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;
@@ -483,18 +477,24 @@ export class SessionRuntimeSupervisor {
       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 });
+      this.#events.publish("runtime.changed", { sessionRef, sessionRevision: projection.sessionRevision, liveState: projection.liveState,
+        operationRef: null, ...(messageRequestId ? { messageRequestId } : {}), 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" });
+      this.#events.publish("runtime.changed", { sessionRef, sessionRevision: projection.sessionRevision, liveState: "uncertain",
+        operationRef: null, ...(messageRequestId ? { messageRequestId } : {}), reasonCode: "runtime-restart-failed" });
     }
   }
-  async close(): Promise<void> {
-    if (this.#closed) return;
-    this.#closed = true;
-    await Promise.allSettled([...this.#opening.values()]);
-    await Promise.allSettled([...this.#active.entries()].filter(([, active]) => active.operationRef)
-      .map(([sessionRef, active]) => this.abort(sessionRef, active.operationRef!, true)));
-    await Promise.allSettled([...this.#active.keys()].map((sessionRef) => this.release(sessionRef)));
+  close(): Promise<void> {
+    if (!this.#closing) {
+      this.#closed = true;
+      this.#closing = closeSessionRuntimes({ opening: this.#opening, active: this.#active,
+        terminationTimeoutMs: this.#operationDeadlinePolicy.terminationTimeoutMs,
+        abort: (sessionRef, operationRef) => this.abort(sessionRef, operationRef, true),
+        release: sessionRef => this.release(sessionRef),
+        quarantine: (sessionRef, operationRef, active, reasonCode) =>
+          this.#quarantineRuntime(sessionRef, operationRef, active, active.stream!, reasonCode) });
+    }
+    return this.#closing;
   }
 }

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

@@ -3,8 +3,27 @@ import { randomBytes } from "node:crypto";
 import { redactSensitiveText } from "../../piagent-core/extensions/redaction-core.js";
 import { ReadModelNotFound, type SourceView, type StreamEvent, type WebUiReadModelProvider } from "./read-model-provider.ts";
 import { projectTranscript } from "./transcript-projection.ts";
+import { readTerminalDeliveryReceipt, terminalDeliverySessionEntries } from "./terminal-delivery-receipt.ts";
 
 const CORE_ROOT = "../../piagent-core";
+const SOURCE_AUTHORITY_ALIGNED = Symbol("piagent-source-authority-aligned");
+const STABLE_IDENTITY_FIELDS = ["projectRef", "runtimeInstanceId", "sessionRef", "taskId", "taskRunId"] as const;
+
+function stableIdentityMatches(left: Record<string, any> | null | undefined, right: Record<string, any> | null | undefined): boolean {
+  return Boolean(left && right && STABLE_IDENTITY_FIELDS.every((field) => left[field] === right[field]));
+}
+
+function sourceBinding(snapshot: Record<string, any>) {
+  return { sourceProjectionRevision: snapshot.sourceChanges.projectionRevision,
+    taskViewRevision: snapshot.sourceChanges.task.revision, workspaceRevision: snapshot.sourceChanges.workingTree.revision,
+    indexRevision: snapshot.sourceChanges.staged.revision };
+}
+
+function sourceDocumentMatches(document: Record<string, any> | null | undefined, snapshot: Record<string, any>): boolean {
+  const binding = sourceBinding(snapshot);
+  return Boolean(document && stableIdentityMatches(document.identity, snapshot.identity)
+    && Object.entries(binding).every(([field, value]) => document.snapshotBinding?.[field] === value));
+}
 
 type RuntimeEvent = { eventCursor: string; [key: string]: unknown };
 type EventReplay = {
@@ -52,6 +71,7 @@ export type CoreInspectionInput = {
   activityEvents?: () => unknown[];
   currentActivity?: () => unknown[];
   sessionEntries?: () => unknown[];
+  sessionFile?: () => string | undefined;
   protectedPaths?: () => string[];
   // Extra directories the operator granted through the profile. The document
   // workspace lists them beside the project; without them it shows the project
@@ -72,6 +92,7 @@ export type CoreInspectionInput = {
   chatControl?: () => { state: "unbound" | "ready" | "replacement-pending" | "shutdown"; liveness: "idle" | "running" | "unknown";
     taskState: "none" | "active" | "pause-requested" | "paused" | "terminal" | "unknown"; identity: Record<string, any> | null; revisions: Record<string, any> | null;
     heldCount: number; queueRevision: string | null };
+  operationLiveness?: () => "idle" | "running" | "unknown";
 };
 
 export class CoreInspectionProvider implements WebUiReadModelProvider {
@@ -97,12 +118,15 @@ export class CoreInspectionProvider implements WebUiReadModelProvider {
     const projectionEpoch = this.#invalidationEpoch;
     const { buildWebUiInspectionProjection } = await loadCoreInspection();
     const retention = this.#input.eventStore.retention();
+    const control = this.#input.chatControl?.();
+    const operationLiveness = control?.state === "ready" ? control.liveness : this.#input.operationLiveness?.();
     const value = await buildWebUiInspectionProjection({
       cwd: this.#input.cwd, sessionId: this.#input.sessionId, runtimeInstanceId: this.#input.runtimeInstanceId,
       task: this.#input.task?.(), events: this.#input.activityEvents?.() ?? [], current: this.#input.currentActivity?.() ?? [],
       sessionEntries: this.#input.sessionEntries?.() ?? [], protectedPaths: this.#input.protectedPaths?.() ?? [],
       contextUsage: this.#input.contextUsage?.(), model: this.#input.model?.(), thinkingLevel: this.#input.thinkingLevel?.(),
-      eventCursor: this.#input.eventStore.currentCursor(), resyncRequired: this.#input.eventStore.resyncRequired(), eventReplay: retention
+      eventCursor: this.#input.eventStore.currentCursor(), resyncRequired: this.#input.eventStore.resyncRequired(), eventReplay: retention,
+      operationLiveness
     });
     // What the host will accept as an attachment is a property of the machine and
     // the model, not of chat control. The Gateway drives sessions without a chat
@@ -115,11 +139,15 @@ export class CoreInspectionProvider implements WebUiReadModelProvider {
       Object.assign(value.snapshot.capabilities.limits, { maxRequestBodyBytes: 11_250_000, maxAttachmentCount: 4,
         maxAttachmentFileBytes: 8_388_608, maxAttachmentTotalBytes: 16_777_216 });
     }
-    const control = this.#input.chatControl?.();
+    const projectedIdentity = value.snapshot.identity, projectedTaskRevision = value.snapshot.revision.taskRevision;
+    let sourceIdentityAligned = !this.#input.eventStore.resyncRequired()
+      && Object.values(value.sourceViews).every((document) => document === null || sourceDocumentMatches(document as Record<string, any>, value.snapshot));
     if (control?.state === "ready" && control.identity && control.revisions && !this.#input.eventStore.resyncRequired()) {
       const available = { available: true, reasonCode: null }, disabled = (reasonCode: string) => ({ available: false, reasonCode });
       const lifecycle = this.#input.lifecycleControl?.(), terminal = control.taskState === "terminal";
       const dispatchBlocked = lifecycle?.dispatchBlocked === true && lifecycle.state !== "terminal";
+      sourceIdentityAligned = sourceIdentityAligned && stableIdentityMatches(projectedIdentity, control.identity)
+        && (projectedIdentity.taskId === null || projectedTaskRevision === control.revisions.taskRevision);
       value.snapshot.identity = structuredClone(control.identity);
       value.snapshot.capabilities.identity = structuredClone(control.identity);
       for (const name of ["runtimeRevision", "taskRevision", "controlRevision", "sessionOptionRevision", "queueRevision"])
@@ -173,7 +201,12 @@ export class CoreInspectionProvider implements WebUiReadModelProvider {
         value.snapshot.capabilities.capabilities.approve = { status: "available", version: 1, reason: null,
           decisions: ["allow", "deny"], arbitration: "first-valid-cas" };
       }
-      if (control.identity.taskId && control.identity.taskRunId && control.revisions.taskRevision && value.snapshot.revision.workspaceRevision) {
+      if (control.identity.taskId && control.identity.taskRunId && control.revisions.taskRevision && value.snapshot.revision.workspaceRevision
+        && !sourceIdentityAligned) {
+        value.snapshot.capabilities.capabilities.reviewActions = { status: "unavailable", version: null,
+          reason: { code: "source-binding-resync-required",
+            message: "Source actions require a source projection bound to the current project, session and task." } };
+      } else if (control.identity.taskId && control.identity.taskRunId && control.revisions.taskRevision && value.snapshot.revision.workspaceRevision) {
         const mutationGuardAvailable = this.#input.sourceMutationGuardAvailable?.() === true;
         const chatSend = value.snapshot.capabilities.capabilities["control.chat"]?.status === "available"
           && value.snapshot.capabilities.capabilities["control.chat"].actions.send.available;
@@ -192,6 +225,16 @@ export class CoreInspectionProvider implements WebUiReadModelProvider {
         } };
       }
     }
+    if (sourceIdentityAligned) {
+      const binding = sourceBinding(value.snapshot);
+      for (const document of Object.values(value.sourceViews)) {
+        if (document && typeof document === "object") Object.assign(document as Record<string, any>, {
+          identity: structuredClone(value.snapshot.identity), snapshotBinding: structuredClone(binding)
+        });
+      }
+    }
+    Object.defineProperty(value, SOURCE_AUTHORITY_ALIGNED, { value: sourceIdentityAligned
+      && Object.values(value.sourceViews).every((document) => document === null || sourceDocumentMatches(document as Record<string, any>, value.snapshot)) });
     if (projectionEpoch === this.#invalidationEpoch) this.#cachedProjection = { at: Date.now(), value };
     return value;
   }
@@ -244,6 +287,8 @@ 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,
+      terminalDeliveryReceipt: readTerminalDeliveryReceipt(this.#input.cwd, activeTask),
+      terminalDeliveryEntries: terminalDeliverySessionEntries(this.#input.sessionFile?.(), this.#input.sessionId),
       generatedAt: snapshot.generatedAt, taskOutcome: typeof activeTask?.trace?.outcome === "string" ? activeTask.trace.outcome : null });
   }
   async queue(): Promise<unknown> {
@@ -258,15 +303,18 @@ export class CoreInspectionProvider implements WebUiReadModelProvider {
     const value = this.#input.approvalDetail?.(approvalRef); if (!value) throw new ReadModelNotFound(); return value;
   }
   async diff(view: SourceView, fileRef: string): Promise<unknown> {
-    const cacheKey = `${view}:${fileRef}`;
-    const cached = this.#diffCache.get(cacheKey);
-    if (cached && Date.now() - cached.at <= 200) return cached.value;
-    const { collectFileDiff, matchesProtectedPath } = await loadCoreInspection();
+    const requestEpoch = this.#invalidationEpoch;
     const projection = await this.#projection();
+    this.#requireSourceAuthority(projection, [view]);
     const source = view === "working-tree" ? projection.sourceViews.workingTree : projection.sourceViews[view];
     const file = source?.files.find((candidate: any) => candidate.fileRef === fileRef) as Record<string, any> | undefined;
     if (!source || !file) throw new ReadModelNotFound();
     const identity = projection.snapshot.identity;
+    const cacheKey = [...STABLE_IDENTITY_FIELDS.map((field) => identity[field]), projection.snapshot.revision.taskRevision,
+      projection.snapshot.sourceChanges.projectionRevision, view, source.viewRevision, file.fileRevision, fileRef].join("\0");
+    const cached = this.#diffCache.get(cacheKey);
+    if (cached && Date.now() - cached.at <= 200) return cached.value;
+    const { collectFileDiff, matchesProtectedPath } = await loadCoreInspection();
     const protectedPaths = this.#input.protectedPaths?.() ?? [];
     const value = await collectFileDiff({
       cwd: this.#input.cwd, identity, sourceView: source, fileRef,
@@ -278,8 +326,10 @@ export class CoreInspectionProvider implements WebUiReadModelProvider {
       selectedRepoPaths: file.pathDisplay === "exact-safe" ? [file.oldPath, file.path].filter((value: unknown): value is string => typeof value === "string") : undefined,
       isProtectedPath: (_root: string, repoPath: string) => Boolean(matchesProtectedPath(repoPath, protectedPaths))
     });
-    this.#diffCache.set(cacheKey, { at: Date.now(), value });
-    if (this.#diffCache.size > 128) this.#diffCache.delete(this.#diffCache.keys().next().value as string);
+    if (requestEpoch === this.#invalidationEpoch) {
+      this.#diffCache.set(cacheKey, { at: Date.now(), value });
+      if (this.#diffCache.size > 128) this.#diffCache.delete(this.#diffCache.keys().next().value as string);
+    }
     return value;
   }
 
@@ -288,6 +338,7 @@ export class CoreInspectionProvider implements WebUiReadModelProvider {
     // cache when deriving its exact Git/task preimage.
     this.invalidate();
     const projection = await this.#projection(), snapshot = projection.snapshot;
+    this.#requireSourceAuthority(projection, [view]);
     const identity = { ...snapshot.identity, agentOperationId: null, toolCallId: null };
     if (!identity.taskId || !identity.taskRunId || !snapshot.revision.taskRevision || !snapshot.revision.workspaceRevision) throw new ReadModelNotFound();
     const diff = await this.diff(view, fileRef) as any;
@@ -303,10 +354,11 @@ export class CoreInspectionProvider implements WebUiReadModelProvider {
   async #sourceMutation(action: "source.stage" | "source.unstage", fileRef: string) {
     this.invalidate();
     const projection = await this.#projection(), snapshot = projection.snapshot;
+    const view: SourceView = action === "source.stage" ? "working-tree" : "staged";
+    this.#requireSourceAuthority(projection, [view]);
     const identity = { ...snapshot.identity, agentOperationId: null, toolCallId: null };
     if (!identity.taskId || !identity.taskRunId || !snapshot.revision.taskRevision || !snapshot.revision.workspaceRevision || !snapshot.revision.indexRevision)
       throw new ReadModelNotFound();
-    const view: SourceView = action === "source.stage" ? "working-tree" : "staged";
     const source = view === "working-tree" ? projection.sourceViews.workingTree : projection.sourceViews.staged;
     if (!source?.files.some((file: any) => file.fileRef === fileRef)) throw new ReadModelNotFound();
     const diff = await this.diff(view, fileRef) as any;
@@ -330,6 +382,7 @@ export class CoreInspectionProvider implements WebUiReadModelProvider {
   async #sourceRevert(fileRef: string, hunkRef: string | null) {
     this.invalidate();
     const projection = await this.#projection(), snapshot = projection.snapshot;
+    this.#requireSourceAuthority(projection, ["working-tree", ...(projection.sourceViews.task ? ["task" as const] : [])]);
     const identity = { ...snapshot.identity, agentOperationId: null, toolCallId: null };
     if (!identity.taskId || !identity.taskRunId || !snapshot.revision.taskRevision || !snapshot.revision.workspaceRevision || !snapshot.revision.indexRevision)
       throw new ReadModelNotFound();
@@ -357,6 +410,7 @@ export class CoreInspectionProvider implements WebUiReadModelProvider {
 
   async sourceOpenAuthority(fileRef: string) {
     this.invalidate(); const projection = await this.#projection(), snapshot = projection.snapshot;
+    this.#requireSourceAuthority(projection, ["working-tree"]);
     const identity = { ...snapshot.identity, agentOperationId: null, toolCallId: null };
     if (!identity.taskId || !identity.taskRunId || !snapshot.revision.taskRevision || !snapshot.revision.workspaceRevision) return null;
     const { resolveSourceOpenTarget, matchesProtectedPath } = await loadCoreInspection(), protectedPaths = this.#input.protectedPaths?.() ?? [];
@@ -367,6 +421,7 @@ export class CoreInspectionProvider implements WebUiReadModelProvider {
 
   async commitSummary(): Promise<unknown> {
     this.invalidate(); const projection = await this.#projection(), snapshot = projection.snapshot;
+    this.#requireSourceAuthority(projection, ["staged"]);
     const identity = { ...snapshot.identity, agentOperationId: null, toolCallId: null };
     if (!identity.taskId || !identity.taskRunId || !snapshot.revision.taskRevision || !snapshot.revision.indexRevision) throw new ReadModelNotFound();
     const { projectDeterministicCommitSummary } = await loadCoreInspection();
@@ -424,12 +479,16 @@ export class CoreInspectionProvider implements WebUiReadModelProvider {
     this.invalidate(); return structuredClone((await this.#projection()).snapshot.revision);
   }
 
+  #requireSourceAuthority(projection: any, views: SourceView[]): void {
+    if (projection[SOURCE_AUTHORITY_ALIGNED] !== true || views.some((view) => {
+      const document = view === "working-tree" ? projection.sourceViews.workingTree : projection.sourceViews[view];
+      return !sourceDocumentMatches(document, projection.snapshot);
+    })) throw new ReadModelNotFound();
+  }
+
   replay(after: string | null, limit: number) {
     const replay = this.#input.eventStore.replay(after, limit);
-    if (replay.state !== "current") {
-      this.#cachedProjection = null;
-      this.#diffCache.clear();
-    }
+    if (replay.state !== "current") this.invalidate();
     return { ...replay, events: replay.events.map((event) => ({ cursor: event.eventCursor, value: event })) };
   }
   subscribe(listener: (event: StreamEvent) => void): () => void { this.#listeners.add(listener); return () => this.#listeners.delete(listener); }