fix(email-agent): make undo window configurable for chat-speed bulk ops

[github-actions]

The bulk-archive undo window was 30s — calibrated for an instant UI button — but a chat-mediated multi-item archive runs through the LLM tool-loop and can take longer than that on a local model, so the "undo within the window" offer was already stale by the time the user could act. The default is now 120s (still overridable via GAIA_EMAIL_UNDO_WINDOW_SECONDS), applied consistently across the tools — the prior autofix only touched config.py and left hardcoded getattr(..., 30) fallbacks in the archive / organize / phishing tools plus the generated openapi.email.json / specification.html, which this syncs.

Test plan

• Unit — test_undo_window_config_2447.py → 6 passed; rest-contract asserts undo_window_seconds == 120
• Real-world, macOS — bulk-archived 3 messages via the real chat tool-loop (real Metal inference), then undo_archive_batch restored all 3 to INBOX; undo_window_seconds=120 confirmed. (The Mac's fast GPU kept the archive under 30s, so the original >30s failure wasn't reproduced live; 120s comfortably covers a >4× slower run.)
• Agent UI — not captured: the email sidecar exposes no REST-injectable no-OAuth mailbox seam (FakeGmailBackend is a Python-construction seam only) and live OAuth is non-interactive on the keychain-locked box. Follow-up: expose the fake-backend seam via an env hook for no-OAuth UI regression.

Closes #2447

[github-actions]

Verdict: Request changes — the code change is correct and well-tested, but the "raise the default to 120s" sweep is incomplete, so the package would ship docs that contradict themselves.

This PR raises the email agent's undo window default from 30s to 120s (still overridable via GAIA_EMAIL_UNDO_WINDOW_SECONDS, with a fail-loud error on a bad value) so a slow chat-mediated bulk archive stays undoable after it finishes. The config change, validation, and tests are solid.

Two things to fix before merge:

1. Stale "30s" undo-window text left behind in several docs. The sweep updated the endpoint blocks but missed the summary paragraphs and the npm-side integrator docs. The result is that the same shipped spec file states both "reversible for 120s" and "reversible within a 30-second undo window", and the npm SPEC.md / SKILL.md still tell integrators the window is 30s. Per GAIA's doc-sync rule a behavior change must update every doc that describes it — please finish the sweep and regenerate the rendered spec.
2. The PR description contradicts the diff. The visible description says "The 30s default is unchanged (no doc/contract churn)" and the technical notes argue against bumping the default — but the code does raise it to 120s and does churn the contract surfaces (matching the CHANGELOG entry). Update the description so the merge record matches what shipped.

Real-world evidence

evidence-bundle.md is present and shows real, non-inference execution (not fabricated): a live FastAPI TestClient against the actual gaia_agent_email app returned undo_window_seconds: 120 in the archive response body; direct env resolution confirmed override (=45 → 45), default (unset → 120), and fail-loud (=notanumber → ConfigurationError); and pytest ran green — 115 passed (contract + new config suite) and 34 passed (openapi conformance). This confirms the code behaves as intended, so my verdict rests entirely on the doc-sync gap, not on the runtime behavior. Screenshot is N/A — this is a backend config default with no rendered-pixel change; the underlying-route evidence the CI lane can produce is present.

🔍 Technical details

Issues

🟡 Incomplete doc-sync — stale "30s" undo-window claims (multiple files)

The default-change sweep updated the endpoint descriptions but missed these, leaving contradictory undo-window durations in shipped docs:

• spec_html.py:916 — summary paragraph still reads "reversible within a 30-second undo window", while the endpoint blocks in the same render now say 120s. Because specification.html is a pure render of this function (guarded by tests/test_spec_html_artifact.py), specification.html:226 inherits the stale text and the drift test still passes (both are stale together) — so CI won't catch it.

    <code>/v1/email/send</code>. Both are reversible within a 120-second undo window via
  

  After editing, regenerate the artifact: python -m gaia_agent_email.spec_html.

• hub/agents/email/npm/SPEC.md:245 — "Both are reversible inside the 30s undo window:"

• hub/agents/email/npm/SKILL.md:108, 110, 125, 363 — "within the 30s window" / "within 30s"

CHANGELOG.md:137 (npm) — the "reversible within 30 seconds" line is a historical past-version entry describing when the capability shipped; leave it as-is (rewriting history would be wrong). GAIA's hub doc-sync rule (README/SPEC/SKILL/CHANGELOG must move together) is exactly the surface at risk here.

🟡 PR description describes an abandoned approach. The visible body ("30s default is unchanged") and the technical-details section ("Why not just bump the default?") describe a keep-30s-add-override design, but the diff raises the default to 120s across the contract surfaces and the CHANGELOG entry is titled "Undo window default raised to 120s". Please align the description with the shipped change so the squash-merge record is accurate.

🟢 Weak override test (tests/test_undo_window_config_2447.py:29) — test_env_override_raises_window sets GAIA_EMAIL_UNDO_WINDOW_SECONDS=120 and asserts 120, which equals the default, so it can't distinguish "override honored" from "override ignored". Use a non-default value (the evidence bundle used 45):

def test_env_override_raises_window(monkeypatch):
  monkeypatch.setenv("GAIA_EMAIL_UNDO_WINDOW_SECONDS", "45")
  assert default_undo_window_seconds() == 45
  assert EmailAgentConfig().undo_window_seconds == 45

Strengths

• Fail-loud config — default_undo_window_seconds() (config.py:66) raises an actionable ConfigurationError on a malformed/non-positive override instead of silently defaulting, matching the No-Silent-Fallbacks rule; the validate() guard mirrors the existing followup_window_days pattern.
• Single source of truth — routing the default through field(default_factory=...) means the override flows to both the chat-tool path and the REST _undo_window_seconds() path with no duplication.
• Good test + evidence coverage — unset/override/blank/non-integer/non-positive/validate cases plus a real end-to-end HTTP response in the evidence bundle.

[github-actions]

🟡 One stale "30-second" claim slipped through in the mailbox-actions section intro of the contract spec — the endpoint blocks now say 120s, but the lead paragraph still says 30s, so the spec contradicts itself.

🔍 Technical details

hub/agents/email/python/gaia_agent_email/spec_html.py:916 — the <p> intro for the "Mailbox actions — archive & quarantine" section:

Both are reversible within a 30-second undo window via

This template string was not updated in this PR. Because specification.html is generated from spec_html.py, the rendered spec at specification.html:226 carries the same stale claim. The individual archive_block and quarantine_block descriptions (lines 620/646 in spec_html.py) were updated correctly, leaving the section header/intro inconsistent with them.

Fix: change a 30-second undo window → a 120-second undo window in spec_html.py and regenerate specification.html.