@paleo/workspace 0.16.0 → 0.18.0

package/README.md

@@ -51,7 +51,6 @@ await runWorkspace({
   portNames: ["server", "frontend", "db"],
   sharedDirs: [".local", ".plans"],
   runtimeDir: ".local-wt",
-  registryDir: ".local/_workspace-registry",
   configFiles: [
     {
       path: ".env",
@@ -89,7 +88,6 @@ import { runDevServer, helpers } from "@paleo/workspace";
 await runDevServer({
   basePort: 8100,
   runtimeDir: ".local-wt",
-  registryDir: ".local/_workspace-registry",
   devLimit: 5,
   servers: [
     {

package/dist/cli.d.ts

@@ -2,6 +2,7 @@ export type WorkspaceCommand = {
     kind: "setup";
     branch?: string;
     newBranch: boolean;
+    from?: string;
     owner?: string;
     slot?: string;
     force: boolean;
@@ -9,7 +10,7 @@ export type WorkspaceCommand = {
 } | {
     kind: "remove";
     branch?: string;
-    noRemoteCheck: boolean;
+    force: boolean;
 } | {
     kind: "list";
 } | {
@@ -25,6 +26,9 @@ export type WorkspaceCommand = {
     kind: "finalize";
     slot: string;
     force: boolean;
+} | {
+    kind: "migrate";
+    oldRegistryDir: string;
 } | {
     kind: "help";
 };

package/dist/cli.js

@@ -32,6 +32,8 @@ function parseSubcommand(subcommand, tokens) {
             return parseSetOwner(tokens);
         case "__finalize":
             return parseFinalize(tokens);
+        case "migrate-0.16":
+            return parseMigrate(tokens);
         default:
             throw new ConfigError(`Unknown command "${subcommand}". Run \`workspace --help\`.`);
     }
@@ -41,6 +43,7 @@ function parseSetup(tokens) {
         args: tokens,
         options: {
             "new-branch": { type: "boolean", short: "c" },
+            from: { type: "string" },
             owner: { type: "string" },
             slot: { type: "string", short: "s" },
             force: { type: "boolean" },
@@ -55,11 +58,15 @@ function parseSetup(tokens) {
     if (newBranch && branch === undefined) {
         throw new ConfigError("`workspace setup <branch> -c` requires a branch name.");
     }
+    if (values.from !== undefined && !newBranch) {
+        throw new ConfigError("`--from` requires `-c`/`--new-branch`.");
+    }
     return {
         command: {
             kind: "setup",
             branch,
             newBranch,
+            from: values.from,
             owner: values.owner,
             slot: values.slot,
             force: values.force ?? false,
@@ -72,7 +79,7 @@ function parseRemove(tokens) {
     const { values, positionals } = parseArgs({
         args: tokens,
         options: {
-            "no-remote-check": { type: "boolean" },
+            force: { type: "boolean" },
             verbose: { type: "boolean", short: "v" },
         },
         allowPositionals: true,
@@ -80,7 +87,7 @@ function parseRemove(tokens) {
     });
     const branch = takeOptionalPositional(positionals, "remove");
     return {
-        command: { kind: "remove", branch, noRemoteCheck: values["no-remote-check"] ?? false },
+        command: { kind: "remove", branch, force: values.force ?? false },
         verbose: values.verbose ?? false,
     };
 }
@@ -140,6 +147,16 @@ function parseFinalize(tokens) {
     const slot = takeRequiredPositional(positionals, "__finalize", "slot");
     return { command: { kind: "finalize", slot, force: values.force ?? false }, verbose: false };
 }
+function parseMigrate(tokens) {
+    const { values, positionals } = parseArgs({
+        args: tokens,
+        options: { verbose: { type: "boolean", short: "v" } },
+        allowPositionals: true,
+        strict: true,
+    });
+    const oldRegistryDir = takeRequiredPositional(positionals, "migrate-0.16", "old-registry-dir");
+    return { command: { kind: "migrate", oldRegistryDir }, verbose: values.verbose ?? false };
+}
 function takeOptionalPositional(positionals, command) {
     if (positionals.length > 1) {
         throw new ConfigError(`\`workspace ${command}\` accepts at most one positional argument.`);
@@ -164,13 +181,15 @@ export function printWorkspaceHelp() {
         "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]",
+        "  setup [<branch>] [-c|--new-branch] [--from <ref>] [--owner <name>] [-s|--slot <port>] [--force] [--wait]",
         "      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).",
+        "      With -c, the new branch starts at the current worktree's HEAD, or at <ref> with --from.",
         "      Finalize runs in the background; add --wait to block until it reaches READY.",
-        "  remove [<branch>] [--no-remote-check]",
+        "  remove [<branch>] [--force]",
         "      Remove a workspace by branch, or the current one when omitted.",
+        "      Refuses on uncommitted changes unless --force.",
         "  list",
         "      List all registered workspaces (slot, status, branch, path, owner, created).",
         "  status [-s|--slot <port>]",

package/dist/dev-server.d.ts

@@ -8,12 +8,6 @@ export interface DevServerConfig {
     basePort: number;
     /** 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/_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`).
-     */
-    registryDir: string;
     /** Maximum concurrent dev-servers across all worktrees. Omit for no limit. */
     devLimit?: number;
     /** One entry per server to start. Started in array order; stopped in reverse order. */

package/dist/dev-server.js

@@ -8,7 +8,7 @@ import { detectCommonJsError, formatDuration, lastLines, setupLogPath } from "./
 import { awaitAllReady, handleStartupFailure, LOG_TAIL_LINES, } from "./log-polling.js";
 import { canonicalCwd, detectPortConflicts, sweepStalePorts, waitForPortsFree, } from "./port-holder.js";
 import { isProcessAlive, stopProcessGroup } from "./process-control.js";
-import { readSlots, resolveCurrentSlot } from "./slots.js";
+import { readSlots, registryDirFor, resolveCurrentSlot, warnLegacyRegistryDir, } from "./slots.js";
 import { detectWorktree, getWorktreeBranch } from "./worktree.js";
 function logFileFor(runtimeDir, name) {
     return join(runtimeDir, "logs", `${name}.log`);
@@ -30,60 +30,65 @@ export async function runDevServer(config) {
         printDevHelp();
         return;
     }
+    warnLegacyRegistryDir(config);
+    const registryDir = registryDirFor(config.runtimeDir);
     const { mainWorktree } = detectWorktree();
     switch (command.kind) {
         case "list":
-            listDevServers(mainWorktree, config.registryDir);
+            listDevServers(mainWorktree, registryDir);
             return;
         case "down":
             if (command.all) {
                 await stopAllRegistered({
                     mainWorktree,
-                    registryDir: config.registryDir,
+                    registryDir,
                     callbackServers: callbackServersOf(config),
                 });
             }
             else {
-                await stopLocal(config, mainWorktree);
+                await stopLocal(config, mainWorktree, registryDir);
             }
             return;
         case "up":
-            await start(config, mainWorktree, { evict: command.evict, restart: command.restart });
+            await start(config, mainWorktree, registryDir, {
+                evict: command.evict,
+                restart: command.restart,
+            });
             return;
         case "restart":
-            await start(config, mainWorktree, { evict: command.evict, restart: true });
+            await start(config, mainWorktree, registryDir, { evict: command.evict, restart: true });
             return;
         case "status":
-            printStatus(config, mainWorktree);
+            printStatus(config, mainWorktree, registryDir);
             return;
         case "foreground":
-            await runForeground(config, mainWorktree, {
+            await runForeground(config, mainWorktree, registryDir, {
                 evict: command.evict,
                 restart: command.restart,
             });
             return;
     }
 }
-function printStatus(config, mainWorktree) {
-    const entry = findOwnEntry(mainWorktree, config.registryDir, process.cwd());
+function printStatus(config, mainWorktree, registryDir) {
+    const entry = findOwnEntry(mainWorktree, registryDir, process.cwd());
     if (!entry || !Object.values(entry.pids).some(isProcessAlive)) {
         console.log("Dev-server status: DOWN.");
         return;
     }
     console.log("Dev-server status: UP.");
-    const slot = resolveCurrentSlot(config.basePort, config.registryDir);
+    const slot = resolveCurrentSlot(config.basePort, registryDir);
     printStartSummary(config, slot, entry.pids);
 }
 function callbackServersOf(config) {
     return config.servers.filter((s) => s.kind === "callback");
 }
-async function start(config, mainWorktree, options) {
+async function start(config, mainWorktree, registryDir, options) {
     const ctx = { cwd: process.cwd() };
-    if (await runStartChecks(config, mainWorktree, ctx, options))
+    if (await runStartChecks(config, mainWorktree, registryDir, ctx, options))
         return;
     const state = { spawnPids: {}, startedCallbacks: [] };
     await spawnWithRollback(config, ctx, state);
-    const slot = registerStartedServer(config, mainWorktree, state.spawnPids);
+    const slot = registerStartedServer(config, mainWorktree, registryDir, state.spawnPids);
     printStartSummary(config, slot, state.spawnPids);
 }
 /**
@@ -91,10 +96,10 @@ async function start(config, mainWorktree, options) {
  * 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) {
+async function runForeground(config, mainWorktree, registryDir, options) {
     const ctx = { cwd: process.cwd() };
     if (!options.restart) {
-        const running = findOwnLiveEntry(config, mainWorktree, ctx.cwd);
+        const running = findOwnLiveEntry(mainWorktree, registryDir, ctx.cwd);
         if (running)
             return attachForeground(config, running);
     }
@@ -106,7 +111,7 @@ async function runForeground(config, mainWorktree, options) {
             return;
         shuttingDown = true;
         if (started) {
-            void shutdownForeground(config, mainWorktree);
+            void shutdownForeground(config, mainWorktree, registryDir);
         }
         else {
             void rollbackStart(state.spawnPids, state.startedCallbacks, ctx).then(() => process.exit(130));
@@ -114,7 +119,7 @@ async function runForeground(config, mainWorktree, options) {
     };
     process.on("SIGINT", onSignal);
     process.on("SIGTERM", onSignal);
-    if (await runStartChecks(config, mainWorktree, ctx, options))
+    if (await runStartChecks(config, mainWorktree, registryDir, ctx, options))
         process.exit(0);
     // Stream logs from the first byte so the whole startup (e.g. a slow build) is visible live.
     const streamLogs = () => tailLogs(config, state.spawnPids, { fromStart: true });
@@ -123,7 +128,7 @@ async function runForeground(config, mainWorktree, options) {
     if (!(await spawnWithRollback(config, ctx, state, () => shuttingDown, streamLogs))) {
         await new Promise(() => { });
     }
-    const slot = registerStartedServer(config, mainWorktree, state.spawnPids);
+    const slot = registerStartedServer(config, mainWorktree, registryDir, state.spawnPids);
     started = true;
     printStartSummary(config, slot, state.spawnPids);
     watchForExternalStop(Object.values(state.spawnPids), () => {
@@ -135,8 +140,8 @@ async function runForeground(config, mainWorktree, options) {
     });
     await new Promise(() => { });
 }
-function findOwnLiveEntry(config, mainWorktree, cwd) {
-    const entry = findOwnEntry(mainWorktree, config.registryDir, cwd);
+function findOwnLiveEntry(mainWorktree, registryDir, cwd) {
+    const entry = findOwnEntry(mainWorktree, registryDir, cwd);
     if (!entry)
         return;
     return Object.values(entry.pids).some(isProcessAlive) ? entry : undefined;
@@ -171,18 +176,18 @@ async function attachForeground(config, entry) {
     });
     await new Promise(() => { });
 }
-async function shutdownForeground(config, mainWorktree) {
+async function shutdownForeground(config, mainWorktree, registryDir) {
     console.log("\nStopping dev servers...");
-    await stopLocal(config, mainWorktree);
+    await stopLocal(config, mainWorktree, registryDir);
     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))
+async function runStartChecks(config, mainWorktree, registryDir, ctx, { evict, restart }) {
+    checkWorktreeReady(config, mainWorktree, registryDir, ctx.cwd);
+    if (await handleAlreadyRunning(config, mainWorktree, registryDir, ctx, restart))
         return true;
-    await enforceCap(config, mainWorktree, evict);
-    checkNoLocalRegistryConflict(config, mainWorktree, ctx.cwd);
+    await enforceCap(config, mainWorktree, registryDir, evict);
+    checkNoLocalRegistryConflict(mainWorktree, registryDir, ctx.cwd);
     await checkPortsFree(config.servers, ctx.cwd);
     return false;
 }
@@ -244,8 +249,8 @@ async function spawnAndAwait(config, ctx, state, onSpawned) {
     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);
+function registerStartedServer(config, mainWorktree, registryDir, spawnPids) {
+    const slot = resolveCurrentSlot(config.basePort, registryDir);
     const devEntry = {
         slot: slot.slot,
         worktree: slot.worktree,
@@ -255,7 +260,7 @@ function registerStartedServer(config, mainWorktree, spawnPids) {
     };
     if (slot.main)
         devEntry.main = true;
-    registerDevServer(mainWorktree, config.registryDir, devEntry);
+    registerDevServer(mainWorktree, registryDir, devEntry);
     return slot;
 }
 function printStartSummary(config, slot, spawnPids) {
@@ -382,9 +387,9 @@ export function buildWorktreeReadyMessage(input) {
             "Re-run `workspace setup` to retry the finalize.",
     };
 }
-function checkWorktreeReady(config, mainWorktree, cwd) {
-    const slot = resolveCurrentSlot(config.basePort, config.registryDir);
-    const entry = readSlots(mainWorktree, config.registryDir).slots[String(slot.slot)];
+function checkWorktreeReady(config, mainWorktree, registryDir, cwd) {
+    const slot = resolveCurrentSlot(config.basePort, registryDir);
+    const entry = readSlots(mainWorktree, registryDir).slots[String(slot.slot)];
     const result = buildWorktreeReadyMessage({
         slotPort: slot.slot,
         worktreePath: cwd,
@@ -402,8 +407,8 @@ function checkWorktreeReady(config, mainWorktree, cwd) {
  * normal start path can proceed, or print a friendly notice and return `true` to short-circuit.
  * Returns `true` when the caller should exit cleanly without starting.
  */
-async function handleAlreadyRunning(config, mainWorktree, ctx, restart) {
-    const entry = findOwnEntry(mainWorktree, config.registryDir, ctx.cwd);
+async function handleAlreadyRunning(config, mainWorktree, registryDir, ctx, restart) {
+    const entry = findOwnEntry(mainWorktree, registryDir, ctx.cwd);
     if (!entry)
         return false;
     const livePids = Object.entries(entry.pids).filter(([, pid]) => isProcessAlive(pid));
@@ -411,7 +416,7 @@ async function handleAlreadyRunning(config, mainWorktree, ctx, restart) {
         return false;
     if (restart) {
         console.log("Restarting dev-server in this worktree...");
-        await stopLocal(config, mainWorktree);
+        await stopLocal(config, mainWorktree, registryDir);
         return false;
     }
     const pidList = livePids.map(([name, pid]) => `${name}=${pid}`).join(", ");
@@ -422,11 +427,11 @@ async function handleAlreadyRunning(config, mainWorktree, ctx, restart) {
 // 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) {
+async function enforceCap(config, mainWorktree, registryDir, evict) {
     const limit = config.devLimit;
     if (limit === undefined)
         return;
-    const active = pruneAndPersist(mainWorktree, config.registryDir).servers;
+    const active = pruneAndPersist(mainWorktree, registryDir).servers;
     if (active.length < limit)
         return;
     if (!evict) {
@@ -440,7 +445,7 @@ async function enforceCap(config, mainWorktree, evict) {
     console.log(`Evicting ${toEvict} dev-server(s) to make room (cap ${limit}).`);
     const evicted = await evictOldest({
         mainWorktree,
-        registryDir: config.registryDir,
+        registryDir,
         callbackServers: callbackServersOf(config),
         count: toEvict,
     });
@@ -482,8 +487,8 @@ async function checkPortsFree(servers, cwd) {
         process.exit(1);
     }
 }
-function checkNoLocalRegistryConflict(config, mainWorktree, cwd) {
-    const entry = findOwnEntry(mainWorktree, config.registryDir, cwd);
+function checkNoLocalRegistryConflict(mainWorktree, registryDir, cwd) {
+    const entry = findOwnEntry(mainWorktree, registryDir, cwd);
     if (!entry)
         return;
     for (const [name, pid] of Object.entries(entry.pids)) {
@@ -493,11 +498,11 @@ function checkNoLocalRegistryConflict(config, mainWorktree, cwd) {
         }
     }
     // Stale entry — drop it so registration overwrites cleanly.
-    removeDevServerEntryByWorktree(mainWorktree, config.registryDir, cwd);
+    removeDevServerEntryByWorktree(mainWorktree, registryDir, cwd);
 }
-async function stopLocal(config, mainWorktree) {
+async function stopLocal(config, mainWorktree, registryDir) {
     const ctx = { cwd: process.cwd() };
-    const entry = findOwnEntry(mainWorktree, config.registryDir, ctx.cwd);
+    const entry = findOwnEntry(mainWorktree, registryDir, ctx.cwd);
     if (!entry) {
         console.log("No dev-server running in this worktree.");
         await sweepStalePorts(config.servers, ctx.cwd);
@@ -519,7 +524,7 @@ async function stopLocal(config, mainWorktree) {
             console.error(`  Failed to stop ${server.name}: ${err.message}`);
         }
     }
-    unregisterDevServer(mainWorktree, config.registryDir, ctx.cwd);
+    unregisterDevServer(mainWorktree, registryDir, ctx.cwd);
     await sweepStalePorts(config.servers, ctx.cwd);
 }
 function defaultPrintSummary(slot, servers, runtimeDir) {

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

@@ -42,3 +42,5 @@ export declare function pruneDeadServers(data: DevServersData, isAlive?: IsAlive
 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;
+/** Union by resolved `worktree`; `override` wins on conflict. Base-first then override-only order. */
+export declare function mergeDevServers(base: DevServersData, override: DevServersData): DevServersData;

package/dist/dev-servers-registry.js

@@ -136,6 +136,17 @@ export function writeDevServers(mainWorktree, registryDir, data) {
     mkdirSync(join(mainWorktree, registryDir), { recursive: true });
     writeFileSync(fp, `${JSON.stringify(data, undefined, 2)}\n`);
 }
+/** Union by resolved `worktree`; `override` wins on conflict. Base-first then override-only order. */
+export function mergeDevServers(base, override) {
+    const overrideByWorktree = new Map(override.servers.map((e) => [resolve(e.worktree), e]));
+    const merged = base.servers.map((entry) => overrideByWorktree.get(resolve(entry.worktree)) ?? entry);
+    const baseWorktrees = new Set(base.servers.map((e) => resolve(e.worktree)));
+    for (const entry of override.servers) {
+        if (!baseWorktrees.has(resolve(entry.worktree)))
+            merged.push(entry);
+    }
+    return { servers: merged };
+}
 function filePath(mainWorktree, registryDir) {
     return join(mainWorktree, registryDir, DEV_SERVERS_FILENAME);
 }

package/dist/slots.d.ts

@@ -1,4 +1,11 @@
 import { type PortScheme } from "./ports.js";
+export declare const REGISTRY_SUBDIR = "shared-registry";
+export declare function registryDirFor(runtimeDir: string): string;
+/** `registryDir` is gone from the config types but may linger in a consumer's config file. */
+export declare function warnLegacyRegistryDir(config: {
+    runtimeDir: string;
+    registryDir?: string;
+}): void;
 export interface ResolvedSlot {
     slot: number;
     worktree: string;
@@ -24,6 +31,8 @@ export interface SlotsRegistry {
 }
 export declare function readSlots(mainWorktree: string, registryDir: string): SlotsRegistry;
 export declare function writeSlots(mainWorktree: string, registryDir: string, registry: SlotsRegistry): void;
+/** Union of slots keyed by port; `override` wins on conflict. */
+export declare function mergeSlots(base: SlotsRegistry, override: SlotsRegistry): SlotsRegistry;
 export interface RegisterSlotInput {
     slot?: string;
     currentWorktree: string;

package/dist/slots.js

@@ -3,7 +3,20 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { allPorts, isValidPort } from "./ports.js";
 import { getWorktreeBranch } from "./worktree.js";
+export const REGISTRY_SUBDIR = "shared-registry";
 const SLOTS_FILENAME = "slots.json";
+export function registryDirFor(runtimeDir) {
+    return join(runtimeDir, REGISTRY_SUBDIR);
+}
+/** `registryDir` is gone from the config types but may linger in a consumer's config file. */
+export function warnLegacyRegistryDir(config) {
+    if (config.registryDir === undefined)
+        return;
+    console.warn("Warning: `registryDir` is obsolete and ignored. The registry now lives at " +
+        `\`${registryDirFor(config.runtimeDir)}\`. Remove \`registryDir\` from your config. ` +
+        `If you have an existing registry at "${config.registryDir}", run ` +
+        `\`workspace migrate-0.16 ${config.registryDir}\` once to merge it.`);
+}
 export function readSlots(mainWorktree, registryDir) {
     const filePath = join(mainWorktree, registryDir, SLOTS_FILENAME);
     if (!existsSync(filePath))
@@ -15,6 +28,10 @@ export function writeSlots(mainWorktree, registryDir, registry) {
     mkdirSync(join(mainWorktree, registryDir), { recursive: true });
     writeFileSync(filePath, `${JSON.stringify(registry, undefined, 2)}\n`);
 }
+/** Union of slots keyed by port; `override` wins on conflict. */
+export function mergeSlots(base, override) {
+    return { slots: { ...base.slots, ...override.slots } };
+}
 export function resolveAndRegisterSlot(input) {
     const registry = readSlots(input.mainWorktree, input.registryDir);
     const port = pickSlotPort(input, registry);

package/dist/workspace.d.ts

@@ -32,12 +32,6 @@ export interface WorkspaceConfig {
      * Holds the setup log and dev-server logs.
      */
     runtimeDir: string;
-    /**
-     * 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`).
-     */
-    registryDir: string;
     /** Config files copied from the main worktree and patched per slot. */
     configFiles: ConfigFileEntry[];
     /**

package/dist/workspace.js

@@ -1,14 +1,14 @@
 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 { appendFileSync, closeSync, existsSync, lstatSync, mkdirSync, openSync, readFileSync, rmSync, symlinkSync, writeFileSync, } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { parseWorkspaceArgs, printWorkspaceHelp } from "./cli.js";
-import { findOwnEntry, liveWorktrees, readDevServers, removeDevServerEntryByWorktree, } from "./dev-servers-registry.js";
+import { findOwnEntry, liveWorktrees, mergeDevServers, readDevServers, removeDevServerEntryByWorktree, writeDevServers, } from "./dev-servers-registry.js";
 import { ConfigError } from "./errors.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";
-import { createBranch, detectWorktree, enforceWorktreeMode, getWorktreeBranch, removeWorktree, useExistingBranch, verifyBranchAbsentFromRemote, } from "./worktree.js";
+import { handleSetOwner, markSlotFailed, markSlotReady, mergeSlots, readSlots, REGISTRY_SUBDIR, registryDirFor, resolveAndRegisterSlot, resolveCurrentSlot, validateSlotAvailability, warnLegacyRegistryDir, writeSlots, } from "./slots.js";
+import { createBranch, detectWorktree, getWorktreeBranch, isWorktreeDirty, removeWorktree, useExistingBranch, } from "./worktree.js";
 export async function runWorkspace(config) {
     let command;
     let verbose;
@@ -27,6 +27,12 @@ export async function runWorkspace(config) {
         printWorkspaceHelp();
         return;
     }
+    warnLegacyRegistryDir(config);
+    const registryDir = registryDirFor(config.runtimeDir);
+    if (command.kind === "migrate") {
+        handleMigrate(command, config, registryDir);
+        return;
+    }
     if (!existsSync(config.scriptPath)) {
         console.error(`Error: scriptPath does not exist: ${config.scriptPath}. ` +
             "Pass `fileURLToPath(import.meta.url)` from your wrapper script.");
@@ -34,53 +40,52 @@ export async function runWorkspace(config) {
     }
     switch (command.kind) {
         case "finalize":
-            await runFinalize(command, config);
+            await runFinalize(command, config, registryDir);
             return;
         case "wait":
-            await runWait(command, config);
+            await runWait(command, config, registryDir);
             return;
         case "status":
-            runStatus(command, config);
+            runStatus(command, config, registryDir);
             return;
         case "list":
-            runList(config);
+            runList(registryDir);
             return;
     }
     const ctx = detectWorktree();
-    enforceWorktreeMode(command, ctx);
     const run = { verbose };
     switch (command.kind) {
         case "remove":
-            await handleRemove(command, ctx, run, config);
+            await handleRemove(command, ctx, run, config, registryDir);
             return;
         case "set-owner":
-            handleSetOwnerMode(command, ctx, config);
+            handleSetOwnerMode(command, ctx, registryDir);
             return;
         case "setup": {
-            const { slot } = await runSetup(command, ctx, run, config);
+            const { slot } = await runSetup(command, ctx, run, config, registryDir);
             if (command.wait)
-                await waitForSlot(slot, config, { printSummary: false });
+                await waitForSlot(slot, config, registryDir, { printSummary: false });
             return;
         }
     }
 }
-async function runSetup(command, ctx, run, config) {
+async function runSetup(command, ctx, run, config, registryDir) {
     const scheme = resolvePortScheme(config);
     const portsFn = resolvePortsFn(config);
     validateSlotAvailability(command.slot, {
         currentWorktree: ctx.currentWorktree,
         mainWorktree: ctx.mainWorktree,
-        registryDir: config.registryDir,
+        registryDir,
         scheme,
     });
     const setupCtx = ensureWorktree(command, ctx, run, config.worktreeDirName);
-    refuseIfFinalizePending(setupCtx, config.registryDir, command.force);
+    refuseIfFinalizePending(setupCtx, registryDir, command.force);
     const branch = getWorktreeBranch(setupCtx.currentWorktree) ?? "(detached)";
     const { port: slot, owner, status, } = resolveAndRegisterSlot({
         slot: command.slot,
         currentWorktree: setupCtx.currentWorktree,
         mainWorktree: setupCtx.mainWorktree,
-        registryDir: config.registryDir,
+        registryDir,
         scheme,
         requestedOwner: command.owner,
         isMainWorktree: setupCtx.isMainWorktree,
@@ -117,6 +122,7 @@ async function runSetup(command, ctx, run, config) {
         });
     }
     linkSharedDirectories(setupCtx, config.sharedDirs, verboseLog);
+    linkSharedRegistry(setupCtx, config.runtimeDir, verboseLog);
     generateConfigFiles(setupCtx, config.configFiles, slot, ports, command.force, verboseLog);
     teeLog(config.printSummary({
         slot,
@@ -159,14 +165,14 @@ function refuseIfFinalizePending(ctx, registryDir, force) {
         "then retry. Use --force to bypass.");
     process.exit(1);
 }
-async function runFinalize(command, config) {
+async function runFinalize(command, config, registryDir) {
     const slot = Number(command.slot);
     const ctx = detectWorktree();
     const logPath = setupLogPath(ctx.currentWorktree, config.runtimeDir);
     const appendLog = (message) => {
         appendFileSync(logPath, `${message}\n`);
     };
-    const registry = readSlots(ctx.mainWorktree, config.registryDir);
+    const registry = readSlots(ctx.mainWorktree, registryDir);
     const entry = registry.slots[String(slot)];
     if (!entry || resolve(entry.worktree) !== resolve(ctx.currentWorktree)) {
         appendLog(`FAILED: No matching slot ${slot} for worktree ${ctx.currentWorktree}.`);
@@ -193,7 +199,7 @@ async function runFinalize(command, config) {
     };
     try {
         await config.finalizeWorktree(setupContext);
-        markSlotReady(ctx.mainWorktree, config.registryDir, slot);
+        markSlotReady(ctx.mainWorktree, registryDir, slot);
         appendLog("============================================================");
         appendLog(`READY: branch ${branch} (slot ${slot})`);
         appendLog("============================================================");
@@ -201,14 +207,14 @@ async function runFinalize(command, config) {
     catch (err) {
         const message = err.message;
         const stack = err.stack ?? "";
-        markSlotFailed(ctx.mainWorktree, config.registryDir, slot, message);
+        markSlotFailed(ctx.mainWorktree, registryDir, slot, message);
         appendLog(`FAILED: ${message}`);
         if (stack)
             appendLog(stack);
         process.exit(1);
     }
 }
-function resolveTargetSlot(slotArg, config) {
+function resolveTargetSlot(slotArg, config, registryDir) {
     if (slotArg !== undefined) {
         const slot = Number(slotArg);
         const scheme = resolvePortScheme(config);
@@ -218,11 +224,11 @@ function resolveTargetSlot(slotArg, config) {
         }
         return slot;
     }
-    return resolveCurrentSlot(config.basePort, config.registryDir).slot;
+    return resolveCurrentSlot(config.basePort, registryDir).slot;
 }
-function printWorktreeInfo(config, slot, worktreeForLog, fallback) {
+function printWorktreeInfo(config, registryDir, slot, worktreeForLog, fallback) {
     const ctx = detectWorktree();
-    const registry = readSlots(ctx.mainWorktree, config.registryDir);
+    const registry = readSlots(ctx.mainWorktree, registryDir);
     const entry = registry.slots[String(slot)];
     const ports = resolvePortsFn(config)(slot);
     const owner = entry?.owner ?? fallback.owner;
@@ -252,10 +258,10 @@ function printWorktreeInfo(config, slot, worktreeForLog, fallback) {
         const elapsed = formatDuration(now - Date.parse(entry.createdAt));
         console.log(`Pending since ${elapsed} ago (tail ${setupLogPath})`);
     }
-    printDevServerBlock(config, ctx.mainWorktree, targetWorktree, now);
+    printDevServerBlock(config, registryDir, ctx.mainWorktree, targetWorktree, now);
 }
-function printDevServerBlock(config, mainWorktree, targetWorktree, now) {
-    const entry = findOwnEntry(mainWorktree, config.registryDir, targetWorktree);
+function printDevServerBlock(config, registryDir, mainWorktree, targetWorktree, now) {
+    const entry = findOwnEntry(mainWorktree, registryDir, targetWorktree);
     const liveEntries = entry
         ? Object.entries(entry.pids)
             .filter(([, pid]) => isProcessAlive(pid))
@@ -272,31 +278,31 @@ function printDevServerBlock(config, mainWorktree, targetWorktree, now) {
         console.log(`    log: ${join(targetWorktree, config.runtimeDir, "logs", `${name}.log`)}`);
     }
 }
-function runStatus(command, config) {
+function runStatus(command, config, registryDir) {
     if (command.slot !== undefined) {
-        const slot = resolveTargetSlot(command.slot, config);
+        const slot = resolveTargetSlot(command.slot, config, registryDir);
         const ctx = detectWorktree();
-        const entry = readSlots(ctx.mainWorktree, config.registryDir).slots[String(slot)];
+        const entry = readSlots(ctx.mainWorktree, registryDir).slots[String(slot)];
         if (!entry) {
             console.error(`Error: No slot ${slot} in registry.`);
             process.exit(1);
         }
-        printWorktreeInfo(config, slot, entry.worktree, { owner: entry.owner });
+        printWorktreeInfo(config, registryDir, slot, entry.worktree, { owner: entry.owner });
         return;
     }
-    const resolved = resolveCurrentSlot(config.basePort, config.registryDir);
-    printWorktreeInfo(config, resolved.slot, resolved.worktree, {
+    const resolved = resolveCurrentSlot(config.basePort, registryDir);
+    printWorktreeInfo(config, registryDir, resolved.slot, resolved.worktree, {
         owner: resolved.owner,
     });
 }
-function runList(config) {
+function runList(registryDir) {
     const ctx = detectWorktree();
-    const entries = Object.entries(readSlots(ctx.mainWorktree, config.registryDir).slots).sort(([a], [b]) => Number(a) - Number(b));
+    const entries = Object.entries(readSlots(ctx.mainWorktree, registryDir).slots).sort(([a], [b]) => Number(a) - Number(b));
     if (entries.length === 0) {
         console.log("No workspaces registered.");
         return;
     }
-    const liveSet = liveWorktrees(readDevServers(ctx.mainWorktree, config.registryDir));
+    const liveSet = liveWorktrees(readDevServers(ctx.mainWorktree, registryDir));
     const rows = entries.map(([port, e]) => ({
         slot: port,
         type: e.main ? "main" : "linked",
@@ -331,15 +337,15 @@ function runList(config) {
     for (const r of rows)
         console.log(fmt(r));
 }
-async function runWait(command, config) {
+async function runWait(command, config, registryDir) {
     // standalone `workspace wait` (no prior setup in this invocation) → print the full summary on success.
-    const slot = resolveTargetSlot(command.slot, config);
-    await waitForSlot(slot, config);
+    const slot = resolveTargetSlot(command.slot, config, registryDir);
+    await waitForSlot(slot, config, registryDir);
 }
-async function waitForSlot(slot, config, options = {}) {
+async function waitForSlot(slot, config, registryDir, options = {}) {
     const printSummary = options.printSummary ?? true;
     const ctx = detectWorktree();
-    const initial = readSlots(ctx.mainWorktree, config.registryDir).slots[String(slot)];
+    const initial = readSlots(ctx.mainWorktree, registryDir).slots[String(slot)];
     if (!initial) {
         console.error(`Error: No slot ${slot} in registry.`);
         process.exit(1);
@@ -348,7 +354,7 @@ async function waitForSlot(slot, config, options = {}) {
     // Poll slots.json — the finalize child writes `status` on success or failure. Tiny file, no
     // log-tailing race.
     for (;;) {
-        const entry = readSlots(ctx.mainWorktree, config.registryDir).slots[String(slot)];
+        const entry = readSlots(ctx.mainWorktree, registryDir).slots[String(slot)];
         if (!entry) {
             console.error(`Error: Slot ${slot} disappeared from registry.`);
             process.exit(1);
@@ -356,7 +362,7 @@ async function waitForSlot(slot, config, options = {}) {
         if (entry.status === "ready") {
             console.log("\n… ready");
             if (printSummary) {
-                printWorktreeInfo(config, slot, entry.worktree, {
+                printWorktreeInfo(config, registryDir, slot, entry.worktree, {
                     owner: entry.owner,
                 });
             }
@@ -371,10 +377,10 @@ async function waitForSlot(slot, config, options = {}) {
         await new Promise((r) => setTimeout(r, pollMs));
     }
 }
-async function handleRemove(command, ctx, run, config) {
+async function handleRemove(command, ctx, run, config, registryDir) {
     const verboseLog = makeVerboseLog(run.verbose);
     const removeHere = command.branch === undefined;
-    const registry = readSlots(ctx.mainWorktree, config.registryDir);
+    const registry = readSlots(ctx.mainWorktree, registryDir);
     const target = resolveRemoveTarget(command, ctx, registry);
     // 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.
@@ -383,18 +389,19 @@ async function handleRemove(command, ctx, run, config) {
             `Run 'workspace wait --slot ${target.slotPort}' to wait for it to finish (or fail), then retry the removal.`);
         process.exit(1);
     }
-    if (!command.noRemoteCheck) {
-        verifyBranchAbsentFromRemote(target.branch, run);
-    }
     const ownerSuffix = target.owner ? `, owner ${target.owner}` : "";
     if (!existsSync(target.worktreePath)) {
         console.warn(`Warning: Worktree directory ${target.worktreePath} not found. Cleaning up registry only.`);
         delete registry.slots[target.slotPort];
-        writeSlots(ctx.mainWorktree, config.registryDir, registry);
+        writeSlots(ctx.mainWorktree, registryDir, registry);
         console.log(`Removed registry entry for branch "${target.branch}" (slot ${target.slotPort}${ownerSuffix}).`);
         return;
     }
-    const targetEntry = findOwnEntry(ctx.mainWorktree, config.registryDir, target.worktreePath);
+    if (!command.force && isWorktreeDirty(target.worktreePath)) {
+        console.error(`Error: Uncommitted changes in ${target.worktreePath}. Commit or stash them, or pass --force.`);
+        process.exit(1);
+    }
+    const targetEntry = findOwnEntry(ctx.mainWorktree, registryDir, target.worktreePath);
     if (targetEntry) {
         stopTargetDevServer(config.devServerScript, target.worktreePath, verboseLog);
     }
@@ -409,8 +416,8 @@ async function handleRemove(command, ctx, run, config) {
         });
     }
     delete registry.slots[target.slotPort];
-    writeSlots(ctx.mainWorktree, config.registryDir, registry);
-    removeDevServerEntryByWorktree(ctx.mainWorktree, config.registryDir, target.worktreePath);
+    writeSlots(ctx.mainWorktree, registryDir, registry);
+    removeDevServerEntryByWorktree(ctx.mainWorktree, registryDir, target.worktreePath);
     if (removeHere) {
         process.chdir(ctx.mainWorktree);
     }
@@ -421,17 +428,17 @@ async function handleRemove(command, ctx, run, config) {
         console.log(`Now run: cd ${ctx.mainWorktree}`);
     }
 }
-function handleSetOwnerMode(command, ctx, config) {
+function handleSetOwnerMode(command, ctx, registryDir) {
     const newOwner = command.name;
     const { slotPort } = handleSetOwner({
         newOwner,
         currentWorktree: ctx.currentWorktree,
         mainWorktree: ctx.mainWorktree,
-        registryDir: config.registryDir,
+        registryDir,
         isMainWorktree: ctx.isMainWorktree,
     });
     // Propagate to dev-servers.json entries for this worktree.
-    const devServersPath = join(ctx.mainWorktree, config.registryDir, "dev-servers.json");
+    const devServersPath = join(ctx.mainWorktree, registryDir, "dev-servers.json");
     if (existsSync(devServersPath)) {
         const data = JSON.parse(readFileSync(devServersPath, "utf-8"));
         let changed = false;
@@ -452,11 +459,61 @@ function handleSetOwnerMode(command, ctx, config) {
     }
     console.log(`Owner for slot ${slotPort}: ${newOwner ?? "(none)"}`);
 }
+/** Transitional (0.16 only): merge a pre-0.16 registry into `${runtimeDir}/shared-registry`. */
+function handleMigrate(command, config, newRel) {
+    const ctx = detectWorktree();
+    const oldRel = command.oldRegistryDir;
+    const oldAbs = join(ctx.mainWorktree, oldRel);
+    if (resolve(oldAbs) === resolve(join(ctx.mainWorktree, newRel))) {
+        console.log(`Registry already at ${newRel}; relinking worktrees.`);
+        relinkWorktrees(readSlots(ctx.mainWorktree, newRel), ctx.mainWorktree, config.runtimeDir);
+        return;
+    }
+    refuseUnlessOldRegistry(oldAbs, ctx.mainWorktree);
+    const mergedSlots = mergeSlots(readSlots(ctx.mainWorktree, oldRel), readSlots(ctx.mainWorktree, newRel));
+    writeSlots(ctx.mainWorktree, newRel, mergedSlots);
+    const mergedDevServers = mergeDevServers(readDevServers(ctx.mainWorktree, oldRel), readDevServers(ctx.mainWorktree, newRel));
+    writeDevServers(ctx.mainWorktree, newRel, mergedDevServers);
+    rmSync(oldAbs, { recursive: true, force: true });
+    const relinked = relinkWorktrees(mergedSlots, ctx.mainWorktree, config.runtimeDir);
+    console.log(`Migrated ${oldRel} → ${newRel}: ${Object.keys(mergedSlots.slots).length} slot(s), ` +
+        `${mergedDevServers.servers.length} dev-server(s); ${relinked} symlink(s) recreated.`);
+}
+/** `oldAbs` is recursively deleted after the merge — refuse anything that isn't clearly a registry. */
+function refuseUnlessOldRegistry(oldAbs, mainWorktree) {
+    const fromMain = relative(mainWorktree, resolve(oldAbs));
+    if (fromMain.startsWith("..") || isAbsolute(fromMain)) {
+        console.error(`Error: the old registry must be inside the main worktree; got ${oldAbs}.`);
+        process.exit(1);
+    }
+    if (!existsSync(oldAbs)) {
+        console.error(`Error: nothing to migrate at ${oldAbs}.`);
+        process.exit(1);
+    }
+    if (!existsSync(join(oldAbs, "slots.json")) && !existsSync(join(oldAbs, "dev-servers.json"))) {
+        console.error(`Error: ${oldAbs} does not look like a registry (no slots.json or dev-servers.json).`);
+        process.exit(1);
+    }
+}
+function relinkWorktrees(slots, mainWorktree, runtimeDir) {
+    let count = 0;
+    for (const entry of Object.values(slots.slots)) {
+        if (entry.main)
+            continue;
+        if (!existsSync(entry.worktree)) {
+            console.warn(`Warning: worktree ${entry.worktree} not found; skipping symlink.`);
+            continue;
+        }
+        linkSharedRegistry({ currentWorktree: entry.worktree, mainWorktree, isMainWorktree: false }, runtimeDir, console.log, { force: true });
+        ++count;
+    }
+    return count;
+}
 function ensureWorktree(command, ctx, run, dirNameFn) {
     if (command.branch === undefined)
         return ctx;
     if (command.newBranch)
-        return createBranch(command.branch, ctx, run, dirNameFn);
+        return createBranch(command.branch, ctx, run, dirNameFn, command.from);
     return useExistingBranch(command.branch, ctx, run, dirNameFn);
 }
 function linkSharedDirectories(ctx, dirs, log) {
@@ -476,6 +533,36 @@ function linkSharedDirectories(ctx, dirs, log) {
         }
     }
 }
+/**
+ * Symlinks the linked worktree's `${runtimeDir}/shared-registry` to the main worktree's, so the
+ * cwd-relative registry read in `resolveCurrentSlot` reaches main. `runtimeDir` is per-worktree and
+ * not in `sharedDirs`, so this is distinct from {@link linkSharedDirectories}.
+ */
+function linkSharedRegistry(ctx, runtimeDir, log, opts) {
+    if (ctx.isMainWorktree)
+        return;
+    const mainDir = join(ctx.mainWorktree, runtimeDir, REGISTRY_SUBDIR);
+    mkdirSync(mainDir, { recursive: true });
+    const runtimeRoot = join(ctx.currentWorktree, runtimeDir);
+    mkdirSync(runtimeRoot, { recursive: true });
+    const link = join(runtimeRoot, REGISTRY_SUBDIR);
+    // lstat, not existsSync: existsSync follows symlinks, so a broken one would read as absent and
+    // make symlinkSync throw EEXIST. A broken symlink is recreated even without `force`.
+    const linkStat = lstatSync(link, { throwIfNoEntry: false });
+    if (linkStat) {
+        if (!linkStat.isSymbolicLink()) {
+            log("Skipped shared-registry symlink (a real directory exists here).");
+            return;
+        }
+        if (!opts?.force && existsSync(link)) {
+            log("Skipped shared-registry symlink (already exists).");
+            return;
+        }
+        rmSync(link);
+    }
+    symlinkSync(relative(runtimeRoot, mainDir), link);
+    log("Created shared-registry symlink → main worktree.");
+}
 function generateConfigFiles(ctx, entries, slot, ports, force, log) {
     for (const entry of entries) {
         const patchCtx = {

package/dist/worktree.d.ts

@@ -1,4 +1,3 @@
-import type { WorkspaceCommand } from "./cli.js";
 export interface WorktreeContext {
     currentWorktree: string;
     mainWorktree: string;
@@ -8,10 +7,9 @@ export interface RunCtx {
     verbose: boolean;
 }
 export declare function detectWorktree(): WorktreeContext;
-export declare function enforceWorktreeMode(command: WorkspaceCommand, ctx: WorktreeContext): void;
 export declare function useExistingBranch(branch: string, ctx: WorktreeContext, run: RunCtx, dirNameFn?: WorktreeDirNameFn): WorktreeContext;
-export declare function createBranch(requestedBranch: string, ctx: WorktreeContext, run: RunCtx, dirNameFn?: WorktreeDirNameFn): WorktreeContext;
-export declare function verifyBranchAbsentFromRemote(branch: string, run: RunCtx): void;
+export declare function createBranch(requestedBranch: string, ctx: WorktreeContext, run: RunCtx, dirNameFn?: WorktreeDirNameFn, from?: string): WorktreeContext;
+export declare function isWorktreeDirty(worktreePath: string): boolean;
 export declare function getWorktreeBranch(worktreePath: string): string | undefined;
 export declare function removeWorktree(worktreePath: string, run: RunCtx): void;
 /** Pure function that produces the basename of a worktree directory from a branch. */

package/dist/worktree.js

@@ -10,14 +10,6 @@ export function detectWorktree() {
     const isMainWorktree = resolve(currentWorktree) === resolve(mainWorktree);
     return { currentWorktree, mainWorktree, isMainWorktree };
 }
-export function enforceWorktreeMode(command, ctx) {
-    // Adding a worktree for a branch must happen from the main worktree. A branch-less
-    // `workspace setup` runs anywhere: linked worktree (retry path) or main (initial bootstrap).
-    if (command.kind === "setup" && command.branch !== undefined && !ctx.isMainWorktree) {
-        console.error("Error: Adding a workspace for a branch must be run from the main worktree.");
-        process.exit(1);
-    }
-}
 export function useExistingBranch(branch, ctx, run, dirNameFn = defaultWorktreeDirName) {
     if (!branchExists(branch)) {
         console.error(`Error: Branch "${branch}" does not exist locally or on the remote.`);
@@ -27,7 +19,9 @@ export function useExistingBranch(branch, ctx, run, dirNameFn = defaultWorktreeD
     execFileSync("git", ["worktree", "add", worktreePath, branch], { stdio: stdioFor(run) });
     return { ...ctx, currentWorktree: worktreePath, isMainWorktree: false };
 }
-export function createBranch(requestedBranch, ctx, run, dirNameFn = defaultWorktreeDirName) {
+export function createBranch(requestedBranch, ctx, run, dirNameFn = defaultWorktreeDirName, from) {
+    if (from !== undefined)
+        verifyFromRef(from);
     let finalBranch = requestedBranch;
     if (branchExists(finalBranch)) {
         let suffix = 2;
@@ -38,18 +32,36 @@ export function createBranch(requestedBranch, ctx, run, dirNameFn = defaultWorkt
         console.warn(`Warning: Branch "${requestedBranch}" already exists; using "${finalBranch}" instead.`);
     }
     const worktreePath = dedupeWorktreePath(computeWorktreePath(ctx.mainWorktree, finalBranch, dirNameFn));
-    execFileSync("git", ["worktree", "add", "-b", finalBranch, worktreePath], {
-        stdio: stdioFor(run),
-    });
+    const addArgs = ["worktree", "add", "-b", finalBranch, "--end-of-options", worktreePath];
+    if (from !== undefined)
+        addArgs.push(from);
+    execFileSync("git", addArgs, { stdio: stdioFor(run) });
     return { ...ctx, currentWorktree: worktreePath, isMainWorktree: false };
 }
-export function verifyBranchAbsentFromRemote(branch, run) {
-    execFileSync("git", ["fetch"], { stdio: stdioFor(run) });
-    const remoteBranches = execFileSync("git", ["branch", "-r", "--list", `origin/${branch}`], {
-        encoding: "utf-8",
-    }).trim();
-    if (remoteBranches.length > 0) {
-        console.error(`Error: Branch "${branch}" still exists on the remote. Use --no-remote-check to skip this verification.`);
+function verifyFromRef(from) {
+    try {
+        // `^{commit}` accepts any commit-ish: branch, origin/x, tag, SHA.
+        // `--end-of-options` guards against option-like refs (rev-parse treats args after `--` as paths).
+        execFileSync("git", ["rev-parse", "--verify", "--end-of-options", `${from}^{commit}`], {
+            stdio: "pipe",
+        });
+    }
+    catch {
+        console.error(`Error: --from ref "${from}" does not resolve to a commit.`);
+        process.exit(1);
+    }
+}
+export function isWorktreeDirty(worktreePath) {
+    try {
+        const out = execFileSync("git", ["status", "--porcelain"], {
+            stdio: "pipe",
+            cwd: worktreePath,
+            encoding: "utf-8",
+        });
+        return out.trim().length > 0;
+    }
+    catch {
+        console.error(`Error: Cannot check for uncommitted changes in ${worktreePath}. Pass --force to remove anyway.`);
         process.exit(1);
     }
 }

package/package.json

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