Repository navigation
Releases
wavecoord 0.3.1
Fixed
wavecoord init --prstages the files it puts in the PR. An untracked copy made thegit pullafter the merge refuse to overwrite it.
Everything else, and the course videos, are in 0.3.0.
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 tok...
wavecoord 0.2.0
The spec tree: requirements and plans as typed Markdown records in your repo, merge-friendly, checked by scripts, planned in waves, with live status in git (docs/specs.md, docs/design/spec-layer.md). Phases S0 to S5.
Added
- Spec tree, phase S1 (
docs/design/spec-layer.md,docs/specs.md): typed Markdown records for capabilities, features, requirements, tasks and decisions underspecs/(spec.dir).wavecoord spec tree|show|query|check|lint|fmt|fp: read the tree from the working tree or a git ref (--ref, two git processes for any number of files), query it (kind=task status=planned outputs~src/*), check each record (layout, frame, schema, sections, artifacts, EARS, canonical form), format it canonically, and print a requirement's fingerprint.schemas/spec-record.schema.json, and thespec.dirconfig key.
- Spec tree, phase S2: the rules across records and the writes.
checknow also proves references (with aliases), blockers (needson any node expands to its subtree and is inherited; no cycles; no needs on an ancestor or descendant), alignment rules A1-A7 between inputs, outputs andneeds, and predicate P (two tasks that may run at the same time do not write the same paths); suspect tasks are warnings.- New reads:
waves(what can run together, the critical path, the width),ready,trace,artifacts,suspect. - Writes through one op API (
schemas/spec-ops.schema.json):new,set,status,section,add,rm,artifact,artifact-rm,scenario,mv(rewrites references, keeps the old id as an alias),rebase-basis,supersede,delete, andapplyfor a JSON list of ops. A change that would add an error writes nothing;--dry-runprints the diff. migrate-planmovesplan/tasksinto the tree.- Tests: real
git mergeof random edits on two branches (no conflict, the result checks clean), sorted inserts, genuine conflicts, status against other keys, races; parallel safety of the computed waves; injected misalignments; seeded defects S01-S06 and S09-S11.
- Spec tree, phase S3: the tree in the lead.
- The spec tree is the plan store when the config has no
plankey andspec.dirhas records on the default branch, or with"plan": {"adapter": "specs"}:plan_ready,plan_get,dispatch,dispatch_waveand the dispatcher loop read tasks from it. A task's coordinator id is its path with.for/. The coordinator's states (live attempts, parked leases, merges) count over the status in the files. - The worker's prompt gets the requirement (statement, scenarios), the task's inputs and outputs with their contracts, and the requirement's Verify commands.
- MCP tools
spec_tree,spec_get,spec_query,spec_waves,spec_trace,spec_checkandspec_edit(ops on aplan/<n>branch, moves asgit mv, one PR; several calls with one branch build one PR), and the REST routes under/api/spec/. plan/edit.pysplit intoplan_branch,commit_filesandread_at, shared byplan_editandspec_edit.
- The spec tree is the plan store when the config has no
- Spec tree, phase S4: status commits, the merge rule, verify at merge.
- The coordinator writes task status into the spec tree:
in_progress,in_review,done, and back toplanned, by reconciling the files with its state and committing only thestatus:lines that differ (wavecoord: status (<n> tasks),Wavecoord-Status:lines), everyspec.status_flush_sand at once after a merge. When the default branch refuses the push, the commit goes through awavecoord/statusPR merged withmerge_cmd. Eventsspec.statusandspec.status_blocked;wavecoord spec status-syncand thespec_status_synctool. - A task PR may not change the spec tree: gate-check reports
spec_change, the refinery blocks (edit-fence.md section 8.1, predicate S, seeded defect D25).specandplanjoined the config keys that a task PR may not change. spec.verify_at_merge(on by default): the refinery runs the task's Acceptance and its requirement's Verify, from the default branch, aftercheck_cmd; a failure blocks withverify_failed;refinery.mergerecords the requirement and its fingerprint.- The PR body of a tree task ends with the trailers
Spec-Task:andSpec-Basis:. - Config keys
spec.require_approved,suspect,verify_at_merge,status_commits,status_flush_s,status_author. - Seeded defects S07 and S08.
- The coordinator writes task status into the spec tree:
- Spec tree, phase S5: the workflow.
/wavecoord:specbuilds and revises the tree with the user (referencesears.md,spec-templates.md) and opens one plan PR withspec_edit.wave-planplans tasks under requirements (outputs cover the requirement's promises, inputs from needs, Acceptance includes Verify,spec_wavesin the PR body);revisehandles suspect tasks and the proposal kindsrequirement_gapandspec_change;wave-runusesspec_waves;triagehandlesverify_failed,spec_changeandspec.status_blocked;coord-statusshows the tree's progress.- The planner and reviewer subagents read the tree (
spec_get,spec_query,spec_trace,spec_check); the reviewer has a spec mode. - Report proposals
requirement_gapandspec_change. scripts/smoke-live.py --checks spec: a two-task requirement through the coordinator with a realclaude.
- Block lists in the YAML subset:
key:followed by- itemlines, in task specs too, and block lists of flat maps for the spec tree's inputs and outputs. Every file that parsed before parses to the same value.
Fixed
- A too-large request could reset the connection instead of answering 413. The server refused a body over
REQ_MAX_BYTESbefore reading it, so a client still writing it gotConnection reset by peer(seen in CI on macOS with Python 3.12). It now reads and drops up to 1 MiB of the body first, then answers 413 and closes the connection. - A launched worker's
SessionEndhook released its own lease before the launcher pushed. Real Claude Code runsSessionEndwhen a worker ends; the hook sentfinishwithpushed: false, so the server released the lease, the attempt went to the refinery with no parked lease (blocked asstale_lease), and a task never showed as in review. The fake claude runs noSessionEndhook, so only the live smoke test found it. The hook now leaves the finish to the launcher whenWAVECOORD_ATTEMPT_DIRis set. - Verify at merge on a requirement with several tasks. The requirement's Verify describes the finished requirement, so it now runs with the merge of the last open task under it; earlier merges run the task's Acceptance and record the tasks still pending (
requirement_pending).
wavecoord 0.1.6
Added
- Listen to and steer running workers. Workers now run with
--input-format stream-json, and the wrapper keeps their stdin open (launcher/steer.py).- Every
INBOX_POLL_S(5 s), and with each heartbeat answer, the wrapper writes the worker's new messages into its stdin as one framed user line withpriority: "next". The worker reads it at its next step instead of after its next tool batch. The wrapper then acks the messages with the hooks' key, so the hooks do not show them again. - A lead message
wavecoord:{"action": ...}is a steer action:interrupt(acontrol_requestinterrupt, then the note as the next turn),model(set_model) orstop. From any other sender it stays plain text. - After a
result, new messages get one more turn, at most 3 per run. Otherwise the wrapper closes stdin and the run ends. - New lead commands:
wavecoord hint <task> <text>andwavecoord steer <task> interrupt|model <m>|stop [--note].
- Every
- Progress and stuck notices. The wrapper keeps a digest of the stream: turns, tokens, the last tool calls and text, edited files, failing commands, and the session state (
CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS=1). It posts aprogressnotice everyPROGRESS_S(300 s), with the context use from aget_context_usagecontrol request. It posts astucknotice, once per reason, for:loop: the same tool call 3 times in a rowfailing: the same command failed 3 timeswaiting:requires_actionbudget: 75% of turns or tokens usedquiet: no output forQUIET_S
- Inbox relay for sessions that wavecoord did not launch. A worker session that a person started (
WAVECOORD_TASKset, no launcher) gets its messages through its Claude Code inbox socket (CLAUDE_CODE_MESSAGING_SOCKET).SessionStartstartswavecoord inbox-relay, which pushes the framed messages with the session's token and acks them only after the socket took them. The hooks skip the pushed ids.- The socket's line format is not documented by Claude Code. It was taken from Claude Code 2.1.302 (
hooks.md, "Claude Code facts"). A failed push leaves the message to the hooks.
steerersubagent andauto_steer./wavecoord:triagehandlesprogressandstucklines. Withauto_steer: "draft"(the default), thesteererdrafts a hint and the user decides. With"hints", triage sends plain-text hints itself, at most one per attempt every 10 minutes. Interrupts, model switches and stops always need the user.auto_steeris lead config: a task PR that changes it fails the merge check (config_change).- New constants
INBOX_POLL_S,PROGRESS_S,QUIET_S(contract section 5). scripts/smoke-live.py: a live check with a realclaude(hint, steer, listen and relay; this host and--sshhosts). A manual release check, never in CI (CONTRIBUTING.md).
Fixed
wavecoord tokens provision --outinto a new directory failed (the quick start's~/.wavecoord/hosts/local.tokenon a fresh machine), after it had already added the token to the tokens file. It now creates the directory (mode 700) first.- A worker launched from inside a Claude session inherited that session's inbox. The launcher now also removes
CLAUDE_CODE_MESSAGING_SOCKETandCLAUDE_CODE_MESSAGING_TOKENfrom the worker's environment.
Also in this release: 0.1.5 (not released separately)
Fixed
--continueresumed a session that does not exist. Each run of an attempt got a fresh session id intask.json. A--continuerun passes only--resume <id>, and Claude Code keeps writing into the transcript of the resumed id (only--fork-sessionmakes a new one), so the fresh id of a resumed run never had a transcript. The next--continueresumed that id: claude printedNo conversation found with session ID: <id>, the result waserror_during_executionwith 0 turns, and every later--continueof the attempt failed the same way (seen with Claude Code 2.1.302 on Linux, after a--continue --specrun). Now:- The launcher resumes the attempt's lineage: the session whose transcript the last run wrote (
transcript_session), then the first run's id, then the ids of the earlier runs inprev-*/, oldest first. So an attempt left by 0.1.4 resumes its first run's session again. - The wrapper checks that the transcript file exists (
$CLAUDE_CONFIG_DIRor~/.claude,projects/<encoded worktree path>/<id>.jsonl, with the provider's environment) before it resumes. It never passes--session-idtogether with--resume. - When no transcript exists, or claude says
No conversation found, the wrapper starts a fresh session in the same worktree, one time. The prompt is a short note with the branch's commits since the base, the first run's full prompt and the continue prompt.session_fallbackin the result,status.jsonandtask.jsonrecords the reason. The next--continueresumes the fresh session. - A
--continuerun with--speckeeps the same lineage. The result, the report request andstatus.jsongive the session id of the transcript. - The fake claude keeps transcripts in a fake
~/.claude/projectslayout (FAKE_CLAUDE_TRANSCRIPTS=1, on in the launcher and e2e tests), refuses--session-idwith--resume, and fails a--resumeof an unknown id as Claude Code does. New tests: two--continueruns (the second with the spec prompt) resume the first id, recovery of a 0.1.4 attempt dir, the fallback without a transcript, and the fallback afterNo conversation found.
- The launcher resumes the attempt's lineage: the session whose transcript the last run wrote (
dispatch --wavecheckedwip_capagainst the same count for each task. The dry run printedwip 3/6for all four tasks of a wave, becausedecidecounted only the attempts in the snapshot. Now each task that the wave placed counts for the next one (wip 3/6,4/6, ...), in a dry run too, and a wave stops at the cap. New assertions intest_wip_cap_and_wave.
wavecoord 0.1.5
Fixed
--continueresumed a session that does not exist. Each run of an attempt got a fresh session id intask.json. A--continuerun passes only--resume <id>, and Claude Code keeps writing into the transcript of the resumed id (only--fork-sessionmakes a new one), so the fresh id of a resumed run never had a transcript. The next--continueresumed that id: claude printedNo conversation found with session ID: <id>, the result waserror_during_executionwith 0 turns, and every later--continueof the attempt failed the same way (seen with Claude Code 2.1.302 on Linux, after a--continue --specrun). Now:- The launcher resumes the attempt's lineage: the session whose transcript the last run wrote (
transcript_session), then the first run's id, then the ids of the earlier runs inprev-*/, oldest first. So an attempt left by 0.1.4 resumes its first run's session again. - The wrapper checks that the transcript file exists (
$CLAUDE_CONFIG_DIRor~/.claude,projects/<encoded worktree path>/<id>.jsonl, with the provider's environment) before it resumes. It never passes--session-idtogether with--resume. - When no transcript exists, or claude says
No conversation found, the wrapper starts a fresh session in the same worktree, one time. The prompt is a short note with the branch's commits since the base, the first run's full prompt and the continue prompt.session_fallbackin the result,status.jsonandtask.jsonrecords the reason. The next--continueresumes the fresh session. - A
--continuerun with--speckeeps the same lineage. The result, the report request andstatus.jsongive the session id of the transcript. - The fake claude keeps transcripts in a fake
~/.claude/projectslayout (FAKE_CLAUDE_TRANSCRIPTS=1, on in the launcher and e2e tests), refuses--session-idwith--resume, and fails a--resumeof an unknown id as Claude Code does. New tests: two--continueruns (the second with the spec prompt) resume the first id, recovery of a 0.1.4 attempt dir, the fallback without a transcript, and the fallback afterNo conversation found.
- The launcher resumes the attempt's lineage: the session whose transcript the last run wrote (
dispatch --wavecheckedwip_capagainst the same count for each task. The dry run printedwip 3/6for all four tasks of a wave, becausedecidecounted only the attempts in the snapshot. Now each task that the wave placed counts for the next one (wip 3/6,4/6, ...), in a dry run too, and a wave stops at the cap. New assertions intest_wip_cap_and_wave.
wavecoord 0.1.4
Fixed
- A task PR could change the fence and the lead config. Section 8 of
docs/design/edit-fence.mdsays that a fence mode change is a lead decision in a config PR, but nothing enforced it: a worker could commit"fence": "off"(or newclaude_flags,providers, amerge_cmd, a settings hook) and the merge put it on the default branch. Nowgate-checkand the refinery refuse a task PR (a PR withTask:,Attempt:andLease:lines) that changesfence,merge_cmd,check_cmd,protected_paths_cmd,providersorhosts[].claude_flags/envin.claude/wavecoord.json, the keyshooks,disableAllHooks,enabledPlugins,extraKnownMarketplacesorenvin.claude/settings.jsonor.claude/settings.local.json, or anyhooks/hooks.json. The violation kind isconfig_change, and the refinery reason isconfig_change, with a detail that tells the lead to make a plan or config PR. It blocks in themergemodesadvisoryandenforce(advisory mode measures the path fence; it does not let a worker turn the fence off), and is only reported in modeoff. The mode comes from the config on the base side. Plan PRs and lead PRs have no such lines and are not affected. New seeded defect D24 with the table checkconfig_change_check, and a refinery test. - Fence simulation flake: "journal not sent after a reachable call" under load. Seed 631187689 failed on Python 3.9 under heavy parallel load. The fence was right: the check answered but used the whole hook budget (1.5 s in the tests), so the journal flush had no time left, and the journal stayed complete for the next reachable call. The design allows this (section 4.4: only an acknowledged entry leaves the journal, and E3 refuses while it is not empty). The flush does not get its own budget slice, because that would make the edit tool call wait longer than the E1 budget. Assertion 5 now accepts a journal that stays only when the hook run's client got no answer, a request of the flush got no answer, or the budget ended before the flush (
fencesim.flush_deferred). A flush whose requests all got answers must still empty the journal, and the end of each run still needs one reachable call to send all of it. The hook now flushes the journal before the spool replay, because only the journal stops a push. New deterministic tests: a slow check that uses the budget (the journal stays whole, E3 refuses, the next call sends it), and a check that the tolerance does not cover a flush that kept acknowledged entries.
Added
- A report for a run that ran out of turns. Workers on non-Anthropic models through Anthropic-compatible endpoints (for example GLM) used about 1.5 to 2 times the planned turns and hit
error_max_turnsbefore they wrote the report, so the lead got "report invalid". Now, when the result iserror_max_turnsor the run hit its token budget, and the launcher pushed commits, the launcher writes a validfailedreport with the commits, the changed files,checks_runempty andplan_feedback: "continue: <n> commits pushed", and setscontinue_suggested: trueon the report request, the result and the attempt. - Planning guidance for turn budgets.
wave-plan(exec-plan.md,llm-risks.md): non-Anthropic providers need about 2 timesmax_turns, and the prompt should tell the worker to batch shell commands and not to read a file again./wavecoord:triage: oncontinue_suggested, continue the same attempt withwavecoord launch --continueand a short prompt that lists the acceptance commands. The worker rules (the appended system prompt) now say: when fewer than 15% of the turns remain, stop, commit and write the report.
wavecoord 0.1.3
Fixed
- The fence test oracle folded the wrong event log. CI on
main(macos-latest, Python 3.9) failedtest_fence_invariantfor seed 44 with six safety and integration failures and no fault. The fence and the server were right; the oracle was wrong. The oracle's fold cache (tests/fenceworld.py,ofold) was keyed byid(events). A process of the test pool runs several seeds, and the event list of seed 44 got the id of the freed list of an earlier seed. The oracle then extended that seed's fold with the events of seed 44, so it saw leases of another run and said that correct writes were notok(W). The same alias can also hide a real violation. Now the cache holds the list it folded and is used only for that same object with the same last event. The invariant predicate (docs/design/edit-fence.md, section 2.2) did not change. PR #11 did not cause the failure: the code before #11 fails the same way when the id is reused. The newOracleCacheTestchecks that a cached fold equals a fresh fold, that this check catches the old cache (seeded defect O1), and runs seed 44 after seed 5 in one process with a forced id reuse (the CI failure). - The override journal lost a write after a lost answer.
fence.journal_flushsends the journal with the idempotency keyfence-override:<nonce>:<first n>. When the first send was logged but its answer was lost (a fault), and a write was added to the journal before the retry, the retry had the same key. The server returned the first notice, and the client removed all entries of the larger batch, so the new write never reached the lead. Now only the entries that the acknowledged notice holds leave the journal (fence.acked_entries), and the flush sends again with a new key while it makes progress, so one reachable call sends the whole journal. Found by a 300-seed soak run (seed 72857574); the code before PR #11 has the same bug. New seeded defect D23 with the table checkjournal_retry_checkand the unit testtest_flush_retry_after_lost_answer_keeps_new_entries. - Fence simulation: the agent's config trick reached the default branch. The simulation's
trickoperation writesfence: "off"into the worktree copy of.claude/wavecoord.json(D13: the fence ignores it). A commit withgit add -Astaged it, and a merge put it on the default branch, so the lead's mode becameoffand the lead check expectedask(seed 289598702). The fence did what section 8 of the design says (the config on the default branch is the authority). The simulation keeps its config fixed, so it now keeps the trick file out of commits.
wavecoord 0.1.1
Fixed
- Placement and AUTH by provider. A host with no claude login but with the env file of a provider profile (mode 600) now counts as authenticated for an attempt of that profile. Placement is per attempt: a host can take it with the attempt's provider or with one of its
provider_fallbackprofiles (less the ones backed off after a rate limit), limited to the host'sproviderslist. The primary provider wins whenever an eligible host can run it; the most free slots, then the most free memory, rank hosts only within one provider rank. Before, only the first provider was looked at, so an attempt failed (or waited) when no host could run its first provider, although build hosts with free slots had the env file of its fallback. A host placed with a fallback runs that profile, and the rest of the chain stays its fallback. wavecoord hostsAUTH column. It showsprovider:<name>when the host has the env file ofdefault_provider, and the login check (logged-in,env,keychain?,no) otherwise. STATUS is checked against the host'sproviderslist.--jsonaddsauthanddispatchper host.- Report proposals are filed. On
report.postthe server files each item ofreport.proposals[]as aproposal.newevent (idempotent by<report idem>#p<i>; the task defaults to the attempt's task;sourceis the attempt id). Before,GET /api/proposals,plan_getand/wavecoord:revisedid not see them. - PRs merged or closed outside the refinery.
collect(and so each dispatcher loop tick) now reads the PR state of everyparkedlease's attempt with the newpr_state_cmd(defaultgh pr view {pr} --json state,mergedAt). A merged PR logsattempt.endmergedand releases the lease with reasonmerged; a PR closed without a merge logsattempt.endabandonedand releases the lease with reasonabandoned. Before, the lease stayedparkedand its exclusive reservations kept an overlapping task out ofready. Thecollectresult has a newparkedlist. - Skipped hosts are visible. The
dispatch.decidereason now names each host that placement skipped and why (for examplebuild1: unreachable: Permission denied (publickey)), and a fallback provider when one was used.
Added
install-server --env KEY=VALUE(repeatable) adds a variable to the unit's environment. The unit also carries this shell'sWAVECOORD_*variables (for exampleWAVECOORD_SSH,WAVECOORD_HOME), except worker variables and names that look like a secret;--no-carry-envturns that off. Before, a launchd or systemd server had noWAVECOORD_SSH, so its launcher could reach an ssh host only through a ControlMaster socket that a CLI run had opened, and placement fell back tolocal.dispatch: falseon a host (docs/adapters.md,schemas/config.schema.json): automatic placement never picks the host;--hostand thehostof thedispatchtool still do.
wavecoord 0.1.0
The first usable release: one lead session plans a wave in git, dispatches it to Claude Code workers on local or SSH hosts, and merges the results, with every coordination step in coord/log.
Added
- Plugin and marketplace.
claude plugin marketplace add jellologic/wavecoord,claude plugin install wavecoord@wavecoord. One stdlib Python zipapp (plugin/bin/wavecoord, Python 3.9+) is the server, the launcher, the hooks and the CLI. - Coordinator (
wavecoord serve): an append-only, hash-chained event log on the orphan branchcoord/log(group commit before ack, async push), a sqlite cache rebuilt from the log, leases with fencing epochs, path reservations, REST, SSE and MCP over HTTP on127.0.0.1:18741, bearer tokens with the rolesagent,lead,uiandgate. wavecoord install-server: copies the zipapp, pinned by its content hash, to~/.wavecoord/bin/and runs the server as a launchd agent (macOS) or asystemd --userunit (Linux).--dry-run,--no-start,--uninstall.- Plan store: task specs as Markdown files with a small YAML frontmatter on the default branch (
docs/task-spec.md), or a command adapter for an existing tracker.plan_editmakes atomic anchored edits on aplan/<n>branch and opens one PR. - Lead tools (MCP):
plan_ready,plan_get,plan_graph,plan_validate,plan_edit,dispatch,dispatch_wave,collect,attempts,attempt_get,conflicts,resolve,refinery_status,refinery_merge,propose,proposals,proposal_decide,inbox,ack,send,config. - Launcher: attempts in their own worktree and branch on local or SSH hosts, slot placement, a pinned plugin copy per host, push without force, a structured report validated against
schemas/report.schema.json, PRs opened on the lead machine withpr_cmd. - Provider profiles: workers on Anthropic-compatible endpoints from a mode-600 env file on each host; rate-limit backoff and fallback to the next provider.
- Conflicts and the refinery: merge-tree checks, resolver agents that continue the branch, a serialized merge queue in funnel order with a fresh merge-tree re-check, protected paths,
check_cmdandmerge_cmdpinned to the checked sha. - Feedback into the lead:
wavecoord events --follow --for leadfor a Monitor, inbox injection by the hooks, the experimentallead-feedchannel, and a watchdog for idle workers. - Hooks and git guards: heartbeats, inbox delivery, path checks before commit and push.
- The edit fence (
docs/design/edit-fence.md):fence: off|advisory|enforceper point (default advisory). A fail-closedPreToolUsedeny (onFailure: "block"),guard check --enforce, the launcher's own pre-push check, a fence verdict on each report,wavecoord gate-check <pr|range>for merge gates, the refinery's fence and stale-lease checks, the human-only offline override (wavecoord fence offline|online|status) with a logged journal, and reservation origins (a hot-file mark never widens a lease; an agent token may add only hot marks). Tested by a randomized invariant test with an independent oracle and 22 seeded defects. - Skills:
wave-plan,wave-run,triage,revise,resolve,coord-status; agentsplannerandreviewer. - Rollback:
wavecoord revert <seq>andwavecoord rebuild --at <sha>, with epochs that never go back. - Docs:
README.md,docs/quickstart.mdand the reference pages indocs/. - Localhost end-to-end test (
tests/e2e/test_wave.py): a real server, MCP calls as Claude makes them, a fakeclaudewith per-task modes, one wave from the plan PR to merged work, a resolved conflict, a provider fallback, a revert and a rollback, all checked incoord/logon the bare origin.
Fixed
- Workers on a local host used the lead's
~/.wavecoord/token(and an inherited plugin option token), so they acted with the lead role. They now use the host's agent token~/.wavecoord/hosts/<host>.tokenwhen it exists (docs/security.md).