From a5aed931ab34dacb78f47fd845b60a30a2df7285 Mon Sep 17 00:00:00 2001
From: Dotta <bippadotta@protonmail.com>
Date: Sat, 11 Apr 2026 08:35:53 -0500
Subject: [PATCH] fix(dev-runner): tighten worktree env bootstrap

---
 scripts/dev-runner.ts                            |  2 +-
 server/src/__tests__/dev-runner-worktree.test.ts |  2 ++
 server/src/dev-runner-worktree.ts                | 14 ++++++++++----
 3 files changed, 13 insertions(+), 5 deletions(-)

diff --git a/scripts/dev-runner.ts b/scripts/dev-runner.ts
index 1c991b99..a26ef638 100644
--- a/scripts/dev-runner.ts
+++ b/scripts/dev-runner.ts
@@ -23,7 +23,7 @@ type BindMode = (typeof BIND_MODES)[number];
 const worktreeEnvBootstrap = bootstrapDevRunnerWorktreeEnv(repoRoot, process.env);
 if (worktreeEnvBootstrap.missingEnv) {
   console.error(
-    `[paperclip] linked git worktree at ${repoRoot} is missing ${path.relative(repoRoot, worktreeEnvBootstrap.envPath ?? "")}. Run \`paperclipai worktree init\` in this worktree before \`pnpm dev\`.`,
+    `[paperclip] linked git worktree at ${repoRoot} is missing ${path.relative(repoRoot, worktreeEnvBootstrap.envPath)}. Run \`paperclipai worktree init\` in this worktree before \`pnpm dev\`.`,
   );
   process.exit(1);
 }
diff --git a/server/src/__tests__/dev-runner-worktree.test.ts b/server/src/__tests__/dev-runner-worktree.test.ts
index 714cb54b..461f2aab 100644
--- a/server/src/__tests__/dev-runner-worktree.test.ts
+++ b/server/src/__tests__/dev-runner-worktree.test.ts
@@ -42,6 +42,7 @@ describe("dev-runner worktree env bootstrap", () => {
         "PAPERCLIP_INSTANCE_ID=feature-worktree",
         "PAPERCLIP_IN_WORKTREE=true",
         "PAPERCLIP_WORKTREE_NAME=feature-worktree",
+        "PAPERCLIP_OPTIONAL= # comment-only value",
         "",
       ].join("\n"),
       "utf8",
@@ -59,6 +60,7 @@ describe("dev-runner worktree env bootstrap", () => {
     expect(env.PAPERCLIP_HOME).toBe("/tmp/paperclip-worktrees");
     expect(env.PAPERCLIP_INSTANCE_ID).toBe("already-set");
     expect(env.PAPERCLIP_IN_WORKTREE).toBe("true");
+    expect(env.PAPERCLIP_OPTIONAL).toBe("");
   });
 
   it("reports uninitialized linked worktrees so dev runner can fail fast", () => {
diff --git a/server/src/dev-runner-worktree.ts b/server/src/dev-runner-worktree.ts
index 286087ef..4e2b5d8d 100644
--- a/server/src/dev-runner-worktree.ts
+++ b/server/src/dev-runner-worktree.ts
@@ -17,6 +17,10 @@ function parseEnvFile(contents: string): Record<string, string> {
       entries[key] = "";
       continue;
     }
+    if (value.startsWith("#")) {
+      entries[key] = "";
+      continue;
+    }
 
     if (
       (value.startsWith("\"") && value.endsWith("\"")) ||
@@ -32,6 +36,11 @@ function parseEnvFile(contents: string): Record<string, string> {
   return entries;
 }
 
+type WorktreeEnvBootstrapResult =
+  | { envPath: null; missingEnv: false }
+  | { envPath: string; missingEnv: true }
+  | { envPath: string; missingEnv: false };
+
 export function isLinkedGitWorktreeCheckout(rootDir: string): boolean {
   const gitMetadataPath = path.join(rootDir, ".git");
   if (!existsSync(gitMetadataPath)) return false;
@@ -49,10 +58,7 @@ export function resolveWorktreeEnvFilePath(rootDir: string): string {
 export function bootstrapDevRunnerWorktreeEnv(
   rootDir: string,
   env: NodeJS.ProcessEnv = process.env,
-): {
-  envPath: string | null;
-  missingEnv: boolean;
-} {
+): WorktreeEnvBootstrapResult {
   if (!isLinkedGitWorktreeCheckout(rootDir)) {
     return {
       envPath: null,