@thincoder/core 0.10.3 → 0.10.5

package/proxy.mjs

@@ -1,264 +1,31 @@
 /**
- * proxy.mjs — Shared proxy tunnel for websearch, fetch, and provider calls.
- * Zero dependencies: Node built-ins only (net, tls, http, url).
+ * proxy.mjs — 代理出口：`injectProxy`（逐渠注入）∥ `proxyFetch`（统一出口编排；直连分支 = 断流通道建设点）
+ * + 兼容再出口（`proxy-target.mjs` ∥ `proxy-transport.mjs`——消费面 import 零改；2026-10-08 拆档 · #1037）。
+ * 零依赖：Node built-ins only（url）。
  */
-import { connect } from "node:net";
-import { connect as tlsConnect } from "node:tls";
-import { PassThrough } from "node:stream";
-import { URL } from "node:url";
-import { abortError, timeoutError } from "./abort-provenance.mjs";
-import { IDLE_ABORT, destroyBody } from "./stream-destroy.mjs";
+import { URL } from "node:url"
+import { normalizeProxy } from "./config.mjs"
+import { IDLE_ABORT } from "./stream-destroy.mjs"
+import { isLoopbackTarget, resolveProxyConfig, resolveWebProxy } from "./proxy-target.mjs"
+import { FETCH_TIMEOUT, streamHttpResponse, tcpConnectProxy, tunnelHttps } from "./proxy-transport.mjs"
 
-const FETCH_TIMEOUT = 15_000
-
-/**
- * Resolve proxy URI.
- * New format: { proxy: { uri: "http://host:port", web: true, model: false } }
- * Old format: { proxy: "http://host:port" } — backwards compatible, web=true model=false
- * Env vars: HTTPS_PROXY, HTTP_PROXY, ALL_PROXY
- *
- * @returns {{ uri: string|null, web: boolean, model: boolean }}
- */
-export function resolveProxyConfig(ctx) {
-  const cfgProxy = ctx?.agent?.config?.proxy
-  if (!cfgProxy) {
-    const uri = process.env.HTTPS_PROXY || process.env.HTTP_PROXY || process.env.ALL_PROXY || null
-    return { uri, web: !!uri, model: false }
-  }
-  if (typeof cfgProxy === "string") {
-    // Backward compat: bare string → web only
-    return { uri: cfgProxy, web: true, model: false }
-  }
-  return {
-    uri: cfgProxy.uri || cfgProxy.url || null,
-    web: cfgProxy.web !== false,
-    model: cfgProxy.model === true,
-  }
-}
-
-/** Convenience: resolve proxy URI for web tools (websearch/fetch) */
-export function resolveWebProxy(ctx) {
-  const cfg = resolveProxyConfig(ctx)
-  return (cfg.uri && cfg.web) ? cfg.uri : null
-}
+export { isLoopbackTarget, resolveProxyConfig, resolveWebProxy, streamHttpResponse, tunnelHttps }
 
 /**
  * Inject the resolved proxy URI into each provider as provider.proxyUri
  * (consumed by chat() in provider/core.mjs).
- * Model 请求走代理需要双重开启：per-provider `proxy: true` 且全局 `config.proxy.model === true`（默认关）。
+ * 逐渠独立：per-provider `proxy: true` ∧ **在案** `proxy.uri` ⇒ 注入（无全局闸——D-PX1，2026-10-08）。
+ * env 回落不供模型代理（D-PX4）：盘上 `proxy` 字段缺席 ⇒ 零注入（web 面 env 回落照旧——`resolveWebProxy`）。
+ * 判定归一化单源 = `normalizeProxy`（#1082，2026-10-10）：`""` ∥ 空对象 ∥ 非法型 ⇒ 零注入（`!= null` 过闸后
+ * 的 env 回供理论口封死——模型代理永不吃 env）。
  */
 export function injectProxy(providers, config) {
-  const { uri, model } = resolveProxyConfig({ agent: { config } })
+  const uri = normalizeProxy(config?.proxy)?.uri ?? null
   for (const p of providers ?? []) {
-    p.proxyUri = p.proxy && model ? (uri ?? undefined) : undefined
+    p.proxyUri = p.proxy && uri ? uri : undefined
   }
 }
 
-/**
- * 在已建立的 socket 上发 HTTP 请求，响应头到齐即 resolve（流式）。
- * 返回 Response-like: { ok, status, headers: Headers, body: PassThrough(异步迭代), text(): Promise<string> }
- * body 边收边吐（SSE 流式消费方可逐 chunk 读取）；text() 消费流到底（非流式调用方用）。
- * opts.signal 全程有效：abort 即 destroy socket 并 reject/终止流。
- * absoluteForm: 请求行发绝对 URI（http:// 目标的经典代理转发用），默认发 origin-form。
- * 2026-08-31 会诊 #4：timeout 只覆盖"响应头阶段"；settle 后 body 空闲 > bodyIdleMs 即
- * 断流（原实现头部 timer 到齐即清，流式中途停摆会无限挂起直到用户 Ctrl+C）。
- * bodyIdleMs 默认 120s（provider 长生成用 0 即禁用，由调用方决定）。
- * 导出供测试（裸 socket，无需 TLS/CONNECT）；生产路径走 tunnelHttps / proxyFetch。
- */
-export function streamHttpResponse(sock, urlStr, opts = {}, timeout = FETCH_TIMEOUT, absoluteForm = false, bodyIdleMs = 120_000) {
-  return new Promise((resolve, reject) => {
-    const target = new URL(urlStr)
-    const method = opts.method ?? "GET"
-    const headers = opts.headers ?? {}
-    const signal = opts.signal
-
-    if (signal?.aborted) { sock.destroy(); return reject(abortError(signal, "provider", "proxy")) }
-
-    const body = new PassThrough()
-    let settled = false
-    let headerBuf = ""
-    let idleTimer = null
-
-    const timer = setTimeout(() => fail(timeoutError("Response timeout", "provider", "proxy-header")), timeout)
-    const onAbort = () => { sock.destroy(); fail(abortError(signal, "provider", "proxy")) }
-    signal?.addEventListener("abort", onAbort, { once: true })
-
-    function cleanup() {
-      clearTimeout(timer)
-      clearTimeout(idleTimer)
-      signal?.removeEventListener("abort", onAbort)
-    }
-    /** 头部阶段失败 reject；resolve 后失败则终止 body 流（for-await 抛出，不挂起） */
-    function fail(err) {
-      cleanup()
-      if (!settled) { settled = true; reject(err) }
-      else destroyBody(body, err)
-    }
-    /** body 阶段空闲看门狗：每次数据到达重置；无数据超时 → 断流（流式消费方抛错） */
-    function armIdle() {
-      clearTimeout(idleTimer)
-      if (bodyIdleMs > 0) idleTimer = setTimeout(() => destroyBody(body, timeoutError("Response body timeout (idle)", "provider", "proxy-body-idle")), bodyIdleMs)
-    }
-
-    sock.on("data", (d) => {
-      if (settled) return // 理论上不会发生（settle 后摘掉本监听器），防御
-      headerBuf += d.toString("utf8")
-      const idx = headerBuf.indexOf("\r\n\r\n")
-      if (idx < 0) return
-
-      const headerText = headerBuf.slice(0, idx)
-      const statusMatch = headerText.match(/^HTTP\/\d\.\d (\d+)/)
-      const status = statusMatch ? Number(statusMatch[1]) : 502
-      const respHeaders = {}
-      for (const line of headerText.split("\r\n").slice(1)) {
-        const ci = line.indexOf(":")
-        if (ci > 0) respHeaders[line.slice(0, ci).trim().toLowerCase()] = line.slice(ci + 1).trim()
-      }
-
-      // 头到齐：摘掉头阶段监听，剩余字节推入 body，后续数据直接 pipe
-      sock.removeAllListeners("data")
-      settled = true
-      cleanup()
-      armIdle()
-      const remaining = headerBuf.slice(idx + 4)
-      if (remaining) body.write(Buffer.from(remaining, "utf8"))
-      sock.pipe(body)
-      // 空闲看门狗随数据到达重置。注意必须用 'readable' 而非 'data'：
-      // 'data' 监听把流切成 flowing 模式，会抢走 readSSE/for-await 未来得及认领的
-      // 已写缓冲（2026-08-31 实测：分包响应头的 remaining 首段被吞，readSSE 等不到 ack）。
-      // 'readable' 不改变流模式，数据仍由消费方按需拉取。
-      body.on("readable", armIdle)
-      // body 结束后才移除 abort 监听（流式中途 abort 要能终止流）；空闲看门狗一并清
-      body.on("close", () => {
-        clearTimeout(idleTimer)
-        signal?.removeEventListener("abort", onAbort)
-      })
-      signal?.addEventListener("abort", onAbort, { once: true })
-
-      resolve({
-        ok: status >= 200 && status < 400,
-        status,
-        headers: new Headers(respHeaders),
-        body,
-        text: async () => {
-          const chunks = []
-          for await (const c of body) chunks.push(c)
-          return Buffer.concat(chunks).toString("utf8")
-        },
-      })
-    })
-    sock.on("close", () => {
-      if (!settled) fail(new Error("Connection closed before response"))
-      else body.end()
-    })
-    // 头部阶段的传输错误统一包装为稳定契约（对端 RST 会抛原生 ECONNRESET，调用方难判别）；
-    // resolve 后的 body 阶段保留原始错误终止流
-    sock.on("error", (e) => {
-      if (!settled) fail(new Error(`Connection closed before response (${e.code ?? e.message})`))
-      else fail(e)
-    })
-
-    // 写请求（absoluteForm：代理转发时请求行为绝对 URI）
-    const requestTarget = absoluteForm ? urlStr : `${target.pathname}${target.search}`
-    const lines = [`${method} ${requestTarget} HTTP/1.1`]
-    for (const [k, v] of Object.entries({ ...headers, Host: target.hostname })) lines.push(`${k}: ${v}`)
-    lines.push("Connection: close", "", "")
-    sock.write(lines.join("\r\n"))
-    if (opts.body) sock.write(opts.body)
-  })
-}
-
-/**
- * HTTPS request through HTTP CONNECT proxy tunnel.
- * CONNECT + TLS 建立后交给 streamHttpResponse — 响应头到齐即 resolve，body 为流式。
- * 2026-08-31 会诊 #1/#4：
- *  - TLS 默认全量证书校验（rejectUnauthorized: true）——走代理的流量（含 API key）
- *    不得在未验证链路上传输；确需自签/内网代理时 opts.insecureTls=true 显式放行。
- *  - CONNECT/TLS 阶段用 timeout（默认 15s，建隧道快）；**响应头超时**用
- *    opts._headerTimeoutMs（默认 60s）——原实现共用 15s，DeepSeek 排队 TTFB>15s
- *    即误报 "Response timeout"，与直连 600s 语义割裂。
- */
-export function tunnelHttps(urlStr, opts, proxyUri, timeout = FETCH_TIMEOUT) {
-  return new Promise((resolve, reject) => {
-    let target, proxy
-    try {
-      target = new URL(urlStr)
-      proxy = new URL(proxyUri)
-    } catch {
-      // 融合（§2.5 #74——取双侧并集）：VSC 侧的**坏代理串友好报错**并入核内——
-      // 原生 `Invalid URL` 不解释期望形态，调用方拿到的可观测文案退化。
-      return reject(new Error(`Invalid proxy URI: "${proxyUri}" — expected http://host:port`))
-    }
-    const signal = opts?.signal
-    const headerTimeoutMs = Number.isFinite(opts?._headerTimeoutMs) ? opts._headerTimeoutMs : 60_000
-    const bodyIdleMs = opts?._bodyIdleMs ?? 120_000
-
-    if (signal?.aborted) return reject(abortError(signal, "provider", "proxy"))
-
-    const sock = connect({ host: proxy.hostname, port: Number(proxy.port) || 3128 })
-    const timer = setTimeout(() => { sock.destroy(); reject(new Error("Proxy CONNECT timeout")) }, timeout)
-    const onAbort = () => { sock.destroy(); reject(abortError(signal, "provider", "proxy")) }
-    signal?.addEventListener("abort", onAbort, { once: true })
-    sock.on("connect", () => sock.write(`CONNECT ${target.hostname}:${target.port || 443} HTTP/1.1\r\nHost: ${target.hostname}\r\n\r\n`))
-
-    let buf = ""
-    sock.on("data", d => {
-      buf += d.toString()
-      const end = buf.indexOf("\r\n\r\n")
-      if (end < 0) return
-      const statusLine = buf.slice(0, end).split("\r\n")[0]
-      buf = buf.slice(end + 4)
-      if (!statusLine.includes("200")) { sock.destroy(); clearTimeout(timer); return reject(new Error(`Proxy CONNECT: ${statusLine}`)) }
-      sock.removeAllListeners("data"); clearTimeout(timer)
-
-      // 安全默认：TLS 全量校验。企业中间人代理场景显式 opts.insecureTls=true 才放行。
-      const tlsSock = tlsConnect({ socket: sock, servername: target.hostname, rejectUnauthorized: opts?.insecureTls !== true })
-      if (buf) tlsSock.unshift(Buffer.from(buf))
-      tlsSock.on("secureConnect", () => {
-        // TLS 之后的请求/响应阶段：abort 交由 streamHttpResponse 接管
-        signal?.removeEventListener("abort", onAbort)
-        streamHttpResponse(tlsSock, urlStr, opts, headerTimeoutMs, false, bodyIdleMs).then(resolve, reject)
-      })
-      tlsSock.on("error", e => { sock.destroy(); reject(e) })
-    })
-    sock.on("error", e => { clearTimeout(timer); reject(new Error(`Proxy CONNECT failed (${e.code ?? e.message})`)) })
-    // 代理干净 FIN 关闭（无 error）时也要 reject，不能卡满超时
-    sock.on("close", () => { clearTimeout(timer); reject(new Error("Proxy connection closed before tunnel established")) })
-  })
-}
-
-/** TCP 直连代理（http:// 目标的经典转发用）：超时/abort/对端关闭都有稳定 reject */
-function tcpConnectProxy(proxyUri, signal, timeout) {
-  return new Promise((resolve, reject) => {
-    let proxy
-    try {
-      proxy = new URL(proxyUri)
-    } catch {
-      // 融合（§2.5 #74）：同 tunnelHttps——坏代理串友好报错。
-      return reject(new Error(`Invalid proxy URI: "${proxyUri}" — expected http://host:port`))
-    }
-    const sock = connect({ host: proxy.hostname, port: Number(proxy.port) || 3128 })
-    if (signal?.aborted) { sock.destroy(); return reject(abortError(signal, "provider", "proxy")) }
-    const onAbort = () => sock.destroy()
-    signal?.addEventListener("abort", onAbort, { once: true })
-    const timer = setTimeout(() => { sock.destroy(); reject(new Error("Proxy CONNECT timeout")) }, timeout)
-    const onError = (e) => { clearTimeout(timer); reject(new Error(`Proxy CONNECT failed (${e.code ?? e.message})`)) }
-    const onClose = () => {
-      clearTimeout(timer)
-      reject(signal?.aborted ? abortError(signal, "provider", "proxy") : new Error("Proxy connection closed before tunnel established"))
-    }
-    sock.once("connect", () => {
-      clearTimeout(timer)
-      signal?.removeEventListener("abort", onAbort)
-      sock.removeListener("error", onError)
-      sock.removeListener("close", onClose)
-      resolve(sock)
-    })
-    sock.once("error", onError)
-    sock.once("close", onClose)
-  })
-}
-
 /**
  * Generic fetch with proxy support.
  * No proxy → native fetch. Proxy + HTTPS → CONNECT tunnel. Proxy + HTTP → 经典代理转发（绝对 URI 请求行）。
@@ -267,6 +34,8 @@ function tcpConnectProxy(proxyUri, signal, timeout) {
  * （`readSSE` ∥ `parseGeminiStream`）经 `terminateBody` 恢复有效；proxy 两分支不挂（自有 `_bodyIdleMs`）。
  */
 export async function proxyFetch(urlStr, opts, proxyUri) {
+  // Loopback 目标永不经代理（NO_PROXY 语义——#1026：本地网关被塞进代理 ⇒ 403 假红）：
+  if (proxyUri && isLoopbackTarget(urlStr)) proxyUri = null
   if (!proxyUri) {
     const idleAbort = new AbortController()
     const signal = opts?.signal ? AbortSignal.any([opts.signal, idleAbort.signal]) : idleAbort.signal

package/session-gc.mjs

@@ -130,7 +130,7 @@ export async function gcResidue({ dir = sessionsDir(), prefix, now = Date.now(),
   return result
 }
 
-/** ② 显式面清运腿（§6.12 / §6.17 补充——存量通路）：全目录孤儿 sidecar 记录目录
+/** ② 显式面清运分支（§6.12 / §6.17 补充——存量通路）：全目录孤儿 sidecar 记录目录
  *（`{prefix}.{N}.d`——主文件不存在 ∧ 该槽非活跃）⇒ 逐条**回收**（rename 进 `sessions-trash/<批次>/`，同 ① 语义）。
  *  与 ① 两面之差：① = 自动面（单前缀 / 当前 cwd / **带 30 天保留期**——只治本前缀未来新增）；
  *  本函数 = **用户显式面**（跳前缀遍历全目录 / **不设保留期**——存量孤儿跨多前缀且多为近期孤儿，
@@ -355,7 +355,7 @@ export async function runSessionGc(args, { dir = sessionsDir(), prefix = null, c
     }
     out(`Moved ${r.deleted.length} files for ${t.hash} into the recycle bin (${r.batch})${r.skipped?.length ? ` — skipped ${r.skipped.length} (locked/racing, kept in place)` : ""}.`)
   }
-  // ② 显式面清运腿（孤儿 sidecar 记录目录——存量通路；与 ① 同语义：rename 进回收批）
+  // ② 显式面清运分支（孤儿 sidecar 记录目录——存量通路；与 ① 同语义：rename 进回收批）
   if (confirmTarget === "--all" && orphanDirs.candidates.length) {
     const moved = await sweepOrphanRecordDirs({ dir, now, probeFn, entries: loopEntries })
     out(`Orphan record dirs (.d): moved ${moved.recycled.length}/${moved.candidates.length} into the recycle bin (${trashRootFor(dir)}).`)

package/session-lifecycle.mjs

@@ -20,7 +20,7 @@
 import { existsSync } from "node:fs"
 import { resolveCompactThreshold } from "./config.mjs"
 // 槽面判据单源（#841 KD-841-2：槽渠道 key 门 + 模型面序——PROVIDER.md §6.22）。
-import { resolveProviderPlan } from "./model-ref.mjs"
+import { hasKey, resolveChannelModel, resolveProviderPlan } from "./model-ref.mjs"
 import {
   slotPath, loadManifest, saveManifest, slotDigest, writeSessionFile, getSessionId,
   writeEndMarker, sessionEnd, ownerPid, ownerPids,
@@ -77,10 +77,10 @@ function stripTruncatedToolArgs(m) {
  *
  *  MODEL-MERGE-SESSION（F-4）applySession 重写为两支 + 删旧支（评审 #7/#9 措辞——防
  *  "三支"误读）：
- *  ① 槽 provider 存在 → provider/model 按槽值设（双字段恒非空——模型取 data.activeModel（**串值**；
- *     非串 ∕ null ∕ 空串 = 未登记 ⇒ 回该渠道默认模型 `providers[].model` 单值——2026-09-10 MODEL-SELECTION
- *     v2；老 models[] 首候选形态已退场）+ 重算
- *     compactThreshold（auto 时——按恢复后模型）——不看 config（defaultModel 只是新会话起点）；
+ *  ① 槽 provider 存在 → provider/model 按槽值设（模型链 = 槽模型 → `defaultModel` 属本渠道 ⇒ 其模型段；
+ *     两档皆无 ⇒ `null`——2026-10-09 清除批：原 `providers[].model` 回落退场；`defaultModel` 经
+ *     `resolveProviderPlan` 参与模型面）+ 重算
+ *     compactThreshold（auto 时——按恢复后模型）；
  *  ② 槽 provider 没了 → D-S3 保留——静默保持现状（config 有效则有效——两方都无效由调用侧
  *     复验 validateProvider 弹重选）。
  *  删旧支："activeModel==null 清 stale override 回渠道默认"——前提 = 渠道默认字段——已随
@@ -172,8 +172,8 @@ export function applySession(agent, data, opts = {}) {
   if (slotPlan.source === "slot") {
     const slotProvider = agent.providers?.find((pr) => pr.name === slotPlan.channel)
     // ① 槽 provider 存在 → 按槽值设（不看 config）：双字段恒非空。
-    //    模型面序（#841）：槽模型 → `defaultModel` 属本渠道 ⇒ 其模型段 → 渠道默认单值
-    //    （`providers[].model`）；三档皆无 ⇒ `null`（不落 model 键——下游沿既有「model 缺失」处置）。
+    //    模型面序（#841）：槽模型 → `defaultModel` 属本渠道 ⇒ 其模型段；两档皆无 ⇒ `null`（不落
+    //    model 键——下游沿既有「model 缺失」处置；渠道单值模型退场——2026-10-09 清除批）。
     //    F-2d（MODEL-400-FIX）径保留：空串 / 非串槽模型同样兜（#638 非串 = 未登记）——slotPlan.model
     //    已按同归一出值（单源，无第二判据）。
     const prevName = agent.activeProvider
@@ -379,21 +379,25 @@ export function slotOccupancy(cwd, slot) {
  *  读数百分数（整数）。与 `applySession` 后读数**同源同式**（四事同判——组合既有件，零新公式）：
  *  ① 线选 = `contextHistory` 非空取之，否则 `history` 经 `stripTruncatedToolArgs` 回退（同 applySession）；
  *  ② 回声归并 = `mergeAdjacentAssistantEchoes`（同 applySession 装线前一步）；
- *  ③ 渠道合并 = `providers` 命中 `data.activeProvider` ⇒ 串值 `activeModel` 覆盖 `entry.model`（非串 ∕
- *     空串 = 未登记 ⇒ 回退 `entry.model`——模型合并支 ① 同归一）；未命中 ⇒ `fallback`（支 ②「静默保持现状」的装配口径 = `loadConfig().provider`）；
+ *  ③ 渠道合并 = `providers` 命中 `data.activeProvider` ⇒ 槽模型（串值 `activeModel`；非串 ∕ 空串 = 未登记
+ *     ⇒ 落链）∥ 无槽模型 ⇒ 现行模型链回落（`defaultModel` 属本渠道 ⇒ 其模型段；两档皆无 ⇒ `null`——
+ *     `resolveChannelModel`，2026-10-09 清除批：渠道单值模型退场，零静默回落）；未命中 ⇒ `fallback`
+ *     （支 ②「静默保持现状」的装配口径 = `loadConfig().provider`）；
  *  ④ 公式 = `historyPercent`（`thincoder-core/token-window.mjs`——与 CLI 状态行 / VSC 同式）。
- *  **零副作用**：`data` / `providers` / `fallback` 皆入参（不读盘、不写盘、不改任何进程态）；
+ *  **零副作用**：`data` / `providers` / `fallback` / `defaultModel` 皆入参（不读盘、不写盘、不改任何进程态）；
  *  `data` 非对象 ⇒ `0`（与空历史同值——「非正 ⇒ 零节点」显示门归端侧，沿 `historyPercent` 空历史口径）。 */
-export function sessionReading(data, { providers, fallback } = {}) {
+export function sessionReading(data, { providers, fallback, defaultModel } = {}) {
   if (data === null || typeof data !== "object") return 0
   const full = Array.isArray(data.history) ? data.history : []
   const ch = data.contextHistory
   const machine = (Array.isArray(ch) && ch.length > 0) ? ch : full.map(stripTruncatedToolArgs)
   const line = mergeAdjacentAssistantEchoes(machine)
-  const entry = data.activeProvider ? providers?.find((pr) => pr.name === data.activeProvider) : null
-  // #638：非串 `activeModel` 归一（与 applySession 模型合并支 ① 同判）——脏值不达 `historyPercent`。
+  const entry = data.activeProvider ? providers?.find((pr) => pr.name === data.activeProvider && hasKey(pr)) : null
+  // #638：非串 ∕ 空串 `activeModel` 归一（与 applySession 模型合并支 ① 同判）——脏值不达 `historyPercent`；
+  // 未登记 ⇒ 落现行模型链（`defaultModel` 属本渠段 ∥ `null`——渠道单值退场，2026-10-09 清除批）。
+  const slotModel = (typeof data.activeModel === "string" && data.activeModel) ? data.activeModel : null
   const provider = entry
-    ? { ...entry, model: (typeof data.activeModel === "string" && data.activeModel) ? data.activeModel : entry.model }
+    ? { ...entry, model: slotModel ?? resolveChannelModel(entry, defaultModel ?? null) }
     : fallback
   return historyPercent(line, provider)
 }

package/session-slot-claims.mjs

@@ -16,7 +16,7 @@
  * `unknown`（探测失败 / 缺行）⇒ 不认领 / 不判死 / 不删（D-MI10）。
  */
 import { existsSync } from "node:fs"
-// 探测束（判活）+ 属主三态判据 / 死主判定（本档零自有 exec——判据面与探测面分离）。
+// 探测束（判活）+ 属主三态判据 / 死主判定（本档零自有 exec——判据与探测面分离）。
 import { probeOwnersSync, ownerState, filterDeadOwners } from "./process-probe.mjs"
 // 存储原语（路径 / 原子写 / 进程 sessionId）——静态环见头注。
 import { getSessionId, manifestPath, slotPath } from "./session-slots.mjs"
@@ -210,7 +210,7 @@ export const _releaseStats = { calls: 0 }
  *  早退面：磁盘无 manifest ⇒ `existsSync` 单条目早退**零写**（不造盘面）；本进程无认领 ⇒
  *  零写返回 false。失败容忍（F-XR1「退出恒达」）：整体 try/catch **永不抛出**，返回 boolean
  *  （true = 有释放且落盘成功；false = 早退 / 失败 / **写面拒写**——`saveManifest` 返回值透传，
- *  §6.23 判据句 3——断言面）；写失败盘面 = 认领残留 →
+ *  §6.23 判据句 3——断言）；写失败盘面 = 认领残留 →
  *  恢复走既有探测面（现状形态，数据零险）。 */
 export function releaseClaimsAll(cwd) {
   _releaseStats.calls += 1

package/session-slots-manifest.mjs

@@ -1,7 +1,7 @@
 /**
  * session-slots-manifest.mjs — 清单 / 认领 / 属主面（init-block 批 · F-MI7 拆分：
  * `session-slots.mjs` 探测束接线后实读 517 行，破 490 判定线并越 500 硬限 ⇒ 按
- * `CORE-UNIFICATION.md` §2.8.1 表第 3 行随批执行外提；各函数语义**原样**迁移）：
+ * `CORE-UNIFICATION.md` §2.8.1 子表原行 3（已随 2026-10-08 批清账）随批执行外提；各函数语义**原样**迁移）：
  * 摘要面（`extractSlotMeta` / `slotDigest`）· 清单读写（`loadManifest` / `saveManifest`）·
  * 属主面（`ownerPid` / `ownerPids` / `ownerStateOf` / `ownerArgs` / `cleanDeadOwners`）·
  * 认领面（`ensureActive` / `allocateFresh` / `claimSlot` / `activeSlot` / **认领释放集

package/session-slots.mjs

@@ -4,7 +4,7 @@
  * re-export 全部导出以保持既有 import 兼容）。
  *
  * init-block 批 · F-MI7 二次拆分：探测束接线后本档实读 517 行（破 490 判定线并越 500 硬限）
- * ⇒ 按 `CORE-UNIFICATION.md` §2.8.1 表第 3 行**随批**外提清单 / 认领 / 属主面至
+ * ⇒ 按 `CORE-UNIFICATION.md` §2.8.1 子表原行 3（已随 2026-10-08 批清账）**随批**外提清单 / 认领 / 属主面至
  * `session-slots-manifest.mjs`（语义原样迁移；本档 re-export 该档导出保既有 import 面——
  * 消费档 import 路径与名面不动）。本档保留 = 存储原语（cwd 哈希 / 路径 / 原子写 / 进程
  * sessionId）· 端记录（end marker）· 列表面（listSlots——条目集 = 盘面实读；扫描面住
@@ -33,14 +33,14 @@ import { join, dirname, basename } from "node:path"
 import { configDir } from "./config.mjs"
 import { migrateHashLength } from "./session-migrate.mjs"
 // §6.10 D-2（2026-09-05）：resumeSlot 决策归本文件（slot/claim 层）；data 层读（loadSlotFile/
-// legacy 过滤）属 session.mjs（500 行内不迁移）——静态环（本档 ↔ session.mjs；init-block 批起
+// legacy 过滤）属 session.mjs（800 行内不迁移）——静态环（本档 ↔ session.mjs；init-block 批起
 // 另加本档 ↔ session-slots-manifest.mjs，见头注与 L38-47）：函数声明实例化期已初始化、只函数
 // 体内运行时使用（环安全）；VS Code 端 session-slots ↔ session-io 同构镜像。
 import { loadSlotFile, isLegacyTransient } from "./session.mjs"
 // TUI-OOM-ROOTCAUSE 批（SESSION.md §6.14 生命周期联动）：删槽联动记录存储（store 零项目内依赖——无环）。
 import { unlinkRecordStore } from "./session-store.mjs"
 // 探测束（init-block 批 · F-MI7）：实现 / 判据单源住 process-probe.mjs——本档零自有 exec、
-// 零逐 pid 探测（判据面与探测面分离）；单 pid 判活 re-export 见下方「判活兼容面」。
+// 零逐 pid 探测（判据与探测面分离）；单 pid 判活 re-export 见下方「判活兼容面」。
 import { probeOwnersAsync, isProcessAlive } from "./process-probe.mjs"
 // 清单 / 认领 / 属主面（init-block 批外提——双向静态环见头注）：本档 import 取用 + re-export
 // 保既有 import 面（消费档路径与名面不动）。

package/shell-identity.mjs

@@ -0,0 +1,107 @@
+/**
+ * shell-identity.mjs — bash 工具**执行器身份**探测单源（bash-executor-face 批 · 台账 #922——
+ * 设计权威 = `docs/core/design/BASH-EXECUTOR-FACE.md` §2 契约 + §3.1）。
+ *
+ * 探测源 = **spawn 同链镜像**（`tools/bash.mjs` spawn 的 `shell` 参数计算式）：
+ *   config.shell（trim 后非空即用）→ win32 %COMSPEC% → 兜底字面 `cmd.exe`；
+ *   非 win32 = `process.env.SHELL` → 兜底 `/bin/sh`（Node `shell:true` 兜底的事实陈述，非平台推断）。
+ * 探测值 = 实际执行器（不是环境快照）；探测不到（识别表未命中知名字）⇒ `unknown` 中性句
+ * （fail-open 零猜测——用户 2026-10-04 22:48 裁定③）；**零静态平台默认**（裁定①）。
+ *
+ * memo（进程生命周期 + 按配置值键控）先例 = `shell-candidates.mjs`（「shell 路径不热变化」同判据）；
+ * 配置值变化 ⇒ memo 未命中重探（K2 配置变更刷新 ∥ 裁定①零静态同时成立）。
+ * 测试缝 `_setComSpecForTest` 先例 = `shell-candidates.mjs:34` `_setShellDetectForTest`。
+ */
+
+// 识别表（raw 尾段词 → 显示名 + 语法族）。匹配大小写不敏感，尾段词先剥 `.exe` 后缀（U3——
+// `bash.exe` ∥ `cmd.exe` ∥ `pwsh.exe` 均须命中）；序 = 最特异优先：
+// `pwsh` 先于 `powershell`；`sh` 排末（防 `fish` 尾段误命中——fish 自目在前）。
+const IDENTITY_TABLE = Object.freeze([
+  { word: "pwsh", name: "PowerShell (pwsh)", kind: "powershell" },
+  { word: "powershell", name: "Windows PowerShell", kind: "powershell" },
+  { word: "cmd", name: "cmd.exe", kind: "cmd" },
+  { word: "bash", name: "bash", kind: "posix" },
+  { word: "wsl", name: "wsl", kind: "posix" },
+  { word: "fish", name: "fish", kind: "posix" },
+  { word: "zsh", name: "zsh", kind: "posix" },
+  { word: "sh", name: "sh", kind: "posix" },
+])
+
+/** 尾段词：raw 的最后一段非空词，剥尾 `.exe`（`C:\\...\\bash.exe` → `bash`；`pwsh` → `pwsh`）。 */
+function lastWord(raw) {
+  const parts = String(raw).trim().split(/[\\/:]+/).filter(Boolean)
+  const tail = parts[parts.length - 1] ?? ""
+  return tail.toLowerCase().replace(/\.exe$/i, "")
+}
+
+/**
+ * 探测执行器身份。`configShell` = spawn 侧同一取值（`ctx.agent?.config?.shell ?? null`）。
+ * 纯函数（不读环境外的状态；win32 分支内读 `%COMSPEC%`）；memo 按配置值键控。
+ * @param {string|null|undefined} configShell
+ * @returns {{ raw: string, name: string, kind: "cmd"|"powershell"|"posix"|"unknown", known: boolean }}
+ */
+export function resolveShellIdentity(configShell) {
+  const key = configShell == null ? null : String(configShell)
+  if (_memo.key === key) return _memo.value
+
+  // 链 = spawn 侧同式：config.shell trim 后非空即用 → 空/缺省时 win32 读 %COMSPEC%（兜底字面
+  // cmd.exe）∥ 非 win32 读 SHELL（兜底 /bin/sh）——探测值 = 实际执行器。
+  const trimmed = key == null ? "" : key.trim()
+  let raw
+  if (trimmed) {
+    raw = trimmed
+  } else if (process.platform === "win32") {
+    const comspec = _comSpecOverride !== null ? _comSpecOverride : process.env.ComSpec
+    raw = comspec && comspec.trim() ? comspec : "cmd.exe"
+  } else {
+    const shell = process.env.SHELL
+    raw = shell && shell.trim() ? shell : "/bin/sh"
+  }
+
+  const lw = lastWord(raw).toLowerCase()
+  // pwsh 分流总则（设计档 §2）：powershell 族值面按 raw 尾段词命中 /pwsh/i 分流——
+  // 命中 ⇒ pwsh 形；未命中 ⇒ Windows PowerShell（5.x）形。kind 枚举不动（识别表单目）。
+  const pwshForm = /pwsh/i.test(lw)
+  const hit =
+    IDENTITY_TABLE.find((e) => lw === e.word) ??
+    (pwshForm ? null : IDENTITY_TABLE.find((e) => lw.endsWith(e.word)))
+  const value = hit
+    ? { raw, name: hit.name, kind: hit.kind, known: true }
+    : { raw, name: raw, kind: "unknown", known: false }
+  _memo.key = key
+  _memo.value = value
+  return value
+}
+
+/** memo（进程生命周期 ∕ 按配置值键控——本档单点持有）。 */
+const _memo = { key: undefined, value: null }
+
+/** 测试缝：注入 %COMSPEC% 读数（undefined = 复位真实环境读数）；注入即清 memo。 */
+let _comSpecOverride = null
+export function _setComSpecForTest(value) {
+  _comSpecOverride = value === undefined ? null : value
+  _memo.key = undefined
+  _memo.value = null
+}
+
+/**
+ * kind ⇒ 注入值面（一行 Executor 声明 · 设计档 §2 值面表逐字）。powershell 族按 raw 尾段词
+ * `/pwsh/i` 分流（pwsh 形 ∥ Windows PowerShell 5.x 形）；identity.kind 为 unknown ⇒ 中性句。
+ * @param {{ raw: string, name: string, kind: string, known: boolean }} identity resolveShellIdentity 出参
+ * @returns {string}
+ */
+export function executorLine(identity) {
+  const { raw, name, kind } = identity
+  switch (kind) {
+    case "cmd":
+      return "- Executor: the bash tool runs commands through Windows cmd.exe (%COMSPEC%). Use cmd syntax: && works; NUL not /dev/null; %VAR% not $VAR; no single-quote grouping. For complex logic prefer the execute tool (node)."
+    case "powershell":
+      return /pwsh/i.test(lastWord(raw))
+        ? `- Executor: the bash tool runs commands through PowerShell (pwsh; ${raw}). && and || work; %VAR% does not expand (use $VAR); cmdlets differ (Remove-Item, Copy-Item). For complex logic prefer the execute tool (node).`
+        : `- Executor: the bash tool runs commands through Windows PowerShell (${raw}). PS 5.1 has NO &&/|| (use ; or separate calls); redirection differs (2>/dev/null is invalid); cmdlets differ (Remove-Item, Copy-Item). For complex logic prefer the execute tool (node).`
+    case "posix":
+      return `- Executor: the bash tool runs commands through a POSIX shell (${raw}). Standard POSIX syntax applies ($(...), $VAR, ;, >/dev/null).`
+    default:
+      return `- Executor: the bash tool shell could not be identified (raw: ${raw}) — write portable commands and trust the command's own error output.`
+  }
+}