fix(workspaces): prepare checkouts without a local seed config (#14810)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Task preparation can create an isolated Git worktree and run its
setup script.
> - The Paperclip repository setup script also prepares a seeded
development instance.
> - A server configured through environment variables can have no local
seed config.
> - This stops ordinary task preparation before the agent starts.
> - This pull request prepares checkout dependencies when no seed source
exists, while preserving errors for invalid sources and existing
development instances.
> - Tasks can start without creating or claiming a seeded development
runtime.

## Linked Issues or Issue Description

**What happened?**

A task with the Paperclip repository fails during setup when the host
has no repository-local or default instance config. The automatic
worktree provisioner requires a seed source even when the task only
needs the checkout.

**Expected behavior**

A plain checkout should prepare its dependencies without a local
development database. A missing custom source, invalid source path, or
existing development instance with a missing source should still fail.
Starting a seeded runtime must still require a valid source.

**Steps to reproduce**

1. Run an environment-configured Paperclip server without a local
instance config.
2. Add the Paperclip repository to a project.
3. Start a task that uses an isolated Git worktree without a custom
provision command.
4. Observe the setup error before agent execution.

**Paperclip version or commit**

Reproduced against `0d3e7bf6ac` with a real script subprocess and
workspace realization regression.

**Deployment mode**

Environment-configured server with external PostgreSQL.

**Additional context**

Searched open and closed GitHub PRs and issues. Related work: Refs
#14795 (seed-source diagnostics) and Refs #11733 (source validation).
This change keeps source validation and seed-readiness checks in place.

## What Changed

- Permit dependency setup when the default seed config is absent
(including the Docker image config path) and the worktree has no
development-instance state.
- Keep missing custom configs, invalid paths, and lost sources for
existing instances as errors.
- Create no config, environment file, or seed manifest for a plain
checkout.
- Keep dependency install failures visible and allow normal instance
setup once a source becomes available.
- Cover the setup script, seed-runtime refusal, and automatic server
worktree realization.
- Document the difference between checkout preparation and
seeded-runtime readiness.

## Verification

- Regression tests failed before the fix for absent-source checkout
preparation and dependency setup.
- `bash -n scripts/provision-worktree.sh`
- `node --test scripts/__tests__/provision-worktree-self-heal.test.mjs`
— 34 passed; 1 existing flock-dependent test skipped on macOS.
- Server regression — 2 passed, covering an unset config and the Docker
image default path.
- `pnpm build` — passed.
- `pnpm -r typecheck` — passed.
- All CI checks passed, including the full test shards, build,
typecheck, browser tests, and canary dry run.
- The first local `pnpm test:run` encountered two chat-test failures
because skill discovery selected an unrelated parent directory. Both
tests pass at the PR commit in a clean temporary checkout. The full
local run was not completed; the redundant clean run was stopped after
the complete CI suite passed.
- `git diff --check` and added-line secrets/PII scan passed.
- Greptile: 5/5, no comments. The branch has no merge conflicts.
- No live tenant deployment or task retry was performed.

## Risks

- A new checkout with no implicit seed config now completes dependency
setup. It has no seeded development instance. A runtime request still
fails until a valid source exists.
- Existing instances and custom source paths retain their failure
behavior. The script does not synthesize a source from environment
credentials or copy a live database.
- No schema, API, or task-setting changes. Revert the commit to restore
the previous setup behavior.

## Model Used

OpenAI Codex (GPT-6), with tool-assisted analysis, code edits, and local
tests. The runtime did not expose a verified model variant or
context-window size.

## 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
- [x] 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

Co-authored-by: Paperclip <noreply@paperclip.ing>

scripts/__tests__/provision-worktree-self-heal.test.mjs

@@ -102,7 +102,7 @@ process.exit(0);
   return baseCwd;
 }
 
-function runProvision(baseCwd, { pathPrefix, setupWorktree, setupInstance, existingWorktree } = {}) {
+function runProvision(baseCwd, { pathPrefix, setupWorktree, setupInstance, existingWorktree, env = {} } = {}) {
   const worktreeCwd = existingWorktree ?? makeTempDir("paperclip-provision-worktree-");
   setupWorktree?.(worktreeCwd);
   const worktreesHome = makeTempDir("paperclip-provision-home-");
@@ -121,14 +121,16 @@ function runProvision(baseCwd, { pathPrefix, setupWorktree, setupInstance, exist
       PAPERCLIP_HOME: paperclipHome,
       PAPERCLIP_PROJECT_WORKSPACE_ID: "project-workspace-1",
       PAPERCLIP_SEED_EXPECTED_COMPANY_ID: "company-1",
+      ...(typeof env === "function" ? env(paperclipHome) : env),
     },
   });
   return { result, worktreeCwd, worktreesHome, paperclipHome };
 }
 
-function runRuntimeProvision(baseCwd, worktreeCwd) {
+function runRuntimeProvision(baseCwd, worktreeCwd, { setupInstance } = {}) {
   const worktreesHome = makeTempDir("paperclip-provision-runtime-home-");
   const paperclipHome = makeInstanceHome();
+  setupInstance?.(paperclipHome);
   return spawnSync("bash", [runtimeScript], {
     cwd: worktreeCwd,
     encoding: "utf8",
@@ -183,22 +185,122 @@ test("uses the base CLI when its import graph boots", () => {
   );
 });
 
-test("explains unavailable instance source config without creating target state", () => {
+for (const defaultConfigInEnv of [false, true]) {
+  test(`prepares a plain checkout without a default instance config (image default env: ${defaultConfigInEnv})`, () => {
+    const baseCwd = makeBaseWorkspace({ helpExit: 0, initExit: 0 });
+    const { result, worktreeCwd } = runProvision(baseCwd, {
+      setupInstance: (home) => fs.rmSync(path.join(home, "instances", "default", "config.json")),
+      env: (home) => defaultConfigInEnv ? { PAPERCLIP_CONFIG: path.join(home, "instances", "default", "config.json") } : {},
+    });
+
+    assert.equal(result.status, 0, result.stderr);
+    assert.match(result.stderr, /preparing checkout dependencies without a seeded development instance/);
+    for (const file of ["config.json", ".env", "seed-manifest.json", "seed-pending", "seed-complete"]) {
+      assert.equal(fs.existsSync(path.join(worktreeCwd, ".paperclip", file)), false);
+    }
+    assert.equal(fs.realpathSync(path.join(worktreeCwd, "cli", "node_modules")), path.join(baseCwd, "cli", "node_modules"));
+    assert.deepEqual(readCliInvocations(baseCwd), []);
+  });
+}
+
+test("rejects a missing custom seed source", () => {
   const baseCwd = makeBaseWorkspace({ helpExit: 0, initExit: 0 });
   const { result, worktreeCwd } = runProvision(baseCwd, {
-    setupInstance: (home) => fs.rmSync(path.join(home, "instances", "default", "config.json")),
+    env: { PAPERCLIP_CONFIG: path.join(baseCwd, "missing", "config.json") },
   });
 
   assert.notEqual(result.status, 0);
   assert.match(result.stderr, /config is unavailable \(control-plane instance\)/);
   assert.match(result.stderr, /For a seeded development instance, configure a canonical config/);
-  assert.match(result.stderr, /Only for a checkout-only worktree/);
-  assert.match(result.stderr, /workspaceStrategy\.provisionCommand to "true"/);
-  assert.match(result.stderr, /does not prepare a development runtime/);
   assert.equal(fs.existsSync(path.join(worktreeCwd, ".paperclip")), false);
   assert.deepEqual(readCliInvocations(baseCwd), []);
 });
 
+test("initializes a previously plain checkout once a registered seed source is available", () => {
+  const baseCwd = makeBaseWorkspace({ helpExit: 0, initExit: 0 });
+  const first = runProvision(baseCwd, {
+    setupInstance: (home) => fs.rmSync(path.join(home, "instances"), { recursive: true }),
+  });
+  assert.equal(first.result.status, 0, first.result.stderr);
+  assert.deepEqual(readCliInvocations(baseCwd), []);
+
+  const second = runProvision(baseCwd, { existingWorktree: first.worktreeCwd });
+  assert.equal(second.result.status, 0, second.result.stderr);
+  assert.equal(readWorktreeConfig(first.worktreeCwd).$meta.source, "fake-cli");
+  assert.equal(JSON.parse(fs.readFileSync(path.join(first.worktreeCwd, ".paperclip", "seed-manifest.json"), "utf8")).state, "pending");
+});
+
+test("a plain checkout without a source is not ready for a seeded runtime", () => {
+  const baseCwd = makeBaseWorkspace({ helpExit: 0, initExit: 0 });
+  fs.mkdirSync(path.join(baseCwd, "scripts"));
+  fs.copyFileSync(script, path.join(baseCwd, "scripts", "provision-worktree.sh"));
+  const setupInstance = (home) => fs.rmSync(path.join(home, "instances"), { recursive: true });
+  const { result, worktreeCwd } = runProvision(baseCwd, { setupInstance });
+  assert.equal(result.status, 0, result.stderr);
+
+  const runtime = runRuntimeProvision(baseCwd, worktreeCwd, { setupInstance });
+  assert.notEqual(runtime.status, 0);
+  assert.match(runtime.stderr, /Worktree config still does not exist after built-in provisioning/);
+  assert.equal(fs.existsSync(path.join(worktreeCwd, ".paperclip", "seed-manifest.json")), false);
+  assert.deepEqual(readCliInvocations(baseCwd), []);
+});
+
+for (const relativePath of ["instances/default/config.json", "instances/default"]) {
+  test(`rejects a dangling implicit source symlink at ${relativePath}`, () => {
+    const baseCwd = makeBaseWorkspace({ helpExit: 0, initExit: 0 });
+    const { result, worktreeCwd } = runProvision(baseCwd, {
+      setupInstance(home) {
+        const sourcePath = path.join(home, relativePath);
+        fs.rmSync(sourcePath, { recursive: true });
+        fs.symlinkSync(path.join(home, "missing"), sourcePath);
+      },
+    });
+    assert.notEqual(result.status, 0);
+    assert.match(result.stderr, /canonical/);
+    assert.equal(fs.existsSync(path.join(worktreeCwd, ".paperclip")), false);
+    assert.deepEqual(readCliInvocations(baseCwd), []);
+  });
+}
+
+for (const file of ["config.json", ".env", "seed-manifest.json", "seed-pending", "seed-complete"]) {
+  test(`does not downgrade an existing development instance with ${file} when its source disappears`, () => {
+    const baseCwd = makeBaseWorkspace({ helpExit: 0, initExit: 0 });
+    const { result, worktreeCwd } = runProvision(baseCwd, {
+      setupInstance: (home) => fs.rmSync(path.join(home, "instances", "default", "config.json")),
+      setupWorktree(root) {
+        fs.mkdirSync(path.join(root, ".paperclip"));
+        fs.writeFileSync(path.join(root, ".paperclip", file), "retained state\n");
+      },
+    });
+    assert.notEqual(result.status, 0);
+    assert.match(result.stderr, /config is unavailable/);
+    assert.equal(fs.readFileSync(path.join(worktreeCwd, ".paperclip", file), "utf8"), "retained state\n");
+    assert.deepEqual(readCliInvocations(baseCwd), []);
+  });
+}
+
+for (const installExit of [0, 42]) {
+  test(`plain checkout dependency provisioning preserves install exit ${installExit}`, () => {
+    const baseCwd = makeBaseWorkspace({ helpExit: 0, initExit: 0 });
+    const bin = makeTempDir("paperclip-checkout-pnpm-");
+    fs.writeFileSync(path.join(bin, "pnpm"), `#!/bin/sh\nprintf '%s\\n' "$*" >> pnpm-calls\nmkdir -p node_modules cli/node_modules\nexit ${installExit}\n`, { mode: 0o700 });
+    const { result, worktreeCwd } = runProvision(baseCwd, {
+      pathPrefix: bin,
+      setupInstance: (home) => fs.rmSync(path.join(home, "instances", "default", "config.json")),
+      setupWorktree(root) {
+        fs.writeFileSync(path.join(root, "package.json"), "{}\n");
+        fs.writeFileSync(path.join(root, "pnpm-lock.yaml"), "lockfileVersion: '9.0'\n");
+      },
+    });
+    assert.equal(result.status, installExit, result.stderr);
+    assert.match(fs.readFileSync(path.join(worktreeCwd, "pnpm-calls"), "utf8"), /^install --prod=false --frozen-lockfile/);
+    assert.equal(fs.existsSync(path.join(worktreeCwd, ".paperclip", "pnpm-install-fingerprint")), installExit === 0);
+    assert.equal(fs.existsSync(path.join(worktreeCwd, ".paperclip", "config.json")), false);
+    assert.equal(fs.existsSync(path.join(worktreeCwd, ".paperclip", "seed-manifest.json")), false);
+    assert.deepEqual(readCliInvocations(baseCwd), []);
+  });
+}
+
 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 });