@forgeax/interface 0.4.1

package/dist/package/node/lib/lucide-icon.js

@@ -0,0 +1,20 @@
+import { Box, icons as LucideIcons, } from 'lucide-react';
+/** kebab / snake / spaced → Lucide registry PascalCase key. */
+function toPascalCase(name) {
+    return name
+        .trim()
+        .split(/[-_\s]+/)
+        .filter(Boolean)
+        .map((part) => `${part.charAt(0).toUpperCase()}${part.slice(1)}`)
+        .join('');
+}
+/** Resolve only explicit Lucide declarations; emoji and arbitrary text are invalid. */
+export function declaredLucideIcon(name) {
+    if (!name || !/^[A-Za-z][A-Za-z0-9_\-\s]*$/.test(name.trim()))
+        return undefined;
+    return LucideIcons[toPascalCase(name)];
+}
+/** Missing or invalid declarations receive the neutral product fallback. */
+export function lucideIconOrBox(name) {
+    return declaredLucideIcon(name) ?? Box;
+}

package/dist/package/node/lib/menu-registry.js

@@ -0,0 +1,197 @@
+/** menu-registry —— 顶部菜单栏的单一真值源 (SSOT for the menu bar).
+ *
+ *  一张注册表服务两个消费者 (压缩公理:消掉「Web 菜单和原生菜单是不是同一套?」):
+ *    1. Web 端渲染器 (React) —— 通过 `snapshotMenu(...)` / `snapshotAllMenus()` + `onMenuChange`
+ *       走 useSyncExternalStore 拿到当前菜单结构;
+ *    2. Tauri 原生菜单桥接 —— 通过 `serializeMenusForNative(t)` 拿到已翻译、去函数、
+ *       JSON 可序列化的原生菜单契约,一次性 build native menu / 每次注册表变化时 rebuild.
+ *
+ *  设计与 action-registry.ts 对齐 (模块级 Map 页级单例 + change listener):
+ *    - 菜单项按 `menu`(顶层大类) + `group`(段落分组) + `order`(段内序) 三级组织;
+ *    - 同 id 重复注册 = **替换** (幂等,HMR / StrictMode 双挂载安全,cleanup
+ *      走身份检查避免误删);
+ *    - 键位串遵循全仓 canonical combo 格式 (见 lib/global-shortcuts.ts `prettyCombo`),
+ *      例:'Ctrl+S' / 'Ctrl+Shift+Z' / 'Ctrl+,'。Web 显示走 prettyCombo,原生菜单走
+ *      `serializeMenusForNative` 内部的 accelerator 转换 (Ctrl→CmdOrCtrl,保留 Shift/Alt)。
+ *
+ *  分隔符策略 (评审):**注册者不显式发 separator sentinel** —— 只填 `group`,
+ *  渲染器按 `snapshotMenu` 返回结果中相邻两项的 `group` 差异自行绘制分隔线;
+ *  原生序列化则在 `serializeMenusForNative` 中把段边界翻成 `separatorBefore=true`。
+ *  这样避免维护「三种分隔来源」(注册者手插 + 渲染器 + 原生桥)—— 一处派生 (§2 Derive)。
+ */
+// ─── 注册表本体 (模块级 Map,页级单例) ────────────────────────────────────────
+const items = new Map();
+const changeListeners = new Set();
+function notifyChange() {
+    for (const cb of changeListeners) {
+        try {
+            cb();
+        }
+        catch {
+            /* listener 异常不传染 */
+        }
+    }
+}
+/** 注册一项菜单 —— 同 id 重复注册 = 替换 (幂等,HMR / StrictMode 双挂载安全)。
+ *  返回 cleanup 函数;cleanup 幂等 (身份检查:仅当当前项仍是本次注册的 def
+ *  才 delete,避免 A 注册→A 注销 后误删掉 B 的 same-id 覆盖)。
+ *
+ *  设计变更 (T7 集成):初版为 throw-on-duplicate,与 action-registry 的
+ *  「替换即幂等」策略不一致 —— React StrictMode 会双执行 App.tsx 的
+ *  bootstrapAppHost useEffect,两次 setup 并发跑到同一个模块级 Map 时必抛
+ *  「duplicate menu item id」把整个菜单栏打空。改为 last-writer-wins 后
+ *  两次 setup 都能顺利完成,先释放的 cleanup 通过身份检查不会误删,
+ *  与 action-registry 的语义对齐 (§SSOT / 兄弟注册表一致性)。 */
+export function registerMenuItem(def) {
+    items.set(def.id, def);
+    notifyChange();
+    return () => {
+        if (items.get(def.id) === def) {
+            items.delete(def.id);
+            notifyChange();
+        }
+    };
+}
+/** 注册表变更订阅 —— 供 useSyncExternalStore / native bridge rebuild 消费。 */
+export function onMenuChange(listener) {
+    changeListeners.add(listener);
+    return () => {
+        changeListeners.delete(listener);
+    };
+}
+// ─── 派生视图:排序与快照 (SSOT 是 items Map;所有视图都是纯 derive) ─────────
+/** 排序规则:先按 group 的**首次出现顺序**分段,段内按 order 升序 (相同 order 用
+ *  插入顺序破平局,稳定排序)。JS `Array.prototype.sort` 从 ES2019 起要求稳定,
+ *  Bun/V8/JSC 均已合规,直接用即可。 */
+function sortMenuItems(list) {
+    const groupFirstIndex = new Map();
+    list.forEach((item, idx) => {
+        if (!groupFirstIndex.has(item.group))
+            groupFirstIndex.set(item.group, idx);
+    });
+    const decorated = list.map((item, idx) => ({ item, idx }));
+    decorated.sort((a, b) => {
+        const ga = groupFirstIndex.get(a.item.group);
+        const gb = groupFirstIndex.get(b.item.group);
+        if (ga !== gb)
+            return ga - gb;
+        if (a.item.order !== b.item.order)
+            return a.item.order - b.item.order;
+        return a.idx - b.idx; // 稳定破平局:插入顺序
+    });
+    return decorated.map((d) => d.item);
+}
+/** 取单个菜单的排序后条目 —— 渲染器直接消费。 */
+export function snapshotMenu(menu) {
+    const list = [];
+    for (const def of items.values()) {
+        if (def.menu === menu)
+            list.push(def);
+    }
+    return sortMenuItems(list);
+}
+const ALL_MENUS = ['brand', 'file', 'edit', 'window', 'build', 'select', 'help', 'publish'];
+/** 取所有菜单的排序后条目,按 MenuId 组织。 */
+export function snapshotAllMenus() {
+    const out = {};
+    for (const m of ALL_MENUS)
+        out[m] = snapshotMenu(m);
+    return out;
+}
+/** 键位串 → 原生 accelerator 转换。canonical 形如 'Ctrl+Shift+S';原生形 'CmdOrCtrl+Shift+S'
+ *  (Tauri/Electron 通用惯例:Ctrl 走 CmdOrCtrl,让 macOS 走 ⌘、其它平台走 Ctrl)。 */
+function toNativeAccelerator(combo) {
+    return combo
+        .split('+')
+        .map((seg) => (seg === 'Ctrl' ? 'CmdOrCtrl' : seg))
+        .join('+');
+}
+/** 递归序列化一项 (含 children) —— 返回值必须完全无函数,可直接 JSON.stringify。 */
+function serializeItem(def, translate) {
+    if (def.when && !def.when())
+        return null; // 隐藏项直接 drop
+    // Static `children` OR a `dynamicChildren` derivation — both serialize the
+    // same way. dynamicChildren is evaluated at serialize time (native menu is
+    // rebuilt on every registry change, so it re-derives with the cache current
+    // at that moment). Web + native thus share one derivation (§Derive / §SSOT).
+    const childDefs = def.children && def.children.length > 0
+        ? def.children
+        : def.dynamicChildren
+            ? def.dynamicChildren()
+            : null;
+    // enabled: explicit predicate wins; a submenu opener (has children) defaults
+    // enabled even without a command; else `!!commandId`. Mirrors the web
+    // renderer's resolveEnabled so both bars agree on which items are clickable.
+    const enabledResolved = def.enabled
+        ? def.enabled()
+        : (childDefs && childDefs.length > 0)
+            ? true
+            : !!def.commandId;
+    const out = {
+        id: def.id,
+        label: translate(def.labelKey),
+        enabled: enabledResolved,
+    };
+    if (def.keybinding)
+        out.accelerator = toNativeAccelerator(def.keybinding);
+    if (def.danger)
+        out.danger = true;
+    if (childDefs && childDefs.length > 0) {
+        const kids = [];
+        for (const child of childDefs) {
+            const ser = serializeItem(child, translate);
+            if (ser)
+                kids.push(ser);
+        }
+        if (kids.length > 0)
+            out.children = kids;
+    }
+    return out;
+}
+/** 序列化全部菜单为原生契约 —— T5 (Tauri 桥) 的唯一入口。契约要点:
+ *    - `when === false` 的项被 drop;
+ *    - `enabled` 缺省时默认 = `!!commandId` (无命令 = 禁用);
+ *    - `labelKey` 走 `translate` 翻译,函数不出墙;
+ *    - `keybinding` 转 native accelerator (Ctrl→CmdOrCtrl,Shift/Alt 保留);
+ *    - 段边界翻成 `separatorBefore=true` (每个菜单首项除外);
+ *    - 输出**完全 JSON 可序列化** (JSON.stringify 无损 roundtrip,无函数残留)。 */
+export function serializeMenusForNative(translate) {
+    const out = [];
+    for (const menu of ALL_MENUS) {
+        const sorted = snapshotMenu(menu);
+        const serialized = [];
+        let prevGroup = null;
+        for (const def of sorted) {
+            const ser = serializeItem(def, translate);
+            if (!ser) {
+                // when=false 的项被 drop;下一项若换 group 依然按已见 group 判段边界。
+                prevGroup = def.group;
+                continue;
+            }
+            if (prevGroup !== null && def.group !== prevGroup)
+                ser.separatorBefore = true;
+            serialized.push(ser);
+            prevGroup = def.group;
+        }
+        out.push({ menu, items: serialized });
+    }
+    return out;
+}
+// ─── Vite HMR: preserve registrations across hot module swap ───────────────
+if (import.meta.hot) {
+    import.meta.hot.dispose((data) => {
+        data.menuItems = [...items.entries()];
+    });
+    const saved = import.meta.hot.data.menuItems;
+    if (saved) {
+        for (const [id, def] of saved)
+            items.set(id, def);
+        notifyChange();
+    }
+}
+// ─── 测试辅助 (生产代码不要调) ─────────────────────────────────────────────
+/** 清空注册表 —— 仅供单测 beforeEach 使用。 */
+export function __resetMenuRegistryForTest() {
+    items.clear();
+    changeListeners.clear();
+}

package/dist/package/node/lib/model-config.js

@@ -0,0 +1,72 @@
+// @desc Frontend client for `builtin/commands/models.ts` —— list / get / set
+//
+// 三个 helper 一律走 `/api/commands/*` 走 transport.ts 的 `{ args }` 协议。统一在
+// 这里抛 server 端的 `result.error`，调用方只需 try/catch 即可。
+//
+// 与 `lib/forgeax-bridge.ts:listSessionAgents` 同款套路（POST query+args）。
+async function callQuery(name, args) {
+    const r = await fetch(`/api/commands/${name}/query`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ args }),
+    });
+    // transport.ts 在 result.ok=false 时仍返 500 + body —— 都按 json 解析。
+    const j = (await r.json());
+    if (!j.result?.ok)
+        throw new Error(j.result?.error ?? `${name} failed (HTTP ${r.status})`);
+    return j.result.data;
+}
+async function callExecute(name, args) {
+    const r = await fetch(`/api/commands/${name}/execute`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ args }),
+    });
+    const j = (await r.json());
+    if (!j.result?.ok)
+        throw new Error(j.result?.error ?? `${name} failed (HTTP ${r.status})`);
+    return j.result.data;
+}
+/** Catalog 来自 `~/.forgeax/key/models.json`（disk）与 LiteLLM `/v1/models`（live）
+ *  的合并：live 权威时展示集合即 live 那份，disk 只静默补元数据。
+ *  返回顺序由 server 端按「强度」排好（claude 族最前 → 版本号降序 → tier），
+ *  前端不再二次排序，直接平铺渲染。providerId 非空时返回对应内核的
+ *  driver-scoped catalog。 */
+export async function listModels(providerId) {
+    return (await listModelsWithMeta(providerId)).models;
+}
+/** listModels + driver 元数据透传(内核目录路径需要;见 CatalogDriverMeta)。 */
+export async function listModelsWithMeta(providerId) {
+    const args = providerId ? [providerId] : [];
+    const data = await callQuery("list_models", args);
+    return { models: data.models ?? [], driver: data.driver };
+}
+/** Full `list_models` payload including the live-probe summary. Use this when
+ *  connectivity must NOT treat disk-only fallback as success (onboarding). */
+export async function listModelsWithLive(providerId) {
+    const args = providerId ? [providerId] : [];
+    const data = await callQuery("list_models", args);
+    return {
+        models: data.models ?? [],
+        live: data.live ?? { source: "disabled", ids: 0 },
+    };
+}
+/** 读 agent.json::models.model —— **不**经 AGENT_DEFAULTS deep-merge，
+ *  能区分"用户没配"（chain=[]、raw=null）和"显式空 chain"（chain=[]、raw=[]）。 */
+export async function getAgentModel(sid, agentPath) {
+    return callQuery("get_agent_model", [sid, agentPath]);
+}
+/** 写 agent.json models.model = string[]（单模型也写成 ["MODEL"]）。
+ *  已 running 的 agent server 端会自动 controlAgent("restart") 重读盘。 */
+export async function setAgentModels(sid, agentPath, models) {
+    if (models.length === 0)
+        throw new Error("setAgentModels: at least one model required");
+    return callExecute("set_agent_models", [sid, agentPath, ...models]);
+}
+/** Toggle a model's "show in Composer picker" visibility. Persists to
+ *  ~/.forgeax/key/models-hidden.json on the server side. Caller should refresh
+ *  the catalog (useModelCatalog.refresh) after a successful toggle so the
+ *  single-mode dropdown re-filters. */
+export async function setModelHidden(id, hidden) {
+    return callExecute("set_model_hidden", [id, hidden ? "1" : "0"]);
+}

package/dist/package/node/lib/model-prefs.js

@@ -0,0 +1,53 @@
+// Per-provider "last hand-picked model" memory.
+//
+// Two distinct gestures land on different defaults, and conflating them was the
+// reported bug:
+//   • Switching PROVIDER is a deliberate "give me this provider's default" — the
+//     active-session reset policy belongs to Chat. We do NOT record that here.
+//   • Creating a NEW SESSION should resume "where I left off" for the current
+//     provider — the model the user last HAND-PICKED in the composer. Only the
+//     manual pick writes here; new sessions read it to seed their agent model.
+//
+// Keyed by catalog-provider id: a CLI driver id (claude-code / codex / …) or
+// 'forgeax' for the native gateway path (catalogProviderId === null).
+import { STORAGE_KEYS } from './storageKeys.js';
+function storageKey() {
+    return STORAGE_KEYS.lastModelByProvider;
+}
+function providerKey(catalogProviderId) {
+    return catalogProviderId && catalogProviderId !== 'forgeax' ? catalogProviderId : 'forgeax';
+}
+function readMap() {
+    try {
+        const raw = localStorage.getItem(storageKey());
+        if (!raw)
+            return {};
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return {};
+    }
+    catch {
+        return {};
+    }
+}
+/** The model the user last hand-picked for this provider, or null if none. */
+export function getLastModel(catalogProviderId) {
+    const v = readMap()[providerKey(catalogProviderId)];
+    return typeof v === 'string' && v.length > 0 ? v : null;
+}
+/** Record a HAND-PICKED model for this provider (called from the composer's
+ *  model picker onChange — never from a provider-switch reset). */
+export function recordLastModel(catalogProviderId, modelId) {
+    if (!modelId)
+        return;
+    try {
+        const map = readMap();
+        map[providerKey(catalogProviderId)] = modelId;
+        localStorage.setItem(storageKey(), JSON.stringify(map));
+    }
+    catch {
+        /* ignore (private mode / SSR) */
+    }
+}

package/dist/package/node/lib/model-route/index.js

@@ -0,0 +1,175 @@
+// ActiveModelRoute — the single source of truth for "which model source is the
+// chat actually using right now", and the one place that mutation flows through.
+//
+// Design §12 (adopted revisions) calls for a closed-union ActiveModelRoute from
+// which `providerOverride` is DERIVED rather than a second hand-maintained
+// field. In this codebase the runtime routing is already decided by two pieces
+// of existing state — we do NOT add a third:
+//
+//   1. store.providerOverride (per-session): null → native forgeax path
+//      (POST /api/sessions/:sid/messages); non-null → a CLI driver via
+//      /api/cli/chat (claude-code / codex / cursor-agent / codebuddy).
+//   2. .env FORGEAX_MODEL: which model the native path resolves (auto-resolver
+//      routes by id prefix — claude-* → Anthropic, gpt-* → OpenAI, …).
+//
+// So the "active source" the Providers panel + onboarding show is a pure
+// DERIVATION over (providerOverride, FORGEAX_MODEL), and switching source is a
+// single `applyModelRoute` that writes both consistently. No ghost field.
+import { useShellStore } from '../../store.js';
+import { getAgentModel, listModels, setAgentModels } from '../model-config.js';
+import { getLastModel } from '../model-prefs.js';
+const RE_OPENAI = /^(gpt-|o[1-9]|codex-)/i;
+/**
+ * Derive the active source id purely from the two runtime inputs. Kept a pure
+ * function so it can be unit-tested and reused by both the Providers panel and
+ * the onboarding readiness gate.
+ */
+export function deriveActiveSource(providerOverride, forgeaxModel) {
+    // A CLI override always wins — the chat is routed through /api/cli/chat.
+    if (providerOverride && providerOverride !== 'forgeax') {
+        return providerOverride;
+    }
+    // Native path: the model id tells us the source.
+    const m = (forgeaxModel ?? '').trim();
+    if (m && RE_OPENAI.test(m))
+        return 'api-key';
+    // Any native model (claude-*/gemini-*/proxy) — still the "api-key" bucket from
+    // the Providers UI's perspective (BYO credential).
+    if (m)
+        return 'api-key';
+    return null;
+}
+async function patchEnv(patch) {
+    const r = await fetch('/api/settings/env', {
+        method: 'PUT',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(patch),
+    });
+    const j = (await r.json().catch(() => null));
+    if (!r.ok || !j?.ok) {
+        throw new Error(j?.error ?? `HTTP ${r.status}`);
+    }
+}
+/**
+ * Switch the active model source. Writes the two underlying pieces of state
+ * atomically-enough (env then override) so the derived active source lands on
+ * the requested value. Returns once persisted.
+ *
+ *  - api-key → providerOverride=null + FORGEAX_MODEL=<vendor id> (env keys are
+ *              saved separately via the Providers EnvFields)
+ *  - cli     → providerOverride=<id> (FORGEAX_MODEL untouched — the driver owns
+ *              its own model selection)
+ */
+export async function applyModelRoute(source) {
+    const setProviderOverride = useShellStore.getState().setProviderOverride;
+    switch (source.kind) {
+        case 'api-key':
+            await patchEnv({ FORGEAX_MODEL: source.model });
+            setProviderOverride(null);
+            return;
+        case 'cli':
+            setProviderOverride(source.providerId);
+            return;
+    }
+}
+/** The catalog provider id currently in effect, derived from providerOverride. */
+export function currentCatalogProvider(providerOverride) {
+    return providerOverride && providerOverride !== 'forgeax' ? providerOverride : null;
+}
+/** Preserve the last explicit user pick when it still belongs to this catalog;
+ * otherwise use the provider's first visible/default entry. */
+export function preferredCatalogModel(catalog, remembered) {
+    if (remembered && catalog.some((model) => model.id === remembered && !model.hidden)) {
+        return remembered;
+    }
+    return catalog.find((model) => !model.hidden)?.id ?? catalog[0]?.id;
+}
+/** Model seeding policy for a newly scaffolded session. Native sessions only
+ * override their scaffold default when the user has an applicable remembered
+ * pick; CLI sessions must always land on a model from that driver's catalog. */
+export function initialSessionCatalogModel(catalog, catalogProviderId, remembered) {
+    const rememberedEntry = remembered
+        ? catalog.find((model) => model.id === remembered && !model.hidden)
+        : undefined;
+    if (rememberedEntry)
+        return rememberedEntry.id;
+    return catalogProviderId ? preferredCatalogModel(catalog, null) : undefined;
+}
+/**
+ * Reset EVERY open session's agent model to a catalog's default.
+ *
+ * `providerOverride` is GLOBAL (one value for the whole app), so switching it
+ * re-routes ALL sessions through the new provider — but each session's
+ * agent.json still pins the OLD provider's model id, which may not exist in the
+ * new provider's catalog. The product requirement is therefore: switching the
+ * provider in Settings resets the current model of ALL active sessions to the
+ * new provider's default (not just the focused one). We compute the default
+ * once (provider-scoped) and write it into each open tab's agent.json. Returns
+ * the model set + how many sessions were updated, or null when nothing to do.
+ */
+export async function resetOpenSessionsModelToProviderDefault(catalogProviderId) {
+    const st = useShellStore.getState();
+    const targets = st.tabs
+        .map((t) => ({ sid: t.sid, agentPath: t.agentId }))
+        .filter((x) => !!x.sid && !!x.agentPath);
+    if (targets.length === 0)
+        return null;
+    const catalog = await listModels(catalogProviderId);
+    const nextModel = catalog.find((m) => !m.hidden)?.id ?? catalog[0]?.id;
+    if (!nextModel)
+        return null;
+    let count = 0;
+    for (const { sid, agentPath } of targets) {
+        try {
+            await setAgentModels(sid, agentPath, [nextModel]);
+            count++;
+        }
+        catch (e) {
+            // Best-effort per session — one bad agent.json must not abort the rest.
+            console.warn('[model-route] reset session model failed', { sid, agentPath, err: e });
+        }
+    }
+    return count > 0 ? { selected: nextModel, count } : null;
+}
+/**
+ * On SESSION SWITCH: conform the switched-to session's model to the currently
+ * ACTIVE provider (Settings › Providers is the single global provider setting;
+ * the in-chat switcher is hidden). "Does this session's provider match the
+ * active provider?" is answered by CATALOG MEMBERSHIP — a session whose
+ * agent.json model isn't in the active provider's catalog was last touched
+ * under a DIFFERENT provider (e.g. switching game loads that game's disk
+ * sessions, which the last provider-switch reset never reached).
+ *
+ *   • mismatch → snap the session's model to this provider's last HAND-PICKED
+ *     model (model-prefs), else its catalog default (first non-hidden);
+ *   • match (model already in the active catalog) → leave it untouched
+ *     ("同 provider 就不管").
+ *
+ * Best-effort + returns null on no-op: an empty catalog, a missing model, or
+ * any IO failure must never block the session switch. Returns the model set on
+ * a mismatch so the caller can repaint immediately if it wants.
+ */
+export async function reconcileSessionModelToActiveProvider(sid, agentPath) {
+    const catalogProviderId = currentCatalogProvider(useShellStore.getState().providerOverride);
+    const catalog = await listModels(catalogProviderId).catch(() => null);
+    if (!catalog || catalog.length === 0)
+        return null;
+    const cur = await getAgentModel(sid, agentPath).catch(() => null);
+    const currentId = cur?.selected ?? null;
+    // Same provider — the session's model is a member of the active catalog. Leave it.
+    if (currentId && catalog.some((m) => m.id === currentId))
+        return null;
+    // Mismatch — prefer this provider's last hand-picked model, else its default.
+    const remembered = getLastModel(catalogProviderId);
+    const next = preferredCatalogModel(catalog, remembered);
+    if (!next)
+        return null;
+    try {
+        await setAgentModels(sid, agentPath, [next]);
+        return { selected: next };
+    }
+    catch (e) {
+        console.warn('[model-route] reconcile session model failed', { sid, agentPath, err: e });
+        return null;
+    }
+}

package/dist/package/node/lib/narrative-copilot.js

@@ -0,0 +1,105 @@
+/** 叙事工坊「完成即重唤醒」闭环（END 侧）。
+ *
+ *  背景：剧情师 Kotone 是一问一答的 agent —— 用它跑叙事管线时，它在**启动那一轮**里
+ *  讲完选型、调 `narrative:start-pipeline`（秒回 runId）后这一轮就结束、随即静默。管线在
+ *  后台跑几分钟，跑完是个**后台事件**，没人唤醒 Kotone，于是用户若不再开口就永远等不到
+ *  「完成总结」。
+ *
+ *  本模块补上这一环：监听 Kotone 调用 start-pipeline，轮询叙事后端直到该 run 进入终态，
+ *  然后给 Kotone（事件 emitter）投一条 user_input 系统提示，触发它产出完成总结。
+ *
+ *  为什么放前端、靠 history 轮询：
+ *  - `hook:toolResult` 事件**不带工具返回值**，前端拿不到 runId；但叙事后端同源暴露
+ *    `/api/narrative/history`（带 status），且后端强制单实例 run，所以「当前在跑的那条」
+ *    就是 Kotone 刚起的。
+ *  - 前端是同时连着「agent 会话(WS)」和「叙事后端(REST)」的唯一协调者；放后端要跨进程。
+ *
+ *  START 侧（左栏回填 + 中间预览直播）由 extension-narrative viz 的 useAutoAttach 自包含完成，
+ *  不在本模块职责内。 */
+import { getSessionClient } from '../store-parts/session-client.js';
+const START_TOOL = 'narrative:start-pipeline';
+const POLL_MS = 5_000;
+/** 安全上限：超过则放弃 watch（避免 zombie run 让定时器永生）。 */
+const MAX_WATCH_MS = 40 * 60 * 1_000;
+/** 同一 (sid::agent) 同时只跑一个 watcher，避免重复唤醒。 */
+const activeWatchers = new Set();
+async function fetchNarrativeHistory() {
+    try {
+        const r = await fetch('/api/narrative/history');
+        if (!r.ok)
+            return [];
+        const j = (await r.json());
+        return Array.isArray(j) ? j : [];
+    }
+    catch {
+        return [];
+    }
+}
+function watchRunToCompletion(sid, agent) {
+    const watcherKey = `${sid}::${agent}`;
+    if (activeWatchers.has(watcherKey))
+        return; // 已在 watch（同一 agent 连点不重复起）
+    activeWatchers.add(watcherKey);
+    const startedAt = Date.now();
+    // 记住「我们确实看到过它在跑」的那条 run —— 只有见过 running 才认它真起来了，
+    // 避免 toolCall 后 run 尚未起来就误判「已结束」。
+    let seenRunningKey = null;
+    const stop = () => {
+        window.clearInterval(timer);
+        activeWatchers.delete(watcherKey);
+    };
+    const timer = window.setInterval(() => {
+        void (async () => {
+            if (Date.now() - startedAt > MAX_WATCH_MS) {
+                stop();
+                return;
+            }
+            const history = await fetchNarrativeHistory();
+            if (history.length === 0)
+                return;
+            const running = history.find((e) => e.status === 'running' && !!e.id);
+            if (running) {
+                seenRunningKey = running.key;
+                return;
+            }
+            // 没有 running 了。若我们之前见过它在跑 → 判定结束，取它的终态去唤醒。
+            if (seenRunningKey) {
+                const entry = history.find((e) => e.key === seenRunningKey);
+                const status = entry?.status ?? 'completed';
+                stop();
+                await nudgeKotone(sid, agent, seenRunningKey, status);
+            }
+            // 还没见过 running（run 尚未起来 / 起得很快已结束）—— 继续等到超时为止。
+        })();
+    }, POLL_MS);
+}
+async function nudgeKotone(sid, agent, runKey, status) {
+    const completed = status === 'completed';
+    const content = completed
+        ? `【叙事工坊 · 系统通知】你刚启动的管线已完成（输出目录：${runKey}）。请用 narrative:get-run-status / narrative:get-story-tree / narrative:read-file 看一下产出，按你剧情师的视角给用户一段完成总结：跑了哪些环节、产出是什么、是否符合用户需求（默认符合，明显跑偏才指出并建议 narrative:regenerate-step）。`
+        : `【叙事工坊 · 系统通知】你刚启动的管线已结束，状态为「${status}」（输出目录：${runKey}）。请用 narrative:get-run-status 看一下停在哪一步、为什么，给用户一句说明并建议下一步（narrative:resume-pipeline 续跑 / 重新启动等）。`;
+    await getSessionClient().emitForgeaXMessage(sid, content, {
+        to: agent,
+        type: 'user_input',
+        // session-stream 据此把它渲染成「叙事工坊」系统来信行，而非伪装成用户气泡。
+        payload: { narrativeAutoNudge: true, runKey, runStatus: status },
+    }).catch(() => {
+        /* 唤醒失败静默 —— 用户仍可手动追问，不阻塞主流程 */
+    });
+}
+/** Boot 时调一次（main.tsx）。按 key 注册，HMR 重载会覆盖旧 handler。 */
+export function subscribeNarrativeCopilot() {
+    getSessionClient().onSessionEvent('narrative-copilot', (e) => {
+        const ev = e.event;
+        if (!ev || ev.type !== 'hook:toolCall')
+            return;
+        const payload = ev.payload;
+        const toolName = payload.name ?? payload.toolCall?.name;
+        if (toolName !== START_TOOL)
+            return;
+        const agent = e.emitterId;
+        if (!agent)
+            return;
+        watchRunToCompletion(e.sid, agent);
+    });
+}