runcloud 0.1.117 → 0.1.119

package/dist/diagnose.js

@@ -1,6 +1,6 @@
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { GoogleAuth, Impersonated } from 'google-auth-library';
+import { GoogleAuth } from 'google-auth-library';
 import { renderSessionDiagnosticTerminal, writeSessionDiagnosticBundle, } from './sessionDiagnostics.js';
 const execFileAsync = promisify(execFile);
 const AUTH_ATTEMPT_TIMEOUT_MS = 10_000;
@@ -87,10 +87,8 @@ function extractAuthorization(headers) {
     const h = headers;
     return h?.Authorization ?? h?.authorization;
 }
-async function gcloudIdentityToken(audience, serviceAccount) {
-    const args = ['auth', 'print-identity-token', `--audiences=${audience}`];
-    if (serviceAccount)
-        args.push(`--impersonate-service-account=${serviceAccount}`);
+async function gcloudIdentityToken(audience) {
+    const args = ['auth', 'print-identity-token', '--audiences=' + audience];
     const { stdout } = await execFileAsync('gcloud', args, { timeout: 15_000, maxBuffer: 1024 * 1024 });
     const token = stdout.trim();
     if (!token)
@@ -123,22 +121,32 @@ function exactAudienceAuthorization(authorization, audience) {
     }
     return authorization;
 }
-async function impersonatedIdentityToken(audience, serviceAccount) {
-    return withDeadline('service-account impersonation', async (signal) => {
+async function serviceAccountIdentityToken(audience, serviceAccount) {
+    return withDeadline('service-account ID-token minting', async (signal) => {
         const sourceClient = await new GoogleAuth({
             projectId: AUTH_DISCOVERY_PROJECT_ID,
             scopes: ['https://www.googleapis.com/auth/cloud-platform'],
             clientOptions: { transporterOptions: { signal, timeout: AUTH_ATTEMPT_TIMEOUT_MS } },
         }).getClient();
-        const impersonated = new Impersonated({
-            sourceClient,
-            targetPrincipal: serviceAccount,
-            targetScopes: ['https://www.googleapis.com/auth/cloud-platform'],
-            lifetime: 600,
-            transporterOptions: { signal, timeout: AUTH_ATTEMPT_TIMEOUT_MS },
+        const sourceToken = await sourceClient.getAccessToken();
+        const authorization = typeof sourceToken === 'string' ? sourceToken : sourceToken.token;
+        if (!authorization)
+            throw new Error('ADC returned an empty source access token');
+        const response = await fetch('https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/' +
+            encodeURIComponent(serviceAccount) + ':generateIdToken', {
+            method: "POST",
+            headers: {
+                Authorization: 'Bearer ' + authorization,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ audience, includeEmail: true }),
+            signal,
         });
-        const token = await impersonated.fetchIdToken(audience, { includeEmail: true });
-        return exactAudienceAuthorization(`Bearer ${token}`, audience);
+        const body = await response.json().catch(() => ({}));
+        if (!response.ok || typeof body.token !== 'string') {
+            throw new Error("generateIdToken failed (" + response.status + "): " + JSON.stringify(body.error ?? body));
+        }
+        return exactAudienceAuthorization('Bearer ' + body.token, audience);
     });
 }
 export async function resolveOpsAuthHeader(env = process.env, requestedAudience, requestedServiceAccount) {
@@ -158,13 +166,13 @@ export async function resolveOpsAuthHeader(env = process.env, requestedAudience,
     catch (error) {
         adcError = error instanceof Error ? error.message : String(error);
     }
-    let impersonationError = 'not configured';
+    let serviceAccountError = 'not configured';
     if (serviceAccount && env.DIAGNOSE_DISABLE_IMPERSONATION !== '1') {
         try {
-            return await impersonatedIdentityToken(audience, serviceAccount);
+            return await serviceAccountIdentityToken(audience, serviceAccount);
         }
         catch (error) {
-            impersonationError = error instanceof Error ? error.message : String(error);
+            serviceAccountError = error instanceof Error ? error.message : String(error);
         }
     }
     const token = env.DIAGNOSE_OPS_TOKEN;
@@ -173,13 +181,13 @@ export async function resolveOpsAuthHeader(env = process.env, requestedAudience,
     }
     if (env.DIAGNOSE_DISABLE_GCLOUD !== '1') {
         try {
-            return exactAudienceAuthorization(`Bearer ${await gcloudIdentityToken(audience, serviceAccount)}`, audience);
+            return exactAudienceAuthorization(`Bearer ${await gcloudIdentityToken(audience)}`, audience);
         }
         catch (error) {
             const gcloudError = error instanceof Error ? error.message : String(error);
             throw new Error(`No usable ops credential for audience ${audience}.\n` +
                 `ADC failed: ${truncate(adcError, 500)}\n` +
-                `Service-account impersonation failed: ${truncate(impersonationError, 500)}\n` +
+                `Service-account ID-token minting failed: ${truncate(serviceAccountError, 500)}\n` +
                 `gcloud failed: ${truncate(gcloudError, 500)}\n\n` +
                 'Repair access by adding the Google identity to control-plane `operators`, applying Terraform, ' +
                 'and running `gcloud auth application-default login`, then rerun. ' +
@@ -188,7 +196,7 @@ export async function resolveOpsAuthHeader(env = process.env, requestedAudience,
     }
     throw new Error(`No ops credential available for audience ${audience}. ` +
         `ADC failed: ${truncate(adcError, 300)}. ` +
-        `Service-account impersonation failed: ${truncate(impersonationError, 300)}. ` +
+        `Service-account ID-token minting failed: ${truncate(serviceAccountError, 300)}. ` +
         'Run `gcloud auth application-default login` after the operator Terraform has been applied, or export DIAGNOSE_OPS_TOKEN.');
 }
 function truncate(value, max = 200) {

package/dist/version.js

@@ -1 +1 @@
-export const CLI_VERSION = '0.1.117';
+export const CLI_VERSION = '0.1.119';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runcloud",
-  "version": "0.1.117",
+  "version": "0.1.119",
   "description": "Create and control run.cloud remote mobile simulators and cloud sandboxes",
   "license": "Apache-2.0",
   "keywords": [

package/skills/run-cloud/SKILL.md

@@ -12,11 +12,17 @@ Keep this skill as a router. Do not duplicate operational instructions here.
   iframe embeds, Metro tunnels, mobile assets, and mobile session cleanup.
 - Use `$run-cloud-sandboxes` for microVM sandboxes, command execution, files,
   snapshots, images, SSH, secrets, public ports, desktop automation, resource
-  sizing, and sandbox cleanup.
+  sizing, sandbox cleanup, and investigating a broken sandbox.
 - Use both focused skills when a workflow genuinely combines mobile sessions
   and sandboxes. Follow each skill's authentication, security, metering, and
   cleanup guardrails.
 
+Symptom phrasing ("is down", "stuck", "hung", "not responding", "why did it
+stop") names no resource, so route on the id in hand: a sandbox id or tag goes to
+`$run-cloud-sandboxes`, a session id to `$run-cloud-ios-simulator`. Each says
+what its own signals do and do not mean, which is the part that cannot be
+guessed from the outside.
+
 If the request is ambiguous, infer the product from the resource noun and
 desired outcome. Ask only when choosing the wrong product would materially
 change the work.

package/skills/run-cloud-sandboxes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: run-cloud-sandboxes
-description: Operate run.cloud microVM sandboxes with the CLI or TypeScript SDK. Use for creating isolated compute, running commands, moving files, managing snapshots or images, exposing ports, using SSH or desktop automation, attaching secrets, sizing resources, or cleaning up sandboxes.
+description: Operate and debug run.cloud microVM sandboxes with the CLI or TypeScript SDK. Use for creating isolated compute, running commands, moving files, managing snapshots or images, exposing ports, using SSH or desktop automation, attaching secrets, sizing resources, or cleaning up sandboxes. Also use to investigate a sandbox that is down, stuck, hung, unreachable, or not responding, to find out why one stopped or was destroyed, or to trace a sandbox from a log line by tag.
 ---
 
 # Operate run.cloud Sandboxes
@@ -274,6 +274,55 @@ Key names do not match the env vars, and `sops` needs
 see the Secrets section of the root `CLAUDE.md`/`AGENTS.md` before concluding
 you lack access.
 
+## What the Signals Mean When a Sandbox Misbehaves
+
+`state` describes the microVM lease, not the workload inside it. A sandbox whose
+process died an hour ago still reads `running`, so `running` on its own never
+means healthy.
+
+The console log is one file per sandbox carrying boot output, everything `exec`
+printed, and lifecycle markers, interleaved in the order they happened.
+`runcloud sandbox logs <id>` serves it, and it survives destroy: the host renames
+the file rather than deleting it, so a post-mortem read works on a sandbox that
+no longer exists.
+
+Two limits that change what you can conclude from it:
+
+- It is capped at 10 MiB and trimmed to the newest 5 MiB, so on a chatty workload
+  early output is gone, not merely paged out. An empty-looking start is a trim,
+  not proof the process printed nothing.
+- `systemd-run` output goes to the journal, not the console, so those units never
+  appear here at all. Read `journalctl -u <unit>` inside the sandbox instead.
+
+### Lifecycle markers
+
+The host writes a marker into the console on every transition:
+
+```
+--- sandbox destroyed: timeout-sweep at 2026-08-05T11:02:11Z ---
+```
+
+The events are `created`, `paused`, `resumed`, `stopped`, and `destroyed`. The
+token after the colon is the control plane's actor, written verbatim so it can be
+matched rather than parsed; the sentence around it is not a contract. Only stops
+carry a reason, so `created` and `resumed` appear without one.
+
+| actor | what it means |
+| --- | --- |
+| `timeout-sweep` | hit its `--timeout` lifetime cap. Not a crash |
+| `idle-sweep` | idle-paused after `--idle-pause` seconds. Resumable, and not a failure |
+| `retention-sweep` | destroyed after its 48h parked window expired |
+| `pause` `resume` `stop` `archive` `restore` | a caller requested exactly this |
+| `api` `api-force` | a caller destroyed it. `api-force` bypassed a wedged guest |
+| `health-sweep` `host-reconcile` `reap-sweep` | the platform reclaimed it |
+| `boot-failure` `placement-timeout` `request-timeout` `scheduler` | it never started. Capacity or image, not the workload |
+| `image-built` `image-build-failure` | an async image build finished or failed |
+| `startup-recover` `volume-lease-invalid` `replica-fork-resume-failure` | platform recovery paths |
+
+A sandbox that failed before it ever reached a host has no console, because the
+file is created at boot. Those carry a `Last error` row on
+`runcloud sandbox get` instead, which is then the only record of the cause.
+
 ## Guardrails
 
 - Destroy every sandbox created during a task unless the user explicitly asks

package/skills/run-cloud-sandboxes/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Run Cloud Sandboxes"
-  short_description: "Operate secure remote microVM sandboxes"
-  default_prompt: "Use $run-cloud-sandboxes to create, operate, and clean up run.cloud sandboxes."
+  short_description: "Operate and debug secure remote microVM sandboxes"
+  default_prompt: "Use $run-cloud-sandboxes to create, operate, debug, and clean up run.cloud sandboxes."