@mzzsfy/dsh-shell-select 0.3.1 → 0.4.1

package/src/executor.mjs

@@ -1,34 +1,35 @@
 // shell-select 执行器:ctx.shell 提供者(官方 SandboxPwshExecutor 同构,进程机制
-// 继承 dsh-pwsh-local 形态),并把模型可见 shell 工具、systemPrompt 段、
-// shell-select 设置节与浏览器半区路由一并挂在本行 fiber 上。
+// 继承 dsh-pwsh-local 形态),并把模型可见 shell 工具与 systemPrompt 段挂在本行
+// fiber 上;设置页数据通道在 web-routes 行(声明式 webServer 门控),配置事实源
+// = 本行 Config(settings 面以行条目为存储,变更经 cordis 行重载活生效)。
 //
 // 与官方的两处结构差异(其余逐项同构):
 // 1. argv 由「本次调用选中的 shell 条目」决定(pwsh/bash/cmd/wsl 四形 + args 模板),
 //    confine 包的正是该条目 argv;
-// 2. 执行器预算与客户端清单同节('shell-select'),官方拆 'shell' 节 + 行内 Config。
+// 2. 执行器预算与客户端清单同行 Config,官方拆 'shell' 节 + 行内 Config。
 //
 // 兼容性:ShellExecutor 基类为官方文档级扩展缝(dsh-shell README 明示子类化);
 // dsh-llm 经 tool.mjs 动态 import + 特性检测(HarnessError 缺失即降级),
 // dsh-tools/dsh-sandbox 静态 import(官方组合必装,无降级面)。
 
 import { ShellExecutor } from '@deepseek-ai/dsh-shell'
-import { MAX_TIMER_DELAY_MS, clampTimeout, deadline, timeoutOf } from '@deepseek-ai/dsh-timeout'
-import { Config, KINDS, buildArgv, requireEntry } from './config.mjs'
+import { clampTimeout, deadline, timeoutOf } from '@deepseek-ai/dsh-timeout'
+import { Config, KINDS, buildArgv, requireEntry, resolveConfig, resolveConfigStrict, unwrapConfig, assertServiceableConfig, normalizeWin32Path } from './config.mjs'
 import { matchDeny } from './denylist.mjs'
 import { candidateExists, detectCandidates, resolveEntryPath } from './resolve.mjs'
 import { classifyDenial, classifyRunnerFailure, isRunnerSpawnFailure } from './sandbox-classify.mjs'
 import { registerShellTool } from './tool.mjs'
-import { mountRoutes } from './api.mjs'
-import { beginShellSelectApply, endShellSelectApplyActive } from './apply-state.mjs'
 
 export const name = 'shell-select'
 
-// 单一事实源:loader 消费模块级 inject 导出,Service 类静态与它共用同一常量
-export const SHELL_SELECT_INJECT = ['subprocess', 'sandbox', 'sandboxPolicy', 'settings', 'tools', 'systemPrompt', 'shellEnv']
+// 单一事实源:loader 消费模块级 inject 导出,Service 类静态与它共用同一常量。
+// settings 不在列:配置事实源 = 行 Config(0.1.7 settings 面语义),页面策略经
+// apply 内可选子级注入注册,业务插件无 settings 服务也可运行(官方 README 同构)。
+export const SHELL_SELECT_INJECT = ['subprocess', 'sandbox', 'sandboxPolicy', 'tools', 'systemPrompt', 'shellEnv']
 
 export const inject = SHELL_SELECT_INJECT
 
-export { Config }
+export { Config } from './config.mjs'
 
 // 面向模型的终端环境覆盖(官方 dsh-pwsh-local 同构):禁色禁 pager
 export const ENV_OVERRIDES = {
@@ -82,41 +83,6 @@ function assertPositiveFinite(name, value) {
   if (!Number.isFinite(value) || value <= 0) throw new Error(`shell-select: ${name} must be a positive finite number`)
 }
 
-// yaml 无引号标量会把 `\` 字面落盘,任何一层再转义都让路径翻倍(C:\\ 实测):
-// 入口统一归一,保证进 schema 的 path 就是干净值。
-// 仅 Windows 宿主生效:posix 路径以 / 分隔,归一会把合法路径毁成反斜杠字面(CI linux 实测)
-function normalizeWin32Path(path) {
-  if (process.platform !== 'win32') return path
-  if (typeof path !== 'string' || path.length === 0) return path
-  return path.replace(/\\{2,}/g, '\\').replace(/\//g, '\\')
-}
-
-// 更新负载深归一:shells[].path 与任意层字符串值只处理 path 键,避免误伤 args 模板
-function normalizeConfigPaths(patch) {
-  if (typeof patch !== 'object' || patch === null || !Array.isArray(patch.shells)) return patch
-  return {
-    ...patch,
-    shells: patch.shells.map((entry) => (typeof entry?.path === 'string' ? { ...entry, path: normalizeWin32Path(entry.path) } : entry)),
-  }
-}
-
-/** 拒绝无法运行的已解析配置节(schema 之外的正数/时限/清单约束,官方 assertServiceable 同构)。 */
-export function assertServiceableConfig(config) {
-  assertPositiveFinite('timeoutMs', config.timeoutMs)
-  assertPositiveFinite('maxTimeoutMs', config.maxTimeoutMs)
-  assertPositiveFinite('maxOutputBytes', config.maxOutputBytes)
-  assertPositiveFinite('maxSpillBytes', config.maxSpillBytes)
-  assertPositiveFinite('graceMs', config.graceMs)
-  if (config.graceMs > MAX_TIMER_DELAY_MS) throw new Error(`shell-select: graceMs must be no greater than ${MAX_TIMER_DELAY_MS}`)
-  if (!Array.isArray(config.shells) || config.shells.length === 0) throw new Error('shell-select: shells must not be empty')
-  const ids = new Set()
-  for (const entry of config.shells) {
-    if (ids.has(entry.id)) throw new Error(`shell-select: duplicate shell id "${entry.id}"`)
-    ids.add(entry.id)
-  }
-  if (!ids.has(config.default)) throw new Error(`shell-select: default "${config.default}" is not a configured shell id`)
-}
-
 /** 收集模式的 reader 投影成 CollectedOutput(官方同构)。 */
 function finalOutput(reader) {
   const read = reader.readFrom(0)
@@ -155,10 +121,12 @@ export const ShellSelectExecutor = class ShellSelectExecutor extends ShellExecut
   // (getTraceable/createShadowMethod)会把经 ctx.shell 访问的方法 this 重定向到
   // 阴影对象,#私有字段在阴影 receiver 下触发 V8 品牌检查错误(官方工具
   // tool-pwsh 正是经 ctx.shell 调用,实测复现)。
-  /** 当前权威配置来源:设置节(接线后)或行内配置。 */
+  /** 当前权威配置:行 Config(0.1.7 settings 面以行为存储,变更即行重载重建本实例)。 */
   source
-  /** 工具重注册句柄(onChange 先卸后挂;仅构造期闭包触达,this 恒为裸实例)。 */
+  /** 工具重注册句柄(仅构造期闭包触达,this 恒为裸实例)。 */
   #toolRegistration = null
+  /** 配置快照(挂载时解包产物;volatile 变更经 refresh 换新)。 */
+  #entry = {}
   /** 托管进程的每进程 confinement 事实(官方同构)。 */
   processFacts = new Map()
   /** SANDBOX_UNAVAILABLE 构造器(动态导入就绪后由官方类顶替降级类)。 */
@@ -166,36 +134,37 @@ export const ShellSelectExecutor = class ShellSelectExecutor extends ShellExecut
 
   constructor(ctx, config) {
     super(ctx)
-    beginShellSelectApply()
     void loadSandboxUnavailable(ctx).then((resolved) => {
       this.unavailableError = resolved
     })
-    // settings 为硬依赖(static inject 门控);面异常按降级处理,能力不损
-    const settingsOk = typeof ctx.settings?.installSection === 'function'
-    if (!settingsOk) ctx.logger?.warn?.('shell-select: 宿主 settings 服务缺 installSection,配置退化为行内 Config,无热更新')
-
-    const entry = config ?? {}
-    assertServiceableConfig(Config(entry))
-    this.source = () => Config(entry)
-    if (settingsOk) {
-      ctx.settings.installSection(ctx, 'shell-select', Config, entry, {
-        validate: assertServiceableConfig,
-        setSource: (current) => {
-          this.source = current
-        },
-        onChange: () => this.#onConfigChange(),
-      })
-    }
+    this.#setEntry(config)
+    this.source = () => resolveConfig(this.#entry)
+    // refresh 桥绑定随本 fiber 卸载自动解绑(实例退场后写路径请求静默丢弃)
+    ctx.effect(() => bindShellRefreshBridge((next) => this.refresh(next)))
+    // 自带设置页(客户端半区自定义卡):抑制宿主按 schema 自动生成的原生页
+    // (官方 README 同构:可选子级注入声明策略归属 fiber,服务迟加载也采纳)
+    ctx.inject?.(['settings'], (child) => {
+      if (typeof child.settings?.configure !== 'function') return
+      child.effect(() => child.settings.configure({ auto: false }, ctx.fiber))
+    })
     this.#registerTool()
     this.#mountPromptSection()
-    mountRoutes(ctx, {
-      listShells: () => this.listShells(),
-      readConfig: () => this.source(),
-      updateConfig: (patch) => this.updateConfig(patch),
-      detect: (kinds) => this.detect(kinds),
-      probe: (candidatePath) => candidateExists(candidatePath),
-    })
-    endShellSelectApplyActive()
+  }
+
+  /** 挂载/换源共用落定:入参经宿主按 static Config resolve,volatile 字段是
+   * boxed ref,存储前解箱成普通对象;落定校验走 strict——解箱后仍存在非法
+   * 形态字段即抛(宿主契约变化炸在挂载点,接管序列回滚告警),禁止静默回落
+   * 出厂默认(行 config 永不生效缺陷的机械化防线)。 */
+  #setEntry(config) {
+    this.#entry = unwrapConfig(config ?? {})
+    assertServiceableConfig(resolveConfigStrict(this.#entry))
+  }
+
+  /** volatile-only 配置变更的活刷新:换配置源并重建工具注册(写路径经
+   * requestShellRefresh 触达;行不重挂,本实例与进行中执行不受扰)。 */
+  refresh(config) {
+    this.#setEntry(config)
+    this.#registerTool()
   }
 
   get config() {
@@ -224,7 +193,6 @@ export const ShellSelectExecutor = class ShellSelectExecutor extends ShellExecut
         const resolved = normalizeWin32Path(resolveEntryPath(entry, candidateExists))
         return {
           id: entry.id,
-          name: entry.name,
           kind: entry.kind,
           args: entry.args,
           path: resolved,
@@ -258,33 +226,6 @@ export const ShellSelectExecutor = class ShellSelectExecutor extends ShellExecut
     return { id: entry.id, kind: entry.kind, path: resolved, args: entry.args, login: entry.login === true, distro: entry.distro ?? '', env: entry.env ?? {} }
   }
 
-  /**
-   * 客户端半区配置更新入口:wholesale replace(settings merge 对数组是整值
-   * 覆盖,部分清单会静默丢条目;设置页语义是保存完整清单);等写队列落定再回读。
-   */
-  async updateConfig(patch) {
-    const current = this.config
-    const section = normalizeConfigPaths({
-      shells: patch.shells ?? current.shells,
-      default: patch.default ?? current.default,
-      deny: Array.isArray(patch.deny) ? patch.deny : current.deny,
-    })
-    assertServiceableConfig(Config(section))
-    await this.ctx.settings.replace('shell-select', section)
-    return this.listShells()
-  }
-
-  #onConfigChange() {
-    try {
-      assertServiceableConfig(this.config)
-    } catch (error) {
-      // validate hook 已在写入路径拦截;此处兜底防御,保旧配置
-      this.ctx.logger?.warn?.(`shell-select: 新配置不可用,保留先前配置: ${error?.message ?? error}`)
-      return
-    }
-    this.#registerTool()
-  }
-
   /** 注册/重注册 shell 工具(描述随客户端清单变化)。 */
   #registerTool() {
     this.#toolRegistration?.()
@@ -323,11 +264,162 @@ export const ShellSelectExecutor = class ShellSelectExecutor extends ShellExecut
     return buildArgv(entry, spec.command)
   }
 
-  /** 官方 run seam:已解析 spec 按默认客户端前台执行(dsh-pwsh-local run 同构)。 */
+  /** 官方 execute seam:已解析 spec 按默认客户端前台执行(dsh-pwsh-local run 同构)。 */
   async run(spec) {
     return this.runFor(this.entryFor(), spec)
   }
 
+  /**
+   * 官方 ctx.shell 唯一执行契约(ShellExecutor 抽象方法,官方 tool-pwsh 与
+   * 进程内消费方共同依赖):解析 spec 后按默认客户端 spawn,返回 ShellExecution
+   * 句柄(done/readOutput/kill/observed/result)。前台与否是调用方 await 什么的
+   * 属性,不是 spawn 的属性。沙箱语义与 runFor 同源:danger 直跑,受限模式
+   * confine 包装,定案按 denial/runner-failure 规则附 sandbox 事实。
+   * @param {object} spec resolve() 产物(never 原始 request)
+   * @returns {Promise<object>} ShellExecution 句柄
+   */
+  async execute(spec) {
+    this.assertNotDenied(spec.command)
+    const entry = this.entryFor()
+    const policy = spec.sandboxPolicy
+    const { mode } = policy
+    if (mode === 'danger-full-access') {
+      return this.executionArgv(entry, spec)
+    }
+    const confined = this.ctx.sandbox.confine(this.argvFor(entry, spec), { ...policy, mode })
+    return this.executionArgv(entry, spec, confined.argv, {
+      mode,
+      enforcement: confined.enforcement,
+      denialSignatures: confined.denialSignatures,
+      runnerFailureRules: confined.runnerFailureRules,
+      runnerProgram: confined.argv[0],
+      workdir: spec.workdir,
+    })
+  }
+
+  /**
+   * 官方 executeArgv 同构(条目参数化):deadline 按 spec.onExpiry 武装
+   * ('kill' 到期杀,'none'/缺省只跟随调用方信号);done 永不 reject,provider
+   * spawn 失败定局 killed + stderr 注记,result() 携带同一 rejection;受限模式
+   * 定案事实经 processFacts/onProcessDone 单通道写 proc.sandbox(官方
+   * pwsh-sandbox 子类同构),unsandboxed 的 result() 无 sandbox 键。
+   */
+  executionArgv(entry, spec, forcedArgv, sandboxFacts) {
+    const argv = forcedArgv ?? this.argvFor(entry, spec)
+    const armDeadline = spec.onExpiry === 'kill'
+    const d = armDeadline ? deadline(spec.signal, spec.timeoutMs, 'SHELL_TIMEOUT') : undefined
+    const spawnSignal = d ? d.signal : spec.signal
+    const classifyState = () => {
+      if (d === undefined) return { timedOut: false, aborted: spec.signal?.aborted === true }
+      const timedOut = timeoutOf(d.signal, 'SHELL_TIMEOUT') !== undefined
+      return { timedOut, aborted: d.signal.aborted === true && !timedOut }
+    }
+    let running
+    let syncSpawnError
+    const prepareAborted = spawnSignal?.aborted === true
+    if (!prepareAborted) {
+      try {
+        running = this.ctx.subprocess.spawn(this.spawnSpec(entry, spec, argv, spec.stdoutMaxBytes, spawnSignal))
+      } catch (error) {
+        syncSpawnError = { error }
+      }
+    }
+    const emptyReader = { readFrom: () => ({ text: '', lossy: false, nextOffset: 0 }) }
+    const collected = running !== undefined ? ShellSelectExecutor.collected(running) : { stdout: emptyReader, stderr: emptyReader }
+    const spawnThrow = () => syncSpawnError.error
+    const spawned = prepareAborted
+      ? Promise.resolve({ exitCode: null, signal: null })
+      : running !== undefined ? running.done : Promise.reject(spawnThrow())
+    let providerFailure
+    const consumeProviderFailure = () => {
+      if (providerFailure === undefined || providerFailure.reported) return ''
+      providerFailure.reported = true
+      return providerFailure.note
+    }
+    let stdoutOffset = 0
+    let stderrOffset = 0
+    const readCollected = (offsets) => ({
+      out: collected.stdout.readFrom(offsets.stdout),
+      err: collected.stderr.readFrom(offsets.stderr),
+    })
+    const executor = this
+    let resultPromise
+    const proc = {
+      status: 'running',
+      exitCode: null,
+      signal: null,
+      observed: {
+        stdout: collected.stdout,
+        stderr: {
+          readFrom: (fromByte) => {
+            if (providerFailure === undefined) return collected.stderr.readFrom(fromByte)
+            const note = Buffer.from(providerFailure.note, 'utf8')
+            return { text: note.subarray(Math.min(fromByte, note.length)).toString('utf8'), nextOffset: note.length, lossy: false }
+          },
+        },
+      },
+      done: spawned.then((outcome) => {
+        if (proc.status === 'running') proc.status = spawnSignal?.aborted === true || outcome.signal !== null ? 'killed' : 'completed'
+        proc.exitCode = outcome.exitCode
+        proc.signal = outcome.signal
+        if (sandboxFacts !== undefined) executor.processFacts.set(proc, sandboxFacts)
+        executor.onProcessDone(proc, collected.stderr.readFrom(0).text, false)
+        d?.[Symbol.dispose]?.()
+      }, (error) => {
+        proc.status = 'killed'
+        let detail = 'unprintable provider failure'
+        try {
+          detail = String(error)
+        } catch {}
+        const isRunnerFailure = sandboxFacts !== undefined && isRunnerSpawnFailure(error, sandboxFacts.runnerProgram, sandboxFacts.workdir)
+        if (isRunnerFailure) {
+          providerFailure = { error: new executor.unavailableError(sandboxFacts.mode, String(error)), note: String(error), reported: false }
+        } else {
+          providerFailure = { error, note: `subprocess failed before reporting an outcome: ${detail}`, reported: false }
+        }
+        executor.onProcessDone(proc, providerFailure.note, true, error)
+        d?.[Symbol.dispose]?.()
+      }),
+      readOutput: () => {
+        const { out, err } = readCollected({ stdout: stdoutOffset, stderr: stderrOffset })
+        stdoutOffset = out.nextOffset
+        stderrOffset = err.nextOffset
+        const providerNote = consumeProviderFailure()
+        const failureSeparator = err.text.length > 0 && !err.text.endsWith('\n') ? '\n' : ''
+        const errText = err.text + (providerNote.length > 0 ? `${failureSeparator}${providerNote}` : '')
+        const separator = out.text.length > 0 && !out.text.endsWith('\n') ? '\n' : ''
+        return {
+          delta: out.text + (errText.length > 0 ? `${separator}[stderr]\n${errText}` : ''),
+          lossy: out.lossy || err.lossy,
+          ...out.spillPath !== undefined ? { stdoutSpillPath: out.spillPath } : {},
+          ...err.spillPath !== undefined ? { stderrSpillPath: err.spillPath } : {},
+        }
+      },
+      kill: () => {
+        if (proc.status !== 'running') return false
+        proc.status = 'killed'
+        running?.terminate()
+        return true
+      },
+      result: () => {
+        resultPromise ??= proc.done.then(() => {
+          if (providerFailure !== undefined) throw providerFailure.error
+          return {
+            exitCode: proc.exitCode,
+            signal: proc.signal,
+            ...classifyState(),
+            timeoutMs: spec.timeoutMs,
+            stdout: finalOutput(collected.stdout),
+            stderr: finalOutput(collected.stderr),
+            ...proc.sandbox !== undefined ? { sandbox: proc.sandbox } : {},
+          }
+        })
+        return resultPromise
+      },
+    }
+    return Promise.resolve(proc)
+  }
+
   /** 官方 start seam:已解析 spec 按默认客户端后台启动(dsh-pwsh-local start 同构)。 */
   start(spec) {
     return this.startFor(this.entryFor(), spec)
@@ -529,4 +621,22 @@ export const ShellSelectExecutor = class ShellSelectExecutor extends ShellExecut
   }
 }
 
+// volatile 变更的 refresh 桥(模块级单例,apply-state 同款先例):执行器
+// provide 的 ctx.shell 作用域在主行子树,web-routes 行是兄弟行,cordis 服务
+// 沿 ctx 树向上查找不横向,ctx.shell getter 直接 throw——写路径经此桥触达
+// 活跃实例。挂载绑定、实例卸载/顶替时解绑,未挂载时请求静默丢弃(执行面
+// 由下次挂载的行配置重建)。
+let refreshBridge = null
+
+export function bindShellRefreshBridge(handler) {
+  refreshBridge = handler
+  return () => {
+    if (refreshBridge === handler) refreshBridge = null
+  }
+}
+
+export function requestShellRefresh(snapshot) {
+  refreshBridge?.(snapshot)
+}
+
 export default ShellSelectExecutor

package/src/guard-state.mjs

@@ -60,3 +60,29 @@ export function detectDeadState(loader, { applyState }) {
     return !state.present || (state.disabled && !state.running)
   })
 }
+
+/**
+ * 全树扫描:枚举 loader 树内全部 entry 中 id/name 命中 pwsh 关键字的行,
+ * 报告前缀 id/声明禁用/求值禁用/fiber 存活(多实例二相性诊断用)。
+ * @param {object} loader 宿主 loader 服务
+ */
+export function rowScan(loader) {
+  if (loader?.root === undefined) return []
+  const hits = []
+  const walk = (tree, prefix) => {
+    for (const [id, entry] of Object.entries(tree.store ?? {})) {
+      const fullId = prefix + id
+      if (/pwsh/i.test(fullId) || /pwsh/i.test(String(entry.options?.name ?? ''))) {
+        hits.push({
+          id: fullId,
+          rawType: typeof entry.options?.disabled,
+          evalDisabled: (() => { try { return entry.disabled === true } catch { return 'throw' } })(),
+          running: entry.fiber?.uid != null,
+        })
+      }
+      if (entry.subtree) walk(entry.subtree, `${fullId}:`)
+    }
+  }
+  walk(loader.root.tree ?? loader.root, '')
+  return hits
+}

package/src/guard.js

@@ -1,13 +1,15 @@
 // shell-select guard 哨兵行:死态自愈,守服务不抢权(逐项同构 dsh-llm-pi-gateway
 // guard,差异仅代挂对象为官方 tool-pwsh + pwsh-sandbox 两行,且无 compat 键处理)。
 // 死态 = 主行功能性停摆(市场开关即时禁用 / apply 旗标 inactive)且官方两行仍被
-// bundle patch 禁用停稳——无任何 shell 执行器与工具。代挂走 ctx.plugin,随 guard
-// fiber 卸载;主行或官方行任一复活先卸代挂。guard 行 id 含 "/",市场行写入对其
-// 拒绝,窗口内始终存活。
+// 主行 runtime-disable 禁用停稳(内存残留)——无任何 shell 执行器与工具。代挂走
+// ctx.plugin,随 guard fiber 卸载;主行或官方行任一复活先卸代挂。guard 行 id 含
+// "/",市场行写入对其拒绝,窗口内始终存活。运行时接管后官方行默认启用,主行
+// 包级损伤形态下官方自服务,guard 空闲;死窗仅剩「接管中主行被禁」。
 
-import { MAIN_ROW_ID, OFFICIAL_ROW_IDS, detectDeadState, rowState } from './guard-state.mjs'
+import { MAIN_ROW_ID, OFFICIAL_ROW_IDS, detectDeadState, rowState, rowScan } from './guard-state.mjs'
 import { officialRowConfig, readSettingsDocument, resolveFromHostTree } from './guard-config.mjs'
-import { shellSelectApplyState } from './apply-state.mjs'
+import { officialRowState } from './takeover.mjs'
+import { shellSelectApplyState, shellSelectTakeoverTrace } from './apply-state.mjs'
 
 // 官方包 npm 名(与行 id 独立:行 id 是 dsh-base 组合行,包名才是模块解析键)
 const OFFICIAL_PACKAGES = {
@@ -211,15 +213,21 @@ export async function installGuard(ctx, {
     }
   }
 
-  // 可观测面:死态判定中间量与代挂状态只读暴露(排障与巡检共用)
+  // 可观测面:死态判定中间量、代挂状态与主行接管序列只读暴露(排障与巡检共用)
   const webServer = ctx.get?.('webServer')
   if (webServer !== undefined && typeof webServer.register === 'function') {
     const status = () => ({
       dead: detectDeadState(ctx.loader, { applyState: shellSelectApplyState }),
       applyState: shellSelectApplyState(),
+      takeover: shellSelectTakeoverTrace(),
       mounted: [...mounted.keys()],
       mounting: mounting !== null,
       rows: [MAIN_ROW_ID, ...OFFICIAL_ROW_IDS].map((id) => ({ id, ...rowState(ctx.loader, id) })),
+      officialRaw: Object.fromEntries(OFFICIAL_ROW_IDS.map((id) => {
+        const s = officialRowState(ctx.loader, id)
+        return [id, { rawType: typeof s.rawDisabled, disabled: s.disabled, running: s.running }]
+      })),
+      rowScan: rowScan(ctx.loader),
     })
     ctx.effect(() => webServer.register({
       kind: 'exact',

package/src/index.js

@@ -0,0 +1,163 @@
+// shell-select 主行入口(apply 型):官方 pwsh 链的运行时接管编排。
+//
+// 为什么是 apply 型而不是 Service 类:本包执行器与官方 pwsh-sandbox 抢同一个
+// cordis 服务(ctx.shell,cordis 重复 provide 抛错)。Service 类在构造期同步
+// provide,无法等待官方退场;apply 型行把「占服务」的动作变成可编排的挂载
+// 时序——apply 落定后禁官方行 → 等退场 → ctx.plugin 挂执行器,与 guard 的
+// mountOfficial(主行死时挂官方)互为镜像。
+//
+// 流程:POSIX 早退(官方 bash 链不碰,Linux 行为与无本包一致)→ 决策 →
+// yield(宿主状态异常,零动作)/ takeover(官方已禁,直挂)/
+// await-exit(等官方退场再挂)/ runtime-disable(官方启用中,apply 落定后
+// 运行时禁用再接管)。接管序列任何失败都回滚或降级:官方行恢复启用或保持
+// 在场服务,系统不出现 shell 真空。序列全程经 recordTakeover 留可观测面
+// (guard-status 暴露,0.1.7 运行期日志不落盘,排障以该探口为准)。
+//
+// 配置事实源 = 行 Config(Config 声明随主行模块导出供宿主 settings 面注册节,
+// apply 经 ctx.plugin 第二参传给执行器;设置页写经 settings 面行条目重载本行,
+// apply 重跑换挂执行器)。
+
+import { ShellSelectExecutor } from './executor.mjs'
+import {
+  beginShellSelectApply,
+  endShellSelectApplyActive,
+  endShellSelectApplyInactive,
+  recordTakeover,
+} from './apply-state.mjs'
+import {
+  awaitOfficialExit,
+  officialChainState,
+  rollbackDisabledRows,
+  runtimeDisableRows,
+  takeoverDecision,
+} from './takeover.mjs'
+import { coerceServiceable } from './config.mjs'
+
+export const name = 'shell-select'
+
+// settings 节注册面:宿主按行模块的 Config 导出注册 shell-select 节(与执行器
+// 同一 schema 单一事实源)
+export { Config } from './config.mjs'
+
+/**
+ * 主行 apply。
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {object|undefined} config 行 Config(shell 客户端清单等)
+ */
+export async function apply(ctx, config) {
+  beginShellSelectApply()
+  // 平台早退:行级平台门控在本前已停用本行,此为纵深防御——行被显式启用到
+  // POSIX 时本行自身不得碰官方 bash/pwsh 链
+  if (process.platform !== 'win32') {
+    endShellSelectApplyInactive()
+    return
+  }
+  const states = officialChainState(ctx.loader)
+  const { decision, targets } = takeoverDecision(states)
+  recordTakeover({
+    event: `decision=${decision} targets=${targets.length}`,
+    rows: Object.fromEntries(Object.entries(states).map(([id, row]) => [id, {
+      present: row.present,
+      rawType: typeof row.rawDisabled,
+      unreliable: row.disabledUnreliable,
+      running: row.running,
+    }])),
+  })
+  ctx.logger.info?.(`shell-select: 官方 pwsh 链接管决策 ${decision}(targets=${targets.length})`)
+  if (decision === 'yield') {
+    endShellSelectApplyActive()
+    return
+  }
+  if (decision === 'runtime-disable') {
+    endShellSelectApplyActive()
+    void runtimeTakeover(ctx, config, targets).catch((error) => {
+      recordTakeover({ error: String(error?.message ?? error) })
+    })
+    return
+  }
+  // takeover / await-exit:官方行已禁(或缺席),直接接管
+  if (decision === 'await-exit') {
+    const entries = Object.values(states).filter((row) => row.present).map((row) => row.entry)
+    const exited = await awaitOfficialExit(entries)
+    if (!exited) {
+      ctx.logger.warn('shell-select: 官方行退场超时,放弃接管(官方仍在服务);重启后由行树声明态收敛')
+      recordTakeover({ event: 'await-exit 退场超时,放弃挂载' })
+      endShellSelectApplyActive()
+      return
+    }
+  }
+  await mountExecutor(ctx, config)
+  recordTakeover({ event: 'executed=mounted' })
+  endShellSelectApplyActive()
+}
+
+/** volatile ref 解包成挂载/刷新快照(深拷切断冻结产物,见 mountExecutor 注释)。 */
+function unwrapConfigSnapshot(config) {
+  const unwrap = (value) => {
+    const raw = typeof value?.get === 'function' ? value.get() : value
+    return raw !== null && typeof raw === 'object' ? structuredClone(raw) : raw
+  }
+  const section = { ...config }
+  for (const key of Object.keys(section)) section[key] = unwrap(section[key])
+  return section
+}
+
+/**
+ * 挂载执行器(注册 ctx.shell 服务、shell 工具与 systemPrompt 段,均随本行
+ * fiber 卸载自动清理)。行 config 的 volatile 字段是响应式 ref(get() 协议):
+ * 挂载前解包成快照——子行管线(ShellSelectExecutor static Config)是纯
+ * schemastery,不认 ref,透传 ref 容器直接撞 "expected array but got
+ * [object Object]" 拒挂(真机实证);解包产物必须 structuredClone:ref
+ * .get() 返回 cosmokit snapshot 深冻结对象,cordis 挂载管线对 section 原地
+ * resolve,冻结 env 直接炸 "Cannot assign to read only property" 并触发
+ * 接管回滚。快照的陈旧由 apply 里的 loader/volatile-update 监听补偿:
+ * volatile-only 变更宿主换值后发事件不重挂行,监听器现取 ref 解包成新
+ * 快照经 ctx.shell.refresh 换源并重建工具。
+ */
+async function mountExecutor(ctx, config) {
+  // 用户声明值挂载前 coercing:任意配置(坏类型/空 shells/悬空 default/坏
+  // deny 正则)降级为可服务配置 + 逐条告警,行永不因配置死(官方链兜底之外
+  // 的第一道本体防线)
+  const { config: coerced, warnings } = coerceServiceable(unwrapConfigSnapshot(config))
+  for (const warning of warnings) ctx.logger?.warn?.(`shell-select: ${warning}`)
+  const fiber = await ctx.plugin(ShellSelectExecutor, coerced)
+  // await 返回 ≠ 激活:executor inject 的宿主服务缺失时 fiber 静默 pending
+  // (不 provide 不报错),ctx.shell 空缺会被官方复活行补位——挂载必须核实
+  // 激活态,未激活按失败处理(触发回滚,官方接管)
+  if (fiber?.state !== 2) {
+    const waiting = fiber?.inject ? Object.keys(fiber.inject).join(',') : '?'
+    throw new Error(`执行器 fiber 未激活(state=${fiber?.state},inject=${waiting})`)
+  }
+}
+
+/**
+ * runtime-disable 接管序列(apply 落定后的异步链,不阻塞 apply 生命周期):
+ * 禁用启用中的官方行 → 等双行退场 → 挂执行器。任何失败都把系统带回官方
+ * 自服务形态:禁一半(update 失败)回滚已禁行;挂载失败(官方已退场,
+ * ctx.shell 真空)回滚启用官方两行令其复活。
+ */
+async function runtimeTakeover(ctx, config, targets) {
+  const { disabled, failed } = await runtimeDisableRows(targets)
+  recordTakeover({ event: `disabled=${disabled.length} updateFailed=${failed.length}` })
+  if (failed.length > 0) {
+    ctx.logger.warn(`shell-select: 官方行运行时禁用失败(${failed.length} 行),回滚并保持官方服务`)
+    await rollbackDisabledRows(disabled)
+    recordTakeover({ event: `rolledBack=${disabled.length}, 不挂载` })
+    return
+  }
+  const exited = await awaitOfficialExit(targets)
+  if (!exited) {
+    ctx.logger.warn('shell-select: 官方行退场超时,放弃接管(官方 fiber 仍在服务);重启后由行树声明态收敛')
+    recordTakeover({ event: 'runtime 退场超时,放弃挂载' })
+    return
+  }
+  try {
+    await mountExecutor(ctx, config)
+    recordTakeover({ event: 'executed=mounted' })
+    ctx.logger.warn('shell-select: 官方 pwsh 链已运行时禁用,本包执行器接管 ctx.shell 与 shell 工具')
+  } catch (error) {
+    recordTakeover({ event: `挂载失败,回滚: ${error?.message ?? error}` })
+    ctx.logger.error(`shell-select: 执行器挂载失败,回滚启用官方 pwsh 链: ${error?.message ?? error}`)
+    await rollbackDisabledRows(targets)
+  }
+}

package/src/render.mjs

@@ -14,8 +14,11 @@ function streamText(output) {
  * 前台运行结果 → 模型可见文本。
  * @param {object} result ShellRunResult(含 sandbox 事实)
  * @param {string[]} escalationModes 本组合公示的升权目标;非空时拒绝标记后附升权提示
+ * @param {string|undefined} shellId 执行事实:实际生效的客户端条目 id;缺省不落标记
+ * (渲染面与官方逐字同构)。标记居 markers 首位,官方退出/信号锚保持末行,
+ * parseExitStatus 复原不受扰;客户端半区据此校正卡片徽章(配置事后变更不溯往)。
  */
-export function renderResult(result, escalationModes = []) {
+export function renderResult(result, escalationModes = [], shellId) {
   const out = streamText(result.stdout)
   const err = streamText(result.stderr)
   let body = out
@@ -25,6 +28,7 @@ export function renderResult(result, escalationModes = []) {
   }
   if (body.length === 0) body = '(no output)'
   const markers = []
+  if (shellId !== undefined) markers.push(`[shell: ${shellId}]`)
   if (result.sandbox?.denied) {
     markers.push(sandboxDenialMarker(result.sandbox.mode))
     if (escalationModes.length > 0) markers.push(escalationHintMarker('command'))