@theaileverage/marionette 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## 0.2.1 — 2026-09-08
+
+- Separate verification, terminal release, delivery, evidence archival and Git collection lifecycles. Task completion continues to preserve branches and worktrees.
+- Automatic release of settled, identity-verified single-pane workers after integrated outcome completion; retained failures, native-input states and ambiguous close reconciliation.
+- Explicit merged/published/abandoned delivery, durable SHA-256 evidence archives and standalone Git bundles. Archived evidence preserves completion after checkout removal and detects tampering.
+- Opt-in retention policies, live consumer and dirty-file guards, safe worktree removal, later PR-branch collection and compare-and-delete for explicitly abandoned archived branches.
+- CLI/MCP cleanup tools, dashboard eligibility and retention controls, and regression coverage for recovery, identity changes, lease fencing, shared checkouts and evidence preservation.
+
+## 0.2.0 — 8 September 2026
+
+- Persistent outcomes, observable completion criteria, independent assessments and integrated reviews. Required descendants, current revisions and artifact digests guard completion.
+- Audited task splitting/revision/supersession, findings, scoped managed delegation, waiting-parent capacity release, and continuation in the original run and native session.
+- Shared global/project/provider/model limits and outcome execution-turn budgets.
+- Durable event-driven lead waits, grouped deliveries, ownership fencing, checkpoints, cache capability boundaries and deduplicated provider usage import.
+- 27 exact model profiles across Codex, Claude and AGY, native catalog discovery, account validation, category defaults, assignment/lead overrides and retained run configuration.
+- Bounded councils, debates, competing proposals, sequential work, independent review and repair strategies.
+- Outcome board, task-tree/dependency views, criterion and integrated-review forms, revision details, findings, limits and model controls.
+- Startup readiness recovery, interruption settling, uncertain-delivery detection and ancestor/evidence invalidation fixes discovered by real-agent acceptance.
+- Schema-2 migration preserves 0.1 task/run/lease identities. Upgrade the supervisor with the same state directory and rerun setup; workers retain their old executable paths.
+
+See [ORCHESTRATION.md](ORCHESTRATION.md) for the public contract and [VERIFICATION.md](VERIFICATION.md) for measured evidence and operating limits.

package/CONTRIBUTING.md

@@ -0,0 +1,7 @@
+# Contributing
+
+Use Node 22.13 or newer and install dependencies with `npm ci`. Run `npm run check`, `npm test`, `npm run build` and `npm run format:check` before opening a pull request. Describe the concrete behavior change and its validation. Keep tests deterministic; the standard suite must not start paid agent sessions or depend on a developer's Herdr configuration.
+
+Keep generated bundles, local agent configuration, `.env` files, `.marionette` state, `.runtime` fixtures and credentials out of commits. Live validation scripts are opt-in and use explicitly named isolated sessions. Never point them at someone else's active session.
+
+Changes enter `main` through pull requests. Release preparation and publication follow [RELEASING.md](RELEASING.md). Marionette is licensed under [MIT](LICENSE); bundled third-party licenses are preserved in `THIRD_PARTY_NOTICES.md`.

package/DESIGN.md

@@ -0,0 +1,73 @@
+# Marionette design
+
+## Process boundaries
+
+```text
+Codex desktop ── STDIO MCP ──┐
+Terminal lead ── MCP / CLI ──┼── authenticated loopback HTTP
+Browser dashboard ──────────┘              │
+                                  persistent supervisor
+                                    │             │
+                               SQLite WAL     Herdr NDJSON socket
+                                                  │
+                                      explicitly selected workspace
+                                          ├─ Codex tab
+                                          ├─ Claude tab
+                                          └─ AGY tab
+```
+
+MCP calls persist bounded intentions and return promptly. Independent supervisor loops monitor assigned panes; closing the calling conversation cannot cancel work. One process/PID lock protects each state directory. Herdr owns worker terminals and their lifecycle.
+
+## Durable records
+
+`Store` uses Node's SQLite API with WAL and synchronous FULL. Version 2 stores typed JSON documents by kind/id plus an append-only sequenced event table. Transactions group local changes before external side effects. Documents include projects, tasks, attempts/runs, lead leases (token hashes only), operations, decisions, pending/answered questions, idempotency receipts and per-consumer inbox cursors.
+
+Tasks carry dependencies, declared ownership, agent kind, objective revision, attempt budget, latest bounded output, receipt and verification. Runs retain the precise terminal/pane/tab, agent name and native session, dispatch phase, baseline digests, connection state and scoped worker-token hash. Control operations retain their phase and revision so a restart cannot silently duplicate delivery.
+
+## Execution environments
+
+The lead recommends isolation based on likely concurrent file conflicts and requests the user's choice unless already authorized. The supervisor does not make a heuristic isolation decision. An optional task `execution` selects `shared` (also the backwards-compatible default) or `worktree` with optional `baseRef`. Submission remains a nonblocking database operation; Git preparation runs asynchronously after scheduling. Ownership compares effective filesystem paths, including reserved worktree locations before creation. Dependencies and project concurrency remain in force.
+
+Managed worktrees live beneath the instance state directory, with a unique project/task path and `marionette/<task-id>` branch. Before any Git write, a durable plan records the repository and common Git directory, source and destination working directories, branch, and resolved base commit. Only committed history is checked out. A monorepo subdirectory maps to the same relative path in the new tree. The effective `task.cwd` and file checks are validated before Herdr receives that directory.
+
+The worktree lifecycle is separate from the worker run lifecycle: `planned → creating → ready`. A restart may execute a persisted plan or adopt a registered creation only after checking repository identity, branch, checkout status, and pinned commit. Ambiguous or incomplete creations fail closed and preserve all files. A ready worktree must retain its identity but may contain worker commits and dirty files, which retries preserve. Git calls use argument arrays, bounded subprocess execution, disabled hooks, and a cleared inherited Git environment; preparation issues no forced checkout, reset, merge, prune, or removal. Later cleanup uses the separately authorized lifecycle below. Pause/cancel/redirect during preparation is applied before worker launch.
+
+Completion leaves the branch and worktree available. The lead recommends review, merge, or push/PR based on the user's workflow and obtains a choice unless already authorized. These delivery actions use normal Git/hosting tools and are not automatic supervisor side effects. No task dependency implicitly integrates another branch. The structured worktree metadata is available in briefings, task reads, inbox-associated task state, and the dashboard.
+
+## State and delivery
+
+Tasks normally follow `queued → preparing → running → verifying → completed/failed`. Dependencies, concurrency and ownership can retain `queued`. Questions or native screens produce `blocked`; pause produces `paused`. Cancel/redirect await an interrupted worker before acting. The revised objective fences obsolete reports immediately.
+
+Before `tab.create`, the run is persisted as `creating`. Returned identifiers are saved before `agent.start`; the agent must become interactively ready before any task prompt is sent. `prompting` is persisted before `agent.prompt`. Native startup and input screens never trigger automatic approvals. The transport validates response IDs and handles fragmented NDJSON; loss before acknowledgement is treated as ambiguous.
+
+A crash in `creating` or `prompting`, or while a control is `sending`, requires explicit reconciliation. A run in `starting` is inspected and continued in its existing pane. Running attempts reattach; verification safely reruns. Identity mismatch suspends control. This is conservative at-most-once automatic dispatch with visible uncertainty, not a claim of exactly-once external execution.
+
+Each task is reserved synchronously before asynchronous I/O; a busy set prevents concurrent loops touching its run. Store updates merge onto the latest row so output sampling cannot erase a concurrent report or lead revision. Lead authorization is rechecked after external reads for retry/reconciliation. Explicit takeover rotates the token and increments the epoch in one transaction.
+
+## Verification and trust
+
+An agent report alone never completes a task. The supervisor also requires a settled recognized identity and passes every check. Files are bounded to the task root, artifacts to declared ownership, and default checks require freshness. Commands are trusted lead input, launched with `shell: false`, a timeout, capped output and isolated process group. Arbitrary acceptance commands may have side effects and must be chosen accordingly.
+
+Herdr output and reported evidence are untrusted data. They render as escaped React text, not HTML or executable instructions. Worker credentials authorize reports and bounded inspect/finding/delegation/revision/control operations within their assigned attempt and task subtree. The instance bearer token is administrative; anyone who can read its private file has local instance access. Lead leases prevent conflicting workflow writes among cooperative authorized clients; they are not a multi-user security boundary.
+
+Host and Origin checks plus loopback binding defend the HTTP interface against cross-site control and DNS rebinding. No public listener, remote credentials, global permission relaxation or Ghostty UI bypass is required.
+
+## Notification boundary
+
+Events persist independently of clients. Each inbox reader has its own monotonic acknowledgement cursor. Dashboard event alerts use a separate forward cursor, so an old unread backlog cannot hide a fresh completion. OS notification delivery depends on browser permission and the dashboard remaining open. MCP exposes inbox tools and server instructions; it does not claim an idle desktop-task wakeup capability.
+
+## Outcome contracts and continuation
+
+See [ORCHESTRATION.md](ORCHESTRATION.md) for the public 0.2 contract. Outcomes, digest-linked criterion assessments, integrated reviews, plan revisions, model catalogs/profiles, findings, strategies, checkpoints, native usage and lead waits are typed records alongside existing tasks. Schema migration preserves legacy identities and adds implicit outcomes. Nested mutations use SQLite savepoints.
+
+Task and outcome revisions fence asynchronous verification and plan changes. Required descendants form an acyclic completion graph together with dependencies. Changed artifacts invalidate affected work and integrated evidence. Parent yield transfers declared ownership to children after the native turn settles; resumption reuses its original run, pane and native conversation. Shared worker and lead reservations are acquired before external dispatch.
+
+Lead wait delivery persists waiting, ready, sending, delivered or uncertain state. Current lease ownership and exact native identity are checked before side effects and after asynchronous reads. Ambiguous acknowledgements never trigger automatic replay. Routine event summaries and targeted artifact/history reads reduce repeated context. Cache metrics retain missing values as unavailable and native message IDs prevent duplicate import.
+
+## Resource retirement
+
+The cleanup service separates run release from worktree delivery/archive/collection. Completed integrated outcomes enable conservative automatic single-pane tab release; failed/cancelled runs require inspection. Closure persists `closing → closed` or `uncertain`, pins the full native identity and original terminal, and never replays an ambiguous close. It does not close project sessions or workspaces.
+
+Managed-checkout collection is disabled until explicitly requested or covered by an authorized retention policy. All tasks sharing the checkout are locked during inspection; task mutations, child submission, project registration and evidence assessment are fenced while cleanup awaits external reads. Archives seal terminal tasks and preserve file evidence, run diagnostics and a Git bundle. File writes and directory entries are flushed before committing the archive record. Collection verifies live files and archive digests before non-forced worktree removal. Original task references resolve to archived bytes only after recorded collection and actual checkout disappearance; tampering still invalidates acceptance. Delivery records retain pinned HEAD/target commits. Published branches can be collected later after a new merged delivery decision. Explicit abandonment retains a bundle before compare-and-delete of the exact branch tip. Partial Git operations preserve their phase and are explicitly inspectable/retryable.
+
+Closing a native tab and invoking Git have unavoidable external-process boundaries. Herdr protocol 20 has no atomic conditional-close operation; identity is checked immediately before the close, but operators must not repurpose a tab concurrently with its cleanup. Git checks and branch-tip comparisons likewise do not replace coordination with external tools editing a checkout. Marionette fences its own concurrent mutations and refuses unsafe observed states.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The AI Leverage
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/ORCHESTRATION.md

@@ -0,0 +1,142 @@
+# Outcome orchestration in 0.2
+
+A lead defines observable criteria, dispatches bounded work, waits for meaningful events, and evaluates the integrated result. Marionette persists and enforces that contract across the full delegation tree. The same authenticated service implements CLI, MCP, and dashboard actions.
+
+## Establish the outcome
+
+Save an input file containing:
+
+```json
+{
+  "outcome": {
+    "projectId": "PROJECT_ID",
+    "key": "invoice-outcome-v1",
+    "objective": "Deliver an invoice summarizer with correct fractional cents",
+    "scope": ["src", "tests", "review"],
+    "category": "software",
+    "criteria": [
+      {
+        "id": "correctness",
+        "description": "Fractional prices total correctly and invalid prices are rejected",
+        "requiredEvidence": "Independent acceptance tests and a review artifact"
+      }
+    ],
+    "maxTurns": 60,
+    "maxDepth": 3
+  }
+}
+```
+
+```sh
+marionette call outcome.create --file outcome.json --lease /private/path/lead.json
+```
+
+Categories are `software`, `research`, `analysis`, and `decision`; evidence can be source notes, experiments, comparisons, decision records, or executable checks. Give assignments the returned `outcomeId` and its current `expectedTreeRevision`. Add `parentId` for accountable child work. Add a reason when extending the plan. Stale tree/task revisions and cycles are rejected.
+
+To finish, use `outcome.assess` for each `criterionId`, supplying the current `expectedRevision`, `rationale`, and `references` array. Then use `outcome.integrate` with an independent `summary` and `references`, followed by `outcome.complete`. Each call needs the lead lease and outcome ID. References must resolve to regular files; their digests are stored. For a managed checkout, use `task:TASK_ID:relative/owned/file`.
+
+Completion rejects any required failed, cancelled, blocked, unverified or stale task, missing criterion evidence, stale strategy result, or missing integrated review. Every required descendant must pass, and a parent must pass its own checks. An outcome with no worker tasks can still be assessed directly against real evidence.
+
+## Evolve the plan and delegate
+
+`plan.revise` requires `taskId`, `expectedRevision`, `expectedTreeRevision`, `reason`, optional evidence references, and a `patch`. Supported changes include criteria/checks, prompt, title, dependencies, required status, and explicit supersession. Create split tasks with `task.submit` or scoped delegation, then supersede the old requirement with its concrete replacement. A reason and revision history expose changes to the completion contract.
+
+New required work reopens affected parents and outcomes. Changed artifact digests invalidate affected verification and downstream work while preserving unaffected results. Routine board history contains summaries; `plan.get` reads the full before/after record on demand.
+
+A task needs `canDelegate: true` to request children. Workers receive an attempt-scoped credential and use:
+
+```sh
+marionette worker-call --file request.json
+marionette worker-report --file report.json
+```
+
+Scoped actions are `inspect`, `finding`, `delegate`, `revise`, and `control`. Mutation requests carry the current parent `revision`; delegation contains an `assignment`. Children cannot expand the parent's ownership or outcome scope, change root criteria, or control unrelated tasks. They inherit the parent's effective checkout and applicable limits. A child in a managed worktree shares its parent's branch; it does not create another checkout.
+
+After delegating, the parent reports `type: "yield"` using the returned `parentRevision`, ends its native turn, and stops editing transferred paths. Once the native turn settles, its execution slot and ownership reservation are released. Verified child results produce a compact continuation in the same parent run and native session. The parent evaluates and integrates the result before reporting completion. Pause/cancel controls cascade through descendants. Findings remain visible to the root lead.
+
+Ownership is a scheduling/reporting contract, not an operating-system sandbox. Native agent permissions remain in force.
+
+## Shared execution limits
+
+`limits.configure` accepts a reason and `limits` with `global` (1–32, default 8), `project` (1–8, default 3), optional `providers` keyed by `codex`, `claude`, `agy` (1–16), and optional exact `models` (1–16). Existing project concurrency also applies. Global/provider/model settings are shared across the instance and count activity across registered projects; configuring them updates that shared policy. Profile concurrency is 1–8, default 2.
+
+Outcome `maxTurns` is 1–1000 (default 60), shared by all worker dispatches, parent resumptions, controls that send new prompts, and automatic lead continuations. It counts Marionette-triggered execution turns, not internal tool/model calls. It is not a token or dollar spending cap. `maxDepth` is 0–6 (default 3). Queued tasks expose the limiting reason. Waiting coordinators release capacity after settling; active lead continuations reserve capacity until their native turn settles. Existing turns are not forcibly stopped when limits are reduced.
+
+## Wait without model polling
+
+`lead.wait` persists a unique `key`, `outcomeId`, a condition, and an adapter. Conditions support task `all`/`any`/`quorum`, strategy quorum, answered questions, and intervention events. Failed/cancelled results can trigger a continuation; they never count as successful outcome completion. Routine events are grouped, while blocking questions and findings can trigger prompt intervention.
+
+A Herdr adapter pins `paneId`, `terminalId`, `name`, `kind`, and the observed `nativeSession`. Only use identifiers obtained from the explicitly selected session. The supervisor verifies the original identity and current lead ownership, waits for readiness and capacity, then appends one compact delivery with a durable ID. Busy or blocked leads retain their queued delivery. Restart during ambiguous delivery produces `uncertain`, requiring inspection and `lead.reconcile`; it does not replay automatically. Handover fences the old lead and requires a fresh wait for the receiving session.
+
+For Codex desktop or another client without a supported injection API, use `{ "type": "next-message" }`. `lead.pending` retrieves the durable message on the user's next turn; `lead.ack` acknowledges it. MCP alone cannot wake an idle desktop conversation. `adapter.capabilities` states the supported boundary.
+
+On the tested Herdr 0.8.2 installation, native screen/status detection became stale when the session had no attached client. Keep a client attached to the named session for reliable native readiness observation. Marionette preserves uncertain state rather than assuming delivery succeeded. No permission prompts are automatically approved.
+
+## Checkpoints, cache and cost
+
+Wait registration saves a checkpoint with the objective, decisions, remaining criteria, and evidence references. `checkpoint.save` also accepts an explicit summary and `kind: "compaction"`; this records a deliberate compaction decision, but does not itself compact the provider conversation. Request native compaction only after saving the checkpoint and inspecting the exact settled session.
+
+Native CLIs expose no verified user-selectable cache TTL here. Retention policy therefore uses the native provider default where observable, preserves the existing session and checkpoint, and never wakes a lead merely to keep a cache alive. API cache controls are not assumed to exist in a CLI. Claude's observed 1-hour cache counters are evidence from this account, not a guaranteed lifetime.
+
+`usage.import` reads a local provider JSON/NDJSON file within the project. Supported records are Claude print results, Claude native assistant usage rows, and Codex `turn.completed` usage. Optional `runId` or `waitId` associates counters with the outcome's execution. Repeated assistant blocks and growing native transcripts are deduplicated by provider message identity. Import one representation per execution; do not combine aggregate print totals with the same run's individual transcript requests. AGY metrics and per-request native Claude dollar costs may be unavailable and remain `null`. Compaction-internal requests missing from the transcript are not silently estimated.
+
+Routine coordination excludes full output and truncates prompt/receipt text. `task.get`, artifact references, and `plan.get` provide targeted detail. The browser requests full task details for its output drawer.
+
+## Exact model profiles
+
+0.2 includes 27 selectable profiles seeded from the native catalogs inspected on 8 September 2026: seven Codex, five Claude catalog configurations plus the evaluated Fable 5 profile, and fourteen AGY configurations. These are unverified seeds until checked on the current account. Category labels describe selectable uses, not comparative benchmark rankings.
+
+`profile.discover` reads current native metadata: Codex app-server `model/list`, Claude SDK initialization model metadata, or `agy models`. It adds missing exact configurations and retains custom profiles, validation evidence, and defaults. Hidden Codex entries and ambiguous aliases are excluded. Discovery uses no model inference prompt.
+
+`profile.configure` stores exact model ID, runtime, supported effort, capabilities, strengths, delegation permission and profile concurrency. Its optional `defaults` map selects a profile by task category. `profile.validate` explicitly probes Codex/Claude with tools disabled and verifies AGY's exact model catalog membership. The validation may incur a small provider charge. Metadata discovery and AGY catalog membership are not proof that a substantive task will succeed.
+
+Assignments, council participants, and `lead --profile PROFILE_ID` can override category defaults. Setup also accepts `leadProfile` / `--lead-profile`. Explicit profile requests must validate; an unavailable model is not silently replaced. Runs retain the resolved model, effort and launch arguments separately from the display name. Unprofiled legacy runs retain their runtime defaults and label the exact model unreported.
+
+AGY effort variants are encoded in their exact model IDs; Marionette does not add an unsupported `--effort` flag. Claude context variants such as `[1m]` remain part of the exact configured value. Catalogs are account/version dependent and can change.
+
+## Collaboration strategies
+
+`strategy.create`, `strategy.contribute`, `strategy.advance`, `strategy.finish`, and `strategy.reopen` provide bounded orchestration records. Supported kinds include parallel specialists, sequential work, councils, debates, competing proposals, and review/repair. They operate on ordinary accountable tasks; they do not create untracked agents.
+
+Stage independent council/debate/proposal tasks with `deferStart: true`, then create the strategy so all participants receive the same initial protocol before dispatch. Contributions require verified participant results. Councils require quorum and a synthesis with an explicit disagreements array. Debates require fresh verified task revisions for later rounds, preserve earlier rounds, and enforce their round limit. Record claims, evidence, rebuttals, decision criteria and stop conditions. A strategy's completion never bypasses the outcome's own completion criteria.
+
+Combine a sequential implementation/review dependency with new repair and re-verification tasks when findings warrant it. Record the original finding and reason, then assess the final integrated outcome. Fable 5 successfully coordinated continuation, delegated child work, synthesized a council and re-reviewed repaired software in acceptance; it also made unsupported source inferences that needed independent correction. It is a usable candidate, not an automatic authority or a demonstrated universal best model.
+
+## Upgrade from 0.1
+
+Stop the existing supervisor, retain its state, then start 0.2 with the same `--home` and rerun setup. Database schema 2 migrates legacy tasks into persistent implicit outcomes while preserving IDs, run identity, receipts, verification, leases and setup bindings. Newer database schemas fail closed. Old runtime directories remain available to existing workers.
+
+Legacy submissions without an outcome remain compatible through implicit criteria derived from their assignment checks. New lead prompts establish an explicit outcome first. The 0.2 setup contract refuses an older running supervisor and prints the stop/start remedy instead of mixing protocol versions.
+
+## Delivery, archival and cleanup in 0.2.1
+
+Cleanup has five stages: verify the result, release execution resources, record delivery, archive evidence, and collect eligible Git resources. Task completion alone never deletes branches or worktrees. Project sessions and workspaces remain until the operator retires the project through Herdr.
+
+`cleanup.preview` takes `taskId` and returns run identities, cleanup states, blocking consumers, delivery, archive and project policy without deleting anything. The dashboard exposes these operations under **Delivery and cleanup** in task details. Every mutation requires the current lead `lease` and a meaningful `reason`.
+
+- `cleanup.release` takes `taskId` and optional `runId`. After the lead has inspected the result and decided that no native continuation is needed, it preserves bounded output and closes the settled worker's single-pane tab. Herdr has no separate worker-stop endpoint in protocol 20; closing that tab releases its terminal and worker together. The exact workspace, tab, pane, terminal, agent name/kind and native session must still match. Split tabs, busy agents, pending controls, lead waits, active dependent tasks and waiting parents prevent closure. Failed/cancelled results need this explicit inspection; their files remain intact.
+- Automatic release defaults on and waits for a completed integrated outcome, a settled completed task, and no active consumers. It runs at most once per ten-second scan. Failed, blocked, paused, yielding and uncertain work stays available. A failed preflight is retained for inspection instead of being retried continuously.
+- A close intent is durable before `tab.close`. Lost acknowledgements or restart during closure become `uncertain` and never replay automatically. `cleanup.reconcile` takes `taskId`, optional `runId`, and `resolution: "closed" | "not-closed"`. Closed requires both the original tab and terminal to be absent; not-closed requires the original settled identity. A later explicit release can retry a reconciled retained tab. Closing a tab manually is also recognized only after confirming the original terminal is absent.
+- `cleanup.deliver` records `disposition: "merged" | "published" | "abandoned"` and, except for abandonment, `targetRef`. It performs no commit, merge, fetch or push. Supply a full branch ref such as `refs/heads/main`; published work requires a refreshed remote-tracking ref such as `refs/remotes/origin/review`. The clean worktree's HEAD must be an ancestor of that target. Local remote-tracking metadata must be refreshed using the normal Git workflow first. Squash/rebase integration without ancestry proof needs manual review; it is not inferred from similar content. Modified, untracked and ignored files block delivery and collection. Preserve or remove those files explicitly; collection never forces their removal.
+- `cleanup.archive` seals all finished tasks sharing a managed checkout after every recorded worker terminal has been released and all live consumers have finished. Completed tasks require integrated outcome completion. It stores receipt artifacts, file-check evidence and referenced outcome evidence with SHA-256 digests, a manifest containing reports/checks/output and public run identity, and a standalone Git bundle retaining committed history, including abandoned unique commits. Files and directories are flushed before the durable archive record is committed. Archives live in `<state>/archives/<archive-id>` and remain private. Sealed tasks cannot resume or retry; create a new assignment for further work.
+- `cleanup.collect` requires the preview's exact `archiveId`, `taskId`, and optional `deleteBranch` (default false). It rechecks archive integrity, original worker absence, all tasks/projects sharing the checkout, Git identity, clean files, delivery ancestry and unchanged evidence. It removes the worktree through non-forced `git worktree remove`. Merged branch deletion rechecks ancestry and compares the branch tip against the archived commit with `git update-ref -d REF EXPECTED_COMMIT`; a moved tip is retained and exposes a recoverable partial result. Explicit abandonment plus `deleteBranch: true` permits compare-and-delete of the exact archived branch tip after checking that no checkout uses it. Published PR branches remain until a subsequent merged or abandoned delivery decision. That decision and branch collection can happen after the worktree has already been removed.
+
+Live files remain authoritative while the checkout exists: archival does not mask edits or stale verification. Once an authorized collection removes it, existing `task:TASK_ID:path` evidence references resolve to their verified archived bytes. Missing or tampered archived evidence still invalidates acceptance. An interrupted removal retains its phase and error; inspect and repeat `cleanup.collect` with the same archive ID. It checks whether Git actually removed the original worktree before proceeding. A branch that moved is preserved. No session, workspace, source checkout, remote branch, archive, or unrelated file is collected.
+
+`cleanup.configure` stores a project-wide authorized retention policy:
+
+```json
+{
+  "lease": { "projectId": "PROJECT_ID", "owner": "LEAD", "epoch": 1, "token": "PRIVATE" },
+  "reason": "User authorized retaining delivered work for seven days",
+  "policy": {
+    "autoRelease": true,
+    "collectAfterHours": 168,
+    "deleteMergedBranches": false
+  }
+}
+```
+
+The default `collectAfterHours: null` retains worktrees until explicit collection; the default `deleteMergedBranches: false` retains branches. A configured delay begins at recorded delivery and never bypasses checks, archives or consumers. Only completed, delivered work is automatically archived and collected; failures and abandonment require explicit actions. Revoking/changing policy before a pending side effect stops that automatic operation. Cleanup errors remain in the inbox and archive/run records for inspection. Closing the supervisor drains cleanup operations along with other work; it does not initiate cleanup during shutdown.
+
+Upgrade with `stop`, `start`, and setup using the existing state directory. The additive records retain schema 2 and existing run identities. A new supervisor is required for the cleanup tools; existing workers keep their versioned report executable paths.

package/README.md

@@ -1,7 +1,14 @@
 # Marionette
 
+[![CI](https://github.com/theaileverage/marionette/actions/workflows/ci.yml/badge.svg)](https://github.com/theaileverage/marionette/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@theaileverage/marionette)](https://www.npmjs.com/package/@theaileverage/marionette)
+
 Marionette keeps one named lead conversation available while Codex, Claude Code, and AGY specialists work in Herdr. A persistent local supervisor owns dispatch and monitoring; the lead, MCP tools, CLI, and dashboard share the same task, decision, and inbox state.
 
+## Outcome orchestration in 0.2
+
+Define persistent completion criteria, coordinate a bounded task tree, and resume a Herdr lead from meaningful worker events. Shared budgets, exact model profiles, councils/debates, independent review and repair, and the outcome board use the same durable records and completion guards. See [ORCHESTRATION.md](ORCHESTRATION.md) for APIs, limits, model discovery, cache measurements, and upgrade instructions.
+
 ## Quick start
 
 Requires **Node.js 22.13+**, **Herdr** on PATH (validated with 0.8.2 / protocol 20), and the agent CLIs you intend to use, installed and signed in. Supported host platforms are macOS and Linux. Marionette uses each agent's configured model and normal permission policy.
@@ -88,7 +95,7 @@ npm run build
 node dist/cli.js setup
 ```
 
-`npm pack` checks, tests, builds, and produces the same allowlisted tarball used for publishing. Only the bundled CLI/MCP executable, built dashboard, package metadata, and README are distributed; local state, logs, credentials, test artifacts, and source fixtures are excluded.
+`npm pack` checks, tests, builds, and produces the same allowlisted tarball used for publishing. Only the bundled CLI/MCP executable, built dashboard, package metadata, and documentation are distributed; local state, logs, credentials, test artifacts, and source fixtures are excluded.
 
 ## Connect Herdr explicitly
 
@@ -142,7 +149,26 @@ Suggested lead instructions:
 
 The dashboard supports project selection, explicit takeover/handover, assignments, dependencies, status and output inspection, decisions, inbox acknowledgement, redirects, pause, continue, cancel, bounded retry, and delivery reconciliation.
 
-An assignment requires an objective, specialist, owned paths, and at least one verification check. Paths are files or directory prefixes relative to the task working directory, not globs. Disjoint assignments run concurrently; overlapping ownership and incomplete dependencies wait. Task working directories must be within the registered project root. Register external Git worktrees as separate projects, or create them beneath the registered root.
+An assignment requires an objective, specialist, owned paths, and at least one verification check. Paths are files or directory prefixes relative to the task working directory, not globs. In a shared directory, disjoint assignments run concurrently and overlapping ownership waits. Incomplete dependencies and the project worker limit apply to every execution mode. Caller-supplied working directories must be within the registered project root. Marionette can create and manage an isolated Git worktree for an assignment.
+
+### Choosing a shared directory or worktree
+
+The lead assesses likely file conflicts before dispatch: overlapping files, cross-cutting changes, shared manifests or lockfiles, generated outputs, and uncertain scope. It **recommends an execution mode with a reason and asks the user to choose**, unless the user's existing instructions already authorize that workflow. Conflict risk does not automatically create a worktree. Marionette acts on the explicit task choice:
+
+```json
+"execution": { "mode": "worktree", "baseRef": "main" }
+```
+
+- Omit `execution`, or use `{ "mode": "shared" }`, to keep the existing behavior: run in `cwd` or the registered root. This also works for non-Git projects.
+- Use `{ "mode": "worktree" }` for Marionette to create a new branch and full Git checkout before launching the worker. `baseRef` is optional; the default is the source checkout's committed `HEAD` when preparation begins. Marionette resolves it to a commit once and persists it before creation. It never copies uncommitted or untracked source files.
+- `cwd` still identifies the source working directory. For a monorepo subdirectory, Marionette uses the corresponding directory in the new checkout. Ownership and file checks must be relative paths and are validated again after relocation. A source directory missing from the selected revision fails preparation.
+- Each managed task gets branch `marionette/<task-id>` and a checkout under `<instance-state-directory>/worktrees/<project-id>/<task-id>`. `task.worktree` exposes its state, path, branch, pinned base commit, source directory, and repository identity. `task.cwd` becomes the actual worker directory. The dashboard shows the execution choice and these details.
+- Independent worktrees can edit the same repository files concurrently. Ownership remains a filesystem-path contract; it does not predict merge conflicts or protect shared external resources. Dependencies wait for completion but do not merge another task's changes into a worktree. Select an appropriate committed base when one task needs another's result.
+- Worktree creation requires an existing Git repository and a valid commit. Failure starts no worker and never falls back silently to the shared checkout. Git hooks are disabled for supervisor worktree operations; dependency installation, submodule initialization, and other project setup remain explicit task instructions.
+
+After verification, the lead recommends a next step and asks the user to choose unless already authorized: review locally, merge, or push the task branch and open a PR through the user's Git hosting workflow. Marionette retains the branch and worktree on completion, failure, and cancellation. It does not automatically commit, publish, or merge; the separate delivery/archive/cleanup lifecycle governs later removal. Ordinary Git and PR tools can operate in `task.cwd`. Retries reuse the same worktree and preserve worker commits and uncommitted changes.
+
+For existing worktrees created outside Marionette, supply an in-root `cwd` in shared mode or register an external worktree as a separate project. Separate projects cannot have cross-project task dependencies.
 
 CLI example after obtaining a project ID and fresh briefing:
 
@@ -195,6 +221,14 @@ node dist/cli.js call decision.record --lease /private/tmp/marionette-lead.json
 
 Workers receive an attempt-scoped report credential through their new pane environment. The supplied instructions explain `worker-report --file REPORT.json`, including revision, summary, artifact paths, and evidence. Credentials are not included in briefings. Workers must request normal sandbox approval if their report command needs permission to reach the local supervisor.
 
+## Delivery and cleanup
+
+Version 0.2.1 separates terminal release from delivery and Git cleanup. After integrated outcome completion, the supervisor can save worker diagnostics and close an eligible settled worker tab automatically. Failed/cancelled work needs explicit inspection; blocked, paused, waiting and uncertain workers stay intact.
+
+Task completion preserves branches and worktrees. Use the task drawer's **Delivery and cleanup** panel or `cleanup.preview`, `cleanup.release`, `cleanup.deliver`, `cleanup.archive`, and `cleanup.collect` through CLI/MCP. Record merged, published or explicitly abandoned work, preserve evidence and committed history, then collect only the exact eligible checkout. A published PR branch stays available for later review and merge. Archives preserve completion evidence after the worktree is removed.
+
+Automatic worktree collection is disabled by default. `cleanup.configure` can authorize a retention delay and optional merged-branch deletion. Dirty/untracked/ignored files, active consumers, changed resource identities and ambiguous operations prevent removal. Project Herdr sessions and workspaces remain. See [the full cleanup contract](ORCHESTRATION.md#delivery-archival-and-cleanup-in-021) for safeguards, recovery, and API inputs.
+
 ## Handover
 
 `lead_handover` transfers control atomically and returns the receiving lead's lease and a current briefing. The previous owner/token/epoch immediately stops authorizing writes; existing workers continue.
@@ -220,6 +254,7 @@ The inbox displays up to 200 unacknowledged events per page. Marking them read a
 - If creation lost its acknowledgement, no task prompt was attempted. `not-delivered` reconciliation checks for an absent tab or one matching untouched shell. An occupied or ambiguous tab is refused. Original tabs are retained. If the identity cannot be established, resolve the named pane/session through Herdr before retrying.
 - A crash during startup blocks for inspection and continuation of the existing pane. Restart during verification reruns checks. Design checks to be safe to repeat; Marionette cannot make arbitrary commands transactional.
 - Retries require a failed/cancelled task and a settled previous worker, and consume the assignment's maximum of one to three attempts. They are explicit, never automatic for ambiguous work.
+- Managed worktree creation persists `planned → creating → ready` before worker launch. Restart reuses a matching registered checkout. A creation interrupted before `ready` is reused only if clean at the pinned base; missing, incomplete, or mismatched checkouts fail preparation for inspection without reset, pruning, or destructive recreation. Once ready, retries preserve edits. An interrupted creation that cannot be validated requires manual inspection and repair or a new assignment.
 - Ownership is a scheduling and reporting contract, **not an OS filesystem sandbox**. Agents retain their normal CLI permissions. Use isolated worktrees and each agent's permission controls where stronger isolation is required. Verification commands are trusted lead-selected local code.
 - Marionette is a single-user local product. It does not provide remote multi-user authentication, deployment, billing, automatic Git merges, or session cleanup. Preserve existing Herdr sessions and use explicit project connections.
 
@@ -237,3 +272,7 @@ npm run format:check
 The tests use isolated temporary databases and a labeled Herdr protocol double for deterministic failure injection, plus real Unix-socket transport and HTTP/STDIO MCP integration. They do not start paid agent work. The test runner needs permission to listen on local sockets.
 
 See [VERIFICATION.md](VERIFICATION.md) for the real three-agent acceptance evidence, browser results, and tested versions. [DESIGN.md](DESIGN.md) describes persistence, state transitions, and trust boundaries. `scripts/live-validation.mjs` inspects the opt-in live fixture retained on this machine; `start` intentionally refuses to duplicate an existing exercise. Its real results and private leases remain in `.runtime/`.
+
+## Contributing and releases
+
+Marionette is MIT licensed. See [CONTRIBUTING.md](CONTRIBUTING.md) for development checks and [RELEASING.md](RELEASING.md) for versioned GitHub/npm releases.

package/RELEASING.md

@@ -0,0 +1,64 @@
+# Releasing Marionette
+
+The public repository is [theaileverage/marionette](https://github.com/theaileverage/marionette). Source changes go through pull requests into `main`. GitHub Actions runs formatting, metadata validation, type checks, tests, a production build and an installed-package smoke test on Linux and macOS with Node 22 and 24. These checks use protocol fixtures, not paid agent sessions.
+
+## Prepare a version
+
+From a clean checkout, create a branch and run:
+
+```sh
+git switch -c release/0.2.1
+npm run release:prepare -- 0.2.1
+```
+
+The helper updates `package.json`, `package-lock.json`, `src/version.ts` and a dated changelog section. Replace the placeholder with concrete release notes. Do not change the setup protocol number unless the protocol changes. Update verification evidence when behavior changes, then run:
+
+```sh
+npm run format
+npm run release:check
+npm pack --pack-destination /private/tmp
+```
+
+Commit the release preparation and open a pull request. `Required CI` must pass before merging. A tag must point at a commit contained in `main`; it must exactly match the package, lockfile, runtime version and changelog. Stable versions go to npm `latest`; prereleases such as `0.3.0-beta.1` go to `next`.
+
+## Publish the merged version
+
+```sh
+git switch main
+git pull --ff-only
+git tag -a v0.2.1 -m 'Release 0.2.1'
+git push origin v0.2.1
+```
+
+The `Release` workflow rebuilds and verifies the package, publishes the tested tarball using npm OIDC, compares the registry integrity, then creates a GitHub release with the tarball and `SHA256SUMS`. It uses pinned official actions, read-only checkout credentials, a dedicated `npm` environment, and an explicitly scoped OIDC permission. No npm token is stored in GitHub.
+
+If a run fails after npm publication, rerun the failed job. Existing package integrity must match before the workflow continues; it never overwrites an npm version or a differing GitHub asset. You can also dispatch on the existing tag:
+
+```sh
+gh workflow run release.yml --ref v0.2.1 -f tag=v0.2.1
+```
+
+Do not move or delete published tags. Fix a bad release with a new version. Registry publication is irreversible in the usual release workflow; removing a GitHub release does not remove its npm package.
+
+## npm trusted publisher
+
+The package's trusted publisher must match these exact values:
+
+- Package: `@theaileverage/marionette`
+- Repository: `theaileverage/marionette`
+- Workflow: `release.yml`
+- Environment: `npm`
+- Permission: publish
+
+A package maintainer configures this once through npm's authenticated trust flow:
+
+```sh
+npm exec --yes --package npm@11.19.1 -- npm trust github @theaileverage/marionette \
+  --repo theaileverage/marionette --file release.yml --env npm --allow-publish --yes
+```
+
+npm may require fresh two-factor/browser authentication for this administrative operation. Subsequent CI publishing uses the GitHub OIDC identity. See [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) and the [npm trust command](https://docs.npmjs.com/cli/v11/commands/npm-trust/). Protect the `npm` environment so only version tags deploy; repository administrators can manage any required reviewer policy.
+
+## Initial 0.2.0 release
+
+Version 0.2.0 was published to npm before this repository existed. `.github/release-baseline.json` pins its verified registry integrity. Only this exact version may reuse the original npm tarball for its initial GitHub release; the workflow never attempts to republish it. The repository adds licensing, metadata and CI/release tooling after that publication, so rebuilding the initial repository commit need not reproduce the old package byte for byte. Future releases are built and published from their Git tags.

package/VERIFICATION.md

@@ -0,0 +1,125 @@
+# Verification record
+
+## Resource lifecycle 0.2.1 (8 September 2026)
+
+The release adds 26 cleanup regression tests to the existing suite (100 total). The cleanup fixtures use real temporary Git repositories/worktrees and SQLite databases, plus an explicitly labelled Herdr protocol double. They exercise integrated-outcome release, retained failures/native-input states, split and replaced tabs, busy workers, lead handover, lost acknowledgements and restart reconciliation, dirty/untracked/ignored files, shared-checkout and registered-project consumers, archived evidence and Git bundles, tampering, branch movement, published-then-merged delivery, explicit abandonment, policy opt-in/revocation, directory/symlink artifacts and continuation after terminal release. HTTP/STDIO integration checks all 47 MCP tools, including the seven cleanup tools.
+
+The installed Herdr protocol-20 schema was inspected for `tab.get`, `pane.list`, `agent.get`, and `tab.close`. No real user worker, tab, branch or worktree was removed in this release exercise, and no paid agent was launched. Protocol-fixture results do not claim new live native-agent acceptance; the earlier 0.2.0 exercise remains documented below.
+
+The built dashboard was checked in an isolated temporary supervisor with no real Herdr connection. Cleanup eligibility rendered the retained worker and blocking reasons. A seven-day retention policy saved and reloaded through the UI. Screenshots were visually inspected at desktop and 390-pixel mobile width; the mobile drawer and document both measured 390 pixels with no horizontal overflow. The test used private fixture state and left production project bindings untouched.
+
+Release gates: formatting, TypeScript checks, release metadata, the full suite, production build, packaged-install smoke, and the Linux/macOS Node 22/24 CI matrix. Evidence archival flushes files/directories before recording success; collection retains an explicit phase through interruptions and rechecks identity/integrity before removal. Herdr does not provide an atomic conditional-close primitive, so external operators must not repurpose a tab while cleanup is closing it.
+
+## Outcome orchestration 0.2.0 (8 September 2026)
+
+Published `@theaileverage/marionette@0.2.0` publicly with the `latest` tag. The registry integrity exactly matches the tested tarball, and an independent fresh-cache registry install returned version `0.2.0`. All required validation, including the cold-resume probe, passed before publication.
+
+The release candidate implements the complete outcome lifecycle. The current suite has **72 tests** covering recursive completion and an in-flight verification race, late requirements, artifact invalidation, cycles, scoped delegation, shared capacity/budgets, native identity fencing, ambiguous delivery, legacy migration, model discovery/validation and actual HTTP/STDIO MCP/CLI parity. Protocol doubles are explicitly separated from the real agent exercise below.
+
+### Real supported-agent acceptance
+
+An isolated named Herdr session ran eleven tracked tasks using Codex `gpt-6-astra` high, Claude `claude-fable-5` high and AGY `gemini-3.1-pro-high`. The persistent outcome completed at tree revision 25 after all four criteria and a separate integrated review passed. The source corpus was a controlled synthetic fixture, not a production benchmark.
+
+- **Research council:** Fable and AGY independently evaluated the same source corpus, disagreed about adaptive versus fixed concurrency, and produced verified artifacts. A separate Fable synthesis was revised after lead review. The final lead decision preserves disagreement and explicitly rejects unsupported per-job retry guarantees and zero-all-cause-retry claims.
+- **Bounded debate:** Codex and Fable produced independent round-one claims and fresh verified round-two rebuttals in their original sessions. The strategy retained all four contributions and stopped after two rounds. The final decision records disagreement over stress-test vetoes and a remaining unsupported affected-job bound in Fable's argument. No proposed production experiment was actually run.
+- **Nested delegation:** a Codex coordinator requested a registered Fable child, yielded capacity and ownership, resumed its original run/native session on the child's result, and independently integrated it. The supervisor's nested acceptance command passed.
+- **Review and repair:** Codex implemented a summarizer against an intentionally flawed helper. AGY independently identified `0.29 → 28`, `1.15 → 114`, and invalid-input handling. A targeted Codex repair and independent Fable re-verification passed both basic and fractional-cent acceptance commands. The reviewer documented half-cent rounding as outside the fixture's two-decimal contract.
+- **Restart and interruptions:** the isolated supervisor was restarted repeatedly while preserving worker IDs and sessions. Real startup races, a waiting-parent monitor race and an AGY interruption that swallowed an acknowledged continuation were reproduced and fixed. The ambiguous AGY delivery was explicitly reconciled after inspecting the exact idle pane; its report was then submitted from the same native conversation. No worker report was fabricated by the test harness.
+
+Native CLI versions observed: Codex 0.153.4, Claude Code 2.1.263, AGY language server 1.1.27; Herdr 0.8.2/protocol 20. On this Herdr installation, an attached client was necessary for fresh terminal/status observation. This operating requirement is documented; a fully detached headless session is not claimed as validated. Specific native permission prompts were inspected and approved individually, without disabling native safeguards.
+
+### Model profiles
+
+Live metadata extraction returned seven public Codex models, five exact Claude catalog configurations and fourteen AGY configurations. Together with the evaluated Fable 5 profile, the package includes **27 profiles**. Discovery preserves existing validation and custom defaults. Exact Codex Astra/Luna and Claude Fable 5/Fable 5.1 `[1m]`/Sonnet 5/Haiku 4.5 response probes passed; AGY Gemini 3.1 Pro high and Gemini 3.8 Flash high catalog checks passed. Only the three models in the task exercise above were evaluated on substantive assignments. Catalog inclusion is not an account-independent performance or availability guarantee.
+
+Fable was effective at continuation, child work, synthesis and software re-verification. Its source-analysis errors demonstrate why independent review remains required. Category labels and descriptions are not benchmark rankings.
+
+### Event continuation and cache evidence
+
+The pinned Claude lead waited **2,234.497 seconds (37 minutes 14.497 seconds)** without model polling, then automatically wrote the correct delivery ID and a phrase retained from the original conversation. First resume request: **45,340 cache-read tokens, 1,141 cache-write tokens, 2 uncached input tokens**. The next request read 46,481 cache tokens and wrote 398. Provider counters classified the writes as ephemeral one-hour cache entries; no configurable native TTL or future guarantee is inferred.
+
+Deliberate native compaction reduced reported context from **47,009 to 5,683 tokens**, dropping 41,326. A durable checkpoint preceded it. A second event wait of **75.097 seconds** resumed the same conversation with the correct delivery ID and phrase. Its first request read **30,218** cache tokens and wrote **10,826**, with 2 uncached input tokens; the next read 41,044 and wrote 334. Compaction retained some prefix reuse while requiring new cache writes. Six unique native assistant requests were imported without duplicate message blocks. Native transcript dollar cost and any hidden compaction request usage are unavailable, not zero. No cache-only wakeup was scheduled.
+
+The fresh-conversation checkpoint recovery probe also passed. A new Claude Fable 5 session, with tools and MCP disabled, received only a synthetic checkpoint and returned both the exact recovery phrase and the correct remaining action. Its session ID differed from the original lead. Provider-reported usage was **0 cache-read tokens, 3,911 cache-write tokens, 2 uncached input tokens and 94 output tokens**, with a provider-reported list-price cost of **$0.08294**. These measurements establish an observed cold cache for this probe, not a guarantee that every new conversation starts cold. This test verifies minimal checkpoint recovery; the longer real orchestration exercise above verifies same-session continuation and integration.
+
+### Package checks
+
+The exact 0.2.0 candidate tarball was installed with an independent offline npm cache. Its CLI returned 0.2.0, setup schema exposed `leadProfile`, and supervisor health reported setup contract 2. The dashboard and all 40 bundled STDIO MCP tools worked after deleting that isolated cache; the copied runtime had no `node_modules`. The test supervisor was stopped afterward. Setup also reused the live acceptance project's original name, workspace and lease under 0.2 without installing a global MCP registration.
+
+The tarball has 12 allowlisted files (about 630 kB compressed, 2.7 MB unpacked): bundled CLI/MCP, built dashboard, package metadata, license notices and documentation. No state database, credentials, logs, provider transcripts, test projects or screenshots are included. The final release target is `@theaileverage/marionette@0.2.0`; the publisher verifies the registry tarball integrity against this tested artifact.
+
+### Board and compatibility
+
+The browser created an outcome, rejected a missing evidence reference, recorded criterion and integrated assessments separately, completed the outcome, revised its criteria with a reason, and observed it reopen. Lazy before/after history reads, recursive task cards, dependency navigation and the mobile task drawer were exercised. An outcome-switch form-value leak was found and fixed by resetting the form for each outcome/revision.
+
+At **375, 414, 768, 1024 and 1440 px**, document width equaled viewport width. The 375 px task drawer fit the full viewport. Axe-core 4.12.1 found **zero WCAG 2 A/AA violations** on desktop and mobile; mobile reported four partly clipped horizontal-navigation items whose contrast could not be automatically assessed. Visible controls were visually inspected. This is not a complete accessibility certification.
+
+Schema-2 migration tests preserve v0.1 task IDs, runs, receipts, verification and lead leases. A real Git regression confirms that delegated children inherit a managed checkout outside the registered root without creating an extra worktree, while task-scoped evidence rejects traversal. Transport tests create an outcome through MCP, submit a paused assignment through the actual CLI, read it through HTTP/board, and reject unauthorized worker access and premature completion.
+
+Private reproducibility inputs and provider artifacts remain under `.runtime/v02-live/`; they are excluded from npm. Opt-in scripts are `scripts/live-v02.mjs`, `scripts/cache-v02.mjs`, `scripts/restart-acceptance.mjs` and `scripts/board-validation.mjs`. These use an explicitly named isolated session and refuse duplicate exercise stages. The earlier v0.1 evidence below is historical and does not replace these 0.2 checks.
+
+## Managed worktrees (8 September 2026)
+
+The suite now includes **43 tests**, with 12 new real-Git regression cases for managed execution. Checks cover simultaneous same-file tasks in separate worktrees alongside a shared task, independent completion checks in the new directory, whole-directory ownership before checkout creation, concurrency/dependency waiting, invalid repositories and base refs, monorepo subdirectories, retained worker commits and dirty files on retry, restart adoption without duplicate creation, incomplete/colliding checkout preservation, cancellation during Git creation, absolute-path refusal and symlink revalidation, and changed-branch refusal. Herdr remains a labeled protocol double in these cases; no paid agent work or remote push/PR was performed.
+
+Server/dashboard/test type checks and the production build pass. The HTTP/STDIO MCP and Unix-socket tests pass with local socket permission; the filesystem sandbox initially denied their listeners. The new execution selector and optional base field were exercised through the real dashboard form against a temporary server with worker dispatch stopped. The saved assignment retained `execution: {mode: "worktree", baseRef: "main"}`. Worktree details were inspected using an explicitly seeded display fixture, separate from the earlier live integration exercise below. Form checks at 375, 414, 768, 1024 and 1440 px found no page overflow; both new controls are 44 px high. Long selector labels were shortened after mobile visual inspection.
+
+Lead instructions now require a reasoned recommendation and the user's choice for isolation and delivery unless already authorized. No automatic merge, push, PR, or cleanup policy was added. This validation updates the source and built artifacts; it does not replace or restart an existing installed supervisor or MCP client.
+
+## Earlier validation
+
+Validated locally on 8 September 2026 (Asia/Kolkata). The product is running at `http://127.0.0.1:4380`; obtain its private access link with `node dist/cli.js dashboard`.
+
+## Real integration exercise
+
+The isolated Herdr session was `marionette-validation`, workspace `w1`, project `71013dce-ccb2-4758-868b-5bd85e0f0085`. Existing sessions and panes were preserved. The supervisor used Herdr 0.8.2's supported protocol-20 socket API, not GUI control or fabricated caller variables. Models were inherited from the user's installed agent configuration.
+
+| Path                     | Observed result                                                                                                                                                                                                                                                                                                                  |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Nonblocking MCP dispatch | Three real submissions returned in 8.0, 7.2 and 9.0 ms while workers started independently. The desktop conversation continued during execution.                                                                                                                                                                                 |
+| Codex backend            | Task `ecad0278-0834-43d6-b12a-d27e37afc63a`, pane `w1:p3`, attempt 1, revision 3. Reported a currency question, received INR, implemented the ledger. Independent artifact digest and Node acceptance checks passed.                                                                                                             |
+| Claude design            | Task `e70877ea-c74a-448e-9cbd-27387ceff737`, pane `w1:p4`, attempt 1, revision 2. Redirected from compact to comfortable density during execution. Independent checks confirmed fresh invoice HTML and comfortable layout metadata.                                                                                              |
+| AGY review               | Task `7727932b-c39f-435f-b7fa-39601c0b5efa`, pane `w1:p2`, attempt 1, revision 2. Normal native read/write/report permissions were resolved individually. Recovery review artifact passed an independent content and digest check.                                                                                               |
+| Concurrent work          | Backend and design occupied distinct live worker tabs with disjoint ownership. The third review task also ran independently.                                                                                                                                                                                                     |
+| Shared decisions         | Currency and density decisions persisted, appeared in the dashboard and were read by the terminal lead.                                                                                                                                                                                                                          |
+| Handover                 | Desktop-validation lease handed to terminal-validation at epoch 2. The old lease failed a write with `stale_lead`. A real Codex lead in `w1:p5` confirmed `HERDR_ENV=1`, used Marionette MCP briefing/inbox/decision tools, and recorded decision `f43a5af5-85d6-4bec-ac68-e06c6bff0889`. No CLI fallback was used by that lead. |
+| Crash recovery           | The identified supervisor process was deliberately killed during the exercise and restarted with its existing database. Run IDs, pane IDs and attempt counts were unchanged. Running/blocked workers continued; no duplicate task dispatch occurred.                                                                             |
+| Desktop discovery        | Project-only config was visible to Codex CLI but did not appear in a fresh desktop task. With explicit user approval, the same server was added through `codex mcp add` at user level. The user confirmed Marionette appeared and connected after refresh.                                                                       |
+| Dashboard controls       | Explicit takeover, task-detail output, native-key input, decision creation, dependency-blocked assignment creation, queued pause and cancel all worked against the live store. The cancelled UI-only task remained at attempt 0; no worker was created for it.                                                                   |
+
+Private evidence is retained under `.runtime/`: `live-state.json`, `live-verification.json`, `terminal-lead-receipt.json`, `automated-tests.txt`, browser audit results, and `.runtime/workflow/` worker artifacts. Lease files contain credentials and are deliberately ignored by version control.
+
+The review surfaced a preparation reservation that could stick across restart, interruption without a deadline, missing orphan-pane reconciliation, and missing artifact ownership validation. These were fixed and covered by regression tests. The review artifact is retained as the worker's original assessment, so some findings describe the earlier source snapshot.
+
+## Automated checks
+
+**25 tests passed**, with no skipped tests. `npm run check` typechecks server, dashboard and tests; `npm run build` succeeds; `npm run format:check` succeeds.
+
+Coverage includes nonblocking/idempotent submissions, conflicting keys, lead fencing, overlapping ownership, dependencies, incorrect and obsolete reports, independent acceptance failure/success, redirect ordering, blocked replies, ambiguous dispatch without replay, database restart, replaced pane identity, retry limits, traversal/symlinks, command timeouts, concurrent stale snapshots, late reports, prompt-acknowledgement races, orphan pane recovery/refusal, interactive startup readiness, artifact ownership, bounded interruption, preparation recovery, real fragmented Unix-socket transport, HTTP bearer/Origin/Host rejection, process-lock refusal, and actual STDIO MCP initialization/list/call/error handling.
+
+The protocol double used for failure injection is explicitly labeled; it is separate from the real three-agent evidence above. The HTTP/MCP test launches an actual isolated local server and STDIO client and does not incur worker-model usage.
+
+## Browser checks and limits
+
+- The final overview has **zero detected WCAG 2 A/AA violations** in axe-core 4.12.1. This automated audit is not a complete accessibility certification.
+- The actual dashboard was measured at widths **375, 414, 768, 1024 and 1440 px**: document scroll width equaled viewport width at each size.
+- Controls were exercised through browser forms; no simulated task completion was written to the database. Dashboard handover downloaded a valid receiving lease and disabled stale controls. Inbox acknowledgement cleared only the browser consumer.
+- A real CLI-initiated handover produced the matching in-app notification on the open dashboard. The observed notification text is retained in `.runtime/notification-verification.txt`. Final desktop control belongs to `codex-desktop`; its private lease is `.runtime/desktop-lead-lease.json`.
+- A test-browser session unexpectedly reset to `about:blank` during validation. Its session authentication was restored normally and the dashboard rechecked. Durable tasks, decisions, worker identities and the supervisor were unaffected.
+- An idle Codex desktop task is **not automatically awakened**. The working path is durable MCP inbox plus the open dashboard. Browser/OS notification delivery depends on permission and an open page; native OS banner delivery has not been separately tested.
+- The generated Claude invoice fixture passed static and supervisor acceptance checks; it was not subjected to a separate screen-reader certification.
+- No required external connection remains blocked. The runtime is local and manually started after a machine reboot. Strong filesystem isolation is delegated to worktrees and the agents' normal permission systems; ownership is not an OS sandbox.
+
+Integration references consulted: [Herdr socket API](https://herdr.dev/docs/socket-api), [Herdr agents](https://herdr.dev/docs/agents), and [Codex MCP documentation](https://learn.chatgpt.com/docs/extend/mcp). The installed Herdr schema and CLI were inspected before integration.
+
+## npm release and guided setup (0.1.0)
+
+The release adds six regression tests, bringing the suite to **31 passing tests**. New coverage verifies conservative AGY settings updates, malformed settings and concurrent-edit refusal, read-only setup planning, preserved setup preferences, private file permissions, durable runtime reuse after package deletion, all lead-client command argument shapes, and agent identity through fenced handover.
+
+A tarball was installed with `npm exec --offline --package=/absolute/package.tgz` from an independent temporary project. Setup started its own named Herdr session, selected free port 4381 while the original instance remained running, and registered exactly one workspace. Repeating setup preserved the workspace, custom name, lead epoch, and AGY trust entry. Actual Codex, Claude Code, and AGY CLI MCP registrations and reruns passed using an instance-specific test server name. No worker models were invoked by these setup tests.
+
+After deleting that test's npm cache, the supervisor and dashboard still worked, and the standalone bundled MCP server initialized, listed all 14 tools, and returned the correct project briefing. The copied runtime had no `node_modules` directory. `lead --print` discovered the project from a nested directory. Results are retained privately in `.runtime/package-smoke.mjs` and `/private/tmp/marionette-release-check/smoke-result.json`.
+
+The npm tarball uses an explicit files allowlist and includes bundled dependency license notices. State databases, private leases, credentials, screenshots, test projects, and local logs are excluded. Human lead launch preserves the normal CLI trust and permission prompts; native terminal interaction for the new launch shortcut was not separately automated.
+
+Published `@theaileverage/marionette@0.1.0` publicly to npm with the `latest` tag. The public registry integrity matches the locally verified tarball, and a fresh-cache download through `npm exec` returned version `0.1.0`. Temporary MCP registrations and the isolated release-test Herdr session were removed; the original instance was preserved.