@theaileverage/marionette 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.4.0 — 2026-09-08
+
+- Add interactive setup with editable defaults, required-tool preflight, explicit installation options, and recovery for missing Herdr workspaces without losing project identity or history.
+- Open terminal leads in dedicated Herdr tabs, reuse verified sessions, and restart exited leads only after confirming an idle shell. Give each project a readable MCP registration and migrate owned legacy entries.
+- Add instance-wide update and upgrade commands that migrate saved project bindings and MCP registrations together, preserve worker terminals and lead leases, and restore the previous runtime and database if startup fails.
+- Add previewable project removal and instance uninstallation with active-work, terminal-identity, shared-resource, and retained-worktree checks. Preserve project source files and restore only workspace trust settings owned by Marionette.
+- Manage native workspace trust for Codex, Claude Code, and AGY, including managed worktrees, while preserving agent tool-approval and sandbox settings.
+- Consolidate lead, worker, strategy, delegation, and follow-up instructions into editable Mustache templates embedded in the distributed executables. Preserve literal task data, scoped ownership, revision fencing, and independent verification.
+- Expand regression coverage to 189 tests, including runtime rollback, setup recovery, MCP migration, terminal reuse, trust restoration, and prompt rendering.
+
 ## 0.3.0 — 2026-09-08
 
 - **Runtime change:** the CLI and supervisor now require Bun 1.3.14+. `npx` remains supported when Bun is on PATH. Development, tests, and CI use Bun with a frozen lockfile.

package/CONTRIBUTING.md

@@ -2,6 +2,24 @@
 
 Use Bun 1.3.14 or newer and install dependencies with `bun install --frozen-lockfile`. Run `bun run check`, `bun run test`, `bun run build` and `bun 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.
 
+Edit the lead prompt in [`src/templates/lead.mustache`](src/templates/lead.mustache).
+It is a plain-text Mustache template shared by setup, lead launch, and MCP
+instructions. The optional `session` section receives `leadName`, `projectName`,
+`projectId`, and `leasePath`; triple braces preserve their literal text without
+HTML escaping. Keep session-specific details inside that section. Run
+`bun test tests/prompts.test.ts tests/lead-terminal.test.ts` to check rendering
+and terminal compatibility. Source commands load template edits on their next
+start; run `bun run build` to embed them in the distributed CLI and MCP bundles.
+
+Worker wording lives beside it: `worker.mustache` contains the assignment,
+scope, inspection, worktree, and reporting instructions; `worker-delegation.mustache`
+and `worker-strategy.mustache` are conditional partials; `worker-followup.mustache`
+handles child results, lead answers, and replacement objectives. Task data and
+shell-quoted CLI commands are prepared in `src/prompts.ts` and `src/supervisor.ts`.
+Use triple braces for literal text and the prepared `*Json` fields inside JSON
+examples. Templates and partials are embedded during the same build. Run
+`bun test tests/prompts.test.ts tests/orchestration.test.ts` after worker edits.
+
 The project pins Bun, Effect v4, and TypeScript 7. Commit `bun.lock`; do not generate an npm lockfile. `bun install --frozen-lockfile` runs the `prepare` script to
 patch the local TypeScript and Oxlint binaries with `@effect/tsgo`. If dependencies
 were installed with lifecycle scripts disabled, run `bun run prepare` before

package/README.md

@@ -12,7 +12,7 @@ Coordinate Codex, Claude Code, and AGY workers through one lead conversation. Wo
 
 ## Quick start
 
-Requires **macOS or Linux**, **Bun 1.3.14+**, **Herdr** on PATH, and your chosen agent CLIs installed and signed in.
+Requires **macOS or Linux** and **Bun 1.3.14+**. Setup checks Git, Herdr, and the selected lead CLI before creating project state. It reports other agent CLIs as optional workers.
 
 From your project directory:
 
@@ -22,7 +22,11 @@ bunx --bun @theaileverage/marionette setup
 
 You can also use `npx @theaileverage/marionette setup`. Bun must still be installed and on PATH; `npx` downloads the package but does not install Bun.
 
-Setup starts the supervisor, connects a named Herdr session and project workspace, and configures MCP for your chosen lead: Codex desktop, Codex CLI, Claude Code, or AGY.
+The interactive setup uses editable defaults and arrow-key choices. It offers to install missing required tools, then starts the supervisor, connects a named Herdr session and project workspace, and configures MCP for Codex desktop, Codex CLI, Claude Code, or AGY.
+
+Setup installs Herdr through Homebrew when available, or its [official installer](https://herdr.dev/docs/install/); Git through existing Homebrew; Codex through npm when available; and Claude Code through its official installer. AGY and Git without Homebrew require manual installation. Agent sign-in remains a separate step. Setup does not install every optional worker or change existing agent integrations.
+
+The project defaults to your current directory. To select Menderly from another directory, for example, pass `setup --project /path/to/menderly`.
 
 For a terminal lead:
 
@@ -30,6 +34,10 @@ For a terminal lead:
 bunx --bun @theaileverage/marionette lead
 ```
 
+The terminal lead opens in a dedicated tab in the project’s Herdr session. Repeating `lead` focuses the existing lead without resending its prompt. If the lead has exited and its tab contains a verified idle shell, `lead` starts it again in that tab. If a process is still present or its state is uncertain, `lead` opens the tab for inspection without sending a launch command. Detach with `Ctrl-B q`; the lead and workers keep running.
+
+Setup names each project’s MCP entry `mnett-<project>-<lead>`, such as `mnett-menderly-mendy`. Names use lowercase words and hyphens, with a numeric suffix when needed to avoid collisions. `--mcp install` installs the entry and migrates owned older names; `--mcp print` prints a command with shell quoting only where needed.
+
 For Codex desktop, refresh MCP in Settings and give your conversation the prompt file printed by setup.
 
 ```sh
@@ -37,7 +45,38 @@ bunx --bun @theaileverage/marionette dashboard  # Print the private dashboard UR
 bunx --bun @theaileverage/marionette doctor     # Diagnose connections
 ```
 
-For scripted setup, use `setup --yes --json`; `setup --help` and `setup --schema` describe the available options. Install globally with `bun add --global @theaileverage/marionette` for the shorter `marionette` command.
+For scripted setup, use `setup --yes --json`. Add `--install-tools` to explicitly allow installation of missing required tools; `--yes` alone only accepts configuration defaults. `--dry-run` prints the plan without installations or writes; `setup --help` and `setup --schema` describe the available options. Install globally with `bun add --global @theaileverage/marionette` for the shorter `marionette` command.
+
+If an older cached package fails on `node:sqlite`, run `bunx --bun @theaileverage/marionette@latest setup`. Marionette 0.3.0 and later use Bun’s SQLite runtime.
+
+Setup's `trustWorkspaces` option registers native workspace trust for Codex, Claude Code, and AGY as each lead or worker starts, including managed worktrees. Use `--no-trust-workspaces` to keep native trust prompts, or `--trust-workspaces` to enable it explicitly. Tool approvals and sandbox settings remain controlled by each agent. Legacy AGY-only settings remain compatible and do not silently authorize trust for other agents.
+
+## Update and removal
+
+```sh
+marionette update --check           # Compare installed and published versions
+marionette update                   # Upgrade this instance and detected global CLI packages
+marionette upgrade                  # Alias for update
+marionette update --from /path/to/built/marionette  # Use a local build
+```
+
+An instance can serve several projects. Updating moves all its saved project bindings and owned MCP registrations together, restarts the supervisor, and preserves worker terminals, assignments, and lead leases. A failed restart restores the previous runtime and database. Recovery files are retained only if rollback needs attention. Refresh or restart agent MCP clients afterward. `--runtime-only` leaves the global CLI package unchanged; `--home DIR` selects another instance. Global package-manager failures are reported separately from the runtime migration and can be retried.
+
+Setup detects a different saved or running runtime and offers the same migration. For scripts, use `setup --yes --upgrade`; without `--upgrade`, setup reports the required update command before changing project state.
+
+`setup --upgrade` also refreshes a changed local build with the same version number. If a saved Herdr workspace no longer exists, setup finds or creates its replacement and reconnects the existing project while preserving its ID, lead lease, and history. Active tasks and unresolved operations must be resolved first. An explicitly supplied `--workspace` must exist.
+
+```sh
+marionette remove --dry-run         # Preview removal of the current project
+marionette remove                   # Confirm removal interactively
+marionette remove --project /path/to/project --yes
+marionette uninstall --dry-run --global
+marionette uninstall --global       # Remove this instance and detected Bun/npm global CLI installs
+```
+
+Project removal deletes its binding, leases, stored project history, and archives, and restores workspace trust settings that Marionette added. Its MCP registrations are removed while other projects’ entries remain. Legacy shared MCP registrations remain until the final project is removed or all dependent projects have their own entries. Uninstallation deletes the selected instance's state, logs, runtimes, and recovery files. Project source files and Git branches are preserved; collect or relocate managed worktrees before removal. Shared instance logs and any failed-upgrade recovery files remain after individual project removal.
+
+Removal previews active tasks, pending operations, and terminal ownership before making changes. Exit lead/worker agents first, or explicitly use `--stop-agents` to close verified project agents. Use `--keep-herdr` to retain terminal resources, including offline sessions. Herdr itself and the coding-agent applications remain installed. Noninteractive removal requires `--yes`; `--json` provides structured output. `--project-id ID` can remove an orphaned project whose source directory no longer exists.
 
 ## How it runs
 

package/THIRD_PARTY_NOTICES.md

@@ -2,6 +2,38 @@
 
 These libraries are included in Marionette’s executable and dashboard bundles.
 
+## @clack/core 1.5.0
+
+License: MIT
+
+```text
+MIT License
+
+MIT License Copyright (c) 2025-Present [Bombshell contributors](https://bomb.sh/team)
+
+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.
+```
+
+## @clack/prompts 1.8.0
+
+License: MIT
+
+```text
+MIT License
+
+MIT License Copyright (c) 2025-Present [Bombshell contributors](https://bomb.sh/team)
+
+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.
+```
+
 ## @modelcontextprotocol/sdk 1.30.0
 
 License: MIT
@@ -749,6 +781,62 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
+## fast-string-truncated-width 3.0.3
+
+License: MIT
+
+```text
+The MIT License (MIT)
+
+Copyright (c) 2024-present Fabio Spampinato
+
+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.
+```
+
+## fast-string-width 3.0.2
+
+License: MIT
+
+```text
+The MIT License (MIT)
+
+Copyright (c) 2024-present Fabio Spampinato
+
+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.
+```
+
 ## fast-uri 3.1.7
 
 License: BSD-3-Clause
@@ -786,6 +874,36 @@ The complete list of contributors can be found at:
 - https://github.com/garycourt/uri-js/graphs/contributors
 ```
 
+## fast-wrap-ansi 0.2.2
+
+License: MIT
+
+```text
+MIT License
+
+Copyright (c) 2025 James Garbutt
+
+Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
+
+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.
+```
+
 ## finalhandler 2.1.1
 
 License: MIT
@@ -1383,6 +1501,24 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
+## mustache 4.2.0
+
+License: MIT
+
+```text
+The MIT License
+
+Copyright (c) 2009 Chris Wanstrath (Ruby)
+Copyright (c) 2010-2014 Jan Lehnardt (JavaScript)
+Copyright (c) 2010-2015 The mustache.js community
+
+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.
+```
+
 ## negotiator 1.1.0
 
 License: MIT
@@ -2041,6 +2177,34 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
+## sisteransi 1.0.5
+
+License: MIT
+
+```text
+MIT License
+
+Copyright (c) 2018 Terkel Gjervig Nielsen
+
+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.
+```
+
 ## statuses 2.0.2
 
 License: MIT

package/VERIFICATION.md

@@ -1,5 +1,15 @@
 # Verification record
 
+## Project lifecycle and prompt templates — 0.4.0 local acceptance
+
+Verified locally on macOS arm64 with Bun 1.3.14. The complete suite passed **189 tests across 20 files**. New coverage includes instance-wide runtime and MCP migration, rollback after failed startup, project removal and shared-resource preservation, native workspace trust restoration, missing-workspace recovery, terminal-lead reuse, and literal Mustache rendering for lead and worker instructions.
+
+`bun run check`, `bun run format:check`, `bun run release:check`, and `bun run tooling:check` passed. Full `bun pm pack` prepack validation passed, including runtime lifecycle checks and the production build. The resulting 0.4.0 tarball installed in an isolated temporary consumer and passed CLI version, read-only setup planning, standalone Herdr SDK, and TypeScript declaration checks without an installed Effect dependency.
+
+Worker prompt tests cover all six collaboration strategies, optional delegation and worktree sections, current-revision follow-ups, literal task text, JSON field escaping, and shell-quoted report commands. A supervisor dispatch fixture confirms that the rendered worker prompt excludes the worker credential.
+
+These checks use isolated state, temporary repositories, and protocol fixtures. They do not claim new live coding-agent acceptance or exercise removal against a user's real projects. Linux and macOS release CI independently validate the committed artifact before publication.
+
 ## Effect v4 on Bun — 0.3.0 local acceptance (8 September 2026)
 
 Verified locally on macOS arm64 with Bun 1.3.14, Effect 4.0.0-rc.112, TypeScript 7.0.2, and `@effect/tsgo` 0.43.0. The implementation was coordinated through a dedicated Marionette session. The complete Bun suite passed **127 tests across 14 files**, including all 125 retained Effect-era tests and two Bun SQLite compatibility tests.