infraweaver 0.1.0

package/src/agents/shared.ts

@@ -0,0 +1,377 @@
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+import type { RunTokenQuota } from "#app/agents/tokenQuota";
+import type { AgentId } from "#app/external";
+import type { ToolState } from "#app/toolState";
+import { log } from "#app/utils/cli";
+import type { ResolvedInstructions } from "#app/utils/instructions";
+import type { ResolvedPayload } from "#app/utils/payload";
+import type { TodoTracker } from "#app/utils/todoTracking";
+
+// maximum number of stderr lines to keep in the rolling buffer during agent execution
+export const MAX_STDERR_LINES = 20;
+
+// ── post-run retry loop ────────────────────────────────────────────────────────
+
+/**
+ * how many times the post-run loop may resume the agent to fix a dirty tree
+ * or a failing stop hook before giving up.
+ */
+export const MAX_POST_RUN_RETRIES = 3;
+
+export function getGitStatus(): string {
+  try {
+    return execFileSync("git", ["status", "--porcelain"], {
+      encoding: "utf-8",
+      timeout: 10_000,
+    }).trim();
+  } catch (err) {
+    // a git failure (timeout on a huge repo, index lock held by a stray
+    // agent-spawned process) is otherwise indistinguishable from a clean tree,
+    // silently disabling the dirty-tree gate — surface it so a lost-work run
+    // can be diagnosed.
+    log.warning(
+      `git status failed — dirty-tree gate skipped for this check: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return "";
+  }
+}
+
+export function buildCommitPrompt(status: string): string {
+  return [
+    `UNCOMMITTED CHANGES — the working tree is dirty. push all changes to a pull request (new or existing). \`git status\` must be clean before you finish.`,
+    "",
+    "```",
+    status,
+    "```",
+  ].join("\n");
+}
+
+export interface StopHookFailure {
+  exitCode: number;
+  output: string;
+}
+
+export interface SummaryStale {
+  /** absolute path to the seeded snapshot file the agent was meant to edit. */
+  filePath: string;
+}
+
+export interface PostRunIssues {
+  stopHook?: StopHookFailure;
+  dirtyTree?: string;
+  /** populated when the rolling PR summary file is byte-identical to its
+   * seed, i.e. the agent never touched it. soft gate — nudges once via a
+   * resume turn but never fails the run, parallel to dirtyTree semantics. */
+  summaryStale?: SummaryStale;
+  /**
+   * populated when the agent selected a review mode but the post-run check
+   * over toolState shows neither a `create_pull_request_review` submission
+   * nor a final `report_progress` write happened. derived inline from
+   * `toolState.selectedMode` + `toolState.review` + `toolState.finalSummaryWritten`
+   * via {@link getUnsubmittedReview} — no parallel toolState flag is stored.
+   * carries the mode name so the resume prompt can reference it. handled like
+   * `stopHook`: nudge via resume, hard-fail if still unsatisfied after
+   * `MAX_POST_RUN_RETRIES`.
+   */
+  unsubmittedReview?: "Review" | "IncrementalReview" | "TerraformCodeReview";
+}
+
+export function hasPostRunIssues(issues: PostRunIssues): boolean {
+  return (
+    issues.stopHook !== undefined ||
+    issues.dirtyTree !== undefined ||
+    issues.summaryStale !== undefined ||
+    issues.unsubmittedReview !== undefined
+  );
+}
+
+/**
+ * token/cost usage data from a single agent run.
+ *
+ * NOTE on semantics: `inputTokens` here is the *total* billable input for the
+ * run — non-cached input + cache read + cache write — matching the per-agent
+ * SDK conventions. This is what gets persisted to `WorkflowRun.inputTokens`.
+ *
+ * The stdout token table and markdown step summary display a different "Input"
+ * column that shows only the non-cached portion (derivable as
+ * `inputTokens - cacheReadTokens - cacheWriteTokens`) so humans can see the
+ * cache hit ratio at a glance. Dashboards that query `WorkflowRun.inputTokens`
+ * directly are seeing the full total, not the log column.
+ */
+export interface AgentUsage {
+  agent: string;
+  /** full billable input: non-cached + cache read + cache write */
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens?: number | undefined;
+  cacheWriteTokens?: number | undefined;
+  costUsd?: number | undefined;
+}
+
+export interface AgentToolUseEvent {
+  toolName: string;
+  input: unknown;
+}
+
+/**
+ * Result returned by agent execution
+ */
+export interface AgentResult {
+  success: boolean;
+  output?: string | undefined;
+  error?: string | undefined;
+  metadata?: Record<string, unknown>;
+  usage?: AgentUsage | undefined;
+}
+
+/**
+ * Env var that carries the per-run MCP bearer token to BOTH agent harnesses,
+ * which reference it from their MCP client config so the on-disk/in-config form
+ * holds only a placeholder, never the raw token:
+ *   - Claude Code expands `${INFRAWEAVER_MCP_TOKEN}` in .mcp.json headers.
+ *   - opencode expands `{env:INFRAWEAVER_MCP_TOKEN}` in remote-MCP headers.
+ * The `_TOKEN` suffix also makes filterEnv() strip it from the MCP shell
+ * sandbox. Set only on the agent/server spawn env (never process.env), so a
+ * co-located dependency-install subprocess never inherits it. See
+ * ToolContext.mcpServerToken and gateServer.ts for the same pattern.
+ */
+export const MCP_SERVER_TOKEN_ENV = "INFRAWEAVER_MCP_TOKEN";
+
+/**
+ * Context passed to agent.run() and threaded through the post-run loop.
+ *
+ * design rule: this is the single object that flows through the harness and
+ * downstream utilities by reference. derived predicates (e.g.
+ * `getUnsubmittedReview`), tmpfile paths, and seed bytes live on
+ * `toolState` — read them at the call site, do not duplicate them onto this
+ * interface. utilities that need run state should accept `ctx` whole, not
+ * destructure a narrow subset.
+ */
+export interface AgentRunContext {
+  payload: ResolvedPayload;
+  resolvedModel?: string | undefined;
+  mcpServerUrl: string;
+  /** per-run bearer token the agent's MCP client presents to mcpServerUrl. See
+   * ToolContext.mcpServerToken — delivered to the client config out-of-band so
+   * it never lands in a readable file. */
+  mcpServerToken: string;
+  tmpdir: string;
+  /** harness-owned secret paths that agent filesystem tools must never read. */
+  secretDenyPaths?: string[] | undefined;
+  /**
+   * canonical bare names of the state-mutating MCP tools subagents must not
+   * call, derived from each tool's `mutates` flag (`subagentDeniedToolNames`).
+   * Embedded into the claude/opencode subagent gate sources written at startup.
+   */
+  subagentDeniedTools: readonly string[];
+  instructions: ResolvedInstructions;
+  todoTracker?: TodoTracker | undefined;
+  /**
+   * user-configured stop hook script. runs after the agent finishes each
+   * attempt; non-zero exit resumes the agent with the hook output as
+   * guidance. null when the repo has no stop hook configured.
+   */
+  stopScript?: string | null | undefined;
+  /**
+   * mutable per-run state shared with the MCP server (by reference). post-run
+   * gates read fresh values from it after each agent attempt — `summaryFilePath`,
+   * `summarySeed`, `selectedMode`, `review`, `finalSummaryWritten`,
+   * `hadProgressComment` are all consulted by `collectPostRunIssues`. see
+   * `action/toolState.ts` for the literal-state design rule.
+   */
+  toolState: ToolState;
+  /**
+   * called synchronously when the agent subprocess is killed for inner
+   * activity timeout. lets main.ts tear down shared resources (MCP HTTP
+   * server) so lingering SSE reconnects don't keep the outer timer alive.
+   */
+  onActivityTimeout?: (() => void) | undefined;
+  onToolUse?: ((event: AgentToolUseEvent) => void) | undefined;
+  /**
+   * Per-run token ceiling (OWASP LLM10). Harnesses report their running total
+   * to `observe()` as usage arrives and must stop the run when it returns true
+   * — the activity watchdogs bound idleness, and a runaway loop is never idle.
+   * Absent for call sites with nothing to bound (subagents, tests); use
+   * `unlimitedTokenQuota()` rather than a null check when one is required.
+   */
+  tokenQuota?: RunTokenQuota | undefined;
+  /**
+   * Infraweaver API JWT scoped to this run. agents only need this when they
+   * have to write state back to Infraweaver mid-run (today: opencode.ts uses
+   * it to seed the post-hook's writeback envelope for Codex auth refresh).
+   * empty string when the run wasn't context-resolved (e.g. local dry-runs).
+   */
+  apiToken: string;
+}
+
+export interface Agent {
+  name: AgentId;
+  install: (token?: string) => Promise<string>;
+  run: (ctx: AgentRunContext) => Promise<AgentResult>;
+}
+
+export const agent = (input: Agent): Agent => {
+  return {
+    ...input,
+    run: async (ctx: AgentRunContext): Promise<AgentResult> => {
+      log.debug(`» payload: ${JSON.stringify(ctx.payload, null, 2)}`);
+      return input.run(ctx);
+    },
+  };
+};
+
+/** format a USD cost to 4 decimal places, always showing the leading zero */
+export function formatCostUsd(costUsd: number): string {
+  return costUsd.toFixed(4);
+}
+
+/**
+ * Redirect the sub-agent's HOME / XDG config into the run tmpdir so it never
+ * reads or writes the runner's real home. Both harnesses build this identically
+ * (then `mkdir` under `XDG_CONFIG_HOME` for their provider config).
+ */
+export function agentHomeEnv(tmpdir: string): {
+  HOME: string;
+  XDG_CONFIG_HOME: string;
+} {
+  return { HOME: tmpdir, XDG_CONFIG_HOME: join(tmpdir, ".config") };
+}
+
+/**
+ * The base spawn env every harness starts from: the process env, the tmpdir
+ * HOME/XDG redirect, and `PWD` pinned to the repo dir.
+ *
+ * PWD is load-bearing: opencode (≥1.14) resolves the session `directory` from
+ * `process.env.PWD`, and claude-code (2.1.x) registers `PWD` as a "session"
+ * additional working dir when it differs from `process.cwd()` — so inheriting
+ * the harness's own PWD via `...process.env` would add the wrong dir to the
+ * agent's allowed working set under `pnpm runtest`/`dev:run`. Providers spread
+ * this and layer their own keys (config content, credentials) on top.
+ */
+export function baseAgentEnv(
+  homeEnv: { HOME: string; XDG_CONFIG_HOME: string },
+  repoDir: string,
+): NodeJS.ProcessEnv {
+  return { ...process.env, ...homeEnv, PWD: repoDir };
+}
+
+/**
+ * Normalize a run's raw token/cost components into an {@link AgentUsage}, or
+ * `undefined` when the run produced nothing billable. The single home for the
+ * convention both harnesses previously re-implemented in their `buildUsage`:
+ *   - total `inputTokens` = non-cached input + cache read + cache write
+ *   - a zero cache / cost field collapses to `undefined` (symmetry with
+ *     {@link mergeAgentUsage})
+ *   - all-zero input/output/cost → `undefined` (no empty usage rows)
+ */
+export function buildAgentUsage(parts: {
+  agent: string;
+  /** non-cached input tokens sent this run. */
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  costUsd: number;
+}): AgentUsage | undefined {
+  const inputTokens = parts.input + parts.cacheRead + parts.cacheWrite;
+  if (inputTokens <= 0 && parts.output <= 0 && parts.costUsd <= 0)
+    return undefined;
+  return {
+    agent: parts.agent,
+    inputTokens,
+    outputTokens: parts.output,
+    cacheReadTokens: parts.cacheRead > 0 ? parts.cacheRead : undefined,
+    cacheWriteTokens: parts.cacheWrite > 0 ? parts.cacheWrite : undefined,
+    costUsd: parts.costUsd > 0 ? parts.costUsd : undefined,
+  };
+}
+
+/**
+ * merge two AgentUsage snapshots into one running total.
+ *
+ * both agent harnesses invoke their runner multiple times per `run()` when the
+ * post-run retry loop kicks in (MAX_POST_RUN_RETRIES). each invocation
+ * produces its own AgentUsage; we sum them so downstream callers (usage
+ * summary, WorkflowRun persistence) see the whole session — not just the
+ * final retry's slice.
+ *
+ * returns `undefined` when both sides are empty so callers can short-circuit
+ * without a special case. zero-valued cache / cost fields are dropped to
+ * `undefined` for symmetry with each harness's `buildUsage`.
+ */
+export function mergeAgentUsage(
+  a: AgentUsage | undefined,
+  b: AgentUsage | undefined,
+): AgentUsage | undefined {
+  // always return a fresh object — callers treat AgentUsage as immutable, and
+  // returning `a` / `b` directly would leak that invariant to future callers
+  if (!a && !b) return undefined;
+  if (!a) return { ...(b as AgentUsage) };
+  if (!b) return { ...a };
+  const cacheRead = (a.cacheReadTokens ?? 0) + (b.cacheReadTokens ?? 0);
+  const cacheWrite = (a.cacheWriteTokens ?? 0) + (b.cacheWriteTokens ?? 0);
+  const cost = (a.costUsd ?? 0) + (b.costUsd ?? 0);
+  return {
+    agent: a.agent,
+    inputTokens: a.inputTokens + b.inputTokens,
+    outputTokens: a.outputTokens + b.outputTokens,
+    cacheReadTokens: cacheRead > 0 ? cacheRead : undefined,
+    cacheWriteTokens: cacheWrite > 0 ? cacheWrite : undefined,
+    costUsd: cost > 0 ? cost : undefined,
+  };
+}
+
+/**
+ * unified per-run token table used by every agent harness.
+ *
+ * columns are kept stable across agents and models so downstream log parsers
+ * (scripts/token-usage.ts, cost dashboards) only have to understand one format:
+ *
+ *   Input       non-cached input tokens sent this run
+ *   Cache Read  input tokens served from prompt cache (Anthropic, etc.)
+ *   Cache Write input tokens written to prompt cache this run
+ *   Output      assistant output tokens
+ *   Total       sum of the four columns — the real billable quantity
+ *   Cost ($)    USD cost reported by the provider (only rendered when known)
+ *
+ * models that don't report prompt caching leave Cache Read / Write at 0.
+ * OpenCode emits per-step `part.cost` sourced from models.dev (works across
+ * Anthropic, OpenAI, Google, xAI, DeepSeek, Moonshot, OpenRouter, etc.);
+ * Claude CLI emits `total_cost_usd` on its final `result` event. pass the
+ * accumulated value via `costUsd` to render the Cost column.
+ */
+export function logTokenTable(t: {
+  input: number;
+  cacheRead: number;
+  cacheWrite: number;
+  output: number;
+  costUsd?: number | undefined;
+}): void {
+  const total = t.input + t.cacheRead + t.cacheWrite + t.output;
+  // narrow costUsd to a concrete number so the render path doesn't need a cast
+  const costUsd =
+    typeof t.costUsd === "number" && t.costUsd > 0 ? t.costUsd : undefined;
+
+  const headerRow: Array<{ data: string; header: true }> = [
+    { data: "Input", header: true },
+    { data: "Cache Read", header: true },
+    { data: "Cache Write", header: true },
+    { data: "Output", header: true },
+    { data: "Total", header: true },
+  ];
+  const dataRow: string[] = [
+    String(t.input),
+    String(t.cacheRead),
+    String(t.cacheWrite),
+    String(t.output),
+    String(total),
+  ];
+
+  if (costUsd !== undefined) {
+    headerRow.push({ data: "Cost ($)", header: true });
+    dataRow.push(formatCostUsd(costUsd));
+  }
+
+  log.table([headerRow, dataRow]);
+}

package/src/agents/subagentModels.ts

@@ -0,0 +1,40 @@
+import { modelAliases } from "#app/models";
+
+/**
+ * Derive a cheaper subagent model override from the orchestrator's resolved
+ * model spec.
+ *
+ * This is a pure registry lookup: every alias in `action/models.ts` declares
+ * its own `subagentModel` (alias key in the same provider). At runtime we
+ * reverse-lookup the orchestrator's resolved slug to find the alias that
+ * produced it, follow the `subagentModel` pointer, and return the target
+ * alias's resolve / openRouterResolve depending on which route the
+ * orchestrator was using.
+ *
+ * Returns `{ reviewer: undefined }` when the orchestrator's alias has no
+ * `subagentModel` (e.g. it's already at a sufficiently cheap tier, or its
+ * provider doesn't have a clean cheaper-but-capable sibling). See models.ts
+ * for the wiring + per-provider rationale.
+ */
+export function deriveSubagentModels(orchestratorSpec: string | undefined): {
+  reviewer: string | undefined;
+} {
+  if (!orchestratorSpec) return { reviewer: undefined };
+
+  // Reverse-lookup. The same resolve string appears in only one alias
+  // (within its provider), so first match wins. We track which field
+  // matched (resolve vs openRouterResolve) so we can pick the same field
+  // off the subagent target — keeping the orchestrator's route consistent.
+  for (const source of modelAliases) {
+    const matchedDirect = source.resolve === orchestratorSpec;
+    const matchedOR = source.openRouterResolve === orchestratorSpec;
+    if (!matchedDirect && !matchedOR) continue;
+    if (!source.subagentModel) return { reviewer: undefined };
+    const target = modelAliases.find((a) => a.slug === source.subagentModel);
+    if (!target) return { reviewer: undefined };
+    const reviewer = matchedOR ? target.openRouterResolve : target.resolve;
+    return { reviewer };
+  }
+
+  return { reviewer: undefined };
+}

package/src/agents/tokenQuota.ts

@@ -0,0 +1,203 @@
+/**
+ * Per-run token quota (OWASP **LLM10**, unbounded consumption).
+ *
+ * WHAT WAS ACTUALLY UNBOUNDED. The engine already bounds a run in *time* — an
+ * outer process-output timer, an inner event-silence watchdog, one agent per
+ * run — and Infraweaver Cloud already bounds *spend* per run and per tenant. What
+ * neither bounds is **tokens inside a single, continuously-progressing run**: an
+ * agent that keeps emitting tokens never trips an activity watchdog, because it
+ * is not idle. A hostile repository can steer a remediation loop into exactly
+ * that shape (a fix that re-breaks its own check, a file that always re-scans
+ * dirty), and on a **self-hosted** run there is no Cloud meter watching. Time
+ * says nothing about consumption; this module is the missing bound.
+ *
+ * FAIL-CLOSED, NOT TRUNCATED. When the quota is reached the run STOPS and says
+ * so. It does not quietly finish with whatever it had — a truncated compliance
+ * run that reports as complete is worse than no run, because the output looks
+ * like an assessment and is not one. {@link RunTokenQuota.gap} is the sentence
+ * that goes to the operator, phrased as a coverage gap rather than a crash.
+ *
+ * WHY MONOTONIC-BY-SOURCE. The harnesses do not report deltas. Claude Code
+ * accumulates per-message usage and then *replaces* the running total with the
+ * authoritative figure from the terminal `result` event; opencode sums per-turn
+ * and retries produce a fresh accumulator. Feeding either straight into a `+=`
+ * would double-count. So callers report a running TOTAL under a stable source
+ * key and the quota charges only the increase — correct whether the harness
+ * accumulates, replaces, or restarts, and never decreasing.
+ *
+ * INPUT-ONLY, NEVER `.infraweaver.yml`. This is a safety limit, so it is settable
+ * from the workflow input alone. A quota a pull request could raise in the run
+ * that reviews it would not be a quota — the A.1 lesson, applied at birth (the
+ * same call TC-0.2 made for `tools_network`).
+ */
+
+/**
+ * Thrown (as an abort reason) when a run reaches its token ceiling.
+ *
+ * A distinct class because the retry paths must be able to tell this apart
+ * from a transient provider failure: retrying a run that was stopped for
+ * spending too much is precisely the wrong response, and would double the
+ * consumption the quota exists to bound.
+ */
+export class TokenQuotaExceededError extends Error {
+  readonly code = "TOKEN_QUOTA_EXCEEDED";
+  constructor(message: string) {
+    super(message);
+    this.name = "TokenQuotaExceededError";
+  }
+}
+
+/** True when an unknown error is (or wraps) a token-quota abort. */
+export function isTokenQuotaError(err: unknown): boolean {
+  return err instanceof TokenQuotaExceededError;
+}
+
+/**
+ * Default ceiling on billable tokens for one run.
+ *
+ * Sized to bound a runaway, not to ration real work: a heavy Review over a
+ * large repository lands in the low millions once cache reads are counted, so
+ * this sits roughly an order of magnitude above the worst legitimate run we
+ * expect. A limit tuned close to normal usage would turn a control into an
+ * outage, which is how safety limits get switched off for good.
+ */
+export const DEFAULT_RUN_TOKEN_QUOTA = 10_000_000;
+
+/** The workflow input that overrides {@link DEFAULT_RUN_TOKEN_QUOTA}. */
+export const RUN_TOKEN_QUOTA_INPUT = "max_run_tokens";
+
+/** The four token components a run is charged for. Cache reads are cheap per
+ *  token but they are still work performed on the model's behalf, and a
+ *  runaway loop is visible mostly in cache reads — excluding them would leave
+ *  the loudest signal of the very failure this bounds outside the count. */
+export interface TokenComponents {
+  input?: number | undefined;
+  output?: number | undefined;
+  cacheRead?: number | undefined;
+  cacheWrite?: number | undefined;
+}
+
+/** Sum the components that count against the quota. Negative and non-finite
+ *  values are dropped rather than trusted — the numbers come from a provider
+ *  response, which is not ours. */
+export function billableTokens(t: TokenComponents): number {
+  let total = 0;
+  for (const v of [t.input, t.output, t.cacheRead, t.cacheWrite]) {
+    if (typeof v === "number" && Number.isFinite(v) && v > 0) total += v;
+  }
+  return Math.floor(total);
+}
+
+export interface RunTokenQuota {
+  /** The ceiling, in billable tokens. */
+  readonly limit: number;
+  /** Billable tokens charged so far across every source. */
+  used(): number;
+  /**
+   * Report a source's running TOTAL (not a delta) and return whether the quota
+   * is exhausted as of this observation. `source` must be stable for the life
+   * of one accumulator — an attempt id, not a message id.
+   */
+  observe(source: string, total: TokenComponents | number): boolean;
+  /** True once {@link used} has reached the limit. Latches: a quota cannot
+   *  un-exhaust, so a late-arriving smaller figure can't reopen a stopped run. */
+  exhausted(): boolean;
+  /** The operator-facing sentence. Stable text — the error renderer and the
+   *  tests both key on it. */
+  gap(): string;
+}
+
+/**
+ * A quota that never trips. Returned when the operator sets the input to `0`,
+ * and used by call sites that have no quota to enforce (subagent harnesses,
+ * tests) so they need no null checks.
+ */
+export function unlimitedTokenQuota(): RunTokenQuota {
+  let used = 0;
+  const seen = new Map<string, number>();
+  return {
+    limit: 0,
+    used: () => used,
+    observe(source, total) {
+      const t =
+        typeof total === "number"
+          ? Math.max(0, Math.floor(total))
+          : billableTokens(total);
+      const prev = seen.get(source) ?? 0;
+      if (t > prev) {
+        used += t - prev;
+        seen.set(source, t);
+      }
+      return false;
+    },
+    exhausted: () => false,
+    gap: () => "",
+  };
+}
+
+/**
+ * Create a per-run token quota.
+ *
+ * `limit <= 0` yields {@link unlimitedTokenQuota} — the explicit opt-out, which
+ * an operator has to ask for. There is no accidental path to unlimited.
+ */
+export function createTokenQuota(limit: number): RunTokenQuota {
+  if (!Number.isFinite(limit) || limit <= 0) return unlimitedTokenQuota();
+  const ceiling = Math.floor(limit);
+  let used = 0;
+  let latched = false;
+  const seen = new Map<string, number>();
+  return {
+    limit: ceiling,
+    used: () => used,
+    observe(source, total) {
+      const t =
+        typeof total === "number"
+          ? Math.max(0, Math.floor(total))
+          : billableTokens(total);
+      const prev = seen.get(source) ?? 0;
+      if (t > prev) {
+        used += t - prev;
+        seen.set(source, t);
+      }
+      if (used >= ceiling) latched = true;
+      return latched;
+    },
+    exhausted: () => latched,
+    gap: () =>
+      `run token quota exhausted: ${used.toLocaleString("en-GB")} of ${ceiling.toLocaleString("en-GB")} ` +
+      "billable tokens consumed, so the run was stopped before it finished. Its results are INCOMPLETE " +
+      "and must not be read as a clean assessment — a finding that would have been raised after this " +
+      `point was never looked for. Raise \`${RUN_TOKEN_QUOTA_INPUT}\` if the run legitimately needs more ` +
+      `budget, or set \`${RUN_TOKEN_QUOTA_INPUT}: 0\` to remove the bound entirely. A run that reaches ` +
+      "this limit without finishing is more often a remediation loop that cannot converge (a fix that " +
+      "re-breaks its own check) than a genuinely large repository.",
+  };
+}
+
+/**
+ * Parse the `max_run_tokens` input. A non-negative integer; `0` means unlimited.
+ * Anything unparseable returns undefined so the caller applies the default —
+ * a typo'd limit must not silently become "no limit".
+ *
+ * Deliberately stricter than the other numeric input parsers, which use a bare
+ * `parseInt`. `parseInt("1e6")` is `1` and `parseInt("5.5")` is `5`: for
+ * `max_prs` a prefix-parse is merely surprising, but here it would turn a
+ * plausible-looking limit into a one-token quota that aborts every run at the
+ * first message. Underscore separators are accepted because a limit of
+ * `10_000_000` is far easier to read — and to get right — than `10000000`.
+ */
+export function parseRunTokenQuota(
+  raw: string | undefined,
+): number | undefined {
+  if (raw === undefined) return undefined;
+  const trimmed = raw.trim().replace(/_/g, "");
+  if (!/^\d+$/.test(trimmed)) return undefined;
+  const n = Number.parseInt(trimmed, 10);
+  return Number.isSafeInteger(n) ? n : undefined;
+}
+
+/** Resolve the effective limit from the parsed input, applying the default. */
+export function resolveRunTokenQuota(parsed: number | undefined): number {
+  return parsed === undefined ? DEFAULT_RUN_TOKEN_QUOTA : parsed;
+}