atom-agent 1.2.0 → 1.3.0

package/dist/extensions.js

@@ -0,0 +1,1571 @@
+// Extension host (tickets 01-07): discovery, loading, lifecycle, trust gate.
+//
+// An extension is a local .ts/.js file exporting a factory function that
+// receives an ExtensionAPI and registers subscriptions. Loading is
+// same-process dynamic import via jiti (TypeScript-capable, no sandbox):
+// extension code runs with full user privileges, exactly like app code.
+// Trust posture (ticket 07): global-scope extensions are user-owned and
+// implicitly trusted (like the user's own config); project-scope + explicit
+// paths never execute until the project is trusted (LoadOptions.projectTrusted,
+// driven by the App's one-time trust prompt + the project-trust store) or
+// are skipped by the lockdown / enable-disable filters. Skipped extensions
+// are never imported — their factories never run — and are reported on
+// runtime.skipped so the host can show what was left inert and why.
+//
+// Generations (stale-use rule): every session replacement (switch, /new,
+// /resume) invalidates the runtime, bumping a generation counter. API
+// objects captured before the bump throw on any further use; event handlers
+// always receive a fresh, current-generation API. This makes
+// use-after-replacement a loud error instead of a silent wrong-session bug.
+//
+// This module never throws out of loadExtensions: per-extension failures are
+// recorded on the runtime. It never touches React, the TUI, or LLM clients.
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import * as path from "node:path";
+import { createJiti } from "jiti";
+import { atomDir } from "./auth.js";
+import { TOOL_DEFINITIONS, registerExtensionTool, registerExtensionToolOverride, validateExtensionToolDef, } from "./tools/registry.js";
+import { registerExtensionPromptHint, validateExtensionPromptHint, validateExtensionToolOverrideDef, } from "./tools/overrides.js";
+import { registerAfterToolCall, registerBeforeToolCall, } from "./tools/intercept.js";
+import { registerAfterResponse, registerBeforeRequest, registerContextTransform, } from "./tools/provider-hooks.js";
+import { registerBeforeCompact, } from "./tools/compaction-hooks.js";
+import { registerExtensionCommand as registerCommandInStore, validateExtensionCommandDef, } from "./extension-commands.js";
+import { validateDialogDef, validateNotifyMessage, validateStatusSegment, validateWidgetDef, } from "./extension-ui.js";
+import { getSession as readSessionRecord, updateSession as writeSessionRecord, } from "./sessions.js";
+import { matchGlob } from "./permissions.js";
+export const EXTENSIONS_DIRNAME = "extensions";
+// Staged extension notices are drained into the transcript on render. Cap the
+// queue drop-oldest so a chatty extension cannot grow memory between drains.
+export const EXT_NOTICE_CAP = 100;
+// Extra extension paths from the environment (path.delimiter-separated).
+// Explicit configuration; honored alongside the two discovered scopes.
+export const EXTENSIONS_ENV = "ATOM_EXTENSIONS";
+// Per-session extension state lives namespaced here: record metadata
+// `{ ..., extensions: { [extName]: state } }` in the sessions store — the
+// existing durable per-session record, so state survives resume and reload
+// with the session itself and no parallel store is ever introduced.
+const EXT_STATE_KEY = "extensions";
+function assertJsonSerializable(value, what) {
+    let text;
+    try {
+        text = JSON.stringify(value);
+    }
+    catch (e) {
+        throw new Error(`${what} must be JSON-serializable: ${errorText(e)}`);
+    }
+    if (text === undefined) {
+        throw new Error(`${what} must be JSON-serializable (functions and undefined do not persist)`);
+    }
+}
+// Cancel interpretation (single rule for requestSwitch): only an explicit
+// veto cancels — true (default reason), a string (that reason, empty falls
+// back to the default), or { cancel: true | "reason" }. Everything else
+// (void/null/false/{cancel:false}/foreign shapes) allows.
+function cancelReasonOf(decision, extName) {
+    if (decision === true)
+        return `extension "${extName}" cancelled the session switch`;
+    if (typeof decision === "string") {
+        return decision.length > 0
+            ? decision
+            : `extension "${extName}" cancelled the session switch`;
+    }
+    if (isRecord(decision)) {
+        const cancel = decision.cancel;
+        if (cancel === true)
+            return `extension "${extName}" cancelled the session switch`;
+        if (typeof cancel === "string") {
+            return cancel.length > 0
+                ? cancel
+                : `extension "${extName}" cancelled the session switch`;
+        }
+    }
+    return null;
+}
+// Fresh parse per call (the store re-reads the file), so callers can never
+// alias persisted state — but mutating the result still persists nothing.
+function readExtensionState(home, sessionId, extName) {
+    if (sessionId === null)
+        return undefined;
+    const record = readSessionRecord(sessionId, home);
+    if (!record)
+        return undefined;
+    const metadata = record.metadata;
+    if (!isRecord(metadata))
+        return undefined;
+    const bag = metadata[EXT_STATE_KEY];
+    if (!isRecord(bag))
+        return undefined;
+    return bag[extName];
+}
+function writeExtensionState(home, sessionId, extName, value) {
+    if (sessionId === null) {
+        throw new Error(`extension "${extName}": no active session to persist state into`);
+    }
+    // undefined clears the slot; anything else must survive a JSON round-trip
+    // (the store persists via JSON.stringify, which would throw there — fail
+    // here instead, loudly and before touching the record).
+    if (value !== undefined)
+        assertJsonSerializable(value, `extension "${extName}" session state`);
+    const record = readSessionRecord(sessionId, home);
+    if (!record) {
+        throw new Error(`extension "${extName}": session "${sessionId}" is unavailable`);
+    }
+    const metadata = isRecord(record.metadata) ? { ...record.metadata } : {};
+    const rawBag = metadata[EXT_STATE_KEY];
+    const bag = isRecord(rawBag) ? { ...rawBag } : {};
+    if (value === undefined) {
+        delete bag[extName];
+    }
+    else {
+        bag[extName] = value;
+    }
+    if (Object.keys(bag).length === 0) {
+        delete metadata[EXT_STATE_KEY];
+    }
+    else {
+        metadata[EXT_STATE_KEY] = bag;
+    }
+    const updated = writeSessionRecord(sessionId, { metadata }, home);
+    if (!updated) {
+        throw new Error(`extension "${extName}": could not persist session state`);
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function globalExtensionsDir(home) {
+    return path.join(atomDir(home), EXTENSIONS_DIRNAME);
+}
+export function projectExtensionsDir(cwd) {
+    const base = typeof cwd === "string" && cwd.length > 0 ? cwd : process.cwd();
+    return path.join(base, ".atom", EXTENSIONS_DIRNAME);
+}
+const ENTRY_EXTENSIONS = new Set([".ts", ".js", ".mjs", ".cjs"]);
+const INDEX_BASENAMES = ["index.ts", "index.js", "index.mjs", "index.cjs"];
+function isEntryFile(name) {
+    return ENTRY_EXTENSIONS.has(path.extname(name).toLowerCase());
+}
+/** Manifest field for extension-package subdirectories (mirrors the Pi `pi` field convention). */
+function readAtomManifest(dir) {
+    let raw;
+    try {
+        raw = readFileSync(path.join(dir, "package.json"), "utf8");
+    }
+    catch {
+        return null;
+    }
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(data))
+        return null;
+    const atom = data["atom"];
+    if (!isRecord(atom))
+        return null;
+    const extensions = atom["extensions"];
+    if (!Array.isArray(extensions))
+        return null;
+    const out = [];
+    for (const e of extensions) {
+        if (typeof e === "string" && e.length > 0) {
+            out.push(path.resolve(dir, e));
+        }
+    }
+    return out;
+}
+/** Resolve one discovered path to loadable entry files (no recursion beyond one level). */
+function resolveEntries(entryPath) {
+    let stat;
+    try {
+        stat = statSync(entryPath);
+    }
+    catch {
+        return [];
+    }
+    if (stat.isFile()) {
+        return isEntryFile(path.basename(entryPath)) ? [entryPath] : [];
+    }
+    if (!stat.isDirectory())
+        return [];
+    const manifest = readAtomManifest(entryPath);
+    if (manifest)
+        return manifest;
+    for (const base of INDEX_BASENAMES) {
+        const candidate = path.join(entryPath, base);
+        try {
+            if (statSync(candidate).isFile())
+                return [candidate];
+        }
+        catch {
+            // try next basename
+        }
+    }
+    return [];
+}
+function discoverInDir(dir) {
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of [...names].sort()) {
+        if (name.startsWith("."))
+            continue;
+        out.push(...resolveEntries(path.join(dir, name)));
+    }
+    return out;
+}
+/**
+ * Ordered, deduplicated entries with scope labels: project scope, global
+ * scope, then explicit paths (env ATOM_EXTENSIONS + extraPaths). Missing
+ * scopes are silently skipped — never throws.
+ */
+export function discoverExtensionEntries(opts = {}) {
+    const seen = new Set();
+    const out = [];
+    const push = (p, scope) => {
+        const abs = path.resolve(p);
+        if (!seen.has(abs)) {
+            seen.add(abs);
+            out.push({ path: abs, scope });
+        }
+    };
+    for (const p of discoverInDir(projectExtensionsDir(opts.cwd)))
+        push(p, "project");
+    for (const p of discoverInDir(globalExtensionsDir(opts.home)))
+        push(p, "global");
+    const envRaw = process.env[EXTENSIONS_ENV];
+    if (typeof envRaw === "string" && envRaw.length > 0) {
+        for (const p of envRaw.split(path.delimiter)) {
+            const trimmed = p.trim();
+            if (trimmed.length === 0)
+                continue;
+            for (const e of resolveEntries(path.resolve(trimmed)))
+                push(e, "explicit");
+        }
+    }
+    for (const p of opts.extraPaths ?? []) {
+        for (const e of resolveEntries(path.resolve(p)))
+            push(e, "explicit");
+    }
+    return out;
+}
+/**
+ * Ordered, deduplicated entry files: project scope, global scope, then
+ * explicit paths (env ATOM_EXTENSIONS + extraPaths). Missing scopes are
+ * silently skipped — never throws.
+ */
+export function discoverExtensionPaths(opts = {}) {
+    return discoverExtensionEntries(opts).map((e) => e.path);
+}
+// Scope for a pre-resolved entry file (the LoadOptions.entryPaths seam):
+// under the project dir → project, under the global dir → global,
+// anywhere else → explicit (gated like project scope).
+export function classifyExtensionScope(entryPath, opts = {}) {
+    const abs = path.resolve(entryPath);
+    const proj = path.resolve(projectExtensionsDir(opts.cwd));
+    if (abs === proj || abs.startsWith(proj + path.sep))
+        return "project";
+    const glob = path.resolve(globalExtensionsDir(opts.home));
+    if (abs === glob || abs.startsWith(glob + path.sep))
+        return "global";
+    return "explicit";
+}
+export function parseExtensionFlags(argv) {
+    const out = { lockdown: false, enable: [], disable: [] };
+    const takeValue = (args, i, name) => {
+        const a = args[i];
+        const eqPrefix = `${name}=`;
+        if (a.startsWith(eqPrefix))
+            return { value: a.slice(eqPrefix.length), next: i };
+        if (a === name) {
+            const next = args[i + 1];
+            // Same convention as cli.tsx --port: a following `-flag` is another
+            // flag, not this flag's value.
+            if (typeof next === "string" && !next.startsWith("-"))
+                return { value: next, next: i + 1 };
+        }
+        return { next: i };
+    };
+    const pushList = (raw, target) => {
+        if (raw === undefined)
+            return;
+        for (const part of raw.split(",")) {
+            const trimmed = part.trim();
+            if (trimmed.length > 0)
+                target.push(trimmed);
+        }
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--no-extensions" || a === "--lockdown") {
+            out.lockdown = true;
+            continue;
+        }
+        if (a === "--enable-extension" || a.startsWith("--enable-extension=")) {
+            const r = takeValue(argv, i, "--enable-extension");
+            i = r.next;
+            pushList(r.value, out.enable);
+            continue;
+        }
+        if (a === "--disable-extension" || a.startsWith("--disable-extension=")) {
+            const r = takeValue(argv, i, "--disable-extension");
+            i = r.next;
+            pushList(r.value, out.disable);
+            continue;
+        }
+    }
+    return out;
+}
+export function resolveExtensionName(entryPath) {
+    const base = path.basename(entryPath);
+    const stem = base.replace(/\.(ts|js|mjs|cjs)$/i, "");
+    if (stem.toLowerCase() !== "index")
+        return stem;
+    const parent = path.basename(path.dirname(entryPath));
+    return parent.length > 0 ? parent : stem;
+}
+function errorText(e) {
+    return e instanceof Error ? e.message : String(e ?? "unknown error");
+}
+let jitiInstance = null;
+function jiti() {
+    if (!jitiInstance) {
+        jitiInstance = createJiti(import.meta.url);
+    }
+    return jitiInstance;
+}
+function resolveFactory(mod) {
+    if (typeof mod === "function")
+        return mod;
+    if (isRecord(mod)) {
+        const def = mod.default;
+        if (typeof def === "function")
+            return def;
+    }
+    return null;
+}
+/**
+ * Load every discovered extension. Never throws: each failure is recorded
+ * in runtime.errors with its path, and loading continues with the rest.
+ */
+export async function loadExtensions(opts = {}) {
+    // Ticket-07 gate inputs (precedence: lockdown > untrusted-project >
+    // disabledPatterns > enabledPatterns > load; disabled wins over enabled).
+    // projectTrusted defaults true for direct programmatic callers (tests,
+    // tooling); the App always passes the explicit boot trust value, so
+    // production project scope stays gated.
+    const lockdown = opts.lockdown === true;
+    const trusted = opts.projectTrusted !== false;
+    const enabled = opts.enabledPatterns ?? [];
+    const disabled = opts.disabledPatterns ?? [];
+    // Scoped entries: discovery already labels scope; pre-resolved entryPaths
+    // are classified by location (project dir → project, global dir → global,
+    // anywhere else → explicit). Entry order is preserved either way.
+    const scoped = opts.entryPaths !== undefined
+        ? opts.entryPaths.map((p) => ({ path: path.resolve(p), scope: classifyExtensionScope(p, opts) }))
+        : discoverExtensionEntries(opts);
+    // The gate: skipped entries are never imported (factory never runs — fully
+    // inert), only recorded with the reason so the host stays visible.
+    const skipped = [];
+    const entryPaths = [];
+    for (const e of scoped) {
+        const name = resolveExtensionName(e.path);
+        if (lockdown) {
+            skipped.push({ path: e.path, name, reason: "lockdown" });
+            continue;
+        }
+        // Global-scope extensions are user-owned (implicitly trusted, like the
+        // user's own config); the gate applies to project-scope + explicit paths.
+        if (e.scope !== "global" && !trusted) {
+            skipped.push({ path: e.path, name, reason: "untrusted-project" });
+            continue;
+        }
+        if (disabled.some((pattern) => matchGlob(pattern, name))) {
+            skipped.push({ path: e.path, name, reason: "disabled" });
+            continue;
+        }
+        if (enabled.length > 0 && !enabled.some((pattern) => matchGlob(pattern, name))) {
+            skipped.push({ path: e.path, name, reason: "not-enabled" });
+            continue;
+        }
+        entryPaths.push(e.path);
+    }
+    const handlers = new Map();
+    // Cancellable switch gate (ticket 05): runtime-local like event handlers
+    // (never a global store — a replaced runtime must not leak vetoes).
+    const beforeSwitchHandlers = [];
+    const loaded = [];
+    const errors = [];
+    let generation = 0;
+    let staleMessage = null;
+    // Session scoping for get/setSessionState (ticket 05): the store base is
+    // the load home; the host re-binds the id on every session boundary.
+    const sessionHome = opts.home;
+    let currentSessionId = typeof opts.sessionId === "string" && opts.sessionId.length > 0 ? opts.sessionId : null;
+    // Ticket-10 UI surface: runtime-local like beforeSwitchHandlers (a
+    // replaced runtime never leaks segments into another lineage, and
+    // parallel runtimes in tests never observe each other). Segments and
+    // widgets persist across session replacement keyed by owner — the fresh
+    // session_start API updates the same slots — and clear only on unload
+    // (unregister) or teardown (disposeUI). Only the pending dialog is
+    // transient: invalidate rejects it so it never hangs across a switch.
+    const interactive = opts.interactive === true;
+    const statusSegments = new Map();
+    const widgets = new Map();
+    const notifications = [];
+    let pendingDialog = null;
+    let dialogSeq = 0;
+    const uiListeners = new Set();
+    const emitUI = () => {
+        for (const fn of [...uiListeners]) {
+            try {
+                fn();
+            }
+            catch {
+                // Listener errors never break the host (same best-effort rule as emit).
+            }
+        }
+    };
+    const widgetKey = (owner, id) => `${owner}∅${id}`;
+    const addBeforeSwitchHandler = (extensionPath, handler) => {
+        const record = { extensionPath, handler };
+        beforeSwitchHandlers.push(record);
+        let live = true;
+        return () => {
+            if (!live)
+                return;
+            live = false;
+            const idx = beforeSwitchHandlers.indexOf(record);
+            if (idx >= 0)
+                beforeSwitchHandlers.splice(idx, 1);
+        };
+    };
+    // Builtin slash names (slash-prefixed) extension commands must not
+    // shadow — checked after shape validation whenever a command registers.
+    const builtinSlash = new Set((opts.builtinSlashCommands ?? []).map((n) => (n.startsWith("/") ? n : `/${n}`)));
+    const assertCommandNameFree = (def) => {
+        if (builtinSlash.has(`/${def.name}`)) {
+            throw new Error(`extension command "/${def.name}" collides with a builtin command (builtins always win)`);
+        }
+    };
+    const makeApi = (name, extensionPath) => {
+        // Generation captured at creation: any use after a later invalidate
+        // throws, while APIs minted fresh at emit time stay live.
+        const apiGeneration = generation;
+        const staleCheck = () => {
+            if (apiGeneration !== generation) {
+                throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+            }
+        };
+        return {
+            name,
+            on: (event, handler) => {
+                staleCheck();
+                if (typeof handler !== "function") {
+                    throw new Error(`extension "${name}": handler for "${event}" must be a function`);
+                }
+                let list = handlers.get(event);
+                if (!list) {
+                    list = [];
+                    handlers.set(event, list);
+                }
+                const record = { extensionPath, handler };
+                list.push(record);
+                return () => {
+                    const current = handlers.get(event);
+                    if (!current)
+                        return;
+                    const idx = current.indexOf(record);
+                    if (idx >= 0)
+                        current.splice(idx, 1);
+                };
+            },
+            registerTool: (def) => {
+                staleCheck();
+                const apiGenerationAtCall = apiGeneration;
+                const unregister = registerExtensionTool(def);
+                let live = true;
+                return () => {
+                    if (apiGenerationAtCall !== generation) {
+                        throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                    }
+                    if (!live)
+                        return;
+                    live = false;
+                    unregister();
+                };
+            },
+            overrideTool: (def) => {
+                staleCheck();
+                const apiGenerationAtCall = apiGeneration;
+                const unregister = registerExtensionToolOverride(def, name);
+                let live = true;
+                return () => {
+                    if (apiGenerationAtCall !== generation) {
+                        throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                    }
+                    if (!live)
+                        return;
+                    live = false;
+                    unregister();
+                };
+            },
+            addPromptHint: (hint) => {
+                staleCheck();
+                const apiGenerationAtCall = apiGeneration;
+                const unregister = registerExtensionPromptHint(hint, name);
+                let live = true;
+                return () => {
+                    if (apiGenerationAtCall !== generation) {
+                        throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                    }
+                    if (!live)
+                        return;
+                    live = false;
+                    unregister();
+                };
+            },
+            registerCommand: (def) => {
+                staleCheck();
+                validateExtensionCommandDef(def);
+                assertCommandNameFree(def);
+                const apiGenerationAtCall = apiGeneration;
+                const unregister = registerCommandInStore(def, name);
+                let live = true;
+                return () => {
+                    if (apiGenerationAtCall !== generation) {
+                        throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                    }
+                    if (!live)
+                        return;
+                    live = false;
+                    unregister();
+                };
+            },
+            onBeforeToolCall: (handler) => {
+                staleCheck();
+                if (typeof handler !== "function") {
+                    throw new Error(`extension "${name}": before-tool-call handler must be a function`);
+                }
+                const apiGenerationAtCall = apiGeneration;
+                const unregister = registerBeforeToolCall(handler, name);
+                let live = true;
+                return () => {
+                    if (apiGenerationAtCall !== generation) {
+                        throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                    }
+                    if (!live)
+                        return;
+                    live = false;
+                    unregister();
+                };
+            },
+            onAfterToolCall: (handler) => {
+                staleCheck();
+                if (typeof handler !== "function") {
+                    throw new Error(`extension "${name}": after-tool-call handler must be a function`);
+                }
+                const apiGenerationAtCall = apiGeneration;
+                const unregister = registerAfterToolCall(handler, name);
+                let live = true;
+                return () => {
+                    if (apiGenerationAtCall !== generation) {
+                        throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                    }
+                    if (!live)
+                        return;
+                    live = false;
+                    unregister();
+                };
+            },
+            onBeforeSwitch: (handler) => {
+                staleCheck();
+                if (typeof handler !== "function") {
+                    throw new Error(`extension "${name}": before-switch handler must be a function`);
+                }
+                const apiGenerationAtCall = apiGeneration;
+                const unregister = addBeforeSwitchHandler(extensionPath, handler);
+                let live = true;
+                return () => {
+                    if (apiGenerationAtCall !== generation) {
+                        throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                    }
+                    if (!live)
+                        return;
+                    live = false;
+                    unregister();
+                };
+            },
+            onTransformContext: (handler) => {
+                staleCheck();
+                if (typeof handler !== "function") {
+                    throw new Error(`extension "${name}": context-transform handler must be a function`);
+                }
+                const apiGenerationAtCall = apiGeneration;
+                const unregister = registerContextTransform(handler, name);
+                let live = true;
+                return () => {
+                    if (apiGenerationAtCall !== generation) {
+                        throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                    }
+                    if (!live)
+                        return;
+                    live = false;
+                    unregister();
+                };
+            },
+            onBeforeRequest: (handler) => {
+                staleCheck();
+                if (typeof handler !== "function") {
+                    throw new Error(`extension "${name}": before-request handler must be a function`);
+                }
+                const apiGenerationAtCall = apiGeneration;
+                const unregister = registerBeforeRequest(handler, name);
+                let live = true;
+                return () => {
+                    if (apiGenerationAtCall !== generation) {
+                        throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                    }
+                    if (!live)
+                        return;
+                    live = false;
+                    unregister();
+                };
+            },
+            onAfterResponse: (handler) => {
+                staleCheck();
+                if (typeof handler !== "function") {
+                    throw new Error(`extension "${name}": after-response handler must be a function`);
+                }
+                const apiGenerationAtCall = apiGeneration;
+                const unregister = registerAfterResponse(handler, name);
+                let live = true;
+                return () => {
+                    if (apiGenerationAtCall !== generation) {
+                        throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                    }
+                    if (!live)
+                        return;
+                    live = false;
+                    unregister();
+                };
+            },
+            onBeforeCompact: (handler) => {
+                staleCheck();
+                if (typeof handler !== "function") {
+                    throw new Error(`extension "${name}": before-compact handler must be a function`);
+                }
+                const apiGenerationAtCall = apiGeneration;
+                const unregister = registerBeforeCompact(handler, name);
+                let live = true;
+                return () => {
+                    if (apiGenerationAtCall !== generation) {
+                        throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                    }
+                    if (!live)
+                        return;
+                    live = false;
+                    unregister();
+                };
+            },
+            getSessionState: () => {
+                staleCheck();
+                return readExtensionState(sessionHome, currentSessionId, name);
+            },
+            setSessionState: (value) => {
+                staleCheck();
+                writeExtensionState(sessionHome, currentSessionId, name, value);
+            },
+            isProjectTrusted: () => {
+                staleCheck();
+                return trusted;
+            },
+            setStatusSegment: (text) => {
+                staleCheck();
+                // Eager shape check: a bad segment fails loudly (fail-closed), the
+                // slot upserts by owner so calling again updates live across turns
+                // (each call returns its own unregister; any of them removes the
+                // whole slot, so the latest handle is the one to keep).
+                const clean = validateStatusSegment(name, text);
+                const apiGenerationAtCall = apiGeneration;
+                statusSegments.set(name, clean);
+                emitUI();
+                let live = true;
+                return () => {
+                    if (apiGenerationAtCall !== generation) {
+                        throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                    }
+                    if (!live)
+                        return;
+                    live = false;
+                    statusSegments.delete(name);
+                    emitUI();
+                };
+            },
+            setWidget: (def) => {
+                staleCheck();
+                // Eager shape + placement check: a bad widget fails loudly
+                // (fail-closed); same-id calls upsert in place for live updates.
+                const clean = validateWidgetDef(name, def);
+                const apiGenerationAtCall = apiGeneration;
+                const key = widgetKey(name, clean.id);
+                widgets.set(key, { owner: name, ...clean });
+                emitUI();
+                let live = true;
+                return () => {
+                    if (apiGenerationAtCall !== generation) {
+                        throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                    }
+                    if (!live)
+                        return;
+                    live = false;
+                    widgets.delete(key);
+                    emitUI();
+                };
+            },
+            notify: (message) => {
+                staleCheck();
+                // Transient by design: staged for the host to drain into the
+                // transcript, dropped on teardown — nothing to unregister.
+                // Bounded (drop-oldest past EXT_NOTICE_CAP) so a chatty extension
+                // cannot grow memory between render drains.
+                notifications.push({ owner: name, message: validateNotifyMessage(name, message) });
+                if (notifications.length > EXT_NOTICE_CAP) {
+                    notifications.splice(0, notifications.length - EXT_NOTICE_CAP);
+                }
+                emitUI();
+            },
+            promptUser: (question, options, allowCustom) => {
+                staleCheck();
+                const clean = validateDialogDef(name, { question, options, allowCustom });
+                if (!interactive) {
+                    return Promise.reject(new Error(`extension "${name}": dialogs are unavailable in non-interactive mode (no prompt was shown)`));
+                }
+                if (pendingDialog) {
+                    return Promise.reject(new Error("(an extension dialog is already open — wait for it to resolve)"));
+                }
+                const apiGenerationAtCall = apiGeneration;
+                const id = (dialogSeq += 1);
+                return new Promise((resolve, reject) => {
+                    pendingDialog = {
+                        id,
+                        owner: name,
+                        question: clean.question,
+                        options: clean.options,
+                        allowCustom: clean.allowCustom,
+                        generation: apiGenerationAtCall,
+                        resolve: (answer) => {
+                            if (pendingDialog?.id !== id)
+                                return;
+                            pendingDialog = null;
+                            emitUI();
+                            resolve(answer);
+                        },
+                        reject: (err) => {
+                            if (pendingDialog?.id !== id)
+                                return;
+                            pendingDialog = null;
+                            emitUI();
+                            reject(err);
+                        },
+                    };
+                    emitUI();
+                });
+            },
+        };
+    };
+    const runtime = {
+        loaded,
+        errors,
+        skipped,
+        get generation() {
+            return generation;
+        },
+        invalidate(message) {
+            staleMessage = message;
+            generation += 1;
+            // A dialog awaiting input across a session switch resolves safely:
+            // reject with the stale message (never hangs, never fulfills into
+            // the wrong session). Visible segments/widgets persist keyed by
+            // owner — the fresh session_start API updates the same slots.
+            const cur = pendingDialog;
+            if (cur)
+                cur.reject(new Error(message));
+        },
+        async emit(event, info) {
+            const list = handlers.get(event) ?? [];
+            for (const record of [...list]) {
+                const api = makeApi(resolveExtensionName(record.extensionPath), record.extensionPath);
+                try {
+                    await record.handler(api, info);
+                }
+                catch (e) {
+                    errors.push({ path: record.extensionPath, error: `${event} handler failed: ${errorText(e)}` });
+                }
+            }
+        },
+        setSessionId(id) {
+            currentSessionId = typeof id === "string" && id.length > 0 ? id : null;
+        },
+        // Ticket-10 host reads (all copies — callers can never alias live
+        // store state) and host-side dialog settlement. Never throw except
+        // subscribeUI's shape check (the on() convention).
+        getStatusSegments() {
+            return [...statusSegments].map(([owner, text]) => ({ owner, text }));
+        },
+        getWidgets() {
+            return [...widgets.values()].map((w) => ({ ...w }));
+        },
+        drainNotifications() {
+            const out = notifications.map((n) => ({ ...n }));
+            notifications.length = 0;
+            return out;
+        },
+        getPendingDialog() {
+            if (!pendingDialog)
+                return null;
+            return {
+                id: pendingDialog.id,
+                owner: pendingDialog.owner,
+                question: pendingDialog.question,
+                options: [...pendingDialog.options],
+                allowCustom: pendingDialog.allowCustom,
+            };
+        },
+        subscribeUI(listener) {
+            if (typeof listener !== "function") {
+                throw new Error("extension UI listener must be a function");
+            }
+            uiListeners.add(listener);
+            let live = true;
+            return () => {
+                if (!live)
+                    return;
+                live = false;
+                uiListeners.delete(listener);
+            };
+        },
+        resolvePendingDialog(answer) {
+            const cur = pendingDialog;
+            if (!cur)
+                return false;
+            if (typeof answer !== "string" || answer.length === 0)
+                return false;
+            cur.resolve(answer);
+            return true;
+        },
+        cancelPendingDialog(reason) {
+            const cur = pendingDialog;
+            if (!cur)
+                return false;
+            cur.reject(new Error(typeof reason === "string" && reason.length > 0
+                ? reason
+                : `extension "${cur.owner}" dialog was cancelled`));
+            return true;
+        },
+        disposeUI() {
+            statusSegments.clear();
+            widgets.clear();
+            notifications.length = 0;
+            const cur = pendingDialog;
+            if (cur) {
+                cur.reject(new Error(`extension "${cur.owner}" dialog was cancelled (session teardown)`));
+            }
+            else {
+                emitUI();
+            }
+        },
+        // The sanctioned pre-replacement gate: the host awaits this BEFORE any
+        // snapshot/persist/mutate step. Handlers observe fresh APIs; the first
+        // explicit cancel wins (later handlers never run); throws fail open.
+        // The sanctioned post-replacement continuation is the fresh API passed
+        // to session_start handlers by emit — captured pre-replacement handles
+        // throw via the generation check above (reused, never reimplemented).
+        async requestSwitch(info) {
+            for (const record of [...beforeSwitchHandlers]) {
+                const extName = resolveExtensionName(record.extensionPath);
+                const api = makeApi(extName, record.extensionPath);
+                let decision;
+                try {
+                    decision = await record.handler(api, info);
+                }
+                catch (e) {
+                    errors.push({ path: record.extensionPath, error: `before_switch handler failed: ${errorText(e)}` });
+                    continue;
+                }
+                const reason = cancelReasonOf(decision, extName);
+                if (reason !== null)
+                    return { cancelled: true, reason };
+            }
+            return { cancelled: false };
+        },
+    };
+    const importer = jiti();
+    for (const entryPath of entryPaths) {
+        const name = resolveExtensionName(entryPath);
+        let mod;
+        try {
+            mod = await importer.import(entryPath, { default: true });
+        }
+        catch (e) {
+            errors.push({ path: entryPath, error: `import failed: ${errorText(e)}` });
+            continue;
+        }
+        const factory = resolveFactory(mod);
+        if (!factory) {
+            errors.push({ path: entryPath, error: "does not export a factory function (default export must be a function)" });
+            continue;
+        }
+        // A factory that throws during activation fails alone: activation runs
+        // before commit, so nothing from this extension is ever registered.
+        const pendingHandlers = [];
+        const pendingTools = [];
+        const pendingOverrides = [];
+        const pendingHints = [];
+        const pendingCommands = [];
+        const pendingBefore = [];
+        const pendingAfter = [];
+        // Staged switch gate (same atomicity as interceptors): validated eagerly
+        // so a non-function fails activation loudly, committed only after the
+        // factory succeeds — a throwing factory leaves no veto behind.
+        const pendingSwitch = [];
+        // Staged provider hooks (ticket 08; same atomicity as interceptors): a
+        // factory that throws during activation leaves no provider hook behind.
+        // Committed after the tool/command rounds below — hook registration
+        // cannot fail, so a tool-commit failure still rolls back to zero.
+        const pendingProviderContext = [];
+        const pendingProviderPre = [];
+        const pendingProviderPost = [];
+        // Staged compaction hooks (ticket 09; same atomicity as provider hooks):
+        // a factory that throws during activation leaves no compaction hook
+        // behind. Committed with the rounds below — hook registration cannot
+        // fail, so a tool/command failure still rolls back to zero.
+        const pendingCompact = [];
+        // Staged UI surface (ticket 10; same atomicity as hints): validated
+        // eagerly so a bad shape fails activation loudly, committed only after
+        // the factory succeeds — a throwing factory leaves zero UI residue.
+        // (Boxed: the slot is assigned only inside unregister closures, and a
+        // plain `let` would flow-narrow to its null initializer at commit.)
+        const stagedStatusBox = { current: null };
+        const pendingWidgets = [];
+        const pendingNotices = [];
+        const activationGeneration = generation;
+        const activationApi = {
+            name,
+            on: (event, handler) => {
+                if (activationGeneration !== generation) {
+                    throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                }
+                if (typeof handler !== "function") {
+                    throw new Error(`extension "${name}": handler for "${event}" must be a function`);
+                }
+                pendingHandlers.push({ event, handler });
+                return () => {
+                    const idx = pendingHandlers.findIndex((p) => p.event === event && p.handler === handler);
+                    if (idx >= 0)
+                        pendingHandlers.splice(idx, 1);
+                };
+            },
+            registerTool: (def) => {
+                if (activationGeneration !== generation) {
+                    throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                }
+                // Eager shape check: a malformed definition fails this extension's
+                // activation before anything is committed (cross-extension name
+                // races still surface at commit below, failing alone there too).
+                validateExtensionToolDef(def);
+                if (pendingTools.some((p) => p.def.name === def.name)) {
+                    throw new Error(`extension "${name}": tool "${def.name}" is already registered`);
+                }
+                const entry = { def, committedUnregister: null };
+                pendingTools.push(entry);
+                let alive = true;
+                return () => {
+                    if (activationGeneration !== generation) {
+                        throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                    }
+                    if (!alive)
+                        return;
+                    alive = false;
+                    if (entry.committedUnregister) {
+                        const undo = entry.committedUnregister;
+                        entry.committedUnregister = null;
+                        undo();
+                    }
+                    else {
+                        const idx = pendingTools.indexOf(entry);
+                        if (idx >= 0)
+                            pendingTools.splice(idx, 1);
+                    }
+                };
+            },
+            overrideTool: (def) => {
+                if (activationGeneration !== generation) {
+                    throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                }
+                // Eager shape + builtin checks: a malformed definition or a
+                // non-builtin name fails this extension's activation before anything
+                // is committed (cross-extension override races still surface at
+                // commit below, failing alone there too).
+                validateExtensionToolOverrideDef(def);
+                if (!TOOL_DEFINITIONS.some((t) => t.function.name === def.name)) {
+                    throw new Error(`extension tool override "${def.name}" is not a builtin tool (only builtins can be overridden)`);
+                }
+                if (pendingOverrides.some((p) => p.def.name === def.name)) {
+                    throw new Error(`extension "${name}": tool override "${def.name}" is already registered`);
+                }
+                const entry = { def, committedUnregister: null };
+                pendingOverrides.push(entry);
+                let alive = true;
+                return () => {
+                    if (activationGeneration !== generation) {
+                        throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                    }
+                    if (!alive)
+                        return;
+                    alive = false;
+                    if (entry.committedUnregister) {
+                        const undo = entry.committedUnregister;
+                        entry.committedUnregister = null;
+                        undo();
+                    }
+                    else {
+                        const idx = pendingOverrides.indexOf(entry);
+                        if (idx >= 0)
+                            pendingOverrides.splice(idx, 1);
+                    }
+                };
+            },
+            addPromptHint: (hint) => {
+                if (activationGeneration !== generation) {
+                    throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                }
+                // Eager shape check: an empty/oversize hint fails this extension's
+                // activation before anything is committed.
+                validateExtensionPromptHint(hint);
+                const entry = { hint, committedUnregister: null };
+                pendingHints.push(entry);
+                let alive = true;
+                return () => {
+                    if (activationGeneration !== generation) {
+                        throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                    }
+                    if (!alive)
+                        return;
+                    alive = false;
+                    if (entry.committedUnregister) {
+                        const undo = entry.committedUnregister;
+                        entry.committedUnregister = null;
+                        undo();
+                    }
+                    else {
+                        const idx = pendingHints.indexOf(entry);
+                        if (idx >= 0)
+                            pendingHints.splice(idx, 1);
+                    }
+                };
+            },
+            registerCommand: (def) => {
+                if (activationGeneration !== generation) {
+                    throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                }
+                // Eager shape + builtin checks: a malformed or colliding definition
+                // fails this extension's activation before anything is committed
+                // (cross-extension name races still surface at commit below).
+                validateExtensionCommandDef(def);
+                assertCommandNameFree(def);
+                if (pendingCommands.some((p) => p.def.name === def.name)) {
+                    throw new Error(`extension "${name}": command "/${def.name}" is already registered`);
+                }
+                const entry = { def, committedUnregister: null };
+                pendingCommands.push(entry);
+                let alive = true;
+                return () => {
+                    if (activationGeneration !== generation) {
+                        throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                    }
+                    if (!alive)
+                        return;
+                    alive = false;
+                    if (entry.committedUnregister) {
+                        const undo = entry.committedUnregister;
+                        entry.committedUnregister = null;
+                        undo();
+                    }
+                    else {
+                        const idx = pendingCommands.indexOf(entry);
+                        if (idx >= 0)
+                            pendingCommands.splice(idx, 1);
+                    }
+                };
+            },
+            onBeforeToolCall: (handler) => {
+                if (activationGeneration !== generation) {
+                    throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                }
+                if (typeof handler !== "function") {
+                    throw new Error(`extension "${name}": before-tool-call handler must be a function`);
+                }
+                const entry = { handler, committedUnregister: null };
+                pendingBefore.push(entry);
+                let alive = true;
+                return () => {
+                    if (activationGeneration !== generation) {
+                        throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                    }
+                    if (!alive)
+                        return;
+                    alive = false;
+                    if (entry.committedUnregister) {
+                        const undo = entry.committedUnregister;
+                        entry.committedUnregister = null;
+                        undo();
+                    }
+                    else {
+                        const idx = pendingBefore.indexOf(entry);
+                        if (idx >= 0)
+                            pendingBefore.splice(idx, 1);
+                    }
+                };
+            },
+            onAfterToolCall: (handler) => {
+                if (activationGeneration !== generation) {
+                    throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                }
+                if (typeof handler !== "function") {
+                    throw new Error(`extension "${name}": after-tool-call handler must be a function`);
+                }
+                const entry = { handler, committedUnregister: null };
+                pendingAfter.push(entry);
+                let alive = true;
+                return () => {
+                    if (activationGeneration !== generation) {
+                        throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                    }
+                    if (!alive)
+                        return;
+                    alive = false;
+                    if (entry.committedUnregister) {
+                        const undo = entry.committedUnregister;
+                        entry.committedUnregister = null;
+                        undo();
+                    }
+                    else {
+                        const idx = pendingAfter.indexOf(entry);
+                        if (idx >= 0)
+                            pendingAfter.splice(idx, 1);
+                    }
+                };
+            },
+            onTransformContext: (handler) => {
+                if (activationGeneration !== generation) {
+                    throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                }
+                if (typeof handler !== "function") {
+                    throw new Error(`extension "${name}": context-transform handler must be a function`);
+                }
+                const entry = { handler, committedUnregister: null };
+                pendingProviderContext.push(entry);
+                let alive = true;
+                return () => {
+                    if (activationGeneration !== generation) {
+                        throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                    }
+                    if (!alive)
+                        return;
+                    alive = false;
+                    if (entry.committedUnregister) {
+                        const undo = entry.committedUnregister;
+                        entry.committedUnregister = null;
+                        undo();
+                    }
+                    else {
+                        const idx = pendingProviderContext.indexOf(entry);
+                        if (idx >= 0)
+                            pendingProviderContext.splice(idx, 1);
+                    }
+                };
+            },
+            onBeforeRequest: (handler) => {
+                if (activationGeneration !== generation) {
+                    throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                }
+                if (typeof handler !== "function") {
+                    throw new Error(`extension "${name}": before-request handler must be a function`);
+                }
+                const entry = { handler, committedUnregister: null };
+                pendingProviderPre.push(entry);
+                let alive = true;
+                return () => {
+                    if (activationGeneration !== generation) {
+                        throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                    }
+                    if (!alive)
+                        return;
+                    alive = false;
+                    if (entry.committedUnregister) {
+                        const undo = entry.committedUnregister;
+                        entry.committedUnregister = null;
+                        undo();
+                    }
+                    else {
+                        const idx = pendingProviderPre.indexOf(entry);
+                        if (idx >= 0)
+                            pendingProviderPre.splice(idx, 1);
+                    }
+                };
+            },
+            onAfterResponse: (handler) => {
+                if (activationGeneration !== generation) {
+                    throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                }
+                if (typeof handler !== "function") {
+                    throw new Error(`extension "${name}": after-response handler must be a function`);
+                }
+                const entry = { handler, committedUnregister: null };
+                pendingProviderPost.push(entry);
+                let alive = true;
+                return () => {
+                    if (activationGeneration !== generation) {
+                        throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                    }
+                    if (!alive)
+                        return;
+                    alive = false;
+                    if (entry.committedUnregister) {
+                        const undo = entry.committedUnregister;
+                        entry.committedUnregister = null;
+                        undo();
+                    }
+                    else {
+                        const idx = pendingProviderPost.indexOf(entry);
+                        if (idx >= 0)
+                            pendingProviderPost.splice(idx, 1);
+                    }
+                };
+            },
+            onBeforeCompact: (handler) => {
+                if (activationGeneration !== generation) {
+                    throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                }
+                if (typeof handler !== "function") {
+                    throw new Error(`extension "${name}": before-compact handler must be a function`);
+                }
+                const entry = { handler, committedUnregister: null };
+                pendingCompact.push(entry);
+                let alive = true;
+                return () => {
+                    if (activationGeneration !== generation) {
+                        throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                    }
+                    if (!alive)
+                        return;
+                    alive = false;
+                    if (entry.committedUnregister) {
+                        const undo = entry.committedUnregister;
+                        entry.committedUnregister = null;
+                        undo();
+                    }
+                    else {
+                        const idx = pendingCompact.indexOf(entry);
+                        if (idx >= 0)
+                            pendingCompact.splice(idx, 1);
+                    }
+                };
+            },
+            onBeforeSwitch: (handler) => {
+                if (activationGeneration !== generation) {
+                    throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                }
+                if (typeof handler !== "function") {
+                    throw new Error(`extension "${name}": before-switch handler must be a function`);
+                }
+                const entry = { handler, committedUnregister: null };
+                pendingSwitch.push(entry);
+                let alive = true;
+                return () => {
+                    if (activationGeneration !== generation) {
+                        throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                    }
+                    if (!alive)
+                        return;
+                    alive = false;
+                    if (entry.committedUnregister) {
+                        const undo = entry.committedUnregister;
+                        entry.committedUnregister = null;
+                        undo();
+                    }
+                    else {
+                        const idx = pendingSwitch.indexOf(entry);
+                        if (idx >= 0)
+                            pendingSwitch.splice(idx, 1);
+                    }
+                };
+            },
+            getSessionState: () => {
+                if (activationGeneration !== generation) {
+                    throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                }
+                return readExtensionState(sessionHome, currentSessionId, name);
+            },
+            setSessionState: (value) => {
+                if (activationGeneration !== generation) {
+                    throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                }
+                writeExtensionState(sessionHome, currentSessionId, name, value);
+            },
+            isProjectTrusted: () => {
+                if (activationGeneration !== generation) {
+                    throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                }
+                return trusted;
+            },
+            setStatusSegment: (text) => {
+                if (activationGeneration !== generation) {
+                    throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                }
+                // Eager shape check + single-slot staging: a later set overwrites
+                // the earlier (live-update upsert), a throw rolls back to null.
+                const entry = { text: validateStatusSegment(name, text), committed: false };
+                stagedStatusBox.current = entry;
+                let alive = true;
+                return () => {
+                    if (activationGeneration !== generation) {
+                        throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                    }
+                    if (!alive)
+                        return;
+                    alive = false;
+                    if (entry.committed) {
+                        statusSegments.delete(name);
+                        emitUI();
+                    }
+                    else if (stagedStatusBox.current === entry) {
+                        stagedStatusBox.current = null;
+                    }
+                };
+            },
+            setWidget: (def) => {
+                if (activationGeneration !== generation) {
+                    throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                }
+                // Eager shape + placement check: same-id sets upsert the pending
+                // entry (live-update staging), a throw drops the whole list.
+                const clean = validateWidgetDef(name, def);
+                const key = widgetKey(name, clean.id);
+                let entry = pendingWidgets.find((p) => widgetKey(name, p.def.id) === key);
+                if (!entry) {
+                    entry = { def: clean, committed: false };
+                    pendingWidgets.push(entry);
+                }
+                else {
+                    entry.def = clean;
+                }
+                const staged = entry;
+                let alive = true;
+                return () => {
+                    if (activationGeneration !== generation) {
+                        throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                    }
+                    if (!alive)
+                        return;
+                    alive = false;
+                    if (staged.committed) {
+                        widgets.delete(key);
+                        emitUI();
+                    }
+                    else {
+                        const idx = pendingWidgets.indexOf(staged);
+                        if (idx >= 0)
+                            pendingWidgets.splice(idx, 1);
+                    }
+                };
+            },
+            notify: (message) => {
+                if (activationGeneration !== generation) {
+                    throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                }
+                // Eager shape check: staged with the other UI, committed only on
+                // success — a throwing factory posts nothing.
+                pendingNotices.push(validateNotifyMessage(name, message));
+            },
+            promptUser: () => {
+                if (activationGeneration !== generation) {
+                    throw new Error(staleMessage ?? "extension context is stale after a session replacement");
+                }
+                // Activation runs before the host assigns the runtime, so no modal
+                // could ever fulfill this — reject instead of hanging forever.
+                return Promise.reject(new Error(`extension "${name}": dialogs cannot open during activation — prompt from a command or event handler instead (nothing was shown)`));
+            },
+        };
+        try {
+            await factory(activationApi);
+        }
+        catch (e) {
+            errors.push({ path: entryPath, error: `activation failed: ${errorText(e)}` });
+            continue;
+        }
+        // Commit: activation succeeded, registrations go live atomically. A
+        // duplicate/builtin-colliding tool name fails this extension alone:
+        // tools committed earlier in this round roll back and handlers never
+        // go live.
+        const committedToolUndos = [];
+        try {
+            for (const t of pendingTools) {
+                const undo = registerExtensionTool(t.def);
+                t.committedUnregister = undo;
+                committedToolUndos.push(undo);
+            }
+        }
+        catch (e) {
+            for (const undo of committedToolUndos) {
+                try {
+                    undo();
+                }
+                catch {
+                    // rollback is best-effort; the error entry below carries the cause
+                }
+            }
+            for (const t of pendingTools)
+                t.committedUnregister = null;
+            errors.push({ path: entryPath, error: `tool registration failed: ${errorText(e)}` });
+            continue;
+        }
+        // Override commit (same atomic round): a duplicate override (a
+        // cross-extension race — same-extension duplicates fail eagerly above)
+        // fails this extension alone: overrides committed earlier in this round
+        // roll back ALONGSIDE the tools above, and later rounds never go live.
+        const committedOverrideUndos = [];
+        try {
+            for (const o of pendingOverrides) {
+                const undo = registerExtensionToolOverride(o.def, name);
+                o.committedUnregister = undo;
+                committedOverrideUndos.push(undo);
+            }
+        }
+        catch (e) {
+            for (const undo of [...committedOverrideUndos, ...committedToolUndos]) {
+                try {
+                    undo();
+                }
+                catch {
+                    // rollback is best-effort; the error entry below carries the cause
+                }
+            }
+            for (const t of pendingTools)
+                t.committedUnregister = null;
+            for (const o of pendingOverrides)
+                o.committedUnregister = null;
+            errors.push({ path: entryPath, error: `tool override registration failed: ${errorText(e)}` });
+            continue;
+        }
+        // Command commit (same atomic round): a duplicate/colliding name fails
+        // this extension alone — commands committed earlier in this round roll
+        // back ALONGSIDE the tools and overrides above, and handlers/interceptors
+        // never go live, so a failed activation always leaves zero registrations
+        // behind.
+        const committedCommandUndos = [];
+        try {
+            for (const c of pendingCommands) {
+                const undo = registerCommandInStore(c.def, name);
+                c.committedUnregister = undo;
+                committedCommandUndos.push(undo);
+            }
+        }
+        catch (e) {
+            for (const undo of [...committedCommandUndos, ...committedOverrideUndos, ...committedToolUndos]) {
+                try {
+                    undo();
+                }
+                catch {
+                    // rollback is best-effort; the error entry below carries the cause
+                }
+            }
+            for (const t of pendingTools)
+                t.committedUnregister = null;
+            for (const o of pendingOverrides)
+                o.committedUnregister = null;
+            for (const c of pendingCommands)
+                c.committedUnregister = null;
+            errors.push({ path: entryPath, error: `command registration failed: ${errorText(e)}` });
+            continue;
+        }
+        // Hint commit (same atomic round): validated eagerly, cannot fail — a
+        // tool/override/command failure above skips this entirely via continue,
+        // so a failed activation never leaves a hint behind either.
+        for (const h of pendingHints) {
+            h.committedUnregister = registerExtensionPromptHint(h.hint, name);
+        }
+        // UI-surface commit (same atomic round): validated eagerly, cannot
+        // fail — a tool/override/command failure above skips this entirely via
+        // continue, so a failed activation never leaves a segment, widget, or
+        // notice behind either.
+        const stagedStatus = stagedStatusBox.current;
+        if (stagedStatus) {
+            stagedStatus.committed = true;
+            statusSegments.set(name, stagedStatus.text);
+        }
+        for (const w of pendingWidgets) {
+            w.committed = true;
+            widgets.set(widgetKey(name, w.def.id), { owner: name, ...w.def });
+        }
+        for (const message of pendingNotices) {
+            notifications.push({ owner: name, message });
+            if (notifications.length > EXT_NOTICE_CAP) {
+                notifications.splice(0, notifications.length - EXT_NOTICE_CAP);
+            }
+        }
+        if (stagedStatus || pendingWidgets.length > 0 || pendingNotices.length > 0)
+            emitUI();
+        for (const e of pendingBefore) {
+            e.committedUnregister = registerBeforeToolCall(e.handler, name);
+        }
+        for (const e of pendingAfter) {
+            e.committedUnregister = registerAfterToolCall(e.handler, name);
+        }
+        // Provider-hook commit (same atomic round): runtime-global like the
+        // interceptors above, cannot fail — a tool/command failure skips this
+        // entirely via continue, so a failed activation never leaves a provider
+        // hook behind either.
+        for (const e of pendingProviderContext) {
+            e.committedUnregister = registerContextTransform(e.handler, name);
+        }
+        for (const e of pendingProviderPre) {
+            e.committedUnregister = registerBeforeRequest(e.handler, name);
+        }
+        for (const e of pendingProviderPost) {
+            e.committedUnregister = registerAfterResponse(e.handler, name);
+        }
+        // Compaction-hook commit (same atomic round): runtime-global like the
+        // provider hooks above, cannot fail — a tool/command failure skips this
+        // entirely via continue, so a failed activation never leaves a
+        // compaction hook behind either.
+        for (const e of pendingCompact) {
+            e.committedUnregister = registerBeforeCompact(e.handler, name);
+        }
+        // Switch-gate commit (same atomic round): runtime-local, cannot fail —
+        // a tool/command failure above skips this entirely via continue, so a
+        // failed activation never leaves a veto behind either.
+        for (const e of pendingSwitch) {
+            e.committedUnregister = addBeforeSwitchHandler(entryPath, e.handler);
+        }
+        for (const p of pendingHandlers) {
+            let list = handlers.get(p.event);
+            if (!list) {
+                list = [];
+                handlers.set(p.event, list);
+            }
+            list.push({ extensionPath: entryPath, handler: p.handler });
+        }
+        loaded.push({ path: entryPath, name });
+    }
+    return runtime;
+}