@dsh-workbench/shared 1.1.12 → 1.1.14-beta.0

package/src/host/__tests__/plugin-helpers.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { defineUnitHostPlugin, type UnitHostContextLike } from '../unit-plugin.js';
+import { recordOf, textOf } from '../payload.js';
+import { writeApprovalOf } from '../tool-approval.js';
+import type { UnitModuleFace } from '../unit-face.js';
+
+const face: UnitModuleFace = {
+  unit: 'demo',
+  mount: () => ({ routes: {}, registerTools: () => [] }),
+};
+
+describe('recordOf / textOf', () => {
+  it('非对象回空对象；字符串 trim；别的算空串', () => {
+    expect(recordOf(null)).toEqual({});
+    expect(recordOf('x')).toEqual({});
+    expect(recordOf({ a: 1 })).toEqual({ a: 1 });
+    expect(textOf('  hi  ')).toBe('hi');
+    expect(textOf(3)).toBe('');
+    expect(textOf(undefined)).toBe('');
+  });
+});
+
+describe('writeApprovalOf', () => {
+  const approval = writeApprovalOf({
+    tools: ['demo_write'],
+    reason: '会写一条',
+    question: { zh: '写吗？', en: 'Write?' },
+    fallback: { zh: '只写模块自己的文件', en: 'Writes the module’s own file' },
+    detail: { zh: '写 1 条', en: 'Write 1' },
+  });
+
+  it('点名的写工具：ask + 明细', () => {
+    expect(approval.needsApproval({ name: 'demo_write' })).toMatchObject({ kind: 'ask' });
+    expect(approval.approvalDetail({ name: 'demo_write' })).toEqual({ zh: '写 1 条', en: 'Write 1' });
+  });
+
+  it('别的工具：read、没有明细', () => {
+    expect(approval.needsApproval({ name: 'demo_read' })).toEqual({ kind: 'read' });
+    expect(approval.needsApproval({})).toEqual({ kind: 'read' });
+    expect(approval.approvalDetail({ name: 'demo_read' })).toBeUndefined();
+  });
+});
+
+describe('defineUnitHostPlugin', () => {
+  it('导出 name / inject；apply 把面注册进 workbenchUnits 并交回清理函数', () => {
+    const plugin = defineUnitHostPlugin({ name: '@demo/module', unit: 'demo', face });
+    expect(plugin.name).toBe('@demo/module');
+    expect(plugin.inject).toEqual(['workbenchUnits']);
+    const dispose = vi.fn();
+    const register = vi.fn(() => dispose);
+    const effect = vi.fn((run: () => void | (() => void)) => {
+      run();
+      return () => {};
+    });
+    plugin.apply({ get: () => ({ register }), effect } as unknown as UnitHostContextLike);
+    expect(register).toHaveBeenCalledWith(face);
+    expect(effect).toHaveBeenCalledWith(expect.any(Function), '@demo/module: 注册 demo');
+  });
+
+  it('外壳没给服务：warn 一声，不抛', () => {
+    const plugin = defineUnitHostPlugin({ name: '@demo/module', unit: 'demo', face });
+    const warn = vi.fn();
+    const ctx = { get: () => undefined, effect: () => () => {}, logger: { warn } } as unknown as UnitHostContextLike;
+    expect(() => plugin.apply(ctx)).not.toThrow();
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('workbenchUnits'));
+  });
+});

package/src/host/__tests__/runtime-layout.test.ts

@@ -1,3 +1,4 @@
+import { join } from 'node:path';
 import { describe, expect, it } from 'vitest';
 import { runtimeLayoutOf, runtimeRootOf } from '../paths.js';
 
@@ -6,9 +7,9 @@ describe('运行时根的算法（这里不认识任何具体运行时）', () =
     const layout = runtimeLayoutOf('demo-runtime');
 
     expect(layout.root).toBe(runtimeRootOf('demo-runtime'));
-    expect(layout.root.endsWith('/workbench/demo-runtime')).toBe(true);
-    expect(layout.vendorPluginsDir).toBe(`${layout.root}/plugins-npm/node_modules`);
-    expect(layout.libsPrefix).toBe(`${layout.root}/libs`);
-    expect(layout.npmCacheDir).toBe(`${layout.root}/npm-cache`);
+    expect(layout.root.endsWith(join('workbench', 'demo-runtime'))).toBe(true);
+    expect(layout.vendorPluginsDir).toBe(join(layout.root, 'plugins-npm', 'node_modules'));
+    expect(layout.libsPrefix).toBe(join(layout.root, 'libs'));
+    expect(layout.npmCacheDir).toBe(join(layout.root, 'npm-cache'));
   });
 });

package/src/host/__tests__/shell-text.test.ts

@@ -1,6 +1,6 @@
 import { execFileSync } from 'node:child_process';
 import { describe, expect, it } from 'vitest';
-import { quoteShellArg, quoteShellArgFor, tailLines } from '../shell-text.js';
+import { quoteShellArg, quoteShellArgFor, shellKindOf, tailLines } from '../shell-text.js';
 
 function shellSees(value: string): string {
   return execFileSync('/bin/sh', ['-c', `printf '%s' ${quoteShellArg(value)}`], {
@@ -8,7 +8,7 @@ function shellSees(value: string): string {
   });
 }
 
-describe('quoteShellArg', () => {
+describe.skipIf(process.platform === 'win32')('quoteShellArg（POSIX /bin/sh）', () => {
   it('普通值原样往返', () => {
     expect(shellSees('example-monorepo')).toBe('example-monorepo');
   });
@@ -45,15 +45,40 @@ describe('tailLines', () => {
 
 
 describe('quoteShellArgFor', () => {
-  it('win32 用双引号，路径里的空格原样保留', () => {
-    expect(quoteShellArgFor('C:\\Program Files\\dsh\\x.cjs', 'win32')).toBe('"C:\\Program Files\\dsh\\x.cjs"');
+  it('★ win32 按 pwsh 的字面量走：单引号，路径里的空格与反斜杠都原样', () => {
+    expect(quoteShellArgFor('C:\\Program Files\\dsh\\x.cjs', 'win32')).toBe("'C:\\Program Files\\dsh\\x.cjs'");
   });
 
-  it('win32 里值自身的双引号被转义', () => {
-    expect(quoteShellArgFor('a"b', 'win32')).toBe('"a\\"b"');
+  it('★ pwsh 里值自身的单引号按双写逃逸（不是 POSIX 那套反斜杠）', () => {
+    expect(quoteShellArgFor("it's", 'win32')).toBe("'it''s'");
   });
 
-  it('POSIX 仍用单引号', () => {
+  it('★ pwsh 里 $ 与双引号不再被当成语法（单引号内是字面量）', () => {
+    expect(quoteShellArgFor('a$b"c', 'win32')).toBe(`'a$b"c'`);
+  });
+
+  it('POSIX 仍用单引号加反斜杠逃逸', () => {
     expect(quoteShellArgFor("it's", 'darwin')).toBe("'it'\\''s'");
   });
 });
+
+describe.skipIf(process.platform !== 'win32')('quoteShellArg（Windows pwsh）', () => {
+  it('经真 pwsh 解析后原样往返', { timeout: 30000 }, () => {
+    for (const raw of ["it's", '$HOME', 'a;b', 'a && b']) {
+      const out = execFileSync(
+        'pwsh',
+        ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', `[Console]::Out.Write(${quoteShellArg(raw)})`],
+        { encoding: 'utf8' },
+      );
+      expect(out, raw).toBe(raw);
+    }
+  });
+});
+
+describe('shellKindOf', () => {
+  it('win32 是 pwsh，其余是 POSIX', () => {
+    expect(shellKindOf('win32')).toBe('pwsh');
+    expect(shellKindOf('darwin')).toBe('posix');
+    expect(shellKindOf('linux')).toBe('posix');
+  });
+});

package/src/host/__tests__/shell.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { DshShell, DshShellExecution } from '../../api/dsh.js';
+import { runShell } from '../shell.js';
+
+function hangingShell(): DshShell {
+  return {
+    resolve: (request) => request,
+    execute: () => new Promise<DshShellExecution>(() => {}),
+  };
+}
+
+function replyingShell(exitCode: number, timedOut = false): DshShell {
+  return {
+    resolve: (request) => request,
+    execute: async () => ({
+      result: async () => ({
+        exitCode,
+        timedOut,
+        aborted: false,
+        stdout: { text: 'v24.21.0\n', truncated: false },
+        stderr: { text: '', truncated: false },
+      }),
+    }),
+  };
+}
+
+describe('runShell', () => {
+  it('★ 宿主一直不交结果 → 到点自己收尾，不把调用方挂住', async () => {
+    vi.useFakeTimers();
+    try {
+      const pending = runShell(hangingShell(), 'node --version', { timeoutMs: 10_000 });
+      await vi.advanceTimersByTimeAsync(11_000);
+      const result = await pending;
+
+      expect(result.stalled).toBe(true);
+      expect(result.timedOut).toBe(true);
+      expect(result.exitCode).toBeNull();
+      expect(result.stdout).toBe('');
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('★ 宿主准时交结果 → stalled=false，退出码与输出原样', async () => {
+    const result = await runShell(replyingShell(0), 'node --version');
+
+    expect(result.stalled).toBe(false);
+    expect(result.timedOut).toBe(false);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toBe('v24.21.0\n');
+  });
+
+  it('★ 宿主自己报超时 → timedOut=true，但不算 stalled', async () => {
+    const result = await runShell(replyingShell(0, true), 'node --version');
+
+    expect(result.timedOut).toBe(true);
+    expect(result.stalled).toBe(false);
+  });
+
+  it('★ env 走 resolve 的覆盖字段，不拼进命令行的 shell 语法', async () => {
+    const seen: Array<Record<string, unknown>> = [];
+    const shell: DshShell = {
+      resolve: (request) => {
+        seen.push(request as unknown as Record<string, unknown>);
+        return request;
+      },
+      execute: async () => ({
+        result: async () => ({
+          exitCode: 0,
+          timedOut: false,
+          aborted: false,
+          stdout: { text: '', truncated: false },
+          stderr: { text: '', truncated: false },
+        }),
+      }),
+    };
+
+    await runShell(shell, 'node --version', { env: { OPENCLI_WINDOW: 'background' } });
+
+    expect(seen[0]?.command).toBe('node --version');
+    expect(seen[0]?.env).toEqual({ OPENCLI_WINDOW: 'background' });
+  });
+
+  it('★ 宿主自己抛错 → 照旧抛出去，不吞成 stalled', async () => {
+    const shell: DshShell = {
+      resolve: (request) => request,
+      execute: async () => {
+        throw new Error('spawn /bin/sh ENOENT');
+      },
+    };
+
+    await expect(runShell(shell, 'node --version')).rejects.toThrow('ENOENT');
+  });
+});

package/src/host/data-root.ts

@@ -1,15 +1,18 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
 export function dshHome(): string {
   const configured = process.env.DSH_HOME?.trim();
   if (configured !== undefined && configured !== '') return configured;
-  return `${process.env.HOME ?? ''}/.dsh`;
+  return join(homedir(), '.dsh');
 }
 
 export function workbenchRoot(): string {
   const configured = process.env.DSH_WORKBENCH_HOME?.trim();
   if (configured !== undefined && configured !== '') return configured;
-  return `${dshHome()}/workbench`;
+  return join(dshHome(), 'workbench');
 }
 
 export function workspacesRoot(): string {
-  return `${workbenchRoot()}/workspaces`;
+  return join(workbenchRoot(), 'workspaces');
 }

package/src/host/flow/__tests__/step.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+
+import type { FlowStepEvent } from '../types.js';
+import { longTaskStepOf } from '../step.js';
+
+const eventOf = (status: FlowStepEvent['status'], extra: Partial<FlowStepEvent> = {}): FlowStepEvent => ({
+  stepId: 'read',
+  title: '读目录',
+  status,
+  ...extra,
+});
+
+describe('longTaskStepOf：流程事件 → 长任务步骤的默认映射', () => {
+  it('running 记成 start，文字用 title', () => {
+    expect(longTaskStepOf(eventOf('running'))).toEqual({ kind: 'start', text: '读目录' });
+  });
+
+  it('ok 记成 succeed', () => {
+    expect(longTaskStepOf(eventOf('ok'))).toEqual({ kind: 'succeed', text: '读目录' });
+  });
+
+  it('skipped 记成 info', () => {
+    expect(longTaskStepOf(eventOf('skipped'))).toEqual({ kind: 'info', text: '读目录' });
+  });
+
+  it('failed 记成 fail', () => {
+    expect(longTaskStepOf(eventOf('failed'))).toEqual({ kind: 'fail', text: '读目录' });
+  });
+
+  it('needs-login 带 loginUrl', () => {
+    expect(longTaskStepOf(eventOf('needs-login', { loginUrl: 'https://example.com/login' }))).toEqual({
+      kind: 'info',
+      text: '读目录',
+      loginUrl: 'https://example.com/login',
+    });
+  });
+
+  it('message 盖过 title；没有 loginUrl 就不带那个键', () => {
+    const step = longTaskStepOf(eventOf('running', { message: '正在读' }));
+    expect(step).toEqual({ kind: 'start', text: '正在读' });
+    expect('loginUrl' in step).toBe(false);
+  });
+});

package/src/host/flow/step.ts

@@ -0,0 +1,21 @@
+import type { LongTaskStep } from '../../contract/long-task.js';
+import type { FlowStepEvent } from './types.js';
+
+/**
+ * 把流程的一步事件翻成长任务步骤流的默认一行。
+ * `running` → `start`、`ok` → `succeed`、`skipped` → `info`、`failed` → `fail`、
+ * `needs-login` → `info`（带 `loginUrl`）；文字取 `message ?? title`。
+ * 要改文案或过滤步骤，就在模块里自己映射 —— 这只是默认值。
+ * @param event `flow.run({ onStep })` 收到的那条事件。
+ * @returns 能直接交给长任务 `run({ onStep })` 的一行。
+ */
+export function longTaskStepOf(event: FlowStepEvent): LongTaskStep {
+  const text = event.message ?? event.title;
+  if (event.status === 'failed') return { kind: 'fail', text };
+  if (event.status === 'needs-login') {
+    return { kind: 'info', text, ...(event.loginUrl === undefined ? {} : { loginUrl: event.loginUrl }) };
+  }
+  if (event.status === 'ok') return { kind: 'succeed', text };
+  if (event.status === 'skipped') return { kind: 'info', text };
+  return { kind: 'start', text };
+}

package/src/host/host-kit.ts

@@ -1,26 +1,34 @@
+import type { HostSurface } from '../contract/protocol/platform.js';
 import type { EnvSupplyPort } from './port-types.js';
 import { createFlowHost, type FlowHost } from './flow/kit.js';
 import { sessionIdOf, sessionWorkspace } from './tool-kit.js';
 
 /**
- * 宿主 kit 的公共部分：flow、工具侧 session 读法、外部供给装法。
+ * 宿主 kit 的公共部分：flow、工具侧 session 读法、外部供给装法、宿主平台事实。
  */
 export interface HostKit {
   readonly flow: FlowHost;
   readonly sessionIdOf: typeof sessionIdOf;
   readonly sessionWorkspace: typeof sessionWorkspace;
   readonly libInstallCommand: EnvSupplyPort['libInstallCommand'];
+  readonly surface: HostSurface;
 }
 
 /**
  * 建一份宿主 kit；每个挂载点一份，没有模块级状态。
- * @returns flow / sessionIdOf / sessionWorkspace / libInstallCommand。
+ * @param parts.libInstallCommand 拼「装这个共用依赖」的那条命令。
+ * @param parts.surface 宿主平台事实；由组合根按 profile 与宿主进程算好再交进来。
+ * @returns flow / sessionIdOf / sessionWorkspace / libInstallCommand / surface。
  */
-export function createHostKit(parts: { readonly libInstallCommand: EnvSupplyPort['libInstallCommand'] }): HostKit {
+export function createHostKit(parts: {
+  readonly libInstallCommand: EnvSupplyPort['libInstallCommand'];
+  readonly surface: HostSurface;
+}): HostKit {
   return {
     flow: createFlowHost(),
     sessionIdOf,
     sessionWorkspace,
     libInstallCommand: parts.libInstallCommand,
+    surface: parts.surface,
   };
 }

package/src/host/install-failure.ts

@@ -4,7 +4,7 @@ import type { InstallFailure, InstallFailureKind } from '../contract/command.js'
 
 const TARGET_FLAGS = ['--prefix', '--cache', '--dir', '--store-dir'];
 
-const INSTALL_VERBS = /^\s*npm\s+(i|install|add)\b/;
+const INSTALL_VERBS = /^\s*(?:npm\s+(?:i|install|add)|pnpm\s+(?:add|install))\b/;
 
 const NPM_PATH = /^npm (?:error|ERR!) path (.+)$/m;
 

package/src/host/lib-install.ts

@@ -12,13 +12,15 @@ export function libInstallCommand(options: {
   readonly env?: NodeJS.ProcessEnv | undefined;
   readonly prefix: string;
   readonly cacheDir?: string | undefined;
+  readonly pnpm?: string | undefined;
 }): string {
   const { need, source, version } = options;
+  const pnpm = options.pnpm ?? process.env.DSH_WB_PNPM?.trim() ?? 'pnpm';
   const registry = npmRegistryOf(source, options.env ?? process.env);
   const spec = version ?? need.version ?? 'latest';
   const registryFlag = registry.ok ? ` --registry ${quoteShellArg(registry.value)}` : '';
-  const cacheFlag = options.cacheDir === undefined ? '' : ` --cache ${quoteShellArg(options.cacheDir)}`;
-  return `npm i --prefix ${quoteShellArg(options.prefix)} ${quoteShellArg(`${need.name}@${spec}`)}${registryFlag}${cacheFlag}`;
+  const storeFlag = options.cacheDir === undefined ? '' : ` --store-dir ${quoteShellArg(options.cacheDir)}`;
+  return `${pnpm} add --dir ${quoteShellArg(options.prefix)} ${quoteShellArg(`${need.name}@${spec}`)}${registryFlag}${storeFlag} --allow-build=${quoteShellArg(need.name)}`;
 }
 
 export function binInstallCommand(
@@ -52,5 +54,5 @@ export function binInstallCommand(
 }
 
 export function libUninstallCommand(options: { readonly need: LibNeed; readonly prefix: string }): string {
-  return `npm uninstall --prefix ${quoteShellArg(options.prefix)} ${quoteShellArg(options.need.name)}`;
+  return `pnpm remove --dir ${quoteShellArg(options.prefix)} ${quoteShellArg(options.need.name)}`;
 }

package/src/host/paths.ts

@@ -1,3 +1,4 @@
+import { join } from 'node:path';
 import { workbenchRoot } from './data-root.js';
 
 export interface RuntimeLayout {
@@ -11,20 +12,20 @@ export interface RuntimeLayout {
 }
 
 export function runtimeRootOf(id: string): string {
-  return `${workbenchRoot()}/${id}`;
+  return join(workbenchRoot(), id);
 }
 
 export function runtimeLayoutOf(id: string): RuntimeLayout {
   const root = runtimeRootOf(id);
-  const vendorPrefix = `${root}/plugins-npm`;
-  const libsPrefix = `${root}/libs`;
+  const vendorPrefix = join(root, 'plugins-npm');
+  const libsPrefix = join(root, 'libs');
   return {
     root,
-    home: `${root}/home`,
+    home: join(root, 'home'),
     vendorPrefix,
-    vendorPluginsDir: `${vendorPrefix}/node_modules`,
+    vendorPluginsDir: join(vendorPrefix, 'node_modules'),
     libsPrefix,
-    libsBinDir: `${libsPrefix}/node_modules/.bin`,
-    npmCacheDir: `${root}/npm-cache`,
+    libsBinDir: join(libsPrefix, 'node_modules', '.bin'),
+    npmCacheDir: join(root, 'npm-cache'),
   };
 }

package/src/host/payload.ts

@@ -0,0 +1,17 @@
+/**
+ * 把任意 payload 当对象看；不是对象就回空对象。
+ * @param value 任意入参。
+ * @returns 可按下标取值的安全对象。
+ */
+export function recordOf(value: unknown): Record<string, unknown> {
+  return typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : {};
+}
+
+/**
+ * 把任意 payload 当一段文字看：字符串就 trim，别的都算空串。
+ * @param value 任意入参。
+ * @returns 去掉首尾空白的字符串；不是字符串时是空串。
+ */
+export function textOf(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}

package/src/host/preflight.ts

@@ -1,7 +1,7 @@
 export type PreflightStepId = 'toolchain' | 'cli' | 'bridge' | 'runtime' | 'diy' | 'warm';
 export type PreflightStepStatus = 'pending' | 'running' | 'ok' | 'warn' | 'failed';
-export type PreflightFailure = 'permission' | 'network' | 'missing' | 'unknown';
-export type PreflightGuidance = 'install' | 'path' | 'shell';
+export type PreflightFailure = 'permission' | 'network' | 'missing' | 'host' | 'unknown';
+export type PreflightGuidance = 'install' | 'path' | 'shell' | 'host';
 export type PreflightBridgeIssue = string;
 
 export interface PreflightStep {
@@ -11,6 +11,7 @@ export interface PreflightStep {
   readonly detail?: string;
   readonly action?: string;
   readonly command?: string;
+  readonly log?: readonly string[];
 }
 
 export interface PreflightDiyGap {
@@ -29,4 +30,5 @@ export interface PreflightSnapshot {
   readonly bridgeIssues?: readonly PreflightBridgeIssue[];
   readonly diyGap?: PreflightDiyGap;
   readonly canWakeBrowser?: boolean;
+  readonly log?: readonly string[];
 }

package/src/host/shell-text.ts

@@ -1,12 +1,26 @@
 /**
- * 按目标平台把一个值裹成 shell 字面量：POSIX 用单引号，win32 用双引号（cmd 与 PowerShell 都认）。
+ * 一台机器上跑命令的那种 shell：POSIX 系（sh / bash / zsh），或 dsh 在 Windows 上用的 pwsh。
+ */
+export type ShellKind = 'posix' | 'pwsh';
+
+/**
+ * 按目标平台判 shell 种类：win32 是 pwsh（dsh 的 Windows 执行器就是 PowerShell），其余是 POSIX。
+ * @param platform - 目标平台，默认当前 `process.platform`。
+ * @returns `'pwsh'` 或 `'posix'`。
+ */
+export function shellKindOf(platform: NodeJS.Platform = process.platform): ShellKind {
+  return platform === 'win32' ? 'pwsh' : 'posix';
+}
+
+/**
+ * 按目标平台把一个值裹成 shell 字面量：POSIX 用单引号并按 `'\''` 逃逸，pwsh 也用单引号但按 `''` 逃逸。
  * @param value - 任意值；不是字符串的先 `String()`。
  * @param platform - 目标平台，默认当前 `process.platform`。
  * @returns 可安全拼进该平台 shell 命令的一段文本；含空格 / 元字符的值不会被当成语法。
  */
 export function quoteShellArgFor(value: unknown, platform: NodeJS.Platform = process.platform): string {
   const text = String(value);
-  if (platform === 'win32') return `"${text.replace(/"/g, '\\"')}"`;
+  if (shellKindOf(platform) === 'pwsh') return `'${text.replace(/'/g, "''")}'`;
   return `'${text.replace(/'/g, `'\\''`)}'`;
 }
 

package/src/host/shell.ts

@@ -8,16 +8,48 @@ export interface ShellResult {
   readonly stdout: string;
   readonly stderr: string;
   readonly truncated: boolean;
+  readonly stalled: boolean;
 }
 
 const DEFAULT_MAX_BYTES = 8 * 1024 * 1024;
 
+const GUARD_SLACK_MS = 1_000;
+
+function stalledResult(): ShellResult {
+  return {
+    exitCode: null,
+    timedOut: true,
+    aborted: false,
+    stdout: '',
+    stderr: '',
+    truncated: false,
+    stalled: true,
+  };
+}
+
+async function settleWithin<T>(work: Promise<T>, limitMs: number): Promise<T | null> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const guard = new Promise<null>((resolve) => {
+    timer = setTimeout(() => resolve(null), limitMs);
+  });
+  try {
+    return await Promise.race([work, guard]);
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+}
+
 export async function runShell(
   shell: DshShell,
   command: string,
-  options: { workdir?: string; timeoutMs?: number; signal?: AbortSignal } = {},
+  options: {
+    workdir?: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    env?: Readonly<Record<string, string>>;
+  } = {},
 ): Promise<ShellResult> {
-  const { workdir, timeoutMs = GIT_TIMEOUT_MS, signal } = options;
+  const { workdir, timeoutMs = GIT_TIMEOUT_MS, signal, env } = options;
 
   const spec = shell.resolve({
     command,
@@ -26,17 +58,25 @@ export async function runShell(
     onExpiry: 'kill',
     stdoutMaxBytes: DEFAULT_MAX_BYTES,
     ...(signal === undefined ? {} : { signal }),
+    ...(env === undefined ? {} : { env }),
   });
 
-  const execution = await shell.execute(spec);
-  const result = await execution.result();
+  const settled = await settleWithin(
+    (async (): Promise<ShellResult> => {
+      const execution = await shell.execute(spec);
+      const result = await execution.result();
+      return {
+        exitCode: result.exitCode,
+        timedOut: result.timedOut === true,
+        aborted: result.aborted === true,
+        stdout: result.stdout.text,
+        stderr: result.stderr.text,
+        truncated: result.stdout.truncated || result.stderr.truncated,
+        stalled: false,
+      };
+    })(),
+    timeoutMs + GUARD_SLACK_MS,
+  );
 
-  return {
-    exitCode: result.exitCode,
-    timedOut: result.timedOut === true,
-    aborted: result.aborted === true,
-    stdout: result.stdout.text,
-    stderr: result.stderr.text,
-    truncated: result.stdout.truncated || result.stderr.truncated,
-  };
+  return settled ?? stalledResult();
 }

package/src/host/tool-approval.ts

@@ -181,3 +181,34 @@ export async function approvalFor(
     displayReason: compose(facts, verdict, note),
   };
 }
+
+/**
+ * 「写工具要点头」那一对的默认口径：点名的工具一律 `ask` + 同一份明细，其余一律 `read`。
+ * 把它直接摊在 `mount()` 的返回值里：`...writeApprovalOf({ … })`。
+ * @param options.tools 需要点头的工具名。
+ * @param options.reason 为什么问（给 agent 看的理由）。
+ * @param options.question 问句（zh / en，≤40 字）。
+ * @param options.fallback 没有明细时的整句（zh / en，≤40 字）。
+ * @param options.detail 审批屏头行那句明细（zh / en，≤20 字）。
+ * @returns `{ needsApproval, approvalDetail }`。
+ */
+export function writeApprovalOf(options: {
+  readonly tools: readonly string[];
+  readonly reason: string;
+  readonly question: ApprovalDetail;
+  readonly fallback: ApprovalDetail;
+  readonly detail: ApprovalDetail;
+}): {
+  needsApproval(call: ApprovalCall): ApprovalVerdict;
+  approvalDetail(call: ApprovalCall): ApprovalFacts | undefined;
+} {
+  const tools = new Set(options.tools);
+  const named = (call: ApprovalCall): boolean => call.name !== undefined && tools.has(call.name);
+  return {
+    needsApproval: (call) =>
+      named(call)
+        ? { kind: 'ask', reason: options.reason, question: options.question, fallback: options.fallback }
+        : { kind: 'read' },
+    approvalDetail: (call) => (named(call) ? options.detail : undefined),
+  };
+}

package/src/host/unit-face.ts

@@ -53,6 +53,11 @@ export interface UnitCall {
   readonly result: unknown;
 }
 
+/**
+ * 挂载结果：路由表 + 工具注册。
+ * `registerTools()` 是**调用时才注册**，返回一组清理函数（卸载 / 热换时外壳逐个调）；
+ * 工具名必须与清单 `dsh.workbench.tools` 一字不差，没有工具就 `() => []`。
+ */
 export interface UnitMountResult {
   readonly routes: RouteTable;
   registerTools(): Array<() => void>;