# 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.