[aicayzer]

Summary

marfa folders autostart on --key-file <path> makes the login agent run the folder watch with a key file in place of the keychain, so a machine where nobody signs in to unlock the keychain can keep folders in step without raising a dialog. Without the option nothing changes. marfa folders watch --key-file is the same thing for a watch started by hand or by a script.

Closes #2313

Changes

• Design choice the issue left open. The file may live anywhere its owner chooses, because a fixed location would be a second mechanism beside MARFA_API_URL and MARFA_API_KEY. The rules are on the file, not the place: it must exist, be a regular file with one name (no hard link, which could put a second name inside a folder), not be a symbolic link, belong to the user running the command, be unreadable by group and others (mode 600 or stricter), hold a MARFA_API_URL line that is a server address and a MARFA_API_KEY line, and lie outside every folder the registry lists (and outside the folder being watched), because a key inside a synced folder would be sent to the server as one of its files. A fault exits 1 with invalid, names the file and the reason, and never prints a value.
• What the key may reach is the key's own permission set. A key limited to the types the folder carries is the intended use; the command does not check the key's scope.
• The agent holds the file's path only (folders watch --key-file <path> --log <log>), never the address or key, and the watch reads and checks the file again each time it opens a folder, so a key rotated in the file is the one used at the next open, and a file that has become unsafe, or lies inside a folder added since, is refused for that folder alone while the others go on. A watch of one directory reads it at its start. autostart on checks the file first and writes nothing if it is refused.
• A watch with a key file uses it for each folder of that server and reads the keychain for none: a folder of another server is reported as having no credential and never receives the key.
• autostart on run again without the option replaces the agent and goes back to the keychain; run again with the same file it changes nothing. autostart status and the on report show key_file.
• Contract: folders/autostart-key-file, folders/autostart-key-file-refused, folders/watch-key-file, with autostart-no-credential and autostart-status amended. The command reference is regenerated.

Testing

• cargo test -p marfa-cli, cargo clippy -p marfa-cli --all-targets -- -D warnings, cargo fmt --check and pnpm format:check pass.
• Unit tests for the file's rules (modes 640, 604, 644 and 660 refused with owner-only as the witness; link; missing names; quotes, export, comments) and for the agent file (the path is there, no address, key or --key is).
• Four device fixtures in folders-autostart.test.ts. They run the real agent through the stand-in service manager and a scripted server: the key from the file reaches the server and is the only credential sent, with a keychain that holds nothing and cannot be asked; a folder of another server never receives it; every refusal writes no agent. They fail with the marfa build from main. The inside-a-folder fixture caught a first version that listed the registry through a call that also rewrites it; it now reads the file without writing.
• The 'reads the keychain for no folder' fixture (macOS) fails when credentials::turn_off() is removed and holds a keychain credential for the folder's server as its witness.
• Not tested: a key rotated while the watch runs (traced in code, no fixture), a key file owned by another user (needs root), Linux (the fixtures ran on macOS with launchd), and a real login with no unlocked keychain.

Notes for reviewers

• The docs pages for the CLI ("Use another keychain file") and "Keep folders running" are in the docs repository and are updated after this merges.
• Review depth: a withmarfa-reviewer read the whole change, since it handles a credential at rest. It found nine problems, all fixed in the second commit: a hard link and a later-added folder getting past the location check, a rotated key never being picked up, an unreadable registry stopping the watch, a named pipe hanging the command, wrong keychain advice in the status, two tests without a witness, two contract statements left untrue, an address that is no server address, and an unquoted path in the chmod advice.

Checklist

• The title is a scoped Conventional Commit.
• New behavior has a test that was seen failing first, or no test was needed and the reason is above.
• Docs, comments and the contract still say what is true after this change.