infraweaver 0.1.0

package/src/skills/terraform-best-practices/SKILL.md

@@ -0,0 +1,379 @@
+---
+name: terraform-best-practices
+description: Fix Terraform to best practice from a scanner concern — the minimal, correct change for a trivy/checkov/tflint/fmt/validate finding, plus the security, structure, and naming conventions a good fix must follow. Use when remediating Terraform, applying a `terraform_scan` concern, or generating new HCL that must start compliant.
+---
+
+# Terraform best-practice remediation
+
+You are fixing Terraform against a **concern** emitted by `terraform_scan` (or
+`terraform_validate`). Each concern names the producing `source`, a `rule_id`,
+the `location` (file + line), an `evidence` string (what's wrong), and often a
+`remediation_hint`. Your job is the **smallest correct change** that clears that
+concern — nothing more.
+
+## The remediation loop
+
+1. **Read the concern.** The `rule_id` tells you the class of problem; the
+   `evidence` tells you the specifics; `location.file:line` tells you where.
+2. **Open the file and understand the surrounding resource** before editing.
+   Don't fix a line in isolation — know which `resource` / `module` / `variable`
+   block it belongs to.
+3. **Apply the minimal fix** (see the catalogue below). Touch only `*.tf` /
+   `*.tfvars`. Do not reformat, reorder, or "improve" unrelated code — that
+   buries the real fix and breaks the one-concern-per-PR contract.
+4. **Re-validate** with `terraform_validate`. If it doesn't pass, your fix is
+   incomplete or introduced a new problem — fix that before opening a PR.
+5. **Confirm the concern cleared** by re-running `terraform_scan` on the branch.
+   The concern's `id` must be gone. If it isn't, say so honestly.
+
+## What a good fix looks like, by source
+
+- **`terraform-fmt:unformatted`** — run `terraform fmt` on the named file. This
+  is whitespace/alignment only; never combine it with a behavioural change in
+  the same PR.
+- **`tflint:*`** — idiomatic-HCL and provider-rule issues. Common fixes: remove
+  unused `variable`/`local`/`data` declarations; pin deprecated syntax forward;
+  add missing required provider/version constraints. Follow the rule's link.
+- **`trivy:*` / `checkov:*`** — security misconfiguration. These are the
+  high-value fixes. Apply the **secure default**, e.g.:
+  - **encryption at rest** — add the `server_side_encryption_configuration` /
+    `encryption` block (S3, RDS, EBS, etc.); prefer a CMK where the rule asks.
+  - **no public access** — set `block_public_acls`/`block_public_policy` etc. to
+    `true`; remove `acl = "public-read"`; tighten `0.0.0.0/0` ingress to the
+    real CIDR or a referenced security group.
+  - **least privilege** — replace `"*"` actions/resources in IAM policies with
+    the specific actions/ARNs actually needed.
+  - **logging / versioning** — add the access-logging, audit, or versioning
+    block the rule requires.
+- **`terraform-validate:*`** — a correctness error (bad reference, type
+  mismatch, missing required argument). Fix the actual HCL so `terraform
+validate` passes.
+
+## Secure-default catalogue (by problem class)
+
+Copy-pasteable shapes for the highest-frequency security concerns. These target
+the **AWS provider v5+** layout (encryption / versioning / ACL / public-access
+are standalone resources, not inline `aws_s3_bucket` blocks). Adapt resource and
+attribute names to the block the concern points at — don't paste blindly.
+
+### Encryption at rest
+
+S3 — server-side encryption with a customer-managed key (preferred over `AES256`
+when the rule asks for a CMK):
+
+```hcl
+resource "aws_s3_bucket_server_side_encryption_configuration" "this" {
+  bucket = aws_s3_bucket.this.id
+  rule {
+    apply_server_side_encryption_by_default {
+      sse_algorithm     = "aws:kms"
+      kms_master_key_id = aws_kms_key.this.arn
+    }
+    bucket_key_enabled = true
+  }
+}
+```
+
+EBS volume / root device: `encrypted = true` (add `kms_key_id` when a CMK is
+required). RDS: `storage_encrypted = true` (+ `kms_key_id`). When `aws:kms` needs
+a key and none exists, reference an existing `aws_kms_key`/`var.*`; only add a new
+`aws_kms_key` resource if the stack genuinely has none — keep `AES256` if the rule
+is satisfied by SSE-S3 alone.
+
+### Block public access
+
+S3 — the four-flag public-access block is the canonical fix; wire it to the same
+bucket:
+
+```hcl
+resource "aws_s3_bucket_public_access_block" "this" {
+  bucket                  = aws_s3_bucket.this.id
+  block_public_acls       = true
+  block_public_policy     = true
+  ignore_public_acls      = true
+  restrict_public_buckets = true
+}
+```
+
+Also remove any `acl = "public-read"` (move to a private `aws_s3_bucket_acl` if an
+ACL is needed at all).
+
+### Network ingress
+
+Replace world-open ingress with the real source. Never leave `0.0.0.0/0` on admin
+ports (22/3389/database ports):
+
+```hcl
+ingress {
+  from_port       = 443
+  to_port         = 443
+  protocol        = "tcp"
+  cidr_blocks     = [var.allowed_cidr]      # or: security_groups = [aws_security_group.lb.id]
+}
+```
+
+### IAM least privilege
+
+Replace wildcard `Action`/`Resource` with the specific actions and ARNs the
+workload actually uses. If you can't determine the exact set from the surrounding
+code, this is a human decision — report it rather than guessing a narrow policy
+that breaks the stack.
+
+### Versioning & logging
+
+S3 versioning and access logging as standalone resources:
+
+```hcl
+resource "aws_s3_bucket_versioning" "this" {
+  bucket = aws_s3_bucket.this.id
+  versioning_configuration { status = "Enabled" }
+}
+```
+
+### EC2 instance metadata (IMDSv2)
+
+Require token-backed metadata to close the SSRF→credential path:
+
+```hcl
+metadata_options {
+  http_endpoint = "enabled"
+  http_tokens   = "required"
+}
+```
+
+### Deprecations & style
+
+- **Provider v4→v5 S3 split** — inline `server_side_encryption_configuration` /
+  `versioning` / `acl` / `logging` blocks on `aws_s3_bucket` are deprecated; move
+  each to its standalone resource (above). Don't bump the provider major version
+  as a side effect of a remediation — if a fix genuinely requires a newer
+  provider, report that as a blocker.
+- **`terraform-fmt:unformatted`** — run `terraform fmt` on the named file only;
+  never fold a formatting pass into a behavioural fix.
+
+## Don't over-reach
+
+- **Smallest change that clears the concern.** Add the missing block; don't
+  refactor the resource, rename it, or restructure the file around it.
+- **Don't add speculative hardening** the concern didn't ask for (extra KMS keys,
+  new modules, blanket tagging) — that's scope creep and buries the real fix.
+- **Don't widen or bump version pins** to reach a resource or attribute.
+- **One concern's blast radius only.** If the secure default would break the
+  stack or needs a human call (a real CIDR, an IAM action set, a CMK policy),
+  stop and report it instead of opening a broken or guessed PR.
+
+## Conventions every fix must honour
+
+- **Variables over hardcoded values.** Don't bake an account id, region, CIDR,
+  or ARN into a fix — reference an existing `var.*`/`local.*`, or add a typed
+  `variable` with a sensible `default` and `description` when one is genuinely
+  needed.
+- **Pin versions.** When adding a provider or module, include a version
+  constraint. Never widen an existing pin as a side effect.
+- **Approved modules first.** Call `list_modules` — if a catalogue is configured,
+  prefer the catalogue module (a registry module or a local/house module) + its
+  exact variable names over inlining a raw resource, and pin its `version`. See
+  _Using Terraform modules_ below.
+- **No secrets in HCL or state.** Never introduce a literal credential. If the
+  fix needs a secret, reference a variable or a secrets data source.
+- **Idempotent, reviewable diffs.** The diff should read so a senior engineer
+  approves it without hesitation: one concern, one rationale, no churn.
+
+## Gold standards (the bar every fix is measured against)
+
+These are the non-negotiable defaults a "good" Terraform change embodies. A fix
+should never _move away_ from any of these, and should move _toward_ them when
+the concern is adjacent:
+
+- **Encrypt everything, at rest and in transit.** Storage encrypted (CMK where
+  the data is sensitive); TLS-only endpoints; no plaintext in state.
+- **Private by default.** No `0.0.0.0/0` to admin/database ports; public access
+  blocked unless the resource's whole purpose is to be public (and then scoped).
+- **Least privilege.** No `"*"` IAM actions/resources; scope to what the workload
+  uses. Prefer a referenced role/policy over an inline wildcard.
+- **Pinned + reproducible.** `required_version` and every `required_providers` /
+  module `version` constrained (`~>`); no floating `latest`.
+- **Parameterised, not hardcoded** (see below).
+- **Tagged + named consistently.** Match the repo's existing tag keys and naming
+  scheme; don't invent a new convention.
+- **Observable.** Logging / versioning / audit trails enabled where the provider
+  supports them and the concern is about data durability or traceability.
+- **Idempotent + deterministic.** No `timestamp()`/`uuid()`/unkeyed `random_*`
+  driving a value that lands in state — it produces a perpetual diff.
+
+When in doubt, the secure/idiomatic default from the catalogue above IS the gold
+standard. Don't gold-plate beyond the concern, but never regress one of these.
+
+## Parameterize, don't hardcode
+
+A value that varies by environment, account, or deployment must be a `variable`
+or `local`, never a literal baked into a resource:
+
+- **Reuse first.** If the repo already exposes `var.region` / `local.tags` /
+  `var.vpc_cidr`, reference it — don't introduce a parallel one.
+- **Introduce a typed variable** when none fits: give it a `type`, a
+  `description`, and a safe `default` only when a default is genuinely sane
+  (secrets and account-specific ids get NO default). Match the repo's existing
+  file layout — add to `variables.tf` if the repo separates them, otherwise keep
+  it next to the resource as the repo does.
+- **Derive with `locals`.** Computed/repeated values (a name prefix, a merged tag
+  map) belong in `locals`, referenced everywhere — not copy-pasted.
+- **Never inline a secret, account id, ARN, or CIDR.** A "fix" that pastes a
+  literal credential is itself a finding (and the secret-scan guardrail will
+  block the push). Reference a variable or a secrets data source.
+
+## Using Terraform modules (registry, private git libraries, your own)
+
+Prefer a well-formed module over a pile of raw resources when one cleanly fits —
+it carries the secure defaults for you. **Always call `list_modules` first**; it
+returns three things: the operator's `module_catalogue`, the
+`discovered_house_modules` (local modules already used in THIS repo), and a note.
+
+Four source kinds you'll encounter, each pinned differently:
+
+- **Public registry module** — `terraform-aws-modules/vpc/aws`. Pin with a
+  `version = "~> 5.0"` argument. The big public collections
+  ([terraform-aws-modules](https://registry.terraform.io/namespaces/terraform-aws-modules):
+  `vpc`, `s3-bucket`, `rds`, `eks`, …) are the default when nothing is configured.
+  A registry submodule is `…/aws//modules/log-group`.
+- **Private registry module** — a host-prefixed address like
+  `app.terraform.io/acme/networking/aws` (HCP Terraform / Terraform Enterprise / an
+  org registry). Pin with a `version` argument, exactly like a public registry
+  module. `terraform_module_lookup` reads its real interface when the run supplies a
+  `registry_token` (+ `registry_host`) — the token is only ever sent to the
+  allow-listed host. (There is no private `search`; look these up by exact address.)
+- **Private git module library** — e.g.
+  `git::https://github.com/acme/tf-modules.git//aws/s3?ref=s3-v0.1.2`. The
+  `//aws/s3` selects the module within the repo and **`?ref=s3-v0.1.2` IS the
+  version pin** (git modules have no `version` argument). Keep the exact `ref`;
+  never float it. Many orgs (e.g. UKHSA's `data-integration-terraform-modules`)
+  ship a whole library this way, tagged per-module.
+- **House module** — one of the repo's own `modules/<name>` dirs. `list_modules`
+  surfaces these under `discovered_house_modules` with their caller files — reuse
+  the existing one with its **real variable names** (read its `variables.tf`)
+  rather than re-implementing it.
+
+Rules: use the module's **exact variable names**, set the secure-relevant inputs
+the concern is about, and keep the version **pinned**. Don't introduce a module
+mid-remediation just to "improve" things — using a module is right when
+_generating_ new infra or when the fix is genuinely a module swap; for a one-line
+security fix on an existing raw resource, fix the resource in place.
+
+Prefer authoritative registry knowledge over recalling it from memory — it moves
+faster than any training data, and a fix written against a remembered-but-renamed
+argument breaks `plan`. Built in and always on: `terraform_module_lookup` reads a
+published module's real inputs/outputs + resolved version, `terraform_module_search`
+finds published modules to reuse (pass your org's namespace to surface your own),
+`terraform_version_currency` reports versions, and `terraform_provider_schema` gives
+the installed provider's arguments. When the **`terraform` MCP server** is registered
+(the `terraform_mcp` input), it adds the deeper provider/resource documentation
+surface on top — prefer it for provider argument shapes.
+
+### Authoring a reusable module (standard layout)
+
+When you GENERATE a reusable module, follow the conventional layout real module
+libraries use so it's drop-in familiar:
+
+- `main.tf` (resources), `variables.tf` (every input typed, with a `description`
+  and a `validation` block where it helps), `outputs.tf`, `versions.tf` /
+  `providers.tf` (`required_version` + `required_providers` pinned), `README.md`
+  (usage + inputs/outputs), and a `CHANGELOG.md` if the repo versions modules.
+- Do **not** generate `examples/` fixtures. Document usage in the module's
+  `README.md` instead; test coverage comes from the opt-in terratest scaffold
+  (see below), which plans the module directly.
+
+### Module-source-aware fixes
+
+Before fixing a concern, call `terraform_module_graph` to see where the file
+lives in the module call-graph:
+
+- **Concern inside a LOCAL module dir** (listed in `local_module_dirs`): fix it
+  **once at the module source**. The fix propagates to every caller — do not
+  patch each call site. Note the callers in the PR body so a reviewer sees the
+  blast radius.
+- **Concern that would require editing a REGISTRY / git / remote module**: that
+  source lives outside this repo — you **cannot** fix it here. Do **not** vendor
+  the module or fork it inline. Instead report it (open an issue / PR comment)
+  naming the upstream module + version and the concern, so a human routes it.
+
+### Modularization as remediation (M2)
+
+`module_extraction_candidates` finds clusters of raw resources that should be a
+module call, each matched against the repo's house modules (real resource-type
+signature + `required_variables`) and the operator's `module_catalogue`. Turn a
+candidate into a refactor PR under this contract:
+
+- **One PR per cluster**, branch `remediate/modularize-<cluster file/prefix>` —
+  never mix two clusters or a behavioural fix into a modularization PR.
+- Replace the cluster's raw resources with ONE `module` block calling the
+  candidate (pin the version for registry sources; wire the module's REAL
+  variable names from `required_variables` / `terraform_module_interface` for a
+  local module, or `terraform_module_lookup` for a registry-sourced one).
+- **Preserve state with `moved {}` blocks** — one per resource, mapping the old
+  address to its new `module.<name>.` address:
+
+  ```hcl
+  moved {
+    from = aws_s3_bucket.logs
+    to   = module.logging.aws_s3_bucket.this
+  }
+  ```
+
+- **The gate:** the PR may proceed only when `terraform_validate` passes AND
+  `terraform_plan` reports `refactor_safe: true` (a pure-move plan — zero
+  add/change/destroy). Anything else means a moved block is wrong or the module
+  diverges from the raw resources — fix that or report it; never accept
+  resource churn as "the refactor".
+- A required variable you can't derive from the existing attributes is a
+  **PR question for the reviewer**, never a guessed value.
+
+### Version currency (provider + module upgrades)
+
+`terraform_version_currency` reports which pinned providers and registry modules
+trail the registry's latest stable version, and which registry modules are
+unpinned. Turn its rows into upgrade PRs under this contract:
+
+- **One `chore(deps)` PR per upgrade group** — never mix a version bump with a
+  behavioural fix; a bump PR must read as "only the constraint changed".
+- **Minor/patch bumps** (`outdated` with `majors_behind: 0`) may proceed
+  autonomously: update the `version` constraint to admit `newest_satisfying` →
+  `latest`, then prove it with `terraform_validate` (and `terraform_plan` when
+  credentials exist).
+- **Major bumps** (`majors_behind > 0`) mean the provider/module interface may
+  have changed — apply only with the `needs-human` label, and consult
+  `terraform_module_interface` / `terraform_provider_schema` for what moved.
+- **Unpinned registry modules**: pin to the reported `latest` (`version = "~> X.Y"`),
+  one PR for all unpinned modules in a file group — pinning is low-risk and sweeps well.
+- An upgrade whose `terraform_plan` shows **destructive changes is never auto** —
+  escalate with the plan excerpt in the PR body.
+
+## Tests for modules
+
+Infraweaver does **not** create or edit `examples/` fixtures — leave any the repo
+already ships untouched. Module test coverage is **opt-in** via the `terratest`
+input:
+
+- **Terratest (opt-in).** When the `terratest` input is enabled, call
+  `scaffold_terratest` (module name + dir) to generate a plan-only Go
+  [Terratest](https://terratest.gruntwork.io/) smoke test (`test/<name>_test.go`)
+  **and** a Terraform-native `*.tftest.hcl` in the module's own `tests/` dir.
+  Both plan the **module directly** (no example fixture). Write the returned files
+  (the input also widens `allowed_paths` to permit them). If the repo already has
+  a Terratest suite, update its options/assertions to match the new interface
+  instead.
+
+In all cases: Infraweaver **never runs** the tests — it holds no cloud credentials,
+and Terratest needs Go + a real `apply`. It keeps the test source consistent with
+the module and flags in the PR that the suite should be run in the user's
+pipeline. **Never weaken an assertion or delete a test to go green.**
+
+## Hard rules
+
+- Only modify `*.tf` / `*.tfvars` (and, when `allowed_paths` permits — i.e. the
+  `terratest` input is on — that module's test files). Never touch CI, application
+  code, or unrelated config in a remediation PR.
+- One concern per PR. If you notice other issues, leave them for their own runs.
+- Never auto-merge. The PR is for a human to review.
+- If you cannot fix a concern cleanly (it needs a human decision, or the secure
+  default would break the stack), do **not** open a broken PR — report it
+  instead with what's blocking.

package/src/toolState.ts

@@ -0,0 +1,241 @@
+import { DispatchRecorder } from "#app/agents/dispatchMetrics";
+import type { AgentUsage } from "#app/agents/shared";
+import { type ScanSession, createScanSession } from "#app/mcp/terraform/scanSession";
+import type { PrepResult } from "#app/prep/types";
+import type { AgentDiagnostic } from "#app/utils/agentHangReport";
+import { log } from "#app/utils/cli";
+import type { DiffCoverageState } from "#app/utils/diffCoverage";
+import {
+  type ProgressComment,
+  type ProgressCommentType,
+  parseProgressComment,
+} from "#app/utils/progressComment";
+import type { UserFacingLanguage } from "#app/utils/payload";
+import type { TodoTracker } from "#app/utils/todoTracking";
+
+export type BackgroundProcess = {
+  pid: number;
+  outputPath: string;
+  pidPath: string;
+};
+
+export type StoredPushDest = {
+  remoteName: string;
+  remoteBranch: string;
+  localBranch: string;
+};
+
+/**
+ * Valid inline-comment anchor lines per side at a particular checkout SHA.
+ * Lives here (not in `mcp/review.ts`) so `ToolState` — which caches
+ * `Map<path, CommentableLines>` per checkout — does not pull the MCP server
+ * graph into every consumer of run state (the action's main loop, agent
+ * harnesses, cf-worker indexing).
+ */
+export type CommentableLines = { RIGHT: Set<number>; LEFT: Set<number> };
+
+/**
+ * mutable per-run record of facts that occurred during execution. shared
+ * between the action process and the MCP server (one process — toolState is
+ * just a JS object passed by reference into both surfaces).
+ *
+ * design rule: ToolState is LITERAL. each field records a thing that
+ * happened — `review` is set when `create_pull_request_review` succeeded,
+ * `finalSummaryWritten` flips when `report_progress` wrote a non-plan body,
+ * `selectedMode` is set when `select_mode` was called. fields should never
+ * encode the absence of an event ("unsubmittedReview", "missingArtifact"),
+ * speculative state, or values derived from other fields.
+ *
+ * any predicate the rest of the code needs ("the agent picked review mode but
+ * never produced a review or progress write") is computed inline at the call
+ * site, not stored. derived state in this struct invariably drifts from the
+ * literal fields under refactors and is the wrong layer for the check.
+ *
+ * write narrowly: prefer adding state inside the tool that mutates it (e.g.
+ * `create_pull_request_review` populates `toolState.review`) and reading
+ * narrowly elsewhere. don't introduce flags from main.ts that mirror what an
+ * MCP tool already records.
+ */
+export interface ToolState {
+  // where we're allowed to push - base repo initially, fork URL for fork PRs
+  // set by setupGit, updated by checkout_pr. always set before push validation.
+  pushUrl?: string;
+  // push destination set by checkout_pr - used as primary source in push_branch
+  // because git config reads can fail in certain environments
+  pushDest?: StoredPushDest;
+  // HEAD identity captured by setupGit at run start. load-bearing for the
+  // checkout_pr initial-branch invariant: the only sanctioned HEAD positions
+  // when calling checkout_pr are the run-entry HEAD or the target `pr-N`.
+  // blocks the zed-style cross-PR clobber where a subagent left HEAD on
+  // someone else's `pr-X` and the orchestrator's next checkout_pr inherited
+  // that position.
+  //
+  // discriminated by `kind` because `git rev-parse --abbrev-ref HEAD` returns
+  // the literal sentinel string `"HEAD"` on detached entry, which is the
+  // default state from `actions/checkout` on `pull_request` events (it
+  // checks out the merge commit as a detached SHA). without the kind tag,
+  // detached-entry runs would trivially accept any future detached state.
+  initialHead?: { kind: "branch"; name: string } | { kind: "detached"; sha: string };
+  // issue or PR number (same number space in GitHub)
+  issueNumber?: number;
+  // PR/issue numbers this run CREATED (create_pull_request / create_issue).
+  // read by the REST-write scope guard (mcp/scope.ts) so the agent may edit the
+  // body of / comment on a PR or issue it opened this run, even though that
+  // number differs from the run's triggering issue_number. a merely checked-out
+  // PR is intentionally NOT recorded here — checkout_pr is agent-controlled, so
+  // letting it widen write scope would defeat the guard.
+  createdTargets?: Set<number>;
+  // PR HEAD sha at checkout time — used to detect new commits pushed during a review
+  checkoutSha?: string;
+  // commentable lines per file at checkoutSha — captured during checkout_pr so
+  // review-time inline-comment validation matches the diff GitHub will anchor
+  // to (commit_id=checkoutSha). without this, a PR update between checkout and
+  // review would make listFiles (latest HEAD) disagree with the anchor,
+  // silently dropping valid comments or letting invalid ones through.
+  //
+  // commentableLinesPullNumber records WHICH PR this snapshot belongs to. if
+  // the agent checks out PR B and then reviews PR A in the same session, the
+  // cached snapshot for B would silently mis-validate A's comments — keying
+  // by PR number forces a re-fetch when the target changes.
+  //
+  // commentableLinesCheckoutSha pins the snapshot to the SHA it was built
+  // against. if a second checkout_pr for the SAME PR bumps checkoutSha but
+  // fails before repopulating the cache (e.g., listFiles rate-limits), the
+  // stale snapshot would silently mis-validate comments against the new SHA.
+  // comparing both fields forces a re-fetch when either moves.
+  commentableLinesByFile?: Map<string, CommentableLines>;
+  commentableLinesPullNumber?: number;
+  commentableLinesCheckoutSha?: string | undefined;
+  // SHA to diff incrementally against — set from event payload on first checkout,
+  // then from checkoutSha when review.ts detects new commits mid-review
+  beforeSha?: string;
+  selectedMode?: string;
+  // number of remediation PRs opened this run. set only in Remediate mode by
+  // create_pull_request; read by the max_prs guardrail (mcp/guardrails.ts).
+  remediationPrsOpened?: number;
+  // the terraform tool-to-tool session: the baseline/scan/plan/cost/refactor
+  // signals the terraform MCP tools hand to one another and to end-of-run
+  // reporting. Extracted from this god-bag into its own typed, documented
+  // channel (mcp/terraform/scanSession.ts) so the coupling and its load-bearing
+  // ordering are visible and testable instead of being loose fields here. Reach
+  // it through `scanSessionOf(toolState)`.
+  scanSession?: ScanSession;
+  // number of prepush hook failures this run. push_branch runs the hook
+  // while this is 0 and skips it once non-zero; never decremented within
+  // a run.
+  prepushFailureCount: number;
+  backgroundProcesses: Map<string, BackgroundProcess>;
+  review?: {
+    id: number;
+    nodeId: string;
+    reviewedSha: string | undefined;
+  };
+  // dedupe key: parent review comment_id → most-recent reply written this
+  // session by reply_to_review_comment. used by duplicateReplyDecision to
+  // skip identical-body re-emissions of the same call (PR #610 root cause).
+  // body-keyed (not just id-keyed) so legitimate follow-up replies with
+  // different content still go through.
+  reviewReplies?: Map<
+    number,
+    { commentId: number; url: string | undefined; bodyWithFooter: string }
+  >;
+  dependencyInstallation?: {
+    status: "not_started" | "in_progress" | "completed" | "failed";
+    promise: Promise<PrepResult[]> | undefined;
+    results: PrepResult[] | undefined;
+  };
+  // undefined = no comment yet, object = active comment, null = deliberately deleted
+  progressComment: ProgressComment | null | undefined;
+  // immutable snapshot: true if a progress comment was pre-created at init time.
+  // survives deleteProgressComment so handleAgentResult can still detect "expected but never reported".
+  hadProgressComment: boolean;
+  lastProgressBody?: string;
+  wasUpdated?: boolean;
+  // set after a non-plan report_progress successfully writes the final summary.
+  // decoupled from todoTracker.enabled so cleanup detection survives API failures.
+  finalSummaryWritten?: boolean;
+  // set when create_issue_comment posted a standalone comment on the run's OWN
+  // target issue/PR. signals the progress comment is now redundant chrome so
+  // run-end cleanup deletes it even though report_progress finalized.
+  answerCommentPosted?: boolean;
+  // set by select_mode when Plan + issue_number and plan-comment API returns existing plan (for report_progress target_plan_comment)
+  existingPlanCommentId?: number;
+  previousPlanBody?: string;
+  // absolute path to the PR summary markdown file the agent edits in place.
+  // seeded by main.ts before the agent starts when payload.generateSummary is set;
+  // read back at end-of-run to persist to DB.
+  summaryFilePath?: string;
+  // exact bytes of the seeded snapshot file at run start. compared against
+  // the file content at end-of-run to detect "agent never touched it" — in
+  // that case persistSummary skips the DB write (saving the seed verbatim
+  // would either re-write what the DB already has, on incremental runs, or
+  // serialize the placeholder scaffold, on first runs).
+  summarySeed?: string;
+  // set to true after persistSummary completes once. prevents the error-path
+  // call (which exists so a successful agent edit before a crash still gets
+  // persisted) from redundantly re-running the DB PATCH on the
+  // success-then-late-throw path.
+  summaryPersistAttempted?: boolean;
+  // absolute path to the rolling repo-level learnings markdown file the
+  // agent reads at startup and may edit at end-of-run. seeded by main.ts
+  // for every run from `Repo.learnings` (empty file when no learnings
+  // exist yet); read back at end-of-run to persist any edits.
+  learningsFilePath?: string;
+  // exact bytes of the seeded learnings file at run start. compared
+  // against the file content at end-of-run to detect "agent never touched
+  // it" — in that case persistLearnings skips the DB PATCH (saving the
+  // identical content would be a no-op write that wastes a LearningsRevision
+  // row and the API round-trip).
+  learningsSeed?: string;
+  // mirror of `summaryPersistAttempted` for the learnings tmpfile — guards
+  // the error-path / exit-signal callers from a redundant second PATCH
+  // after the success path already persisted.
+  learningsPersistAttempted?: boolean;
+  output?: string | undefined;
+  usageEntries: AgentUsage[];
+  // specialist-routing watch (see agents/dispatchMetrics.ts). accumulates
+  // across agent invocations for the same reason `usageEntries` does — a
+  // post-run resume or a transient-provider retry is the same run's cost.
+  dispatchMetrics: DispatchRecorder;
+  model?: string | undefined;
+  // set by main.ts when the BYOK fallback engaged (configured model needed
+  // a provider key the runner didn't have). carried into PR-comment footers
+  // so users can see "Using <free model> (credentials for <configured> not
+  // configured)" rather than just being silently downgraded. literal record
+  // of an event that happened — matches the ToolState design rule.
+  modelFallback?: { from: string } | undefined;
+  // user-facing language for fixed comment/footer chrome (mirrors payload.language,
+  // seeded in main.ts). "en"/undefined → the default English labels.
+  language?: UserFacingLanguage | undefined;
+  todoTracker?: TodoTracker | undefined;
+  diffCoverage?: DiffCoverageState | undefined;
+  // mutable handle the agent harness writes to as a run progresses (recent
+  // stderr ring buffer reference, last provider-error label, event count).
+  // read by main.ts's outer catch so a watchdog-fired activity timeout still
+  // surfaces the same agent-side context the harness's own catch path returns
+  // via `result.error`. see `utils/agentHangReport.ts`.
+  agentDiagnostic?: AgentDiagnostic | undefined;
+}
+
+interface InitToolStateParams {
+  progressComment: { id: string; type: ProgressCommentType } | undefined;
+}
+
+export function initToolState(params: InitToolStateParams): ToolState {
+  const resolved = parseProgressComment(params.progressComment);
+
+  if (resolved) {
+    log.info(`» using pre-created progress comment: ${resolved.id} (${resolved.type})`);
+  }
+
+  return {
+    progressComment: resolved,
+    hadProgressComment: !!resolved,
+    prepushFailureCount: 0,
+    backgroundProcesses: new Map(),
+    createdTargets: new Set(),
+    usageEntries: [],
+    dispatchMetrics: new DispatchRecorder(),
+    scanSession: createScanSession(),
+  };
+}