install: Hermes agent_config fails on Windows (content-independent), aborting PATH registration

[limeflash]

Summary

On Windows, install fails for the Hermes agent with two agent_config errors. Because agent-config failures abort activation, the whole install exits 1 and PATH registration / index cleanup are skipped — even though the other 10 detected agents are configured successfully.

The failure is independent of the config file's contents and independent of the directory ACL. A 26-byte YAML reproduces it exactly.

Environment

• codebase-memory-mcp 0.10.5, build f8aee1683f94f7598ae70640a588f27d51811433f046b39c1faf186c17010739
• Windows 11 Pro 10.0.28000, amd64
• Installed via the documented one-liner (install.ps1)
• Detected agents: Claude-Code Codex Gemini-CLI OpenCode Antigravity VS-Code Cursor Hermes Warp Kimi Code CLI

Observed output

error: agent_config agent=Hermes op=mcp_install path=C:\Users\<user>\AppData\Local\hermes/config.yaml (target: regular file, 16888 bytes)
error: agent_config agent=Hermes op=pre_llm_hook_install path=C:\Users\<user>\AppData\Local\hermes/config.yaml (target: regular file, 16888 bytes)
error: one or more agent configurations failed; the published/current executable was kept, and PATH/index cleanup was not attempted
error: activation stopped after one or more agent configuration or cleanup operations failed; the published/current executable was kept, and configuration changes that completed may remain.

No further detail is given for why the two ops failed — the message reports the target's type and size only.

Minimal reproduction

Only config.yaml needs to exist; no other Hermes files are required.

New-Item -ItemType Directory -Force "$env:LOCALAPPDATA\hermes" | Out-Null
"model:`n  default: test`n" | Set-Content "$env:LOCALAPPDATA\hermes\config.yaml" -Encoding UTF8
codebase-memory-mcp install -y --force --dir="$env:LOCALAPPDATA\Programs\codebase-memory-mcp"
# exit code 1, same two agent_config errors (now reporting "26 bytes")

Control — remove that directory and re-run the identical command:

exit code: 0    # no errors; PATH registration then completes normally

What I ruled out

Hypothesis	Test	Result
YAML shape — no mcp_servers: key / hooks: {} is an empty flow mapping	Replaced the real 660-line config with a 26-byte model:\n default: test	Still fails — content-independent
Directory ACL (per the acl-grants-cross-account-mutation note in install.ps1)	Applied a protected owner-only DACL to %LOCALAPPDATA%\hermes before re-running	Still fails — not the ACL
Hermes running / file locked	No Hermes process; file freshly written and readable/writable, not read-only	Not a lock

For the record, the real config does contain a hooks: key and an mcp: key, so "missing section" is not the trigger either — and neither is needed to reproduce.

Possible lead: path separators

Hermes is the only agent whose path is logged with mixed separators:

Hermes:      C:\Users\<user>\AppData\Local\hermes/config.yaml     <-- backslashes + forward slash
Claude Code: C:/Users/<user>/.claude.json                          <-- normalized
Codex:       C:/Users/<user>/.codex/config.toml                    <-- normalized
Cursor:      C:/Users/<user>/.cursor/mcp.json                      <-- normalized

This looks like %LOCALAPPDATA% (which carries backslashes) is concatenated with a hard-coded /config.yaml without normalization, whereas the other handlers normalize. If a downstream step (atomic temp-write + rename, or a path validation/containment check) is separator-sensitive, that would explain a content-independent failure confined to this one agent.

Interestingly, the Hermes skill write to a path built the same way does succeed (...\hermes/skills/codebase-memory/SKILL.md (1 installed)), so if it is the path, only the mcp_install / pre_llm_hook_install writers are affected.

Suggested fixes

1. Normalize the Hermes config path the way the other agent handlers do.
2. Surface the underlying error in the agent_config message (errno / exception), instead of only the target type and size — this was undiagnosable from the output alone.
3. Consider not failing the whole activation when a single optional agent's config fails. Skipping PATH registration because one of eleven agents could not be written leaves an otherwise-good install half-finished, and the user has to set PATH by hand.

Happy to run any further diagnostics on this machine — the reproduction is deterministic.

[DeusData]

Thank you — this is an unusually well-isolated report. Ruling out the content and the ACL before filing, with a 26-byte reproduction and a control, is most of the work.

First, what I could confirm and what it rules out. I ran your exact minimal file on macOS:

before: 23 bytes  ->  after: 502 bytes, 4 codebase-memory entries written

So a config.yaml with no MCP section at all is fine — we create the section rather than requiring it. Combined with your two results, that removes the obvious hypotheses: it is not the content, not the size, not a missing key, and not the ACL. It is Windows-specific.

The lead. Our YAML writer replaces the file atomically, and it takes two different Win32 calls depending on one condition:

BOOL replaced = destination_exists
    ? ReplaceFileW(wide_path, wide_temp, NULL, REPLACEFILE_WRITE_THROUGH, NULL, NULL)
    : MoveFileExW(wide_temp, wide_path, MOVEFILE_WRITE_THROUGH);

ReplaceFileW is used only when the target file already exists. Every other agent we configured on your machine may well have been the create case, taking MoveFileExW, while Hermes is the one whose config.yaml was already there — which would explain why 10 agents succeeded and this one did not, with no dependence on what is inside the file.

One test would confirm or kill that, and it is quick:

# keep the directory (so Hermes is still detected), remove only the file
Remove-Item "$env:LOCALAPPDATA\hermes\config.yaml"
codebase-memory-mcp install -y --force --dir="$env:LOCALAPPDATA\Programs\codebase-memory-mcp"

If that succeeds, the fault is ReplaceFileW on your host and we fix the replace path. If it still fails, the fault is earlier — in opening or creating the temp file beside the target — and that is a different fix. Either answer is decisive.

Your removal control deleted the whole directory, which also makes Hermes undetected, so it could not separate those two.

On the missing explanation — you are right that the message gives the target's type and size and nothing about why. That is a real gap and it is being closed separately: the config editors are being taught to carry a stable refusal reason out to the error line, so this would read something like reason=atomic_replace_failed instead of leaving you to guess. Your report is a good argument for prioritising it.

One more thing worth flagging: a single agent failing aborts the whole activation, so PATH registration is skipped even though 10 of 11 agents configured correctly. That is arguably the more serious half of what you found, and it is a separate question from the Hermes bug itself.