@field/cascade 0.8.0 → 0.11.0

package/dist/cli/cliCommands-UQSFGEHF.js

@@ -0,0 +1,3464 @@
+import {
+  formatCompactJSON
+} from "./chunk-OWWBYLHC.js";
+import {
+  PythonWorker,
+  StageCancelledError,
+  callStage,
+  compileEmbedded,
+  compileProjectModule,
+  compileProjectPanel,
+  formatStageTrace,
+  pythonWorkerStatuses,
+  shutdownAllPythonWorkers,
+  stageSources
+} from "./chunk-MIIEFUGG.js";
+import {
+  writeFileAtomic,
+  writeFileAtomicSync
+} from "./chunk-WPUDGEFY.js";
+import {
+  readStageConfig,
+  runProjectStage
+} from "./chunk-VVGSLVSF.js";
+import "./chunk-WD62JIP6.js";
+import {
+  CredentialStore,
+  PathSafetyError,
+  ProjectRoot,
+  ShellProcessError,
+  ShellRequestError,
+  readProjectManifest,
+  resolveWithinRoot,
+  secretValue,
+  writeProjectManifest
+} from "./chunk-RQZ4SX5R.js";
+import "./chunk-A4OAMOZH.js";
+import "./chunk-J7VK7MNF.js";
+import "./chunk-BIJO5OFS.js";
+
+// server/src/cliCommands.ts
+import fs13 from "node:fs";
+import path13 from "node:path";
+import { execFile as execFile3 } from "node:child_process";
+
+// server/src/config.ts
+import fs from "fs";
+import os from "os";
+import path from "path";
+var CONFIG_DIR = path.join(os.homedir(), ".cascade");
+var CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
+var DEFAULT_PROJECTS_ROOT = path.join(os.homedir(), "Documents", "Cascade");
+function loadConfig() {
+  try {
+    const raw = JSON.parse(fs.readFileSync(CONFIG_FILE, "utf-8"));
+    if (typeof raw?.projectsRoot === "string" && raw.projectsRoot.trim()) {
+      const expanded = raw.projectsRoot.replace(/^~(?=\/|$)/, os.homedir());
+      return { projectsRoot: path.resolve(expanded) };
+    }
+  } catch {
+  }
+  return { projectsRoot: DEFAULT_PROJECTS_ROOT };
+}
+function saveConfig(config) {
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + "\n", "utf-8");
+}
+function configPath() {
+  return CONFIG_FILE;
+}
+
+// server/src/index.ts
+import express2 from "express";
+import { createServer } from "http";
+import path8 from "path";
+import fs9 from "fs";
+import { fileURLToPath } from "url";
+
+// server/src/routes/graph.ts
+import { Router } from "express";
+
+// server/src/git.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+import fssync from "fs";
+import path2 from "path";
+var execFileAsync = promisify(execFile);
+async function git(cwd, args) {
+  return execFileAsync("git", args, { cwd });
+}
+async function ensureGitRepo(root) {
+  if (fssync.existsSync(path2.join(root, ".git"))) return;
+  await git(root, ["init"]);
+}
+async function autoCommit(root, message2, paths) {
+  await ensureGitRepo(root);
+  const scope = paths && paths.length ? ["--", ...paths] : [];
+  await git(root, scope.length ? ["add", ...scope] : ["add", "-A"]);
+  const { stdout } = await git(root, ["status", "--porcelain", ...scope]);
+  if (!stdout.trim()) {
+    return { committed: false };
+  }
+  await git(root, ["commit", "-m", message2, ...scope]);
+  const { stdout: sha } = await git(root, ["rev-parse", "HEAD"]);
+  return { committed: true, sha: sha.trim() };
+}
+var LOG_SEP = "";
+async function listFileVersions(root, file, limit = 50) {
+  if (!fssync.existsSync(path2.join(root, ".git"))) return [];
+  try {
+    const { stdout } = await git(root, [
+      "log",
+      `--max-count=${limit}`,
+      `--format=%H${LOG_SEP}%aI${LOG_SEP}%s`,
+      "--",
+      file
+    ]);
+    return stdout.split("\n").filter(Boolean).map((line) => {
+      const [sha, date, ...rest] = line.split(LOG_SEP);
+      return { sha, shortSha: sha.slice(0, 7), date, message: rest.join(LOG_SEP) };
+    });
+  } catch {
+    return [];
+  }
+}
+async function isFileDirty(root, file) {
+  if (!fssync.existsSync(path2.join(root, ".git"))) return false;
+  try {
+    const { stdout } = await git(root, ["status", "--porcelain", "--", file]);
+    return Boolean(stdout.trim());
+  } catch {
+    return false;
+  }
+}
+async function readFileAtVersion(root, file, sha) {
+  if (!/^[0-9a-fA-F]{4,40}$/.test(sha)) {
+    throw new Error(`Not a commit hash: ${sha}`);
+  }
+  try {
+    const { stdout } = await git(root, ["show", `${sha}:${file}`]);
+    return stdout;
+  } catch (err) {
+    const notFound = new Error(`No version ${sha} of ${file}`);
+    notFound.code = "ENOENT";
+    throw notFound;
+  }
+}
+
+// server/src/routes/graph.ts
+import fs2 from "node:fs/promises";
+import path3 from "node:path";
+function handleError(res, err) {
+  if (err instanceof PathSafetyError) {
+    res.status(400).json({ error: err.message });
+    return;
+  }
+  const code = err?.code;
+  if (code === "ENOENT") {
+    res.status(404).json({ error: "not found" });
+    return;
+  }
+  console.error("[graph route] error:", err);
+  res.status(500).json({ error: String(err) });
+}
+function createGraphRouter(project) {
+  const router = Router();
+  router.get("/", async (_req, res) => {
+    try {
+      res.json({
+        root: project.root,
+        isGitRepo: project.isGitRepo,
+        graphs: await project.listGraphFiles(),
+        default: await project.resolveDefaultGraph()
+      });
+    } catch (err) {
+      handleError(res, err);
+    }
+  });
+  router.get("/:filename", async (req, res) => {
+    try {
+      const content = await project.readGraph(req.params.filename);
+      res.type("application/json").send(content);
+    } catch (err) {
+      handleError(res, err);
+    }
+  });
+  router.put("/:filename", async (req, res) => {
+    try {
+      const graphData = req.body;
+      graphData.metadata = graphData.metadata || {};
+      graphData.metadata.modified = (/* @__PURE__ */ new Date()).toISOString();
+      const compact = formatCompactJSON(JSON.stringify(graphData, null, 2), 2);
+      await project.writeGraph(req.params.filename, compact);
+      const { committed, sha } = await autoCommit(
+        project.root,
+        saveCommitMessage(req.params.filename),
+        [req.params.filename]
+      );
+      res.json({ ok: true, committed, sha });
+    } catch (err) {
+      handleError(res, err);
+    }
+  });
+  router.get("/:filename/workspace", async (req, res) => {
+    try {
+      const target = workspacePath(project, req.params.filename);
+      await fs2.access(project.resolve(req.params.filename));
+      let content;
+      try {
+        content = await fs2.readFile(target, "utf-8");
+      } catch (err) {
+        if (err?.code === "ENOENT") {
+          res.json(null);
+          return;
+        }
+        throw err;
+      }
+      res.type("application/json").send(content);
+    } catch (err) {
+      handleError(res, err);
+    }
+  });
+  router.put("/:filename/workspace", async (req, res) => {
+    try {
+      const body = req.body;
+      if (!body || typeof body !== "object" || Array.isArray(body) || !body.layout || typeof body.layout !== "object") {
+        res.status(400).json({ error: "a workspace is an object with a layout" });
+        return;
+      }
+      const slot = req.query.slot === "failed" ? "failed" : null;
+      const target = workspacePath(project, req.params.filename, slot);
+      await writeFileAtomic(target, JSON.stringify(body, null, 1));
+      res.json({ ok: true, file: path3.basename(target) });
+    } catch (err) {
+      handleError(res, err);
+    }
+  });
+  router.get("/:filename/versions", async (req, res) => {
+    try {
+      const filename = req.params.filename;
+      if (!filename.endsWith(".cascade")) {
+        res.status(400).json({ error: `not a .cascade file: ${filename}` });
+        return;
+      }
+      project.resolve(filename);
+      res.json({
+        isGitRepo: project.isGitRepo,
+        dirty: await isFileDirty(project.root, filename),
+        versions: await listFileVersions(project.root, filename)
+      });
+    } catch (err) {
+      handleError(res, err);
+    }
+  });
+  router.get("/:filename/versions/:sha", async (req, res) => {
+    try {
+      const filename = req.params.filename;
+      if (!filename.endsWith(".cascade")) {
+        res.status(400).json({ error: `not a .cascade file: ${filename}` });
+        return;
+      }
+      project.resolve(filename);
+      if (!/^[0-9a-fA-F]{4,40}$/.test(req.params.sha)) {
+        res.status(400).json({ error: `not a commit hash: ${req.params.sha}` });
+        return;
+      }
+      const content = await readFileAtVersion(project.root, filename, req.params.sha);
+      res.type("application/json").send(content);
+    } catch (err) {
+      handleError(res, err);
+    }
+  });
+  return router;
+}
+function workspacePath(project, filename, slot = null) {
+  if (!filename.endsWith(".cascade") || filename !== path3.basename(filename)) {
+    throw new PathSafetyError(`not a .cascade file: ${filename}`);
+  }
+  const stem = filename.slice(0, -".cascade".length);
+  return project.resolve(`${stem}.workspace${slot ? `.${slot}` : ""}.json`);
+}
+function saveCommitMessage(filename, at = /* @__PURE__ */ new Date()) {
+  const time = at.toLocaleTimeString("en-GB", { hour: "2-digit", minute: "2-digit", hour12: false });
+  return `Saved ${filename} ${time}`;
+}
+
+// server/src/routes/assets.ts
+import { Router as Router2 } from "express";
+import multer from "multer";
+import path4 from "path";
+import fs3 from "fs/promises";
+function handleError2(res, err) {
+  if (err instanceof PathSafetyError) {
+    res.status(400).json({ error: err.message });
+    return;
+  }
+  res.status(500).json({ error: String(err) });
+}
+function createAssetsRouter(project) {
+  const router = Router2();
+  const assetsRoot = project.resolve("assets");
+  const storage = multer.diskStorage({
+    destination: async (_req, file, cb) => {
+      let assetType = "data";
+      if (file.mimetype.startsWith("image/")) assetType = "images";
+      else if (file.mimetype.startsWith("audio/")) assetType = "audio";
+      const dir = path4.join(assetsRoot, assetType);
+      await fs3.mkdir(dir, { recursive: true });
+      cb(null, dir);
+    },
+    filename: (_req, file, cb) => cb(null, file.originalname)
+  });
+  const upload = multer({ storage });
+  router.post("/", upload.single("file"), (req, res) => {
+    if (!req.file) {
+      res.status(400).json({ error: "no file uploaded" });
+      return;
+    }
+    const relativePath = path4.relative(assetsRoot, req.file.path);
+    res.json({
+      id: req.file.filename,
+      path: `./assets/${relativePath}`,
+      type: req.file.mimetype.startsWith("image/") ? "image" : req.file.mimetype.startsWith("audio/") ? "audio" : "binary",
+      size: req.file.size,
+      filename: req.file.filename
+    });
+  });
+  router.get("/{*assetPath}", async (req, res) => {
+    try {
+      const rel = req.params.assetPath?.join("/") ?? "";
+      const full = resolveWithinRoot(assetsRoot, rel);
+      res.sendFile(full);
+    } catch (err) {
+      if (err instanceof PathSafetyError) {
+        res.status(400).json({ error: err.message });
+      } else {
+        res.status(404).json({ error: "asset not found" });
+      }
+    }
+  });
+  router.delete("/{*assetPath}", async (req, res) => {
+    try {
+      const rel = req.params.assetPath?.join("/") ?? "";
+      const full = resolveWithinRoot(assetsRoot, rel);
+      await fs3.unlink(full);
+      res.json({ ok: true });
+    } catch (err) {
+      handleError2(res, err);
+    }
+  });
+  return router;
+}
+
+// server/src/routes/nodes.ts
+import { Router as Router3 } from "express";
+
+// server/src/nodeWatch.ts
+import fs5 from "node:fs";
+import path5 from "node:path";
+
+// server/src/watchSeam.ts
+import fs4 from "node:fs";
+var systemClock = {
+  setTimeout: (callback, ms) => setTimeout(callback, ms),
+  clearTimeout: (handle) => clearTimeout(handle)
+};
+var systemWatch = (directory, options, listener) => fs4.watch(directory, options, (event, filename) => listener(event, filename === null ? null : String(filename)));
+function createDebouncer(clock, ms, fire) {
+  const pending = /* @__PURE__ */ new Map();
+  return {
+    push(key2) {
+      const existing = pending.get(key2);
+      if (existing !== void 0) clock.clearTimeout(existing);
+      pending.set(key2, clock.setTimeout(() => {
+        pending.delete(key2);
+        fire(key2);
+      }, ms));
+    },
+    cancel() {
+      for (const handle of pending.values()) clock.clearTimeout(handle);
+      pending.clear();
+    }
+  };
+}
+
+// server/src/nodeWatch.ts
+var ALL_MODULES = "*";
+var NODE_WATCH_DEBOUNCE_MS = 120;
+function moduleNameFor(relative) {
+  const segments = relative.split(path5.sep).filter(Boolean);
+  if (segments.length < 2) return null;
+  const name = segments[0];
+  if (!name || name.startsWith(".")) return null;
+  return name;
+}
+function createNodeWatcher(project, seams = {}) {
+  const listeners = /* @__PURE__ */ new Set();
+  const watchers = [];
+  const watchDirectory = seams.watch ?? systemWatch;
+  const debounce = createDebouncer(seams.clock ?? systemClock, NODE_WATCH_DEBOUNCE_MS, (moduleName) => {
+    for (const listener of listeners) listener(moduleName);
+  });
+  const emit = (moduleName) => debounce.push(moduleName);
+  function watch(directory, scope) {
+    if (!fs5.existsSync(directory)) return;
+    try {
+      const watcher = watchDirectory(directory, { recursive: true }, (_event, filename) => {
+        if (!filename) return;
+        if (scope === "shared") {
+          emit(ALL_MODULES);
+          return;
+        }
+        const moduleName = moduleNameFor(String(filename));
+        if (moduleName) emit(moduleName);
+      });
+      watcher.on?.("error", (error) => console.warn("[node watch] stopped watching", directory, error));
+      watchers.push(watcher);
+    } catch (error) {
+      console.warn("[node watch] could not watch", directory, error);
+    }
+  }
+  watch(project.resolve("nodes"), "project");
+  try {
+    const sharedNodes = fs5.realpathSync(path5.join(project.root, "shared"));
+    watch(path5.join(sharedNodes, "nodes"), "shared");
+  } catch {
+  }
+  return {
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    close() {
+      debounce.cancel();
+      for (const watcher of watchers) watcher.close();
+      watchers.length = 0;
+      listeners.clear();
+    }
+  };
+}
+
+// server/src/routes/nodes.ts
+function handleError3(res, err) {
+  if (err instanceof PathSafetyError) {
+    res.status(400).json({ error: err.message });
+    return;
+  }
+  const code = err?.code;
+  if (code === "ENOENT") {
+    res.status(404).json({ error: "not found" });
+    return;
+  }
+  console.error("[nodes route] error:", err);
+  res.status(500).json({ error: String(err) });
+}
+var MAX_BATCH_MODULES = 500;
+function createNodesRouter(project) {
+  const router = Router3();
+  let watcher = null;
+  const factsCache = /* @__PURE__ */ new Map();
+  function forget(moduleName) {
+    if (moduleName === ALL_MODULES) factsCache.clear();
+    else factsCache.delete(moduleName);
+  }
+  function ensureWatcher() {
+    if (!watcher) {
+      watcher = createNodeWatcher(project);
+      watcher.subscribe(forget);
+    }
+    return watcher;
+  }
+  function moduleFacts(name) {
+    let cached = factsCache.get(name);
+    if (!cached) {
+      cached = Promise.all([project.moduleRunsOn(name), project.moduleIcon(name)]).then(([runsOn, icon]) => ({ runsOn, icon }));
+      factsCache.set(name, cached);
+      cached.catch(() => {
+        if (factsCache.get(name) === cached) factsCache.delete(name);
+      });
+    }
+    return cached;
+  }
+  router.get("/events", (req, res) => {
+    res.set({
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache, no-transform",
+      Connection: "keep-alive",
+      // Without this a proxy can hold the stream in a buffer and deliver
+      // every event at once when the request finally ends.
+      "X-Accel-Buffering": "no"
+    });
+    res.flushHeaders?.();
+    res.write("retry: 2000\n\n");
+    const unsubscribe = ensureWatcher().subscribe((moduleName) => {
+      res.write(`event: module-changed
+data: ${JSON.stringify({ module: moduleName })}
+
+`);
+    });
+    const keepAlive = setInterval(() => res.write(": keep-alive\n\n"), 3e4);
+    req.on("close", () => {
+      clearInterval(keepAlive);
+      unsubscribe();
+    });
+  });
+  router.get("/", async (_req, res) => {
+    try {
+      ensureWatcher();
+      const modules = await project.listNodeModules();
+      const runsOn = {};
+      const icons = {};
+      await Promise.all(modules.map(async (name) => {
+        const facts = await moduleFacts(name);
+        runsOn[name] = facts.runsOn;
+        if (facts.icon) icons[name] = facts.icon;
+      }));
+      res.json({ modules, runsOn, icons });
+    } catch (err) {
+      handleError3(res, err);
+    }
+  });
+  router.get("/compiled", async (req, res) => {
+    const raw = req.query.module;
+    const names = [...new Set((Array.isArray(raw) ? raw : raw === void 0 ? [] : [raw]).map(String).filter(Boolean))];
+    if (names.length === 0) {
+      res.status(400).json({ error: "name at least one module: /api/nodes/compiled?module=<name>" });
+      return;
+    }
+    if (names.length > MAX_BATCH_MODULES) {
+      res.status(400).json({ error: `at most ${MAX_BATCH_MODULES} modules per request` });
+      return;
+    }
+    try {
+      const modules = {};
+      await Promise.all(names.map(async (name) => {
+        const result = await compileProjectModule(project, name);
+        modules[name] = result.ok ? { code: result.code } : { error: result.errors.join("\n") };
+      }));
+      res.set("Cache-Control", "no-store").json({ modules });
+    } catch (err) {
+      handleError3(res, err);
+    }
+  });
+  router.get("/:moduleName/runs-on", async (req, res) => {
+    try {
+      res.json({ module: req.params.moduleName, runsOn: await project.moduleRunsOn(req.params.moduleName) });
+    } catch (err) {
+      handleError3(res, err);
+    }
+  });
+  router.get("/:moduleName/path", (req, res) => {
+    try {
+      res.json({ path: project.resolve(`nodes/${req.params.moduleName}/index.ts`) });
+    } catch (err) {
+      handleError3(res, err);
+    }
+  });
+  router.get("/:moduleName/compiled", async (req, res) => {
+    try {
+      const result = await compileProjectModule(project, req.params.moduleName);
+      if (!result.ok) {
+        res.status(422).json({ error: result.errors.join("\n") });
+        return;
+      }
+      res.type("application/javascript").send(result.code);
+    } catch (err) {
+      handleError3(res, err);
+    }
+  });
+  router.get("/:moduleName/{*file}", async (req, res) => {
+    try {
+      const rel = req.params.file?.join("/") || "index.ts";
+      const content = await project.readNodeModuleFile(req.params.moduleName, rel);
+      res.type("text/plain").send(content);
+    } catch (err) {
+      handleError3(res, err);
+    }
+  });
+  router.put("/:moduleName/{*file}", async (req, res) => {
+    try {
+      const rel = req.params.file?.join("/") || "index.ts";
+      const content = req.body?.content;
+      if (typeof content !== "string") {
+        res.status(400).json({ error: "body must be { content: string }" });
+        return;
+      }
+      await project.writeNodeModuleFile(req.params.moduleName, rel, content);
+      forget(req.params.moduleName);
+      const { committed } = await autoCommit(project.root, `Update node ${req.params.moduleName}/${rel}`, [`nodes/${req.params.moduleName}`]);
+      res.json({ ok: true, committed });
+    } catch (err) {
+      handleError3(res, err);
+    }
+  });
+  router.post("/", async (req, res) => {
+    try {
+      const name = String(req.body?.name ?? "");
+      if (!name) {
+        res.status(400).json({ error: "body must include { name: string }" });
+        return;
+      }
+      await project.ensureNodeModuleScaffold(name);
+      forget(name);
+      const { committed } = await autoCommit(project.root, `Scaffold node ${name}`, [`nodes/${name}`]);
+      res.json({ ok: true, name, committed });
+    } catch (err) {
+      handleError3(res, err);
+    }
+  });
+  router.post("/compile-embedded", async (req, res) => {
+    try {
+      const code = req.body?.code;
+      if (typeof code !== "string") {
+        res.status(400).json({ error: "body must be { code: string }" });
+        return;
+      }
+      const result = await compileEmbedded(project, code);
+      if (!result.ok) {
+        res.status(422).json({ error: result.errors.join("\n") });
+        return;
+      }
+      res.type("application/javascript").send(result.code);
+    } catch (err) {
+      handleError3(res, err);
+    }
+  });
+  return router;
+}
+
+// server/src/routes/panels.ts
+import { Router as Router4 } from "express";
+function handleError4(res, err) {
+  if (err instanceof PathSafetyError) {
+    res.status(400).json({ error: err.message });
+    return;
+  }
+  if (err?.code === "ENOENT") {
+    res.status(404).json({ error: "not found" });
+    return;
+  }
+  console.error("[panels route] error:", err);
+  res.status(500).json({ error: String(err) });
+}
+function createPanelsRouter(project) {
+  const router = Router4();
+  router.get("/", async (_req, res) => {
+    try {
+      const names = await project.listPanels();
+      res.json({ panels: await Promise.all(names.map((name) => project.panelMeta(name))) });
+    } catch (err) {
+      handleError4(res, err);
+    }
+  });
+  router.get("/:name/compiled", async (req, res) => {
+    try {
+      await project.resolvePanelEntry(req.params.name);
+      const result = await compileProjectPanel(project, req.params.name);
+      if (!result.ok) {
+        res.status(422).json({ error: result.errors.join("\n") });
+        return;
+      }
+      res.type("application/javascript").send(result.code);
+    } catch (err) {
+      handleError4(res, err);
+    }
+  });
+  return router;
+}
+
+// server/src/routes/exec.ts
+import { execFile as execFile2 } from "node:child_process";
+import { Router as Router5, json } from "express";
+
+// server/src/security.ts
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { isIP } from "node:net";
+function isLoopbackHost(host) {
+  const normalized = host.toLowerCase().replace(/^\[|\]$/g, "");
+  return normalized === "127.0.0.1" || normalized === "localhost" || normalized === "::1";
+}
+function allowsSensitiveCapabilities(options) {
+  return options.sensitiveCapabilities;
+}
+function createProjectRequestBoundary(options) {
+  const origins = new Set(options.trustedOrigins.map((origin) => validateOrigin(origin, "Project")));
+  const authorities = allowedAuthorities(options, origins);
+  return {
+    guard(req, res, next) {
+      const host = req.get("Host");
+      const origin = req.get("Origin");
+      if (!host || !authorities.has(host.toLowerCase()) || origin === "null" || origin && !origins.has(origin)) {
+        res.status(403).json({ ok: false, error: "Project access denied" });
+        return;
+      }
+      if (origin) setCorsOrigin(res, origin);
+      next();
+    },
+    preflight(req, res) {
+      const origin = req.get("Origin");
+      if (origin) setCorsOrigin(res, origin);
+      res.setHeader("Access-Control-Allow-Methods", "GET, HEAD, POST, PUT, DELETE, OPTIONS");
+      res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+      res.status(204).end();
+    }
+  };
+}
+function createBrowserCapabilityBoundary(options, label, header) {
+  const origins = new Set(options.trustedOrigins.map((origin) => validateOrigin(origin, label)));
+  const authorities = allowedAuthorities(options, origins);
+  const capability = randomBytes(32).toString("base64url");
+  const expectedBytes = Buffer.from(capability);
+  return {
+    guardOrigin(req, res, next) {
+      const origin = req.get("Origin");
+      const host = req.get("Host");
+      if (!host || !authorities.has(host.toLowerCase()) || origin === "null" || origin && !origins.has(origin)) {
+        res.status(403).json({ ok: false, error: `${label} access denied` });
+        return;
+      }
+      if (origin) setCorsOrigin(res, origin);
+      next();
+    },
+    preflight(_req, res) {
+      res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+      res.setHeader("Access-Control-Allow-Headers", `Content-Type, ${header}`);
+      res.status(204).end();
+    },
+    issueCapability(_req, res) {
+      res.setHeader("Cache-Control", "no-store, private");
+      res.setHeader("Pragma", "no-cache");
+      res.json({ capability });
+    },
+    requireCapability(req, res, next) {
+      const supplied = req.get(header);
+      const suppliedBytes = supplied ? Buffer.from(supplied) : Buffer.alloc(0);
+      if (suppliedBytes.length !== expectedBytes.length || !timingSafeEqual(suppliedBytes, expectedBytes)) {
+        res.status(403).json({ ok: false, error: `${label} capability required` });
+        return;
+      }
+      next();
+    }
+  };
+}
+function allowedAuthorities(options, origins) {
+  const authorities = new Set([...origins].map((origin) => new URL(origin).host.toLowerCase()));
+  if (isLoopbackHost(options.host)) {
+    authorities.add(`127.0.0.1:${options.port}`);
+    authorities.add(`localhost:${options.port}`);
+  } else if (!isWildcardHost(options.host)) {
+    authorities.add(authority(options.host, options.port));
+  }
+  for (const host of options.trustedHosts) {
+    const value = trustedAuthority(host, options.port);
+    authorities.add(value);
+    const bare = value.replace(/:(?:80|443)$/, "");
+    if (bare !== value) authorities.add(bare);
+  }
+  return authorities;
+}
+function isWildcardHost(host) {
+  const normalized = host.trim().toLowerCase().replace(/^\[|\]$/g, "");
+  return normalized === "0.0.0.0" || normalized === "::" || normalized === "*";
+}
+function trustedAuthority(value, defaultPort) {
+  const trimmed = value.trim().toLowerCase();
+  const bracketed = /^\[([^\]]+)\]:(\d+)$/.exec(trimmed);
+  if (bracketed) return authority(`[${bracketed[1]}]`, checkedPort(bracketed[2]));
+  const hostAndPort = /^([^:]+):(\d+)$/.exec(trimmed);
+  if (hostAndPort) return authority(hostAndPort[1], checkedPort(hostAndPort[2]));
+  return authority(trimmed, defaultPort);
+}
+function checkedPort(raw) {
+  const port = Number(raw);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(`Invalid trusted host port: ${raw}`);
+  }
+  return port;
+}
+function authority(host, port) {
+  const normalized = host.trim().toLowerCase().replace(/^\[|\]$/g, "");
+  if (!normalized || /[\s/?#@]/.test(normalized)) throw new Error(`Invalid trusted host: ${host}`);
+  if (normalized.includes(":") && isIP(normalized) !== 6) throw new Error(`Invalid trusted host: ${host}`);
+  return `${normalized.includes(":") ? `[${normalized}]` : normalized}:${port}`;
+}
+function setCorsOrigin(res, origin) {
+  res.setHeader("Access-Control-Allow-Origin", origin);
+  res.setHeader("Vary", "Origin");
+}
+function validateOrigin(value, label) {
+  const url = new URL(value);
+  if (!/^https?:$/.test(url.protocol) || url.username || url.password || url.pathname !== "/" || url.search || url.hash) {
+    throw new Error(`Invalid trusted ${label.toLowerCase()} origin: ${value}`);
+  }
+  return url.origin;
+}
+
+// server/src/routes/exec.ts
+var EXEC_TIMEOUT_MS = 12e4;
+var MAX_BUFFER = 64 * 1024 * 1024;
+var BODY_LIMIT = "64mb";
+function createExecRouter(project, security) {
+  const router = Router5();
+  if (!allowsSensitiveCapabilities(security)) return router.use((_req, res) => res.status(404).end());
+  const boundary = createBrowserCapabilityBoundary(security, "Exec", "X-Cascade-Exec-Capability");
+  let workerSlot = null;
+  router.use(boundary.guardOrigin);
+  router.options("{*path}", boundary.preflight);
+  router.get("/capability", boundary.issueCapability);
+  router.post("/", boundary.requireCapability, json({ limit: BODY_LIMIT }), async (req, res) => {
+    try {
+      const request = parseRequest(req.body);
+      const credentialEnv = new CredentialStore().environment(readProjectManifest(project.root).credentials);
+      if (request.kind === "stage") {
+        const config = readStageConfig(project);
+        const env = { ...process.env, ...credentialEnv };
+        const onTrace = (trace) => console.log(`[stage] ${formatStageTrace(trace)}`);
+        if (config.worker) {
+          const sources = stageSources(project, config);
+          const key2 = `${config.python}\0${config.worker}\0${sources.roots.join("\0")}\0${JSON.stringify(credentialEnv)}`;
+          if (workerSlot?.key !== key2) {
+            workerSlot?.worker.shutdown();
+            workerSlot = { key: key2, worker: new PythonWorker(project, config.worker, config.python, env, { sources }) };
+          }
+          const worker = workerSlot.worker;
+          const workerAbort = new AbortController();
+          res.once("close", () => {
+            if (!res.writableEnded) workerAbort.abort();
+          });
+          try {
+            const { result, trace } = await callStage(project, config, request.stage, request.args, (envelope) => worker.callWithMeta(request.stage, request.args, { signal: workerAbort.signal, cascade: envelope }), { env, onTrace, caller: request.caller });
+            res.json({ ok: true, stdout: JSON.stringify(result), stderr: "", trace });
+          } catch (error) {
+            if (res.destroyed || res.writableEnded) return;
+            const message2 = error instanceof Error ? error.message : String(error);
+            const cancelled = error instanceof StageCancelledError;
+            res.status(cancelled ? 499 : 500).json({ ok: false, error: message2, stdout: "", stderr: message2, ...cancelled ? { cancelled: true } : {} });
+          }
+          return;
+        }
+        const controller = new AbortController();
+        res.once("close", () => {
+          if (!res.writableEnded) controller.abort();
+        });
+        try {
+          const { result, trace } = await callStage(project, config, request.stage, request.args, async (envelope) => ({
+            result: await runProjectStage(project, request.stage, request.args, {
+              env,
+              timeout: EXEC_TIMEOUT_MS,
+              signal: controller.signal,
+              cascade: envelope,
+              codeHash: envelope.code
+            })
+          }), { env, onTrace, caller: request.caller });
+          res.json({ ok: true, stdout: JSON.stringify(result), stderr: "", trace });
+        } catch (error) {
+          const message2 = error instanceof Error ? error.message : String(error);
+          res.status(500).json({ ok: false, error: message2, stdout: "", stderr: message2 });
+        }
+        return;
+      }
+      await runPython(res, project, request.python, request.entrypoint, request.args, credentialEnv);
+    } catch (error) {
+      res.status(400).json({ ok: false, error: error instanceof Error ? error.message : String(error) });
+    }
+  });
+  router.use((error, _req, res, next) => {
+    if (error?.type === "entity.too.large" || error?.type === "entity.parse.failed") {
+      res.status(error.status ?? 400).json({ ok: false, error: error.message, type: error.type });
+    } else next(error);
+  });
+  return router;
+}
+function parseRequest(body) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) throw new Error("body must be an object");
+  const value = body;
+  if (typeof value.stage === "string") {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(value.stage)) throw new Error("stage contains unsupported characters");
+    if (value.args !== void 0 && (!value.args || typeof value.args !== "object" || Array.isArray(value.args))) {
+      throw new Error("stage args must be an object");
+    }
+    const caller = value.caller === "cook" ? "cook" : "action";
+    return { kind: "stage", stage: value.stage, args: value.args ?? {}, caller };
+  }
+  if (typeof value.entrypoint !== "string" || !value.entrypoint) {
+    throw new Error("body must include either { stage: string } or { entrypoint: string }");
+  }
+  if (value.args !== void 0 && !Array.isArray(value.args)) throw new Error("entrypoint args must be an array");
+  const python = value.python === "python" ? "python" : "python3";
+  return { kind: "entrypoint", entrypoint: value.entrypoint, args: (value.args ?? []).map(String), python };
+}
+function runPython(res, project, python, entrypoint, args, credentialEnv) {
+  const scriptPath = project.resolve(entrypoint);
+  return new Promise((resolve) => {
+    const child = execFile2(
+      python,
+      [scriptPath, ...args],
+      { cwd: project.root, timeout: EXEC_TIMEOUT_MS, maxBuffer: MAX_BUFFER, env: { ...process.env, ...credentialEnv } },
+      (error, stdout, stderr) => {
+        if (error) {
+          res.status(500).json({
+            ok: false,
+            error: error.message,
+            stdout,
+            stderr,
+            timedOut: error.signal === "SIGTERM"
+          });
+        } else {
+          res.json({ ok: true, stdout, stderr });
+        }
+        resolve();
+      }
+    );
+    res.once("close", () => {
+      if (!res.writableEnded) child.kill();
+    });
+  });
+}
+
+// server/src/routes/shell.ts
+import { Router as Router6, json as json2 } from "express";
+function createShellRouter(shell, options) {
+  const router = Router6();
+  if (!allowsSensitiveCapabilities(options)) return router.use((_req, res) => res.status(404).end());
+  const boundary = createBrowserCapabilityBoundary(options, "Shell", "X-Cascade-Shell-Capability");
+  router.use(boundary.guardOrigin);
+  router.options("{*path}", boundary.preflight);
+  router.get("/capability", boundary.issueCapability);
+  router.post("/", boundary.requireCapability, json2({ limit: "20mb" }), async (req, res) => {
+    const controller = new AbortController();
+    const cancel = () => controller.abort();
+    req.once("aborted", cancel);
+    res.once("close", () => {
+      if (!res.writableEnded) cancel();
+    });
+    try {
+      const body = parseBody(req.body);
+      const result = await shell.run(body.command, body.args, { ...body.options, signal: controller.signal });
+      if (result.code !== 0) {
+        res.status(500).json(errorPayload(new ShellProcessError("nonzero", result, result.stderr || `Command exited with code ${result.code}`)));
+      } else {
+        res.json({ ok: true, ...result });
+      }
+    } catch (error) {
+      if (error instanceof ShellRequestError) {
+        res.status(error.code === "COMMAND_NOT_ALLOWED" ? 403 : 400).json({ ok: false, error: error.message, code: error.code });
+      } else if (error instanceof ShellProcessError) {
+        res.status(error.kind === "cancelled" ? 499 : 500).json(errorPayload(error));
+      } else {
+        res.status(500).json({ ok: false, error: "Shell execution failed" });
+      }
+    }
+  });
+  router.use((error, _req, res, next) => {
+    if (error?.type === "entity.too.large" || error?.type === "entity.parse.failed") {
+      res.status(error.status ?? 400).json({ ok: false, error: error.message, type: error.type });
+    } else next(error);
+  });
+  return router;
+}
+function parseBody(body) {
+  if (!body || typeof body !== "object" || typeof body.command !== "string") throw new ShellRequestError("INVALID_REQUEST", "body must include { command: string }");
+  if (body.args !== void 0 && !Array.isArray(body.args)) throw new ShellRequestError("INVALID_REQUEST", "args must be an array");
+  return { command: body.command, args: body.args ?? [], options: { cwd: body.cwd, timeout: body.timeout, stdin: body.stdin, env: body.env } };
+}
+function errorPayload(error) {
+  return { ok: false, error: error.message, kind: error.kind, ...error.result };
+}
+
+// server/src/routes/agent.ts
+import { Router as Router7, json as json3 } from "express";
+
+// server/src/agent/session.ts
+import { spawn } from "node:child_process";
+
+// server/src/agent/eventBuffer.ts
+var MAX_BUFFERED_EVENTS = 2e3;
+var MAX_BUFFERED_BYTES = 4 * 1024 * 1024;
+function weigh(event) {
+  const text = event?.text;
+  return (typeof text === "string" ? text.length : 0) + 64;
+}
+var AgentEventBuffer = class {
+  constructor(maxEvents = MAX_BUFFERED_EVENTS, maxBytes = MAX_BUFFERED_BYTES) {
+    this.maxEvents = maxEvents;
+    this.maxBytes = maxBytes;
+    this.entries = [];
+    this.bytes = 0;
+    this.next = 0;
+    this.lost = 0;
+  }
+  /** The sequence number the next pushed event will carry. */
+  get nextSeq() {
+    return this.next;
+  }
+  /** The sequence number of the oldest event still held. */
+  get firstSeq() {
+    return this.entries[0]?.seq ?? this.next;
+  }
+  get size() {
+    return this.entries.length;
+  }
+  /** How many events have been evicted over the life of this buffer. */
+  get droppedTotal() {
+    return this.lost;
+  }
+  push(event) {
+    const seq = this.next++;
+    this.entries.push({ seq, event });
+    this.bytes += weigh(event);
+    while (this.entries.length > 1 && (this.entries.length > this.maxEvents || this.bytes > this.maxBytes)) {
+      const evicted = this.entries.shift();
+      if (!evicted) break;
+      this.bytes -= weigh(evicted.event);
+      this.lost += 1;
+    }
+    return seq;
+  }
+  replay(since = 0) {
+    const from = Math.max(0, Math.floor(Number.isFinite(since) ? since : 0));
+    const start2 = this.firstSeq;
+    return {
+      events: this.entries.filter((entry) => entry.seq >= from).map((entry) => entry.event),
+      dropped: Math.max(0, Math.min(start2, this.next) - from),
+      nextSeq: this.next
+    };
+  }
+};
+
+// server/src/agent/allowlist.ts
+import fs6 from "node:fs";
+import os2 from "node:os";
+import path6 from "node:path";
+var ALIAS = /^[A-Za-z0-9._-]+$/;
+var AgentRequestError = class extends Error {
+  constructor(code, message2) {
+    super(message2);
+    this.code = code;
+    this.name = "AgentRequestError";
+  }
+};
+function allowlistHint(root, alias) {
+  return `Add this under "commands" in ${root}/cascade.json: "${alias}": "<path>"`;
+}
+function readManifest(root) {
+  try {
+    return JSON.parse(fs6.readFileSync(path6.join(root, "cascade.json"), "utf8"));
+  } catch {
+    return {};
+  }
+}
+function readCommands(root) {
+  const raw = readManifest(root);
+  return raw?.commands && typeof raw.commands === "object" && !Array.isArray(raw.commands) ? raw.commands : {};
+}
+var DEFAULT_AGENT_ARGS = {
+  // A headless Claude cannot prompt, so without this it runs and then declines
+  // to edit anything — the console would launch successfully and do nothing,
+  // which is the worst of both.
+  claude: ["--permission-mode", "acceptEdits"]
+};
+function agentExtraArgs(root, alias) {
+  const raw = readManifest(root);
+  const entry = raw?.agent?.[alias];
+  const declared = entry && typeof entry === "object" && !Array.isArray(entry) && "args" in entry ? entry.args : void 0;
+  if (Array.isArray(declared)) {
+    return declared.filter((value) => typeof value === "string" && !value.includes("\0"));
+  }
+  return [...DEFAULT_AGENT_ARGS[alias] ?? []];
+}
+function executableFile(candidate) {
+  try {
+    fs6.accessSync(candidate, fs6.constants.X_OK);
+    return fs6.statSync(candidate).isFile() ? fs6.realpathSync(candidate) : null;
+  } catch {
+    return null;
+  }
+}
+function resolveExecutable(target) {
+  if (typeof target !== "string" || !target || target.includes("\0")) return null;
+  const expanded = target.replace(/^~(?=\/|$)/, os2.homedir());
+  if (path6.isAbsolute(expanded)) return executableFile(expanded);
+  if (!/[\\/]/.test(expanded)) {
+    for (const dir of (process.env.PATH ?? "").split(path6.delimiter)) {
+      const found = executableFile(path6.join(dir, expanded));
+      if (found) return found;
+    }
+    return null;
+  }
+  return null;
+}
+function agentAvailability(root, alias) {
+  if (!ALIAS.test(alias)) {
+    return { alias, configured: false, resolved: false, hint: "Agent name must be an allowlist alias" };
+  }
+  const commands = readCommands(root);
+  if (!(alias in commands)) {
+    return { alias, configured: false, resolved: false, hint: allowlistHint(root, alias) };
+  }
+  const executable = resolveExecutable(commands[alias]);
+  return {
+    alias,
+    configured: true,
+    resolved: Boolean(executable),
+    hint: executable ? null : `Configured command "${alias}" is not available \u2014 check the path in ${root}/cascade.json`
+  };
+}
+function requireExecutable(root, alias) {
+  if (!ALIAS.test(alias)) throw new AgentRequestError("INVALID_REQUEST", "agent must be an allowlist alias");
+  const commands = readCommands(root);
+  if (!(alias in commands)) {
+    throw new AgentRequestError("COMMAND_NOT_ALLOWED", `Command "${alias}" is not allowed. ${allowlistHint(root, alias)}`);
+  }
+  const executable = resolveExecutable(commands[alias]);
+  if (!executable) throw new AgentRequestError("MISSING_EXECUTABLE", `Configured command "${alias}" is not available`);
+  return executable;
+}
+
+// server/src/agent/session.ts
+var DEFAULT_TIMEOUT_MS = 9e5;
+var MAX_PROMPT_BYTES = 64 * 1024;
+function childEnvironment() {
+  const env = { ...process.env };
+  for (const key2 of Object.keys(env)) {
+    if (key2.startsWith("TELEGRAM_") || key2 === "CLAUDE_CHANNELS") delete env[key2];
+  }
+  return env;
+}
+function claudeArgs(prompt, sessionId) {
+  const args = ["-p", prompt, "--output-format", "stream-json", "--verbose"];
+  if (sessionId) args.push("--resume", sessionId);
+  return args;
+}
+function argsFor(agent, prompt, sessionId, extra = []) {
+  if (agent === "codex") {
+    const base2 = sessionId ? ["exec", "resume", "--json"] : ["exec", "--json"];
+    const flags = codexExtraArgs(extra);
+    return sessionId ? [...base2, ...flags, sessionId, prompt] : [...base2, ...flags, prompt];
+  }
+  const base = claudeArgs(prompt, sessionId);
+  return [...base, ...extra];
+}
+function codexExtraArgs(extra) {
+  const result = [];
+  for (let index = 0; index < extra.length; index += 1) {
+    const arg = extra[index];
+    if (arg === "--sandbox" && extra[index + 1]) {
+      result.push("-c", `sandbox_mode=${JSON.stringify(extra[index + 1])}`);
+      index += 1;
+    } else if (arg.startsWith("--sandbox=")) {
+      result.push("-c", `sandbox_mode=${JSON.stringify(arg.slice("--sandbox=".length))}`);
+    } else {
+      result.push(arg);
+    }
+  }
+  return result;
+}
+function sessionIdFrom(line) {
+  const trimmed = line.trim();
+  if (!trimmed.startsWith("{")) return null;
+  try {
+    const value = JSON.parse(trimmed);
+    const id = value?.session_id ?? value?.sessionId ?? (value?.type === "thread.started" ? value?.thread_id : null);
+    return typeof id === "string" && id ? id : null;
+  } catch {
+    return null;
+  }
+}
+var LiveRun = class {
+  constructor(agent, sketch) {
+    this.agent = agent;
+    this.sketch = sketch;
+    this.buffer = new AgentEventBuffer();
+    this.listeners = /* @__PURE__ */ new Set();
+    this.startedAt = Date.now();
+    this.child = null;
+    this.running = true;
+    this.endedAt = null;
+  }
+  emit(event) {
+    this.buffer.push(event);
+    for (const listener of [...this.listeners]) {
+      try {
+        listener(event);
+      } catch {
+        this.listeners.delete(listener);
+      }
+    }
+  }
+  /** SIGTERM the whole process group — the agent spawns children of its own,
+   *  and killing only the parent leaves those behind. */
+  stop() {
+    const child = this.child;
+    if (!child?.pid) return;
+    try {
+      if (process.platform === "win32") child.kill("SIGTERM");
+      else process.kill(-child.pid, "SIGTERM");
+    } catch {
+      child.kill("SIGTERM");
+    }
+  }
+};
+var liveRuns = /* @__PURE__ */ new Set();
+var reaperInstalled = false;
+function reapAll() {
+  for (const run of [...liveRuns]) run.stop();
+}
+function ensureReaper() {
+  if (reaperInstalled) return;
+  reaperInstalled = true;
+  process.on("exit", reapAll);
+  for (const signal of ["SIGINT", "SIGTERM"]) {
+    if (process.listenerCount(signal) > 0) continue;
+    process.on(signal, () => {
+      reapAll();
+      process.removeAllListeners(signal);
+      process.kill(process.pid, signal);
+    });
+  }
+}
+var AgentSessions = class {
+  constructor(project) {
+    this.project = project;
+    this.states = /* @__PURE__ */ new Map();
+    this.changeListeners = /* @__PURE__ */ new Set();
+  }
+  /**
+   * Called whenever a run starts, ends or is forgotten. This is what lets the
+   * panel hold one quiet stream instead of asking for the status every second:
+   * the only thing it was polling for was a run it did not start appearing.
+   */
+  onChange(listener) {
+    this.changeListeners.add(listener);
+    return () => this.changeListeners.delete(listener);
+  }
+  notifyChange() {
+    for (const listener of [...this.changeListeners]) {
+      try {
+        listener();
+      } catch {
+        this.changeListeners.delete(listener);
+      }
+    }
+  }
+  availability(agent) {
+    return agentAvailability(this.project.root, agent);
+  }
+  /** What the panel shows before anything is typed: which agents this sketch
+   *  may launch, for the ones it may not exactly what to add, and — the reason
+   *  a reloaded panel does not strand anything — whether a run is still live. */
+  status(agents = ["claude", "codex"], sketch) {
+    const sessions = [];
+    for (const [id, state] of this.states) {
+      const run = state.run;
+      if (!run) continue;
+      if (sketch && run.sketch !== sketch) continue;
+      void id;
+      sessions.push({
+        agent: run.agent,
+        sketch: run.sketch,
+        running: run.running,
+        sessionId: state.sessionId,
+        startedAt: run.startedAt,
+        endedAt: run.endedAt,
+        buffered: run.buffer.size,
+        dropped: run.buffer.droppedTotal,
+        nextSeq: run.buffer.nextSeq
+      });
+    }
+    return { root: this.project.root, agents: agents.map((agent) => this.availability(agent)), sessions };
+  }
+  sessionId(agent, sketch) {
+    return this.states.get(key(agent, sketch))?.sessionId ?? null;
+  }
+  isRunning(agent, sketch) {
+    return this.states.get(key(agent, sketch))?.run?.running === true;
+  }
+  /** Drop the conversation for one sketch without touching anything on disk.
+   *  Refuses while a run is live, because forgetting the session id mid-run
+   *  would silently start the next prompt as a fresh conversation. */
+  reset(agent, sketch) {
+    const state = this.states.get(key(agent, sketch));
+    if (!state) return;
+    if (state.run?.running) throw new AgentRequestError("BUSY", `The ${agent} session for ${sketch} is still working`);
+    state.sessionId = null;
+    state.run = null;
+    this.notifyChange();
+  }
+  /** Stop a live run. This is the only thing that kills an agent now: a reader
+   *  going away no longer does, which is the whole point of the change. */
+  cancel(agent, sketch) {
+    const run = this.states.get(key(agent, sketch))?.run;
+    if (!run?.running) return false;
+    run.stop();
+    return true;
+  }
+  /**
+   * Join whatever is happening for this sketch — running, finished, or nothing.
+   *
+   * Never refuses with BUSY. BUSY exists to stop two prompts colliding on one
+   * conversation; a second *reader* is the opposite of a collision, so attach is
+   * always allowed and any number of panels may hold one open.
+   *
+   * Resolves when the run ends or when the caller detaches, whichever comes
+   * first. Detaching does not touch the child.
+   */
+  attach(request) {
+    const { agent, sketch, sink } = request;
+    const state = this.states.get(key(agent, sketch));
+    const run = state?.run ?? null;
+    const since = Math.max(0, Math.floor(request.since ?? 0));
+    if (!run) {
+      sink({ type: "attached", agent, sketch, running: false, sessionId: state?.sessionId ?? null, dropped: 0, replayed: 0, since });
+      return Promise.resolve();
+    }
+    const replay = run.buffer.replay(since);
+    sink({
+      type: "attached",
+      agent,
+      sketch,
+      running: run.running,
+      sessionId: state?.sessionId ?? null,
+      dropped: replay.dropped,
+      replayed: replay.events.length,
+      since
+    });
+    for (const event of replay.events) sink(event);
+    if (!run.running) return Promise.resolve();
+    return new Promise((resolve) => {
+      const detach = () => {
+        run.listeners.delete(listener);
+        request.signal?.removeEventListener("abort", detach);
+        resolve();
+      };
+      const listener = (event) => {
+        sink(event);
+        if (event.type === "exit" || event.type === "error") detach();
+      };
+      run.listeners.add(listener);
+      request.signal?.addEventListener("abort", detach, { once: true });
+      if (request.signal?.aborted) detach();
+    });
+  }
+  async prompt(request) {
+    const prompt = request.prompt;
+    if (typeof prompt !== "string" || !prompt.trim()) throw new AgentRequestError("INVALID_REQUEST", "prompt must be a non-empty string");
+    if (Buffer.byteLength(prompt) > MAX_PROMPT_BYTES) throw new AgentRequestError("INVALID_REQUEST", "prompt exceeds 64 KiB");
+    if (typeof request.sketch !== "string" || !/^[A-Za-z0-9][A-Za-z0-9 ._-]{0,127}\.cascade$/.test(request.sketch)) {
+      throw new AgentRequestError("INVALID_REQUEST", "sketch must be a .cascade filename in this project");
+    }
+    const executable = requireExecutable(this.project.root, request.agent);
+    const id = key(request.agent, request.sketch);
+    const state = this.states.get(id) ?? { sessionId: null, run: null };
+    this.states.set(id, state);
+    if (state.run?.running) throw new AgentRequestError("BUSY", `The ${request.agent} session for ${request.sketch} is still working`);
+    const run = new LiveRun(request.agent, request.sketch);
+    state.run = run;
+    liveRuns.add(run);
+    ensureReaper();
+    const reading = this.attach({
+      agent: request.agent,
+      sketch: request.sketch,
+      sink: request.sink,
+      signal: request.signal,
+      since: 0
+    });
+    this.launch(executable, request, state, run);
+    this.notifyChange();
+    await reading;
+  }
+  launch(executable, request, state, run) {
+    const resumed = Boolean(state.sessionId);
+    const args = argsFor(request.agent, request.prompt, state.sessionId, agentExtraArgs(this.project.root, request.agent));
+    run.emit({ type: "started", agent: request.agent, sketch: request.sketch, resumed });
+    const child = spawn(executable, args, {
+      cwd: this.project.root,
+      env: childEnvironment(),
+      shell: false,
+      detached: process.platform !== "win32",
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    run.child = child;
+    let timedOut = false;
+    let settled = false;
+    let carry = "";
+    const timer = setTimeout(() => {
+      timedOut = true;
+      run.stop();
+    }, request.timeout ?? DEFAULT_TIMEOUT_MS);
+    const finish = (event) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      run.running = false;
+      run.endedAt = Date.now();
+      liveRuns.delete(run);
+      run.emit(event);
+      run.listeners.clear();
+      this.notifyChange();
+    };
+    const takeLine = (line) => {
+      if (!line.trim()) return;
+      const found = sessionIdFrom(line);
+      if (found && found !== state.sessionId) {
+        state.sessionId = found;
+        run.emit({ type: "session", sessionId: found });
+      }
+      run.emit({ type: "stdout", text: line });
+    };
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      carry += chunk;
+      const lines = carry.split("\n");
+      carry = lines.pop() ?? "";
+      for (const line of lines) takeLine(line);
+    });
+    child.stderr.setEncoding("utf8");
+    child.stderr.on("data", (chunk) => run.emit({ type: "stderr", text: String(chunk) }));
+    child.once("error", (error) => {
+      finish({ type: "error", message: `Unable to spawn ${request.agent}: ${error.message}`, code: "SPAWN_FAILED" });
+    });
+    child.once("close", (code) => {
+      if (carry.trim()) takeLine(carry);
+      carry = "";
+      finish({ type: "exit", code, timedOut, cancelled: !timedOut && code !== 0 && wasSignalled(child) });
+    });
+    child.stdin.end();
+  }
+};
+function wasSignalled(child) {
+  return child.signalCode !== null;
+}
+function key(agent, sketch) {
+  return `${agent} ${sketch}`;
+}
+
+// server/src/routes/agent.ts
+var BODY_LIMIT2 = "1mb";
+var WATCH_KEEPALIVE_MS = 3e4;
+function createAgentRouter(project, security) {
+  const router = Router7();
+  if (!allowsSensitiveCapabilities(security)) return router.use((_req, res) => res.status(404).end());
+  const boundary = createBrowserCapabilityBoundary(security, "Agent", "X-Cascade-Agent-Capability");
+  const sessions = new AgentSessions(project);
+  router.use(boundary.guardOrigin);
+  router.options("{*path}", boundary.preflight);
+  router.get("/capability", boundary.issueCapability);
+  router.get("/status", boundary.requireCapability, (req, res) => {
+    const sketch = typeof req.query?.sketch === "string" ? req.query.sketch : void 0;
+    res.json({ ok: true, ...sessions.status(void 0, sketch) });
+  });
+  router.get("/watch", boundary.requireCapability, (req, res) => {
+    const sketch = typeof req.query?.sketch === "string" ? req.query.sketch : void 0;
+    res.status(200).set({
+      "Content-Type": "application/x-ndjson; charset=utf-8",
+      "Cache-Control": "no-store, no-transform",
+      "X-Accel-Buffering": "no"
+    });
+    res.flushHeaders?.();
+    const send = () => {
+      if (res.writableEnded) return;
+      res.write(`${JSON.stringify({ type: "status", sessions: sessions.status([], sketch).sessions })}
+`);
+    };
+    send();
+    const unsubscribe = sessions.onChange(send);
+    const keepAlive = setInterval(() => {
+      if (!res.writableEnded) res.write("\n");
+    }, WATCH_KEEPALIVE_MS);
+    res.once("close", () => {
+      clearInterval(keepAlive);
+      unsubscribe();
+    });
+  });
+  router.post("/reset", boundary.requireCapability, json3({ limit: BODY_LIMIT2 }), (req, res) => {
+    const agent = typeof req.body?.agent === "string" ? req.body.agent : "claude";
+    const sketch = typeof req.body?.sketch === "string" ? req.body.sketch : "";
+    try {
+      sessions.reset(agent, sketch);
+      res.json({ ok: true });
+    } catch (error) {
+      if (error instanceof AgentRequestError) res.status(409).json({ ok: false, error: error.message, code: error.code });
+      else throw error;
+    }
+  });
+  router.post("/cancel", boundary.requireCapability, json3({ limit: BODY_LIMIT2 }), (req, res) => {
+    const agent = typeof req.body?.agent === "string" ? req.body.agent : "claude";
+    const sketch = typeof req.body?.sketch === "string" ? req.body.sketch : "";
+    res.json({ ok: true, cancelled: sessions.cancel(agent, sketch) });
+  });
+  router.post("/attach", boundary.requireCapability, json3({ limit: BODY_LIMIT2 }), async (req, res) => {
+    const agent = typeof req.body?.agent === "string" ? req.body.agent : "claude";
+    const sketch = typeof req.body?.sketch === "string" ? req.body.sketch : "";
+    const since = Number.isFinite(req.body?.since) ? Number(req.body.since) : 0;
+    const controller = new AbortController();
+    res.once("close", () => {
+      if (!res.writableEnded) controller.abort();
+    });
+    const write = streamWriter(res);
+    await sessions.attach({ agent, sketch, since, sink: write, signal: controller.signal });
+    if (!res.writableEnded) res.end();
+  });
+  router.post("/prompt", boundary.requireCapability, json3({ limit: BODY_LIMIT2 }), async (req, res) => {
+    const agent = typeof req.body?.agent === "string" ? req.body.agent : "claude";
+    const sketch = typeof req.body?.sketch === "string" ? req.body.sketch : "";
+    const prompt = typeof req.body?.prompt === "string" ? req.body.prompt : "";
+    const controller = new AbortController();
+    res.once("close", () => {
+      if (!res.writableEnded) controller.abort();
+    });
+    const write = streamWriter(res);
+    let streaming = false;
+    const send = (event) => {
+      streaming = true;
+      write(event);
+    };
+    try {
+      await sessions.prompt({ agent, sketch, prompt, sink: send, signal: controller.signal });
+      if (!res.writableEnded) res.end();
+    } catch (error) {
+      const payload = error instanceof AgentRequestError ? { ok: false, error: error.message, code: error.code } : { ok: false, error: error instanceof Error ? error.message : "Agent launch failed" };
+      if (streaming) {
+        send({ type: "error", message: payload.error, code: "code" in payload ? payload.code : void 0 });
+        if (!res.writableEnded) res.end();
+        return;
+      }
+      const status = error instanceof AgentRequestError ? { COMMAND_NOT_ALLOWED: 403, MISSING_EXECUTABLE: 409, BUSY: 409, INVALID_REQUEST: 400 }[error.code] : 500;
+      res.status(status).json({ ...payload, hint: hintFor(error, project) });
+    }
+  });
+  router.use((error, _req, res, next) => {
+    if (error?.type === "entity.too.large" || error?.type === "entity.parse.failed") {
+      res.status(error.status ?? 400).json({ ok: false, error: error.message, type: error.type });
+    } else next(error);
+  });
+  return router;
+}
+function streamWriter(res) {
+  let open = false;
+  return (event) => {
+    if (!open) {
+      res.status(200).set({
+        "Content-Type": "application/x-ndjson; charset=utf-8",
+        "Cache-Control": "no-store, no-transform",
+        "X-Accel-Buffering": "no"
+      });
+      res.flushHeaders?.();
+      open = true;
+    }
+    if (!res.writableEnded) res.write(`${JSON.stringify(event)}
+`);
+  };
+}
+function hintFor(error, project) {
+  if (!(error instanceof AgentRequestError) || error.code !== "COMMAND_NOT_ALLOWED") return null;
+  return `${project.root}/cascade.json`;
+}
+
+// server/src/routes/graphWatch.ts
+import { Router as Router8 } from "express";
+
+// server/src/graphWatch.ts
+var GRAPH_WATCH_DEBOUNCE_MS = 150;
+function graphFileFor(relative) {
+  const segments = String(relative).split(/[\\/]/).filter(Boolean);
+  if (segments.length !== 1) return null;
+  const name = segments[0];
+  if (!name || name.startsWith(".")) return null;
+  if (!name.endsWith(".cascade")) return null;
+  return name;
+}
+function createGraphWatcher(project, seams = {}) {
+  const listeners = /* @__PURE__ */ new Set();
+  let watcher = null;
+  const debounce = createDebouncer(seams.clock ?? systemClock, GRAPH_WATCH_DEBOUNCE_MS, (filename) => {
+    for (const listener of listeners) listener(filename);
+  });
+  try {
+    watcher = (seams.watch ?? systemWatch)(project.root, { recursive: false }, (_event, filename) => {
+      if (!filename) return;
+      const graph = graphFileFor(String(filename));
+      if (graph) debounce.push(graph);
+    });
+    watcher.on?.("error", (error) => console.warn("[graph watch] stopped watching", project.root, error));
+  } catch (error) {
+    console.warn("[graph watch] could not watch", project.root, error);
+  }
+  return {
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    close() {
+      debounce.cancel();
+      watcher?.close();
+      watcher = null;
+      listeners.clear();
+    }
+  };
+}
+
+// server/src/routes/graphWatch.ts
+function createGraphWatchRouter(project) {
+  const router = Router8();
+  let watcher = null;
+  router.get("/", (req, res) => {
+    res.set({
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache, no-transform",
+      Connection: "keep-alive",
+      // Without this a proxy can hold the stream in a buffer and deliver every
+      // event at once when the request finally ends.
+      "X-Accel-Buffering": "no"
+    });
+    res.flushHeaders?.();
+    res.write("retry: 2000\n\n");
+    watcher ??= createGraphWatcher(project);
+    const unsubscribe = watcher.subscribe((filename) => {
+      res.write(`event: graph-changed
+data: ${JSON.stringify({ file: filename })}
+
+`);
+    });
+    const keepAlive = setInterval(() => res.write(": keep-alive\n\n"), 3e4);
+    req.on("close", () => {
+      clearInterval(keepAlive);
+      unsubscribe();
+    });
+  });
+  return router;
+}
+
+// server/src/routes/projectSettings.ts
+import { Router as Router9, json as json4 } from "express";
+function createProjectSettingsRouter(project, security, credentials = new CredentialStore()) {
+  const router = Router9();
+  if (!allowsSensitiveCapabilities(security)) return router.use((_req, res) => res.status(404).end());
+  const boundary = createBrowserCapabilityBoundary(security, "Project settings", "X-Cascade-Project-Capability");
+  router.use(boundary.guardOrigin);
+  router.options("{*path}", boundary.preflight);
+  router.get("/capability", boundary.issueCapability);
+  router.get("/", boundary.requireCapability, (_req, res) => {
+    try {
+      res.json(publicProjectState(project, credentials));
+    } catch (error) {
+      res.status(500).json({ ok: false, error: message(error) });
+    }
+  });
+  router.put("/", boundary.requireCapability, json4({ limit: "1mb" }), (req, res) => {
+    try {
+      writeProjectManifest(project.root, req.body);
+      res.json(publicProjectState(project, credentials));
+    } catch (error) {
+      res.status(400).json({ ok: false, error: message(error) });
+    }
+  });
+  return router;
+}
+function publicProjectState(project, credentials) {
+  const manifest = readProjectManifest(project.root);
+  const requiredCredentials = manifest.credentials.map((name) => ({ name, set: credentials.has(name) }));
+  return { ok: true, manifest, requiredCredentials, missingCredentials: requiredCredentials.filter((item) => !item.set).map((item) => item.name) };
+}
+function message(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// server/src/routes/net.ts
+import { Router as Router10, json as json5 } from "express";
+var ALLOWED_METHODS = /* @__PURE__ */ new Set(["GET", "POST", "PUT", "PATCH", "DELETE"]);
+var BLOCKED_HEADER = /^(?:authorization|cookie|host|origin|referer|proxy-|sec-)/i;
+function createNetRouter(project, security, credentials = new CredentialStore()) {
+  const router = Router10();
+  if (!allowsSensitiveCapabilities(security)) return router.use((_req, res) => res.status(404).end());
+  const boundary = createBrowserCapabilityBoundary(security, "Authorized fetch", "X-Cascade-Net-Capability");
+  router.use(boundary.guardOrigin);
+  router.options("{*path}", boundary.preflight);
+  router.get("/capability", boundary.issueCapability);
+  router.post("/", boundary.requireCapability, json5({ limit: "16mb" }), async (req, res) => {
+    try {
+      res.json(await authorizedProxyRequest(project, credentials, req.body));
+    } catch (error) {
+      const status = typeof error?.status === "number" ? error.status : 400;
+      res.status(status).json({ ok: false, error: error instanceof Error ? error.message : String(error) });
+    }
+  });
+  return router;
+}
+async function authorizedProxyRequest(project, credentials, input, fetcher = fetch) {
+  const request = parseRequest2(input);
+  const manifest = readProjectManifest(project.root);
+  if (!manifest.credentials.includes(request.credential)) throw statusError(403, `Credential ${JSON.stringify(request.credential)} is not declared in cascade.json`);
+  const definition = credentials.get(request.credential);
+  if (!definition) throw statusError(424, `Credential ${JSON.stringify(request.credential)} is not set`);
+  const secret = secretValue(definition);
+  if (!secret || !definition.header || definition.hosts.length === 0) throw statusError(400, `Credential ${JSON.stringify(request.credential)} needs field/header/hosts metadata for browser proxy use`);
+  const url = new URL(request.url);
+  if (url.protocol !== "https:" || url.username || url.password || !definition.hosts.includes(url.hostname.toLowerCase())) {
+    throw statusError(403, `Credential ${JSON.stringify(request.credential)} is not authorized for ${url.hostname}`);
+  }
+  const headers = new Headers(request.headers);
+  for (const name of [...headers.keys()]) if (BLOCKED_HEADER.test(name)) headers.delete(name);
+  headers.set(definition.header, definition.scheme ? `${definition.scheme} ${secret}` : secret);
+  const response = await fetcher(url, { method: request.method, headers, body: request.body, redirect: "manual" });
+  const body = await response.text();
+  return {
+    ok: true,
+    status: response.status,
+    statusText: response.statusText,
+    headers: { "content-type": response.headers.get("content-type") ?? "text/plain" },
+    body
+  };
+}
+function parseRequest2(input) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error("body must be an object");
+  const value = input;
+  if (typeof value.credential !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(value.credential)) throw new Error("credential is invalid");
+  if (typeof value.url !== "string") throw new Error("url is required");
+  const method = typeof value.method === "string" ? value.method.toUpperCase() : "GET";
+  if (!ALLOWED_METHODS.has(method)) throw new Error("method is not supported");
+  if (value.body !== void 0 && typeof value.body !== "string") throw new Error("body must be a string");
+  const headers = value.headers === void 0 ? {} : value.headers;
+  if (!headers || typeof headers !== "object" || Array.isArray(headers) || Object.values(headers).some((item) => typeof item !== "string")) throw new Error("headers must be an object of strings");
+  return { credential: value.credential, url: value.url, method, headers, ...typeof value.body === "string" ? { body: value.body } : {} };
+}
+function statusError(status, message2) {
+  return Object.assign(new Error(message2), { status });
+}
+
+// server/src/routes/media.ts
+import express, { Router as Router11 } from "express";
+import crypto from "crypto";
+import fs7 from "fs";
+import path7 from "path";
+var sharpModule = null;
+var sharpError = null;
+async function loadSharp() {
+  if (sharpModule) return sharpModule;
+  if (sharpError) throw new Error(sharpError);
+  try {
+    sharpModule = (await import("sharp")).default;
+    return sharpModule;
+  } catch (err) {
+    sharpError = `Image transformation needs the "sharp" package, which failed to load: ${err instanceof Error ? err.message : String(err)}`;
+    throw new Error(sharpError);
+  }
+}
+var RASTER = /* @__PURE__ */ new Set([".png", ".jpg", ".jpeg", ".webp", ".tif", ".tiff", ".avif", ".gif"]);
+function readNpy(buffer) {
+  if (buffer.length < 10 || buffer.toString("latin1", 0, 6) !== "\x93NUMPY") {
+    throw new Error("not a .npy file");
+  }
+  const major = buffer[6];
+  const headerLength = major >= 2 ? buffer.readUInt32LE(8) : buffer.readUInt16LE(8);
+  const headerStart = major >= 2 ? 12 : 10;
+  const header = buffer.toString("latin1", headerStart, headerStart + headerLength);
+  const descr = header.match(/'descr':\s*'([^']+)'/)?.[1];
+  const fortran = /'fortran_order':\s*True/.test(header);
+  const shape = (header.match(/'shape':\s*\(([^)]*)\)/)?.[1] ?? "").split(",").map((part) => part.trim()).filter(Boolean).map(Number);
+  if (!descr) throw new Error(".npy header has no dtype");
+  if (fortran) throw new Error(".npy is Fortran-ordered; not supported");
+  if (shape.length < 2) throw new Error(`.npy is ${shape.length}-dimensional; expected an image-shaped array`);
+  const height = shape[0];
+  const width = shape[1];
+  const stride = shape.length > 2 ? shape.slice(2).reduce((a, b) => a * b, 1) : 1;
+  const count = height * width * stride;
+  const body = buffer.subarray(headerStart + headerLength);
+  const readers = {
+    "<f4": (o) => body.readFloatLE(o),
+    "<f8": (o) => body.readDoubleLE(o),
+    "|u1": (o) => body.readUInt8(o),
+    "<u1": (o) => body.readUInt8(o),
+    "|i1": (o) => body.readInt8(o),
+    "<i2": (o) => body.readInt16LE(o),
+    "<u2": (o) => body.readUInt16LE(o),
+    "<i4": (o) => body.readInt32LE(o),
+    "<u4": (o) => body.readUInt32LE(o),
+    "|b1": (o) => body.readUInt8(o)
+  };
+  const sizes = {
+    "<f4": 4,
+    "<f8": 8,
+    "|u1": 1,
+    "<u1": 1,
+    "|i1": 1,
+    "<i2": 2,
+    "<u2": 2,
+    "<i4": 4,
+    "<u4": 4,
+    "|b1": 1
+  };
+  const read = readers[descr];
+  const itemSize = sizes[descr];
+  if (!read || !itemSize) throw new Error(`.npy dtype ${descr} not supported`);
+  const data = new Float64Array(height * width);
+  for (let i = 0; i < height * width; i++) {
+    data[i] = read(i * stride * itemSize);
+  }
+  if (count * itemSize > body.length) throw new Error(".npy body is shorter than its shape");
+  return { data, width, height };
+}
+function fieldToGrey(array) {
+  let min = Infinity;
+  let max = -Infinity;
+  for (const value of array.data) {
+    if (!Number.isFinite(value)) continue;
+    if (value < min) min = value;
+    if (value > max) max = value;
+  }
+  if (!Number.isFinite(min) || !Number.isFinite(max)) {
+    min = 0;
+    max = 1;
+  }
+  const span = max - min || 1;
+  const pixels = Buffer.allocUnsafe(array.data.length);
+  for (let i = 0; i < array.data.length; i++) {
+    const value = array.data[i];
+    pixels[i] = Number.isFinite(value) ? Math.round((value - min) / span * 255) : 0;
+  }
+  return { pixels, min, max };
+}
+var CACHE_DIR = ".cascade-cache";
+function contentAddressed(rel, body) {
+  const hash = crypto.createHash("sha1").update(body).digest("hex").slice(0, 12);
+  const dir = path7.posix.dirname(rel);
+  const name = path7.posix.basename(rel);
+  const [stem, ...rest] = name.split(".");
+  const tail = rest.length ? `.${rest.join(".")}` : "";
+  return path7.posix.join(dir, `${stem}.${hash}${tail}`);
+}
+var MIME = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".gif": "image/gif",
+  ".tif": "image/tiff",
+  ".tiff": "image/tiff",
+  ".avif": "image/avif",
+  ".svg": "image/svg+xml",
+  ".json": "application/json",
+  ".txt": "text/plain",
+  ".npy": "application/octet-stream"
+};
+function clampInt(value, min, max) {
+  const n = Number(value);
+  if (!Number.isFinite(n)) return null;
+  return Math.min(max, Math.max(min, Math.round(n)));
+}
+function createMediaRouter(project) {
+  const router = Router11();
+  router.put("/{*mediaPath}", express.raw({ type: "*/*", limit: "512mb" }), async (req, res) => {
+    const rel = req.params.mediaPath?.join("/") ?? "";
+    if (!rel.startsWith(CACHE_DIR + "/")) {
+      res.status(400).json({ error: `writes are confined to ${CACHE_DIR}/ \u2014 got ${rel}` });
+      return;
+    }
+    if (!Buffer.isBuffer(req.body) || req.body.length === 0) {
+      res.status(400).json({ error: "empty body" });
+      return;
+    }
+    try {
+      const target = req.query.exact === "1" ? rel : contentAddressed(rel, req.body);
+      const full = project.resolve(target);
+      await fs7.promises.mkdir(path7.dirname(full), { recursive: true });
+      await fs7.promises.writeFile(full, req.body);
+      res.json({ ok: true, path: target, bytes: req.body.length });
+    } catch (err) {
+      res.status(err instanceof PathSafetyError ? 400 : 500).json({ error: String(err) });
+    }
+  });
+  router.get("/{*mediaPath}", async (req, res) => {
+    let full;
+    const rel = req.params.mediaPath?.join("/") ?? "";
+    try {
+      full = project.resolveMedia(rel);
+    } catch (err) {
+      res.status(err instanceof PathSafetyError ? 400 : 500).json({ error: String(err) });
+      return;
+    }
+    let stat;
+    try {
+      stat = await fs7.promises.stat(full);
+      if (!stat.isFile()) throw new Error("not a file");
+    } catch {
+      res.status(404).json({ error: `no such file: ${rel}` });
+      return;
+    }
+    const ext = path7.extname(full).toLowerCase();
+    const width = clampInt(req.query.w, 1, 2e4);
+    const quality = clampInt(req.query.q, 1, 100) ?? 82;
+    const requested = String(req.query.fmt ?? "").toLowerCase();
+    const raw = req.query.raw === "1" || req.query.raw === "true";
+    const etag = `W/"${stat.size.toString(16)}-${stat.mtimeMs.toString(16)}-${width ?? "full"}-${requested || "auto"}-${quality}-${raw ? "raw" : "enc"}"`;
+    res.setHeader("ETag", etag);
+    res.setHeader("Cache-Control", "private, max-age=0, must-revalidate");
+    if (req.headers["if-none-match"] === etag) {
+      res.status(304).end();
+      return;
+    }
+    if (!raw && ext === ".npy") {
+      try {
+        const array = readNpy(await fs7.promises.readFile(full));
+        const { pixels, min, max } = fieldToGrey(array);
+        res.setHeader("X-Field-Shape", `${array.height}x${array.width}`);
+        res.setHeader("X-Field-Range", `${min}:${max}`);
+        const sharp = await loadSharp();
+        let pipeline = sharp(pixels, {
+          raw: { width: array.width, height: array.height, channels: 1 }
+        });
+        if (width) pipeline = pipeline.resize({ width, withoutEnlargement: true });
+        if (requested === "png") {
+          res.type("image/png");
+          pipeline = pipeline.png({ compressionLevel: 9 });
+        } else {
+          res.type("image/webp");
+          pipeline = pipeline.webp({ quality, effort: 4 });
+        }
+        pipeline.on("error", (err) => {
+          console.error("[media] field encode failed:", rel, err);
+          if (!res.headersSent) res.status(500).json({ error: String(err) });
+          else res.end();
+        });
+        pipeline.pipe(res);
+      } catch (err) {
+        console.error("[media] field render failed:", rel, err);
+        res.status(422).json({ error: String(err instanceof Error ? err.message : err) });
+      }
+      return;
+    }
+    if (raw || !RASTER.has(ext)) {
+      res.type(MIME[ext] ?? "application/octet-stream");
+      res.setHeader("Content-Length", String(stat.size));
+      fs7.createReadStream(full).pipe(res);
+      return;
+    }
+    let format = requested;
+    if (!format) format = ext === ".gif" ? "gif" : "webp";
+    if (format === "gif") {
+      res.type("image/gif");
+      res.setHeader("Content-Length", String(stat.size));
+      fs7.createReadStream(full).pipe(res);
+      return;
+    }
+    try {
+      const sharp = await loadSharp();
+      let pipeline = sharp(full, { failOn: "none" }).rotate();
+      if (width) {
+        pipeline = pipeline.resize({ width, withoutEnlargement: true });
+      }
+      switch (format) {
+        case "png":
+          pipeline = pipeline.png({ compressionLevel: 9 });
+          res.type("image/png");
+          break;
+        case "jpeg":
+        case "jpg":
+          pipeline = pipeline.jpeg({ quality, mozjpeg: true });
+          res.type("image/jpeg");
+          break;
+        case "avif":
+          pipeline = pipeline.avif({ quality });
+          res.type("image/avif");
+          break;
+        default:
+          pipeline = pipeline.webp({ quality, effort: 4 });
+          res.type("image/webp");
+      }
+      pipeline.on("error", (err) => {
+        console.error("[media] encode failed:", rel, err);
+        if (!res.headersSent) res.status(500).json({ error: String(err) });
+        else res.end();
+      });
+      pipeline.pipe(res);
+    } catch (err) {
+      console.error("[media] error:", rel, err);
+      if (!res.headersSent) res.status(500).json({ error: String(err) });
+    }
+  });
+  return router;
+}
+
+// server/src/build.ts
+import fs8 from "node:fs";
+import { createHash } from "node:crypto";
+function buildId(distDir) {
+  try {
+    const contents = fs8.readFileSync(`${distDir}/index.html`);
+    return createHash("sha256").update(contents).digest("hex").slice(0, 16);
+  } catch {
+    return null;
+  }
+}
+
+// server/src/hostBinding.ts
+import net from "node:net";
+var HOST_UNAVAILABLE = /* @__PURE__ */ new Set(["ENOTFOUND", "EAI_AGAIN", "EAI_NONAME", "EAI_FAIL", "EADDRNOTAVAIL"]);
+var DEFAULT_FALLBACK_HOSTS = Object.freeze(["127.0.0.1"]);
+var DEFAULT_HOST_RETRY_MS = 1e4;
+function isHostUnavailable(error) {
+  return HOST_UNAVAILABLE.has(error?.code ?? "");
+}
+function bindWithFallback(server, options) {
+  const { port, preferredHost } = options;
+  const retryMs = options.retryMs ?? DEFAULT_HOST_RETRY_MS;
+  const log = options.log ?? ((message2) => console.warn(message2));
+  const resolveHost = options.resolveHost ?? ((host) => host);
+  const fallbacks = (options.fallbackHosts ?? DEFAULT_FALLBACK_HOSTS).filter((host) => host && host !== preferredHost);
+  let state = { host: null, port, preferredHost, fallback: false, reason: null, since: null };
+  let timer = null;
+  let stopped = false;
+  const update = (next) => {
+    state = { ...state, ...next };
+    options.onChange?.(state);
+  };
+  const bound = (host, reason) => {
+    update({ host, fallback: host !== preferredHost, reason, since: (/* @__PURE__ */ new Date()).toISOString() });
+    if (state.fallback) schedule();
+  };
+  async function bindFirstAvailable() {
+    let reason = null;
+    for (const host of [preferredHost, ...fallbacks]) {
+      try {
+        await listen(server, port, resolveHost(host));
+        if (host !== preferredHost) log(`[cascade] bound ${host}:${port} instead (fallback); will retry ${preferredHost} every ${Math.round(retryMs / 1e3)}s`);
+        bound(host, reason);
+        return state;
+      } catch (error) {
+        if (!isHostUnavailable(error)) throw error;
+        const message2 = describe(error, host, port);
+        reason ??= message2;
+        log(`[cascade] host ${host} is unavailable (${message2})`);
+      }
+    }
+    throw new Error(`no bindable host: tried ${[preferredHost, ...fallbacks].join(", ")} (${reason})`);
+  }
+  function schedule() {
+    if (stopped || timer) return;
+    timer = setTimeout(() => {
+      timer = null;
+      void retryPreferred();
+    }, retryMs);
+    timer.unref?.();
+  }
+  async function retryPreferred() {
+    if (stopped || !state.fallback) return;
+    if (state.host !== null && !server.listening) {
+      stopped = true;
+      return;
+    }
+    try {
+      await probe(resolveHost(preferredHost), port);
+    } catch {
+      schedule();
+      return;
+    }
+    const previous = state.host ?? fallbacks[0] ?? preferredHost;
+    if (server.listening) server.close();
+    server.closeIdleConnections?.();
+    try {
+      await listen(server, port, resolveHost(preferredHost));
+      log(`[cascade] ${preferredHost} is back \u2014 moved from ${previous}:${port} to ${preferredHost}:${port}`);
+      bound(preferredHost, null);
+    } catch (error) {
+      log(`[cascade] rebinding ${preferredHost} failed (${describe(error, preferredHost, port)}); staying on ${previous}`);
+      try {
+        await listen(server, port, resolveHost(previous));
+        bound(previous, state.reason);
+      } catch (fallbackError) {
+        log(`[cascade] could not rebind ${previous}:${port} either (${describe(fallbackError, previous, port)}); Studio is not listening \u2014 retrying`);
+        update({ host: null, since: null });
+        schedule();
+      }
+    }
+  }
+  const ready = bindFirstAvailable();
+  ready.catch(() => {
+  });
+  return {
+    ready,
+    state: () => state,
+    stop() {
+      stopped = true;
+      if (timer) clearTimeout(timer);
+      timer = null;
+    }
+  };
+}
+function listen(server, port, host) {
+  return new Promise((resolve, reject) => {
+    const onError = (error) => {
+      server.off("listening", onListening);
+      reject(error);
+    };
+    const onListening = () => {
+      server.off("error", onError);
+      resolve();
+    };
+    server.once("error", onError);
+    server.once("listening", onListening);
+    server.listen(port, host);
+  });
+}
+function probe(host, port) {
+  return new Promise((resolve, reject) => {
+    const socket = net.createServer();
+    socket.once("error", reject);
+    socket.listen(port, host, () => socket.close(() => resolve()));
+  });
+}
+function describe(error, host, port) {
+  const code = error.code;
+  if (code === "EADDRNOTAVAIL") return `EADDRNOTAVAIL ${host}:${port}`;
+  if (code && code.startsWith("E")) return `getaddrinfo ${code} ${host}`;
+  return error instanceof Error ? error.message : String(error);
+}
+
+// server/src/index.ts
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = path8.dirname(__filename);
+var CASCADE_DIST = path8.resolve(__dirname, "..", "..", "dist");
+var PROJECT_JSON_LIMIT = "32mb";
+function startServer(project, opts = {}) {
+  const app = express2();
+  const PORT = opts.port ?? (process.env.PORT ? parseInt(process.env.PORT, 10) : 3030);
+  const HOST = opts.host ?? "127.0.0.1";
+  const trustedHosts = Object.freeze([...opts.trustedHosts ?? []]);
+  const fallbackHosts = opts.fallbackHosts ?? DEFAULT_FALLBACK_HOSTS;
+  const loopbackReachable = isLoopbackHost(HOST) || fallbackHosts.some(isLoopbackHost);
+  const defaultOrigins = [
+    ...loopbackReachable ? [`http://127.0.0.1:${PORT}`, `http://localhost:${PORT}`] : [],
+    // Both schemes for a trusted host, because the server cannot know whether
+    // something is terminating TLS in front of it.
+    //
+    // This was `http://` only, and behind a TLS proxy a browser sends
+    // `Origin: https://name:port` — so the Host check passed and the **Origin
+    // check refused it**, which 403s every POST and PUT while GETs without an
+    // Origin header sail through. That is a Studio that loads, renders and
+    // then silently cannot save. Measured before fixing: `httpsOrigin: 403`,
+    // `httpOrigin: 200` on the same server.
+    //
+    // Not a widening: the Host allowlist already decides which authorities are
+    // acceptable, and this only says the same authority may arrive over either
+    // scheme.
+    ...trustedHosts.flatMap((host) => {
+      const value = trustedAuthority(host, PORT);
+      const bare = value.replace(/:(?:80|443)$/, "");
+      return [.../* @__PURE__ */ new Set([value, bare])].flatMap((authority3) => [
+        `http://${authority3}`,
+        `https://${authority3}`
+      ]);
+    })
+  ];
+  const security = Object.freeze({
+    host: HOST,
+    port: PORT,
+    trustedHosts,
+    sensitiveCapabilities: isLoopbackHost(HOST) || trustedHosts.length > 0,
+    trustedOrigins: Object.freeze([...opts.trustedOrigins ?? opts.trustedShellOrigins ?? defaultOrigins])
+  });
+  app.use("/api/shell", createShellRouter(project.shell, security));
+  app.use("/api/exec", createExecRouter(project, security));
+  app.use("/api/net", createNetRouter(project, security));
+  app.use("/api/agent", createAgentRouter(project, security));
+  app.use("/api/project", createProjectSettingsRouter(project, security));
+  const projectBoundary = createProjectRequestBoundary(security);
+  app.use("/api", projectBoundary.guard);
+  app.options("/api/{*splat}", projectBoundary.preflight);
+  app.use(express2.json({ limit: PROJECT_JSON_LIMIT }));
+  app.use(express2.urlencoded({ extended: true, limit: PROJECT_JSON_LIMIT }));
+  app.use((err, _req, res, next) => {
+    if (err && (err.type === "entity.too.large" || err.type === "entity.parse.failed")) {
+      res.status(err.status ?? 400).json({ ok: false, error: err.message, type: err.type });
+      return;
+    }
+    next(err);
+  });
+  app.use("/api/graph", createGraphRouter(project));
+  app.use("/api/assets", createAssetsRouter(project));
+  app.use("/api/nodes", createNodesRouter(project));
+  app.use("/api/panels", createPanelsRouter(project));
+  app.use("/api/media", createMediaRouter(project));
+  app.use("/api/graph-events", createGraphWatchRouter(project));
+  app.get("/health", (_req, res) => {
+    res.json({ status: "ok", version: "2.0", projectRoot: project.root, isGitRepo: project.isGitRepo });
+  });
+  app.get("/api/build", (_req, res) => {
+    res.json({ id: buildId(CASCADE_DIST) });
+  });
+  if (fs9.existsSync(CASCADE_DIST)) {
+    app.use(express2.static(CASCADE_DIST, {
+      setHeaders(res, filePath) {
+        res.setHeader(
+          "Cache-Control",
+          filePath.endsWith("index.html") ? "no-store" : "public, max-age=31536000, immutable"
+        );
+      }
+    }));
+    app.get("/{*splat}", (req, res, next) => {
+      if (req.path.startsWith("/api") || req.path === "/health") return next();
+      res.setHeader("Cache-Control", "no-store");
+      res.sendFile(path8.join(CASCADE_DIST, "index.html"));
+    });
+  } else {
+    console.warn(`[cascade-server] no build found at ${CASCADE_DIST} \u2014 run "npm run build" in the Cascade repo first. API-only for now.`);
+  }
+  const server = createServer(app);
+  const binding = bindWithFallback(server, {
+    port: PORT,
+    preferredHost: HOST,
+    fallbackHosts,
+    ...opts.hostRetryMs === void 0 ? {} : { retryMs: opts.hostRetryMs }
+  });
+  binding.ready.then((state) => {
+    console.log(`\u{1F680} Cascade running on http://${state.host}:${PORT}${state.fallback ? ` (fallback; preferred ${HOST} unavailable)` : ""}`);
+    console.log(`\u{1F4C1} Project: ${project.root}${project.isGitRepo ? " (git)" : " (not a git repo yet)"}`);
+    if (trustedHosts.length > 0) console.log(`\u{1F510} Trusted Studio URL: http://${trustedAuthority(trustedHosts[0], PORT)} (all reachable VPN/interface peers are trusted)`);
+  }, (error) => {
+    server.emit("error", error);
+  });
+  return Object.assign(server, { binding });
+}
+
+// server/src/projectTemplate.ts
+import fs10 from "node:fs";
+import path9 from "node:path";
+function cascadeVersionRange() {
+  try {
+    const pkg = JSON.parse(
+      fs10.readFileSync(new URL("../../package.json", import.meta.url), "utf8")
+    );
+    const match = /^(\d+)\.(\d+)\./.exec(pkg.version ?? "");
+    return match ? `^${match[1]}.${match[2]}.0` : "*";
+  } catch {
+    return "*";
+  }
+}
+var PROJECT_NAME = /^[a-z0-9][a-z0-9-]{0,63}$/;
+var NODE_NAME = /^[A-Z][A-Za-z0-9]{0,63}$/;
+function createProject(projectsRoot, name) {
+  if (!PROJECT_NAME.test(name)) {
+    throw new Error("Project names use lowercase letters, numbers, and hyphens (maximum 64 characters).");
+  }
+  const root = path9.resolve(projectsRoot);
+  const directory = path9.resolve(root, name);
+  if (path9.dirname(directory) !== root) throw new Error("Project path escapes the configured projects directory.");
+  if (fs10.existsSync(directory)) throw new Error(`Already exists: ${directory}`);
+  fs10.mkdirSync(path9.join(directory, "nodes"), { recursive: true });
+  fs10.mkdirSync(path9.join(directory, "assets"));
+  writeJson(path9.join(directory, "cascade.json"), { name });
+  writeJson(path9.join(directory, "index.cascade"), {
+    name,
+    version: "0.2",
+    viewport: { x: 0, y: 0, zoom: 1 },
+    nodes: [],
+    connections: [],
+    annotations: []
+  });
+  writeJson(path9.join(directory, "package.json"), {
+    name,
+    private: true,
+    type: "module",
+    scripts: {
+      check: "tsc --noEmit",
+      validate: "cascade validate index.cascade",
+      "check:graph": "cascade check index.cascade",
+      inspect: "cascade inspect index.cascade",
+      run: "cascade run index.cascade"
+    },
+    // Aliased, not renamed: the package publishes as `@field/cascade` because
+    // the bare name belongs to somebody else on npm — and a scaffolded project
+    // asking for `cascade` would silently install that stranger's package.
+    // The alias keeps every `cascade/contracts` import in a project working.
+    devDependencies: {
+      cascade: `npm:@field/cascade@${cascadeVersionRange()}`,
+      typescript: "^6.0.0"
+    }
+  });
+  writeJson(path9.join(directory, "tsconfig.json"), {
+    compilerOptions: {
+      target: "ES2022",
+      module: "ESNext",
+      moduleResolution: "Bundler",
+      strict: true,
+      noEmit: true
+    },
+    include: ["nodes/**/*.ts"]
+  });
+  fs10.writeFileSync(path9.join(directory, ".gitignore"), ".cascade-cache/\n.cascade/cache/\n.cascade/runs/\nrenders/\nnode_modules/\n");
+  fs10.writeFileSync(path9.join(directory, "AGENTS.md"), `# Cascade project
+
+Read \`node_modules/cascade/AGENTS.md\` for the framework itself. What follows is what an agent working in *this* project needs.
+
+## Read this first
+
+\`node_modules/cascade/doc/NODE_REFERENCE.md\` \u2014 every built-in node with its inputs, props and outputs, generated from the definitions themselves. Read it before creating a wrapper for an existing node. Time-based parameter changes usually need an expression or channel.
+
+## Common commands
+
+- Run \`npm install\` in this directory first. Scripts use the project's installed Cascade version; use \`npx --no-install cascade\` for direct local CLI commands.
+- \`npm run check\` \u2014 type-check custom nodes.
+- \`npm run check:graph\` \u2014 statically check the graph and node definitions.
+- \`npm run validate\` \u2014 validate \`index.cascade\`.
+- \`npm run run\` \u2014 execute headlessly without Studio.
+- \`cascade .\` \u2014 launch local Studio on loopback.
+- \`cascade . --host KURO --port 3030\` \u2014 launch for \`http://KURO:3030\` on a trusted VPN/LAN.
+
+Do not start another Cascade process on an occupied port. Remote access requires
+both the explicit bind address and the exact trusted browser hostname.
+
+## The \`.cascade\` document format
+
+Hand-editing is supported. Preserve metadata, source fields, IDs, and valid connection endpoints, then run the static checks. This example uses the node below; save it at \`nodes/Multiply/index.ts\` before running the graph.
+
+\`\`\`json
+{
+  "version": "0.2",
+  "metadata": { "name": "My Sketch" },
+  "nodes": [
+    {
+      "id": "multiply",
+      "module": "project.Multiply",
+      "position": [240, 200],
+      "source": "project",
+      "props": { "factor": { "value": 2, "expression": "2 + sin($T)" } }
+    }
+  ],
+  "connections": [],
+  "annotations": []
+}
+\`\`\`
+
+Five things that are easy to get wrong:
+
+- **Use \`module\` for the module identity and \`"source": "project"\` for project modules.** Unresolved modules need investigation even when validation only warns.
+- **\`position\` is \`[x, y]\`**, an array, not \`{x, y}\`.
+- **Definition-v1 stored parameter values belong under \`props\`.** A leftover \`params\` array is not read by the deterministic runtime; \`runtime/stray-params\` warns about stranded values.
+- **A connection is a pair of triples**: \`[[fromNode, portIndex, portName], [toNode, portIndex, portName]]\`. Direction comes from *position in the pair* \u2014 first is the source. The middle number is the **port index**, not a direction.
+- **A prop is a bare value or \`{ value, expression?, channel? }\`.** Channels take precedence over expressions, then stored values. Save the binding, not just its value at the playhead.
+
+## Design the graph, not one big node
+
+A piece is several nodes, each doing one job: load the data, lay it out, colour it, draw it, export it. Do not write one 300-line node that does all of it. The graph is the record Marcus inspects, so each node boundary should be a place worth looking at, with the parameters that matter on it.
+
+Clean graph design is clean code design:
+
+- **One responsibility per node**, named for what it does (\`layout_rings\`, not \`main\`).
+- **Data flows through typed ports**, never through module-level state or files one node writes and another reads behind the graph's back.
+- **What varies is a parameter**; seeds, counts and colours are on the node, not constants in the code.
+- **Shared helpers go in \`lib/\` or the kit**; the node is the unit you compose and reuse.
+
+Split a node when it does two of load, generate, style, render and export, or when its \`execute\` grows past about 150 lines.
+
+## Before writing a node, check whether you need one
+
+**Parameters can hold expressions**, and this is usually the answer to anything time-based. The variables are Houdini's:
+
+| | |
+|---|---|
+| \`$F\` | frame, integer |
+| \`$FF\` | frame, fractional |
+| \`$T\` | seconds \u2014 **zero on the first frame** |
+| \`$FPS\` | rate |
+| \`ch("node/param")\`, \`ch("./param")\` | read another parameter |
+
+So "oscillate the angle" is \`sin($T) * 40\` in the \`angle\` prop. **There is no built-in oscillator node and you do not need one.** A node earns its place when it produces geometry or pixels, or when several parameters share a computation.
+
+\`fit\`, \`fit01\`, \`clamp\`, \`lerp\`, \`smooth\`, \`noise\` and \`random\` are all available inside an expression.
+
+The maths library is exposed bare, so write \`sin(x)\` rather than \`Math.sin(x)\`. Angles are in **radians**, unlike Houdini; \`sind\`, \`cosd\`, \`tand\`, \`radians()\` and \`degrees()\` are there for a formula carried across, and \`PI\`, \`TAU\` and \`E\` are in scope.
+
+## Writing a node
+
+Project nodes live at \`nodes/<name>/index.ts\`, one folder per module, referenced as \`project.<name>\`. Write them in the **definition-v1** style, which is what \`cascade node <Name>\` scaffolds:
+
+\`\`\`ts
+import type { NodeDefinition, NodeExecutionContext } from 'cascade/contracts';
+
+export const definition = {
+  apiVersion: 1,
+  label: 'Multiply',
+  icon: 'Circle',                    // a Lucide icon name
+  runsOn: 'portable',                // 'portable' | 'browser' | 'server'
+  inputs: {
+    value: { kind: 'data', type: 'float', default: 3 },
+  },
+  outputs: {
+    result: { kind: 'data', type: 'float' },
+  },
+  props: {
+    factor: { type: 'float', default: 2, min: 0, max: 10, step: 0.1 },
+  },
+} as const satisfies NodeDefinition;
+
+export function execute(context: NodeExecutionContext<typeof definition>) {
+  context.outputs.result.set(context.inputs.value * context.props.factor);
+}
+\`\`\`
+
+The declaration is the point: ports, types, props and the execution locus are read from the literal without running anything, which is what \`cascade check\` inspects and what the Definition panel shows. \`execute\` then does computation only \u2014 it never declares a port.
+
+### Use the vector types
+
+Anything with an x and a y is **one** \`vec2\`, not two floats. Same for \`vec3\` and \`vec4\`, with \`vec2i\`, \`vec3i\` and \`vec4i\` for integer counts and pixel sizes. Positions, offsets, scales, and resolutions use vector ports; colours use the core \`color\` type.
+
+\`\`\`ts
+// Wrong
+props: { offset_x: { type: 'float', default: 0 }, offset_y: { type: 'float', default: 0 } }
+
+// Right
+props: { offset: { type: 'vec2', default: [0, 0] } }
+\`\`\`
+
+Not a style preference. Two floats that are really one vector cannot be connected to a \`vec2\` output, get two rows in the Inspector instead of one control, need two keyframes to animate one movement, and let a graph carry an x without its y. The type system knows what a \`vec2\` is; it cannot know that \`offset_x\` and \`offset_y\` belong together.
+
+Split only when the components differ in kind. Vector props support \`min\`, \`max\`, and \`step\`, with one range across their components.
+
+Studio and a compatible CLI host cook this style. **Studio** builds ports from the compiled definition and calls \`execute\` with a real \`NodeExecutionContext\`; **\`cascade run\`** uses the deterministic runtime when the node's execution locus and capabilities are supported. A browser-only declaration still prevents a Node-host run.
+
+The **dynamic** style \u2014 \`execute(node, graph)\` declaring ports with \`node.in\`, \`node.param\`, and \`node.out\` \u2014 remains supported by Studio and the CLI compatibility engine. It cannot provide the same static checks. Studio may mix both styles; the CLI rejects mixed graphs. Convert deliberately with saved-value and output comparisons.
+
+Definition-v1 props support default \`expression\` values. An explicitly saved value overrides that default, even when equal to the numeric default. Both fully definition-v1 and supported dynamic graphs can render sequences with \`cascade run index.cascade --frames 1-100\`, subject to host capabilities. \`cascade render index.cascade --node <id>\` renders the same sequence across worker processes and encodes a half-size preview mp4; it needs each frame written to its own file (the frame in the name, or \`saveImage\` with \`cachePath\`, which is content-addressed), and refuses a node that writes one fixed path.
+
+For a standalone browser page or embed, use \`cascade build index.cascade --out web-player\` with a new output directory. Add \`--asset assets/file.svg\` for each asset addressed from code; typed literal asset/image references in the document are included automatically. Serve the result over HTTP(S). This player supports definition-v1 browser/portable nodes with assets or GPU capabilities, not server operations or dynamic modules. See \`node_modules/cascade/doc/WEB_PLAYER.md\` for iframe and programmatic controls.
+
+Either way the module is a real ES module and the loader needs the \`execute\` export. Top-level side effects do not belong in it.
+
+## Rendering
+
+Prefer Canvas 2D, WebGL, and WebGPU for interactive rendering. Use Python or another server stage for libraries and tools that require it. Transport, serialization, and cold starts can affect parameter-drag latency; persistent workers can avoid repeated process/model startup.
+
+Definition-v1 image nodes can use \`saveImage(canvas, cachePath(context.nodeId, '.png'))\` from \`cascade/io\`. The instance ID provides a cache namespace, not graph access. Final artefacts may instead use an explicit filename. Optional Skia supplies Canvas2D APIs; optional Dawn separately supplies WebGPU. Neither overrides a browser-only declaration or supplies the DOM.
+
+Use \`browser\` only for code that genuinely needs the page, such as the DOM or WebGL. Prefer \`new OffscreenCanvas(width, height)\` to \`document.createElement('canvas')\` when both hosts can run the same node.
+
+WebGPU nodes declare \`capabilities: ['gpu']\` and use \`context.capabilities.gpu\` for the shared device and per-node cache. Portable GPU nodes run in Studio or the optional Dawn CLI host. Import usage constants and explicit RGBA8 \`readTexture\` from \`cascade/gpu\`, then encode through the image/IO host. Graph texture exchange remains future work. For agent image feedback use \`cascade run index.cascade --frames 1 --json --timeout 60000\`; see \`node_modules/cascade/doc/HEADLESS_GPU.md\` for limitations.
+
+## Finding out what exists
+
+- \`node_modules/cascade/doc/PROJECT_AUTHORING.md\` \u2014 project layout and the node contract.
+- \`node_modules/cascade/ARCHITECTURE.md\` \u2014 what each package owns.
+- \`GET /api/nodes\` on the running server \u2014 the project's own modules, with their \`runsOn\` and icons.
+- \`node_modules/cascade/dist/runtime/builtins/\` \u2014 the built-in node definitions, as the shipped type declarations. (\`packages/\` is not in the published \`files\` list, so an installed copy has no source tree.)
+- The **Definition panel** in Studio shows, for any selected node, where it is defined and what it declares.
+
+## Verification and shared development
+
+Cascade's build refreshes \`dist/\`, which running Studio servers may serve. Coordinate a core rebuild with anyone using that checkout; routine sketch edits do not require rebuilding Cascade.
+
+Use \`npm run check:graph\` for static checks and \`npm run run\` for a compatible headless graph. A browser-only node may pass static checks with an environment warning and still be refused by the CLI; verify it in Studio instead. Compare actual outputs after edits and distinguish recorded measurements from tests run in the current session.
+`);
+  return directory;
+}
+function createNode(projectRoot, name) {
+  if (!NODE_NAME.test(name)) {
+    throw new Error("Node names start with an uppercase letter and contain only letters or numbers.");
+  }
+  const directory = path9.resolve(projectRoot, "nodes", name);
+  if (fs10.existsSync(directory)) throw new Error(`Already exists: ${directory}`);
+  fs10.mkdirSync(directory, { recursive: true });
+  fs10.writeFileSync(path9.join(directory, "index.ts"), nodeSource(name));
+  return directory;
+}
+function writeJson(file, value) {
+  fs10.writeFileSync(file, `${JSON.stringify(value, null, 2)}
+`);
+}
+function nodeSource(name) {
+  return `import type { NodeDefinition, NodeExecutionContext } from 'cascade/contracts';
+
+export const definition = {
+  apiVersion: 1,
+  label: '${name}',
+  runsOn: 'portable',
+  inputs: {
+    value: { kind: 'data', type: 'float', default: 0 }
+  },
+  outputs: {
+    result: { kind: 'data', type: 'float' }
+  }
+} as const satisfies NodeDefinition;
+
+export function execute(context: NodeExecutionContext<typeof definition>) {
+  context.outputs.result.set(context.inputs.value);
+}
+`;
+}
+
+// server/src/serve/command.ts
+import fs12 from "node:fs";
+import path12 from "node:path";
+import { spawn as spawn3 } from "node:child_process";
+
+// server/src/serve/files.ts
+import fs11 from "node:fs";
+import os3 from "node:os";
+import path10 from "node:path";
+import { createHash as createHash2 } from "node:crypto";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+function serveRoot() {
+  return process.env.CASCADE_SERVE_DIR ?? path10.join(os3.homedir(), ".cascade", "serve");
+}
+function serviceId(projectRoot) {
+  const name = path10.basename(projectRoot).toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "project";
+  const hash = createHash2("sha256").update(path10.resolve(projectRoot)).digest("hex").slice(0, 8);
+  return `${name}-${hash}`;
+}
+function servicePaths(projectRoot) {
+  return pathsForId(serviceId(projectRoot));
+}
+function pathsForId(id) {
+  const dir = path10.join(serveRoot(), id);
+  return {
+    id,
+    dir,
+    lock: path10.join(dir, "serve.lock"),
+    record: path10.join(dir, "serve.json"),
+    server: path10.join(dir, "server.json"),
+    options: path10.join(dir, "options.json"),
+    log: path10.join(dir, "studio.log")
+  };
+}
+function listServiceIds() {
+  try {
+    return fs11.readdirSync(serveRoot(), { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+  } catch {
+    return [];
+  }
+}
+function readJson(file) {
+  try {
+    return JSON.parse(fs11.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function writeJsonAtomic(file, value) {
+  fs11.mkdirSync(path10.dirname(file), { recursive: true });
+  writeFileAtomicSync(file, JSON.stringify(value, null, 2) + "\n");
+}
+function removeFile(file) {
+  try {
+    fs11.unlinkSync(file);
+  } catch {
+  }
+}
+function isAlive(pid) {
+  if (!pid || !Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+}
+var AlreadyRunningError = class extends Error {
+  constructor(pid) {
+    super(`already running (pid ${pid})`);
+    this.pid = pid;
+  }
+};
+function acquireLock(lockFile, pid = process.pid) {
+  fs11.mkdirSync(path10.dirname(lockFile), { recursive: true });
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const fd = fs11.openSync(lockFile, "wx");
+      fs11.writeSync(fd, `${pid}
+`);
+      fs11.closeSync(fd);
+      return;
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      const holder = readLockPid(lockFile);
+      if (holder !== null && holder !== pid && isAlive(holder)) throw new AlreadyRunningError(holder);
+      removeFile(lockFile);
+    }
+  }
+  throw new Error(`could not take the lock at ${lockFile}`);
+}
+function readLockPid(lockFile) {
+  try {
+    const pid = Number.parseInt(fs11.readFileSync(lockFile, "utf8").trim(), 10);
+    return Number.isInteger(pid) ? pid : null;
+  } catch {
+    return null;
+  }
+}
+function releaseLock(lockFile, pid = process.pid) {
+  if (readLockPid(lockFile) === pid) removeFile(lockFile);
+}
+function tailLines(file, count) {
+  let fd;
+  try {
+    fd = fs11.openSync(file, "r");
+  } catch {
+    return [];
+  }
+  try {
+    const size = fs11.fstatSync(fd).size;
+    const length = Math.min(size, Math.max(4096, count * 400));
+    const buffer = Buffer.alloc(length);
+    fs11.readSync(fd, buffer, 0, length, size - length);
+    const lines = buffer.toString("utf8").split("\n");
+    if (lines[lines.length - 1] === "") lines.pop();
+    return lines.slice(-count);
+  } finally {
+    fs11.closeSync(fd);
+  }
+}
+function rotateLog(file, maxBytes = 10 * 1024 * 1024) {
+  try {
+    if (fs11.statSync(file).size > maxBytes) fs11.renameSync(file, `${file}.1`);
+  } catch {
+  }
+}
+function cascadeVersion() {
+  let directory = path10.dirname(fileURLToPath2(import.meta.url));
+  for (let depth = 0; depth < 6; depth++) {
+    const manifest = readJson(path10.join(directory, "package.json"));
+    if (manifest?.name === "@field/cascade" && manifest.version) return manifest.version;
+    directory = path10.dirname(directory);
+  }
+  return "unknown";
+}
+
+// server/src/serve/launchd.ts
+import os4 from "node:os";
+import path11 from "node:path";
+import { execFileSync } from "node:child_process";
+function launchdLabel(id) {
+  return `io.field.cascade.${id}`;
+}
+function launchAgentsDir() {
+  return process.env.CASCADE_LAUNCH_AGENTS_DIR ?? path11.join(os4.homedir(), "Library", "LaunchAgents");
+}
+function plistPath(label) {
+  return path11.join(launchAgentsDir(), `${label}.plist`);
+}
+function renderPlist(job) {
+  const string = (value) => `<string>${escapeXml(value)}</string>`;
+  const env = Object.entries(job.environment).map(([key2, value]) => `      <key>${escapeXml(key2)}</key>
+      ${string(value)}`).join("\n");
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>Label</key>
+    ${string(job.label)}
+    <key>ProgramArguments</key>
+    <array>
+${job.programArguments.map((argument) => `      ${string(argument)}`).join("\n")}
+    </array>
+    <key>WorkingDirectory</key>
+    ${string(job.workingDirectory)}
+    <key>EnvironmentVariables</key>
+    <dict>
+${env}
+    </dict>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <dict>
+      <key>SuccessfulExit</key>
+      <false/>
+    </dict>
+    <key>StandardOutPath</key>
+    ${string(job.logFile)}
+    <key>StandardErrorPath</key>
+    ${string(job.logFile)}
+  </dict>
+</plist>
+`;
+}
+function escapeXml(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function guiDomain() {
+  return `gui/${process.getuid?.() ?? os4.userInfo().uid}`;
+}
+function launchctl(...args) {
+  try {
+    const output = execFileSync("launchctl", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+    return { ok: true, output };
+  } catch (error) {
+    const failure = error;
+    return { ok: false, output: (failure.stderr || failure.message).trim() };
+  }
+}
+
+// server/src/serve/supervisor.ts
+import { spawn as spawn2 } from "node:child_process";
+var MAX_BACKOFF_MS = 3e4;
+function runSupervisor(config) {
+  const { paths } = config;
+  const maxCrashes = config.maxCrashes ?? 5;
+  const crashWindowMs = config.crashWindowMs ?? 6e4;
+  const stopGraceMs = config.stopGraceMs ?? 8e3;
+  const log = config.log ?? ((message2) => console.log(`${(/* @__PURE__ */ new Date()).toISOString()} [serve] ${message2}`));
+  acquireLock(paths.lock);
+  removeFile(paths.server);
+  let record = {
+    pid: process.pid,
+    project: config.project,
+    id: paths.id,
+    options: config.options,
+    manager: config.manager,
+    version: config.version,
+    startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    logFile: paths.log,
+    serverPid: null,
+    serverStartedAt: null,
+    restarts: 0,
+    lastExit: null
+  };
+  const save = (next) => {
+    record = { ...record, ...next };
+    writeJsonAtomic(paths.record, record);
+  };
+  save({});
+  writeJsonAtomic(paths.options, config.options);
+  return new Promise((resolve) => {
+    let child = null;
+    let stopping = false;
+    let restartTimer = null;
+    const crashes = [];
+    const startChild = () => {
+      const proc = spawn2(config.server.command, [...config.server.args], {
+        cwd: config.project,
+        env: { ...process.env, CASCADE_SERVE_STATE: paths.server },
+        stdio: ["ignore", "inherit", "inherit"],
+        detached: true
+        // its own process group, so stop can take its workers with it
+      });
+      child = proc;
+      log(`started Studio (pid ${proc.pid}) for ${config.project}`);
+      save({ serverPid: proc.pid ?? null, serverStartedAt: (/* @__PURE__ */ new Date()).toISOString() });
+      proc.once("error", (error) => log(`could not start Studio: ${error.message}`));
+      proc.once("exit", (code, signal) => onChildExit(proc, code, signal));
+    };
+    const onChildExit = (proc, code, signal) => {
+      if (child !== proc) return;
+      child = null;
+      killGroup(proc.pid, "SIGKILL");
+      killWorkers();
+      save({ serverPid: null, lastExit: { code, signal, at: (/* @__PURE__ */ new Date()).toISOString() } });
+      if (stopping) return finish(0);
+      const now = Date.now();
+      crashes.push(now);
+      while (crashes.length && now - crashes[0] > crashWindowMs) crashes.shift();
+      if (crashes.length >= maxCrashes) {
+        log(`Studio exited ${crashes.length} times in ${Math.round(crashWindowMs / 1e3)}s (last: ${signal ?? `code ${code}`}); giving up \u2014 see this log`);
+        return finish(1);
+      }
+      const delay = Math.min(1e3 * 2 ** (crashes.length - 1), MAX_BACKOFF_MS);
+      log(`Studio exited (${signal ?? `code ${code}`}); restarting in ${delay / 1e3}s`);
+      save({ restarts: record.restarts + 1 });
+      restartTimer = setTimeout(() => {
+        restartTimer = null;
+        if (!stopping) startChild();
+      }, delay);
+    };
+    const stop2 = (signal) => {
+      if (stopping) return;
+      stopping = true;
+      log(`${signal}: stopping Studio`);
+      if (restartTimer) {
+        clearTimeout(restartTimer);
+        restartTimer = null;
+      }
+      const proc = child;
+      if (!proc) return finish(0);
+      killGroup(proc.pid, "SIGTERM");
+      const force = setTimeout(() => {
+        log(`Studio did not stop within ${stopGraceMs / 1e3}s; killing its process group`);
+        killGroup(proc.pid, "SIGKILL");
+      }, stopGraceMs);
+      proc.once("exit", () => clearTimeout(force));
+    };
+    const killWorkers = () => {
+      const state = readJson(paths.server);
+      for (const worker of state?.workers ?? []) {
+        if (worker.pid && isAlive(worker.pid)) {
+          try {
+            process.kill(worker.pid, "SIGKILL");
+          } catch {
+          }
+        }
+      }
+      removeFile(paths.server);
+    };
+    const onTerm = () => stop2("SIGTERM");
+    const onInt = () => stop2("SIGINT");
+    const onHup = () => {
+    };
+    process.on("SIGTERM", onTerm);
+    process.on("SIGINT", onInt);
+    process.on("SIGHUP", onHup);
+    let finished = false;
+    const finish = (code) => {
+      if (finished) return;
+      finished = true;
+      process.off("SIGTERM", onTerm);
+      process.off("SIGINT", onInt);
+      process.off("SIGHUP", onHup);
+      removeFile(paths.record);
+      removeFile(paths.server);
+      releaseLock(paths.lock);
+      log(code === 0 ? "stopped" : "supervisor exiting after repeated crashes");
+      resolve(code);
+    };
+    startChild();
+  });
+}
+function killGroup(pid, signal) {
+  if (!pid) return;
+  try {
+    process.kill(-pid, signal);
+  } catch {
+    try {
+      process.kill(pid, signal);
+    } catch {
+    }
+  }
+}
+
+// server/src/serve/command.ts
+var SERVE_USAGE = `Usage:
+  cascade serve start   [project] [--port N] [--host H] [--fallback-host H]... [--trusted-host H]...
+  cascade serve stop    [project]
+  cascade serve restart [project] [same options as start]
+  cascade serve status  [project] [--all] [--json]
+  cascade serve logs    [project] [-n LINES] [-f]
+  cascade serve install [project] [options] [--no-load] [--print]   (macOS launchd)
+  cascade serve uninstall [project]
+
+Options given to start/restart are remembered: a later start without them reuses them.
+State and logs live in ~/.cascade/serve/<project>-<hash>/ (override with CASCADE_SERVE_DIR).`;
+var DEFAULT_PORT = 3030;
+function parseServeArgs(args) {
+  const [action = "status", ...rest] = args;
+  const positional = [];
+  const fallbackHosts = [];
+  const trustedHosts = [];
+  let port;
+  let host;
+  let json6 = false, all = false, follow = false, load = true, print = false;
+  let lines = 50;
+  let waitMs = 3e4;
+  for (let index = 0; index < rest.length; index++) {
+    const argument = rest[index];
+    const [name, inline] = argument.startsWith("--") ? argument.split("=", 2) : [argument, void 0];
+    const value = () => {
+      const next = inline ?? rest[++index];
+      if (next === void 0 || next.startsWith("-")) throw new Error(`${name} requires a value`);
+      return next;
+    };
+    switch (name) {
+      case "--json":
+        json6 = true;
+        break;
+      case "--all":
+        all = true;
+        break;
+      case "-f":
+      case "--follow":
+        follow = true;
+        break;
+      case "--no-load":
+        load = false;
+        break;
+      case "--print":
+        print = true;
+        break;
+      case "--no-open":
+        break;
+      // serve never opens a browser; accepted for muscle memory
+      case "-n":
+      case "--lines":
+        lines = positiveInteger(value(), name);
+        break;
+      case "--wait":
+        waitMs = positiveInteger(value(), name) * 1e3;
+        break;
+      case "--port":
+        port = positiveInteger(value(), name);
+        break;
+      case "--host":
+        host = value();
+        break;
+      case "--fallback-host":
+        fallbackHosts.push(value());
+        break;
+      case "--trusted-host":
+        trustedHosts.push(value());
+        break;
+      default:
+        if (argument.startsWith("-")) throw new Error(`unknown serve option: ${argument}`);
+        positional.push(argument);
+    }
+  }
+  if (positional.length > 1) throw new Error(`serve ${action} takes at most one project, got: ${positional.join(" ")}`);
+  if (port !== void 0 && port > 65535) throw new Error("--port must be between 1 and 65535");
+  const overrides = {
+    ...port === void 0 ? {} : { port },
+    ...host === void 0 ? {} : { host },
+    ...fallbackHosts.length ? { fallbackHosts } : {},
+    ...trustedHosts.length ? { trustedHosts } : {}
+  };
+  return { action, project: positional[0], overrides, json: json6, all, follow, lines, load, print, waitMs };
+}
+function positiveInteger(raw, name) {
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 1) throw new Error(`${name} must be a positive integer`);
+  return value;
+}
+function studioArgs(project, options) {
+  return [
+    project,
+    "--no-open",
+    "--port",
+    String(options.port),
+    ...options.host ? ["--host", options.host] : [],
+    ...options.fallbackHosts.flatMap((host) => ["--fallback-host", host]),
+    ...options.trustedHosts.flatMap((host) => ["--trusted-host", host])
+  ];
+}
+function optionFlags(options) {
+  return studioArgs("", options).slice(2);
+}
+function cliInvocation() {
+  const script = process.argv[1];
+  return { command: process.execPath, args: [...process.execArgv, script ? fs12.realpathSync(script) : script] };
+}
+function resolveOptions(paths, overrides) {
+  const saved = readJson(paths.options) ?? {};
+  const options = {
+    port: overrides.port ?? saved.port ?? DEFAULT_PORT,
+    fallbackHosts: overrides.fallbackHosts ?? saved.fallbackHosts ?? [],
+    trustedHosts: overrides.trustedHosts ?? saved.trustedHosts ?? [],
+    ...overrides.host ?? saved.host ? { host: overrides.host ?? saved.host } : {}
+  };
+  parseStudioArgs(studioArgs(".", options).slice(1));
+  return options;
+}
+async function runServeCommand(args, resolveProject) {
+  const parsed = parseServeArgs(args);
+  const projectFor = () => resolveProject(parsed.project ?? ".");
+  switch (parsed.action) {
+    case "run": {
+      const project = projectFor();
+      const paths = servicePaths(project);
+      const options = resolveOptions(paths, parsed.overrides);
+      const cli = cliInvocation();
+      try {
+        return await runSupervisor({
+          project,
+          paths,
+          options,
+          server: { command: cli.command, args: [...cli.args, ...studioArgs(project, options)] },
+          manager: process.env.CASCADE_SERVE_MANAGER === "launchd" ? "launchd" : "cascade",
+          version: cascadeVersion()
+        });
+      } catch (error) {
+        if (error instanceof AlreadyRunningError) {
+          console.error(`[cascade] ${project} is ${error.message}`);
+          return 1;
+        }
+        throw error;
+      }
+    }
+    case "start":
+      return start(projectFor(), parsed);
+    case "stop":
+      return stop(projectFor());
+    case "restart": {
+      const project = projectFor();
+      const paths = servicePaths(project);
+      if (fs12.existsSync(plistPath(launchdLabel(paths.id))) && Object.keys(parsed.overrides).length === 0) {
+        return restartLaunchd(project, paths, parsed.waitMs, parsed.json);
+      }
+      const stopped = await stop(project);
+      if (stopped !== 0) return stopped;
+      return start(project, parsed);
+    }
+    case "status": {
+      if (parsed.all) return printStatuses(listServiceIds(), parsed);
+      if (parsed.project) return printStatuses([servicePaths(projectFor()).id], parsed);
+      let here = null;
+      try {
+        here = servicePaths(projectFor());
+      } catch {
+      }
+      if (here && (fs12.existsSync(here.record) || fs12.existsSync(here.lock))) return printStatuses([here.id], parsed);
+      return printStatuses(listServiceIds(), { ...parsed, all: true });
+    }
+    case "logs":
+      return logs(projectFor(), parsed);
+    case "install":
+      return install(projectFor(), parsed);
+    case "uninstall":
+      return uninstall(projectFor());
+    case "help":
+    case "--help":
+    case "-h":
+      console.log(SERVE_USAGE);
+      return 0;
+    default:
+      console.error(`unknown serve command: ${parsed.action}
+
+${SERVE_USAGE}`);
+      return 1;
+  }
+}
+async function start(project, parsed) {
+  const paths = servicePaths(project);
+  if (fs12.existsSync(plistPath(launchdLabel(paths.id)))) return startLaunchd(project, paths, parsed.waitMs, parsed.json);
+  const running = supervisorPid(paths);
+  if (running) {
+    console.log(`[cascade] already running (pid ${running}); use \`cascade serve restart\` to restart`);
+    printStatus(statusOf(paths), parsed.json);
+    return 0;
+  }
+  const options = resolveOptions(paths, parsed.overrides);
+  fs12.mkdirSync(paths.dir, { recursive: true });
+  rotateLog(paths.log);
+  const logFd = fs12.openSync(paths.log, "a");
+  const cli = cliInvocation();
+  const supervisor = spawn3(cli.command, [...cli.args, "serve", "run", project, ...optionFlags(options)], {
+    cwd: project,
+    detached: true,
+    stdio: ["ignore", logFd, logFd],
+    env: { ...process.env, CASCADE_SERVE_MANAGER: "cascade" }
+  });
+  supervisor.unref();
+  fs12.closeSync(logFd);
+  const state = await waitForListening(paths, supervisor.pid ?? 0, parsed.waitMs);
+  if (!state) {
+    console.error(`[cascade] Studio did not start within ${parsed.waitMs / 1e3}s. Last log lines (${paths.log}):`);
+    for (const line of tailLines(paths.log, 20)) console.error(`  ${line}`);
+    if (supervisor.pid && isAlive(supervisor.pid)) await stop(project, true);
+    return 1;
+  }
+  printStatus(statusOf(paths), parsed.json);
+  return 0;
+}
+async function stop(project, quiet = false) {
+  const paths = servicePaths(project);
+  const label = launchdLabel(paths.id);
+  if (fs12.existsSync(plistPath(label))) {
+    const result = launchctl("bootout", `${guiDomain()}/${label}`);
+    if (!result.ok && !/No such process|Could not find|not find service/i.test(result.output)) {
+      console.error(`[cascade] launchctl bootout failed: ${result.output}`);
+    }
+  }
+  const record = readJson(paths.record);
+  const pid = supervisorPid(paths);
+  if (!pid) {
+    cleanup(paths, record);
+    if (!quiet) console.log(`[cascade] not running (${project})`);
+    return 0;
+  }
+  try {
+    process.kill(pid, "SIGTERM");
+  } catch {
+  }
+  const exited = await waitFor(() => !isAlive(pid), 15e3);
+  if (!exited) {
+    console.warn(`[cascade] supervisor ${pid} did not stop in 15s; killing it and its Studio`);
+    try {
+      process.kill(pid, "SIGKILL");
+    } catch {
+    }
+  }
+  cleanup(paths, record);
+  if (!quiet) console.log(`[cascade] stopped ${project} (was pid ${pid})`);
+  return 0;
+}
+function cleanup(paths, record) {
+  const state = readJson(paths.server);
+  const serverPid = state?.pid ?? record?.serverPid ?? null;
+  if (serverPid && isAlive(serverPid)) {
+    try {
+      process.kill(-serverPid, "SIGKILL");
+    } catch {
+      try {
+        process.kill(serverPid, "SIGKILL");
+      } catch {
+      }
+    }
+  }
+  for (const worker of state?.workers ?? []) {
+    if (worker.pid && isAlive(worker.pid)) {
+      try {
+        process.kill(worker.pid, "SIGKILL");
+      } catch {
+      }
+    }
+  }
+  const lockHolder = readLockPid(paths.lock);
+  if (lockHolder !== null && !isAlive(lockHolder)) releaseLock(paths.lock, lockHolder);
+  if (!supervisorPid(paths)) {
+    removeFile(paths.record);
+    removeFile(paths.server);
+  }
+}
+function supervisorPid(paths) {
+  for (const pid of [readLockPid(paths.lock), readJson(paths.record)?.pid]) {
+    if (pid && isAlive(pid)) return pid;
+  }
+  return null;
+}
+async function waitForListening(paths, supervisor, timeoutMs, notServerPid) {
+  let state = null;
+  await waitFor(() => {
+    state = readJson(paths.server);
+    const listening = !!state?.binding.host && isAlive(state.pid) && state.pid !== notServerPid;
+    return listening || supervisor > 0 && !isAlive(supervisor) && !readLockPid(paths.lock);
+  }, timeoutMs);
+  const final = state;
+  return final && final.binding.host && isAlive(final.pid) && final.pid !== notServerPid ? final : null;
+}
+async function waitFor(condition, timeoutMs, intervalMs = 200) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (condition()) return true;
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+  return condition();
+}
+function statusOf(paths) {
+  const record = readJson(paths.record);
+  const pid = supervisorPid(paths);
+  const state = pid ? readJson(paths.server) : null;
+  const serverAlive = !!state && isAlive(state.pid);
+  const now = Date.now();
+  const seconds = (iso) => iso ? Math.round((now - Date.parse(iso)) / 1e3) : null;
+  const binding = serverAlive ? state.binding : null;
+  const workers = serverAlive ? state.workers : [];
+  const workerState = workers.some((worker) => worker.state === "busy") ? "busy" : workers.some((worker) => worker.state === "idle") ? "idle" : workers.length ? "stopped" : "none";
+  return {
+    project: record?.project ?? state?.project ?? null,
+    id: paths.id,
+    running: !!pid && serverAlive && !!binding?.host,
+    manager: pid ? record?.manager ?? null : null,
+    launchdInstalled: fs12.existsSync(plistPath(launchdLabel(paths.id))),
+    pid,
+    serverPid: serverAlive ? state.pid : null,
+    host: binding?.host ?? null,
+    port: binding?.port ?? (pid ? record?.options.port ?? null : null),
+    preferredHost: binding?.preferredHost ?? (pid ? record?.options.host ?? null : null),
+    fallback: binding?.fallback ?? false,
+    fallbackReason: binding?.fallback ? binding.reason : null,
+    url: binding?.host ? `http://${authority(binding.host, binding.port)}` : null,
+    uptimeSeconds: pid ? seconds(record?.startedAt) : null,
+    serverUptimeSeconds: serverAlive ? seconds(state.startedAt) : null,
+    version: serverAlive ? state.version : pid ? record?.version ?? null : null,
+    workerState,
+    workers,
+    restarts: pid ? record?.restarts ?? 0 : 0,
+    lastExit: record?.lastExit ?? null,
+    heartbeatAgeSeconds: serverAlive ? seconds(state.heartbeatAt) : null,
+    logFile: paths.log
+  };
+}
+function printStatuses(ids, parsed) {
+  const statuses = ids.map((id) => statusOf(pathsForId(id)));
+  const shown = parsed.all ? statuses.filter((entry) => entry.running || entry.pid) : statuses;
+  if (parsed.json) {
+    console.log(JSON.stringify(parsed.all ? shown : shown[0] ?? null, null, 2));
+  } else if (shown.length === 0) {
+    console.log("[cascade] no Studio is being served");
+  } else {
+    for (const entry of shown) printStatus(entry, false);
+  }
+  return 0;
+}
+function printStatus(entry, json6) {
+  if (json6) {
+    console.log(JSON.stringify(entry, null, 2));
+    return;
+  }
+  const lines = [`${entry.project ?? entry.id}`];
+  if (!entry.pid) {
+    lines.push("  stopped");
+  } else {
+    lines.push(`  ${entry.running ? "running" : "starting"}  ${entry.url ?? "(not listening yet)"}${entry.fallback ? `  FALLBACK \u2014 ${entry.preferredHost} unavailable: ${entry.fallbackReason}` : ""}`);
+    lines.push(`  pid ${entry.pid} (supervisor, ${entry.manager}), Studio ${entry.serverPid ?? "-"}, up ${duration(entry.uptimeSeconds)}, v${entry.version ?? "?"}`);
+    lines.push(`  python worker: ${entry.workerState}${entry.workers.length ? ` (${entry.workers.map((worker) => `${worker.pid ?? "-"} ${worker.state}`).join(", ")})` : ""}`);
+    if (entry.restarts) lines.push(`  restarts: ${entry.restarts}${entry.lastExit ? `, last exit ${entry.lastExit.signal ?? `code ${entry.lastExit.code}`} at ${entry.lastExit.at}` : ""}`);
+  }
+  lines.push(`  log: ${entry.logFile}${entry.launchdInstalled ? "  (launchd job installed)" : ""}`);
+  console.log(lines.join("\n"));
+}
+function duration(seconds) {
+  if (seconds === null) return "?";
+  if (seconds < 60) return `${seconds}s`;
+  if (seconds < 3600) return `${Math.floor(seconds / 60)}m`;
+  return `${Math.floor(seconds / 3600)}h${Math.floor(seconds % 3600 / 60)}m`;
+}
+async function logs(project, parsed) {
+  const paths = servicePaths(project);
+  if (!fs12.existsSync(paths.log)) {
+    console.error(`[cascade] no log yet at ${paths.log}`);
+    return 1;
+  }
+  if (!parsed.follow) {
+    for (const line of tailLines(paths.log, parsed.lines)) console.log(line);
+    return 0;
+  }
+  return new Promise((resolve) => {
+    const tail = spawn3("tail", ["-n", String(parsed.lines), "-F", paths.log], { stdio: "inherit" });
+    tail.once("exit", (code) => resolve(code ?? 0));
+  });
+}
+async function install(project, parsed) {
+  const paths = servicePaths(project);
+  const options = resolveOptions(paths, parsed.overrides);
+  const cli = cliInvocation();
+  const label = launchdLabel(paths.id);
+  const plist = renderPlist({
+    label,
+    programArguments: [cli.command, ...cli.args, "serve", "run", project, ...optionFlags(options)],
+    workingDirectory: project,
+    logFile: paths.log,
+    environment: {
+      PATH: process.env.PATH ?? "/usr/bin:/bin",
+      HOME: process.env.HOME ?? "",
+      CASCADE_SERVE_MANAGER: "launchd",
+      ...process.env.CASCADE_SERVE_DIR ? { CASCADE_SERVE_DIR: process.env.CASCADE_SERVE_DIR } : {}
+    }
+  });
+  if (parsed.print) {
+    process.stdout.write(plist);
+    return 0;
+  }
+  if (process.platform !== "darwin") {
+    console.error("[cascade] serve install writes a launchd job and is macOS only; use --print to see it");
+    return 1;
+  }
+  const file = plistPath(label);
+  const wasInstalled = fs12.existsSync(file);
+  if (wasInstalled) launchctl("bootout", `${guiDomain()}/${label}`);
+  if (supervisorPid(paths)) await stop(project, true);
+  fs12.mkdirSync(paths.dir, { recursive: true });
+  fs12.mkdirSync(path12.dirname(file), { recursive: true });
+  fs12.writeFileSync(file, plist);
+  fs12.writeFileSync(paths.options, JSON.stringify(options, null, 2) + "\n");
+  console.log(`[cascade] wrote ${file}`);
+  if (!parsed.load) {
+    console.log(`[cascade] not loaded; run: launchctl bootstrap ${guiDomain()} ${JSON.stringify(file)}`);
+    return 0;
+  }
+  return startLaunchd(project, paths, parsed.waitMs, parsed.json);
+}
+async function uninstall(project) {
+  const paths = servicePaths(project);
+  const label = launchdLabel(paths.id);
+  const file = plistPath(label);
+  if (!fs12.existsSync(file)) {
+    console.log(`[cascade] no launchd job installed for ${project}`);
+    return 0;
+  }
+  await stop(project, true);
+  fs12.unlinkSync(file);
+  console.log(`[cascade] removed ${file}; Studio is stopped`);
+  return 0;
+}
+async function startLaunchd(project, paths, waitMs, json6) {
+  const label = launchdLabel(paths.id);
+  if (!supervisorPid(paths)) {
+    const result = launchctl("bootstrap", guiDomain(), plistPath(label));
+    if (!result.ok) {
+      const kick = launchctl("kickstart", `${guiDomain()}/${label}`);
+      if (!kick.ok) {
+        console.error(`[cascade] launchctl could not start ${label}: ${result.output}; ${kick.output}`);
+        return 1;
+      }
+    }
+  }
+  const state = await waitForListening(paths, 0, waitMs);
+  if (!state) {
+    console.error(`[cascade] launchd job ${label} did not report listening within ${waitMs / 1e3}s. Last log lines:`);
+    for (const line of tailLines(paths.log, 20)) console.error(`  ${line}`);
+    return 1;
+  }
+  printStatus(statusOf(paths), json6);
+  return 0;
+}
+async function restartLaunchd(project, paths, waitMs, json6) {
+  const label = launchdLabel(paths.id);
+  const previous = readJson(paths.server)?.pid;
+  const result = launchctl("kickstart", "-k", `${guiDomain()}/${label}`);
+  if (!result.ok) return startLaunchd(project, paths, waitMs, json6);
+  const state = await waitForListening(paths, 0, waitMs, previous);
+  if (!state) {
+    console.error(`[cascade] ${label} did not come back within ${waitMs / 1e3}s; see ${paths.log}`);
+    return 1;
+  }
+  printStatus(statusOf(paths), json6);
+  return 0;
+}
+
+// server/src/serve/state.ts
+function startStateReporter(file, snapshot, intervalMs = 2e3) {
+  const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const update = () => {
+    try {
+      writeJsonAtomic(file, { pid: process.pid, startedAt, heartbeatAt: (/* @__PURE__ */ new Date()).toISOString(), ...snapshot() });
+    } catch (error) {
+      console.warn(`[cascade] could not write serve state to ${file}: ${error.message}`);
+    }
+  };
+  update();
+  const timer = setInterval(update, intervalMs);
+  timer.unref();
+  return {
+    update,
+    stop() {
+      clearInterval(timer);
+      removeFile(file);
+    }
+  };
+}
+
+// server/src/cliCommands.ts
+function parseStudioArgs(args) {
+  const positional = [];
+  const trustedHosts = [];
+  const fallbackHosts = [];
+  let noOpen = false;
+  let host;
+  let port;
+  for (let index = 0; index < args.length; index++) {
+    const argument = args[index];
+    if (argument === "--no-open") {
+      noOpen = true;
+      continue;
+    }
+    const [name, inlineValue] = argument.startsWith("--") ? argument.split("=", 2) : [argument, void 0];
+    if (name === "--host" || name === "--port" || name === "--trusted-host" || name === "--fallback-host") {
+      const value = inlineValue ?? args[++index];
+      if (!value || value.startsWith("--")) throw new Error(`${name} requires a value`);
+      if (name === "--host") host = value;
+      else if (name === "--fallback-host") {
+        if (isWildcardHost(value)) throw new Error("--fallback-host must be a specific address, not a wildcard");
+        fallbackHosts.push(value);
+      } else if (name === "--trusted-host") {
+        trustedAuthority(value, 1);
+        trustedHosts.push(value);
+      } else {
+        port = Number(value);
+        if (!Number.isInteger(port) || port < 1 || port > 65535) {
+          throw new Error("--port must be an integer between 1 and 65535");
+        }
+      }
+      continue;
+    }
+    if (argument.startsWith("-")) throw new Error(`unknown option: ${argument}`);
+    positional.push(argument);
+  }
+  if (trustedHosts.length > 0 && !host) {
+    throw new Error("--trusted-host requires an explicit --host bind address, loopback or otherwise");
+  }
+  if (host && !isLoopbackHost(host)) {
+    if (host === "0.0.0.0" || host === "::" || host === "[::]") {
+      throw new Error("remote Studio must bind a specific hostname or VPN/interface address, not a wildcard address");
+    }
+    if (trustedHosts.length === 0) trustedHosts.push(host);
+  }
+  return {
+    positional,
+    noOpen,
+    ...host === void 0 ? {} : { host },
+    ...port === void 0 ? {} : { port },
+    trustedHosts,
+    ...fallbackHosts.length ? { fallbackHosts } : {}
+  };
+}
+async function runStudioCli(args) {
+  if (args[0] === "serve") {
+    process.exitCode = await runServeCommand(args.slice(1), resolveProjectTarget);
+    return;
+  }
+  const { noOpen, positional, host, port, trustedHosts, fallbackHosts } = parseStudioArgs(args);
+  const config = loadConfig();
+  if (positional[0] === "projects") {
+    if (positional[1]) {
+      saveConfig({ projectsRoot: path13.resolve(positional[1].replace(/^~(?=\/|$)/, process.env.HOME ?? "~")) });
+      console.log(`[cascade] projects root set to ${loadConfig().projectsRoot} (${configPath()})`);
+    } else console.log(loadConfig().projectsRoot);
+    return;
+  }
+  if (positional[0] === "new") {
+    if (!positional[1]) throw new Error("usage: cascade new <name>");
+    const directory = createProject(config.projectsRoot, positional[1]);
+    console.log(`[cascade] created ${directory}`);
+    positional[0] = directory;
+  }
+  if (positional[0] === "node") {
+    if (!positional[1]) throw new Error("usage: cascade node <Name> [project-directory]");
+    const project2 = ProjectRoot.fromArg(positional[2] ?? ".");
+    const directory = createNode(project2.root, positional[1]);
+    console.log(`[cascade] created project.${positional[1]} at ${directory}`);
+    return;
+  }
+  const project = ProjectRoot.fromArg(resolveProjectTarget(positional[0] ?? "."));
+  const envFallbacks = (process.env.CASCADE_FALLBACK_HOSTS ?? "").split(",").map((value) => value.trim()).filter(Boolean);
+  const server = startServer(project, {
+    host,
+    port,
+    trustedHosts,
+    ...fallbackHosts || envFallbacks.length ? { fallbackHosts: fallbackHosts ?? envFallbacks } : {}
+  });
+  server.on("error", (error) => {
+    if (isHostUnavailable(error)) return;
+    console.error(`[cascade] Studio could not listen: ${error.message}`);
+    process.exit(1);
+  });
+  const stateFile = process.env.CASCADE_SERVE_STATE;
+  const reporter = stateFile ? startStateReporter(stateFile, () => ({
+    project: project.root,
+    version: cascadeVersion(),
+    binding: server.binding.state(),
+    workers: pythonWorkerStatuses()
+  })) : null;
+  let stopping = false;
+  const shutdown = (signal) => {
+    if (stopping) return;
+    stopping = true;
+    console.log(`[cascade] ${signal}: stopping Studio`);
+    server.binding.stop();
+    shutdownAllPythonWorkers();
+    reporter?.stop();
+    server.close(() => process.exit(0));
+    server.closeAllConnections?.();
+    setTimeout(() => process.exit(0), 3e3).unref();
+  };
+  process.once("SIGTERM", () => shutdown("SIGTERM"));
+  process.once("SIGINT", () => shutdown("SIGINT"));
+  server.binding.ready.then(async (bound) => {
+    reporter?.update();
+    const defaultGraph = await project.resolveDefaultGraph();
+    console.log(defaultGraph ? `\u{1F4C4} Opening ${defaultGraph}` : "\u{1F4C4} No default graph (name one explicitly, or add index.cascade) \u2014 starting empty");
+    const port2 = bound.port;
+    const browserHost = bound.fallback ? isLoopbackHost(bound.host) ? "localhost" : bound.host : trustedHosts[0] ?? (host && !isLoopbackHost(host) ? host : "localhost");
+    const url = `http://${trustedAuthority(browserHost, port2)}`;
+    if (!noOpen) {
+      const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+      execFile3(opener, [url], (error) => {
+        if (error) console.warn(`[cascade] couldn't auto-open a browser (${error.message}) \u2014 open ${url} yourself.`);
+      });
+    }
+  }, () => {
+  });
+}
+function resolveProjectTarget(target) {
+  if (fs13.existsSync(path13.resolve(target))) return path13.resolve(target);
+  const projectTarget = path13.resolve(loadConfig().projectsRoot, target);
+  return fs13.existsSync(projectTarget) ? projectTarget : path13.resolve(target);
+}
+export {
+  parseStudioArgs,
+  resolveProjectTarget,
+  runStudioCli
+};
+//# sourceMappingURL=cliCommands-UQSFGEHF.js.map