docs: integrate session settlement recovery

.project-docs/30-worklog/current-state.md

@@ -4,6 +4,16 @@ This file is the integrated default-branch snapshot. Feature tasks record progre
 
 ## Integrated Through
 
+- Coding terminal-settlement source `f1fd13a` from task
+  `20260901-fix-session-settlement-a47d2e91` is integrated through merge
+  `e76a1e1` by task `20260902-integrate-session-settlement-6e41c8b2`.
+  Normal prompt completion still uses authoritative `agent_settled`; when that
+  handshake is missing after Pi has terminalized, Main probes only the accepted
+  target thread after a bounded 30-second grace period. Exact idle evidence
+  hydrates the persisted final assistant response and releases ownership once;
+  contradictory state becomes an explicit target-only protocol failure. Accepted
+  or uncertain mutations are never replayed, and sibling Conversations remain
+  available.
 - Plugin-navigation sources `b3f4166` and `e237941` from task
   `20260831-consolidate-plugin-navigation-3d9a6c71` are integrated through
   merge `a278ca3`. Coding history/quota source `d523b72` from task
@@ -241,6 +251,12 @@ Robot 绑定设备默认先显示“引导配网 / 已有激活码”路径选
 
 ## Recently Completed
 
+- 2026-09-02: Integrated bounded recovery for a missing Pi prompt settlement.
+  A final persisted assistant response can no longer leave the Composer permanently
+  processing merely because `agent_settled` was lost: Main waits for the normal
+  handshake, then uses exact target-thread idle evidence to hydrate and settle once,
+  or emits a safe target-only protocol failure. Focused runtime/process tests,
+  typecheck, and the Vite/Electron production build passed on the integrated tree.
 - 2026-09-01: Integrated the consolidated Plugin Services navigation, complete
   active-branch Coding history with scroll-anchor preservation, narrow Token Point
   quota feedback, and stable first-line process previews. Combined typecheck,
@@ -330,4 +346,4 @@ Robot 绑定设备默认先显示“引导配网 / 已有激活码”路径选
 
 ## Last Updated
 
-2026-09-01
+2026-09-02

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

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

.project-docs/30-worklog/tasks/20260902-integrate-session-settlement-6e41c8b2.md

@@ -0,0 +1,74 @@
+# Task: Integrate stuck session settlement fix
+
+## Identity
+
+- Task ID: 20260902-integrate-session-settlement-6e41c8b2
+- Mode: Integration
+- Branch: main
+- Worktree: /Users/inmanx/Documents/makelore
+- Base commit: dedbc85014e0c7e656464c9b3af26f9f4882bd04
+- Owner: codex
+- Status: Completed
+
+## Scope
+
+- Integrate source commit `f1fd13a` from task
+  `20260901-fix-session-settlement-a47d2e91` into local `main`.
+- Promote the verified missing-settlement recovery behavior into the integrated
+  project snapshot without changing the accepted ADR-006 runtime boundary.
+- Re-run focused runtime tests, typecheck, and the Renderer/Main/Preload build on
+  the integrated tree, then confirm the development desktop process reloads.
+
+## Intent And Constraints
+
+- Preserve normal `agent_settled` authority, per-Conversation generation isolation,
+  exactly-once ownership cleanup, and sibling availability.
+- Do not replay an accepted or uncertain Coding mutation and do not settle an
+  ordinary prompt solely because `message_end` was observed.
+- Permit bounded fallback completion only from exact target-thread idle evidence;
+  contradictory terminal state must converge to a target-only protocol failure.
+- Keep Pi wire/runtime state private to Electron Main and make no unrelated product,
+  protocol, authentication, provider, or project-data change.
+
+## Outcome
+
+- Committed the completed read-only live-stall diagnosis on `main` as `dedbc85`
+  and released its prior feature-task ownership cleanly.
+- Merged source fix `f1fd13a` into `main` without conflicts as merge `e76a1e1`.
+- Kept the source task record read-only on its feature branch; `main` contains the
+  integration task record and canonical promoted facts rather than a mutable copy
+  of another task's owned record.
+- Promoted the bounded missing-settlement recovery into `current-state.md`, the
+  evidence index, and `README.md`; ADR-006 remains unchanged because the fix
+  restores its existing authority, isolation, and no-replay contract.
+- Restarted the development desktop application from the integrated tree. The
+  new Electron Main process is listening on the Host API and the Renderer returns
+  HTTP 200 with the settlement-probe implementation present in the built bundle.
+
+## Verification
+
+- Source task evidence: 68 focused tests passed across 8 files; 1,732 full unit
+  tests passed and 3 skipped; typecheck, targeted/full lint, Vite build, and
+  `git diff --check` passed.
+- Integrated tree: `vitest run tests/unit/pi-worker-pool.test.ts
+  tests/unit/pi-agent-server-process-real.test.ts --maxWorkers=2` passed 26 tests
+  across 2 files.
+- Integrated tree: `pnpm run typecheck` passed.
+- Integrated tree: `pnpm run build:vite` passed for Renderer, Main, Preload, and
+  utility bundles; only pre-existing Browserslist/import/chunk-size warnings
+  remained.
+- Restart smoke: Renderer `http://localhost:5173/` returned HTTP 200; Electron
+  process `87870` listens on `127.0.0.1:13210`; the built Main bundle contains the
+  settlement-probe implementation.
+- `check_project_docs.py`, task-aware `check_doc_drift.py`, `git diff --check`,
+  and the final Git cleanliness check passed.
+
+## Follow-ups
+
+- No additional code follow-up is required for this local integration. A future
+  packaged release should retain the existing Pi final-artifact and cross-platform
+  release gates.
+
+## Promotion Candidates
+
+- None recorded.

.project-docs/50-evidence/evidence-index.md

@@ -4,6 +4,7 @@ Use this index for searchable, traceable evidence records.
 
 | Date | Topic | Status | Source | Detail |
 |---|---|---|---|---|
+| 2026-09-02 | Makelore Code missing terminal-settlement recovery | Integrated locally; live pre-fix stall diagnosed and automated regression coverage passed | Source `f1fd13a`, merge `e76a1e1`, source task `20260901-fix-session-settlement-a47d2e91`, integration task `20260902-integrate-session-settlement-6e41c8b2` | Live evidence showed Pi had persisted its final assistant response while Main retained run ownership because no effective `agent_settled` arrived. The fix preserves normal settlement authority and no-replay semantics, reports post-accept prompt rejection, and after a bounded grace period probes only the target thread: exact idle evidence hydrates and settles once; contradictory state fails that target explicitly. The source passed 68 focused tests, 1,732 full tests / 3 skipped, typecheck, lint, and Vite build; the integrated tree repeated focused runtime/process tests, typecheck, and Vite build. |
 | 2026-08-30 | MakeLore AI Design Living Form V2 hard cutover | Integrated locally with matching server source; production data cutover and Provider activation pending | Client source `b0b5a602b501308a23eb27e2f51a5169b9e46b1e`, server source `b5351d54f595ce8eb873593e462e4a556bea0b05`, integration task `20260830-integrate-marketplace-design-client-main-9d5f3b82`, ADR-007 | Replaces nested V1 Conversations, Briefs, editable provider Prompt, mutable Quote PATCH, and local semantic fallback with one current Direction, one Living Form/Specification authority, stable operations, immutable Quote confirmation, and Main-owned V2 transport. Client source passed typecheck, lint with zero errors, 1,425 unit tests, Vite/Electron build, and 2 Electron E2E tests. Server source passed 2,626 tests / 31 skipped under UTF-8 mode. No production database cutover, real paid Provider request, deployment, or publication occurred. |
 | 2026-08-30 | MakeLore curated Plugin Marketplace Release A | Integrated locally; XMA-01 live acceptance PASS; production trust activation HOLD | Source `40df677a31ff7651f962151eb84b925987781c03`, source task `20260828-plugin-marketplace-client-5f8b3d72`, integration task `20260830-integrate-plugin-marketplace-client-6e3b9d82` | R7 Standards/Spec passed with zero findings. XMA-01 passed 12/12 using real PostgreSQL, signed-in packaged MakeLore, Operations-published temporary-key packages, A/B account isolation, immutable install/update/freeze/rollback, project/Agent/Pi materialization, lifecycle invalidation, pricing-only ETag change, Data Service 10 tools/14 operations and zero Token Point transactions. Final Windows installer was 208,235,670 bytes with SHA-256 `738A2F6573C502281787F418EA666C6E62C287CA0EC13C6EB22369DAB0B3FFFA`. The official Ed25519 public key was not supplied, so the production trust store correctly remains fail closed; no deployment or production publication occurred. |
 | 2026-08-26 | Makelore Code Pi hard cutover、后台运行 ownership 与 Works user-context Provider 修复 | 本地 `main` 已集成；Windows 最终安装包与 packaged proof Pass；真实 Provider/macOS/native Linux 非 Pass | 集成交付 `48a9189`、实现 `a098266`、任务 `20260826-fix-pi-model-provider-8d4c2a71` / `20260826-integrate-pi-provider-fix-6e4c2a91`、`docs/pi-runtime-release-runbook.md` | OpenCode production runtime/package/plugin/fallback 已删除，Pi `0.84.2` 是唯一 runtime。未解析 Conversation 现在 validate→persist resolved model→prepare；exact Works `works square AI gateway did not return one-api user context` 会失效缓存 credential、以非重试 Provider-auth failure 结束且不自动 replay，`agent_end willRetry:false` 不再被 `agent_settled` 覆盖成 completed。聚焦 47/47、related 54/54、projector 12/12、181 files / 1541 full unit + pressure、typecheck、lint、Vite build、Windows Electron 4/4、publish/runtime/artifact/Pi/subagent/final packaged proof 通过。NSIS 208,162,564 bytes，SHA-256 `A02F79FCD3273FB0B013450492DC788B6E5ED7BBC1007468FB83BE949B8CB30D`，未签名；final app.asar SHA-256 `A8394D0F7324B27D2C95469ABD4E2A39C739EABCC6D8B41E1D65BA4B41FB9D39`。真实 Provider 是 Explicitly Waived / Accepted Risk 且 `realTurnVerified=false`；macOS x64/arm64 与 native non-WSL Linux 未验收。 |

README.md

@@ -133,7 +133,7 @@ Pi 正式包必须继续运行 `pnpm run verify:artifact:pi`、`pnpm run smoke:p
 - Composer 使用贴底的复合输入面板，支持文字、登录后的语音转写，以及粘贴或选择 PNG/JPEG/WebP/GIF 图片；每条消息最多 16 张图片、最多并行上传 4 张。语音录制通过现有 Main-owned Works Speech Host API 转成文字，并在项目或账号切换时立即停止；当前对话的模型与思考强度组合入口、语音及发送/中止入口保留在底部控制行，模型入口默认使用透明底色。模型与思考强度通过向上展开的分级菜单切换，只列出当前 Provider 或 Makelore 已验证模型档案实际支持的选项；Qwen3.6 Plus 使用混合思考开关，Qwen3.8 Max 暴露低/中/高三档并把产品“高”映射到服务端 `xhigh`。模型仅报告 `off` 时明确显示“不可调”，不伪造未知模型的推理档位。切换完成后静默刷新当前 Snapshot，只有真正恢复 worker 时才显示本地 Agent 重连提示。重复读取 Snapshot 不发布无变化的 worker 状态；Snapshot 与 SSE 批次竞态时，Renderer 会丢弃已覆盖事件并只应用连续的新尾部，避免形成伪重连循环。上下文接近模型限制或发生溢出时由 Pi 自动整理，Composer 不提供手动整理入口；自动整理的进度和结果仍显示在对话过程轨道中。图片在发送前只保留本地预览，点击发送时才经 Main-owned 有界二进制接口上传一次；Main 在落盘前核对 MIME 与最小图片签名，状态与事件只保存 attachment id，时间线按需读取二进制并创建临时 object URL，不保存重复 base64。智能体报告 `changed-file.v1` 后，输入框上方会展示当前轮次的文件数与增删行统计，并可展开查看 Main-owned 变更快照中的逐文件差异。
 - Makelore 在应用侧按 Session 独立提交、跟踪和隔离运行状态，不使用“当前对话正在回复”的全局界面锁；同一 Session 的后续消息仍按顺序排队。最终产品中的 Pi 运行时会通过受控 Provider-shaped 回环 smoke 验证同一 Agent Server 内多个 Conversation 逻辑线程的重叠执行、状态隔离、凭证引用隔离、单线程关闭和 Server 崩溃后重启，以及独立子 Agent 进程的隔离与回收；真实外部 Provider 的并发、限流、协议兼容和凭证隔离仍是独立风险，未执行真实 Provider 验证时不得标记为 Pass。
 - 首次发送会立即生成稳定的乐观用户消息；HTTP 202 只表示本地 Agent 已接收。后续失败不会删除已接受消息，不确定交付不会自动重发；准备失败可在目标 Conversation 上手动恢复。
-- 运行中的 Conversation 可把新消息作为 steer 引导当前回答或 follow-up 排到下一轮，并显示队列位置；队列只在 `agent_settled` 后释放，用户可中止当前运行。select/confirm/input/editor 交互在输入区上方回答，select 除预设选项外支持自由输入；交互提交或取消后立即从输入区移除，失效请求会就地提示并允许重试或取消。
+- 运行中的 Conversation 可把新消息作为 steer 引导当前回答或 follow-up 排到下一轮，并显示队列位置；队列正常在 `agent_settled` 后释放，用户可中止当前运行。若 Pi 已终结但该握手丢失，Main 会在 30 秒宽限后仅探测目标线程：权威 idle 状态会补齐持久化最终回复并 exactly-once 释放 ownership，矛盾状态则显式失败该目标，且不会重放已接受请求。select/confirm/input/editor 交互在输入区上方回答，select 除预设选项外支持自由输入；交互提交或取消后立即从输入区移除，失效请求会就地提示并允许重试或取消。
 - 核心聊天页标题栏左侧只显示 Conversation 名称，必要的中止/恢复入口保留在右侧；不再展示 Pi 空闲/运行副标题。对话列表栏只显示项目名称和项目设置入口，不显示“Pi 本地对话”副标题；全局品牌 Logo 贴齐窗口最右边缘。归档、未读、整段 Conversation 分支和编程工具抽屉均不占用标题栏。从已持久化的 user 消息仍可“从这里创建新对话分支”，assistant 消息和未持久化消息不提供该动作；分支只创建新的 Conversation 历史，不表示文件回滚。Pi 的工具调用与浏览器附件继续在对应的对话过程节点中按需展开；分享、待办、全局运行时和 revert/unrevert 不属于该产品界面。
 
 ## 运行内核与项目数据