instar 1.3.252 → 1.3.254

package/dist/tunnel/CloudflareQuickProvider.d.ts

@@ -32,6 +32,15 @@ export interface CloudflareQuickProviderOptions {
     /** Start timeout in milliseconds (default: 30_000). */
     startTimeoutMs?: number;
 }
+/**
+ * Classify a cloudflared quick-tunnel failure into a fixed-substring reason the
+ * TunnelManager parses to a ProviderFailureReason. Pure + exported so the
+ * decision boundary (esp. the Cloudflare 429/1015 rate-limit detection) is
+ * unit-testable. Depends on the caller having captured cloudflared's real stderr
+ * (the 'stderr' event) into `stderr` — otherwise the rate-limit text never
+ * reaches the haystack and the classification falls through to generic.
+ */
+export declare function classifyQuickTunnelError(msg: string, stderr: string): Error;
 export declare class CloudflareQuickProvider implements TunnelProvider {
     readonly name: ProviderName;
     readonly tier: ProviderTier;

package/dist/tunnel/CloudflareQuickProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CloudflareQuickProvider.d.ts","sourceRoot":"","sources":["../../src/tunnel/CloudflareQuickProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAKH,OAAO,KAAK,EACV,cAAc,EACd,oBAAoB,EACpB,YAAY,EACZ,YAAY,EACb,MAAM,qBAAqB,CAAC;AAE7B,MAAM,WAAW,8BAA8B;IAC7C,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,qBAAa,uBAAwB,YAAW,cAAc;IAC5D,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAsB;IACjD,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAK;IAEhC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;gBAE5B,IAAI,EAAE,8BAA8B;IAM1C,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAQrC,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;YASzC,UAAU;IA6FxB,OAAO,CAAC,aAAa;YAiBP,UAAU;CAmCzB"}
+{"version":3,"file":"CloudflareQuickProvider.d.ts","sourceRoot":"","sources":["../../src/tunnel/CloudflareQuickProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAKH,OAAO,KAAK,EACV,cAAc,EACd,oBAAoB,EACpB,YAAY,EACZ,YAAY,EACb,MAAM,qBAAqB,CAAC;AAE7B,MAAM,WAAW,8BAA8B;IAC7C,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,KAAK,CAc3E;AAED,qBAAa,uBAAwB,YAAW,cAAc;IAC5D,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAsB;IACjD,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAK;IAEhC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;gBAE5B,IAAI,EAAE,8BAA8B;IAM1C,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAQrC,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;YASzC,UAAU;IAwGxB,OAAO,CAAC,aAAa;YAIP,UAAU;CAmCzB"}

package/dist/tunnel/CloudflareQuickProvider.js

@@ -26,6 +26,29 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { bin, install, Tunnel } from 'cloudflared';
+/**
+ * Classify a cloudflared quick-tunnel failure into a fixed-substring reason the
+ * TunnelManager parses to a ProviderFailureReason. Pure + exported so the
+ * decision boundary (esp. the Cloudflare 429/1015 rate-limit detection) is
+ * unit-testable. Depends on the caller having captured cloudflared's real stderr
+ * (the 'stderr' event) into `stderr` — otherwise the rate-limit text never
+ * reaches the haystack and the classification falls through to generic.
+ */
+export function classifyQuickTunnelError(msg, stderr) {
+    const haystack = `${msg} ${stderr}`.toLowerCase();
+    // Cloudflare's quick-tunnel rate-limit surfaces as 429 / error 1015.
+    if (haystack.includes('429') || haystack.includes('1015') || haystack.includes('rate limit') || haystack.includes('too many requests')) {
+        return new Error(`rate-limited: cloudflared quick-tunnel rate-limited (${msg})`);
+    }
+    if (haystack.includes('enoent') || haystack.includes('not found') || haystack.includes('binary-missing')) {
+        return new Error(`binary-missing: ${msg}`);
+    }
+    if (haystack.includes('dns') || haystack.includes('eai_again') || haystack.includes('econnrefused') || haystack.includes('network')) {
+        return new Error(`network: ${msg}`);
+    }
+    // Preserve as-is so the manager's classifier sees the original prefix.
+    return new Error(msg);
+}
 export class CloudflareQuickProvider {
     name = 'cloudflare-quick';
     tier = 1;
@@ -100,6 +123,16 @@ export class CloudflareQuickProvider {
                 reject(new Error('timeout: cloudflared quick tunnel did not emit a URL within the start budget'));
             }
         }, this.startTimeoutMs);
+        // Capture cloudflared's REAL stderr. The `cloudflared` wrapper emits a
+        // 'stderr' event per child stderr line (incl. the "429 Too Many Requests /
+        // error code 1015" rate-limit line). Without listening here, stderrTail
+        // stayed empty → 'exit' logged "no stderr captured" → classifyError's
+        // 429/1015 detection was DEAD for the exit path, so the manager could never
+        // recognize (or back off on) a Cloudflare rate-limit. (Found live 2026-05-31:
+        // a quick tunnel 429'd but surfaced only as opaque "process-exit code 1".)
+        tunnel.on('stderr', (data) => {
+            stderrTail = (stderrTail + ' ' + data).slice(-2000);
+        });
         tunnel.once('url', (url) => {
             if (resolved)
                 return;
@@ -140,20 +173,7 @@ export class CloudflareQuickProvider {
         void urlEmitted;
     }
     classifyError(msg, stderr) {
-        const haystack = `${msg} ${stderr}`.toLowerCase();
-        // Cloudflare's quick-tunnel rate-limit surfaces as 429 / error 1015.
-        // Both substrings appear in cloudflared's stderr on rate-limit.
-        if (haystack.includes('429') || haystack.includes('1015') || haystack.includes('rate limit') || haystack.includes('too many requests')) {
-            return new Error(`rate-limited: cloudflared quick-tunnel rate-limited (${msg})`);
-        }
-        if (haystack.includes('enoent') || haystack.includes('not found') || haystack.includes('binary-missing')) {
-            return new Error(`binary-missing: ${msg}`);
-        }
-        if (haystack.includes('dns') || haystack.includes('eai_again') || haystack.includes('econnrefused') || haystack.includes('network')) {
-            return new Error(`network: ${msg}`);
-        }
-        // Preserve as-is so the manager's classifier sees the original prefix.
-        return new Error(msg);
+        return classifyQuickTunnelError(msg, stderr);
     }
     async stopHandle(tunnel) {
         // Force-stop with PID escalation, mirroring TunnelManager.forceStop's

package/dist/tunnel/CloudflareQuickProvider.js.map

@@ -1 +1 @@
-{"version":3,"file":"CloudflareQuickProvider.js","sourceRoot":"","sources":["../../src/tunnel/CloudflareQuickProvider.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"CloudflareQuickProvider.js","sourceRoot":"","sources":["../../src/tunnel/CloudflareQuickProvider.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.252",
+  "version": "1.3.254",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/scripts/assemble-next-md.mjs

@@ -83,6 +83,22 @@ export function parseBumpType(content) {
   return match ? match[1].toLowerCase() : null;
 }
 
+/**
+ * Does this fragment opt into the internal-only ship lane via an
+ * `<!-- internal-only -->` marker? Such a fragment has no user-facing surface,
+ * so it may omit the "What to Tell Your User" / "Summary of New Capabilities"
+ * sections — the assembler auto-fills them ONLY when EVERY contributing fragment
+ * is internal-only (see assembleNextMd). The pre-push gate independently verifies
+ * the marker against the staged diff (an internal-only fragment whose PR touches
+ * runtime `src/` is rejected), so the marker cannot be misused.
+ */
+export function hasInternalOnlyMarker(content) {
+  return /<!--\s*internal-only\s*-->/i.test(String(content));
+}
+
+/** Canonical text auto-filled into the user-facing sections of an all-internal release. */
+export const INTERNAL_ONLY_FILL = 'None — internal change (no user-facing surface).';
+
 /**
  * Split a fragment body into H2 sections: [{ title, body }] in source order.
  * `body` excludes the heading line itself and is right-trimmed.
@@ -140,9 +156,15 @@ export function assembleNextMd(fragments) {
   const extraOrder = [];
   let maxBumpRank = 0;
   let sawAnyBump = false;
+  // The internal-only lane auto-fills the user-facing sections ONLY when every
+  // contributing fragment opts in. Starts true for a non-empty input set and is
+  // cleared by the first fragment WITHOUT an <!-- internal-only --> marker, so a
+  // single user-facing fragment keeps the full user-section requirement.
+  let allInternal = effective.length > 0;
 
   for (const frag of effective) {
     const content = frag.content ?? '';
+    if (!hasInternalOnlyMarker(content)) allInternal = false;
     const bump = parseBumpType(content);
     if (bump) {
       sawAnyBump = true;
@@ -183,6 +205,20 @@ export function assembleNextMd(fragments) {
     );
   }
 
+  // Internal-only lane: when EVERY contributing fragment is marked
+  // <!-- internal-only -->, the change has no user-facing surface, so the two
+  // user-facing sections are auto-filled rather than hand-written. This keeps the
+  // shared validator (pre-push AND publish) satisfied without forcing
+  // "None — internal" boilerplate by hand. We auto-fill ONLY missing sections, so
+  // an internal fragment that DOES say something user-facing is preserved as-is;
+  // and because `allInternal` is false whenever any fragment lacks the marker, a
+  // genuinely user-facing change that omits these sections still fails validation.
+  if (allInternal) {
+    for (const title of ['What to Tell Your User', 'Summary of New Capabilities']) {
+      if (!merged.has(title)) merged.set(title, [INTERNAL_ONLY_FILL]);
+    }
+  }
+
   // Emit canonical sections first (only when present), then extras in
   // first-seen order.
   const titleOrder = [

package/scripts/pre-push-gate.js

@@ -14,7 +14,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { validateGuideContent } from './upgrade-guide-validator.mjs';
-import { assembleNextMd, gatherFragmentInputs } from './assemble-next-md.mjs';
+import { assembleNextMd, gatherFragmentInputs, hasInternalOnlyMarker } from './assemble-next-md.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(__dirname, '..');
@@ -186,6 +186,29 @@ try {
     );
   }
 
+  // ── 3c. Internal-only lane verification (objective gate) ──────────────
+  // A release fragment marked <!-- internal-only --> may omit the user-facing
+  // sections — the assembler auto-fills "None — internal" for an all-internal
+  // release. That is ONLY valid for changes with no shipped runtime surface.
+  // Verify against the diff: if any staged internal-only fragment accompanies a
+  // runtime src/ change, REJECT — a user-facing change must not skip
+  // "What to Tell Your User" / "Summary of New Capabilities". This is the
+  // objective gate that keeps the marker from being misused (the agent sets it,
+  // the diff verifies it). tests/docs/scripts-only changes are fine.
+  const internalOnlyFragments = fragmentChanges.filter(f => {
+    try { return hasInternalOnlyMarker(fs.readFileSync(path.join(ROOT, f), 'utf-8')); }
+    catch { return false; }
+  });
+  if (internalOnlyFragments.length > 0 && srcChanges.length > 0) {
+    errors.push(
+      `Internal-only release fragment(s) accompany ${srcChanges.length} runtime src/ change(s):\n` +
+      internalOnlyFragments.slice(0, 5).map(f => `      • ${f} (marked <!-- internal-only -->)`).join('\n') + '\n' +
+      `      The internal-only lane (which auto-fills the user-facing release sections) is ONLY for changes ` +
+      `with no shipped runtime surface (tests / docs / scripts). Either remove the marker and write the ` +
+      `"What to Tell Your User" + "Summary of New Capabilities" sections, or split the src/ change into its own PR.`
+    );
+  }
+
   // ── 4. Adapter contract test gate ─────────────────────────────────────
   // If messaging adapter source files changed, require contract test evidence.
   // This prevents shipping integration code verified only by mocked unit tests.

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-04T23:01:14.429Z",
-  "instarVersion": "1.3.252",
+  "generatedAt": "2026-06-04T23:23:29.388Z",
+  "instarVersion": "1.3.254",
   "entryCount": 198,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.253.md

@@ -0,0 +1,39 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Added an internal-only release-note lane to the instar-dev ship gate. A release-note
+fragment that has no user-facing surface (test-only, docs-only, or build/CI scripts
+with no `src/` runtime change) can now carry an `<!-- internal-only -->` marker and
+OMIT the two user-facing sections ("What to Tell Your User", "Summary of New
+Capabilities"). The shared assembler (`scripts/assemble-next-md.mjs`) auto-fills those
+sections with "None — internal change (no user-facing surface)." — but ONLY when every
+fragment in the release is internal-only, so a real user-facing change can never skip
+telling the user.
+
+The marker is verified objectively: `scripts/pre-push-gate.js` rejects an
+`<!-- internal-only -->` fragment whose diff touches a runtime `src/` file. The
+side-effects review and decision-trace are unchanged — only the user-facing release
+boilerplate is lifted, and only for changes that provably have no user-facing surface.
+
+This very fragment uses the new lane (this PR is scripts + tests only), dogfooding it.
+
+## What to Tell Your User
+
+None — internal change (no user-facing surface).
+
+## Summary of New Capabilities
+
+None — internal change (no user-facing surface).
+
+## Evidence
+
+- 45 tests green across `tests/unit/assemble-next-md.test.ts` (auto-fill on all-internal,
+  validator passes the auto-filled guide, real content preserved when any fragment is
+  user-facing, marker detection, self-... ) and `tests/unit/pre-push-gate.test.ts` (the
+  objective §3c marker-vs-diff gate). `node --check scripts/pre-push-gate.js` clean.
+- The auto-fill lives in the assembler shared by BOTH the pre-push gate and the publish
+  gate (`check-upgrade-guide.js`), so the two can never disagree about a release note.

package/upgrades/1.3.254.md

@@ -0,0 +1,42 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+**Quick tunnels now correctly recognize when Cloudflare is rate-limiting them.**
+When the zero-config quick tunnel failed because Cloudflare's free tunnel service
+returned "429 Too Many Requests", instar only saw an opaque "process exited" with
+no detail — it couldn't tell a rate-limit apart from any other failure, so it
+couldn't react appropriately. The provider now captures cloudflared's real error
+output, so a rate-limit is identified as exactly that and handed to the tunnel
+manager's failure handling with the right reason.
+
+## What to Tell Your User
+
+Nothing to configure. If your quick tunnel ever gets rate-limited by Cloudflare,
+instar now recognizes it as a rate-limit (instead of a generic failure), which
+lets it respond more sensibly under that degraded condition. Named tunnels and
+the healthy path are unaffected.
+
+## Summary of New Capabilities
+
+- `classifyQuickTunnelError(msg, stderr)` — pure, exported, unit-tested
+  classifier mapping a cloudflared failure to a fixed reason
+  (rate-limited / binary-missing / network / passthrough).
+- `CloudflareQuickProvider` now listens to the cloudflared wrapper's `stderr`
+  event, so the rate-limit text actually reaches the classifier (it never did
+  before, which made the 429 detection dead on the process-exit path).
+
+## Evidence
+
+- Found live (2026-05-31): a quick tunnel hit Cloudflare 429, but instar
+  surfaced only "process-exit code 1: no stderr captured"; the 429 was visible
+  only by running cloudflared directly.
+- Tests: `tests/unit/CloudflareQuickProvider.test.ts` (6) — the classifier
+  across all reason branches, plus a mock-cloudflared test proving the new
+  stderr listener feeds a 429 line into the classifier so start() rejects with
+  rate-limited. `tsc --noEmit` clean.
+- Spec: tunnel-failure-resilience (the manager's single-owner failure handling
+  this classification feeds).

package/upgrades/side-effects/internal-only-ship-lane.md

@@ -0,0 +1,77 @@
+# Side-Effects Review — internal-only release-note lane (mechanism)
+
+**Version / slug:** `internal-only-ship-lane`
+**Date:** `2026-06-04`
+**Author:** `echo`
+**Second-pass reviewer:** `required (release-critical CI machinery)`
+
+## Summary of the change
+
+Every release-note fragment currently must carry all four sections — including the
+two user-facing ones (**What to Tell Your User**, **Summary of New Capabilities**).
+For a change with NO user-facing surface (test-only, docs-only, build/CI scripts with
+no `src/` runtime change) that copy is pure boilerplate ("None — internal"), which is
+disproportionate ceremony (the codex-#25 friction; the #758 telegraph test-flake fix
+had to hand-write two "None — internal" sections).
+
+This adds an **internal-only lane** (operator-approved). A fragment opts in with an
+`<!-- internal-only -->` marker and may OMIT the two user-facing sections. The
+assembler auto-fills them with a canonical "None — internal change…" ONLY when
+*every* contributing fragment is internal-only. The objective gate: the pre-push gate
+verifies the marker against the diff — an internal-only fragment whose change touches
+runtime `src/` is REJECTED. Side-effects review + decision-trace are unchanged — safety
+and auditability never get a lighter lane.
+
+This PR is the **mechanism** (assembler + pre-push verification + tests). The
+deployed-skill documentation (`skills/instar-dev/SKILL.md` + a PostUpdateMigrator
+migration to redeploy it) is a tracked follow-up.
+
+## Decision-point inventory
+
+1. **assembler auto-fill** (`assembleNextMd`): when `allInternal` (every fragment
+   marked) and a user-facing canonical section is missing from the merged map, inject
+   `INTERNAL_ONLY_FILL`. Never auto-fills when any fragment is non-internal.
+2. **pre-push verification** (`pre-push-gate.js` §3c): an internal-only fragment +
+   any `src/*.ts` change in the diff → error.
+
+## 1. Over-block (what still fails / is required)
+
+- A genuinely user-facing change that OMITS the user sections still fails: it is not
+  `allInternal` (it has no marker, or the gate rejects the marker on a `src/` diff), so
+  the assembler does NOT auto-fill, and `validateGuideContent` reports the missing
+  sections. (test: "does NOT auto-fill when any fragment is user-facing".)
+- `What Changed` + `Evidence` are still required; the Evidence-bar (fix-claim →
+  Evidence) is untouched.
+- All existing fragment validations (inline-code / camelCase / fenced-block leakage,
+  malformed fragment, bump tier) are unchanged — 25 pre-existing assembler tests +
+  the full pre-push suite stay green.
+
+## 2. Under-block (what it now allows)
+
+- An all-internal release may omit the two user-facing sections; the assembler fills
+  them. This is gated objectively: the marker is verified against the diff at pre-push,
+  so it cannot be set on a runtime `src/` change to hide user-facing impact. The agent
+  sets the marker; the diff verifies it. (test: source-presence of the §3c gate +
+  `hasInternalOnlyMarker`.)
+- Worst case of a wrong marker on a non-src change (e.g. a scripts change that DOES have
+  user impact): the publish notes say "None — internal" for that release. Bounded and
+  low-harm — scripts/docs/test changes have no agent-user runtime surface by
+  construction.
+
+## 3. Blast radius
+
+- `scripts/assemble-next-md.mjs` — pure function; new `hasInternalOnlyMarker` +
+  `INTERNAL_ONLY_FILL` exports + the auto-fill branch.
+- `scripts/pre-push-gate.js` — one new §3c check (reuses existing `srcChanges` /
+  `fragmentChanges`).
+- Tests only otherwise. NO `src/` change, no runtime/agent surface. The assembler is
+  shared by BOTH the pre-push gate and the publish gate (`check-upgrade-guide.js`), so
+  the auto-fill keeps both consistent — the change was deliberately placed in the shared
+  assembler so the two gates can never disagree.
+
+## 4. Reversibility
+
+Fully reversible: revert the two scripts + test edits. No state, no persisted format
+(the `<!-- internal-only -->` marker is just a fragment comment — a fragment without it
+behaves exactly as before). Verified: 45 tests green (assemble-next-md + pre-push-gate
+suites), `node --check` clean on the gate.

package/upgrades/side-effects/quick-tunnel-stderr-capture.md

@@ -0,0 +1,63 @@
+# Side effects — quick-tunnel captures cloudflared stderr (429 detection)
+
+## What was broken
+
+`CloudflareQuickProvider` (the Tier-1 zero-config quick tunnel) classified
+failures via `classifyError(msg, stderr)`, whose rate-limit branch checks the
+text for `429` / `1015` / "rate limit" / "too many requests". But the provider
+listened only to the cloudflared wrapper's `url` / `error` / `exit` events — it
+**never listened to the wrapper's `stderr` event**, which is the only place
+cloudflared's real stderr (including the `429 Too Many Requests` / `error code
+1015` rate-limit line) is delivered. So `stderrTail` stayed empty, `exit` logged
+the opaque `process-exit code 1: no stderr captured`, and the 429 branch was
+**dead code on the exit path** — the manager could never recognize (or back off
+on / surface) a Cloudflare rate-limit.
+
+Found live (2026-05-31): a quick-tunnel start hit Cloudflare 429, but instar
+surfaced only "process-exit code 1: no stderr captured"; the 429 was visible
+only by running `cloudflared tunnel --url` directly.
+
+## The fix
+
+1. `CloudflareQuickProvider.startInner` now registers
+   `tunnel.on('stderr', (data) => { stderrTail = (stderrTail + ' ' + data).slice(-2000); })`,
+   capturing cloudflared's real stderr (bounded to the last 2000 chars). The
+   existing `error`/`exit` handlers already feed `stderrTail` into the
+   classifier, so the 429/1015 text now reaches it.
+2. The classification logic is extracted to a pure, exported
+   `classifyQuickTunnelError(msg, stderr)` (unchanged behavior), so the
+   decision boundary is unit-testable.
+
+## Who is affected
+
+- **Any agent with a quick tunnel that hits Cloudflare 429** (the free
+  trycloudflare service rate-limits under load): the failure is now classified
+  `rate-limited:` instead of opaque `process-exit`, so the TunnelManager's
+  failure handling (per the tunnel-failure-resilience spec) acts on the correct
+  reason. No behavior change on the success path or for non-rate-limited
+  failures (those classify exactly as before).
+
+## Blast radius
+
+- 1 source file: `src/tunnel/CloudflareQuickProvider.ts` (one added event
+  listener + a pure-function extraction). No config, no schema, no migration —
+  picked up by existing agents on the normal dist update. The TunnelManager,
+  other providers, and the success path are untouched.
+
+## Failure modes considered
+
+- **Listener fires after resolution?** Harmless — it only appends to a bounded
+  buffer; once `url` resolves, the buffer is unused.
+- **stderr never arrives (true silent exit)?** Behavior is exactly as before:
+  `stderrTail` empty → `exit` logs "no stderr captured" → classified generic.
+  The fix can only ADD signal, never remove it.
+- **Buffer growth?** Bounded to the last 2000 chars via `.slice(-2000)`.
+
+## Tests
+
+`tests/unit/CloudflareQuickProvider.test.ts` (6): `classifyQuickTunnelError`
+across 429/1015/"too many requests"/"rate limit", ENOENT→binary-missing,
+DNS/ECONNREFUSED→network, and unrecognized→preserved; plus a mock-`cloudflared`
+test proving the new `stderr` listener feeds a 429 stderr line into the
+classifier so `start()` rejects `rate-limited` (rather than the opaque
+`process-exit`). `tsc --noEmit` clean.