fix: resume Local AI setup with a new model

[RomneyDa]

Summary

• allow the non-destructive Local AI recovery flow to select another compatible catalog model
• reuse the verified llama-server runtime while downloading only the replacement model
• keep the prior manifest and verified replacement endpoint history inside the existing atomic receipt
• reuse the recovery pipeline's existing ownership checks, rollback, restart, and uninstall behavior

Cleanup

This branch was rebuilt on current main after #1384, #1390, #1397, and #1399 landed adjacent recovery and endpoint-lifecycle infrastructure.

• removed the separate replacement store, sidecar, router-preset snapshot, and parallel rollback state machine
• use the existing recovery transaction flags and exact Gateway provider/primary checks
• consolidated the old 15-commit branch into one focused commit
• reduced the PR from +1,005 net lines to +432 net lines, including focused interruption regressions

Recovery model

The active manifest may temporarily contain one validated ReplacedManifest plus the verified endpoints published during the replacement. The prior receipt must describe the same runtime, executable, runtime assets, and requested port, but a different catalog model. Nested replacements and mixed Gateway routes fail closed. Recovery accepts only an exact current, earlier verified replacement, or rollback route; transaction state is cleared only after the replacement route has been applied and the Gateway restart succeeds.

Required proof pools

• windows-wsl-dgx-blackwell: managed Local AI model routing and restart behavior changed.
• windows-wsl-gateway-e2e: the managed Gateway provider/primary route, recovery, and uninstall paths changed.
• windows-winui-interactive: recovery now permits selecting another compatible model.

Validation

• git diff --check — PASS at 2aa28687
• exact-head Windows Build and Test — PASS
• exact-head CodeQL — PASS
• ClawSweeper exact-head review — no actionable code or security findings

Current-head native Windows/GPU/WSL behavior proof is not claimed from this macOS host. The declared proof pools remain a maintainer landing gate.

Security impact

No new permissions, credentials, externally reachable endpoints, or command surfaces. Replacement accepts only a catalog-qualified model on the same validated runtime/GPU and only the exact prior or replacement managed Gateway route; ambiguous, nested, or mixed state fails closed.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: blocked before merge. Reviewed September 12, 2026, 5:41 AM ET / 09:41 UTC (Revision 24).

ClawSweeper review

What this changes

Allows Local AI recovery to choose another compatible model while preserving installation receipts and endpoint history for resume, rollback, and uninstall.

Regression provenance

Possible regression — suspected (reviewed change). No predecessor PR is attributed.

Merge readiness

⛔ Blocked before merge - 5 items remain

This remains a distinct, useful extension to main’s recovery flow. One source-proven receipt compatibility defect blocks merge; the previously reported interruption fixes are present.

Priority: P2
Reviewed head: 2aa286871cf71a8d5e9986134df9eb68392acd02
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The focused recovery design and regression coverage are useful, but a documented receipt compatibility contract is broken.
Proof confidence	🌊 off-meta tidepool	Not applicable: The MEMBER author is exempt from the external-contributor proof gate. The supplied evidence covers tests and CI, while production endpoint-history writes, native Gateway replacement/recovery, and enabled WinUI selection remain explicitly unverified under the declared proof pools.
Patch quality	🦐 gold shrimp (3/6)	1 actionable review finding remain.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: The MEMBER author is exempt from the external-contributor proof gate. The supplied evidence covers tests and CI, while production endpoint-history writes, native Gateway replacement/recovery, and enabled WinUI selection remain explicitly unverified under the declared proof pools.
Evidence reviewed	9 items	Repository policy applied: Read the complete root AGENTS.md and proof-validation skill. No nested AGENTS.md files were found under src or tests, and .agents/maintainer-notes was absent. Applied recovery ownership, receipt compatibility, and native proof guidance without executing builds or mutating the checkout. Work remains distinct from main: Pinned main still disables the model selector for receipt-backed recovery. The merged recovery work at #1384 (fix(local-ai): add non-destructive recovery) supplies the recovery foundation but explicitly pins the existing model. The latest release endpoint reports v2026.9.3; no local release tag contains this PR head. Documented backward-reader contract: The setup design explicitly preserves rollback to schema-4-aware transitional builds, including the reader at 3ce56b8. This is a documented compatibility path, not a demand for arbitrary downgrade support.
Findings	1 actionable finding	[P1] [P1] Omit replacement metadata from completed compatible receipts
Security	None	None.

How this fits together

Local AI setup installs a managed llama-server runtime and configures the WSL Gateway to use its model. Recovery coordinates the selected model, persisted installation receipt, runtime endpoint, and Gateway route.

flowchart TD
  A[Recovery model selection] --> B[Validate existing installation]
  B --> C[Reuse runtime and acquire model]
  C --> D[Save replacement receipt]
  D --> E[Verify runtime endpoint]
  E --> F[Update managed Gateway route]
  F --> G[Restart and finalize receipt]
  D --> H[Resume or roll back]

Loading

Decision needed

Question	Recommendation
After the receipt compatibility repair, must the three declared native proof pools complete before landing, or will you explicitly accept their scoped coverage gaps?	Complete the declared native evidence: Require current-head replacement, interrupted recovery, uninstall, and enabled model-selection evidence before landing.

Why: The PR declares Windows/GPU/WSL and interactive evidence outstanding; accepting those gaps requires maintainer ownership of the existing-install risk.

Before merge

• [P1] Omit replacement metadata from completed compatible receipts (P1) - Every manifest save now emits previousEndpoints: [], including ordinary runtime startup and finalization after a successful replacement. The documented schema-4 transitional reader at 3ce56b8902d558a2d43a1308b4d61ccbf6856274 has no such property and uses JsonUnmappedMemberHandling.Disallow, so the supported rollback path fails to load these receipts even when no replacement is pending. Omit replacement-only fields outside pending transitions and add backward-reader coverage for ordinary and finalized saves. This was missed in the earlier review of the same unchanged head.
• Resolve merge risk (P1) - Native replacement and upgrade behavior remains unverified; an interruption or failed compensation could leave an existing Gateway pointing at an unavailable model endpoint.
• Resolve merge risk (P1) - The supported rollback boundary while a replacement is pending remains unspecified; preserving model bytes alone does not make older readers understand replacement metadata.
• Complete next step (P2) - Repair completed-receipt compatibility, resolve the retained endpoint-history validation request, and obtain native proof or explicit scoped maintainer acceptance before merge.
• Resolve maintainer decision - Resolve the maintainer decision shown above before merge.

Findings

• [P1] [P1] Omit replacement metadata from completed compatible receipts — src/OpenClaw.Connection/LocalAi/LocalAiManifest.cs:205-206

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Production and test LOC	Production +316/-47 (net +269); tests +188/-25 (net +163)	Production growth implements durable replacement within existing recovery owners, with focused receipt and Gateway regression coverage.

Merge-risk options

Maintainer options:

1. Preserve completed-receipt compatibility (recommended)
   Omit replacement-only metadata from ordinary and finalized receipts and verify them against the documented transitional reader.
2. Hold landing for native recovery evidence
   Keep the PR open until declared native proof is supplied or a maintainer explicitly accepts the remaining coverage gaps.

Copy recommended automerge instruction

@clawsweeper automerge

Special instructions:
Preserve the documented schema-4 transitional-reader contract by omitting replacement-only metadata when no replacement is pending; add ordinary-save and finalized-receipt backward-reader regressions without weakening strict JSON validation or losing pending endpoint history.

Technical review

Best possible solution:

Preserve the documented completed-receipt format, retain durable pending transitions, and establish upgrade/recovery proof or explicit scoped maintainer acceptance.

Do we have a high-confidence way to reproduce the issue?

Yes, from source: save an ordinary or finalized receipt with this branch, then load it with the documented transitional reader; the emitted previousEndpoints member encounters strict unknown-member rejection. This path was not executed.

Is this the best way to solve the issue?

The existing recovery owners are the right place for this capability, but the patch is not ready: ordinary and finalized receipts must preserve the supported backward-reader format.

Full review comments:

• [P1] [P1] Omit replacement metadata from completed compatible receipts — src/OpenClaw.Connection/LocalAi/LocalAiManifest.cs:205-206
  Every manifest save now emits previousEndpoints: [], including ordinary runtime startup and finalization after a successful replacement. The documented schema-4 transitional reader at 3ce56b8902d558a2d43a1308b4d61ccbf6856274 has no such property and uses JsonUnmappedMemberHandling.Disallow, so the supported rollback path fails to load these receipts even when no replacement is pending. Omit replacement-only fields outside pending transitions and add backward-reader coverage for ordinary and finalized saves. This was missed in the earlier review of the same unchanged head.
  Confidence: 0.98
  Late finding: first raised on code an earlier review cycle already covered.

Overall correctness: patch is incorrect
Overall confidence: 0.94

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against bd9ce43b4d9c.

Labels

Label justifications:

• P2: This is a bounded Local AI recovery improvement without evidence of a new widespread user-facing outage.
• merge-risk: 🚨 compatibility: The new serialized receipt member breaks the documented transitional-reader rollback path even outside pending replacement.
• merge-risk: 🚨 auth-provider: Model replacement changes persisted Gateway provider and primary routing, whose native interruption and compensation behavior remains unverified.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: The MEMBER author is exempt from the external-contributor proof gate. The supplied evidence covers tests and CI, while production endpoint-history writes, native Gateway replacement/recovery, and enabled WinUI selection remain explicitly unverified under the declared proof pools.

Evidence

Acceptance criteria:

• [P1] ./build.ps1.
• [P1] dotnet test ./tests/OpenClaw.Shared.Tests/OpenClaw.Shared.Tests.csproj --no-restore.
• [P1] dotnet test ./tests/OpenClaw.Tray.Tests/OpenClaw.Tray.Tests.csproj --no-restore.
• [P1] dotnet test ./tests/OpenClaw.Connection.Tests/OpenClaw.Connection.Tests.csproj --no-restore.
• [P1] dotnet test ./tests/OpenClaw.SetupEngine.Tests/OpenClaw.SetupEngine.Tests.csproj --no-restore.

What I checked:

• Repository policy applied: Read the complete root AGENTS.md and proof-validation skill. No nested AGENTS.md files were found under src or tests, and .agents/maintainer-notes was absent. Applied recovery ownership, receipt compatibility, and native proof guidance without executing builds or mutating the checkout. (AGENTS.md:88, 2aa286871cf7)
• Work remains distinct from main: Pinned main still disables the model selector for receipt-backed recovery. The merged recovery work at fix(local-ai): add non-destructive recovery #1384 (fix(local-ai): add non-destructive recovery) supplies the recovery foundation but explicitly pins the existing model. The latest release endpoint reports v2026.9.3; no local release tag contains this PR head. (src/OpenClaw.SetupEngine.UI/Pages/CapabilitiesPage.xaml.cs:598, bd9ce43b4d9c)
• Documented backward-reader contract: The setup design explicitly preserves rollback to schema-4-aware transitional builds, including the reader at 3ce56b8. This is a documented compatibility path, not a demand for arbitrary downgrade support. (docs/SETUP_ENGINE_REDESIGN.md:228, 2aa286871cf7)
• Transitional reader rejects new fields: Read the exact transitional source through GitHub. Its manifest has neither replacement property, and its serializer sets UnmappedMemberHandling to Disallow, so previousEndpoints is rejected even when its value is an empty array. (src/OpenClaw.Connection/LocalAi/LocalAiManifest.cs:272, 3ce56b8902d5)
• Unconditional receipt format expansion: PreviousEndpoints has no conditional serialization rule. Ordinary runtime endpoint saves serialize it, and finalization merely assigns an empty array, leaving the new JSON member in completed receipts. (src/OpenClaw.Connection/LocalAi/LocalAiManifest.cs:206, 2aa286871cf7)
• Review continuity: The most recent completed review inspected this same head and reported no findings. The manifest comparison is empty, so the backward-reader defect is explicitly marked as a late discovery. Earlier receipt, fallback, missing-endpoint, and endpoint-history concerns have corresponding repairs in the current source. (src/OpenClaw.Connection/LocalAi/LocalAiManifest.cs:206, 2aa286871cf7)

Likely related people:

• shanselman: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• joelagnel: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• karkarl: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Omit replacement metadata from ordinary and finalized receipts and verify the documented transitional reader accepts both.
• Exercise production endpoint-history writers across repeated disk reloads, then verify recovery and uninstall from those receipts.
• Complete the declared native upgrade/recovery evidence or record explicit scoped maintainer acceptance.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (23 earlier review cycles; latest 8 shown)

• reviewed 2026-09-12T08:02:15.787Z sha 1aa568b :: blocked before merge. :: [P1] [P1] Retain the published replacement endpoint across resume | [P1] [P1] Preserve pending replacement state when assets need repair | [P2] [P2] Guard prior-provider matching when its endpoint is absent | [P2] [P2] Recognize the previous model's retained primary during replacement | [P2] [P2] Allow recovery to record the current external fallback
• reviewed 2026-09-12T08:12:29.327Z sha 1aa568b :: blocked before merge. :: [P1] [P1] Retain the published replacement endpoint across resume | [P1] [P1] Preserve pending replacement state when assets need repair | [P2] [P2] Guard prior-provider matching when its endpoint is absent | [P2] [P2] Recognize the previous model's retained primary during replacement | [P2] [P2] Allow recovery to record the current external fallback
• reviewed 2026-09-12T08:19:04.367Z sha 765cc81 :: blocked before merge. :: [P1] [P1] Match the persisted published endpoint when recovery resumes | [P1] [P1] Preserve the pending receipt's fallback during asset repair
• reviewed 2026-09-12T08:35:28.366Z sha d7cea40 :: blocked before merge. :: [P1] [P1] Preserve the original fallback when no replacement is pending | [P1] [P1] Advance durable endpoint provenance after route publication
• reviewed 2026-09-12T08:48:59.442Z sha 1bded38 :: blocked before merge. :: [P1] [P1] Advance durable provenance when a replacement route is published
• reviewed 2026-09-12T09:04:29.933Z sha 400d743 :: blocked before merge. :: [P1] [P1] Preserve publication provenance before the next endpoint rewrite
• reviewed 2026-09-12T09:21:44.519Z sha 2aa2868 :: blocked before merge. :: none
• reviewed 2026-09-12T09:34:44.615Z sha 2aa2868 :: blocked before merge. :: none

[RomneyDa]

Addressed the ClawSweeper P1 in d9fd022.

• Accepts the exact prior companion-managed provider/primary only during an explicit model replacement.
• Carries the prior fallback into the replacement manifest.
• Reconstructs the prior provider from the trusted old manifest and restores the old primary on rollback.
• Adds a gateway-step regression covering successful old-to-new transition and rollback.
• Fixes the prior CI compile failure by importing the shared GPU types.
• Structured autoreview is clean with no actionable findings.

Native Windows CI is rerunning now. @clawsweeper re-review

[RomneyDa]

Fixed the Windows CI compile failure in the GPU test fixture. GpuInfo includes shared-memory parameters, so the positional driver/CUDA/stable-ID arguments had shifted. Commit uses named arguments and autoreview is clean. CI is rerunning.

[karkarl]

Adversarial dual-model review

Verdict: SHIP AFTER FIXES

Claude Opus and GPT Codex independently reviewed the PR diff, then cross-examined the disputed interruption path. Both confirmed one release blocker.

HIGH consensus

Issue	Opus	Codex	Fix confidence	Release blocker
If setup is interrupted after persisting model B's manifest but before switching the gateway from model A to B, prior-install provenance is lost because ReplacedLocalAiInstall exists only in memory. A fresh run treats B as fully reused while the gateway remains on A, so ConfigureLocalAiGatewayStep rejects the exact old managed route. Repeated B retries remain stuck. Uninstall also cannot prove that gateway A belongs to manifest B, preserves the stale route, and continues best-effort cleanup of Local AI state.	HIGH	HIGH	85%	Yes

Affected regions:

• LocalAiSetupSteps.cs:568-580
• LocalAiInstallReconciler.cs:76-103
• LocalAiGatewayConfiguration.cs:100-129,247-303

Required fix direction: make the replacement transition durable across process termination, retaining enough trusted prior-install/provider provenance to complete or roll back the A-to-B gateway transition. Keep the exact-provider ownership checks. Do not broaden them to accept merely managed-looking configuration.

Required regression coverage: add a fresh-process crash/resume test for the window after manifest replacement and before gateway configuration, plus uninstall behavior from that drift state.

LOW consensus

Issue	Opus	Codex	Fix confidence
matchesReplacementPrior can throw InvalidDataException if the old model is no longer catalog-qualified. The pipeline fails safely, but reports an opaque unhandled-step failure.	—	LOW	95%

In-process rollback ordering, reused-runtime preservation, API-key redaction handling, and fallback/primary propagation were reviewed and found sound for uninterrupted replacement.

Regression risk: Medium-high for interrupted model replacement; low for the uninterrupted happy path.

[RomneyDa]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event exact_review_queue).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/34421808330
• Updated: 2026-09-10T00:33:54.044Z

[RomneyDa]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event exact_review_queue).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/34437739078
• Updated: 2026-09-10T04:35:19.925Z

[RomneyDa]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event exact_review_queue).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

[RomneyDa]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event exact_review_queue).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.