runcloud 0.1.118 → 0.1.120

package/dist/version.js

@@ -1 +1 @@
-export const CLI_VERSION = '0.1.118';
+export const CLI_VERSION = '0.1.120';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runcloud",
-  "version": "0.1.118",
+  "version": "0.1.120",
   "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,58 @@ 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.
+
+Three limits that change what you can conclude from it:
+
+- A destroyed sandbox's console gets removed after 14 days (2 weeks), so a
+  post-mortem has a deadline. A running or paused sandbox's log is never removed,
+  however long it has sat quiet.
+- 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."