@piagent/platform 1.6.1 → 1.8.0

package/packages/piagent-webui/extension/source-mutation-controller.ts

@@ -35,11 +35,19 @@ function timestamp(value: unknown): value is string {
   if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value)) return false;
   const parsed = Date.parse(value); return Number.isFinite(parsed) && new Date(parsed).toISOString() === value;
 }
+function nullableRevision(value: unknown): value is string | null { return value === null || typeof value === "string" && REVISION.test(value); }
 function wireIdentity(value: BridgeIdentity): BridgeIdentity { return { projectRef: value.projectRef, runtimeInstanceId: value.runtimeInstanceId,
   sessionRef: value.sessionRef, taskId: value.taskId, taskRunId: value.taskRunId, agentOperationId: null, toolCallId: null }; }
 function wireRevisions(value: Record<string, any>): BridgeRevisions { return { runtimeRevision: value.runtimeRevision, taskRevision: value.taskRevision,
   controlRevision: value.controlRevision, workspaceRevision: value.workspaceRevision, indexRevision: value.indexRevision,
   approvalRevision: value.approvalRevision, sessionOptionRevision: value.sessionOptionRevision, queueRevision: value.queueRevision }; }
+function replayIdentityDisposition(record: Pick<SourceMutationEvidenceRecord, "projectRef" | "runtimeInstanceId" | "sessionRef" | "taskId" | "taskRunId">,
+  identity: BridgeIdentity): "task-identity-mismatch" | "runtime-or-session-replaced" | null {
+  if (record.taskId !== identity.taskId || record.taskRunId !== identity.taskRunId) return "task-identity-mismatch";
+  if (record.projectRef !== identity.projectRef || record.runtimeInstanceId !== identity.runtimeInstanceId || record.sessionRef !== identity.sessionRef)
+    return "runtime-or-session-replaced";
+  return null;
+}
 
 function receiptFromRecord(record: SourceMutationEvidenceRecord, deduplicated: boolean): SourceMutationReceipt {
   if (record.action === "source.revert") throw new Error("source-mutation-evidence-action-mismatch");
@@ -109,8 +117,9 @@ export class SourceMutationController {
     if (prior.length) {
       if (prior.some((record) => record.commandId !== command.commandId || record.idempotencyKeyDigest !== keyDigest || record.actionDigest !== command.actionDigest
         || record.action !== command.action)) return this.#reject(command, "idempotency-payload-mismatch", "idempotency-payload-mismatch", false);
-      if (prior.some((record) => record.runtimeInstanceId !== identity.runtimeInstanceId || record.sessionRef !== identity.sessionRef))
-        return this.#reject(command, "identity-mismatch", "runtime-or-session-replaced", false);
+      const dispositions = prior.map((record) => replayIdentityDisposition(record, identity)).filter(Boolean);
+      if (dispositions.length) return this.#reject(command, "identity-mismatch",
+        dispositions.includes("task-identity-mismatch") ? "task-identity-mismatch" : "runtime-or-session-replaced", false);
       return receiptFromRecord(prior.at(-1)!, true);
     }
     const now = this.#now().getTime();
@@ -122,6 +131,20 @@ export class SourceMutationController {
     let resolved: { projection: SourceMutationProjection; authority: SourceMutationAuthority | null };
     try { resolved = await this.#resolve(command.action, command.payload.fileRef); }
     catch { return this.#reject(command, "capability-unavailable", "mutation-preview-unavailable", true); }
+    const rebound = this.#bridge.snapshot();
+    if (rebound.state !== "ready" || !rebound.identity || !rebound.revisions)
+      return this.#reject(command, "resync-required", "mutation-binding-unavailable-after-preview", true);
+    const reboundIdentity = wireIdentity(rebound.identity), reboundRevisions = wireRevisions(rebound.revisions);
+    if (!same(reboundIdentity, identity)) {
+      const taskChanged = reboundIdentity.taskId !== identity.taskId || reboundIdentity.taskRunId !== identity.taskRunId;
+      return this.#reject(command, "identity-mismatch", taskChanged ? "task-identity-mismatch" : "runtime-or-session-replaced", false);
+    }
+    if (rebound.taskState === "terminal") return this.#reject(command, "terminal-task", "task-terminal-after-preview", false);
+    if (rebound.liveness !== "idle") return this.#reject(command, "capability-unavailable", "agent-not-idle-after-preview", true);
+    if (command.expectedRevisions.runtimeRevision !== reboundRevisions.runtimeRevision
+      || command.expectedRevisions.taskRevision !== reboundRevisions.taskRevision
+      || command.expectedRevisions.controlRevision !== reboundRevisions.controlRevision)
+      return this.#reject(command, "stale-revision", "stale-task-control-revision-after-preview", true);
     if (!resolved.authority || resolved.projection.state !== "ready" || !resolved.projection.target)
       return this.#reject(command, "capability-unavailable", resolved.projection.reasonCode ?? "mutation-preview-unavailable", true);
     const target = resolved.projection.target;
@@ -185,8 +208,11 @@ export class SourceMutationController {
       || command.identity.agentOperationId !== null || command.identity.toolCallId !== null) return "invalid-command-identity";
     const preimageKeys = [...REVISION_KEYS, "workspacePreimage", "indexPreimage", "patchPreimage"];
     if (!exactKeys(command.expectedRevisions, preimageKeys) || !REVISION.test(command.expectedRevisions.runtimeRevision)
-      || !REVISION.test(command.expectedRevisions.taskRevision ?? "") || !REVISION.test(command.expectedRevisions.workspaceRevision ?? "")
+      || !REVISION.test(command.expectedRevisions.taskRevision ?? "") || !REVISION.test(command.expectedRevisions.controlRevision ?? "")
+      || !REVISION.test(command.expectedRevisions.workspaceRevision ?? "")
       || !REVISION.test(command.expectedRevisions.indexRevision ?? "") || !WORKSPACE.test(command.expectedRevisions.workspacePreimage)
+      || ![command.expectedRevisions.approvalRevision, command.expectedRevisions.sessionOptionRevision,
+        command.expectedRevisions.queueRevision].every(nullableRevision)
       || !DIGEST.test(command.expectedRevisions.indexPreimage) || !DIGEST.test(command.expectedRevisions.patchPreimage)) return "invalid-mutation-authority";
     if (!exactKeys(command.payload, ["fileRef", "hunkRefs", "contentDigest"]) || !REF.test(command.payload.fileRef)
       || !Array.isArray(command.payload.hunkRefs) || command.payload.hunkRefs.length > 128

package/packages/piagent-webui/extension/source-open-controller.ts

@@ -33,6 +33,13 @@ function revisions(value: Record<string, any>, record?: SourceHandoffRecord): Br
   taskRevision: record?.taskRevision ?? value.taskRevision, controlRevision: value.controlRevision,
   workspaceRevision: record?.workspaceRevision ?? value.workspaceRevision, indexRevision: value.indexRevision,
   approvalRevision: value.approvalRevision, sessionOptionRevision: value.sessionOptionRevision, queueRevision: value.queueRevision }; }
+function replayIdentityDisposition(record: Pick<SourceHandoffRecord, "projectRef" | "runtimeInstanceId" | "sessionRef" | "taskId" | "taskRunId">,
+  current: BridgeIdentity): "task-identity-mismatch" | "runtime-or-session-replaced" | null {
+  if (record.taskId !== current.taskId || record.taskRunId !== current.taskRunId) return "task-identity-mismatch";
+  if (record.projectRef !== current.projectRef || record.runtimeInstanceId !== current.runtimeInstanceId || record.sessionRef !== current.sessionRef)
+    return "runtime-or-session-replaced";
+  return null;
+}
 
 export class SourceOpenController {
   readonly #bridge: SameSessionPiBridge; readonly #root: string; readonly #resolve: (fileRef: string) => Promise<SourceOpenAuthority | null>;
@@ -55,8 +62,9 @@ export class SourceOpenController {
     if (prior.length) {
       if (prior.some((record) => record.commandId !== command.commandId || record.idempotencyKeyDigest !== keyDigest || record.actionDigest !== command.actionDigest))
         return this.#reject(command, "idempotency-payload-mismatch", "idempotency-payload-mismatch", false);
-      if (prior.some((record) => record.runtimeInstanceId !== currentIdentity.runtimeInstanceId || record.sessionRef !== currentIdentity.sessionRef))
-        return this.#reject(command, "identity-mismatch", "runtime-or-session-replaced", false);
+      const dispositions = prior.map((record) => replayIdentityDisposition(record, currentIdentity)).filter(Boolean);
+      if (dispositions.length) return this.#reject(command, "identity-mismatch",
+        dispositions.includes("task-identity-mismatch") ? "task-identity-mismatch" : "runtime-or-session-replaced", false);
       const last = prior.at(-1)!; if (last.phase !== "requested") return this.#receipt(last, currentRevisions, true);
       const uncertain = this.#append(command, currentIdentity, keyDigest, last, "uncertain", "effect-unknown", "source-open-outcome-unknown");
       return this.#receipt(uncertain, currentRevisions, true);
@@ -64,9 +72,22 @@ export class SourceOpenController {
     const now = this.#now().getTime(); if (Date.parse(command.requestedAt) > now + 30_000) return this.#reject(command, "invalid-command", "requested-at-in-future", false);
     if (now > Date.parse(command.expiresAt)) return this.#reject(command, "expired", "command-expired", false);
     if (!same(command.identity, currentIdentity)) return this.#reject(command, "identity-mismatch", "identity-mismatch", false);
-    if (command.expectedRevisions.runtimeRevision !== currentRevisions.runtimeRevision || command.expectedRevisions.taskRevision !== currentRevisions.taskRevision)
-      return this.#reject(command, "stale-revision", "stale-source-open-revision", true);
+    if (command.expectedRevisions.runtimeRevision !== currentRevisions.runtimeRevision || command.expectedRevisions.taskRevision !== currentRevisions.taskRevision
+      || command.expectedRevisions.controlRevision !== currentRevisions.controlRevision)
+      return this.#reject(command, "stale-revision", "stale-task-control-revision", true);
     let authority: SourceOpenAuthority | null; try { authority = await this.#resolve(command.payload.fileRef); } catch { authority = null; }
+    const rebound = this.#bridge.snapshot();
+    if (rebound.state !== "ready" || !rebound.identity || !rebound.revisions)
+      return this.#reject(command, "resync-required", "source-open-binding-unavailable-after-target-resolution", true);
+    const reboundIdentity = identity(rebound.identity), reboundRevisions = revisions(rebound.revisions);
+    if (!same(reboundIdentity, currentIdentity)) {
+      const taskChanged = reboundIdentity.taskId !== currentIdentity.taskId || reboundIdentity.taskRunId !== currentIdentity.taskRunId;
+      return this.#reject(command, "identity-mismatch", taskChanged ? "task-identity-mismatch" : "runtime-or-session-replaced", false);
+    }
+    if (command.expectedRevisions.runtimeRevision !== reboundRevisions.runtimeRevision
+      || command.expectedRevisions.taskRevision !== reboundRevisions.taskRevision
+      || command.expectedRevisions.controlRevision !== reboundRevisions.controlRevision)
+      return this.#reject(command, "stale-revision", "stale-task-control-revision-after-target-resolution", true);
     if (!authority) return this.#reject(command, "capability-unavailable", "source-open-target-unavailable", true);
     if (authority.target.taskRevision !== command.expectedRevisions.taskRevision || authority.target.workspaceRevision !== command.expectedRevisions.workspaceRevision)
       return this.#reject(command, "stale-revision", "source-open-target-stale", true);
@@ -110,9 +131,10 @@ export class SourceOpenController {
       || command.identity.agentOperationId !== null || command.identity.toolCallId !== null) return "invalid-command-identity";
     if (!exact(command.expectedRevisions, [...REVISION_KEYS, "workspacePreimage", "indexPreimage", "patchPreimage"])
       || !REVISION.test(command.expectedRevisions.runtimeRevision) || !REVISION.test(command.expectedRevisions.taskRevision ?? "")
-      || !REVISION.test(command.expectedRevisions.workspaceRevision ?? "") || command.expectedRevisions.workspacePreimage !== null
-      || ![command.expectedRevisions.controlRevision, command.expectedRevisions.indexRevision, command.expectedRevisions.approvalRevision,
-        command.expectedRevisions.sessionOptionRevision, command.expectedRevisions.queueRevision].every(nullableRevision)
+      || !REVISION.test(command.expectedRevisions.controlRevision ?? "") || !REVISION.test(command.expectedRevisions.workspaceRevision ?? "")
+      || command.expectedRevisions.workspacePreimage !== null
+      || ![command.expectedRevisions.indexRevision, command.expectedRevisions.approvalRevision, command.expectedRevisions.sessionOptionRevision,
+        command.expectedRevisions.queueRevision].every(nullableRevision)
       || command.expectedRevisions.indexPreimage !== null || command.expectedRevisions.patchPreimage !== null) return "invalid-source-open-authority";
     if (!exact(command.payload, ["fileRef", "line", "column"]) || !REF.test(command.payload.fileRef)
       || command.payload.line !== null && (!Number.isInteger(command.payload.line) || command.payload.line < 1 || command.payload.line > 100_000_000)

package/packages/piagent-webui/extension/source-revert-controller.ts

@@ -38,6 +38,13 @@ function wireIdentity(value: BridgeIdentity): BridgeIdentity { return { projectR
 function wireRevisions(value: Record<string, any>): BridgeRevisions { return { runtimeRevision: value.runtimeRevision, taskRevision: value.taskRevision,
   controlRevision: value.controlRevision, workspaceRevision: value.workspaceRevision, indexRevision: value.indexRevision,
   approvalRevision: value.approvalRevision, sessionOptionRevision: value.sessionOptionRevision, queueRevision: value.queueRevision }; }
+function replayIdentityDisposition(record: Pick<SourceMutationEvidenceRecord, "projectRef" | "runtimeInstanceId" | "sessionRef" | "taskId" | "taskRunId">,
+  identity: BridgeIdentity): "task-identity-mismatch" | "runtime-or-session-replaced" | null {
+  if (record.taskId !== identity.taskId || record.taskRunId !== identity.taskRunId) return "task-identity-mismatch";
+  if (record.projectRef !== identity.projectRef || record.runtimeInstanceId !== identity.runtimeInstanceId || record.sessionRef !== identity.sessionRef)
+    return "runtime-or-session-replaced";
+  return null;
+}
 function receipt(record: SourceMutationEvidenceRecord, deduplicated: boolean): SourceRevertReceipt {
   const identity = { projectRef: record.projectRef, runtimeInstanceId: record.runtimeInstanceId, sessionRef: record.sessionRef,
     taskId: record.taskId, taskRunId: record.taskRunId, agentOperationId: null, toolCallId: null } as BridgeIdentity;
@@ -90,8 +97,9 @@ export class SourceRevertController {
     if (prior.length) {
       if (prior.some((record) => record.commandId !== command.commandId || record.idempotencyKeyDigest !== keyDigest || record.actionDigest !== command.actionDigest
         || record.action !== command.action)) return this.#reject(command, "idempotency-payload-mismatch", "idempotency-payload-mismatch", false);
-      if (prior.some((record) => record.runtimeInstanceId !== identity.runtimeInstanceId || record.sessionRef !== identity.sessionRef))
-        return this.#reject(command, "identity-mismatch", "runtime-or-session-replaced", false);
+      const dispositions = prior.map((record) => replayIdentityDisposition(record, identity)).filter(Boolean);
+      if (dispositions.length) return this.#reject(command, "identity-mismatch",
+        dispositions.includes("task-identity-mismatch") ? "task-identity-mismatch" : "runtime-or-session-replaced", false);
       return receipt(prior.at(-1)!, true);
     }
     const now = this.#now().getTime();
@@ -103,10 +111,25 @@ export class SourceRevertController {
     let resolved: { projection: SourceRevertProjection; authority: SourceRevertAuthority | null };
     try { resolved = await this.#resolve(command.payload.fileRef, command.payload.hunkRefs); }
     catch { return this.#reject(command, "capability-unavailable", "revert-preview-unavailable", true); }
+    const rebound = this.#bridge.snapshot();
+    if (rebound.state !== "ready" || !rebound.identity || !rebound.revisions)
+      return this.#reject(command, "resync-required", "revert-binding-unavailable-after-preview", true);
+    const reboundIdentity = wireIdentity(rebound.identity), reboundRevisions = wireRevisions(rebound.revisions);
+    if (!same(reboundIdentity, identity)) {
+      const taskChanged = reboundIdentity.taskId !== identity.taskId || reboundIdentity.taskRunId !== identity.taskRunId;
+      return this.#reject(command, "identity-mismatch", taskChanged ? "task-identity-mismatch" : "runtime-or-session-replaced", false);
+    }
+    if (rebound.taskState === "terminal") return this.#reject(command, "terminal-task", "task-terminal-after-preview", false);
+    if (rebound.liveness !== "idle") return this.#reject(command, "capability-unavailable", "agent-not-idle-after-preview", true);
+    if (command.expectedRevisions.runtimeRevision !== reboundRevisions.runtimeRevision
+      || command.expectedRevisions.taskRevision !== reboundRevisions.taskRevision
+      || command.expectedRevisions.controlRevision !== reboundRevisions.controlRevision)
+      return this.#reject(command, "stale-revision", "stale-task-control-revision-after-preview", true);
     if (!resolved.authority || resolved.projection.state !== "ready" || !resolved.projection.target)
       return this.#reject(command, "capability-unavailable", resolved.projection.reasonCode ?? "revert-preview-unavailable", true);
     const target = resolved.projection.target;
-    if (!this.#matches(command, target) || now > Date.parse(target.expiresAt)) return this.#reject(command, "stale-revision", "revert-preview-stale", true);
+    if (!this.#matches(command, target) || this.#now().getTime() > Date.parse(target.expiresAt))
+      return this.#reject(command, "stale-revision", "revert-preview-stale", true);
     const before = { ...bridgeRevisions, workspaceRevision: target.workspaceRevision, indexRevision: target.indexRevision };
     let requested: SourceMutationEvidenceRecord;
     try { requested = appendSourceMutationEvidence({ projectRoot: this.#projectRoot, projectRef: identity.projectRef, runtimeInstanceId: identity.runtimeInstanceId,

package/packages/piagent-webui/gateway/gateway-events.ts

@@ -14,10 +14,14 @@ export type GatewayProtocolEvent = {
   payload: Record<string, unknown>;
 };
 
+export type GatewayTaskStatus = "pending" | "completed" | "refused" | "failed" | "unknown";
+
 export type GatewayTerminalSettlement = {
   sessionRef: string;
   operationRef: string;
+  messageRequestId?: string;
   settlement: "blocked" | "aborted" | "error" | "unknown";
+  taskStatus: GatewayTaskStatus;
   reasonCode: string;
   settledAt: string;
   sequence: number;
@@ -30,7 +34,12 @@ const SETTLEMENT_RETENTION_COUNT = 100;
 const SETTLEMENT_RETENTION_MS = 60 * 60_000;
 const MAX_SETTLEMENT_DECISION_COUNT = 10_000;
 type GatewaySettlementDecision = { settledAt: string; settlement: "completed" | GatewayTerminalSettlement["settlement"];
-  reasonCode: string | null };
+  taskStatus: GatewayTaskStatus; reasonCode: string | null };
+
+function settlementTaskStatus(value: unknown): GatewayTaskStatus {
+  return ["pending", "completed", "refused", "failed", "unknown"].includes(String(value))
+    ? value as GatewayTaskStatus : "unknown";
+}
 
 function settlementReason(settlement: GatewayTerminalSettlement["settlement"], value: unknown): string {
   if (typeof value === "string" && REASON_CODE_PATTERN.test(value) && !redactSensitiveText(value).redacted) return value;
@@ -84,7 +93,8 @@ export class GatewayEventStore {
     if (indexed) return indexed;
     const retained = this.#settlements.find((item) => item.sessionRef === sessionRef && item.operationRef === operationRef);
     if (!retained) return undefined;
-    const restored = { settledAt: retained.settledAt, settlement: retained.settlement, reasonCode: retained.reasonCode };
+    const restored = { settledAt: retained.settledAt, settlement: retained.settlement,
+      taskStatus: retained.taskStatus, reasonCode: retained.reasonCode };
     this.#settlementDecisions.set(key, restored);
     return restored;
   }
@@ -100,11 +110,16 @@ export class GatewayEventStore {
     if (this.#settlementDecision(sessionRef, operationRef)) return;
     this.#settlementDecisions.set(key, { settledAt: event.generatedAt,
       settlement: settlement as GatewaySettlementDecision["settlement"],
+      taskStatus: settlementTaskStatus(event.payload.taskStatus),
       reasonCode: settlement === "completed" ? null : String(event.payload.reasonCode) });
-    const retained = { sessionRef, operationRef, settledAt: event.generatedAt, sequence: event.sequence };
+    const messageRequestId = typeof event.payload.messageRequestId === "string" && OPAQUE_REF_PATTERN.test(event.payload.messageRequestId)
+      ? event.payload.messageRequestId : undefined;
+    const retained = { sessionRef, operationRef, ...(messageRequestId ? { messageRequestId } : {}),
+      settledAt: event.generatedAt, sequence: event.sequence };
     if (settlement !== "completed") {
       const outcome = settlement as GatewayTerminalSettlement["settlement"];
-      this.#settlements.push({ ...retained, settlement: outcome, reasonCode: settlementReason(outcome, event.payload.reasonCode) });
+      this.#settlements.push({ ...retained, settlement: outcome, taskStatus: settlementTaskStatus(event.payload.taskStatus),
+        reasonCode: settlementReason(outcome, event.payload.reasonCode) });
     }
     this.#pruneSettlements(now);
   }
@@ -112,6 +127,7 @@ export class GatewayEventStore {
   publish(kind: GatewayEventKind, payload: Record<string, unknown>, now = new Date()): GatewayProtocolEvent {
     if (!Number.isFinite(now.getTime())) throw new Error("gateway-event-time-invalid");
     if (kind === "operation.settled") {
+      payload = { ...payload, taskStatus: settlementTaskStatus(payload.taskStatus) };
       if (payload.settlement === "completed") payload = { ...payload, reasonCode: null };
       else {
         const settlement = ["blocked", "aborted", "error", "unknown"].includes(String(payload.settlement))
@@ -123,7 +139,8 @@ export class GatewayEventStore {
       if (typeof sessionRef === "string" && OPAQUE_REF_PATTERN.test(sessionRef)
         && typeof operationRef === "string" && OPAQUE_REF_PATTERN.test(operationRef)) {
         const canonical = this.#settlementDecision(sessionRef, operationRef);
-        if (canonical) payload = { ...payload, settlement: canonical.settlement, reasonCode: canonical.reasonCode };
+        if (canonical) payload = { ...payload, settlement: canonical.settlement,
+          taskStatus: canonical.taskStatus, reasonCode: canonical.reasonCode };
       }
     }
     this.#sequence += 1;

package/packages/piagent-webui/gateway/gateway-service.ts

@@ -32,6 +32,7 @@ import { ProjectRegistry } from "./project-registry.ts";
 import { pickNativeProjectFolders } from "./native-project-picker.ts";
 import { ProviderAuthBroker } from "./provider-auth-broker.ts";
 import { McpAuthBroker } from "./mcp-auth-broker.ts";
+import type { ScopedBrokerRouter } from "./session-runtime-factory.ts";
 
 function unavailable(reasonCode: string) {
   return { status: "unavailable" as const, version: null, reasonCode };
@@ -80,6 +81,8 @@ export async function startPiagentGateway(options: {
   packageRoot: string;
   expectedPiVersion: string;
   agentDir?: string;
+  staticRoot?: string;
+  scopedBrokerRouter?: ScopedBrokerRouter;
 }): Promise<{ descriptor: GatewayDescriptor; wait(): Promise<void>; close(): Promise<void> }> {
   const state = gatewayProfileState(options.agentDir);
   process.env.PI_CODING_AGENT_DIR = state.agentDir;
@@ -87,7 +90,7 @@ export async function startPiagentGateway(options: {
   const metadata = new SessionMetadataStore(state.root, key);
   const projects = new ProjectRegistry(state.root, key);
   const gatewayInstanceRef = `gateway_${process.pid}_${randomBytes(24).toString("base64url")}`;
-  const staticRoot = path.join(options.packageRoot, "packages", "piagent-webui", "dist", "client");
+  const staticRoot = options.staticRoot ?? path.join(options.packageRoot, "packages", "piagent-webui", "dist", "client");
   if (!fs.existsSync(path.join(staticRoot, "index.html"))) throw new Error("gateway-webui-build-missing");
 
   let descriptor: GatewayDescriptor | null = null;
@@ -145,6 +148,7 @@ export async function startPiagentGateway(options: {
     runtimes = new SessionRuntimeSupervisor({
       gatewayInstanceRef, key, leases, listSessions: () => host.SessionManager.listAll(),
       host, agentDir: state.agentDir, packageRoot: options.packageRoot, modelRuntime: inspectionModels, events,
+      scopedBrokerRouter: options.scopedBrokerRouter,
       resolveProject: (projectRef) => projects.resolve(projectRef)
     });
     const readCatalog = () => buildSessionCatalog({
@@ -182,7 +186,8 @@ export async function startPiagentGateway(options: {
       events, command: commands });
     const inspections = new SessionInspectionRegistry({ gatewayInstanceRef, host, key, packageRoot: options.packageRoot, agentDir: state.agentDir,
       models: inspectionModels, projects, mcpAuth, listSessions: () => runtimes!.listSessions(),
-      openLiveSession: (sessionRef) => runtimes!.liveSessionManager(sessionRef) });
+      openLiveSession: (sessionRef) => runtimes!.liveSessionManager(sessionRef),
+      operationLiveness: (sessionRef) => runtimes!.currentOperation(sessionRef) ? "running" : "idle" });
     // Staged bytes live beside the inspection projection they were checked
     // against, so both read the same session through the same registry.
     attachments = new SessionAttachmentRegistry({

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

@@ -2,7 +2,8 @@ import { randomBytes } from "node:crypto";
 
 import { redactSensitiveText } from "../../piagent-core/security/sensitive-data.js";
 import { hasVisibleText } from "../shared/text-visibility.ts";
-import { GatewayEventStore } from "./gateway-events.ts";
+import type { TerminalDeliveryReceipt } from "../server/terminal-delivery-receipt.ts";
+import { GatewayEventStore, type GatewayTaskStatus } from "./gateway-events.ts";
 import { SessionOperationLifecycle, type SessionOperationObservation,
   type SessionOperationPhase, type SessionOperationRetryPolicyOptions } from "./session-operation-lifecycle.ts";
 
@@ -17,6 +18,14 @@ const COMPLETION_GATE = /^\[Piagent completion gate: (CONTINUING|NOT APPROVED)\]
 export type GatewayOperationSettlement = "completed" | "blocked" | "aborted" | "error" | "unknown";
 type Settlement = { outcome: GatewayOperationSettlement; reasonCode: string | null };
 
+function projectedTaskStatus(taskOutcome: string | null, override: GatewayTaskStatus | null): GatewayTaskStatus {
+  if (override) return override;
+  if (taskOutcome === "pending") return "pending";
+  if (taskOutcome === "completed") return "completed";
+  if (["blocked", "partial", "failed"].includes(String(taskOutcome))) return "failed";
+  return "unknown";
+}
+
 function clean(value: unknown): string {
   return String(value ?? "").replace(/\u001b(?:\[[0-?]*[ -/]*[@-~]|[@-_])/g, "")
     .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, " ");
@@ -26,6 +35,66 @@ function safeTool(value: unknown): string {
   if (safe.redacted) return "redacted-tool";
   return safe.text.replace(/[^A-Za-z0-9._:-]/g, "-").replace(/^[^A-Za-z0-9]+/, "").slice(0, 160) || "tool";
 }
+
+const DIRECT_FILE_KEYS = ["file", "filePath", "file_path", "filename", "targetFile", "target_file"] as const;
+const PATH_KEYS = ["path", "targetPath", "target_path"] as const;
+const FILE_MUTATION_OR_READ_TOOL = /(?:^|[._:-])(read|write|edit|patch|apply)(?:[._:-]|$)/i;
+const FILE_SEARCH_TOOL = /(?:^|[._:-])(grep|search|find|glob|list|ls)(?:[._:-]|$)/i;
+const FILE_LIKE_BASENAME = /(?:^\.[^./\\]+$)|(?:\.[A-Za-z0-9][A-Za-z0-9+_-]{0,15}$)|^(?:Dockerfile|Containerfile|Makefile|README|LICENSE|CHANGELOG)$/i;
+const PATCH_FILE_HEADER = /^\*\*\* (?:Update|Add|Delete) File:\s*(.+)$/m;
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : null;
+}
+
+function firstString(records: readonly Record<string, unknown>[], keys: readonly string[]): string | null {
+  for (const source of records) for (const key of keys) {
+    const value = source[key];
+    if (typeof value === "string" && value.trim()) return value;
+    if (Array.isArray(value)) {
+      const first = value.find((item) => typeof item === "string" && item.trim());
+      if (typeof first === "string") return first;
+    }
+  }
+  return null;
+}
+
+function safeBasename(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const source = clean(value).trim();
+  if (!source || source.includes("\n") || source.includes("\r") || /(?:^|\s)(?:https?|data):\/\//i.test(source)) return null;
+  const parts = source.replace(/\\/g, "/").replace(/\/+$/, "").split("/");
+  const basename = (parts.at(-1) ?? "").trim().replace(/^["']|["']$/g, "");
+  if (!basename || basename === "." || basename === "..") return null;
+  const projected = redactSensitiveText(basename);
+  if (projected.redacted || projected.text !== basename || /[\u0000-\u001f\u007f/\\]/.test(basename)) return null;
+  return basename.slice(0, 160);
+}
+
+/**
+ * Returns only a redaction-checked basename suitable for the compact chat
+ * progress row. Raw arguments and full paths remain confined to the runtime;
+ * the Activity inspector keeps its independent, richer projection.
+ */
+export function safeToolFileLabel(toolName: unknown, args: unknown): string | null {
+  const tool = safeTool(toolName), direct = record(args); if (!direct) return null;
+  const nested = record(direct.args), input = record(direct.input);
+  const records = [direct, ...(nested ? [nested] : []), ...(input ? [input] : [])];
+  const explicitFile = firstString(records, DIRECT_FILE_KEYS);
+  if (explicitFile) return safeBasename(explicitFile);
+  const path = firstString(records, PATH_KEYS);
+  if (path) {
+    const basename = safeBasename(path);
+    if (basename && (FILE_MUTATION_OR_READ_TOOL.test(tool)
+      || FILE_SEARCH_TOOL.test(tool) && FILE_LIKE_BASENAME.test(basename))) return basename;
+  }
+  if (FILE_MUTATION_OR_READ_TOOL.test(tool)) {
+    const patch = firstString(records, ["patch"]);
+    const headerPath = typeof patch === "string" ? PATCH_FILE_HEADER.exec(patch)?.[1] : null;
+    if (headerPath) return safeBasename(headerPath);
+  }
+  return null;
+}
 function ref(prefix: string): string { return `${prefix}_${randomBytes(18).toString("base64url")}`; }
 function messageText(message: any): string {
   if (typeof message?.content === "string") return message.content;
@@ -69,6 +138,7 @@ export function runtimeRestartReasonCode(event: unknown): "runtime-restart-requi
 export class GatewaySessionStream {
   readonly sessionRef: string;
   readonly operationRef: string;
+  readonly messageRequestId: string | null;
   readonly #events: GatewayEventStore;
   #messageRef: string | null = null;
   #messageSequence = 0;
@@ -83,7 +153,12 @@ export class GatewaySessionStream {
   #lifecycleTerminationReasonCode: string | null = null;
   #settleListeners: Array<() => void> = [];
   readonly #toolRefs = new Map<string, string>();
+  readonly #toolLabels = new Map<string, string>();
+  readonly #toolFileLabels = new Map<string, string | null>();
   readonly #lifecycle: SessionOperationLifecycle;
+  readonly #commitTerminalDeliveryReceipt: ((message: unknown) => TerminalDeliveryReceipt | undefined) | undefined;
+  #terminalDeliveryMessage: unknown;
+  #receiptOnly = true;
 
   get runtimeRestartRequired(): boolean { return this.#runtimeRestartRequired; }
   get lifecycleTerminationReasonCode(): string | null { return this.#lifecycleTerminationReasonCode; }
@@ -91,6 +166,9 @@ export class GatewaySessionStream {
   get retryAbortRequired(): boolean { return this.#lifecycle.retryAbortRequired; }
 
   markAborted(reasonCode = "operation-aborted"): void { this.#forcedSettlement = { outcome: "aborted", reasonCode }; }
+  markBlocked(reasonCode = "operation-blocked"): void {
+    if (!this.#forcedSettlement) this.#forcedSettlement = { outcome: "blocked", reasonCode };
+  }
   markError(reasonCode = "operation-failed"): void {
     if (!this.#forcedSettlement) this.#forcedSettlement = { outcome: "error", reasonCode };
   }
@@ -102,10 +180,17 @@ export class GatewaySessionStream {
     if (!wasSettled) for (const resolve of this.#settleListeners.splice(0)) resolve();
   }
 
-  constructor(options: { sessionRef: string; operationRef: string; events: GatewayEventStore;
-    retryPolicy?: SessionOperationRetryPolicyOptions }) {
-    this.sessionRef = options.sessionRef; this.operationRef = options.operationRef; this.#events = options.events;
+  constructor(options: { sessionRef: string; operationRef: string; messageRequestId?: string | null; events: GatewayEventStore;
+    retryPolicy?: SessionOperationRetryPolicyOptions;
+    commitTerminalDeliveryReceipt?: (message: unknown) => TerminalDeliveryReceipt | undefined }) {
+    this.sessionRef = options.sessionRef; this.operationRef = options.operationRef;
+    this.messageRequestId = options.messageRequestId ?? null; this.#events = options.events;
     this.#lifecycle = new SessionOperationLifecycle({ operationRef: options.operationRef, retryPolicy: options.retryPolicy });
+    this.#commitTerminalDeliveryReceipt = options.commitTerminalDeliveryReceipt;
+  }
+
+  #correlation(): { messageRequestId?: string } {
+    return this.messageRequestId ? { messageRequestId: this.messageRequestId } : {};
   }
 
   started(): Promise<void> {
@@ -122,6 +207,9 @@ export class GatewaySessionStream {
     const wasStarted = this.#lifecycle.started, wasSettled = this.#lifecycle.hostSettled;
     const observation = this.#lifecycle.observe(event);
     if (!observation.accepted) return observation;
+    if (event?.type === "agent_start" || event?.message?.role === "assistant" || event?.assistantMessageEvent
+      || String(event?.type ?? "").startsWith("tool_execution_")) this.#receiptOnly = false;
+    if (event?.type === "message_end" && event.message?.role === "custom") this.#terminalDeliveryMessage = event.message;
     if (!wasStarted && this.#lifecycle.started) for (const resolve of this.#startListeners.splice(0)) resolve();
     if (!wasSettled && this.#lifecycle.hostSettled) for (const resolve of this.#settleListeners.splice(0)) resolve();
     if (observation.retry === "abort") this.markError(observation.reasonCode ?? "automatic-retry-blocked");
@@ -129,6 +217,7 @@ export class GatewaySessionStream {
       return observation;
     }
     if (event?.type === "agent_settled") {
+      this.#settleActiveTools("operation-settled-before-tool-result");
       return observation;
     }
     if (event?.type === "message_start" && event.message?.role === "assistant") {
@@ -146,22 +235,35 @@ export class GatewaySessionStream {
       this.#flush(true); this.#lastMessageRef = this.#messageRef; this.#settlement = assistantSettlement(event.message); return observation;
     }
     if (event?.type === "tool_execution_start" && typeof event.toolCallId === "string") {
-      const toolCallRef = ref("tool"); this.#toolRefs.set(event.toolCallId, toolCallRef);
-      this.#events.publish("tool.started", { sessionRef: this.sessionRef, operationRef: this.operationRef, toolCallRef,
-        toolLabel: safeTool(event.toolName), isError: null, reasonCode: null });
+      const toolCallRef = ref("tool"), toolLabel = safeTool(event.toolName), fileLabel = safeToolFileLabel(event.toolName, event.args);
+      this.#toolRefs.set(event.toolCallId, toolCallRef); this.#toolLabels.set(event.toolCallId, toolLabel);
+      this.#toolFileLabels.set(event.toolCallId, fileLabel);
+      this.#events.publish("tool.started", { sessionRef: this.sessionRef, operationRef: this.operationRef, ...this.#correlation(), toolCallRef,
+        toolLabel, fileLabel, isError: null, reasonCode: null });
       return observation;
     }
     if (event?.type === "tool_execution_end" && typeof event.toolCallId === "string") {
       const toolCallRef = this.#toolRefs.get(event.toolCallId); if (!toolCallRef) return observation;
       const reasonCode = runtimeRestartReasonCode(event);
       if (reasonCode) this.#runtimeRestartRequired = true;
-      this.#events.publish("tool.completed", { sessionRef: this.sessionRef, operationRef: this.operationRef, toolCallRef,
-        toolLabel: safeTool(event.toolName), isError: event.isError === true, reasonCode });
-      this.#toolRefs.delete(event.toolCallId);
+      this.#events.publish("tool.completed", { sessionRef: this.sessionRef, operationRef: this.operationRef, ...this.#correlation(), toolCallRef,
+        toolLabel: safeTool(event.toolName), fileLabel: this.#toolFileLabels.get(event.toolCallId) ?? null,
+        isError: event.isError === true, reasonCode });
+      this.#toolRefs.delete(event.toolCallId); this.#toolLabels.delete(event.toolCallId); this.#toolFileLabels.delete(event.toolCallId);
     }
+    if (event?.type === "turn_end") this.#settleActiveTools("turn-ended-before-tool-result");
     return observation;
   }
 
+  #settleActiveTools(reasonCode: string): void {
+    for (const [toolCallId, toolCallRef] of this.#toolRefs) {
+      this.#events.publish("tool.completed", { sessionRef: this.sessionRef, operationRef: this.operationRef, ...this.#correlation(), toolCallRef,
+        toolLabel: this.#toolLabels.get(toolCallId) ?? "tool", fileLabel: this.#toolFileLabels.get(toolCallId) ?? null,
+        isError: true, reasonCode });
+    }
+    this.#toolRefs.clear(); this.#toolLabels.clear(); this.#toolFileLabels.clear();
+  }
+
   #flush(final: boolean): void {
     if (!this.#messageRef || !this.#buffer || this.#eventCount >= MAX_EVENTS) {
       if (this.#eventCount >= MAX_EVENTS) this.#truncated = true;
@@ -186,37 +288,57 @@ export class GatewaySessionStream {
   #emit(value: string): void {
     for (let offset = 0; offset < value.length; offset += MAX_DELTA) {
       if (this.#eventCount >= MAX_EVENTS) { this.#truncated = true; break; }
-      this.#events.publish("message.delta", { sessionRef: this.sessionRef, operationRef: this.operationRef,
+      this.#events.publish("message.delta", { sessionRef: this.sessionRef, operationRef: this.operationRef, ...this.#correlation(),
         messageRef: this.#messageRef!, messageSequence: this.#messageSequence++, delta: value.slice(offset, offset + MAX_DELTA) });
       this.#eventCount += 1;
     }
   }
 
-  complete(sessionRevision: string | null, taskOutcome: string | null = null): void {
+  complete(sessionRevision: string | null, taskOutcome: string | null = null,
+    taskStatusOverride: GatewayTaskStatus | null = null): void {
     if (!this.#lifecycle.markTerminal()) return;
+    const receipt = this.#receiptOnly && !this.#forcedSettlement && !this.#runtimeRestartRequired
+      && sessionRevision !== null && taskOutcome !== null && taskOutcome !== "pending"
+      ? this.#commitTerminalDeliveryReceipt?.(this.#terminalDeliveryMessage) : undefined;
+    if (receipt) {
+      // The canonical transcript renders a custom receipt. Never stream it as
+      // assistant text or open a model turn just to supply a final message.
+      this.#lastMessageRef = ref("receipt");
+      const diagnostic = receipt.details.diagnosticDelivery as { mode?: string; qualityClaim?: string } | undefined;
+      const diagnosticDelivered = taskOutcome === "completed" && receipt.details.completionApproved === false
+        && diagnostic?.mode === "diagnostic" && diagnostic.qualityClaim === "withheld";
+      const completedTask = receipt.details.outcome === "completed" && (receipt.details.completionApproved || diagnosticDelivered)
+        && receipt.details.gateDecision === "pass";
+      // Delivery of an already refused task is a completed operation, never
+      // approval to perform the refused action. Both the committed receipt
+      // and the supervisor's current native task projection must agree.
+      const refusedTask = taskOutcome === "blocked" && taskStatusOverride === "refused"
+        && receipt.details.outcome === "blocked" && receipt.details.completionApproved === false
+        && receipt.details.gateDecision === "fail";
+      this.#settlement = completedTask || refusedTask ? { outcome: "completed", reasonCode: null }
+        : { outcome: "blocked", reasonCode: "terminal-receipt-not-approved" };
+    }
     this.#flush(true);
+    this.#settleActiveTools("operation-settled-before-tool-result");
     let settlement = this.#forcedSettlement ?? (this.#runtimeRestartRequired
       ? { outcome: "unknown" as const, reasonCode: "runtime-restart-required" }
       : this.#settlement);
     const messageRef = this.#lastMessageRef ?? this.#messageRef;
+    const taskStatus = projectedTaskStatus(taskOutcome, taskStatusOverride);
     if (settlement.outcome === "completed" && !messageRef) {
       settlement = { outcome: "unknown", reasonCode: "assistant-message-unavailable" };
-    } else if (settlement.outcome === "completed" && taskOutcome === "pending") {
-      // Provider completion is not governed-task completion. The durable task
-      // contract is authoritative, so withhold both success settlement and the
-      // durable assistant-success event until that contract becomes terminal.
-      settlement = { outcome: "unknown", reasonCode: "task-completion-pending" };
     } else if (settlement.outcome === "completed" && sessionRevision === null) {
       // Streaming text is not durable success until the canonical session
       // projection confirms it. Still terminate the UI, but do not show draft.
       settlement = { outcome: "unknown", reasonCode: "session-projection-unavailable" };
     }
     if (settlement.outcome === "completed" && messageRef && sessionRevision) {
-      this.#events.publish("message.completed", { sessionRef: this.sessionRef, operationRef: this.operationRef,
+      this.#events.publish("message.completed", { sessionRef: this.sessionRef, operationRef: this.operationRef, ...this.#correlation(),
         messageRef, sessionRevision, truncated: this.#truncated });
     }
-    this.#events.publish("operation.settled", { sessionRef: this.sessionRef, operationRef: this.operationRef,
+    this.#events.publish("operation.settled", { sessionRef: this.sessionRef, operationRef: this.operationRef, ...this.#correlation(),
       messageRef, sessionRevision, settlement: settlement.outcome,
+      taskStatus,
       reasonCode: settlement.outcome === "completed" ? null : settlement.reasonCode ?? "operation-settlement-unknown" });
   }
 }

package/packages/piagent-webui/gateway/rpc-ui-context.ts

@@ -16,13 +16,38 @@ export function rpcUiContext(): object {
     getThinkingBorderColor: () => plain,
     getBashModeBorderColor: () => plain
   });
-  return new Proxy({}, {
-    get(_target, property) {
-      if (property === GATEWAY_RUNTIME_UI_MARKER) return true;
-      if (property === "theme") return theme;
-      if (property === "confirm") return () => new Promise<boolean>(() => undefined);
-      if (property === "select" || property === "input") return async () => undefined;
-      return () => undefined;
-    }
-  });
+  const noop = () => undefined;
+  // Pi copies this context when wrapping prompts. Keep methods and the ownership
+  // marker enumerable so notification delivery and gateway detection survive.
+  return {
+    [GATEWAY_RUNTIME_UI_MARKER]: true,
+    theme,
+    confirm: () => new Promise<boolean>(() => undefined),
+    select: async () => undefined,
+    input: async () => undefined,
+    editor: async () => undefined,
+    custom: async () => undefined,
+    notify: noop,
+    onTerminalInput: () => noop,
+    setStatus: noop,
+    setWorkingMessage: noop,
+    setWorkingVisible: noop,
+    setWorkingIndicator: noop,
+    setHiddenThinkingLabel: noop,
+    setWidget: noop,
+    setFooter: noop,
+    setHeader: noop,
+    setTitle: noop,
+    pasteToEditor: noop,
+    setEditorText: noop,
+    getEditorText: () => "",
+    addAutocompleteProvider: noop,
+    setEditorComponent: noop,
+    getEditorComponent: noop,
+    getAllThemes: () => [],
+    getTheme: noop,
+    setTheme: () => ({ success: false, error: "UI not available" }),
+    getToolsExpanded: () => false,
+    setToolsExpanded: noop
+  };
 }