Use this index to open only the troubleshooting domain relevant to the symptom. Entries record recurring, evidence-backed failure patterns; one-off defect journals belong in Git history.

Entry Format

Each entry should include the symptom, quick checks, root cause, fix, validation, and references when useful. Add a new entry only when the pattern is likely to recur and the repository now has implementation or debugging evidence for it.

Agent Runtime

Use the focused runtime index or open one area directly:

Agent Providers And Setup: Provider discovery, installation, authentication, models, configuration, and runtime reachability. Includes Codex Model Plan Responses-to-Chat routing, oversized request metadata compatibility, and extension command/Skill palette hydration failures. Also covers uv-managed Extension installs that accidentally select an incompatible system Python. Also covers Kimi Code ACP sessions that advertise no model or hide provider failures behind an empty end_turn. Also covers Cursor ACP session-service startup races and tool results that hide aborted/TLS failures in provider-specific output fields, plus Cursor CLI questions that are absent from the ACP tool catalog. Also covers focus-driven provider CLI scans, repeated Extension Target version probes, Windows managed-runtime adoption sharing violations, optional Provider absence misclassified as an environment failure, extension release refresh delaying daemon startup, Tutti Agent browser login that loses the managed Node environment, repeated Hermes helper downloads in isolated session homes, and CPU spikes.
Agent Sessions And Lifecycle: Turn state, activation, planning-mode classification, capability snapshots, Tutti workflow response contracts, loading, cancel, goal controls, restore, file-change undo, rail projection, realtime completion provenance, event updates, imports, and performance. Includes shared-device recovery that looks terminal while the host is still retrying. Also covers new or derived conversations that silently fail or lose project/Git ownership when a runtime worktree is mistaken for a canonical project (or the source Session is unavailable), and one hung provider startup blocking unrelated Agent sessions. Extension snapshot failures that erase the Agent's Tutti CLI command catalog or block restart resume are covered here as well. Includes cassette replay startup that fails when concurrent provider input and output are treated as a strict scheduling order, false final-state mismatches caused by replay-generated child identities, an orphan managed Replay Desktop that crashes with EPIPE after its owner exits, and canonical completion delayed behind a streaming activity-report backlog. It also covers an active existing-Session Tutti snapshot being misread as provider Default mode, stopped Tutti Mode conversations revived by legacy startup wakes, provider-completed submissions reported as delivery unknown after canonical message provenance conflicts, completed Claude Code Turns that lack a Fork entry because provider identity was not observed from the durable transcript, Claude failures before provider Turn identity that leave AgentGUI thinking, and Claude Fork operations that fail because an empty query never creates a durable provider child. It also covers a Claude Query that keeps returning connection errors after the machine network recovers, and forked conversations that disappear from the Rail after their active/running overlay settles. Also covers inactive Claude Resume timing out the queue send and leaving later prompts stuck as 排队中 behind uncertainDelivery, and Standard ACP process cleanup failures that stop a send before provider dispatch while preserving the composer draft. Standard ACP cancellation that returns before the active provider prompt drains, causing every later prompt to remain provider-queued, is covered here too. Historical Standard ACP sessions that reject image preflight before reconnect, or incorrectly choose replaying session/load over an advertised object-form session/resume, are covered here as well.
Agent Approvals And Child Sessions: Approval gates, plan exits, root/parent/child event attribution, child sessions, and Message Center. Includes provider-native work that continues invisibly after root cancellation and late child creation racing the durable cancel boundary.

Issue Execution

Issue dispatch, Run cancellation, Agent settlement, and stop coordination.

Desktop And Release

Electron startup, daemon supervision, macOS packaging, updates, and performance diagnostics.

Workbench And Renderer

React rendering, Workbench state, external stores, input composition, and UI performance.

Workspace Apps And Files

App Center, workspace-app lifecycle, App Factory, file references, and File Manager.

Connector Market

Connector catalog, installation, account authorization, and runtime convergence.

Toolchain, Browser, And Terminal

CLI behavior, CI, package assets, skills, Browser Node, and terminal input.

Mobile

Android app login, native bridge, secure identity, and mobile transport diagnostics.

Computer Use

cua-driver discovery, targeting, capture, input delivery, and result verification.