@crouton-kit/crouter 0.3.37 → 0.3.39

package/dist/core/config.js

@@ -1,7 +1,8 @@
 import { join } from 'node:path';
-import { CONFIG_FILE, STATE_FILE, defaultScopeConfig, defaultScopeState, defaultCanvasNavConfig, defaultModelLaddersConfig } from '../types.js';
+import { CONFIG_FILE, STATE_FILE, defaultScopeConfig, defaultScopeState, defaultCanvasNavConfig, defaultModelLaddersConfig, defaultKindsConfig } from '../types.js';
 import { readJsonIfExists, writeJson, ensureDir } from './fs-utils.js';
-import { scopeRoot, requireScopeRoot } from './scope.js';
+import { scopeRoot, requireScopeRoot, findProjectScopeRoots } from './scope.js';
+import { profileRoot } from './profiles/manifest.js';
 function configPathFor(root) {
     return join(root, CONFIG_FILE);
 }
@@ -150,14 +151,15 @@ function mergeCanvasNav(raw) {
         graphBinds: mergeBinds(defaults.graphBinds, r.graphBinds, normalizeGraphBind),
     };
 }
-function mergeModelLadders(raw) {
-    const defaults = defaultModelLaddersConfig();
+function mergeModelLadders(raw, base = defaultModelLaddersConfig()) {
+    const defaults = base;
     if (raw === null || typeof raw !== 'object')
         return defaults;
     const r = raw;
     const out = {
         anthropic: { ...defaults.anthropic },
         openai: { ...defaults.openai },
+        ...(defaults.defaultProvider !== undefined ? { defaultProvider: defaults.defaultProvider } : {}),
     };
     if (r.defaultProvider === 'anthropic' || r.defaultProvider === 'openai') {
         out.defaultProvider = r.defaultProvider;
@@ -174,13 +176,42 @@ function mergeModelLadders(raw) {
     }
     return out;
 }
-function mergePersonaStrengths(raw) {
-    const out = {};
+/** Validate one raw `kinds.<name>` entry into a `KindConfig`, or drop it
+ *  (return null) rather than throwing — an invalid kind entry in config.json
+ *  must not break config parsing for every other kind. `whenToUse` is the
+ *  only required field. */
+function normalizeKindEntry(raw) {
     if (raw === null || typeof raw !== 'object')
-        return out;
-    for (const [persona, value] of Object.entries(raw)) {
-        if (value === 'ultra' || value === 'strong' || value === 'medium' || value === 'light') {
-            out[persona] = value;
+        return null;
+    const r = raw;
+    if (typeof r.whenToUse !== 'string' || r.whenToUse.trim() === '')
+        return null;
+    const out = { whenToUse: r.whenToUse };
+    if (typeof r.model === 'string' && r.model.trim() !== '')
+        out.model = r.model;
+    if (typeof r.orchestratorModel === 'string' && r.orchestratorModel.trim() !== '')
+        out.orchestratorModel = r.orchestratorModel;
+    const isStringArray = (v) => Array.isArray(v) && v.every((item) => typeof item === 'string');
+    if (isStringArray(r.tools))
+        out.tools = r.tools;
+    if (isStringArray(r.extensions))
+        out.extensions = r.extensions;
+    if (isStringArray(r.availableTo))
+        out.availableTo = r.availableTo;
+    return out;
+}
+/** Merge a raw `kinds` block over `base` (defaulting to the builtin registry):
+ *  each valid entry adds or shadows a kind by name; invalid entries are
+ *  dropped, never thrown. Mirrors `mergeModelLadders`'s layer-over-defaults
+ *  shape so a user/project config.json can add or override a single kind
+ *  without restating the whole registry. */
+function mergeKinds(raw, base = defaultKindsConfig()) {
+    const out = { ...base };
+    if (raw !== null && typeof raw === 'object') {
+        for (const [kind, value] of Object.entries(raw)) {
+            const normalized = normalizeKindEntry(value);
+            if (normalized !== null)
+                out[kind] = normalized;
         }
     }
     return out;
@@ -215,8 +246,120 @@ function mergeConfig(partial) {
         : defaults.max_panes_per_window;
     const canvasNav = mergeCanvasNav(partial.canvasNav);
     const modelLadders = mergeModelLadders(partial.modelLadders);
-    const personaStrengths = mergePersonaStrengths(partial.personaStrengths);
-    return { schema_version, marketplaces, plugins, auto_update, max_panes_per_window, canvasNav, modelLadders, personaStrengths };
+    const kinds = mergeKinds(partial.kinds);
+    return { schema_version, marketplaces, plugins, auto_update, max_panes_per_window, canvasNav, modelLadders, kinds };
+}
+/** Raw (un-defaulted) partial config for one scope, or null if the scope has
+ *  no root or no config.json. Used by `readMergedLaunchConfig` to layer
+ *  scopes onto each other WITHOUT each scope's own default-fill masking a
+ *  lower-precedence scope's real customization (see that function's comment
+ *  for why `readConfig(scope)`, which already defaults-fills, is unusable
+ *  for cross-scope layering). */
+function readRawScopeConfig(scope) {
+    const root = scopeRoot(scope);
+    if (!root)
+        return null;
+    return readJsonIfExists(configPathFor(root));
+}
+/** Raw partial config at `<profileRoot(profileId)>/config.json`, or null when
+ *  no profile is selected, the profile id no longer resolves (deleted/
+ *  invalid), or it has no config.json. `profileRoot` centralizes the id-shape
+ *  + containment checks (never a raw path join), and any resolution failure
+ *  is swallowed here — launch config resolution is a hot path that must never
+ *  throw on a stale `CRTR_PROFILE_ID`. */
+function readRawProfileConfig(profileId) {
+    if (profileId === null || profileId === '')
+        return null;
+    try {
+        return readJsonIfExists(configPathFor(profileRoot(profileId)));
+    }
+    catch {
+        return null;
+    }
+}
+/** Raw partial configs for the whole project-scope STACK (`findProjectScopeRoots`
+ *  — every ancestor `.crouter/`, widened by a selected profile's `projects`),
+ *  ordered FARTHEST-first so `readMergedLaunchConfig` can layer them on last
+ *  and have the NEAREST root win — mirroring the resolver's nearest-project-
+ *  strongest replacement precedence. */
+function readRawProjectScopeConfigs() {
+    const nearestFirst = findProjectScopeRoots();
+    const farthestFirst = [...nearestFirst].reverse();
+    const out = [];
+    for (const root of farthestFirst) {
+        const raw = readJsonIfExists(configPathFor(root));
+        if (raw !== null)
+            out.push(raw);
+    }
+    return out;
+}
+/** Merge launch knobs (`kinds`, `modelLadders`) across scopes in
+ *  project stack > profile > user > builtin precedence — the same precedence
+ *  order used for memory resolution. A kind or ladder cell declared at a
+ *  more-specific scope shadows the same key from a less-specific scope; the
+ *  project STACK (`findProjectScopeRoots` — every ancestor `.crouter/`,
+ *  widened by a selected profile's `projects`) layers nearest-root-strongest;
+ *  a key no scope declares falls through to the builtin default registry
+ *  (`defaultScopeConfig().kinds` / `.modelLadders`).
+ *
+ *  Layers RAW (un-defaulted) partial config per scope, not `readConfig(scope)`
+ *  — `readConfig` already fills in every default kind for a scope that
+ *  customizes even one, so naively overlaying two already-defaulted
+ *  `ScopeConfig.kinds` objects would let an untouched project-scope kind
+ *  (silently defaulted) clobber a real user-scope customization of that same
+ *  kind. Layering the raw partials avoids that.
+ *
+ *  Callers (launch, kind registry) go through this function rather than
+ *  `readConfig` directly, so `ScopeConfig.kinds`/`modelLadders`/tools/
+ *  extensions/`availableTo` all honor the same profile + multi-project
+ *  precedence. */
+export function readMergedLaunchConfig() {
+    const defaults = defaultScopeConfig();
+    const userRaw = readRawScopeConfig('user');
+    const profileRaw = readRawProfileConfig(process.env['CRTR_PROFILE_ID'] || null);
+    const projectRawsFarthestFirst = readRawProjectScopeConfigs();
+    let kinds = mergeKinds(userRaw?.kinds, defaults.kinds);
+    let modelLadders = mergeModelLadders(userRaw?.modelLadders, defaults.modelLadders);
+    if (profileRaw !== null) {
+        kinds = mergeKinds(profileRaw.kinds, kinds);
+        modelLadders = mergeModelLadders(profileRaw.modelLadders, modelLadders);
+    }
+    for (const raw of projectRawsFarthestFirst) {
+        kinds = mergeKinds(raw.kinds, kinds);
+        modelLadders = mergeModelLadders(raw.modelLadders, modelLadders);
+    }
+    return { kinds, modelLadders };
+}
+/** The effective `KindConfig` for one full kind string (top-level, e.g.
+ *  `developer`, or sub-kind, e.g. `plan/reviewers/security`), across
+ *  project > user > builtin precedence. Returns `undefined` for a kind no
+ *  scope registers — existence is deliberately NOT validated here (kind
+ *  existence/launch-menu enumeration is a Phase 3 caller concern); this only
+ *  resolves the config for a kind the caller already knows about. */
+export function resolveKindConfig(kind) {
+    return readMergedLaunchConfig().kinds[kind];
+}
+/** The sub-kinds available to spawn FROM a given top-level kind — every
+ *  registered sub-kind (full path contains `/`) whose `availableTo` (default:
+ *  its own top-level ancestor, e.g. `plan/reviewers/security` defaults to
+ *  `['plan']`) includes `kind` or `'*'`. The single source both `sys
+ *  prompt-review --list`'s `subPersonas` metadata and the live sub-persona
+ *  spawn-menu splice (`core/substrate/render.ts`) read, so the two can never
+ *  drift apart. Sorted by full kind name for stable rendering. */
+export function subKindsAvailableTo(kind) {
+    const registry = readMergedLaunchConfig().kinds;
+    const out = [];
+    for (const [full, cfg] of Object.entries(registry)) {
+        const slash = full.indexOf('/');
+        if (slash === -1)
+            continue;
+        const topAncestor = full.slice(0, slash);
+        const availableTo = cfg.availableTo ?? [topAncestor];
+        if (!(availableTo.includes('*') || availableTo.includes(kind)))
+            continue;
+        out.push({ kind: full, whenToUse: cfg.whenToUse });
+    }
+    return out.sort((a, b) => a.kind.localeCompare(b.kind));
 }
 export function updateConfig(scope, mutate) {
     const cfg = readConfig(scope);

package/dist/core/hearth/provider.d.ts

@@ -11,6 +11,14 @@ export interface HomeBackend {
      * and return refreshed provider pointers for the CP registry to persist.
      */
     wake(home: HomeProviderDescriptor): Promise<HomeProviderRefresh>;
+    /**
+     * Targeted destroy→recreate of a home onto a SPECIFIC image, reattaching the same durable
+     * volume (auto-upgrade roll and rollback, design §4/§5). Force-destroys the sandbox first so
+     * the recreate genuinely lands on `imageRef` (the volume is never touched), reboots the guest,
+     * and reports `templateVersion` for the CP to record. The caller independently asserts the
+     * running `crtr sys version` in-guest before trusting the flip.
+     */
+    recreateOnImage(home: HomeProviderDescriptor, imageRef: string, templateVersion: string): Promise<HomeProviderRefresh>;
     /** Pause the home and return refreshed provider pointers for the CP registry to persist. */
     suspend(home: HomeProviderDescriptor): Promise<HomeProviderRefresh>;
     /** Machine resources (cpu/mem) for status, or null when unavailable. */

package/dist/core/hearth/providers/__tests__/sweep-and-release.test.d.ts

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

package/dist/core/hearth/providers/__tests__/sweep-and-release.test.js

@@ -0,0 +1,254 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { BlaxelHomeBackend } from '../blaxel-home.js';
+import { isMissingResourceError } from '../blaxel.js';
+// Regression for the Run-3 orphan gap (orphan-cleanup-fix.md §1/§3.3): cleanup used a
+// point-in-time `attachedTo` read to find "the sandbox holding the volume", but Blaxel
+// autonomously drops that claim on idle→STANDBY, so a failed roll-forward generation that had
+// already been detached was invisible to cleanup and lived on as a billed, route-registered,
+// volume-claiming orphan. The fix destroys the entire generation NAME FAMILY via `listMachines`
+// with ZERO dependence on attachment state — so a family member NOT holding the volume must
+// still be destroyed, and a same-prefixed foreign name must NOT.
+const VOLUME_ID = 'hearth-zt-test-1';
+function makeConfig() {
+    return {
+        providerName: 'blaxel',
+        guestUser: 'agent',
+        guestHome: '/home/agent',
+        guestCodePath: '/home/agent/code',
+        piPackages: [],
+        webPort: 8080,
+        nodeKind: 'developer',
+        imageRef: 'crouter-hearth-home-0-3-35',
+        templateVersion: '0.3.35',
+    };
+}
+function makeDescriptor() {
+    return {
+        homeId: 'home-1',
+        tenantId: 'tenant-1',
+        providerName: 'blaxel',
+        providerSandboxId: `${VOLUME_ID}-gold`,
+        providerVolumeId: VOLUME_ID,
+        homeAgentTarget: 'guest-node-1',
+        relayToken: 'relay-token',
+    };
+}
+/** A fake provider whose `listMachines` HONORS the `externalId` filter over a tagged inventory:
+ *  the row-pointed generation, a DETACHED/standby family member NOT holding the volume (the Run-3
+ *  miss), a FAILED family record (a create that 500'd but left a row, e.g. Blaxel's `gmr…azqr`),
+ *  and the bare base name — all tagged `externalId = VOLUME_ID`. Plus survivors: a same-prefixed
+ *  FOREIGN home (`hearth-zt-test-10-…`, numeric-adjacent, spared by the `-g` anchor too); the
+ *  suffix-extension collision `<base>-gfoo` that IS in the name family but belongs to a DIFFERENT
+ *  home (tagged with its own volume id) — destroyed by the old name-only sweep, spared now by the
+ *  tag filter; and a same-name-family-but-UNTAGGED record (a legacy pre-backfill member, no
+ *  externalId) — excluded by the filter, so it survives as the alerted self-heals orphan class,
+ *  NOT a collateral destroy. Records every destroy target. */
+function makeFakeProvider(destroyed) {
+    const inventory = [
+        { ref: { providerName: 'blaxel', machineId: `${VOLUME_ID}-gold`, state: 'running' }, externalId: VOLUME_ID }, // row pointer
+        { ref: { providerName: 'blaxel', machineId: `${VOLUME_ID}-gdetached`, state: 'running' }, externalId: VOLUME_ID }, // detached standby orphan — the miss
+        { ref: { providerName: 'blaxel', machineId: `${VOLUME_ID}-gfailed`, state: 'terminated' }, externalId: VOLUME_ID }, // FAILED leftover record
+        { ref: { providerName: 'blaxel', machineId: VOLUME_ID, state: 'running' }, externalId: VOLUME_ID }, // bare base name
+        { ref: { providerName: 'blaxel', machineId: 'hearth-zt-test-10-gxyz', state: 'running' }, externalId: 'hearth-zt-test-10' }, // FOREIGN numeric-adjacent home, must survive
+        { ref: { providerName: 'blaxel', machineId: `${VOLUME_ID}-gfoo`, state: 'running' }, externalId: `${VOLUME_ID}-gfoo` }, // suffix-extension collision, DIFFERENT home — must survive
+        { ref: { providerName: 'blaxel', machineId: `${VOLUME_ID}-gstale`, state: 'running' } }, // same-name-family but UNTAGGED (legacy) — must survive
+        { ref: { providerName: 'blaxel', machineId: 'unrelated-sandbox', state: 'running' } }, // unrelated, must survive
+    ];
+    const fake = {
+        providerName: 'blaxel',
+        imageRef: 'crouter-hearth-home-0-3-35',
+        templateVersion: '0.3.35',
+        volumeSizeGb: 4,
+        async listMachines(filter) {
+            return inventory.filter((e) => filter?.externalId === undefined || e.externalId === filter.externalId).map((e) => e.ref);
+        },
+        async destroy(machineId) {
+            destroyed.push(machineId);
+            return { kind: 'destroyed' };
+        },
+        // Volume already free (Blaxel detached it) — the poll passes on the first read.
+        async getVolumeAttachment() {
+            return null;
+        },
+        async createMachine(input) {
+            return { providerName: 'blaxel', machineId: input.name ?? VOLUME_ID, state: 'running' };
+        },
+        async exec(_id, _input) {
+            return { exitCode: 0, timedOut: false, stdout: '', stderr: '' };
+        },
+        async waitForPort() { },
+        async publishHttpPort(machineId, input) {
+            return { routeId: input.routeName ?? `${machineId}-web`, machineId, targetPort: input.targetPort, url: `https://${machineId}.example` };
+        },
+        async getMachine(machineId) {
+            return { providerName: 'blaxel', machineId, state: 'running' };
+        },
+    };
+    return fake;
+}
+// Regression for the recovery-wake live re-proof (SHA 567cd4f, backfill-recovery-evidence.md §3):
+// the Blaxel SDK (@blaxel/core 0.2.94) rejects a not-found lookup with a PLAIN OBJECT
+// (`{code:404,error:"Sandbox not found"}`), not an `Error` instance. `String()` on that object
+// yields the literal "[object Object]", which matched none of the message regex, so the
+// predicate returned `false` for a genuine 404 — breaking the `getMachine` terminated-machine
+// fallback (the sweep's entry point) AND the `destroy`/`destroyVolume` not_found tolerance the
+// sweep's per-name destroy loop depends on.
+test('isMissingResourceError recognizes the Blaxel SDK plain-object 404 shape', () => {
+    assert.equal(isMissingResourceError({ code: 404, error: 'Sandbox not found' }), true, 'plain-object 404 (the exact live shape) must be recognized');
+    assert.equal(isMissingResourceError({ code: 500, error: 'boom' }), false, 'an unrelated plain-object error must not be mistaken for not-found');
+});
+test('isMissingResourceError preserves existing Error-message-regex behavior', () => {
+    assert.equal(isMissingResourceError(new Error('sandbox hearth-zt-test-1-gxyz not found')), true, 'an Error whose message matches the regex must still be recognized');
+    assert.equal(isMissingResourceError(new Error('boom')), false, 'an unrelated Error must not be mistaken for not-found');
+});
+test('sweepAndReleaseVolume (via recreateOnImage) destroys EVERY name-family member — including a detached one — and spares foreign homes', async () => {
+    const destroyed = [];
+    const backend = new BlaxelHomeBackend(makeConfig(), makeFakeProvider(destroyed));
+    const refresh = await backend.recreateOnImage(makeDescriptor(), 'crouter-hearth-home-0-3-36', '0.3.36');
+    // Both the row-pointed generation AND the detached standby orphan (the exact Run-3 miss) are
+    // destroyed, plus the FAILED leftover and the bare base name.
+    assert.ok(destroyed.includes(`${VOLUME_ID}-gold`), 'row-pointed generation must be destroyed');
+    assert.ok(destroyed.includes(`${VOLUME_ID}-gdetached`), 'DETACHED standby orphan (Run-3 miss) must be destroyed');
+    assert.ok(destroyed.includes(`${VOLUME_ID}-gfailed`), 'FAILED leftover record must be destroyed');
+    assert.ok(destroyed.includes(VOLUME_ID), 'bare base-name generation must be destroyed');
+    // The `-g` anchor keeps a same-prefixed foreign home and unrelated sandboxes safe.
+    assert.ok(!destroyed.includes('hearth-zt-test-10-gxyz'), 'foreign home hearth-zt-test-10 must NOT be swept (-g anchor)');
+    assert.ok(!destroyed.includes('unrelated-sandbox'), 'unrelated sandbox must NOT be swept');
+    // MAJOR-1: the suffix-extension collision (`<base>-gfoo`, a DIFFERENT home) IS in the name
+    // family but carries a different externalId, so the tag-scoped list never surfaces it — the
+    // old name-only sweep would have collateral-destroyed it. And a same-name-family but UNTAGGED
+    // legacy record is likewise excluded by the filter, surviving as the self-heals orphan class.
+    assert.ok(!destroyed.includes(`${VOLUME_ID}-gfoo`), 'suffix-extension foreign home <base>-gfoo must NOT be swept (untagged — MAJOR-1)');
+    assert.ok(!destroyed.includes(`${VOLUME_ID}-gstale`), 'same-name-family but UNTAGGED record must NOT be swept (tag filter excludes it)');
+    // The four tagged family members are destroyed before the fresh generation is created.
+    assert.equal(destroyed.length, 4, 'exactly the four tagged family members are destroyed');
+    // A fresh `-g` generation is minted and reported on the target version.
+    assert.match(refresh.providerSandboxId, new RegExp(`^${VOLUME_ID}-g[0-9a-z]+$`));
+    assert.notEqual(refresh.providerSandboxId, `${VOLUME_ID}-gold`);
+    assert.equal(refresh.templateVersion, '0.3.36');
+});
+/** A fake modeling a provider that assembles its filtered result from MULTIPLE cursor pages
+ *  before returning (MINOR-1). The tagged family spans 3 pages; `listMachines` walks all pages,
+ *  concatenates, and honors the externalId filter — the same total the real paginated
+ *  `listSandboxes` loop assembles. Asserts the sweep destroys every tagged member across every
+ *  page, so a family member beyond page 1 can never survive as an orphan. */
+function makePaginatedFakeProvider(familyIds, destroyed) {
+    // Split the tagged family across three pages; sprinkle in a foreign untagged record per page.
+    const pages = [[], [], []];
+    familyIds.forEach((id, i) => pages[i % 3].push({ ref: { providerName: 'blaxel', machineId: id, state: 'running' }, externalId: VOLUME_ID }));
+    pages[0].push({ ref: { providerName: 'blaxel', machineId: 'foreign-a', state: 'running' }, externalId: 'other-home' });
+    pages[2].push({ ref: { providerName: 'blaxel', machineId: 'foreign-b', state: 'running' } });
+    const fake = {
+        providerName: 'blaxel',
+        imageRef: 'crouter-hearth-home-0-3-35',
+        templateVersion: '0.3.35',
+        volumeSizeGb: 4,
+        async listMachines(filter) {
+            // Assemble across all pages (what the real cursor loop does) then apply the filter.
+            return pages.flat().filter((e) => filter?.externalId === undefined || e.externalId === filter.externalId).map((e) => e.ref);
+        },
+        async destroy(machineId) {
+            destroyed.push(machineId);
+            return { kind: 'destroyed' };
+        },
+        async getVolumeAttachment() {
+            return null;
+        },
+        async createMachine(input) {
+            return { providerName: 'blaxel', machineId: input.name ?? VOLUME_ID, state: 'running' };
+        },
+        async exec() {
+            return { exitCode: 0, timedOut: false, stdout: '', stderr: '' };
+        },
+        async waitForPort() { },
+        async publishHttpPort(machineId, input) {
+            return { routeId: input.routeName ?? `${machineId}-web`, machineId, targetPort: input.targetPort, url: `https://${machineId}.example` };
+        },
+        async getMachine(machineId) {
+            return { providerName: 'blaxel', machineId, state: 'running' };
+        },
+    };
+    return fake;
+}
+test('MINOR-1 pagination: a family served across multiple pages is fully found+destroyed by the sweep', async () => {
+    const destroyed = [];
+    // A family that would straddle page boundaries: the base plus several `-g` generations.
+    const familyIds = [VOLUME_ID, `${VOLUME_ID}-ga`, `${VOLUME_ID}-gb`, `${VOLUME_ID}-gc`, `${VOLUME_ID}-gd`, `${VOLUME_ID}-ge`, `${VOLUME_ID}-gf`];
+    const backend = new BlaxelHomeBackend(makeConfig(), makePaginatedFakeProvider(familyIds, destroyed));
+    await backend.recreateOnImage(makeDescriptor(), 'crouter-hearth-home-0-3-36', '0.3.36');
+    // Every tagged family member across every page is destroyed — none survives beyond page 1.
+    for (const id of familyIds)
+        assert.ok(destroyed.includes(id), `family member ${id} (across pages) must be destroyed`);
+    assert.equal(destroyed.length, familyIds.length, 'exactly the tagged family is destroyed — foreign records on the same pages survive');
+    assert.ok(!destroyed.includes('foreign-a'), 'foreign tagged record must survive');
+    assert.ok(!destroyed.includes('foreign-b'), 'foreign untagged record must survive');
+});
+/** A fake whose `createMachine` runs a scripted sequence of outcomes ('ok' | a rejection value)
+ *  per call, with an empty family (isolating the §4 retry logic from the sweep). Records every
+ *  destroy so self-cleanup and the discarded generation are observable. */
+function makeCreateScriptedProvider(script, destroyed) {
+    let call = 0;
+    const fake = {
+        providerName: 'blaxel',
+        imageRef: 'crouter-hearth-home-0-3-35',
+        templateVersion: '0.3.35',
+        volumeSizeGb: 4,
+        async listMachines() {
+            return [];
+        },
+        async destroy(machineId) {
+            destroyed.push(machineId);
+            return { kind: 'destroyed' };
+        },
+        async getVolumeAttachment() {
+            return null;
+        },
+        async createMachine(input) {
+            const outcome = script[call++];
+            if (outcome !== 'ok')
+                throw outcome;
+            return { providerName: 'blaxel', machineId: input.name ?? VOLUME_ID, state: 'running' };
+        },
+        async exec() {
+            return { exitCode: 0, timedOut: false, stdout: '', stderr: '' };
+        },
+        async waitForPort() { },
+        async publishHttpPort(machineId, input) {
+            return { routeId: input.routeName ?? `${machineId}-web`, machineId, targetPort: input.targetPort, url: `https://${machineId}.example` };
+        },
+        async getMachine(machineId) {
+            return { providerName: 'blaxel', machineId, state: 'running' };
+        },
+    };
+    return fake;
+}
+test('§4 retry: a genuine 5xx DEPLOYMENT_FAILED create is self-cleaned and retried ONCE onto a fresh name', async () => {
+    const destroyed = [];
+    // First create fails with a server-side deployment transient; the bounded retry then succeeds.
+    const backend = new BlaxelHomeBackend(makeConfig(), makeCreateScriptedProvider([{ status_code: 500, code: 'DEPLOYMENT_FAILED', message: 'deployment failed, please try again' }, 'ok'], destroyed));
+    const refresh = await backend.recreateOnImage(makeDescriptor(), 'crouter-hearth-home-0-3-36', '0.3.36');
+    // The failed first generation is self-cleaned (destroyed) — no orphan — and exactly one
+    // discarded generation was destroyed (empty family means the only destroy is the self-cleanup).
+    assert.equal(destroyed.length, 1, 'exactly the failed first generation is self-cleaned');
+    // The returned generation is the SECOND minted name, not the discarded one.
+    assert.notEqual(refresh.providerSandboxId, destroyed[0]);
+    assert.match(refresh.providerSandboxId, new RegExp(`^${VOLUME_ID}-g[0-9a-z]+$`));
+    assert.equal(refresh.templateVersion, '0.3.36');
+});
+test('§4 retry: a 4xx create is NEVER retried — it self-cleans and rethrows the original error', async () => {
+    const destroyed = [];
+    const boom = { status_code: 409, code: 'SANDBOX_ALREADY_EXISTS', message: 'conflict' };
+    const backend = new BlaxelHomeBackend(makeConfig(), makeCreateScriptedProvider([boom, 'ok'], destroyed));
+    await assert.rejects(() => backend.recreateOnImage(makeDescriptor(), 'crouter-hearth-home-0-3-36', '0.3.36'), (err) => err === boom, 'a 4xx must rethrow the ORIGINAL rejection, never be absorbed by a retry');
+    // Self-cleanup destroyed the one failed generation, and the retry path never ran a second create.
+    assert.equal(destroyed.length, 1, 'the failed 4xx generation is still self-cleaned exactly once');
+});
+test('§4 retry: a second consecutive retryable failure throws (bounded to one retry) and both generations are self-cleaned', async () => {
+    const destroyed = [];
+    const boom = { status_code: 503, code: 'DEPLOYMENT_FAILED', message: 'still failing' };
+    const backend = new BlaxelHomeBackend(makeConfig(), makeCreateScriptedProvider([boom, boom], destroyed));
+    await assert.rejects(() => backend.recreateOnImage(makeDescriptor(), 'crouter-hearth-home-0-3-36', '0.3.36'), (err) => err === boom);
+    // Both the first and the retry generation are self-cleaned — no orphan survives a double failure.
+    assert.equal(destroyed.length, 2, 'both failed generations are self-cleaned');
+});

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

@@ -6,6 +6,45 @@ export declare class BlaxelHomeBackend {
     private readonly provider;
     constructor(config: M0Config, provider?: BlaxelMachineProvider);
     wake(homeInput: HomeProviderDescriptor): Promise<HomeProviderRefresh>;
+    /** Destroy EVERY generation of this home via a deterministic name-family sweep — never a
+     *  point-in-time `attachedTo` read, which Blaxel's autonomous idle→STANDBY detach can race
+     *  ahead of, leaving a live orphan the read cannot see (orphan-cleanup-fix.md §1/§3.3). Then
+     *  poll until the platform reports the volume detached. Safe because at sweep time the
+     *  replacement does not exist yet (its name is minted after) and any live family member is by
+     *  construction either the generation being replaced or an uncommitted leftover — the home's
+     *  durable state is the volume, never a sandbox; one wake per home runs at a time. */
+    private sweepAndReleaseVolume;
+    /** Poll the volume until the platform reports it detached — the create-precondition gate
+     *  (recreate-race-fix.md §3.2). Reads only; never destroys. Emits `hearth.recreate.volume_wait`
+     *  whenever it actually had to wait, so the re-proof can quantify headroom against the budget. */
+    private pollVolumeDetached;
+    /** Create one fresh generation and bring it to a serving state (create → bootstrap exec →
+     *  waitForPort → publish → getMachine), with provider self-cleanup and a single bounded
+     *  retry (orphan-cleanup-fix.md §3.4/§4). Each attempt destroys the generation IT created if
+     *  anything from `createMachine` through the final `getMachine` fails — no code path exits
+     *  leaving a live generation it created and did not return — then rethrows the ORIGINAL error
+     *  (cleanup never masks it). On the first failure, if the error is a genuine server-side
+     *  deployment transient, pause, re-run ONLY the volume-free poll (the sweep already ran once),
+     *  mint a NEW name, and retry exactly once; a second failure throws. The sweep is the caller's
+     *  responsibility and runs before the first attempt only. */
+    private createGeneration;
+    /** Targeted destroy→recreate onto a SPECIFIC image (auto-upgrade roll and
+     *  rollback, design §4/§5). Unlike `wake()`'s standby-resume path, this is the ONE path
+     *  that force-destroys the home's sandboxes before recreating. Cleanup is a deterministic
+     *  name-family sweep (orphan-cleanup-fix.md §3.3): every generation of this home is destroyed
+     *  before the fresh one is minted, so a failed roll-forward generation can never survive as a
+     *  live orphan even after Blaxel autonomously detaches it from the volume. The recreate lands
+     *  on a FRESH sandbox name every call — a name that has never existed cannot 409 against a
+     *  lingering same-name delete. The durable volume is a separate resource and is NEVER touched
+     *  (flow-D durability) — user state is byte-identical across the flip, which is exactly what
+     *  makes both the upgrade and the rollback lossless. The new `providerSandboxId` is returned on
+     *  the refresh; callers persist it (`refreshProviderPointers` treats it as a refreshable
+     *  pointer). `templateVersion` is baked into the bootstrap's fail-fast version assert (the
+     *  baked crtr must match) AND reported back so the CP records the target version — the caller
+     *  still independently asserts `crtr sys version` in-guest before trusting it (wake.ts
+     *  `rollHome`/`rollbackHome`, against `refresh.providerSandboxId`, never a stale captured
+     *  name). */
+    recreateOnImage(homeInput: HomeProviderDescriptor, imageRef: string, templateVersion: string): Promise<HomeProviderRefresh>;
     suspend(homeInput: HomeProviderDescriptor): Promise<HomeProviderRefresh>;
     getMachine(machineId: string): Promise<MachineRef | null>;
     /** P2.6 stdin-capable exec seam, passed through verbatim — the `HomeBackend` interface is the