infraweaver 0.1.0

package/dist/agents/sessionLabeler.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Track per-session labels so log lines from parallel subagents can be
+ * differentiated. The orchestrator dispatches lens subagents
+ * via the Task tool; each subagent runs in its own opencode/claude Session
+ * with its own `sessionID` (or `session_id`) tag on the NDJSON event stream.
+ *
+ * Without per-session prefixing, parallel subagent tool_use / tool_result /
+ * text events appear as a single interleaved stream tagged with `[Infraweaver]`,
+ * making it impossible for a human reading the logs to attribute work to a
+ * specific lens.
+ *
+ * The labeler is deliberately runtime-agnostic — both opencode.ts and
+ * claude.ts feed it the same shape. The contract is FIFO: when the orchestrator
+ * dispatches N task tool_use blocks in a single assistant turn (the parallel
+ * fan-out the multi-lens prompt requires), the i-th new sessionID is assumed
+ * to belong to the i-th task dispatch. This is correct as long as parallel
+ * dispatches are emitted in source-order and the runtimes respect that order
+ * when assigning child sessions; we do not depend on it for correctness of
+ * the read-only contract — only for log readability.
+ */
+export interface TaskDispatchInput {
+    description?: string | undefined;
+    subagent_type?: string | undefined;
+    prompt?: string | undefined;
+}
+export declare const ORCHESTRATOR_LABEL = "orchestrator";
+/**
+ * Extract a human-readable label from a Task tool's input. Tries (in order):
+ *   1. explicit `lens: <name>` marker on a line in the prompt — preferred,
+ *      lets the orchestrator name the lens deterministically
+ *   2. the Task tool's `description` field — short, written by orchestrator
+ *      per call, usually enough
+ *   3. the `subagent_type` — falls back to the named
+ *      subagent identity when description is missing
+ *   4. generic "subagent" — last resort
+ */
+export declare function deriveLabelFromTaskInput(input: TaskDispatchInput): string;
+/**
+ * Stateful tracker mapping subagent activity back to human-readable labels.
+ *
+ * Two attribution channels are supported because the runtimes differ:
+ *
+ *   - **OpenCode** spawns each subagent as its own opencode `Session` with
+ *     a distinct `sessionID`. The harness records each Task dispatch into a
+ *     pending FIFO queue; the next previously-unseen sessionID consumes the
+ *     head of the queue and binds it to that label.
+ *
+ *   - **Claude Code** runs subagents inside the orchestrator's session — they
+ *     all share `session_id` — and instead stamps every subagent message with
+ *     `parent_tool_use_id` pointing at the Agent tool_use id that spawned them.
+ *     The harness binds each Agent tool_use id to its dispatched label up
+ *     front, then `labelFor` looks the label up directly when an event arrives
+ *     carrying that `parent_tool_use_id`.
+ *
+ * `labelFor(sessionID, parentToolUseId?)` accepts both: when
+ * `parentToolUseId` is set and known it short-circuits to the direct mapping;
+ * otherwise it falls through to the FIFO/sessionID path.
+ */
+export declare class SessionLabeler {
+    private readonly labels;
+    private readonly labelsByToolUseId;
+    private readonly pendingLabels;
+    private fallbackCounter;
+    /**
+     * Record a Task/Agent tool dispatch.
+     *
+     * @param input  Task tool input — used to derive the lens label.
+     * @param toolUseId  Optional Agent tool_use id. When provided, future events
+     *                   carrying `parent_tool_use_id === toolUseId` resolve
+     *                   directly to this label without consuming the FIFO queue
+     *                   (Claude path). Always also pushed to the FIFO queue so
+     *                   the OpenCode path still works when toolUseId is absent.
+     */
+    recordTaskDispatch(input: TaskDispatchInput, toolUseId?: string | null): string;
+    /**
+     * Return a label for the given event.
+     *
+     * @param sessionID         Session id from the event (OpenCode: per-session;
+     *                          Claude: shared across orchestrator + subagents).
+     * @param parentToolUseId   Claude's `parent_tool_use_id` — non-null on
+     *                          subagent messages. When set and known, takes
+     *                          priority over the FIFO/sessionID path.
+     */
+    labelFor(sessionID: string | undefined | null, parentToolUseId?: string | null): string;
+    /** number of distinct sessions seen so far (for diagnostics) */
+    size(): number;
+    /** all (sessionID, label) pairs, oldest first */
+    entries(): Array<[string, string]>;
+    /** how many pending labels are queued waiting to bind to a new session */
+    pendingDispatchCount(): number;
+}
+/**
+ * Format a log message with a session label prefix in magenta. Mirrors the
+ * style of utils/log.ts:prefixLines() so per-session prefixes look the same
+ * as the dormant withLogPrefix-based ones.
+ */
+export declare function formatWithLabel(label: string, message: string): string;

package/dist/agents/shared.d.ts

@@ -0,0 +1,246 @@
+import type { RunTokenQuota } from "#app/agents/tokenQuota";
+import type { AgentId } from "#app/external";
+import type { ToolState } from "#app/toolState";
+import type { ResolvedInstructions } from "#app/utils/instructions";
+import type { ResolvedPayload } from "#app/utils/payload";
+import type { TodoTracker } from "#app/utils/todoTracking";
+export declare const MAX_STDERR_LINES = 20;
+/**
+ * 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 declare const MAX_POST_RUN_RETRIES = 3;
+export declare function getGitStatus(): string;
+export declare function buildCommitPrompt(status: string): string;
+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 declare function hasPostRunIssues(issues: PostRunIssues): boolean;
+/**
+ * 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 declare 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 declare const agent: (input: Agent) => Agent;
+/** format a USD cost to 4 decimal places, always showing the leading zero */
+export declare function formatCostUsd(costUsd: number): string;
+/**
+ * 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 declare function agentHomeEnv(tmpdir: string): {
+    HOME: string;
+    XDG_CONFIG_HOME: string;
+};
+/**
+ * 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 declare function baseAgentEnv(homeEnv: {
+    HOME: string;
+    XDG_CONFIG_HOME: string;
+}, repoDir: string): NodeJS.ProcessEnv;
+/**
+ * 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 declare function buildAgentUsage(parts: {
+    agent: string;
+    /** non-cached input tokens sent this run. */
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    costUsd: number;
+}): AgentUsage | 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 declare function mergeAgentUsage(a: AgentUsage | undefined, b: AgentUsage | undefined): AgentUsage | 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 declare function logTokenTable(t: {
+    input: number;
+    cacheRead: number;
+    cacheWrite: number;
+    output: number;
+    costUsd?: number | undefined;
+}): void;

package/dist/agents/subagentModels.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 declare function deriveSubagentModels(orchestratorSpec: string | undefined): {
+    reviewer: string | undefined;
+};

package/dist/agents/tokenQuota.d.ts

@@ -0,0 +1,118 @@
+/**
+ * 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 declare class TokenQuotaExceededError extends Error {
+    readonly code = "TOKEN_QUOTA_EXCEEDED";
+    constructor(message: string);
+}
+/** True when an unknown error is (or wraps) a token-quota abort. */
+export declare function isTokenQuotaError(err: unknown): boolean;
+/**
+ * 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 declare const DEFAULT_RUN_TOKEN_QUOTA = 10000000;
+/** The workflow input that overrides {@link DEFAULT_RUN_TOKEN_QUOTA}. */
+export declare 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 declare function billableTokens(t: TokenComponents): number;
+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 declare function unlimitedTokenQuota(): RunTokenQuota;
+/**
+ * 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 declare function createTokenQuota(limit: number): RunTokenQuota;
+/**
+ * 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 declare function parseRunTokenQuota(raw: string | undefined): number | undefined;
+/** Resolve the effective limit from the parsed input, applying the default. */
+export declare function resolveRunTokenQuota(parsed: number | undefined): number;

package/dist/agents/writeGateSource.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The path-decision half of the write-time gates, emitted as source text that
+ * both agent runtimes embed into the standalone scripts they drop in the run
+ * tmpdir (see action/agents/claudePretoolGate.ts and
+ * action/agents/opencodePlugin.ts).
+ *
+ * It lives in one place because the two runtimes previously derived their base
+ * directory differently (the hook payload's `cwd` vs `process.cwd()`), which
+ * would silently misalign every glob the moment one of them changed. Sharing
+ * the source keeps a single definition of "is this write allowed", and keeps it
+ * aligned with the push-time gates in action/mcp/guardrails.ts that re-check
+ * the same globs.
+ *
+ * The emitted code is dependency-free (node builtins only) because the scripts
+ * run outside the bundle, with no module resolution available to them.
+ */
+/**
+ * Shared helper source. Defines `refuseWrite(policy, rawPath, root)` returning
+ * a refusal string or null, plus the primitives it needs. Callers supply their
+ * own `targetPathOf` because the two runtimes name tool arguments differently.
+ */
+export declare const WRITE_GATE_HELPERS_SOURCE: string;

package/dist/agents/writePolicy.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The write-time counterpart to the push-time path guardrails in
+ * `action/mcp/guardrails.ts`.
+ *
+ * Those gates (`enforceRemediationPaths`, `enforceProtectedPaths`,
+ * `assertNoVendoredModuleEdits`) all read `git diff <run-start> HEAD` — so they
+ * only fire once a change is already committed and heading for a push. That is
+ * fail-safe but LATE: between the write and the push the modified tree is what
+ * every subsequent subprocess sees, so a `terraform plan` or a re-scan can run
+ * against a file the guardrails would ultimately refuse. This module moves the
+ * same allow/deny decision to the moment of the write itself.
+ *
+ * SCOPE — this covers the agent's file-writing TOOLS, not every possible write.
+ * It deliberately does not cover:
+ *   - the MCP `shell` tool (`cat > f`, `tee`, `sed -i`), which is bounded by
+ *     the OS sandbox in `action/mcp/shell.ts` rather than by these globs;
+ *   - the file-emitting MCP tools (`terraform_emit_sarif`, `_emit_evidence`,
+ *     `_emit_oscal`, `_emit_vex`, `terraform_module_docs`), whose output paths
+ *     are confined to the workspace by `resolveWithinCwd` but not to
+ *     `allowed_paths`.
+ * Both remain covered by the push-time gates, which still fail closed, so
+ * neither is a route to a merged PR — but neither is stopped at write time.
+ *
+ * The policy is published as a small JSON file in the run's tmpdir rather than
+ * baked into the agent's gate script, because `select_mode` sets
+ * `toolState.selectedMode` DURING the run (see action/mcp/selectMode.ts) while
+ * the gate script is written before the agent launches. The gate re-reads this
+ * file on every tool call, so an auto-selected mode is picked up without
+ * restarting the agent. No file (or a non-guarded mode) means no restriction —
+ * exactly matching the push-time gates, which no-op outside a guarded mode.
+ *
+ * Both agent runtimes consume it: action/agents/claudePretoolGate.ts (Claude
+ * Code `PreToolUse`) and action/agents/opencodePlugin.ts
+ * (`tool.execute.before`).
+ */
+import { type GuardrailContext } from "#app/mcp/guardrails";
+export declare const WRITE_POLICY_FILENAME: "infraweaver-write-policy.json";
+/**
+ * What the gate scripts read. Deliberately a flat, dependency-free shape: the
+ * gates are plain `.mjs` with no imports, so anything richer would have to be
+ * re-modelled on the other side.
+ */
+export interface WritePolicy {
+    /** the guarded mode in force — surfaced in the refusal so the model can reason about it. */
+    mode: string;
+    /**
+     * The repo root every glob is resolved against. Carried in the policy rather
+     * than derived inside the gates because `main.ts` chdir()s into the `cwd`
+     * input for monorepo subdirectories, so neither gate's own process cwd is a
+     * safe base — and the push-time globs are always repo-root-relative.
+     */
+    root: string;
+    /** globs a write MUST match (the `allowed_paths` allow-list). */
+    allowed: string[];
+    /** globs a write must NOT match (the `protected_paths` deny-list). */
+    protected: string[];
+    /** fetched/vendored module code, which is read-only by the refactor contract. */
+    vendored: string[];
+}
+/**
+ * Derive the policy for the current run, or `null` when no restriction applies
+ * (no mode selected yet, or a mode outside the guarded set — Review, Plan,
+ * Assess and friends legitimately write files the Terraform-only allow-list
+ * would reject, so gating them would break them).
+ */
+export declare function buildWritePolicy(ctx: GuardrailContext): WritePolicy | null;
+export declare function writePolicyPath(tmpdir: string): string;
+/**
+ * Publish (or clear) the policy for the gates to read.
+ *
+ * Written via a temp file + `rename` so a gate that reads concurrently sees
+ * either the old policy or the new one, never a half-written file — `rename` is
+ * atomic within a filesystem, and the temp file is created in the same tmpdir.
+ *
+ * Best-effort by design: the push-time guardrails remain the authoritative,
+ * fail-closed backstop, so a failure to publish must not abort a run that would
+ * otherwise be blocked correctly a few steps later. It is logged, not thrown.
+ */
+export declare function refreshWritePolicy(ctx: GuardrailContext): void;

package/dist/brand.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Single source of truth for the product brand on the engine side.
+ *
+ * Every user-visible product name, slug, prefix, and brand-derived filename
+ * must come from this module — a rebrand (or a white-label build) is then a
+ * handful of one-line edits here. The one permitted exception is `action.yml`,
+ * which is static YAML and cannot import; src/brand.test.ts asserts it stays
+ * in sync with these values.
+ *
+ * The reviewer subagent name is NOT defined here — it is a separate sub-brand
+ * owned by `REVIEWER_AGENT_NAME` in src/agents/reviewer.ts.
+ */
+/** Display name — PR bodies, review comments, run summaries, agent labels. */
+export declare const PRODUCT_NAME = "Infraweaver";
+/** Lowercase wordmark — package/dir names, CLI usage strings, slugs. */
+export declare const PRODUCT_SLUG = "infraweaver";
+/** PR comment trigger, e.g. `@infraweaver fix`. */
+export declare const COMMENT_COMMAND = "@infraweaver";
+/** SARIF `driver.name`, CycloneDX VEX tool component, evidence `tool.name` —
+ * the emitted artifacts all use the lowercase wordmark. */
+export declare const TOOL_NAME = "infraweaver";
+/** Cloud API token prefix — must match the Cloud UI's `TOKEN_PREFIX`. */
+export declare const TOKEN_PREFIX = "tmnd_";
+/** Prefix for all brand-scoped environment variables. */
+export declare const ENV_PREFIX = "INFRAWEAVER_";
+/** Primary domain — the Cloud API's default host and bearer-credential allowlist root. */
+export declare const PRIMARY_DOMAIN = "infraweaver.dev";
+/** Default Cloud API base URL. */
+export declare const DEFAULT_API_URL = "https://infraweaver.dev";
+/** Docs subdomain, used in in-product setup links. */
+export declare const DOCS_URL = "https://docs.infraweaver.dev";
+/** Status-page subdomain, linked from transient-error messages. */
+export declare const STATUS_URL = "https://status.infraweaver.dev";
+/** Asset-hosting subdomain, used for static images embedded in PR/issue markdown. */
+export declare const UPLOADS_URL = "https://uploads.infraweaver.dev";
+/** Repo config file (YAML). */
+export declare const CONFIG_FILE = ".infraweaver.yml";
+/** Repo config file (`.yaml` spelling variant). */
+export declare const CONFIG_FILE_YAML = ".infraweaver.yaml";
+/** Repo config file (JSON variant). */
+export declare const CONFIG_FILE_JSON = ".infraweaver.json";
+/** Committed baseline of accepted pre-existing findings. */
+export declare const BASELINE_FILE = ".infraweaver.baseline.json";
+/** Committed fix-memory (proven-fix recall) file. */
+export declare const FIX_MEMORY_FILE = ".infraweaver.fix-memory.json";
+/** Repo-committed reviewer learnings file seeded by the server. */
+export declare const LEARNINGS_FILE = "infraweaver-learnings.md";
+/** Rolling PR summary snapshot file. */
+export declare const SUMMARY_FILE = "infraweaver-summary.md";
+/** Signed evidence bundle. */
+export declare const EVIDENCE_FILE = "infraweaver-evidence.json";
+/** Detached signature for the evidence bundle. */
+export declare const EVIDENCE_SIG_FILE = "infraweaver-evidence.json.sig";
+/** SARIF report. */
+export declare const SARIF_FILE = "infraweaver.sarif";
+/** CycloneDX VEX document. */
+export declare const VEX_FILE = "infraweaver-vex.cdx.json";
+/** OSCAL Assessment Results document. */
+export declare const OSCAL_FILE = "infraweaver-oscal.json";
+/** Credential-free cost-analysis artifact committed to the PR (§5.19). */
+export declare const COST_FILE = "cost.md";
+/** The product's GitHub App bot login. */
+export declare const BOT_LOGIN = "infraweaver[bot]";
+/** The bot's GitHub noreply commit-author email. */
+export declare const BOT_EMAIL = "infraweaver[bot]@users.noreply.github.com";
+/** Default GitHub Actions OIDC audience for the product API. */
+export declare const OIDC_AUDIENCE = "infraweaver-api";