0035: One agent daemon pipe per profile on Windows
- Status: accepted
- Date: 2026-10-07
- Amends: 0028 (the Windows bullet of "Local transport": the pipe name)
Context
ADR 0028 put the daemon's Windows endpoint at
\\.\pipe\vaultfold-agent-<user SID>. On unix the socket is
<runtime>/agent.sock, in the same per-profile runtime directory as the
instance lock agent.lock, so each profile (each VAULTFOLD_HOME) gets
its own daemon. On Windows the pipe ignores the profile while the lock
does not: two profiles share one pipe, the first daemon to start answers
for both with its own configuration and vaults, and the other profile's
daemon cannot listen. Tests, which give every case its own temporary
VAULTFOLD_HOME, worked around it by setting an explicit
VAULTFOLD_AGENT_SOCK pipe, and an explicit endpoint disables auto-start
and the in-process fallback; make check-windows found 30 test failures
from this (agentboard ticket 01M4BKSMG1T64NQEXBQ5GY272Z). The OpenSpec
change windows-per-profile-endpoint holds the details.
Decision
- The Windows default pipe is
\\.\pipe\vaultfold-agent-<SID>-<hash>, where<hash>is the first 16 lowercase hex characters of the SHA-256 of the profile's runtime directory (the directory holdingagent.lock), after replacing/with\, dropping trailing separators (a bare drive root keeps its\) and lowercasing. The path is not resolved against the file system, so the computation stays pure and the native host can mirror it exactly. - The SID stays in the name: the DACL
D:P(A;;GA;;;<SID>)(A;;GA;;;SY)is keyed to it, and it keeps users apart in the pipe namespace. The DACL, first-instance exclusivity, remote-client rejection and peer SID checks are unchanged. VAULTFOLD_AGENT_SOCKkeeps its meaning: an explicit endpoint, never rewritten; one that does not answer is exit 3 with nothing started.- The browser native host mirrors the rule, including
profile.ResolvePaths' Windows runtime directory. vaultfold agent stopstops a daemon that holds this profile's lock but serves another endpoint, through the endpoint itsagent.pidnames. This is the migration path for a daemon still on the old name.
Consequences
- One daemon per profile on every OS (with the existing unix exception that the long-path fallback socket is per user).
- Windows tests isolate daemons with
VAULTFOLD_HOMEalone and exercise auto-start and fallback like unix. - After upgrading, a daemon started by an older vaultfold is not found by
the new CLI or native host. Commands fall back to in-process unlock
with the usual notice,
doctorreportsdaemon-elsewherenaming the old pipe, andvaultfold agent stopstops it. Windows has had no release, so this affects developers and testers only. - Two spellings of one directory that only the file system equates
(junctions,
subst, 8.3 names) give two pipe names over one lock; the second auto-start fails on the lock and its commands fall back in-process. Separator and case normalisation covers the common cases.
Alternatives considered
- Keep one pipe per user and isolate tests some other way (a test-only, non-explicit pipe suffix). Rejected: it fixes the tests but leaves real profiles sharing one daemon with the wrong configuration.
- Hash
VAULTFOLD_HOMEinstead of the runtime directory. Rejected: the runtime directory is what identifies an instance (it holds the lock), and withoutVAULTFOLD_HOMEthere would be nothing to hash. - Put the path itself in the pipe name. Rejected:
\is not allowed in a pipe name, so it needs escaping, it can approach the 256-character limit, and it would publish the profile path, which usually contains the user name, in a namespace any local user can list. - Probe the old name on every command for compatibility. Rejected: an extra dial on every command forever for a migration that affects only pre-release builds, when the fallback is already safe.