worktree-controller 1.30.4__tar.gz → 1.30.6__tar.gz

worktree_controller-1.30.6/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: worktree-controller
+Version: 1.30.6
+Summary: Govern Git worktree budgets, authority, ownership, and lifecycle
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: websockets>=15,<16
+Requires-Python: >=3.12, <3.13
+Project-URL: Homepage, https://github.com/xuanheng-tech/worktree-controller
+Project-URL: Documentation, https://github.com/xuanheng-tech/worktree-controller/blob/main/README.md
+Project-URL: Repository, https://github.com/xuanheng-tech/worktree-controller
+Project-URL: Issues, https://github.com/xuanheng-tech/worktree-controller/issues
+Project-URL: Changelog, https://github.com/xuanheng-tech/worktree-controller/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# Worktree Controller
+
+Worktree Controller (WC) helps people and AI agents share a Git repository without losing track of
+who owns each working directory, what it may change, and whether it is safe to close.
+It checks repository policy before allocating a worktree, grants writing authority to a live
+process, and records handoff, integration, recovery and release evidence. Git remains the source
+of truth for files, branches, commits and registered worktrees.
+
+**Current release: 1.30.6 · Linux · Python 3.12 · Apache-2.0**
+
+## Install
+
+Use a virtual environment in a new directory:
+
+```bash
+python3.12 -m venv .venv
+. .venv/bin/activate
+python -m pip install worktree-controller==1.30.6
+worktree-controller --version
+worktree-controller capabilities --json
+```
+
+WC requires Git and readable Linux `/proc`. Other operating systems and Python versions are not
+supported by this release. Its one runtime dependency is `websockets>=15,<16`.
+On Ubuntu, if creating the environment reports that `ensurepip` is unavailable, install the
+distribution's `python3.12-venv` package first (for example, `sudo apt install python3.12-venv`).
+Software version 1.30.6 retains CLI contract **60** and storage layout **5**.
+
+## Try it in a disposable repository
+
+With the environment above active:
+
+```bash
+git clone https://github.com/xuanheng-tech/worktree-controller.git wc
+cd wc
+git checkout v1.30.6
+python examples/quickstart.py --workspace "$HOME/wc-first-run"
+```
+
+The workspace path must not exist; its parent must already exist. The example creates its own
+repository and isolated HOME, uses no credentials or remote, and leaves existing projects alone.
+It runs a small inspection task: admit a worktree, bind a live writer, check permission, observe an
+expected wrong-owner refusal, inspect recovery guidance, and formally close the unchanged task.
+On success it prints `PASS`, releases the linked checkout through WC, and keeps the repository,
+branch and command log. On failure it stops and preserves results for inspection.
+
+The [getting started guide](https://github.com/xuanheng-tech/worktree-controller/blob/main/docs/getting-started.md)
+explains the output and how to proceed to tasks that change files. The example also ships in the
+source distribution; it requires only WC and Git, with no companion delivery tools.
+
+To actually change a file, publish to a local bare remote, integrate and recover a paused task,
+follow [your first change](https://github.com/xuanheng-tech/worktree-controller/blob/main/docs/first-change.md).
+That complete example additionally uses public Git Finalizer and Snapshot Runner installations.
+
+## Use WC in a real project
+
+A governed repository tracks `.agents/worktree-policy.toml` and registers its checkouts with WC.
+Start with read-only `status` and `doctor`; adopt existing checkouts explicitly rather than
+assuming that a clean directory is unowned. Follow the
+[operations guide](https://github.com/xuanheng-tech/worktree-controller/blob/main/docs/operations.md)
+for task admission, writer identity, handoff, integration and safe release.
+
+WC manages checkout authority and lifecycle. It does not implement your task, commit changes or
+publish a branch. Real handoff and integration flows use separate delivery evidence from
+[Git Finalizer](https://github.com/xuanheng-tech/git-finalizer).
+Context Loader and the maintenance checker are optional. The complete integration example uses
+Snapshot Runner for the explicit review receipts required by its policy; see
+[optional integrations](https://github.com/xuanheng-tech/worktree-controller/blob/main/docs/reference.md#optional-integrations-and-dependencies).
+
+When blocked, run `worktree-controller recovery-guide --repo /path/to/repo --path /path/to/checkout --json`
+and follow the state-specific guidance. Preserve unfinished changes and unknown files.
+At session end, use the full recorded session identity and check every allocation's result;
+a successful process exit alone does not prove that all worktrees are settled.
+
+## Documentation and help
+
+- [Getting started](https://github.com/xuanheng-tech/worktree-controller/blob/main/docs/getting-started.md)
+- [Operations and recovery](https://github.com/xuanheng-tech/worktree-controller/blob/main/docs/operations.md)
+- [Technical reference](https://github.com/xuanheng-tech/worktree-controller/blob/main/docs/reference.md)
+- [Architecture](https://github.com/xuanheng-tech/worktree-controller/blob/main/docs/architecture.md)
+- [Exact CLI and capability contract](https://github.com/xuanheng-tech/worktree-controller/blob/main/tool_cli_contract.json)
+- [Changelog](https://github.com/xuanheng-tech/worktree-controller/blob/main/CHANGELOG.md)
+- [Publishing and recovery](https://github.com/xuanheng-tech/worktree-controller/blob/main/docs/publishing.md)
+- [Releases](https://github.com/xuanheng-tech/worktree-controller/releases) · [PyPI](https://pypi.org/project/worktree-controller/)
+- [Report a bug](https://github.com/xuanheng-tech/worktree-controller/issues) · [Contribute](https://github.com/xuanheng-tech/worktree-controller/blob/main/CONTRIBUTING.md)
+- [Report a security issue](https://github.com/xuanheng-tech/worktree-controller/blob/main/SECURITY.md)
+
+Licensed under the [Apache License 2.0](https://github.com/xuanheng-tech/worktree-controller/blob/main/LICENSE).

worktree_controller-1.30.6/README.md

@@ -0,0 +1,88 @@
+# Worktree Controller
+
+Worktree Controller (WC) helps people and AI agents share a Git repository without losing track of
+who owns each working directory, what it may change, and whether it is safe to close.
+It checks repository policy before allocating a worktree, grants writing authority to a live
+process, and records handoff, integration, recovery and release evidence. Git remains the source
+of truth for files, branches, commits and registered worktrees.
+
+**Current release: 1.30.6 · Linux · Python 3.12 · Apache-2.0**
+
+## Install
+
+Use a virtual environment in a new directory:
+
+```bash
+python3.12 -m venv .venv
+. .venv/bin/activate
+python -m pip install worktree-controller==1.30.6
+worktree-controller --version
+worktree-controller capabilities --json
+```
+
+WC requires Git and readable Linux `/proc`. Other operating systems and Python versions are not
+supported by this release. Its one runtime dependency is `websockets>=15,<16`.
+On Ubuntu, if creating the environment reports that `ensurepip` is unavailable, install the
+distribution's `python3.12-venv` package first (for example, `sudo apt install python3.12-venv`).
+Software version 1.30.6 retains CLI contract **60** and storage layout **5**.
+
+## Try it in a disposable repository
+
+With the environment above active:
+
+```bash
+git clone https://github.com/xuanheng-tech/worktree-controller.git wc
+cd wc
+git checkout v1.30.6
+python examples/quickstart.py --workspace "$HOME/wc-first-run"
+```
+
+The workspace path must not exist; its parent must already exist. The example creates its own
+repository and isolated HOME, uses no credentials or remote, and leaves existing projects alone.
+It runs a small inspection task: admit a worktree, bind a live writer, check permission, observe an
+expected wrong-owner refusal, inspect recovery guidance, and formally close the unchanged task.
+On success it prints `PASS`, releases the linked checkout through WC, and keeps the repository,
+branch and command log. On failure it stops and preserves results for inspection.
+
+The [getting started guide](https://github.com/xuanheng-tech/worktree-controller/blob/main/docs/getting-started.md)
+explains the output and how to proceed to tasks that change files. The example also ships in the
+source distribution; it requires only WC and Git, with no companion delivery tools.
+
+To actually change a file, publish to a local bare remote, integrate and recover a paused task,
+follow [your first change](https://github.com/xuanheng-tech/worktree-controller/blob/main/docs/first-change.md).
+That complete example additionally uses public Git Finalizer and Snapshot Runner installations.
+
+## Use WC in a real project
+
+A governed repository tracks `.agents/worktree-policy.toml` and registers its checkouts with WC.
+Start with read-only `status` and `doctor`; adopt existing checkouts explicitly rather than
+assuming that a clean directory is unowned. Follow the
+[operations guide](https://github.com/xuanheng-tech/worktree-controller/blob/main/docs/operations.md)
+for task admission, writer identity, handoff, integration and safe release.
+
+WC manages checkout authority and lifecycle. It does not implement your task, commit changes or
+publish a branch. Real handoff and integration flows use separate delivery evidence from
+[Git Finalizer](https://github.com/xuanheng-tech/git-finalizer).
+Context Loader and the maintenance checker are optional. The complete integration example uses
+Snapshot Runner for the explicit review receipts required by its policy; see
+[optional integrations](https://github.com/xuanheng-tech/worktree-controller/blob/main/docs/reference.md#optional-integrations-and-dependencies).
+
+When blocked, run `worktree-controller recovery-guide --repo /path/to/repo --path /path/to/checkout --json`
+and follow the state-specific guidance. Preserve unfinished changes and unknown files.
+At session end, use the full recorded session identity and check every allocation's result;
+a successful process exit alone does not prove that all worktrees are settled.
+
+## Documentation and help
+
+- [Getting started](https://github.com/xuanheng-tech/worktree-controller/blob/main/docs/getting-started.md)
+- [Operations and recovery](https://github.com/xuanheng-tech/worktree-controller/blob/main/docs/operations.md)
+- [Technical reference](https://github.com/xuanheng-tech/worktree-controller/blob/main/docs/reference.md)
+- [Architecture](https://github.com/xuanheng-tech/worktree-controller/blob/main/docs/architecture.md)
+- [Exact CLI and capability contract](https://github.com/xuanheng-tech/worktree-controller/blob/main/tool_cli_contract.json)
+- [Changelog](https://github.com/xuanheng-tech/worktree-controller/blob/main/CHANGELOG.md)
+- [Publishing and recovery](https://github.com/xuanheng-tech/worktree-controller/blob/main/docs/publishing.md)
+- [Releases](https://github.com/xuanheng-tech/worktree-controller/releases) · [PyPI](https://pypi.org/project/worktree-controller/)
+- [Report a bug](https://github.com/xuanheng-tech/worktree-controller/issues) · [Contribute](https://github.com/xuanheng-tech/worktree-controller/blob/main/CONTRIBUTING.md)
+- [Report a security issue](https://github.com/xuanheng-tech/worktree-controller/blob/main/SECURITY.md)
+
+Licensed under the [Apache License 2.0](https://github.com/xuanheng-tech/worktree-controller/blob/main/LICENSE).

worktree_controller-1.30.6/docs/architecture.md

@@ -0,0 +1,78 @@
+# Architecture and maintenance boundaries
+
+The Controller adds authority and lifecycle to Git facts. It does not replace Git, the caller's
+test/review evidence, or Git Finalizer publication. See [operations](operations.md) for the normal
+development and recovery paths; exact public interfaces live in the [contract](../tool_cli_contract.json).
+
+## Responsibilities
+
+| Area | Existing implementation | Invariant |
+| --- | --- | --- |
+| CLI parsing and routing | `cli.py`, command modules | Dispatch explicit operations; do not duplicate authority decisions |
+| Git observations and mutations | `git_backend.py` | Git owns registrations, refs, paths, HEAD and cleanliness |
+| State and durable evidence | `models.py`, `store.py`, `metadata_codec.py` | Validate stored identities; serialize mutations under the repository lock |
+| Shared identity and semantic checks | `semantics.py` | Consume the caller's snapshot; do not acquire authority or write metadata |
+| Budget admission | `resource_admission.py` | Preserve durable request identity and host reservations across retries |
+| Writer entitlement | `writer_lease.py`, `writer_session.py`, `governance.py` | Bind the real process identity and exact operation/target |
+| Lifecycle orchestration | `lifecycle.py` and focused recovery modules | Compose existing guards and append durable transition evidence |
+| Environment and resource inspection | `environment.py`, `disposable.py`, preservation modules | Incomplete observation blocks dependent deletion; unknown content is retained |
+| Publication execution | `publication_execution.py` and Finalizer protocol | Exact candidate, validation, lease and current remote main must agree |
+| Idle-work maintenance | `convergence.py`, `reconciler.py` | Only delegated authority closes eligible unused allocations |
+
+This is a responsibility map, not a claim of an acyclic module graph. Lifecycle orchestration
+still imports and is imported by focused modules, including deferred imports. New code should use
+the narrow existing owner of a guard instead of importing lifecycle merely to look up a record.
+
+`semantics.record_for`, `managed_record` and `assert_record_version` are internal shared helpers.
+They preserve binding lookup, Git registration checks and allocation/version CAS errors. They do
+not refresh a snapshot or establish a transaction. A mutation caller must retain its existing
+repository lock and apply the relevant role, owner, lifecycle, resource and runtime checks.
+Compatibility aliases in lifecycle/controller keep existing internal call sites usable; new
+consumers should import the shared helpers directly.
+
+## Durable state and recovery
+
+Resolve the repository's actual Git common directory; a linked checkout's `.git` can be a file.
+Controller Git commands drop inherited repository selection (`GIT_DIR`, `GIT_INDEX_FILE` and the
+other variables in `git_backend.REPOSITORY_SELECTION_ENVIRONMENT`). A worktree key is derived
+from the Git administrative directory name, which Git reuses after a removal; a linked binding
+therefore also carries a `worktree-registration/v1` token that must match the marker inside that
+administrative directory. `MetadataStore` withdraws a mismatched binding for every consumer and
+reports `BINDING_IDENTITY_DRIFT`; new binding writers pass the registration to `write_record`.
+Bindings that predate registrations gain one only through `registration_backfill`, which ties
+them to the live registration on matching Git and record evidence and writes nothing else.
+Every directory under the metadata root is a `MetadataStore` attribute declared in the layout
+contract; a listing failure other than absence fails closed.
+The `worktree-controller/v1` namespace suffix is not its storage layout version. Repository
+metadata and host admission reservations have separate locks and identities. Never infer an
+allocation, completed cleanup, publication or release from a missing path or a clean Git status.
+
+Before changing a transition, follow its ordinary path and its interrupted path: persisted request,
+allocation, frozen handoff, integration preparation, validation, publication and release receipts.
+Use typed recovery entries for partial operations. Preserve the original request and evidence;
+an error explanation must not silently substitute a new intent or relax the original guard.
+
+## Validation and future changes
+
+Start with regressions for the observed failure and its unchanged refusal boundary. For shared
+authority checks, cover both successful callers and the error taxonomy. Use `check-shards` for
+the parallel integration gate and `check-project` for the complete package/release gate. Build
+and installed smoke results are distinct from a live external client's behavior.
+
+History growth should be measured with `scripts/benchmark-cli` before changing storage. Compare
+pinned executables on the same synthetic fixtures, alternating repeated calls, and retain the
+history sizes, timing, peak RSS and cache limitations. A faster lookup must not skip fresh evidence
+validation or introduce a second authoritative state store. Indexing or additional caching needs
+a demonstrated bottleneck and explicit invalidation/recovery tests.
+
+Runtime scans that gate deletion read every same-UID process. Positive references and read
+failures other than permission denial block; a permission-denied same-UID process without a
+verified holder association is a host visibility gap (for example a non-dumpable service
+manager), reported by typed cleanup and tolerated by release. Both scans require the checkout to
+keep one path and inode for the whole scan. The strict scan, which also refuses visibility gaps,
+is for consumers that must prove complete visibility.
+
+Further lifecycle extraction should follow one cohesive transition at a time, keeping its lock
+scope and immutable evidence together. Avoid moving mutation helpers that depend on lifecycle's
+clock, transaction state or caller-specific guards merely to reduce a line count. Public CLI,
+capability and storage changes require their own version and compatibility review.

worktree_controller-1.30.6/docs/first-change.md

@@ -0,0 +1,140 @@
+# Deliver your first change
+
+This example changes one README, commits and publishes its branch through Git Finalizer, hands
+it off to WC, reviews and validates an integration candidate, and publishes local main. It can
+pause after handoff and continue in a new process with the original task and integration request.
+It creates a **local bare Git remote**, never contacts a hosting service, and needs no credentials.
+Use a disposable workspace; do not point it at an existing project.
+
+## Install the example's tools
+
+WC itself needs Linux, Python 3.12, Git and readable `/proc`. Install the released version using
+the [README](../README.md#install). On Ubuntu, a Python installation without `ensurepip` also
+needs its distribution's `python3.12-venv` package before `python3.12 -m venv` can work.
+
+This complete delivery example also uses these public tools:
+
+- [Git Finalizer 1.9.3](https://github.com/xuanheng-tech/git-finalizer#installation): download its
+  published release tarball and checksum file, verify them, and keep all `git-finalize*` companions
+  together as its installation instructions describe. It is not a PyPI package.
+- [Snapshot Runner 2.5.11](https://github.com/xuanheng-tech/snapshot-runner#requirements-and-installation):
+  install its PyPI package in a separate virtual environment. Its own interpreter needs
+  Python 3.12.13 or a later supported version; using Python 3.12.13+ for both environments meets
+  WC's Python 3.12 requirement too. WC's core Python requirement is unchanged.
+
+For example, with a suitable Python 3.12 already installed and a new `runner-venv` path:
+
+```bash
+python3.12 --version
+python3.12 -m venv /absolute/path/to/runner-venv
+/absolute/path/to/runner-venv/bin/python -m pip install 'snapshot-runner==2.5.11'
+```
+
+Use the WC environment's Python to run the example. Pass the two installed entrypoints
+explicitly, or put their directories on PATH. `tool-skill-sync`, Context Loader, agent clients,
+model APIs and personal Skills are not required by this example.
+
+WC policy schema 4 and newer requires separate explicit **test and Snapshot receipt identities**
+at `integration-validate`. The example creates real Snapshot Runner artifacts and reads their
+README evidence; it checks the expected README content and clean candidate separately. A tool's
+successful evidence collection alone is not a passed test or code review. No fake receipt, lowered
+policy version or changed Controller state is used.
+
+## Run the whole task
+
+From this release's source checkout, with the WC environment active:
+
+```bash
+python examples/change_task.py --workspace "$HOME/wc-first-change" \
+  --finalizer /absolute/path/to/git-finalize \
+  --snapshot-runner /absolute/path/to/runner-venv/bin/snapshot-runner
+```
+
+The workspace path must be new and its parent must exist. The script refuses an existing path
+without changing it. The source archive includes both `change_task.py` and its neighboring
+`quickstart.py`; keep them together. Missing tools are refused before the workspace is created.
+
+`PASS` means all of the following were checked:
+
+1. The admitted feature's real writer passed the write guard before changing `README.md`.
+2. The exact file scope was reviewed, committed and published to the local remote with Finalizer.
+3. The writer ended and its exact commit was handed off, then queued and claimed through WC.
+4. Tests and Snapshot evidence were bound to the candidate before its main-publication lease.
+5. Finalizer and WC independently verified the published commit; WC released both linked checkouts.
+6. Canonical main was refreshed, the delivered README was checked, strict closeout proof covered
+   both known allocations, and `doctor` passed.
+
+The example intentionally changes only a known text file, so its content review is narrow and
+deterministic. Real application changes need their own tests and appropriate review.
+This local demonstration does not authorize a hosted publication or production deployment.
+
+## Pause and resume the same task
+
+Use a different new workspace for this exercise:
+
+```bash
+python examples/change_task.py --workspace "$HOME/wc-change-resume" \
+  --finalizer /absolute/path/to/git-finalize \
+  --snapshot-runner /absolute/path/to/runner-venv/bin/snapshot-runner \
+  --pause-after-handoff
+```
+
+The output is **`PAUSED`**, not `PASS`. The change and its branch have reached the local remote,
+the feature writer is released, and `handoff.json` records the original task's source, repository
+and integration identities. The integration is queued, with no candidate checkout yet.
+The preserved source is still awaiting integration; this is not completed business work.
+
+Run in a new process with the **same** workspace and installed tools:
+
+```bash
+python examples/change_task.py --workspace "$HOME/wc-change-resume" \
+  --finalizer /absolute/path/to/git-finalize \
+  --snapshot-runner /absolute/path/to/runner-venv/bin/snapshot-runner --resume
+```
+
+Resume checks the existing repository, local remote, source identity and uncommitted files. It
+claims the original queued intent, or observes the same unchanged claimed candidate. It does not
+create another task, replace source evidence, reset a branch or delete unknown files. Repeating
+resume after verified completion only rechecks the delivered result and closeout evidence.
+
+## Inspect a failure and keep the evidence
+
+Every command's actual exit code, stdout and stderr is saved in `commands.jsonl`. The workspace
+also retains Finalizer receipts, Snapshot summaries and artifacts, content-check results, branches,
+the local remote and final `closeout.json`. Linked checkouts are removed only through WC.
+
+An unexpected refusal stops with nonzero exit status and preserves the current result. This
+example's resume entry covers queued or unchanged claimed handoffs and verified completion;
+it is not a general crash-recovery engine. For a different interruption point, unknown files,
+identity drift or a publication in progress, inspect the saved command and the formal
+[recovery guidance](operations.md#recovery-guidance-and-session-closeout). Do not rerun without
+`--resume` into an old workspace or clear metadata to make the example continue.
+
+The isolated state is under the workspace's `home/`. For inspection, activate the WC environment
+and use the actual workspace path:
+
+```bash
+workspace="$HOME/wc-change-resume"
+HOME="$workspace/home" XDG_STATE_HOME="$workspace/home/.local/state" \
+  worktree-controller status --repo "$workspace/main" --json
+```
+
+Use the original `intent_id` from `handoff.json` with `recovery-guide --intent-id` even after a
+checkout is released. Follow each returned owner/CAS step and reobserve. `doctor PASS` and an
+observation command's exit 0 do not prove recovery, integration or task completion.
+
+## Repeat the regression as a contributor
+
+The default test suite checks refusal of existing workspaces and missing prerequisites. The real
+cross-tool regression is explicit opt-in, runs entirely against temporary local repositories,
+and covers unknown-file preservation, source drift, pause/resume and completed replay:
+
+```bash
+WC_DEMO_FINALIZER=/absolute/path/to/git-finalize \
+WC_DEMO_SNAPSHOT_RUNNER=/absolute/path/to/runner-venv/bin/snapshot-runner \
+  uv run --locked --python 3.12 --no-env-file python -m pytest -q tests/test_change_task.py \
+  -p no:cacheprovider --basetemp /absolute/path/to/a/new/demo-pytest
+```
+
+Install the contributor environment as described in [CONTRIBUTING](../CONTRIBUTING.md). Without
+both opt-in entrypoints, the cross-tool case is skipped; a skipped case is not acceptance evidence.

worktree_controller-1.30.6/docs/getting-started.md

@@ -0,0 +1,75 @@
+# Getting started
+
+Use Linux, Python 3.12, Git and readable `/proc`. Install WC in a virtual environment using the
+[README instructions](../README.md#install). The example needs no credentials, running service,
+companion tool or connection to a remote repository.
+
+## Run the example
+
+From the release's source checkout, with that environment active:
+
+```bash
+python examples/quickstart.py --workspace "$HOME/wc-first-run"
+```
+
+The parent directory must exist and the workspace path must be new, including on a second run.
+The script refuses an existing directory even when it is empty. A PyPI source archive includes
+the same `examples/quickstart.py` if you prefer downloading that over cloning the repository.
+
+The script creates `main/` as a new repository and `inspection/` as its governed linked checkout.
+An isolated `home/` keeps demo metadata separate from your normal WC state. `commands.jsonl`
+records every Git and WC command, actual exit code and JSON response. No real project is changed.
+
+## What to expect
+
+| Step | Meaning |
+| --- | --- |
+| `adopt`, `plan`, `acquire` | Register the demo's canonical checkout, check admission, allocate an inspection task. |
+| `writer-lease-acquire`, `WRITE_ALLOWED` | Bind the real demo process and check its exact task, owner and session. |
+| `BLOCK_OWNER_MISMATCH` | An intentional negative control: another owner is refused with exit code **1**. No forbidden write runs. |
+| `recovery-guide` | Read the current state and available formal next steps. This permission refusal does not itself change the allocation to `BLOCKED`. |
+| Inspection | Read the README; this task produces no source edit or new task commit. |
+| `complete-no-change`, `release --dry-run`, `release` | End the unchanged task and release its checkout through the Controller. |
+| Strict closeout check, `doctor`, `PASS` | Require completion proof for that exact allocation and verify metadata integrity. |
+
+The final `PASS` means the expected refusal was observed and the example's closeout checks passed.
+It does not mean a main-branch integration or release occurred. The repository, inspection branch,
+isolated HOME and log remain in the workspace; the linked `inspection/` directory is released.
+The script never deletes the workspace or a branch.
+
+## If it stops
+
+Read the last output and `commands.jsonl`. Unexpected exits stop the script; admission refusals
+are not retried under another identity. Resource requirements still apply on a small machine.
+An interrupted run can leave an allocation or writer lease, so do not delete a checkout by hand
+or rerun into its existing path.
+
+To inspect the same isolated state, replace the workspace below with the actual absolute path:
+
+```bash
+workspace="$HOME/wc-first-run"
+HOME="$workspace/home" XDG_STATE_HOME="$workspace/home/.local/state" \
+  worktree-controller status --repo "$workspace/main" --json
+HOME="$workspace/home" XDG_STATE_HOME="$workspace/home/.local/state" \
+  worktree-controller recovery-guide --repo "$workspace/main" --path "$workspace/inspection" --json
+```
+
+Use the recorded owner, allocation, process/session identity and current record version when
+following the returned formal recovery guidance. Never edit Controller metadata or weaken a guard.
+An already released checkout is inspected with `lifecycle-history`; directory absence alone does
+not establish completion.
+
+## Move on to work that changes files
+
+The example deliberately performs a genuine no-change inspection, so `complete-no-change` is
+appropriate. A task that edits files or creates commits must preserve or deliver that work;
+it cannot use this shortcut. Follow [your first change](first-change.md) for an executable local
+commit, handoff, integration and pause/resume example with public companion tools. See the
+[operations guide](operations.md) for the existing contracts. WC itself does not commit, push
+or approve a production release.
+
+For real session closeout, pass the complete recorded selector (`--client-id`, `--session-id`,
+`--run-id` when present, and `--holder`) and every known `--expected-allocation-id` to
+`worktree-session-end --check`. After resolving its blockers, use `--require-complete` and require
+`summary.terminal_complete=true` together with each allocation's decision. The example uses a
+read-only strict check after its explicit completion and release.