vinta-ai-workflows 0.6.1 → 0.7.0-alpha10

package/CHANGELOG.md

@@ -5,6 +5,720 @@ All notable changes to `vinta-ai-workflows` are documented in this file.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
 the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.0] — YYYY-MM-DD
+
+<!-- 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 -->
+<!-- pre-release: 0.7.0-alpha7 on 2026-09-14 -->
+<!-- pre-release: 0.7.0-alpha6 on 2026-09-13 -->
+<!-- pre-release: 0.7.0-alpha5 on 2026-09-13 -->
+<!-- pre-release: 0.7.0-alpha4 on 2026-09-13 -->
+<!-- pre-release: 0.7.0-alpha3 on 2026-09-12 -->
+<!-- pre-release: 0.7.0-alpha2 on 2026-09-12 -->
+<!-- pre-release: 0.7.0-alpha1 on 2026-09-11 -->
+
+### Added
+
+- **A project declares what makes a lane runnable.** `project.env_files` copies
+  ignored configuration into each worktree, `project.setup_cmd` runs an
+  idempotent setup hook on provisioning and recycle, and the fixed
+  `project.commands` vocabulary tells implementers, reviewers and fixers the
+  project's real lint, typecheck, test and migration entry points.
+
+- **Compose-backed lanes are isolated past `COMPOSE_PROJECT_NAME`.** The daemon
+  now generates an out-of-tree Compose override per lane, strips fixed host
+  ports, re-pins fixed and external volumes, and carries the complete lane
+  environment into agent and takeover processes as well as gates. Explicitly
+  published services receive probed per-lane ports recorded in the teardown
+  summary.
+
+- **Shared services get one namespace per lane.** `project.services` models a
+  fixed index or lane-derived name inside one Redis, RabbitMQ, object-storage,
+  or similar server, with project-owned create/reset commands and capacity
+  validation before provisioning creates templates or worktrees.
+
+- **Agents can take the semaphore a workflow declares.**
+  `vinta-ai-maestro with <resource> -- <cmd>` waits on the run's existing
+  `ResourcePools`, runs the heavy inner-loop command, and releases on exit.
+  Renewable leases expire when their client disappears, are visible in the
+  live journal, and are surfaced in implementer, reviewer and fixer prompts.
+
+- **A failed phase retries itself, and then asks.** `--on-failure` defaults to
+  `retry`: one cold re-attempt (`--retries <n>`, 0–5), and then the node parks
+  on a question — retry, retry with another member of the crew, or stop. The
+  failures this system produces are overwhelmingly environmental and are gone by
+  the second attempt; the ones that survive it are the ones worth a person.
+  `ask` skips the automatic attempt. `stop` is the old behaviour and remains the
+  right choice for CI, because everything else eventually **waits**.
+
+  A failure that survives its retries says so: the reason carries
+  `(after N attempts)`, which no event otherwise records.
+
+- **A failed phase can be retried by hand.** A **Retry phase** button, and
+  `POST /api/runs/:runId/nodes/:nodeId/retry`. It returns the node to the ready
+  set and unblocks the subtree its failure blocked — a phase that died of
+  something environmental holds up work that was never broken. It needs the run
+  to still be in flight, which with the new default it usually is; a run that
+  has genuinely ended is re-run, not retried, and says so rather than doing
+  nothing.
+
+- **The monitor can go and look.** It was given a digest and nothing else, and
+  read exactly as thin as that sounds — it could say a phase had failed and
+  never say what the phase had written. It is briefed as a technical project
+  manager now, with the map: the plan document, each phase's brief, each lane's
+  worktree path, each branch and its base, and where the journal and transcripts
+  live. It has a shell and its working directory is the repository, so it can
+  read the diff before drawing a conclusion. The digest stays as the index —
+  bounded, cheap, enough to know which phase is worth a closer look.
+
+- **The monitor conversation is kept.** It lived in component state, so a reload
+  threw away every question and every answer — a worse record than the run it
+  describes. It is written to the transcript store under a reserved node id and
+  read back on load, so it outlives the tab, the daemon and the run.
+
+- **Panels expand.** Anything holding content that is only nominally
+  summarisable — an agent's transcript, a gate log, the monitor conversation,
+  the steering box — takes the full container width and about a screen of
+  height on demand. The height travels as a CSS variable, because the element
+  that has to grow is a scroller several components below the panel.
+
+- **A run has a spokesperson you can ask.** `serve` grows a **Monitor** panel on
+  the run view: one agent that reads the journal and answers in prose — what is
+  blocked, why a phase failed, what it would take to move on. It runs on the
+  dearest tier on the crew, because it is read by a person deciding what to do
+  about a failing run, and it is asked a handful of times rather than hundreds.
+
+  Three things it deliberately is not.
+
+  **It is not in the permission path.** The obvious thought, once an agent has
+  been refused something, is to put a smarter agent in front of the refusals —
+  but a phase makes hundreds of tool calls (one node in one real run made 179)
+  and a model turn before each is latency and cost spent on questions like "may
+  I run ruff", which should never have been questions. Permissions are settled
+  structurally, once per spawn, for free.
+
+  **It does not read the transcripts.** Piping every agent's output into a
+  second agent would make the monitor the most expensive thing in the run and
+  tie its cost to the work rather than to the questions. It reads a bounded
+  digest — statuses, failure reasons, pending questions, the last few refusals
+  with their sentences, one trimmed last word per phase — so a one-hour run and
+  a one-day run cost about the same to ask about.
+
+  **It has no authority.** It can explain a §9.1 pause; it cannot answer one.
+  An agent that could quietly approve its colleagues' work would turn a
+  checkpoint into a formality, and the checkpoint is the point.
+
+  It answers about **finished runs too**, which is when "why did this fail" is
+  usually asked, and it needs no lane: it writes nothing.
+
+- **`serve` reads `--permission`.** The flag has been accepted and ignored since
+  it existed. It decides how the monitor is spawned, so it is read now.
+
+- **A plan staffs a team, instead of picking a model per phase.** Choosing a tier
+  phase by phase answers "what runs this one" ten times and never adds it up, so the
+  two questions that decide what a feature costs go unasked: how many agents does
+  this need at once, and is any of them too junior for what it was handed.
+  - `plan-feature` opens **Phased Rollout** with a **Crew** table — one row per
+    agent, carrying its tier and the phases it takes — and every phase carries an
+    **`**Assigned to**:`** line naming one of them. It replaces
+    `**Suggested AI model**:`; a plan that still has the old line keeps working, and
+    the executor reads the tier straight off it.
+  - The **Execution graph** table gains an **Agent** column and an **Idle** note.
+    Reading across a row says who is working that wave; reading down a column says
+    who is not. A wave that will serialize because the roster cannot staff it is now
+    stated in the plan rather than discovered as a slow run.
+  - **Every member has to earn their place**, by concurrency (a wave genuinely needs
+    that many hands *at or above* those phases' tiers) or by cheapness (they take
+    work a dearer member would otherwise do). The roster is therefore **not** capped
+    at the widest wave — a junior who runs the migration and the flag deletion is
+    worth having in a graph that never runs two phases at once — but the lane pool
+    still is, because lanes are bought with concurrency and crew are not.
+  - **Reviewers are a role on the crew, and implementers and reviewers are
+    disjoint.** A member has `role: implementer` or `role: reviewer`; a phase cannot
+    be assigned to a reviewer and a reviewer never writes code, so an agent reading
+    its own diff is not something a plan can express. A phase is read by the
+    cheapest reviewer at or above its tier. A roster with no reviewer still runs and
+    falls back to `agent_models.reviewer`, cold, one session per phase.
+    - **A reviewer reads the lane it is reviewing**, with the phase's changes still
+      uncommitted in it, and has no worktree of its own. That is what puts review
+      before the commit: a finding is fixed in the working tree rather than
+      recorded as a mistake on the branch plus a correction after it. The cost is
+      that a reviewer's directory follows the work, so its session carries only
+      between reviews that land in the same lane.
+  - **A crew member is an agent that lives for the whole run.** Each one keeps its
+    own worktree and its own session across every phase it takes, so the agent that
+    takes Phase 4 still knows what it learned about the codebase in Phase 1 —
+    which is most of what a cold agent's first turn of a phase is spent
+    rediscovering.
+    - This works because the *directory* stops moving. Lanes used to be anonymous
+      slots handed out by a free list, so a member landed somewhere different each
+      phase and its context described paths it was not standing in. Pinning each
+      member to one worktree leaves a far smaller question — which files changed —
+      and `git diff --name-only` answers it exactly.
+    - A cross-phase continuation therefore gets the new phase's **full brief** (it
+      is new work, not a delta) behind a re-orientation: same agent, same directory,
+      everything you learned still holds; the tree is on a different branch; these
+      files differ; and — the sentence that matters most — whether the previous
+      phase's own work is in this tree at all.
+    - A delta that cannot be computed is reported as **unknown**, never as empty.
+      "Nothing changed" is the one wording that would stop an agent re-reading.
+    - Two things still start cold: a member whose previous phase **failed**, because
+      its session is the context that failed with it, and the final fix round.
+    - The cost, stated plainly: **one worktree and one set of forked databases per
+      implementer**, so `resources.lane.capacity` is now the implementer count
+      rather than the widest wave, and adding a cheaper implementer is a trade of
+      disk against money rather than free.
+  - The workflow document gained a top-level **`crew`** block and **`nodes[].crew`**.
+    A staffed node carries no `model` — the member has one — and a document that is
+    half-staffed, names a member nobody declared, assigns a phase to a reviewer,
+    declares an implementer nobody is assigned to, or staffs a reviewer below every
+    phase on the plan is refused before the run starts.
+  - `vinta-ai-maestro` claims an agent **before** the lane, prefers the member the plan
+    named, covers with the **cheapest** qualified free peer when they are busy, and
+    **waits rather than handing a phase below its tier** — even with a lane free. A
+    lane is disk; a phase run by too junior an agent does not fail cleanly, it fails
+    review two rounds later with nothing pointing back at the staffing. A reviewer is
+    claimed per review turn rather than per phase — it has one session ledger and
+    two concurrent reviews would collide over it — so one reviewer on a three-lane
+    plan is a queue at the review step and not a serialised run.
+  - The run view reports who actually worked against who the plan said would.
+    `substituted` is the figure to read beside a cost that overran: every
+    substitution ran at or above the budgeted tier, so a run can be entirely green
+    and still have been staffed dearer than planned.
+
+- **`implement-plan` runs independent phases in parallel.** The plan now carries a
+  dependency graph and the conductor schedules against it: a phase starts as soon as
+  every phase it depends on is green and a worktree lane is free, instead of waiting
+  for its turn in plan order. A chain-shaped plan behaves exactly as before —
+  sequential execution is the one-lane case of the same scheduler.
+  - `plan-feature` gives every phase a **`**Depends on**:`** line naming the artifact
+    it needs from each upstream phase, and opens **Phased Rollout** with an
+    **Execution graph** table derived from those lines. It also checks same-wave
+    phases against the **Touch List** for file overlap and tells you to add an edge
+    when two phases would fight over the same file.
+  - New shared partial `plan-execution/partials/parallel-lanes.md` carries the graph
+    parse, the worktree lane pool, the dependency-derived branch topology, the
+    dispatch loop, the tracking-directory schema, and the sibling-lane write guard.
+  - `prepare-worktree` documents provisioning a **pool** of lanes for one plan and
+    records a `reset_cmd` per forked DB so a lane can be reused across phases without
+    carrying the previous phase's migrations into the next one's test run.
+  - Two new config fields: `run_options.implement-plan.parallel_phases` (default
+    `true`) and `run_options.implement-plan.max_parallel_lanes` (default `3`), asked
+    at bootstrap alongside the existing `prepare-worktree` follow-ups.
+
+- **`plan-feature` emits an executable `ai-plans/<feature-kebab>.workflow.json`
+  beside every plan.** The markdown stays the document humans review; the JSON is
+  the same phase graph in the form an orchestrator runs — one node per phase, one
+  `depends_on` entry per `**Depends on**:` clause carrying both the upstream phase
+  and the artifact it provides, plus the phase's Touch List, gates, capacity pools
+  and model tier. Validated by
+  [`schemas/workflow.v1.schema.json`](schemas/workflow.v1.schema.json), which the
+  emitted file references from its `$schema` key so editors validate it as it is
+  written. **Unconditional** — no config field, no bootstrap question, no opt-in:
+  a project with no orchestrator carries a file nothing reads, and a project that
+  adopts one later finds its plans already executable.
+
+- **Review findings go back to the phase's own implementer, not to a fresh fixer.**
+  The agent that wrote the code still holds the phase brief, the plan's bounds, the
+  dependency context and its own reasoning; a fresh fixer held a quoted finding and
+  had to rediscover the rest — slower, dearer, and likelier to "fix" a symptom by
+  undoing something the phase chose deliberately. The fix message is now a delta —
+  the findings, nothing else — because re-sending the brief invites a
+  re-implementation rather than a fix.
+
+  Three rules keep that from costing what it buys. **The reviewer is never the
+  implementer**: continuing the reviewer across rounds is fine, but the review must
+  come from an agent that did not write the code. **The last round before giving up
+  goes to a fresh fixer, always** — reuse means the agent that wrote the bug is
+  fixing it, which is usually the point and occasionally exactly wrong, because that
+  assumption *was* the bug. And where a runtime cannot continue a finished
+  sub-agent, the old cold hand-off still happens and is recorded as one, so a slow
+  phase can be read later without guessing.
+
+  One consequence worth knowing: a continued implementer fixes at its own crew
+  member's tier, so `agent_models.fixer` now governs only the cold cases. A project
+  that set `fixer` cheap to save money is saving it on fewer rounds.
+
+- **The workflow schema gained `defaults.max_session_turns`.** Optional, default
+  12. An orchestrator that reuses one agent session across a phase's implement
+  and fix turns needs a ceiling on how long that session may grow before the next
+  turn starts cold; without one a long phase eventually dies on a context-window
+  error that reads as a broken harness. `plan-feature` omits the field — it is a
+  safety limit, not something a plan tunes — and its field table says so.
+
+- **`plan-feature` asks about the project's databases and emits the workflow's
+  `project` block.** The block records what a phase lane must **fork** to be a
+  working checkout — the `dev` and `test` databases, and the project's own
+  migrate command, which runs once per template database rather than once per
+  lane. Without it every lane got a git worktree and nothing else, so two phases
+  running concurrently pointed their test gate at the same rows. Asked at
+  emission time with one `AskUserQuestion` call ("what does a phase lane need its
+  own copy of", "how is that database delivered"); the rest — the migrate
+  command, the database names, the env var names — is read out of the project's
+  settings and task runner rather than asked.
+
+  Two rules the skill is explicit about, because both are easy to get wrong:
+  **sharing is the absence of a declaration** (there is no `share` value, and a
+  lane that reads the main checkout's database has nothing to describe), and
+  **each role names its own database** (a lane's fork is named from `name` and
+  the lane, not the role, so `dev` and `test` sharing one `name` collapse to one
+  forked database). Everything `prepare-worktree` discovers per worktree —
+  `reset_cmd`, compose project names, volume forks, seed commands, env-file
+  strategy — stays out of the block by design.
+
+- **New schema
+  [`postmortem.v1.schema.json`](schemas/postmortem.v1.schema.json)** — the
+  structured plan post-mortem an orchestrator writes at
+  `.vinta-ai-maestro/runs/<run-id>/postmortem.json` once a run has ended: dependencies
+  that were declared but never used, dependencies discovered at gate time,
+  same-wave phases that actually conflicted, and phases whose real duration
+  diverged from their wave placement. `plan-feature` reads it before drawing the
+  next feature's Execution graph, which is what stops a plan from repeating a
+  defect the last run already paid for. Like
+  [`workflow.v1.schema.json`](schemas/workflow.v1.schema.json) it is
+  **generated** from a zod source rather than hand-written — see
+  [`schemas/README.md`](schemas/README.md).
+
+### Changed
+
+- **Phase branches base on their dependencies, not on the previous phase.** A phase
+  with no dependencies cuts from the default branch; one with a single dependency
+  cuts from that phase's branch; one with several cuts from a
+  `plan/{plan-id}/integ-{phase-id}` branch that merges them. Each wave is then merged
+  into a `plan/{plan-id}/wave-{N}` integration branch, which is what a resume anchors
+  on and what the final report points at. The PR `base` follows the same value —
+  a stacked plan produces exactly the stack it did before.
+- **Tracking is a directory, not a file.** `{{PLAN_DIR}}/TRACKING_{plan-id}/` holds
+  `run.md` (conductor-owned), one `phase-{id}.md` per phase (written only by the lane
+  that ran it, committed on that phase's own branch), and `waves/wave-{N}.md`. No two
+  branches write the same path, so wave merges no longer conflict on tracking. A run
+  started under the old single-file layout is migrated on resume.
+- **An implementer is told about its dependencies only.** Prior-phase context passed
+  into a phase prompt is now that phase's transitive dependency closure rather than
+  "everything finished so far" — a sibling lane's work is not in the phase's base
+  branch, and describing it as done made the implementer code against files it could
+  not see.
+- **The stray-write guard covers sibling lanes.** The sandbox denies the whole
+  worktree pool root and allows back only the running lane; the review-phase backstop
+  checks the main checkout and every sibling workroot after each implementer and
+  fixer. A write into a lane that is mid-implementation is worse than a stray
+  main-checkout write.
+- **`amend-plan` cascades along the dependency graph.** A rewrite touches the
+  amended phase's dependent closure instead of "every phase with a higher number",
+  rebases in topological order, rebuilds `integ-` bases before rebasing a
+  multi-dependency phase onto them, and refuses to run while any phase is still in
+  flight. It gained a `dependency-change` amendment kind for edits to a
+  `**Depends on**:` line.
+- **`implement-plan` refuses rather than degrading** when parallel execution is asked
+  for but worktrees are unavailable — several agents cannot share one working tree,
+  and silently falling back to sequential would discard the schedule the user
+  approved.
+- **`modular-commits` supports parallel runs**: lanes commit their atomic units on
+  `plan/{plan-id}/lane-{phase-id}` branches, merged `--no-ff` into the single plan
+  branch at each wave boundary, so the unit commits survive.
+
+### Fixed
+
+- **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
+  2 began by resetting attempt 1's work to base. The files left the worktree,
+  the next reviewer correctly reported "phase not implemented at all", and the
+  fix budget burned re-implementing from nothing until the operator was asked. A
+  phase that produced real commits was guaranteed to lose them.
+
+  "Cold" was always meant to describe the agent's *session*, not its branch —
+  and the default policy targets environmental failures, which is exactly when
+  the previous attempt's code is worth keeping. A resumed branch is checked out,
+  never rebased onto a base that moved: a conflict there would fail the retry
+  during its setup, before the agent that might resolve it has run. A branch
+  that committed nothing is still moved up. Whether this is a second attempt is
+  read from the journal rather than from the ref, because a phase branch's name
+  carries the plan id and not the run id — an identically named branch left by
+  an earlier run must still be cut fresh. `node_assigned` now records
+  `previous_head`, so a reset that does happen is visible in the run rather than
+  only in a reflog.
+
+- **A phase is judged on commits, and the prompts finally say so.** An
+  implementer ran four sessions, reported `SUCCESS` with a green inner loop, and
+  never ran `git commit`: its deliverables were untracked files. The reviewer
+  reads the committed diff, so it saw an empty one and reported "not implemented
+  at all"; the fixer re-implemented, also without committing; the rounds ran out
+  and the lane was recycled over the files. Every instruction that agent had was
+  *about* committing — "never commit while a gate is red" — and none of them
+  said it had to.
+
+  Implementers and fixers, cold and continued, are now told that the phase is
+  reviewed and merged from commits on its branch, that an uncommitted file does
+  not exist as far as the run is concerned, and that the turn is not over until
+  `git status --porcelain` is empty of their work — staged by explicit path,
+  never `git add -A`, because a lane holds local files that are not theirs to
+  commit. The reviewer reads the working tree as well as the diff: a full tree
+  with an empty diff is a real failure and is *not* "not implemented", and the
+  difference decides whether the fixer writes the code again or simply commits
+  it.
+
+- **A recycled lane no longer deletes work nobody committed.** Both recycle
+  paths throw the working tree away. The tree is now committed first — with
+  plumbing, and **off the branch**, under `refs/vinta-ai-maestro/wip/`. On the
+  branch was the first implementation, and it was wrong: a lane's dirty tree
+  holds gate artifacts as often as deliverables, and a phase branch is the base
+  of its dependents, so one gate's scratch file reached the next phase and
+  failed a gate for a reason nothing in that phase caused. Nothing merges,
+  nothing reaches a dependent, and one `git restore --source <ref>` gets a file
+  back. Where the rescue itself fails, the recycle refuses and names the paths.
+
+  The retry question says how much is at stake: commits are kept, and *N*
+  uncommitted files in the lane will be set aside.
+
+- **`project.hooks: skip`.** Committing is not optional any more, and a
+  `language: system` pre-commit chain reads a never-committed-in worktree as a
+  fresh machine — one project's hooks built a 510 MB virtualenv before allowing
+  a first commit, per lane, after four attempts and a two-minute timeout. Set
+  per worktree, so the operator's own checkout keeps its hooks, and opt-in,
+  because hooks are usually there for a reason.
+
+- **`doctor` knows when a project needs docker compose.** It assembled its
+  options without a `project`, so `needsCompose` was handed `undefined` on every
+  invocation and reported "not required by this project" for a
+  compose-delivered database — and `run`'s own preflight did the same. A check
+  nothing can reach is worse than an absent one: it reads as a pass.
+
+- **A failing `setup_cmd` says why.** It carried a lane name and nothing else,
+  so the operator saw "could not provision the lane pool under …" and had to
+  replay the command by hand with the lane environment rebuilt to find a missing
+  settings module. It carries the exit code and a bounded stderr tail now — the
+  same class of thing as a harness refusal's own explanation, which this package
+  already decided to carry after an afternoon lost to the same silence.
+
+- **A lane the executor was not given is refused, not guessed.** It fell back to
+  the right directory with an *empty environment* — a gate running against the
+  wrong compose project and no forked connection string, with nothing anywhere
+  saying a lane was missing.
+
+- **The monitor reads, and does not run.** Its shell has no lane environment, so
+  the project's own commands run from it contend with the lanes instead of
+  observing them. One reported "the final gate fails on a port conflict" when no
+  gate had run at all, and the operator believed it. Gate results come from the
+  journal and the gate logs.
+
+- **`serve --host 0.0.0.0` prints a URL another machine can open.** Binding
+  every interface made the server report the wildcard back, so the line printed
+  for the operator to open — and share — was `http://0.0.0.0:<port>`, which
+  resolves for nobody. The bind is unchanged; the printed host is now this
+  machine's LAN address. The daemon still warns, because the token in that URL
+  is the only thing between the run and anyone who can reach the port.
+
+- **An agent can run a shell command.** `auto` mapped to the vendor's
+  `acceptEdits`, which accepts file *edits* and nothing else — a shell command
+  still goes to a permission prompt, and in `-p` there is nobody to answer one.
+  A run of eight phases died of it: the agents wrote their code and were then
+  refused `ruff`, `pytest`, `git add` and `docker compose`, **69 denials across
+  two lanes**, every gate failing on work that was never allowed to be checked.
+  `auto` now allows `Bash` in the policy file it already writes.
+
+  What that costs is worth stating plainly: **`Bash` was never confined to the
+  lane.** The deny list covers the file-editing tools and a shell redirection
+  walks through it, so allowing the shell allows commands on the machine.
+  `auto` has always promised exactly this in words — "the agent works unattended
+  inside its lane" — and this is the first version where the words are true.
+  `ask` still does not allow it: that mode exists for a human at the browser,
+  and the prompt is its purpose.
+
+- **A refusal says why, in the words the harness used.** `permission_denied`
+  carried a decision token and deliberately dropped the sentence beside it, on
+  §11 grounds. Then a run failed with forty-five denials reading
+  `reason: "other"`, and finding out what that meant cost an afternoon and a
+  rebuilt reproduction — the sentence said "this Bash command contains multiple
+  operations; the following parts require approval". §11 keeps repository
+  *contents* out of the record; a refusal's own explanation is not contents, and
+  the `tool_use` row above it already carries the path and the command verbatim.
+  Withholding it protected nothing and hid the one fact worth having.
+
+- **`serve` opens a run that has already finished.** The API resolved a run from
+  the in-memory registry *and* the journal and required both, so a daemon
+  started with nothing running listed the operator's history — the list reads
+  the journal — and then answered 404 for every run in it, under a message
+  saying the daemon was not running. Reads now need only the journal, which is
+  where a run's whole record lives and which outlives the daemon by design
+  (§5.3). Steering a finished run is still refused, with `409` rather than
+  `404`: the run exists, and saying it does not sends the operator hunting for a
+  typo instead of reading the status in front of them.
+
+- **Four places the UI asked the operator to work around it.** The transcript
+  opened at the *oldest* row it held, so a live agent's newest line — the one
+  the panel was opened to read — sat below the fold and every arriving entry
+  pushed it further down; it now opens at the newest and stays there, but only
+  while the operator is already at the bottom, because scrolling up is reading.
+  The `git diff` command overflowed its panel, uncopyable without selecting
+  blind, and now wraps. The shell's bounded column went from 1280px to 1600px:
+  1280 is a reading measure, and the Nodes table's columns are ids, lane names
+  and branch names, none of which can be abbreviated without losing what
+  identifies them. And the notification interval said "Remind every 5 min"
+  without ever saying what it would remind anyone about — it repeats the
+  notification for a phase that stopped to ask the operator something, until
+  they answer, which is what the options say now.
+
+- **A killed terminal releases its directory on Windows.** Two PTY tests failed
+  teardown with `EBUSY: rmdir`: killing a process there is not synchronous with
+  releasing what it held, so the conpty and its background child are gone as far
+  as the test is concerned while the OS still has the working directory open.
+
+- **A failed phase can be retried instead of ending the run.** `run` takes
+  `--on-failure <stop|ask>`. `stop` is the default and is what every run has
+  always done — the phase fails, its dependents block, the run finishes. `ask`
+  parks the node on a question instead: retry, retry with another member of the
+  crew, or stop.
+
+  It exists because the failures worth retrying are overwhelmingly
+  environmental — a permission wall, a grant nobody made, a gate whose service
+  was not up — and the only recovery was to start the whole plan again, running
+  every phase that had already succeeded a second time. Only pass `ask` when
+  somebody is watching: the run waits, which is exactly why it is not the
+  default.
+
+  The alternatives offered are **members of the crew, not models**. A staffed
+  run has no free-floating models in it — a phase is taken by a member, and the
+  tier floor that decides who may take it is the assigned member's own — so a
+  model is something the plan cannot express and nobody could be found to hold.
+  A member below the phase's tier is never offered: an operator answering a
+  question is not a reason to hand a phase to somebody the plan judged too
+  junior for it.
+
+  The retry starts **cold**, and everything the node held goes back before it
+  waits (§6.1) — an operator at lunch must not be holding a lane another phase
+  could use.
+
+- **A refusal nobody was asked about is now said out loud.** The adapter knew
+  about `permission_request`, a question waiting for an answer, and nothing
+  else. The refusal an operator actually hits is not a question: a read outside
+  the working directory is decided by the CLI and announced as
+  `permission_denied`, with no request to reply to. That frame was dropped at
+  the first `switch` — no event, no journal row, no transcript line. The new
+  `permission_denied` event carries the decision token (`workingDir`, `mode`)
+  and never the vendor's prose, which names the file being read (§11).
+
+- **A turn that ended blocked is no longer a turn that succeeded.** The CLI
+  says `status_category: "blocked"` one frame before reporting
+  `is_error: false`, and both are true from its side: it was asked for
+  something it could not do and said so. Taking the second at its word is how a
+  phase passed having written no code and then failed two steps later under
+  another name. A session that reported an error no longer ends `ok` — which
+  also makes a reviewer fail closed, since its verdict is read back out of a
+  transcript whose session did not end cleanly.
+
+- **An agent still could not write in its own lane.** The entry below passed
+  claude-code `--permission-mode auto`, which matched our own vocabulary for
+  "works unattended" and is not what the vendor means by the word: `auto` still
+  routes a write to a permission prompt, and in `-p` there is nobody to answer
+  one. Run against the CLI, a `Write` to the agent's *own working directory*
+  comes back denied with no reason attached — the same dead end, wearing the
+  word that made it look closed. `acceptEdits` is the mode under which that
+  write succeeds, and is what `auto` now maps to. The test covering this
+  asserted the word rather than the behaviour, so it pinned the bug in place.
+
+- **A phase can read the operator's checkout.** A lane is a worktree cut from a
+  branch, so anything uncommitted — a plan written this morning, a spec that
+  never leaves the operator's machine — is present where they are and absent
+  from every lane. Reaching for it was refused before the model saw a byte, with
+  a message that reads like a prompt awaiting an answer ("Claude requested
+  permissions to read from …, but you haven't granted it yet") when in fact
+  nothing is asking: the CLI denies it outright, emits no permission request,
+  and the session then ends *successfully*, having written nothing.
+
+  The repository root is now granted to every claude-code agent for **reading**.
+  Granting a directory also grants writing in it, and the lane sits inside the
+  directory being granted, so the grant is paired with a deny list that keeps
+  the lane the only writable place under it — the operator's source and every
+  sibling lane stay refused. That list names the *siblings* at each level down
+  to the lane rather than the root itself, because the vendor resolves deny
+  before allow with no carve-out: `deny: <repo>/**` plus `allow: <lane>/**`
+  refuses the lane too. Each of those facts was established by running the CLI.
+
+  **This covers the file-editing tools and not `Bash`.** A shell redirection was
+  never confined to the working directory and is not confined now; that boundary
+  is the OS's, and the vendor's sandbox that enforces it also switches off the
+  network a phase needs to install anything.
+
+  codex needed nothing: under `--approve-for-me` it already reads anywhere on
+  disk, which was confirmed the same way.
+
+- **An agent can write in its own lane.** Every adapter declared
+  `permissionControl: true` and passed no policy at all: claude-code was spawned
+  as `-p --output-format stream-json …` with no `--permission-mode`, and codex as
+  `exec --json` with no sandbox and no approval flag, under a comment saying it
+  took both on the command line. So a headless run asked before its first write,
+  emitted a `permission_request`, rendered it in the transcript — and nothing
+  anywhere answered. The phase failed reporting a permission system it could not
+  see, having written nothing.
+
+  `run` and `serve` now take `--permission <ask|auto|full>`, defaulting to
+  `auto`. **The operator sets it, never the workflow document**: the document is
+  committed and shared, and a file in a repository should not be able to tell
+  someone else's machine to run agents without approvals.
+
+  Both CLIs refuse combinations that looked reasonable, and both were found by
+  running them rather than reading them: codex rejects `--sandbox` alongside
+  `--approve-for-me`, and `codex exec resume` accepts neither — passing the
+  fresh-spawn policy there turned a `stale_session` refusal, which the scheduler
+  retries cold, into a `fatal` one that fails the node.
+
+  This reverses a documented decision. The README said the daemon passed no
+  permission flags and that a committed `.claude/settings.json` was what made a
+  run able to write; that is now the narrowing layer on top of a mode, not the
+  only thing standing between an agent and a blocked lane.
+- **`purge --lanes --branches` clears what a failed run leaves behind.** A run's
+  lane worktrees are not under `runs/`, so no purge ever reached them: three
+  failed attempts at one plan left twelve worktrees, twelve summaries, and a set
+  of `plan/<id>/phase-*` branches still checked out — which is what makes the
+  *next* run of that plan impossible, since git refuses to check out a branch a
+  second worktree holds.
+
+  One rule decides both: **never delete the only copy of work.** A phase can
+  leave work committed on its branch or uncommitted in its worktree, and both
+  count — so a branch carrying commits no other branch has is kept, a lane with
+  a dirty tree is kept, and each is listed with the command to remove it by
+  hand. Untracked files count as work: a phase that wrote three new modules and
+  never committed them is exactly the case worth protecting.
+
+  Emptiness is measured as "carries no commit another branch does not already
+  have", not as "merged into HEAD". The latter is relative to wherever the
+  operator is standing, so on a feature branch — the checkout this is most often
+  run from — every empty phase branch looked unmerged and nothing was ever
+  cleaned up.
+
+  `--dry-run` and `--yes` work as they already did, and a worktree that will not
+  go is named rather than counted.
+
+- **`doctor` now catches, before a lane exists, the failures that used to take a
+  run each.** Four consecutive runs of one plan failed four different ways, and
+  every one of them was knowable at minute zero from the workflow and the repo.
+  - **Every `prompt_ref` and `plan_context_ref` is resolved against
+    `base_branch`**, with `git cat-file -e`, which reads the branch's tree and
+    so cannot be satisfied by a working-tree copy — the working tree being
+    exactly what a lane will not have. It distinguishes the three cases, because
+    they have three different fixes: never committed, **staged but never
+    committed** (`git add` alone does not put a file in a branch), and committed
+    on a different branch. The last offers both routes out — merge it, or point
+    `base_branch` at the branch that has it — since only the operator knows
+    which they want.
+  - **Phase branches held by another worktree** are reported with the directory
+    to remove. Lane directories are named per run and phase branches per
+    workflow, so a failed run leaves worktrees holding the branch names the next
+    run will try to cut, and git refuses to check out a branch twice. Nothing
+    cleans those up: `purge` deletes run state under `.vinta-ai-maestro/runs/`,
+    and lane worktrees are not there. `doctor` does not delete them either — a
+    failed lane's worktree is the only place its state survives — but it now
+    names each one and the exact command.
+
+- **A failed node records why.** `node_status` carried `{"status":"failed"}` and
+  nothing else, so two runs failing for two unrelated reasons produced identical
+  journal rows and the cause survived only in the operator's terminal. The
+  reason is now persisted — **sanitized**, not raw: errors the package builds
+  itself are identifiers by construction and are kept verbatim, and anything
+  else is reduced to its kind, the rule `recycleStage` already followed. The
+  journal is durable and API-served, and an exception message from a dependency
+  is exactly how repository content gets into one. Blocked dependents record
+  which node blocked them.
+
+- **Two diagnostics that named the symptom and hid the cause.** Both came out of
+  one real run, and neither was a wrong answer — just an unusable one.
+  - **A phase whose plan is not committed** failed with `prompt_ref "…" names no
+    readable file`, against a path that was spelled correctly. A lane is a fresh
+    worktree of the base branch, so a plan sitting untracked in the operator's
+    checkout is in the one place the run cannot look. The message now names the
+    directory it resolved against and says why a plan is often not in it.
+  - **A lane summary the daemon could not accept** reported `summary unreadable`
+    and advised deleting the lane — which takes its forked databases with it,
+    over what turned out to be two wrong fields. `doctor` now names the fields
+    and what was expected, and offers repair before deletion. A file that does
+    not parse at all still reports as unreadable, because there is no field to
+    name. Neither message carries the offending *value*: a summary holds
+    database names and connection variables, and the value that failed
+    validation is the likeliest thing in it to be one.
+
+  `prepare-worktree` gained the rule that would have prevented the summary in
+  the first place — its `|` alternatives are closed sets read by machine, `null`
+  is how you say "none", and a strategy outside the set should be the closest
+  one plus a `note:` rather than a fourth word.
+
+- **`npx vinta-ai-maestro` now runs.** The published package pointed its `bin` at
+  `src/cli/bin.ts` and relied on Node stripping the types at startup — which Node
+  refuses to do anywhere under `node_modules`, unconditionally and with no flag to
+  override. So the CLI worked from a checkout and died on first run once installed,
+  with `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`.
+
+  `packages/vinta-ai-maestro` now builds: `tsc` emits `dist/` with
+  `rewriteRelativeImportExtensions` (the source imports `.ts` specifiers, which
+  emitted JS cannot keep), vite writes the daemon's UI into `dist/ui`, and the
+  shebang is rewritten from the source's `--experimental-transform-types` form to
+  a plain `#!/usr/bin/env node` — a compiled entry point has no types left to
+  transform, and should not ask Node for a flag it is free to retire. `prepack`
+  runs the build, so a tarball can never be cut from a stale `dist/`.
+
+  Three packaging faults surfaced with it, each of which broke an install on its
+  own:
+  - **The UI was never in the tarball.** `serve` resolves its static root as
+    `dist/ui` and refuses to read outside it, so it would have booted and answered
+    every page with "build the UI first". The build now asserts `dist/ui/index.html`
+    exists rather than trusting a vite config that writes outside its own root.
+  - **`tailwindcss` and `tw-animate-css` were imported but never declared.** They
+    resolved only through pnpm's `.bin` shim setting `NODE_PATH`; building by any
+    other path failed to resolve them. Both are now devDependencies.
+  - **Everything the UI imports was a runtime dependency.** React, xterm,
+    lucide-react and the three workspace packages are bundled into `dist/ui` by
+    vite and cannot be loaded at runtime — yet a consumer installed all of them,
+    and two carried `workspace:*` specifiers that no registry understands. Moved to
+    devDependencies; the published package now declares six runtime dependencies
+    instead of fourteen.
+
+  CI packs the tarball, installs it into a throwaway project and runs the binary
+  from `node_modules`. Every previous check ran from a checkout, which is the one
+  place this class of bug cannot appear.
+
+- **Lane provisioning serializes `git worktree add`, not only the database
+  template.** `prepare-worktree` previously named one serialization point; there
+  are two. Git rewrites `.git/worktrees/` metadata on every add, and concurrent
+  adds against one repository clobber each other's entries — a reproducible
+  corruption, not a theoretical race. Worktrees are added one at a time; the
+  expensive per-lane work (dependency linking, database cloning, summary
+  writing) still overlaps around it.
+
+- **The conflict-fixer round budget is an integration-level setting, not a
+  phase's `max_fix_rounds`.** `parallel-lanes.md` now says so, and defaults it to
+  two. A merge conflict belongs to a *pair* of phases, so deriving the budget
+  from one of them made the answer depend on which phase happened to merge
+  second.
+
+- **A resolved merge conflict is confirmed by scanning the files, never by asking
+  git.** `git add` clears a path's unmerged flag whether or not `<<<<<<<` is
+  still sitting in it, so git's index cannot answer "did the fixer actually fix
+  it". `parallel-lanes.md` now requires scanning the conflicted paths for
+  conflict markers before the merge is committed. Without it, a fixer that did
+  nothing produces a merge commit full of markers that passes into the wave
+  branch unnoticed.
+
+> The repository also gained `packages/vinta-ai-maestro/`, the workspace package
+> that executes these workflows. It is published as its own npm package,
+> `vinta-ai-maestro`, carrying the same version as `vinta-ai-workflows`, and is
+> run with `npx vinta-ai-maestro`. It is not part of the `vinta-ai-workflows`
+> tarball — the root `files` whitelist excludes `packages/`, so nothing in it is
+> installed by `npx vinta-ai-workflows install`. What ships from that work into
+> the skills package is the two generated schemas above and the skill changes
+> that produce and consume them.
+>
+> Its browser UI is now built on `packages/design-system/` (`vinta-design-system`),
+> a second workspace package: oklch tokens in three layers mirroring
+> `vinta-schedule-design-system`, six run-status **tones** (`idle`, `active`,
+> `wait`, `attention`, `ok`, `error` — waiting is amber and failure is red, never
+> the same hue), shadcn/ui components on Tailwind CSS v4, a small layout kit, and
+> a light/dark/system theme. The run graph and the pipeline editor are re-skinned
+> through their own custom properties, so the canvas and the badges beside it
+> share one palette. It and `vinta-dag-editor` publish on their own cadence
+> (`0.1.0`) as dependencies of `vinta-ai-maestro`; nothing in either reaches
+> `npx vinta-ai-workflows install`.
+
 ## [0.6.1] — 2026-08-17
 
 ### Fixed