@mzzsfy/dsh-shell-select 0.3.0 → 0.4.0

package/test/config.test.mjs

@@ -3,10 +3,10 @@
 
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
-import { Config, defaultConfig, entryById, requireEntry, buildArgv, KINDS, RESOLVED_AUTO } from '../src/config.mjs'
+import { resolveConfig, defaultConfig, entryById, requireEntry, buildArgv, KINDS, RESOLVED_AUTO } from '../src/config.mjs'
 
 test('schema 应用出厂默认:三客户端 + 默认 pwsh', () => {
-  const applied = Config({})
+  const applied = resolveConfig({})
   assert.deepEqual(applied, defaultConfig())
   assert.equal(applied.default, 'pwsh')
   assert.deepEqual(applied.shells.map((entry) => entry.id), ['pwsh', 'git-bash', 'cmd'])
@@ -17,7 +17,60 @@ test('schema 应用出厂默认:三客户端 + 默认 pwsh', () => {
 })
 
 test('schema 拒绝未知 kind;default 跨字段一致性由 validate hook 与 requireEntry 兜底', () => {
-  assert.throws(() => Config({ shells: [{ id: 'x', name: 'X', kind: 'fish', path: '' }], default: 'x' }))
+  assert.throws(() => resolveConfig({ shells: [{ id: 'x', name: 'X', kind: 'fish', path: '' }], default: 'x' }))
+})
+
+test('落盘坏形态防御:volatile 字段被序列化成对象时降级默认,行构造不炸', () => {
+  // 事故:原生设置页/ref 序列化把 shells 落盘为 {},冷启动 Config 抛
+  // "expected array but got [object Object]" → 行死 → settings 无节 →
+  // 设置页 "no longer configurable" 死锁。类型不符的键必须降级默认。
+  const poisoned = {
+    shells: {},
+    deny: { 0: 'rm' },
+    default: 42,
+    timeoutMs: 'forever',
+    cwd: ['C:\\'],
+    good: 'ignored-by-schema',
+  }
+  const applied = resolveConfig(poisoned)
+  assert.deepEqual(applied, defaultConfig())
+  // 合法值原样保留,清洗不做过度剥离
+  const valid = resolveConfig({ shells: [{ id: 'pwsh', kind: 'pwsh' }], default: 'pwsh', deny: ['rm -rf'], cwd: 'C:\\tmp', timeoutMs: 5000 })
+  assert.equal(valid.shells.length, 1)
+  assert.equal(valid.default, 'pwsh')
+  assert.deepEqual(valid.deny, ['rm -rf'])
+  assert.equal(valid.cwd, 'C:\\tmp')
+  assert.equal(valid.timeoutMs, 5000)
+  // 非对象整体(null/数组/标量)= 无配置,出厂默认
+  for (const junk of [null, 'x', 42, ['shells']]) {
+    assert.deepEqual(resolveConfig(junk), defaultConfig())
+  }
+})
+
+test('冻结输入防御:volatile ref 深冻结快照喂入不改写不抛(挂载路径)', () => {
+  // 事故:cosmokit createVolatile 的 snapshot 对 volatile 值逐层 Object.freeze,
+  // 行 Config ref .get() 产物是深冻结对象;sanitizeConfigEntry 引用透传,
+  // schemastery resolve 原地改写入参(填默认)撞冻结 env 抛
+  // "Cannot assign to read only property 'MSYSTEM'" → 执行器挂载失败,
+  // 每次启动回滚官方 pwsh 链,shell 工具永不注册。
+  // 契约:resolveConfig 对输入不可变(与 unwrapConfig 输出 clone 对称)。
+  const frozenSection = Object.freeze({
+    shells: Object.freeze([
+      Object.freeze({ id: 'pwsh', kind: 'pwsh', path: '', args: Object.freeze([]), env: Object.freeze({}) }),
+      Object.freeze({ id: 'git-bash', kind: 'bash', path: '', args: Object.freeze([]), login: true, distro: '', env: Object.freeze({ MSYSTEM: 'MINGW64' }) }),
+    ]),
+    default: 'git-bash',
+  })
+  const applied = resolveConfig(frozenSection)
+  assert.equal(applied.default, 'git-bash')
+  assert.deepEqual(applied.shells.map((entry) => entry.id), ['pwsh', 'git-bash'])
+  assert.deepEqual(applied.shells[1].env, { MSYSTEM: 'MINGW64' })
+  // 二轮 resolve(行重载/快照回灌常态)同样幂等
+  const again = resolveConfig(frozenSection)
+  assert.deepEqual(again, applied)
+  // 输出与冻结输入脱耦:改输出不 affects 输入,反复解析结果稳定
+  applied.shells[1].env.MSYSTEM = 'TERM'
+  assert.deepEqual(resolveConfig(frozenSection).shells[1].env, { MSYSTEM: 'MINGW64' })
 })
 
 test('pwsh argv:非交互形 + 编码前缀', () => {
@@ -50,7 +103,7 @@ test('login 显式配置与自定义 args 模板互斥时模板优先', () => {
 })
 
 test('schema 往返:login 布尔保留,旧配置缺省落 false', () => {
-  const applied = Config({ shells: [
+  const applied = resolveConfig({ shells: [
     { id: 'm', name: 'MSYS2', kind: 'bash', path: 'C:\\msys64\\usr\\bin\\bash.exe', login: true },
     { id: 'g', name: 'Git Bash', kind: 'bash', path: '' },
   ], default: 'm' })

package/test/deny-config.test.mjs

@@ -1,4 +1,4 @@
-// deny 顶层字段:schema 往返与 updateConfig 落盘回读。
+// deny 顶层字段:schema 往返与 updateConfig 落盘回读。
 // BDD 场景见 docs/progress/feat-shell-select-deny.md 场景 7。
 
 import { test } from 'node:test'
@@ -6,10 +6,10 @@ import assert from 'node:assert/strict'
 import { readFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { dirname, join } from 'node:path'
-import { Config, defaultConfig } from '../src/config.mjs'
+import { resolveConfig, defaultConfig } from '../src/config.mjs'
 
 const here = dirname(fileURLToPath(import.meta.url))
-const executorSource = readFileSync(join(here, '..', 'src', 'executor.mjs'), 'utf8')
+const webRoutesSource = readFileSync(join(here, '..', 'src', 'web-routes.mjs'), 'utf8')
 
 test('schema 默认:deny 空数组,旧配置反序列化补默认', () => {
   const config = defaultConfig()
@@ -17,17 +17,17 @@ test('schema 默认:deny 空数组,旧配置反序列化补默认', () => {
 })
 
 test('schema 往返:deny 保留;allow 无消费者(deny 绝对,无豁免语义)', () => {
-  const config = Config({ deny: ['format '], allow: ['git .*'] })
+  const config = resolveConfig({ deny: ['format '], allow: ['git .*'] })
   assert.deepEqual(config.deny, ['format '])
   // schemastery 透传未知键,僵尸键靠"无读取方"守卫:matchDeny/toSection 均只触 deny
   const denylistSource = readFileSync(join(here, '..', 'src', 'denylist.mjs'), 'utf8')
   const clientSource = readFileSync(join(here, '..', 'src', 'client.js'), 'utf8')
   assert.doesNotMatch(denylistSource, /allow/)
   assert.doesNotMatch(clientSource, /allowText|section\.allow/)
-  assert.doesNotMatch(executorSource, /current\.allow|patch\.allow/)
+  assert.doesNotMatch(webRoutesSource, /current\.allow|patch\.allow/)
 })
 
-test('updateConfig 携带 deny(wholesale replace 防静默重置,同 login 教训)', () => {
-  assert.match(executorSource, /deny: Array\.isArray\(patch\.deny\) \? patch\.deny : current\.deny/)
-  assert.doesNotMatch(executorSource, /patch\.allow/)
+test('updateConfig 携带 deny(wholesale replace 防静默重置,同 login 教训;写路径在 web 行)', () => {
+  assert.match(webRoutesSource, /deny: Array\.isArray\(patch\.deny\) \? patch\.deny : current\.deny/)
+  assert.doesNotMatch(webRoutesSource, /patch\.allow/)
 })

package/test/executor-seam.test.mjs

@@ -1,4 +1,4 @@
-// executor 官方 seam 集成(桩 ctx):BDD 场景见本文件与 README「官方工具兼容」。
+// executor 官方 seam 集成(桩 ctx):BDD 场景见本文件与 README「官方工具兼容」。
 // 背景:preset 注入的官方 tool-pwsh 经 cordis 服务代理(ctx.shell)调用执行器,
 // 代理把方法 this 重定向到阴影对象;执行器公开面必须与官方 PwshLocalExecutor
 // 同构地使用公有字段/方法(#私有在阴影 receiver 下触发品牌检查错误)。
@@ -6,7 +6,7 @@
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
 import ShellSelectExecutor from '../src/executor.mjs'
-import { Config } from '../src/config.mjs'
+import { resolveConfig } from '../src/config.mjs'
 
 function stubReader(text) {
   return { readFrom: () => ({ text, lossy: false, nextOffset: text.length }) }
@@ -33,7 +33,7 @@ function stubCtx({ sandboxMode = 'danger-full-access', spawn = stubSpawn() } = {
   const settingsImpl = {
     installSection: (ctx, ns, schema, base, hooks) => {
       registered.sections.push({ ns, schema, base, hooks })
-      settingsImpl._source = () => Config(base ?? {})
+      settingsImpl._source = () => resolveConfig(base ?? {})
     },
   }
   const ctx = {

package/test/executor.test.mjs

@@ -3,8 +3,8 @@
 
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
-import ShellSelectExecutor, { assertServiceableConfig } from '../src/executor.mjs'
-import { Config } from '../src/config.mjs'
+import ShellSelectExecutor from '../src/executor.mjs'
+import { resolveConfig, assertServiceableConfig } from '../src/config.mjs'
 
 // --- 桩具 ---
 
@@ -29,18 +29,14 @@ function stubSpawn(stdoutText = '', stderrText = '', exitCode = 0) {
 }
 
 function stubCtx({ withSettings = true, sandboxMode = 'danger-full-access', spawn = stubSpawn() } = {}) {
-  const registered = { tools: [], sections: [], promptSections: [], routes: [] }
+  const registered = { tools: [], sections: [], promptSections: [], routes: [], policies: [] }
   const settingsImpl = {
-    installSection: (ctx, ns, schema, base, hooks) => {
-      registered.sections.push({ ns, schema, base, hooks })
-      settingsImpl._source = () => Config(base ?? {})
-    },
-    update: (ns, patch) => {
-      settingsImpl._patch = { ns, patch }
-      registered.sections[0].hooks.onChange()
+    configure: (presentation, fiber) => {
+      registered.policies.push({ presentation, fiber })
     },
   }
   const disposers = []
+  const childEffects = []
   const ctx = {
     // cordis Service 基类构造期要求 reflect.provide(登记服务实例),桩空转
     reflect: { provide: () => {} },
@@ -51,6 +47,18 @@ function stubCtx({ withSettings = true, sandboxMode = 'danger-full-access', spaw
       }
       return undefined
     },
+    // 可选子级注入(设置页策略形态):子级立即执行,effect 收集待验
+    inject(services, fn) {
+      const child = {
+        settings: withSettings ? settingsImpl : undefined,
+        effect: (effectFn) => {
+          const disposer = effectFn()
+          childEffects.push(disposer)
+          return disposer
+        },
+      }
+      fn(child)
+    },
     subprocess: spawn,
     sandbox: {
       confine: (argv, policy) => ({
@@ -84,6 +92,7 @@ function stubCtx({ withSettings = true, sandboxMode = 'danger-full-access', spaw
       disposers.push(disposer)
       return disposer
     },
+    _childEffects: childEffects,
   }
   return { ctx, registered, disposers }
 }
@@ -110,24 +119,49 @@ function build() {
 
 // --- 断言 ---
 
-test('构造:注册 shell 工具、systemPrompt 段、shell-select 设置节、三条路由(config 双方法单注册)', () => {
+test('构造:注册 shell+pwsh 双工具与 systemPrompt 段,路由不再由主行挂载', () => {
   const { registered } = build()
-  assert.equal(registered.tools.length, 1)
-  assert.equal(registered.tools[0].name, 'shell')
-  assert.match(registered.tools[0].description, /git-bash/)
+  assert.deepEqual(registered.tools.map((tool) => tool.name).sort(), ['pwsh', 'shell'])
+  const shell = registered.tools.find((tool) => tool.name === 'shell')
+  const pwsh = registered.tools.find((tool) => tool.name === 'pwsh')
+  assert.match(shell.description, /git-bash/)
+  assert.match(pwsh.description, /PowerShell/)
+  assert.ok(!('shell' in pwsh.parameters.properties))
+  assert.ok('shell' in shell.parameters.properties)
   assert.equal(registered.promptSections.length, 1)
-  assert.equal(registered.sections[0].ns, 'shell-select')
-  // exact 路由 path 为唯一键:config/probe/detect 三条,GET/POST 分流在 handler 内
-  const routePaths = registered.routes.filter((path) => path.startsWith('/api/shell-select/'))
-  assert.equal(routePaths.length, 3)
-  assert.equal(new Set(routePaths).size, 3)
+  // 数据通道迁至 web-routes 行:主行零路由
+  const routePaths = registered.routes.filter((path) => String(path).startsWith('/api/shell-select/'))
+  assert.equal(routePaths.length, 0)
 })
 
-test('settings 缺席:降级不 installSection,工具照常注册', () => {
+test('settings 在场:注册 auto:false 页面策略挂本行 fiber(自带设置页,官方同构)', () => {
+  const { ctx, registered } = stubCtx()
+  const fiber = { id: 'fiber-1' }
+  ctx.fiber = fiber
+  new ShellSelectExecutor(ctx, baseConfig())
+  assert.equal(registered.policies.length, 1)
+  assert.deepEqual(registered.policies[0].presentation, { auto: false })
+  assert.equal(registered.policies[0].fiber, fiber)
+})
+
+test('settings 缺席:策略静默跳过,双工具照常注册(业务插件无 settings 也可运行)', () => {
   const { ctx, registered } = stubCtx({ withSettings: false })
   new ShellSelectExecutor(ctx, baseConfig())
-  assert.equal(registered.sections.length, 0)
-  assert.equal(registered.tools.length, 1)
+  assert.equal(registered.policies.length, 0)
+  assert.equal(registered.tools.length, 2)
+})
+
+test('pwsh 工具钉死 pwsh 客户端:default 漂移不改变落点(旧会话语义保真)', async () => {
+  const spawn = stubSpawn('ok', '', 0)
+  const { ctx, registered } = stubCtx({ spawn })
+  const executor = new ShellSelectExecutor(ctx, baseConfig())
+  const pwshTool = registered.tools.find((tool) => tool.name === 'pwsh')
+  // 模型无 shell 参数可传(pinned 工具),default 漂到 git-bash 也不影响
+  executor.refresh({ shells: baseConfig().shells, default: 'git-bash' })
+  await pwshTool.execute({ command: 'Get-Date', description: 'probe', workdir: process.cwd() }, { signal: new AbortController().signal })
+  assert.equal(spawn.calls[0].argv[0], NODE_EXE)
+  assert.match(spawn.calls[0].argv.at(-1), /Get-Date$/)
+  assert.deepEqual(spawn.calls[0].argv.slice(1, 5), ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command'])
 })
 
 test('listShells:出厂条目自动解析为真实路径(pwsh/cmd 必在本机)', () => {
@@ -223,102 +257,6 @@ test('runFor pwsh 条目:非交互形 + 编码前缀进 argv', async () => {
   assert.match(argv[5], /OutputEncoding/)
 })
 
-test('settings.update 触发 onChange:工具重注册且描述更新', () => {
-  const { executor, registered } = stubCtxAndBuild()
-  const before = registered.tools.length
-  assert.ok(before >= 1)
-  registered.sections[0].hooks.onChange()
-  assert.ok(registered.tools.length >= 1)
-})
-
-test('updateConfig:await settings.update 后读数即新值(setSource 接线)', async () => {
-  const { ctx, registered } = stubCtx()
-  // 桩 settings:installSection 后 setSource 接 scope;replace wholesale 后 setSource 到新值
-  const scope = { value: Config({}) }
-  registered.sectionsHook = null
-  ctx.settings.installSection = (ctx2, ns, schema, base, hooks) => {
-    registered.sections.push({ ns, schema, base, hooks })
-    scope.value = Config(base ?? {})
-    hooks.setSource(() => scope.value)
-    registered.sectionsHook = hooks
-  }
-  ctx.settings.replace = async (ns, section) => {
-    scope.value = Config(section)
-    registered.sectionsHook.onChange()
-  }
-  const executor = new ShellSelectExecutor(ctx, baseConfig())
-  assert.equal(executor.config.default, 'pwsh')
-  await executor.updateConfig({ default: 'git-bash' })
-  assert.equal(executor.config.default, 'git-bash')
-  assert.equal(executor.listShells().default, 'git-bash')
-})
-
-test('updateConfig:部分补丁归并当前节后 replace(单改 default 不丢 shells)', async () => {
-  const { ctx, registered } = stubCtx()
-  const written = []
-  ctx.settings.replace = async (ns, section) => {
-    written.push(section)
-  }
-  const executor = new ShellSelectExecutor(ctx, baseConfig())
-  await executor.updateConfig({ default: 'git-bash' })
-  assert.equal(written[0].shells.length, 3)
-  assert.equal(written[0].default, 'git-bash')
-})
-
-test('api POST config:await updateConfig,resolved 即新清单(async 修复)', async () => {
-  const { ctx, registered } = stubCtx()
-  ctx.get = (service) => {
-    if (service === 'webServer') {
-      const routes = []
-      ctx.__routes = routes
-      return { register: (item) => routes.push(item) }
-    }
-    return undefined
-  }
-  ctx.settings.replace = async (ns, section) => {
-    registered.sections[0].hooks.setSource(() => section)
-    registered.sections[0].hooks.onChange()
-  }
-  const executor = new ShellSelectExecutor(ctx, baseConfig())
-  const handler = ctx.__routes.find((r) => r.path === '/api/shell-select/config').handler
-  let captured = null
-  const fakeRes = {
-    writeHead: () => {},
-    end: (body) => {
-      captured = JSON.parse(body)
-    },
-  }
-  const body = JSON.stringify({ default: 'git-bash', shells: executor.config.shells })
-  const fakeReq = {
-    method: 'POST',
-    headers: { origin: 'http://127.0.0.1:9191', host: '127.0.0.1:9191' },
-    on(event, cb) {
-      if (event === 'data') setImmediate(() => cb(Buffer.from(body)))
-      if (event === 'end') setImmediate(cb)
-    },
-    destroy: () => {},
-  }
-  await handler(fakeReq, fakeRes)
-  assert.equal(captured.ok, true)
-  assert.equal(captured.resolved.default, 'git-bash')
-  assert.equal(captured.resolved.shells.length, 3)
-})
-
-test('updateConfig:入参 path 反斜杠归一(防 yaml 无引号落盘字面翻倍)', async () => {
-  // 归一是 Windows 宿主行为(linux 无反斜杠翻倍怪癖,源码层按平台守卫)
-  if (process.platform !== 'win32') return
-  const { ctx, registered } = stubCtx()
-  const written = []
-  ctx.settings.replace = async (ns, section) => {
-    written.push(section)
-  }
-  const executor = new ShellSelectExecutor(ctx, baseConfig())
-  await executor.updateConfig({
-    shells: [{ id: 'pwsh', name: 'PowerShell', kind: 'pwsh', path: 'C:\\\\WINDOWS\\\\System32\\\\powershell.exe' }],
-  })
-  assert.equal(written[0].shells[0].path, 'C:\\WINDOWS\\System32\\powershell.exe')
-})
-
 test('entryFor:双反斜杠污染路径被归一后仍可用', () => {
   const { executor } = stubCtxAndBuild()
   const ctx2 = stubCtx()
@@ -368,9 +306,9 @@ test('startFor danger:返回进程句柄,readOutput 增量与 done 定局', asyn
 })
 
 test('assertServiceableConfig:空 shells/default 不在列/重复 id 全拒', () => {
-  assert.throws(() => assertServiceableConfig(Config({ shells: [], default: 'x' })), /shells/)
-  assert.throws(() => assertServiceableConfig(Config({ shells: [{ id: 'a', name: 'A', kind: 'bash', path: '' }], default: 'b' })), /default/)
-  assert.throws(() => assertServiceableConfig(Config({
+  assert.throws(() => assertServiceableConfig(resolveConfig({ shells: [], default: 'x' })), /shells/)
+  assert.throws(() => assertServiceableConfig(resolveConfig({ shells: [{ id: 'a', name: 'A', kind: 'bash', path: '' }], default: 'b' })), /default/)
+  assert.throws(() => assertServiceableConfig(resolveConfig({
     shells: [
       { id: 'a', name: 'A', kind: 'bash', path: '' },
       { id: 'a', name: 'A2', kind: 'cmd', path: '' },
@@ -378,3 +316,94 @@ test('assertServiceableConfig:空 shells/default 不在列/重复 id 全拒', ()
     default: 'a',
   })), /duplicate/)
 })
+
+// --- execute 官方契约(ShellExecutor 抽象方法,官方 tool-pwsh 唯一执行入口)---
+
+test('execute 契约:danger 直跑,返回句柄形态,result() 前台投影无 sandbox 键', async () => {
+  const spawn = stubSpawn('exec-out', '', 0)
+  const { ctx } = stubCtx({ spawn })
+  const executor = new ShellSelectExecutor(ctx, baseConfig())
+  const handle = await executor.execute(executor.resolve({ command: 'hi', workdir: process.cwd() }))
+  assert.ok(['running', 'completed'].includes(handle.status))
+  assert.equal(typeof handle.readOutput, 'function')
+  assert.equal(typeof handle.kill, 'function')
+  assert.equal(typeof handle.observed.stdout.readFrom, 'function')
+  const result = await handle.result()
+  assert.equal(result.exitCode, 0)
+  assert.equal(result.timedOut, false)
+  assert.equal(result.aborted, false)
+  assert.equal(result.stdout.text, 'exec-out')
+  assert.equal(result.sandbox, undefined)
+  assert.equal(spawn.calls[0].argv[0], NODE_EXE)
+  assert.match(spawn.calls[0].argv.at(-1), /hi$/)
+})
+
+test('execute 契约:onExpiry none 不武装 deadline(后台注册形态)', async () => {
+  const spawn = stubSpawn('bg', '', 0)
+  const { ctx } = stubCtx({ spawn })
+  const executor = new ShellSelectExecutor(ctx, baseConfig())
+  const handle = await executor.execute(executor.resolve({ command: 'x', workdir: process.cwd(), onExpiry: 'none' }))
+  const result = await handle.result()
+  assert.equal(result.exitCode, 0)
+  assert.equal(result.timedOut, false)
+})
+
+test('execute 契约:provider spawn 失败,done 定局 killed 不 reject,result() 携带同一失败', async () => {
+  const spawn = { spawn: () => { throw new Error('spawn exploded') } }
+  const { ctx } = stubCtx({ spawn })
+  const executor = new ShellSelectExecutor(ctx, baseConfig())
+  const handle = await executor.execute(executor.resolve({ command: 'x', workdir: process.cwd() }))
+  await handle.done
+  assert.equal(handle.status, 'killed')
+  const read = handle.readOutput()
+  assert.match(read.delta, /subprocess failed before reporting an outcome/)
+  await assert.rejects(() => handle.result(), /spawn exploded/)
+})
+
+test('execute 契约:受限模式经 confine,定案写 proc.sandbox 并入 result', async () => {
+  const spawn = stubSpawn('', 'file access denied under read-only', 1)
+  const { ctx } = stubCtx({ spawn, sandboxMode: 'read-only' })
+  const executor = new ShellSelectExecutor(ctx, baseConfig())
+  const handle = await executor.execute(executor.resolve({ command: 'dir', workdir: process.cwd() }))
+  assert.equal(spawn.calls[0].argv[0], 'WRAPPED')
+  const result = await handle.result()
+  assert.equal(result.sandbox.mode, 'read-only')
+  assert.equal(result.sandbox.denied, true)
+  assert.equal(result.sandbox.enforcement, 'full')
+})
+
+test('execute 契约:deny 命中拒绝执行,不产生句柄', async () => {
+  const spawn = stubSpawn('', '', 0)
+  const { ctx } = stubCtx({ spawn })
+  const executor = new ShellSelectExecutor(ctx, { ...baseConfig(), deny: ['rm -rf'] })
+  await assert.rejects(
+    () => executor.execute(executor.resolve({ command: 'rm -rf /', workdir: process.cwd() })),
+    (error) => error.code === 'SHELL_COMMAND_BLOCKED',
+  )
+  assert.equal(spawn.calls.length, 0)
+})
+
+test('execute 契约:默认客户端解析,显式 onExpiry kill 正常完成', async () => {
+  const spawn = stubSpawn('ok', '', 0)
+  const { ctx } = stubCtx({ spawn })
+  const executor = new ShellSelectExecutor(ctx, baseConfig())
+  const handle = await executor.execute(executor.resolve({ command: 'x', workdir: process.cwd(), onExpiry: 'kill', timeoutMs: 5000 }))
+  const result = await handle.result()
+  assert.equal(result.exitCode, 0)
+  assert.equal(result.timeoutMs, 5000)
+})
+
+test('refresh:换源后执行面即时收紧(已删 id 拒绝,新清单生效)', async () => {
+  const { ctx, registered } = stubCtx()
+  const executor = new ShellSelectExecutor(ctx, baseConfig())
+  assert.equal(executor.entryFor('cmd').id, 'cmd')
+  const toolsBefore = registered.tools.length
+  executor.refresh({
+    shells: baseConfig().shells.filter((entry) => entry.id !== 'cmd'),
+    default: 'pwsh',
+  })
+  assert.throws(() => executor.entryFor('cmd'), /cmd/)
+  assert.equal(executor.entryFor('pwsh').id, 'pwsh')
+  assert.equal(executor.entryFor(undefined).id, 'pwsh')
+  assert.equal(registered.tools.length, toolsBefore)
+})

package/test/guard-state.test.mjs

@@ -2,7 +2,7 @@
 
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
-import { detectDeadState, rowState, effectiveDisabled, MAIN_ROW_ID, OFFICIAL_ROW_IDS } from '../src/guard-state.mjs'
+import { detectDeadState, rowState, rowScan, effectiveDisabled, MAIN_ROW_ID, OFFICIAL_ROW_IDS } from '../src/guard-state.mjs'
 import { officialRowConfig } from '../src/guard-config.mjs'
 
 // --- 桩 loader / 行 ---
@@ -101,6 +101,51 @@ test('主行禁用停稳时旗标不阻断判定(行确已停,残留旗标无意
   assert.equal(detectDeadState(rows, { applyState: () => 'pending' }), true)
 })
 
+test('运行时接管常态:主行崩(pending)且官方两行启用 → 非死态(官方自服务,guard 空闲)', () => {
+  const crashed = loader([
+    row({ id: MAIN }),
+    row({ id: OFF_TOOL }),
+    row({ id: OFF_EXEC }),
+  ])
+  assert.equal(detectDeadState(crashed, { applyState: () => 'pending' }), false)
+})
+
+test('rowScan:全树枚举 pwsh 行(声明态类型/求值禁用/fiber 存活),无 root 按空', () => {
+  assert.deepEqual(rowScan({}), [])
+  assert.deepEqual(rowScan(undefined), [])
+  const entryOf = (r) => ({
+    options: { id: r.id, name: r.name ?? `@x/${r.id}`, disabled: r.rawDisabled ?? r.disabled },
+    get disabled() {
+      if (r.disabled === 'throw') throw new Error('expr eval failed')
+      return r.disabled
+    },
+    fiber: r.running ? { uid: 'f1' } : undefined,
+  })
+  const treeLoader = (rows) => ({ root: { tree: { store: Object.fromEntries(rows.map((r) => [r.id, entryOf(r)])) } } })
+  const hits = rowScan(treeLoader([
+    { id: 'tool-pwsh', disabled: true },
+    { id: 'pwsh-sandbox', rawDisabled: { expr: true }, disabled: false, running: true },
+    { id: 'shell-select', disabled: false },
+  ]))
+  assert.deepEqual(hits, [
+    { id: 'tool-pwsh', rawType: 'boolean', evalDisabled: true, running: false },
+    { id: 'pwsh-sandbox', rawType: 'object', evalDisabled: false, running: true },
+  ])
+})
+
+test('rowScan:disabled getter 抛错按 throw 标记,不中断扫描', () => {
+  const entry = (r) => ({
+    options: { id: r.id, disabled: false },
+    get disabled() {
+      throw new Error('expr eval failed')
+    },
+    fiber: undefined,
+  })
+  const treeLoader = (rows) => ({ root: { tree: { store: Object.fromEntries(rows.map((r) => [r.id, entry(r)])) } } })
+  const hits = rowScan(treeLoader([{ id: 'pwsh-sandbox' }]))
+  assert.deepEqual(hits, [{ id: 'pwsh-sandbox', rawType: 'boolean', evalDisabled: 'throw', running: false }])
+})
+
 test('officialRowConfig:读 settings.yaml shell 节,缺失返回空对象', async () => {
   const section = await officialRowConfig(async () => ({ shell: { pwshPath: 'C:\\x\\pwsh.exe' } }))
   assert.deepEqual(section, { pwshPath: 'C:\\x\\pwsh.exe' })