Umpire

Umpire is the @tjalve/aiu CLI for safe agent continuation. It reads configured trusted state commands, evaluates continuation policy, and produces a concrete prompt only when the next action is bounded enough for an agent to continue.

Umpire does not decide quality, planning, or issue status from agent narration. It expects structured local state from trusted commands and treats unknown, malformed, stale, blocked, or untrusted state as a stop condition.

For the full QUBE package family and command deck, see https://zark.github.io/ai-qube/ or the repository landing-page artifact at https://github.com/ZarK/ai-qube/blob/HEAD/docs/index.html.

Install

pnpm add -D --save-exact --ignore-scripts @tjalve/[email protected]
pnpm exec aiu --help

For manual global use:

npm install -g @tjalve/[email protected] --ignore-scripts
aiu --help

What It Provides

• the aiu CLI
• typed .qube/aiu/config.json discovery, defaults, and validation
• read-only diagnostics through aiu doctor
• path inspection through aiu paths
• local continuation state, locks, and redacted logs under .qube/aiu/
• dry-runnable aiu init plans for supported host files
• trusted-state continuation decisions for quality, planning, work, and optional maintenance prompts
• public helper exports from @tjalve/aiu and @tjalve/aiu/opencode

Quick Start

Inspect the current repository before writing files:

pnpm exec aiu paths --json
pnpm exec aiu config --json
pnpm exec aiu doctor --json
pnpm exec aiu init --dry-run --json

Apply a reviewed init plan:

pnpm exec aiu init --tool all
pnpm exec aiu doctor --json

Existing host files that differ from package-managed content are reported as conflicts. Umpire does not replace them unless --force is explicitly selected after review.

Continuation Policy

Quality continuation is driven by configured trusted commands that emit the quality state kind. Umpire can continue quality work only when that state reports a concrete failing stage or finding group, affected paths when relevant, a next command, expected evidence, and a rerun command.

Planning continuation is driven by configured trusted commands that emit the planning state kind. Umpire can continue planning only when planning continuation is enabled and the state includes a concrete next action such as a command, artifact check, or draft path. Human-blocking questions, inconsistent artifacts, approval blocks, and ambiguous mappings stop continuation.

Whip tasks are optional idle maintenance prompts. They are considered only after higher-priority continuation work is unavailable, and prompt delivery alone never completes a task.

Run native lifecycle verification explicitly after initialization:

pnpm exec aiu verify --tool opencode --json

Verification warns before it launches a harness or model. It creates a disposable Git repository, installs a packed copy of Umpire with lifecycle scripts disabled, and checks both the allow and continue paths. OpenCode verification selects a listed free model when --model is absent. If no free model is listed, the command stops and asks for an explicit model. Successful verification records compatible consumed-event evidence for doctor; normal hook delivery does not.

Cursor verification requires an explicit model. List the available Cursor models, select an appropriate low-cost model, and then run:

cursor-agent models
pnpm exec aiu verify --tool cursor --model <model-id> --json

Cursor verification never grants project trust. If Cursor blocks the first run, the JSON report includes trustApprovalPath and preserves that disposable project. Approve that exact project through Cursor's trust surface, then rerun the same verification command.

Run Cursor verification in an interactive terminal. Standard input and standard error must be TTYs. The verifier tests the Cursor CLI project Stop reprompt. It does not assert continuation support in Cursor desktop, cloud, or headless mode. Umpire does not pass Cursor's trust flag or change repository trust.

Host Support

| Host | Status | Init target | Notes | | --- | --- | --- | --- | | OpenCode | Supported | aiu init --tool opencode | A named project plugin delegates /make-it-so to the exact package version declared in .opencode/package.json. | | Codex CLI/Desktop | Experimental | aiu init --tool codex | Stop-hook behavior must be explicitly trusted and verified. | | Claude Code | Experimental | aiu init --tool claude-code | Project settings are preserved on conflict; continuation must be explicitly verified. | | Grok Build | Experimental | aiu init --tool grok-build | Project hooks require explicit trust and verification. | | Cursor | Supported | aiu init --tool cursor | One finite-loop Stop hook is merged into .cursor/hooks.json; unrelated hooks are preserved. | | Generic MCP, Git hooks, GitHub Actions | Not a continuation host | none | These are not interactive idle-session continuation surfaces. |

Safe Uninstall

Remove the package only after host files and trusted command descriptors no longer depend on aiu:

pnpm remove @tjalve/aiu

Review pnpm exec aiu doctor --json, pnpm exec aiu paths --json, and normal git diffs before deleting host configuration.

Safety Notes

• The package has no install lifecycle scripts.
• doctor, paths, config, status, and init --dry-run are inspection-first commands.
• Umpire does not stage, commit, push, open pull requests, close issues, delete files, install package managers, or create provider credentials.
• Umpire does not install, authenticate, trust, restart, or wrap an agent harness.
• Local .qube/aiu/ state, locks, and logs are diagnostics, not provider truth.
• Use pnpm install --frozen-lockfile --ignore-scripts for repository development and trusted publishing for package releases.

Public API

• @tjalve/aiu - config loading, prompt rendering, path inspection, and diagnostics helpers
• @tjalve/aiu/opencode - OpenCode plugin composition helpers
• aiu - package CLI entrypoint

Development

corepack enable
pnpm install --frozen-lockfile --ignore-scripts
pnpm --filter @tjalve/aiu run release:check