docs: demonstrate cooperating-worker admission and cleanup

[flyingrobots]

Add a runnable launcher integration for two cooperating workers. Alice acquires two generated paths before mutation; Bob's overlapping launcher receives a refusal naming Alice and her note, while Bob's unrelated work completes. Deterministic gates retain Alice's live acquisition through that interaction.

The same example demonstrates renewal preserving acquisition identity, wrapper cleanup after renewal, a replacement surviving superseded cleanup, worker exit 17 releasing its reservation, and simulated TTL expiry while the command remains active. It retains JSONL command receipts and artifacts in a fresh isolated store. Partial file writes remain after failure; reservation cleanup is not rollback.

The runbook explains shared-artifact versus linked-worktree path meaning, the explicit store policy, and the lack of automatic renewal. It defines an external maintainer adoption experiment as unrun and schedules that evaluation after hardening and the unresolved #45 correctness gate. These controlled flows do not prove mixed-observation safety or establish external adoption. No production module or generated executable changed.

Validation on final head 834733721bf67973540e956d1ae83b3dce1acc2a:

• Observed RED before the example existed; the behavior oracle now passes against the real launchers and store.
• Normal pre-commit lint passed. Normal pre-push make test: 453 passed, 0 failed.
• The oracle checks admission/lifecycle identities, both reserved paths, holder/note refusal, absence of blocked mutation, unrelated progress, renewal/release, superseded cleanup, failure cleanup, simulated expiry and final store health. It validates lifecycle JSON against the public schema.
• A golden run uses an output path with spaces; an existing-output edge preserves a sentinel; two complete demonstrations run concurrently in separate stores. This is bounded stress of the example and isolation, not arbitrary-schedule fuzzing.
• recorded-run.json retains 30 schema-valid CLI records, artifacts and source hashes against implementation revision 29249ff9166e5be8b937c5fdcf63248edef1b241.

Run from this checkout:

./examples/cooperating-workers/demo.sh /tmp/locks-workers-review

Choose a fresh output directory. The executable example uses Bash and Git; Python is used only by the test oracle, with the existing jsonschema test dependency. See examples/cooperating-workers/README.md for the copyable runbook and experiment protocol.

Closes #40 for the runnable integration and adoption-experiment definition. External adoption remains untested, and #45 remains open.

[coderabbitai]

Warning

Review limit reached

Next included review available in 23 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: f0ef9c29-4700-4406-ae08-f9d3cfd6e9fa

📥 Commits

Reviewing files that changed from the base of the PR and between 01e39c3 and 8347337.

📒 Files selected for processing (9)

• CHANGELOG.md
• Makefile
• README.md
• examples/cooperating-workers/README.md
• examples/cooperating-workers/demo.sh
• examples/cooperating-workers/recorded-run.json
• examples/cooperating-workers/worker.sh
• test/cooperating-workers.py
• test/test.sh

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}