razzou-harness 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -3,6 +3,186 @@
 The notable changes in each release of razzou-harness. Before 1.0, a new minor version
 may change how a project is set up, and its notes say how.
 
+## 0.4.0 (2026-11-08)
+
+**Upgrading a project from 0.3.x:** install the new version, then rebuild the agents'
+image with `harness doctor --build-images`, or run `harness setup`, which does it: the
+image's tag follows the harness's version. The doctor now removes the 0.3.0 image once
+no container uses it. Nothing else changes in a project.
+
+- A **Sandboxes** view in the dashboard lists the sandboxes on the OpenShell gateway:
+  this project's, with what each is for and whether anything still uses it, then the
+  others'. A left-over sandbox of this project, which a crash or a failed delete left,
+  can be deleted there; one in use, or another project's, can't. Selecting a sandbox
+  shows the network requests its policy refused, from its log: the program, the host,
+  why, and how often. The daemon labels the sandboxes it makes with the project's name
+  (`harness.project`) to tell them apart; a left-over sandbox from 0.3.0 or earlier has
+  no label, so it shows among the others.
+- The view shows what each sandbox uses of the machine now, its CPUs and memory against
+  its caps, and the total for every OpenShell sandbox, read from `docker stats` every
+  five seconds while the view is open.
+- **Caps on each sandbox**, set in the Sandboxes view: how many CPUs and how much memory
+  each new sandbox may use, so that Developers, check runs and reviewers in parallel
+  leave the machine usable. The daemon records them, and creates every sandbox with
+  them from then on; those already there keep theirs. There is no cap until you set one.
+- An attempt keeps the network requests its sandbox's policy refused. OpenShell keeps
+  only a sandbox's last 2,000 log lines, so the daemon reads the log every minute while
+  the Developer works, and once more before the sandbox goes. The attempt's card shows
+  them, and the Manager gets them with a failed attempt. A refused host is the
+  Manager's to resolve: it guides the next Developer around the host, or asks the owner
+  to allow it, since only the owner widens the network policy.
+
+Disk space:
+- The git bundles the daemon hands to sandboxes, each a copy of the plan branch's whole
+  history, are deleted once uploaded, and the ones it takes back once fetched. One was
+  kept for every attempt and every review, and never deleted, so `.harness/` grew with
+  each. The daemon deletes the ones earlier versions left in `.harness/modules/` when it
+  starts.
+- The daemon deletes this project's left-over sandboxes when it starts and every hour:
+  those the Sandboxes view offers to delete, so a delete that failed is tried again. It
+  spares an Architect's, which holds the owner's conversation with it.
+- `harness doctor --build-images` removes the agents' images the new one replaces, about
+  2 GB each, once no container uses them: the other versions' tags, and the untagged
+  images that building a tag again leaves. It also shows the size of Docker's build
+  cache, with `docker builder prune` to free it; that cache is shared with every other
+  build on the machine, so the doctor leaves it alone.
+
+## 0.3.0 (2026-11-07)
+
+**Upgrading a project from 0.2.x:** install the new version, then run `harness setup`
+in the project, which does both steps, or do them by hand. Run `harness install-ci` and
+commit the CI files it writes before the next `Arch:` pull request: the protected paths
+changed, and the lock the daemon writes lists more, which the old CI script on `main`
+would refuse. Rebuild the agents' image with `harness doctor --build-images`: its tag
+now follows the harness's version. Then open the dashboard from the link the daemon
+prints, once.
+
+Fixes from a review of 0.2.0.
+
+Protected files:
+- Paths with a non-ASCII character, a quote or a backslash passed every protection rule,
+  in CI's `verify` and in the daemon's own checks, because git quoted them: a Developer
+  could add `.claude/skills/é/SKILL.md`, and a `CODE` plan could add Terraform in
+  `iac/ñ.tf`. Paths are now read NUL-separated.
+- `CLAUDE.md`, `CLAUDE.local.md`, `AGENTS.md` and `.claude/` are protected in every
+  folder, as Claude Code reads them there; so are the configs that decide what a check
+  runs (`vitest.config.mts` overrode a protected `vitest.config.js`; Vite, Babel, Mocha,
+  pytest and tox configs, and package.json's `jest`, `babel` and `mocha` fields, weren't
+  protected), and the npm script of `npm run -s lint` or `npm --prefix . test`.
+- A Plan or Fix PR may not add a local link to `package-lock.json`, which could swap a
+  check's tool for a stub. An Arch PR is judged by the base branch's rules, so it can't
+  protect `src/**` to change `src/` in the same PR.
+- `protect.files` takes globs, `./x` and `dir/`, which matched nothing before, and
+  `terraform.dir` may be written `./iac` or `iac/`. `harness lock` leaves out what git
+  ignores.
+
+Swarm mode:
+- Every Developer under way reaches the Manager: `ask_manager` from a second or third
+  attempt at once was refused, and the Manager could answer or stop only the first. A
+  plan's Manager acts on its own plan only.
+- Plans in parallel no longer stop on `progress.txt`: both add lines to it, and the
+  daemon keeps both sides' lines when it merges `main` into a plan branch. Before it
+  merges a pull request, it merges `main` into it when `main` moved since CI ran, so CI
+  and the reviewers judge what `main` gets.
+- Modules are built one after another in Swarm too, as the design says: the first plan
+  of a second module started alongside the first module's plans, with its own
+  Developers, Manager and reviewers. Only the module being built has those now. Any
+  module's Architect still works meanwhile, so the next module can be designed while one
+  is built; its plans wait their turn. Two modules already under way at the upgrade are
+  finished one after the other, the older first: the other's attempts are interrupted,
+  and start again in its turn.
+- A plan that a design change drops while it is built no longer holds a place under
+  `swarm.maxPlans`, and its Manager is no longer started over and over, each time in a
+  new sandbox and session.
+- An `INFRA` or `MIXED` plan's estimate counts only for the head it was made on, and is
+  read only once the `cost` job itself succeeded: after a fix round, a head without its
+  own estimate merged on the earlier head's.
+- `Arch:` and `Fix:` pull requests get the reviewers' statuses as "not reviewed", so the
+  owner merges them without bypassing the rules, which also skipped CI.
+- A blocking finding blocks, whatever the reviewer's verdict says. A usage limit is not
+  one of a reviewer's two failures. Two reviews at once each keep their own transcript.
+- Granting the App "Commit statuses: write" takes effect at its next token, within the
+  hour, without restarting the daemon; the doctor reads what the installation accepted.
+  Swarm's readiness note reads every ruleset on `main`, on every page.
+- The pay-per-use calls the cost reviewer is told about are found in every SDK's
+  spelling, without false hits on words in comments.
+
+Both modes:
+- A usage limit never shortens a pause already there, such as the owner's or a brake's:
+  it replaced it with an hour's pause that lifted itself. An attempt that reports a usage
+  limit counts from the third time on the same feature, as other interruptions do.
+- A plan whose step keeps failing, such as a push GitHub refuses, no longer stops every
+  other plan: it is tried again for a while, then the pipeline pauses with its error.
+- In Manual, a module whose design lands while another is built waits for it, and the
+  other's pull request is still followed: a module whose id sorted first took over.
+- A design change that redefines a feature under way interrupts its attempt in Manual
+  too. An accepted feature it redefines is built again while its plan is. A plan past its
+  build is frozen: `submit_design` refuses a change to its features. A feature a design
+  change drops no longer breaks the Manager's items.
+- Dead ends after a failure: the owner's push to a plan's pull request branch is built
+  on, instead of pausing; a CI run the owner starts again on GitHub counts once it passes;
+  on resume, a failed deploy is looked at again, and a later successful apply on `main`
+  covers an earlier merge, as when GitHub cancels a pending run.
+- An invalid design on `main` pauses the pipeline with the reason, instead of a log line.
+- `harness budget --owner-hours` with the daemon down replaces hours already set, and
+  `harness mode` with the daemon down records the switch for it.
+
+Setup and the CLI:
+- `harness setup` on a machine without the App creates it and waits for its
+  installation before it writes `harness/config.json`: the config had no `project.repo`
+  or `project.bot`, and the project stayed local. A later run fills them in.
+- The setup's commit holds the files it wrote, and nothing else you had staged, and it
+  pushes only from `main`: run on another branch, it pushed that branch's commits to
+  `main`. A setup commit that wasn't pushed is offered again. A ruleset GitHub refuses,
+  as on a free plan's private repository, no longer stops the setup.
+- `harness recover` reads GitHub's `main`, not your checkout's, and says what it can't
+  rebuild.
+- A daemon is running only if its process started when `daemon.json` says: after a crash
+  or a reboot, `harness down` could stop another process that reused the pid. A lock
+  keeps two `harness up` apart, and closing the terminal stops the daemon cleanly.
+- The browser opens the dashboard with a code that works once, not the token, which
+  showed on xdg-open's command line.
+- Refused owner actions and unknown commands exit with an error.
+- The doctor: the probe's `web_read` check passes only on the harness's own refusal; the
+  workflow probe fails when the App's installation grants workflows; the ruleset must
+  apply to `main`; the statuses warning reads what the installation accepted; a Claude
+  token the usage endpoint refuses is reported; a half-created AWS provider is deleted
+  so the next run asks for the key again, and setup asks for the view role's ARN once.
+- AWS providers are named after the repository: two projects in folders of the same name
+  shared one.
+- The owner's time: a design without owner actions always fits, and actions done before
+  a redesign dropped them still count.
+- Hashes no longer depend on the machine's locale, a failed `terraform show` fails the
+  check that needs the plan, and the usage endpoint has a timeout.
+
+The sandboxes and the dashboard:
+- `web_read` refuses this machine's own addresses and the networks it is on: over IPv6,
+  or with a public IPv4 on an interface, an agent could read the host's services or the
+  router. A compressed page past the size limit stops decompressing, instead of growing
+  the daemon's memory, and a page full of unclosed comments or tags no longer freezes
+  the daemon for minutes. One deadline of 75 seconds covers a read and its redirects,
+  within the 90 seconds an agent waits. claude.ai and chatgpt.com are never read. An
+  HTML comment ends at `--!>` too, as browsers read it: the text after one was lost.
+- Usage limits are recognised in Claude Code 2.1's words ("You've hit your 5-hour
+  limit"): an attempt that hit one counted as failed.
+- An agent can no longer crash the daemon with a line too long for its follower, and a
+  terminal whose sandbox ends at once no longer crashes it either. Transcripts and the
+  agents' channels pick up again after the OpenShell gateway restarts, a hung `openshell`
+  call is stopped, and a tool call too large gets an error, not a wait.
+- A torn line in the Architect's inbox no longer breaks its prompt hook, and an
+  `extraHosts` entry for a bundle's host, such as github.com, no longer takes away its
+  git access.
+- The dashboard's cookie is named after its port, so two projects' dashboards no longer
+  log each other out: after upgrading, open the printed link once. Agent-written
+  Markdown loses its styles, which could hide parts of Needs you. The reviewers' "Shell
+  in" button works while a review runs.
+- The agents' image pins the AWS CLI, 2.39.6, by checksum.
+
+Releases:
+- The release workflow runs the install and the tests in a job without the npm OIDC
+  token, and a second job publishes the tarball the first one packed: no dependency's
+  code runs where the token can publish.
+
 ## 0.2.0 (2026-11-06)
 
 **Upgrading a project from 0.1.x:** install the new version, then run `harness setup`
@@ -14,10 +194,10 @@ new attempt clock of 120 minutes and Manager turn of 90.
 - **Swarm mode**, designed in `docs/architecture/proposal-v3.md`: a second mode, switched
   in the dashboard or with `harness mode`, in which the daemon merges a plan's pull
   request once CI and the reviewers' statuses pass. `CODE` plans merge when
-  `swarm.merge.code` is `daemon`; `INFRA` and `MIXED` plans need the cost estimate
-  under `swarm.merge.infraMonthlyUsdCeiling`, which no project produces yet, so they
-  wait for the owner. A pull request the policy leaves to the owner shows the reason
-  under Needs you. `Arch:` and `Fix:` pull requests stay the owner's.
+  `swarm.merge.code` is `daemon`; `INFRA` and `MIXED` plans need the cost job's
+  estimate under `swarm.merge.infraMonthlyUsdCeiling`, or the owner's button (both
+  below). A pull request the policy leaves to the owner shows the reason under Needs
+  you. `Arch:` and `Fix:` pull requests stay the owner's.
 - A plan is `CODE`, `INFRA` or `MIXED`, from its features' kinds. Plan pull requests
   carry the tag in their title, and CI's `verify` job keeps a `CODE` plan's pull
   request off the Terraform folder.

package/README.md

@@ -137,14 +137,17 @@ the token from `claude setup-token` at a hidden prompt, two clicks on GitHub for
 App, since GitHub creates and installs Apps only in the browser, three questions (your
 stack's network bundles, AWS or not, the hours of your time), and, with AWS, the role
 ARNs from your bootstrap and the gateway key. In order, it logs you in to `gh`; creates
-the repository on GitHub if the project has no remote, and writes the harness's files;
-asks the questions and writes `harness/config.json`, with the `staging` environment
-and the variables on GitHub for AWS; commits and pushes the files to `main` with your
-git, once you agree; runs `harness doctor` and fixes what it can (starts the OpenShell
-gateway, builds the agents' image, imports the Claude profile and creates the provider
-with your token, creates the App from its manifest and waits for you to install it,
+the repository on GitHub if the project has no remote; creates the App from its
+manifest when this machine has none, and waits for you to install it; writes the
+harness's files; asks the questions and writes `harness/config.json`, with the
+`staging` environment and the variables on GitHub for AWS; commits the files it wrote,
+and only those, with your git once you agree, and pushes them when you are on `main`;
+runs `harness doctor` and fixes what it can (starts the OpenShell gateway, builds the
+agents' image, imports the Claude profile and creates the provider with your token,
 applies the ruleset on `main`, creates the AWS provider with your key); runs the probe;
-and offers to start the daemon. Run it again at any time: what is done is skipped.
+and offers to start the daemon. Run it again at any time: what is done is skipped, and a
+setup commit that wasn't pushed is offered again. On a private repository of a free
+plan, where GitHub has no rulesets, it says so and goes on.
 
 The same by hand: `harness init` writes the harness's files into the repository, never
 over existing ones, and prints the setup checklist:
@@ -202,7 +205,10 @@ plans it finds there (see [Configuration](#configuration)).
 ## Concepts
 
 - **Module:** a part of the system you want to build, with one Architect and one
-  accepted proposal, then its plans. Modules are built one after another. Size a module
+  accepted proposal, then its plans. Modules are built one after another, in both modes:
+  the one under way is finished before the next starts, and only it has Developers,
+  Managers and reviewers. Every module's Architect stays available, so you can design the
+  next module while one is built; its plans wait their turn. Size a module
   so that its design fits in one conversation. With the default model, Opus 5.5, the
   Architect's context holds up to a million tokens, and a well-sized module never fills
   it. If a module's design keeps growing, split it into smaller modules: each gets its
@@ -214,7 +220,10 @@ plans it finds there (see [Configuration](#configuration)).
   tagged in the pull request's title, and a `CODE` plan's pull request may not touch
   the Terraform folder. Give infrastructure plans of its own.
 - **Feature:** one change that a Developer can make in one attempt, with at least one
-  check. Its definition is frozen once its design is merged.
+  check. A design change can redefine it while its plan is built: an attempt under way
+  stops, and the feature is built again with a fresh budget, even if it was accepted.
+  Once its plan is past its build (every feature of it accepted, then its pull request
+  and merge), it is frozen: a change goes in a new plan.
 - **Check:** a shell command, run from the repository root, that exits 0 when the feature
   works. `pre-merge` checks run on every attempt and in CI; `post-deploy` checks run
   after an infrastructure deploy.
@@ -226,16 +235,22 @@ plans it finds there (see [Configuration](#configuration)).
   policy or setting a secret. A **gate** holds back the plans or features it blocks
   until you mark it done; a **task** holds nothing back.
 - **Protected files:** the design and its checks, CI, and what agents read as
-  instructions: `harness/`, `.github/`, `.claude/`, `CLAUDE.md`, `AGENTS.md`,
-  `ARCHITECTURE.md`, `init.sh`, tool configs and the npm scripts that checks run. A
-  `Plan:` or `Fix:` pull request may not change them: CI's `verify` job, run with the
-  base branch's rules, fails it. They change through an `Arch:` pull request, or your own
-  commits. `harness/lock.json` holds their hashes.
+  instructions: `harness/`, `.github/`, `ARCHITECTURE.md`, `init.sh`, and in any folder
+  `.claude/`, `CLAUDE.md`, `CLAUDE.local.md` and `AGENTS.md`, which Claude Code reads
+  wherever they are; the configs that decide what a check runs (ESLint, Prettier, Biome,
+  Vitest, Vite, Jest, Babel, Playwright, Mocha, pytest, tox, and package.json's `jest`,
+  `babel` and `mocha` fields); and the npm scripts that checks run. A `Plan:` or `Fix:`
+  pull request may not change them, nor add a local link to `package-lock.json`: CI's
+  `verify` job, run with the base branch's rules, fails it, and the daemon refuses it
+  first. They change through an `Arch:` pull request, also judged by the base branch's
+  rules, so what it newly protects counts from the next one, or your own commits.
+  `harness/lock.json` holds their hashes.
 - **`progress.txt`:** one line per accepted feature and satisfied gate, committed with
-  the work. It only grows.
+  the work. It only grows. When plans in parallel both add lines, the daemon keeps both.
 - **Brakes:** counters and deadlines, not judgment. Three failed attempts in a row, a
   Manager that leaves an item waiting for 180 minutes, or CI still failing after two fix
-  rounds pause the pipeline until you resume it.
+  rounds pause the pipeline until you resume it. A usage limit pauses it for an hour,
+  and never shortens a pause already there.
 
 ## The dashboard
 
@@ -246,7 +261,18 @@ behind a token. Its views:
 - **Project:** modules, proposals, plans and features, with attempts, findings, CI,
   deploys and `progress.txt`.
 - **Agents:** the Architect's terminal, the Manager's and the Developers' live
-  transcripts, a message box for the Manager, and a shell in any agent's sandbox.
+  transcripts, a message box for the Manager, and a shell in any agent's sandbox. An
+  attempt's card keeps the network requests its sandbox's policy refused.
+- **Sandboxes:** what runs on the OpenShell gateway. This project's sandboxes, with what
+  each is for, whether anything still uses it, and the CPUs and memory it uses now,
+  read from `docker stats` every five seconds. A left-over one, which a crash or a
+  failed delete left, has a button to delete it; the daemon deletes them itself when it
+  starts and every hour, except an Architect's. Select one to see the network requests
+  its policy refused, from its log: the program, the host, why, and how often. Then the
+  other projects' sandboxes, which the dashboard only lists, and the gateway's status.
+  Above them, the caps on each new sandbox: how many CPUs and how much memory it may
+  use, so that agents and checks in parallel leave the machine usable. There is no cap
+  until you set one.
 - **Events:** the event log, live, with a filter.
 
 The header pauses and resumes the pipeline: a pause lets what runs finish, and starts
@@ -280,10 +306,17 @@ once CI passed and every status in `swarm.requiredStatuses` is green on its head
   estimate over the ceiling still waiting for you. The button is off by default, and
   the choice is recorded in the event log.
 
+Only an estimate of the pull request's current head counts: after a fix round, the new
+head needs its own. Before it merges, the daemon merges `main` into the pull request's
+branch if `main` moved since CI ran, so CI and the reviewers judge what `main` gets; a
+conflict leaves the pull request to you, to resolve on GitHub.
+
 Anything else waits for you, under **Needs you** with the reason. `Arch:` and `Fix:`
 pull requests are yours in both modes. In Swarm, GitHub's rules need no approval but
 require the reviewers' statuses, pinned to the App, so even the daemon can't merge
-before they pass.
+before they pass. The reviewers read plan pull requests only: the daemon gives an
+`Arch:` or `Fix:` pull request the two statuses as "not reviewed", so you merge it
+without bypassing the rules, and CI still gates it.
 
 **Before a launch.** In Swarm the daemon reads your subscription's usage before it
 starts an attempt, and at or above `swarm.usageCeilingPercent` the pipeline waits for
@@ -302,9 +335,10 @@ with a verdict and findings. The daemon posts the findings on the pull request a
 review, with comments on the lines of the diff, and sets the reviewer's commit status,
 `harness/security` or `harness/cost`. A blocking verdict opens a fix round on the
 plan branch, like a CI failure: a Developer fixes with the findings as guidance, the
-Manager reviews, CI and the reviewers run again on the new head. After
-`swarm.securityFixRounds` or `swarm.costFixRounds`, the pull request is yours. In
-Manual, `swarm.reviewersInManual` runs them as comments only.
+Manager reviews, CI and the reviewers run again on the new head. A blocking finding
+blocks, whatever the verdict says. After `swarm.securityFixRounds` or
+`swarm.costFixRounds`, the pull request is yours. In Manual,
+`swarm.reviewersInManual` runs them as comments and statuses that gate nothing.
 
 The App needs **Commit statuses: write** for the verdicts. An App created before this
 version has read only: give it the permission on GitHub, accept it on the installation,
@@ -318,16 +352,19 @@ Architect is told to declare every dependency. Each attempt starts from the plan
 branch as it is. When another feature lands first, the daemon merges the new head
 into the attempt before its checks, so they see the accepted work, and the feature
 lands as one commit on the head. A conflict interrupts the attempt, without counting
-it, and the next one starts from the new head. A design change merged while a feature
-is built interrupts its attempt the same way, and the next one builds the new
-definition. Manual mode builds one feature at a time, as before. In both modes, the
+it, and the next one starts from the new head. In both modes, a design change merged
+while a feature is built interrupts its attempt the same way, and the next one builds
+the new definition. Manual mode builds one feature at a time, as before. In both modes, the
 Architect hears in one line when a plan's pull request opens, waits for you, is
 blocked by a reviewer, or merges.
 
 **Parallel plans.** A plan may declare `dependsOn`, the plans of its module that must
 be merged before it starts; without it, it waits for the previous plan, as always. In
-Swarm, up to `swarm.maxPlans` plans whose dependencies are merged build at once, each
-on its own branch with its own Manager, keyed `module/plan` in the Agents view; a
+Swarm, up to `swarm.maxPlans` plans of the module under way whose dependencies are
+merged build at once, each on its own branch with its own Manager, keyed `module/plan`
+in the Agents view. When one merges, `main` is merged into the others, `progress.txt`
+keeping both sides' lines; a conflict in other files is resolved in that plan's pull
+request. A
 feature may also depend on a feature of an earlier plan, as `P1/F03`, and then waits
 for that plan's merge. The Project view draws each module's features as a graph, plan
 by plan, with an edge per dependency: green accepted, blue under way, red escalated,
@@ -337,7 +374,7 @@ as before.
 **The cost job.** `harness install-ci` adds a `cost` job to the workflow: on a pull
 request that has `iac/`, it runs [Infracost](https://www.infracost.io) on the base and
 the head and uploads the estimate as the `cost` artifact, which the daemon reads once
-CI passed. It needs the repository secret `INFRACOST_API_KEY`, a free key from
+CI passed and the `cost` job itself succeeded. It needs the repository secret `INFRACOST_API_KEY`, a free key from
 `infracost auth login`; without it the job does nothing, no estimate exists, and
 `INFRA` and `MIXED` plans wait for you with that reason. Infracost sees your Terraform's
 resource types and sizes, not your code or state. The cost reviewer gets the estimate in
@@ -371,7 +408,7 @@ too.
 | `harness github-app create --org <org>` | Creates the harness's GitHub App, once per machine |
 | `harness github-app check --repo <org>/<repo>` | Checks that the App can reach the repository |
 | `harness github-setup --repo <org>/<repo> [--mode manual\|swarm]` | Sets merge commits only, and the ruleset on `main` for the daemon's mode, with your own `gh` |
-| `harness budget --owner-hours <n>` | Sets the hours of your time for the whole project; with the daemon down, it records them when it starts (`--agent-hours` sets the threshold) |
+| `harness budget --owner-hours <n>` | Sets the hours of your time for the whole project; with the daemon down, it records them when it starts, over hours set before (`--agent-hours` sets the threshold) |
 | `harness setup [--repo <owner/name>] [--owner <login>]` | Sets up this machine and the project, asking only for what is yours; run it again any time |
 | `harness install-ci [--owner <login>]` | Writes the workflow, its CI script and `CODEOWNERS` again, after an upgrade |
 | `harness lock` | Writes `harness/lock.json`, the hashes of the protected files |
@@ -385,8 +422,8 @@ too.
 | `harness message <text>` | Writes to the Manager of the module being built |
 | `harness retry <module>/<plan>/<feature>` | Gives an escalated feature one more attempt; `--note` adds guidance |
 | `harness resume` | Lifts a pause |
-| `harness mode [manual\|swarm]` | Shows the mode, or switches it |
-| `harness recover` | Rebuilds a lost `.harness/` from `main` and GitHub |
+| `harness mode [manual\|swarm]` | Shows the mode, or switches it; with the daemon down, it records the switch for when it starts |
+| `harness recover` | Rebuilds a lost `.harness/` from GitHub's `main` and branches, and lists what it can't: the mode, the budgets, the owner tasks done |
 
 ## Configuration
 
@@ -395,7 +432,7 @@ through an `Arch:` pull request, or a commit of your own on `main`.
 
 ```json
 {
-  "harnessVersion": "0.1.1",
+  "harnessVersion": "0.4.0",
   "project": { "name": "shop", "repo": "<org>/shop", "bot": "<org>-harness[bot]" },
   "roles": {
     "architect": { "model": "claude-opus-5-5", "effort": "max" },
@@ -418,8 +455,8 @@ through an `Arch:` pull request, or a commit of your own on `main`.
 | `network.bundles` | `["core"]` | The hosts sandboxes reach, by bundle: `core`, `node`, `python`, `aws`, `terraform`, `go`, `rust`, `jvm`, `opentofu`, `browsers`. The Architect gets them all. |
 | `network.extraHosts` | `[]` | More hosts, read-only |
 | `checks` | `[]` | Checks that every feature must keep passing, such as `npm run lint` |
-| `protect.files`, `protect.jsonFields` | none | More protected files, and protected JSON fields by file, like `{"tsconfig.json": ["/compilerOptions/strict"]}` |
-| `sandbox.image` | `razzou-harness/agent:0.1.0` | The agents' image, which `harness doctor --build-images` builds |
+| `protect.files`, `protect.jsonFields` | none | More protected files, as paths or globs (`scripts/*.sh`, `docs/`, `**/Makefile`), and protected JSON fields by file, like `{"tsconfig.json": ["/compilerOptions/strict"]}` |
+| `sandbox.image` | `razzou-harness/agent:<version>` | The agents' image, tagged with the harness's version, which `harness doctor --build-images` builds |
 | `sandbox.claudeProvider` | `claude-sub` | The OpenShell provider that holds your Claude token |
 | `sandbox.env` | `{}` | Environment variables for every sandbox |
 | `github.requiredChecks` | `["verify", "checks"]` | The CI jobs a pull request must pass; `tf-plan` is added with Terraform |
@@ -519,7 +556,7 @@ and Terraform applies only in CI, after you merge.
 1. In `harness/config.json`, add `aws` and `terraform`:
 
    ```json
-   "aws": { "region": "us-east-1", "provider": "aws-view-shop", "services": ["sts", "s3", "iam", "sqs"] },
+   "aws": { "region": "us-east-1", "provider": "aws-view-<org>-shop", "services": ["sts", "s3", "iam", "sqs"] },
    "terraform": { "dir": "iac", "backendConfig": "backend-configs/staging.hcl", "varFile": "env/staging.tfvars" }
    ```
 
@@ -558,8 +595,9 @@ What agents can't do, and what stops them:
 - **Change AWS.** A read-only role with explicit denies, and applies only in CI after
   your merge.
 - **Go anywhere online.** Sandboxes reach listed hosts, read-only. Other pages go
-  through `web_read`: GET only, public addresses only, checked again after every
-  redirect.
+  through `web_read`: GET only, public addresses only, never this machine's own
+  addresses or the networks it is on (IPv6 included), checked again after every
+  redirect, within 75 seconds and 2 MB, decompressed.
 - **Decide alone.** Code runs the loop: deadlines, attempt budgets, checks in fresh
   sandboxes and the merges, yours or the Swarm policy's, are enforced by the daemon,
   not left to the agents.
@@ -608,20 +646,31 @@ To report a vulnerability, see `SECURITY.md` in the source repository.
 | `Claude provider: … is missing` | `claude setup-token`, then `harness doctor` in a terminal: it asks for the token |
 | `GitHub App: … 404` | Install the App on the repository, from the link `harness github-app create` printed, or the organization's settings |
 | `ruleset: …` fails | `harness github-setup --repo <org>/<repo>`. A private repository needs a paid GitHub plan for rulesets. |
+| `ruleset: applies to the default branch, master, not to main` | Make `main` the repository's default branch on GitHub, then `harness github-setup --repo <org>/<repo>` |
 | `.github/… differs from this version of the harness` | `harness install-ci`, then commit the files yourself |
 
 While the daemon runs:
 - **The pipeline is paused.** **Needs you** says why: attempts that failed in a row, a
-  Manager that didn't act, CI still failing after its fix rounds, a usage limit, or a
-  broken environment. Fix the cause, then **Resume**.
+  Manager that didn't act, CI still failing after its fix rounds, a deploy still failing
+  after its Fix PRs, a usage limit, an invalid design on `main`, or a broken environment.
+  Fix the cause, then **Resume**. On resume, a failed full check run runs again and a
+  failed deploy is looked at again: a later successful apply on `main` counts.
+- **CI fails for a reason outside the code.** Fix it (a secret, the runner), then re-run
+  the jobs on GitHub: a passing re-run counts. To fix the code yourself, push to the pull
+  request's branch, or resolve a conflict in GitHub's editor: the daemon builds on your
+  push, and CI runs again.
 - **A feature is escalated.** It used its attempts. In **Needs you**, give it one more
   attempt with your guidance, send it to the Architect (the design may change), or pause.
 - **The dashboard asks for its token.** Each `harness up` prints a new link: open that
-  one.
+  one. Each project's dashboard keeps its own cookie, named after its port, so several
+  can be open at once. The browser it opens by itself logs in with a code that works once, for two
+  minutes, so the token never shows on a command line.
 - **A merge takes minutes to show up.** The daemon polls GitHub: every minute, then every
   five once nothing has changed for ten minutes.
-- **Closing the terminal stopped the daemon.** Run `harness up` again: it picks up from
-  its event log, and the agents kept working meanwhile.
+- **Closing the terminal stopped the daemon.** It stops cleanly, as with `harness down`.
+  Run `harness up` again: it picks up from its event log, and the agents kept working
+  meanwhile. A daemon that crashed leaves `.harness/daemon.json` and
+  `.harness/daemon.lock` behind: the next `harness up` sees that their process is gone.
 
 ## Development
 

package/dist/agents/claude-code.js

@@ -170,6 +170,13 @@ export function reviewJsonSchema() {
     const { $schema: _, ...schema } = z.toJSONSchema(ReviewReportSchema, { target: 'draft-7' });
     return JSON.stringify(schema);
 }
+/**
+ * How a session's error result says the subscription ran out. Claude Code 2.1.x writes
+ * "You've hit your 5-hour limit · resets 3pm", "You've reached your …", "You're out of
+ * usage credits", "You're out of extra usage" or "Your org is out of usage …"; older
+ * versions wrote "Claude AI usage limit reached|<epoch>".
+ */
+const USAGE_LIMIT = /usage limit|limit reached|rate.?limit|you['’]ve (?:hit|reached) your|you['’]re out of (?:usage credits|extra usage)|your org is out of usage/i;
 /** A reviewer's session: its report, or why there is none, read like a Developer's. */
 export function readReview(stream, exitCode, stderr = '') {
     const result = lastResult(stream);
@@ -179,7 +186,7 @@ export function readReview(stream, exitCode, stderr = '') {
     }
     const usage = toUsage(result.usage, result.total_cost_usd);
     const text = typeof result.result === 'string' ? result.result : '';
-    if (result.is_error === true && /usage limit|limit reached|rate.?limit/i.test(text))
+    if (result.is_error === true && USAGE_LIMIT.test(text))
         return { outcome: 'usage_limit', detail: text.slice(0, 500), usage };
     const report = ReviewReportSchema.safeParse(result.structured_output);
     if (!report.success)
@@ -198,7 +205,7 @@ export function readResult(stream, exitCode, stderr = '') {
     }
     const usage = toUsage(result.usage, result.total_cost_usd);
     const text = typeof result.result === 'string' ? result.result : '';
-    if (result.is_error === true && /usage limit|limit reached|rate.?limit/i.test(text)) {
+    if (result.is_error === true && USAGE_LIMIT.test(text)) {
         return { outcome: 'usage_limit', detail: text.slice(0, 500), usage };
     }
     const report = ReportSchema.safeParse(result.structured_output);

package/dist/anthropic/usage.js

@@ -2,10 +2,11 @@ import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'n
 import { join } from 'node:path';
 import { configDir } from '../github/app.js';
 export const USAGE_URL = 'https://api.anthropic.com/api/oauth/usage';
-/** Reads the usage with the token the provider was created with. Throws when the endpoint refuses or answers something else. */
+/** Reads the usage with the token the provider was created with. Throws when the endpoint refuses, answers something else, or not within 15 seconds. */
 export async function readUsage(token, fetchImpl = fetch) {
     const response = await fetchImpl(USAGE_URL, {
         headers: { authorization: `Bearer ${token}`, accept: 'application/json', 'anthropic-beta': 'oauth-2025-04-20', 'user-agent': 'razzou-harness' },
+        signal: AbortSignal.timeout(15_000),
     });
     if (!response.ok)
         throw new Error(`the usage endpoint answered ${response.status}`);

package/dist/checks/runner.js

@@ -50,7 +50,8 @@ async function makePlan(driver, sandbox, workDir, options) {
         `cd ${sh(`${workDir}/${tf.dir}`)} || exit 1`,
         `terraform init -input=false -no-color -backend-config=${sh(tf.backendConfig)} > ${sh(`${out}/terraform-init.log`)} 2>&1 || { tail -c 3000 ${sh(`${out}/terraform-init.log`)}; exit 1; }`,
         `terraform plan -input=false -no-color -lock=false -var-file=${sh(tf.varFile)} -out=${sh(`${out}/plan.bin`)} > ${sh(`${out}/terraform-plan.log`)} 2>&1 || { tail -c 3000 ${sh(`${out}/terraform-plan.log`)}; exit 1; }`,
-        `terraform show -json ${sh(`${out}/plan.bin`)} > ${sh(`${out}/plan.json`)}`,
+        // Without the JSON, the checks would read an empty $HARNESS_PLAN_JSON: the plan fails instead, with terraform's error.
+        `terraform show -json ${sh(`${out}/plan.bin`)} > ${sh(`${out}/plan.json`)} || exit 1`,
         `grep -E '^(Plan:|No changes)' ${sh(`${out}/terraform-plan.log`)} || true`,
     ].join('\n');
     const result = await driver.exec(sandbox, script, { timeoutSec: 900 });