@te-river/opencode-team-mode 1.7.7 → 1.7.9

package/dist/tm/webfetch.d.ts

@@ -19,8 +19,13 @@
  *     allowlist (an allowlisted shortener cannot bounce off-site);
  *   - a URL naming an env file (isEnvFilePath) is refused — the R6 red
  *     line applies to remote spellings too;
- *   - response body capped at 2 MB, whole fetch under a hard 20 s timeout,
- *     HTML stripped to text before governance.
+ *   - response body capped at 2 MB, each request under a hard 20 s timeout,
+ *     HTML stripped to text before governance;
+ *   - a FAILED REQUEST (network throw, per-attempt timeout, HTTP 429/5xx) is
+ *     retried on the fixed 5s/10s/20s ladder (max 3 retries, same config the
+ *     provider-error governor reads) and the reply says when it was used —
+ *     a policy refusal (allowlist, red line, env-file, 403/418, other 4xx) is
+ *     never re-asked, because asking again earns the same verdict.
  */
 import { type TmAskFn } from "./perm-ask.js";
 import type { ToolResult } from "../types.js";
@@ -151,6 +156,10 @@ export interface WebFetchResult {
     /** Set when the body came from the URL cache instead of the network — the
      *  reply says so, because a re-served page is not a freshly-verified one. */
     cachedAt?: number;
+    /** The HTTP retries actually taken before this body arrived (absent = the
+     *  first request answered).  Rides up to the reply so 第N次重试后成功 is a
+     *  measurement of what happened, not a restatement of the config. */
+    retries?: number[];
 }
 export type FetchImpl = (input: string, init?: Record<string, unknown>) => Promise<{
     ok?: boolean;
@@ -167,12 +176,76 @@ export type FetchImpl = (input: string, init?: Record<string, unknown>) => Promi
 /** A 429/503 that says WHEN, not just NO.  Only the delta-seconds spelling
  *  becomes a sentence: an HTTP-date would be laundered into a countdown the
  *  agent has no way to honor (there is no sleep in this toolset), and a wrong
- *  number is worse than no number. */
-export declare function retryAfterNote(raw: unknown): string;
+ *  number is worse than no number.
+ *  `retriesTaken` keeps the advice consistent with what this tool just DID:
+ *  telling the agent "别对同一 URL 原地重试" while the reply carries our own
+ *  「重试3次」 is one sentence contradicting the other (review finding #4).
+ *  Either way the Retry-After number stays visible. */
+export declare function retryAfterNote(raw: unknown, retriesTaken?: number): string;
+/** Retries per request: attempt #1 waits 5s, #2 waits 10s, #3 waits 20s, then
+ *  the failure is reported.  Same ladder the provider-error governor promises,
+ *  derived from the SAME config (`retryBaseMs` doubling, no jitter), so the two
+ *  failure surfaces cannot drift into two different meanings of "retry". */
+export declare const HTTP_RETRY_MAX = 3;
+/** A transient HTTP failure worth asking again: 429 (rate limited) and any 5xx.
+ *  Everything else in the 4xx band is a VERDICT about this request — a retry
+ *  would earn the same bytes, and 403/418 carry their own browser directive. */
+export declare function isRetryableHttpStatus(status: number): boolean;
+/** Pure so a test can pin the ladder without sleeping: retry `attempt` (1-based)
+ *  waits `baseMs × 2^(attempt-1)` clamped to `maxMs`; attempt 0 or anything past
+ *  `HTTP_RETRY_MAX` waits nothing (0 = no further retry).  The clamp is what
+ *  makes the docs' promise true (review finding #3): with `retryBaseMs > 15000`
+ *  the un-clamped third rung (base×4) exceeded `retryMaxMs`, while the `retry`
+ *  key says BOTH surfaces share one capped ladder.  Defaults read from the
+ *  registry, so the shipped path stays exactly 5s/10s/20s (all under 60s). */
+export declare function httpRetryDelayMs(attempt: number, baseMs?: number, maxMs?: number): number;
+export interface HttpRetryPolicy {
+    enabled: boolean;
+    baseMs: number;
+    maxRetries: number;
+    /** One rung's ceiling — the registry's `retryMaxMs`, threaded so the ladder
+     *  and the governor cannot drift into two meanings of "capped". */
+    maxMs: number;
+}
+/** The registry is the one source of truth: `retry: "off"` disables the HTTP
+ *  retries as well as the governor's directive, and `retryBaseMs` sets the
+ *  first wait.  Callers holding a resolved `TmConfig` pass it in; a caller with
+ *  none (the search engine legs' inner helper, a PTC bridge) gets the defaults. */
+export declare function httpRetryFromConfig(cfg?: Partial<Pick<TmConfig, "retry" | "retryBaseMs">>): HttpRetryPolicy;
+/** The same policy from an explicit per-call partial (what `fetchWebText`'s
+ *  `retry` option carries): every field falls back to the registry, never to a
+ *  guessed number, so a caller that passes `{}` retries exactly like the tool.
+ *  `maxRetries` is CLAMPED to HTTP_RETRY_MAX (review finding #5): the ladder has
+ *  three rungs, and `httpRetryDelayMs` answers 0 past them — an accepted 9 would
+ *  take six zero-delay "retries" the note renderers used to print as 「1s」, a
+ *  wait that never happened. */
+export declare function resolveHttpRetry(policy?: Partial<HttpRetryPolicy>): HttpRetryPolicy;
+/** Honest labelling (design goal #6): a page that arrived on the third try is
+ *  not the same fact as a page that arrived on the first, and a failure after
+ *  three tries says how long the caller waited for nothing.  Zero-delay entries
+ *  are filtered before rendering (review finding #5): a 0 is "the ladder was
+ *  already walked", and `Math.max(1, round(0/1000))` would print it as a 「1s」
+ *  wait that never happened.  With the maxRetries clamp these cannot reach the
+ *  list any more — this is the belt under the braces. */
+export declare function httpRetryNote(delaysMs: readonly number[]): string;
+/** The failure counterpart — how many times, at what waits, still no answer.
+ *  Zero-delay entries filtered for the same reason as above. */
+export declare function httpRetryFailNote(delaysMs: readonly number[]): string;
 /**
  * Fetch a URL with hard timeout, byte cap, and MANUAL redirects — every
  * hop is re-checked against the allowlist before it is requested.
- * `fetchImpl` is injectable for tests (default: globalThis.fetch).
+ * `fetchImpl` is injectable for tests (default: globalThis.fetch), as is
+ * `sleep` (default: setTimeout) so the ladder can be pinned without waiting
+ * on it.
+ *
+ * HTTP retries: a failed request (network throw, per-attempt timeout, 429,
+ * 5xx) is retried up to `HTTP_RETRY_MAX` times with the fixed 5s/10s/20s
+ * ladder.  The timeout stays PER ATTEMPT, so the worst case for one URL is
+ * 4 × 20s of fetching plus 35s of waiting ≈ 115s — accepted deliberately:
+ * a transient failure that clears in 20s should not cost the caller a new
+ * round, and the reply says out loud when the ladder was used up.
+ * A policy refusal is never retried, and a retry re-requests THIS hop only —
+ * it never re-follows a redirect chain and never re-asks a dialog.
  */
 export declare function fetchWebText(url: URL, allowlist: readonly string[], opts?: {
     timeoutMs?: number;
@@ -203,6 +276,19 @@ export declare function fetchWebText(url: URL, allowlist: readonly string[], opt
      *  content-type — which is also why the reply says so when a body arrived
      *  as Markdown.  A re-negotiation is a `fresh: true` away. */
     accept?: string;
+    /** HTTP retry policy (see `httpRetryFromConfig`).  Omitted = the registry
+     *  defaults, so tm_webfetch, every tm_search engine leg and the PTC bridge
+     *  all retry the same way without repeating the knobs at each call site. */
+    retry?: Partial<HttpRetryPolicy>;
+    /** Injectable sleep so a test can pin the 5s/10s/20s ladder instantly. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Audit sink: one row per retry ACTUALLY taken (the caller writes it to the
+     *  trajectory — fetchWebText owns no pipeline instance of its own). */
+    onRetry?: (row: {
+        attempt: number;
+        delayMs: number;
+        reason: string;
+    }) => void;
 }): Promise<WebFetchResult>;
 /** Content extraction: HTML stripped to text; JSON kept for the json
  *  preview branch; anything else passes through untouched. */
@@ -221,6 +307,9 @@ export declare function buildTmWebfetchTool(deps: {
     /** Shared URL cache (tm/index.ts owns the one instance so tm_search and
      *  tm_webfetch cannot drift into two stores of the same page). */
     cache?: WebCache;
+    /** Injectable sleep for the HTTP retry ladder (tests pin 5s/10s/20s without
+     *  waiting on it).  Omitted = real setTimeout. */
+    sleep?: (ms: number) => Promise<void>;
 }): {
     description: string;
     args: Record<string, unknown>;

package/dist/tm/webfetch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"webfetch.d.ts","sourceRoot":"","sources":["../../src/tm/webfetch.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"webfetch.d.ts","sourceRoot":"","sources":["../../src/tm/webfetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAGH,OAAO,EAAqF,KAAK,OAAO,EAAE,MAAM,eAAe,CAAA;AAC/H,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EAAoD,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAA;AAE7F;;;;;6EAK6E;AAC7E,eAAO,MAAM,iBAAiB,EAAE,SAAS,MAAM,EAAgD,CAAA;AAE/F,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAK1E;AAID,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAA;AACpE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAW1C;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,kBAAkB,wGACwE,CAAA;AAQvG,sEAAsE;AACtE,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAoBnF;AAED,MAAM,MAAM,UAAU,GAClB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,GAAG,CAAC;IAAC,GAAG,CAAC,EAAE,eAAe,GAAG,iBAAiB,GAAG,UAAU,CAAA;CAAE,GAC9E;IACE,EAAE,EAAE,KAAK,CAAA;IACT,OAAO,EAAE,MAAM,CAAA;IACf;;0BAEsB;IACtB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,GAAG,CAAC,EAAE,GAAG,CAAA;CACV,CAAA;AAEL,MAAM,MAAM,kBAAkB,GAAG,KAAK,GAAG,OAAO,GAAG,MAAM,CAAA;AAsBzD,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,kBAAkB,CAItE;AAKD,wBAAgB,kBAAkB,IAAI,kBAAkB,CAEvD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,UAAU,CAuFlF;AAID;4DAC4D;AAC5D,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAmB/C;AAQD;4EAC4E;AAC5E,eAAO,MAAM,cAAc,QAC4F,CAAA;AAWvH;;;;;;6DAM6D;AAC7D,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAoBlE;AAgBD;;;;0CAI0C;AAC1C,eAAO,MAAM,4BAA4B,EAAE,SAAS,MAAM,EAAkB,CAAA;AAK5E;2BAC2B;AAC3B,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAKjE;AAED,wBAAgB,kBAAkB,IAAI,MAAM,EAAE,CAE7C;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;IACX;0EACsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;gEAE4D;IAC5D,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AA4BD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,GAAG,SAAK,EACR,SAAS,GAAE,SAAS,MAAM,EAAyB,GAClD,SAAS,EAAE,CAwDb;AAED;;2DAE2D;AAC3D;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,GAAG,GAAE,IAAiB,GAAG,MAAM,CAM7D;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,MAAM,CASzF;AAID,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB;iFAC6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;yEAEqE;IACrE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CACnB;AAED,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;IACjF,EAAE,CAAC,EAAE,OAAO,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE;QAAE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;KAAE,CAAA;IAC7C,IAAI,CAAC,EAAE;QAAE,SAAS,IAAI,2BAA2B,CAAC,UAAU,CAAC,CAAA;KAAE,GAAG,IAAI,CAAA;IACtE,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,WAAW,CAAC,CAAA;IACxC,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;CAC7B,CAAC,CAAA;AAgCF;;;;;;;uDAOuD;AACvD,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,YAAY,SAAI,GAAG,MAAM,CAerE;AAID;;;4EAG4E;AAC5E,eAAO,MAAM,cAAc,IAAI,CAAA;AAE/B;;gFAEgF;AAChF,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAE7D;AAED;;;;;;8EAM8E;AAC9E,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAMzF;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;IAClB;uEACmE;IACnE,KAAK,EAAE,MAAM,CAAA;CACd;AAED;;;mFAGmF;AACnF,wBAAgB,mBAAmB,CAAC,GAAG,GAAE,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,GAAG,aAAa,CAAC,CAAM,GAAG,eAAe,CAQ/G;AAED;;;;;;gCAMgC;AAChC,wBAAgB,gBAAgB,CAAC,MAAM,GAAE,OAAO,CAAC,eAAe,CAAM,GAAG,eAAe,CAWvF;AAED;;;;;;yDAMyD;AACzD,wBAAgB,aAAa,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAKjE;AAED;gEACgE;AAChE,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAKrE;AAuCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,GAAG,EACR,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,IAAI,GAAE;IACJ,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB;;2CAEuC;IACvC,GAAG,CAAC,EAAE,OAAO,CAAA;IACb;mDAC+C;IAC/C,YAAY,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IAC1B;;oDAEgD;IAChD,KAAK,CAAC,EAAE,QAAQ,CAAA;IAChB;;;;;wCAKoC;IACpC,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;;;;;kEAK8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;gFAE4E;IAC5E,KAAK,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAA;IAChC,0EAA0E;IAC1E,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACrC;2EACuE;IACvE,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAA;CACzE,GACL,OAAO,CAAC,cAAc,CAAC,CA0JzB;AAED;8DAC8D;AAC9D,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAKtG;AAcD;;0DAE0D;AAC1D,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IACxC,SAAS,EAAE,WAAW,CAAA;IACtB,GAAG,EAAE,QAAQ,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC9B,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB;sEACkE;IAClE,KAAK,CAAC,EAAE,QAAQ,CAAA;IAChB;sDACkD;IAClD,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACtC,GAAG;IACF,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7B,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,UAAU,CAAC,CAAA;CACjF,CA2KA"}

package/dist/tm/webfetch.js

@@ -19,12 +19,17 @@
  *     allowlist (an allowlisted shortener cannot bounce off-site);
  *   - a URL naming an env file (isEnvFilePath) is refused — the R6 red
  *     line applies to remote spellings too;
- *   - response body capped at 2 MB, whole fetch under a hard 20 s timeout,
- *     HTML stripped to text before governance.
+ *   - response body capped at 2 MB, each request under a hard 20 s timeout,
+ *     HTML stripped to text before governance;
+ *   - a FAILED REQUEST (network throw, per-attempt timeout, HTTP 429/5xx) is
+ *     retried on the fixed 5s/10s/20s ladder (max 3 retries, same config the
+ *     provider-error governor reads) and the reply says when it was used —
+ *     a policy refusal (allowlist, red line, env-file, 403/418, other 4xx) is
+ *     never re-asked, because asking again earns the same verdict.
  */
 import { isEnvFilePath } from "../envprotect.js";
 import { askFnOf, askGrantNote, askRefusalNote, askUserForTarget, askUserForTargetDetailed } from "./perm-ask.js";
-import { shorten, DEFAULT_WEBFETCH_DOMAINS } from "./config.js";
+import { shorten, resolveConfig, DEFAULT_WEBFETCH_DOMAINS } from "./config.js";
 /** T4 (tm_search quality upgrade): the two new no-key engine hosts.
  *  DEFAULT_WEBFETCH_DOMAINS itself lives in config.ts (owned by the P0
  *  batch — NOT editable by this package), so the seed extension is applied
@@ -481,21 +486,155 @@ async function readBodyCapped(res, maxBytes) {
 /** A 429/503 that says WHEN, not just NO.  Only the delta-seconds spelling
  *  becomes a sentence: an HTTP-date would be laundered into a countdown the
  *  agent has no way to honor (there is no sleep in this toolset), and a wrong
- *  number is worse than no number. */
-export function retryAfterNote(raw) {
+ *  number is worse than no number.
+ *  `retriesTaken` keeps the advice consistent with what this tool just DID:
+ *  telling the agent "别对同一 URL 原地重试" while the reply carries our own
+ *  「重试3次」 is one sentence contradicting the other (review finding #4).
+ *  Either way the Retry-After number stays visible. */
+export function retryAfterNote(raw, retriesTaken = 0) {
     const v = String(raw ?? "").trim();
     if (!/^\d{1,6}$/.test(v))
         return "";
     const s = Number(v);
     if (!s)
         return "";
+    if (retriesTaken > 0) {
+        return (` · Retry-After: ${s} 秒——服务端建议等 ${s} 秒；本工具已按 5s/10s/20s 重试过 ${retriesTaken} 次仍被限流，` +
+            `别再原地重问，换别的来源（tm_search 其它引擎 / 直接源站）。`);
+    }
     return (` · Retry-After: ${s} 秒——这是"待会儿再来"，不是"这页没了"。` +
         `本轮先换别的来源（tm_search 其它引擎 / 直接源站），别对同一 URL 原地重试。`);
 }
+// ---------- HTTP-layer retry ladder (the fixed 5s / 10s / 20s) ----------
+/** Retries per request: attempt #1 waits 5s, #2 waits 10s, #3 waits 20s, then
+ *  the failure is reported.  Same ladder the provider-error governor promises,
+ *  derived from the SAME config (`retryBaseMs` doubling, no jitter), so the two
+ *  failure surfaces cannot drift into two different meanings of "retry". */
+export const HTTP_RETRY_MAX = 3;
+/** A transient HTTP failure worth asking again: 429 (rate limited) and any 5xx.
+ *  Everything else in the 4xx band is a VERDICT about this request — a retry
+ *  would earn the same bytes, and 403/418 carry their own browser directive. */
+export function isRetryableHttpStatus(status) {
+    return status === 429 || (status >= 500 && status <= 599);
+}
+/** Pure so a test can pin the ladder without sleeping: retry `attempt` (1-based)
+ *  waits `baseMs × 2^(attempt-1)` clamped to `maxMs`; attempt 0 or anything past
+ *  `HTTP_RETRY_MAX` waits nothing (0 = no further retry).  The clamp is what
+ *  makes the docs' promise true (review finding #3): with `retryBaseMs > 15000`
+ *  the un-clamped third rung (base×4) exceeded `retryMaxMs`, while the `retry`
+ *  key says BOTH surfaces share one capped ladder.  Defaults read from the
+ *  registry, so the shipped path stays exactly 5s/10s/20s (all under 60s). */
+export function httpRetryDelayMs(attempt, baseMs, maxMs) {
+    const a = Number.isFinite(attempt) ? Math.floor(attempt) : 0;
+    if (a < 1 || a > HTTP_RETRY_MAX)
+        return 0;
+    const base = Number.isFinite(baseMs) && baseMs > 0 ? baseMs : resolveConfig().retryBaseMs;
+    const max = Number.isFinite(maxMs) && maxMs > 0 ? maxMs : resolveConfig().retryMaxMs;
+    return Math.min(Math.round(base * Math.pow(2, a - 1)), max);
+}
+/** The registry is the one source of truth: `retry: "off"` disables the HTTP
+ *  retries as well as the governor's directive, and `retryBaseMs` sets the
+ *  first wait.  Callers holding a resolved `TmConfig` pass it in; a caller with
+ *  none (the search engine legs' inner helper, a PTC bridge) gets the defaults. */
+export function httpRetryFromConfig(cfg = {}) {
+    const base = resolveConfig();
+    return {
+        enabled: (cfg.retry ?? base.retry) !== "off",
+        baseMs: Number.isFinite(cfg.retryBaseMs) && cfg.retryBaseMs > 0 ? cfg.retryBaseMs : base.retryBaseMs,
+        maxRetries: HTTP_RETRY_MAX,
+        maxMs: base.retryMaxMs,
+    };
+}
+/** The same policy from an explicit per-call partial (what `fetchWebText`'s
+ *  `retry` option carries): every field falls back to the registry, never to a
+ *  guessed number, so a caller that passes `{}` retries exactly like the tool.
+ *  `maxRetries` is CLAMPED to HTTP_RETRY_MAX (review finding #5): the ladder has
+ *  three rungs, and `httpRetryDelayMs` answers 0 past them — an accepted 9 would
+ *  take six zero-delay "retries" the note renderers used to print as 「1s」, a
+ *  wait that never happened. */
+export function resolveHttpRetry(policy = {}) {
+    const base = resolveConfig();
+    return {
+        enabled: policy.enabled ?? base.retry !== "off",
+        baseMs: Number.isFinite(policy.baseMs) && policy.baseMs > 0 ? policy.baseMs : base.retryBaseMs,
+        maxRetries: Number.isFinite(policy.maxRetries) && policy.maxRetries >= 0
+            ? Math.min(Math.floor(policy.maxRetries), HTTP_RETRY_MAX)
+            : HTTP_RETRY_MAX,
+        maxMs: Number.isFinite(policy.maxMs) && policy.maxMs > 0 ? policy.maxMs : base.retryMaxMs,
+    };
+}
+/** Honest labelling (design goal #6): a page that arrived on the third try is
+ *  not the same fact as a page that arrived on the first, and a failure after
+ *  three tries says how long the caller waited for nothing.  Zero-delay entries
+ *  are filtered before rendering (review finding #5): a 0 is "the ladder was
+ *  already walked", and `Math.max(1, round(0/1000))` would print it as a 「1s」
+ *  wait that never happened.  With the maxRetries clamp these cannot reach the
+ *  list any more — this is the belt under the braces. */
+export function httpRetryNote(delaysMs) {
+    const ds = delaysMs.filter((d) => Number.isFinite(d) && d > 0);
+    if (!ds.length)
+        return "";
+    const waited = ds.map((d) => `${Math.max(1, Math.round(d / 1000))}s`).join("+");
+    return `（第${ds.length}次重试后成功 · 已等待${waited}）`;
+}
+/** The failure counterpart — how many times, at what waits, still no answer.
+ *  Zero-delay entries filtered for the same reason as above. */
+export function httpRetryFailNote(delaysMs) {
+    const ds = delaysMs.filter((d) => Number.isFinite(d) && d > 0);
+    if (!ds.length)
+        return "";
+    const ladder = ds.map((d) => `${Math.max(1, Math.round(d / 1000))}s`).join("/");
+    return `（重试${ds.length}次 · ${ladder} · 仍失败）`;
+}
+/** A POLICY verdict, not a failed request: allowlist/dialog refusal, 403/418,
+ *  a non-429 4xx, a redirect without a usable Location.  Never retried. */
+function fatalFetchError(message) {
+    const e = new Error(message);
+    e.retryable = false;
+    return e;
+}
+/** A status the caller may ask again about (429 / 5xx). */
+function transientFetchError(message) {
+    const e = new Error(message);
+    e.retryable = true;
+    return e;
+}
+const isFatalFetchError = (err) => err?.retryable === false;
+/** `AbortError` is a timeout, anything else that reached the catch without a
+ *  fatal tag is a network failure — the two shapes a retry can actually fix. */
+function retryReason(err) {
+    const e = err;
+    if (e?.name === "AbortError")
+        return "timeout";
+    return String(e?.name ?? e?.message ?? "error").slice(0, 40) || "network error";
+}
+/** Stamp the exhausted-ladder fact onto the error the caller will read, without
+ *  replacing it (an `AbortError` that lost its name would print as unknown). */
+function tagHttpRetryExhausted(err, delaysMs) {
+    const e = err;
+    if (!e)
+        return;
+    const note = httpRetryFailNote(delaysMs);
+    if (!note)
+        return;
+    e.retryNote = note;
+    e.message = `${String(e.message ?? "")}\n${note}`;
+}
 /**
  * Fetch a URL with hard timeout, byte cap, and MANUAL redirects — every
  * hop is re-checked against the allowlist before it is requested.
- * `fetchImpl` is injectable for tests (default: globalThis.fetch).
+ * `fetchImpl` is injectable for tests (default: globalThis.fetch), as is
+ * `sleep` (default: setTimeout) so the ladder can be pinned without waiting
+ * on it.
+ *
+ * HTTP retries: a failed request (network throw, per-attempt timeout, 429,
+ * 5xx) is retried up to `HTTP_RETRY_MAX` times with the fixed 5s/10s/20s
+ * ladder.  The timeout stays PER ATTEMPT, so the worst case for one URL is
+ * 4 × 20s of fetching plus 35s of waiting ≈ 115s — accepted deliberately:
+ * a transient failure that clears in 20s should not cost the caller a new
+ * round, and the reply says out loud when the ladder was used up.
+ * A policy refusal is never retried, and a retry re-requests THIS hop only —
+ * it never re-follows a redirect chain and never re-asks a dialog.
  */
 export async function fetchWebText(url, allowlist, opts = {}) {
     const doFetch = opts.fetchImpl ?? globalThis.fetch;
@@ -505,6 +644,23 @@ export async function fetchWebText(url, allowlist, opts = {}) {
     const timeoutMs = opts.timeoutMs ?? WEBFETCH_TIMEOUT_MS;
     const maxBytes = opts.maxBytes ?? WEBFETCH_MAX_BYTES;
     const accept = (opts.accept && opts.accept.trim()) || WEBFETCH_ACCEPT;
+    const retry = resolveHttpRetry(opts.retry ?? {});
+    const sleep = opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    // Retries actually taken in THIS call, in the order they were slept.  Both
+    // labels (success and exhausted) are rendered from this list, so the reply
+    // can only ever claim waiting for time this function actually spent.
+    const delays = [];
+    const takeRetry = async (attempt, reason) => {
+        const delayMs = httpRetryDelayMs(attempt + 1, retry.baseMs, retry.maxMs);
+        delays.push(delayMs);
+        try {
+            opts.onRetry?.({ attempt: attempt + 1, delayMs, reason });
+        }
+        catch {
+            /* the trajectory line is an extra, never a reason to fail the fetch */
+        }
+        await sleep(delayMs);
+    };
     let current = url;
     const approvedHosts = opts.skipAskHosts ?? new Set();
     // Every hop, in order.  Without this an allowlisted shortener that bounces
@@ -517,7 +673,7 @@ export async function fetchWebText(url, allowlist, opts = {}) {
         const seq = hopHosts.filter((h, i) => i === 0 || h !== hopHosts[i - 1]);
         return seq.length > 1 ? ` · 跳转链: ${seq.join(" → ")}（停在第 ${hopHosts.length} 跳）` : "";
     };
-    for (let hop = 0; hop <= WEBFETCH_MAX_REDIRECTS; hop++) {
+    hopLoop: for (let hop = 0; hop <= WEBFETCH_MAX_REDIRECTS; hop++) {
         hopHosts.push(current.hostname);
         // every hop re-checked — an allowlisted shortener cannot bounce off-site
         const verdict = checkWebUrl(current.toString(), allowlist);
@@ -549,53 +705,94 @@ export async function fetchWebText(url, allowlist, opts = {}) {
             if (hit)
                 return { text: hit.body, contentType: hit.contentType, finalUrl: current.toString(), cachedAt: hit.at };
         }
-        const ctrl = new AbortController();
-        const timer = setTimeout(() => ctrl.abort(), timeoutMs);
-        try {
-            const res = (await doFetch(current.toString(), {
-                redirect: "manual",
-                signal: ctrl.signal,
-                headers: {
-                    "user-agent": WEBFETCH_UA,
-                    accept,
-                    "accept-language": WEBFETCH_ACCEPT_LANGUAGE,
-                },
-            }));
-            if (REDIRECT_STATUSES.has(res.status)) {
-                const loc = res.headers.get("location");
-                if (!loc)
-                    throw new Error(`重定向 ${res.status} 缺少 Location 头${trail()}`);
-                current = new URL(loc, current);
-                continue;
+        // One attempt = ONE request for THIS hop.  A retry re-requests this same
+        // URL — it never re-follows the chain, never re-asks a dialog, and never
+        // reaches a hop whose allowlist / red-line verdict already refused (those
+        // throw above this loop, outside the retry's reach).
+        for (let attempt = 0;; attempt++) {
+            const ctrl = new AbortController();
+            const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+            try {
+                const res = (await doFetch(current.toString(), {
+                    redirect: "manual",
+                    signal: ctrl.signal,
+                    headers: {
+                        "user-agent": WEBFETCH_UA,
+                        accept,
+                        "accept-language": WEBFETCH_ACCEPT_LANGUAGE,
+                    },
+                }));
+                if (REDIRECT_STATUSES.has(res.status)) {
+                    const loc = res.headers.get("location");
+                    if (!loc)
+                        throw fatalFetchError(`重定向 ${res.status} 缺少 Location 头${trail()}`);
+                    // A malformed Location is a VERDICT about this response, not a failed
+                    // request — asking again earns the same broken header.  Without the
+                    // fatal tag (review finding #2) a TypeError from the URL parse looked
+                    // transient and burned the whole 35 s ladder on it.
+                    try {
+                        current = new URL(loc, current);
+                    }
+                    catch {
+                        throw fatalFetchError(`重定向 ${res.status} 的 Location 无法解析${trail()}`);
+                    }
+                    continue hopLoop;
+                }
+                // A 429/5xx with ladder left is a retry, not a result — the reporting
+                // code below only ever sees a response the caller has to be told about.
+                if (isRetryableHttpStatus(res.status) && retry.enabled && attempt < retry.maxRetries) {
+                    await takeRetry(attempt, `HTTP ${res.status}`);
+                    continue;
+                }
+                if (res.status === 403 || res.status === 418) {
+                    // Already sent real-Chrome UA + Accept headers and still rejected:
+                    // the gate is JS-challenge / TLS-fingerprint based — only a real
+                    // browser passes.  DIRECTIVE to the agent: use the host's native browser.
+                    const u = current.toString();
+                    const known = u.includes("baike.baidu.com")
+                        ? "（baike.baidu.com 是 JS 渲染 SPA）"
+                        : u.includes("zhihu.com")
+                            ? "（知乎对 fetch 一律 403）"
+                            : "";
+                    throw fatalFetchError(`HTTP ${res.status}${known}——伪装浏览器请求头后仍被拒，该站需要真实浏览器会话。` +
+                        `下一步：用宿主原生浏览器打开此 URL（browser_navigate → browser_snapshot）` +
+                        `（${shorten(u, 120)}）；或换 tm_search 引擎 / 找直接源站。${trail()}`);
+                }
+                if (res.status < 200 || res.status >= 300) {
+                    // 429/5xx exhausted their ladder → still a transient, and the note
+                    // says so.  Any other 4xx is a verdict on THIS request: no retry.
+                    throw (isRetryableHttpStatus(res.status) ? transientFetchError : fatalFetchError)(`HTTP ${res.status}（最终 URL: ${shorten(current.toString(), 120)}）${retryAfterNote(res.headers.get("retry-after"), delays.length)}${trail()}`);
+                }
+                const contentType = (res.headers.get("content-type") ?? "text/plain").toLowerCase();
+                const raw = await readBodyCapped(res, maxBytes);
+                // Store the RAW body (pre-extraction) under the SAME static-allowlist
+                // condition; a 2xx-only rule keeps an error page from outliving itself
+                // as "the content of that URL".
+                if (staticAllow && opts.cache?.enabled())
+                    opts.cache.put(current.toString(), { status: res.status, contentType, body: raw });
+                return {
+                    text: raw,
+                    contentType,
+                    finalUrl: current.toString(),
+                    ...(delays.length ? { retries: [...delays] } : {}),
+                };
             }
-            if (res.status === 403 || res.status === 418) {
-                // Already sent real-Chrome UA + Accept headers and still rejected:
-                // the gate is JS-challenge / TLS-fingerprint based — only a real
-                // browser passes.  DIRECTIVE to the agent: use the host's native browser.
-                const u = current.toString();
-                const known = u.includes("baike.baidu.com")
-                    ? "（baike.baidu.com 是 JS 渲染 SPA）"
-                    : u.includes("zhihu.com")
-                        ? "（知乎对 fetch 一律 403）"
-                        : "";
-                throw new Error(`HTTP ${res.status}${known}——伪装浏览器请求头后仍被拒，该站需要真实浏览器会话。` +
-                    `下一步：用宿主原生浏览器打开此 URL（browser_navigate → browser_snapshot）` +
-                    `（${shorten(u, 120)}）；或换 tm_search 引擎 / 找直接源站。${trail()}`);
+            catch (err) {
+                // Only a FAILED REQUEST retries here.  An error carrying a policy
+                // verdict is tagged fatal (allowlist refusal, 403/418, a non-429 4xx,
+                // a redirect without a usable Location) and leaves immediately; a bare
+                // throw from fetch/body-read is a network error or a timeout abort,
+                // which is exactly what asking again can fix.
+                if (retry.enabled && attempt < retry.maxRetries && !isFatalFetchError(err)) {
+                    await takeRetry(attempt, retryReason(err));
+                    continue;
+                }
+                tagHttpRetryExhausted(err, delays);
+                throw err;
             }
-            if (res.status < 200 || res.status >= 300) {
-                throw new Error(`HTTP ${res.status}（最终 URL: ${shorten(current.toString(), 120)}）${retryAfterNote(res.headers.get("retry-after"))}${trail()}`);
+            finally {
+                clearTimeout(timer);
             }
-            const contentType = (res.headers.get("content-type") ?? "text/plain").toLowerCase();
-            const raw = await readBodyCapped(res, maxBytes);
-            // Store the RAW body (pre-extraction) under the SAME static-allowlist
-            // condition; a 2xx-only rule keeps an error page from outliving itself
-            // as "the content of that URL".
-            if (staticAllow && opts.cache?.enabled())
-                opts.cache.put(current.toString(), { status: res.status, contentType, body: raw });
-            return { text: raw, contentType, finalUrl: current.toString() };
-        }
-        finally {
-            clearTimeout(timer);
         }
     }
     throw new Error(`重定向超过 ${WEBFETCH_MAX_REDIRECTS} 跳，放弃抓取`);
@@ -609,13 +806,15 @@ export function extractWebResponse(raw, contentType) {
     return { text: raw, isHtml: false };
 }
 // ---------- tool definition ----------
-const WEBFETCH_DESCRIPTION = `Fetch a web page through the governed pipeline (domain allowlist + threshold offload) — use it for a KNOWN URL only.  For open-ended lookups use tm_search FIRST (multi-engine, extracted hit lists); never hand-build search URLs here.
-
-- ANTI-PATTERN: do NOT hand-build search-engine URLs here — that is tm_search's job (multi-engine, extracted hit lists).  Use THIS tool for a page you already know: a direct article/wiki term, a registry JSON endpoint, a raw file.
-- Seeded hosts (CN-reachable, no API keys): moegirl.org.cn (parent — all subdomains: mobile. term https://mobile.moegirl.org.cn/TERM, mzh. main site) · search.bilibili.com · cn.bing.com (search: https://cn.bing.com/search?q=QUERY; &ensearch=1 for international results) · baidu.com (parent: www. search /s?wd=QUERY, baike. encyclopedia entries) · www.sogou.com (https://www.sogou.com/web?query=QUERY) · www.so.com (https://www.so.com/s?q=QUERY) · registry.npmjs.org (package JSON: https://registry.npmjs.org/<pkg>/latest, search: https://registry.npmjs.org/-/v1/search?text=QUERY) · api.github.com (repo search: https://api.github.com/search/repositories?q=QUERY) · api.stackexchange.com (question search: https://api.stackexchange.com/2.3/search/advanced?order=desc&sort=relevance&q=QUERY&site=stackoverflow&pagesize=10) · hn.algolia.com (HN story search: https://hn.algolia.com/api/v1/search?query=QUERY&tags=story) · raw.githubusercontent.com + gist.githubusercontent.com + github.com (docs/code/issues) · ghproxy.net (mainland mirror for github raw).  URL-encode the query (CJK terms too).  Search-engine result pages are auto-extracted to a title+URL hit list.  Expand colloquial/abbreviated terms to canonical forms and fetch BOTH spellings.
-- Governance: only http(s), hosts must be allowlisted (extend via webfetchAllowedDomains, "*" opens all), redirects re-checked per hop (a refusal names the whole hop chain), HTML stripped to text — some documentation hosts (learn.microsoft.com measured 5.3x smaller) are fetched as Markdown when they honour accept: text/markdown, and the reply says so; output above offloadThreshold tokens is offloaded to a handle — page with tm_fetch (try mode:"structure" first).
-- Governance: out-of-allowlist hosts route through the OFFICIAL confirmation dialog (approve to proceed once; the 1-min unanswered auto-reject applies); env-file URLs and non-http(s) schemes are hard-rejected with no dialog.
-- Freshness: a repeated URL is served from a local TTL cache (webCacheTtlSec, default 300 s) and the reply SAYS 缓存命中 with its age.  Need the page as it is NOW?  Pass { fresh: true } to bypass the cache and hit the network.`;
+const WEBFETCH_DESCRIPTION = `Fetch a web page through the governed pipeline (domain allowlist + threshold offload) — use it for a KNOWN URL only.  For open-ended lookups use tm_search FIRST (multi-engine, extracted hit lists); never hand-build search URLs here.
+
+- ANTI-PATTERN: do NOT hand-build search-engine URLs here — that is tm_search's job (multi-engine, extracted hit lists).  Use THIS tool for a page you already know: a direct article/wiki term, a registry JSON endpoint, a raw file.
+- Seeded hosts (CN-reachable, no API keys): moegirl.org.cn (parent — all subdomains: mobile. term https://mobile.moegirl.org.cn/TERM, mzh. main site) · search.bilibili.com · cn.bing.com (search: https://cn.bing.com/search?q=QUERY; &ensearch=1 for international results) · baidu.com (parent: www. search /s?wd=QUERY, baike. encyclopedia entries) · www.sogou.com (https://www.sogou.com/web?query=QUERY) · www.so.com (https://www.so.com/s?q=QUERY) · registry.npmjs.org (package JSON: https://registry.npmjs.org/<pkg>/latest, search: https://registry.npmjs.org/-/v1/search?text=QUERY) · api.github.com (repo search: https://api.github.com/search/repositories?q=QUERY) · api.stackexchange.com (question search: https://api.stackexchange.com/2.3/search/advanced?order=desc&sort=relevance&q=QUERY&site=stackoverflow&pagesize=10) · hn.algolia.com (HN story search: https://hn.algolia.com/api/v1/search?query=QUERY&tags=story) · raw.githubusercontent.com + gist.githubusercontent.com + github.com (docs/code/issues) · ghproxy.net (mainland mirror for github raw).  URL-encode the query (CJK terms too).  Search-engine result pages are auto-extracted to a title+URL hit list.  Expand colloquial/abbreviated terms to canonical forms and fetch BOTH spellings.
+- Governance: only http(s), hosts must be allowlisted (extend via webfetchAllowedDomains, "*" opens all), redirects re-checked per hop (a refusal names the whole hop chain), HTML stripped to text — some documentation hosts (learn.microsoft.com measured 5.3x smaller) are fetched as Markdown when they honour accept: text/markdown, and the reply says so; output above offloadThreshold tokens is offloaded to a handle — page with tm_fetch (try mode:"structure" first).
+- Governance: out-of-allowlist hosts route through the OFFICIAL confirmation dialog (approve to proceed once; the 1-min unanswered auto-reject applies); env-file URLs and non-http(s) schemes are hard-rejected with no dialog.
+- Freshness: a repeated URL is served from a local TTL cache (webCacheTtlSec, default 300 s) and the reply SAYS 缓存命中 with its age.  Need the page as it is NOW?  Pass { fresh: true } to bypass the cache and hit the network.
+- Transient failures: a network throw, a per-request 20 s timeout, an HTTP 429 or 5xx is retried up to 3 times on the fixed 5s/10s/20s ladder and the reply labels it (第N次重试后成功 / 重试3次…仍失败).  A refusal (off-allowlist, red line, env-file URL, 403/418, other 4xx) is NOT retried — it is a verdict, so change source instead of re-asking.  Set retry: "off" to disable both.
+`;
 /** Build the tm_webfetch ToolDefinition over the SHARED main pipelines
  *  instance (same step counter as tm_read/tm_grep/tm_bash — refs stay
  *  unambiguous).  `fetchImpl` is injectable for tests. */
@@ -674,7 +873,23 @@ export function buildTmWebfetchTool(deps) {
                     // learn.microsoft.com, no-op elsewhere); the engine legs never come
                     // through here, so their calibrated browser-shaped header stands.
                     accept: WEBFETCH_ACCEPT_MD,
+                    // The fixed HTTP ladder (5s/10s/20s) with the registry's own knobs, and
+                    // one trajectory row per retry actually taken — so "重试3次" in the
+                    // reply is falsifiable in steps.jsonl, not just asserted.
+                    retry: httpRetryFromConfig(cfg),
+                    sleep: deps.sleep,
+                    onRetry: (row) => pipelines.store.appendTrajectory({
+                        tool,
+                        step_id: stepId,
+                        event: "http_retry",
+                        attempt: row.attempt,
+                        delay_ms: row.delayMs,
+                        reason: row.reason,
+                    }),
                 });
+                // A page that arrived on the second or third try is not the same fact as
+                // one that arrived on the first — the wait is stated, not hidden.
+                const retryNote = httpRetryNote(res.retries ?? []);
                 // A re-served page is stated as such — an agent that believes a cache
                 // hit is a fresh observation propagates a stale fact into the plan.
                 let cacheNote = "";
@@ -692,7 +907,7 @@ export function buildTmWebfetchTool(deps) {
                     if (hits.length > 0) {
                         const sp = (verdict.ok ? verdict.url : new URL(requested)).searchParams;
                         const query = sp.get("q") ?? sp.get("wd") ?? sp.get("query") ?? sp.get("keyword") ?? "";
-                        const listing = renderSearchHits(query || res.finalUrl, "webfetch", hits) + cacheNote + grantNote;
+                        const listing = renderSearchHits(query || res.finalUrl, "webfetch", hits) + retryNote + cacheNote + grantNote;
                         return toToolResult(pipelines.govern(stepId, tool, listing, {
                             contentType: detectContentType(listing),
                             clue: `search url=${shorten(res.finalUrl, 120)}`,
@@ -708,8 +923,11 @@ export function buildTmWebfetchTool(deps) {
                     : "";
                 if (!text.trim()) {
                     // anti-bot / JS-rendered pages (baidu is the usual offender) return
-                    // an empty shell — tell the agent instead of storing nothing
-                    return toToolResult(tmError(tool, "execute", "页面内容为空——该站点可能是反爬或 JS 渲染页（baidu 常见）。换 tm_search 的其他引擎（bing/stackoverflow/hn）、用宿主原生浏览器打开，或直接访问数据源 URL（如 registry.npmjs.org/<pkg>/latest）。"));
+                    // an empty shell — tell the agent instead of storing nothing.  When
+                    // the shell only arrived after walking the ladder, that wait is part
+                    // of the fact too (review finding #6) — an empty page that cost 35 s
+                    // is not the same experience as one that answered instantly.
+                    return toToolResult(tmError(tool, "execute", "页面内容为空——该站点可能是反爬或 JS 渲染页（baidu 常见）。换 tm_search 的其他引擎（bing/stackoverflow/hn）、用宿主原生浏览器打开，或直接访问数据源 URL（如 registry.npmjs.org/<pkg>/latest）。" + retryNote));
                 }
                 const contentType = detectContentType(text);
                 // Wave B M2 — `fields` dot-path projection on a JSON response body.
@@ -732,13 +950,13 @@ export function buildTmWebfetchTool(deps) {
                             "--- 投影 ---",
                         ].join("\n");
                         const projected = proj.values.length ? `${head}\n${proj.values.join("\n")}` : head;
-                        return toToolResult(pipelines.govern(stepId, tool, projected, {
+                        return toToolResult(pipelines.govern(stepId, tool, `${projected}${retryNote}`, {
                             contentType: "text",
                             clue: `url=${shorten(res.finalUrl, 120)} fields=${shorten(fields, 60)}`,
                         }));
                     }
                 }
-                return toToolResult(pipelines.govern(stepId, tool, text + cacheNote + mdNote + grantNote, {
+                return toToolResult(pipelines.govern(stepId, tool, text + retryNote + cacheNote + mdNote + grantNote, {
                     contentType,
                     clue: `url=${shorten(res.finalUrl, 120)}`,
                 }));
@@ -746,7 +964,10 @@ export function buildTmWebfetchTool(deps) {
             catch (err) {
                 const e = err;
                 if (e?.name === "AbortError") {
-                    return toToolResult(tmError(tool, "execute", "抓取超时（20s）——换更具体的搜索词或稍后重试"));
+                    // A timeout that used up the ladder says so — the per-attempt 20s is
+                    // not the whole story of how long this call took.
+                    const exhausted = typeof e?.retryNote === "string" ? e.retryNote : "";
+                    return toToolResult(tmError(tool, "execute", "抓取超时（每次请求 20s）——换更具体的搜索词或稍后重试" + exhausted));
                 }
                 return toToolResult(tmError(tool, "execute", String(e?.message ?? err ?? "webfetch 失败")));
             }