Fix stale-cache proof race and consolidate release preparation

CHANGELOG.md

@@ -1,9 +1,15 @@
 
 # Changelog
 
+## Unreleased
+
+- **Release preparation.** Document batching pending consumer changes before review and merging repository-only maintenance without publishing unchanged packages.
+- **Beads worker setup.** Document matching ATS and Beads actor identities for claiming and completing owned issues.
+- **Cache refresh validation.** Wait for the refreshed corpus and lease cleanup together in the stale-cache CLI proof, preserving the bounded deadline and final cleanup assertion.
+
 ## 0.17.0 - Beads ready work, atomic claims and native dependencies
 
-Unreleased.
+Released 2026-10-03.
 
 - **Ready retrieval.** `ats tasks ready` lists blocker-aware ready work through Beads. Matching ready issues add a scoped `ready` branch to RRF search; failures retain healthy results and report degradation. Project-name scopes also retain native results whose project id was resolved from the corpus.
 - **Explicit claims.** `ats update PROJECT ISSUE --claim --agent NAME` delegates to an atomic Beads claim, verifies the owner, and supports same-actor retries. Claims honor review requirements and cannot be combined with field patches.

README.md

@@ -148,11 +148,14 @@ Run ATS inside the repository containing `.beads`; its directory name is the def
 ```bash
 cd /path/to/my-repo
 ats config use beads
+export ATS_AGENT_ID=worker-a BEADS_ACTOR=worker-a
 ats tasks ready --json
-ats update my-repo ISSUE --claim --agent worker-a
+ats update my-repo ISSUE --claim
 ats link add my-repo ISSUE my-repo PREREQUISITE --type depends-on --native --dry-run
 ```
 
+Use the same worker name for `ATS_AGENT_ID` and `BEADS_ACTOR`; Beads checks the claiming actor again when a claimed issue is completed.
+
 From another directory, use `ATS_ADAPTER=@reneza/ats-adapter-beads ATS_BEADS_ROOT=/path/to/my-repo ATS_BEADS_PROJECT_ID=my-repo ats tasks ready --json`. Ready work contributes a named RRF branch; claims and native dependency writes use the existing review gate. See the [Beads adapter guide](packages/adapter-beads/README.md) for worker identities, dependency semantics, and the real CLI proof.
 
 ## Tradeoffs and limits
@@ -360,7 +363,7 @@ so it stops re-reading the whole tree each session.
 
 ## Releases and license
 
-**v0.16.0** adds scoped native-search pagination, HTTP deadlines and cancellation, per-project failure reporting, safe mutation retries, bound create and batch replay keys, and reviewed fact freshness with separate source and learned dates. Full history: [`CHANGELOG.md`](CHANGELOG.md).
+**v0.17.0** adds blocker-aware Beads ready retrieval, named atomic claims, native dependency writes, and real CLI concurrency checks. It also fixes named undo selection and refreshes compatible dependencies. Full history: [`CHANGELOG.md`](CHANGELOG.md).
 
 MIT. See [LICENSE](LICENSE).
 

docs/releasing.md

@@ -4,6 +4,21 @@ ATS is a JavaScript npm-workspaces monorepo. Publish its public npm packages,
 the existing MCP server manifest, and one matching GitHub Release. The private
 workspace is excluded. There is no Python distribution.
 
+## Prepare one complete batch
+
+Documentation, tests, and CI maintenance can merge without a version bump or
+registry publication when the published package contents and consumer behavior
+are unchanged. A merge is not itself a reason to publish.
+
+Before preparing a version bump, inventory the remaining consumer changes,
+known release blockers, and adapter integration work. Consolidate the changes
+that belong in the release into one PR, then finish the repository gates,
+package-content checks, and consumer smoke tests before requesting final review.
+Record the package versions and registry destinations for that complete batch;
+avoid publishing successive small releases while related work is still pending.
+
+## Publish the reviewed batch
+
 Before publishing, the release PR must be reviewed and accepted at its final
 commit. Merge the reviewed commit, then use a clean checkout of that merged
 revision. A changed PR needs another review. No registry publication belongs

packages/cli/test/find-stale.test.js

@@ -78,13 +78,14 @@ test('find answers from the stale cache and the background refresh lands', async
   assert.equal(out.corpus.revalidating, true);
   assert.equal(out.tasks[0].id, 'old1', 'served the stale copy without blocking');
 
-  // The detached `ats cache sync` rewrites the cache with the adapter's current corpus.
+  // The detached worker writes the corpus before its finally block releases the lease.
+  // Wait for both conditions so a successful write cannot race the cleanup assertion.
   let refreshed = null;
   for (let i = 0; i < 50 && !refreshed; i++) {
     await wait(100);
     try {
       const raw = JSON.parse(fs.readFileSync(cachePath, 'utf8'));
-      if (raw.tasks?.[0]?.id === 't1') refreshed = raw;
+      if (raw.tasks?.[0]?.id === 't1' && !fs.existsSync(`${cachePath}.refreshing`)) refreshed = raw;
     } catch {}
   }
   assert.ok(refreshed, 'background refresh rewrote the cache');