Skip to content

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 holding agent.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_SOCK keeps 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 stop stops a daemon that holds this profile's lock but serves another endpoint, through the endpoint its agent.pid names. 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_HOME alone 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, doctor reports daemon-elsewhere naming the old pipe, and vaultfold agent stop stops 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_HOME instead of the runtime directory. Rejected: the runtime directory is what identifies an instance (it holds the lock), and without VAULTFOLD_HOME there 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.