Agent Orchestrator MCP

A local multi-agent orchestration control plane, exposed over MCP.

Codex is the sole decision authority. Every other agent — Gemini via agy, a deterministic browser/CDP worker, future agents — is a worker that produces evidence. Only Codex may approve, reject, or complete a job, and that is enforced by capability-based authorization and by database triggers, not by prompt instructions.

Status

Phase 4 — Authority and authentication activation (merged into main). PR #7 merged the implementation at ea07fbcae4264fb91601ba03b1bbc84c57e8b7a5; the CLI prepares and protects the global state root, initializes the approved schema-v6 local SQLite store, bootstraps the codex principal and internal system actor, and prints the first bearer token exactly once. Serve uses the database-backed actor_tokens resolver and exposes the compatibility ping tool plus codex_decide only to a verified codex principal holding job:decide. Doctor remains filesystem/security-only and explicitly reports DB_SQL_INTEGRITY=NOT_CHECKED_BY_DESIGN; init and serve startup own deep SQLite integrity, canonical schema, audit-chain, actor-state, and token checks.

Phase 5 — Job lifecycle (merged and published in main). The independently reviewed implementation was merged at 7d7c3f61a118c26d4da0347f6c3ceb9ec286d0ea from reviewed head 4ba475005a0f6d0b9504e7dc82d71d88f23a27e8, followed by the documentation closure commit 530e2441636e6517096b1319c4510b1e56626592. It provides durable job_create, job_start, job_resume, job_get, and job_list behavior with workspace admission, bounded pagination, idempotency, CAS, and the existing Codex authority boundary. Worker execution, leases, evidence/artifacts, resilience loops, and all Phase 6+ behavior remain outside the Phase 5 implementation.

Phase 6 — Worker runtime (merged and published in main). The scoped worker registry, bounded process protocol, run/lease lifecycle, qa_dispatch, run_report, and run_status surface are published at 88670743f8a443bbf3b71c9f379199deca42d512. The post-merge closure is recorded in docs/PHASE6_POST_MERGE_CLOSURE.md. Evidence/artifact handling, recovery loops, remote workers, and all Phase 7+ behavior remain out of scope for Phase 6.

Phase 7 — Evidence and artifacts (merged and published). The reviewed implementation was fast-forwarded into main, followed by the Windows path-normalization fix at bf789157619a0ec39486f451405e190ad5209d14 and the documentation closure at d0ce68cb7fa2c0bdeb4e9de8ed15fd611bc253c3. Local main and origin/main now match at the closure commit. The post-merge record is in docs/PHASE7_POST_MERGE_CLOSURE.md.

Phase 8 — Resilience and recovery (merged and published). The reviewed planning baseline is preserved at 809d698c164ad614e2365778e85e40dc65be872b; the implementation was authorized on codex/phase8-implementation and fast-forwarded into main at reviewed head 130d6988422ad38dcd5513361e049d0171386613 and published in main/origin/main at 3f03168c161a941c4f7055629e6f433c636e62a7. It provides bounded startup recovery, reaping, cancellation settlement, graceful shutdown, STALLED paths, and the principal-only audit_query surface, using schema v7 without a migration. The implementation is now published in main and origin/main; Phase 9 is the current published hardening layer. The detailed handoff is in docs/PHASE8_IMPLEMENTATION_REPORT.md and the local closure is in docs/PHASE8_POST_MERGE_CLOSURE.md.

Phase 9 — Hardening and documentation (merged and published). The implementation branch codex/phase9-implementation starts from the reviewed planning snapshot a75ec06542660cd4d3a338bed514186549a381bd and contains the local implementation at f17ba7788c6b364646eaf7e31c12422bc4d1e20c. It adds fixed post-authentication per-token request admission for HTTP and stdio, centralized redaction/error shaping, lease-aware worker-output redaction, two-session attribution coverage, and regression tests. The implementation is limited to Phase 9: no migration, new business tool, protocol-version change, deployment, or Phase 10 work has been performed. The accepted implementation was fast-forwarded into local main at bea75982ec6c53539a3c13a8260d70f7d0160786 and published in main/origin/main at 398785ea48926b52829a0fd1fa4c6d8d8c6e0ef8; no PR was created. The post-merge record is in docs/PHASE9_POST_MERGE_CLOSURE.md.

The approved design and phase plans are in docs/ARCHITECTURE.md, docs/PHASE4_PLAN.md, and docs/PHASE5_PLAN.md, docs/PHASE6_PLAN.md, and docs/WORKER_PROTOCOL.md, docs/PHASE6_POST_MERGE_CLOSURE.md, docs/PHASE7_PLAN.md, docs/PHASE8_PLAN.md, docs/PHASE8_IMPLEMENTATION_REPORT.md, and docs/PHASE8_POST_MERGE_CLOSURE.md, docs/PHASE9_PLAN.md, docs/PHASE9_IMPLEMENTATION_REPORT.md, docs/PHASE9_POST_MERGE_CLOSURE.md, and SECURITY.md. The empirical Codex/Inspector protocol observation is recorded in docs/PHASE2_PROTOCOL.md.

Related MCP server: coordinaut

Requirements

• Node.js >= 22

Getting started

npm install

npm run ci

npm run ci runs the full gate: typecheck, lint, tests, build.

CLI

node dist/index.js init

Prepares the state root, creates the database only on the explicit init path, applies owner-only protection, verifies it, applies the exact numbered migration set [1, 2, 3, 4, 5, 6], and runs the deep structural/canonical integrity gate. A fresh database atomically creates the codex principal, internal system actor, and digest-only initial token; the plaintext token is printed once after commit. Re-running init preserves the lease key and does not print another token. Existing ambiguous authority state fails closed and is never auto-repaired.

Local token administration is explicit and operator-only:

node dist/index.js token issue --label operator-session
node dist/index.js token list
node dist/index.js token revoke --token-id <token_id>

token list returns metadata only. Revocation is one-way; expiry and revoked rows remain retained for attribution and audit history.

node dist/index.js doctor

Reports the resolved root, DB file, and WAL/SHM filesystem-security state. Read-only: it never invokes SQLite for the authoritative DB, creates, hardens, repairs, migrates, checkpoints, or reads lease-key contents. When filesystem checks pass it reports DB_FILE_SECURITY=PASS and DB_SQL_INTEGRITY=NOT_CHECKED_BY_DESIGN; SQL integrity is not claimed. It exits non-zero for unsafe filesystem/security state. Advisory warnings — such as a superseded state root still present on disk — are reported without failing the run.

ORCHESTRATOR_ACTOR_TOKEN="<operator-supplied-token>" node dist/index.js serve --stdio

Starts the official MCP stdio transport. The supplied bearer is hashed and matched against the persistent database token row before protocol output; environment actor IDs, labels, token IDs, and scopes cannot override database identity. Operational errors go to stderr and stdout remains reserved for MCP protocol traffic.

ORCHESTRATOR_ACTOR_TOKEN="<operator-supplied-token>" node dist/index.js serve --http --port 4317

Starts Streamable HTTP on 127.0.0.1 only. Every MCP request requires a persistent database bearer token with the fixed mcp transport marker; application capabilities come from the verified actor row. Host and Origin are restricted to localhost-class values. --port is optional and defaults to 4317.

Before either transport starts, serve performs the filesystem/security checks and then opens only an existing authoritative DB for the approved deep migration/schema/integrity gate, then verifies the exact enabled principal/system state, persistent token rows, and audit chain. It refuses to start before HTTP bind or stdio protocol output when the state root, DB/sidecars, migrations, PRAGMA policy, schema, authority state, audit chain, or integrity checks are invalid. It never runs init, creates a missing DB, repairs permissions, or reads lease-key contents automatically.

Writable AOM connections enable and verify recursive_triggers=ON as defense in depth. The schema itself rejects INSERT OR REPLACE and REPLACE against existing job, decision, and audit identities even when an external connection explicitly disables that pragma.

Exit codes: 0 success, 1 unexpected internal failure, 2 usage error, 3 security or invariant failure.

State root

Runtime state lives outside this repository, in one global root shared by every project:

<OS user profile>\.agent-orchestrator-mcp\     e.g. C:\Users\<user>\.agent-orchestrator-mcp
  config.json  protected Phase 5 runtime settings (workspace roots and bounded defaults)
  workers.json protected Phase 6 worker registry (disabled starter entry until configured)
  data\        orchestrator.db, WAL/SHM sidecars when SQLite owns them
  artifacts\   per job / cycle / run
  secrets\     lease.key
  logs\

init creates the protected config.json with the approved Windows workspace-root seeds and bounded lifecycle defaults, plus a disabled starter workers.json registry. Before exposing the Phase 6 MCP surface, serve reads and validates both protected configuration files; operators may add local workspace roots there without changing source code. On POSIX, no workspace roots are seeded by default; a local root must be configured explicitly before job_create can admit a job.

On POSIX the root is $XDG_STATE_HOME/agent-orchestrator-mcp, falling back to ~/.local/state/agent-orchestrator-mcp. There is deliberately no override — no flag, environment variable, or config file can redirect the state root, so secrets cannot be steered to a less protected location. init refuses a state root inside a known cloud-synchronised directory, checking both the literal path and, once the root exists, its resolved real path. The check covers root, secrets, data, artifacts, logs, and secrets\lease.key; it rejects both protected paths inside a sync root and sync roots nested inside protected state.

The profile directory comes from OS identity, not from %USERPROFILE%. The location normally corresponds to that variable, but it is not trusted to determine it: os.userInfo().homedir is used, never os.homedir(), which Node documents as consulting USERPROFILE first. Measured here, USERPROFILE=D:\attacker-profile moved os.homedir() but not the state root. UNC and device-namespace profiles are rejected — V1 is a local orchestrator.

Why not %LOCALAPPDATA%? A packaged (MSIX) process has LocalAppData virtualized into ...\Packages\<id>\LocalCache\Local. Measured on Windows 11, a state root created there by a packaged process was reported as absent by an unpackaged process on the same machine — two clients, two physical stores, breaking the invariant that there is exactly one orchestrator state store per user. The user-profile root is still user-scoped but sits outside that boundary, and was measured to resolve identically from both contexts. A state root left behind at the old location is reported by doctor as a warning; it is never read, migrated, or deleted.

Security model

Every directory in the state root, and the lease key itself, is protected identically:

• Windows — a DACL with inheritance removed and exactly one allow entry, for the current user's SID. BUILTIN\Users, Everyone, Authenticated Users, INTERACTIVE, SYSTEM, and Administrators are all absent by design. Applied with icacls using an argument vector and the *<SID> principal form; never a shell string, never a localized account name.

• POSIX — directories 0700, secret files 0600, owned by the current user. Note that chmod is a no-op for access control on Windows and is not the Windows mechanism.

Protection is verified after it is applied, and again on every doctor run. Verification reads the security descriptor as SDDL, which reports identities as SIDs, so it does not depend on the Windows display language. If protection cannot be proven, the command fails closed rather than continuing.

Verification requires the descriptor to match the exact canonical shape hardening produces — owned by the current user, protected, and carrying exactly one full-access allow entry for the current user with the inheritance flags appropriate to a directory or a file. Deny entries, callback or unknown entry types, extra entries, reduced rights, unexpected inheritance flags, and anything the parser cannot fully model are all rejected. No attempt is made to compute Windows effective permissions; the policy is deliberately narrower than that.

icacls.exe and powershell.exe are resolved only at their absolute locations under SystemRoot and are proven to be regular files before use. There is no PATH fallback — if a trusted tool cannot be located, the command fails closed.

Every protected path is checked for redirection before it is hardened or inspected: symbolic links, NTFS junctions, wrong object types, and hard-linked secrets are refused, so protection is never applied through a link to a target elsewhere. This applies to every path including the state root — there is no package-specific bypass, because the root now lives outside the LocalAppData virtualization boundary.

The same policy is applied uniformly to data\, artifacts\, and logs\ as to secrets\, so the future database is never created inside a broadly accessible directory and no path is left weaker than another.

Ordering is load-bearing: secrets\ is created, hardened, and verified before the lease key is written into it, and an existing key has its protection verified before anything opens it. An unsafe key is refused, never read and never repaired in place.

The lease key is exactly 32 random bytes (256-bit, for HMAC-SHA256) — not a minimum; a file of any other size is malformed and refused. It is written with a loop that honours short writes and its final size is confirmed before it is trusted; any failure removes the partial file. It is never printed, logged, or included in any error message or report — doctor reports only its size and protection status.

Scripts

Layout

src/config/     state-root resolution, cloud-sync detection, Phase 5/6 configuration
src/security/   ACL and permission providers, SDDL policy, safe process execution
src/secrets/    lease key lifecycle
src/store/      secure DB modes, migrations, schema, integrity, repositories
src/authority/  Phase 4 bootstrap, capabilities, audit, runtime, and decisions
src/domain/     job and Phase 6 run lifecycle domains
src/workers/    bounded protocol, leases, and local process runtime
src/commands/   init, doctor, and local token administration
src/mcp/        shared MCP factory, Phase 4/5/6 tools, auth, HTTP, and stdio entry points
test/unit/      unit tests
test/store/     migrations, schema, raw-SQL authority, doctor, startup gates
test/integration/ real loopback HTTP and stdio transport acceptance tests
docs/           approved architecture
.github/        CI workflow (Windows + Linux)