@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/core/hearth/model-auth-guest.js

@@ -0,0 +1,435 @@
+// model-auth-guest.ts — Hearth product seam: the in-guest model-auth lane.
+//
+// Handles GET/POST /__hearth/model-auth/anthropic/{status,start,finish}, mounted
+// by src/clients/web/server.ts (the crtr web substrate provides only routing +
+// relay-token enforcement there; ALL Hearth/OAuth product logic lives here).
+//
+// This is the in-guest counterpart of the M0 wake-proxy's
+// src/hearth/wake-proxy/{anthropic-oauth,model-auth}.ts: the PKCE/OAuth exchange
+// logic is ported verbatim (proven in M0), but the credential read/write no
+// longer round-trips through `runGuestSource` exec — this handler already runs
+// IN the guest, so it talks to pi's AuthStorage directly. No tenantId/owner-auth
+// resolution either: the relay token already gates the whole lane one layer up,
+// and a guest serves exactly one home.
+//
+// This module must not import anything from src/clients/web (the seam runs the
+// other direction: server.ts imports `handleHearthModelAuthRequest` from here)
+// and must not import from src/hearth/wake-proxy (transitional, deleted at
+// P6.6) — it is a standalone, self-contained Hearth handler.
+import { createHash, randomBytes as nodeRandomBytes } from 'node:crypto';
+import { AuthStorage } from '@earendil-works/pi-coding-agent';
+const ANTHROPIC_CLIENT_ID = '9d1c250a-e61b-44d9-88ed-5944d1962f5e';
+const ANTHROPIC_AUTHORIZE_URL = 'https://claude.ai/oauth/authorize';
+const ANTHROPIC_TOKEN_URL = 'https://platform.claude.com/v1/oauth/token';
+const ANTHROPIC_REDIRECT_URI = 'http://localhost:53692/callback';
+const ANTHROPIC_SCOPES = 'org:create_api_key user:profile user:inference user:sessions:claude_code user:mcp_servers user:file_upload';
+const ANTHROPIC_SESSION_TTL_MS = 10 * 60_000;
+const ANTHROPIC_CALLBACK_MAX_URL_LENGTH = 2048;
+const ANTHROPIC_TOKEN_TIMEOUT_MS = 30_000;
+const ANTHROPIC_TOKEN_SKEW_MS = 5 * 60_000;
+const BODY_LIMIT_BYTES = 16 * 1024;
+// ── Redaction ────────────────────────────────────────────────────────────
+// Ported from src/hearth/wake-proxy/redact.ts (+ the owner-auth patterns from
+// wake-proxy/auth.ts that applied to this lane): never let a raw access/
+// refresh token, bearer header, auth.json path, or OAuth query param reach a
+// log line or an HTTP response body.
+const REDIRECT_URL_RE = /https?:\/\/localhost:53692\/callback[^\s"'`<>)]*/gi;
+const BEARER_RE = /\bBearer\s+[A-Za-z0-9._~+/-]+=?=?/gi;
+const TOKEN_QUERY_RE = /([?&](?:token|code|state|code_verifier)=)[^&#\s]+/gi;
+const JSON_TOKEN_RE = /("(?:access_token|refresh_token|access|refresh|code|state|code_verifier)"\s*:\s*")[^"]+(")/gi;
+const ASSIGN_TOKEN_RE = /\b(?:access_token|refresh_token|access|refresh|code|state|code_verifier)\s*[:=]\s*[^\s,&}]+/gi;
+const AUTH_JSON_RE = /\bauth\.json\b/gi;
+const SHA256_RE = /\bsha256:[0-9a-f]{64}\b/gi;
+function redact(message) {
+    return message
+        .replace(REDIRECT_URL_RE, '[redacted redirect url]')
+        .replace(BEARER_RE, 'Bearer [redacted]')
+        .replace(TOKEN_QUERY_RE, '$1[redacted]')
+        .replace(JSON_TOKEN_RE, '$1[redacted]$2')
+        .replace(ASSIGN_TOKEN_RE, (value) => value.replace(/[:=]\s*[^\s,&}]+$/, ': [redacted]'))
+        .replace(AUTH_JSON_RE, '[redacted auth.json]')
+        .replace(SHA256_RE, 'sha256:[redacted]');
+}
+function redactedErrorMessage(error) {
+    return redact(error instanceof Error ? error.message : String(error));
+}
+let currentSession;
+function defaultRandomBytes(size) {
+    return nodeRandomBytes(size);
+}
+function defaultSha256(value) {
+    return createHash('sha256').update(value, 'utf8').digest();
+}
+function purgeExpiredSession(now) {
+    if (currentSession !== undefined && currentSession.expiresAt <= now) {
+        currentSession = undefined;
+    }
+}
+function buildAuthUrl(session, challenge) {
+    const params = new URLSearchParams({
+        // claude.ai/oauth/authorize requires `code=true` (the Claude Code authorize
+        // flow param); omitting it makes the endpoint reject with "Invalid request
+        // format". Claude Code also requires `state` to be the PKCE verifier so the
+        // authorize request satisfies `code_challenge === S256(state)`; the
+        // installed @earendil-works/pi-ai adapter does the same (`state: verifier`).
+        code: 'true',
+        client_id: ANTHROPIC_CLIENT_ID,
+        response_type: 'code',
+        redirect_uri: ANTHROPIC_REDIRECT_URI,
+        scope: ANTHROPIC_SCOPES,
+        state: session.state,
+        code_challenge: challenge,
+        code_challenge_method: 'S256',
+    });
+    return `${ANTHROPIC_AUTHORIZE_URL}?${params.toString()}`;
+}
+function failure(status, error) {
+    return { ok: false, status, error: redact(error) };
+}
+function parseCallbackUrl(raw) {
+    if (raw.length > ANTHROPIC_CALLBACK_MAX_URL_LENGTH) {
+        return failure(400, 'Anthropic callback URL is too long');
+    }
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return failure(400, 'Anthropic callback URL is invalid');
+    }
+    if (url.protocol !== 'http:' || url.hostname !== 'localhost' || url.port !== '53692' || url.pathname !== '/callback') {
+        return failure(400, 'Anthropic callback URL must be http://localhost:53692/callback');
+    }
+    const error = url.searchParams.get('error');
+    if (error !== null && error.trim() !== '') {
+        return failure(400, `Anthropic callback reported error=${error}`);
+    }
+    const code = url.searchParams.get('code')?.trim() ?? '';
+    const state = url.searchParams.get('state')?.trim() ?? '';
+    if (code === '' || state === '') {
+        return failure(400, 'Anthropic callback is missing code or state');
+    }
+    return { code, state };
+}
+async function postTokenExchange(body) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => {
+        controller.abort(new Error('Anthropic OAuth token exchange timed out'));
+    }, ANTHROPIC_TOKEN_TIMEOUT_MS);
+    timeout.unref();
+    try {
+        const response = await fetch(ANTHROPIC_TOKEN_URL, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', accept: 'application/json' },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+        const responseBody = await response.text();
+        if (!response.ok) {
+            return failure(502, `Anthropic token exchange failed with HTTP ${response.status} ${response.statusText}${responseBody.trim() === '' ? '' : `: ${responseBody}`}`);
+        }
+        return { ok: true, body: responseBody };
+    }
+    catch (error) {
+        return failure(502, `Anthropic token exchange request failed: ${redactedErrorMessage(error)}`);
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function validateTokenExchangeResponse(body, now) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return failure(502, `Anthropic token exchange returned invalid JSON: ${body}`);
+    }
+    const access = typeof parsed.access_token === 'string' ? parsed.access_token.trim() : '';
+    const refresh = typeof parsed.refresh_token === 'string' ? parsed.refresh_token.trim() : '';
+    const expiresIn = typeof parsed.expires_in === 'number' ? parsed.expires_in : Number.NaN;
+    if (access === '' || refresh === '' || !Number.isFinite(expiresIn) || expiresIn <= 0) {
+        return failure(502, 'Anthropic token exchange response is missing access_token, refresh_token, or positive expires_in');
+    }
+    return { type: 'oauth', access, refresh, expires: now + expiresIn * 1000 - ANTHROPIC_TOKEN_SKEW_MS };
+}
+function startAnthropicOAuthSession(now) {
+    purgeExpiredSession(now);
+    const sessionId = defaultRandomBytes(16).toString('base64url');
+    const verifier = defaultRandomBytes(32).toString('base64url');
+    const session = {
+        sessionId,
+        state: verifier,
+        verifier,
+        createdAt: now,
+        expiresAt: now + ANTHROPIC_SESSION_TTL_MS,
+    };
+    const challenge = defaultSha256(verifier).toString('base64url');
+    currentSession = session;
+    return { sessionId, authUrl: buildAuthUrl(session, challenge), expiresAt: session.expiresAt };
+}
+async function finishAnthropicOAuthSession(sessionId, redirectUrl) {
+    const now = Date.now();
+    purgeExpiredSession(now);
+    const session = currentSession;
+    if (session === undefined) {
+        return failure(400, 'Anthropic OAuth session not found or expired');
+    }
+    // Delete on first use regardless of outcome below — a session is single-shot.
+    currentSession = undefined;
+    if (session.sessionId !== sessionId) {
+        return failure(400, 'Anthropic OAuth session id does not match the active session');
+    }
+    const parsed = parseCallbackUrl(redirectUrl);
+    if ('status' in parsed)
+        return parsed;
+    if (parsed.state !== session.state) {
+        return failure(400, 'Anthropic OAuth callback state mismatch');
+    }
+    const result = await postTokenExchange({
+        grant_type: 'authorization_code',
+        client_id: ANTHROPIC_CLIENT_ID,
+        code: parsed.code,
+        state: parsed.state,
+        redirect_uri: ANTHROPIC_REDIRECT_URI,
+        code_verifier: session.verifier,
+    });
+    if ('status' in result)
+        return result;
+    const credential = validateTokenExchangeResponse(result.body, now);
+    if ('status' in credential)
+        return credential;
+    return { ok: true, sessionId: session.sessionId, credential };
+}
+// ── AuthStorage (direct, in-guest — no runGuestSource round-trip) ──────────
+function readAnthropicStatus() {
+    const storage = AuthStorage.create();
+    const credential = storage.get('anthropic');
+    const errors = storage.drainErrors();
+    if (errors.length > 0) {
+        throw new Error(errors.map((error) => error.message).join('; '));
+    }
+    const adapterConfigured = storage.getOAuthProviders().some((provider) => provider.id === 'anthropic');
+    const storedOauth = credential?.type === 'oauth';
+    const expiresAt = storedOauth ? credential.expires : null;
+    return { storedOauth, expiresAt, adapterConfigured };
+}
+function writeAnthropicCredential(credential) {
+    const storage = AuthStorage.create();
+    // pi-ai's `OAuthCredentials` carries a `[key: string]: unknown` index
+    // signature for adapter-specific extra fields; our narrower
+    // AnthropicOAuthCredential is otherwise structurally identical (`type`,
+    // `refresh`, `access`, `expires`), so this is a safe widen, not a cast away
+    // from a real type mismatch.
+    storage.set('anthropic', credential);
+    const errors = storage.drainErrors();
+    if (errors.length > 0) {
+        throw new Error(errors.map((error) => error.message).join('; '));
+    }
+    // set() mutates in-memory state before persistence — re-read through a FRESH
+    // AuthStorage instance to verify the write actually round-tripped to disk.
+    const reread = AuthStorage.create();
+    const stored = reread.get('anthropic');
+    const rereadErrors = reread.drainErrors();
+    if (rereadErrors.length > 0) {
+        throw new Error(rereadErrors.map((error) => error.message).join('; '));
+    }
+    if (stored === undefined ||
+        stored.type !== 'oauth' ||
+        stored.refresh !== credential.refresh ||
+        stored.access !== credential.access ||
+        stored.expires !== credential.expires) {
+        throw new Error('stored anthropic oauth credential did not round-trip');
+    }
+    return { storedOauth: true, expiresAt: stored.expires };
+}
+// ── HTTP plumbing ───────────────────────────────────────────────────────
+function respondJson(res, statusCode, value) {
+    const body = `${JSON.stringify(value, null, 2)}\n`;
+    res.writeHead(statusCode, {
+        'content-type': 'application/json; charset=utf-8',
+        'content-length': Buffer.byteLength(body),
+        'cache-control': 'no-store',
+    });
+    res.end(body);
+}
+function respondText(res, statusCode, message) {
+    const body = `${redact(message)}\n`;
+    res.writeHead(statusCode, {
+        'content-type': 'text/plain; charset=utf-8',
+        'content-length': Buffer.byteLength(body),
+        'cache-control': 'no-store',
+    });
+    res.end(body);
+}
+/** Read a request body up to `limitBytes`, rejecting (and destroying the
+ *  socket) if it grows past the cap. */
+function readJsonBody(req, limitBytes) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let bytes = 0;
+        const cleanup = () => {
+            req.off('data', onData);
+            req.off('end', onEnd);
+            req.off('error', onError);
+            req.off('aborted', onAbort);
+        };
+        const onData = (chunk) => {
+            bytes += chunk.byteLength;
+            if (bytes > limitBytes) {
+                cleanup();
+                req.destroy();
+                reject(new Error(`request body too large (limit ${limitBytes} bytes)`));
+                return;
+            }
+            chunks.push(chunk);
+        };
+        const onEnd = () => {
+            cleanup();
+            try {
+                const text = Buffer.concat(chunks).toString('utf8');
+                resolve(text === '' ? {} : JSON.parse(text));
+            }
+            catch (error) {
+                reject(error instanceof Error ? error : new Error(String(error)));
+            }
+        };
+        const onError = (error) => {
+            cleanup();
+            reject(error instanceof Error ? error : new Error(String(error)));
+        };
+        const onAbort = () => {
+            cleanup();
+            reject(new Error('request aborted while reading body'));
+        };
+        req.on('data', onData);
+        req.once('end', onEnd);
+        req.once('error', onError);
+        req.once('aborted', onAbort);
+    });
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function parseFinishBody(body) {
+    if (!isPlainObject(body))
+        return null;
+    if (Object.keys(body).length !== 2)
+        return null;
+    const sessionId = typeof body.sessionId === 'string' ? body.sessionId.trim() : '';
+    const redirectUrl = typeof body.redirectUrl === 'string' ? body.redirectUrl.trim() : '';
+    if (sessionId === '' || redirectUrl === '')
+        return null;
+    return { sessionId, redirectUrl };
+}
+async function handleStatus(req, res) {
+    if (req.method !== 'GET') {
+        respondText(res, 405, 'method not allowed');
+        return;
+    }
+    try {
+        respondJson(res, 200, readAnthropicStatus());
+    }
+    catch (error) {
+        respondJson(res, 502, { error: redactedErrorMessage(error) });
+    }
+}
+async function handleStart(req, res) {
+    if (req.method !== 'POST') {
+        respondText(res, 405, 'method not allowed');
+        return;
+    }
+    let body;
+    try {
+        body = await readJsonBody(req, BODY_LIMIT_BYTES);
+    }
+    catch (error) {
+        respondJson(res, 400, { error: redactedErrorMessage(error) });
+        return;
+    }
+    if (!isPlainObject(body)) {
+        respondJson(res, 400, { error: 'start request must be empty or a JSON object' });
+        return;
+    }
+    try {
+        const started = startAnthropicOAuthSession(Date.now());
+        respondJson(res, 200, {
+            provider: 'anthropic',
+            sessionId: started.sessionId,
+            authUrl: started.authUrl,
+            expiresAt: started.expiresAt,
+        });
+    }
+    catch (error) {
+        respondJson(res, 502, { error: redactedErrorMessage(error) });
+    }
+}
+async function handleFinish(req, res) {
+    if (req.method !== 'POST') {
+        respondText(res, 405, 'method not allowed');
+        return;
+    }
+    let body;
+    try {
+        body = await readJsonBody(req, BODY_LIMIT_BYTES);
+    }
+    catch (error) {
+        respondJson(res, 400, { error: redactedErrorMessage(error) });
+        return;
+    }
+    const parsed = parseFinishBody(body);
+    if (parsed === null) {
+        respondJson(res, 400, { error: 'finish request must be { sessionId, redirectUrl }' });
+        return;
+    }
+    try {
+        const finished = await finishAnthropicOAuthSession(parsed.sessionId, parsed.redirectUrl);
+        if (!finished.ok) {
+            respondJson(res, finished.status, { error: finished.error });
+            return;
+        }
+        const stored = writeAnthropicCredential(finished.credential);
+        respondJson(res, 200, {
+            ok: true,
+            provider: 'anthropic',
+            sessionId: finished.sessionId,
+            storedOauth: stored.storedOauth,
+            expiresAt: stored.expiresAt,
+        });
+    }
+    catch (error) {
+        respondJson(res, 502, { error: redactedErrorMessage(error) });
+    }
+}
+/** Dispatch one `/__hearth/model-auth/anthropic/{status,start,finish}` request.
+ *  The caller (src/clients/web/server.ts) has already matched the path prefix
+ *  and enforced the relay token — this function assumes both are done and
+ *  handles ONLY routing-within-the-lane, method checks, and the Hearth/OAuth
+ *  product logic. Always writes a response; never throws (errors become a
+ *  redacted 502/500 JSON body). */
+export async function handleHearthModelAuthRequest(req, res) {
+    const pathname = new URL(req.url ?? '/', 'http://127.0.0.1').pathname;
+    try {
+        if (pathname === '/__hearth/model-auth/anthropic/status') {
+            await handleStatus(req, res);
+            return;
+        }
+        if (pathname === '/__hearth/model-auth/anthropic/start') {
+            await handleStart(req, res);
+            return;
+        }
+        if (pathname === '/__hearth/model-auth/anthropic/finish') {
+            await handleFinish(req, res);
+            return;
+        }
+        respondText(res, 404, 'not found');
+    }
+    catch (error) {
+        if (!res.headersSent) {
+            respondJson(res, 500, { error: redactedErrorMessage(error) });
+        }
+        else {
+            res.destroy();
+        }
+    }
+}

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

@@ -0,0 +1,28 @@
+import type { HomeProviderDescriptor, HomeProviderRefresh, MachineId, MachineRef, M0Config } from './types.js';
+import type { ExecInput, ExecResult } from './providers/types.js';
+/**
+ * The Hearth home backend seam. The wake-proxy front door (token auth, origin checks,
+ * SSE/WS forwarding, the source gate) is vendor-neutral and drives a home purely through
+ * this interface — never a concrete sandbox SDK.
+ */
+export interface HomeBackend {
+    /**
+     * Bring a CP-resolved home up and serving — warm-resume or recreate as the backend decides —
+     * and return refreshed provider pointers for the CP registry to persist.
+     */
+    wake(home: HomeProviderDescriptor): 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. */
+    getMachine(machineId: MachineId): Promise<MachineRef | null>;
+    /**
+     * The P2.6 stdin-capable provider exec seam, exposed through this vendor-neutral interface
+     * so CP code (P4.4 `wakeAndExecNodeMessage`) never imports a concrete sandbox SDK to run an
+     * in-guest command. Callers pass untrusted bodies via `input.stdin`, never `input.command`.
+     */
+    exec(machineId: MachineId, input: ExecInput): Promise<ExecResult>;
+}
+/**
+ * Resolve the configured home backend.
+ */
+export declare function getHomeBackend(config: M0Config): HomeBackend;

package/dist/core/hearth/provider.js

@@ -0,0 +1,10 @@
+import { general } from '../errors.js';
+import { BlaxelHomeBackend } from './providers/blaxel-home.js';
+/**
+ * Resolve the configured home backend.
+ */
+export function getHomeBackend(config) {
+    if (config.providerName === 'blaxel')
+        return new BlaxelHomeBackend(config);
+    throw general('no Hearth home provider configured — Blaxel backend pending', { status: 503 });
+}

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

@@ -0,0 +1,12 @@
+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

@@ -0,0 +1,147 @@
+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)} canvas 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

@@ -0,0 +1,15 @@
+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>;
+    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>;
+}