fix(coding): bound missing Pi settlement

.project-docs/30-worklog/tasks/20260901-fix-session-settlement-a47d2e91.md

@@ -0,0 +1,72 @@
+# 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.