Repo locks
The four repo lock tools - declare a lock on a repository's refs once, then hold it with a lease while landing changes, so landings happen one at a time.
On this page
A repo lock guards a repository's refs, so agents on several machines land changes one at a time (how repo locks work). These tools belong to the Repo locks optional feature, off by default: while it is off they are neither listed nor callable.
Naming the repository
A lock has no project, so these tools take none. They name the repository by
its checkout, with the arguments session_start takes: cwd, host,
repo_root, main_worktree_root and repo_origin. The daemon reads the
checkout's git identity from cwd only on its own machine with peer_auth off;
from anywhere else, send repo_root (and main_worktree_root, repo_origin)
resolved on the checkout's own machine. seam lock always does.
locks_acquire and locks_release also take a lock's id (from locks_list
or locks_declare) in place of the checkout and the name.
What an answer shows
A lock answers with its label (the repository and the name), its refs, its
state (active, or requested for a declaration waiting for the owner),
whether it is held, since and until for a hold, its aliases and its
projects. A holder is named (holder, holder_session) only to a caller who
may read that session; a project is listed only where the caller may list it.
Every lock also answers with:
held_by_caller- true when the lock is held, and by the session this connection is bound to: by the agent-process identity its requests carry, or by asession_starton it. A connection bound to no session reads false, whatever session an unbound call would act as.waiting- how many sessions wait for the lock.next_waiter_session- the session first in the queue, only where the caller may read that session (as for the holder).
locks_list adds caller_bound beside locks: whether this connection is
bound to an active session at all, the same binding held_by_caller reads.
A restricted account sees no aliases (the
list is empty), and no caller sees the aliases of a lock a restricted account
declared. A lock a restricted account may not reach is not listed for it, and
by id, by checkout or through locks_declare it reads exactly as a lock that
does not exist.
Waiting for a lock
locks_acquire with wait: true joins the lock's queue when the lock cannot
be yours now, or keeps your place in it, and answers acquired: false,
queued: true, your position (1 is next) and place_until, when your place
lapses unless you ask again. Ask again within two minutes to keep the place;
seam lock acquire --wait does so every few seconds. While anyone waits, only
the session first in the queue takes the lock; anyone else's acquire is
refused with the next waiter and their own place. A locks_release from a
session that waits and does not hold the lock leaves the queue and answers
released: false, left_queue: true.
A declaration from a conversation that may not write the global scope (bound
to a confidential project, or confined by isolation.requests) is refused in
the fence's own words, and such a conversation's locks_acquire records no new
repository identity on the lock.
locks_list
List repo locks: each lock's repository and name, the refs it guards, whether it is held, by which session (when you may see that session), since and until when, whether you hold it, how many sessions wait for it and which is next, the repository identities that resolve to it, and the projects whose restricted accounts the declaration lists. Pass a checkout's identity (cwd, or repo_root and repo_origin) to list only that repository's locks. A declaration waiting for the owner's approval is listed with state requested. Read-only.
Optional - part of Repo locks, hidden when the repo_locks feature is disabled: the tool leaves tools/list and a call to it is refused as an unknown tool, while its stored data stays exactly where it was. See Optional features.
| Parameter | Type | Required | Description |
|---|---|---|---|
cwd |
string | no | Absolute working directory inside the repository's checkout. The daemon reads the checkout's git identity from it only on its own machine with peer_auth off; otherwise pass repo_root (and main_worktree_root, repo_origin) resolved on your machine. seam lock sends all of them |
host |
string | no | Machine the checkout is on (hostname). Defaults to the X-Seamless-Host header, then to the daemon's own host |
main_worktree_root |
string | no | Absolute root of the repository's MAIN checkout when repo_root is a linked worktree; defaults to repo_root |
repo_origin |
string | no | The repository's origin remote URL: the key a lock is found by from every machine, so the ssh and https forms of one repository are one lock. A side clone whose origin is a local path is the repository at that path |
repo_root |
string | no | Absolute root of the checkout, resolved on its own machine |
session |
string | no | the session to act as: the name session_start returned, the cc/<id> or cx/<id> on your briefing's 'Seam session' line, or a session ULID. It scopes and credits this call. Defaults to this connection's session; pass it on every call when session_start reports the connection as stateless |
locks_declare
Declare a lock on a repository's refs, once per repository and name: the lock agents hold while they land changes, so landings happen one at a time across machines. Name the repository by its checkout (cwd, or repo_root, main_worktree_root and repo_origin): its origin URL is the key, so the ssh and https forms of one repository are one lock, and a repository with no origin is locked by host and path. Declaring again, from any project or machine, returns the existing lock unchanged and records this checkout's identity on it, so a repository that gains or changes its origin keeps its lock. A restricted account's declaration waits for the owner's approval on the console. refs defaults to refs/heads/<name>; projects, the projects whose restricted accounts may hold the lock, defaults to the project the checkout maps to.
Optional - part of Repo locks, hidden when the repo_locks feature is disabled: the tool leaves tools/list and a call to it is refused as an unknown tool, while its stored data stays exactly where it was. See Optional features.
| Parameter | Type | Required | Description |
|---|---|---|---|
cwd |
string | no | Absolute working directory inside the repository's checkout. The daemon reads the checkout's git identity from it only on its own machine with peer_auth off; otherwise pass repo_root (and main_worktree_root, repo_origin) resolved on your machine. seam lock sends all of them |
host |
string | no | Machine the checkout is on (hostname). Defaults to the X-Seamless-Host header, then to the daemon's own host |
main_worktree_root |
string | no | Absolute root of the repository's MAIN checkout when repo_root is a linked worktree; defaults to repo_root |
name |
string | no | The lock's name on its repository, a token: main (the default), release. A line naming a lock shows its repository and its name: LOCK seamless main |
projects |
array | no | Project slugs whose restricted accounts may hold the lock (a comma-separated string is also accepted). Defaults to the project the checkout maps to |
refs |
array | no | The guarded refs: full ref names (refs/heads/main) or patterns with one '' (refs/tags/v), at most 16 (a comma-separated string is also accepted). Defaults to refs/heads/<name> |
repo_origin |
string | no | The repository's origin remote URL: the key a lock is found by from every machine, so the ssh and https forms of one repository are one lock. A side clone whose origin is a local path is the repository at that path |
repo_root |
string | no | Absolute root of the checkout, resolved on its own machine |
session |
string | no | the acting agent's session: the cc/<id> or cx/<id> on your briefing's 'Seam session' line, another session name, or a session ULID. Defaults to this connection's session -- bound automatically for Claude Code and Codex agents -- then a sole active ambient. Pass it when a call reports the agent as ambiguous: the bare call then fails rather than guesses. |
session_id |
string | no | the acting agent's session ULID; takes precedence over session and the bound session |
locks_acquire
Take a repo lock for the current session, with a lease, before landing changes on the refs it guards. Re-acquiring a lock you hold refreshes the lease: the heartbeat for a long landing. A lock another session holds under a live lease is refused, naming the holder when you may see that session, since and until; a lapsed lease is taken over. Sessions waiting for a lock take it first come, first served: while any wait, only the next one may take it, and anyone else is refused with the next waiter and their own place. With wait, a refusal joins the queue instead (or keeps your place) and answers queued, with your position; ask again within two minutes to keep the place, or run seam lock acquire --wait in the background, which asks every few seconds and returns once you hold the lock. A declaration still waiting for the owner cannot be held. Name the lock by id, or by the checkout and name (default main). Release it with locks_release once the refs have landed; a hold also lapses at the end of its lease.
Optional - part of Repo locks, hidden when the repo_locks feature is disabled: the tool leaves tools/list and a call to it is refused as an unknown tool, while its stored data stays exactly where it was. See Optional features.
| Parameter | Type | Required | Description |
|---|---|---|---|
cwd |
string | no | Absolute working directory inside the repository's checkout. The daemon reads the checkout's git identity from it only on its own machine with peer_auth off; otherwise pass repo_root (and main_worktree_root, repo_origin) resolved on your machine. seam lock sends all of them |
host |
string | no | Machine the checkout is on (hostname). Defaults to the X-Seamless-Host header, then to the daemon's own host |
id |
string | no | lock id (from locks_list or locks_declare); or name the checkout instead |
lease_seconds |
number | no | lease duration in seconds before the hold lapses (default 900, at most 14400) |
main_worktree_root |
string | no | Absolute root of the repository's MAIN checkout when repo_root is a linked worktree; defaults to repo_root |
name |
string | no | The lock's name on its repository, a token: main (the default), release. A line naming a lock shows its repository and its name: LOCK seamless main |
repo_origin |
string | no | The repository's origin remote URL: the key a lock is found by from every machine, so the ssh and https forms of one repository are one lock. A side clone whose origin is a local path is the repository at that path |
repo_root |
string | no | Absolute root of the checkout, resolved on its own machine |
session |
string | no | the acting agent's session: the cc/<id> or cx/<id> on your briefing's 'Seam session' line, another session name, or a session ULID. Defaults to this connection's session -- bound automatically for Claude Code and Codex agents -- then a sole active ambient. Pass it when a call reports the agent as ambiguous: the bare call then fails rather than guesses. |
session_id |
string | no | the acting agent's session ULID; takes precedence over session and the bound session |
wait |
boolean | no | join the lock's queue, or keep your place in it, when the lock cannot be yours now; the answer is queued with your position instead of a refusal (default false) |
locks_release
Release a repo lock the current session holds, live or lapsed, so another session can take it: the next waiter, when sessions wait for it. A session that waits for the lock and does not hold it leaves the queue instead. Only the holder may release; the owner can force-release any hold from the console. Name the lock by id, or by the checkout and name (default main).
Optional - part of Repo locks, hidden when the repo_locks feature is disabled: the tool leaves tools/list and a call to it is refused as an unknown tool, while its stored data stays exactly where it was. See Optional features.
| Parameter | Type | Required | Description |
|---|---|---|---|
cwd |
string | no | Absolute working directory inside the repository's checkout. The daemon reads the checkout's git identity from it only on its own machine with peer_auth off; otherwise pass repo_root (and main_worktree_root, repo_origin) resolved on your machine. seam lock sends all of them |
host |
string | no | Machine the checkout is on (hostname). Defaults to the X-Seamless-Host header, then to the daemon's own host |
id |
string | no | lock id (from locks_list or locks_acquire); or name the checkout instead |
main_worktree_root |
string | no | Absolute root of the repository's MAIN checkout when repo_root is a linked worktree; defaults to repo_root |
name |
string | no | The lock's name on its repository, a token: main (the default), release. A line naming a lock shows its repository and its name: LOCK seamless main |
repo_origin |
string | no | The repository's origin remote URL: the key a lock is found by from every machine, so the ssh and https forms of one repository are one lock. A side clone whose origin is a local path is the repository at that path |
repo_root |
string | no | Absolute root of the checkout, resolved on its own machine |
session |
string | no | the acting agent's session: the cc/<id> or cx/<id> on your briefing's 'Seam session' line, another session name, or a session ULID. Defaults to this connection's session -- bound automatically for Claude Code and Codex agents -- then a sole active ambient. Pass it when a call reports the agent as ambiguous: the bare call then fails rather than guesses. |
session_id |
string | no | the acting agent's session ULID; takes precedence over session and the bound session |