# Plans History Durability Implementation Plan

audience: AI coding agents first.

> **For agentic workers:** Execute inline under current no-subagent constraint. Use TDD and guarded project landing.

**Goal:** Persist and rebuild v2 run history independently from validated live-control records, then restore production Plans.

**Architecture:** `registry.js` owns durable history records and idempotent journal import. Control API projects only this store. Supervision readers retain exclusive ownership of `state/v2/runs`.

**Tech Stack:** Node.js standard library, Bun collector, Astro/React web, systemd user services.

---

## Wave Plan

| Wave | Tasks | Files touched | Safe to parallelize? |
|------|-------|---------------|----------------------|
| 1 | Task 1 | `modules/harness/v2/test/registry.test.js`, `modules/harness/v2/test/control-api.test.js` | single task |
| 2 | Task 2 | `modules/harness/v2/registry.js`, `modules/harness/v2/control-api.js`, `modules/harness/v2/run.js`, `modules/harness/v2/test/index.js` | single task |
| 3 | Task 3 | `modules/harness/v2/test/reconcile-runs.test.js`, `modules/harness/v2/test/watchdog.test.js` | single task |
| 4 | Task 4 | `modules/harness/VERSION` | single task |
| 5 | Task 5 | deployment/runtime state only | single task |

### Task 1: Durable History Regression Tests

**Wave:** 1
**Blocks:** Task 2
**Blocked by:** —

**Files:**
- Create: `modules/harness/v2/test/registry.test.js`
- Modify: `modules/harness/v2/test/control-api.test.js`

- [ ] Add failing tests proving history survives legacy/quarantine removal, restart, journal import, malformed siblings, and idempotent re-import.
- [ ] Add phase3-shaped journal test: eight completed tasks plus final `plan-error` projects failed, completed count eight, and finalization reason.
- [ ] Run `node --test modules/harness/v2/test/registry.test.js modules/harness/v2/test/control-api.test.js`.
- [ ] Expected: new assertions fail against mutable `v2/runs`.

### Task 2: History Store and Projection

**Wave:** 2
**Blocks:** Task 3
**Blocked by:** Task 1

**Files:**
- Modify: `modules/harness/v2/registry.js`
- Modify: `modules/harness/v2/control-api.js`
- Modify: `modules/harness/v2/run.js`
- Modify: `modules/harness/v2/bin/runplan.js`
- Modify: `modules/harness/v2/test/index.js`
- Modify: `modules/harness/v2/test/seats.test.js`

- [ ] Implement validated atomic history writes at `history/v2/runs`.
- [ ] Implement bounded idempotent import from legacy history, quarantine history records, and preserved journals.
- [ ] Register new runs durably before execution.
- [ ] Make `/runs` and run details read history only after import.
- [ ] Project final `plan-error` reason without changing journal data.
- [ ] Run Task 1 command; expected all pass.

### Task 3: Admission Isolation Proof

**Wave:** 3
**Blocks:** Task 4
**Blocked by:** Task 2

**Files:**
- Modify: `modules/harness/v2/test/reconcile-runs.test.js`
- Modify: `modules/harness/v2/test/watchdog.test.js`

- [ ] Prove history-directory terminal/malformed records never reach reconcile/watchdog or start units.
- [ ] Run `node --test modules/harness/v2/test/reconcile-runs.test.js modules/harness/v2/test/watchdog.test.js`.
- [ ] Run full `node --test modules/harness/v2/test/*.test.js`.

### Task 4: Release and Repository Verification

**Wave:** 4
**Blocks:** Task 5
**Blocked by:** Task 3

**Files:**
- Modify: `modules/harness/VERSION`

- [ ] Run harness tests, collector tests, web tests, typechecks, and web build with pristine output.
- [ ] Commit source fix.
- [ ] Cut next immutable harness bundle and commit release version.
- [ ] Land only with `bash .claude/scripts/ship.sh land fix/plans-history-regression <worktree>`.

### Task 5: Deploy and Production Acceptance

**Wave:** 5
**Blocks:** —
**Blocked by:** Task 4

**Files:** runtime state only

- [ ] Activate released harness bundle and restart control API without starting phase3 coordinators.
- [ ] Run `packaging/deploy-local.sh` through ship post-land flow.
- [ ] Query authenticated harness `/runs`, collector `/state`, and web proxy `/api/collector/state`.
- [ ] Verify phase3 plus earlier v2 runs, no harness adapter error, non-empty Plans panel.
- [ ] Verify deployed `/plans` in authenticated browser tooling and save screenshot artifact.