merge: integrate upstream main with local Makelore changes

.project-docs/10-decisions/adr-006-pi-runtime-hard-cutover.md

@@ -2,7 +2,8 @@
 
 ## Status
 
-Accepted and implemented on 2026-08-26.
+Accepted and implemented on 2026-08-26; amended on 2026-08-31 for the shared
+parent Agent Server topology and `.makelore`-only project ownership.
 
 ## Context
 
@@ -12,18 +13,20 @@ The former OpenCode integration coupled Renderer state, a shared runtime lifecyc
 
 - Pin `@earendil-works/pi-coding-agent` `0.84.2` as the sole Makelore Code production runtime. Do not maintain OpenCode fallback, dual execution, RPC/SDK alternatives, or Renderer access to runtime HTTP/RPC/event types.
 - Use product-owned schema-v2 project, Agent, Conversation, model, Snapshot/Patch, command, interaction, attachment, file and subagent contracts. Pi wire and Provider details remain private to Electron Main.
-- Electron Main owns the single `/api/coding/*` composition, project storage, Provider credentials, managed Prompt/Skill/extension resources, persistent per-Conversation worker/session registry, recovery, event projection, background lifecycle, process budget, subagent scheduler and same-project write lease.
-- Keep one persistent worker/session per active or warm Conversation. Limit top-level running workers to 4, warm idle workers to 4, child concurrency to 4, and all parent/child processes to a shared FIFO budget of 8. A coding child shares its parent's project write lease and cannot recursively dispatch subagents.
+- Electron Main owns the single `/api/coding/*` composition, project storage, Provider credentials, managed Prompt/Skill/extension resources, the persistent per-Conversation logical Runtime/Session registry, the long-lived parent Agent Server, recovery, event projection, background lifecycle, process budget, subagent scheduler and same-project write lease.
+- Run one long-lived parent Pi Agent Server per Coding composition. Each active or warm Conversation receives an isolated logical Runtime, Session, generation, credential store, extension context and JSONL channel inside that process. Limit running parent turns to 4 and warm idle logical threads to 8. An Agent Server exit invalidates every old parent channel and the next recovery starts exactly one replacement Server; it must not exit Electron Main or replay accepted work.
+- Keep child Agents as independent short-lived processes. Limit child concurrency to 4 and retain the FIFO child-process budget of 8; shared parent logical threads do not each consume a process lease. A coding child shares its parent's project write lease and cannot recursively dispatch subagents.
 - Public streaming is Snapshot-first plus bounded `patch-batch` SSE. Generation/sequence recovery is target-only; accepted or uncertain mutations are never replayed automatically.
 - A prompt or compact confirmation timeout preserves target run permit, process ownership and Main background lease until authoritative success, failure, exit or abort converges exactly once. Page hiding cannot stop an active or uncertain run. Pi `0.84.2` manual compact may terminalize through its correlated RPC result because it does not emit `agent_settled`.
-- A new unresolved Conversation validates and persists its resolved model before first worker prepare. Same-account model changes may use target `set_model`; cross-account changes rebuild only the target worker after an active run settles.
-- Provider secrets enter only the selected worker environment. The deterministic Works missing user-context response expires the cached gateway credential, fails without replay and projects as a fixed Provider-auth error; it is not a Pi crash.
-- Back up v1 metadata and old OpenCode sessions during migration but do not continue them. Remove only exact generated legacy Agent files; preserve unknown or modified files in the migration backup and leave unrelated `.opencode` content alone.
+- A new unresolved Conversation validates and persists its resolved model before first logical-thread prepare. Same-account model changes may use target `set_model`; cross-account changes rebuild only the target logical thread after an active run settles.
+- Parent Provider secrets enter only the selected logical thread's in-memory credential store; independently spawned child credentials remain scoped to that child process. Secrets never enter argv, catalogs, Renderer state or sibling threads. The deterministic Works missing user-context response expires the cached gateway credential, fails without replay and projects as a fixed Provider-auth error; it is not a Pi crash.
+- `.makelore/project.json` and `.makelore/conversations.json` are the only project-owned Coding configuration stores. Do not read, migrate or delete project metadata from `.niancode` or `.opencode`; legacy content remains inert and user-owned.
 
 ## Consequences
 
 - Makelore Code has one runtime architecture and one product contract instead of a long-lived compatibility seam.
-- A single Conversation can recover or rebuild without invalidating siblings, while process and write budgets provide bounded real concurrency.
+- A target logical thread can normally recover or rebuild without invalidating siblings. A whole Agent Server exit is deliberately process-wide: all old parent channels fail closed together, then one replacement Server is created on demand while Conversation generations still prevent stale events from returning.
+- Parent process startup and Pi module loading are amortized across Conversation threads, while logical-turn, child-process and write budgets preserve bounded concurrency.
 - Installed-package regressions must be verified against the final `app.asar` and `resources/pi-runtime`, not only workspace tests.
 - Provider-shaped loopback proves serialization and local isolation only. The user explicitly waived real Provider account testing and accepted authentication, endpoint/proxy/rate-limit, protocol variation, real concurrency and credential-isolation risk; `realTurnVerified=false` must remain visible and is not Pass.
 - Windows x64 final-package evidence is available. macOS x64/arm64 and native non-WSL Linux desktop/compositor remain release evidence gaps, so the product is not yet cross-platform release-ready.
@@ -39,6 +42,9 @@ The former OpenCode integration coupled Renderer state, a shared runtime lifecyc
 - Release proof and resilience chain: `a795e0c` through `9f05e2d`
 - Provider-context correction implementation: `a098266`
 - Integrated delivery: `48a9189`
+- Local shared-Agent-Server source snapshot: `33fb31fb285b5cfb00d194a036aaf6e21cf8c5a1`
+- Upstream integration base: `62304dc85b3c1069cd656dfacb61ee820e216fa2`
+- Integration task: `20260831-merge-upstream-main-7c3a91f2`
 - Runtime release runbook: `docs/pi-runtime-release-runbook.md`
 
 ## Related

.project-docs/10-decisions/decision-index.md

@@ -9,7 +9,7 @@
 | ADR-003 | Robot 配网页内扫描并连接 Windows/macOS 热点 | Accepted / implemented with physical release gates pending | 2026-08-16 | Robot Renderer、Host API、Electron Main、Windows WLAN、macOS CoreWLAN/CoreLocation | `adr-003-robot-in-app-hotspot-connection.md` |
 | ADR-004 | Works Square 统一拥有桌面认证生命周期边界 | Accepted / implemented | 2026-08-19 | Renderer、Host API、Electron Main、Works Square auth facade | `adr-004-square-auth-lifecycle-boundary.md` |
 | ADR-005 | Learning 采用运营精选项目目录、直接渲染经校验的 HTTPS README 图片、下载不做大小校验并退役课程运行时 | Accepted / implemented, amended 2026-08-20 | 2026-08-20 | Learning Renderer、Host API、Electron Main、Works Square operations/API | `adr-005-learning-project-catalog.md` |
-| ADR-006 | Makelore Code 以 Pi `0.84.2` 为唯一 runtime，Main 独占 worker/session/provider/lease，产品只暴露 Snapshot/Patch 合同 | Accepted / implemented | 2026-08-26 | Code Renderer、Host API、Electron Main、Pi runtime、Provider/resource、packaging | `adr-006-pi-runtime-hard-cutover.md` |
+| ADR-006 | Makelore Code 以 Pi `0.84.2` 为唯一 runtime，父 Conversation 复用一个 Main-owned Agent Server 并隔离逻辑 Runtime/Session/provider/lease，产品只暴露 Snapshot/Patch 合同 | Accepted / implemented, amended 2026-08-31 | 2026-08-26 | Code Renderer、Host API、Electron Main、Pi runtime、Provider/resource、packaging | `adr-006-pi-runtime-hard-cutover.md` |
 
 ## Superseded Decisions