@skrr-ai/cli 0.1.119 → 0.1.120

package/dist/node_modules/@skrr-ai/auth-core/dist/esm/guidedUpdate.js

@@ -0,0 +1,404 @@
+/**
+ * The pure core of a GUIDED update (OSK-19107, Space OSK-S-524, tasks M51 to M53):
+ * hold the machine, wait for it to be quiet, update, verify, and give the machine
+ * back. The Desktop app and a standalone `skrr` install both run it, so what they
+ * decide on, and the words they use for what is in the way, cannot drift apart.
+ *
+ * This file is DECISIONS ONLY. It performs no I/O, reads no clock and holds no
+ * state, so every rule below is a table test. The orchestration (a persisted flow
+ * record, polling, the installer, the supervisor) lives with each caller, because
+ * that is the part that differs between a Desktop that quits mid-flow and a CLI that
+ * runs in the foreground.
+ *
+ * ## Why these rules (each names the failure it prevents)
+ *
+ * - **`prepare` is a probe that briefly refuses admitted work.** While it runs the
+ *   daemon refuses admitted tool calls with an infra-class error, and a tool-proxy Run
+ *   that sees one drops its tools to the Hosted Machine for good. So a guided flow
+ *   calls it ONLY when the server's reading says there is nothing admitted to refuse
+ *   ({@link prepareBasis}), never to find out whether there is.
+ * - **`unknown` is an answer.** A source nobody could read is never zero and never
+ *   ready. {@link noServerVeto} is deliberately strict: every server source must have
+ *   been read, and none may list active or unproven work.
+ * - **A server source can only veto.** Only the daemon's own positively announced
+ *   report grants `ready`; the owner's attestation and the daemon's own `prepare`
+ *   (labelled `no_veto`, D38) are the two other bases, and each is labelled as what
+ *   it is wherever it is shown.
+ * - **Blockers are shown in the words of whoever knows them.** The daemon's blocker
+ *   `reason` and the server's holder `label` are the vocabulary; nothing here
+ *   re-spells them. They are bounded and never a raw path, because a diagnostic can
+ *   carry one.
+ * - **A new PID, an exit code or a cloud connection is not a verified update.**
+ *   {@link verifyReplacement} requires the daemon's own `verified`, from a process
+ *   other than the one that was replaced, for the build that was asked for, and the
+ *   same machine identity afterwards. A different identity is the reinstall case: the
+ *   hold is left in place and shown, never resumed.
+ *
+ * The shapes are STRUCTURAL SUBSETS of `DaemonMaintenanceView` in
+ * `@skrr-ai/data-provider` (`daemonMaintenance.ts`), which is the one vocabulary.
+ * This package cannot import it (it sits below it), so `guidedUpdate.test.ts` reads
+ * that file and fails when a list mirrored here drifts from it.
+ */
+/** The server sources that can only veto. `daemon_report` is the only one that grants. */
+export const GUIDED_SERVER_SOURCES = [
+    'claims',
+    'receipts',
+    'sessions',
+    'runs',
+    'leases',
+    'custody',
+];
+/** The refusals the owner API names, mirrored from `DAEMON_MAINTENANCE_REFUSALS`. */
+export const GUIDED_REFUSALS = [
+    'managed_machine',
+    'no_stable_identity',
+    'not_found',
+    'ambiguous',
+    'generation_conflict',
+    'not_held',
+    'already_held',
+    'attestation_not_applicable',
+    'not_owner',
+    'held_by_other',
+];
+export function isGuidedRefusal(value) {
+    return typeof value === 'string' && GUIDED_REFUSALS.includes(value);
+}
+/** The daemon handoff phases, mirrored from `daemon/src/update/handoff.ts`. */
+export const GUIDED_HANDOFF_PHASES = [
+    'ready',
+    'deferred',
+    'reconnecting',
+    'verified',
+    'failed',
+    'rolled-back',
+];
+/**
+ * Whether the server holds a reading that nothing vetoes, for a daemon that cannot
+ * report (D38). Strict on purpose: a source that is absent from the list, unreadable,
+ * truncated, or that names active or unproven work, is a veto. `daemon_report` must
+ * be `not_announced`: any other answer means the reading is not the
+ * `no_inventory_capability` case this is for.
+ */
+export function noServerVeto(sources) {
+    // `Array.isArray` does not narrow a readonly array, so the list is named explicitly.
+    if (!Array.isArray(sources))
+        return false;
+    const list = sources;
+    for (const name of GUIDED_SERVER_SOURCES) {
+        const source = list.find((s) => s && s.source === name);
+        if (!source || source.read !== 'ok' || source.truncated === true)
+            return false;
+        const holders = Array.isArray(source.holders)
+            ? source.holders
+            : null;
+        if (!holders)
+            return false;
+        if (holders.some((h) => h && (h.class === 'active' || h.class === 'unproven')))
+            return false;
+    }
+    const report = list.find((s) => s && s.source === 'daemon_report');
+    return report !== undefined && report.read === 'not_announced';
+}
+/**
+ * Read the owner API's view for a flow that took `generation`.
+ *
+ * Order matters and is the rule set (each is a test):
+ *  1. No live hold: `not_held`. A different live generation: `generation_changed`.
+ *  2. The fence is not confirmed (`pausing`): nothing below it means anything.
+ *  3. The reading is `ready` (the daemon's own report): `ready` by evidence.
+ *  4. `draining`: work is running. Evidence, never overridden.
+ *  5. `unknown`: ready by attestation if the Journey says the owner vouched for this
+ *     cause; `no_report` if the daemon cannot report and no source vetoes; else
+ *     `unknown`. No reading at all is `unknown (source_unreadable)`, never ready.
+ */
+export function evaluateReadiness(view, expectedGeneration) {
+    const hold = view?.hold;
+    if (!view || !hold || hold.lifecycle !== 'held')
+        return { kind: 'not_held' };
+    if (expectedGeneration !== null && hold.generation !== expectedGeneration) {
+        return { kind: 'generation_changed', currentGeneration: hold.generation };
+    }
+    if (view.journey?.phase === 'pausing')
+        return { kind: 'pausing' };
+    const reading = view.reading;
+    if (!reading)
+        return { kind: 'unknown', cause: 'source_unreadable' };
+    if (reading.state === 'ready')
+        return { kind: 'ready', basis: 'evidence' };
+    if (reading.state === 'draining')
+        return { kind: 'draining' };
+    if (reading.state !== 'unknown')
+        return { kind: 'unknown', cause: 'source_unreadable' };
+    if (view.journey?.phase === 'ready' && view.journey.modifiers?.includes('attested')) {
+        return { kind: 'ready', basis: 'attested' };
+    }
+    if (reading.cause === 'no_inventory_capability' && noServerVeto(reading.sources)) {
+        return { kind: 'no_report' };
+    }
+    return { kind: 'unknown', cause: reading.cause ?? null };
+}
+/**
+ * Whether a guided flow may call the daemon's `prepare`, and on what basis. `null`
+ * means NO: `prepare` is never a way to find out. A legacy daemon never gets one:
+ * it has no endpoint, and its restart is the owner's attested decision, not a probe.
+ */
+export function prepareBasis(readiness, opts) {
+    if (opts.legacy)
+        return null;
+    if (readiness.kind === 'ready')
+        return readiness.basis;
+    if (readiness.kind === 'no_report')
+        return 'no_veto';
+    return null;
+}
+/**
+ * Whether a legacy daemon (no handoff endpoint) may be restarted by the supervisor.
+ * Only on the owner's attestation: the daemon cannot report what it is doing and a
+ * SIGTERM ends its wrappers, so nothing but the owner's word can vouch for it.
+ */
+export function legacyRestartAllowed(readiness) {
+    return readiness.kind === 'ready' && readiness.basis === 'attested';
+}
+export const MAX_OWNER_BLOCKERS = 20;
+const BLOCKER_TEXT_MAX = 200;
+const ID_PATTERN = /^[A-Za-z0-9_-]{1,120}$/;
+// A diagnostic can carry a local path or a URL. Showing one would leak the layout of
+// someone's machine into a notice, so a reason that looks like one is dropped whole.
+const PATHLIKE = /(?:^|[\s("'=])(?:~|\.{1,2})?[\\/](?:[\w.-]+[\\/])+|[A-Za-z]:[\\/]|\\\\|file:\/\/|\/(?:Users|home|var|tmp|private|opt|etc|usr)\//i;
+/** A sentence safe to put in front of the owner, or `undefined` when it is not. */
+export function sanitizeBlockerText(value, max = BLOCKER_TEXT_MAX) {
+    if (typeof value !== 'string')
+        return undefined;
+    const cleaned = Array.from(value, (ch) => {
+        const code = ch.charCodeAt(0);
+        return code < 0x20 || code === 0x7f ? ' ' : ch;
+    })
+        .join('')
+        .replace(/\s+/g, ' ')
+        .trim();
+    if (!cleaned || PATHLIKE.test(cleaned))
+        return undefined;
+    return cleaned.length > max ? `${cleaned.slice(0, max - 1)}…` : cleaned;
+}
+function boundedId(value) {
+    return typeof value === 'string' && ID_PATTERN.test(value) ? value : undefined;
+}
+/**
+ * Everything in the way, from the three places that know: the server's holders
+ * (active and unproven work: `pending_delivery` and `forensic` never block), the
+ * daemon's own refusal from `prepare`, and the work the Desktop app itself hosts and
+ * ends when it quits (`LocalSessionService` processes and agent browser windows,
+ * which the daemon's inventory cannot see).
+ *
+ * A daemon blocker whose id equals a server holder's ref is the same work seen twice:
+ * it is listed once, with the daemon's reason and the server's label. Whether the two
+ * ids are in fact comparable was never established (review §6.2 item 2), so a match
+ * only MERGES the wording and never hides a blocker that has no match.
+ */
+export function describeBlockers(input) {
+    const out = [];
+    const serverByRef = new Map();
+    const serverHolders = [];
+    for (const source of input.view?.reading?.sources ?? []) {
+        for (const holder of source?.holders ?? []) {
+            if (!holder || (holder.class !== 'active' && holder.class !== 'unproven'))
+                continue;
+            serverHolders.push(holder);
+            if (typeof holder.ref === 'string')
+                serverByRef.set(holder.ref, holder);
+        }
+    }
+    const merged = new Set();
+    for (const blocker of input.daemon ?? []) {
+        if (!blocker || typeof blocker.kind !== 'string')
+            continue;
+        const id = boundedId(blocker.id);
+        const holder = blocker.id ? serverByRef.get(blocker.id) : undefined;
+        if (holder)
+            merged.add(holder);
+        const label = holder ? sanitizeBlockerText(holder.label, 120) : undefined;
+        out.push({
+            source: 'daemon',
+            kind: blocker.kind.slice(0, 64),
+            text: sanitizeBlockerText(blocker.reason),
+            ...(label ? { label } : {}),
+            ...(id ? { id } : {}),
+            ...(holder?.since !== undefined ? { since: holder.since } : {}),
+        });
+    }
+    for (const holder of serverHolders) {
+        if (merged.has(holder))
+            continue;
+        const id = boundedId(holder.ref);
+        out.push({
+            source: 'server',
+            kind: String(holder.kind || 'work').slice(0, 64),
+            text: sanitizeBlockerText(holder.label, 120),
+            ...(id ? { id } : {}),
+            ...(holder.since !== undefined ? { since: holder.since } : {}),
+        });
+    }
+    const desktop = input.desktop;
+    if (desktop && desktop.localSessions > 0) {
+        out.push({ source: 'desktop', kind: 'desktop_local_sessions', count: desktop.localSessions });
+    }
+    if (desktop && desktop.agentBrowserWindows > 0) {
+        out.push({
+            source: 'desktop',
+            kind: 'desktop_agent_browser',
+            count: desktop.agentBrowserWindows,
+        });
+    }
+    return out.slice(0, MAX_OWNER_BLOCKERS);
+}
+/**
+ * A string that changes whenever the set of things in the way changes. The "update
+ * now anyway" confirmation carries the one it was shown, and the action is refused
+ * when it no longer matches: a confirmation that names what WAS running is not a
+ * confirmation of what is.
+ */
+export function blockersFingerprint(blockers) {
+    return blockers
+        .map((b) => [b.source, b.kind, b.id ?? '', b.count ?? ''].join('|'))
+        .sort()
+        .join(';');
+}
+/**
+ * The labels the owner is shown, as the server records them in the outcome
+ * (`acknowledged`): each bounded to the server's 160-character limit.
+ */
+export function acknowledgedLabels(blockers, max = 20) {
+    const labels = [];
+    for (const b of blockers) {
+        const detail = b.label ?? b.text;
+        const text = b.count ? `${b.kind} (${b.count})` : detail ? `${b.kind}: ${detail}` : b.kind;
+        labels.push(text.slice(0, 160));
+        if (labels.length >= max)
+            break;
+    }
+    return labels;
+}
+function isHandoffStatus(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const v = value;
+    return (v.protocolVersion === 1 &&
+        typeof v.handoffId === 'string' &&
+        typeof v.phase === 'string' &&
+        GUIDED_HANDOFF_PHASES.includes(v.phase) &&
+        typeof v.sourceProcessId === 'string' &&
+        !!v.target &&
+        typeof v.target.sha256 === 'string' &&
+        Array.isArray(v.blockers) &&
+        Array.isArray(v.expectedSessions));
+}
+export function classifyHandoffReply(input) {
+    const { statusCode, body } = input;
+    if (statusCode === null)
+        return { kind: 'unreachable' };
+    if (statusCode === 200) {
+        return isHandoffStatus(body) ? { kind: 'ok', status: body } : { kind: 'unreachable' };
+    }
+    if (statusCode === 404)
+        return { kind: 'absent' };
+    if (statusCode === 401 || statusCode === 403)
+        return { kind: 'unauthorized' };
+    if (statusCode === 400 || statusCode === 409 || statusCode === 413 || statusCode === 405) {
+        const code = body && typeof body === 'object' && typeof body.error === 'string'
+            ? String(body.error).slice(0, 64)
+            : undefined;
+        return { kind: 'refused', ...(code ? { code } : {}) };
+    }
+    return { kind: 'unreachable' };
+}
+/**
+ * Decide whether a committed replacement is complete. All of (1) and (2) must hold
+ * before anything else is asked of the server (3, {@link serverSawNewProcess}), and
+ * nothing here resumes: the verdict only says what was seen.
+ *
+ * An identity that is merely UNREADABLE (the bootstrap is mid-rotation, the machine
+ * payload could not be fetched) is `not_yet`, never a reinstall and never verified.
+ */
+export function verifyReplacement(evidence) {
+    const { handoff, expect, identity } = evidence;
+    if (!handoff)
+        return { kind: 'not_yet', missing: 'daemon_status' };
+    if (handoff.phase === 'failed' || handoff.phase === 'rolled-back') {
+        return {
+            kind: 'failed',
+            phase: handoff.phase,
+            reason: String(handoff.reason || handoff.phase).slice(0, 64),
+            // A failed handoff observed by the SAME process is a replacement that never
+            // happened: the old daemon is still the one running, and a retry is meaningful.
+            sameProcess: handoff.observer?.processId === expect.sourceProcessId,
+        };
+    }
+    if (handoff.phase !== 'verified')
+        return { kind: 'not_yet', missing: 'verified' };
+    const by = handoff.verifiedBy;
+    if (!by ||
+        by.processId === expect.sourceProcessId ||
+        handoff.target.sha256 !== expect.targetSha256 ||
+        (expect.version !== null && by.version !== expect.version)) {
+        return { kind: 'not_yet', missing: 'verified' };
+    }
+    if (identity.bootstrapDaemonId === null || identity.runtimeKeyNow === null) {
+        return { kind: 'not_yet', missing: 'identity_unreadable' };
+    }
+    if (identity.bootstrapDaemonId !== identity.recordedDaemonId) {
+        return { kind: 'reinstall', what: 'daemon_id' };
+    }
+    if (identity.runtimeKeyNow !== identity.recordedRuntimeKey) {
+        return { kind: 'reinstall', what: 'runtime_key' };
+    }
+    return { kind: 'verified' };
+}
+/**
+ * The legacy counterpart: a daemon with no handoff cannot say `verified`, so the copy
+ * claims only what was seen ("restarted on version X"), never "adopted N sessions".
+ * A new process (a different start time and, where known, a different PID), the same
+ * identity, and the version it announces equal to the bundled one.
+ */
+export function verifyLegacyRestart(evidence) {
+    const { before, after, expect } = evidence;
+    if (after.daemonId === null || after.startedAt === null || evidence.runtimeKeyNow === null) {
+        return { kind: 'not_yet', missing: 'identity_unreadable' };
+    }
+    const newProcess = before.startedAt === null
+        ? after.processId !== null && after.processId !== before.processId
+        : after.startedAt > before.startedAt &&
+            (after.processId === null ||
+                before.processId === null ||
+                after.processId !== before.processId);
+    if (!newProcess)
+        return { kind: 'not_yet', missing: 'verified' };
+    if (after.daemonId !== expect.daemonId)
+        return { kind: 'reinstall', what: 'daemon_id' };
+    if (evidence.runtimeKeyNow !== evidence.recordedRuntimeKey) {
+        return { kind: 'reinstall', what: 'runtime_key' };
+    }
+    if (expect.version !== null && after.version !== expect.version) {
+        return { kind: 'not_yet', missing: 'verified' };
+    }
+    return { kind: 'verified' };
+}
+/**
+ * Whether the server independently saw a new process register under the held key
+ * (condition 3). The Journey says `back_held` for ANY process that registered since
+ * the fence, so it can only corroborate THIS replacement when it did not already say
+ * so before the commit. When it did, the answer is `not_independent`: the flow rests
+ * on (1) and (2) and says so.
+ */
+export function serverSawNewProcess(input) {
+    if (input.backHeldAtCommit)
+        return 'not_independent';
+    return input.journeyPhase === 'back_held' ? 'seen' : 'not_yet';
+}
+/** Whether an observed hold is the one this flow took, and still live. */
+export function isOurLiveHold(view, generation) {
+    return (generation !== null &&
+        !!view?.hold &&
+        view.hold.lifecycle === 'held' &&
+        view.hold.generation === generation);
+}

package/dist/node_modules/@skrr-ai/auth-core/dist/esm/maintenanceReportWire.d.ts

@@ -0,0 +1,178 @@
+/**
+ * The maintenance report wire contract (Machine Maintenance, OSK-19107, task M24;
+ * `docs/architecture/machine-maintenance/implementation-plan-2026-10-24.md` §3.5,
+ * `phase0/m04-quiescence-evidence.md` §2.5 and §2.6).
+ *
+ * Declared ONCE, here. The daemon is published and cannot import the API, so the
+ * capability name, the payload shape and its bounds live in this package, which
+ * every end can import (`@skrr-ai/auth-core/maintenance-report-wire`).
+ * `maintenanceReportWire.test.ts` fails on a second spelling of the capability
+ * anywhere else in the repo. The shape follows `dedicatedRuntimeBusyWire.ts`, the
+ * precedent for a positively announced, fail-closed report, and differs from it
+ * only where the owner's pause needs more.
+ *
+ * WHAT THE REPORT SAYS
+ * ---------------------------------------------------------------------------
+ * "What does this daemon process hold right now that an update would take from
+ * the owner, and has anything been admitted since the last time you asked?" It is
+ * a LOCAL read summarised into counts, the handoff's own restart blockers, and
+ * the daemon's own update handoff phase.
+ *
+ * It is EVIDENCE, never authority. The fence does not depend on it: a daemon that
+ * lies, or one that sends nothing, cannot make a held machine accept work. Only
+ * this report can grant `ready` (a server-side source can only veto it), and a
+ * daemon that never announces the capability can only reach `ready` by the
+ * owner's attestation.
+ *
+ * FAIL CLOSED, in three places
+ * ---------------------------------------------------------------------------
+ *  1. A count is `0` only when the daemon positively counted. A source that could
+ *     not be read is `complete: 'unknown'`; a daemon that is leaving is
+ *     `complete: false`. A reader MUST treat both as busy, whatever the counts
+ *     say (`maintenanceReportIsQuiet` is the one place that says so).
+ *  2. A report that is malformed in ANY field is `null` from
+ *     `parseMaintenanceReport`, and the caller treats the machine as not quiet.
+ *     A count that is missing, negative, fractional or not a safe integer is not
+ *     "zero": it is a different, broken report. A version this parser does not
+ *     know is `null` too: a newer shape needs its own announced capability.
+ *  3. Bounds. The blocker list and every string are clamped, so one report can
+ *     never be large enough to matter, and a field that is NOT in the contract is
+ *     never copied into what the parser returns (the result is built from a
+ *     fresh object, so `__proto__` and its kin cannot ride along).
+ *
+ * `admittedTotal`
+ * ---------------------------------------------------------------------------
+ * A MONOTONIC counter of admissions since this process started. The server proves
+ * "nothing was admitted between two reports" by comparing two values, without
+ * trusting the daemon's clock. It counts at every place the daemon admits work
+ * and OVER-counts on purpose (one admission may be noted at the gate and again
+ * where the work registers): a second increment can only make the proof harder,
+ * never easier. A path that the daemon cannot count must say so in
+ * `daemon/src/maintenance-report.ts`, not hide in a zero.
+ */
+export declare const MAINTENANCE_REPORT_CAPABILITY = "maintenance_report_v1";
+/** The heartbeat (and register) key the report rides under. Sent only by a daemon that announced the capability. */
+export declare const MAINTENANCE_REPORT_HEARTBEAT_KEY = "maintenanceReport";
+export declare const MAINTENANCE_REPORT_VERSION = 1;
+/**
+ * The daemon's own update handoff phases (`daemon/src/update/handoff.ts`), and the
+ * members of `DaemonMaintenanceHandoff.phase` in `@skrr-ai/data-provider`. A phase
+ * outside this list is a newer protocol and makes the whole report `null`.
+ */
+export declare const MAINTENANCE_REPORT_HANDOFF_PHASES: readonly ["ready", "deferred", "reconnecting", "verified", "failed", "rolled-back"];
+export type MaintenanceReportHandoffPhase = (typeof MAINTENANCE_REPORT_HANDOFF_PHASES)[number];
+export declare const MAINTENANCE_REPORT_LIMITS: {
+    /** The handoff's blockers carried for the "waiting on" text; the counts, not this list, decide busy. */
+    readonly maxBlockers: 32;
+    readonly maxKindLength: 32;
+    readonly maxIdLength: 128;
+    readonly maxReasonLength: 240;
+    readonly maxHandoffIdLength: 64;
+    readonly maxHandoffReasonLength: 64;
+    readonly maxProcessStartIdLength: 64;
+    /** Hard ceiling on the serialized report. The clamps above keep a valid one well under it. */
+    readonly maxSerializedBytes: 20000;
+};
+/** What `complete` can be. Anything but `true` means the counts prove nothing. */
+export type MaintenanceReportComplete = boolean | 'unknown';
+/** The handoff's own `RestartBlocker` shape (`daemon/src/update/handoff.ts`). Reason text is the handoff's, never re-spelled. */
+export interface MaintenanceReportBlocker {
+    kind: string;
+    id?: string;
+    reason: string;
+}
+export interface MaintenanceReportInflight {
+    /** Provider sessions and their wrapper processes: in-process turns, preparing dispatches, live wrappers. */
+    sessions: number;
+    /** Tool calls running, plus background commands still running. */
+    tools: number;
+    /** Terminals the daemon holds, preservable or not. A person's open shell is work an update would interrupt. */
+    terminals: number;
+    /** Provider turns that still depend on credentials, permissions, a browser or a model connection the service owns. */
+    providerDependencies: number;
+    /** Write-ahead entries whose durability the daemon has not confirmed. */
+    walUnconfirmed: number;
+}
+export interface MaintenanceReportHandoff {
+    phase: MaintenanceReportHandoffPhase;
+    handoffId: string;
+    reason?: string;
+    /** ISO time the daemon's lease on this phase ends. */
+    expiresAt?: string;
+}
+export interface MaintenanceReport {
+    version: typeof MAINTENANCE_REPORT_VERSION;
+    /** The daemon process that read this. The server drops a report that is not its registered process's. */
+    processStartId: string;
+    /** ISO time of the daemon's own read. Informational: freshness is the server's receipt time. */
+    readAt: string;
+    /** `true`: every source was read. `'unknown'`: one could not be. `false`: the process is leaving. */
+    complete: MaintenanceReportComplete;
+    /** Monotonic count of admissions since this process started. */
+    admittedTotal: number;
+    inflight: MaintenanceReportInflight;
+    blockers: MaintenanceReportBlocker[];
+    /** True when the daemon had more blockers than it sent. */
+    blockersTruncated: boolean;
+    /** The daemon's own update handoff, only while it is live or unresolved; otherwise `null`. */
+    handoff: MaintenanceReportHandoff | null;
+}
+/**
+ * The reader's view of a daemon's heartbeat section. Anything malformed, from a
+ * daemon that did not announce the capability, an unknown version, or oversized
+ * is `null`, and the caller must then treat the machine as NOT quiet. Never
+ * trusts a field it did not validate and never copies one it does not know.
+ */
+export declare function parseMaintenanceReport(raw: unknown): MaintenanceReport | null;
+/**
+ * A report as it was stored (JSON text on the presence row). Anything that does
+ * not parse, or does not validate, is `null`: a stored value is an input like any
+ * other and is read with the same suspicion.
+ */
+export declare function parseStoredMaintenanceReport(stored: unknown): MaintenanceReport | null;
+/**
+ * The one definition of a POSITIVE ZERO: the daemon read every source and found
+ * nothing. `complete: 'unknown'` and `complete: false` are never zero whatever
+ * the counts say, because the counts were not (all) read.
+ *
+ * A blocker that is not work (a missing restart owner, say) does not make a
+ * report non-quiet; readiness is "nothing is running", not "the daemon can
+ * restart itself".
+ */
+export declare function maintenanceReportIsQuiet(report: MaintenanceReport | null): boolean;
+export interface BuildMaintenanceReportInput {
+    processStartId: string;
+    /** Epoch ms of the daemon's own read. */
+    readAtMs: number;
+    complete: MaintenanceReportComplete;
+    admittedTotal: number;
+    inflight: MaintenanceReportInflight;
+    blockers: ReadonlyArray<{
+        kind: string;
+        id?: string;
+        reason: string;
+    }>;
+    /** `expiresAtMs` is epoch ms; the wire carries ISO. */
+    handoff: {
+        phase: MaintenanceReportHandoffPhase;
+        handoffId: string;
+        reason?: string;
+        expiresAtMs?: number;
+    } | null;
+}
+/**
+ * A report that says nothing was counted. The shape the daemon sends when it
+ * could not read an inventory source at all, and the shape `buildMaintenanceReport`
+ * falls back to when it was handed something the contract cannot carry.
+ */
+export declare function unknownMaintenanceReport(processStartId: string, readAtMs: number, admittedTotal?: number): MaintenanceReport;
+/**
+ * Build the wire report from what the daemon read. Input the contract cannot
+ * carry (a negative count, a blocker with no kind, a time that is not a time)
+ * becomes an `unknown` report rather than a throw or a report that parses to
+ * something else, so the result parses whenever `processStartId` is a real id (the
+ * daemon's always is). A builder that threw would turn a bad read into silence,
+ * and silence is the absence of a report, which the server reads the same way,
+ * but later.
+ */
+export declare function buildMaintenanceReport(input: BuildMaintenanceReportInput): MaintenanceReport;