vinta-ai-workflows 0.7.0-alpha10 → 0.7.0-alpha12

package/CHANGELOG.md

@@ -7,6 +7,8 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [0.7.0] — YYYY-MM-DD
 
+<!-- pre-release: 0.7.0-alpha12 on 2026-09-15 -->
+<!-- pre-release: 0.7.0-alpha11 on 2026-09-15 -->
 <!-- pre-release: 0.7.0-alpha10 on 2026-09-15 -->
 <!-- pre-release: 0.7.0-alpha9 on 2026-09-14 -->
 <!-- pre-release: 0.7.0-alpha8 on 2026-09-14 -->
@@ -318,8 +320,104 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   `plan/{plan-id}/lane-{phase-id}` branches, merged `--no-ff` into the single plan
   branch at each wave boundary, so the unit commits survive.
 
+- **`project.prepare_cmd`, for the shared servers a run depends on.** A project
+  whose databases are `delivery: external` and whose services point at one Redis
+  has no long-lived containers of its own — the shape these fields recommend —
+  and that makes some *other* stack a hard dependency of every run. Nothing in
+  the package could bring it up. `setup_cmd` looks like the place and is not: it
+  runs per lane, long after the template database was created on a server that
+  had to be up for `createdb` to work at all.
+
+  It runs in the repository root **before anything else a run does** — before
+  the preflight, before the templates, before the first worktree — and again
+  before every lane recycle, so a server that dies mid-run is restored at the
+  next hand-off rather than failing every phase after it. Failure aborts with
+  the exit code and a bounded stderr tail, and says what the failure means
+  rather than only that a command exited. It must be idempotent, and `--wait`
+  is only as good as the `healthcheck` a service declares: without one, compose
+  returns as soon as the container starts and `createdb` races the server.
+
 ### Fixed
 
+- **`doctor` checks that the shared servers answer.** It verified that binaries
+  existed and disk fitted, and never looked at a `server_url` — so a project
+  whose Postgres lives in another checkout's compose stack passed the preflight
+  with that stack down and died on the first `createdb`, before a worktree
+  existed. Each external database's server and each service URL is now probed
+  with a TCP connect, and a failure names the address that did not answer. A
+  compose-delivered database is deliberately not probed: the lane starts it.
+
+  The order matters as much as the check. `prepare_cmd` runs *before* the
+  preflight, so the check reports the world that hook just made rather than the
+  one in front of it.
+
+- **A service's `create_cmd` runs with the lane's environment.** `reset_cmd`
+  always had it and `create_cmd` did not, so a `create_cmd` that reached for
+  `docker compose` ran against the lane's own compose file with no project name
+  and no override — booting a stack on the project's fixed host ports, which is
+  the collision the override exists to prevent, caused by the step that sets a
+  lane up.
+
+- **`vinta-ai-maestro with` waits for the lock instead of giving up on it.** Its
+  usage said it blocked until the resource was granted, and it did — for about
+  five minutes, which is where Node's own `fetch` stops waiting for a response.
+  A test suite behind a capacity-1 semaphore beats that regularly. What the
+  agent saw was "could not reach the lease daemon", and what agents did with
+  that, repeatedly, was run the command without a lease: exactly the stampede
+  the pool exists to prevent, arrived at by an agent behaving reasonably.
+
+  The wait is the client's now. The daemon answers `202 still queued` within
+  seconds and **leaves its own queue behind it**, so nothing is granted to a
+  request that has gone away; the client loops until it is granted, saying so
+  once and then occasionally, so a transcript shows a wait rather than a
+  silence. Only answers that waiting cannot change — a resource this run does
+  not declare, a run that is no longer live — end it.
+
+  And when it does end that way, the refusal says what not to do about it.
+  "The resource lease was not granted" is an error with no alternative in it;
+  the rule against working around it now travels with the message rather than
+  sitting only in a prompt the agent read twenty minutes earlier. The prompt
+  says it too, including that waiting is the expected outcome and not a failure.
+
+- **A retry gets a fresh fix budget.** `fix_rounds` was set to 0 when a node was
+  created and never again, so a phase that spent its whole budget on attempt 1
+  began attempt 2 already exhausted — one review, one fix, and the exhaustion
+  transition fired straight back. Seen with `max_fix_rounds: 4`: the retry got a
+  single round before the operator was asked again, forty seconds of work
+  standing in for four rounds of it. A retry that inherits the reason the last
+  attempt ran out is not a retry. It resets wherever a node is re-driven from
+  its pipeline's initial state — a capacity refusal, an automatic retry, the
+  operator's answer, the `retry` verb — which is one place rather than four.
+
+- **The last fix is reviewed rather than failed unread.** `standard-phase`
+  checked the budget on the way *out* of `fix`, so the final fixer's work went
+  straight to `failed` with nothing looking at it. Two phases in one run ended
+  on a fixer reporting "all gates green, committed, tree clean" and were failed
+  anyway. The check now sits in front of the fixer, on both doors into it: every
+  fixer that runs is reviewed, and the review after the last one can still pass
+  the phase. Guarding only the review side left a red gate under a passing
+  reviewer looping forever, which is the other half of the same change.
+
+  `max_fix_rounds` still means the number of fixers a phase may spend. `0` now
+  means none, where before it let one run and failed the phase regardless.
+
+- **Agents are told not to background their work.** An implementer started five
+  commands with `run_in_background: true` and closed its turn with "I'll wait for
+  the test result notification before continuing to the outer gate". There is no
+  notification: a headless session ends when the turn ends and whatever it
+  backgrounded is killed with it. Three sessions ended with no report and no
+  commit, and the reviewer failed each for uncommitted work — true, and not the
+  cause. Nothing had said so, and believing a tool that offers backgrounding will
+  still be there afterwards is not unreasonable.
+
+- **The reviewer runs the gates instead of taking their word for it.** The prompt
+  asked it to confirm the outer gate was green, which an agent can do by reading
+  the implementer's report — one reused reviewer session reached a verdict in
+  under four minutes without running the project's tests at all. It is now asked
+  to run them, to say what they returned, and to treat being unable to run them
+  as a finding. Re-review rounds are asked again, because a session that
+  remembers running them last round is remembering a different tree.
+
 - **A retried phase keeps the commits the attempt before it made.** A failed
   phase re-enters its pipeline at the initial state, which runs `git_branch`
   again — and `checkout -B` moves an existing branch unconditionally, so attempt

package/package.json

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

package/schemas/workflow.v1.schema.json

@@ -331,6 +331,11 @@
           "additionalProperties": false,
           "description": "How a lane’s compose stack is isolated past `COMPOSE_PROJECT_NAME`."
         },
+        "prepare_cmd": {
+          "description": "Run in the repository root **before anything else a run does** — before the preflight, before the template databases, before the first worktree. Its job is to make the shared servers this project’s lanes connect to reachable: `docker compose up -d --wait db redis` for a stack in the root checkout, `brew services start postgresql` for a host install, nothing at all for a project whose lanes boot their own. `setup_cmd` cannot do this — it runs per lane, long after the template database has been created on a server that had to be up already. MUST be idempotent: it runs again before every lane recycle, which is what restores a server that died mid-run. Note that `--wait` only waits for services that declare a `healthcheck`; without one it returns as soon as the container is started, and `createdb` races the server.",
+          "type": "string",
+          "minLength": 1
+        },
         "setup_cmd": {
           "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",