sliccy 3.5.4 → 3.6.0

package/README.md

@@ -11,7 +11,7 @@ If this scares, confuses, or excites you, keep reading.
 
 # slicc — Self-Licking Ice Cream Cone
 
-[![74% Vibe_Coded](https://img.shields.io/badge/74%25-Vibe_Coded-ff69b4?style=for-the-badge&logo=claude&logoColor=white)](https://github.com/ai-ecoverse/vibe-coded-badge-action)
+[![75% Vibe_Coded](https://img.shields.io/badge/75%25-Vibe_Coded-ff69b4?style=for-the-badge&logo=claude&logoColor=white)](https://github.com/ai-ecoverse/vibe-coded-badge-action)
 
 [![npm](https://img.shields.io/npm/v/sliccy)](https://www.npmjs.com/package/sliccy)
 
@@ -125,7 +125,6 @@ SLICC can mirror itself across multiple browsers, even on other machines:
 1. **First browser:** click your avatar in the top-right header and choose **Enable multi-browser sync**. A dialog opens with the sync URL (already copied to your clipboard) and step-by-step instructions. The same dialog has a **Reset URL** button if you want to invalidate the link and disconnect connected browsers. (You can also type `host` in the built-in terminal to print the URL.)
 2. **Second browser:** open the account dialog, click **Connect to another browser**, and paste the URL. The "How do I get the sync URL?" hint inside the dialog walks through the same steps.
 3. **Leaving the tray:** click the avatar on either browser to open the popover — the tray section now has a **Stop multi-browser sync** (leader) or **Disconnect from leader** (follower) action. From the terminal, `host leave` does the same thing; `host leave --leader <worker-url>` leaves the current role and becomes a leader on that worker.
-4. **Re-enabling after Stop:** once you've stopped multi-browser sync, the avatar popover keeps an **Enable multi-browser sync** entry so you can restart the leader without reloading the extension or dropping into the shell. Clicking it spins up a new leader on the default tray worker; reopen the popover after a moment to copy the fresh sync URL.
 
 Both browsers must run the same SLICC version. Once connected, the sessions stay in sync in real time.
 

package/dist/node-server/_cloud_core/src/errors.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Stable, machine-readable error codes used across cloud operations.
+ * Workers' HTTP handlers translate these to HTTP statuses (Plan D maps the
+ * codes to 403/404/409/503/500 etc.); CLI commands print them. Adding a new
+ * code is fine; renaming/removing one is a breaking change to consumers.
+ */
+export type CloudErrorCode = 'CAP_EXCEEDED' | 'NOT_FOUND' | 'NAME_TAKEN' | 'ALREADY_PAUSED' | 'ALREADY_RUNNING' | 'LEADER_NOT_READY' | 'SANDBOX_NOT_READY' | 'CDP_NOT_READY' | 'CDP_ERROR' | 'DO_UNREACHABLE' | 'UPSTREAM_UNAVAILABLE' | 'INTERNAL';
+export declare class CloudError extends Error {
+    readonly code: CloudErrorCode;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(code: CloudErrorCode, message: string, details?: Record<string, unknown> | undefined);
+}
+export declare function isCloudError(err: unknown): err is CloudError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/node-server/_cloud_core/src/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GACtB,cAAc,GACd,WAAW,GACX,YAAY,GACZ,gBAAgB,GAChB,iBAAiB,GACjB,kBAAkB,GAClB,mBAAmB,GACnB,eAAe,GACf,WAAW,GACX,gBAAgB,GAChB,sBAAsB,GACtB,UAAU,CAAC;AAEf,qBAAa,UAAW,SAAQ,KAAK;aAEjB,IAAI,EAAE,cAAc;aAEpB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBAFjC,IAAI,EAAE,cAAc,EACpC,OAAO,EAAE,MAAM,EACC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAAA;CAKpD;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,UAAU,CAE5D"}

package/dist/node-server/_cloud_core/src/errors.js

@@ -0,0 +1,13 @@
+export class CloudError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = 'CloudError';
+    }
+}
+export function isCloudError(err) {
+    return err instanceof CloudError;
+}

package/dist/node-server/_cloud_core/src/index.d.ts

@@ -0,0 +1,19 @@
+export * from './types.js';
+export * from './errors.js';
+export * from './substrate.js';
+export * from './substrate-factory.js';
+export * from './polling.js';
+export { createE2bSubstrate } from './substrates/e2b.js';
+export { filterSecretsEnv } from './secrets-filter.js';
+export type { Registry } from './registry.js';
+export { startCone, reserveSlot } from './operations/start.js';
+export type { StartConeOpts, StartConeDeps, ReserveSlotOpts } from './operations/start.js';
+export { listCones } from './operations/list.js';
+export type { ListConesDeps, ListConesOpts } from './operations/list.js';
+export { pauseCone } from './operations/pause.js';
+export type { PauseConeDeps } from './operations/pause.js';
+export { resumeCone } from './operations/resume.js';
+export type { ResumeConeOpts, ResumeConeDeps } from './operations/resume.js';
+export { killCone } from './operations/kill.js';
+export type { KillConeDeps, KillConeResult } from './operations/kill.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/node-server/_cloud_core/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,wBAAwB,CAAC;AACvC,cAAc,cAAc,CAAC;AAC7B,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAC/D,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC3F,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACzE,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,YAAY,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7E,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/node-server/_cloud_core/src/index.js

@@ -0,0 +1,14 @@
+// Public re-exports for the @slicc/cloud-core package.
+// Populated by subsequent tasks as we move code in.
+export * from './types.js';
+export * from './errors.js';
+export * from './substrate.js';
+export * from './substrate-factory.js';
+export * from './polling.js';
+export { createE2bSubstrate } from './substrates/e2b.js';
+export { filterSecretsEnv } from './secrets-filter.js';
+export { startCone, reserveSlot } from './operations/start.js';
+export { listCones } from './operations/list.js';
+export { pauseCone } from './operations/pause.js';
+export { resumeCone } from './operations/resume.js';
+export { killCone } from './operations/kill.js';

package/dist/node-server/_cloud_core/src/operations/kill.d.ts

@@ -0,0 +1,18 @@
+import type { Registry } from '../registry.js';
+import type { SandboxSubstrate } from '../substrate.js';
+export interface KillConeDeps {
+    substrate: SandboxSubstrate;
+    registry: Registry;
+}
+export interface KillConeResult {
+    sandboxId: string;
+    alreadyDead: boolean;
+}
+/**
+ * Kill a cloud cone and remove it from the registry.
+ * Discriminates between "not found" substrate errors (sandbox is already gone,
+ * safe to clean up registry) and other errors (network issues, auth failures, etc.)
+ * which are re-thrown to surface the problem without silently leaking credits.
+ */
+export declare function killCone(deps: KillConeDeps, query: string): Promise<KillConeResult>;
+//# sourceMappingURL=kill.d.ts.map

package/dist/node-server/_cloud_core/src/operations/kill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kill.d.ts","sourceRoot":"","sources":["../../../src/operations/kill.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExD,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,gBAAgB,CAAC;IAC5B,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CA0BzF"}

package/dist/node-server/_cloud_core/src/operations/kill.js

@@ -0,0 +1,32 @@
+import { CloudError } from '../errors.js';
+/**
+ * Kill a cloud cone and remove it from the registry.
+ * Discriminates between "not found" substrate errors (sandbox is already gone,
+ * safe to clean up registry) and other errors (network issues, auth failures, etc.)
+ * which are re-thrown to surface the problem without silently leaking credits.
+ */
+export async function killCone(deps, query) {
+    const entry = await deps.registry.findByNameOrId(query);
+    if (!entry)
+        throw new CloudError('NOT_FOUND', `cloud session not found: ${query}`);
+    let alreadyDead = false;
+    try {
+        const handle = await deps.substrate.connect(entry.sandboxId);
+        await handle.kill();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        // Only proceed with registry cleanup if substrate reports "not found".
+        // Other errors (timeouts, auth failures) might leave a sandbox running;
+        // surface them so the user doesn't silently leak credits.
+        const notFound = /not found|unknown sandbox|404|does not exist/i.test(msg);
+        if (!notFound) {
+            throw new CloudError('INTERNAL', `substrate.kill failed (sandbox ${entry.sandboxId}): ${msg}. ` +
+                `Registry entry NOT removed — verify sandbox state manually.`);
+        }
+        // else: substrate doesn't know about it; registry cleanup proceeds below.
+        alreadyDead = true;
+    }
+    await deps.registry.remove(entry.sandboxId);
+    return { sandboxId: entry.sandboxId, alreadyDead };
+}

package/dist/node-server/_cloud_core/src/operations/list.d.ts

@@ -0,0 +1,25 @@
+import type { Registry } from '../registry.js';
+import type { SandboxSubstrate } from '../substrate.js';
+import type { ConeEntry } from '../types.js';
+export interface ListConesDeps {
+    substrate: SandboxSubstrate;
+    registry: Registry;
+}
+export interface ListConesOpts {
+    /**
+     * Restrict substrate.list to sandboxes whose metadata matches.
+     * Worker passes { userId } to scope per-user. CLI passes nothing
+     * (sees every sandbox in the team account).
+     */
+    metadata?: Record<string, string>;
+}
+/**
+ * List cones reconciling registry against substrate.
+ * - Substrate is source of truth for state (running/paused).
+ * - Registry entries missing from substrate → marked 'dead'.
+ * - Substrate sandboxes not in registry → rebuilt and appended (orphan recovery).
+ *
+ * Reconciliation writes are persisted to registry (state flips, entry adds).
+ */
+export declare function listCones(deps: ListConesDeps, opts?: ListConesOpts): Promise<ConeEntry[]>;
+//# sourceMappingURL=list.d.ts.map

package/dist/node-server/_cloud_core/src/operations/list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../../src/operations/list.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,gBAAgB,CAAC;IAC5B,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAC7B,IAAI,EAAE,aAAa,EACnB,IAAI,GAAE,aAAkB,GACvB,OAAO,CAAC,SAAS,EAAE,CAAC,CA8ItB"}

package/dist/node-server/_cloud_core/src/operations/list.js

@@ -0,0 +1,145 @@
+/**
+ * List cones reconciling registry against substrate.
+ * - Substrate is source of truth for state (running/paused).
+ * - Registry entries missing from substrate → marked 'dead'.
+ * - Substrate sandboxes not in registry → rebuilt and appended (orphan recovery).
+ *
+ * Reconciliation writes are persisted to registry (state flips, entry adds).
+ */
+export async function listCones(deps, opts = {}) {
+    const registryEntries = await deps.registry.list();
+    // Pass metadata filter to substrate.list for server-side filtering
+    const live = await deps.substrate.list(opts.metadata ? { metadata: opts.metadata } : undefined);
+    const liveById = new Map(live.map((s) => [s.sandboxId, s]));
+    // Helper to check if an entry matches the metadata filter
+    const matchesFilter = (entry) => {
+        if (!opts.metadata)
+            return true;
+        if (!entry.metadata)
+            return false;
+        for (const [k, v] of Object.entries(opts.metadata)) {
+            if (entry.metadata[k] !== v)
+                return false;
+        }
+        return true;
+    };
+    // Pass 1: walk registry; reconcile against live.
+    // Reconciliation runs for EVERY registry entry regardless of metadata filter
+    // — otherwise zombie entries (e.g. legacy entries without userId metadata)
+    // never get marked dead and accumulate forever in cap math. The metadata
+    // filter is applied to the RETURN value only, so callers still see their
+    // per-user view.
+    const reconciled = [];
+    for (const entry of registryEntries) {
+        // Reserved entries: check for stale reservations (TTL: 10 min) and reclaim.
+        // Stale reservations are from crashed operations that never completed or rolled back.
+        if (entry.state === 'reserved') {
+            const STALE_MS = 10 * 60 * 1000;
+            // Reclaim if stale OR if reservedAt is missing (legacy/malformed entry
+            // from before commit e9011ba6 — could otherwise wedge cap forever).
+            const isStale = !entry.reservedAt || Date.now() - new Date(entry.reservedAt).getTime() > STALE_MS;
+            if (isStale) {
+                await deps.registry.remove(entry.sandboxId);
+                console.warn('[cloud-core] reclaimed stale reservation', {
+                    sandboxId: entry.sandboxId,
+                    reservedAt: entry.reservedAt ?? '(missing)',
+                });
+                continue;
+            }
+            // Active reservation — preserve as-is (in-flight operation holding a cap slot)
+            reconciled.push(entry);
+            continue;
+        }
+        const liveEntry = liveById.get(entry.sandboxId);
+        if (!liveEntry) {
+            // Substrate doesn't know about it — mark dead unless it's a placeholder.
+            // The 'pending-' prefix is a sentinel for "no real sandbox yet" (paired
+            // with state:'reserved' by reserveSlot before substrate.create).
+            if (entry.sandboxId.startsWith('pending-')) {
+                // Reservation placeholder — no real sandbox yet. Keep it alive.
+                reconciled.push(entry);
+            }
+            else {
+                // Real sandbox is missing — mark dead
+                if (entry.state !== 'dead') {
+                    await deps.registry.update(entry.sandboxId, { state: 'dead' });
+                }
+                reconciled.push({ ...entry, state: 'dead' });
+            }
+            continue;
+        }
+        if (entry.state !== liveEntry.state) {
+            await deps.registry.update(entry.sandboxId, { state: liveEntry.state });
+        }
+        reconciled.push({ ...entry, state: liveEntry.state });
+        liveById.delete(entry.sandboxId);
+    }
+    // Pass 2: any substrate entries not in registry → recover.
+    for (const summary of liveById.values()) {
+        const now = new Date().toISOString();
+        // Try to read the real joinUrl from the sandbox. Orphans created before this
+        // fix won't have it in metadata, but we can read /tmp/slicc-join.json directly.
+        let joinUrl = summary.metadata?.['joinUrl'] ?? '';
+        let trayId = summary.metadata?.['trayId'];
+        let lastJoinUpdatedAt = summary.metadata?.['lastJoinUpdatedAt'];
+        // Recover joinUrl from /tmp/slicc-join.json ONLY when sandbox is running.
+        // Calling substrate.connect() on a paused sandbox would RESUME it, which:
+        // (a) burns sandbox runtime silently
+        // (b) destabilizes the leader chromium mid-list
+        // Paused orphans surface with joinUrl='' — UI hides the Open button.
+        // User explicitly resumes via /api/cloud/resume which writes a fresh joinUrl.
+        if (!joinUrl && summary.state === 'running') {
+            try {
+                const handle = await deps.substrate.connect(summary.sandboxId);
+                const joinData = await handle.readFile('/tmp/slicc-join.json');
+                const parsed = JSON.parse(joinData);
+                joinUrl = parsed.joinUrl ?? '';
+                trayId = trayId ?? parsed.trayId;
+                lastJoinUpdatedAt = lastJoinUpdatedAt ?? parsed.updatedAt;
+            }
+            catch (err) {
+                // File not readable (sandbox is transitioning, or file doesn't exist).
+                // Leave joinUrl empty — UI will handle gracefully.
+                const msg = err instanceof Error ? err.message : String(err);
+                console.warn('[cloud-core] orphan recovery readFile failed', {
+                    sandboxId: summary.sandboxId,
+                    err: msg,
+                });
+            }
+        }
+        const recovered = {
+            sandboxId: summary.sandboxId,
+            substrate: 'e2b',
+            name: summary.metadata?.['name'] ?? summary.name,
+            createdAt: summary.metadata?.['createdAt'] ?? now,
+            joinUrl,
+            lastSeen: now,
+            state: summary.state,
+            trayId,
+            lastJoinUpdatedAt,
+            metadata: summary.metadata,
+        };
+        await deps.registry.append(recovered);
+        reconciled.push(recovered);
+    }
+    // Refresh the timeout of every running cone so active users keep their cones
+    // alive past the 1h default. Failures are non-fatal — a sandbox that
+    // disappears between substrate.list() and extendTimeout() will be discovered
+    // dead on the NEXT list call.
+    const DEFAULT_TTL_MS = 60 * 60 * 1000;
+    await Promise.all(reconciled
+        .filter((c) => c.state === 'running')
+        .map(async (c) => {
+        try {
+            await deps.substrate.extendTimeout(c.sandboxId, DEFAULT_TTL_MS);
+        }
+        catch (err) {
+            // Sandbox may have died between list and extendTimeout; ignore.
+            const msg = err instanceof Error ? err.message : String(err);
+            console.warn('[cloud-core] extendTimeout failed', { sandboxId: c.sandboxId, err: msg });
+        }
+    }));
+    // Apply the metadata filter to the RETURN value only — reconciliation
+    // above ran on all entries to keep zombies from accumulating.
+    return reconciled.filter(matchesFilter);
+}

package/dist/node-server/_cloud_core/src/operations/pause.d.ts

@@ -0,0 +1,15 @@
+import type { Registry } from '../registry.js';
+import type { SandboxSubstrate } from '../substrate.js';
+export interface PauseConeDeps {
+    substrate: SandboxSubstrate;
+    registry: Registry;
+}
+/**
+ * Pause a running cloud cone. Fails if the cone is not found or already paused.
+ * Updates registry state to 'paused' and lastSeen timestamp.
+ *
+ * Note: trayId and lastJoinUpdatedAt are deliberately NOT overwritten during pause,
+ * as they are baseline values for the next resume operation to detect tray rebuilds.
+ */
+export declare function pauseCone(deps: PauseConeDeps, query: string): Promise<void>;
+//# sourceMappingURL=pause.d.ts.map

package/dist/node-server/_cloud_core/src/operations/pause.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pause.d.ts","sourceRoot":"","sources":["../../../src/operations/pause.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExD,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,gBAAgB,CAAC;IAC5B,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAmBjF"}

package/dist/node-server/_cloud_core/src/operations/pause.js

@@ -0,0 +1,27 @@
+import { CloudError } from '../errors.js';
+/**
+ * Pause a running cloud cone. Fails if the cone is not found or already paused.
+ * Updates registry state to 'paused' and lastSeen timestamp.
+ *
+ * Note: trayId and lastJoinUpdatedAt are deliberately NOT overwritten during pause,
+ * as they are baseline values for the next resume operation to detect tray rebuilds.
+ */
+export async function pauseCone(deps, query) {
+    const entry = await deps.registry.findByNameOrId(query);
+    if (!entry)
+        throw new CloudError('NOT_FOUND', `cloud session not found: ${query}`);
+    if (entry.state === 'reserved') {
+        throw new CloudError('ALREADY_RUNNING', `cloud session is being started/resumed: ${query}`);
+    }
+    if (entry.state === 'paused') {
+        throw new CloudError('ALREADY_PAUSED', `cloud session is already paused: ${query}`);
+    }
+    const handle = await deps.substrate.connect(entry.sandboxId);
+    await handle.pause();
+    // Update ONLY state + lastSeen. trayId and lastJoinUpdatedAt are baseline
+    // values for the next resume — preserving them is load-bearing.
+    await deps.registry.update(entry.sandboxId, {
+        state: 'paused',
+        lastSeen: new Date().toISOString(),
+    });
+}

package/dist/node-server/_cloud_core/src/operations/resume.d.ts

@@ -0,0 +1,22 @@
+import type { Registry } from '../registry.js';
+import type { SandboxSubstrate } from '../substrate.js';
+import type { ResumeResult } from '../types.js';
+export interface ResumeConeDeps {
+    substrate: SandboxSubstrate;
+    registry: Registry;
+}
+export interface ResumeConeOpts {
+    query: string;
+    localSliccVersion: string;
+    /** Optional: if provided, written to /slicc/secrets.env AFTER substrate.connect
+     * and BEFORE the leader-restart kick. Both CLI (cloud/resume.ts) and worker
+     * (cloud-sessions-do.ts) pass this unconditionally now to inject a fresh IMS bearer. */
+    refreshSecretsContents?: string;
+    pollIntervalMs?: number;
+    pollTimeoutMs?: number;
+    /** Skip the state check (NOT_FOUND + ALREADY_RUNNING). Used by the worker
+     * after doing atomic cap-check + state-flip under DO lock. */
+    skipStateCheck?: boolean;
+}
+export declare function resumeCone(deps: ResumeConeDeps, opts: ResumeConeOpts): Promise<ResumeResult>;
+//# sourceMappingURL=resume.d.ts.map

package/dist/node-server/_cloud_core/src/operations/resume.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resume.d.ts","sourceRoot":"","sources":["../../../src/operations/resume.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EAAiB,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,gBAAgB,CAAC;IAC5B,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,iBAAiB,EAAE,MAAM,CAAC;IAC1B;;4FAEwF;IACxF,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;kEAC8D;IAC9D,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AASD,wBAAsB,UAAU,CAC9B,IAAI,EAAE,cAAc,EACpB,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,YAAY,CAAC,CA6EvB"}

package/dist/node-server/_cloud_core/src/operations/resume.js

@@ -0,0 +1,86 @@
+import { CloudError } from '../errors.js';
+import { pollForRefreshedStatus } from '../polling.js';
+// curl writes its body to /dev/null and prints the HTTP status code on stdout.
+// We DO want curl to return non-zero on connection errors (so the retry loop
+// can distinguish "node-server not up yet" from "200/503 response received").
+// Therefore: no `|| true`; we parse status from stdout AND check exitCode.
+const KICK_CMD = 'curl -sS -X POST http://localhost:5710/api/leader-restart -o /dev/null -w "%{http_code}"';
+export async function resumeCone(deps, opts) {
+    // skipStateCheck is used by the worker after doing atomic cap-check + state-flip
+    // under DO lock. CLI still wants the NOT_FOUND + ALREADY_RUNNING checks.
+    if (!opts.skipStateCheck) {
+        const entry = await deps.registry.findByNameOrId(opts.query);
+        if (!entry)
+            throw new CloudError('NOT_FOUND', `cloud session not found: ${opts.query}`);
+        // NEW: ALREADY_RUNNING check (additive — existing CLI resume didn't have this).
+        // Accept both 'running' and 'reserved' as "already in flight".
+        if (entry.state === 'running' || entry.state === 'reserved') {
+            throw new CloudError('ALREADY_RUNNING', `cloud session is already running: ${opts.query}`);
+        }
+    }
+    // After state checks, fetch the entry again for baseline data (the worker's
+    // precheck already validated it exists).
+    const entry = await deps.registry.findByNameOrId(opts.query);
+    if (!entry)
+        throw new CloudError('NOT_FOUND', `cloud session not found: ${opts.query}`);
+    // Baseline from the registry — `startCone` stored these at create, and
+    // `pauseCone` preserves them across pause. Resume requires a strictly
+    // newer `updatedAt` than `entry.lastJoinUpdatedAt`, so we only declare
+    // success once the kick has produced a fresh refresh.
+    const baselineUpdatedAt = entry.lastJoinUpdatedAt;
+    const baselineTrayId = entry.trayId;
+    const handle = await deps.substrate.connect(entry.sandboxId);
+    // refreshSecretsContents: both CLI and worker pass this now to inject a fresh
+    // IMS bearer. Write to /slicc/secrets.env BEFORE the kick loop.
+    if (opts.refreshSecretsContents !== undefined) {
+        await handle.writeFile('/slicc/secrets.env', opts.refreshSecretsContents);
+    }
+    // Kick the leader to recover from a possible onReconnectGaveUp state.
+    // 5×1s retry covers the CDP-cold-start race after a long pause.
+    // Success = curl exited 0 AND status is 200. 503 means the SLICC page
+    // target isn't ready yet — retry. Any other status is a hard error.
+    const kicked = await kickLeaderUntilReady(handle);
+    if (!kicked) {
+        throw new CloudError('LEADER_NOT_READY', 'Failed to kick leader after 5 retries (sandbox may not be healthy)');
+    }
+    const refreshed = await pollForRefreshedStatus(handle, baselineUpdatedAt, {
+        timeoutMs: opts.pollTimeoutMs ?? 60_000,
+        intervalMs: opts.pollIntervalMs ?? 500,
+    });
+    // Tray rebuilt iff we had a baseline AND the new trayId is different.
+    // (No baseline → can't tell, default to false so we don't spuriously
+    // warn on a freshly-created sandbox where the registry was wiped.)
+    const trayRebuilt = Boolean(baselineTrayId && refreshed.trayId && baselineTrayId !== refreshed.trayId);
+    const versionMismatch = refreshed.sliccVersion && refreshed.sliccVersion !== opts.localSliccVersion
+        ? { running: refreshed.sliccVersion, local: opts.localSliccVersion }
+        : undefined;
+    // Write the new baseline back — same fields startCone populated.
+    await deps.registry.update(entry.sandboxId, {
+        joinUrl: refreshed.joinUrl,
+        lastSeen: new Date().toISOString(),
+        state: 'running',
+        trayId: refreshed.trayId,
+        lastJoinUpdatedAt: refreshed.updatedAt,
+    });
+    return {
+        sandboxId: entry.sandboxId,
+        joinUrl: refreshed.joinUrl,
+        trayRebuilt,
+        ...(versionMismatch ? { versionMismatch } : {}),
+    };
+}
+async function kickLeaderUntilReady(handle) {
+    for (let i = 0; i < 5; i++) {
+        const result = await handle.run(KICK_CMD);
+        if (result.exitCode === 0) {
+            const status = result.stdout.trim();
+            if (status === '200')
+                return true;
+            if (status !== '503') {
+                throw new CloudError('LEADER_NOT_READY', `/api/leader-restart returned unexpected status ${status}`);
+            }
+        }
+        await new Promise((r) => setTimeout(r, 1000));
+    }
+    return false;
+}

package/dist/node-server/_cloud_core/src/operations/start.d.ts

@@ -0,0 +1,67 @@
+import type { Registry } from '../registry.js';
+import type { SandboxSubstrate } from '../substrate.js';
+import type { ConeEntry, StartResult } from '../types.js';
+export interface StartConeOpts {
+    /** Full secrets.env content (caller reads from disk in CLI; constructs in
+     * worker). Will be filtered with filterSecretsEnv before upload. */
+    envContents: string;
+    /** Tray worker base URL injected into the sandbox env. */
+    workerBaseUrl: string;
+    /** Substrate template ID (default 'slicc'). */
+    template?: string;
+    /** Optional user-supplied name; goes into substrate.metadata.name. */
+    name?: string;
+    /** SLICC version recorded on the registry entry. */
+    sliccVersion: string;
+    /** Additional metadata tagged on the sandbox (e.g., { userId, email } in
+     * worker context). Merged on top of the sandbox metadata. */
+    metadata?: Record<string, string>;
+    /** Extra envs passed at substrate.create. start.sh writes /slicc/secrets.env
+     * from these BEFORE node-server boots (no race). Plan B task. */
+    envs?: Record<string, string>;
+    /** Poll budget for waiting on /tmp/slicc-join.json. */
+    pollTimeoutMs?: number;
+    pollIntervalMs?: number;
+    /** Default true. */
+    autoPauseOnCap?: boolean;
+    /** Optional reservation ID from reserveSlot(); if provided, updates that
+     * placeholder entry instead of appending a new one. */
+    reservationId?: string;
+}
+export interface StartConeDeps {
+    substrate: SandboxSubstrate;
+    registry: Registry;
+}
+export interface ReserveSlotOpts {
+    /** User ID for filtering (worker use) or undefined (CLI use). */
+    userId?: string;
+    /** Optional name; checked for conflicts. */
+    name?: string;
+    /** Metadata to store on the reservation entry. */
+    metadata?: Record<string, string>;
+    /** SLICC version recorded on the registry entry. */
+    sliccVersion: string;
+    /** Environment for cap checking. */
+    env?: {
+        CONE_CAP_RUNNING: string;
+        CONE_CAP_PAUSED: string;
+    };
+    /** Pre-reconciled cone list (from listCones). If provided, skips the slow
+     * reconciliation call inside reserveSlot, making it fast enough to fit under
+     * blockConcurrencyWhile. Worker callers MUST pass this to avoid holding the
+     * DO lock through substrate.list(). */
+    reconciledCones?: ConeEntry[];
+}
+/**
+ * Reserve a slot in the registry atomically under DO lock, BEFORE substrate.create.
+ * Returns a synthetic reservationId (pending-<uuid>) that counts toward the cap.
+ * Throws CloudError('CAP_EXCEEDED' | 'NAME_TAKEN') on conflict.
+ *
+ * Callers MUST wrap this in blockConcurrencyWhile so two concurrent calls
+ * serialize and the second sees the first's placeholder.
+ */
+export declare function reserveSlot(deps: StartConeDeps, opts: ReserveSlotOpts): Promise<{
+    reservationId: string;
+}>;
+export declare function startCone(deps: StartConeDeps, opts: StartConeOpts): Promise<StartResult>;
+//# sourceMappingURL=start.d.ts.map

package/dist/node-server/_cloud_core/src/operations/start.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start.d.ts","sourceRoot":"","sources":["../../../src/operations/start.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EAAE,gBAAgB,EAAiB,MAAM,iBAAiB,CAAC;AACvE,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1D,MAAM,WAAW,aAAa;IAC5B;wEACoE;IACpE,WAAW,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,aAAa,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,YAAY,EAAE,MAAM,CAAC;IACrB;iEAC6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC;qEACiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,uDAAuD;IACvD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oBAAoB;IACpB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;2DACuD;IACvD,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,gBAAgB,CAAC;IAC5B,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,oDAAoD;IACpD,YAAY,EAAE,MAAM,CAAC;IACrB,oCAAoC;IACpC,GAAG,CAAC,EAAE;QACJ,gBAAgB,EAAE,MAAM,CAAC;QACzB,eAAe,EAAE,MAAM,CAAC;KACzB,CAAC;IACF;;;2CAGuC;IACvC,eAAe,CAAC,EAAE,SAAS,EAAE,CAAC;CAC/B;AA6BD;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,aAAa,EACnB,IAAI,EAAE,eAAe,GACpB,OAAO,CAAC;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC,CAwDpC;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,CAAC,CAkJ9F"}