@theaileverage/marionette 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 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/DESIGN.md

@@ -0,0 +1,65 @@
+# 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; no forced checkout, reset, merge, prune, or removal is issued. 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.

package/ORCHESTRATION.md

@@ -0,0 +1,109 @@
+# 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.

package/README.md

@@ -2,6 +2,10 @@
 
 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 +92,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 +146,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, 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.
+
+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:
 
@@ -220,6 +243,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.
 

package/VERIFICATION.md

@@ -0,0 +1,113 @@
+# Verification record
+
+## Outcome orchestration 0.2.0 (8 September 2026)
+
+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.