@theaileverage/marionette 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # 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.

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.
 
@@ -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 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

@@ -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 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,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
@@ -163,7 +166,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 +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.
@@ -261,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

@@ -1,7 +1,19 @@
 # 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