@crouton-kit/crouter 0.3.38 → 0.3.39

package/dist/core/hearth/providers/blaxel.d.ts

@@ -7,6 +7,7 @@ interface BlaxelMachineProviderOptions {
     templateVersion?: string;
     volumeSizeGb?: number;
 }
+export declare function isMissingResourceError(error: unknown): boolean;
 export declare class BlaxelMachineProvider implements MachineProvider {
     readonly providerName: "blaxel";
     readonly imageRef: string;
@@ -18,6 +19,9 @@ export declare class BlaxelMachineProvider implements MachineProvider {
         name: string;
     }): Promise<VolumeRef>;
     createMachine(input: CreateMachineInput): Promise<MachineRef>;
+    listMachines(filter?: {
+        externalId?: string;
+    }): Promise<MachineRef[]>;
     getMachine(machineId: string): Promise<MachineRef>;
     exec(machineId: string, input: ExecInput): Promise<ExecResult>;
     waitForPort(machineId: string, port: number, opts?: {
@@ -27,5 +31,6 @@ export declare class BlaxelMachineProvider implements MachineProvider {
     health(): Promise<HealthResult>;
     destroy(machineId: string): Promise<DestroyOutcome>;
     destroyVolume(volumeId: string): Promise<DestroyOutcome>;
+    getVolumeAttachment(volumeId: string): Promise<string | null>;
 }
 export {};

package/dist/core/hearth/providers/blaxel.js

@@ -1,6 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { readFileSync } from 'node:fs';
-import { SandboxInstance, VolumeInstance } from '@blaxel/core';
+import { SandboxInstance, VolumeInstance, getVolume, listSandboxes } from '@blaxel/core';
 import { general } from '../../errors.js';
 const TERMINATED_STATES = new Set(['TERMINATED', 'DELETING', 'DEACTIVATED', 'DEACTIVATING', 'FAILED']);
 const PROVISIONING_STATES = new Set(['UPLOADING', 'BUILDING', 'DEPLOYING', 'BUILT']);
@@ -81,10 +81,28 @@ function resolveExecCommand(input) {
     }
     return argv.map(shellQuote).join(' ');
 }
-function isMissingResourceError(error) {
-    const message = error instanceof Error ? error.message : String(error);
+// The Blaxel SDK (@blaxel/core 0.2.94) does not always reject with an `Error` instance — a 404
+// comes back as a plain object (e.g. `{code:404,error:"Sandbox not found"}`), and `String()` on
+// such an object yields the useless literal "[object Object]", which matches none of the regex
+// below. Recognize the structured shape directly (a numeric-or-string `404` status field) AND
+// fall back to JSON-serializing the value (mirroring wake.ts's `serializeError`) before running
+// the message regex, so both an `Error("... not found")` and a plain-object 404 are caught.
+export function isMissingResourceError(error) {
+    const fields = record(error);
+    if (fields !== null) {
+        for (const key of ['code', 'status', 'status_code', 'statusCode']) {
+            const value = fields[key];
+            if (value === 404 || value === '404')
+                return true;
+        }
+    }
+    const message = error instanceof Error ? error.message : (JSON.stringify(error) ?? String(error));
     return /\b(not found|404|does not exist|missing)\b/i.test(message);
 }
+// Accepts either a live `SandboxInstance` or a raw wire `Sandbox` page item — only the
+// `metadata`/`status`/`spec` fields are read, so mapping raw list pages avoids constructing
+// `SandboxInstance`s (whose `list()` eagerly warms an H2 session per sandbox — pointless for a
+// destroy sweep).
 function toMachineRef(sandbox) {
     const metadata = sandbox.metadata;
     const status = sandbox.status ?? undefined;
@@ -142,7 +160,16 @@ export class BlaxelMachineProvider {
     async createMachine(input) {
         const sandbox = await SandboxInstance.createIfNotExists({
             name: input.name ?? input.tenantId,
-            image: this.config.image,
+            // Tag every sandbox with the home's stable volume id so the recreate sweep can scope its
+            // destructive list to this home's family only (orphan-cleanup-fix MAJOR-1). Unset on
+            // callers that pass no externalId.
+            ...(input.externalId === undefined ? {} : { externalId: input.externalId }),
+            // A targeted recreate (auto-upgrade roll / rollback, design §4.1) passes
+            // an explicit `image`; the normal provision/wake path leaves it unset
+            // and uses the provider's construction-time config image. `createIfNotExists`
+            // only honors this on genuine creation — the roll path destroys the old
+            // sandbox first so the name is free (blaxel-home.ts `recreateOnImage`).
+            image: input.image ?? this.config.image,
             memory: this.config.memory,
             region: this.config.region,
             volumes: input.volumeMount === undefined || input.volumeMount === null ? undefined : [{ name: input.volumeMount.volumeName, mountPath: input.volumeMount.path, readOnly: false }],
@@ -158,6 +185,38 @@ export class BlaxelMachineProvider {
         await sandbox.wait({ maxWait: 90_000, interval: 500 }).catch(() => sandbox);
         return toMachineRef(sandbox);
     }
+    // orphan-cleanup-fix.md §3.2 + MAJOR-1/MINOR-1: the deterministic name-family sweep enumerates
+    // a home's generations via LIST scoped to the caller-owned `externalId` tag, then destroys the
+    // ones whose name is in the family. Over-listing is harmless — a FAILED/detached record still
+    // shows up here and destroy tolerates not_found, which is exactly what closes the autonomous-
+    // standby-detach orphan gap. Drives the generated `listSandboxes` client directly (bypassing
+    // `SandboxInstance.list()`, which never follows a cursor and warms an H2 session per sandbox):
+    // loops until exhausted so a future SDK version crossing Blaxel-Version 2026-04-28 (cursor
+    // pagination, 50/page) cannot silently truncate the sweep to page 1. At the SDK's pinned
+    // 2026-04-16 the server returns a bare array (the full set) and the loop breaks on the first
+    // page.
+    async listMachines(filter) {
+        const machines = [];
+        let cursor;
+        for (;;) {
+            const { data: raw } = await listSandboxes({
+                query: {
+                    limit: 200,
+                    ...(cursor === undefined ? {} : { cursor }),
+                    ...(filter?.externalId === undefined ? {} : { externalId: filter.externalId }),
+                },
+                throwOnError: true,
+            });
+            const page = Array.isArray(raw) ? raw : (raw?.data ?? []);
+            machines.push(...page.map(toMachineRef));
+            if (Array.isArray(raw))
+                break; // legacy bare array (Blaxel-Version < 2026-04-28) = full set
+            cursor = raw?.meta?.nextCursor || undefined; // empty when there are no more pages
+            if (cursor === undefined)
+                break;
+        }
+        return machines;
+    }
     async getMachine(machineId) {
         try {
             const sandbox = await SandboxInstance.get(machineId);
@@ -279,4 +338,27 @@ export class BlaxelMachineProvider {
             throw error;
         }
     }
+    // recreate-race-fix.md §3.1: read the platform's own positive attachment signal
+    // (`Volume.state.attachedTo`) rather than inferring detach from a sandbox GET/delete —
+    // that read/create consistency split is exactly what raced the old same-name recreate.
+    // `VolumeInstance.get`'s backing `volume` field is TS-private (no public state getter
+    // in @blaxel/core 0.2.94), so this calls the underlying `getVolume` SDK function
+    // directly instead — same request `VolumeInstance.get` makes, with `state` exposed.
+    // A 404 (or any other failure) throws, wrapped with the volumeId for context: a missing
+    // home volume is a real incident, never something to continue past (volume-is-sacred).
+    async getVolumeAttachment(volumeId) {
+        let attachedTo;
+        try {
+            const { data } = await getVolume({ path: { volumeName: volumeId }, throwOnError: true });
+            attachedTo = data.state?.attachedTo;
+        }
+        catch (error) {
+            throw general(`blaxel volume ${volumeId} attachment check failed`, {
+                volumeId,
+                cause: error instanceof Error ? error.message : String(error),
+            });
+        }
+        const trimmed = (attachedTo ?? '').trim();
+        return trimmed === '' ? null : trimmed;
+    }
 }

package/dist/core/hearth/providers/types.d.ts

@@ -22,10 +22,12 @@ export interface VolumeRef {
 }
 export interface CreateMachineInput {
     tenantId: string;
+    externalId?: string;
     template?: string | null;
     envs?: Record<string, string>;
     enableNetwork?: boolean;
     name?: string | null;
+    image?: string | null;
     ports?: {
         target: number;
         protocol: 'HTTP';
@@ -65,6 +67,16 @@ export interface MachineProvider {
     }): Promise<VolumeRef>;
     createMachine(input: CreateMachineInput): Promise<MachineRef>;
     getMachine(machineId: MachineId): Promise<MachineRef>;
+    /** List machine records, optionally scoped to a caller-owned `externalId` tag. The recreate
+     *  cleanup sweep passes the home's `providerVolumeId` as the filter so only sandboxes Hearth
+     *  itself tagged for this home come back, then intersects that with the generation NAME FAMILY
+     *  matcher — a tag∩name intersection on a destructive op, so no id-format or workspace name
+     *  discipline is load-bearing for other homes' safety (orphan-cleanup-fix MAJOR-1). The result
+     *  is NOT a promise of every machine in the workspace; without a filter it lists broadly, with
+     *  one it lists only tagged matches. Implementations must page until exhausted (MINOR-1). */
+    listMachines(filter?: {
+        externalId?: string;
+    }): Promise<MachineRef[]>;
     exec(machineId: MachineId, input: ExecInput): Promise<ExecResult>;
     waitForPort(machineId: MachineId, port: number, opts?: {
         maxWaitMs?: number;
@@ -73,5 +85,9 @@ export interface MachineProvider {
     health(): Promise<HealthResult>;
     destroy(machineId: MachineId): Promise<DestroyOutcome>;
     destroyVolume(volumeId: string): Promise<DestroyOutcome>;
+    /** The resource currently holding this volume ("sandbox:<name>"), or null if detached.
+     *  A missing volume (404) throws — a home volume disappearing is always an incident,
+     *  never something to continue past (recreate-race-fix.md §3.1). */
+    getVolumeAttachment(volumeId: string): Promise<string | null>;
 }
 export type { MachineState, M0Config, RouteRef };

package/dist/hearth/control-plane/__tests__/error-serialization.test.d.ts

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

package/dist/hearth/control-plane/__tests__/error-serialization.test.js

@@ -0,0 +1,29 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+// Bug-regression test (independent review of commit 6018050, recreate-race-fix.md §3.6):
+// `JSON.stringify` returns `undefined` (does not throw) for `undefined`, a function, or a
+// symbol — a naive `JSON.stringify(error)` rider would silently hand that `undefined` back to
+// callers. In `relay.ts` that `undefined` message then makes `message.startsWith('relay ')`
+// THROW inside the very catch block meant to handle it (a control-flow regression §3.6
+// promised not to introduce); in `wake.ts` it would OMIT the `error` field from the
+// `hearth.roll.incident` JSON line entirely. Both serializers must fall back to `String`
+// whenever `JSON.stringify` yields `undefined`, not only when it throws.
+test('serializeError (wake.ts) never returns undefined for undefined/function/symbol rejections', async () => {
+    const { serializeError } = await import('../wake.js');
+    for (const value of [undefined, function unnamed() { }, Symbol('boom')]) {
+        const result = serializeError(value);
+        assert.equal(typeof result, 'string', `serializeError(${String(value)}) must return a string, never JS \`undefined\``);
+        assert.ok(result.length > 0, `serializeError(${String(value)}) must be a non-empty string`);
+    }
+});
+test('serializeRelayError (relay.ts) never returns undefined for undefined/function/symbol rejections, and the relay control-flow checks it feeds never throw', async () => {
+    const { serializeRelayError } = await import('../relay.js');
+    for (const value of [undefined, function unnamed() { }, Symbol('boom')]) {
+        const result = serializeRelayError(value);
+        assert.equal(typeof result, 'string');
+        assert.ok(result.length > 0, `serializeRelayError(${String(value)}) must be a non-empty string`);
+        // The exact control flow `proxyHttp`'s catch runs on this value — must not throw.
+        assert.doesNotThrow(() => result.startsWith('relay '));
+        assert.doesNotThrow(() => /timed out/i.test(result));
+    }
+});

package/dist/hearth/control-plane/__tests__/oauth-serving-marker.test.d.ts

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

package/dist/hearth/control-plane/__tests__/oauth-serving-marker.test.js

@@ -0,0 +1,44 @@
+// Regression test for the P2 review Major fix: a stale, abandoned OAuth
+// marker must not make a later `beginOAuth` on the same home read as
+// non-serving. See serving.ts's `beginOAuth`/`oauthMarkerLive`.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mock } from 'node:test';
+import { beginOAuth, endOAuth, isHomeServing, resetServingForTests } from '../serving.js';
+const HOME = 'home-oauth-marker-test';
+const OAUTH_MARKER_TTL_MS = 5 * 60_000;
+test('a second beginOAuth refreshes a stale marker and stays live until both finishes land', () => {
+    resetServingForTests();
+    mock.timers.enable({ apis: ['Date'] });
+    try {
+        // Start A begins an OAuth window; it is immediately serving.
+        beginOAuth(HOME);
+        assert.equal(isHomeServing(HOME), true, 'start A should mark the home as serving');
+        // Start A is abandoned: advance the clock past the 5-minute TTL with no
+        // matching endOAuth. The marker goes stale, but the counter (1) is still
+        // positive because start A was never finished.
+        mock.timers.tick(OAUTH_MARKER_TTL_MS + 1_000);
+        assert.equal(isHomeServing(HOME), false, 'a stale marker with no refresh must read as not-serving');
+        // Start B is a fresh retry on the same home. Per the fix, beginOAuth
+        // refreshes oauthStartedAt on EVERY call, not only when the counter
+        // transitions from 0 — so B's own window must read as live immediately.
+        beginOAuth(HOME);
+        assert.equal(isHomeServing(HOME), true, 'a second beginOAuth must refresh the marker and read as serving');
+        // B's window survives well past when A's original (unrefreshed) TTL
+        // would have expired, proving the refresh — not the original timestamp
+        // — is what's being judged now.
+        mock.timers.tick(OAUTH_MARKER_TTL_MS - 1_000);
+        assert.equal(isHomeServing(HOME), true, 'B\'s window must still be live before its own TTL elapses');
+        // A late finish for start A arrives: counter floors from 2 -> 1. Still
+        // serving, because B's own start/finish window has not closed yet.
+        endOAuth(HOME);
+        assert.equal(isHomeServing(HOME), true, 'one matched finish (of two starts) must not end serving early');
+        // B finishes: counter 1 -> 0, marker cleared, no longer serving.
+        endOAuth(HOME);
+        assert.equal(isHomeServing(HOME), false, 'both starts matched by a finish must end serving');
+    }
+    finally {
+        mock.timers.reset();
+        resetServingForTests();
+    }
+});

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

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

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;