Skip to content

Distinguish install path shape from ownership conflicts - #517

Open
esseener wants to merge 1 commit into
higress-group:mainfrom
esseener:fix/specific-install-path-error-codes
Open

esseener wants to merge 1 commit into
higress-group:mainfrom
esseener:fix/specific-install-path-error-codes

Conversation

@esseener

@esseener esseener commented Nov 18, 2026 •

Copy link
Copy Markdown

What breaks

invalid() returns INSTALL_OWNERSHIP_CONFLICT for every package and destination refusal, not only ownership ones. regular() refuses a reparse point or symlink in any ancestor of a destination — it is the single admission point for every destination and every source read — but it reports that refusal with the ownership code.

The installer diagnostic is the only thing a user sees, and it deliberately prints just the step, the shareable code and the I/O kind, because raw error text can carry paths or localized native text. So the report cannot distinguish:

  • a junction or symlink above a destination,
  • a destination that exists but is not a regular file,
  • a genuine admitted-byte conflict.

All three read Code: INSTALL_OWNERSHIP_CONFLICT, Operation: plan-installed-files, I/O kind: InvalidData.

How it shows up

The transaction writes the Agent skill record under both ~/.agents and ~/.claude. An account that keeps ~/.claude/skills as a junction onto another drive — a common Windows layout — therefore cannot install at all, and every retry ends at plan-installed-files with the same ownership text. Nothing in the report points at a path, and renaming the installation directories, taking ownership of them, or rerunning the installer does not change the outcome.

Change

Give the two path-shape refusals their own codes:

case before after
reparse point or symlink in an ancestor INSTALL_OWNERSHIP_CONFLICT INSTALL_PATH_REPARSE_UNSUPPORTED
destination is not a regular file INSTALL_OWNERSHIP_CONFLICT INSTALL_PATH_NOT_REGULAR_FILE

Both are added to the code list in crates/cli/src/service/windows/install.rs, so the JSON code carries them instead of collapsing to INSTALL_FAILED.

The security behaviour is unchanged: those paths are still refused, invalid() still covers byte conflicts, and the error kind stays InvalidData. Only the shareable code changes.

docs/standalone-windows.md now names the destinations the transaction writes, shows how to inspect them, and says what to do when one of them is a link.

Testing

  • cargo fmt --all -- --check — clean.
  • cargo test --locked -p hiroute-host-runtime --lib on Windows 11 x64 — 61 passed, 0 failed.
  • New unit tests in crates/host-runtime/src/standalone_install/files.rs: a symlinked ancestor and a non-regular target each keep their own code, and an absent path still admits. The two path-shape tests are #[cfg(unix)] because creating a junction in a test needs a privilege Windows CI does not have, so Linux CI is their first run.
  • Reproduced the failure this change describes on Windows 11 x64: with ~/.claude/skills as a junction, hiroute __windows-install --request-stdin stops at plan-installed-files with I/O kind: InvalidData and the ownership text; with the junction replaced by a real directory the same package installs and service doctor reports five of five checks healthy.

Scope of verification: the hiroute CLI binary does not build on this machine because its build script requires cmake, so I did not execute the post-change failure end to end. The unit tests cover regular(), and the code list change is a literal addition of the two strings the CLI matches against.

@esseener
esseener requested a review from johnlanni as a code owner November 18, 2026 15:17
@CLAassistant

Copy link
Copy Markdown

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
You have signed the CLA already but the status is still pending? Let us recheck it.

`invalid()` compresses every package and destination refusal into
`INSTALL_OWNERSHIP_CONFLICT`. The shareable installer diagnostic prints only
the step, the code and the I/O kind, so a machine whose install path contains a
junction or symbolic link reports the same text as a genuine admitted-byte
conflict and leaves no way to tell them apart.

`regular()` is the single admission point for every destination and source, and
it already refuses reparse-point and symlinked ancestors by design. Give that
refusal its own code, and give the non-regular target case one as well, so
`plan-installed-files` names the shape instead of the conflict.

A common Windows layout triggers this: an account that keeps `~/.claude/skills`
as a junction onto another drive cannot install, and every retry repeats the
same ownership text. The Windows guide now says which destinations the
transaction writes and how to inspect them before running the installer.

Signed-off-by: esseener <28524448+esseener@users.noreply.github.com>
@esseener
esseener force-pushed the fix/specific-install-path-error-codes branch from f7bde0e to fac6d37 Compare November 18, 2026 15:32

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants