@skrr-ai/cli 0.1.119 → 0.1.120

package/dist/lib/daemon-maintenance.js

@@ -0,0 +1,1035 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.maintenanceClock = exports.maintenanceApi = exports.MAINTENANCE_MAX_TIMEOUT_MS = exports.MAINTENANCE_DEFAULT_TIMEOUT_MS = exports.MAINTENANCE_POLL_INTERVAL_MS = exports.DAEMON_MAINTENANCE_CLI_SCHEMA = void 0;
+exports.failureFromError = failureFromError;
+exports.attempt = attempt;
+exports.looksLikeRuntimeKey = looksLikeRuntimeKey;
+exports.resolveMaintenanceTarget = resolveMaintenanceTarget;
+exports.stateLine = stateLine;
+exports.waitForReady = waitForReady;
+exports.defaultIo = defaultIo;
+exports.outcomeLines = outcomeLines;
+exports.describeView = describeView;
+exports.explainLines = explainLines;
+exports.runStatus = runStatus;
+exports.runHold = runHold;
+exports.runResume = runResume;
+exports.holdersShown = holdersShown;
+exports.runAttest = runAttest;
+exports.parseTimeout = parseTimeout;
+exports.invalidFlagRun = invalidFlagRun;
+const data_provider_1 = require("@skrr-ai/data-provider");
+const format_1 = require("./format");
+const hosted_machines_1 = require("./hosted-machines");
+const machines_1 = require("./machines");
+/**
+ * daemon-maintenance.ts — the owner's pause on one of their own machines, from the
+ * terminal (`skrr daemon maintenance status | hold | resume | attest`; OSK-19107,
+ * Space OSK-S-524, plan §3.6, journey J12).
+ *
+ * ## What this file does NOT do
+ *
+ * It declares no phase, cause, refusal, control or word. All of them are owned by
+ * `@skrr-ai/data-provider` (`daemonMaintenance.ts`) and imported: the SERVER decides
+ * which phase a machine is in (`deriveMaintenanceJourney`), this file renders what
+ * the server answered. A synonym spelled here is the drift that module exists to stop.
+ *
+ * It never builds an `/api/...` URL. Every call is a `dataService` function
+ * (`listDaemonMaintenance` and its three siblings), which is how
+ * `domain-api-parity.spec.ts` sees this domain.
+ *
+ * ## The contract a script can rely on
+ *
+ * With `--json` every command writes EXACTLY ONE JSON object to stdout and nothing
+ * else (progress goes to stderr), with `schema: 1` and a `command` and an `outcome`.
+ * The exit code follows `scripts/release-status.js` and is in the document as
+ * `exit`: `DAEMON_MAINTENANCE_EXIT_CODES` — 0 ready, 1 refused, 2 still pending at
+ * the timeout, 3 unknown.
+ *
+ *  - Only `hold --wait ready` and a command that could not read the state end in 2 or 3.
+ *    `status`, a `hold` that did not wait, `resume` and `attest` end in 0 when they did
+ *    what was asked, and in 1 when the server (or this CLI, before asking) refused.
+ *  - **A timeout NEVER releases the hold**, and the document and the text both say so
+ *    (`holdInForce: true`). A script cannot mistake "timed out" for "ready", and a
+ *    person is told the one command that lets go.
+ *  - A state this CLI could not read (the network, a 5xx, a 429) is `unknown`, exit 3:
+ *    "I could not tell" is an answer, and it is never rendered as `ready` or as zero.
+ *
+ * ## Naming a machine, and why it never picks
+ *
+ * `<machine>` is a machine id, a name, or a runtimeKey. A hold addresses ONE
+ * `runtimeKey` (one daemon, so one profile), and one machine can span several, so a
+ * machine that is two daemons is ambiguous by construction. Resolution therefore
+ * REFUSES with the candidates when a reference matches zero or more than one, and
+ * the only inference it makes is the unambiguous one: no reference given and exactly
+ * one daemon that qualifies.
+ */
+/** The version of the documents `--json` prints. Bump it when a field's meaning changes. */
+exports.DAEMON_MAINTENANCE_CLI_SCHEMA = 1;
+/** How often `--wait` reads the state, and how long it waits when no timeout is given. */
+exports.MAINTENANCE_POLL_INTERVAL_MS = 5_000;
+exports.MAINTENANCE_DEFAULT_TIMEOUT_MS = 30 * 60_000;
+exports.MAINTENANCE_MAX_TIMEOUT_MS = 24 * 60 * 60_000;
+/** Progress is repeated at least this often (in polls), even when nothing changed. */
+const PROGRESS_EVERY_POLLS = 12;
+/** The server bounds `acknowledged` entries at this length; so does the CLI before it asks. */
+const MAX_ACKNOWLEDGED_LABEL = 160;
+const MAX_ACKNOWLEDGED = 20;
+const MAX_CANDIDATES_LISTED = 20;
+// ── the four calls, and the machine list ───────────────────────────────────
+/**
+ * Every call this CLI makes. A plain mutable object so a test replaces one member
+ * without touching a module: the real members are `dataService` functions and the
+ * machine list, nothing else.
+ */
+exports.maintenanceApi = {
+    listMachines: () => (0, machines_1.listMachines)(),
+    list: () => data_provider_1.dataService.listDaemonMaintenance(),
+    get: (runtimeKey) => data_provider_1.dataService.getDaemonMaintenance(runtimeKey),
+    change: (runtimeKey, body) => data_provider_1.dataService.changeDaemonMaintenance(runtimeKey, body),
+    attest: (runtimeKey, body) => data_provider_1.dataService.attestDaemonMaintenance(runtimeKey, body),
+};
+/** The clock and the sleep `--wait` uses, replaceable so a timeout takes no time to test. */
+exports.maintenanceClock = {
+    now: () => Date.now(),
+    sleep: (ms) => (0, hosted_machines_1.sleep)(ms),
+};
+function parseBody(body) {
+    if (typeof body !== 'string' || !body.trim())
+        return null;
+    try {
+        const parsed = JSON.parse(body);
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+const STATUS_CODES = {
+    400: 'invalid_request',
+    401: 'unauthorized',
+    403: 'forbidden',
+    404: 'not_found',
+};
+/**
+ * What a failed call means. Two kinds, and the difference is the whole design:
+ *
+ *  - `refused`: the server ANSWERED no (a 4xx other than 429). The answer carries a
+ *    code the vocabulary knows, or a transport word (`invalid_request`,
+ *    `unauthorized`), and a sentence. Repeating the request unchanged repeats it.
+ *  - `unknown`: there was NO answer (the network, a 5xx, a 429). Nothing is known
+ *    about the machine's state from it, so it is never reported as a refusal or as
+ *    "not held".
+ */
+function failureFromError(err) {
+    const e = (err && typeof err === 'object' ? err : {});
+    const status = typeof e.status === 'number' ? e.status : undefined;
+    if (status === undefined || status === 429 || status >= 500 || status === 408) {
+        return {
+            kind: 'unknown',
+            code: status === undefined ? 'unreachable' : `http_${status}`,
+            message: status === undefined
+                ? 'The server could not be reached, so the machine state is not known.'
+                : `The server did not answer (HTTP ${status}), so the machine state is not known.`,
+            ...(status !== undefined ? { status } : {}),
+            ...(typeof e.retryAfterMs === 'number' ? { retryAfterMs: e.retryAfterMs } : {}),
+        };
+    }
+    const body = parseBody(e.body);
+    const code = typeof body?.code === 'string' && body.code
+        ? body.code
+        : (STATUS_CODES[status] ?? `http_${status}`);
+    const fromBody = [body?.message, body?.error].find((value) => typeof value === 'string' && value.length > 0);
+    const message = status === 401
+        ? 'You are not signed in. Run `skrr login`, then try again.'
+        : fromBody || (0, data_provider_1.maintenanceRefusalMessage)(code);
+    const candidates = Array.isArray(body?.candidates)
+        ? body.candidates.filter((c) => typeof c === 'string')
+        : undefined;
+    return {
+        kind: 'refused',
+        code,
+        message,
+        status,
+        ...(typeof body?.currentGeneration === 'number'
+            ? { currentGeneration: body.currentGeneration }
+            : {}),
+        ...(candidates && candidates.length ? { candidates } : {}),
+    };
+}
+/** Run one call and turn what it throws into a value. */
+async function attempt(call) {
+    try {
+        return { ok: true, value: await call() };
+    }
+    catch (err) {
+        return { ok: false, error: failureFromError(err) };
+    }
+}
+// ── naming a machine ───────────────────────────────────────────────────────
+const RUNTIME_KEY_SHAPE = /^rk\d+:[A-Za-z0-9_.:-]+$/;
+/** A runtimeKey needs no lookup: the server decides whether it is one of ours. */
+function looksLikeRuntimeKey(ref) {
+    return RUNTIME_KEY_SHAPE.test(ref);
+}
+function afterIdentityKind(value) {
+    if (!value)
+        return undefined;
+    const separator = value.indexOf(':');
+    return separator === -1 ? undefined : value.slice(separator + 1);
+}
+function machineDisplayName(machine) {
+    return machine.preferences?.name || machine.name;
+}
+function idsOfMachine(machine) {
+    return [
+        machine.id,
+        machine.machineUuid,
+        machine.stableDaemonId,
+        machine.daemonId,
+        afterIdentityKind(machine.id),
+        afterIdentityKind(machine.machineUuid),
+        ...(machine.harnesses ?? []).map((h) => h.id),
+    ].filter((v) => typeof v === 'string' && v.length > 0);
+}
+/** Build what a reference can match: machines from the list, and holds (orphans live only there). */
+function buildPool(machines, holds) {
+    const pool = { candidates: [], unholdable: [], unlisted: 0 };
+    const byKey = new Map();
+    for (const machine of machines) {
+        const ids = idsOfMachine(machine);
+        const names = [machine.name, machine.preferences?.name]
+            .filter((v) => Boolean(v))
+            .map((v) => v.toLowerCase());
+        if (machine.lease) {
+            pool.unholdable.push({ item: { machine, code: 'managed_machine' }, ids, names });
+        }
+        else if (machine.daemons === undefined) {
+            pool.unlisted += 1;
+        }
+        else if (machine.daemons.length === 0) {
+            pool.unholdable.push({ item: { machine, code: 'no_stable_identity' }, ids, names });
+        }
+        else {
+            for (const daemon of machine.daemons) {
+                const entry = {
+                    candidate: {
+                        runtimeKey: daemon.runtimeKey,
+                        machineId: machine.id,
+                        name: machineDisplayName(machine),
+                        profile: daemon.profile,
+                        daemonId: daemon.daemonId,
+                        held: daemon.maintenance?.held === true,
+                    },
+                    ids: [...ids, daemon.daemonId, daemon.runtimeKey],
+                    names,
+                };
+                byKey.set(daemon.runtimeKey, entry);
+                pool.candidates.push(entry);
+            }
+        }
+    }
+    // The holds list is the authority on what is held (a primary read), and the only
+    // place an orphan — a hold whose machine has no row any more — can be found.
+    for (const view of holds) {
+        const live = view.hold?.lifecycle === 'held';
+        const cover = view.machine?.covers?.[0];
+        const existing = byKey.get(view.runtimeKey);
+        if (existing) {
+            if (live)
+                existing.candidate.held = true;
+            continue;
+        }
+        const entry = {
+            candidate: {
+                runtimeKey: view.runtimeKey,
+                machineId: view.machine?.id,
+                name: view.machine?.name,
+                profile: cover?.profile ?? null,
+                daemonId: cover?.daemonId,
+                held: live,
+            },
+            ids: [view.runtimeKey, view.machine?.id, cover?.daemonId].filter((v) => typeof v === 'string' && v.length > 0),
+            names: view.machine?.name ? [view.machine.name.toLowerCase()] : [],
+        };
+        byKey.set(view.runtimeKey, entry);
+        pool.candidates.push(entry);
+    }
+    return pool;
+}
+function listed(candidates) {
+    return candidates.slice(0, MAX_CANDIDATES_LISTED);
+}
+function refusal(code, extra = {}) {
+    return { code, message: (0, data_provider_1.maintenanceRefusalMessage)(code), ...extra };
+}
+/**
+ * Which daemon a reference names. Pure: the lists are passed in.
+ *
+ * A reference is matched in three tiers and the FIRST tier with any match decides:
+ * an exact id or runtimeKey, then an exact name (any case), then a unique id prefix of
+ * at least four characters. Within the tier the answer is the set of matching
+ * DAEMONS, and a set of anything but one is a refusal that lists them.
+ *
+ * `scope: 'held'` (resume, attest) considers only daemons with a live hold: naming a
+ * machine that is not held is `not_held`, not a pick of some other machine.
+ *
+ * With no reference, the one candidate that qualifies is used and anything else is a
+ * refusal listing them: `hold` with no argument on an account with a single
+ * machine is not a guess, and on an account with two it never picks.
+ */
+function resolveMaintenanceTarget(input) {
+    const ref = input.ref?.trim();
+    if (ref && looksLikeRuntimeKey(ref))
+        return { ok: true, target: { runtimeKey: ref } };
+    const pool = buildPool(input.machines ?? [], input.holds ?? []);
+    const qualifying = (c) => input.scope === 'any' || c.held === true;
+    if (!ref) {
+        const candidates = pool.candidates.map((e) => e.candidate).filter(qualifying);
+        if (candidates.length === 1)
+            return { ok: true, target: candidates[0] };
+        if (candidates.length > 1) {
+            return {
+                ok: false,
+                refusal: refusal('ambiguous', {
+                    message: `More than one daemon qualifies (${candidates.length}). Name one: a machine name, a machine id, or a runtimeKey.`,
+                    candidates: listed(candidates),
+                }),
+            };
+        }
+        return {
+            ok: false,
+            refusal: input.scope === 'held'
+                ? refusal('not_held', { message: 'No machine of yours is held.' })
+                : refusal('not_found', {
+                    message: pool.unlisted > 0
+                        ? "No daemon of yours is listed as holdable. This server does not list machines' daemons: name a runtimeKey."
+                        : 'No machine of yours can be held: every one is managed by the platform or has no stable identity.',
+                }),
+        };
+    }
+    const lower = ref.toLowerCase();
+    const tiers = [
+        (t) => t.ids.includes(ref),
+        (t) => t.names.includes(lower),
+        (t) => lower.length >= 4 && t.ids.some((id) => id.toLowerCase().startsWith(lower)),
+    ];
+    for (const matches of tiers) {
+        const hits = pool.candidates.filter((e) => matches(e));
+        const blocked = pool.unholdable.filter((e) => matches(e));
+        if (hits.length === 0 && blocked.length === 0)
+            continue;
+        const wanted = hits.map((e) => e.candidate).filter(qualifying);
+        if (wanted.length === 1)
+            return { ok: true, target: wanted[0] };
+        if (wanted.length > 1) {
+            return {
+                ok: false,
+                refusal: refusal('ambiguous', {
+                    message: `"${ref}" names ${wanted.length} daemons (a machine can run several profiles). Name one by its runtimeKey.`,
+                    candidates: listed(wanted),
+                }),
+            };
+        }
+        // Matched, but nothing of it qualifies.
+        if (hits.length > 0) {
+            return {
+                ok: false,
+                refusal: refusal('not_held', { message: `"${ref}" is not held.` }),
+            };
+        }
+        if (blocked.length === 1) {
+            return { ok: false, refusal: refusal(blocked[0].item.code) };
+        }
+        return {
+            ok: false,
+            refusal: refusal('ambiguous', {
+                message: `"${ref}" matches ${blocked.length} machines the platform manages or that have no stable identity, and none can be held.`,
+                candidates: blocked.slice(0, MAX_CANDIDATES_LISTED).map(({ item }) => ({
+                    runtimeKey: '',
+                    machineId: item.machine.id,
+                    name: machineDisplayName(item.machine),
+                })),
+            }),
+        };
+    }
+    const all = pool.candidates.map((e) => e.candidate).filter(qualifying);
+    return {
+        ok: false,
+        refusal: refusal('not_found', {
+            message: `No machine of yours matches "${ref}". ` +
+                (pool.unlisted > 0
+                    ? "This server does not list machines' daemons, so only a runtimeKey is accepted. "
+                    : '') +
+                (all.length > 0 ? 'The daemons that qualify are listed.' : 'Run `skrr machines list`.'),
+            candidates: listed(all),
+        }),
+    };
+}
+/** The word and cause a progress line shows: the vocabulary's word, and the cause code as is. */
+function stateLine(view) {
+    const { phase, cause, modifiers } = view.journey;
+    const word = data_provider_1.DAEMON_MAINTENANCE_WORDS[phase] ?? phase;
+    return [word, cause ? `(${cause})` : '', modifiers.length ? `[${modifiers.join(', ')}]` : '']
+        .filter(Boolean)
+        .join(' ');
+}
+function elapsed(ms) {
+    const total = Math.max(0, Math.round(ms / 1000));
+    const minutes = Math.floor(total / 60);
+    return minutes > 0 ? `${minutes}m${`${total % 60}`.padStart(2, '0')}s` : `${total}s`;
+}
+/**
+ * Poll the view until it says `ready`, the hold is gone, or the timeout passes.
+ *
+ * It stops waiting the moment the machine is `ready`; otherwise it keeps waiting until
+ * the timeout, because the server — not this loop — decides that `unknown` or
+ * `back_held` is final. At least one read is made even with a zero timeout. A read
+ * that cannot be answered (the network, a 5xx, a 429) is retried until the timeout and
+ * is never taken for progress, or for readiness; a read the server REFUSES (a 404, a
+ * 403) ends the wait.
+ *
+ * Reaching the timeout does nothing to the hold. This function has no way to release
+ * one: it is given a `read` and nothing else.
+ */
+async function waitForReady(io, options) {
+    const start = io.now();
+    const deadline = start + Math.max(0, options.timeoutMs);
+    let polls = 0;
+    let view = null;
+    let error = null;
+    let lastShown = '';
+    for (;;) {
+        polls += 1;
+        const read = await io.read();
+        if (read.ok) {
+            view = read.value;
+            error = null;
+            const shown = stateLine(view);
+            if (shown !== lastShown || polls % PROGRESS_EVERY_POLLS === 0) {
+                io.progress(`waiting for ready: ${shown} (${elapsed(io.now() - start)})`);
+                lastShown = shown;
+            }
+            if ((0, data_provider_1.isMaintenanceReady)(view.journey)) {
+                return { outcome: 'ready', view, error: null, polls, waitedMs: io.now() - start };
+            }
+            if (!view.hold || view.hold.lifecycle !== 'held') {
+                return { outcome: 'released', view, error: null, polls, waitedMs: io.now() - start };
+            }
+        }
+        else if (read.error.kind === 'refused') {
+            return { outcome: 'refused', view, error: read.error, polls, waitedMs: io.now() - start };
+        }
+        else {
+            error = read.error;
+            io.progress(`could not read the state (${read.error.code}); trying again`);
+            lastShown = '';
+        }
+        const remaining = deadline - io.now();
+        if (remaining <= 0)
+            break;
+        await io.sleep(Math.min(options.intervalMs, remaining));
+    }
+    return { outcome: 'timeout', view, error, polls, waitedMs: io.now() - start };
+}
+function defaultIo(progress) {
+    return {
+        api: exports.maintenanceApi,
+        now: exports.maintenanceClock.now,
+        sleep: exports.maintenanceClock.sleep,
+        progress,
+    };
+}
+function targetDocument(target) {
+    if (!target)
+        return {};
+    return {
+        machine: {
+            runtimeKey: target.runtimeKey,
+            ...(target.machineId ? { machineId: target.machineId } : {}),
+            ...(target.name ? { name: target.name } : {}),
+            ...(target.profile ? { profile: target.profile } : {}),
+        },
+    };
+}
+function viewFields(view) {
+    if (!view)
+        return {};
+    return {
+        phase: view.journey.phase,
+        word: data_provider_1.DAEMON_MAINTENANCE_WORDS[view.journey.phase] ?? view.journey.phase,
+        cause: view.journey.cause,
+        generation: view.hold?.generation ?? null,
+        view,
+    };
+}
+function candidateLine(candidate) {
+    if (typeof candidate === 'string')
+        return candidate;
+    const label = [candidate.name, candidate.profile ? `profile ${candidate.profile}` : '']
+        .filter(Boolean)
+        .join(', ');
+    return `${candidate.runtimeKey || candidate.machineId || '-'}${label ? `  (${label})` : ''}`;
+}
+/** A refusal or an unknown, as the one document and the lines a person reads. */
+function failedRun(command, failure, context = {}) {
+    const unknown = failure.kind === 'unknown';
+    const exit = unknown
+        ? data_provider_1.DAEMON_MAINTENANCE_EXIT_CODES.unknown
+        : data_provider_1.DAEMON_MAINTENANCE_EXIT_CODES.refused;
+    const stderr = [failure.message];
+    if (failure.currentGeneration !== undefined) {
+        stderr.push(`The current generation is ${failure.currentGeneration}.`);
+    }
+    if (failure.candidates?.length) {
+        stderr.push('Candidates:');
+        for (const candidate of failure.candidates)
+            stderr.push(`  ${candidateLine(candidate)}`);
+    }
+    for (const line of context.next ?? [])
+        stderr.push(line);
+    return {
+        document: {
+            schema: exports.DAEMON_MAINTENANCE_CLI_SCHEMA,
+            command,
+            outcome: unknown ? 'unknown' : 'refused',
+            exit,
+            ...targetDocument(context.target),
+            refusal: {
+                code: failure.code,
+                message: failure.message,
+                ...(failure.status !== undefined ? { status: failure.status } : {}),
+                ...(failure.currentGeneration !== undefined
+                    ? { currentGeneration: failure.currentGeneration }
+                    : {}),
+                ...(failure.candidates?.length ? { candidates: failure.candidates } : {}),
+                ...(failure.retryAfterMs !== undefined ? { retryAfterMs: failure.retryAfterMs } : {}),
+            },
+            ...viewFields(context.view),
+            ...(context.extra ?? {}),
+        },
+        exit,
+        stdout: [],
+        stderr,
+    };
+}
+const countOf = (value) => typeof value === 'number' && Number.isInteger(value) && value >= 0 ? value : null;
+/**
+ * What became of the work a released hold had parked (OSK-19623): one summary line and, where
+ * something could not restart or ran out of time, one line per cause in the CLI's own words.
+ *
+ * A count that was never measured is "not counted", never zero, and a re-drive that has not
+ * finished says so: the numbers are what it has done so far. The causes are closed classes
+ * (`DAEMON_MAINTENANCE_RESTART_REFUSAL_WORDS`), so nothing here prints a run id or a reason
+ * the server wrote.
+ */
+function outcomeLines(outcome) {
+    if (!outcome)
+        return [];
+    const parked = countOf(outcome.parkedRuns);
+    const final = outcome.counts === 'final';
+    if (parked === null) {
+        return [`  restart      ${final ? 'not counted' : 'not counted yet'}`];
+    }
+    if (parked === 0)
+        return ['  restart      nothing was parked'];
+    const parts = [];
+    const add = (count, text) => {
+        const n = countOf(count);
+        if (n !== null && n > 0)
+            parts.push(`${n} ${text}`);
+    };
+    add(outcome.redrivenRuns, 'restarted');
+    add(outcome.supersededRuns, 'replaced by a newer scheduled run');
+    add(outcome.expiredRuns, 'ran out of time');
+    add(outcome.refusedRuns, 'could not restart');
+    if (final)
+        add(outcome.stillParkedRuns, 'still waiting for the machine');
+    add(final ? outcome.leftElsewhereRuns : null, 'started or ended without this restart');
+    const lines = [
+        `  restart      ${parts.length ? parts.join(', ') : 'none restarted yet'} (of ${parked} parked)` +
+            `${final ? '' : ', still being restarted'}`,
+    ];
+    for (const cls of data_provider_1.DAEMON_MAINTENANCE_RESTART_REFUSALS) {
+        const n = countOf(outcome.refusedByReason?.[cls]);
+        if (n)
+            lines.push(`    ${n} could not restart: ${data_provider_1.DAEMON_MAINTENANCE_RESTART_REFUSAL_WORDS[cls]}`);
+    }
+    for (const cls of data_provider_1.DAEMON_MAINTENANCE_EXPIRY_CLASSES) {
+        const n = countOf(outcome.expiredByReason?.[cls]);
+        if (n)
+            lines.push(`    ${n} ran out of time: ${data_provider_1.DAEMON_MAINTENANCE_EXPIRY_WORDS[cls]}`);
+    }
+    return lines;
+}
+/** The lines `status` and the end of `hold` print for one machine. */
+function describeView(view, options = {}) {
+    const j = view.journey;
+    const lines = [];
+    const name = view.machine?.name || view.runtimeKey;
+    lines.push(`${name}${view.machine?.name ? `  ${view.runtimeKey}` : ''}`);
+    lines.push(`  state        ${stateLine(view)}`);
+    if (view.hold) {
+        const h = view.hold;
+        const who = h.heldBy ? `${h.heldBy.kind}${h.via ? ` via ${h.via}` : ''}` : '';
+        lines.push(`  hold         generation ${h.generation} ${h.lifecycle}` +
+            `${h.requestedAt ? `, since ${(0, format_1.localStamp)(h.requestedAt)} ${(0, format_1.localZone)()}` : ''}${who ? `, by ${who}` : ''}`);
+        lines.push(`  applied      ${h.fence.state === 'confirmed' ? 'on every daemon row' : 'still being applied'} ` +
+            `(${h.fence.rowsConfirmed}/${h.fence.rowsTotal})`);
+        if (h.reason)
+            lines.push(`  reason       ${h.reason}`);
+        if (h.autoResume)
+            lines.push('  auto-resume  yes, when the machine comes back on a new process');
+        if (h.lifecycle === 'released')
+            lines.push(...outcomeLines(h.outcome));
+    }
+    if (view.parked && (view.parked.total > 0 || view.parked.unreadable)) {
+        const kinds = Object.entries(view.parked.byKind)
+            .map(([kind, count]) => `${kind} ${count}`)
+            .join(', ');
+        lines.push(view.parked.unreadable
+            ? '  parked       could not be read'
+            : `  parked       ${view.parked.total}${kinds ? ` (${kinds})` : ''}`);
+    }
+    if (j.evidenceAt)
+        lines.push(`  evidence     read ${(0, format_1.localStamp)(j.evidenceAt)} ${(0, format_1.localZone)()}`);
+    lines.push(`  controls     ${j.controls.length ? j.controls.join(', ') : 'none'}`);
+    if (view.readOnly)
+        lines.push('  access       read-only (a machine shared with you)');
+    if (options.explain)
+        lines.push(...explainLines(view));
+    return lines;
+}
+function fenceWord(confirmed) {
+    if (confirmed === null)
+        return 'unknown';
+    return confirmed ? 'confirmed' : 'not confirmed';
+}
+/** `--explain`: each source the reading used, in the order it was read, and what each said. */
+function explainLines(view) {
+    const reading = view.reading;
+    if (!reading) {
+        return ['  reading      none (nothing was read, so nothing is claimed)'];
+    }
+    const lines = [
+        `  reading      ${reading.state}${reading.cause ? ` (${reading.cause})` : ''}, read ${(0, format_1.localStamp)(reading.readAt)} ${(0, format_1.localZone)()}`,
+        `  fence        ${fenceWord(reading.fence.confirmed)} ` +
+            `(${reading.fence.rowsConfirmed}/${reading.fence.rowsTotal})`,
+        '  sources      in the order they were read:',
+    ];
+    for (const step of reading.order)
+        lines.push(`    ${(0, format_1.localStamp)(step.at)}  ${step.step}`);
+    for (const source of reading.sources) {
+        lines.push(`    ${source.source}: ${source.read}${source.cause ? ` (${source.cause})` : ''}, ` +
+            `${source.total} found${source.truncated ? ' (list truncated)' : ''}`);
+        for (const holder of source.holders) {
+            lines.push(`      - ${holder.label || holder.ref || holder.kind} (${holder.class})`);
+        }
+    }
+    return lines;
+}
+// ── commands ───────────────────────────────────────────────────────────────
+async function loadLists(io, needs) {
+    const [machines, holds] = await Promise.all([
+        needs.machines ? attempt(() => io.api.listMachines()) : Promise.resolve(null),
+        needs.holds ? attempt(() => io.api.list()) : Promise.resolve(null),
+    ]);
+    if (machines && !machines.ok)
+        return { ok: false, error: machines.error };
+    if (holds && !holds.ok)
+        return { ok: false, error: holds.error };
+    return {
+        ok: true,
+        machines: machines?.ok ? machines.value : [],
+        holds: holds?.ok ? (holds.value?.holds ?? []) : [],
+    };
+}
+async function resolveTarget(io, ref, scope, needsHolds) {
+    if (ref && looksLikeRuntimeKey(ref.trim()))
+        return { ok: true, target: { runtimeKey: ref.trim() } };
+    const lists = await loadLists(io, { machines: true, holds: needsHolds });
+    if (!lists.ok)
+        return { ok: false, failure: lists.error };
+    const resolved = resolveMaintenanceTarget({
+        ref,
+        machines: lists.machines,
+        holds: lists.holds,
+        scope,
+    });
+    return resolved.ok ? resolved : { ok: false, failure: resolved.refusal };
+}
+/** `status`: every hold the owner has, or one machine's state. */
+async function runStatus(input, io) {
+    if (!input.ref?.trim()) {
+        const listed = await attempt(() => io.api.list());
+        if (!listed.ok)
+            return failedRun('status', listed.error);
+        const holds = listed.value?.holds ?? [];
+        const stdout = [];
+        if (holds.length === 0)
+            stdout.push('No machine is held.');
+        for (const view of holds) {
+            stdout.push(...describeView(view, { explain: input.explain }));
+            stdout.push('');
+        }
+        return {
+            document: {
+                schema: exports.DAEMON_MAINTENANCE_CLI_SCHEMA,
+                command: 'status',
+                outcome: 'list',
+                exit: data_provider_1.DAEMON_MAINTENANCE_EXIT_CODES.ready,
+                count: holds.length,
+                holds,
+            },
+            exit: data_provider_1.DAEMON_MAINTENANCE_EXIT_CODES.ready,
+            stdout: stdout[stdout.length - 1] === '' ? stdout.slice(0, -1) : stdout,
+            stderr: [],
+        };
+    }
+    const resolved = await resolveTarget(io, input.ref, 'any', true);
+    if (!resolved.ok)
+        return failedRun('status', resolved.failure);
+    const got = await attempt(() => io.api.get(resolved.target.runtimeKey));
+    if (!got.ok)
+        return failedRun('status', got.error, { target: resolved.target });
+    return {
+        document: {
+            schema: exports.DAEMON_MAINTENANCE_CLI_SCHEMA,
+            command: 'status',
+            outcome: 'ok',
+            exit: data_provider_1.DAEMON_MAINTENANCE_EXIT_CODES.ready,
+            ...targetDocument(resolved.target),
+            ...viewFields(got.value),
+        },
+        exit: data_provider_1.DAEMON_MAINTENANCE_EXIT_CODES.ready,
+        stdout: describeView(got.value, { explain: input.explain }),
+        stderr: [],
+    };
+}
+function normalizeSpaces(text) {
+    return text.replace(/\s+/g, ' ').trim();
+}
+/**
+ * `hold`: take the hold, and optionally wait for the machine to be ready.
+ *
+ * A hold already in force is not a refusal here: asking to hold a machine you have
+ * already held is the retry after a lost response, or the re-run after a Ctrl-C
+ * during `--wait`. The live hold is reported (`created: false`), its reason is kept
+ * and a different `--reason` is said to have been ignored, and `--wait` then waits
+ * on it.
+ */
+async function runHold(input, io) {
+    const reason = input.reason === undefined ? undefined : normalizeSpaces(input.reason);
+    if (reason !== undefined && reason.length > data_provider_1.DAEMON_MAINTENANCE_REASON_MAX_LENGTH) {
+        return failedRun('hold', {
+            kind: 'refused',
+            code: 'invalid_request',
+            message: `--reason is ${reason.length} characters; the most it can be is ${data_provider_1.DAEMON_MAINTENANCE_REASON_MAX_LENGTH}.`,
+        });
+    }
+    const resolved = await resolveTarget(io, input.ref, 'any', false);
+    if (!resolved.ok)
+        return failedRun('hold', resolved.failure);
+    const target = resolved.target;
+    const body = {
+        lifecycle: 'held',
+        ...(reason ? { reason } : {}),
+        ...(input.autoResume ? { autoResume: true } : {}),
+    };
+    const put = await attempt(() => io.api.change(target.runtimeKey, body));
+    let view;
+    let created = true;
+    let reasonIgnored = false;
+    if (put.ok) {
+        view = put.value;
+    }
+    else if (put.error.code === 'already_held') {
+        const got = await attempt(() => io.api.get(target.runtimeKey));
+        if (!got.ok)
+            return failedRun('hold', got.error, { target });
+        view = got.value;
+        created = false;
+        reasonIgnored = Boolean(reason) && normalizeSpaces(view.hold?.reason ?? '') !== reason;
+        io.progress(`Already held (generation ${view.hold?.generation ?? put.error.currentGeneration}); ` +
+            'the existing hold is kept.');
+        if (reasonIgnored)
+            io.progress('The reason you gave was not applied: the existing hold keeps its own.');
+    }
+    else {
+        return failedRun('hold', put.error, { target });
+    }
+    if (!view.hold || view.hold.lifecycle !== 'held') {
+        return failedRun('hold', {
+            kind: 'unknown',
+            code: 'unexpected_answer',
+            message: 'The server answered without a hold in force, so the machine state is not known.',
+        }, { target, view });
+    }
+    const common = {
+        schema: exports.DAEMON_MAINTENANCE_CLI_SCHEMA,
+        command: 'hold',
+        ...targetDocument(target),
+        created,
+        ...(reasonIgnored ? { reasonIgnored: true } : {}),
+        holdInForce: true,
+    };
+    if (!input.wait) {
+        return {
+            document: {
+                ...common,
+                outcome: 'held',
+                exit: data_provider_1.DAEMON_MAINTENANCE_EXIT_CODES.ready,
+                wait: { requested: false },
+                ...viewFields(view),
+                note: 'The hold is in force. It does not mean the machine is ready: run `skrr daemon maintenance status` or `hold --wait ready`.',
+            },
+            // 0 here means the hold was taken, NOT that the machine is ready.
+            exit: data_provider_1.DAEMON_MAINTENANCE_EXIT_CODES.ready,
+            stdout: [
+                `${created ? 'Hold taken' : 'Already held'}: generation ${view.hold.generation}.`,
+                ...describeView(view, { explain: input.explain }),
+            ],
+            stderr: [],
+        };
+    }
+    const timeoutMs = input.wait.timeoutMs;
+    const waited = await waitForReady({
+        read: () => attempt(() => io.api.get(target.runtimeKey)),
+        now: io.now,
+        sleep: io.sleep,
+        progress: io.progress,
+    }, { timeoutMs, intervalMs: input.wait.intervalMs ?? exports.MAINTENANCE_POLL_INTERVAL_MS });
+    const last = waited.view ?? view;
+    const wait = {
+        requested: true,
+        until: 'ready',
+        timeoutMs,
+        waitedMs: waited.waitedMs,
+        polls: waited.polls,
+        timedOut: waited.outcome === 'timeout',
+    };
+    if (waited.outcome === 'ready') {
+        return {
+            document: {
+                ...common,
+                outcome: 'ready',
+                exit: data_provider_1.DAEMON_MAINTENANCE_EXIT_CODES.ready,
+                wait,
+                ...viewFields(last),
+            },
+            exit: data_provider_1.DAEMON_MAINTENANCE_EXIT_CODES.ready,
+            stdout: [
+                `Ready: generation ${last.hold?.generation}.`,
+                ...(last.journey.modifiers.includes('attested')
+                    ? ["This is the owner's attestation, not evidence from the machine."]
+                    : []),
+                ...describeView(last, { explain: input.explain }),
+            ],
+            stderr: [],
+        };
+    }
+    if (waited.outcome === 'released') {
+        return {
+            document: {
+                ...common,
+                holdInForce: false,
+                outcome: 'released_elsewhere',
+                exit: data_provider_1.DAEMON_MAINTENANCE_EXIT_CODES.refused,
+                wait,
+                ...viewFields(last),
+                note: 'The hold was released by someone else while waiting, so there is nothing left to wait for.',
+            },
+            exit: data_provider_1.DAEMON_MAINTENANCE_EXIT_CODES.refused,
+            stdout: [],
+            stderr: ['The hold was released while waiting. The machine is no longer held.'],
+        };
+    }
+    if (waited.outcome === 'refused' && waited.error) {
+        return failedRun('hold', waited.error, {
+            target,
+            view: last,
+            extra: { holdInForce: true, wait },
+            next: [
+                `The hold taken above is still in force. \`skrr daemon maintenance resume ${target.runtimeKey}\` releases it.`,
+            ],
+        });
+    }
+    // The timeout. What the LAST read saw decides 2 (still moving) or 3 (unknown),
+    // exactly `maintenanceExitFor`. If that read FAILED, the state at the deadline is
+    // not known, whatever an earlier read said: an old `draining` is not evidence about
+    // now, so it is neither shown nor used for the exit.
+    const known = waited.view && !waited.error ? waited.view : null;
+    const exit = known
+        ? data_provider_1.DAEMON_MAINTENANCE_EXIT_CODES[(0, data_provider_1.maintenanceExitFor)(known.journey)]
+        : data_provider_1.DAEMON_MAINTENANCE_EXIT_CODES.unknown;
+    const note = 'The timeout did not release the hold: it is still in force. ' +
+        `Run \`skrr daemon maintenance resume ${target.runtimeKey}\` to release it.`;
+    return {
+        document: {
+            ...common,
+            outcome: 'timeout',
+            exit,
+            wait,
+            ...viewFields(known),
+            ...(waited.error
+                ? { lastReadError: { code: waited.error.code, message: waited.error.message } }
+                : {}),
+            note,
+        },
+        exit,
+        stdout: known ? describeView(known, { explain: input.explain }) : [],
+        stderr: [
+            `Not ready after ${elapsed(waited.waitedMs)}: ${known ? stateLine(known) : 'the last read of the state failed, so it is not known'}.`,
+            note,
+        ],
+    };
+}
+/** `resume`: release the hold. A compare-and-set on the generation. */
+async function runResume(input, io) {
+    const resolved = await resolveTarget(io, input.ref, 'held', true);
+    if (!resolved.ok)
+        return failedRun('resume', resolved.failure);
+    const target = resolved.target;
+    let generation = input.generation;
+    if (generation === undefined) {
+        const got = await attempt(() => io.api.get(target.runtimeKey));
+        if (!got.ok)
+            return failedRun('resume', got.error, { target });
+        if (got.value.hold?.lifecycle !== 'held') {
+            return failedRun('resume', refusal('not_held'), {
+                target,
+                view: got.value,
+                extra: got.value.hold ? { latestGeneration: got.value.hold.generation } : {},
+            });
+        }
+        generation = got.value.hold.generation;
+    }
+    const put = await attempt(() => io.api.change(target.runtimeKey, { lifecycle: 'released', expectedGeneration: generation }));
+    if (!put.ok)
+        return failedRun('resume', put.error, { target });
+    const view = put.value;
+    // The server answers with the machine's LATEST hold. Releasing a generation that was
+    // already released while a newer one is live leaves the machine held, and "resumed"
+    // would be the one claim that is false.
+    if (view.hold?.lifecycle === 'held') {
+        return failedRun('resume', {
+            kind: 'refused',
+            ...refusal('generation_conflict', {
+                currentGeneration: view.hold.generation,
+                message: `Generation ${generation} was already released, but the machine is held by generation ${view.hold.generation}.`,
+            }),
+        }, { target, view, extra: { holdInForce: true } });
+    }
+    return {
+        document: {
+            schema: exports.DAEMON_MAINTENANCE_CLI_SCHEMA,
+            command: 'resume',
+            outcome: 'released',
+            exit: data_provider_1.DAEMON_MAINTENANCE_EXIT_CODES.ready,
+            ...targetDocument(target),
+            releasedGeneration: generation,
+            holdInForce: false,
+            ...viewFields(view),
+        },
+        exit: data_provider_1.DAEMON_MAINTENANCE_EXIT_CODES.ready,
+        stdout: [
+            `Released: generation ${generation}. New work can start again.`,
+            ...outcomeLines(view.hold?.outcome),
+        ],
+        stderr: [],
+    };
+}
+/** The labels of the work the reading shows, for a `proceed_anyway` the owner confirmed. */
+function holdersShown(view) {
+    const labels = [];
+    for (const source of view.reading?.sources ?? []) {
+        for (const holder of source.holders) {
+            if (holder.class !== 'active' && holder.class !== 'unproven')
+                continue;
+            const label = (holder.label || holder.ref || holder.kind || '').trim();
+            if (label)
+                labels.push(label.slice(0, MAX_ACKNOWLEDGED_LABEL));
+        }
+    }
+    return [...new Set(labels)].slice(0, MAX_ACKNOWLEDGED);
+}
+/**
+ * `attest`: the owner says the machine is ready (`--ready`, only where the server
+ * allows it) or proceeds anyway (`--proceed`, naming what was running). The server
+ * decides whether an attestation applies; the CLI never decides it from a phase.
+ */
+async function runAttest(input, io) {
+    const resolved = await resolveTarget(io, input.ref, 'held', true);
+    if (!resolved.ok)
+        return failedRun('attest', resolved.failure);
+    const target = resolved.target;
+    const got = await attempt(() => io.api.get(target.runtimeKey));
+    if (!got.ok)
+        return failedRun('attest', got.error, { target });
+    if (got.value.hold?.lifecycle !== 'held') {
+        return failedRun('attest', refusal('not_held'), { target, view: got.value });
+    }
+    const generation = input.generation ?? got.value.hold.generation;
+    const acknowledged = input.kind === 'proceed_anyway' ? holdersShown(got.value) : [];
+    if (acknowledged.length > 0) {
+        io.progress(`Proceeding anyway while this is running: ${acknowledged.join('; ')}`);
+    }
+    const post = await attempt(() => io.api.attest(target.runtimeKey, {
+        expectedGeneration: generation,
+        kind: input.kind,
+        ...(input.kind === 'proceed_anyway' ? { acknowledged } : {}),
+    }));
+    if (!post.ok)
+        return failedRun('attest', post.error, { target, view: got.value });
+    const view = post.value;
+    return {
+        document: {
+            schema: exports.DAEMON_MAINTENANCE_CLI_SCHEMA,
+            command: 'attest',
+            outcome: 'attested',
+            exit: data_provider_1.DAEMON_MAINTENANCE_EXIT_CODES.ready,
+            ...targetDocument(target),
+            kind: input.kind,
+            attestedGeneration: generation,
+            ...(input.kind === 'proceed_anyway' ? { acknowledged } : {}),
+            holdInForce: view.hold?.lifecycle === 'held',
+            ...viewFields(view),
+        },
+        exit: data_provider_1.DAEMON_MAINTENANCE_EXIT_CODES.ready,
+        stdout: [
+            input.kind === 'attest_ready'
+                ? `Attested: generation ${generation}. This records your word that the machine is ready; it is not evidence from the machine.`
+                : `Recorded: you are proceeding anyway at generation ${generation}${acknowledged.length ? `, with ${acknowledged.length} thing(s) running` : ''}.`,
+            'The hold stays in force until you run `skrr daemon maintenance resume`.',
+        ],
+        stderr: [],
+    };
+}
+/** `--timeout`, parsed and bounded. */
+function parseTimeout(value) {
+    if (value === undefined)
+        return { ok: true, ms: exports.MAINTENANCE_DEFAULT_TIMEOUT_MS };
+    if (!value.trim()) {
+        return { ok: false, message: '--timeout needs a duration, such as 90s, 30m or 2h.' };
+    }
+    let ms;
+    try {
+        ms = (0, hosted_machines_1.parseDurationMs)(value, '--timeout');
+    }
+    catch {
+        return {
+            ok: false,
+            message: `--timeout "${value}" is not a duration. Use a number with a unit, such as 90s, 30m or 2h.`,
+        };
+    }
+    if (ms === undefined || ms > exports.MAINTENANCE_MAX_TIMEOUT_MS) {
+        return { ok: false, message: '--timeout can be at most 24h.' };
+    }
+    return { ok: true, ms };
+}
+/** A failed flag, as a refusal the command prints the way every other refusal is printed. */
+function invalidFlagRun(command, message) {
+    return failedRun(command, { kind: 'refused', code: 'invalid_request', message });
+}