Skip to content

Check health with doctor

vaultfold doctor is the first thing to run when something looks wrong. It checks the vault, the git repository around it, and the agent daemon setup.

  • A registered vault (see store and read).
  • A terminal in the vault's repository, or --vault <name> for another one.
Terminal window
vaultfold doctor

The first report is the vault: hygiene (the vault is tracked and ignored correctly), integrity, rejected and held events, concurrent values, epochs, rotation reminders, conflict copies, clock and cache. The second report, headed agent daemon, covers the daemon, its endpoint, identities, approval dialogs, lock triggers, callers, the machine key, memory locking and the audit log. Each warning and error carries a remedy.

For a vault in a git repository, the vault report also checks the branch the vault syncs to: sync-branch-protected (the forge's rules block sync; see protect the vault branch), sync-branch-unchecked (gh is missing or not signed in), vault-worktree-layout, vault-worktree-extra-files, vault-moved-to-branch, same-branch-vault, vault-branch-not-recorded and git-in-build-context. Each names its remedy.

In a shared folder, a privilege change (epoch new, a revocation or a grant) that lost its place in the policy chain leaves its key wrap files behind. doctor reports each as stray-wrap, a warning: the file is used for nothing, blocks nothing and needs no action. When the finding ends "the directory is that of a lost record written by ", the name is the author of the lost record the directory belongs to. It does not say who wrote the file: anyone who can write to the folder can put a file there. Until a later record mints the same epoch number, the same files are reported as orphan-wrap, and a file for a device that the later record does not give the epoch to stays orphan-wrap.

doctor exits 2 when either report has an error, and never starts a daemon. For scripts use --json.

Terminal window
vaultfold doctor --json

--fix restores .gitattributes, adds missing ignore rules and removes a .gitignore line that hides the vault. For a vault set up by hand in a worktree it instead switches your registration to branch mode, which is local and loses nothing, and prints the remaining steps; it refuses to do that inside an agent session. See move a vault to its own branch.

Terminal window
vaultfold doctor --fix
Terminal window
vaultfold agent status
vaultfold version

If agent status reports a version mismatch after an upgrade, run vaultfold agent stop so the next command starts the new daemon.

If you have reviewed a rollback warning and the new history is right, record and accept it with vaultfold doctor --accept-rollback.

  • Vault commands start the agent daemon and unlock once. doctor never starts one; with no daemon it reports that vault commands will start one when needed. Set VAULTFOLD_NO_AGENT=1 to stop auto-start and unlock in-process for each command instead.
  • Some warnings depend on the system, for example the macOS approval helper app or a Linux session without a keyring.
  • --fix repairs repository hygiene only; it does not change vault contents.