infraweaver 0.1.0

package/dist/utils/proxyModel.d.ts

@@ -0,0 +1,76 @@
+import type { Agent } from "#app/agents/index";
+import type { ModelGateResult } from "#app/utils/agent";
+import { apiFetch } from "#app/utils/apiFetch";
+import type { AccountPlan } from "#app/utils/runContext";
+/** A resolved model decision plus the env patch (if any) the caller must apply to
+ *  route the run. `envToApply` is set only when the managed proxy engaged. */
+export type RoutedModel = ModelGateResult & {
+    envToApply?: Record<string, string>;
+};
+export type ProxyMintResult = {
+    ok: true;
+    token: string;
+    endpoint: string;
+} | {
+    ok: false;
+    reason: "requires_card" | "requires_upgrade" | "unconfigured" | "transient";
+};
+/**
+ * The proxy `endpoint` becomes `ANTHROPIC_BASE_URL` and receives the bearer on every
+ * model call, so it must be a well-formed **https** URL — never cleartext. It comes
+ * from the authenticated Cloud (not directly attacker-controlled), but a
+ * compromised/misconfigured Cloud response could otherwise redirect the proxy token.
+ * Operators can additionally pin exact hosts via `INFRAWEAVER_MODEL_PROXY_ALLOWED_HOSTS`
+ * (comma-separated); unset = trust any https host the Cloud returns.
+ */
+export declare function isSafeProxyEndpoint(endpoint: string): boolean;
+/** Classify a `/api/proxy-token` response. Pure given the status + parsed body
+ *  (aside from the optional `INFRAWEAVER_MODEL_PROXY_ALLOWED_HOSTS` host pin). */
+export declare function classifyProxyMint(status: number, body: {
+    token?: unknown;
+    endpoint?: unknown;
+} | null): ProxyMintResult;
+/** The env that points the Anthropic-compatible harness at the managed proxy. Pure. */
+export declare function managedProxyEnv(token: string, endpoint: string): Record<string, string>;
+/** Apply a model-routing env patch to the process. The one place env is mutated, and
+ *  the caller does it explicitly with a value it can see (no hidden side effect). */
+export declare function applyModelEnv(env: Record<string, string>): void;
+/** Mint a managed-model proxy token from the Cloud. Never throws — network/parse
+ *  failures classify as `transient` so the caller can fall back to the free model. */
+export declare function mintProxyToken(opts: {
+    credential: string;
+    model?: string | undefined;
+    fetchImpl?: typeof apiFetch;
+}): Promise<ProxyMintResult>;
+/** The mint seam `applyManagedProxy` / `resolveRunModel` accept for tests. */
+export type ProxyMint = typeof mintProxyToken;
+/**
+ * The model the managed EU Bedrock proxy should serve for this run. The managed
+ * gateway is Anthropic-on-Bedrock, and unlike a BYOK key it can serve the whole
+ * Claude family — including Claude Fable, which the BYOK catalog deprecates to Opus
+ * (many BYOK Anthropic keys can't invoke Fable). So for an `anthropic/*` selection
+ * we mint for the slug's *undeprecated* resolve (e.g. `anthropic/claude-fable`
+ * stays Fable) rather than the fallback-collapsed model the BYOK gate produced.
+ * Non-Anthropic selections keep the gate's resolved model (the proxy maps anything
+ * else to its default Claude model anyway). Returns undefined when there is no
+ * usable Anthropic override, so the caller keeps `gate.fallback.from`.
+ */
+export declare function managedProxyModel(slug: string | undefined): string | undefined;
+/**
+ * Overlay the managed proxy onto a model gate. A no-op (returns the gate unchanged)
+ * unless the free fallback engaged (no BYO key) AND the org is on PAYG. On a
+ * successful mint it routes the originally-requested model through the proxy and sets
+ * `envToApply`; a `requires_card` mint surfaces a `BillingError`;
+ * `unconfigured`/`transient` keep the free fallback the gate already chose.
+ */
+export declare function applyManagedProxy(input: {
+    gate: ModelGateResult;
+    plan: AccountPlan;
+    credential: string;
+    resolveAgent: (ctx: {
+        model?: string | undefined;
+    }) => Agent;
+    /** the originally-requested model slug (before BYOK fallback), when known */
+    slug?: string | undefined;
+    mint?: ProxyMint;
+}): Promise<RoutedModel>;

package/dist/utils/rangeDiff.d.ts

@@ -0,0 +1,51 @@
+type ComputeIncrementalDiffParams = {
+    baseBranch: string;
+    beforeSha: string;
+    headSha: string;
+};
+/**
+ * computes the incremental diff between two versions of a PR using range-diff
+ * on virtual squash commits created via `git commit-tree`.
+ *
+ * each PR version is squashed into a single synthetic commit (merge-base → tip tree),
+ * then range-diff compares those two single-commit ranges. this:
+ * - isolates each version's net effect (base branch noise eliminated via per-version merge bases)
+ * - avoids commit-matching issues that raw range-diff has with rebases/squashes/reordering
+ * - creates only loose git objects, no branches or refs (unlike temp-branch squash approaches)
+ *
+ * unlike fetchAndFormatPrDiff/formatFilesWithLineNumbers, this output has no line numbers.
+ * range-diff compares *patches* (diffs-of-diffs), not file trees — its hunk headers are
+ * `@@ file.ts` breadcrumbs, not positional `@@ -X,Y +A,B @@` markers. reconstructing
+ * line numbers would require cross-referencing with the v2 diff or content-matching against
+ * file trees, both of which are fragile (duplicate lines, hunk boundary shifts after rebase).
+ * a structured interdiff approach (diff two parsed patches, compare only +/- keys via Myers)
+ * could approximate line numbers but loses semantic precision: range-diff understands patch
+ * structure natively (rename detection, hunk-aware matching, dual-prefix inner/outer changes),
+ * while flat key-sequence comparison can misalign duplicate lines and can't distinguish
+ * "new addition to the PR" from "existing code newly modified by the PR". range-diff is the
+ * right abstraction here — the incremental diff answers "how did the changeset evolve?",
+ * not "where in the file is this?", and forcing positional line numbers onto it would be
+ * semantically misleading.
+ *
+ * alternatives considered:
+ * - plain git diff (two-tree or three-dot): includes base branch changes, no PR isolation
+ * - patch-text diffing (interdiff / diff-of-diffs): fragile, hunk offset noise on rebase
+ * - range-diff on raw commit ranges: confused by commit reorganization across force-pushes
+ */
+export declare function computeIncrementalDiff(params: ComputeIncrementalDiffParams): string | null;
+/**
+ * transforms git range-diff output into a clean incremental diff.
+ *
+ * range-diff content lines have two prefix characters:
+ *   1st (outer): range-diff level — space (same in both), + (new only), - (old only)
+ *   2nd (inner): original diff level — space (context), + (added), - (removed)
+ *
+ * stripping the inner prefix produces a standard unified-diff-like output where
+ * +/- means "changed between PR versions" rather than "changed vs base branch".
+ *
+ * uses a streaming approach: a ring buffer of before-context lines is flushed when
+ * a change is hit, then afterCount lines of after-context are emitted directly.
+ * nearest preceding ## / @@ headers are force-included when outside the context window.
+ */
+export declare function postProcessRangeDiff(raw: string, contextLines?: number): string | null;
+export {};

package/dist/utils/redact.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Sink-independent secret redaction for log output.
+ *
+ * `core.setSecret()` only masks on the GitHub `actions` log sink. Every stdio MCP
+ * server runs with `setLogSink("stderr")` (stdout is the JSON-RPC channel there) and
+ * local dev prints to the console — neither is masked. So a stray `log.debug(env)`,
+ * an error that stringifies a request, or any line that merely contains a bearer would
+ * print it in cleartext on those sinks. This scrubs secret-shaped substrings from an
+ * already-formatted log line BEFORE it reaches any sink, so redaction no longer depends
+ * on which sink is active (it complements `core.setSecret`, it doesn't replace it).
+ *
+ * Two layers, applied in order:
+ *  1. Registered literals — exact values handed to {@link registerSecret} (e.g. the
+ *     minted managed-proxy token). Caught even when their shape is unusual.
+ *  2. Shape patterns — known token formats (`tmnd_`/`tmpx_` org + proxy tokens, the
+ *     GitHub `ghp_`/`gho_`/`ghu_`/`ghs_`/`ghr_` family + fine-grained PATs, Anthropic
+ *     keys, AWS access-key ids, `Bearer …` headers) plus any JSON property whose NAME
+ *     matches the sensitive-env patterns (reuses {@link isSensitiveEnvName}, so an
+ *     `{"GITHUB_TOKEN":"…"}` env dump is masked by key even if the value shape is novel).
+ */
+/**
+ * Register a literal secret value for sink-independent log redaction. Safe to call with
+ * any string; values under 8 chars are ignored so we never scrub a common substring.
+ * Complements `core.setSecret` (call both) — this one also masks on stderr/local sinks.
+ */
+export declare function registerSecret(value: string | undefined | null): void;
+/** Test-only: clear the literal registry between cases. */
+export declare function _resetRegisteredSecrets(): void;
+/**
+ * Redact secret-shaped substrings from an already-formatted log line. Idempotent,
+ * allocation-light on the common (no-secret) path, and never throws.
+ */
+export declare function redactSecrets(text: string): string;

package/dist/utils/registryAuth.d.ts

@@ -0,0 +1,52 @@
+/** the HCP Terraform / private-registry host a `registry_token` defaults to. */
+export declare const DEFAULT_REGISTRY_HOST = "app.terraform.io";
+/**
+ * The `TF_TOKEN_<host>` env-var NAME for a registry host, per Terraform's encoding:
+ * lower-cased, each `.` → `_`, each `-` → `__`. The two replacements operate on
+ * disjoint characters, so order is immaterial. Pure.
+ */
+export declare function registryTokenEnvName(host: string): string;
+/**
+ * Parse the `registry_host` input (newline/comma-separated) into the hosts a
+ * registry token authorises. Blank/whitespace entries are dropped and hosts are
+ * de-duplicated case-insensitively. Falls back to the HCP host when none is given —
+ * the overwhelmingly common private-registry target — so supplying just a token works.
+ */
+export declare function registryHosts(raw?: string | undefined): string[];
+/**
+ * Build the `TF_TOKEN_<host>=<token>` env that authorises `terraform init` to fetch
+ * a private-registry module for each host. Pure (token + hosts in, env out) so it is
+ * unit-testable without a real terraform. The token only ever lands in a VALUE, never
+ * a key. Returns `{}` for a blank token or no usable host.
+ */
+export declare function buildRegistryTokenEnv(token: string, hosts: string[]): Record<string, string>;
+/**
+ * Resolve the registry-token env for a run, or undefined when no `registry_token`
+ * was supplied (the common public-registry/local case). Mirrors
+ * `resolveModuleFetchEnv` so the scan/verify/plan/refactor paths treat both
+ * credentials identically. The token authorises the hosts named in `registryHost`
+ * (default: the HCP host).
+ */
+export declare function resolveRegistryTokenEnv(payload: {
+    registryToken?: string | undefined;
+    registryHost?: string | undefined;
+}): Record<string, string> | undefined;
+/**
+ * The full extra-env a terraform subprocess needs to FETCH private modules: the
+ * git-transport credential for cross-repo `git::` modules (moduleFetch.ts) merged
+ * with the registry-protocol token for private-registry modules (this file). The two
+ * key namespaces (`GIT_CONFIG_*` / `GIT_SSH_COMMAND` vs `TF_TOKEN_*`) never collide.
+ * Both are scoped to the subprocess and never persisted. Returns undefined when
+ * neither is configured (the common public/local-module case). This is the single
+ * resolver the scan / verify / plan / equivalence-check paths call so they treat both
+ * credentials alike.
+ */
+export declare function resolveModuleCredentialEnv(payload: {
+    moduleFetchToken?: string | undefined;
+    moduleFetchSshKey?: string | undefined;
+    registryToken?: string | undefined;
+    registryHost?: string | undefined;
+}, opts?: {
+    sshKeyDir?: string;
+    writeKey?: (path: string, contents: string) => void;
+}): Record<string, string> | undefined;

package/dist/utils/remediationCommand.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Comment-command interface. A developer can scope a remediation run from
+ * a PR/issue comment that mentions the bot:
+ *
+ *   @infraweaver fix #3a9f1c2          → fix exactly one concern (by id or short id)
+ *   @infraweaver fix all high-severity → fix every concern at/above a severity
+ *   @infraweaver fix all               → fix everything (still bounded by max_prs)
+ *   @infraweaver fix main.tf           → fix one file's group
+ *
+ * Propose, then let me steer — when a non-trivial finding has several
+ * genuinely distinct valid fixes, Remediate proposes 2–3 labelled strategies in
+ * a comment instead of guessing, and the reviewer picks one by replying:
+ *
+ *   @infraweaver fix #3a9f1c2 with strategy B   → apply strategy B to that concern
+ *   @infraweaver strategy 2                      → pick strategy 2 (concern from the thread)
+ *
+ * The parsing is pure + deterministic so the scoping doesn't depend on the
+ * model's reading of the comment. The Remediate mode applies the parsed scope
+ * (which group(s) to act on, and which strategy) instead of the default
+ * "highest-severity group, agent's-choice fix".
+ */
+export type RemediationCommand = {
+    kind: "concern";
+    concernRef: string;
+    strategy?: string;
+} | {
+    kind: "severity";
+    severity: Severity;
+} | {
+    kind: "file";
+    file: string;
+} | {
+    kind: "rule";
+    ruleId: string;
+} | {
+    kind: "strategy";
+    strategy: string;
+} | {
+    kind: "all";
+};
+declare const SEVERITIES: readonly ["critical", "high", "medium", "low", "info"];
+type Severity = (typeof SEVERITIES)[number];
+/**
+ * the canonical phrasing the proposal comment must tell reviewers to reply
+ * with. Lives next to the parser that accepts it so the proposal template (in
+ * the Remediate prompt) and the parser can never drift apart. `<concern-id>` and
+ * `<A|B|C>` are placeholders the agent fills with the real id and the offered
+ * strategy labels.
+ */
+export declare const STRATEGY_REPLY_HINT = "@infraweaver fix #<concern-id> with strategy <A|B|C>";
+/**
+ * Parse a `@infraweaver fix …` command out of a comment body. Returns null when
+ * the body isn't a recognised fix command (the run then falls back to its
+ * default scope). Tolerant of surrounding prose — it scans for the mention then
+ * the `fix` verb and its argument.
+ */
+export declare function parseRemediationCommand(body: string | undefined): RemediationCommand | null;
+export {};

package/dist/utils/retry.d.ts

@@ -0,0 +1,38 @@
+/** Default upper bound on a honored server Retry-After hint (ms). A hostile or
+ *  buggy `Retry-After` could otherwise stall a run for its full value (GitHub
+ *  secondary-rate-limit responses have carried multi-minute hints); 20s matches
+ *  octokit's throttling-plugin ceiling. */
+export declare const DEFAULT_RETRY_AFTER_CAP_MS = 20000;
+export type RetryOptions = {
+    maxAttempts?: number;
+    delayMs?: number;
+    /**
+     * explicit delay schedule — one entry per retry (length N ⇒ N+1 attempts).
+     * when set, overrides `maxAttempts` and `delayMs`. e.g. `[1_000, 3_000]`
+     * means up to 3 attempts, sleeping 1s before retry 2 and 3s before retry 3.
+     */
+    delaysMs?: readonly number[];
+    shouldRetry?: (error: unknown) => boolean;
+    /** cap (ms) on a honored server Retry-After / rate-limit-reset hint. default
+     *  {@link DEFAULT_RETRY_AFTER_CAP_MS}. The fixed backoff is never capped —
+     *  this only bounds how long a *server-suggested* delay can extend it. */
+    retryAfterCapMs?: number;
+    label?: string;
+};
+/**
+ * A broad transient predicate for octokit/GitHub calls: an HTTP 5xx (an upstream
+ * blip) OR a network-class error. Distinct from a deterministic 4xx (404/401/403/
+ * 422), which fails fast. Pass as `shouldRetry` for idempotent GitHub reads/
+ * dispatches whose client carries no 5xx retry of its own (mirrors pullfrog's
+ * `isTransientOctokitError`). see #999/#997.
+ */
+export declare function isTransientServerError(error: unknown): boolean;
+/**
+ * Parse an HTTP `Retry-After` header value into milliseconds. Accepts the two
+ * RFC-9110 forms — delta-seconds (`"120"`) and an HTTP-date (`"Wed, 21 Oct 2026
+ * 07:28:00 GMT"`) — and returns `undefined` for anything else. Callers that hold
+ * the `Response` attach the result as `retryAfterMs` on the thrown error so
+ * {@link retry} can floor its backoff to it.
+ */
+export declare function parseRetryAfter(value: string | null | undefined): number | undefined;
+export declare function retry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;

package/dist/utils/reviewCleanup.d.ts

@@ -0,0 +1,14 @@
+import type { ToolContext } from "#app/mcp/server";
+/**
+ * post-agent review lifecycle: runs after the agent exits (success or timeout).
+ *
+ * normally the agent handles new commits inline: create_pull_request_review
+ * detects HEAD movement and tells the agent to pull and review the delta.
+ * this dispatch is a safety net for cases where the agent couldn't handle
+ * it (timeout, error, etc).
+ *
+ * ordering matters: reportReviewNodeId marks this run "done" FIRST so push
+ * webhooks stop being suppressed by dedup. the HEAD check runs SECOND to
+ * catch any pushes that were suppressed while this run was in-flight.
+ */
+export declare function postReviewCleanup(ctx: ToolContext): Promise<void>;

package/dist/utils/run.d.ts

@@ -0,0 +1,9 @@
+import type { AgentResult } from "#app/agents/shared";
+import type { MainResult } from "#app/main";
+import type { ToolContext } from "#app/mcp/server";
+export interface HandleAgentResultParams {
+    result: AgentResult;
+    toolContext: ToolContext;
+    silent: boolean | undefined;
+}
+export declare function handleAgentResult(ctx: HandleAgentResultParams): Promise<MainResult>;

package/dist/utils/runContext.d.ts

@@ -0,0 +1,112 @@
+import type { PushPermission, ShellPermission } from "#app/external";
+import type { RepoContext } from "#app/utils/github";
+export interface Mode {
+    id: string;
+    name: string;
+    description: string;
+    prompt: string;
+}
+/**
+ * server-parsed TOC entry for `Repo.learnings`. depth is 1-6 (h1-h6),
+ * line numbers are 1-indexed against the raw body. computed by
+ * `parseLearningsHeadings` in `utils/learningsToc.ts` (server side) and
+ * shipped over the run-context JSON boundary; the canonical declaration
+ * lives there. duplicated here because the action runtime can't reach
+ * across into the proprietary root-level codebase, and the JSON wire
+ * means typecheck can't enforce shape equality across both sides.
+ */
+export interface LearningsHeading {
+    depth: 1 | 2 | 3 | 4 | 5 | 6;
+    title: string;
+    startLine: number;
+    endLine: number;
+}
+export interface RepoSettings {
+    model: string | null;
+    modes: Mode[];
+    setupScript: string | null;
+    postCheckoutScript: string | null;
+    prepushScript: string | null;
+    stopScript: string | null;
+    push: PushPermission;
+    shell: ShellPermission;
+    prApproveEnabled: boolean;
+    modeInstructions: Record<string, string>;
+    learnings: string | null;
+    learningsHeadings: LearningsHeading[];
+    envAllowlist: string | null;
+}
+/**
+ * Account-level billing plan. Orthogonal to repo-level OSS status. Mirrors
+ * the server's `AccountPlan` in `utils/billing.ts`. `"none"` = free tier,
+ * `"payg"` = card on file / pay-as-you-go.
+ */
+export type AccountPlan = "none" | "payg";
+/**
+ * Cloud-managed module credentials for this repo, entered once in the dashboard's
+ * Refactor dialog and sealed at rest. Delivered over the authenticated, repo-scoped
+ * run-context call (never the GitHub `repository_dispatch` payload). Used by the
+ * engine only as a FALLBACK for the matching action inputs — an explicit
+ * `module_fetch_token` / `registry_token` input always wins. Both fields optional;
+ * absent on OSS / unmanaged runs or when none were stored.
+ */
+export interface ModuleCredentials {
+    /** read-only PAT for a private cross-repo `git::` module (refactor b.1). */
+    moduleFetchToken?: string;
+    /** bearer token for a private Terraform registry module (refactor b.4). */
+    registryToken?: string;
+}
+export interface RunContext {
+    settings: RepoSettings;
+    apiToken: string;
+    oss: boolean;
+    plan: AccountPlan;
+    /**
+     * The maintained-pack control ids this run's ORG marked MANDATORY in the Cloud
+     * dashboard (the "required controls" policy). Org-scoped by construction — the
+     * run-context call is authenticated to exactly one org + repo, so a run only
+     * ever receives its own org's policy. Merged into the gate's `required_controls`
+     * so an open finding on any of these fails CI regardless of severity. `[]` for
+     * OSS / unmanaged runs.
+     */
+    requiredControls: string[];
+    /** §5.12 the org's proven-fix library — patterns (finding-type → proven
+     *  transformation) captured from prior `✗→✓` proofs across the org's fleet,
+     *  served so this run can offer them as priors for matching finding-types. An
+     *  untrusted blob coerced engine-side (utils/fixMemory `coerceLibrary`). `[]`
+     *  for OSS / unentitled / unconfigured runs. */
+    provenFixes: unknown[];
+    /** G7 the org's fleet-wide dismissal record — which rules this org has waived,
+     *  across how many DISTINCT repos, with the reasons given. A SURFACING signal
+     *  only: it reorders the low-severity tail and can neither suppress a finding
+     *  nor change a verdict (see `terraform/noiseProfile`). An untrusted blob
+     *  coerced engine-side, same posture as {@link RunContext.provenFixes}. `[]`
+     *  for OSS / unentitled / unconfigured runs. */
+    noiseProfile: unknown[];
+    /** TC-2.2 the org's fleet-wide record of provider-upgrade transforms that have
+     *  already planned cleanly elsewhere — counters keyed by transform id, never
+     *  another repo's configuration. Annotates a detected transform with how widely
+     *  it has been proven. An untrusted blob coerced engine-side, same posture as
+     *  {@link RunContext.provenFixes}. `[]` for OSS / unentitled / unconfigured runs. */
+    provenTransforms: unknown[];
+    /** Cloud-managed module credentials (see {@link ModuleCredentials}); undefined
+     *  when none are stored for this repo. */
+    moduleCredentials?: ModuleCredentials;
+}
+/** Coerce the untrusted run-context `moduleCredentials` blob into the typed shape,
+ *  keeping only non-empty string values. Returns undefined when nothing usable is
+ *  present (so the engine treats it as "no managed credentials"). */
+export declare function parseModuleCredentials(raw: {
+    moduleFetchToken?: unknown;
+    registryToken?: unknown;
+} | undefined): ModuleCredentials | undefined;
+/**
+ * fetch run context from Infraweaver API
+ * returns settings + API token for subsequent calls
+ * returns defaults if fetch fails (warns when a backend was configured)
+ */
+export declare function fetchRunContext(params: {
+    token: string;
+    repoContext: RepoContext;
+    oidcToken?: string | undefined;
+}): Promise<RunContext>;

package/dist/utils/runContextData.d.ts

@@ -0,0 +1,42 @@
+import type { Octokit } from "@octokit/rest";
+import { type OctokitWithPlugins } from "#app/utils/github";
+import { type AccountPlan, type ModuleCredentials, type RepoSettings } from "#app/utils/runContext";
+export interface RunContextData {
+    repo: {
+        owner: string;
+        name: string;
+        data: Awaited<ReturnType<Octokit["repos"]["get"]>>["data"];
+    };
+    repoSettings: RepoSettings;
+    apiToken: string;
+    oss: boolean;
+    plan: AccountPlan;
+    /** The org's mandatory crosswalk-pack control ids (Cloud "required controls"
+     *  policy), org-scoped via the authenticated run-context. Merged into the gate. */
+    requiredControls: string[];
+    /** §5.12 the org's proven-fix library (untrusted blob; coerced engine-side).
+     *  `[]` for OSS / unentitled runs. */
+    provenFixes: unknown[];
+    /** TC-2.2 the org's proven provider-upgrade transforms (untrusted blob;
+     *  coerced engine-side). Counters only — never another repo's configuration.
+     *  `[]` for OSS / unentitled runs. */
+    provenTransforms: unknown[];
+    /** G7 the org's fleet-wide dismissal record (untrusted blob; coerced
+     *  engine-side). Reorders surfacing only — never suppresses. `[]` for OSS /
+     *  unentitled runs. */
+    noiseProfile: unknown[];
+    /** Cloud-managed module credentials for this repo (a read-only module-repo PAT /
+     *  a private-registry token), entered in the dashboard's Refactor dialog. A
+     *  fallback for the matching action inputs; an explicit input still wins.
+     *  undefined when none are stored. */
+    moduleCredentials?: ModuleCredentials;
+}
+interface ResolveRunContextDataParams {
+    octokit: OctokitWithPlugins;
+    token: string;
+}
+/**
+ * initialize run context data: parse context, fetch repo info and settings
+ */
+export declare function resolveRunContextData(params: ResolveRunContextDataParams): Promise<RunContextData>;
+export {};

package/dist/utils/runErrorRenderer.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Classify + render the error thrown out of the main run try-block into a
+ * pair of user-facing markdown bodies — one for the GitHub Actions job
+ * summary tab, one for the PR progress comment.
+ *
+ * Classifications, in dispatch order (first match wins; the api-key
+ * branch additionally folds in the activity-timeout hang body as a
+ * sub-source so a hang masking an api-key error still surfaces the api-key
+ * CTA):
+ *
+ *   1. `BillingError` — either the proxy-token mint already threw one (402
+ *      handled inline) or the agent runtime surfaced an OpenRouter
+ *      "key budget exhausted" string mid-run. Both render via
+ *      `formatBillingErrorSummary` so the user sees actionable copy.
+ *
+ *   2. BYOK provider billing-exhausted (#835) — DeepSeek "Insufficient
+ *      Balance", Anthropic "credit balance is too low", OpenCode Zen
+ *      `CreditsError`, Gemini "spending cap". Checked before api-key auth
+ *      because billing-exhausted responses often carry 401 status codes
+ *      that `isApiKeyAuthError` would otherwise mis-classify.
+ *
+ *   3. API-key auth error — `isApiKeyAuthError` sniffs the raw error string
+ *      (or the activity-timeout hang body when present, since that's where
+ *      the underlying provider error often lands); `formatApiKeyErrorSummary`
+ *      renders provider + console-link copy.
+ *
+ *   4. ProviderModelNotFoundError — stale free-fallback model id no longer
+ *      in the OpenCode catalog; renders a nudge to add a BYOK key.
+ *
+ *   5. Activity-timeout hang — `errorMessage` starts with
+ *      `"activity timeout"` or `"agent still pending"` AND none of the
+ *      above matched. The harness keeps structured diagnostic state on
+ *      `toolState.agentDiagnostic`; `formatAgentHangBody` renders that into
+ *      the job summary. The PR comment instead collapses to a one-line
+ *      `**Run failed.** [View the logs →]` — the watchdog jargon, event
+ *      counts, and benign stderr tail are operator-grade detail that only
+ *      alarm the average user. The one exception is a hang masking billing
+ *      exhaustion (#778), where `formatAgentHangBody` emits an actionable
+ *      top-up CTA that the comment keeps verbatim.
+ *
+ *   6. Default — the job summary gets a plain-English lead sentence plus the
+ *      raw error in a fenced code block under the `### ❌ Infraweaver failed`
+ *      banner; the PR comment collapses to the same one-line logs link as
+ *      the hang case, since the raw internal string helps nobody on the PR.
+ *
+ * Net: the actionable classifications (billing, API-key, model-not-found)
+ * render identical bodies on both surfaces; the non-actionable ones (hang,
+ * generic) keep the forensics in the Actions job summary and show a calm
+ * one-liner in the PR comment, whose footer already carries Infraweaver
+ * branding + rerun links.
+ */
+import type { AgentDiagnostic } from "#app/utils/agentHangReport";
+export type RenderedRunError = {
+    summary: string;
+    comment: string;
+};
+export declare function renderRunError(input: {
+    errorMessage: string;
+    repo: {
+        owner: string;
+        name: string;
+    };
+    agentDiagnostic: AgentDiagnostic | undefined;
+}): RenderedRunError;

package/dist/utils/runLifecycle.d.ts

@@ -0,0 +1,89 @@
+/**
+ * End-of-run cleanup phases extracted out of `main.ts`. Three shapes:
+ *
+ *   - `persistRunArtifacts`: best-effort post-review cleanup + summary +
+ *     learnings persistence. Shared by both the success path and the
+ *     error-catch path; idempotent (each step has its own guard against
+ *     double-execution).
+ *
+ *   - `finalizeSuccessRun`: success-only — calls `persistRunArtifacts`
+ *     first, then surfaces harness-side failures in the progress comment,
+ *     deletes stranded progress comments, writes the GitHub Actions job
+ *     summary, and emits the structured output marker.
+ *
+ *   - `writeRunErrorOutputs`: error-only — writes the rendered error
+ *     summary to the Actions summary tab and mirrors it to the PR
+ *     progress comment. The catch path calls this and then
+ *     `persistRunArtifacts` separately so the rendered error lands before
+ *     the persistence calls, in case the latter throw.
+ *
+ * All three swallow their own non-fatal errors (`log.debug` or empty
+ * `catch {}`) so a cleanup failure can't flip an already-decided run
+ * outcome.
+ */
+import type { AgentResult } from "#app/agents/shared";
+import type { ToolContext } from "#app/mcp/server";
+import type { ToolState } from "#app/toolState";
+import { type RenderedRunError } from "#app/utils/runErrorRenderer";
+/**
+ * Best-effort cleanup shared by both run-end paths:
+ *   1. post-review cleanup (dispatch follow-up re-review on submitted reviews)
+ *   2. persist the agent-edited PR summary tmpfile
+ *   3. persist the agent-edited repo-level learnings tmpfile
+ *
+ * Each step is idempotent and swallows its own errors. Safe to call from
+ * both `main()`'s success path and its catch path.
+ */
+export declare function persistRunArtifacts(toolContext: ToolContext): Promise<void>;
+/**
+ * Run the success-path cleanup waterfall:
+ *
+ *   1. shared best-effort cleanup via `persistRunArtifacts`
+ *   2. when the harness returned `success=false` (e.g. unsubmitted-review
+ *      gate exhausted retries, stop-hook persistently failing), render via
+ *      `renderRunError` and surface the error in BOTH the progress comment
+ *      (rendered.comment) and the Actions job summary (rendered.summary,
+ *      prepended below in step 4) — same classifier as the catch path so
+ *      the user sees it instead of a deleted-comment void / empty summary
+ *      tab
+ *   3. when the run succeeded, some write landed (`wasUpdated`), but the
+ *      progress comment was never finalized via `report_progress`, delete
+ *      the stranded comment (abandoned checklist, or a substantive artifact
+ *      written via another MCP write tool that skipped report_progress). a
+ *      run where NO write landed keeps its comment for handleAgentResult to
+ *      salvage into — see the `wasUpdated` guard below and #868
+ *   4. write the GitHub Actions step summary (best-effort — a write
+ *      failure must not throw past this point because we'd hit the outer
+ *      catch and clobber any progress comment we just wrote)
+ *   5. emit the structured output marker for tests + workflow consumers
+ */
+export declare function finalizeSuccessRun(input: {
+    toolContext: ToolContext;
+    toolState: ToolState;
+    result: AgentResult;
+    repo: {
+        owner: string;
+        name: string;
+    };
+    /** Infraweaver Cloud org token (the `api_token` input). When set, the run's
+     *  findings/posture are reported to Cloud (best-effort). */
+    cloudApiToken?: string | undefined;
+}): Promise<void>;
+/**
+ * Write the rendered error to the GitHub Actions job summary tab + mirror
+ * to the PR progress comment when one exists. Catch path only.
+ *
+ * `lastProgressBody` and the usage table are appended to the summary so the
+ * partial work the agent did before failing isn't lost.
+ *
+ * `createIfMissing: true` is symmetric with `finalizeSuccessRun` — silent
+ * triggers (IncrementalReview / pull_request_synchronize / auto-label) that
+ * throw past `finalizeSuccessRun` (e.g. timeout race kills the agent
+ * mid-billing-exhausted-retry) reach this catch path with no progress
+ * comment to update, and without `createIfMissing` the terminal error
+ * lands only in the GH job summary that most users never open. see #835.
+ */
+export declare function writeRunErrorOutputs(input: {
+    rendered: RenderedRunError;
+    toolState: ToolState;
+}): Promise<void>;