vinta-ai-workflows 0.7.0-alpha31 → 0.7.0-alpha33

package/CHANGELOG.md

@@ -7,6 +7,7 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [0.7.0] — YYYY-MM-DD
 
+<!-- pre-release: 0.7.0-alpha33 on 2026-10-16 -->
 <!-- pre-release: 0.7.0-alpha31 on 2026-10-09 -->
 <!-- pre-release: 0.7.0-alpha30 on 2026-10-09 -->
 <!-- pre-release: 0.7.0-alpha20 on 2026-09-24 -->
@@ -32,6 +33,91 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- **`vinta-ai-maestro`: ways past a stale gate verdict.** `gate <id>
+  --no-cache` runs a gate past its cached result and keeps the new one in its
+  place; a cached red now says so. `gate-cache invalidate <run-id> <gate-id>
+  [--tree <hash>]` forgets a gate's results for the operator and the run
+  coordinator (`POST /api/runs/:id/gates/:gate/invalidate`, journalled as
+  `gate_cache_invalidated`; an agent's token cannot reach it). Both are for a
+  verdict whose cause git does not track — an ignored file, a tool's cache, an
+  installed dependency — which the tree-keyed cache would otherwise replay.
+
+- **`vinta-ai-maestro`: a phase's decisions outlive the session they were
+  made in.** Each node now keeps a list of what was settled for it: agents'
+  questions with their answers (marked as the operator's, the coordinator's,
+  or unattended), the operator's `node context` and `redirect` text, and the
+  findings the review rejected with their counter-evidence. Every later
+  prompt carries the list — implementer, fixer, chores, and the review, which
+  hands it to its reviewer — so a fresh reviewer, a replaced session or a
+  retry no longer re-asks or re-raises what was already decided. Before
+  this, an unattended run answered one question four times and a phase ran
+  some thirty rounds without converging, and operator context sent with
+  `node context` had to be re-sent after a session change. The review now
+  rejects a finding that re-opens a decision, citing it, and asks the
+  operator about it at most once, and only with new evidence. It ends its
+  report with a `REJECTED:` line per rejected finding, which the run keeps.
+  The list is bounded (the newest 12 answers and notes and the newest 8
+  rejected findings), kept across retries, written to
+  `runs/<id>/nodes/<node>/decisions.jsonl` and read back when a run resumes.
+
+- **`vinta-ai-maestro judge calibrate`: measure a permission-judge question
+  before a run relies on it.** It replays a past run's `Bash` calls
+  (`--run <run-id>`), or a file of commands each optionally labelled `safe` or
+  `unsafe` (`--commands <file>`), against a candidate question
+  (`--question` / `--question-file`) and threshold (`--threshold`) through the
+  classifier in `--system-one`. Nothing is executed. It reports how many would
+  be allowed and refused, the score distribution, every labelled command
+  judged the wrong way, and the highest-scoring must-deny command, and exits 1
+  on a misjudged one so a case file can guard a project's question in CI.
+  Commands are printed as recorded, never their output.
+
+- **`vinta-ai-maestro`: `project.reset_cmd` and `project.recycle_keep`.**
+  `reset_cmd` is a project hook run inside a lane when it is recycled for the
+  next phase, and only then, after maestro's own resets and before
+  `setup_cmd`. `recycle_keep` lists gitignore patterns a recycled lane keeps
+  (`.venv`, say) now that the recycle cleans ignored files. Both optional, in
+  `workflow.v1`.
+
+- **`vinta-ai-maestro`: `node fresh <run> <phase>` drops a phase's agent
+  session without failing the attempt.** The phase's next turn starts cold with
+  the whole brief, journalled `node_session` `reason: operator_fresh`; the turn
+  in flight is not stopped (pair it with `redirect` for that). It is the way out
+  of a session gone wrong — an agent replaying killed work or carrying on with
+  the previous phase — that used to cost an `abort`. Also `POST
+  /api/runs/:run/nodes/:node/fresh`, and the run coordinator can use it. The
+  post-mortem's `operations.node_operations[].op` gains `fresh` (additive, in
+  `postmortem.v1.schema.json`).
+
+
+- **`vinta-ai-maestro`: a busy crew member is replaced, not borrowed
+  (`defaults.max_spare_crew`, default 2).** When the member a phase is planned
+  for — or the one an operator picked with `retry with <member>` — is busy, or
+  is planned for a phase still to come, the run takes on a spare in that
+  member's image (same tier, model and harness) with a worktree provisioned for
+  it there and then, instead of borrowing a member another pending phase is
+  waiting for, or waiting. A member nobody is planned for is still borrowed, an
+  idle spare is reused first, and a member busy only with a finished phase's PR
+  chores is waited for. Journalled as `node_crew` `reason: spare_crew` and shown
+  in the post-mortem's `crew_substitutions`. Set `0` in the plan or under
+  `maestro.defaults` to keep the roster to the plan's. One observed run left a
+  phase on its critical path idle for 17 minutes while a retry held the member
+  it was planned for.
+- **`vinta-ai-maestro`: `defaults.pull_requests: plan` opens one PR for the
+  run.** The default, `phase`, is unchanged: a PR per phase, per integration
+  branch, and the plan PR. `plan` opens the plan PR alone, from the last wave
+  branch, and skips the phases' `after_pr` chores (there is no phase PR for
+  them). Also accepted under `maestro.defaults` in `.vinta-ai-workflows.yaml`.
+- **`vinta-ai-maestro doctor` warns when a phase gate will run its full command
+  every time** (`gate-scope:<gate>`), and every run prints it at start: a
+  `test` or `lint` gate a phase uses has no `scoped_cmd` under
+  `gate_scope: scoped`. It says whether `commands.test_unit_scoped` /
+  `lint_scoped` was passed over for having no `{changed_files}` / `{touches}`
+  placeholder — a skill-era line such as `pytest <app>/tests/` is not inherited
+  — or nothing is configured, and names the key to set (e.g.
+  `pytest --testmon {changed_files}`), or `maestro.defaults.gate_scope: full`
+  to accept it. One observed run spent two of its five hours running a
+  6,500-test suite on every phase gate and fix round.
+
 - **`vinta-ai-maestro`: `run` now shows what a slow start is doing.** Until
   now `run` printed "starting in the background…" and nothing else until the
   run was up, which can take minutes (`prepare_cmd`, preflight, database
@@ -523,6 +609,79 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Changed
 
+- **`vinta-ai-maestro`: a recycled lane no longer keeps the last phase's
+  ignored files.** A lane handed to the next phase kept everything gitignored,
+  and one kept `apps/api/.mypy_cache` and a deleted package's `__pycache__`,
+  so mypy reported 18 errors on clean code. The recycle now cleans ignored
+  files too, keeping only the copied `node_modules`, the `env_files` and the
+  new `project.recycle_keep` patterns. **Migration:** anything expensive your
+  lanes build and should keep across phases, such as a `.venv`, goes in
+  `recycle_keep`; otherwise `setup_cmd`, which already runs on every
+  recycle, rebuilds it.
+- **`vinta-ai-maestro`: agents wait for background work the way a normal
+  Claude Code session does.** A headless session no longer ends at the first
+  turn that leaves background work running. It stays open, the agent is woken
+  in the same session when that work reports, and the session ends on the
+  first turn that leaves nothing running. A held session ends after 30 minutes
+  with no output, and any work still running is cleaned up. Harnesses declare
+  this as a new `backgroundWork` capability:
+  - **claude-code:** the CLI wakes the agent itself. A resumed session also no
+    longer ends on the empty turn the CLI replays first.
+  - **codex:** the adapter wakes the agent itself (see below).
+  - **opencode:** on servers the adapter starts, background `task` sub-agents
+    are enabled through `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS`. A
+    configured `baseUrl` reports `false`.
+
+  This fixes the slow review loop. The reviewer, resumed with a message, was
+  killed with the turn. Every round after the first ended "waiting on the
+  reviewer" with no verdict, went to the operator as `unapproved`, and
+  restarted with a cold reviewer. Every turn's prompt now says how to wait on
+  its harness (end the turn, never sleep or poll), naming that harness's own
+  tools. The review starts each round's gates alongside the reviewer's next
+  pass; on opencode, which has no background shell, the reviewer runs in the
+  background and the gates run beside it.
+
+- **`vinta-ai-maestro`: codex runs on `codex app-server` instead of
+  `codex exec`, and needs codex-cli 0.147.0 or later.** `exec` killed
+  background work when the turn ended. App-server keeps it, and the adapter
+  starts the next turn naming, by id, what finished. Codex now also supports
+  `inject`, so steering a running codex node is a message, no longer an
+  interrupt and resume. Each thread is started and resumed with an explicit
+  sandbox, approval policy and reviewer, so `~/.codex/config.toml` can no
+  longer widen `--permission`. Under `--permission ask`, a request for approval
+  is now recorded as a `permission_request` and declined; before, the model
+  could not ask at all. A logged-out codex is refused at spawn instead of
+  failing mid-turn.
+
+- **`vinta-ai-maestro`: an opencode review can no longer pass on its own
+  prompt.** The adapter echoed the user's prompt back as the agent's text. The
+  review prompt contains the line `VERDICT: pass`, so a review that stated no
+  verdict could read as approved. opencode 1.19's `permission.asked` event is
+  now mapped too.
+- **`vinta-ai-maestro`: an unattended run answers `exhausted` and `unapproved`
+  with `continue` once, then `stop`.** It answered `stop` straight away, which
+  failed the phase; the unattended retry then re-drove it from `implement` on
+  a cold session, gates and review from scratch, to reach the same question —
+  twelve failed attempts in one observed run. A plan question's
+  `unattended_answer` may now be a list, one answer per unattended answer
+  within an attempt, the last repeating.
+- **`vinta-ai-maestro`: a phase's dependents start once it has merged, pushed
+  and opened its PR**, when only `after_pr` chores that cannot fail it are left
+  (a review canvas, a PR comment). They used to wait for those too — up to four
+  minutes a phase on the critical path.
+- **`vinta-ai-maestro`: an agent's `gate <id>` is refused while an earlier gate
+  of the phase is red on the same tree**, naming that gate, and runs once the
+  tree moves. A `for g in lint typecheck test` loop no longer runs the suite
+  against a tree its typecheck already failed.
+- **`vinta-ai-maestro`: a crew member woken on a new phase is told the
+  objective changed** before anything else — the previous phase is finished
+  and nothing in flight for it is owed — ahead of the brief and the note about
+  what moved in its worktree.
+- **`vinta-ai-maestro`: the coordinator's gate-cost wake scales with the run**:
+  more than 15 minutes of uncached gate time per phase that ran it, never less
+  than 30 minutes, instead of every 30 minutes; it says how many phases the
+  time is spread over and whether the gate lacks a scoped form.
+
 - **`vinta-ai-maestro`: lane database names stay within Postgres's 63-character
   identifier limit, with room for test-runner affixes.** A forked lane database
   or template whose `<name>_wt_<lane>` form was too long was silently truncated
@@ -798,6 +957,144 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Fixed
 
+- **`vinta-ai-maestro`: a fix loop that changes nothing now stops and asks.**
+  A typecheck red because of ignored files left in a lane kept coming back
+  from the gate cache after they were gone, and twenty fixers in a row found
+  nothing to fix. When a gate is red again on the very tree a fixer turn left
+  unchanged, the scheduler reruns that gate once without the cache; if it is
+  still red the same way, `standard-phase` goes to `exhausted` instead of
+  spawning another fixer — with or without `max_fix_rounds` — and the run
+  coordinator is woken. New guard fact `gate.stalled`, new `run_gate` param
+  `no_cache`, new journal event `gate_stalled`. A fixer that moved the tree at
+  all is never a stall. A custom pipeline keeps its own guards and can opt in
+  on `gate.stalled`.
+
+- **`vinta-ai-maestro`: a claude-code review no longer loses a reviewer answer
+  that comes back early.** When a reviewer resumed with `SendMessage` answered
+  while the agent was still writing its last message, the session ended at the
+  turn's `result` and killed the turn the CLI starts to hand over the answer.
+  The review then stated no verdict and went to the operator as `unapproved`.
+  The session now waits for that turn, for at most a minute of silence.
+
+- **`vinta-ai-maestro purge` no longer ends a run you did not name.** A bulk
+  `purge --lanes` removed the lanes of paused, failed and interrupted runs —
+  the integration worktree included — so `run --resume` had nothing to adopt,
+  and a bulk `purge` deleted those runs' frozen snapshots. A run that could
+  still be resumed is now kept whole, directory and lanes, and named with the
+  reason; purge it by name, or pass the new `--force`. A run whose job is
+  still running is kept even then.
+- **`vinta-ai-maestro purge --lanes` tears a lane down, not just its
+  worktree.** It used to leave every forked database, compose stack and lane
+  summary behind, including summaries whose worktree was already gone. Each
+  reaped lane's summary is now its teardown manifest: `docker compose -p
+  <project> down`, `docker volume rm` for its forked volumes, the `reset_cmd`
+  of its own service namespaces, and `dropdb` (or the project's `dropdb_cmd`)
+  for its forked databases — every command listed before anything runs, and
+  under `--dry-run` nothing runs. Only what is provably that lane's is
+  touched: never a compose-delivered database, an index-numbered service slot,
+  or a summary `prepare-worktree` wrote for a worktree you made. A step that
+  fails is reported, and its lane's summary is kept so a rerun retries it.
+- **`vinta-ai-maestro run --help` says which runs resume.** It claimed a run
+  that "finished" could not be resumed, while a `failed` run resumes — its
+  failed phases and the ones they blocked are attempted again, and `status`
+  prints the command for it. The help now names paused, interrupted and
+  failed as resumable, and only `done` and `cancelled` as refused.
+- **`vinta-ai-maestro`: the shipped permission-judge question no longer
+  refuses routine commands.** Under `--permission judged` it allowed 44 of 69
+  commands from a real run, refusing `ls .env*`, `cat .env.example`,
+  `docker ps` and the project's own `make` targets. The question now says a
+  secret is a *value* — listing env files and reading templates is allowed,
+  reading a real `.env` is not — allows read-only inspection and the project's
+  own commands in its worktree, and still refuses pushes, `sudo`, writes
+  outside the worktree and another project's containers or volumes. A
+  project that set its own `judges.permission.question` is unaffected; the
+  default `allow_above` stays 0.9.
+
+- **`vinta-ai-maestro`: the disk preflight sizes the pool the run will
+  really create.** `run --resume` with every worktree still on disk was
+  refused (`3 lanes + 1 integration worktree needs 37.9 GiB, only 18.0 GiB
+  free`) by a doctor that charged for them all again; it now charges only the
+  worktrees still to be made, and passes a resume that makes none. A staffed run
+  is counted as the pool provisions it — a worktree per crew member, not per
+  unit of `resources.lane.capacity` — plus `defaults.max_spare_crew`
+  headroom, and the doctor, the pool and the refusal line now name the same
+  count. The per-lane estimate is the tracked tree at the base branch, the
+  copied `node_modules` and the `env_files`, instead of a walk of the whole
+  main checkout that counted `.git`, the `.vinta-ai-maestro/` store (lanes
+  included) and ignored caches — one run's estimate had grown from 4.0 to
+  9.5 GiB a lane against real lanes of about 1.1 GiB.
+
+- **`vinta-ai-maestro`: an integration merge a pause, stop or kill caught
+  half-way no longer wedges the run.** Every later attempt used to fail on
+  `integration worktree is mid-merge` until someone ran `git merge --abort` by
+  hand. The integrator now recognises a merge it started — one of the plan's
+  phase branches (or a kept resolution, or the plan branch) into one of its
+  `integ-`/`wave-` branches — keeps what it had under
+  `refs/vinta-ai-maestro/abandoned/<branch>`, aborts it and redoes it, so the
+  result is gated again; each one journals `integration_reclaimed`. The same
+  sweep runs on `run --resume` and when a stop outlives its deadline. A conflict
+  left for a person that nobody finished is redone on the retry the same way.
+  A merge the run did not start is still refused by name. A failed `git_merge`
+  of a named branch now aborts its merge.
+
+- **`vinta-ai-maestro`: aborting the only runnable phase no longer ends the
+  run.** A run whose remaining phases all depended on an aborted one ended
+  `failed` at once, and the `node retry` that followed was refused as `run has
+  ended`. Aborted phases now hold the run open for their retry (no timer retries
+  them); `pause` or `stop` ends it. Under `--on-failure stop` an abort still ends
+  the run. A retry sent while the aborted attempt is still winding down is
+  applied once it has.
+
+- **`vinta-ai-maestro`: a gate run inside `with` no longer deadlocks every
+  lane.** `vinta-ai-maestro with test-suite -- vinta-ai-maestro gate test`
+  held the only `test-suite` slot while the gate queued for it, and every
+  lane's tests and gates queued behind the pair (55 minutes in one run). The
+  gate guard now refuses `gate` inside `with` and tells the agent to run the
+  gate on its own. The daemon refuses a gate whose resources the asking phase
+  already holds through `with` (`holds_required:<resource>`), naming the
+  process holding them. The agent prompts state the same rule.
+- **`vinta-ai-maestro`: `with` and `gate` say who they are waiting on.** A
+  queued answer names each holder of the resource: the phase, its lane, and
+  how it holds it (`with` with its process id, a gate an agent ran, or the
+  phase's own gate step). When the holder is the asking phase itself, the
+  message says so. It used to say "held by another lane" in exactly that case.
+  `gate` now says "queued" until the gate has its resources and "running"
+  after; it used to say "running" throughout.
+- **`vinta-ai-maestro`: commands left behind by an ended agent session stop
+  holding capacity.** Each agent session gets a turn id
+  (`VINTA_AI_MAESTRO_TURN_ID`), which `with` and `gate` send with every
+  request. When the session ends, the leases its commands hold are released,
+  their queued waits and queued gates are cancelled, and their next request is
+  refused (`turn_ended`). A request for a phase that is not running is refused
+  too (`holder_not_running`). A command backgrounded with `&` used to keep its
+  place in the queue for as long as it lived: one run had nine such waiters,
+  up to 55 minutes old.
+- **`vinta-ai-maestro`: `pause` finishes while an agent waits on a lease or a
+  gate.** A pause (or stop) now answers every queued `with` and `gate` with
+  `run_pausing` (`run_stopping`) and refuses new ones. The CLIs tell the agent
+  to end its turn, which is the step boundary the pause waits for. Commands
+  and gates already running finish as before. The halt log names each node
+  the drain is still waiting on and what it is doing, and
+  `vinta-ai-maestro pause` prints the same list.
+
+- **`vinta-ai-maestro`: a turn the agent never took part in is no longer read
+  as work.** A session that ended with no text and no tool call — observed when
+  a resumed claude-code session closed a replay of killed background tasks
+  before reading the prompt — counted as a failed review with no reviewer
+  behind it, or, on a crew member's first turn of a new phase, swallowed the
+  new phase's brief so every later turn carried on with the old phase. Such a
+  turn is now retried once, cold, with the whole brief (`node_session`
+  `reason: empty_turn`), and a cold one that is empty too fails the turn.
+
+- **Maestro: an amended gate re-runs instead of returning its old result.**
+  The gate cache matched only the gate's command, so changing a gate's
+  `timeout_s` (the monitor's `retime_gate`) or its `requires` partway through
+  a run reused the result from the old settings on an unchanged tree. The
+  cache now matches every setting that affects the run. Edits to
+  `description` or `tuning` still reuse the result, and so does a
+  `scoped_cmd` edit for runs that use the full `cmd`. Existing
+  `gate-cache.db` entries are dropped once, at the first start after
+  upgrading.
 - **Maestro: PRs say how the plan lands.** Every phase and integration PR is
   marked as a review unit that lands through the plan PR, and the plan PR says
   to merge it alone; it used to offer two landing paths, and a 36-PR landing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vinta-ai-workflows",
-  "version": "0.7.0-alpha31",
+  "version": "0.7.0-alpha33",
   "description": "Bootstrap AI tooling (AGENTS.md, skills, sub-agents) across Claude Code, Codex, Cursor, and VS Code + GitHub Copilot.",
   "type": "module",
   "bin": {

package/schemas/postmortem.v1.schema.json

@@ -593,9 +593,10 @@
                 "type": "string",
                 "enum": [
                   "peer_busy",
-                  "warm_session"
+                  "warm_session",
+                  "spare_crew"
                 ],
-                "description": "`peer_busy`: the planned member was working. `warm_session`: promoted to reuse an open session."
+                "description": "`peer_busy`: the planned member was working. `warm_session`: promoted to reuse an open session. `spare_crew`: the planned member was working, and a spare was taken on in their image."
               },
               "attempts": {
                 "type": "integer",
@@ -679,7 +680,8 @@
                       "add_context",
                       "redirect",
                       "pause",
-                      "abort"
+                      "abort",
+                      "fresh"
                     ]
                   },
                   "by": {
@@ -703,7 +705,7 @@
                 ],
                 "additionalProperties": false
               },
-              "description": "Steering, pauses and aborts, per phase."
+              "description": "Steering, pauses, aborts and dropped sessions, per phase."
             },
             "questions": {
               "type": "object",

package/schemas/vinta-ai-workflows-config.v1.schema.json

@@ -339,7 +339,7 @@
       "additionalProperties": false,
       "properties": {
         "defaults": {
-          "description": "Run defaults a plan's `defaults` overrides field by field: `harness`, `model`, `pipeline`, `chores`, `gates` (the gate ids every phase runs unless it names its own), `gate_scope` (`scoped` | `full`), `wave_gates` (`off` | `final` | `every`), `substitution` (`same_tier` | `up_one_tier` | `any`), `allow_ungated_phases`, `model_fallbacks`, `max_session_turns`.",
+          "description": "Run defaults a plan's `defaults` overrides field by field: `harness`, `model`, `pipeline`, `chores`, `gates` (the gate ids every phase runs unless it names its own), `gate_scope` (`scoped` | `full`), `wave_gates` (`off` | `final` | `every`), `substitution` (`same_tier` | `up_one_tier` | `any`), `allow_ungated_phases`, `model_fallbacks`, `max_session_turns`, `max_spare_crew`, `pull_requests` (`phase` | `plan`).",
           "type": "object",
           "properties": {
             "harness": {
@@ -412,6 +412,19 @@
             "max_session_turns": {
               "type": "integer",
               "minimum": 1
+            },
+            "pull_requests": {
+              "type": "string",
+              "enum": [
+                "phase",
+                "plan"
+              ],
+              "description": "Which pull requests a run opens. `phase` (the default): one per phase, one per integration branch, and the plan PR that lands them. `plan`: the plan PR alone, from the last wave branch; phases' `after_pr` chores are then skipped."
+            },
+            "max_spare_crew": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Crew members a run may take on beyond the plan's roster (default 2). When the member a phase was planned for is busy, the phase gets a new member at that member's tier and model, with its own worktree, instead of borrowing a member another pending phase is planned for or waiting. `0` keeps the roster to the plan's."
             }
           },
           "additionalProperties": false

package/schemas/workflow.v1.schema.json

@@ -360,6 +360,20 @@
           "description": "The project’s own lane-setup command, run inside each freshly provisioned lane with that lane’s environment applied. The escape hatch for whatever a project needs that no field here describes. It MUST be idempotent: it runs again every time the lane is recycled for another phase.",
           "type": "string",
           "minLength": 1
+        },
+        "reset_cmd": {
+          "description": "Run inside a lane when it is recycled for another phase, and only then — never on a freshly provisioned lane. Runs with the lane’s environment applied, after maestro has reset the worktree, the env files, the databases and the services, and before `setup_cmd`. For what a phase leaves behind that the clean does not reach: a cache outside the worktree, a `recycle_keep` directory that needs pruning rather than deleting.",
+          "type": "string",
+          "minLength": 1
+        },
+        "recycle_keep": {
+          "default": [],
+          "description": "Ignored paths a recycled lane keeps. A recycle removes every untracked and ignored file the previous phase left — caches such as `.mypy_cache` and `__pycache__` included, which once kept a deleted package importable and failed a type check on clean code — except the copied dependency tree, the `env_files` and what is listed here. Each entry is a gitignore pattern handed to `git clean -e`: `.venv` keeps one at any depth, `/apps/api/.venv` only that one. For what is expensive to rebuild; anything not listed is rebuilt by `setup_cmd`, which runs on every recycle.",
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
         }
       },
       "required": [
@@ -423,6 +437,22 @@
             "any"
           ]
         },
+        "pull_requests": {
+          "default": "phase",
+          "description": "Which pull requests a run opens. `phase` — the default — one per phase, one per integration branch, and the plan PR that lands them all: the phase PRs are review units stacked in merge order. `plan` opens the plan PR alone, from the last wave branch, which already holds every phase and every conflict resolution; review happens there. One observed ten-phase refactor opened fifteen PRs that nobody was going to merge. Under `plan` a phase has no PR of its own, so its `after_pr` chores are skipped.",
+          "type": "string",
+          "enum": [
+            "phase",
+            "plan"
+          ]
+        },
+        "max_spare_crew": {
+          "default": 2,
+          "description": "Crew members a run may take on beyond the roster. When the member a phase was planned for is busy, the phase does not borrow a member another pending phase is planned for, and does not wait: it gets a new member at the planned member’s tier and model, with a worktree of its own provisioned there and then. A member nobody plans for is borrowed as before. The spare stays on the roster for the rest of the run, is never planned for, and covers later phases at its tier. `retry with <member>` takes a spare in that member’s image the same way when the member is needed elsewhere. A worktree, its databases and its compose stack each, so this is bounded; `0` keeps the roster to the plan’s and restores waiting and covering. One observed run left a phase on the critical path idle for 17 minutes while a retry held the member it was planned for.",
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
         "wave_gates": {
           "default": "final",
           "description": "When the phases’ gates run in full on a merged wave, in the integration worktree. Each phase passes its gates on its own branch, and two parallel phases can each be green and disagree with each other — a sender and a receiver of one signal, say — which only a merged tree shows. `final` — the default — runs every gate of the plan once on the last wave before the plan PR opens, and the wave’s phases’ gates on any wave whose merge needed a conflict resolution. `every` runs the wave’s phases’ gates on every wave as well, which costs one full suite per wave and catches a disagreement at the wave that introduced it. `off` runs none of these. Under `gate_scope: scoped` the full form of a narrowed gate still runs on each wave whatever this says: that is where the suite the phases skipped is paid back.",