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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: worktree-controller
-Version: 1.30.6
+Version: 1.32.0
 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.6 · 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.30.6
+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.30.6 retains CLI contract **60** 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.30.6
+git checkout v1.32.0
 python examples/quickstart.py --workspace "$HOME/wc-first-run"
 ```
 
@@ -69,6 +69,17 @@ To actually change a file, publish to a local bare remote, integrate and recover
 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.
 
+## Everyday tasks
+
+Use `worktree-controller task list` to see live checkout tasks and `task show --task-key <task>`
+for the recorded owner and next formal step. The [everyday task guide](docs/daily-workflow.md)
+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.30.6 → worktree_controller-1.32.0}/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.6 · 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.30.6
+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.30.6 retains CLI contract **60** 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.30.6
+git checkout v1.32.0
 python examples/quickstart.py --workspace "$HOME/wc-first-run"
 ```
 
@@ -52,6 +52,17 @@ To actually change a file, publish to a local bare remote, integrate and recover
 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.
 
+## Everyday tasks
+
+Use `worktree-controller task list` to see live checkout tasks and `task show --task-key <task>`
+for the recorded owner and next formal step. The [everyday task guide](docs/daily-workflow.md)
+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.0/docs/client-integration.md

@@ -0,0 +1,121 @@
+# 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).
+
+## 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.32.0/docs/daily-workflow.md

@@ -0,0 +1,127 @@
+# Everyday task operations
+
+Use `worktree-controller task` for named feature/audit checkout tasks. It resolves the recorded
+path, owner and record version, then calls the existing guarded lifecycle operation. The existing
+low-level commands remain available. No separate task database or lifecycle is introduced.
+
+These entrypoints require **WC 1.31.0, CLI 61, task_workflow_version 1**. Storage layout remains 5.
+Check the installed `--version`, `capabilities --json` and `task --help` before using them. A newer
+source checkout does not update a separately installed Controller. Governed installations still
+need their normal compatibility, deployment and activation checks.
+
+Start in an already governed repository: inspect `status`, `doctor` and its selected policy;
+adopt existing checkouts explicitly. Examples below use `/project` as that repository's canonical
+checkout. These commands operate locally and do not grant permission to publish or deploy.
+
+## See the current work
+
+```bash
+worktree-controller task list --repo /project
+worktree-controller task show --repo /project --task-key report-fix
+```
+
+`list` shows live linked checkouts, their recorded owner, lifecycle, writer lease observation,
+cleanliness and any checkpoint dependency. It is not a list of all business Tasks or queued
+integrations. `show` explains the named checkout and its next formal step. After release, the
+task key queries the original lifecycle history instead of inventing a new task.
+
+Task keys can be ambiguous in imported or historical work. Mutations never pick a checkout by
+owner, age or directory order. If multiple live checkouts share a key, select its exact `--path`
+instead. Historical results retain their proof status and pagination; absence is not completion.
+
+## 1. Start and finish a task with no changes
+
+```bash
+worktree-controller task start --repo /project --task-key report-fix \
+  --owner alice --scope src/reports
+
+# An inspection that made no file changes and produced no task commit:
+worktree-controller task finish --repo /project --task-key report-fix \
+  --owner alice --outcome no-change
+```
+
+Start requires an explicit task key, owner and file scope. It defaults to feature role,
+`authority_key=task_key`, module `task`, branch `task/<task-key>`, and the repository policy's
+publication remote/branch as base. Override `--authority-key`, `--module`, `--branch`, `--base-ref`
+or `--path` when your existing task requires different values. It does not fetch or substitute
+another base when the policy base is unavailable locally. An existing live task is not duplicated.
+
+Admission creates a checkout, **not write entitlement**. Before editing, bind the real writer
+with the existing writer-session/lease flow and require `write-guard` to allow the operation.
+Use the admitted path and declared task/authority. End only that writer's exact lease before
+finishing. See [start or resume development](operations.md#start-or-resume-development).
+
+The no-change finish first records the existing `complete-no-change` result, then attempts normal
+guarded release. It retains the branch. A task commit or dirty worktree refuses no-change completion.
+Unknown ignored files or registered resources can block the separate release step. In that case,
+exit status is **2**, `TASK_RELEASE_BLOCKED` retains the completed prefix and provides a release
+dry-run command. Preserve/classify those files through their existing owner flow. Repeating this
+finish while `NO_CHANGE_COMPLETED` retries release without creating another completion receipt.
+After successful release, use `task show`; another finish refuses the absent live allocation.
+
+## 2. Pause and continue the original task
+
+First save a checkpoint in your existing Task system. Obtain its content-addressed ID and the
+exact HEAD it records. WC records that owner's attestation; it does not create or verify the
+checkpoint payload and does not copy uncommitted files into it. Then, after the writer ends:
+
+```bash
+worktree-controller task finish --repo /project --task-key report-fix --owner alice \
+  --outcome checkpoint --checkpoint-id "$checkpoint_id" --checkpoint-head "$checkpoint_head" \
+  --waiting-on 'Awaiting source data'
+
+worktree-controller task resume --repo /project --task-key report-fix --owner alice
+```
+
+The checkpoint ID must use the existing `sha256:<64 hex>` or `art_<64 hex>` format. Its HEAD
+must still match the checkout. Parking preserves the same checkout, branch, uncommitted files
+and unknown files; work remains unfinished. Resume uses the same allocation and owner, without
+creating a replacement task or writer lease. Obtain fresh write entitlement before editing again.
+This entry does not release an unfinished checkout; that remains a separate reviewed owner flow.
+
+## 3. Hand off a completed change
+
+Run appropriate tests/review and publish the task branch through your authorized Git Finalizer
+flow. Use the actual returned record and the exact commit it binds; do not invent evidence.
+After ending the exact writer:
+
+```bash
+worktree-controller task finish --repo /project --task-key report-fix --owner alice \
+  --outcome handoff --finalizer-record-id "$finalizer_record_id" --commit "$commit"
+```
+
+`TASK_HANDED_OFF` freezes the original scope and commit. It does not integrate or publish main,
+release the checkout, declare the business Task complete or authorize a production deployment.
+Continue the existing [handoff and integration](operations.md#handoff-and-integrate) flow, or use
+the complete [first change example](first-change.md). Scope/commit drift and unknown files keep
+their existing refusals. Active **or expired but still recorded** writer leases remain blocked;
+these entrypoints never steal, renew or remove them.
+
+## Inspect a blocked integration
+
+```bash
+worktree-controller task recover --repo /project --task-key original-integration-task
+# Also works after its candidate checkout has been released:
+worktree-controller task recover --repo /project --intent-id "$original_intent_id" --json
+```
+
+`recover` is a read-only entry to the existing `recovery-guide`. It shows the recorded owner,
+blockers and exact next formal command, retaining the original intent and evidence. For an
+unchanged BLOCKED integration, the supported path starts with quarantine, then formal abort,
+guarded release and retry of the original intent. Execute only the current owner-authorized
+step, then run `recover` again: every transition can change the next command and record version.
+Source/scope drift, dirty files, active publication and missing evidence still block recovery.
+The entry does not run commands, edit Controller metadata or make a recovery plan executable.
+
+## Read results accurately
+
+All actions accept `--json`. `list`, `show` and `recover` return 0 when observation succeeds,
+including when that observation describes a blocker. This is not recovery or task completion.
+Mutating actions return 0 only when the requested supported operation finishes; refusals,
+`RESOURCE_WAIT` and incomplete release return 2. A waiting admission keeps its existing request;
+inspect `admission-queue` instead of creating another task or branch.
+
+Task selectors do not replace exact session closeout. At normal session exit, use the real
+client/session/holder/run and every known expected allocation with `worktree-session-end --check
+--require-complete`; read all rows and `summary.terminal_complete`. Business Task completion,
+checkout release and published integration each require their own evidence.

{worktree_controller-1.30.6 → worktree_controller-1.32.0}/docs/first-change.md

@@ -6,6 +6,10 @@ pause after handoff and continue in a new process with the original task and int
 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.
 
+This release uses the CLI 61 [task entrypoints](daily-workflow.md) for start, handoff and
+recovery inspection; use WC 1.31.0 or newer with `task_workflow_version` 1. The underlying
+writer, review, integration and closeout guards are the same as the low-level flow.
+
 ## Install the example's tools
 
 WC itself needs Linux, Python 3.12, Git and readable `/proc`. Install the released version using

{worktree_controller-1.30.6 → worktree_controller-1.32.0}/docs/operations.md

@@ -4,9 +4,15 @@ 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
 
+For everyday feature/audit work, the [task entrypoints](daily-workflow.md) resolve the original
+checkout and record identity by task key, covering start, checkpoint/resume and finish. The
+steps below remain the underlying authority and the route for advanced integration/recovery.
+
 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
@@ -256,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.30.6 → worktree_controller-1.32.0}/docs/reference.md

@@ -1,5 +1,8 @@
 # Technical reference
 
+For the task-oriented CLI 61 entrypoints, see [everyday task operations](daily-workflow.md).
+They delegate to the existing lifecycle guards and introduce no additional stored state.
+
 For a first run, use the [getting started guide](getting-started.md). This reference retains
 the detailed contracts, historical compatibility notes and benchmark evidence previously in the README.
 The [CLI contract](../tool_cli_contract.json) is authoritative for exact interfaces.
@@ -31,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

{worktree_controller-1.30.6 → worktree_controller-1.32.0}/examples/change_task.py

@@ -99,7 +99,11 @@ def main():
         (workspace / name).write_text(json.dumps(value, indent=2) + "\n")
 
     def wc(command, *arguments):
-        value = json.loads(run(controller, command, "--repo", repo, "--json", *arguments))
+        if command == "task":
+            action, *arguments = arguments
+            value = json.loads(run(controller, command, action, "--repo", repo, "--json", *arguments))
+        else:
+            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
@@ -146,11 +150,10 @@ def main():
            "--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"]
+        acquired = wc("task", "start", "--task-key", "demo-change", "--module", "demo",
+                      "--owner", OWNER, "--branch", "demo/change", "--base-ref", "main",
+                      "--path", source, "--scope", "README.md")
+        allocation = acquired["decision"]["operation"]["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",
@@ -168,8 +171,8 @@ def main():
         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,
+        wc("task", "finish", "--task-key", "demo-change", "--owner", OWNER,
+           "--outcome", "handoff", "--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,
@@ -197,7 +200,7 @@ def main():
                 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"]
+    guide = wc("task", "recover", "--intent-id", checkpoint["intent_id"])["decision"]["guidance"]
     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")