@opengeni/react 0.57.0 → 1.0.2-canary.37191796234001

package/src/timeline/projection.ts

@@ -1,13 +1,23 @@
 import {
   parseMediaGenerationResult,
+  parseToolDisplayMetadata,
+  EMPTY_FINAL_REPLY_NOTICE,
+  turnCompletedWithEmptyFinalReply,
+  type HumanInputAnswer,
+  type HumanInputQuestion,
+  type HumanInputResponse,
   type SessionEvent,
   type SessionStatus,
   type TimelineAnnotation,
 } from "@opengeni/sdk";
 import fleetDecisionItem from "./fleet-decision-projection";
+import {
+  allowanceExhaustedMessage,
+  parseAllowanceExhaustedRefusal,
+} from "@opengeni/sdk/allowance-refusal";
 import {
   CREDIT_EXHAUSTION_MESSAGE,
-  humanizeFailureReason,
+  presentFailure,
   isCreditExhaustion,
   tryParseJson,
 } from "../lib/format";
@@ -18,9 +28,15 @@ import type {
   AuthNeededItem,
   ContextCompactionItem,
   GoalItem,
+  HumanInputAnswerSummary,
+  HumanInputItem,
   MachineInputBatchItem,
+  MachineInputMember,
   MemoryItem,
+  NoticeItem,
   SandboxItem,
+  StartupPhase,
+  StartupPhaseItem,
   SessionStatusItem,
   TimelineGroup,
   TimelineItem,
@@ -32,6 +48,14 @@ import type {
 
 export { toolDisplayName, mcpToolLeaf, toolMatchesLeaf } from "./tool-display-name";
 
+/** Message identity only: queue placement needs the surrounding turn history. */
+export function isTimelineUserQuestion(event: SessionEvent): boolean {
+  return (
+    event.type === "user.message" &&
+    workerCompletionPayload(asRecord(event.payload).childCompletion) === null
+  );
+}
+
 /* ----------------------------------------------------------------------------
    Timeline projection
 
@@ -51,6 +75,8 @@ const WORKER_SPAWN_TOOL = "session_create";
 const WORKER_MESSAGE_TOOL = "session_send_message";
 const WORKER_FAILURE_CODE_MAX_LENGTH = 128;
 const WORKER_FAILURE_MESSAGE_MAX_UTF8_BYTES = 1_024;
+type PendingWaitOutcome = { id: string; reason: string; occurredAt: string };
+type TrackedAgentResponse = { item: AgentMessageItem; completed: boolean };
 
 /**
  * Tools whose durable side-effect events already own the timeline (MemoryRow).
@@ -120,13 +146,199 @@ function timelineAnnotationToolOutputText(output: unknown): string | null {
   return text.length > 0 ? text : null;
 }
 
-export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
+export function buildTimeline(
+  events: SessionEvent[],
+  options: { partialStart?: boolean } = {},
+): TimelineItem[] {
   const items: TimelineItem[] = [];
+  const allowanceNotices = new Set<string>();
+  const allowanceNotice = (event: SessionEvent, turnId: string | null) => {
+    const refusal = parseAllowanceExhaustedRefusal(event.payload);
+    if (!refusal) return null;
+    const text = allowanceExhaustedMessage(refusal);
+    const key = JSON.stringify([
+      turnId,
+      event.turnAttemptId,
+      startupRecoveryRevisionByTurn.get(turnId ?? "") ?? 0,
+      refusal.scope,
+      refusal.subjectId,
+      refusal.resetsAt,
+    ]);
+    if (!allowanceNotices.has(key)) {
+      allowanceNotices.add(key);
+      items.push({
+        kind: "notice",
+        id: `${event.id}-allowance`,
+        tone: "failed",
+        text,
+        // The canonical sentence replaces upstream prose, so a host renderer
+        // reading `message` never shows a wrapper's private wording.
+        allowance: { ...refusal, message: text },
+        occurredAt: event.occurredAt,
+      });
+    }
+    return text;
+  };
   const prescan = prescanTurnAnchors(events);
   const ordered = orderTimelineEvents(events, prescan);
+  // A bounded replay can begin halfway through a message (including inside an
+  // interactive fence). Never parse that suffix as a complete Markdown source.
+  // Keep the raw events available for pagination; a completed receipt restores
+  // the authoritative message without requiring an unbounded history fetch.
+  let completeHistoryPrefix = options.partialStart !== true;
+  const knownMessagePrefixTurns = new Set<string | null>();
+  const incompleteMessageKeys = new Set<string>();
+  const pendingWaitOutcomeByTurn = new Map<string | null, PendingWaitOutcome>();
+  const latestAgentResponseByTurn = new Map<string | null, TrackedAgentResponse>();
+  const identifiedMessages = new Map<string, AgentMessageItem>();
+  const humanInputRequests = humanInputRequestsById(events);
+  const humanInputToolCallIds = new Set(
+    [...humanInputRequests.values()]
+      .map((request) => stringValue(request.toolCallId))
+      .filter(Boolean),
+  );
+  // Delegated workers that have not reported back yet, so a recorded agent wait
+  // can say how many agents it is waiting for. Only a session's own workers
+  // report back, so a message to any other session is never awaited. Best
+  // effort: a bounded replay only knows the spawns and results inside its window.
+  const workerSessions = new Set<string>();
+  const pendingWorkerSessions = new Set<string>();
+  let openWaitNotice: NoticeItem | null = null;
+  // Tool results update the original tool row in place, and running lifecycle
+  // receipts have no row. Carry resume evidence on the attention landmarks so
+  // grouping cannot mistake historical approval for a live wait.
+  const presentationWaits = new Map<string | null, Array<NoticeItem | SessionStatusItem>>();
+  const presentationFailures = new Map<string | null, SessionStatusItem[]>();
+  let presentationTurnId: string | null = null;
+  const rememberPresentationWait = (
+    item: NoticeItem | SessionStatusItem,
+    turnId: string | null,
+  ) => {
+    const key = turnId ?? presentationTurnId;
+    const waits = presentationWaits.get(key) ?? [];
+    waits.push(item);
+    presentationWaits.set(key, waits);
+    items.push(item);
+  };
+  const resolvePresentationWait = (event: SessionEvent, turnId: string | null) => {
+    if (event.duplicateOfEventId || (event.turnAssociation && event.turnAssociation !== "current"))
+      return;
+    const key = turnId ?? presentationTurnId;
+    for (const item of presentationWaits.get(key) ?? []) item.resolvedAt = event.occurredAt;
+    presentationWaits.delete(key);
+  };
+  const queuedAtByTurn = new Map<string, string>();
+  const startupRecoveryRevisionByTurn = new Map<string, number>();
+  const startupPhases = new Map<string, readonly [StartupPhaseItem, string | null, number]>();
+  let startupEvent: SessionEvent;
+  let startupTurnId: string | null = null;
+  let startupAttemptId: string | null = null;
+  let startupRecoveryRevision = 0;
+
+  const settleStartupPhase = (
+    phase: StartupPhase,
+    status: StartupPhaseItem["status"],
+    duration: number | null,
+    outcome: StartupPhaseItem["outcome"],
+    mode = 0,
+    explicitStartedAt?: string,
+    explicitId?: string,
+    blockedReason?: StartupPhaseItem["blockedReason"],
+  ): void => {
+    const key = `${startupTurnId}:${phase}`;
+    const priorState = startupPhases.get(key);
+    const prior = priorState?.[0];
+    const comparedByAttempt = priorState?.[1] && startupAttemptId;
+    const sameAttempt = comparedByAttempt
+      ? priorState[1] === startupAttemptId
+      : (priorState?.[2] ?? 0) === startupRecoveryRevision;
+    const open = prior?.status === "running" && sameAttempt ? prior : undefined;
+    const replacesPriorAttempt =
+      prior !== undefined &&
+      (comparedByAttempt ? !sameAttempt : startupRecoveryRevision > (priorState?.[2] ?? 0));
+    // A later activity attempt may replay preparation that the logical turn had
+    // already completed before the worker moved. Keep that first successful
+    // landmark; only an abandoned or failed attempt needs replacement.
+    if (replacesPriorAttempt && prior.status === "complete") return;
+    if (mode === 2 && prior && !replacesPriorAttempt) return;
+    if (mode === 1 && !open) return;
+    if (!replacesPriorAttempt && status !== "running" && open) {
+      open.status = status;
+      open.completedAt = startupEvent.occurredAt;
+      open.durationMs =
+        duration === null
+          ? elapsedDurationMs(open.startedAt, startupEvent.occurredAt)
+          : Math.max(0, duration);
+      open.outcome = outcome ?? open.outcome;
+      open.blockedReason = blockedReason;
+      return;
+    }
+    const running = status === "running";
+    const durationMs = running || duration === null ? null : Math.max(0, duration);
+    const completedEpoch = Date.parse(startupEvent.occurredAt);
+    const startedAt =
+      explicitStartedAt ??
+      (!running && durationMs !== null && Number.isFinite(completedEpoch)
+        ? new Date(completedEpoch - durationMs).toISOString()
+        : startupEvent.occurredAt);
+    if (replacesPriorAttempt) {
+      Object.assign(prior, {
+        id: explicitId ?? startupEvent.id,
+        status,
+        startedAt,
+        completedAt: running ? null : startupEvent.occurredAt,
+        durationMs,
+        outcome,
+        blockedReason,
+        occurredAt: startedAt,
+      } satisfies Partial<StartupPhaseItem>);
+      startupPhases.set(key, [prior, startupAttemptId, startupRecoveryRevision]);
+      return;
+    }
+    const item: StartupPhaseItem = {
+      kind: "startup-phase",
+      id: explicitId ?? startupEvent.id,
+      turnId: startupTurnId,
+      phase,
+      status,
+      startedAt,
+      completedAt: running ? null : startupEvent.occurredAt,
+      durationMs,
+      outcome,
+      blockedReason,
+      occurredAt: startedAt,
+    };
+    items.push(item);
+    startupPhases.set(key, [item, startupAttemptId, startupRecoveryRevision]);
+  };
 
   const last = (): TimelineItem | undefined => items[items.length - 1];
 
+  const rememberAgentResponse = (
+    turnId: string | null,
+    item: AgentMessageItem,
+    completed: boolean,
+  ): void => {
+    latestAgentResponseByTurn.set(turnId, { item, completed });
+  };
+
+  const takePendingWaitOutcome = (turnId: string | null): PendingWaitOutcome | undefined => {
+    const outcome = pendingWaitOutcomeByTurn.get(turnId);
+    pendingWaitOutcomeByTurn.delete(turnId);
+    return outcome;
+  };
+
+  const takeAgentResponse = (turnId: string | null): TrackedAgentResponse | undefined => {
+    const response = latestAgentResponseByTurn.get(turnId);
+    latestAgentResponseByTurn.delete(turnId);
+    return response;
+  };
+
+  const clearUnscopedTerminalTracking = (): void => {
+    latestAgentResponseByTurn.delete(null);
+    pendingWaitOutcomeByTurn.delete(null);
+  };
+
   /** A new item of a different kind ends whatever was streaming at the tail. */
   const closeStreamingTail = (): void => {
     const open = last();
@@ -138,6 +350,7 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
   const finalizeOpen = (
     turnId?: string | null,
     disposition: "complete" | "failed" | "cancelled" = "complete",
+    completedAt?: string,
   ): void => {
     for (const item of items) {
       if (
@@ -158,20 +371,119 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
       if (item.kind === "sandbox" && item.status === "running") {
         item.status = disposition;
       }
+      if (item.kind === "startup-phase" && item.status === "running") {
+        item.status = disposition;
+        if (completedAt) {
+          item.completedAt = completedAt;
+          item.durationMs = elapsedDurationMs(item.startedAt, completedAt);
+        }
+      }
     }
   };
 
   for (const event of ordered) {
     const payload = asRecord(event.payload);
     const turnId = event.turnId ?? null;
+    if (
+      turnId &&
+      (event.type === "turn.started" ||
+        (presentationTurnId === null && isAgentActivityEvent(event.type)))
+    ) {
+      presentationTurnId = turnId;
+    }
+    if (
+      openWaitNotice &&
+      (event.type === "user.message" ||
+        event.type === "system.update.delivered" ||
+        event.type === "turn.started" ||
+        event.type === "session.control.paused" ||
+        (event.type === "session.status.changed" &&
+          (payload.status === "cancelled" || payload.status === "failed")))
+    ) {
+      // New input, a pause, or the end of the session ends a recorded wait; the
+      // notice keeps its wait span.
+      openWaitNotice.waitEndedAt = event.occurredAt;
+      openWaitNotice = null;
+    }
+    if (event.type === "session.created") {
+      completeHistoryPrefix = true;
+    } else if (
+      event.type === "turn.started" ||
+      (event.type === "user.message" &&
+        payload.delivery !== "steer" &&
+        payload.routing !== "accepted_for_steering")
+    ) {
+      // Accepted Steer is visible before its replacement turn starts. It says
+      // nothing about the prefix of a still-streaming message from the old turn.
+      knownMessagePrefixTurns.add(turnId);
+    }
+    startupEvent = event;
+    startupTurnId = turnId;
+    startupAttemptId =
+      (typeof event.turnAttemptId === "string" ? event.turnAttemptId : null) ??
+      stringValue(payload.attemptId);
+    startupRecoveryRevision = turnId ? (startupRecoveryRevisionByTurn.get(turnId) ?? 0) : 0;
+    const setupPhase = event.type.startsWith("rig.setup.")
+      ? "rig"
+      : event.type.startsWith("turn.startup.phase.")
+        ? startupPhaseFromPayload(payload.phase)
+        : null;
+    const setupStatus = event.type.endsWith(".started")
+      ? "running"
+      : event.type.endsWith(".failed")
+        ? "failed"
+        : event.type.endsWith(".completed") || event.type === "rig.setup.skipped"
+          ? "complete"
+          : null;
+    if (setupPhase && setupStatus) {
+      closeStreamingTail();
+      let blockedReason: StartupPhaseItem["blockedReason"];
+      if (setupPhase === "model_preparation" && setupStatus === "failed") {
+        blockedReason = startupLifecycleWaitReason(payload);
+        // Older preparation events omit the typed lifecycle fields. The
+        // sandbox span can supply them only inside the same turn attempt.
+        const sandbox = startupPhases.get(`${startupTurnId}:sandbox`);
+        const sameAttempt =
+          sandbox?.[1] || startupAttemptId
+            ? Boolean(startupAttemptId && sandbox?.[1] === startupAttemptId)
+            : sandbox?.[2] === startupRecoveryRevision;
+        if (
+          !blockedReason &&
+          payload.expectedTransition === undefined &&
+          payload.failureCode === undefined &&
+          payload.failureStage === undefined &&
+          payload.failureCategory === undefined &&
+          payload.error === undefined &&
+          startupTurnId &&
+          sameAttempt &&
+          sandbox?.[0].status === "cancelled"
+        ) {
+          blockedReason = sandbox[0].blockedReason;
+        }
+      }
+      settleStartupPhase(
+        setupPhase,
+        blockedReason ? "cancelled" : setupStatus,
+        numberOrNull(payload.durationMs),
+        event.type === "rig.setup.skipped" ? "skipped" : null,
+        0,
+        undefined,
+        undefined,
+        blockedReason,
+      );
+      continue;
+    }
 
     switch (event.type) {
       case "user.message": {
         // A steering message must not mark in-flight tools complete; it only
         // ends whatever text was streaming. Turn lifecycle events finalize.
+        clearUnscopedTerminalTracking();
         closeStreamingTail();
         const childCompletion = workerCompletionPayload(payload.childCompletion);
         if (childCompletion) {
+          workerSessions.add(childCompletion.childSessionId);
+          pendingWorkerSessions.delete(childCompletion.childSessionId);
           items.push({
             kind: "worker-completion",
             id: event.id,
@@ -191,6 +503,9 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
         items.push({
           kind: "user-message",
           id: event.id,
+          ...(event.clientEventId
+            ? { reconciliationKey: `user-message:${event.clientEventId}` }
+            : {}),
           text: voiceMessage?.text ?? stringValue(payload.text),
           annotations: timelineAnnotations(payload.annotations),
           annotationSource: {
@@ -209,13 +524,38 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
         break;
       }
 
+      case "user.humanInputResponse": {
+        // A structured answer resumes the frozen tool call rather than adding a
+        // synthetic user.message to model history. Keep the original question
+        // and the resolved human choice together as first-class chat history;
+        // neither belongs behind the generic activity fold.
+        const item = humanInputItemFromResponse(event, payload, humanInputRequests);
+        if (!item) break;
+        closeStreamingTail();
+        items.push(item);
+        break;
+      }
+
       case "system.update.delivered": {
         const inputs = machineInputMembers(payload.members);
+        for (const input of inputs) {
+          if (input.kind === "child_terminal_result") {
+            workerSessions.add(input.sourceId);
+            pendingWorkerSessions.delete(input.sourceId);
+          }
+        }
         if (inputs.length === 0) break;
-        // Goal continuations already land as `goal.continuation` GoalRows.
-        // A solo continuation batch would duplicate that landmark + dump the
-        // model-facing prompt — skip chrome for that case only.
-        if (inputs.every((member) => member.kind === "goal_continuation")) {
+        // Background command receipts are agent-facing inputs, not chat messages.
+        // The durable event remains available to the agent and audit history.
+        const visibleInputs = inputs.filter(
+          (member) => member.kind !== "background_command_result",
+        );
+        // Goal continuations already have GoalRows. A batch with no other
+        // visible update must not interrupt an in-flight streaming message.
+        if (
+          visibleInputs.length === 0 ||
+          visibleInputs.every((member) => member.kind === "goal_continuation")
+        ) {
           break;
         }
         closeStreamingTail();
@@ -223,7 +563,7 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
           kind: "machine-input-batch",
           id: event.id,
           turnId,
-          members: inputs,
+          members: visibleInputs,
           occurredAt: event.occurredAt,
         });
         break;
@@ -234,30 +574,85 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
         if (!text) {
           break;
         }
+        const messageId = stringValue(payload.messageId);
+        const messageKey = messageId ? JSON.stringify([turnId, messageId]) : null;
+        // Responses providers declare the phase when they announce the item, so
+        // a streaming progress note is known as commentary before it completes.
+        const phase = assistantMessagePhase(payload.phase);
+        if (
+          (!completeHistoryPrefix && !knownMessagePrefixTurns.has(turnId)) ||
+          (messageKey && incompleteMessageKeys.has(messageKey))
+        ) {
+          if (messageKey) incompleteMessageKeys.add(messageKey);
+          break;
+        }
+        const identified = messageKey ? identifiedMessages.get(messageKey) : undefined;
+        if (identified) {
+          if (identified.annotationSource?.eventType !== "agent.message.completed") {
+            identified.text += text;
+            if (phase && !identified.phase) identified.phase = phase;
+            rememberAgentResponse(turnId, identified, false);
+          }
+          break;
+        }
         const open = last();
-        if (open?.kind === "agent-message" && open.streaming && open.turnId === turnId) {
+        if (!messageKey && open?.kind === "tool-call" && open.status === "running") {
+          const previous = latestAgentResponseByTurn.get(turnId);
+          const previousIndex = previous ? items.indexOf(previous.item) : -1;
+          if (
+            previous &&
+            !previous.completed &&
+            previousIndex >= 0 &&
+            items
+              .slice(previousIndex + 1)
+              .every(
+                (item) =>
+                  item.kind === "tool-call" && item.turnId === turnId && item.status === "running",
+              )
+          ) {
+            // Legacy deltas have no provider message identity. Tool creation
+            // alone is not a text boundary; completed output still is.
+            previous.item.text += text;
+            break;
+          }
+        }
+        if (
+          !messageKey &&
+          open?.kind === "agent-message" &&
+          open.streaming &&
+          open.turnId === turnId
+        ) {
           open.text += text;
+          rememberAgentResponse(turnId, open, false);
           break;
         }
         closeStreamingTail();
-        items.push({
+        const item: AgentMessageItem = {
           kind: "agent-message",
           id: event.id,
           turnId,
           text,
+          ...(phase ? { phase } : {}),
           streaming: true,
           occurredAt: event.occurredAt,
-        });
+        };
+        items.push(item);
+        if (messageKey) identifiedMessages.set(messageKey, item);
+        rememberAgentResponse(turnId, item, false);
         break;
       }
 
       case "agent.message.completed": {
+        knownMessagePrefixTurns.add(turnId);
         const text = stringValue(payload.text);
+        const messageId = stringValue(payload.messageId);
+        const messageKey = messageId ? JSON.stringify([turnId, messageId]) : null;
+        const phase = assistantMessagePhase(payload.phase);
         // Reconcile the most recent same-turn agent message — even when
         // activity (tool calls, reasoning) landed after its deltas — so the
         // completed text never duplicates the streamed one.
-        let openIndex = -1;
-        for (let index = items.length - 1; index >= 0; index -= 1) {
+        let openIndex = messageKey ? items.indexOf(identifiedMessages.get(messageKey)!) : -1;
+        for (let index = messageKey ? -1 : items.length - 1; index >= 0; index -= 1) {
           const candidate = items[index];
           if (candidate?.kind === "agent-message" && candidate.turnId === turnId) {
             openIndex = index;
@@ -269,15 +664,26 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
           candidate?.kind === "agent-message" ? candidate : undefined;
         if (
           open &&
-          (open.streaming || !open.text || text === open.text || text.startsWith(open.text))
+          (messageKey ||
+            open.streaming ||
+            !open.text ||
+            text === open.text ||
+            text.startsWith(open.text))
         ) {
-          // The completed text is authoritative when it extends what streamed.
-          if (!open.text || (text && text.startsWith(open.text))) {
+          // Identity makes the final text authoritative even if it corrects the
+          // draft; legacy receipts still require an extension match.
+          if (!open.text || (text && (messageKey || text.startsWith(open.text)))) {
             open.text = text || open.text;
           }
+          // A phase-less settlement mirror (the worker's final-output receipt)
+          // must not erase the provider-declared phase captured by the SDK item.
+          if (phase) open.phase = phase;
+          // Completion time is what the footer shows ("finished at"); the
+          // first-delta stamp stays as the stream's start.
+          if (open.startedAt === undefined && open.occurredAt !== event.occurredAt) {
+            open.startedAt = open.occurredAt;
+          }
           open.streaming = false;
-          // Completion time is what the footer shows ("finished at"); keep the
-          // first-delta stamp only until this event arrives.
           open.occurredAt = event.occurredAt;
           open.annotationSource =
             text && open.text === text
@@ -299,14 +705,16 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
             items.splice(openIndex, 1);
             items.push(open);
           }
+          rememberAgentResponse(turnId, open, true);
           break;
         }
         if (text) {
-          items.push({
+          const item: AgentMessageItem = {
             kind: "agent-message",
             id: event.id,
             turnId,
             text,
+            ...(phase ? { phase } : {}),
             streaming: false,
             occurredAt: event.occurredAt,
             annotationSource: {
@@ -317,7 +725,10 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
               turnId,
               text,
             },
-          });
+          };
+          items.push(item);
+          if (messageKey) identifiedMessages.set(messageKey, item);
+          rememberAgentResponse(turnId, item, true);
         }
         break;
       }
@@ -346,9 +757,16 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
 
       case "agent.toolCall.created": {
         const name = typeof payload.name === "string" ? payload.name : "tool";
+        const display = parseToolDisplayMetadata(payload.display);
         const callId = typeof payload.id === "string" ? payload.id : null;
         const args = payload.arguments ?? null;
         closeStreamingTail();
+        if (callId && humanInputToolCallIds.has(callId)) {
+          // The matching session.humanInput.requested / response lifecycle owns
+          // the visible chat card. Rendering the raw tool too would hide the
+          // decision behind a duplicate generic "Ask" step.
+          break;
+        }
         if (
           toolMatchesLeaf(name, WORKER_SPAWN_TOOL) ||
           toolMatchesLeaf(name, WORKER_MESSAGE_TOOL)
@@ -381,6 +799,7 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
               (item): item is ToolCallItem => item.kind === "tool-call" && item.callId === callId,
             );
           if (existing) {
+            if (display) existing.display = display;
             if (args != null) {
               existing.arguments = args;
             }
@@ -397,6 +816,7 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
           turnId,
           callId,
           name,
+          ...(display ? { display } : {}),
           arguments: args,
           output: undefined,
           truncation: null,
@@ -415,12 +835,20 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
         if (!target) {
           break;
         }
+        resolvePresentationWait(event, turnId ?? target.turnId);
         if (target.kind === "worker") {
           // A worker spawn/message that returns an error flag (or an MCP
           // isError result) settles to "failed" too, so WorkerRow surfaces it.
           target.status = isErrorOutput(payload) ? "failed" : "complete";
           target.workerSessionId = target.workerSessionId ?? extractSessionRef(payload.output);
           target.failure = target.status === "failed" ? workerFailure(payload.output) : null;
+          // A spawned or re-messaged worker owes this session a result.
+          if (target.status === "complete" && target.workerSessionId) {
+            if (target.action === "spawn") workerSessions.add(target.workerSessionId);
+            if (workerSessions.has(target.workerSessionId)) {
+              pendingWorkerSessions.add(target.workerSessionId);
+            }
+          }
           break;
         }
         // An output carrying an explicit error flag (or an MCP isError result)
@@ -452,15 +880,73 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
         break;
       }
 
+      case "turn.queued": {
+        const queuedTurnId = turnId ?? (typeof payload.turnId === "string" ? payload.turnId : null);
+        if (queuedTurnId) {
+          queuedAtByTurn.set(queuedTurnId, event.occurredAt);
+        }
+        break;
+      }
+
+      case "turn.started": {
+        if (turnId) clearUnscopedTerminalTracking();
+        if (!turnId) break;
+        const queuedAt = queuedAtByTurn.get(turnId);
+        if (!queuedAt) break;
+        // Recovery starts the same logical turn again. Queue latency belongs to
+        // the first admission only, so consume the queued timestamp after its
+        // first projection instead of manufacturing another queue span.
+        queuedAtByTurn.delete(turnId);
+        closeStreamingTail();
+        settleStartupPhase(
+          "queue",
+          "complete",
+          elapsedDurationMs(queuedAt, event.occurredAt),
+          null,
+          0,
+          queuedAt,
+          `${event.id}-queue`,
+        );
+        break;
+      }
+
       case "sandbox.operation.started":
       case "sandbox.operation.completed":
       case "sandbox.operation.failed": {
         const name = typeof payload.name === "string" ? payload.name : "sandbox";
         const status = event.type.endsWith(".failed")
-          ? "failed"
+          ? payload.expectedTransition === true
+            ? "cancelled"
+            : "failed"
           : event.type.endsWith(".completed")
             ? "complete"
             : "running";
+        const origin =
+          payload.origin === "created" ||
+          payload.origin === "restored" ||
+          payload.origin === "resumed"
+            ? payload.origin
+            : null;
+        const startupPhase = startupPhaseForSandboxOperation(name);
+        if (startupPhase) {
+          closeStreamingTail();
+          settleStartupPhase(
+            startupPhase,
+            status,
+            numberOrNull(payload.durationMs),
+            origin,
+            0,
+            undefined,
+            undefined,
+            status === "cancelled"
+              ? (startupLifecycleWaitReason(payload) ??
+                  (payload.failureCode === "rotation_in_progress"
+                    ? "rotation_in_progress"
+                    : undefined))
+              : undefined,
+          );
+          break;
+        }
         // Routine per-turn platform plumbing that runs before EVERY turn to
         // guarantee box contents survive a re-warm — NOT the agent redoing work:
         //   - repository-clone: idempotent clone check + off-manifest token re-seed;
@@ -471,8 +957,13 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
         // Rendering either every turn reads as churn. Only FAILURES surface, and
         // they surface loudly — the failed event below creates its own item even
         // without a started row.
+        //   - optional-repository-access: the worker's per-turn report of an
+        //     automatically attached repository that sat the turn out, reported
+        //     like a skipped optional clone (event payload + log, no row).
         if (
-          (name === "repository-clone" || name === "file-resource-download") &&
+          (name === "repository-clone" ||
+            name === "file-resource-download" ||
+            name === "optional-repository-access") &&
           status !== "failed"
         ) {
           break;
@@ -480,13 +971,7 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
         const existing = findOpenSandbox(items, name);
         if (existing && status !== "running") {
           existing.status = status;
-          if (
-            payload.origin === "created" ||
-            payload.origin === "restored" ||
-            payload.origin === "resumed"
-          ) {
-            existing.origin = payload.origin;
-          }
+          if (origin) existing.origin = origin;
           const message = failureMessage(payload);
           if (message) {
             existing.output = existing.output ? `${existing.output}\n${message}` : message;
@@ -502,12 +987,7 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
             name,
             command: typeof payload.command === "string" ? payload.command : null,
             output: failureMessage(payload) ?? "",
-            origin:
-              payload.origin === "created" ||
-              payload.origin === "restored" ||
-              payload.origin === "resumed"
-                ? payload.origin
-                : null,
+            origin,
             status,
             occurredAt: event.occurredAt,
           });
@@ -515,6 +995,29 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
         break;
       }
 
+      case "agent.model.request": {
+        const requestPhase = typeof payload.phase === "string" ? payload.phase : null;
+        const status =
+          requestPhase === "started"
+            ? "running"
+            : requestPhase === "first_byte" || requestPhase === "first_event"
+              ? "complete"
+              : requestPhase === "failed" || requestPhase === "timed_out"
+                ? "failed"
+                : null;
+        if (status) {
+          if (status === "running") closeStreamingTail();
+          settleStartupPhase(
+            "provider_first_byte",
+            status,
+            status === "running" ? null : numberOrNull(payload.durationMs),
+            null,
+            status === "running" ? 2 : 1,
+          );
+        }
+        break;
+      }
+
       case "sandbox.command.output.delta": {
         // `chunk` is the canonical wire field; text/output are legacy shapes.
         const text =
@@ -548,6 +1051,7 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
         if (!isSessionStatus(status)) {
           break;
         }
+        if (status === "running") resolvePresentationWait(event, turnId);
         // Only attention-worthy statuses earn a timeline divider. queued /
         // running / idle are machinery telemetry: the header pill carries the
         // live status, the shimmer says "running", and the turn chip's duration
@@ -559,30 +1063,57 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
         const previous = [...items]
           .reverse()
           .find((item): item is SessionStatusItem => item.kind === "session-status");
-        if (previous?.status === status) {
+        if (previous?.status === status && !previous.resolvedAt) {
           break;
         }
-        items.push({
+        const item: SessionStatusItem = {
           kind: "session-status",
           id: event.id,
           status,
           occurredAt: event.occurredAt,
-        });
+        };
+        if (status === "requires_action") rememberPresentationWait(item, turnId);
+        else {
+          items.push(item);
+          if (status === "failed") {
+            const key = turnId ?? presentationTurnId;
+            const failures = presentationFailures.get(key) ?? [];
+            failures.push(item);
+            presentationFailures.set(key, failures);
+          }
+        }
         break;
       }
 
-      case "session.requiresAction": {
-        finalizeOpen(turnId);
+      case "codex.capacity.waiting": {
         items.push({
           kind: "notice",
           id: event.id,
           tone: "waiting",
-          text: "Approval needed — the turn is paused until someone decides.",
+          text:
+            stringValue(payload.detail) ??
+            stringValue(payload.error) ??
+            "Waiting for Codex capacity.",
           occurredAt: event.occurredAt,
         });
         break;
       }
 
+      case "session.requiresAction": {
+        finalizeOpen(turnId, "complete", event.occurredAt);
+        rememberPresentationWait(
+          {
+            kind: "notice",
+            id: event.id,
+            tone: "waiting",
+            text: "Approval needed — the turn is paused until someone decides.",
+            occurredAt: event.occurredAt,
+          },
+          turnId,
+        );
+        break;
+      }
+
       case "session.context.compaction.requested":
       case "session.context.compaction.started": {
         closeStreamingTail();
@@ -594,6 +1125,7 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
           estimatedTokensBefore: numberOrNull(payload.estimatedTokensBefore),
           estimatedTokensAfter: null,
           skipReason: null,
+          providerRejection: null,
           implementation:
             typeof payload.implementation === "string" ? payload.implementation : null,
           occurredAt: event.occurredAt,
@@ -611,6 +1143,7 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
           estimatedTokensBefore: numberOrNull(payload.estimatedTokensBefore),
           estimatedTokensAfter: numberOrNull(payload.estimatedTokensAfter),
           skipReason: null,
+          providerRejection: null,
           implementation:
             typeof payload.implementation === "string" ? payload.implementation : null,
           occurredAt: event.occurredAt,
@@ -628,6 +1161,7 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
           estimatedTokensBefore: numberOrNull(payload.estimatedTokensBefore),
           estimatedTokensAfter: null,
           skipReason: typeof payload.reason === "string" ? payload.reason : null,
+          providerRejection: compactionProviderRejection(payload),
           implementation:
             typeof payload.implementation === "string" ? payload.implementation : null,
           occurredAt: event.occurredAt,
@@ -639,6 +1173,29 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
         // Recovery requests are durable control-plane evidence, not a user
         // message or proof that recovery succeeded. Live state already exposes
         // a genuinely recovering session; keep the raw event in Debug/audit.
+        if (turnId) {
+          startupRecoveryRevisionByTurn.set(
+            turnId,
+            (startupRecoveryRevisionByTurn.get(turnId) ?? 0) + 1,
+          );
+          if (
+            !event.duplicateOfEventId &&
+            (!event.turnAssociation || event.turnAssociation === "current")
+          ) {
+            // Human Retry reopens the existing logical turn, unlike a new
+            // prompt. Keep failure evidence, but do not let its old settlement
+            // close the recovered turn's work surface.
+            for (const item of items) {
+              if (item.kind === "turn-end" && item.turnId === turnId && item.outcome === "failed") {
+                item.resumedAt ??= event.occurredAt;
+              }
+            }
+            for (const item of presentationFailures.get(turnId) ?? []) {
+              item.resolvedAt = event.occurredAt;
+            }
+            presentationFailures.delete(turnId);
+          }
+        }
         break;
       }
 
@@ -652,6 +1209,7 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
       case "tool.auth_needed":
       case "credential.auth_needed": {
         const capability = capabilityAuthorizationRequest(payload.capability);
+        const setupRequest = customMcpSetupRequest(payload.setupRequest);
         if (
           event.type === "tool.auth_needed" &&
           !stringValue(payload.toolName) &&
@@ -674,25 +1232,44 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
           id: event.id,
           turnId,
           serverId: typeof payload.serverId === "string" ? payload.serverId : null,
-          source: capability
-            ? "capability"
-            : event.type === "tool.auth_needed"
-              ? "tool"
-              : "credential",
+          canonicalServerId:
+            typeof payload.canonicalServerId === "string" ? payload.canonicalServerId : null,
+          connectionSubjectScope:
+            payload.connectionSubjectScope === "subject" ||
+            payload.connectionSubjectScope === "workspace"
+              ? payload.connectionSubjectScope
+              : null,
+          source:
+            capability || setupRequest
+              ? "capability"
+              : event.type === "tool.auth_needed"
+                ? "tool"
+                : "credential",
           providerDomain: stringValue(payload.providerDomain),
           connectionId: typeof payload.connectionId === "string" ? payload.connectionId : null,
-          reason: authNeededReason(payload.reason),
+          authoritySource: payload.authoritySource === "host" ? "host" : null,
+          reason: authNeededReason(
+            payload.authoritySource === "host" && typeof payload.authorizationUrl === "string"
+              ? (payload.hostReason ?? payload.reason)
+              : payload.reason,
+          ),
           scopes: stringList(payload.scopes),
           resource: typeof payload.resource === "string" ? payload.resource : null,
           toolName: typeof payload.toolName === "string" ? payload.toolName : null,
           authorizationUrl:
             typeof payload.authorizationUrl === "string" ? payload.authorizationUrl : null,
           capability,
+          setupRequest,
           occurredAt: event.occurredAt,
         });
         break;
       }
 
+      case "usage.exhausted": {
+        allowanceNotice(event, turnId);
+        break;
+      }
+
       case "turn.completed": {
         // A standalone manual compaction uses the turn ledger for fencing and
         // recovery, but it is maintenance rather than a conversational turn.
@@ -700,7 +1277,9 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
         // adding a generic turn chip would falsely make it look like an
         // extra agent response.
         if (payload.maintenance === "context_compaction") {
-          finalizeOpen(turnId);
+          finalizeOpen(turnId, "complete", event.occurredAt);
+          takeAgentResponse(turnId);
+          takePendingWaitOutcome(turnId);
           break;
         }
         // Credit exhaustion arrives as a NOMINALLY completed turn (`detail:
@@ -709,8 +1288,19 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
         // Rendering it as a clean "complete" turn is a lie that leaves the
         // session looking healthy while every future turn silently dies, so it
         // projects exactly like a failed turn plus an explicit notice.
+        const allowance = parseAllowanceExhaustedRefusal(payload);
+        if (allowance) {
+          finalizeOpen(turnId, "complete", event.occurredAt);
+          takeAgentResponse(turnId);
+          takePendingWaitOutcome(turnId);
+          items.push(turnEndItem(event, "failed", ALLOWANCE_TURN_END_TEXT));
+          allowanceNotice(event, turnId);
+          break;
+        }
         if (isCreditExhaustionPayload(payload)) {
-          finalizeOpen(turnId);
+          finalizeOpen(turnId, "complete", event.occurredAt);
+          takeAgentResponse(turnId);
+          takePendingWaitOutcome(turnId);
           items.push(turnEndItem(event, "failed", CREDIT_EXHAUSTION_MESSAGE));
           items.push({
             kind: "notice",
@@ -721,26 +1311,116 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
           });
           break;
         }
-        finalizeOpen(turnId);
-        items.push(turnEndItem(event, "complete", null));
+        const latestAgentResponse = takeAgentResponse(turnId);
+        const finalOutput = stringValue(payload.output);
+        const visibleFinalOutput = stripOpaqueCitationTokens(finalOutput).trim();
+        const visibleTrackedResponse = stripOpaqueCitationTokens(
+          latestAgentResponse?.item.text ?? "",
+        ).trim();
+        const finalOutputMirrorsCommentary =
+          latestAgentResponse?.item.phase === "commentary" &&
+          visibleTrackedResponse === visibleFinalOutput;
+        const hasAuthoritativeFinalOutput =
+          Boolean(visibleFinalOutput) && !finalOutputMirrorsCommentary;
+        const pendingWaitOutcome = takePendingWaitOutcome(turnId);
+        if (hasAuthoritativeFinalOutput) {
+          // The final message normally lands as its own completion before
+          // `turn.completed` (older workers commit a copy with it), but legacy or
+          // partially compacted ledgers may retain only the terminal output
+          // receipt. Keep that authoritative response visible instead of
+          // leaving it trapped in raw audit data.
+          if (
+            latestAgentResponse &&
+            !latestAgentResponse.completed &&
+            finalOutput.startsWith(latestAgentResponse.item.text)
+          ) {
+            latestAgentResponse.item.text = finalOutput;
+            latestAgentResponse.item.streaming = false;
+            if (
+              latestAgentResponse.item.startedAt === undefined &&
+              latestAgentResponse.item.occurredAt !== event.occurredAt
+            ) {
+              latestAgentResponse.item.startedAt = latestAgentResponse.item.occurredAt;
+            }
+            latestAgentResponse.item.occurredAt = event.occurredAt;
+            const responseIndex = items.indexOf(latestAgentResponse.item);
+            if (responseIndex >= 0 && responseIndex < items.length - 1) {
+              items.splice(responseIndex, 1);
+              items.push(latestAgentResponse.item);
+            }
+          } else if (visibleTrackedResponse !== visibleFinalOutput) {
+            items.push({
+              kind: "agent-message",
+              id: `${event.id}-output-message`,
+              turnId,
+              text: finalOutput,
+              streaming: false,
+              occurredAt: event.occurredAt,
+            });
+          }
+        }
+        finalizeOpen(turnId, "complete", event.occurredAt);
+        const completedTurn = turnEndItem(event, "complete", null);
+        items.push(completedTurn);
+        if (turnCompletedWithEmptyFinalReply(payload)) {
+          items.push({
+            kind: "notice",
+            id: `${event.id}-empty-final-reply`,
+            tone: "input",
+            text: EMPTY_FINAL_REPLY_NOTICE,
+            recordedOutcome: true,
+            occurredAt: event.occurredAt,
+          });
+        }
+        const hasCompletedFinalResponse =
+          latestAgentResponse?.completed === true &&
+          latestAgentResponse.item.phase !== "commentary" &&
+          Boolean(visibleTrackedResponse);
+        if (!hasAuthoritativeFinalOutput && pendingWaitOutcome) {
+          // Preserve existing prose, including delta-only streams, when a
+          // trailing wait yields without a terminal output receipt.
+          completedTurn.preserveWaitResponse = true;
+        }
+        if (!hasAuthoritativeFinalOutput && !hasCompletedFinalResponse && pendingWaitOutcome) {
+          const notice: NoticeItem = {
+            kind: "notice",
+            id: `${pendingWaitOutcome.id}-visible-outcome`,
+            tone: "waiting",
+            text: waitingOutcomeText(pendingWaitOutcome.reason),
+            recordedOutcome: true,
+            ...(pendingWorkerSessions.size > 0
+              ? { waitingAgents: pendingWorkerSessions.size }
+              : {}),
+            occurredAt: pendingWaitOutcome.occurredAt,
+          };
+          items.push(notice);
+          openWaitNotice = notice;
+        }
         break;
       }
 
       case "turn.failed": {
+        takeAgentResponse(turnId);
+        takePendingWaitOutcome(turnId);
         const hadActivity = hasTurnActivity(items, turnId);
         // Credit death can hide behind fields `failureMessage` doesn't read
         // (detail/segmentLimit), so classify the whole payload before falling
         // back to the generic error/message extraction.
-        const failureText = isCreditExhaustionPayload(payload)
-          ? CREDIT_EXHAUSTION_MESSAGE
-          : failureMessage(payload);
+        const allowance = parseAllowanceExhaustedRefusal(payload);
+        const failureText = allowance
+          ? ALLOWANCE_TURN_END_TEXT
+          : isCreditExhaustionPayload(payload)
+            ? CREDIT_EXHAUSTION_MESSAGE
+            : failureMessage(payload);
         // The TURN failed — the in-flight items did not. Chip doctrine: red is
         // spent once, on the turn-level outcome. Items caught mid-flight read
         // as calm "interrupted" (same as turn.cancelled); an item that itself
         // failed keeps its own failed status from its output event.
-        finalizeOpen(turnId, "cancelled");
+        finalizeOpen(turnId, "cancelled", event.occurredAt);
         items.push(turnEndItem(event, "failed", failureText));
-        if (!hadActivity) {
+        if (allowance) {
+          allowanceNotice(event, turnId);
+        } else if (!hadActivity) {
           items.push({
             kind: "notice",
             id: event.id,
@@ -752,15 +1432,18 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
         break;
       }
 
+      case "turn.superseded":
       case "turn.cancelled": {
         // A retraction of a never-started queued turn is not a turn ending —
         // the message was withdrawn before any work happened; show nothing.
         // A null turnId proves nothing, so it keeps the legacy finalize path.
-        if (turnId && !prescan.startedTurnIds.has(turnId)) {
+        if (event.type === "turn.cancelled" && turnId && !prescan.startedTurnIds.has(turnId)) {
           break;
         }
+        takeAgentResponse(turnId);
+        takePendingWaitOutcome(turnId);
         const hadActivity = hasTurnActivity(items, turnId);
-        finalizeOpen(turnId, "cancelled");
+        finalizeOpen(turnId, "cancelled", event.occurredAt);
         items.push(turnEndItem(event, "cancelled", null));
         if (!hadActivity) {
           items.push({
@@ -774,6 +1457,45 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
         break;
       }
 
+      case "instruction.confirmation.recovered": {
+        const receipt = asRecord(payload.receipt);
+        if (receipt.outcome !== "published") break;
+        closeStreamingTail();
+        items.push({
+          kind: "notice",
+          id: event.id,
+          tone: "input",
+          text: "Your previously approved workspace instruction was saved.",
+          occurredAt: event.occurredAt,
+        });
+        break;
+      }
+      case "knowledge.confirmation.recovered":
+      case "knowledge.source.prepared":
+      case "knowledge.source.failed": {
+        const receipt = asRecord(payload.receipt);
+        const outcome = event.type === "knowledge.source.failed" ? "failed" : receipt.outcome;
+        if (
+          (event.type !== "knowledge.confirmation.recovered" &&
+            typeof payload.fileId !== "string") ||
+          !["published", "pending", "rejected", "archived", "failed"].includes(String(outcome))
+        )
+          break;
+        closeStreamingTail();
+        items.push({
+          kind: "knowledge",
+          id: event.id,
+          turnId,
+          fileId: typeof payload.fileId === "string" ? payload.fileId : undefined,
+          filename: typeof payload.filename === "string" ? payload.filename : undefined,
+          entryId: typeof receipt.entryId === "string" ? receipt.entryId : undefined,
+          status: outcome === "failed" ? "failed" : "complete",
+          outcome: outcome as "published" | "pending" | "rejected" | "archived" | "failed",
+          occurredAt: event.occurredAt,
+        });
+        break;
+      }
+
       case "memory.saved":
       case "memory.corrected": {
         // A first-party memory write is a discrete step, not streamed text, so it
@@ -802,7 +1524,11 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
       case "goal.paused":
       case "goal.resumed":
       case "goal.cleared":
+      case "goal.held":
       case "goal.continuation": {
+        if (event.type === "goal.held" && payload.actor === "agent") {
+          rememberPendingWaitOutcome(pendingWaitOutcomeByTurn, event, payload, turnId);
+        }
         // Agent tool mutations already appear as tool-call rows in the activity
         // cluster. Re-emitting them as GoalRow landmarks splits "N steps" mid-turn.
         if (shouldSuppressAgentGoalLandmark(event.type, payload)) {
@@ -812,18 +1538,37 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
           kind: "goal",
           id: event.id,
           action: event.type.slice("goal.".length) as GoalItem["action"],
-          text: goalText(payload),
+          text:
+            event.type === "goal.held" && typeof payload.reason === "string" && payload.reason
+              ? payload.reason
+              : goalText(payload),
           occurredAt: event.occurredAt,
         });
         break;
       }
 
+      case "session.wait.started": {
+        if (payload.actor === "agent") {
+          rememberPendingWaitOutcome(pendingWaitOutcomeByTurn, event, payload, turnId);
+        }
+        break;
+      }
+
       default:
         break;
     }
   }
 
+  const sourceEventsById = new Map(events.map((event) => [event.id, event]));
   for (const item of items) {
+    const source = sourceEventsById.get(item.id);
+    const canonical = "annotationSource" in item ? item.annotationSource : undefined;
+    item.sourceEvents = [
+      ...(source ? [{ eventId: source.id, sequence: source.sequence }] : []),
+      ...(canonical && canonical.eventId !== source?.id
+        ? [{ eventId: canonical.eventId, sequence: canonical.sequence }]
+        : []),
+    ];
     if (item.kind === "agent-message") {
       item.text = stripOpaqueCitationTokens(item.text);
     }
@@ -849,6 +1594,134 @@ function realtimeVoiceMessage(payload: Record<string, unknown>): {
   return null;
 }
 
+function humanInputRequestsById(events: SessionEvent[]): Map<string, Record<string, unknown>> {
+  const requests = new Map<string, Record<string, unknown>>();
+  for (const event of events) {
+    if (event.type !== "session.humanInput.requested") continue;
+    const request = asRecord(asRecord(event.payload).request);
+    const requestId = stringValue(request.id);
+    if (requestId) requests.set(requestId, request);
+  }
+  return requests;
+}
+
+function humanInputItemFromResponse(
+  event: SessionEvent,
+  payload: Record<string, unknown>,
+  requests: Map<string, Record<string, unknown>>,
+): HumanInputItem | null {
+  const response = asRecord(payload.response);
+  const outcome = response.outcome;
+  if (
+    outcome !== "answered" &&
+    outcome !== "skipped" &&
+    outcome !== "expired" &&
+    outcome !== "cancelled"
+  ) {
+    return null;
+  }
+
+  const requestId = stringValue(payload.requestId);
+  const request = requests.get(requestId);
+  const questions = humanInputQuestions(request?.questions);
+  const normalizedResponse: HumanInputResponse =
+    outcome === "answered"
+      ? {
+          outcome,
+          answers: Array.isArray(response.answers)
+            ? response.answers
+                .map(asRecord)
+                .map(humanInputAnswer)
+                .filter((answer): answer is HumanInputAnswer => answer !== null)
+            : [],
+        }
+      : { outcome };
+  const questionsById = new Map(questions.map((question) => [question.id, question]));
+  const answers =
+    normalizedResponse.outcome === "answered"
+      ? normalizedResponse.answers.map((answer) =>
+          humanInputAnswerSummary(answer, questionsById.get(answer.questionId)),
+        )
+      : [];
+  return {
+    kind: "human-input",
+    id: event.id,
+    turnId: event.turnId ?? null,
+    requestId,
+    questions,
+    response: normalizedResponse,
+    answers,
+    occurredAt: event.occurredAt,
+  };
+}
+
+function humanInputQuestions(value: unknown): HumanInputQuestion[] {
+  if (!Array.isArray(value)) return [];
+  return value.map(asRecord).flatMap((question) => {
+    const id = stringValue(question.id);
+    const prompt = stringValue(question.prompt);
+    const kind = question.kind;
+    if (
+      !id ||
+      !prompt ||
+      (kind !== "text" && kind !== "single_select" && kind !== "multi_select")
+    ) {
+      return [];
+    }
+    const options = Array.isArray(question.options)
+      ? question.options.map(asRecord).flatMap((option) => {
+          const optionId = stringValue(option.id);
+          const label = stringValue(option.label);
+          return optionId && label
+            ? [{ id: optionId, label, description: stringValue(option.description) || null }]
+            : [];
+        })
+      : [];
+    return [
+      {
+        id,
+        kind,
+        prompt,
+        label: stringValue(question.label) || null,
+        helpText: stringValue(question.helpText) || null,
+        options,
+        required: question.required === true,
+        allowOther: question.allowOther === true,
+      },
+    ];
+  });
+}
+
+function humanInputAnswer(value: Record<string, unknown>): HumanInputAnswer | null {
+  const questionId = stringValue(value.questionId);
+  if (!questionId) return null;
+  return {
+    questionId,
+    values: Array.isArray(value.values)
+      ? value.values.filter((answer): answer is string => typeof answer === "string")
+      : [],
+    ...(typeof value.other === "string" && value.other ? { other: value.other } : {}),
+  };
+}
+
+function humanInputAnswerSummary(
+  answer: HumanInputAnswer,
+  question: HumanInputQuestion | undefined,
+): HumanInputAnswerSummary {
+  const optionLabels = new Map(question?.options.map((option) => [option.id, option.label]) ?? []);
+  const values = answer.values.map((value) => optionLabels.get(value) || value);
+  if (answer.other) values.push(answer.other);
+  const fallbackLabel = answer.questionId
+    .replace(/[_-]+/g, " ")
+    .replace(/\b\w/g, (character) => character.toUpperCase());
+  return {
+    questionId: answer.questionId,
+    label: question?.label || question?.prompt || fallbackLabel,
+    prompt: question?.prompt || fallbackLabel,
+    values,
+  };
+}
+
 function providerNativeToolStatus(rawValue: unknown): ToolCallItem["status"] {
   const raw = asRecord(rawValue);
   if (raw.type !== "hosted_tool_call") {
@@ -909,8 +1782,16 @@ export function stripOpaqueCitationTokens(text: string): string {
   return text.replace(/\s*cite(?:[^]+)+/gu, "");
 }
 
+/**
+ * The turn summary's short outcome for a usage ceiling. The adjacent notice row
+ * carries who can raise it and when it resets (and is host-customizable), so
+ * the summary line stays a neutral fact instead of repeating remedy prose.
+ */
+const ALLOWANCE_TURN_END_TEXT = "Usage limit reached";
+
 /** The turn-end payload shape, as `isCreditExhaustion` wants it. */
 function isCreditExhaustionPayload(payload: Record<string, unknown>): boolean {
+  if (payload.code === "allowance_exhausted") return false;
   return isCreditExhaustion({
     error: typeof payload.error === "string" ? payload.error : null,
     detail: typeof payload.detail === "string" ? payload.detail : null,
@@ -961,18 +1842,24 @@ export function sessionStatusFromEvents(events: SessionEvent[]): SessionStatus |
    non-user span folds behind a turn group, with activity blocks nested inside.
    -------------------------------------------------------------------------- */
 
+/** Work items: every activity kind except assistant commentary. */
+type WorkActivityItem = Exclude<ActivityItem, AgentMessageItem>;
+
 /**
  * Whether an item clusters into an activity block. A `switch` (not a stringly-
  * typed set) so adding an {@link ActivityItem} kind is a compile-time prompt to
- * decide its grouping — and it narrows `item` to `ActivityItem` with no cast.
+ * decide its grouping, and it narrows `item` to a work item with no cast.
+ * Assistant prose stays outside activity clusters.
  */
-function isActivityItem(item: TimelineItem): item is ActivityItem {
+function isActivityItem(item: TimelineItem): item is WorkActivityItem {
   switch (item.kind) {
     case "reasoning":
     case "tool-call":
     case "worker":
     case "sandbox":
+    case "startup-phase":
     case "memory":
+    case "knowledge":
     case "fleet-decision":
       return true;
     default:
@@ -980,7 +1867,18 @@ function isActivityItem(item: TimelineItem): item is ActivityItem {
   }
 }
 
-export function groupTimeline(items: TimelineItem[]): TimelineGroup[] {
+export type GroupTimelineOptions = {
+  /** Readable assistant prose with an independent work summary for each turn. */
+  readableTurns?: boolean;
+  /** @deprecated Use readableTurns. Cross-turn exchange folding has been removed. */
+  foldExchanges?: boolean;
+};
+
+export function groupTimeline(
+  items: TimelineItem[],
+  options: GroupTimelineOptions = {},
+): TimelineGroup[] {
+  if (options.readableTurns || options.foldExchanges) return groupReadableTurns(items);
   const groups: TimelineGroup[] = [];
   for (const item of items) {
     if (isActivityItem(item)) {
@@ -1006,32 +1904,429 @@ export function groupTimeline(items: TimelineItem[]): TimelineGroup[] {
   return groups;
 }
 
+/** Live prose stays primary; settled progress joins its own turn's work history. */
+function groupReadableTurns(items: TimelineItem[]): TimelineGroup[] {
+  type Work = Extract<TimelineGroup, { kind: "activity" }>;
+  let groups: TimelineGroup[] = [];
+  const turns = new Map<string, Work>();
+  // Turn identity and settlement exist even when a final-only turn has no
+  // disclosure. A late receipt must not become a new turn or revive its clock.
+  const seenTurns = new Set<string>();
+  const settlements = new Map<
+    string,
+    { endedAt: string; outcome?: Work["outcome"]; failureText?: string }
+  >();
+  const compactionTurns = new Map<ContextCompactionItem, string>();
+  const messages = new Map<string, AgentMessageItem[]>();
+  const inputs = new Map<string, Extract<TimelineItem, { kind: "machine-input-batch" }>>();
+  const itemOrder = new Map(items.map((item, index) => [item.id, index]));
+  let legacyTurn = "start";
+  let currentTurn = legacyTurn;
+  for (const item of items) {
+    if (item.kind === "user-message") legacyTurn = item.id;
+    const key = ("turnId" in item && item.turnId) || legacyTurn;
+    // Legacy work still establishes a boundary using its prompt key.
+    // A human message alone does not: it may be steering the existing turn.
+    if (
+      ("turnId" in item && item.turnId) ||
+      isActivityItem(item) ||
+      (item.kind === "agent-message" && item.text.trim())
+    ) {
+      if (key !== currentTurn && !seenTurns.has(key)) {
+        const previous = turns.get(currentTurn);
+        if (!settlements.has(currentTurn)) {
+          settlements.set(currentTurn, { endedAt: item.occurredAt });
+        }
+        if (previous?.work && !previous.work.endedAt) previous.work.endedAt = item.occurredAt;
+        currentTurn = key;
+      }
+      seenTurns.add(key);
+    }
+    const workForTurn = () => {
+      let group = turns.get(key);
+      const firstMessage = messages.get(key)?.[0];
+      const messageStart = firstMessage?.startedAt ?? firstMessage?.occurredAt;
+      const startedAt =
+        messageStart && Date.parse(messageStart) < Date.parse(item.occurredAt)
+          ? messageStart
+          : item.occurredAt;
+      if (!group) {
+        const settlement = settlements.get(key);
+        group = {
+          kind: "activity",
+          id: `work-${key}`,
+          items: [],
+          work: { startedAt, details: [] },
+        };
+        if (settlement) {
+          group.work!.endedAt = settlement.endedAt;
+          if (settlement.outcome) group.outcome = settlement.outcome;
+          if (settlement.failureText) group.failureText = settlement.failureText;
+        }
+        turns.set(key, group);
+        const firstMessageIndex =
+          settlement && firstMessage
+            ? groups.findIndex((entry) => entry.kind === "item" && entry.item === firstMessage)
+            : -1;
+        if (firstMessageIndex >= 0) groups.splice(firstMessageIndex, 0, group);
+        else groups.push(group);
+      } else if (Date.parse(startedAt) < Date.parse(group.work!.startedAt)) {
+        // Completion-only startup receipts can reveal an earlier phase start
+        // after another activity has already established the work row.
+        group.work!.startedAt = startedAt;
+      }
+      return group;
+    };
+    if (isActivityItem(item)) {
+      const group = workForTurn();
+      group.items.push(item);
+      const previous = group.work!.details.at(-1);
+      const preparing = (entry: ActivityItem) =>
+        entry.kind === "startup-phase" || (entry.kind === "reasoning" && !entry.text.trim());
+      if (
+        preparing(item) &&
+        previous?.kind === "activity" &&
+        previous.items.every(preparing) &&
+        previous.items.at(-1) === items[(itemOrder.get(item.id) ?? 0) - 1]
+      )
+        previous.items.push(item);
+      else
+        group.work!.details.push({ kind: "activity", id: `work-item-${item.id}`, items: [item] });
+      delete group.work!.waiting;
+    } else if (item.kind === "turn-end") {
+      if (!item.resumedAt) {
+        settlements.set(key, {
+          endedAt: item.occurredAt,
+          outcome: item.outcome,
+          ...(item.failureText ? { failureText: item.failureText } : {}),
+        });
+      }
+      const group = turns.get(key);
+      if (group?.work) {
+        if (item.resumedAt) {
+          group.work.details.push({
+            kind: "item",
+            item: {
+              kind: "notice",
+              id: item.id,
+              tone: "failed",
+              text: item.failureText ?? "The turn failed before retrying.",
+              occurredAt: item.occurredAt,
+            },
+          });
+          continue;
+        }
+        group.outcome = item.outcome;
+        if (item.failureText) group.failureText = item.failureText;
+        group.work.endedAt = item.occurredAt;
+      }
+    } else if (item.kind === "context-compaction" && item.phase === "compacted") {
+      // A maintenance checkpoint alone is not conversational work. Resolve its
+      // attachment after real activity has established this turn's work row.
+      compactionTurns.set(item, key);
+      groups.push({ kind: "item", item });
+    } else if (
+      item.kind === "machine-input-batch" &&
+      item.members.every((member) => ROUTINE_MACHINE_INPUT_KINDS.has(member.kind))
+    ) {
+      const previous = inputs.get(key);
+      if (previous) {
+        previous.members.push(
+          ...item.members.filter((member) => !previous.members.some((old) => old.id === member.id)),
+        );
+        previous.sourceEvents = [...(previous.sourceEvents ?? []), ...(item.sourceEvents ?? [])];
+      } else {
+        const batch = { ...item, compact: true, members: [...item.members] };
+        inputs.set(key, batch);
+        groups.push({ kind: "item", item: batch });
+      }
+    } else if (
+      item.kind === "worker-completion" ||
+      (item.kind === "goal" && item.action === "continuation")
+    ) {
+      const group = turns.get(currentTurn);
+      if (group?.work) group.work.details.push({ kind: "item", item });
+      else groups.push({ kind: "item", item });
+    } else {
+      const current = turns.get(currentTurn)?.work;
+      // A live approval wait is carried by the turn header ("Waiting for you")
+      // and decided in the host's approval surface; a second in-timeline banner
+      // only repeats it. Once resolved it returns as the quiet recorded marker.
+      const liveApprovalWait =
+        item.kind === "notice" &&
+        item.tone === "waiting" &&
+        !item.recordedOutcome &&
+        !item.resolvedAt &&
+        item.text.startsWith("Approval needed") &&
+        current !== undefined &&
+        !current.endedAt;
+      // Likewise the live "waiting on you" divider: the open turn's header
+      // already reads "Waiting for you · <elapsed>". It returns, resolved, as
+      // the "work resumed" divider once the session runs again.
+      const liveStatusWait =
+        item.kind === "session-status" &&
+        item.status === "requires_action" &&
+        !item.resolvedAt &&
+        current !== undefined &&
+        !current.endedAt;
+      if (!liveApprovalWait && !liveStatusWait) groups.push({ kind: "item", item });
+      if (current && !current.endedAt) {
+        if (
+          item.kind === "notice" &&
+          item.tone === "waiting" &&
+          !item.recordedOutcome &&
+          !item.resolvedAt
+        ) {
+          current.waiting = {
+            label: item.text.startsWith("Approval needed") ? "Waiting for you" : "Waiting",
+            since: item.occurredAt,
+          };
+        } else if (
+          item.kind === "session-status" &&
+          item.status === "requires_action" &&
+          !item.resolvedAt
+        ) {
+          current.waiting = { label: "Waiting for you", since: item.occurredAt };
+        } else if (
+          item.kind === "session-status" &&
+          ["paused", "cancelled", "failed"].includes(item.status) &&
+          !item.resolvedAt
+        ) {
+          current.endedAt = item.occurredAt;
+          delete current.waiting;
+        }
+      }
+      if (item.kind === "agent-message" && item.text.trim()) {
+        const prose = messages.get(key) ?? [];
+        prose.push(item);
+        messages.set(key, prose);
+        // A text-only turn still has one overall activity surface. An explicit
+        // final-only response does not manufacture an empty work disclosure.
+        if (
+          (item.phase !== "final_answer" || prose.length > 1) &&
+          (turns.has(key) || !settlements.has(key))
+        )
+          workForTurn();
+      }
+    }
+  }
+  groups = groups.filter((entry) => {
+    if (entry.kind !== "item" || entry.item.kind !== "context-compaction") return true;
+    const key = compactionTurns.get(entry.item);
+    const work = key === undefined ? undefined : turns.get(key)?.work;
+    if (!work) return true;
+    work.details.push(entry);
+    return false;
+  });
+  // A declared answer starts the response clock immediately. Without a phase,
+  // only settlement identifies the last response; text length never does.
+  const beforeRows = new Map<TimelineGroup, Work>();
+  const afterRows = new Map<TimelineGroup, Work>();
+  const movedRows = new Set<Work>();
+  const foldedProse = new Set<AgentMessageItem>();
+  const positions = new Map<TimelineGroup | TimelineItem, number>();
+  const nextBoundary = new Map<Work, number>();
+  let boundary = groups.length;
+  for (let index = groups.length - 1; index >= 0; index -= 1) {
+    const entry = groups[index]!;
+    positions.set(entry.kind === "item" ? entry.item : entry, index);
+    if (entry.kind === "activity" && entry.work) {
+      nextBoundary.set(entry, boundary);
+      boundary = index;
+    } else if (
+      entry.kind === "item" &&
+      (entry.item.kind === "user-message" || entry.item.kind === "machine-input-batch")
+    ) {
+      boundary = index;
+    }
+  }
+  for (const [key, group] of turns) {
+    const prose = messages.get(key) ?? [];
+    const settledAt = group.work!.endedAt;
+    const responseCandidates = settledAt
+      ? prose.filter(
+          (message) => Date.parse(message.startedAt ?? message.occurredAt) <= Date.parse(settledAt),
+        )
+      : prose;
+    const response =
+      responseCandidates.filter((message) => message.phase === "final_answer").at(-1) ??
+      (settledAt
+        ? (responseCandidates.at(-1) ??
+          prose.filter((message) => message.phase === "final_answer").at(-1))
+        : undefined);
+    if (settledAt) {
+      for (const message of responseCandidates) {
+        // Markdown image syntax also carries retained video/audio previews.
+        // Keep potential primary media visible rather than guessing whether a
+        // partial/reference-style embed can safely disappear into history.
+        if (message === response || message.text.includes("![")) continue;
+        foldedProse.add(message);
+        group.work!.details.push({ kind: "item", item: message });
+      }
+    }
+    // Preserve event chronology, not completion timestamps or activity kinds.
+    group.work!.details.sort((a, b) => {
+      const first = (entry: TimelineGroup) =>
+        entry.kind === "item"
+          ? entry.item.id
+          : entry.kind === "activity"
+            ? entry.items[0]?.id
+            : undefined;
+      return (itemOrder.get(first(a) ?? "") ?? 0) - (itemOrder.get(first(b) ?? "") ?? 0);
+    });
+    if (response) {
+      const responseAt = response.startedAt ?? response.occurredAt;
+      // A delayed completion-only receipt cannot extend a settled work clock.
+      group.work!.responseStartedAt =
+        settledAt && Date.parse(responseAt) > Date.parse(settledAt) ? settledAt : responseAt;
+      // A late completion may belong to an older turn. Keep its work at its
+      // original boundary rather than moving it across a newer turn's input.
+      if (
+        settledAt &&
+        (positions.get(response) ?? groups.length) < (nextBoundary.get(group) ?? groups.length)
+      ) {
+        beforeRows.set(groups[positions.get(response)!]!, group);
+        movedRows.add(group);
+      }
+    }
+    if (!settledAt) {
+      // Keep the same row at the tail of this turn, after every live progress
+      // message and attention surface, without crossing a newer input/turn.
+      // A visible steer is not a turn boundary when later prose still belongs
+      // to this turn. New input without that evidence remains a hard boundary.
+      const lastProseIndex = Math.max(...prose.map((message) => positions.get(message) ?? -1));
+      let tailIndex = groups.length - 1;
+      for (let index = (positions.get(group) ?? 0) + 1; index <= tailIndex; index += 1) {
+        const entry = groups[index]!;
+        if (
+          (entry.kind === "activity" && entry.work) ||
+          (entry.kind === "item" &&
+            (("turnId" in entry.item && entry.item.turnId && entry.item.turnId !== key) ||
+              (index > lastProseIndex &&
+                (entry.item.kind === "user-message" || entry.item.kind === "machine-input-batch"))))
+        ) {
+          tailIndex = index - 1;
+          break;
+        }
+      }
+      const tail = groups[tailIndex];
+      if (tail && tail !== group) {
+        afterRows.set(tail, group);
+        movedRows.add(group);
+      }
+    }
+  }
+  return groups.flatMap((group) => {
+    if (group.kind === "activity" && movedRows.has(group)) return [];
+    const hidden =
+      group.kind === "item" && group.item.kind === "agent-message" && foldedProse.has(group.item);
+    const before = beforeRows.get(group);
+    const after = afterRows.get(group);
+    return [...(before ? [before] : []), ...(hidden ? [] : [group]), ...(after ? [after] : [])];
+  });
+}
+
+/** Machine inputs that continue the current exchange rather than start one. */
+const ROUTINE_MACHINE_INPUT_KINDS: ReadonlySet<MachineInputMember["kind"]> = new Set([
+  "goal_continuation",
+  "background_command_result",
+  "session_wait_timeout",
+  "agent_message",
+  "agent_steer_instruction",
+  "child_terminal_result",
+  "child_requires_action_resolved",
+  "child_paused",
+  "child_waiting_capacity",
+  "child_progress",
+]);
+
 /* --- helpers ---------------------------------------------------------------- */
 
 type TurnAnchorPrescan = {
   queuedTurnByTrigger: Map<string, string>;
   startSeqByTrigger: Map<string, number>;
   cancelledBeforeStartTriggers: Set<string>;
+  directChatSequenceByTrigger: Map<string, number>;
+  explicitQueuedTriggers: Set<string>;
   startedTurnIds: Set<string>;
 };
 
+/** Navigation uses the same queue/start/withdrawal rules as transcript ordering. */
+export function timelineQuestionPlacement(question: SessionEvent, evidence: SessionEvent[]) {
+  const anchors = prescanTurnAnchors([question, ...evidence]);
+  const direct = anchors.directChatSequenceByTrigger.get(question.id);
+  if (direct !== undefined) return { kind: "visible" as const, sequence: direct };
+  if (anchors.cancelledBeforeStartTriggers.has(question.id)) return { kind: "withdrawn" as const };
+  const start = anchors.startSeqByTrigger.get(question.id);
+  if (start !== undefined) return { kind: "visible" as const, sequence: start };
+  if (
+    anchors.queuedTurnByTrigger.has(question.id) ||
+    anchors.explicitQueuedTriggers.has(question.id)
+  )
+    return { kind: "pending" as const };
+  return { kind: "visible" as const, sequence: question.sequence };
+}
+
 function prescanTurnAnchors(events: SessionEvent[]): TurnAnchorPrescan {
   const ordered = [...events].sort((a, b) => a.sequence - b.sequence);
   const queuedTurnByTrigger = new Map<string, string>();
   const startSeqByTrigger = new Map<string, number>();
   const cancelledTurnIds = new Set<string>();
+  const withdrawnTurnIds = new Set<string>();
   const fallbackSeqByTurn = new Map<string, number>();
+  const directChatSequenceByTrigger = new Map<string, number>();
+  const explicitQueuedTriggers = new Set<string>();
+  const queueSteerSequenceByTurn = new Map<string, number>();
   const startedTurnIds = new Set<string>();
+  const userMessageSequenceById = new Map<string, number>();
 
   for (const event of ordered) {
     const payload = asRecord(event.payload);
     const turnId = event.turnId ?? null;
+    if (event.type === "user.message") {
+      userMessageSequenceById.set(event.id, event.sequence);
+      if (payload.routing === "queued_for_execution") {
+        explicitQueuedTriggers.add(event.id);
+      } else if (
+        payload.routing === "accepted_for_execution" ||
+        payload.routing === "accepted_for_steering"
+      ) {
+        directChatSequenceByTrigger.set(event.id, event.sequence);
+      }
+    }
+    if (event.type === "user.message" && payload.delivery === "steer") {
+      directChatSequenceByTrigger.set(event.id, event.sequence);
+    }
+    if (event.type === "session.control.steer_requested") {
+      const targetTurnId = typeof payload.targetTurnId === "string" ? payload.targetTurnId : null;
+      if (targetTurnId && !queueSteerSequenceByTurn.has(targetTurnId)) {
+        queueSteerSequenceByTurn.set(targetTurnId, event.sequence);
+      }
+    }
+    if (
+      event.type === "session.queue.changed" &&
+      (payload.operation === "edit" || payload.operation === "delete")
+    ) {
+      const withdrawnTurnId =
+        typeof payload.turnId === "string" ? payload.turnId : (turnId ?? null);
+      if (withdrawnTurnId) withdrawnTurnIds.add(withdrawnTurnId);
+    }
     if (event.type === "turn.queued") {
       const triggerEventId =
         typeof payload.triggerEventId === "string" ? payload.triggerEventId : null;
       const queuedTurnId = typeof payload.turnId === "string" ? payload.turnId : turnId;
       if (triggerEventId && queuedTurnId) {
         queuedTurnByTrigger.set(triggerEventId, queuedTurnId);
+        if (
+          (payload.routing === "accepted_for_execution" ||
+            payload.routing === "accepted_for_steering") &&
+          !directChatSequenceByTrigger.has(triggerEventId)
+        ) {
+          directChatSequenceByTrigger.set(
+            triggerEventId,
+            userMessageSequenceById.get(triggerEventId) ?? event.sequence,
+          );
+        }
       }
       continue;
     }
@@ -1060,6 +2355,10 @@ function prescanTurnAnchors(events: SessionEvent[]): TurnAnchorPrescan {
   }
 
   for (const [triggerEventId, turnId] of queuedTurnByTrigger) {
+    const queueSteerSequence = queueSteerSequenceByTurn.get(turnId);
+    if (queueSteerSequence !== undefined) {
+      directChatSequenceByTrigger.set(triggerEventId, queueSteerSequence);
+    }
     if (!startSeqByTrigger.has(triggerEventId)) {
       const fallbackSeq = fallbackSeqByTurn.get(turnId);
       if (fallbackSeq !== undefined) {
@@ -1071,7 +2370,7 @@ function prescanTurnAnchors(events: SessionEvent[]): TurnAnchorPrescan {
   const cancelledBeforeStartTriggers = new Set<string>();
   for (const [triggerEventId, turnId] of queuedTurnByTrigger) {
     if (
-      cancelledTurnIds.has(turnId) &&
+      (cancelledTurnIds.has(turnId) || withdrawnTurnIds.has(turnId)) &&
       !startSeqByTrigger.has(triggerEventId) &&
       !fallbackSeqByTurn.has(turnId)
     ) {
@@ -1083,6 +2382,8 @@ function prescanTurnAnchors(events: SessionEvent[]): TurnAnchorPrescan {
     queuedTurnByTrigger,
     startSeqByTrigger,
     cancelledBeforeStartTriggers,
+    directChatSequenceByTrigger,
+    explicitQueuedTriggers,
     startedTurnIds,
   };
 }
@@ -1095,8 +2396,22 @@ function orderTimelineEvents(events: SessionEvent[], prescan: TurnAnchorPrescan)
     if (event.type !== "user.message") {
       continue;
     }
+    // Steer is an accepted direction change, not waiting queue copy. Keep it
+    // directly in chat across refresh/reconnect even before its turn starts.
+    const directChatSequence = prescan.directChatSequenceByTrigger.get(event.id);
+    if (directChatSequence !== undefined) {
+      pushInsertion(insertions, directChatSequence, event);
+      continue;
+    }
     const queuedTurnId = prescan.queuedTurnByTrigger.get(event.id);
     if (!queuedTurnId) {
+      if (prescan.explicitQueuedTriggers.has(event.id)) {
+        const startSeq = prescan.startSeqByTrigger.get(event.id);
+        if (startSeq !== undefined) {
+          pushInsertion(insertions, startSeq, event);
+        }
+        continue;
+      }
       pushInsertion(insertions, event.sequence, event);
       continue;
     }
@@ -1150,16 +2465,21 @@ function isAgentActivityEvent(type: string): boolean {
  * steering, or deleting a waiting row must never make its prompt appear in the
  * transcript as though inference had begun.
  */
-function isTurnExecutionEvidence(type: string): boolean {
+export function isTurnExecutionEvidence(type: string): boolean {
   return (
     isAgentActivityEvent(type) ||
     type === "turn.completed" ||
     type === "turn.failed" ||
+    // An admission refusal can settle a queued turn before it ever starts:
+    // its prompt still belongs above the "usage limit reached" row.
+    type === "usage.exhausted" ||
+    type === "turn.superseded" ||
     type === "turn.recovery.requested" ||
     type === "turn.capacity_waiting" ||
     type === "session.requiresAction" ||
     type === "tool.auth_needed" ||
     type === "credential.auth_needed" ||
+    type.startsWith("turn.startup.phase.") ||
     type.startsWith("rig.setup.") ||
     type === "codex.capacity.waiting" ||
     type === "codex.capacity.resumed" ||
@@ -1263,9 +2583,39 @@ function foldSettledTurn(groups: TimelineGroup[], turnEnd: TurnEndItem): void {
   if (collected.length === 0) {
     return;
   }
-
-  const finalMessage = extractFinalAgentMessage(collected, turnEnd);
-  const body = finalMessage ? collected.slice(0, -1) : collected;
+  const collectedLength = collected.length;
+
+  // Resolve only inside this turn's collected suffix. A user/machine-input
+  // boundary or an interleaved foreign turn must never donate its answer.
+  const waitMessages = turnEnd.preserveWaitResponse
+    ? collected.filter(
+        (group): group is Extract<TimelineGroup, { kind: "item" }> =>
+          group.kind === "item" &&
+          group.item.kind === "agent-message" &&
+          !group.item.streaming &&
+          group.item.text.trim().length > 0 &&
+          belongsToTurn(group.item, turnEnd.turnId),
+      )
+    : [];
+  // A completed answer outranks later commentary. Otherwise use the latest
+  // visible existing prose, ignoring whitespace and opaque-only stream tails.
+  const waitResponse =
+    waitMessages
+      .slice()
+      .reverse()
+      .find(
+        (group) =>
+          group.item.kind === "agent-message" &&
+          group.item.phase !== "commentary" &&
+          group.item.annotationSource?.eventType === "agent.message.completed",
+      ) ?? waitMessages.at(-1);
+  const finalMessage = waitResponse ?? extractFinalAgentMessage(collected, turnEnd);
+  const fallbackMessage =
+    finalMessage || hasOrdinaryFinalAgentMessage(collected, turnEnd)
+      ? null
+      : extractLatestCompletedCommentary(collected, turnEnd);
+  const visibleMessage = finalMessage ?? fallbackMessage;
+  const body = visibleMessage ? collected.filter((group) => group !== visibleMessage) : collected;
   if (body.length === 0) {
     return;
   }
@@ -1293,8 +2643,8 @@ function foldSettledTurn(groups: TimelineGroup[], turnEnd: TurnEndItem): void {
 
   groups.splice(
     startIndex,
-    collected.length,
-    ...(finalMessage ? [turnGroup, finalMessage] : [turnGroup]),
+    collectedLength,
+    ...(visibleMessage ? [turnGroup, visibleMessage] : [turnGroup]),
   );
 }
 
@@ -1303,9 +2653,9 @@ function isTurnBoundary(group: TimelineGroup | undefined): boolean {
     group?.kind === "turn" ||
     (group?.kind === "item" &&
       (group.item.kind === "user-message" ||
+        group.item.kind === "human-input" ||
         group.item.kind === "context-compaction" ||
-        (group.item.kind === "machine-input-batch" &&
-          group.item.members.some((member) => member.kind === "media_generation_result")) ||
+        group.item.kind === "machine-input-batch" ||
         (group.item.kind === "notice" && group.item.tone === "input")))
   );
 }
@@ -1350,6 +2700,43 @@ function extractFinalAgentMessage(
   return tail;
 }
 
+function hasOrdinaryFinalAgentMessage(groups: TimelineGroup[], turnEnd: TurnEndItem): boolean {
+  return groups.some((group) => {
+    if (group.kind !== "item" || group.item.kind !== "agent-message") return false;
+    const message = group.item;
+    return (
+      !message.streaming &&
+      message.phase !== "commentary" &&
+      message.text.trim().length > 0 &&
+      belongsToTurn(message, turnEnd.turnId)
+    );
+  });
+}
+
+function extractLatestCompletedCommentary(
+  groups: TimelineGroup[],
+  turnEnd: TurnEndItem,
+): Extract<TimelineGroup, { kind: "item" }> | null {
+  for (let index = groups.length - 1; index >= 0; index -= 1) {
+    const group = groups[index];
+    if (group?.kind !== "item" || group.item.kind !== "agent-message") continue;
+    const message = group.item;
+    if (
+      !message.streaming &&
+      message.phase === "commentary" &&
+      message.text.trim().length > 0 &&
+      belongsToTurn(message, turnEnd.turnId)
+    ) {
+      return group;
+    }
+  }
+  return null;
+}
+
+function belongsToTurn(message: AgentMessageItem, turnId: string | null): boolean {
+  return !message.turnId || !turnId || message.turnId === turnId;
+}
+
 function groupStartedAt(group: TimelineGroup | undefined): string | undefined {
   if (!group) {
     return undefined;
@@ -1372,10 +2759,37 @@ function stringValue(value: unknown): string {
   return typeof value === "string" ? value : "";
 }
 
+function assistantMessagePhase(value: unknown): AgentMessageItem["phase"] {
+  return value === "commentary" || value === "final_answer" ? value : undefined;
+}
+
 function numberOrNull(value: unknown): number | null {
   return typeof value === "number" && Number.isFinite(value) ? value : null;
 }
 
+/**
+ * Read the closed provider-rejection record a `summarization_failed` skip
+ * carries. Only bounded identifiers are accepted; a provider message is never
+ * part of the payload and would be ignored here anyway.
+ */
+function compactionProviderRejection(
+  payload: Record<string, unknown>,
+): ContextCompactionItem["providerRejection"] {
+  const record = asRecord(payload.providerRejection);
+  if (typeof record.httpStatus !== "number" || !Number.isFinite(record.httpStatus)) {
+    return null;
+  }
+  const text = (value: unknown): string | null =>
+    typeof value === "string" && value.trim() ? value : null;
+  return {
+    httpStatus: record.httpStatus,
+    type: text(record.type),
+    code: text(record.code),
+    param: text(record.param),
+    requestId: text(record.requestId),
+  };
+}
+
 function compactionTrigger(payload: Record<string, unknown>): ContextCompactionItem["trigger"] {
   const trigger = payload.trigger;
   return trigger === "auto" ||
@@ -1431,10 +2845,17 @@ function machineInputMembers(value: unknown): MachineInputBatchItem["members"] {
   const kinds = new Set<MachineInputBatchItem["members"][number]["kind"]>([
     "scheduled_occurrence",
     "goal_continuation",
+    "background_command_result",
+    "session_wait_timeout",
     "agent_message",
     "agent_steer_instruction",
     "child_terminal_result",
     "media_generation_result",
+    "child_requires_action",
+    "child_requires_action_resolved",
+    "child_paused",
+    "child_waiting_capacity",
+    "child_progress",
   ]);
   const classifications = new Set<MachineInputBatchItem["members"][number]["classification"]>([
     "success",
@@ -1481,6 +2902,8 @@ const SESSION_STATUSES: readonly SessionStatus[] = [
   "running",
   "idle",
   "requires_action",
+  "recovering",
+  "waiting_capacity",
   "failed",
   "cancelled",
 ];
@@ -1624,6 +3047,10 @@ function findOpenCall(
     if (byId) {
       return byId as ToolCallItem | WorkerItem;
     }
+    // An explicit provider correlation id is authoritative. Falling back to
+    // an unrelated running call corrupts its status/output when compact pages
+    // or interleaved providers deliver an unmatched historical result.
+    return undefined;
   }
   return reversed.find(
     (item): item is ToolCallItem | WorkerItem => isCall(item) && item.status === "running",
@@ -1639,16 +3066,58 @@ function findOpenSandbox(items: TimelineItem[], name: string): SandboxItem | und
     );
 }
 
-function failureMessage(payload: Record<string, unknown>): string | null {
-  for (const key of ["error", "message"] as const) {
-    const value = payload[key];
-    if (typeof value === "string" && value.trim().length > 0) {
-      // Auth/quota provider errors are rewritten for the right audience
-      // (raw text remains in the event payload for debug surfaces).
-      return humanizeFailureReason(value);
-    }
+function startupPhaseForSandboxOperation(name: string): StartupPhase | null {
+  return SANDBOX_STARTUP_PHASES[name] ?? null;
+}
+
+function startupPhaseFromPayload(value: unknown): StartupPhase | null {
+  return typeof value === "string" && STARTUP_PHASES.has(value as StartupPhase)
+    ? (value as StartupPhase)
+    : null;
+}
+
+function startupLifecycleWaitReason(
+  payload: Record<string, unknown>,
+): StartupPhaseItem["blockedReason"] {
+  if (
+    payload.expectedTransition !== true ||
+    payload.failureStage !== "lifecycle_wait" ||
+    payload.failureCategory !== "drain_capture_wait"
+  ) {
+    return undefined;
   }
-  return null;
+  const code = payload.failureCode;
+  return code === "capture_in_progress" ||
+    code === "rotation_in_progress" ||
+    code === "provider_recovery_in_progress"
+    ? code
+    : undefined;
+}
+
+const SANDBOX_STARTUP_PHASES: Record<string, StartupPhase> = {
+  "sandbox.provision": "sandbox",
+  "repository-clone": "repository",
+  "file-resource-download": "files",
+};
+const STARTUP_PHASES = new Set<StartupPhase>([
+  "queue",
+  "sandbox",
+  "rig",
+  "repository",
+  "files",
+  "tools",
+  "model_preparation",
+  "provider_first_byte",
+]);
+
+function elapsedDurationMs(startedAt: string, completedAt: string): number | null {
+  const start = Date.parse(startedAt);
+  const end = Date.parse(completedAt);
+  return Number.isFinite(start) && Number.isFinite(end) ? Math.max(0, end - start) : null;
+}
+
+function failureMessage(payload: Record<string, unknown>): string | null {
+  return presentFailure(payload).reason;
 }
 
 function goalText(payload: Record<string, unknown>): string | null {
@@ -1665,17 +3134,41 @@ function goalText(payload: Record<string, unknown>): string | null {
   return null;
 }
 
+function rememberPendingWaitOutcome(
+  pending: Map<string | null, PendingWaitOutcome>,
+  event: SessionEvent,
+  payload: Record<string, unknown>,
+  eventTurnId: string | null,
+): void {
+  const reason = stringValue(payload.reason).trim();
+  if (!reason) return;
+  const turnId =
+    eventTurnId || stringValue(payload.waitTurnId) || stringValue(payload.turnId) || null;
+  pending.set(turnId, { id: event.id, reason, occurredAt: event.occurredAt });
+}
+
+function waitingOutcomeText(reason: string): string {
+  return /^waiting\b/i.test(reason) ? reason : `Waiting: ${reason}`;
+}
+
 /**
  * Agent-owned goal mutations already have an in-cluster tool row. Suppress the
- * breakaway landmark for those only. `goal.completed` has no actor field today
- * and is only emitted by the agent tool, so it is always suppressed. API /
- * system / create-session / continuation landmarks stay visible.
+ * breakaway landmark for those only. Empty wait turns retain the durable hold
+ * reason and surface it after the folded steps. `goal.completed` has no actor
+ * field today and is only emitted by the agent tool, so it is always
+ * suppressed. API / system / create-session / continuation landmarks stay
+ * visible.
  */
 function shouldSuppressAgentGoalLandmark(type: string, payload: Record<string, unknown>): boolean {
   if (type === "goal.completed") {
     return true;
   }
-  if (type === "goal.set" || type === "goal.updated" || type === "goal.paused") {
+  if (
+    type === "goal.set" ||
+    type === "goal.updated" ||
+    type === "goal.paused" ||
+    type === "goal.held"
+  ) {
     return payload.actor === "agent";
   }
   return false;
@@ -1746,7 +3239,7 @@ function capabilityAuthorizationRequest(
   if (
     typeof record.id !== "string" ||
     typeof record.name !== "string" ||
-    !["pack", "mcp", "api", "skill", "plugin"].includes(String(kind)) ||
+    !["mcp", "api", "skill", "plugin"].includes(String(kind)) ||
     !["built_in", "library", "configured", "public_registry", "registry", "manual"].includes(
       String(source),
     ) ||
@@ -1766,6 +3259,29 @@ function capabilityAuthorizationRequest(
   };
 }
 
+function customMcpSetupRequest(value: unknown): NonNullable<AuthNeededItem["setupRequest"]> | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const input = value as Record<string, unknown>;
+  if (
+    input.kind !== "mcp" ||
+    typeof input.name !== "string" ||
+    typeof input.rationale !== "string" ||
+    typeof input.endpointUrl !== "string"
+  )
+    return null;
+  try {
+    if (new URL(input.endpointUrl).protocol !== "https:") return null;
+  } catch {
+    return null;
+  }
+  return {
+    kind: "mcp",
+    name: input.name,
+    endpointUrl: input.endpointUrl,
+    rationale: input.rationale,
+  };
+}
+
 function stringList(value: unknown): string[] {
   return Array.isArray(value)
     ? value.filter((entry): entry is string => typeof entry === "string" && entry.trim().length > 0)