fix(coding): recover provider context failures

.project-docs/30-worklog/tasks/20260826-fix-pi-model-provider-8d4c2a71.md

@@ -0,0 +1,170 @@
+# Task: Fix Pi first-model and Provider context failures
+
+## Identity
+
+- Task ID: 20260826-fix-pi-model-provider-8d4c2a71
+- Mode: Feature
+- Branch: codex/20260826-fix-pi-model-provider-8d4c2a71-fix-pi-model-provider
+- Worktree: D:\Datas\OthersProjects\makelore-fix-pi-model-provider-8d4c2a71
+- Base commit: 9f05e2d7e194b3ae3507c019de53e437aaed9458
+- Owner: codex-root
+- Status: In Progress
+
+## Scope
+
+- Fix the production ordering for an unresolved Conversation's first model
+  selection: validate the selected managed model, persist resolved product
+  metadata, and only then prepare the Pi worker/session. Preserve the existing
+  active-run-safe `runtime.setModel()` path for already-resolved Conversations.
+- Add a production-shaped regression whose runtime rejects every unresolved
+  prepare, so the InMemory runtime can no longer hide the ordering defect.
+- Classify the exact captured Works Square gateway failure "did not return
+  one-api user context" at the Main-owned local AI proxy boundary as a
+  Provider credential/context failure. Preserve the upstream body, avoid
+  generic Pi automatic retry of the deterministic `502`, and reuse the
+  existing single credential refresh/reopen boundary without replaying a
+  mutation.
+- Replace the misleading generic English "local Agent retry failed" projection
+  with a fixed Provider-neutral Chinese retry failure message while retaining
+  content redaction.
+- Rebuild and verify the Windows package and final packaged proof after the
+  product-code correction; durably bind the candidate/artifact/runtime/test
+  identity required by the prior planner review.
+
+## Intent And Constraints
+
+- The installed incident is confirmed to be a Works/one-api user-context
+  rejection, not a Pi worker crash and not the unresolved-first-model defect.
+  These are two independent defects fixed in one bounded correction because
+  both block acceptance of the same candidate.
+- Do not invent a new Provider authentication protocol or forward the local
+  Host `Authorization` token upstream. Existing evidence shows the same proxy
+  contract worked before the incident; only the exact observed structured
+  failure may be reclassified unless tests or source contracts prove more.
+- Keep Provider refresh bounded to the existing one refresh/reopen attempt.
+  Never replay an accepted or uncertain mutation, and never add another Pi
+  restart/watchdog/fallback path.
+- Preserve Pi `0.84.2`, the hard cutover, Conversation target isolation,
+  selected-account secret scoping, redaction, and Main ownership of Provider
+  and runtime lifecycle.
+- Real Provider remains `Explicitly Waived / Accepted Risk` with
+  `realTurnVerified=false`. A loopback or captured-response regression is not
+  a real Provider Pass. macOS and native non-WSL Linux remain unverified.
+- No external Works account, gateway mapping, installed user data, or running
+  application is mutated by this feature task. If the server mapping remains
+  invalid, the client must expose an actionable Provider failure but cannot
+  manufacture a successful turn.
+
+## Project Context Loaded
+
+- `.project-docs/10-overview/read-before-planning.md`
+- `.project-docs/10-overview/project-positioning.md`
+- `.project-docs/10-overview/current-state.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-rules/business-rules.md`
+- `.project-docs/40-rules/success-criteria.md`
+- `.project-docs/60-contracts/commitments.md`
+- `.project-docs/60-contracts/stale-items.md`
+- `.project-docs/00-governance/memory-index.md`
+- `.project-docs/00-governance/decision-index.md`
+- `.project-docs/00-governance/evidence-index.md`
+- `.project-docs/00-governance/reflection-index.md`
+- `.project-docs/00-governance/planning-gate.md`
+- `.project-docs/30-worklog/proposals/20260825-pi-runtime-resilience-proposal.md`
+- Peer scopes inspected: the completed background-run implementation, its
+  planner review, and the installed-package diagnosis. This task owns only the
+  two accepted corrections and their regenerated Windows proof; it does not
+  reopen retained-correlation/background-lease design or modify the read-only
+  diagnosis records.
+- All registry peers still marked `planning` were inspected through their task
+  records. Eight retain placeholder/undefined scope and therefore provide
+  unknown coordination state, but none claims this worktree or a concrete Pi
+  Provider/conversation-service code path. The one concrete E2E peer is scoped
+  to an AI Design test. The existing `main` integration task owns only the old
+  OpenCode model-switch reconciliation and the canonical integration lock; it
+  does not conflict with feature implementation here, but it must be resolved
+  before any later merge to `main`.
+- Planning Gate: **Passed**. Ownership matches this task's feature worktree and
+  branch; no concrete semantic conflict blocks the bounded correction.
+
+## Plan
+
+1. Add failing regressions for strict unresolved preparation and the exact
+   captured Works user-context response; confirm both fail for the expected
+   contract reason.
+2. Make the minimal ordering and Provider-classification changes, plus the
+   redacted Provider-neutral retry message, then rerun the focused feedback
+   loop.
+3. Run typecheck, scoped/full lint and unit tests, `build:vite`, applicable
+   Windows Electron E2E, Windows package/artifact/Pi verifiers, and final
+   packaged proof. Record exact candidate and artifact identity.
+4. Complete the task documentation gate and commit only owned product/tests/
+   task-record changes. Integration to `main` remains a separate Integration
+   Gate after the feature candidate is accepted.
+
+## Outcome
+
+- `CodingConversationService.setModel()` now keeps the already-resolved path
+  unchanged (`prepare -> authoritative Snapshot guard -> runtime.setModel ->
+  persist`) while the unresolved path performs `validate -> persist resolved
+  metadata -> initial prepare`. A strict runtime that rejects unresolved input
+  reproduces the old `CODING_MIGRATION_MODEL_REQUIRED` failure and passes only
+  after the ordering correction.
+- The Main-owned AI proxy recognizes only the captured Works Square
+  user-context failure shape. It expires the cached gateway credential,
+  preserves the upstream JSON body, maps the retryable upstream `502` to a
+  non-retryable `401`, and does not replay the current Provider mutation. The
+  next user retry obtains a fresh gateway credential through the existing
+  credential service.
+- Pi projection now terminalizes a non-retrying assistant Provider error on
+  `agent_end`, preserves the failure through `agent_settled`, and classifies
+  both fail-fast and exhausted-retry forms of the observed Works failure as
+  `CODING_PROVIDER_AUTH_REQUIRED`. Raw Provider/request text is not projected.
+  Other exhausted Provider retries use a fixed Chinese Provider-neutral
+  message instead of blaming a local Agent crash.
+- This client correction cannot repair a persistently invalid Works backend
+  account mapping. It makes one fresh-credential retry possible and attributes
+  any continuing failure to the correct Provider boundary.
+
+## Verification
+
+- Regression red phase: the three new production-shaped tests failed on the
+  old implementation with unresolved prepare, forwarded `502`, and an
+  incorrectly completed run.
+- Focused related tests: 5 files / 54 tests passed before the exhausted-retry
+  addition; final projector file 12/12 passed.
+- `pnpm run typecheck`: passed.
+- Scoped ESLint: passed.
+- `pnpm test`: 181 functional files / 1540 passed / 2 skipped, plus REN-008
+  pressure 1/1 passed. The final added projector assertion is covered by a
+  subsequent isolated 12/12 pass and will be included in the clean-candidate
+  rerun.
+- `pnpm run lint:check`: 0 errors / 5 pre-existing warnings.
+- `pnpm run build:vite`: passed.
+- `pnpm run test:electron:windows`: 2 files / 4 tests passed.
+- A dirty-worktree staging/package smoke completed after the GitHub UV download
+  timed out twice; exact verified uv 0.10.0 binaries were reused from the prior
+  accepted Windows candidate. This smoke is not final artifact evidence because
+  packaged Git metadata still points at the base commit. A clean committed
+  rebuild and all artifact/final-ASAR verifiers remain required.
+
+## Follow-ups
+
+- Commit the implementation candidate, rebuild from that clean commit, and run
+  Windows artifact/Pi/final-ASAR verification with a self-bound structured
+  report before completing this feature task.
+- After feature acceptance, use a separate Integration Gate to resolve the old
+  `main` integration lock, reconcile canonical project memory, and merge. Do
+  not conflate this feature branch with integration ownership.
+
+## Promotion Candidates
+
+- Target canonical document: Pi runtime/provider failure contract.
+  Proposal: record that deterministic Works user-context failures expire the
+  cached gateway credential, fail fast without replay, and remain Provider
+  failures through Renderer projection rather than being relabeled as local
+  worker crashes. Evidence: captured installed-package trace plus strict proxy
+  and projector regressions. Human confirmation required during Integration
+  Gate: yes.