Troubleshooting

Symptom, cause, and fix for the most common Orchemax friction points: the reaper, stale locks, PATH, second Chair, permission timeouts, silent hooks, and usage showing zero.

Grep this page by the error string you're seeing — each row is a self-contained symptom/cause/fix triplet.

The reaper reclaimed a session I thought was still running#

• Symptom: locks, a running task, or a worktree from a session disappeared while you weren't watching.
• Cause: the daemon reaps dead sessions on a clock (daemon.reap_interval_sec, default 60s). Once a killed/crashed agent's seat looks abandoned, the reaper frees what it held: its shared_locks rows, its running task row, and — for an isolated checkout — its worktree.
• Fix: expected cleanup, not a bug. To stop it entirely (not recommended), set daemon.reap_interval_sec: 0.

A shared-path lock won't budge, or orch lock acquire fails#

• Symptom: orch lock acquire <path> --holder <id> fails, or a stale lock blocks a guard check.
• Cause: locks carry a TTL (--ttl-min, default 15 minutes) — a session that died before releasing leaves the lock held until it expires.
• Fix: orch lock status <path> (or no path, for the full list) shows expires_at; once expired, any holder can re-acquire it. orch msg stale --older-min 15 finds stale unread alerts more broadly.

orch: command not found after install#

• Symptom: orch isn't recognized in a new shell right after install.
• Cause: orch setup updates the user PATH, not the current process's PATH — an already-open shell doesn't see the change.
• Fix: open a new terminal. If it's still missing, run orch setup --prune-path --dry-run to see what Orchemax believes is on PATH, then orch setup --prune-path to reconcile.

"project already has Chair session … — one Chair per project"#

• Symptom: starting a second interactive Chair on the same project is refused with that exact message.
• Cause: by design, a project runs one interactive Chair at a time (ChairOnly seat claim) — two Chairs racing to dispatch workers on the same project would double-claim work.
• Fix: join the existing Chair session, or dispatch with --force-chair if it's actually dead and the reaper hasn't caught up. Workers never hit this — spawn them with orch task run.

"Outside the Team work schedule…"#

• Symptom: dispatch / spawn fails with a plain sentence about the Team work schedule (not plan deny: capability=…).
• Cause: Team (or Enterprise) has an enabled weekday window and the company clock is outside those hours, or that weekday is Disabled. Ignored days and empty schedules do not gate.
• Fix: wait for the window, or ask a Team admin to adjust hours / Ignore the day at orchemax.com/app/schedules. Then refresh the lease: orch server entitlements. See Team work schedules.

"every route is cooling, soonest available in Ns, beyond the Ms wait cap"#

• Symptom: a 502 from the local gateway naming every provider as skipped: in cooldown or circuit open, and a soonest-available time past the wait cap.
• Cause: every route in the chain is cooling at once. A 60s cooldown is the quota / rate-limit path (HTTP 429 or 402, or a body saying rate limit, insufficient quota, out of credits); 300s is the unreachable path. A chain of free tiers hits the first one together, which is what a free tier does.
• Read what happened: <workshop>/.orch/gateway.err carries one line per failed dispatch — [gateway] dispatch failed model=… class=cooling err=… — and the error text names every provider it tried and why. orch usage shows the attempts; a row with error_class=cooling is this, not an upstream fault.
• Fix: let it wait instead of refusing. gateway.cooldown_wait_ms caps that wait (0 = the router's 30s default, negative = never wait); 90000 covers a 60s rate-limit cooldown with margin. Restart the gateway after editing (orch gateway service restart) and the startup line reports the cap in effect. Add a paid route to the chain if free tiers are not enough.

"…allows N concurrent worker…" / Chair open-agent cap#

• Symptom: spawn refused because concurrent workers are full, or opening another interactive Chair hits the plan's open-Chair ceiling.
• Cause: orch.agents.concurrent meters workers; orch.agents.max meters open Chairs (MCP-only Chairs do not consume the worker meter).
• Fix: wait for a worker to finish, close an idle Chair seat, or upgrade the plan. Optional agents.workers in orch.yaml only prefers cheap models — it does not raise the cap.

OpenClaude model / MCP permission friction#

• Symptom: picker always shows orchemax/pareto; or mcp__orch__verify_status has been denied in dontAsk mode.
• Cause / fix: see Common seat tune-ups (env.OPENAI_MODEL pin; dontAsk vs bypassPermissions + mcp__orch__*).

A worker exits 126 or 124#

• Symptom: a dispatched worker's .orch-agent.log ends with exit 126 or 124 and no useful diff.
• Cause: 126 = Orchemax detected a headless permission/write denial (the CLI tried to prompt interactively and couldn't). 124 = it hit agents.timeout_sec (wall-clock cap) or agents.idle_timeout_sec (no stdout/stderr for that long).
• Fix: for 126, make the preset's headless command allow writes without an interactive prompt — see configure-agents.md. For 124, raise agents.timeout_sec/--timeout, or raise/disable agents.idle_timeout_sec if the agent is just slow.

A context hook seems to do nothing#

• Symptom: context.hooks.post_tool/pre_compact is true in orch.yaml, but tool output never shrinks and BOARD.md never condenses.
• Cause: orch hook post-tool/pre-compact resolve orch.yaml the same way every command does — outside a registered workshop (no resolvable orch.yaml) the hook silently returns and does nothing, by design (a context hook must never fail loudly and break the agent it's helping).
• Fix: confirm orch home resolves a workspace from where the hook runs, and that orch guard wire --claude (or the OpenCode plugin wire) actually installed it — the orch.yaml flag alone doesn't wire it in.

cursor-agent says a hook failed with a syntax error near &#

• Symptom: a worker running cursor-agent on Windows has every tool blocked, and its log shows a hook dying with syntax error near unexpected token '&'.
• Cause: cursor-agent picks bash to evaluate its own (PowerShell-flavored) hook wrapper when the process environment has a POSIX-looking SHELL — which it inherits when the Chair itself ran under Git Bash (Claude Code → orch mcp → worker). Orchemax strips SHELL/MSYSTEM* from a dispatched worker's environment for exactly this reason; an older orch build did not.
• Fix: update orch. If it recurs, confirm nothing else re-sets SHELL in the workspace or the agent's own config before it launches.

A worker closes "ok" but its log says "MCP server does not exist: orch"#

• Symptom: a dispatched worker's .orch-agent.log shows the CLI itself complaining it has no orch MCP server (MCP server does not exist: orch or orch MCP is not connected), yet the session still closes and verify_status used to read guardrails: ok.
• Cause: the CLI loaded only its machine-global MCP config and never approved the worktree's own .cursor/mcp.json / .mcp.json / .orch/mcp.json — every worker-side MCP tool (msg_send, verify_report, lock_acquire, code_snippet, search_shared_symbols) was unreachable for the whole session. For cursor-agent specifically: cursor-agent mcp list shows the project server stuck at "not loaded (needs approval)" in headless mode, because nobody is there to approve it.
• Fix: update orch — the cursor preset now passes --approve-mcps, and verification now fails with reason orch MCP unavailable in worker whenever the log carries that marker, instead of reading "ok". If a different CLI still shows this, confirm it has a documented flag or workspace-config convention for auto-loading project MCP servers headless (copilot reads .mcp.json on its own; agy has no per-workspace MCP config at all — run orch guard wire --agy --scope user --allow-user-scope once to register orch in its global one, which is what its reason line tells you — see configure-agents.md).

orch cursor freezes on “MCP servers need to be approved”#

• Symptom: interactive Cursor shows Approve for the orch MCP server, then hangs on Applying your selection... until you kill the terminal.
• Cause: Cursor’s MCP approval whitelist (mcp-approvals.json) hashes the project server entry. Orch rewrites .cursor/mcp.json with a new ORCH_SESSION each seat, so the hash misses and the TUI returns every launch. Without --approve-mcps on the interactive preset, that dialog is unavoidable — and applying it often freezes under the seat console.
• Fix: update orch (interactive default is cursor-agent --approve-mcps --trust). Or set agents.interactive.cursor / ORCH_AGENT_CMD the same way. Field matrix for other CLIs’ allowlists: common seat tune-ups — vendor allowlists.

Cursor / Claude plan / Codex lost connectors after gateway connect#

• Symptom: after pasting :8788 / orch_gk_… into Cursor, Claude Code, or Codex, the seat asks for an API key, drops plan connectors, or gateway returns 403 on an OAuth bearer.
• Cause: those seats default to account / plan login — model traffic stays on the vendor login. The gateway is only for API-key / BYO seats.
• Fix: restore the vendor login; set agents.auth.<preset>: account (or leave unset). Do not point plan seats at the gateway. See common seat tune-ups — account / plan login.

orch usage shows zero right after a session#

• Symptom: a plan-billed seat (e.g. Claude Code on its own login) just ran, but orch usage shows no tokens for it.
• Cause: there's no billing API for a plan login — usage for these seats comes from scanning the harness's own transcript files under ~/.claude/projects/<slug>/*.jsonl, which can lag the live session.
• Fix: re-run orch usage after the transcript is written — it scans transcripts on every invocation, so a second run is enough.