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

package/engine/src/launch.ts

@@ -16,6 +16,7 @@ import { loadConfig, PHASE_MODE_LABELS, type PipelineConfig, PROFILE_LABELS } fr
 import { cardFieldsText } from "./integrations.js";
 import { defaultConfigPath, ENGINE_DIR } from "./locations.js";
 import { describeLiveActivity, describeStatus, stopPipeline } from "./control.js";
+import { trackRequirement } from "./records.js";
 import { describeFeatures, featuresWithRuns, findWorktreeRun, listFeatures, resolveFeatureArg } from "./features.js";
 import { checkChatCwd, normalizeFeatureDir, preflight, type PreflightResult, specProfile, verifyPhaseProblem } from "./preflight.js";
 import { loadRuntimeFactory } from "./runtime-loader.js";
@@ -92,6 +93,22 @@ if (args.cardFields) {
   }
 }
 
+if (args.track) {
+  // 1.14: the requirement shows in the plugin from the start of the interview, with its chat.
+  try {
+    const repo = fs.realpathSync(args.repo);
+    const featureDir = normalizeFeatureDir(repo, args.featureDir);
+    const dir = path.join(repo, featureDir);
+    if (!fs.existsSync(dir)) throw new Error(`功能目录不存在：${featureDir}`);
+    trackRequirement(repo, featureDir, args.originAgentId);
+    console.log(`已登记需求：${featureDir}（Paseo 的 req-kit 插件里能看到它，状态"对齐中"${args.originAgentId ? "，关联这个对话" : ""}）`);
+    process.exit(0);
+  } catch (error) {
+    console.error(`没能登记需求：${(error as Error).message}`);
+    process.exit(2);
+  }
+}
+
 if (args.list) {
   console.log(describeFeatures(listFeatures(args.repo), args.repo));
   process.exit(0);
@@ -344,7 +361,9 @@ if (args.worktree) {
   try {
     ownWorktree = await Promise.race([
       create(),
-      new Promise<never>((_, reject) => setTimeout(() => reject(new Error("连接 Paseo 新建工作区超过 2 分钟没有完成")), 120_000).unref()),
+      // 1.14: big repositories (Windows especially) can take minutes to check out. Giving up early
+      // left a branch with only the spec on it; now it waits, and a later start continues there.
+      new Promise<never>((_, reject) => setTimeout(() => reject(new Error("连接 Paseo 新建工作区超过 15 分钟没有完成。工作区可能稍后才建好：再执行一次启动命令，会在已建好的工作区里接着开始")), 15 * 60_000).unref()),
     ]);
   } catch (error) {
     fail(`没能为这个需求新建工作区：${(error as Error).message}`);
@@ -356,7 +375,7 @@ if (args.worktree) {
   try {
     checked = preflight(args, hashFile);
   } catch (error) {
-    fail(`新工作区 ${ownWorktree.repo} 已建好，但无法在那里启动：${(error as Error).message}`);
+    fail(`新工作区 ${ownWorktree.repo} 已建好，但无法在那里启动：${(error as Error).message}\n问题解决后再执行一次启动命令，会在这个工作区里接着开始（不会再新建）。`);
   }
 }
 
@@ -403,8 +422,10 @@ console.log(
         ? "只做研发：写好提测说明和研发报告后结束，测试由人完成。"
         : null,
     ownWorktree
-      ? `已为这个需求新建工作区：${ownWorktree.repo}（分支 ${ownWorktree.branch}，在 Paseo 侧边栏中可以看到）。开发在那里进行，步骤仍挂在这个对话下；这个对话的工作目录不变。` +
-        `需求文件已移到 ${path.join(ownWorktree.repo, checked.featureDir)}${ownWorktree.removedSource ? "" : "（这里原有的已提交版本保留不动）"}，之后读写需求文件请用这个路径。`
+      ? `${ownWorktree.reused ? "在上次已建好的工作区中开始" : "已为这个需求新建工作区"}：${ownWorktree.repo}（分支 ${ownWorktree.branch}，在 Paseo 侧边栏中可以看到）。开发在那里进行，步骤仍挂在这个对话下；这个对话的工作目录不变。` +
+        `需求文件已移到 ${path.join(ownWorktree.repo, checked.featureDir)}${ownWorktree.removedSource ? "" : "（这里原有的已提交版本保留不动）"}，之后读写需求文件请用这个路径。` +
+        (ownWorktree.carried.length ? `\n访谈中改过的 ${ownWorktree.carried.join("、")} 也一起带过去提交了；这里的未提交改动保留不动，确认无误后可以撤销。` : "") +
+        ownWorktree.warnings.map((w) => `\n注意：${w}`).join("")
       : args.sourceRepo
         ? `这个需求在为它新建的工作区中开发：${checked.repo}`
         : null,

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({
@@ -299,6 +307,11 @@ export function createRuntimeWithClient(
       if (!directory) throw new Error("Paseo 没有返回新工作区的目录");
       return { workspaceId: workspace.id, directory };
     },
+    async openWorkspace(directory) {
+      if (!client.workspaces) throw new Error("这个 Paseo 版本不支持接手已有的工作区目录");
+      const handle = await client.workspaces.open({ cwd: directory });
+      return { workspaceId: handle.id };
+    },
     async waitForWorkspaceSetup(workspaceId, timeoutMs) {
       const api = await getScripts();
       if (!api) return { status: "none", error: null };

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/preflight.ts

@@ -31,6 +31,8 @@ export interface LaunchArgs {
   list: boolean;
   /** --card-fields: what /req confirms with the spec for the external systems (card.json). */
   cardFields?: boolean;
+  /** 1.14 --track: register a requirement being aligned, before the pipeline runs (shown in the plugin). */
+  track?: boolean;
   /** --spec-review: independent review of the draft spec, before confirmation. */
   specReview: boolean;
   /** --worktree: create a Paseo worktree workspace for this requirement and develop there. */

package/engine/src/records.ts

@@ -47,6 +47,8 @@ export interface IndexEntry {
   /** Name of the project: the source checkout's directory name. */
   project: string;
   registeredAt: string;
+  /** 1.14: the chat the requirement is being aligned in (registered before the pipeline ran). */
+  chatAgentId?: string | null;
 }
 
 export function indexDir(env: NodeJS.ProcessEnv = process.env): string {
@@ -59,7 +61,7 @@ export function requirementKey(sourceOrRepo: string, featureDir: string): string
 }
 
 /** Records where this requirement lives, if it is not recorded that way already. Never throws. */
-export function registerRequirement(state: Pick<PipelineState, "repo" | "featureDir" | "worktree">, env: NodeJS.ProcessEnv = process.env): void {
+export function registerRequirement(state: Pick<PipelineState, "repo" | "featureDir" | "worktree">, env: NodeJS.ProcessEnv = process.env, chatAgentId: string | null = null): void {
   if (recordingOff(env)) return;
   try {
     const source = state.worktree?.sourceRepo ?? null;
@@ -75,6 +77,7 @@ export function registerRequirement(state: Pick<PipelineState, "repo" | "feature
       workspaceId: state.worktree?.workspaceId ?? null,
       project: path.basename(real(source ?? state.repo)),
       registeredAt: existing?.registeredAt ?? new Date().toISOString(),
+      ...(chatAgentId ?? existing?.chatAgentId ? { chatAgentId: chatAgentId ?? existing?.chatAgentId ?? null } : {}),
     };
     if (existing && JSON.stringify(existing) === JSON.stringify(entry)) return;
     fs.mkdirSync(path.dirname(file), { recursive: true });
@@ -86,6 +89,24 @@ export function registerRequirement(state: Pick<PipelineState, "repo" | "feature
   }
 }
 
+/**
+ * 1.14: a requirement whose interview has started: marked in its feature directory
+ * (.pipeline/tracked.json, not committed) and registered with its chat, so the plugin lists it
+ * before the pipeline ever runs.
+ */
+export function trackRequirement(repo: string, featureDir: string, chatAgentId: string | null, env: NodeJS.ProcessEnv = process.env): void {
+  const marker = path.join(repo, featureDir, ".pipeline", "tracked.json");
+  fs.mkdirSync(path.dirname(marker), { recursive: true });
+  let since = new Date().toISOString();
+  try {
+    since = (JSON.parse(fs.readFileSync(marker, "utf8")) as { since?: string }).since ?? since;
+  } catch {
+    // First time.
+  }
+  fs.writeFileSync(marker, `${JSON.stringify({ since, chatAgentId }, null, 2)}\n`);
+  registerRequirement({ repo, featureDir, worktree: null }, env, chatAgentId);
+}
+
 function readEntry(file: string): IndexEntry | null {
   try {
     const raw = JSON.parse(fs.readFileSync(file, "utf8")) as IndexEntry;
@@ -104,7 +125,8 @@ export function readIndex(env: NodeJS.ProcessEnv = process.env): Array<IndexEntr
     .filter((n) => n.endsWith(".json"))
     .map((n) => readEntry(path.join(dir, n)))
     .filter((e): e is IndexEntry => e !== null)
-    .map((e) => ({ ...e, present: fs.existsSync(path.join(e.repo, e.featureDir, ".pipeline", "state.json")) }));
+    // 1.14: a requirement still in its interview has no state yet, only its notes.
+    .map((e) => ({ ...e, present: ["spec.md", "alignment.md", ".pipeline/state.json", ".pipeline/tracked.json"].some((f) => fs.existsSync(path.join(e.repo, e.featureDir, f))) }));
 }
 
 /** Removes the entries whose requirement is gone. Returns how many. */

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

@@ -135,12 +135,16 @@ export interface AgentRuntime {
   stopServices(target: ServiceTarget, names: string[]): Promise<void>;
   /** Creates a Paseo worktree workspace (paseo.json setup runs in the background). */
   createWorktree(request: WorktreeRequest): Promise<{ workspaceId: string; directory: string }>;
+  /** 1.14: the Paseo workspace of an existing directory (opened as one if it is not yet). */
+  openWorkspace?(directory: string): Promise<{ workspaceId: string }>;
   /** Waits for the workspace's paseo.json setup; "none" when there is nothing to wait for or it cannot be read. */
   waitForWorkspaceSetup(workspaceId: string, timeoutMs: number): Promise<{ status: "completed" | "failed" | "none" | "timeout"; error: string | null }>;
   /** Subscription windows of the given providers; null when Paseo has no usage data. */
   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: "自动继续",