@paleo/workspace 0.12.0 → 0.13.0

package/README.md

@@ -5,7 +5,7 @@ Run multiple local dev environments side by side, one per git worktree, with iso
 Each project writes two custom scripts on top, using these entry points:
 
 - `runWorkspace(config)` — worktree lifecycle (setup / remove / set-owner).
-- `runDevServer(config)` — background dev-server start / stop / list.
+- `runDevServer(config)` — dev-server start (foreground or background) / stop / list.
 
 ## Setup
 
@@ -27,11 +27,12 @@ The agent reads the skill, adapts the reference scripts to your stack, installs
 
 ```sh
 npm run workspace -- setup feat/42 -c   # new branch + worktree + isolated env
-npm run dev:up                          # start dev server in the background (no-op if already running here)
-npm run dev:up -- --restart             # stop the dev-server in this worktree if running, then start fresh
-npm run dev:up -- --evict               # if devLimit is reached, evict the oldest dev-server and start
-npm run dev:list                        # active dev-servers across all worktrees
-npm run dev:down                        # stop dev server (infrastructure stays up)
+npm run dev                             # start in the foreground; holds the terminal, stops on CTRL+C
+npm run dev -- up                       # start in the background (no-op if already running here)
+npm run dev -- up --restart             # stop the dev-server in this worktree if running, then start fresh
+npm run dev -- up --evict               # if devLimit is reached, evict the oldest dev-server and start
+npm run dev -- list                     # active dev-servers across all worktrees
+npm run dev -- down                     # stop dev server (infrastructure stays up)
 npm run workspace -- remove feat/42     # full teardown
 ```
 
@@ -78,7 +79,7 @@ Setup runs in two phases: a fast foreground Part 1 creates the worktree and conf
 
 **Bootstrap the main worktree first.** Linked-worktree setup copies config sources from the main worktree, so the main must already have those files. Run `workspace setup` once on the main checkout. Use `preSetup` (with `isMainWorktree === true`) to seed sources from examples or templates. `configFiles` entries are required by default; mark `optional: true` for sources that may legitimately be missing.
 
-`--evict` is best-effort: the cap check and the subsequent register are not atomic, so two concurrent `dev:up --evict` from different worktrees can both pass the check and end up at `devLimit + 1` live servers. The window is narrow; if it matters, `dev:list` + `dev:down` deterministically.
+`--evict` is best-effort: the cap check and the subsequent register are not atomic, so two concurrent `dev up --evict` from different worktrees can both pass the check and end up at `devLimit + 1` live servers. The window is narrow; if it matters, `dev list` + `dev down` deterministically.
 
 ```ts
 import { runDevServer, helpers } from "@paleo/workspace";
@@ -92,7 +93,8 @@ await runDevServer({
     {
       kind: "spawn",
       name: "dev",
-      exec: { command: "npm", args: ["run", "dev"] },
+      // Not `dev` — the workspace wrapper script is named `dev`, so `npm run dev` would recurse.
+      exec: { command: "npm", args: ["run", "dev:app"] },
       port: helpers.readPortFromEnvFile(".env", "PORT"),
       detectSuccess: (log) => log.includes("Server is ready on port"),
     },

package/dist/cli.d.ts

@@ -34,14 +34,21 @@ export interface ParsedWorkspaceArgs {
 }
 export declare function parseWorkspaceArgs(argv?: string[]): ParsedWorkspaceArgs;
 export declare function printWorkspaceHelp(): void;
-export interface DevServerArgs {
-    help?: boolean;
-    stop?: boolean;
-    list?: boolean;
-    all?: boolean;
-    evict?: boolean;
-    restart?: boolean;
-}
-export declare function parseDevServerArgs(argv?: string[]): DevServerArgs;
-export declare function printDevServerHelp(): void;
-export declare function validateDevServerFlags(args: DevServerArgs): void;
+export type DevCommand = {
+    kind: "foreground";
+    evict: boolean;
+    restart: boolean;
+} | {
+    kind: "up";
+    evict: boolean;
+    restart: boolean;
+} | {
+    kind: "down";
+    all: boolean;
+} | {
+    kind: "list";
+} | {
+    kind: "help";
+};
+export declare function parseDevArgs(argv?: string[]): DevCommand;
+export declare function printDevHelp(): void;

package/dist/cli.js

@@ -1,28 +1,19 @@
 import { parseArgs } from "node:util";
 import { ConfigError } from "./errors.js";
-const DEV_SERVER_OPTIONS = {
-    help: { type: "boolean", short: "h", description: "Show this help message" },
-    stop: { type: "boolean", description: "Stop dev servers in the current worktree" },
-    list: { type: "boolean", description: "List active dev-servers across all worktrees" },
-    all: { type: "boolean", description: "Apply --stop to every active dev-server" },
-    evict: { type: "boolean", description: "Evict the oldest dev-server when the cap is reached" },
-    restart: {
-        type: "boolean",
-        description: "If a dev-server is already running in this worktree, stop it first, then start",
-    },
-};
 export function parseWorkspaceArgs(argv = process.argv.slice(2)) {
     const [subcommand, ...tokens] = argv;
-    if (subcommand === undefined || subcommand === "--help" || subcommand === "-h") {
+    if (subcommand === "--help" || subcommand === "-h") {
         return { command: { kind: "help" }, verbose: false };
     }
+    if (subcommand === undefined)
+        throw new ConfigError("No command given.");
     try {
         return parseSubcommand(subcommand, tokens);
     }
     catch (err) {
         if (err instanceof ConfigError)
             throw err;
-        throw new ConfigError(`Error: ${err.message}`);
+        throw new ConfigError(err.message);
     }
 }
 function parseSubcommand(subcommand, tokens) {
@@ -42,7 +33,7 @@ function parseSubcommand(subcommand, tokens) {
         case "__finalize":
             return parseFinalize(tokens);
         default:
-            throw new ConfigError(`Error: Unknown command "${subcommand}". Run \`workspace --help\`.`);
+            throw new ConfigError(`Unknown command "${subcommand}". Run \`workspace --help\`.`);
     }
 }
 function parseSetup(tokens) {
@@ -62,7 +53,7 @@ function parseSetup(tokens) {
     const branch = takeOptionalPositional(positionals, "setup");
     const newBranch = values["new-branch"] ?? false;
     if (newBranch && branch === undefined) {
-        throw new ConfigError("Error: `workspace setup <branch> -c` requires a branch name.");
+        throw new ConfigError("`workspace setup <branch> -c` requires a branch name.");
     }
     return {
         command: {
@@ -151,19 +142,19 @@ function parseFinalize(tokens) {
 }
 function takeOptionalPositional(positionals, command) {
     if (positionals.length > 1) {
-        throw new ConfigError(`Error: \`workspace ${command}\` accepts at most one positional argument.`);
+        throw new ConfigError(`\`workspace ${command}\` accepts at most one positional argument.`);
     }
     return positionals[0];
 }
 function takeRequiredPositional(positionals, command, label) {
     if (positionals.length !== 1) {
-        throw new ConfigError(`Error: \`workspace ${command}\` requires exactly one ${label}.`);
+        throw new ConfigError(`\`workspace ${command}\` requires exactly one ${label}.`);
     }
     return positionals[0];
 }
 function rejectPositionals(positionals, command) {
     if (positionals.length > 0) {
-        throw new ConfigError(`Error: \`workspace ${command}\` takes no positional arguments.`);
+        throw new ConfigError(`\`workspace ${command}\` takes no positional arguments.`);
     }
 }
 export function printWorkspaceHelp() {
@@ -193,44 +184,91 @@ export function printWorkspaceHelp() {
         "  -v, --verbose   Show intermediate output.",
     ].join("\n"));
 }
-export function parseDevServerArgs(argv) {
-    return parseOptions(argv, DEV_SERVER_OPTIONS);
-}
-export function printDevServerHelp() {
-    console.log(formatHelp("dev-server [options]", "Start, stop, or list background dev-server processes.", DEV_SERVER_OPTIONS));
-}
-export function validateDevServerFlags(args) {
-    if (args.all && !args.stop) {
-        throw new ConfigError("Error: --all requires --stop.");
-    }
-    if (args.list && (args.stop || args.all)) {
-        throw new ConfigError("Error: --list is mutually exclusive with --stop and --all.");
+export function parseDevArgs(argv = process.argv.slice(2)) {
+    const [first] = argv;
+    if (first === "--help" || first === "-h")
+        return { kind: "help" };
+    try {
+        if (first === undefined || first.startsWith("-"))
+            return parseForeground(argv);
+        return parseDevSubcommand(first, argv.slice(1));
     }
-    if (args.evict && (args.stop || args.list || args.all)) {
-        const conflict = args.stop ? "--stop" : args.list ? "--list" : "--all";
-        throw new ConfigError(`Error: --evict cannot be combined with ${conflict}.`);
+    catch (err) {
+        if (err instanceof ConfigError)
+            throw err;
+        throw new ConfigError(err.message);
     }
-    if (args.restart && (args.stop || args.list || args.all)) {
-        const conflict = args.stop ? "--stop" : args.list ? "--list" : "--all";
-        throw new ConfigError(`Error: --restart cannot be combined with ${conflict}.`);
+}
+function parseDevSubcommand(subcommand, tokens) {
+    switch (subcommand) {
+        case "up":
+            return parseUp(tokens);
+        case "down":
+            return parseDown(tokens);
+        case "list":
+            return parseDevList(tokens);
+        default:
+            throw new ConfigError(`Unknown command "${subcommand}". Run \`dev --help\`.`);
     }
 }
-function parseOptions(argv, options) {
-    const cfg = { options: options, strict: true };
-    if (argv)
-        cfg.args = argv;
-    const { values } = parseArgs(cfg);
-    return values;
-}
-function formatHelp(usage, intro, options) {
-    const lines = [`Usage: ${usage}`, "", intro, ""];
-    for (const [name, opt] of Object.entries(options)) {
-        if (opt.description === "")
-            continue;
-        const shortFlag = opt.short ? `-${opt.short}, ` : "";
-        const argSuffix = opt.arg ? ` <${opt.arg}>` : "";
-        const flag = `${shortFlag}--${name}${argSuffix}`;
-        lines.push(`  ${flag.padEnd(28)} ${opt.description}`);
+function parseForeground(tokens) {
+    const { evict, restart } = parseEvictRestart(tokens, "dev");
+    return { kind: "foreground", evict, restart };
+}
+function parseUp(tokens) {
+    const { evict, restart } = parseEvictRestart(tokens, "dev up");
+    return { kind: "up", evict, restart };
+}
+function parseEvictRestart(tokens, command) {
+    const { values, positionals } = parseArgs({
+        args: tokens,
+        options: { evict: { type: "boolean" }, restart: { type: "boolean" } },
+        allowPositionals: true,
+        strict: true,
+    });
+    rejectDevPositionals(positionals, command);
+    return { evict: values.evict ?? false, restart: values.restart ?? false };
+}
+function parseDown(tokens) {
+    const { values, positionals } = parseArgs({
+        args: tokens,
+        options: { all: { type: "boolean" } },
+        allowPositionals: true,
+        strict: true,
+    });
+    rejectDevPositionals(positionals, "dev down");
+    return { kind: "down", all: values.all ?? false };
+}
+function parseDevList(tokens) {
+    const { positionals } = parseArgs({
+        args: tokens,
+        options: {},
+        allowPositionals: true,
+        strict: true,
+    });
+    rejectDevPositionals(positionals, "dev list");
+    return { kind: "list" };
+}
+function rejectDevPositionals(positionals, command) {
+    if (positionals.length > 0) {
+        throw new ConfigError(`\`${command}\` takes no positional arguments.`);
     }
-    return lines.join("\n");
+}
+export function printDevHelp() {
+    console.log([
+        "Usage: dev [command] [options]",
+        "",
+        "Start, stop, or list dev-server processes for worktree-based environments.",
+        "",
+        "Commands:",
+        "  dev               Start in the foreground; holds the terminal, stops on CTRL+C.",
+        "  dev up            Start in the background and return once ready.",
+        "  dev down [--all]  Stop this worktree's dev-server, or every dev-server with --all.",
+        "  dev list          List active dev-servers across all worktrees.",
+        "  dev --help        Show this help message.",
+        "",
+        "Options (dev, dev up):",
+        "  --evict     Evict the oldest dev-server when the cap is reached.",
+        "  --restart   If a dev-server is already running here, stop it first, then start.",
+    ].join("\n"));
 }

package/dist/dev-server.d.ts

@@ -40,7 +40,7 @@ export type WorktreeReadyCheck = {
     message: string;
 };
 /**
- * Pure builder for the `dev:up` worktree-readiness gate. Returns `ok` when the slot is `ready`
+ * Pure builder for the `dev` worktree-readiness gate. Returns `ok` when the slot is `ready`
  * or absent (synthesized main); otherwise returns the user-facing error message.
  */
 export declare function buildWorktreeReadyMessage(input: {

package/dist/dev-server.js

@@ -1,7 +1,7 @@
 import { spawn } from "node:child_process";
-import { closeSync, mkdirSync, openSync } from "node:fs";
+import { closeSync, existsSync, mkdirSync, openSync, readSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { parseDevServerArgs, printDevServerHelp, validateDevServerFlags, } from "./cli.js";
+import { parseDevArgs, printDevHelp } from "./cli.js";
 import { evictOldest, findOwnEntry, listDevServers, printActiveServers, pruneAndPersist, registerDevServer, removeDevServerEntryByWorktree, stopAllRegistered, unregisterDevServer, } from "./dev-servers-registry.js";
 import { ConfigError, StartupError } from "./errors.js";
 import { detectCommonJsError, formatDuration, setupLogPath } from "./helpers.js";
@@ -14,92 +14,151 @@ function logFileFor(runtimeDir, name) {
     return join(runtimeDir, "logs", `${name}.log`);
 }
 export async function runDevServer(config) {
-    let args;
+    let command;
     try {
-        args = parseDevServerArgs();
-    }
-    catch (err) {
-        console.error(err.message);
-        process.exit(1);
-    }
-    if (args.help) {
-        printDevServerHelp();
-        return;
-    }
-    try {
-        validateDevServerFlags(args);
+        command = parseDevArgs();
     }
     catch (err) {
         if (err instanceof ConfigError) {
-            console.error(err.message);
-            process.exit(err.exitCode);
+            console.error(`Warning: ${err.message}`);
+            printDevHelp();
+            process.exit(1);
         }
         throw err;
     }
-    const { mainWorktree } = detectWorktree();
-    if (args.list) {
-        listDevServers(mainWorktree, config.registryDir);
-        return;
-    }
-    if (args.stop && args.all) {
-        await stopAllRegistered({
-            mainWorktree,
-            registryDir: config.registryDir,
-            callbackServers: callbackServersOf(config),
-        });
+    if (command.kind === "help") {
+        printDevHelp();
         return;
     }
-    if (args.stop) {
-        await stopLocal(config, mainWorktree);
-        return;
+    const { mainWorktree } = detectWorktree();
+    switch (command.kind) {
+        case "list":
+            listDevServers(mainWorktree, config.registryDir);
+            return;
+        case "down":
+            if (command.all) {
+                await stopAllRegistered({
+                    mainWorktree,
+                    registryDir: config.registryDir,
+                    callbackServers: callbackServersOf(config),
+                });
+            }
+            else {
+                await stopLocal(config, mainWorktree);
+            }
+            return;
+        case "up":
+            await start(config, mainWorktree, { evict: command.evict, restart: command.restart });
+            return;
+        case "foreground":
+            await runForeground(config, mainWorktree, {
+                evict: command.evict,
+                restart: command.restart,
+            });
+            return;
     }
-    await start(config, mainWorktree, {
-        evict: Boolean(args.evict),
-        restart: Boolean(args.restart),
-    });
 }
 function callbackServersOf(config) {
     return config.servers.filter((s) => s.kind === "callback");
 }
-async function start(config, mainWorktree, { evict, restart }) {
+async function start(config, mainWorktree, options) {
     const ctx = { cwd: process.cwd() };
-    checkWorktreeReady(config, mainWorktree, ctx.cwd);
-    if (await handleAlreadyRunning(config, mainWorktree, ctx, restart))
+    if (await runStartChecks(config, mainWorktree, ctx, options))
         return;
-    await enforceCap(config, mainWorktree, evict);
-    checkNoLocalRegistryConflict(config, mainWorktree, ctx.cwd);
-    await checkPortsFree(config.servers, ctx.cwd);
-    const spawnPids = {};
-    const startedCallbacks = [];
+    const state = { spawnPids: {}, startedCallbacks: [] };
     try {
-        for (const server of config.servers) {
-            console.log(`Starting ${server.name} dev server...`);
-            if (server.kind === "spawn") {
-                spawnPids[server.name] = spawnServer(server, config.runtimeDir, ctx.cwd);
-            }
-            else {
-                await server.start(ctx);
-                startedCallbacks.push(server);
-            }
+        await spawnAndAwait(config, ctx, state);
+    }
+    catch (err) {
+        await rollbackStart(state.spawnPids, state.startedCallbacks, ctx);
+        if (err instanceof StartupError) {
+            handleStartupFailure(err);
+            process.exit(1);
         }
-        const spawnEntries = config.servers.filter((s) => s.kind === "spawn");
-        const pollables = spawnEntries.map((s) => ({
-            name: s.name,
-            logFile: logFileFor(config.runtimeDir, s.name),
-            detectSuccess: s.detectSuccess,
-            detectError: s.detectError ?? detectCommonJsError,
-        }));
-        const pollPids = spawnEntries.map((s) => spawnPids[s.name]);
-        await awaitAllReady(pollables, pollPids);
+        throw err;
+    }
+    const slot = registerStartedServer(config, mainWorktree, state.spawnPids);
+    printStartSummary(config, slot, state.spawnPids);
+}
+/**
+ * Foreground start: hold the terminal and tail logs until CTRL+C, then stop cleanly. Signal
+ * handlers are installed before starting so an interrupt during startup rolls back; after a
+ * successful start they switch to the local stop sequence.
+ */
+async function runForeground(config, mainWorktree, options) {
+    const ctx = { cwd: process.cwd() };
+    const state = { spawnPids: {}, startedCallbacks: [] };
+    let started = false;
+    let shuttingDown = false;
+    const onSignal = () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        if (started) {
+            void shutdownForeground(config, mainWorktree);
+        }
+        else {
+            void rollbackStart(state.spawnPids, state.startedCallbacks, ctx).then(() => process.exit(130));
+        }
+    };
+    process.on("SIGINT", onSignal);
+    process.on("SIGTERM", onSignal);
+    if (await runStartChecks(config, mainWorktree, ctx, options))
+        process.exit(0);
+    try {
+        await spawnAndAwait(config, ctx, state);
     }
     catch (err) {
-        await rollbackStart(spawnPids, startedCallbacks, ctx);
+        await rollbackStart(state.spawnPids, state.startedCallbacks, ctx);
         if (err instanceof StartupError) {
             handleStartupFailure(err);
             process.exit(1);
         }
         throw err;
     }
+    const slot = registerStartedServer(config, mainWorktree, state.spawnPids);
+    started = true;
+    printStartSummary(config, slot, state.spawnPids);
+    tailLogs(config, state.spawnPids);
+    await new Promise(() => { });
+}
+async function shutdownForeground(config, mainWorktree) {
+    console.log("\nStopping dev servers...");
+    await stopLocal(config, mainWorktree);
+    console.log("Stopped.");
+    process.exit(0);
+}
+async function runStartChecks(config, mainWorktree, ctx, { evict, restart }) {
+    checkWorktreeReady(config, mainWorktree, ctx.cwd);
+    if (await handleAlreadyRunning(config, mainWorktree, ctx, restart))
+        return true;
+    await enforceCap(config, mainWorktree, evict);
+    checkNoLocalRegistryConflict(config, mainWorktree, ctx.cwd);
+    await checkPortsFree(config.servers, ctx.cwd);
+    return false;
+}
+async function spawnAndAwait(config, ctx, state) {
+    for (const server of config.servers) {
+        console.log(`Starting ${server.name} dev server...`);
+        if (server.kind === "spawn") {
+            state.spawnPids[server.name] = spawnServer(server, config.runtimeDir, ctx.cwd);
+        }
+        else {
+            await server.start(ctx);
+            state.startedCallbacks.push(server);
+        }
+    }
+    const spawnEntries = config.servers.filter((s) => s.kind === "spawn");
+    const pollables = spawnEntries.map((s) => ({
+        name: s.name,
+        logFile: logFileFor(config.runtimeDir, s.name),
+        detectSuccess: s.detectSuccess,
+        detectError: s.detectError ?? detectCommonJsError,
+    }));
+    const pollPids = spawnEntries.map((s) => state.spawnPids[s.name]);
+    await awaitAllReady(pollables, pollPids);
+}
+function registerStartedServer(config, mainWorktree, spawnPids) {
     const slot = resolveCurrentSlot(config.basePort, config.registryDir);
     const devEntry = {
         slot: slot.slot,
@@ -111,6 +170,9 @@ async function start(config, mainWorktree, { evict, restart }) {
     if (slot.main)
         devEntry.main = true;
     registerDevServer(mainWorktree, config.registryDir, devEntry);
+    return slot;
+}
+function printStartSummary(config, slot, spawnPids) {
     const summaryServers = config.servers.map((server) => {
         if (server.kind === "spawn") {
             return { server, port: server.port, pid: spawnPids[server.name] };
@@ -124,6 +186,35 @@ async function start(config, mainWorktree, { evict, restart }) {
         defaultPrintSummary(slot, summaryServers, config.runtimeDir);
     }
 }
+const TAIL_INTERVAL_MS = 300;
+function tailLogs(config, spawnPids) {
+    const names = Object.keys(spawnPids);
+    const prefixed = names.length > 1;
+    for (const name of names) {
+        const path = join(process.cwd(), logFileFor(config.runtimeDir, name));
+        followLogFile(path, prefixed ? `[${name}] ` : "");
+    }
+}
+function followLogFile(path, prefix) {
+    let offset = existsSync(path) ? statSync(path).size : 0;
+    setInterval(() => {
+        if (!existsSync(path))
+            return;
+        const size = statSync(path).size;
+        if (size < offset)
+            offset = 0;
+        if (size <= offset)
+            return;
+        const length = size - offset;
+        const fd = openSync(path, "r");
+        const buffer = Buffer.allocUnsafe(length);
+        const bytesRead = readSync(fd, buffer, 0, length, offset);
+        closeSync(fd);
+        offset += bytesRead;
+        const text = buffer.subarray(0, bytesRead).toString("utf8");
+        process.stdout.write(prefix === "" ? text : text.replace(/^(?=.)/gm, prefix));
+    }, TAIL_INTERVAL_MS);
+}
 async function rollbackStart(spawnPids, startedCallbacks, ctx) {
     console.error("\nStopping dev servers...");
     for (const pid of Object.values(spawnPids)) {
@@ -145,7 +236,7 @@ async function rollbackStart(spawnPids, startedCallbacks, ctx) {
     }
 }
 /**
- * Pure builder for the `dev:up` worktree-readiness gate. Returns `ok` when the slot is `ready`
+ * Pure builder for the `dev` worktree-readiness gate. Returns `ok` when the slot is `ready`
  * or absent (synthesized main); otherwise returns the user-facing error message.
  */
 export function buildWorktreeReadyMessage(input) {
@@ -159,7 +250,7 @@ export function buildWorktreeReadyMessage(input) {
             ok: false,
             message: `Error: Worktree setup is still in progress (slot ${slotPort}, started ${elapsed} ago).\n` +
                 `Tail: ${logPath}\n` +
-                "Run `workspace wait` to block until it finishes, or retry `dev:up` once ready.",
+                "Run `workspace wait` to block until it finishes, or retry `dev` once ready.",
         };
     }
     const failureAt = entry.failure?.at ?? entry.createdAt;
@@ -206,10 +297,10 @@ async function handleAlreadyRunning(config, mainWorktree, ctx, restart) {
     }
     const pidList = livePids.map(([name, pid]) => `${name}=${pid}`).join(", ");
     console.log(`dev-server already running for this worktree (slot ${entry.slot}, pids: ${pidList}).`);
-    console.log("Run `dev:down` to stop it, or re-run with --restart to restart.");
+    console.log("Run `dev down` to stop it, or re-run with `--restart` to restart.");
     return true;
 }
-// TOCTOU: the cap check and the subsequent register are not atomic. Two concurrent `dev:up --evict`
+// TOCTOU: the cap check and the subsequent register are not atomic. Two concurrent `dev up --evict`
 // from different worktrees can both pass the cap check and both register, exceeding the limit by
 // one. Accepted: the race window is narrow and the consequence is bounded (one extra dev-server).
 async function enforceCap(config, mainWorktree, evict) {
@@ -222,8 +313,8 @@ async function enforceCap(config, mainWorktree, evict) {
     if (!evict) {
         console.error(`Error: dev-server cap reached (${active.length}/${limit}). Active dev-servers:`);
         printActiveServers(active);
-        console.error("Run `dev:down` in another worktree, or `dev:down --all`.");
-        console.error("Re-run with --evict to evict the oldest.");
+        console.error("Run `dev down` in another worktree, or `dev down --all`.");
+        console.error("Re-run with `--evict` to evict the oldest.");
         process.exit(1);
     }
     const toEvict = active.length - limit + 1;

package/dist/dev-servers-registry.d.ts

@@ -38,5 +38,7 @@ export declare function removeDevServerEntryByWorktree(mainWorktree: string, reg
 export declare function findOwnEntry(mainWorktree: string, registryDir: string, worktreePath: string): DevServerEntry | undefined;
 export declare function pruneAndPersist(mainWorktree: string, registryDir: string, isAlive?: IsAliveFn): DevServersData;
 export declare function pruneDeadServers(data: DevServersData, isAlive?: IsAliveFn): DevServersData;
+/** Resolved worktree paths whose dev-server entry has at least one live PID. */
+export declare function liveWorktrees(data: DevServersData, isAlive?: IsAliveFn): Set<string>;
 export declare function readDevServers(mainWorktree: string, registryDir: string): DevServersData;
 export declare function writeDevServers(mainWorktree: string, registryDir: string, data: DevServersData): void;

package/dist/dev-servers-registry.js

@@ -115,6 +115,16 @@ export function pruneDeadServers(data, isAlive = isProcessAlive) {
     const live = data.servers.filter((entry) => Object.values(entry.pids).some((pid) => isAlive(pid)));
     return { servers: live };
 }
+/** Resolved worktree paths whose dev-server entry has at least one live PID. */
+export function liveWorktrees(data, isAlive = isProcessAlive) {
+    const live = new Set();
+    for (const entry of data.servers) {
+        if (Object.values(entry.pids).some((pid) => isAlive(pid))) {
+            live.add(resolve(entry.worktree));
+        }
+    }
+    return live;
+}
 export function readDevServers(mainWorktree, registryDir) {
     const fp = filePath(mainWorktree, registryDir);
     if (!existsSync(fp))

package/dist/server-descriptor.d.ts

@@ -3,7 +3,7 @@ export interface ServerContext {
     /**
      * Worktree directory for this lifecycle call. Equals `process.cwd()` at start time for local
      * starts/stops; equals the victim entry's worktree for cross-worktree stops (eviction,
-     * `dev:down --all`). Callbacks MUST thread this into every child-process call
+     * `dev down --all`). Callbacks MUST thread this into every child-process call
      * (`{ cwd: ctx.cwd }` on `execSync`, `spawn`, etc.) and resolve relative paths against it.
      */
     cwd: string;

package/dist/slots.js

@@ -22,7 +22,7 @@ export function resolveAndRegisterSlot(input) {
     const owner = input.requestedOwner ?? existing?.owner;
     const createdAt = existing?.createdAt ?? new Date().toISOString();
     // Re-runs of `workspace setup` keep a previously finalized slot ready, unless `--force` is set —
-    // then we reset to pending so `workspace wait` blocks and `dev:up` refuses during the re-finalize.
+    // then we reset to pending so `workspace wait` blocks and `dev` refuses during the re-finalize.
     const status = existing?.status === "ready" && !input.force ? "ready" : "pending";
     const entry = {
         worktree: input.currentWorktree,

package/dist/workspace.d.ts

@@ -10,7 +10,7 @@ export interface WorkspaceConfig {
     scriptPath: string;
     /**
      * Absolute path to your dev-server script (the file that calls `runDevServer`). On
-     * `workspace remove`, the kernel shells out to `node <devServerScript> --stop` with
+     * `workspace remove`, the kernel shells out to `node <devServerScript> down` with
      * `cwd: <target worktree>`. Typically
      * `fileURLToPath(new URL('./dev-server.mjs', import.meta.url))` from your `workspace.mjs`.
      */

package/dist/workspace.js

@@ -2,7 +2,7 @@ import { spawn, spawnSync } from "node:child_process";
 import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, symlinkSync, writeFileSync, } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
 import { parseWorkspaceArgs, printWorkspaceHelp } from "./cli.js";
-import { findOwnEntry, removeDevServerEntryByWorktree } from "./dev-servers-registry.js";
+import { findOwnEntry, liveWorktrees, readDevServers, removeDevServerEntryByWorktree, } from "./dev-servers-registry.js";
 import { ConfigError } from "./errors.js";
 import { copyAndPatchFile, formatDuration, setupLogPath } from "./helpers.js";
 import { isProcessAlive } from "./process-control.js";
@@ -17,8 +17,9 @@ export async function runWorkspace(config) {
     }
     catch (err) {
         if (err instanceof ConfigError) {
-            console.error(err.message);
-            process.exit(err.exitCode);
+            console.error(`Warning: ${err.message}`);
+            printWorkspaceHelp();
+            process.exit(1);
         }
         throw err;
     }
@@ -295,10 +296,12 @@ function runList(config) {
         console.log("No workspaces registered.");
         return;
     }
+    const liveSet = liveWorktrees(readDevServers(ctx.mainWorktree, config.registryDir));
     const rows = entries.map(([port, e]) => ({
         slot: port,
         type: e.main ? "main" : "linked",
         status: e.status,
+        dev: liveSet.has(resolve(e.worktree)) ? "up" : "-",
         branch: getWorktreeBranch(e.worktree) ?? "(detached)",
         worktree: e.worktree,
         owner: e.owner ?? "-",
@@ -308,6 +311,7 @@ function runList(config) {
         slot: "SLOT",
         type: "TYPE",
         status: "STATUS",
+        dev: "DEV",
         branch: "BRANCH",
         worktree: "PATH",
         owner: "OWNER",
@@ -317,11 +321,12 @@ function runList(config) {
         slot: Math.max(headers.slot.length, ...rows.map((r) => r.slot.length)),
         type: Math.max(headers.type.length, ...rows.map((r) => r.type.length)),
         status: Math.max(headers.status.length, ...rows.map((r) => r.status.length)),
+        dev: Math.max(headers.dev.length, ...rows.map((r) => r.dev.length)),
         branch: Math.max(headers.branch.length, ...rows.map((r) => r.branch.length)),
         worktree: Math.max(headers.worktree.length, ...rows.map((r) => r.worktree.length)),
         owner: Math.max(headers.owner.length, ...rows.map((r) => r.owner.length)),
     };
-    const fmt = (r) => `${r.slot.padEnd(widths.slot)}  ${r.type.padEnd(widths.type)}  ${r.status.padEnd(widths.status)}  ${r.branch.padEnd(widths.branch)}  ${r.worktree.padEnd(widths.worktree)}  ${r.owner.padEnd(widths.owner)}  ${r.created}`;
+    const fmt = (r) => `${r.slot.padEnd(widths.slot)}  ${r.type.padEnd(widths.type)}  ${r.status.padEnd(widths.status)}  ${r.dev.padEnd(widths.dev)}  ${r.branch.padEnd(widths.branch)}  ${r.worktree.padEnd(widths.worktree)}  ${r.owner.padEnd(widths.owner)}  ${r.created}`;
     console.log(fmt(headers));
     for (const r of rows)
         console.log(fmt(r));
@@ -394,7 +399,7 @@ async function handleRemove(command, ctx, run, config) {
         stopTargetDevServer(config.devServerScript, target.worktreePath, verboseLog);
     }
     else {
-        verboseLog(`No dev-server running in ${target.worktreePath}; skipping --stop.`);
+        verboseLog(`No dev-server running in ${target.worktreePath}; skipping stop.`);
     }
     if (config.purgeInfrastructure) {
         await config.purgeInfrastructure({
@@ -516,21 +521,21 @@ function resolveRemoveTarget(command, ctx, registry) {
 }
 /**
  * Stops the dev-server running in the target worktree by shelling out to
- * `node <devServerScript> --stop` with `cwd: worktreePath`. The subprocess runs the target's
+ * `node <devServerScript> down` with `cwd: worktreePath`. The subprocess runs the target's
  * own stop flow — registry-based spawn-PID kill + callback `stop()` from the target's branch.
  */
 function stopTargetDevServer(devServerScript, worktreePath, log) {
     log(`Stopping dev-server in ${worktreePath}...`);
-    const result = spawnSync(process.execPath, [devServerScript, "--stop"], {
+    const result = spawnSync(process.execPath, [devServerScript, "down"], {
         cwd: worktreePath,
         stdio: "inherit",
         timeout: 30_000,
     });
     if (result.error) {
-        console.warn(`Warning: failed to run dev-server --stop: ${result.error.message}`);
+        console.warn(`Warning: failed to run dev down: ${result.error.message}`);
     }
     else if (result.status !== 0) {
-        console.warn(`Warning: dev-server --stop exited with code ${result.status}.`);
+        console.warn(`Warning: dev down exited with code ${result.status}.`);
     }
 }
 function resolvePortsFn(config) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paleo/workspace",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Run multiple git-worktree dev environments side by side.",
   "keywords": [
     "workspace",