makelore/.project-docs/30-worklog/tasks/20260821-model-switch-runtime-fix-a83d6c91.md

Task: Fix OpenCode session model switching and local proxy token binding

Identity

• Task ID: 20260821-model-switch-runtime-fix-a83d6c91
• Mode: Feature
• Branch: codex/20260821-model-switch-runtime-fix-a83d6c91-model-switch-runtime-fix
• Worktree: D:\Datas\OthersProjects\makelore-model-switch-runtime-fix-a83d6c91
• Base commit: 605fef417f
• Owner: codex
• Status: Ready for Integration

Scope

• Correct the OpenCode 1.18.9 Session-model request body at the Main-owned client boundary while retaining Makelore's internal { providerID, modelID } reference.
• Ensure a fresh runtime is launched with the current per-application Host API token for the local AI proxy, and treat persistence of that already-active token as an internal rebind rather than a user model change.
• Preserve runtime-refresh blocking for actual provider/model shape changes, direct upstream credential changes, pending refreshes, and attached or unknown runtime generations.
• Add focused regressions for the real wire payload, fresh-runtime local-proxy token rotation, and attached-runtime fail-closed behavior.

Intent And Constraints

• Page selection and /models / /model must converge on OpenCode's native Session model mutation without provider persistence or runtime restart.
• Ordinary execution must not automatically restart, reload, or dispose the shared runtime; another Session may still be active.
• Keep Host API credentials Main-owned and out of logs and Renderer state.
• Make surgical changes only in the OpenCode client, runtime provider config, provider/runtime acceptance, and focused tests. Do not alter project Agent hot-add semantics or canonical .project-docs files in feature mode.
• Work only in the claimed isolated worktree and do not create sub-agents.

Outcome

• Corrected the Main-owned OpenCode client boundary so Makelore's internal { providerID, modelID } reference is serialized as OpenCode 1.18.9's required { model: { providerID, id } } request body.
• Added the current per-application Host API token to fresh OpenCode runtime provider construction for the managed local AI proxy. The persisted token is no longer allowed to override the token already active for that runtime.
• Changed provider import and prompt preflight so persisting the token already used by an owned fresh runtime does not mark provider/runtime configuration stale or request a restart. Attached or unknown runtime generations still fail closed when the persisted token differs.
• Preserved sticky runtime uncertainty when token persistence rejects, times out, or is aborted; actual provider shape changes, upstream credential changes, and existing pending refreshes retain their previous behavior.
• Kept partner creation and Agent hot-add semantics unchanged. The fix is limited to Session model wire compatibility and the managed local-proxy credential lifecycle.

Verification

• The original focused regression run failed in all four intended areas before implementation: Session wire payload, runtime provider token selection, fresh/attached provider import behavior, and prompt preflight token rebind.
• Installed @opencode-ai/sdk 1.18.9 declares ModelRef as { id: string; providerID: string; variant?: string } for POST /api/session/{sessionID}/model, matching the corrected wire payload.
• Focused unit suite for the OpenCode client, provider config, provider routes, and OpenCode routes — 4 files, 171 tests passed.
• corepack pnpm run typecheck — passed.
• corepack pnpm run lint:check — passed with 0 errors and 6 pre-existing warnings in unrelated Renderer files.
• corepack pnpm test — 177 files, 2074 tests passed.
• corepack pnpm run build:vite — passed; only existing dynamic-import and chunk-size warnings were reported.
• corepack pnpm exec playwright test tests/e2e/opencode-multichat-runtime.spec.ts — 1 Electron E2E passed.
• git diff --check — passed; only configured LF-to-CRLF notices were emitted.
• check_doc_drift.py --task-id 20260821-model-switch-runtime-fix-a83d6c91 — passed with only the owned task record changed under .project-docs.

Follow-ups

• After integration, relaunch the rebuilt desktop application and repeat the real local model-selection smoke. The already-running installed process does not contain this source change.

Promotion Candidates

Session model wire contract and local-proxy runtime binding

• Target canonical documents: .project-docs/30-worklog/current-state.md, .project-docs/20-architecture/module-map.md, .project-docs/20-architecture/data-flow.md, and .project-docs/50-evidence/evidence-index.md.
• Proposal: retain the existing product rule that page selection and /models / /model perform native per-Session switching without provider persistence or runtime restart, and document the implementation boundary: Makelore maps internal modelID to OpenCode's wire field id; an owned fresh runtime receives the current process Host API token when its local-proxy provider config is built, so later persistence of that same active token is not a runtime configuration change. Attached/unknown generations and timeout/partial persistence remain fail-closed.
• Evidence: installed OpenCode SDK 1.18.9 ModelRef and switch-model endpoint types; electron/opencode/client.ts, electron/opencode/provider-config.ts, electron/main/index.ts, provider/OpenCode route changes, 171 focused unit tests, 2074 full unit tests, typecheck, lint, production build, and the existing model-switch Electron E2E.
• Future impact: OpenCode upgrades must recheck the exact Session model wire schema. Runtime readiness work must distinguish an ephemeral Main-owned proxy token already injected into an owned fresh generation from a true upstream provider credential change; otherwise every application launch can recreate the false manual-restart requirement.
• Semantic conflicts: canonical memory already says Session switching does not require a restart, while the previously integrated client serialized the incompatible modelID field and treated the per-process proxy token as a provider credential rotation. This candidate corrects the implementation and refines the credential boundary without changing the accepted product rule.
• Human confirmation required: no; the user explicitly requested the repair and the change is covered by regression tests.