@dsh-workbench/shared 1.1.14-beta.1 → 1.1.14

package/src/contract/unit-declaration.ts

@@ -71,7 +71,9 @@ const TITLE_KEYS = ['zh', 'en'];
 const TOOL_KEYS = ['name', 'writes', 'key'];
 
 const TOOL_KEY_SHAPE = /^[a-z][a-zA-Z0-9]*$/;
-const HOST_KEYS = ['inject', 'optional'];
+const HOST_KEYS = ['inject', 'optional', 'writes'];
+
+const UNIT_WRITE_SCOPES: readonly string[] = ['unit', 'workspace'];
 
 function text(value: unknown): string {
   return typeof value === 'string' ? value.trim() : '';
@@ -263,6 +265,22 @@ export function declarationProblemsOf(subject: string, raw: unknown): readonly s
       if (host.optional !== undefined) {
         problems.push(...stringArrayProblems(`${subject}: dsh.workbench.host.optional`, host.optional));
       }
+      if (host.writes !== undefined) {
+        const shape = stringArrayProblems(`${subject}: dsh.workbench.host.writes`, host.writes);
+        problems.push(...shape);
+        if (shape.length === 0) {
+          const outsideScopes = (host.writes as readonly string[]).filter(
+            (scope) => !UNIT_WRITE_SCOPES.includes(scope),
+          );
+          if (outsideScopes.length > 0) {
+            problems.push(
+              `${subject}: dsh.workbench.host.writes 里有不认的写入域 ${listOf(outsideScopes)} —— ` +
+                `只认 "unit"（模块自己的数据目录）与 "workspace"（当前会话工作区）两档；` +
+                `模块拿不到产品域与任意路径，别写别的名字（缺省 [] = 不给执行缝门面）`,
+            );
+          }
+        }
+      }
     }
   }
 
@@ -308,6 +326,7 @@ export function readDeclaration(subject: string, raw: unknown): DeclarationRead
       host: {
         inject: [...(declaration.host.inject ?? [])],
         ...(declaration.host.optional === undefined ? {} : { optional: [...declaration.host.optional] }),
+        writes: [...(declaration.host.writes ?? [])],
       },
       ...(declaration.needs === undefined ? {} : { needs: declaration.needs }),
     },

package/src/contract/unit.ts

@@ -45,10 +45,13 @@ export interface UnitTool {
 
 /**
  * 模块要外壳的哪些服务：inject 缺一个就挂不上，optional 缺了照挂。
+ * writes 声明模块要哪几档执行缝写入域：unit 是模块自己的数据目录，workspace 是当前会话工作区；
+ * 缺省 [] = 不给执行缝门面（deps.seam 是 undefined）。
  */
 export interface UnitHostNeeds {
   readonly inject: readonly string[];
   readonly optional?: readonly string[];
+  readonly writes?: readonly ('unit' | 'workspace')[];
 }
 
 /**

package/src/host/__tests__/env-policy.test.ts

@@ -0,0 +1,114 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, delimiter } from 'node:path';
+import { afterAll, afterEach, beforeAll, describe, expect, it } from 'vitest';
+import {
+  bootstrapEnvOf,
+  envTextOf,
+  inheritedEnvOf,
+  overlayEnvOf,
+  pathWithBinsOf,
+  productEnvOf,
+  promptlessGitEnvOf,
+  promptlessProcessEnvOf,
+  unitEnvOf,
+} from '../env-policy.js';
+
+const ROOT = mkdtempSync(join(tmpdir(), 'dsh-wb-env-policy-'));
+const REAL_HOME = join(ROOT, 'real-home');
+const RUNTIME = join(ROOT, 'workbench');
+const DSH_HOME = process.env.DSH_HOME;
+
+beforeAll(() => {
+  mkdirSync(REAL_HOME, { recursive: true });
+  writeFileSync(join(REAL_HOME, '.npmrc'), 'registry=https://example.test\n');
+  writeFileSync(join(REAL_HOME, '.gitconfig'), '[user]\n');
+  process.env.DSH_HOME = join(ROOT, 'dsh');
+});
+
+afterEach(() => {
+  if (DSH_HOME === undefined) delete process.env.DSH_HOME;
+  else process.env.DSH_HOME = DSH_HOME;
+});
+
+afterAll(() => {
+  rmSync(ROOT, { recursive: true, force: true });
+});
+
+describe('受控 env 入口', () => {
+  it('product：HOME / 缓存全钉在运行时根，真 npmrc/gitconfig 只读指过去', () => {
+    const env = productEnvOf({ runtimeRoot: RUNTIME, realHome: REAL_HOME });
+    expect(env['HOME']).toBe(join(RUNTIME, 'home'));
+    expect(env['DSH_WORKBENCH_HOME']).toBe(RUNTIME);
+    expect(env['DSH_HOME']).toBe(join(ROOT, 'dsh'));
+    expect(env['npm_config_cache']).toBe(join(RUNTIME, 'npm-cache'));
+    expect(env['NPM_CONFIG_CACHE']).toBe(join(RUNTIME, 'npm-cache'));
+    expect(env['npm_config_store_dir']).toBe(join(RUNTIME, 'pnpm-store'));
+    expect(env['NPM_CONFIG_USERCONFIG']).toBe(join(REAL_HOME, '.npmrc'));
+    expect(env['GIT_CONFIG_GLOBAL']).toBe(join(REAL_HOME, '.gitconfig'));
+    expect(env['NO_UPDATE_NOTIFIER']).toBe('1');
+  });
+
+  it('product：没有真配置时不指过去', () => {
+    const emptyHome = join(ROOT, 'empty-home');
+    mkdirSync(emptyHome, { recursive: true });
+    const env = productEnvOf({ runtimeRoot: RUNTIME, realHome: emptyHome });
+    expect(env['NPM_CONFIG_USERCONFIG']).toBeUndefined();
+    expect(env['GIT_CONFIG_GLOBAL']).toBeUndefined();
+  });
+
+  it('unit：HOME 与 npm/pnpm 目录钉到单元数据目录', () => {
+    const unitRoot = join(RUNTIME, 'units', 'demo');
+    const env = unitEnvOf({ runtimeRoot: RUNTIME, unitRoot, realHome: REAL_HOME });
+    expect(env['HOME']).toBe(join(unitRoot, 'home'));
+    expect(env['npm_config_cache']).toBe(join(unitRoot, 'npm-cache'));
+    expect(env['npm_config_store_dir']).toBe(join(unitRoot, 'pnpm-store'));
+    expect(env['DSH_WORKBENCH_HOME']).toBe(RUNTIME);
+  });
+
+  it('bootstrap：继承父环境、HOME/缓存钉住、PATH 可替换、pwsh 加 USERPROFILE', () => {
+    const parent = { PATH: '/usr/bin', KEEP: 'yes' };
+    const env = bootstrapEnvOf({
+      root: join(RUNTIME, 'opencli'),
+      realHome: REAL_HOME,
+      shellKind: 'posix',
+      parent,
+      path: '/desktop/bin' + delimiter + '/usr/bin',
+    });
+    expect(env['KEEP']).toBe('yes');
+    expect(env['PATH']).toBe('/desktop/bin' + delimiter + '/usr/bin');
+    expect(env['HOME']).toBe(join(RUNTIME, 'opencli', 'home'));
+    expect(env['npm_config_cache']).toBe(join(RUNTIME, 'opencli', 'npm-cache'));
+    expect(env['NPM_CONFIG_USERCONFIG']).toBe(join(REAL_HOME, '.npmrc'));
+    expect(env['NO_COLOR']).toBe('1');
+    expect(env['TERM']).toBe('dumb');
+    expect(env['USERPROFILE']).toBeUndefined();
+    const pwsh = bootstrapEnvOf({ root: join(RUNTIME, 'opencli'), realHome: REAL_HOME, shellKind: 'pwsh', parent });
+    expect(pwsh['USERPROFILE']).toBe(join(RUNTIME, 'opencli', 'home'));
+  });
+
+  it('promptless：posix 关 askpass 指向 false，win32 删掉父进程的 askpass', () => {
+    const posix = promptlessGitEnvOf('darwin');
+    expect(posix['GIT_TERMINAL_PROMPT']).toBe('0');
+    expect(posix['GIT_ASKPASS']).toBe('/usr/bin/false');
+    const win = promptlessGitEnvOf('win32');
+    expect(win).not.toHaveProperty('GIT_ASKPASS');
+    const parent = { GIT_ASKPASS: 'C:/evil.exe', KEEP: '1' };
+    const merged = promptlessProcessEnvOf(parent, 'win32');
+    expect(merged['GIT_ASKPASS']).toBeUndefined();
+    expect(merged['KEEP']).toBe('1');
+    expect(merged['GIT_TERMINAL_PROMPT']).toBe('0');
+  });
+
+  it('叠层：undefined 删键，envTextOf 丢掉非字符串', () => {
+    const merged = overlayEnvOf({ A: '1', B: '2' }, { B: undefined, C: '3' });
+    expect(merged).toEqual({ A: '1', C: '3' });
+    expect(inheritedEnvOf({ A: '1' })).toEqual({ A: '1' });
+    expect(envTextOf({ A: '1', B: undefined })).toEqual({ A: '1' });
+  });
+
+  it('PATH 前插去重', () => {
+    expect(pathWithBinsOf(['/a', '/b'].join(delimiter), ['/a', '/c'])).toBe(['/a', '/c', '/b'].join(delimiter));
+    expect(pathWithBinsOf(undefined, ['/x'])).toBe('/x');
+  });
+});

package/src/host/__tests__/fs-write.test.ts

@@ -0,0 +1,96 @@
+import { chmodSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterAll, describe, expect, it } from 'vitest';
+import {
+  ensureDir,
+  makeExecutable,
+  writeBytesFile,
+  writeBytesFileAsync,
+  writeJsonFile,
+  writeJsonFileAsync,
+  writeTextFile,
+  writeTextFileAsync,
+} from '../fs-write.js';
+
+const ROOT = mkdtempSync(join(tmpdir(), 'dsh-wb-fs-write-'));
+
+afterAll(() => {
+  rmSync(ROOT, { recursive: true, force: true });
+});
+
+describe('宿主文件写入口', () => {
+  it('写文本：建父目录、原子落盘、内容正确', () => {
+    const file = join(ROOT, 'a', 'b', 'note.txt');
+    writeTextFile(file, 'hello');
+    expect(readFileSync(file, 'utf8')).toBe('hello');
+    expect(readdirSync(join(ROOT, 'a', 'b'))).toEqual(['note.txt']);
+  });
+
+  it('mode 默认保留已有文件的权限位', () => {
+    const file = join(ROOT, 'secret.txt');
+    writeFileSync(file, 'old', { mode: 0o600 });
+    writeTextFile(file, 'new');
+    expect(statSync(file).mode & 0o777).toBe(0o600);
+  });
+
+  it('显式 mode 生效，可执行文件 0755', () => {
+    const secret = join(ROOT, 'explicit.txt');
+    writeTextFile(secret, 's', { mode: 0o600 });
+    expect(statSync(secret).mode & 0o777).toBe(0o600);
+    const script = join(ROOT, 'bin', 'run.sh');
+    writeTextFile(script, '#!/bin/sh\n', { mode: 0o755 });
+    expect(statSync(script).mode & 0o777).toBe(0o755);
+    const plain = join(ROOT, 'plain.sh');
+    writeTextFile(plain, '#!/bin/sh\n');
+    makeExecutable(plain);
+    expect(statSync(plain).mode & 0o777).toBe(0o755);
+  });
+
+  it('JSON：两空格缩进 + 末尾换行', () => {
+    const file = join(ROOT, 'state.json');
+    writeJsonFile(file, { a: 1, list: [2] });
+    expect(readFileSync(file, 'utf8')).toBe('{\n  "a": 1,\n  "list": [\n    2\n  ]\n}\n');
+  });
+
+  it('atomic:false 直接写，不建父目录', () => {
+    const file = join(ROOT, 'direct.txt');
+    writeTextFile(file, 'x', { atomic: false });
+    expect(readFileSync(file, 'utf8')).toBe('x');
+    expect(() => writeTextFile(join(ROOT, 'missing', 'deep.txt'), 'x', { atomic: false, mkdir: false })).toThrow();
+  });
+
+  it('二进制写：字节原样落盘', () => {
+    const file = join(ROOT, 'img.bin');
+    writeBytesFile(file, new Uint8Array([0, 255, 7]));
+    expect([...readFileSync(file)]).toEqual([0, 255, 7]);
+  });
+
+  it('异步版语义一致', async () => {
+    const file = join(ROOT, 'async.json');
+    await writeJsonFileAsync(file, { ok: true });
+    expect(JSON.parse(readFileSync(file, 'utf8'))).toEqual({ ok: true });
+    const text = join(ROOT, 'async.txt');
+    await writeTextFileAsync(text, 'a');
+    expect(readFileSync(text, 'utf8')).toBe('a');
+    const bin = join(ROOT, 'async.bin');
+    await writeBytesFileAsync(bin, new Uint8Array([1, 2]));
+    expect([...readFileSync(bin)]).toEqual([1, 2]);
+  });
+
+  it('并发写同一文件：结果完整，不残留临时文件', async () => {
+    const file = join(ROOT, 'race.txt');
+    await Promise.all(Array.from({ length: 12 }, (_, i) => writeTextFileAsync(file, `v${String(i)}`)));
+    expect(readFileSync(file, 'utf8')).toMatch(/^v\d+$/);
+    expect(readdirSync(ROOT).filter((name) => name.startsWith('race.txt'))).toEqual(['race.txt']);
+  });
+
+  it('ensureDir 幂等', () => {
+    const dir = join(ROOT, 'x', 'y');
+    ensureDir(dir);
+    ensureDir(dir);
+    writeFileSync(join(dir, 'f'), '', 'utf8');
+    chmodSync(join(dir, 'f'), 0o644);
+    expect(readdirSync(dir)).toEqual(['f']);
+  });
+});

package/src/host/__tests__/preflight-route.test.ts

@@ -30,4 +30,33 @@ describe('preflightHandler（体检那一拍带什么参数）', () => {
 
     expect(handler(new URLSearchParams(''))).toEqual({ ok: true, ...SNAPSHOT });
   });
+
+  it('★ 先回上一轮的结果再起新一轮：run 一上来就把快照重置成 checking，也不许把它顶掉', () => {
+    let current = { phase: 'failed', steps: [], at: 1 };
+    const run = vi.fn(async () => {
+      current = { phase: 'checking', steps: [], at: 2 };
+      return current;
+    });
+    const handler = preflightHandler({ run, snapshot: () => current });
+
+    const reply = handler(new URLSearchParams(''));
+
+    expect(reply).toEqual({ ok: true, phase: 'failed', steps: [], at: 1 });
+    expect(run).toHaveBeenCalledTimes(1);
+    expect(current.phase).toBe('checking');
+  });
+
+  it('★ 重试（hard）回的是新一轮的进度：别把上一轮的 failed 又顶回画面', () => {
+    let current = { phase: 'failed', steps: [], at: 1 };
+    const run = vi.fn(async () => {
+      current = { phase: 'checking', steps: [], at: 2 };
+      return current;
+    });
+    const handler = preflightHandler({ run, snapshot: () => current });
+
+    const reply = handler(new URLSearchParams('hard=1'));
+
+    expect(reply).toEqual({ ok: true, phase: 'checking', steps: [], at: 2 });
+    expect(run).toHaveBeenCalledWith({ hard: true });
+  });
 });

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

@@ -0,0 +1,296 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterAll, describe, expect, it } from 'vitest';
+import { SeamError } from '../seam/intent.js';
+import { createSeam } from '../seam/run.js';
+import { createUnitSeam, unitDataRoot } from '../seam/unit-seam.js';
+import { createFakeProcesses, createFakeShell, createFakeLogger } from '../../testing/host-fakes.js';
+
+const ROOT = join(tmpdir(), 'dsh-wb-seam-root');
+const PROJECT = join(tmpdir(), 'dsh-wb-seam-project');
+const SCRATCH = mkdtempSync(join(tmpdir(), 'dsh-wb-seam-'));
+const REAL_HOME = join(SCRATCH, 'home');
+
+afterAll(() => {
+  rmSync(SCRATCH, { recursive: true, force: true });
+});
+
+function policyOf(call: { sandboxPolicy?: unknown } | undefined): unknown {
+  return call?.sandboxPolicy;
+}
+
+describe('createSeam', () => {
+  it('产品域：固定根 + 注入产品环境', async () => {
+    const fake = createFakeShell([{}]);
+    const seam = createSeam({ shell: fake.shell, runtimeRoot: ROOT, realHome: REAL_HOME });
+    const outcome = await seam.run({ command: 'npm view left-pad version', intent: { kind: 'product' } });
+    expect(outcome.exitCode).toBe(0);
+    expect(policyOf(fake.calls[0])).toEqual({ mode: 'workspace-write', workspaceRoot: ROOT });
+    const env = fake.calls[0]?.env;
+    expect(env?.['HOME']).toBe(join(ROOT, 'home'));
+    expect(env?.['npm_config_cache']).toBe(join(ROOT, 'npm-cache'));
+    expect(env?.['DSH_WORKBENCH_HOME']).toBe(ROOT);
+    expect(env?.['npm_config_state_dir']).toBe(join(ROOT, 'pnpm-state'));
+  });
+
+  it('产品域不跟会话只读，只跟部署上限', async () => {
+    const fake = createFakeShell([{}]);
+    const seam = createSeam({
+      shell: fake.shell,
+      runtimeRoot: ROOT,
+      ceiling: 'workspace-write',
+      grantOf: () => ({ mode: 'read-only', workspaceRoot: PROJECT }),
+    });
+    await seam.run({ command: 'npm view x version', intent: { kind: 'product' } });
+    expect(policyOf(fake.calls[0])).toEqual({ mode: 'workspace-write', workspaceRoot: ROOT });
+  });
+
+  it('工作区域：取会话解析结果；上限更宽时按会话', async () => {
+    const fake = createFakeShell([{}]);
+    const seam = createSeam({
+      shell: fake.shell,
+      runtimeRoot: ROOT,
+      ceiling: 'danger-full-access',
+      grantOf: () => ({ mode: 'danger-full-access', workspaceRoot: PROJECT }),
+    });
+    await seam.run({ command: 'pnpm install', intent: { kind: 'workspace' }, session: {} });
+    expect(policyOf(fake.calls[0])).toEqual({ mode: 'danger-full-access', workspaceRoot: PROJECT });
+  });
+
+  it('会话只读：起进程前就拒绝，不起进程', async () => {
+    const fake = createFakeShell([{}]);
+    const seam = createSeam({
+      shell: fake.shell,
+      runtimeRoot: ROOT,
+      grantOf: () => ({ mode: 'read-only', workspaceRoot: PROJECT }),
+    });
+    await expect(seam.run({ command: 'pnpm install', intent: { kind: 'workspace' }, session: {} })).rejects.toMatchObject({
+      code: 'read-only',
+    });
+    expect(fake.calls).toHaveLength(0);
+  });
+
+  it('没有会话却要写工作区：起进程前报 workspace-unknown', async () => {
+    const fake = createFakeShell([{}]);
+    const seam = createSeam({ shell: fake.shell, runtimeRoot: ROOT });
+    await expect(seam.run({ command: 'pnpm install', intent: { kind: 'workspace' } })).rejects.toMatchObject({
+      code: 'workspace-unknown',
+    });
+    expect(fake.calls).toHaveLength(0);
+  });
+
+  it('外部路径：同一目录可以，跨目录拒绝', async () => {
+    const fake = createFakeShell([{}]);
+    const seam = createSeam({ shell: fake.shell, runtimeRoot: ROOT });
+    await seam.run({ command: 'png', intent: { kind: 'paths', paths: [join(SCRATCH, 'a.png'), join(SCRATCH, 'b.png')] } });
+    expect(policyOf(fake.calls[0])).toEqual({ mode: 'workspace-write', workspaceRoot: SCRATCH });
+    await expect(
+      seam.run({ command: 'png', intent: { kind: 'paths', paths: [join(SCRATCH, 'a.png'), '/etc/hosts'] } }),
+    ).rejects.toMatchObject({ code: 'paths-span-trees' });
+    expect(fake.calls).toHaveLength(1);
+  });
+
+  it('安全重试：产品域被拒后按产品域重跑一次并标记 healed', async () => {
+    const fake = createFakeShell([
+      {
+        exitCode: 1,
+        stderr: "npm error code EPERM\nnpm error path " + join(ROOT, 'npm-cache', '_cacache') + "\n",
+        sandbox: { mode: 'workspace-write', denied: true },
+      },
+      {},
+    ]);
+    const seam = createSeam({
+      shell: fake.shell,
+      runtimeRoot: ROOT,
+      grantOf: () => ({ mode: 'workspace-write', workspaceRoot: PROJECT }),
+    });
+    const outcome = await seam.run({
+      command: 'npm publish',
+      intent: { kind: 'workspace' },
+      session: {},
+      retry: 'safe',
+    });
+    expect(fake.calls).toHaveLength(2);
+    expect(policyOf(fake.calls[1])).toEqual({ mode: 'workspace-write', workspaceRoot: ROOT });
+    expect(outcome.denial?.healed).toBe(true);
+    expect(outcome.denial?.scope).toBe('product');
+  });
+
+  it('写命令默认不自动重试：denial 直接给类型化错误', async () => {
+    const fake = createFakeShell([
+      {
+        exitCode: 1,
+        stderr: "EPERM: operation not permitted, mkdir '" + join(ROOT, 'npm-cache') + "'\n",
+        sandbox: { mode: 'workspace-write', denied: true },
+      },
+    ]);
+    const seam = createSeam({
+      shell: fake.shell,
+      runtimeRoot: ROOT,
+      grantOf: () => ({ mode: 'workspace-write', workspaceRoot: PROJECT }),
+    });
+    await expect(
+      seam.run({ command: 'git commit', intent: { kind: 'workspace' }, session: {} }),
+    ).rejects.toMatchObject({ code: 'sandbox-denied' });
+    expect(fake.calls).toHaveLength(1);
+  });
+
+  it('外部路径被拒：bestEffort 返回带 denial 的结果，否则抛类型化错误', async () => {
+    const external = join(tmpdir(), 'dsh-wb-seam-external', 'shot.png');
+    const denialReply = {
+      exitCode: 1,
+      stderr: "EPERM: operation not permitted, open '" + external + "'\n",
+      sandbox: { mode: 'workspace-write', denied: true },
+    };
+    const best = createFakeShell([denialReply]);
+    const seamBest = createSeam({ shell: best.shell, runtimeRoot: ROOT, logger: createFakeLogger().logger });
+    const outcome = await seamBest.run({ command: 'png', intent: { kind: 'product' }, bestEffort: true });
+    expect(outcome.denial?.scope).toBe('external');
+    expect(outcome.denial?.path).toBe(external);
+
+    const strict = createFakeShell([denialReply]);
+    const seamStrict = createSeam({ shell: strict.shell, runtimeRoot: ROOT });
+    await expect(seamStrict.run({ command: 'png', intent: { kind: 'product' } })).rejects.toBeInstanceOf(SeamError);
+  });
+
+  it('每次调用都记账', async () => {
+    const fake = createFakeShell([{}, {}]);
+    const seam = createSeam({ shell: fake.shell, runtimeRoot: ROOT });
+    await seam.run({ command: 'git status', intent: { kind: 'none' } });
+    await seam.run({ command: 'npm view x version', intent: { kind: 'product' } });
+    expect(seam.facts()).toHaveLength(2);
+    expect(seam.facts()[0]).toMatchObject({ command: 'git status', intent: 'none', mode: 'workspace-write' });
+    expect(seam.facts()[1]).toMatchObject({ command: 'npm view x version', intent: 'product' });
+  });
+});
+
+describe('createUnitSeam', () => {
+  it('unit 域：根在产品域内，env 落在模块目录', async () => {
+    const fake = createFakeShell([{}]);
+    const seam = createSeam({ shell: fake.shell, runtimeRoot: ROOT, realHome: REAL_HOME });
+    const unit = createUnitSeam({ seam, unit: 'demo', runtimeRoot: ROOT, realHome: REAL_HOME });
+    await unit.run({ command: 'echo hi', scope: 'unit' });
+    expect(policyOf(fake.calls[0])).toEqual({ mode: 'workspace-write', workspaceRoot: ROOT });
+    const env = fake.calls[0]?.env;
+    expect(env?.['HOME']).toBe(join(unitDataRoot(ROOT, 'demo'), 'home'));
+    expect(env?.['npm_config_cache']).toBe(join(unitDataRoot(ROOT, 'demo'), 'npm-cache'));
+  });
+
+  it('workspace 域：清单没声明就拒绝；声明后要求会话', async () => {
+    const fake = createFakeShell([{}, {}]);
+    const seam = createSeam({
+      shell: fake.shell,
+      runtimeRoot: ROOT,
+      grantOf: () => ({ mode: 'workspace-write', workspaceRoot: PROJECT }),
+    });
+    const undeclared = createUnitSeam({ seam, unit: 'demo', runtimeRoot: ROOT });
+    await expect(undeclared.run({ command: 'touch x', scope: 'workspace', session: {} })).rejects.toMatchObject({
+      code: 'scope-not-declared',
+    });
+    const declared = createUnitSeam({ seam, unit: 'demo', runtimeRoot: ROOT, declared: ['workspace'] });
+    await expect(declared.run({ command: 'touch x', scope: 'workspace' })).rejects.toMatchObject({
+      code: 'workspace-unknown',
+    });
+    await declared.run({ command: 'touch x', scope: 'workspace', session: {} });
+    expect(policyOf(fake.calls[0])).toEqual({ mode: 'workspace-write', workspaceRoot: PROJECT });
+  });
+});
+
+describe('宿主域：run / spawn / open', () => {
+  it('host 域 run：按 argv 起宿主进程，拿回输出，记 host 事实', async () => {
+    const fake = createFakeProcesses([{ stdout: 'ok\n', exitCode: 0 }]);
+    const seam = createSeam({ shell: createFakeShell([]).shell, runtimeRoot: ROOT, allowHost: true, processes: fake.host });
+    const outcome = await seam.run({
+      argv: ['git', '-C', PROJECT, 'status'],
+      intent: { kind: 'host' },
+      env: { GIT_TERMINAL_PROMPT: '0' },
+      timeoutMs: 5_000,
+    });
+    expect(outcome.exitCode).toBe(0);
+    expect(outcome.stdout).toBe('ok\n');
+    expect(fake.calls[0]?.file).toBe('git');
+    expect(fake.calls[0]?.args).toEqual(['-C', PROJECT, 'status']);
+    expect(fake.calls[0]?.env['GIT_TERMINAL_PROMPT']).toBe('0');
+    expect(fake.calls[0]?.detached).toBe(false);
+    expect(seam.facts().at(-1)).toMatchObject({ verb: 'run', intent: 'host', mode: 'host' });
+  });
+
+  it('host 域 run：shell line 走 bash -c，超时到点 kill', async () => {
+    const fake = createFakeProcesses([{ hang: true }]);
+    const seam = createSeam({
+      shell: createFakeShell([]).shell,
+      runtimeRoot: ROOT,
+      allowHost: true,
+      processes: fake.host,
+    });
+    const outcome = await seam.run({ command: 'pnpm install', shellKind: 'posix', intent: { kind: 'host' }, timeoutMs: 10 });
+    expect(fake.calls[0]?.file).toBe('bash');
+    expect(fake.calls[0]?.args).toEqual(['-c', 'pnpm install']);
+    expect(outcome.timedOut).toBe(true);
+    expect(fake.children[0]?.killed).toContain('SIGKILL');
+  });
+
+  it('没有宿主能力时 host 域起不来，也不许 spawn/open', async () => {
+    const fake = createFakeProcesses([{}]);
+    const seam = createSeam({ shell: createFakeShell([]).shell, runtimeRoot: ROOT, processes: fake.host });
+    await expect(seam.run({ argv: ['git', 'status'], intent: { kind: 'host' } })).rejects.toMatchObject({
+      code: 'scope-not-declared',
+    });
+    expect(() =>
+      seam.spawn({ target: { argv: ['node', 'x'] }, intent: { kind: 'host' }, lifetime: 'host', logFile: join(SCRATCH, 'x.log') }),
+    ).toThrow(SeamError);
+    expect(fake.calls).toHaveLength(0);
+  });
+
+  it('spawn：detached + 日志文件 + unref，handle 能拿到 pid 与退出', async () => {
+    const fake = createFakeProcesses([{ hang: true }]);
+    const seam = createSeam({ shell: createFakeShell([]).shell, runtimeRoot: ROOT, allowHost: true, processes: fake.host });
+    const logFile = join(SCRATCH, 'spawn.log');
+    const handle = seam.spawn({
+      target: { argv: ['node', 'seed.mjs'] },
+      intent: { kind: 'host' },
+      lifetime: 'host',
+      logFile,
+      label: 'seed',
+    });
+    expect(handle.pid).toBe(4242);
+    expect(handle.logFile).toBe(logFile);
+    expect(fake.calls[0]?.detached).toBe(true);
+    expect(fake.calls[0]?.stdio).toBe('log');
+    expect(fake.calls[0]?.logFile).toBe(logFile);
+    expect(fake.children[0]?.unrefed).toBe(true);
+    expect(seam.facts().at(-1)).toMatchObject({ verb: 'spawn', intent: 'host', mode: 'host' });
+    const waiting = handle.exit();
+    fake.children[0]?.finish(0);
+    await expect(waiting).resolves.toEqual({ code: 0, signal: null });
+  });
+
+  it('open：双向流读写与退出', async () => {
+    const fake = createFakeProcesses([{ hang: true }]);
+    const seam = createSeam({ shell: createFakeShell([]).shell, runtimeRoot: ROOT, allowHost: true, processes: fake.host });
+    const channel = seam.open({
+      target: { argv: ['node', 'mcp-server.mjs'] },
+      intent: { kind: 'host' },
+      env: { MCP_TOKEN: 't' },
+    });
+    const lines: string[] = [];
+    channel.onData((chunk) => lines.push(chunk));
+    channel.write('hello\n');
+    fake.children[0]?.emitStdout('world\n');
+    expect(lines).toEqual(['world\n']);
+    expect(fake.children[0]?.writes).toEqual(['hello\n']);
+    expect(fake.calls[0]?.env['MCP_TOKEN']).toBe('t');
+    const exited = new Promise<unknown>((resolve) => channel.onExit((event) => resolve(event)));
+    fake.children[0]?.finish(3);
+    await expect(exited).resolves.toEqual({ code: 3, signal: null });
+    expect(seam.facts().at(-1)).toMatchObject({ verb: 'open', intent: 'host' });
+  });
+
+  it('沙箱域也能用 argv：内部拼成命令行交给 dsh shell', async () => {
+    const fake = createFakeShell([{}]);
+    const seam = createSeam({ shell: fake.shell, runtimeRoot: ROOT });
+    await seam.run({ argv: ['npm', 'view', 'left-pad', 'version'], intent: { kind: 'product' } });
+    expect(fake.calls[0]?.command).toBe("'npm' 'view' 'left-pad' 'version'");
+  });
+});

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

@@ -24,7 +24,31 @@ function replyingShell(exitCode: number, timedOut = false): DshShell {
   };
 }
 
+function sandboxedShell(): DshShell {
+  return {
+    resolve: (request) => request,
+    execute: async () => ({
+      result: async () => ({
+        exitCode: 3_221_225_794,
+        timedOut: false,
+        aborted: false,
+        stdout: { text: '', truncated: false },
+        stderr: { text: 'windows-acl-run: token setup failed\n', truncated: false },
+        sandbox: { mode: 'workspace-write', denied: false, runnerFailed: true },
+      }),
+    }),
+  };
+}
+
 describe('runShell', () => {
+  it('★ 沙箱事实原样带回来：runnerFailed 不当成"命令自己退出"', async () => {
+    const result = await runShell(sandboxedShell(), 'echo hi');
+
+    expect(result.exitCode).toBe(3_221_225_794);
+    expect(result.sandbox?.runnerFailed).toBe(true);
+    expect(result.stderr).toContain('windows-acl-run');
+  });
+
   it('★ 宿主一直不交结果 → 到点自己收尾，不把调用方挂住', async () => {
     vi.useFakeTimers();
     try {

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

@@ -0,0 +1,20 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { clockOf, epochOf, now, nowIso } from '../time.js';
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe('宿主时间入口', () => {
+  it('now 读的是 Date.now，nowIso 是合法 ISO', () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-01-02T03:04:05.000Z'));
+    expect(now()).toBe(Date.parse('2026-01-02T03:04:05.000Z'));
+    expect(nowIso()).toBe('2026-01-02T03:04:05.000Z');
+  });
+
+  it('格式化助手仍只看传入值', () => {
+    expect(clockOf(0)).toBe('00:00:00');
+    expect(epochOf('1970-01-01T00:00:01.000Z')).toBe(1000);
+  });
+});

package/src/host/adapter-set.ts

@@ -85,7 +85,6 @@ const FULL_METHODS = [
   ['runtime', 'runners'],
   ['runtime', 'health'],
   ['runtime', 'seed'],
-  ['runtime', 'warnUnwritableRoot'],
   ['plugins', 'declarationLookup'],
   ['plugins', 'createUnits'],
   ['actions', 'configSyncHandler'],

package/src/host/changelog.ts

@@ -1,3 +1,4 @@
+import { now as clockNow } from './time.js';
 import dayjs from 'dayjs';
 
 export const CHANGELOG_FILE = 'CHANGELOG.md';
@@ -37,7 +38,7 @@ export function changelogVersion(value: string): string {
     .replace(/^v/, '');
 }
 
-export function changelogDate(now: Date = new Date()): string {
+export function changelogDate(now: Date = new Date(clockNow())): string {
   return dayjs(now).format('YYYY-MM-DD');
 }