release: cut v0.3.0, and make the package prove it contains what the notes claim

[AetherAI3]

Rebased onto 426b124 (post-#98) and re-cut. Head is now e0f9458. Every figure below was re-measured against the new base — nothing was carried forward. See the "What changed on rebase" section at the end.

The problem

On 2026-08-20 this repository described five different releases at once, and nothing compared them:

Statement	Said
package.json	0.2.0
package-lock.json (both version fields)	0.1.0 — the #81 bump never touched it
RELEASE_NOTES.md top entry	a 0.2.0 whose feature list was written at 477f0fc, before #72
npm registry	0.1.0, the only version ever published
aether-agents-0.2.0.tgz committed in the repo root, #83 → #90	a build with no skills runtime in it at all

None of it was deliberate. The statements drifted apart because nothing asserted they had to agree.

Semver decision: 0.2.0 → 0.3.0 (minor)

#72 is a backwards-compatible feature addition the v0.2.0 notes never mention — a skills runtime, three new CLI commands (aether skills, aether capabilities, aether support-bundle), and six built-in skills shipped inside the package. Semver makes that a minor bump.

Reusing 0.2.0 was rejected on identity grounds, not style. 0.2.0 already names a specific dated artifact: the August 19 notes entry, the README availability paragraph, the install.sh pin example, and that committed tarball — whose contents predate the skills runtime entirely. Publishing different contents under the same version makes two materially different artifacts answer to one name, which is precisely the defect this release exists to close.

0.2.0 is retired unused. Nothing will ever be published under it.

Feature boundary: everything the v0.2.0 notes described (never shipped) plus 477f0fc..426b124 — 17 commits, 2026-08-19 08:39 EDT → 2026-08-22 11:12 EDT:

• 2 features: feat(skills): skill runtime, instruction resolver, capabilities and support bundle [SC-A0.1 + A0.2a] #72 (skills runtime and its three commands) and feat(cli): command registration seam, and the flags doctor never received #98 (command-registration seam, which also carries three user-visible fixes).
• 10 user-visible fix commits: fix(repo): validate and fetch a --repo mirror instead of reusing it blind [SC-A2.1] #73, fix(slash): /rollback stops accepting a count it never used, and stops lying about HEAD [SC-A3.1] #74, fix(brain): correlate Ollama tool results by id, generate schemas, stop faking steer [SC-A4.1] #75, fix(chat): thread the abort signal into local turns so Ctrl+C works [SC-A1.1] #77, fix(usage): make /limit a real stop boundary and stop reporting unknown spend as zero [SC-A5.1] #78, fix(repo): pin a --repo worktree to the fetched revision, refuse an unknown base #83, fix(runtime): async tool execution with process-tree teardown #84, fix(ollama): accept Ollama's own OLLAMA_HOST format, and keep the timeout armed through the body read #88, fix(agent): stop blocking CLI startup on an unbounded git status #89, fix(cloud): actually check the dev-session protocol version the server answers #91.
• 3 test-only: test(doctor): assert the hanging-backend property instead of a stopwatch #82, test(release): make the runnable release canaries executable gates #85, test(brain): canary 7 — local/Ollama parity, and the seam that makes it possible #87.
• 1 unwired module: feat(ship): executable pull-request rail, and canary 5 with it #86 (ship rail — no command invokes it, so it changes no behaviour in this release; its own commit message says so).
• 1 docs/hygiene: chore: tell the truth about what installs today, and clear scratch out of the repo root #90.

What this PR does

1. Reconciles the version — package.json, both package-lock.json version fields, and src/version.ts all say 0.3.0.
2. Rewrites the release surface — RELEASE_NOTES.md leads with v0.3.0; the v0.2.0 entry is marked superseded rather than rewritten, because it is the record of what was written that day, not an install instruction. New dated log at docs/releases/2026-08-22.md, indexed.
3. Keeps the availability language honest — README and the notes still say plainly that npm i -g aether-agents gives you 0.1.0, because it does.
4. Adds test/release_coherence.test.ts — a bidirectional gate (below).
5. Adds npm run release:candidate — runs the exact release.yml sequence before the tag exists.
6. Adds docs/releases/OPERATOR-PACKET-v0.3.0.md — the founder-owned publish sequence with digest, manifest, the unannounced-command list, and an explicit list of what is not proven.

The gate runs both directions

Gate A asserts every place naming the release names the same one — including both lockfile version fields, the drift nothing was watching.

Gate B (notes → package). For every feature the release notes claim, the code behind it must be in the file list npm pack would actually ship, and the command exposing it must be in the CLI registry. The source checkout's dist/ is not the package — the allowlist is dist/src plus four docs.

Gate C (package → notes). The inverse: a user-visible command that ships with no claim anywhere in the notes. That is the direction that actually keeps happening — it happened to this very PR while it was open, when #98 landed on main and the notes said nothing about it. Every non-hidden command in the CLI registry must now be announced by some release note, or named in SHIPPED_WITHOUT_A_NOTE with a reason. An explicit list is fine; silence is not.

The list is enforced in both directions — a stale entry fails, and an entry that is announced fails — so it cannot rot into a permanent bypass that quietly absorbs the next unannounced command. Every entry must also appear in the operator packet, because the founder cutting the tag is the person who needs to know what goes out unannounced. 15 commands are on it today; all predate the release log or were announced by capability in the June 2026 entry, and none is new in this release. login/logout are exempt by rule via the registry's own hidden flag.

Both mutations, measured at this base

Gate B — added "!dist/src/commands/skills.js" to the files allowlist, silently dropping aether skills from the tarball:

verify:production  ->  {"ok":true, ... "packedFiles":526}   MISSED IT
release_coherence  ->  FAIL: dist/src/commands/skills.js
                             (agent skills runtime - `aether skills`)

Gate C — added a command to the registry and mentioned it nowhere:

{ name: "teleport", args: "<dest>", summary: "beam the working tree somewhere",
  section: "System" }

verify:production  ->  {"ok":true, ... "packedFiles":527}   MISSED IT
release_coherence  ->  FAIL: no user-visible command ships without either a
                       release note or a named exemption
                       + [ 'teleport - beam the working tree somewhere' ]
                       - []

Both restored: 527 packed files, 10/10 pass. The pre-existing production gate caught neither, because it does not know what the notes promised and does not know what the registry exposes.

src/commands/cli_registry.ts is read-only for this lane. The Gate C mutation existed only in the working tree, was never committed, and the restore is verified by digest (md5 37b3f944…, git status src/ empty).

Evidence — npm run release:candidate, commit-bound

Run against 22aa02141fba158927cb1f01e4344cfa3e8f1a01 in a detached worktree of that commit, not the working checkout. commitBound: true, ok: true, exit 0:

PASS     commit-identity - 22aa02141fba158927cb1f01e4344cfa3e8f1a01
PASS     stage-commit - detached worktree of that commit
PASS     npm-ci-ignore-scripts - found 0 vulnerabilities
PASS     npm-audit-high - found 0 vulnerabilities
PASS     typecheck - tsc --noEmit exit 0
PASS     build - copied 18 built-in skill assets -> dist/src/skills/builtin
PASS     release-tests - 4 release test files, exit 0
NOT-RUN  npm-test - NOT RUN here. The full suite is release.yml's gate.
                    This report says nothing about it.
PASS     verify-production - {"ok":true,"package":"aether-agents","version":"0.3.0",
                             "packedFiles":527,"packedBytes":2459474,"workflows":3}
PASS     pack - aether-agents-0.3.0.tgz
                sha256:8c5c119d93cabf49af0c49c97addb055308d508af93f8675a26b6f5c8ecba307
PASS     install-tarball - <prefix>/node_modules/aether-agents
PASS     installed --version - 0.3.0
PASS     installed --help - 46 lines, lists skills, capabilities, resume, agent, doctor
PASS     installed skills list - aether/frontend-from-screenshot@1.0.0 builtin enabled ...
PASS     installed capabilities - instructions        supported
PASS     installed demo:handoff - independent test run in machine-b/slugify: green

RELEASE CANDIDATE OK

The last five lines all ran the binary npm install --global placed on disk from that exact tarball, in a clean prefix. The handoff demo's harness is not shipped (allowlist is dist/src plus four docs), so it is placed beside the installed package and resolves both the CLI and its own imports from the tarball's dist/src.

Tarball: aether-agents-0.3.0.tgz, 527 entries, 597,400 bytes packed / 2,459,474 unpacked, sha256:8c5c119d93cabf49af0c49c97addb055308d508af93f8675a26b6f5c8ecba307.

Registry / tag / release readings taken 2026-08-22, verbatim:

$ npm view aether-agents versions --json      ->  [ "0.1.0" ]
$ npm view aether-agents dist-tags --json     ->  { "latest": "0.1.0" }
$ gh release list -R AetherAI3/aether-agent   ->  (no output - zero releases)
$ git tag -l                                  ->  frozen-seam-v1, v0.1.0   (no v0.2.0)

What changed on rebase

main moved to 426b124 while this PR was open. The branch was rebased (trial-merge was clean; no conflicts) and everything was re-derived:

• The notes now cover feat(cli): command registration seam, and the flags doctor never received #98. Its user-visible half is three fixes, and the first is the exact failure class this codebase forbids: aether doctor --live never received --live. The argv parse is non-strict, so a flag a command had not declared was captured globally and stripped from what the command was handed — --live ran the fast configured-only report and exited 0, presenting a live end-to-end verification that was never performed. --deep, --dry-run, --no-ui and --only were lost the same way, and the whole --fix path was unreachable. Second: aether doctor --fix --yes replied "re-run with --yes" to someone who had just passed it. Third: command lookup lowercased the token while dispatch was case-sensitive, so aether Vault fell past the typo guard into a chat turn and billed a paid model call.
• The digest changed, and that is the correct outcome. The earlier candidate at a63e1c6e produced 25f33524… over 524 entries. feat(cli): command registration seam, and the flags doctor never received #98 added dist/src/core/command_dispatch.* and rewrote main.js, so the packed content genuinely differs. A digest that had survived that change would have meant the pack was not reading the tree.
• Both mutation checks were re-run, not carried forward. I had initially edited the Gate B figure from 523 to 526 by inference; that is a number nobody measured, so it was re-run before being written down.
• Gate B now reads the registry by importing it, not by regex over its source. feat(cli): command registration seam, and the flags doctor never received #98 replaced "reachability asserted by a regex over main.ts" for exactly this reason, and it immediately split the commands across CLI_COMMANDS and DISPATCH_COMMANDS — a source regex keyed on one array would have silently stopped covering the other. doctor is in the second one.
• A miscount was fixed while re-deriving: the packet said "9 user-visible fixes" over a list of ten.

Explicitly NOT proven

Named as unproven rather than omitted:

• npm availability of 0.3.0. Nothing here contacted the registry to publish. This lane created no tag and published nothing.
• The full npm test suite locally. The candidate runs the release-owned test files only and reports npm-test as not-run with a reason — it can never read as a green tick. A tool_executor test does not return on this Windows box; CI's reading is the authority, and CI is green at this head.
• Cross-machine tarball reproducibility. The digest is what this machine produced, recorded so a CI-built tarball can be compared against it. It is deliberately not asserted to be byte-identical elsewhere.
• npm audit is a reading at pack time, not a standing property.
• That this range is final. feat(review): structured repository state, and a verification that knows what it verified #93, feat(review): select, stage, unstage, revert and commit exactly what was chosen #94, feat(ship): publish HEAD and only HEAD, and bind the work to what carries it #95, feat(review): the one writer for a verification record, and the one condition it writes under #97, feat(sessions): project continuity and the session library (AA-CONT-04) #99, feat(skills): put skills and AGENTS.md inside real runs, and enforce their policy #100, feat(review): line counts beside the state, not inside it #101 and feat(review): the review to commit to pull request rail, reachable as a command #102 are open and expected to land before a tag is cut. Each one moves the range and the digest — which is why §6.2 of the packet re-runs the candidate on the merge commit rather than trusting this PR's digest, and why Gate C exists.

Shared-file collisions

None committed. src/main.ts and src/commands/cli_registry.ts are not modified by this PR — this lane registers no command. The registry was read (Gate B/C import it) and temporarily mutated in the working tree for the Gate C mutation proof, then restored byte-identical and verified by digest before committing.

Every changed file is inside the AA-REL-01 lease:

package.json  package-lock.json  src/version.ts  README.md  RELEASE_NOTES.md
docs/releases/{README.md, 2026-08-22.md, OPERATOR-PACKET-v0.3.0.md}
scripts/{release-candidate.ts, verify-production.ts}
test/{release_coherence.test.ts, release_canaries.test.ts}

scripts/verify-production.ts gained exactly one thing: createPackReport is now exported, so a gate reasoning about what a user receives asks npm instead of reading the build directory. No policy was weakened — the allowlist, audit, provenance and exact-tarball smoke test in release.yml are untouched.

test/release_canaries.test.ts had a coverage map claiming canaries 5 and 7 were unwritable. #86 and #87 wrote them two commits later; the excuse outlived the condition. The map is now enforced by a test that reads the delegated files rather than asserted in a comment.

Founder-owned — this PR does none of it

1. Merge this PR; note the merge SHA.
2. Re-run npm run release:candidate on the merge commit and confirm ok: true, commitBound: true. Do not tag against this PR's digest — the base is still moving.
3. git tag -a v0.3.0 <merge-sha> and push it.
4. Publish a GitHub release for v0.3.0 — publication, not tag creation, triggers release.yml.
5. Confirm the npm-production environment exists and NPM_TOKEN is set before publishing the release, or the run fails after the release is already public.
6. Verify availability from the registry itself, not the workflow log.
7. Only then update the availability language — test/release_coherence.test.ts enforces that the claim cannot be added without the registry actually serving it.

Full detail: docs/releases/OPERATOR-PACKET-v0.3.0.md.

No Aether credential, npm token or GitHub token was used, read, or written by any part of this work.

🤖 Generated with Claude Code

[AetherAI3]

CI closes the one thing the local candidate reported as not-run.

All four required checks green on 02a8aa8, plus CodeQL:

Check	Result
Test (ubuntu-latest)	pass, 35s
Test (windows-latest)	pass, 1m9s
analyze	pass, 1m21s
supply-chain	pass, 16s
CodeQL	pass

Those Test jobs run the full npm test suite — the step the release-candidate report deliberately marked NOT-RUN on this Windows box rather than guessing at. It is now read from the authority, not from a local skip.

mergeStateStatus: CLEAN. Not merging — this is a release cut and the tag/publish steps after it are founder-owned.

[AetherAI3]

Rebased onto 426b124 (post-#98) and re-cut. Head is now e0f9458; the body has been rewritten so every figure in it was measured at this base rather than carried forward.

All five checks green at e0f9458 — these readings are at the exact ref, not the pre-rebase one:

Check	Result
Test (ubuntu-latest)	pass, 30s
Test (windows-latest)	pass, 2m18s
analyze	pass, 1m23s
supply-chain	pass, 14s
CodeQL	pass

mergeStateStatus: CLEAN, mergeable: MERGEABLE.

Two things worth flagging to a reviewer:

The digest changed and that is correct. 25f33524… / 524 entries → 8c5c119d… / 527 entries. #98 added dist/src/core/command_dispatch.* and rewrote main.js, so the packed content genuinely differs. A digest that had survived that would have meant the pack was not reading the tree.

Gate C is the new direction. Gate B caught a note promising something the package lacks. It could not see a command shipping with no note at all — which is what #98 just did to this very PR. Both directions are now enforced, both mutation-proven at this base, and verify:production caught neither mutation.

Still not merging. Tag and publish remain founder-owned, and #93/#94/#95/#97/#99/#100/#101/#102 are all expected to land first — each one moves the range and the digest again, which is why step 2 of the packet re-runs the candidate on the merge commit instead of trusting this PR's number.

[AetherAI3]

MERGE-TRAIN STATE — HELD (2026-08-22T15:56Z)

Head: e0f94587dfae6876ba7cf7b92799956a9f36a537; base/main: 426b12464c2a19549f421adb43348f83d028628e.

Evidence: required Ubuntu, Windows, supply-chain, and CodeQL checks passed on this exact head. Independent release review found the recorded release:candidate artifact/digest is bound to ancestor 22aa02141fba158927cb1f01e4344cfa3e8f1a01, not this final head. No tag, GitHub release, or npm publication is authorized.

Owner: release PR branch writer. Next legal action: run npm run release:candidate on the frozen final head (or exact merge candidate), retain a successful commitBound:true report, then re-fetch head/base/checks and obtain a fresh merge decision.