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

Status

Accepted and implemented on 2026-08-26.

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

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

4.5 KiB Raw Blame History