@steerable/agent-shell 0.6.15

package/dist/brand.js

@@ -0,0 +1,92 @@
+/**
+ * 品牌/ flavor 单一真源（主进程与 Node 侧共用）。
+ *
+ * flavor 是开放字符串（ScenarioId，0.3g 起不再是二值联合）：`generic`
+ * 是无场景包的产品 flavor，其余 flavor 由场景包激活。合法 flavor 集合
+ * = 应用层 products/manifest.json 的 flavors 键（best-effort 校验，
+ * 读不到清单时不强制）。
+ *
+ * flavor 在打包时由 electron-builder.js 通过 extraMetadata.flavor
+ * 写进包内 package.json；运行时从这里读回。dev 优先读 APP_FLAVOR，
+ * 再回退包内 package.json 的 flavor 字段，最终兜底 generic。
+ *
+ * 品牌数据（3.1 起全部产品注入）：产品组装根（products/<id>/active.ts）
+ * 在模块求值早期调用 setProductBrand()——数据源是 product.json 的
+ * brand 字段（无包产品）或激活包的 pack.json brand（0.3g 机制）。
+ * shell 默认品牌是中性占位（Steerable Shell），不注入不出产品名。
+ * getBrand() 在覆盖注入后重算。
+ *
+ * 本模块只允许依赖 node 内置模块——llm-settings.ts 会被 vitest 直接 import，
+ * 不能碰 electron / better-sqlite3。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { getAppRootDir } from './runtime.js';
+/** shell 默认智能体；场景产品里仍可选，但不一定作为首页默认。 */
+export const LOCAL_ASSISTANT_AGENT_ID = 'local-assistant';
+/** 内置「智能助手」：种子时 `loadAllSkills` 开启（无视触发条件全量加载技能）。 */
+export const ALL_ROUND_ASSISTANT_AGENT_ID = 'all-round-assistant';
+/**
+ * shell 默认品牌——中性框架占位（3.1 起产品名一律由产品组装根注入，
+ * 见 products/<id>/product.json 的 brand 字段或激活包的 pack.json）。
+ */
+const SHELL_BRAND = {
+    displayName: 'Steerable Shell',
+    agentName: 'Agent',
+    tagline: '一款本地桌面 AI 伙伴',
+    defaultAgentId: LOCAL_ASSISTANT_AGENT_ID,
+};
+let productBrand = null;
+let cached = null;
+/**
+ * 注入产品品牌（产品组装根在第一个 import 时调用）。重复注入抛错
+ * （组装期笔误，fail fast）。注入后作废缓存，后续 getBrand() 重算。
+ */
+export function setProductBrand(brand) {
+    if (productBrand) {
+        throw new Error('[brand] product brand already set');
+    }
+    productBrand = brand;
+    cached = null;
+}
+/** 合法 flavor 集合（应用层 products/manifest.json 的 flavors 键）；读不到返回 null（不强制）。 */
+function knownFlavors() {
+    try {
+        // 3.2 起 flavor→包 清单是应用层数据（products/manifest.json），由产品
+        // 组装根经 setAppRootDir 注入锚点；shell 包内不再携带该清单。
+        const manifest = JSON.parse(fs.readFileSync(path.join(getAppRootDir(), 'products', 'manifest.json'), 'utf8'));
+        return Object.keys(manifest.flavors ?? {});
+    }
+    catch {
+        return null;
+    }
+}
+function detectFlavor() {
+    const known = knownFlavors();
+    const isKnown = (value) => !known || known.includes(value);
+    const fromEnv = process.env.APP_FLAVOR;
+    if (fromEnv) {
+        if (isKnown(fromEnv))
+            return fromEnv;
+        throw new Error(`Unknown APP_FLAVOR=${fromEnv}. Known flavors: ${known?.join(', ') ?? '(manifest unavailable)'}`);
+    }
+    try {
+        // 应用根 package.json 的 flavor 字段（打包时 electron-builder 经
+        // extraMetadata.flavor 写入包内 package.json；3.2 起应用根由产品注入）。
+        const pkgPath = path.join(getAppRootDir(), 'package.json');
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+        if (pkg.flavor && isKnown(pkg.flavor))
+            return pkg.flavor;
+    }
+    catch {
+        // 读不到 package.json 时用兜底
+    }
+    return 'generic';
+}
+export function getBrand() {
+    if (!cached) {
+        const flavor = detectFlavor();
+        cached = { flavor, ...(productBrand ?? SHELL_BRAND) };
+    }
+    return cached;
+}

package/dist/host/http-routes.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 场景包 HTTP 路由注册表（BS 宿主扩展点，0.4）。
+ *
+ * 包把 `/host/<packId>/*` 前缀下的路由声明为 HttpRouteContribution，由
+ * server/index.ts 在组装期注册；http-server 在宿主自带路由之后、404 之前
+ * 按注册顺序精确/段参数匹配。路径必须带 `/host/<packId>/` 前缀——与 IPC
+ * 通道的 `<packId>:` 前缀同一命名空间纪律。
+ */
+import type { HttpRouteContribution, HttpRouteRequest } from '../scenario/pack.js';
+export type { HttpRouteContribution, HttpRouteRequest };
+/** 注册包 HTTP 路由；路径越出包前缀直接抛错（组装期失败，不进运行时）。 */
+export declare function registerPackHttpRoutes(packId: string, routes: readonly HttpRouteContribution[]): void;
+/** 测试钩子：清空注册表。 */
+export declare function resetPackHttpRoutes(): void;
+/**
+ * 匹配已注册的包路由。段参数（`:id`）逐段捕获进 params；无匹配返回 null。
+ */
+export declare function matchPackHttpRoute(method: string, pathname: string): {
+    route: HttpRouteContribution;
+    params: Record<string, string>;
+} | null;

package/dist/host/http-routes.js

@@ -0,0 +1,55 @@
+/**
+ * 场景包 HTTP 路由注册表（BS 宿主扩展点，0.4）。
+ *
+ * 包把 `/host/<packId>/*` 前缀下的路由声明为 HttpRouteContribution，由
+ * server/index.ts 在组装期注册；http-server 在宿主自带路由之后、404 之前
+ * 按注册顺序精确/段参数匹配。路径必须带 `/host/<packId>/` 前缀——与 IPC
+ * 通道的 `<packId>:` 前缀同一命名空间纪律。
+ */
+const packHttpRoutes = [];
+function assertPackRoutePath(packId, path) {
+    if (!path.startsWith(`/host/${packId}/`)) {
+        throw new Error(`[packs] HTTP 路由 "${path}" 不合规：包 "${packId}" 的路由必须在 /host/${packId}/ 前缀下`);
+    }
+}
+/** 注册包 HTTP 路由；路径越出包前缀直接抛错（组装期失败，不进运行时）。 */
+export function registerPackHttpRoutes(packId, routes) {
+    for (const route of routes) {
+        assertPackRoutePath(packId, route.path);
+        packHttpRoutes.push(route);
+    }
+}
+/** 测试钩子：清空注册表。 */
+export function resetPackHttpRoutes() {
+    packHttpRoutes.length = 0;
+}
+/**
+ * 匹配已注册的包路由。段参数（`:id`）逐段捕获进 params；无匹配返回 null。
+ */
+export function matchPackHttpRoute(method, pathname) {
+    for (const route of packHttpRoutes) {
+        if (route.method !== method)
+            continue;
+        const params = matchPath(route.path, pathname);
+        if (params)
+            return { route, params };
+    }
+    return null;
+}
+function matchPath(pattern, pathname) {
+    const patternSegs = pattern.split('/');
+    const pathSegs = pathname.split('/');
+    if (patternSegs.length !== pathSegs.length)
+        return null;
+    const params = {};
+    for (let i = 0; i < patternSegs.length; i += 1) {
+        const seg = patternSegs[i];
+        if (seg.startsWith(':')) {
+            params[seg.slice(1)] = decodeURIComponent(pathSegs[i]);
+        }
+        else if (seg !== pathSegs[i]) {
+            return null;
+        }
+    }
+    return params;
+}

package/dist/host/ipc.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 包 IPC 绑定器（0.3e）：把包的 IpcContribution 注册到 Electron ipcMain。
+ *
+ * 命名空间规则：channel 必须以 `<packId>:` 开头——包只能占用自己的
+ * 命名空间，注册期 fail fast。handler 统一收单个序列化载荷（renderer
+ * 经 preload 透传），返回值经 IPC 结构化克隆回 renderer。
+ */
+import type { IpcContribution } from '../scenario/pack.js';
+/** 命名空间校验（纯函数，单测直接覆盖）。 */
+export declare function assertPackChannel(packId: string, channel: string): void;
+export declare function registerPackIpc(packId: string, contributions: readonly IpcContribution[]): void;

package/dist/host/ipc.js

@@ -0,0 +1,20 @@
+/**
+ * 包 IPC 绑定器（0.3e）：把包的 IpcContribution 注册到 Electron ipcMain。
+ *
+ * 命名空间规则：channel 必须以 `<packId>:` 开头——包只能占用自己的
+ * 命名空间，注册期 fail fast。handler 统一收单个序列化载荷（renderer
+ * 经 preload 透传），返回值经 IPC 结构化克隆回 renderer。
+ */
+import { ipcMain } from 'electron';
+/** 命名空间校验（纯函数，单测直接覆盖）。 */
+export function assertPackChannel(packId, channel) {
+    if (!channel.startsWith(`${packId}:`)) {
+        throw new Error(`[pack-ipc] channel "${channel}" must be namespaced under "${packId}:"`);
+    }
+}
+export function registerPackIpc(packId, contributions) {
+    for (const contribution of contributions) {
+        assertPackChannel(packId, contribution.channel);
+        ipcMain.handle(contribution.channel, (_event, payload) => contribution.handler(payload));
+    }
+}

package/dist/host/pack-assembly.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 包装配注册表（阶段 2.3）——纯构建期组合的宿主侧机制。
+ *
+ * 宿主（host/runtime.ts、main.ts、server/index.ts）不再静态 import 任何
+ * 包代码：产品组装根（products/<id>/active.ts）把包的装配函数注册进本
+ * 注册表，宿主在装配期逐个调用。产品的 tsc 编译单元只 include 自己的包，
+ * 他包代码物理上不进产品 dist。
+ *
+ * 装配分两个时机：
+ *  - import 期（active.ts 顶层）：迁移/种子/品牌等无宿主依赖的注册；
+ *  - 装配期（createHostRuntime 内）：服务/工具/路由等需要宿主能力的部分，
+ *    经 {@link PackAssemblyDeps} 注入。
+ * 入口差异：CS（main.ts）额外消费 handle.ipc，BS（server/index.ts）额外
+ * 消费 handle.httpRoutes——包的入口面贡献由宿主循环驱动，宿主代码里
+ * 不出现任何包名。
+ */
+import type Database from 'better-sqlite3';
+import type { HttpRouteContribution, IpcContribution, ToolContribution } from '../scenario/pack.js';
+/** 宿主注入包的装配能力面。包不 import 宿主装配模块，全部经回调注入。 */
+export interface PackAssemblyDeps {
+    /** 宿主借出的同一个 SQLite 连接（包只读写自己声明的包前缀表）。 */
+    readonly db: Database.Database;
+    /** 模型可见工具面（与普通回合同源）。 */
+    readonly listTools: () => {
+        name: string;
+        description: string;
+        inputSchema: unknown;
+    }[];
+    /** chatId → 绑定项目（无项目对话返回 null）。与 router.resolveChatProject 同源。 */
+    readonly resolveChatProject: (chatId: string) => {
+        name: string;
+        folderPath: string;
+    } | null;
+    /** 面向全部用户面的事件广播（CS=所有窗口 IPC，BS=SSE 总线）。 */
+    readonly broadcast: (channel: string, payload: unknown) => void;
+    /** 工具贡献注册口（toolRouter.registerToolContributions 的收窄面）。 */
+    readonly registerTools: (tools: readonly ToolContribution[]) => void;
+    /** 用量归因（包的独立流不经 router 记账路径，不注入会静默漏账）。 */
+    readonly recordUsage: (input: {
+        chatId: string;
+        kind: string;
+        provider: string | null;
+        model: string | null;
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+        cachedPromptTokens?: number;
+        costUsd?: number | null;
+    }) => void;
+    /** 行为洞察（与主对话同款 turn 事件）。 */
+    readonly recordInsight: (input: {
+        chatId: string;
+        mode?: string;
+        modelId?: string | null;
+        completionStatus?: string;
+        durationMs?: number | null;
+        toolNames?: unknown;
+        userText?: string;
+        assistantText?: string;
+    }) => void;
+    /** 装配期日志行（进宿主日志）。 */
+    readonly onLog: (line: string) => void;
+}
+/** CS 宿主的窗口能力：打开一个加载应用内路由的独立窗口。 */
+export interface PackHostWindowCapabilities {
+    /** route 如 '/<pack>-debug-log'；title 为窗口副标题（宿主拼品牌名）。 */
+    openRouteWindow(route: string, options: {
+        title: string;
+    }): Promise<void>;
+}
+/** 装配产物：宿主按入口面消费。全部槽位可选。 */
+export interface PackAssemblyHandle {
+    /** 宿主关停钩子（进程退出时按装配逆序调用）。 */
+    readonly dispose?: () => void | Promise<void>;
+    /** CS：包 IPC 贡献（需要宿主窗口能力时经 caps 注入）。 */
+    readonly ipc?: (caps: PackHostWindowCapabilities) => readonly IpcContribution[];
+    /** BS：/host/<packId>/* 路由贡献。 */
+    readonly httpRoutes?: () => readonly HttpRouteContribution[];
+}
+export type PackAssembly = (deps: PackAssemblyDeps) => PackAssemblyHandle | void;
+/** 注册包的装配函数（产品组装根在 import 期调用；重复注册同包抛错）。 */
+export declare function registerPackAssembly(packId: string, assembly: PackAssembly): void;
+/** 全部已注册装配（按注册序）。宿主装配期消费。 */
+export declare function getPackAssemblies(): ReadonlyMap<string, PackAssembly>;
+/** 测试钩子：清空注册表。 */
+export declare function resetPackAssemblies(): void;

package/dist/host/pack-assembly.js

@@ -0,0 +1,32 @@
+/**
+ * 包装配注册表（阶段 2.3）——纯构建期组合的宿主侧机制。
+ *
+ * 宿主（host/runtime.ts、main.ts、server/index.ts）不再静态 import 任何
+ * 包代码：产品组装根（products/<id>/active.ts）把包的装配函数注册进本
+ * 注册表，宿主在装配期逐个调用。产品的 tsc 编译单元只 include 自己的包，
+ * 他包代码物理上不进产品 dist。
+ *
+ * 装配分两个时机：
+ *  - import 期（active.ts 顶层）：迁移/种子/品牌等无宿主依赖的注册；
+ *  - 装配期（createHostRuntime 内）：服务/工具/路由等需要宿主能力的部分，
+ *    经 {@link PackAssemblyDeps} 注入。
+ * 入口差异：CS（main.ts）额外消费 handle.ipc，BS（server/index.ts）额外
+ * 消费 handle.httpRoutes——包的入口面贡献由宿主循环驱动，宿主代码里
+ * 不出现任何包名。
+ */
+const assemblies = new Map();
+/** 注册包的装配函数（产品组装根在 import 期调用；重复注册同包抛错）。 */
+export function registerPackAssembly(packId, assembly) {
+    if (assemblies.has(packId)) {
+        throw new Error(`[pack-assembly] duplicate registration for pack: ${packId}`);
+    }
+    assemblies.set(packId, assembly);
+}
+/** 全部已注册装配（按注册序）。宿主装配期消费。 */
+export function getPackAssemblies() {
+    return assemblies;
+}
+/** 测试钩子：清空注册表。 */
+export function resetPackAssemblies() {
+    assemblies.clear();
+}

package/dist/host/runtime.d.ts

@@ -0,0 +1,69 @@
+/**
+ * HostRuntime —— CS（Electron 主进程）与 BS（headless HTTP server）共享的
+ * 服务装配与生命周期。
+ *
+ * 历史上 main.ts 与 server/index.ts 各自装配同一份服务（LocalExecutor /
+ * ToolRouter / TaskService / sidecar …），两处逐行重复；BS 曾漏接
+ * TaskService 导致模型退化成 local_exec_shell + nohup 的"假后台"。本模块
+ * 把装配收敛为一处，两个入口只保留各自的广播机制（IPC webContents.send
+ * vs SSE 总线）与生命周期（Electron app 事件 vs SIGINT/SIGTERM）。
+ *
+ * 这也是阶段 3 上提框架后 `@steerable/agent-shell` 的核心装配件：场景包
+ * （ScenarioPack）的服务/工具贡献在 0.3 逐槽接入本模块。
+ */
+import { LocalExecutor, type LocalExecRequest, type LocalExecResult } from '../local-executor.js';
+import { LocalScriptRegistry } from '../local-script-registry.js';
+import { TerminalManager } from '../terminal-manager.js';
+import { ToolRouter } from '../tool-router.js';
+import { McpServerRegistry } from '../mcp-server-registry.js';
+import { ProjectRegistry } from '../project-registry.js';
+import { LocalBackendRouter } from '../local-backend/router.js';
+import { WorktreeService } from '../local-backend/worktree-service.js';
+import { TaskService } from '../local-backend/task-service.js';
+import { createApprovalBridge } from '../sidecar/reverse-approval.js';
+import { createAskUserBridge } from '../sidecar/reverse-ask-user.js';
+import { type PackAssemblyHandle } from './pack-assembly.js';
+export interface HostRuntimeOptions {
+    /** 面向全部用户面的事件广播（CS=所有窗口 IPC，BS=SSE 总线）。 */
+    broadcast: (channel: string, payload: unknown) => void;
+    /**
+     * 可选的"主窗口限定"广播：CS 的 LocalBackendRouter 历史上只推主窗口
+     * （title 是 nice-to-have，启动时序里没拿到主窗就静默丢）。缺省退回
+     * broadcast（BS 行为）。
+     */
+    broadcastMain?: (channel: string, payload: unknown) => void;
+    /** 是否有人能应答审批/提问（CS=有窗口，BS=有浏览器连着事件总线）。 */
+    hasWindow: () => boolean;
+    onLog: (line: string) => void;
+    /**
+     * 启动清扫 running 任务时写入的失败原因。任务流不跨进程存活，上次
+     * 进程留下的 running 是崩溃/重启签名；CS/BS 措辞不同（应用/服务）。
+     */
+    taskSweepReason: string;
+}
+export interface HostRuntime {
+    localExecutor: LocalExecutor;
+    localScriptRegistry: LocalScriptRegistry;
+    terminalManager: TerminalManager;
+    /** 包装配产物（2.3）：按产品组装根注册的包逐个装配；宿主不感知包名。 */
+    packHandles: ReadonlyMap<string, PackAssemblyHandle>;
+    mcpServerRegistry: McpServerRegistry;
+    projectRegistry: ProjectRegistry;
+    toolRouter: ToolRouter;
+    worktreeService: WorktreeService;
+    taskService: TaskService;
+    localBackendRouter: LocalBackendRouter;
+    approvalBridge: ReturnType<typeof createApprovalBridge>;
+    askUserBridge: ReturnType<typeof createAskUserBridge>;
+    /** 可见终端优先的 shell 执行缝（CS 的 local:exec-shell IPC 也用它）。 */
+    maybeExecInTerminal: (request: LocalExecRequest) => Promise<LocalExecResult | null>;
+    /**
+     * 启动后台部分：任务清扫、sidecar 启动、MCP 工具列表刷新、终端预热。
+     * 不阻塞调用方的就绪路径（sidecar python import 慢，竞速的回合由
+     * router 回退处理）。
+     */
+    start(): void;
+    /** 关停：杀终端、停 mock、关 sidecar。 */
+    shutdown(): Promise<void>;
+}
+export declare function createHostRuntime(options: HostRuntimeOptions): HostRuntime;

package/dist/host/runtime.js

@@ -0,0 +1,207 @@
+/**
+ * HostRuntime —— CS（Electron 主进程）与 BS（headless HTTP server）共享的
+ * 服务装配与生命周期。
+ *
+ * 历史上 main.ts 与 server/index.ts 各自装配同一份服务（LocalExecutor /
+ * ToolRouter / TaskService / sidecar …），两处逐行重复；BS 曾漏接
+ * TaskService 导致模型退化成 local_exec_shell + nohup 的"假后台"。本模块
+ * 把装配收敛为一处，两个入口只保留各自的广播机制（IPC webContents.send
+ * vs SSE 总线）与生命周期（Electron app 事件 vs SIGINT/SIGTERM）。
+ *
+ * 这也是阶段 3 上提框架后 `@steerable/agent-shell` 的核心装配件：场景包
+ * （ScenarioPack）的服务/工具贡献在 0.3 逐槽接入本模块。
+ */
+import { LocalExecutor, setDefaultExecTimeoutMs, } from '../local-executor.js';
+import { LocalScriptRegistry } from '../local-script-registry.js';
+import { TerminalManager } from '../terminal-manager.js';
+import { ToolRouter } from '../tool-router.js';
+import { McpServerRegistry, } from '../mcp-server-registry.js';
+import { ProjectRegistry } from '../project-registry.js';
+import { LocalBackendRouter } from '../local-backend/router.js';
+import { WorktreeService } from '../local-backend/worktree-service.js';
+import { TaskService } from '../local-backend/task-service.js';
+import { localStore } from '../storage/index.js';
+import { createApprovalBridge } from '../sidecar/reverse-approval.js';
+import { createAskUserBridge } from '../sidecar/reverse-ask-user.js';
+import { startHostSidecar, shutdownHostSidecar } from '../sidecar/boot.js';
+import { createVisibleTerminalExec } from './visible-terminal-exec.js';
+import { createJsonStore } from '../json-store.js';
+import { bindWorkspaceSkillRoots } from '../local-backend/skill-loader.js';
+import { getChatAttachmentsDir } from '../attachments.js';
+import { recordInsightTurn } from '../insights/record.js';
+import { getPackAssemblies, } from './pack-assembly.js';
+export function createHostRuntime(options) {
+    const { broadcast, hasWindow, onLog } = options;
+    const broadcastMain = options.broadcastMain ?? broadcast;
+    const localExecutor = new LocalExecutor();
+    // 恢复设置界面里配置的"命令默认超时"（保存时由 local-backend router 即时
+    // 生效，这里负责进程重启后的恢复）。
+    {
+        const persistedLlmSettings = localStore.getLlmSettings();
+        setDefaultExecTimeoutMs(persistedLlmSettings?.execTimeoutSeconds
+            ? persistedLlmSettings.execTimeoutSeconds * 1000
+            : null);
+    }
+    const localScriptRegistry = new LocalScriptRegistry();
+    const terminalManager = new TerminalManager();
+    // 外部 MCP 服务注册表（设置 → MCP 服务里导入），持久化到
+    // userData/agent-mcp-servers.json；项目注册表同理（agent-projects.json）。
+    const mcpServerRegistry = new McpServerRegistry(createJsonStore({
+        name: 'agent-mcp-servers',
+        defaults: { mcpServers: [] },
+    }));
+    const projectRegistry = new ProjectRegistry(createJsonStore({
+        name: 'agent-projects',
+        defaults: { projects: [] },
+    }));
+    bindWorkspaceSkillRoots(projectRegistry);
+    // 终端输出 / 退出 / 新会话 → 广播（CS=所有窗口，BS=SSE 总线）。
+    terminalManager.on('data', (sessionId, chunk) => {
+        broadcast('terminal:data', { sessionId, chunk });
+    });
+    terminalManager.on('exit', (sessionId, code, signal) => {
+        broadcast('terminal:exit', { sessionId, code, signal });
+    });
+    terminalManager.on('spawned', (session) => {
+        broadcast('terminal:spawned', session);
+    });
+    const maybeExecInTerminal = createVisibleTerminalExec({
+        localExecutor,
+        terminalManager,
+        broadcast,
+    });
+    const toolRouter = new ToolRouter(localExecutor, localScriptRegistry, async (request) => {
+        const viaTerminal = await maybeExecInTerminal(request);
+        if (viaTerminal)
+            return viaTerminal;
+        return localExecutor.executeShell(request);
+    }, mcpServerRegistry, projectRegistry);
+    // 4.6a/4.6b：跨 turn 后台任务 + git worktree 隔离。任务流由宿主独立驱动
+    // （不绑父 turn 生命周期，见 task-service.ts 模块头）；终态经广播推到
+    // 用户面任务面板。
+    const resolveChatProjectRoot = (chatId) => {
+        const projectId = localStore.getChat(chatId)?.projectId;
+        if (!projectId)
+            return null;
+        const project = projectRegistry.get(projectId);
+        return project ? { name: project.name, folderPath: project.folderPath } : null;
+    };
+    // 场景包装配（2.3）：产品组装根（products/<id>/active.ts）在 import 期
+    // 把包装配函数注册进 pack-assembly 注册表；这里统一装配。宿主不 import
+    // 任何包代码——产品 tsc 编译单元只含自己的包（纯构建期组合）。
+    const packHandles = new Map();
+    {
+        const packDeps = {
+            db: localStore.getPackDb(),
+            listTools: () => toolRouter.listModelSchemas(),
+            resolveChatProject: resolveChatProjectRoot,
+            broadcast,
+            registerTools: (tools) => toolRouter.registerToolContributions(tools),
+            recordUsage: (input) => localStore.recordUsageEvent(input),
+            recordInsight: (input) => recordInsightTurn(input),
+            onLog,
+        };
+        // 包迁移容错应用（3.2）：包的 import 链可能经 llm/index 等模块提前
+        // 触发 storage 单例构造（ESM 深度优先，active.ts 的注册体后于链上
+        // 单例求值）——构造时注册表尚空，此处（装配前）补上已注册包迁移。
+        // 幂等（按包 id 去重），注册表为空时零开销。
+        localStore.applyPackMigrations();
+        for (const [packId, assemble] of getPackAssemblies()) {
+            const handle = assemble(packDeps);
+            if (handle)
+                packHandles.set(packId, handle);
+        }
+    }
+    const worktreeService = new WorktreeService({ resolveProject: resolveChatProjectRoot });
+    const taskService = new TaskService({
+        store: localStore,
+        toolRouter,
+        worktreeService,
+        resolveChatProject: resolveChatProjectRoot,
+        broadcast,
+    });
+    toolRouter.setTaskServices({ taskService, worktreeService });
+    const localBackendRouter = new LocalBackendRouter(toolRouter, {
+        taskService,
+        broadcast: broadcastMain,
+    });
+    // W4-1 / W8：sidecar 反向通道的审批桥与提问桥。
+    const approvalBridge = createApprovalBridge({
+        broadcast,
+        hasWindow,
+        onLog: (line) => onLog(line),
+    });
+    const askUserBridge = createAskUserBridge({
+        broadcast,
+        hasWindow,
+        onLog: (line) => onLog(line),
+    });
+    let started = false;
+    return {
+        localExecutor,
+        localScriptRegistry,
+        terminalManager,
+        packHandles,
+        mcpServerRegistry,
+        projectRegistry,
+        toolRouter,
+        worktreeService,
+        taskService,
+        localBackendRouter,
+        approvalBridge,
+        askUserBridge,
+        maybeExecInTerminal,
+        start() {
+            if (started)
+                return;
+            started = true;
+            // 4.6a：上次进程崩溃/强杀留下的 running 任务不是真相——任务流随进程
+            // 一起死了，启动时落成 failed，任务面板据此显示"重启中断"。
+            const sweptTasks = localStore.failRunningTasks(options.taskSweepReason);
+            if (sweptTasks > 0) {
+                onLog(`[task] swept ${sweptTasks} stale running task(s)`);
+            }
+            void localExecutor.init();
+            // Not awaited: sidecar boot (python import) must not delay readiness.
+            // A turn that races the boot falls back for that turn only.
+            void startHostSidecar({
+                toolRouter,
+                resolveProjectRoot: (chatId) => localBackendRouter.resolveChatProject(chatId)?.folderPath ?? null,
+                // 项目模式下文件读写被围栏在项目目录内；会话附件目录是额外放行的
+                // 只读根，保证用户上传的文件即使在项目会话里也能被 agent 读回。
+                resolveAdditionalReadRoots: (chatId) => [getChatAttachmentsDir(chatId)],
+                approvalHandler: approvalBridge.handler,
+                askUserHandler: askUserBridge.handler,
+                // P2b: resume 时 sidecar 把记录里的读证据推给 LocalExecutor 的
+                // readFileState（CC seed_read_state）——进程重启后自动 CAS 仍成立。
+                readStateSeedHandler: (params) => {
+                    const state = params?.state;
+                    const seeded = localExecutor.seedReadState(state && typeof state === 'object' && !Array.isArray(state)
+                        ? state
+                        : {});
+                    return Promise.resolve({ seeded });
+                },
+                onLogLine: onLog,
+            });
+            // 后台刷新已启用 MCP 服务的工具列表（连接慢的 server 不阻塞启动）。
+            void mcpServerRegistry.refreshAllEnabled();
+            // 预热共享可见 PTY：首条 agent 命令不必付 shell 启动成本。
+            setTimeout(() => {
+                try {
+                    terminalManager.ensurePrimary();
+                }
+                catch (err) {
+                    onLog(`[terminal] pre-warm failed: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }, 2_000);
+        },
+        async shutdown() {
+            terminalManager.killAll();
+            // 包装配逆序关停（后装配的先停）。
+            for (const handle of [...packHandles.values()].reverse()) {
+                await handle.dispose?.();
+            }
+            await shutdownHostSidecar();
+        },
+    };
+}

package/dist/host/visible-terminal-exec.d.ts

@@ -0,0 +1,21 @@
+import { type LocalExecRequest, type LocalExecResult, type LocalExecutor } from '../local-executor.js';
+import type { TerminalManager } from '../terminal-manager.js';
+export type HostBroadcast = (channel: string, payload: unknown) => void;
+export interface VisibleTerminalExecDeps {
+    localExecutor: LocalExecutor;
+    terminalManager: TerminalManager;
+    broadcast: HostBroadcast;
+}
+/**
+ * Map a raw PTY shell binary name (e.g. `powershell.exe`, `cmd.exe`, `zsh`) to
+ * the {@link LocalExecResult} `shell` enum so the agent sees the *real* dialect
+ * it just ran under and can pick the right syntax next turn.
+ */
+export declare function mapSessionShell(shell: string): LocalExecResult['shell'];
+/**
+ * Decide whether to route a shell command through the visible PTY instead of
+ * the headless local-executor. Returns null to fall back headless. No renderer
+ * needs to be attached — the exec sentinel capture runs entirely in this
+ * process.
+ */
+export declare function createVisibleTerminalExec(deps: VisibleTerminalExecDeps): (req: LocalExecRequest) => Promise<LocalExecResult | null>;