ADR-006: Makelore Code Uses Pi As Its Sole Runtime

Status

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

The former OpenCode integration coupled Renderer state, a shared runtime lifecycle, provider configuration, and Session-specific wire behavior. Installed users observed multi-minute first-chat waits, worker exits, stuck submitting/compacting states, model-change failures, and Conversation ownership errors. The product decision was an explicit hard cutover to Pi without an OpenCode fallback or compatibility execution layer.

Decision

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, 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 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 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.

Supersedes

The product OpenCode runtime, plugin, package, routes, Renderer store/UI, resource bundle and compatibility execution behavior integrated before the Pi cutover.

Evidence

Pi cutover planning/spec delivery: a8c0806
Runtime qualification through feature UI and hard cutover: 2bc423e through 977445b
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

.project-docs/20-architecture/system-overview.md
.project-docs/20-architecture/module-map.md
.project-docs/20-architecture/data-flow.md
.project-docs/40-domain/business-rules.md
.project-docs/00-brief/success-criteria.md

5.8 KiB Raw Blame History