A lease says who

[VeryComplexAndLongName]

A workspace lease records a host kind, a hostname and a pid. Two people
on one machine cannot tell whose run holds it, and the only way to ask
who does was to try to start a run and read the refusal.

The lease says who took it

WorkspaceLeaseDocument gains an optional git identity — user.email,
falling back to user.name.

Attribution, never authentication. Anybody can set that value to
anything. The failure mode of recording it is not that it is wrong; it
is that a later reader treats a self-declared label as an audit trail.
So it is called "git author" wherever it is shown, never "user", and
nothing is permitted or refused on the strength of it.

It is read once, where a host starts up — the CLI run, the
standalone server's recovery service, the extension's activation — and
never inside acquireOrRenew, which runs every five seconds while a run
is active for a value that cannot change mid-run.

A lease taken where no identity is configured is valid and records none,
exactly like every lease written before this existed.

Asking who holds a workspace

openspec-ui-cli lease [--format text|json]

Exits 0 held or free: the question was answered either way, and a
script asking "is it free" should read the output rather than infer it
from a failure code.

Clearing one

openspec-ui-cli lease release

There is deliberately no --force, and working out why shaped this
change.

A holder that died stops renewing, and the next acquirer reclaims
the lease on its own once the heartbeat is stale. That case already
heals.

A holder that is alive and still renewing has the workspace open. It
may be stuck, but taking its lease would let a second mutating run start
against files the first still holds — the exact thing the lease exists
to prevent. A stuck holder is stopped, not robbed.

So release clears only where it can establish the holder is gone: the
heartbeat is already stale, or the holder is on this machine and its pid
is not running. process.kill(pid, 0) answers the second without
signalling anything. A holder on another machine cannot be checked from
here at all, and the refusal says so rather than guessing. Exits 0
cleared, 1 refused, 2 could not look.

Verification

npm run verify — exit 0. Typecheck and lint clean across all five
packages; tests cli 107, core 1075, vscode 327, server 80, webui 379 —
1968 across 155 files, 0 failed. openspec validate --strict --changes
passes.

A live smoke found the backward-compatible path for real: the workspace
was held by a VS Code extension built before this change, so its lease
carries no identity. lease described it (exit 0) with no git author
line; lease release refused it (exit 1) because its pid was running.
What that did not show is a lease written by this build, which is what
the change's one delegated item covers.

Change: openspec/changes/a-lease-says-who/

🤖 Generated with Claude Code