@piagent/platform 1.6.0 → 1.7.1

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

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

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

@@ -13,13 +13,13 @@ const MAX_BOOTSTRAP_BODY_BYTES = 4_096;
 const MAX_CONTROL_BODY_BYTES = 70_000;
 const MAX_ATTACHMENT_BODY_BYTES = 11_250_000;
 const REQUESTS_PER_MINUTE = 120;
-const BOOTSTRAPS_PER_MINUTE = 8;
+const BOOTSTRAP_FAILURES_PER_MINUTE = 8;
 const CONTROLS_PER_MINUTE = 60;
 const MAX_JSON_RESPONSE_BYTES = 16 * 1024 * 1024;
 const CURSOR = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,159}$/;
 
 type ReadCapabilities = () => unknown | Promise<unknown>;
-type RateState = { windowStart: number; requests: number; bootstraps: number };
+type RateState = { windowStart: number; requests: number; bootstrapFailures: number };
 type ControlRateState = { windowStart: number; controls: number };
 
 export type LoopbackServer = {
@@ -109,8 +109,8 @@ export async function startLoopbackServer(options: {
     const browserSession = auth.authenticate(request, now);
     const rateKey = browserSession ? `${remote}:${browserSession.id}` : `remote:${remote}`;
     for (const [key, value] of rates) if (now - value.windowStart >= 60_000) rates.delete(key);
-    const rate = rates.get(rateKey) ?? { windowStart: now, requests: 0, bootstraps: 0 };
-    if (now - rate.windowStart >= 60_000) Object.assign(rate, { windowStart: now, requests: 0, bootstraps: 0 });
+    const rate = rates.get(rateKey) ?? { windowStart: now, requests: 0, bootstrapFailures: 0 };
+    if (now - rate.windowStart >= 60_000) Object.assign(rate, { windowStart: now, requests: 0, bootstrapFailures: 0 });
     rate.requests += 1; rates.set(rateKey, rate);
     while (rates.size > 128) rates.delete(rates.keys().next().value as string);
     if (rate.requests > REQUESTS_PER_MINUTE) return errorResponse(response, 429, "rate-limit");
@@ -120,8 +120,6 @@ export async function startLoopbackServer(options: {
     if (url.hash || url.username || url.password || url.origin !== origin) return errorResponse(response, 400, "invalid-url");
 
     if (request.method === "POST" && url.pathname === "/api/v1/bootstrap") {
-      rate.bootstraps += 1;
-      if (rate.bootstraps > BOOTSTRAPS_PER_MINUTE) return errorResponse(response, 429, "bootstrap-rate-limit");
       if (requestOrigin !== origin) return errorResponse(response, 403, "origin-required");
       if (!String(request.headers["content-type"] ?? "").toLowerCase().startsWith("application/json")) return errorResponse(response, 415, "content-type");
       let value: unknown;
@@ -129,7 +127,11 @@ export async function startLoopbackServer(options: {
       catch (error) { return errorResponse(response, (error as Error).message === "body-limit" ? 413 : 400, "invalid-bootstrap"); }
       const capability = value && typeof value === "object" ? (value as Record<string, unknown>).capability : null;
       const session = typeof capability === "string" ? auth.exchange(capability) : null;
-      if (!session) return errorResponse(response, 403, "bootstrap-rejected");
+      if (!session) {
+        rate.bootstrapFailures += 1;
+        if (rate.bootstrapFailures > BOOTSTRAP_FAILURES_PER_MINUTE) return errorResponse(response, 429, "bootstrap-rate-limit");
+        return errorResponse(response, 403, "bootstrap-rejected");
+      }
       response.setHeader("Set-Cookie", auth.cookieHeader(session));
       return jsonResponse(response, 200, { authenticated: true, csrfToken: session.csrf, expiresAt: new Date(session.expiresAt).toISOString() });
     }

package/packages/piagent-webui/server/terminal-delivery-receipt.ts

@@ -0,0 +1,144 @@
+import { isDeepStrictEqual } from "node:util";
+import fs from "node:fs";
+
+import { webUiMessageCorrelationEntry, type WebUiMessageCorrelation } from "../shared/message-correlation.ts";
+
+// As in CoreInspectionProvider, load core through the server boundary. Its
+// internal source types are not part of the strict browser contract graph.
+const CORE_ROOT = "../../piagent-core";
+const [{ activeSessionTask }, { isUncertainSendContinuation, terminalUncertainSendReceipt }] = await Promise.all([
+  import(`${CORE_ROOT}/extensions/task-state.js`),
+  import(`${CORE_ROOT}/runtime/session/uncertain-send-continuation.ts`)
+]);
+
+export type TerminalDeliveryReceipt = { customType: string; content: string; details: {
+  taskId: string; taskRunId: string; outcome: string; completionApproved: boolean; gateDecision: string;
+  [key: string]: unknown;
+} };
+
+export function readTerminalDeliveryReceipt(cwd: string, task: unknown): TerminalDeliveryReceipt | undefined {
+  return terminalUncertainSendReceipt(cwd, task);
+}
+
+export const TERMINAL_DELIVERY_CONFIRMATION_TYPE = "piagent-webui-terminal-delivery-v1";
+export type TerminalDeliveryPair = { requestEntry: any; receiptEntry: any; confirmationEntry?: any; request: string;
+  correlation: WebUiMessageCorrelation; receipt: TerminalDeliveryReceipt };
+
+/** Strict bounded readback; an in-memory Pi branch is not a persistence acknowledgment. */
+export function terminalDeliverySessionEntries(file: string | undefined, sessionId: string): unknown[] {
+  if (!file) return [];
+  let descriptor: number | undefined;
+  try {
+    descriptor = fs.openSync(file, "r");
+    const stat = fs.fstatSync(descriptor);
+    if (!stat.isFile() || stat.size > 64 * 1024 * 1024) return [];
+    const source = fs.readFileSync(descriptor, "utf8");
+    if (!source.endsWith("\n") || Buffer.byteLength(source) > 64 * 1024 * 1024) return [];
+    const lines = source.trimEnd().split("\n");
+    if (lines.length > 50_001) return [];
+    // Pi's generic parser tolerates corrupt lines. Delivery requires every
+    // persisted record, including the confirmation, to be complete and valid.
+    const [header, ...entries] = lines.map((line) => JSON.parse(line));
+    return header?.type === "session" && header.version === 3 && header.id === sessionId ? entries : [];
+  } catch { return []; }
+  finally { if (descriptor !== undefined) fs.closeSync(descriptor); }
+}
+
+/** Only this handled-input protocol needs a request anchor outside model history. */
+export function terminalDeliveryRequest(message: unknown, images?: unknown[]): string | undefined {
+  return typeof message === "string" && message.length <= 65_536 && !images?.length
+    && isUncertainSendContinuation(message) ? message : undefined;
+}
+
+function matchesReceipt(value: any, expected: TerminalDeliveryReceipt): boolean {
+  return value?.display === true && value.customType === expected.customType && value.content === expected.content
+    && isDeepStrictEqual(value.details, expected.details);
+}
+
+function hasEntryIdentity(value: any): boolean {
+  return typeof value?.id === "string" && value.id.length > 0 && value.id.length <= 160
+    && typeof value.timestamp === "string" && Number.isFinite(Date.parse(value.timestamp));
+}
+
+function confirmationData(pair: TerminalDeliveryPair): Record<string, unknown> {
+  return { schemaVersion: 1, ...pair.correlation, receiptEntryId: pair.receiptEntry.id,
+    taskId: pair.receipt.details.taskId, taskRunId: pair.receipt.details.taskRunId };
+}
+
+function receiptPairs(entries: unknown[], expected: TerminalDeliveryReceipt | undefined,
+  confirmed: boolean): TerminalDeliveryPair[] {
+  if (!expected || !Array.isArray(entries) || entries.length > 50_000) return [];
+  const pairs: TerminalDeliveryPair[] = [];
+  const operations = new Map<string, number>(), requests = new Map<string, number>(), entryIds = new Map<string, number>();
+  for (const entry of entries) {
+    const id = (entry as any)?.id;
+    if (typeof id === "string") entryIds.set(id, (entryIds.get(id) ?? 0) + 1);
+    const correlation = webUiMessageCorrelationEntry(entry);
+    if (correlation) {
+      operations.set(correlation.operationRef, (operations.get(correlation.operationRef) ?? 0) + 1);
+      requests.set(correlation.messageRequestId, (requests.get(correlation.messageRequestId) ?? 0) + 1);
+    }
+  }
+  for (let index = 1; index < entries.length; index += 1) {
+    const requestEntry = entries[index - 1] as any, receiptEntry = entries[index] as any;
+    const correlation = webUiMessageCorrelationEntry(requestEntry);
+    const request = terminalDeliveryRequest(requestEntry?.data?.terminalDeliveryRequest);
+    if (!correlation || request === undefined || receiptEntry?.type !== "custom_message"
+      || !hasEntryIdentity(requestEntry) || !hasEntryIdentity(receiptEntry)
+      || entryIds.get(requestEntry.id) !== 1 || entryIds.get(receiptEntry.id) !== 1
+      || !matchesReceipt(receiptEntry, expected)) continue;
+    const pair: TerminalDeliveryPair = { requestEntry, receiptEntry, request, correlation, receipt: expected };
+    if (confirmed) {
+      const confirmation = entries[index + 1] as any;
+      if (confirmation?.type !== "custom" || confirmation.customType !== TERMINAL_DELIVERY_CONFIRMATION_TYPE
+        || !hasEntryIdentity(confirmation) || entryIds.get(confirmation.id) !== 1
+        || !isDeepStrictEqual(confirmation.data, confirmationData(pair))) continue;
+      pair.confirmationEntry = confirmation;
+    }
+    pairs.push(pair);
+  }
+  return pairs.filter((pair) => operations.get(pair.correlation.operationRef) === 1
+    && requests.get(pair.correlation.messageRequestId) === 1);
+}
+
+/** A projection may show only a receipt whose operation reached durable delivery settlement. */
+export function terminalDeliveryPairs(entries: unknown[], expected: TerminalDeliveryReceipt | undefined,
+  persistedEntries: unknown[] = []): TerminalDeliveryPair[] {
+  const persisted = new Map(receiptPairs(persistedEntries, expected, true).map((pair) => [pair.receiptEntry.id, pair]));
+  return receiptPairs(entries, expected, true).filter((pair) => {
+    const disk = persisted.get(pair.receiptEntry.id);
+    return disk && isDeepStrictEqual(pair.requestEntry, disk.requestEntry) && isDeepStrictEqual(pair.receiptEntry, disk.receiptEntry)
+      && isDeepStrictEqual(pair.confirmationEntry, disk.confirmationEntry);
+  });
+}
+
+/**
+ * Compare the observed custom message with current core state and this exact
+ * operation's latest durable receipt. Persist a delivery observation before
+ * the gateway acknowledges settlement. This marker grants no task authority;
+ * transcript reads still require the independently reread core receipt.
+ */
+export function terminalDeliveryReceiptCommitter(input: { cwd: string; sessionId: string; operationRef: string;
+  messageRequestId: string | null; request?: string; entries(): unknown[]; persistedEntries(): unknown[];
+  appendCustomEntry(type: string, data: Record<string, unknown>): unknown }):
+  (message: unknown) => TerminalDeliveryReceipt | undefined {
+  return (message) => {
+    if (input.request === undefined || !input.messageRequestId || (message as any)?.role !== "custom") return undefined;
+    try {
+      const expected = readTerminalDeliveryReceipt(input.cwd, activeSessionTask(input.cwd, input.sessionId));
+      const entries = input.entries(), pair = receiptPairs(entries, expected, false).find((candidate) =>
+        candidate.correlation.operationRef === input.operationRef
+        && candidate.correlation.messageRequestId === input.messageRequestId && candidate.request === input.request);
+      if (!pair || pair.receiptEntry !== entries.at(-1) || !matchesReceipt(message, pair.receipt)) return undefined;
+      const before = input.persistedEntries();
+      const disk = receiptPairs(before, expected, false).find((candidate) => candidate.receiptEntry.id === pair.receiptEntry.id);
+      if (!disk || disk.receiptEntry !== before.at(-1) || !isDeepStrictEqual(pair.requestEntry, disk.requestEntry)
+        || !isDeepStrictEqual(pair.receiptEntry, disk.receiptEntry)) return undefined;
+      input.appendCustomEntry(TERMINAL_DELIVERY_CONFIRMATION_TYPE, confirmationData(pair));
+      const current = input.entries(), persisted = input.persistedEntries();
+      return terminalDeliveryPairs(current, expected, persisted).some((candidate) => candidate.receiptEntry.id === pair.receiptEntry.id
+        && candidate.confirmationEntry === current.at(-1) && candidate.confirmationEntry.id === (persisted.at(-1) as any)?.id)
+        ? pair.receipt : undefined;
+    } catch { return undefined; }
+  };
+}

package/packages/piagent-webui/server/transcript-projection.ts

@@ -1,13 +1,22 @@
 import { createHash } from "node:crypto";
 
 import { redactSensitiveText } from "../../piagent-core/extensions/redaction-core.js";
+import { looksLikeCompletionClaim } from "../../piagent-core/runtime/session/completion-signals.ts";
+import { isLightweightNonAuthorizingChangeLanguage } from "../../piagent-core/runtime/workflows/change-clarification.ts";
+import { workflowCommandPattern } from "../../piagent-core/runtime/workflows/webui-workflow.ts";
 import { hasVisibleText } from "../shared/text-visibility.ts";
+import { WEBUI_MESSAGE_CORRELATION_ENTRY_TYPE, webUiMessageCorrelationEntry,
+  type WebUiMessageCorrelation } from "../shared/message-correlation.ts";
+import { terminalDeliveryPairs, type TerminalDeliveryPair, type TerminalDeliveryReceipt } from "./terminal-delivery-receipt.ts";
 
 const MAX_ENTRIES = 50_000;
 const MAX_ITEMS = 200;
 const MAX_TEXT = 16_384;
 const ANSI = /\u001b(?:\[[0-?]*[ -/]*[@-~]|[@-_])/g;
 const COMPLETION_GATE = /^\[Piagent completion gate: (CONTINUING|NOT APPROVED)\]/i;
+const INTERNAL_FRESH_TRANSITION = new RegExp(
+  `^\\/fresh\\s+(?:${workflowCommandPattern({ aliases: false })})\\s+(?:--session-title\\s+"[^"\\r\\n]{1,64}"\\s+)?Read task intake from \\.pi\\/task-inbox\\/[A-Za-z0-9._-]+\\.md\\.\\s+Current session is near context limits; use a fresh governed session\\.$`, "u"
+);
 
 type TranscriptIdentity = { projectRef: string; runtimeInstanceId: string; sessionRef: string; taskId: string | null; taskRunId: string | null;
   agentOperationId: null; toolCallId: null };
@@ -16,8 +25,8 @@ type TranscriptRevision = { runtimeRevision: string; taskRevision: string | null
 type TranscriptContent = { state: "available" | "redacted" | "unavailable"; text: string | null; textChars: number | null; digest: string | null;
   truncated: boolean; redacted: boolean; imageCount: number; reasonCode: string | null };
 type TranscriptAttachment = { displayName: string; kind: "file" | "image" | "document"; mimeType: string; truncated: boolean };
-type TranscriptItem = { messageRef: string; parentMessageRef: string | null; role: "user" | "assistant" | "tool-result"; recordedAt: string;
-  agentOperationId: string | null; turnIndex: number | null; content: TranscriptContent;
+type TranscriptItem = { messageRef: string; parentMessageRef: string | null; role: "user" | "assistant" | "tool-result" | "custom"; recordedAt: string;
+  agentOperationId: string | null; messageRequestId?: string; turnIndex: number | null; content: TranscriptContent;
   attachments?: TranscriptAttachment[];
   toolCalls: Array<{ toolCallRef: string; toolName: string; state: "requested" | "completed" | "failed" | "unknown" }> };
 export type TranscriptDocument = { schemaVersion: 1; version: "piagent-webui-transcript-v1"; generatedAt: string; identity: TranscriptIdentity;
@@ -32,6 +41,9 @@ export type TranscriptProjectionInput = {
   beforeCursor?: string | null;
   limit?: number;
   generatedAt?: string;
+  taskOutcome?: string | null;
+  terminalDeliveryReceipt?: TerminalDeliveryReceipt;
+  terminalDeliveryEntries?: unknown[];
 };
 
 function hash(value: string): string { return createHash("sha256").update(value).digest("hex"); }
@@ -134,16 +146,15 @@ function role(message: any): TranscriptItem["role"] | null {
 }
 function isInternalFreshTransition(message: any): boolean {
   if (message?.role !== "user") return false;
-  return /^\/fresh\s+(?:task|scout|be-to-fe)\s+(?:--session-title\s+"[^"\r\n]{1,64}"\s+)?Read task intake from \.pi\/task-inbox\/[A-Za-z0-9._-]+\.md\.\s+Current session is near context limits; use a fresh governed session\.$/u
-    .test(messageText(message).trim());
+  return INTERNAL_FRESH_TRANSITION.test(messageText(message).trim());
 }
 function unavailableContent(reasonCode: string): TranscriptContent {
   return { state: "unavailable", text: null, textChars: null, digest: null, truncated: false, redacted: false, imageCount: 0, reasonCode };
 }
-function item(entry: any, identity: TranscriptIdentity): TranscriptItem | null {
+function item(entry: any, identity: TranscriptIdentity, customReceipt = false): TranscriptItem | null {
   if (!entry || entry.type !== "message" || !entry.message) return null;
   if (isInternalFreshTransition(entry.message)) return null;
-  const itemRole = role(entry.message), recordedAt = timestamp(entry.timestamp ?? entry.message.timestamp);
+  const itemRole = customReceipt ? "custom" : role(entry.message), recordedAt = timestamp(entry.timestamp ?? entry.message.timestamp);
   if (!itemRole || !recordedAt || typeof entry.id !== "string" || entry.id.length === 0) return null;
   const userProjection = userMessageProjection(entry.message);
   const projectedToolCalls = toolCalls(entry.message, identity.sessionRef, itemRole);
@@ -159,6 +170,127 @@ function item(entry: any, identity: TranscriptIdentity): TranscriptItem | null {
     agentOperationId: null, turnIndex: null, content, ...(userProjection.attachments.length ? { attachments: userProjection.attachments } : {}),
     toolCalls: projectedToolCalls };
 }
+
+type ProjectedTranscriptItem = { entry: any; item: TranscriptItem; cursor: string };
+
+function correlatedTranscriptItems(entries: unknown[], identity: TranscriptIdentity,
+  receiptPairs: Map<unknown, TerminalDeliveryPair>): ProjectedTranscriptItem[] {
+  let pending: WebUiMessageCorrelation | null = null;
+  let turn: WebUiMessageCorrelation | null = null;
+  const values: ProjectedTranscriptItem[] = [];
+  for (const entry of entries as any[]) {
+    const pair = receiptPairs.get(entry);
+    if (pair) {
+      // Project the admitted request and real custom receipt without writing
+      // fabricated user/assistant messages into Pi's durable model history.
+      for (const [source, itemRole, content] of [[pair.requestEntry, "user", pair.request],
+        [pair.receiptEntry, "custom", pair.receipt.content]] as const) {
+        const projected = item({ ...source, type: "message", message: { role: itemRole, content } }, identity, itemRole === "custom");
+        if (projected) values.push({ entry: source, item: { ...projected, agentOperationId: pair.correlation.operationRef,
+          messageRequestId: pair.correlation.messageRequestId }, cursor: opaque("transcript", [identity.sessionRef, source.id]) });
+      }
+      pending = null; turn = null; continue;
+    }
+    if (entry?.type === "custom" && entry.customType === WEBUI_MESSAGE_CORRELATION_ENTRY_TYPE) {
+      // A newer marker supersedes an older marker that never reached a user
+      // message. Invalid markers fail closed instead of leaking correlation
+      // from an earlier admitted-but-undispatched operation into a later turn.
+      pending = webUiMessageCorrelationEntry(entry);
+      continue;
+    }
+    if (role(entry?.message) === "user") { turn = pending; pending = null; }
+    const projected = item(entry, identity);
+    if (!projected) continue;
+    values.push({ entry, item: turn ? { ...projected, agentOperationId: turn.operationRef,
+      messageRequestId: turn.messageRequestId } : projected,
+    cursor: opaque("transcript", [identity.sessionRef, entry?.id]) });
+  }
+  return values;
+}
+
+function linkTranscriptTurns(values: ProjectedTranscriptItem[]): ProjectedTranscriptItem[] {
+  let userMessageRef: string | null = null;
+  const toolCallOwners = new Map<string, string>();
+  return values.map((value) => {
+    let parentMessageRef: string | null = null;
+    if (value.item.role === "user") userMessageRef = value.item.messageRef;
+    else if (value.item.role === "tool-result") {
+      parentMessageRef = toolCallOwners.get(value.item.toolCalls[0]?.toolCallRef ?? "") ?? userMessageRef;
+    } else parentMessageRef = userMessageRef;
+    const linked = { ...value, item: { ...value.item, parentMessageRef } };
+    if (linked.item.role === "assistant") {
+      for (const toolCall of linked.item.toolCalls) toolCallOwners.set(toolCall.toolCallRef, linked.item.messageRef);
+    }
+    return linked;
+  });
+}
+
+function suppressOpenTaskHandoff(values: ProjectedTranscriptItem[], taskOutcome: string | null | undefined): ProjectedTranscriptItem[] {
+  if (taskOutcome !== "pending") return values;
+  let latestUser = -1;
+  for (let index = values.length - 1; index >= 0; index -= 1) {
+    if (values[index]?.item.role === "user") { latestUser = index; break; }
+  }
+  if (latestUser < 0) return values;
+  const latestPrompt = values[latestUser]?.item.content.text ?? "";
+  if (isLightweightNonAuthorizingChangeLanguage(latestPrompt)) return values;
+  return values.map((value, index) => {
+    if (index <= latestUser || value.item.role !== "assistant" || value.item.toolCalls.length > 0
+      || !["available", "redacted"].includes(value.item.content.state)
+      || !looksLikeCompletionClaim(value.item.content.text ?? "")) return value;
+    return { ...value, item: { ...value.item, content: unavailableContent("assistant-task-pending") } };
+  });
+}
+
+function durableAssistant(item: TranscriptItem): boolean {
+  return (item.role === "assistant" || item.role === "custom") && item.toolCalls.length === 0
+    && (item.content.state === "available" || item.content.state === "redacted")
+    && hasVisibleText(item.content.text ?? "");
+}
+
+function compactOversizedTurn(
+  values: ProjectedTranscriptItem[], start: number, end: number, limit: number
+): ProjectedTranscriptItem[] {
+  if (limit === 1) return [values[start]!];
+  const selected = new Set<number>([start]);
+  for (let index = end - 1; index > start; index -= 1) {
+    if (durableAssistant(values[index]!.item)) { selected.add(index); break; }
+  }
+  for (let index = end - 1; index > start && selected.size < limit; index -= 1) selected.add(index);
+  return [...selected].sort((left, right) => left - right).map((index) => values[index]!);
+}
+
+function boundedTurnPage(
+  values: ProjectedTranscriptItem[], end: number, limit: number
+): { selected: ProjectedTranscriptItem[]; start: number; compacted: boolean } {
+  if (end <= 0) return { selected: [], start: 0, compacted: false };
+  const users: number[] = [];
+  for (let index = 0; index < end; index += 1) if (values[index]?.item.role === "user") users.push(index);
+  if (users.length === 0) {
+    const start = Math.max(0, end - limit);
+    return { selected: values.slice(start, end), start, compacted: false };
+  }
+
+  const selected: ProjectedTranscriptItem[] = [];
+  let remaining = limit, turnEnd = end, start = end;
+  for (let userIndex = users.length - 1; userIndex >= 0 && remaining > 0; userIndex -= 1) {
+    const turnStart = users[userIndex]!;
+    const turnSize = turnEnd - turnStart;
+    if (turnSize > remaining) {
+      if (selected.length === 0) {
+        const compacted = compactOversizedTurn(values, turnStart, turnEnd, remaining);
+        return { selected: compacted, start: turnStart, compacted: true };
+      }
+      break;
+    }
+    selected.unshift(...values.slice(turnStart, turnEnd));
+    start = turnStart;
+    remaining -= turnSize;
+    turnEnd = turnStart;
+  }
+  return { selected, start, compacted: false };
+}
+
 function unavailable(input: TranscriptProjectionInput, reasonCode: string, limit: number): TranscriptDocument {
   return { schemaVersion: 1, version: "piagent-webui-transcript-v1", generatedAt: input.generatedAt ?? new Date().toISOString(),
     identity: structuredClone(input.identity), revision: structuredClone(input.revision), eventCursor: input.eventCursor,
@@ -168,17 +300,24 @@ function unavailable(input: TranscriptProjectionInput, reasonCode: string, limit
 export function projectTranscript(input: TranscriptProjectionInput): TranscriptDocument {
   const limit = Math.max(1, Math.min(MAX_ITEMS, Number.isInteger(input.limit) ? Number(input.limit) : 50));
   if (!Array.isArray(input.entries) || input.entries.length > MAX_ENTRIES) return unavailable(input, "transcript-history-unavailable", limit);
-  const projected = input.entries.map((entry) => ({ entry, item: item(entry, input.identity) })).filter((value): value is { entry: any; item: TranscriptItem } => Boolean(value.item));
-  const cursors = projected.map(({ entry }) => opaque("transcript", [input.identity.sessionRef, entry.id]));
+  const receipt = input.terminalDeliveryReceipt;
+  const boundReceipt = receipt?.details.taskId === input.identity.taskId && receipt?.details.taskRunId === input.identity.taskRunId
+    && receipt?.details.outcome === input.taskOutcome ? receipt : undefined;
+  const receiptPairs = new Map(terminalDeliveryPairs(input.entries, boundReceipt, input.terminalDeliveryEntries)
+    .map((pair) => [pair.receiptEntry, pair]));
+  const projected = suppressOpenTaskHandoff(linkTranscriptTurns(correlatedTranscriptItems(input.entries, input.identity,
+    receiptPairs)), input.taskOutcome);
+  const cursors = projected.map((value) => value.cursor);
   let end = projected.length;
   if (input.beforeCursor) {
     const cursorIndex = cursors.indexOf(input.beforeCursor);
     if (cursorIndex < 0) return unavailable(input, "transcript-cursor-gap", limit);
     end = cursorIndex;
   }
-  const start = Math.max(0, end - limit), selected = projected.slice(start, end).map((value) => value.item), hasOlder = start > 0;
+  const page = boundedTurnPage(projected, end, limit), selected = page.selected.map((value) => value.item), hasOlder = page.start > 0;
   return { schemaVersion: 1, version: "piagent-webui-transcript-v1", generatedAt: input.generatedAt ?? new Date().toISOString(),
     identity: structuredClone(input.identity), revision: structuredClone(input.revision), eventCursor: input.eventCursor,
-    state: "ready", items: selected, page: { beforeCursor: input.beforeCursor ?? null, nextBeforeCursor: hasOlder ? cursors[start] : null,
-      hasOlder, limit, truncated: projected.length !== input.entries.filter((entry: any) => entry?.type === "message").length }, reasonCode: null };
+    state: "ready", items: selected, page: { beforeCursor: input.beforeCursor ?? null, nextBeforeCursor: hasOlder ? cursors[page.start] : null,
+      hasOlder, limit, truncated: page.compacted || projected.length !== input.entries.filter((entry: any) => entry?.type === "message").length
+        + receiptPairs.size * 2 }, reasonCode: null };
 }