@piagent/platform 1.6.1 → 1.8.0

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

@@ -5,8 +5,12 @@ import {
   buildWebUiRuntimeCommand,
   isWebUiRuntimeActionId
 } from "../../piagent-core/runtime/workflows/webui-runtime-command.ts";
+import {
+  PIAGENT_SERVICE_TIER_RECEIPT_ENTRY_TYPE,
+  parseServiceTierReceipt
+} from "../../piagent-core/runtime/model/service-tier-runtime.ts";
 import type { Catalog } from "../contracts/generated/session-catalog-v1.ts";
-import type { Action, Command, Receipt } from "../contracts/generated/runtime-command-v1.ts";
+import type { Action, Command, Output, Receipt } from "../contracts/generated/runtime-command-v1.ts";
 import { GatewayEventStore } from "./gateway-events.ts";
 import { SessionRuntimeSupervisor } from "./session-runtime-supervisor.ts";
 
@@ -15,6 +19,9 @@ const REVISION = /^[A-Za-z0-9][A-Za-z0-9._:~-]{0,159}$/;
 const MAX_REPLAYS = 200;
 
 type Replay = { digest: string; receipt: Receipt };
+type FastControlAssessment = Pick<Receipt, "state" | "resultCode" | "reasonCode">;
+
+const FAST_ACTIONS = new Set<Action>(["runtime.fast-status", "runtime.fast-on", "runtime.fast-off"]);
 
 function record(value: unknown): value is Record<string, unknown> {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
@@ -41,6 +48,33 @@ function commandDigest(command: Command): string {
     argument: command.argument, confirmed: command.confirmed })).digest("hex");
 }
 
+function normalizedOutputs(value: unknown): Receipt["outputs"] {
+  if (!Array.isArray(value)) return [];
+  return value.slice(0, 8).map((item) => {
+    if (!record(item)) return item;
+    const { details: _details, ...base } = item;
+    if (item.customType !== PIAGENT_SERVICE_TIER_RECEIPT_ENTRY_TYPE) return base;
+    const details = parseServiceTierReceipt(item.details);
+    return details ? { ...base, details } : base;
+  }) as Receipt["outputs"];
+}
+
+function assessFastControl(action: Action, outputs: readonly Output[]): FastControlAssessment | null {
+  if (!FAST_ACTIONS.has(action)) return null;
+  const candidates = outputs.filter((output) => output.customType === PIAGENT_SERVICE_TIER_RECEIPT_ENTRY_TYPE);
+  if (candidates.length === 0) return { state: "uncertain", resultCode: "effect-unknown", reasonCode: "fast-service-tier-receipt-missing" };
+  if (candidates.length !== 1) return { state: "uncertain", resultCode: "effect-unknown", reasonCode: "fast-service-tier-receipt-ambiguous" };
+  const details = parseServiceTierReceipt(candidates[0]?.details);
+  if (!details) return { state: "uncertain", resultCode: "effect-unknown", reasonCode: "fast-service-tier-receipt-invalid" };
+  if (action === "runtime.fast-on" && !details.enabled || action === "runtime.fast-off" && details.enabled) {
+    return { state: "uncertain", resultCode: "effect-unknown", reasonCode: "fast-service-tier-receipt-state-mismatch" };
+  }
+  if (details.reasonCode === "provider-not-supported") {
+    return { state: "rejected", resultCode: "unavailable", reasonCode: "provider-not-supported" };
+  }
+  return { state: "settled", resultCode: "completed", reasonCode: null };
+}
+
 export class RuntimeCommandController {
   readonly #catalog: () => Promise<Catalog>;
   readonly #runtimes: SessionRuntimeSupervisor;
@@ -89,11 +123,17 @@ export class RuntimeCommandController {
       const result = await this.#runtimes.runRuntimeCommand(command.sessionRef, built.command);
       const after = await this.#readyCatalog();
       const afterRow = after.sessions.find((session) => session.sessionRef === command.sessionRef);
-      const zeroTurnViolation = built.spec.effect === "read-only" && result.modelCallObserved;
-      const receipt = this.#receipt(command, zeroTurnViolation ? "uncertain" : "settled",
-        zeroTurnViolation ? "effect-unknown" : "completed",
-        zeroTurnViolation ? "read-only-command-started-model-call" : null,
-        afterRow?.sessionRevision ?? null, result.modelCallObserved, result.outputs as Receipt["outputs"]);
+      const outputs = normalizedOutputs(result.outputs);
+      const fastControl = assessFastControl(command.action, outputs);
+      const zeroTurnExpected = built.spec.effect === "read-only" || built.spec.effect === "session-setting";
+      const zeroTurnViolation = zeroTurnExpected && result.modelCallObserved;
+      const zeroTurnReason = built.spec.effect === "session-setting"
+        ? "session-setting-command-started-model-call"
+        : "read-only-command-started-model-call";
+      const receipt = this.#receipt(command, zeroTurnViolation ? "uncertain" : fastControl?.state ?? "settled",
+        zeroTurnViolation ? "effect-unknown" : fastControl?.resultCode ?? "completed",
+        zeroTurnViolation ? zeroTurnReason : fastControl?.reasonCode ?? null,
+        afterRow?.sessionRevision ?? null, result.modelCallObserved, outputs);
       this.#events.publish("session.changed", { catalogRevision: after.catalogRevision, session: afterRow ?? row });
       return this.#settle(command, digest, receipt);
     } catch (error) {

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

@@ -1,4 +1,17 @@
 import { redactSensitiveText } from "../../piagent-core/security/sensitive-data.js";
+import {
+  PIAGENT_SERVICE_TIER_RECEIPT_ENTRY_TYPE,
+  parseServiceTierReceipt,
+  type ServiceTierReceipt
+} from "../../piagent-core/runtime/model/service-tier-runtime.ts";
+
+type RuntimeCommandOutput = {
+  customType: string;
+  content: string;
+  truncated: boolean;
+  redacted: boolean;
+  details?: ServiceTierReceipt;
+};
 
 export async function executePermissionCommand(session: any,
   permissionMode: "read-only" | "workspace-write" | "trusted-full-access"): Promise<void> {
@@ -12,7 +25,7 @@ export async function executePermissionCommand(session: any,
 }
 
 export async function executeRuntimeCommand(session: any, command: string): Promise<{
-  outputs: Array<{ customType: string; content: string; truncated: boolean; redacted: boolean }>;
+  outputs: RuntimeCommandOutput[];
   modelCallObserved: boolean;
 }> {
   const before = Array.isArray(session.messages) ? session.messages.length : 0;
@@ -22,8 +35,10 @@ export async function executeRuntimeCommand(session: any, command: string): Prom
     const source = typeof message.content === "string" ? message.content : JSON.stringify(message.content ?? "");
     const bounded = source.slice(0, 12_000), redacted = redactSensitiveText(bounded);
     const rawType = String(message.customType ?? "runtime-output");
+    const details = rawType === PIAGENT_SERVICE_TIER_RECEIPT_ENTRY_TYPE
+      ? parseServiceTierReceipt(message.details) : null;
     return { customType: /^[A-Za-z0-9._-]{1,120}$/.test(rawType) ? rawType : "runtime-output", content: redacted.text,
-      truncated: source.length > bounded.length, redacted: redacted.redacted };
+      truncated: source.length > bounded.length, redacted: redacted.redacted, ...(details ? { details } : {}) };
   });
   return { outputs, modelCallObserved: added.some((message: any) => message?.role === "assistant") };
 }

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

@@ -2,6 +2,7 @@ import { createHmac } from "node:crypto";
 import path from "node:path";
 
 import { redactSensitiveText } from "../../piagent-core/security/sensitive-data.js";
+import { workflowCommandPattern } from "../../piagent-core/runtime/workflows/webui-workflow.ts";
 import type { Catalog, SessionRow } from "../contracts/generated/session-catalog-v1.ts";
 import type { MetadataSnapshot, SessionMetadata } from "./session-metadata-store.ts";
 import { projectRefForCwd, sessionRefForPath } from "../ownership/session-refs.ts";
@@ -54,7 +55,12 @@ function display(value: unknown, maximum: number, fallback: string): string {
   return (clean || fallback).slice(0, maximum);
 }
 
-const INTERNAL_FRESH_TRANSITION = /(?:^|\b)(?:\/fresh\s+(?:task|scout|be-to-fe)|(?:task|scout|be-to-fe):)\b[\s\S]{0,180}\bRead task intake from \.pi\/task-inbox\//i;
+const WORKFLOW_PATTERN = workflowCommandPattern({ aliases: false });
+const INTERNAL_FRESH_TRANSITION = new RegExp(
+  `(?:^|\\b)(?:\\/fresh\\s+(?:${WORKFLOW_PATTERN})|(?:${WORKFLOW_PATTERN}):)\\b[\\s\\S]{0,180}\\bRead task intake from \\.pi\\/task-inbox\\/`, "i"
+);
+const LEADING_WORKFLOW = new RegExp(`^\\/(?:fresh\\s+)?(?:${WORKFLOW_PATTERN})\\s+`, "i");
+const LEADING_WORKFLOW_LABEL = new RegExp(`^(?:${WORKFLOW_PATTERN}):\\s*`, "i");
 
 function atWordBoundary(value: string, maximum: number): string {
   if (value.length <= maximum) return value;
@@ -78,8 +84,8 @@ export function projectedSessionTitle(info: Pick<PiSessionInfo, "name" | "firstM
   const internal = INTERNAL_FRESH_TRANSITION.test(source) || INTERNAL_FRESH_TRANSITION.test(first)
     || /\.pi\/task-inbox\//i.test(source);
   const cleaned = display(source, 500, "")
-    .replace(/^\/(?:fresh\s+)?(?:task|scout|be-to-fe)\s+/i, "")
-    .replace(/^(?:task|scout|be-to-fe):\s*/i, "")
+    .replace(LEADING_WORKFLOW, "")
+    .replace(LEADING_WORKFLOW_LABEL, "")
     .replace(/^[-#*>\s]+/, "")
     // Keep underscores: the shared redactor deliberately emits
     // [REDACTED_SECRET], and title cleanup must not mutate that proof marker.

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

@@ -6,6 +6,7 @@ import { buildWebUiWorkflowCommand, isWebUiWorkflowId, type WebUiWorkflowId } fr
 import { GatewayEventStore } from "./gateway-events.ts";
 import { SessionCommandStore, type SessionAction, type SessionCommandIdentity } from "./session-command-store.ts";
 import { SessionRuntimeSupervisor } from "./session-runtime-supervisor.ts";
+import type { SessionSendResult } from "./session-prompt-dispatch.ts";
 import { SessionMetadataStore } from "./session-metadata-store.ts";
 
 const REF = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,159}$/;
@@ -125,9 +126,9 @@ export class SessionCommandController {
   }
 
   async #execute(command: SessionCommand): Promise<Receipt> {
-    const current = await this.#readyCatalog(), row = command.sessionRef ? current.sessions.find((item) => item.sessionRef === command.sessionRef) : null;
     const replay = this.#store.lookup(command);
     if (replay.state === "settled") return { ...replay.receipt!, deduplicated: true };
+    const current = await this.#readyCatalog(), row = command.sessionRef ? current.sessions.find((item) => item.sessionRef === command.sessionRef) : null;
     if (replay.state === "conflict") return this.#rejected(command, current, row, "invalid-command", "idempotency-payload-mismatch");
     if (replay.state === "unavailable") return this.#rejected(command, current, row, "unavailable", "session-command-journal-unavailable");
     if (replay.state === "pending") {
@@ -148,7 +149,9 @@ export class SessionCommandController {
     catch { return this.#rejected(command, current, row, "unavailable", "session-command-admission-failed"); }
     let targetSessionRef = command.sessionRef;
     let attachmentReservation: { commit(): void; release(): void } | null = null;
-    let sendAttempted = false;
+    let sendAttempted = false, dispatchCommitted = false;
+    let deferredDispatch: Pick<SessionSendResult, "dispatch" | "cancel"> | null = null;
+    let observedCatalog = current, observedRow = row;
     try {
       let resultCode: "created" | "acquired" | "released" | "started" | "queued" | "steered" | "aborted" | "model-changed" | "thinking-changed" | "permission-changed"
         | "renamed" | "pinned" | "unpinned" | "archived" | "unarchived" | "forked" | "no-change",
@@ -172,12 +175,15 @@ export class SessionCommandController {
         }
         const created = await this.#readyCatalog(), createdRow = created.sessions.find((item) => item.sessionRef === targetSessionRef);
         if (!createdRow) throw new Error("session-catalog-refresh-failed");
+        observedCatalog = created; observedRow = createdRow;
         if (command.payload.deferInitialMessage === true) resultCode = "created";
         else {
           const message = buildWebUiWorkflowCommand((command.payload.workflow as WebUiWorkflowId | undefined) ?? null,
             String(command.payload.message));
           const sent = await this.#runtimes.send(targetSessionRef, { delivery: "new-operation", message,
-            expectedOperationRef: null }, createdRow.sessionRevision);
+            messageRequestId: String(command.payload.messageRequestId), expectedOperationRef: null },
+          createdRow.sessionRevision, { deferDispatch: true });
+          deferredDispatch = sent;
           resultCode = sent.resultCode === "started" ? "started" : sent.resultCode; operationRef = sent.operationRef;
         }
       } else if (command.action === "session.acquire") { await this.#runtimes.acquire(command.sessionRef!); resultCode = "acquired"; }
@@ -186,6 +192,7 @@ export class SessionCommandController {
         await this.#runtimes.acquire(command.sessionRef!);
         const acquired = await this.#readyCatalog(), acquiredRow = acquired.sessions.find((item) => item.sessionRef === command.sessionRef);
         if (!acquiredRow) throw new Error("session-catalog-refresh-failed");
+        observedCatalog = acquired; observedRow = acquiredRow;
         const payload = command.payload as { delivery: "new-operation" | "follow-up" | "steer"; message: string;
           expectedOperationRef: string | null; messageRequestId: string; attachmentRefs: string[]; workflow?: WebUiWorkflowId };
         // Staged refs are claimed once, here, before the runtime is asked to
@@ -198,9 +205,10 @@ export class SessionCommandController {
         if (!this.#prepareAttachments && payload.attachmentRefs.length > 0) throw new Error("session-attachment-unavailable");
         sendAttempted = true;
         const message = buildWebUiWorkflowCommand(payload.workflow ?? null, prepared.text);
-        const sent = await this.#runtimes.send(command.sessionRef!, { ...payload, message, images: prepared.images },
-          acquiredRow.sessionRevision);
-        prepared.commit();
+        const sent = await this.#runtimes.send(command.sessionRef!, { ...payload, message,
+          messageRequestId: payload.messageRequestId, images: prepared.images },
+          acquiredRow.sessionRevision, { deferDispatch: true });
+        deferredDispatch = sent;
         resultCode = sent.resultCode; operationRef = sent.operationRef;
       } else if (command.action === "session.abort") {
         operationRef = String(command.payload.operationRef);
@@ -239,15 +247,27 @@ export class SessionCommandController {
       }
       const after = await this.#readyCatalog(), afterRow = after.sessions.find((item) => item.sessionRef === targetSessionRef);
       if (!afterRow) throw new Error("session-catalog-refresh-failed");
+      observedCatalog = after; observedRow = afterRow;
       const receipt = this.#settled(command, after, afterRow, resultCode, operationRef);
       try { this.#store.settle(command, receipt, this.#now()); }
-      catch { return this.#uncertain(command, after, afterRow, "session-command-settlement-not-durable"); }
+      catch {
+        deferredDispatch?.cancel?.(); try { attachmentReservation?.release(); } catch { /* staged refs remain unavailable to this command */ }
+        return this.#uncertain(command, after, afterRow, "session-command-settlement-not-durable");
+      }
+      if (attachmentReservation) {
+        try { attachmentReservation.commit(); } catch { /* prepared bytes remain dispatchable; the one-shot registry fails closed */ }
+        attachmentReservation = null;
+      }
       this.#events.publish("session.changed", { catalogRevision: after.catalogRevision, session: afterRow });
+      dispatchCommitted = true; deferredDispatch?.dispatch?.();
       return receipt;
     } catch (cause) {
-      const after = await this.#readyCatalog(), afterRow = after.sessions.find((item) => item.sessionRef === targetSessionRef) ?? row;
+      if (!dispatchCommitted) deferredDispatch?.cancel?.();
+      let after = observedCatalog;
+      try { after = await this.#readyCatalog(); } catch { /* the last proven catalog remains authoritative */ }
+      const afterRow = after.sessions.find((item) => item.sessionRef === targetSessionRef) ?? observedRow;
       const message = cause instanceof Error ? cause.message : "session-command-failed";
-      const noDispatchEffect = command.action === "session.send" && (!sendAttempted
+      const noDispatchEffect = command.action === "session.send" && (!sendAttempted || Boolean(deferredDispatch && !dispatchCommitted)
         || /^(session-runtime-unavailable|session-operation-conflict|session-owner-conflict|session-runtime-busy)$/.test(message));
       if (attachmentReservation) {
         try { if (noDispatchEffect) attachmentReservation.release(); else attachmentReservation.commit(); }

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

@@ -25,15 +25,8 @@ export function effectiveThinkingLevel(session: any): string | null {
   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. */ }
+export function inspectEffectiveSessionOptions(session: any, modelRef: string | null,
+  thinkingLevel: string): EffectiveSessionOptions {
   const effectiveModel = effectiveModelRef(session), effectiveThinking = effectiveThinkingLevel(session);
   if (!effectiveModel) return { state: "unknown", modelRef: null,
     thinkingLevel: effectiveThinking, reasonCode: "session-model-effect-unknown" };

package/packages/piagent-webui/gateway/session-inspection-registry.ts

@@ -108,11 +108,13 @@ export class SessionInspectionRegistry {
   readonly #models?: ModelRuntime;
   readonly #projects?: ProjectSource;
   readonly #mcpAuth?: McpAuthBroker;
+  readonly #operationLiveness: ((sessionRef: string) => "idle" | "running" | "unknown") | null;
   readonly #providers = new Map<string, { modifiedAt: string; provider: CoreInspectionProvider }>();
 
   constructor(options: { gatewayInstanceRef: string; host: PiHost; key: Buffer; packageRoot: string; agentDir?: string; models?: ModelRuntime; projects?: ProjectSource;
     mcpAuth?: McpAuthBroker; listSessions?: () => Promise<PiSessionInfo[]>;
-    openLiveSession?: (sessionRef: string) => ReturnType<PiHost["SessionManager"]["open"]> | null }) {
+    openLiveSession?: (sessionRef: string) => ReturnType<PiHost["SessionManager"]["open"]> | null;
+    operationLiveness?: (sessionRef: string) => "idle" | "running" | "unknown" }) {
     this.#gatewayInstanceRef = options.gatewayInstanceRef;
     this.#host = options.host;
     this.#listSessions = options.listSessions ?? (() => options.host.SessionManager.listAll());
@@ -123,6 +125,7 @@ export class SessionInspectionRegistry {
     this.#models = options.models;
     this.#projects = options.projects;
     this.#mcpAuth = options.mcpAuth;
+    this.#operationLiveness = options.operationLiveness ?? null;
   }
 
   #connectionRef(server: { scope: string; origin: string; name: string }): string {
@@ -214,10 +217,9 @@ export class SessionInspectionRegistry {
       return [{ modelRef: webUiModelRef(provider, modelId), provider, modelId, displayName: safeName(value.name ?? modelId),
         reasoning: value.reasoning, imageInput: inputs ? inputs.includes("image") : null, thinkingLevels }];
     });
-    // Keep the WebUI new-session baseline deterministic and visible. If the
-    // preferred model is not authenticated, the host's own default remains the
-    // safe fallback instead of silently substituting another catalog entry.
-    const defaultModel = models.find((value) => value.provider === "openai-codex" && value.modelId === "gpt-5.6-sol");
+    // Only offer a default present in the authenticated host catalog. Retain
+    // the previous Sol baseline for accounts that have not received GPT-6 yet.
+    const defaultModel = ["gpt-6-sol", "gpt-5.6-sol"].map((id) => models.find((value) => value.provider === "openai-codex" && value.modelId === id)).find(Boolean);
     return { schemaVersion: 1, version: "piagent-session-creation-options-v1", generatedAt: new Date().toISOString(),
       projects: [...projects.values()].slice(0, 200), models,
       defaultModelRef: defaultModel?.modelRef ?? null, defaultThinkingLevel: defaultModel ? "high" : null,
@@ -255,7 +257,12 @@ export class SessionInspectionRegistry {
       eventStore,
       task: () => safeRead(() => activeSessionTask(info.cwd, info.id), undefined),
       activityEvents: () => safeRead(() => readContextTelemetry(info.cwd, { limit: 5_000 }), []),
-      sessionEntries: () => entries,
+      // A provider can outlive the turn that created it (notably while a new
+      // session has not reached the host index yet). Read the branch at request
+      // time so transcript/activity projection cannot freeze at the pre-turn
+      // snapshot while the live manager continues appending entries.
+      sessionEntries: () => safeRead(() => manager.getBranch(), []),
+      sessionFile: () => info.path,
       protectedPaths: () => runtimeProtectedPaths(this.#packageRoot, info.cwd),
       // The document workspace lists the project plus whatever the operator
       // granted in the profile. Without this it silently shows the project only,
@@ -269,6 +276,7 @@ export class SessionInspectionRegistry {
       contextUsage: () => contextUsage,
       model: () => model,
       thinkingLevel: () => context.thinkingLevel,
+      operationLiveness: () => this.#operationLiveness?.(sessionRef) ?? "unknown",
       approvalProjection: () => piApprovalBroker.projection(info.cwd, info.id),
       approvalDetail: (approvalRef) => piApprovalBroker.detail(info.cwd, info.id, approvalRef)
     });

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

@@ -0,0 +1,28 @@
+import { settleIndependentWebUiOperation } from "../../piagent-core/extensions/acceptance-independent-registry.js";
+import type { activeSessionTask } from "../../piagent-core/extensions/task-state.js";
+import type { GatewaySessionStream } from "./gateway-session-stream.ts";
+import type { ScopedBrokerRouter } from "./session-runtime-factory.ts";
+
+type SettlementInput = { sessionId: string; operationRef: string; messageRequestId: string | null;
+  manager: any; stream: Pick<GatewaySessionStream, "markBlocked" | "markError"> };
+
+export function createSessionOperationSettlement(options: {
+  scopedBrokerRouter?: ScopedBrokerRouter;
+  compositeSettlementEvidence?(): unknown | Promise<unknown>;
+}) {
+  const router = options.scopedBrokerRouter;
+  const evidence = options.compositeSettlementEvidence ?? (router ? () => router.settlementEvidence()
+    : () => { throw new Error("composite-settlement-evidence-unavailable"); });
+  return async (cwd: string, task: ReturnType<typeof activeSessionTask>, input: SettlementInput) => {
+    const { sessionId, operationRef, messageRequestId, manager, stream } = input;
+    const settlement = await settleIndependentWebUiOperation(cwd, task,
+      { operationRef, messageRequestId, manager, evidence });
+    if (settlement.status === "blocked") stream.markBlocked("composite-settlement-blocked");
+    if (settlement.status === "not-applicable" && task?.trace?.outcome === "completed"
+      && router?.discardUnusedSettlement && messageRequestId) {
+      try { router.discardUnusedSettlement({ sessionId, operationRef, messageRequestId }); }
+      catch { stream.markError("scoped-operation-retirement-failed"); }
+    }
+    return settlement;
+  };
+}

package/packages/piagent-webui/gateway/session-prompt-dispatch.ts

@@ -0,0 +1,37 @@
+import { GatewaySessionStream } from "./gateway-session-stream.ts";
+import { waitForOperationStart } from "./session-operation-start.ts";
+
+export type LaunchedSessionPrompt = {
+  started: Promise<void>;
+  completion: Promise<void>;
+};
+export type SessionSendResult = { resultCode: "started" | "queued" | "steered"; operationRef: string;
+  dispatch?: () => void; cancel?: () => boolean };
+
+/**
+ * Launches host prompt work on the next event-loop turn. Gateway command
+ * admission can therefore persist and return its exact operation receipt
+ * before expensive synchronous Pi hooks begin, while direct runtime callers
+ * can still await the observed agent start through `started`.
+ */
+export function launchSessionPrompt(options: {
+  stream: GatewaySessionStream;
+  invoke(): Promise<void> | void;
+  finish(): Promise<void>;
+  canInvoke(): boolean;
+}): LaunchedSessionPrompt {
+  const prompt = new Promise<void>((resolve, reject) => {
+    setImmediate(() => {
+      if (!options.canInvoke()) { reject(new Error("session-operation-cancelled-before-dispatch")); return; }
+      try { Promise.resolve(options.invoke()).then(resolve, reject); }
+      catch (error) { reject(error); }
+    });
+  });
+  const observed = waitForOperationStart(options.stream, prompt);
+  const lifecycle = observed.then(async (mode) => {
+    if (mode === "deferred") await options.stream.settled();
+    else await Promise.race([options.stream.settled(), prompt]);
+  });
+  const completion = lifecycle.then(options.finish, () => { options.stream.markError(); return options.finish(); });
+  return { started: observed.then(() => undefined), completion };
+}

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

@@ -0,0 +1,36 @@
+import { boundedResult } from "./session-operation-watchdog.ts";
+
+type ClosingRuntime = {
+  operationRef: string | null;
+  settling: boolean;
+  completion: Promise<void> | null;
+  stream: { markError(reasonCode: string): void } | null;
+};
+
+/** Drain ordinary settlement, then revoke authority for work that cannot finish. */
+export async function closeSessionRuntimes<T extends ClosingRuntime>(options: {
+  opening: ReadonlyMap<string, Promise<unknown>>;
+  active: ReadonlyMap<string, T>;
+  terminationTimeoutMs: number;
+  abort(sessionRef: string, operationRef: string): Promise<void>;
+  release(sessionRef: string): Promise<unknown>;
+  quarantine(sessionRef: string, operationRef: string, active: T, reasonCode: string): Promise<void>;
+}): Promise<void> {
+  await Promise.allSettled([...options.opening.values()]);
+  await Promise.allSettled([...options.active.entries()].filter(([, active]) => active.operationRef)
+    .map(([sessionRef, active]) => options.abort(sessionRef, active.operationRef!)));
+  await Promise.allSettled([...options.active.entries()].map(async ([sessionRef, active]) => {
+    // Normal settlement owns its completion promise and cannot be aborted.
+    if (active.settling && active.completion) {
+      await boundedResult(active.completion, options.terminationTimeoutMs);
+    }
+    if (options.active.get(sessionRef) !== active) return;
+    if (active.operationRef && active.stream) {
+      const reasonCode = "session-runtime-shutdown-incomplete";
+      active.stream.markError(reasonCode);
+      await options.quarantine(sessionRef, active.operationRef, active, reasonCode);
+      return;
+    }
+    await options.release(sessionRef);
+  }));
+}