Skip to content

Troubleshooting

Confirm the global Bun bin directory is on PATH:

Terminal window
bun pm bin -g
bun add -g @agenticengineeringagency/ultimate-harness
uh --help

For local development, build first:

Terminal window
bun run build
node dist/cli.js --help

The CLI is Node-compatible, but the OpenTUI/Solid TUI intentionally runs through Bun so TSX can load with the Solid preload.

Terminal window
bun --version
uh tui --once

Use the runtime-specific runbook:

Do not put provider keys into adapter manifests. Use environment variables or the runtime’s own credential store.

Invalid mission id From run-team, report Or steer

Section titled “Invalid mission id From run-team, report Or steer”

uh mission run-team takes a mission id (wave-a), not a path to mission.yaml. uh report and uh steer take a run id or a unique prefix of one, not a mission id; find it with uh ps --all.

A team packet installs its worker packets only when they are given in the same call:

Terminal window
uh mission put team.yaml worker-a.yaml worker-b.yaml

uh land reads collected reviews from the project that owns the worker worktrees. If the reviews live somewhere else, pass that project explicitly:

Terminal window
uh land --worker-branch <branch> --onto <target> --message-file <file> --review-root <project>

A review counts only when it names the branch’s team mission and its captured file hashes match the branch tip; after any change to a reviewed file, collect a new review. uh land also refuses a target worktree that is not on --onto (another branch or a detached HEAD; check out the target branch there first), a dirty target worktree, and a worker branch without a retained worktree; run teams with --retain.

Command Code 1.62.1 crashes after a single tool result of roughly 70K characters or more (CommandCodeAI/command-code#859). The guard makes large file reads windowed; keep shell output small in Command Code packets (no recursive listings, no whole-file dumps, no full test-suite output).

Plugin Tests Cannot Import FastAPI Or httpx

Section titled “Plugin Tests Cannot Import FastAPI Or httpx”

Install the plugin test dependencies:

Terminal window
python -m pip install -r apps/hermes-plugin/dashboard/requirements-dev.txt
bun run plugin:test

The tests use fake runners and isolated temp .harness/ state; failures usually indicate missing Python dependencies or a plugin API regression.

Scoped package dry-runs expect a token-shaped value. CI uses a dummy value for dry-runs:

Terminal window
NPM_CONFIG_TOKEN=dry-run-token bun run publish:dry-run

Real publishing requires the NPM_CONFIG_TOKEN repository secret and should only run through the release workflow.