@mzzsfy/dsh-shell-select 0.3.1 → 0.4.0

package/src/takeover.mjs

@@ -0,0 +1,167 @@
+// 官方 pwsh 链(tool-pwsh + pwsh-sandbox)entry 生命周期探测与运行时接管。
+// 运行时接管(替代 bundle patch 静态禁行):官方两行的禁用由本包主行 apply
+// 落定后经 entry.update(dsh-market 同款调用)执行——禁用官方的前提严格强于
+// 本包可服务性,本包任意死法(模块加载崩/apply 中途崩/被禁/卸载)下官方行
+// 保持启用,官方 pwsh 链自服务,系统不出现 shell 全灭窗口。
+//
+// 接管空间的判定与 gateway(llm-pi-ai 行无 disabled 声明,undefined=默认态)
+// 不同:官方两行在 dsh-base 带平台表达式 `disabled: !!js process.platform !==
+// 'win32'`,win32 上求值 false——宿主默认启用态与「用户显式启用」在行树上
+// 不可区分。因此行级 false 不作为让位信号:凡非 true(启用中)即接管空间,
+// 用户意图通道改为「禁用本包」(market 禁主行或 user patch 禁行,重启后官方
+// 自然回归)。getter 求值抛错(宿主状态异常)仍让位安全向;非布残值同样保守
+// 让位。链式语义:禁用只更新启用中的行(0.1.7 web 面常态:tool-pwsh 被宿主
+// patch 禁用、pwsh-sandbox 平台默认启用,混合态下仅禁后者)。
+
+// 官方受控行 id 与行 id 解析前缀(guard-state 同源共享)
+import { OFFICIAL_ROW_IDS, ROW_ID_PREFIXES } from './guard-state.mjs'
+
+// 退场轮询步长与轮数上限,乘积为等待上界(guard 同源常量)
+export const EXIT_POLL_INTERVAL_MS = 20
+export const EXIT_POLL_ROUNDS = 50
+
+const ABSENT = Object.freeze({ present: false, disabled: false, running: false, entry: undefined, disabledUnreliable: false, rawDisabled: true })
+
+// 宿主 Entry.disabled getter 语义:!!js 表达式求值 + 父链回溯 + 布尔宽化,
+// 裸读 options.disabled 会漏掉表达式与非布尔真值两类禁用形态;求值抛错按
+// 未禁用处理并置 disabledUnreliable(宿主状态异常,自动动作一律让位安全向)
+function effectiveDisabled(entry) {
+  try {
+    return entry.disabled === true
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * 探测单个官方行生命周期状态。loader 缺失或行不存在按缺席处理(官方包未装
+ * 时照常接管,与「官方包缺失时本包独占」的既有降级语义一致)。disabled
+ * getter 求值抛错时 disabled=false 且 disabledUnreliable=true。rawDisabled
+ * 为 options.disabled 原始值(仅观测留档:真机形态是 !!js 表达式包装对象,
+ * 决策不消费它,启用中判定走 disabled 求值结果)。
+ * @param {object|undefined} loader 宿主 loader 服务(cordis Loader/EntryTree)
+ * @param {string} id 行 id
+ */
+export function officialRowState(loader, id) {
+  if (loader?.resolve === undefined) return ABSENT
+  let entry
+  for (const prefix of ROW_ID_PREFIXES) {
+    try {
+      const candidate = loader.resolve(prefix + id)
+      if (candidate) {
+        entry = candidate
+        break
+      }
+    } catch {
+      // 该命名空间无此行,试下一前缀
+    }
+  }
+  if (!entry) return ABSENT
+  const disabled = effectiveDisabled(entry)
+  let rawDisabled
+  try {
+    rawDisabled = entry.options?.disabled
+  } catch {
+    rawDisabled = undefined
+  }
+  return {
+    present: true,
+    disabled: disabled === true,
+    running: entry.fiber?.uid != null,
+    entry,
+    disabledUnreliable: disabled === undefined,
+    rawDisabled,
+  }
+}
+
+/**
+ * 官方双行状态快照(id → 行状态,键序与 OFFICIAL_ROW_IDS 一致)。
+ * @param {object|undefined} loader
+ */
+export function officialChainState(loader) {
+  return Object.fromEntries(OFFICIAL_ROW_IDS.map((id) => [id, officialRowState(loader, id)]))
+}
+
+/**
+ * 接管决策(链为单位):任一行 getter 求值不可信 → 让位安全向;全部已禁停稳
+ * → 接管;禁用但在退场 → 等待;存在启用中的行(getter 求值 false:平台默认
+ * 与无声明同形,同为接管空间)→ runtime-disable,仅禁启用中的行。注意
+ * options.disabled 原始值可能是 !!js 表达式包装对象(真机实证,非求值布尔),
+ * 启用中判定必须走 entry.disabled getter 求值结果,不读原始值。行缺席视为
+ * 已禁(不参与 update),全缺席 = 官方包未装 = 直接接管。
+ * @param {Record<string, object>} states officialChainState 快照
+ * @returns {{ decision: 'takeover'|'await-exit'|'yield'|'runtime-disable', targets: object[] }}
+ *   targets = runtime-disable 时需 update 的 entry 清单,其余态为空
+ */
+export function takeoverDecision(states) {
+  const rows = OFFICIAL_ROW_IDS.map((id) => states[id] ?? ABSENT)
+  if (rows.some((row) => row.present && row.disabledUnreliable)) return { decision: 'yield', targets: [] }
+  const targets = rows.filter((row) => row.present && row.disabled !== true).map((row) => row.entry)
+  if (targets.length > 0) return { decision: 'runtime-disable', targets }
+  const exiting = rows.some((row) => row.present && row.running)
+  return { decision: exiting ? 'await-exit' : 'takeover', targets: [] }
+}
+
+/**
+ * 运行时禁用一批官方行:dsh-market toggle 同款调用(force update,穿透
+ * 「init 在途时 options 翻转但收尾 init 仍拉起 fiber」的空 diff 形态)。
+ * 逐行独立执行,单行失败不中止其余行;调用方据失败清单决定回滚。
+ * 纯内存态不持久:重启后官方行回归行树声明态,由下一轮 apply 收敛。
+ * @param {object[]} entries 官方 loader entry 清单
+ * @param {{quiet?: boolean, force?: boolean}} [options]
+ * @returns {Promise<{disabled: object[], failed: object[]}>}
+ */
+export async function runtimeDisableRows(entries, { quiet = false, force = true } = {}) {
+  const disabled = []
+  const failed = []
+  for (const entry of entries) {
+    try {
+      await entry.update({ disabled: true }, quiet, force)
+      disabled.push(entry)
+    } catch {
+      failed.push(entry)
+    }
+  }
+  return { disabled, failed }
+}
+
+/**
+ * 回滚:重新启用已禁的官方行(update {disabled:false}),官方链复活。
+ * 仅在接管序列失败路径调用;quiet 减噪(失败路径已另行告警),逐行独立,
+ * 失败不抛(重启后行树声明态自然归位)。
+ * @param {object[]} entries
+ */
+export async function rollbackDisabledRows(entries) {
+  for (const entry of entries) {
+    try {
+      await entry.update({ disabled: false }, true, true)
+    } catch {
+      // 回滚失败不抛:重启收敛
+    }
+  }
+}
+
+const defaultDelay = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+
+/**
+ * 有界等待官方行退场(fiber 清)。dispose 为纯内存操作毫秒级完成,轮询上界
+ * 仅防御异常宿主状态。fiber 清空后官方注册的撤销还在卸载收尾(微任务批)中
+ * 完成,返回前补一轮间隔让收尾落定,避免挂载执行器时与官方未撤完的 ctx.shell
+ * 注册交错(cordis 重复 provide 抛错)。
+ * @param {object[]} entries 官方 loader entry 清单
+ * @param {{intervalMs?: number, rounds?: number, delay?: (ms: number) => Promise<void>}} [options]
+ * @returns {Promise<boolean>} true = 已全部退场;false = 轮询耗尽仍有在场
+ */
+export async function awaitOfficialExit(entries, {
+  intervalMs = EXIT_POLL_INTERVAL_MS,
+  rounds = EXIT_POLL_ROUNDS,
+  delay = defaultDelay,
+} = {}) {
+  const stillRunning = () => entries.some((entry) => entry.fiber?.uid != null)
+  for (let round = 0; round < rounds && stillRunning(); round += 1) {
+    await delay(intervalMs)
+  }
+  if (stillRunning()) return false
+  await delay(intervalMs)
+  return true
+}

package/src/tool.mjs

@@ -3,6 +3,10 @@
 // 2. 描述动态含可用客户端清单与方言提示(settings onChange 重注册);
 // 3. 执行经 executor.entryFor/runFor/startFor 按条目 argv 运行。
 // 输出 schema、后台任务语义、升权流程、terminal 卡呈现与官方逐字同构。
+// 另注册 pwsh 名字工具(镜像官方定义,钉死 pwsh 客户端):旧会话 preset
+// 快照里的 pwsh 工具语义是"PowerShell 专用",缺省落 config.default 会随
+// 用户改默认客户端而炸方言;本注册给新会话提供同名工具保语义,模型点名
+// pwsh 时永远 PowerShell。
 
 import { TOOL_ABORTED, defineTool } from '@deepseek-ai/dsh-tools'
 import { ESCALATION_TARGETS, approveEscalation, validateEscalationArgs } from '@deepseek-ai/dsh-sandbox'
@@ -135,8 +139,23 @@ function shellDescription({ executor, backgroundEnabled, escalationModes }) {
   return base + ' Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. When a command is denied and a wider mode would let it succeed, escalate immediately in the same turn: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Never escalate speculatively: ground the request in a real denial. If the session states approval prompts are disabled, a denial is final — do not set `sandbox_permissions`.'
 }
 
+/** pwsh 工具描述:兼容保留工具,开头一句禁止调用。 */
+function pwshDescription({ backgroundEnabled, escalationModes }) {
+  const base = 'Do not call this tool. It is kept only for backward compatibility with old sessions — call the `shell` tool instead. '
+    + 'It executes a PowerShell command and returns its stdout/stderr. '
+    + 'Each call runs in a fresh pwsh process: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. '
+    + 'Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed environment variables (`DSH_*`); inspect them when needed. '
+    + 'Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. '
+    + (backgroundEnabled
+      ? 'Set `run_in_background: true` for long-running commands: the call returns a job id immediately; read its output with `job_output` and stop it with `job_kill`.'
+      : 'Background execution is not available; long-running commands must finish within the timeout.')
+  if (escalationModes.length === 0) return base
+  return base + ' Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. When a command is denied and a wider mode would let it succeed, escalate immediately in the same turn: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Never escalate speculatively: ground the request in a real denial. If the session states approval prompts are disabled, a denial is final — do not set `sandbox_permissions`.'
+}
+
 /**
- * 注册 shell 工具,返回卸载 disposer(重注册 = 先卸后挂)。
+ * 注册 shell + pwsh 双工具,返回卸载 disposer(重注册 = 先卸后挂)。
+ * pwsh 工具钉死 pwsh 客户端(config 删 pwsh 条目时 requireEntry 明确拒绝)。
  * @param {object} ctx cordis context(需 tools/shellEnv 服务在场)
  * @param {{executor: object}} faces 执行器实例
  */
@@ -166,24 +185,28 @@ export function registerShellTool(ctx, { executor }) {
     validateEscalationArgs(args.sandbox_permissions, args.justification)
   }
 
-  const definition = (faces) => defineTool({
-    name: 'shell',
-    description: shellDescription({ executor: faces.executor, backgroundEnabled, escalationModes }),
+  const makeDefinition = (toolName, pinned) => (faces) => defineTool({
+    name: toolName,
+    description: pinned === undefined
+      ? shellDescription({ executor: faces.executor, backgroundEnabled, escalationModes })
+      : pwshDescription({ backgroundEnabled, escalationModes }),
     parameters: {
       command: {
         type: 'string',
         required: true,
-        description: 'The command to execute, in the dialect of the selected shell client (default client when `shell` is omitted).',
+        description: pinned === undefined
+          ? 'The command to execute, in the dialect of the selected shell client (default client when `shell` is omitted).'
+          : 'The PowerShell command to execute.',
       },
       description: {
         type: 'string',
         required: true,
         description: 'Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI).',
       },
-      shell: {
+      ...pinned === undefined ? { shell: {
         type: 'string',
         description: 'Shell client id from the tool description list (e.g. pwsh, git-bash, cmd). Omit to use the configured default client.',
-      },
+      } } : {},
       timeoutMs: {
         type: 'number',
         description: 'Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry.',
@@ -227,11 +250,11 @@ export function registerShellTool(ctx, { executor }) {
       validateArgs(args)
       const standingPolicy = resolveStandingPolicy(exec)
       const approvedMode = args.sandbox_permissions !== undefined && args.justification !== undefined
-        ? await approveShellEscalation(args.sandbox_permissions, args.justification, exec, standingPolicy)
+        ? await approveShellEscalation(toolName, args.sandbox_permissions, args.justification, exec, standingPolicy)
         : undefined
       const policy = approvedMode === undefined ? standingPolicy : { ...standingPolicy, mode: approvedMode }
       const workdir = resolveWorkdir(args.workdir, exec)
-      const entry = faces.executor.entryFor(args.shell)
+      const entry = faces.executor.entryFor(pinned ?? args.shell)
       const request = {
         command: args.command,
         ...workdir !== undefined ? { workdir } : {},
@@ -323,7 +346,7 @@ export function registerShellTool(ctx, { executor }) {
   }
 
   /** 升权审批:先于执行,共享 fail-closed 序列交 approveEscalation(官方同构)。 */
-  function approveShellEscalation(mode, justification, exec, standingPolicy) {
+  function approveShellEscalation(toolName, mode, justification, exec, standingPolicy) {
     if (escalationModes.length === 0) throw new Error('sandbox_permissions is not available in this composition (no sandboxing executor to escalate)')
     const approver = ctx.get('approval')
     return approveEscalation({
@@ -335,16 +358,19 @@ export function registerShellTool(ctx, { executor }) {
       approver,
       agent: exec.agent,
       callId: exec.callId,
-      toolName: 'shell',
+      toolName,
       signal: exec.signal,
     })
   }
 
   const faces = { executor }
-  const disposer = ctx.tools.register(definition(faces))
+  const disposers = [
+    ctx.tools.register(makeDefinition('shell', undefined)(faces)),
+    ctx.tools.register(makeDefinition('pwsh', 'pwsh')(faces)),
+  ]
   return () => {
     if (disposed) return
     disposed = true
-    disposer()
+    for (const disposer of disposers) disposer()
   }
 }

package/src/web-routes.mjs

@@ -0,0 +1,91 @@
+// shell-select web 路由行:设置页数据通道(inject 声明式门控,webServer/settings
+// 就绪才激活——主行一次性同步探测的时序竞态即 0.1.7 设置页 404 事故根因)。
+// faces 不依赖执行器实例:配置事实源 = 行 Config(0.1.7 settings 面以 profile
+// 条目 id 为 ns,行 Config 即设置存储,变更经 cordis 行重载活生效),读经
+// settings.describe,写经 settings.replace;探测/扫描用 resolve 纯函数。
+// HTTP 形态(具名 exact 路由 + 跨源守卫 + 业务异常归一 400)照 dsh-maintain。
+
+import { KINDS, resolveConfig, assertServiceableConfig, normalizeConfigPaths, normalizeWin32Path } from './config.mjs'
+import { candidateExists, detectCandidates, resolveEntryPath } from './resolve.mjs'
+import { requestShellRefresh } from './executor.mjs'
+import { mountRoutes } from './api.mjs'
+
+export const name = 'shell-select/web'
+
+export const inject = ['webServer', 'settings']
+
+// 设置节命名空间 = 本包主行在组合树中的条目 id(cordis.patch.yml insert id)
+export const SECTION_NS = 'shell-select'
+
+/** 会话可见清单:条目 + 解析后的真实路径与可用性(与主行 listShells 同构)。 */
+function listShellsOf(section) {
+  return {
+    default: section.default,
+    shells: section.shells.map((entry) => {
+      const resolved = normalizeWin32Path(resolveEntryPath(entry, candidateExists))
+      return {
+        id: entry.id,
+        kind: entry.kind,
+        args: entry.args,
+        path: resolved,
+        available: resolved !== undefined,
+        login: entry.login === true,
+        distro: entry.distro ?? '',
+        env: entry.env ?? {},
+      }
+    }),
+  }
+}
+
+/**
+ * 从 settings describe 投影当前节:目标 ns 缺失(主行未挂/旧宿主形态)时
+ * 回落出厂默认并告警,读路径不崩。
+ */
+function readSection(ctx, settings) {
+  const found = (typeof settings.describe === 'function' ? settings.describe() : [])
+    .find((descriptor) => descriptor.ns === SECTION_NS)
+  if (found === undefined) {
+    ctx.logger?.warn?.(`shell-select: settings 面无 "${SECTION_NS}" 节,设置页回落出厂默认`)
+    return resolveConfig({})
+  }
+  return resolveConfig(found.value ?? {})
+}
+
+/**
+ * 设置页 faces:HTTP 层(api.mjs)与配置事实源(settings 行条目)的适配。
+ * @param {{logger?: {warn?: Function}}} ctx 行上下文(告警通道)
+ * @param settings 宿主 settings 服务(describe/replace)
+ */
+export function buildFaces(ctx, settings) {
+  const readCurrent = () => readSection(ctx, settings)
+  return {
+    readConfig: () => readCurrent(),
+    listShells: () => listShellsOf(readCurrent()),
+    // replace 落盘后经模块级桥刷新执行面:执行器 provide 的 ctx.shell 作用域
+    // 在主行子树,本行是兄弟行够不着(cordis 服务不横向查找,getter 直接
+    // throw);cordis 对 volatile-only diff 换 ref 不重挂行,执行器手里的
+    // 挂载快照就此陈旧——replace 成功即权威信号,桥调活跃实例换源并重建
+    // 工具注册(原生设置页对本行被 auto:false 抑制,本 API 是唯一写口)
+    async updateConfig(patch) {
+      const current = readCurrent()
+      const section = normalizeConfigPaths({
+        ...current,
+        shells: patch.shells ?? current.shells,
+        default: patch.default ?? current.default,
+        deny: Array.isArray(patch.deny) ? patch.deny : current.deny,
+      })
+      const validated = resolveConfig(section)
+      assertServiceableConfig(validated)
+      await settings.replace(SECTION_NS, section)
+      requestShellRefresh(validated)
+      return listShellsOf(validated)
+    },
+    detect: (kinds) => detectCandidates(kinds ?? [...KINDS], process.env, candidateExists),
+    probe: (candidatePath) => candidateExists(candidatePath),
+  }
+}
+
+/** 行入口:webServer/settings 已由 inject 门控就绪。 */
+export function apply(ctx) {
+  mountRoutes(ctx, buildFaces(ctx, ctx.get('settings')))
+}

package/test/client-card.test.mjs

@@ -34,6 +34,16 @@ function parseEnvText() {
   return extractLogic('parseEnvText')
 }
 
+test('运行时长格式:秒→m:ss,一小时以上→h:mm:ss,负值钳 0', () => {
+  const formatDuration = extractLogic('formatDuration')
+  assert.equal(formatDuration(0), '0:00')
+  assert.equal(formatDuration(42_000), '0:42')
+  assert.equal(formatDuration(61_000), '1:01')
+  assert.equal(formatDuration(3600_000), '1:00:00')
+  assert.equal(formatDuration(3661_000), '1:01:01')
+  assert.equal(formatDuration(-5), '0:00')
+})
+
 function invalidEnvLines() {
   return extractLogic('invalidEnvLines')
 }
@@ -57,10 +67,11 @@ function settledBlock(argsRaw, text, options = {}) {
 const ARGS = JSON.stringify({ command: 'git status', description: 'Show working tree status', workdir: 'sub' })
 const SESSION_CWD = 'C:\\repo'
 
-test('S11 running 且无 description(persistent 形)回退 generic', () => {
+test('S11 running 且无 description(persistent 形):全量卡不回退(阻塞时展开必有命令)', () => {
   const model = cardModel()(runningBlock(JSON.stringify({ command: 'interactive session' })), SESSION_CWD)
-  assert.equal(model.kind, 'generic')
-  assert.equal(model.running, true)
+  assert.equal(model.kind, 'terminal')
+  assert.equal(model.status, 'running')
+  assert.equal(model.description, undefined)
 })
 
 test('S11b settled 无 description(persistent 结束)回退 generic', () => {

package/test/client-render.test.mjs

@@ -0,0 +1,170 @@
+// 渲染守卫:全量执行 client.js 工厂(React 桩),实际调用注册出的 toolview
+// 组件——纯文本/LOGIC 提取守卫抓不住的渲染期未定义引用(model 丢失事故)在此暴露。
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const source = readFileSync(join(here, '..', 'src', 'client.js'), 'utf8')
+
+function reactStub() {
+  // 函数组件即时执行(模拟渲染语义):组件体内的未定义引用/坏访问当场抛出
+  const createElement = (type, props, ...children) => {
+    if (typeof type === 'function') return type(props ?? {})
+    return { type, props, children }
+  }
+  return {
+    createElement,
+    useState: (init) => [typeof init === 'function' ? init() : init, () => {}],
+    useEffect: () => {},
+  }
+}
+
+// 加载 client.js 并执行 apply,返回 slots 注册面
+function loadClient() {
+  const React = reactStub()
+  const registrations = []
+  const slots = {
+    inject: (_name, factory) => factory(),
+    register: (meta, component) => registrations.push({ meta, component }),
+  }
+  const document = {
+    documentElement: { lang: 'zh-CN' },
+    createElement: () => ({ setAttribute: () => {}, remove: () => {}, style: {} }),
+    head: { appendChild: () => {} },
+  }
+  let loaded
+  const window = { __ModuleLoader__: { load: (definition) => { loaded = definition } } }
+  new Function('window', 'document', 'navigator', source)(window, document, {}, undefined)
+  assert.notEqual(loaded, undefined, 'client.js 未调用 __ModuleLoader__.load')
+  const ctx = {
+    effect(fn) {
+      return fn()
+    },
+    slots,
+  }
+  loaded.factory((name) => {
+    if (name === 'react') return React
+    // 其余模块(primitives 等)按缺席处理:抛错触发 client 内 try/catch 降级
+    throw new Error('module not available: ' + name)
+  }).apply(ctx)
+  return registrations
+}
+
+function toolviewOf(registrations, key) {
+  const view = registrations.find((item) => item.meta.name === 'tool.call.toolview' && item.meta.key === key)
+  assert.notEqual(view, undefined, `缺少 key=${key} 的 toolview 注册`)
+  return view.component
+}
+
+// 已定调用块(官方形态:kind 字段在)
+function settledBlock(argsRaw, text) {
+  return {
+    kind: 'tool',
+    callId: 'c1',
+    call: { callId: 'c1', name: 'shell', argsRaw },
+    content: [{ type: 'text', text }],
+  }
+}
+
+test('渲染守卫:settled terminal 调用组件执行不抛(引用完整)', () => {
+  const component = toolviewOf(loadClient(), 'shell')
+  const element = component({
+    block: settledBlock(JSON.stringify({ command: 'git status', description: 'status' }), 'On branch main\n[exit code: 0]'),
+    cwd: 'C:\\repo',
+  })
+  assert.notEqual(element, undefined)
+})
+
+test('渲染守卫:running 块组件执行不抛', () => {
+  const component = toolviewOf(loadClient(), 'pwsh')
+  const element = component({
+    block: { callId: 'c2', name: 'pwsh', argsRaw: JSON.stringify({ command: 'Start-Sleep 1', description: 'wait' }), time: Date.now() - 65_000 },
+    cwd: 'C:\\repo',
+  })
+  assert.notEqual(element, undefined)
+})
+
+test('渲染守卫:运行中卡展开后可见命令全文与实时时长', () => {
+  const component = toolviewOf(loadClient(), 'shell')
+  // 默认收起:运行中折叠行 = 黄点 + 描述 + 时长,不含卡体
+  const element = component({
+    block: { callId: 'c3', name: 'shell', argsRaw: JSON.stringify({ command: 'npm run build', description: 'build' }), time: Date.now() - 65_000 },
+    cwd: 'C:\\repo',
+  })
+  assert.doesNotMatch(JSON.stringify(element), /sls-tv__body/)
+  assert.match(JSON.stringify(element), /1:05/)
+})
+
+test('渲染守卫:后台 ack 块(默认收起行 + 任务号徽标)组件执行不抛', () => {
+  const component = toolviewOf(loadClient(), 'bash')
+  const element = component({
+    block: settledBlock(JSON.stringify({ command: 'npm test', description: 'tests', run_in_background: true }), 'started background job bg-1'),
+    cwd: 'C:\\repo',
+  })
+  assert.notEqual(element, undefined)
+})
+
+test('设置卡注册:settings.section 单卡 id shell-select', () => {
+  const registrations = loadClient()
+  const card = registrations.find((item) => item.meta.name === 'settings.section')
+  assert.notEqual(card, undefined)
+  assert.equal(card.meta.id, 'shell-select')
+})
+
+test('图标名守卫:0.1.7 primitives 字重后缀名在场,尺寸后缀旧名不在首选位', () => {
+  // 0.1.7 图标改名:尺寸从名字移除(IconApiOutline14 → IconApiOutlineRegular/Medium),
+  // 旧名 miss 使 IconApi 落淡灰 fallback 被当成"空白 icon"(实测事故)
+  assert.match(source, /'IconApiOutlineRegular'/)
+  assert.match(source, /'IconChevronDownOutlineRegular'/)
+  assert.match(source, /'IconInspectOutlineRegular'/)
+  assert.doesNotMatch(source, /createElementOf\('IconApiOutline14'/)
+})
+
+test('名册单飞守卫:失败复位 promise,下次渲染重试(宿主启动窗口 404 不永久缺徽章)', () => {
+  // 旧实现 catch 静默吞错且 promise 不复位:boot 窗口期 404 后所有卡永久缺客户端徽章
+  assert.doesNotMatch(source, /catch\(\(\) => \{ \}\)/)
+  assert.match(source, /clientCatalogPromise = null/)
+})
+
+test('后台卡头部守卫:状态点缺省渲染(bg pill 即标识),非法 StateDot state 不再传入', () => {
+  // StateDot 合法 state 仅 done/warning/ongoing/error/idle;'none' 是编造值
+  assert.match(source, /dot: undefined/)
+  assert.match(source, /meta\.dot !== undefined \? TOOLVIEW_ICONS\.StateDot/)
+  assert.doesNotMatch(source, /dot: 'none'/)
+})
+
+test('hooks 恒序守卫:组件内 hook 调用必须全部位于第一个提前 return 之前', () => {
+  // 真实 React 的 hooks 链表按调用序对位:提前 return 之后的 hook 使不同
+  // 块形态(generic/terminal)的 hook 数量分叉 → "Rendered fewer hooks
+  // than expected" → 行组件树整棵卸载(shell 卡全消失事故)。React 桩无
+  // hooks 链表,渲染守卫抓不住,必须源码结构断言。
+  const extract = (name) => {
+    const begin = source.indexOf(`function ${name}(`)
+    assert.ok(begin >= 0, `缺函数 ${name}`)
+    const beginLine = source.slice(0, begin).split('\n').length
+    const body = source.slice(begin)
+    const end = body.indexOf('\n    function ', 1)
+    const scope = end >= 0 ? body.slice(0, end) : body
+    const hookLines = [...scope.matchAll(/\b(?:useState|useEffect|useRef|useMemo|useCallback)\(/g)]
+      .map((m) => beginLine + scope.slice(0, m.index).split('\n').length - 1)
+    return { hookLines, scopeLines: beginLine + scope.split('\n').length }
+  }
+  const earlyReturnLine = (scope, beginLine) => {
+    const m = /return h\(/.exec(scope)
+    return m === null ? Number.POSITIVE_INFINITY : beginLine + scope.slice(0, m.index).split('\n').length - 1
+  }
+  for (const name of ['ShellToolRow', 'GenericShellRow', 'CopyButton', 'RunningDuration', 'ShellSelectApp']) {
+    const { hookLines } = extract(name)
+    const scopeBody = source.slice(source.indexOf(`function ${name}(`))
+    const end = scopeBody.indexOf('\n    function ', 1)
+    const scope = end >= 0 ? scopeBody.slice(0, end) : scopeBody
+    const limit = earlyReturnLine(scope, source.slice(0, source.indexOf(`function ${name}(`)).split('\n').length)
+    for (const line of hookLines) {
+      assert.ok(line < limit, `${name} 的 hook 在第 ${line} 行,位于提前 return(第 ${limit} 行)之后:hooks 恒序被破坏`)
+    }
+  }
+})

package/test/config-entry.test.mjs

@@ -1,12 +1,12 @@
-// 条目级 env 与 wsl distro:schema 默认、argv 形、entryFor 透传。BDD 场景见 docs/feat-shell-select-optim/plan.md S5-S10。
+// 条目级 env 与 wsl distro:schema 默认、argv 形、entryFor 透传。BDD 场景见 docs/feat-shell-select-optim/plan.md S5-S10。
 
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
 import ShellSelectExecutor from '../src/executor.mjs'
-import { Config, buildArgv, defaultConfig } from '../src/config.mjs'
+import { resolveConfig, buildArgv, defaultConfig, entryById, requireEntry } from '../src/config.mjs'
 
 test('S5 schema 默认:条目 env 空对象、distro 空串,旧配置反序列化补默认', () => {
-  const config = Config({ shells: [{ id: 'w', name: 'WSL', kind: 'wsl' }], default: 'w' })
+  const config = resolveConfig({ shells: [{ id: 'w', name: 'WSL', kind: 'wsl' }], default: 'w' })
   const entry = config.shells[0]
   assert.deepEqual(entry.env, {})
   assert.equal(entry.distro, '')
@@ -32,7 +32,7 @@ test('S10 args 模板条目接管 argv,distro 不出现', () => {
 
 test('S6 entryFor 透传 env 与 distro;spawnSpec env 含条目键', () => {
   const cmdPath = process.execPath
-  const config = Config({
+  const config = resolveConfig({
     shells: [{ id: 'c', name: 'CMD', kind: 'cmd', path: cmdPath, env: { MSYSTEM: 'MINGW64' } }, { id: 'p', name: 'pwsh', kind: 'pwsh' }],
     default: 'c',
   })
@@ -45,19 +45,24 @@ test('S6 entryFor 透传 env 与 distro;spawnSpec env 含条目键', () => {
   assert.equal(spawned.env.NO_COLOR, '1')
 })
 
-test('S7 updateConfig 接受 env/distro 字段并落盘回读', async () => {
-  const section = Config({
+test('S7 web 行写路径接受 env/distro 字段并落盘', async () => {
+  const { SECTION_NS, buildFaces } = await import('../src/web-routes.mjs')
+  const section = resolveConfig({
     shells: [
       { id: 'p', name: 'pwsh', kind: 'pwsh' },
       { id: 'w', name: 'WSL', kind: 'wsl', distro: 'Debian', env: { LANG: 'C.UTF-8' } },
     ],
     default: 'p',
   })
-  const executor = new ShellSelectExecutor(stubCtxFor(section), section)
-  const next = await executor.updateConfig({})
+  const replaced = []
+  const ctx = { logger: { warn: () => {} } }
+  const settings = { describe: () => [{ ns: SECTION_NS, value: section }], replace: async (ns, next) => { replaced.push({ ns, next }) } }
+  const faces = buildFaces(ctx, settings)
+  const next = await faces.updateConfig({})
   const wsl = next.shells.find((entry) => entry.id === 'w')
   assert.equal(wsl.distro, 'Debian')
   assert.deepEqual(wsl.env, { LANG: 'C.UTF-8' })
+  assert.equal(replaced[0].ns, SECTION_NS)
 })
 
 function stubCtxFor(config) {