Sessions: discover the current local brief and lease from a checkout

[jeffhuber]

Problem

A cold operator in a checkout cannot discover the current local Code Mower operating brief from the normal status surfaces. In v1.3.1, code-mower session show requires a session_file positional. The lease is observable read-only through code-mower session lease show, and the Board already projects safe lease metadata, but neither session show --help nor code-mower lanes status directs the operator there or resolves the matching brief.

Current main also reserves code-mower session status for provider-neutral remote participant lifecycle status, so the local discovery command must remain distinct.

This is follow-up usability work related to roadmap #900. Its minimum exact-checkout, strictly read-only brief/lease resolver is reused by Board issue #949 under epic #945. It remains separate from Board rendering, lifecycle producers, Slack mapping, and cloud fields. It does not interrupt Devin v1.4.0, Graphify v1.4.1, or Slack children before the final canary; #949 waits for this bounded resolver instead of duplicating it.

Outcome

From anywhere inside a Git checkout, an operator can answer "is there an active local Code Mower session or lease here?" without knowing a session filename and without mutating state:

code-mower session show --current
code-mower lanes status --repo OWNER/REPO

The first command resolves the checkout's live lease to its matching saved operating brief when available. The second includes the same bounded lease state in its ordinary human and JSON status output.

Board coordination

• Expose the accepted exact-checkout/current-brief resolver for Board: connect exact local sessions, work, runs, and worktrees #949 to consume rather than copying its discovery logic.
• Keep observation strictly read-only and return safe state/reason data; do not emit Board/cloud events here.
• A lease continues to prove coordination ownership only. Board: connect exact local sessions, work, runs, and worktrees #949 combines it with independent run observations before Board can describe activity.

Implementation direction

• Keep code-mower session show SESSION_FILE fully compatible.
• Make SESSION_FILE optional only when --current is supplied; reject neither/both with bounded guidance.
• Discover the canonical working-copy root using the existing session-lease boundary. Read the lease without renewal, release, takeover, directory creation, or other mutation.
• Use a lock-free full-record observation rather than inspect_lease, because the latter may create the lease directory/lock. Read the lease before and after opening the brief and reject replacement or expiry races.
• Resolve .code-mower/sessions/<lease-session-id>.json by default. Permit an explicit --state-dir for sessions intentionally saved elsewhere.
• Validate the saved session schema, session id, repository, orchestrator, and live lease before presenting it as current. Never choose a file by mtime or scan an unrelated directory as a fallback.
• Reject a symlinked brief, symlinked state path, or any path escape instead of following it.
• If a lease exists but the matching brief is absent, show the safe lease state and tell the operator to supply the session file or its state directory. Do not guess.
• Add an orchestrator_lease object to lanes status using the Board's existing metadata-only projection. Human output should show state, provider, and expiry; JSON must use a closed schema and omit session id and local paths by default.
• Update session help, first-run/current workflow docs, troubleshooting, and shell examples so session show --current and session lease show are discoverable.
• Correct docs/sessions.md: the lease lives at .code-mower/orchestrator-lease.json, not under .code-mower/sessions/.

Acceptance

• A live default-state session is found from the repository root and any subdirectory.
• No lease, expired lease, malformed lease, missing brief, custom state directory, mismatched repo/session/orchestrator, symlinked or replaced brief, and lease expiry during the read each produce deterministic bounded output.
• --current is strictly read-only: filesystem snapshots prove it creates no lock/state/session directories and changes no lease or brief bytes/timestamps.
• A custom --state-dir is confined to the named directory and the exact lease session id; no broad scan or mtime selection.
• session show --current returns zero only for one active exact-matching brief. Absent, expired, malformed, missing, mismatched, or raced state returns nonzero with bounded guidance. lanes status remains successful and reports the diagnostic lease state.
• lanes status human and JSON outputs report safe checkout lease telemetry consistently with the Board and remain path-redacted by default.
• Existing session show SESSION_FILE, session lease show, remote session status, old session files, and no-session checkouts remain compatible.
• Focused session/lease/lane-status tests, full relevant regression, Ruff, privacy scan, package checks, exact-head independent review, and the normal Code Mower gate pass.

Delivery

One bounded PR with one named Code Mower builder and an independent exact-head peer audit. Fix all P0/P1/P2 findings before merge.

Non-goals

• Inferring session start --repo, which is a separate mutating authority-binding decision.
• Adding --current to mutating guided-context commands. A later bounded follow-up may reuse the proven resolver; this issue may include read-only session context status --current only if it remains small.