infraweaver 0.1.0

package/dist/agents/opencode.d.ts

@@ -0,0 +1,284 @@
+/**
+ * OpenCode agent — in-process harness (opencode-ai >=1.14.x SDK-v2 / Effect-ts
+ * CLI rewrite).
+ *
+ * Architecture, post v2-in-process migration:
+ *
+ *   1. Spawn ONE `opencode serve --port <p>` subprocess per Infraweaver run via
+ *      `node:child_process.spawn` directly (NOT our `spawn()` wrapper — see
+ *      `bootOpencodeServer` for why: long-lived stdio streaming, manual
+ *      activity gating against the SDK event loop, killGroup teardown).
+ *   2. Talk to it over loopback HTTP via the typed `@opencode-ai/sdk/v2`
+ *      `createOpencodeClient({ baseUrl })` — no `Server.Default()` embed,
+ *      no `createOpencode()` SDK lifecycle (would re-wrap our subprocess).
+ *   3. Create ONE session up front (`client.session.create`).
+ *   4. Subscribe to events once (`client.event.subscribe`) and pump them
+ *      through a single per-run handler set for live logging + activity
+ *      tracking + subagent labeling.
+ *   5. Run the initial prompt via `client.session.prompt({ sessionID, parts })`.
+ *      Every post-run gate retry AND the reflection turn re-enter the same
+ *      session via another `client.session.prompt()` call. Warm MCP, warm
+ *      plugins, warm provider connections, same context window — no
+ *      `--continue` subprocess respawn.
+ *   6. Close the server in a finally.
+ *
+ * What that replaces (vs the pre-migration v2 harness):
+ *   - The per-run `opencode run --format json --print-logs --thinking` CLI
+ *     subprocess that emitted NDJSON envelopes.
+ *   - The `runOpenCode(... args: [...baseArgs, "--continue", c.prompt] ...)`
+ *     resume callback that booted a SECOND opencode process (fresh MCP,
+ *     fresh plugins, cold cache) for each gate retry / reflection turn.
+ *   - The `opencodePlugin.ts` bus-event re-emitter — we subscribe to the
+ *     global event stream now, so subagent events arrive naturally without
+ *     a stdout sentinel envelope.
+ *
+ * What stays identical:
+ *   - bash: "deny" via OPENCODE_CONFIG_CONTENT
+ *   - OPENCODE_PERMISSION filesystem sandbox — deny-all + allow /tmp
+ *   - MCP Infraweaver server injected via `mcp.<name> = { type: "remote", url }`
+ *   - ASKPASS for git auth
+ *   - codex auth materialization + post-hook writeback
+ *   - loupe subagent config / model derivation
+ *   - bedrock model prefix routing
+ *   - skills install
+ *   - todo tracker / onToolUse forwarding
+ */
+import { type ChildProcess } from "node:child_process";
+import { type AssistantMessage, type EventSubscribeResponse, type OpencodeClient, type Part } from "@opencode-ai/sdk/v2";
+import { SessionLabeler } from "#app/agents/sessionLabeler";
+import { type AgentResult, type AgentRunContext, type AgentUsage } from "#app/agents/shared";
+import { type RunTokenQuota } from "#app/agents/tokenQuota";
+import type { ToolState } from "#app/toolState";
+import type { AgentDiagnostic } from "#app/utils/agentHangReport";
+import type { TodoTracker } from "#app/utils/todoTracking";
+export declare function buildSecurityConfig(ctx: AgentRunContext, model: string | undefined): string;
+/** split `<providerID>/<modelID>` into the SDK's prompt model shape. */
+export declare function parseModel(value: string | undefined): {
+    providerID: string;
+    modelID: string;
+} | undefined;
+interface ServerHandle {
+    baseUrl: string;
+    proc: ChildProcess;
+    /** kill the server; idempotent. */
+    close: () => Promise<void>;
+    /** rolling tail of server stderr for diagnostics. */
+    recentStderr: string[];
+}
+/**
+ * Spawn `<cliPath> serve --port 0 --hostname 127.0.0.1` and wait for the
+ * "opencode server listening on http://..." stdout line.
+ *
+ * Direct node:child_process.spawn instead of our `spawn()` wrapper because
+ * the wrapper's contract is "Promise<SpawnResult> that resolves on exit" —
+ * we need a handle that stays alive across many session.prompt() calls.
+ * We still register with `trackChild()` so Ctrl-C kills the server alongside
+ * everything else.
+ */
+export declare function bootOpencodeServer(params: {
+    cliPath: string;
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+}): Promise<ServerHandle>;
+/**
+ * What we collect during a single session.prompt() turn so we can render a
+ * unified AgentResult at the end. Per-turn snapshot is reset between turns
+ * inside the event loop via `beginTurn()` / `endTurn()`.
+ */
+export interface TurnAccumulator {
+    finalText: string;
+    /**
+     * Aggregate token totals from step-finish parts across the orchestrator AND
+     * any subagent sessions dispatched during the turn (e.g. loupe).
+     * Mirrors v1's `accumulatedTokens` semantics so production billing/audit
+     * numbers stay apples-to-apples across the migration.
+     */
+    tokens: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+    };
+    costUsd: number;
+    sessionError: string | null;
+    /** populated when a tool_use part on the orchestrator session reports error. */
+    lastToolError: string | null;
+    /**
+     * The token quota's source key for this turn. `tokens` above is reset per
+     * turn, and the quota charges only the increase under a key — so every turn
+     * needs its own, or the second turn's tokens would be free until they
+     * exceeded the first turn's total. See tokenQuota.ts.
+     */
+    quotaSource: string;
+}
+export declare function newTurn(): TurnAccumulator;
+/**
+ * Charge the run's token quota with this turn's running total and, if the
+ * ceiling is reached, abort the turn (LLM10).
+ *
+ * Aborting is the point: a flag alone would let the loop keep streaming until
+ * it happened to finish, which is the consumption we are bounding. The shared
+ * abort controller also serves the activity watchdog, so `tokenQuotaExceeded`
+ * records which of the two fired.
+ */
+export declare function chargeTokenQuota(ctx: RunnerContext): void;
+export interface RunnerContext {
+    client: OpencodeClient;
+    sessionID: string;
+    label: string;
+    orchestratorSessionID: string;
+    labeler: SessionLabeler;
+    toolState: ToolState;
+    todoTracker?: TodoTracker | undefined;
+    onActivityTimeout?: (() => void) | undefined;
+    onToolUse?: ((event: {
+        toolName: string;
+        input: unknown;
+    }) => void) | undefined;
+    /** current per-turn aggregator; nullable between turns. */
+    currentTurn: TurnAccumulator | null;
+    /** monotonic event count for diagnostics. */
+    eventCount: number;
+    /** last activity timestamp (event-stream silence detector). */
+    lastEventAt: number;
+    /** active task dispatch metadata keyed by callID (for subagent timing). */
+    taskDispatchByCallID: Map<string, {
+        label: string;
+        startedAt: number;
+    }>;
+    /**
+     * orchestrator tool callIDs already surfaced via `log.info(» ${tool}(...))`,
+     * tracked so the end-of-turn fallback can re-emit only the calls the live
+     * event stream missed. closes the SSE-connect race against the first
+     * `session.prompt()` (the SDK opens the SSE lazily on first iteration; by
+     * then the server may already have emitted the turn's tool part-updated
+     * events). without the fallback those calls never appear in stdout, which
+     * breaks every validator that greps for tool-call shape.
+     */
+    loggedToolCallIDs: Set<string>;
+    /**
+     * server-side `time.end` of the newest `todowrite` applied to the todo
+     * tracker. the end-of-turn replay processes callIDs the live stream missed
+     * — the *earliest* calls of the first turn — so without this ordering guard
+     * a replayed older todo list would overwrite a newer one already applied
+     * live, and the post-run flush would post the stale checklist to GitHub.
+     */
+    lastTodoUpdateEndMs: number;
+    /** rolling stderr tail from the server process (for diagnostics). */
+    recentStderr: string[];
+    diagnostic: AgentDiagnostic;
+    /**
+     * LLM10 — the per-run token ceiling, charged from `step-finish` parts. The
+     * inner watchdog bounds SILENCE; a remediation loop that cannot converge
+     * streams tokens the whole time and is never silent, so it needs this
+     * separate bound. Absent when there is nothing to enforce.
+     */
+    tokenQuota?: RunTokenQuota | undefined;
+    /**
+     * Set when {@link RunnerContext.tokenQuota} tripped and aborted the turn.
+     * The abort controller is shared with the activity watchdog, so without this
+     * flag a quota stop would be reported as "the model went silent" — the
+     * opposite of what happened.
+     */
+    tokenQuotaExceeded: boolean;
+    /**
+     * Aborts the in-flight turn. Assigned by the runner once the turn's abort
+     * controller exists (the context is built first), so it is optional here and
+     * a no-op in unit tests that drive the event handlers directly.
+     */
+    abortRun?: ((reason: Error) => void) | undefined;
+}
+/**
+ * orchestrate the event stream consumer for the entire server lifetime.
+ *
+ * NB: the SDK subscribe is lazy — the SSE fetch only opens on the first
+ * iteration. so the first turn's tool part-updated events can race the
+ * connect and be missed. live-stream logging is best-effort; see the
+ * end-of-turn `logUnseenToolCalls` fallback for the guarantee.
+ *
+ * the subscription is wrapped in a reconnect loop: a single `for await` with
+ * no retry meant any mid-turn stream error/end permanently killed event
+ * consumption, freezing `ctx.lastEventAt` while the turn kept streaming over
+ * its separate `session.prompt` connection — after the flat idle budget the
+ * inner watchdog then aborted a healthy, progressing run as "model went
+ * silent". reconnects continue (bounded backoff) until the signal aborts.
+ */
+export declare function consumeEvents(ctx: RunnerContext, signal: AbortSignal): Promise<void>;
+export declare function dispatchEvent(ctx: RunnerContext, event: EventSubscribeResponse): Promise<void>;
+/**
+ * shared terminal bookkeeping for a tool part: log line, dedup callID, run
+ * orchestrator-side hooks (`onToolUse` → diff-coverage tracker; `todowrite` /
+ * `report_progress` → todo tracker; tool-error → `lastToolError`), and emit
+ * subagent-finish summary on `task` returns.
+ *
+ * called from both the live SSE path (`onToolPart`) and the end-of-turn
+ * fallback (`logUnseenToolCalls`) — `loggedToolCallIDs` is the dedup guard
+ * so each call's side effects fire exactly once across both paths. critical
+ * for diff-coverage: a first-turn `Read` that races SSE attach would
+ * otherwise be missed by `recordDiffReadFromToolUse`, and the subsequent
+ * `create_pull_request_review` pre-flight would reject the review.
+ */
+export declare function processTerminalToolPart(ctx: RunnerContext, part: Extract<Part, {
+    type: "tool";
+}>, label: string, isOrchestrator: boolean): void;
+export declare function formatPartDuration(time: {
+    start?: number;
+    end?: number;
+} | undefined): string;
+/**
+ * Run a single prompt turn against the persistent server. Resets the per-turn
+ * accumulator, calls `client.session.prompt()`, then assembles an AgentResult
+ * from the returned AssistantMessage + accumulated event state.
+ *
+ * Token / cost: `AssistantMessage.tokens` and `.cost` are authoritative for
+ * the turn. The event-stream accumulator is a fallback / sanity-check path
+ * used when the response is missing (e.g. abort, transport error) — and as
+ * the only source of per-step subagent attribution if we ever surface it.
+ */
+export declare function runPromptTurn(ctx: RunnerContext, params: {
+    text: string;
+    model: {
+        providerID: string;
+        modelID: string;
+    } | undefined;
+    signal: AbortSignal;
+}): Promise<AgentResult>;
+export declare function buildUsage(turn: TurnAccumulator, assistant: AssistantMessage | undefined): AgentUsage | undefined;
+export declare function extractTextFromParts(parts: Part[] | undefined): string | undefined;
+export declare function formatPromptError(error: unknown): string;
+/**
+ * Start an event-silence watchdog. The outer process-level activity timer
+ * (main.ts `createProcessOutputActivityTimeout`) watches `process.stdout.write`
+ * which our harness log lines drive — but it doesn't see SSE event silence
+ * when the harness is itself quiet. This inner timer specifically watches
+ * `ctx.lastEventAt` and fires `onActivityTimeout` so main.ts can tear down
+ * the MCP server early, mirroring the per-spawn watchdog in `subprocess.ts`.
+ *
+ * `ctx.lastEventAt` is refreshed only on meaningful progress (token/tool
+ * part.updated), so any prolonged gap with no progress advances the clock —
+ * including a long in-flight tool call. the budget is the same flat idle
+ * timeout as the outer watchdog, sized to exceed the worst-case legitimate
+ * silent tool window (#760), so a real tool can't trip it; a genuinely stalled
+ * provider or a hung tool does, at the flat budget.
+ */
+export declare function startInnerActivityWatchdog(params: {
+    ctx: RunnerContext;
+    timeoutMs: number;
+    abortController: AbortController;
+}): {
+    stop: () => void;
+};
+export declare const opencode: import("#app/agents/shared").Agent;
+/**
+ * Safety net around a single turn: convert any unexpected throw that escapes
+ * `runPromptTurn` into a `success: false` result so the post-run gate loop
+ * (which expects a result, not a rejection) can surface it through the generic
+ * renderer.
+ *
+ * Watchdog-fired aborts do NOT reach here — `runPromptTurn` owns the abort
+ * signal, catches the aborted `session.prompt` rejection internally, and
+ * classifies it as an `activity timeout` error itself. This wrapper must not
+ * re-classify, since a stray post-prompt throw is not a hang.
+ */
+export declare function runTurnGuarded(ctx: RunnerContext, fn: () => Promise<AgentResult>): Promise<AgentResult>;
+export {};

package/dist/agents/opencodePlugin.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Source for the opencode plugin we drop into the per-run tmpdir at
+ * `<XDG_CONFIG_HOME>/opencode/plugin/infraweaver-events.ts`. The harness already
+ * redirects `XDG_CONFIG_HOME` to `ctx.tmpdir/.config` (see `opencode.ts`
+ * `homeEnv`), so opencode's auto-discovery scans the tmpdir, never the user's
+ * working tree. opencode's `Global.Path.config` resolves to
+ * `path.join(xdgConfig, "opencode")` and the config layer auto-discovers
+ * plugins from every directory in its scan list — including
+ * `Global.Path.config` — by globbing `{plugin,plugins}/*.{ts,js}` via
+ * `ConfigPlugin.load(dir)`.
+ *
+ * We MUST NOT write into the user's repo working tree. The repo is a checkout
+ * the agent operates on; only the agent's own tools (gated by
+ * `OPENCODE_PERMISSION`) may modify it. The whole reason we redirect HOME and
+ * XDG_CONFIG_HOME is so harness-side files (config, plugins, scratch state)
+ * land in the tmpdir.
+ *
+ * Why the events plugin exists: opencode's `task` tool runs subagents
+ * in-process and the CLI's `cli/cmd/run.ts` event loop filters
+ * `part.sessionID !== sessionID`, so subagent-internal `message.part.updated`
+ * events are silently discarded before reaching our parent NDJSON stream.
+ * plugins, by contrast, receive EVERY bus event via `bus.subscribeAll()`
+ * regardless of session.
+ *
+ * The events plugin re-emits every relevant bus event onto opencode's stdout
+ * as a single JSON line wrapped in a sentinel envelope. our `runOpenCode`
+ * parser recognises the envelope, unpacks it, and routes the inner part
+ * through the existing handlers with a per-session label from `SessionLabeler`
+ * so each subagent's tool calls / text appear inline alongside the
+ * orchestrator's.
+ *
+ * The subagent gate (the `tool.execute.before` hook that hard-blocks
+ * state-mutating MCP tool calls from a subagent session) lives in a SEPARATE
+ * plugin — `buildOpencodeSubagentGateSource` below — because it's the
+ * load-bearing security fence and must ship into the opencode harness,
+ * whereas this events re-emitter was only needed by the legacy CLI-parsing
+ * path (the active `opencode.ts` reads subagent events directly off the SDK
+ * event stream, so it installs ONLY the gate plugin). Deny set: derived per-run
+ * from each MCP tool's `mutates` flag (`subagentDeniedToolNames` in
+ * src/mcp/server.ts).
+ *
+ * Dumb plugin / smart parent split: the events plugin emits every part for
+ * every session. the parent dedupes against the orchestrator's own session id
+ * (which it already knows from the `init` event). this keeps the plugin trivial
+ * and keeps the per-session attribution logic on the parent side where the
+ * SessionLabeler already lives.
+ *
+ * Event-name prefixing: the wrapped event-type sentinel is
+ * `infraweaver_bus_event` — picked to be unmistakably ours so a future opencode
+ * release that introduces a coincidentally-named event type won't collide.
+ */
+/**
+ * opencode's native file-writing tools (it lower-cases tool names). The Claude
+ * runtime's equivalent set is `CLAUDE_WRITE_TOOL_NAMES`; both gates enforce the
+ * same policy file so the two runtimes can't diverge on what a guarded mode is
+ * allowed to touch.
+ */
+export declare const OPENCODE_WRITE_TOOL_NAMES: readonly ["write", "edit", "patch"];
+export declare const INFRAWEAVER_BUS_EVENT_TYPE: "infraweaver_bus_event";
+export declare const INFRAWEAVER_OPENCODE_PLUGIN_FILENAME: "infraweaver-events.ts";
+export declare const INFRAWEAVER_OPENCODE_GATE_PLUGIN_FILENAME: "infraweaver-subagent-gate.ts";
+/**
+ * Source written verbatim to `<XDG_CONFIG_HOME>/opencode/plugin/infraweaver-events.ts`.
+ *
+ * - Structural typing only (no runtime import of `@opencode-ai/plugin`):
+ *   opencode installs that dep into the directory containing the plugin
+ *   alongside discovery, but a) the dep isn't required for the structural
+ *   shape we use, and b) keeping zero imports avoids any module-resolution
+ *   coupling to opencode's plugin-loader internals across versions.
+ * - default export is the plugin factory (opencode's plugin loader accepts
+ *   default exports as the server entrypoint).
+ * - we only forward `message.part.updated`. that's where the user-visible
+ *   subagent activity (tool calls, text, step transitions) lives. add more
+ *   event types here if the parent needs them.
+ * - JSON.stringify+single write keeps the line atomic up to PIPE_BUF (4KB on
+ *   Linux). longer parts may interleave with concurrent stdout writers; the
+ *   parser tolerates non-JSON lines (logs them at debug) so a torn line is a
+ *   missed event, not a crash.
+ */
+export declare const INFRAWEAVER_OPENCODE_PLUGIN_SOURCE: string;
+/**
+ * Standalone subagent gate plugin written to
+ * `<XDG_CONFIG_HOME>/opencode/plugin/infraweaver-subagent-gate.ts`. Installed by
+ * the in-process `opencode.ts` harness — the gate is the load-bearing security
+ * fence, so it ships independently of the events re-emitter above (which the
+ * in-process harness doesn't need).
+ *
+ * Hard-blocks state-mutating MCP tool calls originating from a subagent
+ * session via `tool.execute.before`, complementing the runtime backstops from
+ * PR #796 (action/mcp/checkout.ts, action/mcp/git.ts).
+ *
+ * `deniedTools` is the per-run deny set derived from each MCP tool's `mutates`
+ * flag (see `subagentDeniedToolNames`), embedded into the plugin's `Set` literal
+ * so it fences exactly the mutating tools registered for this run.
+ */
+export declare function buildOpencodeSubagentGateSource(deniedTools: readonly string[], writePolicyAbsolutePath: string): string;

package/dist/agents/opencodeShared.d.ts

@@ -0,0 +1,40 @@
+export type OpenCodeConfig = {
+    mcp?: Record<string, unknown>;
+    permission?: Record<string, unknown>;
+    provider?: Record<string, unknown>;
+    agent?: Record<string, unknown>;
+    experimental?: Record<string, unknown>;
+    model?: string;
+    enabled_providers?: string[];
+    [key: string]: unknown;
+};
+/**
+ * Build the `provider.google.models[id].options` map that pins every direct-Google
+ * Gemini alias to `thinkingLevel: "high"`. Sourced from the model registry so
+ * adding/renaming a Google alias in `action/models.ts` flows through automatically.
+ */
+export declare function geminiHighThinkingOverrides(): Record<string, {
+    options: object;
+}>;
+/**
+ * Read-only `loupe` subagent for lens-based review. Non-mutative +
+ * non-recursive — enforced by the system prompt in reviewer.ts.
+ *
+ * Per-subagent `model:` override is driven by the registry in
+ * `action/models.ts` via each alias's `subagentModel` field. Currently wired:
+ * Anthropic opus → sonnet, OpenAI gpt-pro → gpt and gpt → gpt-5.4, Google
+ * gemini-pro → gemini-flash. Other providers inherit (no override).
+ */
+export declare function buildReviewerAgentConfig(orchestratorModel: string | undefined): Record<string, unknown>;
+/**
+ * Install the opencode-ai npm tarball and return the path to the executable.
+ *
+ * The bin path differs by version: v1.4.x and earlier shipped `bin/opencode`;
+ * v1.14+ renames the platform-specific binary to `bin/opencode.exe` for every
+ * OS via the postinstall script. Callers pass the binPath that matches their
+ * pinned version so a v1↔v2 swap can't silently install the wrong file.
+ */
+export declare function installOpencodeCli(params: {
+    binPath: string;
+}): Promise<string>;
+export declare function autoSelectModel(): string | undefined;

package/dist/agents/postRun.d.ts

@@ -0,0 +1,126 @@
+import { type AgentResult, type AgentRunContext, type AgentUsage, type PostRunIssues, type StopHookFailure } from "#app/agents/shared";
+import type { ToolState } from "#app/toolState";
+/**
+ * derive "agent picked a review mode but never produced visible output" from
+ * the literal facts on `toolState`. returns the selected mode when the gate
+ * should fire, `null` otherwise — pure read, no side effects, safe to invoke
+ * after every agent attempt.
+ *
+ * the gate is anchored to `hadProgressComment` so silent runs (non-issue
+ * events, dispatcher skipped seeding) don't fire a nudge there's no UI for.
+ *
+ * `Review` and `IncrementalReview` have different valid exits:
+ *   - Review: only `create_pull_request_review` counts. `report_progress` is
+ *     not a substitute — a Review run that exits with just a summary comment
+ *     has produced nothing reviewable on the PR. matches the hard-fail
+ *     message at `expected = "create_pull_request_review"` below.
+ *   - IncrementalReview: `report_progress` is a legitimate "no review
+ *     warranted" exit, so either toolState flag short-circuits.
+ * splitting per mode also closes the bypass where a subagent (e.g. a
+ * `task`-dispatched `loupe` lens) calls `report_progress` and silences
+ * the gate even though the orchestrator never submitted a review.
+ *
+ * `dispatchedMode` (the payload's pinned mode) backstops `selectedMode`,
+ * which is only set when the agent voluntarily calls `select_mode` — a
+ * review-dispatched run that never opts in would otherwise produce no review
+ * yet pass the gate, the exact silent outcome the gate exists to catch.
+ * `selectedMode` still wins when present: it reflects what actually ran.
+ */
+export declare function getUnsubmittedReview(toolState: ToolState, dispatchedMode?: string | undefined): "Review" | "IncrementalReview" | "TerraformCodeReview" | null;
+/**
+ * run the user-configured stop hook.
+ *
+ * parallel to `executeLifecycleHook` (which soft-fails with a warning), but
+ * returns structured output so agent harnesses can feed the failure back into
+ * the session as a resume prompt.
+ *
+ * - non-zero exit → `StopHookFailure`, actionable: the output is fed to the
+ *   agent so it can fix the underlying issue.
+ * - timeout / spawn error → null, treated as passed: we can't usefully ask the
+ *   agent to fix an infrastructure problem, and retrying would risk infinite
+ *   loops.
+ */
+export declare function executeStopHook(script: string): Promise<StopHookFailure | null>;
+export declare function buildStopHookPrompt(failure: StopHookFailure): string;
+export declare function buildSummaryStalePrompt(filePath: string): string;
+export declare function buildUnsubmittedReviewPrompt(mode: "Review" | "IncrementalReview" | "TerraformCodeReview"): string;
+export declare function collectPostRunIssues(ctx: AgentRunContext, options?: {
+    skipSummaryStale?: boolean;
+}): Promise<PostRunIssues>;
+export declare function buildPostRunPrompt(issues: PostRunIssues): string;
+/**
+ * terminal-only post-run finalize: re-checks the hard-fail gates after the
+ * agent has exited and converts a successful result to a hard-fail when
+ * `stopHook` or `unsubmittedReview` is still failing. used by harnesses
+ * that inject follow-up turns via a mechanism other than the resume
+ * callback (e.g. the Claude managed Stop hook + gate server). soft gates
+ * (`dirtyTree`, `summaryStale`) are intentionally not re-checked here —
+ * they never flip a successful run to failed.
+ */
+export declare function finalizeAgentResult<R extends AgentResult>(params: {
+    ctx: AgentRunContext;
+    result: R;
+}): Promise<R>;
+export declare function shouldRunReflection(mode: string | undefined): boolean;
+/**
+ * prompt for a dedicated post-run reflection turn nudging the agent to edit
+ * the rolling learnings file if it discovered anything worth persisting.
+ *
+ * this exists because passive "if you learned something, write it down"
+ * instructions baked into mode checklists are frequently ignored — the agent
+ * stays focused on the task and the meta-ask falls through. delivering it
+ * as its own resume turn, with nothing competing for attention, raises the
+ * fire rate substantially.
+ *
+ * the file is the single source of truth — there is no separate MCP tool
+ * call. the server reads the file at end-of-run and persists any edits to
+ * `Repo.learnings`.
+ *
+ * the prompt copy is shaped by repo-wide audits of the actual content the
+ * agent has been writing (issue #619 in infraweaver/app). recurring failure
+ * modes the framing pushes back on:
+ *  - massive multi-paragraph "bullets" that are really mini-articles
+ *  - facts anchored to moving repo state (PR / review / commit / branch
+ *    refs, dates, version pins, line numbers) that decay within weeks
+ *  - sections growing into giant flat lists with no internal structure,
+ *    forcing future runs to read kilobytes to find one fact
+ *
+ * single litmus delivered in the prompt: "would a future run on this repo
+ * do its work better because this bullet exists?". tool-quirk workarounds
+ * are explicitly allowed when the agent burned calls discovering the
+ * quirk this run — recording the workaround prevents next run from
+ * repeating the waste. tradeoff: the same quirk gets duplicated across
+ * repos, so when a quirk is fixed upstream in tool descriptions the
+ * per-repo bullets go stale and we have no batch-invalidation path.
+ */
+export declare function buildLearningsReflectionPrompt(filePath: string): string;
+/**
+ * shared post-run retry loop used by every agent harness.
+ *
+ * checks the post-run gates (stop hook + dirty tree), and if either is
+ * failing, invokes `resume` to let the agent fix and push in the same turn.
+ * bails at `MAX_POST_RUN_RETRIES` attempts. the `canResume` predicate is
+ * consulted before each retry — harnesses that can't re-enter the session
+ * (e.g. claude without a sessionId) return false here.
+ *
+ * an optional `reflectionPrompt` fires exactly once, after the gates first
+ * observe a clean state. it's a one-shot nudge (e.g. "update learnings if
+ * relevant"), not a gate, so it does not consume the gate-retry budget. if
+ * the reflection turn dirties the tree, the loop picks that up on the next
+ * iteration via the normal dirty-tree gate.
+ *
+ * stop hook must pass for the run to succeed; persistent hook failures are
+ * surfaced as `AgentResult.error`. dirty-tree-only failures preserve prior
+ * behavior: they're logged but don't fail the run.
+ */
+export declare function runPostRunRetryLoop<R extends AgentResult>(params: {
+    ctx: AgentRunContext;
+    initialResult: R;
+    initialUsage: AgentUsage | undefined;
+    resume: (context: {
+        prompt: string;
+        previousResult: R;
+    }) => Promise<R>;
+    canResume?: ((result: R) => boolean) | undefined;
+    reflectionPrompt?: string | undefined;
+}): Promise<AgentResult>;

package/dist/agents/reviewer.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Definition of the `loupe` named subagent — the constrained
+ * read-only worker dispatched by Build mode self-review and the in-Infraweaver
+ * /anneal multi-lens review.
+ *
+ * The contract: non-mutative + non-recursive.
+ *   allow: file reads, grep/glob, web search/fetch, read-only MCP queries,
+ *          read-only shell (git diff/log, cat, ls)
+ *   deny:  state-changing MCP tools, file writes, side-effectful shell, nested
+ *          subagent dispatch
+ *
+ * Enforcement is now belt-and-suspenders:
+ *   1. Machine-enforced PreToolUse gates intercept every state-mutating MCP
+ *      tool call originating from a subagent session and refuse it before
+ *      MCP runs. The deny set is derived per-run from each MCP tool's `mutates`
+ *      flag (`subagentDeniedToolNames` in action/mcp/server.ts), embedded into
+ *      action/agents/claudePretoolGate.ts (Claude Code's PreToolUse hook),
+ *      and action/agents/opencodePlugin.ts (opencode's tool.execute.before
+ *      hook). Followed PR #796 which added runtime backstops inside
+ *      checkout_pr / push_branch after a subagent-originated tool call
+ *      clobbered an unrelated PR branch in zed-industries/cloud.
+ *   2. The prose system prompt below as a backup against (a) tools added
+ *      to the MCP server without a corresponding deny-list update, and
+ *      (b) shell/git read-vs-write distinctions the static gate can't see.
+ *      It states the rule as a no-op-if-reverted invariant the model can
+ *      apply to any tool, including ones added after this comment was
+ *      written.
+ *
+ * Historical note: per-agent `disallowedTools` in claude-code is upstream-
+ * broken for subagent-spawned tool calls (anthropics/claude-agent-sdk-
+ * typescript#172, open as of Mar 2026), which is why the gate runs at
+ * PreToolUse rather than tool-registration time.
+ */
+export declare const REVIEWER_AGENT_NAME = "loupe";
+/**
+ * System prompt baked into the named reviewer subagent. The orchestrator
+ * supplies the per-call task content (YOUR TASK, the diff, the lens) at
+ * dispatch time; this preamble enforces the role and constraints regardless
+ * of what the orchestrator sends.
+ */
+export declare const REVIEWER_SYSTEM_PROMPT: string;