1490da10f9
Add task lifecycle diagram, review states, auth configuration blocks, common member states, CLI auth diagnostic, and safe-cleanup guidance. Synchronize EN and RU pages for runtime-setup, agent-workflow, code-review, and troubleshooting.
113 lines
4.1 KiB
Markdown
113 lines
4.1 KiB
Markdown
# Troubleshooting
|
|
|
|
Most team issues fall into one of four buckets: runtime setup, launch confirmation, task parsing, or provider limits.
|
|
|
|
## Team does not launch
|
|
|
|
Check:
|
|
|
|
- The selected runtime is installed or authenticated
|
|
- The runtime is available in the environment `PATH`
|
|
- The provider has access to the requested model
|
|
- The project path exists and is readable
|
|
|
|
::: tip
|
|
Run the runtime binary directly in a terminal to verify it is on PATH and authenticated. For example: `claude --version` or `opencode --version`.
|
|
:::
|
|
|
|
### OpenCode bootstrap unconfirmed
|
|
|
|
If OpenCode shows `registered` but bootstrap is unconfirmed:
|
|
|
|
1. Inspect the launch logs in the UI.
|
|
2. Check `~/.claude/teams/<team>/launch-state.json` for the member state.
|
|
3. Look at `~/.claude/teams/<team>/.opencode-runtime/lanes/<lane-id>/manifest.json` for evidence.
|
|
4. Do not change team prompts until you confirm whether the lane started but failed to commit evidence.
|
|
|
|
::: warning
|
|
A missing OpenCode inbox during primary launch is normal. Secondary lanes start after primary filesystem readiness. Do not treat primary hang as an OpenCode bug unless the UI explicitly shows `Y` members waiting with `Y` incorrectly including OpenCode lanes.
|
|
:::
|
|
|
|
## Agent replies are missing
|
|
|
|
Open task logs and teammate messages. Missing replies often come from:
|
|
|
|
- Runtime delivery gaps
|
|
- Parsing or task filtering issues
|
|
- The agent is still processing (large tasks may take minutes)
|
|
|
|
Do not assume the model ignored the message until logs confirm it.
|
|
|
|
::: tip
|
|
For OpenCode teammates, check that `agent-teams_message_send` was called with the correct `from`, `to`, and `taskRefs`. OpenCode replies must be sent via MCP tools, not plain text.
|
|
:::
|
|
|
|
## Tasks are not linked to changes
|
|
|
|
Use task-specific logs and code review links. If a diff appears detached:
|
|
|
|
- Check whether the task id or task reference was included in the agent output.
|
|
- Verify the agent called `task_add_comment` before making edits.
|
|
- Ensure the agent called `task_start` so the board knows work began.
|
|
|
|
## Rate limits
|
|
|
|
If a provider reports a known reset time, Agent Teams can nudge the lead to continue after cooldown. If reset time is unknown, wait or switch provider/runtime path.
|
|
|
|
## Common member states
|
|
|
|
| State | Meaning |
|
|
|-------|---------|
|
|
| `confirmed_alive` + `bootstrapConfirmed` | Healthy and usable |
|
|
| `registered` / `runtime_pending_bootstrap` | Process or lane exists, but bootstrap proof is not committed yet |
|
|
| `failed_to_start` + `runtime_process` | A process exists but the launch gate failed. Inspect diagnostics |
|
|
| `failed_to_start` + `stale_metadata` | Persisted pid/session is old or dead |
|
|
|
|
::: warning
|
|
`member_briefing` alone is NOT runtime evidence. For OpenCode, the authoritative proof is committed runtime evidence such as `opencode-sessions.json` and its manifest entry.
|
|
:::
|
|
|
|
## Teammate runtime debug mode
|
|
|
|
For local debugging, you can force pane-backed teammates through `tmux`:
|
|
|
|
```bash
|
|
# Terminal launch
|
|
CLAUDE_TEAM_TEAMMATE_MODE=tmux pnpm dev
|
|
|
|
# Or add to custom CLI args
|
|
--teammate-mode tmux
|
|
```
|
|
|
|
Use this to inspect interactive CLI behavior. Do not treat it as equivalent to the process backend for recovery semantics.
|
|
|
|
## CLI auth diagnostic
|
|
|
|
Each run of `CliInstallerService.getStatus()` appends one line to `claude-cli-auth-diag.ndjson` inside the Electron logs folder (typically `~/Library/Logs/<product-name>/` on macOS). If the file exceeds **512 KiB**, it is truncated to empty before the next append.
|
|
|
|
Check this file if you see "Not logged in" or authentication errors in the packaged app.
|
|
|
|
## Safe cleanup
|
|
|
|
When cleaning up stale processes:
|
|
|
|
1. Identify the pid and confirm it belongs to the current team/lane.
|
|
2. Stop only processes explicitly owned by the smoke test or the launch you are debugging.
|
|
3. Do **not** kill all OpenCode processes or shared hosts as a shortcut.
|
|
|
|
## When to collect evidence
|
|
|
|
Collect:
|
|
|
|
- Task id
|
|
- Team name
|
|
- Runtime path
|
|
- Launch log excerpt
|
|
- Provider/model
|
|
- Exact time window
|
|
|
|
This is enough to debug most launch and task lifecycle issues.
|
|
|
|
::: tip
|
|
If the problem persists, open the team's persisted files under `~/.claude/teams/<teamName>/` and correlate UI diagnostics with live process state before changing code.
|
|
:::
|