From ce0cfea89ea99912d0f7fd0466a75ad057d725ff Mon Sep 17 00:00:00 2001
From: "haozhe.yang" <yanghaozhe@moonshot.ai>
Date: Fri, 31 Jul 2026 15:41:15 +0800
Subject: [PATCH 1/3] feat(agent-core-v2): persist the terminal turn.ended wire
 record

- add a persisted turn.ended op (turnId, reason, error, durationMs)
  dispatched from the loop's runTurn finally block, alongside the event
- fold the record back in the transcript cold rebuild: terminal state
  (blocked folded into failed, mirroring the live wire edge), durationMs,
  error message and endedAt; journals without the record keep the
  grouping default
- restrict the test harness's snapshot waiters to emit entries so the
  same-named wire record no longer shadows the turn.ended event
---
 .../agent-core-v2/docs/wire-manifest.d.ts     | 59 +++++++++++++-
 .../src/agent/loop/loopService.ts             |  6 +-
 .../agent-core-v2/src/agent/loop/turnOps.ts   | 17 ++++-
 .../test/agent/loop/loop.test.ts              | 16 ++++
 .../test/agent/plan/plan.test.ts              |  2 +
 .../test/app/config/config.test.ts            |  2 +
 packages/agent-core-v2/test/harness/agent.ts  |  6 ++
 packages/agent-core-v2/test/index.test.ts     |  7 +-
 .../agent-core-v2/test/snapshot/events.ts     |  8 +-
 packages/agent-core-v2/test/tool/tool.test.ts |  2 +
 packages/transcript/src/history/foldFacts.ts  | 76 +++++++++++++++++--
 packages/transcript/src/history/groupTurns.ts |  7 +-
 packages/transcript/test/layers.test.ts       | 71 +++++++++++++++++
 13 files changed, 261 insertions(+), 18 deletions(-)

diff --git a/packages/agent-core-v2/docs/wire-manifest.d.ts b/packages/agent-core-v2/docs/wire-manifest.d.ts
index 62a029c96a..9f79e4be23 100644
--- a/packages/agent-core-v2/docs/wire-manifest.d.ts
+++ b/packages/agent-core-v2/docs/wire-manifest.d.ts
@@ -21,7 +21,7 @@
 // owning model offloads inline media to blob storage), cross-reducers
 // (foreign models that also reduce this record on dispatch and replay).
 
-// Index (44 record types)
+// Index (45 record types)
 //   config.update                      profile              persisted  src/agent/profile/profileOps.ts
 //   context_size.measured              contextSize          transient  src/agent/contextSize/contextSizeOps.ts
 //   context.append_loop_event          contextMemory        persisted  src/agent/contextMemory/contextOps.ts
@@ -63,6 +63,7 @@
 //   tools.unregister_user_tool         userTool             persisted  src/agent/userTool/userToolOps.ts
 //   tools.update_store                 todo                 persisted  src/session/todo/todoOps.ts
 //   turn.cancel                        turn                 persisted  src/agent/loop/turnOps.ts
+//   turn.ended                         turn                 persisted  src/agent/loop/turnOps.ts
 //   turn.prompt                        turn                 persisted  src/agent/loop/turnOps.ts
 //   turn.steer                         turn                 persisted  src/agent/loop/turnOps.ts
 //   usage.record                       usage                persisted  src/agent/usage/usageOps.ts
@@ -571,6 +572,61 @@ interface TurnCancelPayload {
   target?: 'active' | 'queued';
 }
 
+/**
+ * model: turn · persisted
+ * owner: src/agent/loop/turnOps.ts
+ */
+interface TurnEndedPayload {
+  _name: 'turn.ended';
+  turnId: number;
+  reason: 'completed' | 'cancelled' | 'failed' | 'blocked';
+  /** KimiErrorPayload */
+  error?: {
+    code: (typeof ErrorCodes)[keyof typeof ErrorCodes];
+    message: string;
+    name?: string;
+    details?: Readonly<Record<string, unknown>>;
+    retryable: boolean;
+    cause?: {
+      code: (typeof ErrorCodes)[keyof typeof ErrorCodes];
+      message: string;
+      name?: string;
+      details?: Readonly<Record<string, unknown>>;
+      retryable: boolean;
+      cause?: {
+        code: (typeof ErrorCodes)[keyof typeof ErrorCodes];
+        message: string;
+        name?: string;
+        details?: Readonly<Record<string, unknown>>;
+        retryable: boolean;
+        cause?: {
+          code: (typeof ErrorCodes)[keyof typeof ErrorCodes];
+          message: string;
+          name?: string;
+          details?: Readonly<Record<string, unknown>>;
+          retryable: boolean;
+          cause?: {
+            code: (typeof ErrorCodes)[keyof typeof ErrorCodes];
+            message: string;
+            name?: string;
+            details?: Readonly<Record<string, unknown>>;
+            retryable: boolean;
+            cause?: {
+              code: ErrorCode;
+              message: string;
+              name?: string;
+              details?: Readonly<Record<string, unknown>>;
+              retryable: boolean;
+              cause?: ErrorPayload;
+            };
+          };
+        };
+      };
+    };
+  };
+  durationMs?: number;
+}
+
 /**
  * model: turn · persisted
  * owner: src/agent/loop/turnOps.ts
@@ -654,6 +710,7 @@ interface WirePayloadMap {
   "tools.unregister_user_tool": ToolsUnregisterUserToolPayload;
   "tools.update_store": ToolsUpdateStorePayload;
   "turn.cancel": TurnCancelPayload;
+  "turn.ended": TurnEndedPayload;
   "turn.prompt": TurnPromptPayload;
   "turn.steer": TurnSteerPayload;
   "usage.record": UsageRecordPayload;
diff --git a/packages/agent-core-v2/src/agent/loop/loopService.ts b/packages/agent-core-v2/src/agent/loop/loopService.ts
index ab568cef23..110e1c76f5 100644
--- a/packages/agent-core-v2/src/agent/loop/loopService.ts
+++ b/packages/agent-core-v2/src/agent/loop/loopService.ts
@@ -84,7 +84,7 @@ import {
 } from './stepRequest';
 import { StepRequestQueue, type StepRequestBatch } from './stepRequestQueue';
 import { isDisplayablePromptOrigin, turnPromptText } from './turnEvents';
-import { cancelTurn, promptTurn, TurnModel } from './turnOps';
+import { cancelTurn, endTurn, promptTurn, TurnModel } from './turnOps';
 
 export type LoopInterruptReason = 'aborted' | 'max_steps' | 'error';
 
@@ -495,12 +495,14 @@ export class AgentLoopService extends Disposable implements IAgentLoopService {
           : this.activeRequestTrace?.traceId;
       if (result !== undefined) {
         const error = result.type === 'failed' ? toKimiErrorPayload(result.error) : undefined;
+        const durationMs = Date.now() - startedAt;
+        this.wire.dispatch(endTurn({ turnId: turn.id, reason: result.type, error, durationMs }));
         this.eventBus.publish({
           type: 'turn.ended',
           turnId: turn.id,
           reason: result.type,
           error,
-          durationMs: Date.now() - startedAt,
+          durationMs,
         });
         if (error !== undefined) this.eventBus.publish({ type: 'error', ...error });
         if (result.type !== 'completed') {
diff --git a/packages/agent-core-v2/src/agent/loop/turnOps.ts b/packages/agent-core-v2/src/agent/loop/turnOps.ts
index 2a5c0dd236..4082a3421a 100644
--- a/packages/agent-core-v2/src/agent/loop/turnOps.ts
+++ b/packages/agent-core-v2/src/agent/loop/turnOps.ts
@@ -3,12 +3,16 @@
  * identity.
  *
  * Owns the next available turn id, including cancelled queued reservations and
- * legacy loop-event observations.
+ * legacy loop-event observations. Also persists the terminal `turn.ended`
+ * record (reason / error / durationMs) so downstream history rebuilds can
+ * recover how a turn ended; the record carries no engine-restorable state, so
+ * its `apply` is a no-op.
  */
 
 import { z } from 'zod';
 
 import { defineModel } from '#/wire/model';
+import type { KimiErrorPayload } from '#/_base/errors/serialize';
 import type { ContentPart } from '#/kosong/contract/message';
 import type { PromptOrigin } from '#/agent/contextMemory/types';
 
@@ -46,6 +50,7 @@ declare module '#/wire/types' {
     'turn.prompt': typeof promptTurn;
     'turn.steer': typeof steerTurn;
     'turn.cancel': typeof cancelTurn;
+    'turn.ended': typeof endTurn;
   }
 }
 
@@ -70,6 +75,16 @@ export const cancelTurn = TurnModel.defineOp('turn.cancel', {
   },
 });
 
+export const endTurn = TurnModel.defineOp('turn.ended', {
+  schema: z.object({
+    turnId: z.number(),
+    reason: z.enum(['completed', 'cancelled', 'failed', 'blocked']),
+    error: z.custom<KimiErrorPayload>().optional(),
+    durationMs: z.number().optional(),
+  }),
+  apply: (s) => s,
+});
+
 function advanceTurnClock(
   state: TurnModelState,
   nextTurnId: number,
diff --git a/packages/agent-core-v2/test/agent/loop/loop.test.ts b/packages/agent-core-v2/test/agent/loop/loop.test.ts
index 9d0242ec1d..89bddbe559 100644
--- a/packages/agent-core-v2/test/agent/loop/loop.test.ts
+++ b/packages/agent-core-v2/test/agent/loop/loop.test.ts
@@ -78,6 +78,7 @@ describe('Agent loop', () => {
       [wire] context.append_loop_event   { "event": { "type": "content.part", "uuid": "<uuid-2>", "turnId": "0", "step": 1, "stepUuid": "<uuid-1>", "part": { "type": "think", "think": "<think-1>" } }, "time": "<time>" }
       [wire] context.append_loop_event   { "event": { "type": "content.part", "uuid": "<uuid-3>", "turnId": "0", "step": 1, "stepUuid": "<uuid-1>", "part": { "type": "text", "text": "<text-1>" } }, "time": "<time>" }
       [wire] context.append_loop_event   { "event": { "type": "step.end", "uuid": "<uuid-1>", "turnId": "0", "step": 1, "finishReason": "end_turn", "usage": { "inputOther": 3, "output": 8, "inputCacheRead": 0, "inputCacheCreation": 0 }, "messageId": "mock-1", "providerFinishReason": "completed", "rawFinishReason": "stop" }, "time": "<time>" }
+      [wire] turn.ended                  { "turnId": 0, "reason": "completed", "time": "<time>" }
       [emit] turn.ended                  { "turnId": 0, "reason": "completed" }
     `);
     expect(ctx.lastLlmInput()).toMatchInlineSnapshot(`
@@ -88,6 +89,19 @@ describe('Agent loop', () => {
   `);
   });
 
+  it('persists a turn.ended wire record with the end reason and duration', async () => {
+    profile.update({ activeToolNames: [] });
+
+    ctx.mockNextResponse({ type: 'text', text: 'done' });
+    await ctx.rpc.prompt({ input: [{ type: 'text', text: 'Hello' }] });
+    await ctx.untilTurnEnd();
+
+    const record = (await ctx.persistedWireRecords()).find((entry) => entry.type === 'turn.ended');
+    expect(record).toMatchObject({ turnId: 0, reason: 'completed' });
+    expect(record?.['durationMs']).toEqual(expect.any(Number));
+    expect(record?.['time']).toEqual(expect.any(Number));
+  });
+
   it('fails the turn after a filtered step completes', async () => {
     ctx.mockNextProviderResponse({
       parts: [{ type: 'text', text: 'blocked' }],
@@ -115,6 +129,7 @@ describe('Agent loop', () => {
       [emit] agent.activity.updated      { "lifecycle": "ready", "turn": { "turnId": 0, "origin": { "kind": "user" }, "phase": "running", "step": 1, "ending": false, "pendingApprovals": [], "activeToolCalls": [], "since": "<time>" }, "background": [] }
       [wire] context.append_loop_event   { "event": { "type": "content.part", "uuid": "<uuid-2>", "turnId": "0", "step": 1, "stepUuid": "<uuid-1>", "part": { "type": "text", "text": "blocked" } }, "time": "<time>" }
       [wire] context.append_loop_event   { "event": { "type": "step.end", "uuid": "<uuid-1>", "turnId": "0", "step": 1, "finishReason": "filtered", "usage": { "inputOther": 3, "output": 5, "inputCacheRead": 0, "inputCacheCreation": 0 }, "messageId": "mock-1", "providerFinishReason": "filtered", "rawFinishReason": "filtered" }, "time": "<time>" }
+      [wire] turn.ended                  { "turnId": 0, "reason": "failed", "error": { "code": "provider.filtered", "message": "Provider safety policy blocked the response.", "name": "ProviderFilteredError", "details": { "finishReason": "filtered" }, "retryable": false }, "time": "<time>" }
       [emit] turn.ended                  { "turnId": 0, "reason": "failed", "error": { "code": "provider.filtered", "message": "Provider safety policy blocked the response.", "name": "ProviderFilteredError", "details": { "finishReason": "filtered" }, "retryable": false } }
     `);
 
@@ -368,6 +383,7 @@ describe('Agent loop', () => {
       [emit] agent.activity.updated              { "lifecycle": "ready", "turn": { "turnId": 0, "origin": { "kind": "user" }, "phase": "running", "step": 2, "ending": false, "pendingApprovals": [], "activeToolCalls": [], "since": "<time>" }, "background": [] }
       [wire] context.append_loop_event           { "event": { "type": "content.part", "uuid": "<uuid-5>", "turnId": "0", "step": 2, "stepUuid": "<uuid-4>", "part": { "type": "text", "text": "The lookup result is lookup-result." } }, "time": "<time>" }
       [wire] context.append_loop_event           { "event": { "type": "step.end", "uuid": "<uuid-4>", "turnId": "0", "step": 2, "finishReason": "end_turn", "usage": { "inputOther": 25, "output": 12, "inputCacheRead": 0, "inputCacheCreation": 0 }, "messageId": "mock-2", "providerFinishReason": "completed", "rawFinishReason": "stop" }, "time": "<time>" }
+      [wire] turn.ended                          { "turnId": 0, "reason": "completed", "time": "<time>" }
       [emit] turn.ended                          { "turnId": 0, "reason": "completed" }
     `);
     expect(ctx.lastLlmInput()).toMatchInlineSnapshot(`
diff --git a/packages/agent-core-v2/test/agent/plan/plan.test.ts b/packages/agent-core-v2/test/agent/plan/plan.test.ts
index 56f2671a5a..cb2dccf472 100644
--- a/packages/agent-core-v2/test/agent/plan/plan.test.ts
+++ b/packages/agent-core-v2/test/agent/plan/plan.test.ts
@@ -768,6 +768,7 @@ describe('Plan service', () => {
         [emit] agent.activity.updated      { "lifecycle": "ready", "turn": { "turnId": 0, "origin": { "kind": "user" }, "phase": "running", "step": 2, "ending": false, "pendingApprovals": [], "activeToolCalls": [], "since": "<time>" }, "background": [] }
         [wire] context.append_loop_event   { "event": { "type": "content.part", "uuid": "<uuid-5>", "turnId": "0", "step": 2, "stepUuid": "<uuid-4>", "part": { "type": "text", "text": "The safe command printed plan-safe." } }, "time": "<time>" }
         [wire] context.append_loop_event   { "event": { "type": "step.end", "uuid": "<uuid-4>", "turnId": "0", "step": 2, "finishReason": "end_turn", "usage": { "inputOther": 592, "output": 12, "inputCacheRead": 0, "inputCacheCreation": 0 }, "messageId": "mock-2", "providerFinishReason": "completed", "rawFinishReason": "stop" }, "time": "<time>" }
+        [wire] turn.ended                  { "turnId": 0, "reason": "completed", "time": "<time>" }
         [emit] turn.ended                  { "turnId": 0, "reason": "completed" }
       `);
 
@@ -843,6 +844,7 @@ describe('Plan service', () => {
         [emit] agent.activity.updated      { "lifecycle": "ready", "turn": { "turnId": 0, "origin": { "kind": "user" }, "phase": "running", "step": 2, "ending": false, "pendingApprovals": [], "activeToolCalls": [], "since": "<time>" }, "background": [] }
         [wire] context.append_loop_event   { "event": { "type": "content.part", "uuid": "<uuid-5>", "turnId": "0", "step": 2, "stepUuid": "<uuid-4>", "part": { "type": "text", "text": "The command completed." } }, "time": "<time>" }
         [wire] context.append_loop_event   { "event": { "type": "step.end", "uuid": "<uuid-4>", "turnId": "0", "step": 2, "finishReason": "end_turn", "usage": { "inputOther": 588, "output": 9, "inputCacheRead": 0, "inputCacheCreation": 0 }, "messageId": "mock-2", "providerFinishReason": "completed", "rawFinishReason": "stop" }, "time": "<time>" }
+        [wire] turn.ended                  { "turnId": 0, "reason": "completed", "time": "<time>" }
         [emit] turn.ended                  { "turnId": 0, "reason": "completed" }
       `);
       expect(toolResultText(context.get())).toContain('removed');
diff --git a/packages/agent-core-v2/test/app/config/config.test.ts b/packages/agent-core-v2/test/app/config/config.test.ts
index 92d74232a7..6560bb4f17 100644
--- a/packages/agent-core-v2/test/app/config/config.test.ts
+++ b/packages/agent-core-v2/test/app/config/config.test.ts
@@ -361,6 +361,7 @@ describe('Agent config', () => {
       [emit] agent.activity.updated      { "lifecycle": "ready", "turn": { "turnId": 0, "origin": { "kind": "user" }, "phase": "running", "step": 2, "ending": false, "pendingApprovals": [], "activeToolCalls": [], "since": "<time>" }, "background": [] }
       [wire] context.append_loop_event   { "event": { "type": "content.part", "uuid": "<uuid-5>", "turnId": "0", "step": 2, "stepUuid": "<uuid-4>", "part": { "type": "text", "text": "Still using the original turn config." } }, "time": "<time>" }
       [wire] context.append_loop_event   { "event": { "type": "step.end", "uuid": "<uuid-4>", "turnId": "0", "step": 2, "finishReason": "end_turn", "usage": { "inputOther": 31, "output": 13, "inputCacheRead": 0, "inputCacheCreation": 0 }, "messageId": "mock-2", "providerFinishReason": "completed", "rawFinishReason": "stop" }, "time": "<time>" }
+      [wire] turn.ended                  { "turnId": 0, "reason": "completed", "time": "<time>" }
       [emit] turn.ended                  { "turnId": 0, "reason": "completed" }
     `);
     expect(ctx.lastLlmInput()).toMatchInlineSnapshot(`
@@ -395,6 +396,7 @@ describe('Agent config', () => {
       [emit] agent.activity.updated      { "lifecycle": "ready", "turn": { "turnId": 1, "origin": { "kind": "user" }, "phase": "running", "step": 1, "ending": false, "pendingApprovals": [], "activeToolCalls": [], "since": "<time>" }, "background": [] }
       [wire] context.append_loop_event   { "event": { "type": "content.part", "uuid": "<uuid-7>", "turnId": "1", "step": 1, "stepUuid": "<uuid-6>", "part": { "type": "text", "text": "Now the changed config is active." } }, "time": "<time>" }
       [wire] context.append_loop_event   { "event": { "type": "step.end", "uuid": "<uuid-6>", "turnId": "1", "step": 1, "finishReason": "end_turn", "usage": { "inputOther": 50, "output": 12, "inputCacheRead": 0, "inputCacheCreation": 0 }, "messageId": "mock-3", "providerFinishReason": "completed", "rawFinishReason": "stop" }, "time": "<time>" }
+      [wire] turn.ended                  { "turnId": 1, "reason": "completed", "time": "<time>" }
       [emit] turn.ended                  { "turnId": 1, "reason": "completed" }
     `);
     expect(ctx.lastLlmInput()).toMatchInlineSnapshot(`
diff --git a/packages/agent-core-v2/test/harness/agent.ts b/packages/agent-core-v2/test/harness/agent.ts
index 68e855533a..0d36e22c08 100644
--- a/packages/agent-core-v2/test/harness/agent.ts
+++ b/packages/agent-core-v2/test/harness/agent.ts
@@ -1569,6 +1569,12 @@ export class AgentTestContext {
     return this.snapshots.until('turn.ended');
   }
 
+  /** The agent's persisted wire journal (drains the persistence queue first). */
+  async persistedWireRecords(): Promise<WireRecord[]> {
+    await this.drainWirePersistence();
+    return this.persistedRecords();
+  }
+
   untilApprovalRequest(): Promise<EventSnapshot> {
     return this.snapshots.until('requestApproval');
   }
diff --git a/packages/agent-core-v2/test/index.test.ts b/packages/agent-core-v2/test/index.test.ts
index db7cd48bad..9a486acb1c 100644
--- a/packages/agent-core-v2/test/index.test.ts
+++ b/packages/agent-core-v2/test/index.test.ts
@@ -78,15 +78,16 @@ const V2_ONLY_RECORD_TYPES: ReadonlySet<string> = new Set([
 
 // Persisted record types introduced after the v1 vocabulary: the task
 // lifecycle journal (the restore seed for ghosts and the cold transcript
-// fold), the interaction request/resolution journal, and the plan revision
-// reference journal. Replay tolerates unknown record types (skip + warn), so
-// older readers degrade gracefully.
+// fold), the interaction request/resolution journal, the plan revision
+// reference journal, and the terminal turn record. Replay tolerates unknown
+// record types (skip + warn), so older readers degrade gracefully.
 const V2_RECORD_TYPES: ReadonlySet<string> = new Set([
   'task.started',
   'task.terminated',
   'interaction.request',
   'interaction.resolved',
   'plan.revision',
+  'turn.ended',
 ]);
 
 describe('v1 wire vocabulary', () => {
diff --git a/packages/agent-core-v2/test/snapshot/events.ts b/packages/agent-core-v2/test/snapshot/events.ts
index 06267edb5d..08f9cd157a 100644
--- a/packages/agent-core-v2/test/snapshot/events.ts
+++ b/packages/agent-core-v2/test/snapshot/events.ts
@@ -55,9 +55,13 @@ export function recordAgentEvents() {
   const emit = (entry: RecordedEventEntry): RecordedEventEntry => {
     entries.push(entry);
 
+    // Snapshot-returning waiters match EMIT entries only: a persisted wire
+    // record can share its type with an event (e.g. `turn.ended`), and the
+    // waiter's intent is the event — resolving on the wire entry would also
+    // truncate the matching emit entry out of the returned snapshot.
     for (let index = eventWaiters.length - 1; index >= 0; index -= 1) {
       const waiter = eventWaiters[index]!;
-      if (waiter.event !== entry.event) continue;
+      if (entry.type !== '[rpc]' || waiter.event !== entry.event) continue;
       eventWaiters.splice(index, 1);
       cursor = Math.max(cursor, entries.length);
       waiter.resolve(snapshotFrom(waiter.start));
@@ -79,7 +83,7 @@ export function recordAgentEvents() {
 
     for (let index = takeWaiters.length - 1; index >= 0; index -= 1) {
       const waiter = takeWaiters[index]!;
-      if (waiter.event !== entry.event) continue;
+      if (entry.type !== '[rpc]' || waiter.event !== entry.event) continue;
       takeWaiters.splice(index, 1);
       cursor = Math.max(cursor, entries.length);
       waiter.resolve({
diff --git a/packages/agent-core-v2/test/tool/tool.test.ts b/packages/agent-core-v2/test/tool/tool.test.ts
index e10e828d28..2f5c185acb 100644
--- a/packages/agent-core-v2/test/tool/tool.test.ts
+++ b/packages/agent-core-v2/test/tool/tool.test.ts
@@ -3157,6 +3157,7 @@ describe('Agent tools', () => {
         [emit] agent.activity.updated      { "lifecycle": "ready", "turn": { "turnId": 0, "origin": { "kind": "user" }, "phase": "running", "step": 2, "ending": false, "pendingApprovals": [], "activeToolCalls": [], "since": "<time>" }, "background": [] }
         [wire] context.append_loop_event   { "event": { "type": "content.part", "uuid": "<uuid-5>", "turnId": "0", "step": 2, "stepUuid": "<uuid-4>", "part": { "type": "text", "text": "The lookup result is moon-result." } }, "time": "<time>" }
         [wire] context.append_loop_event   { "event": { "type": "step.end", "uuid": "<uuid-4>", "turnId": "0", "step": 2, "finishReason": "end_turn", "usage": { "inputOther": 164, "output": 12, "inputCacheRead": 0, "inputCacheCreation": 0 }, "messageId": "mock-2", "providerFinishReason": "completed", "rawFinishReason": "stop" }, "time": "<time>" }
+        [wire] turn.ended                  { "turnId": 0, "reason": "completed", "time": "<time>" }
         [emit] turn.ended                  { "turnId": 0, "reason": "completed" }
       `);
       expect(ctx.lastLlmInput()).toMatchInlineSnapshot(`
@@ -3192,6 +3193,7 @@ describe('Agent tools', () => {
         [emit] agent.activity.updated       { "lifecycle": "ready", "turn": { "turnId": 1, "origin": { "kind": "user" }, "phase": "running", "step": 1, "ending": false, "pendingApprovals": [], "activeToolCalls": [], "since": "<time>" }, "background": [] }
         [wire] context.append_loop_event    { "event": { "type": "content.part", "uuid": "<uuid-7>", "turnId": "1", "step": 1, "stepUuid": "<uuid-6>", "part": { "type": "text", "text": "No lookup tool is available." } }, "time": "<time>" }
         [wire] context.append_loop_event    { "event": { "type": "step.end", "uuid": "<uuid-6>", "turnId": "1", "step": 1, "finishReason": "end_turn", "usage": { "inputOther": 184, "output": 10, "inputCacheRead": 0, "inputCacheCreation": 0 }, "messageId": "mock-3", "providerFinishReason": "completed", "rawFinishReason": "stop" }, "time": "<time>" }
+        [wire] turn.ended                   { "turnId": 1, "reason": "completed", "time": "<time>" }
         [emit] turn.ended                   { "turnId": 1, "reason": "completed" }
       `);
       expect(ctx.lastLlmInput()).toMatchInlineSnapshot(`
diff --git a/packages/transcript/src/history/foldFacts.ts b/packages/transcript/src/history/foldFacts.ts
index c038988439..551688a624 100644
--- a/packages/transcript/src/history/foldFacts.ts
+++ b/packages/transcript/src/history/foldFacts.ts
@@ -1,8 +1,8 @@
 /**
  * Cold-path fact fold: enrich a base snapshot (the turn tree built by
  * `groupMessagesIntoSnapshot`) with the durable facts carried by the
- * non-`context.*` wire records — tasks, interactions, todos, and the
- * goal/plan/swarm meta.
+ * non-`context.*` wire records — tasks, interactions, todos, turn ends, and
+ * the goal/plan/swarm meta.
  *
  * This is the second half of the cold rebuild: the engine persists these
  * records next to the context messages in the same `wire.jsonl`, and the live
@@ -15,10 +15,14 @@
  *    position (the base items carry no timestamps to interleave with), so
  *    they append IN RECORD ORDER at the END of the base items with an
  *    accurate `at` (record time). Entity state is complete.
+ *  - turn end facts (terminal state / durationMs / error message) are
+ *    rebuilt from the persisted `turn.ended` records when the journal
+ *    carries them; journals written before those records existed keep the
+ *    grouping default (`completed`).
  *  - live-only detail is never backfilled: step usage / finishReason /
- *    timing / retry, turn durationMs / error, tool inputText / progress, and
- *    task resultSummary / error / stateReason / usage exist only on live
- *    engine events — the persisted records do not carry them.
+ *    timing / retry, tool inputText / progress, and task resultSummary /
+ *    error / stateReason / usage exist only on live engine events — the
+ *    persisted records do not carry them.
  *  - prompts are NOT cold-rebuilt: the wire journal has no prompt records
  *    (`prompt.submitted/completed/aborted/steered` are in-memory eventBus
  *    events of the engine's prompt service, never persisted as Ops), so a
@@ -34,6 +38,7 @@ import type { TranscriptItem, TranscriptMarker, TranscriptTaskRef } from '../mod
 import type { GoalMeta, GoalStatus, TranscriptMeta } from '../model/meta';
 import type { TranscriptTask } from '../model/task';
 import type { TodoItem, TranscriptTodo } from '../model/todo';
+import type { TranscriptTurn } from '../model/turn';
 import type { AgentTranscriptSnapshot } from '../ops/operation';
 
 export interface HistoryWireRecord {
@@ -97,6 +102,14 @@ interface PlanRevisionPayload {
   readonly bytes?: unknown;
 }
 
+/** `turn.ended` payload (the loop's terminal turn record). */
+interface TurnEndedPayload {
+  readonly turnId?: unknown;
+  readonly reason?: unknown;
+  readonly error?: unknown;
+  readonly durationMs?: unknown;
+}
+
 /** Engine task kinds (`AgentTaskInfoByKind`: process / agent / question) → transcript kinds. */
 function mapTaskKind(kind: unknown): TranscriptTask['kind'] {
   switch (kind) {
@@ -133,6 +146,28 @@ function mapInteractionEndState(
   return 'cancelled';
 }
 
+/** Turn terminal state — mirrors the live path's `mapTurnEndState` (`blocked` folds into `failed`). */
+function mapTurnEndReason(reason: unknown): TranscriptTurn['state'] | undefined {
+  switch (reason) {
+    case 'completed':
+      return 'completed';
+    case 'cancelled':
+      return 'cancelled';
+    case 'failed':
+    case 'blocked':
+      return 'failed';
+    default:
+      return undefined;
+  }
+}
+
+/** The transcript turn carries only the terminal error's message. */
+function readTurnErrorMessage(error: unknown): string | undefined {
+  if (error === null || typeof error !== 'object') return undefined;
+  const message = (error as { message?: unknown }).message;
+  return typeof message === 'string' ? message : undefined;
+}
+
 /** Epoch-ms record times become ISO `at` stamps; ISO strings pass through. */
 function recordTimeIso(record: HistoryWireRecord): string | undefined {
   const time: unknown = record.time;
@@ -173,6 +208,8 @@ export function foldWireRecordFacts(
 ): AgentTranscriptSnapshot {
   const tasks = new Map<string, TranscriptTask>();
   const interactions = new Map<string, TranscriptInteraction>();
+  /** Latest `turn.ended` record per engine turn id (last-wins). */
+  const endedTurns = new Map<number, HistoryWireRecord>();
   let todo: TranscriptTodo | undefined;
   let goal: GoalMeta | undefined;
   let goalTouched = false;
@@ -379,6 +416,11 @@ export function foldWireRecordFacts(
         });
         break;
       }
+      case 'turn.ended': {
+        const payload = record as TurnEndedPayload;
+        if (typeof payload.turnId === 'number') endedTurns.set(payload.turnId, record);
+        break;
+      }
       default:
         break;
     }
@@ -392,6 +434,28 @@ export function foldWireRecordFacts(
     }
   }
 
+  // `turn.ended` records rewrite the matching base turn items (the engine's
+  // 0-based turn id aligns with the grouping ordinal — see groupTurns).
+  // Unmatched ids are ignored: grouping can drift when hidden origins consume
+  // engine turns the fold cannot see.
+  const items =
+    endedTurns.size > 0
+      ? base.items.map((item) => {
+          if (item.kind !== 'turn') return item;
+          const record = endedTurns.get(item.ordinal);
+          if (record === undefined) return item;
+          const payload = record as TurnEndedPayload;
+          return {
+            ...item,
+            state: mapTurnEndReason(payload.reason) ?? item.state,
+            endedAt: recordTimeIso(record) ?? item.endedAt,
+            durationMs:
+              typeof payload.durationMs === 'number' ? payload.durationMs : item.durationMs,
+            error: readTurnErrorMessage(payload.error) ?? item.error,
+          };
+        })
+      : base.items;
+
   const modesTouched = planActive !== undefined || swarmActive !== undefined;
   const meta: TranscriptMeta = {
     ...base.meta,
@@ -416,7 +480,7 @@ export function foldWireRecordFacts(
 
   return {
     ...base,
-    items: appended.length > 0 ? [...base.items, ...appended] : base.items,
+    items: appended.length > 0 ? [...items, ...appended] : items,
     tasks: [...tasks.values()],
     interactions: [...interactions.values()],
     todos: todo !== undefined ? [todo] : base.todos,
diff --git a/packages/transcript/src/history/groupTurns.ts b/packages/transcript/src/history/groupTurns.ts
index a5d558cd03..bc9c6afd8a 100644
--- a/packages/transcript/src/history/groupTurns.ts
+++ b/packages/transcript/src/history/groupTurns.ts
@@ -6,9 +6,10 @@
  * high-fidelity one. Known limitations, accepted by design:
  *  - step granularity collapses to "one assistant message = one step";
  *  - live-only detail is never backfilled: step usage / finishReason /
- *    timing / retry, turn durationMs / error, tool inputText / progress, and
- *    task resultSummary / error / stateReason / usage exist only on live
- *    engine events — persisted context messages do not carry them;
+ *    timing / retry, tool inputText / progress, and task resultSummary /
+ *    error / stateReason / usage exist only on live engine events — persisted
+ *    context messages do not carry them (turn end facts DO persist as
+ *    `turn.ended` records and are folded in by `foldWireRecordFacts`);
  *  - media content parts become attachment entities (metadata only — base64
  *    bytes are dropped, never shipped); mid-turn media is not anchored;
  *  - streamed-vs-persisted duplication is assumed already resolved upstream;
diff --git a/packages/transcript/test/layers.test.ts b/packages/transcript/test/layers.test.ts
index 3ce1b213cd..c5155384f3 100644
--- a/packages/transcript/test/layers.test.ts
+++ b/packages/transcript/test/layers.test.ts
@@ -1036,4 +1036,75 @@ describe('foldWireRecordFacts (cold facts)', () => {
     );
     expect(folded.interactions).toEqual([]);
   });
+
+  it('folds turn.ended records into the matching turn items', () => {
+    const base = baseWithMarker();
+    const folded = foldWireRecordFacts(
+      [
+        {
+          type: 'turn.ended',
+          turnId: 0,
+          reason: 'failed',
+          error: { code: 'provider.overloaded', message: 'Overloaded', name: 'APIStatusError', retryable: true },
+          durationMs: 1234,
+          time: 5000,
+        },
+      ],
+      base,
+    );
+    const turn = folded.items[0];
+    if (turn?.kind !== 'turn') throw new Error('expected turn');
+    // The base grouping hardcodes 'completed'; the record rewrites it.
+    expect(turn.state).toBe('failed');
+    // Only the error's message rides the transcript turn (mirrors the live path).
+    expect(turn.error).toBe('Overloaded');
+    expect(turn.durationMs).toBe(1234);
+    expect(turn.endedAt).toBe(new Date(5000).toISOString());
+    // Turn ends append no items.
+    expect(folded.items).toHaveLength(base.items.length);
+  });
+
+  it('applies turn.ended records last-wins per turn and folds blocked into failed', () => {
+    const base = baseWithMarker();
+    const folded = foldWireRecordFacts(
+      [
+        { type: 'turn.ended', turnId: 0, reason: 'failed', error: { message: 'boom' }, time: 1000 },
+        { type: 'turn.ended', turnId: 0, reason: 'cancelled', durationMs: 10, time: 2000 },
+      ],
+      base,
+    );
+    const turn = folded.items[0];
+    if (turn?.kind !== 'turn') throw new Error('expected turn');
+    expect(turn.state).toBe('cancelled');
+    // The last record replaces the whole terminal upsert — no earlier error.
+    expect(turn.error).toBeUndefined();
+    expect(turn.durationMs).toBe(10);
+    expect(turn.endedAt).toBe(new Date(2000).toISOString());
+
+    const blocked = foldWireRecordFacts(
+      [{ type: 'turn.ended', turnId: 0, reason: 'blocked', time: 3000 }],
+      base,
+    );
+    const blockedTurn = blocked.items[0];
+    if (blockedTurn?.kind !== 'turn') throw new Error('expected turn');
+    expect(blockedTurn.state).toBe('failed');
+  });
+
+  it('ignores turn.ended records with unknown turn ids or malformed payloads', () => {
+    const base = baseWithMarker();
+    const folded = foldWireRecordFacts(
+      [
+        { type: 'turn.ended', turnId: 9, reason: 'cancelled', time: 1000 },
+        { type: 'turn.ended', reason: 'completed', time: 2000 },
+        { type: 'turn.ended', turnId: 0, reason: 'not-a-reason', time: 3000 },
+      ],
+      base,
+    );
+    const turn = folded.items[0];
+    if (turn?.kind !== 'turn') throw new Error('expected turn');
+    // An unrecognized reason keeps the grouping default; only the timestamp lands.
+    expect(turn.state).toBe('completed');
+    expect(turn.endedAt).toBe(new Date(3000).toISOString());
+    expect(folded.items).toHaveLength(base.items.length);
+  });
 });

From d1d7bd9cf58a14232797ec7bb0e6afdb26d744fb Mon Sep 17 00:00:00 2001
From: "haozhe.yang" <yanghaozhe@moonshot.ai>
Date: Fri, 31 Jul 2026 15:41:24 +0800
Subject: [PATCH 2/3] chore(agent-core-v2): stabilize unique-symbol keys in the
 state manifest

The checker names a unique symbol key __@name@NNNN, where NNNN is a
compilation-global counter that shifts with unrelated type additions and
churns the generated manifest. Render the stable __@name form instead.
---
 packages/agent-core-v2/docs/state-manifest.d.ts      |  2 +-
 .../agent-core-v2/scripts/gen-state-manifest.mts     | 12 +++++++++++-
 2 files changed, 12 insertions(+), 2 deletions(-)

diff --git a/packages/agent-core-v2/docs/state-manifest.d.ts b/packages/agent-core-v2/docs/state-manifest.d.ts
index fed980fbf1..d6ed6bd8bc 100644
--- a/packages/agent-core-v2/docs/state-manifest.d.ts
+++ b/packages/agent-core-v2/docs/state-manifest.d.ts
@@ -1004,7 +1004,7 @@ export interface AgentStateSnapshot {
   'llmRequester.lastConfigLogSignature': string | undefined;
   'llmRequester.mediaDegradedTurns': Set<number>;
   'llmRequester.mediaStrippedTurns': Map<number, /* MediaStripSnapshot — packages/agent-core-v2/src/agent/contextProjector/contextProjector.ts */ {
-    readonly "__@mediaStripSnapshotBrand@2376": undefined;
+    readonly "__@mediaStripSnapshotBrand": undefined;
   }>;
   'llmRequester.turnConfigs': Map<number, /* TurnRequestConfig — packages/agent-core-v2/src/agent/llmRequester/llmRequesterService.ts */ {
     readonly resolved: /* ProfileModelContext — packages/agent-core-v2/src/agent/profile/profile.ts */ {
diff --git a/packages/agent-core-v2/scripts/gen-state-manifest.mts b/packages/agent-core-v2/scripts/gen-state-manifest.mts
index d24bbfa843..7fdb480292 100644
--- a/packages/agent-core-v2/scripts/gen-state-manifest.mts
+++ b/packages/agent-core-v2/scripts/gen-state-manifest.mts
@@ -122,6 +122,16 @@ function tsFieldKey(key: string): string {
   return /^[$A-Z_a-z][$\w]*$/.test(key) ? key : JSON.stringify(key);
 }
 
+/**
+ * The checker names a `unique symbol` key `__@<declName>@<globalSymbolId>` —
+ * the numeric id is a compilation-global counter that shifts with unrelated
+ * edits, so the manifest renders the stable `__@<declName>` form instead.
+ */
+function stableSymbolKey(key: string): string {
+  const match = /^__@(.+)@\d+$/.exec(key);
+  return match === null ? key : `__@${match[1]}`;
+}
+
 // ---------------------------------------------------------------------------
 // Static pass — key constants and their register call sites
 // ---------------------------------------------------------------------------
@@ -635,7 +645,7 @@ class TypeRenderer {
       const propLines = rendered.split('\n');
       propLines[propLines.length - 1] += ';';
       lines.push(
-        `  ${readonly}${tsFieldKey(prop.getName())}${optional ? '?' : ''}: ${propLines[0]}`,
+        `  ${readonly}${tsFieldKey(stableSymbolKey(prop.getName()))}${optional ? '?' : ''}: ${propLines[0]}`,
         ...propLines.slice(1).map((line) => `  ${line}`),
       );
     }

From 5d5861cc4b73937842cff3fa5020d1b7d1041499 Mon Sep 17 00:00:00 2001
From: "haozhe.yang" <yanghaozhe@moonshot.ai>
Date: Fri, 31 Jul 2026 15:59:25 +0800
Subject: [PATCH 3/3] fix(transcript): map turn.ended around hidden turns in
 the cold fold

RetryStepRequest opens a real engine turn with origin 'retry' but
contributes no context messages, and a queued-then-cancelled
reservation consumes an engine id without starting. Both make engine
turn ids drift from the grouping ordinals, so matching turn.ended by
ordinal could stamp a later visible turn with the wrong terminal state.
Replay the loop's turn-clock records (turn.prompt / turn.cancel) and
map engine ids to ordinals past the hidden ids; the hidden turns' own
end records map nowhere and are dropped.
---
 packages/transcript/src/history/foldFacts.ts | 96 ++++++++++++++++++--
 packages/transcript/test/layers.test.ts      | 59 ++++++++++++
 2 files changed, 147 insertions(+), 8 deletions(-)

diff --git a/packages/transcript/src/history/foldFacts.ts b/packages/transcript/src/history/foldFacts.ts
index 551688a624..5fff4ba5fa 100644
--- a/packages/transcript/src/history/foldFacts.ts
+++ b/packages/transcript/src/history/foldFacts.ts
@@ -17,8 +17,10 @@
  *    accurate `at` (record time). Entity state is complete.
  *  - turn end facts (terminal state / durationMs / error message) are
  *    rebuilt from the persisted `turn.ended` records when the journal
- *    carries them; journals written before those records existed keep the
- *    grouping default (`completed`).
+ *    carries them, with engine turn ids mapped to grouping ordinals
+ *    through the replayed turn clock (hidden retry turns and cancelled
+ *    queued reservations shift the ordinals); journals written before
+ *    those records existed keep the grouping default (`completed`).
  *  - live-only detail is never backfilled: step usage / finishReason /
  *    timing / retry, tool inputText / progress, and task resultSummary /
  *    error / stateReason / usage exist only on live engine events — the
@@ -110,6 +112,37 @@ interface TurnEndedPayload {
   readonly durationMs?: unknown;
 }
 
+/** `turn.prompt` / `turn.cancel` payloads (the loop's turn-clock records). */
+interface TurnPromptPayload {
+  readonly origin?: unknown;
+}
+interface TurnCancelPayload {
+  readonly turnId?: unknown;
+  readonly target?: unknown;
+}
+
+/**
+ * Mirror of groupTurns' turn-opening rules, applied to `turn.prompt`
+ * origins: whether the turn opens a visible transcript item. The engine
+ * opens a real turn a transcript never shows for retry turns
+ * (`RetryStepRequest` — origin `retry`, no context messages); hidden
+ * mid-turn origins never produce `turn.prompt` records at all, but are
+ * classified here anyway for completeness.
+ */
+function isVisibleTurnOrigin(origin: unknown): boolean {
+  const kind = (origin as { kind?: unknown } | undefined)?.kind;
+  if (kind === 'system_trigger') {
+    const name = (origin as { name?: unknown } | undefined)?.name;
+    return name === 'goal_continuation' || name === 'subagent';
+  }
+  if (kind === 'skill_activation' || kind === 'plugin_command') {
+    return (origin as { trigger?: unknown } | undefined)?.trigger === 'user-slash';
+  }
+  if (kind === 'injection' || kind === 'retry' || kind === 'compaction_summary') return false;
+  // user / cron / task / hook / shell_command / unknown kinds open visible turns.
+  return true;
+}
+
 /** Engine task kinds (`AgentTaskInfoByKind`: process / agent / question) → transcript kinds. */
 function mapTaskKind(kind: unknown): TranscriptTask['kind'] {
   switch (kind) {
@@ -210,6 +243,22 @@ export function foldWireRecordFacts(
   const interactions = new Map<string, TranscriptInteraction>();
   /** Latest `turn.ended` record per engine turn id (last-wins). */
   const endedTurns = new Map<number, HistoryWireRecord>();
+  /**
+   * Turn-clock replay (mirrors the loop's TurnModel): engine turn ids are
+   * assigned to `turn.prompt` records in order, skipping queued-then-
+   * cancelled reservations. Turns whose origin opens no visible transcript
+   * item (retry turns) make engine ids drift from the grouping ordinals.
+   */
+  let nextTurnId = 0;
+  const cancelledTurnIds = new Set<number>();
+  const hiddenTurnIds = new Set<number>();
+  const skipCancelledTurnIds = (): void => {
+    // A skipped reservation never starts: no prompt, no messages, no item.
+    while (cancelledTurnIds.delete(nextTurnId)) {
+      hiddenTurnIds.add(nextTurnId);
+      nextTurnId += 1;
+    }
+  };
   let todo: TranscriptTodo | undefined;
   let goal: GoalMeta | undefined;
   let goalTouched = false;
@@ -421,6 +470,25 @@ export function foldWireRecordFacts(
         if (typeof payload.turnId === 'number') endedTurns.set(payload.turnId, record);
         break;
       }
+      case 'turn.prompt': {
+        skipCancelledTurnIds();
+        const turnId = nextTurnId;
+        nextTurnId += 1;
+        if (!isVisibleTurnOrigin((record as TurnPromptPayload).origin)) hiddenTurnIds.add(turnId);
+        break;
+      }
+      case 'turn.cancel': {
+        const payload = record as TurnCancelPayload;
+        if (
+          payload.target === 'queued' &&
+          typeof payload.turnId === 'number' &&
+          payload.turnId >= nextTurnId
+        ) {
+          cancelledTurnIds.add(payload.turnId);
+          skipCancelledTurnIds();
+        }
+        break;
+      }
       default:
         break;
     }
@@ -434,15 +502,27 @@ export function foldWireRecordFacts(
     }
   }
 
-  // `turn.ended` records rewrite the matching base turn items (the engine's
-  // 0-based turn id aligns with the grouping ordinal — see groupTurns).
-  // Unmatched ids are ignored: grouping can drift when hidden origins consume
-  // engine turns the fold cannot see.
+  // `turn.ended` records rewrite the matching base turn items. An engine
+  // turn id maps to the grouping ordinal `id - (hidden ids below it)`:
+  // hidden turns (retry turns, queued-then-cancelled reservations) consume
+  // an engine id without opening a visible item. Their own end records map
+  // nowhere and are dropped; ids with no matching item are ignored (e.g.
+  // turns compacted out of the message history). One residual gap,
+  // accepted: a turn that ends between `turn.prompt` and its first context
+  // message leaves no message trace and still shifts the ordinals behind it.
+  const endedByOrdinal = new Map<number, HistoryWireRecord>();
+  for (const [turnId, record] of endedTurns) {
+    if (hiddenTurnIds.has(turnId)) continue;
+    let hidden = 0;
+    for (const id of hiddenTurnIds) if (id < turnId) hidden += 1;
+    endedByOrdinal.set(turnId - hidden, record);
+  }
+
   const items =
-    endedTurns.size > 0
+    endedByOrdinal.size > 0
       ? base.items.map((item) => {
           if (item.kind !== 'turn') return item;
-          const record = endedTurns.get(item.ordinal);
+          const record = endedByOrdinal.get(item.ordinal);
           if (record === undefined) return item;
           const payload = record as TurnEndedPayload;
           return {
diff --git a/packages/transcript/test/layers.test.ts b/packages/transcript/test/layers.test.ts
index c5155384f3..08f0a1ec3e 100644
--- a/packages/transcript/test/layers.test.ts
+++ b/packages/transcript/test/layers.test.ts
@@ -1107,4 +1107,63 @@ describe('foldWireRecordFacts (cold facts)', () => {
     expect(turn.endedAt).toBe(new Date(3000).toISOString());
     expect(folded.items).toHaveLength(base.items.length);
   });
+
+  it('maps turn.ended around hidden retry turns replayed from the turn-clock records', () => {
+    // Engine turns: 0 = user "one", 1 = retry (hidden — a real newTurn with
+    // no context messages), 2 = user "two". The base grouping sees only the
+    // two user turns, ordinals 0 and 1.
+    const base = groupMessagesIntoSnapshot([
+      { role: 'user', content: [{ type: 'text', text: 'one' }], toolCalls: [], origin: { kind: 'user' } },
+      { role: 'assistant', content: [{ type: 'text', text: 'a1' }], toolCalls: [] },
+      { role: 'user', content: [{ type: 'text', text: 'two' }], toolCalls: [], origin: { kind: 'user' } },
+      { role: 'assistant', content: [{ type: 'text', text: 'a2' }], toolCalls: [] },
+    ]);
+    const folded = foldWireRecordFacts(
+      [
+        { type: 'turn.prompt', input: [{ type: 'text', text: 'one' }], origin: { kind: 'user' }, time: 1 },
+        { type: 'turn.ended', turnId: 0, reason: 'completed', time: 2 },
+        { type: 'turn.prompt', input: [], origin: { kind: 'retry' }, time: 3 },
+        { type: 'turn.ended', turnId: 1, reason: 'failed', error: { message: 'retry boom' }, time: 4 },
+        { type: 'turn.prompt', input: [{ type: 'text', text: 'two' }], origin: { kind: 'user' }, time: 5 },
+        { type: 'turn.ended', turnId: 2, reason: 'cancelled', durationMs: 20, time: 6 },
+      ],
+      base,
+    );
+    const first = folded.items[0];
+    if (first?.kind !== 'turn') throw new Error('expected turn');
+    expect(first.state).toBe('completed');
+    const second = folded.items[1];
+    if (second?.kind !== 'turn') throw new Error('expected turn');
+    // The retry's failed/error must NOT bleed into the later user turn —
+    // it gets its own record (turnId 2 → ordinal 1).
+    expect(second.state).toBe('cancelled');
+    expect(second.error).toBeUndefined();
+    expect(second.durationMs).toBe(20);
+  });
+
+  it('maps turn.ended across queued-then-cancelled turn reservations', () => {
+    // Engine turns: 0 = user "one", 1 = reserved then cancelled while queued
+    // (never started, no prompt, no messages), 2 = user "two".
+    const base = groupMessagesIntoSnapshot([
+      { role: 'user', content: [{ type: 'text', text: 'one' }], toolCalls: [], origin: { kind: 'user' } },
+      { role: 'assistant', content: [{ type: 'text', text: 'a1' }], toolCalls: [] },
+      { role: 'user', content: [{ type: 'text', text: 'two' }], toolCalls: [], origin: { kind: 'user' } },
+      { role: 'assistant', content: [{ type: 'text', text: 'a2' }], toolCalls: [] },
+    ]);
+    const folded = foldWireRecordFacts(
+      [
+        { type: 'turn.prompt', input: [{ type: 'text', text: 'one' }], origin: { kind: 'user' }, time: 1 },
+        { type: 'turn.ended', turnId: 0, reason: 'completed', time: 2 },
+        { type: 'turn.cancel', turnId: 1, target: 'queued', time: 3 },
+        { type: 'turn.prompt', input: [{ type: 'text', text: 'two' }], origin: { kind: 'user' }, time: 4 },
+        { type: 'turn.ended', turnId: 2, reason: 'failed', error: { message: 'boom' }, time: 5 },
+      ],
+      base,
+    );
+    const second = folded.items[1];
+    if (second?.kind !== 'turn') throw new Error('expected turn');
+    // turnId 2 maps past the cancelled reservation onto ordinal 1.
+    expect(second.state).toBe('failed');
+    expect(second.error).toBe('boom');
+  });
 });