# Configuration

Configure model routing, where settings are read from, and how far a run may continue after failures. Delegation is decided first. Routing only chooses how an already-selected role runs.

## Locations and precedence

Zimster reads configuration from several layers. The highest-priority value wins: an explicit dispatch override, a per-run `--config`, Git-local project configuration, user configuration, host-native configuration, then inheritance from the parent session.

User configuration lives at `$XDG_CONFIG_HOME/zimster/config.json` or `$HOME/.config/zimster/config.json` on Linux, `$HOME/Library/Application Support/Zimster/config.json` on macOS, and `%APPDATA%\Zimster\config.json` on Windows. Project configuration is stored under the Git administrative path returned by `git rev-parse --git-path zimster/config.json`.

Zimster reads these files; it doesn't rewrite your active model or host settings. Each run keeps a snapshot of the configuration it actually used.

## Routing modes and policies

Routing only happens after Zimster decides another agent is worth using. The mode controls what happens next:

- **`inherit`:** request no model or effort override.
- **`recommend`:** report a mapped recommendation, but let the delegated session inherit its model.
- **`map_only`:** use only a candidate you explicitly mapped.
- **`auto_within_policy`:** choose among mapped, available candidates according to policy.

Policies are `quality_first`, `balanced`, and `cost_optimized`. `strict_cost` works only with `cost_optimized`. If the host cannot prove that the requested model was enforced, optional work stays with the owner. Required independent review stops until there is an explicit policy exception.

## Role classes

A role and a model are separate choices. Zimster ships with four classes: `economy`, `balanced`, `expert`, and `inherit`.

| Role | Default class | Typical work |
| --- | --- | --- |
| Scout | economy | Bounded discovery and mechanical inventory. |
| Bounded implementer | balanced | Independent implementation slices. |
| Test reviewer | balanced | One named verification command or focused test review. |
| Integration reviewer | expert | Architecture, security, compatibility, and final integration review. |
| Diagnostician | expert | Difficult failures after repeated owner attempts. |

You can override the class for any named role with `routing.role_classes`.

## Model mappings

`routing.mappings` is where you choose the actual model used for each class. A candidate requires a `model` string and may also specify `provider`, `effort`, ranking values, allowed harnesses, minimum host version, required capabilities, and declared availability.

Use `map_only` when you want a mapped model to be the only eligible override. Use `auto_within_policy` when you want Zimster to rank multiple candidates inside the policy you selected. Ties keep declaration order.

Requested and effective model IDs remain separate. Zimster reports an effective model only when the host exposes that information.

## Configuration example

This maps discovery to an economy model, most implementation and test review to a balanced model, and integration review or diagnosis to an expert model. Replace the placeholder IDs with models your host supports.

```json
{
  "schema_version": 1,
  "routing": {
    "mode": "map_only",
    "policy": "balanced",
    "strict_cost": false,
    "role_classes": {
      "scout": "economy",
      "bounded_implementer": "balanced",
      "test-reviewer": "balanced",
      "integration-reviewer": "expert",
      "diagnostician": "expert"
    },
    "mappings": {
      "economy": [
        { "model": "economy-model-id" }
      ],
      "balanced": [
        { "model": "balanced-model-id", "effort": "high" }
      ],
      "expert": [
        { "model": "expert-model-id", "effort": "high" }
      ]
    }
  },
  "autonomous_convergence": {
    "enabled": true,
    "limits": {
      "correction_commits": 2,
      "final_verification_attempts": 2,
      "complete_suite_executions": 3,
      "exact_duplicate_commands": 2,
      "context_renewals": 2
    }
  }
}
```

Validate a configuration with `node scripts/model-routing.mjs validate-config --config <path>`.

## Execution budgets and review lifecycle

Execution limits and review limits are separate. A review does not get more attempts because some other counter changed.

The shipped execution policy tracks these limits:

| Budget | Limit | Behavior at the boundary |
| --- | ---: | --- |
| Correction commits | 2 | Hard stop |
| Final verification attempts | 2 | Hard stop |
| Complete-suite executions | 3 | Hard stop |
| Exact duplicate commands | 2 | Repetition is surfaced and capped |
| Context renewals | 2 | Additional renewal is escalated |

Review uses its own lifecycle:

| Review control | Limit |
| --- | ---: |
| Correction rechecks per admitted cycle | 1 |
| Review cycles per seam | 2 |
| Material strategy restarts per seam | 1 |
| Final integration reviews | 2 |
| Final correction waves | 1 |

An initial review gets one owner correction and one recheck by the same reviewer. If a load-bearing problem remains, the circuit breaker trips. The owner may try one genuinely different strategy and run a second review cycle. If that still fails on a load-bearing problem, the run ends as `BLOCKED`.

Final integration review waits until the candidate stops changing. If that review finds a defect and the owner corrects it, one more exact-head review is available.

Hard execution limits win over a host's goal or continue setting. Zimster also stops for scope expansion, sensitive decisions without authority, required approval, missing required review, contradictory requirements, or exhausted limits.

## Local records

Run state lives under the repository's Git administrative directory by default. It keeps the current slice, routing decisions, review history, checkpoints, and verification records tied to the Git state that produced them.

Zimster contains no upload or telemetry mechanism for those records.

HTML version: https://www.zimster.dev/docs/configuration.html