Agent Note: Product-level TUI session resume

Status: implemented

English | 中文

Problem

The original /resume printed shell commands. It did not let a keyboard user inspect titles or outcomes, distinguish corruption from a missing adapter, or safely transfer the terminal. Leaving the TUI and manually launching a command also hid the required ordering: finish current work, flush it, release the UI and app, then restore the exact persisted identity without silently creating a replacement.

Decision

/resume uses the TUI's existing interactive overlay seam as a full-viewport picker rather than a centered dialog. The flat page keeps the search field, workspace, candidates, and shortcut footer in stable screen regions; only the active row uses the accent role. Its search editor starts immediately after the search glyph and emits pi-tui's cursor marker, so terminal IME composition remains anchored in the field. Escape clears a non-empty query before a second Escape closes the picker. It lists the current workspace by last logged activity and searches log-backed title or id. Each candidate displays current/live/persisted state, last turn outcome, recent provider/model, durable goal phase when present, and the id as secondary text. The current session and sessions already live in this runtime remain visible but disabled.

session-query.readSession() supplies a detached complete log validated by the same core replay boundary used by resume. The TUI folds title and goal state from that log. A candidate load failure is local to that row; selecting a candidate revalidates the log, cwd, route, current agent's idle status, and the exclusions for the current session and sessions already live in this runtime, so a stale listing cannot bypass preflight. A missing adapter reports an intact session with an unavailable route. This preflight does not lock the target or exclude another process.

After preflight, the TUI flushes the current session, confirms that its agent remains idle, then stops the terminal before calling TuiRuntime.handoffResume. The shipped dsh host disposes the root app and uses process.execve with a normalized --resume argument, atomically replacing the process rather than starting a child. The resumed app publishes the same SessionId; ordinary replay restores transcript, title, todos, and durable goal state. Goal activation is intentionally disarmed, and the TUI asks for human confirmation or /goal resume.

resumeCommand remains an exit and no-host fallback. The TUI substitutes {session} only for display and never executes arbitrary shell text. The exit hint still appears only after the current session is durable.

Alternatives considered

Have the TUI spawn resumeCommand. Rejected: the template is deployment text, not trusted argv, and the TUI does not own app teardown or process lifetime. The constrained host seam receives only a validated SessionId.

Construct the resumed agent inside the existing TUI. Rejected: replacing one config-created agent would cross Loader ownership, scoped plugin setup, persistence retirement, and terminal lifecycle in the presentation layer. Root disposal plus process replacement reuses the supported startup path.

Treat a missing adapter as a missing session. Rejected: storage validity and current route availability are independent facts. The selector keeps the row and names the unavailable provider/model.

Persist goal activation across resume. Rejected: durable intent is not authorization to continue after a human or process boundary. Goal phase survives; automatic continuation does not.

Consequences

Concurrent processes can select or resume the same persisted session because preflight does not serialize them.
/resume depends on session-query for discovery and complete-log reads, but persistence and host handoff remain optional; without a host, the command fallback stays usable.
Process replacement intentionally restarts Loader composition. Runtime-only state is rebuilt, while only logged or header-backed session state survives.

Testing

TUI tests cover keyboard navigation, title/id search, search-clear/cancel behavior, running-agent refusal, refusal of the current session and sessions already live in this runtime, route absence, corrupt rows, preflight revalidation, fallback commands, and stop-before-handoff ordering. Session-query tests pin detached full-log validation. Agent-loop resume tests pin exact identity and history; title, todo, and goal replay suites pin restored projections and disarmed goal activation. The keyless TUI snapshot owns the full-viewport selector and its IME cursor anchor, and a real PTY smoke covers search plus handoff.

4.7 KiB Raw Blame History