fix(hermesagent): follow the platform default profile root and stabilize the shared-file key

[dyoshikawa]

Part of #2439 (findings 1, 2, 5, 9, 10) — the refactor bundle the maintainer asked for, with finding 5 falling out of it. Findings 3, 4, 6, 7, 8 follow in a separate PR.

Finding 1 (mid) — Windows default profile root

Upstream _get_platform_default_hermes_home() returns %LOCALAPPDATA%\hermes on win32 and ~/.hermes only elsewhere, but getHermesagentHome() fell back to ~/.hermes on every platform, so a global generate on native Windows with HERMES_HOME unset wrote where Hermes never reads.

getHermesagentRelativeDirPath now strips the canonical .hermes prefix and re-anchors it: nothing is prepended when HERMES_HOME is set (it is the profile root itself), otherwise the platform default from the new getHermesagentGlobalDir() takes its place. The path constants stay canonical, so this is one funnel rather than a de-prefixing of every constant. docs/reference/supported-tools.md loses the sentence claiming "the default remains ~/.hermes".

Finding 2 (mid) — env-dependent shared-file key

sharedFileKey() collapsed to a bare config.yaml whenever HERMES_HOME was set, while writers passed the constant .hermes/config.yaml — so the ownership lock-step guard and the shared-file contract test went blind in exactly the configuration this feature is about (reproducible before this PR with HERMES_HOME=/tmp/x npx vitest run src/features/shared/shared-config-gateway.test.ts).

Rather than make the writers' key env-dependent too, all five Hermes writers of config.yaml (commands, subagents, mcp, hooks, permissions) now declare every spelling the profile root can take through getExtraSharedWritePaths — .hermes/, AppData/Local/hermes/, and the root itself — so the derived key set is identical on every platform and with or without HERMES_HOME. SHARED_CONFIG_OWNERSHIP declares all three with the same policies. This is the shape #2450 used for the two Zed global paths.

Finding 9 (low) — env-derived outputRoot bypassed validation

resolveToolOutputRoot now runs validateOutputRoot on a substituted home override, so HERMES_HOME=/ is rejected instead of becoming the output root. Closes the same pre-existing hole for KIMI_CODE_HOME.

Finding 10 (low) — weak de-prefix guard

The guard rejected only an exact .., a ..-prefix, and absolute paths. It now uses checkPathTraversal on both the input and the de-prefixed result — checking both matters because relative() normalizes .. away, so a path that walks out of .hermes and back in would pass a check on the result alone.

Finding 5 (low) — hermetic tests, resolved as a side effect

HERMES_HOME and KIMI_CODE_HOME are cleared in vitest.config.ts before any test module loads. They have to be neutralized at that level rather than in a beforeEach, because the shared-write derivation runs at module load. Verified: HERMES_HOME=/tmp/x KIMI_CODE_HOME=/tmp/y npx vitest run over the previously-affected specs (hermesagent-mcp, hermesagent-skill, hermesagent-subagent, shared-config-gateway, shared-file-contract, utils/hermesagent) is green, where it produced 12 failures before.

Tests

New unit coverage for the platform default, the traversal guard, and the env-independence of the declared write paths. E2E specs now derive Hermes global paths from getHermesagentGlobalDir() instead of hardcoding .hermes, which is what makes the win32 default observable on the windows-latest E2E run. Full pnpm cicheck is green, as are every Hermes-touching e2e spec locally (mcp, hooks, permissions, commands, subagents, skills, checks, ignore, hermesagent-home).

🤖 Generated with Claude Code