Files
kandev/docs/plans/quick-terminal-durable-lifecycle/plan.md
T
2026-08-24 11:09:03 +00:00

145 lines
8.1 KiB
Markdown

---
spec: docs/specs/ui/requirements/quick-terminal.md
created: 2026-08-06
status: draft
---
# Implementation Plan: Quick Terminal Durable Session Lifecycle and Menu Alignment
## Overview
Two user-reported defects remain after the refresh-persistence work shipped:
1. A quick terminal does not survive a page reload in practice. A refreshed tab re-numbers
("Terminal 7") and a new shell is created instead of reattaching to the existing one.
2. The plus-button creation menu opens toward the leading (left) edge of the tab strip, overhanging
the workspace edge, which is awkward.
The persistence infrastructure (durable descriptors, boot payload, resync, reattach by `sessionId`)
already exists and is correct. The reload failure is not a missing-descriptor bug; it is a
**session-lifetime** bug: quick-terminal PTYs share the agent-login `IdleTimeout = 10m` /
`HardTimeout = 30m` in `loginpty`. A quiet or detached terminal is reaped, so on the next boot/resync
`reconcileTab` finds no live session, calls `markUnavailable`, and persists `session_id = NULL` /
`status = exited`. The user then starts a fresh terminal, and `sequence` keeps climbing.
The fix gives quick-terminal host-shell sessions their own lifetime policy: **no idle or hard
timeout**. They end only on explicit tab close (already stops the PTY), natural process exit
(already reported via `HandleSessionExit`), or backend shutdown. To avoid leaking PTYs on shutdown
when the timeout no longer reaps them, the `loginpty.Manager` gains a `StopAll` wired into graceful
shutdown. The menu fix is a one-line alignment change plus coverage.
## Confirmed root cause
- `apps/backend/internal/agent/loginpty/manager.go` `supervise()` applies `IdleTimeout` (10m) and a
`HardTimeout` (30m) `context.WithTimeout` to **every** session, including host-shell sessions
started by quick terminals. A quiet or detached quick terminal is terminated by these.
- `apps/backend/internal/quickterminal/service.go` `reconcileTab()` (run by `List`, which boot state
and GET `/quick-terminal-tabs` both call) sees the reaped session as `!Running` and calls
`markUnavailable`, persisting `session_id = ""` and `status = exited`. This is why reload shows the
terminal as gone and a new one is created.
- `apps/web/components/quick-chat/quick-tab-add-menu.tsx` sets `align="end"` on a `w-64`
`DropdownMenuContent`; the trigger is at the leading edge of the strip, so the menu opens leftward.
## Backend
### Per-session lifetime policy in loginpty
- Add an explicit lifetime policy to `Session`/`StartWithKey` so a session can opt out of the idle
and hard timeouts. Host-shell sessions (`agentID == HostShellAgentID`) use the no-timeout policy;
all other agent-login sessions keep the existing 10m/30m behavior. Prefer a small, explicit
policy value (e.g. a `noTimeout bool` or a `lifetime` struct on the session) set from `agentID`
inside `StartWithKey`, rather than reading `agentID` string comparisons scattered in `supervise`.
- In `supervise()`, when the policy disables timeouts, do not arm the idle timer and do not wrap the
context in `WithTimeout`; still handle natural process exit (`exited`) and external `stop()` so
cleanup, map removal, and `onExit` remain correct. Keep the existing drain/`readDone` behavior.
- Add `Manager.StopAll()` that stops every live session (idempotent), for graceful shutdown.
### Graceful shutdown wiring
- Register a cleanup in `backendapp` that calls `loginMgr.StopAll()` during graceful shutdown, so
no-timeout quick-terminal PTYs are reaped when the backend stops (they previously relied on the
30m hard timeout). Follow the existing `addCleanup`/`runCleanups` pattern used for the lifecycle
manager.
## Frontend
### Menu alignment
- In `quick-tab-add-menu.tsx`, change `align="end"` to `align="start"` on `DropdownMenuContent` so
the menu opens toward the trailing edge. Preserve the existing mobile bottom-sheet treatment.
### Reload reattachment (verification, likely no behavior change)
- The reattach path already exists (stable `tabId` → `managerKey`, reconcile trusts backend
`running`). With sessions no longer reaped, confirm no additional frontend change is needed for
reload reattachment; only add regression coverage. If a residual client-side path still starts a
fresh shell for a `running` restored descriptor, fix it in the terminal tab view / reconcile so a
restored live descriptor only attaches by `sessionId`.
## Tests
- **What:** host-shell sessions are not reaped by idle or hard timeout, while agent-login sessions
still are; `StopAll` stops all live sessions and is idempotent; natural exit and external stop
still clean up manager maps and fire `onExit` under the no-timeout policy.
**Files:** `apps/backend/internal/agent/loginpty/manager_test.go`.
**How:** `testing/synctest` to advance fake time past 10m/30m and assert a host-shell session is
still running while an agent-login session has exited; direct `StopAll` assertions.
- **What:** `reconcileTab` keeps a still-running host-shell session as `running` with its
`sessionId` after simulated long idle (no reaping), and only `markUnavailable` when the manager
truly has no entry.
**Files:** `apps/backend/internal/quickterminal/service_test.go`.
**How:** table-driven service tests against a manager holding a live long-idle session and one
with no entry.
- **What:** graceful-shutdown cleanup invokes `loginMgr.StopAll()`.
**Files:** the relevant `apps/backend/internal/backendapp/*_test.go` for cleanup wiring.
**How:** assert the registered cleanup stops a seeded live session.
- **What:** the add menu renders with start alignment and existing items.
**Files:** an existing `apps/web/components/quick-chat/*` test (extend, do not add a new file
unless none covers this component).
**How:** assert the `DropdownMenuContent` alignment prop / rendered side and the two menu items.
## E2E Tests
- **Scenario:** GIVEN a running quick terminal left idle past the old 10m idle window (fast-forward
or a shortened test policy hook), WHEN the user reloads and reopens Quick Chat, THEN the same tab
and sequence reattach to the same PTY without a new numbered terminal.
**File:** `apps/web/e2e/tests/terminal/quick-terminal.spec.ts` (extend the existing reattach spec).
**What to verify:** single tab, unchanged sequence/label, same-session marker output, and no
second shell. Close every surviving terminal in `finally`.
- **Scenario:** GIVEN the plus menu on a desktop pointer viewport, WHEN it opens, THEN it opens
toward the trailing edge and stays within the viewport.
**File:** `apps/web/e2e/tests/terminal/quick-terminal.spec.ts` or the existing quick-chat menu
spec.
**What to verify:** menu bounding box is to the right of the trigger and within the viewport.
## Verification Results
_To be filled in during implementation._
## Implementation Waves And Parallel Candidates
Wave 1 (parallel-safe, independent surfaces):
- [ ] [Task 01: Per-session lifetime policy and StopAll in loginpty](task-01-loginpty-lifetime-policy.md)
- [ ] [Task 02: Fix add-menu alignment](task-02-add-menu-alignment.md)
Wave 2 (depends on Task 01):
- [ ] [Task 03: Shutdown wiring, reconcile coverage, and reload E2E](task-03-shutdown-and-reattach-verification.md)
Task 02 is fully independent of the backend tasks and can land in parallel. Task 03 depends on the
Task 01 policy/`StopAll` surface.
## Risks
- Removing timeouts means a runaway or forgotten shell can live for the entire backend uptime.
Mitigation: explicit tab close already stops the PTY, natural exit is reported, and `StopAll`
reaps everything on shutdown. This matches the user's explicit request and stays bounded by
process lifetime.
- The lifetime policy must not weaken agent-login OAuth reaping. Keep the policy keyed strictly to
`HostShellAgentID` and assert the agent-login path still times out.
- `supervise` cleanup correctness (map removal, `onExit`) must hold when the idle timer and timeout
context are absent. Cover natural exit and external stop under the no-timeout policy.
- E2E time-advancement for a 10m idle window is expensive; prefer a test-only shortened policy hook
or fake-clock injection rather than a real 10-minute wait.