@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/hearth/wake-proxy/config.js

@@ -0,0 +1,151 @@
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { general } from '../../core/errors.js';
+const ENV = {
+    host: 'HEARTH_PROXY_HOST',
+    port: 'HEARTH_PROXY_PORT',
+    publicOrigin: 'HEARTH_PUBLIC_ORIGIN',
+    statePath: 'HEARTH_STATE_PATH',
+    m0RegistryPath: 'CRTR_HEARTH_M0_REGISTRY',
+    ownerToken: 'HEARTH_OWNER_TOKEN',
+    ownerTokenHash: 'HEARTH_OWNER_TOKEN_SHA256',
+    ownerUserId: 'HEARTH_OWNER_USER_ID',
+    defaultTenantId: 'HEARTH_DEFAULT_TENANT_ID',
+    idlePauseMs: 'HEARTH_IDLE_PAUSE_MS',
+    wakeTimeoutMs: 'HEARTH_WAKE_TIMEOUT_MS',
+    readyTimeoutMs: 'HEARTH_READY_TIMEOUT_MS',
+    seedTenantId: 'HEARTH_SEED_TENANT_ID',
+    seedMachineId: 'HEARTH_SEED_MACHINE_ID',
+    seedNodeId: 'HEARTH_SEED_NODE_ID',
+    seedRelayToken: 'HEARTH_SEED_RELAY_TOKEN',
+    seedVolumeId: 'HEARTH_SEED_VOLUME_ID',
+    seedState: 'HEARTH_SEED_STATE',
+    seedWebRoute: 'HEARTH_SEED_WEB_ROUTE',
+};
+function expandHomePath(path) {
+    if (path.startsWith('~'))
+        return join(homedir(), path.slice(1));
+    return resolve(path);
+}
+function parsePort(value, fallback, name) {
+    if (value === undefined || value.trim() === '')
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed <= 0 || parsed > 65535) {
+        throw general(`invalid ${name}: ${value}`, { env: name });
+    }
+    return parsed;
+}
+function parseDuration(value, fallback, name) {
+    if (value === undefined || value.trim() === '')
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 0) {
+        throw general(`invalid ${name}: ${value}`, { env: name });
+    }
+    return parsed;
+}
+function parseRequiredString(env, name) {
+    const value = env[name]?.trim() ?? '';
+    if (value === '')
+        throw general(`${name} is required`, { env: name });
+    return value;
+}
+function normalizeSha256Hash(value) {
+    const trimmed = value.trim();
+    const body = trimmed.startsWith('sha256:') ? trimmed.slice('sha256:'.length) : trimmed;
+    if (!/^[0-9a-fA-F]{64}$/.test(body)) {
+        throw general(`invalid owner token hash`, { env: ENV.ownerTokenHash });
+    }
+    return `sha256:${body.toLowerCase()}`;
+}
+function hashPlaintextToken(token) {
+    return `sha256:${createHash('sha256').update(token, 'utf8').digest('hex')}`;
+}
+function parsePublicOrigin(env, host, port) {
+    const raw = env[ENV.publicOrigin]?.trim() ?? '';
+    if (raw !== '') {
+        const origin = new URL(raw).origin;
+        return { publicOrigin: origin, cookieSecure: origin.startsWith('https://') };
+    }
+    if (host === '127.0.0.1' || host === 'localhost' || host === '::1' || host === '::ffff:127.0.0.1' || host.startsWith('127.')) {
+        const origin = `http://127.0.0.1:${port}`;
+        return { publicOrigin: origin, cookieSecure: false };
+    }
+    throw general(`${ENV.publicOrigin} is required when HEARTH_PROXY_HOST is bound off-loopback`, { env: ENV.publicOrigin, host });
+}
+function parseOwnerHash(env) {
+    const plaintext = env[ENV.ownerToken]?.trim() ?? '';
+    const hash = env[ENV.ownerTokenHash]?.trim() ?? '';
+    if (plaintext === '' && hash === '') {
+        throw general(`${ENV.ownerToken} or ${ENV.ownerTokenHash} is required`, { env: ENV.ownerToken });
+    }
+    if (plaintext !== '' && hash !== '') {
+        const derived = hashPlaintextToken(plaintext);
+        const normalized = normalizeSha256Hash(hash);
+        if (derived !== normalized) {
+            throw general(`owner token and owner token hash do not match`, { env: ENV.ownerTokenHash });
+        }
+        return normalized;
+    }
+    if (hash !== '')
+        return normalizeSha256Hash(hash);
+    return hashPlaintextToken(plaintext);
+}
+function parseSeedHome(env, defaultTenantId) {
+    const machineId = env[ENV.seedMachineId]?.trim() ?? '';
+    const nodeId = env[ENV.seedNodeId]?.trim() ?? '';
+    const relayToken = env[ENV.seedRelayToken]?.trim() ?? '';
+    const volumeId = env[ENV.seedVolumeId]?.trim() ?? '';
+    const tenantId = env[ENV.seedTenantId]?.trim() || defaultTenantId;
+    const anyPresent = machineId !== '' || nodeId !== '' || relayToken !== '' || volumeId !== '' || (env[ENV.seedState]?.trim() ?? '') !== '' || (env[ENV.seedWebRoute]?.trim() ?? '') !== '';
+    if (!anyPresent)
+        return null;
+    if (machineId === '' || nodeId === '' || relayToken === '' || volumeId === '') {
+        throw general(`HEARTH_SEED_MACHINE_ID, HEARTH_SEED_NODE_ID, HEARTH_SEED_RELAY_TOKEN, and HEARTH_SEED_VOLUME_ID are required together when seeding a new home — run the existing M0 provision/bootstrap/relay flow first`, {
+            envs: [ENV.seedMachineId, ENV.seedNodeId, ENV.seedRelayToken, ENV.seedVolumeId],
+        });
+    }
+    const seedState = (env[ENV.seedState]?.trim() || 'running');
+    const webRouteUrl = env[ENV.seedWebRoute]?.trim() ?? '';
+    return {
+        tenantId,
+        machineId,
+        nodeId,
+        relayToken,
+        volumeId,
+        state: seedState,
+        webRouteUrl: webRouteUrl === '' ? null : webRouteUrl,
+    };
+}
+export function loadHearthProxyConfig(env = process.env) {
+    const host = (env[ENV.host] ?? '0.0.0.0').trim() || '0.0.0.0';
+    const port = parsePort(env[ENV.port], 8080, ENV.port);
+    const { publicOrigin, cookieSecure } = parsePublicOrigin(env, host, port);
+    const statePath = expandHomePath(env[ENV.statePath] ?? '/data/hearth-proxy.json');
+    const m0RegistryPath = expandHomePath(env[ENV.m0RegistryPath] ?? '/data/homes.json');
+    const ownerUserId = (env[ENV.ownerUserId] ?? 'silas').trim() || 'silas';
+    const defaultTenantFallback = (env[ENV.defaultTenantId] ?? ownerUserId).trim() || ownerUserId;
+    const ownerTokenHash = parseOwnerHash(env);
+    const idlePauseMs = parseDuration(env[ENV.idlePauseMs], 10 * 60_000, ENV.idlePauseMs);
+    const wakeTimeoutMs = parseDuration(env[ENV.wakeTimeoutMs], 150_000, ENV.wakeTimeoutMs);
+    const readyTimeoutMs = parseDuration(env[ENV.readyTimeoutMs], 30_000, ENV.readyTimeoutMs);
+    const seedHome = parseSeedHome(env, defaultTenantFallback);
+    const defaultTenantId = seedHome?.tenantId ?? defaultTenantFallback;
+    return {
+        host,
+        port,
+        publicOrigin,
+        statePath,
+        m0RegistryPath,
+        ownerUserId,
+        defaultTenantId,
+        ownerTokenHash,
+        idlePauseMs,
+        wakeTimeoutMs,
+        readyTimeoutMs,
+        cookieSecure,
+        seedHome,
+    };
+}

package/dist/hearth/wake-proxy/guest-source.d.ts

@@ -0,0 +1,14 @@
+import type { RawResponse, SourceRequest } from '../../core/view/contract.js';
+import type { ActivityHandle, AwakenedHome, TenantActivitySnapshot } from './types.js';
+export interface GuestSourceDeps {
+    ensureAwake?: (tenantId: string) => Promise<AwakenedHome>;
+    fetch?: typeof fetch;
+    acquireActivity?: (tenantId: string) => ActivityHandle;
+    releaseActivity?: (handle: ActivityHandle) => TenantActivitySnapshot;
+    wakeTimeoutMs?: number;
+    bridgeTimeoutMs?: number;
+    now?: () => number;
+    redact?: (message: string) => string;
+}
+export declare function runGuestSource(tenantId: string, request: SourceRequest, deps?: GuestSourceDeps): Promise<RawResponse>;
+export declare function requireSuccessfulExec<T extends RawResponse>(raw: T, label: string): T;

package/dist/hearth/wake-proxy/guest-source.js

@@ -0,0 +1,130 @@
+import { general } from '../../core/errors.js';
+import { acquireActivity as acquireWakeActivity, ensureAwake as ensureTenantAwake, releaseActivity as releaseWakeActivity } from './home.js';
+import { redactWakeProxyMessage } from './redact.js';
+const SECRET_FIELD_JSON_RE = /"(?:access_token|refresh_token|code_verifier|access|refresh|code|state)"\s*:\s*"[^"]*"/gi;
+const SECRET_FIELD_ASSIGN_RE = /\b(?:access_token|refresh_token|code_verifier|access|refresh|code|state)\b\s*[:=]\s*[^\s,&}]+/gi;
+const SECRET_QUERY_RE = /([?&](?:access_token|refresh_token|access|refresh|code|state|code_verifier)=)[^&#\s]+/gi;
+const DEFAULT_TIMEOUT_MS = 30_000;
+function withTimeout(work, timeoutMs, label, now) {
+    if (timeoutMs <= 0)
+        return work;
+    let timer = null;
+    const startedAt = now();
+    return Promise.race([
+        work,
+        new Promise((_, reject) => {
+            timer = setTimeout(() => {
+                reject(general(`${label} timed out`, { timeoutMs, startedAt: new Date(startedAt).toISOString() }));
+            }, timeoutMs);
+            timer.unref();
+        }),
+    ]).finally(() => {
+        if (timer !== null)
+            clearTimeout(timer);
+    });
+}
+function redactGuestSourceMessage(message) {
+    return redactWakeProxyMessage(message)
+        .replace(SECRET_FIELD_JSON_RE, '"[redacted]"')
+        .replace(SECRET_FIELD_ASSIGN_RE, '[redacted]')
+        .replace(SECRET_QUERY_RE, '$1[redacted]');
+}
+function normalizeFailure(message, redact) {
+    return { ok: false, stdout: '', stderr: redact(message) };
+}
+function parseRawResponse(text) {
+    try {
+        const parsed = JSON.parse(text);
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+            return null;
+        if (typeof parsed.ok !== 'boolean' || typeof parsed.stdout !== 'string' || typeof parsed.stderr !== 'string')
+            return null;
+        if ('exitCode' in parsed && parsed.exitCode !== undefined && typeof parsed.exitCode !== 'number')
+            return null;
+        if ('status' in parsed && parsed.status !== undefined && typeof parsed.status !== 'number')
+            return null;
+        return {
+            ok: parsed.ok,
+            stdout: parsed.stdout,
+            stderr: parsed.stderr,
+            ...(typeof parsed.exitCode === 'number' ? { exitCode: parsed.exitCode } : {}),
+            ...(typeof parsed.status === 'number' ? { status: parsed.status } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+async function fetchRawResponse(url, request, relayToken, deps) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => {
+        controller.abort(new Error('guest source bridge timed out'));
+    }, deps.bridgeTimeoutMs);
+    timeout.unref();
+    try {
+        const response = await deps.fetch(url, {
+            method: 'POST',
+            headers: {
+                authorization: `Bearer ${relayToken}`,
+                'content-type': 'application/json',
+            },
+            body: JSON.stringify(request),
+            signal: controller.signal,
+        });
+        const body = await response.text();
+        if (!response.ok) {
+            return normalizeFailure(`guest source bridge returned HTTP ${response.status} ${response.statusText}${body.trim() === '' ? '' : `: ${body}`}`, deps.redact);
+        }
+        const raw = parseRawResponse(body);
+        if (raw === null) {
+            return normalizeFailure(`guest source bridge returned invalid RawResponse JSON${body.trim() === '' ? '' : `: ${body}`}`, deps.redact);
+        }
+        return raw;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return normalizeFailure(message, deps.redact);
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+export async function runGuestSource(tenantId, request, deps = {}) {
+    const now = deps.now ?? Date.now;
+    const redact = deps.redact ?? redactGuestSourceMessage;
+    const ensureAwake = deps.ensureAwake ?? ensureTenantAwake;
+    const fetchImpl = deps.fetch ?? fetch;
+    const acquireActivity = deps.acquireActivity ?? acquireWakeActivity;
+    const releaseActivity = deps.releaseActivity ?? releaseWakeActivity;
+    const wakeTimeoutMs = deps.wakeTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const bridgeTimeoutMs = deps.bridgeTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const activity = acquireActivity(tenantId);
+    let awakened = null;
+    try {
+        awakened = await withTimeout(ensureAwake(tenantId), wakeTimeoutMs, 'guest wake', now);
+        const upstream = new URL('/__crtr/source', awakened.routeUrl);
+        return await fetchRawResponse(upstream, request, awakened.relayToken, { fetch: fetchImpl, bridgeTimeoutMs, now, redact });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return normalizeFailure(message, redact);
+    }
+    finally {
+        releaseActivity(activity);
+    }
+}
+export function requireSuccessfulExec(raw, label) {
+    if (!raw.ok) {
+        throw general(`${label} failed`, { error: redactGuestSourceMessage(raw.stderr || `${label} transport failed`), exitCode: raw.exitCode ?? null });
+    }
+    if (typeof raw.exitCode !== 'number') {
+        throw general(`${label} failed`, { error: `${label} did not return an exit code`, exitCode: null });
+    }
+    if (raw.exitCode !== 0) {
+        throw general(`${label} failed`, { error: redactGuestSourceMessage(raw.stderr || `${label} exited ${raw.exitCode}`), exitCode: raw.exitCode });
+    }
+    if (raw.stderr.trim() !== '') {
+        throw general(`${label} failed`, { error: redactGuestSourceMessage(raw.stderr), exitCode: raw.exitCode });
+    }
+    return raw;
+}

package/dist/hearth/wake-proxy/hearth-status.d.ts

@@ -0,0 +1,44 @@
+import type { MachineRef } from '../../core/hearth/types.js';
+import { runGuestSource } from './guest-source.js';
+import type { HearthWakeProxyRuntime } from './types.js';
+export interface HearthMachineResources {
+    cpuCount: number | null;
+    memoryMB: number | null;
+}
+export interface HearthRuntimeStats {
+    cpuPct: number | null;
+    memoryUsedMB: number | null;
+    memoryAvailableMB: number | null;
+    crtrRssKB: number | null;
+    piRssKB: number | null;
+    nodeRssKB: number | null;
+    totalRssKB: number | null;
+    capturedAt: string | null;
+    staleMs: number | null;
+}
+export interface HearthStatusResponse {
+    tenantId: string;
+    machineIdSuffix: string | null;
+    nodeId: string | null;
+    routeHost: string | null;
+    homeState: string | null;
+    activeCounts: {
+        http: number;
+        ws: number;
+        wake: number;
+    };
+    activeTotal: number;
+    idleDeadlineAt: string | null;
+    lastActivityAt: string | null;
+    lastWakeAt: string | null;
+    lastPauseAt: string | null;
+    machineResources: HearthMachineResources | null;
+    runtimeStats: HearthRuntimeStats | null;
+}
+export interface HearthStatusDeps {
+    getMachine?: (machineId: string) => Promise<MachineRef | null>;
+    guestSource?: typeof runGuestSource;
+    fetch?: typeof fetch;
+    now?: () => number;
+}
+export declare function loadHearthStatus(tenantId: string, runtime: HearthWakeProxyRuntime, deps?: HearthStatusDeps): Promise<HearthStatusResponse>;

package/dist/hearth/wake-proxy/hearth-status.js

@@ -0,0 +1,267 @@
+import { getHomeBackend } from '../../core/hearth/provider.js';
+import { ensureProxyState, getTenantActivitySnapshot, loadProxyState, readTenantHome } from './state.js';
+const RESOURCE_PROBE_TIMEOUT_MS = 5_000;
+function resourceProbeScript() {
+    return `import { readdir, readFile } from 'node:fs/promises';
+import { setTimeout as sleep } from 'node:timers/promises';
+
+function numberOrNull(value) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+function parseKb(value) {
+  if (typeof value !== 'string') return null;
+  const match = value.trim().match(/^(\d+)\s+kB$/i);
+  return match === null ? null : Number(match[1]);
+}
+
+function parseMemInfo(text) {
+  const entries = new Map();
+  for (const line of text.split('\n')) {
+    const match = line.match(/^([^:]+):\s*(\d+)\s+kB$/i);
+    if (match !== null) entries.set(match[1], Number(match[2]));
+  }
+  const total = entries.get('MemTotal') ?? null;
+  const available = entries.get('MemAvailable') ?? entries.get('MemFree') ?? null;
+  return {
+    memoryUsedMB: total !== null && available !== null ? Math.max(0, Math.round((total - available) / 1024)) : null,
+    memoryAvailableMB: available !== null ? Math.max(0, Math.round(available / 1024)) : null,
+  };
+}
+
+async function sampleCpu() {
+  const read = async () => {
+    const line = (await readFile('/proc/stat', 'utf8')).split('\n', 1)[0] ?? '';
+    const values = line.trim().split(/\s+/).slice(1).map((value) => Number(value));
+    if (values.length === 0 || values.some((value) => !Number.isFinite(value))) return null;
+    const idle = (values[3] ?? 0) + (values[4] ?? 0);
+    const total = values.reduce((sum, value) => sum + value, 0);
+    return { idle, total };
+  };
+  const first = await read();
+  if (first === null) return null;
+  await sleep(200);
+  const second = await read();
+  if (second === null) return null;
+  const total = second.total - first.total;
+  if (total <= 0) return null;
+  const idle = second.idle - first.idle;
+  return Math.max(0, Math.min(100, Math.round(((total - idle) / total) * 1000) / 10));
+}
+
+function parseVmRss(statusText) {
+  const match = statusText.match(/^VmRSS:\s*(\d+)\s*kB$/mi);
+  return match === null ? null : Number(match[1]);
+}
+
+function classifyProcess(comm, cmdline) {
+  const text = comm + '\n' + cmdline;
+  if (/\b(?:node_modules\/(?:\.bin\/)?pi|(?:^|\/)pi)(?:\b|$)/i.test(text)) return 'pi';
+  if (/\b(?:crtr|dist\/cli\.js|bin\/crtr)(?:\b|$)/i.test(text)) return 'crtr';
+  if (/\bnode(?:\.js)?\b/i.test(text)) return 'node';
+  return null;
+}
+
+async function sampleRss() {
+  const totals = { crtrRssKB: null, piRssKB: null, nodeRssKB: null, totalRssKB: null };
+  let crtr = 0;
+  let pi = 0;
+  let node = 0;
+  try {
+    const entries = await readdir('/proc', { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory() || !/^\d+$/.test(entry.name)) continue;
+      const pid = entry.name;
+      try {
+        const [comm, cmdline, status] = await Promise.all([
+          readFile('/proc/' + pid + '/comm', 'utf8').catch(() => ''),
+          readFile('/proc/' + pid + '/cmdline', 'utf8').catch(() => ''),
+          readFile('/proc/' + pid + '/status', 'utf8').catch(() => ''),
+        ]);
+        const rss = parseVmRss(status);
+        const kind = classifyProcess(comm.trim(), cmdline.replaceAll('\0', ' ').trim());
+        if (rss === null || kind === null) continue;
+        if (kind === 'crtr') crtr += rss;
+        else if (kind === 'pi') pi += rss;
+        else if (kind === 'node') node += rss;
+      } catch {
+        /* ignore per-process probe failures */
+      }
+    }
+  } catch {
+    return totals;
+  }
+  totals.crtrRssKB = crtr > 0 ? crtr : null;
+  totals.piRssKB = pi > 0 ? pi : null;
+  totals.nodeRssKB = node > 0 ? node : null;
+  const total = crtr + pi + node;
+  totals.totalRssKB = total > 0 ? total : null;
+  return totals;
+}
+
+const [cpuPct, mem, rss] = await Promise.all([
+  sampleCpu().catch(() => null),
+  readFile('/proc/meminfo', 'utf8').then(parseMemInfo).catch(() => ({ memoryUsedMB: null, memoryAvailableMB: null })),
+  sampleRss().catch(() => ({ crtrRssKB: null, piRssKB: null, nodeRssKB: null, totalRssKB: null })),
+]);
+
+console.log(JSON.stringify({
+  cpuPct,
+  memoryUsedMB: mem.memoryUsedMB,
+  memoryAvailableMB: mem.memoryAvailableMB,
+  crtrRssKB: rss.crtrRssKB,
+  piRssKB: rss.piRssKB,
+  nodeRssKB: rss.nodeRssKB,
+  totalRssKB: rss.totalRssKB,
+  capturedAt: new Date().toISOString(),
+}));`;
+}
+function parseNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+function parseRuntimeStats(raw, now) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+        return null;
+    const record = parsed;
+    const capturedAt = typeof record.capturedAt === 'string' && record.capturedAt.trim() !== '' ? record.capturedAt : null;
+    const staleMs = capturedAt === null ? null : Math.max(0, now() - Date.parse(capturedAt));
+    const stats = {
+        cpuPct: parseNumber(record.cpuPct),
+        memoryUsedMB: parseNumber(record.memoryUsedMB),
+        memoryAvailableMB: parseNumber(record.memoryAvailableMB),
+        crtrRssKB: parseNumber(record.crtrRssKB),
+        piRssKB: parseNumber(record.piRssKB),
+        nodeRssKB: parseNumber(record.nodeRssKB),
+        totalRssKB: parseNumber(record.totalRssKB),
+        capturedAt,
+        staleMs: Number.isFinite(staleMs) ? staleMs : null,
+    };
+    return Object.values(stats).every((value) => value === null) ? null : stats;
+}
+function parseRawResponse(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+            return null;
+        if (typeof parsed.ok !== 'boolean' || typeof parsed.stdout !== 'string' || typeof parsed.stderr !== 'string')
+            return null;
+        if ('exitCode' in parsed && parsed.exitCode !== undefined && typeof parsed.exitCode !== 'number')
+            return null;
+        return {
+            ok: parsed.ok,
+            stdout: parsed.stdout,
+            stderr: parsed.stderr,
+            ...(typeof parsed.exitCode === 'number' ? { exitCode: parsed.exitCode } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function runtimeProbeRequest(cwd) {
+    return {
+        kind: 'exec',
+        bin: 'node',
+        args: ['--input-type=module', '-e', resourceProbeScript()],
+        cwd,
+    };
+}
+async function loadMachineResources(runtime, tenantId, deps) {
+    const home = readTenantHome(runtime.proxy, tenantId);
+    if (home === null)
+        return null;
+    const getMachine = deps.getMachine ?? (async (machineId) => {
+        const backend = getHomeBackend(runtime.m0);
+        return await backend.getMachine(machineId);
+    });
+    try {
+        const machine = await getMachine(home.machineId);
+        if (machine === null || machine.raw === null || typeof machine.raw !== 'object' || Array.isArray(machine.raw))
+            return null;
+        const raw = machine.raw;
+        const cpuCount = parseNumber(raw.cpuCount);
+        const memoryMB = parseNumber(raw.memoryMB);
+        return cpuCount === null && memoryMB === null ? null : { cpuCount, memoryMB };
+    }
+    catch {
+        return null;
+    }
+}
+async function loadRuntimeStats(runtime, tenantId, deps) {
+    const home = readTenantHome(runtime.proxy, tenantId);
+    if (home === null || home.state !== 'running')
+        return null;
+    const routeUrl = home.webRoute?.concreteUrl ?? home.webRoute?.url ?? null;
+    const relayToken = home.relayToken ?? null;
+    if (routeUrl === null || relayToken === null || routeUrl.trim() === '' || relayToken.trim() === '')
+        return null;
+    const fetchImpl = deps.fetch ?? fetch;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(new Error('runtime stats probe timed out')), RESOURCE_PROBE_TIMEOUT_MS);
+    timeout.unref();
+    try {
+        const response = await fetchImpl(new URL('/__crtr/source', routeUrl), {
+            method: 'POST',
+            headers: {
+                authorization: `Bearer ${relayToken}`,
+                'content-type': 'application/json',
+            },
+            body: JSON.stringify(runtimeProbeRequest(runtime.m0.guestCodePath)),
+            signal: controller.signal,
+        });
+        if (!response.ok)
+            return null;
+        const raw = parseRawResponse(await response.text());
+        if (raw === null || !raw.ok || typeof raw.exitCode !== 'number' || raw.exitCode !== 0 || raw.stdout.trim() === '')
+            return null;
+        return parseRuntimeStats(raw.stdout, deps.now ?? Date.now);
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+export async function loadHearthStatus(tenantId, runtime, deps = {}) {
+    const proxyState = loadProxyState(runtime.proxy.statePath) ?? ensureProxyState(runtime.proxy);
+    const tenantState = proxyState.tenants[tenantId] ?? null;
+    const home = readTenantHome(runtime.proxy, tenantId);
+    const activity = getTenantActivitySnapshot(tenantId);
+    const [machineResources, runtimeStats] = await Promise.all([
+        loadMachineResources(runtime, tenantId, deps),
+        loadRuntimeStats(runtime, tenantId, deps),
+    ]);
+    const routeUrl = home?.webRoute?.concreteUrl ?? home?.webRoute?.url ?? null;
+    let routeHost = null;
+    if (routeUrl !== null) {
+        try {
+            routeHost = new URL(routeUrl).host;
+        }
+        catch {
+            routeHost = null;
+        }
+    }
+    return {
+        tenantId,
+        machineIdSuffix: home?.machineId ? home.machineId.slice(-6) : null,
+        nodeId: home?.nodeId ?? null,
+        routeHost,
+        homeState: home?.state ?? null,
+        activeCounts: activity.counts,
+        activeTotal: activity.total,
+        idleDeadlineAt: activity.idleDeadlineAt,
+        lastActivityAt: tenantState?.lastActivityAt ?? null,
+        lastWakeAt: tenantState?.lastWakeAt ?? null,
+        lastPauseAt: tenantState?.lastPauseAt ?? null,
+        machineResources,
+        runtimeStats,
+    };
+}

package/dist/hearth/wake-proxy/home.d.ts

@@ -0,0 +1,61 @@
+import { touchTenantWake } from './state.js';
+import type { ActivityHandle, ActivityKind, AwakenedHome, HearthWakeProxyRuntime, TenantActivitySnapshot } from './types.js';
+export declare function configureWakeProxyRuntime(next: HearthWakeProxyRuntime): void;
+declare function probeRelayReady(routeUrl: string, relayToken: string): Promise<boolean>;
+/**
+ * Retry the cheap single-shot relay probe until it confirms the route is serving or `windowMs`
+ * elapses, returning a boolean. Always runs at least one attempt. This is the reliable answer to
+ * "is the relay serving right now?" — a single shot mistakes a slow first connection for a dead
+ * route. Both the fast-path short-circuit and `waitForRelayReady` build on it.
+ */
+declare function probeRelayServing(routeUrl: string, relayToken: string, windowMs: number): Promise<boolean>;
+declare function waitForRelayReady(routeUrl: string, relayToken: string): Promise<void>;
+declare function captureAwakeHome(tenantId: string): AwakenedHome;
+/**
+ * Cheap, non-throwing route selection for the HTTP fast path: return the persisted home as an
+ * `AwakenedHome` ONLY when it is recorded `running` with a usable webRoute + relayToken. Does NO
+ * probe, takes NO lock, and never wakes — the actual upstream forward is the liveness check.
+ * Returns null when the home is missing, not running, or missing a route/token, so the caller
+ * falls back to the deliberate `ensureAwake` wake/restore path. This is the one authoritative
+ * place that turns "a known-running home" into a forwardable route without the heavy gate.
+ */
+export declare function resolveRunningHome(tenantId: string): AwakenedHome | null;
+/** Wake the tenant's home through the configured backend seam and persist returned pointers. */
+declare function wakeHome(tenantId: string): Promise<void>;
+export declare const wakeProxyInternals: {
+    probeRelayReady: typeof probeRelayReady;
+    probeRelayServing: typeof probeRelayServing;
+    waitForRelayReady: typeof waitForRelayReady;
+    captureAwakeHome: typeof captureAwakeHome;
+    resolveRunningHome: typeof resolveRunningHome;
+    wakeHome: typeof wakeHome;
+    touchTenantWake: typeof touchTenantWake;
+    now: () => number;
+};
+/**
+ * Drop the cached warm verdict for a tenant so the next `ensureAwake` re-probes (or wakes) instead
+ * of trusting a stale "serving" answer. The proxy calls this when an upstream forward fails, so a
+ * home that died mid-TTL is re-checked on the next request rather than serving 502s for the rest of
+ * the window.
+ */
+export declare function invalidateWarmVerdict(tenantId: string): void;
+/** Clear all warm verdicts and in-flight wake coalescing. Used on runtime (re)configuration. */
+export declare function resetWakeProxyMemory(): void;
+export declare function acquireActivity(tenantId: string, kind?: ActivityKind): ActivityHandle;
+export declare function releaseActivity(handle: ActivityHandle): TenantActivitySnapshot;
+export declare function scheduleIdlePause(tenantId: string): void;
+/**
+ * Pause the tenant's home through the backend seam. We never drive a sandbox SDK directly here —
+ * the backend returns provider pointer/state changes and this layer persists them. Serialized under the per-tenant
+ * in-process lock; the single-process deployment invariant (one wake-proxy machine per tenant)
+ * makes this lock authoritative.
+ */
+export declare function pauseNow(tenantId: string): Promise<void>;
+/**
+ * Ensure the tenant's home is awake. First probe an already-serving relay; when that succeeds,
+ * reconcile the registry state if needed, touch wake, and return the existing route. Otherwise,
+ * wake the guest through the backend seam, wait for readiness, touch wake, and return an
+ * `AwakenedHome` the proxy can forward to. Serialized under the per-tenant in-process lock.
+ */
+export declare function ensureAwake(tenantId: string): Promise<AwakenedHome>;
+export {};