ace-lab 0.9.0 → 0.13.1

data/docs/usage.md

@@ -1,637 +1,608 @@
 # ace-lab usage
 
-Topology, routing, and scoped service requests for the Lab. Resolves stable
-project, agent, and service IDs without transient pane IDs or shared service
-credentials.
+`ace-lab` exposes read-only topology queries, the lab status snapshot, the
+`prepare` phase of the lab installer (L8.1), `project add` project
+onboarding (L8.2), the full installer `install` (L8.3, which also resumes
+its own interrupted installation, L8.4), and the end-to-end readiness
+verification `verify` (L8.5).
 
-## Commands
+The file-based ownership model is documented once in
+[../../docs/lab-flow.md](../../docs/lab-flow.md).
 
-Topology commands accept `--format json` (the only supported format) and
-`-q/--quiet`. Service status accepts `--format json`; service request always
-emits JSON.
+## Topology
 
-### `ace-lab projects`
-
-List projects visible to the verified caller.
+Topology configuration is read from `~/.ace/lab/config.yml` or
+`.ace/lab/config.yml` through the normal ACE configuration cascade. All
+topology commands accept `--format json` (the only supported format) and
+`-q/--quiet`.
 
-    $ ace-lab projects --format json
-    {"status":"ok","data":{"projects":[{"id":"atlas","label":"Atlas platform"},{"id":"borealis"}]}}
+```yaml
+# .ace/lab/config.yml -- topology only
+schema_version: 1
+topology:
+  projects:
+    - { id: atlas, label: Atlas platform }
+  agents:
+    - id: atlas-planner
+      project: atlas
+      role: planner
+      capabilities: [planning]
+  services:
+    - id: atlas-search
+      project: atlas
+      capabilities: [search]
+      default_for: [search]
+      endpoint: { kind: http, url: "https://search.example.internal/query" }
+```
 
-A caller with no configured principal receives:
+### `ace-lab projects`
 
-    {"status":"error","error":{"code":"unauthorized","message":"caller has no configured authorization for any lab project"}}
+```bash
+ace-lab projects --format json
+# {"status":"ok","data":{"projects":[{"id":"atlas","label":"Atlas platform"}]}}
+```
 
 ### `ace-lab agents --project PROJECT`
 
-List agents in one project.
-
-    $ ace-lab agents --project atlas --format json
-    {"status":"ok","data":{"agents":[{"id":"atlas-planner","project":"atlas","role":"planner","capabilities":["planning"],"binding":{"kind":"runtime","state":"available"}}]}}
+```bash
+ace-lab agents --project atlas --format json
+```
 
-`binding.state` is `available` when the configured runtime binding is active
-and its instance identity matches the attestation; otherwise `stale`.
+`binding.state` is `available` when the configured runtime binding is active;
+otherwise `stale`.
 
 ### `ace-lab services --project PROJECT`
 
-List services in one project.
-
-    $ ace-lab services --project atlas --format json
-    {"status":"ok","data":{"services":[{"id":"atlas-search","project":"atlas","capabilities":["search"],"default_for":["search"],"binding":{"kind":"service","state":"available","endpoint":{"kind":"http","url":"https://search.example.internal:8443"}}}]}}
+```bash
+ace-lab services --project atlas --format json
+```
 
-The endpoint is a sanitized identity: scheme, host, and explicit port only.
+The endpoint in public output is a sanitized identity: scheme, host and an
+explicit port only. Query parameters, userinfo, fragments and credentials are
+never printed.
 
 ### `ace-lab resolve --id ID`
 
-Resolve one entry by exact stable ID.
-
-    $ ace-lab resolve --id atlas-planner --format json
-    {"status":"ok","data":{"entry":{"id":"atlas-planner","project":"atlas","role":"planner","capabilities":["planning"],"binding":{"kind":"runtime","state":"available"}}}}
+```bash
+ace-lab resolve --id atlas-planner --format json
+```
 
-Labels are display values and never resolve: `resolve "Atlas platform"` is a
+Labels are display values and never resolve: resolving `"Atlas platform"` is a
 `missing` error.
 
 ### `ace-lab route --project PROJECT --capability CAPABILITY`
 
-Select a configured capable service in the requested project.
-
-    $ ace-lab route --project atlas --capability search --format json
-    {"status":"ok","data":{"entry":{"id":"atlas-search","project":"atlas","capabilities":["search"],"default_for":["search"],"binding":{"kind":"service","state":"available","endpoint":{"kind":"http","url":"https://search.example.internal:8443"}}}}}
-
-Routing never invokes the service and never grants credentials.
-
-### `ace-lab service request`
-
-**Goal:** Ask a configured service to perform one named operation for an
-active, task-attached assignment attempt. First create a JSON input file:
-
-```json
-{"target":{"resource":"release/1.2.3","artifact_digest":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"},"arguments":{"version":"1.2.3"}}
+```bash
+ace-lab route --project atlas --capability search --format json
 ```
 
-Run a preview, then submit the exact request:
+Routing selects a capable service in the requested project. It never invokes
+the service and never grants credentials.
 
-```sh
-ace-lab service request --project atlas --assignment A --attempt ATT \
-  --operation publish --input release.json --authorization DECISION \
-  --request-id REQUEST --dry-run
-ace-lab service request --project atlas --assignment A --attempt ATT \
-  --operation publish --input release.json --authorization DECISION \
-  --request-id REQUEST
-```
+## Status
 
-The preview reports `outcome: accepted` with `dry_run: true` and the selected
-service ID, target, and candidate head. It creates no request claim or effect.
-The second command returns `succeeded`, `failed`, or `uncertain` with a
-non-secret receipt when the executor confirms an outcome. A missing response
-leaves `uncertain` in the assignment evidence ref; do not retry with a new ID
-until the external outcome is reconciled. Repeating the same ID and input
-returns its stored state without dispatching again. A changed binding under
-the same ID is a `conflict` error.
-
-Input must be a JSON object of at most 64 KiB. `target.resource` is a stable
-resource ID; `target.artifact_digest`, when supplied, is a SHA-256 hex digest.
-Credential, password, secret, token, private-key, authorization, and env keys
-are rejected recursively. Operation arguments remain structured JSON sent to
-the executor; no caller-provided shell command or argv is accepted.
-
-| Option | Purpose |
-|--------|---------|
-| `--project` | Project stable ID |
-| `--assignment` | Assignment ID |
-| `--attempt` | Active managed attempt ID |
-| `--operation` | Configured named operation |
-| `--input` | Structured JSON file |
-| `--authorization` | Exact decision or configured automation reference |
-| `--request-id` | Idempotency key; use the same ID for retries/status |
-| `--dry-run` | Validate and show scope without an effect |
-
-### `ace-lab service status`
-
-```sh
-ace-lab service status --request REQUEST --format json
-```
+### `ace-lab status [--format table|json] [-q]`
 
-Expected output after a lost executor receipt:
-
-```json
-{"status":"ok","data":{"request_id":"REQUEST","outcome":"uncertain","state":"uncertain"}}
+```bash
+ace-lab status                 # readable table (default)
+ace-lab status --format json   # full report as JSON
 ```
 
-Only the original OS caller identity with project visibility can read the
-request. The authoritative state survives loss of the local assignment cache
-because it lives in the separate assignment evidence Git ref.
-
-### `ace-lab service listen --mode ordinary-merge`
-
-The installed ordinary service owns the Assign, HITL and merge endpoints in one
-process. Start it as the configured service account:
-
-```sh
-ace-lab service listen --mode ordinary-merge --project atlas \
-  --config /etc/lab/ace-lab/atlas-receiver.yml
-```
-
-The receiver configuration selects its existing forge, repository, principal and
-merge socket. `/etc/lab/ace-lab/assign-owners.yml` separately selects the canonical
-Assign journal and native execution owner. Both selections must agree with the
-ordinary project mapping in the trusted authorization document. `repo_path` is
-the merge candidate repository; it does not choose the execution journal.
-
-Each project entry in the root-installed assignment document contains:
-
-| Entry | Installed selection |
-|---|---|
-| `service` | Non-root owner UID/GID, assignment socket and private state root |
-| `journal` | Service-owned repository, execution ref and private evidence checkout |
-| `assignment_root`, `lifecycle_root` | Separate private prepared-input and exclusion directories |
-| `runtime_binary`, `native` | Installed executable and exact native server/socket generation from the installation receipt |
-| `worktrees` | Allowed worktree root and Git common directory |
-| `participants` | OS UID/GID/actor, native workspace and supervisor panes |
-| `hitl` | Private store root, distinct socket, dedicated group, trusted grants path and optional installed TLS authority reference |
-
-For example, the `hitl` entry inside an already selected project can be:
-
-```yaml
-hitl:
-  root: /var/lib/lab/assign/atlas/hitl
-  socket_path: /run/lab/assign/atlas/hitl.sock
-  group: atlas-lifecycle
-  grants_path: /etc/lab/ace-lab/authorization.yml
+`status` is read-only local observability (task 8xg.t.sbz.6.0): it reads the
+ADR-022 lab configuration cascade and the file-based state-owner locations
+(ADR-034) — nothing is started, written, or installed, and there is no
+authorization gate. Live terminal layout belongs to `ace-herdr status`; the
+enriched worktree view with task associations is `ace-git-worktree list`
+(delivered by k9y) — `status` shows only presence/count for worktrees and does
+not duplicate that surface.
+
+Lab configuration is reported in three distinct states — they are never
+conflated:
+
+- `configured` — at least one overlay (`.ace/lab/config.yml` or
+  `~/.ace/lab/config.yml`) present and valid, with topology counts
+  (0/0/0 is a *valid empty set*).
+- `missing` — defaults only: no overlay exists. Informational; exit code 0.
+  Never rendered as a ready-but-empty lab.
+- `invalid` — an unparsable/non-mapping document or a schema violation;
+  carries the path-bearing message.
+
+Runtime *configuration* is echoed (project/user `runtime/config.yml`, then the
+`ACE_RUNTIME` environment variable) with its value and origin. No runtime
+detection and no `ace-runtime` dependency: runtime availability is
+`ace-herdr status`'s dimension.
+
+Local state covers `.ace-tasks/`, `.ace-tasks/_overseer/` (presence only —
+private, never enumerated), `.ace-local/assign/`, `.ace-local/hitl/`,
+`.ace-wt/`, and `.ace-local/coworker/` (presence only — reserved L3). Absence
+of overseer or coworker state is information, not a failure.
+
+Exit codes: 0 for `configured` and `missing` (empty or not); a source error —
+invalid configuration or an unreadable location — prints the **full report
+first**, then fails non-zero with the error, so available results stay visible
+next to the failure.
+
+## Prepare (L8.1)
+
+```bash
+ace-lab prepare              # table: one line per manifest item
+ace-lab prepare --dry-run    # predict (would_*) without mutating anything
+ace-lab prepare --format json
 ```
 
-The store must be a separate child of that project's `service.state_root`; the
-installer creates `service.state_root` with mode `0700`, the HITL root with its
-maintained mode `0711`, and socket access before startup. The private parent keeps
-the HITL tree inaccessible to other accounts; Store maintains private request and
-secret subdirectories. Startup and restart validate the same layout.
-`hitl.service_uid` in the grants document must equal the Assign owner UID. Native
-identities come from the installed receipt and live observation, not the project
-configuration cascade. HITL requests, decisions and merge claims use the same
-canonical Assign journal and lifecycle exclusion.
-
-For the existing remote Hermes transport, install its project-scoped mTLS
-authority and add its absolute configuration path to this same `hitl` entry:
+`prepare` reads the trusted install manifest from the fixed deployment
+path `/etc/lab/ace-lab/install.yml` and makes the machine match it,
+idempotently, in a fixed section order: accounts → directories → keys →
+roles. There is deliberately no `--manifest` flag: a caller-selected
+manifest could manufacture privileges (accounts, directories, keys), so
+the manifest is a root-owned deployment document verified through the
+same fail-closed traversal as the authorization file (every element on
+the path root-owned and not group/world-writable, `O_NOFOLLOW` on the
+final component). It is never edited through the `.ace/` cascade and is
+not task state (ADR-034): nothing outside the manifest is touched, and
+no progress journal is written — re-running `prepare` simply converges.
 
 ```yaml
-  tls_authority: /etc/lab/ace-hitl/atlas-tls.json
-```
-
-The referenced file uses the maintained `ace.hitl.tls.authority/v1` schema and
-credential provisioning layout from `ace-hitl`. Its project must match this
-owner; `service_user` and `service_group` must resolve to the owner's actual UID
-and primary GID. The dedicated Unix control group remains `hitl.group`. Root
-installs the credential references and Incus TCP proxy; callers cannot choose
-them. Invalid ownership, identity, project or TLS material prevents startup.
-
-The TLS listener runs in this same service process and shares its exact HITL
-binding, store, decision policy and in-memory one-time OTP vault. Hermes uses its
-verified project certificate as a remote transport identity; it does not need a
-synthetic Unix transport UID. Keep `transport_uids` empty when no local transport
-is installed. Configure the actual local proposer separately with
-`proposal_uids` and its project grant. A proposer grant never authorizes replies
-or delegates silence-based decisions. Restart the composed service after changing
-its TLS authority or credential selection, retaining the canonical journal.
-
-All selected endpoints must become ready before assignment ingress opens. A
-failed endpoint shuts down the complete owner. A stale assignment endpoint needs
-installer inspection; startup does not remove it or recover merge effects first.
-
-## Ordinary assignment client
-
-`ace-lab assignment` selects the root-installed project owner and uses the
-existing Assign protocol. Assign remains the only accepted execution journal.
-Preparation captures reviewed task context and the existing managed assignment
-graph; it does not start a worker or register accepted work.
-
-```sh
-ace-lab assignment prepare --project atlas --task 8wr.t.abc --pane w1:pS \
-  --output .ace-local/prepared-task
-ace-lab assignment request --project atlas --input .ace-local/prepared-task/request.json
+# /etc/lab/ace-lab/install.yml — root-owned deployment document
+schema_version: 1            # required, must be 1
+machine: lab01               # required identity (role/HITL addressing)
+accounts:                    # optional
+  - username: ace-worker     # ^[a-z_][a-z0-9_-]{0,31}$, unique
+    role: worker             # informational binding
+    create: false            # default; true requires administrator privileges
+    home: /home/ace-worker   # default: /Users/<u> (darwin), /home/<u> (linux)
+directories:                 # optional
+  - path: /home/ace-overseer/labs   # absolute
+    owner: ace-overseer      # optional; omitted = installer ownership
+    mode: "0750"             # optional octal string, default "0755"
+keys:                        # optional, ed25519 only (v1)
+  - account: ace-worker      # must reference a declared account
+    path: /home/ace-worker/.ssh/id_ed25519  # optional, default <home>/.ssh/id_ed25519
+roles:                       # optional
+  - id: worker               # ^[a-z][a-z0-9_-]{0,31}$, unique
+    account: ace-worker
+    instructions: wfi://assign/work  # wfi://|prompt://|tmpl:// or an absolute readable file
+projects:                    # optional (consumed by ace-lab install)
+  - id: atlas                # ^[a-z][a-z0-9_-]{0,31}$, unique
+    path: /Users/ace/lab/atlas         # absolute, unique
+    remote: git@forge:atlas/atlas.git  # optional clone source
+    label: Atlas platform    # optional display label
+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)
 ```
 
-The output directory must not exist. Preparation retains the definition, bundle,
-and registration request with one stable mutation ID. `--dependency-reports FILE`
-selects an explicit JSON array of `{task_id, assignment_id, number}` entries for
-dependency reports. A failed preparation keeps partial files for inspection;
-it never rebuilds an existing directory. In this source checkout use
-`bundle exec ace-lab` because no `bin/ace-lab` binstub is committed.
-
-Every request file has exactly these fields:
-
-```json
-{
-  "version": 1,
-  "project_id": "atlas",
-  "operation": "start_attempt",
-  "mutation_id": "original-start-001",
-  "params": {
-    "assignment_id": "assignment-id",
-    "attempt_id": "attempt-id",
-    "expected_generation": 0,
-    "scope": "010",
-    "head": "0123456789012345678901234567890123456789",
-    "pane": "w1:p2"
-  },
-  "parts": []
-}
+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`; 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;
+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
+phase *would create* are predicted (`would_create` keys, `verified`
+roles) even though the account does not exist in passwd yet; an
+existing private key with a missing `.pub` predicts
+`would_repair_public` (the wet run regenerates it); mode drift on an
+owner-matching pair predicts `would_fix_mode`; a planted `.ssh`
+symlink is refused in dry-run exactly as the wet run refuses it, and a
+missing directory whose declared owner account *failed* the account
+phase is predicted as the wet run's owner-unavailable failure (the
+orchestrator threads its computed account set into the directory
+stage). Four prediction limits: an *existing* directory whose declared
+owner account does not exist yet cannot have its ownership checked,
+and is reported as a failed item with a rerun hint; likewise, a role's
+instruction *file* readability cannot be checked against an account
+that does not exist yet (its uid is unknown), so such bindings are
+predicted `verified` from the file's existence and type alone — the
+wet run performs the full readability check; and an *existing key
+pair* under an account the phase would create cannot have its
+ownership checked either (the future uid is unknown) — a pair owned
+by neither the installer nor the to-be-created account is
+conservatively predicted as the wet run's takeover refusal, which is
+pessimistic only in the pathological case where account creation
+reuses exactly that uid. A fourth, smaller limit: when the account
+phase *would create* the account, an existing installer-owned pair (or
+installer-owned `.ssh`) is predicted as a plain `exists` even though the
+wet run would chown it to the account while converging — the transfer
+itself is not predicted.
+
+Behavior and guarantees:
+
+- **Idempotent convergence.** Existing resources are verified, not
+  recreated; only mode drift on an owner-matching directory or
+  owner-matching key pair is repaired. A pre-existing directory — or
+  key pair — owned by a different account is refused (`refusing
+  takeover`), never silently chowned, and that policy covers `.ssh`
+  itself: a pre-existing `.ssh` owned by neither the account nor the
+  installer is refused on both the create and the existing-key path
+  (wet and dry-run). Symlinks and
+  non-directories at declared paths are refused. Residual policy:
+  symlink refusal applies to the *declared leaf* path only —
+  intermediate path components are followed (and created with default
+  mode/ownership, since only the leaf carries declared values); the
+  manifest is root-owned, so this trusts the deployment document, not
+  the account.
+- **Account creation** uses the platform's own tooling (darwin
+  `dscl . -create` + `createhomedir`, linux `useradd -m`), always with
+  argv arrays. Unsupported platforms are reported with a manual remedy
+  (`create: false`). Missing administrator privileges are classified
+  with an actionable message, as is a missing account without
+  `create: true`. For an *existing* account whose passwd home differs
+  from the manifest home, the drift is reported in the message; the
+  manifest home stays authoritative (key default paths derive from
+  it).
+- **Secret hygiene.** Key pairs are generated with `ssh-keygen -t
+  ed25519`; `.ssh` is 0700, the private key 0600, the public key 0644,
+  ownership assigned to the account — and `.ssh` mode/ownership is
+  *converged* on the existing-key path too (drift predicts
+  `would_fix_mode` in dry-run and is repaired in the wet run; a
+  foreign-owned `.ssh` is a takeover refusal, see above). A pair is
+  ready only when the `.pub` fingerprint matches the public key
+  derived from the private key (`ssh-keygen -y`); unreadable or
+  mismatched pairs are `failed` items, never usable-looking
+  `exists`/`created` with no fingerprint — the unknown pair itself is
+  left untouched for manual resolution. Reports
+  carry the public
+  fingerprint only — private key material never appears in any status,
+  message, report, or diagnostic argument (the derived public key
+  exists only inside a private tmpdir for the duration of one
+  read-only comparison). Key paths inside a git
+  worktree are refused outright — judged by their PHYSICAL location
+  (existing ancestors resolved with `realpath`), so a symlinked
+  ancestor cannot smuggle a key into a repository. Planted symlinks on the
+  account-controlled paths — `.ssh` (checked with `lstat` before any
+  `mkdir`/chmod/chown, on the *existing-key* path and in dry-run too)
+  and `<key>.pub` (checked with `lstat` — including *before*
+  `ssh-keygen` on the create path, since keygen writes the `.pub` by
+  path — and written with `O_NOFOLLOW`) —
+  are refused, so a privileged run cannot be turned into an arbitrary
+  chmod/chown/write by the account.
+- **Symlink-race hardening.** Leaf directories (`.ssh` and declared
+  directories) are created with component-wise `Dir.mkdir` — whose
+  `EEXIST` on a planted symlink refuses instead of following it — and
+  re-`lstat`ed immediately after creation: a leaf that is not a real
+  directory the installer just created is refused before any
+  chmod/chown, and a directory swapped between the owner check and a
+  mode fix is re-checked before the chmod. Key *files* never carry a
+  path-based mutation: after `ssh-keygen` the pair is re-`lstat`ed
+  (a keygen writing through a swapped-in symlink is refused before any
+  ownership transfer), and every chmod/chown on the private key and
+  the `.pub` — regenerated or not — goes through an
+  `O_NOFOLLOW`-opened file handle, so a mid-flight symlink swap
+  surfaces as `ELOOP` and is refused. On the create path the `.ssh`
+  ownership transfer is *deferred* until after the post-keygen
+  verification: while `ssh-keygen` writes by path, a freshly created
+  `.ssh` is still installer-owned 0700 and unwritable by the account,
+  so nothing can be planted inside it during the keygen window.
+  Accepted residuals: a microscopic
+  window remains between that final re-`lstat` and the path-based
+  `chmod`/`chown` on a *directory* leaf (Ruby stdlib offers no fd-based
+  directory chmod); closing it would require exotic APIs for no
+  practical gain over the guard chain above — and `ssh-keygen`
+  necessarily writes by path, so the keygen step itself retains the
+  *account-owned-home rename race*: an account that already owns the
+  parent home directory can rename the installer-owned `.ssh`
+  mid-flight and substitute its own (likewise, an `.ssh` that
+  pre-exists account-owned stays writable by the account throughout).
+  The post-keygen re-`lstat` then detects the substitution after the
+  write and refuses before any ownership transfer; whatever was
+  written lands root-owned 0600 — a file-creation primitive at an
+  attacker-chosen location, not an escalation, and inside the same
+  accepted-threat envelope as the directory residual above.
+- **Role instruction reachability.** A file instruction source is
+  `verified` only when the account can actually reach it: the file's
+  read bits AND the search (`x`) bit of every ancestor directory of
+  the resolved path (ancestor symlinks followed) must grant the
+  account's governing POSIX class — owner, primary or supplementary
+  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.
+- **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
+  predicted failures). A missing, untrusted or invalid manifest is a
+  classified error naming the path, never its content.
+
+Boundaries (what `prepare` is not):
+
+- No project onboarding in `prepare` itself (`ace-lab project add`,
+  L8.2, is the dedicated command) — the manifest's role catalog
+  declares where each role lives and under which account; the
+  project-add step consumes that converged environment.
+- No full `ace-lab install` orchestration (L8.3, delivered as
+  `ace-lab install`): no project onboarding, no trusted-tier grants
+  configuration, no foreign-lab refusal — `prepare` converges the
+  machine and leaves the composition to the installer.
+- No interrupted-install resume bookkeeping (L8.4): re-running `prepare`
+  is the resume mechanism; install-level resumption composes it.
+- No end-to-end verification under the target accounts (L8.5): real
+  multi-account proof belongs to the readiness verification step.
+
+## Project add (L8.2)
+
+```bash
+ace-lab project add atlas --path /Users/ace/lab/atlas --remote git@forge:atlas/atlas.git
+ace-lab project add atlas --path /Users/ace/lab/atlas --dry-run
+ace-lab project add atlas --path /Users/ace/lab/atlas --format json
 ```
 
-Use actual retained IDs, scope, head and native pane. The actual worker executes
-its start request: the owner verifies caller ancestry, live process and checkout.
-A supervisor cannot impersonate another pane by changing `pane`. A new terminal
-or prompt acknowledgement alone is not running proof.
-
-| Operation | `params` beyond `assignment_id` | Transfer / authority |
-|---|---|---|
-| `register_assignment` | Generated by prepare | Exact prepared bundle; supervisor |
-| `registration_status` | None | Read; `mutation_id: null` |
-| `start_attempt` | `attempt_id`, `expected_generation: 0`, `scope`, `head`, `pane` | Actual worker start |
-| `assignment_snapshot` | `attempt_id` (or null), `kind: queue` or `prepared_work` | Download; `mutation_id: null` |
-| `queue_start` | `attempt_id`, `expected_generation`, `pane`, `step` (or null for next) | Original worker |
-| `queue_finish` | Same as queue_start | One UTF-8 report part |
-| `queue_fail` | `attempt_id`, `expected_generation`, `pane`, `message` | Original worker; unfinished work stays failed |
-| `submit_result` | `attempt_id`, `expected_generation`, `pane`, `head`, `receipt_sha256` | Receipt first, then its ordered artifacts; original worker |
-| `result_status` | `attempt_id` | Read; `mutation_id: null` |
-| `result_snapshot` | `attempt_id`, `result_id` | Canonical receipt/artifacts download; `mutation_id: null` |
-| `finish` | `attempt_id`, `expected_generation`, `pane`, `head`, `result_id`, `receipt_digest` | Supervisor accepts exact submitted result after settlement |
-
-Upload `parts` are ordered `{file, bytes, sha256}` entries. Relative files resolve
-beside the retained request. Changed, oversized or symlinked inputs refuse before
-connection. Requesters never supply a wire `transfer` descriptor. Downloads require
-`--output NEW_DIRECTORY`; numbered byte files and `response.json` are private
-projections of the authenticated reply, not another execution store. For queue
-snapshots, the first byte file contains the current step instructions and reports
-as JSON; prepared-work snapshots contain the original Git bundle.
-
-Retain each request and its exact parts before invoking it. On response loss,
-inspect `registration_status` or `result_status` and reuse the same original
-mutation when replay is appropriate. Never refresh its generation, replace its
-bytes, or create a second worker because a reply was lost. Queue completion and
-`submit_result` keep the attempt running; only the canonical accepted `finish`
-reply proves terminal completion. Unknown effect or Inbox settlement refuses it.
-
-These commands do not silently route to a local `ace-assign` cache. Missing or
-changed installed owner selection is an explicit failure. Native wake consumers
-must read the same canonical status and adopt its original attempt/result IDs.
-Changed owner selection refuses new admission and dispatch until a controlled
-restart. Existing canonical receipts remain the source for reconciliation.
-
-## Ordinary candidate, review and merge evidence
-
-Keep the real delivery attempt running through review, test execution and merge.
-Finish it only after settlement. A completed coder attempt can seed a new real
-registered delivery attempt; never reopen its old authority.
-
-The existing `assignment request --input request.json` interface also supports:
-
-| Operation | Params in addition to assignment_id/attempt_id/head/candidate_generation | Authority / transfer |
-|---|---|---|
-| `submit_candidate` | `pane`, `expected_generation` | Original worker; one complete Git bundle; candidate_generation is the previous generation (0 initially) |
-| `assign_review` | `pane`, `expected_generation`, `reviewer_assignment_id`, `reviewer_attempt_id` | Current canonical supervisor selects an already started independent reviewer |
-| `export_candidate` | `pane`, `review_id` | Assigned reviewer; null mutation; `--output NEW_DIRECTORY` downloads canonical bundle |
-| `accept_review` | `pane`, `expected_generation`, `review_id`, `receipt_sha256` | Assigned reviewer uploads exact receipt followed by its ordered report artifacts |
-| `cancel_review` | `pane`, `expected_generation`, `review_id` | Current supervisor revokes that exact review |
-| `review_status` | None | Null mutation; revalidates accepted original receipt and artifacts |
-| `merge_evidence` | `test_execution_ids` (nonempty array) | Null mutation; projects exact accepted review and canonical executed-test references |
-
-First submit the candidate, retaining its returned head, tree and new generation.
-Prepare/register/start a separate review assignment through the ordinary native
-entry. Its agent must have a different actual process generation, session UUID
-and pane. The supervisor assigns that exact reviewer assignment/attempt at its
-honestly observed starting base. Export gives the assigned agent canonical candidate
-bytes; it then materializes/checks out the candidate. Receipt acceptance requires
-that exact candidate HEAD and the unchanged original native reviewer binding. A receipt uses the delivery attempt's identifiers,
-scope and actual producer; its `review.reviewer.actor` is the real reviewer's
-account. The owner derives independence from authenticated native origins, so
-shared-account agents do not need invented actor aliases.
-
-`accept_review` retains the original receipt and up to 15 report artifacts in
-CanonicalEvidence, verifies their exact digests, and returns the accepted review
-ID/digest. The receipt declares operation review, succeeded, approved at the exact
-candidate head, and executed review checks. These review checks are not test
-execution authority. Missing/corrupt reports, a different caller, terminal delivery
-attempt, changed head/generation or cancellation refuse. Retrying the exact
-accepted mutation cannot accept a second review; changed bytes under that mutation
-refuse. This first ingress accepts direct independent review of the exact candidate
-generation. Campaign receipts and accepted-head carry are deliberately unavailable
-until the existing ace-review campaign/assessment owner is connected; a head change
-currently refuses prior approval. This is a remaining delivery capability, not the
-final policy of requiring a full independent review after every SHA change.
-
-Execute the project's root-selected test command through the existing command
-transport. Only an explicit `purpose: test` definition with exact immutable
-candidate head/tree, root-witnessed child, and canonical exit0/no signal can supply
-test evidence. `merge_evidence` resolves those execution IDs and returns
-`review_evidence` and `test_evidence` for the fixed merge request. Copy those exact
-projections into the retained request before obtaining its digest-bound decision.
-Plain worker check strings or generic allowed commands are not substitutes.
-
-The sole owner revalidates evidence in the merge admission CAS and before each
-Forge effect. Assignment exclusion prevents candidate changes, review cancellation
-or finish racing an executing merge. Policy revocation or missing canonical bytes
-refuses without dispatch. Existing unknown outcomes retain their original merge
-reference and require reconciliation.
-
-The dynamic candidate-to-immutable-command-view binding and installed two-worker
-acceptance remain separate required gates. Static source fixtures do not authorize
-per-PR administrative head/path edits or claim installed autonomous merging.
-
-## Ordinary driver and supervisor recovery
-
-`ace-overseer ordinary --operation prepare` retains one context per fresh worker.
-From that worker's native tool process, drive only the installed owner:
-
-```sh
-ace-lab assignment drive --project atlas --context /private/work/context.json --operation status
-ace-lab assignment drive --project atlas --context /private/work/context.json --operation start
-ace-lab assignment drive --project atlas --context /private/work/context.json --operation bootstrap --output /private/work/accepted-context
-ace-lab assignment drive --project atlas --context /private/work/context.json --operation next
-ace-lab assignment drive --project atlas --context /private/work/context.json --operation step-start --generation 1 --step 010.01.01
-ace-lab assignment drive --project atlas --context /private/work/context.json --operation step-finish --generation 2 --step 010.01.01 --report /private/work/check.md
+`project add` makes a project ready for team work (task 8xg.t.sbz.7.1),
+assuming `ace-lab prepare` (L8.1) already converged the machine-level
+accounts, directories, keys and roles. Three steps run in a fixed order:
+
+1. **repository** — the target path becomes a Git repository with the
+   declared origin remote. A missing or empty path is cloned from
+   `--remote`; an existing repository without an origin gets one; an
+   existing repository with a *different* origin is refused as a
+   contradictory registration, and a non-empty non-repository path is
+   refused as a foreign location — never taken over, never overwritten.
+   The path itself must be the repository toplevel: a directory nested
+   inside another repository's work tree is refused as foreign.
+2. **overseer** — the private, untracked `.ace-tasks/_overseer/` folder
+   is created (ADR-034) and its `.gitignore` entry ensured. Existing
+   `.gitignore` content and folder content are never touched; the
+   folder is never enumerated.
+3. **registry** — the project is registered in `<path>/.ace/lab/config.yml`
+   (the project tier of the ordinary ADR-022 lab-config cascade) with
+   its `id`, `label`, absolute `path` and `remote`. Because every
+   consumer already reads that cascade, `ace-lab status` shows the
+   project (`configured`, topology counts) and `ace-lab projects` /
+   `ace-overseer projects` list it — no second registry exists, and
+   `ace-overseer` needed no read-side change. Two prerequisites for
+   that listing: grants come exclusively from the trusted tier of the
+   cascade, so listing the new project id requires a trusted-tier
+   principal grant covering it — configuration the installer (L8.3)
+   owns, not `project add` — and the project-tier document only enters
+   the cascade when the command runs from the project root (cascade
+   tiering). The `path` and `remote` registry fields are
+   installer-owned deployment data and are not exposed in the public
+   projection.
+
+The planner chain consumes the result directly: `ace-coworker prepare`
+provisions task worktrees from the registered repository, and the
+overseer's private queue lives in the prepared `_overseer` folder —
+no manual directory fixing is needed.
+
+Statuses per step: `created|exists|updated|would_create|would_update|failed`.
+`ok` means
+zero failed steps; a wet run with failures prints the report first,
+then exits non-zero naming each step. `--dry-run` predicts
+(`would_*`) with zero mutations and exits 0.
+
+Idempotence and refusals:
+
+- Re-adding an already-registered project re-validates every step and
+  reports `exists` without rewriting the registry, the `.gitignore`,
+  or anything inside `_overseer`. A changed `--label` on re-add
+  updates the recorded label (display data, not identity) and reports
+  `updated`; an omitted `--label` keeps the recorded one.
+- The same id registered with a different `path` or `remote`, or the
+  same absolute `path` registered under a different id, is refused
+  before any write.
+- An unparseable registry document or a foreign `schema_version` is
+  refused rather than overwritten.
+- A failed repository step fails the overseer and registry steps as
+  dependency failures instead of attempting them.
+
+Boundaries: `project add` does not clone role accounts or keys (L8.1
+owns those), does not configure HITL adapters or run the full install
+(L8.3/`ace-lab install`), and adds no new state owner — the only
+persisted artifact is the project's own lab-config cascade document.
+
+## Install (L8.3)
+
+```bash
+ace-lab install              # full installation from the trusted manifest
+ace-lab install --dry-run    # predict every phase without mutating
+ace-lab install --format json
 ```
 
-Use returned generations and actual step numbers, not the illustrative values.
-`HERDR_PANE` supplies the caller pane unless `--pane` is explicit; the selected
-owner authenticates actual native ancestry independently. `bootstrap` returns
-accepted context paths, byte counts, SHA256 values and manifest digest. `next`
-reads the canonical queue including reports and returns current/next instructions.
-`fail --generation N --message REASON` records a failed scope; it never fabricates
-successful completion. The workflow `wfi://assign/drive` selects this protocol
-before local assignment resolution when `--ordinary`/the ordinary environment
-is present.
-
-Submit one bounded execution receipt JSON with the following fields, using
-actual observed values (no placeholders in submitted evidence):
-
-```json
-{
-  "assignment_id": "original-assignment", "attempt_id": "original-attempt",
-  "project_id": "atlas", "scope": "010.01", "operation": "check",
-  "producer": {"actor": "actual-user", "role": "worker", "runtime": "herdr"},
-  "head": "0123456789012345678901234567890123456789",
-  "verdict": "succeeded", "checks": [{"name": "tests", "verdict": "passed"}],
-  "artifacts": [{"path": "check.md", "sha256": "actual-64-hex-artifact-digest"}]
-}
+`install` performs the full new-lab installation (task 8xg.t.sbz.7.2)
+from the same trusted install manifest as `prepare`, by composing the
+existing molecules in a fixed order:
+
+1. **Foreign-lab guard — before any mutation.** The trusted
+   authorization document `/etc/lab/ace-lab/authorization.yml` (when
+   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 → 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
+   others. When `prepare` did not converge, every project is reported
+   as a dependency failure instead of being attempted.
+4. **grants** — the trusted-tier principal grants from the manifest's
+   `grants` section are converged into the `principals` mapping of the
+   authorization document: this is the installer-owned configuration
+   that makes the installed projects visible to `ace-lab projects` and
+   `ace-overseer projects` (see the L8.2 boundary above). Grants only
+   grow: a manifest that would remove an existing grant is refused.
+   Principals the manifest does not mention and every other section of
+   the document (e.g. HITL adapter policy) are preserved untouched —
+   and a converged re-run writes nothing at all, so the document's
+   admin-authored comments stay byte-identical. A manifest with no
+   `grants` over an absent document is a no-op (`skipped`): no empty
+   authorization file is ever created. Before any write the existing
+   document's principals are validated exactly like the read side
+   (shared validation with the grants resolver): a malformed policy is
+   refused with a classified error instead of silently rewritten, and
+   whitespace-padded principal names are normalized so they cannot
+   coexist with a stripped twin.
+   The write is atomic (temp file + rename, mode 0644). Grants are
+   configured only when the earlier phases converged — never over a
+   partially failed install (no pretend success).
+
+Statuses: `prepare` contributes its own per-item statuses; each project
+contributes `created|exists|updated|would_*|failed` per step; grants
+report `created|updated|exists|skipped|would_*|failed` plus a
+per-principal breakdown and the `kept` list (present and possibly
+empty, so machine consumers see a stable schema). `ok` means every phase converged. A wet run with failures
+prints the report first, then exits non-zero enumerating each
+`<phase>/<item>: <message>`; `--dry-run` predicts with zero mutations
+and exits 0.
+
+Idempotence and resume design: every step is idempotent, so an
+interrupted re-run converges where steps already completed (accounts
+`exists`, repositories `exists`, grants `exists`) without duplicates or
+lost configuration — the per-step record is the resume mechanism; no
+journal exists or is needed for convergence. See
+[Resuming an interrupted install](#resuming-an-interrupted-install-l84).
+
+### Resuming an interrupted install (L8.4)
+
+```bash
+ace-lab install              # same command: recognizes and finishes its own partial state
+ace-lab install --dry-run    # previews exactly which steps exist and which would run
 ```
 
-The producer comes from canonical start status; checks and artifacts must describe
-executed work. Run `--operation result --generation N --receipt receipt.json
---artifact check.md` with files in receipt order. The existing receipt verifier
-and canonical import validate attribution, evidence and exact bytes. A result
-submission leaves the worker running until its canonical supervisor executes
-`--operation adopt` and receives terminal status. Keep the actual worker process
-and checkout alive until that acceptance; a terminal pane without the required
-native binding is insufficient.
-
-Mutations retain their exact request and transferred bytes under the original
-context directory before sending. A lost response is recovered with canonical
-`status`/`next`, then `--operation replay --request /original/requests/.../request.json`.
-Never update an existing request's generation, mutation ID or bytes to force a
-retry. The requester directory is not an accepted-state store. The result hint
-file is ignored by canonical reads/adoption, including when forged or stale.
-Inbound Inbox settlement is not provisioned by this driver; nonempty references
-still require the separately selected existing Inbox owner and fail closed otherwise.
-
-A replacement coordinator reads `--operation supervisor`, then from its actual
-installed native supervisor placement uses:
-
-```sh
-ace-lab assignment drive --project atlas --context /private/work/context.json \
-  --operation adopt-supervisor --generation 1 --previous-binding-sha256 EXACT_OLD_DIGEST
-```
-
-The definition chain records old→new bindings under its original generation CAS.
-Only a positively ended old generation (kernel process absence or a different
-exact process birth) permits adoption; live, inaccessible, remote-host and unknown
-identities refuse. A lost adoption response reuses its original retained request.
-No worker is re-registered or relaunched. Existing pending results, uncertain
-operations, attempts and request IDs remain unchanged. Finish, including replay,
-checks the current canonical supervisor binding and rejects the displaced one.
-
-Wire additions are `supervisor_status` (assignment only, null mutation), and
-`adopt_supervisor` (assignment, actual pane, expected definition generation,
-previous_binding_sha256; original mutation). They use the same installed owner,
-project policy, journal and lifecycle exclusion as ordinary execution.
-
-## Error semantics
-
-Errors are one deterministic JSON document on stdout plus a non-zero exit.
-
-| Code | Meaning |
-|------|---------|
-| `missing` | No entry with that stable ID, or no capable service in the project |
-| `ambiguous` | Several equally capable services without a configured `default_for` |
-| `stale` | Binding is inactive, unattested, or the instance identity was replaced |
-| `unauthorized` | Caller's verified local identity has no principal for the project |
-| `invalid_configuration` | Topology config violates the schema; message is actionable |
-| `invalid_input` | Service input or request ID is malformed |
-| `invalid_attempt` | Assignment attempt is absent, unmanaged, terminal, or has a stale candidate head |
-| `conflict` | Request ID is already bound to different input or scope |
-| `evidence_unavailable` | Assignment evidence ref cannot be written or read |
-
-Example:
-
-    $ ace-lab resolve --id atlas-coder --format json; echo $?
-    {"status":"error","error":{"code":"stale","message":"stable ID \"atlas-coder\" has a stale runtime binding; a replaced process must re-attest before routing","id":"atlas-coder","project":"atlas"}}
-    1
-
-## Configuration
-
-Schema version 1, resolved through the ADR-022 cascade (project `.ace/lab/`
-over user `~/.ace/lab/` over gem defaults; gem defaults are an empty, safe
-topology). Cascade documents carry **topology only**:
-
-```yaml
-schema_version: 1
-topology:
-  projects:
-    - id: atlas               # globally unique across all entries
-      label: Display name     # display only; never resolves
-  agents:
-    - id: atlas-planner
-      project: atlas          # must reference an existing project
-      role: planner
-      capabilities: [planning]  # non-empty; normalized (stripped, lowercased)
-      binding:
-        kind: runtime           # agents bind to runtimes, services to services
-        state: active           # routeable only when active
-        instance_id: i1         # runtime identity fact
-        attested_instance_id: i1  # must equal instance_id to be fresh
-  services:
-    - id: atlas-search
-      project: atlas
-      capabilities: [search]
-      default_for: [search]     # exactly one default may win among candidates
-      endpoint:
-        kind: http              # http or https
-        url: "https://search.example.internal/query?token=secret"  # stored, never published
-      binding: { kind: service, state: active, instance_id: i2, attested_instance_id: i2 }
-```
-
-### Authorization grants
-
-Grants never live in the cascade: project and user documents are
-caller-writable, so an `authorization` section there is rejected as
-`invalid_configuration`. Grants come from a single deployment-controlled
-file at the **fixed path** `/etc/lab/ace-lab/authorization.yml` (installed
-by the `lab-config` deployment). The location is not caller-selectable --
-there is no flag or environment override. At every query the tool verifies
-the file and every directory on its real path are root-owned and not
-group/world-writable, and opens the file `O_NOFOLLOW`; any failed
-verification fails closed:
-
-```yaml
-principals:
-  "<verified-local-uid>":     # passwd username or numeric uid of the caller
-    projects: ["atlas"]
-```
-
-The grants file is machine-global: it is validated structurally only, so a
-principal may reference projects absent from the current directory's
-topology. Such grants are valid but never match a locally configured
-project. All-digit principal keys are matched as uids only -- an all-digit
-passwd username is authorized solely through its uid, so it can never
-consume a different account's numeric-uid grant.
-
-A missing trusted file means nobody is authorized (fail closed).
-
-### Trusted service policy
-
-The same deployment-owned file may contain `operations` and
-`authorizations`. An operation names one exact project and stable service ID,
-an executor OS UID, a valid lease, and either a fixed local argv or an absolute
-Unix socket path. The domain deployment owns actual handlers and credentials.
-The Unix service must authenticate the client's OS peer identity, validate
-the exact authorization and current lease itself, and return a structured
-receipt; ACE verifies the service peer UID before accepting that response.
-
-```yaml
-operations:
-  forge-sync:
-    project: atlas
-    service_id: atlas-sync
-    transport: unix
-    socket_path: /run/lab/atlas-sync.sock
-    executor_uid: 997
-    lease_expires_at: '2026-10-02T16:00:00Z'
-authorizations:
-  DECISION:
-    operation: forge-sync
-    project_id: atlas
-    assignment_id: A
-    attempt_id: ATT
-    input_digest: <sha256-of-canonical-json>
-    target: { resource: forge/repository, artifact_digest: null }
-    candidate_head: <exact-git-head>
-    caller_uid: 1000
-    expires_at: '2026-10-02T16:00:00Z'
+An installation interrupted mid-run (crash after accounts, directories,
+keys, a project, or part of the grants) is resumed by running the same
+`ace-lab install` command again. Recognition is derived from the real
+artifacts the steps read and write — there is no journal, marker file
+or second state owner:
+
+- already-done steps report `exists`/`verified` and are not reworked:
+  the converged directory and key pair keep their inode and content, an
+  already-cloned repository keeps its worktree (untracked files
+  included) and a converged trusted document stays byte-identical;
+- missing steps complete: a key pair whose public half is missing
+  regenerates only that half from the surviving private key; a project
+  whose repository exists finishes only `_overseer` and the registry;
+  partially granted own principals converge while principals and
+  sections the manifest does not mention are kept;
+- grants are configured only when prepare and every project converged
+  (no pretend success over a partial install).
+
+Own-partial vs foreign is distinguished per step, not only for grants:
+each already-present artifact is checked against what the manifest
+declares before it is touched, and mismatching content is refused —
+never taken over, never cleaned:
+
+| Step | Foreign state | Result |
+| --- | --- | --- |
+| 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 |
+
+When resume is not possible, the wet failure names every blocking step
+concretely (`install failed (N step(s)): <phase>/<item>: <message>`);
+`--dry-run` predicts the same per-step refusals with zero mutations
+and exits 0.
+
+Boundaries: `install` does not verify readiness under the target
+accounts (that is `verify`, below); HITL adapter configuration beyond
+preserving the existing trusted document sections is not orchestrated
+by this slice.
+
+## Verify (L8.5)
+
+### `ace-lab verify [--format table|json] [-q]`
+
+```bash
+ace-lab verify                 # per-check table; exit 0 only when ready
+ace-lab verify --format json   # stable machine report for the overseer / next tool
 ```
 
-The decision must match every listed field exactly and remain valid. A
-decision never supplies missing executor capability or credentials. For
-authenticated host maintenance, the policy also identifies an executable and
-evidence sink outside the deployment being replaced; its domain handler must
-enforce quiescence for all other product work. Environment `review-approval`
-is a named operation and never substitutes for an independent code review.
-
-Validation of the topology cascade rejects duplicate IDs (globally unique
-across projects, agents, services), unknown project references, malformed
-capabilities, defaults for undeclared capabilities, unusable endpoints
-(absolute http(s) URL with a host and a port in 1–65535; `endpoint.kind` is
-`http` or `https`), unsupported binding kinds, and principals referencing
-unknown projects.
-
-**Error messages are value-free by design:** validation runs before
-authorization, so messages use positional field locations
-(`topology.agents[0].project references an unknown project`) and never echo
-configured IDs, project names, or principal names -- configuration defects
-cannot disclose topology to unauthorized callers.
-
-**Ownership:** deployed topology and authorization values are maintained by
-the `lab-config` repository (`8wl.t.gad`). `ace-lab` defines the schema and
-reads; it never provisions.
-
-## Guarantees and boundaries
-
-- Public output is built from a strict allowlist: `id`, `project`, `label`,
-
-  `role`, `capabilities`, `default_for`, binding `kind` + availability state,
-  and a sanitized endpoint identity. Tokens, auth-file paths, URL userinfo,
-  paths, query parameters, fragments, pane/session IDs, and instance
-  identities never appear in any command output.
-
-- Caller identity comes from the verified local process owner
-
-  (username or uid). `--role`, `--principal`, and `--caller` flags are
-  rejected: authorization is a property of the caller, not an input.
-
-- A replaced process keeps its stable ID; until re-attested, queries
-
-  classify it `stale` -- an explicit unavailable result, never a routeable
-  answer.
-
-- No Works or scheduling. Service request claims and receipts use
-
-  `ace-assign`'s evidence journal. The Lab execution binary
-  (`/usr/local/bin/lab`) is never invoked or required.
-
-### Protected handler cleanup boundary
-
-Handlers retain the fixed closed environment and 30-second execution deadline, with 16KiB stdout and 8KiB stderr caps. Owned cleanup adds at most one second of confirmed reaping; unresolved cleanup remains uncertain and cannot return a service receipt. It cannot establish an arbitrary domain target or surviving writer is absent. The gad.b operation-specific fresh inspector remains required source work; installed verification is centralized in gad.2.
-
-### Selected receiver no-effect recovery
-
-The existing protected receiver exposes `recover_no_effect(binding:, input_bytes:, mutation_id:, expected_generation:)`. Supply the original assignment/attempt/candidate/head/request binding, original structured input, stable mutation ID and unchanged original positive authority generation. The receiver snapshots those inputs, authenticates canonical status and input before any settled return, and adopts an already accepted current challenge without claiming again. A needed claim uses the supplied generation unchanged. Lost acknowledgements remain uncertain; status retry never repeats the original effect.
-
-Trusted operation configuration must provide a distinct fixed `no_effect_argv` for the original project/service/executor. Inspection may proceed after the effect lease expires, but it never renews effect permission or selects normal effect argv. The selected inspector must produce operation-specific original target/handler/writer observations and existing strict challenge-bound artifacts; only the authority's canonical import can establish `failed-settled`. This source API and controlled composition do not deliver the outstanding gad.b inspector or installed acceptance.
-
-## Project commands
-
-`ace-lab run --project ace -- /usr/bin/id` invokes one exact installed command
-policy. `--as publisher` selects a permitted executor; repeated `--service NAME`
-replaces the configured default set. Every service and the entire combination
-must be granted. Arguments after `--` remain literal, including command options.
-No shell is added. Duplicate `--project`/`--as` or empty argv are usage errors.
-
-The root-owned `/etc/lab/ace-lab/project-commands.yml` is the only command-policy
-source. Project preferences and caller environment cannot create grants. Its
-version1 project entries contain `launcher`, `default_executor`, `default_services`,
-`executors`, `services`, `commands`, and `grants`. Executors declare UID/GID/groups,
-HOME/cwd/PATH and nonsecret environment; services declare nonsecret environment
-and secret references; commands bind exact argv, executable SHA256, source
-head/tree and required `purpose: command` or `purpose: test`. Test purpose requires
-nonnull source head/tree and is never inferred from executable name or exit0.
-With `purpose: command`, source head/tree may both be null for a non-Git probe;
-Git source uses two exact object IDs. Grants bind requester kind/UID, command, executor
-and the exact service combination. Accepted code/cwd must be root-owned and
-unwritable by the executor. Missing or changed context refuses execution.
-
-An operator grant authorizes an OS account. Agents sharing that account share
-its operator authority; an environment hint does not prove human presence.
-Agent-selected invocation additionally checks actual current native ancestry.
-Separate identities are required when operator authority must exclude agents.
-
-The CLI retains an invocation under `.ace-local/lab-commands/` and prints its
-execution reference before contacting the canonical Assign owner. Inspect it with
-`ace-lab run-status --project ace --reference REF`. Inspection starts no command
-and remains available to the original requester account after a grant is revoked.
-After response loss, inspect that original reference before requesting new work.
-An existing claim or a replayed acknowledgment cannot release another child.
-
-Interactive terminals preserve no-echo input, dimensions and signals. Pipe mode
-preserves EOF, separate stdout/stderr and actual exit/signal status. Socket closure
-without the authenticated result is uncertainty. Root launch/exit observations
-remain separate from accepted product delivery evidence; exit0 alone does not
-prove publication, installation or completed delivery.
-
-This implementation slice admits nonsecret commands. A nonempty selected secret
-reference set is explicitly refused before claim until the secret execution
-capability is supplied. Publication also requires the publisher's writable
-artifact/cache destination outside immutable accepted source, or retained exact
-artifacts. These remaining joins and installed acceptance are tracked by ei9 .5;
-source/kernel fixture success does not assert installed autonomous publication.
-
-In interactive mode, input EOF sends the terminal's conventional Ctrl-D byte; a
-program that changes its terminal to raw mode may interpret that byte itself.
-Noninteractive EOF closes the command input pipe. The dedicated Linux helper owns
-and reaps detached command descendants as well as the original process group.
+`verify` is the read-only end-of-install check that the lab is ready
+UNDER THE TARGET ACCOUNTS — not merely for the installer's account. It
+reads the same artifacts `install`/`prepare` derive truth from (the
+trusted install manifest, the filesystem's permission bits and
+ownership, the repositories, the per-project registry and the trusted
+authorization document) and writes nothing anywhere: no journal, no
+second state owner. (The key fingerprint probe may use an ephemeral
+tmpdir scratch — 0600, removed afterwards — never a durable write.)
+Because it judges converged artifacts only, a
+fresh install and a resumed one verify identically — there is no
+hidden gap after resume.
+
+Per-check sections, each reported as `pass` / `fail` / `unknown` with
+a concrete reason (never a bare boolean):
+
+| Section | Checks, as the target account |
+| --- | --- |
+| accounts | account exists; home matches the manifest; login shell is usable (non-login shells block readiness) |
+| directories | declared directory exists with the declared mode and owner |
+| keys | the pair is usable: modes (0600/0644/`.ssh` 0700), account ownership, and the public fingerprint matches the key derived from the private half (the same probe `prepare` applies) |
+| roles | instruction source readable by the role's account (the `prepare` role verifier) |
+| repositories | the path is the repository toplevel, the origin matches the manifest remote; local origins are probed with `git ls-remote`, network origins are reported `unknown` (not dialed by the read-only verifier) |
+| 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
+JSON), then the command exits non-zero naming every failed check
+concretely (`lab is not ready (N failed check(s)): <section>/<item>:
+<reason>`). `unknown` (a network remote) is reported and counted but
+does not block readiness — it is not a failure, and treating it as one
+would make `verify` unusable offline. The JSON report shape is stable:
+`ready`, `machine`, `manifest`, `authorization_path`, `checks`
+(per-section lists), and `counts` (`pass`/`fail`/`unknown`).
+
+Key material hygiene is inherited from the provisioner: only the
+public fingerprint ever appears in a report; private key bytes stay
+inside the `ssh-keygen` subprocess.
+
+## Planned waves
+
+> **L7 remainder:** `ace-lab status` is delivered; the remaining L7 scope
+> (configurable `ace-overseer status` aggregation, pi continuation) lives in
+> its own packages and is not available yet.
+>
+> **Planned (L8):** the preparation phase is delivered as `ace-lab
+> prepare` (L8.1), project onboarding as `ace-lab project add` (L8.2),
+> the full installer as `ace-lab install` (L8.3), resuming the
+> installer's own interrupted installation as the same `ace-lab
+> install` re-run (L8.4), and end-to-end readiness verification under
+> the target accounts as `ace-lab verify` (L8.5).
+
+## Boundaries
+
+`ace-lab` owns no task, assignment, HITL, or worktree state. There is no
+journal, authority/admission service, daemon, queue engine, command kernel, or
+extra state cache in this package.
+
+The installed authority/admission/journal/command path is removed in L1: the
+`service request|status|listen`, `ace-lab assignment …`, `run`, `run-status`,
+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.