@irtio/cli 0.5.0 → 0.5.2

package/dist/{rollback-CLQVYFHW.js → rollback-GA6UY772.js}

@@ -1,17 +1,34 @@
 import {
-  createApiClient,
-  isLoginRequired
-} from "./chunk-I37DLT7K.js";
+  readProjectConfig
+} from "./chunk-32QTPKVT.js";
 import {
+  HelpRequested,
+  createApiClient,
+  helpFor,
+  helpRequested,
+  isLoginRequired,
   resolveControlUrlForUser
-} from "./chunk-NVUKSP5U.js";
+} from "./chunk-TV66QHFP.js";
 
 // src/rollback.ts
-import { existsSync } from "fs";
-import { readFile } from "fs/promises";
-import * as path from "path";
+import "fs";
+import "fs/promises";
+import "path";
 import pc from "picocolors";
+var USAGE = `usage: irtio rollback <version> [options]
+
+Re-promotes deployment <version> and brings rooms that migrated past it back to their
+pre-migration state. This DISCARDS whatever those rooms wrote since their migration.
+
+options:
+  <version>          the deployment version to go back to
+  --project <id>     project id (default: the project file)
+  -c, --config <f>   the project file to read (default irtio.json)
+  --url <control>    control plane (default: your stored login)
+  -h, --help         print this
+`;
 function parseRollbackArgs(args) {
+  if (helpRequested(args)) throw helpFor(USAGE);
   const parsed = {};
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -22,6 +39,14 @@ function parseRollbackArgs(args) {
         parsed.project = value;
         break;
       }
+      case "-c":
+      case "--config": {
+        const value = args[++i];
+        if (value === void 0 || value === "")
+          throw new Error("irtio rollback: --config needs a value");
+        parsed.config = value;
+        break;
+      }
       case "--url": {
         const value = args[++i];
         if (value === void 0) throw new Error("irtio rollback: --url needs a value");
@@ -75,23 +100,13 @@ async function runRollback(options) {
   }
   return result;
 }
-async function readIrtioJsonProject(cwd) {
-  const file = path.join(cwd, "irtio.json");
-  if (!existsSync(file)) return void 0;
-  let parsed;
-  try {
-    parsed = JSON.parse(await readFile(file, "utf8"));
-  } catch {
-    throw new Error(`irtio rollback: ${file} is not valid JSON`);
-  }
-  return typeof parsed.project === "string" && parsed.project.length > 0 ? parsed.project : void 0;
-}
 async function rollback(args, deps = {}) {
   const log = deps.log ?? ((line) => console.log(line));
   const errorLog = deps.errorLog ?? ((line) => console.error(line));
   try {
     const parsed = parseRollbackArgs(args);
-    const project = parsed.project ?? await readIrtioJsonProject(process.cwd());
+    const config = await readProjectConfig(process.cwd(), "irtio rollback", parsed.config);
+    const project = parsed.project ?? config.project;
     if (project === void 0) {
       throw new Error(
         "irtio rollback: no project id \u2014 pass --project or run this from a project with irtio.json"
@@ -105,6 +120,10 @@ async function rollback(args, deps = {}) {
       ...deps.client !== void 0 ? { client: deps.client } : {}
     });
   } catch (err) {
+    if (err instanceof HelpRequested) {
+      log(err.usage);
+      return;
+    }
     if (isLoginRequired(err)) {
       errorLog(pc.red("not logged in"));
       errorLog("run: irtio login");
@@ -116,6 +135,7 @@ async function rollback(args, deps = {}) {
   }
 }
 export {
+  USAGE,
   parseRollbackArgs,
   rollback,
   runRollback

package/dist/{rooms-OJ3JLYHD.js → rooms-B66LQIIF.js}

@@ -1,17 +1,41 @@
 import {
-  createApiClient,
-  isLoginRequired
-} from "./chunk-I37DLT7K.js";
+  readProjectConfig
+} from "./chunk-32QTPKVT.js";
 import {
+  HelpRequested,
+  createApiClient,
+  helpFor,
+  helpRequested,
+  isLoginRequired,
   resolveControlUrlForUser
-} from "./chunk-NVUKSP5U.js";
+} from "./chunk-TV66QHFP.js";
 
 // src/rooms.ts
-import { existsSync } from "fs";
-import { readFile } from "fs/promises";
-import * as path from "path";
+import "fs";
+import "fs/promises";
+import "path";
 import pc from "picocolors";
+var USAGE = `usage: irtio rooms [options]
+       irtio rooms saves <room> [options]
+       irtio rooms restore <room> --save <id> [options]
+
+Lists a project's rooms. Rows not reported for longer than the control plane's retention window
+(30 days by default) are pruned.
+
+subcommands:
+  saves <room>              list a room's save generations, newest first
+  restore <room> --save <id>
+                            bring a room back from a save. This DISCARDS its current state, and
+                            stops the tenant if it is live
+
+options:
+  --project <id>     project id (default: the project file)
+  -c, --config <f>   the project file to read (default irtio.json)
+  --url <control>    control plane (default: your stored login)
+  -h, --help         print this
+`;
 function parseRoomsArgs(args) {
+  if (helpRequested(args)) throw helpFor(USAGE);
   const parsed = { sub: "list" };
   let rest = args;
   const first = args[0];
@@ -39,6 +63,14 @@ function parseRoomsArgs(args) {
         parsed.project = value;
         break;
       }
+      case "-c":
+      case "--config": {
+        const value = args[++i];
+        if (value === void 0 || value === "")
+          throw new Error("irtio rooms: --config needs a value");
+        parsed.config = value;
+        break;
+      }
       case "--url": {
         const value = rest[++i];
         if (value === void 0) throw new Error("irtio rooms: --url needs a value");
@@ -140,23 +172,13 @@ async function runRooms(options) {
   for (const line of formatTable(rows)) log(line);
   return rows;
 }
-async function readIrtioJsonProject(cwd) {
-  const file = path.join(cwd, "irtio.json");
-  if (!existsSync(file)) return void 0;
-  let parsed;
-  try {
-    parsed = JSON.parse(await readFile(file, "utf8"));
-  } catch {
-    throw new Error(`irtio rooms: ${file} is not valid JSON`);
-  }
-  return typeof parsed.project === "string" && parsed.project.length > 0 ? parsed.project : void 0;
-}
 async function rooms(args, deps = {}) {
   const log = deps.log ?? ((line) => console.log(line));
   const errorLog = deps.errorLog ?? ((line) => console.error(line));
   try {
     const parsed = parseRoomsArgs(args);
-    const project = parsed.project ?? await readIrtioJsonProject(process.cwd());
+    const config = await readProjectConfig(process.cwd(), "irtio rooms", parsed.config);
+    const project = parsed.project ?? config.project;
     if (project === void 0) {
       throw new Error(
         "irtio rooms: no project id \u2014 pass --project or run this from a project with irtio.json"
@@ -180,6 +202,10 @@ async function rooms(args, deps = {}) {
       await runRooms(common);
     }
   } catch (err) {
+    if (err instanceof HelpRequested) {
+      log(err.usage);
+      return;
+    }
     if (isLoginRequired(err)) {
       errorLog(pc.red("not logged in"));
       errorLog("run: irtio login");
@@ -191,6 +217,7 @@ async function rooms(args, deps = {}) {
   }
 }
 export {
+  USAGE,
   parseRoomsArgs,
   rooms,
   runRestore,

package/dist/simulate.d.ts

@@ -1,4 +1,4 @@
-import { SimulationReport } from '@irtio/bots';
+import { RunEnd, SimulationReport, TickHealthReading } from '@irtio/bots';
 import { AnySchema } from '@irtio/schema';
 
 /**
@@ -26,7 +26,9 @@ interface SimulateArgs {
     mispredictionMax?: number;
     snapsMax?: number;
     correctionsMax?: number;
+    overrunsMax?: number;
 }
+declare const USAGE = "usage: irtio simulate [options]\n\nDrives N real clients at a running room and checks the built-in invariants. Run it from a project\ndirectory so it can load irtio/schema.ts; without one it falls back to a relay run.\n\noptions:\n  --bots <n>                  how many clients to spawn (default 5)\n  --seconds <n>               how long to play for (default 10)\n  --room <code>               join this room instead of creating one\n  --url <ws://...>            where to connect (default ws://localhost:7070)\n  --key <projectKey>          the project key to present\n  --trace <path>              write the frame trace here\n  --cheat                     send illegal writes and expect corrections\n  --misprediction-max <units> fail if one correction snaps a prediction further than this\n  --snaps-max <n>             fail above this many cap-exceeded reconciliations\n  --corrections-max <perSec>  fail above this correction rate per bot\n  --overruns-max <n>          fail above this many server tick overruns in the run window\n                              (default 0; the count is read from the server, and the run says\n                              so when it could not be read)\n  -h, --help                  print this\n\nexit codes: 0 every invariant held, 1 something was measured and failed, 2 the run could not be\nperformed (nobody joined, or it passed its wall-clock ceiling).\n";
 /** Hand-rolled, like `parseDevArgs`: the CLI has no argument-parsing dependency. */
 declare function parseSimulateArgs(args: readonly string[]): SimulateArgs;
 interface LoadSchemaOptions {
@@ -70,6 +72,41 @@ declare function loadProjectWorld(options: LoadSchemaOptions): Promise<LoadedWor
  * description, or `undefined` when the worlds agree.
  */
 declare function checkWorldDeterminism(world: LoadedWorld): Promise<string | undefined>;
+/**
+ * The dev server's JSON view, which is where a local run reads the server's own tick counters.
+ * `irtio dev` serves it on the socket's own port; nothing else does, and that is deliberate — a
+ * deployed tenant's counters belong to the control plane, not to whoever can reach the socket.
+ */
+declare function stateUrlFor(wsUrl: string): string | undefined;
+interface RoomTickCounters {
+    readonly overruns?: number;
+    readonly maxTickMs?: number;
+}
+/**
+ * Reads one room's tick counters off the dev server, or explains why it could not. Every failure
+ * path returns a sentence rather than a zero: the `tick-health` invariant has an `unavailable`
+ * state precisely so that "the room dropped no ticks" and "nobody asked the room" stay different
+ * answers.
+ */
+declare function readTickCounters(wsUrl: string, roomId: string): Promise<{
+    counters?: RoomTickCounters;
+    unavailable?: string;
+    source?: string;
+}>;
+/**
+ * The run-window reading: overruns are a lifetime counter on the server, so the window is the
+ * difference between a baseline taken as the bots came up and a reading taken as they went down.
+ * `maxTickMs` has no windowed form (it is a running maximum) and is reported as what it is.
+ */
+declare function tickHealthFrom(before: {
+    counters?: RoomTickCounters;
+    unavailable?: string;
+    source?: string;
+}, after: {
+    counters?: RoomTickCounters;
+    unavailable?: string;
+    source?: string;
+}): TickHealthReading;
 interface RunSimulationOptions extends Partial<SimulateArgs> {
     /** Project root; defaults to `process.cwd()`. */
     readonly cwd?: string;
@@ -80,9 +117,35 @@ interface RunSimulationOptions extends Partial<SimulateArgs> {
      * hardware can burst past the cursor-tuned default without anything being wrong.
      */
     readonly correctionsPerSecMax?: number;
+    /** D36: initial-join bound, passed through to `spawnBots`. */
+    readonly joinTimeoutMs?: number;
+    /** D36: room-gone grace, passed through to `spawnBots`. */
+    readonly roomGoneGraceMs?: number;
+    /**
+     * D36: the hard wall-clock ceiling on the whole run. Default `seconds × 3 + 30 s`. Reaching it
+     * is a fatal run condition, not a clean end.
+     */
+    readonly ceilingMs?: number;
     /** @internal Test seam, same as `startDev`'s. */
     readonly irtioPackages?: Record<string, string> | undefined;
 }
+/** D36's wall-clock ceiling: generous enough that no healthy run meets it. */
+declare function ceilingFor(seconds: number): number;
+/**
+ * D36: the run could not be performed at all — nobody joined, so there is no report to print and
+ * nothing was measured. `irtio simulate` turns this into exit code 2, which is the whole point of
+ * having a third code: "clean" and "violation" are both claims about a room, and this is not one.
+ */
+declare class RunNotPerformedError extends Error {
+    readonly cause?: unknown | undefined;
+    readonly name = "RunNotPerformedError";
+    constructor(message: string, cause?: unknown | undefined);
+}
+/**
+ * D36: what ended the run. `scripts`/`duration` are the ordinary ends; `room-gone` and `ceiling`
+ * are the two fatal run conditions, and both still print the report and write the trace.
+ */
+type SimulationEnd = RunEnd | 'ceiling';
 interface SimulationRun {
     readonly report: SimulationReport;
     readonly tracePath: string;
@@ -93,6 +156,12 @@ interface SimulationRun {
     /** Result of the build-twice world-builder check: the failure text, or `undefined` if it held
      *  (or did not apply). A failure also fails the run. */
     readonly worldError?: string;
+    /** D36: what ended the run. */
+    readonly endedBy: SimulationEnd;
+    /** D36: the fatal run condition in one sentence, when one ended the run. */
+    readonly fatal?: string;
+    /** D36: `0` clean, `1` a violation was measured, `2` the run was not performed as asked. */
+    readonly exitCode: 0 | 1 | 2;
     /** Everything that was printed, in order — the same lines `log` received. */
     readonly output: readonly string[];
 }
@@ -100,4 +169,4 @@ interface SimulationRun {
 declare function runSimulation(options?: RunSimulationOptions): Promise<SimulationRun>;
 declare function simulate(args: readonly string[]): Promise<void>;
 
-export { type LoadSchemaOptions, type RunSimulationOptions, type SimulateArgs, type SimulationRun, checkWorldDeterminism, loadProjectSchema, loadProjectWorld, parseSimulateArgs, runSimulation, simulate };
+export { type LoadSchemaOptions, RunNotPerformedError, type RunSimulationOptions, type SimulateArgs, type SimulationEnd, type SimulationRun, USAGE, ceilingFor, checkWorldDeterminism, loadProjectSchema, loadProjectWorld, parseSimulateArgs, readTickCounters, runSimulation, simulate, stateUrlFor, tickHealthFrom };

package/dist/simulate.js

@@ -1,3 +1,10 @@
+import {
+  HelpRequested,
+  helpFor,
+  helpRequested,
+  trailerFor
+} from "./chunk-TV66QHFP.js";
+
 // src/simulate.ts
 import { existsSync } from "fs";
 import { mkdir } from "fs/promises";
@@ -25,7 +32,32 @@ function nonNegativeInt(raw, flag) {
   }
   return value;
 }
+var USAGE = `usage: irtio simulate [options]
+
+Drives N real clients at a running room and checks the built-in invariants. Run it from a project
+directory so it can load irtio/schema.ts; without one it falls back to a relay run.
+
+options:
+  --bots <n>                  how many clients to spawn (default ${DEFAULT_BOTS})
+  --seconds <n>               how long to play for (default ${DEFAULT_SECONDS})
+  --room <code>               join this room instead of creating one
+  --url <ws://...>            where to connect (default ${DEFAULT_URL})
+  --key <projectKey>          the project key to present
+  --trace <path>              write the frame trace here
+  --cheat                     send illegal writes and expect corrections
+  --misprediction-max <units> fail if one correction snaps a prediction further than this
+  --snaps-max <n>             fail above this many cap-exceeded reconciliations
+  --corrections-max <perSec>  fail above this correction rate per bot
+  --overruns-max <n>          fail above this many server tick overruns in the run window
+                              (default 0; the count is read from the server, and the run says
+                              so when it could not be read)
+  -h, --help                  print this
+
+exit codes: 0 every invariant held, 1 something was measured and failed, 2 the run could not be
+performed (nobody joined, or it passed its wall-clock ceiling).
+`;
 function parseSimulateArgs(args) {
+  if (helpRequested(args)) throw helpFor(USAGE);
   const parsed = { bots: DEFAULT_BOTS, seconds: DEFAULT_SECONDS, cheat: false };
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -72,6 +104,9 @@ function parseSimulateArgs(args) {
       case "--corrections-max":
         parsed.correctionsMax = positive(value(), "--corrections-max");
         break;
+      case "--overruns-max":
+        parsed.overrunsMax = nonNegativeInt(value(), "--overruns-max");
+        break;
       default:
         throw new Error(`irtio simulate: unknown option ${JSON.stringify(arg)}`);
     }
@@ -178,13 +213,91 @@ function everyByteEqual(a, b) {
   for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
   return true;
 }
+var TICK_HEALTH_TIMEOUT_MS = 2e3;
+function stateUrlFor(wsUrl) {
+  let parsed;
+  try {
+    parsed = new URL(wsUrl);
+  } catch {
+    return void 0;
+  }
+  if (parsed.protocol === "ws:") parsed.protocol = "http:";
+  else if (parsed.protocol === "wss:") parsed.protocol = "https:";
+  else if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return void 0;
+  parsed.pathname = "/__irt/state.json";
+  parsed.search = "";
+  return parsed.toString();
+}
+async function readTickCounters(wsUrl, roomId) {
+  const stateUrl = stateUrlFor(wsUrl);
+  if (stateUrl === void 0) {
+    return { unavailable: `cannot derive an inspector URL from ${wsUrl}` };
+  }
+  let body;
+  try {
+    const response = await fetch(stateUrl, {
+      signal: AbortSignal.timeout(TICK_HEALTH_TIMEOUT_MS)
+    });
+    if (!response.ok) {
+      return {
+        unavailable: `${stateUrl} answered ${response.status}, so the server's tick counters were not read` + (response.status === 404 ? ". Only `irtio dev` serves the inspector; a deployed tenant reports ticks through `irtio rooms` instead." : "")
+      };
+    }
+    body = await response.json();
+  } catch (err) {
+    return {
+      unavailable: `could not reach ${stateUrl} (${err instanceof Error ? err.message : String(err)})`
+    };
+  }
+  const rooms = body?.rooms;
+  const room = Array.isArray(rooms) ? rooms.find((r) => r?.id === roomId) : void 0;
+  if (room === void 0) return { unavailable: `${stateUrl} did not report room ${roomId}` };
+  const overruns = room.metrics?.overruns;
+  if (typeof overruns !== "number") {
+    return {
+      unavailable: `${stateUrl} reported room ${roomId} without tick counters (no live worker)`,
+      source: stateUrl
+    };
+  }
+  return {
+    counters: {
+      overruns,
+      ...typeof room.metrics?.maxTickMs === "number" ? { maxTickMs: room.metrics.maxTickMs } : {}
+    },
+    source: stateUrl
+  };
+}
+function tickHealthFrom(before, after) {
+  if (after.unavailable !== void 0 || after.counters?.overruns === void 0) {
+    return { unavailable: after.unavailable ?? "no overrun count came back from the server" };
+  }
+  const baseline = before.counters?.overruns ?? 0;
+  const overruns = Math.max(0, after.counters.overruns - baseline);
+  return {
+    overruns,
+    ...after.counters.maxTickMs !== void 0 ? { maxTickMs: after.counters.maxTickMs } : {},
+    ...after.source !== void 0 ? { source: after.source } : {}
+  };
+}
+var STOP_GRACE_MS = 5e3;
+function ceilingFor(seconds) {
+  return seconds * 3e3 + 3e4;
+}
+var RunNotPerformedError = class extends Error {
+  constructor(message, cause) {
+    super(message);
+    this.cause = cause;
+  }
+  cause;
+  name = "RunNotPerformedError";
+};
 function rate(bytesPerSecond) {
   return bytesPerSecond >= 1e3 ? `${(bytesPerSecond / 1e3).toFixed(1)} kB/s` : `${Math.round(bytesPerSecond)} B/s`;
 }
 function formatReport(report, schemaLoaded, cheating) {
   const lines = [];
   for (const invariant of report.invariants) {
-    const mark = invariant.ok ? pc.green("ok  ") : pc.red("FAIL");
+    const mark = invariant.state === "unavailable" ? pc.yellow("n/a ") : invariant.ok ? pc.green("ok  ") : pc.red("FAIL");
     lines.push(`  ${mark} ${invariant.name.padEnd(17)} ${pc.dim(invariant.detail)}`);
   }
   lines.push("");
@@ -199,8 +312,13 @@ function formatReport(report, schemaLoaded, cheating) {
   if (report.tracePath !== void 0) lines.push(pc.dim(`  trace: ${report.tracePath}`));
   lines.push("");
   const failed = report.invariants.filter((i) => !i.ok);
+  const unread = report.invariants.filter((i) => i.state === "unavailable");
   if (failed.length === 0) {
-    lines.push(pc.green(`  every invariant held across ${report.bots} bots.`));
+    lines.push(
+      pc.green(
+        `  every invariant held across ${report.bots} bots` + (unread.length === 0 ? "." : `, except ${unread.map((i) => i.name).join(", ")}, which could not be read.`)
+      )
+    );
   } else {
     lines.push(
       pc.red(`  ${failed.length} invariant(s) failed: ${failed.map((i) => i.name).join(", ")}`)
@@ -253,30 +371,67 @@ async function runSimulation(options = {}) {
     ...options.room !== void 0 ? { room: options.room } : {},
     ...options.correctionsPerSecMax !== void 0 ? { correctionsPerSecMax: options.correctionsPerSecMax } : options.correctionsMax !== void 0 ? { correctionsPerSecMax: options.correctionsMax } : {},
     ...options.mispredictionMax !== void 0 ? { mispredictionMagnitudeMax: options.mispredictionMax } : {},
-    ...options.snapsMax !== void 0 ? { snapsMax: options.snapsMax } : {}
+    ...options.snapsMax !== void 0 ? { snapsMax: options.snapsMax } : {},
+    ...options.overrunsMax !== void 0 ? { overrunsMax: options.overrunsMax } : {}
   };
   const predicted = world !== void 0 && worldError === void 0;
-  const runner = loaded ? await spawnBots(bots, {
+  const spawn = {
     ...common,
-    schema: loaded.schema,
-    script: randomScript(loaded.schema, { cheat: options.cheat ?? false }),
-    ...predicted ? {
-      physics: {
-        gravity: world.gravity,
-        ...world.timestep !== void 0 ? { timestep: world.timestep } : {},
-        ...world.setup !== void 0 ? { setup: world.setup } : {},
-        ...world.bodies !== void 0 ? { bodies: world.bodies } : {},
-        ...world.intents !== void 0 ? { intents: world.intents } : {}
-      }
-    } : {}
-  }) : await spawnBots(bots, { ...common, script: relayEchoScript() });
+    ...options.joinTimeoutMs !== void 0 ? { joinTimeoutMs: options.joinTimeoutMs } : {},
+    ...options.roomGoneGraceMs !== void 0 ? { roomGoneGraceMs: options.roomGoneGraceMs } : {}
+  };
+  let runner;
+  try {
+    runner = loaded ? await spawnBots(bots, {
+      ...spawn,
+      schema: loaded.schema,
+      script: randomScript(loaded.schema, { cheat: options.cheat ?? false }),
+      ...predicted ? {
+        physics: {
+          gravity: world.gravity,
+          ...world.timestep !== void 0 ? { timestep: world.timestep } : {},
+          ...world.setup !== void 0 ? { setup: world.setup } : {},
+          ...world.bodies !== void 0 ? { bodies: world.bodies } : {},
+          ...world.intents !== void 0 ? { intents: world.intents } : {}
+        }
+      } : {}
+    }) : await spawnBots(bots, { ...spawn, script: relayEchoScript() });
+  } catch (err) {
+    throw new RunNotPerformedError(
+      `irtio simulate: no bot ever joined ${url}, so nothing was measured.
+  ` + (err instanceof Error ? err.message : String(err)),
+      err
+    );
+  }
   log("");
   log(
     `${pc.bold("irtio simulate")} \u2014 ${bots} bot${bots === 1 ? "" : "s"} \xD7 ${seconds}s on ${url} (room ${pc.bold(runner.roomId)})${options.cheat ? pc.yellow(" [cheat]") : ""}`
   );
   log("");
-  await runner.done();
-  const stopped = await runner.stop();
+  const tickBefore = await readTickCounters(url, runner.roomId);
+  const ceilingMs = options.ceilingMs ?? ceilingFor(seconds);
+  let ceilingHit = false;
+  const ceiling = new Promise((resolve2) => {
+    const timer = setTimeout(() => {
+      ceilingHit = true;
+      resolve2();
+    }, ceilingMs);
+    void runner.done().catch(() => void 0).finally(() => {
+      clearTimeout(timer);
+      resolve2();
+    });
+  });
+  await ceiling;
+  runner.recordTickHealth(tickHealthFrom(tickBefore, await readTickCounters(url, runner.roomId)));
+  const stopped = await Promise.race([
+    runner.stop(),
+    new Promise((resolve2) => {
+      const timer = setTimeout(() => resolve2(runner.report()), STOP_GRACE_MS);
+      timer.unref?.();
+    })
+  ]);
+  const endedBy = ceilingHit ? "ceiling" : runner.endedBy ?? "scripts";
+  const fatal = endedBy === "ceiling" ? `the run passed its wall-clock ceiling of ${Math.round(ceilingMs / 1e3)}s without ending on its own, so it was cut short here` : endedBy === "room-gone" ? "every bot was disconnected at once and none rejoined, so the room is gone" : void 0;
   await mkdir(outDir, { recursive: true });
   const tracePath = path.resolve(
     cwd,
@@ -307,12 +462,17 @@ async function runSimulation(options = {}) {
   for (const failure of runner.scriptErrors) {
     log(pc.red(`  bot ${failure.bot} script failed: ${String(failure.error)}`));
   }
+  if (fatal !== void 0) log(pc.red(`  run ended early: ${fatal}`));
+  const exitCode = endedBy === "ceiling" ? 2 : !report.ok || worldError !== void 0 || runner.scriptErrors.length > 0 ? 1 : 0;
   return {
     report,
     tracePath,
     schema: loaded !== void 0,
     predicted,
     ...worldError !== void 0 ? { worldError } : {},
+    endedBy,
+    ...fatal !== void 0 ? { fatal } : {},
+    exitCode,
     output
   };
 }
@@ -321,24 +481,38 @@ async function simulate(args) {
   try {
     parsed = parseSimulateArgs(args);
   } catch (err) {
+    if (err instanceof HelpRequested) {
+      console.log(err.usage);
+      return;
+    }
     console.error(pc.red(err instanceof Error ? err.message : String(err)));
     process.exitCode = 1;
     return;
   }
   try {
     const run = await runSimulation(parsed);
-    if (!run.report.ok || run.worldError !== void 0) process.exitCode = 1;
+    if (run.exitCode !== 0) process.exitCode = run.exitCode;
   } catch (err) {
     console.error(pc.red(err instanceof Error ? err.message : String(err)));
-    console.error(pc.dim("is `irtio dev` running? pass --url to point somewhere else."));
-    process.exitCode = 1;
+    const localDefault = parsed.url === void 0 || parsed.url === DEFAULT_URL;
+    const trailer = trailerFor(err, [
+      ...err instanceof RunNotPerformedError && localDefault ? [`nothing is answering ${DEFAULT_URL}. Start the room with \`irtio dev\`, or pass --url.`] : []
+    ]);
+    if (trailer !== void 0) console.error(pc.dim(trailer));
+    process.exitCode = err instanceof RunNotPerformedError ? 2 : 1;
   }
 }
 export {
+  RunNotPerformedError,
+  USAGE,
+  ceilingFor,
   checkWorldDeterminism,
   loadProjectSchema,
   loadProjectWorld,
   parseSimulateArgs,
+  readTickCounters,
   runSimulation,
-  simulate
+  simulate,
+  stateUrlFor,
+  tickHealthFrom
 };

package/dist/static-deploy-5TBH4VNA.js

@@ -0,0 +1,17 @@
+import {
+  USAGE,
+  parseStaticDeployArgs,
+  runStaticDeploy,
+  staticDeploy,
+  walkStaticDir
+} from "./chunk-GBNHBWES.js";
+import "./chunk-BPE452KF.js";
+import "./chunk-32QTPKVT.js";
+import "./chunk-TV66QHFP.js";
+export {
+  USAGE,
+  parseStaticDeployArgs,
+  runStaticDeploy,
+  staticDeploy,
+  walkStaticDir
+};