terramend 0.2.0

package/README.md

@@ -0,0 +1,145 @@
+# Terramend
+
+[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](LICENSE)
+[![CI](https://github.com/terramend/terramend/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/terramend/terramend/actions/workflows/test.yml)
+[![Release](https://img.shields.io/github/v/release/terramend/terramend?sort=semver)](https://github.com/terramend/terramend/releases)
+[![Use this GitHub Action](https://img.shields.io/badge/GitHub%20Marketplace-Use%20this%20Action-2ea44f?logo=github)](https://github.com/marketplace/actions/terramend)
+
+**Terramend brings your Terraform up to best practice — automatically, as reviewable pull requests.**
+
+Terramend is an open-source ([AGPL-3.0](#licence)) GitHub Action and agent runtime. Point it at a
+repository and it scans the Terraform with standard deterministic tools, then opens **one scoped,
+reviewable pull request per concern** that fixes the issue and **proves it fixed** by re-scanning the
+branch (✗ → ✓). It never auto-merges — a human always reviews.
+
+- **It proves its own fixes.** The PR body records `✗ → ✓ <rule> resolved`, produced by re-running the
+  same deterministic scanners on the branch. Anyone can reproduce it — evidence, not a claim.
+- **Tools decide, the LLM assists.** Findings come from `terraform fmt`/`validate`, tflint, Trivy and
+  Checkov — not the model's opinion. The agent only applies the minimal, constrained fix.
+- **One scoped PR per concern.** Small, reviewable diffs on stable `remediate/<id>` branches. Re-runs
+  update the existing PR rather than opening duplicates.
+- **Guardrails enforced in code, not prompts.** Terraform-only edits, no inlined secrets, no destroying
+  stateful data, never auto-merges — all fail-closed at push time.
+- **Module-aware.** Fixes land at the module source, version upgrades arrive as scoped `chore(deps)`
+  PRs, and resource piles become module calls only when a pure-`moved` plan proves the refactor is a
+  no-op.
+- **Bring your own key, no hosted backend.** Supply your own LLM key, pointed at an approved endpoint
+  where data residency matters. Nothing leaves your runner that you didn't configure.
+
+## Quickstart
+
+```yaml
+name: Terramend — Terraform remediation
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 6 * * 1" # weekly drift sweep
+
+permissions:
+  contents: write       # push the remediation branch
+  pull-requests: write  # open the PR
+
+jobs:
+  remediate:
+    runs-on: ubuntu-latest
+    steps:
+      # Pin third-party actions to a commit SHA — a tag can be force-repointed.
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+
+      # install the Terraform best-practice toolchain (absent tools are skipped, never fatal)
+      - uses: hashicorp/setup-terraform@b9cd54a3c349d3f38e8881555d616ced269862dd # v3
+      - uses: terraform-linters/setup-tflint@90f302c255ef959cbfb4bd10581afecdb7ece3e6 # v4
+      - uses: aquasecurity/setup-trivy@81e514348e19b6112ce2a7e3ecbafe19c1e1f567 # v0.3.1
+      - run: pipx install checkov
+
+      - name: Run Terramend
+        uses: terramend/terramend@v0
+        with:
+          mode: remediate
+          severity_threshold: medium   # only act on medium+ concerns
+          max_prs: 1                   # one scoped PR per run
+        env:
+          # bring your own LLM key (BYOK)
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          GITHUB_TOKEN: ${{ github.token }}
+```
+
+> **Ready-to-use workflows:** [`examples/`](examples/) has copy-pasteable workflows — scheduled
+> [remediation](examples/remediate.yml), [generation](examples/generate-terraform.yml),
+> [comment-triggered fixes](examples/comment-fix.yml), and the full
+> [SARIF + plan-gate + policy setup](examples/remediate-advanced.yml).
+
+## How it works
+
+```mermaid
+flowchart LR
+  A[Scan<br/>fmt · validate · tflint<br/>Trivy · Checkov] --> B[Concerns<br/>severity-ranked,<br/>grouped]
+  B --> C[Fix<br/>minimal change,<br/>Terraform-only]
+  C --> D[Validate<br/>fmt · validate · tflint]
+  D --> E[Plan gate<br/>optional, with creds]
+  E --> F[Open one<br/>scoped PR]
+  F --> G[Re-scan branch<br/>✗ → ✓ proof]
+  G -.->|regression / needs-human| H[Label for a human]
+```
+
+**Scanners find the problem, the agent applies the minimal fix, and the scanners verify it** before a
+single PR is opened. Coverage is inherited, not reinvented: findings come from the scanners Terramend
+runs (Checkov's 1,000+ policies, Trivy's AVD checks, tflint's provider rulesets, `fmt`/`validate`), so
+new upstream checks show up the day you update the scanner. The PR's **Validation (✗ → ✓)** section is
+the part you can trust without trusting Terramend — re-run the same scanners on the branch and
+reproduce it. Higher-risk fixes (a regression, a stateful destroy/replace, a large blast radius, a
+non-deterministic plan) get a `> [!CAUTION]` banner and a `needs-human` label.
+
+## How Terramend compares
+
+| | Reports findings | Fixes the code | Proves the fix | Opens a PR | Auto-merges |
+| --- | :---: | :---: | :---: | :---: | :---: |
+| **Scanners** (Checkov, Trivy, tfsec, tflint) | ✅ | ❌ | ❌ | ❌ | — |
+| **Plan orchestrators** (Atlantis, Digger) | ❌ | ❌ | ❌ | comments on yours | ❌ |
+| **Dependency bots** (Dependabot, Renovate) | ✅ (deps) | ✅ (version bumps) | ❌ | ✅ | optional |
+| **Auto-fix AI bots** | partial | ✅ | rarely | ✅ | often |
+| **Terramend** | ✅ | ✅ | ✅ (✗ → ✓ re-scan) | ✅ (one per concern) | **never** |
+
+## Documentation
+
+| Doc | What's in it |
+| --- | --- |
+| [Action inputs & outputs](docs/action-inputs.md) | The complete `action.yml` reference (generated — never drifts) |
+| [Configuration](docs/configuration.md) | Modes, comment-scoped runs, scoping out findings, the plan gate & OIDC roles, BYOK, SARIF, modules |
+| [Security model](docs/security-model.md) | The code-level guardrails and the trust/data-privacy story |
+| [MCP server](docs/mcp.md) | `terramend mcp` in your IDE + pairing with HashiCorp's terraform-mcp-server |
+| [Tools](docs/tools.md) | Every MCP tool the agent uses, and the CLI binaries they shell out to |
+| [Supported models](docs/models.md) | The model catalog and how selection works (generated) |
+
+## Support
+
+- **Getting started / usage** — this README, the [docs](docs/), and the [`examples/`](examples/) workflows.
+- **Bug reports & feature requests** — open a [GitHub issue](https://github.com/terramend/terramend/issues).
+- **Security vulnerabilities** — **don't** use a public issue; see [Security](#security) below.
+
+## Contributing
+
+Contributions are welcome. Terramend standardises on **Node 24** and **pnpm 11**:
+
+```bash
+corepack enable
+pnpm install --frozen-lockfile
+pnpm typecheck
+pnpm test
+```
+
+All contributions are accepted under the [Contributor License Agreement](CLA.md) (enforced by the CLA
+Assistant on your first PR), and releases are automated from [Conventional Commits](https://www.conventionalcommits.org)
+via release-please. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the full development, commit, and
+action-pinning conventions.
+
+## Security
+
+Terramend runs AI coding agents with write access to repositories and CI secrets, and is positioned for
+security- and compliance-sensitive use. **Please don't open public issues for vulnerabilities** — report
+them privately via [GitHub Security Advisories](https://github.com/terramend/terramend/security/advisories/new).
+See [`SECURITY.md`](SECURITY.md) for scope, supported versions, and response targets.
+
+## Licence
+
+Terramend is licensed under the **GNU Affero General Public License v3.0 or later** (AGPL-3.0-or-later).

package/dist/agents/claude.d.ts

@@ -0,0 +1,73 @@
+import { type AgentResult, type AgentRunContext } from "#app/agents/shared";
+import type { TodoTracker } from "#app/utils/todoTracking";
+export declare const CLAUDE_EXEC_TOOL_DENY_RULES: string[];
+export declare function writeMcpConfig(ctx: AgentRunContext): string;
+/**
+ * Build the `--agents` JSON definition for the `reviewfrog` subagent.
+ *
+ * The Claude Code path always runs against an Anthropic model (see
+ * resolveAgent), so we hardcode the cheaper-sibling downshift: lenses run
+ * on Sonnet, the orchestrator stays on whatever model `--model` was passed.
+ *
+ * Per-call model override is also possible (Task tool's `model` arg accepts
+ * 'sonnet' | 'opus' | 'haiku') and takes precedence over what's set here —
+ * we don't pass it; the per-subagent `model` field is the right default.
+ *
+ * The non-mutative + non-recursive contract is enforced by the prose system
+ * prompt baked into the agent — see action/agents/reviewer.ts for why we
+ * no longer wire per-agent `disallowedTools` here.
+ */
+export declare function buildAgentsJson(): string;
+export declare function stripProviderPrefix(specifier: string): string;
+type RunParams = {
+    label: string;
+    cmd: string;
+    args: string[];
+    cwd: string;
+    env: Record<string, string | undefined>;
+    todoTracker?: TodoTracker | undefined;
+    onActivityTimeout?: (() => void) | undefined;
+    onToolUse?: ((event: {
+        toolName: string;
+        input: unknown;
+    }) => void) | undefined;
+};
+type ClaudeRunResult = AgentResult & {
+    sessionId?: string | undefined;
+};
+/**
+ * Return the tail of `text` capped at `maxCodeUnits` UTF-16 code units,
+ * dropping any partial first line. used in the exit-non-zero stdout fallback
+ * so we never surface a truncated NDJSON event to operators —
+ * `result.stdout.slice(-2048)` would otherwise cut mid-line and produce a
+ * syntactically broken JSON fragment. code units rather than bytes because
+ * `String.prototype.slice` operates on UTF-16 units; for multi-byte UTF-8
+ * content the effective byte budget can be up to 4× the nominal limit.
+ */
+export declare function tailLines(text: string, maxCodeUnits: number): string;
+export declare function runClaude(params: RunParams): Promise<ClaudeRunResult>;
+/**
+ * managed Stop hook. swaps the old `--resume <sessionId>` follow-up
+ * subprocesses (reflection + every gate retry — cost audit on PR #792
+ * showed reflection alone burned ~$0.85 / 111K cache_write per Opus run,
+ * almost all of it wasted re-running `getAttachmentMessages` in the fresh
+ * process) for a `{decision: "block", reason: ...}` injection inside the
+ * live `queryLoop`. existing session context is already in the prompt
+ * cache so only the new reason text is fresh cache_write.
+ *
+ * the script is intentionally minimal — all decision logic lives in the
+ * sidecar gate server (`gateServer.ts`), which reads live `ctx.toolState`
+ * mutations from the same process the MCP server runs in. budget +
+ * one-shot tracking lives there too, so re-fires across multiple stops in
+ * one session are safe. claude-code's 8-consecutive-block override is the
+ * last-line backstop.
+ */
+export declare function buildStopHookScript(): string;
+export interface ManagedSettingsParams {
+    ctx: AgentRunContext;
+    stopHookPath: string | null;
+    pretoolGateScriptPath: string;
+}
+export declare function buildManagedSettings(params: ManagedSettingsParams): Record<string, unknown>;
+export declare const claude: import("#app/agents/shared").Agent;
+export {};

package/dist/agents/claudePretoolGate.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Claude Code `PreToolUse` hook source — written into `ctx.tmpdir` at runtime
+ * and registered via a tmpdir-scoped `settings.json` referenced by
+ * `--settings <path>` (see action/agents/claude.ts).
+ *
+ * Closes the subagent → state-mutating MCP tool path that motivated the
+ * 2026-05-18 zed-industries/cloud incident (`reviewfrog` lens called
+ * `checkout_pr` mid-review and the orchestrator's next push clobbered an
+ * unrelated branch). Pairs with the `tool.execute.before` hook in
+ * action/agents/opencodePlugin.ts; both runtimes share the deny list at
+ * action/agents/subagentToolGates.ts.
+ *
+ * PreToolUse hook contract (verified against yasasbanukaofficial/claude-code
+ * `src/utils/hooks/hooksConfigManager.ts` and `src/utils/hooks.ts`):
+ *   - stdin: JSON with `hook_event_name: "PreToolUse"`, `tool_name`,
+ *     `tool_input`, `tool_use_id`, `session_id`, `cwd`, `transcript_path`,
+ *     and crucially `agent_id` / `agent_type` populated when the call
+ *     originates from a subagent (set by the SDK when a Task/Agent
+ *     dispatches a tool — see `createBaseHookInput` in claude-code source).
+ *   - exit 0 → allow, no output shown
+ *   - exit 2 → block tool call AND show stderr to model (this is the path
+ *     we want for the deny case — the subagent gets a clear refusal it can
+ *     reason about and pick a different action)
+ *   - other → show stderr to user only, continue with tool call
+ *
+ * The hook itself is intentionally tiny: stdin → JSON → check `agent_id`
+ * presence + `tool_name` against the deny list → exit 0 or 2. No deps.
+ *
+ * Why the script source is a string template, not a separate `.ts` file
+ * shipped with the action: the action runs as a published npm package; at
+ * install time we don't have the source on disk in a stable place. Embedding
+ * the source into `dist/main.mjs` and writing it out per-run keeps the path
+ * inside `ctx.tmpdir` (where `--settings` can find it) and survives bundle
+ * minification.
+ */
+/**
+ * The pinned `@anthropic-ai/claude-code` version against which the subagent
+ * gate's `agent_id` discriminator was last verified (see the contract notes in
+ * the gate source below). The gate fails OPEN for subagents if claude-code ever
+ * stops populating `agent_id` in the PreToolUse hook payload, so a version bump
+ * must be paired with a re-verification of `createBaseHookInput`.
+ *
+ * `claudePretoolGate.test.ts` asserts this equals the version pinned in
+ * `package.json` — that test fails on any bump, forcing the re-verification
+ * before the pin and this constant are updated together.
+ *
+ * 2.1.170 verified 2026-06-10 against the schema embedded in the shipped
+ * binary: the base hook input declares `agent_id` as optional with the
+ * describe-text "Present only when the hook fires from within a subagent
+ * (e.g., a tool called by an AgentTool worker). Absent for the main thread,
+ * even in --agent sessions." — exactly the discriminator the gate relies on.
+ */
+export declare const CLAUDE_CODE_AGENT_ID_VERIFIED_VERSION: "2.1.170";
+/**
+ * Source written to `<ctx.tmpdir>/terramend-pretool-gate.mjs`. Plain ESM,
+ * no TypeScript, no dependencies — node executes it directly via the
+ * `#!/usr/bin/env node` shebang and the executable bit set by the harness.
+ */
+export declare const CLAUDE_PRETOOL_GATE_FILENAME: "terramend-pretool-gate.mjs";
+export declare const CLAUDE_PRETOOL_GATE_SOURCE: string;
+/**
+ * Settings JSON shape registered via `claude --settings <path>`. The
+ * matcher `^mcp__terramend__` is treated as a regex by claude-code's
+ * `matchesPattern` helper (anything outside `[a-zA-Z0-9_|]` triggers the
+ * regex branch — verified in src/utils/hooks.ts), so this anchors at the
+ * start of the tool name and fires for every Terramend MCP tool. We narrow
+ * inside the script itself rather than declaring per-tool matchers because
+ * the deny list is the source of truth.
+ *
+ * The hook process inherits the parent's PATH, so `node` resolves to the
+ * runner's node binary; the `--settings` flag accepts either a path or a
+ * literal JSON string per claude-code source `src/main.tsx` (`Path to a
+ * settings JSON file or a JSON string`), but we use a path so the script
+ * and its config sit side-by-side under `ctx.tmpdir`.
+ *
+ * `execToolDenyRules` are the native exec tools (Bash/Monitor/REPL/Workflow +
+ * their `Agent(...)` forms) to deny at a settings-source rule — the
+ * authoritative, bypass-immune layer. `--disallowedTools` alone (a `cliArg`
+ * deny) was observed to leak under `--dangerously-skip-permissions`, so the
+ * deny is carried here too. Both consumers use both returned fields: the flag
+ * `--settings` JSON (covers non-CI runs) writes the whole object, and
+ * `buildManagedSettings` (CI, /etc managed settings) spreads `hooks` and folds
+ * `permissions.deny` into its richer deny list.
+ */
+export declare function buildClaudePretoolGateSettings(scriptAbsolutePath: string, execToolDenyRules: string[]): {
+    hooks: {
+        PreToolUse: Array<{
+            matcher: string;
+            hooks: Array<{
+                type: "command";
+                command: string;
+                timeout?: number;
+            }>;
+        }>;
+    };
+    permissions: {
+        deny: string[];
+    };
+};

package/dist/agents/gateServer.d.ts

@@ -0,0 +1,7 @@
+import { type AgentRunContext } from "#app/agents/shared";
+export interface GateServerHandle {
+    url: string;
+    token: string;
+    [Symbol.asyncDispose]: () => Promise<void>;
+}
+export declare function startGateServer(ctx: AgentRunContext): Promise<GateServerHandle>;

package/dist/agents/index.d.ts

@@ -0,0 +1,6 @@
+import type { Agent } from "#app/agents/shared";
+export type { Agent, AgentUsage } from "#app/agents/shared";
+export declare const agents: {
+    claude: Agent;
+    opencode: Agent;
+};

package/dist/agents/nativeFsDenies.d.ts

@@ -0,0 +1,28 @@
+/** worktree-relative blanket WRITE deny for the entire `.git` tree, in
+ * OpenCode Wildcard dialect (`*` compiles to regex `.*`, matching `/`
+ * recursively — see packages/core/src/util/wildcard.ts). spread into the
+ * `edit` ruleset after a `"*": "allow"` baseline — `evaluate` is
+ * last-match-wins by key order, so the deny keys must follow the wildcard
+ * allow.
+ *
+ * four patterns, because the root-anchored descendants glob only matches
+ * paths under a root `.git` *directory* — it misses `.git` when it's a gitfile
+ * (worktree / submodule layouts: a regular file whose `gitdir:` line redirects
+ * git metadata) and misses nested gitfiles (a `.git` inside a subdirectory).
+ * rewriting either pointer is the same code-exec surface (`core.hooksPath`,
+ * clean/smudge filters, credential.helper) the blanket deny exists to seal, so
+ * we cover the gitfile itself and any nested `.git` too. */
+export declare const GIT_NATIVE_WRITE_DENY_OPENCODE: Record<string, "deny">;
+/** worktree-relative narrow READ deny (`.git/config` only), in OpenCode
+ * Wildcard dialect. spread into the `read` ruleset after the `"*": "allow"`
+ * baseline. */
+export declare const GIT_NATIVE_READ_DENY_OPENCODE: Record<string, "deny">;
+/** Claude `permissions.deny` entries for the blanket `.git` WRITE deny —
+ * mirrors {@link GIT_NATIVE_WRITE_DENY_OPENCODE}. `**` is recursive. the exact
+ * `.git` entry plus the recursive-prefix gitfile entry cover the gitfile
+ * pointer (root + nested) that the root-anchored descendants glob alone misses;
+ * the recursive-prefix descendants entry covers nested gitdirs. */
+export declare const GIT_NATIVE_WRITE_DENY_CLAUDE: string[];
+/** Claude `permissions.deny` entries for the narrow `.git/config` READ deny,
+ * one per read/enumerate tool — mirrors {@link GIT_NATIVE_READ_DENY_OPENCODE}. */
+export declare const GIT_NATIVE_READ_DENY_CLAUDE: string[];

package/dist/agents/opencode.d.ts

@@ -0,0 +1,231 @@
+/**
+ * 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 Terramend 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 Terramend server injected via `mcp.<name> = { type: "remote", url }`
+ *   - ASKPASS for git auth
+ *   - codex auth materialization + post-hook writeback
+ *   - reviewfrog 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 { 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. reviewfrog).
+     * 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;
+}
+export declare function newTurn(): TurnAccumulator;
+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>;
+    /** rolling stderr tail from the server process (for diagnostics). */
+    recentStderr: string[];
+    diagnostic: AgentDiagnostic;
+}
+/**
+ * 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.
+ */
+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 {};