@genesislcap/ai-assistant 15.84.2 → 15.85.0-FUI-2666.2

package/dist/custom-elements.json

@@ -2965,6 +2965,126 @@
                 "module": "src/components/ai-driver/base-driver-decorator.ts"
               }
             },
+            {
+              "kind": "method",
+              "name": "getHandOffStack",
+              "return": {
+                "type": {
+                  "text": "HandOffFrame[]"
+                }
+              },
+              "inheritedFrom": {
+                "name": "BaseDriverDecorator",
+                "module": "src/components/ai-driver/base-driver-decorator.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "restoreHandOffStack",
+              "return": {
+                "type": {
+                  "text": "{ resume?: { agent: string; note: string }; droppedLocks?: string[] }"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "saved",
+                  "type": {
+                    "text": "unknown"
+                  }
+                },
+                {
+                  "name": "savedStates",
+                  "type": {
+                    "text": "Record<string, unknown>"
+                  }
+                },
+                {
+                  "name": "interrupted",
+                  "type": {
+                    "text": "boolean"
+                  }
+                }
+              ],
+              "inheritedFrom": {
+                "name": "BaseDriverDecorator",
+                "module": "src/components/ai-driver/base-driver-decorator.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "unwindHandOffs",
+              "return": {
+                "type": {
+                  "text": "Promise<void>"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "kind",
+                  "type": {
+                    "text": "Extract<HandOffOutcomeKind, 'cleared' | 'state-lost'>"
+                  }
+                }
+              ],
+              "inheritedFrom": {
+                "name": "BaseDriverDecorator",
+                "module": "src/components/ai-driver/base-driver-decorator.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "serializeWaitingCallers",
+              "return": {
+                "type": {
+                  "text": "Record<string, unknown>"
+                }
+              },
+              "inheritedFrom": {
+                "name": "BaseDriverDecorator",
+                "module": "src/components/ai-driver/base-driver-decorator.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "getHandOffData",
+              "return": {
+                "type": {
+                  "text": "Record<string, unknown>"
+                }
+              },
+              "inheritedFrom": {
+                "name": "BaseDriverDecorator",
+                "module": "src/components/ai-driver/base-driver-decorator.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "restoreHandOffData",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "saved",
+                  "type": {
+                    "text": "unknown"
+                  }
+                },
+                {
+                  "name": "interrupted",
+                  "type": {
+                    "text": "boolean"
+                  }
+                }
+              ],
+              "inheritedFrom": {
+                "name": "BaseDriverDecorator",
+                "module": "src/components/ai-driver/base-driver-decorator.ts"
+              }
+            },
             {
               "kind": "method",
               "name": "getActiveAgent",
@@ -4824,202 +4944,247 @@
     },
     {
       "kind": "javascript-module",
-      "path": "src/components/flowing-waves-indicator.ts",
+      "path": "src/config/config.ts",
       "declarations": [
         {
-          "kind": "class",
-          "description": "Animated \"flowing waves\" loading indicator — coloured organic waves (in the\nfour brand colours) whose bumps swell, shrink, merge and split across a line,\ntapering to nothing at both ends. Where the colours overlap they blend\nadditively toward white.\n\nVisual sibling of the dots loading indicator; interchangeable with the other\nloading styles for the \"assistant is working\" state.",
-          "name": "AiFlowingWavesIndicator",
-          "members": [
-            {
-              "kind": "field",
-              "name": "startTime",
-              "type": {
-                "text": "number | undefined"
-              },
-              "privacy": "private"
-            },
-            {
-              "kind": "field",
-              "name": "animFrame",
-              "type": {
-                "text": "number | undefined"
-              },
-              "privacy": "private"
-            },
-            {
-              "kind": "field",
-              "name": "bandPaths",
-              "type": {
-                "text": "SVGPathElement[] | undefined"
-              },
-              "privacy": "private"
-            },
-            {
-              "kind": "method",
-              "name": "tick",
-              "privacy": "private",
-              "parameters": [
-                {
-                  "name": "now",
-                  "optional": true,
-                  "type": {
-                    "text": "number"
-                  }
-                }
-              ]
-            },
-            {
-              "kind": "method",
-              "name": "buildBand",
-              "privacy": "private",
-              "static": true,
-              "return": {
-                "type": {
-                  "text": "string"
-                }
-              },
-              "parameters": [
-                {
-                  "name": "cfg",
-                  "type": {
-                    "text": "BandConfig"
-                  }
-                },
-                {
-                  "name": "frame",
-                  "type": {
-                    "text": "number"
-                  }
-                }
-              ],
-              "description": "Trace one band for the given frame: a baseline-plus-harmonics half-thickness\nprofile, clamped at 0 (so the band pinches to nothing between bumps) and\ntapered to 0 at both ends."
-            }
-          ],
-          "superclass": {
-            "name": "GenesisElement",
-            "package": "@genesislcap/web-core"
-          },
-          "tagName": "ai-flowing-waves-indicator",
-          "customElement": true
+          "kind": "function",
+          "name": "defineAgent",
+          "description": "Identity helper that infers the narrowest possible type for an agent config,\npreserving string literal types (including `name`) without requiring `as const`.\n\nUse this when you need `typeof myAgent` to carry the literal `name` type —\nfor example, when wiring `ChatToolHandlers<typeof myAgent>`.\n\n```ts\nconst myAgent = defineAgent({ name: 'my_agent', ... });\ntype Handlers = ChatToolHandlers<typeof myAgent>;\n// requestSubAgent name param is now typed as 'my_agent'\n```"
         }
       ],
       "exports": [
         {
           "kind": "js",
-          "name": "AiFlowingWavesIndicator",
+          "name": "CachePolicy",
           "declaration": {
-            "name": "AiFlowingWavesIndicator",
-            "module": "src/components/flowing-waves-indicator.ts"
+            "name": "CachePolicy",
+            "module": "src/config/config.ts"
           }
         },
         {
-          "kind": "custom-element-definition",
-          "name": "ai-flowing-waves-indicator",
+          "kind": "js",
+          "name": "ChatFallback",
           "declaration": {
-            "name": "AiFlowingWavesIndicator",
-            "module": "src/components/flowing-waves-indicator.ts"
+            "name": "ChatFallback",
+            "module": "src/config/config.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "ChatInputDuringExecutionMode",
+          "declaration": {
+            "name": "ChatInputDuringExecutionMode",
+            "module": "src/config/config.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "ChatThinkingPolicy",
+          "declaration": {
+            "name": "ChatThinkingPolicy",
+            "module": "src/config/config.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "ChatToolChoice",
+          "declaration": {
+            "name": "ChatToolChoice",
+            "module": "src/config/config.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "defineAgent",
+          "declaration": {
+            "name": "defineAgent",
+            "module": "src/config/config.ts"
           }
         }
       ]
     },
     {
       "kind": "javascript-module",
-      "path": "src/components/halo-overlay.ts",
+      "path": "src/config/define-stateful-agent.ts",
       "declarations": [
         {
-          "kind": "class",
-          "description": "Animated halo overlay — rotating conic-gradient border with an inward glow.\n\nDrop inside any `position: relative; overflow: hidden` container and toggle\nthe `active` attribute to show/hide the effect.",
-          "name": "AiHaloOverlay",
-          "members": [
+          "kind": "function",
+          "name": "restoreMachine",
+          "return": {
+            "type": {
+              "text": "void"
+            }
+          },
+          "parameters": [
             {
-              "kind": "field",
-              "name": "active",
+              "name": "machine",
               "type": {
-                "text": "boolean"
+                "text": "{ stop: () => void; start: (options?: { state?: unknown }) => void }"
               },
-              "default": "false"
+              "description": "the machine to restore (already constructed/started)."
             },
             {
-              "kind": "field",
-              "name": "speed",
+              "name": "restored",
               "type": {
-                "text": "number"
-              },
-              "default": "1.5",
-              "description": "Rotation speed in degrees per frame. Default: 1.5 (≈ 4 s per full revolution at 60 fps)."
-            },
-            {
-              "kind": "field",
-              "name": "direction",
-              "type": {
-                "text": "'cw' | 'ccw'"
-              },
-              "default": "'cw'",
-              "description": "Rotation direction. Default: 'cw' (clockwise)."
-            },
-            {
-              "kind": "field",
-              "name": "borderSize",
-              "type": {
-                "text": "number"
-              },
-              "default": "3",
-              "description": "Border thickness in px. Default: 3."
-            },
-            {
-              "kind": "field",
-              "name": "glowOpacity",
-              "type": {
-                "text": "number"
-              },
-              "default": "0.35",
-              "description": "Glow layer opacity (0–1). Default: 0.35."
-            },
-            {
-              "kind": "field",
-              "name": "glowSpread",
-              "type": {
-                "text": "number"
+                "text": "unknown"
               },
-              "default": "70",
-              "description": "Transparent stop of the radial glow mask as a percentage (0–100). Higher = less spread. Default: 70."
-            },
-            {
-              "kind": "method",
-              "name": "borderSizeChanged"
-            },
-            {
-              "kind": "method",
-              "name": "glowOpacityChanged"
+              "description": "the agent's serialized image (`ctx.restored` in `init`)."
             },
             {
-              "kind": "method",
-              "name": "glowSpreadChanged"
-            },
+              "name": "key",
+              "default": "'machine'",
+              "description": "the property the machine occupies in the snapshot; defaults to\n`'machine'` to match the conventional `{ machine }` state bag."
+            }
+          ],
+          "description": "Restore a foundation-state-machine instance from a snapshot produced by the\ndefault serializer (or `machine.getPersistedSnapshot()`). Call inside a\nstateful agent's `init` to resume the machine in its exact prior place:\n\n```ts\ninit: ({ restored }) => {\n  const machine = new MyMachine();\n  restoreMachine(machine, restored); // resume, or no-op on a fresh start\n  return { machine };\n}\n```\n\nNo-ops when there is nothing to restore (a fresh session), leaving the\nfreshly-constructed machine in its initial state."
+        },
+        {
+          "kind": "function",
+          "name": "defineStatefulAgent",
+          "return": {
+            "type": {
+              "text": "AgentConfig"
+            }
+          },
+          "parameters": [
             {
-              "kind": "field",
-              "name": "FULL_ROTATION_DEG",
+              "name": "opts",
               "type": {
-                "text": "number"
-              },
-              "privacy": "private",
-              "static": true,
-              "readonly": true,
-              "default": "360"
-            },
+                "text": "StatefulAgentInit<S>"
+              }
+            }
+          ],
+          "description": "Build an `AgentConfig` whose `systemPrompt`, `toolDefinitions`, and tool\nhandlers all close over a long-lived state object created on activation.\n\nThe framework wires the lifecycle: `init` on `onActivate`, `dispose` on\n`onDeactivate`. State is held inside the helper's closure — never exposed on\nthe resulting `AgentConfig` — so the redux serializer doesn't see it."
+        },
+        {
+          "kind": "function",
+          "name": "defineAutopilot",
+          "return": {
+            "type": {
+              "text": "AutopilotConfig<S>"
+            }
+          },
+          "parameters": [
             {
-              "kind": "field",
-              "name": "angle",
+              "name": "config",
               "type": {
-                "text": "number"
-              },
-              "privacy": "private",
-              "default": "0"
-            },
+                "text": "AutopilotConfig<S>"
+              }
+            }
+          ],
+          "description": "Define an autopilot for a stateful agent whose state is `S` (GENC-1660). An identity function\nthat exists for its type: the resolvers get `S`, and the result goes on `defineStatefulAgent`'s\n`autopilot` option."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "restoreMachine",
+          "declaration": {
+            "name": "restoreMachine",
+            "module": "src/config/define-stateful-agent.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "defineStatefulAgent",
+          "declaration": {
+            "name": "defineStatefulAgent",
+            "module": "src/config/define-stateful-agent.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "defineAutopilot",
+          "declaration": {
+            "name": "defineAutopilot",
+            "module": "src/config/define-stateful-agent.ts"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/config/fallback-agents.ts",
+      "declarations": [
+        {
+          "kind": "variable",
+          "name": "friendlyFallbackAgent",
+          "type": {
+            "text": "FallbackAgentConfig"
+          },
+          "default": "{\n  name: 'Assistant',\n  fallback: true,\n  systemPrompt: `You are a warm, friendly assistant. For general conversation like \"Hi\" or \"How are you\", you can have a friendly chat. For anything more complex, you cannot directly help, but you can explain what specialists are available. The available specialists are:\\n\\n{{agents}}\\n\\nPolitely let the user know what you can help with and invite them to rephrase their request if it is outside your scope.`,\n}",
+          "description": "A warm, conversational fallback agent. Acknowledges it can't help directly,\nexplains what the available specialists can do, and invites the user to retry.\n\nThe system prompt is generated at runtime by `OrchestratingDriver` from the\nspecialist list — no manual authoring required."
+        },
+        {
+          "kind": "variable",
+          "name": "strictFallbackAgent",
+          "type": {
+            "text": "FallbackAgentConfig"
+          },
+          "default": "{\n  name: 'Assistant',\n  fallback: true,\n  systemPrompt: `You are a concise assistant. The user's request is outside your scope. The available specialists are: {{agents}}.\n\n{{unroutable}}\n\nAnswer in a single short sentence. Do not elaborate.`,\n}",
+          "description": "A brief, professional fallback agent. States what is available without\nelaboration. The `{{agents}}` placeholder is replaced at runtime by\n`OrchestratingDriver` with the generated specialist list.\n\nThe `{{unroutable}}` placeholder positions `UNROUTABLE_INSTRUCTION` — the framework's\ninstruction for a substantive request no specialist covers, which is otherwise APPENDED to a\nstring-form prompt. Positioned rather than appended for one reason: this preset's whole point is\nbrevity, and appended text would be the last thing the model reads. Putting the block above the\nbrevity rule leaves \"a single short sentence\" with the recency, so the two compose instead of\ncompeting. A prompt whose tone rules matter should do the same."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "friendlyFallbackAgent",
+          "declaration": {
+            "name": "friendlyFallbackAgent",
+            "module": "src/config/fallback-agents.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "strictFallbackAgent",
+          "declaration": {
+            "name": "strictFallbackAgent",
+            "module": "src/config/fallback-agents.ts"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/config/index.ts",
+      "declarations": [],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "*",
+          "declaration": {
+            "name": "*",
+            "package": "./config"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "*",
+          "declaration": {
+            "name": "*",
+            "package": "./fallback-agents"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/config/validate-providers.ts",
+      "declarations": [],
+      "exports": []
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/components/flowing-waves-indicator.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "Animated \"flowing waves\" loading indicator — coloured organic waves (in the\nfour brand colours) whose bumps swell, shrink, merge and split across a line,\ntapering to nothing at both ends. Where the colours overlap they blend\nadditively toward white.\n\nVisual sibling of the dots loading indicator; interchangeable with the other\nloading styles for the \"assistant is working\" state.",
+          "name": "AiFlowingWavesIndicator",
+          "members": [
             {
               "kind": "field",
-              "name": "lastTime",
+              "name": "startTime",
               "type": {
                 "text": "number | undefined"
               },
@@ -5035,43 +5200,229 @@
             },
             {
               "kind": "field",
-              "name": "stopTimer",
-              "type": {
-                "text": "number | undefined"
-              },
-              "privacy": "private"
-            },
-            {
-              "kind": "field",
-              "name": "running",
+              "name": "bandPaths",
               "type": {
-                "text": "boolean"
+                "text": "SVGPathElement[] | undefined"
               },
-              "privacy": "private",
-              "default": "false",
-              "description": "Whether the loop should keep rescheduling itself — see AiHaloOverlay.tick."
-            },
-            {
-              "kind": "method",
-              "name": "activeChanged",
-              "description": "Start/stop with `active`, so an idle overlay costs nothing.\n\nGuarded on `isConnected` because FAST invokes attribute-changed callbacks during\ninitialisation, before the element is in the document — `connectedCallback` is what decides\nfor an element that mounts already-active."
-            },
-            {
-              "kind": "method",
-              "name": "startAnimation",
               "privacy": "private"
             },
             {
               "kind": "method",
-              "name": "scheduleStop",
+              "name": "tick",
               "privacy": "private",
-              "description": "Keep spinning until the host has finished fading out.\n\nDeactivating only drops the host's opacity — the overlay is still on screen for the length of\nthe transition, so stopping the instant `active` flips would freeze the rotation mid-fade.\n\nTimed rather than driven by `transitionend`, which never fires if the host is hidden or an app\noverrides the transition away, and a stop that never arrives is exactly the idle-tick bug this\ngating exists to prevent.\n\nThe timer re-reads `active` rather than trusting that it was cancelled. FAST reflects the\nproperty to the attribute on a queued update, so `activeChanged` can run again, out of order,\nafter a rapid toggle — and a stale stop landing on a re-activated overlay would leave it\nfrozen for good, which is worse than the idle ticking this gate removes."
+              "parameters": [
+                {
+                  "name": "now",
+                  "optional": true,
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ]
             },
             {
               "kind": "method",
-              "name": "cancelPendingStop",
-              "privacy": "private"
-            },
+              "name": "buildBand",
+              "privacy": "private",
+              "static": true,
+              "return": {
+                "type": {
+                  "text": "string"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "cfg",
+                  "type": {
+                    "text": "BandConfig"
+                  }
+                },
+                {
+                  "name": "frame",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "Trace one band for the given frame: a baseline-plus-harmonics half-thickness\nprofile, clamped at 0 (so the band pinches to nothing between bumps) and\ntapered to 0 at both ends."
+            }
+          ],
+          "superclass": {
+            "name": "GenesisElement",
+            "package": "@genesislcap/web-core"
+          },
+          "tagName": "ai-flowing-waves-indicator",
+          "customElement": true
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "AiFlowingWavesIndicator",
+          "declaration": {
+            "name": "AiFlowingWavesIndicator",
+            "module": "src/components/flowing-waves-indicator.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "ai-flowing-waves-indicator",
+          "declaration": {
+            "name": "AiFlowingWavesIndicator",
+            "module": "src/components/flowing-waves-indicator.ts"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/components/halo-overlay.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "Animated halo overlay — rotating conic-gradient border with an inward glow.\n\nDrop inside any `position: relative; overflow: hidden` container and toggle\nthe `active` attribute to show/hide the effect.",
+          "name": "AiHaloOverlay",
+          "members": [
+            {
+              "kind": "field",
+              "name": "active",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false"
+            },
+            {
+              "kind": "field",
+              "name": "speed",
+              "type": {
+                "text": "number"
+              },
+              "default": "1.5",
+              "description": "Rotation speed in degrees per frame. Default: 1.5 (≈ 4 s per full revolution at 60 fps)."
+            },
+            {
+              "kind": "field",
+              "name": "direction",
+              "type": {
+                "text": "'cw' | 'ccw'"
+              },
+              "default": "'cw'",
+              "description": "Rotation direction. Default: 'cw' (clockwise)."
+            },
+            {
+              "kind": "field",
+              "name": "borderSize",
+              "type": {
+                "text": "number"
+              },
+              "default": "3",
+              "description": "Border thickness in px. Default: 3."
+            },
+            {
+              "kind": "field",
+              "name": "glowOpacity",
+              "type": {
+                "text": "number"
+              },
+              "default": "0.35",
+              "description": "Glow layer opacity (0–1). Default: 0.35."
+            },
+            {
+              "kind": "field",
+              "name": "glowSpread",
+              "type": {
+                "text": "number"
+              },
+              "default": "70",
+              "description": "Transparent stop of the radial glow mask as a percentage (0–100). Higher = less spread. Default: 70."
+            },
+            {
+              "kind": "method",
+              "name": "borderSizeChanged"
+            },
+            {
+              "kind": "method",
+              "name": "glowOpacityChanged"
+            },
+            {
+              "kind": "method",
+              "name": "glowSpreadChanged"
+            },
+            {
+              "kind": "field",
+              "name": "FULL_ROTATION_DEG",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "static": true,
+              "readonly": true,
+              "default": "360"
+            },
+            {
+              "kind": "field",
+              "name": "angle",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "0"
+            },
+            {
+              "kind": "field",
+              "name": "lastTime",
+              "type": {
+                "text": "number | undefined"
+              },
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "animFrame",
+              "type": {
+                "text": "number | undefined"
+              },
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "stopTimer",
+              "type": {
+                "text": "number | undefined"
+              },
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "running",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false",
+              "description": "Whether the loop should keep rescheduling itself — see AiHaloOverlay.tick."
+            },
+            {
+              "kind": "method",
+              "name": "activeChanged",
+              "description": "Start/stop with `active`, so an idle overlay costs nothing.\n\nGuarded on `isConnected` because FAST invokes attribute-changed callbacks during\ninitialisation, before the element is in the document — `connectedCallback` is what decides\nfor an element that mounts already-active."
+            },
+            {
+              "kind": "method",
+              "name": "startAnimation",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "scheduleStop",
+              "privacy": "private",
+              "description": "Keep spinning until the host has finished fading out.\n\nDeactivating only drops the host's opacity — the overlay is still on screen for the length of\nthe transition, so stopping the instant `active` flips would freeze the rotation mid-fade.\n\nTimed rather than driven by `transitionend`, which never fires if the host is hidden or an app\noverrides the transition away, and a stop that never arrives is exactly the idle-tick bug this\ngating exists to prevent.\n\nThe timer re-reads `active` rather than trusting that it was cancelled. FAST reflects the\nproperty to the attribute on a queued update, so `activeChanged` can run again, out of order,\nafter a rapid toggle — and a stale stop landing on a re-activated overlay would leave it\nfrozen for good, which is worse than the idle ticking this gate removes."
+            },
+            {
+              "kind": "method",
+              "name": "cancelPendingStop",
+              "privacy": "private"
+            },
             {
               "kind": "method",
               "name": "stopAnimation",
@@ -5348,261 +5699,30 @@
     },
     {
       "kind": "javascript-module",
-      "path": "src/config/config.ts",
+      "path": "src/genesis/calendar.ts",
+      "declarations": [],
+      "exports": []
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/genesis/config.ts",
       "declarations": [
         {
-          "kind": "function",
-          "name": "defineAgent",
-          "description": "Identity helper that infers the narrowest possible type for an agent config,\npreserving string literal types (including `name`) without requiring `as const`.\n\nUse this when you need `typeof myAgent` to carry the literal `name` type —\nfor example, when wiring `ChatToolHandlers<typeof myAgent>`.\n\n```ts\nconst myAgent = defineAgent({ name: 'my_agent', ... });\ntype Handlers = ChatToolHandlers<typeof myAgent>;\n// requestSubAgent name param is now typed as 'my_agent'\n```"
-        }
-      ],
-      "exports": [
-        {
-          "kind": "js",
-          "name": "CachePolicy",
-          "declaration": {
-            "name": "CachePolicy",
-            "module": "src/config/config.ts"
-          }
-        },
-        {
-          "kind": "js",
-          "name": "ChatFallback",
-          "declaration": {
-            "name": "ChatFallback",
-            "module": "src/config/config.ts"
-          }
+          "kind": "variable",
+          "name": "DEFAULT_MAX_ROWS",
+          "type": {
+            "text": "number"
+          },
+          "default": "50",
+          "description": "The default read cap, and the ceiling the config may raise it to."
         },
         {
-          "kind": "js",
-          "name": "ChatInputDuringExecutionMode",
-          "declaration": {
-            "name": "ChatInputDuringExecutionMode",
-            "module": "src/config/config.ts"
-          }
-        },
-        {
-          "kind": "js",
-          "name": "ChatThinkingPolicy",
-          "declaration": {
-            "name": "ChatThinkingPolicy",
-            "module": "src/config/config.ts"
-          }
-        },
-        {
-          "kind": "js",
-          "name": "ChatToolChoice",
-          "declaration": {
-            "name": "ChatToolChoice",
-            "module": "src/config/config.ts"
-          }
-        },
-        {
-          "kind": "js",
-          "name": "defineAgent",
-          "declaration": {
-            "name": "defineAgent",
-            "module": "src/config/config.ts"
-          }
-        }
-      ]
-    },
-    {
-      "kind": "javascript-module",
-      "path": "src/config/define-stateful-agent.ts",
-      "declarations": [
-        {
-          "kind": "function",
-          "name": "restoreMachine",
-          "return": {
-            "type": {
-              "text": "void"
-            }
-          },
-          "parameters": [
-            {
-              "name": "machine",
-              "type": {
-                "text": "{ stop: () => void; start: (options?: { state?: unknown }) => void }"
-              },
-              "description": "the machine to restore (already constructed/started)."
-            },
-            {
-              "name": "restored",
-              "type": {
-                "text": "unknown"
-              },
-              "description": "the agent's serialized image (`ctx.restored` in `init`)."
-            },
-            {
-              "name": "key",
-              "default": "'machine'",
-              "description": "the property the machine occupies in the snapshot; defaults to\n`'machine'` to match the conventional `{ machine }` state bag."
-            }
-          ],
-          "description": "Restore a foundation-state-machine instance from a snapshot produced by the\ndefault serializer (or `machine.getPersistedSnapshot()`). Call inside a\nstateful agent's `init` to resume the machine in its exact prior place:\n\n```ts\ninit: ({ restored }) => {\n  const machine = new MyMachine();\n  restoreMachine(machine, restored); // resume, or no-op on a fresh start\n  return { machine };\n}\n```\n\nNo-ops when there is nothing to restore (a fresh session), leaving the\nfreshly-constructed machine in its initial state."
-        },
-        {
-          "kind": "function",
-          "name": "defineStatefulAgent",
-          "return": {
-            "type": {
-              "text": "AgentConfig"
-            }
-          },
-          "parameters": [
-            {
-              "name": "opts",
-              "type": {
-                "text": "StatefulAgentInit<S>"
-              }
-            }
-          ],
-          "description": "Build an `AgentConfig` whose `systemPrompt`, `toolDefinitions`, and tool\nhandlers all close over a long-lived state object created on activation.\n\nThe framework wires the lifecycle: `init` on `onActivate`, `dispose` on\n`onDeactivate`. State is held inside the helper's closure — never exposed on\nthe resulting `AgentConfig` — so the redux serializer doesn't see it."
-        },
-        {
-          "kind": "function",
-          "name": "defineAutopilot",
-          "return": {
-            "type": {
-              "text": "AutopilotConfig<S>"
-            }
-          },
-          "parameters": [
-            {
-              "name": "config",
-              "type": {
-                "text": "AutopilotConfig<S>"
-              }
-            }
-          ],
-          "description": "Define an autopilot for a stateful agent whose state is `S` (GENC-1660). An identity function\nthat exists for its type: the resolvers get `S`, and the result goes on `defineStatefulAgent`'s\n`autopilot` option."
-        }
-      ],
-      "exports": [
-        {
-          "kind": "js",
-          "name": "restoreMachine",
-          "declaration": {
-            "name": "restoreMachine",
-            "module": "src/config/define-stateful-agent.ts"
-          }
-        },
-        {
-          "kind": "js",
-          "name": "defineStatefulAgent",
-          "declaration": {
-            "name": "defineStatefulAgent",
-            "module": "src/config/define-stateful-agent.ts"
-          }
-        },
-        {
-          "kind": "js",
-          "name": "defineAutopilot",
-          "declaration": {
-            "name": "defineAutopilot",
-            "module": "src/config/define-stateful-agent.ts"
-          }
-        }
-      ]
-    },
-    {
-      "kind": "javascript-module",
-      "path": "src/config/fallback-agents.ts",
-      "declarations": [
-        {
-          "kind": "variable",
-          "name": "friendlyFallbackAgent",
-          "type": {
-            "text": "FallbackAgentConfig"
-          },
-          "default": "{\n  name: 'Assistant',\n  fallback: true,\n  systemPrompt: `You are a warm, friendly assistant. For general conversation like \"Hi\" or \"How are you\", you can have a friendly chat. For anything more complex, you cannot directly help, but you can explain what specialists are available. The available specialists are:\\n\\n{{agents}}\\n\\nPolitely let the user know what you can help with and invite them to rephrase their request if it is outside your scope.`,\n}",
-          "description": "A warm, conversational fallback agent. Acknowledges it can't help directly,\nexplains what the available specialists can do, and invites the user to retry.\n\nThe system prompt is generated at runtime by `OrchestratingDriver` from the\nspecialist list — no manual authoring required."
-        },
-        {
-          "kind": "variable",
-          "name": "strictFallbackAgent",
-          "type": {
-            "text": "FallbackAgentConfig"
-          },
-          "default": "{\n  name: 'Assistant',\n  fallback: true,\n  systemPrompt: `You are a concise assistant. The user's request is outside your scope. The available specialists are: {{agents}}.\n\n{{unroutable}}\n\nAnswer in a single short sentence. Do not elaborate.`,\n}",
-          "description": "A brief, professional fallback agent. States what is available without\nelaboration. The `{{agents}}` placeholder is replaced at runtime by\n`OrchestratingDriver` with the generated specialist list.\n\nThe `{{unroutable}}` placeholder positions `UNROUTABLE_INSTRUCTION` — the framework's\ninstruction for a substantive request no specialist covers, which is otherwise APPENDED to a\nstring-form prompt. Positioned rather than appended for one reason: this preset's whole point is\nbrevity, and appended text would be the last thing the model reads. Putting the block above the\nbrevity rule leaves \"a single short sentence\" with the recency, so the two compose instead of\ncompeting. A prompt whose tone rules matter should do the same."
-        }
-      ],
-      "exports": [
-        {
-          "kind": "js",
-          "name": "friendlyFallbackAgent",
-          "declaration": {
-            "name": "friendlyFallbackAgent",
-            "module": "src/config/fallback-agents.ts"
-          }
-        },
-        {
-          "kind": "js",
-          "name": "strictFallbackAgent",
-          "declaration": {
-            "name": "strictFallbackAgent",
-            "module": "src/config/fallback-agents.ts"
-          }
-        }
-      ]
-    },
-    {
-      "kind": "javascript-module",
-      "path": "src/config/index.ts",
-      "declarations": [],
-      "exports": [
-        {
-          "kind": "js",
-          "name": "*",
-          "declaration": {
-            "name": "*",
-            "package": "./config"
-          }
-        },
-        {
-          "kind": "js",
-          "name": "*",
-          "declaration": {
-            "name": "*",
-            "package": "./fallback-agents"
-          }
-        }
-      ]
-    },
-    {
-      "kind": "javascript-module",
-      "path": "src/config/validate-providers.ts",
-      "declarations": [],
-      "exports": []
-    },
-    {
-      "kind": "javascript-module",
-      "path": "src/genesis/calendar.ts",
-      "declarations": [],
-      "exports": []
-    },
-    {
-      "kind": "javascript-module",
-      "path": "src/genesis/config.ts",
-      "declarations": [
-        {
-          "kind": "variable",
-          "name": "DEFAULT_MAX_ROWS",
-          "type": {
-            "text": "number"
-          },
-          "default": "50",
-          "description": "The default read cap, and the ceiling the config may raise it to."
-        },
-        {
-          "kind": "variable",
-          "name": "MAX_ROWS_CEILING",
-          "type": {
-            "text": "number"
-          },
-          "default": "1000"
+          "kind": "variable",
+          "name": "MAX_ROWS_CEILING",
+          "type": {
+            "text": "number"
+          },
+          "default": "1000"
         },
         {
           "kind": "function",
@@ -6762,46 +6882,220 @@
     },
     {
       "kind": "javascript-module",
-      "path": "src/main/attachment-controller.ts",
-      "declarations": [],
-      "exports": []
-    },
-    {
-      "kind": "javascript-module",
-      "path": "src/main/budget-controller.ts",
-      "declarations": [],
-      "exports": []
-    },
-    {
-      "kind": "javascript-module",
-      "path": "src/main/composer-menu-controller.ts",
-      "declarations": [],
-      "exports": []
-    },
-    {
-      "kind": "javascript-module",
-      "path": "src/main/composer-resize-controller.ts",
-      "declarations": [],
-      "exports": []
-    },
-    {
-      "kind": "javascript-module",
-      "path": "src/main/context-gate-controller.ts",
-      "declarations": [],
-      "exports": []
-    },
-    {
-      "kind": "javascript-module",
-      "path": "src/main/cost-ledger-controller.ts",
-      "declarations": [],
-      "exports": []
-    },
-    {
-      "kind": "javascript-module",
-      "path": "src/main/index.ts",
-      "declarations": [],
-      "exports": [
-        {
+      "path": "src/notifications/agent-notifications.ts",
+      "declarations": [
+        {
+          "kind": "variable",
+          "name": "DEFAULT_AGENT_NOTIFICATION_MESSAGE",
+          "type": {
+            "text": "string"
+          },
+          "default": "'The assistant is ready for your next input'",
+          "description": "The notification's text when neither the app nor the widget gives one."
+        },
+        {
+          "kind": "function",
+          "name": "agentNotificationPermission",
+          "return": {
+            "type": {
+              "text": "AgentNotificationPermission"
+            }
+          },
+          "description": "Whether this page may show notifications. Safe to call anywhere, including Node."
+        },
+        {
+          "kind": "function",
+          "name": "requestAgentNotificationPermission",
+          "return": {
+            "type": {
+              "text": "Promise<AgentNotificationPermission>"
+            }
+          },
+          "description": "Ask the person for permission to show notifications, and resolve to the result. Call it from a\nclick or key handler: browsers ignore or refuse a request that does not come from the person.\nResolves straight away when permission is already decided or unsupported, since a browser only\never asks once."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "DEFAULT_AGENT_NOTIFICATION_MESSAGE",
+          "declaration": {
+            "name": "DEFAULT_AGENT_NOTIFICATION_MESSAGE",
+            "module": "src/notifications/agent-notifications.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "agentNotificationPermission",
+          "declaration": {
+            "name": "agentNotificationPermission",
+            "module": "src/notifications/agent-notifications.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "requestAgentNotificationPermission",
+          "declaration": {
+            "name": "requestAgentNotificationPermission",
+            "module": "src/notifications/agent-notifications.ts"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/notifications/agent-notifier.ts",
+      "declarations": [],
+      "exports": []
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/notifications/index.ts",
+      "declarations": [],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "agentNotificationPermission",
+          "declaration": {
+            "name": "agentNotificationPermission",
+            "module": "./agent-notifications"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "DEFAULT_AGENT_NOTIFICATION_MESSAGE",
+          "declaration": {
+            "name": "DEFAULT_AGENT_NOTIFICATION_MESSAGE",
+            "module": "./agent-notifications"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "requestAgentNotificationPermission",
+          "declaration": {
+            "name": "requestAgentNotificationPermission",
+            "module": "./agent-notifications"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "type",
+          "declaration": {
+            "name": "type",
+            "module": "./agent-notifications"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "AgentAttentionDetail",
+          "declaration": {
+            "name": "AgentAttentionDetail",
+            "module": "./agent-notifications"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "type",
+          "declaration": {
+            "name": "type",
+            "module": "./agent-notifications"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "AgentAttentionKind",
+          "declaration": {
+            "name": "AgentAttentionKind",
+            "module": "./agent-notifications"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "type",
+          "declaration": {
+            "name": "type",
+            "module": "./agent-notifications"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "AgentNotificationLevel",
+          "declaration": {
+            "name": "AgentNotificationLevel",
+            "module": "./agent-notifications"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "type",
+          "declaration": {
+            "name": "type",
+            "module": "./agent-notifications"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "AgentNotificationPermission",
+          "declaration": {
+            "name": "AgentNotificationPermission",
+            "module": "./agent-notifications"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/notifications/notification-level-picker.template.ts",
+      "declarations": [],
+      "exports": []
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/notifications/notification-settings.ts",
+      "declarations": [],
+      "exports": []
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/main/attachment-controller.ts",
+      "declarations": [],
+      "exports": []
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/main/budget-controller.ts",
+      "declarations": [],
+      "exports": []
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/main/composer-menu-controller.ts",
+      "declarations": [],
+      "exports": []
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/main/composer-resize-controller.ts",
+      "declarations": [],
+      "exports": []
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/main/context-gate-controller.ts",
+      "declarations": [],
+      "exports": []
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/main/cost-ledger-controller.ts",
+      "declarations": [],
+      "exports": []
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/main/index.ts",
+      "declarations": [],
+      "exports": [
+        {
           "kind": "js",
           "name": "*",
           "declaration": {
@@ -10797,6 +11091,18 @@
             {
               "description": "Fired after the session is wiped (the lifecycle menu's Clear). The payload is captured before teardown so the host can clean up any external state the active agent was working on. Bubbles and composed. detail: `SessionClearedDetail`",
               "name": "session-cleared"
+            },
+            {
+              "description": "Fired when an agent's `handOff` takes effect and its target becomes active. Bubbles and composed. detail: `HandOffFrame`",
+              "name": "handoff-started"
+            },
+            {
+              "description": "Fired when a hand-off ends and its caller is active again; `detail.outcome` says how it ended. Bubbles and composed. detail: `HandOffFrame`",
+              "name": "handoff-returned"
+            },
+            {
+              "description": "Fired when a hand-off ends with no hand-back: the chat was cleared, the agents changed, or a restore found it could not resume. Bubbles and composed. detail: `HandOffFrame`",
+              "name": "handoff-unwound"
             }
           ],
           "attributes": [
@@ -10931,9 +11237,9 @@
           "kind": "variable",
           "name": "AiAssistantEvent",
           "type": {
-            "text": "{\n  /** Session wiped via the lifecycle menu's Clear. `detail`: `SessionClearedDetail`. */\n  SessionCleared: 'session-cleared',\n  /** Header pressed in `popout-mode=\"expand\"` (drag-to-popout hosts). `detail`: `ChatHeaderMouseDownDetail`. */\n  ChatHeaderMouseDown: 'chat-header-mousedown',\n}"
+            "text": "{\n  /** Session wiped via the lifecycle menu's Clear. `detail`: `SessionClearedDetail`. */\n  SessionCleared: 'session-cleared',\n  /** Header pressed in `popout-mode=\"expand\"` (drag-to-popout hosts). `detail`: `ChatHeaderMouseDownDetail`. */\n  ChatHeaderMouseDown: 'chat-header-mousedown',\n  /** An agent's hand-off started (GENC-1737). `detail`: `HandOffFrame`. */\n  HandOffStarted: 'handoff-started',\n  /** A hand-off ended and its caller is active again. `detail`: `HandOffFrame`, with `outcome`. */\n  HandOffReturned: 'handoff-returned',\n  /** A hand-off ended with no hand-back. `detail`: `HandOffFrame`, with `outcome`. */\n  HandOffUnwound: 'handoff-unwound',\n}"
           },
-          "default": "{\n  /** Session wiped via the lifecycle menu's Clear. `detail`: `SessionClearedDetail`. */\n  SessionCleared: 'session-cleared',\n  /** Header pressed in `popout-mode=\"expand\"` (drag-to-popout hosts). `detail`: `ChatHeaderMouseDownDetail`. */\n  ChatHeaderMouseDown: 'chat-header-mousedown',\n}",
+          "default": "{\n  /** Session wiped via the lifecycle menu's Clear. `detail`: `SessionClearedDetail`. */\n  SessionCleared: 'session-cleared',\n  /** Header pressed in `popout-mode=\"expand\"` (drag-to-popout hosts). `detail`: `ChatHeaderMouseDownDetail`. */\n  ChatHeaderMouseDown: 'chat-header-mousedown',\n  /** An agent's hand-off started (GENC-1737). `detail`: `HandOffFrame`. */\n  HandOffStarted: 'handoff-started',\n  /** A hand-off ended and its caller is active again. `detail`: `HandOffFrame`, with `outcome`. */\n  HandOffReturned: 'handoff-returned',\n  /** A hand-off ended with no hand-back. `detail`: `HandOffFrame`, with `outcome`. */\n  HandOffUnwound: 'handoff-unwound',\n}",
           "description": "DOM events the `<foundation-ai-assistant>` element dispatches to its host.\nAll bubble and are `composed` (they cross the shadow boundary), so a host can\nlisten on the element — or any ancestor — to react. Use these constants to\nwire listeners instead of hand-typing event-name strings.\n\nAn `as const` map (not a TS `enum` — this package ships none), so it serves as\nboth the listener-name value and, via the same-named type below, a union."
         },
         {
@@ -11007,195 +11313,21 @@
     },
     {
       "kind": "javascript-module",
-      "path": "src/notifications/agent-notifications.ts",
+      "path": "src/provider/ai-provider-switcher.ts",
       "declarations": [
         {
           "kind": "variable",
-          "name": "DEFAULT_AGENT_NOTIFICATION_MESSAGE",
-          "type": {
-            "text": "string"
-          },
-          "default": "'The assistant is ready for your next input'",
-          "description": "The notification's text when neither the app nor the widget gives one."
-        },
-        {
-          "kind": "function",
-          "name": "agentNotificationPermission",
-          "return": {
-            "type": {
-              "text": "AgentNotificationPermission"
-            }
-          },
-          "description": "Whether this page may show notifications. Safe to call anywhere, including Node."
-        },
-        {
-          "kind": "function",
-          "name": "requestAgentNotificationPermission",
-          "return": {
-            "type": {
-              "text": "Promise<AgentNotificationPermission>"
-            }
-          },
-          "description": "Ask the person for permission to show notifications, and resolve to the result. Call it from a\nclick or key handler: browsers ignore or refuse a request that does not come from the person.\nResolves straight away when permission is already decided or unsupported, since a browser only\never asks once."
+          "name": "AIProviderSwitcher",
+          "description": "The DI token for the (AIProviderSwitcher:interface). Resolves a noop until the app\nregisters one."
         }
       ],
       "exports": [
         {
           "kind": "js",
-          "name": "DEFAULT_AGENT_NOTIFICATION_MESSAGE",
+          "name": "AIProviderSwitcher",
           "declaration": {
-            "name": "DEFAULT_AGENT_NOTIFICATION_MESSAGE",
-            "module": "src/notifications/agent-notifications.ts"
-          }
-        },
-        {
-          "kind": "js",
-          "name": "agentNotificationPermission",
-          "declaration": {
-            "name": "agentNotificationPermission",
-            "module": "src/notifications/agent-notifications.ts"
-          }
-        },
-        {
-          "kind": "js",
-          "name": "requestAgentNotificationPermission",
-          "declaration": {
-            "name": "requestAgentNotificationPermission",
-            "module": "src/notifications/agent-notifications.ts"
-          }
-        }
-      ]
-    },
-    {
-      "kind": "javascript-module",
-      "path": "src/notifications/agent-notifier.ts",
-      "declarations": [],
-      "exports": []
-    },
-    {
-      "kind": "javascript-module",
-      "path": "src/notifications/index.ts",
-      "declarations": [],
-      "exports": [
-        {
-          "kind": "js",
-          "name": "agentNotificationPermission",
-          "declaration": {
-            "name": "agentNotificationPermission",
-            "module": "./agent-notifications"
-          }
-        },
-        {
-          "kind": "js",
-          "name": "DEFAULT_AGENT_NOTIFICATION_MESSAGE",
-          "declaration": {
-            "name": "DEFAULT_AGENT_NOTIFICATION_MESSAGE",
-            "module": "./agent-notifications"
-          }
-        },
-        {
-          "kind": "js",
-          "name": "requestAgentNotificationPermission",
-          "declaration": {
-            "name": "requestAgentNotificationPermission",
-            "module": "./agent-notifications"
-          }
-        },
-        {
-          "kind": "js",
-          "name": "type",
-          "declaration": {
-            "name": "type",
-            "module": "./agent-notifications"
-          }
-        },
-        {
-          "kind": "js",
-          "name": "AgentAttentionDetail",
-          "declaration": {
-            "name": "AgentAttentionDetail",
-            "module": "./agent-notifications"
-          }
-        },
-        {
-          "kind": "js",
-          "name": "type",
-          "declaration": {
-            "name": "type",
-            "module": "./agent-notifications"
-          }
-        },
-        {
-          "kind": "js",
-          "name": "AgentAttentionKind",
-          "declaration": {
-            "name": "AgentAttentionKind",
-            "module": "./agent-notifications"
-          }
-        },
-        {
-          "kind": "js",
-          "name": "type",
-          "declaration": {
-            "name": "type",
-            "module": "./agent-notifications"
-          }
-        },
-        {
-          "kind": "js",
-          "name": "AgentNotificationLevel",
-          "declaration": {
-            "name": "AgentNotificationLevel",
-            "module": "./agent-notifications"
-          }
-        },
-        {
-          "kind": "js",
-          "name": "type",
-          "declaration": {
-            "name": "type",
-            "module": "./agent-notifications"
-          }
-        },
-        {
-          "kind": "js",
-          "name": "AgentNotificationPermission",
-          "declaration": {
-            "name": "AgentNotificationPermission",
-            "module": "./agent-notifications"
-          }
-        }
-      ]
-    },
-    {
-      "kind": "javascript-module",
-      "path": "src/notifications/notification-level-picker.template.ts",
-      "declarations": [],
-      "exports": []
-    },
-    {
-      "kind": "javascript-module",
-      "path": "src/notifications/notification-settings.ts",
-      "declarations": [],
-      "exports": []
-    },
-    {
-      "kind": "javascript-module",
-      "path": "src/provider/ai-provider-switcher.ts",
-      "declarations": [
-        {
-          "kind": "variable",
-          "name": "AIProviderSwitcher",
-          "description": "The DI token for the (AIProviderSwitcher:interface). Resolves a noop until the app\nregisters one."
-        }
-      ],
-      "exports": [
-        {
-          "kind": "js",
-          "name": "AIProviderSwitcher",
-          "declaration": {
-            "name": "AIProviderSwitcher",
-            "module": "src/provider/ai-provider-switcher.ts"
+            "name": "AIProviderSwitcher",
+            "module": "src/provider/ai-provider-switcher.ts"
           }
         }
       ]
@@ -11668,7 +11800,7 @@
           "type": {
             "text": "readonly string[]"
           },
-          "default": "[\n  'This is an exported debug log for the Genesis AI assistant. Read it top-to-bottom.',\n  \"`sessionUsage` is what this session spent: `costUsd` (USD, provider-reported per request and summed, cache discounts already applied) plus the four TOKEN BUCKETS — `uncachedInputTokens`, `cacheReadTokens`, `cacheWriteTokens`, `outputTokens`. Those four are disjoint and safe to add up for a total-tokens figure; the per-message fields further down are NOT (see kind:'message'). Each bucket bills at a different rate — cache reads a fraction of uncached input, cache writes a premium, output highest — so a big token count against a small cost means the prompt was mostly cache hits, not a missing charge. It covers sub-agent turns and spend a compaction banked, so for the CONVERSATION it is the authoritative total: prefer it over re-summing the timeline, which can be short by whatever the ring buffers evicted. The same figures appear under `meta.context`. It is as current as the snapshot it came from: the assistant's own download stamps a fresh one, but a log stitched by another tool can carry an older one — compare `meta.timestamp` with the last timeline entry, and if it is well behind, read these totals as historical and fall back to summing the timeline. One scope caveat: it is derived from the transcript, so it excludes billed calls that produced no message (a blank or refused attempt that was retried — see kind:'turn'.`usage`). Summing the turns can therefore come out HIGHER than this, and the difference is exactly that discarded spend, not a double-count.\",\n  \"What 'session' means for those figures: the CURRENT conversation under this session key (a host-supplied per-project id, or the element id + header title when the host supplies none) — which is not necessarily everything in `timeline`. It is re-derived from the live transcript, so it spans page loads only when the chat is being remembered, and a Clear resets it to zero. `timeline` is append-only regardless: it keeps every page load and the pre-Clear conversation, with the session.cleared event as the boundary. So on a long-lived log, read these totals as the latest conversation's and the earlier sections as history — not as a total of the whole file.\",\n  '`timeline` is the entire session as one array, already sorted chronologically by `timestamp` (ISO 8601). Every entry has a `kind`.',\n  'Timestamps are millisecond-resolution; entries that share the same millisecond are ordered by a fixed kind rank (event, then turn, then message), which is a heuristic and may not reflect exact causal order within that millisecond — e.g. a user message and the turn it triggered, or a final assistant message and its turn.end event, can appear in either order depending on whether they landed in the same millisecond. Read the logical structure of a turn rather than over-interpreting the micro-ordering of co-timestamped entries of different kinds.',\n  \"kind:'message' — the conversation. `role` is user/assistant/tool/system-event/synthetic-user; `agentName` says which agent produced it; `toolCalls`/`toolResult`/`interaction` carry tool and widget activity; `inputTokens`/`outputTokens`/`cost` are per-message LLM usage, where `inputTokens` is the WHOLE prompt for that request and `cacheReadTokens`/`cacheWriteTokens` BREAK IT DOWN rather than add to it — uncached input is `inputTokens` minus those two, and adding the cache fields to `inputTokens` counts the prompt twice. The cache fields are absent on providers that report no cache split (Gemini reports reads only, since implicit caching bills no write) and on messages persisted before they existed, so read them as 0 when missing. Each bucket bills at a different rate — cache reads a fraction of uncached input, cache writes a premium, output highest — so a large token count at a small cost means the prompt was mostly cache hits. `externalCostUsd` is any non-LLM cost a widget reported for its own external service calls (folded into the session cost total alongside `cost`). On model-produced assistant messages, `model` is the concrete model id that generated it (e.g. 'gemini-2.5-flash-lite') and `providerName` is the registry slot it resolved under (e.g. a tier name like 'high'/'low', or the default); together they attribute the message — and any tool calls it carries — to an exact model even across a mid-session vendor/tier switch, where one slot name can map to different models before and after the switch. Both are undefined on any entry that is NOT an LLM response: non-assistant roles (user/tool/system-event) and 'synthetic-user' echoes; assistant interaction/widget entries (empty content carrying an `interaction` — a rendered widget, not a model turn); driver-authored assistant fallbacks (the timeout, repeated-malformed-call, and empty-response apology messages); and messages restored from a session persisted before these fields existed. One partial case: on a genuine model turn whose provider exposes no `getStatus` (or reports no model), `providerName` is still set but `model` alone is undefined. A 'synthetic-user' message is a display-only echo of an interaction outcome (e.g. the answer a widget reported): it renders on the user's side of the chat and `agentName` is the agent that created it, but it is never sent to the LLM — so it has no matching 'turn' and the model learns the outcome only from the corresponding tool result. An echo of an answer an interceptor (such as an autopilot) gave is NOT synthetic-user: see the delegated-messages paragraph.\",\n  'The autopilot (GENC-1660) runs on a driver of its own, and everything it did is harvested into this log: entries with delegate: autopilot and an agentName ending in › Autopilot are its turns (the decision message it was sent is the user message of its turn, so what it was shown is there verbatim; its systemPrompt is its grounding, such as the brief), its tool calls (widget_read, widget_act, hand_back, any read-only tools of its own, and its widget tools — reads with parameters that a widget type declares, routed to the interaction of that type being decided and refused with a reason when none is, offered on every decision so its tool list never changes; while one is open its tail starts with a line naming them) and their results (a read, view or widget tool, is capped at about 20,000 characters, cut with a note asking for less, and leaves its history at the end of the decision as a one-line note), and its own events. Its cost is already in the session total: it is booked as externalCostUsd on the interaction each decision answered, or, for a written question it answered, on the user message it sent on the user behalf (delegate: autopilot), so do not add its turns to that total. Spend that reached no message is recorded as autopilot.cost-dropped instead.',\n  \"Delegated messages (GENC-1660): a message with a `delegate` field was written or sent ON THE USER'S BEHALF by a driver decorator, and `delegate` names it (e.g. autopilot). The platform stamps it; nothing else can. It renders as the assistant whatever its role. A delegated `user` message was NOT typed by the user: it is an answer given on their behalf, and the model read it with `delegateFraming` in brackets in front of the content (the stored `content` is the bare text). A delegated `assistant` message is display-only (`excludeFromProvider`): the decorator's narration note, or, when its answer carried no note, the widget's own echo of the answer (its `userMessage`), shown as the assistant and never as the person. A widget answer a decorator gave with a note is not echoed at all: the note already says what was chosen. To tell what the person decided from what was decided for them, read `interaction.answeredBy` and these fields, never the role alone.\",\n  \"Sub-agent messages appear inline. When a tool delegates to a sub-agent (via `requestSubAgent`), the sub-agent's whole conversation — its own assistant/tool messages, each with their own `content`/`thinking`/`toolCalls`/`toolResult` and per-message `model`/`providerName`/`inputTokens`/`outputTokens`/`cacheReadTokens`/`cacheWriteTokens`/`cost` — is hoisted into the timeline as ordinary kind:'message' entries, interleaved by timestamp right after the tool call that spawned them (so you read the delegation top-to-bottom). A hoisted entry is marked: `subAgentDepth` is its delegation depth (1 for a sub-agent, 2 for a sub-agent's sub-agent, …), `subAgentOf` is the id of the parent tool call that spawned it (correlates it back even when two sub-agents run in one parent turn), `subAgentName` is the sub-agent's own name, and `agentName` is rewritten to a `\\\"<parent> › <sub-agent>\\\"` breadcrumb (composing when nested, e.g. `\\\"UI Builder › Planner › Grounding\\\"`). The sub-agent's per-LLM-call snapshots also surface as kind:'turn' entries with an N-M `turnIndex`, and subagent.started/completed (or subagent.failed) events bracket the run. Per-message `cost` on hoisted entries is already part of the session total (it is summed from the un-flattened history), so summing the top-level timeline does NOT double-count.\",\n  \"kind:'turn' — one LLM call. `turnIndex` is a string: a top-level turn is the bare counter ('0', '1', …); a sub-agent's turns are numbered under the parent turn that activated them ('3-1', '3-2', …, and a nested sub-agent contributes '3-2-1', …), and `agentName` names the agent that ran the turn. `systemPrompt` and `toolNames` are what the model saw. A systemPrompt of '<repeated — identical to turn N>' was byte-identical to turn N and de-duplicated; the full prompt is shown whenever it changes (often because a stateful agent advanced), so prompt evolution is visible.\",\n  \"kind:'turn'.`model`/`providerName`/`provider` — which model ran that call: the concrete model id, the registry slot it resolved under (a tier name like 'high'/'low', or the default), and the vendor. Recorded per CALL, so an agent whose `provider` selector varies by state — a flow that plans on a high tier and executes on a low one — has every step attributed, including calls that produced no message. `model` is the SERVING model where the provider reports one, so a turn answered by a server-side fallback names the model that answered rather than the one requested; it always matches the `model` on the message that call produced. Absent when the provider exposes no `getStatus` and the transport stamped nothing.\",\n  \"kind:'turn'.`usage` — what that ONE call cost, in the same four-bucket + `costUsd` shape as `sessionUsage`. Absent while a call is in flight and on providers that report no usage. This is the SAME money as the message the call produced, not extra money: never add turn usage to message usage, and read a turn plus its message as one charge. Its distinct value is the calls that produced NO message — a blank or refused response is billed and then discarded before the retry, so the turn entry is the only record of that spend, and a turn with `usage` but no message after it is exactly that. `costUsd: 0` alongside a nonzero token count means the provider reported no price, not that the call was free.\",\n  \"kind:'turn'.`agentSnapshot` — the active agent's own view of its internal state, captured at that turn. An agent opts into this by exposing a `getDebugSnapshot()` that returns JSON-serializable per-state info; stateful/flow agents wire it automatically, so you can watch a flow advance turn-by-turn (e.g. current step, cursor, collected fields, pending changes). Absent for agents that don't expose one.\",\n  \"kind:'event' — a meta/lifecycle event. `type` names it (see below); `detail` carries structured data. `detail.placement` is the emitting UI instance: 'bubble' (collapsed), 'panel' (popped-out), or 'standalone'.\",\n  \"Each 'event' also has an `importance`: 'high' (failures/limits — turn.error, tool.failed, subagent.failed, file.read-failed, suggestions.failed, context.threshold-crossed), 'normal' (session flow — connects, turns, retries, handoffs, agent/provider changes, interactions, sub-agent start/complete), or 'low' (skippable UI/bookkeeping noise — panel.toggled, attachment.added, driver.wired/unwired, context.updated, context.condensed). To skim, ignore importance:'low'; to triage a failure, filter to importance:'high' then read the nearby messages and turns. A 'high' turn.error is often preceded by one or more 'normal' turn.retry events for the same reason — read them together to see how many attempts were made before bailing. 'message' and 'turn' entries carry no importance — they are the substance, always read them.\",\n  'Event types: assistant.connected/disconnected (mount + placement + whether the session was created or restored), assistant.popout/popin (window placement), driver.created/wired/unwired (which driver is live and why it stops/starts responding across a popout), state.changed (idle↔loading), turn.start/turn.end (turn boundary; turn.end carries durationMs), turn.retry (a recoverable in-turn retry — detail.reason plus attempt/maxAttempts; for malformed calls also finishMessage; for empty responses also the provider finishReason + thoughtsTokens + parts breakdown), turn.error (a turn failed or hit a guardrail — detail.reason is one of exception/malformed-function-call/empty-response/unknown-tool-limit/max-iterations/response-truncated/refusal/budget-exhausted/provider-refused/context-exhausted/ai-service-error, plus reason-specific diagnostics: attempts (for empty-response also finishReason + thoughtsTokens + a parts breakdown, distinguishing a thinking-only STOP from a truly empty turn), finishMessage, for response-truncated the model + maxTokens + outputTokens + tools, unknownTools (split into staleTools — real earlier this activation but retired by the current state or hidden behind an open exclusive fold — and hallucinatedTools — never advertised) + availableTools, iterations + limit, for budget-exhausted the budgetUsd + spentUsd figures reported by the proxy plus the resolved vendor, for provider-refused the kind (spend|auth) plus the upstream status and error type — the vendor refusing the ACCOUNT rather than us refusing to spend, so the remedy is a top-up or a key rotation rather than a raised cap, and the kind is the only place that distinction survives because the user-facing copy is deliberately cause-free, for context-exhausted the estimated contextTokens against the guard that stopped the turn plus the iterations reached — the driver ending a runaway tool loop at the edge of the context window rather than issuing a request the provider would reject, so the transcript survives intact and can still be compacted, for ai-service-error the code (one of AI_SERVICE_ERROR_CODES, e.g. NO_API_KEY) and the status the AI service answered with — its own text goes to the browser console only, or name + message for exceptions), tool.failed (a tool threw), tool.unresolved (the model called a tool that could not be dispatched — detail.kind is folded/fold-hidden/stale/unknown, plus tool + agent and, for the counted kinds, the consecutive streak; the recurring lead-up to an unknown-tool-limit turn.error), subagent.started/completed/failed (the lifecycle of a `requestSubAgent` delegation — detail.agent names the sub-agent; these bracket the sub-agent turns that appear as kind:turn entries with an N-M `turnIndex`; subagent.failed also carries detail.reason, one of max_iterations/malformed_tool_call/empty_response/unknown_tool_limit/timeout/response_truncated/refusal/budget_exhausted/provider_refused/context_exhausted/ai_service_error; budget_exhausted and provider_refused are terminal for the PARENT turn too, and so is ai_service_error when the refusal is about the service rather than the request and came from the vendor the parent calls — the parent stops rather than calling the model again into the same wall; after context_exhausted the parent goes on, but its own next call is likely to stop on the same guard), agent.handoff (routing; from=null is the initial activation), agent.pinned/unpinned (forced routing), routing.decided (ONE PER ROUTING DECISION — see its own paragraph below), provider.selected (the resolved provider for the upcoming turns — detail.provider is the registry SLOT/tier name, detail.model the concrete model behind it and detail.vendor its vendor; emitted only when the slot CHANGES, so read the per-turn `model` for the model of any given call rather than assuming the nearest event still applies), interaction.requested/resolved (blocking user widgets — explain quiet gaps; note that when a sub-agent opens a widget, detail.agent — and the agentName on the interaction message — is the HOST agent that owns the widget, NOT the sub-agent that asked, because widgets render and resolve on the host driver; detail.ownerPath names the agents that actually asked, outermost first, the last being the one whose tool requested it, and detail.heldBy says who held it when it opened: user, or the id of the interceptor that claimed it, such as autopilot; on interaction.resolved, detail.answeredBy is who answered — the claimant id when it settled through its own hold, user for any other answer (a click counts as the person even on a widget a claimant held) — absent when it closed unanswered (a timeout or a stop), and absent too when it settled by itself other than through the hold of a claimant — a widget registered resolvesItself (one that does its work and settles on its own, asking the person nothing, such as a generation run), or one outcome its controller said settled itself (ctx.resolve with resolvedItself, such as a generation phase that failed outright before its review gate ever asked anything) — which then carries detail.resolvedItself: true instead, as the interaction message does — nobody answered it, and the platform cannot tell it finishing from the person interrupting it (a Skip), so only the result of the widget itself can say which; the same value is stamped on the interaction message as answeredBy and on the result the asking tool handler receives (absent there in the same cases), and when it is not user the tool result that interaction returned carries a decidedOnUsersBehalf record, so the model was told the choice was not made by the person; detail.edits, present only when non-zero, counts the editing actions a claimant ran on the widget before it was settled, whoever settled it, and those edits are stamped on the interaction message as edits, each with by, action, choice and args when it had some, in the order they ran, while a decidedOnUsersBehalf record carries their choice texts as edits, and when the person settled it after such edits the tool result carries an editedOnUsersBehalf record instead — the framing and those choice texts — so the model knows the widget was changed on the user behalf before the user answered, and that the user then confirmed it by finishing it), interaction.held (a claimant moved a pending interaction to the person or back to itself — detail.heldBy is the new holder, detail.claimant the interceptor; detail.late: true is an interceptor that declined it when it opened claiming it afterwards, such as the autopilot resumed while it was open; a widget held by anything but user was not answered by the person), interaction.claim-refused (a claim on a userOnly interaction, which stays with the person — detail.claimant + reason), autopilot.* (the autopilot, a decorator that answers interactions on behalf of the user — autopilot.claimed / autopilot.declined say whether it took each interaction and, for a decline, detail.reason: paused, other-flow, no-autopilot, unavailable, userOnly, policy or no-controller; one declined as paused that is still open when the person resumes the autopilot is looked at again, and the autopilot.claimed or autopilot.declined recorded for it then carries detail.onResume: true (a decline then can also be claimed-elsewhere, another interceptor having claimed it first); a restored mode looks at nothing; autopilot.decision-sent is what it was sent (detail.chars; detail.nothingEnabled: true when every action on the widget was unavailable — a gate whose controller said it was asking, such as a failed build the autopilot may not cancel — so it could only hand it back, which it may then do even after the person asked it to decide it itself; a widget whose controller says it is working (ctx.setWorking) is never sent a decision until it says it is asking, even when an action is enabled or the person resumes the autopilot); autopilot.acted is what it did (detail.action, detail.note, detail.finished); autopilot.handed-back is a decision it gave to the person (detail.reason and detail.trigger: model, no-decision or error); autopilot.paused / autopilot.resumed are mode changes (detail.scope, detail.trigger, detail.decideYourself when the person resumed during a hand-back; detail.trigger is restored when the mode came back with the session after a reload, applied once its flow re-activated, which starts nothing by itself); autopilot.error is the wrapper itself failing; autopilot.refinement counts a refining action against its step — a written answer (reply) or a widget action declared refines, such as a regenerate with instructions, counted together (detail.action, detail.stepKey, detail.count, detail.limitReached, after which every refining action is withdrawn for that step: not listed, and refused; the decision and every relisting of its actions say how many are left at the step, as a line Refinements left at this step: N, wherever the widget has a refining action); autopilot.handback-presented is the turn-level hand-back, shown when a working turn ended needing the person with no widget to hand over (detail.why: max-iterations, context-exhausted, failure or question; detail.options; detail.choice once answered); autopilot.catch-up is the autopilot being given the whole visible transcript at once (detail.why: first, for its first decision in a flow or after a reload; size, when its own history passed its budget and was rebuilt short — detail.ownChars; or compacted, when a compaction removed the last message it had seen, so it reads the summary and everything since, short; in each, what it had sent on the user behalf is included and labelled as its own, since its own history does not hold it); autopilot.cost-dropped is autopilot spend that no message carries, so it is NOT in the session total (detail.costUsd and detail.why: handed-back, aborted or stale for a written question it answered that no reply was sent for — stale when a pause, a resume, a new turn or the end of its flow came before the answer landed, which then went nowhere — or no-recorder when the driver had no way to book a decision to its interaction); a hand-back trigger can also be budget (the decision passed its spend cap), watchdog (its work went quiet: no ready surface and no heartbeat, or its own decision stalled with no model call landing, which stops that decision) or detached (the autopilot was removed while it held the interaction, which went to the person with no reason shown). To debug one autopilot decision, follow its interactionId: interaction.requested (heldBy), autopilot.claimed, autopilot.decision-sent, autopilot.acted or autopilot.handed-back, interaction.invoked, interaction.resolved (answeredBy), then the next turn of the working agent), interaction.invoked (a claimant ran one of the actions the widget itself exposes, through its hold, the same code the button runs — detail.claimant, detail.action (an option id, select or reply) and detail.finished, whether that settled the interaction, and when it did not, the run is recorded as an edit; the choice and narration it recorded reach the result of the tool that asked as decidedOnUsersBehalf), interaction.step (a long action run as named steps through runSteps, which survive a reload — detail.step and detail.outcome: started, done, skipped when the step was already done before a reload, or resumed when it started before a reload and runs again with what it saved part-way, such as a job id it re-attaches to), interaction.checkpoint (the checkpoints a conversation keeps for its long actions: the one in flight, and each one a reload cut, held apart until a request of its own widget type takes it over, so a resumed flow that opens other long widgets first, which save their own, loses nothing — detail.action: resumed when a reload cut the work and a request of the same widget type that the registration sameWork agrees is the same work took it over, refused when sameWork said a new request is different work (detail.saved is the identity it kept; detail.kept: true, since it stays for a later request of that type, and is offered to every one until one agrees) or when runSteps found the handed-over checkpoint malformed and started fresh (detail.reason, detail.saved), or cleared when its flow ended, once per checkpoint, with detail.cut: true for one a reload cut that nothing took over), context.updated/threshold-crossed (token + cost), context.condensed (a stale tool payload was collapsed out of the model-bound history by a `condenseWhen` declaration on the tool — detail.tool + toolCallId, target args|response, trigger (superseded:<key> or age:<n>), stubLen, and an estimated tokensSaved; stored history and this log keep the FULL payload, so the model-visible slice at any point is the full history minus the condensations recorded up to then), panel.toggled, attachment.added, file.read-failed, suggestions.failed.',\n  'Sub-agent meta events: a sub-agent\\'s own turn.retry/turn.error/tool.failed/tool.unresolved events are merged into this same timeline, tagged with `detail.subAgent` — a `\"<parent> › <sub-agent>\"` breadcrumb that composes when nested (e.g. `\"UI Builder › Planner › Grounding\"`) — and interleaved by their original timestamps within the subagent.started→completed/failed bracket. These are the per-attempt/per-failure signals that do NOT appear among the sub-agent\\'s (hoisted) messages: a malformed/empty attempt that gets retried produces no message, and the stale-vs-hallucinated split and streak counts live only on the event. A sub-agent\\'s high-volume, message-derivable events (turn.start/turn.end, provider.selected, context.updated) are intentionally NOT merged — read its hoisted messages for model/tokens/cost and turn-by-turn activity, and the bracketing subagent.* events for the run\\'s span.',\n  \"`meta` holds context captured at export time: agentSummary (full agent configs), context (active model, contextTokens/contextLimit/contextUsagePercent for the last call, and the session totals — sessionCostUsd, sessionTokensConsumed, and the four-bucket sessionUsage lifted to the top of this log), activeDebugSnapshot (the active agent's `getDebugSnapshot()` taken fresh at export — reflects state NOW, which may have advanced beyond the last turn's agentSnapshot), debug (optional host-supplied debug state), host, and the export timestamp.\",\n  'Note the two different scopes in `meta.context`: `contextTokens` is the prompt size of the LAST call (against `contextLimit`, the model context window), while `sessionUsage`/`sessionTokensConsumed` are cumulative BILLED throughput. Every turn resends the conversation, so the cumulative figure counts each turn’s prompt again in the next turn’s and is expected to dwarf the context size — that is not double-counting.',\n  \"kind:'event' type 'routing.decided' — how ONE turn was routed, emitted by the orchestrating driver before the agent runs (and again after every handoff). `decision` is why that agent was chosen: 'classified' (the classifier ran and picked one), 'no-match' (it ran and answered -1 — nothing listed covers the request), 'ballot-exhausted' (every eligible specialist had already handed off this turn, so the ballot was empty and NO call was made — distinct from 'no-match', where one ran and declined), 'pinned' (a user pin, an agent named for that one message by the send's `agent` option, or an active stateful flow owned the turn, so no call was made), 'single-candidate'/'no-specialists' (configuration left nothing to decide), 'provider-unavailable' (the registry default exposes no chat()), 'classifier-failed' (every attempt threw — `error` carries the last one). `to` names the agent and `fallback` says whether that agent is the fallback. `candidates` is what was actually ON THE BALLOT, in ballot order, so `index` — the classifier's own answer — indexes it directly; `excluded` names the specialists left off because they already handed off this turn, so the full eligible set is `candidates` ∪ `excluded`. `candidates` is absent on the four decisions that put nothing to a vote — 'pinned', 'single-candidate', 'no-specialists', 'ballot-exhausted'. It IS present on 'provider-unavailable', which is not an exception worth removing: the ballot was built there, it simply never got sent. `attempts` covers the retry ladder. `durationMs` is on EVERY routing.decided, and is the field to read when a decision looks wrong: the four decisions that can reach the fallback are told apart by the clock as much as by their name, because a fallback routing that resolved in tens of milliseconds made no network call at all whatever its `decision` says.\",\n  \"kind:'event' type 'routing.decided'.`usage` — what that classifier call cost, in the same four-bucket + costUsd shape as `sessionUsage`, plus `model`. Absent on the decisions that make no call (see 'pinned' and the configuration ones). THIS SPEND IS NOT IN `sessionUsage`: a classifier call never enters the transcript and `sessionUsage` is derived from the transcript, so classifier cost is missing from the session total by construction, not by accident. Sum these events to close that gap — it is the one component of a session's real spend that the totals cannot see.\",\n  'To debug a failure: find the last turn.error or tool.failed, then read upward for the user message, the turn(s), and the agent/provider/state events that led into it. For a turn that went to the wrong agent, read its routing.decided first — `decision` says whether anything was actually asked.',\n]",
+          "default": "[\n  'This is an exported debug log for the Genesis AI assistant. Read it top-to-bottom.',\n  \"`sessionUsage` is what this session spent: `costUsd` (USD, provider-reported per request and summed, cache discounts already applied) plus the four TOKEN BUCKETS — `uncachedInputTokens`, `cacheReadTokens`, `cacheWriteTokens`, `outputTokens`. Those four are disjoint and safe to add up for a total-tokens figure; the per-message fields further down are NOT (see kind:'message'). Each bucket bills at a different rate — cache reads a fraction of uncached input, cache writes a premium, output highest — so a big token count against a small cost means the prompt was mostly cache hits, not a missing charge. It covers sub-agent turns and spend a compaction banked, so for the CONVERSATION it is the authoritative total: prefer it over re-summing the timeline, which can be short by whatever the ring buffers evicted. The same figures appear under `meta.context`. It is as current as the snapshot it came from: the assistant's own download stamps a fresh one, but a log stitched by another tool can carry an older one — compare `meta.timestamp` with the last timeline entry, and if it is well behind, read these totals as historical and fall back to summing the timeline. One scope caveat: it is derived from the transcript, so it excludes billed calls that produced no message (a blank or refused attempt that was retried — see kind:'turn'.`usage`). Summing the turns can therefore come out HIGHER than this, and the difference is exactly that discarded spend, not a double-count.\",\n  \"What 'session' means for those figures: the CURRENT conversation under this session key (a host-supplied per-project id, or the element id + header title when the host supplies none) — which is not necessarily everything in `timeline`. It is re-derived from the live transcript, so it spans page loads only when the chat is being remembered, and a Clear resets it to zero. `timeline` is append-only regardless: it keeps every page load and the pre-Clear conversation, with the session.cleared event as the boundary. So on a long-lived log, read these totals as the latest conversation's and the earlier sections as history — not as a total of the whole file.\",\n  '`timeline` is the entire session as one array, already sorted chronologically by `timestamp` (ISO 8601). Every entry has a `kind`.',\n  'Timestamps are millisecond-resolution; entries that share the same millisecond are ordered by a fixed kind rank (event, then turn, then message), which is a heuristic and may not reflect exact causal order within that millisecond — e.g. a user message and the turn it triggered, or a final assistant message and its turn.end event, can appear in either order depending on whether they landed in the same millisecond. Read the logical structure of a turn rather than over-interpreting the micro-ordering of co-timestamped entries of different kinds.',\n  \"kind:'message' — the conversation. `role` is user/assistant/tool/system-event/synthetic-user; `agentName` says which agent produced it; `toolCalls`/`toolResult`/`interaction` carry tool and widget activity; `inputTokens`/`outputTokens`/`cost` are per-message LLM usage, where `inputTokens` is the WHOLE prompt for that request and `cacheReadTokens`/`cacheWriteTokens` BREAK IT DOWN rather than add to it — uncached input is `inputTokens` minus those two, and adding the cache fields to `inputTokens` counts the prompt twice. The cache fields are absent on providers that report no cache split (Gemini reports reads only, since implicit caching bills no write) and on messages persisted before they existed, so read them as 0 when missing. Each bucket bills at a different rate — cache reads a fraction of uncached input, cache writes a premium, output highest — so a large token count at a small cost means the prompt was mostly cache hits. `externalCostUsd` is any non-LLM cost a widget reported for its own external service calls (folded into the session cost total alongside `cost`). On model-produced assistant messages, `model` is the concrete model id that generated it (e.g. 'gemini-2.5-flash-lite') and `providerName` is the registry slot it resolved under (e.g. a tier name like 'high'/'low', or the default); together they attribute the message — and any tool calls it carries — to an exact model even across a mid-session vendor/tier switch, where one slot name can map to different models before and after the switch. Both are undefined on any entry that is NOT an LLM response: non-assistant roles (user/tool/system-event) and 'synthetic-user' echoes; assistant interaction/widget entries (empty content carrying an `interaction` — a rendered widget, not a model turn); driver-authored assistant fallbacks (the timeout, repeated-malformed-call, and empty-response apology messages); and messages restored from a session persisted before these fields existed. One partial case: on a genuine model turn whose provider exposes no `getStatus` (or reports no model), `providerName` is still set but `model` alone is undefined. A 'synthetic-user' message is a display-only echo of an interaction outcome (e.g. the answer a widget reported): it renders on the user's side of the chat and `agentName` is the agent that created it, but it is never sent to the LLM — so it has no matching 'turn' and the model learns the outcome only from the corresponding tool result. An echo of an answer an interceptor (such as an autopilot) gave is NOT synthetic-user: see the delegated-messages paragraph.\",\n  'The autopilot (GENC-1660) runs on a driver of its own, and everything it did is harvested into this log: entries with delegate: autopilot and an agentName ending in › Autopilot are its turns (the decision message it was sent is the user message of its turn, so what it was shown is there verbatim; its systemPrompt is its grounding, such as the brief), its tool calls (widget_read, widget_act, hand_back, any read-only tools of its own, and its widget tools — reads with parameters that a widget type declares, routed to the interaction of that type being decided and refused with a reason when none is, offered on every decision so its tool list never changes; while one is open its tail starts with a line naming them) and their results (a read, view or widget tool, is capped at about 20,000 characters, cut with a note asking for less, and leaves its history at the end of the decision as a one-line note), and its own events. Its cost is already in the session total: it is booked as externalCostUsd on the interaction each decision answered, or, for a written question it answered, on the user message it sent on the user behalf (delegate: autopilot), so do not add its turns to that total. Spend that reached no message is recorded as autopilot.cost-dropped instead.',\n  \"Delegated messages (GENC-1660): a message with a `delegate` field was written or sent ON THE USER'S BEHALF by a driver decorator, and `delegate` names it (e.g. autopilot). The platform stamps it; nothing else can. It renders as the assistant whatever its role. A delegated `user` message was NOT typed by the user: it is an answer given on their behalf, and the model read it with `delegateFraming` in brackets in front of the content (the stored `content` is the bare text). A delegated `assistant` message is display-only (`excludeFromProvider`): the decorator's narration note, or, when its answer carried no note, the widget's own echo of the answer (its `userMessage`), shown as the assistant and never as the person. A widget answer a decorator gave with a note is not echoed at all: the note already says what was chosen. To tell what the person decided from what was decided for them, read `interaction.answeredBy` and these fields, never the role alone.\",\n  \"Sub-agent messages appear inline. When a tool delegates to a sub-agent (via `requestSubAgent`), the sub-agent's whole conversation — its own assistant/tool messages, each with their own `content`/`thinking`/`toolCalls`/`toolResult` and per-message `model`/`providerName`/`inputTokens`/`outputTokens`/`cacheReadTokens`/`cacheWriteTokens`/`cost` — is hoisted into the timeline as ordinary kind:'message' entries, interleaved by timestamp right after the tool call that spawned them (so you read the delegation top-to-bottom). A hoisted entry is marked: `subAgentDepth` is its delegation depth (1 for a sub-agent, 2 for a sub-agent's sub-agent, …), `subAgentOf` is the id of the parent tool call that spawned it (correlates it back even when two sub-agents run in one parent turn), `subAgentName` is the sub-agent's own name, and `agentName` is rewritten to a `\\\"<parent> › <sub-agent>\\\"` breadcrumb (composing when nested, e.g. `\\\"UI Builder › Planner › Grounding\\\"`). The sub-agent's per-LLM-call snapshots also surface as kind:'turn' entries with an N-M `turnIndex`, and subagent.started/completed (or subagent.failed) events bracket the run. Per-message `cost` on hoisted entries is already part of the session total (it is summed from the un-flattened history), so summing the top-level timeline does NOT double-count.\",\n  \"kind:'turn' — one LLM call. `turnIndex` is a string: a top-level turn is the bare counter ('0', '1', …); a sub-agent's turns are numbered under the parent turn that activated them ('3-1', '3-2', …, and a nested sub-agent contributes '3-2-1', …), and `agentName` names the agent that ran the turn. `systemPrompt` and `toolNames` are what the model saw. A systemPrompt of '<repeated — identical to turn N>' was byte-identical to turn N and de-duplicated; the full prompt is shown whenever it changes (often because a stateful agent advanced), so prompt evolution is visible.\",\n  \"kind:'turn'.`model`/`providerName`/`provider` — which model ran that call: the concrete model id, the registry slot it resolved under (a tier name like 'high'/'low', or the default), and the vendor. Recorded per CALL, so an agent whose `provider` selector varies by state — a flow that plans on a high tier and executes on a low one — has every step attributed, including calls that produced no message. `model` is the SERVING model where the provider reports one, so a turn answered by a server-side fallback names the model that answered rather than the one requested; it always matches the `model` on the message that call produced. Absent when the provider exposes no `getStatus` and the transport stamped nothing.\",\n  \"kind:'turn'.`usage` — what that ONE call cost, in the same four-bucket + `costUsd` shape as `sessionUsage`. Absent while a call is in flight and on providers that report no usage. This is the SAME money as the message the call produced, not extra money: never add turn usage to message usage, and read a turn plus its message as one charge. Its distinct value is the calls that produced NO message — a blank or refused response is billed and then discarded before the retry, so the turn entry is the only record of that spend, and a turn with `usage` but no message after it is exactly that. `costUsd: 0` alongside a nonzero token count means the provider reported no price, not that the call was free.\",\n  \"kind:'turn'.`agentSnapshot` — the active agent's own view of its internal state, captured at that turn. An agent opts into this by exposing a `getDebugSnapshot()` that returns JSON-serializable per-state info; stateful/flow agents wire it automatically, so you can watch a flow advance turn-by-turn (e.g. current step, cursor, collected fields, pending changes). Absent for agents that don't expose one.\",\n  \"kind:'event' — a meta/lifecycle event. `type` names it (see below); `detail` carries structured data. `detail.placement` is the emitting UI instance: 'bubble' (collapsed), 'panel' (popped-out), or 'standalone'.\",\n  \"Each 'event' also has an `importance`: 'high' (failures/limits — turn.error, tool.failed, subagent.failed, file.read-failed, suggestions.failed, context.threshold-crossed), 'normal' (session flow — connects, turns, retries, handoffs, agent/provider changes, interactions, sub-agent start/complete), or 'low' (skippable UI/bookkeeping noise — panel.toggled, attachment.added, driver.wired/unwired, context.updated, context.condensed). To skim, ignore importance:'low'; to triage a failure, filter to importance:'high' then read the nearby messages and turns. A 'high' turn.error is often preceded by one or more 'normal' turn.retry events for the same reason — read them together to see how many attempts were made before bailing. 'message' and 'turn' entries carry no importance — they are the substance, always read them.\",\n  'Event types: assistant.connected/disconnected (mount + placement + whether the session was created or restored), assistant.popout/popin (window placement), driver.created/wired/unwired (which driver is live and why it stops/starts responding across a popout), state.changed (idle↔loading), turn.start/turn.end (turn boundary; turn.end carries durationMs), turn.retry (a recoverable in-turn retry — detail.reason plus attempt/maxAttempts; for malformed calls also finishMessage; for empty responses also the provider finishReason + thoughtsTokens + parts breakdown), turn.error (a turn failed or hit a guardrail — detail.reason is one of exception/malformed-function-call/empty-response/unknown-tool-limit/max-iterations/response-truncated/refusal/budget-exhausted/provider-refused/context-exhausted/ai-service-error, plus reason-specific diagnostics: attempts (for empty-response also finishReason + thoughtsTokens + a parts breakdown, distinguishing a thinking-only STOP from a truly empty turn), finishMessage, for response-truncated the model + maxTokens + outputTokens + tools, unknownTools (split into staleTools — real earlier this activation but retired by the current state or hidden behind an open exclusive fold — and hallucinatedTools — never advertised) + availableTools, iterations + limit, for budget-exhausted the budgetUsd + spentUsd figures reported by the proxy plus the resolved vendor, for provider-refused the kind (spend|auth) plus the upstream status and error type — the vendor refusing the ACCOUNT rather than us refusing to spend, so the remedy is a top-up or a key rotation rather than a raised cap, and the kind is the only place that distinction survives because the user-facing copy is deliberately cause-free, for context-exhausted the estimated contextTokens against the guard that stopped the turn plus the iterations reached — the driver ending a runaway tool loop at the edge of the context window rather than issuing a request the provider would reject, so the transcript survives intact and can still be compacted, for ai-service-error the code (one of AI_SERVICE_ERROR_CODES, e.g. NO_API_KEY) and the status the AI service answered with — its own text goes to the browser console only, or name + message for exceptions), tool.failed (a tool threw), tool.unresolved (the model called a tool that could not be dispatched — detail.kind is folded/fold-hidden/stale/unknown, plus tool + agent and, for the counted kinds, the consecutive streak; the recurring lead-up to an unknown-tool-limit turn.error), subagent.started/completed/failed (the lifecycle of a `requestSubAgent` delegation — detail.agent names the sub-agent; these bracket the sub-agent turns that appear as kind:turn entries with an N-M `turnIndex`; subagent.failed also carries detail.reason, one of max_iterations/malformed_tool_call/empty_response/unknown_tool_limit/timeout/response_truncated/refusal/budget_exhausted/provider_refused/context_exhausted/ai_service_error; budget_exhausted and provider_refused are terminal for the PARENT turn too, and so is ai_service_error when the refusal is about the service rather than the request and came from the vendor the parent calls — the parent stops rather than calling the model again into the same wall; after context_exhausted the parent goes on, but its own next call is likely to stop on the same guard), agent.handoff (routing; from=null is the initial activation), agent.pinned/unpinned (forced routing), routing.decided (ONE PER ROUTING DECISION — see its own paragraph below), provider.selected (the resolved provider for the upcoming turns — detail.provider is the registry SLOT/tier name, detail.model the concrete model behind it and detail.vendor its vendor; emitted only when the slot CHANGES, so read the per-turn `model` for the model of any given call rather than assuming the nearest event still applies), interaction.requested/resolved (blocking user widgets — explain quiet gaps; note that when a sub-agent opens a widget, detail.agent — and the agentName on the interaction message — is the HOST agent that owns the widget, NOT the sub-agent that asked, because widgets render and resolve on the host driver; detail.ownerPath names the agents that actually asked, outermost first, the last being the one whose tool requested it, and detail.heldBy says who held it when it opened: user, or the id of the interceptor that claimed it, such as autopilot; on interaction.resolved, detail.answeredBy is who answered — the claimant id when it settled through its own hold, user for any other answer (a click counts as the person even on a widget a claimant held) — absent when it closed unanswered (a timeout or a stop), and absent too when it settled by itself other than through the hold of a claimant — a widget registered resolvesItself (one that does its work and settles on its own, asking the person nothing, such as a generation run), or one outcome its controller said settled itself (ctx.resolve with resolvedItself, such as a generation phase that failed outright before its review gate ever asked anything) — which then carries detail.resolvedItself: true instead, as the interaction message does — nobody answered it, and the platform cannot tell it finishing from the person interrupting it (a Skip), so only the result of the widget itself can say which; the same value is stamped on the interaction message as answeredBy and on the result the asking tool handler receives (absent there in the same cases), and when it is not user the tool result that interaction returned carries a decidedOnUsersBehalf record, so the model was told the choice was not made by the person; detail.edits, present only when non-zero, counts the editing actions a claimant ran on the widget before it was settled, whoever settled it, and those edits are stamped on the interaction message as edits, each with by, action, choice and args when it had some, in the order they ran, while a decidedOnUsersBehalf record carries their choice texts as edits, and when the person settled it after such edits the tool result carries an editedOnUsersBehalf record instead — the framing and those choice texts — so the model knows the widget was changed on the user behalf before the user answered, and that the user then confirmed it by finishing it), interaction.held (a claimant moved a pending interaction to the person or back to itself — detail.heldBy is the new holder, detail.claimant the interceptor; detail.late: true is an interceptor that declined it when it opened claiming it afterwards, such as the autopilot resumed while it was open; a widget held by anything but user was not answered by the person), interaction.claim-refused (a claim on a userOnly interaction, which stays with the person — detail.claimant + reason), autopilot.* (the autopilot, a decorator that answers interactions on behalf of the user — autopilot.claimed / autopilot.declined say whether it took each interaction and, for a decline, detail.reason: paused, other-flow, no-autopilot, unavailable, userOnly, policy or no-controller; one declined as paused that is still open when the person resumes the autopilot is looked at again, and the autopilot.claimed or autopilot.declined recorded for it then carries detail.onResume: true (a decline then can also be claimed-elsewhere, another interceptor having claimed it first); a restored mode looks at nothing; autopilot.decision-sent is what it was sent (detail.chars; detail.nothingEnabled: true when every action on the widget was unavailable — a gate whose controller said it was asking, such as a failed build the autopilot may not cancel — so it could only hand it back, which it may then do even after the person asked it to decide it itself; a widget whose controller says it is working (ctx.setWorking) is never sent a decision until it says it is asking, even when an action is enabled or the person resumes the autopilot); autopilot.acted is what it did (detail.action, detail.note, detail.finished); autopilot.handed-back is a decision it gave to the person (detail.reason and detail.trigger: model, no-decision or error); autopilot.paused / autopilot.resumed are mode changes (detail.scope, detail.trigger, detail.decideYourself when the person resumed during a hand-back; detail.trigger is restored when the mode came back with the session after a reload, applied once its flow re-activated, which starts nothing by itself); autopilot.error is the wrapper itself failing; autopilot.refinement counts a refining action against its step — a written answer (reply) or a widget action declared refines, such as a regenerate with instructions, counted together (detail.action, detail.stepKey, detail.count, detail.limitReached, after which every refining action is withdrawn for that step: not listed, and refused; the decision and every relisting of its actions say how many are left at the step, as a line Refinements left at this step: N, wherever the widget has a refining action); autopilot.handback-presented is the turn-level hand-back, shown when a working turn ended needing the person with no widget to hand over (detail.why: max-iterations, context-exhausted, failure or question; detail.options; detail.choice once answered); autopilot.catch-up is the autopilot being given the whole visible transcript at once (detail.why: first, for its first decision in a flow or after a reload; size, when its own history passed its budget and was rebuilt short — detail.ownChars; or compacted, when a compaction removed the last message it had seen, so it reads the summary and everything since, short; in each, what it had sent on the user behalf is included and labelled as its own, since its own history does not hold it); autopilot.cost-dropped is autopilot spend that no message carries, so it is NOT in the session total (detail.costUsd and detail.why: handed-back, aborted or stale for a written question it answered that no reply was sent for — stale when a pause, a resume, a new turn or the end of its flow came before the answer landed, which then went nowhere — or no-recorder when the driver had no way to book a decision to its interaction); a hand-back trigger can also be budget (the decision passed its spend cap), watchdog (its work went quiet: no ready surface and no heartbeat, or its own decision stalled with no model call landing, which stops that decision) or detached (the autopilot was removed while it held the interaction, which went to the person with no reason shown). To debug one autopilot decision, follow its interactionId: interaction.requested (heldBy), autopilot.claimed, autopilot.decision-sent, autopilot.acted or autopilot.handed-back, interaction.invoked, interaction.resolved (answeredBy), then the next turn of the working agent), interaction.invoked (a claimant ran one of the actions the widget itself exposes, through its hold, the same code the button runs — detail.claimant, detail.action (an option id, select or reply) and detail.finished, whether that settled the interaction, and when it did not, the run is recorded as an edit; the choice and narration it recorded reach the result of the tool that asked as decidedOnUsersBehalf), interaction.step (a long action run as named steps through runSteps, which survive a reload — detail.step and detail.outcome: started, done, skipped when the step was already done before a reload, or resumed when it started before a reload and runs again with what it saved part-way, such as a job id it re-attaches to), interaction.checkpoint (the checkpoints a conversation keeps for its long actions: the one in flight, and each one a reload cut, held apart until a request of its own widget type takes it over, so a resumed flow that opens other long widgets first, which save their own, loses nothing — detail.action: resumed when a reload cut the work and a request of the same widget type that the registration sameWork agrees is the same work took it over, refused when sameWork said a new request is different work (detail.saved is the identity it kept; detail.kept: true, since it stays for a later request of that type, and is offered to every one until one agrees) or when runSteps found the handed-over checkpoint malformed and started fresh (detail.reason, detail.saved), or cleared when its flow ended, once per checkpoint, with detail.cut: true for one a reload cut that nothing took over), context.updated/threshold-crossed (token + cost), context.condensed (a stale tool payload was collapsed out of the model-bound history by a `condenseWhen` declaration on the tool — detail.tool + toolCallId, target args|response, trigger (superseded:<key> or age:<n>), stubLen, and an estimated tokensSaved; stored history and this log keep the FULL payload, so the model-visible slice at any point is the full history minus the condensations recorded up to then), panel.toggled, attachment.added, file.read-failed, suggestions.failed.',\n  'Sub-agent meta events: a sub-agent\\'s own turn.retry/turn.error/tool.failed/tool.unresolved events are merged into this same timeline, tagged with `detail.subAgent` — a `\"<parent> › <sub-agent>\"` breadcrumb that composes when nested (e.g. `\"UI Builder › Planner › Grounding\"`) — and interleaved by their original timestamps within the subagent.started→completed/failed bracket. These are the per-attempt/per-failure signals that do NOT appear among the sub-agent\\'s (hoisted) messages: a malformed/empty attempt that gets retried produces no message, and the stale-vs-hallucinated split and streak counts live only on the event. A sub-agent\\'s high-volume, message-derivable events (turn.start/turn.end, provider.selected, context.updated) are intentionally NOT merged — read its hoisted messages for model/tokens/cost and turn-by-turn activity, and the bracketing subagent.* events for the run\\'s span.',\n  \"`meta` holds context captured at export time: agentSummary (full agent configs), context (active model, contextTokens/contextLimit/contextUsagePercent for the last call, and the session totals — sessionCostUsd, sessionTokensConsumed, and the four-bucket sessionUsage lifted to the top of this log), activeDebugSnapshot (the active agent's `getDebugSnapshot()` taken fresh at export — reflects state NOW, which may have advanced beyond the last turn's agentSnapshot), debug (optional host-supplied debug state), host, and the export timestamp.\",\n  'Note the two different scopes in `meta.context`: `contextTokens` is the prompt size of the LAST call (against `contextLimit`, the model context window), while `sessionUsage`/`sessionTokensConsumed` are cumulative BILLED throughput. Every turn resends the conversation, so the cumulative figure counts each turn’s prompt again in the next turn’s and is expected to dwarf the context size — that is not double-counting.',\n  \"kind:'event' type 'routing.decided' — how ONE user turn was routed, emitted by the orchestrating driver before the agent runs. Only a user turn is routed: a hand-off names its target, so the agents a hand-off runs show up as agent.handoff events, not as more routing.decided. `decision` is why that agent was chosen: 'classified' (the classifier ran and picked one), 'no-match' (it ran and answered -1 — nothing listed covers the request), 'pinned' (a user pin, an agent named for that one message by the send's `agent` option, or an active stateful flow owned the turn, so no call was made), 'single-candidate'/'no-specialists' (configuration left nothing to decide), 'provider-unavailable' (the registry default exposes no chat()), 'classifier-failed' (every attempt threw — `error` carries the last one). `to` names the agent and `fallback` says whether that agent is the fallback. `candidates` is what was ON THE BALLOT — every classifier-eligible specialist — in ballot order, so `index` — the classifier's own answer — indexes it directly. `candidates` is absent on the three decisions that put nothing to a vote — 'pinned', 'single-candidate', 'no-specialists'. It IS present on 'provider-unavailable', which is not an exception worth removing: the ballot was built there, it simply never got sent. `attempts` covers the retry ladder. `durationMs` is on EVERY routing.decided, and is the field to read when a decision looks wrong: the decisions that can reach the fallback ('no-match', 'no-specialists', 'provider-unavailable', 'classifier-failed') are told apart by the clock as much as by their name, because a fallback routing that resolved in tens of milliseconds made no network call at all whatever its `decision` says.\",\n  \"kind:'event' type 'routing.decided'.`usage` — what that classifier call cost, in the same four-bucket + costUsd shape as `sessionUsage`, plus `model`. Absent on the decisions that make no call (see 'pinned' and the configuration ones). THIS SPEND IS NOT IN `sessionUsage`: a classifier call never enters the transcript and `sessionUsage` is derived from the transcript, so classifier cost is missing from the session total by construction, not by accident. Sum these events to close that gap — it is the one component of a session's real spend that the totals cannot see.\",\n  'To debug a failure: find the last turn.error or tool.failed, then read upward for the user message, the turn(s), and the agent/provider/state events that led into it. For a turn that went to the wrong agent, read its routing.decided first — `decision` says whether anything was actually asked.',\n]",
           "description": "Human/agent-facing guide emitted as the first key of the exported debug log,\nso whoever opens the JSON (often an AI agent) knows how to read it without\nreverse-engineering the shape. Kept here next to the event catalogue it\ndescribes — but proximity alone demonstrably did NOT keep the two in sync\n(`refusal` was missing from both reason lists for a whole release), so\n`debug-event-log.test.ts` now asserts that every `TurnFailureReason` and every\n`SubAgentFailureReason` is named here, and fails the build when one is added\nwithout a matching sentence. Enumerations below read as exhaustive and WILL be\ntrusted by an agent reading the JSON — keep them so."
         }
       ],
@@ -13071,6 +13203,13 @@
               "type": {
                 "text": "readonly ChatMessage[]"
               }
+            },
+            {
+              "name": "suspended",
+              "default": "new Map()",
+              "type": {
+                "text": "ReadonlyMap<number, number>"
+              }
             }
           ],
           "description": "The entries to PERSIST alongside `history` (GENC-1632): every registered policy that has not\nfired yet and whose tool call is still in the transcript being saved, re-expressed as elapsed\nclock counts (see PersistedCondensePolicy).\n\n`history` is the transcript actually being written, not the driver's live one, because the two\ncan differ: a non-resumable save freezes at the last user message, and a compaction may have\nsummarised a call away. An entry whose call is not in the saved transcript has nothing to\ncollapse after a reload, so it is not written.\n\nPure, no writes to the registry — safe on a save path that runs on every autosave."
@@ -15950,7 +16089,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "The stateful-agent contract: which agent is active, whether a flow or a user pin holds routing,\nand the `onActivate` / `onDeactivate` lifecycle around a swap. Either driver can own one.\n\nKnows nothing about routing, tool surfaces or transcripts — whether an agent is terminal, the\ncontinuation tool, the handoff marker in history all stay with the orchestrator, which is the\nonly thing with agents to route between.",
+          "description": "The stateful-agent contract: which agent is active, whether a flow or a user pin holds routing,\nand the `onActivate` / `onDeactivate` lifecycle around a swap. Either driver can own one.\n\nKnows nothing about routing, tool surfaces or transcripts — whether an agent is terminal, the\nhand-off stack, the divider in history all stay with the orchestrator, which is the only thing\nwith agents to route between.",
           "name": "AgentSession",
           "members": [
             {
@@ -16008,6 +16147,23 @@
               "privacy": "private",
               "description": "The tail of the activation queue — see AgentSession.activate."
             },
+            {
+              "kind": "field",
+              "name": "suspended",
+              "type": {
+                "text": "AgentConfig[]"
+              },
+              "privacy": "private",
+              "default": "[]",
+              "description": "Callers waiting in a hand-off (GENC-1737), oldest first: still live, so never deactivated by\nthe hand-off, and resumed without `onActivate`. Empty after a reload, when a caller has no live\nstate and is activated again from its saved state instead."
+            },
+            {
+              "kind": "field",
+              "name": "handOffData",
+              "privacy": "private",
+              "default": "new Map<string, unknown>()",
+              "description": "The `data` of the hand-off that activated each agent (GENC-1737), for its tool handlers: kept\nwhile it is active or waits as a caller, and dropped when its activation ends."
+            },
             {
               "kind": "method",
               "name": "getActive",
@@ -16131,110 +16287,235 @@
             },
             {
               "kind": "method",
-              "name": "activate",
+              "name": "getHandOffData",
               "return": {
                 "type": {
-                  "text": "Promise<AgentTransition>"
+                  "text": "unknown"
                 }
               },
               "parameters": [
                 {
-                  "name": "agent",
+                  "name": "agentName",
                   "type": {
-                    "text": "AgentConfig"
+                    "text": "string"
                   }
                 }
               ],
-              "description": "Make `agent` active, firing the lifecycle hooks around the swap: outgoing `onDeactivate`\nfirst, then incoming `onActivate`. Both are awaited so heavy activation work (a machine\nrestore, say) completes before the agent's first turn runs, and a throw from either is logged\nrather than propagated — an agent whose hook fails still activates.\n\nRe-activating the same agent by name is not a switch: no hooks fire, no lock moves, and no\nhandoff is recorded. That guard matters because a per-turn re-resolve calls through here.\n\nSingle-flight (GENC-1662): calls run one after another, never interleaved. `active` is only\nset once the hooks have finished, so two overlapping calls for the same agent would otherwise\nboth see a switch and run `onActivate` twice — and a restored `init` would be overwritten by a\nfresh one that finished later. That overlap became possible when a restore started activating\nthe flow owner outside a turn, where a send can land mid-activation."
+              "description": "The `data` of the hand-off that activated `agentName`, if one did and carried any."
             },
             {
               "kind": "method",
-              "name": "activateNow",
-              "privacy": "private",
+              "name": "setHandOffData",
               "return": {
                 "type": {
-                  "text": "Promise<AgentTransition>"
+                  "text": "void"
                 }
               },
               "parameters": [
                 {
-                  "name": "agent",
+                  "name": "agentName",
                   "type": {
-                    "text": "AgentConfig"
+                    "text": "string"
+                  }
+                },
+                {
+                  "name": "data",
+                  "type": {
+                    "text": "unknown"
                   }
                 }
-              ]
+              ],
+              "description": "Record the `data` a hand-off activated `agentName` with, or restore it; `undefined` drops it."
             },
             {
               "kind": "method",
-              "name": "release",
+              "name": "dropFlowLock",
               "return": {
                 "type": {
-                  "text": "Promise<AgentTransition | undefined>"
+                  "text": "void"
                 }
               },
-              "description": "Release the active agent: fire `onDeactivate` and drop the flow lock.\n\nThe user pin is intentionally **not** cleared — someone who explicitly picked this agent\nshould stay on it after the flow ends, so the next message starts a fresh flow on the same\nagent rather than routing through the classifier.\n\nReturns `undefined` when there was no active agent, so a caller can skip its events."
+              "description": "Drop the flow lock and leave the active agent active (GENC-1737): a plain agent holding it with\nno hand-off behind it is done once its turn ends."
             },
             {
               "kind": "method",
-              "name": "reportTransition",
-              "privacy": "private",
+              "name": "getSuspended",
               "return": {
                 "type": {
-                  "text": "void"
+                  "text": "readonly AgentConfig[]"
+                }
+              },
+              "description": "The callers waiting in a hand-off whose state is live, oldest first."
+            },
+            {
+              "kind": "method",
+              "name": "handOff",
+              "return": {
+                "type": {
+                  "text": "Promise<AgentTransition>"
                 }
               },
               "parameters": [
                 {
-                  "name": "transition",
+                  "name": "target",
                   "type": {
-                    "text": "AgentTransition"
+                    "text": "AgentConfig"
+                  }
+                },
+                {
+                  "name": "options",
+                  "type": {
+                    "text": "{ suspendCaller: boolean }"
                   }
                 }
               ],
-              "description": "Hand a transition to the owner. A throwing listener is logged rather than propagated, for the\nsame reason a throwing hook is: the transition has already happened, and failing the caller\nwould leave it believing it had not."
+              "description": "Make `target` active for a hand-off (GENC-1737), holding the flow lock whatever kind of agent\nit is, since a waiting caller depends on it. With `suspendCaller` the active agent waits:\nit is not deactivated and keeps its state. Without it the active agent is deactivated as on\nany swap: a one-way hand-off from a target, whose waiting caller then waits for the new\ntarget. Queued with AgentSession.activate."
             },
             {
               "kind": "method",
-              "name": "dispose",
+              "name": "resume",
               "return": {
                 "type": {
-                  "text": "Promise<void>"
+                  "text": "Promise<AgentTransition>"
                 }
               },
-              "description": "Fire `onDeactivate` on the active agent and abort pending lifecycle work, for session\nteardown, so machines release resources cleanly. The session is not reusable afterwards: the\nabort signal stays aborted, so a later `activate` would hand its hook a dead signal.\n\n`onDeactivate` runs **before** the abort, deliberately: teardown that needs to flush state\nwould otherwise be handed an already-aborted signal and have to skip its own work. The cost is\nthat an `onActivate` still in flight keeps running until `onDeactivate` finishes — both hold\nthe same signal. Acceptable because the two are sequenced by `activate`, so overlap only\nhappens if a hook resolves before the work it started; a hook that must stop immediately\nshould own its own cancellation."
+              "parameters": [
+                {
+                  "name": "caller",
+                  "type": {
+                    "text": "AgentConfig"
+                  }
+                },
+                {
+                  "name": "lock",
+                  "type": {
+                    "text": "boolean"
+                  }
+                }
+              ],
+              "description": "Make a waiting caller active again when its hand-off ends (GENC-1737). One whose state is live\nresumes without `onActivate`, since it was never deactivated; after a reload it is activated\nfrom its saved state like any other agent. `lock` keeps the flow lock on it: it held it before,\nor another caller is still waiting further down."
             },
             {
               "kind": "method",
-              "name": "fireDeactivate",
-              "privacy": "private",
+              "name": "endSuspended",
               "return": {
                 "type": {
                   "text": "Promise<void>"
                 }
               },
+              "description": "Deactivate the callers left waiting by hand-offs that ended without a hand-back, newest first,\nwhen no teardown follows to do it (GENC-1737)."
+            },
+            {
+              "kind": "method",
+              "name": "activate",
+              "return": {
+                "type": {
+                  "text": "Promise<AgentTransition>"
+                }
+              },
               "parameters": [
                 {
                   "name": "agent",
                   "type": {
                     "text": "AgentConfig"
                   }
-                },
-                {
-                  "name": "reason",
-                  "type": {
-                    "text": "'switch' | 'release' | 'dispose'"
-                  }
                 }
               ],
-              "description": "The one place `onDeactivate` is invoked. `reason` only reaches the warning text, which is what\ntells a log reader which path fired."
-            }
-          ]
-        }
-      ],
-      "exports": [
-        {
-          "kind": "js",
+              "description": "Make `agent` active, firing the lifecycle hooks around the swap: outgoing `onDeactivate`\nfirst, then incoming `onActivate`. Both are awaited so heavy activation work (a machine\nrestore, say) completes before the agent's first turn runs, and a throw from either is logged\nrather than propagated — an agent whose hook fails still activates.\n\nRe-activating the same agent by name is not a switch: no hooks fire, no lock moves, and no\nhandoff is recorded. That guard matters because a per-turn re-resolve calls through here.\n\nSingle-flight (GENC-1662): calls run one after another, never interleaved. `active` is only\nset once the hooks have finished, so two overlapping calls for the same agent would otherwise\nboth see a switch and run `onActivate` twice — and a restored `init` would be overwritten by a\nfresh one that finished later. That overlap became possible when a restore started activating\nthe flow owner outside a turn, where a send can land mid-activation."
+            },
+            {
+              "kind": "method",
+              "name": "activateNow",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Promise<AgentTransition>"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "agent",
+                  "type": {
+                    "text": "AgentConfig"
+                  }
+                },
+                {
+                  "name": "{ lock = false, suspendPrevious = false }",
+                  "default": "{}"
+                }
+              ],
+              "description": "`lock` takes the flow lock whatever kind of agent it is, and `suspendPrevious` leaves the\noutgoing agent waiting instead of deactivating it, as a hand-off does (GENC-1737)."
+            },
+            {
+              "kind": "method",
+              "name": "release",
+              "return": {
+                "type": {
+                  "text": "Promise<AgentTransition | undefined>"
+                }
+              },
+              "description": "Release the active agent: fire `onDeactivate` and drop the flow lock.\n\nThe user pin is intentionally **not** cleared — someone who explicitly picked this agent\nshould stay on it after the flow ends, so the next message starts a fresh flow on the same\nagent rather than routing through the classifier.\n\nReturns `undefined` when there was no active agent, so a caller can skip its events."
+            },
+            {
+              "kind": "method",
+              "name": "reportTransition",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "transition",
+                  "type": {
+                    "text": "AgentTransition"
+                  }
+                }
+              ],
+              "description": "Hand a transition to the owner. A throwing listener is logged rather than propagated, for the\nsame reason a throwing hook is: the transition has already happened, and failing the caller\nwould leave it believing it had not."
+            },
+            {
+              "kind": "method",
+              "name": "dispose",
+              "return": {
+                "type": {
+                  "text": "Promise<void>"
+                }
+              },
+              "description": "Fire `onDeactivate` on the active agent and abort pending lifecycle work, for session\nteardown, so machines release resources cleanly. The session is not reusable afterwards: the\nabort signal stays aborted, so a later `activate` would hand its hook a dead signal.\n\n`onDeactivate` runs **before** the abort, deliberately: teardown that needs to flush state\nwould otherwise be handed an already-aborted signal and have to skip its own work. The cost is\nthat an `onActivate` still in flight keeps running until `onDeactivate` finishes — both hold\nthe same signal. Acceptable because the two are sequenced by `activate`, so overlap only\nhappens if a hook resolves before the work it started; a hook that must stop immediately\nshould own its own cancellation."
+            },
+            {
+              "kind": "method",
+              "name": "fireDeactivate",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Promise<void>"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "agent",
+                  "type": {
+                    "text": "AgentConfig"
+                  }
+                },
+                {
+                  "name": "reason",
+                  "type": {
+                    "text": "'switch' | 'release' | 'dispose'"
+                  }
+                }
+              ],
+              "description": "The one place `onDeactivate` is invoked. `reason` only reaches the warning text, which is what\ntells a log reader which path fired."
+            }
+          ]
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
           "name": "AgentSession",
           "declaration": {
             "name": "AgentSession",
@@ -16592,6 +16873,102 @@
                 }
               ]
             },
+            {
+              "kind": "method",
+              "name": "getHandOffStack",
+              "return": {
+                "type": {
+                  "text": "HandOffFrame[]"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "restoreHandOffStack",
+              "return": {
+                "type": {
+                  "text": "{ resume?: { agent: string; note: string }; droppedLocks?: string[] }"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "saved",
+                  "type": {
+                    "text": "unknown"
+                  }
+                },
+                {
+                  "name": "savedStates",
+                  "type": {
+                    "text": "Record<string, unknown>"
+                  }
+                },
+                {
+                  "name": "interrupted",
+                  "type": {
+                    "text": "boolean"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "unwindHandOffs",
+              "return": {
+                "type": {
+                  "text": "Promise<void>"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "kind",
+                  "type": {
+                    "text": "Extract<HandOffOutcomeKind, 'cleared' | 'state-lost'>"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "serializeWaitingCallers",
+              "return": {
+                "type": {
+                  "text": "Record<string, unknown>"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "getHandOffData",
+              "return": {
+                "type": {
+                  "text": "Record<string, unknown>"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "restoreHandOffData",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "saved",
+                  "type": {
+                    "text": "unknown"
+                  }
+                },
+                {
+                  "name": "interrupted",
+                  "type": {
+                    "text": "boolean"
+                  }
+                }
+              ]
+            },
             {
               "kind": "method",
               "name": "getActiveAgent",
@@ -17670,24 +18047,6 @@
           },
           "default": "new Set([\n  'turn.retry',\n  'turn.error',\n  'tool.failed',\n  'tool.unresolved',\n])",
           "description": "Sub-agent meta events worth folding into the parent's debug timeline: the\nper-attempt and per-failure signals that do NOT otherwise surface in the\nsub-agent's (now hoisted) messages — a retried-away malformed/empty attempt\nproduces no message, and the stale-vs-hallucinated/streak diagnostics live only\non the event. High-volume, message-derivable events (turn.start/turn.end,\nprovider.selected, context.updated) are intentionally excluded: read the\nsub-agent's hoisted messages for model/tokens/cost and turn-by-turn activity.\nSee `ChatDriver.invokeSubAgent`."
-        },
-        {
-          "kind": "variable",
-          "name": "REQUEST_CONTINUATION_TOOL",
-          "type": {
-            "text": "string"
-          },
-          "default": "'request_continuation'",
-          "description": "Name reserved for the cross-agent handoff tool — injected by OrchestratingDriver."
-        },
-        {
-          "kind": "variable",
-          "name": "HANDOFF_TOOL_RESULT_PLACEHOLDER",
-          "type": {
-            "text": "string"
-          },
-          "default": "'Handoff to another specialist — routing continues on the next turn.'",
-          "description": "Paired in history for each `request_continuation` so tool_calls stay balanced for the provider."
         }
       ],
       "exports": [
@@ -17778,22 +18137,6 @@
             "name": "HARVESTED_SUBAGENT_EVENTS",
             "module": "src/components/chat-driver/chat-driver.constants.ts"
           }
-        },
-        {
-          "kind": "js",
-          "name": "REQUEST_CONTINUATION_TOOL",
-          "declaration": {
-            "name": "REQUEST_CONTINUATION_TOOL",
-            "module": "src/components/chat-driver/chat-driver.constants.ts"
-          }
-        },
-        {
-          "kind": "js",
-          "name": "HANDOFF_TOOL_RESULT_PLACEHOLDER",
-          "declaration": {
-            "name": "HANDOFF_TOOL_RESULT_PLACEHOLDER",
-            "module": "src/components/chat-driver/chat-driver.constants.ts"
-          }
         }
       ]
     },
@@ -18067,7 +18410,7 @@
                 "text": "{ result: unknown } | undefined"
               },
               "privacy": "private",
-              "description": "Set by `completeSubAgent` inside a sub-agent tool handler. Checked at the\nsame point in the loop as `REQUEST_CONTINUATION_TOOL` — after tool results\nare appended — so the exit path mirrors the system-call pattern.\n`undefined` means the loop has not been stopped early."
+              "description": "Set by `completeSubAgent` inside a sub-agent tool handler. Checked after tool\nresults are appended, so the turn ends without another model call.\n`undefined` means the loop has not been stopped early."
             },
             {
               "kind": "field",
@@ -18098,6 +18441,51 @@
               "default": "false",
               "description": "Set by `releaseAgent` inside a top-level tool handler — typically a stateful\nagent's terminal-state handler signalling that its flow is complete and the\nauto-pin lock can release. Checked by the orchestrator after `sendMessage`\nreturns; the orchestrator fires `onDeactivate` and clears the pin.\n\nReset at the start of each `sendMessage` so a release from a previous turn\ndoesn't leak forward."
             },
+            {
+              "kind": "field",
+              "name": "handOffRequested",
+              "type": {
+                "text": "HandOffRequest | undefined"
+              },
+              "privacy": "private",
+              "description": "A `handOff` this call accepted, for the orchestrator to act on after it (GENC-1737)."
+            },
+            {
+              "kind": "field",
+              "name": "handOffCompletion",
+              "type": {
+                "text": "HandOffCompletion | undefined"
+              },
+              "privacy": "private",
+              "description": "What `completeHandOff` handed back this call, beside the release it also requests."
+            },
+            {
+              "kind": "field",
+              "name": "checkHandOff",
+              "type": {
+                "text": "(request: HandOffRequest, caller: string | undefined) => HandOffResult | undefined"
+              },
+              "privacy": "private",
+              "description": "See ChatDriver.setHandOffCheck."
+            },
+            {
+              "kind": "field",
+              "name": "suspendedActivations",
+              "privacy": "private",
+              "readonly": true,
+              "default": "new Map<\n    string,\n    { activation: number; phaseEpoch: number }\n  >()",
+              "description": "The `agentEnd` activation of each caller waiting in a hand-off, by agent name, with the phase\nepoch it was suspended at (GENC-1737). A waiting caller is suspended, not ended, so neither its\n`agentEnd` payloads nor its `phaseEnd` ones (to another agent's `endPhase()`) collapse while the\ntarget runs; when it is installed again its entries move to the new activation and, while\ntheir phase had not ended, to the current epoch. A caller restored from a saved session gets\nan activation placeholder below zero, which no live activation uses."
+            },
+            {
+              "kind": "field",
+              "name": "restoredSuspensionSeq",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "0",
+              "description": "The last placeholder handed out for a restored caller; see `suspendedActivations`."
+            },
             {
               "kind": "field",
               "name": "turnRecorder",
@@ -18754,13 +19142,7 @@
                   "text": "boolean"
                 }
               },
-              "parameters": [
-                {
-                  "name": "handingOff",
-                  "default": "false"
-                }
-              ],
-              "description": "Whether a sub-agent hit a wall this turn that stops this driver too. A handoff goes on past an\nAI-service wall: the next agent may use another vendor, and if it uses this one its own call\nmeets the wall and says so."
+              "description": "Whether a sub-agent hit a wall this turn that stops this driver too."
             },
             {
               "kind": "method",
@@ -18771,7 +19153,7 @@
                   "text": "ChatDriverResult | undefined"
                 }
               },
-              "description": "Ends the turn when a sub-agent hit a wall this turn that stops this driver too: the provider\nrefusing the account, the AI service (GENC-1611), or the budget. Checked before each model call,\nand again right after a tool batch, before a handoff or the iteration cap can report the turn as\nsomething else."
+              "description": "Ends the turn when a sub-agent hit a wall this turn that stops this driver too: the provider\nrefusing the account, the AI service (GENC-1611), or the budget. Checked before each model call,\nand again right after a tool batch, before the iteration cap can report the turn as something\nelse."
             },
             {
               "kind": "method",
@@ -19159,41 +19541,167 @@
             },
             {
               "kind": "method",
-              "name": "releaseIfRequested",
-              "privacy": "private",
+              "name": "getHandOffRequest",
               "return": {
                 "type": {
-                  "text": "Promise<void>"
+                  "text": "HandOffRequest | undefined"
                 }
               },
-              "description": "Act on a `releaseAgent` call from a tool handler: fire `onDeactivate` and drop the flow lock,\nso the next turn starts clean and the persister does not serialize a flow that is over.\n\nNo-op when the owner handles release (ChatDriverConfig.deferAgentRelease). The flag is\ncleared here rather than only at the next `sendMessage`, so the signal cannot be acted on twice\nand release a later agent that never asked."
+              "description": "The `handOff` the most recent call accepted, if any (GENC-1737)."
             },
             {
               "kind": "method",
-              "name": "getTurnSnapshots",
+              "name": "getHandOffCompletion",
               "return": {
                 "type": {
-                  "text": "ReadonlyArray<TurnSnapshot>"
+                  "text": "HandOffCompletion | undefined"
                 }
               },
-              "description": "Return the per-turn snapshots captured so far. Used by the host's debug\nlog exporter to show what the LLM saw on each turn — system prompt, tool\nsurface, and agent-supplied state (e.g. a machine snapshot).\n\nRing-buffered at `maxTurnSnapshots`; older entries are dropped."
+              "description": "What `completeHandOff` handed back in the most recent call, if it was called."
             },
             {
               "kind": "method",
-              "name": "getExternalDiagnostics",
+              "name": "requestHandOff",
+              "privacy": "private",
               "return": {
                 "type": {
-                  "text": "ReadonlyArray<DiagnosticEntry>"
+                  "text": "HandOffResult"
                 }
               },
-              "description": "The `turn` + `message` diagnostic-log entries harvested from resolved interactions'\n`InteractionResult.diagnostics` (e.g. a server-side ChatDriver's collated debug log). The host\nconcatenates these into its own debug log so `downloadDebugLog`/the persisted diagnostics stream\ninclude external-engine logs; `event` entries are excluded here because they're merged into the\nsession's meta-event registry instead and reach the log via `getMetaEvents`. Opaque,\nchronologically sorted by the host at assemble time. (GENC-1461.)"
+              "parameters": [
+                {
+                  "name": "request",
+                  "type": {
+                    "text": "HandOffRequest"
+                  }
+                }
+              ],
+              "description": "A handler's `handOff`: refused once this call has handed off or released, or when `data` is\nnot JSON, and otherwise checked by the orchestrator. `data` is kept as a JSON copy, since it is\nsaved with the session and the handler may change its own object afterwards."
             },
             {
-              "kind": "field",
-              "name": "contextGuard",
-              "type": {
-                "text": "ContextGuardPolicy | undefined"
-              },
+              "kind": "method",
+              "name": "closingCallNote",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "string | undefined"
+                }
+              },
+              "description": "The note of the closing call a hand-off asks for (GENC-1737), or `undefined` when none: once a\nhandler's `handOff` is accepted, or `completeHandOff` is called, the rest of that batch runs,\nthen one model call with no tools, so the agent can say so but not carry on, which a model told\nso in a tool result does anyway. Then the turn ends."
+            },
+            {
+              "kind": "method",
+              "name": "suspendActivation",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "agentName",
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ],
+              "description": "Suspend the active agent's activation for a hand-off it made (GENC-1737): installing the target\nadvances the `agentEnd` clock as any swap does, but this caller's payloads stay live."
+            },
+            {
+              "kind": "method",
+              "name": "suspendRestoredActivations",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "agentNames",
+                  "type": {
+                    "text": "readonly string[]"
+                  }
+                }
+              ],
+              "description": "Suspend restored callers before their condense policies are restored, so entries still live\nat save time stay live instead of waiting for \"the next activation\", which is the target's."
+            },
+            {
+              "kind": "method",
+              "name": "endSuspendedActivations",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "End every suspension: the hand-offs were unwound, so their callers' activations are over."
+            },
+            {
+              "kind": "method",
+              "name": "resumeSuspendedActivation",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "agentName",
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ],
+              "description": "A caller installed again takes its suspended entries into the activation it resumes in, and\nthe ones whose phase had not ended into the current phase epoch."
+            },
+            {
+              "kind": "method",
+              "name": "suspendedClocks",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "ReadonlyMap<number, number>"
+                }
+              },
+              "description": "The suspended activations, each with the phase epoch it was suspended at, for the `agentEnd`\nand `phaseEnd` checks and for persistence."
+            },
+            {
+              "kind": "method",
+              "name": "releaseIfRequested",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Promise<void>"
+                }
+              },
+              "description": "Act on a `releaseAgent` call from a tool handler: fire `onDeactivate` and drop the flow lock,\nso the next turn starts clean and the persister does not serialize a flow that is over.\n\nNo-op when the owner handles release (ChatDriverConfig.deferAgentRelease). The flag is\ncleared here rather than only at the next `sendMessage`, so the signal cannot be acted on twice\nand release a later agent that never asked."
+            },
+            {
+              "kind": "method",
+              "name": "getTurnSnapshots",
+              "return": {
+                "type": {
+                  "text": "ReadonlyArray<TurnSnapshot>"
+                }
+              },
+              "description": "Return the per-turn snapshots captured so far. Used by the host's debug\nlog exporter to show what the LLM saw on each turn — system prompt, tool\nsurface, and agent-supplied state (e.g. a machine snapshot).\n\nRing-buffered at `maxTurnSnapshots`; older entries are dropped."
+            },
+            {
+              "kind": "method",
+              "name": "getExternalDiagnostics",
+              "return": {
+                "type": {
+                  "text": "ReadonlyArray<DiagnosticEntry>"
+                }
+              },
+              "description": "The `turn` + `message` diagnostic-log entries harvested from resolved interactions'\n`InteractionResult.diagnostics` (e.g. a server-side ChatDriver's collated debug log). The host\nconcatenates these into its own debug log so `downloadDebugLog`/the persisted diagnostics stream\ninclude external-engine logs; `event` entries are excluded here because they're merged into the\nsession's meta-event registry instead and reach the log via `getMetaEvents`. Opaque,\nchronologically sorted by the host at assemble time. (GENC-1461.)"
+            },
+            {
+              "kind": "field",
+              "name": "contextGuard",
+              "type": {
+                "text": "ContextGuardPolicy | undefined"
+              },
               "privacy": "private",
               "description": "Mid-loop context guard policy (GENC-1567). `undefined` disables the guard.\n\nCarries a MARGIN rather than an absolute threshold, and the difference is the\nwhole point: the threshold depends on the window of whichever provider the\nnext call resolves to, which the driver learns during the call and the host\ncannot know until afterwards. The host owns the policy; the driver applies it\nagainst the model actually being addressed."
             },
@@ -20116,14 +20624,6 @@
             "module": "./chat-driver.constants"
           }
         },
-        {
-          "kind": "js",
-          "name": "REQUEST_CONTINUATION_TOOL",
-          "declaration": {
-            "name": "REQUEST_CONTINUATION_TOOL",
-            "module": "./chat-driver.constants"
-          }
-        },
         {
           "kind": "js",
           "name": "TurnSnapshot",
@@ -22212,6 +22712,124 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/components/orchestrating-driver/hand-off.ts",
+      "declarations": [
+        {
+          "kind": "function",
+          "name": "handOffNote",
+          "return": {
+            "type": {
+              "text": "string"
+            }
+          },
+          "parameters": [
+            {
+              "name": "caller",
+              "type": {
+                "text": "string"
+              }
+            }
+          ],
+          "description": "The tail note a hand-off's target runs its first call with (GENC-1737). The brief itself is in\nthe transcript, as a message delegated by the caller, so the request already closes on it."
+        },
+        {
+          "kind": "function",
+          "name": "handBackNote",
+          "return": {
+            "type": {
+              "text": "string"
+            }
+          },
+          "parameters": [
+            {
+              "name": "frame",
+              "type": {
+                "text": "HandOffFrame"
+              }
+            },
+            {
+              "name": "outcome",
+              "type": {
+                "text": "HandOffOutcome"
+              }
+            }
+          ],
+          "description": "The tail note a caller resumes with when its hand-off ends (GENC-1737). It quotes nothing: a\ncompleted target's summary is in the transcript as a message it handed back, and a released\ntarget's last reply already is."
+        },
+        {
+          "kind": "function",
+          "name": "frameCopy",
+          "return": {
+            "type": {
+              "text": "HandOffFrame"
+            }
+          },
+          "parameters": [
+            {
+              "name": "frame",
+              "type": {
+                "text": "HandOffFrame"
+              }
+            }
+          ],
+          "description": "A copy of `frame` for a hook or an event, so a host that changes it changes neither the stack\nnor what is saved. Frames are JSON."
+        },
+        {
+          "kind": "function",
+          "name": "parseHandOffFrames",
+          "return": {
+            "type": {
+              "text": "HandOffFrame[]"
+            }
+          },
+          "parameters": [
+            {
+              "name": "saved",
+              "type": {
+                "text": "unknown"
+              }
+            }
+          ],
+          "description": "The saved frames that are frames, oldest first. The snapshot is parsed data."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "handOffNote",
+          "declaration": {
+            "name": "handOffNote",
+            "module": "src/components/orchestrating-driver/hand-off.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "handBackNote",
+          "declaration": {
+            "name": "handBackNote",
+            "module": "src/components/orchestrating-driver/hand-off.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "frameCopy",
+          "declaration": {
+            "name": "frameCopy",
+            "module": "src/components/orchestrating-driver/hand-off.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "parseHandOffFrames",
+          "declaration": {
+            "name": "parseHandOffFrames",
+            "module": "src/components/orchestrating-driver/hand-off.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/components/orchestrating-driver/index.ts",
@@ -22268,7 +22886,7 @@
           "kind": "variable",
           "name": "UNROUTABLE_INSTRUCTION",
           "default": "`When the request is substantive but nothing above covers it, say so directly. Do not offer to do it yourself, and do not imply a specialist will pick it up.\n\nIf the user's message is a short follow-up to something already discussed — \"fix it\", \"try again\", \"why?\" — read it against the conversation above and answer that, rather than treating it as a new request with no context.\n\nNever end your turn without saying something. An empty reply is never a valid response: if you genuinely cannot help, say briefly that you cannot, and why.`",
-          "description": "The instruction a fallback agent needs and, left to itself, tends not to have.\n\nA fallback prompt written by a consumer reliably covers two cases — small talk, and a request\nthat belongs to a specialist — because those are the ones you think of when you write it. The\ncase it exists FOR is the third: a substantive request that no specialist covers, and no way to\nact on it, because a fallback holds no tools and is denied the continuation tool as a leaf.\n\nCreate's fallback prompt is the worked example (GENC-1573). It covered chit-chat and\n\"out of scope, here are the specialists\", said nothing about a request nothing can serve, and\nnothing about a terse follow-up (\"fix it\", \"try again\") aimed at an answer already given. Asked\nto fix a Kotlin null pointer no agent could touch, it returned nine blank turns across three\npage loads — a model with no instruction covering its situation and no tool to reach for.\n\nSo the framework supplies it. Appended to a string-form prompt (or substituted at\nUNROUTABLE_PLACEHOLDER if the consumer positions it), because a fallback with no answer\nfor its own reason to exist is a defect in every host, not a matter of taste. It is additive and\nstatic: being fixed it cannot destabilise a cached prefix, and the fallback prompt already\nchanges whenever the agents array does (`{{agents}}` interpolates the specialist list). The\nfunction form still passes through untouched — a consumer that wants full control has it there.\n\nDELIBERATELY CONFINED TO WHAT A TERSE PROMPT CAN ALSO OBEY, and it must stay that way. Since\nthis is appended by default it lands on top of prompts written with their own tone rules, and\nan earlier draft asked the model to \"state what you can establish… and suggest what the user\ncould do next\" — a direct contradiction of strictFallbackAgent, a preset THIS PACKAGE\nships, whose whole instruction is \"a single short sentence… Do not elaborate\". What is left\nhere is compatible with brevity: say so, don't promise work you cannot do, read a short\nfollow-up in context, and never answer with nothing. Adding anything that presumes room to\nelaborate breaks a shipped preset — put it in the consumer's own prompt instead."
+          "description": "The instruction a fallback agent needs and, left to itself, tends not to have.\n\nA fallback prompt written by a consumer reliably covers two cases — small talk, and a request\nthat belongs to a specialist — because those are the ones you think of when you write it. The\ncase it exists FOR is the third: a substantive request that no specialist covers, and no way to\nact on it, because a fallback holds no tools.\n\nCreate's fallback prompt is the worked example (GENC-1573). It covered chit-chat and\n\"out of scope, here are the specialists\", said nothing about a request nothing can serve, and\nnothing about a terse follow-up (\"fix it\", \"try again\") aimed at an answer already given. Asked\nto fix a Kotlin null pointer no agent could touch, it returned nine blank turns across three\npage loads — a model with no instruction covering its situation and no tool to reach for.\n\nSo the framework supplies it. Appended to a string-form prompt (or substituted at\nUNROUTABLE_PLACEHOLDER if the consumer positions it), because a fallback with no answer\nfor its own reason to exist is a defect in every host, not a matter of taste. It is additive and\nstatic: being fixed it cannot destabilise a cached prefix, and the fallback prompt already\nchanges whenever the agents array does (`{{agents}}` interpolates the specialist list). The\nfunction form still passes through untouched — a consumer that wants full control has it there.\n\nDELIBERATELY CONFINED TO WHAT A TERSE PROMPT CAN ALSO OBEY, and it must stay that way. Since\nthis is appended by default it lands on top of prompts written with their own tone rules, and\nan earlier draft asked the model to \"state what you can establish… and suggest what the user\ncould do next\" — a direct contradiction of strictFallbackAgent, a preset THIS PACKAGE\nships, whose whole instruction is \"a single short sentence… Do not elaborate\". What is left\nhere is compatible with brevity: say so, don't promise work you cannot do, read a short\nfollow-up in context, and never answer with nothing. Adding anything that presumes room to\nelaborate breaks a shipped preset — put it in the consumer's own prompt instead."
         },
         {
           "kind": "class",
@@ -22357,7 +22975,7 @@
               },
               "privacy": "private",
               "default": "false",
-              "description": "Set by `cancel()` for the duration of a `sendMessage` run. Breaks the\nhandoff loop so we don't classify or start another agent turn after the\nuser stops. Reset at the start of each `sendMessage`."
+              "description": "Set by `cancel()` for the duration of a run. Stops it before the next agent\nruns — a hand-off's target or a hand-back's caller — so nothing more is asked\nof a provider after the user stops. Reset at the start of each run."
             },
             {
               "kind": "field",
@@ -22367,7 +22985,46 @@
               },
               "privacy": "private",
               "default": "false",
-              "description": "Whether the CURRENT turn's user message has reached the inner driver's\nhistory. False through the pre-first-turn classify (where the only echo of\nthe message is an optimistic `history-updated` dispatch), true from the\nmoment `chatDriver.sendMessage` is entered — including through every later\nhandoff classify. Read by the budget-wall catch in `sendMessage` to decide\nwhether `reportBudgetExhausted` must append the message itself: appending\nit when already appended duplicated it; not appending it when unappended\nmade it vanish. Reset at the top of each `runOrchestratedTurn`."
+              "description": "Whether the CURRENT turn's user message has reached the inner driver's\nhistory. False through the pre-first-turn classify (where the only echo of\nthe message is an optimistic `history-updated` dispatch), true from the\nmoment `chatDriver.sendMessage` is entered. Read by the budget-wall catch in\n`sendMessage` to decide\nwhether `reportBudgetExhausted` must append the message itself: appending\nit when already appended duplicated it; not appending it when unappended\nmade it vanish. Reset at the top of each `runOrchestratedTurn`."
+            },
+            {
+              "kind": "field",
+              "name": "maxHandOffDepth",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "readonly": true,
+              "description": "How many callers may wait in hand-offs at once (GENC-1737)."
+            },
+            {
+              "kind": "field",
+              "name": "handOffStack",
+              "type": {
+                "text": "HandOffFrame[]"
+              },
+              "privacy": "private",
+              "default": "[]",
+              "description": "The hand-offs in progress, oldest first (GENC-1737). The top frame's target is the active agent\nand holds the flow lock; each caller waits, suspended, for the target above it. Saved with the\nsession through OrchestratingDriver.getHandOffStack."
+            },
+            {
+              "kind": "field",
+              "name": "handOffsThisTurn",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "0",
+              "description": "Hand-offs and hand-backs this user turn, against `maxHandoffs`."
+            },
+            {
+              "kind": "field",
+              "name": "pendingHandBack",
+              "type": {
+                "text": "{ frame: HandOffFrame; resumed: boolean } | undefined"
+              },
+              "privacy": "private",
+              "description": "A hand-back a restore found due — the top frame's target had finished, or has gone — which\nOrchestratingDriver.resumeRestoredFlow carries out."
             },
             {
               "kind": "field",
@@ -22375,215 +23032,617 @@
               "type": {
                 "text": "AgentConfig | undefined"
               },
-              "description": "The active agent, or `undefined` before the first activation and after a release.\n\nKept as an accessor over `agentSession` rather than removed: it is a public member of an\nexported class, so nothing in this package reading it is not the same as nothing reading it.",
-              "readonly": true
+              "description": "The active agent, or `undefined` before the first activation and after a release.\n\nKept as an accessor over `agentSession` rather than removed: it is a public member of an\nexported class, so nothing in this package reading it is not the same as nothing reading it.",
+              "readonly": true
+            },
+            {
+              "kind": "method",
+              "name": "createInner",
+              "privacy": "private",
+              "static": true,
+              "return": {
+                "type": {
+                  "text": "ChatDriver"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "providerRegistry",
+                  "type": {
+                    "text": "AIProviderRegistry"
+                  }
+                },
+                {
+                  "name": "agents",
+                  "type": {
+                    "text": "AgentConfig[]"
+                  }
+                },
+                {
+                  "name": "options",
+                  "default": "{}",
+                  "type": {
+                    "text": "ConstructorParameters<typeof OrchestratingDriver>[2]"
+                  }
+                }
+              ],
+              "description": "Build the inner driver, after validating the agents' providers, so a bad config throws before\na driver exists to subscribe to the registry. Static because it runs before `super()`."
+            },
+            {
+              "kind": "method",
+              "name": "getSuggestions",
+              "return": {
+                "type": {
+                  "text": "Promise<string[]>"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "history",
+                  "type": {
+                    "text": "ChatMessage[]"
+                  }
+                },
+                {
+                  "name": "prompt",
+                  "type": {
+                    "text": "string"
+                  }
+                },
+                {
+                  "name": "count",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "allAgentInfo",
+                  "optional": true,
+                  "type": {
+                    "text": "AllAgentSummary[]"
+                  }
+                }
+              ],
+              "inheritedFrom": {
+                "name": "BaseDriverDecorator",
+                "module": "src/components/ai-driver/base-driver-decorator.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "sendMessage",
+              "return": {
+                "type": {
+                  "text": "Promise<ChatDriverResult>"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "input",
+                  "type": {
+                    "text": "string"
+                  }
+                },
+                {
+                  "name": "attachments",
+                  "optional": true,
+                  "type": {
+                    "text": "ChatAttachment[]"
+                  }
+                },
+                {
+                  "name": "options",
+                  "optional": true,
+                  "type": {
+                    "text": "SendMessageOptions"
+                  }
+                }
+              ],
+              "inheritedFrom": {
+                "name": "BaseDriverDecorator",
+                "module": "src/components/ai-driver/base-driver-decorator.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "runOrchestratedTurn",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Promise<ChatDriverResult>"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "input",
+                  "type": {
+                    "text": "string"
+                  }
+                },
+                {
+                  "name": "attachments",
+                  "type": {
+                    "text": "ChatAttachment[] | undefined"
+                  }
+                },
+                {
+                  "name": "options",
+                  "type": {
+                    "text": "SendMessageOptions | undefined"
+                  }
+                },
+                {
+                  "name": "delegated",
+                  "type": {
+                    "text": "Pick<ChatMessage, 'delegate' | 'delegateFraming' | 'externalCostUsd'>"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "carryOn",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Promise<ChatDriverResult>"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "result",
+                  "type": {
+                    "text": "ChatDriverResult"
+                  }
+                }
+              ],
+              "description": "Act on what the agent call that just ended asked for, and run the next agent in the same user\nturn while there is one (GENC-1737): a `handOff` runs its target with the brief, and a target\nthat releases hands back to its caller. Returns the last call's result.\n\nA failed call ends the turn there, as a Stop does: what it asked for still happens, and the\nnext agent runs on the next message. Running it now would meet the same wall (a budget, a\nrefused account, a full context window), or build on a reply that never came."
+            },
+            {
+              "kind": "method",
+              "name": "afterAgentCall",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Promise<string | undefined>"
+                }
+              },
+              "description": "After one agent call: start the hand-off it asked for, or release it and, when it was a\nhand-off's target, hand back. Returns the tail note for the agent to run next, or `undefined`\nwhen the turn ends here.\n\nA plain target hands back when its call ends, released or not, as a plain agent is done once\nit has answered. A stateful one holds the hand-off until it releases, as it holds its flow."
+            },
+            {
+              "kind": "method",
+              "name": "outcomeOf",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "HandOffOutcome"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "frame",
+                  "type": {
+                    "text": "HandOffFrame"
+                  }
+                }
+              ],
+              "description": "How the target of `frame` finished: with `completeHandOff`, or a release and its last reply."
+            },
+            {
+              "kind": "method",
+              "name": "endPlainTurn",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "agent",
+                  "type": {
+                    "text": "AgentConfig"
+                  }
+                }
+              ],
+              "description": "A plain agent is done once it has answered (GENC-1737): the data a one-way hand-off gave it ends\nwith its turn, and so does a flow lock no hand-off holds, such as one a restore left on a\ntarget whose hand-off it could not resume."
+            },
+            {
+              "kind": "method",
+              "name": "canRestoreFlowOwner",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "agentName",
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ],
+              "description": "{@inheritDoc AiDriver.canRestoreFlowOwner}",
+              "inheritedFrom": {
+                "name": "BaseDriverDecorator",
+                "module": "src/components/ai-driver/base-driver-decorator.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "canResumeRestoredFlow",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "agentName",
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ],
+              "description": "{@inheritDoc AiDriver.canResumeRestoredFlow}",
+              "inheritedFrom": {
+                "name": "BaseDriverDecorator",
+                "module": "src/components/ai-driver/base-driver-decorator.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "resumeRestoredFlow",
+              "return": {
+                "type": {
+                  "text": "Promise<ChatDriverResult | undefined>"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "resumeNote",
+                  "optional": true,
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ],
+              "description": "{@inheritDoc AiDriver.resumeRestoredFlow}\n\nInstalls the flow owner directly rather than through `handleTurn`: there is no user message\nto classify, and a restored lock already says which agent owns the flow. `continueFromHistory`\non its own would not do — it neither routes nor installs, so it would run on whatever agent\nhappened to be installed (none, straight after a reload).\n\nLooks the owner up in its own agents list, so the `agent` argument is not needed and is\nignored; and does not delegate to the inner driver's resume, which would install the agent\nundecorated.",
+              "inheritedFrom": {
+                "name": "BaseDriverDecorator",
+                "module": "src/components/ai-driver/base-driver-decorator.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "resumeHandBack",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Promise<ChatDriverResult | undefined>"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "note",
+                  "optional": true,
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ],
+              "description": "The hand-back a restore found due (GENC-1737). The first call, inside the host's restore gate,\nmakes the caller active again and tells it the outcome; the call with the note runs its turn."
+            },
+            {
+              "kind": "method",
+              "name": "continueFromHistory",
+              "return": {
+                "type": {
+                  "text": "Promise<ChatDriverResult>"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "transientPrimer",
+                  "optional": true,
+                  "type": {
+                    "text": "ChatMessage[]"
+                  }
+                },
+                {
+                  "name": "options",
+                  "optional": true,
+                  "type": {
+                    "text": "ContinueFromHistoryOptions"
+                  }
+                }
+              ],
+              "description": "A continuation outside a routed turn — a decorator carrying the agent on, say — can finish the\nflow as surely as a turn can, so a release it requests is acted on here too. Before\n(GENC-1660), only `sendMessage` checked, and a flow finished by a continuation stayed locked.",
+              "inheritedFrom": {
+                "name": "BaseDriverDecorator",
+                "module": "src/components/ai-driver/base-driver-decorator.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "getContextReserve",
+              "return": {
+                "type": {
+                  "text": "ContextReserveResolution | undefined"
+                }
+              },
+              "description": "{@inheritDoc AiDriver.getContextReserve}\n\nTwo cases, because routing has two modes and they need opposite answers.",
+              "inheritedFrom": {
+                "name": "BaseDriverDecorator",
+                "module": "src/components/ai-driver/base-driver-decorator.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "installAgent",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Promise<void>"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "agent",
+                  "type": {
+                    "text": "AgentConfig"
+                  }
+                }
+              ],
+              "description": "Make `agent` active through the session, firing its hooks, and install it."
+            },
+            {
+              "kind": "method",
+              "name": "applyAgent",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "agent",
+                  "type": {
+                    "text": "AgentConfig"
+                  }
+                },
+                {
+                  "name": "previousName",
+                  "type": {
+                    "text": "string | undefined"
+                  }
+                }
+              ],
+              "description": "Install an agent the session has already made active on the inner driver: the transcript's\ndivider when another agent spoke before it, and its own view of the history. What is left here\nis this driver's own job, the transcript; the session owns the lifecycle."
+            },
+            {
+              "kind": "method",
+              "name": "releaseActiveAgent",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Promise<void>"
+                }
+              },
+              "description": "Release the current stateful agent: fire `onDeactivate` and clear the flow-owner lock. The\ninner driver raises the events from the session's transition, so the host (and Redux) reflect\nthe unlocked state (GENC-1485). Called automatically when a tool handler invokes\n`context.releaseAgent`.\n\nThe user-pin (`pinnedAgentName`) is intentionally *not* cleared — a user\nwho explicitly picked this agent should stay on it after the flow ends,\nso the next message starts a fresh flow on the same agent rather than\nrouting through the classifier."
             },
             {
               "kind": "method",
-              "name": "createInner",
+              "name": "agentNamed",
               "privacy": "private",
-              "static": true,
               "return": {
                 "type": {
-                  "text": "ChatDriver"
+                  "text": "AgentConfig | undefined"
                 }
               },
               "parameters": [
                 {
-                  "name": "providerRegistry",
-                  "type": {
-                    "text": "AIProviderRegistry"
-                  }
-                },
-                {
-                  "name": "agents",
-                  "type": {
-                    "text": "AgentConfig[]"
-                  }
-                },
-                {
-                  "name": "options",
-                  "default": "{}",
+                  "name": "name",
                   "type": {
-                    "text": "ConstructorParameters<typeof OrchestratingDriver>[2]"
+                    "text": "string"
                   }
                 }
               ],
-              "description": "Build the inner driver, after validating the agents' providers, so a bad config throws before\na driver exists to subscribe to the registry. Static because it runs before `super()`."
+              "description": "The agent named `name` as this driver installs it: the fallback with its prompt built."
             },
             {
               "kind": "method",
-              "name": "getSuggestions",
+              "name": "endOrphanedHandOffs",
+              "privacy": "private",
               "return": {
                 "type": {
-                  "text": "Promise<string[]>"
+                  "text": "Promise<void>"
                 }
               },
               "parameters": [
                 {
-                  "name": "history",
-                  "type": {
-                    "text": "ChatMessage[]"
-                  }
-                },
-                {
-                  "name": "prompt",
+                  "name": "agent",
                   "type": {
-                    "text": "string"
+                    "text": "AgentConfig"
                   }
-                },
+                }
+              ],
+              "description": "End the hand-offs when a turn runs an agent other than the top target (GENC-1737): the lock\nthat kept turns on the target was taken away, by a host clearing `flowOwnerAgentName` say,\nand its caller would otherwise wait for good."
+            },
+            {
+              "kind": "method",
+              "name": "checkHandOff",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "HandOffResult"
+                }
+              },
+              "parameters": [
                 {
-                  "name": "count",
+                  "name": "request",
                   "type": {
-                    "text": "number"
+                    "text": "HandOffRequest"
                   }
                 },
                 {
-                  "name": "allAgentInfo",
-                  "optional": true,
+                  "name": "caller",
                   "type": {
-                    "text": "AllAgentSummary[]"
+                    "text": "string | undefined"
                   }
                 }
               ],
-              "inheritedFrom": {
-                "name": "BaseDriverDecorator",
-                "module": "src/components/ai-driver/base-driver-decorator.ts"
-              }
+              "description": "Check a handler's `handOff` when it is made (GENC-1737), so a refusal reaches its model. Checked\nagainst the agents and the stack as they are now; the hand-off itself starts after the call."
             },
             {
               "kind": "method",
-              "name": "sendMessage",
+              "name": "startHandOff",
+              "privacy": "private",
               "return": {
                 "type": {
-                  "text": "Promise<ChatDriverResult>"
+                  "text": "Promise<string | undefined>"
                 }
               },
               "parameters": [
                 {
-                  "name": "input",
+                  "name": "request",
                   "type": {
-                    "text": "string"
+                    "text": "HandOffRequest"
                   }
-                },
+                }
+              ],
+              "description": "Start the hand-off the agent call just made, and return the target's tail note (GENC-1737).\n\n- `returnTo` (the default): push a frame. The caller waits without being deactivated, its\n  `agentEnd` payloads suspended, and the target takes the flow lock.\n- One-way from a hand-off's target: that frame's caller now waits for the new target instead.\n- One-way with nobody waiting: a plain switch, the caller deactivated as on any swap.\n\nEither way the brief is recorded as a message the caller sent on the user's behalf."
+            },
+            {
+              "kind": "method",
+              "name": "handBack",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Promise<string | undefined>"
+                }
+              },
+              "parameters": [
                 {
-                  "name": "attachments",
-                  "optional": true,
+                  "name": "frame",
                   "type": {
-                    "text": "ChatAttachment[]"
+                    "text": "HandOffFrame"
                   }
                 },
                 {
-                  "name": "options",
-                  "optional": true,
+                  "name": "outcome",
                   "type": {
-                    "text": "SendMessageOptions"
+                    "text": "HandOffOutcome"
                   }
                 }
               ],
-              "inheritedFrom": {
-                "name": "BaseDriverDecorator",
-                "module": "src/components/ai-driver/base-driver-decorator.ts"
-              }
+              "description": "Hand back to `frame`'s caller with `outcome`, and return its tail note (GENC-1737). The outcome\nis kept on the frame until the caller is active again and its `onHandOffReturn` has run, so a\nreload in between still hands back; the frame then goes, before the caller's model call."
             },
             {
               "kind": "method",
-              "name": "runOrchestratedTurn",
+              "name": "topFrameFor",
               "privacy": "private",
               "return": {
                 "type": {
-                  "text": "Promise<ChatDriverResult>"
+                  "text": "HandOffFrame | undefined"
                 }
               },
               "parameters": [
                 {
-                  "name": "input",
+                  "name": "agent",
                   "type": {
                     "text": "string"
                   }
-                },
-                {
-                  "name": "attachments",
-                  "type": {
-                    "text": "ChatAttachment[] | undefined"
-                  }
-                },
-                {
-                  "name": "options",
-                  "type": {
-                    "text": "SendMessageOptions | undefined"
-                  }
-                },
-                {
-                  "name": "delegated",
-                  "type": {
-                    "text": "Pick<ChatMessage, 'delegate' | 'delegateFraming' | 'externalCostUsd'>"
-                  }
                 }
-              ]
+              ],
+              "description": "The top frame, when `agent` is its target."
             },
             {
               "kind": "method",
-              "name": "canRestoreFlowOwner",
+              "name": "lastReply",
+              "privacy": "private",
               "return": {
                 "type": {
-                  "text": "boolean"
+                  "text": "string | undefined"
                 }
               },
               "parameters": [
                 {
-                  "name": "agentName",
+                  "name": "frame",
                   "type": {
-                    "text": "string"
+                    "text": "HandOffFrame"
                   }
                 }
               ],
-              "description": "{@inheritDoc AiDriver.canRestoreFlowOwner}",
-              "inheritedFrom": {
-                "name": "BaseDriverDecorator",
-                "module": "src/components/ai-driver/base-driver-decorator.ts"
-              }
+              "description": "The target's last reply since its brief, for a target that released without a summary."
             },
             {
               "kind": "method",
-              "name": "canResumeRestoredFlow",
+              "name": "recordDelegated",
+              "privacy": "private",
               "return": {
                 "type": {
-                  "text": "boolean"
+                  "text": "void"
                 }
               },
               "parameters": [
                 {
-                  "name": "agentName",
+                  "name": "from",
+                  "type": {
+                    "text": "string"
+                  }
+                },
+                {
+                  "name": "message",
+                  "type": {
+                    "text": "string"
+                  }
+                },
+                {
+                  "name": "framing",
                   "type": {
                     "text": "string"
                   }
                 }
               ],
-              "description": "{@inheritDoc AiDriver.canResumeRestoredFlow}",
-              "inheritedFrom": {
-                "name": "BaseDriverDecorator",
-                "module": "src/components/ai-driver/base-driver-decorator.ts"
-              }
+              "description": "The brief, in the transcript as a message the caller sent on the user's behalf."
             },
             {
               "kind": "method",
-              "name": "resumeRestoredFlow",
+              "name": "unwound",
+              "privacy": "private",
               "return": {
                 "type": {
-                  "text": "Promise<ChatDriverResult | undefined>"
+                  "text": "void"
                 }
               },
               "parameters": [
                 {
-                  "name": "resumeNote",
-                  "optional": true,
+                  "name": "frame",
                   "type": {
-                    "text": "string"
+                    "text": "HandOffFrame"
+                  }
+                },
+                {
+                  "name": "kind",
+                  "type": {
+                    "text": "HandOffOutcome['kind']"
                   }
                 }
               ],
-              "description": "{@inheritDoc AiDriver.resumeRestoredFlow}\n\nInstalls the flow owner directly rather than through `handleTurn`: there is no user message\nto classify, and a restored lock already says which agent owns the flow. `continueFromHistory`\non its own would not do — it neither routes nor installs, so it would run on whatever agent\nhappened to be installed (none, straight after a reload).\n\nLooks the owner up in its own agents list, so the `agent` argument is not needed and is\nignored; and does not delegate to the inner driver's resume, which would install the agent\nundecorated.",
+              "description": "End `frame` with `kind` and no hand-back, for the host."
+            },
+            {
+              "kind": "method",
+              "name": "getHandOffStack",
+              "return": {
+                "type": {
+                  "text": "HandOffFrame[]"
+                }
+              },
+              "description": "{@inheritDoc AiDriver.getHandOffStack}",
               "inheritedFrom": {
                 "name": "BaseDriverDecorator",
                 "module": "src/components/ai-driver/base-driver-decorator.ts"
@@ -22591,29 +23650,33 @@
             },
             {
               "kind": "method",
-              "name": "continueFromHistory",
+              "name": "restoreHandOffStack",
               "return": {
                 "type": {
-                  "text": "Promise<ChatDriverResult>"
+                  "text": "{ resume?: { agent: string; note: string }; droppedLocks?: string[] }"
                 }
               },
               "parameters": [
                 {
-                  "name": "transientPrimer",
-                  "optional": true,
+                  "name": "saved",
                   "type": {
-                    "text": "ChatMessage[]"
+                    "text": "unknown"
                   }
                 },
                 {
-                  "name": "options",
-                  "optional": true,
+                  "name": "savedStates",
                   "type": {
-                    "text": "ContinueFromHistoryOptions"
+                    "text": "Record<string, unknown>"
+                  }
+                },
+                {
+                  "name": "interrupted",
+                  "type": {
+                    "text": "boolean"
                   }
                 }
               ],
-              "description": "A continuation outside a routed turn — a decorator carrying the agent on, say — can finish the\nflow as surely as a turn can, so a release it requests is acted on here too. Before\n(GENC-1660), only `sendMessage` checked, and a flow finished by a continuation stayed locked.",
+              "description": "{@inheritDoc AiDriver.restoreHandOffStack}",
               "inheritedFrom": {
                 "name": "BaseDriverDecorator",
                 "module": "src/components/ai-driver/base-driver-decorator.ts"
@@ -22621,24 +23684,35 @@
             },
             {
               "kind": "method",
-              "name": "releaseIfRequested",
-              "privacy": "private",
+              "name": "unwindHandOffs",
               "return": {
                 "type": {
                   "text": "Promise<void>"
                 }
               },
-              "description": "Release the flow if the turn that just ended asked to, and an agent is still active to release."
+              "parameters": [
+                {
+                  "name": "kind",
+                  "type": {
+                    "text": "'cleared' | 'state-lost'"
+                  }
+                }
+              ],
+              "description": "{@inheritDoc AiDriver.unwindHandOffs}",
+              "inheritedFrom": {
+                "name": "BaseDriverDecorator",
+                "module": "src/components/ai-driver/base-driver-decorator.ts"
+              }
             },
             {
               "kind": "method",
-              "name": "getContextReserve",
+              "name": "getHandOffData",
               "return": {
                 "type": {
-                  "text": "ContextReserveResolution | undefined"
+                  "text": "Record<string, unknown>"
                 }
               },
-              "description": "{@inheritDoc AiDriver.getContextReserve}\n\nTwo cases, because routing has two modes and they need opposite answers.",
+              "description": "{@inheritDoc AiDriver.getHandOffData}",
               "inheritedFrom": {
                 "name": "BaseDriverDecorator",
                 "module": "src/components/ai-driver/base-driver-decorator.ts"
@@ -22646,40 +23720,45 @@
             },
             {
               "kind": "method",
-              "name": "installAgent",
-              "privacy": "private",
+              "name": "restoreHandOffData",
               "return": {
                 "type": {
-                  "text": "Promise<void>"
+                  "text": "void"
                 }
               },
               "parameters": [
                 {
-                  "name": "agent",
+                  "name": "saved",
                   "type": {
-                    "text": "AgentConfig"
+                    "text": "unknown"
                   }
                 },
                 {
-                  "name": "pin",
-                  "optional": true,
+                  "name": "interrupted",
                   "type": {
-                    "text": "string | null"
+                    "text": "boolean"
                   }
                 }
               ],
-              "description": "`pin` stands in for the user-pin when given, as for\nOrchestratingDriver.resolvePinnedAgent."
+              "description": "{@inheritDoc AiDriver.restoreHandOffData}",
+              "inheritedFrom": {
+                "name": "BaseDriverDecorator",
+                "module": "src/components/ai-driver/base-driver-decorator.ts"
+              }
             },
             {
               "kind": "method",
-              "name": "releaseActiveAgent",
-              "privacy": "private",
+              "name": "serializeWaitingCallers",
               "return": {
                 "type": {
-                  "text": "Promise<void>"
+                  "text": "Record<string, unknown>"
                 }
               },
-              "description": "Release the current stateful agent: fire `onDeactivate` and clear the flow-owner lock. The\ninner driver raises the events from the session's transition, so the host (and Redux) reflect\nthe unlocked state (GENC-1485). Called automatically when a tool handler invokes\n`context.releaseAgent`.\n\nThe user-pin (`pinnedAgentName`) is intentionally *not* cleared — a user\nwho explicitly picked this agent should stay on it after the flow ends,\nso the next message starts a fresh flow on the same agent rather than\nrouting through the classifier."
+              "description": "{@inheritDoc AiDriver.serializeWaitingCallers}",
+              "inheritedFrom": {
+                "name": "BaseDriverDecorator",
+                "module": "src/components/ai-driver/base-driver-decorator.ts"
+              }
             },
             {
               "kind": "method",
@@ -22689,7 +23768,7 @@
                   "text": "void"
                 }
               },
-              "description": "Stop the current turn (user \"stop\" button). Cancels the inner chat driver's\nin-flight request and breaks the handoff loop so no further agent turn or\nclassify runs. The driver stays usable for the next message.",
+              "description": "Stop the current turn (user \"stop\" button). Cancels the inner chat driver's\nin-flight request, and no further agent runs this turn, not even a hand-off's\ntarget or a hand-back. The driver stays usable for the next message.",
               "inheritedFrom": {
                 "name": "BaseDriverDecorator",
                 "module": "src/components/ai-driver/base-driver-decorator.ts"
@@ -22735,7 +23814,7 @@
                   "name": "detail",
                   "default": "{}",
                   "type": {
-                    "text": "{\n      index?: number;\n      durationMs?: number;\n      attempts?: number;\n      error?: string;\n      response?: ChatMessage;\n      excluded?: readonly string[];\n      /**\n       * What was actually on the ballot for this classification, in ballot order — so `index`\n       * indexes it. Omitted on the decisions that hold no vote at all.\n       */\n      ballot?: readonly string[];\n    }"
+                    "text": "{\n      index?: number;\n      durationMs?: number;\n      attempts?: number;\n      error?: string;\n      response?: ChatMessage;\n      /**\n       * What was actually on the ballot for this classification, in ballot order — so `index`\n       * indexes it. Omitted on the decisions that hold no vote at all.\n       */\n      ballot?: readonly string[];\n    }"
                   }
                 }
               ],
@@ -22788,13 +23867,6 @@
                   "type": {
                     "text": "AgentConfig"
                   }
-                },
-                {
-                  "name": "excludeAgents",
-                  "default": "[]",
-                  "type": {
-                    "text": "readonly string[]"
-                  }
                 }
               ]
             },
@@ -22835,7 +23907,7 @@
                   }
                 }
               ],
-              "description": "Append prose the ORCHESTRATOR wrote — the handoff cap, the no-specialist apology. Flagged\n`excludeFromProvider` for the same reason the driver's own notices are: it is not something a\nmodel said, and feeding it back invites the model to echo it. See\n`ChatMessage.excludeFromProvider`."
+              "description": "Append prose the ORCHESTRATOR wrote — the no-specialist apology. Flagged\n`excludeFromProvider` for the same reason the driver's own notices are: it is not something a\nmodel said, and feeding it back invites the model to echo it. See\n`ChatMessage.excludeFromProvider`."
             },
             {
               "kind": "field",
@@ -23466,6 +24538,24 @@
               "type": {
                 "text": "CustomEvent"
               }
+            },
+            {
+              "name": "handoff-started",
+              "type": {
+                "text": "CustomEvent"
+              }
+            },
+            {
+              "name": "handoff-returned",
+              "type": {
+                "text": "CustomEvent"
+              }
+            },
+            {
+              "name": "handoff-unwound",
+              "type": {
+                "text": "CustomEvent"
+              }
             }
           ],
           "superclass": {