@crouton-kit/crouter 0.3.40 → 0.3.42

package/dist/hearth/control-plane/wake.js

@@ -1,550 +0,0 @@
-// control-plane/wake.ts — CP wake orchestration (P4.2 / part-plan T3.1).
-//
-// Generalizes M0 `wake-proxy/home.ts` (`ensureAwake`/`resolveRunningHome`/
-// `probeRelayServing`) onto the CP `home` registry, with one deliberate
-// behavior drop: NO idle-pause machinery (S3 — the provider owns
-// idle->suspend; M0's `scheduleIdlePause`/`pauseNow` timer chain is not
-// reproduced here, by design, not oversight).
-//
-// Pipeline (R-WAKE-1): read the `home` row -> resolve the relay token handle
-// -> call the provider wake/resume seam (`HomeBackend.wake`, owned by the
-// home/provider slice, IP-1) -> ready-probe the in-guest web server on
-// `/node/<home_agent_target>` over a short retried window, carrying the
-// relay token -> if the provider returned a new sandbox/preview (a
-// recreate), persist the refreshed pointers; `home_agent_target` is NEVER
-// part of that patch (R-WAKE-6 — `refreshProviderPointers` doesn't accept it)
-// -> record wake/ready timing -> return the route. Readiness here means the
-// guest web server answers `/node/<target>` AND relays to a live broker
-// `view.sock` (R-WAKE-2 — not "the SPA shell renders"). `src/clients/web/
-// server.ts` only proves that second half on a WS upgrade: `bridgeConnection`
-// opens `view.sock` AFTER the 101 response and closes the socket with 1011
-// the instant that fails (ECONNREFUSED/ENOENT — "no running broker"), so an
-// HTTP GET 200 on `/node/<target>` (the SPA static/fallback route) proves
-// only that the guest web server is up, not that the broker is. The probe
-// therefore opens a real WebSocket to `/node/<target>` and requires a
-// successful upgrade that SURVIVES a short settle window (or yields a first
-// frame) before declaring readiness.
-//
-// All timers used during a probe retry window are cleared before the
-// function that started them returns — there is no `setTimeout`/`setInterval`
-// left armed once `ensureAwake`/`resolveRunning` resolve (S3 regression bar).
-import { setTimeout as delay } from 'node:timers/promises';
-import { WebSocket } from 'ws';
-import { general } from '../../core/errors.js';
-import { hearthHomeImageRefForVersion, loadM0Config } from '../../core/hearth/config.js';
-import { getHomeBackend } from '../../core/hearth/provider.js';
-import { loadControlPlaneConfig } from './config.js';
-import { getHearthTarget, recordBadTarget } from './hearth-target.js';
-import { getHomeById, refreshProviderPointers, setHealthVerdict, setHomeStatus, touchReady, touchWake } from './registry.js';
-import { isHomeServing as isHomeServingNow } from './serving.js';
-import { resolveSecret } from './secrets.js';
-// Individual probe attempt timeout — bounded short so a dead route fails
-// fast and the retry loop gets multiple attempts inside the overall window,
-// rather than one attempt eating the whole window (mirrors M0's
-// `READY_PROBE_TIMEOUT_MS`).
-const READY_PROBE_ATTEMPT_TIMEOUT_MS = 1_500;
-// Backoff between probe attempts (Q1: "500ms backoff between attempts").
-const READY_PROBE_BACKOFF_MS = 500;
-// How long a confirmed-ready verdict is trusted before `resolveRunning`/
-// `ensureAwake` re-checks instead of trusting a stale answer (Q1: "10s TTL,
-// in-process"). Single CP process, no distributed cache (S2).
-const WARM_VERDICT_TTL_MS = 10_000;
-/** Normalize a provider-observed runtime status into the CP `HomeStatus`
- *  vocabulary before it is ever persisted (Q3 / P3.4 review Minor finding):
- *  the provider's `MachineState` is broad (and may include future
- *  pause/suspend/standby spellings the SDK doesn't expose yet); CP's
- *  `HomeStatus` enum does not have a `'paused'` member. Anything
- *  pause/suspend/standby-shaped collapses to `'suspended'`; an exact
- *  `'running'` passes through; everything else (provisioning, terminating,
- *  terminated, restoring, unrecognized) becomes `'unknown'` rather than
- *  guessing a more specific CP status from a provider-specific string. */
-export function normalizeProviderStatus(providerStatus) {
-    if (providerStatus === null || providerStatus === undefined)
-        return 'unknown';
-    const normalized = providerStatus.trim().toLowerCase();
-    if (normalized === 'paused' || normalized === 'suspended' || normalized === 'standby')
-        return 'suspended';
-    if (normalized === 'running')
-        return 'running';
-    return 'unknown';
-}
-function requireHomeField(value, field, home_id) {
-    if (value === null || value === undefined || (typeof value === 'string' && value.trim() === '')) {
-        throw general(`home ${home_id} is missing ${field} — cannot wake`, { home_id, field });
-    }
-    return value;
-}
-function buildDescriptor(home, relayToken) {
-    return {
-        homeId: home.home_id,
-        tenantId: home.tenant_id,
-        userId: home.user_id,
-        providerName: home.provider,
-        providerSandboxId: requireHomeField(home.provider_sandbox_id, 'provider_sandbox_id', home.home_id),
-        providerVolumeId: requireHomeField(home.provider_volume_id, 'provider_volume_id', home.home_id),
-        previewEndpoint: home.preview_endpoint,
-        homeAgentTarget: requireHomeField(home.home_agent_target, 'home_agent_target', home.home_id),
-        relayAuthRef: home.relay_auth_ref,
-        relayToken,
-        status: home.status,
-        templateVersion: home.template_version,
-    };
-}
-// After a successful 101 upgrade, `bridgeConnection` (server.ts) still has to
-// dial the broker's `view.sock` and can close the socket (1011, "no running
-// broker") the instant that dial fails. That happens fast on a local unix
-// socket (ECONNREFUSED/ENOENT are immediate), so a settle window this short
-// is enough to let a dead-broker close win the race against a false-positive
-// `open` before the probe declares readiness.
-const READY_PROBE_WS_SETTLE_MS = 300;
-function wsUrlForNode(previewEndpoint, target) {
-    const url = new URL(`/node/${encodeURIComponent(target)}`, previewEndpoint);
-    url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
-    return url;
-}
-/** One bounded attempt: open a WebSocket to `/node/<target>` carrying the
- *  relay token and require the upgrade to both succeed AND survive a short
- *  settle window (or yield a first frame) within `attemptTimeoutMs` — proof
- *  the in-guest web server answered AND relayed to a live broker `view.sock`
- *  (R-WAKE-2), not just that the SPA shell route is up. Every branch
- *  (success, handshake rejection, error, premature close, attempt timeout)
- *  closes the socket and resolves exactly once — a success closes gracefully
- *  (code 1000) so the guest relay does not record a false fault, anything
- *  else terminates it. */
-async function probeNodeOnce(previewEndpoint, target, relayToken, attemptTimeoutMs) {
-    return new Promise((resolveProbe) => {
-        let settled = false;
-        let settleTimer = null;
-        let ws;
-        try {
-            ws = new WebSocket(wsUrlForNode(previewEndpoint, target), {
-                headers: { authorization: `Bearer ${relayToken}` },
-                perMessageDeflate: false,
-            });
-        }
-        catch {
-            resolveProbe(false);
-            return;
-        }
-        const finish = (ready) => {
-            if (settled)
-                return;
-            settled = true;
-            if (settleTimer !== null)
-                clearTimeout(settleTimer);
-            clearTimeout(attemptTimer);
-            try {
-                // A confirmed-ready probe closes gracefully (code 1000) so the guest
-                // relay's `bridgeConnection` sees a normal browser close and does NOT
-                // record a false browser<->relay fault (P4.2 re-review Major). `close()`
-                // sends the close frame synchronously off the OPEN socket, so resolving
-                // right after calling it still delivers a normal close to the guest —
-                // the probe does not need to wait for the closing handshake to finish.
-                // Failure/timeout/error paths still abort hard via `terminate()`: there
-                // is nothing graceful to negotiate when the socket never proved ready.
-                if (ready) {
-                    ws.close(1000, 'readiness probe complete');
-                }
-                else {
-                    ws.terminate();
-                }
-            }
-            catch {
-                /* ignore */
-            }
-            resolveProbe(ready);
-        };
-        const attemptTimer = setTimeout(() => finish(false), attemptTimeoutMs);
-        ws.once('open', () => {
-            // The attempt timer (above) still bounds the total wait, so it is safe
-            // to always arm the full settle window here — whichever timer fires
-            // first wins via `finish`'s once-only guard.
-            settleTimer = setTimeout(() => finish(true), Math.min(READY_PROBE_WS_SETTLE_MS, attemptTimeoutMs));
-        });
-        ws.once('message', () => finish(true));
-        ws.once('unexpected-response', () => finish(false));
-        ws.once('error', () => finish(false));
-        ws.once('close', () => finish(false));
-    });
-}
-/** Retry the single-shot probe until it confirms `/node/<target>` is serving
- *  or `windowMs` elapses. Always runs at least one attempt (R-WAKE-1: "a
- *  single failed probe does not abort"). Every timer this loop starts
- *  (the per-attempt abort timeout, the inter-attempt backoff) is cleared/
- *  resolved before the loop returns — nothing is left armed. */
-async function probeNodeReady(previewEndpoint, target, relayToken, windowMs) {
-    const deadline = Date.now() + Math.max(0, windowMs);
-    let firstAttempt = true;
-    for (;;) {
-        const remaining = deadline - Date.now();
-        // Past the first attempt, an already-expired budget ends the loop here
-        // instead of spending one more full attempt timeout (P4.2 re-review
-        // Minor) — only the very first attempt is unconditional (R-WAKE-1: "a
-        // single failed probe does not abort"/at-least-one-attempt).
-        if (!firstAttempt && remaining <= 0)
-            return false;
-        const attemptTimeoutMs = firstAttempt
-            ? Math.max(250, Math.min(READY_PROBE_ATTEMPT_TIMEOUT_MS, windowMs))
-            : Math.min(READY_PROBE_ATTEMPT_TIMEOUT_MS, remaining);
-        firstAttempt = false;
-        if (await wakeInternals.probeNodeOnce(previewEndpoint, target, relayToken, attemptTimeoutMs))
-            return true;
-        const remainingAfter = deadline - Date.now();
-        if (remainingAfter <= 0)
-            return false;
-        await delay(Math.min(READY_PROBE_BACKOFF_MS, remainingAfter));
-    }
-}
-/** Indirection seam so a smoke/test script can swap any step (the provider
- *  backend, the registry setters, the secret resolver, the probe itself, the
- *  clock) without touching a real DB/provider/filesystem. Production code
- *  never reassigns these; only ad hoc verification scripts do. */
-export const wakeInternals = {
-    getHomeById,
-    getHearthTarget,
-    recordBadTarget,
-    refreshProviderPointers,
-    setHomeStatus,
-    setHealthVerdict,
-    touchWake,
-    touchReady,
-    resolveSecret,
-    getHomeBackend: (config) => getHomeBackend(config),
-    loadM0Config: () => loadM0Config(),
-    loadControlPlaneConfig: () => loadControlPlaneConfig(),
-    probeNodeOnce,
-    probeNodeReady,
-    now: () => Date.now(),
-};
-const warmVerdicts = new Map();
-const inflightWakes = new Map();
-/** Cheap, non-probing fast path: return a still-fresh warm-verdict cache hit
- *  for `home_id`, or `null` if there is none (expired or never confirmed).
- *  Never reads the registry and never calls the provider — callers fall back
- *  to `ensureAwake` on a `null` (Q1: "no call to provider"). */
-export function resolveRunning(home_id) {
-    const warm = warmVerdicts.get(home_id);
-    if (warm === undefined)
-        return null;
-    if (wakeInternals.now() - warm.confirmedAt >= WARM_VERDICT_TTL_MS)
-        return null;
-    return warm.result;
-}
-/** Drop the cached warm verdict for a home (e.g. an upstream relay forward
- *  failed) so the next `ensureAwake`/`resolveRunning` re-checks instead of
- *  trusting a stale "ready" answer. */
-export function invalidateWarmVerdict(home_id) {
-    warmVerdicts.delete(home_id);
-}
-/** Clear all warm verdicts and in-flight wake coalescing. Test/smoke-script
- *  hygiene only — production never needs this (one CP process, S2). */
-export function resetWakeCacheForTests() {
-    warmVerdicts.clear();
-    inflightWakes.clear();
-}
-/** Is this home currently serving, so a destructive roll would interrupt it?
- *  Delegates entirely to `serving.ts`'s independent live-session counters,
- *  bumped at the relay's HTTP/WS lifecycle seams and the CP's OAuth
- *  start/finish dispatch — never derived from any TTL/cache. `home.status` is
- *  intentionally NOT consulted: a suspended home has no live counters anyway
- *  (nothing to bump them), so this stays a single source of truth. */
-function homeIsServing(home) {
-    return isHomeServingNow(home.home_id);
-}
-/** Is this home due to roll onto the registered target? Stale = it isn't
- *  already on the target version AND the target is not a known-bad release.
- *  The bad-target clause is the ONLY brake in the zero-touch loop (roadmap
- *  decision 1: never auto-advance onto a release that already failed a roll):
- *  once `recordBadTarget` poisons the current target, no home rolls onto it
- *  until a NEW release advances the target past it.
- *
- *  NOTE (design divergence, flagged): design §3's literal snippet compared
- *  `home.template_version !== last_bad_target_version`, which would THRASH —
- *  after a failed roll a home sits on the PRIOR version, so that clause stays
- *  true and it would re-roll onto the same broken target forever. The roadmap's
- *  plain-English brake and design §5's own comment both mean `target !==
- *  last_bad`; that is what is implemented here. */
-function isHomeStale(home, target) {
-    if (home.template_version === null)
-        return false;
-    if (home.template_version === target.target_template_version)
-        return false;
-    if (target.last_bad_target_version !== null && target.target_template_version === target.last_bad_target_version)
-        return false;
-    return true;
-}
-// Baked crtr path (deploy/hearth-blaxel/Dockerfile symlink) — target it
-// directly for the in-guest version assert rather than a bare PATH lookup,
-// exactly as blaxel-bootstrap.ts does, so a stale legacy binary earlier on
-// PATH can't answer instead.
-const BAKED_CRTR_PATH = '/usr/local/bin/crtr';
-/** Assert what crtr the recreated guest is ACTUALLY running (design §4 step 7)
- *  by reading `crtr --json sys version` in-guest — stronger than trusting the
- *  provider's config version, since it proves the booted binary. Parses the
- *  `.version` field from `{ "version": "X.Y.Z" }`. The same drift-guard env
- *  vars the bootstrap uses keep this a pure read (no bootstrap/auto-init/
- *  auto-update side effects). */
-async function assertGuestVersion(backend, sandboxName) {
-    const result = await backend.exec(sandboxName, {
-        command: `CRTR_NO_BOOTSTRAP=1 CRTR_NO_AUTO_INIT=1 CRTR_NO_AUTO_UPDATE=1 ${BAKED_CRTR_PATH} --json sys version`,
-        timeoutMs: 20_000,
-    });
-    // A parseable stdout is not proof the command itself succeeded — require a
-    // clean exit before trusting anything it printed.
-    if (result.exitCode !== 0 || result.timedOut === true) {
-        throw general(`in-guest crtr sys version did not exit cleanly (exitCode ${result.exitCode}, timedOut ${result.timedOut})`, {
-            sandboxName,
-            exitCode: result.exitCode,
-            timedOut: result.timedOut,
-            stdout: result.stdout.slice(0, 200),
-            stderr: result.stderr.slice(0, 200),
-        });
-    }
-    const stdout = result.stdout.trim();
-    try {
-        const parsed = JSON.parse(stdout);
-        if (typeof parsed.version === 'string' && parsed.version.trim() !== '')
-            return parsed.version.trim();
-    }
-    catch {
-        /* fall through to a tolerant field extraction below */
-    }
-    const match = /"version"\s*:\s*"([^"]+)"/.exec(stdout);
-    if (match !== null && match[1].trim() !== '')
-        return match[1].trim();
-    throw general(`in-guest crtr sys version returned no parseable .version (exit ${result.exitCode})`, {
-        sandboxName,
-        stdout: stdout.slice(0, 200),
-    });
-}
-/** Structured HIGH-SEVERITY alert lines. The CP is a standalone Fly process
- *  and cannot `crtr push`; alerting is a distinct `level: 'error'` stderr line
- *  with an `alert` marker that ops log-alerting keys on. (Wiring these to a
- *  real notification channel is future work — the marker is the seam.) */
-function alertRollRolledBack(home, target, restoredVersion) {
-    process.stderr.write(`${JSON.stringify({
-        level: 'error',
-        alert: 'hearth.roll.rolled_back',
-        message: `Hearth auto-upgrade roll FAILED and was rolled back — release ${target.target_template_version} is broken`,
-        home_id: home.home_id,
-        bad_target_version: target.target_template_version,
-        restored_version: restoredVersion,
-    })}\n`);
-}
-export function serializeError(error) {
-    if (error instanceof Error)
-        return error.message;
-    try {
-        // `JSON.stringify` returns `undefined` (does not throw) for `undefined`, a function, or a
-        // symbol — falling through to that would OMIT the `error` field from the incident alert's
-        // JSON line entirely, which is worse than the "[object Object]" bug this rider fixes.
-        const json = JSON.stringify(error);
-        return json === undefined ? String(error) : json;
-    }
-    catch {
-        return String(error);
-    }
-}
-function alertRollIncident(home, target, priorVersion, error) {
-    process.stderr.write(`${JSON.stringify({
-        level: 'error',
-        alert: 'hearth.roll.incident',
-        message: `Hearth auto-upgrade roll AND rollback both failed — home ${home.home_id} is DEGRADED, manual recovery needed`,
-        home_id: home.home_id,
-        bad_target_version: target.target_template_version,
-        prior_version: priorVersion,
-        error: serializeError(error),
-    })}\n`);
-}
-/** Fall back onto the PRIOR pinned image after a failed roll (design §5). The
- *  volume was never touched by the roll, so this is deterministic: recreate on
- *  the prior image name (still in the registry — images are never pruned),
- *  revive, ready-probe, assert `crtr sys version === priorVersion`. On success,
- *  ALERT (the release is broken) — the bad target is already poisoned by
- *  `rollHome`'s catch (the roll's own failure is what poisons the target, not
- *  rollback's success, so the brake is set even when rollback ALSO fails).
- *  On rollback also failing: mark the home
- *  `unknown`/`degraded` and alert — a genuine incident (the volume is intact,
- *  so manual recovery is always possible). */
-async function rollbackHome(args) {
-    const { home, target, descriptor, priorImageRef, priorVersion, relayToken, backend, readyTimeoutMs } = args;
-    try {
-        const refresh = await backend.recreateOnImage(descriptor, priorImageRef, priorVersion);
-        const previewEndpoint = requireHomeField(refresh.previewEndpoint ?? null, 'preview_endpoint', home.home_id);
-        const ready = await wakeInternals.probeNodeReady(previewEndpoint, descriptor.homeAgentTarget, relayToken, readyTimeoutMs);
-        if (!ready)
-            throw general(`rollback ready-probe timed out for ${home.home_id}`, { home_id: home.home_id });
-        // Assert against the sandbox the recreate actually reports, not a stale name captured at
-        // entry — under generation naming (recreate-race-fix.md §3.5) the pre-recreate sandbox is
-        // destroyed, so exec-ing into anything else would target a gone/wrong generation.
-        const asserted = await assertGuestVersion(backend, refresh.providerSandboxId);
-        if (asserted !== priorVersion) {
-            throw general(`rollback version mismatch: expected ${priorVersion}, got ${asserted}`, { home_id: home.home_id, expected: priorVersion, asserted });
-        }
-        wakeInternals.refreshProviderPointers(home.home_id, {
-            provider_sandbox_id: refresh.providerSandboxId,
-            preview_endpoint: previewEndpoint,
-            template_version: priorVersion,
-            status: 'running',
-        });
-        wakeInternals.setHealthVerdict(home.home_id, 'healthy');
-        alertRollRolledBack(home, target, priorVersion);
-        return { preview_endpoint: previewEndpoint, relayToken };
-    }
-    catch (rollbackError) {
-        wakeInternals.setHomeStatus(home.home_id, 'unknown');
-        wakeInternals.setHealthVerdict(home.home_id, 'degraded');
-        alertRollIncident(home, target, priorVersion, rollbackError);
-        throw general(`hearth roll AND rollback both failed for ${home.home_id}`, {
-            home_id: home.home_id,
-            target: target.target_template_version,
-            priorVersion,
-        });
-    }
-}
-/** CP-driven destroy→recreate of a stale home onto the registered target
- *  image, reattaching the same durable volume (design §4). Captures rollback
- *  anchors first, marks the home `restoring` (so a concurrent wake coalesces
- *  rather than races), then recreates on the target image, ready-probes, and
- *  ASSERTS the in-guest `crtr sys version` equals the target before committing
- *  pointers + `health_verdict = healthy`. A roll never writes
- *  `home_agent_target` (canvas.db is reattached byte-identical;
- *  `refreshProviderPointers` has no such field). Any of recreate/probe/assert
- *  failing falls back to the prior image (§5). Returns the route so the
- *  triggering wake serves the just-upgraded home in the same call. */
-async function rollHome(home, target, relayToken, descriptor) {
-    const priorVersion = requireHomeField(home.template_version, 'template_version', home.home_id);
-    const priorImageRef = hearthHomeImageRefForVersion(priorVersion);
-    const m0 = wakeInternals.loadM0Config();
-    const backend = wakeInternals.getHomeBackend(m0);
-    const cpConfig = wakeInternals.loadControlPlaneConfig();
-    wakeInternals.setHomeStatus(home.home_id, 'restoring');
-    invalidateWarmVerdict(home.home_id);
-    const startedAt = wakeInternals.now();
-    try {
-        const refresh = await backend.recreateOnImage(descriptor, target.target_image_ref, target.target_template_version);
-        const previewEndpoint = requireHomeField(refresh.previewEndpoint ?? null, 'preview_endpoint', home.home_id);
-        const ready = await wakeInternals.probeNodeReady(previewEndpoint, descriptor.homeAgentTarget, relayToken, cpConfig.readyTimeoutMs);
-        if (!ready)
-            throw general(`roll ready-probe timed out for ${home.home_id}`, { home_id: home.home_id });
-        // Assert against the sandbox the recreate actually reports (recreate-race-fix.md §3.5) —
-        // never the row's pre-recreate `provider_sandbox_id`, which under generation naming is
-        // already destroyed by the time this runs.
-        const asserted = await assertGuestVersion(backend, refresh.providerSandboxId);
-        if (asserted !== target.target_template_version) {
-            throw general(`roll version mismatch: expected ${target.target_template_version}, got ${asserted}`, {
-                home_id: home.home_id,
-                expected: target.target_template_version,
-                asserted,
-            });
-        }
-        wakeInternals.refreshProviderPointers(home.home_id, {
-            provider_sandbox_id: refresh.providerSandboxId,
-            preview_endpoint: previewEndpoint,
-            template_version: asserted,
-            status: 'running',
-        });
-        wakeInternals.setHealthVerdict(home.home_id, 'healthy');
-        wakeInternals.touchWake(home.home_id, { at: new Date(startedAt).toISOString(), latency_ms: wakeInternals.now() - startedAt });
-        wakeInternals.touchReady(home.home_id);
-        return { preview_endpoint: previewEndpoint, relayToken };
-    }
-    catch {
-        // The target is known-bad the INSTANT its own roll fails, independent of
-        // whether rollback then recovers — poison it here, before delegating to
-        // rollbackHome, so a roll-fails+rollback-also-fails home doesn't leave the
-        // brake unset (which would let a later wake, of this home or any other,
-        // re-roll onto the same broken target).
-        wakeInternals.recordBadTarget(target.target_template_version);
-        return rollbackHome({ home, target, descriptor, priorImageRef, priorVersion, relayToken, backend, readyTimeoutMs: cpConfig.readyTimeoutMs });
-    }
-}
-async function runEnsureAwake(home_id) {
-    const home = wakeInternals.getHomeById(home_id);
-    if (home === null)
-        throw general(`home not found: ${home_id}`, { home_id });
-    const relayAuthRef = requireHomeField(home.relay_auth_ref, 'relay_auth_ref', home_id);
-    const relayToken = wakeInternals.resolveSecret(relayAuthRef);
-    const target = requireHomeField(home.home_agent_target, 'home_agent_target', home_id);
-    const descriptor = buildDescriptor(home, relayToken);
-    // Auto-upgrade lazy roll (design §3/§4): if a newer image target is
-    // registered, this home is stale, and it is NOT currently serving, roll it
-    // onto the target image now instead of the normal wake. At wake-entry an
-    // idle home is definitionally safe to tear down; a serving home doesn't roll
-    // this pass (it rolls on its next cold wake). This is the ONLY new branch —
-    // the normal wake path below is unchanged.
-    const hearthTarget = wakeInternals.getHearthTarget();
-    if (hearthTarget !== null && isHomeStale(home, hearthTarget) && !homeIsServing(home)) {
-        return rollHome(home, hearthTarget, relayToken, descriptor);
-    }
-    const startedAt = wakeInternals.now();
-    const m0 = wakeInternals.loadM0Config();
-    const refresh = await wakeInternals.getHomeBackend(m0).wake(descriptor);
-    const normalizedStatus = normalizeProviderStatus(refresh.status);
-    const recreated = refresh.providerSandboxId !== home.provider_sandbox_id || (refresh.previewEndpoint ?? null) !== home.preview_endpoint;
-    let previewEndpoint;
-    if (recreated) {
-        // R-WAKE-6, non-negotiable: persist the new sandbox/preview pointers but
-        // never the home node target — `refreshProviderPointers`'s input shape
-        // has no `home_agent_target` field, so there is no way for this call to
-        // touch it even by accident.
-        const updated = wakeInternals.refreshProviderPointers(home_id, {
-            provider_sandbox_id: refresh.providerSandboxId,
-            preview_endpoint: refresh.previewEndpoint ?? null,
-            status: normalizedStatus,
-            template_version: refresh.templateVersion ?? home.template_version,
-        });
-        previewEndpoint = updated.preview_endpoint;
-    }
-    else {
-        wakeInternals.setHomeStatus(home_id, normalizedStatus);
-        previewEndpoint = home.preview_endpoint;
-    }
-    const resolvedPreviewEndpoint = requireHomeField(previewEndpoint, 'preview_endpoint', home_id);
-    const controlPlaneConfig = wakeInternals.loadControlPlaneConfig();
-    const ready = await wakeInternals.probeNodeReady(resolvedPreviewEndpoint, target, relayToken, controlPlaneConfig.readyTimeoutMs);
-    if (!ready) {
-        throw general(`guest web relay did not become ready before timeout: ${home_id}`, { home_id, previewEndpoint: resolvedPreviewEndpoint });
-    }
-    const readyAt = new Date().toISOString();
-    wakeInternals.touchWake(home_id, { at: new Date(startedAt).toISOString(), latency_ms: wakeInternals.now() - startedAt });
-    wakeInternals.touchReady(home_id, readyAt);
-    // A successful ready-probe means the home is healthy right now, regardless of what the
-    // verdict was before this wake (e.g. left `degraded` by an earlier failed rollback) —
-    // clear it here the same way rollHome/rollbackHome clear it on their own success, or a
-    // stale degraded/unknown verdict never heals on the normal wake path.
-    wakeInternals.setHealthVerdict(home_id, 'healthy');
-    return { preview_endpoint: resolvedPreviewEndpoint, relayToken };
-}
-/** Bring a home up and ready, returning the route to relay to once it is.
- *  Reads the registry, resolves the relay token, calls the provider
- *  wake/resume seam, ready-probes `/node/<home_agent_target>`, refreshes
- *  provider pointers on a recreate, records wake/ready timing, clears the
- *  health verdict to `healthy` on success, and returns
- *  `{ preview_endpoint, relayToken }`. Throws on a ready-probe timeout
- *  (wake-failure UX is deferred — gap note 2 — a throw is the accepted
- *  cutover behavior).
- *
- *  A fresh warm-verdict cache hit short-circuits without re-entering this
- *  pipeline at all. Otherwise concurrent callers for the SAME `home_id`
- *  coalesce onto one in-flight wake (Q1) instead of each driving their own
- *  provider call. */
-export async function ensureAwake(home_id) {
-    const warm = resolveRunning(home_id);
-    if (warm !== null)
-        return warm;
-    const inflight = inflightWakes.get(home_id);
-    if (inflight !== undefined)
-        return inflight;
-    const promise = runEnsureAwake(home_id)
-        .then((result) => {
-        warmVerdicts.set(home_id, { result, confirmedAt: wakeInternals.now() });
-        return result;
-    })
-        .finally(() => {
-        if (inflightWakes.get(home_id) === promise)
-            inflightWakes.delete(home_id);
-    });
-    inflightWakes.set(home_id, promise);
-    return promise;
-}