@theaileverage/marionette 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.2.2 — 2026-09-08
+
+- Ship a Marionette agent skill with setup, task coordination, recovery, and SDK guidance.
+- Place new workers in appropriately sized sibling panes, with overflow tabs, durable creation recovery, and cleanup that preserves sibling workers.
+- Export a dependency-free Herdr SDK covering all 102 Herdr 0.9.0/protocol-22 schema methods plus persistent graphics streams, with generated TypeScript types, cancellable event subscriptions, bounded buffering, and file-frame acknowledgements.
+- Verify graphics payloads, placement, replacement, and layer cleanup through the real Herdr server/client renderer with a simulated Kitty-capable terminal. Expand the regression suite to 117 tests.
+
+## 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.

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

@@ -30,7 +30,7 @@ The lead recommends isolation based on likely concurrent file conflicts and requ
 
 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; no forced checkout, reset, merge, prune, or removal is issued. Pause/cancel/redirect during preparation is applied before worker launch.
+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.
 
@@ -38,7 +38,7 @@ Completion leaves the branch and worktree available. The lead recommends review,
 
 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.
+Before `tab.create` or `pane.split`, the run is persisted as `creating`, with the split target and pre-creation pane membership when applicable. Layout allocation is serialized per project; new workers share tabs only when all live members match saved pane-scoped run identities. Geometry and a four-pane cap determine whether to split or create another tab. 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.
 
@@ -63,3 +63,11 @@ See [ORCHESTRATION.md](ORCHESTRATION.md) for the public 0.2 contract. Outcomes,
 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 worker-pane release (legacy runs retain exclusive-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 terminal 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 terminal 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

@@ -107,3 +107,36 @@ Combine a sequential implementation/review dependency with new repair and re-ver
 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 pane. Sibling panes stay open. Legacy runs without pane-scoped ownership retain exclusive single-pane tab release. The exact workspace, tab, pane, terminal, agent name/kind and native session must still match. Changed worker identities, 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 `pane.close` (or `tab.close` for legacy runs). 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 the original pane and terminal to be absent (also the tab for legacy runs); not-closed requires the original settled identity. A later explicit release can retry a reconciled retained terminal. 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,5 +1,8 @@
 # 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
@@ -34,6 +37,21 @@ npx @theaileverage/marionette dashboard
 
 To install the shorter `marionette` command globally, use `npm install -g @theaileverage/marionette`.
 
+## Agent skill and Herdr SDK
+
+The distributable agent skill lives at [skills/marionette/SKILL.md](skills/marionette/SKILL.md). Copy the `skills/marionette` folder into your agent's skill directory (for example `~/.codex/skills/marionette`) to enable discovery. It covers lead leases, assignments, outcome completion, worker reports, recovery, and programmatic terminal control.
+
+The dependency-free ESM SDK targets Herdr 0.9.0/protocol 22. It exports typed access to all 102 schema methods, persistent event subscriptions, graphics streams, and short helpers for common operations:
+
+```js
+import { HerdrClient } from '@theaileverage/marionette/herdr-sdk';
+
+const herdr = HerdrClient.fromEnv(); // Requires a real Herdr-managed environment.
+const { panes } = await herdr.pane.list(process.env.HERDR_WORKSPACE_ID);
+```
+
+Services can pass an explicitly selected absolute socket path to `new HerdrClient(socketPath)`. Use `herdr.api["pane.resize"]({ pane_id, direction: "right", amount: 0.1 })` for the full wire API. See [the SDK guide](skills/marionette/references/herdr-sdk.md) for typed requests, subscriptions, binary/file frames, cancellation, and coverage limits. Use Marionette task APIs for managed workers; direct SDK calls do not create task records or enforce leases.
+
 ## Setup for agents and scripts
 
 The wizard and non-interactive setup use the same implementation. `--yes` accepts defaults; `--json` returns a JSON result and never prompts. Errors return `{ "ok": false, "error": "..." }` with a nonzero exit status when `--json` is used. Unknown options and config keys are rejected.
@@ -92,7 +110,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 documentation 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, thin Herdr SDK with TypeScript declarations, agent skill, built dashboard, package metadata, and documentation are distributed; local state, logs, credentials, test artifacts, and source fixtures are excluded.
 
 ## Connect Herdr explicitly
 
@@ -118,7 +136,7 @@ node dist/cli.js call project.register --file register.json
 node dist/cli.js projects
 ```
 
-Registration checks the live socket and workspace. The socket path determines the actual session; the session name is the explicit human-readable label. Each assignment creates a new unfocused tab in that workspace. No existing pane is reused. Optional `agentArgs` contains argument arrays per kind (`codex`, `claude`, `agy`) when an explicit project-specific agent configuration is needed. It defaults to no overrides.
+Registration checks the live socket and workspace. The socket path determines the actual session; the session name is the explicit human-readable label. Each assignment gets a new unfocused pane. Marionette groups up to four workers per owned tab, splitting the largest suitable pane to the right or down. It creates a new tab when no owned group has room for at least 60 columns by 12 rows per pane. Existing user panes are never reused; all live tab members must match saved Marionette terminal identities. Optional `agentArgs` contains argument arrays per kind (`codex`, `claude`, `agy`) when an explicit project-specific agent configuration is needed. It defaults to no overrides.
 
 ## Connect Codex desktop and terminal leads
 
@@ -163,7 +181,7 @@ The lead assesses likely file conflicts before dispatch: overlapping files, cros
 - 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, merge, or delete them. Ordinary Git and PR tools can operate in `task.cwd`. Retries reuse the same worktree and preserve worker commits and uncommitted changes.
+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.
 
@@ -218,6 +236,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 pane 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.
@@ -240,7 +266,7 @@ The inbox displays up to 200 unacknowledged events per page. Marking them read a
 
 - Restarting the supervisor reattaches using the saved workspace, terminal, agent name/kind, and native session identity. It does not repeat a prompt because a socket disconnected.
 - A crash during pane creation, prompt delivery, or control delivery produces an `uncertain` task. Inspect the original pane and use `task_reconcile` with `delivered` or `not-delivered` and actual evidence. Do not guess. No automatic replay occurs.
-- 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.
+- 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. For interrupted splits, the saved pre-creation membership identifies a possible new shell; moved, occupied, or ambiguous additions are refused. Original terminals 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.
@@ -261,3 +287,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/THIRD_PARTY_NOTICES.md

@@ -2258,3 +2258,211 @@ WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 ```
+
+## Herdr 0.9.0 API schema
+
+The SDK protocol types are generated from Herdr (https://github.com/herdrdev/herdr/tree/v0.9.0), licensed under Apache-2.0.
+
+```text
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+```

package/VERIFICATION.md

@@ -1,7 +1,27 @@
 # Verification record
 
+## Herdr SDK and pane layout 0.2.2 (8 September 2026)
+
+The SDK exposes all 102 methods from the installed Herdr 0.9.0/protocol-22 schema plus the documented graphics-stream transport. The 117-test suite covers generated API coverage, socket framing, event cancellation and buffer limits, graphics errors and acknowledgements, pane layout selection, interrupted creation recovery, and sibling-safe terminal cleanup. The packed SDK was imported independently and its public TypeScript types compiled in a fresh consumer.
+
+A disposable named Herdr 0.9.0 session and real attached Herdr client rendered a 120-by-80 four-color fixture through a simulated Kitty-capable PTY with 10-by-20-pixel cells. Captured terminal graphics commands contained byte-exact RGBA (38,400 bytes), RGB (28,800 bytes), converted BGRA (38,400 bytes), and PNG (289 bytes) payloads. A BGRA file frame returned the expected sequence 7 / revision 11 acknowledgement and emitted the expected RGBA pixels. All placements retained the requested 24-by-8-cell size. Frame replacement and stream closure emitted deletions for all five image IDs. The decoded renderer output was visually inspected.
+
+This verifies the installed Herdr server/client rendering pipeline and SDK transports. The outer terminal was simulated; Computer Use denied access to Ghostty, so native Ghostty display and direct-file terminal consumption were not visually verified. No existing Herdr session was controlled and no paid agent was launched. The test server and frame sources were cleaned up.
+
+## 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