makelore/.project-docs/30-worklog/tasks/20260901-local-runtime-unavailable-8b42c7f1.md

Task: Diagnose local programming runtime unavailable

Identity

• Task ID: 20260901-local-runtime-unavailable-8b42c7f1
• Mode: Feature
• Branch: codex/20260901-local-runtime-unavailable-8b42c7f1-local-runtime-unavailable-8b42c7f1
• Worktree: D:\Datas\OthersProjects\makelore-worktrees\local-runtime-unavailable-8b42c7f1
• Base commit: 7f0e9310a7
• Owner: codex
• Status: Ready for Integration

Scope

• Reproduce the current Makelore Code state that renders 本地编程运行时暂时不可用。 and identify the first failing Renderer, Host API, Pi runtime, packaging, or Provider boundary.
• Build a deterministic, agent-runnable feedback loop for the exact visible symptom before ranking or testing root-cause hypotheses.
• Correlate current source and focused tests with privacy-safe local runtime evidence where available.
• Implement the user-authorized minimal product fix for the confirmed packaged-layout Pi AI ESM resolution failure.
• Add a focused regression at the installed sibling-resource-layout seam, then verify the original process path plus the repository's required checks.

Intent And Constraints

• Treat the visible sentence as a generic safe projection, not as proof of a Pi process failure.
• Preserve ADR-006: Pi 0.84.2 remains the sole production runtime; do not add an OpenCode fallback, dual runtime, compatibility layer, or automatic replay.
• Keep Renderer access behind /api/coding/*; runtime, Provider credentials, recovery, and raw diagnostics remain Electron Main-owned.
• Redact credentials, headers, prompts, session content, account identifiers, and complete user project paths from reported evidence.
• Distinguish confirmed facts, evidence-supported inferences, and unverified assumptions. The historical Host-token startup defect is a regression lead, not an assumed cause.
• Keep package resolution anchored to the explicit Main-owned runtimeRoot; development and packaged layouts must both continue to work without hard-coded layout branches or a compatibility layer.
• Work only in this isolated task worktree and do not modify peer worktrees or the occupied local main worktree.

Outcome

• Confirmed that the installed Makelore application reaches the generic CODING_RUNTIME_UNAVAILABLE projection only after the Pi worker fails during open.
• The installed Agent Server imports @earendil-works/pi-ai with import.meta.resolve(specifier, runtimePackageUrl). In the embedded Node.js v24.18.1 process, the second parentURL argument is not honored unless --experimental-import-meta-resolve is enabled, so resolution starts beside resources/resources/pi-agent-server.mjs instead of the sibling resources/pi-runtime/node_modules tree.
• The dependency is present and healthy: the installed Agent Server matches repository source byte-for-byte, both @earendil-works/pi-coding-agent and @earendil-works/pi-ai are version 0.84.2, and the expected ESM export exists.
• Reproduced the installed startup failure twice with the exact executable, script, runtime root, working directory, and environment shape. Both attempts exited with code 1 and ERR_MODULE_NOT_FOUND before producing protocol output.
• A one-variable differential adding --experimental-import-meta-resolve made the same process exit cleanly without the module error. Importing the verified absolute pi-runtime/node_modules/@earendil-works/pi-ai/dist/index.js URL also succeeded without the experimental flag.
• Added --experimental-import-meta-resolve only to the Main-owned Agent Server child process. This activates the existing runtimePackageUrl parent argument and preserves standard ESM package resolution across both the development layout and packaged pi-runtime closure.
• Added a real-process regression that places pi-agent-server.mjs under the installed resources/resources sibling layout, exposes the real Pi runtime and Pi AI package through a temporary production-shaped root, and starts it with the project's Electron executable.
• The regression failed before the fix with the same ERR_MODULE_NOT_FOUND / PI_RPC_EXITED chain and passed after the fix. No runtime bundle layout, dependency version, Provider behavior, Renderer contract, installed application file, user data, or peer task content was changed.

Verification

• Current startup-log signal loop: found the missing @earendil-works/pi-ai module plus two PI_WORKER_STOPPED / open_failure events; verdict RED as expected for the reported failure.
• Exact installed-process loop: two independent launches reproduced ExitCode=1, ModuleNotFound=true, MissingPiAi=true, and zero protocol bytes within five seconds.
• Resolver differential: the same installed process with only --experimental-import-meta-resolve added produced no resolver error.
• Absolute-path differential: importing the fixed runtime-root ESM entry through pathToFileURL(...) succeeded in the same embedded Node.js process without the experimental flag.
• Artifact comparison: installed pi-agent-server.mjs equals repository source; installed Pi package versions and exports match the expected 0.84.2 runtime closure.
• The existing real-process unit test was inspected and does not cover this boundary because it runs the server from the repository layout, where ancestor lookup can reach the root node_modules; the installed sibling resources/resources and resources/pi-runtime layout is not exercised.
• Red regression: pnpm exec vitest run tests/unit/pi-agent-server-process-real.test.ts -t "boots from the packaged sibling resource layout" --maxWorkers=1 failed at pi-agent-server.mjs:22 with ERR_MODULE_NOT_FOUND and PI_RPC_EXITED before the product change.
• Green regression: the same command passed against Electron Node after the Agent Server launch flag was added.
• Focused verification: 4 relevant test files, 24 tests passed, covering Agent Server behavior, composition paths, Pi runtime bundling, and product artifact rules.
• Existing real-process behavior: both tests in pi-agent-server-process-real.test.ts passed, including two logical Conversation threads, process reuse, invalidation, and restart.
• Full unit suite: 215 test files passed; 1,761 tests passed and 2 existing conditional tests were skipped.
• pnpm run typecheck: passed. Final changed-file ESLint: passed.
• pnpm run lint:check: passed with 0 errors and 5 pre-existing unrelated React warnings.
• pnpm run build:vite: passed for Renderer, Electron Main, Preload, and utility worker; only existing bundle/chunk warnings were emitted.
• git diff --check: passed; no debug instrumentation or generated artifact is tracked.

Follow-ups

• The currently installed application predates this source change. After integration, rebuild the Windows artifact, run verify:artifact:win, verify:artifact:pi, and the final packaged Pi proof, then install it before performing the first-conversation UI acceptance.
• When the pinned Electron/Node runtime is upgraded, retain the packaged-layout regression; remove the launch flag only after the new embedded Node accepts the import.meta.resolve parent argument without it.

Promotion Candidates

• Target: current-state and the Pi release evidence index. Proposal: require an Electron Node Agent Server initialization proof from the installed sibling resource layout, not only source-tree process tests. Evidence: the new layout test reproduced the exact installed ERR_MODULE_NOT_FOUND before the fix and passed after enabling the resolver parent URL; 24 focused tests, the full unit suite, typecheck, lint, and production build passed. Future impact: prevents source-root ancestor node_modules from masking final-artifact ESM resolution regressions. Semantic conflicts: none with ADR-006 or the existing Pi closure requirement. Human confirmation: not required to integrate the evidence rule; final package installation/release remains an operator gate.