@crouton-kit/crouter 0.3.40 → 0.3.41

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

@@ -1,362 +0,0 @@
-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');
-});
-// Contract: when the volume is held by a sandbox outside the tag-scoped destroy set — an
-// untagged holder the sweep cannot reach — the guard must detect it immediately and throw an
-// actionable error, never spin `pollVolumeDetached` to its VOLUME_DETACH_TIMEOUT_MS deadline.
-/** A fake whose tag-scoped `listMachines` returns `[]` (nothing tagged for this home) while
- *  `getVolumeAttachment` reports the volume held by an untagged sandbox outside the destroy set.
- *  Counts `getVolumeAttachment` calls so the test can assert the guard short-circuits on the
- *  first read rather than looping into `pollVolumeDetached`. */
-function makeUntaggedHolderProvider(holderName, destroyed, attachmentCalls) {
-    const fake = {
-        providerName: 'blaxel',
-        imageRef: 'crouter-hearth-home-0-3-35',
-        templateVersion: '0.3.35',
-        volumeSizeGb: 4,
-        async listMachines() {
-            return []; // tag-scoped list finds nothing — the holder carries no externalId tag
-        },
-        async destroy(machineId) {
-            destroyed.push(machineId);
-            return { kind: 'destroyed' };
-        },
-        async getVolumeAttachment() {
-            attachmentCalls.count += 1;
-            return `sandbox:${holderName}`;
-        },
-        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('loud guard: an untagged legacy sandbox holding the volume fails FAST with an actionable error, never the 120s poll', async () => {
-    const destroyed = [];
-    const attachmentCalls = { count: 0 };
-    const backend = new BlaxelHomeBackend(makeConfig(), makeUntaggedHolderProvider('hearth-prod-1', destroyed, attachmentCalls));
-    await assert.rejects(() => backend.recreateOnImage(makeDescriptor(), 'crouter-hearth-home-0-3-36', '0.3.36'), (err) => {
-        assert.ok(err instanceof Error, 'must throw an Error');
-        assert.match(err.message, /hearth-prod-1/, 'error must name the untagged holder sandbox');
-        assert.match(err.message, /migrate/i, 'error must instruct the operator to migrate the home');
-        return true;
-    });
-    // The tag-scoped sweep destroyed nothing (empty family) and the guard fired on the FIRST
-    // attachment read — it never looped into `pollVolumeDetached`'s wait/retry cycle.
-    assert.equal(destroyed.length, 0, 'nothing was destroyed — the holder was never tag-scoped');
-    assert.equal(attachmentCalls.count, 1, 'getVolumeAttachment must be read exactly once before failing fast, never polled to deadline');
-});
-/** A fake modeling the normal path: the row-pointed generation is tag-scoped and destroyed, and
- *  the volume reports still attached to THAT generation on the guard's read, then detached (null)
- *  on the next read inside `pollVolumeDetached` — a real destroy+detach seconds apart. Confirms
- *  the guard does NOT fire for a holder within the destroy set, and the poll still runs. */
-function makeDestroyedHolderProvider(destroyed, attachmentCalls) {
-    const doomedName = `${VOLUME_ID}-gold`;
-    const fake = {
-        providerName: 'blaxel',
-        imageRef: 'crouter-hearth-home-0-3-35',
-        templateVersion: '0.3.35',
-        volumeSizeGb: 4,
-        async listMachines(filter) {
-            if (filter?.externalId !== VOLUME_ID)
-                return [];
-            return [{ providerName: 'blaxel', machineId: doomedName, state: 'running' }];
-        },
-        async destroy(machineId) {
-            destroyed.push(machineId);
-            return { kind: 'destroyed' };
-        },
-        async getVolumeAttachment() {
-            attachmentCalls.count += 1;
-            // First read (the guard, right after destroy): still shows the just-destroyed generation
-            // as the holder — a real detach is not instantaneous. Every subsequent read (inside
-            // `pollVolumeDetached`): the platform has confirmed detach.
-            return attachmentCalls.count === 1 ? `sandbox:${doomedName}` : 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('loud guard: does NOT fire when the holder is a sandbox the tag-scoped sweep just destroyed — normal recreate still completes', async () => {
-    const destroyed = [];
-    const attachmentCalls = { count: 0 };
-    const backend = new BlaxelHomeBackend(makeConfig(), makeDestroyedHolderProvider(destroyed, attachmentCalls));
-    const refresh = await backend.recreateOnImage(makeDescriptor(), 'crouter-hearth-home-0-3-36', '0.3.36');
-    assert.ok(destroyed.includes(`${VOLUME_ID}-gold`), 'the tag-scoped generation must still be destroyed');
-    assert.ok(attachmentCalls.count >= 2, 'the guard read plus at least one poll read must both occur');
-    assert.match(refresh.providerSandboxId, new RegExp(`^${VOLUME_ID}-g[0-9a-z]+$`));
-    assert.equal(refresh.templateVersion, '0.3.36');
-});

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

@@ -1,12 +0,0 @@
-export interface BuildBootstrapScriptOpts {
-    guestHome: string;
-    crtrVersion: string;
-    relayToken: string;
-    webPort: number;
-    nodeId?: string | null;
-    piAuthJson?: string | null;
-    piPackages?: string[];
-    modelLaddersJson?: string | null;
-    isFirstProvision: boolean;
-}
-export declare function buildBootstrapScript(opts: BuildBootstrapScriptOpts): string;

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

@@ -1,147 +0,0 @@
-import { dirname, join } from 'node:path';
-import { general } from '../../errors.js';
-import { guestEnv } from '../guest-env.js';
-// The baked, read-only product layer (deploy/hearth-blaxel/Dockerfile WORKDIR,
-// and config.ts's ENV.guestCode default). Bootstrap never installs anything
-// here at runtime — it only reads what the image already baked.
-const GUEST_CODE_PATH = '/opt/crouter';
-// The baked crtr binary's fixed, image-symlinked path (deploy/hearth-blaxel/Dockerfile
-// `ln -sf /opt/crouter/node_modules/.bin/crtr /usr/local/bin/crtr`). Every crtr
-// invocation this script makes targets this exact path rather than a bare `crtr`
-// PATH lookup: guest-env.ts's PATH still lists a legacy `$HOME/.crtr-runtime/bin`
-// dir ahead of /usr/local/bin — a holdover from the pre-cutover boot-time `npm
-// install --prefix` flow that P3.1 deleted — and nothing populates that directory
-// anymore, but a volume provisioned before this cutover can still have a stale
-// crtr binary sitting there. Targeting the baked path directly makes PATH order
-// irrelevant for this script's own invocations.
-const BAKED_CRTR_PATH = '/usr/local/bin/crtr';
-function shellQuote(value) {
-    return `'${value.replace(/'/g, `'"'"'`)}'`;
-}
-function uniqueStrings(values) {
-    const result = [];
-    const seen = new Set();
-    for (const value of values) {
-        const trimmed = value?.trim();
-        if (!trimmed || seen.has(trimmed))
-            continue;
-        seen.add(trimmed);
-        result.push(trimmed);
-    }
-    return result;
-}
-function appendJsonSeed(lines, path, marker, content) {
-    const raw = content?.trim();
-    if (!raw)
-        return;
-    lines.push(`cat > ${shellQuote(path)} <<'${marker}'`, raw, marker);
-}
-/** Fail-fast assertion: baked crtr is on PATH and pinned to the exact
- *  expected version, and the bootstrap command surface it depends on
- *  (`crtr surface web serve`) actually exists. No install, no fallback to an
- *  older command name — command drift fails the boot instead of silently
- *  taking a different path (the M0 published-install incident this replaces). */
-function appendCommandSurfaceAssertions(lines, crtrVersion) {
-    const crtr = shellQuote(BAKED_CRTR_PATH);
-    lines.push(`if [ ! -x ${crtr} ]; then`, `  printf "baked crtr not found at %s\\n" ${crtr} >&2`, '  exit 1', 'fi', 
-    // Stale-PATH shadow guard: even though every invocation below targets the
-    // baked path directly, assert that a bare `crtr` lookup ALSO resolves
-    // there — catches a stale volume-installed binary shadowing the baked one
-    // ahead of time, before anything downstream of this script (e.g. a node
-    // engine spawned later in this session) could be tricked by it.
-    'resolved_crtr="$(command -v crtr 2>/dev/null || true)"', `if [ "$resolved_crtr" != ${crtr} ]; then`, `  printf "stale crtr shadowing baked binary: PATH resolves crtr to %s, expected %s\\n" "$resolved_crtr" ${crtr} >&2`, '  exit 1', 'fi', `actual_crtr_version="$(${crtr} --json sys version | node -e 'let s="";process.stdin.on("data",c=>s+=c);process.stdin.on("end",()=>{process.stdout.write(JSON.parse(s).version)})')"`, `if [ "$actual_crtr_version" != ${shellQuote(crtrVersion)} ]; then`, `  printf "crtr version assertion FAILED: baked %s, expected %s\\n" "$actual_crtr_version" ${shellQuote(crtrVersion)} >&2`, '  exit 1', 'fi', `if ! ${crtr} surface web -h >/dev/null 2>&1 || ! ${crtr} surface web serve -h >/dev/null 2>&1; then`, '  printf "command surface assertion FAILED: crtr surface web serve not exposed\\n" >&2', '  exit 1', 'fi');
-}
-/** Cache-prime the baked pi Claude OAuth adapter into pi's user npm install
- *  root (`$HOME/.pi/agent/npm/node_modules/pi-claude-oauth-adapter`) so pi's
- *  package manager finds it already present and skips a network install
- *  (see @earendil-works/pi-coding-agent's getNpmInstallPath/needsInstall:
- *  scope "user" resolves to exactly this path and is used as-is when it
- *  exists). Existence-gated and unconditional (not first-boot-only) so a
- *  volume provisioned before this priming existed self-heals on its next
- *  boot; never overwrites an already-primed copy. */
-function appendOauthAdapterCachePrime(lines, guestHome) {
-    const bakedDir = join(GUEST_CODE_PATH, 'node_modules', 'pi-claude-oauth-adapter');
-    const cacheDir = join(guestHome, '.pi', 'agent', 'npm', 'node_modules', 'pi-claude-oauth-adapter');
-    lines.push(`if [ -d ${shellQuote(bakedDir)} ] && [ ! -d ${shellQuote(cacheDir)} ]; then`, `  mkdir -p ${shellQuote(dirname(cacheDir))}`, `  cp -R ${shellQuote(bakedDir)} ${shellQuote(cacheDir)}`, 'fi');
-}
-export function buildBootstrapScript(opts) {
-    if (opts.relayToken.trim() === '') {
-        throw general('buildBootstrapScript: relayToken must not be empty — the web lane must never bind without relay-token enforcement', {
-            guestHome: opts.guestHome,
-        });
-    }
-    const nodeId = (opts.nodeId ?? '').trim();
-    if (!opts.isFirstProvision && nodeId === '') {
-        throw general('buildBootstrapScript: nodeId is required when isFirstProvision is false', { guestHome: opts.guestHome });
-    }
-    // Single source of truth for the home env table (HOME/CRTR_HOME on the
-    // durable volume; CRTR_SOCK_DIR/CRTR_PIDFILE on tmpfs; CRTR_CANVAS_DB left
-    // unset) — see guest-env.ts. Re-exported here because this script is its
-    // own provider exec, not guaranteed to inherit the sandbox-level envs set
-    // at machine creation. `guestEnv` only dereferences `guestHome`, so a
-    // minimal config stand-in is enough.
-    const env = guestEnv({ guestHome: opts.guestHome });
-    // Override the PATH guestEnv() emits: it still lists the legacy (dead)
-    // `$HOME/.crtr-runtime/bin` ahead of /usr/local/bin (see BAKED_CRTR_PATH
-    // above). This script's own crtr invocations target the baked path
-    // directly regardless, but fix the exported PATH too so anything else
-    // spawned downstream in this session (e.g. the daemon and the node
-    // engines it launches) that calls bare `crtr` also resolves to the baked
-    // binary, not a stale volume copy.
-    env['PATH'] = '/usr/local/bin:/usr/bin:/bin';
-    const runtimeDir = join(opts.guestHome, '.crtr-runtime');
-    const settingsPath = join(opts.guestHome, '.pi', 'agent', 'settings.json');
-    const builtinPiExtensionsDir = join(GUEST_CODE_PATH, 'node_modules', '@crouton-kit', 'crouter', 'dist', 'builtin-pi-packages');
-    const packages = uniqueStrings([
-        ...(opts.piPackages ?? []),
-        join(builtinPiExtensionsDir, 'pi-crtr-extensions'),
-    ]);
-    const settingsJson = JSON.stringify({
-        packages,
-        defaultProvider: 'anthropic',
-        defaultModel: 'claude-opus-4-8',
-        defaultThinkingLevel: 'high',
-        enableSkillCommands: true,
-        steeringMode: 'all',
-        quietStartup: true,
-        theme: 'dark',
-    }, null, 2);
-    const lines = [
-        'set -e',
-        ...Object.entries(env).map(([key, value]) => `export ${key}=${shellQuote(value)}`),
-        // Defense-in-depth: CRTR_CANVAS_DB must stay unset on the guest so
-        // canvas.db follows CRTR_HOME onto the durable volume (its fcntl/WAL
-        // locks need real local-disk semantics) rather than a stray NFS path.
-        'unset CRTR_CANVAS_DB 2>/dev/null || true',
-        `mkdir -p "$HOME/.crouter" "$HOME/.pi/agent" ${shellQuote(env['CRTR_SOCK_DIR'] ?? '')} ${shellQuote(dirname(env['CRTR_PIDFILE'] ?? ''))} ${shellQuote(runtimeDir)}`,
-        // The provisioner launches this script as a detached (background) exec, so its stdout is not
-        // captured. Redirect everything to a log on the durable volume so seed/daemon/node-new
-        // failures are inspectable, and so the first-provision node id can be read from a file (below).
-        'exec >>"$HOME/.crtr-runtime/bootstrap.log" 2>&1',
-    ];
-    appendCommandSurfaceAssertions(lines, opts.crtrVersion);
-    if (opts.isFirstProvision) {
-        appendJsonSeed(lines, settingsPath, 'PI_SETTINGS_JSON', settingsJson);
-        appendJsonSeed(lines, join(opts.guestHome, '.crouter', 'config.json'), 'CRTR_CONFIG_JSON', opts.modelLaddersJson);
-        if ((opts.piAuthJson?.trim() ?? '') !== '') {
-            appendJsonSeed(lines, join(opts.guestHome, '.pi', 'agent', 'auth.json'), 'PI_AUTH_JSON', opts.piAuthJson);
-        }
-    }
-    appendOauthAdapterCachePrime(lines, opts.guestHome);
-    // Tmpfs sock/pidfile dirs are already mkdir'd above, before this line.
-    lines.push(`${shellQuote(BAKED_CRTR_PATH)} sys daemon start </dev/null >>"$HOME/.crtr-runtime/daemon.log" 2>&1`);
-    if (opts.isFirstProvision) {
-        lines.push('home_node_output="$(', `${shellQuote(BAKED_CRTR_PATH)} --json node new --root --kind general --name home <<'SEED'`, 'Hearth home seed for the Blaxel home backend.', 'SEED', ')"', "home_node_id=\"$(node -e 'const o = JSON.parse(process.argv[1]); process.stdout.write(String(o.node_id ?? o.nodeId ?? o.id ?? \"\"));' \"$home_node_output\")\"", 'if [ -z "$home_node_id" ]; then', '  printf "failed to parse home node id from crtr node new output\n%s\n" "$home_node_output" >&2', '  exit 1', 'fi', 'printf "__HEARTH_NODE_ID__=%s\n" "$home_node_id"', 
-        // The provisioner polls this file (background exec stdout is not captured).
-        'printf "%s\n" "$home_node_id" > "$HOME/.crtr-runtime/home-node-id"');
-    }
-    else {
-        lines.push(`${shellQuote(BAKED_CRTR_PATH)} canvas revive ${shellQuote(nodeId)}`);
-    }
-    // `crtr surface web serve` is asserted present above; never fall back to the
-    // retired top-level `crtr web serve` alias. --token is always passed and
-    // always non-empty (checked above) so every lane (bridge/SSE/relay) enforces
-    // the relay token on this non-loopback bind.
-    lines.push(`${shellQuote(BAKED_CRTR_PATH)} surface web serve --host 0.0.0.0 --port ${opts.webPort} --token ${shellQuote(opts.relayToken)} </dev/null >>"$HOME/.crtr-runtime/web.log" 2>&1`);
-    return lines.join('\n');
-}

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

@@ -1,60 +0,0 @@
-import type { HomeProviderDescriptor, HomeProviderRefresh, M0Config, MachineRef } from '../types.js';
-import { BlaxelMachineProvider } from './blaxel.js';
-import type { ExecInput, ExecResult } from './types.js';
-export declare class BlaxelHomeBackend {
-    private readonly config;
-    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). The
-     *  destroy set is intentionally TAG-SCOPED (externalId = volumeId) and is never widened by a
-     *  name-family fallback (MAJOR-1) — so after destroying it, read the volume's current holder
-     *  ONCE: if the volume is still attached to a sandbox that is NOT one we just destroyed, that
-     *  holder is outside the strict sweep's reach (an untagged holder, or a foreign claim) and will
-     *  never detach on its own, so fail fast with an actionable error instead of silently spinning
-     *  the detach poll to its timeout. Otherwise 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
-     *  only door CP code uses to reach it (see `provider.ts`), so callers never import
-     *  `BlaxelMachineProvider` directly. */
-    exec(machineId: string, input: ExecInput): Promise<ExecResult>;
-}