@crouton-kit/crouter 0.3.38 → 0.3.40

package/dist/hearth/control-plane/__tests__/wake-roll.test.js

@@ -0,0 +1,230 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+// Bug-regression tests for recreate-race-fix.md §3.3/§3.5: under generation naming, a roll
+// or rollback recreate destroys the PRE-recreate sandbox and creates a fresh-named one.
+// `rollHome`/`rollbackHome` must assert the in-guest `crtr sys version` against the sandbox
+// name the recreate ACTUALLY reports (`refresh.providerSandboxId`) — asserting against a
+// `sandboxName` captured from `home.provider_sandbox_id` at entry (the pre-fix behavior)
+// would exec into the already-destroyed old generation instead. These tests fail if that
+// regresses (they pin the exec target, not just that the call succeeds).
+function fixtureHome(overrides = {}) {
+    return {
+        home_id: 'home-1',
+        tenant_id: 't1',
+        user_id: 'u1',
+        provider: 'blaxel',
+        provider_sandbox_id: 'hearth-home-1',
+        provider_volume_id: 'vol-home-1',
+        preview_endpoint: 'https://old.example',
+        home_agent_target: 'node-1',
+        relay_auth_ref: 'ref-1',
+        status: 'running',
+        template_version: '0.3.35',
+        last_ready_at: null,
+        last_wake_at: null,
+        last_suspend_at: null,
+        last_wake_latency_ms: null,
+        health_verdict: 'healthy',
+        created_at: '2026-07-01T00:00:00.000Z',
+        updated_at: '2026-07-01T00:00:00.000Z',
+        ...overrides,
+    };
+}
+function fixtureTarget(overrides = {}) {
+    return {
+        channel: 'home',
+        target_template_version: '0.3.36',
+        target_image_ref: 'crouter-hearth-home-0-3-36',
+        published_at: '2026-07-01T00:00:00.000Z',
+        source: 'test',
+        last_bad_target_version: null,
+        ...overrides,
+    };
+}
+test('a successful plain (non-roll) wake clears a stale degraded health verdict to healthy', async () => {
+    const { ensureAwake, wakeInternals, resetWakeCacheForTests } = await import('../wake.js');
+    const orig = { ...wakeInternals };
+    resetWakeCacheForTests();
+    const home = fixtureHome({ home_id: 'home-plain-wake', provider_sandbox_id: 'hearth-home-plain-wake', health_verdict: 'degraded' });
+    let healthVerdict = null;
+    wakeInternals.getHomeById = ((id) => (id === home.home_id ? home : null));
+    // No hearth target registered, so runEnsureAwake takes the normal wake path, not the roll branch.
+    wakeInternals.getHearthTarget = (() => null);
+    wakeInternals.resolveSecret = (() => 'relay-token');
+    wakeInternals.loadM0Config = (() => ({}));
+    wakeInternals.loadControlPlaneConfig = (() => ({ readyTimeoutMs: 1_000 }));
+    wakeInternals.probeNodeReady = (async () => true);
+    wakeInternals.setHomeStatus = (() => home);
+    wakeInternals.setHealthVerdict = ((_id, verdict) => {
+        healthVerdict = verdict;
+        return home;
+    });
+    wakeInternals.touchWake = (() => home);
+    wakeInternals.touchReady = (() => home);
+    wakeInternals.getHomeBackend = (() => ({
+        wake: async () => ({
+            providerName: 'blaxel',
+            providerSandboxId: home.provider_sandbox_id,
+            providerVolumeId: 'vol-home-1',
+            previewEndpoint: home.preview_endpoint,
+            route: null,
+            homeAgentTarget: 'node-1',
+            relayAuthRef: null,
+            templateVersion: home.template_version,
+            status: 'running',
+            machine: null,
+            updatedAt: new Date().toISOString(),
+        }),
+        recreateOnImage: async () => {
+            throw new Error('recreateOnImage must not be called on the plain-wake path');
+        },
+        suspend: async () => {
+            throw new Error('unused');
+        },
+        getMachine: async () => null,
+        exec: async () => {
+            throw new Error('exec must not be called on the plain-wake path');
+        },
+    }));
+    try {
+        const result = await ensureAwake(home.home_id);
+        assert.equal(result.preview_endpoint, home.preview_endpoint);
+        assert.equal(healthVerdict, 'healthy', 'a successful plain wake must clear a stale degraded verdict to healthy');
+    }
+    finally {
+        Object.assign(wakeInternals, orig);
+        resetWakeCacheForTests();
+    }
+});
+test('rollHome asserts guest version against the RECREATED sandbox name, not the stale pre-roll name', async () => {
+    const { ensureAwake, wakeInternals, resetWakeCacheForTests } = await import('../wake.js');
+    const orig = { ...wakeInternals };
+    resetWakeCacheForTests();
+    const execCalls = [];
+    const home = fixtureHome({ home_id: 'home-roll-ok', provider_sandbox_id: 'hearth-home-roll-ok' });
+    const target = fixtureTarget();
+    const freshName = 'hearth-home-roll-ok-gfresh1';
+    wakeInternals.getHomeById = ((id) => (id === home.home_id ? home : null));
+    wakeInternals.getHearthTarget = (() => target);
+    wakeInternals.resolveSecret = (() => 'relay-token');
+    wakeInternals.loadM0Config = (() => ({}));
+    wakeInternals.loadControlPlaneConfig = (() => ({ readyTimeoutMs: 1_000 }));
+    wakeInternals.probeNodeReady = (async () => true);
+    wakeInternals.refreshProviderPointers = ((_id, patch) => ({ ...home, ...patch }));
+    wakeInternals.setHomeStatus = (() => home);
+    wakeInternals.setHealthVerdict = (() => home);
+    wakeInternals.touchWake = (() => home);
+    wakeInternals.touchReady = (() => home);
+    wakeInternals.recordBadTarget = (() => null);
+    wakeInternals.getHomeBackend = (() => ({
+        wake: async () => {
+            throw new Error('wake() must not be called on the roll path');
+        },
+        recreateOnImage: async () => ({
+            providerName: 'blaxel',
+            providerSandboxId: freshName,
+            providerVolumeId: 'vol-home-1',
+            previewEndpoint: 'https://new.example',
+            route: null,
+            homeAgentTarget: 'node-1',
+            relayAuthRef: null,
+            templateVersion: target.target_template_version,
+            status: 'running',
+            machine: null,
+            updatedAt: new Date().toISOString(),
+        }),
+        suspend: async () => {
+            throw new Error('unused');
+        },
+        getMachine: async () => null,
+        exec: async (machineId) => {
+            execCalls.push(machineId);
+            return { exitCode: 0, timedOut: false, stdout: JSON.stringify({ version: target.target_template_version }), stderr: '' };
+        },
+    }));
+    try {
+        const result = await ensureAwake(home.home_id);
+        assert.equal(result.preview_endpoint, 'https://new.example');
+        assert.deepEqual(execCalls, [freshName], 'assertGuestVersion must exec into the RECREATED sandbox name, never the stale pre-roll name');
+    }
+    finally {
+        Object.assign(wakeInternals, orig);
+        resetWakeCacheForTests();
+    }
+});
+test('rollbackHome asserts guest version against the RECREATED rollback sandbox name, and rollback success sets healthy with no incident', async () => {
+    const { ensureAwake, wakeInternals, resetWakeCacheForTests } = await import('../wake.js');
+    const orig = { ...wakeInternals };
+    resetWakeCacheForTests();
+    const execCalls = [];
+    const home = fixtureHome({ home_id: 'home-roll-fail', provider_sandbox_id: 'hearth-home-roll-fail' });
+    const target = fixtureTarget();
+    const rollbackFreshName = 'hearth-home-roll-fail-gback1';
+    let recreateCalls = 0;
+    let badTargetRecorded = null;
+    let healthVerdict = null;
+    wakeInternals.getHomeById = ((id) => (id === home.home_id ? home : null));
+    wakeInternals.getHearthTarget = (() => target);
+    wakeInternals.resolveSecret = (() => 'relay-token');
+    wakeInternals.loadM0Config = (() => ({}));
+    wakeInternals.loadControlPlaneConfig = (() => ({ readyTimeoutMs: 1_000 }));
+    wakeInternals.probeNodeReady = (async () => true);
+    wakeInternals.refreshProviderPointers = ((_id, patch) => ({ ...home, ...patch }));
+    wakeInternals.setHomeStatus = (() => home);
+    wakeInternals.setHealthVerdict = ((_id, verdict) => {
+        healthVerdict = verdict;
+        return home;
+    });
+    wakeInternals.touchWake = (() => home);
+    wakeInternals.touchReady = (() => home);
+    wakeInternals.recordBadTarget = ((version) => {
+        badTargetRecorded = version;
+        return null;
+    });
+    wakeInternals.getHomeBackend = (() => ({
+        wake: async () => {
+            throw new Error('unused');
+        },
+        recreateOnImage: async (_descriptor, _imageRef, templateVersion) => {
+            recreateCalls += 1;
+            if (recreateCalls === 1) {
+                // Simulate the roll-forward recreate succeeding but the guest version assert
+                // failing downstream — rollHome's catch delegates to rollbackHome regardless of
+                // WHERE in the try it failed.
+                throw new Error('simulated roll failure (version mismatch)');
+            }
+            return {
+                providerName: 'blaxel',
+                providerSandboxId: rollbackFreshName,
+                providerVolumeId: 'vol-home-1',
+                previewEndpoint: 'https://rollback.example',
+                route: null,
+                homeAgentTarget: 'node-1',
+                relayAuthRef: null,
+                templateVersion,
+                status: 'running',
+                machine: null,
+                updatedAt: new Date().toISOString(),
+            };
+        },
+        suspend: async () => {
+            throw new Error('unused');
+        },
+        getMachine: async () => null,
+        exec: async (machineId) => {
+            execCalls.push(machineId);
+            return { exitCode: 0, timedOut: false, stdout: JSON.stringify({ version: home.template_version }), stderr: '' };
+        },
+    }));
+    try {
+        const result = await ensureAwake(home.home_id);
+        assert.equal(result.preview_endpoint, 'https://rollback.example');
+        assert.equal(badTargetRecorded, target.target_template_version, 'the roll failure must still poison the target (brake unconditional on roll failure)');
+        assert.equal(healthVerdict, 'healthy', 'a successful rollback must clear health to healthy, not leave/raise an incident');
+        assert.deepEqual(execCalls, [rollbackFreshName], "rollback must assert against ITS OWN recreated sandbox name — never the failed roll's name nor the stale pre-roll name");
+    }
+    finally {
+        Object.assign(wakeInternals, orig);
+        resetWakeCacheForTests();
+    }
+});

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

@@ -457,6 +457,32 @@ BEGIN
 END;
 `);
 }
+/** v9 — the single global auto-upgrade target (design.md §2/§9). ONE row,
+ *  `channel = 'home'`, holding the DESIRED crtr image line every home rolls
+ *  onto: `target_template_version` is the semver the fleet should be running,
+ *  `target_image_ref` its immutable Blaxel image name (must equal
+ *  `hearthHomeImageRefForVersion(target_template_version)` — the admin route
+ *  enforces that). `last_bad_target_version` is the ONLY brake in the
+ *  zero-touch loop: a version recorded here already failed a live roll for
+ *  the fleet, so the wake-path stale predicate excludes it until the target
+ *  advances to a newer release. There is deliberately NO `roll_armed` column
+ *  — the loop is full zero-touch (§9.1), so there is no per-release human arm
+ *  gate to persist. `home.template_version` stays the ACTUAL running version;
+ *  this row is the target. Single-tenant: one image line for all homes, so no
+ *  per-home target column. */
+function hearthTargetTable(db) {
+    db.exec(`
+CREATE TABLE IF NOT EXISTS hearth_target (
+  channel                  TEXT PRIMARY KEY DEFAULT 'home',
+  target_template_version  TEXT NOT NULL,
+  target_image_ref         TEXT NOT NULL,
+  published_at             TEXT NOT NULL,
+  source                   TEXT NOT NULL,
+  last_bad_target_version  TEXT,
+  CHECK (channel = 'home')
+);
+`);
+}
 /** The ordered migration list. Index `i` is migration version `i + 1`; the
  *  db's `user_version` tracks how many have been applied. Append only. */
 export const MIGRATIONS = [
@@ -468,6 +494,7 @@ export const MIGRATIONS = [
     /* v6 */ triggerAuditTable,
     /* v7 */ tenantIdentityTriggers,
     /* v8 */ parentIdentityUpdateGuards,
+    /* v9 */ hearthTargetTable,
 ];
 /** Bring `db` up to the latest schema version. Reads `user_version`, runs
  *  each pending migration in order, and bumps `user_version` after each so

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

@@ -0,0 +1,23 @@
+import { DatabaseSync } from 'node:sqlite';
+import type { HearthTarget, SetHearthTargetInput } from './types.js';
+/** Read the single global target row, or `null` when no image has ever been
+ *  registered (fresh CP). A `null` means the wake path treats every home as
+ *  up to date (nothing to roll onto yet). */
+export declare function getHearthTarget(db?: DatabaseSync): HearthTarget | null;
+/** Upsert the global target to a newly-registered image. IDEMPOTENT: a
+ *  re-post of the version already recorded is a no-op (the row, including its
+ *  `published_at` and any `last_bad_target_version` brake, is left exactly as
+ *  is) — the image workflow can fire the notify more than once for one
+ *  release without churning state. Advancing to a DIFFERENT version rewrites
+ *  the target/image/published_at/source but deliberately preserves
+ *  `last_bad_target_version` (a brake recorded for an older release is
+ *  historical and harmless once the target has moved past it; the wake
+ *  predicate keys off `target !== last_bad`). */
+export declare function setHearthTarget(input: SetHearthTargetInput, db?: DatabaseSync): HearthTarget;
+/** Record a version whose live roll failed for the fleet (§5.4). After this,
+ *  the wake-path stale predicate excludes the current target (target ===
+ *  last_bad_target_version → no home rolls) until a NEW release advances the
+ *  target past it. This is the ONLY brake in the zero-touch loop (roadmap
+ *  decision 1: never auto-advance onto a release that already failed a roll).
+ *  Returns `null` if no target row exists (nothing to brake). */
+export declare function recordBadTarget(badVersion: string, db?: DatabaseSync): HearthTarget | null;

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

@@ -0,0 +1,68 @@
+// control-plane/hearth-target.ts — the CP store for the single global
+// auto-upgrade target row (`hearth_target`, db.ts v9). One row, `channel =
+// 'home'`. This module is the ONLY reader/writer of that row; the admin
+// notify route (server.ts) upserts it, the wake path (wake.ts) reads it to
+// decide whether a home is stale, and the rollback path records a bad target
+// through it. It goes through the shared CP db handle (`getControlPlaneDb`)
+// exactly like `registry.ts` — never a second connection.
+import { getControlPlaneDb } from './db.js';
+const TARGET_COLUMNS = [
+    'channel',
+    'target_template_version',
+    'target_image_ref',
+    'published_at',
+    'source',
+    'last_bad_target_version',
+];
+const SELECT_TARGET = `SELECT ${TARGET_COLUMNS.join(', ')} FROM hearth_target WHERE channel = 'home'`;
+function nowIso() {
+    return new Date().toISOString();
+}
+/** Read the single global target row, or `null` when no image has ever been
+ *  registered (fresh CP). A `null` means the wake path treats every home as
+ *  up to date (nothing to roll onto yet). */
+export function getHearthTarget(db = getControlPlaneDb()) {
+    const row = db.prepare(SELECT_TARGET).get();
+    if (row === undefined || row === null)
+        return null;
+    return row;
+}
+/** Upsert the global target to a newly-registered image. IDEMPOTENT: a
+ *  re-post of the version already recorded is a no-op (the row, including its
+ *  `published_at` and any `last_bad_target_version` brake, is left exactly as
+ *  is) — the image workflow can fire the notify more than once for one
+ *  release without churning state. Advancing to a DIFFERENT version rewrites
+ *  the target/image/published_at/source but deliberately preserves
+ *  `last_bad_target_version` (a brake recorded for an older release is
+ *  historical and harmless once the target has moved past it; the wake
+ *  predicate keys off `target !== last_bad`). */
+export function setHearthTarget(input, db = getControlPlaneDb()) {
+    const existing = getHearthTarget(db);
+    if (existing !== null && existing.target_template_version === input.target_template_version) {
+        return existing;
+    }
+    const published_at = input.published_at ?? nowIso();
+    db.prepare(`
+INSERT INTO hearth_target (channel, target_template_version, target_image_ref, published_at, source, last_bad_target_version)
+VALUES ('home', ?, ?, ?, ?, NULL)
+ON CONFLICT(channel) DO UPDATE SET
+  target_template_version = excluded.target_template_version,
+  target_image_ref = excluded.target_image_ref,
+  published_at = excluded.published_at,
+  source = excluded.source
+`).run(input.target_template_version, input.target_image_ref, published_at, input.source);
+    return getHearthTarget(db);
+}
+/** Record a version whose live roll failed for the fleet (§5.4). After this,
+ *  the wake-path stale predicate excludes the current target (target ===
+ *  last_bad_target_version → no home rolls) until a NEW release advances the
+ *  target past it. This is the ONLY brake in the zero-touch loop (roadmap
+ *  decision 1: never auto-advance onto a release that already failed a roll).
+ *  Returns `null` if no target row exists (nothing to brake). */
+export function recordBadTarget(badVersion, db = getControlPlaneDb()) {
+    const existing = getHearthTarget(db);
+    if (existing === null)
+        return null;
+    db.prepare(`UPDATE hearth_target SET last_bad_target_version = ? WHERE channel = 'home'`).run(badVersion);
+    return getHearthTarget(db);
+}

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

@@ -1,5 +1,5 @@
 import { DatabaseSync } from 'node:sqlite';
-import type { CreateHomeInput, Home, HomeId, HomePatch, HomeStatus, RefreshProviderPointersInput, ResolvedHome, TenantSession, TouchWakeInput } from './types.js';
+import type { CreateHomeInput, Home, HomeHealthVerdict, HomeId, HomePatch, HomeStatus, RefreshProviderPointersInput, ResolvedHome, TenantSession, TouchWakeInput } from './types.js';
 export declare function createHome(input: CreateHomeInput, db?: DatabaseSync): Home;
 export declare function getHomeById(home_id: HomeId | null | undefined, db?: DatabaseSync): Home | null;
 /** Resolve a tenant session to its registry row. A null return is a hard
@@ -12,6 +12,11 @@ export declare function getHomeBySandbox(provider_sandbox_id: string | null | un
 export declare function updateHome(home_id: HomeId, mutate: (current: Home) => HomePatch, db?: DatabaseSync): Home;
 export declare function refreshProviderPointers(home_id: HomeId, pointers: RefreshProviderPointersInput, db?: DatabaseSync): Home;
 export declare function setHomeStatus(home_id: HomeId, status: HomeStatus, db?: DatabaseSync): Home;
+/** 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 declare function setHealthVerdict(home_id: HomeId, health_verdict: HomeHealthVerdict, db?: DatabaseSync): Home;
 export declare function touchWake(home_id: HomeId, input?: TouchWakeInput, db?: DatabaseSync): Home;
 export declare function touchReady(home_id: HomeId, at?: string, db?: DatabaseSync): Home;
 export declare function touchSuspend(home_id: HomeId, at?: string, db?: DatabaseSync): Home;

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