Troubleshoot custom harnesses and agents
Start from the symptom. Each harness entry names the first check; the custom harness FAQs further down have the full fix. The cloud agent REST API lifecycle is at the end. When you file a bug, include one agent logs, the harness version and manifest digest from agent details, and one one harness dev run.
Install and discovery
one harness install rejects the manifest
Run one harness validate ./one.json and fix the line-level errors; the usual cause is command written as a shell string instead of an argv array, or one.json missing from the source root.
Install fails at the doctor step
Run the doctor command in a non-interactive shell (zsh -c 'conductor --version'); version managers initialized only in interactive shells are the usual cause.
The harness is missing from Desktop or one agent create
one harness list is the source of truth; detected entries appear only from valid manifests in ~/.one/runtimes.d/ whose name does not collide with a built-in or installed harness.
Sign-in and connectivity
The agent shows offline while the process runs
Run one agent status: the daemon may have died after a logout or reboot, the CLI session may have expired (one auth login), or the machine clock is skewed.
Turns fail with the agent's own auth errors
The harness's vendor login is separate from One Horizon sign-in, so re-authenticate with the vendor's tool, then run one agent doctor. A model provider 401 usually means the key is a shell export the background daemon never sees, so put it in a .env file or the OS keychain. A 403 means the key cannot use that model or endpoint.
Curated OpenCode cannot use web search
Run one harness list and one harness doctor opencode. OpenCode 2.x needs an enabled provider in its effective configuration or one of EXA_API_KEY, FIRECRAWL_API_KEY, PARALLEL_API_KEY, or TAVILY_API_KEY in the environment that starts the agent. disabled reflects OpenCode configuration; unknown means version or configuration detection failed. Readiness is advisory, so the harness can still start while search is unavailable.
One Horizon forwards only the selected provider key, except when OpenCode is configured for random selection. Keys remain machine-local and are never copied into the harness catalog or model snapshot. Search queries go to the external provider and may incur charges.
Turns and protocol
Turns fail instantly with a protocol violation
Something wrote to stdout or the process exited before initialize; log to stderr and run one harness dev to see the first malformed line.
Turns time out with no activity
The agent went silent past the stall window. Emit session/update while working, and stream tool_call_update from long tool calls.
review, research, or plan turns always fail
Review turns must call report_workflow_verdict; plan and research turns must write their declared blocks with append_artifact_block, and research must leave the repository unchanged. See documents and tools. A mode listed in unsupportedModes is never routed to that runtime.
A non-Execute turn ends without report_result
That turn still completes: only Execute requires report_result, and other modes fall back to the normal successful terminal summary.
The session parks as awaiting input
The agent refused (stopReason: refusal) or asked for input; the user's answer resumes the session, and refusals are never auto-retried.
Mistral Vibe never calls the required one_platform tool
Vibe's generic MCP tool permission defaults to Ask. The host grants a one-time allow when it can match the requesting tool to the injected one_platform server (see headless behaviors). If a required call such as append_artifact_block or report_workflow_verdict still never happens, look in the session transcript for a session/request_permission that was cancelled rather than approved: an ambiguous tool identity falls back to Vibe's Ask policy and stalls with no human present. Vibe releases can change whether permission requests carry per-tool identity, so record the tested Vibe version in any bug report.
Git and worktrees
Workspace preparation fails
The agent's projectRoot must be a writable Git repository with a usable base branch, and it is fixed at agent creation; if the folder moved, create a new agent. Clean stale task worktrees with one agent worktrees remove <task-or-path>.
Forced worktree removal discards uncommitted changes. Preserve the branch and any required files before adding --force.
The branch pushed but no PR or MR appeared
PRs and MRs are created through the workspace's GitHub or GitLab integration, not the agent's credentials, so confirm the integration is connected and PR creation is enabled in the workflow.
Operations
Work is queued but the agent stays idle
Run one agent status, then check concurrency and resource pressure, which agent the work targets, whether the mode is excluded, and whether the harness is paused pending re-consent.
Works in one harness dev, fails registered
The registered agent runs with an allowlisted environment, not your interactive shell; one agent doctor runs your doctor check in that environment.
Custom harness FAQs
Cloud agents (REST API)
Cloud agents implement the session lifecycle directly. Keep the failed request, HTTP status, session state, active claim ID, and latest activity together while debugging.
Agent endpoints reject the token
Use an OAuth user access token with the required agent scopes. Workspace API keys cannot call agent execution endpoints.
Revoke any token written to logs, task text, comments, documents, or source control. Store replacement credentials in a secret manager or operating-system secure storage.
No webhook arrived, or a webhook arrived twice
Webhooks only wake the agent; polling is the required recovery path. Deduplicate by event ID, then fetch eligible sessions and claim them. Do not start execution from webhook contents alone.
Claim conflicts and rejected claimId
A conflict means another harness owns the active claim, the session was cancelled, or your harness is no longer eligible; stop processing that session. Every mutation after claim must include the current claimId.
A claimed session never leaves active
Every execution path must call complete, fail, or release. Use release only when the harness stops before useful work. Review-mode sessions must set reviewVerdict to approve, feedback, or reject before completion.
Agent sessions covers the full lifecycle, targeting, resume, and delegation contract.