infraweaver 0.1.0

package/dist/mcp/reviewComments.d.ts

@@ -0,0 +1,245 @@
+import type { Octokit } from "@octokit/rest";
+import type { GitHubToolContext } from "#app/mcp/capabilityContext";
+/**
+ * A GraphQL review-thread fetch worth retrying: an HTTP 5xx / network blip
+ * ({@link isTransientServerError}), OR GitHub's transient "Something went wrong
+ * while executing your query" — which surfaces both as an HTTP-200
+ * `GraphqlResponseError` (message only) and as an HTTP-502 `RequestError`. A
+ * blip here would otherwise drop a whole review delivery. Deterministic GraphQL
+ * validation errors (bad query, unknown field) don't match and fail fast. #997.
+ */
+export declare function isTransientGraphqlError(error: unknown): boolean;
+export declare const REVIEW_THREADS_QUERY = "\nquery ($owner: String!, $name: String!, $prNumber: Int!) {\n  repository(owner: $owner, name: $name) {\n    pullRequest(number: $prNumber) {\n      reviewThreads(first: 100) {\n        nodes {\n          id\n          path\n          line\n          startLine\n          diffSide\n          isResolved\n          isOutdated\n          comments(first: 50) {\n            nodes {\n              fullDatabaseId\n              body\n              bodyHTML\n              createdAt\n              diffHunk\n              line\n              startLine\n              originalLine\n              originalStartLine\n              author { login }\n              pullRequestReview {\n                databaseId\n                author { login }\n              }\n              reactionGroups {\n                content\n                reactors(first: 10) {\n                  totalCount\n                  nodes {\n                    ... on Actor { login }\n                  }\n                }\n              }\n            }\n          }\n        }\n      }\n    }\n  }\n}\n";
+/**
+ * Lightweight PAGINATED query for the approval gate. It fetches only each
+ * thread's resolved state and its ROOT author (oldest comment, hence
+ * `comments(first: 1)`) — everything {@link countOutstandingInfraweaverThreads}
+ * needs and nothing more. Distinct from {@link REVIEW_THREADS_QUERY} (a single
+ * `first: 100` page with full comment bodies) precisely because the invariant
+ * must hold on PRs with more than 100 threads: a silent first-page cap would let
+ * a finding beyond thread #100 slip an approval through.
+ */
+export declare const OUTSTANDING_THREADS_QUERY = "\nquery ($owner: String!, $name: String!, $prNumber: Int!, $cursor: String) {\n  repository(owner: $owner, name: $name) {\n    pullRequest(number: $prNumber) {\n      reviewThreads(first: 100, after: $cursor) {\n        pageInfo { hasNextPage endCursor }\n        nodes {\n          isResolved\n          comments(first: 1) { nodes { author { login } } }\n        }\n      }\n    }\n  }\n}\n";
+export type OutstandingThreadsResponse = {
+    repository: {
+        pullRequest: {
+            reviewThreads: {
+                pageInfo: {
+                    hasNextPage: boolean;
+                    endCursor: string | null;
+                };
+                nodes: ({
+                    isResolved: boolean;
+                    comments: {
+                        nodes: ({
+                            author: {
+                                login: string;
+                            } | null;
+                        } | null)[] | null;
+                    } | null;
+                } | null)[] | null;
+            } | null;
+        } | null;
+    } | null;
+};
+/**
+ * Count unresolved review threads on a PR whose ROOT comment was authored by
+ * Infraweaver's bot — the full set of open Infraweaver findings on the PR. Basis
+ * for the never-approve-with-outstanding-findings invariant (see the approval
+ * gate in `create_pull_request_review`).
+ *
+ * It's a function of ALL open findings, not just the latest commit's delta, so
+ * an incremental review can't approve past a prior unresolved thread. Outdated-
+ * but-unresolved threads still count: GitHub marks a thread `[OUTDATED]` when the
+ * anchor line moved (reformat, rename, force-push), which is not the concern
+ * being addressed. Human-reviewer threads are excluded — they belong to those
+ * reviewers to resolve. Walks every page (bounded) so a long-lived PR with >100
+ * threads can't hide an outstanding finding. #990.
+ */
+export declare function countOutstandingInfraweaverThreads(input: {
+    octokit: Octokit;
+    owner: string;
+    name: string;
+    pullNumber: number;
+}): Promise<number>;
+export type ReviewThreadComment = {
+    fullDatabaseId: string | null;
+    body: string;
+    bodyHTML: string;
+    createdAt: string;
+    diffHunk: string;
+    line: number | null;
+    startLine: number | null;
+    originalLine: number | null;
+    originalStartLine: number | null;
+    author: {
+        login: string;
+    } | null;
+    pullRequestReview: {
+        databaseId: number | null;
+        author: {
+            login: string;
+        } | null;
+    } | null;
+    reactionGroups: Array<{
+        content: string;
+        reactors: {
+            totalCount?: number;
+            nodes: Array<{
+                login: string;
+            } | null> | null;
+        } | null;
+    }> | null;
+};
+export type ReviewThread = {
+    id: string;
+    path: string;
+    line: number | null;
+    startLine: number | null;
+    diffSide: "LEFT" | "RIGHT";
+    isResolved: boolean;
+    isOutdated: boolean;
+    comments: {
+        nodes: (ReviewThreadComment | null)[] | null;
+    } | null;
+};
+export type ReviewThreadsQueryResponse = {
+    repository: {
+        pullRequest: {
+            reviewThreads: {
+                nodes: (ReviewThread | null)[] | null;
+            } | null;
+        } | null;
+    } | null;
+};
+export declare function countLines(str: string): number;
+export type ParsedHunk = {
+    header: string;
+    oldStart: number;
+    oldCount: number;
+    newStart: number;
+    newCount: number;
+    content: string[];
+};
+export declare function parseFilePatches(patch: string): ParsedHunk[];
+export declare const GetReviewComments: import("arktype/internal/variants/object.ts").ObjectType<{
+    pull_number: number;
+    review_id: number;
+}, {}>;
+/**
+ * render 👍/👎 totals as a `reactions=` tag attribute so the agent sees
+ * human feedback on its findings inline with the thread (a 👎 on a infraweaver
+ * root comment is false-positive signal; see the IncrementalReview prompt).
+ * Only the thumbs contents — the other six reaction types carry no
+ * accept/reject semantics — and only when at least one is nonzero, so the
+ * common no-reaction case adds zero tokens.
+ */
+export declare function formatReactionCounts(comment: ReviewThreadComment): string;
+/**
+ * formats thread blocks into markdown with TOC and line numbers.
+ * extracted for testability.
+ */
+export declare function formatReviewThreads(threadBlocks: Array<{
+    path: string;
+    lineRange: string;
+    content: string[];
+}>, header: {
+    pullNumber: number;
+    reviewId: number;
+    reviewer: string;
+    reviewBody?: string;
+}): {
+    toc: string;
+    content: string;
+};
+/**
+ * builds thread blocks from review threads and file patches.
+ * extracted for testability.
+ */
+export declare function buildThreadBlocks(threads: ReviewThread[], filePatchMap: Map<string, ParsedHunk[]>, reviewId: number): {
+    path: string;
+    lineRange: string;
+    content: string[];
+}[];
+interface GetReviewDataInput {
+    octokit: Octokit;
+    owner: string;
+    name: string;
+    pullNumber: number;
+    reviewId: number;
+    approvedBy?: string | undefined;
+    tmpdir: string;
+    githubToken: string;
+}
+export interface FormatReviewDataInput {
+    review: ReviewResponse;
+    threads: ReviewThread[];
+    prFiles: ReviewPrFile[];
+    pullNumber: number;
+    reviewId: number;
+}
+export type ReviewResponse = {
+    body: string | null | undefined;
+    user: {
+        login: string;
+    } | null | undefined;
+};
+export type ReviewPrFile = {
+    filename: string;
+    patch?: string | undefined;
+};
+export declare function formatReviewData(input: FormatReviewDataInput): {
+    threadBlocks: Array<{
+        path: string;
+        lineRange: string;
+        content: string[];
+    }>;
+    reviewer: string;
+    formatted: {
+        toc: string;
+        content: string;
+    };
+} | undefined;
+export declare function getReviewData(input: GetReviewDataInput): Promise<{
+    threadBlocks: Array<{
+        path: string;
+        lineRange: string;
+        content: string[];
+    }>;
+    reviewer: string;
+    formatted: {
+        toc: string;
+        content: string;
+    };
+    truncated: boolean;
+} | undefined>;
+export declare function GetReviewCommentsTool(ctx: GitHubToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    pull_number: number;
+    review_id: number;
+}, {
+    pull_number: number;
+    review_id: number;
+}>> & {
+    mutates?: boolean;
+};
+export declare const ListPullRequestReviews: import("arktype/internal/variants/object.ts").ObjectType<{
+    pull_number: number;
+}, {}>;
+export declare function ListPullRequestReviewsTool(ctx: GitHubToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    pull_number: number;
+}, {
+    pull_number: number;
+}>> & {
+    mutates?: boolean;
+};
+export declare const ResolveReviewThread: import("arktype/internal/variants/object.ts").ObjectType<{
+    thread_id: string;
+}, {}>;
+export declare function ResolveReviewThreadTool(ctx: GitHubToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    thread_id: string;
+}, {
+    thread_id: string;
+}>> & {
+    mutates?: boolean;
+};
+export {};

package/dist/mcp/roots.d.ts

@@ -0,0 +1,60 @@
+import type { LocalToolContext } from "#app/mcp/localContext";
+/**
+ * Multi-root awareness. A repo can hold SEVERAL Terraform root modules — the
+ * dirs you'd run `terraform init/plan/apply` in — not one. hepcare, for example,
+ * has `terraform/` AND `terraform/core/`, plus a child module under
+ * `terraform/modules/`. The scanners run recursively, but plan/validate assume a
+ * single `cwd`; this surfaces the roots so a run can act per-root.
+ *
+ * Heuristic (validated against real repos): a ROOT is a dir whose `*.tf`
+ * declares a PROVIDER CONFIGURATION (`provider "<name>" { … }`) or a BACKEND
+ * (`backend "<type>" { … }`). A CHILD MODULE never configures a provider or a
+ * backend (it only declares `required_providers`), so this cleanly separates the
+ * two. Pure parsing + a single fs walk; no subprocess.
+ */
+export interface TerraformRoot {
+    /** repo-relative dir (POSIX); "" for the top-level. */
+    dir: string;
+    hasBackend: boolean;
+    hasProviderConfig: boolean;
+    tfFileCount: number;
+}
+/** detect whether some concatenated HCL marks a root module. */
+export declare function isRootModuleHcl(hcl: string): {
+    hasBackend: boolean;
+    hasProviderConfig: boolean;
+};
+/**
+ * Discover the Terraform root modules under `cwd`. Walks `*.tf` recursively
+ * (skipping cache/VCS dirs via walkTfFiles), groups by directory, and keeps the
+ * dirs that configure a provider or a backend. Sorted by dir. An empty result
+ * means no obvious root was found — the caller falls back to scanning `cwd`
+ * itself as a single root.
+ */
+export declare function discoverTerraformRoots(cwd: string): TerraformRoot[];
+export interface EnvironmentTwinGroup {
+    /** the shared path shape with the env/region segment replaced by `{env}`. */
+    pattern: string;
+    /** the matched twins: each a dir + the environment/region token it carries. */
+    members: {
+        dir: string;
+        environment: string;
+    }[];
+}
+/**
+ * Detect environment/region TWINS among a set of repo-relative paths (root dirs
+ * and/or `*.tfvars` files): parallel stacks that differ only by an environment
+ * (`dev`/`staging`/`prod`/…) or region (`eu-west-2`) segment. A fix applied to
+ * one should usually be offered for its twins too (backport / fan-out).
+ *
+ * For each path, finds the LAST segment that is an env token or a region (a
+ * `<env>.tfvars` file counts via its basename), replaces it with `{env}` to form
+ * a pattern, and groups by that pattern. Only groups with ≥2 DISTINCT
+ * environments are returned (a single match isn't a twin set). Pure +
+ * deterministic (sorted).
+ */
+export declare function detectEnvironmentTwins(paths: string[]): EnvironmentTwinGroup[];
+export declare const TerraformRootsParams: import("arktype/internal/variants/object.ts").ObjectType<object, {}>;
+export declare function TerraformRootsTool(ctx: LocalToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<object, object>> & {
+    mutates?: boolean;
+};

package/dist/mcp/scope.d.ts

@@ -0,0 +1,26 @@
+import type { ToolState } from "#app/toolState";
+import type { ResolvedPayload } from "#app/utils/payload";
+/**
+ * The slice of the run these scope guards read: the triggering event (for the
+ * scoped issue/PR) and the created-target set. Both `GitHubToolContext` and the
+ * combined GitHub write context satisfy it — the guards need no octokit of their
+ * own.
+ */
+export interface ScopeContext {
+    payload: ResolvedPayload;
+    toolState: ToolState;
+}
+/**
+ * Record a PR/issue this run created so later body edits / comments / reviews on
+ * it pass {@link assertTargetInScope}. Call after a successful
+ * `create_pull_request` / `create_issue`.
+ */
+export declare function recordCreatedTarget(ctx: ScopeContext, target: number): void;
+/** true when `target` is the run's triggering issue/PR or one it created. */
+export declare function isTargetInScope(ctx: ScopeContext, target: number): boolean;
+/**
+ * Throw if `target` is neither the run's triggering issue/PR nor one it created.
+ * `action` is a short verb phrase used in the error (e.g. "comment on",
+ * "submit a review on", "add labels to").
+ */
+export declare function assertTargetInScope(ctx: ScopeContext, target: number, action: string): void;

package/dist/mcp/selectMode.d.ts

@@ -0,0 +1,20 @@
+import type { ToolContext } from "#app/mcp/server";
+export declare const SelectModeParams: import("arktype/internal/variants/object.ts").ObjectType<{
+    mode: string;
+    issue_number?: number;
+}, {}>;
+export type PlanCommentResponsePayload = {
+    error: string;
+} | {
+    commentId: number;
+    body: string;
+};
+export declare function SelectModeTool(ctx: ToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    mode: string;
+    issue_number?: number;
+}, {
+    mode: string;
+    issue_number?: number;
+}>> & {
+    mutates?: boolean;
+};

package/dist/mcp/server.d.ts

@@ -0,0 +1,61 @@
+import "#app/mcp/arkConfig";
+import { type AgentId } from "#app/external";
+import type { Mode } from "#app/modes";
+import type { ToolState } from "#app/toolState";
+import type { OctokitWithPlugins } from "#app/utils/github";
+import type { ResolvedPayload } from "#app/utils/payload";
+import type { AccountPlan } from "#app/utils/runContext";
+import type { RunContextData } from "#app/utils/runContextData";
+export interface ToolContext {
+    agentId: AgentId;
+    repo: RunContextData["repo"];
+    payload: ResolvedPayload;
+    octokit: OctokitWithPlugins;
+    githubInstallationToken: string;
+    gitToken: string;
+    refreshGitToken?: ((stale: string) => Promise<string>) | undefined;
+    apiToken: string;
+    modes: Mode[];
+    postCheckoutScript: string | null;
+    prepushScript: string | null;
+    prApproveEnabled: boolean;
+    modeInstructions: Record<string, string>;
+    toolState: ToolState;
+    runId: number | undefined;
+    mcpServerUrl: string;
+    mcpServerToken: string;
+    tmpdir: string;
+    oss: boolean;
+    plan: AccountPlan;
+    resolvedModel: string | undefined;
+}
+type JsonSchema = Record<string, unknown>;
+/**
+ * The per-run subagent deny set: the canonical bare names of every registered
+ * orchestrator tool marked `mutates: true`. Derived here (not from a static list)
+ * so a newly-added mutating tool is fenced the moment it's tagged — there is no
+ * separate list to drift. Embedded into the claude/opencode subagent gates
+ * (`buildClaudePretoolGateSource` / `buildOpencodeSubagentGateSource`).
+ *
+ * Throws when the derived set is empty: that means the `mutates` tagging
+ * regressed, and we refuse to start with the gate silently disabled rather than
+ * let subagents reach state-changing tools.
+ */
+export declare function subagentDeniedToolNames(ctx: ToolContext, outputSchema?: JsonSchema): string[];
+type McpHttpServerOptions = {
+    outputSchema?: JsonSchema | undefined;
+};
+/**
+ * Start the MCP HTTP server.
+ *
+ * The returned disposer is idempotent — safe to call multiple times.
+ * Callers (e.g. the inner activity-timeout handler in main.ts) may need to
+ * stop the server before the `await using` block exits; a subsequent
+ * automatic dispose is then a no-op.
+ */
+export declare function startMcpHttpServer(ctx: ToolContext, options?: McpHttpServerOptions): Promise<{
+    url: string;
+    token: string;
+    [Symbol.asyncDispose]: () => Promise<void>;
+}>;
+export {};

package/dist/mcp/shared.d.ts

@@ -0,0 +1,62 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { FastMCP, Tool } from "fastmcp";
+import type { ToolContext } from "#app/mcp/server";
+/**
+ * A FastMCP tool augmented with infraweaver's `mutates` flag: `true` marks a
+ * state-changing tool (working tree, remote, GitHub state, run state, fs/process)
+ * that subagents must not call. The subagent deny list is derived from this flag
+ * at runtime (see `subagentDeniedToolNames`) rather than a hand-maintained list,
+ * so a new mutating tool is gated the moment it's tagged — no separate list to
+ * drift out of sync.
+ */
+export type InfraweaverTool = Tool<any, any> & {
+    mutates?: boolean;
+};
+export declare const tool: <const params>(toolDef: Tool<any, StandardSchemaV1<params>> & {
+    mutates?: boolean;
+}) => Tool<any, StandardSchemaV1<params>> & {
+    mutates?: boolean;
+};
+export interface ToolResult {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: boolean;
+}
+/**
+ * Structured tool-outcome envelope ("Structured tool errors"). Every tool
+ * that can be unavailable, skipped, or degrade green returns the SAME shape so a
+ * caller (the agent, or a downstream parser) can branch deterministically:
+ *   - success: `{ ok: true, … }`
+ *   - skip / unavailable / soft failure: `{ ok: false, code, detail }`
+ * where `code` is a stable machine token (snake_case) and `detail` a human
+ * sentence. The newer tools (terraform_roots / terraform_module_interface /
+ * terraform_provider_schema / policy_check) emit this natively; the older
+ * degrade-green tools historically returned `{ ran|found: false,
+ * skipped_reason|reason }`. Those keep their legacy aliases ALONGSIDE the new
+ * fields (the call site spreads `toolSkip(...)` into its existing object) so
+ * prompt + test contracts keep working while the surface converges — additive,
+ * never breaking.
+ */
+export type ToolOk<T extends Record<string, any>> = T & {
+    ok: true;
+};
+/** wrap a success payload with `ok: true`. */
+export declare const toolOk: <T extends Record<string, any>>(data: T) => ToolOk<T>;
+/** the structured skip/unavailable envelope: `{ ok: false, code, detail }`. */
+export declare const toolSkip: (code: string, detail: string) => {
+    ok: false;
+    code: string;
+    detail: string;
+};
+export declare const handleToolSuccess: (data: Record<string, any> | string) => ToolResult;
+export declare const handleToolError: (error: unknown) => ToolResult;
+/**
+ * Helper to wrap a tool execute function with error handling.
+ * Captures ctx in closure so tools don't need to handle try/catch.
+ * @param fn - the function to execute
+ * @param toolName - optional tool name for error logging
+ */
+export declare const execute: <T, R extends Record<string, any> | string>(fn: (params: T) => Promise<R>, toolName?: string) => (params: T) => Promise<ToolResult>;
+export declare const addTools: (ctx: ToolContext, server: FastMCP<any>, tools: InfraweaverTool[]) => FastMCP<any>;

package/dist/mcp/shell.d.ts

@@ -0,0 +1,58 @@
+import type { ToolContext } from "#app/mcp/server";
+export declare const ShellParams: import("arktype/internal/variants/object.ts").ObjectType<{
+    command: string;
+    description: string;
+    timeout?: number;
+    working_directory?: string;
+    background?: boolean;
+}, {}>;
+export type SandboxMethod = "unshare" | "sudo-unshare" | "none";
+/** get the current sandbox method (for testing/diagnostics) */
+export declare function getSandboxMethod(): SandboxMethod;
+export declare function resolveRepoRoot(): string;
+/** chars of shell output kept inline in the agent reply. anything past this
+ * blows the agent's context budget on commands that dump big logs (test
+ * runners, build tools, grep on large trees), so the overflow is spilled
+ * to a tempfile the agent can re-read selectively (cat/tail/grep). */
+export declare const MAX_OUTPUT_CHARS = 5000;
+/** hard ceiling on the stdout/stderr we hold in memory WHILE a command runs.
+ * `capOutput` only spills to a tempfile AFTER exit, so without this the live
+ * accumulator grows by string-concat on every `data` event — a child that streams
+ * hundreds of MB before exiting (runaway build/test, `cat` of a huge file) can OOM the
+ * runner first. Tail-preferring: the newest output, where errors surface, wins —
+ * which also matches `capOutput` keeping the tail. Set far above MAX_OUTPUT_CHARS so it
+ * never interferes with normal output, only bounds the pathological case. */
+export declare const MAX_CAPTURE_CHARS = 5000000;
+/** A string accumulator bounded to ~`limit` chars, keeping the TAIL. The trim is
+ * amortized (the buffer is allowed to reach 2× before slicing back) so steady-state
+ * appends stay O(1). `droppedChars()` reports how much of the head was discarded. */
+export declare function createCappedBuffer(limit: number): {
+    push(chunk: string): void;
+    value(): string;
+    droppedChars(): number;
+};
+export declare function ShellTool(ctx: ToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    command: string;
+    description: string;
+    timeout?: number;
+    working_directory?: string;
+    background?: boolean;
+}, {
+    command: string;
+    description: string;
+    timeout?: number;
+    working_directory?: string;
+    background?: boolean;
+}>> & {
+    mutates?: boolean;
+};
+export declare const KillBackgroundParams: import("arktype/internal/variants/object.ts").ObjectType<{
+    handle: string;
+}, {}>;
+export declare function KillBackgroundTool(ctx: ToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    handle: string;
+}, {
+    handle: string;
+}>> & {
+    mutates?: boolean;
+};

package/dist/mcp/staleFix.d.ts

@@ -0,0 +1,138 @@
+import type { GitHubToolContext } from "#app/mcp/capabilityContext";
+/** true when `branch` is a Infraweaver remediation/generation branch. */
+export declare function isRemediationBranch(branch: string): boolean;
+/** the `<group-id>` of a `remediate/<group-id>` branch (the scan group id that
+ * keys the fix), or null for a generation branch / non-remediation branch. */
+export declare function groupIdFromBranch(branch: string): string | null;
+/** true when a commit-author LOGIN is Infraweaver's bot (so a commit by it is NOT
+ * a human edit). A null/absent login is treated as non-human here for backward
+ * compatibility of this login-only helper — but prefer {@link isBotCommit}, which
+ * resolves an absent login via the commit's git identity rather than assuming
+ * bot (the assumption that caused a human commit with an unlinked email to be
+ * force-overwritten). */
+export declare function isBotActor(login: string | null | undefined): boolean;
+/** the authorship slice of a compareCommits entry that {@link isBotCommit} reads. */
+export interface CommitAuthorship {
+    /** the GitHub user GitHub resolved from the commit's author email, or null when
+     * the email isn't linked to any account — true for Infraweaver's own `[bot]`
+     * noreply email AND for a human committing under an unverified email. */
+    author?: {
+        login?: string | null;
+    } | null;
+    /** the raw git author identity from the commit object, present even when the
+     * GitHub `author` account above is null. */
+    commit?: {
+        author?: {
+            name?: string | null;
+            email?: string | null;
+        } | null;
+    } | null;
+}
+/**
+ * Decide whether a remediation-branch commit is Infraweaver's own (a bot commit,
+ * safe to force-overwrite on refresh) or a human/third-party edit (must be
+ * preserved — escalate instead of refresh).
+ *
+ * A resolved GitHub `author.login` is authoritative: a positive bot match is a
+ * bot, a real login is a human. When the login is ABSENT — which happens both for
+ * Infraweaver's own commits (its `infraweaver[bot]` noreply email doesn't map to a
+ * GitHub account) and for a human committing under an unverified email — fall
+ * back to the commit's git identity: only a recognised bot name/email
+ * (`infraweaver[bot]`, any `[bot]`) counts as a bot; ANY other identity is treated
+ * as a human edit. This is the conservative direction on purpose — a missed bot
+ * commit costs one skipped auto-refresh, whereas a missed human commit is a
+ * force-push that destroys their work.
+ */
+export declare function isBotCommit(commit: CommitAuthorship): boolean;
+export type StaleFixStatus = "current" | "stale" | "human_touched" | "checks_failing";
+export type StaleFixAction = "skip" | "refresh" | "escalate";
+/** the latest CI conclusion on a remediation PR's head, used to self-heal a PR
+ * whose own checks are red (a failed `terraform plan`, a failing module test, a
+ * policy gate) even when its base hasn't moved. `unknown` = no checks reported or
+ * the read failed (treated as "no signal" — never manufactures a refresh). */
+export type ChecksState = "passing" | "failing" | "pending" | "unknown";
+export interface StaleFixAssessment {
+    status: StaleFixStatus;
+    action: StaleFixAction;
+    reason: string;
+    /** a likely zombie: stale (base advanced), untouched by humans, and open past
+     * the staleness age threshold — surface it so the sweep prioritizes closing it
+     * once the concern is confirmed resolved. Advisory; the action stays `refresh`. */
+    zombie: boolean;
+}
+/** age (in days, PR open duration) past which a stale, untouched remediation PR
+ * is flagged as a likely zombie for prioritized cleanup. */
+export declare const DEFAULT_STALE_AFTER_DAYS = 30;
+/**
+ * How many times the sweep will auto re-derive a remediation PR to clear a FAILING
+ * CI check before it gives up and escalates to a human. Self-heal is on by default,
+ * but a fix the engine proves green locally yet that keeps failing the consumer's
+ * CI (a cloud-credentialled `terraform plan`, a flaky integration test) must not
+ * loop forever — past the cap the PR is labelled needs-human and left alone. Only
+ * the checks-failing path is capped; a genuine base move is always a fresh refresh.
+ */
+export declare const DEFAULT_SELF_HEAL_MAX_ATTEMPTS = 3;
+/** count of self-heal attempts already recorded on a PR, from its accumulated
+ * `infraweaver-self-heal-attempt-N` labels. */
+export declare function selfHealAttempts(labels: string[]): number;
+/** the label to stamp when recording the next self-heal attempt (1-based). */
+export declare function nextSelfHealLabel(attempts: number): string;
+/**
+ * Decide what a refresh sweep should do with one open remediation PR, from git +
+ * CI facts alone. Pure.
+ *  - a branch carrying NON-bot commits is `human_touched` → `escalate` (never
+ *    force-overwrite a human's work; leave it for review).
+ *  - a branch whose base has NOT advanced AND whose checks are not failing is
+ *    `current` → `skip` (the fix is still derived against the live base).
+ *  - a branch whose own CI is red (and base unchanged) is `checks_failing` →
+ *    `refresh`: re-derive the fix on the current base and re-prove it (the
+ *    self-heal case — a failed plan/test/policy on Infraweaver's own PR). Two guards
+ *    stop this looping forever: (1) if it is ALREADY labelled needs-human and the
+ *    base hasn't moved, re-deriving would only reproduce the same failing fix, so
+ *    `skip`; (2) once `selfHealAttempts` reaches `maxSelfHealAttempts` (default 3)
+ *    the sweep gives up and `escalate`s instead of re-deriving again.
+ *  - otherwise the base moved → `stale` → `refresh`: re-derive the fix on the
+ *    current base, then close it if the concern is already resolved or update it.
+ *
+ * `ageDays` (PR open duration) is advisory: a stale, untouched PR open past
+ * `staleAfterDays` is additionally flagged `zombie` so the sweep can prioritize
+ * clearing the long-rotting ones. It never changes the action — a fix is only
+ * ever closed once a re-scan confirms its concern is actually resolved.
+ */
+export declare function assessStaleFix(input: {
+    baseBehindBy: number;
+    hasNonBotCommits: boolean;
+    /** the PR's CI is red (a failed plan/test/policy) — triggers a self-heal. */
+    checksFailing?: boolean;
+    /** the PR already carries `needs-human` — used as the self-heal loop guard. */
+    alreadyEscalated?: boolean;
+    /** self-heal attempts already recorded on this PR (from its attempt labels). */
+    selfHealAttempts?: number;
+    /** the retry ceiling for self-heal (default {@link DEFAULT_SELF_HEAL_MAX_ATTEMPTS}). */
+    maxSelfHealAttempts?: number;
+    ageDays?: number;
+    staleAfterDays?: number;
+}): StaleFixAssessment;
+export declare const ListRemediationPrsParams: import("arktype/internal/variants/object.ts").ObjectType<{
+    limit?: number;
+}, {}>;
+export declare function ListRemediationPrsTool(ctx: GitHubToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    limit?: number;
+}, {
+    limit?: number;
+}>> & {
+    mutates?: boolean;
+};
+export declare const ClosePullRequest: import("arktype/internal/variants/object.ts").ObjectType<{
+    pull_number: number;
+    comment?: string;
+}, {}>;
+export declare function ClosePullRequestTool(ctx: GitHubToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    pull_number: number;
+    comment?: string;
+}, {
+    pull_number: number;
+    comment?: string;
+}>> & {
+    mutates?: boolean;
+};