@paleo/workspace 0.11.1 → 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
 ```
 
@@ -48,7 +49,7 @@ await runWorkspace({
   portNames: ["server", "frontend", "db"],
   sharedDirs: [".local", ".plans"],
   runtimeDir: ".local-wt",
-  registryDir: ".local/wt-registry",
+  registryDir: ".local/_workspace-registry",
   configFiles: [
     {
       path: ".env",
@@ -74,11 +75,11 @@ await runWorkspace({
 
 `branch` is resolved live from the worktree on each call (not persisted in the registry — `git checkout` makes any stored value stale). For detached HEAD or missing directory, it falls back to `"(detached)"`. `status` is the slot's finalize status: `"pending"` until `finalizeWorktree` succeeds, then `"ready"` (or `"failed"`).
 
-Setup runs in two phases: a fast foreground Part 1 creates the worktree and config, then a detached Part 2 runs `finalizeWorktree` and writes progress to `<runtimeDir>/wt-setup.log`. If Part 2 fails, `cd` into the worktree and run `workspace setup` — it is idempotent and retries the finalize step. To block until Part 2 finishes (CI, agent orchestration), run `workspace wait` from inside the worktree (or `workspace wait --slot 8110` from anywhere) — exits 0 on `READY`, 1 on `FAILED`.
+Setup runs in two phases: a fast foreground Part 1 creates the worktree and config, then a detached Part 2 runs `finalizeWorktree` and writes progress to `<runtimeDir>/logs/workspace-setup.log`. If Part 2 fails, `cd` into the worktree and run `workspace setup` — it is idempotent and retries the finalize step. To block until Part 2 finishes (CI, agent orchestration), run `workspace wait` from inside the worktree (or `workspace wait --slot 8110` from anywhere) — exits 0 on `READY`, 1 on `FAILED`.
 
 **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";
@@ -86,13 +87,14 @@ import { runDevServer, helpers } from "@paleo/workspace";
 await runDevServer({
   basePort: 8100,
   runtimeDir: ".local-wt",
-  registryDir: ".local/wt-registry",
+  registryDir: ".local/_workspace-registry",
   devLimit: 5,
   servers: [
     {
       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,86 +142,133 @@ 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() {
     console.log([
         "Usage: workspace <command> [options]",
         "",
-        "Manage worktree lifecycle: creation, local environment setup, and removal.",
+        "Manage workspaces: a git worktree plus its own dev setup (ports, config, database, dev server).",
         "",
         "Commands:",
         "  setup [<branch>] [-c|--new-branch] [--owner <name>] [-s|--slot <port>] [--force] [--wait]",
-        "      Set up the local environment. With <branch>, create a sibling worktree for it",
+        "      Set up the workspace. With <branch>, create a sibling worktree for it",
         "      (add -c to create the branch first). Without, set up the current worktree",
         "      (idempotent; bootstrap and retry path).",
         "      Finalize runs in the background; add --wait to block until it reaches READY.",
         "  remove [<branch>] [--no-remote-check]",
-        "      Remove a worktree by branch, or the current one when omitted.",
+        "      Remove a workspace by branch, or the current one when omitted.",
         "  list",
-        "      List all registered worktrees (slot, status, branch, path, owner, created).",
+        "      List all registered workspaces (slot, status, branch, path, owner, created).",
         "  info [-s|--slot <port>]",
-        "      Print a worktree summary (ports, branch, readiness).",
+        "      Print a workspace summary (ports, branch, readiness).",
         "  wait [-s|--slot <port>]",
         "      Block until the background finalize reaches READY (exit 0) or FAILED (exit 1).",
         "  set-owner <name>",
-        "      Update the current linked worktree's slot owner (no rebuild).",
+        "      Update the current workspace's owner (no rebuild).",
         "",
         "Global options:",
         "  -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

@@ -8,7 +8,7 @@ export interface DevServerConfig {
     /** Per-worktree runtime directory, relative to the worktree root (e.g. `.local-wt`). */
     runtimeDir: string;
     /**
-     * Shared registry directory, relative to a worktree root (e.g. `.local/wt-registry`).
+     * Shared registry directory, relative to a worktree root (e.g. `.local/_workspace-registry`).
      * Holds `slots.json` and `dev-servers.json`. Must resolve to the same physical directory
      * across linked worktrees — typically via a symlink (e.g. `.local`).
      */
@@ -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,10 +1,10 @@
 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 } from "./helpers.js";
+import { detectCommonJsError, formatDuration, setupLogPath } from "./helpers.js";
 import { awaitAllReady, handleStartupFailure } from "./log-polling.js";
 import { canonicalCwd, detectPortConflicts, sweepStalePorts, waitForPortsFree, } from "./port-holder.js";
 import { isProcessAlive, stopProcessGroup } from "./process-control.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,21 +236,21 @@ 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) {
     const { slotPort, worktreePath, runtimeDir, entry, now } = input;
     if (!entry || entry.status === "ready")
         return { ok: true };
-    const logPath = join(worktreePath, runtimeDir, "wt-setup.log");
+    const logPath = setupLogPath(worktreePath, runtimeDir);
     if (entry.status === "pending") {
         const elapsed = formatDuration(now - Date.parse(entry.createdAt));
         return {
             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;
@@ -315,7 +406,7 @@ async function stopLocal(config, mainWorktree) {
 function defaultPrintSummary(slot, servers, runtimeDir) {
     console.log("\nDev servers started!");
     const ownerSuffix = slot.owner ? `, owner ${slot.owner}` : "";
-    console.log(`  Worktree: slot ${slot.slot}${ownerSuffix}`);
+    console.log(`  Workspace: slot ${slot.slot}${ownerSuffix}`);
     for (const { server, port, pid } of servers) {
         if (server.kind === "spawn") {
             const url = `http://localhost:${port}/`;

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/helpers.d.ts

@@ -1,3 +1,4 @@
+export declare function setupLogPath(worktreeRoot: string, runtimeDir: string): string;
 export declare function patchEnvFile(content: string, patches: Record<string, string>): string;
 export declare function extractHost(content: string, key: string, fallback?: string): string;
 /**

package/dist/helpers.js

@@ -1,5 +1,8 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+export function setupLogPath(worktreeRoot, runtimeDir) {
+    return join(worktreeRoot, runtimeDir, "logs", "workspace-setup.log");
+}
 export function patchEnvFile(content, patches) {
     const lines = content.trimEnd().split("\n");
     for (const [key, value] of Object.entries(patches)) {

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,
@@ -74,7 +74,7 @@ export function validateSlotAvailability(slotArg, ctx) {
 export function resolveCurrentSlot(basePort, registryDir) {
     const slot = lookupSlotForCwd(registryDir) ?? synthesizeMainSlot(basePort);
     if (!slot) {
-        console.error("Error: No slot found for this worktree. Run `workspace setup` first.");
+        console.error("Error: No workspace here. Run `workspace setup` first.");
         process.exit(1);
     }
     return slot;

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`.
      */
@@ -33,7 +33,7 @@ export interface WorkspaceConfig {
      */
     runtimeDir: string;
     /**
-     * Shared registry directory, relative to a worktree root (e.g. `.local/wt-registry`).
+     * Shared registry directory, relative to a worktree root (e.g. `.local/_workspace-registry`).
      * Holds `slots.json` and `dev-servers.json`. Must resolve to the same physical directory
      * across linked worktrees — typically via a symlink listed in `sharedDirs` (e.g. `.local`).
      */
@@ -54,7 +54,7 @@ export interface WorkspaceConfig {
      * installed deps, etc.).
      *
      * Runs in a detached child whose stdout/stderr are already redirected to
-     * `<runtimeDir>/wt-setup.log`. `console.log` and child-process `stdio: "inherit"` land there.
+     * `<runtimeDir>/logs/workspace-setup.log`. `console.log` and child-process `stdio: "inherit"` land there.
      */
     finalizeWorktree: (ctx: SetupContext) => Promise<void> | void;
     /**

package/dist/workspace.js

@@ -2,9 +2,9 @@ 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 } from "./helpers.js";
+import { copyAndPatchFile, formatDuration, setupLogPath } from "./helpers.js";
 import { isProcessAlive } from "./process-control.js";
 import { defaultComputePorts, isValidPort, resolvePortScheme } from "./ports.js";
 import { handleSetOwner, markSlotFailed, markSlotReady, readSlots, resolveAndRegisterSlot, resolveCurrentSlot, validateSlotAvailability, writeSlots, } from "./slots.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;
     }
@@ -86,9 +87,8 @@ async function runSetup(command, ctx, run, config) {
         force: command.force,
     });
     const ports = portsFn(slot);
-    const runtimeDir = join(setupCtx.currentWorktree, config.runtimeDir);
-    mkdirSync(runtimeDir, { recursive: true });
-    const logPath = join(runtimeDir, "wt-setup.log");
+    const logPath = setupLogPath(setupCtx.currentWorktree, config.runtimeDir);
+    mkdirSync(dirname(logPath), { recursive: true });
     // Truncate any prior log so `workspace setup` retries start with a clean record (the previous run's
     // FAILED: banner would otherwise linger and produce false positives for grep-based tooling).
     writeFileSync(logPath, "");
@@ -128,7 +128,7 @@ async function runSetup(command, ctx, run, config) {
         isMainWorktree: setupCtx.isMainWorktree,
         status,
     }));
-    teeLog(`WORKTREE_CREATED path=${setupCtx.currentWorktree} branch=${branch} slot=${slot}`);
+    teeLog(`WORKSPACE_CREATED path=${setupCtx.currentWorktree} branch=${branch} slot=${slot}`);
     if (status !== "ready") {
         teeLog(`Setup continuing in background. Tail: ${logPath}`);
         teeLog(`Block until ready: workspace wait --slot ${slot}`);
@@ -162,7 +162,7 @@ function refuseIfFinalizePending(ctx, registryDir, force) {
 async function runFinalize(command, config) {
     const slot = Number(command.slot);
     const ctx = detectWorktree();
-    const logPath = join(ctx.currentWorktree, config.runtimeDir, "wt-setup.log");
+    const logPath = setupLogPath(ctx.currentWorktree, config.runtimeDir);
     const appendLog = (message) => {
         appendFileSync(logPath, `${message}\n`);
     };
@@ -227,7 +227,7 @@ function printWorktreeInfo(config, slot, worktreeForLog, fallback) {
     const ports = resolvePortsFn(config)(slot);
     const owner = entry?.owner ?? fallback.owner;
     const status = entry?.status ?? "pending";
-    const setupLogPath = join(worktreeForLog, config.runtimeDir, "wt-setup.log");
+    const setupLog = setupLogPath(worktreeForLog, config.runtimeDir);
     const now = Date.now();
     const isMainWorktree = entry?.main ?? false;
     const targetWorktree = entry?.worktree ?? ctx.currentWorktree;
@@ -246,7 +246,7 @@ function printWorktreeInfo(config, slot, worktreeForLog, fallback) {
         const at = entry?.failure?.at ?? entry?.createdAt;
         const elapsed = at ? formatDuration(now - Date.parse(at)) : "?";
         const reason = entry?.failure?.message ?? "(no message)";
-        console.log(`Failure: ${reason} (${elapsed} ago, tail ${setupLogPath})`);
+        console.log(`Failure: ${reason} (${elapsed} ago, tail ${setupLog})`);
     }
     else if (status === "pending" && entry) {
         const elapsed = formatDuration(now - Date.parse(entry.createdAt));
@@ -293,13 +293,15 @@ function runList(config) {
     const ctx = detectWorktree();
     const entries = Object.entries(readSlots(ctx.mainWorktree, config.registryDir).slots).sort(([a], [b]) => Number(a) - Number(b));
     if (entries.length === 0) {
-        console.log("No worktrees registered.");
+        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 ?? "-",
@@ -309,8 +311,9 @@ function runList(config) {
         slot: "SLOT",
         type: "TYPE",
         status: "STATUS",
+        dev: "DEV",
         branch: "BRANCH",
-        worktree: "WORKTREE",
+        worktree: "PATH",
         owner: "OWNER",
         created: "CREATED",
     };
@@ -318,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));
@@ -359,7 +363,7 @@ async function waitForSlot(slot, config, options = {}) {
             return;
         }
         if (entry.status === "failed") {
-            const logPath = join(entry.worktree, config.runtimeDir, "wt-setup.log");
+            const logPath = setupLogPath(entry.worktree, config.runtimeDir);
             console.error(`FAILED: ${entry.failure?.message ?? "(no message)"}`);
             console.error(`Full log: ${logPath}`);
             process.exit(1);
@@ -372,7 +376,7 @@ async function handleRemove(command, ctx, run, config) {
     const removeHere = command.branch === undefined;
     const registry = readSlots(ctx.mainWorktree, config.registryDir);
     const target = resolveRemoveTarget(command, ctx, registry);
-    // Refuse to remove while the detached finalize is still writing to slots.json / wt-setup.log:
+    // Refuse to remove while the detached finalize is still writing to slots.json / workspace-setup.log:
     // racing the two corrupts the registry and leaves the worktree directory orphaned.
     if (registry.slots[target.slotPort]?.status === "pending") {
         console.error(`Error: Setup is still in progress for slot ${target.slotPort}. ` +
@@ -395,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({
@@ -411,7 +415,7 @@ async function handleRemove(command, ctx, run, config) {
         process.chdir(ctx.mainWorktree);
     }
     removeWorktree(target.worktreePath, run);
-    console.log(`Removed worktree for branch "${target.branch}" (slot ${target.slotPort}${ownerSuffix}). ` +
+    console.log(`Removed workspace for branch "${target.branch}" (slot ${target.slotPort}${ownerSuffix}). ` +
         `Branch "${target.branch}" kept.`);
     if (removeHere) {
         console.log(`Now run: cd ${ctx.mainWorktree}`);
@@ -505,7 +509,7 @@ function resolveRemoveTarget(command, ctx, registry) {
     const branch = command.branch;
     const entry = Object.entries(registry.slots).find(([, v]) => getWorktreeBranch(v.worktree) === branch);
     if (!entry) {
-        console.error(`Error: No worktree found for branch "${branch}" in the slot registry.`);
+        console.error(`Error: No workspace found for branch "${branch}" in the registry.`);
         process.exit(1);
     }
     const worktreePath = entry[1].worktree;
@@ -517,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.11.1",
+  "version": "0.13.0",
   "description": "Run multiple git-worktree dev environments side by side.",
   "keywords": [
     "workspace",