@geoly-ai/skills-hub 0.3.5 → 0.3.7

package/src/publish/token.mjs

@@ -0,0 +1,244 @@
+// `publish` 的 token 来源解析 —— 06-submission.md §9 的**偏离版**
+// （10-open-questions.md Q4，2026-09-05 用户拍板）。
+//
+// ── 🔴 这个模块的**唯一**产品承诺：CLI 不持有 token ──────────────────────
+//
+// 我们不注册 OAuth App / GitHub App，不做 device flow，不做 login / logout，
+// **也不存任何东西**。token 只在一次 `publish` 的进程生命周期里存在于内存，
+// 用完即随进程消失。`src/auth.mjs` 的 keychain 存储在这个模型下**不再被使用** ——
+// 它没有被删掉（别的东西可能还引用它），但 publish 这条路径一个字节都不写。
+//
+// ⚠️ **不要把它描述成「token 权限很小」。** 恰恰相反：用户已有的 token
+//    很可能是 classic `repo` PAT，权限面比 `public_repo` 还大，而**我们无法收窄它**。
+//    「CLI 不持有」与「权限很小」是两件完全不同的事，只有前者是我们能保证的。
+//    权限面必须在任何写操作之前如实披露 —— 那是 `commands/publish.mjs` 的事。
+//
+// ── 🔴 token 的六条禁令（每一条都有测试） ────────────────────────────────
+//   ① 不落盘        ② 不进 argv        ③ 不进子进程环境
+//   ④ 不进日志       ⑤ 不进错误文案      ⑥ 不进 telemetry
+// 前三条靠**控制流**保证（本模块从不 write、从不把 token 放进 args/env）；
+// 后三条靠 `scrub()` 兜底 —— 它是最后一道，不是第一道。
+
+import { spawnSync as nodeSpawnSync } from 'node:child_process';
+
+/**
+ * 来源顺序。**顺序本身是判据的一部分**，不是实现细节：
+ * 用户看到的身份必须与实际投稿身份一致，所以「用了哪一个」要能说得出来。
+ *
+ * ⚠️ `GITHUB_TOKEN` 在 GitHub Actions 里**会自动存在**（每个 job 都注入）。
+ *    它排在最后，但仍然排在 `gh` 前面 —— 于是在 CI 里，一个以为自己在用
+ *    `gh` 身份的用户实际会用上 Actions 的 job token。这不是可以静默处理的事：
+ *    披露里必须把「用的是哪一个变量」写在脸上（见 `describeSource`）。
+ */
+export const TOKEN_ENV_ORDER = Object.freeze([
+  'GEOLY_GITHUB_TOKEN', 'GH_TOKEN', 'GITHUB_TOKEN',
+]);
+
+/**
+ * 跑 `gh` 之前要从继承环境里**删掉**的变量。
+ *
+ * 🔴 `GH_HOST` 必须删 + 显式覆盖成 `github.com`：留着继承值的话，
+ *    一个配了 GHE 的用户会拿到**另一台主机**的 token，而我们接下来把它发去
+ *    `api.github.com` —— 那是一次真正的凭据泄漏，不是配置错误。
+ * 🔴 token 类变量也要删：`gh auth token` 在 `GH_TOKEN` 存在时会**原样回显它**。
+ *    我们只有在三个变量都不存在时才走到这里，所以这一条在今天是冗余的 ——
+ *    留着是因为它防的是「将来有人改了上面的顺序」，而那种改动不会让任何测试变红。
+ */
+const GH_ENV_STRIP = Object.freeze([
+  'GH_TOKEN', 'GITHUB_TOKEN', 'GH_ENTERPRISE_TOKEN', 'GITHUB_ENTERPRISE_TOKEN',
+  'GH_HOST', 'GH_REPO',
+]);
+
+export class TokenError extends Error {
+  /** 认证/权限类一律 EXIT.AUTH(7) —— 见 09-cli.md §6。 */
+  constructor(message) { super(message); this.name = 'TokenError'; this.exitCode = 7; }
+}
+
+/**
+ * token 的形状门。**不是**在验证它有效（那要出网），是在拒绝明显不是 token 的东西。
+ *
+ * 🔴 存在的理由很具体：`gh auth token` 失败时也可能往 stdout 写东西，
+ *    多行输出 / 带空白的输出被当成 token 塞进 `Authorization` header，
+ *    会造成一次**带着垃圾内容的请求**，而且那段垃圾可能被服务端记进日志。
+ *    宁可在这里失败。
+ */
+export function assertTokenShape(raw, where) {
+  if (typeof raw !== 'string') throw new TokenError(`${where} 给出的不是字符串`);
+  // 🔴 这里**不能**把值放进错误文案 —— 哪怕它"看起来不像 token"。
+  if (raw.length < 8 || raw.length > 512) {
+    throw new TokenError(`${where} 给出的 token 长度不合理（应在 8–512 之间）—— 已忽略，不予使用。`);
+  }
+  if (!/^[\x21-\x7e]+$/.test(raw)) {
+    throw new TokenError(
+      `${where} 给出的 token 含空白或不可见字符 —— 拒绝使用。\n`
+      + '  🔴 常见成因：把整段命令输出（含换行/提示语）塞进了环境变量。',
+    );
+  }
+  return raw;
+}
+
+/**
+ * 遮蔽器 —— **最后一道，不是第一道**。
+ *
+ * 🔴 两条规则缺一不可：
+ *   ① 替换掉**这次实际用的** token 原文（最准，但只覆盖我们知道的那一个）；
+ *   ② 按**形态**替换任何看起来像 GitHub 凭据的串 —— 覆盖「响应体里回显了另一个
+ *      token」「用户把 token 写进了 PR body」这类我们不知道的情况。
+ * 只做 ① 的话，一次 `422` 响应体里回显的**别的**凭据会被原样打出来。
+ *
+ * ⚠️ **诚实边界**：`②` 认的是今天 GitHub 在用的前缀（`ghp_`/`gho_`/`ghu_`/`ghs_`/
+ *    `ghr_`/`github_pat_`）。老式的 40 位 hex PAT **不在其中** —— 那个形态与
+ *    commit sha 完全一样，按形态替换会把每一个 sha 都打成 `***`，而 sha 正是
+ *    本命令要给用户看的关键事实。老式 PAT 只由 ① 兜住。
+ */
+export function scrub(text, token = null) {
+  let s = String(text);
+  if (typeof token === 'string' && token.length >= 8) {
+    s = s.split(token).join('***');
+  }
+  return s
+    .replace(/\bgh[pousr]_[A-Za-z0-9]{16,}/g, '***')
+    .replace(/\bgithub_pat_[A-Za-z0-9_]{16,}/g, '***');
+}
+
+/**
+ * 环境变量这一层。返回**存在**的那些（trim 后非空才算存在）。
+ * 🔴 空串视为"不存在"而不是"存在但为空"：CI 里把一个变量置空是常见的
+ *    "关掉它"写法，把它当成一个候选会让后面的冲突检测报出无意义的红。
+ */
+export function collectEnvTokens(env) {
+  const found = [];
+  for (const name of TOKEN_ENV_ORDER) {
+    const raw = env?.[name];
+    if (typeof raw !== 'string') continue;
+    const v = raw.trim();
+    if (v === '') continue;
+    found.push({ name, value: v });
+  }
+  return found;
+}
+
+/**
+ * 🔴 多个来源同时存在**且值不同** → 直接拒，不静默挑一个。
+ *
+ * 为什么不"按顺序挑第一个就好"：用户看到的身份与实际投稿身份必须一致。
+ * 一台机器上同时有 `GH_TOKEN`（个人账号）与 `GITHUB_TOKEN`（CI job token）
+ * 是**常态**，两者是不同的身份 —— 静默挑一个的话，投稿会以他没预期的身份提交，
+ * 而他要到 PR 页面上才看得出来。
+ *
+ * ⚠️ 值**相同**时不拒：那只是同一个 token 被写进了多个变量，身份没有歧义。
+ *    但披露里仍然要把其余变量名列出来（`others`）。
+ *
+ * 🔴 错误文案里**只有变量名**。不列值、不列长度、不列前缀 ——
+ *    长度和前缀足以区分 classic PAT / fine-grained / Actions token，
+ *    那已经是在泄漏「这台机器上有什么凭据」了。
+ */
+export function resolveEnvToken(env) {
+  const found = collectEnvTokens(env);
+  if (found.length === 0) return null;
+  const distinct = new Set(found.map((f) => f.value));
+  if (distinct.size > 1) {
+    throw new TokenError(
+      `检测到多个 GitHub token 环境变量，且它们的值**不同**：${found.map((f) => f.name).join('、')}。\n`
+      + '  🔴 拒绝替你挑一个 —— 它们是不同的身份，挑错了你会以没预期的账号投稿，\n'
+      + '     而要到 PR 页面上才看得出来。\n'
+      + `  ⚠️ 如果你在 GitHub Actions 里：\`GITHUB_TOKEN\` 是 runner 自动注入的 job token，\n`
+      + '     它多半不是你想用的那个身份。\n'
+      + '  怎么办：只留一个，或显式设 `GEOLY_GITHUB_TOKEN` 指定你要用的那一个\n'
+      + '  （它的优先级最高，但**值不同时本命令仍然拒绝** —— 请把其余的 unset）。',
+    );
+  }
+  const chosen = found[0];
+  assertTokenShape(chosen.value, `环境变量 ${chosen.name}`);
+  return {
+    token: chosen.value,
+    source: `env:${chosen.name}`,
+    sourceLabel: `环境变量 ${chosen.name}`,
+    others: found.slice(1).map((f) => f.name),
+  };
+}
+
+/**
+ * `gh auth token` 这一层。
+ *
+ * 🔴 `shell: false`（`spawnSync` 的默认，这里显式写出来）：绝不经过 shell。
+ * 🔴 `--hostname github.com` 固定，并且**同时**把继承来的 `GH_HOST` 删掉再显式设回
+ *    —— 两条都要：`--hostname` 决定它去哪个 host 取凭据，删 `GH_HOST` 防的是
+ *    将来有人去掉那个参数时静默退回继承值。
+ * 🔴 **stdout / stderr 一律不原样输出。** gh 的输出里可能带 token
+ *    （`gh auth token` 的正常输出**就是** token），把它拼进错误文案是最容易犯的错。
+ *    这里按 exit code 分档给固定文案。
+ */
+export function resolveGhToken(env, spawnSync = nodeSpawnSync) {
+  const childEnv = { ...env };
+  for (const k of GH_ENV_STRIP) delete childEnv[k];
+  childEnv.GH_HOST = 'github.com';
+  // 🔴 `GH_PROMPT_DISABLED` / `NO_COLOR`：不让它试图交互，也不要 ANSI 转义进 stdout。
+  childEnv.GH_PROMPT_DISABLED = '1';
+  childEnv.NO_COLOR = '1';
+
+  let r;
+  try {
+    r = spawnSync('gh', ['auth', 'token', '--hostname', 'github.com'], {
+      shell: false,
+      encoding: 'utf8',
+      env: childEnv,
+      timeout: 15000,
+      // 🔴 很小的 maxBuffer：`gh auth token` 的正常输出是**一行**。
+      //    留一个大缓冲区，等于愿意把一大坨我们不打算读的东西收进内存。
+      maxBuffer: 64 * 1024,
+      windowsHide: true,
+    });
+  } catch (e) {
+    // spawn 本身抛（极少见）——**不带 e.message**，它可能含路径等环境信息。
+    throw new TokenError(`调用 \`gh\` 失败（${e?.code ?? 'spawn 错误'}）。${GH_HINT}`);
+  }
+  if (r.error) {
+    const code = r.error.code;
+    if (code === 'ENOENT') {
+      throw new TokenError(`找不到 \`gh\`（GitHub CLI 未安装或不在 PATH 上）。${GH_HINT}`);
+    }
+    throw new TokenError(`调用 \`gh\` 失败（${code ?? 'spawn 错误'}）。${GH_HINT}`);
+  }
+  // 🔴 超时被 kill 时 `status` 是 null、`signal` 有值 —— 单看 exit code 会漏。
+  if (r.signal !== null && r.signal !== undefined) {
+    throw new TokenError(`\`gh auth token\` 被信号 ${r.signal} 中止（多半是 15 秒超时）。${GH_HINT}`);
+  }
+  if (r.status !== 0) {
+    // 🔴 **不透传 gh 的 stderr。** gh 未登录时 exit 1、stderr 是人类文案，
+    //    看着无害 —— 但「看着无害」不是判据：没有任何机制保证它下一个版本不会
+    //    把 token 打进 stderr（比如某个 debug 开关从环境里被继承进去）。
+    //    ⚠️ 也**不靠 exit code 分辨"没装"与"没登录"** —— 它分辨不了。
+    //    「没装」由上面的 `ENOENT` 分支认（那个判据是可靠的）；
+    //    到这里就统一给"两条出路"的固定文案。
+    throw new TokenError(
+      `\`gh auth token --hostname github.com\` 以 exit ${r.status} 失败`
+      + '（最常见的原因是**没有登录 github.com**）。' + GH_HINT,
+    );
+  }
+  const out = typeof r.stdout === 'string' ? r.stdout.trim() : '';
+  if (out === '') throw new TokenError(`\`gh auth token\` 没有输出任何 token。${GH_HINT}`);
+  assertTokenShape(out, '`gh auth token`');
+  return { token: out, source: 'gh', sourceLabel: '`gh auth token`（GitHub CLI 的已登录身份）', others: [] };
+}
+
+const GH_HINT =
+  '\n  怎么办（二选一）：\n'
+  + '    · `gh auth login --hostname github.com`（推荐：本命令不持有、也不存储任何 token）\n'
+  + '    · 或设 `GEOLY_GITHUB_TOKEN=<你的 token>` 后重跑\n'
+  + '  🔴 本命令**不做** login，也**不会**把 token 存到任何地方 —— 撤销请去\n'
+  + '     GitHub 的 Settings → Developer settings，或 `gh auth logout`。';
+
+/**
+ * 完整的来源解析：环境变量 → `gh`。
+ *
+ * @param {object} a
+ * @param {Record<string,string>} a.env
+ * @param {function} [a.spawnSync]  注入点（测试用）。生产走 node:child_process。
+ * @returns {{token:string, source:string, sourceLabel:string, others:string[]}}
+ */
+export function resolveToken({ env, spawnSync = nodeSpawnSync }) {
+  const fromEnv = resolveEnvToken(env);
+  if (fromEnv !== null) return fromEnv;
+  return resolveGhToken(env, spawnSync);
+}

package/src/target.mjs

@@ -111,8 +111,42 @@ const STATE_MARKER_FILES = [
 ];
 const STATE_MARKER_DIRS = ['journal', 'attic', 'quarantine', 'audit-archive'];
 
-/** `.geoly` 之下会出现的状态路径，全部要以 lstat 无跟随方式检查（§3.4）。 */
-const SCAN_DEFAULTS = Object.freeze({ maxDepth: 8, maxDirs: 5000 });
+/**
+ * 扫描预算。
+ *
+ * 🔴 **这三个数在规格里没有出处**（§3.4 / §3.5 只说「拒绝嵌套 target」、
+ * 「状态路径逐个 lstat」，一个数字都没写）。所以它们是**实现的资源闸**，
+ * 不是规则本身 —— 定得太紧不会更安全，只会把「证明不了」当成常态。
+ *
+ * 旧值 `maxDepth: 8` 就是这么栽的：一个真实的 `~/.claude/skills`（657 个目录）
+ * 里只要有**一个** skill vendored 了一个仓库，深度就到 12，
+ * 于是每一次 install 都报 `target.nested-scan-incomplete` 而退出 —— 装不上任何东西。
+ * 实测：那棵树扫完只要 17ms、573/657 个目录，`maxDirs: 5000` 连一半都没碰到。
+ *
+ * 🔴 **成本是 O(目录数)，与深度无关。** 所以：
+ *   · `maxDirs` / `maxEntries` 才是真正的**预算闸**（它们限制的是工作量）；
+ *   · `maxDepth` 只是一个**防病态路径的 sanity guard**（PATH_MAX 量级），
+ *     不该拿来当预算 —— 拿它当预算就是按一个与成本无关的量收费。
+ *
+ * ⚠️ `maxEntries` 补的是 `maxDirs` 的漏：一个目录**下** 500 万个条目
+ * 只算 1 个 visited，`maxDirs` 完全拦不住。（它仍然拦不住**单次** `readdirSync`
+ * 的内存尖峰 —— 那要 `opendirSync` 流式读才行，见文件末尾的「明确没做」。）
+ */
+const SCAN_DEFAULTS = Object.freeze({ maxDepth: 64, maxDirs: 100_000, maxEntries: 1_000_000 });
+
+/**
+ * 🔴 预算旋钮必须有**硬顶**。否则 `--scan-max-dirs 9007199254740991` 就等于
+ * 把有界遍历改回无界 —— 那是把资源闸删掉，而不是「用户自己负责」。
+ * 撞到硬顶要**报错**，不能静默截断成硬顶：静默截断会让用户以为他给的预算生效了。
+ */
+const SCAN_CEILINGS = Object.freeze({
+  maxDepth: 1024, // 比任何文件系统的 PATH_MAX 能容下的层数都宽
+  maxDirs: 5_000_000,
+  maxEntries: 50_000_000,
+});
+
+/** 每一类「没扫完」最多留几条样例路径。样例只用来指路，不是清单。 */
+const SAMPLE_MAX = 5;
 
 /**
  * 🔴 扫描上限必须校验。`NaN` 参与 `>=` 永远是 false ——
@@ -126,14 +160,24 @@ function normalizeScan(scan = {}) {
     if (typeof v !== 'number' || !Number.isFinite(v) || v < 0) {
       throw new Error(`scan.${name} 必须是有限的非负数，收到 ${JSON.stringify(v)}`);
     }
-    return Math.floor(v);
+    const n = Math.floor(v);
+    if (n > SCAN_CEILINGS[name]) {
+      throw new Error(
+        `scan.${name} 超过硬顶 ${SCAN_CEILINGS[name]}（收到 ${n}）。` +
+          '预算旋钮不是关闭开关：无上限的遍历等于没有资源闸。',
+      );
+    }
+    return n;
   };
   return {
     maxDepth: pick(scan.maxDepth, SCAN_DEFAULTS.maxDepth, 'maxDepth'),
     maxDirs: pick(scan.maxDirs, SCAN_DEFAULTS.maxDirs, 'maxDirs'),
+    maxEntries: pick(scan.maxEntries, SCAN_DEFAULTS.maxEntries, 'maxEntries'),
   };
 }
 
+export { SCAN_DEFAULTS, SCAN_CEILINGS };
+
 // ── 有效状态判定 ─────────────────────────────────────────────────────────────
 
 /**
@@ -186,7 +230,7 @@ const isUnder = (child, parent) => {
  * 绝不按名字扫任意后代的 `.claude/skills` —— 那会误伤普通目录。
  */
 export function findNestedTargets(targetPath, { targetSet = [], scan = {} } = {}) {
-  const { maxDepth, maxDirs } = normalizeScan(scan);
+  const { maxDepth, maxDirs, maxEntries } = normalizeScan(scan);
   const self = tryRealpath(targetPath);
   const hits = [];
   const seen = new Set();
@@ -217,35 +261,105 @@ export function findNestedTargets(targetPath, { targetSet = [], scan = {} } = {}
   }
 
   // ②b 向下：有界遍历，找带有效状态的后代
-  const scanResult = walkBounded(self, { maxDepth, maxDirs }, (dir) => {
+  const scanResult = walkBounded(self, { maxDepth, maxDirs, maxEntries }, (dir) => {
     if (dir !== self && hasGeolyState(dir)) add(dir, 'descendant', 'geoly-state');
   });
 
-  return { nested: hits, complete: scanResult.complete, visited: scanResult.visited };
+  return { nested: hits, ...scanResult };
+}
+
+// ── 「没扫完」的原因记账 ─────────────────────────────────────────────────────
+//
+// 🔴 一条**不告诉你撞的是哪个上限**的报错，指导不了任何行动。
+// 旧版把「深度到顶」「目录数超限」「读不进去」三种原因塞进同一句
+// 「深度上限 8 / 目录数上限 5000」里，用户读完既不知道该提哪个旋钮、
+// 也不知道是不是权限问题。所以原因必须是**结构化的事实**，不是一句话。
+//
+// 🔴 不变式：`complete === false` ⇒ `stops` 里至少有一项非空。
+// 一个说不出原因的 incomplete 等于「我拒绝了但我不知道为什么」，
+// 那种拒绝没法被修，也没法被审计。`assertAttributable` 在返回前兜住它。
+
+function newStops() {
+  return {
+    depth: { count: 0, samples: [] }, // 深度到顶、但下面还有目录
+    unreadable: { count: 0, samples: [] }, // EACCES/EPERM 等：有东西但看不了
+    dirs: null, // 目录数预算耗尽时正要处理的那个路径
+    entries: null, // 目录项预算耗尽时正要处理的那个路径
+  };
+}
+
+/** 样例只用来指路，不是清单：留前 `SAMPLE_MAX` 条，但**总数照记**。 */
+function sample(bucket, value) {
+  bucket.count += 1;
+  if (bucket.samples.length < SAMPLE_MAX) bucket.samples.push(value);
+}
+
+/**
+ * 🔴 样例要**确定性**：遍历用的是 LIFO 栈，同一棵树在不同 Node 版本／不同
+ * `readdir` 返回序下拿到的前 5 条可以不一样。不排序的话，报错文案与
+ * `--json` 输出就成了不可复现的东西 —— 用户贴给我们的两次输出对不上。
+ */
+function finalizeStops(stops) {
+  const byPath = (a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+  return {
+    depth: { count: stops.depth.count, samples: [...stops.depth.samples].sort() },
+    unreadable: {
+      count: stops.unreadable.count,
+      samples: [...stops.unreadable.samples].sort(byPath),
+    },
+    dirs: stops.dirs,
+    entries: stops.entries,
+  };
+}
+
+/** `complete:false` 却一个原因都说不出 → 那是本模块自己的 bug，不该悄悄发出去。 */
+function assertAttributable(complete, stops, where) {
+  if (complete) return;
+  if (stops.depth.count || stops.unreadable.count || stops.dirs || stops.entries) return;
+  throw new Error(`内部错误：${where} 报了 complete:false 却没有可归因的原因（记账漏了一条）`);
 }
 
 /**
  * 有界遍历。不跟随 symlink（`readdirSync` 的 Dirent 判类型，不 stat）、
  * 跳过 `.geoly` 自身（它的内容由状态路径检查负责，不是嵌套候选）。
  *
+ * ✅ 「跳过 `.geoly`」这一条**实测生效**：`<target>/.geoly/tx-1/stage/1/a/…/h`
+ *    这样 12 层的事务目录，扫描结果是 `visited:1, complete:true` ——
+ *    事务目录不吃深度预算。（回归测试见 target.test.mjs。）
+ *
  * 🔴 撞到上限**不静默放过**：调用方会因此记一条 `target.nested-scan-incomplete`。
  * 「扫不完」与「扫完了没有」是两件事，把前者说成后者就是在假装证明了一个否定命题。
  */
-function walkBounded(root, { maxDepth, maxDirs }, visit) {
+function walkBounded(root, { maxDepth, maxDirs, maxEntries }, visit) {
   let visited = 0;
+  let entries = 0;
+  let maxDepthSeen = 0;
   let complete = true;
+  const stops = newStops();
   const stack = [[root, 0]];
   while (stack.length) {
     const [dir, depth] = stack.pop();
     if (visited >= maxDirs) {
       complete = false;
+      stops.dirs = dir;
       break;
     }
     visited += 1;
+    if (depth > maxDepthSeen) maxDepthSeen = depth;
     visit(dir);
     if (depth >= maxDepth) {
       // 深度到顶但下面还有目录 → 同样是「没扫完」
-      if (hasSubdir(dir)) complete = false;
+      // 🔴 EACCES 与「确认下面还有目录」**互斥归因**：读不了的时候我们并没有
+      //    确认过下面有目录，把它同时记进 depth 会让文案既劝你提高深度、
+      //    又劝你修权限 —— 其中一半是编的。只记 unreadable。
+      const more = hasSubdir(dir);
+      if (more.unreadable) {
+        complete = false;
+        sample(stops.unreadable, { path: dir, code: more.code });
+      } else if (more.yes) {
+        complete = false;
+        sample(stops.depth, dir);
+      }
       continue;
     }
     let ents;
@@ -256,25 +370,104 @@ function walkBounded(root, { maxDepth, maxDirs }, visit) {
       // 静默跳过等于宣称「这里没有」，而我们并没有看过。
       // ⚠️ 但 ENOENT/ENOTDIR 是「本来就没有东西」——目录还没建、或扫描途中被删 ——
       // 那不是盲区，不能因此把每一次「target 尚不存在」的预检都判成扫不完。
-      if (!isAbsent(err)) complete = false;
+      if (!isAbsent(err)) {
+        complete = false;
+        sample(stops.unreadable, { path: dir, code: err.code ?? 'EUNKNOWN' });
+      }
       continue;
     }
+    // 🔴 预算检查必须**紧跟在这次 readdir 之后**，不能等到下一轮循环顶部。
+    //    等下一轮是 fail-open：`/usr/bin` 这种「924 个条目、一个子目录都没有」
+    //    的目录会把预算撑爆之后**直接把栈跑空**，于是返回 complete:true ——
+    //    预算超了却宣称扫完了。（实测：maxEntries:1 下 entries=924 而 complete:true。）
+    //    顺带把 stop 记在**真正超预算的那个目录**上，而不是下一个待处理目录。
+    entries += ents.length;
+    if (entries > maxEntries) {
+      complete = false;
+      stops.entries = dir;
+      break;
+    }
     for (const e of ents) {
       if (!e.isDirectory()) continue; // Dirent 的 isDirectory 对 symlink 返回 false
       if (e.name === STATE_DIR) continue;
       stack.push([join(dir, e.name), depth + 1]);
     }
   }
-  return { complete, visited };
+  assertAttributable(complete, stops, 'walkBounded');
+  return { complete, visited, entries, maxDepthSeen, stops: finalizeStops(stops) };
 }
 
+/**
+ * 深度到顶那一层：下面**还有没有**目录。
+ * 🔴 「读不了」与「有」要分开报：两者都让 `complete` 变 false，但用户的下一步不同
+ *    （一个是提高 `--scan-max-depth`，一个是去修权限）。旧版把两者合成一个布尔，
+ *    于是权限问题会被文案说成「深度不够」，把人指向错误的方向。
+ */
 function hasSubdir(dir) {
   try {
-    return readdirSync(dir, { withFileTypes: true }).some((e) => e.isDirectory() && e.name !== STATE_DIR);
+    const ents = readdirSync(dir, { withFileTypes: true });
+    return { yes: ents.some((e) => e.isDirectory() && e.name !== STATE_DIR), unreadable: false };
   } catch (err) {
     // 🔴 读不了 → 无法证明下面没有目录，按「还有」算；不存在则确实没有
-    return !isAbsent(err);
+    if (isAbsent(err)) return { yes: false, unreadable: false };
+    return { yes: true, unreadable: true, code: err.code ?? 'EUNKNOWN' };
+  }
+}
+
+/**
+ * 把「没扫完」的记账翻成一句**能指导下一步**的话。
+ *
+ * 🔴 三件事缺一不可：撞的是**哪个**上限、它的**实际值**、以及**怎么办**。
+ * 旧文案（「深度上限 8 / 目录数上限 5000」）三件事只占了半件 ——
+ * 它把两个上限并列念了一遍，既没说是哪个，也没给任何出路。
+ */
+function describeIncomplete(stops, bounds, walk) {
+  const parts = [];
+  if (stops.depth.count) {
+    parts.push(
+      `深度上限 ${bounds.maxDepth} 到顶，仍有 ${stops.depth.count} 处目录没往下看` +
+        `（例如 ${stops.depth.samples.join('、')}）` +
+        `；提高它：--scan-max-depth <N>（硬顶 ${SCAN_CEILINGS.maxDepth}）`,
+    );
+  }
+  if (stops.dirs) {
+    parts.push(
+      `目录数上限 ${bounds.maxDirs} 用尽（已访问 ${walk.visited} 个，停在 ${stops.dirs}）` +
+        `；提高它：--scan-max-dirs <N>（硬顶 ${SCAN_CEILINGS.maxDirs}）`,
+    );
+  }
+  if (stops.entries) {
+    parts.push(
+      `目录项上限 ${bounds.maxEntries} 用尽（已读 ${walk.entries} 条，停在 ${stops.entries}）` +
+        '；这通常意味着 target 下有超大目录，先确认那里该不该有这些文件',
+    );
   }
+  if (stops.unreadable.count) {
+    parts.push(
+      `有 ${stops.unreadable.count} 处目录读不进去（例如 ` +
+        stops.unreadable.samples.map((s) => `${s.path}[${s.code}]`).join('、') +
+        '）；这是权限问题，提高扫描上限没有用，请修好权限或换一个 target',
+    );
+  }
+  return parts.join('；');
+}
+
+/**
+ * 给机器读的那一半（`violation.detail`）。
+ *
+ * 🔴 文案与 detail 必须来自**同一份**记账，不能各算各的 ——
+ * 两边分头拼字符串正是「报错说 A、JSON 说 B」的来源。
+ * detail 里带 `limits`，是因为默认值会随版本变：用户贴给我们一份 JSON 时，
+ * 我们要能看出他当时**实际**跑的是哪一组预算，而不是去猜他装的哪个版本。
+ */
+function scanDetail(bounds, walk) {
+  return {
+    limits: { ...bounds },
+    visited: walk.visited,
+    entries: walk.entries,
+    maxDepthSeen: walk.maxDepthSeen,
+    stops: walk.stops,
+  };
 }
 
 /** 「这里本来就没东西」而不是「有东西但我看不了」。两者的 fail-closed 处置相反。 */
@@ -306,36 +499,70 @@ function tryRealpath(p) {
  * 动作点仍然必须复验并 fail-closed（见文件顶部）。
  */
 export function scanStatePaths(stateDir, scanOpts = {}) {
-  const { maxDepth, maxDirs } = normalizeScan(scanOpts);
+  const bounds = normalizeScan(scanOpts);
+  const { maxDepth, maxDirs, maxEntries } = bounds;
+  // 🔴 提前返回的三条路径也要给出**同形状**的结果：调用方读 `stops` 前不该先判
+  // 「这次是不是走了短路分支」。少一个字段就多一处 `?.`，而 `?.` 正是把
+  // 「没扫完」悄悄读成「没问题」的那种写法。
+  const empty = (over) => ({
+    symlinks: [],
+    notPlain: [],
+    complete: true,
+    visited: 0,
+    entries: 0,
+    maxDepthSeen: 0,
+    stops: finalizeStops(newStops()),
+    ...over,
+  });
   const bad = [];
   let st;
   try {
     st = lstatSync(stateDir);
   } catch (err) {
-    if (isAbsent(err)) return { symlinks: [], notPlain: [], complete: true }; // 还不存在，后面才创建
-    return { symlinks: [], notPlain: [], complete: false }; // 🔴 看不了 ≠ 没问题
+    if (isAbsent(err)) return empty(); // 还不存在，后面才创建
+    // 🔴 看不了 ≠ 没问题。而且要说清是**哪一种**看不了 —— 这条以前只回一个
+    // `complete:false`，报错文案便只能泛泛地说「深度/目录数/读不进去」三选一。
+    const stops = newStops();
+    sample(stops.unreadable, { path: stateDir, code: err.code ?? 'EUNKNOWN' });
+    return empty({ complete: false, stops: finalizeStops(stops) });
   }
-  if (st.isSymbolicLink()) return { symlinks: [stateDir], notPlain: [], complete: true };
-  if (!st.isDirectory()) return { symlinks: [], notPlain: [stateDir], complete: true };
+  if (st.isSymbolicLink()) return empty({ symlinks: [stateDir] });
+  if (!st.isDirectory()) return empty({ notPlain: [stateDir] });
 
   const symlinks = [];
   let visited = 0;
+  let entries = 0;
+  let maxDepthSeen = 0;
   let complete = true;
+  const stops = newStops();
   const stack = [[stateDir, 0]];
   while (stack.length) {
     const [dir, depth] = stack.pop();
     if (visited >= maxDirs) {
       complete = false;
+      stops.dirs = dir;
       break;
     }
     visited += 1;
+    if (depth > maxDepthSeen) maxDepthSeen = depth;
     let ents;
     try {
       ents = readdirSync(dir, { withFileTypes: true });
     } catch (err) {
-      if (!isAbsent(err)) complete = false; // 🔴 看不了就不能宣称这下面没有 symlink
+      if (!isAbsent(err)) {
+        complete = false; // 🔴 看不了就不能宣称这下面没有 symlink
+        sample(stops.unreadable, { path: dir, code: err.code ?? 'EUNKNOWN' });
+      }
       continue;
     }
+    // 🔴 同 walkBounded：检查必须紧跟 readdir，等下一轮循环顶部是 fail-open
+    //    （目录项撑爆预算、但没有子目录可推 → 栈跑空 → 宣称 complete:true）。
+    entries += ents.length;
+    if (entries > maxEntries) {
+      complete = false;
+      stops.entries = dir;
+      break;
+    }
     for (const e of ents) {
       const p = join(dir, e.name);
       if (e.isSymbolicLink()) {
@@ -344,13 +571,25 @@ export function scanStatePaths(stateDir, scanOpts = {}) {
       }
       if (e.isDirectory()) {
         if (depth < maxDepth) stack.push([p, depth + 1]);
-        else complete = false;
+        else {
+          complete = false;
+          sample(stops.depth, p);
+        }
         continue;
       }
       if (!e.isFile()) bad.push(p); // FIFO / socket / 设备节点
     }
   }
-  return { symlinks, notPlain: bad, complete };
+  assertAttributable(complete, stops, 'scanStatePaths');
+  return {
+    symlinks,
+    notPlain: bad,
+    complete,
+    visited,
+    entries,
+    maxDepthSeen,
+    stops: finalizeStops(stops),
+  };
 }
 
 // ── 挂载点（§3.4） ───────────────────────────────────────────────────────────
@@ -556,13 +795,15 @@ export function precheckTarget(targetPath, opts = {}) {
     add(
       V.STATE_SCAN_INCOMPLETE,
       stateDir,
-      `${stateDir} 没扫完（深度上限/目录数上限，或某个子目录读不进去），` +
-        '无法证明状态路径里没有符号链接',
+      `${stateDir} 没扫完，无法证明状态路径里没有符号链接 —— ` +
+        describeIncomplete(stateScan.stops, bounds, stateScan),
+      scanDetail(bounds, stateScan),
     );
   }
 
   // ── §3.5 嵌套 target
-  const { nested, complete } = findNestedTargets(targetPath, { targetSet, scan: bounds });
+  const nestedScan = findNestedTargets(targetPath, { targetSet, scan: bounds });
+  const { nested, complete } = nestedScan;
   for (const n of nested) {
     add(
       V.NESTED_TARGET,
@@ -577,8 +818,9 @@ export function precheckTarget(targetPath, opts = {}) {
     add(
       V.SCAN_INCOMPLETE,
       targetPath,
-      `嵌套 target 扫描未跑完（深度上限 ${bounds.maxDepth} / ` +
-        `目录数上限 ${bounds.maxDirs}），无法证明其下没有嵌套 target`,
+      `嵌套 target 扫描未跑完，无法证明 ${targetPath} 之下没有嵌套 target —— ` +
+        describeIncomplete(nestedScan.stops, bounds, nestedScan),
+      scanDetail(bounds, nestedScan),
     );
   }