wangxuming/makelore
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
08099ea1c2ea24efc10c20f878fc25a557ea9d90
makelore/.project-docs/30-worklog/tasks/20260822-pi-runtime-qualification-c52e8a14.md

11 KiB
Raw Blame History

Task: Implement PI-000 Pi runtime qualification gate

Identity

  • Task ID: 20260822-pi-runtime-qualification-c52e8a14
  • Mode: Feature
  • Branch: codex/20260822-pi-runtime-qualification-c52e8a14-pi-runtime-qualification
  • Worktree: D:\Datas\OthersProjects\makelore-pi-runtime-qualification-c52e8a14
  • Base commit: fba68e86d9
  • Owner: codex
  • Status: Completed — Done with explicit waivers

Scope

  • Implement the PI-000 Runtime qualification gate defined by the accepted Pi runtime cutover specification.
  • Pin the selected Pi runtime package exactly and keep the frozen lockfile reproducible.
  • Add a minimal, standalone RPC qualification probe and focused tests for runtime discovery, JSONL framing, session reopen, abort/settled handling, dependency closure, process cleanup, and measurement reporting.
  • Produce task-scoped evidence for the supported platform/artifact/provider samples that can actually be run from this worktree.
  • Do not change Chat, Host API routes, Renderer behavior, OpenCode migration paths, or final packaged runtime wiring in this task.

Intent And Constraints

  • Candidate runtime: @earendil-works/pi-coding-agent@0.84.2, exact version only. Its npm package, CLI entry, Node engine, upstream tag, and commit must agree before it is accepted.
  • The intended packaged seam is Electron's executable with ELECTRON_RUN_AS_NODE=1 and Pi's RPC CLI; the gate must disprove this seam if packaging, concurrency, provider compatibility, resource discovery, or latency budgets fail.
  • Required protocol coverage is the current four-protocol Makelore contract: openai-completions, openai-responses, anthropic-messages, and openrouter, including base URL, headers, credential injection, model selection, and image-input capability where applicable.
  • Windows/Linux and credential-free samples establish the Phase-0 platform evidence. They do not validate real-provider compatibility, concurrency, abort isolation, credential/model isolation, or image-input behavior; the user explicitly waived those remaining QG-004/QG-005 checks on 2026-08-22 and accepted the resulting risk.
  • The user explicitly waived macOS x64/arm64 from PI-000 on 2026-08-22 and accepted the risk of discovering macOS packaging/native/resource/performance defects later. This is a deferral to PI-150, not a macOS Pass or removal of final cross-platform release validation.
  • The real Provider waiver is not a Pass. Real authentication, endpoint/proxy/rate-limit/provider variation, base URL/header/environment credential/model/image compatibility, true provider concurrency or serialization, and cross-worker abort/event/session/model/credential isolation remain unverified.
  • No OpenCode fallback, compatibility layer, RPC/SDK dual path, speculative migration framework, or unrelated refactor is allowed.
  • If this gate fails, implementation stops at PI-000 and the planner must amend the specification/ADR to the SDK-in-Electron-utility-process alternative.

Outcome

  • Implemented the exact Pi dependency pin, frozen lockfile update, standalone qualification probe, temporary production-closure staging, controlled Electron Builder app.asar probe, real-provider fixture path, four-protocol loopback contract probe, and focused unit coverage.
  • Corrected the controlled packaged-closure inspector before macOS execution: the packaged resource directory is now computed once and passed into the artifact process, so a macOS executable reads Contents/Resources/app.asar instead of the invalid Contents/MacOS/resources/app.asar path.
  • Windows x64 and WSL2 Ubuntu 24.04 Linux x64 workspace, staged, and controlled packaged samples are a partial pass. Runtime identity, JSONL RPC, session persistence/reopen, deterministic failure settlement, local worker isolation, shell abort isolation, complete artifact dependency/resource resolution, startup budgets, RSS reporting, and clean exit were confirmed.
  • Windows and Linux packaged loopback samples passed request/SSE/image/header/credential/model contracts for openai-completions, openai-responses, anthropic-messages, and openrouter, including two-worker overlap and one-worker abort isolation. This is not real Provider Account evidence.
  • The planner audited every PI-000 Required work, Acceptance item, and stop condition after the two user decisions. No unwaived Phase-0 item remains incomplete and no confirmed failure exists, so PI-000 is Done with explicit waivers, not an all-gates Pass. The new Ready Frontier is PI-010, PI-020, and PI-030.

Verification

  • Project-docs preflight and concurrent/planning gates passed in this isolated feature worktree.
  • @earendil-works/pi-coding-agent@0.84.2 npm metadata and upstream v0.84.2 tag both resolve to commit 914cf1472e715297caa30db4b9535d534a9eb718.
  • Electron 43.4.0 runs Node 24.18.1 through ELECTRON_RUN_AS_NODE=1, satisfying Pi's declared Node >=22.19.0 engine floor.
  • pnpm exec vitest run tests/unit/pi-runtime-probe.test.ts: 9 tests passed, including macOS packaged-resource path coverage, aggregate-evidence wording, and explicit real-Provider waiver reporting.
  • pnpm exec eslint scripts/probe-pi-runtime.mjs scripts/probe-pi-packaged-runtime.mjs scripts/probe-pi-provider-contracts.mjs tests/unit/pi-runtime-probe.test.ts: passed.
  • pnpm run typecheck: passed.
  • pnpm run build:vite: passed; existing chunk-size and mixed static/dynamic import warnings remain unchanged and are outside PI-000.
  • node scripts/probe-pi-runtime.mjs --stage --samples 5 --timeout-ms 10000: partial pass on Windows x64. Cold ready p95 681 ms, warm ready p95 674 ms, RSS p95 125780 KiB, exit p95 16 ms; 130 applicable shrinkwrap packages present and 9 platform-specific entries skipped.
  • node scripts/probe-pi-packaged-runtime.mjs --samples 5 --timeout-ms 10000: partial pass on a controlled Windows x64 Electron Builder app.asar artifact. Cold ready p95 682 ms, warm ready p95 663 ms, RSS p95 141320 KiB, exit p95 18 ms; all 130 applicable packages and six runtime assets resolve from the artifact, with one same-version dependency flattened by Electron Builder.
  • node scripts/probe-pi-provider-contracts.mjs ...packaged-runtime-paths...: passed all four loopback HTTP/SSE contracts through the packaged executable. Provider-shaped overlap was 304/309/290/297 ms; every protocol passed image/header/credential/model/path checks and one-worker abort isolation. Scope was 127.0.0.1 only and no real Provider Account was contacted.
  • Frozen install in an isolated WSL2 Ubuntu 24.04 x64 snapshot used Node 22.22.2 and the exact repository-pinned pnpm@10.33.4; native dependencies installed successfully.
  • Linux workspace 5+5: cold ready p95 853 ms, warm ready p95 437 ms, RSS p95 170388 KiB, exit p95 8 ms.
  • Linux staged 5+5: cold ready p95 428 ms, warm ready p95 440 ms, RSS p95 175956 KiB, exit p95 8 ms; all 131 Linux-applicable packages present and 8 platform-specific entries skipped.
  • Linux controlled packaged 5+5: cold ready p95 545 ms, warm ready p95 569 ms, RSS p95 181928 KiB, exit p95 7 ms; all 131 applicable packages, six runtime assets, and unpacked native assets resolve from the artifact.
  • Linux packaged loopback: all four contracts passed with 292/290/277/288 ms overlap, correct path/header/credential/model/image serialization, and isolated abort behavior.
  • Post-fix node scripts/probe-pi-packaged-runtime.mjs --samples 1 --timeout-ms 10000: Windows controlled packaged smoke passed through the explicitly supplied resource directory; cold/warm ready were 650/641 ms and no dependency or asset was missing.
  • Post-Provider-waiver node scripts/probe-pi-runtime.mjs --samples 1 --timeout-ms 10000: passed with cold/warm ready 650/588 ms. All four providerMatrix.realTurnVerified values remained false; real Provider evidence moved out of missingEvidence into explicit waivers, and macOS remained deferred to PI-150. The per-run decision remains incomplete because one local sample cannot issue the aggregate PI-000 decision.
  • Post-probe process queries on Windows and Linux: zero controlled artifact processes and zero Pi RPC-looking processes remained.
  • Execution-environment inventory found no repository CI definition, macOS runner/SSH host, GitLab runner CLI, or Provider credential environment variable. The internal GitLab remote alone cannot produce the deferred macOS evidence or optional real-Provider diagnostics; neither absence remains a PI-000 blocker after the explicit user decisions.
  • The evidence gate table was reconciled with the accepted Spec's normative numbering: QG-002 RPC lifecycle, QG-003 dependency closure, QG-004 Provider Accounts, QG-005 real-provider concurrency, QG-006 metrics, and QG-007 stop-and-amend condition.
  • The planner synchronized the accepted Spec and ticket graph: 134 unique requirements across 19 traceability groups, 18 tickets, 31 edges, and an acyclic topology remain intact; recomputation produced exactly PI-010, PI-020, and PI-030 as the new Ready Frontier.
  • Detailed evidence: .project-docs/50-evidence/topics/20260822-pi-runtime-qualification-c52e8a14__pi-runtime-qualification.md.

Follow-ups

  • Real Provider fixtures may still be run as optional diagnostics, but they are no longer PI-000 or PI-150 acceptance requirements. Never backfill QG-004/QG-005 as Pass without actual evidence, and do not place secrets in fixtures or task records.
  • At PI-150, run macOS x64 and macOS arm64 workspace/staged/final packaged samples, packaged loopback, closure/native/resource checks, and metrics before claiming cross-platform release readiness. Use separate frozen installs and artifacts for each architecture.
  • If Linux qualification must cover a native desktop distribution or release package rather than the accepted controlled dir boundary, repeat the Linux probe outside WSL2; the current sample is explicitly Ubuntu 24.04 userspace on a WSL2 kernel.
  • Any later confirmed runtime, packaging, concurrency, isolation, or performance failure is new evidence and must return to architecture review; this waiver records accepted uncertainty, not permission to misreport a known failure.

Promotion Candidates

  • Target: the planner's Pi runtime cutover ticket graph / ready frontier. Proposal: mark PI-000 Done with explicit waivers and advance the Ready Frontier to PI-010, PI-020, and PI-030; keep macOS explicitly deferred to PI-150 and QG-004/QG-005 explicitly waived rather than passed. Evidence: task-scoped PI-000 qualification evidence record. Future impact: downstream implementation proceeds while carrying explicit real-Provider and deferred macOS uncertainty; loopback and packaged evidence remain the proven boundary. Semantic conflicts: none after the planner's user-authorized Spec/ticket amendment. Human confirmation required: already supplied by the user's 2026-08-22 waiver decisions; a later confirmed failure requires a new architecture decision.