AxiOwl Installer Repair Explained

AxiOwl Installer Repair Explained

Installer repair is one of those features that sounds simple until the installer is responsible for real developer tools. AxiOwl is not just copying one executable into a folder. The Windows MSI installs the local AxiOwl runtime, updates PATH, verifies MCP server mode, registers provider integrations, installs bridge extensions, writes provider MCP configuration, applies selected metadata patches, runs discovery, and records logs for later support work.

That is why AxiOwl treats repair as a controlled maintenance path instead of a blind overwrite. The repair path has to restore AxiOwl-owned pieces without damaging user sessions, provider authentication, unrelated extensions, or unselected providers.

What the Windows installer owns

The current Windows package is the AxiOwl Activation MSI. In the release artifact reviewed for this draft, the package version is 2.0.30, built from the Windows desktop app area of the C++ monorepo.

The core install places the local AxiOwl runtime under:

%LOCALAPPDATA%\AxiOwl

The installer docs identify the core runtime as including:

%LOCALAPPDATA%\AxiOwl\bin\axiowl.exe
%LOCALAPPDATA%\AxiOwl\manifest.json
%LOCALAPPDATA%\AxiOwl\logs
%LOCALAPPDATA%\AxiOwl\registry
%LOCALAPPDATA%\AxiOwl\runtime

The MSI backend payload itself is staged under Program Files as AxiOwl MSI Backend, with payload files such as axiowl.exe, axiowl-installer.exe, axiowl-installer-silent.exe, VSIX packages, provider extension files, Codex plugin assets, and remote-nodes.json.

That split matters. Windows Installer owns the MSI package files and custom action scheduling. The AxiOwl installer helper owns product-specific work such as copying the runtime into the user data root, validating binaries, writing config, and running discovery.

Repair still respects provider selection

AxiOwl's installer behavior matrix says the MSI installs AxiOwl once, but each provider feature should behave like a separate install unit. That is the main rule behind repair.

The provider feature contract covers current MSI provider surfaces:

The WiX file wires provider checkboxes to provider-specific MSI features. It adds selected features with AddLocal, and the build checks explicitly reject old behavior where unchecked provider features could be removed, patched, or installed as collateral damage.

That is the practical difference between a careful repair and a risky reinstall. If the Cursor module is not selected, repair should not mutate Cursor. If VS Code Copilot-backed support is not selected, repair should not apply the VS Code Copilot-backed metadata patch. If Remote is not selected, local provider repair should not quietly use remote fallback.

What happens during maintenance and repair

When the MSI detects an existing installation, the WiX UI enters a maintenance flow. The package includes a MaintenanceWelcomeDlg and schedules normal install custom actions whenever the operation is not a full remove.

The execute sequence runs core actions first:

RunDetectRunningApps
RunInstallPrepare
RunInstallLocalExe
RunInstallPathUpdate
RunInstallMcpWrapper

Then it runs selected provider actions. For example, selected VS Code Copilot-backed support can run patch, extension, and MCP steps. Selected Cursor support can run rollback restore, preflight, cleanup, extension install, MCP install, patch, discovery, and rollback commit. After provider work, the installer runs local discovery, optional remote steps if selected, finalization, and a Windows Installer rollback-cache permission repair before InstallFinalize.

The important detail is that most provider actions are gated by feature state. The WiX schedule uses conditions such as selected feature equals local install. The C++ provider contract and robustness guard tests verify that unchecked providers do not leak into the selected action plan.

The specific rollback-cache repair

The current MSI includes a custom action named:

RunRepairMsiRollbackCache

It calls:

axiowl-installer-silent.exe install-step msi-rollback-cache-repair

The custom action runs elevated, is scheduled for non-remove operations, and runs before InstallFinalize. Its progress text is:

Repairing Windows Installer rollback cache permissions

In the installer helper implementation, that step checks C:\Config.Msi, the Windows Installer rollback cache folder. If the folder is absent, AxiOwl logs that the repair was skipped. If it exists, the helper uses Windows system tools to take ownership for Administrators, enable inheritance, and grant full control to SYSTEM and Administrators. The log markers include MSI_ROLLBACK_CACHE_REPAIR_BEGIN, MSI_ROLLBACK_CACHE_REPAIR_SKIPPED, and MSI_ROLLBACK_CACHE_REPAIR_END.

This is narrow repair work. It is not a general system cleanup tool. It exists so Windows Installer can complete its own rollback/finalization path when rollback-cache permissions are in a bad state.

Cursor repair has its own rollback safety

Cursor is a good example of why AxiOwl repair is not just "copy files again." Cursor support can involve extension install, MCP config, a submit patch, and discovery. The installer schedules Cursor-specific rollback actions around those mutations:

RunCursorRollbackRestore
RunCursorPreflight
RunCleanupCursor
RunInstallCursorExtension
RunInstallCursorMcp
RunCursorMcpHostPatchElevated
RunInstallCursorDiscovery
RunCursorRollbackCommit

The helper has commands for rollback-cursor and commit-cursor. If a Cursor mutation needs to be backed out, the restore path can put saved Cursor MCP config, extension folder state, and patch target files back from AxiOwl's snapshot area. Once the Cursor install path succeeds, the commit step records that the snapshot is no longer needed for rollback.

That behavior is deliberately scoped to Cursor-owned AxiOwl integration work. The installer docs say it should not remove Cursor user chats, unrelated extensions, provider auth, or unrelated settings.

Repair is logged, not guessed

For AxiOwl support, "the installer finished" is only one event. It does not prove that every provider message path works.

The support docs separate these states:

MSI install succeeded
accepted_by_axiowl
provider accepted
MCP reply received

Repair should be diagnosed with that same discipline. First collect installer and runtime evidence:

%LOCALAPPDATA%\AxiOwl\logs
%LOCALAPPDATA%\AxiOwl\registry
%LOCALAPPDATA%\AxiOwl\runtime

For MSI-level issues, collect a verbose Windows Installer log:

msiexec /i path\to\axiowl-activation-windows-installer.msi /l*v install.log

Then check which provider checkboxes were selected, whether the selected provider is actually installed on the machine, whether the installer closed only the selected or required apps, whether payload hashes match the manifest, and whether helper custom actions failed or were skipped.

Build guards make repair behavior harder to regress

AxiOwl's repair behavior is backed by build-time checks, not only by developer intent.

The MSI build script forbids -SkipBuild, restores the WiX toolchain, runs native build and tests, stages payloads, rebuilds the MSI, decompiles or inspects the rebuilt artifact, and writes proof under release\axiowl-activation-build-preflight.json. The reviewed proof file records artifact_verified, package version 2.0.30, WiX 5.0.2, payload hashes, source validation, WiX validation, artifact size, and artifact SHA-256.

The robustness guard checks several installer properties that matter for repair:

The provider contract tests also verify that selected and unchecked feature derivation works as intended. In one test, selected VS Code features produce coordinator actions, while an unchecked Codex provider must not leak into the selected feature list.

What repair is meant to give operators

AxiOwl installer repair is valuable because provider integrations are stateful. A developer machine can have stale bridge folders, old MCP config, outdated provider paths, a partially applied patch, or a Windows Installer cache permission problem. A repair run should give the operator a way to reapply AxiOwl-owned setup while preserving user data and respecting the selected provider boundary.

The operator value is not that repair magically proves every agent path. It does not. The value is that repair narrows the problem. After repair, the next question can be specific: did the selected feature action run, did discovery write current registry rows, did the provider expose the MCP tools, and did an end-to-end reply arrive?

Closing

AxiOwl's installer repair is best understood as controlled reapplication of AxiOwl-owned runtime and selected provider integration state. It repairs what the MSI and installer helper are responsible for, logs what happened, avoids unrelated user/provider data, and leaves end-to-end provider validation as a separate proof step.

That model fits the way AxiOwl actually works: one local runtime, multiple provider surfaces, provider-specific install units, loud logs, and a strict distinction between "installed" and "ready to send and receive through a real agent path."

Tagged , , , , , , , , ,