sliccy 3.5.4 → 3.6.0

package/dist/node-server/cloud/dispatch.js

@@ -0,0 +1,79 @@
+const VALID_SUBCOMMANDS = ['start', 'list', 'pause', 'resume', 'kill'];
+export function parseCloudArgs(argv) {
+    if (argv.includes('--hosted') && argv.includes('--cloud')) {
+        throw new Error('--cloud and --hosted are mutually exclusive');
+    }
+    const cloudIdx = argv.indexOf('--cloud');
+    if (cloudIdx === -1)
+        return null;
+    const sub = argv[cloudIdx + 1];
+    if (!sub || !VALID_SUBCOMMANDS.includes(sub)) {
+        throw new Error(`unknown subcommand: ${sub ?? '(none)'} (expected one of: ${VALID_SUBCOMMANDS.join(', ')})`);
+    }
+    const rest = argv.slice(cloudIdx + 2);
+    const baseArgs = {
+        substrate: 'e2b',
+    };
+    let i = 0;
+    while (i < rest.length) {
+        const a = rest[i];
+        if (a === '--name') {
+            baseArgs.name = rest[++i];
+        }
+        else if (a === '--env-file') {
+            baseArgs.envFile = rest[++i];
+        }
+        else if (a === '--substrate') {
+            const v = rest[++i];
+            if (v !== 'e2b')
+                throw new Error(`unsupported substrate: ${v} (MVP only supports 'e2b')`);
+            baseArgs.substrate = v;
+        }
+        else if (!a.startsWith('--') &&
+            !baseArgs.query &&
+            (sub === 'pause' || sub === 'resume' || sub === 'kill')) {
+            baseArgs.query = a;
+        }
+        else {
+            throw new Error(`unrecognized arg: ${a}`);
+        }
+        i++;
+    }
+    // Build discriminated union based on subcommand
+    switch (sub) {
+        case 'start':
+            return {
+                subcommand: 'start',
+                args: {
+                    substrate: baseArgs.substrate,
+                    name: baseArgs.name,
+                    envFile: baseArgs.envFile,
+                },
+            };
+        case 'list':
+            return { subcommand: 'list', args: { substrate: baseArgs.substrate } };
+        case 'pause':
+        case 'kill':
+            if (!baseArgs.query) {
+                throw new Error(`${sub} requires a query argument (sandbox ID or name)`);
+            }
+            return {
+                subcommand: sub,
+                args: { substrate: baseArgs.substrate, query: baseArgs.query },
+            };
+        case 'resume':
+            if (!baseArgs.query) {
+                throw new Error(`${sub} requires a query argument (sandbox ID or name)`);
+            }
+            return {
+                subcommand: 'resume',
+                args: {
+                    substrate: baseArgs.substrate,
+                    query: baseArgs.query,
+                    envFile: baseArgs.envFile,
+                },
+            };
+        default:
+            throw new Error(`unknown subcommand: ${sub}`);
+    }
+}

package/dist/node-server/cloud/kill.d.ts

@@ -0,0 +1,12 @@
+import { type SandboxSubstrate } from '../_cloud_core/src/index.js';
+export interface RunKillOpts {
+    substrate: SandboxSubstrate;
+    registryPath: string;
+    query: string;
+}
+/**
+ * Thin wrapper over killCone from @slicc/cloud-core.
+ * Adapts the cloud-core interface to the node-server's file-backed registry.
+ * Returns void for backward compatibility with existing callers.
+ */
+export declare function runKill(opts: RunKillOpts): Promise<void>;

package/dist/node-server/cloud/kill.js

@@ -0,0 +1,11 @@
+import { killCone } from '../_cloud_core/src/index.js';
+import { FileRegistry } from './registry-file.js';
+/**
+ * Thin wrapper over killCone from @slicc/cloud-core.
+ * Adapts the cloud-core interface to the node-server's file-backed registry.
+ * Returns void for backward compatibility with existing callers.
+ */
+export async function runKill(opts) {
+    const registry = new FileRegistry(opts.registryPath);
+    await killCone({ substrate: opts.substrate, registry }, opts.query);
+}

package/dist/node-server/cloud/list.d.ts

@@ -0,0 +1,6 @@
+import { type ConeEntry, type SandboxSubstrate } from '../_cloud_core/src/index.js';
+export interface RunListOpts {
+    substrate: SandboxSubstrate;
+    registryPath: string;
+}
+export declare function runList(opts: RunListOpts): Promise<ConeEntry[]>;

package/dist/node-server/cloud/list.js

@@ -0,0 +1,6 @@
+import { listCones } from '../_cloud_core/src/index.js';
+import { FileRegistry } from './registry-file.js';
+export async function runList(opts) {
+    const registry = new FileRegistry(opts.registryPath);
+    return listCones({ substrate: opts.substrate, registry });
+}

package/dist/node-server/cloud/pause.d.ts

@@ -0,0 +1,7 @@
+import { type SandboxSubstrate } from '../_cloud_core/src/index.js';
+export interface RunPauseOpts {
+    substrate: SandboxSubstrate;
+    registryPath: string;
+    query: string;
+}
+export declare function runPause(opts: RunPauseOpts): Promise<void>;

package/dist/node-server/cloud/pause.js

@@ -0,0 +1,6 @@
+import { pauseCone } from '../_cloud_core/src/index.js';
+import { FileRegistry } from './registry-file.js';
+export async function runPause(opts) {
+    const registry = new FileRegistry(opts.registryPath);
+    return pauseCone({ substrate: opts.substrate, registry }, opts.query);
+}

package/dist/node-server/cloud/registry-file.d.ts

@@ -0,0 +1,13 @@
+import type { ConeEntry, Registry } from '../_cloud_core/src/index.js';
+export declare class FileRegistry implements Registry {
+    private readonly filePath;
+    constructor(filePath: string);
+    static defaultPath(): string;
+    list(): Promise<ConeEntry[]>;
+    append(entry: ConeEntry): Promise<void>;
+    update(sandboxId: string, patch: Partial<ConeEntry>): Promise<void>;
+    remove(sandboxId: string): Promise<void>;
+    findByNameOrId(query: string): Promise<ConeEntry | null>;
+    private read;
+    private write;
+}

package/dist/node-server/cloud/registry-file.js

@@ -0,0 +1,85 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+function isConeEntry(x) {
+    if (typeof x !== 'object' || x === null)
+        return false;
+    const e = x;
+    return (typeof e.substrate === 'string' &&
+        typeof e.sandboxId === 'string' &&
+        typeof e.createdAt === 'string' &&
+        typeof e.joinUrl === 'string' &&
+        typeof e.lastSeen === 'string' &&
+        typeof e.state === 'string' &&
+        (e.state === 'running' || e.state === 'paused' || e.state === 'dead' || e.state === 'reserved'));
+}
+export class FileRegistry {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    static defaultPath() {
+        const home = process.env['HOME'] ?? process.env['USERPROFILE'] ?? '.';
+        return path.join(home, '.slicc', 'cloud-sessions.json');
+    }
+    async list() {
+        const data = await this.read();
+        return data.sessions;
+    }
+    async append(entry) {
+        const data = await this.read();
+        // UPSERT semantics: filter out existing sandboxId, then push the new entry
+        data.sessions = data.sessions.filter((s) => s.sandboxId !== entry.sandboxId);
+        data.sessions.push(entry);
+        await this.write(data);
+    }
+    async update(sandboxId, patch) {
+        const data = await this.read();
+        const idx = data.sessions.findIndex((s) => s.sandboxId === sandboxId);
+        if (idx === -1) {
+            throw new Error(`entry not found: ${sandboxId}`);
+        }
+        data.sessions[idx] = { ...data.sessions[idx], ...patch, sandboxId };
+        await this.write(data);
+    }
+    async remove(sandboxId) {
+        const data = await this.read();
+        data.sessions = data.sessions.filter((s) => s.sandboxId !== sandboxId);
+        await this.write(data);
+    }
+    async findByNameOrId(query) {
+        const data = await this.read();
+        return (data.sessions.find((s) => s.sandboxId === query) ??
+            data.sessions.find((s) => s.name === query) ??
+            null);
+    }
+    async read() {
+        let raw;
+        try {
+            raw = JSON.parse(await fs.readFile(this.filePath, 'utf-8'));
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return { sessions: [] };
+            throw err;
+        }
+        if (typeof raw !== 'object' ||
+            raw === null ||
+            !Array.isArray(raw.sessions)) {
+            console.warn('cloud-sessions.json is malformed; treating as empty', this.filePath);
+            return { sessions: [] };
+        }
+        const candidates = raw.sessions;
+        const sessions = [];
+        for (const c of candidates) {
+            if (isConeEntry(c))
+                sessions.push(c);
+            else
+                console.warn('skipping malformed cloud-sessions entry', c);
+        }
+        return { sessions };
+    }
+    async write(data) {
+        await fs.mkdir(path.dirname(this.filePath), { recursive: true });
+        await fs.writeFile(this.filePath, JSON.stringify(data, null, 2));
+    }
+}

package/dist/node-server/cloud/resume.d.ts

@@ -0,0 +1,11 @@
+import { type ResumeResult, type SandboxSubstrate } from '../_cloud_core/src/index.js';
+export interface RunResumeOpts {
+    substrate: SandboxSubstrate;
+    envFilePath: string;
+    registryPath: string;
+    query: string;
+    localSliccVersion: string;
+    pollIntervalMs?: number;
+    pollTimeoutMs?: number;
+}
+export declare function runResume(opts: RunResumeOpts): Promise<ResumeResult>;

package/dist/node-server/cloud/resume.js

@@ -0,0 +1,17 @@
+import { promises as fs } from 'node:fs';
+import { resumeCone } from '../_cloud_core/src/index.js';
+import { FileRegistry } from './registry-file.js';
+export async function runResume(opts) {
+    // Refresh on resume so cones paused for >24h pick up a freshly-issued token
+    // from the local secrets.env. This was a pre-existing CLI gap — resume would
+    // succeed but Adobe LLM calls would 401 on expired tokens.
+    const envContents = await fs.readFile(opts.envFilePath, 'utf-8');
+    const registry = new FileRegistry(opts.registryPath);
+    return resumeCone({ substrate: opts.substrate, registry }, {
+        query: opts.query,
+        localSliccVersion: opts.localSliccVersion,
+        refreshSecretsContents: envContents,
+        pollIntervalMs: opts.pollIntervalMs,
+        pollTimeoutMs: opts.pollTimeoutMs,
+    });
+}

package/dist/node-server/cloud/start.d.ts

@@ -0,0 +1,16 @@
+import { type StartResult, type SandboxHandle } from '../_cloud_core/src/index.js';
+import type { SandboxSubstrate } from '../_cloud_core/src/index.js';
+export interface RunStartOpts {
+    substrate: SandboxSubstrate;
+    envFilePath: string;
+    registryPath: string;
+    workerBaseUrl: string;
+    sliccVersion: string;
+    template?: string;
+    name?: string;
+    pollIntervalMs?: number;
+    pollTimeoutMs?: number;
+    /** Test-only hook: invoked after substrate.create but before pollCloudStatus. */
+    onAfterCreate?: (handle: SandboxHandle) => Promise<void>;
+}
+export declare function runStart(opts: RunStartOpts): Promise<StartResult>;

package/dist/node-server/cloud/start.js

@@ -0,0 +1,49 @@
+import { promises as fs } from 'node:fs';
+import { startCone } from '../_cloud_core/src/index.js';
+import { FileRegistry } from './registry-file.js';
+/**
+ * Extract ADOBE_IMS_TOKEN (+ DOMAINS) from an env-file body so they can be
+ * injected as sandbox env vars at Sandbox.create. start.sh writes them to
+ * /slicc/secrets.env BEFORE node-server boots, eliminating the historical 5s
+ * race window where the page-side bootstrap fetch found no secrets file.
+ */
+function extractAdobeBootstrap(envContents) {
+    const envs = {};
+    for (const line of envContents.split('\n')) {
+        const m = line.match(/^\s*(ADOBE_IMS_TOKEN(?:_DOMAINS)?)\s*=\s*(.*)$/);
+        if (m)
+            envs[m[1]] = m[2].trim();
+    }
+    return envs;
+}
+export async function runStart(opts) {
+    const envContents = await fs.readFile(opts.envFilePath, 'utf-8');
+    const adobeBootstrap = extractAdobeBootstrap(envContents);
+    const registry = new FileRegistry(opts.registryPath);
+    // If we have a test hook, wrap the substrate to inject it.
+    let substrate = opts.substrate;
+    if (opts.onAfterCreate) {
+        const originalCreate = substrate.create.bind(substrate);
+        substrate = {
+            ...substrate,
+            create: async (createOpts) => {
+                const handle = await originalCreate(createOpts);
+                await opts.onAfterCreate(handle);
+                return handle;
+            },
+        };
+    }
+    return startCone({ substrate, registry }, {
+        envContents,
+        envs: adobeBootstrap,
+        workerBaseUrl: opts.workerBaseUrl,
+        template: opts.template,
+        name: opts.name,
+        sliccVersion: opts.sliccVersion,
+        pollTimeoutMs: opts.pollTimeoutMs,
+        pollIntervalMs: opts.pollIntervalMs,
+        metadata: {
+            createdBy: process.env['USER'] ?? 'unknown',
+        },
+    });
+}

package/dist/node-server/cloud-status.d.ts

@@ -0,0 +1,11 @@
+import { type Express, type Request, type Response, type NextFunction } from 'express';
+export interface CloudStatusEndpointOptions {
+    joinFilePath: string;
+}
+/**
+ * Reject non-loopback requests. The sandbox is a private execution boundary,
+ * but defense in depth: someone might wire a port-forward and we want this
+ * endpoint to be unreachable from the outside.
+ */
+export declare function requireLoopback(req: Request, res: Response, next: NextFunction): void;
+export declare function registerCloudStatusEndpoint(app: Express, options: CloudStatusEndpointOptions): void;

package/dist/node-server/cloud-status.js

@@ -0,0 +1,49 @@
+import express from 'express';
+import { promises as fs } from 'node:fs';
+function isCloudStatusPayload(x) {
+    if (typeof x !== 'object' || x === null)
+        return false;
+    const p = x;
+    if (typeof p.joinUrl !== 'string' || p.joinUrl.length === 0)
+        return false;
+    // Optional fields: validate type if present, but don't require.
+    for (const key of ['trayId', 'controllerUrl', 'webhookUrl', 'runtime', 'sliccVersion']) {
+        if (key in p && typeof p[key] !== 'string')
+            return false;
+    }
+    return true;
+}
+/**
+ * Reject non-loopback requests. The sandbox is a private execution boundary,
+ * but defense in depth: someone might wire a port-forward and we want this
+ * endpoint to be unreachable from the outside.
+ */
+export function requireLoopback(req, res, next) {
+    const addr = req.socket.remoteAddress ?? '';
+    const isLoopback = addr === '127.0.0.1' || addr === '::1' || addr === '::ffff:127.0.0.1' || addr === 'localhost';
+    if (!isLoopback) {
+        res.status(403).json({ error: 'localhost only' });
+        return;
+    }
+    next();
+}
+export function registerCloudStatusEndpoint(app, options) {
+    app.post('/api/cloud-status', requireLoopback, express.json(), async (req, res) => {
+        if (!isCloudStatusPayload(req.body)) {
+            res.status(400).json({ error: 'invalid cloud-status payload' });
+            return;
+        }
+        const body = req.body;
+        const payload = {
+            joinUrl: body.joinUrl,
+            trayId: body.trayId ?? null,
+            controllerUrl: body.controllerUrl ?? null,
+            webhookUrl: body.webhookUrl ?? null,
+            runtime: body.runtime ?? null,
+            sliccVersion: body.sliccVersion ?? null,
+            updatedAt: new Date().toISOString(),
+        };
+        await fs.writeFile(options.joinFilePath, JSON.stringify(payload, null, 2));
+        res.json({ ok: true });
+    });
+}

package/dist/node-server/hosted-bootstrap.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Loopback-only endpoint that hands the hosted-leader page any pre-acquired
+ * provider credentials that were uploaded with secrets.env.
+ *
+ * Currently exposes ADOBE_IMS_TOKEN so the laptop can paste in an IMS bearer
+ * once (avoiding OAuth, which can't complete in headless chromium). The
+ * webapp's hosted-leader boot calls saveOAuthAccount with the returned token
+ * before any LLM call goes out.
+ *
+ * Same loopback discipline as /api/cloud-status and /api/leader-restart:
+ * chromium-on-localhost is the only thing that can hit it; the laptop-side
+ * orchestrator talks to the leader through the tray-worker tunnel, not http.
+ */
+import type { Express } from 'express';
+import type { SecretStore } from './secrets/types.js';
+export interface HostedBootstrapPayload {
+    adobeImsToken?: string;
+}
+export declare function registerHostedBootstrapEndpoint(app: Express, options: {
+    secretStore: SecretStore;
+}): void;

package/dist/node-server/hosted-bootstrap.js

@@ -0,0 +1,14 @@
+import { requireLoopback } from './cloud-status.js';
+export function registerHostedBootstrapEndpoint(app, options) {
+    app.get('/api/hosted-bootstrap', requireLoopback, (_req, res) => {
+        const payload = {};
+        // EnvSecretStore.get(name) requires both the value AND a <name>_DOMAINS
+        // entry. The user's secrets.env must contain BOTH:
+        //   ADOBE_IMS_TOKEN=<bearer>
+        //   ADOBE_IMS_TOKEN_DOMAINS=adobe-llm-proxy.paolo-moz.workers.dev
+        const token = options.secretStore.get('ADOBE_IMS_TOKEN');
+        if (token?.value)
+            payload.adobeImsToken = token.value;
+        res.json(payload);
+    });
+}

package/dist/node-server/index.js

@@ -22,10 +22,30 @@ import { SecretProxyManager } from './secrets/proxy-manager.js';
 import { OauthSecretStore } from './secrets/oauth-secret-store.js';
 import { handleDaSignAndForward, handleS3SignAndForward } from './secrets/sign-and-forward.js';
 import { readOrCreateSessionId } from './secrets/session-id-file.js';
+import { registerCloudStatusEndpoint } from './cloud-status.js';
+import { registerHostedBootstrapEndpoint } from './hosted-bootstrap.js';
+import { createHttpCdp, registerLeaderRestartEndpoint } from './leader-restart.js';
 import { FETCH_PROXY_SKIP_HEADERS } from './fetch-proxy-headers.js';
 import { buildLocalApiDescriptor, sliccLinksMiddleware } from './links-middleware.js';
+import { parseCloudArgs } from './cloud/dispatch.js';
+import { createSubstrate } from './_cloud_core/src/index.js';
+import { FileRegistry } from './cloud/registry-file.js';
+import { runStart } from './cloud/start.js';
+import { runList } from './cloud/list.js';
+import { runPause } from './cloud/pause.js';
+import { runResume } from './cloud/resume.js';
+import { runKill } from './cloud/kill.js';
+import { promises as fsPromises } from 'node:fs';
 const __dirname = fileURLToPath(new URL('.', import.meta.url));
 const PROJECT_ROOT = resolve(__dirname, '..', '..');
+// ---------------------------------------------------------------------------
+// Cloud dispatcher — must run BEFORE any other boot logic
+// ---------------------------------------------------------------------------
+const _parsedCloudArgs = parseCloudArgs(process.argv.slice(2));
+if (_parsedCloudArgs) {
+    await runCloudSubcommand(_parsedCloudArgs);
+    process.exit(0);
+}
 const RUNTIME_FLAGS = parseCliRuntimeFlags(process.argv.slice(2));
 // Version command — exit immediately, no side effects
 if (RUNTIME_FLAGS.version) {
@@ -420,6 +440,11 @@ async function main() {
             join: RUNTIME_FLAGS.join,
             joinUrl: RUNTIME_FLAGS.joinUrl,
         });
+        // Append runtime parameter for hosted mode
+        if (RUNTIME_FLAGS.hosted) {
+            const sep = browserLaunchUrl.includes('?') ? '&' : '?';
+            browserLaunchUrl += `${sep}runtime=hosted-leader`;
+        }
         // Append optional prompt parameter
         if (RUNTIME_FLAGS.prompt) {
             const sep = browserLaunchUrl.includes('?') ? '&' : '?';
@@ -433,12 +458,17 @@ async function main() {
         }
         const chromeProfile = (() => {
             try {
-                return resolveChromeLaunchProfile({
+                const resolved = resolveChromeLaunchProfile({
                     projectRoot: PROJECT_ROOT,
                     tmpDir: process.env['TMPDIR'] ?? '/tmp',
                     profile: RUNTIME_FLAGS.profile,
                     servePort: SERVE_PORT,
                 });
+                // Override user data dir in hosted mode to use persistent profile
+                if (RUNTIME_FLAGS.hosted) {
+                    resolved.userDataDir = process.env['CHROME_USER_DATA_DIR'] ?? '/data/profile';
+                }
+                return resolved;
             }
             catch (error) {
                 console.error(error instanceof Error ? error.message : String(error));
@@ -471,6 +501,7 @@ async function main() {
             cdpPort: REQUESTED_CDP_PORT,
             launchUrl: browserLaunchUrl,
             profile: chromeProfile,
+            hosted: RUNTIME_FLAGS.hosted,
         });
         // Profile directories are reused across runs (both the dev
         // `/tmp/browser-coding-agent-chrome` profile and the persistent
@@ -678,7 +709,10 @@ async function main() {
     }));
     app.get('/api/runtime-config', (_req, res) => {
         res.json({
-            trayWorkerBaseUrl: RUNTIME_FLAGS.leadWorkerBaseUrl ??
+            trayWorkerBaseUrl: 
+            // Hosted mode source: env var injected at sandbox-create time.
+            (RUNTIME_FLAGS.hosted ? process.env['SLICC_TRAY_WORKER_BASE_URL']?.trim() : null) ??
+                RUNTIME_FLAGS.leadWorkerBaseUrl ??
                 (process.env['WORKER_BASE_URL']?.trim() || null) ??
                 (DEV_MODE
                     ? 'https://slicc-tray-hub-staging.minivelos.workers.dev'
@@ -992,6 +1026,14 @@ async function main() {
         await secretProxy.reload();
         res.status(204).end();
     });
+    // Cloud status endpoint (hosted-only) — writes join info to /tmp/slicc-join.json
+    // Register BEFORE Chromium launches. The webapp's first action after
+    // ?runtime=hosted-leader boot is to mint a tray and POST /api/cloud-status.
+    // If the route doesn't exist yet, the post 404s and the CLI poll times out.
+    if (RUNTIME_FLAGS.hosted) {
+        registerCloudStatusEndpoint(app, { joinFilePath: '/tmp/slicc-join.json' });
+        registerHostedBootstrapEndpoint(app, { secretStore });
+    }
     // Fetch proxy — forwards cross-origin requests from the browser to bypass CORS.
     // Used by just-bash's curl which calls the browser's fetch() API.
     // Note: express.json() may have already parsed the body, so we check req.body first.
@@ -1304,7 +1346,7 @@ async function main() {
     });
     // Create the HTTP server BEFORE Vite so we can register our upgrade handler first
     const server = createServer(app);
-    if (DEV_MODE) {
+    if (DEV_MODE && !RUNTIME_FLAGS.hosted) {
         // Dev mode: use Vite's dev server as middleware for HMR
         const { createServer: createViteServer } = await import('vite');
         const webappIndexHtml = resolve(process.cwd(), 'packages/webapp/index.html');
@@ -1730,6 +1772,14 @@ async function main() {
                 console.log(`[cdp-proxy] Pre-connected: CDP available at ${cdpUrl}`);
                 await ensureChromeConnection(cdpUrl);
                 console.log('[cdp-proxy] Chrome WebSocket ready (pre-warmed)');
+                // Register leader-restart endpoint now that CDP is ready (hosted mode only)
+                if (RUNTIME_FLAGS.hosted) {
+                    registerLeaderRestartEndpoint(app, {
+                        cdp: createHttpCdp(CDP_PORT),
+                        localUrlPrefix: `http://localhost:${SERVE_PORT}/`,
+                    });
+                    console.log('[hosted] /api/leader-restart endpoint registered');
+                }
             }
             catch (err) {
                 console.log('[cdp-proxy] Pre-connect failed (will retry on first client):', err);
@@ -1762,6 +1812,99 @@ async function main() {
         }
     });
 }
+// ---------------------------------------------------------------------------
+// Cloud dispatcher helpers
+// ---------------------------------------------------------------------------
+async function readSecretsEnvKey(name) {
+    try {
+        const home = process.env['HOME'] ?? process.env['USERPROFILE'] ?? '.';
+        const file = process.env['SLICC_SECRETS_FILE'] ?? join(home, '.slicc', 'secrets.env');
+        const contents = await fsPromises.readFile(file, 'utf-8');
+        for (const line of contents.split('\n')) {
+            const m = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+            if (m && m[1] === name)
+                return m[2].trim();
+        }
+    }
+    catch {
+        /* file missing → undefined */
+    }
+    return undefined;
+}
+function defaultSecretsPath() {
+    const home = process.env['HOME'] ?? process.env['USERPROFILE'] ?? '.';
+    return join(home, '.slicc', 'secrets.env');
+}
+function readPackageVersion() {
+    try {
+        const pkgPath = join(PROJECT_ROOT, 'package.json');
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+        return pkg.version;
+    }
+    catch {
+        return 'unknown';
+    }
+}
+async function runCloudSubcommand(parsed) {
+    const apiKey = process.env['E2B_API_KEY'] ?? (await readSecretsEnvKey('E2B_API_KEY'));
+    if (!apiKey) {
+        console.error('E2B_API_KEY not set. Add it to ~/.slicc/secrets.env (with E2B_API_KEY_DOMAINS=e2b.dev) ' +
+            'or export it.');
+        process.exit(2);
+    }
+    const substrate = createSubstrate(parsed.args.substrate, { apiKey });
+    const registryPath = FileRegistry.defaultPath();
+    const localSliccVersion = readPackageVersion();
+    switch (parsed.subcommand) {
+        case 'start': {
+            const result = await runStart({
+                substrate,
+                envFilePath: parsed.args.envFile ?? defaultSecretsPath(),
+                registryPath,
+                workerBaseUrl: process.env['SLICC_TRAY_WORKER_BASE_URL']?.trim() || 'https://www.sliccy.ai',
+                sliccVersion: localSliccVersion,
+                name: parsed.args.name,
+            });
+            console.log(`Sandbox ${result.sandboxId} ready.`);
+            console.log(`Open: ${result.joinUrl}`);
+            console.log('Attach from iOS, desktop SLICC, or any browser tab.');
+            break;
+        }
+        case 'list': {
+            const entries = await runList({ substrate, registryPath });
+            for (const e of entries) {
+                console.log(`${e.substrate}\t${e.sandboxId}\t${e.name ?? '-'}\t${e.state}\t${e.joinUrl}`);
+            }
+            break;
+        }
+        case 'pause':
+            await runPause({ substrate, registryPath, query: parsed.args.query });
+            console.log('Paused.');
+            break;
+        case 'resume': {
+            const result = await runResume({
+                substrate,
+                envFilePath: parsed.args.envFile ?? defaultSecretsPath(),
+                registryPath,
+                query: parsed.args.query,
+                localSliccVersion,
+            });
+            if (result.versionMismatch) {
+                console.warn(`Warning: running sandbox is sliccVersion=${result.versionMismatch.running}, ` +
+                    `local CLI is ${result.versionMismatch.local}. Proceeding anyway.`);
+            }
+            if (result.trayRebuilt) {
+                console.warn('Tray was rebuilt; existing followers must re-attach to the new join URL.');
+            }
+            console.log(`Resumed. Open: ${result.joinUrl}`);
+            break;
+        }
+        case 'kill':
+            await runKill({ substrate, registryPath, query: parsed.args.query });
+            console.log('Killed.');
+            break;
+    }
+}
 main().catch((err) => {
     console.error('Fatal error:', err);
     const errorData = err instanceof Error