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>
2026-10-23 00:53:38 +02:00 · 2026-10-01 10:00:25 -07:00
1 parent 6d654f63d1
commit 6f2ce27ca7
@@ -837,8 +837,9 @@ The default `worktree init` still seeds eagerly. A lean worktree (created withou

 - `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 <source-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.
- If the built-in provisioner reports an unavailable seed source config, decide whether the task needs a seeded development instance or only an isolated checkout. A seeded instance needs a canonical config from the registered base workspace or control-plane instance; environment-only server configuration does not provide that file. For a checkout-only worktree, explicitly set the `git_worktree` strategy's `provisionCommand` to `"true"`. This skips setup and does not establish runtime or seed readiness. Repair rejected symlinks or non-regular source files instead of treating those validation failures as a missing prerequisite.
+- Managed Paperclip git worktrees default to the repository's `scripts/provision-worktree.sh` when the strategy omits `provisionCommand`. When a registered source config exists, setup creates the isolated config and pending manifest. 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.
+- An environment-configured server may have no local seed config. If neither the base checkout nor the default control-plane instance has one, a fresh worktree prepares its dependencies without creating a development instance. This also applies when `PAPERCLIP_CONFIG` names the default `$PAPERCLIP_HOME/instances/$PAPERCLIP_INSTANCE_ID/config.json` path, as the Docker image does. Setup creates no config, environment file, or seed manifest and does not claim runtime or seed readiness. A later request for a seeded development runtime still needs a canonical registered source config. Once that source exists, provisioning the checkout again creates the development instance normally.
+- A missing custom `PAPERCLIP_CONFIG`, rejected symlink, or non-regular source file still fails setup. An existing worktree with a config, environment file, or seed state also fails if its source disappears; setup never downgrades that instance to a plain checkout. Repair the source before retrying.
 - 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.
 - Worktrees created before lazy seeding shipped may have neither marker. Paperclip adopts them only after their configured database proves a compatible migration journal and the core Paperclip schema; otherwise managed startup creates a pending manifest and performs the normal verified seed. Manual markerless worktrees must provide `--from-config` so the source remains explicit.

@@ -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 });
@@ -5,6 +5,7 @@ base_cwd="${PAPERCLIP_WORKSPACE_BASE_CWD:?PAPERCLIP_WORKSPACE_BASE_CWD is requir
 worktree_cwd="${PAPERCLIP_WORKSPACE_CWD:?PAPERCLIP_WORKSPACE_CWD is required}"
 paperclip_home="${PAPERCLIP_HOME:-$HOME/.paperclip}"
 paperclip_instance_id="${PAPERCLIP_INSTANCE_ID:-default}"
+default_source_config_path="$paperclip_home/instances/$paperclip_instance_id/config.json"
 paperclip_dir="$worktree_cwd/.paperclip"
 worktree_config_path="$paperclip_dir/config.json"
 worktree_env_path="$paperclip_dir/.env"
@@ -53,26 +54,52 @@ 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}"
+  source_config_path="${PAPERCLIP_CONFIG:-$default_source_config_path}"
  source_config_origin="control-plane instance"
-fi
-if [[ ! -f "$source_config_path" || -L "$source_config_path" ]]; then
-  if [[ ! -e "$source_config_path" && ! -L "$source_config_path" ]]; then
-    echo "Registered Paperclip seed source config is unavailable ($source_config_origin): $source_config_path" >&2
-    echo "For a seeded development instance, configure a canonical config for that registered source before retrying." >&2
-    echo 'Only for a checkout-only worktree, explicitly set workspaceStrategy.provisionCommand to "true". This skips setup; it does not prepare a development runtime.' >&2
-  else
-    echo "Registered Paperclip seed source config is not a canonical file ($source_config_origin): $source_config_path" >&2
-    echo "Repair the registered source path; symlinks and non-regular files are not accepted." >&2
+  # Environment-configured servers need no local instance config. A new plain
+  # checkout can still prepare dependencies without inventing a seed source.
+  # The Docker image sets PAPERCLIP_CONFIG to this default even without a file.
+  # Custom sources and existing development instances must still fail closed.
+  if [[ "$source_config_path" == "$default_source_config_path" && ! -e "$source_config_path" && ! -L "$source_config_path" ]]; then
+    source_required=0
+    for target_state in "$worktree_config_path" "$worktree_env_path" "$seed_manifest_path" "$seed_pending_marker_path" "$seed_complete_marker_path"; do
+      if [[ -e "$target_state" || -L "$target_state" ]]; then
+        source_required=1
+      fi
+    done
+    if [[ "$source_required" -eq 0 ]]; then
+      # Do not mistake a broken or aliased parent path for an absent instance.
+      source_parent="$(dirname "$source_config_path")"
+      while [[ ! -e "$source_parent" && ! -L "$source_parent" ]]; do
+        source_parent="$(dirname "$source_parent")"
+      done
+      if [[ ! -d "$source_parent" || -L "$source_parent" || "$(cd "$source_parent" && pwd -P)" != "$source_parent" ]]; then
+        echo "Registered Paperclip seed source config has a non-canonical parent: $source_config_path" >&2
+        exit 1
+      fi
+      echo "No local Paperclip seed source config; preparing checkout dependencies without a seeded development instance." >&2
+      source_config_path=""
+    fi
  fi
-  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 Paperclip seed source config uses a symlink alias: $source_config_path" >&2
-  exit 1
+if [[ -n "$source_config_path" ]]; then
+  if [[ ! -f "$source_config_path" || -L "$source_config_path" ]]; then
+    if [[ ! -e "$source_config_path" && ! -L "$source_config_path" ]]; then
+      echo "Registered Paperclip seed source config is unavailable ($source_config_origin): $source_config_path" >&2
+      echo "For a seeded development instance, configure a canonical config for that registered source before retrying." >&2
+    else
+      echo "Registered Paperclip seed source config is not a canonical file ($source_config_origin): $source_config_path" >&2
+      echo "Repair the registered source path; symlinks and non-regular files are not accepted." >&2
+    fi
+    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 Paperclip seed source config uses a symlink alias: $source_config_path" >&2
+    exit 1
+  fi
+  source_env_path="$(dirname "$source_config_path")/.env"
 fi
-source_env_path="$(dirname "$source_config_path")/.env"

 mkdir -p "$paperclip_dir"

@@ -619,44 +646,46 @@ main().catch((error) => {
 EOF
 }

-if [[ -e "$worktree_config_path" && -e "$worktree_env_path" ]] && existing_worktree_config_is_usable; then
-  echo "Reusing existing isolated Paperclip worktree config at $worktree_config_path" >&2
-else
-  if [[ -e "$worktree_config_path" || -e "$worktree_env_path" ]]; then
-    echo "Existing isolated Paperclip worktree config is stale for this host; regenerating." >&2
-  fi
-  if paperclipai_command_available; then
-    if run_isolated_worktree_init; then
-      :
-    else
-      init_exit_code=$?
-      if [[ "$init_exit_code" -eq 127 ]]; then
-        # Every CLI candidate was unusable (e.g. an unhealthy base install that
-        # the repair could not fix); degrade instead of stranding the run.
-        echo "No usable paperclipai CLI found; writing isolated fallback config without DB seeding." >&2
-        write_fallback_worktree_config
-      else
-        # A CLI that ran and failed signals a real problem; do not paper over
-        # it with an unseeded fallback config.
-        echo "paperclipai worktree init failed (exit $init_exit_code); failing provisioning instead of writing an unseeded fallback config." >&2
-        exit "$init_exit_code"
-      fi
-    fi
+if [[ -n "$source_config_path" ]]; then
+  if [[ -e "$worktree_config_path" && -e "$worktree_env_path" ]] && existing_worktree_config_is_usable; then
+    echo "Reusing existing isolated Paperclip worktree config at $worktree_config_path" >&2
  else
-    echo "paperclipai worktree init unavailable; writing isolated fallback config without DB seeding." >&2
-    write_fallback_worktree_config
+    if [[ -e "$worktree_config_path" || -e "$worktree_env_path" ]]; then
+      echo "Existing isolated Paperclip worktree config is stale for this host; regenerating." >&2
+    fi
+    if paperclipai_command_available; then
+      if run_isolated_worktree_init; then
+        :
+      else
+        init_exit_code=$?
+        if [[ "$init_exit_code" -eq 127 ]]; then
+          # Every CLI candidate was unusable (e.g. an unhealthy base install that
+          # the repair could not fix); degrade instead of stranding the run.
+          echo "No usable paperclipai CLI found; writing isolated fallback config without DB seeding." >&2
+          write_fallback_worktree_config
+        else
+          # A CLI that ran and failed signals a real problem; do not paper over
+          # it with an unseeded fallback config.
+          echo "paperclipai worktree init failed (exit $init_exit_code); failing provisioning instead of writing an unseeded fallback config." >&2
+          exit "$init_exit_code"
+        fi
+      fi
+    else
+      echo "paperclipai worktree init unavailable; writing isolated fallback config without DB seeding." >&2
+      write_fallback_worktree_config
+    fi
+    created_worktree_config=1
  fi
-  created_worktree_config=1
-fi

-# The target config can predate a deployment-mode change on the registered
-# source, and older/fallback CLI writers may default this field independently.
-# Reconcile it after either create or reuse so the final guest config always
-# carries the source's deployment/auth contract without replacing its database.
-reconcile_worktree_deployment_mode
+  # The target config can predate a deployment-mode change on the registered
+  # source, and older/fallback CLI writers may default this field independently.
+  # Reconcile it after either create or reuse so the final guest config always
+  # carries the source's deployment/auth contract without replacing its database.
+  reconcile_worktree_deployment_mode

-if [[ "$created_worktree_config" -eq 1 && ! -e "$seed_manifest_path" && ! -e "$seed_pending_marker_path" && ! -e "$seed_complete_marker_path" ]]; then
-  write_seed_pending_manifest
+  if [[ "$created_worktree_config" -eq 1 && ! -e "$seed_manifest_path" && ! -e "$seed_pending_marker_path" && ! -e "$seed_complete_marker_path" ]]; then
+    write_seed_pending_manifest
+  fi
 fi

 list_base_node_modules_paths() {
@@ -920,6 +920,43 @@ describe("realizeExecutionWorkspace", () => {
    }
  });

+  it.each([false, true])("realizes a plain Paperclip checkout without a local seed instance (image default env: %s)", async (defaultConfigInEnv) => {
+    const repoRoot = await createTempRepo();
+    const paperclipHome = await fs.realpath(await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-env-only-home-")));
+    const previousEnv = {
+      PAPERCLIP_HOME: process.env.PAPERCLIP_HOME,
+      PAPERCLIP_CONFIG: process.env.PAPERCLIP_CONFIG,
+      PAPERCLIP_INSTANCE_ID: process.env.PAPERCLIP_INSTANCE_ID,
+    };
+    try {
+      await fs.mkdir(path.join(repoRoot, "scripts"));
+      await fs.copyFile(provisionWorktreeScriptPath, path.join(repoRoot, "scripts", "provision-worktree.sh"));
+      await runGit(repoRoot, ["add", "scripts/provision-worktree.sh"]);
+      await runGit(repoRoot, ["commit", "-m", "Add Paperclip worktree provisioner"]);
+      process.env.PAPERCLIP_HOME = paperclipHome;
+      process.env.PAPERCLIP_INSTANCE_ID = "default";
+      if (defaultConfigInEnv) process.env.PAPERCLIP_CONFIG = path.join(paperclipHome, "instances", "default", "config.json");
+      else delete process.env.PAPERCLIP_CONFIG;
+
+      const workspace = await realizeWorktreeForTest(repoRoot, "HEAD");
+
+      expect(workspace.strategy).toBe("git_worktree");
+      expect(workspace.created).toBe(true);
+      expect(await readGit(workspace.cwd, ["branch", "--show-current"])).toBe(workspace.branchName);
+      for (const file of ["config.json", ".env", "seed-manifest.json", "seed-pending", "seed-complete"]) {
+        expect(existsSync(path.join(workspace.cwd, ".paperclip", file))).toBe(false);
+      }
+      expect(await fs.readdir(paperclipHome)).toEqual([]);
+    } finally {
+      for (const [key, value] of Object.entries(previousEnv)) {
+        if (value === undefined) delete process.env[key];
+        else process.env[key] = value;
+      }
+      await fs.rm(repoRoot, { recursive: true, force: true });
+      await fs.rm(paperclipHome, { recursive: true, force: true });
+    }
+  });
+
  it("defaults the repo-provided worktree provisioner for git worktree strategies", async () => {
    const repoRoot = await createTempRepo();
    await fs.mkdir(path.join(repoRoot, "scripts"), { recursive: true });