fix(coding): serialize agent server sleep restart

.project-docs/30-worklog/tasks/20260901-agent-received-stall-8b6d4c21.md

@@ -0,0 +1,53 @@
+# Task: Diagnose local Agent received-message stall
+
+## Identity
+
+- Task ID: 20260901-agent-received-stall-8b6d4c21
+- Mode: Feature
+- Branch: codex/20260901-agent-received-stall-8b6d4c21-agent-received-stall
+- Worktree: D:\Datas\OthersProjects\makelore-worktrees\agent-received-stall-8b6d4c21
+- Base commit: 850947c092892cb647c4191b6d8bbf37a763e1ad
+- Owner: codex
+- Status: Ready for Integration
+
+## Scope
+
+- Diagnose the installed-app state where a prompt is acknowledged locally but remains optimistic indefinitely.
+- Fix the background-sleep versus Agent Server start race without replaying accepted prompts.
+- Add focused regression coverage for both lifecycle race windows.
+
+## Intent And Constraints
+
+- Preserve the single shared Pi Agent Server and per-conversation logical thread architecture.
+- Background sleep must not stop work that begins while idle worker cleanup is in flight.
+- A start racing an already-started stop must wait for the stop and then create a fresh server process.
+- Do not auto-replay an accepted or uncertain prompt.
+
+## Outcome
+
+- Confirmed installed-state evidence: the accepted UI state was newer than the latest Pi session write, and no Agent Server process remained live, so the prompt had not reached Provider generation.
+- Confirmed regression: `PiAgentServerProcess.start()` returned immediately when the old child still existed during an in-flight stop; after that stop completed, no server remained. The real-process race test failed before the fix and passed afterward.
+- Confirmed regression: composition checked for active work only before asynchronous background cleanup, then stopped the shared Agent Server even when a new run began during cleanup. The composition race test failed before the fix and passed afterward.
+- Fixed both lifecycle windows: background sleep rechecks active work after worker cleanup, and a start racing a stop waits for that stop before creating a fresh server.
+- The installed-app symptom maps directly to these two confirmed races, although the exact renderer/Main interleaving of the reported occurrence was not captured live.
+- Accepted and uncertain prompts are still never auto-replayed.
+
+## Verification
+
+- Installed-state red loop: accepted screenshot timestamp is newer than the latest Pi session write while no Agent Server process is live.
+- Red phase: the two focused race tests both failed against the original implementation.
+- `pnpm exec vitest run tests/unit/pi-agent-server-process-real.test.ts tests/unit/coding-composition-background-sleep.test.ts --maxWorkers=1` — 2 files, 4 tests passed.
+- `pnpm exec vitest run tests/unit/background-lifecycle.test.ts tests/unit/pi-background-lifecycle.test.ts tests/unit/pi-agent-server-process-real.test.ts tests/unit/coding-composition-background-sleep.test.ts --maxWorkers=1` — 4 files, 9 tests passed.
+- `pnpm run typecheck` — passed.
+- `pnpm run lint:check` — passed with 5 pre-existing warnings and no errors.
+- `pnpm test` — 216 files passed; 1,764 tests passed and 2 skipped.
+- `pnpm run build:vite` — Renderer, Main, Preload, and utility production builds passed.
+- Existing Electron E2E fixtures mock prompt acceptance and do not exercise the real Main-owned Agent Server lifecycle; the real-process regression test is the relevant product-path coverage.
+
+## Follow-ups
+
+- Integrate the feature commit into `main`, then produce/reinstall a Windows package before validating the original installed-app reproduction; the currently installed binary does not contain this source fix.
+
+## Promotion Candidates
+
+- None. The change enforces existing background-lease and single-Agent-Server architecture rather than changing canonical product behavior.