@ashlr/hub 3.12.0 → 3.14.0

package/dist/cli/authority.js

@@ -15,13 +15,16 @@
  *   github-app [--org <login>] [--yes]    GitHub App manifest flow; the key goes straight to custody
  *   rotate-provenance [--yes]             replace the provenance HMAC key agents could read
  *   setup [--dry-run [--json]] [--yes] [--source <ashlr-hub checkout>]   the guided Phase-0 command
+ *   resident start|stop|status [--json]   the resident daemon service under the grant (docs/RESIDENT-RUNTIME.md)
  *
  * LOWERING never asks anything. Everything that raises authority or touches
  * GitHub asks first (or needs --yes) and prints exactly what it did. Nothing
- * here ever runs `sudo`, changes launchd, or prints a secret.
+ * here ever runs `sudo` or prints a secret. Only `resident start` / `resident
+ * stop` change launchd, only for ai.ashlr.daemon, and `start` only after the
+ * operator confirms at a terminal under an active standing grant (no --yes).
  */
-import { spawnSync } from 'node:child_process';
-import { createPublicKey, randomBytes } from 'node:crypto';
+import { execFile, spawnSync } from 'node:child_process';
+import { createHash, createPublicKey, randomBytes } from 'node:crypto';
 import { existsSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { createServer } from 'node:http';
 import { homedir, tmpdir } from 'node:os';
@@ -30,9 +33,10 @@ import { createInterface } from 'node:readline';
 import { CUSTODY_HELPER_PATH } from '../core/authority/custody-client.js';
 // Loaded lazily: `authority stop` and friends must never depend on the daemon
 // service module being importable.
-async function realDaemonService() {
-    const { serviceStatus } = await import('../core/daemon/service.js');
-    const status = serviceStatus();
+// `cached` (the Verse probe) reuses a launchd read up to 15 s old.
+async function realDaemonService(cached = false) {
+    const { serviceStatus, serviceStatusCached } = await import('../core/daemon/service.js');
+    const status = cached ? serviceStatusCached() : serviceStatus();
     if (status.running)
         return 'running';
     if (status.registrationState === 'absent')
@@ -117,8 +121,118 @@ async function defaultDeps() {
         fetch: globalThis.fetch,
         custody: await import('../core/authority/custody-client.js'),
         daemonService: realDaemonService,
+        resident: realResidentDeps,
     };
 }
+async function residentServiceOptions() {
+    const { loadConfigReadOnlyStrict } = await import('../core/config.js');
+    const { daemonServiceInstallOptions } = await import('../core/daemon/service-config.js');
+    let cfg;
+    try {
+        cfg = loadConfigReadOnlyStrict();
+    }
+    catch (error) {
+        return { ok: false, problem: `config.json could not be read (${error.message.slice(0, 160)})` };
+    }
+    // ALWAYS regenerated from config (daemon.dailyBudgetUsd / intervalMs /
+    // parallel) — never carried over from an earlier install, so a budget
+    // changed in config reaches the service on the next `resident start`.
+    const opts = daemonServiceInstallOptions(cfg, { autostart: true });
+    return { ok: true, opts, budgetUsd: opts.budget ?? null };
+}
+/** The installed service file: its text, null when absent, undefined when unreadable. */
+function readServiceFile(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        return error.code === 'ENOENT' ? null : undefined;
+    }
+}
+const realResidentDeps = {
+    admission: async () => (await import('../core/authority/resident.js')).observeResidentAdmission().admission,
+    observe: async () => {
+        const { residentPlistState, plistBudgetUsd } = await import('../core/authority/resident.js');
+        const { generateServiceDefinition } = await import('../core/daemon/service.js');
+        let state;
+        try {
+            state = await realDaemonService();
+        }
+        catch {
+            state = 'unknown';
+        }
+        const prepared = await residentServiceOptions();
+        const def = generateServiceDefinition(prepared.ok ? prepared.opts : {});
+        const installed = readServiceFile(def.filePath);
+        return {
+            state,
+            plist: residentPlistState(installed, prepared.ok ? def.content : null),
+            plistPath: def.filePath,
+            installedBudgetUsd: plistBudgetUsd(installed ?? null),
+            expectedBudgetUsd: prepared.ok ? prepared.budgetUsd : null,
+            problem: prepared.ok ? null : prepared.problem,
+        };
+    },
+    operatorRefusal: async () => {
+        const { operatorContextRefusal, currentOperatorContext } = await import('../core/authority/resident.js');
+        return operatorContextRefusal(currentOperatorContext());
+    },
+    start: async () => {
+        const resident = await import('../core/authority/resident.js');
+        const service = await import('../core/daemon/service.js');
+        const { appendLedger } = await import('../core/authority/ledger.js');
+        const prepared = await residentServiceOptions();
+        if (!prepared.ok)
+            return { ok: false, reason: prepared.problem };
+        // The mint re-observes the operator context and re-verifies the grant,
+        // the build identity and the authority surface itself: nothing this
+        // command computed or printed earlier counts toward the decision.
+        const minted = resident.mintResidentServiceCapability();
+        if (!minted.ok)
+            return { ok: false, reason: minted.reason };
+        const def = service.generateServiceDefinition(prepared.opts);
+        const digest = createHash('sha256').update(def.content, 'utf8').digest('hex');
+        const grantId = minted.capability.grantId;
+        const detail = `release ${minted.admission.revision?.slice(0, 12) ?? '?'} · plist sha256 ${digest.slice(0, 16)} · `
+            + `budget $${prepared.budgetUsd ?? '?'}/day · interval ${prepared.opts.intervalMs ?? '?'} ms · parallel ${prepared.opts.parallel ?? '?'}`;
+        // Fail closed: a start the authority ledger cannot record does not happen.
+        const recorded = appendLedger({ kind: 'note', actor: 'mason', grantId, repo: null, data: { topic: 'resident-service:start', detail } });
+        if (!recorded.ok)
+            return { ok: false, reason: `the ledger refused the start record: ${recorded.reason}` };
+        try {
+            await service.installResidentService(prepared.opts, minted.capability);
+        }
+        catch (error) {
+            appendLedger({ kind: 'note', actor: 'mason', grantId, repo: null, data: { topic: 'resident-service:start-failed', detail: error.message.slice(0, 300) } });
+            return { ok: false, reason: error.message };
+        }
+        const status = service.serviceStatus(prepared.opts);
+        const grant = `grant #${minted.admission.grantSeq ?? '?'}`;
+        return {
+            ok: true,
+            detail: status.running
+                ? `ai.ashlr.daemon is running under ${grant} (${detail})`
+                : `ai.ashlr.daemon is installed and loaded under ${grant}, but launchd has not reported it running yet — check \`${resident.RESIDENT_STATUS_COMMAND}\` (${detail})`,
+        };
+    },
+    stop: async () => {
+        const service = await import('../core/daemon/service.js');
+        try {
+            await service.uninstall({});
+        }
+        catch (error) {
+            return { ok: false, reason: error.message };
+        }
+        try {
+            const { appendLedger } = await import('../core/authority/ledger.js');
+            appendLedger({ kind: 'note', actor: 'mason', grantId: null, repo: null, data: { topic: 'resident-service:stop', detail: 'ai.ashlr.daemon booted out and its plist removed' } });
+        }
+        catch {
+            // Lowering never depends on the ledger.
+        }
+        return { ok: true, detail: 'ai.ashlr.daemon is stopped and its plist removed' };
+    },
+};
 const VALUE_FLAGS = new Set(['--reason', '--payload', '--switch', '--limit', '--kind', '--repo', '--org', '--source']);
 function parseArgs(args) {
     const out = { positional: [], flags: new Set(), values: new Map() };
@@ -163,6 +277,9 @@ const USAGE = `Usage: ashlr authority <command>
   rotate-provenance [--yes]              Replace the provenance HMAC key
   setup [--dry-run [--json]] [--yes] [--source <checkout>]
                                          Guided Phase 0: custody, trust root, App, token, canary, rulesets, first grant, daemon
+  resident start                         Install / restart the resident daemon under the active grant (you confirm here)
+  resident stop                          Boot the resident daemon out and remove its plist (Stop is separate)
+  resident status [--json]               Resident admission, service state and plist drift
 
 Lowering authority never asks. Anything that raises it asks first (or takes --yes).`;
 // ---------------------------------------------------------------------------
@@ -211,6 +328,8 @@ export async function runAuthorityCli(args, injected) {
                 return await cmdRotateProvenance(parsed, deps);
             case 'setup':
                 return await cmdSetup(parsed, deps);
+            case 'resident':
+                return await cmdResident(rest[0], parsed, deps);
             default:
                 deps.err(`Unknown authority command: ${command}`);
                 deps.out(USAGE);
@@ -249,12 +368,48 @@ async function cmdStatus(parsed, deps) {
         const merging = status.policy.repos.filter((repo) => repo.stage === 'merge').map((repo) => repo.nameWithOwner);
         deps.out(`Policy: ${status.policy.repos.length} repos (${merging.length} merging), engines ${status.policy.engines.join(', ')}, caps ${status.policy.merge.maxFiles}/${status.policy.merge.maxLines}`);
     }
+    for (const line of await enforcementStatusLines(deps))
+        deps.out(line);
     deps.out(`Ledger: ${status.ledger.state}${status.ledger.head ? `, ${status.ledger.head.seq + 1} entries, head ${status.ledger.head.hash.slice(0, 12)}` : ''}${status.ledger.reason ? ` — ${status.ledger.reason}` : ''}`);
     const c = status.custody;
     const yn = (v) => (v === null ? 'unknown' : v ? 'yes' : 'no');
     deps.out(`Custody: installed ${yn(c.installed)}, key ${yn(c.keyInitialized)}, GitHub App ${yn(c.githubApp)}, Claude token ${yn(c.claudeToken)}`);
     return 0;
 }
+/**
+ * `status`: does GitHub still enforce what the installed grant says? Only the
+ * grant's `server` repos are read (local ones need nothing from GitHub). A
+ * mismatch is REPORTED, never fixed here — the signed grant is only ever
+ * changed by a re-approval, which switches such a repo to local enforcement.
+ */
+async function enforcementStatusLines(deps) {
+    const { readInstalledGrant } = await import('../core/authority/standing-grant.js');
+    const installed = readInstalledGrant();
+    if (installed.state !== 'ok')
+        return [];
+    const grant = installed.envelope.payload;
+    const server = grant.repos.filter((repo) => repo.enforcement === 'server');
+    if (server.length === 0)
+        return [];
+    const { enforcementMismatch, probeServerEnforcementAll } = await import('../core/authority/server-enforcement.js');
+    const probes = await probeServerEnforcementAll(server.map((repo) => repo.nameWithOwner), ghGet(deps));
+    const lines = [];
+    const unread = [];
+    let enforced = 0;
+    for (const repo of server) {
+        const probe = probes.get(repo.nameWithOwner.toLowerCase());
+        const mismatch = enforcementMismatch(repo, probe, grant.grantSeq);
+        if (mismatch)
+            lines.push(`  ${mismatch}`);
+        else if (probe?.state === 'enforced')
+            enforced += 1;
+        else
+            unread.push(repo.nameWithOwner);
+    }
+    const head = `Enforcement: ${enforced}/${server.length} server-enforced repo(s) protected by GitHub` +
+        `${unread.length > 0 ? `; could not check ${shortList(unread)}` : ''}${lines.length > 0 ? ` — ${lines.length} mismatch${lines.length === 1 ? '' : 'es'}:` : ''}`;
+    return [head, ...lines];
+}
 const SWITCHES = ['off', 'propose', 'autonomous'];
 async function cmdSwitch(to, deps) {
     if (!to || !SWITCHES.includes(to)) {
@@ -334,7 +489,7 @@ async function cmdRevoke(parsed, deps) {
 async function cmdDraft(parsed, deps) {
     const { buildStandingGrantDraft } = await import('../core/verse/authority-api.js');
     const kind = parsed.flags.has('--new') ? 'new' : parsed.flags.has('--reapprove') ? 'reapprove' : 'auto';
-    const draft = await buildStandingGrantDraft(kind);
+    const draft = await buildStandingGrantDraft(kind, Date.now(), { githubGet: ghGet(deps) });
     if (parsed.flags.has('--json')) {
         deps.out(JSON.stringify({ kind: draft.kind, digest: draft.digest, payload: draft.payload }, null, 2));
         return 0;
@@ -382,7 +537,7 @@ async function cmdGrant(parsed, deps, kind) {
     }
     else {
         const { buildStandingGrantDraft } = await import('../core/verse/authority-api.js');
-        payload = (await buildStandingGrantDraft(kind)).payload;
+        payload = (await buildStandingGrantDraft(kind, Date.now(), { githubGet: ghGet(deps) })).payload;
     }
     deps.out(kind === 'new' ? 'You are about to sign this standing grant:' : 'You are about to re-approve (continue) this standing grant:');
     for (const line of describeGrantScope(payload))
@@ -520,68 +675,266 @@ export function buildFleetRuleset(requiredChecks) {
         ],
     };
 }
-function ghJson(deps, args) {
-    const result = deps.run('gh', args);
+/** A `gh api <path>` GET through the CLI's runner (tests inject it; the Verse probe's runner is read-only). */
+function ghGet(deps) {
+    return async (path) => deps.run('gh', ['api', path]);
+}
+async function ghJson(deps, args) {
+    const result = await deps.run('gh', args);
     if (result.status !== 0)
         throw new Error(`gh ${args.slice(0, 3).join(' ')} failed: ${result.stderr.trim().slice(0, 200)}`);
     return JSON.parse(result.stdout || 'null');
 }
 /** Check-run names on the default branch head: what CI actually reports today. */
-function discoverChecks(deps, repo) {
-    const info = ghJson(deps, ['api', `repos/${repo}`]);
-    const branch = info.default_branch ?? 'main';
-    const runs = ghJson(deps, ['api', `repos/${repo}/commits/${encodeURIComponent(branch)}/check-runs?per_page=100`]);
+/**
+ * 3.13: with `verifyAppId` (the repo is in the grant, the fleet can verify it
+ * and the ashlr-fleet App's id is known) the host-verified `ashlr/verify` is
+ * always required, pinned to the App — even when the default branch has no
+ * runs at all (Actions off), which is exactly the repo it exists for. A
+ * same-named run from another App never replaces the pin.
+ */
+async function discoverChecks(deps, repo, branch, verifyAppId = null) {
+    const runs = await ghJson(deps, ['api', `repos/${repo}/commits/${encodeURIComponent(branch)}/check-runs?per_page=100`]);
     const found = [];
     for (const run of runs.check_runs ?? []) {
         if (typeof run.name !== 'string' || run.name.length === 0)
             continue;
+        if (verifyAppId !== null && run.name === ASHLR_VERIFY_CHECK)
+            continue;
         const appId = run.app?.id;
         found.push({ context: run.name, integrationId: typeof appId === 'number' && Number.isSafeInteger(appId) && appId > 0 ? appId : null });
     }
+    if (verifyAppId !== null)
+        found.push({ context: ASHLR_VERIFY_CHECK, integrationId: verifyAppId });
     return normalizeRequiredChecks(found);
 }
-async function protectPlans(parsed, deps) {
-    let repos = parsed.values.get('--repo') ?? [];
-    let enforcement = new Map();
-    if (repos.length === 0) {
-        const { readInstalledGrant } = await import('../core/authority/standing-grant.js');
-        const installed = readInstalledGrant();
-        let grantRepos = [];
-        if (installed.state === 'ok')
-            grantRepos = installed.envelope.payload.repos;
-        else {
-            const { buildStandingGrantDraft } = await import('../core/verse/authority-api.js');
-            grantRepos = (await buildStandingGrantDraft('new')).payload.repos;
+/** The check the ashlr-fleet App posts on fleet PR heads (core/fleet/verify-check-run.ts ASHLR_VERIFY_CHECK_NAME). */
+export const ASHLR_VERIFY_CHECK = 'ashlr/verify';
+/** The ashlr-fleet App as GitHub describes it to your own gh auth (a `gh api` read); null = unreadable. */
+export async function readFleetApp(deps) {
+    try {
+        const app = await ghJson(deps, ['api', `apps/${FLEET_APP_NAME}`]);
+        if (!app || typeof app.id !== 'number' || !Number.isSafeInteger(app.id) || app.id <= 0)
+            return null;
+        const slug = typeof app.slug === 'string' && /^[a-z0-9-]{1,100}$/.test(app.slug) ? app.slug : FLEET_APP_NAME;
+        const ownerLogin = typeof app.owner?.login === 'string' && /^[A-Za-z0-9-]{1,39}$/.test(app.owner.login) ? app.owner.login : '';
+        const checks = typeof app.permissions?.['checks'] === 'string' ? app.permissions['checks'] : null;
+        return { id: app.id, slug, ownerLogin, ownerIsOrg: app.owner?.type === 'Organization', checks };
+    }
+    catch {
+        return null;
+    }
+}
+/** PURE: where the App's permissions (and then each installation's acceptance) are changed. */
+export function fleetAppPermissionUrls(app) {
+    const base = app.ownerIsOrg && app.ownerLogin
+        ? `https://github.com/organizations/${app.ownerLogin}/settings`
+        : 'https://github.com/settings';
+    return { permissions: `${base}/apps/${app.slug}/permissions`, installations: `${base}/installations` };
+}
+/** True when the fleet mirror of `repo` exists and the fleet detects at least one required verify command there. */
+async function fleetCanVerify(repo) {
+    try {
+        const { mirrorPathFor } = await import('../core/fleet/mirrors.js');
+        const { detectVerifyCommands } = await import('../core/run/verify-commands.js');
+        const mirror = mirrorPathFor(repo);
+        if (!existsSync(mirror))
+            return false;
+        return detectVerifyCommands(mirror, 'merge').some((command) => command.required !== false);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * PURE: `actual` (a ruleset as GitHub returns it) already says everything
+ * `desired` says. GitHub adds ids, links, timestamps and server-side rule
+ * defaults to what it returns, so extra object keys are ignored — but every
+ * field we set must match, and arrays must match one-to-one in any order, so
+ * an extra rule, an extra bypass actor or an extra required check is drift
+ * (re-applying would remove it). Anything unreadable is "not up to date".
+ */
+export function rulesetMatches(desired, actual) {
+    if (Array.isArray(desired)) {
+        if (!Array.isArray(actual) || actual.length !== desired.length)
+            return false;
+        const unused = [...actual];
+        for (const wanted of desired) {
+            const at = unused.findIndex((candidate) => rulesetMatches(wanted, candidate));
+            if (at < 0)
+                return false;
+            unused.splice(at, 1);
+        }
+        return true;
+    }
+    if (desired !== null && typeof desired === 'object') {
+        if (actual === null || typeof actual !== 'object' || Array.isArray(actual))
+            return false;
+        const have = actual;
+        return Object.entries(desired).every(([key, value]) => rulesetMatches(value, have[key]));
+    }
+    return Object.is(desired, actual);
+}
+/**
+ * The repos the fleet works in: the installed grant's, or — before the first
+ * grant — the ones it would name (every enrolled checkout's GitHub repo plus
+ * the canary; authority-api draftRepos), whose enforcement is not known yet
+ * (null): the draft names `server` only where GitHub then enforces required
+ * checks (authority/server-enforcement.ts). Read-only: no draft is built and the ledger is not
+ * touched, so a dry run (and Verse's checklist) can ask it freely.
+ */
+async function setupTargetRepos() {
+    const { readInstalledGrant, FLEET_CANARY_REPO } = await import('../core/authority/standing-grant.js');
+    const installed = readInstalledGrant();
+    if (installed.state === 'ok') {
+        return installed.envelope.payload.repos.map((repo) => ({ nameWithOwner: repo.nameWithOwner, enforcement: repo.enforcement }));
+    }
+    const byKey = new Map();
+    try {
+        const { readEnrollmentRegistry } = await import('../core/sandbox/policy.js');
+        const { repoIdentityOfPath } = await import('../core/fleet/repo-identity.js');
+        const registry = readEnrollmentRegistry();
+        if (registry.state === 'ready') {
+            for (const path of registry.repos) {
+                const nameWithOwner = repoIdentityOfPath(path);
+                if (nameWithOwner && !byKey.has(nameWithOwner.toLowerCase()))
+                    byKey.set(nameWithOwner.toLowerCase(), { nameWithOwner, enforcement: null });
+            }
         }
-        repos = grantRepos.map((r) => r.nameWithOwner);
-        enforcement = new Map(grantRepos.map((r) => [r.nameWithOwner, r.enforcement]));
     }
+    catch {
+        // An unreadable registry leaves the canary alone on the list.
+    }
+    if (!byKey.has(FLEET_CANARY_REPO))
+        byKey.set(FLEET_CANARY_REPO, { nameWithOwner: FLEET_CANARY_REPO, enforcement: null });
+    return [...byKey.values()];
+}
+/** Read-only: what `protect --apply` would do for each repo (every gh call here is a GET). */
+async function protectPlans(parsed, deps, given) {
+    const explicit = parsed.values.get('--repo') ?? [];
+    const byGrant = given !== undefined || explicit.length === 0;
+    const targets = given
+        ?? (explicit.length > 0 ? explicit.map((nameWithOwner) => ({ nameWithOwner, enforcement: null })) : await setupTargetRepos());
+    // Repos the grant covers (installed grant, or the would-be grant's own list):
+    // only those get the fleet's ashlr/verify requirement.
+    const grantMembers = new Set();
+    const { readInstalledGrant } = await import('../core/authority/standing-grant.js');
+    const installed = readInstalledGrant();
+    if (installed.state === 'ok')
+        for (const r of installed.envelope.payload.repos)
+            grantMembers.add(r.nameWithOwner.toLowerCase());
+    if (byGrant)
+        for (const r of targets)
+            grantMembers.add(r.nameWithOwner.toLowerCase());
+    const grantEnforcement = new Map();
+    if (installed.state === 'ok')
+        for (const r of installed.envelope.payload.repos)
+            grantEnforcement.set(r.nameWithOwner.toLowerCase(), r.enforcement);
+    const grantSeq = installed.state === 'ok' ? installed.envelope.payload.grantSeq : null;
+    const { classifyGithubReadFailure, describeGithubReadFailure, enforcementMismatch } = await import('../core/authority/server-enforcement.js');
+    const unreadable = (repo, error) => {
+        const message = error.message;
+        return { repo, skipped: `could not read it from GitHub (${describeGithubReadFailure(classifyGithubReadFailure({ message }))}): ${message}`, checks: [], ruleset: null, existingId: null, upToDate: false };
+    };
+    let fleetApp;
     const plans = [];
-    for (const repo of repos) {
-        if (enforcement.get(repo) === 'local') {
-            plans.push({ repo, skipped: 'local enforcement (private free-plan repo: GitHub rulesets unavailable) — the daemon enforces its gates', checks: [], ruleset: null, existingId: null });
+    for (const { nameWithOwner: repo, enforcement } of targets) {
+        if (enforcement === 'local') {
+            plans.push({ repo, skipped: `local enforcement in the grant — GitHub protects nothing here; the daemon enforces its gates and G7 requires the App's host-verified ${ASHLR_VERIFY_CHECK}`, checks: [], ruleset: null, existingId: null, upToDate: false });
+            continue;
+        }
+        let info;
+        try {
+            info = await ghJson(deps, ['api', `repos/${repo}`]);
+        }
+        catch (error) {
+            plans.push(unreadable(repo, error));
+            continue;
+        }
+        // Rulesets before anything else: on GitHub Free a PRIVATE repo has neither
+        // rulesets nor classic branch protection (both answer 403 "Upgrade to
+        // GitHub Pro or make this repository public…", verified live), which is a
+        // plan limit — not a permission problem and not a network error — so it is
+        // reported as such, and only `local` enforcement can work there.
+        const listed = await deps.run('gh', ['api', `repos/${repo}/rulesets`]);
+        if (listed.status !== 0 && classifyGithubReadFailure({ message: listed.stderr }) === 'plan-unavailable') {
+            const kind = info?.private === false ? 'repo' : 'private repo';
+            const mismatch = grantEnforcement.get(repo.toLowerCase()) === 'server'
+                ? enforcementMismatch({ nameWithOwner: repo, enforcement: 'server' }, { nameWithOwner: repo, state: 'unavailable', private: info?.private ?? null, failure: 'plan-unavailable', detail: '' }, grantSeq)
+                : null;
+            plans.push({
+                repo,
+                skipped: mismatch ?? `rulesets unavailable on this plan for ${kind} ${repo} — using local enforcement with ${ASHLR_VERIFY_CHECK}`,
+                checks: [],
+                ruleset: null,
+                existingId: null,
+                upToDate: false,
+                unavailable: true,
+                mismatch,
+            });
             continue;
         }
         try {
-            const info = ghJson(deps, ['api', `repos/${repo}`]);
-            const required = discoverChecks(deps, repo);
+            if (listed.status !== 0)
+                throw new Error(`gh api repos/${repo}/rulesets failed: ${listed.stderr.trim().slice(0, 200)}`);
+            let verifyAppId = null;
+            let verifyNote = null;
+            if (grantMembers.has(repo.toLowerCase())) {
+                if (!(await fleetCanVerify(repo))) {
+                    verifyNote = `${ASHLR_VERIFY_CHECK} not required: the fleet mirror has no verify command yet (rerun protect once it has synced)`;
+                }
+                else {
+                    if (fleetApp === undefined)
+                        fleetApp = await readFleetApp(deps);
+                    if (fleetApp)
+                        verifyAppId = fleetApp.id;
+                    else
+                        verifyNote = `${ASHLR_VERIFY_CHECK} not required: the ${FLEET_APP_NAME} App could not be read (\`gh api apps/${FLEET_APP_NAME}\`)`;
+                }
+            }
+            const required = await discoverChecks(deps, repo, info?.default_branch ?? 'main', verifyAppId);
             const checks = required.map((check) => check.context);
-            const existing = ghJson(deps, ['api', `repos/${repo}/rulesets`]);
+            const existing = JSON.parse(listed.stdout || 'null');
             const match = Array.isArray(existing) ? existing.find((r) => r.name === FLEET_RULESET_NAME) : undefined;
+            const existingId = typeof match?.id === 'number' && Number.isSafeInteger(match.id) ? match.id : null;
+            const ruleset = buildFleetRuleset(required);
+            // Rerun-safe: a ruleset already on GitHub with this exact content is
+            // reported as in place instead of being PUT again.
+            const upToDate = existingId !== null && rulesetMatches(ruleset, await ghJson(deps, ['api', `repos/${repo}/rulesets/${existingId}`]));
             plans.push({
                 repo,
-                skipped: info.private === true && checks.length === 0 ? 'private repo with no CI checks — protect it by hand or keep it propose-only' : null,
+                skipped: info?.private === true && checks.length === 0 ? 'private repo with no CI checks — protect it by hand or keep it propose-only' : null,
                 checks,
-                ruleset: buildFleetRuleset(required),
-                existingId: typeof match?.id === 'number' ? match.id : null,
+                ruleset,
+                existingId,
+                upToDate,
+                verifyNote,
             });
         }
         catch (error) {
-            plans.push({ repo, skipped: `could not read it from GitHub: ${error.message}`, checks: [], ruleset: null, existingId: null });
+            plans.push(unreadable(repo, error));
         }
     }
     return plans;
 }
+/** Create or update each plan's ruleset; the number that failed. */
+async function applyProtectPlans(plans, deps) {
+    let failures = 0;
+    for (const plan of plans) {
+        const result = await deps.run('gh', [
+            'api', '--method', plan.existingId === null ? 'POST' : 'PUT',
+            `repos/${plan.repo}/rulesets${plan.existingId === null ? '' : `/${plan.existingId}`}`,
+            '--input', '-',
+        ], { input: JSON.stringify(plan.ruleset) });
+        if (result.status === 0)
+            deps.out(`${plan.repo}: ruleset ${plan.existingId === null ? 'created' : 'updated'}.`);
+        else {
+            failures += 1;
+            deps.err(`${plan.repo}: failed — ${result.stderr.trim().slice(0, 300)}`);
+        }
+    }
+    return failures;
+}
 async function cmdProtect(parsed, deps) {
     const apply = parsed.flags.has('--apply');
     if (!apply && !parsed.flags.has('--print')) {
@@ -594,7 +947,17 @@ async function cmdProtect(parsed, deps) {
             deps.out(`${plan.repo}: skipped — ${plan.skipped}`);
             continue;
         }
-        deps.out(`${plan.repo}: ${plan.existingId === null ? 'create' : `update ruleset ${plan.existingId}`}; required checks: ${plan.checks.length > 0 ? plan.checks.join(', ') : 'none found (the repo goes to the owner lane until it has CI)'}`);
+        const checks = plan.checks.length > 0 ? plan.checks.join(', ') : 'none found (the repo goes to the owner lane until it has CI)';
+        if (plan.upToDate) {
+            deps.out(`${plan.repo}: ruleset ${plan.existingId} already up to date; required checks: ${checks}`);
+            continue;
+        }
+        deps.out(`${plan.repo}: ${plan.existingId === null ? 'create' : `update ruleset ${plan.existingId}`}; required checks: ${checks}`);
+        if (plan.verifyNote)
+            deps.out(`  note: ${plan.verifyNote}`);
+        else if (plan.checks.includes(ASHLR_VERIFY_CHECK)) {
+            deps.out(`  note: ${ASHLR_VERIFY_CHECK} is posted only on fleet PRs; your own PRs need the admin bypass unless another required check covers them`);
+        }
         if (!apply) {
             deps.out(`  gh api --method ${plan.existingId === null ? 'POST' : 'PUT'} repos/${plan.repo}/rulesets${plan.existingId === null ? '' : `/${plan.existingId}`} --input - <<'JSON'`);
             deps.out(JSON.stringify(plan.ruleset, null, 2));
@@ -603,37 +966,27 @@ async function cmdProtect(parsed, deps) {
     }
     if (!apply)
         return 0;
-    const actionable = plans.filter((plan) => !plan.skipped);
+    const actionable = plans.filter((plan) => !plan.skipped && !plan.upToDate);
     if (actionable.length === 0)
         return 0;
     if (!parsed.flags.has('--yes') && !(await deps.confirm(`Apply the ruleset to ${actionable.length} repo(s)?`))) {
         deps.out('Nothing applied.');
         return 1;
     }
-    let failures = 0;
-    for (const plan of actionable) {
-        const result = deps.run('gh', [
-            'api', '--method', plan.existingId === null ? 'POST' : 'PUT',
-            `repos/${plan.repo}/rulesets${plan.existingId === null ? '' : `/${plan.existingId}`}`,
-            '--input', '-',
-        ], { input: JSON.stringify(plan.ruleset) });
-        if (result.status === 0)
-            deps.out(`${plan.repo}: ruleset ${plan.existingId === null ? 'created' : 'updated'}.`);
-        else {
-            failures += 1;
-            deps.err(`${plan.repo}: failed — ${result.stderr.trim().slice(0, 300)}`);
-        }
-    }
-    return failures === 0 ? 0 : 1;
+    return (await applyProtectPlans(actionable, deps)) === 0 ? 0 : 1;
 }
 // ---------------------------------------------------------------------------
 // github-app — App Manifest flow (addendum §3)
 // ---------------------------------------------------------------------------
 export const FLEET_APP_NAME = 'ashlr-fleet';
 /**
- * PURE: the App manifest. Contents + pull requests read/write, checks /
- * statuses / metadata read. No workflows, no administration — GitHub itself
- * then refuses CI-config and protection changes from the fleet.
+ * PURE: the App manifest. Contents + pull requests read/write, checks
+ * read/write (3.13: the App posts the host-verified `ashlr/verify` check run
+ * on fleet PR heads — core/fleet/verify-check-run.ts), statuses / metadata
+ * read. No workflows, no administration — GitHub itself then refuses
+ * CI-config and protection changes from the fleet. An App created before 3.13
+ * has `checks: read`; `ashlr authority setup` detects that and prints where
+ * to raise it (fleetAppPermissionUrls).
  */
 export function buildGithubAppManifest(redirectUrl) {
     return {
@@ -642,7 +995,7 @@ export function buildGithubAppManifest(redirectUrl) {
         hook_attributes: { url: 'https://github.com/ashlrai/ashlr-hub', active: false },
         redirect_url: redirectUrl,
         public: false,
-        default_permissions: { contents: 'write', pull_requests: 'write', checks: 'read', statuses: 'read', metadata: 'read' },
+        default_permissions: { contents: 'write', pull_requests: 'write', checks: 'write', statuses: 'read', metadata: 'read' },
         default_events: [],
     };
 }
@@ -729,26 +1082,165 @@ async function cmdGithubApp(parsed, deps) {
     const result = await runGithubAppFlow(deps, { org });
     deps.out(`Created ${result.slug} (App id ${result.appId}); its private key is in custody and was never written to disk.`);
     deps.out(`Install it on the enrolled repos: ${result.installUrl}`);
+    deps.out(`It can post the host-verified ${ASHLR_VERIFY_CHECK} check (checks: write). An ${FLEET_APP_NAME} App created before 3.13 cannot: \`ashlr authority setup\` prints the exact settings link to raise it.`);
     return 0;
 }
-// ---------------------------------------------------------------------------
-// rotate-provenance
-// ---------------------------------------------------------------------------
+/** Where Mason installs the App (and picks its repos). */
+export const FLEET_APP_INSTALL_URL = `https://github.com/apps/${FLEET_APP_NAME}/installations/new`;
+/** Bounded wait: a probe that does not answer in time is "unknown", never a hang. */
+async function withTimeout(work, ms, what) {
+    let timer;
+    try {
+        return await Promise.race([
+            work,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`${what} did not answer within ${Math.round(ms / 1000)} s`)), ms);
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+const APP_PROBE_TIMEOUT_MS = 20_000;
+/**
+ * Where the ashlr-fleet App is installed — read-only, in two passes:
+ *
+ *  1. per owner, `gh api orgs/<owner>/installations` with Mason's own gh auth
+ *     (a GET; needs admin:org). An installation on "All repositories" settles
+ *     every repo of that owner; no installation at all settles them as missing.
+ *  2. what that cannot settle (a user account, "Only select repositories", a
+ *     gh token without admin:org) is asked of the App itself: custody's
+ *     gh-token looks the repo up AS the App (GET /repos/<r>/installation under
+ *     the App's JWT), and a 404 there means "not installed". The one-hour token
+ *     the helper mints on success stays in this process's memory, is never
+ *     printed, and changes nothing on GitHub.
+ */
+export async function probeAppInstallation(deps, repos) {
+    const result = { installed: [], missing: [], unknown: [] };
+    const byOwner = new Map();
+    for (const repo of repos) {
+        const owner = repo.split('/')[0];
+        byOwner.set(owner, [...(byOwner.get(owner) ?? []), repo]);
+    }
+    const unsettled = [];
+    for (const [owner, ownerRepos] of byOwner) {
+        let listed = null;
+        try {
+            const read = await ghJson(deps, ['api', `orgs/${owner}/installations?per_page=100`]);
+            if (read && Array.isArray(read.installations))
+                listed = read.installations;
+        }
+        catch {
+            listed = null;
+        }
+        const app = listed?.find((entry) => entry.app_slug === FLEET_APP_NAME);
+        if (listed && !app)
+            result.missing.push(...ownerRepos);
+        else if (app?.repository_selection === 'all')
+            result.installed.push(...ownerRepos);
+        else
+            unsettled.push(...ownerRepos);
+    }
+    // A few at a time: each lookup is two HTTPS calls inside the helper.
+    const queue = [...unsettled];
+    const worker = async () => {
+        for (let repo = queue.shift(); repo !== undefined; repo = queue.shift()) {
+            try {
+                await withTimeout(deps.custody.githubToken(repo), APP_PROBE_TIMEOUT_MS, 'ashlr-custody gh-token');
+                result.installed.push(repo);
+            }
+            catch (error) {
+                const code = error.code;
+                const message = error.message ?? String(error);
+                if (code === 'github' && /not installed/u.test(message))
+                    result.missing.push(repo);
+                else
+                    result.unknown.push({ repo, reason: message.slice(0, 160) });
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(4, queue.length) }, worker));
+    // Stable order for the checklist line, whatever order the lookups finished in.
+    const order = new Map(repos.map((repo, i) => [repo, i]));
+    const byInput = (a, b) => (order.get(a) ?? 0) - (order.get(b) ?? 0);
+    result.installed.sort(byInput);
+    result.missing.sort(byInput);
+    result.unknown.sort((a, b) => byInput(a.repo, b.repo));
+    return result;
+}
+/** "a, b and 3 more" — a list short enough for one checklist line. */
+function shortList(items, max = 3) {
+    if (items.length <= max)
+        return items.join(', ');
+    return `${items.slice(0, max).join(', ')} and ${items.length - max} more`;
+}
+function provenanceRotationRecordPath(keyPath) {
+    return `${keyPath}.rotation.json`;
+}
+function sha256Hex(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+function readRotationRecord(keyPath) {
+    try {
+        const raw = JSON.parse(readFileSync(provenanceRotationRecordPath(keyPath), 'utf8'));
+        if (raw.v !== 1 || typeof raw.rotatedAt !== 'string' || typeof raw.keySha256 !== 'string' || !/^[a-f0-9]{64}$/u.test(raw.keySha256))
+            return null;
+        return { v: 1, rotatedAt: raw.rotatedAt, keySha256: raw.keySha256 };
+    }
+    catch {
+        return null;
+    }
+}
+/** Read-only: never creates, repairs or moves the key. */
+export async function provenanceKeyState() {
+    const { provenanceKeyPath, loadExistingProvenanceKeyReadOnly } = await import('../core/foundry/provenance.js');
+    let path;
+    let key;
+    try {
+        path = provenanceKeyPath();
+        key = loadExistingProvenanceKeyReadOnly();
+    }
+    catch (error) {
+        return { state: 'unhealthy', reason: error.message.replace(homedir(), '~') };
+    }
+    if (!key)
+        return { state: 'missing' };
+    const record = readRotationRecord(path);
+    // The record names the exact key it made: a key swapped in afterwards is not "already rotated".
+    if (record && record.keySha256 === sha256Hex(key))
+        return { state: 'rotated', rotatedAt: record.rotatedAt };
+    return { state: 'unrotated' };
+}
 /**
  * Move the provenance HMAC key aside and create a new one. Every pending
  * provenance signature stops verifying (by design: agents could read the old
  * key while confinement was off), so pending proposals are re-verified.
+ * Records which key it made (provenanceKeyState reads it) so setup can tell
+ * a key it already rotated from the burned one.
  */
 export async function rotateProvenanceKey() {
-    const { provenanceKeyPath, loadOrCreateKey } = await import('../core/foundry/provenance.js');
+    const { provenanceKeyPath, loadOrCreateKey, loadExistingProvenanceKeyReadOnly } = await import('../core/foundry/provenance.js');
     const path = provenanceKeyPath();
     let retiredAs = null;
     if (existsSync(path)) {
         retiredAs = `${path}.retired-${new Date().toISOString().replace(/[:.]/g, '-')}`;
         renameSync(path, retiredAs);
     }
-    loadOrCreateKey();
-    return { retiredAs };
+    const created = loadOrCreateKey();
+    // loadOrCreateKey falls back to a process-lifetime key when it cannot write
+    // one; that is not a rotation — say so instead of recording it.
+    const stored = loadExistingProvenanceKeyReadOnly();
+    if (!stored || !stored.equals(created))
+        throw new Error('the new provenance key could not be stored in ~/.ashlr/foundry');
+    const rotatedAt = new Date().toISOString();
+    const record = { v: 1, rotatedAt, keySha256: sha256Hex(stored) };
+    const target = provenanceRotationRecordPath(path);
+    const tmp = `${target}.${process.pid}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+    renameSync(tmp, target);
+    return { retiredAs, rotatedAt };
 }
 async function cmdRotateProvenance(parsed, deps) {
     if (!parsed.flags.has('--yes') && !(await deps.confirm('Replace the provenance HMAC key? Pending proposals will need re-verification.'))) {
@@ -840,12 +1332,41 @@ const SETUP_STEP_NEEDS = Object.freeze({
     'standing-grant': ['touch-id'],
     'autonomy-switch': [],
     'daemon-service': ['terminal'],
-    'resident-runtime': [],
+    'resident-runtime': ['terminal'],
 });
-// The packaged runtime still has no resident-start broker or production
-// authority roots. This is a source/release gate, not a missing setup action.
-// Keep the checklist blocked until a reviewed resident consumer can prove it.
-const RESIDENT_RUNTIME_BLOCK = 'Resident activation is unavailable in this build: service install/restart authority, compiled daemon and conductor roots, and the native resident-start broker are absent. Preparing the other steps does not start autonomous work.';
+/** The one command that walks every step and resumes where the last run stopped. */
+export const AUTHORITY_SETUP_COMMAND = 'ashlr authority setup';
+/** The only command that installs or restarts the resident service (you, at a terminal, under the grant). */
+const RESIDENT_START_COMMAND = 'ashlr authority resident start';
+/**
+ * The command that moves each step on while it is not in place. Setup is
+ * rerun-safe, so for everything it performs itself the answer is setup; the
+ * rest is what only Mason runs (sudo, the build, the grant, resident start).
+ * A row may name its own (the resident step names what its admission asks
+ * for, or none when a prerequisite outside this Mac's commands is missing).
+ */
+const SETUP_STEP_COMMAND = Object.freeze({
+    'custody-helper': 'sudo scripts/install-custody.sh',
+    'host-binding': 'sudo scripts/install-custody.sh',
+    'signing-key': AUTHORITY_SETUP_COMMAND,
+    'trust-root': AUTHORITY_SETUP_COMMAND,
+    deploy: 'npm run build',
+    'github-app': AUTHORITY_SETUP_COMMAND,
+    'claude-token': AUTHORITY_SETUP_COMMAND,
+    'canary-repo': AUTHORITY_SETUP_COMMAND,
+    rulesets: AUTHORITY_SETUP_COMMAND,
+    'old-activation-state': AUTHORITY_SETUP_COMMAND,
+    'provenance-key': AUTHORITY_SETUP_COMMAND,
+    'standing-grant': 'ashlr authority grant',
+    'autonomy-switch': 'ashlr authority switch autonomous',
+    'daemon-service': RESIDENT_START_COMMAND,
+    'resident-runtime': RESIDENT_START_COMMAND,
+});
+// Every exit before the grant is known to be active (the first unmet live
+// prerequisite, or a dry run past one) reports the resident step with this:
+// a resident service is admitted only under an active standing grant
+// (docs/RESIDENT-RUNTIME.md), so without one it is genuinely blocked.
+const RESIDENT_NEEDS_GRANT = 'blocked until a grant is active (`ashlr authority grant`, Touch ID); then `ashlr authority resident start` in your own terminal installs the resident daemon under it';
 function setupStepId(step) {
     return step.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
 }
@@ -854,7 +1375,17 @@ export function authoritySetupReport(report, dryRun) {
     const count = (status) => report.filter((r) => r.status === status).length;
     const steps = report.map((r) => {
         const id = setupStepId(r.step);
-        return { id, step: r.step, status: r.status, detail: r.detail, needs: SETUP_STEP_NEEDS[id] ?? [] };
+        // A step in place needs nothing; one that is not names what moves it on.
+        const open = r.status !== 'done' && r.status !== 'already';
+        return {
+            id,
+            step: r.step,
+            status: r.status,
+            detail: r.detail,
+            needs: SETUP_STEP_NEEDS[id] ?? [],
+            command: open ? (r.command !== undefined ? r.command : SETUP_STEP_COMMAND[id] ?? null) : null,
+            link: open ? r.link ?? null : null,
+        };
     });
     const open = steps.find((s) => s.status !== 'done' && s.status !== 'already');
     return {
@@ -868,7 +1399,6 @@ export function authoritySetupReport(report, dryRun) {
 }
 async function cmdSetup(parsed, deps) {
     const dryRun = parsed.flags.has('--dry-run');
-    const yes = parsed.flags.has('--yes');
     const json = parsed.flags.has('--json');
     if (json && !dryRun) {
         // A real run asks questions and prints what gh / signing did; only the
@@ -876,24 +1406,119 @@ async function cmdSetup(parsed, deps) {
         deps.err('setup --json needs --dry-run');
         return 2;
     }
+    const report = await runSetup(parsed, deps, { dryRun, yes: parsed.flags.has('--yes'), print: !json });
+    return finish(report, deps, dryRun, json);
+}
+// ---------------------------------------------------------------------------
+// The read-only checklist (Verse: GET /api/verse/authority/setup)
+// ---------------------------------------------------------------------------
+/** Per `gh api` GET in the read-only probe. */
+const READ_ONLY_GH_TIMEOUT_MS = 10_000;
+/** All `gh api` reads of one read-only probe together. */
+const READ_ONLY_PROBE_BUDGET_MS = 30_000;
+const GH_API_PATH_RE = /^[A-Za-z0-9][A-Za-z0-9._~/?=&%-]{0,400}$/u;
+/**
+ * The read-only probe's runner: `gh api <path>` — a GET, since no field,
+ * method or input flag is ever passed — run asynchronously (the Verse server
+ * must not block its event loop) and killed after READ_ONLY_GH_TIMEOUT_MS.
+ * Anything else (git, `gh pr`, `gh repo create`, `--method`) is refused
+ * without running, so a dry-run path that ever grew a write could not reach it.
+ */
+/** PURE: `gh api <path>` with nothing else — the only call the read-only probe runs. */
+export function isReadOnlyGhApiCall(bin, args) {
+    return bin === 'gh' && args.length === 2 && args[0] === 'api' && GH_API_PATH_RE.test(args[1] ?? '');
+}
+export function readOnlyGhRun(bin, args) {
+    if (!isReadOnlyGhApiCall(bin, args)) {
+        return Promise.resolve({ status: 1, stdout: '', stderr: 'refused: the read-only setup probe only runs `gh api <path>` reads' });
+    }
+    return new Promise((done) => {
+        execFile('gh', ['api', args[1]], {
+            encoding: 'utf8',
+            timeout: READ_ONLY_GH_TIMEOUT_MS,
+            maxBuffer: 8 * 1024 * 1024,
+            env: { ...process.env, GH_PROMPT_DISABLED: '1', GH_NO_UPDATE_NOTIFIER: '1' },
+        }, (error, stdout, stderr) => {
+            const code = error?.code;
+            done({
+                status: error ? (typeof code === 'number' ? code : 1) : 0,
+                stdout: stdout ?? '',
+                stderr: stderr || (error ? error.message : ''),
+            });
+        });
+    });
+}
+function refusedInProbe(what) {
+    throw new Error(`${what} is not available to the read-only setup probe`);
+}
+/**
+ * `ashlr authority setup --dry-run --json` as a function: the same planning
+ * path (cmdSetup's steps with --dry-run), with dependencies that cannot ask,
+ * prompt, open a browser, reach the network directly or run anything but a
+ * bounded `gh api` GET. Custody is only asked read-only questions (status,
+ * host binding, public key, and whether the App can see a repo).
+ */
+export async function planAuthoritySetup(injected) {
+    // The whole probe gets READ_ONLY_PROBE_BUDGET_MS of gh time: past it, a read
+    // is answered "not read" at once (the step then says what it could not
+    // check) instead of queueing more ten-second waits behind a slow network.
+    const deadline = Date.now() + READ_ONLY_PROBE_BUDGET_MS;
+    const budgeted = (bin, args) => (Date.now() > deadline
+        ? Promise.resolve({ status: 1, stdout: '', stderr: 'not read: the setup probe ran out of time' })
+        : readOnlyGhRun(bin, args));
+    const deps = {
+        out: () => undefined,
+        err: () => undefined,
+        confirm: async () => false,
+        readSecret: async () => refusedInProbe('a secret prompt'),
+        run: budgeted,
+        openBrowser: () => refusedInProbe('a browser'),
+        fetch: (async () => refusedInProbe('the network')),
+        custody: injected?.custody ?? await import('../core/authority/custody-client.js'),
+        daemonService: () => realDaemonService(true),
+        // The resident step only reads (admission verdict, service + plist
+        // observation); the effects are refused here, never reached by setup.
+        resident: {
+            admission: realResidentDeps.admission,
+            observe: realResidentDeps.observe,
+            operatorRefusal: async () => 'the read-only setup probe is not the operator at a terminal',
+            start: async () => refusedInProbe('resident start'),
+            stop: async () => refusedInProbe('resident stop'),
+        },
+        ...(injected ?? {}),
+    };
+    const parsed = { positional: ['setup'], flags: new Set(['--dry-run', '--json']), values: new Map() };
+    return authoritySetupReport(await runSetup(parsed, deps, { dryRun: true, yes: false, print: false }), true);
+}
+/**
+ * Every step of setup, in order. RERUN-SAFE: Mason runs it several times, so
+ * each step first checks whether it is already in place and says so
+ * ('already') instead of doing it again — the provenance key is rotated once,
+ * a ruleset GitHub already holds is not PUT again, the App counts only when it
+ * is installed, an open trust-root PR is found rather than reopened. A step
+ * that throws is recorded as failed and the run still ends with its summary.
+ */
+async function runSetup(parsed, deps, opts) {
+    const { dryRun, yes } = opts;
     const report = [];
-    const note = (step, status, detail) => {
-        report.push({ step, status, detail });
-        if (json)
+    const note = (step, status, detail, extra = {}) => {
+        report.push({ step, status, detail, ...extra });
+        if (!opts.print)
             return;
         // 'skipped' gets its own glyph: a ✓ on a step a dry run did not perform read as done.
         const glyph = status === 'failed' ? '✗' : status === 'blocked' ? '×' : status === 'waiting-on-you' ? '…' : status === 'skipped' ? '·' : '✓';
         deps.out(`${glyph} ${step}: ${detail}`);
     };
     const done = () => {
-        // Every exit, including the first unmet live prerequisite, must report
-        // this independent source/release block exactly once.
+        // Every exit, including the first unmet live prerequisite, reports the
+        // resident step exactly once — it is never silently complete.
         if (!report.some((row) => row.step === 'resident runtime')) {
-            note('resident runtime', 'blocked', RESIDENT_RUNTIME_BLOCK);
+            note('resident runtime', 'blocked', RESIDENT_NEEDS_GRANT, { command: 'ashlr authority grant' });
         }
-        return finish(report, deps, dryRun, json);
+        return report;
     };
     const ask = async (question) => !dryRun && (yes || deps.confirm(question));
+    const failure = (error) => (error?.message ?? String(error)).replace(homedir(), '~').slice(0, 300);
     // --dry-run PLANS: the CHANGELOG and docs/AUTHORITY.md promise it "prints
     // every step first" (3.10 review c20). A real run must stop at an unmet
     // prerequisite; a dry run notes it and keeps describing the remaining
@@ -907,256 +1532,561 @@ async function cmdSetup(parsed, deps) {
         planning = true;
         return false;
     };
-    // 1. Custody helper (installing it needs sudo — Mason runs that himself).
-    let custody = null;
+    // Which step is running: an exception nobody anticipated becomes its
+    // failure (with the summary still printed), never a bare abort.
+    let current = 'custody helper';
     try {
-        custody = await deps.custody.custodyStatus();
-    }
-    catch (error) {
-        note('custody helper', 'failed', `status unavailable (${error.message})`);
-    }
-    if (!custody || !custody.installed) {
-        note('custody helper', 'waiting-on-you', 'run `sudo scripts/install-custody.sh` from the ashlr-hub checkout, then run setup again');
-        if (stopHere())
-            return done();
-    }
-    else {
-        note('custody helper', 'already', `installed${custody.version ? ` (${custody.version})` : ''}`);
-    }
-    // 1b. The helper and this CLI must agree on which Mac this is: the helper
-    // derives StandingGrantV1.hostBinding as sha256(uppercase IOPlatformUUID)
-    // and so does surface.ts. A disagreement would make every grant fail
-    // "signed for a different Mac" only AFTER Mason's Touch ID — catch it first.
-    if (planning) {
-        note('host binding', 'skipped', 'would check that ashlr-custody and this release agree on which Mac this is');
-    }
-    else {
+        // 1. Custody helper (installing it needs sudo — Mason runs that himself).
+        let custody = null;
         try {
-            const { currentHostBinding } = await import('../core/authority/surface.js');
-            const ours = currentHostBinding();
-            const helpers = await deps.custody.custodyHostBinding();
-            if (ours === null)
-                note('host binding', 'failed', "this Mac's IOPlatformUUID could not be read, so no grant can be bound to it");
-            else if (ours !== helpers)
-                note('host binding', 'failed', 'ashlr-custody and this release disagree on the host binding — reinstall the helper from this checkout');
-            else
-                note('host binding', 'already', `this Mac is ${ours.slice(0, 12)}…`);
+            custody = await deps.custody.custodyStatus();
         }
         catch (error) {
-            note('host binding', 'failed', `could not compare with ashlr-custody (${error.message})`);
-        }
-    }
-    if (report.some((r) => r.step === 'host binding' && r.status === 'failed') && stopHere())
-        return done();
-    // 2. Secure Enclave key (Touch ID). The helper is not on PATH, so every
-    // message names it by its installed path.
-    let keyId = custody?.keyId ?? null;
-    let publicKeyPem = null;
-    if (planning || !custody) {
-        note('signing key', 'skipped', 'would create the Secure Enclave signing key (Touch ID) unless it already exists');
-    }
-    else if (!custody.keyInitialized) {
-        if (!(await ask('Create the Secure Enclave signing key now (Touch ID)?'))) {
-            note('signing key', dryRun ? 'skipped' : 'waiting-on-you', dryRun
-                ? `would create it (Touch ID) — or run \`${CUSTODY_HELPER_PATH} init\``
-                : `create it with \`${CUSTODY_HELPER_PATH} init\` or rerun setup`);
+            note('custody helper', 'failed', `status unavailable (${failure(error)})`);
+        }
+        if (!custody || !custody.installed) {
+            note('custody helper', 'waiting-on-you', 'run `sudo scripts/install-custody.sh` from the ashlr-hub checkout, then run setup again');
             if (stopHere())
                 return done();
         }
         else {
-            const info = await deps.custody.custodyInit();
-            keyId = info.keyId;
-            publicKeyPem = info.publicKeyPem;
-            note('signing key', 'done', `created ${info.keyId}`);
+            note('custody helper', 'already', `installed${custody.version ? ` (${custody.version})` : ''}`);
         }
-    }
-    else {
-        note('signing key', 'already', `key ${keyId ?? '(id unknown)'}`);
-    }
-    // 3. Trust root compiled in (Mason's own PR).
-    const { STANDING_GRANT_TRUST_ROOTS } = await import('../core/authority/trust-roots.js');
-    // A key made on an earlier run whose id status did not report: read its
-    // public half back (`ashlr-custody pubkey`, no Touch ID) instead of asking
-    // Mason to copy it by hand.
-    const isTrusted = (id) => id !== null && STANDING_GRANT_TRUST_ROOTS.some((root) => root.keyId === id);
-    // No kickstart here: a daemon that is disabled or not loaded (the usual
-    // state before the first grant) has nothing to kickstart, and the last step
-    // (daemon service) says how to start it once the grant is in force.
-    const DEPLOY_DETAIL = 'after you merge that PR: `npm run build`, install the release as you normally do (docs/RELEASING-LOCALLY.md), then rerun setup (restart a running daemon with `launchctl kickstart -k gui/$(id -u)/ai.ashlr.daemon`)';
-    if (planning) {
-        note('trust root', 'skipped', 'would check that your signing key is compiled into this release, and if not open a PR adding it to trust-roots.ts for you to review and merge');
-        note('deploy', 'skipped', `would wait for you: ${DEPLOY_DETAIL}`);
-    }
-    else {
-        let trustRootFailed = false;
-        if (!isTrusted(keyId) && !publicKeyPem) {
+        // 1b. The helper and this CLI must agree on which Mac this is: the helper
+        // derives StandingGrantV1.hostBinding as sha256(uppercase IOPlatformUUID)
+        // and so does surface.ts. A disagreement would make every grant fail
+        // "signed for a different Mac" only AFTER Mason's Touch ID — catch it first.
+        current = 'host binding';
+        if (planning) {
+            note('host binding', 'skipped', 'would check that ashlr-custody and this release agree on which Mac this is');
+        }
+        else {
             try {
-                const info = await deps.custody.custodyPublicKey();
-                keyId = info.keyId;
-                publicKeyPem = info.publicKeyPem;
+                const { currentHostBinding } = await import('../core/authority/surface.js');
+                const ours = currentHostBinding();
+                const helpers = await deps.custody.custodyHostBinding();
+                if (ours === null)
+                    note('host binding', 'failed', "this Mac's IOPlatformUUID could not be read, so no grant can be bound to it");
+                else if (ours !== helpers)
+                    note('host binding', 'failed', 'ashlr-custody and this release disagree on the host binding — reinstall the helper from this checkout');
+                else
+                    note('host binding', 'already', `this Mac is ${ours.slice(0, 12)}…`);
             }
             catch (error) {
-                note('trust root', 'failed', `could not read the custody public key (${error.message})`);
-                trustRootFailed = true;
+                note('host binding', 'failed', `could not compare with ashlr-custody (${failure(error)})`);
             }
         }
-        if (trustRootFailed) {
-            if (stopHere())
-                return done();
+        if (report.some((r) => r.step === 'host binding' && r.status === 'failed') && stopHere())
+            return done();
+        // 2. Secure Enclave key (Touch ID). The helper is not on PATH, so every
+        // message names it by its installed path.
+        current = 'signing key';
+        let keyId = custody?.keyId ?? null;
+        let publicKeyPem = null;
+        if (planning || !custody) {
+            note('signing key', 'skipped', 'would create the Secure Enclave signing key (Touch ID) unless it already exists');
+        }
+        else if (!custody.keyInitialized) {
+            if (!(await ask('Create the Secure Enclave signing key now (Touch ID)?'))) {
+                note('signing key', dryRun ? 'skipped' : 'waiting-on-you', dryRun
+                    ? `would create it (Touch ID) — or run \`${CUSTODY_HELPER_PATH} init\``
+                    : `create it with \`${CUSTODY_HELPER_PATH} init\` or rerun setup`);
+                if (stopHere())
+                    return done();
+            }
+            else {
+                try {
+                    const info = await deps.custody.custodyInit();
+                    keyId = info.keyId;
+                    publicKeyPem = info.publicKeyPem;
+                    note('signing key', 'done', `created ${info.keyId}`);
+                }
+                catch (error) {
+                    note('signing key', 'failed', `not created (${failure(error)}) — rerun setup, or run \`${CUSTODY_HELPER_PATH} init\``);
+                    if (stopHere())
+                        return done();
+                }
+            }
+        }
+        else {
+            note('signing key', 'already', `key ${keyId ?? '(id unknown)'}`);
         }
-        else if (isTrusted(keyId)) {
-            note('trust root', 'already', `${keyId} is compiled into this release`);
-            note('deploy', 'already', 'this release carries your trust root');
+        // 3. Trust root compiled in (Mason's own PR).
+        current = 'trust root';
+        const { STANDING_GRANT_TRUST_ROOTS } = await import('../core/authority/trust-roots.js');
+        // A key made on an earlier run whose id status did not report: read its
+        // public half back (`ashlr-custody pubkey`, no Touch ID) instead of asking
+        // Mason to copy it by hand.
+        const isTrusted = (id) => id !== null && STANDING_GRANT_TRUST_ROOTS.some((root) => root.keyId === id);
+        // No kickstart here: a daemon that is disabled or not loaded (the usual
+        // state before the first grant) has nothing to kickstart, and the last step
+        // (daemon service) says how to start it once the grant is in force.
+        const DEPLOY_DETAIL = 'after you merge that PR: `npm run build`, install the release as you normally do (docs/RELEASING-LOCALLY.md), then rerun setup (restart a running daemon with `launchctl kickstart -k gui/$(id -u)/ai.ashlr.daemon`)';
+        if (planning) {
+            note('trust root', 'skipped', 'would check that your signing key is compiled into this release, and if not open a PR adding it to trust-roots.ts for you to review and merge');
+            note('deploy', 'skipped', `would wait for you: ${DEPLOY_DETAIL}`);
         }
         else {
-            const root = { keyId: keyId, alg: 'ES256', publicKeyPem: publicKeyPem };
-            const invalid = validateCustodyRoot(root, deps.custody.keyIdForPublicKeyPem);
-            if (invalid) {
-                note('trust root', 'failed', invalid);
+            let trustRootFailed = false;
+            if (!isTrusted(keyId) && !publicKeyPem) {
+                try {
+                    const info = await deps.custody.custodyPublicKey();
+                    keyId = info.keyId;
+                    publicKeyPem = info.publicKeyPem;
+                }
+                catch (error) {
+                    note('trust root', 'failed', `could not read the custody public key (${failure(error)})`);
+                    trustRootFailed = true;
+                }
+            }
+            if (trustRootFailed) {
+                if (stopHere())
+                    return done();
+            }
+            else if (isTrusted(keyId)) {
+                note('trust root', 'already', `${keyId} is compiled into this release`);
+                note('deploy', 'already', 'this release carries your trust root');
             }
             else {
-                let pr;
+                const root = { keyId: keyId, alg: 'ES256', publicKeyPem: publicKeyPem };
+                const invalid = validateCustodyRoot(root, deps.custody.keyIdForPublicKeyPem);
+                if (invalid) {
+                    note('trust root', 'failed', invalid);
+                }
+                else {
+                    let pr;
+                    try {
+                        // A dry run looks too, through `gh api` reads only (the
+                        // Verse checklist is this path): an open PR, a merged key or a
+                        // pushed branch is reported instead of "add this root yourself".
+                        pr = (dryRun ? await probeTrustRootReadOnly(deps, root) : null) ?? await openTrustRootPr(parsed, deps, root, ask, !dryRun);
+                    }
+                    catch (error) {
+                        pr = { status: 'failed', detail: failure(error) };
+                    }
+                    note('trust root', pr.status, pr.detail, {
+                        ...(pr.link ? { link: pr.link } : {}),
+                        ...(pr.command !== undefined ? { command: pr.command } : {}),
+                    });
+                    note('deploy', 'waiting-on-you', DEPLOY_DETAIL);
+                }
+                if (stopHere())
+                    return done();
+            }
+        }
+        // The canary's existence decides whether the App and ruleset checks
+        // include it yet (setup creates it at step 6). One read-only GET.
+        const canaryRepo = 'ashlrai/fleet-canary';
+        let canaryExists = planning ? false : (await deps.run('gh', ['api', `repos/${canaryRepo}`])).status === 0;
+        // 4. GitHub App: its key in custody is half of it — it also has to be
+        // INSTALLED on the repos the fleet works in, or every mint fails.
+        current = 'GitHub App';
+        if (!custody?.githubApp) {
+            if (await ask(`Create the ${FLEET_APP_NAME} GitHub App now (one browser page)?`)) {
                 try {
-                    pr = await openTrustRootPr(parsed, deps, root, ask, !dryRun);
+                    const app = await runGithubAppFlow(deps, { org: one(parsed, '--org') ?? 'ashlrai' });
+                    // A new App is installed nowhere yet.
+                    note('GitHub App', 'waiting-on-you', `created ${app.slug} (its key is in custody); now install it on the enrolled repos: ${app.installUrl} — then rerun setup`, { link: app.installUrl });
                 }
                 catch (error) {
-                    pr = { status: 'failed', detail: error.message };
+                    note('GitHub App', 'failed', `not created (${failure(error)}) — rerun setup, or run \`ashlr authority github-app\``);
                 }
-                note('trust root', pr.status, pr.detail);
-                note('deploy', 'waiting-on-you', DEPLOY_DETAIL);
             }
-            if (stopHere())
-                return done();
+            else
+                note('GitHub App', dryRun ? 'skipped' : 'waiting-on-you', 'run `ashlr authority github-app`');
+        }
+        else if (planning) {
+            note('GitHub App', 'skipped', `the ${FLEET_APP_NAME} key is in custody; would check the App is installed on the enrolled repos`);
+        }
+        else {
+            const targets = (await setupTargetRepos()).map((repo) => repo.nameWithOwner)
+                .filter((repo) => canaryExists || repo.toLowerCase() !== canaryRepo);
+            const probe = await probeAppInstallation(deps, targets);
+            const later = canaryExists ? '' : ` (${canaryRepo} needs it too once it exists)`;
+            if (probe.missing.length > 0) {
+                note('GitHub App', 'waiting-on-you', `the ${FLEET_APP_NAME} key is in custody, but the App is not installed on ${shortList(probe.missing)} — install it: ${FLEET_APP_INSTALL_URL}, then rerun setup${later}`, { link: FLEET_APP_INSTALL_URL });
+            }
+            else if (probe.unknown.length > 0) {
+                note('GitHub App', 'waiting-on-you', `the ${FLEET_APP_NAME} key is in custody, but its installation on ${shortList(probe.unknown.map((u) => u.repo))} could not be confirmed (${probe.unknown[0].reason}) — check ${FLEET_APP_INSTALL_URL}, then rerun setup`, { link: FLEET_APP_INSTALL_URL });
+            }
+            else {
+                const where = probe.installed.length === 0 ? 'no enrolled repo needs it yet' : probe.installed.length === 1 ? `installed on ${probe.installed[0]}` : `installed on all ${probe.installed.length} enrolled repos`;
+                // 3.13: it must also be able to post ashlr/verify (checks: write); an
+                // App created before 3.13 has checks: read and must be raised by hand.
+                const app = await readFleetApp(deps);
+                if (app && app.checks !== 'write') {
+                    const urls = fleetAppPermissionUrls(app);
+                    note('GitHub App', 'waiting-on-you', `the ${FLEET_APP_NAME} key is in custody and the App is ${where}, but it cannot post the ${ASHLR_VERIFY_CHECK} check (Checks: ${app.checks ?? 'no access'}): `
+                        + `set "Checks: Read and write" at ${urls.permissions}, accept the new permission on each installation at ${urls.installations}, then rerun setup`, { link: urls.permissions });
+                }
+                else {
+                    note('GitHub App', 'already', app
+                        ? `the ${FLEET_APP_NAME} key is in custody; ${where}${later}; the App can post ${ASHLR_VERIFY_CHECK} (checks: write)`
+                        : `the ${FLEET_APP_NAME} key is in custody; ${where}${later} (its checks permission was not read; it needs "Checks: Read and write" for ${ASHLR_VERIFY_CHECK})`);
+                }
+            }
+        }
+        // 5. Claude token for restricted judge / Leader calls.
+        current = 'Claude token';
+        if (custody?.claudeToken)
+            note('Claude token', 'already', 'stored in custody');
+        else if (await ask('Store a Claude token now (run `claude setup-token` in another terminal and paste it)?')) {
+            try {
+                const token = (await deps.readSecret('Paste the token (hidden): ')).trim();
+                if (!token)
+                    note('Claude token', 'failed', 'nothing was pasted');
+                else {
+                    await deps.custody.storeClaudeToken(token);
+                    note('Claude token', 'done', 'stored in custody (never written to disk here)');
+                }
+            }
+            catch (error) {
+                note('Claude token', 'failed', `not stored (${failure(error)}) — run \`claude setup-token\`, then rerun setup`);
+            }
+        }
+        else
+            note('Claude token', dryRun ? 'skipped' : 'waiting-on-you', 'run `claude setup-token`, then rerun setup');
+        // 6. Canary repo (the App cannot write workflows, so this uses your own gh
+        // auth). Before the rulesets: the grant's server-enforced repos include the
+        // canary, and a ruleset cannot be applied to a repo that does not exist yet.
+        current = 'canary repo';
+        if (canaryExists)
+            note('canary repo', 'already', `${canaryRepo} exists`);
+        else if (await ask(`Create the public repo ${canaryRepo} with its CI workflow (your gh auth)?`)) {
+            const created = await deps.run('gh', ['repo', 'create', canaryRepo, '--public', '--add-readme', '--description', 'ashlr fleet canary (revert drills)']);
+            const workflow = created.status === 0
+                ? await deps.run('gh', ['api', '--method', 'PUT', `repos/${canaryRepo}/contents/.github/workflows/ci.yml`, '--input', '-'], {
+                    input: JSON.stringify({ message: 'ci: canary workflow', content: Buffer.from(CANARY_WORKFLOW, 'utf8').toString('base64') }),
+                })
+                : null;
+            canaryExists = created.status === 0;
+            note('canary repo', created.status === 0 && workflow?.status === 0 ? 'done' : 'failed', created.status === 0 ? (workflow?.status === 0 ? 'created with its CI workflow' : 'created, but the workflow push failed') : created.stderr.trim().slice(0, 200));
+        }
+        else
+            note('canary repo', dryRun ? 'skipped' : 'waiting-on-you', `create ${canaryRepo} with a CI workflow`);
+        // 7. Rulesets — only where GitHub does not already hold exactly this one.
+        current = 'rulesets';
+        if (planning) {
+            note('rulesets', 'skipped', 'would check the fleet ruleset on the server-enforced repos and apply it where it is missing or different');
+        }
+        else {
+            const targets = (await setupTargetRepos()).filter((repo) => canaryExists || repo.nameWithOwner.toLowerCase() !== canaryRepo);
+            const plans = await protectPlans(parsed, deps, targets);
+            const stale = plans.filter((plan) => !plan.skipped && !plan.upToDate);
+            const inPlace = plans.filter((plan) => !plan.skipped && plan.upToDate).length;
+            const unreadable = plans.filter((plan) => plan.skipped?.startsWith('could not read')).map((plan) => plan.repo);
+            const unavailable = plans.filter((plan) => plan.unavailable === true);
+            const mismatches = unavailable.map((plan) => plan.mismatch).filter((m) => typeof m === 'string');
+            const byHand = plans.filter((plan) => plan.skipped && !plan.unavailable && !plan.skipped.startsWith('could not read')).length;
+            const unread = unreadable.length > 0 ? `; could not read ${shortList(unreadable)} from GitHub` : '';
+            // A plan limit is not a read failure: say which repos only local enforcement can protect.
+            const noRulesets = unavailable.length > 0
+                ? `; rulesets unavailable on this plan for private ${shortList(unavailable.map((plan) => plan.repo))} — ${mismatches.length > 0 ? mismatches.join('; ') : `using local enforcement with ${ASHLR_VERIFY_CHECK}`}`
+                : '';
+            const left = `${byHand > 0 ? `; ${byHand} left to you (local enforcement or no CI)` : ''}${noRulesets}`;
+            const inPlaceText = inPlace > 0 ? `the fleet ruleset is in place on ${inPlace === 1 ? '1 repo' : `${inPlace} repos`}` : 'no repo has the fleet ruleset';
+            if (plans.length === 0) {
+                // Nothing to look at yet — never "in place on 0 repos".
+                if (canaryExists)
+                    note('rulesets', 'already', 'no server-enforced repo needs one');
+                else
+                    note('rulesets', dryRun ? 'skipped' : 'waiting-on-you', `${canaryRepo} gets the fleet ruleset once it exists`);
+            }
+            else if (stale.length > 0) {
+                const where = shortList(stale.map((plan) => plan.repo));
+                if (await ask(`Apply the fleet ruleset to ${stale.length} repo(s) where it is missing or different (${where})?`)) {
+                    const failures = await applyProtectPlans(stale, deps);
+                    note('rulesets', failures > 0 ? 'failed' : unreadable.length > 0 || mismatches.length > 0 ? 'waiting-on-you' : 'done', failures === 0
+                        ? `applied to ${where}${inPlace > 0 ? `; ${inPlace} already in place` : ''}${unread}${left}`
+                        : `${failures} of ${stale.length} failed (see above)${unread}${noRulesets}`);
+                }
+                else {
+                    note('rulesets', dryRun ? 'skipped' : 'waiting-on-you', `${stale.length} repo(s) need the fleet ruleset (${where})${unread}${noRulesets} — run \`ashlr authority protect --print\`, then \`--apply\``);
+                }
+            }
+            else if (unreadable.length > 0) {
+                note('rulesets', 'waiting-on-you', `could not read ${shortList(unreadable)} from GitHub — check \`gh auth status\`, then rerun setup${inPlace > 0 ? ` (${inPlace} already in place)` : ''}${noRulesets}`);
+            }
+            else if (mismatches.length > 0) {
+                // The signed grant is never rewritten here: only a re-approval (Touch ID) switches the repo.
+                note('rulesets', 'waiting-on-you', `${inPlaceText}${left}`, { command: 'ashlr authority re-approve' });
+            }
+            else {
+                note('rulesets', 'already', `${inPlaceText}${left}`);
+            }
+        }
+        // 8. Retire the burned activation directory.
+        current = 'old activation state';
+        const activation = join(homedir(), '.ashlr', 'activation');
+        if (!existsSync(activation))
+            note('old activation state', 'already', 'nothing to retire');
+        else if (await ask('Move ~/.ashlr/activation (the burned key) out of ~/.ashlr so no code path can reach it?')) {
+            try {
+                const target = join(homedir(), `ashlr-activation-retired-${new Date().toISOString().replace(/[:.]/g, '-')}`);
+                renameSync(activation, target);
+                note('old activation state', 'done', `moved to ${target.replace(homedir(), '~')} — move it offline, then delete it`);
+            }
+            catch (error) {
+                note('old activation state', 'failed', `not moved (${failure(error)})`);
+            }
+        }
+        else
+            note('old activation state', dryRun ? 'skipped' : 'waiting-on-you', 'archive ~/.ashlr/activation offline, then delete it');
+        // 9. Provenance key — rotated ONCE. The burned key is whichever one no
+        // rotation recorded; a key a rotation made (and recorded) is left alone,
+        // because rotating again would invalidate every pending proposal for nothing.
+        current = 'provenance key';
+        const provenance = await provenanceKeyState();
+        if (provenance.state === 'rotated') {
+            note('provenance key', 'already', `rotated ${provenance.rotatedAt.slice(0, 10)}; not rotated again, so pending proposals keep verifying`);
+        }
+        else if (await ask(provenance.state === 'missing'
+            ? 'Create the provenance HMAC key now?'
+            : 'Rotate the provenance HMAC key (agents could read the old one)?')) {
+            try {
+                const rotated = await rotateProvenanceKey();
+                note('provenance key', 'done', rotated.retiredAs ? 'rotated; the old key was moved aside' : 'created');
+            }
+            catch (error) {
+                note('provenance key', 'failed', `not rotated (${failure(error)})`);
+            }
         }
-    }
-    // 4. GitHub App.
-    if (custody?.githubApp)
-        note('GitHub App', 'already', 'the ashlr-fleet key is in custody');
-    else if (await ask(`Create the ${FLEET_APP_NAME} GitHub App now (one browser page)?`)) {
-        const app = await runGithubAppFlow(deps, { org: one(parsed, '--org') ?? 'ashlrai' });
-        note('GitHub App', 'done', `created ${app.slug}; install it on the repos: ${app.installUrl}`);
-    }
-    else
-        note('GitHub App', dryRun ? 'skipped' : 'waiting-on-you', 'run `ashlr authority github-app`');
-    // 5. Claude token for restricted judge / Leader calls.
-    if (custody?.claudeToken)
-        note('Claude token', 'already', 'stored in custody');
-    else if (await ask('Store a Claude token now (run `claude setup-token` in another terminal and paste it)?')) {
-        const token = (await deps.readSecret('Paste the token (hidden): ')).trim();
-        if (!token)
-            note('Claude token', 'failed', 'nothing was pasted');
         else {
-            await deps.custody.storeClaudeToken(token);
-            note('Claude token', 'done', 'stored in custody (never written to disk here)');
+            const why = provenance.state === 'unhealthy' ? `the current key is unusable (${provenance.reason}); ` : '';
+            note('provenance key', dryRun ? 'skipped' : 'waiting-on-you', `${why}run \`ashlr authority rotate-provenance\``);
+        }
+        // 10. First grant (Touch ID), 11. the switch, 12. the daemon service,
+        // 13. resident admission (docs/RESIDENT-RUNTIME.md). Setup itself never
+        // touches launchd: it names the one command that does.
+        const DAEMON_DETAIL = 'would check that the ai.ashlr.daemon service is loaded and running (each tick re-verifies the grant)';
+        if (planning) {
+            note('standing grant', 'skipped', 'would sign the first standing grant (Touch ID)');
+            note('autonomy switch', 'skipped', 'would offer to set the autonomy switch to Autonomous (the ladder starts in shadow)');
+            note('daemon service', 'skipped', DAEMON_DETAIL);
+            return done();
+        }
+        current = 'standing grant';
+        const { evaluateStandingAuthority, displaySurfaceTarget } = await import('../core/authority/effective-config.js');
+        const evaluation = evaluateStandingAuthority({ mode: 'cached', surface: displaySurfaceTarget() });
+        let grantActive = evaluation.grantState === 'active';
+        if (grantActive) {
+            note('standing grant', 'already', `grant #${evaluation.grant?.grantSeq ?? '?'} is active`);
+        }
+        else if (await ask('Sign the first standing grant now (Touch ID)?')) {
+            try {
+                const { buildStandingGrantDraft } = await import('../core/verse/authority-api.js');
+                const draft = await buildStandingGrantDraft('auto', Date.now(), { githubGet: ghGet(deps) });
+                for (const line of draft.summary)
+                    deps.out(`    ${line}`);
+                const signed = await signAndInstall(draft.payload, deps);
+                grantActive = signed.ok;
+                note('standing grant', signed.ok ? 'done' : 'failed', signed.ok ? `grant #${signed.grant.grantSeq} installed, starting at ${signed.grant.rollout.stages[0].id}` : signed.reason);
+            }
+            catch (error) {
+                note('standing grant', 'failed', `no grant was drafted (${failure(error)}) — rerun setup, or run \`ashlr authority grant\``);
+            }
+        }
+        else
+            note('standing grant', dryRun ? 'skipped' : 'waiting-on-you', 'run `ashlr authority grant`');
+        // Resumable: a grant signed on an earlier run (or with `authority grant`)
+        // still gets the switch offered — it used to be offered only in the run
+        // that signed. Raising stays capped by the grant (requestAutonomySwitch).
+        current = 'autonomy switch';
+        if (!grantActive) {
+            note('autonomy switch', dryRun ? 'skipped' : 'waiting-on-you', 'needs an active standing grant first');
+        }
+        else if (evaluation.switch === 'autonomous') {
+            note('autonomy switch', 'already', 'Autonomous');
+        }
+        else if (await ask('Set the autonomy switch to Autonomous (the ladder starts in shadow)?')) {
+            const { requestAutonomySwitch } = await import('../core/authority/effective-config.js');
+            const switched = requestAutonomySwitch('autonomous', 'mason', 'ashlr authority setup');
+            note('autonomy switch', switched.ok ? 'done' : 'failed', switched.ok ? 'Autonomous' : switched.reason);
+        }
+        else
+            note('autonomy switch', dryRun ? 'skipped' : 'waiting-on-you', `it is ${evaluation.switch} — run \`ashlr authority switch autonomous\``);
+        // 12. Read-only service observation. Only `resident start` (Mason, in his
+        // own terminal, under the active grant) installs or restarts the service.
+        current = 'daemon service';
+        let service;
+        try {
+            service = await deps.daemonService();
+        }
+        catch {
+            service = 'unknown';
+        }
+        const START = `\`${RESIDENT_START_COMMAND}\``;
+        const after = grantActive ? `run ${START}` : `after the standing grant, run ${START}`;
+        // Before the grant, the command that moves this step on is the grant.
+        const serviceCommand = grantActive ? {} : { command: 'ashlr authority grant' };
+        if (service === 'running')
+            note('daemon service', 'already', 'ai.ashlr.daemon is running (each tick re-verifies the grant)');
+        else if (service === 'absent')
+            note('daemon service', 'waiting-on-you', `no ai.ashlr.daemon service is installed — ${after} to install it`, serviceCommand);
+        else if (service === 'loaded')
+            note('daemon service', 'waiting-on-you', `ai.ashlr.daemon is loaded but stopped — ${after} to restart it`, serviceCommand);
+        else if (service === 'not-loaded')
+            note('daemon service', 'waiting-on-you', `ai.ashlr.daemon is not loaded — ${after} to load it`, serviceCommand);
+        else
+            note('daemon service', 'waiting-on-you', `ai.ashlr.daemon state is unknown — \`ashlr authority resident status\` shows why; ${after} to repair it`, serviceCommand);
+        // 13. Resident admission: the grant, this release and the service together.
+        current = 'resident runtime';
+        if (!grantActive) {
+            note('resident runtime', 'blocked', RESIDENT_NEEDS_GRANT, { command: 'ashlr authority grant' });
+        }
+        else {
+            const resident = await residentSetupRow(deps, service);
+            note('resident runtime', resident.status, resident.detail, { command: resident.command });
         }
     }
-    else
-        note('Claude token', dryRun ? 'skipped' : 'waiting-on-you', 'run `claude setup-token`, then rerun setup');
-    // 6. Canary repo (the App cannot write workflows, so this uses your own gh
-    // auth). Before the rulesets: the grant's server-enforced repos include the
-    // canary, and a ruleset cannot be applied to a repo that does not exist yet.
-    const canary = planning ? null : deps.run('gh', ['api', 'repos/ashlrai/fleet-canary']);
-    if (canary?.status === 0)
-        note('canary repo', 'already', 'ashlrai/fleet-canary exists');
-    else if (await ask('Create the public repo ashlrai/fleet-canary with its CI workflow (your gh auth)?')) {
-        const created = deps.run('gh', ['repo', 'create', 'ashlrai/fleet-canary', '--public', '--add-readme', '--description', 'ashlr fleet canary (revert drills)']);
-        const workflow = created.status === 0
-            ? deps.run('gh', ['api', '--method', 'PUT', 'repos/ashlrai/fleet-canary/contents/.github/workflows/ci.yml', '--input', '-'], {
-                input: JSON.stringify({ message: 'ci: canary workflow', content: Buffer.from(CANARY_WORKFLOW, 'utf8').toString('base64') }),
-            })
-            : null;
-        note('canary repo', created.status === 0 && workflow?.status === 0 ? 'done' : 'failed', created.status === 0 ? (workflow?.status === 0 ? 'created with its CI workflow' : 'created, but the workflow push failed') : created.stderr.trim().slice(0, 200));
+    catch (error) {
+        // Nothing above is expected to throw; if something does, it is this
+        // step's failure and the run still ends with the summary.
+        note(report.some((row) => row.step === current) ? 'setup' : current, 'failed', `stopped: ${failure(error)}`);
     }
-    else
-        note('canary repo', dryRun ? 'skipped' : 'waiting-on-you', 'create ashlrai/fleet-canary with a CI workflow');
-    // 7. Rulesets.
-    if (await ask('Apply the fleet rulesets to the server-enforced repos now?')) {
-        const code = await cmdProtect({ ...parsed, flags: new Set([...parsed.flags, '--apply', '--yes']) }, deps);
-        note('rulesets', code === 0 ? 'done' : 'failed', code === 0 ? 'applied (see above)' : 'some repos failed (see above)');
+    return done();
+}
+/**
+ * Setup's resident step (docs/RESIDENT-RUNTIME.md §d):
+ *   already        admitted AND ai.ashlr.daemon running AND its plist is what
+ *                  `resident start` would write from config now;
+ *   waiting-on-you the exact command that gets there (start / clear-stop / switch);
+ *   blocked        a prerequisite is missing (no active grant, not a compiled
+ *                  release, dirty build, no confinement, not macOS).
+ * Read-only: never mints, never touches launchd.
+ */
+async function residentSetupRow(deps, service) {
+    let admission;
+    try {
+        admission = await deps.resident.admission();
     }
-    else
-        note('rulesets', dryRun ? 'skipped' : 'waiting-on-you', 'run `ashlr authority protect --print`, then `--apply`');
-    // 8. Retire the burned activation directory.
-    const activation = join(homedir(), '.ashlr', 'activation');
-    if (!existsSync(activation))
-        note('old activation state', 'already', 'nothing to retire');
-    else if (await ask('Move ~/.ashlr/activation (the burned key) out of ~/.ashlr so no code path can reach it?')) {
-        const target = join(homedir(), `ashlr-activation-retired-${new Date().toISOString().replace(/[:.]/g, '-')}`);
-        renameSync(activation, target);
-        note('old activation state', 'done', `moved to ${target.replace(homedir(), '~')} — move it offline, then delete it`);
+    catch (error) {
+        return { status: 'failed', detail: `resident admission could not be evaluated (${error.message})` };
     }
-    else
-        note('old activation state', dryRun ? 'skipped' : 'waiting-on-you', 'archive ~/.ashlr/activation offline, then delete it');
-    // 9. Provenance key.
-    if (await ask('Rotate the provenance HMAC key (agents could read the old one)?')) {
-        const rotated = await rotateProvenanceKey();
-        note('provenance key', 'done', rotated.retiredAs ? 'rotated; the old key was moved aside' : 'created');
+    if (!admission.ok) {
+        const fix = admission.command ? ` — run \`${admission.command}\`` : '';
+        // The checklist's command is exactly what the admission asks for (none when it names none).
+        return { status: admission.status === 'waiting-on-you' ? 'waiting-on-you' : 'blocked', detail: `${admission.reason}${fix}`, command: admission.command ?? null };
     }
-    else
-        note('provenance key', dryRun ? 'skipped' : 'waiting-on-you', 'run `ashlr authority rotate-provenance`');
-    // 10. First grant (Touch ID), 11. the switch, 12. the daemon service,
-    // 13. production resident admission. A running legacy service is not proof
-    // that its execution gate or native release boundary is available.
-    const DAEMON_DETAIL = 'would check that the ai.ashlr.daemon service is loaded and running (each tick re-verifies the grant)';
-    if (planning) {
-        note('standing grant', 'skipped', 'would sign the first standing grant (Touch ID)');
-        note('autonomy switch', 'skipped', 'would offer to set the autonomy switch to Autonomous (the ladder starts in shadow)');
-        note('daemon service', 'skipped', DAEMON_DETAIL);
-        return done();
-    }
-    const { evaluateStandingAuthority, displaySurfaceTarget } = await import('../core/authority/effective-config.js');
-    const evaluation = evaluateStandingAuthority({ mode: 'cached', surface: displaySurfaceTarget() });
-    let grantActive = evaluation.grantState === 'active';
-    if (grantActive) {
-        note('standing grant', 'already', `grant #${evaluation.grant?.grantSeq ?? '?'} is active`);
-    }
-    else if (await ask('Sign the first standing grant now (Touch ID)?')) {
-        const { buildStandingGrantDraft } = await import('../core/verse/authority-api.js');
-        const draft = await buildStandingGrantDraft('auto');
-        for (const line of draft.summary)
-            deps.out(`    ${line}`);
-        const signed = await signAndInstall(draft.payload, deps);
-        grantActive = signed.ok;
-        note('standing grant', signed.ok ? 'done' : 'failed', signed.ok ? `grant #${signed.grant.grantSeq} installed, starting at ${signed.grant.rollout.stages[0].id}` : signed.reason);
+    let observed;
+    try {
+        observed = await deps.resident.observe();
     }
-    else
-        note('standing grant', dryRun ? 'skipped' : 'waiting-on-you', 'run `ashlr authority grant`');
-    // Resumable: a grant signed on an earlier run (or with `authority grant`)
-    // still gets the switch offered — it used to be offered only in the run
-    // that signed. Raising stays capped by the grant (requestAutonomySwitch).
-    if (!grantActive) {
-        note('autonomy switch', dryRun ? 'skipped' : 'waiting-on-you', 'needs an active standing grant first');
+    catch (error) {
+        return { status: 'failed', detail: `the resident service could not be observed (${error.message})` };
     }
-    else if (evaluation.switch === 'autonomous') {
-        note('autonomy switch', 'already', 'Autonomous');
+    if (observed.problem)
+        return { status: 'blocked', detail: observed.problem, command: null };
+    const start = '`ashlr authority resident start`';
+    if (service !== 'running') {
+        return { status: 'waiting-on-you', detail: `admitted under grant #${admission.grantSeq ?? '?'} but the resident daemon is not running — run ${start} in your own terminal` };
     }
-    else if (await ask('Set the autonomy switch to Autonomous (the ladder starts in shadow)?')) {
-        const { requestAutonomySwitch } = await import('../core/authority/effective-config.js');
-        const switched = requestAutonomySwitch('autonomous', 'mason', 'ashlr authority setup');
-        note('autonomy switch', switched.ok ? 'done' : 'failed', switched.ok ? 'Autonomous' : switched.reason);
+    if (observed.plist === 'drifted') {
+        const budget = observed.installedBudgetUsd !== observed.expectedBudgetUsd
+            ? ` (installed budget $${observed.installedBudgetUsd ?? '?'}/day, config says $${observed.expectedBudgetUsd ?? '?'}/day)`
+            : '';
+        return { status: 'waiting-on-you', detail: `the running service's plist differs from config${budget} — run ${start} to regenerate and restart it` };
     }
-    else
-        note('autonomy switch', dryRun ? 'skipped' : 'waiting-on-you', `it is ${evaluation.switch} — run \`ashlr authority switch autonomous\``);
-    // 12. Read-only service observation. Manual launchctl advice would imply
-    // that this build can admit a resident start, which its production gate denies.
-    let service;
-    try {
-        service = await deps.daemonService();
+    if (observed.plist !== 'current') {
+        return { status: 'waiting-on-you', detail: `the running service's plist could not be matched (${observed.plist}) — run ${start} to regenerate it` };
     }
-    catch {
-        service = 'unknown';
-    }
-    if (service === 'running')
-        note('daemon service', 'already', 'ai.ashlr.daemon is running; resident execution still requires the separate runtime admission below');
-    else if (service === 'absent')
-        note('daemon service', 'waiting-on-you', 'no ai.ashlr.daemon service is installed; this build cannot install or start one');
-    else if (service === 'loaded')
-        note('daemon service', 'waiting-on-you', 'ai.ashlr.daemon is loaded but stopped; this build cannot restart it');
-    else if (service === 'not-loaded')
-        note('daemon service', 'waiting-on-you', 'ai.ashlr.daemon is not loaded; this build cannot start it');
-    else
-        note('daemon service', 'waiting-on-you', 'ai.ashlr.daemon state is unknown; this build cannot start or repair it');
-    return done();
+    return { status: 'already', detail: `the resident daemon is running under grant #${admission.grantSeq ?? '?'} (until ${admission.expiresAt ?? '?'}), from clean release ${admission.revision?.slice(0, 12) ?? '?'}` };
+}
+// ---------------------------------------------------------------------------
+// resident start | stop | status
+// ---------------------------------------------------------------------------
+function describeAdmission(admission) {
+    if (admission.ok)
+        return `admitted — ${admission.reason}`;
+    return `${admission.status} — ${admission.reason}${admission.command ? ` (run \`${admission.command}\`)` : ''}`;
+}
+async function cmdResident(sub, parsed, deps) {
+    switch (sub) {
+        case 'status':
+            return cmdResidentStatus(parsed, deps);
+        case 'start':
+            return cmdResidentStart(parsed, deps);
+        case 'stop':
+            return cmdResidentStop(deps);
+        default:
+            deps.err('Usage: ashlr authority resident <start|stop|status [--json]>');
+            return 2;
+    }
+}
+async function cmdResidentStatus(parsed, deps) {
+    const admission = await deps.resident.admission();
+    const observed = await deps.resident.observe();
+    if (parsed.flags.has('--json')) {
+        deps.out(JSON.stringify({ schema: 'ashlr.resident-status.v1', admission, service: observed }, null, 2));
+        return 0;
+    }
+    deps.out(`Resident admission: ${describeAdmission(admission)}`);
+    deps.out(`Service: ai.ashlr.daemon ${observed.state}${observed.plistPath ? ` (${observed.plistPath.replace(homedir(), '~')})` : ''}`);
+    const budget = `installed $${observed.installedBudgetUsd ?? '—'}/day, config $${observed.expectedBudgetUsd ?? '?'}/day`;
+    deps.out(`Plist: ${observed.plist}${observed.plist === 'drifted' ? ' — `ashlr authority resident start` regenerates it' : ''} (budget: ${budget})`);
+    if (observed.problem)
+        deps.out(`  ${observed.problem}`);
+    return 0;
+}
+/**
+ * `resident start` — the only command that installs or restarts the resident
+ * service. Order: refuse a non-operator context; show the verdict; stop if
+ * not admitted; no-op when already running from the current plist; show
+ * exactly what will happen and ask (no --yes: the operator confirms here);
+ * then the real start, which re-verifies everything itself (mint).
+ */
+async function cmdResidentStart(parsed, deps) {
+    if (parsed.flags.has('--yes')) {
+        deps.err('resident start takes no --yes: confirm it yourself at the prompt.');
+        return 2;
+    }
+    const refusal = await deps.resident.operatorRefusal();
+    if (refusal) {
+        deps.err(`resident start refused: ${refusal}`);
+        return 1;
+    }
+    const admission = await deps.resident.admission();
+    if (!admission.ok) {
+        deps.err(`resident start refused: ${describeAdmission(admission)}`);
+        return 1;
+    }
+    const observed = await deps.resident.observe();
+    if (observed.problem) {
+        deps.err(`resident start refused: ${observed.problem}`);
+        return 1;
+    }
+    if (observed.state === 'running' && observed.plist === 'current') {
+        deps.out(`ai.ashlr.daemon is already running under grant #${admission.grantSeq ?? '?'} from the current plist; nothing to do.`);
+        return 0;
+    }
+    const action = observed.state === 'running' ? 'regenerate the plist from config and restart' : observed.plist === 'absent' ? 'install and start' : 'regenerate, load and start';
+    deps.out(`Resident daemon under grant #${admission.grantSeq ?? '?'} (expires ${admission.expiresAt ?? '?'}):`);
+    deps.out(`  release   ${admission.revision ?? '?'} (${admission.packageRoot?.replace(homedir(), '~') ?? '?'})`);
+    deps.out(`  service   ai.ashlr.daemon → ${observed.plistPath?.replace(homedir(), '~') ?? '?'} (${observed.state}, plist ${observed.plist})`);
+    deps.out(`  budget    $${observed.expectedBudgetUsd ?? '?'}/day from config daemon.dailyBudgetUsd${observed.installedBudgetUsd !== null && observed.installedBudgetUsd !== observed.expectedBudgetUsd ? ` (installed: $${observed.installedBudgetUsd})` : ''}`);
+    deps.out('  launchd   enable + bootstrap (RunAtLoad); every tick re-verifies the grant, Stop and the switch');
+    if (!(await deps.confirm(`${action[0].toUpperCase()}${action.slice(1)} ai.ashlr.daemon now?`))) {
+        deps.out('Nothing was changed.');
+        return 1;
+    }
+    const result = await deps.resident.start();
+    if (!result.ok) {
+        deps.err(`resident start failed: ${result.reason}`);
+        return 1;
+    }
+    deps.out(`✓ ${result.detail}`);
+    deps.out('Stop anytime: `ashlr authority stop` halts agents (the service stays up, idle); `ashlr authority resident stop` removes the service.');
+    return 0;
+}
+/** Lowering: never asks, never needs the grant. */
+async function cmdResidentStop(deps) {
+    const result = await deps.resident.stop();
+    if (!result.ok) {
+        deps.err(`resident stop failed: ${result.reason}`);
+        return 1;
+    }
+    deps.out(`${result.detail}. Stop (~/.ashlr/KILL) and the grant are unchanged.`);
+    return 0;
 }
 function finish(report, deps, dryRun = false, json = false) {
     const result = authoritySetupReport(report, dryRun);
@@ -1166,10 +2096,54 @@ function finish(report, deps, dryRun = false, json = false) {
     }
     else {
         const planned = dryRun ? `, ${summary.planned} planned (dry run: nothing was asked or changed)` : '';
-        deps.out(`\nSetup: ${summary.done} done, ${summary.already} already in place, ${summary.waitingOnYou} waiting on you, ${summary.blocked} blocked by this build, ${summary.failed} failed${planned}.`);
+        deps.out(`\nSetup: ${summary.done} done, ${summary.already} already in place, ${summary.waitingOnYou} waiting on you, ${summary.blocked} blocked on a prerequisite, ${summary.failed} failed${planned}.`);
     }
     return summary.failed > 0 ? 1 : 0;
 }
+const HUB_REPO = 'ashlrai/ashlr-hub';
+/**
+ * The dry run's look at the trust-root PR, through `gh api <path>` GETs only
+ * (each passes isReadOnlyGhApiCall, so the Verse probe can run it): the PR an
+ * earlier run opened, the key already merged on the default branch, or a
+ * branch an earlier run pushed without a PR. Same order as the live run's
+ * probes. null = none of these (or GitHub could not be read): the step then
+ * reads as it always has.
+ */
+async function probeTrustRootReadOnly(deps, root) {
+    const branch = `authority/trust-root-${root.keyId}`;
+    const read = async (path) => {
+        const result = await deps.run('gh', ['api', path]);
+        if (result.status !== 0)
+            return null;
+        try {
+            return JSON.parse(result.stdout || 'null');
+        }
+        catch {
+            return null;
+        }
+    };
+    const open = await read(`repos/${HUB_REPO}/pulls?head=${HUB_REPO.split('/')[0]}%3A${encodeURIComponent(branch)}&state=open&per_page=1`);
+    const url = Array.isArray(open) ? open[0]?.html_url : undefined;
+    if (typeof url === 'string' && /^https:\/\/github\.com\/[^\s]+\/pull\/\d+$/u.test(url)) {
+        return { status: 'waiting-on-you', detail: `${url} is already open — review and merge it yourself`, link: url, command: null };
+    }
+    const repo = await read(`repos/${HUB_REPO}`);
+    const base = typeof repo?.default_branch === 'string' && /^[A-Za-z0-9._/-]{1,100}$/u.test(repo.default_branch) ? repo.default_branch : 'master';
+    const file = await read(`repos/${HUB_REPO}/contents/src/core/authority/trust-roots.ts?ref=${encodeURIComponent(base)}`);
+    if (file && file.encoding === 'base64' && typeof file.content === 'string'
+        && Buffer.from(file.content, 'base64').toString('utf8').includes(`keyId: '${root.keyId}'`)) {
+        return {
+            status: 'waiting-on-you',
+            detail: `${root.keyId} is merged on ${base}, but this release was built before it — install a release built after it`,
+            command: 'npm run build',
+        };
+    }
+    const pushed = await read(`repos/${HUB_REPO}/git/ref/heads/${branch.split('/').map(encodeURIComponent).join('/')}`);
+    if (pushed && pushed.ref === `refs/heads/${branch}`) {
+        return { status: 'waiting-on-you', detail: `${branch} was pushed by an earlier run but has no PR yet — rerun setup to open it` };
+    }
+    return null;
+}
 /**
  * Open Mason's trust-root PR from a throwaway worktree (his checkout is never
  * touched). Resumable: a rerun finds the PR it already opened, or the key
@@ -1180,73 +2154,76 @@ async function openTrustRootPr(parsed, deps, root, ask, probe) {
     if (!source)
         return { status: 'waiting-on-you', detail: 'pass --source <your ashlr-hub checkout> so setup can open the trust-root PR' };
     const branch = `authority/trust-root-${root.keyId}`;
-    const base = () => {
-        const result = deps.run('gh', ['repo', 'view', 'ashlrai/ashlr-hub', '--json', 'defaultBranchRef', '--jq', '.defaultBranchRef.name']);
+    const base = async () => {
+        const result = await deps.run('gh', ['repo', 'view', 'ashlrai/ashlr-hub', '--json', 'defaultBranchRef', '--jq', '.defaultBranchRef.name']);
         return result.status === 0 && result.stdout.trim() ? result.stdout.trim() : 'master';
     };
+    const prLink = (text) => /https:\/\/github\.com\/\S+\/pull\/\d+/u.exec(text)?.[0];
     let baseBranch = null;
     let pushedAlready = false;
     if (probe) {
         // Read-only probes (a dry run never makes them).
-        const open = deps.run('gh', ['pr', 'list', '--repo', 'ashlrai/ashlr-hub', '--head', branch, '--state', 'open', '--json', 'url', '--jq', '.[0].url // ""']);
+        const open = await deps.run('gh', ['pr', 'list', '--repo', 'ashlrai/ashlr-hub', '--head', branch, '--state', 'open', '--json', 'url', '--jq', '.[0].url // ""']);
         if (open.status === 0 && open.stdout.trim()) {
-            return { status: 'waiting-on-you', detail: `${open.stdout.trim()} is already open — review and merge it yourself` };
+            const url = open.stdout.trim();
+            return { status: 'waiting-on-you', detail: `${url} is already open — review and merge it yourself`, ...(prLink(url) ? { link: prLink(url) } : {}) };
         }
-        baseBranch = base();
-        const fetched = deps.run('git', ['-C', source, 'fetch', 'origin', baseBranch]);
+        baseBranch = await base();
+        const fetched = await deps.run('git', ['-C', source, 'fetch', 'origin', baseBranch]);
         const onBase = fetched.status === 0
-            ? deps.run('git', ['-C', source, 'show', `origin/${baseBranch}:src/core/authority/trust-roots.ts`])
+            ? await deps.run('git', ['-C', source, 'show', `origin/${baseBranch}:src/core/authority/trust-roots.ts`])
             : null;
         if (onBase?.status === 0 && onBase.stdout.includes(`keyId: '${root.keyId}'`)) {
             return { status: 'waiting-on-you', detail: `${root.keyId} is already on ${baseBranch}, but this release was built before it` };
         }
         // An earlier run pushed the branch but `gh pr create` failed: open the PR from it.
-        const remote = deps.run('git', ['-C', source, 'ls-remote', '--exit-code', '--heads', 'origin', branch]);
+        const remote = await deps.run('git', ['-C', source, 'ls-remote', '--exit-code', '--heads', 'origin', branch]);
         pushedAlready = remote.status === 0 && remote.stdout.trim() !== '';
     }
     if (!(await ask(`Open a PR in ${source.replace(homedir(), '~')} adding key ${root.keyId} to trust-roots.ts?`))) {
         return { status: 'waiting-on-you', detail: `add this root yourself: ${JSON.stringify({ keyId: root.keyId, alg: 'ES256' })}` };
     }
-    baseBranch ??= base();
-    const createPr = (cwd) => {
-        const pr = deps.run('gh', ['pr', 'create', '--repo', 'ashlrai/ashlr-hub', '--base', baseBranch, '--head', branch,
+    baseBranch ??= await base();
+    const createPr = async (cwd) => {
+        const pr = await deps.run('gh', ['pr', 'create', '--repo', 'ashlrai/ashlr-hub', '--base', baseBranch, '--head', branch,
             '--title', `authority: trust custody key ${root.keyId}`,
             '--body', `Adds the Secure Enclave custody key \`${root.keyId}\` to STANDING_GRANT_TRUST_ROOTS (opened by \`ashlr authority setup\`). Tier-1 path: review it yourself.`], cwd ? { cwd } : {});
         if (pr.status !== 0)
             return { status: 'failed', detail: `pushed ${branch}, but the PR could not be opened: ${pr.stderr.trim().slice(0, 200)}` };
-        return { status: 'waiting-on-you', detail: `opened ${pr.stdout.trim()} — review and merge it yourself` };
+        const url = pr.stdout.trim();
+        return { status: 'waiting-on-you', detail: `opened ${url} — review and merge it yourself`, ...(prLink(url) ? { link: prLink(url) } : {}) };
     };
     if (pushedAlready)
         return createPr();
     const worktree = mkdtempSync(join(tmpdir(), 'ashlr-trust-root-'));
     rmSync(worktree, { recursive: true, force: true });
-    const step = (bin, args, cwd) => {
-        const result = deps.run(bin, args, cwd ? { cwd } : {});
+    const step = async (bin, args, cwd) => {
+        const result = await deps.run(bin, args, cwd ? { cwd } : {});
         if (result.status !== 0)
             throw new Error(`${bin} ${args[0] === '-C' ? args[2] : args[0]} failed: ${result.stderr.trim().slice(0, 200)}`);
     };
     let worktreeAdded = false;
     try {
-        step('git', ['-C', source, 'fetch', 'origin', baseBranch]);
+        await step('git', ['-C', source, 'fetch', 'origin', baseBranch]);
         // -B: a local branch left by an earlier run that stopped before the PR
         // (push or `gh pr create` failed) is reset instead of blocking every rerun.
-        step('git', ['-C', source, 'worktree', 'add', '-B', branch, worktree, `origin/${baseBranch}`]);
+        await step('git', ['-C', source, 'worktree', 'add', '-B', branch, worktree, `origin/${baseBranch}`]);
         worktreeAdded = true;
         const file = join(worktree, 'src', 'core', 'authority', 'trust-roots.ts');
         const updated = renderTrustRootsWithKey(readFileSync(file, 'utf8'), root);
         if (!updated)
             return { status: 'failed', detail: `trust-roots.ts on ${baseBranch} already lists a different root — add the key by hand` };
         writeFileSync(file, updated);
-        step('git', ['add', 'src/core/authority/trust-roots.ts'], worktree);
-        step('git', ['commit', '-m', `authority: trust custody key ${root.keyId}`], worktree);
-        step('git', ['push', '-u', 'origin', branch], worktree);
-        return createPr(worktree);
+        await step('git', ['add', 'src/core/authority/trust-roots.ts'], worktree);
+        await step('git', ['commit', '-m', `authority: trust custody key ${root.keyId}`], worktree);
+        await step('git', ['push', '-u', 'origin', branch], worktree);
+        return await createPr(worktree);
     }
     finally {
-        deps.run('git', ['-C', source, 'worktree', 'remove', '--force', worktree]);
+        await deps.run('git', ['-C', source, 'worktree', 'remove', '--force', worktree]);
         // The pushed branch lives on origin; the local copy only blocks a rerun.
         if (worktreeAdded)
-            deps.run('git', ['-C', source, 'branch', '-D', branch]);
+            await deps.run('git', ['-C', source, 'branch', '-D', branch]);
     }
 }
 /** The enrolled checkout of ashlr-hub itself, if any. */