@crouton-kit/crouter 0.3.39 → 0.3.40

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

@@ -252,3 +252,111 @@ test('§4 retry: a second consecutive retryable failure throws (bounded to one r
     // 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-home.d.ts

@@ -8,11 +8,17 @@ export declare class BlaxelHomeBackend {
     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. */
+     *  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`

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

@@ -189,11 +189,17 @@ export class BlaxelHomeBackend {
     }
     /** 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. */
+     *  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. */
     async sweepAndReleaseVolume(volumeId, homeId) {
         // Scope the list to sandboxes Hearth tagged for THIS home (externalId = volumeId), then keep
         // the name-family matcher as an AND-intersection on top (orphan-cleanup-fix MAJOR-1). The
@@ -207,6 +213,19 @@ export class BlaxelHomeBackend {
             await this.provider.destroy(name); // sequential; destroy tolerates not_found
         if (doomed.length > 0)
             emitMarker('hearth.recreate.sweep', { home_id: homeId, volume_id: volumeId, destroyed: doomed });
+        // Loud guard: the sweep above is strictly tag-scoped, so it can only ever destroy a sandbox
+        // that was created with `externalId = volumeId`. Read the volume's current holder ONCE,
+        // before the detach poll, to catch the case that sweep is structurally unable to fix — a
+        // holder that is NOT one of the sandboxes just destroyed (`doomed`) will never detach, and
+        // the poll below would spin the full VOLUME_DETACH_TIMEOUT_MS only to throw the same thing
+        // less clearly. Fail fast instead, naming the holder so an operator can act on it directly.
+        const holder = await this.provider.getVolumeAttachment(volumeId);
+        if (holder !== null) {
+            const holderName = holder.startsWith('sandbox:') ? holder.slice('sandbox:'.length) : holder;
+            if (!doomed.includes(holderName)) {
+                throw general(`legacy untagged sandbox ${holderName} holds volume ${volumeId} for home ${homeId} — the tag-scoped sweep cannot reclaim it (no externalId tag); migrate this home (delete the sandbox so a plain wake recreates it tagged) before rolling`, { homeId, volumeId, holder: holderName });
+            }
+        }
         await this.pollVolumeDetached(volumeId, homeId);
     }
     /** Poll the volume until the platform reports it detached — the create-precondition gate

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/crouter",
-  "version": "0.3.39",
+  "version": "0.3.40",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",