@codeyam-editor/codeyam-editor 0.1.0 → 0.1.2

package/npm/container.js

@@ -8,12 +8,31 @@ const path = require("path");
  * inline monitoring UI at http://localhost:14199.
  */
 
-const { ensureServer, rootDir } = require("./utils");
+const {
+  ensureServer,
+  rootDir,
+  killChildProcess,
+  readMergedEditorConfig,
+  resolveLauncherPort,
+} = require("./utils");
 const { open } = require("./open");
 
-const PORT = 14199;
-
+/**
+ * npm wrapper entry point for the container binary: ensures the Rust
+ * editor server is running and opens the container monitoring UI in
+ * a browser.
+ */
 async function main() {
+  // Same resolution order as the editor launcher: env var
+  // (CODEYAM_EDITOR_PORT) → merged editor.json + editor.local.json
+  // (proxy.controlPort) → hard fallback (14199).
+  const merged = readMergedEditorConfig(rootDir);
+  const PORT = resolveLauncherPort(
+    process.env.CODEYAM_EDITOR_PORT,
+    merged.proxy && merged.proxy.controlPort,
+    14199,
+  );
+
   const serverChild = await ensureServer(PORT);
   const url = `http://localhost:${PORT}`;
   console.error(`Container UI: ${url}`);
@@ -23,9 +42,13 @@ async function main() {
 
   process.on("SIGINT", () => {
     clearInterval(keepAlive);
-    if (serverChild) serverChild.kill("SIGINT");
+    killChildProcess(serverChild);
     process.exit(0);
   });
 }
 
-main();
+module.exports = { main };
+
+if (require.main === module) {
+  main();
+}

package/npm/editor-dev.js

@@ -0,0 +1,378 @@
+#!/usr/bin/env node
+
+/**
+ * Development CLI for running the codeyam-editor against any project.
+ *
+ * Two modes:
+ *
+ *   Launcher — no subcommand (or --restart): builds the Rust binary and UI
+ *   from the editor repo, starts the server, waits for readiness, opens browser.
+ *     codeyam-editor-dev
+ *     codeyam-editor-dev --restart
+ *
+ *   Passthrough — any subcommand (start, init, editor, ...): rebuilds the
+ *   Rust binary, then forwards args to it.
+ *     codeyam-editor-dev editor step 1
+ *     codeyam-editor-dev editor advance
+ *
+ * The wrapper is symlinked twice by scripts/bootstrap.sh:
+ *   codeyam-editor-dev → this file (preserves the -dev branding;
+ *     scaffolded content emits "codeyam-editor-dev").
+ *   codeyam-editor     → this file (shadows the canonical name on PATH
+ *     so hooks and skills that emit `codeyam-editor` still get the
+ *     auto-rebuild behavior on local dev; scaffolded content emits the
+ *     canonical "codeyam-editor").
+ * The invocation name is read from `process.argv[1]` to decide which
+ * branding the Rust binary should use via `CODEYAM_CLI`.
+ */
+
+const { execSync, spawn, spawnSync } = require("child_process");
+const path = require("path");
+const {
+  ensureServer,
+  restartServer,
+  waitForPort,
+  ensureBinary,
+  isSelfHostTarget,
+  rootDir,
+  killChildProcess,
+  readMergedEditorConfig,
+  resolveLauncherPort,
+  staleBinaryBanner,
+  enforceFreshBinary,
+} = require("./utils");
+const { open } = require("./open");
+const { classifyProject } = require("./preflight-guidance");
+const { isEmptyProjectDir } = require("./empty-project-dir");
+
+// When invoked through the `codeyam-editor-dev` symlink, tell the Rust
+// binary to emit "codeyam-editor-dev" in all scaffolded commands,
+// permissions, and installed files. When invoked through the
+// `codeyam-editor` symlink, leave CODEYAM_CLI unset so the binary
+// emits the canonical "codeyam-editor" — matching the cloud install
+// path and the new hook/skill convention. The runtime cost of the
+// rebuild-on-passthrough behavior is identical for both names.
+const invokedAs = path.basename(process.argv[1] || "");
+if (invokedAs === "codeyam-editor-dev") {
+  process.env.CODEYAM_CLI = "codeyam-editor-dev";
+}
+
+const args = process.argv.slice(2);
+const KNOWN_SUBCOMMANDS = ["start", "init", "editor"];
+
+/**
+ * Check if the first non-flag argument is a known subcommand.
+ * Accepts an explicit argv array so the helper is testable without mutating
+ * process.argv (the module-level `args` const is the production default).
+ */
+function hasSubcommand(argv = args) {
+  for (const arg of argv) {
+    if (arg.startsWith("-")) continue;
+    return KNOWN_SUBCOMMANDS.includes(arg);
+  }
+  return false;
+}
+
+/**
+ * Build the Rust binary from the editor repo. Returns true on success,
+ * false if `cargo build` failed. This function only reports the outcome —
+ * the caller decides whether a failed build is fatal (see staleBinaryBanner).
+ */
+function buildBinary() {
+  console.error("Building Rust binary...");
+  try {
+    execSync("cargo build", { stdio: "inherit", cwd: rootDir });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Decide whether the dev wrapper should rebuild the Rust binary (and the UI,
+ * for the launcher path) before forwarding to it. Pure: takes injected cwd /
+ * repoRoot / env so the four-way decision is testable without spawning cargo
+ * or reading process.env.
+ *
+ * The wrapper rebuilds in two cases:
+ *   - The target IS the editor repo itself (developing the editor on its
+ *     own checkout). This is the canonical self-host case.
+ *   - `CODEYAM_DEV_REBUILD=1` is explicitly set (the documented opt-in for
+ *     "editing the editor source while running it against an external client
+ *     project", named in editor-dev.js's earlier history).
+ *
+ * Otherwise — the common case where a developer uses the editor as a tool
+ * against their own app — the wrapper skips the rebuild entirely. The
+ * existing binary runs unchanged, and the server-side stale-binary watcher
+ * (also gated on self-host) never SIGUSR1's. The combined effect is what the
+ * plan calls out: an external-project session is never disrupted by a bare
+ * commit, a fleet rebase, or any other event that would have relinked the
+ * binary without changing what runs.
+ */
+function shouldRebuildOnPassthrough({ cwd, repoRoot, env }) {
+  if (env.CODEYAM_DEV_REBUILD === "1") return true;
+  return isSelfHostTarget(cwd, repoRoot);
+}
+
+/**
+ * Returns true when the merged project config has a non-empty start
+ * command — either at `apps[0].startCommand` (per-app, preferred) or at
+ * the top-level `startCommand` (legacy default). Mirrors the Rust
+ * `resolve_start_command` precedence in
+ * `crates/codeyam-editor/src/commands/start.rs`.
+ *
+ * When neither slot has a non-empty string, the editor server runs in
+ * "editor UI only" mode and the launcher must skip the dev-server port
+ * wait — otherwise the user stares at "Waiting for dev server on port
+ * N..." for the full 15s timeout.
+ */
+function hasStartCommand(mergedConfig) {
+  if (mergedConfig == null || typeof mergedConfig !== "object") return false;
+  const apps = Array.isArray(mergedConfig.apps) ? mergedConfig.apps : null;
+  if (apps && apps.length > 0) {
+    const cmd = apps[0] && apps[0].startCommand;
+    if (typeof cmd === "string" && cmd.trim() !== "") return true;
+  }
+  const topLevel = mergedConfig.startCommand;
+  return typeof topLevel === "string" && topLevel.trim() !== "";
+}
+
+/**
+ * Decide what the launcher should do given a `classifyProject` result.
+ * Pure — no fs, no spawn, no process.exit — so `launcherMain`'s branching
+ * is unit-testable without building a binary or spawning a server (the same
+ * policy/classification split as `classifyPortHolder` in utils.js).
+ *
+ *   modern → { action: "proceed" }                 launch as-is
+ *   none   → { action: "init" }                     greenfield: init, then launch
+ *   legacy → { action: "bail", guidance, code: 2 }  print guidance and exit
+ *
+ * Greenfield auto-inits because the dev launcher is a one-shot "build
+ * everything, run the editor against this project" tool — running it in a
+ * fresh dir should just work. Legacy bails instead: `cmd_init`'s legacy
+ * branch deliberately skips `editor.json` creation so `/codeyam-onboard`
+ * can migrate from the preserved classification, so auto-running init would
+ * strand them. The Rust-side `start_preflight` stays the safety net for
+ * direct `codeyam-editor start` calls; this launcher composes init + start.
+ */
+function planPreflightAction(classification) {
+  if (classification.kind === "legacy") {
+    return { action: "bail", guidance: classification.guidance, code: 2 };
+  }
+  if (classification.kind === "none") {
+    return { action: "init" };
+  }
+  return { action: "proceed" };
+}
+
+/**
+ * Pick the launcher's post-launch tail banner — printed right next to the
+ * `Editor UI: http://…` line where the user is actually looking, after the
+ * editor server is up. Pure (no fs, no spawn) so the three-arm decision is
+ * unit-testable without spawning a binary, mirroring `planPreflightAction`.
+ *
+ * Skill assumption: /codeyam-editor scaffolds a project from scratch;
+ * /codeyam-onboard migrates an existing source tree. Empty greenfield
+ * (no non-hidden entries before init) must route to the scaffold path;
+ * existing greenfield routes to the migration path. Mirrors the same
+ * split in `cmd_init` (init.rs:10-24) — keep both in sync. Do NOT
+ * "simplify" by collapsing the branches; the skill each path names is the
+ * whole point.
+ *
+ *   action !== "init"          → null   (modern: proceed, no banner;
+ *                                         legacy already bailed earlier)
+ *   action "init", wasEmpty    → /codeyam-editor scaffold-from-scratch
+ *   action "init", !wasEmpty   → /codeyam-onboard migrate-existing
+ */
+function postLaunchInitBanner({ preflightAction, wasEmpty }) {
+  if (preflightAction !== "init") return null;
+  if (wasEmpty) {
+    return (
+      "\nInitialized .codeyam/ in this directory. Open Claude Code here and " +
+      "run `/codeyam-editor` to scaffold a new project from scratch."
+    );
+  }
+  return (
+    "\nInitialized .codeyam/ in this directory. To populate scenarios, " +
+    "open Claude Code here and run `/codeyam-onboard`."
+  );
+}
+
+module.exports = {
+  hasSubcommand,
+  buildBinary,
+  shouldRebuildOnPassthrough,
+  staleBinaryBanner,
+  hasStartCommand,
+  planPreflightAction,
+  postLaunchInitBanner,
+};
+
+if (require.main === module) {
+  // --- Passthrough mode: build binary, then forward to it ---
+  if (hasSubcommand()) {
+    // Only rebuild when the target IS the editor repo itself, or when the
+    // developer has explicitly opted into the "edit editor against external
+    // project" workflow via CODEYAM_DEV_REBUILD=1. On any other project the
+    // editor binary is a fixed tool and a `cargo build` here ripples into a
+    // stale-binary SIGUSR1 re-exec that resets the user's session for no
+    // reason. `ensureBinary()` still builds once if no binary exists at all.
+    if (
+      shouldRebuildOnPassthrough({
+        cwd: process.cwd(),
+        repoRoot: rootDir,
+        env: process.env,
+      })
+    ) {
+      enforceFreshBinary(buildBinary(), { action: "run editor commands" });
+    }
+    const binary = ensureBinary();
+    const child = spawn(binary, args, {
+      stdio: "inherit",
+      cwd: process.cwd(),
+      env: process.env,
+    });
+    child.on("exit", (code) => {
+      process.exit(code ?? 1);
+    });
+  } else {
+    // --- Launcher mode: build everything, start server, open browser ---
+    const shouldRestart = args.includes("--restart");
+
+    const launcherMain = async () => {
+      const projectDir = process.cwd();
+      console.error(`Editor repo: ${rootDir}`);
+      console.error(`Target project: ${projectDir}`);
+
+      // Greenfield projects are auto-initialized here so the dev launcher
+      // stays a one-shot "build everything, run the editor against this
+      // project" tool. Legacy projects bail with guidance; modern projects
+      // skip init. See `planPreflightAction` for the rationale on each
+      // branch. Subcommand pass-through (handled above) is unaffected — the
+      // binary classifies its own subcommands.
+      const preflight = planPreflightAction(classifyProject(projectDir));
+      // Capture emptiness BEFORE init runs — the spawn below creates
+      // .codeyam/ (and install_editor_files writes .claude/ etc.), which
+      // would make every project look non-empty by the time the
+      // post-launch banner prints. Same constraint as the Rust comment in
+      // `init_greenfield_branch` (init.rs:82-85). Computed as a sibling
+      // local (not folded into `preflight`) because emptiness is
+      // orthogonal to the preflight kind.
+      const wasEmpty = isEmptyProjectDir(projectDir);
+      if (preflight.action === "bail") {
+        console.error(preflight.guidance);
+        process.exit(preflight.code);
+      }
+      if (preflight.action === "init") {
+        // Run init from projectDir before the config reads below so the
+        // freshly-written .codeyam/editor.json feeds port resolution.
+        // ensureBinary builds the binary first if this is a fresh checkout.
+        console.error(`Initializing codeyam-editor in ${projectDir}...`);
+        const initBinary = ensureBinary();
+        const initResult = spawnSync(initBinary, ["init"], {
+          cwd: projectDir,
+          stdio: "inherit",
+          env: process.env,
+        });
+        if (initResult.status !== 0) {
+          console.error(
+            `codeyam-editor init exited ${initResult.status ?? "by signal"}; aborting launch.`,
+          );
+          process.exit(1);
+        }
+      }
+
+      // Editor server's control port is owned by the editor repo's
+      // merged config (rootDir), not the target project's. The target
+      // project's own `editor.local.json` only contributes to the
+      // app/dev-server port below.
+      const editorMerged = readMergedEditorConfig(rootDir);
+      const SERVER_PORT = resolveLauncherPort(
+        process.env.CODEYAM_EDITOR_PORT,
+        editorMerged.proxy && editorMerged.proxy.controlPort,
+        14199,
+      );
+
+      // Target project's dev-server port comes from its own
+      // editor.json + editor.local.json (developers iterating on the
+      // editor against a real client project rely on the override
+      // file here too).
+      const projectMerged = readMergedEditorConfig(projectDir);
+      const appPort = resolveLauncherPort(undefined, projectMerged.port, 3000);
+
+      // Same gate as the passthrough path: only rebuild the Rust binary +
+      // UI when the launcher target IS the editor repo itself, or when
+      // CODEYAM_DEV_REBUILD=1 is explicitly set. Launching the editor
+      // against an external project must not relink the binary — the
+      // server-side stale-binary watcher would otherwise SIGUSR1-restart
+      // the freshly-launched server immediately. `ensureBinary()` still
+      // builds once if no binary exists.
+      const shouldRebuildLaunch = shouldRebuildOnPassthrough({
+        cwd: projectDir,
+        repoRoot: rootDir,
+        env: process.env,
+      });
+      if (shouldRebuildLaunch) {
+        enforceFreshBinary(buildBinary(), {
+          action: "run editor commands",
+          continueVerb: "launching with",
+        });
+
+        // Build the UI from the editor repo
+        console.error("Building UI...");
+        try {
+          execSync("npx vite build", { stdio: "inherit", cwd: path.join(rootDir, "ui") });
+        } catch {
+          console.error("Failed to build UI. Continuing with existing build (if any)...");
+        }
+      }
+
+      const serverChild = shouldRestart
+        ? await restartServer(SERVER_PORT)
+        : await ensureServer(SERVER_PORT);
+
+      // Re-read the (possibly just-initialized) project config to decide
+      // whether to wait on a dev server at all. On a project where init
+      // couldn't detect a framework (or a user-configured "editor UI
+      // only" setup), `startCommand` is empty — the editor server itself
+      // prints "No startCommand configured. Running editor UI only." and
+      // never spawns a dev server, so waiting 15s for `appPort + 1` is a
+      // pure UX hang. The launcher silently skips the wait; the server's
+      // own log line is the canonical signal to the user.
+      const postInitMerged = readMergedEditorConfig(projectDir);
+      const hasCommand = hasStartCommand(postInitMerged);
+      if (hasCommand) {
+        const viteInternalPort = appPort + 1;
+        console.error(`Waiting for dev server on port ${viteInternalPort}...`);
+        const viteReady = await waitForPort(viteInternalPort, 15000, 300);
+        if (!viteReady) {
+          console.error(`Warning: Dev server not ready on port ${viteInternalPort}. Live Preview may not work initially.`);
+        }
+      }
+
+      const url = `http://localhost:${SERVER_PORT}`;
+      console.error(`Editor UI: ${url}`);
+      if (hasCommand) {
+        console.error(`Live Preview: http://localhost:${appPort}`);
+      }
+      console.error(`Project: ${projectDir}`);
+      open(url);
+      const banner = postLaunchInitBanner({
+        preflightAction: preflight.action,
+        wasEmpty,
+      });
+      if (banner) {
+        console.error(banner);
+      }
+      const keepAlive = setInterval(() => {}, 60_000);
+
+      process.on("SIGINT", () => {
+        clearInterval(keepAlive);
+        killChildProcess(serverChild);
+        process.exit(0);
+      });
+    };
+
+    launcherMain();
+  }
+}

package/npm/editor.js

@@ -13,18 +13,170 @@
  */
 
 const { execSync } = require("child_process");
+const fs = require("fs");
+const os = require("os");
 const path = require("path");
-const { ensureServer, restartServer, waitForPort, rootDir } = require("./utils");
+const {
+  ensureServer,
+  stopServer,
+  waitForPort,
+  rootDir,
+  killChildProcess,
+  readMergedEditorConfig,
+  resolveLauncherPort,
+  resolveWrappedAppPort,
+  classifyPortHolder,
+  formatForeignListenerError,
+  formatCrossProjectError,
+  staleBinaryBanner,
+  enforceFreshBinary,
+} = require("./utils");
 const { open } = require("./open");
 
-const SERVER_PORT = 14199;
-const VITE_PORT = 5173;
-// The reverse proxy sits on VITE_PORT; the actual Vite dev server runs on
-// VITE_PORT + 1. We need to wait for the real Vite server, not the proxy.
-const VITE_INTERNAL_PORT = VITE_PORT + 1;
 const shouldRestart = process.argv.includes("--restart");
 
+function buildBinary() {
+  console.error("Building Rust binary...");
+  try {
+    execSync("cargo build", { stdio: "inherit", cwd: rootDir });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Resolve <CARGO_HOME>/bin (falling back to $HOME/.cargo/bin). Mirrors
+// `installed_binary_path()` in crates/control-api/src/pty_broker_startup.rs
+// — the Rust broker auto-spawn execs the binary at this path, so we MUST
+// keep it in sync with the freshly-built debug binary or `npm run editor`
+// will start a server whose PTY-broker auto-spawn execs a stale install.
+function cargoBinDir() {
+  if (process.env.CARGO_HOME) return path.join(process.env.CARGO_HOME, "bin");
+  return path.join(os.homedir(), ".cargo", "bin");
+}
+
+// Place a hardlink at `dstPath` pointing at the same inode as `srcPath`,
+// replacing any existing file at `dstPath`. On EXDEV (cross-filesystem,
+// rare; target/ on a separate mount from the cargo bin dir) falls back
+// to an atomic copy-and-rename via `tmpPath` so we still succeed — at
+// the cost of distinct inodes, which means the dev binary's
+// `stale_cargo_bin_message` check will fire on every boot.
+//
+// Hardlink-by-default is what keeps the stale-binary advisory silent on
+// `npm run editor`: the freshly-installed binary at <cargo_bin> shares
+// an inode with target/debug/codeyam-editor, so the inode-identity
+// check returns "same underlying file" and nothing is printed.
+function linkOrCopyBinary(srcPath, dstPath, tmpPath) {
+  try {
+    fs.unlinkSync(dstPath);
+  } catch (e) {
+    if (e.code !== "ENOENT") throw e;
+  }
+  try {
+    fs.linkSync(srcPath, dstPath);
+  } catch (err) {
+    if (err.code !== "EXDEV") throw err;
+    fs.copyFileSync(srcPath, tmpPath);
+    fs.chmodSync(tmpPath, 0o755);
+    fs.renameSync(tmpPath, dstPath);
+  }
+}
+
+// Install target/debug/codeyam-editor to <cargo_bin>/codeyam-editor
+// atomically (write to tmp in same dir, then rename), and refresh the
+// codeyam-editor-pty-broker hardlink so it points at the new inode.
+//
+// The PTY broker auto-spawn (control-api/src/pty_broker_startup.rs) always
+// resolves the *installed* path, NOT current_exe() — that was a deliberate
+// fix to prevent a fork-bomb where test binaries spawned themselves. So a
+// fresh `target/debug/codeyam-editor` is not enough; the install path must
+// be refreshed too. Without this, build tabs hang on "Reconnecting..."
+// because the broker daemon errors out (`unrecognized subcommand`) before
+// the UDS socket opens.
+function installBinary() {
+  const srcPath = path.join(rootDir, "target", "debug", "codeyam-editor");
+  if (!fs.existsSync(srcPath)) {
+    console.error(`Skipping install: ${srcPath} not found.`);
+    return;
+  }
+  const binDir = cargoBinDir();
+  const dstPath = path.join(binDir, "codeyam-editor");
+  const linkPath = path.join(binDir, "codeyam-editor-pty-broker");
+  const tmpPath = path.join(binDir, `.codeyam-editor.tmp.${process.pid}`);
+  console.error(`Installing fresh binary to ${dstPath}...`);
+  try {
+    fs.mkdirSync(binDir, { recursive: true });
+    linkOrCopyBinary(srcPath, dstPath, tmpPath);
+    try {
+      fs.unlinkSync(linkPath);
+    } catch (e) {
+      if (e.code !== "ENOENT") throw e;
+    }
+    fs.linkSync(dstPath, linkPath);
+  } catch (err) {
+    console.error(`Failed to install binary: ${err.message}`);
+    try { fs.unlinkSync(tmpPath); } catch {}
+  }
+}
+
+// Evict Rust build artifacts not touched in the last day so target/ doesn't
+// grow unboundedly. Must run after the old server is stopped (it holds files
+// in target/debug/ open) and before the new server starts. Non-fatal.
+function sweepStaleArtifacts() {
+  console.error("Sweeping stale Rust build artifacts (idle >1 day)...");
+  try {
+    execSync("cargo sweep --time 1", { stdio: "inherit", cwd: rootDir });
+  } catch {
+    console.error("cargo-sweep failed (install with `cargo install cargo-sweep`). Continuing.");
+  }
+}
+
+/**
+ * npm wrapper entry point for the editor binary: resolves ports from
+ * the merged editor config, ensures the Rust backend is running, and
+ * opens the editor UI.
+ */
 async function main() {
+  // Read ports from the merged editor config (editor.json + per-developer
+  // editor.local.json). The Rust backend reads the same merged config on
+  // its own — we resolve here so the launcher's log lines, `waitForPort`
+  // calls, and `--port` arg agree with what the binary will actually
+  // bind. Env vars still win for scripted/CI invocations
+  // (CODEYAM_EDITOR_PORT, PORT), then the merged config, then a hard
+  // fallback for fresh checkouts with no override file.
+  const merged = readMergedEditorConfig(rootDir);
+  const SERVER_PORT = resolveLauncherPort(
+    process.env.CODEYAM_EDITOR_PORT,
+    merged.proxy && merged.proxy.controlPort,
+    14199,
+  );
+  // `resolveWrappedAppPort` mirrors `resolve_app_port` in
+  // `crates/codeyam-editor/src/commands/start.rs`: `env > apps[0].port >
+  // config.port`. Without this the launcher's log line and
+  // `waitForPort` probe targeted one port while the backend bound
+  // another, producing the misleading "Vite dev server not ready on
+  // port N" warning whenever apps[0] declared its own port.
+  const VITE_PORT = resolveWrappedAppPort(merged, process.env.PORT, 5173);
+  // The reverse proxy sits on VITE_PORT; the actual Vite dev server runs on
+  // VITE_PORT + 1. We need to wait for the real Vite server, not the proxy.
+  const VITE_INTERNAL_PORT = VITE_PORT + 1;
+
+  // Rebuild the Rust binary so code changes are picked up on restart.
+  // This script is only invoked from a source checkout (via `npm run editor`),
+  // so Cargo.toml and the crates tree are always present.
+  const buildOk = buildBinary();
+  // A failed rebuild means the server would boot on a stale binary that no
+  // longer matches the source. Refuse by default; CODEYAM_ALLOW_STALE=1
+  // forces the old behavior (continue with the last-good install).
+  enforceFreshBinary(buildOk, { action: "start the editor server" });
+  // Refresh <cargo_bin>/codeyam-editor (and the pty-broker hardlink) so
+  // the broker auto-spawn execs a binary that knows the `pty-broker
+  // daemon` subcommand. Skip if the build failed — installing a stale
+  // debug binary over a working install is worse than leaving it.
+  if (buildOk) {
+    installBinary();
+  }
+
   // Build the UI so the backend can serve it as static files
   console.error("Building UI...");
   try {
@@ -37,10 +189,33 @@ async function main() {
   }
 
   // Start the Rust backend — it serves ui/dist/ and launches the Vite dev
-  // server (configured via startCommand in editor.json) for Live Preview HMR
-  const serverChild = shouldRestart
-    ? await restartServer(SERVER_PORT)
-    : await ensureServer(SERVER_PORT);
+  // server (configured via startCommand in editor.json) for Live Preview HMR.
+  // On --restart: identity-check first, then stop the existing server,
+  // sweep stale artifacts while target/ is idle, then start fresh.
+  //
+  // Stopping someone else's editor server on `--restart` is the worst
+  // possible outcome of a port collision — only stop the listener if
+  // the identity probe confirms it's this project's server.
+  if (shouldRestart) {
+    const holder = await classifyPortHolder(SERVER_PORT);
+    if (holder.kind === "foreign") {
+      console.error(formatForeignListenerError(SERVER_PORT));
+      process.exit(1);
+    }
+    if (holder.kind === "cross-project") {
+      console.error(formatCrossProjectError(SERVER_PORT, holder, "restart"));
+      process.exit(1);
+    }
+    if (holder.kind === "same-project") {
+      console.error(`Stopping existing server on port ${SERVER_PORT}...`);
+      await stopServer(SERVER_PORT);
+    }
+    // holder.kind === "free": nothing to stop, fall through to ensureServer.
+  }
+  if (shouldRestart) {
+    sweepStaleArtifacts();
+  }
+  const serverChild = await ensureServer(SERVER_PORT);
 
   // Wait for the actual Vite dev server on the internal port (not the reverse
   // proxy on VITE_PORT, which starts immediately with the Rust binary).
@@ -59,9 +234,21 @@ async function main() {
 
   process.on("SIGINT", () => {
     clearInterval(keepAlive);
-    if (serverChild) serverChild.kill("SIGINT");
+    killChildProcess(serverChild);
     process.exit(0);
   });
 }
 
-main();
+module.exports = {
+  buildBinary,
+  staleBinaryBanner,
+  cargoBinDir,
+  installBinary,
+  linkOrCopyBinary,
+  main,
+  sweepStaleArtifacts,
+};
+
+if (require.main === module) {
+  main();
+}