paseo-req-kit 1.13.0-beta.5 → 1.13.0

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 每个版本分为"使用者会看到的变化"和"升级须知"。升级步骤见 [docs/guide/安装与升级.md](docs/guide/安装与升级.md)。
 
+## 1.13.0
+
+稳定版：内网能装能用、在 Paseo 网页端审查原型、不靠看图检查界面、看得见 token 花在哪。内容包括 1.13.0-beta.1 至 beta.5（详见下面各条）和下面新增的三项，设计决定见 ADR 0032、0033。
+
+### 使用者会看到的变化
+
+- **内网安装和文档**：`npx -y [--registry=<镜像地址>] paseo-req-kit@latest install` 一条命令装好，只需要 npm 源；`req docs` 在本机打开文档站点。
+- **在 Paseo 里审查原型**：需求页面和"等你处理"里的主按钮"审查原型并确认方案"，在原型上点要改的地方、选改法、用自己的话补一句，提交后整理成清单交给需求会话。
+- **界面检查 `req ui-check`**：用本机的 Edge 或 Chrome，用文字报告显示不全、遮挡、超出屏幕、文字太淡、没名字的控件、报错，并和确认过的原型对文字；功能验证自动使用，不需要模型看图。
+- **token**：`req stats` 和插件的"token 花在哪"；可选的每个需求预算（`budget`）；开始时和 `req status` 里的"预计还要多久"。
+- **后台进程意外退出时由插件直接继续**，不再每小时叫醒对话；等待批准的权限进"等你处理"。
+- **新增：打断大目录搜索**（`scanGuard`，默认开）：步骤 agent 搜索整个磁盘、用户目录、Maven 本地仓库（`~/.m2`）、Gradle 缓存、全局或整个 `node_modules` 时，流水线一分钟后打断这个命令，并告诉 agent 改用什么办法（`git grep`、按坐标直接打开那一个依赖、`mvn dependency:tree`）；任何搜索运行超过 5 分钟也打断。构建和测试命令不受影响。各步骤的提示词也写明了只在仓库里搜索。
+- **新增：预算不起作用时会说**：agent 不报告 token 用量时，设了预算的需求在第一步之后提醒一次"预算不会起作用"，`req doctor` 也会检查。
+- **新增：从别的电脑打开审查页时说明原因**：审查页默认只在运行 Paseo 的电脑上能打开；从别的电脑打开 Paseo 网页、点"审查原型"时，页面写明为什么看不到、怎么设置。只设 `REQ_KIT_REVIEW_HOST` 时，审查页地址用这台电脑的计算机名。
+
+### 升级须知
+
+- 新配置都可选：`budget`（默认不限）、`scanGuard`（默认开：`{ "enabled": true, "minutes": 5, "paths": [] }`，关闭写 `"enabled": false`）。
+- 打开 `scanGuard` 时，流水线每分钟查看一次步骤 agent 的状态（以前每 10 分钟），只是读取状态，不占模型 token。
+- 原型按新约定写（`data-ac`、`data-label`、`<section data-state>`、不写脚本），旧原型照常能看，只是审查页认不出区域和状态。
+- 1.12 时预约的"对话定时检查"会留到过期（最多 3 天），装了插件后新需求不再预约，不用手动删。
+- 装过插件的，`req upgrade` 会一并更新插件。新的安装脚本只能安装 1.13 及以后的版本。
+- 状态文件、使用记录和 `req api` 的新增字段见各 beta 的升级须知；`recoveries` 新增 `stop_scan`。
+- 发布前 Linux 和 Windows 的测试都必须通过。
+
 ## 1.13.0-beta.5
 
 ### 使用者会看到的变化

package/contracts/state.md

@@ -21,7 +21,7 @@
 | `stopKind` | string \| null | 可选，1.12 起。停下等人的原因代码：必要的决定 `approval`（确认方案）、`phase_gate`（研发完成，等待测试）、`business`（需求方决定）、`reproduce`（缺陷复现不了）；中断 `timeout`、`agent_error`、`invalid_result`、`transient`、`stopped`、`process_exit`、`budget`（1.13，用完 token 预算）、`other`。运行中或完成时为 null |
 | `budget` | object | 可选，1.13 起，配置了 `budget.tokens` 时。`{ allowance, warnedAt }`：停下前允许用到的 tokens（预算，每次用完后继续再加一份）；已经提醒过的那一档 |
 | `waitingPermission` | object \| null | 可选，1.13 起。步骤 agent 在等权限批准时：`{ agentId, stepTitle, requests, since }`；没有在等时为 null |
-| `recoveries` | array | 可选，1.12 起。流水线自己处理掉的问题（最多保留 200 条）：`at`、`key`（步骤键）、`kind`（`retry` 重试 / `reattach` 接着等上一次的 agent / `reuse_result` 沿用上一次 agent 的结果 / `extend_timeout` 超时后多等一轮 / `redo` 新开 agent 重做 / `fallback` 换备用模型 / `auto_resume` 预约自动继续 / `quota_wait` 预约在额度恢复后继续 / `self_answer` 方案审核的问题由 builder 自答）、`detail` |
+| `recoveries` | array | 可选，1.12 起。流水线自己处理掉的问题（最多保留 200 条）：`at`、`key`（步骤键）、`kind`（`retry` 重试 / `reattach` 接着等上一次的 agent / `reuse_result` 沿用上一次 agent 的结果 / `extend_timeout` 超时后多等一轮 / `redo` 新开 agent 重做 / `fallback` 换备用模型 / `auto_resume` 预约自动继续 / `quota_wait` 预约在额度恢复后继续 / `self_answer` 方案审核的问题由 builder 自答 / `stop_scan` 打断了搜索大目录的命令，1.13 起）、`detail` |
 | `profile` | `quick` \| `standard` | 档位 |
 | `branch` | string \| null | 工作分支，启动时确定 |
 | `milestones` | string[] | 已发送的进展通知，续跑时不重复发送 |

package/docs/guide//347/273/264/346/212/244/350/200/205/346/214/207/345/215/227.md

@@ -39,7 +39,7 @@
 3. **写 `CHANGELOG.md`**：新增一节，分"使用者会看到的变化"和"升级须知"两部分。升级须知写清：要不要重跑 `/req-setup`、提示词有哪些变化（影响用 `prompts.local/` 覆盖过的人）、文件格式有没有变化、旧行为的兼容方式。
 4. **验证**：`npm test`、`npm run typecheck`、`npm run eval:self-check`；步骤提示词或引擎有改动时跑 `npm run eval`，把 `summary.md` 复制到 `evals/baselines/<版本>.md`；入口或手册有改动时跑对话评估，记入记分表。主版本发布前，在一个真实项目里试运行一周。
 5. **冒烟测试**：在一台干净的机器（或临时的 `REQ_KIT_HOME` 和 HOME）上按 [安装与升级](安装与升级.md) 安装，跑冒烟测试第 1–4 项；至少有一台是 Windows。
-6. **合并到 `main`，标签自动打上**：`main` 收到 `package.json` 版本号还没有标签的提交时，`.github/workflows/release.yml` 先在这个提交上跑测试、类型检查和评估自检，通过后才打上同名标签（不用自己打，也不需要推送标签的权限），接着在同一次运行里发布。测试没通过时不会留下标签，把修复合到 `main` 就会用同一个版本号重新发布（1.12.1 起；1.13 起任何推到 `main` 的提交都会检查，不必再改 `package.json`）。也可以照旧自己打：在 GitHub 上建 Release 并新建标签 `<版本>`，或推送 `git tag -a <版本>`，同样会触发发布。发布流程：跑测试、类型检查和评估自检，核对标签与 `package.json` 版本一致，然后发布到 npm（预发布版用 `beta` 标签，正式版用 `latest`），正式版再设置 `paseo-<小版本>` 标签，把 `npm pack` 的安装包附在 Release 上，Release 正文取自 CHANGELOG 的这一节。标签同时也是 git 方式安装的版本列表，所以改版本号的提交要在验证完成后再合到 `main`（自动打标签的时机就是它）；打错了尽快删除标签，npm 上发布错的版本用 `npm deprecate` 标注（npm 不允许重新发布同一版本号）。
+6. **合并到 `main`，标签自动打上**：`main` 收到 `package.json` 版本号还没有标签的提交时，`.github/workflows/release.yml` 先在这个提交上跑测试（Linux 和 Windows 各一遍，1.13 起）、类型检查和评估自检，通过后才打上同名标签（不用自己打，也不需要推送标签的权限），接着在同一次运行里发布。测试没通过时不会留下标签，把修复合到 `main` 就会用同一个版本号重新发布（1.12.1 起；1.13 起任何推到 `main` 的提交都会检查，不必再改 `package.json`）。也可以照旧自己打：在 GitHub 上建 Release 并新建标签 `<版本>`，或推送 `git tag -a <版本>`，同样会触发发布。发布流程：跑测试、类型检查和评估自检，核对标签与 `package.json` 版本一致，然后发布到 npm（预发布版用 `beta` 标签，正式版用 `latest`），正式版再设置 `paseo-<小版本>` 标签，把 `npm pack` 的安装包附在 Release 上，Release 正文取自 CHANGELOG 的这一节。标签同时也是 git 方式安装的版本列表，所以改版本号的提交要在验证完成后再合到 `main`（自动打标签的时机就是它）；打错了尽快删除标签，npm 上发布错的版本用 `npm deprecate` 标注（npm 不允许重新发布同一版本号）。
 7. **通知**：把"使用者会看到的变化"发给使用者，把"升级须知"发给各台机器的安装者；团队配置的 `requiredVersion` 需要提高时，在团队配置仓库中修改。
 
 **npm 发布的一次性设置**：可信发布（trusted publisher）要在 npm 上已有的包的设置页里配置，所以第一个版本在本机手工发布一次，不需要生成任何口令：

package/docs/guide//351/241/271/347/233/256/345/256/232/345/210/266/344/270/216/350/277/220/350/241/214/350/247/204/345/210/231.md

@@ -47,7 +47,7 @@ spec 头部的 `- 类型：` 决定流水线走哪种做法（1.8 起）。缺
 
 为了让审查页能用，方案设计按约定写原型：每个改动区域标 `data-ac`（对应的 AC）和 `data-label`（用需求方的话说是什么），各种状态包在 `<section data-state="状态名">` 中，按钮、标题、字段名写最终的文字。原型里的脚本不会运行。
 
-审查页由一个本机服务提供：用到时在后台启动，空闲 4 小时后自己退出，只监听 `127.0.0.1`，地址中带随机令牌（插件设为只读时给只读的地址）。审查页允许被本机地址上的页面（Paseo 网页端）嵌入；要限定或放开，设 `REQ_KIT_REVIEW_FRAME_ANCESTORS`（CSP `frame-ancestors` 的值）。需求方在别的电脑上用浏览器访问 Paseo 网页端时，在运行 Paseo daemon 的机器上设置环境变量 `REQ_KIT_REVIEW_HOST`（例如 `0.0.0.0`）、`REQ_KIT_REVIEW_PUBLIC_URL`（别人访问这台机器用的地址，例如 `http://10.1.2.3:6781`），需要时用 `REQ_KIT_REVIEW_PORT` 换端口（默认 6781），然后重启 Paseo daemon 让插件拿到新的环境变量。
+审查页由一个本机服务提供：用到时在后台启动，空闲 4 小时后自己退出，只监听 `127.0.0.1`，地址中带随机令牌（插件设为只读时给只读的地址）。审查页允许被本机地址上的页面（Paseo 网页端）嵌入；要限定或放开，设 `REQ_KIT_REVIEW_FRAME_ANCESTORS`（CSP `frame-ancestors` 的值）。需求方在别的电脑上用浏览器访问 Paseo 网页端时，在运行 Paseo daemon 的机器上设置环境变量 `REQ_KIT_REVIEW_HOST`（例如 `0.0.0.0`）、`REQ_KIT_REVIEW_PUBLIC_URL`（别人访问这台机器用的地址，例如 `http://10.1.2.3:6781`），需要时用 `REQ_KIT_REVIEW_PORT` 换端口（默认 6781），然后重启 Paseo daemon 让插件拿到新的环境变量（只设 `REQ_KIT_REVIEW_HOST` 时，地址用这台电脑的计算机名）。没有设置时从别的电脑打开 Paseo 网页、点"审查原型"，页面会说明为什么打不开、该怎么设置（1.13）。
 
 ## 代码评审分两个方向
 
@@ -267,6 +267,8 @@ spec 头部的 `- 类型：` 决定流水线走哪种做法（1.8 起）。缺
 
 写在本机、团队或项目配置中都可以，例如 `"budget": { "tokens": 3000000 }`。还没有数据时，先不设预算跑几个需求，用 `req stats` 的"token 花在哪"看每个需求的中位数，再按它的两三倍设。
 
+agent 不报告 token 用量时（有些模型或接入方式不报告），预算不会起作用：设了预算的需求在第一个步骤结束后会在对话里说明一次，流水线照常继续；`req doctor` 也会检查本机最近的需求有没有用量数据。
+
 用时估算不用配置：本机已完成的同档位需求有 3 个以上时，开始开发的回复里写出"agent 合计用时和 token 的中位数"作为参考；`req status` 和插件的需求页面显示"预计还要约多久"（按中位数减去已用的 agent 时间，不含等人的时间），超过中位数时如实说"已超过通常的用时"。
 
 ## 并行编排：确认前审阅、方案提案、浏览器验证
@@ -526,7 +528,7 @@ Paseo 自带的 `/paseo-advisor`、`/paseo-committee` 等编排 skill 也可以
 
 **结果文件**：每步必须写一个 JSON 结果文件，流水线只看它，不看 agent 的回复文字。文件缺失或格式不对时，会在同一个会话里提醒 agent 补写，最多 2 次，仍不对则判定该步骤失败。
 
-**等待与超时**：每步有总时限（`stepTimeoutMinutes`）。到时 agent 还在做时，先再给它同样长的时间（`selfHeal`，见下）；仍未完成才判定失败，但不停止 agent。继续（`--resume`、自动重试）时先看这一步上一次的 agent：已经做完、结果文件有效就直接用它的结果；还在做就接着等它一轮（这一轮不再额外延长）；第二次仍超时才停止它、另起一个 agent。需求改过、开始了新一次尝试时，上一次留下的 agent 直接停掉，不接手（1.12.1）。同一步不会有两个 agent 同时在做（它们会改同样的文件、在同一个工作区提交、写同一个结果文件）。连续读不到 agent 状态时同样处理。等待被拆成每段 10 分钟，连接断开时自动重试。agent 等待权限批准时，同一个请求只通知一次，然后继续等待。
+**等待与超时**：每步有总时限（`stepTimeoutMinutes`）。到时 agent 还在做时，先再给它同样长的时间（`selfHeal`，见下）；仍未完成才判定失败，但不停止 agent。继续（`--resume`、自动重试）时先看这一步上一次的 agent：已经做完、结果文件有效就直接用它的结果；还在做就接着等它一轮（这一轮不再额外延长）；第二次仍超时才停止它、另起一个 agent。需求改过、开始了新一次尝试时，上一次留下的 agent 直接停掉，不接手（1.12.1）。同一步不会有两个 agent 同时在做（它们会改同样的文件、在同一个工作区提交、写同一个结果文件）。连续读不到 agent 状态时同样处理。等待被拆成每段 10 分钟（打开 `scanGuard` 时每段 1 分钟，以便查看正在运行的命令），连接断开时自动重试。agent 等待权限批准时，同一个请求只通知一次，然后继续等待。
 
 **临时错误自动重试**：步骤因限流（429）、服务暂时不可用（502/503/504/529、overloaded）、网络中断等临时错误失败时，等待后用新的 agent 重做这一步，并告诉它工作区里可能留有上一次没做完的改动。默认最多重试 2 次，分别等 1 分钟和 5 分钟：
 
@@ -554,6 +556,14 @@ Paseo 自带的 `/paseo-advisor`、`/paseo-committee` 等编排 skill 也可以
 
 自动处理的每一次都记在进度日志、状态文件的 `recoveries` 和使用记录中，`req stats` 的"人工介入"一节汇总：停下等人的原因、自动处理了多少次、到达提测的需求中没有非必要介入的比例。
 
+**打断大目录搜索**（1.13，`scanGuard`，默认开）：步骤 agent 有时为了找一个类或一个包，去搜索整个磁盘、用户目录、Maven 本地仓库（`~/.m2`）、Gradle 缓存、全局 `node_modules` 或整个 `node_modules`，一次就是几十分钟，这一步迟迟做不完。步骤运行时，流水线大约每分钟看一次 agent 正在运行的命令：搜索这类大目录的命令运行超过 1 分钟、或者任何搜索命令运行超过 `minutes` 分钟，就打断它，并告诉 agent 改用什么办法（在仓库里用 `git grep`；按 `pom.xml` 里的坐标直接打开那一个依赖目录、用 `unzip -l` 看那一个 jar；`mvn dependency:tree`；找不到就写进"假设"继续）。构建和测试命令（`mvn`、`gradle`、`npm test` 等）不打断；只搜具体的子目录（如 `~/.m2/repository/com/acme/foo`）或排除了 `node_modules` 的搜索也不算。同一个命令只打断一次，每轮最多打断 5 次；每次都记在进度日志和 `recoveries`（`stop_scan`）中。各步骤的提示词里也写明了只在仓库里搜索。
+
+```json
+"scanGuard": { "enabled": true, "minutes": 5, "paths": ["D:/share"] }
+```
+
+`paths`：另外不允许整个搜索的目录（例如共享盘）；`enabled: false` 关闭。
+
 **同一个目录一次只运行一条流水线**，因为各步骤都在这个目录中修改和提交。需要并行时，为每个需求使用单独的 worktree 工作区。
 
 ## 注意事项

package/engine/prompts/00-shared-context.md

@@ -65,6 +65,8 @@ time	step	ref	decision	alternatives	reason	kind	needs_human
 
 **遵循项目已有的做法。** 开始前阅读 `CLAUDE.md`、`AGENTS.md`、`README`、`CONTRIBUTING`（存在哪个读哪个），以及 `GLOSSARY.md`（业务与领域术语；较早的项目可能叫 `CONTEXT.md`）和 `docs/adr/`（已有决定）。命名、目录结构、测试写法、提交信息格式都跟随项目现状。
 
+**只在仓库里搜索，不要扫大目录。** 不要搜索整个磁盘、用户目录、依赖缓存（Maven 的 `~/.m2`、Gradle 的 `~/.gradle`、npm 缓存、全局 `node_modules`）或整个 `node_modules`，这类搜索要几十分钟，流水线会在一分钟后打断它。在仓库里找用 `git grep -n` 或 `git ls-files`。要看某个依赖：先从 `pom.xml`、`build.gradle`、`package.json` 确定它的坐标和版本，再直接打开那一个目录（如 `~/.m2/repository/<groupId 的点换成 />/<artifactId>/<版本>/`、`node_modules/<包名>/`），用 `unzip -l`、`jar tf` 看那一个 jar。不知道类在哪个依赖里时，`mvn dependency:tree` 比搜索快。
+
 **只做这个需求。** 不顺手重构无关代码，不升级无关依赖，不改无关的格式。看到无关的问题可以在产物里提一句，留给人来决定。
 
 **多轮的步骤。** `<pipeline-context>` 写明"第 2 轮"或之后时，说明这一步之前已经执行过：

package/engine/src/activity.ts

@@ -85,3 +85,26 @@ export function describeActivity(items: ActivityItem[], now = new Date()): strin
     return `  ${when ? `${when}：` : ""}${a.text}`;
   });
 }
+
+/**
+ * 1.13: the tool call still running at the end of the timeline (for the scan guard): its
+ * command or search pattern and when it started (the first entry seen for that call).
+ */
+export function runningToolOf(entries: TimelineEntry[]): import("./scan-guard.js").RunningTool | null {
+  const calls = new Map<string, { first: string; last: Record<string, unknown> }>();
+  for (const entry of entries) {
+    const it = entry.item as Record<string, unknown> | null;
+    if (!it || typeof it !== "object" || it.type !== "tool_call" || typeof it.callId !== "string") continue;
+    const seen = calls.get(it.callId);
+    if (seen) seen.last = it;
+    else calls.set(it.callId, { first: entry.timestamp, last: it });
+  }
+  const running = [...calls.entries()].filter(([, c]) => c.last.status === "running");
+  if (running.length === 0) return null;
+  const [callId, call] = running[running.length - 1];
+  const detail = (call.last.detail ?? {}) as Record<string, unknown>;
+  const kind = String(detail.type ?? "unknown");
+  const raw = kind === "shell" ? detail.command : kind === "search" ? detail.query : (detail.command ?? "");
+  const text = Array.isArray(raw) ? raw.join(" ") : String(raw ?? "");
+  return { kind, text, startedAt: call.first, callId };
+}

package/engine/src/config-view.ts

@@ -122,6 +122,11 @@ const CATALOG: Array<{ id: string; title: string; description: string; keys: Rec
         description: "一个需求所有步骤合计（输入 + 输出）最多用多少 tokens；用到一定比例时提醒，用完后做完当前步骤就停下，继续开发会再给一份预算。",
         display: (v) => { const b = v as PipelineConfig["budget"]; return b.tokens === null ? "不限" : `${b.tokens >= 10_000 ? `${Math.round(b.tokens / 1000) / 10} 万` : b.tokens}，用到 ${b.warnPercent}% 时提醒`; },
       },
+      scanGuard: {
+        label: "打断大目录搜索",
+        description: "步骤 agent 搜索整个磁盘、用户目录、Maven 仓库（.m2）、全局 node_modules 等很大的目录时，一分钟后打断它并告诉它该怎么查；任何搜索运行太久也打断。",
+        display: (v) => { const g = v as PipelineConfig["scanGuard"]; return g.enabled ? `开，搜索超过 ${g.minutes} 分钟也打断${g.paths.length ? `；另外不许整个搜索：${g.paths.join("、")}` : ""}` : "关"; },
+      },
     },
   },
   {

package/engine/src/config.ts

@@ -245,6 +245,12 @@ export interface PipelineConfig {
    * pipeline stops to ask; null: no limit. A notice at warnPercent; continuing gives one more budget.
    */
   budget: { tokens: number | null; warnPercent: number };
+  /**
+   * 1.13: interrupt a step agent's search of a very large directory (the whole disk, the home
+   * directory, ~/.m2, the global node_modules, …) after a minute, and any search after `minutes`,
+   * and tell it how to find what it needs instead. `paths`: more directories never to search whole.
+   */
+  scanGuard: import("./scan-guard.js").ScanGuardSettings;
   /** Automatic retries of a step after a transient error (rate limit, dropped connection). */
   retry: { attempts: number; backoffSeconds: number[] };
   /**
@@ -355,6 +361,7 @@ export const DEFAULT_CONFIG: PipelineConfig = {
   factory: { pollMinutes: 5, titleTags: ["[AI]", "【AI】"], maxNewPerPoll: 3 },
   autoConfirm: { hours: 0 },
   budget: { tokens: null, warnPercent: 80 },
+  scanGuard: { enabled: true, minutes: 5, paths: [] },
   retry: { attempts: 2, backoffSeconds: [60, 300] },
   paseoServices: "auto",
   serviceReadySeconds: 120,
@@ -424,6 +431,7 @@ function merge(base: PipelineConfig, raw: Record<string, unknown>): PipelineConf
   merged.factory = { ...base.factory, ...(isRecord(raw.factory) ? raw.factory : {}) } as PipelineConfig["factory"];
   merged.autoConfirm = { ...base.autoConfirm, ...(isRecord(raw.autoConfirm) ? raw.autoConfirm : {}) } as PipelineConfig["autoConfirm"];
   merged.budget = { ...base.budget, ...(isRecord(raw.budget) ? raw.budget : {}) } as PipelineConfig["budget"];
+  merged.scanGuard = { ...base.scanGuard, ...(isRecord(raw.scanGuard) ? raw.scanGuard : {}) } as PipelineConfig["scanGuard"];
   if (isRecord(raw.cardSource)) {
     const c = raw.cardSource;
     merged.cardSource = {
@@ -645,6 +653,10 @@ function validate(config: PipelineConfig): void {
   if (typeof config.budget.warnPercent !== "number" || config.budget.warnPercent <= 0 || config.budget.warnPercent >= 100) {
     throw new ConfigError("budget.warnPercent 必须在 1 到 99 之间（用到预算的百分之几时提醒）");
   }
+  const sg = config.scanGuard;
+  if (typeof sg.enabled !== "boolean") throw new ConfigError("scanGuard.enabled 必须是 true 或 false");
+  if (typeof sg.minutes !== "number" || !(sg.minutes >= 1)) throw new ConfigError("scanGuard.minutes 必须是至少 1 的分钟数（搜索运行多久后打断）");
+  if (!Array.isArray(sg.paths) || !sg.paths.every((p) => typeof p === "string" && p.trim())) throw new ConfigError('scanGuard.paths 必须是目录路径的数组，例如 ["D:/share"]');
   const f = config.factory;
   if (typeof f.pollMinutes !== "number" || !(f.pollMinutes >= 1)) throw new ConfigError("factory.pollMinutes 必须是至少 1 的分钟数");
   if (!Number.isInteger(f.maxNewPerPoll) || f.maxNewPerPoll < 1) throw new ConfigError("factory.maxNewPerPoll 必须是正整数");

package/engine/src/control.ts

@@ -5,7 +5,7 @@ import { describeActivity } from "./activity.js";
 import { describeExternal } from "./integrations.js";
 import { PHASE_MODE_LABELS, PROFILE_LABELS, type PipelineConfig, REQUIREMENT_TYPE_LABELS } from "./config.js";
 import type { AgentRuntime, RuntimeFactory } from "./runtime.js";
-import { isAlive, type PipelineState, readState, type StepRecord, writeState } from "./state.js";
+import { currentLockHolder, isAlive, type PipelineState, readState, type StepRecord, writeState } from "./state.js";
 import { stepTitle } from "./playbooks.js";
 import { describeTotals, totals } from "./usage.js";
 
@@ -195,6 +195,13 @@ export async function stopPipeline(input: StopInput): Promise<{ stopped: boolean
   latest.stopReason = wasAlive ? "已被手动停止" : "后台进程已意外退出";
   latest.stopKind = wasAlive ? "stopped" : "process_exit";
   writeState(input.statePath, latest);
+  // On Windows a stopped process gets no chance to remove the repository lock itself; this
+  // removes a lock whose holder is gone (anywhere, harmless when it was already removed).
+  try {
+    currentLockHolder(latest.repo);
+  } catch {
+    // The next start checks the lock the same way.
+  }
 
   // The step agent keeps working unless told otherwise; stop it so it changes nothing more.
   if (interrupted.some((r) => r.agentId)) {

package/engine/src/doctor.ts

@@ -18,6 +18,8 @@ import { defaultConfigPath, findDependency, KIT_ROOT, kitVersion } from "./locat
 import { PROJECT_DIR } from "./prompts.js";
 import { describeAgentProfile, ProfileResolutionError, profilesFromDaemonConfig, resolveConfigProfiles, usesPaseoProfiles } from "./paseo-profiles.js";
 import { isAlive, STATE_VERSION } from "./state.js";
+import { readRuns, runsFile } from "./records.js";
+import { byRequirement, dedupe } from "./stats.js";
 import { resolveCommand } from "./integrations.js";
 
 const counts = { fail: 0, warn: 0 };
@@ -160,6 +162,7 @@ function configuration(configPath: string, repo: string | null): PipelineConfig
       if (satisfies(kitVersion(), required)) report("ok", `版本要求 ${required}：当前 ${kitVersion()} 满足`);
       else report("warn", `团队或项目要求 req-kit ${required}，当前为 ${kitVersion()}`, "按 docs/guide/安装与升级.md 升级到符合要求的版本");
     }
+    budgetUsage(loaded.config);
     return loaded.config;
   } catch (error) {
     if (!(error instanceof ConfigError)) throw error;
@@ -168,6 +171,21 @@ function configuration(configPath: string, repo: string | null): PipelineConfig
   }
 }
 
+/** 1.13: a token budget only works when the agents report usage; this machine's recent requirements say whether they do. */
+function budgetUsage(config: PipelineConfig): void {
+  if (config.budget.tokens === null) return;
+  let recent: ReturnType<typeof byRequirement> = [];
+  try {
+    recent = byRequirement(dedupe(readRuns(runsFile()))).slice(-3);
+  } catch {
+    return;
+  }
+  if (recent.length === 0) return;
+  if (recent.every((q) => q.inputTokens === null && q.outputTokens === null)) {
+    report("warn", `设了 token 预算（每个需求 ${config.budget.tokens}），但本机最近 ${recent.length} 个需求的 agent 都没有报告 token 用量，预算不会起作用`, "换用会报告用量的 agent；不需要预算时把 budget.tokens 设为 null");
+  } else report("ok", "token 预算：agent 会报告用量");
+}
+
 /** Daemon address from the raw file, so the daemon can be checked even when the agents are not filled in yet. */
 function daemonSettings(configPath: string): PipelineConfig {
   try {

package/engine/src/paseo-runtime.ts

@@ -1,5 +1,5 @@
 import type { PaseoAgentHandle, PaseoClient } from "@getpaseo/client";
-import { summarizeActivity } from "./activity.js";
+import { runningToolOf, summarizeActivity } from "./activity.js";
 import { type AgentProfile, isResolved, type PipelineConfig } from "./config.js";
 import { profilesFromDaemonConfig } from "./paseo-profiles.js";
 import { cronAt, localTimeZone } from "./schedule-time.js";
@@ -288,6 +288,14 @@ export function createRuntimeWithClient(
         return null;
       }
     },
+    async runningTool(agentId) {
+      try {
+        const page = await client.agents.ref(agentId).timeline.refetch({ direction: "tail", limit: 40 });
+        return runningToolOf(page.entries);
+      } catch {
+        return null;
+      }
+    },
     async createWorktree(request) {
       if (!client.workspaces) throw new Error("这个 Paseo 版本不支持新建工作区");
       const workspace = await client.workspaces.create({

package/engine/src/pipeline.ts

@@ -1,3 +1,4 @@
+import { judge as judgeScan } from "./scan-guard.js";
 import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
@@ -200,6 +201,13 @@ async function checkBudget(ctx: PipelineContext, stepTitle: string): Promise<voi
   const budget = (ctx.state.budget ??= { allowance: limit, warnedAt: null });
   const used = tokensUsed(ctx.state);
   if (used >= budget.allowance) throw new BudgetReached(used, budget.allowance);
+  // 1.13: agents that report no usage make the budget do nothing; say so once instead of keeping quiet.
+  const finished = ctx.state.history.filter((h) => h.endedAt);
+  if (used === 0 && finished.length > 0 && !budget.noUsageNoticed && finished.every((h) => !h.usage || (h.usage.inputTokens === undefined && h.usage.outputTokens === undefined))) {
+    budget.noUsageNoticed = true;
+    save(ctx);
+    await notifyOrigin(ctx, noUsageMessage(shownFeatureDir(ctx), limit));
+  }
   if (used >= (budget.allowance * ctx.config.budget.warnPercent) / 100 && budget.warnedAt !== budget.allowance) {
     budget.warnedAt = budget.allowance;
     save(ctx);
@@ -209,6 +217,10 @@ async function checkBudget(ctx: PipelineContext, stepTitle: string): Promise<voi
   }
 }
 
+export function noUsageMessage(featureDir: string, limit: number): string {
+  return `【需求开发流水线通知】${featureDir} 设了每个需求 ${tokenText(limit)} tokens 的预算，但已完成的步骤里 agent 都没有报告 token 用量，所以预算不会起作用，token 统计和预计也没有数据。流水线照常继续。要让预算生效，请换用会报告用量的 agent（Paseo 里能看到用量的那种）；不需要预算时可以在配置里把 budget.tokens 设为 null。这条消息只是告知，不需要处理。`;
+}
+
 class BusinessDecisionNeeded extends Error {
   constructor(
     public readonly questions: string[],
@@ -621,8 +633,37 @@ interface Deadline {
   record?: StepRecord;
 }
 
+/** How often the scan guard looks at the running tool call. */
+const SCAN_CHECK_SECONDS = 60;
+/** At most this many interruptions per turn; after that the step's time limit takes over. */
+const SCAN_MAX_INTERRUPTS = 5;
+
+interface ScanGuardMemory {
+  interrupted: Set<string>;
+  count: number;
+}
+
+/** 1.13: interrupts a search of a very large directory (or a search that runs too long), once per tool call. */
+async function guardScan(ctx: PipelineContext, agent: StepAgent, def: StepDef, key: string, memory: ScanGuardMemory): Promise<void> {
+  if (!ctx.config.scanGuard.enabled || memory.count >= SCAN_MAX_INTERRUPTS) return;
+  const tool = await ctx.runtime.runningTool(agent.id).catch(() => null);
+  if (!tool || memory.interrupted.has(tool.callId)) return;
+  const verdict = judgeScan(tool, ctx.config.scanGuard);
+  if (!verdict) return;
+  memory.interrupted.add(tool.callId);
+  memory.count += 1;
+  try {
+    await ctx.runtime.interruptAgent(agent.id, verdict.message);
+  } catch (error) {
+    ctx.log(`打断「${def.title}」的搜索失败：${(error as Error).message}`);
+    return;
+  }
+  recover(ctx, key, "stop_scan", `「${def.title}」的命令${verdict.reason}，已打断并告诉 agent 改用别的办法：${tool.text.replace(/\s+/g, " ").slice(0, 120)}`);
+}
+
 async function waitForTurn(ctx: PipelineContext, agent: StepAgent, def: StepDef, agentTitle: string, deadline: Deadline): Promise<AgentUsage | null> {
   const notifiedPermissions = new Set<string>();
+  const guard: ScanGuardMemory = { interrupted: new Set(), count: 0 };
   let consecutiveErrors = 0;
   for (;;) {
     let remaining = deadline.at - Date.now();
@@ -644,7 +685,9 @@ async function waitForTurn(ctx: PipelineContext, agent: StepAgent, def: StepDef,
     }
     let outcome;
     try {
-      outcome = await agent.wait(Math.min(ctx.config.waitChunkSeconds * 1000, remaining));
+      // 1.13: with the scan guard on, look at the running tool call about once a minute.
+      const chunk = ctx.config.scanGuard.enabled ? Math.min(ctx.config.waitChunkSeconds, SCAN_CHECK_SECONDS) : ctx.config.waitChunkSeconds;
+      outcome = await agent.wait(Math.min(chunk * 1000, remaining));
       consecutiveErrors = 0;
     } catch (error) {
       consecutiveErrors += 1;
@@ -665,6 +708,7 @@ async function waitForTurn(ctx: PipelineContext, agent: StepAgent, def: StepDef,
       case "idle":
         return outcome.usage ?? null;
       case "timeout":
+        await guardScan(ctx, agent, def, deadline.key, guard);
         continue;
       case "error":
         throw new AgentErrored(def.title, `agent 报告错误：${outcome.error ?? "未知错误"}`);

package/engine/src/review.ts

@@ -11,6 +11,7 @@
 import { spawn, spawnSync } from "node:child_process";
 import crypto from "node:crypto";
 import fs from "node:fs";
+import os from "node:os";
 import http from "node:http";
 import path from "node:path";
 import { ENGINE_DIR, KIT_ROOT, kitHome, kitVersion } from "./locations.js";
@@ -510,7 +511,8 @@ async function serve(env: NodeJS.ProcessEnv): Promise<void> {
     token,
     readToken,
     version: kitVersion(),
-    publicUrl: env.REQ_KIT_REVIEW_PUBLIC_URL?.trim() || `http://127.0.0.1:${port}`,
+    // Listening for other computers without a public address: this computer's name is the best guess.
+    publicUrl: env.REQ_KIT_REVIEW_PUBLIC_URL?.trim() || `http://${/^(127\.|localhost$|::1$)/.test(host) ? "127.0.0.1" : os.hostname()}:${port}`,
     startedAt: new Date().toISOString(),
   };
   fs.mkdirSync(kitHome(env), { recursive: true });

package/engine/src/runtime.ts

@@ -141,6 +141,8 @@ export interface AgentRuntime {
   providerQuota(providers: string[]): Promise<ProviderQuota[] | null>;
   /** The agent's latest actions, oldest first; null when they cannot be read. */
   recentActivity(agentId: string, limit: number): Promise<ActivityItem[] | null>;
+  /** 1.13: the tool call the agent is running now (the latest one still running), or null. */
+  runningTool(agentId: string): Promise<import("./scan-guard.js").RunningTool | null>;
   /** Which Paseo tools step agents get (Settings → Agents); null when unknown. */
   capabilities(): Promise<{ paseoTools: boolean; browser: boolean } | null>;
   /** 1.12: whether each agent provider is installed and logged in ("ready"); null when the daemon does not say. */

package/engine/src/scan-guard.ts

@@ -0,0 +1,132 @@
+// Stopping commands that search very large directories (1.13): a step agent that looks for a
+// class or a package by searching the whole home directory, the Maven repository (~/.m2), the
+// global node_modules or a drive can sit for many minutes and never finish the step. While a step
+// runs, the pipeline looks at the agent's running tool call about once a minute; a search of such
+// a directory (after a minute) or any search that runs too long is interrupted, and the agent is
+// told how to find what it needs without the scan. A plain check of the command text, no model.
+import os from "node:os";
+
+export interface RunningTool {
+  /** Paseo's tool kind: "shell", "search", … */
+  kind: string;
+  /** The command (shell) or the pattern (search). */
+  text: string;
+  /** When the call started (ISO time). */
+  startedAt: string;
+  /** The tool call's ID, so the same call is interrupted at most once. */
+  callId: string;
+}
+
+export interface ScanGuardSettings {
+  enabled: boolean;
+  /** A search that runs this long is interrupted wherever it searches. */
+  minutes: number;
+  /** More directories never to be searched as a whole (e.g. a shared drive). */
+  paths: string[];
+}
+
+/** A search of a large directory gets this long before it is interrupted (most are quick to fail or finish). */
+export const BIG_DIR_GRACE_MS = 60_000;
+
+/** Commands that walk a directory tree. */
+const SCAN_COMMAND =
+  /(^|[\s;&|("'`])(find|fd|locate|mlocate|tree|du|rg|ag|ack|grep\s+(-\w*[rR]\w*|--recursive)|egrep\s+-\w*[rR]|ls\s+(-\w*R\w*)|Get-ChildItem\b[^|;]*-r(ecurse)?\b|gci\b[^|;]*-r(ecurse)?\b|dir\b[^|;]*(\/s\b|-r(ecurse)?\b)|findstr\b[^|;]*\/s\b|where\s+\/r|Select-String\b[^|;]*-Path\b[^|;]*\*\*)(?=$|[\s;&|)"'`])/i;
+
+/** Option values that keep a directory out of a search: not what it searches. */
+const EXCLUSIONS = [
+  /--exclude(-dir)?(=|\s+)("[^"]*"|'[^']*'|\S+)/gi,
+  /(-g|--glob|--iglob)(=|\s+)("![^"]*"|'![^']*'|!\S+)/gi,
+  /(-not|!)\s+-(i?path|i?name|wholename)\s+("[^"]*"|'[^']*'|\S+)/gi,
+  /-(i?path|i?name|wholename)\s+("[^"]*"|'[^']*'|\S+)\s+-prune/gi,
+  /--(ignore-dir|ignore-directory|exclude-from)(=|\s+)("[^"]*"|'[^']*'|\S+)/gi,
+  /-Exclude\s+("[^"]*"|'[^']*'|\S+)/gi,
+];
+
+const END = String.raw`(?=$|[\s"'*;|&)\]` + "`" + `])`;
+const START = String.raw`(?:^|[\s"'=(\[` + "`" + `])`;
+
+const escape = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const norm = (s: string) => s.replace(/\\/g, "/");
+
+interface BigDir {
+  re: RegExp;
+  label: string;
+}
+
+function bigDirs(home: string, extra: string[]): BigDir[] {
+  const h = escape(norm(home).replace(/\/+$/, ""));
+  const homes = String.raw`(?:~|\$HOME|\$\{HOME\}|%USERPROFILE%|\$env:USERPROFILE|\$env:HOME${h ? `|${h}` : ""})`;
+  const sub = (p: string) => new RegExp(`${START}(?:${homes}/|[^\\s"']*/)?${p}/?${END}`, "i");
+  const list: BigDir[] = [
+    { re: new RegExp(`${START}/${END}`), label: "整个磁盘（/）" },
+    { re: new RegExp(`${START}[a-z]:/?${END}`, "i"), label: "整个磁盘" },
+    { re: new RegExp(`${START}${homes}/?${END}`, "i"), label: "用户目录" },
+    { re: sub(String.raw`\.m2(?:/repository)?`), label: "Maven 本地仓库（.m2）" },
+    { re: sub(String.raw`\.gradle(?:/caches)?`), label: "Gradle 缓存（.gradle）" },
+    { re: sub(String.raw`\.ivy2`), label: "Ivy 缓存（.ivy2）" },
+    { re: sub(String.raw`(?:\.npm|\.pnpm-store|\.yarn|AppData/Local/(?:npm-cache|pnpm|Yarn))`), label: "npm/pnpm/yarn 缓存" },
+    { re: sub(String.raw`(?:\.nvm|\.volta|\.fnm|AppData/Roaming/nvm)`), label: "Node.js 版本目录" },
+    { re: sub(String.raw`\.cache`), label: "缓存目录（.cache）" },
+    { re: sub(String.raw`(?:\.cargo|go/pkg/mod|\.rustup)`), label: "Rust/Go 依赖缓存" },
+    { re: sub(String.raw`AppData(?:/Roaming|/Local)?`), label: "AppData" },
+    { re: sub(String.raw`(?:usr/(?:local/)?lib/node_modules|AppData/Roaming/npm(?:/node_modules)?)`), label: "全局 node_modules" },
+    { re: /npm\s+root\s+-g|pnpm\s+root\s+-g/i, label: "全局 node_modules" },
+    { re: sub("node_modules"), label: "node_modules" },
+    { re: new RegExp(`${START}(?:[a-z]:)?/(?:usr(?:/lib|/share|/local)?|opt|var|Library|Program Files(?: \\(x86\\))?|Windows)/?${END}`, "i"), label: "系统目录" },
+    { re: sub(String.raw`site-packages`), label: "Python 依赖目录（site-packages）" },
+  ];
+  for (const p of extra) {
+    const n = escape(norm(p).replace(/\/+$/, ""));
+    if (n) list.push({ re: new RegExp(`${START}${n}/?${END}`, "i"), label: p });
+  }
+  return list;
+}
+
+/** The large directory a command searches as a whole, or null. */
+export function bigDirOf(command: string, options: { home?: string; paths?: string[] } = {}): string | null {
+  if (!SCAN_COMMAND.test(command)) return null;
+  let text = command;
+  for (const re of EXCLUSIONS) text = text.replace(re, " ");
+  text = norm(text);
+  for (const d of bigDirs(options.home ?? os.homedir(), options.paths ?? [])) if (d.re.test(text)) return d.label;
+  return null;
+}
+
+export function isScan(tool: Pick<RunningTool, "kind" | "text">): boolean {
+  return tool.kind === "search" || (tool.kind === "shell" && SCAN_COMMAND.test(tool.text));
+}
+
+export interface ScanVerdict {
+  /** Why: the large directory, or how long the search has run. */
+  reason: string;
+  /** What the agent is told (the interrupt message). */
+  message: string;
+}
+
+const clip = (s: string, n = 160) => {
+  const one = s.replace(/\s+/g, " ").trim();
+  return one.length > n ? `${one.slice(0, n - 1)}…` : one;
+};
+
+/** Whether the running tool call should be interrupted, and what to tell the agent. */
+export function judge(tool: RunningTool | null, settings: ScanGuardSettings, now = new Date(), home = os.homedir()): ScanVerdict | null {
+  if (!tool || !settings.enabled) return null;
+  const ran = now.getTime() - new Date(tool.startedAt).getTime();
+  if (!(ran >= 0)) return null;
+  const big = tool.kind === "shell" ? bigDirOf(tool.text, { home, paths: settings.paths }) : null;
+  let reason: string | null = null;
+  if (big && ran >= BIG_DIR_GRACE_MS) reason = `在搜索${big}`;
+  else if (isScan(tool) && ran >= settings.minutes * 60_000) reason = `搜索已经运行了 ${Math.round(ran / 60_000)} 分钟`;
+  if (!reason) return null;
+  return { reason, message: scanMessage(tool.text, reason) };
+}
+
+export function scanMessage(command: string, reason: string): string {
+  return [
+    `【流水线提示】已停止你刚才的${command ? `命令「${clip(command)}」` : "搜索"}：它${reason}，这类搜索要很久，会让这一步一直做不完。请继续完成本步骤的任务，但不要再搜索整个磁盘、用户目录或依赖缓存，改用下面的办法：`,
+    "- 在仓库里找：用 `git grep -n <内容>` 或 `git ls-files | grep <文件名>`；用 rg 时只在仓库目录里搜，它会跳过 .gitignore 里的目录。",
+    "- 找某个 Maven/Gradle 依赖里的类：先在 pom.xml / build.gradle 里确定 groupId、artifactId 和版本，直接打开 `~/.m2/repository/<groupId 的点换成 />/<artifactId>/<版本>/` 这一个目录，用 `unzip -l <jar> | grep <类名>` 或 `jar tf` 看那一个 jar；要源码时用 `mvn dependency:sources -DincludeArtifactIds=<artifactId>`。不知道是哪个依赖时，`mvn dependency:tree` 比搜索快。",
+    "- 找某个 npm 包：直接看仓库里的 `node_modules/<包名>/package.json`，以及其中 main、types 指向的文件；不要搜索整个 node_modules 或全局 node_modules。",
+    "- 实在找不到就不要再找了：按项目代码和文档里能确认的信息继续，把不确定的地方写进本步骤产物的\"假设\"一节。",
+  ].join("\n");
+}

package/engine/src/state.ts

@@ -50,7 +50,7 @@ export type StopKind =
 export interface Recovery {
   at: string;
   key: string;
-  kind: "retry" | "reattach" | "reuse_result" | "extend_timeout" | "redo" | "fallback" | "auto_resume" | "quota_wait" | "self_answer";
+  kind: "retry" | "reattach" | "reuse_result" | "extend_timeout" | "redo" | "fallback" | "auto_resume" | "quota_wait" | "self_answer" | "stop_scan";
   detail: string;
 }
 
@@ -89,6 +89,8 @@ export interface BudgetState {
   allowance: number;
   /** The allowance a warning was given for, so each level warns once. */
   warnedAt: number | null;
+  /** 1.13: the person was told the agents report no token usage (so the budget cannot work). */
+  noUsageNoticed?: boolean;
 }
 
 export interface PipelineState {

package/engine/src/stats.ts

@@ -506,6 +506,7 @@ export function describeStats(s: StatsSummary): string {
     reattach: "接着等还在做的 agent",
     reuse_result: "沿用旧 agent 的结果",
     extend_timeout: "超时后多等一轮",
+    stop_scan: "打断大目录搜索",
     redo: "新开 agent 重做",
     fallback: "换备用模型",
     auto_resume: "自动继续",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paseo-req-kit",
-  "version": "1.13.0-beta.5",
+  "version": "1.13.0",
   "description": "req-kit: a requirement-development workflow for Paseo. /req aligns a requirement in chat; the engine runs design, implementation, review and verification as Paseo agents.",
   "type": "module",
   "license": "MIT",

package/paseo-plugin/client/review.tsx

@@ -6,7 +6,7 @@ import { Text, View } from "react-native";
 import { useReviewUrl } from "./data";
 import { openReview } from "./nav";
 import { Button, Status, useStyles } from "./ui";
-import { canEmbedPages, embeddedPage } from "./web";
+import { canEmbedPages, embeddedPage, reviewUnreachable } from "./web";
 
 type Theme = PluginHostProps["theme"];
 
@@ -28,6 +28,16 @@ export function ReviewScreen({ theme, layout, params }: PluginScreenProps) {
     );
   }
   const { url, readOnly } = review.data;
+  if (reviewUnreachable(url)) {
+    return (
+      <View style={[s.screen, { padding: 12 }]}>
+        <View style={[s.card, { gap: 8 }]}>
+          <Text style={s.text}>原型审查页只在运行 Paseo 的那台电脑上能打开（地址是 {new URL(url).host}），你现在是从另一台电脑打开的 Paseo 网页，所以看不到。</Text>
+          <Text style={s.muted}>{`办法：到运行 Paseo 的那台电脑上打开 Paseo 网页再点"审查原型"；或者请管理员在那台电脑上设置环境变量 REQ_KIT_REVIEW_HOST=0.0.0.0 和 REQ_KIT_REVIEW_PUBLIC_URL=http://<那台电脑的地址>:6781，再重启 Paseo daemon，审查页就能从别的电脑打开（能连上那台电脑的人都能看到审查页，提交意见要用页面地址里的口令）。也可以直接看功能目录里的 preview.md 和 prototype/。`}</Text>
+        </View>
+      </View>
+    );
+  }
   const frame = canEmbedPages ? embeddedPage(url, `原型审查：${params.title ?? featureDir}`) : null;
   return (
     <View style={[s.screen, { gap: 6 }]}>

package/paseo-plugin/client/web.ts

@@ -15,3 +15,20 @@ export function embeddedPage(url: string, title: string): ReactElement | null {
     style: { border: 0, width: "100%", height: "calc(100vh - 120px)", minHeight: 560, display: "block", background: "transparent" },
   } as Record<string, unknown>);
 }
+
+const LOOPBACK = /^(127\.\d+\.\d+\.\d+|localhost|\[::1\]|::1)$/i;
+
+/**
+ * Whether the review page cannot load in this browser: the review server listens only on the
+ * daemon's machine (127.0.0.1) and this Paseo web page was opened from another computer.
+ */
+export function reviewUnreachable(url: string): boolean {
+  if (Platform.OS !== "web") return false;
+  try {
+    const page = (globalThis as { location?: { hostname?: string } }).location?.hostname ?? "";
+    const target = new URL(url).hostname;
+    return LOOPBACK.test(target) && !!page && !LOOPBACK.test(page);
+  } catch {
+    return false;
+  }
+}