repo-manager/docs/dual-run.md

# Dual-run flags (RMGR-WP-0002 / 0003)

State Hub remains the MCP/REST entrypoint. When dual-run is on, **checkout
mutation** is executed by Repo Manager.

## Config file (preferred for production pilot)

```bash
mkdir -p ~/.repo-manager
cp ~/repo-manager/config/dual-run.pilot.example.yaml ~/.repo-manager/dual-run.yaml
# edit pilot_repos / writeback_push as needed
```

```yaml
writeback: true
reconcile: true
writeback_push: false
pilot_repos:
  - repo-manager
meter_path: ~/.repo-manager/mutation-meter.jsonl
```

Optional path override: `RM_DUAL_RUN_CONFIG=/path/to/dual-run.yaml`

**Restart State Hub API** after config changes so the process reloads
(settings are cached per process).

## Environment variables (override config when set)

| Variable | Meaning |
| --- | --- |
| `RM_WRITEBACK=1` | Task file writeback via `rmgr update-task-status` |
| `RM_RECONCILE=1` | `fix-consistency` also runs `rmgr reconcile` for pilots |
| `RM_WRITEBACK_PUSH=1` | `git push` after RM writeback commit (best-effort) |
| `RM_PILOT_REPOS=slug1,slug2` | Restrict to slugs; **unset** = all when flags on |
| `RM_METER_PATH` | JSONL meter path |
| `REPO_MANAGER_SRC` | Path to `repo-manager/src` for SH adapter |
| `RMGR_BIN` | Override `rmgr` command |

## Rollback

```bash
# config: set writeback/reconcile false, or:
rm ~/.repo-manager/dual-run.yaml
unset RM_WRITEBACK RM_RECONCILE RM_WRITEBACK_PUSH RM_PILOT_REPOS
# restart SH API
```

## Operator checks

```bash
rmgr dual-run-status
# or inspect meter
tail -20 ~/.repo-manager/mutation-meter.jsonl
```

## Paths covered

| Entry | Dual-run when flagged |
| --- | --- |
| `PATCH /tasks/{id}` | RM writeback (+ optional push) |
| `POST /tasks/bulk-status-sync` | RM writeback per task |
| C-15 fix-consistency writeback | RM writeback, else native |
| fix-consistency fix_repo | RM reconcile for pilots |

## Pilot expand (STATE-WP-0079)

Add slugs to `pilot_repos`, restart SH, watch meter for `source=repo-manager`
writebacks. Expand only when failures are absent under normal agent load.