Decide which paths can be locked

tovio lock refuses a path that policy has not declared lockable, with TVO-LOCK-003. That refusal is not an oversight — it is the mechanism that keeps locking rare.

Lockability is opt-in per pattern

The repository's policy manifest carries lockable declarations: a path glob plus a kind, exclusive or advisory. A path matching no declaration is not lockable at all. Where several declarations match, the most specific one wins, by the same specificity ranking the read and write policies use.

These declarations are a manifest field. There is no tovio policy verb for them yet, so today they are authored in the manifest itself rather than set from the CLI — worth knowing before you go looking for a command that does not exist.

What to declare

Why locking text is a mistake

TOVIO's default is optimistic: conflicts are data and work is never blocked. That model assumes a merge exists. For a 200 MB checkpoint it does not — two divergent edits cannot be reconciled and the later writer's work is simply lost, so a pessimistic lock is the right tool.

Declaring a text path exclusive re-introduces exactly the serialization TOVIO exists to avoid. People queue behind each other for a file three-way merge would have handled silently.

What an exclusive declaration changes at land time

This is the part that catches people out, because it takes effect whether or not anyone holds a lock.

A path declared lockable = exclusive is never folded into a conflict object. If it was edited divergently on both sides, the land is refused with TVO-LOCK-002 rather than producing a conflict to resolve, because resolving a binary conflict is not a thing you can do. The remedy is to keep one side's version, land, and have the other writer re-apply their edit under an exclusive lock.

The same refusal fires when a change rebase, split, or absorb leaves a conflict on such a path.

An advisory declaration changes none of this. Advisory paths keep the ordinary optimistic conflict model; the lock is a visibility signal, and a conflicting writer is warned rather than blocked.

Choosing between the two kinds

• Declare exclusive when concurrent edits genuinely destroy work. Accept that a divergence becomes a refusal.
• Declare advisory when you want coordination visibility without serializing anyone. Agents default to advisory leases for this reason.

Locks never restrict reading

A lock governs modification only. It has no effect on clone, fetch, or read, and it is entirely orthogonal to the cryptographic read-permission model — a path can be lockable and unencrypted, encrypted and unlockable, both, or neither.