fix: harden reconnect for ACP chat and terminal sessions

[raphaeltm]

Summary

• Fix reconnect reliability for both ACP chat sessions and terminal sessions (single and multi-terminal) by resolving fresh tokenized WebSocket URLs during reconnect instead of reusing stale URLs.
• Harden VM-agent ACP prompt lifecycle to prevent permanently stuck prompting states: add prompt timeout, cancel grace fallback force-stop, and stronger replay/control-state convergence.
• Add targeted tests for reconnect URL resolution, replay prompt-done race handling, and SessionHost force-stop/priority delivery behavior.
• Sync docs for new VM-agent env vars and append detailed implementation research to the task file.

Validation

• pnpm lint
• pnpm typecheck
• pnpm test
• Additional validation run (if applicable)
• Mobile and desktop verification notes added for UI changes

Additional validation executed locally:

• go test ./internal/acp
• pnpm --filter @simple-agent-manager/acp-client test
• pnpm --filter @simple-agent-manager/terminal test
• pnpm --filter @simple-agent-manager/acp-client typecheck
• pnpm --filter @simple-agent-manager/terminal typecheck
• pnpm --filter @simple-agent-manager/web typecheck

Mobile/desktop note:

• UI changes are connection-behavior/token-refresh plumbing only; no layout/styling changes were introduced.

UI Compliance Checklist (Required for UI changes)

• Mobile-first layout verified
• Accessibility checks completed
• Shared UI components used or exception documented

Exceptions (If any)

• Scope: N/A
• Rationale: N/A
• Expiration: N/A

Agent Preflight (Required)

• Preflight completed before code changes

Classification

• external-api-change
• cross-component-change
• business-logic-change
• public-surface-change
• docs-sync-change
• security-sensitive-change
• ui-change
• infra-change

External References

N/A: no external third-party API contract changes were made; work was based on in-repo architecture/spec/docs and existing implementation.

Codebase Impact Analysis

Changed code paths span multiple components:

• packages/vm-agent/internal/acp/* (prompt timeout/force-stop, control/replay delivery behavior)
• packages/vm-agent/internal/config/config.go and packages/vm-agent/internal/server/server.go (new ACP prompt env wiring)
• packages/acp-client/src/hooks/useAcpSession.ts (resolver-based reconnect + replay race handling)
• packages/terminal/src/* (resolver-based reconnect for terminal sockets)
• apps/web/src/components/ChatSession.tsx and apps/web/src/pages/Workspace.tsx (fresh tokenized URL resolution for chat + terminal reconnect)
• packages/acp-client/src/hooks/useAcpSession.test.ts, packages/terminal/src/*.test.tsx, packages/vm-agent/internal/acp/session_host_test.go (coverage for changed behavior)

Documentation & Specs

Updated documentation/spec artifacts in the same change:

• AGENTS.md
• CLAUDE.md
• tasks/backlog/2026-02-17-acp-session-stuck-after-reconnect.md

Constitution & Risk Check

Validated against .specify/memory/constitution.md, especially Principle XI (No Hardcoded Values):

• Added prompt timeout and cancel grace as configurable env vars (ACP_PROMPT_TIMEOUT, ACP_PROMPT_CANCEL_GRACE_PERIOD) with defaults.
• No hardcoded production URLs were introduced; reconnect URLs are derived from workspace host plus refreshed token.
• Main tradeoff: forced prompt-stop on timeout/cancel-grace can terminate an in-flight agent process, but this is intentional fail-safe behavior to avoid unrecoverable stuck sessions.