npm - ai-maestro - Versions diffs - 1.0.0 → 1.0.1 - Mend

ai-maestro 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,23 @@
 # Changelog
+## 1.0.1 — 2026-07-20
+Documentation-only patch release. No changes to `src/`, `bin/`, or `tests/`.
+- Rewrote the public README to be concise and to match the audited state
+  of the project.
+- Corrected the failover description: it is implemented and wired into
+  the runtime, not future work — it just stays explicitly opt-in
+  (`--failover`).
+- Corrected the description of scheduling/delegation: controlled
+  concurrency and planning-only delegation exist, but there is no
+  unattended multi-agent execution with independent worktrees.
+- Removed an unconfirmed Node.js version requirement ("Node 18+") that
+  was not backed by an `engines.node` field.
+- Simplified and reorganized the public-facing documentation; internal
+  file layout and command list are unchanged.
+- No known API-breaking changes.
 ## 1.0.0 — 2026-07-20
 First public release of AI-MAESTRO on the npm Registry.

package/README.md CHANGED Viewed

@@ -1,727 +1,252 @@
-# AI Maestro CLI
+# AI-MAESTRO
-AI Maestro is a global-friendly Node.js CLI named `maestro` for orchestrating AI coding work across project-local memory, plans, tasks, runs, checkpoints, and handoffs.
+AI-MAESTRO is a Node.js CLI for organizing and running AI-assisted
+development work with persistent project memory — tasks, runs,
+checkpoints, handoffs, execution policies, and auditability.
-The design goal is simple: the project remembers, not the AI session.
+> The project remembers; the AI session does not need to.
 ## Status
-Current version: 1.0.0 (first public release).
-AI-MAESTRO already implements, and validates through its own test suite:
-- A deterministic planner (`maestro plan`/`maestro start`) that classifies a
-  request and generates a scoped task list instead of one generic template.
-- A worker discipline layer: a stricter Codex worker prompt, post-execution
-  verification (workspace diff, syntax validation per changed file, deletion
-  guard, analysis-only guard), so a task can only be marked `completed` when
-  its actual file changes were verified.
-- An orchestration pipeline (task classifier, preflight, engine selector,
-  sector managers, budget manager, verifier, fallback graph, provider health,
-  circuit breaker, and a real provider router) that a real `run-task`/
-  `run-one` consults before dispatching a worker.
-- `--dry-run` on the planning and execution commands to preview the full
-  decision (classification, selected engine, preflight, budget, fallback)
-  without ever calling a worker or mutating task/run state.
-- Delegation and subtask planning (splitting a complex task into subtasks)
-  is implemented as **planning only** — AI-MAESTRO does not auto-execute
-  subagents yet. Parallel subagent execution, worktree isolation, and
-  automatic fallback re-dispatch are not implemented in this release.
-- A release-candidate classifier (`maestro release-check`, `rc-check`) for
-  judging whether an orchestration run is safe to treat as a release
-  candidate.
-See `CHANGELOG.md` for the release history.
-## Project Model
-- `.memory/` is the official portable memory for state, decisions, risks, facts, events, and handoff. It is managed by `ai-universal-memory`.
-- `.maestro/` is the operational layer for plans, tasks, worker runs, checkpoints, and local handoff reports.
-- Codex CLI with `codex exec --profile 9router` is the default non-interactive worker.
-- Premium/Claude-style review is reserved for future critical architecture or final review work, not default task execution.
-AI-Router and AI-MAESTRO are separate tools:
-- AI-Router is a fast CLI router for interactive engine dispatch through `ai`.
-- AI-MAESTRO is a persistent project orchestrator with `.memory/`, `.maestro/`, task state, worker runs, checkpoints, handoffs, safety checks, and usage stats.
-AI-MAESTRO borrows practical patterns from AI-Router, such as command detection, safety guard ideas, status-style diagnostics, and usage summaries, but it does not depend on AI-Router at runtime, and does not modify any local AI-Router installation. A future worker backend may call `ai simples` or `ai fcc` as an optional alternative, but the default worker remains Codex through the isolated `CODEX_HOME`.
+- Stable, publicly released version.
+- Real, controlled task execution through a Codex-based worker.
+- Failover and canary execution are implemented and explicitly opt-in.
+- Internal documentation and the test suite are complete for this release.
+This is not a claim of unlimited autonomy or of compatibility that hasn't
+been tested — see [Current limitations](#current-limitations).
+## Key capabilities
+- **Project memory** — persistent state, decisions, risks, and handoff
+  notes in `.memory/`, independent of any single AI session.
+- **Planning and tasks** — deterministic request classification into a
+  scoped task backlog (`maestro plan`), with full task lifecycle tracking
+  (`maestro task ...`).
+- **Execution via Codex** — `run-one`, `run-task`, and `run-all` dispatch a
+  non-interactive Codex worker under an isolated Codex home.
+- **Dry-run previews** — `--dry-run` on planning and execution commands
+  shows the full orchestration decision (classification, engine, preflight,
+  budget, fallback) without calling a worker or mutating state.
+- **Change verification** — a workspace diff, per-file syntax validation,
+  and analysis-only/deletion guards decide whether a run is actually
+  marked completed.
+- **Logs and reports** — a structured log and report per run
+  (`.maestro/logs/run-<id>.log`, `.maestro/reports/run-<id>.md`).
+- **Locks and recovery** — a global execution lock plus
+  `maestro recover`/`reconcile` for crashed or interrupted runs.
+- **Budget and safety** — `.maestro/budget.json` and pre-dispatch safety
+  checks that block tasks referencing protected files or dangerous actions.
+- **Provider health and circuit breaker** — `maestro provider-health`
+  tracks provider health signals and a failure taxonomy over time.
+- **Opt-in failover** — `maestro run-task <id> --failover` runs an attempt
+  chain through the provider router, under a dedicated lock.
+- **Readiness and rc-check** — `maestro readiness` and `maestro rc-check`
+  assess whether the current state is safe to treat as self-hosting-ready
+  or as a release candidate.
+- **Controlled canary** — `maestro canary <path>` runs a self-hosting
+  validation against a disposable clone, never against the current project.
+- **Local console** — `maestro ui` serves a local dashboard bound to
+  `127.0.0.1`, with a fixed allowlist of operational commands.
 ## Requirements
-- Node.js 18 or newer (this release was tested with Node.js 24.18.0).
-- `ai-universal-memory` available for project memory.
-- Codex CLI installed and configured.
-- A Codex profile named `9router`.
-- 9Router running if your `9router` profile depends on localhost, commonly port `20128`.
-Install memory tooling if needed:
-```bash
-npm install -g ai-universal-memory
-```
+- Node.js. The minimum officially supported Node version is not yet
+  declared in `package.json`. Use a current version and run the local
+  checks (`npm run check`, `npm test`) before relying on it.
+- npm, for install and package scripts.
+- Git, for flows that use it directly (`maestro canary` clones with `git`;
+  `maestro doctor` checks repository status).
+- Codex CLI installed and configured — AI-MAESTRO dispatches it as the
+  default worker.
+- 9Router running locally, only if the Codex profile you configure depends
+  on it.
+- `ai-universal-memory` available for the `.memory/` project memory layer.
-## Install
+AI-MAESTRO has been developed and validated on Windows in this release;
+it is not restricted to Windows by design, but other platforms have not
+been separately verified yet.
-### Global install (recommended)
+## Installation
 ```bash
 npm install -g ai-maestro
 maestro --help
 ```
-This exposes the `maestro` command globally, backed by `bin/maestro.mjs`.
-### Development install (from a clone of this repository)
-```bash
-npm link
-maestro status
-maestro doctor
-```
-## First Safe Use
-Inside the project you want AI-MAESTRO to manage:
+## Quick start
 ```bash
+cd <project-root>
 maestro init
 maestro doctor
-```
-`maestro init` only sets up local project state (`.memory/`, `.maestro/`); it
-does not call a worker or change any files outside the project. `maestro
-doctor` is fully read-only and reports what is configured, missing, or
-misconfigured (Node version, Codex discovery, `9router` profile, memory
-tooling, safety config) before you run anything that touches real files.
-Once `doctor` is clean, preview a task before executing it:
-```bash
 maestro plan "describe what you want to build"
 maestro run-one --dry-run
 ```
-`--dry-run` shows the full orchestration decision (classification, selected
-engine, preflight, budget, fallback) without ever calling a worker or
-mutating task/run state — see "Dry-run vs real execution" below. Only drop
-`--dry-run` once you are comfortable with what a real run will do.
-## Recommended Flow
-```bash
-maestro init
-maestro doctor
-maestro codex-home
-maestro codex-home-diff
-maestro codex-home-inventory
-maestro codex-home-probe
-maestro codex-home-repair
-maestro codex-compare
-maestro codex-test
-maestro plan "criar app de teste com tela inicial, formulario e lista"
-maestro run-one
-maestro run-task 8
-maestro stats
-maestro checkpoint
-maestro handoff
-```
+`maestro init` creates local project state (`.memory/`, `.maestro/`) and
+does not touch anything outside the project. `maestro doctor` is a
+diagnostic command — it inspects Node, Codex, memory tooling, and the
+resolved execution strategy; review its output before running anything
+real. `--dry-run` prints the full orchestration decision without calling a
+worker or mutating task/run state — review it before dropping the flag.
-## Basic Flow
+## Real execution
 ```bash
-maestro start "descreva o que quer construir"
-maestro continue
-maestro task list
-maestro task next
 maestro run-one
+maestro run-task <task-id>
 maestro run-all --limit 3
-maestro release-check
 ```
-`maestro start` initializes project state, validates Codex, runs a smoke test
-when needed, creates a plan, and checkpoints. It does not execute tasks.
+These commands call the Codex worker, which can write files inside the
+project and consume provider usage. Every run is checked against safety
+rules before dispatch, and verified against the actual workspace diff
+afterward before being marked completed.
-`maestro plan` uses a deterministic, keyword-based planner (`smart-heuristic-v1`),
-not an LLM. It classifies the request text and generates a task list shaped for
-that intent; unrecognized requests fall back to a generic template. Before
-replacing an active backlog, it archives active tasks to
-`.maestro/archive/tasks-before-plan-YYYYMMDD-HHMMSS.json`.
+## Failover
-`maestro continue` summarizes memory, handoff state, pending tasks, and the next
-safe command.
+Failover is implemented and connected to the runtime:
-## Dry-run vs Real Execution
+- It is **never** automatic — plain `run-one`, `run-task`, and `run-all` do
+  not use it.
+- It activates only with `maestro run-task <task-id> --failover` (supports
+  `--dry-run`, `--resume`, `--force`).
+- It runs an attempt chain through the provider router, consulting
+  provider health and a circuit breaker, and records the fallback trail
+  under a dedicated global lock.
-Every command that can call a worker supports `--dry-run`:
+## Scheduling and delegation
-```bash
-maestro run-one --dry-run
-maestro run-task <id> --dry-run
-maestro orchestra-plan [<id>] --dry-run
-```
+AI-MAESTRO includes a task classifier, preflight checks, and a scheduler
+with controlled concurrency for orchestration runs (`maestro orchestrate`),
+plus a subtask/delegation planner (`maestro orchestra-plan`) for splitting
+complex work into scoped subtasks. This is not unattended multi-agent
+execution with independent worktrees per subagent — delegation output
+stays planning-oriented, and execution stays under the same controls as
+the rest of the CLI.
-`--dry-run` runs the full orchestration pipeline (classification, sector
-manager, engine selection, preflight, budget, policy, fallback graph) and
-prints the resulting decision, but never calls a worker and never mutates
-task or run state. Drop `--dry-run` only once you have reviewed that output
-and are ready for AI-MAESTRO to actually dispatch a worker and write files.
-## Failover and Canary Are Opt-in
-`maestro run-task <id> --failover` and `maestro canary <path>` are explicit,
-opt-in commands — they are never triggered automatically by `run-one`,
-`run-task`, or `run-all`. Automatic fallback re-dispatch to an alternative
-engine, and parallel/self-hosting canary execution, only happen when you
-invoke these commands yourself.
-## Maestro Console
-Run the local dashboard with:
+## Readiness, canary, and release
 ```bash
-maestro ui
+maestro readiness
+maestro rc-check
+maestro release-check
+maestro canary <disposable-clone-path>
 ```
-It serves `http://127.0.0.1:4317` by default and tries the next ports if that
-one is already in use. The command prints the selected URL and keeps running; it
-does not open a browser automatically.
-The console shows status cards for Maestro, Codex, Memory, Safety, Engine
-Router, and Project state. It reads `.memory/` and `.maestro/`, refreshes through
-Server-Sent Events, and keeps raw logs collapsed by default.
+- `maestro readiness` checks self-hosting readiness and can write a report.
+- `maestro rc-check` classifies an orchestration run as a release
+  candidate (`--json`, `--strict`, `--include-canary`, `--report <path>`).
+  It is a narrower, orchestration-focused check — not a synonym for
+  `release-check`.
+- `maestro release-check` runs the broader release gate: syntax checks,
+  doctor, a Codex smoke test, stats, checkpoint, and handoff.
+- `maestro canary <path>` validates self-hosting behavior against a
+  disposable clone. The target path must be outside the current project
+  root; AI-MAESTRO refuses to run a canary against its own project
+  directory.
-Current UX:
-- `Run Task` appears on each `pending`, `failed`, or `in_progress` task.
-- `Reabrir` appears on blocked tasks and maps to the existing `task pending` CLI path.
-- The timeline merges recent events from memory, runs, usage, and UI command logs.
-- Filters cover `Todos`, `Maestro`, `Codex`, `Memory`, `Safety`, `Engine`, `UI`, and `Erros/Bloqueios`.
-- `Copiar Handoff` copies the current handoff text from memory or the Maestro fallback.
-- Each card and timeline item can reveal its raw log on demand and copy it locally.
-The UI can run only this allowlist of operational commands:
+## Main commands
 ```text
-doctor, codex-home, codex-test, task-list, task-next, run-one,
-run-all-limit-3, run-task, task-pending, checkpoint, handoff, stats,
-release-check, schema-check
-```
-There is no arbitrary terminal in the dashboard. Command execution uses fixed
-`spawn()` argument arrays and records summaries in `.maestro/ui-runs.jsonl`.
-The server binds only to `127.0.0.1`; do not expose it through a public tunnel,
-reverse proxy, or shared interface.
-Limitations currently remain:
-- The timeline is a recent-event view, not a full historical explorer.
-- Raw logs are still stored in the project files; the UI only controls visibility.
-- The console does not replace the CLI for direct task maintenance or archive flows.
-Current validated MVP state:
-- The default worker is Codex through `codex-js-isolated`.
-- Maestro sets `CODEX_HOME=%USERPROFILE%\.codex-maestro` only for spawned worker processes.
-- The isolated Codex home has been validated with `workspace-write`.
-- `maestro codex-test` creates `MAESTRO_CODEX_TEST.md` through 9Router.
-- `api.openai.com` was not observed in the validated Codex smoke test.
-- `blocked by policy` was not observed in the validated Codex smoke test.
-- Normal Codex home `%USERPROFILE%\.codex` is not modified by Maestro.
-- `your local AI-Router installation, if any,` is reference-only and is not modified by Maestro.
-## Commands
-```bash
 maestro help
-maestro init
-maestro status
-maestro start "pedido"
-maestro start "pedido" --validate-worker
-maestro continue
-maestro doctor
-maestro codex-home
-maestro codex-test
-maestro codex-compare
-maestro stats
-maestro release-check
-maestro schema-check
-maestro plan "..."
-maestro run-one
-maestro run-one --quiet
-maestro run-one --dry-run
-maestro run-one --force
-maestro run-task 8
-maestro run-task 8 --quiet
-maestro run-task 8 --dry-run
-maestro run-task 8 --force
-maestro run-all
-maestro run-all --limit 3
-maestro retry <id>
-maestro task list
-maestro task next
-maestro task show <id>
-maestro task add "descricao"
-maestro task complete <id>
-maestro task fail <id>
-maestro task pending <id>
-maestro task archive-failed
-maestro task archive-completed
-maestro task clean-test
-maestro checkpoint
-maestro handoff
-maestro ui
-maestro engines list
-maestro engines show <id>
-maestro engines health
-maestro engines validate <id>
-maestro engines research
-maestro route-task [<id>]
-maestro preflight [<id>]
+maestro init | status | start "<request>" | continue | doctor
+maestro plan "<request>"
+maestro task list | show <id> | add "<desc>" | complete <id> | fail <id> |
+  pending <id> | archive-failed | archive-completed
+maestro run-one | run-task <id> | run-all --limit <n> | retry <id>
+maestro run-task <id> --failover [--dry-run] [--resume] [--force]
+maestro orchestrate <id> [--real] [--force] [--parallel] [--max-concurrent=N]
 maestro orchestra-plan [<id>] [--dry-run]
-maestro budget
-maestro stats --by-engine
-maestro stats --by-run-kind
-maestro stats --cost
-maestro stats --by-gate-decision
-```
-## Task Maintenance
-`maestro task list` prints task totals by status, priority, engine, title, short
-date, and the next task selected by `run-one`.
-`maestro task next` shows the exact pending task that `run-one` would execute.
-`blocked` and `needs_human` tasks are ignored by `run-one` and `run-all`;
-`run-all` also stops its batch when a task lands on `needs_human`, the same
-as `failed`/`blocked`. Use `maestro task pending <id>` to reopen a `blocked`
-or `needs_human` task after review; the next execution may block again if
-the same condition still applies. For a `needs_human` task specifically,
-`maestro run-task <id> --force` is available once a human has reviewed the
-risk — `--force` can only promote a `needs_human` decision to execution; it
-can never bypass the safety guard, `.env`/deletion protections, an engine
-policy violation, or a budget hard limit, all of which resolve to `blocked`
-before `--force` is even considered.
-Archive commands preserve history under `.maestro/archive/` instead of deleting
-tasks:
-```bash
-maestro task archive-failed
-maestro task archive-completed
-maestro task clean-test
-```
-`archive-failed` moves failed tasks out of active `TASKS.json`.
-`archive-completed` does the same for completed tasks. `clean-test` archives
-obvious infrastructure smoke-test tasks such as `MAESTRO_CODEX_TEST.md`,
-`MAESTRO_WORKER_TEST.md`, `WORKING_*`, and `PROBE_*`.
-## Codex Worker
-`maestro run-one`, `maestro run-task <id>`, and `maestro run-all` use non-interactive Codex execution:
-```bash
-codex exec --profile 9router --sandbox workspace-write --skip-git-repo-check "<prompt>"
-```
-The worker prompt instructs Codex to read:
-- `.memory/BRIEF.md`
-- `.maestro/PLAN.md`
-- `.maestro/TASKS.json`
-- `.maestro/worker-policy.md`
-The worker policy forbids editing `.env`, deploys, file deletion, modifying the
-normal Codex home, and modifying any local AI-Router installation. Workers
-should record changed files, run relevant validations, and log meaningful
-work to `.memory/` when possible.
-`maestro run-one` executes the next `pending` task by priority. `maestro
-run-task <id>` executes a specific task when its status is `pending` or
-`in_progress`. Archived, completed, and failed tasks are not executed directly;
-use `maestro retry <id>` for failed tasks.
-`maestro run-all --limit 3` executes pending tasks in priority order, stops on
-the first error, records usage, and writes a checkpoint at the end.
-Before any Codex worker is called, AI-MAESTRO runs `checkTaskSafety()` against
-the task title and description. If a dangerous pattern or protected file is
-detected, the task is marked `blocked`, Codex is not called, `.maestro/RUNS.jsonl`
-and `.maestro/usage.jsonl` are updated, and the finding is logged to memory.
-## Isolated Codex Home
-Normal Codex usage should continue using the user's regular Codex home, typically:
-```text
-%USERPROFILE%\.codex
-```
-AI-MAESTRO uses a separate Codex home only for child worker processes:
-```text
-%USERPROFILE%\.codex-maestro
-```
-It sets `CODEX_HOME` only in the spawned Codex process. It does not set `CODEX_HOME` globally and does not edit the normal Codex config.
-Create or validate the isolated config:
-```powershell
-maestro codex-home
-```
-The default Maestro Codex config uses profile `9router`, provider `9router`, and `wire_api = "responses"` pointing at `http://localhost:20128/v1`.
-Run a direct worker smoke test:
+maestro engines list | show <id> | health | validate <id> | research
+maestro route-task [<id>] | preflight [<id>] | budget
+maestro provider-health [--json]
+maestro codex-home | codex-test | codex-compare
+maestro readiness | rc-check | release-check | canary <path> | schema-check
+maestro checkpoint | handoff | stats | ui
+```
+This is not the full list. Run `maestro help` or `maestro --help` for the
+authoritative, current set of commands and flags.
+## Local files
+- `.memory/` — portable project memory (state, decisions, risks, handoff).
+- `.maestro/TASKS.json` — task backlog and status.
+- `.maestro/RUNS.jsonl` — append-only run history.
+- `.maestro/latest-run.json` — pointer to the most recent run.
+- `.maestro/logs/run-<run-id>.log` — full log for a given run.
+- `.maestro/reports/run-<run-id>.md` — human-readable report for a given run.
+- `.maestro/usage.jsonl` — usage records per run.
+- `.maestro/PROVIDER_HEALTH.json` — current provider health snapshot.
+- `.maestro/HEALTH_EVENTS.jsonl` — provider health event history.
+- `.maestro/locks/fallback-chain-global.lock.json` — lock for the global
+  failover chain.
+## Codex and 9Router
+- **AI-MAESTRO** is the orchestrator: it plans tasks, tracks state, and
+  decides when and how to dispatch a worker.
+- **Codex** is the worker: AI-MAESTRO calls the Codex CLI non-interactively
+  to actually change files.
+- **9Router** is a local gateway that some Codex profiles point to; it
+  only matters if your configured profile depends on it.
+- A Codex **profile** is client-side configuration (provider, model,
+  sandbox mode) that AI-MAESTRO's isolated Codex home uses when invoking
+  Codex.
+- **Engine**, **provider**, and **model** are distinct concepts in
+  AI-MAESTRO's own engine registry (`maestro engines list`); a gateway-side
+  combo/fallback alias is not the same thing as AI-MAESTRO's failover.
+AI-MAESTRO does not publish private model configuration, API keys, or
+internal endpoints beyond what is required to run the CLI.
-```powershell
-maestro codex-test
-```
-This attempts to create `MAESTRO_CODEX_TEST.md` through Codex using the isolated `CODEX_HOME`.
-Run an invocation comparison when Codex works manually but fails through Maestro:
-```powershell
-maestro codex-compare
-```
-This creates four diagnostic files with different invocations and stores the
-result in `.maestro/codex-compare.json`:
-- `codex.cmd` with the normal Codex home.
-- `codex.cmd` with `CODEX_HOME=%USERPROFILE%\.codex-maestro`.
-- `node.exe codex.js` with the normal Codex home.
-- `node.exe codex.js` with `CODEX_HOME=%USERPROFILE%\.codex-maestro`.
-`codex.cmd` is the Windows command shim. `node.exe codex.js` runs the Codex
-JavaScript entrypoint directly, which usually handles long prompts better. Some
-Codex builds can behave differently between the two, so Maestro records the
-working invocation instead of assuming they are equivalent.
-`MAESTRO_CODEX_INVOCATION` controls the selected invocation:
-- `auto` (default): use `.maestro/codex-compare.json` and choose the safest working invocation.
-- `codex-js-isolated`: `node.exe codex.js` with the isolated Maestro Codex home.
-- `codex-cmd-isolated`: `codex.cmd` with the isolated Maestro Codex home.
-- `codex-js-normal-home`: `node.exe codex.js` without forcing `CODEX_HOME`.
-- `codex-cmd`: `codex.cmd` without forcing `CODEX_HOME`.
-The safest order is isolated first: `codex-js-isolated`, then
-`codex-cmd-isolated`, then normal-home compatibility modes. If only `codex.cmd`
-with the normal home works, Maestro reports it as compatibility mode and does
-not edit the normal Codex config.
-Compare the normal and isolated Codex homes without printing secrets:
-```powershell
-maestro codex-home-diff
-```
-This writes `.maestro/codex-home-diff.json` with file names, TOML sections,
-non-sensitive config values, policy/trust-like files, and sensitive files by
-existence/type only. Token, auth, session, cookie, and credential contents are
-never copied into the report.
-Generate a deeper redacted inventory:
-```powershell
-maestro codex-home-inventory
-```
-This writes `.maestro/codex-home-inventory.json`. Each relative path is
-classified as config, trust, policy, sandbox runtime, rule, cache,
-auth-sensitive, session-sensitive, unknown-sensitive, or safe-copy-candidate.
-Hashes are included only for non-sensitive files. Sensitive contents are never
-written to the report.
-Probe safe candidates incrementally:
-```powershell
-maestro codex-home-probe
-```
-The probe confirms the current `codex-js-isolated` baseline, then tests safe
-copy candidates one at a time. It backs up `.codex-maestro`, copies only the
-candidate file, runs an isolated write test, and restores the backup if the
-candidate does not unlock `workspace-write`. It never copies auth, token,
-session, cookie, credential, cache, or unknown-sensitive files.
-Repair the isolated home:
-```powershell
-maestro codex-home-repair
-```
-The repair first backs up `%USERPROFILE%\.codex-maestro` to
-`%USERPROFILE%\.codex-maestro.backup-YYYYMMDD-HHMMSS`, then rewrites
-`9router.config.toml` in the isolated home using the format expected by the
-current Codex build: provider, model, `approval_policy = "never"`, and
-`sandbox_mode = "workspace-write"` in the profile file. It does not copy auth,
-session, token, cookie, credential, or cache files from the normal Codex home.
-The target final state is `codex-js-isolated`. If the isolated home still enters
-`read-only`, Maestro keeps `codex-js-normal-home` as a compatibility fallback.
-That fallback uses the normal Codex configuration only at runtime; Maestro does
-not edit the normal Codex config.
-## Codex Sandbox Strategies
-AI-MAESTRO resolves Codex sandbox execution with `MAESTRO_CODEX_STRATEGY`.
-Valid values are:
-- `auto` (default): use the first safe strategy proven by `maestro codex-test`.
-- `basic`: `codex exec --profile 9router --sandbox workspace-write --skip-git-repo-check`.
-- `global-approval`: pass approval globally before `exec`, for Codex builds where `--ask-for-approval` or `-a` is a global flag.
-- `config-override`: pass `-c approval_policy="never"` and `-c sandbox_mode="workspace-write"` to `exec`.
-- `ignore-rules`: add `--ignore-rules` for diagnosis when the exec help supports it.
-- `workspace-permissions`: use an isolated `workspace-permissions.config.toml` with `default_permissions = ":workspace"`.
-- `dangerous-yolo`: diagnostic only. It is never selected by `auto` and is only tested when `MAESTRO_ALLOW_DANGEROUS_CODEX_TEST=1`.
-`maestro codex-test` tries the safe strategies in order and stores the first
-working result in `.maestro/codex-strategy.json`. `runCodex` uses that validated
-strategy in `auto` mode. If no strategy has been validated yet, it falls back to
-`basic`.
-Some Codex versions expose approval control only in `codex --help`, not in
-`codex exec --help`. In that case the correct order is:
-```powershell
-codex --ask-for-approval never exec ...
-```
-or:
-```powershell
-codex -a never exec ...
-```
-not `codex exec --ask-for-approval never ...`.
-Codex has two sandbox configuration styles. The older style uses
-`sandbox_mode = "workspace-write"`. The newer permission style can use
-`default_permissions = ":workspace"`. AI-MAESTRO keeps these in separate config
-files and does not mix `default_permissions` with `sandbox_mode` in the
-`workspace-permissions` diagnostic config.
-Supported environment variables:
-- `MAESTRO_CODEX_HOME`
-- `MAESTRO_CODEX_PROFILE`
-- `MAESTRO_CODEX_INVOCATION`
-- `MAESTRO_CODEX_STRATEGY`
-- `MAESTRO_CODEX_JS`
-- `MAESTRO_CODEX_PATH`
-- `MAESTRO_NPX_PATH`
-- `NINEROUTER_API_KEY`
-- `MAESTRO_ALLOW_LOCAL_TEST_KEY`
-`NINEROUTER_API_KEY` is not silently replaced. If it is missing, `doctor` reports
-an error. For explicit local diagnostics only, set
-`MAESTRO_ALLOW_LOCAL_TEST_KEY=1` to allow the `local-test` fallback.
-## Safety And Stats
-AI-MAESTRO creates `.maestro/safety.json` and checks task text before dispatching a worker. If a task mentions protected files or dangerous actions, Maestro blocks the run, records it in `.maestro/RUNS.jsonl`, logs it to `.memory/`, and does not call Codex.
-Usage is recorded in:
-- `.maestro/usage.jsonl`
-- `.maestro/usage-summary.json`
-Show stats with:
-```powershell
-maestro stats
-```
+## Security
-Stats include task runs, completed/failed/blocked counts, estimated tokens, estimated Claude tokens avoided, engines, recent runs, Codex home, expected provider, and whether `api.openai.com` appeared in output.
+AI-MAESTRO does not require credentials to be placed in tasks or
+operational files. Authentication remains the responsibility of the tools
+it integrates with (Codex, 9Router). Diagnostic commands avoid reproducing
+sensitive values — they report file existence and type, not contents.
-## Release Check
+Other safety measures:
-Run the MVP release gate with:
+- Task safety checks run before every worker dispatch and block dangerous
+  or protected-file patterns.
+- Critical files are backed up before overwrite where practical.
+- Locks guard concurrent execution and the global failover chain.
+- `maestro canary` requires a disposable target outside the project root.
+- `maestro ui` binds only to `127.0.0.1` and exposes a fixed command
+  allowlist, not an arbitrary terminal; do not expose it through a public
+  tunnel or reverse proxy.
+- Do not remove `.maestro` locks manually without first confirming no
+  AI-MAESTRO process is still running.
-```powershell
-maestro release-check
-```
+## Current limitations
-It runs syntax checks for the main modules, then runs doctor, Codex smoke test,
-stats, checkpoint, and handoff. It also verifies that README exists,
-`package.json` exposes the `maestro` bin, and the main commands are documented.
-The report is written to `.maestro/RELEASE_CHECK.md`.
+- Real execution stays controlled and opt-in for sensitive flows
+  (failover, canary).
+- Canary validation depends on having a disposable environment to target.
+- Provider availability depends on the external tools you configure
+  (Codex, 9Router).
+- Some auxiliary capabilities remain test-only and are not part of the
+  public command surface.
+- Official minimum Node.js version and platform support are not yet
+  formalized.
+- Delegation and subtask planning do not execute unattended multi-agent
+  runs with independent worktrees.
-## Doctor
+## Development
-Run:
+From a local clone of this repository:
 ```bash
-maestro doctor
-```
-The doctor checks:
-- Node version.
-- `.memory/` and `.memory/tools/cli.mjs`.
-- `.maestro/`.
-- `9router` on PATH.
-- port `20128`.
-- Codex command discovery.
-- Codex normal and Maestro Codex home.
-- `MAESTRO_CODEX_PATH`.
-- `MAESTRO_CODEX_HOME`.
-- `MAESTRO_CODEX_JS`.
-- `MAESTRO_CODEX_PROFILE`.
-- `NINEROUTER_API_KEY`.
-- npx/npm discovery.
-- `.maestro/safety.json`.
-- `codex exec --profile 9router --help`.
-- `package.json` global CLI fields.
-- Git repository status and whether `--skip-git-repo-check` is needed.
-Doctor output uses:
-- `OK`
-- `AVISO`
-- `ERRO`
-- `COMO CORRIGIR`
-## Windows: spawn codex ENOENT
-On Windows, PowerShell can sometimes find `codex`, while Node's `spawn(..., { shell: false })` cannot. AI Maestro tries, in order:
-1. `MAESTRO_CODEX_JS`
-2. `MAESTRO_CODEX_PATH` pointing to a `.js` file
-3. the real `codex.js` behind `codex.cmd`
-4. common npm global install paths under `%APPDATA%\npm\node_modules`
-5. `MAESTRO_CODEX_PATH`
-6. `where.exe codex.exe`
-7. `where.exe codex.cmd`
-8. `where.exe codex`
-Prefer the real JS entrypoint for Codex on Windows because long prompts can be split incorrectly by `codex.cmd` wrappers:
-```powershell
-setx MAESTRO_CODEX_JS "%APPDATA%\npm\node_modules\@openai\codex\bin\codex.js"
-```
-AI Maestro will then execute:
-```powershell
-node "...\codex.js" exec --profile 9router --sandbox workspace-write --skip-git-repo-check "<prompt>"
-```
-with the prompt as one array argument.
-If no JS entrypoint is configured or discoverable, AI Maestro falls back to:
-1. `MAESTRO_CODEX_PATH`
-2. `where.exe codex.exe`
-3. `where.exe codex.cmd`
-4. `where.exe codex`
-If `maestro run-one` fails with `spawn codex ENOENT` or the doctor reports that Codex is missing, inspect the installed command:
-```powershell
-Get-Command codex -All | Format-List CommandType,Source,Definition
-where.exe codex
-```
-Then configure the full executable path:
-```powershell
-setx MAESTRO_CODEX_PATH "CAMINHO_COMPLETO_DO_CODEX"
-```
-Open a new terminal after running `setx`, then run:
-```powershell
-maestro doctor
-maestro run-one
-```
-If the path points to `codex.exe`, AI Maestro uses direct `spawn` with `shell:false`. If the path points to `codex.cmd` or `.bat`, AI Maestro uses a controlled `cmd.exe /d /s /c` fallback shaped like:
-```powershell
-cmd.exe /d /s /c ""%APPDATA%\npm\codex.cmd" exec --profile 9router --sandbox workspace-write --skip-git-repo-check "<prompt>""
+npm install
+npm run check
+npm test
+node bin/maestro.mjs --help
 ```
-Arguments are quoted individually before being passed to `cmd.exe`.
-## Windows: spawn npx ENOENT
-On Windows, Node may not find `npx` even when PowerShell can. AI Maestro resolves npx with:
-1. `MAESTRO_NPX_PATH`
-2. `where.exe npx.cmd`
-3. `where.exe npx`
-If `maestro init` fails with `spawn npx ENOENT`, inspect npx:
-```powershell
-where.exe npx
-```
-Then configure the full `.cmd` path:
-```powershell
-setx MAESTRO_NPX_PATH "C:\Program Files\nodejs\npx.cmd"
-```
-Open a new terminal and run:
-```powershell
-maestro doctor
-maestro init
-```
-## Security
-AI-MAESTRO itself never asks for, stores, or transmits API credentials. It
-delegates model calls entirely to the Codex CLI, which you install and
-authenticate separately; AI-MAESTRO only sets `CODEX_HOME` for the spawned
-worker process and checks (never prints the value of) `NINEROUTER_API_KEY`.
-Diagnostic commands (`codex-home-diff`, `codex-home-inventory`,
-`codex-home-probe`) classify config files as auth/session/token/cookie/
-credential-sensitive and never copy or print their contents — only
-non-sensitive values, file existence, and file type are recorded.
-Safety rules enforced at runtime:
-- No `shell:true` for free-form user prompts; worker prompts are always
-  passed as array arguments, never interpolated into a shell string.
-- No deploy command is run by Maestro.
-- `.env` files are not edited by Maestro.
-- `.memory/` and `.maestro/` are not deleted automatically.
-- Before dispatching any worker, `checkTaskSafety()` scans the task text for
-  dangerous patterns or protected files; a match blocks the task instead of
-  calling Codex.
-- Critical files are backed up before overwrite where practical:
-  - `.maestro/TASKS.json`
-  - `.maestro/RUNS.jsonl`
-  - `.maestro/PLAN.md`
-- The Maestro Console (`maestro ui`) binds only to `127.0.0.1`, exposes no
-  arbitrary terminal, and can only run a fixed allowlist of operational
-  commands (see "Maestro Console" above). Do not expose it through a public
-  tunnel or reverse proxy.
-If you find a security issue, please open an issue on the project repository
-rather than filing a public task with sensitive details.
-## Future Work
-- Wire the fallback graph's hints into `run-task`'s actual failure handling
-  (today's release adds the classification/policy, not the automatic retry loop).
-- Parallel subagent execution with per-subagent worktree/branch isolation (serial-only by design in this release).
-- Populate engine `health` fields from a real `maestro engines health --refresh`-style
-  live check, instead of staying `null` until something else writes engine history.
-- Register more of the models 9Router exposes as real, runnable engines
-  (today only `codex9` and `ai-router` have invocation modules).
-- Premium/Claude review as an explicit opt-in command, still never a
-  default worker.
 ## License
-AI-MAESTRO is released under the ISC License. See the `LICENSE` file for the
-full text.
+ISC. See the `LICENSE` file for the full text.

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "ai-maestro",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Project-local multi-agent orchestration CLI backed by ai-universal-memory.",
   "type": "module",
   "license": "ISC",