mandrel 2.7.0 → 2.9.0

package/.agents/scripts/lib/orchestration/task-body-validator.js

@@ -52,6 +52,10 @@
  * at a time.
  */
 
+import {
+  suggestPathEntryFix,
+  suggestVerifyFix,
+} from '../story-body/body-format-lints.js';
 import {
   parse as parseStoryBody,
   StoryBodyParseError,
@@ -73,44 +77,6 @@ export const VERIFY_TIER_VALUES = Object.freeze([
   'validate',
 ]);
 
-const PATH_LIKE_RE = /[/.][\w@\-./*]+|\*\*?\/?\*?\.\w+|[a-z][\w-]*\/[\w-./*]+/i;
-const VAGUE_VERBS = [
-  'clean up',
-  'refactor',
-  'improve',
-  'polish',
-  'tighten',
-  'tidy',
-  'simplify',
-];
-
-/**
- * @param {string} bullet
- * @returns {boolean}
- */
-function bulletNamesPath(bullet) {
-  const colonIdx = bullet.indexOf(':');
-  if (colonIdx <= 0) return PATH_LIKE_RE.test(bullet);
-  const head = bullet.slice(0, colonIdx);
-  // The conventional shape is "<path>: <verb> <object>" — head is the path.
-  return PATH_LIKE_RE.test(head) || PATH_LIKE_RE.test(bullet);
-}
-
-/**
- * @param {string} bullet
- * @returns {string|null} reason if the bullet uses a vague verb without a named target, else null.
- */
-function vagueVerbWithoutTarget(bullet) {
-  const lower = bullet.toLowerCase();
-  for (const verb of VAGUE_VERBS) {
-    if (!lower.includes(verb)) continue;
-    if (!bulletNamesPath(bullet)) {
-      return verb;
-    }
-  }
-  return null;
-}
-
 /**
  * Predicate: should the validator skip this ticket entirely? Skip when:
  *   - it is not a Story (only `type: 'story'` tickets are validated here),
@@ -297,8 +263,13 @@ function collectChangesErrors(prefix, rawChanges) {
   }
   for (const entry of changes) {
     if (typeof entry === 'string') {
+      const fix = suggestPathEntryFix(entry);
+      const fixIt =
+        fix === null
+          ? ''
+          : ` Suggested fix: ${fix} (adjust the assumption to creates|deletes if this is a new file or a removal).`;
       errors.push(
-        `${prefix}: body.changes entry must be a { path, assumption } object; plain string bullets are no longer accepted: "${entry}".`,
+        `${prefix}: body.changes entry must be a { path, assumption } object; plain string bullets are no longer accepted: "${entry}".${fixIt}`,
       );
       continue;
     }
@@ -385,8 +356,10 @@ function collectVerifyErrors(prefix, rawVerify) {
       continue;
     }
     if (!VERIFY_TIER_RE.test(v)) {
+      const fix = suggestVerifyFix(v);
+      const fixIt = fix === null ? '' : ` Suggested fix: "${fix}".`;
       errors.push(
-        `${prefix}: body.verify entry must end with a tier in parentheses — one of (${VERIFY_TIER_VALUES.join('|')}). Got: "${v}".`,
+        `${prefix}: body.verify entry must end with a tier in parentheses — one of (${VERIFY_TIER_VALUES.join('|')}). Got: "${v}".${fixIt}`,
       );
     }
   }

package/.agents/scripts/lib/story-body/body-format-lints.js

@@ -0,0 +1,215 @@
+/**
+ * body-format-lints.js — SSOT for the deterministic body-format lints that can
+ * REJECT an authored Story body at persist time, plus the mechanical auto-fix
+ * inference a failing dry-run surfaces (Story #4684).
+ *
+ * The problem this closes: deterministic format rules (structured `## Changes`
+ * bullet shape, verify-tier suffixes) used to be discovered only as persist
+ * dry-run failures — every miss cost a full re-author round-trip at
+ * resident-context prices. This module is the single home for two remedies:
+ *
+ *   1. `BODY_FORMAT_LINTS` — the enumerated rejecting lints, each carrying a
+ *      concrete good/bad example. `templates/decomposer-prompts.js` renders
+ *      them into the story-author system prompt so the first draft is
+ *      lint-clean by construction; a test enumerates the registry against the
+ *      rendered prompt (Story #4684 AC-1).
+ *   2. `suggestPathEntryFix` / `suggestVerifyFix` — the mechanical rewrites.
+ *      `story-body.js` (`parsePathEntry`) and `task-body-validator.js`
+ *      (`collectChangesErrors` / `collectVerifyErrors`) call them so a failing
+ *      lint emits the corrected form ready to paste rather than a bare reject
+ *      (AC-2).
+ *
+ * Import hygiene: this module imports only the cycle-free
+ * `file-assumption-enum.js` leaf. It must NOT import `story-body.js` or
+ * `task-body-validator.js` — both import this module, and either back-edge
+ * would introduce a cycle (see the note in `file-assumption-enum.js`).
+ */
+
+import { FILE_ASSUMPTION_VALUES } from '../orchestration/file-assumption-enum.js';
+
+/**
+ * Canonical testing-tier vocabulary an inferred verify suffix may name. Kept in
+ * sync with `task-body-validator.js`'s `VERIFY_TIER_VALUES` by a test rather
+ * than an import (importing that module here would create a cycle).
+ *
+ * @type {readonly ['unit','contract','e2e','validate']}
+ */
+const INFERABLE_VERIFY_TIERS = Object.freeze([
+  'unit',
+  'contract',
+  'e2e',
+  'validate',
+]);
+
+/**
+ * The default assumption a mechanical `## Changes` auto-fix proposes. Most
+ * bare-path bullets an author drops are in-place edits, so `refactors-existing`
+ * is the safe default — the fix-it text tells the author to switch it to
+ * `creates` / `deletes` when the edit is net-new or a removal.
+ */
+const DEFAULT_SUGGESTED_ASSUMPTION = 'refactors-existing';
+
+// A token that looks like a file path / glob / module id: it carries a `/` or a
+// `.`-separated segment. Deliberately loose — the suggestion is best-effort, and
+// a false positive only produces an unhelpful (still-valid) fix-it string.
+const PATH_LIKE_RE = /[\w@*-]*[/.][\w@./*-]+/;
+
+/**
+ * Infer the testing tier a bare `verify[]` command implies, when it is
+ * unambiguous. Returns `null` when no confident inference is possible (the
+ * author must then choose the tier themselves — the lint still fires, just
+ * without a fix-it).
+ *
+ * @param {unknown} command
+ * @returns {'unit'|'contract'|'e2e'|'validate'|null}
+ */
+function inferVerifyTier(command) {
+  if (typeof command !== 'string') return null;
+  const c = command.toLowerCase();
+  if (/\bvalidate\b/.test(c)) return 'validate';
+  if (/playwright|\.spec\.|\be2e\b/.test(c)) return 'e2e';
+  if (/\.test\.|node --test|node:test|\bvitest\b|\bjest\b/.test(c)) {
+    return 'unit';
+  }
+  if (/\bcontract\b/.test(c)) return 'contract';
+  return null;
+}
+
+/**
+ * Propose the corrected form of a `verify[]` entry that is missing its tier
+ * suffix, when the tier is inferable from the command. Returns `null` when the
+ * entry is a `manual:` escape, is empty, or the tier cannot be inferred.
+ *
+ * @param {unknown} entry
+ * @returns {string|null} e.g. `"npm run validate (validate)"`.
+ */
+export function suggestVerifyFix(entry) {
+  if (typeof entry !== 'string') return null;
+  const trimmed = entry.trim();
+  if (trimmed === '' || trimmed.startsWith('manual:')) return null;
+  const tier = inferVerifyTier(trimmed);
+  if (tier === null) return null;
+  // Drop any trailing (…) — a wrong/partial tier suffix — before appending the
+  // inferred one, so `npm test (smoke)` becomes `npm test (unit)` not a double.
+  const base = trimmed.replace(/\s*\([^)]*\)\s*$/, '').trim();
+  if (base === '') return null;
+  return `${base} (${tier})`;
+}
+
+/**
+ * Propose the canonical `{ path, assumption }` object form for a `## Changes` /
+ * `## References` bullet an author wrote as a bare path string (or a humanized
+ * bullet with a bad assumption). Returns `null` when no path-shaped token can
+ * be salvaged.
+ *
+ * The returned string is inline-JSON that round-trips cleanly back through the
+ * story-body parser, so it is paste-ready.
+ *
+ * @param {unknown} raw
+ * @returns {string|null} e.g. `{"path":"src/app.js","assumption":"refactors-existing"}`.
+ */
+export function suggestPathEntryFix(raw) {
+  if (typeof raw !== 'string') return null;
+  // Strip a leading markdown bullet marker.
+  let s = raw
+    .trim()
+    .replace(/^[-*]\s+/, '')
+    .trim();
+  // Take the segment before any humanized "— assumption" tail.
+  s = s.split('—')[0].trim();
+  // Peel surrounding backticks / quotes.
+  s = s
+    .replace(/^[`'"]+/, '')
+    .replace(/[`'"]+$/, '')
+    .trim();
+  if (s === '' || !PATH_LIKE_RE.test(s)) return null;
+  return JSON.stringify({ path: s, assumption: DEFAULT_SUGGESTED_ASSUMPTION });
+}
+
+/**
+ * A single deterministic body-format lint the persist path enforces.
+ *
+ * @typedef {object} BodyFormatLint
+ * @property {string}  id          Stable identifier (also the prompt anchor).
+ * @property {string}  summary     One-line statement of the requirement.
+ * @property {string}  badExample  A form the lint rejects.
+ * @property {string}  goodExample The lint-clean form to author instead.
+ * @property {boolean} autoFixable Whether a failing dry-run emits a fix-it.
+ */
+
+/**
+ * The enumerated deterministic lints that can reject an authored Story body at
+ * persist time. Each carries a concrete example so the story-author prompt can
+ * state the requirement example-first (Story #4684 AC-1). The two `autoFixable`
+ * lints are the mechanical rewrites whose dry-run failure carries the corrected
+ * form (AC-2).
+ *
+ * @type {ReadonlyArray<BodyFormatLint>}
+ */
+export const BODY_FORMAT_LINTS = Object.freeze([
+  {
+    id: 'body-is-string',
+    summary:
+      'The Story `body` MUST be the serialized markdown string produced by `serialize()`, never a JSON object.',
+    badExample: '"body": { "goal": "…" }',
+    goodExample: '"body": "## Goal\\n…"',
+    autoFixable: false,
+  },
+  {
+    id: 'goal-non-empty',
+    summary: 'The body MUST open with a non-empty `## Goal` sentence.',
+    badExample: '## Goal\n\n## Spec',
+    goodExample:
+      '## Goal\nExchange short-lived JWTs so sessions survive a restart.',
+    autoFixable: false,
+  },
+  {
+    id: 'changes-path-entry-shape',
+    summary:
+      'Every `## Changes` / `## References` bullet MUST be a `{ path, assumption }` object (assumption ∈ ' +
+      `${FILE_ASSUMPTION_VALUES.join(' | ')}); plain path strings are rejected.`,
+    badExample: '- src/app.js',
+    goodExample: '- {"path": "src/app.js", "assumption": "refactors-existing"}',
+    autoFixable: true,
+  },
+  {
+    id: 'changes-non-empty',
+    summary: 'A Story MUST declare at least one `## Changes` bullet.',
+    badExample: '## Changes\n\n## Acceptance',
+    goodExample: '- {"path": "src/app.js", "assumption": "creates"}',
+    autoFixable: false,
+  },
+  {
+    id: 'verify-tier-suffix',
+    summary:
+      'Every `verify[]` entry MUST end with a tier in parentheses — one of ' +
+      `(${INFERABLE_VERIFY_TIERS.join(' | ')}) — or be a \`manual:<reason>\` escape.`,
+    badExample: 'npm test -- src/app.test.js',
+    goodExample: 'npm test -- src/app.test.js (unit)',
+    autoFixable: true,
+  },
+  {
+    id: 'verify-non-empty',
+    summary:
+      'A Story MUST list at least one `verify[]` entry (use `manual:<reason>` only when truly unverifiable in isolation).',
+    badExample: '"verify": []',
+    goodExample: '"verify": ["npm run validate (validate)"]',
+    autoFixable: false,
+  },
+  {
+    id: 'verify-manual-reason',
+    summary:
+      'A `manual:` verify entry MUST carry a reason after the colon; a bare `manual:` is rejected.',
+    badExample: 'manual:',
+    goodExample: 'manual: copy-only edit an auditor eyeballs',
+    autoFixable: false,
+  },
+  {
+    id: 'acceptance-non-empty',
+    summary:
+      'A Story MUST list at least one observable `acceptance[]` criterion.',
+    badExample: '"acceptance": []',
+    goodExample: '"acceptance": ["`npm run build` exits 0"]',
+    autoFixable: false,
+  },
+]);

package/.agents/scripts/lib/story-body/story-body.js

@@ -48,6 +48,7 @@ import {
   authoredMarkerLine,
 } from '../framework-version.js';
 import { FILE_ASSUMPTION_VALUES } from '../orchestration/file-assumption-enum.js';
+import { suggestPathEntryFix } from './body-format-lints.js';
 
 // ---------------------------------------------------------------------------
 // Public types (JSDoc only — no runtime schema file)
@@ -229,7 +230,7 @@ function parsePathEntry(raw, warnings) {
     }
     // Recognized the humanized shape but the fields are invalid: fail closed.
     throw new StoryBodyParseError(
-      `changes/references entry is a humanized bullet but not a valid PathEntry: ${str.slice(0, 120)}`,
+      `changes/references entry is a humanized bullet but not a valid PathEntry: ${str.slice(0, 120)}${pathEntryFixIt(str)}`,
       { field: 'changes', raw: str },
     );
   }
@@ -261,11 +262,26 @@ function parsePathEntry(raw, warnings) {
   }
 
   throw new StoryBodyParseError(
-    `changes/references entry must be a { path, assumption } object; plain string bullets are no longer accepted: ${str.slice(0, 120)}`,
+    `changes/references entry must be a { path, assumption } object; plain string bullets are no longer accepted: ${str.slice(0, 120)}${pathEntryFixIt(str)}`,
     { field: 'changes', raw: str },
   );
 }
 
+/**
+ * Build the ` Suggested fix: …` suffix for a rejected changes/references
+ * bullet, when a `{ path, assumption }` object can be salvaged from it. Returns
+ * an empty string when nothing is inferable, so callers can append it
+ * unconditionally (Story #4684 — mechanical auto-fix in the failure output).
+ *
+ * @param {string} raw The rejected bullet text.
+ * @returns {string}
+ */
+function pathEntryFixIt(raw) {
+  const suggestion = suggestPathEntryFix(raw);
+  if (suggestion === null) return '';
+  return ` — Suggested fix: ${suggestion} (adjust the assumption to creates|deletes if this is a new file or a removal).`;
+}
+
 /**
  * Extract the `blocked by #N` lines from the footer block (text after
  * the last `---` separator). Returns an array of "#N" strings.

package/.agents/scripts/lib/templates/decomposer-prompts.js

@@ -5,6 +5,7 @@ import {
   DELIVERABLE_GRANULARITY_GUIDANCE,
   resolveCapacityCeilings,
 } from '../orchestration/ticket-validator-sizing.js';
+import { BODY_FORMAT_LINTS } from '../story-body/body-format-lints.js';
 
 /**
  * Sole source of truth for the prompt's `maxTickets` cap is the resolved
@@ -63,6 +64,15 @@ function render2TierPrompt({ maxTickets }) {
     advisoryCaveat,
     newFileContract,
   } = AUTHORING_ALTITUDE_GUIDANCE;
+  // The deterministic body-format lints (structured `## Changes` bullet shape,
+  // verify-tier suffixes, …) rendered example-first from their single source
+  // (`lib/story-body/body-format-lints.js`) so an authored draft is lint-clean
+  // by construction rather than discovered as a persist dry-run failure and
+  // re-authored at resident-context prices (Story #4684).
+  const bodyFormatLintChecklist = BODY_FORMAT_LINTS.map(
+    (lint) =>
+      `- **${lint.id}** — ${lint.summary} Example: \`${lint.goodExample}\``,
+  ).join('\n');
   return `You are an expert Senior Project Manager and Orchestrator.
 Your job is to turn a plan seed / Tech Spec into a Story ticket array for an AI Agent to execute.
 
@@ -152,6 +162,12 @@ The serialized \`body\` string renders these markdown sections (in order):
 - **Bodies record decisions, never questions to the operator.** Never persist an open question ("Flag if…", "TBD", "confirm with the operator") into a Story body — the executing sub-agent is non-interactive and cannot answer it. Resolve the unknown before authoring, or restate it as a declarative Key Assumption the agent can act on.
 - **non_goals** (OPTIONAL, in body string as the \`## Non-Goals\` section): A short list of capabilities or changes this Story explicitly does NOT deliver — an advisory negative-scope bound that fences the executing agent away from adjacent work. It is **advisory and NON-GATING**: the validator does not require, count, or reject on it, and an absent or empty section renders nothing. Use the EXACT single-word hyphenated heading spelling \`## Non-Goals\` (a space-separated heading like \`## Out of Scope\` is NOT recognized by the parser and will be dropped). Reach for it when a Story's negative boundary is non-obvious from its \`acceptance[]\` alone; omit it otherwise.
 
+#### DETERMINISTIC BODY-FORMAT LINTS — author lint-clean by construction:
+
+Persist enforces the deterministic body-format rules below and **rejects** an authored body that violates any of them. Author every Story to satisfy all of them on the FIRST draft — each rule is stated example-first so there is nothing to discover by trial-and-error. The two auto-fixable rules (\`changes-path-entry-shape\`, \`verify-tier-suffix\`) also emit the corrected form in the dry-run failure output, but authoring them right up front avoids the round-trip entirely.
+
+${bodyFormatLintChecklist}
+
 #### AUTHORING ALTITUDE — BINDING ACCEPTANCE vs ADVISORY CHANGES:
 
 ${authoringAltitude}

package/.agents/scripts/providers/github/issues.js

@@ -15,16 +15,38 @@
  * @see Story #2462 — Split GitHubProvider god class into seven composed gateways.
  */
 
+import { GhRateLimitError } from '../../lib/gh-exec.js';
 import { Logger } from '../../lib/Logger.js';
 import { concurrentMap } from '../../lib/util/concurrent-map.js';
 import { isNotFoundError } from './branch-protection.js';
-import { withTransientRetry } from './errors.js';
+import { classifyGithubError, withTransientRetry } from './errors.js';
 import { issueToEpic } from './mappers.js';
 import {
   defaultRetryWarn,
   paginateRest,
   parseApiJson,
 } from './request-helpers.js';
+import {
+  searchBudget as defaultSearchBudget,
+  parseRateLimitResetMs,
+} from './search-budget.js';
+import { composeBoundedQuery } from './search-query.js';
+
+/**
+ * Retry classifier for the `searchIssues` call site. A rate-limit error is
+ * non-transient **here** — the shared search budget (not `withTransientRetry`)
+ * owns the wait, so the call must fail fast rather than burn its retry budget
+ * re-issuing into an empty window. Every other error keeps the global
+ * classification, so a 5xx/network blip still retries. `classifyGithubError`
+ * itself is unchanged: other endpoints legitimately retry on rate-limit.
+ *
+ * @param {unknown} err
+ * @returns {string}
+ */
+function classifySearchRetry(err) {
+  if (err instanceof GhRateLimitError) return 'rate-limited';
+  return classifyGithubError(err);
+}
 
 /**
  * Concurrency budget for the `getSubTickets` fan-out — preserved from
@@ -51,11 +73,15 @@ export class IssuesGateway {
    *   },
    * }} deps
    */
-  constructor({ gh, owner, repo, hooks = {} } = {}) {
+  constructor({ gh, owner, repo, hooks = {}, searchBudget } = {}) {
     this._gh = gh;
     this.owner = owner;
     this.repo = repo;
     this._hooks = hooks;
+    // The `/search/issues` fan-out budget. Defaults to the process-wide
+    // singleton so every gateway instance shares one 30/min window; injectable
+    // so unit tests drive it deterministically (Story #4678).
+    this._searchBudget = searchBudget ?? defaultSearchBudget;
   }
 
   /**
@@ -132,14 +158,35 @@ export class IssuesGateway {
     // Constrain the search to this repo and to issues (not PRs). The
     // fingerprint sha is the free-text term; GitHub matches it against the
     // issue body where the `<!-- audit-fingerprints: ... -->` footer lives.
+    // The composed `q` is bounded to GitHub Search's 256-char limit here — the
+    // only place that knows both the free text and the qualifiers it appends —
+    // truncating the free-text portion on a whole-token boundary (Story #4678).
     const qualifiers = [`repo:${scopeOwner}/${scopeRepo}`, 'type:issue'];
-    const q = `${query.trim()} ${qualifiers.join(' ')}`;
+    const q = composeBoundedQuery(query, qualifiers);
     const params = new URLSearchParams({ q, per_page: '100' });
     const endpoint = `/search/issues?${params}`;
-    const result = await withTransientRetry(
-      () => this._gh.api({ method: 'GET', endpoint }),
-      { label: `searchIssues ${query}`, onRetry: defaultRetryWarn },
-    );
+    // Await the shared 30/min budget before every call so the whole scan's
+    // fan-out is throttled at the endpoint, not per caller (Story #4678).
+    await this._searchBudget.take();
+    let result;
+    try {
+      result = await withTransientRetry(
+        () => this._gh.api({ method: 'GET', endpoint }),
+        {
+          label: `searchIssues ${query}`,
+          onRetry: defaultRetryWarn,
+          classify: classifySearchRetry,
+        },
+      );
+    } catch (err) {
+      // A rate limit means the window is empty: drain the budget until the
+      // reported reset so the *next* call pauses once, rather than every call
+      // retrying independently into the exhausted window.
+      if (err instanceof GhRateLimitError) {
+        this._searchBudget.noteRateLimited(parseRateLimitResetMs(err));
+      }
+      throw err;
+    }
     const json = parseApiJson(result);
     const items = Array.isArray(json?.items) ? json.items : [];
     return items.map((item) => ({

package/.agents/scripts/providers/github/search-budget.js

@@ -0,0 +1,124 @@
+/**
+ * GitHub Provider — `/search/issues` fan-out budget (Story #4678).
+ *
+ * The 30-requests-per-minute cap is a property of GitHub's `/search/issues`
+ * endpoint, not of any one caller. A single audit-to-stories scan issues ~2
+ * search calls per finding; a 22-group scan therefore blows well past the cap
+ * with no throttle of any kind, and every exhausted call then spends its whole
+ * transient-retry budget re-issuing a request against an already-empty window.
+ *
+ * This module owns the throttle at the endpoint seam: a pure, injectable token
+ * bucket that `IssuesGateway#searchIssues` awaits before every call, so every
+ * caller (audit-to-stories dedup, `lib/duplicate-search.js`, the tickets
+ * gateway's `_searchIssues`) inherits one shared budget for free.
+ *
+ * `now` and `sleep` are injected so unit tests drive the bucket deterministically
+ * without wall-clock time.
+ */
+
+/**
+ * Default budget: 30 tokens per 60s window, matching GitHub's authenticated
+ * Search API cap. When a rate limit is reported with no readable reset, the
+ * bucket pauses for one full window before the next `take()` resolves.
+ */
+const SEARCH_BUDGET_DEFAULTS = Object.freeze({
+  capacity: 30,
+  windowMs: 60_000,
+  cooldownMs: 60_000,
+});
+
+/**
+ * Create a token-bucket search budget.
+ *
+ * `take()` resolves once a token is available, consuming it; it awaits an
+ * accruing token (and any active rate-limit cooldown) rather than failing.
+ * `noteRateLimited(resetAtMs)` drains the bucket and blocks every subsequent
+ * `take()` until the reported reset (or a fixed cooldown when no reset is
+ * readable), so the whole batch pauses **once** instead of each call retrying
+ * independently into the empty window.
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.capacity] — max tokens (and burst size).
+ * @param {number} [opts.windowMs] — window over which `capacity` tokens accrue.
+ * @param {number} [opts.cooldownMs] — pause applied when a rate limit reports
+ *   no readable reset time.
+ * @param {() => number} [opts.now] — millisecond clock (injected for tests).
+ * @param {(ms: number) => Promise<void>} [opts.sleep] — delay primitive.
+ * @returns {{ take: () => Promise<void>, noteRateLimited: (resetAtMs?: number) => void }}
+ */
+export function createSearchBudget({
+  capacity = SEARCH_BUDGET_DEFAULTS.capacity,
+  windowMs = SEARCH_BUDGET_DEFAULTS.windowMs,
+  cooldownMs = SEARCH_BUDGET_DEFAULTS.cooldownMs,
+  now = () => Date.now(),
+  sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+} = {}) {
+  const refillPerMs = capacity / windowMs;
+  let tokens = capacity;
+  let lastRefillAt = now();
+  let blockedUntil = 0;
+
+  function refill() {
+    const at = now();
+    const elapsed = at - lastRefillAt;
+    if (elapsed > 0) {
+      tokens = Math.min(capacity, tokens + elapsed * refillPerMs);
+      lastRefillAt = at;
+    }
+  }
+
+  async function take() {
+    for (;;) {
+      const at = now();
+      if (blockedUntil > at) {
+        await sleep(blockedUntil - at);
+        continue;
+      }
+      refill();
+      if (tokens >= 1) {
+        tokens -= 1;
+        return;
+      }
+      // Sleep just long enough for one token to accrue, then re-check.
+      const waitMs = Math.max(1, Math.ceil((1 - tokens) / refillPerMs));
+      await sleep(waitMs);
+    }
+  }
+
+  function noteRateLimited(resetAtMs) {
+    const at = now();
+    tokens = 0;
+    lastRefillAt = at;
+    const until =
+      typeof resetAtMs === 'number' && resetAtMs > at
+        ? resetAtMs
+        : at + cooldownMs;
+    if (until > blockedUntil) blockedUntil = until;
+  }
+
+  return { take, noteRateLimited };
+}
+
+/**
+ * Process-wide singleton shared by every `searchIssues` caller. Per-process,
+ * matching the one-scan-per-checkout model — there is deliberately no
+ * cross-process budget.
+ */
+export const searchBudget = createSearchBudget();
+
+/**
+ * Best-effort extract of a rate-limit reset time (epoch ms) from a thrown
+ * error's stderr. GitHub surfaces the reset as an `x-ratelimit-reset` epoch
+ * (seconds) header; `gh` echoes response headers onto stderr on failure.
+ * Returns `undefined` when no reset is readable so the bucket falls back to a
+ * fixed cooldown. Pure — no I/O.
+ *
+ * @param {unknown} err
+ * @returns {number|undefined} reset time in epoch milliseconds, or undefined.
+ */
+export function parseRateLimitResetMs(err) {
+  const haystack = [err?.stderr, err?.message].filter(Boolean).join('\n');
+  const match = haystack.match(/x-ratelimit-reset:\s*(\d{10})/i);
+  if (!match) return undefined;
+  return Number.parseInt(match[1], 10) * 1000;
+}

package/.agents/scripts/providers/github/search-query.js

@@ -0,0 +1,71 @@
+/**
+ * GitHub Provider — composed `/search/issues` query bound (Story #4678).
+ *
+ * `IssuesGateway#searchIssues` is the only place that knows the *composed* `q`
+ * — the caller's free text plus the `repo:<owner>/<repo> type:issue` qualifiers
+ * it appends. GitHub Search rejects a query over 256 characters with HTTP 422,
+ * which is neither transient nor caught, so an over-long title over a deep path
+ * would abort the whole scan. This module owns the defensive guard: it truncates
+ * the free-text portion on a whole-token boundary until the composed `q` fits.
+ *
+ * Pure and unit-testable — no I/O.
+ */
+
+/**
+ * GitHub Search's documented maximum query length, in characters. Module-private
+ * — `composeBoundedQuery` is the only supported way to apply it, so the bound
+ * cannot drift between call sites.
+ */
+const GITHUB_SEARCH_MAX_QUERY = 256;
+
+/**
+ * Compose a `/search/issues` query from free text plus fixed qualifiers,
+ * truncating the free-text portion on a whole-token boundary so the whole
+ * composed string is at most `max` characters. Qualifiers are never dropped —
+ * they are the load-bearing scope (`repo:` / `type:`) — so when even the
+ * qualifiers alone exceed the budget the qualifier string is returned as-is.
+ *
+ * @param {string} freeText — the caller's free-text search term(s).
+ * @param {string[]} qualifiers — fixed qualifier tokens (e.g. `repo:o/r`).
+ * @param {number} [max] — character ceiling for the composed query.
+ * @returns {string} the composed query, at most `max` characters.
+ */
+export function composeBoundedQuery(
+  freeText,
+  qualifiers,
+  max = GITHUB_SEARCH_MAX_QUERY,
+) {
+  const quals = qualifiers.join(' ');
+  const free = String(freeText ?? '').trim();
+  const full = `${free} ${quals}`.trim();
+  if (full.length <= max) return full;
+
+  // Reserve space for the qualifiers (and the joining space) and fit as many
+  // leading free-text tokens as the remaining budget allows.
+  const reserve = quals.length + (quals.length > 0 ? 1 : 0);
+  const budget = max - reserve;
+  const bounded = fitTokens(free.split(/\s+/).filter(Boolean), budget);
+  return bounded.length > 0 ? `${bounded} ${quals}`.trim() : quals;
+}
+
+/**
+ * Join as many leading `tokens` as fit within `budget` characters, on a
+ * whole-token boundary (space-separated). Returns '' when the budget cannot fit
+ * even the first token. Module-private — exercised through
+ * {@link composeBoundedQuery}, the only caller.
+ *
+ * @param {string[]} tokens
+ * @param {number} budget
+ * @returns {string}
+ */
+function fitTokens(tokens, budget) {
+  const kept = [];
+  let length = 0;
+  for (const token of tokens) {
+    const cost = kept.length === 0 ? token.length : token.length + 1;
+    if (length + cost > budget) break;
+    kept.push(token);
+    length += cost;
+  }
+  return kept.join(' ');
+}