diff --git a/.gitignore b/.gitignore
index 42840131381..63de6b12829 100644
--- a/.gitignore
+++ b/.gitignore
@@ -45,6 +45,7 @@ diagnostics/
 .vscode/
 .claude/settings.local.json
 .paperclip-local/
+.paperclip-runtime/
 /.idea/
 /.agents/
 
diff --git a/packages/shared/src/gitignore-runtime.test.ts b/packages/shared/src/gitignore-runtime.test.ts
new file mode 100644
index 00000000000..e334ab0eca8
--- /dev/null
+++ b/packages/shared/src/gitignore-runtime.test.ts
@@ -0,0 +1,18 @@
+import { execSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+// packages/shared/src/ is three levels below the repo root
+const REPO_ROOT = fileURLToPath(new URL("../../../", import.meta.url));
+
+describe("gitignore: .paperclip-runtime/", () => {
+  it("ignores files under .paperclip-runtime/ via the explicit gitignore rule", () => {
+    const output = execSync(
+      "git check-ignore -v .paperclip-runtime/codex/home/auth.json",
+      { cwd: REPO_ROOT, encoding: "utf8" },
+    ).trim();
+    // Output format: <source>:<line>:<pattern>\t<path>
+    // Asserts that the rule comes from .gitignore and matches .paperclip-runtime/
+    expect(output).toMatch(/^\.gitignore:\d+:\.paperclip-runtime\//);
+  });
+});