@genesislcap/ai-assistant 15.27.0 → 15.28.0

package/dist/esm/components/orchestrating-driver/orchestrating-driver.js

@@ -156,7 +156,7 @@ export class OrchestratingDriver extends EventTarget {
      * **The inner driver's session, not one of our own.** One session is the invariant: two would
      * let the outer and inner driver disagree about which agent is active, and the inner one would
      * never be activated at all, because this driver installs a *decorated* config through
-     * `applyAgent` rather than going via `ChatDriver.activateAgent`. This driver keeps the routing
+     * `installAgent` rather than going via `ChatDriver.activateAgent`. This driver keeps the routing
      * decisions; the session owns the lifecycle.
      */
     get agentSession() {
@@ -431,7 +431,7 @@ export class OrchestratingDriver extends EventTarget {
                 if (this.cancelled)
                     break;
                 // oxlint-disable-next-line no-await-in-loop
-                yield this.applyAgent(currentAgent);
+                yield this.installAgent(currentAgent);
                 let result;
                 if (isHandoff) {
                     const contextPrimer = handoffSummary
@@ -488,7 +488,7 @@ export class OrchestratingDriver extends EventTarget {
                     break;
                 }
                 // Pinned agents never hand off — the continuation tool is filtered out in
-                // applyAgent, but this guards against a model hallucinating a handoff result.
+                // installAgent, but this guards against a model hallucinating a handoff result.
                 if (result.reason !== 'agent-handoff' || isFallback(currentAgent) || pinned) {
                     break;
                 }
@@ -592,7 +592,7 @@ export class OrchestratingDriver extends EventTarget {
     getActiveAgent() {
         return this.agentSession.getActive();
     }
-    applyAgent(agent) {
+    installAgent(agent) {
         return __awaiter(this, void 0, void 0, function* () {
             // The transition — handoff record, lifecycle hooks, restored state, flow lock — belongs to
             // the session. What is left below is this driver's own job: what the agent may route to, and
@@ -634,7 +634,7 @@ export class OrchestratingDriver extends EventTarget {
                 ]);
             }
             this.chatDriver.setProviderHistoryTransform((h) => transformHistoryForAgent(h, agent.name));
-            this.chatDriver.applyAgent(agentToApply);
+            this.chatDriver.installAgent(agentToApply);
             this.dispatchEvent(new CustomEvent('orchestrating-stop'));
             this.dispatchEvent(new CustomEvent('agent-changed', { detail: agent }));
         });

package/dist/esm/components/settings-modal/settings-modal.template.js

@@ -69,7 +69,27 @@ export const timestampModePickerTemplate = (segmentedControlTag, segmentedItemTa
     aria-label="Show timestamps"
     :value=${(x) => x.timestampDisplay}
     @change=${(x, c) => {
-    x.timestampDisplay = c.event.target.value;
+    // Only the GROUP's own `change` is authoritative. Each item emits its own `change` from
+    // `checkedChanged` as the group checks the incoming one and unchecks the outgoing, and
+    // those bubble to this listener carrying whichever mode that item represents — a valid
+    // string, and during startup a STALE one, so neither validating the value nor testing
+    // `checked` can tell them from a real pick. The group, by contrast, emits from
+    // `valueChanged`, which runs only after `changeHandler` has set `value` to the selection.
+    //
+    // Acting on a stale echo is not cosmetic: it writes a mode nobody chose AND marks
+    // preferences user-changed, latching the reconciler for the session — so the host's
+    // `chatConfig.ui.showTimestamps` never applies and the slice default wins instead.
+    // It fires on FIRST RENDER, before any interaction, which is what made a configured
+    // `'always'` unreachable in Create (GENC-1257).
+    if (c.event.target !== c.event.currentTarget)
+        return;
+    const next = c.event.target.value;
+    // `hasOwnProperty`, not `in`: `in` walks the prototype chain, so it would accept
+    // `'toString'`, `'constructor'` and friends as modes.
+    if (typeof next === 'string' &&
+        Object.prototype.hasOwnProperty.call(TIMESTAMP_MODE_LABELS, next)) {
+        x.timestampDisplay = next;
+    }
 }}
   >
     ${repeat(() => TIMESTAMP_MODE_OPTIONS, html `

package/dist/esm/main/main.js

@@ -682,7 +682,7 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         this.persistPreferences();
     }
     /**
-     * When each message shows its timestamp — `'off'`, `'hover'` (default) or `'always'`.
+     * When each message shows its timestamp — `'off'`, `'hover'` or `'always'` (default).
      *
      * Falls back to `DEFAULT_TIMESTAMP_DISPLAY` rather than `'off'` when there is no
      * store yet: this preference defaults ON, so the pre-store render must match the state
@@ -1696,7 +1696,7 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
             if (agents.length === 1 && !agents[0].fallback) {
                 // Preset for getters that read activeAgent before the first turn
                 // (e.g. chatInputDuringExecution). The orchestrator will overwrite
-                // this via `agent-changed` once applyAgent fires on first sendMessage.
+                // this via `agent-changed` once installAgent fires on first sendMessage.
                 this.activeAgent = agents[0];
             }
             return new OrchestratingDriver(this.providerRegistry, agents, {
@@ -2697,11 +2697,11 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
      * @internal
      */
     get contextReserve() {
-        var _a, _b, _c, _d;
+        var _a, _b, _c;
         const resolved = (_b = (_a = this.driver) === null || _a === void 0 ? void 0 : _a.getContextReserve) === null || _b === void 0 ? void 0 : _b.call(_a);
         if (resolved)
             return resolved;
-        const active = (_d = (_c = this.driver) === null || _c === void 0 ? void 0 : _c.getActiveAgent) === null || _d === void 0 ? void 0 : _d.call(_c);
+        const active = (_c = this.driver) === null || _c === void 0 ? void 0 : _c.getActiveAgent();
         const declared = active === null || active === void 0 ? void 0 : active.contextReserve;
         if (declared == null)
             return undefined;
@@ -2945,18 +2945,18 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
      */
     clearSession() {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
+            var _a, _b, _c, _d, _e, _f, _g, _h, _j;
             if ((_a = this.driver) === null || _a === void 0 ? void 0 : _a.isBusy())
                 return; // the menu only opens when idle; defensive
             const key = this.getStateKey();
             // Capture the live agent + its serialized state BEFORE teardown — the
             // machine is stopped below, so this is the host's last chance to learn what
             // the agent was working on (so it can tidy up external state if it wants).
-            const liveActive = (_c = (_b = this.driver) === null || _b === void 0 ? void 0 : _b.getActiveAgent) === null || _c === void 0 ? void 0 : _c.call(_b);
-            const agentName = (_d = liveActive === null || liveActive === void 0 ? void 0 : liveActive.name) !== null && _d !== void 0 ? _d : (_e = this.activeAgent) === null || _e === void 0 ? void 0 : _e.name;
+            const liveActive = (_b = this.driver) === null || _b === void 0 ? void 0 : _b.getActiveAgent();
+            const agentName = (_c = liveActive === null || liveActive === void 0 ? void 0 : liveActive.name) !== null && _c !== void 0 ? _c : (_d = this.activeAgent) === null || _d === void 0 ? void 0 : _d.name;
             let agentSnapshot;
             try {
-                agentSnapshot = (_f = liveActive === null || liveActive === void 0 ? void 0 : liveActive.serialize) === null || _f === void 0 ? void 0 : _f.call(liveActive);
+                agentSnapshot = (_e = liveActive === null || liveActive === void 0 ? void 0 : liveActive.serialize) === null || _e === void 0 ? void 0 : _e.call(liveActive);
             }
             catch (e) {
                 logger.error('Session clear: agent serialize() failed:', e);
@@ -2967,7 +2967,7 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
             const discarded = this.sessionUsage;
             if (this.driver)
                 this.teardownDriver(key);
-            (_g = this._sessionRef) === null || _g === void 0 ? void 0 : _g.actions.aiAssistant.resetSession();
+            (_f = this._sessionRef) === null || _f === void 0 ? void 0 : _f.actions.aiAssistant.resetSession();
             // `resetSession` zeroes the store-backed `contextTokens`; the gate's held copy
             // is ours to drop. Leaving it would carry a block into a conversation that no
             // longer exists — the one thing `contextGate` must never do (GENC-1582).
@@ -2979,7 +2979,7 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
             // Restore-core is owned by the shared per-session persister (GENC-1351 §5.10):
             // it drops the snapshot + resets the carry-forward cache. Diagnostics is
             // append-only and handled separately below.
-            yield ((_h = this.persister()) === null || _h === void 0 ? void 0 : _h.clearRestoreCore());
+            yield ((_g = this.persister()) === null || _g === void 0 ? void 0 : _g.clearRestoreCore());
             this.confirmingClear = false;
             this.composerMenus.closeImmediate();
             this.logMeta('session.cleared', { agentName });
@@ -2988,8 +2988,8 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
             // forward-capture cursors and flush, so the just-logged `session.cleared`
             // event becomes the stream's roll boundary: exactly like a page reload, the
             // new conversation begins a fresh section within the same lifetime log (§5.8).
-            resetDiagnosticsCursorsFor((_j = this.getStateKey()) !== null && _j !== void 0 ? _j : '');
-            (_k = this.persister()) === null || _k === void 0 ? void 0 : _k.scheduleDiagnostics();
+            resetDiagnosticsCursorsFor((_h = this.getStateKey()) !== null && _h !== void 0 ? _h : '');
+            (_j = this.persister()) === null || _j === void 0 ? void 0 : _j.scheduleDiagnostics();
             this.dispatchEvent(new CustomEvent(AiAssistantEvent.SessionCleared, {
                 bubbles: true,
                 composed: true,
@@ -3305,11 +3305,11 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
      * `onActivate` ran, so only its `getDebugSnapshot` closure holds state.
      */
     buildMetaSnapshot() {
-        var _a, _b, _c;
+        var _a, _b;
         return buildMetaSnapshot({
             agents: this.agents,
             activeAgent: this.activeAgent,
-            liveActiveAgent: (_b = (_a = this.driver) === null || _a === void 0 ? void 0 : _a.getActiveAgent) === null || _b === void 0 ? void 0 : _b.call(_a),
+            liveActiveAgent: (_a = this.driver) === null || _a === void 0 ? void 0 : _a.getActiveAgent(),
             activeFoldStack: this.driver instanceof ChatDriver ? this.driver.getActiveFoldNames() : undefined,
             activeModel: this.activeModel,
             contextTokens: this.contextTokens,
@@ -3317,7 +3317,7 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
             sessionCostUsd: this.sessionCostUsd,
             sessionTokensConsumed: this.sessionTokensConsumed,
             sessionUsage: this.sessionUsage,
-            debugState: (_c = this.debugStateFactory) === null || _c === void 0 ? void 0 : _c.call(this),
+            debugState: (_b = this.debugStateFactory) === null || _b === void 0 ? void 0 : _b.call(this),
             host: window.location.host,
         });
     }

package/dist/esm/main/main.styles.js

@@ -399,7 +399,7 @@ const baseStyles = css `
     border: 0;
   }
 
-  /* 'hover' — the default. Space is RESERVED at all times (opacity, not display) so
+  /* 'hover'. Space is RESERVED at all times (opacity, not display) so
      revealing the timestamp cannot reflow the bubble under the pointer; only the paint
      changes. The sender line is rarely the widest line in a bubble, so this costs no
      width except on very short messages. */

package/dist/esm/state/ai-assistant-slice.js

@@ -1,4 +1,5 @@
 import { createSlice } from '@genesislcap/foundation-redux';
+import { DEFAULT_TIMESTAMP_DISPLAY } from '../utils/resolve-preference-baseline';
 import { emptyUsage, sumUsage } from '../utils/sum-usage';
 /**
  * Build a fresh default session state. A factory (not just a shared const) so
@@ -13,7 +14,7 @@ export function createDefaultSessionState() {
         showThinkingSteps: false,
         showNarration: false,
         showAgentSwitchIndicator: false,
-        timestampDisplay: 'hover',
+        timestampDisplay: DEFAULT_TIMESTAMP_DISPLAY,
         enabledAnimations: [],
         suggestionsState: { status: 'idle' },
         contextTokens: undefined,

package/dist/esm/state/persistence/session-persister.js

@@ -270,7 +270,7 @@ export class SessionPersister {
      */
     persistSession() {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
+            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
             const { provider, enabled } = this.deps.getPersistence();
             if (!enabled || !provider)
                 return;
@@ -288,7 +288,7 @@ export class SessionPersister {
             // mints fresh configs (the showcase) would otherwise hand us a never-activated
             // closure whose `serialize()` returns undefined.
             const liveSnapshots = {};
-            const liveActive = (_a = driver === null || driver === void 0 ? void 0 : driver.getActiveAgent) === null || _a === void 0 ? void 0 : _a.call(driver);
+            const liveActive = driver === null || driver === void 0 ? void 0 : driver.getActiveAgent();
             if (liveActive === null || liveActive === void 0 ? void 0 : liveActive.serialize) {
                 try {
                     const snap = liveActive.serialize();
@@ -344,7 +344,7 @@ export class SessionPersister {
                     sessionKey: key,
                     host: window.location.host,
                     messages: messages.slice(0, Math.min(boundary, messages.length)),
-                    activeAgentName: (_b = s.activeAgent) === null || _b === void 0 ? void 0 : _b.name,
+                    activeAgentName: (_a = s.activeAgent) === null || _a === void 0 ? void 0 : _a.name,
                     pinnedAgentName: s.pinnedAgentName,
                     flowOwnerAgentName: null,
                     sessionCostUsd: s.sessionUsage.costUsd,
@@ -365,7 +365,7 @@ export class SessionPersister {
                     return;
                 }
                 this.logMeta('persistence.suppressed', {
-                    agent: (_c = liveActive === null || liveActive === void 0 ? void 0 : liveActive.name) !== null && _c !== void 0 ? _c : null,
+                    agent: (_b = liveActive === null || liveActive === void 0 ? void 0 : liveActive.name) !== null && _b !== void 0 ? _b : null,
                     isFlowOwner: s.flowOwnerAgentName === (liveActive === null || liveActive === void 0 ? void 0 : liveActive.name),
                     frozeAtMessages: frozen.messages.length,
                     custom: !!(liveActive === null || liveActive === void 0 ? void 0 : liveActive.notResumableMessage),
@@ -382,7 +382,7 @@ export class SessionPersister {
                     // event was added to the resumable branch — so a session that broke while an agent was
                     // mid-flow still reported nothing at all, which is precisely the blind spot the
                     // user-facing warning exists to cover.
-                    this.recordSaveOutcome(false, (_d = e === null || e === void 0 ? void 0 : e.message) !== null && _d !== void 0 ? _d : String(e));
+                    this.recordSaveOutcome(false, (_c = e === null || e === void 0 ? void 0 : e.message) !== null && _c !== void 0 ? _c : String(e));
                     // Deliberately NOT reporting from here. This is the non-resumable branch and a reload is
                     // the modal's only action, so advising one now would destroy the in-flight work the
                     // snapshot could not carry. `recordSaveOutcome` has already set `_brokenSince`, so the
@@ -395,11 +395,11 @@ export class SessionPersister {
                     this.logMeta('persistence.save-failed', {
                         messages: frozen.messages.length,
                         agents: [],
-                        active: (_e = liveActive === null || liveActive === void 0 ? void 0 : liveActive.name) !== null && _e !== void 0 ? _e : null,
+                        active: (_d = liveActive === null || liveActive === void 0 ? void 0 : liveActive.name) !== null && _d !== void 0 ? _d : null,
                         hasSerialize: !!(liveActive === null || liveActive === void 0 ? void 0 : liveActive.serialize),
                         frozen: true,
-                        error: (_f = e === null || e === void 0 ? void 0 : e.name) !== null && _f !== void 0 ? _f : typeof e,
-                        message: (_g = e === null || e === void 0 ? void 0 : e.message) !== null && _g !== void 0 ? _g : String(e),
+                        error: (_e = e === null || e === void 0 ? void 0 : e.name) !== null && _e !== void 0 ? _e : typeof e,
+                        message: (_f = e === null || e === void 0 ? void 0 : e.message) !== null && _f !== void 0 ? _f : String(e),
                     });
                     logger.error('Session save (interrupted marker) failed:', e);
                 }
@@ -411,7 +411,7 @@ export class SessionPersister {
                 sessionKey: key,
                 host: window.location.host,
                 messages: [...messages],
-                activeAgentName: (_h = s.activeAgent) === null || _h === void 0 ? void 0 : _h.name,
+                activeAgentName: (_g = s.activeAgent) === null || _g === void 0 ? void 0 : _g.name,
                 pinnedAgentName: s.pinnedAgentName,
                 flowOwnerAgentName: s.flowOwnerAgentName,
                 sessionCostUsd: s.sessionUsage.costUsd,
@@ -435,7 +435,7 @@ export class SessionPersister {
             const captured = {
                 messages: messages.length,
                 agents: Object.keys(agentSnapshots),
-                active: (_j = liveActive === null || liveActive === void 0 ? void 0 : liveActive.name) !== null && _j !== void 0 ? _j : null,
+                active: (_h = liveActive === null || liveActive === void 0 ? void 0 : liveActive.name) !== null && _h !== void 0 ? _h : null,
                 hasSerialize: !!(liveActive === null || liveActive === void 0 ? void 0 : liveActive.serialize),
                 agentSnapshots,
             };
@@ -454,7 +454,7 @@ export class SessionPersister {
                 // means the body never reached the wire at all, because a provider builds its
                 // request body inside the `fetch` init, so a throw while serialising creates no
                 // request and leaves no server-side trace.
-                this.recordSaveOutcome(false, (_k = e === null || e === void 0 ? void 0 : e.message) !== null && _k !== void 0 ? _k : String(e));
+                this.recordSaveOutcome(false, (_j = e === null || e === void 0 ? void 0 : e.message) !== null && _j !== void 0 ? _j : String(e));
                 // Report straight away rather than waiting for the next attempt: we are on the resumable
                 // path, so a reload is safe NOW, and a one-cycle delay is a second of extra exposure for
                 // no benefit.
@@ -471,8 +471,8 @@ export class SessionPersister {
                     agents: captured.agents,
                     active: captured.active,
                     hasSerialize: captured.hasSerialize,
-                    error: (_l = e === null || e === void 0 ? void 0 : e.name) !== null && _l !== void 0 ? _l : typeof e,
-                    message: (_m = e === null || e === void 0 ? void 0 : e.message) !== null && _m !== void 0 ? _m : String(e),
+                    error: (_k = e === null || e === void 0 ? void 0 : e.name) !== null && _k !== void 0 ? _k : typeof e,
+                    message: (_l = e === null || e === void 0 ? void 0 : e.message) !== null && _l !== void 0 ? _l : String(e),
                 });
                 logger.error('Session save failed:', e);
             }
@@ -487,7 +487,7 @@ export class SessionPersister {
      */
     restore() {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d, _e;
+            var _a, _b, _c, _d;
             const { provider } = this.deps.getPersistence();
             if (!provider)
                 return;
@@ -536,8 +536,8 @@ export class SessionPersister {
                 // Prime each stateful agent's persisted machine/state image FIRST — before
                 // seeding Redux or driver history — so the image is waiting on the driver no
                 // matter when the agent re-activates. The flow-owner lock self-heals on
-                // activation (OrchestratingDriver.applyAgent re-sets it).
-                (_a = driver === null || driver === void 0 ? void 0 : driver.primeRestoredAgentState) === null || _a === void 0 ? void 0 : _a.call(driver, snapshot.agentSnapshots);
+                // activation (OrchestratingDriver.installAgent re-sets it).
+                driver === null || driver === void 0 ? void 0 : driver.primeRestoredAgentState(snapshot.agentSnapshots);
                 // Seed the carry-forward cache so the immediate post-restore autosave (fired
                 // by the history change below, before any agent re-activates) preserves the
                 // machine snapshot instead of overwriting it with an empty one (GENC-1351).
@@ -550,7 +550,7 @@ export class SessionPersister {
                 // actually came back (meta events reset on reload, so this is the only window
                 // onto the saved→loaded handoff).
                 this.logMeta('persistence.restored', {
-                    agents: Object.keys((_b = snapshot.agentSnapshots) !== null && _b !== void 0 ? _b : {}),
+                    agents: Object.keys((_a = snapshot.agentSnapshots) !== null && _a !== void 0 ? _a : {}),
                     agentSnapshots: snapshot.agentSnapshots,
                     pinnedAgentName: snapshot.pinnedAgentName,
                     flowOwnerAgentName: snapshot.flowOwnerAgentName,
@@ -618,7 +618,7 @@ export class SessionPersister {
                 }
                 const messages = [...trimmed, ...trailers];
                 ref.actions.aiAssistant.loadSession(toLoadSessionPayload(Object.assign(Object.assign({}, snapshot), { messages })));
-                (_c = driver === null || driver === void 0 ? void 0 : driver.loadHistory) === null || _c === void 0 ? void 0 : _c.call(driver, [...messages]);
+                (_b = driver === null || driver === void 0 ? void 0 : driver.loadHistory) === null || _b === void 0 ? void 0 : _b.call(driver, [...messages]);
                 // Interrupted flow (§5.9): pre-fill the composer with the prompt that started
                 // the flow so "send it again" is one keystroke, and record it for observability.
                 if (snapshot.interrupted) {
@@ -641,8 +641,8 @@ export class SessionPersister {
                 // driver's routing agrees with the restored (picker-locked) store state.
                 const orchestrator = asOrchestrator(driver);
                 if (orchestrator) {
-                    orchestrator.setPinnedAgent((_d = snapshot.pinnedAgentName) !== null && _d !== void 0 ? _d : null);
-                    orchestrator.setFlowOwner((_e = snapshot.flowOwnerAgentName) !== null && _e !== void 0 ? _e : null);
+                    orchestrator.setPinnedAgent((_c = snapshot.pinnedAgentName) !== null && _c !== void 0 ? _c : null);
+                    orchestrator.setFlowOwner((_d = snapshot.flowOwnerAgentName) !== null && _d !== void 0 ? _d : null);
                 }
                 logger.debug('Session restored', { key, messages: messages.length });
             }

package/dist/esm/utils/resolve-preference-baseline.js

@@ -20,7 +20,7 @@ export function preferenceUnchanged(current, value) {
     return current === value;
 }
 /** The mode used when neither the host config nor stored prefs name a valid one. */
-export const DEFAULT_TIMESTAMP_DISPLAY = 'hover';
+export const DEFAULT_TIMESTAMP_DISPLAY = 'always';
 /**
  * Every valid {@link TimestampDisplay}, for narrowing untrusted input.
  *
@@ -39,8 +39,12 @@ const TIMESTAMP_DISPLAY_MODES = {
  *
  * Both inputs need this: the config field is typed but comes from plain JS hosts, and the
  * stored field is a bare `string` read back out of a persistence blob.
+ *
+ * Membership is tested with `hasOwnProperty` rather than `in`, which walks the prototype
+ * chain — `in` would admit `'constructor'`, `'toString'` and every other `Object.prototype`
+ * key as a valid mode, which is exactly the junk this is here to reject.
  */
-const asTimestampDisplay = (value) => typeof value === 'string' && value in TIMESTAMP_DISPLAY_MODES
+const asTimestampDisplay = (value) => typeof value === 'string' && Object.prototype.hasOwnProperty.call(TIMESTAMP_DISPLAY_MODES, value)
     ? value
     : undefined;
 /**

package/docs/migration-GENC-1580.md

@@ -1,47 +1,26 @@
 # Migration Guide — GENC-1580 (agent lifecycle leaves the orchestrator)
 
-> ## ⚠️ Partly shipped — the rename has not landed, so do not action the rename
+> ## ⚠️ §4 only is still unshipped
 >
-> The structural half of this change is in. What is **not** in is the one part that would break
-> you: `ChatDriver.applyAgent` has not been renamed. It was held back deliberately, to land alone
-> as the last PR of GENC-1580 — the rename cannot be caught by a compiler in a JavaScript caller,
-> so it is worth scheduling rather than absorbing alongside a refactor.
+> Everything in this guide is now true **except §4** (`pinned-changed`), which carries its own
+> notice. The breaking rename landed in this release.
 >
-> **What the package you are reading this in actually has:**
+> **Self-check, whatever version you are on:** if `ChatDriver.installAgent` exists, you are on the
+> breaking release and §1–§3 and §5 apply. If only `applyAgent` exists, you are on an earlier one
+> and should not touch your calls.
 >
-> | This guide says | Actually available today |
-> | --- | --- |
-> | `ChatDriver.activateAgent` | ✓ — available, fires the lifecycle hooks |
-> | `ChatDriver.agentSession` | ✓ — available (`@internal`) |
-> | `getActiveAgent` / `primeRestoredAgentState` implemented by both drivers | ✓ — and `setPinnedAgent` / `setFlowOwner` are on the interface now, all four **optional** |
-> | `ChatDriver.installAgent` | ✗ — **still `ChatDriver.applyAgent`, unchanged** |
-> | `pinned-changed` is dispatched | ✗ — still dead wiring (§7.2 of `code-health.md`) |
+> **What breaks:** `ChatDriver.applyAgent` is gone (§1), and four `AiDriver` members are now
+> required rather than optional (§3). Both are compile-time breaks in TypeScript; §1 is **not**
+> caught by a compiler in a JavaScript caller, which is why it shipped alone.
 >
-> **Self-check, whatever version you are on:** if `installAgent` is not present on `ChatDriver`,
-> the rename has not landed and you should not touch your `applyAgent` calls. §4 is also **not**
-> shipped — it carries its own notice. Everything else here is current.
+> **This ships as a MINOR version, not a major.** The AI surface is `@beta` and has no external
+> consumers — the only callers are migrated by hand alongside the release. So a `^15` range will
+> pick this up: if you call `ChatDriver` directly or implement `AiDriver`, read §1 and §3 before
+> upgrading rather than relying on the version number to warn you.
 >
-> **Nothing you have today breaks on this release.** `applyAgent` keeps working, and every
-> `AiDriver` member this ticket touched is declared optional, so an implementor of that interface
-> is unaffected too.
->
-> GENC-1580 ships in more than one PR. The first delivered an internal decomposition of `main.ts`
-> only — five feature controllers, no public API change of any kind. **The agent-lifecycle work
-> described here comes in a later PR under the same ticket**, and this notice is removed in the
-> same change that makes the guide true.
->
-> ---
->
-> When it does land: **config-compatible — no changes required to `chatConfig`, `agents`, or
-> `persistence`.** No element property, attribute, event or `::part()` changes. Nothing about which
-> driver runs your agents changes, so **no runtime behaviour changes**.
->
-> You will need to read this if you call `ChatDriver` directly, or if you implement `AiDriver`
-> yourself. If you only configure the element, there is nothing here for you.
->
-> All surfaces below are `@beta` unless marked otherwise.
-
----
+> **Config-compatible** — no changes to `chatConfig`, `agents` or `persistence`, no element
+> property, attribute, event or `::part()` changes, and **no runtime behaviour changes**. You only
+> need this guide if you call `ChatDriver` directly or implement `AiDriver` yourself.
 
 ## Why
 
@@ -67,8 +46,9 @@ longer depends on which driver you got.
 
 ### 1. `ChatDriver.applyAgent` is renamed to `installAgent`
 
-**This is the only breaking change in this release.** `applyAgent` was public `@beta` and appeared
-in the published type rollup.
+`applyAgent` was public `@beta` and appeared in the published type rollup, so this is a
+compile-time break for a TypeScript caller — and a silent one for a JavaScript caller, which is
+why it shipped in a release of its own.
 
 ```ts
 // before
@@ -97,6 +77,10 @@ name `installAgent` says what it does, so the next reader has to choose delibera
 state to restore, `activateAgent`. If you are re-applying a per-turn tool surface on an agent
 already activated, `installAgent`.
 
+`OrchestratingDriver`'s own private `applyAgent` was renamed to match. It was never public, so
+there is nothing to do — but the two are related, and leaving them differently named would have
+been worse than the original footgun.
+
 ### 2. `ChatDriver.agentSession` is exposed
 
 ```ts
@@ -123,27 +107,90 @@ which is the coupling that used to span two classes.
 
 | Member | Was | Now |
 | --- | --- | --- |
-| `getActiveAgent?()` | `OrchestratingDriver` only | both |
-| `setPinnedAgent?(name)` | not on the interface | both |
-| `setFlowOwner?(name)` | not on the interface | both |
-| `primeRestoredAgentState?(snapshots)` | `OrchestratingDriver` only | both |
+| `getActiveAgent()` | `OrchestratingDriver` only, optional | both, **required** |
+| `setPinnedAgent(name)` | not on the interface | both, **required** |
+| `setFlowOwner(name)` | not on the interface | both, **required** |
+| `primeRestoredAgentState(snapshots)` | `OrchestratingDriver` only, optional | both, **required** |
+
+**If you only call these, there is nothing to do** — and you can now drop your guards, because the
+interface finally promises what both shipped drivers have always provided:
+
+```ts
+// before
+const reserve = driver.getActiveAgent?.()?.contextReserve;
 
-**Nothing to do, and nothing breaks.** All four are declared **optional**, so a third party
-implementing `AiDriver` is unaffected: two were already optional and two are new additions. Keep
-your `?.()` guards — they still type-check, and the interface makes no promise a caller can lean
-on yet.
+// after
+const reserve = driver.getActiveAgent()?.contextReserve;
+```
 
-The `?` comes off in the same release as the `installAgent` rename, which is the only breaking
-change in this ticket. That is when the guards can go:
+**If you implement `AiDriver` yourself, this is the break.** Add the four methods. Each has a
+sensible inert form if your driver has nothing to route between — record the value and return it,
+or no-op:
 
 ```ts
-// after the breaking release, not before
-const reserve = driver.getActiveAgent().contextReserve;
+import type { AgentConfig } from '@genesislcap/ai-assistant';
+
+class MyDriver implements AiDriver {
+  // …your existing members — `AiDriver` extends `EventTarget` and has 11 required
+  // members in total, so this fragment alone will not compile…
+
+  private active?: AgentConfig;
+
+  getActiveAgent() {
+    return this.active;
+  }
+  setPinnedAgent(_name: string | null) {}
+  setFlowOwner(_name: string | null) {}
+  primeRestoredAgentState(_snapshots: Record<string, unknown>) {}
+}
 ```
 
-Fourteen members on `AiDriver` remain optional. They are a separate problem, and `ai-driver.ts`
-still carries a doc comment claiming the element depends only on this interface, which is not yet
-true.
+<details>
+<summary>A complete inert implementation, if you want one to start from</summary>
+
+`AiDriver` extends `EventTarget` and has 11 required members. This compiles as written — the four
+above plus the seven that were already required:
+
+```ts
+import type { ChatAttachment, ChatDriverResult, ChatMessage } from '@genesislcap/foundation-ai';
+import type { AgentConfig, AiDriver } from '@genesislcap/ai-assistant';
+
+class MyDriver extends EventTarget implements AiDriver {
+  private active?: AgentConfig;
+
+  // the four this release promotes
+  getActiveAgent() {
+    return this.active;
+  }
+  setPinnedAgent(_name: string | null) {}
+  setFlowOwner(_name: string | null) {}
+  primeRestoredAgentState(_snapshots: Record<string, unknown>) {}
+
+  // the seven that were already required
+  async sendMessage(_input: string, _attachments?: ChatAttachment[]): Promise<ChatDriverResult> {
+    return { reason: 'done' };
+  }
+  async continueFromHistory(_primer?: ChatMessage[]): Promise<ChatDriverResult> {
+    return { reason: 'done' };
+  }
+  resolveInteraction(_interactionId: string, _result: unknown) {}
+  loadHistory(_messages: ChatMessage[]) {}
+  isBusy() {
+    return false;
+  }
+  async getSuggestions(): Promise<string[]> {
+    return [];
+  }
+  getActiveProviderName() {
+    return 'my-provider';
+  }
+}
+```
+
+</details>
+
+Fourteen of `AiDriver`'s 25 members remain optional — compaction, diagnostics, interactions,
+`cancel`/`dispose`. Feature-detect those as before; this release changes nothing about them.
 
 ### 4. `pinned-changed` — still not dispatched, still nothing to do
 
@@ -182,8 +229,9 @@ behaviour on the session-restore path and deserves its own release to be judged
   a release.
 - `OrchestratingDriver`'s routing: classification, handoffs, the handoff cap, terminality rules,
   the continuation tool, and per-agent history masking.
-- `OrchestratingDriver.applyAgent` — it was already private, and stays private. It shrinks, but its
-  name and signature are not part of any contract.
+- `OrchestratingDriver`'s installer — private before and after, so its rename to `installAgent`
+  (§1) is invisible to you; it also shrank, but neither its name nor its signature is part of any
+  contract.
 - Session persistence and restore, including the shape written to the persistence provider.
 
 ## Known remaining: sub-agent lifecycle
@@ -208,8 +256,10 @@ This release also splits the two largest modules. None of it is consumer-visible
 package's entry points (`.`, `./config`, `./chat-driver`, `./react`), but if you deep-import from
 `dist/esm/...` — which is unsupported — paths have moved:
 
-- `chat-driver.ts` sheds its turn-failure taxonomy, interaction handling, turn recording, turn
-  setup, fold machinery and provider resolution into sibling modules.
+- `chat-driver.ts` sheds its turn-failure taxonomy (`turn-failures.ts`), interaction handling
+  (`interaction-controller.ts`), turn recording and diagnostics (`turn-recorder.ts`), fold
+  machinery (`fold-controller.ts`) and its constants (`chat-driver.constants.ts`) into sibling
+  modules. Turn setup and provider resolution were considered and **not** extracted.
 - `main.ts` sheds the settings modal, composer controls, cost ledger, budget latching, context gate
   and diagnostics assembly into controllers.