feat: back up only files agent-sync did not write, doctor checks the agent on PATH, --budget on sync and apply (v1.11.0)

[hibeekaey]

Summary

One PR for every follow-up from the last two, as asked.

• Adoption backups only for files agent-sync did not write. The rule was "first differing overwrite, once", so the first sync that changed the file backed up agent-sync's own earlier output as <file>.orig on every target, and a hand edit made after that was overwritten with no backup, contrary to the README's safety promise. agent-sync now remembers what it wrote to each target under ~/.config/agent-sync/distributed/ and skips the backup while the file is still that; a hand edit still gets one, and revert restores it. Existing .orig files are left alone.
• doctor checks the agent on PATH. Cursor's CLI installer also creates an agent command, so a hook or cron line saying agent sync can start Cursor instead without a word of complaint. A program that is not agent-sync is a problem; another agent-sync build (a checkout beside a brew install) is only noted.
• --budget BYTES on sync and apply, the flag compact already had, validated up front; the README had described it that way already.
• Docs. The man page synopsis lists compact; the target-filter flags are documented for compact; the README passes markdownlint (a ## code span and one long line) and gains a Notes row on the Cursor name clash; the walkthrough is re-captured from this binary in its own order, so the fold makes no backups, the heal after a hand edit does, and revert restores exactly that one; the zsh completion learns --budget on sync and apply.
• VERSION 1.11.0 and the changelog entry: a new flag and a new doctor check make it a minor release.

Left alone on purpose: the deterministic import prints two blank lines between store entries inside an import block. Fixing that changes the block's bytes and therefore every recorded fold fingerprint, which would re-fold every block once at a model call per agent, for a cosmetic gain inside text that the fold removes anyway.

Validation

• make test passes locally. ShellCheck was not run locally (not installed here) and is covered by CI.
• Against the v1.10.0 binary via AGENT_BIN, the amended sync suite fails at agent-sync backed up its own earlier output: .../.codex/AGENTS.md.orig; with this change it passes, and the new doctor cases cover a non-agent-sync agent (problem), this program under that name (nothing) and another agent-sync build (note).
• The colour suite's run_agent_term ran with the ambient PATH; on a machine where agent is Cursor's CLI the new check fired inside the test. It now pins PATH="$SAFE_PATH" like every other runner.
• Walkthrough blocks were re-captured from bin/agent at this commit against throwaway AGENT_SYNC_HOME fixtures with real claude (fable, low) calls, in the document's own order: deterministic sync, fold (no .orig lines), no-op sync, drift, heal (gemini .orig), apply, revert (gemini and the .bak only). docs/agent.1 is regenerated from the .scd with scdoc 1.11.5. markdownlint-cli2 is clean on the README and the walkthrough and adds nothing to the changelog's two pre-existing findings in released entries.
• The weekly compat workflow was dispatched by hand and passed for all five CLIs, so the synthesizer-flag assertions added on 2026-09-04 have now run against the real packages.

🤖 Generated with Claude Code