worktree-controller 1.31.0__tar.gz → 1.32.1__tar.gz

{worktree_controller-1.31.0 → worktree_controller-1.32.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: worktree-controller
-Version: 1.31.0
+Version: 1.32.1
 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.31.0 · Linux · Python 3.12 · Apache-2.0**
+**Current release: 1.32.0 · Linux · Python 3.12 · Apache-2.0**
 
 ## Install
 
@@ -32,7 +32,7 @@ Use a virtual environment in a new directory:
 ```bash
 python3.12 -m venv .venv
 . .venv/bin/activate
-python -m pip install worktree-controller==1.31.0
+python -m pip install worktree-controller==1.32.0
 worktree-controller --version
 worktree-controller capabilities --json
 ```
@@ -41,7 +41,7 @@ WC requires Git and readable Linux `/proc`. Other operating systems and Python v
 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.31.0 uses CLI contract **61** and storage layout **5**.
+Software version 1.32.0 uses CLI contract **61** and storage layout **5**.
 
 ## Try it in a disposable repository
 
@@ -50,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.31.0
+git checkout v1.32.0
 python examples/quickstart.py --workspace "$HOME/wc-first-run"
 ```
 
@@ -76,6 +76,10 @@ for the recorded owner and next formal step. The [everyday task guide](docs/dail
 covers simpler start, original-task checkpoint/resume, guarded no-change release and exact
 Finalizer handoff. These CLI 61 entrypoints retain the existing ownership, lease and policy checks.
 
+For client developers, the [AI client integration guide](docs/client-integration.md) describes the
+public identity and closeout contract, with an offline example that continues the same unfinished
+task from two independent client processes while preserving its files and checkpoint.
+
 ## Use WC in a real project
 
 A governed repository tracks `.agents/worktree-policy.toml` and registers its checkouts with WC.

{worktree_controller-1.31.0 → worktree_controller-1.32.1}/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.31.0 · Linux · Python 3.12 · Apache-2.0**
+**Current release: 1.32.0 · Linux · Python 3.12 · Apache-2.0**
 
 ## Install
 
@@ -15,7 +15,7 @@ Use a virtual environment in a new directory:
 ```bash
 python3.12 -m venv .venv
 . .venv/bin/activate
-python -m pip install worktree-controller==1.31.0
+python -m pip install worktree-controller==1.32.0
 worktree-controller --version
 worktree-controller capabilities --json
 ```
@@ -24,7 +24,7 @@ WC requires Git and readable Linux `/proc`. Other operating systems and Python v
 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.31.0 uses CLI contract **61** and storage layout **5**.
+Software version 1.32.0 uses CLI contract **61** and storage layout **5**.
 
 ## Try it in a disposable repository
 
@@ -33,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.31.0
+git checkout v1.32.0
 python examples/quickstart.py --workspace "$HOME/wc-first-run"
 ```
 
@@ -59,6 +59,10 @@ for the recorded owner and next formal step. The [everyday task guide](docs/dail
 covers simpler start, original-task checkpoint/resume, guarded no-change release and exact
 Finalizer handoff. These CLI 61 entrypoints retain the existing ownership, lease and policy checks.
 
+For client developers, the [AI client integration guide](docs/client-integration.md) describes the
+public identity and closeout contract, with an offline example that continues the same unfinished
+task from two independent client processes while preserving its files and checkpoint.
+
 ## Use WC in a real project
 
 A governed repository tracks `.agents/worktree-policy.toml` and registers its checkouts with WC.

worktree_controller-1.32.1/docs/client-integration.md

@@ -0,0 +1,148 @@
+# Integrating an AI client
+
+Use the existing public CLI as the boundary between a client and WC. The client implements the
+business task and keeps its durable checkpoint; WC remains the authority for admission, writer
+identity, lifecycle and release. Client names do not grant ownership or write permission.
+
+## Check the installed contract
+
+Read `worktree-controller --version`, `capabilities --json` and the installed command's `--help`.
+The task-oriented flow below requires CLI 61 and `task_workflow_version=1`. For checkpoint and
+strict closeout, require `task_checkpoint_park_version=1`, `session_closeout_report_version=1`
+and `session_closeout_expectations_version=1`. Storage layout is independently versioned (5 in
+1.31.0). A client must explicitly support the reported contract and required capabilities; a
+newer version number alone is not sufficient. Refuse an unsupported contract without mutation.
+
+Invoke commands as argument lists and parse JSON, process exit status and the specific result
+together. Never parse human descriptions, evaluate a returned shell string, open WC's private
+state, recreate a digest or replace a refused operation with raw Git worktree commands.
+
+## Keep the task and executor identities separate
+
+| Durable business Task keeps | Current executor obtains or observes |
+| --- | --- |
+| Repository, task key, authority key, recorded owner | Actual live holder PID, boot identity and start time |
+| Exact allocation ID, checkout path and branch | Client, session and run identity |
+| Checkpoint payload, content-addressed ID and bound HEAD | Fresh writer lease and current record version |
+| All allocations acquired by this task/session | Current HEAD, scope, lifecycle and blockers |
+| Finalizer, integration and release evidence when applicable | Current public recovery guidance |
+
+Changing AI clients changes the executor identity. It does not create a new business Task,
+transfer its owner, replace its allocation or inherit the previous client's lease. An owner
+transfer uses the existing explicit review/transfer flow. Re-observe identity, HEAD, scope and
+record version before every mutation; a checkpoint is not a reusable authorization credential.
+
+## Start, pause and continue
+
+1. Inspect `status`, `doctor`, the selected policy and an existing compatible task. Use
+   `task start` only for a new task. Admission returns a checkout without writer entitlement.
+2. Bind the actual executor through the supported `writer-session` handshake or
+   `writer-lease-acquire`. Pass the exact returned holder/session/run identity to `write-guard`
+   for the recorded task, authority, owner, path and operation before writing.
+3. To pause, first persist the existing Task's checkpoint, including its exact HEAD and enough
+   context to continue. WC does not copy or verify that payload. Preserve uncommitted files,
+   unknown files and generated output. Inspect normal exit with the real full session selector
+   while its leases still exist. End through that same selector to record its allocations and
+   release only its own leases; inspect any incomplete result. Then use `task finish --outcome
+   checkpoint` with its content-addressed ID and HEAD and repeat the strict check. Releasing leases
+   individually before session end can lose the live selector's association: expected IDs add
+   proof obligations but cannot select a retained checkout or establish that association.
+4. A different client reloads the Task checkpoint, uses public `task show`/`status` to match the
+   original allocation, owner, path, HEAD and scope, and refuses drift. Use `task resume` with the
+   original owner, then acquire fresh entitlement for the new live executor and repeat the guard.
+   A stale recorded lease must be resolved through the original formal recovery; never steal it.
+5. When work is deliverable, use real Finalizer evidence and `task finish --outcome handoff`,
+   followed by the existing integration flow. A no-change finish is only for genuine unchanged
+   work. A checkpoint pause leaves work unfinished and retains the checkout.
+
+See [everyday commands](daily-workflow.md) for exact examples and [operations](operations.md)
+for the existing writer, cleanup, recovery and integration entrypoints.
+
+## End every allocation, and report failures accurately
+
+Use the real client/session/holder/run selector with `worktree-session-end --check
+--require-complete`. Add every allocation the Task/session knows it acquired with repeatable
+`--expected-allocation-id`; these are additional proof obligations, not mutation selectors.
+Inspect every live, previous and expected row and require `summary.terminal_complete=true`.
+After preparation, end the session with the same selector and expected IDs using
+`--require-complete` without `--check`. Reobserve any refusal through the public recovery guide.
+
+An advisory exit 0 is not settlement evidence. A read-only guide may successfully describe a
+blocker. `RESOURCE_WAIT` and an incomplete no-change release return 2; retain the original request
+and any completed prefix. Retry only the pending formal step. Checkout settlement, business
+completion and main publication each require their own evidence. A retained checkpoint can
+settle an executor session while its business Task remains unfinished, but dirty or unclassified
+files still require owner action and keep strict closeout incomplete. Checkpoint success alone
+does not settle that obligation. Preserve the pending result when the original owner continues
+the same Task in a new client; do not recreate an old holder to make it appear complete.
+
+## Run the offline continuation example
+
+From the source checkout or the 1.32.0 source distribution, with WC 1.31.0 or later installed:
+
+```bash
+python examples/client_continuation.py --workspace "$HOME/wc-client-example"
+python examples/client_continuation.py --workspace "$HOME/wc-client-example" --resume
+```
+
+The first invocation requires a new path under an existing parent. Each invocation is a real,
+separate executor process with a different client/session/run identity. The example uses its
+own HOME and a disposable repository, no remote, credentials, companion delivery tools or AI
+service. It verifies original-task continuation, wrong-owner and competing-writer refusals,
+two-checkout closeout, partial-release exit 2 and retry without duplicate completion.
+
+The second invocation verifies that the new writer is permitted and the old client identity is
+refused. It preserves the unfinished edit, unknown binary note, original checkpoint and its new
+generation. Only the exact generated fixture created by the example is moved to its preservation
+path; real unknown output still requires its owner's classification/preservation flow.
+`PASS` means the protocol exercise completed. No business task is declared complete or published.
+The original work stays `RETAINED`, with its branch, files and command/closeout evidence available.
+Strict closeout correctly returns 2: the inspection checkout has complete release proof, while
+the dirty unfinished checkout remains pending. Each executor formally ends its own writer session.
+An existing workspace, identity/file drift or repeated resume is refused, preserving evidence.
+
+This demonstrates two CLI consumers, not actual invocation or discovery by two AI vendors.
+Vendor-specific discovery and live-client use require their own observed acceptance, as described
+in [checks and deployment evidence](operations.md#checks-and-deployment).
+
+## Accept a real AI client
+
+Accept a client by observing it use the installed WC interface during a real task,
+including a pause and continuation in a later native session. Running the offline
+protocol example checks the CLI workflow; it does not establish that an AI client
+discovers or invokes WC correctly. Keep the actual session identities and checkpoint
+evidence with the acceptance result, and limit claims to the client and workflow observed.
+
+Use the separate `worktree-session-end` executable for session closeout. Keep a practical
+evidence checklist:
+
+- Capture actual native-client WC invocations, raw results and exit codes, client version,
+  and distinct native session/run/holder identities before and after interruption.
+- Verify the raw checkpoint digest and unchanged Task/authority/owner, allocation, path,
+  branch, HEAD and scope; compare exact file SHA256 values before the next session edits.
+- Resume the original Task, acquire a fresh live writer, and pass its check and write guard;
+  record refusal of the previous identity without reviving it or bypassing a refusal.
+- While leases are recorded, check and end with the exact client/session/run/holder selector.
+  Include every allocation via `--expected-allocation-id`; retain every per-tree decision
+  and require `summary.terminal_complete` with `--require-complete` before claiming closeout.
+- Follow the [first-change workflow](first-change.md) to finish; keep separate Finalizer,
+  handoff, integration/publication and release evidence before claiming task completion.
+  A retained checkpoint preserves unfinished work; it is not delivery evidence.
+
+One tested vendor does not prove another vendor's discovery or invocation of WC; accept each
+client and workflow using its own observed evidence.
+
+## Upgrade an existing managed installation
+
+A public package installation in a new environment is separate from activation of a shared
+Controller. Use the site's supported installer, published toolchain compatibility catalog,
+consumer checks and rollout gate. Finish with installed smoke and the default installed doctor.
+Do not repoint the active runtime, modify another client's session or widen accepted versions.
+
+Ordinary `controller-activate activate` requires the target to descend from the active commit.
+For an independent public export, 1.32.0 provides the explicit, receipt-bound
+[`release-history-handover/v1` procedure](operations.md#moving-an-exact-exported-release-to-its-public-history).
+It requires exact exported payloads, published release identities and current rollout gates;
+ordinary bootstrap, copying the shared Skill or matching storage versions is not a substitute.
+A catalog refusal blocks deployment while isolated protocol validation and source delivery can
+continue. Record staged, activated and verified results separately.

{worktree_controller-1.31.0 → worktree_controller-1.32.1}/docs/operations.md

@@ -4,6 +4,8 @@ Use this page to select a flow. The [CLI contract](../tool_cli_contract.json) ow
 capability and result schemas; installed `--help` owns the arguments available on this host.
 The [technical reference](reference.md) retains detailed protocols and compatibility history;
 the [getting started guide](getting-started.md) provides an isolated first run.
+Client implementers can follow the [AI client integration guide](client-integration.md) and its
+offline cross-client continuation example.
 
 ## Start or resume development
 
@@ -260,6 +262,69 @@ stage, rollout and activation. CLI, capability and storage versions are independ
 Use the existing rollback flow; never repoint the active runtime by hand or activate another
 owner's unintegrated candidate. Finish with installed smoke, rollout/deployment checks and doctor.
 
+### Moving an exact exported release to its public history
+
+Normal `activate` requires descendant history and normal `rollback` requires ancestor history.
+An independent public export does not satisfy either rule. Since 1.32.0, the existing
+`scripts/controller-activate` entry supports `release-history-handover/v1`; it does not modify
+Controller lifecycle data, Git ancestry, admission policy or writer leases. Run the exact
+published target's maintenance script, with the normal site configuration:
+
+```bash
+export CONTROLLER_ROLLOUT_REPO=/absolute/public/canonical-checkout
+export CONTROLLER_ROLLOUT_GIT_SOURCE=https://github.com/your-org/worktree-controller.git
+export CONTROLLER_ROLLOUT_GOVERNED=/absolute/repo-one:/absolute/repo-two
+controller-activate stage --version FULL_TARGET_OID --temp-helper /absolute/tool-temp-dir
+controller-activate history-activate --version FULL_TARGET_OID \
+  --request-id original-export-request --handover-baseline FULL_PUBLIC_ROOT_OID \
+  --previous-source-repo /absolute/retained-original-source \
+  --consumer /absolute/installed-host-capability-command --dry-run
+```
+
+Repeat `--consumer` for every effective external host and include the site's published
+`--toolchain-compatibility /absolute/catalog.json` when one is configured. The optional checker
+must understand CLI 61 and `controller-runtime-source/v1` (Git Finalizer 1.9.4 or later for the
+bundled checker). Stage writes that immutable, owned source manifest beside the runtime; it binds
+the exact commit, primary source checkout, Git common directory, history root, contract hash and
+Skill hash. Legacy installations without it retain their existing source selection. Invalid or
+changed manifests must fail rather than silently fall back. Keep both source histories and both
+installed runtimes available for verification and rollback.
+
+The gate requires a root release whose runtime, packaging, maintenance scripts and complete Skill
+payload exactly equal the original frozen predecessor. Both public baseline and target must have
+live matching stable release tags. The target must descend from that baseline and preserve storage,
+metadata and writer-lease formats and installed Skill bytes. This entry cannot combine namespace,
+policy, Skill or cleanup migrations. Existing resource, metadata and consumer gates still run.
+Live compatible writer sessions may continue; incompatible, stale or incomplete evidence is not
+made eligible by this procedure.
+
+Inspect the single JSON result. Dry-run exit 0 means `plan_ready=true`, **not** completed activation.
+Apply the identical request without `--dry-run`, adding its exact `--expected-plan-id`. The plan
+binds the current active pointer, scope and compatibility catalog. The producer saves an immutable
+receipt before switching. Preserve its `receipt` and `receipt_sha256` from the result. On interruption
+or an uncertain result, inspect the original request and active pin before retrying; do not invent
+another request identity. Resume using only the original receipt and SHA256:
+
+```bash
+controller-activate history-activate --history-receipt /absolute/original-receipt.json \
+  --history-receipt-sha256 ORIGINAL_SHA256 --consumer /absolute/installed-host-capability-command \
+  --dry-run
+controller-activate history-rollback --history-receipt /absolute/original-receipt.json \
+  --history-receipt-sha256 ORIGINAL_SHA256 --consumer /absolute/installed-host-capability-command \
+  --dry-run
+```
+
+For either action, inspect a fresh plan and apply with its exact plan ID. Keep the original governed
+repositories and consumers; adding current checks is allowed, omitting original checks is refused.
+An explicit rollback request fences subsequent forward reuse of that request. Unknown pending files
+are preserved. An interrupted producer write is preserved byte for byte before an exact retry.
+Exit 0 with `operation_complete=true` proves the requested active pin and postchecks; a repeated
+verified operation may report `activation_performed=false`. Refusal exits 2. Failed activation
+followed by verified predecessor restoration exits 3 with `operation_complete=false`; this is a
+failure, not successful upgrade. If restoration itself cannot pass current gates, the entry reports
+the observed active commit and preserves evidence for the original recovery. Finish with installed
+smoke and the default deployment doctor; runtime activation never grants business release approval.
+
 For each external consumer, distinguish three outcomes:
 
 | Check | What it proves |

{worktree_controller-1.31.0 → worktree_controller-1.32.1}/docs/reference.md

@@ -34,7 +34,9 @@ for core inspection/allocation; selecting a delivery flow can add explicit evide
   Repositories created under the current namespace never invoke it.
 - **Maintainer deployment.** `scripts/controller-activate` and `scripts/controller-runtime` are the
   source-owned runtime activation and start entry points used by a maintainer's host; they are not
-  required to install or use the published package.
+  required to install or use the published package. Since 1.32.0, their explicit
+  `release-history-handover/v1` and `controller-runtime-source/v1` contracts support exact public
+  exports and immutable runtime provenance; see the [maintenance procedure](operations.md#moving-an-exact-exported-release-to-its-public-history).
 
 From 1.30.1, a completed cleanup at a retained source may survive normal park/resume
 cycles followed by a formal handoff of the same HEAD and owner. Verification requires
@@ -1476,9 +1478,10 @@ checkout rejects feature writes. `READY_TO_PUBLISH` is write-fenced until explic
 out-of-band HEAD, content, record, or binding drift makes old evidence unusable.
 
 The bounded `integration-keyed-document-scope/v1` refinement applies only when the entire
-overlap is the exact `docs/handbook/business-progress.json` path. Every pair of frozen source
-commits must have one non-ancestor merge base and the same committed `.gitattributes` declaring
-`merge=qp-handbook-progress`. QP schema 2 records are compared by whole `tasks.authority_key`
+overlap is exactly `docs/nexus/business-progress.json` with `merge=qp-nexus-progress`, or
+the historical `docs/handbook/business-progress.json` with `merge=qp-handbook-progress`.
+Cross-path moves retain the ordinary file fence. Every pair of frozen source commits must have
+one non-ancestor merge base and the same committed `.gitattributes` declaring the matching profile. QP schema 2 records are compared by whole `tasks.authority_key`
 or `development_lines/modules/decisions.id`, including additions and deletions. All changed key
 sets must be disjoint. Metadata, schema, ordering, duplicate keys, missing/oversized/non-regular
 blobs, unknown evidence, broad paths and code overlaps keep the ordinary file fence. Explicit

worktree_controller-1.32.1/examples/client_continuation.py

@@ -0,0 +1,239 @@
+#!/usr/bin/env python3
+"""Exercise two independent client processes continuing one unfinished task, offline."""
+
+import argparse
+import hashlib
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from quickstart import POLICY
+
+OWNER = "demo-task-owner"
+TASK = "continued-work"
+
+
+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,
+                        help="new directory under an existing parent on the first invocation")
+    parser.add_argument("--resume", action="store_true", help="continue the example's original task")
+    args = parser.parse_args()
+    workspace = args.workspace.absolute()
+    if workspace.is_symlink():
+        parser.error("workspace must not be a symlink")
+    if not args.resume and (workspace.exists() 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 example 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 1.31.0 or later in this Python environment first")
+        controller = Path(found)
+    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")
+
+    # Never read a caller's checkpoint or append logs through a symlink.
+    if args.resume:
+        for name in ("task-checkpoint.json", "commands.jsonl", "home", "main", "continued-work"):
+            path = workspace / name
+            require(path.exists() and not path.is_symlink(), f"missing or symlink example path: {name}")
+        checkpoint_bytes = (workspace / "task-checkpoint.json").read_bytes()
+        saved = json.loads(checkpoint_bytes)
+        require(saved["example"] == "wc-client-continuation/v1", "unknown example checkpoint")
+    else:
+        workspace.mkdir()
+        (workspace / "home").mkdir()
+        (workspace / "tmp").mkdir()
+
+    home, repo = workspace / "home", workspace / "main"
+    checkout, audit = workspace / TASK, workspace / "inspection"
+    environment = {key: os.environ[key] for key in ("PATH", "LANG", "LC_ALL", "TZ") if key in os.environ}
+    environment.update(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")
+    client = "example-client-b" if args.resume else "example-client-a"
+    identity = ["--client-id", client, "--session-id", client + "-session", "--run-id", client + "-run"]
+
+    def run(*arguments, expected=0):
+        command = [str(value) for value in arguments]
+        result = subprocess.run(command, cwd=workspace, env=environment, capture_output=True,
+                                text=True, timeout=120, check=False)
+        with (workspace / "commands.jsonl").open("a") as stream:
+            stream.write(json.dumps({"argv": command, "returncode": result.returncode,
+                                     "stdout": result.stdout, "stderr": result.stderr}) + "\n")
+        require(result.returncode == expected,
+                f"{command[0]} exited {result.returncode}, expected {expected}; see commands.jsonl")
+        return result.stdout
+
+    def wc(command, *arguments, expected=0):
+        if command == "task":
+            action, *arguments = arguments
+            command_args = [command, action, "--repo", repo, "--json", *arguments]
+        else:
+            command_args = [command, "--repo", repo, "--json", *arguments]
+        payload = json.loads(run(controller, *command_args, expected=expected))
+        if expected == 0:
+            require(not payload.get("errors"), f"Controller refused {command}")
+        return payload
+
+    def row(path):
+        return next(item for item in wc("status")["worktrees"] if item["path"] == str(path))
+
+    def guard(path, task=TASK, *, selected_identity=None, owner=OWNER, expected=0):
+        return wc("write-guard", "--path", path, "--task-key", task, "--authority-key", task,
+                  "--owner", owner, "--holder", os.getpid(), "--operation", "feature-write",
+                  *(identity if selected_identity is None else selected_identity), expected=expected)
+
+    def acquire(path):
+        return wc("writer-lease-acquire", "--path", path, "--owner", OWNER,
+                  "--expected-record-version", row(path)["record_version"],
+                  "--holder-pid", os.getpid(), *identity)["decision"]
+
+    def closeout(allocations, name, *, expected=2, checking=True):
+        options = [option for allocation in allocations
+                   for option in ("--expected-allocation-id", allocation)]
+        result = json.loads(run(session_end, "--path", repo, *identity, "--holder", os.getpid(),
+                                *options, *(["--check"] if checking else []),
+                                "--require-complete", expected=expected))
+        (workspace / name).write_text(json.dumps(result, indent=2) + "\n")
+        require(result["summary"]["terminal_complete"] is (expected == 0), "incorrect closeout summary")
+        return result
+
+    capabilities = wc("capabilities")["decision"]
+    require(capabilities.get("contract_version") == 61
+            and capabilities.get("storage_layout_version") == 5,
+            "unsupported CLI or storage contract; no repository operation was started")
+    for capability in ("task_workflow_version", "session_closeout_expectations_version",
+                       "session_closeout_report_version", "task_checkpoint_park_version"):
+        require(capabilities.get(capability) == 1, f"unsupported capability: {capability}")
+
+    if not args.resume:
+        run("git", "init", "--initial-branch=main", repo)
+        policy = repo / ".agents/worktree-policy.toml"
+        policy.parent.mkdir()
+        policy.write_text(POLICY)
+        (repo / "README.md").write_text("# Offline client continuation\n")
+        (repo / ".gitignore").write_text("generated/\n")
+        run("git", "-C", repo, "add", "README.md", ".gitignore", ".agents/worktree-policy.toml")
+        run("git", "-C", repo, "-c", "user.name=WC Example", "-c", "user.email=demo@example.invalid",
+            "-c", "commit.gpgsign=false", "commit", "-m", "Initialize disposable fixture")
+        wc("adopt", "--path", repo, "--task-key", "control", "--authority-key", "control",
+           "--module", "example", "--role", "control-plane", "--owner", OWNER, "--lifecycle", "ACTIVE")
+        for path, task in ((checkout, TASK), (audit, "inspection")):
+            wc("task", "start", "--task-key", task, "--owner", OWNER, "--scope", "README.md",
+               "--base-ref", "main", "--path", path)
+        original = row(checkout)
+        allocations = [original["allocation_id"], row(audit)["allocation_id"]]
+        leases = [acquire(checkout), acquire(audit)]
+        require(guard(checkout)["decision"]["code"] == "WRITE_ALLOWED", "writer refused")
+        wrong = guard(checkout, owner="another-owner", expected=1)
+        require(wrong["decision"]["code"] == "BLOCK_OWNER_MISMATCH", "owner negative control failed")
+        refused = wc("writer-lease-acquire", "--path", checkout, "--owner", OWNER,
+                     "--client-id", "competing-client", "--session-id", "competing-session",
+                     "--holder-pid", os.getpid(), expected=2)
+        require(refused["errors"][0]["code"] == "WRITER_LEASE_HELD", "competing writer was not refused")
+        (checkout / "README.md").write_text("# Offline client continuation\nClient A unfinished edit.\n")
+        (checkout / "owner-note.bin").write_bytes(b"preserve unknown task evidence\x00\xff")
+        require(guard(audit, "inspection")["decision"]["code"] == "WRITE_ALLOWED", "audit writer refused")
+        generated = audit / "generated"
+        generated.mkdir()
+        (generated / "example-owned.bin").write_bytes(b"example-owned generated fixture\x00")
+        saved = {"example": "wc-client-continuation/v1", "task": {key: original[key] for key in
+                 ("allocation_id", "task_key", "authority_key", "owner", "path", "branch", "head")},
+                 "allocations": allocations, "first_holder": leases[0]["holder"],
+                 "files": {name: (checkout / name).read_bytes().hex() for name in ("README.md", "owner-note.bin")}}
+        checkpoint_bytes = (json.dumps(saved, sort_keys=True) + "\n").encode()
+        (workspace / "task-checkpoint.json").write_bytes(checkpoint_bytes)
+        closeout(allocations, "a-before-end.json")
+        # End through the real selector while it can still observe both leases.
+        # This releases only this session's writers and retains pending owner work.
+        closeout(allocations, "a-ended.json", checking=False)
+        wc("task", "finish", "--task-key", TASK, "--owner", OWNER, "--outcome", "checkpoint",
+           "--checkpoint-id", "sha256:" + hashlib.sha256(checkpoint_bytes).hexdigest(),
+           "--checkpoint-head", original["head"], "--waiting-on", "Continue with another client")
+        partial = wc("task", "finish", "--task-key", "inspection", "--owner", OWNER,
+                     "--outcome", "no-change", expected=2)["decision"]
+        require(partial["code"] == "TASK_RELEASE_BLOCKED" and not partial["operation_complete"],
+                "partial release was reported as success")
+        closeout(allocations, "a-incomplete.json", expected=2)
+        # Only this example's exact fixture is moved. Real unknown output needs its owner flow.
+        (generated / "example-owned.bin").rename(workspace / "preserved-generated.bin")
+        generated.rmdir()
+        retried = wc("task", "finish", "--task-key", "inspection", "--owner", OWNER,
+                     "--outcome", "no-change")["decision"]
+        require([step["code"] for step in retried["operations"]] == ["RELEASED"]
+                and retried["checkout_released"], "completion was replayed")
+        final = closeout(allocations, "a-closeout.json")
+        require(final["summary"]["complete"] == 1 and final["summary"]["pending"] == 1,
+                "expected one released checkout and one unfinished checkout")
+        print(f"PAUSED: checkpoint saved; inspection released; unfinished task still needs its owner: {workspace}")
+        return
+
+    current = row(checkout)
+    require(all(current[key] == value for key, value in saved["task"].items()), "original task identity changed")
+    require(current["lifecycle"] == "RETAINED", "original task is not retained")
+    require(current["wait_checkpoint"]["artifact_id"] == "sha256:" + hashlib.sha256(checkpoint_bytes).hexdigest(),
+            "original checkpoint changed")
+    for name, value in saved["files"].items():
+        require(not (checkout / name).is_symlink() and (checkout / name).is_file(),
+                f"unfinished file is not a regular non-symlink file: {name}")
+        require((checkout / name).read_bytes().hex() == value, f"unfinished file changed: {name}")
+    refused = wc("task", "resume", "--task-key", TASK, "--owner", "another-owner", expected=2)
+    require(refused["errors"][0]["code"] == "OWNER_MISMATCH", "owner change was accepted")
+    wc("task", "resume", "--task-key", TASK, "--owner", OWNER)
+    lease = acquire(checkout)
+    require(any(lease["holder"][key] != saved["first_holder"][key] for key in ("pid", "boot_id", "start_ticks")),
+            "use a separate process to resume")
+    old = ["--client-id", "example-client-a", "--session-id", "example-client-a-session",
+           "--run-id", "example-client-a-run"]
+    require(guard(checkout, selected_identity=old, expected=1)["decision"]["code"] == "BLOCK_WRITER_LEASE_MISMATCH",
+            "old client identity still authorizes writes")
+    require(guard(checkout)["decision"]["code"] == "WRITE_ALLOWED", "new writer refused")
+    with (checkout / "README.md").open("a") as stream:
+        stream.write("Client B continued the same task.\n")
+    next_checkpoint = {**saved, "previous_checkpoint_sha256": hashlib.sha256(checkpoint_bytes).hexdigest(),
+                       "second_holder": lease["holder"], "files": {name: (checkout / name).read_bytes().hex()
+                       for name in saved["files"]}}
+    next_bytes = (json.dumps(next_checkpoint, sort_keys=True) + "\n").encode()
+    require(not (workspace / "continued-checkpoint.json").exists(), "continued checkpoint already exists")
+    (workspace / "continued-checkpoint.json").write_bytes(next_bytes)
+    closeout(saved["allocations"], "b-ended.json", checking=False)
+    wc("task", "finish", "--task-key", TASK, "--owner", OWNER, "--outcome", "checkpoint",
+       "--checkpoint-id", "sha256:" + hashlib.sha256(next_bytes).hexdigest(), "--checkpoint-head", current["head"],
+       "--waiting-on", "Example finished; business work remains unfinished")
+    final_closeout = closeout(saved["allocations"], "b-closeout.json")
+    require(final_closeout["summary"]["complete"] == 1 and final_closeout["summary"]["pending"] == 1,
+            "unfinished files must remain pending")
+    final = row(checkout)
+    require(final["allocation_id"] == saved["task"]["allocation_id"] and final["lifecycle"] == "RETAINED",
+            "continuation replaced the original task")
+    require((checkout / "owner-note.bin").read_bytes().hex() == saved["files"]["owner-note.bin"], "unknown file lost")
+    require(wc("doctor")["decision"]["code"] == "PASS", "doctor failed")
+    result = {"protocol_acceptance_complete": True, "business_task_completed": False,
+              "published": False, "checkout_retained": True, "session_closeout_complete": False,
+              "allocation_id": final["allocation_id"],
+              "first_holder": saved["first_holder"], "second_holder": lease["holder"]}
+    (workspace / "result.json").write_text(json.dumps(result, indent=2) + "\n")
+    print(f"PASS: two client processes continued one task; closeout remains pending; files and logs retained: {workspace}")
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except (OSError, RuntimeError, ValueError, KeyError, StopIteration, subprocess.SubprocessError) as error:
+        print(f"Example stopped; existing results are preserved. {error}", file=sys.stderr)
+        raise SystemExit(1) from error

{worktree_controller-1.31.0 → worktree_controller-1.32.1}/pyproject.toml

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

{worktree_controller-1.31.0 → worktree_controller-1.32.1}/pyproject.toml.orig

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

{worktree_controller-1.31.0 → worktree_controller-1.32.1}/src/worktree_controller/__init__.py

@@ -1,3 +1,3 @@
 """Worktree lifecycle controller."""
 
-__version__ = "1.31.0"
+__version__ = "1.32.1"

{worktree_controller-1.31.0 → worktree_controller-1.32.1}/src/worktree_controller/keyed_document_scope.py

@@ -1,4 +1,4 @@
-"""Prove independent Handbook records from frozen Git objects, never working files.
+"""Prove independent Nexus records from frozen Git objects, never working files.
 
 This refines only the known keyed-document overlap. It does not choose merge results,
 change declared ownership, or replace candidate validation and main publication CAS.
@@ -13,8 +13,11 @@ from pathlib import Path
 from .git_backend import _git
 from .models import ControllerError
 
-PROGRESS_PATH = "docs/handbook/business-progress.json"
-_ATTRIBUTE = f"{PROGRESS_PATH} merge=qp-handbook-progress"
+PROGRESS_PATH = "docs/nexus/business-progress.json"
+PROGRESS_PROFILES = {
+    PROGRESS_PATH: "qp-nexus-progress",
+    "docs/handbook/business-progress.json": "qp-handbook-progress",
+}
 _COLLECTIONS = {
     "tasks": "authority_key",
     "development_lines": "id",
@@ -105,11 +108,11 @@ def _blob(repo: Path, commit: str, path: str, *, limit: int = _MAX_BYTES) -> byt
     return raw
 
 
-def _progress(repo: Path, commit: str) -> tuple[str, bytes]:
+def _progress(repo: Path, commit: str, path: str) -> tuple[str, bytes]:
     attributes = _blob(repo, commit, ".gitattributes", limit=64 * 1024).decode("utf-8")
-    if _ATTRIBUTE not in attributes.splitlines():
+    if f"{path} merge={PROGRESS_PROFILES[path]}" not in attributes.splitlines():
         raise ValueError("keyed merge protocol is not declared")
-    return attributes, _blob(repo, commit, PROGRESS_PATH)
+    return attributes, _blob(repo, commit, path)
 
 
 def independent_progress_scopes(
@@ -133,7 +136,10 @@ def independent_progress_scopes(
         for right in right_paths
         if left == right or left.startswith(right + "/") or right.startswith(left + "/")
     }
-    if overlaps != {(PROGRESS_PATH, PROGRESS_PATH)}:
+    if len(overlaps) != 1:
+        return False
+    path, other = next(iter(overlaps))
+    if path != other or path not in PROGRESS_PROFILES:
         return False
     if len(left_sources) > 8 or len(right_sources) > 8:
         return False
@@ -148,9 +154,9 @@ def independent_progress_scopes(
                 base = bases[0].decode("ascii")
                 if not _OID.fullmatch(base) or base in (left, right):
                     return False
-                attributes, original = _progress(repo, base)
-                left_attributes, left_document = _progress(repo, left)
-                right_attributes, right_document = _progress(repo, right)
+                attributes, original = _progress(repo, base, path)
+                left_attributes, left_document = _progress(repo, left, path)
+                right_attributes, right_document = _progress(repo, right, path)
                 if attributes != left_attributes or attributes != right_attributes:
                     return False
                 left_keys = _changed_keys(original, left_document)

{worktree_controller-1.31.0 → worktree_controller-1.32.1}/src/worktree_controller/tool_cli_contract.json

@@ -468,7 +468,7 @@
     "contract": "integration-keyed-document-scope/v1",
     "entry_points": "normal enqueue, claim, reconcile and retry scope checks",
     "identity": "original frozen source commits, scopes and queue sequence; no mutable checkout evidence",
-    "supported_document": "docs/handbook/business-progress.json, quant-platform schema 2, unchanged committed qp-handbook-progress merge profile",
+    "supported_document": "docs/nexus/business-progress.json with qp-nexus-progress, or historical docs/handbook/business-progress.json with qp-handbook-progress; quant-platform schema 2, unchanged committed merge profile",
     "proof": "unique non-ancestor merge base for every frozen source pair; whole-record changed keys must be disjoint across tasks.authority_key and development_lines/modules/decisions.id",
     "bounds": "at most 8 sources per intent, 2 MiB regular document blobs, 64 KiB attributes blobs",
     "fail_closed": "shared record, metadata/schema/order changes, broad paths, code overlap, duplicate keys, invalid/missing/oversized Git evidence, ancestry dependency, explicit prerequisite or earlier publishing/recovery/attention state",
@@ -1071,7 +1071,7 @@
   "session_launcher_entrypoint": "worktree-session",
   "session_entrypoint": "worktree-session-end",
   "tool_name": "worktree-controller",
-  "tool_version": "1.31.0",
+  "tool_version": "1.32.1",
   "delivered_closeout_version": 1,
   "retained_archive_version": 1,
   "retention_convergence_version": 2,

{worktree_controller-1.31.0 → worktree_controller-1.32.1}/tool_cli_contract.json

@@ -468,7 +468,7 @@
     "contract": "integration-keyed-document-scope/v1",
     "entry_points": "normal enqueue, claim, reconcile and retry scope checks",
     "identity": "original frozen source commits, scopes and queue sequence; no mutable checkout evidence",
-    "supported_document": "docs/handbook/business-progress.json, quant-platform schema 2, unchanged committed qp-handbook-progress merge profile",
+    "supported_document": "docs/nexus/business-progress.json with qp-nexus-progress, or historical docs/handbook/business-progress.json with qp-handbook-progress; quant-platform schema 2, unchanged committed merge profile",
     "proof": "unique non-ancestor merge base for every frozen source pair; whole-record changed keys must be disjoint across tasks.authority_key and development_lines/modules/decisions.id",
     "bounds": "at most 8 sources per intent, 2 MiB regular document blobs, 64 KiB attributes blobs",
     "fail_closed": "shared record, metadata/schema/order changes, broad paths, code overlap, duplicate keys, invalid/missing/oversized Git evidence, ancestry dependency, explicit prerequisite or earlier publishing/recovery/attention state",
@@ -1071,7 +1071,7 @@
   "session_launcher_entrypoint": "worktree-session",
   "session_entrypoint": "worktree-session-end",
   "tool_name": "worktree-controller",
-  "tool_version": "1.31.0",
+  "tool_version": "1.32.1",
   "delivered_closeout_version": 1,
   "retained_archive_version": 1,
   "retention_convergence_version": 2,