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

3.5 KiB

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: 8062b45103
  • 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.