ace-lab 0.13.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff20c0d594202a649d5597257411b611d6faf6b66128fd8ff4ad0702989b6e16
-  data.tar.gz: 1d6575916e526eec678ee39c9be5025f53653fcdfac27c8075692c936d3351bd
+  metadata.gz: 3c2b81c8fa6e9c3e9838a696ccb0813d28e2a18f7cd46f49e724cc3122cb7ed5
+  data.tar.gz: 1b5338586438ce21609dad591ddd740d1fe4277f7d997f4c84eb7a0a097c8f6a
 SHA512:
-  metadata.gz: 32b6ee73258e1534a9ff91f2bc83d30ff4265b124aefcee056652dd0544ef770aba4036e055e282fc35ea1c2a993cfefa67f46480e82ecf4f294fbda5561deeb
-  data.tar.gz: 786a3ca1af5fad657f722d3ea2c0ba525988c5461ed18a94023650e17f5b7870c15a754d71560ee442e78bd6527a42823d25dc297911666156bf57287072e9c7
+  metadata.gz: 803eb4a258b8776e6dc07e98ce77fe58f903236e68bfb486d1bb785b7d888128649a151d637b1b6e5f710a8574c5f1b13238148ae43c9cae83d9501543dbdb19
+  data.tar.gz: 327c1a76590d7b5695545c1003c4ad97d6638b73287524f0fc51464837f5e4524f915e1e3828f23b89e4d4fdac776d64531f5270ec375444dca5b8aa7d651a5f

data/CHANGELOG.md

@@ -5,7 +5,138 @@ 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
+
+### Added
+
+- Gem-set installation into the target lab runtime (gad.2 acceptance
+  gap #1, owner spec 8xg.t.sbz.7, L8 install group): the trusted
+  install manifest (still schema v1) gains an optional `gemset` section
+  — a sibling of `tools` — declaring the target runtime (`gem_home`,
+  an absolute path converged as GEM_HOME and GEM_PATH) and the required
+  gem set (`name` + exact `version`; unique names, versions validated
+  as real Gem versions, so ranges and "latest" are rejected at load).
+  A manifest without the section behaves exactly as before.
+  `ace-lab prepare` (and therefore `ace-lab install`) converges the gem
+  set into the declared runtime idempotently through a new
+  `GemsetProvisioner` molecule: exact version present = no-op
+  (`exists`), missing = installed, different version present = updated
+  (the declared version installed; RubyGems keeps versions side by
+  side and verify judges the declared set). The gem subprocesses run
+  with `GEM_HOME`/`GEM_PATH` pinned to the runtime through the same
+  argv runner seam as every other prepare step — with the invoking
+  process's bundler context stripped (`RUBYOPT`, `RUBYLIB`,
+  `BUNDLE_*`/`BUNDLER_*`), so `bundle exec ace-lab prepare` converges
+  the LAB runtime instead of its own bundle. The runtime directory is
+  created only with administrator privileges (the AccountProvisioner
+  seam); a symlink or non-directory runtime is refused (the
+  DirectoryProvisioner takeover posture); runtime failures fail every
+  gem item as a dependency and gate the install's projects and grants
+  like any other machine-level failure. `--dry-run` predicts
+  `would_install`/`would_update`/`exists` read-only and predicts the
+  wet privilege failure. The install report echoes the declared gemset
+  under `gemset`. `ace-lab verify` gained a matching read-only `gems`
+  check — every declared gem must be installed at its exact version in
+  the declared runtime, judged through the SAME probe the provisioner
+  converges from (a missing `gem` executable reports `unknown`, the
+  offline posture). `project add` stays project-scoped: gem
+  installation is machine-level provisioning and is deliberately not
+  added there. (PR #77)
 
 
 ## [0.13.0] - 2026-10-20

data/docs/usage.md

@@ -170,14 +170,27 @@ projects:                    # optional (consumed by ace-lab install)
 grants:                      # optional: trusted-tier principal grants
   ace-overseer:              # principal → declared project ids
     - atlas
+gemset:                      # optional (gad.2): target runtime + required gem set
+  gem_home: /opt/lab/gems    # absolute; converged as GEM_HOME and GEM_PATH
+  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
 `created|exists|mode_fixed|would_create|would_fix_mode|failed`; keys
 `created|exists|would_create|would_repair_public|would_fix_mode|failed`
-(with the public `fingerprint`); roles `verified|failed`. `ok` in the
+(with the public `fingerprint`); roles `verified|failed`; gems
+`installed|updated|exists|would_install|would_update|failed` (one item
+per declared gem). `ok` in the
 JSON report means zero failed items. Key/role items whose account
-failed are reported as dependency failures instead of being attempted.
+failed are reported as dependency failures instead of being attempted;
+gem items fail as dependencies when the declared runtime did not
+prepare.
 
 `--dry-run` is a faithful prediction of the wet run (`would_*`
 statuses, zero mutations): keys and roles of an account the account
@@ -299,6 +312,55 @@ Behavior and guarantees:
   group, or other. A readable file behind an unsearchable directory
   (e.g. 0644 inside a 0700 directory owned by someone else) is
   `failed`, not `verified`. ACLs remain out of scope.
+- **Gem-set convergence (gad.2).** When the manifest declares a
+  `gemset`, prepare converges the declared gem set into the declared
+  target runtime (`gem_home`): a gem whose exact declared version is
+  already present is a no-op (`exists`), a missing gem is installed
+  (`installed`), a gem present at a different version is updated (the
+  declared version is installed; RubyGems keeps versions side by side
+  and verify judges the declared set). The `gem` subprocesses run with
+  `GEM_HOME`/`GEM_PATH` pinned to the runtime (through the POSIX `env`
+  command, argv arrays only) and with the invoking process's bundler
+  context stripped (`RUBYOPT`, `RUBYLIB`, `BUNDLE_*`/`BUNDLER_*`), so
+  a `bundle exec ace-lab prepare` converges the LAB runtime, never its
+  own bundle. The runtime directory is created only with
+  administrator privileges; a symlink or non-directory at `gem_home`
+  is refused (takeover posture). Installs fetch from the `gem`
+  command's configured sources (provisioning network access, like
+  cloning a declared remote) with `--no-document`. `--dry-run` is a
+  faithful prediction: the read-only probe runs, statuses are
+  `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
@@ -408,8 +470,9 @@ existing molecules in a fixed order:
    present) must not grant projects the manifest does not declare: a
    ready or foreign lab is refused with a classified error and zero
    writes, identically in wet runs and `--dry-run` (prediction parity).
-2. **prepare (L8.1)** — accounts → directories → keys → roles, exactly
-   as `ace-lab prepare` (same organism, same per-item report).
+2. **prepare (L8.1)** — accounts → directories → keys → roles → gems,
+   exactly as `ace-lab prepare` (same organism, same per-item report;
+   the declared gem set converges into the declared target runtime).
 3. **project add (L8.2) per declared project** — repository, private
    `_overseer`, project registry, exactly as `ace-lab project add`.
    Projects are isolated: one failing project does not block the
@@ -486,6 +549,7 @@ never taken over, never cleaned:
 | --- | --- | --- |
 | declared directory | symlink, non-directory, or foreign ownership | step fails with a resolve-manually message; projects and grants are gated as dependency failures |
 | key pair | foreign-owned key files or `.ssh`, non-regular file | step fails with a resolve-manually message |
+| gem set | symlinked or non-directory runtime, missing privileges, or a failed probe/install | every gem item fails with a classified message; projects and grants are gated as dependency failures |
 | project repository | non-empty non-Git directory, or a Git repository with a different origin | step fails: "refusing to take over a foreign location" / "refusing to overwrite an existing registration"; the other projects still run (isolation) |
 | grants | trusted document granting projects outside the manifest, or a document that fails verification/parsing | the whole install refuses before any mutation ("refusing to install over a foreign lab"), wet and in `--dry-run` alike |
 
@@ -533,6 +597,9 @@ a concrete reason (never a bare boolean):
 | grants | the trusted document is present and verifiable, and every manifest principal's grants resolve through the real read-side mechanics (`CallerAuthorizer`) to the declared projects |
 | registry | each project is registered in its `.ace/lab/config.yml` (visibility through the configuration cascade) |
 | overseer | `.ace-tasks/_overseer/` exists and is ignored by Git (`git check-ignore`) |
+| adapters | configuration is a mapping; a declared local command resolves (probed for the target executors); `kind: hitl` routes are installed in every project's `.ace/hitl/config.yml` and satisfy the runtime loader's rules |
+| tools | each required tool resolves to an executable the target executors can run (presence + permission probe, no execution) |
+| gems | each declared gem is installed at its EXACT declared version in the declared target runtime — judged through the same read-only probe prepare converges from; a missing runtime, a missing gem or a version mismatch blocks readiness (a missing `gem` executable reports `unknown`, the offline posture) |
 
 The overall verdict is `ready` only when no check failed. A failure
 never hides healthy data: the full report renders first (table or
@@ -572,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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "rubygems/version"
+
 module Ace
   module Lab
     module Atoms
@@ -13,7 +15,7 @@ module Ace
         SCHEMA_VERSION = 1
         TOP_LEVEL_KEYS =
           %w[schema_version machine accounts directories keys roles projects grants
-             adapters tools].freeze
+             adapters tools gemset].freeze
         ENTRY_KEYS = {
           "accounts" => %w[username role create home],
           "directories" => %w[path owner mode],
@@ -29,6 +31,10 @@ module Ace
         DEFAULT_MODE = "0755"
         DEFAULT_KEY_TYPE = "ed25519"
         KEY_TYPES = [DEFAULT_KEY_TYPE].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
@@ -71,7 +77,8 @@ module Ace
               "projects" => projects,
               "grants" => normalize_grants(document["grants"], projects.map { |p| p["id"] }),
               "adapters" => normalize_adapters(document["adapters"]),
-              "tools" => normalize_tools(document["tools"])
+              "tools" => normalize_tools(document["tools"]),
+              "gemset" => normalize_gemset(document["gemset"], accounts.map { |a| a["username"] })
             }
           end
 
@@ -317,6 +324,131 @@ module Ace
             tools.map(&:strip).uniq
           end
 
+          # 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), 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. 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
+
+            unknown = raw.keys - GEMSET_KEYS
+            unless unknown.empty?
+              raise_invalid "gemset has unknown key '#{unknown.sort.first}'"
+            end
+
+            gem_home = raw["gem_home"]
+            unless gem_home.is_a?(String) && !gem_home.strip.empty? && absolute_path?(gem_home.strip)
+              raise_invalid "gemset gem_home is required and must be an absolute path"
+            end
+
+            {"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)
+            gems = raw.nil? ? [] : raw
+            unless gems.is_a?(Array)
+              raise_invalid "gemset gems must be a list"
+            end
+            gems.each_with_index do |entry, index|
+              unless entry.is_a?(Hash)
+                raise_invalid "gemset gems entry ##{index} must be a mapping"
+              end
+              unknown = entry.keys - GEM_KEYS
+              unless unknown.empty?
+                raise_invalid "gemset gems entry ##{index} has unknown key '#{unknown.sort.first}'"
+              end
+            end
+
+            gems.map do |entry|
+              name = entry["name"]
+              unless name.is_a?(String) && name.strip =~ GEM_NAME_PATTERN
+                raise_invalid_entry("gemset gems", "name is required and must be a gem name")
+              end
+              version = entry["version"]
+              unless version.is_a?(String) && !version.strip.empty?
+                raise_invalid_entry("gemset gems", "version is required and must be an exact version")
+              end
+              begin
+                Gem::Version.new(version.strip)
+              rescue ArgumentError
+                raise_invalid_entry("gemset gems", "version must be an exact gem version")
+              end
+
+              {"name" => name.strip, "version" => version.strip}
+            end.tap do |gems|
+              duplicates_of(gems.map { |gem| gem["name"] }) do |_name|
+                raise_invalid_entry("gemset gems", "name is declared more than once")
+              end
+            end
+          end
+
           def optional_string(entry, section_name, field)
             value = entry[field]
             if !value.nil? && (!value.is_a?(String) || value.strip.empty?)
@@ -330,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