@vibelord/lanes 1.0.2 → 1.0.3

package/payload/lanes/libexec/studio_host.py

@@ -0,0 +1,1608 @@
+#!/usr/bin/env python3
+"""The Throttle Studio Host co-located on this lanes server (docs/SHARING.md "Co-located Studio Host";
+docs/design/throttle-studio.md §8.10 C3). Python 3 stdlib only.
+
+  lanes studio-host status [--json] [--check]
+      what is installed, enrolled and running; exit 0 only when the Host runs enrolled (and, with --check, its
+      own `studio host --check` exits 0)
+  lanes studio-host re-key [--yes] [--dry-run]
+      after a revoke: stop the Host, remove the machine key, its dead enrolment and every record of it, and publish
+      a NEW public key for the next deploy (or a registration key) to enrol. Nothing changes without --yes.
+  lanes studio-host install [--from PATH [--sha256 HEX]]
+      select the throttle-rc binary the unit runs: the holders.lock opt-in pin (download, both digests checked),
+      or a locally built file (hashed, copied, re-hashed). Never starts or restarts anything.
+  sh install/enable-studio-host.sh [options]      (→ `enable`; --help lists the options)
+      the opt-in step: config in lanes-server mode, the machine's PUBLIC key for the deploy, enrolment from a
+      deploy receipt or a registration key, the units — or the unit installed WAITING for enrolment.
+  lanes-studio-host-enrol.service runs `enable --retry`: acts only on something new, never loops on a refusal.
+
+Invariants (design §8.10 C5, each pinned by tests/unit/test_studio_host.py):
+  * the machine key is created ON THIS MACHINE by `throttle-rc studio publish-key`; this module never reads it;
+  * no bearer secret is created or stored: the receipt is inert, the registration key is read by throttle-rc
+    from its 0600 file and never by this module — not opened, not hashed: its stat identity and access(2) only
+    (review round 5);
+  * one Host per machine: refused while `throttle-rc studio service`'s own unit is enabled or active, and the
+    hand-built `lanes-sharing-host.service` is only replaced with --migrate-hand-built, after its text is saved;
+  * throttle-rc children get an allowlisted environment, nothing else from the caller.
+"""
+import base64
+import errno
+import hashlib
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tarfile
+import tempfile
+import time
+from pathlib import Path
+
+UNIT = 'lanes-studio-host.service'
+ENROL_SERVICE = 'lanes-studio-host-enrol.service'
+ENROL_TIMER = 'lanes-studio-host-enrol.timer'
+SUPERVISOR_UNIT = 'throttle-rc-studio-host.service'   # `throttle-rc studio service install`'s own unit (design §8.9)
+HAND_BUILT_UNIT = 'lanes-sharing-host.service'        # ceobox's hand-built sharing Host (docs/handoffs/2026-09-22)
+BINARY = 'throttle-rc'
+PIN_RECORD = 'throttle-rc.pin.json'
+LOCK_OPT_IN = 'opt-in'
+CONFIG_HEADER = '# Written by lanes/install/enable-studio-host.sh'
+HEX64 = re.compile(r'^[0-9a-f]{64}$')
+VERSION_WORD = re.compile(r'^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$')
+MACHINE_ID = re.compile(r'^[A-Za-z0-9._-]{1,64}$')
+# Only these reach a throttle-rc child (C5): directories and locale, never a token or a key from the caller.
+ENV_ALLOWLIST = ('HOME', 'USER', 'LOGNAME', 'PATH', 'LANG', 'LC_ALL', 'TMPDIR', 'XDG_CONFIG_HOME', 'XDG_DATA_HOME',
+                 'XDG_RUNTIME_DIR', 'DBUS_SESSION_BUS_ADDRESS', 'LANES_STATE', 'LANES_SHARE', 'LANES_WORKSPACES')
+SYSTEMCTL_TIMEOUT = 30
+RETRY_KEY_AFTER = 3600
+RECEIPT_REFUSAL_MEMORY = ('receipt_refused_sha', 'receipt_refused_config_sha', 'receipt_refused_at',
+                          'receipt_refused_code')
+# Review round 6: what `studio enroll` answered for the key the timer remembers trying (exit and code), so `status`
+# can say the key was refused instead of pointing at the deploy for the hour the timer skips it.
+KEY_REFUSAL_MEMORY = ('key_failed_exit', 'key_failed_code')
+# The two provenance marks throttle-rc writes into a refused state.json's detail (apps/throttle-rc/src/studio_host/
+# mod.rs PLATFORM_REFUSAL_MARK / SELF_REVOKE_MARK; pinned by a test that reads that file). A revocation is MEASURED
+# only with one of them, for this config's server — the rule `measured_revocation` applies.
+PLATFORM_REFUSAL_MARK = '[platform refused this dial]'
+SELF_REVOKE_MARK = '[measured by `throttle-rc studio revoke` on this machine]'
+# Review round 3: a non-default --receipt / --registration-key-file is REMEMBERED in the enrolment record, so the
+# timer (which runs `--retry` with no options) and `status` watch the path the operator named.
+REMEMBERED_PATHS = {'receipt': 'receipt_path', 'key_file': 'registration_key_path'}
+# The timer's memory of a tried registration key (review round 5): its stat identity, never a digest of its bytes.
+# `key_tried_sha` is the round-1..4 spelling (a SHA-256 of the secret); it is dropped wherever the record is saved.
+LEGACY_KEY_DIGEST = 'key_tried_sha'
+# The lines whose loss changes what the unit DOES (design §8.9 reasons). `status` reports an installed unit missing
+# any of them; the golden test has a sabotage arm per line.
+UNIT_CONTRACT = ('SuccessExitStatus=3', 'KillSignal=SIGINT', 'KillMode=process', 'Restart=on-failure',
+                 'Slice=lanes.slice', 'After=lanes-statusd.service', 'Wants=lanes-statusd.service',
+                 ' studio host --config "')
+
+
+class Refusal(Exception):
+    """A typed refusal: `refused <code>: <sentence>` on stderr, exit `code_exit` (3 unless said otherwise)."""
+
+    def __init__(self, code, sentence, exit_code=3):
+        super().__init__(sentence)
+        self.code, self.sentence, self.exit_code = code, sentence, exit_code
+
+
+class EnrolmentRefused(Refusal):
+    """`studio adopt-receipt` or `studio enroll` did not enrol this machine (typed or not): the units are still
+    installed waiting, so the enrol timer can retry (review round 3)."""
+
+
+# ------------------------------------------------------------------------------------------------ paths
+
+class Layout:
+    """Every path this module touches, from one environment. Mirrors throttle-rc's RuntimePaths (dirs crate:
+    $XDG_CONFIG_HOME|~/.config, $XDG_DATA_HOME|~/.local/share) and the lanes installer's LANES_SHARE/LANES_STATE."""
+
+    def __init__(self, home, share, state, config_home=None, data_home=None):
+        self.home = Path(home)
+        self.share = Path(share)
+        self.state = Path(state)
+        self.config_home = Path(config_home) if config_home else self.home / '.config'
+        self.data_home = Path(data_home) if data_home else self.home / '.local/share'
+
+    @classmethod
+    def from_env(cls, env=None):
+        env = os.environ if env is None else env
+        home = Path(env.get('HOME') or Path.home())
+        return cls(home, env.get('LANES_SHARE') or home / '.local/share/lanes',
+                   env.get('LANES_STATE') or home / '.local/state/lanes',
+                   env.get('XDG_CONFIG_HOME') or None, env.get('XDG_DATA_HOME') or None)
+
+    config = property(lambda self: self.config_home / 'throttle-rc/studio-host.toml')
+    registration_key = property(lambda self: self.config_home / 'throttle-rc/registration.key')
+    credential = property(lambda self: self.data_home / 'throttle-rc/studio-host/credential.json')
+    machine_key = property(lambda self: self.data_home / 'throttle-rc/machine/key.json')   # existence only
+    host_state = property(lambda self: self.data_home / 'throttle-rc/studio-host/state.json')   # the Host's own
+    binary = property(lambda self: self.share / 'bin' / BINARY)
+    pin_record = property(lambda self: self.share / 'bin' / PIN_RECORD)
+    studio_state = property(lambda self: self.state / 'studio-host')
+    public_jwk = property(lambda self: self.studio_state / 'public.jwk')
+    receipt = property(lambda self: self.studio_state / 'receipt.json')
+    record = property(lambda self: self.studio_state / 'enrolment.json')
+    migrated = property(lambda self: self.studio_state / 'migrated')
+    units = property(lambda self: self.home / '.config/systemd/user')
+
+
+def sha256_file(path):
+    digest = hashlib.sha256()
+    with open(path, 'rb') as handle:
+        for block in iter(lambda: handle.read(1 << 20), b''):
+            digest.update(block)
+    return digest.hexdigest()
+
+
+def readable_sha(path, code, remedy):
+    """sha256 of a file the installer acts on, or None when it is absent. A file that exists but this account
+    cannot read is a typed refusal naming its owner and mode (review round 2: an unreadable receipt crashed every
+    timer run with a PermissionError traceback, untyped exit 1, while `status` promised the timer would install it)."""
+    if not path.is_file():
+        return None
+    try:
+        return sha256_file(path)
+    except OSError as error:
+        raise Refusal(code, f'{path} exists but this account cannot read it ({unreadable_detail(path, error)}); '
+                      + remedy)
+
+
+def unreadable_detail(path, error):
+    try:
+        stat = os.stat(path)
+        owner = f'owner uid {stat.st_uid}, mode {stat.st_mode & 0o7777:04o}'
+    except OSError:
+        owner = 'owner and mode unknown'
+    return f'{error.strerror or error}; {owner}; this account is uid {os.getuid()}'
+
+
+def key_fingerprint(path, remedy):
+    """The registration key's identity for the timer's hour-long memory, WITHOUT reading it (design §8.10 C5;
+    review round 5 — this used to hash the secret's bytes into the enrolment record). None when absent. A file this
+    account may not read is the typed `key_unreadable` refusal, decided by access(2): the file is never opened."""
+    if not path.is_file():
+        return None
+    if not os.access(path, os.R_OK):
+        denied = PermissionError(errno.EACCES, os.strerror(errno.EACCES))
+        raise Refusal('key_unreadable', f'{path} exists but this account cannot read it '
+                      f'({unreadable_detail(path, denied)}); ' + remedy)
+    st = os.stat(path)
+    # st_ctime_ns too (review round 6): a chmod/chown that FIXES a refused key changes no byte and no mtime, and the
+    # timer skipped the fixed file for the rest of the hour.
+    return f'{st.st_dev}:{st.st_ino}:{st.st_size}:{st.st_mtime_ns}:{st.st_ctime_ns}'
+
+
+def read_config_text(layout):
+    """studio-host.toml's text, or the typed `config_unreadable` refusal (review round 5: an unreadable config
+    ended enable, the timer and `status` in a PermissionError traceback before the typed arm could be reached)."""
+    try:
+        return layout.config.read_text()
+    except OSError as error:
+        raise Refusal('config_unreadable', f'{layout.config} exists but this account cannot read it '
+                      f'({unreadable_detail(layout.config, error)}); it must be owned by this account (0600)')
+
+
+def is_readable(path):
+    """True when `path` opens for reading (a stat is not a readability check)."""
+    try:
+        with open(path, 'rb'):
+            return True
+    except OSError:
+        return False
+
+
+def b64url(data):
+    return base64.urlsafe_b64encode(data).rstrip(b'=').decode()
+
+
+def jwk_thumbprint(jwk):
+    """RFC 7638 thumbprint (base64url SHA-256) of the Ed25519 public JWK `throttle-rc studio publish-key` writes;
+    None for anything else. The same computation as the binary's `machine_jkt` (pinned against the real binary)."""
+    if not (isinstance(jwk, dict) and jwk.get('kty') == 'OKP' and jwk.get('crv') == 'Ed25519'
+            and isinstance(jwk.get('x'), str) and jwk['x']):
+        return None
+    canonical = json.dumps({'crv': 'Ed25519', 'kty': 'OKP', 'x': jwk['x']}, separators=(',', ':'), sort_keys=True)
+    return b64url(hashlib.sha256(canonical.encode()).digest())
+
+
+def load_credential(layout):
+    """credential.json as a dict ({} when present but unparsable), or None when absent. It is inert: no secret."""
+    if not layout.credential.exists():
+        return None
+    document = read_json(layout.credential)
+    return document if isinstance(document, dict) else {}
+
+
+def key_binding(layout, credential):
+    """Whether `credential` binds the machine key this installer last PUBLISHED: True/False, or None when that is
+    not measurable here (no recorded thumbprint — a version-1 receipt —, no key, no published key, or a published
+    key OLDER than the key file, i.e. not this key's). The machine key itself is never read (C5): the published
+    public key is the evidence. Review round 6: `enrolled` used to mean "a credential and SOME key", so after the
+    timer minted a new key beside a dead receipt, `status` called it `enrolled`/`stopped`."""
+    issued = (credential or {}).get('machine_jkt')
+    if not issued or not layout.machine_key.exists() or not layout.public_jwk.is_file():
+        return None
+    try:
+        if layout.public_jwk.stat().st_mtime_ns < layout.machine_key.stat().st_mtime_ns:
+            return None
+    except OSError:
+        return None
+    published = jwk_thumbprint(read_json(layout.public_jwk))
+    return None if published is None else published == issued
+
+
+def measured_revoked(layout, server):
+    """Whether THIS machine MEASURED its Host row at `server` as revoked: a `refused` state.json for that server
+    whose detail carries a provenance mark and the word REVOKED (throttle-rc's own `measured_revocation`)."""
+    state = read_json(layout.host_state)
+    if not (isinstance(state, dict) and state.get('phase') == 'refused' and server):
+        return False
+    if str(state.get('server') or '').rstrip('/') != str(server).rstrip('/'):
+        return False
+    detail = str(state.get('detail') or '')
+    return (PLATFORM_REFUSAL_MARK in detail or SELF_REVOKE_MARK in detail) and 'REVOKED' in detail
+
+
+def atomic_write(path, data, mode):
+    """Write next to `path` and rename over it; never through an existing symlink."""
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, temporary = tempfile.mkstemp(prefix='.' + path.name + '.', dir=path.parent)
+    try:
+        with os.fdopen(fd, 'wb') as handle:
+            handle.write(data if isinstance(data, bytes) else data.encode())
+        os.chmod(temporary, mode)
+        os.replace(temporary, path)
+    finally:
+        if os.path.exists(temporary):
+            os.unlink(temporary)
+
+
+def read_json(path):
+    try:
+        return json.loads(Path(path).read_text())
+    except (OSError, ValueError):
+        return None
+
+
+def now_utc():
+    return time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime())
+
+
+# -------------------------------------------------------------------------------------------- the pin
+
+class Pin:
+    def __init__(self, name, version, sha256, url, opt_in=False, member=None, binary_sha256=None):
+        self.name, self.version, self.sha256, self.url = name, version, sha256, url
+        self.opt_in, self.member, self.binary_sha256 = opt_in, member, binary_sha256
+
+
+def parse_lock(text):
+    """holders.lock -> {name: Pin}. `name version sha256 url` for an always-installed holder;
+    `... opt-in member member-sha256` for a pin only its opt-in step installs. Malformed lines are refused by
+    line number: a lock is an authority, never best-effort."""
+    pins = {}
+    for number, line in enumerate(text.splitlines(), 1):
+        if not line.strip() or line.lstrip().startswith('#'):
+            continue
+        words = line.split()
+        if len(words) == 4:
+            name, version, sha, url = words
+            pin = Pin(name, version, sha, url)
+        elif len(words) == 7 and words[4] == LOCK_OPT_IN:
+            name, version, sha, url, _flag, member, binary_sha = words
+            if not HEX64.match(binary_sha):
+                raise Refusal('lock_invalid', f'holders.lock line {number}: the member digest is not 64 lowercase hex')
+            parts = member.split('/')
+            if member.startswith('/') or any(part in ('', '.', '..') for part in parts):
+                raise Refusal('lock_invalid', f'holders.lock line {number}: member {member!r} is not a plain relative path')
+            pin = Pin(name, version, sha, url, True, member, binary_sha)
+        else:
+            raise Refusal('lock_invalid', f'holders.lock line {number}: expected 4 fields, or 7 with "{LOCK_OPT_IN}"')
+        if not HEX64.match(sha):
+            raise Refusal('lock_invalid', f'holders.lock line {number}: the tarball digest is not 64 lowercase hex')
+        if not VERSION_WORD.match(version):
+            raise Refusal('lock_invalid', f'holders.lock line {number}: version {version!r} is not a plain word')
+        if name in pins:
+            raise Refusal('lock_invalid', f'holders.lock line {number}: {name} is pinned twice')
+        pins[name] = pin
+    return pins
+
+
+def lock_path():
+    return Path(__file__).resolve().parent.parent / 'holders.lock'
+
+
+def _select(layout, filename, record):
+    """Point bin/throttle-rc at `filename` (in the same directory) and record what it is. Record first: a crash
+    between the two leaves a record that `verify_installed` refuses, never a link with no record."""
+    atomic_write(layout.pin_record, json.dumps(record, indent=1, sort_keys=True) + '\n', 0o644)
+    link = layout.binary
+    temporary = link.with_name(f'.{BINARY}.link-{os.getpid()}')
+    if temporary.is_symlink() or temporary.exists():
+        temporary.unlink()
+    temporary.symlink_to(filename)
+    os.replace(temporary, link)
+
+
+def _place(layout, source_bytes_path, filename, expected_sha):
+    """Copy to bin/<filename> (0755, atomic) and re-hash the COPY: the digest that counts is the one the unit runs."""
+    target = layout.share / 'bin' / filename
+    target.parent.mkdir(parents=True, exist_ok=True)
+    fd, temporary = tempfile.mkstemp(prefix=f'.{filename}.', dir=target.parent)
+    try:
+        with os.fdopen(fd, 'wb') as out, open(source_bytes_path, 'rb') as src:
+            shutil.copyfileobj(src, out)
+        os.chmod(temporary, 0o755)
+        actual = sha256_file(temporary)
+        if actual != expected_sha:
+            raise Refusal('binary_mismatch', f'the copy at {target} hashed {actual}, not {expected_sha}; nothing selected')
+        os.replace(temporary, target)
+    finally:
+        if os.path.exists(temporary):
+            os.unlink(temporary)
+    return target
+
+
+def install_local(layout, source, expected_sha=None):
+    """`install --from PATH [--sha256 HEX]`: a locally built binary, for a lanes server before a node/<sha12>
+    release carries the co-location CLI."""
+    source = Path(source)
+    if source.is_symlink() or not source.is_file():
+        raise Refusal('usage', f'{source} is not a regular file (a symbolic link is refused: name the file itself)', 2)
+    if not os.access(source, os.X_OK):
+        raise Refusal('usage', f'{source} is not executable', 2)
+    if expected_sha is not None and not HEX64.match(expected_sha):
+        raise Refusal('usage', '--sha256 must be 64 lowercase hex', 2)
+    actual = sha256_file(source)
+    if expected_sha is not None and actual != expected_sha:
+        raise Refusal('binary_mismatch', f'{source} hashed {actual}, not the --sha256 given; nothing installed')
+    version = f'local-{actual[:12]}'
+    _place(layout, source, f'{BINARY}-{version}', actual)
+    record = {'source': 'local', 'version': version, 'sha256': actual, 'from': str(source.resolve()),
+              'installed_at': now_utc()}
+    _select(layout, f'{BINARY}-{version}', record)
+    return record
+
+
+def fetch(url, dest, timeout=300):
+    """Download one release asset. A private repository's asset needs `gh` (its own login); anything else is curl."""
+    found = re.match(r'^https://github\.com/([^/]+/[^/]+)/releases/download/(.+)/([^/]+)$', url)
+    if found and shutil.which('gh'):
+        repo, tag, asset = found.groups()
+        argv = ['gh', 'release', 'download', tag, '--repo', repo, '--pattern', asset, '--dir', str(Path(dest).parent),
+                '--clobber']
+        produced = Path(dest).parent / asset
+    else:
+        argv = ['curl', '-fsSL', '--retry', '3', '-o', str(dest), url]
+        produced = Path(dest)
+    try:
+        result = subprocess.run(argv, capture_output=True, text=True, timeout=timeout,
+                                env=child_env({k: os.environ[k] for k in ('GH_TOKEN', 'GITHUB_TOKEN') if os.environ.get(k)}))
+    except (OSError, subprocess.TimeoutExpired) as error:
+        raise Refusal('download_failed', f'{argv[0]}: {error}', 1)
+    if result.returncode != 0:
+        raise Refusal('download_failed', f'{argv[0]} exit {result.returncode}: {result.stderr.strip()[:300]}', 1)
+    if produced != Path(dest):
+        os.replace(produced, dest)
+
+
+def install_pinned(layout, pin, fetcher=fetch):
+    """`install` with no --from: the holders.lock opt-in pin. The tarball digest AND the member digest must match;
+    only the named member is read (no extractall, no links)."""
+    downloads = layout.share / 'dl'
+    downloads.mkdir(parents=True, exist_ok=True)
+    archive = downloads / f'{pin.name}-{pin.version}.tar.gz'
+    fetcher(pin.url, archive)
+    actual = sha256_file(archive)
+    if actual != pin.sha256:
+        raise Refusal('binary_mismatch', f'{archive.name} hashed {actual}, not the pinned {pin.sha256}; nothing installed')
+    with tempfile.TemporaryDirectory(dir=downloads) as scratch:
+        extracted = Path(scratch) / BINARY
+        try:
+            with tarfile.open(archive, 'r:gz') as tar:
+                try:
+                    member = tar.getmember(pin.member)
+                except KeyError:
+                    raise Refusal('binary_mismatch', f'{archive.name} holds no {pin.member}')
+                if not member.isfile():
+                    raise Refusal('binary_mismatch', f'{pin.member} in {archive.name} is not a regular file')
+                with tar.extractfile(member) as src, open(extracted, 'wb') as out:
+                    shutil.copyfileobj(src, out)
+        except (tarfile.TarError, OSError) as error:
+            raise Refusal('binary_mismatch', f'{archive.name} is not a readable tar.gz: {error}')
+        member_sha = sha256_file(extracted)
+        if member_sha != pin.binary_sha256:
+            raise Refusal('binary_mismatch', f'{pin.member} hashed {member_sha}, not the pinned {pin.binary_sha256}')
+        _place(layout, extracted, f'{BINARY}-{pin.version}', member_sha)
+    record = {'source': 'lock', 'version': pin.version, 'sha256': member_sha, 'from': pin.url,
+              'installed_at': now_utc()}
+    _select(layout, f'{BINARY}-{pin.version}', record)
+    return record
+
+
+def verify_installed(layout):
+    """-> (word, detail, record). word: verified | absent | mismatch. Hashes the file the link names NOW."""
+    record = read_json(layout.pin_record)
+    if not layout.binary.is_symlink() and not layout.binary.exists():
+        return 'absent', f'no {layout.binary}', record
+    if not isinstance(record, dict) or not HEX64.match(str(record.get('sha256', ''))):
+        return 'mismatch', f'{layout.pin_record} is missing or unreadable: nothing says what {layout.binary} should be', record
+    try:
+        target = layout.binary.resolve(strict=True)
+        actual = sha256_file(target)
+    except OSError as error:
+        return 'absent', f'{layout.binary}: {error}', record
+    if actual != record['sha256']:
+        return 'mismatch', f'{target} hashed {actual}, the install recorded {record["sha256"]}', record
+    return 'verified', f"{target.name} ({record.get('source')}, sha256 {actual[:16]}…)", record
+
+
+# ------------------------------------------------------------------------------------------- config
+
+def validate_server(server):
+    """The Host's own rule (studio_host::config::validate_server): scheme + host[:port], nothing after."""
+    if not server or not re.match(r'^https?://[^/\s?#]+$', server) or any(ord(c) < 32 for c in server):
+        raise Refusal('usage', f'--server {server!r} must be http(s)://host[:port] with nothing after it', 2)
+    return server
+
+
+def default_machine_id():
+    base = re.sub(r'[^A-Za-z0-9._-]', '-', os.uname().nodename.split('.')[0])[:57] or 'lanes'
+    return f'{base}-lanes'
+
+
+def toml_string(value):
+    value = str(value)
+    if any(ord(c) < 32 or ord(c) == 127 for c in value):
+        raise Refusal('usage', 'configuration values must not contain control characters', 2)
+    return '"' + value.replace('\\', '\\\\').replace('"', '\\"') + '"'
+
+
+def render_config(server, machine_id, state_dir, container_uid=1000):
+    validate_server(server)
+    if not MACHINE_ID.match(machine_id):
+        raise Refusal('usage', f'--machine-id {machine_id!r} is outside 1-64 chars of [A-Za-z0-9._-]', 2)
+    return (f'{CONFIG_HEADER} (lanes-server mode, docs/design/throttle-studio.md §8.10 C2).\n'
+            '# The installer never rewrites this file; edit it freely, then `systemctl --user restart '
+            f'{UNIT}`.\n'
+            f'server = {toml_string(server)}\n'
+            f'machine_id = {toml_string(machine_id)}\n'
+            '\n[inventory]\n'
+            'mode = "lanes-server"\n'
+            'interactive = true\n'
+            f'sharing_state_dir = {toml_string(state_dir)}\n'
+            f'sharing_container_uid = {int(container_uid)}\n'
+            'legacy_coder_launch = false\n')
+
+
+_ASSIGN = re.compile(r'^\s*([A-Za-z0-9_-]+)\s*=\s*(.*?)\s*$')
+
+
+def _scalar(raw):
+    raw = raw.split(' #', 1)[0].strip()
+    if raw.startswith('"') and raw.endswith('"') and len(raw) >= 2:
+        return raw[1:-1].replace('\\"', '"').replace('\\\\', '\\')
+    if raw in ('true', 'false'):
+        return raw == 'true'
+    return raw
+
+
+def config_facts(text):
+    """The keys this installer reasons about — top-level server/machine_id, [inventory] mode/interactive/
+    sharing_state_dir — read line by line (Python 3.9 has no tomllib). Not a validator: `studio host --check` is."""
+    facts, table = {'inventory': {}}, ''
+    for line in text.splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith('#'):
+            continue
+        if stripped.startswith('['):
+            table = stripped.strip('[]').strip()
+            continue
+        found = _ASSIGN.match(line)
+        if not found:
+            continue
+        key, value = found.group(1), _scalar(found.group(2))
+        if table == '' and key in ('server', 'machine_id'):
+            facts[key] = value
+        elif table == 'inventory' and key in ('mode', 'interactive', 'sharing_state_dir', 'sharing_container_uid'):
+            facts['inventory'][key] = value
+    facts['mode'] = facts['inventory'].get('mode', 'in-container')
+    return facts
+
+
+def set_lanes_server_mode(text, state_dir):
+    """Return `text` with [inventory] mode = "lanes-server" and a sharing_state_dir (the mode requires one).
+    Every other line is kept byte for byte."""
+    lines = text.splitlines()
+    start = next((i for i, line in enumerate(lines) if line.strip() == '[inventory]'), None)
+    if start is None:
+        tail = ['', '[inventory]', 'mode = "lanes-server"', f'sharing_state_dir = {toml_string(state_dir)}']
+        return '\n'.join(lines + tail) + '\n'
+    end = next((i for i in range(start + 1, len(lines)) if lines[i].strip().startswith('[')), len(lines))
+    section = lines[start + 1:end]
+    keys = {(_ASSIGN.match(line) or [None, None])[1]: i for i, line in enumerate(section)
+            if not line.strip().startswith('#')}
+    if 'mode' in keys:
+        section[keys['mode']] = 'mode = "lanes-server"'
+    else:
+        section.insert(0, 'mode = "lanes-server"')
+    if 'sharing_state_dir' not in keys:
+        section.insert(1, f'sharing_state_dir = {toml_string(state_dir)}')
+    return '\n'.join(lines[:start + 1] + section + lines[end:]) + '\n'
+
+
+# ----------------------------------------------------------------------------------- external calls
+
+RUNTIME_DIR_ROOT = Path('/run/user')
+
+
+def child_env(extra=None):
+    """The allowlisted environment. Review round 2: like bin/lanes' clean_env() and the install scripts, a caller
+    without XDG_RUNTIME_DIR (a `sudo -u <account> -i` or cron shell) gets /run/user/<uid> when it exists, or every
+    `systemctl --user` answer is `no-answer` and `status` says `unknown` for a running Host."""
+    env = {key: os.environ[key] for key in ENV_ALLOWLIST if os.environ.get(key)}
+    runtime = RUNTIME_DIR_ROOT / str(os.getuid())
+    if 'XDG_RUNTIME_DIR' not in env and runtime.is_dir():
+        env['XDG_RUNTIME_DIR'] = str(runtime)
+    env.update(extra or {})
+    return env
+
+
+def run(argv, timeout, extra_env=None):
+    """-> (rc, stdout, stderr); rc None when it did not finish in `timeout` seconds, 127 when it could not spawn."""
+    try:
+        result = subprocess.run(argv, capture_output=True, text=True, errors='replace', timeout=timeout,
+                                env=child_env(extra_env), stdin=subprocess.DEVNULL)
+        return result.returncode, result.stdout, result.stderr
+    except subprocess.TimeoutExpired as error:
+        return None, error.stdout or '', error.stderr or ''
+    except OSError as error:
+        return 127, '', str(error)
+
+
+def systemctl(*args, timeout=SYSTEMCTL_TIMEOUT):
+    return run(['systemctl', '--user', *args], timeout)
+
+
+def unit_word(verb, unit):
+    """`is-active`/`is-enabled` -> its first word, or 'no-answer' (timeout / no manager). Never invented."""
+    rc, out, err = systemctl(verb, unit, timeout=10)
+    word = (out.strip().splitlines() or [''])[0].strip()
+    if rc is None or rc == 127:
+        return 'no-answer'
+    if not word and 'No such file' in (err or ''):
+        return 'not-found'   # older managers answer a missing unit on stderr only
+    return word or 'no-answer'
+
+
+def manager_units_dir(layout):
+    """Where the user MANAGER reads unit files (systemd.unit(5)): $XDG_CONFIG_HOME/systemd/user when the manager's
+    own environment sets it, else ~/.config/systemd/user. Asked of the manager (`show-environment`), never of this
+    shell (review round 2: a manager with XDG_CONFIG_HOME set never loads ~/.config/systemd/user, so the enable
+    failed `Unit not found` while status said the file was present). No answer keeps the default."""
+    rc, out, _err = systemctl('show-environment', timeout=10)
+    if rc == 0:
+        for line in (out or '').splitlines():
+            if line.startswith('XDG_CONFIG_HOME='):
+                value = line.split('=', 1)[1]
+                if value.startswith('/'):
+                    return Path(value) / 'systemd/user'
+    return layout.units
+
+
+def layout_roots(layout):
+    """The two XDG roots every throttle-rc child — and both studio units (install/services.py) — resolve with:
+    this layout's, ALWAYS set. Review round 3: inherited from whoever ran the step, a user manager whose environment
+    carries XDG_DATA_HOME the installer's shell does not made the supervised Host look for credential.json where the
+    installer never wrote it, while the installer's own `--check` passed."""
+    return {'XDG_CONFIG_HOME': str(layout.config_home), 'XDG_DATA_HOME': str(layout.data_home)}
+
+
+def throttle_rc(layout, *args, timeout=60):
+    return run([str(layout.binary), *args], timeout, extra_env=layout_roots(layout))
+
+
+def hand_built_text(layout):
+    """The hand-built unit's text as the manager has it (`systemctl --user cat`), or None when there is none."""
+    rc, out, _err = systemctl('cat', HAND_BUILT_UNIT, timeout=10)
+    if rc == 0 and out.strip():
+        return out
+    path = manager_units_dir(layout) / HAND_BUILT_UNIT
+    return path.read_text() if path.is_file() else None
+
+
+def expand_unit_path(value, home):
+    """A unit's path argument as the user manager resolves it: `%h` (and `%%`), `${HOME}`/`$HOME` and `~` are the
+    account's home (review round 2: an idiomatic `--config %h/...` unit was refused as naming another file)."""
+    home = str(home)
+    value = value.replace('%%', '\0').replace('%h', home).replace('\0', '%')
+    value = re.sub(r'\$\{HOME\}|\$HOME(?![A-Za-z0-9_])', lambda _m: home, value)
+    if value == '~' or value.startswith('~/'):
+        value = home + value[1:]
+    return Path(value)
+
+
+def hand_built_config(text):
+    """-> (runs_studio_host, config path or None) from the unit's ExecStart lines."""
+    for line in text.splitlines():
+        if not line.strip().startswith('ExecStart='):
+            continue
+        command = line.split('=', 1)[1]
+        if ' studio host' not in command:
+            continue
+        found = re.search(r'--config[ =]"?([^"\s]+)"?', command)
+        return True, (found.group(1) if found else None)
+    return False, None
+
+
+# ------------------------------------------------------------------------------------------- enable
+
+USAGE = """usage: sh install/enable-studio-host.sh [options]
+  --server URL                  the platform the Host dials (required only when no config exists yet)
+  --machine-id ID               the config's machine_id (default: <hostname>-lanes)
+  --container-uid N             the workspace containers' tmux uid (default 1000)
+  --receipt PATH                a deploy receipt to adopt (default: $LANES_STATE/studio-host/receipt.json);
+                                remembered, so the enrol timer and `status` watch it (the default path forgets it)
+  --registration-key-file PATH  enrol with the owner's registration key (default: ~/.config/throttle-rc/registration.key);
+                                remembered like --receipt
+  --set-mode                    an existing config is not in lanes-server mode: rewrite that one key (keeps a .bak)
+  --migrate-hand-built          replace the hand-built lanes-sharing-host.service (its text is saved first)
+  --from PATH [--sha256 HEX]    install this locally built throttle-rc first (else the holders.lock pin)
+  --settle SECONDS              how long a started Host must stay running (default 5)
+  --dry-run                     print the plan; write, enable and start nothing
+  --retry                       what lanes-studio-host-enrol.timer runs: act only on something new
+Exit: 0 running or waiting for enrolment; 2 usage; 3 a typed refusal; 1 an operational failure. A refused or
+failed receipt/key still leaves the units enabled and waiting (the exit says what was refused)."""
+
+
+def parse_enable_args(argv):
+    options = {'server': None, 'machine_id': None, 'container_uid': 1000, 'receipt': None, 'key_file': None,
+               'set_mode': False, 'migrate': False, 'from': None, 'sha256': None, 'settle': 5.0,
+               'dry_run': False, 'retry': False}
+    flags = {'--set-mode': 'set_mode', '--migrate-hand-built': 'migrate', '--dry-run': 'dry_run', '--retry': 'retry'}
+    values = {'--server': 'server', '--machine-id': 'machine_id', '--container-uid': 'container_uid',
+              '--receipt': 'receipt', '--registration-key-file': 'key_file', '--from': 'from', '--sha256': 'sha256',
+              '--settle': 'settle'}
+    items = list(argv)
+    while items:
+        item = items.pop(0)
+        if item in ('-h', '--help'):
+            print(USAGE)
+            raise SystemExit(0)
+        if item in flags:
+            options[flags[item]] = True
+        elif item in values:
+            if not items:
+                raise Refusal('usage', f'{item} needs a value\n{USAGE}', 2)
+            options[values[item]] = items.pop(0)
+        else:
+            raise Refusal('usage', f'unknown option {item!r}\n{USAGE}', 2)
+    try:
+        options['container_uid'] = int(options['container_uid'])
+        options['settle'] = float(options['settle'])
+    except ValueError:
+        raise Refusal('usage', '--container-uid and --settle take numbers', 2)
+    if options['sha256'] and not options['from']:
+        raise Refusal('usage', '--sha256 goes with --from', 2)
+    return options
+
+
+class Plan:
+    """Prints each step; in a dry run, says what it WOULD do and does nothing."""
+
+    def __init__(self, dry_run, quiet=False):
+        self.dry_run, self.quiet = dry_run, quiet
+
+    def say(self, text):
+        if not self.quiet:
+            print(text)
+
+    def step(self, text, action=None):
+        if self.dry_run:
+            print(f'would: {text}')
+            return None
+        self.say(f'{text}')
+        return action() if action else None
+
+
+def _record(layout):
+    return read_json(layout.record) or {}
+
+
+def receipt_path(layout, record):
+    """The receipt this machine watches: the remembered --receipt, else the default."""
+    return Path(record['receipt_path']) if record.get('receipt_path') else layout.receipt
+
+
+def key_path(layout, record):
+    """The registration key file this machine watches: the remembered --registration-key-file, else the default."""
+    return Path(record['registration_key_path']) if record.get('registration_key_path') else layout.registration_key
+
+
+def _remember_paths(layout, options, record):
+    """A manual run's --receipt/--registration-key-file is remembered (an explicit default forgets it)."""
+    defaults = {'receipt': layout.receipt, 'key_file': layout.registration_key}
+    changed = False
+    for option, key in REMEMBERED_PATHS.items():
+        if not options[option]:
+            continue
+        chosen = Path(options[option]).absolute()
+        value = None if chosen == defaults[option] else str(chosen)
+        if record.get(key) != value:
+            if value is None:
+                record.pop(key, None)
+            else:
+                record[key] = value
+            changed = True
+    if changed:
+        _save_record(layout, record)
+
+
+def _save_record(layout, record):
+    record.pop(LEGACY_KEY_DIGEST, None)
+    layout.studio_state.mkdir(parents=True, exist_ok=True)
+    os.chmod(layout.studio_state, 0o700)
+    atomic_write(layout.record, json.dumps(record, indent=1, sort_keys=True) + '\n', 0o600)
+
+
+def _check_systemctl(rc, out, err, what):
+    if rc != 0:
+        raise Refusal('systemd_failed', f'systemctl --user {what}: exit {rc}: {(err or out).strip()[:300]}', 1)
+
+
+def _bounded_detail(text, limit=600):
+    """A child's output for a refusal line: its HEAD and its tail when it is long (review round 6: a tail-only cut
+    dropped the head of the binary's one refusal line, `--registration-key-file …` reading `n-key-file …`)."""
+    text = (text or '').strip()
+    if len(text) <= limit:
+        return text or '(no output)'
+    half = limit // 2
+    return f'{text[:half]} … {text[-half:]}'
+
+
+def _throttle_rc_failed(verb, rc, out, err, kind=None, typed_exits=(3,)):
+    """The installer's refusal for a failed throttle-rc verb. Exit 3 (typed) when the child's exit is one of
+    `typed_exits` — `studio enroll` types a refused key SOURCE as its usage exit 2 (`registration_key_source_refused`,
+    review round 6), which is a refusal, not "an operational failure" — else 1."""
+    kind = kind or Refusal
+    detail = _bounded_detail(err or out)
+    if rc is None:
+        return kind('throttle_rc_failed', f'throttle-rc studio {verb} did not finish in time', 1)
+    return kind('throttle_rc_failed', f'throttle-rc studio {verb} exit {rc}: {detail}', 3 if rc in typed_exits else 1)
+
+
+def _publish(layout):
+    """`throttle-rc studio publish-key` into $LANES_STATE/studio-host (0700). Idempotent for an existing machine key
+    (it is loaded, never rewritten); a key is created here only when there is none."""
+    layout.studio_state.mkdir(parents=True, exist_ok=True)
+    os.chmod(layout.studio_state, 0o700)
+    rc, out, err = throttle_rc(layout, 'studio', 'publish-key', '--out', str(layout.public_jwk), timeout=30)
+    if rc != 0:
+        raise _throttle_rc_failed('publish-key', rc, out, err)
+
+
+def _ensure_binary(layout, options, plan):
+    """The binary the unit runs is installed AND its file still hashes to what was recorded."""
+    planned = False
+    if options['from']:
+        plan.step(f"install {options['from']} as the Host binary (sha256-verified)",
+                  lambda: install_local(layout, options['from'], options['sha256']))
+        planned = True
+    word, detail, _pin = verify_installed(layout)
+    if word == 'absent' and not options['from'] and not options['retry']:
+        pins = parse_lock(lock_path().read_text())
+        if BINARY not in pins:
+            raise Refusal('no_binary', f'{detail}, and holders.lock pins no {BINARY} release yet. Build it '
+                          '(cargo build --release --locked -p throttle-rc) and pass --from PATH, or run '
+                          '`lanes studio-host install --from PATH` first.')
+        plan.step(f'install the holders.lock pin {BINARY} {pins[BINARY].version} (both digests checked)',
+                  lambda: install_pinned(layout, pins[BINARY]))
+        planned = True
+        word, detail, _pin = verify_installed(layout)
+    if word != 'verified' and not (options['dry_run'] and planned):
+        raise Refusal('binary_mismatch' if word == 'mismatch' else 'no_binary', detail)
+    plan.say(f'binary: {detail}' if word == 'verified' else 'binary: (installed by this run)')
+
+
+def _one_host_per_machine(layout, options, record):
+    """One Host per machine. Returns the hand-built unit's text when this run migrates it, else None."""
+    for verb in ('is-active', 'is-enabled'):
+        state = unit_word(verb, SUPERVISOR_UNIT)
+        if state in ('active', 'activating', 'reloading', 'enabled', 'enabled-runtime', 'linked'):
+            raise Refusal('another_host_unit', f'{SUPERVISOR_UNIT} is {state}: one Studio Host per machine. Remove it '
+                          'first (`throttle-rc studio service uninstall --yes`), then re-run this.')
+    hand_built = hand_built_text(layout)
+    if hand_built is None:
+        return None
+    states = (unit_word('is-active', HAND_BUILT_UNIT), unit_word('is-enabled', HAND_BUILT_UNIT))
+    stopped = states[0] in ('inactive', 'failed') and states[1] != 'enabled'
+    if record.get('hand_built_migrated_at') and stopped:
+        return None   # migrated by an earlier run; its file is left for the operator to delete
+    if options['retry'] and stopped:
+        # Review round 1: the timer never refuses on a stopped, disabled hand-built unit (its migration record may
+        # have been lost with $LANES_STATE/studio-host); a manual run still asks for --migrate-hand-built.
+        return None
+    if not options['migrate']:
+        raise Refusal('hand_built_unit_present', f'{HAND_BUILT_UNIT} exists ({states[0]}, {states[1]}). Read it '
+                      f'(`systemctl --user cat {HAND_BUILT_UNIT}`), then re-run with --migrate-hand-built: its text '
+                      f'is saved under {layout.migrated}, it is disabled and stopped, and the machine key and '
+                      'enrolment are kept.')
+    runs_host, config_path = hand_built_config(hand_built)
+    if not runs_host:
+        raise Refusal('hand_built_unit_unrecognised', f'{HAND_BUILT_UNIT} does not run `studio host`; it is not '
+                      'the shape this migration knows. Nothing was changed.')
+    if config_path and expand_unit_path(config_path, layout.home) != layout.config:
+        raise Refusal('hand_built_unit_unrecognised', f'{HAND_BUILT_UNIT} runs the Host with --config {config_path};'
+                      f' the lanes unit reads {layout.config}. Move that file there first. Nothing was changed.')
+    return hand_built
+
+
+def _ensure_config(layout, options, plan):
+    """Step 3: a config in lanes-server mode. Never rewrites an existing file beyond the one `mode` key. Returns the
+    .bak it kept when it patched an existing file (the migration restores it if the replacement does not check)."""
+    if not layout.config.exists():
+        if not options['server']:
+            raise Refusal('server_required', f'there is no {layout.config} yet: name the platform with --server URL')
+        text = render_config(options['server'], options['machine_id'] or default_machine_id(), str(layout.state),
+                             options['container_uid'])
+        plan.step(f'write {layout.config} in lanes-server mode (0600)', lambda: atomic_write(layout.config, text, 0o600))
+        return None
+    facts = config_facts(read_config_text(layout))
+    if facts['mode'] == 'lanes-server':
+        plan.say(f'config: {layout.config} (lanes-server)')
+        return None
+    if not (options['set_mode'] or options['migrate']):
+        raise Refusal('config_mode', f'{layout.config} is in {facts["mode"]} mode. Re-run with --set-mode to rewrite '
+                      'that one key to lanes-server (a .bak is kept), or edit it yourself.')
+
+    kept = []
+
+    def patch():
+        text = read_config_text(layout)
+        backup = layout.config.with_name(f'{layout.config.name}.bak-{time.strftime("%Y%m%dT%H%M%SZ", time.gmtime())}')
+        shutil.copy2(layout.config, backup)
+        atomic_write(layout.config, set_lanes_server_mode(text, str(layout.state)), 0o600)
+        kept.append(backup)
+        print(f'kept the previous file as {backup}')
+    plan.step(f'set [inventory] mode = "lanes-server" in {layout.config} (keeping a .bak)', patch)
+    return kept[0] if kept else None
+
+
+def _migrate_hand_built(layout, plan, hand_built, record, replaced):
+    """Step 4: save the text, then disable --now. The key is never touched.
+
+    Review round 2: the hand-built Host is stopped only after the replacement's own `studio host --check` passes on
+    the migrated config. An enrolled machine whose check refuses (a version-1 credential's unchecked key binding, a
+    refused state) keeps its hand-built Host running and enabled, the config is restored from the .bak this run
+    kept, and the refusal names both. (`--check` is read-only and safe beside a live Host.) An unenrolled machine
+    has no serving Host to protect: its check would only say "not enrolled", so it is not run here. The config is
+    given back by `enable` (review round 5: on ANY failure before `replaced` is set, not only this one)."""
+    def migrate():
+        if layout.credential.exists():
+            rc, out, err = throttle_rc(layout, 'studio', 'host', '--check', '--config', str(layout.config),
+                                       timeout=60)
+            if rc != 0:
+                raise Refusal('host_check_failed', f'`throttle-rc studio host --check` exit {rc} on the migrated '
+                              f'config, so {HAND_BUILT_UNIT} was LEFT running and enabled and nothing was replaced. '
+                              'Fix what the check names, then re-run with --migrate-hand-built:\n'
+                              + (out + err).strip()[-1500:], 3 if rc == 3 else 1)
+        layout.migrated.mkdir(parents=True, exist_ok=True)
+        saved = layout.migrated / f'{HAND_BUILT_UNIT}.{time.strftime("%Y%m%dT%H%M%SZ", time.gmtime())}'
+        atomic_write(saved, hand_built, 0o600)
+        _check_systemctl(*systemctl('disable', '--now', HAND_BUILT_UNIT), f'disable --now {HAND_BUILT_UNIT}')
+        replaced.append(saved)
+        record['hand_built_migrated_at'] = now_utc()
+        record['hand_built_saved'] = str(saved)
+        _save_record(layout, record)
+        print(f'saved {saved}; {HAND_BUILT_UNIT} disabled and stopped (its unit file is left for you to delete)')
+    plan.step(f'check the migrated config (`studio host --check`), save {HAND_BUILT_UNIT} under {layout.migrated}, '
+              'then disable --now it', migrate)
+
+
+RECEIPT_UNREADABLE_REMEDY = ('a deploy run as another account writes it 0600 as that account (DEF-1429): give it to '
+                             'this account (chown, or chmod 0644 — the receipt is inert), or have the deploy write '
+                             'it where this account can read it and pass --receipt PATH')
+KEY_UNREADABLE_REMEDY = 'give it to this account (owned by it, mode 0600); it is read by throttle-rc, never by this script'
+REFUSAL_CODE = re.compile(r'refused ([a-z0-9_]+)')
+# `studio enroll`'s line names its code at the END, `<sentence> (<code>)` (enroll.rs EnrollRefusal::text_line).
+TRAILING_CODE = re.compile(r'\(([a-z][a-z0-9_]*_[a-z0-9_]+)\)\s*$', re.MULTILINE)
+
+
+def _refusal_code(text):
+    found = REFUSAL_CODE.search(text or '') or TRAILING_CODE.search(text or '')
+    return found.group(1) if found else 'unknown'
+
+
+def _configured_server(layout, options):
+    facts = config_facts(read_config_text(layout)) if layout.config.exists() else {}
+    return facts.get('server') or options['server'], facts
+
+
+def _enrol(layout, options, plan, record, receipt, key_file):
+    """Step 5. Returns whether this machine is (or, in a dry run, would be) enrolled.
+
+    Review round 1: an existing credential short-circuits ONLY while it binds the machine key beside it and no NEW
+    deploy receipt has arrived. Review round 6: a credential whose key is gone (or is not the key on disk) is DEAD
+    only when this machine has MEASURED its host row revoked (state.json, the binary's own rule) — then a new key is
+    published and the next enrolment says `--new-key`. Without that measurement it is a live, un-revoked host row
+    whose key went missing (a lost or restored key file, a partial hand remedy): enrolling a second machine beside
+    it is the operator's decision, so this refuses `credential_for_gone_key` and names the two steps (revoke, then
+    `lanes studio-host re-key --yes`). It used to publish a new key and say `--new-key` by itself."""
+    receipt_sha = readable_sha(receipt, 'receipt_unreadable', RECEIPT_UNREADABLE_REMEDY)
+    config_sha = readable_sha(layout.config, 'config_unreadable', 'it must be owned by this account (0600)')
+    credential = load_credential(layout)
+    enrolled = (credential is not None and layout.machine_key.exists()
+                and key_binding(layout, credential) is not False)
+    # Review round 2: the refusal memory is the TIMER's, as the key's is (design §8.10 C3 (c)). It holds only for a
+    # TYPED refusal (exit 3) of THIS receipt under THIS config, for an hour. A manual run always tries a refused
+    # receipt (the operator just fixed the Host side; the deploy re-emits byte-identical bytes), and a transient
+    # failure (exit 1/2, a timeout, a failed spawn) is never remembered at all. Review round 4: the same holds for an
+    # ENROLLED machine — a new receipt (a new host row after a platform reset, a relabel) refused while an old
+    # credential.json was on disk used to be skipped for ever, by the timer and by a manual run alike, leaving a dead
+    # credential beside a valid receipt.
+    refused_before = bool(receipt_sha) and receipt_sha == record.get('receipt_refused_sha')
+    refusal_recent = (refused_before and config_sha == record.get('receipt_refused_config_sha')
+                      and time.time() - record.get('receipt_refused_at', 0) <= RETRY_KEY_AFTER)
+    skip_refused = refused_before and options['retry'] and refusal_recent
+    fresh_receipt = bool(receipt_sha) and receipt_sha != record.get('receipt_adopted_sha') and not skip_refused
+    if skip_refused:   # the one line the timer logs
+        code = record.get('receipt_refused_code', 'unknown')
+        print(f'receipt {receipt} was refused ({code}); the timer tries it again after an hour or when '
+              f'{layout.config} changes; a manual run of install/enable-studio-host.sh tries it now')
+    if enrolled and not fresh_receipt:
+        plan.say(f'enrolment: {layout.credential}')
+        return True
+    new_key = []
+    if credential is not None and not enrolled:
+        server, _facts = _configured_server(layout, options)
+        what = ('is for a machine key that is gone' if not layout.machine_key.exists()
+                else 'is for another machine key than the one on disk')
+        host = credential.get('host_id') or 'unrecorded'
+        machine = credential.get('machine_id') or 'unrecorded'
+        if not measured_revoked(layout, server):
+            raise EnrolmentRefused(
+                'credential_for_gone_key',
+                f'{layout.credential} (Studio Host {host}, machine {machine}) {what}, and this machine has not '
+                f'measured that host row revoked: it may still be enrolled — and if its key exists anywhere, able to '
+                f'dial. Enrolling now would enrol a SECOND machine beside it, so nothing was published or enrolled. '
+                f'Revoke host {host} (Revoke `{machine}` in the console, or `throttle-rc studio revoke --id {host}` '
+                'from an owner session), then run `lanes studio-host re-key --yes` — the explicit decision to enrol '
+                'this machine under a new key.', 3)
+        plan.say(f'enrolment: {layout.credential} {what}; this machine measured host {host} revoked, so the next '
+                 'enrolment is a new key (`--new-key`)')
+        new_key = ['--new-key']
+
+    # The retry republishes only when there is no key to have published (a re-key): publish-key is idempotent for
+    # an existing key, so a published key is re-written only on a manual run.
+    if not (options['retry'] and layout.public_jwk.exists() and layout.machine_key.exists()):
+        plan.step(f"publish this machine's PUBLIC key to {layout.public_jwk} (`throttle-rc studio publish-key`; the "
+                  'key is created here if absent and never leaves this machine)', lambda: _publish(layout))
+    if fresh_receipt:
+        def adopt():
+            # --config: the receipt must name the server THIS unit's Host dials (receipt_server_mismatch, exit 3,
+            # is refused before anything is installed or recorded as adopted).
+            rc, out, err = throttle_rc(layout, 'studio', 'adopt-receipt', '--file', str(receipt), '--config',
+                                       str(layout.config), *new_key, timeout=30)
+            if rc == 3:
+                # A typed refusal of these bytes under this config: remembered for the TIMER (see above).
+                record.update(receipt_refused_sha=receipt_sha, receipt_refused_config_sha=config_sha,
+                              receipt_refused_at=time.time(), receipt_refused_code=_refusal_code(err or out))
+                _save_record(layout, record)
+            if rc != 0:
+                raise _throttle_rc_failed('adopt-receipt', rc, out, err, EnrolmentRefused)
+            for key in RECEIPT_REFUSAL_MEMORY:
+                record.pop(key, None)
+            record.update(receipt_adopted_sha=receipt_sha, receipt_adopted_at=now_utc())
+            _save_record(layout, record)
+        plan.step(f"adopt the deploy receipt {receipt} (`throttle-rc studio adopt-receipt"
+                  + (' --new-key' if new_key else '') + "`; its machine_jkt must be this machine's key and its "
+                  "server this config's)", adopt)
+        return True
+    # Review round 6: the key's stat identity is taken only on the registration-key route — an unusable leftover key
+    # file used to refuse `key_unreadable` BEFORE a fresh deploy receipt, which needs no key, could be adopted.
+    # Review round 5: its stat identity, never its bytes — this module does not open the registration key.
+    key_id = key_fingerprint(key_file, KEY_UNREADABLE_REMEDY)
+    # The hour's memory is the TIMER's (design §8.10 C3 (c)): a manual run always tries the key — the operator just
+    # fixed the file or the server and asked (review round 1: the manual re-run the refusal tells them to make was
+    # silently skipped for an hour).
+    key_recent = (key_id == record.get('key_tried_stat')
+                  and time.time() - record.get('key_tried_at', 0) <= RETRY_KEY_AFTER)
+    if key_id and not (options['retry'] and key_recent):
+        server, facts = _configured_server(layout, options)
+        label = facts.get('machine_id') or options['machine_id'] or default_machine_id()
+
+        def enrol():
+            for key in KEY_REFUSAL_MEMORY:
+                record.pop(key, None)
+            record.update(key_tried_stat=key_id, key_tried_at=time.time())
+            _save_record(layout, record)
+            rc, out, err = throttle_rc(layout, 'studio', 'enroll', server, '--label', label,
+                                       '--registration-key-file', str(key_file), *new_key, timeout=120)
+            if rc != 0:
+                # Review round 6: what was answered is remembered beside the attempt, so `status` names the refusal
+                # (`key-refused`) for the hour the timer skips this key instead of pointing at the deploy.
+                record.update(key_failed_exit=rc if rc is not None else 'timeout',
+                              key_failed_code=_refusal_code(err or out) if rc in (2, 3) else 'throttle_rc_failed')
+                _save_record(layout, record)
+                raise _throttle_rc_failed('enroll', rc, out, err, EnrolmentRefused, typed_exits=(2, 3))
+        plan.step(f'enrol at {server} with the registration key in {key_file} (`throttle-rc studio enroll`'
+                  + (' --new-key: this machine measured the old host row revoked' if new_key else '')
+                  + '; the key is read by throttle-rc, never by this script)', enrol)
+        return True
+    if key_id and key_recent:
+        minutes = int((time.time() - record.get('key_tried_at', 0)) // 60)
+        plan.say(f'registration key {key_file} was tried {minutes} min ago and refused; the timer tries it again '
+                 'after an hour, a manual run of this script tries it now')
+    return False
+
+
+def _units(layout, plan):
+    """Step 6: render every lanes unit for this checkout (services.py), then enable the Host and its retry timer."""
+    repo = Path(__file__).resolve().parent.parent
+
+    def render():
+        sys.path.insert(0, str(repo / 'install'))
+        import services
+        # The roots THIS run resolved (Layout.from_env) are recorded, so a later `./install.sh --server` from a
+        # shell without them re-renders the studio units with the same ones (review round 4).
+        xdg = {name: os.environ[name] for name in services.XDG_ROOTS if os.environ.get(name)}
+        services.record_xdg(layout.state, xdg)
+        # Every lanes unit is re-rendered here, so the opt-in economy poller's and push notifier's settings come from
+        # this shell exactly as `./install.sh --server` takes them (install/services.py __main__): without them the
+        # enable step would strip an operator's LANES_THROTTLE_*/LANES_NOTIFY_CONF from those two units.
+        services.register(repo, layout.home, layout.share, layout.state, os.environ.get('LANES_WORKSPACES'),
+                          economy=services.economy_settings(os.environ), notify=services.notify_settings(os.environ),
+                          xdg=xdg, units_dir=manager_units_dir(layout))
+        _check_systemctl(*systemctl('daemon-reload'), 'daemon-reload')
+        _check_systemctl(*systemctl('enable', UNIT, ENROL_TIMER), f'enable {UNIT} {ENROL_TIMER}')
+        _check_systemctl(*systemctl('start', ENROL_TIMER), f'start {ENROL_TIMER}')
+    plan.step(f'render the lanes units (install/services.py), daemon-reload, enable {UNIT} and {ENROL_TIMER}, start '
+              'the timer', render)
+
+
+def _stale_refusal_only(rc, out):
+    """The `last_refusal` of a `studio host --check` document whose ONLY red is that recorded refusal (exit 3,
+    `identity.ok` true, `ok` false); None for anything else — an unparsable answer is never read as clean."""
+    if rc != 3:
+        return None
+    try:
+        doc = json.loads(out)
+    except ValueError:
+        return None
+    if not isinstance(doc, dict) or doc.get('ok') is not False:
+        return None
+    identity, refusal = doc.get('identity'), doc.get('last_refusal')
+    if not (isinstance(identity, dict) and identity.get('ok') is True and isinstance(refusal, str) and refusal):
+        return None
+    return refusal
+
+
+def _start(layout, options, record):
+    """Step 7: start — or restart, so a new config or binary is in force — a Host that is enrolled and checks clean.
+    The retry never restarts a Host that already ran with this enrolment: its exit 3 is a refusal, not a crash."""
+    credential_sha = readable_sha(layout.credential, 'credential_unreadable',
+                                  'it must be owned by this account (0600)')
+    active = unit_word('is-active', UNIT)
+    if options['retry']:
+        if active in ('active', 'activating'):
+            return 0
+        if credential_sha == record.get('started_credential_sha'):
+            print(f'{UNIT} is {active} with the enrolment it was already started with; not restarting it '
+                  '(`lanes studio-host status`)')
+            return 0
+    rc, out, err = throttle_rc(layout, 'studio', 'host', '--check', '--config', str(layout.config), timeout=60)
+    # Review round 6: whatever enrolment the recorded refusal was written under. The sha gate that stood here made a
+    # receipt adopted under a RUNNING Host (a relabel re-emits different bytes; the active-unit return above leaves
+    # `started_credential_sha` naming the old credential) turn the Host's own later refusal into `host_check_failed`
+    # on every timer tick AND on the documented manual re-run. The identity checks clean, so the Host is started and
+    # judges THIS enrolment; the timer starts it once per enrolment (the sha check above, recorded below).
+    stale = _stale_refusal_only(rc, out)
+    if rc != 0 and stale is None:
+        raise Refusal('host_check_failed', f'`throttle-rc studio host --check` exit {rc}; {UNIT} was not started:\n'
+                      + (out + err).strip()[-1500:], 3 if rc == 3 else 1)
+    if stale is not None:
+        # Review round 4: the Host this installer started with THIS enrolment stopped on a refusal (the owner's
+        # tunnel cap, a build mismatch, three displacements) and left it in state.json; `--check` reds on that
+        # record alone, and only a Host run rewrites it. The identity checks clean, so the Host is started and the
+        # settle window below judges THIS run — a refusal that still holds exits 3 again and is reported typed.
+        print(f'`studio host --check`: the enrolment checks clean; the only red is the refusal the last run of '
+              f'{UNIT} recorded ({stale[:200]}); starting it — its first phase replaces that record')
+    verb = 'restart' if active == 'active' else 'start'
+    _check_systemctl(*systemctl(verb, UNIT), f'{verb} {UNIT}')
+    record['started_credential_sha'] = credential_sha
+    _save_record(layout, record)
+    deadline = time.monotonic() + options['settle']
+    while True:
+        state = unit_word('is-active', UNIT)
+        if state != 'active':
+            raise Refusal('host_not_running', f'{UNIT} is {state} after {verb}: `journalctl --user -u {UNIT} -n 30` '
+                          '(exit 3 = a typed refusal from the Host)')
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            break
+        time.sleep(min(0.5, remaining))
+    print(f'running: {UNIT} {verb}ed and still active after {options["settle"]:g} s')
+    return 0
+
+
+def enable(argv, layout=None):
+    """`sh install/enable-studio-host.sh [options]` — see USAGE. Everything that can refuse statically (another Host
+    unit, the hand-built unit, no binary, the config mode) refuses before anything is changed."""
+    options = parse_enable_args(argv)
+    layout = layout or Layout.from_env()
+    if options['retry'] and not layout.config.exists():
+        print(f'{layout.config} is absent: nothing to retry (run install/enable-studio-host.sh)')
+        return 0
+    plan = Plan(options['dry_run'], quiet=options['retry'])
+    record = _record(layout)
+    receipt = Path(options['receipt']).absolute() if options['receipt'] else receipt_path(layout, record)
+    key_file = Path(options['key_file']).absolute() if options['key_file'] else key_path(layout, record)
+    hand_built = _one_host_per_machine(layout, options, record)
+    # Review round 4: a RUNNING hand-built Host on a machine with no credential.json (ceobox's shape: a human-session
+    # Host from before §8.7 enrolment) is enrolled FIRST, with the same machine key, while it still runs; only then is
+    # it checked, stopped and replaced.
+    enrol_first = (hand_built is not None and not layout.credential.exists()
+                   and unit_word('is-active', HAND_BUILT_UNIT) in ('active', 'activating', 'reloading'))
+    if enrol_first and not (receipt.exists() or key_file.exists()):
+        # Review round 5: with nothing to enrol from, the machine's PUBLIC key is published FIRST — the one artifact
+        # the deploy needs to adopt it (deploy/studio-adopt-host.sh reads it). Refusing before publishing left each
+        # side waiting for the other. publish-key loads the existing machine key and never rewrites it, and the
+        # hand-built Host, its unit and its config are not touched.
+        _ensure_binary(layout, options, plan)
+        plan.step(f"publish this machine's PUBLIC key to {layout.public_jwk} (`throttle-rc studio publish-key`; the "
+                  'existing machine key is loaded, never rewritten)', lambda: _publish(layout))
+        published = 'would be published' if options['dry_run'] else 'is published'
+        raise Refusal('hand_built_host_unenrolled', f'{HAND_BUILT_UNIT} is running, but this machine holds no '
+                      f'enrolment receipt ({layout.credential}): the hand-built Host authenticates another way (a '
+                      "login session), which the lanes unit never uses. This machine's PUBLIC key "
+                      f'{published} at {layout.public_jwk} (the machine key itself unchanged). Enrol first — deploy '
+                      f'with THROTTLE_RC_STUDIO_ADOPT_JWK={layout.public_jwk} THROTTLE_RC_STUDIO_ADOPT_OWNER=<the '
+                      f"owner's sign-in email> THROTTLE_RC_STUDIO_ADOPT_RECEIPT={receipt} (from where those paths "
+                      "are this machine's), or put the owner's registration key in "
+                      f'{key_file} (0600) — then re-run with --migrate-hand-built: the receipt is installed while '
+                      f'{HAND_BUILT_UNIT} still runs, and it is stopped only after the new Host checks clean. Nothing '
+                      'else was changed: the hand-built Host, its unit and its config are as they were.', 3)
+    _ensure_binary(layout, options, plan)
+    backup = _ensure_config(layout, options, plan)
+    if not options['dry_run']:
+        _remember_paths(layout, options, record)
+    replaced = []   # set once the hand-built unit is saved, disabled and stopped
+
+    def give_back():
+        """The hand-built Host reads the same config: until it is stopped, ANY failure gives it back the file it ran
+        with (review round 5: only an enrolment refusal and a failed check used to, so a failed publish-key, an
+        unreadable receipt or key, or a systemctl failure left it on a `mode` key its older binary refuses)."""
+        state = 'LEFT running and enabled' if enrol_first else 'not stopped or disabled'
+        if backup is None or options['dry_run']:
+            return f'{HAND_BUILT_UNIT} was {state}'
+        kept = Path(backup).read_bytes()
+        try:
+            current = layout.config.read_bytes()
+        except OSError:
+            current = None
+        if current != kept:
+            atomic_write(layout.config, kept, 0o600)
+        return f'{HAND_BUILT_UNIT} was {state}, {layout.config} was restored from {backup}'
+    try:
+        if enrol_first:
+            _enrol(layout, options, plan, record, receipt, key_file)
+            if not options['dry_run'] and not layout.credential.exists():
+                raise Refusal('hand_built_host_unenrolled', 'nothing enrolled this machine (no new receipt or '
+                              'registration key was tried)', 3)
+        if hand_built is not None:
+            _migrate_hand_built(layout, plan, hand_built, record, replaced)
+    except BaseException as failure:
+        if hand_built is not None and not replaced:
+            note = give_back()
+            if isinstance(failure, Refusal):
+                failure.sentence += f'\n{note}; nothing was replaced'
+            else:
+                print(f'{note}; nothing was replaced', file=sys.stderr)
+        raise
+    try:
+        enrolled = _enrol(layout, options, plan, record, receipt, key_file)
+    except EnrolmentRefused as refusal:
+        # Review round 3: a refused (or failed) receipt/key on the FIRST run used to end it before the units were
+        # rendered, so no Host unit and no enrol timer existed while every surface promised the timer would retry.
+        # The machine is left genuinely enabled and waiting; the refusal is still the run's answer (its exit code).
+        if not options['retry']:
+            _units(layout, plan)
+            refusal.sentence += (f'\n{UNIT} is enabled and waiting for enrolment: {ENROL_TIMER} tries again '
+                                 'when the receipt or key changes, the config changes, or the hour passes; a '
+                                 'manual run of install/enable-studio-host.sh tries now')
+        raise
+    if not options['retry']:
+        _units(layout, plan)
+    if options['dry_run']:
+        print(f'would: run `studio host --check`, then start (or restart) {UNIT}' if enrolled
+              else f'would: leave {UNIT} enabled and waiting for enrolment')
+        return 0
+    # Review round 6: the enrolment `_enrol` measured, never "a credential.json exists" — a dead receipt beside a new
+    # key (measured revoked, waiting for the deploy) is waiting, and is not started or checked.
+    if not enrolled or not layout.credential.exists():
+        print(f'waiting for enrolment: {UNIT} is enabled and exits 3 until this machine is enrolled.\n'
+              f'  deploy-provisioned: THROTTLE_RC_STUDIO_ADOPT_JWK={layout.public_jwk}, '
+              f'THROTTLE_RC_STUDIO_ADOPT_RECEIPT={receipt}; {ENROL_TIMER} adopts the receipt within 5 minutes\n'
+              f"  or: put the owner's registration key in {key_file} (0600) and re-run this"
+              if not options['retry'] else 'waiting for enrolment: no new receipt or registration key')
+        return 0
+    return _start(layout, options, record)
+
+
+# ------------------------------------------------------------------------------------------- re-key
+
+REKEY_FORGET = ('receipt_adopted_sha', 'receipt_adopted_at', 'receipt_refused_sha', 'receipt_refused_config_sha',
+                'receipt_refused_at', 'receipt_refused_code', 'key_tried_stat', LEGACY_KEY_DIGEST, 'key_tried_at',
+                'started_credential_sha')
+
+
+def re_key(argv, layout=None):
+    """`lanes studio-host re-key [--yes] [--dry-run]` — the documented remedy after the owner revokes this machine
+    (design §8.10 C4, review round 1). A revoked key is never adopted again, so the machine needs a NEW key: stop the
+    Host, remove the machine key, the dead credential, the published key, the old receipt and the Host's refused
+    state, forget the enrolment record's receipt/key memory (the hand-built migration record stays), then publish the
+    new PUBLIC key. The next deploy adopts it and the enrol timer installs the receipt; or put a registration key in
+    place and run install/enable-studio-host.sh. Without --yes it prints the plan and changes nothing (exit 2)."""
+    unknown = [a for a in argv if a not in ('--yes', '--dry-run')]
+    if unknown:
+        raise Refusal('usage', 'usage: lanes studio-host re-key [--yes] [--dry-run]', 2)
+    layout = layout or Layout.from_env()
+    dry_run = '--dry-run' in argv or '--yes' not in argv
+    plan = Plan(dry_run)
+    word, detail, _pin = verify_installed(layout)
+    if word != 'verified':
+        raise Refusal('binary_mismatch' if word == 'mismatch' else 'no_binary', detail)
+    active = unit_word('is-active', UNIT)
+    if active == 'no-answer':
+        # Review round 2: an unanswered manager is not "stopped" — deleting the key under a Host that may be running
+        # is refused, never guessed.
+        raise Refusal('manager_unreachable', f'the user manager did not answer `systemctl --user is-active {UNIT}`, '
+                      'so whether the Host runs is unknown and its key is not removed under it. Run this from a '
+                      'login of this account (XDG_RUNTIME_DIR set), or stop the Host first.')
+    # Review round 5: the key is shared by EVERY Host unit of this account, not only the lanes one. The hand-built
+    # sharing Host (ceobox) and `throttle-rc studio service`'s own unit run with this very machine key; removing it
+    # under either makes its next proof fail. Refused while either may be running — the manager is asked, never
+    # assumed.
+    for other, remedy in ((HAND_BUILT_UNIT, 'migrate it first (sh install/enable-studio-host.sh --migrate-hand-built '
+                           f'— that keeps the key), or stop and disable it (systemctl --user disable --now {HAND_BUILT_UNIT})'),
+                          (SUPERVISOR_UNIT, 'remove it first (throttle-rc studio service uninstall --yes)')):
+        state = unit_word('is-active', other)
+        if state in ('active', 'activating', 'reloading', 'deactivating', 'no-answer'):
+            raise Refusal('another_host_running', f'{other} is {state}: it runs a Host with this machine key '
+                          f'({layout.machine_key}), so the key is not removed under it. Nothing was changed; {remedy}, '
+                          'then re-run `lanes studio-host re-key`.')
+    remembered = receipt_path(layout, _record(layout))
+    # Review round 6: the machine key is removed LAST, and every path is checked removable BEFORE anything changes.
+    # It used to go first, so a remembered --receipt in a directory this account may not write (the deploying
+    # account's — the very place RECEIPT_UNREADABLE_REMEDY points at) ended the run in a PermissionError traceback
+    # with the key already destroyed, the record unchanged and no new key published; every re-run failed the same way.
+    doomed = [path for path in dict.fromkeys((layout.credential, layout.public_jwk, layout.receipt, remembered,
+                                              layout.host_state, layout.machine_key))
+              if path.exists() or path.is_symlink()]
+    blocked = [path for path in doomed if not os.access(path.parent, os.W_OK | os.X_OK)]
+    if blocked:
+        detail = '; '.join(f'{path} (its directory: {unreadable_detail(path.parent, PermissionError(errno.EACCES, os.strerror(errno.EACCES)))})'
+                           for path in blocked)
+        raise Refusal('rekey_path_unremovable', f'this account cannot remove {detail}. Nothing was changed: give it '
+                      'write access to that directory, or remove the file as its owner, then re-run '
+                      '`lanes studio-host re-key`.')
+    if active in ('active', 'activating', 'reloading'):
+        plan.step(f'stop {UNIT} (it is {active})', lambda: _check_systemctl(*systemctl('stop', UNIT), f'stop {UNIT}'))
+
+    def remove():
+        for path in doomed:
+            try:
+                path.unlink()
+            except FileNotFoundError:
+                continue
+            except OSError as error:
+                raise Refusal('rekey_path_unremovable', f'{path}: {unreadable_detail(path, error)}. Removed so far: '
+                              + (', '.join(str(p) for p in doomed[:doomed.index(path)]) or 'nothing')
+                              + f'; the machine key {layout.machine_key} is removed last and was '
+                              + ('not touched' if path != layout.machine_key else 'not removed')
+                              + '. Fix the permission, then re-run `lanes studio-host re-key --yes`.') from error
+        record = _record(layout)
+        for key in REKEY_FORGET:
+            record.pop(key, None)
+        record['rekeyed_at'] = now_utc()
+        _save_record(layout, record)
+    plan.step('remove ' + (', '.join(str(p) for p in doomed) or 'nothing (no key or enrolment on disk)')
+              + f' and forget the receipt/key memory in {layout.record}', remove)
+
+    plan.step(f"publish the NEW machine's PUBLIC key to {layout.public_jwk} (`throttle-rc studio publish-key`)",
+              lambda: _publish(layout))
+    if '--yes' not in argv:
+        print('nothing was changed: re-run with --yes (the old key cannot be restored; any throttle-rc session on '
+              'this account bound to it must log in again)')
+        return 2
+    if dry_run:
+        return 0
+    print(f'next: deploy again (THROTTLE_RC_STUDIO_ADOPT_JWK={layout.public_jwk}); {ENROL_TIMER} installs the new '
+          f"receipt within 5 minutes. Or put the owner's registration key in {layout.registration_key} (0600) and run "
+          'sh install/enable-studio-host.sh')
+    return 0
+
+
+# ------------------------------------------------------------------------------------------- status
+
+def unit_contract_missing(text):
+    return [line for line in UNIT_CONTRACT if line not in text]
+
+
+def status_facts(layout, check=False):
+    word, detail, pin = verify_installed(layout)
+    facts = {'binary': {'state': word, 'detail': detail, 'path': str(layout.binary),
+                        'version': (pin or {}).get('version'), 'source': (pin or {}).get('source')}}
+    try:
+        facts['lock_pin'] = getattr(parse_lock(lock_path().read_text()).get(BINARY), 'version', None)
+    except (OSError, Refusal) as error:
+        facts['lock_pin'] = f'unreadable: {error}'
+    config = {'path': str(layout.config), 'present': layout.config.exists()}
+    if config['present']:
+        try:
+            parsed = config_facts(read_config_text(layout))
+        except Refusal as refusal:   # review round 5: said, never a traceback
+            config.update(readable=False, detail=refusal.sentence)
+        else:
+            config.update(readable=True, mode=parsed['mode'], server=parsed.get('server'),
+                          machine_id=parsed.get('machine_id'),
+                          sharing_state_dir=parsed['inventory'].get('sharing_state_dir'))
+    facts['config'] = config
+    credential = load_credential(layout)
+    record = _record(layout)
+    receipt, key_file = receipt_path(layout, record), key_path(layout, record)
+    receipt_readable = is_readable(receipt) if receipt.exists() else None
+    # Review round 3: the timer's refusal memory, surfaced. A receipt on disk whose bytes the installer recorded as
+    # refused is NOT "waiting for the deploy": the deploy did its part and the Host side refused it.
+    refused = None
+    if receipt_readable and record.get('receipt_refused_sha'):
+        try:
+            on_disk = sha256_file(receipt)
+        except OSError:
+            on_disk = None
+        if on_disk == record['receipt_refused_sha']:
+            config_now = None
+            if layout.config.exists():
+                try:
+                    config_now = sha256_file(layout.config)
+                except OSError:
+                    config_now = None
+            at = record.get('receipt_refused_at') or 0
+            refused = {'code': record.get('receipt_refused_code', 'unknown'),
+                       'at': time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime(at)) if at else None,
+                       'config_changed_since': config_now != record.get('receipt_refused_config_sha'),
+                       'retry_after_s': max(0, int(at + RETRY_KEY_AFTER - time.time())) if at else 0}
+    # Review round 6: the registration key's refusal, surfaced as the receipt's is — while the timer's memory of it
+    # holds (the same file, within the hour). Its stat identity only: never opened.
+    key_refused = None
+    if record.get('key_failed_exit') is not None and key_file.exists() and os.access(key_file, os.R_OK):
+        try:
+            same_key = key_fingerprint(key_file, '') == record.get('key_tried_stat')
+        except (Refusal, OSError):
+            same_key = False
+        at = record.get('key_tried_at') or 0
+        if same_key and at:
+            key_refused = {'code': record.get('key_failed_code') or 'unknown', 'exit': record['key_failed_exit'],
+                           'at': time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime(at)),
+                           'retry_after_s': max(0, int(at + RETRY_KEY_AFTER - time.time()))}
+    binding = key_binding(layout, credential) if credential is not None else None
+    server = config.get('server') if config.get('readable') else None
+    # Review rounds 4 and 6: the predicate `_enrol` uses — a credential whose machine key is gone, or is NOT the key
+    # this machine published, is not an enrolment.
+    facts['enrolment'] = {
+        'enrolled': credential is not None and layout.machine_key.exists() and binding is not False,
+        'machine_key_present': layout.machine_key.exists(),
+        'key_binding': {True: 'verified', False: 'another key', None: 'unchecked'}[binding],
+        'measured_revoked': measured_revoked(layout, server) if credential is not None else None,
+        'via': (credential or {}).get('via', 'unrecorded') if credential is not None else None,
+        'machine_id': (credential or {}).get('machine_id'), 'owner': (credential or {}).get('owner_user_word_id'),
+        'host_id': (credential or {}).get('host_id'),
+        'public_key': str(layout.public_jwk) if layout.public_jwk.exists() else None,
+        'receipt': str(receipt) if receipt.exists() else None,
+        'receipt_path': str(receipt),
+        'receipt_readable': receipt_readable,
+        'receipt_adopted_at': record.get('receipt_adopted_at'),
+        'receipt_refused': refused,
+        'registration_key_file': str(key_file) if key_file.exists() else None,
+        # access(2), never an open (review round 5: this module does not open the registration key)
+        'registration_key_readable': os.access(key_file, os.R_OK) if key_file.exists() else None,
+        'registration_key_tried_at': (time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime(record['key_tried_at']))
+                                      if record.get('key_tried_at') else None),
+        'registration_key_refused': key_refused,
+    }
+    installed = manager_units_dir(layout) / UNIT
+    facts['unit'] = {'file': installed.exists(), 'path': str(installed),
+                     'contract_missing': unit_contract_missing(installed.read_text()) if installed.exists() else None,
+                     'enabled': unit_word('is-enabled', UNIT), 'active': unit_word('is-active', UNIT),
+                     'enrol_timer': unit_word('is-active', ENROL_TIMER)}
+    facts['conflicts'] = {SUPERVISOR_UNIT: unit_word('is-active', SUPERVISOR_UNIT),
+                          HAND_BUILT_UNIT: unit_word('is-active', HAND_BUILT_UNIT)}
+    facts['state'], facts['next'] = classify(facts)
+    if check and word == 'verified' and config['present'] and config.get('readable'):
+        rc, out, err = throttle_rc(layout, 'studio', 'host', '--check', '--config', str(layout.config), timeout=60)
+        facts['check'] = {'exit': rc, 'output': (out + err).strip()[-4000:]}
+        # Review round 2: `--check` binds the exit. A running unit whose own check refuses is not "running".
+        if facts['state'] == 'running' and rc != 0:
+            facts['state'] = 'running-check-failed'
+            facts['next'] = (f'the unit runs but `throttle-rc studio host --check` exit {rc}: read its output below '
+                             f'and journalctl --user -u {UNIT} -n 30')
+    return facts
+
+
+ENABLED_WORDS = ('enabled', 'enabled-runtime', 'linked', 'linked-runtime', 'alias')
+
+
+def classify(facts):
+    """-> (state word, next step). Words: running | running-unenrolled | waiting-for-enrolment | receipt-refused |
+    key-refused | credential-for-gone-key | receipt-unreadable | key-unreadable | config-unreadable | not-enabled |
+    stopped | failed | conflict | not-installed | unknown (and,
+    with --check, running-check-failed, set by status_facts). `unknown` when the manager did not answer: never
+    guessed. Only `running` (active AND enrolled, and with --check its check exit 0) exits 0."""
+    unit, binary = facts['unit'], facts['binary']
+    if facts['config'].get('readable') is False:
+        return 'config-unreadable', f"{facts['config']['detail']}; then sh install/enable-studio-host.sh"
+    if 'active' in facts['conflicts'].values():
+        other = next(name for name, state in facts['conflicts'].items() if state == 'active')
+        return 'conflict', f'{other} is running a Host on this machine: see docs/SHARING.md "Migrating the hand-built unit"'
+    if binary['state'] != 'verified' or not unit['file'] or not facts['config']['present']:
+        return 'not-installed', 'sh install/enable-studio-host.sh --server URL [--from PATH]'
+    if unit['active'] == 'no-answer':
+        return 'unknown', 'the user manager did not answer: systemctl --user status lanes-studio-host.service'
+    enrolled = facts['enrolment']['enrolled']
+    if unit['active'] == 'active':
+        return ('running', '') if enrolled else ('running-unenrolled',
+                                                 'the Host runs without an enrolment receipt: check it')
+    if not enrolled and facts['enrolment'].get('receipt_readable') is False:
+        return 'receipt-unreadable', (f"{facts['enrolment']['receipt']} exists but this account cannot read it, so "
+                                      f'{ENROL_TIMER} cannot install it: {RECEIPT_UNREADABLE_REMEDY}')
+    if not enrolled and facts['enrolment'].get('registration_key_readable') is False:
+        return 'key-unreadable', (f"{facts['enrolment']['registration_key_file']} exists but this account cannot read "
+                                  f'it: {KEY_UNREADABLE_REMEDY}')
+    # Review round 3: "waiting" is said only of a machine whose waiting is real — the Host unit enabled AND the enrol
+    # timer active. Otherwise nothing will retry (a refused first enable used to leave neither installed).
+    if unit['enabled'] == 'no-answer' or unit['enrol_timer'] == 'no-answer':
+        return 'unknown', 'the user manager did not answer: systemctl --user status lanes-studio-host.service'
+    timer_waits = unit['enabled'] in ENABLED_WORDS and unit['enrol_timer'] in ('active', 'activating')
+    refused = facts['enrolment'].get('receipt_refused')
+    # Review round 4: a refused receipt on disk is named whether or not an (older) credential.json exists — an
+    # enrolled-but-stopped machine beside a refused NEW receipt is not merely `stopped`.
+    if refused:
+        if not timer_waits:
+            when = 'nothing retries it: the units are not enabled'
+        elif refused['config_changed_since']:
+            when = f'{ENROL_TIMER} tries it again on its next tick (the config changed since)'
+        else:
+            when = (f"{ENROL_TIMER} tries it again in {refused['retry_after_s'] // 60} min or when "
+                    'studio-host.toml changes')
+        return 'receipt-refused', (f"adopt-receipt refused {facts['enrolment']['receipt']} ({refused['code']}) at "
+                                   f"{refused['at']}; {when}. receipt_server_mismatch: make the config's `server` the "
+                                   "deployment's URL; receipt_key_mismatch: the deploy adopted another key — redeploy "
+                                   'with this public key; then run sh install/enable-studio-host.sh to try it now')
+    enrolment = facts['enrolment']
+    if not enrolled and enrolment.get('via') is not None and enrolment.get('measured_revoked') is False:
+        # Review round 6: a receipt whose key is gone (or is another key) for a row this machine has NOT measured
+        # revoked — `_enrol` refuses to enrol a second machine beside it.
+        host = enrolment.get('host_id') or 'unrecorded'
+        return 'credential-for-gone-key', (f"the receipt on disk (host {host}, machine {enrolment['machine_id']}) is "
+                                           "not for the machine key on disk, and this machine has not measured that "
+                                           f"row revoked: revoke host {host} (console, or `throttle-rc studio revoke "
+                                           f"--id {host}`), then lanes studio-host re-key --yes")
+    key_refused = enrolment.get('registration_key_refused')
+    if not enrolled and key_refused:
+        # Review round 6: the key route's refusal, named as the receipt's is (it used to say "waiting" and point at
+        # the deploy while the timer skipped the key for the hour).
+        when = (f"{ENROL_TIMER} tries it again in {key_refused['retry_after_s'] // 60} min or when the file changes"
+                if timer_waits else 'nothing retries it: the units are not enabled')
+        return 'key-refused', (f"`throttle-rc studio enroll` refused {enrolment['registration_key_file']} "
+                               f"({key_refused['code']}, exit {key_refused['exit']}) at {key_refused['at']}; {when}; "
+                               f'a manual run of sh install/enable-studio-host.sh tries it now '
+                               f'(journalctl --user -u {ENROL_SERVICE} -n 20 has its line)')
+    if not enrolled and not timer_waits:
+        return 'not-enabled', (f"{UNIT} is {unit['enabled']} and {ENROL_TIMER} is {unit['enrol_timer']}, so nothing "
+                               'retries the enrolment: run sh install/enable-studio-host.sh')
+    if not enrolled:
+        return 'waiting-for-enrolment', ('the deploy adopts the public key and writes the receipt; '
+                                         f'{ENROL_TIMER} installs it (or: registration key file, re-run the enable step)')
+    if unit['active'] == 'failed':
+        return 'failed', f'journalctl --user -u {UNIT} -n 30, then systemctl --user reset-failed {UNIT}'
+    return 'stopped', f'journalctl --user -u {UNIT} -n 30 (exit 3 = typed refusal), then systemctl --user start {UNIT}'
+
+
+def print_status(facts):
+    print(f"state: {facts['state']}" + (f"  — next: {facts['next']}" if facts['next'] else ''))
+    binary = facts['binary']
+    print(f"binary: {binary['state']} — {binary['detail']}; holders.lock pin: {facts['lock_pin'] or 'none yet'}")
+    config = facts['config']
+    if config['present'] and config.get('readable') is False:
+        print(f"config: {config['path']} — unreadable by this account")
+    else:
+        print(f"config: {config['path']}" + (f" — mode {config.get('mode')}, server {config.get('server')}, machine "
+                                              f"{config.get('machine_id')}" if config['present'] else ' — absent'))
+    enrolment = facts['enrolment']
+    if enrolment['enrolled']:
+        print(f"enrolment: via {enrolment['via']}, machine {enrolment['machine_id']}, owner {enrolment['owner']}")
+    else:
+        if enrolment['via'] is not None:   # a credential.json whose machine key is gone, or is another key
+            which = 'gone' if not enrolment['machine_key_present'] else 'not the key on disk'
+            revoked = (' (this machine measured that host row revoked)' if enrolment.get('measured_revoked')
+                       else ' (NOT measured revoked here)')
+            print(f"enrolment: the receipt on disk (machine {enrolment['machine_id']}) is for a machine key that is "
+                  f'{which}{revoked}; it does not enrol this machine')
+        key_word = 'none'
+        if enrolment['registration_key_file']:
+            refused = enrolment.get('registration_key_refused')
+            key_word = 'present' + (f" — tried {refused['at']}, refused {refused['code']} (exit {refused['exit']})"
+                                    if refused else '')
+        print('enrolment: none — public key ' + (enrolment['public_key'] or 'not published')
+              + '; receipt ' + (enrolment['receipt'] or f"none (watching {enrolment['receipt_path']})")
+              + '; registration key file ' + key_word)
+    if enrolment.get('receipt_refused'):
+        refused = enrolment['receipt_refused']
+        print(f"receipt refused: {refused['code']} at {refused['at']} (journalctl --user -u {ENROL_SERVICE} -n 20)")
+    unit = facts['unit']
+    print(f"unit: {UNIT} file {'present' if unit['file'] else 'absent'}, {unit['enabled']}, {unit['active']}; "
+          f"{ENROL_TIMER} {unit['enrol_timer']}")
+    if unit['contract_missing']:
+        print(f"  the installed unit lacks: {'; '.join(unit['contract_missing'])} — re-run ./install.sh --server")
+    print('other Host units: ' + ', '.join(f'{name} {state}' for name, state in facts['conflicts'].items()))
+    if 'check' in facts:
+        print(f"studio host --check: exit {facts['check']['exit']}")
+        print(facts['check']['output'])
+
+
+def run_cli(args):
+    """`lanes studio-host <verb>` (bin/lanes hands over its arguments; `main` types the refusals)."""
+    verb, rest = (args[0], args[1:]) if args else ('status', [])
+    layout = Layout.from_env()
+    if verb == 'status':
+        unknown = [a for a in rest if a not in ('--json', '--check')]
+        if unknown:
+            raise Refusal('usage', 'usage: lanes studio-host status [--json] [--check]', 2)
+        facts = status_facts(layout, check='--check' in rest)
+        if '--json' in rest:
+            print(json.dumps({'schema': 'lanes.studio-host-status', 'version': 1, **facts}, indent=1, sort_keys=True))
+        else:
+            print_status(facts)
+        return 0 if facts['state'] == 'running' else 1
+    if verb == 'install':
+        source = expected = None
+        items = list(rest)
+        while items:
+            item = items.pop(0)
+            if item in ('--from', '--sha256') and items:
+                source, expected = (items.pop(0), expected) if item == '--from' else (source, items.pop(0))
+            else:
+                raise Refusal('usage', 'usage: lanes studio-host install [--from PATH [--sha256 HEX]]', 2)
+        if expected and not source:
+            raise Refusal('usage', '--sha256 goes with --from', 2)
+        if source:
+            record = install_local(layout, source, expected)
+        else:
+            pins = parse_lock(lock_path().read_text())
+            if BINARY not in pins:
+                raise Refusal('no_binary', f'holders.lock pins no {BINARY} release yet: use --from PATH')
+            record = install_pinned(layout, pins[BINARY])
+        print(f"selected {layout.binary} -> {BINARY}-{record['version']} (sha256 {record['sha256']}); nothing was "
+              f'restarted: `systemctl --user restart {UNIT}` puts it in force')
+        return 0
+    if verb == 'enable':
+        return enable(rest, layout)
+    if verb == 're-key':
+        return re_key(rest, layout)
+    raise Refusal('usage', 'usage: lanes studio-host status [--json] [--check] | install [--from PATH [--sha256 HEX]]'
+                  ' | re-key [--yes] [--dry-run]', 2)
+
+
+def main(argv):
+    try:
+        return run_cli(argv)
+    except Refusal as refusal:
+        print(f'refused {refusal.code}: {refusal.sentence}', file=sys.stderr)
+        return refusal.exit_code
+
+
+if __name__ == '__main__':
+    sys.exit(main(sys.argv[1:]))