Start with the layer that failed
Keep the original result and decide whether the problem is the client connection, a tool error, one terminal's result, the command's own outcome or the observation itself. These layers have different success signals. Use a harmless read or list where possible, and keep retries of side-effecting work deliberate.
Tools are missing or the terminal set looks different
Confirm the selected service and environment, then initialize the intended connection and list tools. A new connection can receive a different client identity, and a terminal identifier from another identity is not necessarily visible to you. Switching the service to shared mode changes who can operate every terminal and belongs to the service owner.
The terminal is missing, detached or exited
Use the retained identifier to inspect the available state. If the process exited, start it again in a new terminal. A missing record can come from client-session teardown, idle cleanup, detached expiry, a service stop or a failed recovery. Report the sanitized identifier and error before recreating important work.
A command times out or has no exit value
A foreground run waits up to its timeout, 120 seconds by default, and can return partial output with timedOut: true. A named shell can still be running the command. Read the screen before deciding what to do. For longer work, choose a larger timeout in advance or use a background run.
Output is truncated or a capture cannot be found
The inline preview shows a head and a tail. For an ephemeral foreground run, read the full capture with terminal_read in run_output mode and its runId, from the same client identity and while the bounded store keeps it.
Incremental output is empty or skips lines
Incremental reads consume a cursor shared by every reader of the terminal and return only finalized lines. Use screen mode for the current view and scrollback for earlier lines.
A watch is acknowledged but no events arrive
Subscription, output, delivery, forwarding and client consumption are separate steps, and small output can stay below the sampling thresholds. Use explicit screen or stats reads for the observation you need, or pull frames after starting a frame watch. End observation with off: true.
Close succeeds but a process seems to remain
Keep the exact target and result, use the workload's own shutdown signal, and involve the service owner. Close the single terminal rather than all terminals, since in shared mode others can have work there.
Browser access fails or stays open after revocation
attachUrlBridge configuration, and whether this terminal was explicitly exposedattachUrlWhat you getThe failing layer named, and a retry planned after checking what already took effect.