@murmurv2/cli 2.11.0

package/runtime/packages/setup/dist/src/status.js

@@ -0,0 +1,199 @@
+import { DatabaseSync } from "node:sqlite";
+import path from "node:path";
+import { realpath } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { loadConfig, readJson, safeError } from "./config.js";
+import { readOutboxAttention } from "./outbox-attention.js";
+const measured = (at) => ({ measuredAt: at, unknownReason: null });
+const unknown = (reason) => ({ measuredAt: null, unknownReason: reason });
+export const pairFingerprint = (config, peerId) => createHash("sha256").update(JSON.stringify([
+    config.agentId, config.keys.signing.publicKey, config.keys.encryption.publicKey, peerId,
+    config.peers[peerId]?.signing.publicKey, config.peers[peerId]?.encryption.publicKey,
+])).digest("hex");
+export function validPairProof(proof, config, peerId, now) {
+    const at = Date.parse(proof?.verifiedAt);
+    return proof?.peerId === peerId && proof?.localAgentId === config.agentId
+        && proof?.keyFingerprint === pairFingerprint(config, peerId)
+        && Number.isFinite(at) && now - at >= -5000 && now - at <= 86400000;
+}
+export async function readStatus({ context: c, adapter, now = Date.now }) {
+    const started = now();
+    const at = new Date(started).toISOString();
+    let config = null;
+    let configError = null;
+    try {
+        config = await loadConfig(c);
+    }
+    catch (e) {
+        configError = safeError(e);
+    }
+    let service;
+    try {
+        service = await adapter.status(c);
+    }
+    catch {
+        service = { state: "unknown", manager: adapter.manager,
+            since: null, pid: null, lastExitCode: null, observedStorePath: null, restartCount: null,
+            restartWindowMs: null, detail: "service.measurement-failed" };
+    }
+    const restartsLastHour = service.restartWindowMs === 3600000 && Number.isSafeInteger(service.restartCount)
+        && service.restartCount !== null && service.restartCount >= 0 ? service.restartCount : null;
+    if (restartsLastHour !== null && restartsLastHour >= 5)
+        service = { ...service, state: "failed", detail: "service.restart-loop" };
+    let observation = null;
+    let runtimeMeasurement = unknown("runtime.observation-unavailable");
+    try {
+        const raw = await readJson(path.join(c.dataDir, "daemon-observation.json"));
+        const timestamp = Date.parse(raw.measuredAt);
+        const storePath = await realpath(c.storePath);
+        if (raw.schema === "murmur.runtime/1" && service.state === "running" && raw.pid === service.pid
+            && raw.agentId === config?.agentId && raw.storePath === storePath && service.observedStorePath === storePath
+            && Number.isFinite(timestamp) && started - timestamp >= -5000 && started - timestamp <= 15000
+            && ["connected", "disconnected", "unauthorized", "unknown"].includes(raw.broker?.state)
+            && typeof raw.wake?.enabled === "boolean" && ["hook", "monitor", "none"].includes(raw.wake?.mode)) {
+            observation = raw;
+            runtimeMeasurement = measured(raw.measuredAt);
+        }
+        else
+            runtimeMeasurement = unknown("runtime.observation-unverified-or-stale");
+    }
+    catch { /* Absent legacy telemetry is unknown, never reconstructed from config. */ }
+    const inbox = { unread: null, total: null, lastAt: null,
+        unknownReason: null, measurements: { store: unknown("store.unavailable"), cursor: unknown("inbox.cursor-unavailable") } };
+    const outbox = { pending: null, inflight: null, delivered: null,
+        failed: null, dlq: null, oldestPendingAt: null,
+        lastError: null, lastErrorAt: null, unknownReason: null,
+        measurements: { store: unknown("store.unavailable") } };
+    const wake = { enabled: observation?.wake?.enabled ?? null, mode: observation?.wake?.mode ?? null,
+        responder: observation?.wake?.responder ?? null, storedOnly: null,
+        pendingUndelivered: null, lastDeliveredAt: null,
+        lastFault: null, lastFaultAt: null, unknownReason: null,
+        measurements: { store: unknown("store.unavailable"), runtime: runtimeMeasurement } };
+    const peers = {
+        list: config ? Object.keys(config.peers).map((agentId) => ({ agentId, paired: null, lastInboundAt: null, lastOutboundAt: null })) : null,
+        unknownReason: configError, measurements: { config: config ? measured(at) : unknown(configError ?? "config.unavailable"), store: unknown("store.unavailable"), proof: unknown("peers.proof-unavailable") },
+    };
+    let deliveries = null;
+    let attention = { unknownReason: 'store.unavailable' };
+    let db;
+    try {
+        db = new DatabaseSync(c.storePath, { readOnly: true });
+        db.exec("PRAGMA busy_timeout=1000; BEGIN");
+        const summary = db.prepare("SELECT COUNT(*) AS total, MAX(created_at) AS lastAt, COALESCE(MAX(rowid),0) AS tip FROM local_messages WHERE direction='inbound'").get();
+        inbox.total = Number(summary.total);
+        inbox.lastAt = summary.lastAt;
+        inbox.measurements.store = measured(at);
+        try {
+            const cursor = await readJson(path.join(c.dataDir, "read-state.json"));
+            if (cursor.schema !== "murmur.read/1" || cursor.agentId !== config?.agentId || !Number.isSafeInteger(cursor.rowid)
+                || cursor.rowid < 0 || cursor.rowid > Number(summary.tip))
+                throw new Error("inbox.cursor-invalid");
+            inbox.unread = Number(db.prepare("SELECT COUNT(*) AS n FROM local_messages WHERE direction='inbound' AND rowid>?").get(cursor.rowid).n);
+            inbox.measurements.cursor = measured(at);
+        }
+        catch { /* A missing cursor is not an empty inbox. */ }
+        const counts = Object.fromEntries(db.prepare("SELECT status, COUNT(*) AS n FROM outbox GROUP BY status").all().map((r) => [r.status, Number(r.n)]));
+        outbox.pending = counts.pending ?? 0;
+        outbox.inflight = counts.sent ?? 0;
+        outbox.delivered = counts.acked ?? 0;
+        outbox.failed = counts.failed ?? 0;
+        outbox.dlq = counts.dlq ?? 0;
+        outbox.oldestPendingAt = db.prepare("SELECT MIN(created_at) AS at FROM outbox WHERE status IN ('pending','sent','failed')").get().at;
+        const error = db.prepare("SELECT last_error,updated_at FROM outbox WHERE last_error IS NOT NULL AND last_error!='' ORDER BY updated_at DESC LIMIT 1").get();
+        outbox.lastError = error ? safeError(error.last_error) : null;
+        outbox.lastErrorAt = error?.updated_at ?? null;
+        outbox.measurements.store = measured(at);
+        if (config) {
+            try {
+                attention = await readOutboxAttention(c, config.agentId, db);
+            }
+            catch (error) {
+                attention = { unknownReason: safeError(error) };
+            }
+        }
+        try {
+            const rows = Object.fromEntries(db.prepare("SELECT wake_status,COUNT(*) AS n FROM local_messages WHERE direction='inbound' GROUP BY wake_status").all().map((r) => [r.wake_status, Number(r.n)]));
+            wake.storedOnly = rows["stored-only"] ?? 0;
+            wake.pendingUndelivered = (rows.pending ?? 0) + (rows.inflight ?? 0) + (rows.failed ?? 0);
+            wake.lastDeliveredAt = db.prepare("SELECT MAX(wake_updated_at) AS at FROM local_messages WHERE direction='inbound' AND wake_status='handled'").get().at;
+            const fault = db.prepare("SELECT wake_error,wake_updated_at FROM local_messages WHERE direction='inbound' AND wake_status IN ('failed','dlq') AND wake_error IS NOT NULL ORDER BY wake_updated_at DESC LIMIT 1").get();
+            wake.lastFault = fault ? safeError(fault.wake_error) : null;
+            wake.lastFaultAt = fault?.wake_updated_at ?? null;
+            wake.measurements.store = measured(at);
+        }
+        catch {
+            wake.measurements.store = unknown("wake.store-schema-unavailable");
+        }
+        for (const peer of peers.list ?? []) {
+            peer.lastInboundAt = db.prepare("SELECT MAX(created_at) AS at FROM local_messages WHERE direction='inbound' AND sender=?").get(peer.agentId).at;
+            peer.lastOutboundAt = db.prepare("SELECT MAX(created_at) AS at FROM outbox WHERE json_extract(envelope_json,'$.recipients[0]')=?").get(peer.agentId).at;
+        }
+        peers.measurements.store = measured(at);
+        const outbound = db.prepare("SELECT msg_id AS msgId,json_extract(envelope_json,'$.recipients[0]') AS peer,'outbound' AS direction,CASE status WHEN 'acked' THEN 'delivered' WHEN 'sent' THEN 'inflight' ELSE status END AS state,updated_at AS at,attempts,last_error AS error FROM outbox ORDER BY updated_at DESC LIMIT 20").all();
+        const inbound = db.prepare("SELECT msg_id AS msgId,sender AS peer,'inbound' AS direction,'delivered' AS state,created_at AS at,0 AS attempts,NULL AS error FROM local_messages WHERE direction='inbound' ORDER BY created_at DESC LIMIT 20").all();
+        deliveries = [...outbound, ...inbound].sort((a, b) => String(b.at).localeCompare(String(a.at))).slice(0, 20).map((r) => ({ ...r, error: r.error ? safeError(r.error) : null }));
+        db.exec("COMMIT");
+    }
+    catch {
+        // Keep independently completed measurements; each source names its uncertainty.
+    }
+    finally {
+        db?.close();
+    }
+    if (config) {
+        try {
+            const proofs = await readJson(path.join(c.dataDir, "pair-proofs.json"));
+            for (const peer of peers.list ?? [])
+                peer.paired = validPairProof(proofs[peer.agentId], config, peer.agentId, started) ? true : null;
+            peers.measurements.proof = measured(at);
+        }
+        catch { /* No roundtrip evidence: every pairing stays unknown. */ }
+    }
+    const reason = (sources) => Object.entries(sources).filter(([, v]) => v.unknownReason).map(([name, v]) => `${name}:${v.unknownReason}`).join("; ") || null;
+    inbox.unknownReason = reason(inbox.measurements);
+    outbox.unknownReason = reason(outbox.measurements);
+    wake.unknownReason = reason(wake.measurements);
+    peers.unknownReason = reason(peers.measurements);
+    return {
+        schema: "murmur.status/1", generatedAt: at, agentId: config?.agentId ?? null, serviceName: c.serviceName,
+        service: { ...service, lastFailureAt: null, restartsLastHour, restartFailureThreshold: 5,
+            unknownReason: service.state === "unknown" ? service.detail ?? "service.unavailable" : null,
+            measurements: { manager: service.state === "unknown" ? unknown(service.detail ?? "service.unavailable") : measured(at), history: unknown("service.history-unavailable") } },
+        broker: { url: config?.natsUrl ?? null, state: observation?.broker?.state ?? "unknown",
+            connectedAt: observation?.broker?.connectedAt ?? null, lastError: observation?.broker?.lastError ?? null,
+            lastErrorAt: observation?.broker?.lastErrorAt ?? null, unknownReason: runtimeMeasurement.unknownReason,
+            measurements: { runtime: runtimeMeasurement } },
+        peers, inbox, deliveries,
+        outbox: {
+            attention,
+            queue: { pending: outbox.pending, inflight: outbox.inflight, delivered: outbox.delivered,
+                failed: outbox.failed, dlq: outbox.dlq, oldestPendingAt: outbox.oldestPendingAt,
+                unknownReason: outbox.measurements.store.unknownReason },
+            faults: { lastError: outbox.lastError, lastErrorAt: outbox.lastErrorAt,
+                unknownReason: outbox.measurements.store.unknownReason, source: "durable-outbox" },
+        },
+        wake: {
+            config: { enabled: config ? config.wake?.enabled !== false : null,
+                mode: config ? configuredWakeMode(config) : null,
+                responder: config ? configuredWakeMode(config) === "monitor" ? "codex" : config.onReceive ? null : "none" : null,
+                unknownReason: configError },
+            effective: { enabled: wake.enabled,
+                needsRestart: config && typeof wake.enabled === "boolean" ? (config.wake?.enabled !== false) !== wake.enabled : null,
+                observedAt: runtimeMeasurement.measuredAt, unknownReason: runtimeMeasurement.unknownReason },
+            delivery: { pendingUndelivered: wake.pendingUndelivered, storedOnly: wake.storedOnly,
+                lastDeliveredAt: wake.lastDeliveredAt, unknownReason: wake.measurements.store.unknownReason },
+            faults: {
+                lastFault: observation?.wake?.lastFault && (!wake.lastFaultAt || observation.wake.lastFaultAt > wake.lastFaultAt)
+                    ? safeError(observation.wake.lastFault) : wake.lastFault,
+                lastFaultAt: observation?.wake?.lastFault && (!wake.lastFaultAt || observation.wake.lastFaultAt > wake.lastFaultAt)
+                    ? observation.wake.lastFaultAt : wake.lastFaultAt,
+                unknownReason: reason({ store: wake.measurements.store, runtime: runtimeMeasurement }),
+                measurements: { store: wake.measurements.store, runtime: runtimeMeasurement },
+            },
+        },
+    };
+}
+export function configuredWakeMode(config) {
+    return config.wake?.mode === "codex_app_server" || Object.values(config.wake?.peers ?? {}).some(p => p.mode === "codex_app_server")
+        ? "monitor" : config.onReceive ? "hook" : "none";
+}

package/runtime/packages/setup/dist/src/types.d.ts

@@ -0,0 +1,40 @@
+/** Absolute paths resolved by the shared engine, independent of caller cwd. */
+export interface ServiceContext {
+    dataDir: string;
+    configPath: string;
+    storePath: string;
+    repoRoot: string;
+    nodePath: string;
+    logDir: string;
+    serviceName: string;
+}
+export type ServiceManager = "windows-service" | "scheduled-task" | "launchd" | "systemd" | "none";
+export interface ServiceSnapshot {
+    state: "running" | "stopped" | "failed" | "unknown";
+    manager: ServiceManager;
+    since: string | null;
+    pid: number | null;
+    lastExitCode: number | null;
+    /** Observed open database, not a guess from configuration or process arguments. */
+    observedStorePath: string | null;
+    /** Restarts in the stated interval. Null if the platform cannot measure it. */
+    restartCount: number | null;
+    restartWindowMs: number | null;
+    detail?: string;
+}
+export interface ClientDetection {
+    id: "claude-code" | "claude-desktop" | "codex-cli" | "codex-desktop";
+    installed: boolean;
+    configPath: string | null;
+    format: "json" | "toml";
+    detail?: string;
+}
+export interface PlatformAdapter {
+    manager: ServiceManager;
+    status(context: ServiceContext): Promise<ServiceSnapshot>;
+    install(context: ServiceContext): Promise<void>;
+    start(context: ServiceContext): Promise<void>;
+    stop(context: ServiceContext): Promise<void>;
+    uninstall?(context: ServiceContext): Promise<void>;
+    detectClients(context: ServiceContext): Promise<ClientDetection[]>;
+}

package/runtime/packages/setup/dist/src/types.js

@@ -0,0 +1 @@
+export {};

package/runtime/packages/setup/dist/src/updates.d.ts

@@ -0,0 +1,46 @@
+export declare const UPDATE_INTERVAL_MS: number;
+export declare const UPDATE_TIMEOUT_MS = 4000;
+export declare const UPDATE_ENDPOINT = "https://api.github.com/repos/alexfrmn/murmur/releases/latest";
+export declare function compareReleaseVersions(left: string, right: string): number;
+export declare function readVersion(manifest?: URL): Promise<{
+    schema: "murmur.version/1";
+    product: string;
+    version: string;
+    source: "root-package-json";
+    comparison: "declared-release-version";
+}>;
+export interface UpdateResult {
+    schema: 'murmur.updates/1';
+    channel: 'stable';
+    currentVersion: string | null;
+    versionSource: 'root-package-json';
+    comparison: 'declared-release-version';
+    enabled: boolean;
+    state: 'up-to-date' | 'available' | 'unknown';
+    reason: string;
+    latestVersion: string | null;
+    releaseUrl: string | null;
+    action: 'open-release-page' | null;
+    checkedAt: string | null;
+    lastSuccessAt: string | null;
+    nextCheckAt: string | null;
+    cached: boolean;
+    stale: boolean;
+    checkIntervalMs: number;
+    timeoutMs: number;
+}
+type Options = {
+    directory?: string;
+    now?: () => number;
+    fetch?: typeof fetch;
+    manifest?: URL;
+    timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+};
+export declare function updateDirectory(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, home?: string): string;
+export declare function setUpdateChecks(enabled: boolean, options?: Options): Promise<{
+    schema: string;
+    enabled: boolean;
+}>;
+export declare function checkUpdates(options?: Options): Promise<UpdateResult>;
+export {};

package/runtime/packages/setup/dist/src/updates.js

@@ -0,0 +1,284 @@
+import * as fs from 'node:fs/promises';
+import { constants } from 'node:fs';
+import path from 'node:path';
+import { homedir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+export const UPDATE_INTERVAL_MS = 6 * 60 * 60 * 1000;
+export const UPDATE_TIMEOUT_MS = 4000;
+export const UPDATE_ENDPOINT = 'https://api.github.com/repos/alexfrmn/murmur/releases/latest';
+const RELEASE_BASE = 'https://github.com/alexfrmn/murmur/releases/tag/';
+const MAX_BYTES = 128 * 1024;
+const versionPattern = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+function versionParts(value) {
+    if (typeof value !== 'string' || value.length > 100)
+        return null;
+    const match = versionPattern.exec(value);
+    return match ? match.slice(1, 4).map(BigInt) : null;
+}
+export function compareReleaseVersions(left, right) {
+    const a = versionParts(left), b = versionParts(right);
+    if (!a || !b)
+        throw new Error('updates.version-invalid');
+    for (let i = 0; i < 3; i++)
+        if (a[i] !== b[i])
+            return a[i] > b[i] ? 1 : -1;
+    return 0;
+}
+export async function readVersion(manifest = new URL('../../../../package.json', import.meta.url)) {
+    const pkg = JSON.parse(await fs.readFile(manifest, 'utf8'));
+    if (pkg.name !== 'murmur' || !versionParts(pkg.version))
+        throw new Error('version.root-manifest-invalid');
+    return { schema: 'murmur.version/1', product: 'Murmur', version: pkg.version,
+        source: 'root-package-json', comparison: 'declared-release-version' };
+}
+export function updateDirectory(env = process.env, platform = process.platform, home = homedir()) {
+    const paths = platform === 'win32' ? path.win32 : path.posix;
+    const parent = platform === 'win32' ? (env.LOCALAPPDATA || paths.join(home, 'AppData', 'Local'))
+        : platform === 'darwin' ? paths.join(home, 'Library', 'Application Support')
+            : (env.XDG_STATE_HOME || paths.join(home, '.local', 'state'));
+    if (!paths.isAbsolute(parent))
+        throw new Error('updates.state-path-invalid');
+    return paths.join(parent, 'Murmur', 'updates');
+}
+function date(value) {
+    if (typeof value !== 'string')
+        return null;
+    const n = Date.parse(value);
+    return Number.isFinite(n) && new Date(n).toISOString() === value ? n : null;
+}
+async function readJson(file) {
+    let handle;
+    try {
+        if (!(await fs.lstat(file)).isFile())
+            throw new Error('updates.state-invalid');
+        handle = await fs.open(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.size > MAX_BYTES)
+            throw new Error('updates.state-invalid');
+        const buffer = Buffer.alloc(MAX_BYTES + 1);
+        let size = 0;
+        while (size < buffer.length) {
+            const read = await handle.read(buffer, size, buffer.length - size, null);
+            if (read.bytesRead === 0)
+                break;
+            size += read.bytesRead;
+        }
+        if (size > MAX_BYTES)
+            throw new Error('updates.state-invalid');
+        return JSON.parse(buffer.subarray(0, size).toString('utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    finally {
+        await handle?.close();
+    }
+}
+async function prepare(directory) {
+    if (!path.isAbsolute(directory))
+        throw new Error('updates.state-path-invalid');
+    await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+    if (!(await fs.lstat(directory)).isDirectory())
+        throw new Error('updates.state-invalid');
+}
+async function writeJson(directory, name, value) {
+    const temporary = path.join(directory, `.tmp-${randomUUID()}`);
+    try {
+        await fs.writeFile(temporary, JSON.stringify(value) + '\n', { flag: 'wx', mode: 0o600 });
+        await fs.rename(temporary, path.join(directory, name));
+    }
+    finally {
+        await fs.unlink(temporary).catch(() => { });
+    }
+}
+async function preference(directory) {
+    const value = await readJson(path.join(directory, 'preferences.json'));
+    if (value === undefined)
+        return true;
+    if (!value || value.schema !== 'murmur.update-preferences/1' || typeof value.enabled !== 'boolean') {
+        throw new Error('updates.preferences-invalid');
+    }
+    return value.enabled;
+}
+async function lock(directory) {
+    const file = path.join(directory, 'check.lock');
+    try {
+        await fs.mkdir(file);
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        // The request is bounded to four seconds. Recover an abandoned empty lock,
+        // but never wait for another client or let it stall application startup.
+        const stat = await fs.lstat(file);
+        if (!stat.isDirectory() || Date.now() - stat.mtimeMs < 60_000)
+            throw new Error('updates.check-in-progress');
+        await fs.rmdir(file);
+        await fs.mkdir(file);
+    }
+    return async () => { await fs.rmdir(file); };
+}
+export async function setUpdateChecks(enabled, options = {}) {
+    const directory = options.directory ?? updateDirectory(options.env);
+    await prepare(directory);
+    const unlock = await lock(directory);
+    try {
+        const result = { schema: 'murmur.update-preferences/1', enabled };
+        await writeJson(directory, 'preferences.json', result);
+        return result;
+    }
+    finally {
+        await unlock();
+    }
+}
+function validCache(value) {
+    if (!value || value.schema !== 'murmur.update-cache/1' || date(value.checkedAt) === null ||
+        (value.lastSuccessAt !== null && date(value.lastSuccessAt) === null))
+        return false;
+    if (value.reason === 'updates.checked') {
+        return value.lastSuccessAt === value.checkedAt && value.release && versionParts(value.release.version) !== null &&
+            value.release.tag === `v${value.release.version}`;
+    }
+    return value.release === null && ['updates.network-error', 'updates.timeout', 'updates.rate-limited',
+        'updates.http-error', 'updates.release-invalid', 'updates.interrupted'].includes(value.reason);
+}
+async function requestRelease(fetcher, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetcher(UPDATE_ENDPOINT, { signal: controller.signal, redirect: 'error',
+            headers: { Accept: 'application/vnd.github+json', 'X-GitHub-Api-Version': '2022-11-28',
+                'User-Agent': 'Murmur-update-check' } });
+        if (!response.ok) {
+            await response.body?.cancel();
+            throw new Error(response.status === 403 || response.status === 429 ? 'updates.rate-limited' : 'updates.http-error');
+        }
+        if (!response.body)
+            throw new Error('updates.release-invalid');
+        const reader = response.body.getReader();
+        const chunks = [];
+        let size = 0;
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                size += value.byteLength;
+                if (size > MAX_BYTES) {
+                    await reader.cancel();
+                    throw new Error('updates.release-invalid');
+                }
+                chunks.push(value);
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+        let data;
+        try {
+            data = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        }
+        catch {
+            throw new Error('updates.release-invalid');
+        }
+        const version = typeof data.tag_name === 'string' ? data.tag_name.slice(1) : null;
+        if (data.draft !== false || data.prerelease !== false || !versionParts(version) ||
+            data.tag_name !== `v${version}` ||
+            ![RELEASE_BASE + encodeURIComponent(data.tag_name), RELEASE_BASE + data.tag_name].includes(data.html_url) ||
+            typeof data.published_at !== 'string' || !Number.isFinite(Date.parse(data.published_at))) {
+            throw new Error('updates.release-invalid');
+        }
+        return { version: version, tag: data.tag_name };
+    }
+    catch (error) {
+        if (controller.signal.aborted)
+            throw new Error('updates.timeout');
+        if (['updates.rate-limited', 'updates.http-error', 'updates.release-invalid'].includes(error.message))
+            throw error;
+        throw new Error('updates.network-error');
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function checkUpdates(options = {}) {
+    const now = options.now ?? Date.now;
+    const result = { schema: 'murmur.updates/1', channel: 'stable', currentVersion: null,
+        versionSource: 'root-package-json', comparison: 'declared-release-version', enabled: true,
+        state: 'unknown', reason: 'updates.not-checked', latestVersion: null, releaseUrl: null, action: null,
+        checkedAt: null, lastSuccessAt: null, nextCheckAt: null, cached: false, stale: false,
+        checkIntervalMs: UPDATE_INTERVAL_MS, timeoutMs: UPDATE_TIMEOUT_MS };
+    try {
+        result.currentVersion = (await readVersion(options.manifest)).version;
+    }
+    catch {
+        return { ...result, reason: 'updates.current-version-invalid' };
+    }
+    if ((options.env ?? process.env).MURMUR_UPDATE_CHECK === '0')
+        return { ...result, enabled: false, reason: 'updates.disabled' };
+    let directory;
+    try {
+        directory = options.directory ?? updateDirectory(options.env);
+        result.enabled = await preference(directory);
+    }
+    catch {
+        return { ...result, enabled: false, reason: 'updates.preferences-unavailable' };
+    }
+    if (!result.enabled)
+        return { ...result, reason: 'updates.disabled' };
+    let unlock;
+    try {
+        await prepare(directory);
+        unlock = await lock(directory);
+        // Re-read under the cross-process lock: disabling and competing checks cannot
+        // race the decision to initiate the next network request.
+        if (!await preference(directory))
+            return { ...result, enabled: false, reason: 'updates.disabled' };
+        const saved = await readJson(path.join(directory, 'cache.json'));
+        if (saved !== undefined && !validCache(saved))
+            return { ...result, reason: 'updates.cache-invalid' };
+        let cache = saved ?? null;
+        const at = now();
+        if (cache && (date(cache.checkedAt) > at || (cache.lastSuccessAt !== null && date(cache.lastSuccessAt) > date(cache.checkedAt)))) {
+            return { ...result, reason: 'updates.cache-invalid' };
+        }
+        if (cache && at - date(cache.checkedAt) < UPDATE_INTERVAL_MS)
+            result.cached = true;
+        else {
+            result.stale = cache !== null;
+            cache = { schema: 'murmur.update-cache/1', checkedAt: new Date(at).toISOString(),
+                lastSuccessAt: cache?.lastSuccessAt ?? null, release: null, reason: 'updates.interrupted' };
+            // Persist the attempt before fetching. Network failure or a killed client
+            // must not cause every status refresh to hit GitHub again.
+            await writeJson(directory, 'cache.json', cache);
+            try {
+                cache.release = await requestRelease(options.fetch ?? fetch, options.timeoutMs ?? UPDATE_TIMEOUT_MS);
+                cache.reason = 'updates.checked';
+                cache.lastSuccessAt = cache.checkedAt;
+            }
+            catch (error) {
+                cache.reason = error.message;
+            }
+            await writeJson(directory, 'cache.json', cache);
+        }
+        result.checkedAt = cache.checkedAt;
+        result.lastSuccessAt = cache.lastSuccessAt;
+        result.nextCheckAt = new Date(date(cache.checkedAt) + UPDATE_INTERVAL_MS).toISOString();
+        if (!cache.release)
+            return { ...result, reason: cache.reason, stale: cache.lastSuccessAt !== null };
+        const newer = compareReleaseVersions(cache.release.version, result.currentVersion) > 0;
+        return { ...result, stale: false, state: newer ? 'available' : 'up-to-date',
+            reason: newer ? 'updates.newer-release' : 'updates.no-newer-release', latestVersion: cache.release.version,
+            releaseUrl: newer ? RELEASE_BASE + encodeURIComponent(cache.release.tag) : null,
+            action: newer ? 'open-release-page' : null };
+    }
+    catch (error) {
+        return { ...result, state: 'unknown', reason: error.message === 'updates.check-in-progress'
+                ? 'updates.check-in-progress' : 'updates.cache-unavailable' };
+    }
+    finally {
+        await unlock?.().catch(() => { });
+    }
+}

package/runtime/packages/setup/dist/src/verdict.d.ts

@@ -0,0 +1,11 @@
+export interface StatusVerdict {
+    level: "grey" | "red" | "yellow" | "green";
+    unread: boolean;
+    code: string;
+    missing: string[];
+    missingWhy: Record<string, string>;
+}
+/** Shared policy, including 2.11 dead-letter acknowledgement and effective pause. */
+export declare function statusVerdict(input: unknown, now?: number): StatusVerdict;
+/** A failed diagnostic stage prevents later stages from claiming measurements. */
+export declare function doctorChainValid(input: unknown): boolean;