ronin-skillforce 0.1.0 → 0.2.0-beta.0

package/bin/commands/studio-state.js

@@ -0,0 +1,159 @@
+/**
+ * Background state for `skillforce studio` (RON-297): the `studio.json` snapshot that `--status`
+ * and `--stop` read, plus the two probes they need (pid liveness, one-shot health check).
+ *
+ * Nothing here writes during a read path: `writeState` is only called by a running server, and
+ * `readState`/`probeStudioHealth` never create a file or a token.
+ */
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { dirname, join } from 'path';
+
+export const STATE_FILE = 'studio.json';
+export const LOG_FILE = 'studio.log';
+
+/**
+ * Resolve `${PROFESSOR_HOME:-~/.professor}` without consulting the real home when one is supplied.
+ * @param {{ env?: Record<string,string|undefined>, home?: string }} [opts]
+ * @returns {string}
+ */
+export function professorHome({ env = process.env, home } = {}) {
+  return home || env.PROFESSOR_HOME || join(homedir(), '.professor');
+}
+
+/**
+ * Absolute path of the background state file.
+ * @param {{ env?: Record<string,string|undefined>, home?: string }} [opts]
+ * @returns {string}
+ */
+export function stateFilePath({ env = process.env, home } = {}) {
+  return join(professorHome({ env, home }), STATE_FILE);
+}
+
+/**
+ * Absolute path of the background log file used by the LaunchAgent.
+ * @param {{ env?: Record<string,string|undefined>, home?: string }} [opts]
+ * @returns {string}
+ */
+export function logFilePath({ env = process.env, home } = {}) {
+  return join(professorHome({ env, home }), 'logs', LOG_FILE);
+}
+
+/** True for the payload Studio's `/api/studio/health` returns; anything else is a foreign app. */
+export function isStudioHealthPayload(body) {
+  return Boolean(body) && body.ok === true && typeof body.version === 'string';
+}
+
+/** A recorded state is usable only with a numeric pid; anything else is treated as absent. */
+function isStateShape(value) {
+  return Boolean(value) && typeof value === 'object' && Number.isInteger(value.pid);
+}
+
+/**
+ * Write the state file atomically (temp file + rename, mode `0600`).
+ * @param {{ pid: number, port: number, apiPort: number, studioUrl: string, apiUrl: string,
+ *           startedAt: string }} state
+ * @param {{ env?: Record<string,string|undefined>, home?: string }} [opts]
+ * @returns {string} the file path
+ */
+export function writeState(state, { env = process.env, home } = {}) {
+  const file = stateFilePath({ env, home });
+  mkdirSync(dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  try {
+    writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+    renameSync(tmp, file);
+  } catch (err) {
+    try {
+      rmSync(tmp, { force: true });
+    } catch {
+      /* ignore */
+    }
+    throw err;
+  }
+  return file;
+}
+
+/**
+ * Read the state file. A missing, malformed or truncated file reads as `null`.
+ * @param {{ env?: Record<string,string|undefined>, home?: string }} [opts]
+ * @returns {{ pid: number, port: number, apiPort: number, studioUrl: string, apiUrl: string,
+ *             startedAt: string } | null}
+ */
+export function readState({ env = process.env, home } = {}) {
+  try {
+    const parsed = JSON.parse(readFileSync(stateFilePath({ env, home }), 'utf-8'));
+    return isStateShape(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Remove the state file; missing is not an error.
+ * @param {{ env?: Record<string,string|undefined>, home?: string }} [opts]
+ * @returns {boolean} true when a file was removed
+ */
+export function removeState({ env = process.env, home } = {}) {
+  try {
+    rmSync(stateFilePath({ env, home }), { force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * True when the pid exists. `EPERM` counts as alive: the process exists but is not ours.
+ * @param {number} pid
+ * @param {{ kill?: (pid: number, signal?: number) => void }} [opts]
+ * @returns {boolean}
+ */
+export function isPidAlive(pid, { kill = process.kill } = {}) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err?.code === 'EPERM';
+  }
+}
+
+/**
+ * A timeout signal when the runtime has one; `undefined` keeps the probe working on older Nodes.
+ */
+function abortTimeout(ms) {
+  try {
+    return typeof AbortSignal?.timeout === 'function' ? AbortSignal.timeout(ms) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * One `GET /api/studio/health` against the loopback bridge. Any answer that is not a Studio health
+ * payload (404, foreign JSON, timeout, refused connection) is `false`; it never throws.
+ *
+ * @param {{ apiUrl: string, token?: string|null, fetchImpl?: typeof fetch,
+ *           timeoutMs?: number }} opts
+ * @returns {Promise<boolean>}
+ */
+export async function probeStudioHealth({
+  apiUrl,
+  token,
+  fetchImpl = globalThis.fetch,
+  timeoutMs = 1500,
+} = {}) {
+  const headers = token ? { 'X-Studio-Token': token } : {};
+  try {
+    const res = await fetchImpl(`${apiUrl}/api/studio/health`, {
+      headers,
+      signal: abortTimeout(timeoutMs),
+    });
+    if (!res || !res.ok) return false;
+    const body = await res.json().catch(() => null);
+    return isStudioHealthPayload(body);
+  } catch {
+    return false;
+  }
+}

package/bin/commands/studio.js

@@ -5,21 +5,43 @@
  *   2. starts the local server (`web/server.js`, production, on `--api-port`) with a pairing token
  *   3. serves `studio/dist` on `--port` (tiny static server, loopback only)
  *   4. waits for `/api/studio/health`, then opens
- *      `http://localhost:<port>/#token=…` (plus `&bridge=…` for a non-default API port)
+ *      `http://127.0.0.1:<port>/#token=…` (plus `&bridge=…` for a non-default API port)
  *      (unless `--no-open`)
  *
+ * Every URL this command polls or prints uses `127.0.0.1`, matching the server bind: `localhost`
+ * resolves to `::1` first on macOS, where another app may already be listening.
+ *
  * Inherited `CLAUDECODE` / `CLAUDE_CODE_*` env vars are stripped from the child so a nested agent
  * CLI (spawned by the bridge) behaves like a normal terminal.
  */
-import { spawn, execSync } from 'child_process';
+import { spawn, execSync, execFileSync } from 'child_process';
 import { createServer } from 'http';
+import { createServer as createNetServer } from 'net';
 import { existsSync, statSync, readdirSync } from 'fs';
 import { dirname, join } from 'path';
+import { homedir } from 'os';
 import { fileURLToPath } from 'url';
 import { createRequire } from 'module';
 import { createStaticHandler } from '../static-server.js';
 import { requireStudioNode } from '../node-version.js';
 import * as security from '../../web/security.js';
+import {
+  isStudioHealthPayload,
+  removeState,
+  writeState,
+} from './studio-state.js';
+import {
+  LABEL,
+  UNSUPPORTED_PLATFORM,
+  collectStatus,
+  disableAutostart,
+  displayPath,
+  enableAutostart,
+  formatStatus,
+  stopStudio,
+} from './studio-autostart.js';
+
+export { isStudioHealthPayload };
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 export const REPO_ROOT = join(__dirname, '..', '..');
@@ -28,6 +50,19 @@ export const DEFAULT_PORT = 5180;
 export const DEFAULT_API_PORT = 3000;
 export const HEALTH_PATH = '/api/studio/health';
 
+/** Hosts probed for a busy port: the `127.0.0.1` bind plus the IPv6 loopback `localhost` may use. */
+export const LOOPBACK_HOSTS = ['127.0.0.1', '::1'];
+
+/** Base URL the CLI polls and prints — the IPv4 literal, never `localhost`. */
+export function loopbackUrl(port) {
+  return `http://127.0.0.1:${port}`;
+}
+
+/** Rewrite an `http://localhost…` URL to the IPv4 loopback literal. */
+export function toLoopbackUrl(url) {
+  return String(url).replace(/^http:\/\/localhost(?=[:/]|$)/, 'http://127.0.0.1');
+}
+
 /**
  * Usage text for `studio --help`. Kept as a plain string so the CLI can print it without starting
  * or binding anything.
@@ -41,6 +76,11 @@ Options:
   --port <n>        Studio port (default ${DEFAULT_PORT})
   --api-port <n>    Local bridge server port (default ${DEFAULT_API_PORT})
   --no-open         Do not open the browser
+  --strict-port     Fail instead of picking another port when one is busy
+  --autostart on    Start Studio at login (macOS, global install only)
+  --autostart off   Remove the login item and stop starting Studio at login
+  --status          Show whether Studio is running, its URLs, autostart and log path
+  --stop            Stop the running Studio (never another app's process)
   --rotate-token    Generate a new pairing token and exit
   -h, --help        Show this help and exit
 `.trim();
@@ -52,9 +92,17 @@ export function wantsHelp(args = []) {
 
 
 /**
- * Parse `--port`, `--api-port`, `--no-open` (both `--flag value` and `--flag=value` forms).
+ * Parse `--port`, `--api-port`, `--no-open`, `--strict-port`, `--status`, `--stop` and
+ * `--autostart on|off` (both `--flag value` and `--flag=value` forms).
+ * `portExplicit` / `apiPortExplicit` say whether the value came from a valid flag, which decides
+ * whether a busy port is an error or an auto-pick.
+ * `autostart` is `'on'`, `'off'` or `'invalid'` when the flag was given without a usable value;
+ * `null` means the flag was not used.
+ *
  * @param {string[]} [args]
- * @returns {{ port: number, apiPort: number, open: boolean, rotateToken: boolean }}
+ * @returns {{ port: number, apiPort: number, portExplicit: boolean, apiPortExplicit: boolean,
+ *             open: boolean, rotateToken: boolean, strictPort: boolean, status: boolean,
+ *             stop: boolean, autostart: 'on'|'off'|'invalid'|null }}
  */
 export function parseStudioArgs(args = []) {
   const valueOf = (name, fallback) => {
@@ -64,15 +112,32 @@ export function parseStudioArgs(args = []) {
     if (i !== -1 && args[i + 1] && !args[i + 1].startsWith('--')) return args[i + 1];
     return fallback;
   };
-  const asPort = (raw, fallback) => {
-    const n = Number.parseInt(raw, 10);
-    return Number.isInteger(n) && n > 0 && n < 65536 ? n : fallback;
+  const readPort = (name, fallback) => {
+    const raw = valueOf(name, null);
+    const parsed = Number.parseInt(raw, 10);
+    const valid = Number.isInteger(parsed) && parsed > 0 && parsed < 65536;
+    return { value: valid ? parsed : fallback, explicit: raw !== null && valid };
   };
+  const port = readPort('--port', DEFAULT_PORT);
+  const apiPort = readPort('--api-port', DEFAULT_API_PORT);
+  const wantsAutostart = args.some((a) => a === '--autostart' || a.startsWith('--autostart='));
+  const autostartValue = valueOf('--autostart', null);
+  const autostart = wantsAutostart
+    ? autostartValue === 'on' || autostartValue === 'off'
+      ? autostartValue
+      : 'invalid'
+    : null;
   return {
-    port: asPort(valueOf('--port', String(DEFAULT_PORT)), DEFAULT_PORT),
-    apiPort: asPort(valueOf('--api-port', String(DEFAULT_API_PORT)), DEFAULT_API_PORT),
+    port: port.value,
+    apiPort: apiPort.value,
+    portExplicit: port.explicit,
+    apiPortExplicit: apiPort.explicit,
     open: !args.includes('--no-open'),
     rotateToken: args.includes('--rotate-token'),
+    strictPort: args.includes('--strict-port'),
+    status: args.includes('--status'),
+    stop: args.includes('--stop'),
+    autostart,
   };
 }
 
@@ -171,8 +236,8 @@ export function mergeOrigins(existing, port) {
  * @returns {{ apiUrl: string, studioUrl: string, pairingUrl: string }}
  */
 export function buildPairingUrl({ studioPort, apiPort, token }) {
-  const apiUrl = `http://localhost:${apiPort}`;
-  const studioUrl = `http://localhost:${studioPort}`;
+  const apiUrl = loopbackUrl(apiPort);
+  const studioUrl = loopbackUrl(studioPort);
   let pairingUrl = `${studioUrl}/#token=${encodeURIComponent(token)}`;
   if (Number(apiPort) !== DEFAULT_API_PORT) {
     pairingUrl += `&bridge=${encodeURIComponent(apiUrl)}`;
@@ -180,6 +245,87 @@ export function buildPairingUrl({ studioPort, apiPort, token }) {
   return { apiUrl, studioUrl, pairingUrl };
 }
 
+/** `true` when `port` is busy on that family, `false` when free or the family is unavailable. */
+function probeBind(port, host) {
+  return new Promise((resolve) => {
+    const server = createNetServer();
+    server.once('error', (err) => resolve(err?.code === 'EADDRINUSE'));
+    server.listen({ port, host, exclusive: true }, () => {
+      server.close(() => resolve(false));
+    });
+  });
+}
+
+/**
+ * True when something already listens on `port` on any loopback family. An IPv4-only listener
+ * leaves `::1:<port>` free and vice versa, so both families have to be probed.
+ *
+ * @param {number|string} port
+ * @param {{ hosts?: string[], probe?: (port: number, host: string) => Promise<boolean> }} [opts]
+ * @returns {Promise<boolean>}
+ */
+export async function isPortBusy(port, { hosts = LOOPBACK_HOSTS, probe = probeBind } = {}) {
+  const states = await Promise.all(hosts.map((host) => probe(Number(port), host)));
+  return states.some(Boolean);
+}
+
+/**
+ * First port at or above `from` that is free on every loopback family.
+ *
+ * @param {number} from
+ * @param {{ hosts?: string[], maxTries?: number,
+ *           isBusy?: (port: number, opts?: object) => Promise<boolean> }} [opts]
+ * @returns {Promise<number>}
+ */
+export async function findFreePort(
+  from,
+  { hosts = LOOPBACK_HOSTS, maxTries = 25, isBusy = isPortBusy } = {}
+) {
+  const start = Number(from);
+  for (let port = start; port < start + maxTries && port < 65536; port += 1) {
+    if (!(await isBusy(port, { hosts }))) return port;
+  }
+  throw new Error(`No free loopback port between ${start} and ${start + maxTries - 1}.`);
+}
+
+/**
+ * Keep both ports usable before anything binds: a busy default port moves to the next free one,
+ * while a busy port the user pinned with a flag is a hard error. `strict` removes the auto-pick
+ * entirely, so a LaunchAgent start never changes the URL it was paired on.
+ *
+ * @param {{ port: number, apiPort: number, portExplicit?: boolean, apiPortExplicit?: boolean,
+ *           strict?: boolean,
+ *           isBusy?: (port: number) => Promise<boolean>,
+ *           findFree?: (from: number) => Promise<number> }} opts
+ * @returns {Promise<{ port: number, apiPort: number, notices: string[] }>}
+ */
+export async function resolveStudioPorts({
+  port,
+  apiPort,
+  portExplicit = false,
+  apiPortExplicit = false,
+  strict = false,
+  isBusy = (value) => isPortBusy(value),
+  findFree = (from) => findFreePort(from),
+} = {}) {
+  const notices = [];
+  const pick = async (value, explicit, flag, label) => {
+    if (!(await isBusy(value))) return value;
+    if (explicit || strict) {
+      throw new Error(
+        `Port ${value} is already in use on loopback (127.0.0.1 or ::1). ` +
+          `Choose another port: --${flag} <free port>.`
+      );
+    }
+    const next = await findFree(value + 1);
+    notices.push(`Port ${value} is in use; using ${next} for ${label} instead.`);
+    return next;
+  };
+  const resolvedApiPort = await pick(apiPort, apiPortExplicit, 'api-port', 'the local server');
+  const resolvedPort = await pick(port, portExplicit, 'port', 'Studio');
+  return { port: resolvedPort, apiPort: resolvedApiPort, notices };
+}
+
 /**
  * Resolve the pairing token through the shared helper (D-01/D-02). `repoRoot` is still accepted for
  * tests but only supplies the one-time legacy `web/.studio-token` migration path; the token itself
@@ -198,6 +344,7 @@ export function resolveStudioToken({ repoRoot = REPO_ROOT, env = process.env, ho
 
 /**
  * Poll `/api/studio/health` until it answers 200 with the pairing token.
+ * A 404 or a JSON body that is not a Studio health payload means another app owns the port.
  * @param {{ url: string, token: string, timeoutMs?: number, intervalMs?: number, fetchImpl?: typeof fetch }} opts
  */
 export async function waitForHealth({
@@ -209,17 +356,36 @@ export async function waitForHealth({
 }) {
   const deadline = Date.now() + timeoutMs;
   let lastError = 'no response';
+  let foreign = false;
   while (Date.now() < deadline) {
     try {
       const res = await fetchImpl(url, { headers: { 'X-Studio-Token': token } });
-      if (res.ok) return await res.json().catch(() => ({ ok: true }));
-      lastError = `HTTP ${res.status}`;
+      if (res.ok) {
+        const body = await res.json().catch(() => null);
+        if (isStudioHealthPayload(body)) return body;
+        foreign = true;
+        lastError = 'an answer that is not Studio';
+      } else {
+        if (res.status === 404) foreign = true;
+        lastError = `HTTP ${res.status}`;
+      }
     } catch (err) {
       lastError = err.message;
     }
     await new Promise((r) => setTimeout(r, intervalMs));
   }
-  throw new Error(`Studio server did not become healthy at ${url} (${lastError})`);
+  const port = (() => {
+    try {
+      return new URL(url).port;
+    } catch {
+      return '';
+    }
+  })();
+  const hint =
+    foreign && port
+      ? ` Another app is answering on port ${port}; start Studio with --api-port <free port>.`
+      : '';
+  throw new Error(`Studio server did not become healthy at ${url} (${lastError}).${hint}`);
 }
 
 /**
@@ -259,7 +425,7 @@ export async function createStudioStaticServer({
   return {
     server,
     port: actualPort,
-    url: `http://localhost:${actualPort}`,
+    url: loopbackUrl(actualPort),
     close: () => new Promise((done) => server.close(() => done())),
   };
 }
@@ -337,10 +503,131 @@ function ensureBuild({ studioDir, spinner }) {
   }
 }
 
+/**
+ * `--autostart on|off`, `--status` and `--stop`. None of them starts the Studio server, so they run
+ * before the Node 22.5 gate and never import `ora`.
+ *
+ * @param {{ parsed: object, ctx?: object, style?: Function, repoRoot: string }} opts
+ * @returns {Promise<number>} process exit code
+ */
+async function runBackground({ parsed, ctx = {}, style, repoRoot }) {
+  const {
+    env = process.env,
+    userHome,
+    platform = process.platform,
+    exec = execFileSync,
+    kill = process.kill,
+    fetchImpl = globalThis.fetch,
+  } = ctx;
+  const log = (line) => console.log(line);
+  const fail = (line) => console.error(style('error', line));
+  const show = (file) => displayPath(file, { home: userHome || homedir() });
+
+  if (parsed.autostart === 'invalid') {
+    fail('--autostart needs a value: on or off.');
+    return 1;
+  }
+  if (parsed.autostart && (parsed.status || parsed.stop)) {
+    fail('Use --autostart, --status or --stop one at a time.');
+    return 1;
+  }
+  if (parsed.autostart && platform !== 'darwin') {
+    fail(UNSUPPORTED_PLATFORM);
+    return 1;
+  }
+
+  if (parsed.autostart === 'on') {
+    try {
+      const ports = await resolveStudioPorts({
+        port: parsed.port,
+        apiPort: parsed.apiPort,
+        portExplicit: parsed.portExplicit,
+        apiPortExplicit: parsed.apiPortExplicit,
+        strict: true,
+        isBusy: ctx.isPortBusy,
+        findFree: ctx.findFreePort,
+      });
+      const { logPath } = enableAutostart({
+        port: ports.port,
+        apiPort: ports.apiPort,
+        cliPath: join(repoRoot, 'bin', 'cli.js'),
+        execPath: ctx.execPath,
+        env,
+        userHome,
+        platform,
+        exec,
+        uid: ctx.uid,
+      });
+      log(style('success', `Studio will start at login (${LABEL}).`));
+      log(`  Studio URL:  ${loopbackUrl(ports.port)}`);
+      log(`  Log:         ${show(logPath)}`);
+      return 0;
+    } catch (err) {
+      fail(err.message);
+      return 1;
+    }
+  }
+
+  if (parsed.autostart === 'off') {
+    try {
+      const { plistPath, removed } = disableAutostart({ userHome, platform, exec, uid: ctx.uid });
+      log(
+        removed
+          ? `Studio will no longer start at login (removed ${show(plistPath)}).`
+          : 'Studio auto-start was already off.'
+      );
+      return 0;
+    } catch (err) {
+      fail(err.message);
+      return 1;
+    }
+  }
+
+  if (parsed.status) {
+    const report = await collectStatus({ env, userHome, kill, fetchImpl });
+    const pairingUrl =
+      report.token && report.state?.port && report.state?.apiPort
+        ? buildPairingUrl({
+            studioPort: report.state.port,
+            apiPort: report.state.apiPort,
+            token: report.token,
+          }).pairingUrl
+        : null;
+    log(formatStatus({ ...report, pairingUrl, userHome: userHome || homedir() }));
+    return report.status === 'running' ? 0 : 1;
+  }
+
+  if (parsed.stop) {
+    const result = await stopStudio({ env, userHome, platform, exec, uid: ctx.uid, kill });
+    if (result.refused) {
+      fail(`Refusing to stop pid ${result.pid}: it is not a Studio process.`);
+      return 1;
+    }
+    if (result.stopped) {
+      log(
+        result.via === 'launchctl'
+          ? 'Stopped Studio (launchd agent).'
+          : `Stopped Studio (pid ${result.pid}).`
+      );
+      return 0;
+    }
+    if (result.reason === 'stale') {
+      log(`Studio is not running (removed a stale studio.json for pid ${result.pid}).`);
+    } else {
+      log('Studio is not running.');
+    }
+    return 0;
+  }
+
+  return 1;
+}
+
 /**
  * @param {{ args?: string[], cwd?: string, chalk?: object, style?: Function, repoRoot?: string,
  *           ora?: Function, spawnImpl?: typeof spawn, fetchImpl?: typeof fetch,
- *           openImpl?: typeof openBrowser, nodeVersion?: string }} [ctx]
+ *           openImpl?: typeof openBrowser, nodeVersion?: string,
+ *           isPortBusy?: (port: number) => Promise<boolean>,
+ *           findFreePort?: (from: number) => Promise<number> }} [ctx]
  */
 export async function run(ctx = {}) {
   const {
@@ -358,10 +645,16 @@ export async function run(ctx = {}) {
     return 0;
   }
 
+  const parsed = parseStudioArgs(args);
+  if (parsed.autostart || parsed.status || parsed.stop) {
+    return runBackground({ parsed, ctx, style, repoRoot });
+  }
+
   requireStudioNode(ctx.nodeVersion);
 
   const ora = ctx.ora || (await import('ora')).default;
-  const { port, apiPort, open, rotateToken } = parseStudioArgs(args);
+  const { open, rotateToken } = parsed;
+  let { port, apiPort } = parsed;
 
   const hasStartRequest = args.some((arg) => arg !== '--rotate-token');
   let rotatedToken = null;
@@ -394,6 +687,30 @@ export async function run(ctx = {}) {
     throw new Error(`Local server not found at ${serverEntry}. Is the package installed fully?`);
   }
 
+  const portOptions = {
+    port,
+    apiPort,
+    portExplicit: parsed.portExplicit,
+    apiPortExplicit: parsed.apiPortExplicit,
+    strict: parsed.strictPort,
+    isBusy: ctx.isPortBusy,
+    findFree: ctx.findFreePort,
+  };
+  let ports;
+  try {
+    ports = await resolveStudioPorts(portOptions);
+  } catch (err) {
+    // The LaunchAgent run has no terminal: one readable line in the log beats a stack trace.
+    if (!parsed.strictPort) throw err;
+    console.error(style('error', err.message));
+    return 1;
+  }
+  port = ports.port;
+  apiPort = ports.apiPort;
+  for (const notice of ports.notices) {
+    console.log(style('warning', notice));
+  }
+
   console.log('');
   const setupSpinner = ora('Preparing local platform…');
   // `express`/`cors` are root dependencies, so the web server runs without a nested install. This
@@ -437,6 +754,7 @@ export async function run(ctx = {}) {
   const shutdown = async (code = 0) => {
     if (shuttingDown) return;
     shuttingDown = true;
+    try { removeState(); } catch { /* best effort */ }
     try { apiChild.kill('SIGTERM'); } catch { /* already gone */ }
     if (staticServer) {
       try { await staticServer.close(); } catch { /* ignore */ }
@@ -485,6 +803,22 @@ export async function run(ctx = {}) {
     return done;
   }
 
+  try {
+    writeState(
+      {
+        pid: process.pid,
+        port,
+        apiPort,
+        studioUrl,
+        apiUrl,
+        startedAt: new Date().toISOString(),
+      },
+      { env: process.env }
+    );
+  } catch (err) {
+    console.log(style('warning', `Could not record studio.json: ${err.message}`));
+  }
+
   console.log('');
   console.log(style('success', `Professor Studio is running at ${studioUrl}`));
   console.log(`  Pairing URL: ${pairingUrl}`);