mandrel 2.8.0 → 2.10.0

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(' ');
+}

package/.agents/scripts/single-story-confirm-merge.js

@@ -27,7 +27,8 @@
  * short-circuits to a `noop` envelope.
  *
  * Usage:
- *   node single-story-confirm-merge.js --story <STORY_ID> [--pr <n>]
+ *   node single-story-confirm-merge.js --story <STORY_ID> [--pr <n>] [--wait]
+ *                                      [--max-wait-seconds <n>]
  *                                      [--cwd <main-repo>]
  *
  * Exit codes: 0 ok (merged, pending, or noop), 1 error.
@@ -40,11 +41,13 @@ import { parseSprintArgs } from './lib/cli-args.js';
 import { runAsCli } from './lib/cli-utils.js';
 import { resolveConfig } from './lib/config-resolver.js';
 import { formatCliError } from './lib/error-redactor.js';
-import { gh as defaultGh } from './lib/gh-exec.js';
+import { createGh } from './lib/gh-exec.js';
 import { getStoryBranch } from './lib/git-utils.js';
 import { Logger } from './lib/Logger.js';
 import { emitTerminalFriction } from './lib/observability/runtime-friction.js';
+import { emitTerseResult } from './lib/observability/terse-result.js';
 import { MERGED_FLIP_FAILED_BLOCK_CLASS } from './lib/orchestration/lifecycle/emit-merge-flip-failed.js';
+import { MERGE_WAIT_GH_TIMEOUT_MS } from './lib/orchestration/merge-poll.js';
 import { parsePrNumber } from './lib/orchestration/single-story-close/phases/code-review.js';
 import { runConfirmMergePhase as defaultRunConfirmMergePhase } from './lib/orchestration/single-story-close/phases/confirm-merge.js';
 import { parseCloseOptions } from './lib/orchestration/single-story-close/phases/options.js';
@@ -63,6 +66,25 @@ const progress = Logger.createProgress('single-story-confirm-merge', {
   stderr: true,
 });
 
+/**
+ * Default `gh` facade for this CLI, bound to the merge wait's spawn-level
+ * timeout (Story #4710). This CLI is the resume surface async mode hands the
+ * merge wait to — a background invocation with no host tool ceiling — so an
+ * un-timeboxed `gh pr list` / `gh pr view` here could strand the resume the
+ * same way an un-timeboxed probe stranded the in-close wait.
+ */
+const defaultGh = createGh(undefined, { timeoutMs: MERGE_WAIT_GH_TIMEOUT_MS });
+
+/** One usage string for the throw path and `--help` (Story #4710). */
+const USAGE =
+  'Usage: node single-story-confirm-merge.js --story <STORY_ID> [--pr <n>] [--wait] ' +
+  '[--max-wait-seconds <n>] [--cwd <main-repo>]\n\n' +
+  '  --wait              resume the bounded merge wait instead of probing once\n' +
+  '  --max-wait-seconds  per-invocation wait bound override, threaded to\n' +
+  '                      resolveMergeWaitConfig exactly as the close does (wins\n' +
+  '                      over delivery.mergeWatch.maxWaitSeconds and the async\n' +
+  '                      probe-window cap; only meaningful with --wait)';
+
 /**
  * Read the `--pr <n>` flag from `process.argv` for the direct-CLI path.
  * Injection callers pass `pr` directly and never reach this. Returns the
@@ -105,6 +127,33 @@ function readWaitFlag() {
   }
 }
 
+/**
+ * `--max-wait-seconds <n>`: per-invocation wait-bound override for the
+ * `--wait` resume path (Story #4710). The close CLI already accepted this
+ * flag, but the resume CLI — the exact command async mode's `pending`
+ * terminal hands off to — did not, so the documented per-run override was
+ * unreachable where it mattered most and a slow-CI landing depended on an
+ * unbounded chain of short invocations. Threaded to `runConfirmMergePhase`
+ * (and thence `resolveMergeWaitConfig`) exactly as close threads its own
+ * flag. Returns `undefined` when absent or not a positive integer — the
+ * phase's config/default resolution owns that case.
+ *
+ * @returns {number|undefined}
+ */
+function readMaxWaitSecondsFlag() {
+  try {
+    const { values } = parseArgs({
+      args: process.argv.slice(2),
+      options: { 'max-wait-seconds': { type: 'string' } },
+      strict: false,
+    });
+    const parsed = Number.parseInt(String(values['max-wait-seconds']), 10);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Resolve the PR number for the Story branch when one was not passed on
  * the CLI. Probes `gh pr list --head <branch> --state all` (the merged PR
@@ -142,11 +191,19 @@ async function resolvePrNumber({ cwd, storyBranch, gh }) {
  * exits via `process.exit` the moment `main` resolves.
  */
 async function logConfirmResult(result, terminal, config) {
-  // Human-facing dump stays level-gated; the envelope is the machine
-  // contract and must survive AGENT_LOG_LEVEL=silent.
-  Logger.info(
-    `\n--- CONFIRM MERGE RESULT ---\n${JSON.stringify(result, null, 2)}\n--- END RESULT ---\n`,
-  );
+  // Story #4685 — full detail to a temp log; the agent acts on the terminal
+  // envelope emitted below. The summary line keeps the at-a-glance fields.
+  emitTerseResult({
+    label: 'CONFIRM MERGE RESULT',
+    result,
+    scope: result?.storyId,
+    summary: {
+      storyId: result?.storyId,
+      action: result?.action,
+      reason: result?.reason,
+      status: terminal?.status,
+    },
+  });
   emitTerminalEnvelope(terminal);
   await emitTerminalFriction({ envelope: terminal, config });
   return { success: terminal.status !== 'failed', result, terminal };
@@ -253,6 +310,7 @@ export async function runConfirmMerge({
   cwd: cwdParam,
   pr: prParam,
   wait: waitParam,
+  maxWaitSeconds: maxWaitSecondsParam,
   injectedProvider,
   injectedConfig,
   injectedGh,
@@ -266,11 +324,10 @@ export async function runConfirmMerge({
   });
 
   if (!storyId) {
-    throw new Error(
-      'Usage: node single-story-confirm-merge.js --story <STORY_ID> [--pr <n>] [--wait] [--cwd <main-repo>]',
-    );
+    throw new Error(USAGE);
   }
   const wait = waitParam ?? readWaitFlag();
+  const maxWaitSeconds = maxWaitSecondsParam ?? readMaxWaitSecondsFlag();
 
   const startedAtMs = Date.now();
   const config = injectedConfig || resolveConfig({ cwd });
@@ -337,6 +394,10 @@ export async function runConfirmMerge({
       // The close already armed it; this CLI is resuming that wait, not
       // deciding whether to arm.
       autoMergeEnabled: true,
+      // The per-run override (`--max-wait-seconds`), resolved by
+      // `resolveMergeWaitConfig` exactly as the close resolves its own flag —
+      // it wins over the config value and the async probe-window cap.
+      maxWaitSeconds,
       provider,
       config,
       progress,
@@ -441,6 +502,14 @@ export async function runConfirmMerge({
  * or none at all; "none at all" is what Story #4543 removes.
  */
 async function main() {
+  if (process.argv.includes('--help')) {
+    // Print usage (including --max-wait-seconds) and exit cleanly — the
+    // resume-path override is only discoverable if the CLI can say it exists.
+    // `process.stdout.write` (not console.log) keeps the CLI within the
+    // no-console repo invariant while still writing help to stdout.
+    process.stdout.write(`${USAGE}\n`);
+    return 0;
+  }
   try {
     const outcome = await runConfirmMerge();
     return exitCodeForTerminal(outcome?.terminal ?? { status: 'failed' });

package/.agents/scripts/single-story-init.js

@@ -55,6 +55,7 @@ import { getStoryBranch, gitSpawn, gitSync } from './lib/git-utils.js';
 import { Logger } from './lib/Logger.js';
 import { TYPE_LABELS } from './lib/label-constants.js';
 import { setActiveStoryEnv } from './lib/observability/active-story-env.js';
+import { emitTerseResult } from './lib/observability/terse-result.js';
 import {
   executeFastForward,
   planFastForward,
@@ -769,9 +770,24 @@ export async function runSingleStoryInit({
     }
   }
 
-  Logger.info('\n--- STORY INIT RESULT ---');
-  Logger.info(JSON.stringify(result, null, 2));
-  Logger.info('--- END RESULT ---\n');
+  // Story #4685 — route the full result to a temp log and emit a single-line
+  // summary carrying the fields the orchestrating agent acts on (workCwd,
+  // remoteVerified). The `## Spec` names this the hot-path stdout to quiet.
+  emitTerseResult({
+    label: 'STORY INIT RESULT',
+    result,
+    scope: storyId,
+    logDir: path.join(cwd, 'temp', 'orchestration'),
+    summary: {
+      storyId,
+      storyBranch,
+      workCwd,
+      worktreeCreated,
+      dependenciesInstalled,
+      remoteVerified: result.remoteVerified,
+      dryRun,
+    },
+  });
   progress(
     'DONE',
     dryRun

package/.agents/scripts/stories-wave-tick.js

@@ -862,7 +862,7 @@ async function main(argv) {
           inFlight: values['in-flight'],
         });
 
-  process.stdout.write(`${JSON.stringify(envelope, null, 2)}\n`);
+  process.stdout.write(`${JSON.stringify(envelope)}\n`);
 
   if (exitCode !== 0) {
     Logger.error(

package/.agents/scripts/sync-branch-from-base.js

@@ -34,6 +34,7 @@ import { runAsCli } from './lib/cli-utils.js';
 import { syncBranchFromBase } from './lib/git/sync-from-base.js';
 import { gitSpawn, gitSync } from './lib/git-utils.js';
 import { Logger } from './lib/Logger.js';
+import { emitTerseResult } from './lib/observability/terse-result.js';
 import { PROJECT_ROOT } from './lib/project-root.js';
 
 const progress = Logger.createProgress('sync-branch-from-base', {
@@ -93,9 +94,14 @@ export async function runSyncBranchFromBase(opts = {}) {
     gitSpawn,
   });
 
-  Logger.info(
-    `\n--- SYNC RESULT ---\n${JSON.stringify(result, null, 2)}\n--- END RESULT ---\n`,
-  );
+  // Story #4685 — full detail to a temp log; emit a single summary line.
+  emitTerseResult({
+    label: 'SYNC RESULT',
+    result,
+    scope: branch,
+    logDir: path.join(cwd, 'temp', 'orchestration'),
+    summary: { branch, base, synced: result.synced, kind: result.kind },
+  });
 
   if (!result.synced) {
     const detail =