# 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: 7f0e9310a7f394249fab3cadc5c82d70f91cbfeb
- 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.