@crouton-kit/crouter 0.3.33 → 0.3.34

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

@@ -0,0 +1,66 @@
+import type { GuestNodeId, MachineId, TenantId } from '../../core/hearth/types.js';
+export type HearthProvider = 'blaxel';
+export type HomeId = string;
+export type UserId = string;
+export type ProviderSandboxId = MachineId;
+export type ProviderVolumeId = string;
+export type PreviewEndpoint = string;
+export type RelayAuthRef = string;
+export type HomeStatus = 'provisioning' | 'running' | 'suspended' | 'restoring' | 'terminating' | 'terminated' | 'unknown';
+export type HomeHealthVerdict = 'healthy' | 'degraded' | 'unknown';
+export interface Home {
+    home_id: HomeId;
+    tenant_id: TenantId;
+    user_id: UserId;
+    provider: HearthProvider;
+    provider_sandbox_id: ProviderSandboxId | null;
+    provider_volume_id: ProviderVolumeId | null;
+    preview_endpoint: PreviewEndpoint | null;
+    home_agent_target: GuestNodeId | null;
+    relay_auth_ref: RelayAuthRef | null;
+    status: HomeStatus;
+    template_version: string | null;
+    last_ready_at: string | null;
+    last_wake_at: string | null;
+    last_suspend_at: string | null;
+    last_wake_latency_ms: number | null;
+    health_verdict: HomeHealthVerdict;
+    created_at: string;
+    updated_at: string;
+}
+export type ResolvedHome = Home;
+export interface CreateHomeInput {
+    home_id: HomeId;
+    tenant_id: TenantId;
+    user_id: UserId;
+    provider?: HearthProvider;
+    provider_sandbox_id?: ProviderSandboxId | null;
+    provider_volume_id?: ProviderVolumeId | null;
+    preview_endpoint?: PreviewEndpoint | null;
+    home_agent_target?: GuestNodeId | null;
+    relay_auth_ref?: RelayAuthRef | null;
+    status?: HomeStatus;
+    template_version?: string | null;
+    last_ready_at?: string | null;
+    last_wake_at?: string | null;
+    last_suspend_at?: string | null;
+    last_wake_latency_ms?: number | null;
+    health_verdict?: HomeHealthVerdict;
+    created_at?: string;
+    updated_at?: string;
+}
+export interface RefreshProviderPointersInput {
+    provider_sandbox_id: ProviderSandboxId | null;
+    preview_endpoint: PreviewEndpoint | null;
+    status?: HomeStatus;
+    template_version?: string | null;
+}
+export interface TouchWakeInput {
+    at?: string;
+    latency_ms?: number | null;
+}
+export type HomePatch = Partial<Pick<Home, 'provider_sandbox_id' | 'provider_volume_id' | 'preview_endpoint' | 'relay_auth_ref' | 'status' | 'template_version' | 'last_ready_at' | 'last_wake_at' | 'last_suspend_at' | 'last_wake_latency_ms' | 'health_verdict'>>;
+export interface TenantSession {
+    tenant_id: TenantId;
+    user_id: UserId;
+}

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

@@ -0,0 +1,80 @@
+import { type HomeBackend } from '../../core/hearth/provider.js';
+import type { M0Config } from '../../core/hearth/types.js';
+import { type ControlPlaneConfig } from './config.js';
+import { getHomeById, refreshProviderPointers, setHomeStatus, touchReady, touchWake } from './registry.js';
+import { resolveSecret } from './secrets.js';
+import type { HomeId, HomeStatus } from './types.js';
+export interface WakeResult {
+    preview_endpoint: string;
+    relayToken: string;
+}
+/** Normalize a provider-observed runtime status into the CP `HomeStatus`
+ *  vocabulary before it is ever persisted (Q3 / P3.4 review Minor finding):
+ *  the provider's `MachineState` is broad (and may include future
+ *  pause/suspend/standby spellings the SDK doesn't expose yet); CP's
+ *  `HomeStatus` enum does not have a `'paused'` member. Anything
+ *  pause/suspend/standby-shaped collapses to `'suspended'`; an exact
+ *  `'running'` passes through; everything else (provisioning, terminating,
+ *  terminated, restoring, unrecognized) becomes `'unknown'` rather than
+ *  guessing a more specific CP status from a provider-specific string. */
+export declare function normalizeProviderStatus(providerStatus: string | null | undefined): HomeStatus;
+/** One bounded attempt: open a WebSocket to `/node/<target>` carrying the
+ *  relay token and require the upgrade to both succeed AND survive a short
+ *  settle window (or yield a first frame) within `attemptTimeoutMs` — proof
+ *  the in-guest web server answered AND relayed to a live broker `view.sock`
+ *  (R-WAKE-2), not just that the SPA shell route is up. Every branch
+ *  (success, handshake rejection, error, premature close, attempt timeout)
+ *  closes the socket and resolves exactly once — a success closes gracefully
+ *  (code 1000) so the guest relay does not record a false fault, anything
+ *  else terminates it. */
+declare function probeNodeOnce(previewEndpoint: string, target: string, relayToken: string, attemptTimeoutMs: number): Promise<boolean>;
+/** Retry the single-shot probe until it confirms `/node/<target>` is serving
+ *  or `windowMs` elapses. Always runs at least one attempt (R-WAKE-1: "a
+ *  single failed probe does not abort"). Every timer this loop starts
+ *  (the per-attempt abort timeout, the inter-attempt backoff) is cleared/
+ *  resolved before the loop returns — nothing is left armed. */
+declare function probeNodeReady(previewEndpoint: string, target: string, relayToken: string, windowMs: number): Promise<boolean>;
+/** Indirection seam so a smoke/test script can swap any step (the provider
+ *  backend, the registry setters, the secret resolver, the probe itself, the
+ *  clock) without touching a real DB/provider/filesystem. Production code
+ *  never reassigns these; only ad hoc verification scripts do. */
+export declare const wakeInternals: {
+    getHomeById: typeof getHomeById;
+    refreshProviderPointers: typeof refreshProviderPointers;
+    setHomeStatus: typeof setHomeStatus;
+    touchWake: typeof touchWake;
+    touchReady: typeof touchReady;
+    resolveSecret: typeof resolveSecret;
+    getHomeBackend: (config: M0Config) => HomeBackend;
+    loadM0Config: () => M0Config;
+    loadControlPlaneConfig: () => ControlPlaneConfig;
+    probeNodeOnce: typeof probeNodeOnce;
+    probeNodeReady: typeof probeNodeReady;
+    now: () => number;
+};
+/** Cheap, non-probing fast path: return a still-fresh warm-verdict cache hit
+ *  for `home_id`, or `null` if there is none (expired or never confirmed).
+ *  Never reads the registry and never calls the provider — callers fall back
+ *  to `ensureAwake` on a `null` (Q1: "no call to provider"). */
+export declare function resolveRunning(home_id: HomeId): WakeResult | null;
+/** Drop the cached warm verdict for a home (e.g. an upstream relay forward
+ *  failed) so the next `ensureAwake`/`resolveRunning` re-checks instead of
+ *  trusting a stale "ready" answer. */
+export declare function invalidateWarmVerdict(home_id: HomeId): void;
+/** Clear all warm verdicts and in-flight wake coalescing. Test/smoke-script
+ *  hygiene only — production never needs this (one CP process, S2). */
+export declare function resetWakeCacheForTests(): void;
+/** Bring a home up and ready, returning the route to relay to once it is.
+ *  Reads the registry, resolves the relay token, calls the provider
+ *  wake/resume seam, ready-probes `/node/<home_agent_target>`, refreshes
+ *  provider pointers on a recreate, records wake/ready timing, and returns
+ *  `{ preview_endpoint, relayToken }`. Throws on a ready-probe timeout
+ *  (wake-failure UX is deferred — gap note 2 — a throw is the accepted
+ *  cutover behavior).
+ *
+ *  A fresh warm-verdict cache hit short-circuits without re-entering this
+ *  pipeline at all. Otherwise concurrent callers for the SAME `home_id`
+ *  coalesce onto one in-flight wake (Q1) instead of each driving their own
+ *  provider call. */
+export declare function ensureAwake(home_id: HomeId): Promise<WakeResult>;
+export {};

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

@@ -0,0 +1,312 @@
+// control-plane/wake.ts — CP wake orchestration (P4.2 / part-plan T3.1).
+//
+// Generalizes M0 `wake-proxy/home.ts` (`ensureAwake`/`resolveRunningHome`/
+// `probeRelayServing`) onto the CP `home` registry, with one deliberate
+// behavior drop: NO idle-pause machinery (S3 — the provider owns
+// idle->suspend; M0's `scheduleIdlePause`/`pauseNow` timer chain is not
+// reproduced here, by design, not oversight).
+//
+// Pipeline (R-WAKE-1): read the `home` row -> resolve the relay token handle
+// -> call the provider wake/resume seam (`HomeBackend.wake`, owned by the
+// home/provider slice, IP-1) -> ready-probe the in-guest web server on
+// `/node/<home_agent_target>` over a short retried window, carrying the
+// relay token -> if the provider returned a new sandbox/preview (a
+// recreate), persist the refreshed pointers; `home_agent_target` is NEVER
+// part of that patch (R-WAKE-6 — `refreshProviderPointers` doesn't accept it)
+// -> record wake/ready timing -> return the route. Readiness here means the
+// guest web server answers `/node/<target>` AND relays to a live broker
+// `view.sock` (R-WAKE-2 — not "the SPA shell renders"). `src/clients/web/
+// server.ts` only proves that second half on a WS upgrade: `bridgeConnection`
+// opens `view.sock` AFTER the 101 response and closes the socket with 1011
+// the instant that fails (ECONNREFUSED/ENOENT — "no running broker"), so an
+// HTTP GET 200 on `/node/<target>` (the SPA static/fallback route) proves
+// only that the guest web server is up, not that the broker is. The probe
+// therefore opens a real WebSocket to `/node/<target>` and requires a
+// successful upgrade that SURVIVES a short settle window (or yields a first
+// frame) before declaring readiness.
+//
+// All timers used during a probe retry window are cleared before the
+// function that started them returns — there is no `setTimeout`/`setInterval`
+// left armed once `ensureAwake`/`resolveRunning` resolve (S3 regression bar).
+import { setTimeout as delay } from 'node:timers/promises';
+import { WebSocket } from 'ws';
+import { general } from '../../core/errors.js';
+import { loadM0Config } from '../../core/hearth/config.js';
+import { getHomeBackend } from '../../core/hearth/provider.js';
+import { loadControlPlaneConfig } from './config.js';
+import { getHomeById, refreshProviderPointers, setHomeStatus, touchReady, touchWake } from './registry.js';
+import { resolveSecret } from './secrets.js';
+// Individual probe attempt timeout — bounded short so a dead route fails
+// fast and the retry loop gets multiple attempts inside the overall window,
+// rather than one attempt eating the whole window (mirrors M0's
+// `READY_PROBE_TIMEOUT_MS`).
+const READY_PROBE_ATTEMPT_TIMEOUT_MS = 1_500;
+// Backoff between probe attempts (Q1: "500ms backoff between attempts").
+const READY_PROBE_BACKOFF_MS = 500;
+// How long a confirmed-ready verdict is trusted before `resolveRunning`/
+// `ensureAwake` re-checks instead of trusting a stale answer (Q1: "10s TTL,
+// in-process"). Single CP process, no distributed cache (S2).
+const WARM_VERDICT_TTL_MS = 10_000;
+/** Normalize a provider-observed runtime status into the CP `HomeStatus`
+ *  vocabulary before it is ever persisted (Q3 / P3.4 review Minor finding):
+ *  the provider's `MachineState` is broad (and may include future
+ *  pause/suspend/standby spellings the SDK doesn't expose yet); CP's
+ *  `HomeStatus` enum does not have a `'paused'` member. Anything
+ *  pause/suspend/standby-shaped collapses to `'suspended'`; an exact
+ *  `'running'` passes through; everything else (provisioning, terminating,
+ *  terminated, restoring, unrecognized) becomes `'unknown'` rather than
+ *  guessing a more specific CP status from a provider-specific string. */
+export function normalizeProviderStatus(providerStatus) {
+    if (providerStatus === null || providerStatus === undefined)
+        return 'unknown';
+    const normalized = providerStatus.trim().toLowerCase();
+    if (normalized === 'paused' || normalized === 'suspended' || normalized === 'standby')
+        return 'suspended';
+    if (normalized === 'running')
+        return 'running';
+    return 'unknown';
+}
+function requireHomeField(value, field, home_id) {
+    if (value === null || value === undefined || (typeof value === 'string' && value.trim() === '')) {
+        throw general(`home ${home_id} is missing ${field} — cannot wake`, { home_id, field });
+    }
+    return value;
+}
+function buildDescriptor(home, relayToken) {
+    return {
+        homeId: home.home_id,
+        tenantId: home.tenant_id,
+        userId: home.user_id,
+        providerName: home.provider,
+        providerSandboxId: requireHomeField(home.provider_sandbox_id, 'provider_sandbox_id', home.home_id),
+        providerVolumeId: requireHomeField(home.provider_volume_id, 'provider_volume_id', home.home_id),
+        previewEndpoint: home.preview_endpoint,
+        homeAgentTarget: requireHomeField(home.home_agent_target, 'home_agent_target', home.home_id),
+        relayAuthRef: home.relay_auth_ref,
+        relayToken,
+        status: home.status,
+        templateVersion: home.template_version,
+    };
+}
+// After a successful 101 upgrade, `bridgeConnection` (server.ts) still has to
+// dial the broker's `view.sock` and can close the socket (1011, "no running
+// broker") the instant that dial fails. That happens fast on a local unix
+// socket (ECONNREFUSED/ENOENT are immediate), so a settle window this short
+// is enough to let a dead-broker close win the race against a false-positive
+// `open` before the probe declares readiness.
+const READY_PROBE_WS_SETTLE_MS = 300;
+function wsUrlForNode(previewEndpoint, target) {
+    const url = new URL(`/node/${encodeURIComponent(target)}`, previewEndpoint);
+    url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+    return url;
+}
+/** One bounded attempt: open a WebSocket to `/node/<target>` carrying the
+ *  relay token and require the upgrade to both succeed AND survive a short
+ *  settle window (or yield a first frame) within `attemptTimeoutMs` — proof
+ *  the in-guest web server answered AND relayed to a live broker `view.sock`
+ *  (R-WAKE-2), not just that the SPA shell route is up. Every branch
+ *  (success, handshake rejection, error, premature close, attempt timeout)
+ *  closes the socket and resolves exactly once — a success closes gracefully
+ *  (code 1000) so the guest relay does not record a false fault, anything
+ *  else terminates it. */
+async function probeNodeOnce(previewEndpoint, target, relayToken, attemptTimeoutMs) {
+    return new Promise((resolveProbe) => {
+        let settled = false;
+        let settleTimer = null;
+        let ws;
+        try {
+            ws = new WebSocket(wsUrlForNode(previewEndpoint, target), {
+                headers: { authorization: `Bearer ${relayToken}` },
+                perMessageDeflate: false,
+            });
+        }
+        catch {
+            resolveProbe(false);
+            return;
+        }
+        const finish = (ready) => {
+            if (settled)
+                return;
+            settled = true;
+            if (settleTimer !== null)
+                clearTimeout(settleTimer);
+            clearTimeout(attemptTimer);
+            try {
+                // A confirmed-ready probe closes gracefully (code 1000) so the guest
+                // relay's `bridgeConnection` sees a normal browser close and does NOT
+                // record a false browser<->relay fault (P4.2 re-review Major). `close()`
+                // sends the close frame synchronously off the OPEN socket, so resolving
+                // right after calling it still delivers a normal close to the guest —
+                // the probe does not need to wait for the closing handshake to finish.
+                // Failure/timeout/error paths still abort hard via `terminate()`: there
+                // is nothing graceful to negotiate when the socket never proved ready.
+                if (ready) {
+                    ws.close(1000, 'readiness probe complete');
+                }
+                else {
+                    ws.terminate();
+                }
+            }
+            catch {
+                /* ignore */
+            }
+            resolveProbe(ready);
+        };
+        const attemptTimer = setTimeout(() => finish(false), attemptTimeoutMs);
+        ws.once('open', () => {
+            // The attempt timer (above) still bounds the total wait, so it is safe
+            // to always arm the full settle window here — whichever timer fires
+            // first wins via `finish`'s once-only guard.
+            settleTimer = setTimeout(() => finish(true), Math.min(READY_PROBE_WS_SETTLE_MS, attemptTimeoutMs));
+        });
+        ws.once('message', () => finish(true));
+        ws.once('unexpected-response', () => finish(false));
+        ws.once('error', () => finish(false));
+        ws.once('close', () => finish(false));
+    });
+}
+/** Retry the single-shot probe until it confirms `/node/<target>` is serving
+ *  or `windowMs` elapses. Always runs at least one attempt (R-WAKE-1: "a
+ *  single failed probe does not abort"). Every timer this loop starts
+ *  (the per-attempt abort timeout, the inter-attempt backoff) is cleared/
+ *  resolved before the loop returns — nothing is left armed. */
+async function probeNodeReady(previewEndpoint, target, relayToken, windowMs) {
+    const deadline = Date.now() + Math.max(0, windowMs);
+    let firstAttempt = true;
+    for (;;) {
+        const remaining = deadline - Date.now();
+        // Past the first attempt, an already-expired budget ends the loop here
+        // instead of spending one more full attempt timeout (P4.2 re-review
+        // Minor) — only the very first attempt is unconditional (R-WAKE-1: "a
+        // single failed probe does not abort"/at-least-one-attempt).
+        if (!firstAttempt && remaining <= 0)
+            return false;
+        const attemptTimeoutMs = firstAttempt
+            ? Math.max(250, Math.min(READY_PROBE_ATTEMPT_TIMEOUT_MS, windowMs))
+            : Math.min(READY_PROBE_ATTEMPT_TIMEOUT_MS, remaining);
+        firstAttempt = false;
+        if (await wakeInternals.probeNodeOnce(previewEndpoint, target, relayToken, attemptTimeoutMs))
+            return true;
+        const remainingAfter = deadline - Date.now();
+        if (remainingAfter <= 0)
+            return false;
+        await delay(Math.min(READY_PROBE_BACKOFF_MS, remainingAfter));
+    }
+}
+/** Indirection seam so a smoke/test script can swap any step (the provider
+ *  backend, the registry setters, the secret resolver, the probe itself, the
+ *  clock) without touching a real DB/provider/filesystem. Production code
+ *  never reassigns these; only ad hoc verification scripts do. */
+export const wakeInternals = {
+    getHomeById,
+    refreshProviderPointers,
+    setHomeStatus,
+    touchWake,
+    touchReady,
+    resolveSecret,
+    getHomeBackend: (config) => getHomeBackend(config),
+    loadM0Config: () => loadM0Config(),
+    loadControlPlaneConfig: () => loadControlPlaneConfig(),
+    probeNodeOnce,
+    probeNodeReady,
+    now: () => Date.now(),
+};
+const warmVerdicts = new Map();
+const inflightWakes = new Map();
+/** Cheap, non-probing fast path: return a still-fresh warm-verdict cache hit
+ *  for `home_id`, or `null` if there is none (expired or never confirmed).
+ *  Never reads the registry and never calls the provider — callers fall back
+ *  to `ensureAwake` on a `null` (Q1: "no call to provider"). */
+export function resolveRunning(home_id) {
+    const warm = warmVerdicts.get(home_id);
+    if (warm === undefined)
+        return null;
+    if (wakeInternals.now() - warm.confirmedAt >= WARM_VERDICT_TTL_MS)
+        return null;
+    return warm.result;
+}
+/** Drop the cached warm verdict for a home (e.g. an upstream relay forward
+ *  failed) so the next `ensureAwake`/`resolveRunning` re-checks instead of
+ *  trusting a stale "ready" answer. */
+export function invalidateWarmVerdict(home_id) {
+    warmVerdicts.delete(home_id);
+}
+/** Clear all warm verdicts and in-flight wake coalescing. Test/smoke-script
+ *  hygiene only — production never needs this (one CP process, S2). */
+export function resetWakeCacheForTests() {
+    warmVerdicts.clear();
+    inflightWakes.clear();
+}
+async function runEnsureAwake(home_id) {
+    const home = wakeInternals.getHomeById(home_id);
+    if (home === null)
+        throw general(`home not found: ${home_id}`, { home_id });
+    const relayAuthRef = requireHomeField(home.relay_auth_ref, 'relay_auth_ref', home_id);
+    const relayToken = wakeInternals.resolveSecret(relayAuthRef);
+    const target = requireHomeField(home.home_agent_target, 'home_agent_target', home_id);
+    const descriptor = buildDescriptor(home, relayToken);
+    const startedAt = wakeInternals.now();
+    const m0 = wakeInternals.loadM0Config();
+    const refresh = await wakeInternals.getHomeBackend(m0).wake(descriptor);
+    const normalizedStatus = normalizeProviderStatus(refresh.status);
+    const recreated = refresh.providerSandboxId !== home.provider_sandbox_id || (refresh.previewEndpoint ?? null) !== home.preview_endpoint;
+    let previewEndpoint;
+    if (recreated) {
+        // R-WAKE-6, non-negotiable: persist the new sandbox/preview pointers but
+        // never the home node target — `refreshProviderPointers`'s input shape
+        // has no `home_agent_target` field, so there is no way for this call to
+        // touch it even by accident.
+        const updated = wakeInternals.refreshProviderPointers(home_id, {
+            provider_sandbox_id: refresh.providerSandboxId,
+            preview_endpoint: refresh.previewEndpoint ?? null,
+            status: normalizedStatus,
+            template_version: refresh.templateVersion ?? home.template_version,
+        });
+        previewEndpoint = updated.preview_endpoint;
+    }
+    else {
+        wakeInternals.setHomeStatus(home_id, normalizedStatus);
+        previewEndpoint = home.preview_endpoint;
+    }
+    const resolvedPreviewEndpoint = requireHomeField(previewEndpoint, 'preview_endpoint', home_id);
+    const controlPlaneConfig = wakeInternals.loadControlPlaneConfig();
+    const ready = await wakeInternals.probeNodeReady(resolvedPreviewEndpoint, target, relayToken, controlPlaneConfig.readyTimeoutMs);
+    if (!ready) {
+        throw general(`guest web relay did not become ready before timeout: ${home_id}`, { home_id, previewEndpoint: resolvedPreviewEndpoint });
+    }
+    const readyAt = new Date().toISOString();
+    wakeInternals.touchWake(home_id, { at: new Date(startedAt).toISOString(), latency_ms: wakeInternals.now() - startedAt });
+    wakeInternals.touchReady(home_id, readyAt);
+    return { preview_endpoint: resolvedPreviewEndpoint, relayToken };
+}
+/** Bring a home up and ready, returning the route to relay to once it is.
+ *  Reads the registry, resolves the relay token, calls the provider
+ *  wake/resume seam, ready-probes `/node/<home_agent_target>`, refreshes
+ *  provider pointers on a recreate, records wake/ready timing, and returns
+ *  `{ preview_endpoint, relayToken }`. Throws on a ready-probe timeout
+ *  (wake-failure UX is deferred — gap note 2 — a throw is the accepted
+ *  cutover behavior).
+ *
+ *  A fresh warm-verdict cache hit short-circuits without re-entering this
+ *  pipeline at all. Otherwise concurrent callers for the SAME `home_id`
+ *  coalesce onto one in-flight wake (Q1) instead of each driving their own
+ *  provider call. */
+export async function ensureAwake(home_id) {
+    const warm = resolveRunning(home_id);
+    if (warm !== null)
+        return warm;
+    const inflight = inflightWakes.get(home_id);
+    if (inflight !== undefined)
+        return inflight;
+    const promise = runEnsureAwake(home_id)
+        .then((result) => {
+        warmVerdicts.set(home_id, { result, confirmedAt: wakeInternals.now() });
+        return result;
+    })
+        .finally(() => {
+        if (inflightWakes.get(home_id) === promise)
+            inflightWakes.delete(home_id);
+    });
+    inflightWakes.set(home_id, promise);
+    return promise;
+}

package/dist/hearth/wake-proxy/__tests__/guest-source.test.js

@@ -97,7 +97,7 @@ test('runGuestSource releases activity on wake timeout', async () => {
             throw new Error('fetch should not run after wake timeout');
         },
     });
-    const raw = await runGuestSource(tenantId, { kind: 'exec', bin: 'crtr', args: ['view', 'list'] }, deps);
+    const raw = await runGuestSource(tenantId, { kind: 'exec', bin: 'crtr', args: ['surface', 'view', 'list'] }, deps);
     assert.equal(raw.ok, false);
     assert.equal(raw.stdout, '');
     assert.match(raw.stderr, /timed out/i);
@@ -118,7 +118,7 @@ test('runGuestSource releases activity when the bridge fetch aborts on timeout',
             });
         }),
     });
-    const raw = await runGuestSource(tenantId, { kind: 'exec', bin: 'crtr', args: ['view', 'list'] }, deps);
+    const raw = await runGuestSource(tenantId, { kind: 'exec', bin: 'crtr', args: ['surface', 'view', 'list'] }, deps);
     assert.equal(raw.ok, false);
     assert.equal(raw.stdout, '');
     assert.doesNotMatch(raw.stderr, /Bearer secret/);

package/dist/hearth/wake-proxy/home.d.ts

@@ -20,13 +20,7 @@ declare function captureAwakeHome(tenantId: string): AwakenedHome;
  * place that turns "a known-running home" into a forwardable route without the heavy gate.
  */
 export declare function resolveRunningHome(tenantId: string): AwakenedHome | null;
-/**
- * Wake the tenant's home through the configured backend seam. The backend owns the restore-vs-
- * recreate decision and persists the refreshed `webRoute`/`relayToken` to the registry. Until the
- * Blaxel backend is wired, `getHomeBackend` throws a 503 "no provider
- * configured" — so a cold home cannot be woken, while an already-serving home still forwards via
- * the fast path above (which never calls this).
- */
+/** Wake the tenant's home through the configured backend seam and persist returned pointers. */
 declare function wakeHome(tenantId: string): Promise<void>;
 export declare const wakeProxyInternals: {
     probeRelayReady: typeof probeRelayReady;
@@ -52,7 +46,7 @@ export declare function releaseActivity(handle: ActivityHandle): TenantActivityS
 export declare function scheduleIdlePause(tenantId: string): void;
 /**
  * Pause the tenant's home through the backend seam. We never drive a sandbox SDK directly here —
- * the backend owns the registry write and state transition. Serialized under the per-tenant
+ * the backend returns provider pointer/state changes and this layer persists them. Serialized under the per-tenant
  * in-process lock; the single-process deployment invariant (one wake-proxy machine per tenant)
  * makes this lock authoritative.
  */

package/dist/hearth/wake-proxy/home.js

@@ -121,15 +121,51 @@ export function resolveRunningHome(tenantId) {
         webPort: getRuntime().m0.webPort,
     };
 }
-/**
- * Wake the tenant's home through the configured backend seam. The backend owns the restore-vs-
- * recreate decision and persists the refreshed `webRoute`/`relayToken` to the registry. Until the
- * Blaxel backend is wired, `getHomeBackend` throws a 503 "no provider
- * configured" — so a cold home cannot be woken, while an already-serving home still forwards via
- * the fast path above (which never calls this).
- */
+function homeProviderDescriptor(home) {
+    return {
+        homeId: home.tenantId,
+        tenantId: home.tenantId,
+        providerName: 'blaxel',
+        providerSandboxId: home.machineId,
+        providerVolumeId: home.homeStorage.volumeId,
+        previewEndpoint: home.webRoute?.concreteUrl ?? home.webRoute?.url ?? null,
+        homeAgentTarget: home.nodeId ?? '',
+        relayToken: home.relayToken ?? '',
+        status: home.state,
+        templateVersion: home.templateVersion ?? null,
+    };
+}
+function persistProviderRefresh(m0, tenantId, refresh) {
+    updateHome(m0.registryPath, tenantId, (draft) => ({
+        ...draft,
+        providerName: refresh.providerName,
+        machineId: refresh.providerSandboxId,
+        homeStorage: {
+            ...draft.homeStorage,
+            ownerMachineId: refresh.providerSandboxId,
+            volumeId: refresh.providerVolumeId,
+            guestHome: m0.guestHome,
+            mountPath: m0.guestHome,
+        },
+        state: refresh.status,
+        nodeId: refresh.homeAgentTarget,
+        webRoute: refresh.route ?? draft.webRoute,
+        templateVersion: refresh.templateVersion,
+        updatedAt: refresh.updatedAt,
+    }));
+}
+async function loadHomeDescriptor(tenantId) {
+    const home = getHome(getRuntime().m0.registryPath, tenantId);
+    if (home === null) {
+        throw general(`no home for tenant ${tenantId} — run the existing provision/bootstrap flow`, { tenantId });
+    }
+    return homeProviderDescriptor(home);
+}
+/** Wake the tenant's home through the configured backend seam and persist returned pointers. */
 async function wakeHome(tenantId) {
-    await getHomeBackend(getRuntime().m0).wake(tenantId);
+    const m0 = getRuntime().m0;
+    const refresh = await getHomeBackend(m0).wake(await loadHomeDescriptor(tenantId));
+    persistProviderRefresh(m0, tenantId, refresh);
 }
 export const wakeProxyInternals = {
     probeRelayReady,
@@ -194,7 +230,7 @@ export function scheduleIdlePause(tenantId) {
 }
 /**
  * Pause the tenant's home through the backend seam. We never drive a sandbox SDK directly here —
- * the backend owns the registry write and state transition. Serialized under the per-tenant
+ * the backend returns provider pointer/state changes and this layer persists them. Serialized under the per-tenant
  * in-process lock; the single-process deployment invariant (one wake-proxy machine per tenant)
  * makes this lock authoritative.
  */
@@ -213,7 +249,8 @@ export async function pauseNow(tenantId) {
         }
         if (home.state !== 'running')
             return;
-        await getHomeBackend(m0).suspend(tenantId);
+        const refresh = await getHomeBackend(m0).suspend(homeProviderDescriptor(home));
+        persistProviderRefresh(m0, tenantId, refresh);
         touchTenantPause(cfg, tenantId);
         clearTenantIdleTimer(tenantId);
     });
@@ -279,8 +316,7 @@ async function runEnsureAwake(tenantId) {
             return wakeProxyInternals.captureAwakeHome(tenantId);
         }
     }
-    // Not serving: drive the backend seam to bring the home up and refresh its route. The backend
-    // owns the warm-resume-vs-recreate decision and persists webRoute/relayToken to the registry.
+    // Not serving: drive the backend seam to bring the home up, then persist the returned route.
     await wakeProxyInternals.wakeHome(tenantId);
     const refreshed = getHome(m0.registryPath, tenantId);
     const relayUrl = refreshed?.webRoute?.concreteUrl ?? refreshed?.webRoute?.url ?? null;

package/dist/pi-extensions/canvas-doc-substrate.js

@@ -45,6 +45,31 @@ import { loadInjectedDocs, saveInjectedDocs } from '../core/substrate/injected-s
  *  to reach for while reading the tools, so memory docs/preferences must sit
  *  there, not far below. Mirrors crouter-help.ts. Falls back to appending if absent. */
 const TOOLS_ANCHOR = '\n\nGuidelines:';
+const AUTO_CONTEXT_RE = /<auto-loaded-context(?:\s[^>]*)?>\n([\s\S]*?)\n<\/auto-loaded-context>/;
+function mergeAutoLoadedContext(injected, content) {
+    const match = injected.match(AUTO_CONTEXT_RE);
+    const inner = match?.[1]?.trim();
+    if (!inner)
+        return content;
+    const existingText = content.map((block) => block.text ?? '').join('\n');
+    if (existingText.includes(inner))
+        return content;
+    const existingIdx = content.findIndex((block) => typeof block.text === 'string' && AUTO_CONTEXT_RE.test(block.text));
+    if (existingIdx !== -1) {
+        return content.map((block, idx) => {
+            if (idx !== existingIdx || typeof block.text !== 'string')
+                return block;
+            return {
+                ...block,
+                text: block.text.replace(AUTO_CONTEXT_RE, (_whole, current) => {
+                    const trimmed = String(current).trim();
+                    return `<auto-loaded-context>\n${inner}${trimmed === '' ? '' : `\n${trimmed}`}\n</auto-loaded-context>`;
+                }),
+            };
+        });
+    }
+    return [{ type: 'text', text: `<auto-loaded-context>\n${inner}\n</auto-loaded-context>` }, ...content];
+}
 /**
  * Register the document substrate's two render hooks on `pi`.
  *
@@ -115,8 +140,9 @@ export function registerCanvasDocSubstrate(pi) {
             // A doc surfaced → renderOnReadDocs grew injectedDocs; persist the set so
             // the dedup survives a later dormancy → revive(resume).
             saveInjectedDocs(nodeId, injectedDocs);
-            // Prepend the surfacing docs ahead of the file contents.
-            return { content: [{ type: 'text', text: injected }, ...event.content] };
+            // Fold into any existing auto-loaded-context block from sibling read hooks;
+            // otherwise prepend one quiet block ahead of the file contents.
+            return { content: mergeAutoLoadedContext(injected, event.content) };
         }
         catch {
             return; // inert on error — a bug must degrade a read, never break it

package/dist/pi-extensions/canvas-nav.js

@@ -473,7 +473,7 @@ export function registerCanvasNav(pi) {
             const target = cursorId ?? nodeId;
             const n = cNode(target);
             const nm = n !== null ? fullName(n) : shortId(target);
-            pendingConfirm = { label: `kill ${nm}?`, action: () => shellCrtr(['node', 'close', '--node', target], render) };
+            pendingConfirm = { label: `kill ${nm}?`, action: () => shellCrtr(['node', 'lifecycle', 'close', '--node', target], render) };
             render();
             return { consume: true };
         }