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

{worktree_controller-1.30.5 → worktree_controller-1.30.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: worktree-controller
-Version: 1.30.5
+Version: 1.30.6
 Summary: Govern Git worktree budgets, authority, ownership, and lifecycle
 License-Expression: Apache-2.0
 License-File: LICENSE
@@ -23,7 +23,7 @@ It checks repository policy before allocating a worktree, grants writing authori
 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.5 · Linux · Python 3.12 · Apache-2.0**
+**Current release: 1.30.6 · Linux · Python 3.12 · Apache-2.0**
 
 ## Install
 
@@ -32,14 +32,16 @@ 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.5
+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`.
-Software version 1.30.5 retains CLI contract **60** and storage layout **5**.
+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
 
@@ -48,7 +50,7 @@ With the environment above active:
 ```bash
 git clone https://github.com/xuanheng-tech/worktree-controller.git wc
 cd wc
-git checkout v1.30.5
+git checkout v1.30.6
 python examples/quickstart.py --workspace "$HOME/wc-first-run"
 ```
 
@@ -63,6 +65,10 @@ The [getting started guide](https://github.com/xuanheng-tech/worktree-controller
 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.
@@ -74,7 +80,8 @@ 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 Snapshot Runner are optional companion tools; see
+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`
@@ -90,6 +97,7 @@ a successful process exit alone does not prove that all worktrees are settled.
 - [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)

{worktree_controller-1.30.5 → worktree_controller-1.30.6}/README.md

@@ -6,7 +6,7 @@ It checks repository policy before allocating a worktree, grants writing authori
 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.5 · Linux · Python 3.12 · Apache-2.0**
+**Current release: 1.30.6 · Linux · Python 3.12 · Apache-2.0**
 
 ## Install
 
@@ -15,14 +15,16 @@ 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.5
+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`.
-Software version 1.30.5 retains CLI contract **60** and storage layout **5**.
+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
 
@@ -31,7 +33,7 @@ With the environment above active:
 ```bash
 git clone https://github.com/xuanheng-tech/worktree-controller.git wc
 cd wc
-git checkout v1.30.5
+git checkout v1.30.6
 python examples/quickstart.py --workspace "$HOME/wc-first-run"
 ```
 
@@ -46,6 +48,10 @@ The [getting started guide](https://github.com/xuanheng-tech/worktree-controller
 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.
@@ -57,7 +63,8 @@ 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 Snapshot Runner are optional companion tools; see
+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`
@@ -73,6 +80,7 @@ a successful process exit alone does not prove that all worktrees are settled.
 - [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)

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.5 → worktree_controller-1.30.6}/docs/getting-started.md

@@ -63,9 +63,10 @@ not establish completion.
 
 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. See the [operations guide](operations.md) for the existing
-handoff, integration and recovery contracts and [Git Finalizer](https://github.com/xuanheng-tech/git-finalizer)
-for delivery evidence. WC itself does not commit, push or approve a production release.
+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_controller-1.30.5 → worktree_controller-1.30.6}/docs/operations.md

@@ -7,8 +7,15 @@ the [getting started guide](getting-started.md) provides an isolated first run.
 
 ## Start or resume development
 
-1. Run `tool-skill-sync doctor --repo <checkout> --summary`, then Controller `status --json`.
+For a worked local task, use [your first change](first-change.md). Core inspection/allocation needs
+WC and Git. The integration flow below additionally uses Git Finalizer and separate test and
+Snapshot evidence; policy schema 4+ requires both receipt identities explicitly. The worked example
+uses the public Snapshot Runner package. Context Loader and `tool-skill-sync` are optional.
+
+1. Run Controller `--version`, `capabilities --json`, `status --json` and `doctor --json`.
    Read the selected repository policy and distinguish installed runtime from source candidates.
+   If your site installed the optional maintenance checker, also run
+   `tool-skill-sync doctor --repo <checkout> --summary` for its tool/Skill pairing checks.
 2. Use `plan` for the existing task/authority. Reuse its allocation when supported; otherwise use
    `acquire` with explicit owner, branch, base and scope. A waiting request is not an allocation.
 3. Bind the real writer process and session/run through `writer-session` or `writer-lease-acquire`.

worktree_controller-1.30.6/docs/publishing.md

@@ -0,0 +1,104 @@
+# Publishing WC packages
+
+The `Publish release` workflow in `.github/workflows/release.yml` releases an existing stable tag
+that is already integrated into public `main`. It does not create tags, commit, merge or push Git
+branches. Source delivery continues to use the repository's Controller and Git Finalizer flow.
+The software version, CLI contract and storage layout remain independently versioned.
+
+## One-time setup
+
+The repository uses a GitHub environment named **`pypi`**, restricted to workflow runs from **main**.
+The environment grants no additional review exemption. Keep any existing platform protections.
+
+In the PyPI project's **Manage → Publishing → Add a new publisher → GitHub** form, register:
+
+| Field | Exact value |
+| --- | --- |
+| PyPI project | `worktree-controller` |
+| Owner | `xuanheng-tech` |
+| Repository | `worktree-controller` |
+| Workflow filename | `release.yml` |
+| Environment | `pypi` |
+
+The owner completes this authenticated PyPI account step. Do not put a long-lived PyPI token in
+GitHub secrets. The workflow uses `uv publish --trusted-publishing always`: an unavailable or
+mismatched publisher fails rather than falling back to another credential. Existing local
+credentials are not read, copied, revoked or changed by this workflow.
+
+See [PyPI's publisher setup](https://docs.pypi.org/trusted-publishers/adding-a-publisher/) and
+[uv's GitHub integration](https://docs.astral.sh/uv/guides/integration/github/#publishing-to-pypi).
+
+## Audit an existing release
+
+Run from an authenticated GitHub CLI with access to the public repository:
+
+```bash
+gh workflow run release.yml --repo xuanheng-tech/worktree-controller --ref main \
+  -f tag=v1.30.5 -F publish=false
+```
+
+This checks and builds the exact tag in a job with read-only repository permissions. Automation
+comes from the immutable workflow commit; the payload is checked out separately at its tag.
+The workflow records a manifest and checksums and audits the existing GitHub/PyPI inventory.
+For an already published release, it also downloads and installs both distributions in fresh
+environments and runs the onboarding example shipped in the source archive.
+
+For an unpublished tag, audit reports the missing remote files and skips post-publication
+installation. A successful audit is preparation evidence, not proof of a new publication or a
+successful OIDC upload. WC's packaged onboarding contract introduced in 1.30.5 is required.
+
+## Publish a real version
+
+After the actual source change and version update have been validated and integrated, create and
+publish its exact stable version tag through the normal release process. Then trigger once:
+
+```bash
+gh workflow run release.yml --repo xuanheng-tech/worktree-controller --ref main \
+  -f tag=vX.Y.Z -F publish=true
+```
+
+Replace `vX.Y.Z` with that existing tag. The tag must exactly match `pyproject.toml` and the CLI
+contract's software version. A tag outside main, a moved tag, dirty source, unknown file or
+checksum mismatch stops the workflow. No force operation or Controller-state edit is used.
+
+The workflow performs these stages:
+
+1. Run `scripts/check-project` on the tag: lint, full default suite, wheel/sdist build, sdist
+   rebuild and installed checks. Freeze one authoritative wheel/sdist pair in an immutable run
+   artifact. Rebuilding the sdist for validation does not replace that pair.
+2. With publishing permissions, recheck the source identity and both remote inventories. Store
+   the exact pair and SHA256SUMS in a GitHub draft, upload only missing PyPI files using short-lived
+   publishing credentials, verify the registry, and make the matching GitHub release public.
+   Building or installing package code never runs in this privileged job.
+3. In a separate job without publishing permissions, independently download both PyPI files,
+   compare their hashes, install them with fresh caches, verify metadata and all three CLI entry
+   points, and run the source archive's onboarding example. A short bounded retry handles a newly
+   uploaded version missing from the package index; functional failures are not retried.
+
+## Recover a failed or interrupted run
+
+Inspect the failing step and its real exit code. A nonzero uploader exit remains a failed step,
+even if a file reached the server. The GitHub draft and immutable Actions artifact retain the
+original bytes. Resolve the stated blocker and use **Re-run failed jobs** in that same run:
+
+```bash
+gh run rerun RUN_ID --failed --repo xuanheng-tech/worktree-controller
+```
+
+The publish job consumes the successful build job's original artifact name, including its original
+run attempt. It checks already uploaded bytes, uploads only missing files, and never uses
+`--clobber` or blindly skips an existing PyPI filename. An already complete matching release is
+observed without another upload. Unknown assets, yanked files, identity drift and different bytes
+remain blocked; do not delete or replace them to make a retry pass.
+
+A repository-wide workflow concurrency group serializes release runs without interrupting an
+active publisher. GitHub retains only one pending run per concurrency group, so use failed-job
+recovery instead of submitting a queue of duplicate dispatches. Bundles and check evidence have
+90-day retention. Once an artifact expires, a new run must build and validate again; if its bytes
+differ from existing remote files, it stops and requires review of the retained original evidence.
+It never overwrites the old release.
+
+Receipts distinguish a read-only audit, `PUBLISHED_VERIFIED`, and `FRESH_INSTALLS_VERIFIED`.
+Skipped tests remain skipped. Local installation or activation of a maintainer's WC runtime is a
+separate operation; publishing a package does not update that runtime or authorize a production
+release in any repository governed by WC.

{worktree_controller-1.30.5 → worktree_controller-1.30.6}/docs/reference.md

@@ -7,14 +7,17 @@ The [CLI contract](../tool_cli_contract.json) is authoritative for exact interfa
 ## Optional integrations and dependencies
 
 The core control plane has a single runtime dependency (`websockets>=15,<16`) and works standalone
-against any local Git repository on the supported platform. Everything below is optional and is
-exercised only when the corresponding context or companion tool is present:
+against any local Git repository on the supported platform. The integrations below are optional
+for core inspection/allocation; selecting a delivery flow can add explicit evidence requirements:
 
 - **Companion delivery tools.** WC composes with, but does not require or embed, the separate
   **Context Loader** (context reading), **Snapshot Runner** (read-only review evidence) and
   **Git Finalizer** (commit and publication). Each owns its own authority; WC never merges,
   publishes or commits on their behalf. The handoff and integration flows in
   [docs/operations.md](operations.md) assume Git Finalizer is installed for delivery evidence.
+  Policy schema 4+ also requires explicit test and Snapshot receipt identities for preparation;
+  [your first change](first-change.md) uses the public Snapshot Runner package to produce them.
+  Context Loader and the optional maintenance checker are not required by that example.
 - **Client-specific recovery.** The `archived_codex_binding_recovery_version` capability
   (`--recover-archived-codex-session`) recovers a released writer lease whose original session
   belonged to the Codex CLI client, by verifying that client's own archived-session and

worktree_controller-1.30.6/examples/change_task.py

@@ -0,0 +1,242 @@
+#!/usr/bin/env python3
+"""Deliver a README change to a local bare remote, with an optional handoff pause."""
+
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from quickstart import POLICY
+
+OWNER = "demo-owner"
+CONTENT = "# WC demo\nA delivered change.\n"
+CHECK = """
+import pathlib, sys
+if (pathlib.Path(sys.argv[1]) / 'README.md').read_text() != sys.argv[2]:
+    raise SystemExit('README change did not match the reviewed result')
+print('README change verified')
+"""
+
+
+def require(condition, message):
+    if not condition:
+        raise RuntimeError(message)
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--workspace", type=Path, required=True)
+    parser.add_argument("--finalizer", type=Path, help="installed public git-finalize entrypoint")
+    parser.add_argument("--snapshot-runner", type=Path, help="installed public snapshot-runner entrypoint")
+    parser.add_argument("--pause-after-handoff", action="store_true")
+    parser.add_argument("--resume", action="store_true", help="continue this demo's saved handoff")
+    args = parser.parse_args()
+    workspace = args.workspace.absolute()
+    if args.resume:
+        if args.pause_after_handoff:
+            parser.error("--resume and --pause-after-handoff are separate invocations")
+        if workspace.is_symlink() or not (workspace / "handoff.json").is_file():
+            parser.error("--resume needs this demo's existing workspace and handoff.json")
+    elif workspace.exists() or workspace.is_symlink() or not workspace.parent.is_dir():
+        parser.error("--workspace must be a new path under an existing directory")
+    if sys.platform != "linux" or sys.version_info[:2] != (3, 12):
+        parser.error("the demo requires Linux and Python 3.12")
+    controller = Path(sys.executable).with_name("worktree-controller")
+    if not controller.is_file():
+        found = shutil.which("worktree-controller")
+        if not found:
+            parser.error("install WC in this Python environment first")
+        controller = Path(found)
+    finalizer = args.finalizer or shutil.which("git-finalize")
+    if not finalizer or not Path(finalizer).is_file() or not os.access(finalizer, os.X_OK):
+        parser.error("install Git Finalizer, or pass --finalizer /absolute/path/to/git-finalize")
+    finalizer = Path(finalizer).absolute()
+    runner = args.snapshot_runner or shutil.which("snapshot-runner")
+    if not runner or not Path(runner).is_file() or not os.access(runner, os.X_OK):
+        parser.error("install Snapshot Runner, or pass --snapshot-runner /absolute/path/to/snapshot-runner")
+    runner = Path(runner).absolute()
+    session_end = controller.with_name("worktree-session-end")
+    if not session_end.is_file() or not shutil.which("git"):
+        parser.error("Git and worktree-session-end must be installed")
+    if not args.resume:
+        workspace.mkdir()
+        (workspace / "home").mkdir()
+        (workspace / "tmp").mkdir()
+    repo, source, candidate = (workspace / name for name in ("main", "change", "integration"))
+    for path in (repo, source, candidate, workspace / "origin.git", workspace / "handoff.json"):
+        require(not path.is_symlink(), f"demo paths must not be symlinks: {path}")
+    environment = {key: os.environ[key] for key in ("LANG", "LC_ALL", "TZ") if key in os.environ}
+    home = workspace / "home"
+    state = home / ".local/state"
+    state.mkdir(parents=True, exist_ok=True, mode=0o700)
+    state.chmod(0o700)
+    environment.update(
+        PATH=os.pathsep.join((str(controller.parent), str(finalizer.parent), os.environ.get("PATH", os.defpath))),
+        HOME=str(home), TMPDIR=str(workspace / "tmp"),
+        XDG_STATE_HOME=str(home / ".local/state"), XDG_CONFIG_HOME=str(home / ".config"),
+        XDG_CACHE_HOME=str(home / ".cache"), GIT_CONFIG_NOSYSTEM="1",
+        GIT_CONFIG_GLOBAL=os.devnull, GIT_TERMINAL_PROMPT="0",
+        PYTHONNOUSERSITE="1", PYTHONDONTWRITEBYTECODE="1",
+    )
+    identity = ["--client-id", "wc-change-demo", "--session-id", "change-demo", "--run-id", "change-demo"]
+
+    def run(*arguments, expected=0):
+        result = subprocess.run([str(arg) for arg in arguments], cwd=workspace, env=environment,
+                                stdin=subprocess.DEVNULL, capture_output=True, text=True,
+                                timeout=120, check=False)
+        with (workspace / "commands.jsonl").open("a") as stream:
+            stream.write(json.dumps({"argv": [str(arg) for arg in arguments],
+                                     "returncode": result.returncode, "stdout": result.stdout,
+                                     "stderr": result.stderr}) + "\n")
+        require(result.returncode == expected,
+                f"{arguments[0]} exited {result.returncode}, expected {expected}; see commands.jsonl")
+        return result.stdout
+
+    def save(name, value):
+        (workspace / name).write_text(json.dumps(value, indent=2) + "\n")
+
+    def wc(command, *arguments):
+        value = json.loads(run(controller, command, "--repo", repo, "--json", *arguments))
+        require(not value.get("errors"), f"Controller refused {command}; see commands.jsonl")
+        print(f"{command}: {(value.get('decision') or {}).get('code', 'observed')}", flush=True)
+        return value
+
+    def row(path):
+        return next(item for item in wc("status")["worktrees"] if item["path"] == str(path))
+
+    def gf(name, *arguments):
+        value = json.loads(run(finalizer, "--summary", *arguments))
+        save(name, value)
+        require(value["status"] == "success", f"Finalizer stopped; see {name}")
+        return value
+
+    def check(path, name):
+        output = run(sys.executable, "-I", "-c", CHECK, path, CONTENT)
+        require(not run("git", "-C", path, "status", "--porcelain"), "candidate must be clean")
+        save(name, {"status": "PASS", "checked_file": "README.md", "stdout": output,
+                    "commit": run("git", "-C", path, "rev-parse", "HEAD").strip()})
+
+    def snapshot(path, name, *, committed):
+        arguments = ["branch-review", "--repo", path, "main"] if committed else [
+            "diff-audit", "--repo", path, "--scope-path", "README.md"]
+        summary = json.loads(run(runner, *arguments, "--summary"))
+        save(name, summary)
+        require(summary["status"] == "complete" and not summary["truncated"]
+                and not summary["evidence_gap"] and not summary["warnings"], "Snapshot evidence incomplete")
+        evidence = json.loads(run(runner, "read", summary["snapshot_id"], "--repo", path, "--path", "README.md"))
+        save(name.replace(".json", "-read.json"), evidence)
+        require(evidence["found"] and not evidence["truncated"] and not evidence["evidence_gap"],
+                "README snapshot could not be read")
+        return summary["snapshot_id"]
+
+    if not args.resume:
+        run("git", "init", "--bare", "--initial-branch=main", workspace / "origin.git")
+        run("git", "init", "--initial-branch=main", repo)
+        for key, value in (("user.name", "WC Demo"), ("user.email", "demo@example.invalid")):
+            run("git", "-C", repo, "config", key, value)
+        run("git", "-C", repo, "remote", "add", "origin", workspace / "origin.git")
+        policy = repo / ".agents/worktree-policy.toml"
+        policy.parent.mkdir()
+        policy.write_text(POLICY)
+        (repo / "README.md").write_text("# WC demo\nA local change task.\n")
+        gf("bootstrap-finalizer.json", "--initial-publish", "--remote", "origin", "--repo", repo,
+           "--message", "Initialize local demo", "--", "README.md", ".agents/worktree-policy.toml")
+        wc("adopt", "--path", repo, "--task-key", "demo-control", "--authority-key", "demo-control",
+           "--module", "demo", "--role", "control-plane", "--owner", OWNER, "--lifecycle", "ACTIVE")
+        request = ["--task-key", "demo-change", "--authority-key", "demo-change", "--module", "demo", "--role", "feature"]
+        require(wc("plan", *request)["decision"]["code"] == "CREATE_ALLOWED", "admission refused")
+        acquired = wc("acquire", *request, "--owner", OWNER, "--branch", "demo/change",
+                      "--base-ref", "main", "--path", source, "--scope", "README.md")
+        allocation = acquired["decision"]["allocation_id"]
+        lease = wc("writer-lease-acquire", "--path", source, "--owner", OWNER,
+                   "--holder-pid", os.getpid(), *identity)["decision"]
+        guard = wc("write-guard", "--path", source, "--task-key", "demo-change",
+                   "--authority-key", "demo-change", "--owner", OWNER, "--holder", os.getpid(),
+                   *identity, "--operation", "feature-write")
+        require(guard["decision"]["code"] == "WRITE_ALLOWED", "writer was refused")
+        (source / "README.md").write_text(CONTENT)
+        run(sys.executable, "-I", "-c", CHECK, source, CONTENT)
+        source_snapshot = snapshot(source, "source-snapshot.json", committed=False)
+        delivered = gf("source-finalizer.json", "--initial-branch-publish", "--remote", "origin",
+                       "--remote-branch", "demo/change", "--repo", source,
+                       "--message", "Deliver the README change", "--", "README.md")
+        commit = delivered["commit"]["sha"]
+        holder = lease["holder"]
+        wc("writer-lease-release", "--path", source, "--lease-id", lease["lease_id"],
+           "--holder-pid", holder["pid"], "--holder-boot-id", holder["boot_id"],
+           "--holder-start-ticks", holder["start_ticks"], *identity)
+        wc("handoff", "--path", source, "--expected-record-version", row(source)["record_version"],
+           "--kind", "integration-ready", "--commit", commit, "--finalizer-commit", commit,
+           "--finalizer-record-id", workspace / "source-finalizer.json")
+        queued = wc("integration-enqueue", "--task-key", "demo-integration", "--authority-key",
+                    "demo-integration", "--module", "demo", "--owner", OWNER,
+                    "--source-allocation", allocation, "--source-snapshot", source_snapshot)["decision"]
+        checkpoint = {"schema_version": 1, "intent_id": queued["intent_id"],
+                      "source_allocation": allocation, "source_commit": commit,
+                      "repository_id": wc("status")["repository"]["repository_id"]}
+        save("handoff.json", checkpoint)
+        if args.pause_after_handoff:
+            print(f"PAUSED: source published to local origin, writer released; resume with --resume --workspace {workspace}")
+            return
+    else:
+        checkpoint = json.loads((workspace / "handoff.json").read_text())
+        require(checkpoint["schema_version"] == 1, "unsupported demo checkpoint")
+        require(run("git", "-C", repo, "rev-parse", "--show-toplevel").strip() == str(repo),
+                "repository path changed")
+        require(run("git", "-C", repo, "remote", "get-url", "origin").strip() == str(workspace / "origin.git"),
+                "demo remote changed")
+        require(wc("status")["repository"]["repository_id"] == checkpoint["repository_id"],
+                "repository identity changed")
+        require(run("git", "-C", repo, "rev-parse", "demo/change^{commit}").strip() == checkpoint["source_commit"],
+                "saved source identity changed")
+        for path in (repo, source, candidate):
+            if path.exists():
+                require(not run("git", "-C", path, "status", "--porcelain"),
+                        f"uncommitted files remain in {path}; preserve them and follow recovery-guide")
+
+    guide = wc("recovery-guide", "--intent-id", checkpoint["intent_id"])["decision"]
+    if guide.get("terminal_status") != "PUBLISHED_RELEASED":
+        require(guide["intent"]["state"] in {"QUEUED", "PREPARING_INTEGRATION"},
+                "this demo resumes only queued or unchanged claimed work; follow recovery-guide")
+        claimed = wc("integration-claim", "--intent-id", checkpoint["intent_id"], "--owner", OWNER,
+                     "--path", candidate, "--branch", "demo/integration")["decision"]
+        check(candidate, "candidate-check.json")
+        candidate_snapshot = snapshot(candidate, "candidate-snapshot.json", committed=True)
+        wc("integration-validate", "--path", candidate, "--owner", OWNER,
+           "--expected-record-version", row(candidate)["record_version"],
+           "--validation-evidence-id", workspace / "candidate-check.json",
+           "--tests-receipt-id", workspace / "candidate-check.json",
+           "--snapshot-receipt-id", candidate_snapshot)
+        publication = wc("lease-acquire", "--path", candidate, "--owner", OWNER,
+                         "--expected-record-version", row(candidate)["record_version"],
+                         "--run-id", "demo-publication")["decision"]
+        published = gf("publication-finalizer.json", "--publish-integration-candidate", claimed["candidate_oid"],
+                       "--repo", candidate, "--lease-id", publication["lease_id"], "--run-id", "demo-publication")
+        require(published["remote_verify"]["oid"] == claimed["candidate_oid"], "remote identity mismatch")
+        wc("lease-complete", "--path", candidate, "--expected-record-version", row(candidate)["record_version"],
+           "--lease-id", publication["lease_id"], "--published-commit", claimed["candidate_oid"],
+           "--finalizer-record-id", published["record_id"], "--run-id", "demo-publication")
+        candidate_allocation = claimed["allocation_id"]
+    else:
+        candidate_allocation = guide["intent"]["allocation_id"]
+    wc("canonical-refresh")
+    check(repo, "main-check.json")
+    strict = json.loads(run(session_end, "--path", repo, *identity, "--holder", os.getpid(),
+                            "--expected-allocation-id", checkpoint["source_allocation"],
+                            "--expected-allocation-id", candidate_allocation, "--check", "--require-complete"))
+    save("closeout.json", strict)
+    require(strict["summary"]["terminal_complete"] is True, "checkout closeout incomplete")
+    require(wc("doctor")["decision"]["code"] == "PASS", "doctor did not pass")
+    require(not source.exists() and not candidate.exists(), "linked checkouts remain; follow their release guidance")
+    print(f"PASS: change integrated into local main; both checkouts released; branches and evidence kept: {workspace}")
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except (OSError, RuntimeError, ValueError, KeyError, StopIteration, subprocess.SubprocessError) as error:
+        print(f"Demo stopped; results are preserved. {error}", file=sys.stderr)
+        raise SystemExit(1) from error

{worktree_controller-1.30.5 → worktree_controller-1.30.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "worktree-controller"
-version = "1.30.5"
+version = "1.30.6"
 description = "Govern Git worktree budgets, authority, ownership, and lifecycle"
 readme = "README.md"
 requires-python = ">=3.12,<3.13"

{worktree_controller-1.30.5 → worktree_controller-1.30.6}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "worktree-controller"
-version = "1.30.5"
+version = "1.30.6"
 description = "Govern Git worktree budgets, authority, ownership, and lifecycle"
 readme = "README.md"
 requires-python = ">=3.12,<3.13"

{worktree_controller-1.30.5 → worktree_controller-1.30.6}/src/worktree_controller/__init__.py

@@ -1,3 +1,3 @@
 """Worktree lifecycle controller."""
 
-__version__ = "1.30.5"
+__version__ = "1.30.6"

{worktree_controller-1.30.5 → worktree_controller-1.30.6/src/worktree_controller}/tool_cli_contract.json

@@ -1065,7 +1065,7 @@
   "session_launcher_entrypoint": "worktree-session",
   "session_entrypoint": "worktree-session-end",
   "tool_name": "worktree-controller",
-  "tool_version": "1.30.5",
+  "tool_version": "1.30.6",
   "delivered_closeout_version": 1,
   "retained_archive_version": 1,
   "retention_convergence_version": 2,

{worktree_controller-1.30.5/src/worktree_controller → worktree_controller-1.30.6}/tool_cli_contract.json

@@ -1065,7 +1065,7 @@
   "session_launcher_entrypoint": "worktree-session",
   "session_entrypoint": "worktree-session-end",
   "tool_name": "worktree-controller",
-  "tool_version": "1.30.5",
+  "tool_version": "1.30.6",
   "delivered_closeout_version": 1,
   "retained_archive_version": 1,
   "retention_convergence_version": 2,