# Task: Fix stuck Coding session settlement

## Identity

- Task ID: 20260901-fix-session-settlement-a47d2e91
- Mode: Feature
- Branch: codex/20260901-fix-session-settlement-a47d2e91-fix-session-settlement
- Worktree: /Users/inmanx/Documents/makelore-fix-session-settlement-a47d2e91
- Base commit: 8062b45103be45ae036167d3e9890c3ca9ba3e80
- Owner: codex
- Status: Ready for integration

## Scope

- Harden the shared Pi Agent Server/Main terminal handshake so a prompt cannot remain
  visibly processing after Pi has produced its terminal assistant response.
- Preserve authoritative `agent_settled` semantics during normal retries, follow-ups,
  compaction, and queued work; add a bounded, evidence-based terminal fallback only for
  a logically idle target thread.
- Add focused regression coverage for post-accept prompt failure and missing/delayed
  settlement, including exactly-once release of target run ownership.

## Intent And Constraints

- Do not automatically replay any accepted or uncertain Coding mutation.
- Do not settle directly on `message_end`; Pi may still retry, compact, or process a
  queued continuation after that event.
- Keep Pi wire/state Main-private and preserve per-Conversation generation isolation,
  run permits, background leases, and sibling Conversation availability.
- A user-visible wait must end in finite time as completed only when target runtime
  state proves idle; otherwise it must converge to an explicit safe failure.
- Do not touch or terminate the currently running app/processes from the diagnostic
  task while implementing this isolated source fix.

## Outcome

- Confirmed the visible indefinite wait was a missing terminal-handshake failure:
  Pi had already persisted a final assistant message, but Main never received an
  effective `agent_settled`, so run ownership and the processing timer remained live.
- The Agent Server now reports prompt failures that happen after RPC acceptance as a
  private target-thread error instead of swallowing the rejected prompt promise.
- Main now probes only the accepted target thread's authoritative runtime state. Exact
  idle evidence settles a missing handshake and hydrates the persisted final response;
  contradictory terminal state converges to an explicit target-only protocol failure
  after a bounded 30-second grace period.
- Preserved normal `agent_settled` authority, retry/compaction/queued-work semantics,
  exactly-once cleanup, sibling Conversation availability, and the no-replay rule for
  accepted or uncertain mutations.

## Verification

- Focused Pi/runtime unit and real-process integration tests: 68 passed across 8 files.
- Full unit suite: 1,732 passed and 3 skipped (including the pressure project).
- `pnpm run typecheck`: passed.
- Targeted ESLint for all changed source/test files: passed.
- `pnpm run lint:check`: passed with 0 errors and 5 pre-existing unrelated warnings.
- `pnpm run build:vite`: passed for Renderer, Main, Preload, and utility bundles; only
  existing Browserslist/import/chunk-size warnings remained.
- `git diff --check`: passed.
- Electron E2E was not run: the repository has no shared fixture that can inject a
  dropped Pi settlement handshake, and the task intentionally did not stop or restart
  the user's currently running application.

## Follow-ups

- Integrate this feature branch, then restart/rebuild the desktop app so the currently
  running process loads the corrected Agent Server and Main runtime code.

## Promotion Candidates

- None. This restores the existing ADR-006 terminal-settlement contract and does not
  introduce a new product or architecture decision.