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.
Prerequisites
Section titled “Prerequisites”- A registered vault (see store and read).
- A terminal in the vault's repository, or
--vault <name>for another one.
Run the check
Section titled “Run the check”vaultfold doctorThe 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
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.
vaultfold doctor --jsonFix what it can
Section titled “Fix what it can”--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.
vaultfold doctor --fixLook at the daemon directly
Section titled “Look at the daemon directly”vaultfold agent statusvaultfold versionIf 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.
Current limitations
Section titled “Current limitations”- Vault commands start the agent daemon and unlock once.
doctornever starts one; with no daemon it reports that vault commands will start one when needed. SetVAULTFOLD_NO_AGENT=1to 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.
--fixrepairs repository hygiene only; it does not change vault contents.