@mzzsfy/dsh-shell-select 0.3.1 → 0.4.1

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'
@@ -52,8 +56,8 @@ function processOutcome(proc) {
   return { status: 'completed', detail: `exit code: ${proc.exitCode ?? 0}` }
 }
 
-/** 前台结果 DTO 去只读化(官方 canonical 同构)。 */
-function canonicalResult(result) {
+/** 前台结果 DTO 去只读化(官方 canonical 同构);shellId 为执行事实,随块落存储供卡片徽章回放。 */
+function canonicalResult(result, shellId) {
   const output = (stream) => ({
     text: stream.text,
     truncated: stream.truncated,
@@ -68,6 +72,7 @@ function canonicalResult(result) {
     timeoutMs: result.timeoutMs,
     stdout: output(result.stdout),
     stderr: output(result.stderr),
+    ...shellId !== undefined ? { shell: shellId } : {},
     ...result.sandbox !== undefined ? { sandbox: {
       mode: result.sandbox.mode,
       denied: result.sandbox.denied,
@@ -77,10 +82,11 @@ function canonicalResult(result) {
   }
 }
 
-/** 后台输出并集公共键(官方同构)。 */
+/** 后台输出并集公共键(官方同构);shell 同前台,执行事实随 DTO 供渲染。 */
 const BACKGROUND_OUTPUT_PROPERTIES = {
   kind: { type: 'string', required: true, const: 'background' },
   jobId: { type: 'string', required: true },
+  shell: { type: 'string' },
 }
 
 /** 前台输出分支(官方同构,逐字段)。 */
@@ -104,6 +110,7 @@ function foregroundOutputProperties() {
     timeoutMs: { type: 'number', required: true },
     stdout: streamSchema,
     stderr: streamSchema,
+    shell: { type: 'string' },
     sandbox: {
       type: 'object',
       additionalProperties: false,
@@ -135,8 +142,14 @@ 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() {
+  return 'Do not call; use `shell`.'
+}
+
 /**
- * 注册 shell 工具,返回卸载 disposer(重注册 = 先卸后挂)。
+ * 注册 shell + pwsh 双工具,返回卸载 disposer(重注册 = 先卸后挂)。
+ * pwsh 工具钉死 pwsh 客户端(config 删 pwsh 条目时 requireEntry 明确拒绝)。
  * @param {object} ctx cordis context(需 tools/shellEnv 服务在场)
  * @param {{executor: object}} faces 执行器实例
  */
@@ -166,24 +179,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(),
     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.',
@@ -220,18 +237,20 @@ export function registerShellTool(ctx, { executor }) {
       }] },
       render: (_args, value) => [{
         type: 'text',
-        text: value.kind === 'background' ? `started background job ${value.jobId}` : renderResult(value, escalationModes),
+        text: value.kind === 'background'
+          ? `started background job ${value.jobId}${value.shell !== undefined ? `\n[shell: ${value.shell}]` : ''}`
+          : renderResult(value, escalationModes, value.shell),
       }],
     },
     async execute(args, exec) {
       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 } : {},
@@ -246,11 +265,12 @@ export function registerShellTool(ctx, { executor }) {
         try {
           faces.executor.startFor(entry, faces.executor.resolve(request))
         } catch (error) {
-          if (isDenyError(error)) return { kind: 'foreground', blocked: true, blockedBy: error.pattern, exitCode: null, signal: null, timedOut: false, aborted: false, timeoutMs: 0, stdout: { text: '', truncated: false }, stderr: { text: blockedMarker(error), truncated: false } }
+          if (isDenyError(error)) return { kind: 'foreground', shell: entry.id, blocked: true, blockedBy: error.pattern, exitCode: null, signal: null, timedOut: false, aborted: false, timeoutMs: 0, stdout: { text: '', truncated: false }, stderr: { text: blockedMarker(error), truncated: false } }
           throw error
         }
         return {
           kind: 'background',
+          shell: entry.id,
           jobId: jobs.start({
             kind: 'shell',
             label: args.command,
@@ -273,11 +293,11 @@ export function registerShellTool(ctx, { executor }) {
           signal: exec.signal,
         }))
       } catch (error) {
-        if (isDenyError(error)) return { kind: 'foreground', blocked: true, blockedBy: error.pattern, exitCode: null, signal: null, timedOut: false, aborted: false, timeoutMs: 0, stdout: { text: '', truncated: false }, stderr: { text: blockedMarker(error), truncated: false } }
+        if (isDenyError(error)) return { kind: 'foreground', shell: entry.id, blocked: true, blockedBy: error.pattern, exitCode: null, signal: null, timedOut: false, aborted: false, timeoutMs: 0, stdout: { text: '', truncated: false }, stderr: { text: blockedMarker(error), truncated: false } }
         throw error
       }
       if (result.aborted) throw await abortError('tool call aborted')
-      return canonicalResult(result)
+      return canonicalResult(result, entry.id)
     },
     presentCall: (args) => {
       if (args.run_in_background === true) {
@@ -323,7 +343,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 +355,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,93 @@
+// 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, coerceServiceable, 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({})
+  }
+  // 读出面同走 coercing:落盘坏值(悬空 default/空 shells)投影为可服务配置,
+  // 设置页显示与执行面一致,不再暴露不可服务的中间态
+  return resolveConfig(coerceServiceable(found.value ?? {}).config)
+}
+
+/**
+ * 设置页 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

@@ -26,6 +26,8 @@ function cardModel(catalog = null) {
     lastSegment,
     parseExitTail: extractLogic('parseExitTail'),
     hasSpillNotice: extractLogic('hasSpillNotice'),
+    parseShellMark: extractLogic('parseShellMark'),
+    stripShellMark: extractLogic('stripShellMark'),
     clientDisplayName: extractLogic('clientDisplayName', { clientCatalog: catalog }),
   })
 }
@@ -34,6 +36,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 +69,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', () => {
@@ -144,6 +157,76 @@ test('S17d 后台状态中性:不断言运行中,点为中性图标(渲染守卫
   assert.doesNotMatch(source, /case 'background': return en \? 'Background' : '后台运行'/)
 })
 
+test('S18 头部单行:cwd 与客户端徽章强制不换行(渲染守卫)', () => {
+  // BDD:Given 头部行宽受限,When cwd 或客户端名过长,Then 二者均不内部折行(cwd 压缩出省略号,徽章保持完整)
+  assert.match(source, /\.sls-tv__cwd \{[^}]*white-space:nowrap/)
+  assert.match(source, /\.sls-tv__cwd \{[^}]*overflow:hidden/)
+  assert.match(source, /\.sls-tv__cwd \{[^}]*text-overflow:ellipsis/)
+  assert.match(source, /\.sls-tv__badge \{[^}]*white-space:nowrap/)
+  assert.match(source, /\.sls-tv__pill \{[^}]*white-space:nowrap/)
+  assert.match(source, /\.sls-tv__duration \{[^}]*white-space:nowrap/)
+  assert.match(source, /\.sls-tv__pulse \{[^}]*white-space:nowrap/)
+})
+
+test('S19 行首无展开箭头:官方组件无展开箭头,可展开性由指针与整行点击承载(渲染守卫)', () => {
+  // BDD:Given 官方 ToolRow 无展开箭头,When 行渲染,Then 不存在 chevron 节点及其样式与状态钩子
+  assert.doesNotMatch(source, /sls-tv__chev/)
+  assert.doesNotMatch(source, /IconChevron/)
+  assert.doesNotMatch(source, /data-open/)
+})
+
+test('S20 徽章执行事实:结果标记优先于查看时配置读数', () => {
+  // BDD:Given 缺省客户端调用时 default 为 pwsh,查看时配置 default 已改 git-bash,When 派生卡片模型,Then 徽章显示标记承载的 pwsh,输出不含标记行
+  const model = cardModel({ default: 'git-bash', byId: { 'git-bash': 'git-bash' } })(
+    settledBlock(ARGS, 'out\n[shell: pwsh]\n[exit code: 0]'), SESSION_CWD)
+  assert.equal(model.kind, 'terminal')
+  assert.equal(model.shellName, 'pwsh')
+  assert.equal(model.output, 'out')
+})
+
+test('S20b 徽章执行事实:标记在场不依赖配置面,catalog 缺失仍显示', () => {
+  // BDD:Given 配置读取失败(catalog null),When 块带执行事实标记,Then 徽章仍按标记显示(执行事实不依赖查看时读数)
+  const model = cardModel(null)(
+    settledBlock(ARGS, 'out\n[shell: git-bash]\n[exit code: 2]'), SESSION_CWD)
+  assert.equal(model.shellName, 'git-bash')
+  assert.equal(model.exitCode, 2)
+})
+
+test('S20c 旧块无标记:回退显式参数 → 查看时 default(S15 链不回归)', () => {
+  // BDD:Given 历史块无标记时代产物,When 派生模型,Then 沿用显式参数/查看时 default 推导
+  const catalog = { default: 'git-bash', byId: { 'git-bash': 'git-bash', pwsh: 'pwsh' } }
+  const fallback = cardModel(catalog)(settledBlock(ARGS, 'out\n[exit code: 0]'), SESSION_CWD)
+  assert.equal(fallback.shellName, 'git-bash')
+  const explicit = cardModel(catalog)(
+    settledBlock(JSON.stringify({ command: 'ls', description: 'list', shell: 'pwsh' }), 'out\n[exit code: 0]'), SESSION_CWD)
+  assert.equal(explicit.shellName, 'pwsh')
+})
+
+test('S20d 后台 ack:标记入徽章,输出剥离标记行', () => {
+  // BDD:Given 后台调用 ack 携带执行事实标记,When 派生模型,Then shellName 按标记,输出仅剩 ack 原文
+  const model = cardModel({ default: 'git-bash', byId: {} })(settledBlock(
+    JSON.stringify({ command: 'node server.js', description: 'Boot server', run_in_background: true }),
+    'started background job shell-11\n[shell: pwsh]'), SESSION_CWD)
+  assert.equal(model.kind, 'background')
+  assert.equal(model.jobId, 'shell-11')
+  assert.equal(model.shellName, 'pwsh')
+  assert.equal(model.output, 'started background job shell-11')
+})
+
+test('S20e generic 输出剥离标记行(isError 路径)', () => {
+  // BDD:Given isError 块文本含标记,When 回退 generic,Then 输出不含标记行
+  const model = cardModel(null)(settledBlock(ARGS, 'boom\n[shell: pwsh]', { isError: true }), SESSION_CWD)
+  assert.equal(model.kind, 'generic')
+  assert.equal(model.output, 'boom')
+})
+
+test('S20f 运行中块:无结果文本,徽章按显式参数/查看时 default 推导(现状)', () => {
+  // BDD:Given 调用进行中无结果,When 派生模型,Then 徽章沿用配置读数(执行事实落定后由标记校正)
+  const catalog = { default: 'git-bash', byId: { 'git-bash': 'git-bash' } }
+  const model = cardModel(catalog)(runningBlock(ARGS), SESSION_CWD)
+  assert.equal(model.shellName, 'git-bash')
+})
+
 test('S12c isError 与空结果仍走 generic(回归)', () => {
   const errored = cardModel()(settledBlock(ARGS, 'boom', { isError: true }), SESSION_CWD)
   assert.equal(errored.kind, 'generic')
@@ -156,6 +239,91 @@ test('S13 注册面:shell/pwsh/bash 三 key 且 priority -1(文本守卫)', () =
   assert.match(source, /key: toolKey, priority: -1/)
 })
 
+// ── S21 六态徽章矩阵:前台/后台 × shell(git-bash/pwsh) × pwsh 官方 ──
+// 背景:官方 pwsh 工具调用被增强卡接管,但其输出无 [shell: ...] 标记、参数无
+// shell 字段,徽章兜底落查看时默认客户端读数 → 官方 pwsh 调用误标 git-bash。
+
+const BG_ARGS = JSON.stringify({ command: 'node server.js', description: 'Boot server', run_in_background: true })
+
+test('S21a shell 前台 git-bash:执行事实标记入徽章', () => {
+  // BDD:Given shell 工具经 git-bash 客户端前台执行,When 派生卡片模型,Then 徽章显示标记承载的 git-bash
+  const model = cardModel(null)(settledBlock(ARGS, 'out\n[shell: git-bash]\n[exit code: 0]'), SESSION_CWD, 'shell')
+  assert.equal(model.kind, 'terminal')
+  assert.equal(model.shellName, 'git-bash')
+})
+
+test('S21b shell 前台 pwsh:执行事实标记入徽章', () => {
+  // BDD:Given shell 工具经 pwsh 客户端前台执行失败,When 派生卡片模型,Then 徽章 pwsh 且退出码保留
+  const model = cardModel(null)(settledBlock(ARGS, 'out\n[shell: pwsh]\n[exit code: 2]'), SESSION_CWD, 'shell')
+  assert.equal(model.shellName, 'pwsh')
+  assert.equal(model.exitCode, 2)
+})
+
+test('S21c shell 后台 git-bash:ack 标记入徽章,jobId 解析', () => {
+  // BDD:Given shell 工具后台启动于 git-bash,When 派生 ack 卡,Then 徽章 git-bash 且 jobId 取自 ack
+  const model = cardModel(null)(settledBlock(BG_ARGS, 'started background job shell-4\n[shell: git-bash]'), SESSION_CWD, 'shell')
+  assert.equal(model.kind, 'background')
+  assert.equal(model.jobId, 'shell-4')
+  assert.equal(model.shellName, 'git-bash')
+})
+
+test('S21d shell 后台 pwsh:ack 标记入徽章', () => {
+  // BDD:Given shell 工具后台启动于 pwsh,When 派生 ack 卡,Then 徽章 pwsh
+  const model = cardModel(null)(settledBlock(BG_ARGS, 'started background job shell-5\n[shell: pwsh]'), SESSION_CWD, 'shell')
+  assert.equal(model.kind, 'background')
+  assert.equal(model.jobId, 'shell-5')
+  assert.equal(model.shellName, 'pwsh')
+})
+
+test('S21e pwsh 官方前台:徽章钉死 pwsh,不落默认客户端读数', () => {
+  // BDD:Given 官方 pwsh 工具调用(无标记无 shell 参数)且查看时默认客户端为 git-bash,
+  // When 派生卡片模型,Then 徽章 pwsh(工具名即执行事实,读数兜底只属 shell 工具历史块)
+  const model = cardModel({ default: 'git-bash', byId: { 'git-bash': 'git-bash' } })(
+    settledBlock(ARGS, 'On branch main\n[exit code: 0]'), SESSION_CWD, 'pwsh')
+  assert.equal(model.kind, 'terminal')
+  assert.equal(model.shellName, 'pwsh')
+})
+
+test('S21f pwsh 官方后台:徽章钉死 pwsh,官方 pwsh 前缀 jobId 解析', () => {
+  // BDD:Given 官方 pwsh 工具后台启动(kind pwsh → 任务号 pwsh-N),When 派生 ack 卡,Then 徽章 pwsh 且 jobId=pwsh-3
+  const model = cardModel({ default: 'git-bash', byId: { 'git-bash': 'git-bash' } })(
+    settledBlock(BG_ARGS, 'started background job pwsh-3'), SESSION_CWD, 'pwsh')
+  assert.equal(model.kind, 'background')
+  assert.equal(model.jobId, 'pwsh-3')
+  assert.equal(model.shellName, 'pwsh')
+})
+
+test('S21g pwsh 官方运行中:徽章钉死 pwsh(落定前不误标)', () => {
+  // BDD:Given 官方 pwsh 调用进行中无结果文本,When 派生 running 卡,Then 徽章 pwsh 而非默认客户端读数
+  const model = cardModel({ default: 'git-bash', byId: { 'git-bash': 'git-bash' } })(runningBlock(ARGS), SESSION_CWD, 'pwsh')
+  assert.equal(model.status, 'running')
+  assert.equal(model.shellName, 'pwsh')
+})
+
+test('S21h bash 官方 key 同规钉死(同类预防)', () => {
+  // BDD:Given 官方 bash 工具调用且默认客户端读数为 git-bash,When 派生卡片模型,Then 徽章 bash
+  const model = cardModel({ default: 'git-bash', byId: { 'git-bash': 'git-bash' } })(
+    settledBlock(ARGS, 'out\n[exit code: 0]'), SESSION_CWD, 'bash')
+  assert.equal(model.shellName, 'bash')
+})
+
+test('S21i toolKey 贯通:注册循环注入 + 行组件传入模型(渲染守卫)', () => {
+  // BDD:Given 卡片按 key 注册,When 渲染,Then key 以 toolKey 注入组件并传入模型派生(漏任何一环徽章退回读数兜底)
+  assert.match(source, /React\.createElement\(ShellToolRow, \{ \.\.\.props, toolKey \}\)/)
+  assert.match(source, /shellCardModel\(block, cwd, toolKey\)/)
+})
+
+test('S21j 钉死键集与注册键集同源:PINNED_CLIENT 恒等于 TOOLVIEW_KEYS 去 shell(渲染守卫)', () => {
+  // BDD:Given 官方钉死客户端事实在 client.js 双处字面编码(TOOLVIEW_KEYS 与 PINNED_CLIENT),
+  // When 派生两处键集,Then 钉死键集恒等于注册键集去掉 shell——注册面新增官方工具 key 而
+  // 漏配钉死映射时此处红,误标 bug 不静默复发
+  const toolviewKeys = /const TOOLVIEW_KEYS = \[([^\]]*)\]/.exec(source)[1]
+    .split(',').map((item) => item.trim().replace(/^'|'$/g, '')).filter((key) => key !== '' && key !== 'shell')
+  const pinnedKeys = /const PINNED_CLIENT = \{([^}]*)\}/.exec(source)[1]
+    .split(',').map((pair) => pair.trim().split(':')[0].trim().replace(/^'|'$/g, '')).filter((key) => key !== '')
+  assert.deepEqual(pinnedKeys.sort(), toolviewKeys.sort())
+})
+
 test('K=V 往返:值含 = 与空格无损,空行忽略,重复键后行胜', () => {
   const parse = parseEnvText()
   assert.deepEqual(parse('A=1\nB=x=y z\n\nA=2'), { A: '2', B: 'x=y z' })