# GRACE Orchestrator MCP

Local MCP control-plane for the Codex → GLM → worker → acceptance workflow.

This repository contains the reusable host/tooling layer. Product repositories
keep their own GRACE artifacts, policies, and runtime contracts; this server
only owns workflow ledger state, gate execution, handoff events, and host
continuation plumbing.

Runtime routing is provider-neutral. The server records the workflow ledger,
accepts only server-bound roles, derives Git evidence, and keeps an immutable
record of each execution attempt. Provider, model, and target selection live
in operator-managed TOML, so changing from GLM to Kimi (or disabling any
provider) does not require changing a GRACE task or asking an LLM to edit code.

## Local development

```powershell
py -3.11 -m venv .venv
.\.venv\Scripts\python -m pip install -e ".[dev]"
.\.venv\Scripts\python -m pytest
```

Set `GRACE_MCP_HOME` in consuming projects to this checkout when docs or MCP
configuration need to refer to the external tool source.

## STDIO identity

Set the identity before starting the server. It is deliberately process-bound,
so no MCP tool can elevate itself by supplying a role argument.

```powershell
$env:GRACE_ORCHESTRATOR_ACTOR_NAME = "codex"
$env:GRACE_ORCHESTRATOR_ACTOR_ROLE = "codex"
$env:GRACE_ORCHESTRATOR_DATA_DIR = "D:\path\to\grace-orchestrator-state"
.\.venv\Scripts\grace-orchestrator-mcp
```

Logs use stderr; stdout is reserved for MCP JSON-RPC.

Keep `GRACE_ORCHESTRATOR_DATA_DIR` outside the repository: it holds the local
ledger, routing configuration, run evidence, and any driver-managed workspaces.

## GUI-Neutral Inbox & Project Authorization

`inbox.next` and `inbox.list` provide passive, backend-neutral inbox queries returning actor-bound execution items:
- Queries are strictly bounded by process identity (`GRACE_ORCHESTRATOR_ACTOR_NAME` / `GRACE_ORCHESTRATOR_ACTOR_ROLE`).
- Inbox items contain only actions that the caller has active role or project capability/delegation authorization to perform.
- For GUI-backed environments (e.g. Antigravity IDE, VSCode, Codex GUI), active tab or context switching is performed manually by the human user.
- Calling `inbox.next` or `inbox.list` eliminates context transfer overhead, but does NOT launch, spawn, or wake up background Codex/ZCode/Antigravity instances.
- Project-scoped authorization is strictly enforced across both tool calls and FastMCP `@mcp.resource` endpoints. `GLM` and `TEST_OWNER` primary roles require explicit project capability registration or delegation to access project resources.

## Runtime routing and model changes

Initialize and edit the operational configuration directly; these commands do
not use MCP or an LLM:

```powershell
grace-orchestrator --data-dir D:\path\to\grace-orchestrator-state config init
grace-orchestrator --data-dir D:\path\to\grace-orchestrator-state provider add moonshot --driver openai_compatible --credential-env MOONSHOT_API_KEY
grace-orchestrator --data-dir D:\path\to\grace-orchestrator-state model add kimi-main --provider moonshot --remote-id kimi-k2
grace-orchestrator --data-dir D:\path\to\grace-orchestrator-state target add kimi-planner --model kimi-main --capability planner
grace-orchestrator --data-dir D:\path\to\grace-orchestrator-state route set planner --target kimi-planner
grace-orchestrator --data-dir D:\path\to\grace-orchestrator-state config doctor --capability planner --min-candidates 2
grace-orchestrator --data-dir D:\path\to\grace-orchestrator-state health status
grace-orchestrator --data-dir D:\path\to\grace-orchestrator-state health reset kimi-planner
```

`routing.toml` is atomically written under `config/`, versioned in `config/history/`,
and hot-reloaded with last-known-good protection. Disable or drain a target to
stop new dispatches; previously-created attempts retain their selected target,
routing generation, and evidence. The v4 lifecycle is
`grace.dispatch_v4_task` → `attempt.start` → verification → `attempt.complete`.
`attached_actor`, `command`, and `openai_compatible` are explicit driver
types. MCP records a handoff for external drivers; it never accepts arbitrary
argv or credentials and does not impersonate an external provider executor.

`config doctor` is the preflight check for routing. Use
`--min-candidates 2` for a capability that must remain available after one
provider/model target is quarantined. Quarantine is scoped to the actual
failure blast radius (target, model, provider, credential, or host), so a
quota or authentication fault is not blindly retried through another target
using the same provider account.

The retired transport is not part of the runtime. Existing historical sessions
are copied on startup into the immutable `legacy_execution_sessions` archive
for audit only; no executable legacy transport is exposed.

New MCP servers expose the GRACE v4 attempt surface only. The superseded
task/work-package surface is an explicit temporary compatibility mode. An
environment start requires both `GRACE_ORCHESTRATOR_LEGACY_API=1` and
`GRACE_ORCHESTRATOR_LEGACY_API_ACK=1`; every such start is written to the
audit ledger. This mode restores legacy package tools only — not the retired
MiMo transport.

## GRACE v4 completion and recovery

Import accepts an active approved `GraceChangeSpec`/`GraceChangePlan` only
when its version, scope, graph anchors, task dependencies, acceptance
criteria, and verification commands form a safe runtime contract. The server
also requires a successful canonical upstream validator receipt at import. Set
the validator once in the MCP host environment with JSON argv; it is executed
without a shell and supports `{project_root}`, `{grace_root}`, and
`{change_id}` placeholders:

```powershell
$env:GRACE_V4_VALIDATOR_ARGV_JSON = '["bun","run","D:\tools\GRACE\src\grace.ts","lint","--path","{project_root}"]'
$env:GRACE_V4_VALIDATOR_CWD = 'D:\tools\GRACE'
```

The server records hashes of the command and its output in the execution
policy, then re-hashes the approved bundle at start and completion.

`attempt.complete` cannot mark a v4 task successful until every plan-declared
acceptance criterion and verification command has structured passing evidence.
Use `attempt.record_verification` for evidence produced by a test owner, or
`attempt.run_verification` for a plan-declared command that is also in the
project allowlist. The latter records command exit code and log locations.

Every started attempt holds a renewable lease. `attempt.heartbeat` renews it;
server startup reconciles expired leases into one `SESSION_STALLED` failure and
an idempotent fallback attempt when an eligible route remains. An MCP host is
still responsible for reconnecting/restarting a dead STDIO process.

For an imported v4 task, a changed or unavailable approved `spec.xml` or
`plan.xml` closes the active attempt as `APPROVED_CONTRACT_DRIFT` in the ledger
and requires a replan. Legacy package operations are also disabled inside the
service by default; exposing them requires explicit compatibility mode in
addition to the server-level acknowledgement.

For a product repository, enforce v4 guidance with:

```powershell
grace-docs-lint D:\path\to\product-repository
```

It rejects active `AGENTS.md` and `docs/grace/**/*.md` references to v3
packet/work-package controls. Historical material belongs under a `legacy` or
`archive` directory and is intentionally excluded.

## Legacy worker handoff and controller wait

This section documents the temporary `GRACE_ORCHESTRATOR_LEGACY_API` package
compatibility surface. It is not part of the default v4 execution path.

Dispatch does not end controller responsibility.  Every launch writes
`WORKER_STARTED`; a valid `submission.create` writes a durable
`WORKER_READY_FOR_REVIEW` event and a controller-readable report.  Workers
must use `handoff.report_worker_event` for `WORKER_BLOCKED`,
`WORKER_NEEDS_CONTROLLER`, or `WORKER_FAILED`; controller review writes
`CONTROLLER_ACCEPTED` or `CONTROLLER_REWORK_REQUESTED`.

Events and reports live below the configured external data directory at
`runs/project-<id>/task-<id>/package-<id>/`, never in a product worktree.  A
live Codex controller reads the current count with `handoff.list_events` and
then blocks through `handoff.wait_for_event`.  The wait is a bounded,
cross-process Windows named-event wait rather than a blind polling timer; it
returns only when a new durable event appears or its explicit timeout expires.
The controller then reviews or escalates and renews the wait while the package
is still open.  A host that has completely ended a Codex conversation must
provide its own continuation/wakeup integration; the MCP server cannot revive
an already-terminated client process.

## Host-level continuation

`handoff.wait_for_event` is the live-controller wait path. It only works while
the controller session is alive and actively waiting inside an MCP tool call.
Host-level continuation is the external recovery path for the opposite case:
the runtime/host process watches durable files under
`GRACE_ORCHESTRATOR_DATA_DIR\runs\...` and starts controller review from those
files after a worker emits `WORKER_READY_FOR_REVIEW`, `WORKER_BLOCKED`,
`WORKER_FAILED`, or `WORKER_NEEDS_CONTROLLER`.

Start it from the repository root:

```powershell
$env:GRACE_ORCHESTRATOR_DATA_DIR = "D:\path\to\grace-orchestrator-state"
$env:GRACE_CODEX_START_COMMAND = 'codex "{prompt_file}"'
.\scripts\Start-GraceHostContinuation.ps1
```

Use `-Once` for a single scan during tests or manual recovery. The supervisor
keeps its cursor under
`GRACE_ORCHESTRATOR_DATA_DIR\host-continuation\cursor.json`, writes per-run
host events to `runs\project-<id>\task-<id>\package-<id>\host-events.ndjson`,
and uses per-run directory locks under `host-continuation\locks\` so two host
instances do not start duplicate controller continuation for the same run.

Continuation has two modes. If per-run controller metadata records a usable
`controller_session_id` and `GRACE_CODEX_RESUME_COMMAND` is configured, the
host attempts that resume command first. Resume syntax is Codex-version and
host-version dependent, so the command is deliberately configured instead of
hardcoded. If resume is unavailable or fails, the reliable baseline is logical
continuation: the host writes a compact controller prompt and launches
`GRACE_CODEX_START_COMMAND`. The configured command can use placeholders such
as `{prompt_file}`, `{data_dir}`, `{run_id}`, `{task_id}`,
`{work_package_id}`, `{report_path}`, `{worktree_path}`, and
`{controller_session_id}`. The prompt file path is also supplied through
`GRACE_CONTROLLER_CONTINUATION_PROMPT_FILE`.

The host emits these durable host events: `HOST_CONTINUATION_DETECTED`,
`HOST_CONTROLLER_RESUME_ATTEMPTED`, `HOST_CONTROLLER_RESUME_STARTED`,
`HOST_CONTROLLER_RESUME_FAILED`, and
`HOST_CONTROLLER_LOGICAL_CONTINUATION_STARTED`. These are workflow wakeup
evidence only. They do not accept a package, do not mutate product runtime
truth, and do not prove that a closed Codex session was revived. A closed
session is resumed only if the configured resume command really starts.

## Enforcement gates

The server is a gatekeeper, not only a ledger. It exposes:

- `gate.contract_discovery`: reads current GRACE/code-adjacent sources and
  returns contracts, M-* refs, V-M-* refs, rule refs, and blocking issues.
- `gate.validate_execution_packet`: rejects worker packets missing task,
  module, verification, scope, contracts-read, test surface, rollback, command,
  stop-condition, or compact-report fields.
- `gate.validate_worker_report`: rejects worker reports missing files read,
  files changed, contract delta, exact command results, scaffolded/wired/
  verified split, unverified gaps, protected-test scope statement, or delta
  proposals.
- `gate.agent_infra_lint`: validates AGENTS/GRACE enforcement files without
  executing a shell command.
- `gate.acceptance_review`: projects whether a task currently satisfies package
  acceptance, worker report, and agent-infra prerequisites.

`workpackage.create`, `submission.create`, GLM acceptance, and Codex final
acceptance call these validators internally. A client can preflight with the
`gate.*` tools, but cannot bypass the same checks by calling the lifecycle
tools directly.

## Transactional hooks

The server has a trusted in-process `HookRegistry`, not a public scripting
surface. It audits and revalidates the relevant scope after task, artifact,
package, submission, and review mutations. A rejected GLM package enables only
its assigned Pro repair path; the Codex final gate requires all canonical GRACE
artifacts; a Codex acceptance closes the task atomically.

`gate.promote` is an internal EventBus event and intentionally is not an MCP
tool. Hooks do not accept shell commands, scripts, or client-defined handlers.