@paperclipai/shared 2026.824.1 → 2026.825.0-beta.1

package/dist/worktree-port-registry.test.js

@@ -0,0 +1,118 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { afterEach, describe, expect, it } from "vitest";
+import { withWorktreePortRegistryLock, withWorktreePortRegistryLockSync, } from "./worktree-port-registry.js";
+const temporaryRoots = [];
+function makeTemporaryRoot() {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-port-registry-lock-"));
+    temporaryRoots.push(root);
+    return root;
+}
+function deferred() {
+    let resolve;
+    const promise = new Promise((done) => {
+        resolve = done;
+    });
+    return { promise, resolve };
+}
+afterEach(() => {
+    for (const root of temporaryRoots.splice(0)) {
+        fs.rmSync(root, { recursive: true, force: true });
+    }
+});
+describe("worktree port registry lock", () => {
+    it("does not reclaim a stale lock while its fallback ownership probe responds", async () => {
+        const homeDir = makeTemporaryRoot();
+        const lockPath = path.join(homeDir, ".worktree-port-reservations.lock");
+        const firstEntered = deferred();
+        const releaseFirst = deferred();
+        let secondEntered = false;
+        const first = withWorktreePortRegistryLock(homeDir, async () => {
+            fs.renameSync(path.join(lockPath, "owner.json"), path.join(lockPath, "owner.unavailable.json"));
+            const backupOwnerPath = path.join(lockPath, "owner.backup.json");
+            const owner = JSON.parse(fs.readFileSync(backupOwnerPath, "utf8"));
+            fs.writeFileSync(backupOwnerPath, `${JSON.stringify({
+                ...owner,
+                processIdentity: "unavailable-process-identity",
+            })}\n`);
+            const oldTimestamp = new Date(Date.now() - 10_000);
+            fs.utimesSync(lockPath, oldTimestamp, oldTimestamp);
+            firstEntered.resolve();
+            await releaseFirst.promise;
+        });
+        await firstEntered.promise;
+        expect(Date.now() - fs.statSync(lockPath).mtimeMs).toBeGreaterThan(5_000);
+        const second = withWorktreePortRegistryLock(homeDir, async () => {
+            secondEntered = true;
+        });
+        await delay(100);
+        expect(secondEntered).toBe(false);
+        releaseFirst.resolve();
+        await Promise.all([first, second]);
+        expect(secondEntered).toBe(true);
+    }, 10_000);
+    it("refreshes the lease throughout an async critical section", async () => {
+        const homeDir = makeTemporaryRoot();
+        const lockPath = path.join(homeDir, ".worktree-port-reservations.lock");
+        await withWorktreePortRegistryLock(homeDir, async () => {
+            await delay(5_250);
+            expect(Date.now() - fs.statSync(lockPath).mtimeMs).toBeLessThan(2_000);
+        });
+        expect(fs.existsSync(lockPath)).toBe(false);
+    }, 10_000);
+    it("reclaims an old lock after its owner process exits", async () => {
+        const homeDir = makeTemporaryRoot();
+        const lockPath = path.join(homeDir, ".worktree-port-reservations.lock");
+        fs.mkdirSync(lockPath);
+        fs.writeFileSync(path.join(lockPath, "owner.json"), `${JSON.stringify({
+            version: 1,
+            pid: 2_147_483_647,
+            processIdentity: "dead-process",
+            probePort: 1,
+            token: "dead-owner",
+        })}\n`);
+        const oldTimestamp = new Date(Date.now() - 10_000);
+        fs.utimesSync(lockPath, oldTimestamp, oldTimestamp);
+        let entered = false;
+        await withWorktreePortRegistryLock(homeDir, async () => {
+            entered = true;
+        });
+        expect(entered).toBe(true);
+        expect(fs.existsSync(lockPath)).toBe(false);
+    });
+    it("reclaims an old lock when its pid belongs to a different process", async () => {
+        const homeDir = makeTemporaryRoot();
+        const lockPath = path.join(homeDir, ".worktree-port-reservations.lock");
+        fs.mkdirSync(lockPath);
+        fs.writeFileSync(path.join(lockPath, "owner.json"), `${JSON.stringify({
+            version: 1,
+            pid: process.pid,
+            processIdentity: "reused-pid-owner",
+            probePort: 1,
+            token: "abandoned-owner",
+        })}\n`);
+        const oldTimestamp = new Date(Date.now() - 10_000);
+        fs.utimesSync(lockPath, oldTimestamp, oldTimestamp);
+        let entered = false;
+        await withWorktreePortRegistryLock(homeDir, async () => {
+            entered = true;
+        });
+        expect(entered).toBe(true);
+        expect(fs.existsSync(lockPath)).toBe(false);
+    });
+    it("refreshes the lease while a synchronous critical section blocks the main thread", () => {
+        const homeDir = makeTemporaryRoot();
+        const lockPath = path.join(homeDir, ".worktree-port-reservations.lock");
+        const blocker = new Int32Array(new SharedArrayBuffer(4));
+        withWorktreePortRegistryLockSync(homeDir, () => {
+            const oldTimestamp = new Date(Date.now() - 10_000);
+            fs.utimesSync(lockPath, oldTimestamp, oldTimestamp);
+            Atomics.wait(blocker, 0, 0, 1_500);
+            expect(Date.now() - fs.statSync(lockPath).mtimeMs).toBeLessThan(1_250);
+        });
+        expect(fs.existsSync(lockPath)).toBe(false);
+    });
+});
+//# sourceMappingURL=worktree-port-registry.test.js.map

package/dist/worktree-port-registry.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-port-registry.test.js","sourceRoot":"","sources":["../src/worktree-port-registry.test.ts"],"names":[],"mappings":"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"}

package/dist/worktree-seed-source.d.ts

@@ -0,0 +1,43 @@
+export type WorktreeSeedSourceDiagnostic = {
+    configPath?: unknown;
+    instanceId?: unknown;
+};
+export type CanonicalWorktreeSeedSource = {
+    baseWorkspaceCwd: string | null;
+    configPath: string;
+    instanceId: string;
+    targetConfigPath: string;
+    targetInstanceId: string;
+};
+export type RegisteredWorktreeSeedSourceInput = {
+    registeredBaseWorkspaceCwd?: string | null;
+    explicitSourceConfigPath?: string | null;
+    targetConfigPath: string;
+    expectedTargetInstanceId: string;
+};
+/**
+ * Whether a base project workspace declares an instance config of its own.
+ *
+ * This tests directory entries and does not follow them. A dangling or aliased symlink,
+ * at the config itself or at the `.paperclip` directory holding it, still counts as a
+ * declared config, so the resolver rejects the malformed source instead of falling back
+ * to another one.
+ */
+export declare function baseWorkspaceDeclaresInstanceConfig(baseWorkspaceCwd: string): boolean;
+/** Resolve the authoritative source and target identities without consulting diagnostics. */
+export declare function resolveRegisteredWorktreeSeedSource(input: RegisteredWorktreeSeedSourceInput): CanonicalWorktreeSeedSource;
+/**
+ * Resolve a worktree seed source without granting authority to the seed manifest.
+ *
+ * A managed caller supplies the project-workspace cwd from its server-owned row.
+ * An operator may instead supply an explicit source config. A base workspace that
+ * carries its own `.paperclip/config.json` stays authoritative, so an explicit path
+ * must equal it; a base workspace that is a plain checkout has none, and the explicit
+ * path supplies the source. Manifest source fields are diagnostic assertions only and
+ * never select the returned source.
+ */
+export declare function resolveCanonicalWorktreeSeedSource(input: RegisteredWorktreeSeedSourceInput & {
+    manifestSource: WorktreeSeedSourceDiagnostic | null | undefined;
+    manifestTargetInstanceId?: unknown;
+}): CanonicalWorktreeSeedSource;
+//# sourceMappingURL=worktree-seed-source.d.ts.map

package/dist/worktree-seed-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-seed-source.d.ts","sourceRoot":"","sources":["../src/worktree-seed-source.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,4BAA4B,GAAG;IACzC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,iCAAiC,GAAG;IAC9C,0BAA0B,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,wBAAwB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,gBAAgB,EAAE,MAAM,CAAC;IACzB,wBAAwB,EAAE,MAAM,CAAC;CAClC,CAAC;AA6CF;;;;;;;GAOG;AACH,wBAAgB,mCAAmC,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAmBrF;AAmBD,6FAA6F;AAC7F,wBAAgB,mCAAmC,CACjD,KAAK,EAAE,iCAAiC,GACvC,2BAA2B,CAyE7B;AAED;;;;;;;;;GASG;AACH,wBAAgB,kCAAkC,CAAC,KAAK,EAAE,iCAAiC,GAAG;IAC5F,cAAc,EAAE,4BAA4B,GAAG,IAAI,GAAG,SAAS,CAAC;IAChE,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACpC,GAAG,2BAA2B,CAsB9B"}

package/dist/worktree-seed-source.js

@@ -0,0 +1,180 @@
+import { existsSync, lstatSync, readFileSync, realpathSync, statSync } from "node:fs";
+import path from "node:path";
+import { resolvePaperclipInstanceId } from "./home-paths.js";
+function readInstanceId(configPath, label) {
+    const configDir = path.dirname(configPath);
+    const envPath = path.join(configDir, ".env");
+    if (!existsSync(envPath)) {
+        // An instance-root config (`<home>/instances/<id>/config.json`) names its instance
+        // by directory rather than by an adjacent .env; worktree configs always ship one.
+        if (path.basename(path.dirname(configDir)) === "instances") {
+            return resolvePaperclipInstanceId(path.basename(configDir));
+        }
+        throw new Error(`Registered ${label} Paperclip config is missing its adjacent .env instance pointer.`);
+    }
+    const contents = readFileSync(envPath, "utf8");
+    for (const rawLine of contents.split(/\r?\n/)) {
+        const match = rawLine.match(/^\s*(?:export\s+)?PAPERCLIP_INSTANCE_ID\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s#]+))/);
+        const value = (match?.[1] ?? match?.[2] ?? match?.[3] ?? "").trim();
+        if (value)
+            return value;
+    }
+    throw new Error(`Registered ${label} Paperclip config has no PAPERCLIP_INSTANCE_ID binding.`);
+}
+function errorCode(error) {
+    return error?.code ?? "unknown error";
+}
+/**
+ * Inspect a directory entry without following it, returning null only when it is absent.
+ *
+ * Any other failure means the declared path is unreadable or malformed, and a guess there
+ * would silently seed from a different instance.
+ */
+function inspectDeclaredEntry(entryPath, configPath, detail) {
+    try {
+        return lstatSync(entryPath);
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT")
+            return null;
+        throw new Error(`Registered base project workspace Paperclip config at ${configPath} cannot be inspected (${errorCode(error)}${detail ?? ""}).`);
+    }
+}
+/**
+ * Whether a base project workspace declares an instance config of its own.
+ *
+ * This tests directory entries and does not follow them. A dangling or aliased symlink,
+ * at the config itself or at the `.paperclip` directory holding it, still counts as a
+ * declared config, so the resolver rejects the malformed source instead of falling back
+ * to another one.
+ */
+export function baseWorkspaceDeclaresInstanceConfig(baseWorkspaceCwd) {
+    const configDir = path.join(baseWorkspaceCwd, ".paperclip");
+    const configPath = path.join(configDir, "config.json");
+    if (inspectDeclaredEntry(configPath, configPath))
+        return true;
+    // The probe above resolves `.paperclip` before it reaches the config, so a broken link
+    // there also reports ENOENT. Only an absent or traversable `.paperclip` lets the caller
+    // name another source; a link that hides whatever it points at is malformed, not empty.
+    const configDirEntry = inspectDeclaredEntry(configDir, configPath, " on its .paperclip entry");
+    if (configDirEntry?.isSymbolicLink()) {
+        try {
+            statSync(configDir);
+        }
+        catch (error) {
+            throw new Error(`Registered base project workspace Paperclip config at ${configPath} cannot be inspected (${errorCode(error)} on its .paperclip symlink target).`);
+        }
+    }
+    return false;
+}
+function canonicalRegularFile(filePath, label) {
+    const resolved = path.resolve(filePath);
+    let canonical;
+    try {
+        canonical = realpathSync(resolved);
+    }
+    catch {
+        throw new Error(`${label} does not exist at ${resolved}.`);
+    }
+    if (canonical !== resolved || lstatSync(resolved).isSymbolicLink()) {
+        throw new Error(`${label} must be a canonical path and cannot use a symlink alias.`);
+    }
+    if (!lstatSync(canonical).isFile()) {
+        throw new Error(`${label} is not a regular file at ${canonical}.`);
+    }
+    return canonical;
+}
+/** Resolve the authoritative source and target identities without consulting diagnostics. */
+export function resolveRegisteredWorktreeSeedSource(input) {
+    const registeredCwd = input.registeredBaseWorkspaceCwd?.trim();
+    const explicitSource = input.explicitSourceConfigPath?.trim();
+    if (!registeredCwd && !explicitSource) {
+        throw new Error("Worktree seed source is not registered. Managed boot requires a project workspace; manual boot requires --from-config.");
+    }
+    let canonicalBaseCwd = null;
+    let registeredConfigPath = null;
+    if (registeredCwd) {
+        const resolvedRegisteredCwd = path.resolve(registeredCwd);
+        try {
+            canonicalBaseCwd = realpathSync(resolvedRegisteredCwd);
+        }
+        catch {
+            throw new Error(`Registered base project workspace does not exist at ${resolvedRegisteredCwd}.`);
+        }
+        if (canonicalBaseCwd !== resolvedRegisteredCwd) {
+            throw new Error("Registered base project workspace must be canonical and cannot use a symlink alias.");
+        }
+        if (!lstatSync(canonicalBaseCwd).isDirectory()) {
+            throw new Error(`Registered base project workspace is not a directory at ${canonicalBaseCwd}.`);
+        }
+        // A base workspace that is a plain checkout carries no instance config of its own.
+        // The caller's explicit source supplies it, and stays subject to every check below.
+        registeredConfigPath = baseWorkspaceDeclaresInstanceConfig(canonicalBaseCwd)
+            ? path.join(canonicalBaseCwd, ".paperclip", "config.json")
+            : null;
+    }
+    const selectedPath = registeredConfigPath ?? explicitSource;
+    if (!selectedPath) {
+        throw new Error("Registered base project workspace has no Paperclip config of its own and no explicit source was provided.");
+    }
+    const canonicalSourceConfigPath = canonicalRegularFile(selectedPath, "Registered source Paperclip config");
+    if (registeredConfigPath && canonicalSourceConfigPath !== registeredConfigPath) {
+        throw new Error("Registered source Paperclip config escapes the base project workspace or uses a symlink alias.");
+    }
+    if (explicitSource) {
+        const canonicalExplicitSource = canonicalRegularFile(explicitSource, "Explicit source Paperclip config");
+        if (canonicalExplicitSource !== canonicalSourceConfigPath) {
+            throw new Error("Explicit source Paperclip config does not match the registered base project workspace.");
+        }
+    }
+    const canonicalTargetConfigPath = canonicalRegularFile(input.targetConfigPath, "Target worktree Paperclip config");
+    if (canonicalSourceConfigPath === canonicalTargetConfigPath) {
+        throw new Error("Source and target Paperclip configs are the same canonical file.");
+    }
+    const sourceInstanceId = readInstanceId(canonicalSourceConfigPath, "source");
+    const targetInstanceId = readInstanceId(canonicalTargetConfigPath, "target");
+    if (targetInstanceId !== input.expectedTargetInstanceId) {
+        throw new Error("Target Paperclip instance does not match the registered worktree instance.");
+    }
+    if (sourceInstanceId === targetInstanceId) {
+        throw new Error("Source and target Paperclip configs name the same instance.");
+    }
+    return {
+        baseWorkspaceCwd: canonicalBaseCwd,
+        configPath: canonicalSourceConfigPath,
+        instanceId: sourceInstanceId,
+        targetConfigPath: canonicalTargetConfigPath,
+        targetInstanceId,
+    };
+}
+/**
+ * Resolve a worktree seed source without granting authority to the seed manifest.
+ *
+ * A managed caller supplies the project-workspace cwd from its server-owned row.
+ * An operator may instead supply an explicit source config. A base workspace that
+ * carries its own `.paperclip/config.json` stays authoritative, so an explicit path
+ * must equal it; a base workspace that is a plain checkout has none, and the explicit
+ * path supplies the source. Manifest source fields are diagnostic assertions only and
+ * never select the returned source.
+ */
+export function resolveCanonicalWorktreeSeedSource(input) {
+    const registered = resolveRegisteredWorktreeSeedSource(input);
+    const diagnosticPath = typeof input.manifestSource?.configPath === "string"
+        ? input.manifestSource.configPath.trim()
+        : "";
+    if (!diagnosticPath) {
+        throw new Error("Worktree seed manifest is missing source path diagnostics.");
+    }
+    const canonicalDiagnosticPath = canonicalRegularFile(diagnosticPath, "Worktree seed manifest source diagnostic");
+    if (path.resolve(diagnosticPath) !== registered.configPath || canonicalDiagnosticPath !== registered.configPath) {
+        throw new Error("Worktree seed manifest source path does not match the registered canonical source.");
+    }
+    if (input.manifestSource?.instanceId !== registered.instanceId) {
+        throw new Error("Worktree seed manifest source instance does not match the registered source instance.");
+    }
+    if (input.manifestTargetInstanceId !== registered.targetInstanceId) {
+        throw new Error("Worktree seed manifest target instance does not match the registered target instance.");
+    }
+    return registered;
+}
+//# sourceMappingURL=worktree-seed-source.js.map

package/dist/worktree-seed-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-seed-source.js","sourceRoot":"","sources":["../src/worktree-seed-source.ts"],"names":[],"mappings":"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"}

package/dist/worktree-seed-source.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=worktree-seed-source.test.d.ts.map

package/dist/worktree-seed-source.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-seed-source.test.d.ts","sourceRoot":"","sources":["../src/worktree-seed-source.test.ts"],"names":[],"mappings":""}

package/dist/worktree-seed-source.test.js

@@ -0,0 +1,166 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { resolveCanonicalWorktreeSeedSource } from "./worktree-seed-source.js";
+const cleanup = [];
+function makeInstance(prefix, instanceId) {
+    const cwd = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+    cleanup.push(cwd);
+    const configDir = path.join(cwd, ".paperclip");
+    const configPath = path.join(configDir, "config.json");
+    fs.mkdirSync(configDir, { recursive: true });
+    fs.writeFileSync(configPath, "{}\n");
+    fs.writeFileSync(path.join(configDir, ".env"), `PAPERCLIP_INSTANCE_ID=${instanceId}\n`);
+    return { cwd, configPath, instanceId };
+}
+/**
+ * A control plane's own instance root: `<home>/instances/<id>/config.json`, which
+ * names its instance by directory and has no adjacent .env.
+ */
+function makeInstanceRoot(instanceId) {
+    const home = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-seed-home-"));
+    cleanup.push(home);
+    const configDir = path.join(home, "instances", instanceId);
+    fs.mkdirSync(configDir, { recursive: true });
+    const configPath = path.join(configDir, "config.json");
+    fs.writeFileSync(configPath, "{}\n");
+    return { configPath, instanceId };
+}
+/** A managed project checkout: a plain clone with no `.paperclip` of its own. */
+function makePlainCheckout() {
+    const cwd = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-seed-checkout-"));
+    cleanup.push(cwd);
+    return cwd;
+}
+afterEach(() => {
+    for (const dir of cleanup.splice(0))
+        fs.rmSync(dir, { recursive: true, force: true });
+});
+describe("resolveCanonicalWorktreeSeedSource", () => {
+    it("returns only the registered base workspace config", () => {
+        const source = makeInstance("paperclip-seed-source-", "source-instance");
+        const target = makeInstance("paperclip-seed-target-", "target-instance");
+        expect(resolveCanonicalWorktreeSeedSource({
+            registeredBaseWorkspaceCwd: source.cwd,
+            targetConfigPath: target.configPath,
+            expectedTargetInstanceId: target.instanceId,
+            manifestSource: { configPath: source.configPath, instanceId: source.instanceId },
+            manifestTargetInstanceId: target.instanceId,
+        })).toMatchObject({
+            baseWorkspaceCwd: source.cwd,
+            configPath: source.configPath,
+            targetConfigPath: target.configPath,
+        });
+    });
+    it("takes the named source when the base workspace carries no config of its own", () => {
+        const baseCwd = makePlainCheckout();
+        const source = makeInstanceRoot("default");
+        const target = makeInstance("paperclip-seed-target-", "target-instance");
+        expect(resolveCanonicalWorktreeSeedSource({
+            registeredBaseWorkspaceCwd: baseCwd,
+            explicitSourceConfigPath: source.configPath,
+            targetConfigPath: target.configPath,
+            expectedTargetInstanceId: target.instanceId,
+            manifestSource: { configPath: source.configPath, instanceId: source.instanceId },
+            manifestTargetInstanceId: target.instanceId,
+        })).toMatchObject({
+            baseWorkspaceCwd: baseCwd,
+            configPath: source.configPath,
+            instanceId: "default",
+        });
+    });
+    it("rejects a dangling config symlink instead of falling back to the named source", () => {
+        const baseCwd = makePlainCheckout();
+        fs.mkdirSync(path.join(baseCwd, ".paperclip"), { recursive: true });
+        fs.symlinkSync(path.join(baseCwd, "absent.json"), path.join(baseCwd, ".paperclip", "config.json"));
+        const source = makeInstanceRoot("default");
+        const target = makeInstance("paperclip-seed-dangling-target-", "target-instance");
+        expect(() => resolveCanonicalWorktreeSeedSource({
+            registeredBaseWorkspaceCwd: baseCwd,
+            explicitSourceConfigPath: source.configPath,
+            targetConfigPath: target.configPath,
+            expectedTargetInstanceId: target.instanceId,
+            manifestSource: { configPath: source.configPath, instanceId: source.instanceId },
+            manifestTargetInstanceId: target.instanceId,
+        })).toThrow(/Registered source Paperclip config does not exist/);
+    });
+    it("fails closed when the declared config cannot be inspected", () => {
+        const baseCwd = makePlainCheckout();
+        // `.paperclip` as a regular file makes lstat report ENOTDIR, not ENOENT.
+        fs.writeFileSync(path.join(baseCwd, ".paperclip"), "not a directory\n");
+        const source = makeInstanceRoot("default");
+        const target = makeInstance("paperclip-seed-unreadable-target-", "target-instance");
+        expect(() => resolveCanonicalWorktreeSeedSource({
+            registeredBaseWorkspaceCwd: baseCwd,
+            explicitSourceConfigPath: source.configPath,
+            targetConfigPath: target.configPath,
+            expectedTargetInstanceId: target.instanceId,
+            manifestSource: { configPath: source.configPath, instanceId: source.instanceId },
+            manifestTargetInstanceId: target.instanceId,
+        })).toThrow(/cannot be inspected \(ENOTDIR\)/);
+    });
+    it("rejects a dangling .paperclip symlink instead of falling back to the named source", () => {
+        const baseCwd = makePlainCheckout();
+        // Resolving `.paperclip` fails before the probe reaches config.json, so the config
+        // entry reports ENOENT even though this workspace is malformed rather than plain.
+        fs.symlinkSync(path.join(baseCwd, "absent-dir"), path.join(baseCwd, ".paperclip"));
+        const source = makeInstanceRoot("default");
+        const target = makeInstance("paperclip-seed-dangling-parent-target-", "target-instance");
+        expect(() => resolveCanonicalWorktreeSeedSource({
+            registeredBaseWorkspaceCwd: baseCwd,
+            explicitSourceConfigPath: source.configPath,
+            targetConfigPath: target.configPath,
+            expectedTargetInstanceId: target.instanceId,
+            manifestSource: { configPath: source.configPath, instanceId: source.instanceId },
+            manifestTargetInstanceId: target.instanceId,
+        })).toThrow(/cannot be inspected \(ENOENT on its \.paperclip symlink target\)/);
+    });
+    it("takes the named source when .paperclip is a symlink to a directory with no config", () => {
+        const baseCwd = makePlainCheckout();
+        const linked = path.join(baseCwd, "linked-config-dir");
+        fs.mkdirSync(linked, { recursive: true });
+        fs.symlinkSync(linked, path.join(baseCwd, ".paperclip"));
+        const source = makeInstanceRoot("default");
+        const target = makeInstance("paperclip-seed-linked-empty-target-", "target-instance");
+        const resolved = resolveCanonicalWorktreeSeedSource({
+            registeredBaseWorkspaceCwd: baseCwd,
+            explicitSourceConfigPath: source.configPath,
+            targetConfigPath: target.configPath,
+            expectedTargetInstanceId: target.instanceId,
+            manifestSource: { configPath: source.configPath, instanceId: source.instanceId },
+            manifestTargetInstanceId: target.instanceId,
+        });
+        expect(resolved.configPath).toBe(source.configPath);
+        expect(resolved.instanceId).toBe("default");
+    });
+    it("fails closed when the base workspace carries no config and none is named", () => {
+        const baseCwd = makePlainCheckout();
+        const target = makeInstance("paperclip-seed-unnamed-target-", "target-instance");
+        expect(() => resolveCanonicalWorktreeSeedSource({
+            registeredBaseWorkspaceCwd: baseCwd,
+            targetConfigPath: target.configPath,
+            expectedTargetInstanceId: target.instanceId,
+            manifestSource: { configPath: target.configPath, instanceId: target.instanceId },
+            manifestTargetInstanceId: target.instanceId,
+        })).toThrow(/no Paperclip config of its own/);
+    });
+    it("fails closed without registration and when source equals target", () => {
+        const target = makeInstance("paperclip-seed-same-target-", "target-instance");
+        const diagnostic = { configPath: target.configPath, instanceId: target.instanceId };
+        expect(() => resolveCanonicalWorktreeSeedSource({
+            targetConfigPath: target.configPath,
+            expectedTargetInstanceId: target.instanceId,
+            manifestSource: diagnostic,
+            manifestTargetInstanceId: target.instanceId,
+        })).toThrow(/not registered/);
+        expect(() => resolveCanonicalWorktreeSeedSource({
+            registeredBaseWorkspaceCwd: target.cwd,
+            targetConfigPath: target.configPath,
+            expectedTargetInstanceId: target.instanceId,
+            manifestSource: diagnostic,
+            manifestTargetInstanceId: target.instanceId,
+        })).toThrow(/same canonical file/);
+    });
+});
+//# sourceMappingURL=worktree-seed-source.test.js.map

package/dist/worktree-seed-source.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-seed-source.test.js","sourceRoot":"","sources":["../src/worktree-seed-source.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paperclipai/shared",
-  "version": "2026.824.1",
+  "version": "2026.825.0-beta.1",
   "license": "MIT",
   "homepage": "https://github.com/paperclipai/paperclip",
   "bugs": {
@@ -33,12 +33,15 @@
     "dist"
   ],
   "dependencies": {
-    "zod": "^3.24.2"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^22.20.1",
+    "@types/node": "^24.0.0",
     "typescript": "^5.7.3"
   },
+  "engines": {
+    "node": ">=24.11.0"
+  },
   "scripts": {
     "build": "tsc",
     "clean": "rm -rf dist",