From a9d1f740f05218765c5ef5ae974a7ce5a05d0f48 Mon Sep 17 00:00:00 2001 From: Nicky Leach Date: Thu, 20 Aug 2026 08:42:16 -0700 Subject: [PATCH] fix(workspaces): seed managed worktrees when the base checkout has no config (#11752) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Agents do that work in isolated git worktrees, and a managed worktree runs its own Paperclip instance with a cloned database > - That clone needs a seed source, and the source must come from server-owned registration, never from state the workspace itself can rewrite > - The seed-source resolver requires the registered base project workspace to hold its own `.paperclip/config.json` > - A managed project workspace is a plain `git clone`, and no code writes that file into it > - Every isolated worktree provision, deferred seed, and workspace repair therefore fails on a managed checkout > - This pull request lets a named source supply the config when the base checkout has none > - The benefit is that managed worktrees provision again, and the seed source stays server-owned ## Linked Issues or Issue Description No public GitHub issue exists for this problem. It is described below. **What happened?** Agent runs that need an isolated worktree fail during provisioning. The provision command exits with this error (paths redacted): ``` Execution workspace provision command "bash ./scripts/provision-worktree.sh" failed: Registered base project workspace has no canonical Paperclip config: /instances/default/projects////.paperclip/config.json ``` `resolveRegisteredWorktreeSeedSource` sets `registeredConfigPath` to `/.paperclip/config.json` whenever the caller names a registered base workspace. It then requires that file to exist. `scripts/provision-worktree.sh` applies the same rule. A managed project workspace never has that file. `materializeManagedProjectWorkspace` creates it with `git clone` and a rename, so the checkout holds repository content only. The control plane keeps its config at `/instances//config.json` instead. The failure reaches three paths: worktree provisioning, deferred seeding through `worktree ensure-seeded`, and workspace repair. The behavior changed in #11671. That pull request replaced a fallback chain with a single hard requirement. Fixture code in `scripts/__tests__/provision-worktree-self-heal.test.mjs` writes a config into the fake base workspace, so tests kept passing. **Expected behavior** A managed worktree provisions and seeds from the registered source. The seed manifest still never selects that source. **Steps to reproduce** 1. Register the Paperclip repository as a project with a `repoUrl`, so the server materializes a managed checkout. 2. Assign an issue to an agent whose workspace strategy is `git_worktree`. 3. Watch the workspace operation log for the provision command. 4. The command exits non-zero with the error above. **Paperclip version or commit** Reproduced on `master` at 01ddc26a3. **Deployment mode** `local_trusted`, single instance. **Database mode** Embedded PostgreSQL. **Operating system** Linux, Node.js 22. **Related pull requests** - Refs #11671 — introduced the requirement this pull request relaxes. - Refs #11733 — open work on seed-source preflight. It reads the same base-workspace config path and skips when the file is absent. It does not change source selection. - Refs #11735 — open work on provisioning reliability. It edits the same four files and will need a rebase after either lands. ## What Changed - `resolveRegisteredWorktreeSeedSource` sets the registered config path only when `/.paperclip/config.json` exists. This makes the existing `registeredConfigPath ?? explicitSource` branch reachable for a plain checkout. - A base workspace that does hold its own config stays authoritative. A mismatched explicit source is still rejected. - The resolver throws a named error when the base workspace has no config and no source is named. - `readInstanceId` accepts an instance-root config at `/instances//config.json`. That layout names its instance by directory and has no adjacent `.env`. Validation reuses `resolvePaperclipInstanceId`. - `scripts/provision-worktree.sh` and `scripts/provision-worktree-runtime.sh` name the control plane's instance config as the source when the base workspace has none. The canonical-path and symlink checks stay. - The workspace repair route supplies the same fallback, and only when the base workspace has no config of its own. - `doc/DEVELOPING.md` records the two source layouts. ## Verification - `node --test scripts/__tests__/provision-worktree-self-heal.test.mjs` — 10 tests pass. The fixture no longer writes a config into the base workspace, so it models a real managed checkout. One test now creates that config mid-test, which covers both layouts. - `npx vitest run src/worktree-seed-source.test.ts` in `packages/shared` — 4 tests pass. Two are new: one resolves an instance-root source, and one still fails closed when no source exists. - `npx vitest run src/__tests__/workspace-runtime.test.ts src/__tests__/execution-workspaces-routes.test.ts src/__tests__/execution-workspace-runtime-control-conflict.test.ts src/__tests__/workspace-operations-reconciliation.test.ts src/__tests__/worktree-seed-server-spawn.test.ts` in `server` — all pass. Run them one file at a time. They share one test database, and concurrent runs fail teardown. - `npx vitest run src/__tests__/worktree.test.ts` in `cli` — 63 tests pass. - `pnpm --filter @paperclipai/shared typecheck` — clean. - Manual check on a live instance: the resolver now returns the instance config as the source for a managed checkout, with the source instance `default` and a distinct target instance. ## Risks Low to moderate. - The relaxed rule applies only when the base workspace holds no config. A base workspace that holds one keeps full authority, so the trust model from #11671 is unchanged. The seed manifest still never selects the source. - The instance-id fallback reads a directory name. It applies only to the `/instances//config.json` layout, and `resolvePaperclipInstanceId` rejects an unsafe segment. - #11735 edits the same four files. Whichever pull request lands second needs a rebase. - `pnpm --filter @paperclipai/server typecheck` currently fails on this checkout with duplicate `drizzle-orm` type instantiations. The failure is present with and without this change, and the error count is identical. It comes from an unrelated lockfile state, not from this pull request. ## Model Used Claude Opus 5 (`claude-opus-5`), by Anthropic, running in Claude Code. Extended thinking was on. The model used file, search, and shell tools to diagnose the failure on a live instance and to run the test suites. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5 --- doc/DEVELOPING.md | 2 +- .../shared/src/worktree-seed-source.test.ts | 126 ++++++++++++++++++ packages/shared/src/worktree-seed-source.ts | 83 ++++++++++-- .../provision-worktree-self-heal.test.mjs | 56 ++++++-- scripts/provision-worktree-runtime.sh | 23 +++- scripts/provision-worktree.sh | 16 ++- server/src/routes/execution-workspaces.ts | 14 ++ 7 files changed, 294 insertions(+), 26 deletions(-) diff --git a/doc/DEVELOPING.md b/doc/DEVELOPING.md index 53a787da10..3a5e153175 100644 --- a/doc/DEVELOPING.md +++ b/doc/DEVELOPING.md @@ -485,7 +485,7 @@ Seeding state is tracked in `.paperclip/seed-manifest.json`. The versioned manif The default `worktree init` still seeds eagerly. A lean worktree (created without an eager seed) has a `pending` manifest until something seeds it on demand: -- `pnpm paperclipai worktree ensure-seeded` performs the deferred seed **exactly once**. It is lock-guarded and idempotent: only a complete `verified` manifest short-circuits it, so it is safe to call repeatedly and from concurrent processes. Managed workspaces derive the source exclusively from the control-plane-provided base project workspace; manual worktrees must pass `--from-config`. +- `pnpm paperclipai worktree ensure-seeded` performs the deferred seed **exactly once**. It is lock-guarded and idempotent: only a complete `verified` manifest short-circuits it, so it is safe to call repeatedly and from concurrent processes. Managed workspaces derive the source from the control-plane-provided base project workspace when it carries its own `.paperclip/config.json`, and otherwise from the control plane's own registered instance config; either way the workspace's manifest never selects it. Manual worktrees must pass `--from-config`. - `paperclipai run` calls `ensureWorktreeSeeded` automatically before doctor/boot. Managed runs transparently seed a lean worktree from their registered base workspace; an unmanaged lean worktree must first run `worktree ensure-seeded --from-config `. - Managed Paperclip git worktrees default to the repository's `scripts/provision-worktree.sh` when the strategy omits `provisionCommand`, so the isolated config and pending manifest cannot be silently skipped. Runtime startup also runs `scripts/provision-worktree-runtime.sh` automatically when no explicit runtime provision command is configured and the manifest is not verified. Explicitly configured provision commands still take precedence. - The built-in deferred seed is recorded as its own terminal `workspace_seed` operation. A zero exit code is not enough for success: the operation succeeds only when `.paperclip/seed-manifest.json` contains complete verified evidence; failed, missing, or malformed manifests produce a failed operation with the seed phase in metadata. diff --git a/packages/shared/src/worktree-seed-source.test.ts b/packages/shared/src/worktree-seed-source.test.ts index 7f54e80cc1..fa7688a6dd 100644 --- a/packages/shared/src/worktree-seed-source.test.ts +++ b/packages/shared/src/worktree-seed-source.test.ts @@ -17,6 +17,27 @@ function makeInstance(prefix: string, instanceId: string) { return { cwd, configPath, instanceId }; } +/** + * A control plane's own instance root: `/instances//config.json`, which + * names its instance by directory and has no adjacent .env. + */ +function makeInstanceRoot(instanceId: string) { + 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 }); }); @@ -39,6 +60,111 @@ describe("resolveCanonicalWorktreeSeedSource", () => { }); }); + 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 }; diff --git a/packages/shared/src/worktree-seed-source.ts b/packages/shared/src/worktree-seed-source.ts index fca8556bef..3d1a09bed2 100644 --- a/packages/shared/src/worktree-seed-source.ts +++ b/packages/shared/src/worktree-seed-source.ts @@ -1,5 +1,6 @@ -import { existsSync, lstatSync, readFileSync, realpathSync } from "node:fs"; +import { existsSync, lstatSync, readFileSync, realpathSync, statSync, type Stats } from "node:fs"; import path from "node:path"; +import { resolvePaperclipInstanceId } from "./home-paths.js"; export type WorktreeSeedSourceDiagnostic = { configPath?: unknown; @@ -22,8 +23,14 @@ export type RegisteredWorktreeSeedSourceInput = { }; function readInstanceId(configPath: string, label: "source" | "target"): string { - const envPath = path.join(path.dirname(configPath), ".env"); + const configDir = path.dirname(configPath); + const envPath = path.join(configDir, ".env"); if (!existsSync(envPath)) { + // An instance-root config (`/instances//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"); @@ -37,6 +44,56 @@ function readInstanceId(configPath: string, label: "source" | "target"): string throw new Error(`Registered ${label} Paperclip config has no PAPERCLIP_INSTANCE_ID binding.`); } +function errorCode(error: unknown): string { + return (error as NodeJS.ErrnoException | null)?.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: string, configPath: string, detail?: string): Stats | null { + 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: string): boolean { + 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: string, label: string): string { const resolved = path.resolve(filePath); let canonical: string; @@ -81,10 +138,19 @@ export function resolveRegisteredWorktreeSeedSource( if (!lstatSync(canonicalBaseCwd).isDirectory()) { throw new Error(`Registered base project workspace is not a directory at ${canonicalBaseCwd}.`); } - registeredConfigPath = path.join(canonicalBaseCwd, ".paperclip", "config.json"); + // 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!; + 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."); @@ -127,10 +193,11 @@ export function resolveRegisteredWorktreeSeedSource( * 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. When both are present, - * the explicit path must still equal the registered project-workspace config. - * Manifest source fields are diagnostic assertions only and never select the - * returned source. + * 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: RegisteredWorktreeSeedSourceInput & { manifestSource: WorktreeSeedSourceDiagnostic | null | undefined; diff --git a/scripts/__tests__/provision-worktree-self-heal.test.mjs b/scripts/__tests__/provision-worktree-self-heal.test.mjs index 91aa420358..34d64167fb 100644 --- a/scripts/__tests__/provision-worktree-self-heal.test.mjs +++ b/scripts/__tests__/provision-worktree-self-heal.test.mjs @@ -21,6 +21,17 @@ function makeTempDir(prefix) { return dir; } +/** + * A control plane's own instance home. A managed project checkout carries no + * instance config of its own, so this is the seed source the scripts fall back to. + */ +function makeInstanceHome() { + const home = makeTempDir("paperclip-provision-instance-home-"); + fs.mkdirSync(path.join(home, "instances", "default"), { recursive: true }); + fs.writeFileSync(path.join(home, "instances", "default", "config.json"), "{}\n"); + return home; +} + test.after(() => { for (const dir of cleanupDirs) { fs.rmSync(dir, { recursive: true, force: true }); @@ -37,9 +48,6 @@ test.after(() => { */ function makeBaseWorkspace({ helpExit, initExit, ensureExit = 0 }) { const baseCwd = makeTempDir("paperclip-provision-base-"); - fs.mkdirSync(path.join(baseCwd, ".paperclip"), { recursive: true }); - fs.writeFileSync(path.join(baseCwd, ".paperclip", "config.json"), "{}\n"); - fs.writeFileSync(path.join(baseCwd, ".paperclip", ".env"), "PAPERCLIP_INSTANCE_ID=base-source\n"); const runnerPath = path.join(baseCwd, "cli", "node_modules", "tsx", "dist", "cli.mjs"); const entryPath = path.join(baseCwd, "cli", "src", "index.ts"); fs.mkdirSync(path.dirname(runnerPath), { recursive: true }); @@ -97,6 +105,7 @@ process.exit(0); function runProvision(baseCwd, { pathPrefix } = {}) { const worktreeCwd = makeTempDir("paperclip-provision-worktree-"); const worktreesHome = makeTempDir("paperclip-provision-home-"); + const paperclipHome = makeInstanceHome(); const result = spawnSync("bash", [script], { cwd: worktreeCwd, encoding: "utf8", @@ -107,16 +116,17 @@ function runProvision(baseCwd, { pathPrefix } = {}) { PAPERCLIP_WORKSPACE_CWD: worktreeCwd, PAPERCLIP_WORKSPACE_BRANCH: "feature/provision-test", PAPERCLIP_WORKTREES_DIR: worktreesHome, - PAPERCLIP_HOME: path.join(worktreesHome, "no-such-instance-home"), + PAPERCLIP_HOME: paperclipHome, PAPERCLIP_PROJECT_WORKSPACE_ID: "project-workspace-1", PAPERCLIP_SEED_EXPECTED_COMPANY_ID: "company-1", }, }); - return { result, worktreeCwd, worktreesHome }; + return { result, worktreeCwd, worktreesHome, paperclipHome }; } function runRuntimeProvision(baseCwd, worktreeCwd) { const worktreesHome = makeTempDir("paperclip-provision-runtime-home-"); + const paperclipHome = makeInstanceHome(); return spawnSync("bash", [runtimeScript], { cwd: worktreeCwd, encoding: "utf8", @@ -127,7 +137,7 @@ function runRuntimeProvision(baseCwd, worktreeCwd) { PAPERCLIP_WORKSPACE_CWD: worktreeCwd, PAPERCLIP_WORKSPACE_BRANCH: "feature/provision-runtime-test", PAPERCLIP_WORKTREES_DIR: worktreesHome, - PAPERCLIP_HOME: path.join(worktreesHome, "no-such-instance-home"), + PAPERCLIP_HOME: paperclipHome, PAPERCLIP_PROJECT_WORKSPACE_ID: "project-workspace-1", PAPERCLIP_COMPANY_ID: "company-1", }, @@ -171,6 +181,29 @@ test("uses the base CLI when its import graph boots", () => { ); }); +test("rejects a dangling base workspace config symlink instead of falling back", () => { + const baseCwd = makeBaseWorkspace({ helpExit: 0, initExit: 0 }); + fs.mkdirSync(path.join(baseCwd, ".paperclip"), { recursive: true }); + fs.symlinkSync(path.join(baseCwd, "absent.json"), path.join(baseCwd, ".paperclip", "config.json")); + + const { result } = runProvision(baseCwd); + + assert.notEqual(result.status, 0); + assert.match(result.stderr, /is missing or is not a canonical file/); +}); + +test("rejects a dangling base workspace .paperclip symlink instead of falling back", () => { + const baseCwd = makeBaseWorkspace({ helpExit: 0, initExit: 0 }); + // `-e`/`-L` on the config resolve `.paperclip` first, so the config reads as absent + // here even though the workspace is malformed rather than a plain checkout. + fs.symlinkSync(path.join(baseCwd, "absent-dir"), path.join(baseCwd, ".paperclip")); + + const { result } = runProvision(baseCwd); + + assert.notEqual(result.status, 0); + assert.match(result.stderr, /\.paperclip is a broken symlink/); +}); + test("falls back to an isolated config when the base CLI cannot boot", () => { // Simulates the dangling pnpm symlink incident: the runner and entry files // exist, but booting the CLI fails ESM resolution. The base has no @@ -198,10 +231,12 @@ test("falls back to an isolated config when the base CLI cannot boot", () => { test("reconciles deployment mode from the registered source when reusing a guest config", () => { const baseCwd = makeBaseWorkspace({ helpExit: 1, initExit: 0 }); - const { result: first, worktreeCwd, worktreesHome } = runProvision(baseCwd); + const { result: first, worktreeCwd, worktreesHome, paperclipHome } = runProvision(baseCwd); assert.equal(first.status, 0, first.stderr); assert.equal(readWorktreeConfig(worktreeCwd).server.deploymentMode, "local_trusted"); + // A base workspace that does carry its own instance config outranks the fallback. + fs.mkdirSync(path.join(baseCwd, ".paperclip"), { recursive: true }); fs.writeFileSync( path.join(baseCwd, ".paperclip", "config.json"), `${JSON.stringify({ @@ -222,7 +257,7 @@ test("reconciles deployment mode from the registered source when reusing a guest PAPERCLIP_WORKSPACE_CWD: worktreeCwd, PAPERCLIP_WORKSPACE_BRANCH: "feature/provision-test", PAPERCLIP_WORKTREES_DIR: worktreesHome, - PAPERCLIP_HOME: path.join(worktreesHome, "no-such-instance-home"), + PAPERCLIP_HOME: paperclipHome, PAPERCLIP_PROJECT_WORKSPACE_ID: "project-workspace-1", PAPERCLIP_SEED_EXPECTED_COMPANY_ID: "company-1", }, @@ -247,9 +282,6 @@ test("repairs an unhealthy base install under the lock and then uses the CLI", ( // The CLI's health is controlled by a flag file, and a fake `pnpm install` // creates that flag — modeling a forced reinstall that relinks the store. const baseCwd = makeTempDir("paperclip-provision-repair-base-"); - fs.mkdirSync(path.join(baseCwd, ".paperclip"), { recursive: true }); - fs.writeFileSync(path.join(baseCwd, ".paperclip", "config.json"), "{}\n"); - fs.writeFileSync(path.join(baseCwd, ".paperclip", ".env"), "PAPERCLIP_INSTANCE_ID=base-source\n"); const healthFlag = path.join(baseCwd, "cli-healthy.flag"); const runnerPath = path.join(baseCwd, "cli", "node_modules", "tsx", "dist", "cli.mjs"); const entryPath = path.join(baseCwd, "cli", "src", "index.ts"); @@ -339,7 +371,7 @@ test("runtime provisioning invokes ensure-seeded once and fast-exits after succe .filter((args) => args[0] === "worktree" && args[1] === "ensure-seeded"); assert.equal(ensureCallsAfterFirst.length, 1); assert.ok(ensureCallsAfterFirst[0].includes("--config")); - assert.ok(!ensureCallsAfterFirst[0].includes("--from-config")); + assert.ok(ensureCallsAfterFirst[0].includes("--from-config")); const second = runRuntimeProvision(baseCwd, worktreeCwd); assert.equal(second.status, 0, second.stderr); diff --git a/scripts/provision-worktree-runtime.sh b/scripts/provision-worktree-runtime.sh index b9710344c5..99a56fe1e4 100755 --- a/scripts/provision-worktree-runtime.sh +++ b/scripts/provision-worktree-runtime.sh @@ -3,6 +3,8 @@ set -euo pipefail base_cwd="${PAPERCLIP_WORKSPACE_BASE_CWD:?PAPERCLIP_WORKSPACE_BASE_CWD is required}" worktree_cwd="${PAPERCLIP_WORKSPACE_CWD:?PAPERCLIP_WORKSPACE_CWD is required}" +paperclip_home="${PAPERCLIP_HOME:-$HOME/.paperclip}" +paperclip_instance_id="${PAPERCLIP_INSTANCE_ID:-default}" paperclip_dir="$worktree_cwd/.paperclip" worktree_config_path="$paperclip_dir/config.json" seed_manifest_path="$paperclip_dir/seed-manifest.json" @@ -66,10 +68,25 @@ if [[ ! -f "$worktree_config_path" ]]; then exit 1 fi -# The CLI derives the source from PAPERCLIP_WORKSPACE_BASE_CWD, which the -# control plane injects from the registered project-workspace row. The seed -# manifest is diagnostic evidence only and must never choose the clone source. +# The CLI derives the source from PAPERCLIP_WORKSPACE_BASE_CWD, which the control +# plane injects from the registered project-workspace row. A base workspace that is +# a plain checkout carries no instance config of its own, so name the control plane's +# own registered instance config explicitly. The seed manifest stays diagnostic +# evidence only and must never choose the clone source. +if [[ -L "$base_cwd/.paperclip" && ! -d "$base_cwd/.paperclip" ]]; then + echo "Registered base project workspace .paperclip is a broken symlink: $base_cwd/.paperclip" >&2 + exit 1 +fi source_config_args=() +if [[ ! -e "$base_cwd/.paperclip/config.json" && ! -L "$base_cwd/.paperclip/config.json" ]]; then + source_config_path="${PAPERCLIP_CONFIG:-$paperclip_home/instances/$paperclip_instance_id/config.json}" + # A human may invoke this after sourcing `worktree env`, which points + # PAPERCLIP_CONFIG at the target. Naming the target as its own source is never + # right, so leave the source to the CLI in that case. + if [[ "$source_config_path" != "$worktree_config_path" ]]; then + source_config_args=(--from-config "$source_config_path") + fi +fi base_cli_runner_path="$base_cwd/cli/node_modules/tsx/dist/cli.mjs" base_cli_entry_path="$base_cwd/cli/src/index.ts" diff --git a/scripts/provision-worktree.sh b/scripts/provision-worktree.sh index 63fa570355..d25f6a6672 100644 --- a/scripts/provision-worktree.sh +++ b/scripts/provision-worktree.sh @@ -41,14 +41,26 @@ if [[ ! -d "$worktree_cwd" ]]; then fi canonical_base_cwd="$(cd "$base_cwd" && pwd -P)" +if [[ -L "$canonical_base_cwd/.paperclip" && ! -d "$canonical_base_cwd/.paperclip" ]]; then + # A broken link hides whatever it points at, so the config below would read as absent + # on a workspace that is malformed rather than plain. Refuse instead of falling back. + echo "Registered base project workspace .paperclip is a broken symlink: $canonical_base_cwd/.paperclip" >&2 + exit 1 +fi source_config_path="$canonical_base_cwd/.paperclip/config.json" +if [[ ! -e "$source_config_path" && ! -L "$source_config_path" ]]; then + # A base workspace that is a plain checkout carries no instance config of its own. + # Fall back to the control plane's own registered instance config, which is process + # state this workspace cannot rewrite. + source_config_path="${PAPERCLIP_CONFIG:-$paperclip_home/instances/$paperclip_instance_id/config.json}" +fi if [[ ! -f "$source_config_path" || -L "$source_config_path" ]]; then - echo "Registered base project workspace has no canonical Paperclip config: $source_config_path" >&2 + echo "Registered Paperclip seed source config is missing or is not a canonical file: $source_config_path" >&2 exit 1 fi canonical_source_dir="$(cd "$(dirname "$source_config_path")" && pwd -P)" if [[ "$canonical_source_dir/config.json" != "$source_config_path" ]]; then - echo "Registered base project workspace Paperclip config uses a symlink alias: $source_config_path" >&2 + echo "Registered Paperclip seed source config uses a symlink alias: $source_config_path" >&2 exit 1 fi source_env_path="$(dirname "$source_config_path")/.env" diff --git a/server/src/routes/execution-workspaces.ts b/server/src/routes/execution-workspaces.ts index 442ab7b784..cd5e67d3e1 100644 --- a/server/src/routes/execution-workspaces.ts +++ b/server/src/routes/execution-workspaces.ts @@ -15,9 +15,11 @@ import { } from "@paperclipai/shared"; import type { WorkspaceRuntimeDesiredState, WorkspaceRuntimeServiceStateMap } from "@paperclipai/shared"; import { + baseWorkspaceDeclaresInstanceConfig, resolveCanonicalWorktreeSeedSource, type CanonicalWorktreeSeedSource, } from "@paperclipai/shared/worktree-seed-source"; +import { resolvePaperclipConfigPath } from "../paths.js"; import { validate } from "../middleware/validate.js"; import { accessService, @@ -71,6 +73,16 @@ function isReadableFile(filePath: string) { } } +/** + * The control plane's own instance config, named as the seed source only when the base + * project workspace is a plain checkout carrying no instance config of its own. A base + * workspace that has one stays authoritative, so an operator's mismatched source is + * still rejected. + */ +function resolveFallbackSeedSourceConfigPath(baseWorkspaceCwd: string): string | null { + return baseWorkspaceDeclaresInstanceConfig(baseWorkspaceCwd) ? null : resolvePaperclipConfigPath(); +} + export function executionWorkspaceRoutes(db: Db, opts: { pluginWorkerManager?: PluginWorkerManager } = {}) { const router = Router(); const svc = executionWorkspaceService(db); @@ -395,6 +407,7 @@ export function executionWorkspaceRoutes(db: Db, opts: { pluginWorkerManager?: P } repairSeedSource = resolveCanonicalWorktreeSeedSource({ registeredBaseWorkspaceCwd: projectWorkspace.cwd, + explicitSourceConfigPath: resolveFallbackSeedSourceConfigPath(projectWorkspace.cwd), targetConfigPath: path.join(workspaceCwd, ".paperclip", "config.json"), expectedTargetInstanceId, manifestSource: manifest.source, @@ -782,6 +795,7 @@ export function executionWorkspaceRoutes(db: Db, opts: { pluginWorkerManager?: P } resolveCanonicalWorktreeSeedSource({ registeredBaseWorkspaceCwd: baseWorkspaceCwd, + explicitSourceConfigPath: resolveFallbackSeedSourceConfigPath(baseWorkspaceCwd), targetConfigPath: path.join(workspaceCwd, ".paperclip", "config.json"), expectedTargetInstanceId: repairSeedSource.targetInstanceId, manifestSource: manifest.source as { configPath?: unknown; instanceId?: unknown } | undefined,