fix(pi): resolve packaged proxy token lazily

.project-docs/30-worklog/tasks/20260824-pi-runtime-unavailable-hotfix-4e9c7a31.md

@@ -0,0 +1,141 @@
+# Task: Fix packaged Pi proxy token initialization and recovery
+
+## Identity
+
+- Task ID: 20260824-pi-runtime-unavailable-hotfix-4e9c7a31
+- Mode: Feature
+- Branch: codex/20260824-pi-runtime-unavailable-hotfix-4e9c7a31-pi-runtime-unavailable-hotfix
+- Worktree: D:\Datas\OthersProjects\makelore-pi-runtime-unavailable-hotfix-4e9c7a31
+- Base commit: fa510c49761485cbd323801923dbe2472d6981bb
+- Owner: codex-root
+- Status: In Progress
+
+## Scope
+
+- Fix the Windows packaged Pi startup failure for the
+  `works_square_ai_gateway_proxy` account without changing the OpenCode-to-Pi
+  architecture or starting PI-160.
+- Resolve the Main Host API credential lazily for persistent parent open,
+  rebuild/recover, and ephemeral child open; preserve Main ownership and prove
+  token rotation does not reuse a captured value.
+- Map Pi's typed `PROVIDER_AUTH_REQUIRED` failure through the existing single
+  refresh/reopen boundary, and make Renderer Conversation recovery failure
+  leave `recovering` for a retryable per-Conversation error without losing
+  user state.
+- Produce and verify a Windows x64 NSIS installer from the final clean
+  candidate, including a real packaged Main-composition proxy first-
+  Conversation proof and token non-disclosure checks.
+
+## Intent And Constraints
+
+- Base exactly on `fa510c49761485cbd323801923dbe2472d6981bb`, which is the
+  common HEAD of the PI-150 release-proof and diagnostic worktrees and contains
+  code candidate `09841c8`; do not rewrite or drop cumulative PI-150 history.
+- Do not modify the old PI-150 worktree, diagnostic worktree, occupied/dirty
+  `main`, or the user's installed application under
+  `D:\Tools\泥土\niancode\Makelore`.
+- Keep the Host token Main-owned and memory-only. Never write it to argv,
+  `models.json`, logs, diagnostics, task evidence, or Renderer state.
+- Do not upgrade Pi, add a fallback/compatibility layer, refactor Host auth, or
+  change direct API-key, OAuth, or local Provider behavior.
+- Real Provider verification remains `Explicitly Waived / Accepted Risk` with
+  `realTurnVerified=false`; macOS and native non-WSL Linux gate status is
+  unchanged.
+- Use the exact package-manager version pinned by `packageManager`, frozen
+  install semantics, focused regressions, full repository verification, and
+  the formal Windows packaging path.
+
+## Project Context Loaded
+
+- Concurrent Task Gate: Passed in the isolated worktree above; ownership is
+  `codex-root`, feature mode, and the task record matches the registry.
+- Planning Gate: Passed after reading the diagnostic record, PI-150 source
+  record, memory index, positioning/current-state/decision/architecture/domain/
+  evidence/reflection/commitment/stale records, and all active peer scopes.
+- The shared canonical snapshot is older than the Pi feature chain. The
+  diagnostic record, cumulative PI-150 source record, current source, and the
+  delegated repair boundary are authoritative for this task.
+- Other active tasks use separate worktrees. The main-worktree integration task
+  concerns the older OpenCode model-switch path and explicitly does not package;
+  no semantic conflict requires changing this hotfix plan.
+- No subagents are used by explicit user direction.
+
+## Plan
+
+1. Inspect the exact composition, opener, auth-classifier, recovery-store, test,
+   Windows Electron E2E, and packaged proof seams; identify the smallest
+   production and test surface.
+2. Add red-capable focused regressions for lazy/current token reads across
+   parent/rebuild/recover/child, typed auth mapping and bounded refresh, recovery
+   failure/retry, and unaffected direct/OAuth/local Provider paths.
+3. Implement the lazy Main-owned credential getter, typed error classification,
+   and retryable recovery-state transition with surgical changes only.
+4. Run focused tests, typecheck, lint, the full unit suite, production build,
+   and Windows Electron E2E; fix only failures caused by this hotfix.
+5. Commit the clean implementation candidate, run formal `package:win`, execute
+   Windows artifact/runtime closure checks, and run a final packaged Main-
+   composition proxy first-Conversation proof including token-secrecy and clean
+   process-exit assertions.
+6. Record exact commits, changed files, verification results, NSIS size/hash,
+   structured packaged evidence and unchanged release waivers; pass the Task
+   Documentation Gate and mark the task ready for integration.
+
+## Outcome
+
+- Implemented a lazy `getLocalProxyCredential` seam from Electron Main through
+  the single coding composition. Composition construction no longer reads or
+  captures the pre-server token; persistent parent first-open, recover/rebuild,
+  and ephemeral child open all resolve the getter at the worker-open boundary.
+- Extended the existing typed Provider-auth classifier to recognize only
+  `PiProviderConfigError.code === PROVIDER_AUTH_REQUIRED`. Initial prepare and
+  prompt authentication failures now use the existing maximum-one refresh and
+  reopen coordinator and project as `CODING_PROVIDER_AUTH_REQUIRED`.
+- Made Renderer recovery failures leave `recovering` for the target
+  Conversation's retryable `error` state while preserving the selected
+  Conversation, last good Snapshot, draft, and attachments; a later retry can
+  recover normally.
+- Added focused rotation/non-disclosure regressions for parent first-open,
+  recover, rebuild, and child open while retaining the pre-existing direct
+  API-key/OAuth/local credential coverage.
+- Extended the final packaged proof entry so the actual global Main composition
+  can exercise `works_square_ai_gateway_proxy` through the current authenticated
+  Host proxy, create the first Conversation from the real UI, establish a Pi
+  binding, accept input, dispatch a real packaged parent and child, and verify
+  argv/models/log/diagnostic token non-disclosure. Its upstream is controlled
+  loopback and the report remains `realTurnVerified=false`.
+- Implementation and repository verification are complete. Formal Windows NSIS
+  packaging and final-artifact proof remain pending from the clean candidate.
+
+## Verification
+
+- `corepack pnpm install --frozen-lockfile` with pinned pnpm `10.33.4`: passed,
+  997 packages linked from the existing store and the lockfile remained
+  unchanged.
+- Focused Vitest run for composition, auth, Renderer recovery, parent opener,
+  child opener, and auth recovery: 6 files / 55 tests passed. The preceding red
+  run failed exactly on typed auth classification, auth-required projection,
+  and permanent `recovering` state.
+- `corepack pnpm run typecheck`: passed after the final proof changes.
+- `corepack pnpm run lint:check`: passed with 0 errors and 5 pre-existing React
+  warnings in `src/pages/Home/index.tsx` and `src/pages/Makelore/index.tsx`.
+- `corepack pnpm test`: passed; primary run 178 files / 1512 passed / 2 skipped,
+  serialized pressure run 1 file / 1 passed.
+- `corepack pnpm run build:vite`: passed; Renderer, Main, Preload, and release
+  utility bundles built. Existing dynamic-import and large-chunk warnings remain.
+- `corepack pnpm run test:electron:windows`: passed; 2 files / 4 tests.
+- `corepack pnpm run package:win`, final artifact/closure verifier, and final
+  packaged global-Main proxy proof: pending the clean implementation commit.
+
+## Follow-ups
+
+- Real external Provider turn verification remains explicitly waived and its
+  concurrency, credential-isolation, and protocol-compatibility risk remains
+  accepted; the loopback Host-proxy proof must not be reported as a real
+  Provider pass.
+- macOS and native non-WSL Linux release gates remain unchanged by this Windows
+  hotfix.
+
+## Promotion Candidates
+
+- None. This feature task records the hotfix and evidence locally; it does not
+  promote stale shared OpenCode-era canonical documents.