docs: plan for #305 — workbench idle session auto-suspend behavior

[posit-vip-triage]

Plan for issue #305: workbench idle session auto-suspend behavior

This PR revises the generated plan with two critical design fixes applied on top of the #349/#336 merges.

What the plan proposes

• New [workbench] idle_timeout_minutes and idle_grace_seconds TOML fields in WorkbenchConfig (alongside job_timeout and test_packages, not after kubernetes)
• Two new scenarios in src/vip_tests/workbench/test_session_idle.feature tagged @workbench @performance:
  • Idle session auto-suspends after the configured timeout — waits for Suspended state with a configurable grace window (idle_grace_seconds, default 60 s)
  • Active session is not suspended while work is running — drives the session with periodic activity, then asserts still Active

Design: periodic activity loop (not a blocking Sys.sleep)

The active-session scenario keeps the session alive by sending periodic interactive input events via rstudio_eval every 90 seconds across the idle-timeout window — not a single blocking Sys.sleep spanning the whole window. A console blocked in Sys.sleep is R being busy, not a session registering user activity; Workbench's idle timeout is driven by interactive input events. The loop:

POLL_INTERVAL_S = 90
end_time = time.monotonic() + (idle_timeout_minutes * 60) + idle_grace_seconds
while time.monotonic() < end_time:
    rstudio_eval(page, "invisible(NULL)", timeout=15_000)
    remaining = end_time - time.monotonic()
    if remaining > 0:
        time.sleep(min(POLL_INTERVAL_S, remaining))

Each rstudio_eval call types a trivial expression into the RStudio console, emitting a real input event that resets the idle clock — faithful to "activity correctly resets the idle clock" from the issue.

Configurable grace window

The grace window added on top of idle_timeout_minutes is exposed as idle_grace_seconds: int = 60 in WorkbenchConfig. Deployments with high clock drift or slow suspend response can increase this value in vip.toml. The vip.toml.example documents both fields:

idle_timeout_minutes = 5   # must be ≤ 15 for the idle scenarios to run
idle_grace_seconds = 60    # seconds added on top of idle_timeout_minutes before asserting suspend

Runtime ceiling: 15 minutes

These scenarios are only viable against deployments configured with a short idle timeout. The implementation skips (with a clear message) when idle_timeout_minutes > 15:

MAX_VIABLE_IDLE_TIMEOUT_MINUTES = 15

if timeout > MAX_VIABLE_IDLE_TIMEOUT_MINUTES:
    pytest.skip(
        f"idle_timeout_minutes={timeout} exceeds the test ceiling of "
        f"{MAX_VIABLE_IDLE_TIMEOUT_MINUTES} min — configure the deployment "
        "with a shorter timeout to run these scenarios"
    )

The vip.toml.example will use idle_timeout_minutes = 5 (not 120) and note the ceiling. A 120-minute example value would imply a 2+ hour test run, which is not viable.

Note on TERMINAL_SESSION_FAILURE_STATES

TERMINAL_SESSION_FAILURE_STATES in src/vip_tests/workbench/conftest.py:39 contains only ("Failed",) — "Suspended" is intentionally absent, so PR #320's fail-fast logic will not false-fail the idle scenario when the session legitimately reaches Suspended state.

---

Implements plan for #305

[github-actions]

Preview Links

Website	Validation Report
https://posit-dev.github.io/vip/pr-preview-site/pr-315/	https://posit-dev.github.io/vip/pr-preview/pr-315/

[ian-flores]

@copilot configurable

[Copilot]

Done — the grace window is now a configurable idle_grace_seconds: int = 60 field in WorkbenchConfig (alongside idle_timeout_minutes). The plan has been updated throughout: config wiring, fixture snippet, activity loop, vip.toml.example docs, and verification selftest list. The open question is resolved. Commit: docs: make idle grace window configurable via idle_grace_seconds field.