@crouton-kit/crouter 0.3.38 → 0.3.39

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

@@ -147,6 +147,13 @@ export function refreshProviderPointers(home_id, pointers, db = getControlPlaneD
 export function setHomeStatus(home_id, status, db = getControlPlaneDb()) {
     return updateHome(home_id, () => ({ status }), db);
 }
+/** Set the home's health verdict. The auto-upgrade roll (wake.ts `rollHome`)
+ *  is the first natural producer of `health_verdict`: a completed roll/
+ *  rollback writes `'healthy'`, a roll AND rollback both failing writes
+ *  `'degraded'` (design §4/§5). */
+export function setHealthVerdict(home_id, health_verdict, db = getControlPlaneDb()) {
+    return updateHome(home_id, () => ({ health_verdict }), db);
+}
 export function touchWake(home_id, input = {}, db = getControlPlaneDb()) {
     return updateHome(home_id, () => ({
         last_wake_at: input.at ?? nowIso(),

package/dist/hearth/control-plane/relay.d.ts

@@ -5,6 +5,10 @@ import { type ControlPlaneConfig } from './config.js';
 import { type WakeResult } from './wake.js';
 import type { HomeId, ResolvedHome } from './types.js';
 import type { RelayDispatcher } from './server.js';
+/** Serialize a non-`Error` rejection for a log line without collapsing it to `"[object Object]"`
+ *  (`String(error)` on a plain object) — recreate-race-fix.md §3.6. Falls back to `String` only
+ *  if the value itself isn't JSON-serializable (a circular structure, a BigInt, etc). */
+export declare function serializeRelayError(error: unknown): string;
 /** Join the validated origin-form request target onto `previewEndpoint` and
  *  reject anything that would escape that origin (criterion 4: "reject
  *  scheme-relative/absolute external escapes"). */

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

@@ -35,6 +35,7 @@ import { BROKER_READ_CAPS } from '../../core/runtime/broker-protocol.js';
 import { general } from '../../core/errors.js';
 import { loadControlPlaneConfig } from './config.js';
 import { ensureAwake, invalidateWarmVerdict, resolveRunning } from './wake.js';
+import { beginHttp, beginWs, endHttp, endWs } from './serving.js';
 import { redactSecrets } from './secrets.js';
 import { tenantSessionAuthRedactedMessage } from './session.js';
 const hopByHopHeaders = new Set([
@@ -69,6 +70,22 @@ function redactDeep(value) {
 function logError(message, details = {}) {
     process.stderr.write(`${JSON.stringify({ level: 'error', message, details: redactDeep(details) })}\n`);
 }
+/** Serialize a non-`Error` rejection for a log line without collapsing it to `"[object Object]"`
+ *  (`String(error)` on a plain object) — recreate-race-fix.md §3.6. Falls back to `String` only
+ *  if the value itself isn't JSON-serializable (a circular structure, a BigInt, etc). */
+export function serializeRelayError(error) {
+    try {
+        // `JSON.stringify` returns `undefined` (does not throw) for `undefined`, a function, or a
+        // symbol. Falling through to that here would hand the `message.startsWith('relay ')`/
+        // `/timed out/i` control-flow checks right after this an `undefined` string and THROW
+        // inside the catch block — exactly the control-flow change this rider promised not to make.
+        const json = JSON.stringify(error);
+        return json === undefined ? String(error) : json;
+    }
+    catch {
+        return String(error);
+    }
+}
 function requestPath(req) {
     return req.url ?? '/';
 }
@@ -339,7 +356,25 @@ export async function proxyHttp(req, res, home, deps = {}) {
         const running = resolveRunningImpl(home.home_id);
         if (running !== null) {
             try {
-                await forwardUpstream(req, res, running, controller);
+                // Mark this home as actively serving ONLY around the actual data
+                // transfer, never around the wake DECISION above it. Bumping the
+                // counter any earlier (e.g. unconditionally on function
+                // entry, before `ensureAwake` runs below) would make a home's very
+                // FIRST request after being suspended see ITS OWN just-begun counter
+                // and read as "serving" — `isHomeStale && !homeIsServing` would then
+                // never be true for any home, ever, silently disabling every roll
+                // (verified live: `beginHttp` then `isHomeServing` in the same tick
+                // returns true with zero other activity). Scoping begin/end tightly
+                // around each `forwardUpstream` call still protects the real target
+                // (a genuinely separate, already-open session on this home) because
+                // that session's OWN counter is independent and already non-zero.
+                beginHttp(home.home_id);
+                try {
+                    await forwardUpstream(req, res, running, controller);
+                }
+                finally {
+                    endHttp(home.home_id);
+                }
                 return;
             }
             catch (error) {
@@ -358,10 +393,21 @@ export async function proxyHttp(req, res, home, deps = {}) {
         const awakened = await withTimeout(ensureAwakeImpl(home.home_id), config.wakeTimeoutMs, 'control plane relay wake');
         if (controller.signal.aborted)
             throw general('request closed while waking');
-        await forwardUpstream(req, res, awakened, controller);
+        beginHttp(home.home_id);
+        try {
+            await forwardUpstream(req, res, awakened, controller);
+        }
+        finally {
+            endHttp(home.home_id);
+        }
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
+        // A non-`Error` rejection (e.g. a raw object thrown from outside the SDK's recognized error
+        // shapes) must not serialize to "[object Object]" here — that loss of the real error is what
+        // cost the recreate-race incident its diagnosis (recreate-race-fix.md §3.6). `message` below
+        // still drives the control-flow checks that follow (relay-prefixed/timeout messages), which
+        // only ever come from `Error` instances (`general()`), so this branch change cannot affect them.
+        const message = error instanceof Error ? error.message : serializeRelayError(error);
         logError('hearth control plane relay HTTP request failed', {
             home_id: home.home_id,
             path: requestPath(req).replace(/\?.*$/, ''),
@@ -489,6 +535,12 @@ async function proxyWebSocketBrowser(browserWs, home, deps = {}) {
     const handshakeAt = Date.now();
     let upstream = null;
     let teardownStarted = false;
+    // Whether THIS bridge has actually incremented `wsOpen` (set true only
+    // once the upstream leg is being established — see below —
+    // and guards the `close`-handler `endWs` call so a bridge whose own
+    // `ensureAwake` failed before ever counting itself can't decrement a
+    // DIFFERENT, still-live session's counter for the same home).
+    let wsCounted = false;
     let upstreamOpenAt = null;
     let browserClose = null;
     let upstreamClose = null;
@@ -551,6 +603,10 @@ async function proxyWebSocketBrowser(browserWs, home, deps = {}) {
         if (upstream !== null && (upstream.readyState === WebSocket.OPEN || upstream.readyState === WebSocket.CONNECTING)) {
             sendSocketClose(upstream, code, closeReason);
         }
+        if (wsCounted) {
+            wsCounted = false;
+            endWs(home.home_id);
+        }
     });
     browserWs.on('error', (error) => {
         logError('hearth control plane relay browser websocket failed', { home_id: home.home_id, error: error instanceof Error ? error.message : String(error) });
@@ -565,6 +621,19 @@ async function proxyWebSocketBrowser(browserWs, home, deps = {}) {
             beginTeardown();
             return;
         }
+        // Mark this home as actively serving ONLY once the wake DECISION above
+        // has already resolved — not on function entry.
+        // `ensureAwake` (inside the wait above) makes the roll-vs-normal-wake
+        // call by consulting this very tracker; counting a bridge as "open"
+        // before that decision runs would make a home's very first WS reconnect
+        // after being suspended see ITS OWN not-yet-real session and read as
+        // "serving," permanently blocking the roll this connection was itself
+        // supposed to trigger (mirrors the identical HTTP hazard in `proxyHttp`
+        // above — verified live for the HTTP case; same mechanism applies here).
+        // A genuinely separate, already-open bridge for this home is unaffected:
+        // its own counter is already live and independent of this one.
+        beginWs(home.home_id);
+        wsCounted = true;
         upstream = createUpstream(toWssUrl(awakened.preview_endpoint, target), awakened.relayToken);
         upstream.on('open', () => {
             if (teardownStarted || browserWs.readyState !== WebSocket.OPEN) {

package/dist/hearth/control-plane/secrets.d.ts

@@ -7,6 +7,20 @@
  *  an unknown handle — the thrown message never includes a resolved value,
  *  only the handle name. */
 export declare function resolveSecret(handle: string, env?: NodeJS.ProcessEnv): string;
+/** The secret HANDLE for the CP admin bearer token that gates the
+ *  `POST /__admin/*` ingress (the image workflow's push-notify, design
+ *  §2-C). Resolves through the SAME `resolveSecret` seam as every other CP
+ *  handle: the per-handle env override
+ *  `CRTR_HEARTH_CP_SECRET_HEARTH_CP_ADMIN_TOKEN`, else the `HEARTH_CP_ADMIN_TOKEN`
+ *  key in the CP secrets file. The GitHub repo secret `HEARTH_CP_ADMIN_TOKEN`
+ *  and the deployed Fly CP must carry the SAME value. */
+export declare const HEARTH_CP_ADMIN_TOKEN_HANDLE = "HEARTH_CP_ADMIN_TOKEN";
+/** Resolve the CP admin bearer token, or `null` when it is not configured.
+ *  Unlike `resolveSecret` (which throws on an unknown handle), this returns
+ *  `null` so the admin route can FAIL CLOSED — a CP with no admin token
+ *  configured rejects every `/__admin/*` request rather than crashing the
+ *  request handler. Never logs the value. */
+export declare function resolveCpAdminToken(env?: NodeJS.ProcessEnv): string | null;
 /** Redact every secret value resolved so far this process out of a log
  *  line/message. CP code building a log line from data that may carry a
  *  resolved secret (e.g. an upstream request trace) MUST pass it through this

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

@@ -92,6 +92,27 @@ export function resolveSecret(handle, env = process.env) {
     }
     throw general(`unknown secret handle: ${trimmed}`, { handle: trimmed });
 }
+/** The secret HANDLE for the CP admin bearer token that gates the
+ *  `POST /__admin/*` ingress (the image workflow's push-notify, design
+ *  §2-C). Resolves through the SAME `resolveSecret` seam as every other CP
+ *  handle: the per-handle env override
+ *  `CRTR_HEARTH_CP_SECRET_HEARTH_CP_ADMIN_TOKEN`, else the `HEARTH_CP_ADMIN_TOKEN`
+ *  key in the CP secrets file. The GitHub repo secret `HEARTH_CP_ADMIN_TOKEN`
+ *  and the deployed Fly CP must carry the SAME value. */
+export const HEARTH_CP_ADMIN_TOKEN_HANDLE = 'HEARTH_CP_ADMIN_TOKEN';
+/** Resolve the CP admin bearer token, or `null` when it is not configured.
+ *  Unlike `resolveSecret` (which throws on an unknown handle), this returns
+ *  `null` so the admin route can FAIL CLOSED — a CP with no admin token
+ *  configured rejects every `/__admin/*` request rather than crashing the
+ *  request handler. Never logs the value. */
+export function resolveCpAdminToken(env = process.env) {
+    try {
+        return resolveSecret(HEARTH_CP_ADMIN_TOKEN_HANDLE, env);
+    }
+    catch {
+        return null;
+    }
+}
 /** Redact every secret value resolved so far this process out of a log
  *  line/message. CP code building a log line from data that may carry a
  *  resolved secret (e.g. an upstream request trace) MUST pass it through this

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

@@ -53,10 +53,14 @@
 // handed to the dispatcher, which today simply reports "not implemented yet"
 // without contacting any home.
 import { createServer } from 'node:http';
+import { createHash, timingSafeEqual } from 'node:crypto';
+import { hearthHomeImageRefForVersion } from '../../core/hearth/config.js';
 import { getControlPlaneDb } from './db.js';
 import { resolveHome } from './registry.js';
+import { setHearthTarget } from './hearth-target.js';
 import { resolveTenantSession, resolveTenantWriteAuth, swapQueryTokenForCookie, tenantSessionAuthRedactedMessage } from './session.js';
-import { redactSecrets } from './secrets.js';
+import { redactSecrets, resolveCpAdminToken } from './secrets.js';
+import { beginOAuth, endOAuth } from './serving.js';
 import { handleWebhookRequest, isWebhookPath, isWebhookRequest } from './register.js';
 const notImplementedRelay = {
     proxyHttp(_req, res) {
@@ -89,6 +93,106 @@ function redirectChat(res, target) {
 function respondHealthz(res) {
     sendText(res, 200, 'ok\n');
 }
+const ADMIN_HEARTH_IMAGE_PATH = '/__admin/hearth-image';
+// The auto-upgrade notify body is tiny ({template_version, image_ref}); cap
+// hard so a malformed/oversized POST can't buffer unbounded.
+const ADMIN_BODY_MAX_BYTES = 4 * 1024;
+const STRICT_SEMVER_RE = /^[0-9]+\.[0-9]+\.[0-9]+$/;
+/** Fixed-length digest of a UTF-8 string — always 32 bytes (sha256), so
+ *  comparing two digests never branches on the ORIGINAL strings' lengths. */
+function sha256(value) {
+    return createHash('sha256').update(value, 'utf8').digest();
+}
+/** Constant-time bearer check against the configured CP admin token. Fails
+ *  CLOSED: no `Authorization: Bearer` header, or no token configured on the
+ *  CP, or a mismatch — all return false without leaking which. Compares
+ *  sha256 digests (always 32 bytes each) rather than the raw token buffers,
+ *  so there is no length-inequality short-circuit that would leak the
+ *  configured token's length before `timingSafeEqual` runs — equal plaintext
+ *  still implies equal digest, and every digest is the same size regardless
+ *  of what was presented. */
+function isAdminAuthorized(req) {
+    const configured = resolveCpAdminToken();
+    if (configured === null || configured === '')
+        return false;
+    const header = req.headers.authorization;
+    if (typeof header !== 'string')
+        return false;
+    const match = /^Bearer[ ]+(.+)$/.exec(header.trim());
+    if (match === null)
+        return false;
+    return timingSafeEqual(sha256(match[1]), sha256(configured));
+}
+function readRequestBody(req, maxBytes) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let total = 0;
+        let tooLarge = false;
+        req.on('data', (chunk) => {
+            total += chunk.length;
+            if (total > maxBytes) {
+                tooLarge = true;
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on('end', () => resolve({ body: Buffer.concat(chunks), tooLarge }));
+        req.on('error', (error) => {
+            if (tooLarge) {
+                resolve({ body: Buffer.alloc(0), tooLarge: true });
+                return;
+            }
+            reject(error instanceof Error ? error : new Error(String(error)));
+        });
+    });
+}
+/** `POST /__admin/hearth-image` — the image-build workflow's push-notify
+ *  (design §2-C). Bearer-authed against the CP admin token (constant-time),
+ *  BEFORE and outside the session/registry gate (it is a machine ingress, not
+ *  a browser lane). Validates the body is strict semver + `image_ref ===
+ *  hearthHomeImageRefForVersion(template_version)` (the notify cannot register
+ *  an image name that doesn't match its version), then idempotently upserts
+ *  the single global target row — a re-post of the same version is a no-op. It
+ *  never contacts a home; the actual roll happens lazily on each home's next
+ *  wake (wake.ts). */
+async function respondAdminHearthImage(req, res, db) {
+    if (!isAdminAuthorized(req)) {
+        sendText(res, 401, 'admin authorization required\n');
+        return;
+    }
+    const { body, tooLarge } = await readRequestBody(req, ADMIN_BODY_MAX_BYTES);
+    if (tooLarge) {
+        sendText(res, 413, 'request body too large\n');
+        return;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(body.toString('utf8'));
+    }
+    catch {
+        sendText(res, 400, 'body must be valid JSON\n');
+        return;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        sendText(res, 400, 'body must be a JSON object with template_version and image_ref\n');
+        return;
+    }
+    const record = parsed;
+    const templateVersion = typeof record.template_version === 'string' ? record.template_version.trim() : '';
+    const imageRef = typeof record.image_ref === 'string' ? record.image_ref.trim() : '';
+    if (!STRICT_SEMVER_RE.test(templateVersion)) {
+        sendText(res, 400, 'template_version must be strict semver (X.Y.Z)\n');
+        return;
+    }
+    const expectedImageRef = hearthHomeImageRefForVersion(templateVersion);
+    if (imageRef !== expectedImageRef) {
+        sendText(res, 400, `image_ref must equal ${expectedImageRef} for template_version ${templateVersion}\n`);
+        return;
+    }
+    const target = setHearthTarget({ target_template_version: templateVersion, target_image_ref: imageRef, source: 'image-workflow' }, db);
+    sendText(res, 200, `hearth target = ${target.target_template_version} (${target.target_image_ref})\n`);
+}
 /** `?token=` is intentionally not accepted as durable auth (`session.ts`); the
  *  one allowed query-token use is the single-use M0 handoff swap-to-cookie,
  *  attempted here only when no durable cookie/bearer session is already
@@ -128,12 +232,14 @@ function respondRoot(req, res, db, config, store) {
     }
     redirectChat(res, target);
 }
+const MODEL_AUTH_START_PATH = '/__hearth/model-auth/anthropic/start';
+const MODEL_AUTH_FINISH_PATH = '/__hearth/model-auth/anthropic/finish';
 const DYNAMIC_ROUTES = [
     { method: 'POST', path: '/__crtr/source', auth: 'write' },
     { method: 'GET', path: '/__crtr/events', auth: 'read' },
     { method: 'GET', path: '/__hearth/model-auth/anthropic/status', auth: 'read' },
-    { method: 'POST', path: '/__hearth/model-auth/anthropic/start', auth: 'write' },
-    { method: 'POST', path: '/__hearth/model-auth/anthropic/finish', auth: 'write' },
+    { method: 'POST', path: MODEL_AUTH_START_PATH, auth: 'write' },
+    { method: 'POST', path: MODEL_AUTH_FINISH_PATH, auth: 'write' },
 ];
 const DYNAMIC_ROUTE_PATHS = new Set(DYNAMIC_ROUTES.map((route) => route.path));
 function findDynamicRoute(method, pathname) {
@@ -177,6 +283,13 @@ function isRelayableViewOrAssetPath(pathname) {
  *  (or, for `auth: 'write'`, an untrusted Origin) or an unresolved home
  *  rejects before the relay dispatcher (and therefore before any
  *  wake/provider/home contact) is ever invoked. */
+/** OAuth-in-progress marker: the CP's own proxied `start`/`finish` dispatch
+ *  is the seam — mark a window open the moment a
+ *  `start` is about to be proxied (regardless of what the guest does with
+ *  it), close it once the `finish` proxy call resolves (success OR failure;
+ *  a failed finish still ends the CP-visible window — the bounded TTL in
+ *  `serving.ts` is the backstop for a `start` that never gets a `finish` at
+ *  all, e.g. an abandoned browser tab). */
 async function respondDynamicLane(req, res, db, config, store, relay, auth) {
     const session = auth === 'write'
         ? resolveTenantWriteAuth(req, { store, publicOrigin: config.publicOrigin })
@@ -190,7 +303,18 @@ async function respondDynamicLane(req, res, db, config, store, relay, auth) {
         sendText(res, 404, 'home not found\n');
         return;
     }
-    await relay.proxyHttp(req, res, home);
+    const pathname = requestUrl(req).pathname;
+    const isOAuthStart = pathname === MODEL_AUTH_START_PATH;
+    const isOAuthFinish = pathname === MODEL_AUTH_FINISH_PATH;
+    if (isOAuthStart)
+        beginOAuth(home.home_id);
+    try {
+        await relay.proxyHttp(req, res, home);
+    }
+    finally {
+        if (isOAuthFinish)
+            endOAuth(home.home_id);
+    }
 }
 async function routeControlPlaneRequest(req, res, db, config, store, relay) {
     const url = requestUrl(req);
@@ -215,6 +339,18 @@ async function routeControlPlaneRequest(req, res, db, config, store, relay) {
         await handleWebhookRequest(req, res);
         return;
     }
+    // Admin push-notify lane. Authenticated by the CP admin bearer token inside
+    // the handler, so — like the webhook lane — it sits BEFORE and outside the
+    // session/registry gate. A wrong method on the admin path is a 405, never a
+    // fall-through to the relay.
+    if (url.pathname === ADMIN_HEARTH_IMAGE_PATH) {
+        if (req.method !== 'POST') {
+            sendText(res, 405, 'method not allowed\n');
+            return;
+        }
+        await respondAdminHearthImage(req, res, db);
+        return;
+    }
     if (DYNAMIC_ROUTE_PATHS.has(url.pathname)) {
         const route = findDynamicRoute(req.method, url.pathname);
         if (route === undefined) {

package/dist/hearth/control-plane/serving.d.ts

@@ -0,0 +1,15 @@
+import type { HomeId } from './types.js';
+export declare function beginHttp(id: HomeId): void;
+export declare function endHttp(id: HomeId): void;
+export declare function beginWs(id: HomeId): void;
+export declare function endWs(id: HomeId): void;
+export declare function beginOAuth(id: HomeId): void;
+export declare function endOAuth(id: HomeId): void;
+/** Is `id` currently serving — any active relay HTTP request, any open relay
+ *  WebSocket bridge, or a live (non-stale) OAuth start->finish window? This is
+ *  the ONLY signal `wake.ts`'s `homeIsServing` consults — it does not depend
+ *  on `resolveRunning`/`WARM_VERDICT_TTL_MS` at all. */
+export declare function isHomeServing(id: HomeId): boolean;
+/** Test/smoke-script hygiene only — production never needs this (one CP
+ *  process, S2, and every counter self-clears on its own end/dec path). */
+export declare function resetServingForTests(): void;

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

@@ -0,0 +1,106 @@
+// control-plane/serving.ts — CP-layer active-session tracker, independent of
+// the wake path's warm-verdict TTL.
+//
+// `wake.ts`'s `resolveRunning`/`WARM_VERDICT_TTL_MS` answers "did we recently
+// confirm this home is up" for exactly 10s — a cheap fast-path cache, not a
+// live-session signal. A destructive roll must never fire while a home has
+// an open browser/broker WebSocket, an in-flight HTTP request, or an open
+// OAuth start->finish window, no matter how long that session has been
+// running (design §3's "no active turn / no in-flight OAuth" safety
+// invariant).
+//
+// Three independent live-count maps, keyed by HomeId, are bumped directly at
+// the relay's HTTP/WS lifecycle seams and at the CP's OAuth start/finish
+// dispatch — NOT derived from any cache/TTL. A home is "serving" whenever
+// any one of them is non-zero. Single CP process (S2), in-process only, no
+// persistence — a CP restart naturally drops to zero, which is correct (a
+// fresh process has no in-flight anything).
+const httpInflight = new Map();
+const wsOpen = new Map();
+const oauthInProgress = new Map();
+// Timestamp of the most recent `beginOAuth` call for this home — the TTL
+// clock for the bounded-safety rule below. Refreshed on every `beginOAuth`,
+// so each new `start` gets its own full TTL window regardless of how stale
+// an earlier, still-uncompleted start's marker had become. Cleared once the
+// counter returns to 0 (no window is open, nothing to bound).
+const oauthStartedAt = new Map();
+// Bounded safety — "do not let a dropped OAuth pin a home un-rollable
+// forever": a `start` with no matching `finish` (browser tab closed
+// mid-flow, network drop, abandoned auth) must not hold `isHomeServing` true
+// indefinitely. Chose a TTL over a "clear on idle" scheme because idle here
+// has no other natural signal to key off (no heartbeat on the OAuth lane)
+// and a TTL is simplest to reason about / test. 5 minutes is generous for a
+// real human completing an OAuth redirect+approve+callback round trip (the
+// M0 in-guest flow is a single localhost redirect, seconds in the happy
+// path) while still bounding the worst case to a single-digit-minutes window
+// rather than forever.
+const OAUTH_MARKER_TTL_MS = 5 * 60_000;
+function inc(map, id) {
+    map.set(id, (map.get(id) ?? 0) + 1);
+}
+function dec(map, id) {
+    const current = map.get(id) ?? 0;
+    const next = current - 1;
+    if (next <= 0) {
+        map.delete(id);
+    }
+    else {
+        map.set(id, next);
+    }
+}
+export function beginHttp(id) {
+    inc(httpInflight, id);
+}
+export function endHttp(id) {
+    dec(httpInflight, id);
+}
+export function beginWs(id) {
+    inc(wsOpen, id);
+}
+export function endWs(id) {
+    dec(wsOpen, id);
+}
+export function beginOAuth(id) {
+    // Every real OAuth `start` is a fresh auth window and earns its own full
+    // TTL, not just the first one since the counter hit 0 — otherwise a stale,
+    // abandoned start's marker would age out from under a brand-new retry that
+    // shares its counter, letting that retry's own wake see `!isHomeServing`.
+    oauthStartedAt.set(id, Date.now());
+    inc(oauthInProgress, id);
+}
+export function endOAuth(id) {
+    dec(oauthInProgress, id);
+    if ((oauthInProgress.get(id) ?? 0) === 0)
+        oauthStartedAt.delete(id);
+}
+/** Is an OAuth window open for `id` right now, per the counter, and still
+ *  within the bounded-safety TTL of the MOST RECENT `beginOAuth`? A marker
+ *  past TTL is treated as stale (does NOT count as serving) so a dropped
+ *  `start` can't pin a home un-rollable forever; the counter itself is left
+ *  alone (an eventual late `finish` still decrements it correctly, and `dec`
+ *  floors at 0 regardless), and a later `beginOAuth` on the same counter
+ *  refreshes the timestamp so its own window is judged live. */
+function oauthMarkerLive(id) {
+    const count = oauthInProgress.get(id) ?? 0;
+    if (count <= 0)
+        return false;
+    const startedAt = oauthStartedAt.get(id);
+    if (startedAt === undefined)
+        return true; // defensive: count>0 with no timestamp — treat as live
+    return Date.now() - startedAt < OAUTH_MARKER_TTL_MS;
+}
+/** Is `id` currently serving — any active relay HTTP request, any open relay
+ *  WebSocket bridge, or a live (non-stale) OAuth start->finish window? This is
+ *  the ONLY signal `wake.ts`'s `homeIsServing` consults — it does not depend
+ *  on `resolveRunning`/`WARM_VERDICT_TTL_MS` at all. */
+export function isHomeServing(id) {
+    return (httpInflight.get(id) ?? 0) > 0 || (wsOpen.get(id) ?? 0) > 0 || oauthMarkerLive(id);
+}
+/** Test/smoke-script hygiene only — production never needs this (one CP
+ *  process, S2, and every counter self-clears on its own end/dec path). */
+export function resetServingForTests() {
+    httpInflight.clear();
+    wsOpen.clear();
+    oauthInProgress.clear();
+    oauthStartedAt.clear();
+}

package/dist/hearth/control-plane/types.d.ts

@@ -64,3 +64,23 @@ export interface TenantSession {
     tenant_id: TenantId;
     user_id: UserId;
 }
+/** The single global auto-upgrade target row (`hearth_target`, db.ts v9).
+ *  `channel` is always `'home'` (single-tenant, one image line). The DESIRED
+ *  crtr version/image the fleet rolls onto; `home.template_version` is the
+ *  ACTUAL running version. `last_bad_target_version`, when set, is a release
+ *  whose live roll already failed — the wake-path stale predicate excludes it
+ *  so no home re-rolls onto it until the target advances. */
+export interface HearthTarget {
+    channel: 'home';
+    target_template_version: string;
+    target_image_ref: string;
+    published_at: string;
+    source: string;
+    last_bad_target_version: string | null;
+}
+export interface SetHearthTargetInput {
+    target_template_version: string;
+    target_image_ref: string;
+    source: string;
+    published_at?: string;
+}

package/dist/hearth/control-plane/wake.d.ts

@@ -1,7 +1,8 @@
 import { type HomeBackend } from '../../core/hearth/provider.js';
 import type { M0Config } from '../../core/hearth/types.js';
 import { type ControlPlaneConfig } from './config.js';
-import { getHomeById, refreshProviderPointers, setHomeStatus, touchReady, touchWake } from './registry.js';
+import { getHearthTarget, recordBadTarget } from './hearth-target.js';
+import { getHomeById, refreshProviderPointers, setHealthVerdict, setHomeStatus, touchReady, touchWake } from './registry.js';
 import { resolveSecret } from './secrets.js';
 import type { HomeId, HomeStatus } from './types.js';
 export interface WakeResult {
@@ -40,8 +41,11 @@ declare function probeNodeReady(previewEndpoint: string, target: string, relayTo
  *  never reassigns these; only ad hoc verification scripts do. */
 export declare const wakeInternals: {
     getHomeById: typeof getHomeById;
+    getHearthTarget: typeof getHearthTarget;
+    recordBadTarget: typeof recordBadTarget;
     refreshProviderPointers: typeof refreshProviderPointers;
     setHomeStatus: typeof setHomeStatus;
+    setHealthVerdict: typeof setHealthVerdict;
     touchWake: typeof touchWake;
     touchReady: typeof touchReady;
     resolveSecret: typeof resolveSecret;
@@ -64,10 +68,12 @@ export declare function invalidateWarmVerdict(home_id: HomeId): void;
 /** Clear all warm verdicts and in-flight wake coalescing. Test/smoke-script
  *  hygiene only — production never needs this (one CP process, S2). */
 export declare function resetWakeCacheForTests(): void;
+export declare function serializeError(error: unknown): string;
 /** 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, and returns
+ *  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).