vinta-ai-workflows 0.7.0-alpha32 → 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,62 @@ 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
@@ -552,6 +609,15 @@ 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
@@ -891,6 +957,126 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vinta-ai-workflows",
-  "version": "0.7.0-alpha32",
+  "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

@@ -680,7 +680,8 @@
                       "add_context",
                       "redirect",
                       "pause",
-                      "abort"
+                      "abort",
+                      "fresh"
                     ]
                   },
                   "by": {
@@ -704,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/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": [