dsh-gitbash-shell 0.39.0 → 0.39.2

package/CHANGELOG.md

@@ -3,6 +3,84 @@
 > 倒序排列,新版本条目在最上面。条目格式:`## vX.Y.Z — YYYY-MM-DD` + 类型(feat / fix / docs / chore)+ 要点 + 相关链接。
 > 纪律见 AGENTS.md「变更记录纪律」:发版前先更新本文件并随版本提交;事故复盘、复现与真机验证记录也记在这里。
 
+## v0.39.2 — 2026-10-13
+
+**类型**:fix(route B 工具/预设生命周期、动态配置与客户端回归) / test。
+
+- **复现与裁定**:两名 Sol 分区审查、Grok 交叉反证与主代理隔离复验确认了工具面、生命周期、
+  组合、代码扫描和客户端状态转换的问题;普通子 scope 的原始冲突仍由 v0.39.1 的 `shell` 隔离修复。
+  FastCtx 全文路径回显是既定策略,不误当文件工具替换问题;minimal 的 persistent PTY 不与全工具
+  变体的执行器来源混为一谈。只修既有功能,不新增功能、改 root shell 或市场 patch。
+- **变体接线**:Windows 全工具 Git Bash 变体不再启用依赖 root PowerShell 的官方 `tool-bash`;
+  保留官方 pwsh 面,经同一行内补位通道接入私有 Git Bash 工具。minimal 的 persistent 通道保持。
+- **工具生命周期**:存活 agent 的 `pwshTool` 双向翻转同步解除/重建自身的 restrict;异步导入/
+  挂载在插件或 agent 退役后不再迟到注册;jobs 服务卸载按真实 Cordis 活跃状态恢复前台 bash。
+- **降级分支**:plain definition 的 required 标志递归转换为合法 JSON Schema;升级助手不可用
+  时仍解析并传递每会话 standing policy,不错误回退部署默认。两项为模块解析降级的受控复现,
+  不宣称本机生产已发生导入失败,也不改变 Windows 受限模式明示 unconfined 的既定取舍。
+- **预设与默认值**:串行 reconcile 退役时关闭新任务、清理晚到 register 并等待 unregister;
+  动态关闭变体在退役前迁回部署默认,避免后续新会话引用不存在的 preset。既有钉住会话不迁移。
+- **路径与终端**:run_code 扫描辨认关键字后的正则并在不确定时整份 no-op,不改正则数据;
+  FastCtx 入/出参获得 execution 上下文并服从总方言、委托与虚拟挂载开关;better-sidebar 的
+  adoptSidebar 动态翻转恢复接管前值并保护接管后的用户手选,不改变官方 autoTerminalShell
+  关后只停止未来写入的独立语义。
+- **FastCtx 错误**:子进程/写管道 error 进入初始化 Promise,失败清理 pending 计时器与连接;
+  MCP `isError:true` 按官方桥约定抛错,不再把失败包装成宿主成功 value。
+  发现与连接启动采用 single-flight,拥有在途连接并在卸载时取消/等待,不让并发 agent 的发现流程
+  覆盖已在使用的 lazy client。该丢失所有权链已用受控 MCP 传输复现,并新增关闭/晚注册回归。
+- **客户端**:设置卡所有 Hooks 在 readiness early-return 前调用;工具链进度轮询在网络/HTTP
+  暂态失败后重试,卸载或失效时取消,不因单次请求失败永久卡在忙碌状态。
+- **回归入口**:新增可移植客户端/桥/运行时/宿主回归与实际 Core preview 集成用例,接入现有
+  `npm test`/`npm run test:preview`;不新增依赖、不跳过旧断言或 Node 22 矩阵。对齐上游 v0.39.1
+  (`521be01`)后完整测试 **156/156**、实际 Core 无头 preview **14/14**、打包 dry-run 和 diff 检查
+  通过。新增执行级回归保留 #21 的 real-array glob 契约与 stringified-array 响亮拒绝;不改已发布
+  版本号、历史记录或 npm 发布流程。Grok 对修复 diff 的只读反证未发现确定遗漏。
+  首轮全量检查发现三条旧源码正则仍锁旧实现,改为对应新保护条件并补同值/手选行为测试,没有删掉
+  保护断言。原 [Issue #19](https://github.com/KannaKuron/dsh-gitbash-shell/issues/19) 和
+  [PR #20](https://github.com/KannaKuron/dsh-gitbash-shell/pull/20) 已完成;这些后续修复由新 PR 承载,
+  Windows/Linux × Node 22/24 的远端结果见其检查。preview 不等同于完整 Electron GUI 或真 MCP
+  exe 并发验收,模块解析降级使用受控夹具复现。
+
+## v0.39.1 — 2026-10-13
+
+**类型**:fix(route B 私有执行器的真实服务隔离与读取授权) / test / ci。
+
+- **根因**:普通 `ctx.plugin()` 子 fiber 只隔离副作用所有权,不隔离服务命名空间。
+  `GitBashSandboxExecutor` 仍经 `SandboxBashExecutor → LocalBashExecutor → ShellExecutor → Service`
+  注册 `shell`,与 route B 保留的 `SandboxPwshExecutor` 冲突,报
+  `service "shell" has been registered at <SandboxPwshExecutor>`;bash 工具尚未注册即中断。
+  Git Bash 路径已成功解析时同样发生,不是工具发现或路径探测问题。
+- **修复**:`mountPrivateExecutor` 仅对 `shell` 调用 `ctx.isolate('shell')`,其余宿主依赖原样继承;
+  类插件仍走官方 `plugin()` 通道,Config/volatile/static inject 与生命周期不变。
+  空 scope 通过 `get('shell')` 读取活跃私有实例,工具就绪检查用 `get('tools')`,避免
+  缺少 inject 声明的属性访问再度中断补位。失败时销毁已建 scope,成功/失败均清理挂载计时器。
+- **边界**:不撤官方 PowerShell 执行器、不改 bundle patch、不改 shell 执行/沙箱/后台协议,
+  不抬 Core 兼容下限,不发版、不触发 npm 发布。
+- **回归**:新增 5 项真实 Cordis 测试,覆盖普通子 scope 冲突、显式隔离后的 Config/inject 与
+  根 shell 保留、卸载、构造失败清理/再挂载、缺服务失败与挂载超时清理;不是仅正则源码检查。
+  既有 minimal PTY 测试的非 Windows 断言现在显式模拟 Linux,不再在恢复 win32 后误断言 `/bin/bash`。
+  首轮远端 CI 发现两项独立 error-content 测试误嵌套在父测试中,Node 22 会取消未等待的子测试;
+  恢复独立结构并保留全部断言,不跳过测试、不移除 Node 22 矩阵。
+- **验证入口**:`npm test` 合并 smoke 与真实 Cordis 回归;新增 `npm run test:preview`,通过
+  显式 `DSH_PREVIEW_HOST_DIR` 只读解析目标宿主包,在新 Context + 临时 cwd 做无头运行时 preview。
+  Windows 本机已通过:Core **0.2.1-alpha.2**,宿主 Cordis **4.0.5-alpha.1**,Node **24.13.0**;
+  原路径真实重现服务冲突,修复后 bash 出现在实际 ToolRuntime schema 中并执行
+  `command -v bash`/`uname -s`/sentinel(退出码 0),官方 pwsh 执行 `Get-Process`,
+  `pwshTool` 开/关两态与卸载恢复均通过。**不等同于完整 GUI、PTY、后台任务或受限模式验收**。
+- **CI**:新增非发布 `ci` 工作流(push 修复分支 / PR / 手动触发),Windows/Linux × Node 22/24,
+  锁定依赖、禁止生命周期脚本与可选载荷、完整测试及 `npm pack --dry-run --ignore-scripts`。
+  本机完整测试 **127/127 通过**,打包预检与 `git diff --check` 通过;远端矩阵结果见对应 PR 检查。
+  复验命令和覆盖边界见 `tests/README.md`。
+- **gb_glob 守卫封杀了上游主用法([#21](https://github.com/KannaKuron/dsh-gitbash-shell/issues/21),同日报告)**:
+  上游 `tools/list` 的 glob `pattern` 是 `string | string[]` 的 untagged enum——**数组才是主形态**
+  (schema 示例本身就是数组),v0.38.5 的只认字符串守卫把它一并拒绝;且模型常把数组 JSON 序列化后
+  传入(实测 25 次调用 24 次为 `["*.txt"]` 字符串),上游按**一个字面 glob** 匹配 → 静默返回空
+  ——恰好是守卫要防的「静默错误答案」。修法(`validateFastctxPattern`,提取为纯导出函数):
+  glob 接受非空字符串或非空字符串数组;**字符串化数组响亮报错并给出正确形状**(绝不代模型反序列化
+  ——那会掩盖错误);replace 维持单正则字符串契约;其他类型报错带类型名。gb_glob 的 description
+  增补 pattern 形状声明(模型侧修正源)。**教训**:给上游加防御守卫必须从 `tools/list` 的
+  `inputSchema` 原文出发,单一探针会误判(v0.38.5 的「静默当全部文件」实测即单一探针结论)。
+
 ## v0.39.0 — 2026-10-13
 
 **类型**:feat(架构转向:route B——插件自带 bash 工具,不再替换宿主执行器;DSH STORE 收录合规)。

package/dsh.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "dsh-external/dsh-gitbash-shell",
-  "version": "0.39.0",
+  "version": "0.39.2",
   "main": "./src/index.js",
   "description": "Windows 全模式 Git Bash:自带 bash 工具(私有 Git Bash 执行器实例,官方 PowerShell 执行器原样保留),官方四个模式经行内工具补位直接获得 Git Bash(v0.35.0 起;v0.39.0 起不再替换宿主执行器),四个 *·Git Bash 变体 preset 可开关;官方 pwsh 工具默认隐藏、开关可见(真 PowerShell);附带 gb_* FastCtx 文件工具,检测到 dsh-ops 自动让位。联动:dsh-ptc-cordis-preset(PTC 创造模式带 Git Bash 行且可去重)+ dsh-better-sidebar(终端标签自动切 Git Bash)。",
   "engines": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-gitbash-shell",
-  "version": "0.39.0",
+  "version": "0.39.2",
   "description": "Windows 上给 agent 一个真正的 Git Bash 命令工具:私有 Git Bash 执行器实例(官方 PowerShell 执行器原样保留),统一 MSYS 盘根路径方言,官方 pwsh 工具默认隐藏可开关,物化四个内置预设的 Git Bash 变体,侧栏终端接管可开关。· Give agents a real Git Bash tool on Windows: a private Git Bash executor instance (the official PowerShell executor stays untouched), a unified MSYS drive-root path dialect, an opt-in official pwsh tool, and four Git Bash preset variants.",
   "type": "module",
   "repository": {
@@ -52,7 +52,8 @@
     "icon.svg"
   ],
   "scripts": {
-    "test": "node --test tests/smoke.mjs",
+    "test": "node --test tests/smoke.mjs tests/private-executor.mjs tests/client-regressions.mjs tests/bridge-regressions.mjs tests/runtime-regressions.mjs tests/host-regressions.mjs",
+    "test:preview": "node --import ./tests/host-loader.mjs --test tests/preview.mjs tests/bridge-preview.mjs tests/runtime-preview.mjs tests/host-preview.mjs",
     "version": "node -e \"const fs=require('fs');const m=JSON.parse(fs.readFileSync('dsh.plugin.json','utf8'));const v=JSON.parse(fs.readFileSync('package.json','utf8')).version;m.version=v;fs.writeFileSync('dsh.plugin.json',JSON.stringify(m,null,2)+'\\n')\" && git add dsh.plugin.json"
   },
   "keywords": [

package/src/bash-tool.js

@@ -11,8 +11,8 @@
  * instead ships an OWN tool:
  *
  *   - the executor is a private `GitBashSandboxExecutor` instance constructed
- *     through cordis's own plugin path in a PRIVATE scope (never registered as
- *     `ctx.shell`, which stays the official PowerShell executor); it inherits
+ *     through cordis's own plugin path in a `shell`-isolated scope (never
+ *     registered as the ROOT `ctx.shell`, which stays PowerShell); it inherits
  *     the shipped bash-sandbox semantics (deadline, output capture, argv
  *     execution) and points them at Git for Windows' bash.exe;
  *   - the tool definition mirrors `@deepseek-ai/dsh-tool-bash` call-for-call
@@ -248,20 +248,29 @@ function outputSchemaSpec() {
   }
 }
 
-/** Plain JSON-schema variant of the same union (fallback when defineTool is absent). */
-function outputSchemaJson() {
-  const convert = (item) => {
-    const out = { type: item.type, additionalProperties: item.additionalProperties, properties: {} }
-    const required = []
-    for (const [key, value] of Object.entries(item.properties)) {
-      if (value.required === true) { required.push(key) }
-      const { required: _drop, ...rest } = value
-      if (rest.oneOf !== undefined) delete rest.required
-      out.properties[key] = rest
+/** Convert key-level spec flags at every depth, including union branches. */
+function schemaSpecToJson(spec) {
+  const { required: marker, ...out } = spec
+  if (Array.isArray(marker)) out.required = [...marker]
+  if (spec.properties !== undefined) {
+    const required = Array.isArray(marker) ? [...marker] : []
+    out.properties = {}
+    for (const [key, value] of Object.entries(spec.properties)) {
+      if (value.required === true && !required.includes(key)) required.push(key)
+      out.properties[key] = schemaSpecToJson(value)
     }
-    return required.length > 0 ? { ...out, required } : out
+    if (required.length > 0) out.required = required
   }
-  return { oneOf: outputSchemaSpec().oneOf.map(convert) }
+  for (const key of ['oneOf', 'anyOf', 'allOf']) {
+    if (Array.isArray(spec[key])) out[key] = spec[key].map(schemaSpecToJson)
+  }
+  if (spec.items !== undefined) out.items = schemaSpecToJson(spec.items)
+  return out
+}
+
+/** Plain JSON-schema variant of the same union (fallback when defineTool is absent). */
+function outputSchemaJson() {
+  return schemaSpecToJson(outputSchemaSpec())
 }
 
 /** The official args validation (index.ts:73). */
@@ -320,8 +329,9 @@ export function createBashToolModule({ executor, toolsModule, sandboxModule, llm
       const defaultMode = executor.sandboxMode
       const escalationReady = defaultMode !== undefined && typeof approveEscalation === 'function'
       const escalationModes = escalationReady ? ESCALATION_TARGETS : []
+      // Missing approval helpers narrow escalation, not the session's standing policy.
       const resolveSandboxPolicy = (exec) => {
-        if (!escalationReady) return undefined
+        if (defaultMode === undefined) return undefined
         const policy = ctx.get('sandboxPolicy')
         return policy ? policy.resolve(exec?.agent === undefined ? {} : { session: exec.agent.session }) : undefined
       }
@@ -548,7 +558,7 @@ export function createBashToolModule({ executor, toolsModule, sandboxModule, llm
           // keys reach execute too, where enableRunInBackground enforces them
           // ("Undeclared keys are allowed, so schema omission also needs
           // enforcement", index.ts:498).
-          parameters: { type: 'object', properties: parametersSpec(), required: ['description', 'command'] },
+          parameters: schemaSpecToJson({ type: 'object', properties: parametersSpec() }),
           output: {
             schema: outputSchemaJson(),
             render: (_args, value) => [{
@@ -580,7 +590,8 @@ export function createBashToolModule({ executor, toolsModule, sandboxModule, llm
         jobCtx.effect(() => () => {
           unregister()
           try {
-            if (ctx.fiber?.state === 'active') foregroundOnly = ctx.tools.register(bashTool(undefined))
+            // Cordis FiberState.ACTIVE is the numeric enum member 2.
+            if (ctx.fiber?.state === 2) foregroundOnly = ctx.tools.register(bashTool(undefined))
           } catch { /* the scope is going away */ }
         })
       })

package/src/client.js

@@ -2063,6 +2063,42 @@ window.__ModuleLoader__.load({
 				if (scope && typeof scope.getSnapshot === "function") snap = scope.getSnapshot();
 			} catch (error_) { /* keep unavailable */ }
 
+			var pageView = props.view === "page";
+
+			// Hooks run for every snapshot state; readiness only gates their work.
+			useEffect(function () {
+				if (snap.status !== "ready" || (!open && !pageView)) return undefined;
+				if (toolsLoaded || toolBusy) return undefined;
+				loadTools();
+				return undefined;
+			}, [open, pageView, snap.status]);
+
+			/* Poll ONLY while a job is unfinished, and through the cheap ?job=1
+			   form. A transient failure retries without discarding progress. */
+			useEffect(function () {
+				if (snap.status !== "ready" || toolJob === null || toolJob.finished) return undefined;
+				var alive = true;
+				var timer;
+				function schedule() {
+					timer = setTimeout(function () {
+						fetch(TOOLS_URL + "?job=1", { headers: { accept: "application/json" } })
+							.then(function (res) {
+								if (!res.ok) throw new Error("HTTP " + res.status);
+								return res.json();
+							})
+							.then(function (data) {
+								if (!alive) return;
+								var next = data !== null && typeof data === "object" && data.job ? data.job : null;
+								setToolJob(next);
+								if (next !== null && next.finished) loadTools();
+							})
+							.catch(function () { if (alive) schedule(); });
+					}, 1200);
+				}
+				schedule();
+				return function () { alive = false; clearTimeout(timer); };
+			}, [toolJob, snap.status]);
+
 			if (snap.status !== "ready") return null;
 
 			var value = snap.value || {};
@@ -2135,7 +2171,6 @@ window.__ModuleLoader__.load({
 			// dsh 0.1.6-alpha.2: the Plugins page renders this card through the
 			// `plugins.bundle.config` slot with view="page" — the page draws the
 			// title itself; the collapsible shell only shows on the popup seat.
-			var pageView = props.view === "page";
 
 			var mounts = snap.value.virtualMounts !== false;
 			var errs = snap.value.errorDialect !== false;
@@ -2469,30 +2504,6 @@ window.__ModuleLoader__.load({
 					.then(function () { setToolBusy(false); });
 			}
 
-			useEffect(function () {
-				if (!open && !pageView) return undefined;
-				if (toolsLoaded || toolBusy) return undefined;
-				loadTools();
-				return undefined;
-			}, [open]);
-
-			/* Poll ONLY while a job is unfinished, and through the cheap ?job=1
-			   form: a full probe re-runs three winget commands per second. */
-			useEffect(function () {
-				if (toolJob === null || toolJob.finished) return undefined;
-				var timer = setTimeout(function () {
-					fetch(TOOLS_URL + "?job=1", { headers: { accept: "application/json" } })
-						.then(function (res) { return res.json(); })
-						.then(function (data) {
-							var next = data !== null && typeof data === "object" && data.job ? data.job : null;
-							setToolJob(next);
-							if (next !== null && next.finished) loadTools();
-						})
-						.catch(function () { /* keep the last known progress */ });
-				}, 1200);
-				return function () { clearTimeout(timer); };
-			}, [toolJob]);
-
 			var toolsSection = fold("sec.tools",
 					toolsData === null && toolErr === "" ? E("p", { className: "gb-hint" }, t("tools.loading")) : null,
 					toolErr !== "" ? E("p", { className: "gb-error" }, toolErr) : null,

package/src/compositions.js

@@ -9,10 +9,10 @@
  *
  * Every variant mirrors the official 0.1.7 preset it replaces (packages/
  * bundle/web-app/presets/{standard,minimal,ptc,cordis}.patch.yml) with the
- * one Git Bash delta: the bash rows are always on and the pwsh rows are
- * always off (the plugin ships its OWN bash tool over a private executor —
- * on non-Windows hosts the official stack is native anyway, which is exactly
- * what the old materialized variants encoded). A second, conditional delta exists while
+ * Git Bash routing: full variants keep the official platform-gated shell
+ * rows, and the inline patch adds OUR bash over a private executor on Windows.
+ * The minimal variant instead keeps its persistent Git Bash terminal rows.
+ * On non-Windows hosts the official stack stays native. A conditional delta exists while
  * dsh-ptc-cordis-preset reports its experimental-CPython backend ACTIVE: the
  * two workflow rows follow the official Python composition and go off (see
  * `pythonActive` below). While that backend is off — the default, and also
@@ -56,7 +56,8 @@ const planSectionFor = (hostEra021) => hostEra021
  * @param {'standard'|'ptc'|'cordis'} input.kind - which official preset this
  *   variant mirrors (workflow rows follow it: enabled on standard/cordis,
  *   disabled on ptc).
- * @param {boolean} input.gitBash - bash rows always on, pwsh rows always off.
+ * @param {boolean} input.gitBash - retained for composition-call compatibility;
+ *   full variants obtain Git Bash from the per-agent inline patch on Windows.
  * @param {string|undefined} input.skillsDir - Creation authoring skills
  *   directory (cordis variant only; resolved beside the agent-preset package).
  * @param {boolean} [input.pythonActive] - whether the experimental CPython
@@ -75,8 +76,11 @@ const planSectionFor = (hostEra021) => hostEra021
  */
 export function pluginsFor({ kind, gitBash, skillsDir, pythonActive = false, hostExtras = {} }) {
   const win = typeof process !== 'undefined' && process.platform === 'win32'
-  const bashDisabled = gitBash ? false : win
-  const pwshDisabled = gitBash ? true : !win
+  // Route B preserves the root PowerShell executor. On Windows the official
+  // tool-bash would execute through that executor, so full variants retain the
+  // official pwsh face and let the same per-agent inline patch add OUR bash.
+  const bashDisabled = win
+  const pwshDisabled = !win
   const workflowOn = kind !== 'ptc' && pythonActive !== true
   // dsh 0.2.1 added two rows to every full-tool official preset — time-context
   // (durable clock readings) and tool-schedule (the reminder tools) — plus a

package/src/fastctx-bridge.js

@@ -106,20 +106,21 @@ export class McpStdio {
     this.child.stderr.on('data', (chunk) => {
       this.stderrTail = (this.stderrTail + chunk).slice(-2000)
     })
-    this.child.on('exit', (code) => {
-      this.dead = true
-      for (const [, { reject }] of [...this.pending]) {
-        reject(new Error(`the FastCtx server exited (code ${code ?? 'null'})`))
-      }
-      this.pending.clear()
-    })
-    await this.#request('initialize', {
-      protocolVersion: '2024-11-05',
-      capabilities: {},
-      clientInfo: { name: 'dsh-gitbash-shell', version: '0.35.0' },
-    })
-    this.#notify('notifications/initialized')
-    return this
+    this.child.on('error', (error) => this.#fail(error))
+    this.child.stdin.on('error', (error) => this.#fail(error))
+    this.child.on('exit', (code) => this.#fail(new Error(`the FastCtx server exited (code ${code ?? 'null'})`)))
+    try {
+      await this.#request('initialize', {
+        protocolVersion: '2024-11-05',
+        capabilities: {},
+        clientInfo: { name: 'dsh-gitbash-shell', version: '0.35.0' },
+      })
+      this.#notify('notifications/initialized')
+      return this
+    } catch (error) {
+      await this.close()
+      throw error
+    }
   }
 
   /** List the server's tools: [{ name, description, inputSchema }]. */
@@ -140,15 +141,21 @@ export class McpStdio {
     this.dead = true
     const child = this.child
     this.child = undefined
-    for (const [, { reject }] of [...this.pending]) {
-      reject(new Error('the FastCtx bridge was stopped'))
-    }
-    this.pending.clear()
+    this.#fail(new Error('the FastCtx bridge was stopped'))
     if (child && child.exitCode === null && !child.killed) {
       try { child.kill() } catch { /* already gone */ }
     }
   }
 
+  #fail(error) {
+    this.dead = true
+    for (const { reject, timer } of this.pending.values()) {
+      clearTimeout(timer)
+      reject(error)
+    }
+    this.pending.clear()
+  }
+
   #onChunk(chunk) {
     this.buffer += chunk
     let at = this.buffer.indexOf('\n')
@@ -209,6 +216,42 @@ export class McpStdio {
  * the fastctx shapes: `path`, `file_path`, `files[].path`, and an absolute
  * glob `pattern`. Pure.
  */
+/**
+ * Validate one pattern argument BEFORE dispatch (v0.38.5 guard, reshaped in
+ * v0.39.1 around the upstream SCHEMA — issue #21). glob's `pattern` is an
+ * untagged enum of string | string[] in tools/list (the array is the PRIMARY
+ * form — the schema's own example is an array), so a string-only check bans
+ * the main usage; and a JSON-stringified array ("[\"*.txt\"]") is matched by
+ * the upstream as ONE literal glob and silently returns nothing — the exact
+ * silent-wrong-answer this guard exists to prevent. replace's pattern is a
+ * single regex string. Pure; returns an error message or undefined.
+ * @param {string} rawName - upstream tool name ('glob' | 'replace' | ...).
+ * @param {unknown} pattern - the raw pattern argument.
+ * @returns {string|undefined}
+ */
+export function validateFastctxPattern(rawName, pattern) {
+  if (rawName !== 'glob' && rawName !== 'replace') return undefined
+  const describe = (v) => (v === null ? 'null' : Array.isArray(v) ? 'array' : typeof v)
+  if (rawName === 'replace') {
+    if (typeof pattern !== 'string' || pattern.trim() === '') {
+      return `invalid arguments: ${gbName(rawName)} pattern must be a non-empty string (got ${describe(pattern)})`
+    }
+    return undefined
+  }
+  // A stringified array would match as one literal glob and return an empty
+  // set: name the mistake, never guess the intent (un-serializing on the
+  // model's behalf would hide the error this guard is here to surface).
+  if (typeof pattern === 'string' && pattern.length >= 2 && pattern.startsWith('[') && pattern.endsWith(']')) {
+    return `invalid arguments: ${gbName(rawName)} pattern looks like a JSON-stringified array (${String(pattern).slice(0, 60)}). Pass a real array of strings (e.g. ["*.js","*.py"]) or one plain glob string — a stringified array matches nothing.`
+  }
+  const ok = (typeof pattern === 'string' && pattern.trim() !== '')
+    || (Array.isArray(pattern) && pattern.length > 0 && pattern.every((p) => typeof p === 'string' && p.trim() !== ''))
+  if (!ok) {
+    return `invalid arguments: ${gbName(rawName)} pattern must be a non-empty string or a non-empty array of non-empty strings (got ${describe(pattern)})`
+  }
+  return undefined
+}
+
 export function translateFastctxArgs(args, msysToWin) {
   if (!msysToWin || !args || typeof args !== 'object') return args
   const translate = (value) => (typeof value === 'string' ? msysToWin(value) : value)
@@ -274,6 +317,10 @@ export function mountFastctx(ctx, deps) {
   let client = undefined
   let decided = false
   let withdrawnByOps = false
+  let closed = false
+  let publishing
+  let connecting
+  const starting = new Set()
 
   const unpublish = (reason) => {
     if (disposer) {
@@ -284,16 +331,34 @@ export function mountFastctx(ctx, deps) {
   }
 
   const callWithReconnect = async (rawName, args) => {
+    if (closed || withdrawnByOps) throw new Error('the FastCtx bridge was stopped')
     if (client === undefined || client.isDead) {
-      const { file } = resolveFastctx(ctx, createRequireFrom)
-      if (file === '') throw new Error('the FastCtx payload is not installed; repair the profile dependencies (frozen install) and retry')
-      client = await new McpStdio({ file, log }).start()
+      if (!connecting) {
+        connecting = (async () => {
+          const { file } = resolveFastctx(ctx, createRequireFrom)
+          if (file === '') throw new Error('the FastCtx payload is not installed; repair the profile dependencies (frozen install) and retry')
+          const fresh = new McpStdio({ file, log })
+          starting.add(fresh)
+          try {
+            await fresh.start()
+            if (closed || withdrawnByOps) throw new Error('the FastCtx bridge was stopped')
+            client = fresh
+          } catch (error) {
+            await fresh.close()
+            throw error
+          } finally {
+            starting.delete(fresh)
+          }
+        })().finally(() => { connecting = undefined })
+      }
+      await connecting
     }
+    if (closed || withdrawnByOps) throw new Error('the FastCtx bridge was stopped')
     return client.callTool(rawName, args)
   }
 
-  const publish = async () => {
-    if (disposer || decided && withdrawnByOps) return
+  const publishOnce = async () => {
+    if (closed || disposer || decided && withdrawnByOps) return
     const registry = tools(ctx)
     if (!registry || typeof registry.register !== 'function') return
     const { file, source } = resolveFastctx(ctx, createRequireFrom)
@@ -304,6 +369,7 @@ export function mountFastctx(ctx, deps) {
       return
     }
     const fresh = new McpStdio({ file, log })
+    starting.add(fresh)
     let toolList
     try {
       await fresh.start()
@@ -314,9 +380,12 @@ export function mountFastctx(ctx, deps) {
       decided = true
       withdrawnByOps = true
       return
+    } finally {
+      starting.delete(fresh)
     }
     await fresh.close()
-    client = undefined // the first call re-launches lazily; boot stays cheap
+    if (closed || withdrawnByOps) return
+    // Discovery never overwrites the independently owned lazy call client.
     const wanted = toolList.filter((tool) => FASTCTX_FILE_TOOLS.includes(String(tool?.name)))
     const registered = []
     const registeredNames = []
@@ -334,29 +403,36 @@ export function mountFastctx(ctx, deps) {
         : rawName === 'grep'
           ? '\nIgnore rules: this tool honors .gitignore and skips .git — unlike gb_glob (bare .ignore only) and the official glob (ignores nothing).'
           : ''
+      // Pattern-shape transparency (v0.39.1, issue #21): models keep
+      // JSON-stringifying the glob array (24 of 25 measured calls), which the
+      // upstream matches as one literal glob -> silent empty. State the
+      // accepted shapes on the tool.
+      const patternNote = rawName === 'glob'
+        ? '\npattern accepts one glob string OR an array of glob strings (e.g. ["**/*.rs", "!tests/**"]). Pass a real array — never a JSON-stringified array.'
+        : ''
       try {
         const dispose = registry.register({
           name: gbName(rawName),
-          description: `${String(tool.description ?? rawName)}\n${FASTCTX_SANDBOX_NOTE}${ignoreNote}`,
+          description: `${String(tool.description ?? rawName)}\n${FASTCTX_SANDBOX_NOTE}${ignoreNote}${patternNote}`,
           parameters: schema,
           output: {
             schema: TOOL_OUTPUT_SCHEMA,
             render: (_args, value) => renderTextContent(value),
           },
-          async execute(args) {
-            // Fail LOUD on malformed patterns (v0.38.5, the field smoke
-            // report): the upstream server silently treats a non-string
-            // pattern as "everything", which turns a typo into a full-tree
-            // result set — a silent wrong answer is worse than an error.
-            if ((rawName === 'glob' || rawName === 'replace') && args !== null && typeof args === 'object' && 'pattern' in args) {
-              const pattern = args.pattern
-              if (typeof pattern !== 'string' || pattern.trim() === '') {
-                throw new Error(`invalid arguments: ${gbName(rawName)} pattern must be a non-empty string (got ${pattern === null ? 'null' : typeof pattern})`)
-              }
+          async execute(args, execution) {
+            // Preserve v0.39.1 / #21: glob accepts real string arrays,
+            // while stringified arrays and malformed patterns fail loudly.
+            if (args !== null && typeof args === 'object' && 'pattern' in args) {
+              const invalid = validateFastctxPattern(rawName, args.pattern)
+              if (invalid) throw new Error(invalid)
             }
-            const translated = translateFastctxArgs(args, msysToWin)
+            const translated = translateFastctxArgs(args, msysToWin ? (path) => msysToWin(path, execution) : undefined)
             const result = await callWithReconnect(rawName, translated)
-            return { content: [{ type: 'text', text: renderFastctxResult(rawName, result, echo) }] }
+            const text = renderFastctxResult(rawName, result, echo ? (value) => echo(value, execution) : undefined)
+            // The host treats a returned value as success; MCP failures must
+            // throw, just as its official MCP client does.
+            if (result?.isError === true) throw new Error(text)
+            return { content: [{ type: 'text', text }] }
           },
         })
         if (typeof dispose === 'function') {
@@ -377,7 +453,13 @@ export function mountFastctx(ctx, deps) {
     log(`FastCtx bridge active (${source}): ${registeredNames.join(', ')}`)
   }
 
+  const publish = () => {
+    if (!publishing) publishing = publishOnce().finally(() => { publishing = undefined })
+    return publishing
+  }
+
   const reconcile = (agent) => {
+    if (closed) return
     if (!enabled()) { unpublish('FastCtx bridge disabled by the fastctxTools switch'); decided = true; withdrawnByOps = true; return }
     if (decided && withdrawnByOps) return
     let names = []
@@ -401,8 +483,12 @@ export function mountFastctx(ctx, deps) {
     log(`FastCtx bridge wiring failed: ${error?.message ?? error}`)
     return
   }
-  ctx.effect(() => () => {
+  ctx.effect(() => async () => {
+    closed = true
     unpublish()
-    if (client) { void client.close().catch(() => {}) }
+    const owned = new Set([...starting, client].filter(Boolean))
+    await Promise.allSettled([...owned].map((connection) => connection.close()))
+    await Promise.allSettled([publishing, connecting].filter(Boolean))
+    client = undefined
   }, 'dsh-gitbash-shell: FastCtx bridge')
 }