Agent activity: messages, events and lifecycle

Gotchas and known limits

• control-openhands conversation events <id> returns the last 25 events unless you pass --last N; it reads the server's 100-event pages until N rows are in hand (pages says how many it read, more: true that older pages remain), so --last 500 covers a 150-event conversation in two pages (total 152, pages 2, more false on the Older history conversation; --last 25 there reads one page, more true) and --from-start reads from the oldest. --kinds and --grep filter before --last counts, and pages are read until --last matching rows are in hand: --kinds MessageEvent --last 3 is the three newest messages, --kinds MessageEvent --last 500 all thirty, and --grep 'qa older 1' reaches qa older 1 on the oldest page with the default --last (count 11, pages 2). Event texts are cut at about 160 characters.
• --observe takes the same selector syntax as the verbs: testid= and plain CSS segments (joined with >> ) are watched by an in-page MutationObserver (observedBy mutation; the Older history bullet's --observe 'testid=loading-older-events' is one), while other engines (role=, text=, nth=) are polled every 20 ms instead (not driven in this family).
• role=button[name="Expand"] also matches "Expand thinking" and "Expand actions"; use [exact] to target tool rows. Each click flips the row to Collapse, so nth=0 walks to the next collapsed row.
• Tool rows show no success icon; the only indicators are the exit N badge for non-zero exits and a clock icon (status-icon) for timeouts. A single action is not grouped: it renders as a bare row without event-group.
• The model writes the tool titles and may append to commands (it turned ls /missing into ls ...; echo "EXIT:$?", exit 0). Ask for the command "verbatim, with nothing appended" when the exit code matters.
• The agent itself may open files with canvas_ui_control (a third action in the echo/file run). Close the file tab before proving that a path link opens it.
• On Settings → Verification the Security Analyzer field (All tab) is shown only while Confirmation Mode is on: switch Confirmation Mode on first, then pick the analyzer. Check api GET /api/settings after saving.
• Confirmation mode with the default Security Analyzer LLM uses ConfirmRisky(HIGH): harmless commands run without a prompt. Set the analyzer to None to confirm every action, and restore LLM afterwards. The composer stays editable while waiting (status "User needed"); the buttons read Cancel / Continue.
• Known failure, Canvas UI: after Cancel the event group keeps a spinner and "1/2 actions completed" forever, even after reload, although the conversation is idle and the server recorded UserRejectObservation (the group only counts ObservationEvents) (#17920). Evidence F06.confirmation-mode/rejected-after-reload.png.
• Known failure, Canvas UI: the confirm/cancel shortcuts check only metaKey; on Linux/Windows Control+Enter does nothing although the composer and plan shortcuts accept Ctrl (#17928).
• Known failure, Canvas UI (repro candidate, not filed yet): after a user-message branch the composer holds the prefilled text but Send stays disabled (browser enabled 'testid=submit-button' is false, and a click on it times out with element is not enabled). The prefill is a saved draft that src/hooks/chat/use-draft-persistence.ts writes into the field without an input event, and the composer is reused across the client-side switch, so its Send state keeps the source conversation's empty field. Editing the text, a reload, or Enter in the field (browser press Enter --selector 'testid=chat-input') all work. A draft restored by a sidebar switch behaves the same (F05 Gotchas).
• Known failure, likely Agent Server: every message in a branched conversation ends with ConversationErrorEvent LLMAuthenticationError ("Your LLM API key appears to be invalid or has expired."), while the source conversation keeps working (OpenHands/software-agent-sdk#5465). Do not use branches as fixtures for other checks.
• "The terminal session was reset because the underlying tmux server/session disappeared" (clock status-icon on the row) appears after a service stop agent-server / restart cycle. Since launch gives each run its own short TMUX_TMPDIR, other runs no longer cause it. The underlying product bug is still open (OpenHands/OpenHands#17946) for plain agent-canvas instances: bin/agent-canvas.mjs → scripts/dev-with-automation.mjs passes TMUX_TMPDIR=<state>/tmux to the Agent Server but ensureDirectories never creates it (dev-safe.mjs does), so tmux 3.4 falls back to the shared /tmp/tmux-<uid>/openhands socket and another instance's restart or stop kills this run's windows. The model usually reruns the command; expect an extra action.
• The ConversationErrorEvent banner is not restored after navigating away and back (or a reload); read the error from the events API instead.
• After restart, reconnection takes about 20 s without a click; click error-message-banner-retry to reconnect at once. The error banner does not come back after a page reload once the stack is healthy.
• "Sending..." lasts about 100 to 650 ms on a local stack, too short to hover and click chat-message-stop; that stop path is not driven here. The F06.pending-messages failure path needs service stop agent-server.
• browser clock installs a fake clock that stays with the page across reloads and client-side navigation. Install it before the goto whose page should see it, and put it back with browser clock --offset-ms 0 plus browser reload; compare browser eval "new Date().toISOString()" with date -u when in doubt.
• The pending-message queue lives in page memory, so a failed bubble survives sidebar navigation and a backend restart but not a browser reload or browser goto of the conversation (src/stores/optimistic-user-message-store.ts). Leave and return through the sidebar when proving F06.failed-send-persists. The sidebar card's title is the first message or model-written: click its link by id, 'a[href*="/conversations/<id>"] >> nth=0'.
• Both the pending bubble and the echoed message carry testid=user-message, so count 'testid=user-message >> has-text=...' is one too high while a failed bubble is still shown; count attempts with conversation events <id> --kinds MessageEvent (user rows: "source": "user") and the bubbles with chat-message-retry.
• Local Stop calls the Agent Server's interrupt (Cloud pauses the sandbox instead, see pauseConversation): a command already running in the terminal is cut off, recorded as AgentErrorEvent + InterruptEvent, and after Play the model only reports the interruption.
• The no-LLM banner reuses the home banner's test ids (home-llm-not-configured-banner). It exists only in a run where no LLM was ever configured: use a separate launch --new, never remove the profile from the shared run.
• Read the clipboard with control-openhands browser clipboard, never browser eval "navigator.clipboard.readText()". An agent bubble that contains a code block holds two copy-to-clipboard buttons (the code block's is hidden until hovered): scope the bubble's with >> nth=0.
• Plan-mode previews (plan-preview-*) and the BTW side messages render in this stream but are reached from the composer's mode controls; they are not mapped here.