@piagent/platform 1.6.0 → 1.7.1

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 {
@@ -255,7 +258,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 +277,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-lifecycle.ts

@@ -0,0 +1,237 @@
+import { hasVisibleText } from "../shared/text-visibility.ts";
+
+export type SessionOperationPhase = "pending" | "running" | "retry" | "compaction" | "settled";
+
+export type SessionOperationRetryPolicy = Readonly<{
+  maximumAttempts: number;
+  maximumDelayMs: number;
+}>;
+
+export type SessionOperationRetryPolicyOptions = Partial<SessionOperationRetryPolicy>;
+
+export type SessionOperationObservation = Readonly<{
+  accepted: boolean;
+  phase: SessionOperationPhase;
+  retry: "none" | "allowed" | "abort";
+  reasonCode: string | null;
+}>;
+
+const DEFAULT_RETRY_POLICY: SessionOperationRetryPolicy = Object.freeze({
+  // Pi's provider retry is useful before a response exists, but a long retry
+  // chain burns quota and keeps the browser in Working. One automatic retry
+  // absorbs an ordinary transient failure without replaying a persistent one.
+  maximumAttempts: 1,
+  maximumDelayMs: 8_000
+});
+
+function boundedInteger(value: unknown, fallback: number, minimum: number, maximum: number): number {
+  if (value === undefined) return fallback;
+  if (!Number.isSafeInteger(value) || Number(value) < minimum || Number(value) > maximum) {
+    throw new Error("session-operation-retry-policy-invalid");
+  }
+  return Number(value);
+}
+
+export function sessionOperationRetryPolicy(
+  options: SessionOperationRetryPolicyOptions = {}
+): SessionOperationRetryPolicy {
+  return Object.freeze({
+    maximumAttempts: boundedInteger(options.maximumAttempts, DEFAULT_RETRY_POLICY.maximumAttempts, 0, 10),
+    maximumDelayMs: boundedInteger(options.maximumDelayMs, DEFAULT_RETRY_POLICY.maximumDelayMs, 0, 300_000)
+  });
+}
+
+function correlationRef(event: any): string | null {
+  for (const key of ["operationRef", "agentOperationId", "operationId"]) {
+    if (typeof event?.[key] === "string" && event[key]) return event[key];
+  }
+  return null;
+}
+
+function visibleAssistantContent(message: any): boolean {
+  if (typeof message?.content === "string") return hasVisibleText(message.content);
+  if (!Array.isArray(message?.content)) return false;
+  return message.content.some((item: any) => {
+    if (item?.type === "text") return hasVisibleText(item.text);
+    // Images and every model-emitted tool/server-tool block are observable
+    // output even when they do not contain user-visible text.
+    return ["image", "image_url", "toolCall", "tool_call", "tool_use", "server_tool_use"]
+      .includes(String(item?.type ?? ""));
+  });
+}
+
+function attempt(value: unknown): number | null {
+  return Number.isSafeInteger(value) && Number(value) >= 1 ? Number(value) : null;
+}
+
+function delay(value: unknown): number | null {
+  return Number.isSafeInteger(value) && Number(value) >= 0 ? Number(value) : null;
+}
+
+/**
+ * Operation-local authority for provider retry, compaction and settlement.
+ *
+ * Pi's pinned host owns the actual provider retry. This state machine owns the
+ * stricter Piagent admission decision and is shared by the Gateway stream and
+ * runtime supervisor. It never treats compaction as a provider retry, and it
+ * fails closed once assistant output or a tool call makes replay unsafe.
+ */
+export class SessionOperationLifecycle {
+  readonly operationRef: string;
+  readonly retryPolicy: SessionOperationRetryPolicy;
+  #phase: SessionOperationPhase = "pending";
+  #started = false;
+  #hostSettled = false;
+  #terminal = false;
+  #visibleAssistantOutput = false;
+  #toolCallObserved = false;
+  #lastRetryAttempt = 0;
+  #activeRetryAttempt: number | null = null;
+  #retryAbortRequired = false;
+
+  constructor(options: {
+    operationRef: string;
+    retryPolicy?: SessionOperationRetryPolicyOptions | SessionOperationRetryPolicy;
+  }) {
+    this.operationRef = options.operationRef;
+    this.retryPolicy = sessionOperationRetryPolicy(options.retryPolicy);
+  }
+
+  get phase(): SessionOperationPhase { return this.#phase; }
+  get started(): boolean { return this.#started; }
+  get hostSettled(): boolean { return this.#hostSettled; }
+  get terminal(): boolean { return this.#terminal; }
+  get replayUnsafe(): boolean { return this.#visibleAssistantOutput || this.#toolCallObserved; }
+  get retryAbortRequired(): boolean { return this.#retryAbortRequired; }
+
+  forceHostSettlement(): void {
+    this.#started = true;
+    this.#hostSettled = true;
+    this.#phase = "settled";
+  }
+
+  markTerminal(): boolean {
+    if (this.#terminal) return false;
+    this.#terminal = true;
+    this.#hostSettled = true;
+    this.#phase = "settled";
+    return true;
+  }
+
+  observe(event: any): SessionOperationObservation {
+    if (this.#terminal || this.#hostSettled) return this.#ignored("operation-event-after-settlement");
+    const correlated = correlationRef(event);
+    if (correlated && correlated !== this.operationRef) return this.#ignored("operation-correlation-mismatch");
+    const type = String(event?.type ?? "");
+
+    if (type === "agent_start") {
+      this.#started = true;
+      this.#phase = "running";
+      return this.#accepted();
+    }
+    if (type === "agent_settled") {
+      this.#started = true;
+      this.#hostSettled = true;
+      this.#phase = "settled";
+      return this.#accepted();
+    }
+
+    // Direct stream fixtures and some deferred command hosts begin with a
+    // message/tool event. Treat that as an observed start while still refusing
+    // uncorrelated retry/compaction lifecycle events before any operation work.
+    if (["message_start", "message_update", "message_end", "tool_execution_start",
+      "tool_execution_update", "tool_execution_end", "turn_start", "turn_end"].includes(type)) {
+      this.#started = true;
+      if (this.#phase === "pending") this.#phase = "running";
+    }
+
+    if (type === "message_update") {
+      const update = event?.assistantMessageEvent;
+      if (update?.type === "text_delta" && hasVisibleText(update.delta)) this.#visibleAssistantOutput = true;
+      if (visibleAssistantContent(event?.message)) this.#visibleAssistantOutput = true;
+      return this.#accepted();
+    }
+    if (type === "message_end" && event?.message?.role === "assistant") {
+      if (visibleAssistantContent(event.message)) this.#visibleAssistantOutput = true;
+      return this.#accepted();
+    }
+    if (type === "tool_execution_start") {
+      this.#toolCallObserved = true;
+      return this.#accepted();
+    }
+
+    if (type === "agent_end" && event?.willRetry === true && this.replayUnsafe) {
+      return this.#abortRetry("automatic-retry-replay-unsafe");
+    }
+    if (type === "auto_retry_start") return this.#retryStarted(event);
+    if (type === "auto_retry_end") return this.#retryEnded(event);
+
+    // Summarization retries belong to compaction and never consume or inherit
+    // the provider-turn retry budget.
+    if (type === "compaction_start") {
+      if (!this.#started) return this.#ignored("operation-event-before-start");
+      if (this.#phase === "retry") this.#retryAbortRequired = true;
+      this.#phase = "compaction";
+      return this.#retryAbortRequired
+        ? this.#abortRetry("automatic-retry-compaction-overlap")
+        : this.#accepted();
+    }
+    if (type === "compaction_end") {
+      if (this.#phase !== "compaction") return this.#ignored("compaction-event-stale");
+      this.#phase = "running";
+      return this.#accepted();
+    }
+    if (["summarization_retry_scheduled", "summarization_retry_attempt_start",
+      "summarization_retry_finished"].includes(type)) {
+      return this.#phase === "compaction" ? this.#accepted() : this.#ignored("compaction-event-stale");
+    }
+    return this.#accepted();
+  }
+
+  #retryStarted(event: any): SessionOperationObservation {
+    if (!this.#started) return this.#ignored("operation-event-before-start");
+    const currentAttempt = attempt(event?.attempt), currentDelay = delay(event?.delayMs);
+    if (currentAttempt === null || currentDelay === null) return this.#abortRetry("automatic-retry-metadata-invalid");
+    if (currentAttempt === this.#lastRetryAttempt) return this.#ignored("automatic-retry-event-duplicate");
+    if (currentAttempt !== this.#lastRetryAttempt + 1) {
+      this.#activeRetryAttempt = currentAttempt;
+      this.#phase = "retry";
+      return this.#abortRetry("automatic-retry-attempt-stale");
+    }
+    this.#lastRetryAttempt = currentAttempt;
+    this.#activeRetryAttempt = currentAttempt;
+    if (this.#phase === "compaction") return this.#abortRetry("automatic-retry-compaction-overlap");
+    this.#phase = "retry";
+    if (this.replayUnsafe) return this.#abortRetry("automatic-retry-replay-unsafe");
+    if (currentAttempt > this.retryPolicy.maximumAttempts) return this.#abortRetry("automatic-retry-attempt-limit");
+    if (currentDelay > this.retryPolicy.maximumDelayMs) return this.#abortRetry("automatic-retry-delay-limit");
+    return { accepted: true, phase: this.#phase, retry: "allowed", reasonCode: null };
+  }
+
+  #retryEnded(event: any): SessionOperationObservation {
+    const currentAttempt = attempt(event?.attempt);
+    if (currentAttempt === null || currentAttempt !== this.#activeRetryAttempt) {
+      return this.#ignored("automatic-retry-event-stale");
+    }
+    this.#activeRetryAttempt = null;
+    // Keep the highest attempt for the whole logical operation so hosts that
+    // emit retry_end between attempts still have a monotonic sequence. Keep an
+    // abort latched too: retry_end can arrive synchronously before the
+    // supervisor's cancellation microtask observes the host AbortController.
+    if (this.#phase === "retry") this.#phase = "running";
+    return this.#accepted();
+  }
+
+  #abortRetry(reasonCode: string): SessionOperationObservation {
+    this.#retryAbortRequired = true;
+    return { accepted: true, phase: this.#phase, retry: "abort", reasonCode };
+  }
+
+  #accepted(): SessionOperationObservation {
+    return { accepted: true, phase: this.#phase, retry: "none", reasonCode: null };
+  }
+
+  #ignored(reasonCode: string): SessionOperationObservation {
+    return { accepted: false, phase: this.#phase, retry: "none", reasonCode };
+  }
+}

package/packages/piagent-webui/gateway/session-operation-retry-control.ts

@@ -0,0 +1,38 @@
+type RetryObservation = { retry?: unknown } | null | undefined;
+
+function invoke(action: (() => unknown) | null): void {
+  if (!action) return;
+  try {
+    const result = action();
+    if (result && typeof (result as PromiseLike<unknown>).then === "function") {
+      void Promise.resolve(result).catch(() => undefined);
+    }
+  } catch { /* the operation watchdog remains the terminal authority */ }
+}
+
+/**
+ * Cancels a host-owned provider retry without replaying the prompt. Pinned Pi
+ * creates its retry AbortController immediately after auto_retry_start is
+ * emitted, so the microtask always runs before even a zero-millisecond timer.
+ */
+export class SessionOperationRetryCancellation {
+  readonly #session: any;
+  #fallbackIssued = false;
+
+  constructor(session: any) { this.#session = session; }
+
+  observe(observation: RetryObservation): void {
+    if (observation?.retry !== "abort") return;
+    if (typeof this.#session?.abortRetry === "function") {
+      const cancel = () => invoke(() => this.#session.abortRetry());
+      cancel();
+      queueMicrotask(cancel);
+      return;
+    }
+    // Unknown hosts fail closed once. Replaying a tool-capable turn is more
+    // dangerous than ending the logical operation with an explicit error.
+    if (this.#fallbackIssued || typeof this.#session?.abort !== "function") return;
+    this.#fallbackIssued = true;
+    invoke(() => this.#session.abort());
+  }
+}

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-operation-watchdog.ts

@@ -1,3 +1,5 @@
+import { SessionOperationRetryCancellation } from "./session-operation-retry-control.ts";
+
 export type SessionOperationDeadlineReason = "operation-inactivity-timeout" | "operation-deadline-exceeded";
 
 export type SessionOperationDeadlinePolicy = Readonly<{
@@ -113,10 +115,15 @@ export class SessionOperationWatchdog {
 export function armSessionOperationWatchdog(options: {
   watchdog: SessionOperationWatchdog;
   subscribe(listener: (event: unknown) => void): unknown;
-  observe(event: unknown): void;
+  observe(event: unknown): unknown;
+  retrySession?: any;
   expire(reason: SessionOperationDeadlineReason): void;
 }): () => void {
-  const unsubscribe = options.subscribe((event) => { options.watchdog.progress(); options.observe(event); });
+  const retry = new SessionOperationRetryCancellation(options.retrySession);
+  const unsubscribe = options.subscribe((event) => {
+    options.watchdog.progress();
+    retry.observe(options.observe(event) as { retry?: unknown } | null | undefined);
+  });
   if (typeof unsubscribe !== "function") throw new Error("session-operation-subscribe-invalid");
   try { options.watchdog.start(options.expire); }
   catch (error) { try { unsubscribe(); } catch { /* authority is quarantined by the caller */ } throw error; }

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