@steerable/agent-shell 0.6.15

package/dist/sidecar/reverse-spawn.js

@@ -0,0 +1,161 @@
+/**
+ * W4.1.1 reverse channel: serve the sidecar's `host.process.spawn` by
+ * spawning the command confined on Windows via the win-spawn-helper Rust
+ * binary (restricted token + Job Object; contract: steerable-framework
+ * docs/spec/safety.md "Host capability surface").
+ *
+ * Fail closed by construction: on non-Windows platforms (which have local
+ * rewriter backends and never legitimately route here) or when the helper
+ * binary is absent, the handler throws — the sidecar surfaces a tool error
+ * and the command never runs unconfined.
+ *
+ * Enforcement honesty: the helper confines filesystem writes only. When the
+ * sidecar policy also constrains the network (`network: false` or an
+ * allow-list), the helper's exit frame lists those fields under
+ * `sandbox.notEnforced` and this handler reports `partial`.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createInterface } from 'node:readline';
+import log from 'electron-log';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+/** Helper spawn supervision cap; the sidecar's own tool timeout is shorter. */
+const HELPER_TIMEOUT_MS = 30 * 60 * 1000;
+export function resolveWinSpawnHelperPath() {
+    const binary = 'win-spawn-helper.exe';
+    // 显式覆盖（测试/调试逃生门）：设置后只认这一条路径。指向不存在的
+    // 路径即可强制走"helper 缺失"的失败分支，与 dev checkout 是否已构建
+    // Rust 二进制无关，保证失败分支的测试确定性。
+    const override = process.env.DEEPPATH_WIN_SPAWN_HELPER;
+    if (override !== undefined) {
+        return override && existsSync(override) ? override : null;
+    }
+    const resourcesPath = process.resourcesPath;
+    const candidates = [];
+    if (resourcesPath) {
+        candidates.push(join(resourcesPath, 'win-spawn-helper', binary));
+    }
+    // Dev checkout: native/ builds into resources/windows-spawn-helper/.
+    candidates.push(join(__dirname, '..', '..', 'resources', 'windows-spawn-helper', binary));
+    for (const candidate of candidates) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+export function createProcessSpawnHandler() {
+    return async (params) => {
+        if (process.platform !== 'win32') {
+            throw new Error('host.process.spawn is the no-rewriter route for Windows; ' +
+                `this host is ${process.platform} — the sidecar should have rewritten the command locally`);
+        }
+        const p = (params ?? {});
+        const command = typeof p.command === 'string' ? p.command : '';
+        if (!command.trim()) {
+            throw new Error('host.process.spawn: missing command');
+        }
+        const helper = resolveWinSpawnHelperPath();
+        if (!helper) {
+            throw new Error('win-spawn-helper.exe not found (packaged resource or resources/windows-spawn-helper); ' +
+                'refusing to run the command unconfined');
+        }
+        const cwd = typeof p.cwd === 'string' && p.cwd ? p.cwd : process.cwd();
+        const policy = p.policy ?? {};
+        return await runHelper(helper, {
+            command,
+            cwd,
+            writable_roots: policy.writableRoots ?? [],
+            network: policy.network ?? false,
+            allowed_hosts: policy.allowedHosts ?? [],
+        });
+    };
+}
+function runHelper(helperPath, spec) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(helperPath, [], {
+            stdio: ['pipe', 'pipe', 'inherit'],
+            windowsHide: true,
+        });
+        let stdout = '';
+        let stderr = '';
+        let truncated = false;
+        let timedOut = false;
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            timedOut = true;
+            log.warn('[host-spawn] helper timeout; tree-killing confined child');
+            try {
+                child.stdin.write('{"kill":true}\n');
+            }
+            catch {
+                // stdin already closed — the helper is gone; destroy below.
+            }
+            setTimeout(() => {
+                if (!settled)
+                    child.kill();
+            }, 5000).unref();
+        }, HELPER_TIMEOUT_MS);
+        timer.unref();
+        const lines = createInterface({ input: child.stdout });
+        lines.on('line', (line) => {
+            let frame;
+            try {
+                frame = JSON.parse(line);
+            }
+            catch {
+                log.warn('[host-spawn] unparseable helper frame', line.slice(0, 200));
+                return;
+            }
+            if (frame.type === 'stdout') {
+                stdout += frame.data ?? '';
+            }
+            else if (frame.type === 'stderr') {
+                stderr += frame.data ?? '';
+            }
+            else if (frame.type === 'error') {
+                settled = true;
+                clearTimeout(timer);
+                reject(new Error(`win-spawn-helper setup failed: ${frame.message ?? 'unknown'}`));
+            }
+            else if (frame.type === 'exit') {
+                settled = true;
+                clearTimeout(timer);
+                truncated = Boolean(frame.stdoutTruncated || frame.stderrTruncated);
+                const notEnforced = frame.sandbox?.notEnforced ?? [];
+                resolve({
+                    exitCode: typeof frame.code === 'number' ? frame.code : 1,
+                    stdout,
+                    stderr: timedOut
+                        ? `${stderr}\n[killed by host: exceeded ${HELPER_TIMEOUT_MS / 60_000}min spawn cap]`
+                        : stderr,
+                    truncated,
+                    sandbox: {
+                        backend: frame.sandbox?.backend ?? 'windows-restricted-token',
+                        enforcement: notEnforced.length === 0 ? 'full' : 'partial',
+                    },
+                });
+            }
+        });
+        child.on('error', (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            reject(new Error(`failed to spawn win-spawn-helper: ${err.message}`));
+        });
+        child.on('exit', (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            // Helper exited without an exit frame: crash between spawn and report.
+            reject(new Error(`win-spawn-helper exited prematurely (code ${code})`));
+        });
+        child.stdin.write(JSON.stringify(spec) + '\n');
+    });
+}

package/dist/sidecar/reverse-tools.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A4 reverse channel: serve the sidecar-hosted CoreLoop's `tool.invoke`
+ * requests by executing the tool in this process (shell / files / MCP live
+ * in Electron, not in Python).
+ *
+ * Hard-gates critical shell commands — the TS loop only annotates them, but
+ * on the CoreLoop path the framework's blocking semantics apply.
+ */
+import type { ToolRouter } from '../tool-router.js';
+import type { SidecarReverseHandler } from './types.js';
+export interface ReverseToolDeps {
+    toolRouter: ToolRouter;
+    onBlocked?: (info: {
+        command: string;
+        rules: string[];
+    }) => void;
+    /**
+     * 项目模式：按 chatId 解析项目根（绝对路径），无绑定/已删除返回 null。
+     * main.ts 注入 LocalBackendRouter.resolveChatProject 的适配；未注入时
+     * 项目围栏不生效（CLI/test 场景）。
+     */
+    resolveProjectRoot?: (chatId: string) => string | null;
+    /**
+     * 额外放行的只读根（会话附件目录等）。写入仍只受 projectRoot 围栏约束，
+     * 这里只放宽 local_read_file 的读取范围。
+     */
+    resolveAdditionalReadRoots?: (chatId: string) => string[];
+}
+export declare function createToolInvokeHandler(deps: ReverseToolDeps): SidecarReverseHandler;

package/dist/sidecar/reverse-tools.js

@@ -0,0 +1,106 @@
+/**
+ * A4 reverse channel: serve the sidecar-hosted CoreLoop's `tool.invoke`
+ * requests by executing the tool in this process (shell / files / MCP live
+ * in Electron, not in Python).
+ *
+ * Hard-gates critical shell commands — the TS loop only annotates them, but
+ * on the CoreLoop path the framework's blocking semantics apply.
+ */
+import { classifyShellCommand } from './safety-patterns.js';
+import { compactToolResultJson } from '../local-backend/context-compactor.js';
+import { normalizeToolPolicy } from '../local-backend/agent-capability.js';
+/**
+ * 模型上下文硬顶：喂给 sidecar 的工具结果必须待在框架逐项 10k token 断言线
+ * 以下（2026-08-28 E2E 录制实锤：local_exec_shell 对 node_modules 跑
+ * `grep -R` 返回了 ~68k token——终端采集的 256KiB 上限是 UI 防爆兜底，
+ * 不是模型预算）。完整输出用户始终能在可见终端里看到，这里只截断喂给
+ * 模型的那份。复用 context-compactor 的既有策略（8000 字符总量 /
+ * 2000 单字段，最坏情况纯 CJK 约 4.8k token）。
+ */
+function capResultForModelContext(out) {
+    const json = JSON.stringify(out);
+    if (json.length <= 8000)
+        return out;
+    return JSON.parse(compactToolResultJson(json));
+}
+export function createToolInvokeHandler(deps) {
+    return async (params) => {
+        const p = (params ?? {});
+        const name = typeof p.name === 'string' ? p.name : '';
+        const toolArgs = p.arguments ?? {};
+        if (!name) {
+            return { success: false, error: 'missing tool name', needsFollowup: false };
+        }
+        // Plan mode is enforced at the execution layer too, not just by tool
+        // advertisement — a pseudo-recovered call could name a write tool that
+        // was never advertised.
+        if (p.context?.mode === 'plan') {
+            const schema = deps.toolRouter.listSchemas().find((s) => s.name === name);
+            if (schema && schema.mode !== 'read') {
+                return {
+                    success: false,
+                    error: `blocked by plan mode: ${name} is a write tool`,
+                    needsFollowup: false,
+                };
+            }
+        }
+        // 项目模式硬围栏（W4-2 接线补齐）：CoreLoop 路径此前把 projectRoot 丢
+        // 了——toolContext 只带 mode，ToolRouter 的项目沙箱（cwd 收口 + 文件
+        // 路径围栏）在 sidecar 驱动的回合里形同虚设。这里从 chat 绑定解析
+        // 项目根并随调用上下文下发，与旧 TS 循环语义对齐。
+        // 4.6b：调用方显式带 workspaceRoot（worktree 任务的隔离工作区）时
+        // 优先采用——围栏根收窄到 worktree，任务摸不到主检出。
+        const projectRoot = typeof p.context?.workspaceRoot === 'string' && p.context.workspaceRoot
+            ? p.context.workspaceRoot
+            : p.context?.chatId
+                ? (deps.resolveProjectRoot?.(p.context.chatId) ?? null)
+                : null;
+        const additionalReadRoots = p.context?.chatId
+            ? (deps.resolveAdditionalReadRoots?.(p.context.chatId) ?? [])
+            : [];
+        if (name === 'local_exec_shell') {
+            const classification = classifyShellCommand(String(toolArgs.command ?? ''));
+            if (classification.severity === 'critical') {
+                deps.onBlocked?.({
+                    command: String(toolArgs.command ?? '').slice(0, 200),
+                    rules: classification.matchedRules,
+                });
+                return {
+                    success: false,
+                    error: `blocked by shell safety policy (critical): ${classification.matchedRules.join(', ')}`,
+                    needsFollowup: false,
+                };
+            }
+        }
+        // 智能体工具策略随 toolContext 下发（router 按本轮生效的智能体解析），
+        // 未配置策略时不进调用上下文——那种回合的上下文与旧版逐字段一致。
+        const normalizedPolicy = p.context?.toolPolicy
+            ? normalizeToolPolicy(p.context.toolPolicy)
+            : null;
+        const toolPolicy = normalizedPolicy && normalizedPolicy.mode !== 'all' ? normalizedPolicy : null;
+        const execContext = projectRoot || additionalReadRoots.length > 0 || p.context?.chatId || toolPolicy
+            ? {
+                projectRoot,
+                chatId: p.context?.chatId,
+                // 4.6a：chatId 随上下文透传——task_run/status/result 与
+                // worktree_* 工具按它把任务绑定到来源对话。
+                ...(toolPolicy ? { toolPolicy } : {}),
+                ...(additionalReadRoots.length > 0 ? { additionalReadRoots } : {}),
+            }
+            : undefined;
+        try {
+            const out = await deps.toolRouter.execute({ name, arguments: toolArgs }, execContext);
+            if (out && typeof out === 'object' && 'success' in out) {
+                return capResultForModelContext(out);
+            }
+            return capResultForModelContext({ success: true, data: { value: out } });
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error ? err.message : String(err),
+                needsFollowup: true,
+            };
+        }
+    };
+}

package/dist/sidecar/safety-patterns.d.ts

@@ -0,0 +1,41 @@
+export interface CommandSafetyConfig {
+    disabledPatternIds?: string[];
+    hiddenPatternIds?: string[];
+    customPatterns?: Array<{
+        id: string;
+        label: string;
+        pattern: string;
+        category: string;
+        enabled: boolean;
+    }>;
+}
+export type PatternSeverity = 'critical' | 'warning';
+export type PatternPlatform = 'all' | 'unix' | 'windows';
+export interface SafetyPatternDef {
+    id: string;
+    label: string;
+    description: string;
+    pattern: string;
+    category: string;
+    severity: PatternSeverity;
+    platform: PatternPlatform;
+}
+export declare const SAFETY_CATEGORIES: Record<string, string>;
+export declare const BUILTIN_PATTERNS: SafetyPatternDef[];
+/**
+ * 根据用户配置计算当前生效的正则模式列表
+ */
+export declare function getActivePatterns(config?: CommandSafetyConfig | null): RegExp[];
+/**
+ * 按分类分组返回内置模式
+ */
+export declare function getPatternsByCategory(): Record<string, SafetyPatternDef[]>;
+/**
+ * 默认空配置（所有内置模式均启用，无自定义模式）
+ */
+export declare const DEFAULT_COMMAND_SAFETY_CONFIG: CommandSafetyConfig;
+export interface ShellCommandClassification {
+    severity: 'safe' | PatternSeverity;
+    matchedRules: string[];
+}
+export declare function classifyShellCommand(command: string, config?: CommandSafetyConfig | null): ShellCommandClassification;

package/dist/sidecar/safety-patterns.js

@@ -0,0 +1,157 @@
+// ─── Categories ──────────────────────────────────────────────────────
+export const SAFETY_CATEGORIES = {
+    file_ops: '文件操作',
+    system: '系统管理',
+    process: '进程管理',
+    network: '网络安全',
+    package: '包管理',
+    vcs: '版本控制',
+    container: '容器管理',
+    file_write: '文件写入',
+    windows: 'Windows / PowerShell',
+};
+// ─── Built-in patterns ──────────────────────────────────────────────
+// Merged from local-actions.ts (web, severity=warning) and
+// local-executor.ts (desktop, severity=critical).
+export const BUILTIN_PATTERNS = [
+    // ── file_ops ──
+    { id: 'rm', label: 'rm 删除', description: '匹配 rm 命令', pattern: '\\brm\\s', category: 'file_ops', severity: 'warning', platform: 'unix' },
+    { id: 'rm_end', label: 'rm（行尾）', description: '匹配行尾的 rm', pattern: '\\brm$', category: 'file_ops', severity: 'warning', platform: 'unix' },
+    { id: 'rm_rf_root', label: 'rm -rf /', description: '递归删除根目录', pattern: 'rm\\s+-rf\\s+\\/(?:\\s|$)', category: 'file_ops', severity: 'critical', platform: 'unix' },
+    { id: 'rmdir', label: 'rmdir 删除目录', description: '匹配 rmdir 命令', pattern: '\\brmdir\\s', category: 'file_ops', severity: 'warning', platform: 'unix' },
+    { id: 'mv', label: 'mv 移动/重命名', description: '匹配 mv 命令', pattern: '\\bmv\\s.*\\/', category: 'file_ops', severity: 'warning', platform: 'unix' },
+    { id: 'shred', label: 'shred 安全擦除', description: '不可恢复地擦除文件', pattern: '\\bshred\\b', category: 'file_ops', severity: 'warning', platform: 'unix' },
+    { id: 'truncate', label: 'truncate 截断文件', description: '截断文件内容', pattern: '\\btruncate\\b', category: 'file_ops', severity: 'warning', platform: 'unix' },
+    // ── system ──
+    { id: 'sudo', label: 'sudo 提权', description: '以超级用户权限执行', pattern: '\\bsudo\\s', category: 'system', severity: 'critical', platform: 'unix' },
+    { id: 'mkfs', label: 'mkfs 格式化磁盘', description: '创建文件系统（格式化）', pattern: '\\bmkfs\\b', category: 'system', severity: 'critical', platform: 'unix' },
+    { id: 'dd', label: 'dd 磁盘写入', description: '底层磁盘数据复制', pattern: '\\bdd\\s', category: 'system', severity: 'warning', platform: 'unix' },
+    { id: 'dd_if', label: 'dd if= 磁盘镜像', description: '使用 dd if= 读写磁盘', pattern: '\\bdd\\s+if=', category: 'system', severity: 'critical', platform: 'unix' },
+    { id: 'format', label: 'format 格式化', description: '格式化磁盘', pattern: '\\bformat\\b', category: 'system', severity: 'warning', platform: 'all' },
+    { id: 'shutdown', label: 'shutdown 关机', description: '关闭系统', pattern: '\\bshutdown\\b', category: 'system', severity: 'warning', platform: 'all' },
+    { id: 'reboot', label: 'reboot 重启', description: '重启系统', pattern: '\\breboot\\b', category: 'system', severity: 'warning', platform: 'all' },
+    { id: 'chmod', label: 'chmod 修改权限', description: '修改文件权限', pattern: '\\bchmod\\s', category: 'system', severity: 'warning', platform: 'unix' },
+    { id: 'chmod_777_root', label: 'chmod -R 777 /', description: '递归赋予根目录所有权限', pattern: 'chmod\\s+-R\\s+777\\s+\\/(?:\\s|$)', category: 'system', severity: 'critical', platform: 'unix' },
+    { id: 'chown', label: 'chown 修改所有者', description: '修改文件所有者', pattern: '\\bchown\\s', category: 'system', severity: 'warning', platform: 'unix' },
+    { id: 'fork_bomb', label: 'Fork Bomb', description: ':(){ :|:& };: fork 炸弹', pattern: ':\\(\\)\\s*\\{\\s*:\\|:&\\s*\\};:', category: 'system', severity: 'critical', platform: 'unix' },
+    // ── process ──
+    { id: 'kill', label: 'kill 终止进程', description: '向进程发送信号', pattern: '\\bkill\\s', category: 'process', severity: 'warning', platform: 'unix' },
+    { id: 'killall', label: 'killall 终止所有', description: '按名称终止进程', pattern: '\\bkillall\\s', category: 'process', severity: 'warning', platform: 'unix' },
+    // ── network ──
+    { id: 'curl_pipe_sh', label: 'curl | sh', description: '从网络下载并直接执行脚本', pattern: '\\bcurl\\s.*\\|\\s*(sh|bash|zsh)', category: 'network', severity: 'warning', platform: 'unix' },
+    { id: 'wget_pipe_sh', label: 'wget | sh', description: '从网络下载并直接执行脚本', pattern: '\\bwget\\s.*\\|\\s*(sh|bash|zsh)', category: 'network', severity: 'warning', platform: 'unix' },
+    { id: 'redirect_dev', label: '重定向到 /dev/', description: '向设备文件写入数据', pattern: '>\\s*\\/dev\\/', category: 'network', severity: 'warning', platform: 'unix' },
+    // ── package ──
+    { id: 'npm_publish', label: 'npm publish', description: '发布/取消发布 npm 包', pattern: '\\bnpm\\s+(publish|unpublish)', category: 'package', severity: 'warning', platform: 'all' },
+    { id: 'pip_install', label: 'pip install', description: '安装 Python 包', pattern: '\\bpip\\s+install\\b', category: 'package', severity: 'warning', platform: 'all' },
+    { id: 'npm_install', label: 'npm install', description: '安装 npm 包', pattern: '\\bnpm\\s+install\\b', category: 'package', severity: 'warning', platform: 'all' },
+    { id: 'yarn_add', label: 'yarn add', description: '添加 yarn 依赖', pattern: '\\byarn\\s+add\\b', category: 'package', severity: 'warning', platform: 'all' },
+    { id: 'pnpm_add', label: 'pnpm add', description: '添加 pnpm 依赖', pattern: '\\bpnpm\\s+add\\b', category: 'package', severity: 'warning', platform: 'all' },
+    { id: 'uv_add', label: 'uv add', description: '添加 uv 依赖', pattern: '\\buv\\s+add\\b', category: 'package', severity: 'warning', platform: 'all' },
+    { id: 'apt_install', label: 'apt install/remove', description: '系统包管理器操作', pattern: '\\bapt(-get)?\\s+(install|remove|purge)', category: 'package', severity: 'warning', platform: 'unix' },
+    { id: 'brew_install', label: 'brew install/uninstall', description: 'Homebrew 包管理器操作', pattern: '\\bbrew\\s+(install|uninstall|remove)', category: 'package', severity: 'warning', platform: 'unix' },
+    // ── vcs ──
+    { id: 'git_push', label: 'git push / reset --hard', description: 'Git 远程推送或硬重置', pattern: '\\bgit\\s+(push|reset\\s+--hard|clean\\s+-fd)', category: 'vcs', severity: 'warning', platform: 'all' },
+    // ── container ──
+    { id: 'docker_rm', label: 'docker rm/rmi/prune', description: '删除容器/镜像或清理系统', pattern: '\\bdocker\\s+(rm|rmi|system\\s+prune)', category: 'container', severity: 'warning', platform: 'all' },
+    // ── file_write ──
+    { id: 'redirect_overwrite', label: '> / >> 重定向写入', description: '文件重定向覆盖或追加', pattern: '\\b(>\\s|>>)\\s*[^|]', category: 'file_write', severity: 'warning', platform: 'all' },
+    { id: 'tee', label: 'tee 写入文件', description: '将输出写入文件', pattern: '\\btee\\s', category: 'file_write', severity: 'warning', platform: 'unix' },
+    { id: 'sed_inplace', label: 'sed -i 原地修改', description: '直接修改文件内容', pattern: '\\bsed\\s+-i', category: 'file_write', severity: 'warning', platform: 'unix' },
+    // ── windows ──
+    { id: 'win_del', label: 'del 删除', description: 'Windows 删除命令', pattern: '\\bdel\\s', category: 'windows', severity: 'warning', platform: 'windows' },
+    { id: 'win_rd', label: 'rd 删除目录', description: 'Windows 删除目录', pattern: '\\brd\\s', category: 'windows', severity: 'warning', platform: 'windows' },
+    { id: 'win_rd_end', label: 'rd（行尾）', description: '匹配行尾的 rd', pattern: '\\brd$', category: 'windows', severity: 'warning', platform: 'windows' },
+    { id: 'win_rdel', label: 'rdel', description: 'Windows rdel 命令', pattern: '\\brdel\\b', category: 'windows', severity: 'warning', platform: 'windows' },
+    { id: 'win_del_force', label: 'del /f /s /q 强制删除', description: '强制递归删除整个驱动器', pattern: '\\bdel\\s+\\/f\\s+\\/s\\s+\\/q\\s+[a-z]:\\\\', category: 'windows', severity: 'critical', platform: 'windows' },
+    { id: 'win_rd_force', label: 'rd /s /q 强制删除目录', description: '强制递归删除整个驱动器目录', pattern: '\\brd\\s+\\/s\\s+\\/q\\s+[a-z]:\\\\', category: 'windows', severity: 'critical', platform: 'windows' },
+    { id: 'win_remove_item', label: 'Remove-Item', description: 'PowerShell 删除项', pattern: '\\bRemove-Item\\b', category: 'windows', severity: 'warning', platform: 'windows' },
+    { id: 'win_stop_process', label: 'Stop-Process', description: 'PowerShell 终止进程', pattern: '\\bStop-Process\\b', category: 'windows', severity: 'warning', platform: 'windows' },
+    { id: 'win_stop_computer', label: 'Stop-Computer', description: 'PowerShell 关机', pattern: '\\bStop-Computer\\b', category: 'windows', severity: 'warning', platform: 'windows' },
+    { id: 'win_restart_computer', label: 'Restart-Computer', description: 'PowerShell 重启', pattern: '\\bRestart-Computer\\b', category: 'windows', severity: 'warning', platform: 'windows' },
+    { id: 'win_set_execution_policy', label: 'Set-ExecutionPolicy', description: '修改脚本执行策略', pattern: '\\bSet-ExecutionPolicy\\b', category: 'windows', severity: 'warning', platform: 'windows' },
+    { id: 'win_format_volume', label: 'Format-Volume', description: 'PowerShell 格式化卷', pattern: '\\bFormat-Volume\\b', category: 'windows', severity: 'warning', platform: 'windows' },
+    { id: 'win_clear_disk', label: 'Clear-Disk', description: 'PowerShell 清除磁盘', pattern: '\\bClear-Disk\\b', category: 'windows', severity: 'warning', platform: 'windows' },
+    { id: 'win_wsl', label: 'wsl 子系统', description: '调用 WSL 子系统', pattern: '\\bwsl\\s', category: 'windows', severity: 'warning', platform: 'windows' },
+    { id: 'win_powershell_cmd', label: 'powershell -Command', description: '通过 PowerShell 执行命令', pattern: '\\bpowershell\\s.*-[Cc]ommand', category: 'windows', severity: 'warning', platform: 'windows' },
+    { id: 'win_pwsh', label: 'pwsh', description: 'PowerShell Core', pattern: '\\bpwsh\\s', category: 'windows', severity: 'warning', platform: 'windows' },
+    { id: 'win_cmd_c', label: 'cmd /c', description: 'CMD 执行命令', pattern: '\\bcmd\\s*\\/c\\b', category: 'windows', severity: 'warning', platform: 'windows' },
+    { id: 'win_reg', label: 'reg delete/add', description: '注册表操作', pattern: '\\breg\\s+(delete|add)\\b', category: 'windows', severity: 'warning', platform: 'windows' },
+    { id: 'win_net', label: 'net user/stop/start', description: '网络和用户管理', pattern: '\\bnet\\s+(user|stop|start)\\b', category: 'windows', severity: 'warning', platform: 'windows' },
+    { id: 'win_sc', label: 'sc delete/stop/config', description: '服务管理', pattern: '\\bsc\\s+(delete|stop|config)\\b', category: 'windows', severity: 'warning', platform: 'windows' },
+    { id: 'win_diskpart', label: 'diskpart', description: '磁盘分区工具', pattern: '\\bdiskpart\\b', category: 'windows', severity: 'warning', platform: 'windows' },
+    { id: 'win_bcdedit', label: 'bcdedit', description: '启动配置编辑', pattern: '\\bbcdedit\\b', category: 'windows', severity: 'warning', platform: 'windows' },
+    { id: 'win_sfc', label: 'sfc', description: '系统文件检查器', pattern: '\\bsfc\\b', category: 'windows', severity: 'warning', platform: 'windows' },
+    { id: 'win_dism', label: 'dism', description: '部署映像服务和管理', pattern: '\\bdism\\b', category: 'windows', severity: 'warning', platform: 'windows' },
+    // 只匹配"format <盘符>:"形式的磁盘格式化（含 format.com），避免误伤
+    // PowerShell 的 Format-List / Format-Table 等格式化输出 cmdlet
+    // （Format-Volume 由上面的 win_format_volume 单独覆盖）。
+    { id: 'win_format_cmd', label: 'format（Windows）', description: 'Windows 格式化磁盘命令', pattern: '\\bformat(\\.com)?\\s+[a-z]:', category: 'windows', severity: 'critical', platform: 'windows' },
+];
+// ─── Helpers ─────────────────────────────────────────────────────────
+/**
+ * 根据用户配置计算当前生效的正则模式列表
+ */
+export function getActivePatterns(config) {
+    const disabled = new Set(config?.disabledPatternIds ?? []);
+    const patterns = BUILTIN_PATTERNS
+        .filter(p => !disabled.has(p.id))
+        .map(p => {
+        const flags = p.platform === 'windows' ? 'i' : undefined;
+        return new RegExp(p.pattern, flags);
+    });
+    if (config?.customPatterns) {
+        for (const cp of config.customPatterns) {
+            if (!cp.enabled)
+                continue;
+            try {
+                patterns.push(new RegExp(cp.pattern));
+            }
+            catch {
+                // skip invalid regex
+            }
+        }
+    }
+    return patterns;
+}
+/**
+ * 按分类分组返回内置模式
+ */
+export function getPatternsByCategory() {
+    const grouped = {};
+    for (const p of BUILTIN_PATTERNS) {
+        if (!grouped[p.category])
+            grouped[p.category] = [];
+        grouped[p.category].push(p);
+    }
+    return grouped;
+}
+/**
+ * 默认空配置（所有内置模式均启用，无自定义模式）
+ */
+export const DEFAULT_COMMAND_SAFETY_CONFIG = {
+    disabledPatternIds: [],
+    hiddenPatternIds: [],
+    customPatterns: [],
+};
+export function classifyShellCommand(command, config) {
+    const normalized = command.trim();
+    if (!normalized) {
+        return { severity: 'safe', matchedRules: [] };
+    }
+    const disabled = new Set(config?.disabledPatternIds ?? []);
+    const matches = BUILTIN_PATTERNS
+        .filter(rule => !disabled.has(rule.id))
+        .filter(rule => {
+        const flags = rule.platform === 'windows' ? 'i' : undefined;
+        return new RegExp(rule.pattern, flags).test(normalized);
+    });
+    if (!matches.length) {
+        return { severity: 'safe', matchedRules: [] };
+    }
+    const severity = matches.some(item => item.severity === 'critical') ? 'critical' : 'warning';
+    return {
+        severity,
+        matchedRules: matches.map(item => item.id),
+    };
+}

package/dist/sidecar/storage-path.d.ts

@@ -0,0 +1,14 @@
+/**
+ *  1. `STEERABLE_SIDECAR_STORAGE_PATH` 显式覆盖（dev 脚本与测试的逃生门——
+ *     with-flavor.mjs 会给开发实例注入 sessions-dev-<flavor>.db）；
+ *  2. `DEEPPATH_USER_DATA_DIR`（BS 模式/只读 HOME 场景）优先于 `~/.steerable`：
+ *     sidecar 库落到 `<userDataDir>/sidecar/sessions-<flavor>.db`，保证 HOME
+ *     不可写时 BS server 仍能启动 sidecar；
+ *  3. 按 flavor 隔离默认路径：`<flavor>` 非 generic 时 → sessions-<flavor>.db，
+ *     generic → sessions.db（历史默认，保留存量数据）。
+ *
+ * 写锁是跨进程互斥的（Windows 命名 mutex / POSIX flock），两个宿主共用同
+ * 一库时后到者 boot 失败并无限重启。flavor 的 userData 目录本已隔离，
+ * sidecar 库同样隔离后两个 flavor 才能真正同机共存。
+ */
+export declare function resolveSidecarStoragePath(): string;

package/dist/sidecar/storage-path.js

@@ -0,0 +1,35 @@
+/**
+ * Sidecar 持久化库（sessions/traces/history）路径解析。
+ *
+ * 单独成模块而不是留在 boot.ts：boot.ts 会拉起 localStore 单例（进程内
+ * 独占写锁），只想读 history 的调用方（如后台任务过程投影）不该为一个
+ * 路径付这个代价。
+ */
+import path from 'node:path';
+import { homedir } from 'node:os';
+import { getBrand } from '../brand.js';
+/**
+ *  1. `STEERABLE_SIDECAR_STORAGE_PATH` 显式覆盖（dev 脚本与测试的逃生门——
+ *     with-flavor.mjs 会给开发实例注入 sessions-dev-<flavor>.db）；
+ *  2. `DEEPPATH_USER_DATA_DIR`（BS 模式/只读 HOME 场景）优先于 `~/.steerable`：
+ *     sidecar 库落到 `<userDataDir>/sidecar/sessions-<flavor>.db`，保证 HOME
+ *     不可写时 BS server 仍能启动 sidecar；
+ *  3. 按 flavor 隔离默认路径：`<flavor>` 非 generic 时 → sessions-<flavor>.db，
+ *     generic → sessions.db（历史默认，保留存量数据）。
+ *
+ * 写锁是跨进程互斥的（Windows 命名 mutex / POSIX flock），两个宿主共用同
+ * 一库时后到者 boot 失败并无限重启。flavor 的 userData 目录本已隔离，
+ * sidecar 库同样隔离后两个 flavor 才能真正同机共存。
+ */
+export function resolveSidecarStoragePath() {
+    const override = process.env.STEERABLE_SIDECAR_STORAGE_PATH;
+    if (override)
+        return override;
+    // 按 flavor 派生（开放字符串，0.3g）——不含任何产品分支。
+    const flavor = getBrand().flavor;
+    const name = flavor === 'generic' ? 'sessions.db' : `sessions-${flavor}.db`;
+    const userDataDir = process.env.DEEPPATH_USER_DATA_DIR;
+    if (userDataDir)
+        return path.join(userDataDir, 'sidecar', name);
+    return path.join(homedir(), '.steerable', name);
+}