@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/lib/stdio_utf8.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+"""stdout/stderr 的 UTF-8 安全（**唯一真源**）：中文 Windows 上别让"打印"把入口脚本打崩。
+
+## 事故（2026-10-08，Windows 装机验证）
+`flow_registry.py --json` 用 `ensure_ascii=False` 打印合并后的注册表（里面有 `⇒` U+21D2、
+`✅` U+2705 这类字符），而中文 Windows 上 **stdout 被重定向/管道**时 Python 用的是
+**locale 编码（cp936/GBK）**——PEP 528 只把**交互式控制台**改成 UTF-8，重定向后的
+stdout/stderr 仍按 locale 编码 ⇒
+
+    UnicodeEncodeError: 'gbk' codec can't encode character '\\u21d2'
+
+⇒ 脚本 exit 1、stdout 半截 ⇒ 调用它的 `scripts/argent-catalog.mjs`（以及任何
+`JSON.parse(stdout)` 的 Node 侧）**连带全挂**。同类受害面见下"覆盖范围"。
+
+## 口径：为什么是 reconfigure 而不是 `ensure_ascii=True`
+`sys.stdout.reconfigure(encoding="utf-8")` 把"用哪个编码写出去"钉死，而在**本来就是 UTF-8**
+的机器/管道上**字节层面完全不变**（同一段 JSON、同样的转义形式、同样的键序）⇒ 下游
+（`JSON.parse`、留痕比对、`sha256(stdout)` 类断言）**零感知**。
+换成 `ensure_ascii=True` 虽然也是合法 JSON，但会把非 ASCII 改成 `\\uXXXX` ⇒ **改变了
+下游看到的字节**（这也是为什么本模块不采用它）。
+`errors="backslashreplace"` 是最后一道保险：宁可把个别怪异字符（如孤立代理对）写成转义，
+也不要在**打印时崩** —— 打印崩掉是整条调用链断，代价远大于一个字符的显示问题。
+
+## 覆盖范围（"逐处核"的结论，2026-10-08）
+**已接入**（stdout 会被 Node/工具链 `JSON.parse`/解析的入口；括号内=调用方）：
+  · `scripts/flow_registry.py`（`scripts/lib/registry.mjs`、`core/lib/*.mjs`、`argent-catalog.mjs`）
+  · `scripts/capability_pack.py`（`install-argent.mjs#describeCapability`、`profile-doctor.mjs`、
+    `check-pack-closure.mjs`、`core/lib/versions.mjs`）—— 它的 `--validate/--stamp/--build`
+    会打印 ✅❌📦 等非 GBK 字符
+  · `scripts/check-model-auth.py`（装机第 7d 步，`install-argent.mjs`；`--json` 载荷里就有 U+21D2）
+  · `scripts/argent-datadir.py`（`core/lib/argent-datadir.mjs`）
+  · `scripts/fix-skill-frontmatter.py`（`core/lib/init.mjs` 安装/升级期调用）
+  · `scripts/entitlements.py`（网关插件 `--json`/`--validate`）
+  · `scripts/flow_capability_stats.py`（`plugins/argent-flow` 的 `--json`）
+**未接入**（有意，附理由）：**流程引擎运行期**脚本（`scripts/**` 里除上表之外的 Python 入口：
+流程引擎本体、各门户适配器、环境探测/遥测/用量统计等）—— 它们同样打印非 GBK 字符，
+但 **Windows 目前根本跑不了流程引擎**（venv 是 POSIX-only、也没有定时器机制 ⇒ 见
+`docs/Argent-Windows-安装与HR能力验证-2026-10-08.md` §6-③/§7），且它们的 stdout 由
+`flow-trigger.sh`（POSIX）重定向到日志。等"流程引擎上 Windows"那件事做时，逐个入口加三行即可
+（本模块就是为那次准备的单点）。
+
+## 用法（入口脚本，`main()` 的第一句）
+    HERE = pathlib.Path(__file__).resolve().parent
+    sys.path.insert(0, str(HERE / "lib"))
+    from stdio_utf8 import use_utf8_stdio  # noqa: E402
+
+    def main(argv=None) -> int:
+        use_utf8_stdio()
+        ...
+
+回归：`node scripts/tests/py-stdio-gbk.test.mjs`（在 `PYTHONIOENCODING=gbk` 下逐个入口实跑，
+并断言 `--json` 的输出**与 UTF-8 下逐字节相同**）。
+"""
+from __future__ import annotations
+
+import sys
+
+__all__ = ["use_utf8_stdio"]
+
+
+def use_utf8_stdio() -> bool:
+    """把 stdout / stderr 钉成 UTF-8（幂等；已是 UTF-8 时是**无操作**）。
+
+    返回是否"两条流都已确认是 UTF-8"。被替换成非 `TextIOWrapper`（测试夹具、嵌入宿主）
+    而无法 `reconfigure` 时返回 False —— 调用方不必据此判死（那是宿主的事），
+    但**不允许**因为这里失败就跳过本函数：它是唯一的出口编码判据。
+    """
+    ok = True
+    for stream in (sys.stdout, sys.stderr):
+        if stream is None:                      # pythonw/GUI 宿主：没有控制台流
+            continue
+        if _is_utf8(stream):
+            continue
+        try:
+            stream.reconfigure(encoding="utf-8", errors="backslashreplace")   # py3.7+
+        except Exception:  # noqa: BLE001 —— 流被换成了不认识的对象：只能如实报告
+            ok = False
+            continue
+        if not _is_utf8(stream):
+            ok = False
+    return ok
+
+
+def _is_utf8(stream) -> bool:
+    enc = getattr(stream, "encoding", "") or ""
+    return enc.lower().replace("-", "").replace("_", "") == "utf8"

package/engine/scripts/lib/wake-auth.mjs

@@ -0,0 +1,392 @@
+#!/usr/bin/env node
+/**
+ * wake-auth —— 「拿什么去唤醒 dsh 会话」的**唯一鉴权来源链**（2026-10-08）。
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * 事故（本模块的由来）
+ * ══════════════════════════════════════════════════════════════════════════
+ * 定时触发的唤醒端（`scripts/flow-trigger-wake.mjs`）**只从 `/tmp/dsh-web.log` 读 token**；
+ * launchd 的 dsh-web 日志恰好是**唯一**落在 `/tmp` 的日志 ⇒ 该文件被系统清理后（进程仍持有
+ * 已 unlink 的 inode），门控/认领一切正常、**下一行**就 `❌ 取不到 token` ⇒ 唤醒 exit 2
+ * ⇒ 角色会话没起、当轮活没人干，**而全程没有任何失败信号**（静默故障）。
+ *
+ * ## 为什么 token 只能"从日志捡"
+ * dsh 的启动 token 是**每进程随机**的（`dsh-client-connection#processLaunchToken`
+ * = `base64url(randomBytes(32))`，见 `AUTH_RECORD_KEY`/`authenticatedUrl`）：不进任何配置文件，
+ * 只在启动时打印的那行 URL 里（`dsh web: http://127.0.0.1:3080/?token=…`）⇒ 日志没了就"捡"不到。
+ *
+ * ## 但有**不依赖 /tmp** 的既有机制：browser-session 记录的签名 cookie
+ * `~/.dsh/.credentials.yaml` 的 `records.<client-connection/browser-session>`（kind=grant）里
+ * 持久化着 cookie 的 **HMAC 密钥**（dsh 首次激活 web 时写入，重启不变）；cookie 形如
+ * `dsh-auth-<base64url(sha256(authority))> = v1.<base64url(payload)>.<base64url(hmac-sha256)>`，
+ * payload 只需要 `{version, authority, issuedAt, expiresAt}` ⇒ 本模块用**同一个密钥、同一种格式**
+ * 现签一个（⛔ 不是新协议：格式取自 `dsh-client-connection/lib/index.js` 的 encodeCookie/decodeCookie）。
+ *
+ * ## 来源优先级（**先验后用**：每个来源都真打一次服务，验不过就换下一个）
+ * | # | 来源 | 依赖 | 说明 |
+ * |---|---|---|---|
+ * | 1 | `ARGENT_WAKE_TOKEN_FILE` | 显式配置 | 运维指定的 token 文件（含 `token=…` 或裸 token） |
+ * | 2 | **凭据签名 cookie** | `~/.dsh/.credentials.yaml` | **主源**：不依赖 /tmp、不依赖当前进程的日志 |
+ * | 3 | `DSH_WEB_LOG` | 显式配置 | 既有约定（`argent-core` 的 `/url` 也读它） |
+ * | 4 | plist 的 `StandardOutPath` | launchd | 自动跟随"日志被挪到哪儿了"（`com.whyshu.dsh-web.plist`） |
+ * | 5 | `$DSH_HOME/dsh-web.log`、`~/Library/Logs/dsh-web.log` | 稳定目录 | 运维把日志挪到稳定位置的常见落点 |
+ * | 6 | `/tmp/dsh-web.log` | 旧机器 | **兜底兼容**（历史形态；不再是唯一来源） |
+ * `ARGENT_WAKE_LOG_PATHS`（`:` 分隔）可**整表覆盖**第 3–6 项（运维把日志挪走、或测试夹具用）。
+ *
+ * ## 纪律
+ * · 只读凭据文件、**绝不打印/落盘** secret 或 cookie（日志只打"来源名"）；
+ * · 每个来源的失败都**分类**（不存在 / 取到了但解析不出 / 已失效）——"文件不存在"与
+ *   "有文件没 token"是两种故障，混成一句就没法修；
+ * · 全部失败 ⇒ 由调用方（`flow-trigger-wake.mjs`）**响亮失败 + 台账 blocked + 遥测**（不许静默）。
+ */
+import { execFileSync } from 'node:child_process'
+import { createHash, createHmac } from 'node:crypto'
+import { existsSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { isAbsolute, join } from 'node:path'
+import { isDirectRun } from './is-direct-run.mjs'
+
+/** 历史形态：launchd 把 dsh-web 的 stdout/stderr 都指到这里（**兜底**，不再是唯一来源）。 */
+export const LEGACY_LOG = '/tmp/dsh-web.log'
+
+/** cookie 前缀与签名算法（取自 dsh-client-connection；改动这里必须同步核该实现）。 */
+export const COOKIE_PREFIX = 'dsh-auth-'
+export const COOKIE_PAYLOAD_VERSION = 1
+export const SECRET_BYTES = 32
+
+/** 现签 cookie 的有效期：6 小时（够一轮唤醒用；**远短于** dsh 的 cookieMaxAgeDays，必被接受）。 */
+export const DEFAULT_MAX_AGE_MS = 6 * 60 * 60 * 1000
+
+const NET_TIMEOUT_MS = 8000
+
+// ── base64url / 摘要 ────────────────────────────────────────────────────────
+const b64url = (buf) => Buffer.from(buf).toString('base64').replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/u, '')
+const unb64url = (s) => Buffer.from(String(s).replaceAll('-', '+').replaceAll('_', '/'), 'base64')
+const sha256 = (s) => createHash('sha256').update(s).digest()
+const hmac256 = (secret, body) => createHmac('sha256', secret).update(body).digest()
+
+/** `--base` 的 authority（cookie 的签名绑定的就是它：换 Host 必须重签）。 */
+export function authorityOf(base) {
+  try { return new URL(String(base)).host } catch { return '' }
+}
+
+/**
+ * 用持久化密钥现签一个 dsh browser-session cookie（格式同 `dsh-client-connection`）。
+ * @param {{authority: string, secret: string, nowMs?: number, maxAgeMs?: number}} o
+ * @returns {{name: string, value: string, expiresAt: number}}
+ */
+export function mintCookie({ authority, secret, nowMs = Date.now(), maxAgeMs = DEFAULT_MAX_AGE_MS }) {
+  if (!authority) throw new Error('mintCookie 需要 authority（来自 --base 的 host）')
+  const key = unb64url(secret)
+  if (key.byteLength !== SECRET_BYTES) throw new Error(`browser-session secret 不是 ${SECRET_BYTES} 字节（实际 ${key.byteLength}）`)
+  const expiresAt = nowMs + maxAgeMs
+  const body = b64url(Buffer.from(JSON.stringify({
+    version: COOKIE_PAYLOAD_VERSION, authority, issuedAt: nowMs, expiresAt,
+  }), 'utf8'))
+  return {
+    name: COOKIE_PREFIX + b64url(sha256(authority)),
+    value: `v1.${body}.${b64url(hmac256(key, body))}`,
+    expiresAt,
+  }
+}
+
+// ── 来源①：token 文件（日志形态 或 裸 token）────────────────────────────────
+/**
+ * 从一个文本里取**最后一次**出现的 `token=…`（= 启动时打印的那个；日志是追加型的）。
+ * @returns {string} 取不到返回空串
+ */
+export function parseTokenFromText(text) {
+  const m = String(text || '').match(/token=([A-Za-z0-9_-]{8,})/g) || []
+  return m.length ? m[m.length - 1].slice('token='.length) : ''
+}
+
+/**
+ * 读一个"可能是日志、也可能是裸 token"的文件。
+ * 三种结果**必须区分**：`missing`（文件不在）/ `unparsable`（取到了文件但没 token）/ `ok`。
+ * @returns {{status:'ok',token:string}|{status:'missing'|'unparsable',detail:string}}
+ */
+export function readTokenFile(path) {
+  let text
+  try {
+    text = readFileSync(path, 'utf8')
+  } catch (e) {
+    return { status: 'missing', detail: e && e.code === 'ENOENT' ? '文件不存在' : `读不了（${(e && (e.code || e.message)) || e}）` }
+  }
+  const token = parseTokenFromText(text)
+  if (token) return { status: 'ok', token }
+  const bare = String(text).trim()
+  if (/^[A-Za-z0-9_-]{20,}$/.test(bare)) return { status: 'ok', token: bare }
+  return { status: 'unparsable', detail: `取到了文件（${String(text).length} 字节）但没解析出 token=（既不是启动日志形态，也不是裸 token）` }
+}
+
+// ── 来源②：credentials 的 browser-session 记录 ──────────────────────────────
+/** credentials 文件位置（`$DSH_HOME/.credentials.yaml`，缺省 `~/.dsh/.credentials.yaml`）。 */
+export function credentialsPath({ env = process.env, dshHome, home = homedir() } = {}) {
+  const h = (dshHome || (env && env.DSH_HOME) || join(home, '.dsh'))
+  return join(h, '.credentials.yaml')
+}
+
+/**
+ * 极小 YAML 子集：**只解析"缩进映射"**（`键: 值` / `键:` + 更深缩进的子映射）。
+ * 为什么不用通用 YAML：内核（L1）不引第三方依赖；dsh 写这份文件是**定形**的
+ * （三段 `version`/`refs`/`records`，见 ~/.dsh/AGENTS.md）。遇到不认识的形态 ⇒ 报告，绝不猜。
+ */
+function parseIndentMap(lines, start, baseIndent) {
+  const root = {}
+  const stack = [{ indent: baseIndent, node: root }]
+  for (let i = start; i < lines.length; i++) {
+    const raw = lines[i]
+    const t = raw.trim()
+    if (!t || t.startsWith('#')) continue
+    const ind = raw.length - raw.trimStart().length
+    if (ind <= baseIndent) break                       // 回到同级（下一条记录）或更外层
+    while (stack.length > 1 && ind <= stack[stack.length - 1].indent) stack.pop()
+    const m = t.match(/^([^:]+):(?:\s*(.*))?$/)
+    if (!m) return { error: `第 ${i + 1} 行不是「键: 值」形态：${t.slice(0, 60)}` }
+    const key = m[1].trim()
+    const rest = (m[2] ?? '').trim().replace(/^["']|["']$/g, '')
+    const parent = stack[stack.length - 1].node
+    if (rest === '') {
+      const child = {}
+      parent[key] = child
+      stack.push({ indent: ind, node: child })
+    } else {
+      parent[key] = rest
+    }
+  }
+  return { value: root }
+}
+
+/**
+ * 从 credentials 文本里取 `records.<scope>/<id>` 的 grant 载荷密钥（只认缩进结构）。
+ * @returns {{status:'ok',secret:string}|{status:'no-record'|'malformed',detail:string}}
+ */
+export function readBrowserSecret(text, recordId = 'client-connection/browser-session') {
+  const lines = String(text || '').split(/\r?\n/)
+  let inRecords = false
+  let recIndent = -1
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i]
+    const t = raw.trim()
+    if (!t || t.startsWith('#')) continue
+    const ind = raw.length - raw.trimStart().length
+    if (ind === 0) {
+      inRecords = /^records\s*:/.test(t)
+      recIndent = -1
+      continue
+    }
+    if (!inRecords) continue
+    if (recIndent < 0) {
+      const m = t.match(/^([^:]+):\s*$/)             // 记录块头必须是 `<scope>/<id>:`（无值）
+      if (!m) return { status: 'malformed', detail: `records 段首个条目不是「<scope>/<id>:」形态：${t.slice(0, 60)}` }
+      recIndent = ind
+    }
+    if (ind !== recIndent) continue
+    const m = t.match(/^([^:]+):\s*$/)
+    if (!m || m[1].trim() !== recordId) continue
+    const parsed = parseIndentMap(lines, i + 1, recIndent)
+    if (parsed.error) return { status: 'malformed', detail: `记录 ${recordId} 的缩进结构坏了：${parsed.error}` }
+    const rec = parsed.value
+    if (rec.kind !== 'grant') return { status: 'malformed', detail: `记录 ${recordId} 的 kind=${JSON.stringify(rec.kind)}（期望 grant）` }
+    const payload = rec.payload
+    if (!payload || typeof payload !== 'object') return { status: 'malformed', detail: `记录 ${recordId} 缺 payload` }
+    if (Number(payload.version) !== 1) return { status: 'malformed', detail: `记录 ${recordId} 的 payload.version=${JSON.stringify(payload.version)}（期望 1）` }
+    const secret = String(payload.secret || '')
+    if (!secret) return { status: 'malformed', detail: `记录 ${recordId} 缺 payload.secret` }
+    if (unb64url(secret).byteLength !== SECRET_BYTES) return { status: 'malformed', detail: `记录 ${recordId} 的 payload.secret 不是 ${SECRET_BYTES} 字节` }
+    return { status: 'ok', secret }
+  }
+  return { status: 'no-record', detail: `没有 records.${recordId} 记录（dsh web 首次启动会写入；非 web 部署本就没有）` }
+}
+
+// ── 来源④：plist 声明的日志落点（自动跟随"日志挪到哪儿了"）───────────────────
+/**
+ * 读 `com.whyshu.dsh-web.plist` 的 `StandardOutPath`（回退 `StandardErrorPath`）。
+ * 为什么要有：运维把日志从 /tmp 挪走的**正确做法**就是改 plist ⇒ 这里直接跟随声明，
+ * 不必再让人来改代码/加环境变量。plutil 不可用（非 macOS）或没这 plist ⇒ 返回空串。
+ */
+export function plistLogPath(launchAgentsDir = join(homedir(), 'Library', 'LaunchAgents')) {
+  const plist = join(launchAgentsDir, 'com.whyshu.dsh-web.plist')
+  if (!existsSync(plist)) return ''
+  try {
+    const out = execFileSync('plutil', ['-convert', 'json', '-o', '-', '--', plist],
+      { encoding: 'utf8', timeout: 4000, stdio: ['ignore', 'pipe', 'ignore'] })
+    const doc = JSON.parse(out)
+    const p = String(doc.StandardOutPath || doc.StandardErrorPath || '')
+    return p && isAbsolute(p) ? p : ''
+  } catch {
+    return ''
+  }
+}
+
+/**
+ * 日志候选路径（**有序**，含历史 `/tmp` 兜底）。
+ * `ARGENT_WAKE_LOG_PATHS`（`:` 分隔）给了就**整表覆盖**（运维把日志挪到稳定目录、测试夹具）。
+ */
+export function logPaths({ env = process.env, home = homedir(), dshHome, launchAgentsDir } = {}) {
+  const explicit = String((env && env.ARGENT_WAKE_LOG_PATHS) || '').trim()
+  if (explicit) return explicit.split(':').map((s) => s.trim()).filter(Boolean)
+  const out = []
+  const push = (p) => { if (p && !out.includes(p)) out.push(p) }
+  push(env && env.DSH_WEB_LOG)                                    // 既有约定（argent-core 也读它）
+  push(plistLogPath(launchAgentsDir || join(home, 'Library', 'LaunchAgents')))
+  push(join(dshHome || (env && env.DSH_HOME) || join(home, '.dsh'), 'dsh-web.log'))
+  push(join(home, 'Library', 'Logs', 'dsh-web.log'))
+  push(LEGACY_LOG)                                               // 旧机器兜底（**最后**）
+  return out
+}
+
+/**
+ * 组装**有序**来源表（每个来源带 `label` 与 `obtain()`；`label` 会原样出现在失败文案里）。
+ * 优先级见文件头表格；顺序即"先试谁"。
+ */
+export function authSources({ env = process.env, home = homedir(), dshHome, base, logs } = {}) {
+  const authority = authorityOf(base)
+  const sources = []
+  const tokenFile = String((env && env.ARGENT_WAKE_TOKEN_FILE) || '').trim()
+  if (tokenFile) {
+    sources.push({
+      id: 'env-token-file',
+      kind: 'token-file',
+      label: `ARGENT_WAKE_TOKEN_FILE=${tokenFile}`,
+      obtain: () => readTokenFile(tokenFile),
+    })
+  }
+  const cred = credentialsPath({ env, dshHome, home })
+  sources.push({
+    id: 'credentials',
+    kind: 'credentials',
+    label: `凭据文件 ${cred}（records.client-connection/browser-session）`,
+    obtain: () => {
+      let text
+      try {
+        text = readFileSync(cred, 'utf8')
+      } catch (e) {
+        return { status: 'missing', detail: e && e.code === 'ENOENT' ? '文件不存在' : `读不了（${(e && (e.code || e.message)) || e}）` }
+      }
+      const rec = readBrowserSecret(text)
+      if (rec.status !== 'ok') return { status: rec.status === 'no-record' ? 'missing' : 'unparsable', detail: rec.detail }
+      try {
+        return { status: 'ok', cookie: mintCookie({ authority, secret: rec.secret }), detail: '用持久化密钥现签 browser-session cookie（同 dsh-client-connection 格式，不依赖日志）' }
+      } catch (e) {
+        return { status: 'unparsable', detail: `签不出 cookie：${e.message}` }
+      }
+    },
+  })
+  for (const p of (logs || logPaths({ env, home, dshHome }))) {
+    sources.push({
+      id: `log:${p}`,
+      kind: 'log-file',
+      label: `启动日志 ${p}${p === LEGACY_LOG ? '（历史兜底位置）' : ''}`,
+      obtain: () => readTokenFile(p),
+    })
+  }
+  return sources
+}
+
+// ── 取用（先验后用）─────────────────────────────────────────────────────────
+/** 一次 HTTP 探活：区分「服务不可达」（网络层）与「服务拒绝」（401/403）。 */
+async function probe(url, { fetchImpl, cookie, timeoutMs = NET_TIMEOUT_MS, redirect }) {
+  const ac = new AbortController()
+  const timer = setTimeout(() => ac.abort(), timeoutMs)
+  try {
+    const res = await fetchImpl(url, {
+      redirect: redirect || 'follow',
+      headers: cookie ? { cookie: `${cookie.name}=${cookie.value}` } : {},
+      signal: ac.signal,
+    })
+    return { res }
+  } catch (e) {
+    return { unreachable: String((e && (e.message || e.code)) || e) }
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/**
+ * 按优先级逐个试来源，**每个都真打一次服务**（验不过就换下一个）。
+ * @returns {Promise<{ok:true,cookie:{name:string,value:string},source:string,tried:Array}|{ok:false,tried:Array,unreachable?:string}>}
+ */
+export async function acquireWakeAuth({ sources, base, fetchImpl = fetch, timeoutMs = NET_TIMEOUT_MS } = {}) {
+  const tried = []
+  for (const s of sources || []) {
+    let got
+    try {
+      got = await s.obtain()
+    } catch (e) {
+      got = { status: 'error', detail: String((e && e.message) || e) }
+    }
+    if (!got || got.status !== 'ok') {
+      tried.push({ id: s.id, label: s.label, status: (got && got.status) || 'error', detail: (got && got.detail) || '未知' })
+      continue
+    }
+    if (got.cookie) {
+      // 现签 cookie：直接验证服务是否认它
+      const { res, unreachable } = await probe(`${base}/`, { fetchImpl, cookie: got.cookie, timeoutMs })
+      if (unreachable) return { ok: false, tried, unreachable }
+      if (res && res.status === 200) {
+        tried.push({ id: s.id, label: s.label, status: 'ok', detail: got.detail })
+        return { ok: true, cookie: got.cookie, source: s.label, tried }
+      }
+      tried.push({ id: s.id, label: s.label, status: 'rejected', detail: `${got.detail} ⇒ 服务返回 HTTP ${res ? res.status : '?'}` })
+      continue
+    }
+    // 启动 token：换 cookie（303 + Set-Cookie 才算数）
+    const { res, unreachable } = await probe(`${base}/?token=${encodeURIComponent(got.token)}`, { fetchImpl, timeoutMs, redirect: 'manual' })
+    if (unreachable) return { ok: false, tried, unreachable }
+    const raw = res ? ((typeof res.headers.getSetCookie === 'function' ? res.headers.getSetCookie() : null) || [res.headers.get('set-cookie')] || []).join('; ') : ''
+    const pair = raw.split(';')[0].trim()
+    const at = pair.indexOf('=')
+    if (res && res.status === 303 && at > 0) {
+      tried.push({ id: s.id, label: s.label, status: 'ok', detail: `用启动 token 换到 cookie（HTTP 303）` })
+      return { ok: true, cookie: { name: pair.slice(0, at), value: pair.slice(at + 1) }, source: s.label, tried }
+    }
+    tried.push({ id: s.id, label: s.label, status: 'rejected', detail: `token 换不到 cookie（HTTP ${res ? res.status : '?'}）—— 多半是旧进程留下的 token` })
+  }
+  return { ok: false, tried }
+}
+
+/** 来源失败状态 → 人读文案（失败文案与"跳过摘要"共用同一份，避免两处口径漂移）。 */
+export const SOURCE_STATUS_ZH = {
+  missing: '取不到', unparsable: '取到了但解析不出', rejected: '被服务拒绝（过期/不匹配）', error: '尝试时出错',
+}
+
+/** 失败文案：**点名所有尝试过的来源**（逐个带原因 + 状态）+ 可执行修法。 */
+export function authFailureText({ tried, base, home = homedir(), dshHome } = {}) {
+  const statusZh = SOURCE_STATUS_ZH
+  const lines = [`取不到唤醒鉴权（dsh web 的启动 token / browser-session cookie）——已尝试 ${tried.length} 个来源，全部不可用：`]
+  tried.forEach((t, i) => lines.push(`  ${i + 1}) ❌ ${t.label}：${statusZh[t.status] || t.status}｜${t.detail}`))
+  const cred = credentialsPath({ dshHome, home })
+  lines.push(
+    '',
+    `服务地址：${base}（鉴权失败 → 角色会话起不来 → 本轮已认领的活没人干；台账 case=wake 已留痕）`,
+    '修法（按代价从低到高）：',
+    '  · 把 dsh-web 的启动日志从 /tmp 挪到**稳定目录**（/tmp 会被系统清理，进程还握着已删除的 inode ⇒ 日志"看着有、其实已成孤儿"）：',
+    `      plutil -replace StandardOutPath  -string "$HOME/Library/Logs/dsh-web.log" ~/Library/LaunchAgents/com.whyshu.dsh-web.plist`,
+    `      plutil -replace StandardErrorPath -string "$HOME/Library/Logs/dsh-web.log" ~/Library/LaunchAgents/com.whyshu.dsh-web.plist`,
+    `      然后重启 dsh web：bash ~/Code/argent-dsh/scripts/dsh-restart.sh（本模块会自动跟随 plist 的新落点，无需改代码）`,
+    `  · 或显式指定来源：ARGENT_WAKE_TOKEN_FILE=<含 token= 的文件>；ARGENT_WAKE_LOG_PATHS=<日志路径，":" 分隔>`,
+    `  · 或确保 ${cred} 里有 records.client-connection/browser-session（dsh web 首次启动即写入 —— 这条**完全不依赖 /tmp**）`,
+  )
+  return lines.join('\n')
+}
+
+// ── CLI：把"落点链"暴露给 shell 消费者（**唯一真源**，⛔ 别在 .sh 里再抄一份顺序）──────
+// `node scripts/lib/wake-auth.mjs --log-paths`  ⇒ 逐行打印候选日志落点（有序，末项是 /tmp 兜底）。
+// 用途：`scripts/dsh-url.sh` / `scripts/check-dsh-web-expose.sh` 等 shell 侧消费者遍历同一条链，
+// 命中即停（因此"有 DSH_WEB_LOG ⇒ 不碰 /tmp"是**同一个循环**的自然结果，不是各写一份判据）。
+if (isDirectRun(import.meta.url)) {
+  const args = process.argv.slice(2)
+  if (args.includes('--log-paths')) {
+    for (const p of logPaths()) console.log(p)
+    process.exit(0)
+  }
+  if (args.includes('--help') || args.length === 0) {
+    console.log('用法：node scripts/lib/wake-auth.mjs --log-paths')
+    console.log('  逐行打印 dsh web 启动日志的候选落点（有序；DSH_WEB_LOG → plist → $DSH_HOME → ~/Library/Logs → /tmp）')
+    console.log('  ARGENT_WAKE_LOG_PATHS（":" 分隔）可整表覆盖；本文件是"落点顺序"的唯一真源。')
+    process.exit(args.length === 0 ? 2 : 0)
+  }
+  console.error(`未知参数：${args.join(' ')}（只有 --log-paths）`)
+  process.exit(2)
+}