Repository navigation
wavecoord 0.3.0
The course is attached: eleven narrated lessons on spec-driven development with wavecoord (course-NN-*.mp4, subtitles in .srt), recorded in real Claude Code sessions. The pages are in docs/course. Three short CLI videos are attached too. Use 0.3.1 or later: it fixes wavecoord init --pr.
Two adversarial reviews of 0.2.0, fixed: the spec workflow (#27-#30) and the whole plugin (#32-#36). The trust boundary between workers and the lead is tighter, the refinery merges only work that should land, and the launcher, steering and hooks survive restarts, retries and stops. Some changes need action on upgrade.
Upgrading
- Set the plugin option
coord_url(it has no default now). A remote coordinator gets the token only throughcoord_urlorWAVECOORD_URL, never from a repo's.claude/wavecoord.json; set one of them forgate-checkin CI too. - The fence mode and
spec.verify_at_mergecount only on the default branch's.claude/wavecoord.json, not in the lead's working copy. - Task PRs may no longer change Claude Code config (any settings key, anything under
.claude/or.claude-plugin/,.mcp.json,CLAUDE.local.md), in advisory mode too. Make these changes in a lead or plan PR. - A submodule change is a changed path: its lease must cover the submodule path itself (
vendor/suborvendor/**). - Agent tokens can no longer create leases, and their hot marks are literal paths.
watchdogandserverare reserved sender ids. - The spool and the lead cursor are kept per coordinator. An old
spool.jsonlis not replayed, and a lead session starts at the head of the log. migrate-planneeds the coordinator,--states FILEor--no-coord.- Requirements whose inputs have
fromchange fingerprint, so their tasks are suspect once (wavecoord spec rebase-basis). - Plan changes can no longer set
in_progress,in_reviewordone. In CI,spec check --baseaccepts the status writer's commits by theirWavecoord-Status:lines; give thewavecoord/statusbranch the same review rules as other bot branches. - Skills pre-approve only read-only
wavecoordcommands; the others ask each time. - The plugin option
projectis gone. Workers get the newpre-merge-commitguard in each new worktree.
Security
- The refinery runs the fence check (the
Lease:line, config and spec changes) beforecheck_cmdand before a spec tree task's Acceptance and Verify, so a PR that is refused never runs its code on the lead. - Verify and Acceptance run with a scrubbed environment:
PATH,HOME,LANG,LC_*,TMPDIR,TERM,TZ,USER,LOGNAME,SHELLand the newspec.verify_envnames; neverWAVECOORD_*,GIT_*,GH_TOKEN,GITHUB_TOKEN,SSH_AUTH_SOCKor the Anthropic keys. This is not a sandbox;docs/security.mdhas the trust model. - A task PR may not change any lead config key:
pr_cmd,pr_state_cmd,coord_url,project,log_branch,default_provider,auto_resolve,branch_prefixand the hosts'ssh,repo_path,prepare_cmd,providers,labelsanddispatchare nowconfig_changetoo (seeded defect D27). gate-checkruns the config and spec checks before it reads theLease:line, so a PR body with noLease:line, or with two, can no longer skip them (D26). The refinery refuses a missing or doubledLease:line like a stale one (a PR body thatgh pr viewcannot read is an E5 problem instead:enforceblocks,advisorynotes).- The refinery takes the fence merge mode and
spec.verify_at_mergefrom the config on the default branch, never from the lead's working tree. - Predicate S (a task PR may not change the spec tree) normalizes
spec.dir(D28), also uses the spec dir at the merge base, so a tree that moved meanwhile is still covered (D29), and compares paths without case (D30). - Claude Code config in task PRs (
config_change, design section 8): the settings files deny by default, so a change to any key but$schema(permissions,statusLine,apiKeyHelper,enableAllProjectMcpServersand every other) is refused, not only the five hook keys (D32). Any other file under a.claudeor.claude-pluginfolder at any depth (agents, commands, skills, a nestedpkg/.claude/settings.json), every.mcp.jsonandCLAUDE.local.mdare lead config too. Paths compare without case, so.claude/Settings.jsonorplugin/Hooks/hooks.jsonno longer pass on a case-insensitive checkout (D31). - The lead's repo config lookup reads
.claude/wavecoord.jsononly at the repo's top level: a nestedpkg/.claude/wavecoord.jsonno longer becomes the config (and thecoord_url) of a session started inpkg. - Submodule (gitlink) changes are paths at E2, E3, E5, the Stop hook and the refinery: every fence diff uses
--ignore-submodules=noneand-c diff.ignoreSubmodules=none, soignore = allin.gitmodulesno longer hides them (D33). A lease must cover the gitlink path (vendor/suborvendor/**). - E1 checks a file in a nested repo of another repo (a submodule checkout, a vendored clone) by its path in the worker's worktree, not by the nested repo's own path (D34).
- E1 compares the protected local folders (
~/.claude,$WAVECOORD_HOME, the plugin root) without case on a disk that folds case, and a.GITsegment is git internals (D35). - The refinery's protected-path check lists both names of a rename (
--no-renames), so moving a protected file out of its folder needs the approval; a git error there blocks instead of passing. - The pre-push guard refuses in enforce mode when git cannot compute the pushed paths, and reads the new commits when the remote head is not in the local repo (a forced push over a moved branch) (D37).
- Schema patterns follow JSON Schema:
$matches only at the end of the string, sot1\nis no longer a valid task id. - An agent token acts only within what the lead dispatched (
docs/design/edit-fence.md2.3,contract.mdsection 4). A claim may only renew the lease the lead granted to its holder, or resume a parked lease of the same attempt on the same host with the same grants (seeded defect D39): a worker can no longer claim**for a task the lead never dispatched, or widen a resumed lease and pass E5 through the resolver lineage. Hot marks are one path, no*or?(D38). A report must come from the attempt's holder and is refused for amergedorabandonedattempt;mergedstays final in the fold. An agent'spr_urlis ignored: the PR of an attempt is the one the lead opened.collectno longer takes a PR URL from the host'sresult.jsonorstatus.json(the worker can write both), and opens the PR for the branch the lead launched, not the branch the host reports. - Idempotency keys are scoped per principal, so a host can no longer take another host's report key (
report:<task>:<n>) and drop its report. The lead's collect re-post still deduplicates against the host's report. - Agent ids are checked:
lead,ui,watchdogandserverare reserved in any case and with surrounding white space, and an id must be a plain token ([A-Za-z0-9][A-Za-z0-9._:@+/-]*, at most 128), so a worker cannot send as the watchdog or put a fake frame in its sender. - The hooks and the CLI send the user's token only to
WAVECOORD_URL, the plugin optioncoord_urlor a loopback URL, never to acoord_urlthat only a repo's.claude/wavecoord.jsonnames. - The lead's records are redacted before they are logged: secret env values, the coordinator token files and common token formats in
check_cmd, Verify andmerge_cmdoutput no longer reachcoord/log(redact.py). - A remote host's probe sends no token to
/api/healthand checks that the server proves it is the coordinator (a challenge answered with HMACs keyed by the host's token digests); the launcher refuses a host where another process holds the coordinator port. - Local workers without
~/.wavecoord/hosts/<host>.tokenget an agent token provisioned; the wrapper never falls back to the lead's token. tokens provision --outwrites a mode-600 file also over an existing file with a looser mode.- The HTTP front: a socket timeout (
REQ_TIMEOUT_S), at mostMAX_CONNSconnections, the token checked before the body is read, and chunked bodies refused (411), so idle connections can no longer exhaust threads and file descriptors, and a chunked body never runs a request with its defaults. tests/test_generic.pyalso catches GitHub fine-grained, GitLab, Slack, OpenAI, Google and AWS STS keys.- Launched workers get no tool of the plugin's MCP servers (the worker settings deny
mcp__plugin_wavecoord_wavecoordandmcp__plugin_wavecoord_lead-feed): Claude Code fills their token from the plugin option, which can be the lead's. - The plugin option
coord_urlhas no default, and the hooks act only withWAVECOORD_URLset or in a repo with.claude/wavecoord.json, so sessions in other repos no longer heartbeat or post notices to the coordinator with the lead token. - The PR body quotes a line of the worker's text that starts with
Task:,Attempt:orLease:, so a worker cannot add a second header and block its PR. - When the worker pushed its branch itself, the launcher still runs the fetch, merge-tree and E3 on it, so the report has its E4 fields and an E3 refusal fails the attempt.
- A zipapp upload is checked against its hash before it takes the build's name; a cut transfer no longer leaves a broken build that is never uploaded again.
Added
- Setup in two commands.
wavecoord initsets up a repo: it writes.claude/wavecoord.json(or adds only the missing keys to an existing one), makes the lead token and the local host's agent token when their files are missing (never over an existing file), and on request installs the server service (--server), creates the spec folder (--specs), sets the plugin options withclaude plugin configure(--configure-plugin; the token is never printed unless--show-token) and opens a config PR onwavecoord/setup(--pr).--dry-runwrites nothing;--interactiveasks on a terminal. It ends withwavecoord doctor --quick. wavecoord doctorchecks every prerequisite, one line each (ok,warn,fail) with the command that fixes it: Python, git, origin and its default branch,ghand its login (or a custompr_cmd), the claude version and login (claude auth status, no model call), the plugin and its options, the config (valid, committed on the default branch),coord_url, the coordinator (reachable, same version, the token accepted), the token files and their modes, the hosts (thehostsprobe;--quickskips it), the server service and its pinned build, and the plan store with the reason.--jsonprints the checks; the exit code is 1 when one fails.- The
/wavecoord:setupskill runs doctor, explains each problem, runswavecoord initafter asking, re-checks and points to/wavecoord:spec. It pre-approves onlywavecoord doctor,wavecoord init,wavecoord statusand read-only git. - The quickstart starts with
wavecoord initand/wavecoord:setup; the manual steps moved to its end. wavecoord lease release <task|id>and the lead toollease_release: release a stale or parked lease so the task can be dispatched again (a lost worker's lease used to hold its task for good). The triage skill uses it.wavecoord spec import --from <speckit|kiro|openspec>: reads GitHub Spec Kit, Amazon Kiro or OpenSpec files and writes them as draft records under one capability, through the op API, so the result passesspec check. Statements become EARS where the rewrite is mechanical; task items with file paths become tasks withpathsandneeds; each record names its source file, which is never changed. It reports what needs a person (statements that are not EARS, tasks without paths, unknown sections) and a Verify warning per requirement.--dry-runprints the diff,--dry-run --jsonthe ops forspec_edit; a re-import changes nothing or is refused.docs/import.mdhas the mappings and their gaps.- The course (
docs/course/): spec-driven development with wavecoord for beginners, in eleven lessons (what SDD is, install, first spec, a new project, an existing project, importing Spec Kit, Kiro or OpenSpec, good specs, running, steering, triage and recovery), each a short page, a narrated video of a real Claude Code session and an exercise, with a choose-your-path map.scripts/course/has the demo projects (demos/demos.py:fresh,brownfieldin four states,speckit,kiro,openspec, each with a local bare origin), a local stand-in for GitHub (demos/bin/gh), the lesson scripts andbuild.py, which builds the demo, records the lesson with the rig, adds title and diagram cards, cuts long waits and writes the MP4 and SRT todist/course/.build.py --validatechecks every lesson against the rig's format. The rig gains await_shellstep and acheckcommand, givesshellsteps the lesson's environment, and reads token usage from the lesson'sCLAUDE_CONFIG_DIR. The guide's triage table adds thebranch_missingandmerge_failedholds, and thespec newexample indocs/specs.mdgives the Statement a requirement needs. - The skill
/wavecoord:spec-import: finds Spec Kit, Kiro, OpenSpec or free-form specs (PRDs, BMAD documents, ADRs) in the repo, shows the mapping, asks about granularity and scope, and opens one plan PR withspec_edit./wavecoord:specpoints to it when it finds such files.
Fixed
- Task prompts from
/wavecoord:wave-planno longer tell workers to push. A launched worker may not push (the launcher does), so such a prompt made it reportblocked. The reviewer agent, the risk table and the watchdog nudge say the same. wavecoord initlets workers rungit mergeandgit log. A resolver merges the default branch into its branch, and was denied before.wavecoord attempts lsshows costs as$0.0097or$1.23, not as raw floats.wavecoord launch --continuekeeps the earlier run's model, effort, turn and budget limits when they are not given; it ran on Claude Code's default model before.--continueresumes the earlier session when the recorded worktree path and git's differ only by a symlink (/tmpand/private/tmpon macOS); it started a fresh session before.- A usage warning from Claude Code (
rate_limit_eventwith statusallowed_warning) no longer counts as a rate limit, so it does not back off the provider and hold the next wave. /wavecoord:specand/wavecoord:wave-planwrite spec ops to a file forwavecoord spec apply --dry-run, instead of a heredoc that made Claude Code ask for permission.- Verify and Acceptance run on the merge of the default branch and the PR head, not on the head alone, so work merged since the branch started is in the checked tree.
- Verification fails closed: a task or requirement record that is missing or does not parse at merge blocks with
verify_unavailable.verifiedis recorded only when a Verify command ran. - A
droppedoron_holdsibling no longer defers a requirement's Verify: the last merging task runs it. - A Verify or Acceptance command with a trailing
# commentno longer fails every merge. - Predicate S applies only when the repo uses the spec tree, so a flat-plan repo with its own
specs/folder is not refused withspec_change. spec.dirvalues such as./specs,specs/.ordocs//specsno longer cut characters off the record ids; the schema now rejects.,..and//in it.- Status commits (
docs/specs.md, Status;docs/design/spec-layer.md7.2):- The writer reads the task files at the exact sha it commits on, never at a moving ref or the working tree, and refuses a write that changes more than the
status:line. A plan PR merged during a flush is no longer reverted. - The status line is found in any form the parser reads: quotes, a trailing comment (kept), CRLF (kept).
- The writer writes only over
planned,in_progressandin_review;draft,on_holdanddroppedare never overwritten, also while an attempt runs (listed underheld). - A parked lease counts as
in_reviewonly when its attempt has a PR. spec status-sync --reset <task>(andspec_status_syncreset) sets a rolled-backdoneback toplannedwhen the coordinator has no merged attempt.- The status PR: the branch
wavecoord/statusis no longer deleted under its open PR; it is force-pushed with a lease and rebuilt only when the base or the changes move. A merged or closed status PR is replaced.merge_cmdgetsWAVECOORD_PR,WAVECOORD_SHAand the other variables, as in the refinery. - A push failure is classified: a lost race is retried after a fetch with backoff, a refusal goes to the status PR, anything else is blocked.
- A flush never raises, so
dispatch,collectandrefinery_mergeno longer fail after their side effects.spec.status_blockedis logged once per distinct reason. - A non-forced flush never waits for a running one, and a forced one is queued behind it, so dispatch and the refinery do not stall. The status loop follows
spec.status_flush_s.
- The writer reads the task files at the exact sha it commits on, never at a moving ref or the working tree, and refuses a write that changes more than the
- Bot commits (status,
spec_edit,plan_edit) do not run the consumer's git hooks, and their worktree add and remove take the worktree admin lock. spec_edit,plan_edit: a reused branch that is merged, or whose PR is merged or closed, is refused; one without a PR gets one. A delete then a move into the freed id works. A move then a delete of the same record deletes it. Writes through a symlink underspec.dirare refused. The PR body reports the errors already on the base instead of "no errors".- Spec tree in the lead.
- The lead reads the spec tree only from the default branch, never from its working tree, so uncommitted spec files are never dispatched or pushed by a status commit.
- With no
plan.adapter, the spec tree is the plan only whenspec.diron the default branch holds a valid record; a strayspecs/openapi.yamlkeeps the flat plan. Theconfigtool shows the store in use (plan.selected_by) and thespecdefaults. - Coordinator state follows a task through its aliases: a moved task keeps its live or merged state (readiness,
plan_graph, status commits) and is not dispatched again.plan_getanddispatchtake a tree id or an alias. conflicts_withis enforced: a task is not ready while a task it conflicts with runs or is in review, anddispatch_wavenever starts both.- A task under a folder without
_node.mdno longer crashesplan_graph,plan_getorplan_ready; it is not ready, with a reason. - A task left
in_progressorin_reviewin the files with no live attempt is ready again. attempt.startrecords the task'sbasis; the worker prompt names the task that makes each input.spec_treeprogress andspec_queryuse the coordinator's state.
- migrate-plan.
- Carries the coordinator's state (
--states FILE,--no-coord, else it asks the coordinator): merged tasks aredone, running onesin_progress, in reviewin_review;blockedbecomeson_hold. - Keeps every old id as an alias (aliases may now hold any flat task id), fits long ids within 64 characters, and makes a valid tag of a phase that starts with
_. - Gives open tasks with overlapping paths
conflicts_withinstead of refusing the plan. - The legacy requirement is approved and its capability and feature active, so the migrated tasks run;
docs/specs.mdsays what to review and commit.
- Carries the coordinator's state (
- Spec records never lose data.
spec fmtand every op refuse a record whosekindis unknown or not its path's, that has unknown keys, or whose list key holds a scalar or mixed types; the file is left as it is and reported (cannot format, exit 1). Code fences follow Markdown (and ~~~, closed by a run at least as long;x``` is inline code). Rendered scalars always read back: control characters are quoted, flow items with,`[` `]` `{` `}` are quoted, floats are written as digits. - Readiness fails closed. A need that does not resolve, a needed record that does not parse or breaks its schema, and a need on a node with no tasks yet keep dependents waiting; one malformed field no longer crashes the whole plan (the record is reported and left out). Dropped tasks neither block a need on their subtree nor count as producers.
suspect: refusetreats a task withoutbasisas suspect. A superseded requirement's tasks do not run;supersedeson itself or in a cycle is an error. - Plan changes cannot set coordinator statuses. The op API (
spec_edit, REST, the CLI) refusesin_progress,in_reviewanddone(also increatefields), any change of adonetask's status, and any change of a live task other thandropped; the publiccoordinatorop flag is gone.wavecoord spec check --base <ref>reports such a change in a hand edit. - Moves keep tasks current. The fingerprint leaves out an input's
from, so moving a node no longer makes the tasks of its consumers suspect (tasks whose requirement has such inputs show suspect once after the upgrade: review them, thenrebase-basis). Moving back to an old id drops that alias. A task created in a batch gets its basis after the batch's last op. waveslists only tasks that can run (or are running); held tasks come with a reason (held), and an unknown node is an error (not_found). A4 accepts a producer reached through other tasks. Cycle detection no longer hits the recursion limit.pathslike./src/a.pyorsrc//a.pyare errors and compare assrc/a.py./wavecoord:speccan open its PR before tasks exist: A1 and A3 only warn while no task file is under the node.- Ops: line breaks in one-line values, malformed scenario steps and moves of a subtree with stray files are clean errors; the Statement is never split into sentences, and the splitter keeps numbered lists, indented lines and abbreviations (
e.g.,approx.,v2. 0).delete --forcesays what it does (children, not references).spec querywith an unbalanced quote is a clean error. - A symlink under the spec directory is a layout error in the working tree and in a git ref; no tool reads or writes through it.
- Skills: wave-plan and the planner no longer copy the requirement's Verify into every task's Acceptance (the refinery runs it with the last task); wave-plan reports the waves of the plan branch with
wavecoord spec waves --ref <commit>; wave-run maps tree ids to coordinator ids; triage sends spec changes through/wavecoord:revise(spec_edit); revise reads a requirement's change from its history. docs/specs.md names only commands that exist. The worker prompt says the requirement's Verify may fail until the last task merges. - Seeded defects S12-S15.
- Predicate S uses the lead's rule for the spec tree: with no
plan.adapter, only aspec.dirthat holds a spec record is the tree, so a task PR may change a strayspecs/api.yamlin a flat-plan repo. A task PR that adds the first spec records is refused. - An offline-override journal of any size can be flushed: the batches are cut by size (half the server's body limit), not by count, so a large journal no longer gets a 413 forever and blocks every push on the host (D36). One reachable flush sends batches until the journal is empty.
- The Stop hook reads the changed paths with
-z, so a non-ASCII file name no longer makes the server refuse the batch and drop the other outside-lease warnings; a path that no glob can hold is reported as outside the lease without a server call. guard installalso writes apre-merge-commitguard. The docs now say that git runs no commit hook forcherry-pick,rebase,amor a fast-forward merge; E3 and E5 check those commits.- Seeded defects D31-D39.
- A failed group commit of
coord/log(a staleindex.lock) is retried with a backoff instead of refusing writes until a restart. - A forked
coord/log(two servers on clones of oneorigin) is refused at start and after a rejected push, with both heads, instead of pushing nothing forever withok: true(rollback.md, "A forked log"). - The hooks spool keeps entries the server answers with 5xx, 408 or 429, keeps their order when hooks spool during a replay, and is per coordinator (
spool-<hash>.jsonl), so writes for one coordinator are never replayed into another. Entries in an oldspool.jsonlare not replayed. - The watchdog's idempotency keys are unique per idle episode, so a lease revived without new activity is nudged and marked stale again.
rebuild --atkeeps a revert marker only for an event after the rollback point, so a reverted message that comes back can be reverted again.GET /api/eventsrefuses a negativesinceorLast-Event-ID(it busy-looped).NaNandInfinityin a body are 400, and the schema validator rejects them as numbers; a$at the end of a schema pattern no longer accepts a trailing newline.- A body that is not a JSON object, or a malformed lead request, is 400 instead of 503.
- MCP
tools/callchecks the arguments against the tool'sinputSchema;conflictswithglobsas a string no longer answers "no conflicts". - With a wildcard bind and no
coord_url, workers get the firstallow_hostsname (or loopback), nothttp://0.0.0.0:<port>. - A lead line quotes a value with a trailing newline instead of breaking the line.
- The refinery merges only what should merge. It merges an attempt only when its report is
done(failed,blockedandneeds_decisionblock withreport_not_done) and its task is notdropped,on_holdordrafton the default branch (held). One item whose check cannot run (git,protected_paths_cmd, the plan) blocks withunavailable; the loop goes on, and the merged items' status is flushed. Requirement Verify follows a sibling's aliases (a moved task merged under its old id counts as done), and a sibling record that does not parse blocks withverify_unavailable. - Resolvers. The refinery starts a resolver only with
auto_resolve, andMAX_RESOLVEScounts resolver runs per attempt (a new conflict id per round no longer resets it).resolveis refused while a run of the attempt is in flight, and a resolver resumes the parked lease instead of stealing a live one.resolvetakesbrief, the user's decision, which the resolver reads first. - Rate-limit fallback.
collectstarts the fallback attempt through the normal readiness check (noforce), so a task dropped, held or merged meanwhile is not started again; the provider comes from the lead's chain, not the host's result. A rate-limited resolver keeps the attemptreportedwith its PR and runs the resolver again on the next provider, instead of a new full attempt. - Status commits.
wavecoord spec check --basepasses the status PR (status lines only, each named by aWavecoord-Status:line) and the output ofmigrate-plan(new tasks with a flat id alias), so the documented CI check no longer refuses them. After a restart the writer adopts its open status PR instead of failing on a second one.spec.status_blockedis logged under thestatus-writeractor, so it reaches the lead's feed. - Spec tree in the lead.
SpecTreePlan.getresolves a migrated flat id with dots before a node with the same path. A read error of the default branch fails closed (unavailable) instead of planning fromplan/tasks.spec_treeandspec_wavessay whenplan.adapterkeeps the tree from being dispatched (plan_note).spec_editrefuses a new task under the id of a deleted task that the coordinator merged or runs, warns (switch:) when its PR adds the first spec records whileplan/taskshas tasks, and rewrites the PR body for the whole branch on a later call.wavecoord spec apply - --dry-run --ref <ref>checks ops against a ref. plan_graphand plan validation no longer hit the recursion limit on a long needs chain (plan/graph.pycycles and critical path are iterative).- Skills: triage and wave-run call
collect(PRs now open in the plugin workflow); triage names a retry path for an attempt that has a PR (continue it, or close the PR andcollect) and the new holds; wave-plan and the planner create tasksplanned; the spec, wave-plan and wave-run skills checkplan.selected_by; the resolve skill and its template match the real resolver (same branch,brief). - Launcher.
- A new attempt that fails before its wrapper runs moves its state to
attempts/<project>/.failed/and removes its worktree and branch; the attempt number counts the hosts' attempt dirs and local branches (for-each-refnow uses a glob). A failed launch no longer makes every later dispatch fail withalready exists. attempts stopnever writes a final state while the wrapper holds its run lock (it answersstopping); a held run lock takes a slot and keeps gc away whateverstatus.jsonsays. A stop kills a runningprepare_cmd(its own process group). When finish fails, the wrapper still posts afailedreport and the finish.- The finish fetch takes the worktree-admin lock and retries, and a push error that is not a refusal is retried, so a concurrent fetch no longer fails a finished attempt.
- Heartbeats go on during
prepare_cmdand the push steps, so a long build no longer makes a healthy lease stale. - Every remote command touches its build, so the 30-day cleanup never removes a build in use; the wrapper reads the report schema and the modules it needs at start.
- Worktrees are
<repo_path>/../wt/<project>/<task>-<n>, so repos side by side do not collide (a--continuerun reuses a worktree at the old path). - The
ssh -Rtunnel is a connection of its own (ControlMaster=nonow comes before the shared options). - Remote scripts run as
sh -c '<script>', so a host whose login shell is csh, tcsh or fish works. - A
--continuerun (a resolver) that adds no commit still gets the merge-tree check, so it is not counted clean while the branch conflicts.
- A new attempt that fails before its wrapper runs moves its state to
- Steering.
- A lead steer action acts only on the run that held the task's lease when it was sent: an old
steer stopno longer stops every later attempt. - The hooks of a launched worker never show or ack a steer action, so the wrapper always gets it.
- The inbox relay no longer acks a message because the socket write went through; the hooks ack it when the transcript shows it and deliver it themselves otherwise.
- The STEER_WAIT_S close guard counts only turn lines (not control responses, hooks or state changes), and a control alone (a model switch with no note) gives no extra turn: a run no longer hangs until its timeout and ends
timed_outwith a valid report. steer interruptwithout a note stops the turn, not the run: a line that says to go on follows the interrupt.- A steered turn after the report that fails or writes no report no longer replaces the worker's valid report (
late_turnin the result). - An error answer to a lead's control request (or none) is recorded in
steer.jsonland sent to the lead as asteer_failednotice. - The stuck detectors:
loopkeys on the whole tool input and counts assistant messages, not parallel calls;failingcounts failures in a row and starts again after a success or an edit.
- A lead steer action acts only on the run that held the task's lease when it was sent: an old
- Hooks.
- The
Stophook no longer tells a launched worker to push. - Injected text is fitted before anything is acked: a message that does not fit stays unacked, and the lead cursor moves only past the event lines that went in.
- Hook state, the relay files and the lead cursor are per coordinator (
<state dir>/coord-<sha(url)>/), so a second coordinator's message ids are not taken as shown.
- The
- Setup (found while writing the course).
wavecoord initandwavecoord doctorput and look for host tokens where the launcher reads them,$WAVECOORD_HOME/hosts/when it is set (one function,launcher.common.host_token_file), not always~/.wavecoord/hosts/.init --serverstarts the service on the port of the config'scoord_url(serve --port), not always on 18741; for acoord_urlwith another host it prints theinstall-server --bindcommand instead of widening the bind.WAVECOORD_HOMEis the launcher's root folder but one project's state folder for the server;docs/launcher.mdsays so, and doctor's newhomesline names both folders.- A
claude --plugin-dirsession's plugin (wavecoord@inline) is no longer reported as not installed: doctor finds it throughCLAUDE_PLUGIN_ROOTor--plugin-id, andinit --configure-plugin --plugin-id <id>configures that id (in a--plugin-dirsession it pickswavecoord@inlineby itself). - doctor no longer says
ghis "not needed" whenpr_cmd,merge_cmdandpr_state_cmdare set: the refinery's fence check, a resolver'sLease:line and plan PR bodies still usegh(warn;failin fence merge modeenforce).docs/adapters.md, "Other forges", lists these calls. - The refinery's merge order between tasks that unblock the same amount of work is the attempt that finished first, then the task id (unchanged, now documented and tested).
Changed
refinery_mergerefusesapproved_protectedwithoutpr: an approval covers one PR the user saw.- Skills pre-approve only read-only
wavecoordcommands (status,events,hint,attempts logs,specreads);launch,steer,refinery,revert,rebuild,tokens,gcandspec applyask each time. - The README and quickstart config no longer set
"plan": {"adapter": "builtin"}, which kept the spec tree from being dispatched. - The default
pr_state_cmdalso asks forurl. - The plugin option
projectis gone: nothing read it, and the project comes from.claude/wavecoord.json. - The lead cursor moved to
<state dir>/coord-<sha(url)>/lead-cursor.json. After the upgrade a lead session starts at the head, without the old backlog.wavecoord events --for lead --state-dirtakes the same base dir and finds the subdirectory from--url. Run one lead session per coordinator. - The plugin option
coord_urlmust be set (it had the defaulthttp://127.0.0.1:18741). - Hints (plain messages) to a task still reach every later run of the task that has not seen them; this is now documented (
launcher.md, "Listen and steer"). - CLI text output (the
--jsonoutputs are unchanged):attempts lssizes its columns to the content and shows the PR thatcollectopened;refinery mergeadds a short detail to a blocked line (the paths outside the lease, or the report status) and drops the trailing space aftermerged;refinery statusandspec treesize their name columns to the content;planpoints towavecoord spec ready/spec waveswhen the spec tree is the plan;hintsays "within a few seconds" for a shortINBOX_POLL_S;gate-checkprints its verdict on stdout too, in words (fail: 1 path outside the lease: README.md). The refinery's fence hold detail lists the E5 paths first. - Docs: the README is rewritten as the front door, with an architecture diagram and a wave sequence. The new
docs/guide.mdteaches the workflow (the model, one feature from idea to merge, writing specs, safe waves, steering, triage, recovery, upgrade notes), anddocs/README.mdmaps the pages. The quickstart config setscoord_url, which the terminal CLI needs now that nothing has a default URL.