Merge remote-tracking branch 'origin/master' into fix/stats

scripts/gen-doc-graphs.ts

@@ -1195,7 +1195,7 @@ function renderLifecycle(): string {
   const maintenance = 'curated Mermaid sequence; exact event signatures live in the generated Cordis catalog'
   return [
     ...generatedHeader('Agent Turn And Step Lifecycle'),
-    'This sequence is the visual companion to [architecture.md](architecture.md#default-loop-lifecycle). It keeps durable replay facts on `session/event` and live control/status on `agent/*`.',
+    'This sequence is the visual companion to [architecture.md](architecture.md#turn-flow). It keeps durable replay facts on `session/event` and live control/status on `agent/*`.',
     '',
     '```mermaid',
     'sequenceDiagram',
@@ -1213,15 +1213,15 @@ function renderLifecycle(): string {
     `  Agent-->>SDK: ${mermaidCode('agent/inbox/inserted')} { message }`,
     '  Agent->>Driver: queued work wakes driver',
     `  Driver-->>SDK: ${mermaidCode('agent/status')} running`,
+    `  Driver->>Session: ${mermaidCode('turn/start')}`,
     '  Note over Agent,Driver: claim pending next-step input plus one queued prompt',
     `  Driver-->>SDK: ${mermaidCode('agent/inbox/spliced')} pure deletion`,
     `  Driver-->>SDK: ${mermaidCode('agent/inbox/claimed')} { message, turn } per message`,
     `  Driver->>Hooks: ${mermaidCode('agent/pre-step')} waterfall`,
     '  Hooks-->>Driver: authoritative reject or enter(messages)',
     '  alt proposed step rejected or pre-step failed',
-    '    Driver-->>Driver: claimed batch stays removed, no turn opens',
+    '    Driver-->>Driver: claimed batch stays removed, the open turn spends no step',
     '  else enter proposed step',
-    `  Driver->>Session: ${mermaidCode('turn/start')}`,
     `  Driver->>Session: ${mermaidCode('step/start')}`,
     `  Driver->>Session: ${mermaidCode('user/message')} per entered message`,
     `  Driver->>Prompt: ${mermaidCode('system-prompt/assemble')} waterfall`,
@@ -1258,8 +1258,8 @@ function renderLifecycle(): string {
     '    Hooks-->>Driver: authoritative reject or enter(messages)',
     '  end',
     '  end',
-    `  Driver->>Session: ${mermaidCode('turn/end')}`,
     '  end',
+    `  Driver->>Session: ${mermaidCode('turn/end')}`,
     `  Driver-->>SDK: ${mermaidCode('agent/status')} idle`,
     '```',
     '',