@mirinjs/cli 0.1.0-alpha.18 → 0.1.0-alpha.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mirinjs/cli",
-  "version": "0.1.0-alpha.18",
+  "version": "0.1.0-alpha.19",
   "description": "CLI for mirin apps: dev, build, init.",
   "type": "module",
   "license": "MIT",
@@ -27,15 +27,15 @@
     "bun": ">=1.2.0"
   },
   "dependencies": {
-    "create-mirinjs": "0.1.0-alpha.18",
-    "mirinjs": "0.1.0-alpha.18"
+    "create-mirinjs": "0.1.0-alpha.19",
+    "mirinjs": "0.1.0-alpha.19"
   },
   "optionalDependencies": {
-    "@mirinjs/darwin-arm64": "0.1.0-alpha.18",
-    "@mirinjs/win32-x64": "0.1.0-alpha.18",
-    "@mirinjs/win32-arm64": "0.1.0-alpha.18",
-    "@mirinjs/linux-arm64": "0.1.0-alpha.18",
-    "@mirinjs/linux-x64": "0.1.0-alpha.18"
+    "@mirinjs/darwin-arm64": "0.1.0-alpha.19",
+    "@mirinjs/win32-x64": "0.1.0-alpha.19",
+    "@mirinjs/win32-arm64": "0.1.0-alpha.19",
+    "@mirinjs/linux-arm64": "0.1.0-alpha.19",
+    "@mirinjs/linux-x64": "0.1.0-alpha.19"
   },
   "publishConfig": {
     "access": "public"

package/src/artifacts.ts

@@ -25,6 +25,7 @@ import {
 import { homedir, tmpdir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { $ } from "bun";
+import { createReporter, type Reporter } from "./shared/report.ts";
 
 const REPO_SLUG = "Netko-Labs/mirin";
 
@@ -49,15 +50,29 @@ export function isInRepo(): boolean {
   return IN_REPO;
 }
 
-export async function resolveArtifacts(opts: { release: boolean }): Promise<Artifacts> {
+/** The in-repo CEF distribution. `present` checks the framework marker, not just
+ *  the directory: an interrupted `fetch-cef.ts` leaves an empty one behind. */
+export function vendoredCef(): { path: string; present: boolean } {
+  const path = join(REPO_ROOT, "vendor", "cef");
+  return { path, present: existsSync(join(path, cefMarker())) };
+}
+
+export async function resolveArtifacts(opts: {
+  release: boolean;
+  /** Where build chatter goes. Defaults to human mode, which prints it. */
+  reporter?: Reporter;
+}): Promise<Artifacts> {
   assertSupportedPlatform();
-  const cefPath = await ensureCef();
+  const reporter = opts.reporter ?? createReporter(false);
+  const cefPath = await ensureCef(reporter);
 
   if (IN_REPO) {
     const profile = opts.release ? "release" : "debug";
-    console.log(`[mirin] building native core + helpers (${profile})…`);
+    reporter.info(`[mirin] building native core + helpers (${profile})…`);
     const flags = opts.release ? ["--release"] : [];
-    await $`cargo build -p mirin-codec -p mirin-core -p mirin-helper ${flags}`.cwd(REPO_ROOT);
+    await reporter.build(
+      $`cargo build -p mirin-codec -p mirin-core -p mirin-helper ${flags}`.cwd(REPO_ROOT),
+    );
     const target = join(REPO_ROOT, "target", profile);
     return {
       coreDylib: join(target, coreFileName()),
@@ -142,14 +157,14 @@ function cefMarker(): string {
   return "Chromium Embedded Framework.framework";
 }
 
-async function ensureCef(): Promise<string> {
+async function ensureCef(reporter: Reporter): Promise<string> {
   if (IN_REPO) {
-    const vendor = join(REPO_ROOT, "vendor", "cef");
-    if (existsSync(join(vendor, cefMarker()))) return vendor;
+    const vendor = vendoredCef();
+    if (vendor.present) return vendor.path;
     console.error(
       "[mirin] vendor/cef missing — run `bun scripts/fetch-cef.ts` in the monorepo first.",
     );
-    return vendor;
+    return vendor.path;
   }
 
   const version = cliVersion();
@@ -160,7 +175,7 @@ async function ensureCef(): Promise<string> {
   mkdirSync(cacheRoot, { recursive: true });
   const asset = `cef-${platformTag()}.tar.gz`;
   const url = `https://github.com/${REPO_SLUG}/releases/download/v${version}/${asset}`;
-  console.log(`[mirin] downloading CEF for ${platformTag()} (one-time, ~hundreds of MB)…`);
+  reporter.info(`[mirin] downloading CEF for ${platformTag()} (one-time, ~hundreds of MB)…`);
 
   // Download with curl, not `Bun.write(file, await fetch(url))`: the latter
   // pins a core at 100% CPU and never completes on large gzip responses

package/src/build.ts

@@ -251,6 +251,8 @@ export async function build(
       id: bundleId,
       windows: config.windows,
       singleInstance: config.singleInstance,
+      // Lets a diagnostic build opt in via `devtools.production`; otherwise fully off.
+      devtools: config.devtools,
     }),
     versionJson,
     workers: extraWorkers,

package/src/check.ts

@@ -0,0 +1,271 @@
+/**
+ * `mirin check` — boot the app once, capture a screenshot and accessibility
+ * snapshot, collect errors, exit non-zero on failure (docs/agent-devtools.md).
+ */
+
+import type { CheckScenario } from "mirinjs/check";
+import type { DevEvent } from "mirinjs/devtools/session";
+import { readEventsFile, sessionPaths } from "mirinjs/devtools/session";
+import { dev } from "./dev.ts";
+import type { ScenarioOutcome } from "./shared/driver.ts";
+import { InspectorClient } from "./shared/inspector.ts";
+import { createReporter, type Reporter } from "./shared/report.ts";
+import { loadScenario, runScenario } from "./shared/scenario.ts";
+
+/** How long to wait for the app to show a window before giving up. */
+const DEFAULT_TIMEOUT_MS = 45_000;
+
+/** Quiet time after the first window appears, so the capture shows painted UI
+ *  rather than an empty frame. */
+const DEFAULT_SETTLE_MS = 1_000;
+
+export interface CheckOptions {
+  timeoutMs?: number;
+  settleMs?: number;
+  json?: boolean;
+  /** Path to a scenario module (`mirin check --scenario ./check.ts`). */
+  scenario?: string;
+}
+
+export interface CheckReport {
+  ok: boolean;
+  reason?: string;
+  session: string | null;
+  inspector: string | null;
+  windows: { id: number; name?: string; url?: string; title?: string }[];
+  /** Path to the captured screenshot. */
+  screenshot: string | null;
+  /** Accessibility snapshot of the first window. */
+  snapshot: string | null;
+  /** Slices the app published with `devtools.expose`, read at the end of the run. */
+  exposed: Record<string, unknown>;
+  errors: DevEvent[];
+  eventCount: number;
+  durationMs: number;
+  /** Present when `--scenario` ran. */
+  scenario?: { file: string } & ScenarioOutcome;
+}
+
+function record(value: unknown): Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function windowsOf(state: unknown): CheckReport["windows"] {
+  const list = record(state).windows;
+  if (!Array.isArray(list)) return [];
+  return list.flatMap((entry) => {
+    const win = record(entry);
+    const id = win.id;
+    if (typeof id !== "number") return [];
+    return [
+      {
+        id,
+        ...(typeof win.name === "string" ? { name: win.name } : {}),
+        ...(typeof win.url === "string" ? { url: win.url } : {}),
+        ...(typeof win.title === "string" ? { title: win.title } : {}),
+      },
+    ];
+  });
+}
+
+/** Poll `/state` until a window exists, or the deadline passes. */
+async function waitForWindow(
+  client: InspectorClient,
+  deadline: number,
+): Promise<CheckReport["windows"]> {
+  let last: CheckReport["windows"] = [];
+  while (Date.now() < deadline) {
+    try {
+      last = windowsOf(await client.get("/state"));
+      if (last.length > 0) return last;
+    } catch {
+      // The inspector may still be binding; keep trying until the deadline.
+    }
+    await Bun.sleep(250);
+  }
+  return last;
+}
+
+async function capture(client: InspectorClient, report: CheckReport): Promise<void> {
+  try {
+    const shot = record(await client.get("/screenshot"));
+    if (typeof shot.path === "string") report.screenshot = shot.path;
+  } catch (err) {
+    report.errors.push(syntheticError(`screenshot failed: ${message(err)}`));
+  }
+  try {
+    const snap = record(await client.get("/snapshot"));
+    if (typeof snap.snapshot === "string") report.snapshot = snap.snapshot;
+  } catch (err) {
+    report.errors.push(syntheticError(`snapshot failed: ${message(err)}`));
+  }
+  try {
+    report.exposed = record(record(await client.get("/state")).exposed);
+  } catch {
+    // The app publishing nothing is the common case; not worth an error.
+  }
+}
+
+function message(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/** A failure of the check itself, shaped like a stream event so one list suffices. */
+function syntheticError(text: string): DevEvent {
+  return { seq: 0, ts: Date.now(), src: "main", level: "error", type: "check.error", msg: text };
+}
+
+function renderReport(report: CheckReport): void {
+  const mark = report.ok ? "✓" : "✗";
+  console.log(`\n${mark} mirin check ${report.ok ? "passed" : "failed"} in ${report.durationMs}ms`);
+  if (report.reason !== undefined) console.log(`  reason: ${report.reason}`);
+
+  if (report.windows.length > 0) {
+    console.log(`  windows: ${report.windows.length}`);
+    for (const win of report.windows) {
+      const label = [win.name, win.title].filter(Boolean).join(" / ");
+      console.log(
+        `    #${win.id}${label.length > 0 ? ` ${label}` : ""} ${win.url ?? ""}`.trimEnd(),
+      );
+    }
+  }
+  if (report.scenario !== undefined) {
+    const { file, steps, screenshots, failure } = report.scenario;
+    console.log(`  scenario: ${file}`);
+    for (const step of steps) {
+      const mark = step.ok ? "✓" : "✗";
+      console.log(`    ${mark} ${step.name}${step.ms >= 0 ? ` (${step.ms}ms)` : ""}`);
+    }
+    if (failure !== undefined) console.log(`    → ${failure.message}`);
+    for (const shot of screenshots) console.log(`    shot: ${shot}`);
+  }
+  const exposedKeys = Object.keys(report.exposed);
+  if (exposedKeys.length > 0) {
+    console.log(`  app state: ${JSON.stringify(report.exposed).slice(0, 400)}`);
+  }
+  if (report.screenshot !== null) console.log(`  screenshot: ${report.screenshot}`);
+  if (report.session !== null) console.log(`  session: ${report.session}`);
+  console.log(`  events: ${report.eventCount}, errors: ${report.errors.length}`);
+
+  for (const error of report.errors.slice(0, 10)) {
+    console.log(`\n  [${error.src}] ${error.type}: ${error.msg}`);
+    const stack = record(error.data).stack;
+    if (Array.isArray(stack)) {
+      for (const frame of stack.slice(0, 4)) console.log(`      at ${String(frame)}`);
+    }
+  }
+  if (report.errors.length > 10) {
+    console.log(`\n  … ${report.errors.length - 10} more errors (see the session's events.jsonl)`);
+  }
+  if (report.snapshot !== null) {
+    console.log(`\n  ui snapshot:\n${report.snapshot.replace(/^/gm, "    ")}`);
+  }
+}
+
+/** Run the check. Returns the process exit code: 0 when the app came up clean. */
+export async function check(
+  projectDir = process.cwd(),
+  options: CheckOptions = {},
+): Promise<number> {
+  const reporter: Reporter = createReporter(options.json === true);
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const settleMs = options.settleMs ?? DEFAULT_SETTLE_MS;
+  const startedAt = Date.now();
+
+  const report: CheckReport = {
+    ok: false,
+    session: null,
+    inspector: null,
+    windows: [],
+    screenshot: null,
+    snapshot: null,
+    exposed: {},
+    errors: [],
+    eventCount: 0,
+    durationMs: 0,
+  };
+
+  reporter.event("start", { projectDir, timeoutMs });
+
+  // Load the scenario before anything is built: a typo in the path should cost a
+  // second, not a cold compile.
+  let scenario: CheckScenario | undefined;
+  if (options.scenario !== undefined) {
+    try {
+      scenario = await loadScenario(projectDir, options.scenario);
+    } catch (err) {
+      report.reason = message(err);
+      report.durationMs = Date.now() - startedAt;
+      reporter.finish({ ...report }, () => renderReport(report));
+      return 1;
+    }
+  }
+
+  await dev(projectDir, {
+    // Inherit the output mode: in JSON mode `mirin dev`'s prose would otherwise
+    // interleave with the report and break parsing.
+    json: options.json === true,
+    async onLaunched(context) {
+      const deadline = Date.now() + timeoutMs;
+      const session = context.session;
+      if (session === undefined) {
+        report.reason = "no dev session was created — devtools artifacts are unavailable";
+        return;
+      }
+      report.session = session.paths.dir;
+
+      reporter.event("await-inspector");
+      const endpoint = await session.waitForInspector(Math.max(1_000, deadline - Date.now()));
+      if (endpoint === undefined) {
+        report.reason = "the app never published an inspector endpoint";
+        return;
+      }
+      report.inspector = `http://127.0.0.1:${endpoint.port}`;
+      const client = new InspectorClient(endpoint);
+
+      reporter.event("await-window");
+      report.windows = await waitForWindow(client, deadline);
+      if (report.windows.length === 0) {
+        report.reason = `no window appeared within ${timeoutMs}ms`;
+        return;
+      }
+
+      // Let the first paint land, or the capture shows an empty frame and tree.
+      await Bun.sleep(settleMs);
+
+      if (scenario !== undefined && options.scenario !== undefined) {
+        reporter.event("scenario", { file: options.scenario });
+        const outcome = await runScenario(client, scenario, (name) =>
+          reporter.event("step", { name }),
+        );
+        report.scenario = { file: options.scenario, ...outcome };
+        if (outcome.failure !== undefined) {
+          report.reason = `scenario failed at "${outcome.failure.step}": ${outcome.failure.message}`;
+        }
+      }
+
+      // Capture after the scenario, so artifacts show the state the run ended in.
+      reporter.event("capture", { windows: report.windows.length });
+      await capture(client, report);
+    },
+  });
+
+  // Read the stream from disk rather than the inspector: by now the app has exited,
+  // and the file is the complete record of the run.
+  if (report.session !== null) {
+    const events = readEventsFile(sessionPaths(report.session).events);
+    report.eventCount = events.length;
+    report.errors.push(...events.filter((event) => event.level === "error"));
+  }
+
+  report.durationMs = Date.now() - startedAt;
+  report.ok = report.reason === undefined && report.errors.length === 0;
+  if (!report.ok && report.reason === undefined) {
+    report.reason = `${report.errors.length} error-level event(s) during startup`;
+  }
+
+  reporter.finish({ ...report }, () => renderReport(report));
+  return report.ok ? 0 : 1;
+}

package/src/dev.ts

@@ -6,6 +6,9 @@
  * 3. assemble + ad-hoc-sign the dev .app
  * 4. start the Vite dev server (rolldown-vite) for the UI
  * 5. launch the app pointed at the Vite URL, with RPC injected into the webview
+ *
+ * Each run also opens a dev session under `.mirin/dev/` and records its phase
+ * timeline there (docs/agent-devtools.md).
  */
 
 import { existsSync, mkdirSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
@@ -27,13 +30,37 @@ const IS_WINDOWS = process.platform === "win32";
 const IS_LINUX = process.platform === "linux";
 
 import { compileWorkers, normalizeSidecars } from "./extras.ts";
+import { createReporter } from "./shared/report.ts";
+import { DevSession } from "./shared/session.ts";
 import { sweepBuildTemps } from "./temps.ts";
 
 /** Vite's default port. `mirin dev` probes upward from here for a free one, so a
  *  second dev session (or anything already on 5173) doesn't collide. */
 const DEV_PORT_BASE = 5173;
 
-export async function dev(projectDir = process.cwd()): Promise<number> {
+/** Where the CEF DevTools-protocol port search starts. Well clear of Vite's range
+ *  so concurrent dev sessions of different apps don't fight over either. */
+const CDP_PORT_BASE = 9222;
+
+export interface DevLaunchContext {
+  session?: DevSession;
+  devUrl: string;
+  cdpPort: number;
+  pid: number;
+  /** Stop the app and the Vite server. */
+  stop(): void;
+}
+
+export interface DevOptions {
+  /** Emit newline-delimited JSON progress instead of prose. */
+  json?: boolean;
+  /** Called once the app is running. The app is always stopped after the hook
+   *  settles, whether it threw or not. */
+  onLaunched?(context: DevLaunchContext): Promise<void> | void;
+}
+
+export async function dev(projectDir = process.cwd(), options?: DevOptions): Promise<number> {
+  const reporter = createReporter(options?.json === true);
   const work = join(projectDir, ".mirin");
   mkdirSync(work, { recursive: true });
   // `bun build --compile` drops temp *.bun-build files in the cwd; clear any left
@@ -51,25 +78,40 @@ export async function dev(projectDir = process.cwd()): Promise<number> {
   // bundling; the file is read from the project at window-create time.
   const linuxIconPng = IS_LINUX && iconSrc ? resolveLinuxIconPng(iconSrc) : undefined;
 
+  // --- open the dev session (agent devtools) ---
+  const session = DevSession.create({
+    projectDir,
+    appName,
+    appId: bundleId,
+    version: typeof config.version === "string" ? config.version : undefined,
+  });
+
   // --- native artifacts ---
-  const artifacts = await resolveArtifacts({ release: false });
+  const artifacts = await resolveArtifacts({ release: false, reporter });
 
   // --- compile the Bun host + bundle the Worker ---
-  console.log("[mirin dev] compiling host + bundling main process…");
+  const compilePhase = session?.phase("compile");
+  reporter.info("[mirin dev] compiling host + bundling main process…");
+  reporter.event("compile");
   // `bun build --compile` emits an `.exe` on Windows; name it so explicitly.
   const hostExe = join(work, IS_WINDOWS ? "host.exe" : "host");
   const workerJs = join(work, "worker.js");
   const hostTarget =
     process.platform === "win32" && process.arch === "arm64" ? ["--target=bun-windows-x64"] : [];
-  await $`bun build --compile ${hostTarget} ${artifacts.hostEntry} --outfile ${hostExe}`.cwd(
-    projectDir,
+  await reporter.build(
+    $`bun build --compile ${hostTarget} ${artifacts.hostEntry} --outfile ${hostExe}`.cwd(
+      projectDir,
+    ),
+  );
+  await reporter.build(
+    $`bun build ${mainEntry} --target=bun --outfile ${workerJs}`.cwd(projectDir),
   );
-  await $`bun build ${mainEntry} --target=bun --outfile ${workerJs}`.cwd(projectDir);
+  compilePhase?.ok();
 
   // Extra assets (dev): compile workers into .mirin/workers and symlink sidecar
   // binaries into .mirin/sidecars (no copy/sign in dev — they run unsigned locally).
   const workersDir = join(work, "workers");
-  await compileWorkers(projectDir, config.workers, workersDir, false);
+  await compileWorkers(projectDir, config.workers, workersDir, false, reporter);
   const sidecarsDir = join(work, "sidecars");
   mkdirSync(sidecarsDir, { recursive: true });
   for (const sc of normalizeSidecars(projectDir, config.sidecars)) {
@@ -80,7 +122,9 @@ export async function dev(projectDir = process.cwd()): Promise<number> {
   }
 
   // --- assemble the dev bundle (Windows/Linux app folder, or macOS .app) ---
-  console.log("[mirin dev] assembling dev bundle…");
+  const bundlePhase = session?.phase("bundle");
+  reporter.info("[mirin dev] assembling dev bundle…");
+  reporter.event("bundle");
   const { app, exe } = IS_WINDOWS
     ? await buildWindowsBundle({
         appName,
@@ -112,6 +156,7 @@ export async function dev(projectDir = process.cwd()): Promise<number> {
           icon: iconSrc,
           urlSchemes: config.urlSchemes,
         });
+  bundlePhase?.ok();
 
   // Linux: install a dev `.desktop` entry so cosmic's dock can resolve the app's
   // icon. cosmic matches a running X11 window's `WM_CLASS` (which the core sets to
@@ -140,8 +185,12 @@ export async function dev(projectDir = process.cwd()): Promise<number> {
   // both sides to 127.0.0.1 avoids the family mismatch (and matches the loopback
   // RPC server). `--host 127.0.0.1` forces Vite's bind.
   const port = await findFreePort(DEV_PORT_BASE);
+  const cdpPort = await findFreePort(CDP_PORT_BASE);
   const devUrl = `http://127.0.0.1:${port}`;
-  console.log(`[mirin dev] starting Vite dev server on ${devUrl}…`);
+  const vitePhase = session?.phase("vite");
+  session?.setDevUrl(devUrl);
+  reporter.info(`[mirin dev] starting Vite dev server on ${devUrl}…`);
+  reporter.event("vite", { devUrl });
   const vite = Bun.spawn(
     [
       "bunx",
@@ -156,13 +205,21 @@ export async function dev(projectDir = process.cwd()): Promise<number> {
     ],
     {
       cwd: projectDir,
-      stdio: ["ignore", "inherit", "inherit"],
+      stdio: reporter.childStdio,
     },
   );
-  await waitForUrl(devUrl, 15_000);
+  try {
+    await waitForUrl(devUrl, 15_000);
+    vitePhase?.ok(devUrl);
+  } catch (err) {
+    vitePhase?.fail(err instanceof Error ? err.message : String(err));
+    vite.kill();
+    throw err;
+  }
 
   // --- launch the app ---
-  console.log(`[mirin dev] launching ${appName}…`);
+  const launchPhase = session?.phase("launch");
+  reporter.info(`[mirin dev] launching ${appName}…`);
   const appProc = Bun.spawn([exe], {
     cwd: projectDir,
     env: {
@@ -183,7 +240,11 @@ export async function dev(projectDir = process.cwd()): Promise<number> {
         : {}),
       MIRIN_WORKER: workerJs,
       MIRIN_DEV_URL: devUrl,
-      MIRIN_MANIFEST_JSON: JSON.stringify({ id: bundleId, windows: config.windows }),
+      MIRIN_MANIFEST_JSON: JSON.stringify({
+        id: bundleId,
+        windows: config.windows,
+        devtools: config.devtools,
+      }),
       // dev: true → enables inspect-element AND gives this run its own `-dev`
       // CEF cache dir, so `mirin dev` can run alongside the installed app.
       // `icon_path` (Linux) → the window's `_NET_WM_ICON` (cosmic dock/taskbar).
@@ -193,9 +254,33 @@ export async function dev(projectDir = process.cwd()): Promise<number> {
       }),
       MIRIN_SIDECAR_DIR: sidecarsDir,
       MIRIN_WORKERS_DIR: workersDir,
+      // CEF's DevTools-protocol port (screenshots, snapshots, eval, input).
+      // Loopback only, and only ever set for a dev run (docs/agent-devtools.md).
+      MIRIN_CDP_PORT: String(cdpPort),
+      ...(session?.env() ?? {}),
     },
-    stdio: ["ignore", "inherit", "inherit"],
+    stdio: reporter.childStdio,
   });
+  session?.setPid(appProc.pid);
+  launchPhase?.ok();
+  reporter.event("launch", {
+    pid: appProc.pid,
+    devUrl,
+    cdpPort,
+    session: session?.paths.dir ?? null,
+  });
+  if (session) {
+    reporter.info(`[mirin dev] dev session: ${session.paths.dir}`);
+    // The app publishes its inspector endpoint once the Worker binds it; report it
+    // when it lands, without holding up the dev loop if it never does.
+    void session.waitForInspector().then((endpoint) => {
+      if (endpoint === undefined) return;
+      reporter.info(
+        `[mirin dev] inspector: http://127.0.0.1:${endpoint.port} — token in inspector.json`,
+      );
+      reporter.event("inspector", { url: `http://127.0.0.1:${endpoint.port}` });
+    });
+  }
 
   const cleanup = () => {
     vite.kill();
@@ -204,8 +289,26 @@ export async function dev(projectDir = process.cwd()): Promise<number> {
   process.on("SIGINT", cleanup);
   process.on("SIGTERM", cleanup);
 
+  if (options?.onLaunched !== undefined) {
+    try {
+      await options.onLaunched({
+        ...(session !== undefined ? { session } : {}),
+        devUrl,
+        cdpPort,
+        pid: appProc.pid,
+        stop: cleanup,
+      });
+    } catch (err) {
+      console.error(`[mirin] launch hook failed: ${err instanceof Error ? err.message : err}`);
+    } finally {
+      // A hooked run is a one-shot: stop the app whether the hook succeeded or not.
+      cleanup();
+    }
+  }
+
   const code = await appProc.exited;
   vite.kill();
+  session?.finish(code, appProc.signalCode ?? undefined);
   return code;
 }