infinity-harness 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,114 @@
+# Changelog
+
+All notable changes to this project are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.0.0] — 2026-08-23
+
+Renamed from `pi-harness` to **infinity-harness**, and rebuilt from a working prototype into
+something shippable. This is a breaking release: tool names, command names and the package name all
+changed, and the extension no longer depends on an external repository.
+
+### Breaking
+
+- **Package renamed** `pi-harness` → `infinity-harness`.
+- **Tools renamed.** `harness_task_list` → `infinity_plan`, `pi_goal_task`/`harness_goal_loop` →
+  `infinity_goal`, `pi_harness_remote`/`harness_remote` → `infinity_dashboard`,
+  `harness_spawn_worker` → `infinity_spawn_worker`. New: `infinity_brief`, `infinity_validate`,
+  `infinity_advance`.
+- **Commands renamed** to the `/infinity:*` namespace, and `/infinity:run` / `/infinity:halt` added.
+- **The `cli`, `prompts` and `skills` symlinks are gone.** They pointed at absolute paths inside a
+  sibling `dev-harness` checkout, which made the package impossible to install anywhere else. The
+  logic they reached is now owned TypeScript in `src/core/`. Skills ship from `harness/skills/`.
+- **Node 22+ required** (the test and E2E runners use native TypeScript stripping).
+- **Dependencies trimmed** to `proper-lockfile` and `string-width`; `ajv` and `simple-git` were
+  declared but unused.
+
+### Fixed
+
+- **Concurrent plan writes could lose edits.** `writeTaskList` read the plan, checked `baseRevision`,
+  then wrote — three steps with no mutual exclusion, so two writers that both read revision N both
+  passed the check and both wrote N+1. Measured at 2 lost updates in a 6-way fan-out. The whole
+  read-apply-write now happens under an exclusive lock, and fails closed rather than racing.
+- **Plan writes silently dropped task fields.** Round-tripping through the extension rebuilt each
+  task from a fixed shape, discarding `difficulty`, `modelHint`, `criteria` and anything else. Updates
+  now merge onto the stored task, so unknown fields survive.
+- **The tested code was not the shipped code.** The extension carried inlined copies of the plan
+  engine and the widget; the test suite exercised `src/`, which the extension never called. One
+  implementation now, in `src/`.
+- **Status aliases failed dependency validation.** `rework.ts` and `replan.ts` parsed the plan raw, so
+  a task stored as `"done"` never compared equal to `"complete"` and every amendment to such a plan
+  was rejected — with a message claiming a task in flight had unresolved dependencies.
+- **A nested lock deadlocked against itself.** The new sync lock used `<path>.lock`, the same
+  directory `proper-lockfile` uses, so a caller holding the async lock blocked the event loop waiting
+  for a directory it already owned. The sync lock now uses `<path>.ilock`.
+- **Locks were held across whole agent turns** with an 8-second staleness timeout, meaning any turn
+  longer than eight seconds left a lock another process could steal. Critical sections are now
+  milliseconds.
+- **`require()` in an ESM module** meant the rich tool renderers silently never loaded.
+- **`process.cwd()` in the context hook** instead of the session's project directory.
+- **The widget overran its frame below 40 columns.** The progress row now degrades instead of padding
+  past the edge, and unboxed output is clamped to the requested width.
+- **Ambiguous-width glyphs misaligned the widget.** `string-width` reports `⚠ ↷ ▸ ✓ ·` as two columns;
+  terminals draw them in one. Width measurement now pins them.
+- **Truncation destroyed ANSI styling**, bleeding colour into the rest of the line.
+- **`gateHistory` grew without bound** over a long run. Capped at 500 entries.
+- **A type-only import of `AddressInfo`** made the dashboard module fail to load under type stripping.
+- **A raw NUL byte in a source file** made `grep` and `file` treat the module as binary.
+- **A model reference reached a shell unvalidated.** It is interpolated into the worker command, so it
+  is now checked against a strict character set and refused rather than escaped — a typo cannot
+  become a command substitution.
+
+### Added
+
+- **Continuous run driver** (`src/loop.ts`). `/infinity:run` validates, advances, re-briefs and keeps
+  going until the pipeline completes or a guard fires: no-progress detection, wall-clock and
+  iteration ceilings, retry budgets, and a human brake (`/infinity:halt`, `paused`, `harness/STOP`).
+  Every stop names its reason.
+- **New terminal widget.** Phase rail, progress meter, task window centred on the active task,
+  dependency references, subtasks under the task actually being worked. Responsive to ~58 columns,
+  ASCII fallback on non-UTF-8 locales, colour degradation from truecolor to none.
+- **New web dashboard.** Same information design for the browser: stacked progress meters that show
+  stuck work as colour rather than absence, gate panel, alerts strip, 5-second self-refresh with
+  backoff. Read-only, loopback-only, and it never runs the gate.
+- **Deterministic gate suite** with per-phase checks, task-scoped validation, and advisory checks that
+  report without blocking.
+- **E2E suite** (`npm run e2e`): 11 scenarios, 79 assertion groups, over real temp projects, real git
+  repos and real child processes — including a concurrency fan-out with an unlocked control that
+  demonstrates why the lock is load-bearing.
+- **Test runner** (`npm test`): 21 files, plain `node:assert`, no framework.
+- **Full configuration from inside pi.** `/infinity:config` opens an interactive menu covering models,
+  pipeline, project commands, gates, loop budgets and retry budgets; `/infinity:config show` prints
+  the lot as text and is what runs automatically when the mode has no dialogs. The menu is generated
+  from one schema (`src/core/settings.ts`), so an option cannot exist in the file format and be
+  missing from the UI.
+- **Model tiers picked from pi's own models.** Config → Models offers the models pi has configured
+  and can authenticate — session-scoped ones when scoping is set — for each difficulty tier, the
+  master model and the default. Any tier can be handed back to "pi's current model".
+  `/infinity:models` shows the available list beside the current routing.
+- Values are bounds-checked before they are written, durations accept `24h` / `90m`, and the phase
+  list is toggled item by item and stored in pipeline order rather than click order.
+- `.bak` recovery for a corrupt plan file.
+- A `LockTimeoutError` a caller can actually act on.
+
+### Changed
+
+- **Model routing ships vendor-neutral.** Every slot is empty by default, meaning "use whatever model
+  pi is already configured with". Installing the harness no longer silently redirects work to a
+  specific third-party model.
+- **Pi-only.** Support and references for other agent systems were removed; this is a pi extension
+  and nothing else.
+- The dashboard refuses to bind to a non-loopback interface without an explicit opt-in, and serves a
+  CSP tight enough that an escaping slip cannot become script execution.
+- Documentation rewritten: README, AGENTS.md, and `harness/docs/ARCHITECTURE.md`.
+- **`strict: true`.** The whole tree typechecks under TypeScript strict mode, with ambient types added
+  for `proper-lockfile`, which ships none.
+- **Verified installable from npm** (`pi install infinity-harness`). pi loads extensions through
+  `jiti`, which transpiles TypeScript at runtime, so the package ships `.ts` with no build step.
+  Plain `node` refuses to type-strip inside `node_modules`; pi does not use plain `node` for this.
+
+---
+
+Earlier releases (0.2.0 – 1.2.0) were developed under the `pi-harness` name and are not carried
+forward here; that history is in the git log.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bakr Bagaber
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,266 @@
+# infinity-harness
+
+**A pi extension that keeps an agent building — correctly — for hours or days without you.**
+
+Point it at a project, describe the goal, and walk away. infinity-harness drives the agent through a
+gated pipeline, checks the work with deterministic gates rather than the model's own judgement, and
+stops with a clear reason when it genuinely needs you.
+
+```
+╭──────────────────────────────────────────────────────────────────────────╮
+│ ∞ INFINITY ──────────────────────────────────────────────── BUILD rev 42 │
+│ ▸ Ship the payments rewrite behind a flag                                │
+│                                                                          │
+│ ● define ─ ● plan ─ ◉ BUILD ─ ○ verify ─ ○ review ─ ○ ship               │
+│                                                                          │
+│ ▰▰▰▰▰▰▰▰▰▰▰▱▱▱▱▱▱▱▱▱▱▱▱▱  45%                  5/11 tasks · 1/2 features │
+│ ⚠ 1 blocked · ↷ 1 rework · retry 2/10                                    │
+│                                                                          │
+│ ▸ feature-002 · Checkout flow                                            │
+│   ●  4 validate cart totals against catalogue prices                     │
+│   ●  5 apply stacked discount codes with precedence rules           ← #4 │
+│   ◐  6 handle partial refunds across split tenders              ← #4, #5 │
+│        ✓ unit tests for tender split                                     │
+│        ▸ integration test against sandbox                                │
+│        · audit log entries                                               │
+│   ○  7 emit refund webhook                                          ← #6 │
+│   ⚠  8 reconcile ledger nightly                                     ← #6 │
+│   ⋯ 3 more                                                               │
+╰──────────────────────────────────────────────────────────────────────────╯
+```
+
+---
+
+## Why it exists
+
+Left alone, a coding agent drifts. It declares work finished that isn't, forgets what it already
+did, re-solves the same problem three different ways, and — worst of all — keeps going long after it
+stopped making progress. Pair it with a small or cheap model and all of that gets worse.
+
+infinity-harness fixes that by taking two decisions away from the model:
+
+1. **When work is done.** A deterministic gate decides, not the agent. Same tree, same verdict, every
+   time. No agent marks its own homework.
+2. **What happens next.** The phase pipeline is forward-only and one step at a time. The agent cannot
+   decide it's bored of BUILD and jump to SHIP.
+
+Everything else — the plan, the retries, the model routing — exists to keep those two decisions
+honest over a very long run.
+
+## Install
+
+Requires **Node 22+** and [pi](https://github.com/earendil-works/pi-coding-agent).
+
+```bash
+# from npm — project-local, so the team shares it via .pi/settings.json
+pi install npm:infinity-harness -l
+
+# or globally
+pi install npm:infinity-harness
+
+# straight from the repo
+pi install git:github.com/bakr-bagaber/infinity-harness
+
+# or from a checkout
+pi install ./infinity-harness -l
+
+pi list   # confirm it loaded
+```
+
+The package ships TypeScript. pi loads extensions through `jiti`, which
+transpiles at runtime, so there is no build step and nothing to compile.
+
+## Use it
+
+```bash
+cd your-project
+pi
+```
+
+On session start the harness injects a brief — phase, role, current task, acceptance criteria, and
+what to do next. Do the work, then:
+
+```
+/infinity:validate     run the gate for this phase
+/infinity:run          hand it the wheel: validate → advance → re-brief, until done or stuck
+/infinity:config       change any setting, including which model runs which tier
+/infinity:models       what models pi has, and how they are being routed
+/infinity:dashboard    open the live web view
+/infinity:halt         take the wheel back
+```
+
+`/infinity:run` is the point of the tool. It keeps the loop turning without you.
+
+## Configuration
+
+Everything is configurable from inside pi:
+
+```
+/infinity:config        interactive menu
+/infinity:config show   print the whole configuration as text
+```
+
+The menu is generated from a single schema, so every option the file format
+supports is reachable from the UI — the two cannot drift. Editing
+`harness/config.json` and `harness/model-router.json` by hand stays entirely
+valid; the menu is the same data with prompts and bounds checking attached.
+
+| Group | Covers |
+|---|---|
+| **Models** | Which model runs each difficulty tier, the master model, consultation budget |
+| **Pipeline** | Which phases run, copilot vs autopilot, role strictness, pause |
+| **Project commands** | lint / test / coverage / build — what the gate actually runs |
+| **Gates** | Enable, coverage threshold, placeholder rejection |
+| **Continuous run** | Iteration ceiling, wall-clock budget, no-progress strikes |
+| **Retry budgets** | Attempts per task, feature and phase |
+
+## The pipeline
+
+```
+define → plan → build → verify → [simplify] → review → ship
+```
+
+| Phase | What it's for | Gate opens when |
+|---|---|---|
+| **define** | Write down what's being built and how you'll know it's done | Every feature has acceptance criteria |
+| **plan** | Break features into ordered, dependency-aware tasks | Tasks exist and criteria are set |
+| **build** | Implement, one task at a time, tests alongside | Lint, tests, coverage pass; no placeholders; every task complete |
+| **verify** | Prove behaviour; hunt what the tests miss | Tests and coverage pass on a clean tree |
+| **simplify** | Delete more than you add *(opt-in)* | Tests pass, no empty dirs, clean tree |
+| **review** | Judge it as if someone else wrote it | Rubric, README, architecture doc and decisions are real; branch level with upstream |
+| **ship** | Tag, changelog, leave it clean | Clean tree, tagged, changelog, README, licence, no placeholders |
+
+Enable or disable phases in `harness/config.json` under `phases.enabled`. SIMPLIFY is off by default.
+
+## Knowing when to stop
+
+This is the part that makes an unattended run safe. `/infinity:run` halts on any of:
+
+| Guard | Default | What it catches |
+|---|---|---|
+| **No progress** | 3 strikes | Gate keeps failing and the working tree hasn't moved — the agent is spinning, not working |
+| **Wall clock** | 24h | A run you forgot about |
+| **Iterations** | 2000 | Runaway loops that stay under the clock |
+| **Retry budget** | 10/task | One impossible task eating the whole run |
+| **Pipeline complete** | — | Final phase passed with every task done |
+| **Human brake** | — | `/infinity:halt`, `/infinity:pause`, or `touch harness/STOP` |
+
+Every stop names its reason. You come back to an explanation, not a mystery.
+
+Tune the budgets in `harness/config.json`:
+
+```json
+{
+  "loop": {
+    "maxIterations": 2000,
+    "maxWallClockMs": 86400000,
+    "noProgressLimit": 3
+  }
+}
+```
+
+## The plan is a file
+
+`harness/features/feature-list.json` is the single source of truth. The widget, the dashboard and the
+brief all read it; nothing caches a second copy.
+
+The agent edits it by submitting the **complete** task list through the `infinity_plan` tool:
+
+- **Omission means deletion.** One unambiguous rule beats incremental edits a model loses track of.
+- **`baseRevision` guards every write.** A stale revision is rejected, so parallel workers can't
+  clobber each other.
+- **Unknown fields survive.** An update merges onto the stored task, so `difficulty`, `modelHint`,
+  `criteria` and anything added later are never silently dropped.
+- **The dependency graph stays sane.** Cycles and dangling references are rejected at write time; a
+  task can't be `complete` while something it depends on isn't.
+
+## Watching it work
+
+**In the terminal** — the widget above updates on every turn. It's responsive down to ~58 columns,
+degrades to ASCII when the locale isn't UTF-8, and drops colour under `NO_COLOR`.
+
+**In a browser** — `/infinity:dashboard` serves a live page on loopback: phase rail, stacked progress
+meters that show stuck work as colour rather than absence, the full task tree, and the last gate
+verdict. It refreshes itself every 5 seconds and reconnects with backoff if the run ends.
+
+The dashboard is strictly read-only and binds to `127.0.0.1`. It never writes, and never bumps
+`baseRevision` — opening it can't perturb the run you're watching.
+
+## Model routing (optional)
+
+Send cheap tasks to a small model and hard ones to a large one. Pick them with `/infinity:config` →
+**Models**: the list offered is the models **pi itself has configured and can authenticate**, so you
+choose from what you already have rather than typing ids from memory. `/infinity:models` shows that
+list alongside the current routing.
+
+Routing ships **disabled with every slot empty**, meaning "use whatever model pi is already
+configured with" — installing the harness never silently redirects your work to someone else's
+model. Any tier can be handed back to that default at any time.
+
+Resolution order:
+
+```
+task.modelHint → byTask → byDifficulty → byFeature → bySprint → byPhase → byRole → default
+```
+
+`master` is never assigned directly; it's reachable only through one-step consultation after the
+normal ladder is exhausted.
+
+**Reasoning models need headroom.** A reasoning model emits nothing on the content channel until it
+has finished thinking — measured at ~370 reasoning tokens to answer "reply with one word". If you
+route a tier to one, give its workers a generous timeout; a tight budget returns an empty completion
+that looks like a broken endpoint but is only a small cap.
+
+## Tools the agent gets
+
+| Tool | Purpose |
+|---|---|
+| `infinity_brief` | What am I supposed to be doing right now? |
+| `infinity_plan` | Read or rewrite the task list |
+| `infinity_validate` | Run the gate for this phase |
+| `infinity_advance` | Move to the next phase (refuses on a failing gate) |
+| `infinity_dashboard` | Start/stop/query the web view |
+
+## Layout
+
+```
+infinity-harness/
+├── extensions/infinity-harness/   pi lifecycle adapter — thin, no logic of its own
+├── src/
+│   ├── core/                      types · paths · fsx · config · phases · gates · brief
+│   │                              · featureList (the SSOT) · lock · exec
+│   ├── ui/                        theme · widget (terminal) · dashboard (web)
+│   ├── loop.ts                    the continuous-run driver and its stop conditions
+│   ├── taskList.ts                atomic plan editor
+│   ├── worker.ts                  isolated per-task workers
+│   ├── modelRouter.ts             difficulty ladder + consultation
+│   ├── rework.ts · replan.ts      backward rework with BFS impact · mid-build amendment
+│   ├── unstuck.ts · review.ts     escalation strategy matrix · review bounce guard
+│   └── goalLoop.ts · goalState.ts · goalSpec.ts
+├── harness/
+│   ├── features/feature-list.json the plan
+│   ├── config.json                pipeline state and settings
+│   ├── model-router.json          optional routing
+│   ├── docs/                      architecture · decisions · phase and role docs
+│   └── skills/                    29 craft skills the brief points at
+├── tests/                         20 files, plain node:assert
+└── scripts/run-tests.mjs
+```
+
+The extension is deliberately thin. Every decision lives in `src/`, where it's typed and tested —
+there is one implementation, and the adapter calls it.
+
+## Development
+
+```bash
+npm install
+npm run check    # tsc --noEmit
+npm test         # 20 test files
+npm run e2e      # end-to-end against a live model
+```
+
+Tests are plain `node:assert` run under `--experimental-strip-types`. No framework, no build step.
+
+## Licence
+
+MIT