@paleo/workspace 0.15.1 → 0.17.0

package/README.md

@@ -27,7 +27,7 @@ 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                             # foreground: stream logs from startup, CTRL+C stops; attaches if already running (CTRL+C then detaches)
+npm run dev                             # foreground: stream logs, CTRL+C stops; attaches if already running
 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
@@ -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

@@ -25,6 +25,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\`.`);
     }
@@ -140,6 +142,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.`);
@@ -287,7 +299,7 @@ export function printDevHelp() {
         "",
         "Commands:",
         "  dev               Start in the foreground, streaming logs from startup; CTRL+C stops it.",
-        "                    If one is already running here, attach to its logs instead",
+        "                    If one is already running here, attach to its logs instead.",
         "  dev up            Start in the background and return once ready.",
         "  dev restart       Stop this worktree's dev-server if running, then start in the background.",
         "  dev down [--all]  Stop this worktree's dev-server, or every dev-server with --all.",

package/dist/dev-server.d.ts

@@ -1,3 +1,4 @@
+import { StartupError } from "./errors.js";
 import type { CallbackServer, ServerContext, ServerDescriptor, SpawnServer } from "./server-descriptor.js";
 import { type ResolvedSlot, type SlotEntry } from "./slots.js";
 export type { CallbackServer, ServerContext, ServerDescriptor, SpawnServer };
@@ -7,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. */
@@ -33,6 +28,12 @@ export interface DevServerSummaryContext {
     }[];
 }
 export declare function runDevServer(config: DevServerConfig): Promise<void>;
+/**
+ * Wraps an error thrown by a callback server's `start()` into a {@link StartupError}, so a failing
+ * callback (e.g. `docker compose up -d`) gets the same clean rollback-and-report path as a spawn
+ * server instead of surfacing as a raw unhandled-rejection stack trace.
+ */
+export declare function toCallbackStartupError(name: string, err: unknown): StartupError;
 /**
  * Poll the foreground's own spawn PIDs; when none remain alive, the servers were stopped from
  * outside this process (`dev down`, `down --all`, eviction, or a manual kill). Fires `onStopped`

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;
 }
@@ -207,6 +212,16 @@ async function spawnWithRollback(config, ctx, state, isAborted = () => false, on
     }
     return !isAborted();
 }
+/**
+ * Wraps an error thrown by a callback server's `start()` into a {@link StartupError}, so a failing
+ * callback (e.g. `docker compose up -d`) gets the same clean rollback-and-report path as a spawn
+ * server instead of surfacing as a raw unhandled-rejection stack trace.
+ */
+export function toCallbackStartupError(name, err) {
+    if (err instanceof StartupError)
+        return err;
+    return new StartupError(name, err instanceof Error ? err.message : String(err));
+}
 async function spawnAndAwait(config, ctx, state, onSpawned) {
     for (const server of config.servers) {
         console.log(`Starting ${server.name} dev server...`);
@@ -214,7 +229,12 @@ async function spawnAndAwait(config, ctx, state, onSpawned) {
             state.spawnPids[server.name] = spawnServer(server, config.runtimeDir, ctx.cwd);
         }
         else {
-            await server.start(ctx);
+            try {
+                await server.start(ctx);
+            }
+            catch (err) {
+                throw toCallbackStartupError(server.name, err);
+            }
             state.startedCallbacks.push(server);
         }
     }
@@ -229,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,
@@ -240,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) {
@@ -367,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,
@@ -387,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));
@@ -396,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(", ");
@@ -407,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) {
@@ -425,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,
     });
@@ -467,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)) {
@@ -478,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);
@@ -504,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/helpers.d.ts

@@ -14,10 +14,15 @@ export declare function readPortFromEnvFile(file: string, varName: string): numb
 export declare function readPortFromJsonFile(file: string, jsonPath: string): number;
 export interface CopyAndPatchCtx {
     currentWorktree: string;
-    mainWorktree: string;
     log: (msg: string) => void;
 }
-export declare function copyAndPatchFile(ctx: CopyAndPatchCtx, relPath: string, patchFn: (content: string) => string, label: string, force: boolean, optional?: boolean): void;
+/** Resolved initial-content source for {@link copyAndPatchFile}. `path` is absolute. */
+export type ResolvedFileSource = {
+    path: string;
+} | {
+    content: string;
+};
+export declare function copyAndPatchFile(ctx: CopyAndPatchCtx, relPath: string, source: ResolvedFileSource, patchFn: (content: string) => string, label: string, force: boolean, optional?: boolean): void;
 /**
  * Formats a millisecond duration as the two largest units among `d`/`h`/`m`/`s`.
  * Drops the smaller unit when zero (`5d` instead of `5d 0h`). Sub-second values

package/dist/helpers.js

@@ -67,24 +67,29 @@ export function readPortFromJsonFile(file, jsonPath) {
     }
     return toPort(String(cur), file);
 }
-export function copyAndPatchFile(ctx, relPath, patchFn, label, force, optional = false) {
+export function copyAndPatchFile(ctx, relPath, source, patchFn, label, force, optional = false) {
     const targetPath = join(ctx.currentWorktree, relPath);
-    const sourcePath = join(ctx.mainWorktree, relPath);
     const alreadyExists = existsSync(targetPath);
     if (alreadyExists && !force) {
         ctx.log(`Skipped ${label} (already exists; use --force to overwrite).`);
         return;
     }
-    if (!existsSync(sourcePath)) {
-        if (!optional) {
-            console.error(`Error: ${relPath} not found in main worktree. Bootstrap the main worktree first ` +
-                "(`workspace setup`), or mark the entry as optional.");
-            process.exit(1);
+    let content;
+    if ("content" in source) {
+        content = source.content;
+    }
+    else {
+        if (!existsSync(source.path)) {
+            if (!optional) {
+                console.error(`Error: source ${source.path} not found. Bootstrap the main worktree first ` +
+                    "(`workspace setup`), provide a `source`, or mark the entry as optional.");
+                process.exit(1);
+            }
+            ctx.log(`Warning: source ${source.path} not found, skipping (optional).`);
+            return;
         }
-        ctx.log(`Warning: ${relPath} not found in main worktree, skipping (optional).`);
-        return;
+        content = readFileSync(source.path, "utf-8");
     }
-    const content = readFileSync(sourcePath, "utf-8");
     const patched = patchFn(content);
     mkdirSync(dirname(targetPath), { recursive: true });
     writeFileSync(targetPath, patched);

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { runWorkspace } from "./workspace.js";
 export { defaultWorktreeDirName } from "./worktree.js";
 export type { WorktreeDirNameFn } from "./worktree.js";
-export type { WorkspaceConfig, SetupContext, SummaryContext, PatchContext, ConfigFileEntry, PurgeContext, } from "./workspace.js";
+export type { WorkspaceConfig, SetupContext, SummaryContext, PatchContext, ConfigFileEntry, ConfigFileSource, ConfigFileSourceSpec, PurgeContext, } from "./workspace.js";
 export { runDevServer } from "./dev-server.js";
 export type { DevServerConfig, DevServerSummaryContext, ServerDescriptor, ServerContext, SpawnServer, CallbackServer, } from "./dev-server.js";
 export type { ResolvedSlot } from "./slots.js";

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[];
     /**
@@ -121,16 +115,38 @@ export interface PurgeContext {
     mainWorktree: string;
     verbose: boolean;
 }
-/** One config file copied from the main worktree and patched per slot. */
+/** A `{ path }` (relative to the main worktree) or `{ content }` (verbatim) initial source. */
+export type ConfigFileSourceSpec = {
+    path: string;
+} | {
+    content: string;
+};
+/**
+ * Overrides where a {@link ConfigFileEntry}'s initial content comes from. Defaults to reading
+ * `entry.path` from the main worktree.
+ *
+ * - `{ path }` — read this path (relative to the main worktree) instead of `entry.path`,
+ *   e.g. seed from a committed example: `{ path: "packages/api/.env.local.example" }`.
+ * - `{ content }` — use this string as the initial content verbatim.
+ * - a callback returning either of the above, resolved per worktree with the same
+ *   {@link PatchContext} the `patch` callback receives.
+ */
+export type ConfigFileSource = ConfigFileSourceSpec | ((ctx: PatchContext) => ConfigFileSourceSpec);
+/** One config file seeded from its source (the main worktree by default) and patched per slot. */
 export interface ConfigFileEntry {
-    /** Path relative to the worktree root. Same path is read from main and written to current. */
+    /** Path relative to the worktree root. Written to the current worktree. */
     path: string;
+    /**
+     * Overrides the initial content's source. Defaults to reading `path` from the main worktree.
+     * Use this to seed from a committed example or supplied content instead. See {@link ConfigFileSource}.
+     */
+    source?: ConfigFileSource;
     /** Returns the patched content given the source content and the slot's ports. */
     patch: (content: string, ctx: PatchContext) => string;
     /**
-     * When `true`, a missing source on the main worktree logs a warning and skips the entry.
+     * When `true`, a missing `{ path }` source logs a warning and skips the entry.
      * Default: required (missing source aborts setup). Bootstrap the main worktree first via
-     * `workspace setup`, or seed sources in `preSetup`.
+     * `workspace setup`, or seed sources in `preSetup`. Ignored for `{ content }` sources.
      */
     optional?: boolean;
 }

package/dist/workspace.js

@@ -1,13 +1,13 @@
 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 { 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 { handleSetOwner, markSlotFailed, markSlotReady, mergeSlots, readSlots, REGISTRY_SUBDIR, registryDirFor, resolveAndRegisterSlot, resolveCurrentSlot, validateSlotAvailability, warnLegacyRegistryDir, writeSlots, } from "./slots.js";
 import { createBranch, detectWorktree, enforceWorktreeMode, getWorktreeBranch, removeWorktree, useExistingBranch, verifyBranchAbsentFromRemote, } from "./worktree.js";
 export async function runWorkspace(config) {
     let command;
@@ -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,16 +40,16 @@ 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();
@@ -51,36 +57,36 @@ export async function runWorkspace(config) {
     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 +123,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 +166,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 +200,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 +208,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 +225,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 +259,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 +279,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 +338,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 +355,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 +363,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 +378,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.
@@ -390,11 +397,11 @@ async function handleRemove(command, ctx, run, config) {
     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);
+    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,6 +459,56 @@ 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;
@@ -476,16 +533,55 @@ 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) {
-        copyAndPatchFile({ currentWorktree: ctx.currentWorktree, mainWorktree: ctx.mainWorktree, log }, entry.path, (content) => entry.patch(content, {
+        const patchCtx = {
             slot,
             ports,
             mainWorktree: ctx.mainWorktree,
             currentWorktree: ctx.currentWorktree,
-        }), entry.path, force, entry.optional ?? false);
+        };
+        copyAndPatchFile({ currentWorktree: ctx.currentWorktree, log }, entry.path, resolveConfigSource(entry, patchCtx), (content) => entry.patch(content, patchCtx), entry.path, force, entry.optional ?? false);
     }
 }
+function resolveConfigSource(entry, ctx) {
+    const spec = typeof entry.source === "function" ? entry.source(ctx) : entry.source;
+    if (spec === undefined)
+        return { path: join(ctx.mainWorktree, entry.path) };
+    if ("content" in spec)
+        return { content: spec.content };
+    return { path: join(ctx.mainWorktree, spec.path) };
+}
 function resolveRemoveTarget(command, ctx, registry) {
     if (command.branch === undefined) {
         if (ctx.isMainWorktree) {

package/package.json

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