ai-maestro 1.0.0

package/README.md

@@ -0,0 +1,727 @@
+# AI Maestro CLI
+
+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.
+
+The design goal is simple: the project remembers, not the AI session.
+
+## 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`.
+
+## 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
+```
+
+## Install
+
+### Global install (recommended)
+
+```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:
+
+```bash
+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
+```
+
+## Basic Flow
+
+```bash
+maestro start "descreva o que quer construir"
+maestro continue
+maestro task list
+maestro task next
+maestro run-one
+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.
+
+`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`.
+
+`maestro continue` summarizes memory, handoff state, pending tasks, and the next
+safe command.
+
+## Dry-run vs Real Execution
+
+Every command that can call a worker supports `--dry-run`:
+
+```bash
+maestro run-one --dry-run
+maestro run-task <id> --dry-run
+maestro orchestra-plan [<id>] --dry-run
+```
+
+`--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:
+
+```bash
+maestro ui
+```
+
+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.
+
+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:
+
+```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 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:
+
+```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
+```
+
+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.
+
+## Release Check
+
+Run the MVP release gate with:
+
+```powershell
+maestro release-check
+```
+
+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`.
+
+## Doctor
+
+Run:
+
+```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>""
+```
+
+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.