ace-lab 0.13.1 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 347fa4748ebbcf945253d67f0e9f2f7de3cfd88a11abf134cf2aaf40128c9054
-  data.tar.gz: 934f7b130e93180ab259a0ec4efa2598980af7ce3935628bf9e295e8b4689451
+  metadata.gz: 3c2b81c8fa6e9c3e9838a696ccb0813d28e2a18f7cd46f49e724cc3122cb7ed5
+  data.tar.gz: 1b5338586438ce21609dad591ddd740d1fe4277f7d997f4c84eb7a0a097c8f6a
 SHA512:
-  metadata.gz: 1def278779e6c0593732ebb7872e0ee05aeaed5bacff5c6d623d13a15a1edea755cfe7bb6506edd11d2b22f8c71d8d64c3870bf9b35207395622f2f9c8ccd781
-  data.tar.gz: 0b459c559a716459349d6b7b96ff3dfb521413c526593549e06a18d48a1b682d0d1e006e783ffa80eea9409dabf639341e8556dcf17dcd40fc2baec3c7da9259
+  metadata.gz: 803eb4a258b8776e6dc07e98ce77fe58f903236e68bfb486d1bb785b7d888128649a151d637b1b6e5f710a8574c5f1b13238148ae43c9cae83d9501543dbdb19
+  data.tar.gz: 327c1a76590d7b5695545c1003c4ad97d6638b73287524f0fc51464837f5e4524f915e1e3828f23b89e4d4fdac776d64531f5270ec375444dca5b8aa7d651a5f

data/CHANGELOG.md

@@ -5,7 +5,100 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.14.0] - 2026-10-30
+
+### Fixed
+
+- Forgejo wire contract (PR #398 re-review R1): issue/revoke use the
+  token-authenticated ADMIN endpoints (`/api/v1/admin/users/{account}/tokens`)
+  — the user endpoint requires BasicAuth and does not accept a PAT;
+  repository scoping uses the server's RepoTargetOption shape
+  (`owner/name` → owner+name objects) and an unidentifiable repo is refused
+  before any request, never an all-repositories token; the creation
+  response's granted scopes are validated against the request.
+- GitHub scope semantics (re-review R8): requested subjects are validated
+  against the REAL installation-permission names (`contents`,
+  `pull_requests`, `members`, ...) — Forgejo-shaped subjects like
+  `write:repository` are refused instead of producing permission keys the
+  endpoint does not have; docs use correct examples.
+- Lease durability (re-review R3/R4/R5): every record write is atomic
+  (tmp+fsync+rename under a stable sidecar write lock) and an unparseable
+  record surfaces as a visible `corrupt` recovery error in reconcile, never
+  a silently skipped entry; a record is born `preparing` and becomes
+  `issued` only after a complete usable handoff (a killed issuer leaves a
+  recoverable record, never a phantom live grant); the deterministic remote
+  identity (Forgejo token name) is written at creation, and a retry after
+  an unresolved issue settles the predecessor through it (404 =
+  already-invalid) or refuses — never a blind second mint.
+- exec environment isolation (re-review R6): the child runs through
+  `env -i` with an ALLOWLISTED environment (PATH/HOME &c. plus the leased
+  credential reference) — ambient credential overrides (GH_TOKEN, GIT_*
+  auth, ...) are never inherited past the profile's scope; verified with a
+  real spawned child.
+- Auth lease resilience (task 8xs.t.pu0.f): `LeaseStore#find_live`/`#live?`
+  treated a revoke-pending record (an interrupted issue or a lost revoke) as
+  a LIVE grant — a retry after an interrupted issue returned the dead grant
+  instead of minting a fresh one. Only an ISSUED record inside its deadlines
+  is live; the interrupted record stays a visible open item for reconcile.
+- Auth service hardening (PR #398 review round 8xthaf): the provider and its
+  expiry capability are resolved BEFORE any lease record exists (no orphaned
+  records); an empty repository intersection is refused before issuing (an
+  empty `repositories` payload means ALL repos provider-side — the github and
+  forgejo plugins refuse it too); TTL must be a positive integer; concurrent
+  identical requests serialize through a per-correlation lock (one token, not
+  two); `find_live` is deadline-aware (an expired grant is never returned as
+  live); exec refuses a live lease without its delivered credential; revoke
+  and reconcile degrade cleanly when the profile was removed from the
+  authorization document; a revoke-pending lease whose credential is gone can
+  be closed by an explicit operator `revoke --force` (forced-terminal, never
+  a claimed revocation); exec preserves and EXITS with the child's real exit
+  code; status never prints `token_ref`; provider Authorization headers live
+  in 0600 ephemeral files (`curl -H @file`), never in argv visible to `ps`;
+  github scopes are correctly oriented `level:subject` (`write:repository` →
+  `{"repository" => "write"}` installation permission).
+- Installer robustness: `gemset_provisioner` validates every parsed version
+  with `Gem::Version` itself (platform-suffixed strings fail the probe closed)
+  and normalizes default-gem `default: V` markers from real `gem list` output;
+  `ProjectLocations` reads the lab configuration by explicit path (no
+  `Dir.chdir`) and returns nil for nil/blank project path encodings instead
+  of raising.
+- `ace-lab auth` no longer advertises `--format` (Changed, re-review 8xttao06):
+  the reports are always a single structured JSON document — the option
+  previously parsed and was silently ignored (no table form exists for auth
+  reports), so callers following the lab-wide `--format json` convention now
+  get a documented hard error instead of a silently ignored flag.
+
+### Added
+
+- `ace-lab auth request|status|exec|revoke|reconcile` (task 8xs.t.pu0.7):
+  short-lived role-scoped access. Host-owned profiles in the trusted
+  authorization document's `auth:` section; one minimal lease record (token
+  REFERENCE, deadlines, cleanup outcome — never secrets); ephemeral
+  credential handoff under /run/lab/credentials; idempotent requests per live
+  correlation; scope = profile∩request (never widened by task/config edits);
+  TTL refusals instead of clipping; exec preserves exit codes with both
+  process and cleanup outcomes; revoke idempotent, network outcomes stay
+  revoke-pending; reconcile resolves interrupted cycles.
+- Auth plugins (explicit registry): forgejo (per-lease scoped token on the
+  role account, exact-id revoke), github (App JWT → installation token with
+  real expires_at, DELETE revoke, 401 = already invalid), env (named
+  process-scoped values; standalone env cannot declare remote expiry).
+- Canonical owner map (docs/lab-flow.md) and ADR-034 amendment for the
+  Captain-approved lease record and handoff channel.
+- `ProjectLocations` internal molecule (task 8xs.t.pu0.a): the lab-level
+  start reads the configured projects' canonical locations from the raw
+  topology cascade document — never derived from a public id or repo name.
+- Gem-set dependency closure convergence: missing transitive runtime dependencies
+  (e.g. `json`) are installed at the parent requirement even when the parent version
+  already figures in `gem list`; unsatisfiable dependencies are classified failures
+  (task 8xs.t.pu0.0).
+- Newer versions of a declared gem beside the declared one are removed from the
+  declared runtime during convergence, and `verify` fails while any newer sibling
+  would win CLI activation.
+- `gemset.extensions` manifest entries: harness extension projections from the
+  installed gem's exact declared version (`ExtensionProvisioner`), receipt-based
+  pruning, `loaded_version`/`restart_required` reporting, and read-only
+  re-derivation in `verify`.
 
 ## [0.13.1] - 2026-10-26
 

data/docs/usage.md

@@ -175,6 +175,10 @@ gemset:                      # optional (gad.2): target runtime + required gem s
   gems:                      # exact versions, unique names
     - name: ace-lab
       version: 0.13.0        # must be an exact gem version (no ranges)
+  extensions:                # optional (8xs.t.pu0.0): harness extension projections
+    - gem: ace-wake          # must be declared in gems above
+      path: /Users/overseer/.pi/agent/extensions  # absolute target directory
+      account: lab-overseer  # must be a declared account (the loading executor)
 ```
 
 Statuses: accounts `created|exists|would_create|failed`; directories
@@ -328,6 +332,35 @@ Behavior and guarantees:
   `would_install`/`would_update`/`exists`, nothing is created or
   installed, and a runtime that would need privileges predicts the wet
   failure.
+- **Dependency closure and CLI activation (8xs.t.pu0.0).** Presence of
+  the exact declared version is necessary but not sufficient. Prepare
+  also walks each declared gem's runtime dependency closure in the
+  target runtime and installs missing transitive dependencies at the
+  parent's requirement — a gem whose version already figures in
+  `gem list` but misses a transitive dependency (the manually repaired
+  `json` class of gap) is repaired by `ace-lab install`, and an
+  unsatisfiable dependency is a classified failure, never readiness.
+  A NEWER version of a declared gem sitting beside the declared one
+  would win RubyGems activation and silently take over the runtime's
+  CLI; convergence removes it from the declared runtime (the manifest
+  is the single owner of the declared set) and `verify` fails the gem
+  while any newer sibling remains. `verify` re-derives both facts with
+  the same probes convergence uses — readiness means the closure
+  resolves AND the declared version wins activation.
+- **Extension projections (8xs.t.pu0.0).** Each `gemset.extensions`
+  entry projects the installed gem's `handbook/extensions` tree — at
+  its EXACT declared version, never the checkout and never a newer
+  sibling — into the declared target directory. The projection is
+  receipt-based: only files recorded in the target's
+  `.ace-lab-extension-projection.json` receipt are ever removed, so
+  user-authored extensions in the same directory stay untouched. The
+  report carries `loaded_version` (the version the running harness
+  still holds) and `restart_required` — a changed projection means the
+  executor's processes hold the old extension, and the installer
+  REPORTS the restart need; it never restarts an executor on its own.
+  `verify` re-derives the projection from the installed gem tree and
+  the receipt: a missing receipt, a version mismatch, or a differing
+  file fails readiness.
 - **Exit codes.** A wet run with failed items prints the report, then
   exits non-zero enumerating each `<section>/<item>: <message>`;
   `--dry-run` exits 0 whenever a report renders (conflicts appear as
@@ -606,3 +639,100 @@ The installed authority/admission/journal/command path is removed in L1: the
 and `command execute` commands no longer exist. The local file-based flow does
 not use them. The Forgejo merge adapter and its trusted configuration loader
 remain as provider building blocks; the local flow does not invoke them.
+
+## Auth (8xs.t.pu0.7)
+
+`ace-lab auth request|status|exec|revoke|reconcile` — short-lived, role-scoped
+access for delegated work. The host owns the profile declarations in the SAME
+trusted document (`/etc/lab/ace-lab/authorization.yml`, `auth:` section —
+converged by install); the existing `principals` map stays a visibility map and
+grants no issuance. A project/coworker config only NAMES a profile — it can
+never widen one.
+
+```yaml
+auth:
+  leases_dir: /var/lib/lab/ace-lab/auth/leases
+  credentials_dir: /run/lab/credentials
+  profiles:
+    developer-forgejo:
+      provider: forgejo          # forgejo | github | env
+      roles: [developer]
+      principals: [lab-overseer] # who may REQUEST (empty = any verified account)
+      repos: [cs3b/ace]          # owner/name — Forgejo RepoTargetOption targets
+      scopes: ["write:repository"]
+      ttl_minutes: 30            # default 30; max 60 unless the host sets otherwise
+      expiry_mode: host-revoke   # provider | host-revoke | process
+      issuer:                    # an ADMIN PAT: the token-authenticated admin API
+        url: https://forge.example.com
+        account: lab-role-dev
+        token_file: /etc/lab/ace-lab/secrets/forgejo.admin.token
+```
+
+```bash
+ace-lab auth request --profile developer-forgejo --role developer \
+  --task 8xs.t.pu0.7 --assignment job-7 --repo cs3b/ace
+ace-lab auth status [LEASE]                 # read-only readiness view
+ace-lab auth exec LEASE --cmd bin/ace-test --cmd ace-lab
+ace-lab auth revoke LEASE                   # idempotent
+ace-lab auth reconcile                      # resolves interrupted cycles
+```
+
+Contract highlights:
+
+- The lease record (`/var/lib/lab/ace-lab/auth/leases/<id>.json`) is the ONE
+  minimal record: correlation, provider token REFERENCE (the DETERMINISTIC
+  remote identity, written at creation), deadlines, cleanup outcome. No
+  secrets, no task progress. The ephemeral handoff
+  (`/run/lab/credentials/<lease>-<recipient>`, 0400) carries the reference the
+  child reads (`ACE_LAB_CREDENTIAL_FILE`); no command ever prints a token.
+  A record is born `preparing` and becomes `issued` only after a COMPLETE,
+  usable handoff — an issuer killed mid-flight leaves a recoverable record,
+  never a phantom live grant; every record write is atomic (tmp+fsync+rename)
+  and an unparseable record surfaces as a visible `corrupt` recovery error in
+  `reconcile`, never a silently skipped entry.
+- Request is idempotent per the live task/assignment/profile/role correlation
+  (concurrent requests mint one token under a per-correlation lock); the
+  granted scope is the intersection of the host profile and the request — a
+  request may narrow, never widen, and editing the task or project config
+  grants nothing. The calling ACCOUNT is verified against the profile's
+  principals. A retry after an UNRESOLVED issue outcome never blind-mints a
+  second remote token: the predecessor is settled first through its
+  deterministic reference (Forgejo: the `ace-lab-<lease id>` token name, where
+  a 404 settles as already-invalid), and an unresolvable outcome refuses the
+  retry until reconcile or the provider's native expiry.
+- TTL: default 30m, max 60m unless the host sets an explicit profile limit;
+  exceeding the limit is a REFUSAL, never a silent clip. Status always shows
+  the actual use-until and — separately — the provider-guaranteed expiry.
+- exec preserves the child's exit code and EXITS with it (`ace-lab auth exec`
+  returns the child's code after printing the report); on process success a
+  cleanup failure is itself an error and the report carries both outcomes;
+  one exec at a time per lease; normal end/cancel revokes immediately, a
+  SIGKILL'd executor is cleaned up no later than the recorded deadline (host
+  scheduler) and `reconcile` resolves interrupted cycles. The child runs with
+  an ALLOWLISTED environment (PATH/HOME &c. plus the leased credential
+  reference) — ambient credential overrides (GH_TOKEN, GIT_* auth, ...) are
+  never inherited past the profile's scope.
+- Refusals are non-zero with a reason and the escalation addressee; there is
+  no fallback identity. A network-shaped revoke stays visibly
+  `revoke-pending` — a revocation is never claimed before the provider
+  confirms it. A revoke-pending lease whose credential file is already gone
+  can be closed by an explicit operator decision (`ace-lab auth revoke
+  LEASE --force` → forced-terminal with the unconfirmed outcome recorded),
+  never silently marked revoked.
+- Plugins (explicit registry, like the ace-git providers): `forgejo` (one
+  scoped token per lease through the TOKEN-AUTHENTICATED ADMIN API
+  (`/api/v1/admin/users/{account}/tokens`; the user endpoint requires
+  BasicAuth, not a PAT) with owner/name RepoTargetOption repository targets —
+  a repo without an owner is refused, never an all-repositories token — and
+  the response's granted scopes validated against the request; revoke deletes
+  that exact token name, 404 = already invalid), `github` (App JWT →
+  installation token for chosen repos/permissions with the real `expires_at`;
+  DELETE to revoke; 401 = already invalid), `env` (named values of configured
+  safe sources, process-scoped only — a standalone env profile cannot declare
+  remote expiry/revoke). Scopes are `level:subject` strings, validated per
+  provider: forgejo uses its own scope strings (`write:repository`); github
+  validates subjects against the REAL installation-permission names
+  (`write:contents`, `read:pull_requests`, `members`, ...) and refuses
+  Forgejo-shaped subjects like `write:repository`. Provider Authorization
+  headers travel in 0600 ephemeral files (`curl -H @file`), never in argv
+  visible to `ps`.

data/lib/ace/lab/atoms/install_schema.rb

@@ -31,9 +31,10 @@ module Ace
         DEFAULT_MODE = "0755"
         DEFAULT_KEY_TYPE = "ed25519"
         KEY_TYPES = [DEFAULT_KEY_TYPE].freeze
-        GEMSET_KEYS = %w[gem_home gems].freeze
+        GEMSET_KEYS = %w[gem_home gems extensions].freeze
         GEM_KEYS = %w[name version].freeze
         GEM_NAME_PATTERN = /\A[A-Za-z0-9._-]+\z/
+        EXTENSION_KEYS = %w[gem path account].freeze
 
         class << self
           # @param document [Object] parsed YAML document
@@ -77,7 +78,7 @@ module Ace
               "grants" => normalize_grants(document["grants"], projects.map { |p| p["id"] }),
               "adapters" => normalize_adapters(document["adapters"]),
               "tools" => normalize_tools(document["tools"]),
-              "gemset" => normalize_gemset(document["gemset"])
+              "gemset" => normalize_gemset(document["gemset"], accounts.map { |a| a["username"] })
             }
           end
 
@@ -323,16 +324,22 @@ module Ace
             tools.map(&:strip).uniq
           end
 
-          # Target lab runtime and required gem set (gad.2 gap #1, owner
-          # spec 8xg.t.sbz.7): a sibling of `tools` declaring WHERE the
+          # Target lab runtime, required gem set and harness extension
+          # projections (gad.2 gap #1, owner spec 8xg.t.sbz.7; task
+          # 8xs.t.pu0.0): a sibling of `tools` declaring WHERE the
           # lab's gems must live (`gem_home`, converged as GEM_HOME/
-          # GEM_PATH) and WHICH gems at WHICH exact versions. Absent =
-          # no runtime declared, behavior unchanged. Names must be real
+          # GEM_PATH), WHICH gems at WHICH exact versions, and WHICH
+          # installed gems' handbook/extensions trees are projected
+          # into WHICH target extension directories. Absent = no
+          # runtime declared, behavior unchanged. Names must be real
           # gem names; versions must parse as exact Gem versions (the
           # same parser the runtime uses) — ranges and bare names are
-          # rejected so convergence is always exact-version.
-          def normalize_gemset(raw)
-            return {"gem_home" => nil, "gems" => []} if raw.nil?
+          # rejected so convergence is always exact-version. An
+          # extension entry must reference a declared gem and a
+          # declared account (the executor whose harness loads the
+          # projection) and carries an absolute target path.
+          def normalize_gemset(raw, usernames)
+            return {"gem_home" => nil, "gems" => [], "extensions" => []} if raw.nil?
             unless raw.is_a?(Hash)
               raise_invalid "gemset must be a mapping"
             end
@@ -347,7 +354,61 @@ module Ace
               raise_invalid "gemset gem_home is required and must be an absolute path"
             end
 
-            {"gem_home" => gem_home.strip, "gems" => normalize_gems(raw["gems"])}
+            {"gem_home" => gem_home.strip, "gems" => normalize_gems(raw["gems"]),
+             "extensions" => normalize_extensions(raw["extensions"], raw["gems"], usernames)}
+          end
+
+          # Harness extension projections: each entry names a DECLARED
+          # gem (the projection source — the gem's handbook/extensions
+          # tree at its exact declared version), an absolute target
+          # path (the harness extension directory) and the declared
+          # account whose executor loads it. The manifest stays the
+          # single owner of the declaration; the projection itself is
+          # re-derived from the installed gem on every run.
+          def normalize_extensions(raw, gems, usernames)
+            entries = raw.nil? ? [] : raw
+            unless entries.is_a?(Array)
+              raise_invalid "gemset extensions must be a list"
+            end
+            entries.each_with_index do |entry, index|
+              unless entry.is_a?(Hash)
+                raise_invalid "gemset extensions entry ##{index} must be a mapping"
+              end
+              unknown = entry.keys - EXTENSION_KEYS
+              unless unknown.empty?
+                raise_invalid "gemset extensions entry ##{index} has unknown key '#{unknown.sort.first}'"
+              end
+            end
+
+            declared = (gems || []).filter_map do |gem|
+              gem.is_a?(Hash) && gem["name"].is_a?(String) ? gem["name"].strip : nil
+            end
+            entries.map do |entry|
+              gem = required_string(entry, "gemset extensions", "gem")
+              unless declared.include?(gem)
+                raise_invalid_entry("gemset extensions",
+                  "gem '#{gem}' must be declared in gemset gems before it can project an extension")
+              end
+
+              path = required_string(entry, "gemset extensions", "path")
+              unless absolute_path?(path)
+                raise_invalid_entry("gemset extensions", "path must be an absolute path")
+              end
+
+              account = required_string(entry, "gemset extensions", "account")
+              unless usernames.include?(account)
+                raise_invalid_entry("gemset extensions",
+                  "account must reference a declared account")
+              end
+
+              {"gem" => gem, "path" => path, "account" => account}
+            end.tap do |extensions|
+              duplicates_of(extensions.map { |extension| extension["path"] }) do |_path|
+                raise_invalid_entry("gemset extensions",
+                  "path is declared more than once — a duplicate projection path would overwrite " \
+                    "another entry's receipt")
+              end
+            end
           end
 
           def normalize_gems(raw)
@@ -401,7 +462,7 @@ module Ace
             unless value.is_a?(String) && !value.strip.empty?
               raise_invalid_entry(section_name, "#{field} is required and must be a non-empty string")
             end
-            value
+            value.strip
           end
 
           def normalize_mode(raw)

data/lib/ace/lab/auth/credential_handoff.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Ace
+  module Lab
+    module Auth
+      # Ephemeral secret handoff (task 8xs.t.pu0.7): the leased secret
+      # is written ONCE under the credentials dir (/run/lab/credentials
+      # by default), in a per-lease, per-recipient file, mode 0400,
+      # verified against symlink takeover; the child receives the file
+      # REFERENCE (path), never the value in argv or the serialized
+      # report. Removal after the lease is idempotent.
+      class CredentialHandoff
+        def initialize(credentials_dir, recipient: )
+          @credentials_dir = credentials_dir
+          @recipient = recipient
+        end
+
+        def path(lease_id)
+          File.join(@credentials_dir, "#{lease_id}-#{@recipient}")
+        end
+
+        # @return [String] the credential file path (the reference)
+        def deliver(lease_id, secret)
+          FileUtils.mkdir_p(@credentials_dir)
+          target = path(lease_id)
+          raise Error, "credential handoff path is a symlink; refusing" if File.symlink?(target)
+
+          temporary = "#{target}.#{Process.pid}.tmp"
+          File.write(temporary, secret.to_s)
+          FileUtils.chmod(0o400, temporary)
+          File.rename(temporary, target)
+          target
+        end
+
+        def clear(lease_id)
+          target = path(lease_id)
+          File.delete(target) if File.file?(target) && !File.symlink?(target)
+          :cleared
+        rescue Errno::ENOENT
+          :cleared
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/auth/lease_store.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "json"
+require "fileutils"
+require "digest"
+require "time"
+
+module Ace
+  module Lab
+    module Auth
+      # The ONE owner of the minimal lease record (task 8xs.t.pu0.7):
+      # one JSON file per lease under the trusted leases dir (default
+      # /var/lib/lab/ace-lab/auth/leases), private to the issuer. The
+      # record carries the correlation (task/assignment/profile/role/
+      # principal), the provider TOKEN REFERENCE (never the secret
+      # value), the deadlines and the cleanup outcome — never task
+      # progress, queues, or another tool's state.
+      #
+      # Lifecycle: a record is born PREPARING (issue in flight — a hard
+      # process death in that window leaves a recoverable record, never
+      # a phantom "live" grant); it becomes ISSUED only after a
+      # complete, usable credential handoff; an unresolved remote
+      # outcome (lost response, lost revoke) is REVOKE-PENDING until
+      # reconciled; REVOKED is terminal. Every write is atomic
+      # (temporary file + fsync + rename) under a STABLE sidecar write
+      # lock — a crash mid-write can never truncate or half-replace a
+      # record, and an unparseable record surfaces as a visible CORRUPT
+      # marker instead of silently vanishing from the inventory.
+      class LeaseStore
+        STATES = %w[preparing issued revoke-pending revoked].freeze
+
+        attr_reader :dir
+
+        def initialize(dir)
+          @dir = dir
+        end
+
+        # @param id [String, nil] caller-generated lease id (so the
+        #   provider's deterministic token_ref can be computed from it
+        #   and written in the SAME atomic creation write)
+        # @param token_ref [String, nil] the provider's DETERMINISTIC
+        #   remote identity for this lease, written at creation so an
+        #   interrupted issue can still be reconciled against the
+        #   remote side (the response may never have arrived).
+        # @return [Hash] the created (PREPARING) lease record
+        def create(profile:, role:, principal:, task:, assignment:, repos:,
+          use_until:, provider_expiry:, token_ref: nil, id: nil)
+          lease = {"id" => id || "lease-#{SecureRandom.hex(8)}",
+                   "profile" => profile, "role" => role, "principal" => principal,
+                   "task" => task, "assignment" => assignment, "repos" => repos.sort,
+                   "state" => "preparing", "requested_at" => now,
+                   "use_until" => use_until, "provider_expiry" => provider_expiry,
+                   "token_ref" => token_ref, "cleanup" => nil}
+          write(lease)
+          lease
+        end
+
+        # Idempotency: the LIVE lease for the same task/assignment/
+        # profile/role correlation, if any. Only an ISSUED record is
+        # live: preparing (issue in flight or dead mid-issue) and
+        # revoke-pending (unresolved remote outcome) records are never
+        # returned — recovery settles them instead. A finished or
+        # scope-changed correlation does not match, and
+        # DEADLINE-AWARENESS is part of the match: an issued record
+        # past its use_until/provider expiry is not returned, so a
+        # retry mints a fresh grant while reconcile retires the expired
+        # one — an expired grant is never handed back as "live".
+        def find_live(task:, assignment:, profile:, role:)
+          all.filter_map do |lease|
+            next unless lease["task"] == task && lease["assignment"] == assignment &&
+              lease["profile"] == profile && lease["role"] == role &&
+              lease["state"] == "issued"
+            lease if live?(lease)
+          end.min_by { |lease| lease["requested_at"].to_s }
+        end
+
+        def load(id)
+          path = lease_path(id)
+          raise Error, "unknown lease '#{id}'" unless File.file?(path)
+
+          JSON.parse(File.read(path))
+        rescue JSON::ParserError
+          raise Error, "lease record '#{id}' is unreadable"
+        end
+
+        # The full inventory, including CORRUPT records as explicit
+        # markers: a record that cannot be parsed is a visible recovery
+        # problem (the remote token may still be live) — never a
+        # silently skipped entry that disappears from reconcile.
+        def all
+          return [] unless Dir.exist?(@dir)
+
+          Dir.glob(File.join(@dir, "*.json")).sort.filter_map do |path|
+            JSON.parse(File.read(path))
+          rescue Errno::EACCES
+            nil
+          rescue JSON::ParserError
+            {"id" => File.basename(path, ".json"), "state" => nil,
+             "corrupt" => true, "_path" => path}
+          end
+        end
+
+        # Atomic update under a STABLE sidecar write lock: the record is
+        # read, modified and replaced via temporary-file + fsync +
+        # rename. A crash at any point leaves either the old or the new
+        # complete record — never a truncated file — and the lock
+        # survives the replacement (it is not held on the record inode).
+        def update(id)
+          path = lease_path(id)
+          with_write_lock(id) do
+            lease = begin
+              JSON.parse(File.read(path))
+            rescue JSON::ParserError, Errno::ENOENT => e
+              # A corrupt/missing record is a named store failure, never a
+              # raw parser error escaping through the update seam.
+              raise Error, "lease '#{id}' cannot be read at #{path}: #{e.class} #{e.message}"
+            end
+            yield(lease)
+            atomic_write(path, lease)
+            lease
+          end
+        end
+
+        def write(lease)
+          atomic_write(lease_path(lease["id"]), lease)
+          lease
+        end
+
+        def with_write_lock(id)
+          FileUtils.mkdir_p(@dir)
+          File.open(File.join(@dir, "#{id}.write.lock"), File::CREAT | File::RDWR) do |lock|
+            lock.flock(File::LOCK_EX)
+            yield
+          end
+        end
+
+        # One request flow at a time per correlation (task/assignment/
+        # profile/role): a BLOCKING exclusive lock on the correlation's
+        # lockfile so the find_live + create + issue sequence is atomic
+        # against a concurrent identical request — the second caller
+        # waits and then returns the first caller's live lease.
+        def with_correlation_lock(task:, assignment:, profile:, role:)
+          FileUtils.mkdir_p(@dir)
+          key = Digest::SHA256.hexdigest([task, assignment, profile, role].join("\e"))
+          File.open(File.join(@dir, "correlation-#{key}.lock"), File::CREAT | File::RDWR) do |lock|
+            lock.flock(File::LOCK_EX)
+            yield
+          end
+        end
+
+        # One exec at a time per lease: an exclusive lock on the lease's
+        # exec lockfile, non-blocking — a parallel exec is a refusal.
+        def with_exec_lock(id)
+          FileUtils.mkdir_p(@dir)
+          File.open(File.join(@dir, "#{id}.exec.lock"), File::CREAT | File::RDWR) do |lock|
+            unless lock.flock(File::LOCK_EX | File::LOCK_NB)
+              raise Error, "lease '#{id}' already has a running exec"
+            end
+
+            yield
+          end
+        end
+
+        # Usable NOW: only an ISSUED record inside its deadlines. A
+        # preparing record was never delivered (or the process died
+        # mid-issue) and a revoke-pending record has no valid handoff
+        # or is mid-revocation — neither is ever usable or "live".
+        def live?(lease, at: Time.now)
+          return false unless lease["state"] == "issued"
+          return false if lease["use_until"] && Time.parse(lease["use_until"]) <= at
+          if lease["provider_expiry"] && Time.parse(lease["provider_expiry"]) <= at
+            return false
+          end
+
+          true
+        end
+
+        private
+
+        def atomic_write(path, lease)
+          FileUtils.mkdir_p(@dir)
+          temporary = "#{path}.#{Process.pid}.tmp"
+          File.open(temporary, "w") do |file|
+            file.write(JSON.pretty_generate(lease))
+            file.flush
+            file.fsync
+          end
+          # 0600 BEFORE the rename: the record never exists at the target
+          # path with umask-default permissions, even for an instant.
+          FileUtils.chmod(0o600, temporary)
+          begin
+            File.rename(temporary, path)
+          rescue Errno::ENOENT
+            FileUtils.mkdir_p(File.dirname(path))
+            File.rename(temporary, path)
+          end
+        end
+
+        def lease_path(id)
+          raise Error, "invalid lease id" unless id.to_s.match?(/\Alease-[a-f0-9]{16}\z/)
+
+          File.join(@dir, "#{id}.json")
+        end
+
+        def now
+          Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ")
+        end
+      end
+    end
+  end
+end