From 5c7d2116e96d06c9d0cbd19fce620cb3bc44e1e7 Mon Sep 17 00:00:00 2001
From: Paperclip <noreply@paperclip.ing>
Date: Thu, 12 Mar 2026 14:33:11 -0500
Subject: [PATCH 01/28] Fix local-cli skill install for moved .agents skills

Co-Authored-By: Paperclip <noreply@paperclip.ing>
---
 cli/src/commands/client/agent.ts | 49 ++++++++++++++++++++++++++++++--
 1 file changed, 46 insertions(+), 3 deletions(-)

diff --git a/cli/src/commands/client/agent.ts b/cli/src/commands/client/agent.ts
index 36eb04e6..a6e86277 100644
--- a/cli/src/commands/client/agent.ts
+++ b/cli/src/commands/client/agent.ts
@@ -40,7 +40,9 @@ interface SkillsInstallSummary {
 
 const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
 const PAPERCLIP_SKILLS_CANDIDATES = [
+  path.resolve(__moduleDir, "../../../../../.agents/skills"), // dev: cli/src/commands/client -> repo root/.agents/skills
   path.resolve(__moduleDir, "../../../../../skills"), // dev: cli/src/commands/client -> repo root/skills
+  path.resolve(process.cwd(), ".agents/skills"),
   path.resolve(process.cwd(), "skills"),
 ];
 
@@ -85,8 +87,48 @@ async function installSkillsForTarget(
     const target = path.join(targetSkillsDir, entry.name);
     const existing = await fs.lstat(target).catch(() => null);
     if (existing) {
-      summary.skipped.push(entry.name);
-      continue;
+      if (existing.isSymbolicLink()) {
+        let linkedPath: string | null = null;
+        try {
+          linkedPath = await fs.readlink(target);
+        } catch (err) {
+          await fs.unlink(target);
+          try {
+            await fs.symlink(source, target);
+            summary.linked.push(entry.name);
+            continue;
+          } catch (linkErr) {
+            summary.failed.push({
+              name: entry.name,
+              error:
+                err instanceof Error && linkErr instanceof Error
+                  ? `${err.message}; then ${linkErr.message}`
+                  : err instanceof Error
+                    ? err.message
+                    : `Failed to recover broken symlink: ${String(err)}`,
+            });
+            continue;
+          }
+        }
+
+        const resolvedLinkedPath = path.isAbsolute(linkedPath)
+          ? linkedPath
+          : path.resolve(path.dirname(target), linkedPath);
+        const linkedTargetExists = await fs
+          .stat(resolvedLinkedPath)
+          .then(() => true)
+          .catch(() => false);
+
+        if (!linkedTargetExists) {
+          await fs.unlink(target);
+        } else {
+          summary.skipped.push(entry.name);
+          continue;
+        }
+      } else {
+        summary.skipped.push(entry.name);
+        continue;
+      }
     }
 
     try {
@@ -98,6 +140,7 @@ async function installSkillsForTarget(
         error: err instanceof Error ? err.message : String(err),
       });
     }
+    }
   }
 
   return summary;
@@ -213,7 +256,7 @@ export function registerAgentCommands(program: Command): void {
             const skillsDir = await resolvePaperclipSkillsDir();
             if (!skillsDir) {
               throw new Error(
-                "Could not locate local Paperclip skills directory. Expected ./skills in the repo checkout.",
+                "Could not locate local Paperclip skills directory. Expected ./skills or ./.agents/skills in the repo checkout.",
               );
             }
 

From 69b9e45eaf923df4c8e8694e6c30387e4094d11c Mon Sep 17 00:00:00 2001
From: Dotta <bippadotta@protonmail.com>
Date: Thu, 12 Mar 2026 14:39:50 -0500
Subject: [PATCH 02/28] Change sidebar Documentation link to external
 docs.paperclip.ing

The sidebar Documentation links were pointing to an internal /docs route.
Updated both mobile and desktop sidebar instances to link to
https://docs.paperclip.ing/ in a new tab instead.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 ui/src/components/Layout.tsx | 31 ++++++++++++++++++-------------
 1 file changed, 18 insertions(+), 13 deletions(-)

diff --git a/ui/src/components/Layout.tsx b/ui/src/components/Layout.tsx
index 12cc6f88..a90efa9a 100644
--- a/ui/src/components/Layout.tsx
+++ b/ui/src/components/Layout.tsx
@@ -5,7 +5,6 @@ import { Link, Outlet, useLocation, useNavigate, useParams } from "@/lib/router"
 import { CompanyRail } from "./CompanyRail";
 import { Sidebar } from "./Sidebar";
 import { InstanceSidebar } from "./InstanceSidebar";
-import { SidebarNavItem } from "./SidebarNavItem";
 import { BreadcrumbBar } from "./BreadcrumbBar";
 import { PropertiesPanel } from "./PropertiesPanel";
 import { CommandPalette } from "./CommandPalette";
@@ -248,12 +247,15 @@ export function Layout() {
           </div>
           <div className="border-t border-r border-border px-3 py-2 bg-background">
             <div className="flex items-center gap-1">
-              <SidebarNavItem
-                to="/docs"
-                label="Documentation"
-                icon={BookOpen}
-                className="flex-1 min-w-0"
-              />
+              <a
+                href="https://docs.paperclip.ing/"
+                target="_blank"
+                rel="noopener noreferrer"
+                className="flex items-center gap-2.5 px-3 py-2 text-[13px] font-medium transition-colors text-foreground/80 hover:bg-accent/50 hover:text-foreground flex-1 min-w-0"
+              >
+                <BookOpen className="h-4 w-4 shrink-0" />
+                <span className="truncate">Documentation</span>
+              </a>
               <Button variant="ghost" size="icon-sm" className="text-muted-foreground shrink-0" asChild>
                 <Link
                   to="/instance/settings"
@@ -295,12 +297,15 @@ export function Layout() {
           </div>
           <div className="border-t border-r border-border px-3 py-2">
             <div className="flex items-center gap-1">
-              <SidebarNavItem
-                to="/docs"
-                label="Documentation"
-                icon={BookOpen}
-                className="flex-1 min-w-0"
-              />
+              <a
+                href="https://docs.paperclip.ing/"
+                target="_blank"
+                rel="noopener noreferrer"
+                className="flex items-center gap-2.5 px-3 py-2 text-[13px] font-medium transition-colors text-foreground/80 hover:bg-accent/50 hover:text-foreground flex-1 min-w-0"
+              >
+                <BookOpen className="h-4 w-4 shrink-0" />
+                <span className="truncate">Documentation</span>
+              </a>
               <Button variant="ghost" size="icon-sm" className="text-muted-foreground shrink-0" asChild>
                 <Link
                   to="/instance/settings"

From 4e759da070fc597e20233e430a5d52d78f33216d Mon Sep 17 00:00:00 2001
From: Dotta <bippadotta@protonmail.com>
Date: Thu, 12 Mar 2026 15:44:44 -0500
Subject: [PATCH 03/28] fix: prefer .agents skills and repair codex symlink
 targets\n\nCo-Authored-By: Paperclip <noreply@paperclip.ing>

---
 packages/adapter-utils/src/server-utils.ts    | 95 +++++++++++++++++++
 .../codex-local/src/server/execute.ts         | 43 ++++-----
 .../adapters/codex-local/src/server/index.ts  |  2 +-
 .../cursor-local/src/server/execute.ts        | 50 +++-------
 .../gemini-local/src/server/execute.ts        | 43 +++------
 .../adapters/pi-local/src/server/execute.ts   | 32 ++-----
 6 files changed, 151 insertions(+), 114 deletions(-)

diff --git a/packages/adapter-utils/src/server-utils.ts b/packages/adapter-utils/src/server-utils.ts
index 2b9de31f..15f0ada8 100644
--- a/packages/adapter-utils/src/server-utils.ts
+++ b/packages/adapter-utils/src/server-utils.ts
@@ -32,6 +32,17 @@ export const runningProcesses = new Map<string, RunningProcess>();
 export const MAX_CAPTURE_BYTES = 4 * 1024 * 1024;
 export const MAX_EXCERPT_BYTES = 32 * 1024;
 const SENSITIVE_ENV_KEY = /(key|token|secret|password|passwd|authorization|cookie)/i;
+const PAPERCLIP_SKILL_ROOT_RELATIVE_CANDIDATES = [
+  "../../.agents/skills",
+  "../../skills",
+  "../../../../../.agents/skills",
+  "../../../../../skills",
+];
+
+export interface PaperclipSkillEntry {
+  name: string;
+  source: string;
+}
 
 export function parseObject(value: unknown): Record<string, unknown> {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
@@ -245,6 +256,90 @@ export async function ensureAbsoluteDirectory(
   }
 }
 
+export async function listPaperclipSkillEntries(moduleDir: string): Promise<PaperclipSkillEntry[]> {
+  const entriesByName = new Map<string, PaperclipSkillEntry>();
+  const seenRoots = new Set<string>();
+
+  for (const relativePath of PAPERCLIP_SKILL_ROOT_RELATIVE_CANDIDATES) {
+    const root = path.resolve(moduleDir, relativePath);
+    if (seenRoots.has(root)) continue;
+    seenRoots.add(root);
+
+    const isDirectory = await fs.stat(root).then((stats) => stats.isDirectory()).catch(() => false);
+    if (!isDirectory) continue;
+
+    let entries: Awaited<ReturnType<typeof fs.readdir>>;
+    try {
+      entries = await fs.readdir(root, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entriesByName.has(entry.name)) continue;
+      entriesByName.set(entry.name, {
+        name: entry.name,
+        source: path.join(root, entry.name),
+      });
+    }
+  }
+
+  return Array.from(entriesByName.values());
+}
+
+export async function readPaperclipSkillMarkdown(
+  moduleDir: string,
+  skillName: string,
+): Promise<string | null> {
+  const normalized = skillName.trim().toLowerCase();
+  if (!normalized) return null;
+
+  const entries = await listPaperclipSkillEntries(moduleDir);
+  const match = entries.find((entry) => entry.name === normalized);
+  if (!match) return null;
+
+  try {
+    return await fs.readFile(path.join(match.source, "SKILL.md"), "utf8");
+  } catch {
+    return null;
+  }
+}
+
+export async function ensurePaperclipSkillSymlink(
+  source: string,
+  target: string,
+  linkSkill: (source: string, target: string) => Promise<void> = (linkSource, linkTarget) =>
+    fs.symlink(linkSource, linkTarget),
+): Promise<"created" | "repaired" | "skipped"> {
+  const existing = await fs.lstat(target).catch(() => null);
+  if (!existing) {
+    await linkSkill(source, target);
+    return "created";
+  }
+
+  if (!existing.isSymbolicLink()) {
+    return "skipped";
+  }
+
+  const linkedPath = await fs.readlink(target).catch(() => null);
+  if (!linkedPath) return "skipped";
+
+  const resolvedLinkedPath = path.resolve(path.dirname(target), linkedPath);
+  if (resolvedLinkedPath === source) {
+    return "skipped";
+  }
+
+  const linkedPathExists = await fs.stat(resolvedLinkedPath).then(() => true).catch(() => false);
+  if (linkedPathExists) {
+    return "skipped";
+  }
+
+  await fs.unlink(target);
+  await linkSkill(source, target);
+  return "repaired";
+}
+
 export async function ensureCommandResolvable(command: string, cwd: string, env: NodeJS.ProcessEnv) {
   const resolved = await resolveCommandPath(command, cwd, env);
   if (resolved) return;
diff --git a/packages/adapters/codex-local/src/server/execute.ts b/packages/adapters/codex-local/src/server/execute.ts
index 3dec4ff7..3afbf09e 100644
--- a/packages/adapters/codex-local/src/server/execute.ts
+++ b/packages/adapters/codex-local/src/server/execute.ts
@@ -13,17 +13,15 @@ import {
   redactEnvForLogs,
   ensureAbsoluteDirectory,
   ensureCommandResolvable,
+  ensurePaperclipSkillSymlink,
   ensurePathInEnv,
+  listPaperclipSkillEntries,
   renderTemplate,
   runChildProcess,
 } from "@paperclipai/adapter-utils/server-utils";
 import { parseCodexJsonl, isCodexUnknownSessionError } from "./parse.js";
 
 const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
-const PAPERCLIP_SKILLS_CANDIDATES = [
-  path.resolve(__moduleDir, "../../skills"),         // published: <pkg>/dist/server/ -> <pkg>/skills/
-  path.resolve(__moduleDir, "../../../../../skills"), // dev: src/server/ -> repo root/skills/
-];
 const CODEX_ROLLOUT_NOISE_RE =
   /^\d{4}-\d{2}-\d{2}T[^\s]+\s+ERROR\s+codex_core::rollout::list:\s+state db missing rollout path for thread\s+[a-z0-9-]+$/i;
 
@@ -67,33 +65,32 @@ function codexHomeDir(): string {
   return path.join(os.homedir(), ".codex");
 }
 
-async function resolvePaperclipSkillsDir(): Promise<string | null> {
-  for (const candidate of PAPERCLIP_SKILLS_CANDIDATES) {
-    const isDir = await fs.stat(candidate).then((s) => s.isDirectory()).catch(() => false);
-    if (isDir) return candidate;
-  }
-  return null;
-}
+type EnsureCodexSkillsInjectedOptions = {
+  skillsHome?: string;
+  skillsEntries?: Awaited<ReturnType<typeof listPaperclipSkillEntries>>;
+  linkSkill?: (source: string, target: string) => Promise<void>;
+};
 
-async function ensureCodexSkillsInjected(onLog: AdapterExecutionContext["onLog"]) {
-  const skillsDir = await resolvePaperclipSkillsDir();
-  if (!skillsDir) return;
+export async function ensureCodexSkillsInjected(
+  onLog: AdapterExecutionContext["onLog"],
+  options: EnsureCodexSkillsInjectedOptions = {},
+) {
+  const skillsEntries = options.skillsEntries ?? await listPaperclipSkillEntries(__moduleDir);
+  if (skillsEntries.length === 0) return;
 
-  const skillsHome = path.join(codexHomeDir(), "skills");
+  const skillsHome = options.skillsHome ?? path.join(codexHomeDir(), "skills");
   await fs.mkdir(skillsHome, { recursive: true });
-  const entries = await fs.readdir(skillsDir, { withFileTypes: true });
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-    const source = path.join(skillsDir, entry.name);
+  const linkSkill = options.linkSkill;
+  for (const entry of skillsEntries) {
     const target = path.join(skillsHome, entry.name);
-    const existing = await fs.lstat(target).catch(() => null);
-    if (existing) continue;
 
     try {
-      await fs.symlink(source, target);
+      const result = await ensurePaperclipSkillSymlink(entry.source, target, linkSkill);
+      if (result === "skipped") continue;
+
       await onLog(
         "stderr",
-        `[paperclip] Injected Codex skill "${entry.name}" into ${skillsHome}\n`,
+        `[paperclip] ${result === "repaired" ? "Repaired" : "Injected"} Codex skill "${entry.name}" into ${skillsHome}\n`,
       );
     } catch (err) {
       await onLog(
diff --git a/packages/adapters/codex-local/src/server/index.ts b/packages/adapters/codex-local/src/server/index.ts
index 1b8dad75..04c1e368 100644
--- a/packages/adapters/codex-local/src/server/index.ts
+++ b/packages/adapters/codex-local/src/server/index.ts
@@ -1,4 +1,4 @@
-export { execute } from "./execute.js";
+export { execute, ensureCodexSkillsInjected } from "./execute.js";
 export { testEnvironment } from "./test.js";
 export { parseCodexJsonl, isCodexUnknownSessionError } from "./parse.js";
 import type { AdapterSessionCodec } from "@paperclipai/adapter-utils";
diff --git a/packages/adapters/cursor-local/src/server/execute.ts b/packages/adapters/cursor-local/src/server/execute.ts
index 162ed5c6..ae068c1c 100644
--- a/packages/adapters/cursor-local/src/server/execute.ts
+++ b/packages/adapters/cursor-local/src/server/execute.ts
@@ -1,5 +1,4 @@
 import fs from "node:fs/promises";
-import type { Dirent } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -13,7 +12,9 @@ import {
   redactEnvForLogs,
   ensureAbsoluteDirectory,
   ensureCommandResolvable,
+  ensurePaperclipSkillSymlink,
   ensurePathInEnv,
+  listPaperclipSkillEntries,
   renderTemplate,
   runChildProcess,
 } from "@paperclipai/adapter-utils/server-utils";
@@ -23,10 +24,6 @@ import { normalizeCursorStreamLine } from "../shared/stream.js";
 import { hasCursorTrustBypassArg } from "../shared/trust.js";
 
 const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
-const PAPERCLIP_SKILLS_CANDIDATES = [
-  path.resolve(__moduleDir, "../../skills"),
-  path.resolve(__moduleDir, "../../../../../skills"),
-];
 
 function firstNonEmptyLine(text: string): string {
   return (
@@ -82,16 +79,9 @@ function cursorSkillsHome(): string {
   return path.join(os.homedir(), ".cursor", "skills");
 }
 
-async function resolvePaperclipSkillsDir(): Promise<string | null> {
-  for (const candidate of PAPERCLIP_SKILLS_CANDIDATES) {
-    const isDir = await fs.stat(candidate).then((s) => s.isDirectory()).catch(() => false);
-    if (isDir) return candidate;
-  }
-  return null;
-}
-
 type EnsureCursorSkillsInjectedOptions = {
   skillsDir?: string | null;
+  skillsEntries?: Array<{ name: string; source: string }>;
   skillsHome?: string;
   linkSkill?: (source: string, target: string) => Promise<void>;
 };
@@ -100,8 +90,13 @@ export async function ensureCursorSkillsInjected(
   onLog: AdapterExecutionContext["onLog"],
   options: EnsureCursorSkillsInjectedOptions = {},
 ) {
-  const skillsDir = options.skillsDir ?? await resolvePaperclipSkillsDir();
-  if (!skillsDir) return;
+  const skillsEntries = options.skillsEntries
+    ?? (options.skillsDir
+      ? (await fs.readdir(options.skillsDir, { withFileTypes: true }))
+          .filter((entry) => entry.isDirectory())
+          .map((entry) => ({ name: entry.name, source: path.join(options.skillsDir!, entry.name) }))
+      : await listPaperclipSkillEntries(__moduleDir));
+  if (skillsEntries.length === 0) return;
 
   const skillsHome = options.skillsHome ?? cursorSkillsHome();
   try {
@@ -113,31 +108,16 @@ export async function ensureCursorSkillsInjected(
     );
     return;
   }
-
-  let entries: Dirent[];
-  try {
-    entries = await fs.readdir(skillsDir, { withFileTypes: true });
-  } catch (err) {
-    await onLog(
-      "stderr",
-      `[paperclip] Failed to read Paperclip skills from ${skillsDir}: ${err instanceof Error ? err.message : String(err)}\n`,
-    );
-    return;
-  }
-
   const linkSkill = options.linkSkill ?? ((source: string, target: string) => fs.symlink(source, target));
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-    const source = path.join(skillsDir, entry.name);
+  for (const entry of skillsEntries) {
     const target = path.join(skillsHome, entry.name);
-    const existing = await fs.lstat(target).catch(() => null);
-    if (existing) continue;
-
     try {
-      await linkSkill(source, target);
+      const result = await ensurePaperclipSkillSymlink(entry.source, target, linkSkill);
+      if (result === "skipped") continue;
+
       await onLog(
         "stderr",
-        `[paperclip] Injected Cursor skill "${entry.name}" into ${skillsHome}\n`,
+        `[paperclip] ${result === "repaired" ? "Repaired" : "Injected"} Cursor skill "${entry.name}" into ${skillsHome}\n`,
       );
     } catch (err) {
       await onLog(
diff --git a/packages/adapters/gemini-local/src/server/execute.ts b/packages/adapters/gemini-local/src/server/execute.ts
index 4ffb51e3..fa27bffa 100644
--- a/packages/adapters/gemini-local/src/server/execute.ts
+++ b/packages/adapters/gemini-local/src/server/execute.ts
@@ -12,7 +12,9 @@ import {
   buildPaperclipEnv,
   ensureAbsoluteDirectory,
   ensureCommandResolvable,
+  ensurePaperclipSkillSymlink,
   ensurePathInEnv,
+  listPaperclipSkillEntries,
   parseObject,
   redactEnvForLogs,
   renderTemplate,
@@ -29,10 +31,6 @@ import {
 import { firstNonEmptyLine } from "./utils.js";
 
 const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
-const PAPERCLIP_SKILLS_CANDIDATES = [
-  path.resolve(__moduleDir, "../../skills"),
-  path.resolve(__moduleDir, "../../../../../skills"),
-];
 
 function hasNonEmptyEnvValue(env: Record<string, string>, key: string): boolean {
   const raw = env[key];
@@ -73,14 +71,6 @@ function renderApiAccessNote(env: Record<string, string>): string {
   ].join("\n");
 }
 
-async function resolvePaperclipSkillsDir(): Promise<string | null> {
-  for (const candidate of PAPERCLIP_SKILLS_CANDIDATES) {
-    const isDir = await fs.stat(candidate).then((s) => s.isDirectory()).catch(() => false);
-    if (isDir) return candidate;
-  }
-  return null;
-}
-
 function geminiSkillsHome(): string {
   return path.join(os.homedir(), ".gemini", "skills");
 }
@@ -93,8 +83,8 @@ function geminiSkillsHome(): string {
 async function ensureGeminiSkillsInjected(
   onLog: AdapterExecutionContext["onLog"],
 ): Promise<void> {
-  const skillsDir = await resolvePaperclipSkillsDir();
-  if (!skillsDir) return;
+  const skillsEntries = await listPaperclipSkillEntries(__moduleDir);
+  if (skillsEntries.length === 0) return;
 
   const skillsHome = geminiSkillsHome();
   try {
@@ -107,27 +97,16 @@ async function ensureGeminiSkillsInjected(
     return;
   }
 
-  let entries: Dirent[];
-  try {
-    entries = await fs.readdir(skillsDir, { withFileTypes: true });
-  } catch (err) {
-    await onLog(
-      "stderr",
-      `[paperclip] Failed to read Paperclip skills from ${skillsDir}: ${err instanceof Error ? err.message : String(err)}\n`,
-    );
-    return;
-  }
-
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-    const source = path.join(skillsDir, entry.name);
+  for (const entry of skillsEntries) {
     const target = path.join(skillsHome, entry.name);
-    const existing = await fs.lstat(target).catch(() => null);
-    if (existing) continue;
 
     try {
-      await fs.symlink(source, target);
-      await onLog("stderr", `[paperclip] Linked Gemini skill: ${entry.name}\n`);
+      const result = await ensurePaperclipSkillSymlink(entry.source, target);
+      if (result === "skipped") continue;
+      await onLog(
+        "stderr",
+        `[paperclip] ${result === "repaired" ? "Repaired" : "Linked"} Gemini skill: ${entry.name}\n`,
+      );
     } catch (err) {
       await onLog(
         "stderr",
diff --git a/packages/adapters/pi-local/src/server/execute.ts b/packages/adapters/pi-local/src/server/execute.ts
index 23cad28b..6fabe32d 100644
--- a/packages/adapters/pi-local/src/server/execute.ts
+++ b/packages/adapters/pi-local/src/server/execute.ts
@@ -12,7 +12,9 @@ import {
   redactEnvForLogs,
   ensureAbsoluteDirectory,
   ensureCommandResolvable,
+  ensurePaperclipSkillSymlink,
   ensurePathInEnv,
+  listPaperclipSkillEntries,
   renderTemplate,
   runChildProcess,
 } from "@paperclipai/adapter-utils/server-utils";
@@ -20,10 +22,6 @@ import { isPiUnknownSessionError, parsePiJsonl } from "./parse.js";
 import { ensurePiModelConfiguredAndAvailable } from "./models.js";
 
 const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
-const PAPERCLIP_SKILLS_CANDIDATES = [
-  path.resolve(__moduleDir, "../../skills"),
-  path.resolve(__moduleDir, "../../../../../skills"),
-];
 
 const PAPERCLIP_SESSIONS_DIR = path.join(os.homedir(), ".pi", "paperclips");
 
@@ -50,34 +48,22 @@ function parseModelId(model: string | null): string | null {
   return trimmed.slice(trimmed.indexOf("/") + 1).trim() || null;
 }
 
-async function resolvePaperclipSkillsDir(): Promise<string | null> {
-  for (const candidate of PAPERCLIP_SKILLS_CANDIDATES) {
-    const isDir = await fs.stat(candidate).then((s) => s.isDirectory()).catch(() => false);
-    if (isDir) return candidate;
-  }
-  return null;
-}
-
 async function ensurePiSkillsInjected(onLog: AdapterExecutionContext["onLog"]) {
-  const skillsDir = await resolvePaperclipSkillsDir();
-  if (!skillsDir) return;
+  const skillsEntries = await listPaperclipSkillEntries(__moduleDir);
+  if (skillsEntries.length === 0) return;
 
   const piSkillsHome = path.join(os.homedir(), ".pi", "agent", "skills");
   await fs.mkdir(piSkillsHome, { recursive: true });
-  
-  const entries = await fs.readdir(skillsDir, { withFileTypes: true });
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-    const source = path.join(skillsDir, entry.name);
+
+  for (const entry of skillsEntries) {
     const target = path.join(piSkillsHome, entry.name);
-    const existing = await fs.lstat(target).catch(() => null);
-    if (existing) continue;
 
     try {
-      await fs.symlink(source, target);
+      const result = await ensurePaperclipSkillSymlink(entry.source, target);
+      if (result === "skipped") continue;
       await onLog(
         "stderr",
-        `[paperclip] Injected Pi skill "${entry.name}" into ${piSkillsHome}\n`,
+        `[paperclip] ${result === "repaired" ? "Repaired" : "Injected"} Pi skill "${entry.name}" into ${piSkillsHome}\n`,
       );
     } catch (err) {
       await onLog(

From 29a743cb9e3601a7896c89875609df3a6968fe8b Mon Sep 17 00:00:00 2001
From: Dotta <bippadotta@protonmail.com>
Date: Thu, 12 Mar 2026 15:57:37 -0500
Subject: [PATCH 04/28] fix: keep runtime skills scoped to ./skills

Co-Authored-By: Paperclip <noreply@paperclip.ing>
---
 cli/src/commands/client/agent.ts              |  31 +++---
 packages/adapter-utils/src/server-utils.ts    | 102 +++++++++++++-----
 .../codex-local/src/server/execute.ts         |  11 ++
 .../cursor-local/src/server/execute.ts        |  11 ++
 .../gemini-local/src/server/execute.ts        |  11 ++
 .../adapters/pi-local/src/server/execute.ts   |  11 ++
 .../__tests__/paperclip-skill-utils.test.ts   |  61 +++++++++++
 7 files changed, 195 insertions(+), 43 deletions(-)
 create mode 100644 server/src/__tests__/paperclip-skill-utils.test.ts

diff --git a/cli/src/commands/client/agent.ts b/cli/src/commands/client/agent.ts
index a6e86277..2c294628 100644
--- a/cli/src/commands/client/agent.ts
+++ b/cli/src/commands/client/agent.ts
@@ -1,5 +1,9 @@
 import { Command } from "commander";
 import type { Agent } from "@paperclipai/shared";
+import {
+  removeMaintainerOnlySkillSymlinks,
+  resolvePaperclipSkillsDir,
+} from "@paperclipai/adapter-utils/server-utils";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -34,17 +38,12 @@ interface SkillsInstallSummary {
   tool: "codex" | "claude";
   target: string;
   linked: string[];
+  removed: string[];
   skipped: string[];
   failed: Array<{ name: string; error: string }>;
 }
 
 const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
-const PAPERCLIP_SKILLS_CANDIDATES = [
-  path.resolve(__moduleDir, "../../../../../.agents/skills"), // dev: cli/src/commands/client -> repo root/.agents/skills
-  path.resolve(__moduleDir, "../../../../../skills"), // dev: cli/src/commands/client -> repo root/skills
-  path.resolve(process.cwd(), ".agents/skills"),
-  path.resolve(process.cwd(), "skills"),
-];
 
 function codexSkillsHome(): string {
   const fromEnv = process.env.CODEX_HOME?.trim();
@@ -58,14 +57,6 @@ function claudeSkillsHome(): string {
   return path.join(base, "skills");
 }
 
-async function resolvePaperclipSkillsDir(): Promise<string | null> {
-  for (const candidate of PAPERCLIP_SKILLS_CANDIDATES) {
-    const isDir = await fs.stat(candidate).then((s) => s.isDirectory()).catch(() => false);
-    if (isDir) return candidate;
-  }
-  return null;
-}
-
 async function installSkillsForTarget(
   sourceSkillsDir: string,
   targetSkillsDir: string,
@@ -75,12 +66,17 @@ async function installSkillsForTarget(
     tool,
     target: targetSkillsDir,
     linked: [],
+    removed: [],
     skipped: [],
     failed: [],
   };
 
   await fs.mkdir(targetSkillsDir, { recursive: true });
   const entries = await fs.readdir(sourceSkillsDir, { withFileTypes: true });
+  summary.removed = await removeMaintainerOnlySkillSymlinks(
+    targetSkillsDir,
+    entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name),
+  );
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
     const source = path.join(sourceSkillsDir, entry.name);
@@ -140,7 +136,6 @@ async function installSkillsForTarget(
         error: err instanceof Error ? err.message : String(err),
       });
     }
-    }
   }
 
   return summary;
@@ -253,10 +248,10 @@ export function registerAgentCommands(program: Command): void {
 
           const installSummaries: SkillsInstallSummary[] = [];
           if (opts.installSkills !== false) {
-            const skillsDir = await resolvePaperclipSkillsDir();
+            const skillsDir = await resolvePaperclipSkillsDir(__moduleDir, [path.resolve(process.cwd(), "skills")]);
             if (!skillsDir) {
               throw new Error(
-                "Could not locate local Paperclip skills directory. Expected ./skills or ./.agents/skills in the repo checkout.",
+                "Could not locate local Paperclip skills directory. Expected ./skills in the repo checkout.",
               );
             }
 
@@ -301,7 +296,7 @@ export function registerAgentCommands(program: Command): void {
           if (installSummaries.length > 0) {
             for (const summary of installSummaries) {
               console.log(
-                `${summary.tool}: linked=${summary.linked.length} skipped=${summary.skipped.length} failed=${summary.failed.length} target=${summary.target}`,
+                `${summary.tool}: linked=${summary.linked.length} removed=${summary.removed.length} skipped=${summary.skipped.length} failed=${summary.failed.length} target=${summary.target}`,
               );
               for (const failed of summary.failed) {
                 console.log(`  failed ${failed.name}: ${failed.error}`);
diff --git a/packages/adapter-utils/src/server-utils.ts b/packages/adapter-utils/src/server-utils.ts
index 15f0ada8..30f0c9bd 100644
--- a/packages/adapter-utils/src/server-utils.ts
+++ b/packages/adapter-utils/src/server-utils.ts
@@ -33,9 +33,7 @@ export const MAX_CAPTURE_BYTES = 4 * 1024 * 1024;
 export const MAX_EXCERPT_BYTES = 32 * 1024;
 const SENSITIVE_ENV_KEY = /(key|token|secret|password|passwd|authorization|cookie)/i;
 const PAPERCLIP_SKILL_ROOT_RELATIVE_CANDIDATES = [
-  "../../.agents/skills",
   "../../skills",
-  "../../../../../.agents/skills",
   "../../../../../skills",
 ];
 
@@ -44,6 +42,14 @@ export interface PaperclipSkillEntry {
   source: string;
 }
 
+function normalizePathSlashes(value: string): string {
+  return value.replaceAll("\\", "/");
+}
+
+function isMaintainerOnlySkillTarget(candidate: string): boolean {
+  return normalizePathSlashes(candidate).includes("/.agents/skills/");
+}
+
 export function parseObject(value: unknown): Record<string, unknown> {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
     return {};
@@ -256,36 +262,44 @@ export async function ensureAbsoluteDirectory(
   }
 }
 
-export async function listPaperclipSkillEntries(moduleDir: string): Promise<PaperclipSkillEntry[]> {
-  const entriesByName = new Map<string, PaperclipSkillEntry>();
+export async function resolvePaperclipSkillsDir(
+  moduleDir: string,
+  additionalCandidates: string[] = [],
+): Promise<string | null> {
+  const candidates = [
+    ...PAPERCLIP_SKILL_ROOT_RELATIVE_CANDIDATES.map((relativePath) => path.resolve(moduleDir, relativePath)),
+    ...additionalCandidates.map((candidate) => path.resolve(candidate)),
+  ];
   const seenRoots = new Set<string>();
 
-  for (const relativePath of PAPERCLIP_SKILL_ROOT_RELATIVE_CANDIDATES) {
-    const root = path.resolve(moduleDir, relativePath);
+  for (const root of candidates) {
     if (seenRoots.has(root)) continue;
     seenRoots.add(root);
-
     const isDirectory = await fs.stat(root).then((stats) => stats.isDirectory()).catch(() => false);
-    if (!isDirectory) continue;
-
-    let entries: Awaited<ReturnType<typeof fs.readdir>>;
-    try {
-      entries = await fs.readdir(root, { withFileTypes: true });
-    } catch {
-      continue;
-    }
-
-    for (const entry of entries) {
-      if (!entry.isDirectory()) continue;
-      if (entriesByName.has(entry.name)) continue;
-      entriesByName.set(entry.name, {
-        name: entry.name,
-        source: path.join(root, entry.name),
-      });
-    }
+    if (isDirectory) return root;
   }
 
-  return Array.from(entriesByName.values());
+  return null;
+}
+
+export async function listPaperclipSkillEntries(
+  moduleDir: string,
+  additionalCandidates: string[] = [],
+): Promise<PaperclipSkillEntry[]> {
+  const root = await resolvePaperclipSkillsDir(moduleDir, additionalCandidates);
+  if (!root) return [];
+
+  try {
+    const entries = await fs.readdir(root, { withFileTypes: true });
+    return entries
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => ({
+        name: entry.name,
+        source: path.join(root, entry.name),
+      }));
+  } catch {
+    return [];
+  }
 }
 
 export async function readPaperclipSkillMarkdown(
@@ -340,6 +354,44 @@ export async function ensurePaperclipSkillSymlink(
   return "repaired";
 }
 
+export async function removeMaintainerOnlySkillSymlinks(
+  skillsHome: string,
+  allowedSkillNames: Iterable<string>,
+): Promise<string[]> {
+  const allowed = new Set(Array.from(allowedSkillNames));
+  try {
+    const entries = await fs.readdir(skillsHome, { withFileTypes: true });
+    const removed: string[] = [];
+    for (const entry of entries) {
+      if (allowed.has(entry.name)) continue;
+
+      const target = path.join(skillsHome, entry.name);
+      const existing = await fs.lstat(target).catch(() => null);
+      if (!existing?.isSymbolicLink()) continue;
+
+      const linkedPath = await fs.readlink(target).catch(() => null);
+      if (!linkedPath) continue;
+
+      const resolvedLinkedPath = path.isAbsolute(linkedPath)
+        ? linkedPath
+        : path.resolve(path.dirname(target), linkedPath);
+      if (
+        !isMaintainerOnlySkillTarget(linkedPath) &&
+        !isMaintainerOnlySkillTarget(resolvedLinkedPath)
+      ) {
+        continue;
+      }
+
+      await fs.unlink(target);
+      removed.push(entry.name);
+    }
+
+    return removed;
+  } catch {
+    return [];
+  }
+}
+
 export async function ensureCommandResolvable(command: string, cwd: string, env: NodeJS.ProcessEnv) {
   const resolved = await resolveCommandPath(command, cwd, env);
   if (resolved) return;
diff --git a/packages/adapters/codex-local/src/server/execute.ts b/packages/adapters/codex-local/src/server/execute.ts
index 3afbf09e..c51dc8a1 100644
--- a/packages/adapters/codex-local/src/server/execute.ts
+++ b/packages/adapters/codex-local/src/server/execute.ts
@@ -16,6 +16,7 @@ import {
   ensurePaperclipSkillSymlink,
   ensurePathInEnv,
   listPaperclipSkillEntries,
+  removeMaintainerOnlySkillSymlinks,
   renderTemplate,
   runChildProcess,
 } from "@paperclipai/adapter-utils/server-utils";
@@ -80,6 +81,16 @@ export async function ensureCodexSkillsInjected(
 
   const skillsHome = options.skillsHome ?? path.join(codexHomeDir(), "skills");
   await fs.mkdir(skillsHome, { recursive: true });
+  const removedSkills = await removeMaintainerOnlySkillSymlinks(
+    skillsHome,
+    skillsEntries.map((entry) => entry.name),
+  );
+  for (const skillName of removedSkills) {
+    await onLog(
+      "stderr",
+      `[paperclip] Removed maintainer-only Codex skill "${skillName}" from ${skillsHome}\n`,
+    );
+  }
   const linkSkill = options.linkSkill;
   for (const entry of skillsEntries) {
     const target = path.join(skillsHome, entry.name);
diff --git a/packages/adapters/cursor-local/src/server/execute.ts b/packages/adapters/cursor-local/src/server/execute.ts
index ae068c1c..043c3ef1 100644
--- a/packages/adapters/cursor-local/src/server/execute.ts
+++ b/packages/adapters/cursor-local/src/server/execute.ts
@@ -15,6 +15,7 @@ import {
   ensurePaperclipSkillSymlink,
   ensurePathInEnv,
   listPaperclipSkillEntries,
+  removeMaintainerOnlySkillSymlinks,
   renderTemplate,
   runChildProcess,
 } from "@paperclipai/adapter-utils/server-utils";
@@ -108,6 +109,16 @@ export async function ensureCursorSkillsInjected(
     );
     return;
   }
+  const removedSkills = await removeMaintainerOnlySkillSymlinks(
+    skillsHome,
+    skillsEntries.map((entry) => entry.name),
+  );
+  for (const skillName of removedSkills) {
+    await onLog(
+      "stderr",
+      `[paperclip] Removed maintainer-only Cursor skill "${skillName}" from ${skillsHome}\n`,
+    );
+  }
   const linkSkill = options.linkSkill ?? ((source: string, target: string) => fs.symlink(source, target));
   for (const entry of skillsEntries) {
     const target = path.join(skillsHome, entry.name);
diff --git a/packages/adapters/gemini-local/src/server/execute.ts b/packages/adapters/gemini-local/src/server/execute.ts
index fa27bffa..2408b425 100644
--- a/packages/adapters/gemini-local/src/server/execute.ts
+++ b/packages/adapters/gemini-local/src/server/execute.ts
@@ -15,6 +15,7 @@ import {
   ensurePaperclipSkillSymlink,
   ensurePathInEnv,
   listPaperclipSkillEntries,
+  removeMaintainerOnlySkillSymlinks,
   parseObject,
   redactEnvForLogs,
   renderTemplate,
@@ -96,6 +97,16 @@ async function ensureGeminiSkillsInjected(
     );
     return;
   }
+  const removedSkills = await removeMaintainerOnlySkillSymlinks(
+    skillsHome,
+    skillsEntries.map((entry) => entry.name),
+  );
+  for (const skillName of removedSkills) {
+    await onLog(
+      "stderr",
+      `[paperclip] Removed maintainer-only Gemini skill "${skillName}" from ${skillsHome}\n`,
+    );
+  }
 
   for (const entry of skillsEntries) {
     const target = path.join(skillsHome, entry.name);
diff --git a/packages/adapters/pi-local/src/server/execute.ts b/packages/adapters/pi-local/src/server/execute.ts
index 6fabe32d..dfb1453b 100644
--- a/packages/adapters/pi-local/src/server/execute.ts
+++ b/packages/adapters/pi-local/src/server/execute.ts
@@ -15,6 +15,7 @@ import {
   ensurePaperclipSkillSymlink,
   ensurePathInEnv,
   listPaperclipSkillEntries,
+  removeMaintainerOnlySkillSymlinks,
   renderTemplate,
   runChildProcess,
 } from "@paperclipai/adapter-utils/server-utils";
@@ -54,6 +55,16 @@ async function ensurePiSkillsInjected(onLog: AdapterExecutionContext["onLog"]) {
 
   const piSkillsHome = path.join(os.homedir(), ".pi", "agent", "skills");
   await fs.mkdir(piSkillsHome, { recursive: true });
+  const removedSkills = await removeMaintainerOnlySkillSymlinks(
+    piSkillsHome,
+    skillsEntries.map((entry) => entry.name),
+  );
+  for (const skillName of removedSkills) {
+    await onLog(
+      "stderr",
+      `[paperclip] Removed maintainer-only Pi skill "${skillName}" from ${piSkillsHome}\n`,
+    );
+  }
 
   for (const entry of skillsEntries) {
     const target = path.join(piSkillsHome, entry.name);
diff --git a/server/src/__tests__/paperclip-skill-utils.test.ts b/server/src/__tests__/paperclip-skill-utils.test.ts
new file mode 100644
index 00000000..4344dc17
--- /dev/null
+++ b/server/src/__tests__/paperclip-skill-utils.test.ts
@@ -0,0 +1,61 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  listPaperclipSkillEntries,
+  removeMaintainerOnlySkillSymlinks,
+} from "@paperclipai/adapter-utils/server-utils";
+
+async function makeTempDir(prefix: string): Promise<string> {
+  return fs.mkdtemp(path.join(os.tmpdir(), prefix));
+}
+
+describe("paperclip skill utils", () => {
+  const cleanupDirs = new Set<string>();
+
+  afterEach(async () => {
+    await Promise.all(Array.from(cleanupDirs).map((dir) => fs.rm(dir, { recursive: true, force: true })));
+    cleanupDirs.clear();
+  });
+
+  it("lists runtime skills from ./skills without pulling in .agents/skills", async () => {
+    const root = await makeTempDir("paperclip-skill-roots-");
+    cleanupDirs.add(root);
+
+    const moduleDir = path.join(root, "a", "b", "c", "d", "e");
+    await fs.mkdir(moduleDir, { recursive: true });
+    await fs.mkdir(path.join(root, "skills", "paperclip"), { recursive: true });
+    await fs.mkdir(path.join(root, ".agents", "skills", "release"), { recursive: true });
+
+    const entries = await listPaperclipSkillEntries(moduleDir);
+
+    expect(entries.map((entry) => entry.name)).toEqual(["paperclip"]);
+    expect(entries[0]?.source).toBe(path.join(root, "skills", "paperclip"));
+  });
+
+  it("removes stale maintainer-only symlinks from a shared skills home", async () => {
+    const root = await makeTempDir("paperclip-skill-cleanup-");
+    cleanupDirs.add(root);
+
+    const skillsHome = path.join(root, "skills-home");
+    const runtimeSkill = path.join(root, "skills", "paperclip");
+    const customSkill = path.join(root, "custom", "release-notes");
+    const staleMaintainerSkill = path.join(root, ".agents", "skills", "release");
+
+    await fs.mkdir(skillsHome, { recursive: true });
+    await fs.mkdir(runtimeSkill, { recursive: true });
+    await fs.mkdir(customSkill, { recursive: true });
+
+    await fs.symlink(runtimeSkill, path.join(skillsHome, "paperclip"));
+    await fs.symlink(customSkill, path.join(skillsHome, "release-notes"));
+    await fs.symlink(staleMaintainerSkill, path.join(skillsHome, "release"));
+
+    const removed = await removeMaintainerOnlySkillSymlinks(skillsHome, ["paperclip"]);
+
+    expect(removed).toEqual(["release"]);
+    await expect(fs.lstat(path.join(skillsHome, "release"))).rejects.toThrow();
+    expect((await fs.lstat(path.join(skillsHome, "paperclip"))).isSymbolicLink()).toBe(true);
+    expect((await fs.lstat(path.join(skillsHome, "release-notes"))).isSymbolicLink()).toBe(true);
+  });
+});

From 9c7d9ded1e79d866f927ea5274bdd148703e4daf Mon Sep 17 00:00:00 2001
From: Dotta <bippadotta@protonmail.com>
Date: Fri, 13 Mar 2026 08:43:44 -0500
Subject: [PATCH 05/28] docs: organize plans into doc/plans with date prefixes

Move plans from doc/plan/ into doc/plans/ and add YYYY-MM-DD date
prefixes to all undated plan files based on document headers or
earliest git commit dates.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 doc/plans/{module-system.md => 2026-02-16-module-system.md}       | 0
 ...ation.md => 2026-02-18-agent-authentication-implementation.md} | 0
 ...agent-authentication.md => 2026-02-18-agent-authentication.md} | 0
 ...mt-followup-plan.md => 2026-02-19-agent-mgmt-followup-plan.md} | 0
 ...-and-hiring.md => 2026-02-19-ceo-agent-creation-and-hiring.md} | 0
 ...tration-plan.md => 2026-02-20-issue-run-orchestration-plan.md} | 0
 ...lementation.md => 2026-02-20-storage-system-implementation.md} | 0
 .../2026-02-21-humans-and-permissions-implementation.md}          | 0
 .../2026-02-21-humans-and-permissions.md}                         | 0
 ...cursor-cloud-adapter.md => 2026-02-23-cursor-cloud-adapter.md} | 0
 ...dation.md => 2026-02-23-deployment-auth-mode-consolidation.md} | 0
 ...rees.md => 2026-03-10-workspace-strategy-and-git-worktrees.md} | 0
 ...=> 2026-03-11-agent-chat-ui-and-issue-backed-conversations.md} | 0
 13 files changed, 0 insertions(+), 0 deletions(-)
 rename doc/plans/{module-system.md => 2026-02-16-module-system.md} (100%)
 rename doc/plans/{agent-authentication-implementation.md => 2026-02-18-agent-authentication-implementation.md} (100%)
 rename doc/plans/{agent-authentication.md => 2026-02-18-agent-authentication.md} (100%)
 rename doc/plans/{agent-mgmt-followup-plan.md => 2026-02-19-agent-mgmt-followup-plan.md} (100%)
 rename doc/plans/{ceo-agent-creation-and-hiring.md => 2026-02-19-ceo-agent-creation-and-hiring.md} (100%)
 rename doc/plans/{issue-run-orchestration-plan.md => 2026-02-20-issue-run-orchestration-plan.md} (100%)
 rename doc/plans/{storage-system-implementation.md => 2026-02-20-storage-system-implementation.md} (100%)
 rename doc/{plan/humans-and-permissions-implementation.md => plans/2026-02-21-humans-and-permissions-implementation.md} (100%)
 rename doc/{plan/humans-and-permissions.md => plans/2026-02-21-humans-and-permissions.md} (100%)
 rename doc/plans/{cursor-cloud-adapter.md => 2026-02-23-cursor-cloud-adapter.md} (100%)
 rename doc/plans/{deployment-auth-mode-consolidation.md => 2026-02-23-deployment-auth-mode-consolidation.md} (100%)
 rename doc/plans/{workspace-strategy-and-git-worktrees.md => 2026-03-10-workspace-strategy-and-git-worktrees.md} (100%)
 rename doc/plans/{agent-chat-ui-and-issue-backed-conversations.md => 2026-03-11-agent-chat-ui-and-issue-backed-conversations.md} (100%)

diff --git a/doc/plans/module-system.md b/doc/plans/2026-02-16-module-system.md
similarity index 100%
rename from doc/plans/module-system.md
rename to doc/plans/2026-02-16-module-system.md
diff --git a/doc/plans/agent-authentication-implementation.md b/doc/plans/2026-02-18-agent-authentication-implementation.md
similarity index 100%
rename from doc/plans/agent-authentication-implementation.md
rename to doc/plans/2026-02-18-agent-authentication-implementation.md
diff --git a/doc/plans/agent-authentication.md b/doc/plans/2026-02-18-agent-authentication.md
similarity index 100%
rename from doc/plans/agent-authentication.md
rename to doc/plans/2026-02-18-agent-authentication.md
diff --git a/doc/plans/agent-mgmt-followup-plan.md b/doc/plans/2026-02-19-agent-mgmt-followup-plan.md
similarity index 100%
rename from doc/plans/agent-mgmt-followup-plan.md
rename to doc/plans/2026-02-19-agent-mgmt-followup-plan.md
diff --git a/doc/plans/ceo-agent-creation-and-hiring.md b/doc/plans/2026-02-19-ceo-agent-creation-and-hiring.md
similarity index 100%
rename from doc/plans/ceo-agent-creation-and-hiring.md
rename to doc/plans/2026-02-19-ceo-agent-creation-and-hiring.md
diff --git a/doc/plans/issue-run-orchestration-plan.md b/doc/plans/2026-02-20-issue-run-orchestration-plan.md
similarity index 100%
rename from doc/plans/issue-run-orchestration-plan.md
rename to doc/plans/2026-02-20-issue-run-orchestration-plan.md
diff --git a/doc/plans/storage-system-implementation.md b/doc/plans/2026-02-20-storage-system-implementation.md
similarity index 100%
rename from doc/plans/storage-system-implementation.md
rename to doc/plans/2026-02-20-storage-system-implementation.md
diff --git a/doc/plan/humans-and-permissions-implementation.md b/doc/plans/2026-02-21-humans-and-permissions-implementation.md
similarity index 100%
rename from doc/plan/humans-and-permissions-implementation.md
rename to doc/plans/2026-02-21-humans-and-permissions-implementation.md
diff --git a/doc/plan/humans-and-permissions.md b/doc/plans/2026-02-21-humans-and-permissions.md
similarity index 100%
rename from doc/plan/humans-and-permissions.md
rename to doc/plans/2026-02-21-humans-and-permissions.md
diff --git a/doc/plans/cursor-cloud-adapter.md b/doc/plans/2026-02-23-cursor-cloud-adapter.md
similarity index 100%
rename from doc/plans/cursor-cloud-adapter.md
rename to doc/plans/2026-02-23-cursor-cloud-adapter.md
diff --git a/doc/plans/deployment-auth-mode-consolidation.md b/doc/plans/2026-02-23-deployment-auth-mode-consolidation.md
similarity index 100%
rename from doc/plans/deployment-auth-mode-consolidation.md
rename to doc/plans/2026-02-23-deployment-auth-mode-consolidation.md
diff --git a/doc/plans/workspace-strategy-and-git-worktrees.md b/doc/plans/2026-03-10-workspace-strategy-and-git-worktrees.md
similarity index 100%
rename from doc/plans/workspace-strategy-and-git-worktrees.md
rename to doc/plans/2026-03-10-workspace-strategy-and-git-worktrees.md
diff --git a/doc/plans/agent-chat-ui-and-issue-backed-conversations.md b/doc/plans/2026-03-11-agent-chat-ui-and-issue-backed-conversations.md
similarity index 100%
rename from doc/plans/agent-chat-ui-and-issue-backed-conversations.md
rename to doc/plans/2026-03-11-agent-chat-ui-and-issue-backed-conversations.md

From 84fc6d4a87f262c7c1bc4e1f3bf8c5baa13c202b Mon Sep 17 00:00:00 2001
From: Dotta <bippadotta@protonmail.com>
Date: Fri, 13 Mar 2026 08:04:57 -0500
Subject: [PATCH 06/28] docs: add token optimization plan

Co-Authored-By: Paperclip <noreply@paperclip.ing>
---
 .../2026-03-13-TOKEN-OPTIMIZATION-PLAN.md     | 383 ++++++++++++++++++
 1 file changed, 383 insertions(+)
 create mode 100644 doc/plans/2026-03-13-TOKEN-OPTIMIZATION-PLAN.md

diff --git a/doc/plans/2026-03-13-TOKEN-OPTIMIZATION-PLAN.md b/doc/plans/2026-03-13-TOKEN-OPTIMIZATION-PLAN.md
new file mode 100644
index 00000000..678444ac
--- /dev/null
+++ b/doc/plans/2026-03-13-TOKEN-OPTIMIZATION-PLAN.md
@@ -0,0 +1,383 @@
+# Token Optimization Plan
+
+Date: 2026-03-13  
+Related discussion: https://github.com/paperclipai/paperclip/discussions/449
+
+## Goal
+
+Reduce token consumption materially without reducing agent capability, control-plane visibility, or task completion quality.
+
+This plan is based on:
+
+- the current V1 control-plane design
+- the current adapter and heartbeat implementation
+- the linked user discussion
+- local runtime data from the default Paperclip instance on 2026-03-13
+
+## Executive Summary
+
+The discussion is directionally right about two things:
+
+1. We should preserve session and prompt-cache locality more aggressively.
+2. We should separate stable startup instructions from per-heartbeat dynamic context.
+
+But that is not enough on its own.
+
+After reviewing the code and local run data, the token problem appears to have four distinct causes:
+
+1. **Measurement inflation on sessioned adapters.** Some token counters, especially for `codex_local`, appear to be recorded as cumulative session totals instead of per-heartbeat deltas.
+2. **Avoidable session resets.** Task sessions are intentionally reset on timer wakes and manual wakes, which destroys cache locality for common heartbeat paths.
+3. **Repeated context reacquisition.** The `paperclip` skill tells agents to re-fetch assignments, issue details, ancestors, and full comment threads on every heartbeat. The API does not currently offer efficient delta-oriented alternatives.
+4. **Large static instruction surfaces.** Agent instruction files and globally injected skills are reintroduced at startup even when most of that content is unchanged and not needed for the current task.
+
+The correct approach is:
+
+1. fix telemetry so we can trust the numbers
+2. preserve reuse where it is safe
+3. make context retrieval incremental
+4. add session compaction/rotation so long-lived sessions do not become progressively more expensive
+
+## Validated Findings
+
+### 1. Token telemetry is at least partly overstated today
+
+Observed from the local default instance:
+
+- `heartbeat_runs`: 11,360 runs between 2026-02-18 and 2026-03-13
+- summed `usage_json.inputTokens`: `2,272,142,368,952`
+- summed `usage_json.cachedInputTokens`: `2,217,501,559,420`
+
+Those totals are not credible as true per-heartbeat usage for the observed prompt sizes.
+
+Supporting evidence:
+
+- `adapter.invoke.payload.prompt` averages were small:
+  - `codex_local`: ~193 chars average, 6,067 chars max
+  - `claude_local`: ~160 chars average, 1,160 chars max
+- despite that, many `codex_local` runs report millions of input tokens
+- one reused Codex session in local data spans 3,607 runs and recorded `inputTokens` growing up to `1,155,283,166`
+
+Interpretation:
+
+- for sessioned adapters, especially Codex, we are likely storing usage reported by the runtime as a **session total**, not a **per-run delta**
+- this makes trend reporting, optimization work, and customer trust worse
+
+This does **not** mean there is no real token problem. It means we need a trustworthy baseline before we can judge optimization impact.
+
+### 2. Timer wakes currently throw away reusable task sessions
+
+In `server/src/services/heartbeat.ts`, `shouldResetTaskSessionForWake(...)` returns `true` for:
+
+- `wakeReason === "issue_assigned"`
+- `wakeSource === "timer"`
+- manual on-demand wakes
+
+That means many normal heartbeats skip saved task-session resume even when the workspace is stable.
+
+Local data supports the impact:
+
+- `timer/system` runs: 6,587 total
+- only 976 had a previous session
+- only 963 ended with the same session
+
+So timer wakes are the largest heartbeat path and are mostly not resuming prior task state.
+
+### 3. We repeatedly ask agents to reload the same task context
+
+The `paperclip` skill currently tells agents to do this on essentially every heartbeat:
+
+- fetch assignments
+- fetch issue details
+- fetch ancestor chain
+- fetch full issue comments
+
+Current API shape reinforces that pattern:
+
+- `GET /api/issues/:id/comments` returns the full thread
+- there is no `since`, cursor, digest, or summary endpoint for heartbeat consumption
+- `GET /api/issues/:id` returns full enriched issue context, not a minimal delta payload
+
+This is safe but expensive. It forces the model to repeatedly consume unchanged information.
+
+### 4. Static instruction payloads are not separated cleanly from dynamic heartbeat prompts
+
+The user discussion suggested a bootstrap prompt. That is the right direction.
+
+Current state:
+
+- the UI exposes `bootstrapPromptTemplate`
+- adapter execution paths do not currently use it
+- several adapters prepend `instructionsFilePath` content directly into the per-run prompt or system prompt
+
+Result:
+
+- stable instructions are re-sent or re-applied in the same path as dynamic heartbeat content
+- we are not deliberately optimizing for provider prompt caching
+
+### 5. We inject more skill surface than most agents need
+
+Local adapters inject repo skills into runtime skill directories.
+
+Current repo skill sizes:
+
+- `skills/paperclip/SKILL.md`: 17,441 bytes
+- `skills/create-agent-adapter/SKILL.md`: 31,832 bytes
+- `skills/paperclip-create-agent/SKILL.md`: 4,718 bytes
+- `skills/para-memory-files/SKILL.md`: 3,978 bytes
+
+That is nearly 58 KB of skill markdown before any company-specific instructions.
+
+Not all of that is necessarily loaded into model context every run, but it increases startup surface area and should be treated as a token budget concern.
+
+## Principles
+
+We should optimize tokens under these rules:
+
+1. **Do not lose functionality.** Agents must still be able to resume work safely, understand why tasks exist, and act within governance rules.
+2. **Prefer stable context over repeated context.** Unchanged instructions should not be resent through the most expensive path.
+3. **Prefer deltas over full reloads.** Heartbeats should consume only what changed since the last useful run.
+4. **Measure normalized deltas, not raw adapter claims.** Especially for sessioned CLIs.
+5. **Keep escape hatches.** Board/manual runs may still want a forced fresh session.
+
+## Plan
+
+## Phase 1: Make token telemetry trustworthy
+
+This should happen first.
+
+### Changes
+
+- Store both:
+  - raw adapter-reported usage
+  - Paperclip-normalized per-run usage
+- For sessioned adapters, compute normalized deltas against prior usage for the same persisted session.
+- Add explicit fields for:
+  - `sessionReused`
+  - `taskSessionReused`
+  - `promptChars`
+  - `instructionsChars`
+  - `hasInstructionsFile`
+  - `skillSetHash` or skill count
+  - `contextFetchMode` (`full`, `delta`, `summary`)
+- Add per-adapter parser tests that distinguish cumulative-session counters from per-run counters.
+
+### Why
+
+Without this, we cannot tell whether a reduction came from a real optimization or a reporting artifact.
+
+### Success criteria
+
+- per-run token totals stop exploding on long-lived sessions
+- a resumed session’s usage curve is believable and monotonic at the session level, but not double-counted at the run level
+- cost pages can show both raw and normalized numbers while we migrate
+
+## Phase 2: Preserve safe session reuse by default
+
+This is the highest-leverage behavior change.
+
+### Changes
+
+- Stop resetting task sessions on ordinary timer wakes.
+- Keep resetting on:
+  - explicit manual “fresh run” invocations
+  - assignment changes
+  - workspace mismatch
+  - model mismatch / invalid resume errors
+- Add an explicit wake flag like `forceFreshSession: true` when the board wants a reset.
+- Record why a session was reused or reset in run metadata.
+
+### Why
+
+Timer wakes are the dominant heartbeat path. Resetting them destroys both session continuity and prompt cache reuse.
+
+### Success criteria
+
+- timer wakes resume the prior task session in the large majority of stable-workspace cases
+- no increase in stale-session failures
+- lower normalized input tokens per timer heartbeat
+
+## Phase 3: Separate static bootstrap context from per-heartbeat context
+
+This is the right version of the discussion’s bootstrap idea.
+
+### Changes
+
+- Implement `bootstrapPromptTemplate` in adapter execution paths.
+- Use it only when starting a fresh session, not on resumed sessions.
+- Keep `promptTemplate` intentionally small and stable:
+  - who I am
+  - what triggered this wake
+  - which task/comment/approval to prioritize
+- Move long-lived setup text out of recurring per-run prompts where possible.
+- Add UI guidance and warnings when `promptTemplate` contains high-churn or large inline content.
+
+### Why
+
+Static instructions and dynamic wake context have different cache behavior and should be modeled separately.
+
+### Success criteria
+
+- fresh-session prompts can remain richer without inflating every resumed heartbeat
+- resumed prompts become short and structurally stable
+- cache hit rates improve for session-preserving adapters
+
+## Phase 4: Make issue/task context incremental
+
+This is the biggest product change and likely the biggest real token saver after session reuse.
+
+### Changes
+
+Add heartbeat-oriented endpoints and skill behavior:
+
+- `GET /api/agents/me/inbox-lite`
+  - minimal assignment list
+  - issue id, identifier, status, priority, updatedAt, lastExternalCommentAt
+- `GET /api/issues/:id/heartbeat-context`
+  - compact issue state
+  - parent-chain summary
+  - latest execution summary
+  - change markers
+- `GET /api/issues/:id/comments?after=<cursor>` or `?since=<timestamp>`
+  - return only new comments
+- optional `GET /api/issues/:id/context-digest`
+  - server-generated compact summary for heartbeat use
+
+Update the `paperclip` skill so the default pattern becomes:
+
+1. fetch compact inbox
+2. fetch compact task context
+3. fetch only new comments unless this is the first read, a mention-triggered wake, or a cache miss
+4. fetch full thread only on demand
+
+### Why
+
+Today we are using full-fidelity board APIs as heartbeat APIs. That is convenient but token-inefficient.
+
+### Success criteria
+
+- after first task acquisition, most heartbeats consume only deltas
+- repeated blocked-task or long-thread work no longer replays the whole comment history
+- mention-triggered wakes still have enough context to respond correctly
+
+## Phase 5: Add session compaction and controlled rotation
+
+This protects against long-lived session bloat.
+
+### Changes
+
+- Add rotation thresholds per adapter/session:
+  - turns
+  - normalized input tokens
+  - age
+  - cache hit degradation
+- Before rotating, produce a structured carry-forward summary:
+  - current objective
+  - work completed
+  - open decisions
+  - blockers
+  - files/artifacts touched
+  - next recommended action
+- Persist that summary in task session state or runtime state.
+- Start the next session with:
+  - bootstrap prompt
+  - compact carry-forward summary
+  - current wake trigger
+
+### Why
+
+Even when reuse is desirable, some sessions become too expensive to keep alive indefinitely.
+
+### Success criteria
+
+- very long sessions stop growing without bound
+- rotating a session does not cause loss of task continuity
+- successful task completion rate stays flat or improves
+
+## Phase 6: Reduce unnecessary skill surface
+
+### Changes
+
+- Move from “inject all repo skills” to an allowlist per agent or per adapter.
+- Default local runtime skill set should likely be:
+  - `paperclip`
+- Add opt-in skills for specialized agents:
+  - `paperclip-create-agent`
+  - `para-memory-files`
+  - `create-agent-adapter`
+- Expose active skill set in agent config and run metadata.
+
+### Why
+
+Most agents do not need adapter-authoring or memory-system skills on every run.
+
+### Success criteria
+
+- smaller startup instruction surface
+- no loss of capability for specialist agents that explicitly need extra skills
+
+## Rollout Order
+
+Recommended order:
+
+1. telemetry normalization
+2. timer-wake session reuse
+3. bootstrap prompt implementation
+4. heartbeat delta APIs + `paperclip` skill rewrite
+5. session compaction/rotation
+6. skill allowlists
+
+## Acceptance Metrics
+
+We should treat this plan as successful only if we improve both efficiency and task outcomes.
+
+Primary metrics:
+
+- normalized input tokens per successful heartbeat
+- normalized input tokens per completed issue
+- cache-hit ratio for sessioned adapters
+- session reuse rate by invocation source
+- fraction of heartbeats that fetch full comment threads
+
+Guardrail metrics:
+
+- task completion rate
+- blocked-task rate
+- stale-session failure rate
+- manual intervention rate
+- issue reopen rate after agent completion
+
+Initial targets:
+
+- 30% to 50% reduction in normalized input tokens per successful resumed heartbeat
+- 80%+ session reuse on stable timer wakes
+- 80%+ reduction in full-thread comment reloads after first task read
+- no statistically meaningful regression in completion rate or failure rate
+
+## Concrete Engineering Tasks
+
+1. Add normalized usage fields and migration support for run analytics.
+2. Patch sessioned adapter accounting to compute deltas from prior session totals.
+3. Change `shouldResetTaskSessionForWake(...)` so timer wakes do not reset by default.
+4. Implement `bootstrapPromptTemplate` end-to-end in adapter execution.
+5. Add compact heartbeat context and incremental comment APIs.
+6. Rewrite `skills/paperclip/SKILL.md` around delta-fetch behavior.
+7. Add session rotation with carry-forward summaries.
+8. Replace global skill injection with explicit allowlists.
+
+## Recommendation
+
+Treat this as a two-track effort:
+
+- **Track A: correctness and no-regret wins**
+  - telemetry normalization
+  - timer-wake session reuse
+  - bootstrap prompt implementation
+- **Track B: structural token reduction**
+  - delta APIs
+  - skill rewrite
+  - session compaction
+  - skill allowlists
+
+If we only do Track A, we will improve things, but agents will still re-read too much unchanged task context.
+
+If we only do Track B without fixing telemetry first, we will not be able to prove the gains cleanly.

From 216cb3fb28b8ca9e5bd1adde3171860242b19131 Mon Sep 17 00:00:00 2001
From: Dotta <bippadotta@protonmail.com>
Date: Fri, 13 Mar 2026 08:41:01 -0500
Subject: [PATCH 07/28] Add workspace product model plan

---
 ...orkspace-product-model-and-work-product.md | 959 ++++++++++++++++++
 1 file changed, 959 insertions(+)
 create mode 100644 doc/plans/workspace-product-model-and-work-product.md

diff --git a/doc/plans/workspace-product-model-and-work-product.md b/doc/plans/workspace-product-model-and-work-product.md
new file mode 100644
index 00000000..3b201e7d
--- /dev/null
+++ b/doc/plans/workspace-product-model-and-work-product.md
@@ -0,0 +1,959 @@
+# Workspace Product Model, Work Product, and PR Flow
+
+## Context
+
+Paperclip needs to support two very different but equally valid ways of working:
+
+- a solo developer working directly on `master`, or in a folder that is not even a git repo
+- a larger engineering workflow with isolated branches, previews, pull requests, and cleanup automation
+
+Today, Paperclip already has the beginnings of this model:
+
+- `projects` can carry execution workspace policy
+- `project_workspaces` already exist as a durable project-scoped object
+- issues can carry execution workspace settings
+- runtime services can be attached to a workspace or issue
+
+What is missing is a clear product model and UI that make these capabilities understandable and operable.
+
+The main product risk is overloading one concept to do too much:
+
+- making subissues do the job of branches or PRs
+- making projects too infrastructure-heavy
+- making workspaces so hidden that users cannot form a mental model
+- making Paperclip feel like a code review tool instead of a control plane
+
+## Goals
+
+1. Keep `project` lightweight enough to remain a planning container.
+2. Make workspace behavior understandable for both git and non-git projects.
+3. Support three real workflows without forcing one:
+   - shared workspace / direct-edit workflows
+   - isolated issue workspace workflows
+   - long-lived branch or operator integration workflows
+4. Provide a first-class place to see the outputs of work:
+   - previews
+   - PRs
+   - branches
+   - commits
+   - documents and artifacts
+5. Keep the main navigation and task board simple.
+
+## Non-Goals
+
+- Turning Paperclip into a full code review product
+- Requiring every issue to have its own branch or PR
+- Requiring every project to configure code/workspace automation
+- Making workspaces a top-level global navigation primitive in V1
+
+## Core Product Decisions
+
+### 1. Project stays the planning object
+
+A `project` remains the thing that groups work around a deliverable or initiative.
+
+It may have:
+
+- no code at all
+- one default codebase/workspace
+- several codebases/workspaces
+
+Projects are not required to become heavyweight.
+
+### 2. Project workspace is a first-class object, but scoped under project
+
+A `project workspace` is the durable codebase or root environment for a project.
+
+Examples:
+
+- a local folder on disk
+- a git repo checkout
+- a monorepo package root
+- a non-git design/doc folder
+- a remote adapter-managed codebase reference
+
+This is the stable anchor that operators configure once.
+
+It should not be a top-level sidebar item in the main app. It should live under the project experience.
+
+### 3. Execution workspace is a first-class runtime object
+
+An `execution workspace` is where a specific run or issue actually executes.
+
+Examples:
+
+- the shared project workspace itself
+- an isolated git worktree
+- a long-lived operator branch checkout
+- an adapter-managed remote sandbox
+
+This object must be recorded explicitly so that Paperclip can:
+
+- show where work happened
+- attach previews and runtime services
+- link PRs and branches
+- decide cleanup behavior
+- support reuse across multiple related issues
+
+### 4. PRs are work product, not the core issue model
+
+A PR is an output of work, not the planning unit.
+
+Paperclip should treat PRs as a type of work product linked back to:
+
+- the issue
+- the execution workspace
+- optionally the project workspace
+
+Git-specific automation should live under workspace policy, not under the core issue abstraction.
+
+### 5. Subissues remain planning and ownership structure
+
+Subissues are for decomposition and parallel ownership.
+
+They are not the same thing as:
+
+- a branch
+- a worktree
+- a PR
+- a preview
+
+They may correlate with those things, but they should not be overloaded to mean them.
+
+## Terminology
+
+Use these terms consistently in product copy:
+
+- `Project`: planning container
+- `Project workspace`: durable configured codebase/root
+- `Execution workspace`: actual runtime workspace used for issue execution
+- `Isolated issue workspace`: user-facing term for an issue-specific derived workspace
+- `Work product`: previews, PRs, branches, commits, artifacts, docs
+- `Runtime service`: a process or service Paperclip owns or tracks for a workspace
+
+Avoid teaching users that "workspace" always means "git worktree on my machine".
+
+## Product Object Model
+
+## 1. Project
+
+Existing object. No fundamental change in role.
+
+### Required behavior
+
+- can exist without code/workspace configuration
+- can have zero or more project workspaces
+- can define execution defaults that new issues inherit
+
+### Proposed fields
+
+- `id`
+- `companyId`
+- `name`
+- `description`
+- `status`
+- `goalIds`
+- `leadAgentId`
+- `targetDate`
+- `executionWorkspacePolicy`
+- `workspaces[]`
+- `primaryWorkspace`
+
+## 2. Project Workspace
+
+Durable, configured, project-scoped codebase/root object.
+
+This should evolve from the current `project_workspaces` table into a more explicit product object.
+
+### Motivation
+
+This separates:
+
+- "what codebase/root does this project use?"
+
+from:
+
+- "what temporary execution environment did this issue run in?"
+
+That keeps the model simple for solo users while still supporting advanced automation.
+
+### Proposed fields
+
+- `id`
+- `companyId`
+- `projectId`
+- `name`
+- `sourceType`
+  - `local_path`
+  - `git_repo`
+  - `remote_managed`
+  - `non_git_path`
+- `cwd`
+- `repoUrl`
+- `defaultRef`
+- `isPrimary`
+- `visibility`
+  - `default`
+  - `advanced`
+- `setupCommand`
+- `cleanupCommand`
+- `metadata`
+- `createdAt`
+- `updatedAt`
+
+### Notes
+
+- `sourceType=non_git_path` is important so non-git projects are first-class.
+- `setupCommand` and `cleanupCommand` should be allowed here for workspace-root bootstrap, even when isolated execution is not used.
+- For a monorepo, multiple project workspaces may point at different roots or packages under one repo.
+
+## 3. Project Execution Workspace Policy
+
+Project-level defaults for how issues execute.
+
+This is the main operator-facing configuration surface.
+
+### Motivation
+
+This lets Paperclip support:
+
+- direct editing in a shared workspace
+- isolated workspaces for issue parallelism
+- long-lived integration branch workflows
+
+without forcing every issue or agent to expose low-level runtime configuration.
+
+### Proposed fields
+
+- `enabled: boolean`
+- `defaultMode`
+  - `shared_workspace`
+  - `isolated_workspace`
+  - `operator_branch`
+  - `adapter_default`
+- `allowIssueOverride: boolean`
+- `defaultProjectWorkspaceId: uuid | null`
+- `workspaceStrategy`
+  - `type`
+    - `project_primary`
+    - `git_worktree`
+    - `adapter_managed`
+  - `baseRef`
+  - `branchTemplate`
+  - `worktreeParentDir`
+  - `provisionCommand`
+  - `teardownCommand`
+- `branchPolicy`
+  - `namingTemplate`
+  - `allowReuseExisting`
+  - `preferredOperatorBranch`
+- `pullRequestPolicy`
+  - `mode`
+    - `disabled`
+    - `manual`
+    - `agent_may_open_draft`
+    - `approval_required_to_open`
+    - `approval_required_to_mark_ready`
+  - `baseBranch`
+  - `titleTemplate`
+  - `bodyTemplate`
+- `runtimePolicy`
+  - `allowWorkspaceServices`
+  - `defaultServicesProfile`
+  - `autoHarvestOwnedUrls`
+- `cleanupPolicy`
+  - `mode`
+    - `manual`
+    - `when_issue_terminal`
+    - `when_pr_closed`
+    - `retention_window`
+  - `retentionHours`
+  - `keepWhilePreviewHealthy`
+  - `keepWhileOpenPrExists`
+
+## 4. Issue Workspace Binding
+
+Issue-level selection of execution behavior.
+
+This should remain lightweight in the normal case and only surface richer controls when relevant.
+
+### Motivation
+
+Not every issue in a code project should create a new derived workspace.
+
+Examples:
+
+- a tiny fix can run in the shared workspace
+- three related issues may intentionally share one integration branch
+- a solo operator may be working directly on `master`
+
+### Proposed fields on `issues`
+
+- `projectWorkspaceId: uuid | null`
+- `executionWorkspacePreference`
+  - `inherit`
+  - `shared_workspace`
+  - `isolated_workspace`
+  - `operator_branch`
+  - `reuse_existing`
+- `preferredExecutionWorkspaceId: uuid | null`
+- `executionWorkspaceSettings`
+  - keep advanced per-issue override fields here
+
+### Rules
+
+- if the project has no workspace automation, these fields may all be null
+- if the project has one primary workspace, issue creation should default to it silently
+- `reuse_existing` is advanced-only and should target active execution workspaces, not the whole workspace universe
+
+## 5. Execution Workspace
+
+A durable record for a shared or derived runtime workspace.
+
+This is the missing object that makes cleanup, previews, PRs, and branch reuse tractable.
+
+### Motivation
+
+Without an explicit `execution workspace` record, Paperclip has nowhere stable to attach:
+
+- derived branch/worktree identity
+- active preview ownership
+- PR linkage
+- cleanup state
+- "reuse this existing integration branch" behavior
+
+### Proposed new object
+
+`execution_workspaces`
+
+### Proposed fields
+
+- `id`
+- `companyId`
+- `projectId`
+- `projectWorkspaceId`
+- `sourceIssueId`
+- `mode`
+  - `shared_workspace`
+  - `isolated_workspace`
+  - `operator_branch`
+  - `adapter_managed`
+- `strategyType`
+  - `project_primary`
+  - `git_worktree`
+  - `adapter_managed`
+- `name`
+- `status`
+  - `active`
+  - `idle`
+  - `in_review`
+  - `archived`
+  - `cleanup_failed`
+- `cwd`
+- `repoUrl`
+- `baseRef`
+- `branchName`
+- `providerRef`
+- `derivedFromExecutionWorkspaceId`
+- `lastUsedAt`
+- `openedAt`
+- `closedAt`
+- `cleanupEligibleAt`
+- `cleanupReason`
+- `metadata`
+- `createdAt`
+- `updatedAt`
+
+### Notes
+
+- `sourceIssueId` is the issue that originally caused the workspace to be created, not necessarily the only issue linked to it later.
+- multiple issues may link to the same execution workspace in a long-lived branch workflow.
+
+## 6. Issue-to-Execution Workspace Link
+
+An issue may need to link to one or more execution workspaces over time.
+
+Examples:
+
+- an issue begins in a shared workspace and later moves to an isolated one
+- a failed attempt is archived and a new workspace is created
+- several issues intentionally share one operator branch workspace
+
+### Proposed object
+
+`issue_execution_workspaces`
+
+### Proposed fields
+
+- `issueId`
+- `executionWorkspaceId`
+- `relationType`
+  - `current`
+  - `historical`
+  - `preferred`
+- `createdAt`
+- `updatedAt`
+
+### UI simplification
+
+Most issues should only show one current workspace in the main UI. Historical links belong in advanced/history views.
+
+## 7. Work Product
+
+User-facing umbrella concept for outputs of work.
+
+### Motivation
+
+Paperclip needs a single place to show:
+
+- "here is the preview"
+- "here is the PR"
+- "here is the branch"
+- "here is the commit"
+- "here is the artifact/report/doc"
+
+without turning issues into a raw dump of adapter details.
+
+### Proposed new object
+
+`issue_work_products`
+
+### Proposed fields
+
+- `id`
+- `companyId`
+- `projectId`
+- `issueId`
+- `executionWorkspaceId`
+- `runtimeServiceId`
+- `type`
+  - `preview_url`
+  - `runtime_service`
+  - `pull_request`
+  - `branch`
+  - `commit`
+  - `artifact`
+  - `document`
+- `provider`
+  - `paperclip`
+  - `github`
+  - `gitlab`
+  - `vercel`
+  - `netlify`
+  - `custom`
+- `externalId`
+- `title`
+- `url`
+- `status`
+  - `active`
+  - `ready_for_review`
+  - `merged`
+  - `closed`
+  - `failed`
+  - `archived`
+- `reviewState`
+  - `none`
+  - `needs_board_review`
+  - `approved`
+  - `changes_requested`
+- `isPrimary`
+- `healthStatus`
+  - `unknown`
+  - `healthy`
+  - `unhealthy`
+- `summary`
+- `metadata`
+- `createdByRunId`
+- `createdAt`
+- `updatedAt`
+
+### Behavior
+
+- PRs are stored here as `type=pull_request`
+- previews are stored here as `type=preview_url` or `runtime_service`
+- Paperclip-owned processes should update health/status automatically
+- external providers should at least store link, provider, external id, and latest known state
+
+## Page and UI Model
+
+## 1. Global Navigation
+
+Do not add `Workspaces` as a top-level sidebar item in V1.
+
+### Motivation
+
+That would make the whole product feel infra-heavy, even for companies that do not use code automation.
+
+### Global nav remains
+
+- Dashboard
+- Inbox
+- Companies
+- Agents
+- Goals
+- Projects
+- Issues
+- Approvals
+
+Workspaces and work product should be surfaced through project and issue detail views.
+
+## 2. Project Detail
+
+Add a project sub-navigation that keeps planning first and code second.
+
+### Tabs
+
+- `Overview`
+- `Issues`
+- `Code`
+- `Activity`
+
+Optional future:
+
+- `Outputs`
+
+### `Overview` tab
+
+Planning-first summary:
+
+- project status
+- goals
+- lead
+- issue counts
+- top-level progress
+- latest major work product summaries
+
+### `Issues` tab
+
+- default to top-level issues only
+- show parent issue rollups:
+  - child count
+  - `x/y` done
+  - active preview/PR badges
+- optional toggle: `Show subissues`
+
+### `Code` tab
+
+This is the main workspace configuration and visibility surface.
+
+#### Section: `Project Workspaces`
+
+List durable project workspaces for the project.
+
+Card/list columns:
+
+- workspace name
+- source type
+- path or repo
+- default ref
+- primary/default badge
+- active execution workspaces count
+- active issue count
+- active preview count
+
+Actions:
+
+- `Add workspace`
+- `Edit`
+- `Set default`
+- `Archive`
+
+#### Section: `Execution Defaults`
+
+Fields:
+
+- `Enable workspace automation`
+- `Default issue execution mode`
+  - `Shared workspace`
+  - `Isolated workspace`
+  - `Operator branch`
+  - `Adapter default`
+- `Default codebase`
+- `Allow issue override`
+
+#### Section: `Provisioning`
+
+Fields:
+
+- `Setup command`
+- `Cleanup command`
+- `Implementation`
+  - `Shared workspace`
+  - `Git worktree`
+  - `Adapter-managed`
+- `Base ref`
+- `Branch naming template`
+- `Derived workspace parent directory`
+
+Hide git-specific fields when the selected workspace is not git-backed.
+
+#### Section: `Pull Requests`
+
+Fields:
+
+- `PR workflow`
+  - `Disabled`
+  - `Manual`
+  - `Agent may open draft PR`
+  - `Approval required to open PR`
+  - `Approval required to mark ready`
+- `Default base branch`
+- `PR title template`
+- `PR body template`
+
+#### Section: `Previews and Runtime`
+
+Fields:
+
+- `Allow workspace runtime services`
+- `Default services profile`
+- `Harvest owned preview URLs`
+- `Track external preview URLs`
+
+#### Section: `Cleanup`
+
+Fields:
+
+- `Cleanup mode`
+  - `Manual`
+  - `When issue is terminal`
+  - `When PR closes`
+  - `After retention window`
+- `Retention window`
+- `Keep while preview is active`
+- `Keep while PR is open`
+
+## 3. Add Project Workspace Flow
+
+Entry point: `Project > Code > Add workspace`
+
+### Form fields
+
+- `Name`
+- `Source type`
+  - `Local folder`
+  - `Git repo`
+  - `Non-git folder`
+  - `Remote managed`
+- `Local path`
+- `Repository URL`
+- `Default ref`
+- `Set as default workspace`
+- `Setup command`
+- `Cleanup command`
+
+### Behavior
+
+- if source type is non-git, hide branch/PR-specific setup
+- if source type is git, show ref and optional advanced branch fields
+- for simple solo users, this can be one path field and one save button
+
+## 4. Issue Create Flow
+
+Issue creation should stay simple by default.
+
+### Default behavior
+
+If the selected project:
+
+- has no workspace automation: show no workspace UI
+- has one default project workspace and default execution mode: inherit silently
+
+### Show a `Workspace` section only when relevant
+
+#### Basic fields
+
+- `Codebase`
+  - default selected project workspace
+- `Execution mode`
+  - `Project default`
+  - `Shared workspace`
+  - `Isolated workspace`
+  - `Operator branch`
+
+#### Advanced-only field
+
+- `Reuse existing execution workspace`
+
+This dropdown should show only active execution workspaces for the selected project workspace, with labels like:
+
+- `dotta/integration-branch`
+- `PAP-447-add-worktree-support`
+- `shared primary workspace`
+
+### Important rule
+
+Do not show a picker containing every possible workspace object by default.
+
+The normal flow should feel like:
+
+- choose project
+- optionally choose codebase
+- optionally choose execution mode
+
+not:
+
+- choose from a long mixed list of roots, derived worktrees, previews, and branch names
+
+## 5. Issue Detail
+
+Issue detail should expose workspace and work product clearly, but without becoming a code host UI.
+
+### Header chips
+
+Show compact summary chips near the title/status area:
+
+- `Codebase: Web App`
+- `Workspace: Shared`
+- `Workspace: PAP-447-add-worktree-support`
+- `PR: Open`
+- `Preview: Healthy`
+
+### Tabs
+
+- `Comments`
+- `Subissues`
+- `Work Product`
+- `Activity`
+
+### `Work Product` tab
+
+Sections:
+
+- `Current workspace`
+- `Previews`
+- `Pull requests`
+- `Branches and commits`
+- `Artifacts and documents`
+
+#### Current workspace panel
+
+Fields:
+
+- workspace name
+- mode
+- branch
+- base ref
+- last used
+- linked issues count
+- cleanup status
+
+Actions:
+
+- `Open workspace details`
+- `Mark in review`
+- `Request cleanup`
+
+#### Pull request cards
+
+Fields:
+
+- title
+- provider
+- status
+- review state
+- linked branch
+- open/ready/merged timestamps
+
+Actions:
+
+- `Open PR`
+- `Refresh status`
+- `Request board review`
+
+#### Preview cards
+
+Fields:
+
+- title
+- URL
+- provider
+- health
+- ownership
+- updated at
+
+Actions:
+
+- `Open preview`
+- `Refresh`
+- `Archive`
+
+## 6. Execution Workspace Detail
+
+This can be reached from a project code tab or an issue work product tab.
+
+It does not need to be in the main sidebar.
+
+### Sections
+
+- identity
+- source issue
+- linked issues
+- branch/ref
+- active runtime services
+- previews
+- PRs
+- cleanup state
+- event/activity history
+
+### Motivation
+
+This is where advanced users go when they need to inspect the mechanics. Most users should not need it in normal flow.
+
+## 7. Inbox Behavior
+
+Inbox should surface actionable work product events, not every implementation detail.
+
+### Show inbox items for
+
+- issue assigned or updated
+- PR needs board review
+- PR opened or marked ready
+- preview unhealthy
+- workspace cleanup failed
+- runtime service failed
+
+### Do not show by default
+
+- every workspace heartbeat
+- every branch update
+- every derived workspace creation
+
+### Display style
+
+If the inbox item is about a preview or PR, show issue context with it:
+
+- issue identifier and title
+- parent issue if this is a subissue
+- workspace name if relevant
+
+## 8. Issues List and Kanban
+
+Keep list and board planning-first.
+
+### Default behavior
+
+- show top-level issues by default
+- show parent rollups for subissues
+- do not flatten every child execution detail into the main board
+
+### Row/card adornments
+
+For issues with linked work product, show compact badges:
+
+- `1 PR`
+- `2 previews`
+- `shared workspace`
+- `isolated workspace`
+
+### Optional advanced filters
+
+- `Has PR`
+- `Has preview`
+- `Workspace mode`
+- `Codebase`
+
+## Behavior Rules
+
+## 1. Cleanup must not depend on agents remembering `in_review`
+
+Agents may still use `in_review`, but cleanup behavior must be governed by policy and observed state.
+
+### Keep an execution workspace alive while any of these are true
+
+- a linked issue is non-terminal
+- a linked PR is open
+- a linked preview/runtime service is active
+- the workspace is still within retention window
+
+### Hide instead of deleting aggressively
+
+Archived or idle workspaces should be hidden from default lists before they are hard-cleaned up.
+
+## 2. Multiple issues may intentionally share one execution workspace
+
+This is how Paperclip supports:
+
+- solo dev on a shared branch
+- operator integration branches
+- related features batched into one PR
+
+This is the key reason not to force 1 issue = 1 workspace = 1 PR.
+
+## 3. Isolated issue workspaces remain opt-in
+
+Even in a git-heavy project, isolated workspaces should be optional.
+
+Examples where shared mode is valid:
+
+- tiny bug fixes
+- branchless prototyping
+- non-git projects
+- single-user local workflows
+
+## 4. PR policy belongs to git-backed workspace policy
+
+PR automation decisions should be made at the project/workspace policy layer.
+
+The issue should only:
+
+- surface the resulting PR
+- route approvals/review requests
+- show status and review state
+
+## 5. Work product is the user-facing unifier
+
+Previews, PRs, commits, and artifacts should all be discoverable through one consistent issue-level affordance.
+
+That keeps Paperclip focused on coordination and visibility instead of splitting outputs across many hidden subsystems.
+
+## Recommended Implementation Order
+
+## Phase 1: Clarify current objects in UI
+
+1. Surface `Project > Code` tab
+2. Show existing project workspaces there
+3. Re-enable project-level execution workspace policy with revised copy
+4. Keep issue creation simple with inherited defaults
+
+## Phase 2: Add explicit execution workspace record
+
+1. Add `execution_workspaces`
+2. Link runs, issues, previews, and PRs to it
+3. Add simple execution workspace detail page
+
+## Phase 3: Add work product model
+
+1. Add `issue_work_products`
+2. Ingest PRs, previews, branches, commits
+3. Add issue `Work Product` tab
+4. Add inbox items for actionable work product state changes
+
+## Phase 4: Add advanced reuse and cleanup workflows
+
+1. Add `reuse existing execution workspace`
+2. Add cleanup lifecycle UI
+3. Add operator branch workflow shortcuts
+4. Add richer external preview harvesting
+
+## Why This Model Is Right
+
+This model keeps the product balanced:
+
+- simple enough for solo users
+- strong enough for real engineering teams
+- flexible for non-git projects
+- explicit enough to govern PRs and previews
+
+Most importantly, it keeps the abstractions clean:
+
+- projects plan the work
+- project workspaces define the durable codebases
+- execution workspaces define where work ran
+- work product defines what came out of the work
+- PRs remain outputs, not the core task model
+
+That is a better fit for Paperclip than either extreme:
+
+- hiding workspace behavior until nobody understands it
+- or making the whole app revolve around code-host mechanics

From 89e247b410ee2d7ffa2ffc613af2871928360367 Mon Sep 17 00:00:00 2001
From: Dotta <bippadotta@protonmail.com>
Date: Fri, 13 Mar 2026 09:06:49 -0500
Subject: [PATCH 08/28] Expand workspace plan for migration and cloud execution

---
 ...orkspace-product-model-and-work-product.md | 169 +++++++++++++++++-
 1 file changed, 168 insertions(+), 1 deletion(-)

diff --git a/doc/plans/workspace-product-model-and-work-product.md b/doc/plans/workspace-product-model-and-work-product.md
index 3b201e7d..ae5b8e79 100644
--- a/doc/plans/workspace-product-model-and-work-product.md
+++ b/doc/plans/workspace-product-model-and-work-product.md
@@ -38,6 +38,8 @@ The main product risk is overloading one concept to do too much:
    - commits
    - documents and artifacts
 5. Keep the main navigation and task board simple.
+6. Seamlessly upgrade existing Paperclip users to the new model without forcing disruptive reconfiguration.
+7. Support cloud-hosted Paperclip deployments where execution happens in remote or adapter-managed environments rather than local workers.
 
 ## Non-Goals
 
@@ -45,6 +47,7 @@ The main product risk is overloading one concept to do too much:
 - Requiring every issue to have its own branch or PR
 - Requiring every project to configure code/workspace automation
 - Making workspaces a top-level global navigation primitive in V1
+- Requiring a local filesystem path or local git checkout to use workspace-aware execution
 
 ## Core Product Decisions
 
@@ -86,6 +89,7 @@ Examples:
 - an isolated git worktree
 - a long-lived operator branch checkout
 - an adapter-managed remote sandbox
+- a cloud agent provider's isolated branch/session environment
 
 This object must be recorded explicitly so that Paperclip can:
 
@@ -107,7 +111,38 @@ Paperclip should treat PRs as a type of work product linked back to:
 
 Git-specific automation should live under workspace policy, not under the core issue abstraction.
 
-### 5. Subissues remain planning and ownership structure
+### 5. Existing users must upgrade automatically
+
+Paperclip already has users and existing project/task data. Any new model must preserve continuity.
+
+The product should default existing installs into a sensible compatibility mode:
+
+- existing projects without workspace configuration continue to work unchanged
+- existing `project_workspaces` become the durable `project workspace` objects
+- existing project execution workspace policy is mapped forward rather than discarded
+- issues without explicit workspace fields continue to inherit current behavior
+
+This migration should feel additive, not like a mandatory re-onboarding flow.
+
+### 6. Cloud-hosted Paperclip must be a first-class deployment mode
+
+Paperclip cannot assume that it is running on the same machine as the code.
+
+In cloud deployments, Paperclip may:
+
+- run on Vercel or another serverless host
+- have no long-lived local worker process
+- delegate execution to a remote coding agent or provider-managed sandbox
+- receive back a branch, PR, preview URL, or artifact from that remote environment
+
+The model therefore must be portable:
+
+- `project workspace` may be remote-managed, not local
+- `execution workspace` may have no local `cwd`
+- `runtime services` may be tracked by provider reference and URL rather than a host process
+- work product harvesting must handle externally owned previews and PRs
+
+### 7. Subissues remain planning and ownership structure
 
 Subissues are for decomposition and parallel ownership.
 
@@ -131,6 +166,11 @@ Use these terms consistently in product copy:
 - `Work product`: previews, PRs, branches, commits, artifacts, docs
 - `Runtime service`: a process or service Paperclip owns or tracks for a workspace
 
+Use these terms consistently in migration and deployment messaging:
+
+- `Compatible mode`: existing behavior preserved without new workspace automation
+- `Adapter-managed workspace`: workspace realized by a remote or cloud execution provider
+
 Avoid teaching users that "workspace" always means "git worktree on my machine".
 
 ## Product Object Model
@@ -176,6 +216,7 @@ from:
 - "what temporary execution environment did this issue run in?"
 
 That keeps the model simple for solo users while still supporting advanced automation.
+It also lets cloud-hosted Paperclip deployments point at codebases and remotes without pretending the Paperclip host has direct filesystem access.
 
 ### Proposed fields
 
@@ -206,6 +247,7 @@ That keeps the model simple for solo users while still supporting advanced autom
 - `sourceType=non_git_path` is important so non-git projects are first-class.
 - `setupCommand` and `cleanupCommand` should be allowed here for workspace-root bootstrap, even when isolated execution is not used.
 - For a monorepo, multiple project workspaces may point at different roots or packages under one repo.
+- `sourceType=remote_managed` is important for cloud deployments where the durable codebase is defined by provider/repo metadata rather than a local checkout path.
 
 ## 3. Project Execution Workspace Policy
 
@@ -220,6 +262,7 @@ This lets Paperclip support:
 - direct editing in a shared workspace
 - isolated workspaces for issue parallelism
 - long-lived integration branch workflows
+- remote cloud-agent execution that returns a branch or PR
 
 without forcing every issue or agent to expose low-level runtime configuration.
 
@@ -305,6 +348,7 @@ Examples:
 - if the project has no workspace automation, these fields may all be null
 - if the project has one primary workspace, issue creation should default to it silently
 - `reuse_existing` is advanced-only and should target active execution workspaces, not the whole workspace universe
+- existing issues without these fields should behave as `inherit` during migration
 
 ## 5. Execution Workspace
 
@@ -321,6 +365,7 @@ Without an explicit `execution workspace` record, Paperclip has nowhere stable t
 - PR linkage
 - cleanup state
 - "reuse this existing integration branch" behavior
+- remote provider session identity
 
 ### Proposed new object
 
@@ -354,6 +399,11 @@ Without an explicit `execution workspace` record, Paperclip has nowhere stable t
 - `baseRef`
 - `branchName`
 - `providerRef`
+- `providerType`
+  - `local_fs`
+  - `git_worktree`
+  - `adapter_managed`
+  - `cloud_sandbox`
 - `derivedFromExecutionWorkspaceId`
 - `lastUsedAt`
 - `openedAt`
@@ -368,6 +418,7 @@ Without an explicit `execution workspace` record, Paperclip has nowhere stable t
 
 - `sourceIssueId` is the issue that originally caused the workspace to be created, not necessarily the only issue linked to it later.
 - multiple issues may link to the same execution workspace in a long-lived branch workflow.
+- `cwd` may be null for remote execution workspaces; provider identity and work product links still make the object useful.
 
 ## 6. Issue-to-Execution Workspace Link
 
@@ -473,6 +524,7 @@ without turning issues into a raw dump of adapter details.
 - previews are stored here as `type=preview_url` or `runtime_service`
 - Paperclip-owned processes should update health/status automatically
 - external providers should at least store link, provider, external id, and latest known state
+- cloud agents should be able to create work product records without Paperclip owning the execution host
 
 ## Page and UI Model
 
@@ -550,6 +602,7 @@ Card/list columns:
 - active execution workspaces count
 - active issue count
 - active preview count
+- hosting type / provider when remote-managed
 
 Actions:
 
@@ -586,6 +639,7 @@ Fields:
 - `Derived workspace parent directory`
 
 Hide git-specific fields when the selected workspace is not git-backed.
+Hide local-path-specific fields when the selected workspace is remote-managed.
 
 #### Section: `Pull Requests`
 
@@ -637,6 +691,8 @@ Entry point: `Project > Code > Add workspace`
   - `Remote managed`
 - `Local path`
 - `Repository URL`
+- `Remote provider`
+- `Remote workspace reference`
 - `Default ref`
 - `Set as default workspace`
 - `Setup command`
@@ -646,6 +702,7 @@ Entry point: `Project > Code > Add workspace`
 
 - if source type is non-git, hide branch/PR-specific setup
 - if source type is git, show ref and optional advanced branch fields
+- if source type is remote-managed, show provider/reference fields and hide local-path-only configuration
 - for simple solo users, this can be one path field and one save button
 
 ## 4. Issue Create Flow
@@ -695,6 +752,10 @@ not:
 
 - choose from a long mixed list of roots, derived worktrees, previews, and branch names
 
+### Migration rule
+
+For existing users, issue creation should continue to look the same until a project explicitly enables richer workspace behavior.
+
 ## 5. Issue Detail
 
 Issue detail should expose workspace and work product clearly, but without becoming a code host UI.
@@ -790,6 +851,7 @@ It does not need to be in the main sidebar.
 - source issue
 - linked issues
 - branch/ref
+- provider/session identity
 - active runtime services
 - previews
 - PRs
@@ -812,6 +874,7 @@ Inbox should surface actionable work product events, not every implementation de
 - preview unhealthy
 - workspace cleanup failed
 - runtime service failed
+- remote cloud-agent run returned PR or preview that needs review
 
 ### Do not show by default
 
@@ -853,6 +916,101 @@ For issues with linked work product, show compact badges:
 - `Workspace mode`
 - `Codebase`
 
+## Upgrade and Migration Plan
+
+## 1. Product-level migration stance
+
+Migration must be silent-by-default and compatibility-preserving.
+
+Existing users should not be forced to:
+
+- create new workspace objects by hand before they can keep working
+- re-tag old issues
+- learn new workspace concepts before basic issue flows continue to function
+
+## 2. Existing project migration
+
+On upgrade:
+
+- existing `project_workspaces` records are retained and shown as `Project Workspaces`
+- the current primary workspace remains the default codebase
+- existing project execution workspace policy is mapped into the new `Project Execution Workspace Policy` surface
+- projects with no execution workspace policy stay in compatible/shared mode
+
+## 3. Existing issue migration
+
+On upgrade:
+
+- existing issues default to `executionWorkspacePreference=inherit`
+- if an issue already has execution workspace settings, map them forward directly
+- if an issue has no explicit workspace data, preserve existing behavior and do not force a user-visible choice
+
+## 4. Existing run/runtime migration
+
+On upgrade:
+
+- active or recent runtime services can be backfilled into execution workspace history where feasible
+- missing history should not block rollout; forward correctness matters more than perfect historical reconstruction
+
+## 5. Rollout UX
+
+Use additive language in the UI:
+
+- `Code`
+- `Workspace automation`
+- `Optional`
+- `Advanced`
+
+Avoid migration copy that implies users were previously using the product "wrong".
+
+## Cloud Deployment Requirements
+
+## 1. Paperclip host and execution host must be decoupled
+
+Paperclip may run:
+
+- locally with direct filesystem access
+- in a cloud app host such as Vercel
+- in a hybrid setup with external job runners
+
+The workspace model must work in all three.
+
+## 2. Remote execution must support first-class work product reporting
+
+A cloud agent should be able to:
+
+- resolve a project workspace
+- realize an adapter-managed execution workspace remotely
+- produce a branch
+- open or update a PR
+- emit preview URLs
+- register artifacts
+
+without the Paperclip host itself running local git or local preview processes.
+
+## 3. Local-only assumptions must be optional
+
+The following must be optional, not required:
+
+- local `cwd`
+- local git CLI
+- host-managed worktree directories
+- host-owned long-lived preview processes
+
+## 4. Same product surface, different provider behavior
+
+The UI should not split into "local mode" and "cloud mode" products.
+
+Instead:
+
+- local projects show path/git implementation details
+- cloud projects show provider/reference details
+- both surface the same high-level objects:
+  - project workspace
+  - execution workspace
+  - work product
+  - runtime service or preview
+
 ## Behavior Rules
 
 ## 1. Cleanup must not depend on agents remembering `in_review`
@@ -921,6 +1079,7 @@ That keeps Paperclip focused on coordination and visibility instead of splitting
 1. Add `execution_workspaces`
 2. Link runs, issues, previews, and PRs to it
 3. Add simple execution workspace detail page
+4. Make `cwd` optional and ensure provider-managed remote workspaces are supported from day one
 
 ## Phase 3: Add work product model
 
@@ -928,6 +1087,7 @@ That keeps Paperclip focused on coordination and visibility instead of splitting
 2. Ingest PRs, previews, branches, commits
 3. Add issue `Work Product` tab
 4. Add inbox items for actionable work product state changes
+5. Support remote agent-created PR/preview reporting without local ownership
 
 ## Phase 4: Add advanced reuse and cleanup workflows
 
@@ -935,6 +1095,7 @@ That keeps Paperclip focused on coordination and visibility instead of splitting
 2. Add cleanup lifecycle UI
 3. Add operator branch workflow shortcuts
 4. Add richer external preview harvesting
+5. Add migration tooling/backfill where it improves continuity for existing users
 
 ## Why This Model Is Right
 
@@ -953,6 +1114,12 @@ Most importantly, it keeps the abstractions clean:
 - work product defines what came out of the work
 - PRs remain outputs, not the core task model
 
+It also keeps the rollout practical:
+
+- existing users can upgrade without workflow breakage
+- local-first installs stay simple
+- cloud-hosted Paperclip deployments remain first-class
+
 That is a better fit for Paperclip than either extreme:
 
 - hiding workspace behavior until nobody understands it

From e2f02415332bd2d1ea8736132143e6a908066975 Mon Sep 17 00:00:00 2001
From: Dotta <bippadotta@protonmail.com>
Date: Fri, 13 Mar 2026 09:16:28 -0500
Subject: [PATCH 09/28] docs: add dated plan naming rule and align workspace
 plan

---
 AGENTS.md                                                      | 3 +++
 ... => 2026-03-13-workspace-product-model-and-work-product.md} | 0
 2 files changed, 3 insertions(+)
 rename doc/plans/{workspace-product-model-and-work-product.md => 2026-03-13-workspace-product-model-and-work-product.md} (100%)

diff --git a/AGENTS.md b/AGENTS.md
index e4b5b514..dad6684f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -78,6 +78,9 @@ If you change schema/API behavior, update all impacted layers:
 4. Do not replace strategic docs wholesale unless asked.
 Prefer additive updates. Keep `doc/SPEC.md` and `doc/SPEC-implementation.md` aligned.
 
+5. Keep plan docs dated and centralized.
+New plan documents belong in `doc/plans/` and should use `YYYY-MM-DD-slug.md` filenames.
+
 ## 6. Database Change Workflow
 
 When changing data model:
diff --git a/doc/plans/workspace-product-model-and-work-product.md b/doc/plans/2026-03-13-workspace-product-model-and-work-product.md
similarity index 100%
rename from doc/plans/workspace-product-model-and-work-product.md
rename to doc/plans/2026-03-13-workspace-product-model-and-work-product.md

From 24d6e3a543a7dfb8ceb0c2e099b0e2c5a18db78b Mon Sep 17 00:00:00 2001
From: Dotta <bippadotta@protonmail.com>
Date: Fri, 13 Mar 2026 09:25:04 -0500
Subject: [PATCH 10/28] fix: align embedded postgres ctor types with
 initdbFlags usage

---
 cli/src/commands/worktree.ts         | 1 +
 packages/db/src/migration-runtime.ts | 1 +
 2 files changed, 2 insertions(+)

diff --git a/cli/src/commands/worktree.ts b/cli/src/commands/worktree.ts
index 94a1b8aa..582bb5dd 100644
--- a/cli/src/commands/worktree.ts
+++ b/cli/src/commands/worktree.ts
@@ -83,6 +83,7 @@ type EmbeddedPostgresCtor = new (opts: {
   password: string;
   port: number;
   persistent: boolean;
+  initdbFlags?: string[];
   onLog?: (message: unknown) => void;
   onError?: (message: unknown) => void;
 }) => EmbeddedPostgresInstance;
diff --git a/packages/db/src/migration-runtime.ts b/packages/db/src/migration-runtime.ts
index 10b7b9b1..e07bdf04 100644
--- a/packages/db/src/migration-runtime.ts
+++ b/packages/db/src/migration-runtime.ts
@@ -17,6 +17,7 @@ type EmbeddedPostgresCtor = new (opts: {
   password: string;
   port: number;
   persistent: boolean;
+  initdbFlags?: string[];
   onLog?: (message: unknown) => void;
   onError?: (message: unknown) => void;
 }) => EmbeddedPostgresInstance;

From f3c18db7dddab726fa8837544fc9b279e4f2b225 Mon Sep 17 00:00:00 2001
From: Dotta <bippadotta@protonmail.com>
Date: Thu, 12 Mar 2026 14:37:30 -0500
Subject: [PATCH 11/28] Delay onboarding starter task creation until launch

Co-Authored-By: Paperclip <noreply@paperclip.ing>
---
 ui/src/components/OnboardingWizard.tsx | 64 ++++++++++++++------------
 1 file changed, 34 insertions(+), 30 deletions(-)

diff --git a/ui/src/components/OnboardingWizard.tsx b/ui/src/components/OnboardingWizard.tsx
index 5d166929..88e16d09 100644
--- a/ui/src/components/OnboardingWizard.tsx
+++ b/ui/src/components/OnboardingWizard.tsx
@@ -494,23 +494,41 @@ export function OnboardingWizard() {
   }
 
   async function handleStep3Next() {
+    if (!createdCompanyId || !createdAgentId) return;
+    setError(null);
+    setStep(4);
+  }
+
+  async function handleLaunch() {
     if (!createdCompanyId || !createdAgentId) return;
     setLoading(true);
     setError(null);
     try {
-      const issue = await issuesApi.create(createdCompanyId, {
-        title: taskTitle.trim(),
-        ...(taskDescription.trim()
-          ? { description: taskDescription.trim() }
-          : {}),
-        assigneeAgentId: createdAgentId,
-        status: "todo"
-      });
-      setCreatedIssueRef(issue.identifier ?? issue.id);
-      queryClient.invalidateQueries({
-        queryKey: queryKeys.issues.list(createdCompanyId)
-      });
-      setStep(4);
+      let issueRef = createdIssueRef;
+      if (!issueRef) {
+        const issue = await issuesApi.create(createdCompanyId, {
+          title: taskTitle.trim(),
+          ...(taskDescription.trim()
+            ? { description: taskDescription.trim() }
+            : {}),
+          assigneeAgentId: createdAgentId,
+          status: "todo"
+        });
+        issueRef = issue.identifier ?? issue.id;
+        setCreatedIssueRef(issueRef);
+        queryClient.invalidateQueries({
+          queryKey: queryKeys.issues.list(createdCompanyId)
+        });
+      }
+
+      setSelectedCompanyId(createdCompanyId);
+      reset();
+      closeOnboarding();
+      navigate(
+        createdCompanyPrefix
+          ? `/${createdCompanyPrefix}/issues/${issueRef}`
+          : `/issues/${issueRef}`
+      );
     } catch (err) {
       setError(err instanceof Error ? err.message : "Failed to create task");
     } finally {
@@ -518,20 +536,6 @@ export function OnboardingWizard() {
     }
   }
 
-  async function handleLaunch() {
-    if (!createdAgentId) return;
-    setLoading(true);
-    setError(null);
-    setLoading(false);
-    reset();
-    closeOnboarding();
-    if (createdCompanyPrefix) {
-      navigate(`/${createdCompanyPrefix}/dashboard`);
-      return;
-    }
-    navigate("/dashboard");
-  }
-
   function handleKeyDown(e: React.KeyboardEvent) {
     if (e.key === "Enter" && (e.metaKey || e.ctrlKey)) {
       e.preventDefault();
@@ -1175,8 +1179,8 @@ export function OnboardingWizard() {
                     <div>
                       <h3 className="font-medium">Ready to launch</h3>
                       <p className="text-xs text-muted-foreground">
-                        Everything is set up. Your assigned task already woke
-                        the agent, so you can jump straight to the issue.
+                        Everything is set up. Launching now will create the
+                        starter task, wake the agent, and open the issue.
                       </p>
                     </div>
                   </div>
@@ -1291,7 +1295,7 @@ export function OnboardingWizard() {
                       ) : (
                         <ArrowRight className="h-3.5 w-3.5 mr-1" />
                       )}
-                      {loading ? "Opening..." : "Open Issue"}
+                      {loading ? "Creating..." : "Create & Open Issue"}
                     </Button>
                   )}
                 </div>

From c9259bbec0d201eb864a7058c7d1fef0114c28c5 Mon Sep 17 00:00:00 2001
From: Dotta <bippadotta@protonmail.com>
Date: Thu, 12 Mar 2026 16:04:28 -0500
Subject: [PATCH 12/28] Fix manual company switch route sync

Co-Authored-By: Paperclip <noreply@paperclip.ing>
---
 ui/src/components/Layout.tsx         | 11 ++++++++-
 ui/src/context/CompanyContext.tsx    |  3 +--
 ui/src/lib/company-selection.test.ts | 34 ++++++++++++++++++++++++++++
 ui/src/lib/company-selection.ts      | 18 +++++++++++++++
 4 files changed, 63 insertions(+), 3 deletions(-)
 create mode 100644 ui/src/lib/company-selection.test.ts
 create mode 100644 ui/src/lib/company-selection.ts

diff --git a/ui/src/components/Layout.tsx b/ui/src/components/Layout.tsx
index a90efa9a..e484b265 100644
--- a/ui/src/components/Layout.tsx
+++ b/ui/src/components/Layout.tsx
@@ -22,6 +22,7 @@ import { useTheme } from "../context/ThemeContext";
 import { useKeyboardShortcuts } from "../hooks/useKeyboardShortcuts";
 import { useCompanyPageMemory } from "../hooks/useCompanyPageMemory";
 import { healthApi } from "../api/health";
+import { shouldSyncCompanySelectionFromRoute } from "../lib/company-selection";
 import { queryKeys } from "../lib/queryKeys";
 import { cn } from "../lib/utils";
 import { NotFoundPage } from "../pages/NotFound";
@@ -36,6 +37,7 @@ export function Layout() {
     loading: companiesLoading,
     selectedCompany,
     selectedCompanyId,
+    selectionSource,
     setSelectedCompanyId,
   } = useCompany();
   const { theme, toggleTheme } = useTheme();
@@ -88,7 +90,13 @@ export function Layout() {
       return;
     }
 
-    if (selectedCompanyId !== matchedCompany.id) {
+    if (
+      shouldSyncCompanySelectionFromRoute({
+        selectionSource,
+        selectedCompanyId,
+        routeCompanyId: matchedCompany.id,
+      })
+    ) {
       setSelectedCompanyId(matchedCompany.id, { source: "route_sync" });
     }
   }, [
@@ -99,6 +107,7 @@ export function Layout() {
     location.pathname,
     location.search,
     navigate,
+    selectionSource,
     selectedCompanyId,
     setSelectedCompanyId,
   ]);
diff --git a/ui/src/context/CompanyContext.tsx b/ui/src/context/CompanyContext.tsx
index eafc7f55..fb074f33 100644
--- a/ui/src/context/CompanyContext.tsx
+++ b/ui/src/context/CompanyContext.tsx
@@ -12,8 +12,7 @@ import type { Company } from "@paperclipai/shared";
 import { companiesApi } from "../api/companies";
 import { ApiError } from "../api/client";
 import { queryKeys } from "../lib/queryKeys";
-
-type CompanySelectionSource = "manual" | "route_sync" | "bootstrap";
+import type { CompanySelectionSource } from "../lib/company-selection";
 type CompanySelectionOptions = { source?: CompanySelectionSource };
 
 interface CompanyContextValue {
diff --git a/ui/src/lib/company-selection.test.ts b/ui/src/lib/company-selection.test.ts
new file mode 100644
index 00000000..a8533a4b
--- /dev/null
+++ b/ui/src/lib/company-selection.test.ts
@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+import { shouldSyncCompanySelectionFromRoute } from "./company-selection";
+
+describe("shouldSyncCompanySelectionFromRoute", () => {
+  it("does not resync when selection already matches the route", () => {
+    expect(
+      shouldSyncCompanySelectionFromRoute({
+        selectionSource: "route_sync",
+        selectedCompanyId: "pap",
+        routeCompanyId: "pap",
+      }),
+    ).toBe(false);
+  });
+
+  it("defers route sync while a manual company switch is in flight", () => {
+    expect(
+      shouldSyncCompanySelectionFromRoute({
+        selectionSource: "manual",
+        selectedCompanyId: "pap",
+        routeCompanyId: "ret",
+      }),
+    ).toBe(false);
+  });
+
+  it("syncs back to the route company for non-manual mismatches", () => {
+    expect(
+      shouldSyncCompanySelectionFromRoute({
+        selectionSource: "route_sync",
+        selectedCompanyId: "pap",
+        routeCompanyId: "ret",
+      }),
+    ).toBe(true);
+  });
+});
diff --git a/ui/src/lib/company-selection.ts b/ui/src/lib/company-selection.ts
new file mode 100644
index 00000000..ce02cb4d
--- /dev/null
+++ b/ui/src/lib/company-selection.ts
@@ -0,0 +1,18 @@
+export type CompanySelectionSource = "manual" | "route_sync" | "bootstrap";
+
+export function shouldSyncCompanySelectionFromRoute(params: {
+  selectionSource: CompanySelectionSource;
+  selectedCompanyId: string | null;
+  routeCompanyId: string;
+}): boolean {
+  const { selectionSource, selectedCompanyId, routeCompanyId } = params;
+
+  if (selectedCompanyId === routeCompanyId) return false;
+
+  // Let manual company switches finish their remembered-path navigation first.
+  if (selectionSource === "manual" && selectedCompanyId) {
+    return false;
+  }
+
+  return true;
+}

From 575a2fd83f83dfb5cfa2f7a89e9f02b2269fce88 Mon Sep 17 00:00:00 2001
From: Dotta <bippadotta@protonmail.com>
Date: Thu, 12 Mar 2026 16:11:37 -0500
Subject: [PATCH 13/28] feat: skip pre-filled assignee/project fields when
 tabbing in new issue dialog

When creating a new issue with a pre-filled assignee or project (e.g. from
a project page), Tab from the title field now skips over fields that already
have values, going directly to the next empty field or description.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
---
 ui/src/components/NewIssueDialog.tsx | 96 ++++++++++++++++++++--------
 1 file changed, 70 insertions(+), 26 deletions(-)

diff --git a/ui/src/components/NewIssueDialog.tsx b/ui/src/components/NewIssueDialog.tsx
index 01f210ed..c017306c 100644
--- a/ui/src/components/NewIssueDialog.tsx
+++ b/ui/src/components/NewIssueDialog.tsx
@@ -10,6 +10,11 @@ import { assetsApi } from "../api/assets";
 import { queryKeys } from "../lib/queryKeys";
 import { useProjectOrder } from "../hooks/useProjectOrder";
 import { getRecentAssigneeIds, sortAgentsByRecency, trackRecentAssignee } from "../lib/recent-assignees";
+import {
+  assigneeValueFromSelection,
+  currentUserAssigneeOption,
+  parseAssigneeValue,
+} from "../lib/assignees";
 import {
   Dialog,
   DialogContent,
@@ -63,7 +68,8 @@ interface IssueDraft {
   description: string;
   status: string;
   priority: string;
-  assigneeId: string;
+  assigneeValue: string;
+  assigneeId?: string;
   projectId: string;
   assigneeModelOverride: string;
   assigneeThinkingEffort: string;
@@ -173,7 +179,7 @@ export function NewIssueDialog() {
   const [description, setDescription] = useState("");
   const [status, setStatus] = useState("todo");
   const [priority, setPriority] = useState("");
-  const [assigneeId, setAssigneeId] = useState("");
+  const [assigneeValue, setAssigneeValue] = useState("");
   const [projectId, setProjectId] = useState("");
   const [assigneeOptionsOpen, setAssigneeOptionsOpen] = useState(false);
   const [assigneeModelOverride, setAssigneeModelOverride] = useState("");
@@ -220,7 +226,11 @@ export function NewIssueDialog() {
     userId: currentUserId,
   });
 
-  const assigneeAdapterType = (agents ?? []).find((agent) => agent.id === assigneeId)?.adapterType ?? null;
+  const selectedAssignee = useMemo(() => parseAssigneeValue(assigneeValue), [assigneeValue]);
+  const selectedAssigneeAgentId = selectedAssignee.assigneeAgentId;
+  const selectedAssigneeUserId = selectedAssignee.assigneeUserId;
+
+  const assigneeAdapterType = (agents ?? []).find((agent) => agent.id === selectedAssigneeAgentId)?.adapterType ?? null;
   const supportsAssigneeOverrides = Boolean(
     assigneeAdapterType && ISSUE_OVERRIDE_ADAPTER_TYPES.has(assigneeAdapterType),
   );
@@ -295,7 +305,7 @@ export function NewIssueDialog() {
       description,
       status,
       priority,
-      assigneeId,
+      assigneeValue,
       projectId,
       assigneeModelOverride,
       assigneeThinkingEffort,
@@ -307,7 +317,7 @@ export function NewIssueDialog() {
     description,
     status,
     priority,
-    assigneeId,
+    assigneeValue,
     projectId,
     assigneeModelOverride,
     assigneeThinkingEffort,
@@ -330,7 +340,7 @@ export function NewIssueDialog() {
       setStatus(newIssueDefaults.status ?? "todo");
       setPriority(newIssueDefaults.priority ?? "");
       setProjectId(newIssueDefaults.projectId ?? "");
-      setAssigneeId(newIssueDefaults.assigneeAgentId ?? "");
+      setAssigneeValue(assigneeValueFromSelection(newIssueDefaults));
       setAssigneeModelOverride("");
       setAssigneeThinkingEffort("");
       setAssigneeChrome(false);
@@ -340,7 +350,11 @@ export function NewIssueDialog() {
       setDescription(draft.description);
       setStatus(draft.status || "todo");
       setPriority(draft.priority);
-      setAssigneeId(newIssueDefaults.assigneeAgentId ?? draft.assigneeId);
+      setAssigneeValue(
+        newIssueDefaults.assigneeAgentId || newIssueDefaults.assigneeUserId
+          ? assigneeValueFromSelection(newIssueDefaults)
+          : (draft.assigneeValue ?? draft.assigneeId ?? ""),
+      );
       setProjectId(newIssueDefaults.projectId ?? draft.projectId);
       setAssigneeModelOverride(draft.assigneeModelOverride ?? "");
       setAssigneeThinkingEffort(draft.assigneeThinkingEffort ?? "");
@@ -350,7 +364,7 @@ export function NewIssueDialog() {
       setStatus(newIssueDefaults.status ?? "todo");
       setPriority(newIssueDefaults.priority ?? "");
       setProjectId(newIssueDefaults.projectId ?? "");
-      setAssigneeId(newIssueDefaults.assigneeAgentId ?? "");
+      setAssigneeValue(assigneeValueFromSelection(newIssueDefaults));
       setAssigneeModelOverride("");
       setAssigneeThinkingEffort("");
       setAssigneeChrome(false);
@@ -390,7 +404,7 @@ export function NewIssueDialog() {
     setDescription("");
     setStatus("todo");
     setPriority("");
-    setAssigneeId("");
+    setAssigneeValue("");
     setProjectId("");
     setAssigneeOptionsOpen(false);
     setAssigneeModelOverride("");
@@ -406,7 +420,7 @@ export function NewIssueDialog() {
   function handleCompanyChange(companyId: string) {
     if (companyId === effectiveCompanyId) return;
     setDialogCompanyId(companyId);
-    setAssigneeId("");
+    setAssigneeValue("");
     setProjectId("");
     setAssigneeModelOverride("");
     setAssigneeThinkingEffort("");
@@ -443,7 +457,8 @@ export function NewIssueDialog() {
       description: description.trim() || undefined,
       status,
       priority: priority || "medium",
-      ...(assigneeId ? { assigneeAgentId: assigneeId } : {}),
+      ...(selectedAssigneeAgentId ? { assigneeAgentId: selectedAssigneeAgentId } : {}),
+      ...(selectedAssigneeUserId ? { assigneeUserId: selectedAssigneeUserId } : {}),
       ...(projectId ? { projectId } : {}),
       ...(assigneeAdapterOverrides ? { assigneeAdapterOverrides } : {}),
       ...(executionWorkspaceSettings ? { executionWorkspaceSettings } : {}),
@@ -475,7 +490,9 @@ export function NewIssueDialog() {
   const hasDraft = title.trim().length > 0 || description.trim().length > 0;
   const currentStatus = statuses.find((s) => s.value === status) ?? statuses[1]!;
   const currentPriority = priorities.find((p) => p.value === priority);
-  const currentAssignee = (agents ?? []).find((a) => a.id === assigneeId);
+  const currentAssignee = selectedAssigneeAgentId
+    ? (agents ?? []).find((a) => a.id === selectedAssigneeAgentId)
+    : null;
   const currentProject = orderedProjects.find((project) => project.id === projectId);
   const currentProjectExecutionWorkspacePolicy = SHOW_EXPERIMENTAL_ISSUE_WORKTREE_UI
     ? currentProject?.executionWorkspacePolicy ?? null
@@ -497,16 +514,18 @@ export function NewIssueDialog() {
       : ISSUE_THINKING_EFFORT_OPTIONS.claude_local;
   const recentAssigneeIds = useMemo(() => getRecentAssigneeIds(), [newIssueOpen]);
   const assigneeOptions = useMemo<InlineEntityOption[]>(
-    () =>
-      sortAgentsByRecency(
+    () => [
+      ...currentUserAssigneeOption(currentUserId),
+      ...sortAgentsByRecency(
         (agents ?? []).filter((agent) => agent.status !== "terminated"),
         recentAssigneeIds,
       ).map((agent) => ({
-        id: agent.id,
+        id: assigneeValueFromSelection({ assigneeAgentId: agent.id }),
         label: agent.name,
         searchText: `${agent.name} ${agent.role} ${agent.title ?? ""}`,
       })),
-    [agents, recentAssigneeIds],
+    ],
+    [agents, currentUserId, recentAssigneeIds],
   );
   const projectOptions = useMemo<InlineEntityOption[]>(
     () =>
@@ -710,7 +729,16 @@ export function NewIssueDialog() {
               }
               if (e.key === "Tab" && !e.shiftKey) {
                 e.preventDefault();
-                assigneeSelectorRef.current?.focus();
+                if (assigneeValue) {
+                  // Assignee already set — skip to project or description
+                  if (projectId) {
+                    descriptionEditorRef.current?.focus();
+                  } else {
+                    projectSelectorRef.current?.focus();
+                  }
+                } else {
+                  assigneeSelectorRef.current?.focus();
+                }
               }
             }}
             autoFocus
@@ -723,33 +751,49 @@ export function NewIssueDialog() {
               <span>For</span>
               <InlineEntitySelector
                 ref={assigneeSelectorRef}
-                value={assigneeId}
+                value={assigneeValue}
                 options={assigneeOptions}
                 placeholder="Assignee"
                 disablePortal
                 noneLabel="No assignee"
                 searchPlaceholder="Search assignees..."
                 emptyMessage="No assignees found."
-                onChange={(id) => { if (id) trackRecentAssignee(id); setAssigneeId(id); }}
+                onChange={(value) => {
+                  const nextAssignee = parseAssigneeValue(value);
+                  if (nextAssignee.assigneeAgentId) {
+                    trackRecentAssignee(nextAssignee.assigneeAgentId);
+                  }
+                  setAssigneeValue(value);
+                }}
                 onConfirm={() => {
-                  projectSelectorRef.current?.focus();
+                  if (projectId) {
+                    descriptionEditorRef.current?.focus();
+                  } else {
+                    projectSelectorRef.current?.focus();
+                  }
                 }}
                 renderTriggerValue={(option) =>
-                  option && currentAssignee ? (
-                    <>
-                      <AgentIcon icon={currentAssignee.icon} className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />
+                  option ? (
+                    currentAssignee ? (
+                      <>
+                        <AgentIcon icon={currentAssignee.icon} className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />
+                        <span className="truncate">{option.label}</span>
+                      </>
+                    ) : (
                       <span className="truncate">{option.label}</span>
-                    </>
+                    )
                   ) : (
                     <span className="text-muted-foreground">Assignee</span>
                   )
                 }
                 renderOption={(option) => {
                   if (!option.id) return <span className="truncate">{option.label}</span>;
-                  const assignee = (agents ?? []).find((agent) => agent.id === option.id);
+                  const assignee = parseAssigneeValue(option.id).assigneeAgentId
+                    ? (agents ?? []).find((agent) => agent.id === parseAssigneeValue(option.id).assigneeAgentId)
+                    : null;
                   return (
                     <>
-                      <AgentIcon icon={assignee?.icon} className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />
+                      {assignee ? <AgentIcon icon={assignee.icon} className="h-3.5 w-3.5 shrink-0 text-muted-foreground" /> : null}
                       <span className="truncate">{option.label}</span>
                     </>
                   );

From 2246d5f1eb59e4a0883fc3101d79994ed3135268 Mon Sep 17 00:00:00 2001
From: Dotta <bippadotta@protonmail.com>
Date: Thu, 12 Mar 2026 16:12:38 -0500
Subject: [PATCH 14/28] Add me and unassigned assignee options

Co-Authored-By: Paperclip <noreply@paperclip.ing>
---
 ui/src/components/IssueProperties.tsx |  29 +++---
 ui/src/components/IssuesList.tsx      | 123 ++++++++++++++++++++------
 ui/src/context/DialogContext.tsx      |   1 +
 ui/src/lib/assignees.test.ts          |  53 +++++++++++
 ui/src/lib/assignees.ts               |  51 +++++++++++
 ui/src/pages/IssueDetail.tsx          |   3 +-
 6 files changed, 219 insertions(+), 41 deletions(-)
 create mode 100644 ui/src/lib/assignees.test.ts
 create mode 100644 ui/src/lib/assignees.ts

diff --git a/ui/src/components/IssueProperties.tsx b/ui/src/components/IssueProperties.tsx
index ca8e1bd4..cf4b6a43 100644
--- a/ui/src/components/IssueProperties.tsx
+++ b/ui/src/components/IssueProperties.tsx
@@ -10,6 +10,7 @@ import { useCompany } from "../context/CompanyContext";
 import { queryKeys } from "../lib/queryKeys";
 import { useProjectOrder } from "../hooks/useProjectOrder";
 import { getRecentAssigneeIds, sortAgentsByRecency, trackRecentAssignee } from "../lib/recent-assignees";
+import { formatAssigneeUserLabel } from "../lib/assignees";
 import { StatusIcon } from "./StatusIcon";
 import { PriorityIcon } from "./PriorityIcon";
 import { Identity } from "./Identity";
@@ -206,14 +207,7 @@ export function IssueProperties({ issue, onUpdate, inline }: IssuePropertiesProp
   const assignee = issue.assigneeAgentId
     ? agents?.find((a) => a.id === issue.assigneeAgentId)
     : null;
-  const userLabel = (userId: string | null | undefined) =>
-    userId
-      ? userId === "local-board"
-        ? "Board"
-        : currentUserId && userId === currentUserId
-          ? "Me"
-          : userId.slice(0, 5)
-      : null;
+  const userLabel = (userId: string | null | undefined) => formatAssigneeUserLabel(userId, currentUserId);
   const assigneeUserLabel = userLabel(issue.assigneeUserId);
   const creatorUserLabel = userLabel(issue.createdByUserId);
 
@@ -349,7 +343,22 @@ export function IssueProperties({ issue, onUpdate, inline }: IssuePropertiesProp
         >
           No assignee
         </button>
-        {issue.createdByUserId && (
+        {currentUserId && (
+          <button
+            className={cn(
+              "flex items-center gap-2 w-full px-2 py-1.5 text-xs rounded hover:bg-accent/50",
+              issue.assigneeUserId === currentUserId && "bg-accent",
+            )}
+            onClick={() => {
+              onUpdate({ assigneeAgentId: null, assigneeUserId: currentUserId });
+              setAssigneeOpen(false);
+            }}
+          >
+            <User className="h-3 w-3 shrink-0 text-muted-foreground" />
+            Assign to me
+          </button>
+        )}
+        {issue.createdByUserId && issue.createdByUserId !== currentUserId && (
           <button
             className={cn(
               "flex items-center gap-2 w-full px-2 py-1.5 text-xs rounded hover:bg-accent/50",
@@ -361,7 +370,7 @@ export function IssueProperties({ issue, onUpdate, inline }: IssuePropertiesProp
             }}
           >
             <User className="h-3 w-3 shrink-0 text-muted-foreground" />
-            {creatorUserLabel ? `Assign to ${creatorUserLabel === "Me" ? "me" : creatorUserLabel}` : "Assign to requester"}
+            {creatorUserLabel ? `Assign to ${creatorUserLabel}` : "Assign to requester"}
           </button>
         )}
         {sortedAgents
diff --git a/ui/src/components/IssuesList.tsx b/ui/src/components/IssuesList.tsx
index 6899bd5c..442f8ae4 100644
--- a/ui/src/components/IssuesList.tsx
+++ b/ui/src/components/IssuesList.tsx
@@ -3,7 +3,9 @@ import { useQuery } from "@tanstack/react-query";
 import { useDialog } from "../context/DialogContext";
 import { useCompany } from "../context/CompanyContext";
 import { issuesApi } from "../api/issues";
+import { authApi } from "../api/auth";
 import { queryKeys } from "../lib/queryKeys";
+import { formatAssigneeUserLabel } from "../lib/assignees";
 import { groupBy } from "../lib/groupBy";
 import { formatDate, cn } from "../lib/utils";
 import { timeAgo } from "../lib/timeAgo";
@@ -87,11 +89,20 @@ function toggleInArray(arr: string[], value: string): string[] {
   return arr.includes(value) ? arr.filter((v) => v !== value) : [...arr, value];
 }
 
-function applyFilters(issues: Issue[], state: IssueViewState): Issue[] {
+function applyFilters(issues: Issue[], state: IssueViewState, currentUserId?: string | null): Issue[] {
   let result = issues;
   if (state.statuses.length > 0) result = result.filter((i) => state.statuses.includes(i.status));
   if (state.priorities.length > 0) result = result.filter((i) => state.priorities.includes(i.priority));
-  if (state.assignees.length > 0) result = result.filter((i) => i.assigneeAgentId != null && state.assignees.includes(i.assigneeAgentId));
+  if (state.assignees.length > 0) {
+    result = result.filter((issue) => {
+      for (const assignee of state.assignees) {
+        if (assignee === "__unassigned" && !issue.assigneeAgentId && !issue.assigneeUserId) return true;
+        if (assignee === "__me" && currentUserId && issue.assigneeUserId === currentUserId) return true;
+        if (issue.assigneeAgentId === assignee) return true;
+      }
+      return false;
+    });
+  }
   if (state.labels.length > 0) result = result.filter((i) => (i.labelIds ?? []).some((id) => state.labels.includes(id)));
   return result;
 }
@@ -165,6 +176,11 @@ export function IssuesList({
 }: IssuesListProps) {
   const { selectedCompanyId } = useCompany();
   const { openNewIssue } = useDialog();
+  const { data: session } = useQuery({
+    queryKey: queryKeys.auth.session,
+    queryFn: () => authApi.getSession(),
+  });
+  const currentUserId = session?.user?.id ?? session?.session?.userId ?? null;
 
   // Scope the storage key per company so folding/view state is independent across companies.
   const scopedKey = selectedCompanyId ? `${viewStateKey}:${selectedCompanyId}` : viewStateKey;
@@ -224,9 +240,9 @@ export function IssuesList({
 
   const filtered = useMemo(() => {
     const sourceIssues = normalizedIssueSearch.length > 0 ? searchedIssues : issues;
-    const filteredByControls = applyFilters(sourceIssues, viewState);
+    const filteredByControls = applyFilters(sourceIssues, viewState, currentUserId);
     return sortIssues(filteredByControls, viewState);
-  }, [issues, searchedIssues, viewState, normalizedIssueSearch]);
+  }, [issues, searchedIssues, viewState, normalizedIssueSearch, currentUserId]);
 
   const { data: labels } = useQuery({
     queryKey: queryKeys.issues.labels(selectedCompanyId!),
@@ -253,13 +269,21 @@ export function IssuesList({
         .map((p) => ({ key: p, label: statusLabel(p), items: groups[p]! }));
     }
     // assignee
-    const groups = groupBy(filtered, (i) => i.assigneeAgentId ?? "__unassigned");
+    const groups = groupBy(
+      filtered,
+      (issue) => issue.assigneeAgentId ?? (issue.assigneeUserId ? `__user:${issue.assigneeUserId}` : "__unassigned"),
+    );
     return Object.keys(groups).map((key) => ({
       key,
-      label: key === "__unassigned" ? "Unassigned" : (agentName(key) ?? key.slice(0, 8)),
+      label:
+        key === "__unassigned"
+          ? "Unassigned"
+          : key.startsWith("__user:")
+            ? (formatAssigneeUserLabel(key.slice("__user:".length), currentUserId) ?? "User")
+            : (agentName(key) ?? key.slice(0, 8)),
       items: groups[key]!,
     }));
-  }, [filtered, viewState.groupBy, agents]); // eslint-disable-line react-hooks/exhaustive-deps
+  }, [filtered, viewState.groupBy, agents, agentName, currentUserId]);
 
   const newIssueDefaults = (groupKey?: string) => {
     const defaults: Record<string, string> = {};
@@ -267,13 +291,16 @@ export function IssuesList({
     if (groupKey) {
       if (viewState.groupBy === "status") defaults.status = groupKey;
       else if (viewState.groupBy === "priority") defaults.priority = groupKey;
-      else if (viewState.groupBy === "assignee" && groupKey !== "__unassigned") defaults.assigneeAgentId = groupKey;
+      else if (viewState.groupBy === "assignee" && groupKey !== "__unassigned") {
+        if (groupKey.startsWith("__user:")) defaults.assigneeUserId = groupKey.slice("__user:".length);
+        else defaults.assigneeAgentId = groupKey;
+      }
     }
     return defaults;
   };
 
-  const assignIssue = (issueId: string, assigneeAgentId: string | null) => {
-    onUpdateIssue(issueId, { assigneeAgentId, assigneeUserId: null });
+  const assignIssue = (issueId: string, assigneeAgentId: string | null, assigneeUserId: string | null = null) => {
+    onUpdateIssue(issueId, { assigneeAgentId, assigneeUserId });
     setAssigneePickerIssueId(null);
     setAssigneeSearch("");
   };
@@ -419,22 +446,37 @@ export function IssuesList({
                     </div>
 
                     {/* Assignee */}
-                    {agents && agents.length > 0 && (
-                      <div className="space-y-1">
-                        <span className="text-xs text-muted-foreground">Assignee</span>
-                        <div className="space-y-0.5 max-h-32 overflow-y-auto">
-                          {agents.map((agent) => (
-                            <label key={agent.id} className="flex items-center gap-2 px-2 py-1 rounded-sm hover:bg-accent/50 cursor-pointer">
-                              <Checkbox
-                                checked={viewState.assignees.includes(agent.id)}
-                                onCheckedChange={() => updateView({ assignees: toggleInArray(viewState.assignees, agent.id) })}
-                              />
-                              <span className="text-sm">{agent.name}</span>
-                            </label>
-                          ))}
-                        </div>
+                    <div className="space-y-1">
+                      <span className="text-xs text-muted-foreground">Assignee</span>
+                      <div className="space-y-0.5 max-h-32 overflow-y-auto">
+                        <label className="flex items-center gap-2 px-2 py-1 rounded-sm hover:bg-accent/50 cursor-pointer">
+                          <Checkbox
+                            checked={viewState.assignees.includes("__unassigned")}
+                            onCheckedChange={() => updateView({ assignees: toggleInArray(viewState.assignees, "__unassigned") })}
+                          />
+                          <span className="text-sm">No assignee</span>
+                        </label>
+                        {currentUserId && (
+                          <label className="flex items-center gap-2 px-2 py-1 rounded-sm hover:bg-accent/50 cursor-pointer">
+                            <Checkbox
+                              checked={viewState.assignees.includes("__me")}
+                              onCheckedChange={() => updateView({ assignees: toggleInArray(viewState.assignees, "__me") })}
+                            />
+                            <User className="h-3.5 w-3.5 text-muted-foreground" />
+                            <span className="text-sm">Me</span>
+                          </label>
+                        )}
+                        {(agents ?? []).map((agent) => (
+                          <label key={agent.id} className="flex items-center gap-2 px-2 py-1 rounded-sm hover:bg-accent/50 cursor-pointer">
+                            <Checkbox
+                              checked={viewState.assignees.includes(agent.id)}
+                              onCheckedChange={() => updateView({ assignees: toggleInArray(viewState.assignees, agent.id) })}
+                            />
+                            <span className="text-sm">{agent.name}</span>
+                          </label>
+                        ))}
                       </div>
-                    )}
+                    </div>
 
                     {labels && labels.length > 0 && (
                       <div className="space-y-1">
@@ -683,6 +725,13 @@ export function IssuesList({
                           >
                             {issue.assigneeAgentId && agentName(issue.assigneeAgentId) ? (
                               <Identity name={agentName(issue.assigneeAgentId)!} size="sm" />
+                            ) : issue.assigneeUserId ? (
+                              <span className="inline-flex items-center gap-1.5 text-xs">
+                                <span className="inline-flex h-5 w-5 items-center justify-center rounded-full border border-dashed border-muted-foreground/35 bg-muted/30">
+                                  <User className="h-3 w-3" />
+                                </span>
+                                {formatAssigneeUserLabel(issue.assigneeUserId, currentUserId) ?? "User"}
+                              </span>
                             ) : (
                               <span className="inline-flex items-center gap-1.5 text-xs text-muted-foreground">
                                 <span className="inline-flex h-5 w-5 items-center justify-center rounded-full border border-dashed border-muted-foreground/35 bg-muted/30">
@@ -701,7 +750,7 @@ export function IssuesList({
                         >
                           <input
                             className="mb-1 w-full border-b border-border bg-transparent px-2 py-1.5 text-xs outline-none placeholder:text-muted-foreground/50"
-                            placeholder="Search agents..."
+                            placeholder="Search assignees..."
                             value={assigneeSearch}
                             onChange={(e) => setAssigneeSearch(e.target.value)}
                             autoFocus
@@ -710,16 +759,32 @@ export function IssuesList({
                             <button
                               className={cn(
                                 "flex w-full items-center gap-2 rounded px-2 py-1.5 text-xs hover:bg-accent/50",
-                                !issue.assigneeAgentId && "bg-accent",
+                                !issue.assigneeAgentId && !issue.assigneeUserId && "bg-accent",
                               )}
                               onClick={(e) => {
                                 e.preventDefault();
                                 e.stopPropagation();
-                                assignIssue(issue.id, null);
+                                assignIssue(issue.id, null, null);
                               }}
                             >
                               No assignee
                             </button>
+                            {currentUserId && (
+                              <button
+                                className={cn(
+                                  "flex w-full items-center gap-2 rounded px-2 py-1.5 text-left text-xs hover:bg-accent/50",
+                                  issue.assigneeUserId === currentUserId && "bg-accent",
+                                )}
+                                onClick={(e) => {
+                                  e.preventDefault();
+                                  e.stopPropagation();
+                                  assignIssue(issue.id, null, currentUserId);
+                                }}
+                              >
+                                <User className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />
+                                <span>Me</span>
+                              </button>
+                            )}
                             {(agents ?? [])
                               .filter((agent) => {
                                 if (!assigneeSearch.trim()) return true;
@@ -737,7 +802,7 @@ export function IssuesList({
                                   onClick={(e) => {
                                     e.preventDefault();
                                     e.stopPropagation();
-                                    assignIssue(issue.id, agent.id);
+                                    assignIssue(issue.id, agent.id, null);
                                   }}
                                 >
                                   <Identity name={agent.name} size="sm" className="min-w-0" />
diff --git a/ui/src/context/DialogContext.tsx b/ui/src/context/DialogContext.tsx
index ef7b12b8..904ceb88 100644
--- a/ui/src/context/DialogContext.tsx
+++ b/ui/src/context/DialogContext.tsx
@@ -5,6 +5,7 @@ interface NewIssueDefaults {
   priority?: string;
   projectId?: string;
   assigneeAgentId?: string;
+  assigneeUserId?: string;
   title?: string;
   description?: string;
 }
diff --git a/ui/src/lib/assignees.test.ts b/ui/src/lib/assignees.test.ts
new file mode 100644
index 00000000..1ce22ef7
--- /dev/null
+++ b/ui/src/lib/assignees.test.ts
@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+import {
+  assigneeValueFromSelection,
+  currentUserAssigneeOption,
+  formatAssigneeUserLabel,
+  parseAssigneeValue,
+} from "./assignees";
+
+describe("assignee selection helpers", () => {
+  it("encodes and parses agent assignees", () => {
+    const value = assigneeValueFromSelection({ assigneeAgentId: "agent-123" });
+
+    expect(value).toBe("agent:agent-123");
+    expect(parseAssigneeValue(value)).toEqual({
+      assigneeAgentId: "agent-123",
+      assigneeUserId: null,
+    });
+  });
+
+  it("encodes and parses current-user assignees", () => {
+    const [option] = currentUserAssigneeOption("local-board");
+
+    expect(option).toEqual({
+      id: "user:local-board",
+      label: "Me",
+      searchText: "me board human local-board",
+    });
+    expect(parseAssigneeValue(option.id)).toEqual({
+      assigneeAgentId: null,
+      assigneeUserId: "local-board",
+    });
+  });
+
+  it("treats an empty selection as no assignee", () => {
+    expect(parseAssigneeValue("")).toEqual({
+      assigneeAgentId: null,
+      assigneeUserId: null,
+    });
+  });
+
+  it("keeps backward compatibility for raw agent ids in saved drafts", () => {
+    expect(parseAssigneeValue("legacy-agent-id")).toEqual({
+      assigneeAgentId: "legacy-agent-id",
+      assigneeUserId: null,
+    });
+  });
+
+  it("formats current and board user labels consistently", () => {
+    expect(formatAssigneeUserLabel("user-1", "user-1")).toBe("Me");
+    expect(formatAssigneeUserLabel("local-board", "someone-else")).toBe("Board");
+    expect(formatAssigneeUserLabel("user-abcdef", "someone-else")).toBe("user-");
+  });
+});
diff --git a/ui/src/lib/assignees.ts b/ui/src/lib/assignees.ts
new file mode 100644
index 00000000..274bcd40
--- /dev/null
+++ b/ui/src/lib/assignees.ts
@@ -0,0 +1,51 @@
+export interface AssigneeSelection {
+  assigneeAgentId: string | null;
+  assigneeUserId: string | null;
+}
+
+export interface AssigneeOption {
+  id: string;
+  label: string;
+  searchText?: string;
+}
+
+export function assigneeValueFromSelection(selection: Partial<AssigneeSelection>): string {
+  if (selection.assigneeAgentId) return `agent:${selection.assigneeAgentId}`;
+  if (selection.assigneeUserId) return `user:${selection.assigneeUserId}`;
+  return "";
+}
+
+export function parseAssigneeValue(value: string): AssigneeSelection {
+  if (!value) {
+    return { assigneeAgentId: null, assigneeUserId: null };
+  }
+  if (value.startsWith("agent:")) {
+    const assigneeAgentId = value.slice("agent:".length);
+    return { assigneeAgentId: assigneeAgentId || null, assigneeUserId: null };
+  }
+  if (value.startsWith("user:")) {
+    const assigneeUserId = value.slice("user:".length);
+    return { assigneeAgentId: null, assigneeUserId: assigneeUserId || null };
+  }
+  // Backward compatibility for older drafts/defaults that stored a raw agent id.
+  return { assigneeAgentId: value, assigneeUserId: null };
+}
+
+export function currentUserAssigneeOption(currentUserId: string | null | undefined): AssigneeOption[] {
+  if (!currentUserId) return [];
+  return [{
+    id: assigneeValueFromSelection({ assigneeUserId: currentUserId }),
+    label: "Me",
+    searchText: currentUserId === "local-board" ? "me board human local-board" : `me human ${currentUserId}`,
+  }];
+}
+
+export function formatAssigneeUserLabel(
+  userId: string | null | undefined,
+  currentUserId: string | null | undefined,
+): string | null {
+  if (!userId) return null;
+  if (currentUserId && userId === currentUserId) return "Me";
+  if (userId === "local-board") return "Board";
+  return userId.slice(0, 5);
+}
diff --git a/ui/src/pages/IssueDetail.tsx b/ui/src/pages/IssueDetail.tsx
index bb152e17..9a43f26a 100644
--- a/ui/src/pages/IssueDetail.tsx
+++ b/ui/src/pages/IssueDetail.tsx
@@ -304,8 +304,7 @@ export function IssueDetail() {
       options.push({ id: `agent:${agent.id}`, label: agent.name });
     }
     if (currentUserId) {
-      const label = currentUserId === "local-board" ? "Board" : "Me (Board)";
-      options.push({ id: `user:${currentUserId}`, label });
+      options.push({ id: `user:${currentUserId}`, label: "Me" });
     }
     return options;
   }, [agents, currentUserId]);

From 7d1748b3a7bd6bc354a20c6f8f66b7bbafd4819f Mon Sep 17 00:00:00 2001
From: Dotta <bippadotta@protonmail.com>
Date: Fri, 13 Mar 2026 08:49:11 -0500
Subject: [PATCH 15/28] feat: optimize heartbeat token usage

Co-Authored-By: Paperclip <noreply@paperclip.ing>
---
 .../skills}/create-agent-adapter/SKILL.md     |   0
 .../2026-03-13-TOKEN-OPTIMIZATION-PLAN.md     |   2 +-
 docs/adapters/creating-an-adapter.md          |   2 +-
 packages/adapter-utils/src/server-utils.ts    |  10 +
 packages/adapter-utils/src/types.ts           |   1 +
 .../claude-local/src/server/execute.ts        |  24 +-
 .../claude-local/src/ui/build-config.ts       |   1 +
 .../codex-local/src/server/execute.ts         |  29 +-
 .../codex-local/src/ui/build-config.ts        |   1 +
 .../cursor-local/src/server/execute.ts        |  31 +-
 .../cursor-local/src/ui/build-config.ts       |   1 +
 .../gemini-local/src/server/execute.ts        |  30 +-
 .../gemini-local/src/ui/build-config.ts       |   1 +
 .../opencode-local/src/server/execute.ts      |  27 +-
 .../opencode-local/src/ui/build-config.ts     |   1 +
 .../adapters/pi-local/src/server/execute.ts   |  37 +-
 .../adapters/pi-local/src/ui/build-config.ts  |   1 +
 packages/shared/src/validators/agent.ts       |   1 +
 ...08-46-token-optimization-implementation.md |  40 ++
 .../heartbeat-workspace-session.test.ts       |  16 +-
 server/src/routes/access.ts                   |  10 +-
 server/src/routes/agents.ts                   |  29 ++
 server/src/routes/issues.ts                   |  94 ++++-
 server/src/services/heartbeat.ts              | 348 ++++++++++++++++--
 server/src/services/issues.ts                 |  65 +++-
 skills/paperclip/SKILL.md                     |  16 +-
 ui/src/components/AgentConfigForm.tsx         |  73 ++--
 ui/src/components/agent-config-primitives.tsx |   4 +-
 28 files changed, 800 insertions(+), 95 deletions(-)
 rename {skills => .agents/skills}/create-agent-adapter/SKILL.md (100%)
 create mode 100644 report/2026-03-13-08-46-token-optimization-implementation.md

diff --git a/skills/create-agent-adapter/SKILL.md b/.agents/skills/create-agent-adapter/SKILL.md
similarity index 100%
rename from skills/create-agent-adapter/SKILL.md
rename to .agents/skills/create-agent-adapter/SKILL.md
diff --git a/doc/plans/2026-03-13-TOKEN-OPTIMIZATION-PLAN.md b/doc/plans/2026-03-13-TOKEN-OPTIMIZATION-PLAN.md
index 678444ac..e85cfdfc 100644
--- a/doc/plans/2026-03-13-TOKEN-OPTIMIZATION-PLAN.md
+++ b/doc/plans/2026-03-13-TOKEN-OPTIMIZATION-PLAN.md
@@ -121,7 +121,7 @@ Local adapters inject repo skills into runtime skill directories.
 Current repo skill sizes:
 
 - `skills/paperclip/SKILL.md`: 17,441 bytes
-- `skills/create-agent-adapter/SKILL.md`: 31,832 bytes
+- `.agents/skills/create-agent-adapter/SKILL.md`: 31,832 bytes
 - `skills/paperclip-create-agent/SKILL.md`: 4,718 bytes
 - `skills/para-memory-files/SKILL.md`: 3,978 bytes
 
diff --git a/docs/adapters/creating-an-adapter.md b/docs/adapters/creating-an-adapter.md
index e33b5411..fae0e4b3 100644
--- a/docs/adapters/creating-an-adapter.md
+++ b/docs/adapters/creating-an-adapter.md
@@ -6,7 +6,7 @@ summary: Guide to building a custom adapter
 Build a custom adapter to connect Paperclip to any agent runtime.
 
 <Tip>
-If you're using Claude Code, the `create-agent-adapter` skill can guide you through the full adapter creation process interactively. Just ask Claude to create a new adapter and it will walk you through each step.
+If you're using Claude Code, the `.agents/skills/create-agent-adapter` skill can guide you through the full adapter creation process interactively. Just ask Claude to create a new adapter and it will walk you through each step.
 </Tip>
 
 ## Package Structure
diff --git a/packages/adapter-utils/src/server-utils.ts b/packages/adapter-utils/src/server-utils.ts
index 30f0c9bd..52e52b4c 100644
--- a/packages/adapter-utils/src/server-utils.ts
+++ b/packages/adapter-utils/src/server-utils.ts
@@ -112,6 +112,16 @@ export function renderTemplate(template: string, data: Record<string, unknown>)
   return template.replace(/{{\s*([a-zA-Z0-9_.-]+)\s*}}/g, (_, path) => resolvePathValue(data, path));
 }
 
+export function joinPromptSections(
+  sections: Array<string | null | undefined>,
+  separator = "\n\n",
+) {
+  return sections
+    .map((value) => (typeof value === "string" ? value.trim() : ""))
+    .filter(Boolean)
+    .join(separator);
+}
+
 export function redactEnvForLogs(env: Record<string, string>): Record<string, string> {
   const redacted: Record<string, string> = {};
   for (const [key, value] of Object.entries(env)) {
diff --git a/packages/adapter-utils/src/types.ts b/packages/adapter-utils/src/types.ts
index 6503e5a1..df0d075a 100644
--- a/packages/adapter-utils/src/types.ts
+++ b/packages/adapter-utils/src/types.ts
@@ -99,6 +99,7 @@ export interface AdapterInvocationMeta {
   commandNotes?: string[];
   env?: Record<string, string>;
   prompt?: string;
+  promptMetrics?: Record<string, number>;
   context?: Record<string, unknown>;
 }
 
diff --git a/packages/adapters/claude-local/src/server/execute.ts b/packages/adapters/claude-local/src/server/execute.ts
index be85439d..13d92df8 100644
--- a/packages/adapters/claude-local/src/server/execute.ts
+++ b/packages/adapters/claude-local/src/server/execute.ts
@@ -12,6 +12,7 @@ import {
   parseObject,
   parseJson,
   buildPaperclipEnv,
+  joinPromptSections,
   redactEnvForLogs,
   ensureAbsoluteDirectory,
   ensureCommandResolvable,
@@ -363,7 +364,8 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
       `[paperclip] Claude session "${runtimeSessionId}" was saved for cwd "${runtimeSessionCwd}" and will not be resumed in "${cwd}".\n`,
     );
   }
-  const prompt = renderTemplate(promptTemplate, {
+  const bootstrapPromptTemplate = asString(config.bootstrapPromptTemplate, "");
+  const templateData = {
     agentId: agent.id,
     companyId: agent.companyId,
     runId,
@@ -371,7 +373,24 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     agent,
     run: { id: runId, source: "on_demand" },
     context,
-  });
+  };
+  const renderedPrompt = renderTemplate(promptTemplate, templateData);
+  const renderedBootstrapPrompt =
+    !sessionId && bootstrapPromptTemplate.trim().length > 0
+      ? renderTemplate(bootstrapPromptTemplate, templateData).trim()
+      : "";
+  const sessionHandoffNote = asString(context.paperclipSessionHandoffMarkdown, "").trim();
+  const prompt = joinPromptSections([
+    renderedBootstrapPrompt,
+    sessionHandoffNote,
+    renderedPrompt,
+  ]);
+  const promptMetrics = {
+    promptChars: prompt.length,
+    bootstrapPromptChars: renderedBootstrapPrompt.length,
+    sessionHandoffChars: sessionHandoffNote.length,
+    heartbeatPromptChars: renderedPrompt.length,
+  };
 
   const buildClaudeArgs = (resumeSessionId: string | null) => {
     const args = ["--print", "-", "--output-format", "stream-json", "--verbose"];
@@ -416,6 +435,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
         commandNotes,
         env: redactEnvForLogs(env),
         prompt,
+        promptMetrics,
         context,
       });
     }
diff --git a/packages/adapters/claude-local/src/ui/build-config.ts b/packages/adapters/claude-local/src/ui/build-config.ts
index 0c45e156..748c8dab 100644
--- a/packages/adapters/claude-local/src/ui/build-config.ts
+++ b/packages/adapters/claude-local/src/ui/build-config.ts
@@ -67,6 +67,7 @@ export function buildClaudeLocalConfig(v: CreateConfigValues): Record<string, un
   if (v.cwd) ac.cwd = v.cwd;
   if (v.instructionsFilePath) ac.instructionsFilePath = v.instructionsFilePath;
   if (v.promptTemplate) ac.promptTemplate = v.promptTemplate;
+  if (v.bootstrapPrompt) ac.bootstrapPromptTemplate = v.bootstrapPrompt;
   if (v.model) ac.model = v.model;
   if (v.thinkingEffort) ac.effort = v.thinkingEffort;
   if (v.chrome) ac.chrome = true;
diff --git a/packages/adapters/codex-local/src/server/execute.ts b/packages/adapters/codex-local/src/server/execute.ts
index c51dc8a1..1bccbc44 100644
--- a/packages/adapters/codex-local/src/server/execute.ts
+++ b/packages/adapters/codex-local/src/server/execute.ts
@@ -18,6 +18,7 @@ import {
   listPaperclipSkillEntries,
   removeMaintainerOnlySkillSymlinks,
   renderTemplate,
+  joinPromptSections,
   runChildProcess,
 } from "@paperclipai/adapter-utils/server-utils";
 import { parseCodexJsonl, isCodexUnknownSessionError } from "./parse.js";
@@ -278,6 +279,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   const instructionsFilePath = asString(config.instructionsFilePath, "").trim();
   const instructionsDir = instructionsFilePath ? `${path.dirname(instructionsFilePath)}/` : "";
   let instructionsPrefix = "";
+  let instructionsChars = 0;
   if (instructionsFilePath) {
     try {
       const instructionsContents = await fs.readFile(instructionsFilePath, "utf8");
@@ -285,6 +287,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
         `${instructionsContents}\n\n` +
         `The above agent instructions were loaded from ${instructionsFilePath}. ` +
         `Resolve any relative file references from ${instructionsDir}.\n\n`;
+      instructionsChars = instructionsPrefix.length;
       await onLog(
         "stderr",
         `[paperclip] Loaded agent instructions file: ${instructionsFilePath}\n`,
@@ -309,7 +312,8 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
       `Configured instructionsFilePath ${instructionsFilePath}, but file could not be read; continuing without injected instructions.`,
     ];
   })();
-  const renderedPrompt = renderTemplate(promptTemplate, {
+  const bootstrapPromptTemplate = asString(config.bootstrapPromptTemplate, "");
+  const templateData = {
     agentId: agent.id,
     companyId: agent.companyId,
     runId,
@@ -317,8 +321,26 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     agent,
     run: { id: runId, source: "on_demand" },
     context,
-  });
-  const prompt = `${instructionsPrefix}${renderedPrompt}`;
+  };
+  const renderedPrompt = renderTemplate(promptTemplate, templateData);
+  const renderedBootstrapPrompt =
+    !sessionId && bootstrapPromptTemplate.trim().length > 0
+      ? renderTemplate(bootstrapPromptTemplate, templateData).trim()
+      : "";
+  const sessionHandoffNote = asString(context.paperclipSessionHandoffMarkdown, "").trim();
+  const prompt = joinPromptSections([
+    instructionsPrefix,
+    renderedBootstrapPrompt,
+    sessionHandoffNote,
+    renderedPrompt,
+  ]);
+  const promptMetrics = {
+    promptChars: prompt.length,
+    instructionsChars,
+    bootstrapPromptChars: renderedBootstrapPrompt.length,
+    sessionHandoffChars: sessionHandoffNote.length,
+    heartbeatPromptChars: renderedPrompt.length,
+  };
 
   const buildArgs = (resumeSessionId: string | null) => {
     const args = ["exec", "--json"];
@@ -346,6 +368,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
         }),
         env: redactEnvForLogs(env),
         prompt,
+        promptMetrics,
         context,
       });
     }
diff --git a/packages/adapters/codex-local/src/ui/build-config.ts b/packages/adapters/codex-local/src/ui/build-config.ts
index a5b834d3..7c8f0d9c 100644
--- a/packages/adapters/codex-local/src/ui/build-config.ts
+++ b/packages/adapters/codex-local/src/ui/build-config.ts
@@ -71,6 +71,7 @@ export function buildCodexLocalConfig(v: CreateConfigValues): Record<string, unk
   if (v.cwd) ac.cwd = v.cwd;
   if (v.instructionsFilePath) ac.instructionsFilePath = v.instructionsFilePath;
   if (v.promptTemplate) ac.promptTemplate = v.promptTemplate;
+  if (v.bootstrapPrompt) ac.bootstrapPromptTemplate = v.bootstrapPrompt;
   ac.model = v.model || DEFAULT_CODEX_LOCAL_MODEL;
   if (v.thinkingEffort) ac.modelReasoningEffort = v.thinkingEffort;
   ac.timeoutSec = 0;
diff --git a/packages/adapters/cursor-local/src/server/execute.ts b/packages/adapters/cursor-local/src/server/execute.ts
index 043c3ef1..9caf606b 100644
--- a/packages/adapters/cursor-local/src/server/execute.ts
+++ b/packages/adapters/cursor-local/src/server/execute.ts
@@ -17,6 +17,7 @@ import {
   listPaperclipSkillEntries,
   removeMaintainerOnlySkillSymlinks,
   renderTemplate,
+  joinPromptSections,
   runChildProcess,
 } from "@paperclipai/adapter-utils/server-utils";
 import { DEFAULT_CURSOR_LOCAL_MODEL } from "../index.js";
@@ -268,6 +269,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   const instructionsFilePath = asString(config.instructionsFilePath, "").trim();
   const instructionsDir = instructionsFilePath ? `${path.dirname(instructionsFilePath)}/` : "";
   let instructionsPrefix = "";
+  let instructionsChars = 0;
   if (instructionsFilePath) {
     try {
       const instructionsContents = await fs.readFile(instructionsFilePath, "utf8");
@@ -275,6 +277,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
         `${instructionsContents}\n\n` +
         `The above agent instructions were loaded from ${instructionsFilePath}. ` +
         `Resolve any relative file references from ${instructionsDir}.\n\n`;
+      instructionsChars = instructionsPrefix.length;
       await onLog(
         "stderr",
         `[paperclip] Loaded agent instructions file: ${instructionsFilePath}\n`,
@@ -307,7 +310,8 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     return notes;
   })();
 
-  const renderedPrompt = renderTemplate(promptTemplate, {
+  const bootstrapPromptTemplate = asString(config.bootstrapPromptTemplate, "");
+  const templateData = {
     agentId: agent.id,
     companyId: agent.companyId,
     runId,
@@ -315,9 +319,29 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     agent,
     run: { id: runId, source: "on_demand" },
     context,
-  });
+  };
+  const renderedPrompt = renderTemplate(promptTemplate, templateData);
+  const renderedBootstrapPrompt =
+    !sessionId && bootstrapPromptTemplate.trim().length > 0
+      ? renderTemplate(bootstrapPromptTemplate, templateData).trim()
+      : "";
+  const sessionHandoffNote = asString(context.paperclipSessionHandoffMarkdown, "").trim();
   const paperclipEnvNote = renderPaperclipEnvNote(env);
-  const prompt = `${instructionsPrefix}${paperclipEnvNote}${renderedPrompt}`;
+  const prompt = joinPromptSections([
+    instructionsPrefix,
+    renderedBootstrapPrompt,
+    sessionHandoffNote,
+    paperclipEnvNote,
+    renderedPrompt,
+  ]);
+  const promptMetrics = {
+    promptChars: prompt.length,
+    instructionsChars,
+    bootstrapPromptChars: renderedBootstrapPrompt.length,
+    sessionHandoffChars: sessionHandoffNote.length,
+    runtimeNoteChars: paperclipEnvNote.length,
+    heartbeatPromptChars: renderedPrompt.length,
+  };
 
   const buildArgs = (resumeSessionId: string | null) => {
     const args = ["-p", "--output-format", "stream-json", "--workspace", cwd];
@@ -340,6 +364,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
         commandArgs: args,
         env: redactEnvForLogs(env),
         prompt,
+        promptMetrics,
         context,
       });
     }
diff --git a/packages/adapters/cursor-local/src/ui/build-config.ts b/packages/adapters/cursor-local/src/ui/build-config.ts
index c7c21101..d64f9ee2 100644
--- a/packages/adapters/cursor-local/src/ui/build-config.ts
+++ b/packages/adapters/cursor-local/src/ui/build-config.ts
@@ -62,6 +62,7 @@ export function buildCursorLocalConfig(v: CreateConfigValues): Record<string, un
   if (v.cwd) ac.cwd = v.cwd;
   if (v.instructionsFilePath) ac.instructionsFilePath = v.instructionsFilePath;
   if (v.promptTemplate) ac.promptTemplate = v.promptTemplate;
+  if (v.bootstrapPrompt) ac.bootstrapPromptTemplate = v.bootstrapPrompt;
   ac.model = v.model || DEFAULT_CURSOR_LOCAL_MODEL;
   const mode = normalizeMode(v.thinkingEffort);
   if (mode) ac.mode = mode;
diff --git a/packages/adapters/gemini-local/src/server/execute.ts b/packages/adapters/gemini-local/src/server/execute.ts
index 2408b425..fc293066 100644
--- a/packages/adapters/gemini-local/src/server/execute.ts
+++ b/packages/adapters/gemini-local/src/server/execute.ts
@@ -13,6 +13,7 @@ import {
   ensureAbsoluteDirectory,
   ensureCommandResolvable,
   ensurePaperclipSkillSymlink,
+  joinPromptSections,
   ensurePathInEnv,
   listPaperclipSkillEntries,
   removeMaintainerOnlySkillSymlinks,
@@ -268,7 +269,8 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     return notes;
   })();
 
-  const renderedPrompt = renderTemplate(promptTemplate, {
+  const bootstrapPromptTemplate = asString(config.bootstrapPromptTemplate, "");
+  const templateData = {
     agentId: agent.id,
     companyId: agent.companyId,
     runId,
@@ -276,10 +278,31 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     agent,
     run: { id: runId, source: "on_demand" },
     context,
-  });
+  };
+  const renderedPrompt = renderTemplate(promptTemplate, templateData);
+  const renderedBootstrapPrompt =
+    !sessionId && bootstrapPromptTemplate.trim().length > 0
+      ? renderTemplate(bootstrapPromptTemplate, templateData).trim()
+      : "";
+  const sessionHandoffNote = asString(context.paperclipSessionHandoffMarkdown, "").trim();
   const paperclipEnvNote = renderPaperclipEnvNote(env);
   const apiAccessNote = renderApiAccessNote(env);
-  const prompt = `${instructionsPrefix}${paperclipEnvNote}${apiAccessNote}${renderedPrompt}`;
+  const prompt = joinPromptSections([
+    instructionsPrefix,
+    renderedBootstrapPrompt,
+    sessionHandoffNote,
+    paperclipEnvNote,
+    apiAccessNote,
+    renderedPrompt,
+  ]);
+  const promptMetrics = {
+    promptChars: prompt.length,
+    instructionsChars: instructionsPrefix.length,
+    bootstrapPromptChars: renderedBootstrapPrompt.length,
+    sessionHandoffChars: sessionHandoffNote.length,
+    runtimeNoteChars: paperclipEnvNote.length + apiAccessNote.length,
+    heartbeatPromptChars: renderedPrompt.length,
+  };
 
   const buildArgs = (resumeSessionId: string | null) => {
     const args = ["--output-format", "stream-json"];
@@ -309,6 +332,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
         )),
         env: redactEnvForLogs(env),
         prompt,
+        promptMetrics,
         context,
       });
     }
diff --git a/packages/adapters/gemini-local/src/ui/build-config.ts b/packages/adapters/gemini-local/src/ui/build-config.ts
index a1ec6ddc..5ce333a4 100644
--- a/packages/adapters/gemini-local/src/ui/build-config.ts
+++ b/packages/adapters/gemini-local/src/ui/build-config.ts
@@ -56,6 +56,7 @@ export function buildGeminiLocalConfig(v: CreateConfigValues): Record<string, un
   if (v.cwd) ac.cwd = v.cwd;
   if (v.instructionsFilePath) ac.instructionsFilePath = v.instructionsFilePath;
   if (v.promptTemplate) ac.promptTemplate = v.promptTemplate;
+  if (v.bootstrapPrompt) ac.bootstrapPromptTemplate = v.bootstrapPrompt;
   ac.model = v.model || DEFAULT_GEMINI_LOCAL_MODEL;
   ac.timeoutSec = 0;
   ac.graceSec = 15;
diff --git a/packages/adapters/opencode-local/src/server/execute.ts b/packages/adapters/opencode-local/src/server/execute.ts
index 970896af..06b5a99f 100644
--- a/packages/adapters/opencode-local/src/server/execute.ts
+++ b/packages/adapters/opencode-local/src/server/execute.ts
@@ -9,6 +9,7 @@ import {
   asStringArray,
   parseObject,
   buildPaperclipEnv,
+  joinPromptSections,
   redactEnvForLogs,
   ensureAbsoluteDirectory,
   ensureCommandResolvable,
@@ -233,7 +234,8 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     ];
   })();
 
-  const renderedPrompt = renderTemplate(promptTemplate, {
+  const bootstrapPromptTemplate = asString(config.bootstrapPromptTemplate, "");
+  const templateData = {
     agentId: agent.id,
     companyId: agent.companyId,
     runId,
@@ -241,8 +243,26 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     agent,
     run: { id: runId, source: "on_demand" },
     context,
-  });
-  const prompt = `${instructionsPrefix}${renderedPrompt}`;
+  };
+  const renderedPrompt = renderTemplate(promptTemplate, templateData);
+  const renderedBootstrapPrompt =
+    !sessionId && bootstrapPromptTemplate.trim().length > 0
+      ? renderTemplate(bootstrapPromptTemplate, templateData).trim()
+      : "";
+  const sessionHandoffNote = asString(context.paperclipSessionHandoffMarkdown, "").trim();
+  const prompt = joinPromptSections([
+    instructionsPrefix,
+    renderedBootstrapPrompt,
+    sessionHandoffNote,
+    renderedPrompt,
+  ]);
+  const promptMetrics = {
+    promptChars: prompt.length,
+    instructionsChars: instructionsPrefix.length,
+    bootstrapPromptChars: renderedBootstrapPrompt.length,
+    sessionHandoffChars: sessionHandoffNote.length,
+    heartbeatPromptChars: renderedPrompt.length,
+  };
 
   const buildArgs = (resumeSessionId: string | null) => {
     const args = ["run", "--format", "json"];
@@ -264,6 +284,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
         commandArgs: [...args, `<stdin prompt ${prompt.length} chars>`],
         env: redactEnvForLogs(env),
         prompt,
+        promptMetrics,
         context,
       });
     }
diff --git a/packages/adapters/opencode-local/src/ui/build-config.ts b/packages/adapters/opencode-local/src/ui/build-config.ts
index 3abfd6cd..0d425cf1 100644
--- a/packages/adapters/opencode-local/src/ui/build-config.ts
+++ b/packages/adapters/opencode-local/src/ui/build-config.ts
@@ -55,6 +55,7 @@ export function buildOpenCodeLocalConfig(v: CreateConfigValues): Record<string,
   if (v.cwd) ac.cwd = v.cwd;
   if (v.instructionsFilePath) ac.instructionsFilePath = v.instructionsFilePath;
   if (v.promptTemplate) ac.promptTemplate = v.promptTemplate;
+  if (v.bootstrapPrompt) ac.bootstrapPromptTemplate = v.bootstrapPrompt;
   if (v.model) ac.model = v.model;
   if (v.thinkingEffort) ac.variant = v.thinkingEffort;
   // OpenCode sessions can run until the CLI exits naturally; keep timeout disabled (0)
diff --git a/packages/adapters/pi-local/src/server/execute.ts b/packages/adapters/pi-local/src/server/execute.ts
index dfb1453b..810ec1ce 100644
--- a/packages/adapters/pi-local/src/server/execute.ts
+++ b/packages/adapters/pi-local/src/server/execute.ts
@@ -9,6 +9,7 @@ import {
   asStringArray,
   parseObject,
   buildPaperclipEnv,
+  joinPromptSections,
   redactEnvForLogs,
   ensureAbsoluteDirectory,
   ensureCommandResolvable,
@@ -270,7 +271,8 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     systemPromptExtension = promptTemplate;
   }
 
-  const renderedSystemPromptExtension = renderTemplate(systemPromptExtension, {
+  const bootstrapPromptTemplate = asString(config.bootstrapPromptTemplate, "");
+  const templateData = {
     agentId: agent.id,
     companyId: agent.companyId,
     runId,
@@ -278,18 +280,26 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     agent,
     run: { id: runId, source: "on_demand" },
     context,
-  });
-
-  // User prompt is simple - just the rendered prompt template without instructions
-  const userPrompt = renderTemplate(promptTemplate, {
-    agentId: agent.id,
-    companyId: agent.companyId,
-    runId,
-    company: { id: agent.companyId },
-    agent,
-    run: { id: runId, source: "on_demand" },
-    context,
-  });
+  };
+  const renderedSystemPromptExtension = renderTemplate(systemPromptExtension, templateData);
+  const renderedHeartbeatPrompt = renderTemplate(promptTemplate, templateData);
+  const renderedBootstrapPrompt =
+    !canResumeSession && bootstrapPromptTemplate.trim().length > 0
+      ? renderTemplate(bootstrapPromptTemplate, templateData).trim()
+      : "";
+  const sessionHandoffNote = asString(context.paperclipSessionHandoffMarkdown, "").trim();
+  const userPrompt = joinPromptSections([
+    renderedBootstrapPrompt,
+    sessionHandoffNote,
+    renderedHeartbeatPrompt,
+  ]);
+  const promptMetrics = {
+    systemPromptChars: renderedSystemPromptExtension.length,
+    promptChars: userPrompt.length,
+    bootstrapPromptChars: renderedBootstrapPrompt.length,
+    sessionHandoffChars: sessionHandoffNote.length,
+    heartbeatPromptChars: renderedHeartbeatPrompt.length,
+  };
 
   const commandNotes = (() => {
     if (!resolvedInstructionsFilePath) return [] as string[];
@@ -345,6 +355,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
         commandArgs: args,
         env: redactEnvForLogs(env),
         prompt: userPrompt,
+        promptMetrics,
         context,
       });
     }
diff --git a/packages/adapters/pi-local/src/ui/build-config.ts b/packages/adapters/pi-local/src/ui/build-config.ts
index f871019d..5748064e 100644
--- a/packages/adapters/pi-local/src/ui/build-config.ts
+++ b/packages/adapters/pi-local/src/ui/build-config.ts
@@ -48,6 +48,7 @@ export function buildPiLocalConfig(v: CreateConfigValues): Record<string, unknow
   if (v.cwd) ac.cwd = v.cwd;
   if (v.instructionsFilePath) ac.instructionsFilePath = v.instructionsFilePath;
   if (v.promptTemplate) ac.promptTemplate = v.promptTemplate;
+  if (v.bootstrapPrompt) ac.bootstrapPromptTemplate = v.bootstrapPrompt;
   if (v.model) ac.model = v.model;
   if (v.thinkingEffort) ac.thinking = v.thinkingEffort;
   
diff --git a/packages/shared/src/validators/agent.ts b/packages/shared/src/validators/agent.ts
index 8a0450cb..dae54754 100644
--- a/packages/shared/src/validators/agent.ts
+++ b/packages/shared/src/validators/agent.ts
@@ -78,6 +78,7 @@ export const wakeAgentSchema = z.object({
   reason: z.string().optional().nullable(),
   payload: z.record(z.unknown()).optional().nullable(),
   idempotencyKey: z.string().optional().nullable(),
+  forceFreshSession: z.boolean().optional().default(false),
 });
 
 export type WakeAgent = z.infer<typeof wakeAgentSchema>;
diff --git a/report/2026-03-13-08-46-token-optimization-implementation.md b/report/2026-03-13-08-46-token-optimization-implementation.md
new file mode 100644
index 00000000..9bee83ca
--- /dev/null
+++ b/report/2026-03-13-08-46-token-optimization-implementation.md
@@ -0,0 +1,40 @@
+# Token Optimization Implementation Report
+
+Implemented the token-optimization plan across heartbeat orchestration, issue context APIs, adapter prompt construction, skill exposure, and agent configuration UX.
+
+The main behavior changes are:
+
+- Heartbeat telemetry now normalizes sessioned local adapter usage as per-run deltas instead of blindly trusting cumulative session totals.
+- Timer and manual wakes now preserve task sessions by default; fresh sessions are forced only for explicit `forceFreshSession` wakes or new issue assignment wakes.
+- Heartbeat session rotation is now policy-driven in the control plane, with a handoff note injected when a session is compacted and restarted.
+- Paperclip issue context now has incremental APIs: `GET /api/agents/me/inbox-lite`, `GET /api/issues/:id/heartbeat-context`, and comment delta queries via `GET /api/issues/:id/comments?after=...&order=asc`.
+- The `paperclip` skill now teaches agents to use those compact/incremental APIs first, while keeping full-thread fetches as a cold-start fallback.
+- All local adapters now separate first-session bootstrap prompts from per-heartbeat prompt templates, and emit prompt size metrics in invocation metadata.
+- Adapter create flows now persist `bootstrapPromptTemplate` correctly.
+- The agent config UI now explains the difference between bootstrap prompts and heartbeat prompts and warns about prompt churn.
+- Runtime skill defaults now include `paperclip`, `para-memory-files`, and `paperclip-create-agent`. `create-agent-adapter` was moved to `.agents/skills/create-agent-adapter`.
+
+Files with the most important implementation work:
+
+- `server/src/services/heartbeat.ts`
+- `server/src/services/issues.ts`
+- `server/src/routes/issues.ts`
+- `server/src/routes/agents.ts`
+- `server/src/routes/access.ts`
+- `skills/paperclip/SKILL.md`
+- `packages/adapters/*/src/server/execute.ts`
+- `packages/adapters/*/src/ui/build-config.ts`
+- `ui/src/components/AgentConfigForm.tsx`
+
+Verification completed successfully:
+
+- `pnpm -r typecheck`
+- `pnpm test:run`
+- `pnpm build`
+
+While verifying, I also fixed two existing embedded-postgres typing mismatches so repo-wide `typecheck` and `build` pass again:
+
+- `packages/db/src/migration-runtime.ts`
+- `cli/src/commands/worktree.ts`
+
+Next useful follow-up is measuring the before/after effect in real runs now that telemetry is less misleading and prompt/session reuse behavior is consistent across adapters.
diff --git a/server/src/__tests__/heartbeat-workspace-session.test.ts b/server/src/__tests__/heartbeat-workspace-session.test.ts
index 650556d1..bca52142 100644
--- a/server/src/__tests__/heartbeat-workspace-session.test.ts
+++ b/server/src/__tests__/heartbeat-workspace-session.test.ts
@@ -93,16 +93,26 @@ describe("shouldResetTaskSessionForWake", () => {
     expect(shouldResetTaskSessionForWake({ wakeReason: "issue_assigned" })).toBe(true);
   });
 
-  it("resets session context on timer heartbeats", () => {
-    expect(shouldResetTaskSessionForWake({ wakeSource: "timer" })).toBe(true);
+  it("preserves session context on timer heartbeats", () => {
+    expect(shouldResetTaskSessionForWake({ wakeSource: "timer" })).toBe(false);
   });
 
-  it("resets session context on manual on-demand invokes", () => {
+  it("preserves session context on manual on-demand invokes by default", () => {
     expect(
       shouldResetTaskSessionForWake({
         wakeSource: "on_demand",
         wakeTriggerDetail: "manual",
       }),
+    ).toBe(false);
+  });
+
+  it("resets session context when a fresh session is explicitly requested", () => {
+    expect(
+      shouldResetTaskSessionForWake({
+        wakeSource: "on_demand",
+        wakeTriggerDetail: "manual",
+        forceFreshSession: true,
+      }),
     ).toBe(true);
   });
 
diff --git a/server/src/routes/access.ts b/server/src/routes/access.ts
index c13366ff..ee156091 100644
--- a/server/src/routes/access.ts
+++ b/server/src/routes/access.ts
@@ -97,7 +97,11 @@ function requestBaseUrl(req: Request) {
 
 function readSkillMarkdown(skillName: string): string | null {
   const normalized = skillName.trim().toLowerCase();
-  if (normalized !== "paperclip" && normalized !== "paperclip-create-agent")
+  if (
+    normalized !== "paperclip" &&
+    normalized !== "paperclip-create-agent" &&
+    normalized !== "para-memory-files"
+  )
     return null;
   const moduleDir = path.dirname(fileURLToPath(import.meta.url));
   const candidates = [
@@ -1610,6 +1614,10 @@ export function accessRoutes(
     res.json({
       skills: [
         { name: "paperclip", path: "/api/skills/paperclip" },
+        {
+          name: "para-memory-files",
+          path: "/api/skills/para-memory-files"
+        },
         {
           name: "paperclip-create-agent",
           path: "/api/skills/paperclip-create-agent"
diff --git a/server/src/routes/agents.ts b/server/src/routes/agents.ts
index b1b53759..6c60b644 100644
--- a/server/src/routes/agents.ts
+++ b/server/src/routes/agents.ts
@@ -575,6 +575,34 @@ export function agentRoutes(db: Db) {
     res.json({ ...agent, chainOfCommand });
   });
 
+  router.get("/agents/me/inbox-lite", async (req, res) => {
+    if (req.actor.type !== "agent" || !req.actor.agentId || !req.actor.companyId) {
+      res.status(401).json({ error: "Agent authentication required" });
+      return;
+    }
+
+    const issuesSvc = issueService(db);
+    const rows = await issuesSvc.list(req.actor.companyId, {
+      assigneeAgentId: req.actor.agentId,
+      status: "todo,in_progress,blocked",
+    });
+
+    res.json(
+      rows.map((issue) => ({
+        id: issue.id,
+        identifier: issue.identifier,
+        title: issue.title,
+        status: issue.status,
+        priority: issue.priority,
+        projectId: issue.projectId,
+        goalId: issue.goalId,
+        parentId: issue.parentId,
+        updatedAt: issue.updatedAt,
+        activeRun: issue.activeRun,
+      })),
+    );
+  });
+
   router.get("/agents/:id", async (req, res) => {
     const id = req.params.id as string;
     const agent = await svc.getById(id);
@@ -1275,6 +1303,7 @@ export function agentRoutes(db: Db) {
       contextSnapshot: {
         triggeredBy: req.actor.type,
         actorId: req.actor.type === "agent" ? req.actor.agentId : req.actor.userId,
+        forceFreshSession: req.body.forceFreshSession === true,
       },
     });
 
diff --git a/server/src/routes/issues.ts b/server/src/routes/issues.ts
index f02067a6..bc938910 100644
--- a/server/src/routes/issues.ts
+++ b/server/src/routes/issues.ts
@@ -314,6 +314,79 @@ export function issueRoutes(db: Db, storage: StorageService) {
     });
   });
 
+  router.get("/issues/:id/heartbeat-context", async (req, res) => {
+    const id = req.params.id as string;
+    const issue = await svc.getById(id);
+    if (!issue) {
+      res.status(404).json({ error: "Issue not found" });
+      return;
+    }
+    assertCompanyAccess(req, issue.companyId);
+
+    const wakeCommentId =
+      typeof req.query.wakeCommentId === "string" && req.query.wakeCommentId.trim().length > 0
+        ? req.query.wakeCommentId.trim()
+        : null;
+
+    const [ancestors, project, goal, commentCursor, wakeComment] = await Promise.all([
+      svc.getAncestors(issue.id),
+      issue.projectId ? projectsSvc.getById(issue.projectId) : null,
+      issue.goalId
+        ? goalsSvc.getById(issue.goalId)
+        : !issue.projectId
+          ? goalsSvc.getDefaultCompanyGoal(issue.companyId)
+          : null,
+      svc.getCommentCursor(issue.id),
+      wakeCommentId ? svc.getComment(wakeCommentId) : null,
+    ]);
+
+    res.json({
+      issue: {
+        id: issue.id,
+        identifier: issue.identifier,
+        title: issue.title,
+        description: issue.description,
+        status: issue.status,
+        priority: issue.priority,
+        projectId: issue.projectId,
+        goalId: goal?.id ?? issue.goalId,
+        parentId: issue.parentId,
+        assigneeAgentId: issue.assigneeAgentId,
+        assigneeUserId: issue.assigneeUserId,
+        updatedAt: issue.updatedAt,
+      },
+      ancestors: ancestors.map((ancestor) => ({
+        id: ancestor.id,
+        identifier: ancestor.identifier,
+        title: ancestor.title,
+        status: ancestor.status,
+        priority: ancestor.priority,
+      })),
+      project: project
+        ? {
+            id: project.id,
+            name: project.name,
+            status: project.status,
+            targetDate: project.targetDate,
+          }
+        : null,
+      goal: goal
+        ? {
+            id: goal.id,
+            title: goal.title,
+            status: goal.status,
+            level: goal.level,
+            parentId: goal.parentId,
+          }
+        : null,
+      commentCursor,
+      wakeComment:
+        wakeComment && wakeComment.issueId === issue.id
+          ? wakeComment
+          : null,
+    });
+  });
+
   router.post("/issues/:id/read", async (req, res) => {
     const id = req.params.id as string;
     const issue = await svc.getById(id);
@@ -791,7 +864,26 @@ export function issueRoutes(db: Db, storage: StorageService) {
       return;
     }
     assertCompanyAccess(req, issue.companyId);
-    const comments = await svc.listComments(id);
+    const afterCommentId =
+      typeof req.query.after === "string" && req.query.after.trim().length > 0
+        ? req.query.after.trim()
+        : typeof req.query.afterCommentId === "string" && req.query.afterCommentId.trim().length > 0
+          ? req.query.afterCommentId.trim()
+          : null;
+    const order =
+      typeof req.query.order === "string" && req.query.order.trim().toLowerCase() === "asc"
+        ? "asc"
+        : "desc";
+    const limitRaw =
+      typeof req.query.limit === "string" && req.query.limit.trim().length > 0
+        ? Number(req.query.limit)
+        : null;
+    const limit = limitRaw && Number.isFinite(limitRaw) && limitRaw > 0 ? Math.floor(limitRaw) : null;
+    const comments = await svc.listComments(id, {
+      afterCommentId,
+      order,
+      limit,
+    });
     res.json(comments);
   });
 
diff --git a/server/src/services/heartbeat.ts b/server/src/services/heartbeat.ts
index f0665c9a..1a9dba74 100644
--- a/server/src/services/heartbeat.ts
+++ b/server/src/services/heartbeat.ts
@@ -18,7 +18,7 @@ import { logger } from "../middleware/logger.js";
 import { publishLiveEvent } from "./live-events.js";
 import { getRunLogStore, type RunLogHandle } from "./run-log-store.js";
 import { getServerAdapter, runningProcesses } from "../adapters/index.js";
-import type { AdapterExecutionResult, AdapterInvocationMeta, AdapterSessionCodec } from "../adapters/index.js";
+import type { AdapterExecutionResult, AdapterInvocationMeta, AdapterSessionCodec, UsageSummary } from "../adapters/index.js";
 import { createLocalAgentJwt } from "../agent-auth-jwt.js";
 import { parseObject, asBoolean, asNumber, appendWithCap, MAX_EXCERPT_BYTES } from "../adapters/utils.js";
 import { costService } from "./costs.js";
@@ -47,6 +47,14 @@ const HEARTBEAT_MAX_CONCURRENT_RUNS_MAX = 10;
 const DEFERRED_WAKE_CONTEXT_KEY = "_paperclipWakeContext";
 const startLocksByAgent = new Map<string, Promise<void>>();
 const REPO_ONLY_CWD_SENTINEL = "/__paperclip_repo_only__";
+const SESSIONED_LOCAL_ADAPTERS = new Set([
+  "claude_local",
+  "codex_local",
+  "cursor",
+  "gemini_local",
+  "opencode_local",
+  "pi_local",
+]);
 
 const heartbeatRunListColumns = {
   id: heartbeatRuns.id,
@@ -117,6 +125,26 @@ interface WakeupOptions {
   contextSnapshot?: Record<string, unknown>;
 }
 
+type UsageTotals = {
+  inputTokens: number;
+  cachedInputTokens: number;
+  outputTokens: number;
+};
+
+type SessionCompactionPolicy = {
+  enabled: boolean;
+  maxSessionRuns: number;
+  maxRawInputTokens: number;
+  maxSessionAgeHours: number;
+};
+
+type SessionCompactionDecision = {
+  rotate: boolean;
+  reason: string | null;
+  handoffMarkdown: string | null;
+  previousRunId: string | null;
+};
+
 interface ParsedIssueAssigneeAdapterOverrides {
   adapterConfig: Record<string, unknown> | null;
   useProjectWorkspace: boolean | null;
@@ -142,6 +170,88 @@ function readNonEmptyString(value: unknown): string | null {
   return typeof value === "string" && value.trim().length > 0 ? value : null;
 }
 
+function normalizeUsageTotals(usage: UsageSummary | null | undefined): UsageTotals | null {
+  if (!usage) return null;
+  return {
+    inputTokens: Math.max(0, Math.floor(asNumber(usage.inputTokens, 0))),
+    cachedInputTokens: Math.max(0, Math.floor(asNumber(usage.cachedInputTokens, 0))),
+    outputTokens: Math.max(0, Math.floor(asNumber(usage.outputTokens, 0))),
+  };
+}
+
+function readRawUsageTotals(usageJson: unknown): UsageTotals | null {
+  const parsed = parseObject(usageJson);
+  if (Object.keys(parsed).length === 0) return null;
+
+  const inputTokens = Math.max(
+    0,
+    Math.floor(asNumber(parsed.rawInputTokens, asNumber(parsed.inputTokens, 0))),
+  );
+  const cachedInputTokens = Math.max(
+    0,
+    Math.floor(asNumber(parsed.rawCachedInputTokens, asNumber(parsed.cachedInputTokens, 0))),
+  );
+  const outputTokens = Math.max(
+    0,
+    Math.floor(asNumber(parsed.rawOutputTokens, asNumber(parsed.outputTokens, 0))),
+  );
+
+  if (inputTokens <= 0 && cachedInputTokens <= 0 && outputTokens <= 0) {
+    return null;
+  }
+
+  return {
+    inputTokens,
+    cachedInputTokens,
+    outputTokens,
+  };
+}
+
+function deriveNormalizedUsageDelta(current: UsageTotals | null, previous: UsageTotals | null): UsageTotals | null {
+  if (!current) return null;
+  if (!previous) return { ...current };
+
+  const inputTokens = current.inputTokens >= previous.inputTokens
+    ? current.inputTokens - previous.inputTokens
+    : current.inputTokens;
+  const cachedInputTokens = current.cachedInputTokens >= previous.cachedInputTokens
+    ? current.cachedInputTokens - previous.cachedInputTokens
+    : current.cachedInputTokens;
+  const outputTokens = current.outputTokens >= previous.outputTokens
+    ? current.outputTokens - previous.outputTokens
+    : current.outputTokens;
+
+  return {
+    inputTokens: Math.max(0, inputTokens),
+    cachedInputTokens: Math.max(0, cachedInputTokens),
+    outputTokens: Math.max(0, outputTokens),
+  };
+}
+
+function formatCount(value: number | null | undefined) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return "0";
+  return value.toLocaleString("en-US");
+}
+
+function parseSessionCompactionPolicy(agent: typeof agents.$inferSelect): SessionCompactionPolicy {
+  const runtimeConfig = parseObject(agent.runtimeConfig);
+  const heartbeat = parseObject(runtimeConfig.heartbeat);
+  const compaction = parseObject(
+    heartbeat.sessionCompaction ?? heartbeat.sessionRotation ?? runtimeConfig.sessionCompaction,
+  );
+  const supportsSessions = SESSIONED_LOCAL_ADAPTERS.has(agent.adapterType);
+  const enabled = compaction.enabled === undefined
+    ? supportsSessions
+    : asBoolean(compaction.enabled, supportsSessions);
+
+  return {
+    enabled,
+    maxSessionRuns: Math.max(0, Math.floor(asNumber(compaction.maxSessionRuns, 200))),
+    maxRawInputTokens: Math.max(0, Math.floor(asNumber(compaction.maxRawInputTokens, 2_000_000))),
+    maxSessionAgeHours: Math.max(0, Math.floor(asNumber(compaction.maxSessionAgeHours, 72))),
+  };
+}
+
 export function resolveRuntimeSessionParamsForWorkspace(input: {
   agentId: string;
   previousSessionParams: Record<string, unknown> | null;
@@ -246,29 +356,20 @@ function deriveTaskKey(
 export function shouldResetTaskSessionForWake(
   contextSnapshot: Record<string, unknown> | null | undefined,
 ) {
+  if (contextSnapshot?.forceFreshSession === true) return true;
+
   const wakeReason = readNonEmptyString(contextSnapshot?.wakeReason);
   if (wakeReason === "issue_assigned") return true;
-
-  const wakeSource = readNonEmptyString(contextSnapshot?.wakeSource);
-  if (wakeSource === "timer") return true;
-
-  const wakeTriggerDetail = readNonEmptyString(contextSnapshot?.wakeTriggerDetail);
-  return wakeSource === "on_demand" && wakeTriggerDetail === "manual";
+  return false;
 }
 
 function describeSessionResetReason(
   contextSnapshot: Record<string, unknown> | null | undefined,
 ) {
+  if (contextSnapshot?.forceFreshSession === true) return "forceFreshSession was requested";
+
   const wakeReason = readNonEmptyString(contextSnapshot?.wakeReason);
   if (wakeReason === "issue_assigned") return "wake reason is issue_assigned";
-
-  const wakeSource = readNonEmptyString(contextSnapshot?.wakeSource);
-  if (wakeSource === "timer") return "wake source is timer";
-
-  const wakeTriggerDetail = readNonEmptyString(contextSnapshot?.wakeTriggerDetail);
-  if (wakeSource === "on_demand" && wakeTriggerDetail === "manual") {
-    return "this is a manual invoke";
-  }
   return null;
 }
 
@@ -501,6 +602,159 @@ export function heartbeatService(db: Db) {
       .then((rows) => rows[0] ?? null);
   }
 
+  async function getLatestRunForSession(
+    agentId: string,
+    sessionId: string,
+    opts?: { excludeRunId?: string | null },
+  ) {
+    const conditions = [
+      eq(heartbeatRuns.agentId, agentId),
+      eq(heartbeatRuns.sessionIdAfter, sessionId),
+    ];
+    if (opts?.excludeRunId) {
+      conditions.push(sql`${heartbeatRuns.id} <> ${opts.excludeRunId}`);
+    }
+    return db
+      .select()
+      .from(heartbeatRuns)
+      .where(and(...conditions))
+      .orderBy(desc(heartbeatRuns.createdAt))
+      .limit(1)
+      .then((rows) => rows[0] ?? null);
+  }
+
+  async function resolveNormalizedUsageForSession(input: {
+    agentId: string;
+    runId: string;
+    sessionId: string | null;
+    rawUsage: UsageTotals | null;
+  }) {
+    const { agentId, runId, sessionId, rawUsage } = input;
+    if (!sessionId || !rawUsage) {
+      return {
+        normalizedUsage: rawUsage,
+        previousRawUsage: null as UsageTotals | null,
+        derivedFromSessionTotals: false,
+      };
+    }
+
+    const previousRun = await getLatestRunForSession(agentId, sessionId, { excludeRunId: runId });
+    const previousRawUsage = readRawUsageTotals(previousRun?.usageJson);
+    return {
+      normalizedUsage: deriveNormalizedUsageDelta(rawUsage, previousRawUsage),
+      previousRawUsage,
+      derivedFromSessionTotals: previousRawUsage !== null,
+    };
+  }
+
+  async function evaluateSessionCompaction(input: {
+    agent: typeof agents.$inferSelect;
+    sessionId: string | null;
+    issueId: string | null;
+  }): Promise<SessionCompactionDecision> {
+    const { agent, sessionId, issueId } = input;
+    if (!sessionId) {
+      return {
+        rotate: false,
+        reason: null,
+        handoffMarkdown: null,
+        previousRunId: null,
+      };
+    }
+
+    const policy = parseSessionCompactionPolicy(agent);
+    if (!policy.enabled) {
+      return {
+        rotate: false,
+        reason: null,
+        handoffMarkdown: null,
+        previousRunId: null,
+      };
+    }
+
+    const runs = await db
+      .select({
+        id: heartbeatRuns.id,
+        createdAt: heartbeatRuns.createdAt,
+        usageJson: heartbeatRuns.usageJson,
+        resultJson: heartbeatRuns.resultJson,
+        error: heartbeatRuns.error,
+      })
+      .from(heartbeatRuns)
+      .where(and(eq(heartbeatRuns.agentId, agent.id), eq(heartbeatRuns.sessionIdAfter, sessionId)))
+      .orderBy(desc(heartbeatRuns.createdAt))
+      .limit(Math.max(policy.maxSessionRuns + 1, 4));
+
+    if (runs.length === 0) {
+      return {
+        rotate: false,
+        reason: null,
+        handoffMarkdown: null,
+        previousRunId: null,
+      };
+    }
+
+    const latestRun = runs[0] ?? null;
+    const oldestRun = runs[runs.length - 1] ?? latestRun;
+    const latestRawUsage = readRawUsageTotals(latestRun?.usageJson);
+    const sessionAgeHours =
+      latestRun && oldestRun
+        ? Math.max(
+            0,
+            (new Date(latestRun.createdAt).getTime() - new Date(oldestRun.createdAt).getTime()) / (1000 * 60 * 60),
+          )
+        : 0;
+
+    let reason: string | null = null;
+    if (policy.maxSessionRuns > 0 && runs.length > policy.maxSessionRuns) {
+      reason = `session exceeded ${policy.maxSessionRuns} runs`;
+    } else if (
+      policy.maxRawInputTokens > 0 &&
+      latestRawUsage &&
+      latestRawUsage.inputTokens >= policy.maxRawInputTokens
+    ) {
+      reason =
+        `session raw input reached ${formatCount(latestRawUsage.inputTokens)} tokens ` +
+        `(threshold ${formatCount(policy.maxRawInputTokens)})`;
+    } else if (policy.maxSessionAgeHours > 0 && sessionAgeHours >= policy.maxSessionAgeHours) {
+      reason = `session age reached ${Math.floor(sessionAgeHours)} hours`;
+    }
+
+    if (!reason || !latestRun) {
+      return {
+        rotate: false,
+        reason: null,
+        handoffMarkdown: null,
+        previousRunId: latestRun?.id ?? null,
+      };
+    }
+
+    const latestSummary = summarizeHeartbeatRunResultJson(latestRun.resultJson);
+    const latestTextSummary =
+      readNonEmptyString(latestSummary?.summary) ??
+      readNonEmptyString(latestSummary?.result) ??
+      readNonEmptyString(latestSummary?.message) ??
+      readNonEmptyString(latestRun.error);
+
+    const handoffMarkdown = [
+      "Paperclip session handoff:",
+      `- Previous session: ${sessionId}`,
+      issueId ? `- Issue: ${issueId}` : "",
+      `- Rotation reason: ${reason}`,
+      latestTextSummary ? `- Last run summary: ${latestTextSummary}` : "",
+      "Continue from the current task state. Rebuild only the minimum context you need.",
+    ]
+      .filter(Boolean)
+      .join("\n");
+
+    return {
+      rotate: true,
+      reason,
+      handoffMarkdown,
+      previousRunId: latestRun.id,
+    };
+  }
+
   async function resolveSessionBeforeForWakeup(
     agent: typeof agents.$inferSelect,
     taskKey: string | null,
@@ -1016,9 +1270,10 @@ export function heartbeatService(db: Db) {
     run: typeof heartbeatRuns.$inferSelect,
     result: AdapterExecutionResult,
     session: { legacySessionId: string | null },
+    normalizedUsage?: UsageTotals | null,
   ) {
     await ensureRuntimeState(agent);
-    const usage = result.usage;
+    const usage = normalizedUsage ?? normalizeUsageTotals(result.usage);
     const inputTokens = usage?.inputTokens ?? 0;
     const outputTokens = usage?.outputTokens ?? 0;
     const cachedInputTokens = usage?.cachedInputTokens ?? 0;
@@ -1270,15 +1525,42 @@ export function heartbeatService(db: Db) {
       context.projectId = executionWorkspace.projectId;
     }
     const runtimeSessionFallback = taskKey || resetTaskSession ? null : runtime.sessionId;
-    const previousSessionDisplayId = truncateDisplayId(
+    let previousSessionDisplayId = truncateDisplayId(
       taskSessionForRun?.sessionDisplayId ??
         (sessionCodec.getDisplayId ? sessionCodec.getDisplayId(runtimeSessionParams) : null) ??
         readNonEmptyString(runtimeSessionParams?.sessionId) ??
         runtimeSessionFallback,
     );
+    let runtimeSessionIdForAdapter =
+      readNonEmptyString(runtimeSessionParams?.sessionId) ?? runtimeSessionFallback;
+    let runtimeSessionParamsForAdapter = runtimeSessionParams;
+
+    const sessionCompaction = await evaluateSessionCompaction({
+      agent,
+      sessionId: previousSessionDisplayId ?? runtimeSessionIdForAdapter,
+      issueId,
+    });
+    if (sessionCompaction.rotate) {
+      context.paperclipSessionHandoffMarkdown = sessionCompaction.handoffMarkdown;
+      context.paperclipSessionRotationReason = sessionCompaction.reason;
+      context.paperclipPreviousSessionId = previousSessionDisplayId ?? runtimeSessionIdForAdapter;
+      runtimeSessionIdForAdapter = null;
+      runtimeSessionParamsForAdapter = null;
+      previousSessionDisplayId = null;
+      if (sessionCompaction.reason) {
+        runtimeWorkspaceWarnings.push(
+          `Starting a fresh session because ${sessionCompaction.reason}.`,
+        );
+      }
+    } else {
+      delete context.paperclipSessionHandoffMarkdown;
+      delete context.paperclipSessionRotationReason;
+      delete context.paperclipPreviousSessionId;
+    }
+
     const runtimeForAdapter = {
-      sessionId: readNonEmptyString(runtimeSessionParams?.sessionId) ?? runtimeSessionFallback,
-      sessionParams: runtimeSessionParams,
+      sessionId: runtimeSessionIdForAdapter,
+      sessionParams: runtimeSessionParamsForAdapter,
       sessionDisplayId: previousSessionDisplayId,
       taskKey,
     };
@@ -1522,6 +1804,14 @@ export function heartbeatService(db: Db) {
         previousDisplayId: runtimeForAdapter.sessionDisplayId,
         previousLegacySessionId: runtimeForAdapter.sessionId,
       });
+      const rawUsage = normalizeUsageTotals(adapterResult.usage);
+      const sessionUsageResolution = await resolveNormalizedUsageForSession({
+        agentId: agent.id,
+        runId: run.id,
+        sessionId: nextSessionState.displayId ?? nextSessionState.legacySessionId,
+        rawUsage,
+      });
+      const normalizedUsage = sessionUsageResolution.normalizedUsage;
 
       let outcome: "succeeded" | "failed" | "cancelled" | "timed_out";
       const latestRun = await getRun(run.id);
@@ -1550,9 +1840,23 @@ export function heartbeatService(db: Db) {
               : "failed";
 
       const usageJson =
-        adapterResult.usage || adapterResult.costUsd != null
+        normalizedUsage || adapterResult.costUsd != null
           ? ({
-              ...(adapterResult.usage ?? {}),
+              ...(normalizedUsage ?? {}),
+              ...(rawUsage ? {
+                rawInputTokens: rawUsage.inputTokens,
+                rawCachedInputTokens: rawUsage.cachedInputTokens,
+                rawOutputTokens: rawUsage.outputTokens,
+              } : {}),
+              ...(sessionUsageResolution.derivedFromSessionTotals ? { usageSource: "session_delta" } : {}),
+              ...((nextSessionState.displayId ?? nextSessionState.legacySessionId)
+                ? { persistedSessionId: nextSessionState.displayId ?? nextSessionState.legacySessionId }
+                : {}),
+              sessionReused: runtimeForAdapter.sessionId != null || runtimeForAdapter.sessionDisplayId != null,
+              taskSessionReused: taskSessionForRun != null,
+              freshSession: runtimeForAdapter.sessionId == null && runtimeForAdapter.sessionDisplayId == null,
+              sessionRotated: sessionCompaction.rotate,
+              sessionRotationReason: sessionCompaction.reason,
               ...(adapterResult.costUsd != null ? { costUsd: adapterResult.costUsd } : {}),
               ...(adapterResult.billingType ? { billingType: adapterResult.billingType } : {}),
             } as Record<string, unknown>)
@@ -1609,7 +1913,7 @@ export function heartbeatService(db: Db) {
       if (finalizedRun) {
         await updateRuntimeState(agent, finalizedRun, adapterResult, {
           legacySessionId: nextSessionState.legacySessionId,
-        });
+        }, normalizedUsage);
         if (taskKey) {
           if (adapterResult.clearSession || (!nextSessionState.params && !nextSessionState.displayId)) {
             await clearTaskSessions(agent.companyId, agent.id, {
diff --git a/server/src/services/issues.ts b/server/src/services/issues.ts
index 807a97eb..d6f5a643 100644
--- a/server/src/services/issues.ts
+++ b/server/src/services/issues.ts
@@ -1060,13 +1060,70 @@ export function issueService(db: Db) {
         .returning()
         .then((rows) => rows[0] ?? null),
 
-    listComments: (issueId: string) =>
-      db
+    listComments: async (
+      issueId: string,
+      opts?: {
+        afterCommentId?: string | null;
+        order?: "asc" | "desc";
+        limit?: number | null;
+      },
+    ) => {
+      const order = opts?.order === "asc" ? "asc" : "desc";
+      const afterCommentId = opts?.afterCommentId?.trim() || null;
+      const limit = opts?.limit && opts.limit > 0 ? Math.floor(opts.limit) : null;
+
+      const conditions = [eq(issueComments.issueId, issueId)];
+      if (afterCommentId) {
+        const anchor = await db
+          .select({
+            id: issueComments.id,
+            createdAt: issueComments.createdAt,
+          })
+          .from(issueComments)
+          .where(and(eq(issueComments.issueId, issueId), eq(issueComments.id, afterCommentId)))
+          .then((rows) => rows[0] ?? null);
+
+        if (!anchor) return [];
+        conditions.push(
+          sql<boolean>`(${issueComments.createdAt} > ${anchor.createdAt} OR (${issueComments.createdAt} = ${anchor.createdAt} AND ${issueComments.id} <> ${anchor.id}))`,
+        );
+      }
+
+      const query = db
         .select()
         .from(issueComments)
+        .where(and(...conditions))
+        .orderBy(order === "asc" ? asc(issueComments.createdAt) : desc(issueComments.createdAt));
+
+      const comments = limit ? await query.limit(limit) : await query;
+      return comments.map(redactIssueComment);
+    },
+
+    getCommentCursor: async (issueId: string) => {
+      const latest = await db
+        .select({
+          latestCommentId: issueComments.id,
+          latestCommentAt: issueComments.createdAt,
+        })
+        .from(issueComments)
         .where(eq(issueComments.issueId, issueId))
-        .orderBy(desc(issueComments.createdAt))
-        .then((comments) => comments.map(redactIssueComment)),
+        .orderBy(desc(issueComments.createdAt), desc(issueComments.id))
+        .limit(1)
+        .then((rows) => rows[0] ?? null);
+
+      const [{ totalComments }] = await db
+        .select({
+          totalComments: sql<number>`count(*)::int`,
+        })
+        .from(issueComments)
+        .where(eq(issueComments.issueId, issueId));
+
+      return {
+        totalComments: Number(totalComments ?? 0),
+        latestCommentId: latest?.latestCommentId ?? null,
+        latestCommentAt: latest?.latestCommentAt ?? null,
+      };
+    },
 
     getComment: (commentId: string) =>
       db
diff --git a/skills/paperclip/SKILL.md b/skills/paperclip/SKILL.md
index d1858ee6..928e3bc1 100644
--- a/skills/paperclip/SKILL.md
+++ b/skills/paperclip/SKILL.md
@@ -35,7 +35,7 @@ Follow these steps every time you wake up:
   - add a markdown comment explaining why it remains open and what happens next.
     Always include links to the approval and issue in that comment.
 
-**Step 3 — Get assignments.** `GET /api/companies/{companyId}/issues?assigneeAgentId={your-agent-id}&status=todo,in_progress,blocked`. Results sorted by priority. This is your inbox.
+**Step 3 — Get assignments.** Prefer `GET /api/agents/me/inbox-lite` for the normal heartbeat inbox. It returns the compact assignment list you need for prioritization. Fall back to `GET /api/companies/{companyId}/issues?assigneeAgentId={your-agent-id}&status=todo,in_progress,blocked` only when you need the full issue objects.
 
 **Step 4 — Pick work (with mention exception).** Work on `in_progress` first, then `todo`. Skip `blocked` unless you can unblock it.
 **Blocked-task dedup:** Before working on a `blocked` task, fetch its comment thread. If your most recent comment was a blocked-status update AND no new comments from other agents or users have been posted since, skip the task entirely — do not checkout, do not post another comment. Exit the heartbeat (or move to the next task) instead. Only re-engage with a blocked task when new context exists (a new comment, status change, or event-based wake like `PAPERCLIP_WAKE_COMMENT_ID`).
@@ -56,8 +56,15 @@ Headers: Authorization: Bearer $PAPERCLIP_API_KEY, X-Paperclip-Run-Id: $PAPERCLI
 
 If already checked out by you, returns normally. If owned by another agent: `409 Conflict` — stop, pick a different task. **Never retry a 409.**
 
-**Step 6 — Understand context.** `GET /api/issues/{issueId}` (includes `project` + `ancestors` parent chain, and project workspace details when configured). `GET /api/issues/{issueId}/comments`. Read ancestors to understand _why_ this task exists.
-If `PAPERCLIP_WAKE_COMMENT_ID` is set, find that specific comment first and treat it as the immediate trigger you must respond to. Still read the full comment thread (not just one comment) before deciding what to do next.
+**Step 6 — Understand context.** Prefer `GET /api/issues/{issueId}/heartbeat-context` first. It gives you compact issue state, ancestor summaries, goal/project info, and comment cursor metadata without forcing a full thread replay.
+
+Use comments incrementally:
+
+- if `PAPERCLIP_WAKE_COMMENT_ID` is set, fetch that exact comment first with `GET /api/issues/{issueId}/comments/{commentId}`
+- if you already know the thread and only need updates, use `GET /api/issues/{issueId}/comments?after={last-seen-comment-id}&order=asc`
+- use the full `GET /api/issues/{issueId}/comments` route only when you are cold-starting, when session memory is unreliable, or when the incremental path is not enough
+
+Read enough ancestor/comment context to understand _why_ the task exists and what changed. Do not reflexively reload the whole thread on every heartbeat.
 
 **Step 7 — Do the work.** Use your tools and capabilities.
 
@@ -226,10 +233,13 @@ PATCH /api/agents/{agentId}/instructions-path
 | Action                                | Endpoint                                                                                   |
 | ------------------------------------- | ------------------------------------------------------------------------------------------ |
 | My identity                           | `GET /api/agents/me`                                                                       |
+| My compact inbox                      | `GET /api/agents/me/inbox-lite`                                                            |
 | My assignments                        | `GET /api/companies/:companyId/issues?assigneeAgentId=:id&status=todo,in_progress,blocked` |
 | Checkout task                         | `POST /api/issues/:issueId/checkout`                                                       |
 | Get task + ancestors                  | `GET /api/issues/:issueId`                                                                 |
+| Get compact heartbeat context         | `GET /api/issues/:issueId/heartbeat-context`                                               |
 | Get comments                          | `GET /api/issues/:issueId/comments`                                                        |
+| Get comment delta                     | `GET /api/issues/:issueId/comments?after=:commentId&order=asc`                             |
 | Get specific comment                  | `GET /api/issues/:issueId/comments/:commentId`                                             |
 | Update task                           | `PATCH /api/issues/:issueId` (optional `comment` field)                                    |
 | Add comment                           | `POST /api/issues/:issueId/comments`                                                       |
diff --git a/ui/src/components/AgentConfigForm.tsx b/ui/src/components/AgentConfigForm.tsx
index 5f92a588..abfc04fb 100644
--- a/ui/src/components/AgentConfigForm.tsx
+++ b/ui/src/components/AgentConfigForm.tsx
@@ -444,23 +444,28 @@ export function AgentConfigForm(props: AgentConfigFormProps) {
               />
             </Field>
             {isLocal && (
-              <Field label="Prompt Template" hint={help.promptTemplate}>
-                <MarkdownEditor
-                  value={eff(
-                    "adapterConfig",
-                    "promptTemplate",
-                    String(config.promptTemplate ?? ""),
-                  )}
-                  onChange={(v) => mark("adapterConfig", "promptTemplate", v ?? "")}
-                  placeholder="You are agent {{ agent.name }}. Your role is {{ agent.role }}..."
-                  contentClassName="min-h-[88px] text-sm font-mono"
-                  imageUploadHandler={async (file) => {
-                    const namespace = `agents/${props.agent.id}/prompt-template`;
-                    const asset = await uploadMarkdownImage.mutateAsync({ file, namespace });
-                    return asset.contentPath;
-                  }}
-                />
-              </Field>
+              <>
+                <Field label="Prompt Template" hint={help.promptTemplate}>
+                  <MarkdownEditor
+                    value={eff(
+                      "adapterConfig",
+                      "promptTemplate",
+                      String(config.promptTemplate ?? ""),
+                    )}
+                    onChange={(v) => mark("adapterConfig", "promptTemplate", v ?? "")}
+                    placeholder="You are agent {{ agent.name }}. Your role is {{ agent.role }}..."
+                    contentClassName="min-h-[88px] text-sm font-mono"
+                    imageUploadHandler={async (file) => {
+                      const namespace = `agents/${props.agent.id}/prompt-template`;
+                      const asset = await uploadMarkdownImage.mutateAsync({ file, namespace });
+                      return asset.contentPath;
+                    }}
+                  />
+                </Field>
+                <div className="rounded-md border border-amber-500/25 bg-amber-500/10 px-3 py-2 text-xs text-amber-100">
+                  Prompt template is replayed on every heartbeat. Keep it compact and dynamic to avoid recurring token cost and cache churn.
+                </div>
+              </>
             )}
           </div>
         </div>
@@ -576,19 +581,24 @@ export function AgentConfigForm(props: AgentConfigFormProps) {
 
           {/* Prompt template (create mode only — edit mode shows this in Identity) */}
           {isLocal && isCreate && (
-            <Field label="Prompt Template" hint={help.promptTemplate}>
-              <MarkdownEditor
-                value={val!.promptTemplate}
-                onChange={(v) => set!({ promptTemplate: v })}
-                placeholder="You are agent {{ agent.name }}. Your role is {{ agent.role }}..."
-                contentClassName="min-h-[88px] text-sm font-mono"
-                imageUploadHandler={async (file) => {
-                  const namespace = "agents/drafts/prompt-template";
-                  const asset = await uploadMarkdownImage.mutateAsync({ file, namespace });
-                  return asset.contentPath;
-                }}
-              />
-            </Field>
+            <>
+              <Field label="Prompt Template" hint={help.promptTemplate}>
+                <MarkdownEditor
+                  value={val!.promptTemplate}
+                  onChange={(v) => set!({ promptTemplate: v })}
+                  placeholder="You are agent {{ agent.name }}. Your role is {{ agent.role }}..."
+                  contentClassName="min-h-[88px] text-sm font-mono"
+                  imageUploadHandler={async (file) => {
+                    const namespace = "agents/drafts/prompt-template";
+                    const asset = await uploadMarkdownImage.mutateAsync({ file, namespace });
+                    return asset.contentPath;
+                  }}
+                />
+              </Field>
+              <div className="rounded-md border border-amber-500/25 bg-amber-500/10 px-3 py-2 text-xs text-amber-100">
+                Prompt template is replayed on every heartbeat. Prefer small task framing and variables like <code>{"{{ context.* }}"}</code> or <code>{"{{ run.* }}"}</code>; avoid repeating stable instructions here.
+              </div>
+            </>
           )}
 
           {/* Adapter-specific fields */}
@@ -704,6 +714,9 @@ export function AgentConfigForm(props: AgentConfigFormProps) {
                   }}
                 />
               </Field>
+              <div className="rounded-md border border-sky-500/25 bg-sky-500/10 px-3 py-2 text-xs text-sky-100">
+                Bootstrap prompt is only sent for fresh sessions. Put stable setup, habits, and longer reusable guidance here. Frequent changes reduce the value of session reuse because new sessions must replay it.
+              </div>
               {adapterType === "claude_local" && (
                 <ClaudeLocalAdvancedFields {...adapterFieldProps} />
               )}
diff --git a/ui/src/components/agent-config-primitives.tsx b/ui/src/components/agent-config-primitives.tsx
index 77a5b14c..3384c366 100644
--- a/ui/src/components/agent-config-primitives.tsx
+++ b/ui/src/components/agent-config-primitives.tsx
@@ -26,7 +26,7 @@ export const help: Record<string, string> = {
   capabilities: "Describes what this agent can do. Shown in the org chart and used for task routing.",
   adapterType: "How this agent runs: local CLI (Claude/Codex/OpenCode), OpenClaw Gateway, spawned process, or generic HTTP webhook.",
   cwd: "Default working directory fallback for local adapters. Use an absolute path on the machine running Paperclip.",
-  promptTemplate: "The prompt sent to the agent on each heartbeat. Supports {{ agent.id }}, {{ agent.name }}, {{ agent.role }} variables.",
+  promptTemplate: "Sent on every heartbeat. Keep this small and dynamic. Use it for current-task framing, not large static instructions. Supports {{ agent.id }}, {{ agent.name }}, {{ agent.role }} and other template variables.",
   model: "Override the default model used by the adapter.",
   thinkingEffort: "Control model reasoning depth. Supported values vary by adapter/model.",
   chrome: "Enable Claude's Chrome integration by passing --chrome.",
@@ -44,7 +44,7 @@ export const help: Record<string, string> = {
   args: "Command-line arguments, comma-separated.",
   extraArgs: "Extra CLI arguments for local adapters, comma-separated.",
   envVars: "Environment variables injected into the adapter process. Use plain values or secret references.",
-  bootstrapPrompt: "Optional prompt prepended on the first run to bootstrap the agent's environment or habits.",
+  bootstrapPrompt: "Only sent when Paperclip starts a fresh session. Use this for stable setup guidance that should not be repeated on every heartbeat.",
   payloadTemplateJson: "Optional JSON merged into remote adapter request payloads before Paperclip adds its standard wake and workspace fields.",
   webhookUrl: "The URL that receives POST requests when the agent is invoked.",
   heartbeatInterval: "Run this agent automatically on a timer. Useful for periodic tasks like checking for new work.",

From 4a368f54d5de458081a352850d99d95fd0200ed1 Mon Sep 17 00:00:00 2001
From: Dotta <bippadotta@protonmail.com>
Date: Thu, 12 Mar 2026 14:37:30 -0500
Subject: [PATCH 16/28] Delay onboarding starter task creation until launch

Co-Authored-By: Paperclip <noreply@paperclip.ing>
---
 ui/src/components/OnboardingWizard.tsx | 64 ++++++++++++++------------
 1 file changed, 34 insertions(+), 30 deletions(-)

diff --git a/ui/src/components/OnboardingWizard.tsx b/ui/src/components/OnboardingWizard.tsx
index 5d166929..88e16d09 100644
--- a/ui/src/components/OnboardingWizard.tsx
+++ b/ui/src/components/OnboardingWizard.tsx
@@ -494,23 +494,41 @@ export function OnboardingWizard() {
   }
 
   async function handleStep3Next() {
+    if (!createdCompanyId || !createdAgentId) return;
+    setError(null);
+    setStep(4);
+  }
+
+  async function handleLaunch() {
     if (!createdCompanyId || !createdAgentId) return;
     setLoading(true);
     setError(null);
     try {
-      const issue = await issuesApi.create(createdCompanyId, {
-        title: taskTitle.trim(),
-        ...(taskDescription.trim()
-          ? { description: taskDescription.trim() }
-          : {}),
-        assigneeAgentId: createdAgentId,
-        status: "todo"
-      });
-      setCreatedIssueRef(issue.identifier ?? issue.id);
-      queryClient.invalidateQueries({
-        queryKey: queryKeys.issues.list(createdCompanyId)
-      });
-      setStep(4);
+      let issueRef = createdIssueRef;
+      if (!issueRef) {
+        const issue = await issuesApi.create(createdCompanyId, {
+          title: taskTitle.trim(),
+          ...(taskDescription.trim()
+            ? { description: taskDescription.trim() }
+            : {}),
+          assigneeAgentId: createdAgentId,
+          status: "todo"
+        });
+        issueRef = issue.identifier ?? issue.id;
+        setCreatedIssueRef(issueRef);
+        queryClient.invalidateQueries({
+          queryKey: queryKeys.issues.list(createdCompanyId)
+        });
+      }
+
+      setSelectedCompanyId(createdCompanyId);
+      reset();
+      closeOnboarding();
+      navigate(
+        createdCompanyPrefix
+          ? `/${createdCompanyPrefix}/issues/${issueRef}`
+          : `/issues/${issueRef}`
+      );
     } catch (err) {
       setError(err instanceof Error ? err.message : "Failed to create task");
     } finally {
@@ -518,20 +536,6 @@ export function OnboardingWizard() {
     }
   }
 
-  async function handleLaunch() {
-    if (!createdAgentId) return;
-    setLoading(true);
-    setError(null);
-    setLoading(false);
-    reset();
-    closeOnboarding();
-    if (createdCompanyPrefix) {
-      navigate(`/${createdCompanyPrefix}/dashboard`);
-      return;
-    }
-    navigate("/dashboard");
-  }
-
   function handleKeyDown(e: React.KeyboardEvent) {
     if (e.key === "Enter" && (e.metaKey || e.ctrlKey)) {
       e.preventDefault();
@@ -1175,8 +1179,8 @@ export function OnboardingWizard() {
                     <div>
                       <h3 className="font-medium">Ready to launch</h3>
                       <p className="text-xs text-muted-foreground">
-                        Everything is set up. Your assigned task already woke
-                        the agent, so you can jump straight to the issue.
+                        Everything is set up. Launching now will create the
+                        starter task, wake the agent, and open the issue.
                       </p>
                     </div>
                   </div>
@@ -1291,7 +1295,7 @@ export function OnboardingWizard() {
                       ) : (
                         <ArrowRight className="h-3.5 w-3.5 mr-1" />
                       )}
-                      {loading ? "Opening..." : "Open Issue"}
+                      {loading ? "Creating..." : "Create & Open Issue"}
                     </Button>
                   )}
                 </div>

From 2b9de934e3b31656c535d4dbe3092c29c87b6c74 Mon Sep 17 00:00:00 2001
From: Dotta <bippadotta@protonmail.com>
Date: Thu, 12 Mar 2026 16:04:28 -0500
Subject: [PATCH 17/28] Fix manual company switch route sync

Co-Authored-By: Paperclip <noreply@paperclip.ing>
---
 ui/src/components/Layout.tsx         | 11 ++++++++-
 ui/src/context/CompanyContext.tsx    |  3 +--
 ui/src/lib/company-selection.test.ts | 34 ++++++++++++++++++++++++++++
 ui/src/lib/company-selection.ts      | 18 +++++++++++++++
 4 files changed, 63 insertions(+), 3 deletions(-)
 create mode 100644 ui/src/lib/company-selection.test.ts
 create mode 100644 ui/src/lib/company-selection.ts

diff --git a/ui/src/components/Layout.tsx b/ui/src/components/Layout.tsx
index a90efa9a..e484b265 100644
--- a/ui/src/components/Layout.tsx
+++ b/ui/src/components/Layout.tsx
@@ -22,6 +22,7 @@ import { useTheme } from "../context/ThemeContext";
 import { useKeyboardShortcuts } from "../hooks/useKeyboardShortcuts";
 import { useCompanyPageMemory } from "../hooks/useCompanyPageMemory";
 import { healthApi } from "../api/health";
+import { shouldSyncCompanySelectionFromRoute } from "../lib/company-selection";
 import { queryKeys } from "../lib/queryKeys";
 import { cn } from "../lib/utils";
 import { NotFoundPage } from "../pages/NotFound";
@@ -36,6 +37,7 @@ export function Layout() {
     loading: companiesLoading,
     selectedCompany,
     selectedCompanyId,
+    selectionSource,
     setSelectedCompanyId,
   } = useCompany();
   const { theme, toggleTheme } = useTheme();
@@ -88,7 +90,13 @@ export function Layout() {
       return;
     }
 
-    if (selectedCompanyId !== matchedCompany.id) {
+    if (
+      shouldSyncCompanySelectionFromRoute({
+        selectionSource,
+        selectedCompanyId,
+        routeCompanyId: matchedCompany.id,
+      })
+    ) {
       setSelectedCompanyId(matchedCompany.id, { source: "route_sync" });
     }
   }, [
@@ -99,6 +107,7 @@ export function Layout() {
     location.pathname,
     location.search,
     navigate,
+    selectionSource,
     selectedCompanyId,
     setSelectedCompanyId,
   ]);
diff --git a/ui/src/context/CompanyContext.tsx b/ui/src/context/CompanyContext.tsx
index eafc7f55..fb074f33 100644
--- a/ui/src/context/CompanyContext.tsx
+++ b/ui/src/context/CompanyContext.tsx
@@ -12,8 +12,7 @@ import type { Company } from "@paperclipai/shared";
 import { companiesApi } from "../api/companies";
 import { ApiError } from "../api/client";
 import { queryKeys } from "../lib/queryKeys";
-
-type CompanySelectionSource = "manual" | "route_sync" | "bootstrap";
+import type { CompanySelectionSource } from "../lib/company-selection";
 type CompanySelectionOptions = { source?: CompanySelectionSource };
 
 interface CompanyContextValue {
diff --git a/ui/src/lib/company-selection.test.ts b/ui/src/lib/company-selection.test.ts
new file mode 100644
index 00000000..a8533a4b
--- /dev/null
+++ b/ui/src/lib/company-selection.test.ts
@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+import { shouldSyncCompanySelectionFromRoute } from "./company-selection";
+
+describe("shouldSyncCompanySelectionFromRoute", () => {
+  it("does not resync when selection already matches the route", () => {
+    expect(
+      shouldSyncCompanySelectionFromRoute({
+        selectionSource: "route_sync",
+        selectedCompanyId: "pap",
+        routeCompanyId: "pap",
+      }),
+    ).toBe(false);
+  });
+
+  it("defers route sync while a manual company switch is in flight", () => {
+    expect(
+      shouldSyncCompanySelectionFromRoute({
+        selectionSource: "manual",
+        selectedCompanyId: "pap",
+        routeCompanyId: "ret",
+      }),
+    ).toBe(false);
+  });
+
+  it("syncs back to the route company for non-manual mismatches", () => {
+    expect(
+      shouldSyncCompanySelectionFromRoute({
+        selectionSource: "route_sync",
+        selectedCompanyId: "pap",
+        routeCompanyId: "ret",
+      }),
+    ).toBe(true);
+  });
+});
diff --git a/ui/src/lib/company-selection.ts b/ui/src/lib/company-selection.ts
new file mode 100644
index 00000000..ce02cb4d
--- /dev/null
+++ b/ui/src/lib/company-selection.ts
@@ -0,0 +1,18 @@
+export type CompanySelectionSource = "manual" | "route_sync" | "bootstrap";
+
+export function shouldSyncCompanySelectionFromRoute(params: {
+  selectionSource: CompanySelectionSource;
+  selectedCompanyId: string | null;
+  routeCompanyId: string;
+}): boolean {
+  const { selectionSource, selectedCompanyId, routeCompanyId } = params;
+
+  if (selectedCompanyId === routeCompanyId) return false;
+
+  // Let manual company switches finish their remembered-path navigation first.
+  if (selectionSource === "manual" && selectedCompanyId) {
+    return false;
+  }
+
+  return true;
+}

From 6365e03731ba8f6c8d3a6d9f831112248e8f1bb6 Mon Sep 17 00:00:00 2001
From: Dotta <bippadotta@protonmail.com>
Date: Thu, 12 Mar 2026 16:11:37 -0500
Subject: [PATCH 18/28] feat: skip pre-filled assignee/project fields when
 tabbing in new issue dialog

When creating a new issue with a pre-filled assignee or project (e.g. from
a project page), Tab from the title field now skips over fields that already
have values, going directly to the next empty field or description.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
---
 ui/src/components/NewIssueDialog.tsx | 96 ++++++++++++++++++++--------
 1 file changed, 70 insertions(+), 26 deletions(-)

diff --git a/ui/src/components/NewIssueDialog.tsx b/ui/src/components/NewIssueDialog.tsx
index 01f210ed..c017306c 100644
--- a/ui/src/components/NewIssueDialog.tsx
+++ b/ui/src/components/NewIssueDialog.tsx
@@ -10,6 +10,11 @@ import { assetsApi } from "../api/assets";
 import { queryKeys } from "../lib/queryKeys";
 import { useProjectOrder } from "../hooks/useProjectOrder";
 import { getRecentAssigneeIds, sortAgentsByRecency, trackRecentAssignee } from "../lib/recent-assignees";
+import {
+  assigneeValueFromSelection,
+  currentUserAssigneeOption,
+  parseAssigneeValue,
+} from "../lib/assignees";
 import {
   Dialog,
   DialogContent,
@@ -63,7 +68,8 @@ interface IssueDraft {
   description: string;
   status: string;
   priority: string;
-  assigneeId: string;
+  assigneeValue: string;
+  assigneeId?: string;
   projectId: string;
   assigneeModelOverride: string;
   assigneeThinkingEffort: string;
@@ -173,7 +179,7 @@ export function NewIssueDialog() {
   const [description, setDescription] = useState("");
   const [status, setStatus] = useState("todo");
   const [priority, setPriority] = useState("");
-  const [assigneeId, setAssigneeId] = useState("");
+  const [assigneeValue, setAssigneeValue] = useState("");
   const [projectId, setProjectId] = useState("");
   const [assigneeOptionsOpen, setAssigneeOptionsOpen] = useState(false);
   const [assigneeModelOverride, setAssigneeModelOverride] = useState("");
@@ -220,7 +226,11 @@ export function NewIssueDialog() {
     userId: currentUserId,
   });
 
-  const assigneeAdapterType = (agents ?? []).find((agent) => agent.id === assigneeId)?.adapterType ?? null;
+  const selectedAssignee = useMemo(() => parseAssigneeValue(assigneeValue), [assigneeValue]);
+  const selectedAssigneeAgentId = selectedAssignee.assigneeAgentId;
+  const selectedAssigneeUserId = selectedAssignee.assigneeUserId;
+
+  const assigneeAdapterType = (agents ?? []).find((agent) => agent.id === selectedAssigneeAgentId)?.adapterType ?? null;
   const supportsAssigneeOverrides = Boolean(
     assigneeAdapterType && ISSUE_OVERRIDE_ADAPTER_TYPES.has(assigneeAdapterType),
   );
@@ -295,7 +305,7 @@ export function NewIssueDialog() {
       description,
       status,
       priority,
-      assigneeId,
+      assigneeValue,
       projectId,
       assigneeModelOverride,
       assigneeThinkingEffort,
@@ -307,7 +317,7 @@ export function NewIssueDialog() {
     description,
     status,
     priority,
-    assigneeId,
+    assigneeValue,
     projectId,
     assigneeModelOverride,
     assigneeThinkingEffort,
@@ -330,7 +340,7 @@ export function NewIssueDialog() {
       setStatus(newIssueDefaults.status ?? "todo");
       setPriority(newIssueDefaults.priority ?? "");
       setProjectId(newIssueDefaults.projectId ?? "");
-      setAssigneeId(newIssueDefaults.assigneeAgentId ?? "");
+      setAssigneeValue(assigneeValueFromSelection(newIssueDefaults));
       setAssigneeModelOverride("");
       setAssigneeThinkingEffort("");
       setAssigneeChrome(false);
@@ -340,7 +350,11 @@ export function NewIssueDialog() {
       setDescription(draft.description);
       setStatus(draft.status || "todo");
       setPriority(draft.priority);
-      setAssigneeId(newIssueDefaults.assigneeAgentId ?? draft.assigneeId);
+      setAssigneeValue(
+        newIssueDefaults.assigneeAgentId || newIssueDefaults.assigneeUserId
+          ? assigneeValueFromSelection(newIssueDefaults)
+          : (draft.assigneeValue ?? draft.assigneeId ?? ""),
+      );
       setProjectId(newIssueDefaults.projectId ?? draft.projectId);
       setAssigneeModelOverride(draft.assigneeModelOverride ?? "");
       setAssigneeThinkingEffort(draft.assigneeThinkingEffort ?? "");
@@ -350,7 +364,7 @@ export function NewIssueDialog() {
       setStatus(newIssueDefaults.status ?? "todo");
       setPriority(newIssueDefaults.priority ?? "");
       setProjectId(newIssueDefaults.projectId ?? "");
-      setAssigneeId(newIssueDefaults.assigneeAgentId ?? "");
+      setAssigneeValue(assigneeValueFromSelection(newIssueDefaults));
       setAssigneeModelOverride("");
       setAssigneeThinkingEffort("");
       setAssigneeChrome(false);
@@ -390,7 +404,7 @@ export function NewIssueDialog() {
     setDescription("");
     setStatus("todo");
     setPriority("");
-    setAssigneeId("");
+    setAssigneeValue("");
     setProjectId("");
     setAssigneeOptionsOpen(false);
     setAssigneeModelOverride("");
@@ -406,7 +420,7 @@ export function NewIssueDialog() {
   function handleCompanyChange(companyId: string) {
     if (companyId === effectiveCompanyId) return;
     setDialogCompanyId(companyId);
-    setAssigneeId("");
+    setAssigneeValue("");
     setProjectId("");
     setAssigneeModelOverride("");
     setAssigneeThinkingEffort("");
@@ -443,7 +457,8 @@ export function NewIssueDialog() {
       description: description.trim() || undefined,
       status,
       priority: priority || "medium",
-      ...(assigneeId ? { assigneeAgentId: assigneeId } : {}),
+      ...(selectedAssigneeAgentId ? { assigneeAgentId: selectedAssigneeAgentId } : {}),
+      ...(selectedAssigneeUserId ? { assigneeUserId: selectedAssigneeUserId } : {}),
       ...(projectId ? { projectId } : {}),
       ...(assigneeAdapterOverrides ? { assigneeAdapterOverrides } : {}),
       ...(executionWorkspaceSettings ? { executionWorkspaceSettings } : {}),
@@ -475,7 +490,9 @@ export function NewIssueDialog() {
   const hasDraft = title.trim().length > 0 || description.trim().length > 0;
   const currentStatus = statuses.find((s) => s.value === status) ?? statuses[1]!;
   const currentPriority = priorities.find((p) => p.value === priority);
-  const currentAssignee = (agents ?? []).find((a) => a.id === assigneeId);
+  const currentAssignee = selectedAssigneeAgentId
+    ? (agents ?? []).find((a) => a.id === selectedAssigneeAgentId)
+    : null;
   const currentProject = orderedProjects.find((project) => project.id === projectId);
   const currentProjectExecutionWorkspacePolicy = SHOW_EXPERIMENTAL_ISSUE_WORKTREE_UI
     ? currentProject?.executionWorkspacePolicy ?? null
@@ -497,16 +514,18 @@ export function NewIssueDialog() {
       : ISSUE_THINKING_EFFORT_OPTIONS.claude_local;
   const recentAssigneeIds = useMemo(() => getRecentAssigneeIds(), [newIssueOpen]);
   const assigneeOptions = useMemo<InlineEntityOption[]>(
-    () =>
-      sortAgentsByRecency(
+    () => [
+      ...currentUserAssigneeOption(currentUserId),
+      ...sortAgentsByRecency(
         (agents ?? []).filter((agent) => agent.status !== "terminated"),
         recentAssigneeIds,
       ).map((agent) => ({
-        id: agent.id,
+        id: assigneeValueFromSelection({ assigneeAgentId: agent.id }),
         label: agent.name,
         searchText: `${agent.name} ${agent.role} ${agent.title ?? ""}`,
       })),
-    [agents, recentAssigneeIds],
+    ],
+    [agents, currentUserId, recentAssigneeIds],
   );
   const projectOptions = useMemo<InlineEntityOption[]>(
     () =>
@@ -710,7 +729,16 @@ export function NewIssueDialog() {
               }
               if (e.key === "Tab" && !e.shiftKey) {
                 e.preventDefault();
-                assigneeSelectorRef.current?.focus();
+                if (assigneeValue) {
+                  // Assignee already set — skip to project or description
+                  if (projectId) {
+                    descriptionEditorRef.current?.focus();
+                  } else {
+                    projectSelectorRef.current?.focus();
+                  }
+                } else {
+                  assigneeSelectorRef.current?.focus();
+                }
               }
             }}
             autoFocus
@@ -723,33 +751,49 @@ export function NewIssueDialog() {
               <span>For</span>
               <InlineEntitySelector
                 ref={assigneeSelectorRef}
-                value={assigneeId}
+                value={assigneeValue}
                 options={assigneeOptions}
                 placeholder="Assignee"
                 disablePortal
                 noneLabel="No assignee"
                 searchPlaceholder="Search assignees..."
                 emptyMessage="No assignees found."
-                onChange={(id) => { if (id) trackRecentAssignee(id); setAssigneeId(id); }}
+                onChange={(value) => {
+                  const nextAssignee = parseAssigneeValue(value);
+                  if (nextAssignee.assigneeAgentId) {
+                    trackRecentAssignee(nextAssignee.assigneeAgentId);
+                  }
+                  setAssigneeValue(value);
+                }}
                 onConfirm={() => {
-                  projectSelectorRef.current?.focus();
+                  if (projectId) {
+                    descriptionEditorRef.current?.focus();
+                  } else {
+                    projectSelectorRef.current?.focus();
+                  }
                 }}
                 renderTriggerValue={(option) =>
-                  option && currentAssignee ? (
-                    <>
-                      <AgentIcon icon={currentAssignee.icon} className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />
+                  option ? (
+                    currentAssignee ? (
+                      <>
+                        <AgentIcon icon={currentAssignee.icon} className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />
+                        <span className="truncate">{option.label}</span>
+                      </>
+                    ) : (
                       <span className="truncate">{option.label}</span>
-                    </>
+                    )
                   ) : (
                     <span className="text-muted-foreground">Assignee</span>
                   )
                 }
                 renderOption={(option) => {
                   if (!option.id) return <span className="truncate">{option.label}</span>;
-                  const assignee = (agents ?? []).find((agent) => agent.id === option.id);
+                  const assignee = parseAssigneeValue(option.id).assigneeAgentId
+                    ? (agents ?? []).find((agent) => agent.id === parseAssigneeValue(option.id).assigneeAgentId)
+                    : null;
                   return (
                     <>
-                      <AgentIcon icon={assignee?.icon} className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />
+                      {assignee ? <AgentIcon icon={assignee.icon} className="h-3.5 w-3.5 shrink-0 text-muted-foreground" /> : null}
                       <span className="truncate">{option.label}</span>
                     </>
                   );

From 32ab4f8e47f55a983f056d6d438ea134ac22237a Mon Sep 17 00:00:00 2001
From: Dotta <bippadotta@protonmail.com>
Date: Thu, 12 Mar 2026 16:12:38 -0500
Subject: [PATCH 19/28] Add me and unassigned assignee options

Co-Authored-By: Paperclip <noreply@paperclip.ing>
---
 ui/src/components/IssueProperties.tsx |  29 +++---
 ui/src/components/IssuesList.tsx      | 123 ++++++++++++++++++++------
 ui/src/context/DialogContext.tsx      |   1 +
 ui/src/lib/assignees.test.ts          |  53 +++++++++++
 ui/src/lib/assignees.ts               |  51 +++++++++++
 ui/src/pages/IssueDetail.tsx          |   3 +-
 6 files changed, 219 insertions(+), 41 deletions(-)
 create mode 100644 ui/src/lib/assignees.test.ts
 create mode 100644 ui/src/lib/assignees.ts

diff --git a/ui/src/components/IssueProperties.tsx b/ui/src/components/IssueProperties.tsx
index ca8e1bd4..cf4b6a43 100644
--- a/ui/src/components/IssueProperties.tsx
+++ b/ui/src/components/IssueProperties.tsx
@@ -10,6 +10,7 @@ import { useCompany } from "../context/CompanyContext";
 import { queryKeys } from "../lib/queryKeys";
 import { useProjectOrder } from "../hooks/useProjectOrder";
 import { getRecentAssigneeIds, sortAgentsByRecency, trackRecentAssignee } from "../lib/recent-assignees";
+import { formatAssigneeUserLabel } from "../lib/assignees";
 import { StatusIcon } from "./StatusIcon";
 import { PriorityIcon } from "./PriorityIcon";
 import { Identity } from "./Identity";
@@ -206,14 +207,7 @@ export function IssueProperties({ issue, onUpdate, inline }: IssuePropertiesProp
   const assignee = issue.assigneeAgentId
     ? agents?.find((a) => a.id === issue.assigneeAgentId)
     : null;
-  const userLabel = (userId: string | null | undefined) =>
-    userId
-      ? userId === "local-board"
-        ? "Board"
-        : currentUserId && userId === currentUserId
-          ? "Me"
-          : userId.slice(0, 5)
-      : null;
+  const userLabel = (userId: string | null | undefined) => formatAssigneeUserLabel(userId, currentUserId);
   const assigneeUserLabel = userLabel(issue.assigneeUserId);
   const creatorUserLabel = userLabel(issue.createdByUserId);
 
@@ -349,7 +343,22 @@ export function IssueProperties({ issue, onUpdate, inline }: IssuePropertiesProp
         >
           No assignee
         </button>
-        {issue.createdByUserId && (
+        {currentUserId && (
+          <button
+            className={cn(
+              "flex items-center gap-2 w-full px-2 py-1.5 text-xs rounded hover:bg-accent/50",
+              issue.assigneeUserId === currentUserId && "bg-accent",
+            )}
+            onClick={() => {
+              onUpdate({ assigneeAgentId: null, assigneeUserId: currentUserId });
+              setAssigneeOpen(false);
+            }}
+          >
+            <User className="h-3 w-3 shrink-0 text-muted-foreground" />
+            Assign to me
+          </button>
+        )}
+        {issue.createdByUserId && issue.createdByUserId !== currentUserId && (
           <button
             className={cn(
               "flex items-center gap-2 w-full px-2 py-1.5 text-xs rounded hover:bg-accent/50",
@@ -361,7 +370,7 @@ export function IssueProperties({ issue, onUpdate, inline }: IssuePropertiesProp
             }}
           >
             <User className="h-3 w-3 shrink-0 text-muted-foreground" />
-            {creatorUserLabel ? `Assign to ${creatorUserLabel === "Me" ? "me" : creatorUserLabel}` : "Assign to requester"}
+            {creatorUserLabel ? `Assign to ${creatorUserLabel}` : "Assign to requester"}
           </button>
         )}
         {sortedAgents
diff --git a/ui/src/components/IssuesList.tsx b/ui/src/components/IssuesList.tsx
index 6899bd5c..442f8ae4 100644
--- a/ui/src/components/IssuesList.tsx
+++ b/ui/src/components/IssuesList.tsx
@@ -3,7 +3,9 @@ import { useQuery } from "@tanstack/react-query";
 import { useDialog } from "../context/DialogContext";
 import { useCompany } from "../context/CompanyContext";
 import { issuesApi } from "../api/issues";
+import { authApi } from "../api/auth";
 import { queryKeys } from "../lib/queryKeys";
+import { formatAssigneeUserLabel } from "../lib/assignees";
 import { groupBy } from "../lib/groupBy";
 import { formatDate, cn } from "../lib/utils";
 import { timeAgo } from "../lib/timeAgo";
@@ -87,11 +89,20 @@ function toggleInArray(arr: string[], value: string): string[] {
   return arr.includes(value) ? arr.filter((v) => v !== value) : [...arr, value];
 }
 
-function applyFilters(issues: Issue[], state: IssueViewState): Issue[] {
+function applyFilters(issues: Issue[], state: IssueViewState, currentUserId?: string | null): Issue[] {
   let result = issues;
   if (state.statuses.length > 0) result = result.filter((i) => state.statuses.includes(i.status));
   if (state.priorities.length > 0) result = result.filter((i) => state.priorities.includes(i.priority));
-  if (state.assignees.length > 0) result = result.filter((i) => i.assigneeAgentId != null && state.assignees.includes(i.assigneeAgentId));
+  if (state.assignees.length > 0) {
+    result = result.filter((issue) => {
+      for (const assignee of state.assignees) {
+        if (assignee === "__unassigned" && !issue.assigneeAgentId && !issue.assigneeUserId) return true;
+        if (assignee === "__me" && currentUserId && issue.assigneeUserId === currentUserId) return true;
+        if (issue.assigneeAgentId === assignee) return true;
+      }
+      return false;
+    });
+  }
   if (state.labels.length > 0) result = result.filter((i) => (i.labelIds ?? []).some((id) => state.labels.includes(id)));
   return result;
 }
@@ -165,6 +176,11 @@ export function IssuesList({
 }: IssuesListProps) {
   const { selectedCompanyId } = useCompany();
   const { openNewIssue } = useDialog();
+  const { data: session } = useQuery({
+    queryKey: queryKeys.auth.session,
+    queryFn: () => authApi.getSession(),
+  });
+  const currentUserId = session?.user?.id ?? session?.session?.userId ?? null;
 
   // Scope the storage key per company so folding/view state is independent across companies.
   const scopedKey = selectedCompanyId ? `${viewStateKey}:${selectedCompanyId}` : viewStateKey;
@@ -224,9 +240,9 @@ export function IssuesList({
 
   const filtered = useMemo(() => {
     const sourceIssues = normalizedIssueSearch.length > 0 ? searchedIssues : issues;
-    const filteredByControls = applyFilters(sourceIssues, viewState);
+    const filteredByControls = applyFilters(sourceIssues, viewState, currentUserId);
     return sortIssues(filteredByControls, viewState);
-  }, [issues, searchedIssues, viewState, normalizedIssueSearch]);
+  }, [issues, searchedIssues, viewState, normalizedIssueSearch, currentUserId]);
 
   const { data: labels } = useQuery({
     queryKey: queryKeys.issues.labels(selectedCompanyId!),
@@ -253,13 +269,21 @@ export function IssuesList({
         .map((p) => ({ key: p, label: statusLabel(p), items: groups[p]! }));
     }
     // assignee
-    const groups = groupBy(filtered, (i) => i.assigneeAgentId ?? "__unassigned");
+    const groups = groupBy(
+      filtered,
+      (issue) => issue.assigneeAgentId ?? (issue.assigneeUserId ? `__user:${issue.assigneeUserId}` : "__unassigned"),
+    );
     return Object.keys(groups).map((key) => ({
       key,
-      label: key === "__unassigned" ? "Unassigned" : (agentName(key) ?? key.slice(0, 8)),
+      label:
+        key === "__unassigned"
+          ? "Unassigned"
+          : key.startsWith("__user:")
+            ? (formatAssigneeUserLabel(key.slice("__user:".length), currentUserId) ?? "User")
+            : (agentName(key) ?? key.slice(0, 8)),
       items: groups[key]!,
     }));
-  }, [filtered, viewState.groupBy, agents]); // eslint-disable-line react-hooks/exhaustive-deps
+  }, [filtered, viewState.groupBy, agents, agentName, currentUserId]);
 
   const newIssueDefaults = (groupKey?: string) => {
     const defaults: Record<string, string> = {};
@@ -267,13 +291,16 @@ export function IssuesList({
     if (groupKey) {
       if (viewState.groupBy === "status") defaults.status = groupKey;
       else if (viewState.groupBy === "priority") defaults.priority = groupKey;
-      else if (viewState.groupBy === "assignee" && groupKey !== "__unassigned") defaults.assigneeAgentId = groupKey;
+      else if (viewState.groupBy === "assignee" && groupKey !== "__unassigned") {
+        if (groupKey.startsWith("__user:")) defaults.assigneeUserId = groupKey.slice("__user:".length);
+        else defaults.assigneeAgentId = groupKey;
+      }
     }
     return defaults;
   };
 
-  const assignIssue = (issueId: string, assigneeAgentId: string | null) => {
-    onUpdateIssue(issueId, { assigneeAgentId, assigneeUserId: null });
+  const assignIssue = (issueId: string, assigneeAgentId: string | null, assigneeUserId: string | null = null) => {
+    onUpdateIssue(issueId, { assigneeAgentId, assigneeUserId });
     setAssigneePickerIssueId(null);
     setAssigneeSearch("");
   };
@@ -419,22 +446,37 @@ export function IssuesList({
                     </div>
 
                     {/* Assignee */}
-                    {agents && agents.length > 0 && (
-                      <div className="space-y-1">
-                        <span className="text-xs text-muted-foreground">Assignee</span>
-                        <div className="space-y-0.5 max-h-32 overflow-y-auto">
-                          {agents.map((agent) => (
-                            <label key={agent.id} className="flex items-center gap-2 px-2 py-1 rounded-sm hover:bg-accent/50 cursor-pointer">
-                              <Checkbox
-                                checked={viewState.assignees.includes(agent.id)}
-                                onCheckedChange={() => updateView({ assignees: toggleInArray(viewState.assignees, agent.id) })}
-                              />
-                              <span className="text-sm">{agent.name}</span>
-                            </label>
-                          ))}
-                        </div>
+                    <div className="space-y-1">
+                      <span className="text-xs text-muted-foreground">Assignee</span>
+                      <div className="space-y-0.5 max-h-32 overflow-y-auto">
+                        <label className="flex items-center gap-2 px-2 py-1 rounded-sm hover:bg-accent/50 cursor-pointer">
+                          <Checkbox
+                            checked={viewState.assignees.includes("__unassigned")}
+                            onCheckedChange={() => updateView({ assignees: toggleInArray(viewState.assignees, "__unassigned") })}
+                          />
+                          <span className="text-sm">No assignee</span>
+                        </label>
+                        {currentUserId && (
+                          <label className="flex items-center gap-2 px-2 py-1 rounded-sm hover:bg-accent/50 cursor-pointer">
+                            <Checkbox
+                              checked={viewState.assignees.includes("__me")}
+                              onCheckedChange={() => updateView({ assignees: toggleInArray(viewState.assignees, "__me") })}
+                            />
+                            <User className="h-3.5 w-3.5 text-muted-foreground" />
+                            <span className="text-sm">Me</span>
+                          </label>
+                        )}
+                        {(agents ?? []).map((agent) => (
+                          <label key={agent.id} className="flex items-center gap-2 px-2 py-1 rounded-sm hover:bg-accent/50 cursor-pointer">
+                            <Checkbox
+                              checked={viewState.assignees.includes(agent.id)}
+                              onCheckedChange={() => updateView({ assignees: toggleInArray(viewState.assignees, agent.id) })}
+                            />
+                            <span className="text-sm">{agent.name}</span>
+                          </label>
+                        ))}
                       </div>
-                    )}
+                    </div>
 
                     {labels && labels.length > 0 && (
                       <div className="space-y-1">
@@ -683,6 +725,13 @@ export function IssuesList({
                           >
                             {issue.assigneeAgentId && agentName(issue.assigneeAgentId) ? (
                               <Identity name={agentName(issue.assigneeAgentId)!} size="sm" />
+                            ) : issue.assigneeUserId ? (
+                              <span className="inline-flex items-center gap-1.5 text-xs">
+                                <span className="inline-flex h-5 w-5 items-center justify-center rounded-full border border-dashed border-muted-foreground/35 bg-muted/30">
+                                  <User className="h-3 w-3" />
+                                </span>
+                                {formatAssigneeUserLabel(issue.assigneeUserId, currentUserId) ?? "User"}
+                              </span>
                             ) : (
                               <span className="inline-flex items-center gap-1.5 text-xs text-muted-foreground">
                                 <span className="inline-flex h-5 w-5 items-center justify-center rounded-full border border-dashed border-muted-foreground/35 bg-muted/30">
@@ -701,7 +750,7 @@ export function IssuesList({
                         >
                           <input
                             className="mb-1 w-full border-b border-border bg-transparent px-2 py-1.5 text-xs outline-none placeholder:text-muted-foreground/50"
-                            placeholder="Search agents..."
+                            placeholder="Search assignees..."
                             value={assigneeSearch}
                             onChange={(e) => setAssigneeSearch(e.target.value)}
                             autoFocus
@@ -710,16 +759,32 @@ export function IssuesList({
                             <button
                               className={cn(
                                 "flex w-full items-center gap-2 rounded px-2 py-1.5 text-xs hover:bg-accent/50",
-                                !issue.assigneeAgentId && "bg-accent",
+                                !issue.assigneeAgentId && !issue.assigneeUserId && "bg-accent",
                               )}
                               onClick={(e) => {
                                 e.preventDefault();
                                 e.stopPropagation();
-                                assignIssue(issue.id, null);
+                                assignIssue(issue.id, null, null);
                               }}
                             >
                               No assignee
                             </button>
+                            {currentUserId && (
+                              <button
+                                className={cn(
+                                  "flex w-full items-center gap-2 rounded px-2 py-1.5 text-left text-xs hover:bg-accent/50",
+                                  issue.assigneeUserId === currentUserId && "bg-accent",
+                                )}
+                                onClick={(e) => {
+                                  e.preventDefault();
+                                  e.stopPropagation();
+                                  assignIssue(issue.id, null, currentUserId);
+                                }}
+                              >
+                                <User className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />
+                                <span>Me</span>
+                              </button>
+                            )}
                             {(agents ?? [])
                               .filter((agent) => {
                                 if (!assigneeSearch.trim()) return true;
@@ -737,7 +802,7 @@ export function IssuesList({
                                   onClick={(e) => {
                                     e.preventDefault();
                                     e.stopPropagation();
-                                    assignIssue(issue.id, agent.id);
+                                    assignIssue(issue.id, agent.id, null);
                                   }}
                                 >
                                   <Identity name={agent.name} size="sm" className="min-w-0" />
diff --git a/ui/src/context/DialogContext.tsx b/ui/src/context/DialogContext.tsx
index ef7b12b8..904ceb88 100644
--- a/ui/src/context/DialogContext.tsx
+++ b/ui/src/context/DialogContext.tsx
@@ -5,6 +5,7 @@ interface NewIssueDefaults {
   priority?: string;
   projectId?: string;
   assigneeAgentId?: string;
+  assigneeUserId?: string;
   title?: string;
   description?: string;
 }
diff --git a/ui/src/lib/assignees.test.ts b/ui/src/lib/assignees.test.ts
new file mode 100644
index 00000000..1ce22ef7
--- /dev/null
+++ b/ui/src/lib/assignees.test.ts
@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+import {
+  assigneeValueFromSelection,
+  currentUserAssigneeOption,
+  formatAssigneeUserLabel,
+  parseAssigneeValue,
+} from "./assignees";
+
+describe("assignee selection helpers", () => {
+  it("encodes and parses agent assignees", () => {
+    const value = assigneeValueFromSelection({ assigneeAgentId: "agent-123" });
+
+    expect(value).toBe("agent:agent-123");
+    expect(parseAssigneeValue(value)).toEqual({
+      assigneeAgentId: "agent-123",
+      assigneeUserId: null,
+    });
+  });
+
+  it("encodes and parses current-user assignees", () => {
+    const [option] = currentUserAssigneeOption("local-board");
+
+    expect(option).toEqual({
+      id: "user:local-board",
+      label: "Me",
+      searchText: "me board human local-board",
+    });
+    expect(parseAssigneeValue(option.id)).toEqual({
+      assigneeAgentId: null,
+      assigneeUserId: "local-board",
+    });
+  });
+
+  it("treats an empty selection as no assignee", () => {
+    expect(parseAssigneeValue("")).toEqual({
+      assigneeAgentId: null,
+      assigneeUserId: null,
+    });
+  });
+
+  it("keeps backward compatibility for raw agent ids in saved drafts", () => {
+    expect(parseAssigneeValue("legacy-agent-id")).toEqual({
+      assigneeAgentId: "legacy-agent-id",
+      assigneeUserId: null,
+    });
+  });
+
+  it("formats current and board user labels consistently", () => {
+    expect(formatAssigneeUserLabel("user-1", "user-1")).toBe("Me");
+    expect(formatAssigneeUserLabel("local-board", "someone-else")).toBe("Board");
+    expect(formatAssigneeUserLabel("user-abcdef", "someone-else")).toBe("user-");
+  });
+});
diff --git a/ui/src/lib/assignees.ts b/ui/src/lib/assignees.ts
new file mode 100644
index 00000000..274bcd40
--- /dev/null
+++ b/ui/src/lib/assignees.ts
@@ -0,0 +1,51 @@
+export interface AssigneeSelection {
+  assigneeAgentId: string | null;
+  assigneeUserId: string | null;
+}
+
+export interface AssigneeOption {
+  id: string;
+  label: string;
+  searchText?: string;
+}
+
+export function assigneeValueFromSelection(selection: Partial<AssigneeSelection>): string {
+  if (selection.assigneeAgentId) return `agent:${selection.assigneeAgentId}`;
+  if (selection.assigneeUserId) return `user:${selection.assigneeUserId}`;
+  return "";
+}
+
+export function parseAssigneeValue(value: string): AssigneeSelection {
+  if (!value) {
+    return { assigneeAgentId: null, assigneeUserId: null };
+  }
+  if (value.startsWith("agent:")) {
+    const assigneeAgentId = value.slice("agent:".length);
+    return { assigneeAgentId: assigneeAgentId || null, assigneeUserId: null };
+  }
+  if (value.startsWith("user:")) {
+    const assigneeUserId = value.slice("user:".length);
+    return { assigneeAgentId: null, assigneeUserId: assigneeUserId || null };
+  }
+  // Backward compatibility for older drafts/defaults that stored a raw agent id.
+  return { assigneeAgentId: value, assigneeUserId: null };
+}
+
+export function currentUserAssigneeOption(currentUserId: string | null | undefined): AssigneeOption[] {
+  if (!currentUserId) return [];
+  return [{
+    id: assigneeValueFromSelection({ assigneeUserId: currentUserId }),
+    label: "Me",
+    searchText: currentUserId === "local-board" ? "me board human local-board" : `me human ${currentUserId}`,
+  }];
+}
+
+export function formatAssigneeUserLabel(
+  userId: string | null | undefined,
+  currentUserId: string | null | undefined,
+): string | null {
+  if (!userId) return null;
+  if (currentUserId && userId === currentUserId) return "Me";
+  if (userId === "local-board") return "Board";
+  return userId.slice(0, 5);
+}
diff --git a/ui/src/pages/IssueDetail.tsx b/ui/src/pages/IssueDetail.tsx
index bb152e17..9a43f26a 100644
--- a/ui/src/pages/IssueDetail.tsx
+++ b/ui/src/pages/IssueDetail.tsx
@@ -304,8 +304,7 @@ export function IssueDetail() {
       options.push({ id: `agent:${agent.id}`, label: agent.name });
     }
     if (currentUserId) {
-      const label = currentUserId === "local-board" ? "Board" : "Me (Board)";
-      options.push({ id: `user:${currentUserId}`, label });
+      options.push({ id: `user:${currentUserId}`, label: "Me" });
     }
     return options;
   }, [agents, currentUserId]);

From 41eb8e51e33610d3b7095abfa2b5adf2c1ff35af Mon Sep 17 00:00:00 2001
From: Dotta <bippadotta@protonmail.com>
Date: Fri, 13 Mar 2026 09:58:26 -0500
Subject: [PATCH 20/28] Fix company switch remembered routes

Co-Authored-By: Paperclip <noreply@paperclip.ing>
---
 ui/src/hooks/useCompanyPageMemory.test.ts | 71 +++++++++++++++++++++++
 ui/src/hooks/useCompanyPageMemory.ts      | 39 +++++++------
 ui/src/lib/company-page-memory.ts         | 65 +++++++++++++++++++++
 3 files changed, 158 insertions(+), 17 deletions(-)
 create mode 100644 ui/src/hooks/useCompanyPageMemory.test.ts
 create mode 100644 ui/src/lib/company-page-memory.ts

diff --git a/ui/src/hooks/useCompanyPageMemory.test.ts b/ui/src/hooks/useCompanyPageMemory.test.ts
new file mode 100644
index 00000000..a64c60b8
--- /dev/null
+++ b/ui/src/hooks/useCompanyPageMemory.test.ts
@@ -0,0 +1,71 @@
+import { describe, expect, it } from "vitest";
+import {
+  getRememberedPathOwnerCompanyId,
+  sanitizeRememberedPathForCompany,
+} from "../lib/company-page-memory";
+
+const companies = [
+  { id: "for", issuePrefix: "FOR" },
+  { id: "pap", issuePrefix: "PAP" },
+];
+
+describe("getRememberedPathOwnerCompanyId", () => {
+  it("uses the route company instead of stale selected-company state for prefixed routes", () => {
+    expect(
+      getRememberedPathOwnerCompanyId({
+        companies,
+        pathname: "/FOR/issues/FOR-1",
+        fallbackCompanyId: "pap",
+      }),
+    ).toBe("for");
+  });
+
+  it("skips saving when a prefixed route cannot yet be resolved to a known company", () => {
+    expect(
+      getRememberedPathOwnerCompanyId({
+        companies: [],
+        pathname: "/FOR/issues/FOR-1",
+        fallbackCompanyId: "pap",
+      }),
+    ).toBeNull();
+  });
+
+  it("falls back to the previous company for unprefixed board routes", () => {
+    expect(
+      getRememberedPathOwnerCompanyId({
+        companies,
+        pathname: "/dashboard",
+        fallbackCompanyId: "pap",
+      }),
+    ).toBe("pap");
+  });
+});
+
+describe("sanitizeRememberedPathForCompany", () => {
+  it("keeps remembered issue paths that belong to the target company", () => {
+    expect(
+      sanitizeRememberedPathForCompany({
+        path: "/issues/PAP-12",
+        companyPrefix: "PAP",
+      }),
+    ).toBe("/issues/PAP-12");
+  });
+
+  it("falls back to dashboard for remembered issue identifiers from another company", () => {
+    expect(
+      sanitizeRememberedPathForCompany({
+        path: "/issues/FOR-1",
+        companyPrefix: "PAP",
+      }),
+    ).toBe("/dashboard");
+  });
+
+  it("falls back to dashboard when no remembered path exists", () => {
+    expect(
+      sanitizeRememberedPathForCompany({
+        path: null,
+        companyPrefix: "PAP",
+      }),
+    ).toBe("/dashboard");
+  });
+});
diff --git a/ui/src/hooks/useCompanyPageMemory.ts b/ui/src/hooks/useCompanyPageMemory.ts
index d427e587..5206df11 100644
--- a/ui/src/hooks/useCompanyPageMemory.ts
+++ b/ui/src/hooks/useCompanyPageMemory.ts
@@ -1,10 +1,14 @@
-import { useEffect, useRef } from "react";
+import { useEffect, useMemo, useRef } from "react";
 import { useLocation, useNavigate } from "@/lib/router";
 import { useCompany } from "../context/CompanyContext";
 import { toCompanyRelativePath } from "../lib/company-routes";
+import {
+  getRememberedPathOwnerCompanyId,
+  isRememberableCompanyPath,
+  sanitizeRememberedPathForCompany,
+} from "../lib/company-page-memory";
 
 const STORAGE_KEY = "paperclip.companyPaths";
-const GLOBAL_SEGMENTS = new Set(["auth", "invite", "board-claim", "docs"]);
 
 function getCompanyPaths(): Record<string, string> {
   try {
@@ -22,36 +26,36 @@ function saveCompanyPath(companyId: string, path: string) {
   localStorage.setItem(STORAGE_KEY, JSON.stringify(paths));
 }
 
-function isRememberableCompanyPath(path: string): boolean {
-  const pathname = path.split("?")[0] ?? "";
-  const segments = pathname.split("/").filter(Boolean);
-  if (segments.length === 0) return true;
-  const [root] = segments;
-  if (GLOBAL_SEGMENTS.has(root!)) return false;
-  return true;
-}
-
 /**
  * Remembers the last visited page per company and navigates to it on company switch.
  * Falls back to /dashboard if no page was previously visited for a company.
  */
 export function useCompanyPageMemory() {
-  const { selectedCompanyId, selectedCompany, selectionSource } = useCompany();
+  const { companies, selectedCompanyId, selectedCompany, selectionSource } = useCompany();
   const location = useLocation();
   const navigate = useNavigate();
   const prevCompanyId = useRef<string | null>(selectedCompanyId);
+  const rememberedPathOwnerCompanyId = useMemo(
+    () =>
+      getRememberedPathOwnerCompanyId({
+        companies,
+        pathname: location.pathname,
+        fallbackCompanyId: prevCompanyId.current,
+      }),
+    [companies, location.pathname],
+  );
 
   // Save current path for current company on every location change.
   // Uses prevCompanyId ref so we save under the correct company even
   // during the render where selectedCompanyId has already changed.
   const fullPath = location.pathname + location.search;
   useEffect(() => {
-    const companyId = prevCompanyId.current;
+    const companyId = rememberedPathOwnerCompanyId;
     const relativePath = toCompanyRelativePath(fullPath);
     if (companyId && isRememberableCompanyPath(relativePath)) {
       saveCompanyPath(companyId, relativePath);
     }
-  }, [fullPath]);
+  }, [fullPath, rememberedPathOwnerCompanyId]);
 
   // Navigate to saved path when company changes
   useEffect(() => {
@@ -63,9 +67,10 @@ export function useCompanyPageMemory() {
     ) {
       if (selectionSource !== "route_sync" && selectedCompany) {
         const paths = getCompanyPaths();
-        const savedPath = paths[selectedCompanyId];
-        const relativePath = savedPath ? toCompanyRelativePath(savedPath) : "/dashboard";
-        const targetPath = isRememberableCompanyPath(relativePath) ? relativePath : "/dashboard";
+        const targetPath = sanitizeRememberedPathForCompany({
+          path: paths[selectedCompanyId],
+          companyPrefix: selectedCompany.issuePrefix,
+        });
         navigate(`/${selectedCompany.issuePrefix}${targetPath}`, { replace: true });
       }
     }
diff --git a/ui/src/lib/company-page-memory.ts b/ui/src/lib/company-page-memory.ts
new file mode 100644
index 00000000..df549b68
--- /dev/null
+++ b/ui/src/lib/company-page-memory.ts
@@ -0,0 +1,65 @@
+import {
+  extractCompanyPrefixFromPath,
+  normalizeCompanyPrefix,
+  toCompanyRelativePath,
+} from "./company-routes";
+
+const GLOBAL_SEGMENTS = new Set(["auth", "invite", "board-claim", "docs"]);
+
+export function isRememberableCompanyPath(path: string): boolean {
+  const pathname = path.split("?")[0] ?? "";
+  const segments = pathname.split("/").filter(Boolean);
+  if (segments.length === 0) return true;
+  const [root] = segments;
+  if (GLOBAL_SEGMENTS.has(root!)) return false;
+  return true;
+}
+
+function findCompanyByPrefix<T extends { id: string; issuePrefix: string }>(params: {
+  companies: T[];
+  companyPrefix: string;
+}): T | null {
+  const normalizedPrefix = normalizeCompanyPrefix(params.companyPrefix);
+  return params.companies.find((company) => normalizeCompanyPrefix(company.issuePrefix) === normalizedPrefix) ?? null;
+}
+
+export function getRememberedPathOwnerCompanyId<T extends { id: string; issuePrefix: string }>(params: {
+  companies: T[];
+  pathname: string;
+  fallbackCompanyId: string | null;
+}): string | null {
+  const routeCompanyPrefix = extractCompanyPrefixFromPath(params.pathname);
+  if (!routeCompanyPrefix) {
+    return params.fallbackCompanyId;
+  }
+
+  return findCompanyByPrefix({
+    companies: params.companies,
+    companyPrefix: routeCompanyPrefix,
+  })?.id ?? null;
+}
+
+export function sanitizeRememberedPathForCompany(params: {
+  path: string | null | undefined;
+  companyPrefix: string;
+}): string {
+  const relativePath = params.path ? toCompanyRelativePath(params.path) : "/dashboard";
+  if (!isRememberableCompanyPath(relativePath)) {
+    return "/dashboard";
+  }
+
+  const pathname = relativePath.split("?")[0] ?? "";
+  const segments = pathname.split("/").filter(Boolean);
+  const [root, entityId] = segments;
+  if (root === "issues" && entityId) {
+    const identifierMatch = /^([A-Za-z]+)-\d+$/.exec(entityId);
+    if (
+      identifierMatch &&
+      normalizeCompanyPrefix(identifierMatch[1] ?? "") !== normalizeCompanyPrefix(params.companyPrefix)
+    ) {
+      return "/dashboard";
+    }
+  }
+
+  return relativePath;
+}

From d51c4b1a4c378449ee39c33956c7e31e08e3a231 Mon Sep 17 00:00:00 2001
From: Dotta <bippadotta@protonmail.com>
Date: Fri, 13 Mar 2026 10:18:00 -0500
Subject: [PATCH 21/28] fix: tighten token optimization edge cases

Co-Authored-By: Paperclip <noreply@paperclip.ing>
---
 server/src/routes/issues.ts      |  7 ++++++-
 server/src/services/heartbeat.ts | 21 +++++++++++++++++++--
 server/src/services/issues.ts    | 21 ++++++++++++++++++---
 3 files changed, 43 insertions(+), 6 deletions(-)

diff --git a/server/src/routes/issues.ts b/server/src/routes/issues.ts
index bc938910..0213ded2 100644
--- a/server/src/routes/issues.ts
+++ b/server/src/routes/issues.ts
@@ -28,6 +28,8 @@ import { assertCompanyAccess, getActorInfo } from "./authz.js";
 import { shouldWakeAssigneeOnCheckout } from "./issues-checkout-wakeup.js";
 import { isAllowedContentType, MAX_ATTACHMENT_BYTES } from "../attachment-types.js";
 
+const MAX_ISSUE_COMMENT_LIMIT = 500;
+
 export function issueRoutes(db: Db, storage: StorageService) {
   const router = Router();
   const svc = issueService(db);
@@ -878,7 +880,10 @@ export function issueRoutes(db: Db, storage: StorageService) {
       typeof req.query.limit === "string" && req.query.limit.trim().length > 0
         ? Number(req.query.limit)
         : null;
-    const limit = limitRaw && Number.isFinite(limitRaw) && limitRaw > 0 ? Math.floor(limitRaw) : null;
+    const limit =
+      limitRaw && Number.isFinite(limitRaw) && limitRaw > 0
+        ? Math.min(Math.floor(limitRaw), MAX_ISSUE_COMMENT_LIMIT)
+        : null;
     const comments = await svc.listComments(id, {
       afterCommentId,
       order,
diff --git a/server/src/services/heartbeat.ts b/server/src/services/heartbeat.ts
index 1a9dba74..eec83d08 100644
--- a/server/src/services/heartbeat.ts
+++ b/server/src/services/heartbeat.ts
@@ -623,6 +623,19 @@ export function heartbeatService(db: Db) {
       .then((rows) => rows[0] ?? null);
   }
 
+  async function getOldestRunForSession(agentId: string, sessionId: string) {
+    return db
+      .select({
+        id: heartbeatRuns.id,
+        createdAt: heartbeatRuns.createdAt,
+      })
+      .from(heartbeatRuns)
+      .where(and(eq(heartbeatRuns.agentId, agentId), eq(heartbeatRuns.sessionIdAfter, sessionId)))
+      .orderBy(asc(heartbeatRuns.createdAt), asc(heartbeatRuns.id))
+      .limit(1)
+      .then((rows) => rows[0] ?? null);
+  }
+
   async function resolveNormalizedUsageForSession(input: {
     agentId: string;
     runId: string;
@@ -672,6 +685,7 @@ export function heartbeatService(db: Db) {
       };
     }
 
+    const fetchLimit = Math.max(policy.maxSessionRuns > 0 ? policy.maxSessionRuns + 1 : 0, 4);
     const runs = await db
       .select({
         id: heartbeatRuns.id,
@@ -683,7 +697,7 @@ export function heartbeatService(db: Db) {
       .from(heartbeatRuns)
       .where(and(eq(heartbeatRuns.agentId, agent.id), eq(heartbeatRuns.sessionIdAfter, sessionId)))
       .orderBy(desc(heartbeatRuns.createdAt))
-      .limit(Math.max(policy.maxSessionRuns + 1, 4));
+      .limit(fetchLimit);
 
     if (runs.length === 0) {
       return {
@@ -695,7 +709,10 @@ export function heartbeatService(db: Db) {
     }
 
     const latestRun = runs[0] ?? null;
-    const oldestRun = runs[runs.length - 1] ?? latestRun;
+    const oldestRun =
+      policy.maxSessionAgeHours > 0
+        ? await getOldestRunForSession(agent.id, sessionId)
+        : runs[runs.length - 1] ?? latestRun;
     const latestRawUsage = readRawUsageTotals(latestRun?.usageJson);
     const sessionAgeHours =
       latestRun && oldestRun
diff --git a/server/src/services/issues.ts b/server/src/services/issues.ts
index d6f5a643..c42ac02a 100644
--- a/server/src/services/issues.ts
+++ b/server/src/services/issues.ts
@@ -27,6 +27,7 @@ import { resolveIssueGoalId, resolveNextIssueGoalId } from "./issue-goal-fallbac
 import { getDefaultCompanyGoal } from "./goals.js";
 
 const ALL_ISSUE_STATUSES = ["backlog", "todo", "in_progress", "in_review", "blocked", "done", "cancelled"];
+const MAX_ISSUE_COMMENT_PAGE_LIMIT = 500;
 
 function assertTransition(from: string, to: string) {
   if (from === to) return;
@@ -1070,7 +1071,10 @@ export function issueService(db: Db) {
     ) => {
       const order = opts?.order === "asc" ? "asc" : "desc";
       const afterCommentId = opts?.afterCommentId?.trim() || null;
-      const limit = opts?.limit && opts.limit > 0 ? Math.floor(opts.limit) : null;
+      const limit =
+        opts?.limit && opts.limit > 0
+          ? Math.min(Math.floor(opts.limit), MAX_ISSUE_COMMENT_PAGE_LIMIT)
+          : null;
 
       const conditions = [eq(issueComments.issueId, issueId)];
       if (afterCommentId) {
@@ -1085,7 +1089,15 @@ export function issueService(db: Db) {
 
         if (!anchor) return [];
         conditions.push(
-          sql<boolean>`(${issueComments.createdAt} > ${anchor.createdAt} OR (${issueComments.createdAt} = ${anchor.createdAt} AND ${issueComments.id} <> ${anchor.id}))`,
+          order === "asc"
+            ? sql<boolean>`(
+                ${issueComments.createdAt} > ${anchor.createdAt}
+                OR (${issueComments.createdAt} = ${anchor.createdAt} AND ${issueComments.id} > ${anchor.id})
+              )`
+            : sql<boolean>`(
+                ${issueComments.createdAt} < ${anchor.createdAt}
+                OR (${issueComments.createdAt} = ${anchor.createdAt} AND ${issueComments.id} < ${anchor.id})
+              )`,
         );
       }
 
@@ -1093,7 +1105,10 @@ export function issueService(db: Db) {
         .select()
         .from(issueComments)
         .where(and(...conditions))
-        .orderBy(order === "asc" ? asc(issueComments.createdAt) : desc(issueComments.createdAt));
+        .orderBy(
+          order === "asc" ? asc(issueComments.createdAt) : desc(issueComments.createdAt),
+          order === "asc" ? asc(issueComments.id) : desc(issueComments.id),
+        );
 
       const comments = limit ? await query.limit(limit) : await query;
       return comments.map(redactIssueComment);

From cce9941464b4107b66ba02918f62689a54954a8d Mon Sep 17 00:00:00 2001
From: Dotta <bippadotta@protonmail.com>
Date: Fri, 13 Mar 2026 11:12:43 -0500
Subject: [PATCH 22/28] Add worktree UI branding

---
 cli/src/__tests__/worktree.test.ts       |  17 +-
 cli/src/commands/worktree-lib.ts         |  58 ++++-
 cli/src/commands/worktree.ts             |  12 +-
 doc/DEVELOPING.md                        |   8 +-
 server/src/__tests__/ui-branding.test.ts |  66 +++++-
 server/src/ui-branding.ts                | 208 +++++++++++++++--
 ui/index.html                            |   2 +
 ui/src/components/Layout.tsx             | 274 ++++++++++++-----------
 ui/src/components/WorktreeBanner.tsx     |  25 +++
 ui/src/lib/worktree-branding.ts          |  65 ++++++
 10 files changed, 566 insertions(+), 169 deletions(-)
 create mode 100644 ui/src/components/WorktreeBanner.tsx
 create mode 100644 ui/src/lib/worktree-branding.ts

diff --git a/cli/src/__tests__/worktree.test.ts b/cli/src/__tests__/worktree.test.ts
index 115d03b3..fe325cd2 100644
--- a/cli/src/__tests__/worktree.test.ts
+++ b/cli/src/__tests__/worktree.test.ts
@@ -16,6 +16,7 @@ import {
   buildWorktreeConfig,
   buildWorktreeEnvEntries,
   formatShellExports,
+  generateWorktreeColor,
   resolveWorktreeSeedPlan,
   resolveWorktreeLocalPaths,
   rewriteLocalUrlPort,
@@ -181,13 +182,22 @@ describe("worktree helpers", () => {
       path.resolve("/tmp/paperclip-worktrees", "instances", "feature-worktree-support", "data", "storage"),
     );
 
-    const env = buildWorktreeEnvEntries(paths);
+    const env = buildWorktreeEnvEntries(paths, {
+      name: "feature-worktree-support",
+      color: "#3abf7a",
+    });
     expect(env.PAPERCLIP_HOME).toBe(path.resolve("/tmp/paperclip-worktrees"));
     expect(env.PAPERCLIP_INSTANCE_ID).toBe("feature-worktree-support");
     expect(env.PAPERCLIP_IN_WORKTREE).toBe("true");
+    expect(env.PAPERCLIP_WORKTREE_NAME).toBe("feature-worktree-support");
+    expect(env.PAPERCLIP_WORKTREE_COLOR).toBe("#3abf7a");
     expect(formatShellExports(env)).toContain("export PAPERCLIP_INSTANCE_ID='feature-worktree-support'");
   });
 
+  it("generates vivid worktree colors as hex", () => {
+    expect(generateWorktreeColor()).toMatch(/^#[0-9a-f]{6}$/);
+  });
+
   it("uses minimal seed mode to keep app state but drop heavy runtime history", () => {
     const minimal = resolveWorktreeSeedPlan("minimal");
     const full = resolveWorktreeSeedPlan("full");
@@ -280,7 +290,10 @@ describe("worktree helpers", () => {
       });
 
       const envPath = path.join(repoRoot, ".paperclip", ".env");
-      expect(fs.readFileSync(envPath, "utf8")).toContain("PAPERCLIP_AGENT_JWT_SECRET=worktree-shared-secret");
+      const envContents = fs.readFileSync(envPath, "utf8");
+      expect(envContents).toContain("PAPERCLIP_AGENT_JWT_SECRET=worktree-shared-secret");
+      expect(envContents).toContain("PAPERCLIP_WORKTREE_NAME=repo");
+      expect(envContents).toMatch(/PAPERCLIP_WORKTREE_COLOR=#[0-9a-f]{6}/);
     } finally {
       process.chdir(originalCwd);
       if (originalJwtSecret === undefined) {
diff --git a/cli/src/commands/worktree-lib.ts b/cli/src/commands/worktree-lib.ts
index 4a0a3aeb..5249acc2 100644
--- a/cli/src/commands/worktree-lib.ts
+++ b/cli/src/commands/worktree-lib.ts
@@ -1,3 +1,4 @@
+import { randomInt } from "node:crypto";
 import path from "node:path";
 import type { PaperclipConfig } from "../config/schema.js";
 import { expandHomePrefix } from "../config/home.js";
@@ -44,6 +45,11 @@ export type WorktreeLocalPaths = {
   storageDir: string;
 };
 
+export type WorktreeUiBranding = {
+  name: string;
+  color: string;
+};
+
 export function isWorktreeSeedMode(value: string): value is WorktreeSeedMode {
   return (WORKTREE_SEED_MODES as readonly string[]).includes(value);
 }
@@ -87,6 +93,51 @@ export function resolveSuggestedWorktreeName(cwd: string, explicitName?: string)
   return nonEmpty(explicitName) ?? path.basename(path.resolve(cwd));
 }
 
+function hslComponentToHex(n: number): string {
+  return Math.round(Math.max(0, Math.min(255, n)))
+    .toString(16)
+    .padStart(2, "0");
+}
+
+function hslToHex(hue: number, saturation: number, lightness: number): string {
+  const s = Math.max(0, Math.min(100, saturation)) / 100;
+  const l = Math.max(0, Math.min(100, lightness)) / 100;
+  const c = (1 - Math.abs((2 * l) - 1)) * s;
+  const h = ((hue % 360) + 360) % 360;
+  const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
+  const m = l - (c / 2);
+
+  let r = 0;
+  let g = 0;
+  let b = 0;
+
+  if (h < 60) {
+    r = c;
+    g = x;
+  } else if (h < 120) {
+    r = x;
+    g = c;
+  } else if (h < 180) {
+    g = c;
+    b = x;
+  } else if (h < 240) {
+    g = x;
+    b = c;
+  } else if (h < 300) {
+    r = x;
+    b = c;
+  } else {
+    r = c;
+    b = x;
+  }
+
+  return `#${hslComponentToHex((r + m) * 255)}${hslComponentToHex((g + m) * 255)}${hslComponentToHex((b + m) * 255)}`;
+}
+
+export function generateWorktreeColor(): string {
+  return hslToHex(randomInt(0, 360), 68, 56);
+}
+
 export function resolveWorktreeLocalPaths(opts: {
   cwd: string;
   homeDir?: string;
@@ -196,13 +247,18 @@ export function buildWorktreeConfig(input: {
   };
 }
 
-export function buildWorktreeEnvEntries(paths: WorktreeLocalPaths): Record<string, string> {
+export function buildWorktreeEnvEntries(
+  paths: WorktreeLocalPaths,
+  branding?: WorktreeUiBranding,
+): Record<string, string> {
   return {
     PAPERCLIP_HOME: paths.homeDir,
     PAPERCLIP_INSTANCE_ID: paths.instanceId,
     PAPERCLIP_CONFIG: paths.configPath,
     PAPERCLIP_CONTEXT: paths.contextPath,
     PAPERCLIP_IN_WORKTREE: "true",
+    ...(branding?.name ? { PAPERCLIP_WORKTREE_NAME: branding.name } : {}),
+    ...(branding?.color ? { PAPERCLIP_WORKTREE_COLOR: branding.color } : {}),
   };
 }
 
diff --git a/cli/src/commands/worktree.ts b/cli/src/commands/worktree.ts
index 582bb5dd..fca320b9 100644
--- a/cli/src/commands/worktree.ts
+++ b/cli/src/commands/worktree.ts
@@ -39,6 +39,7 @@ import {
   buildWorktreeEnvEntries,
   DEFAULT_WORKTREE_HOME,
   formatShellExports,
+  generateWorktreeColor,
   isWorktreeSeedMode,
   resolveSuggestedWorktreeName,
   resolveWorktreeSeedPlan,
@@ -623,7 +624,7 @@ async function seedWorktreeDatabase(input: {
 
 async function runWorktreeInit(opts: WorktreeInitOptions): Promise<void> {
   const cwd = process.cwd();
-  const name = resolveSuggestedWorktreeName(
+  const worktreeName = resolveSuggestedWorktreeName(
     cwd,
     opts.name ?? detectGitBranchName(cwd) ?? undefined,
   );
@@ -631,12 +632,16 @@ async function runWorktreeInit(opts: WorktreeInitOptions): Promise<void> {
   if (!isWorktreeSeedMode(seedMode)) {
     throw new Error(`Unsupported seed mode "${seedMode}". Expected one of: minimal, full.`);
   }
-  const instanceId = sanitizeWorktreeInstanceId(opts.instance ?? name);
+  const instanceId = sanitizeWorktreeInstanceId(opts.instance ?? worktreeName);
   const paths = resolveWorktreeLocalPaths({
     cwd,
     homeDir: resolveWorktreeHome(opts.home),
     instanceId,
   });
+  const branding = {
+    name: worktreeName,
+    color: generateWorktreeColor(),
+  };
   const sourceConfigPath = resolveSourceConfigPath(opts);
   const sourceConfig = existsSync(sourceConfigPath) ? readConfig(sourceConfigPath) : null;
 
@@ -669,7 +674,7 @@ async function runWorktreeInit(opts: WorktreeInitOptions): Promise<void> {
     nonEmpty(process.env.PAPERCLIP_AGENT_JWT_SECRET);
   mergePaperclipEnvEntries(
     {
-      ...buildWorktreeEnvEntries(paths),
+      ...buildWorktreeEnvEntries(paths, branding),
       ...(existingAgentJwtSecret ? { PAPERCLIP_AGENT_JWT_SECRET: existingAgentJwtSecret } : {}),
     },
     paths.envPath,
@@ -710,6 +715,7 @@ async function runWorktreeInit(opts: WorktreeInitOptions): Promise<void> {
   p.log.message(pc.dim(`Repo env: ${paths.envPath}`));
   p.log.message(pc.dim(`Isolated home: ${paths.homeDir}`));
   p.log.message(pc.dim(`Instance: ${paths.instanceId}`));
+  p.log.message(pc.dim(`Worktree badge: ${branding.name} (${branding.color})`));
   p.log.message(pc.dim(`Server port: ${serverPort} | DB port: ${databasePort}`));
   if (copiedGitHooks?.copied) {
     p.log.message(
diff --git a/doc/DEVELOPING.md b/doc/DEVELOPING.md
index 1ca1409b..4b379dcb 100644
--- a/doc/DEVELOPING.md
+++ b/doc/DEVELOPING.md
@@ -152,7 +152,13 @@ Seed modes:
 
 After `worktree init`, both the server and the CLI auto-load the repo-local `.paperclip/.env` when run inside that worktree, so normal commands like `pnpm dev`, `paperclipai doctor`, and `paperclipai db:backup` stay scoped to the worktree instance.
 
-That repo-local env also sets `PAPERCLIP_IN_WORKTREE=true`, which the server can use for worktree-specific UI behavior such as an alternate favicon.
+That repo-local env also sets:
+
+- `PAPERCLIP_IN_WORKTREE=true`
+- `PAPERCLIP_WORKTREE_NAME=<worktree-name>`
+- `PAPERCLIP_WORKTREE_COLOR=<hex-color>`
+
+The server/UI use those values for worktree-specific branding such as the top banner and dynamically colored favicon.
 
 Print shell exports explicitly when needed:
 
diff --git a/server/src/__tests__/ui-branding.test.ts b/server/src/__tests__/ui-branding.test.ts
index 858823bb..c649d5c9 100644
--- a/server/src/__tests__/ui-branding.test.ts
+++ b/server/src/__tests__/ui-branding.test.ts
@@ -1,8 +1,16 @@
 import { describe, expect, it } from "vitest";
-import { applyUiBranding, isWorktreeUiBrandingEnabled, renderFaviconLinks } from "../ui-branding.js";
+import {
+  applyUiBranding,
+  getWorktreeUiBranding,
+  isWorktreeUiBrandingEnabled,
+  renderFaviconLinks,
+  renderRuntimeBrandingMeta,
+} from "../ui-branding.js";
 
 const TEMPLATE = `<!doctype html>
 <head>
+    <!-- PAPERCLIP_RUNTIME_BRANDING_START -->
+    <!-- PAPERCLIP_RUNTIME_BRANDING_END -->
     <!-- PAPERCLIP_FAVICON_START -->
     <link rel="icon" href="/favicon.ico" sizes="48x48" />
     <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
@@ -18,21 +26,57 @@ describe("ui branding", () => {
     expect(isWorktreeUiBrandingEnabled({ PAPERCLIP_IN_WORKTREE: "false" })).toBe(false);
   });
 
-  it("renders the worktree favicon asset set when enabled", () => {
-    const links = renderFaviconLinks(true);
-    expect(links).toContain("/worktree-favicon.ico");
-    expect(links).toContain("/worktree-favicon.svg");
-    expect(links).toContain("/worktree-favicon-32x32.png");
-    expect(links).toContain("/worktree-favicon-16x16.png");
+  it("resolves name, color, and text color for worktree branding", () => {
+    const branding = getWorktreeUiBranding({
+      PAPERCLIP_IN_WORKTREE: "true",
+      PAPERCLIP_WORKTREE_NAME: "paperclip-pr-432",
+      PAPERCLIP_WORKTREE_COLOR: "#4f86f7",
+    });
+
+    expect(branding.enabled).toBe(true);
+    expect(branding.name).toBe("paperclip-pr-432");
+    expect(branding.color).toBe("#4f86f7");
+    expect(branding.textColor).toMatch(/^#[0-9a-f]{6}$/);
+    expect(branding.faviconHref).toContain("data:image/svg+xml,");
   });
 
-  it("rewrites the favicon block for worktree instances only", () => {
-    const branded = applyUiBranding(TEMPLATE, { PAPERCLIP_IN_WORKTREE: "true" });
-    expect(branded).toContain("/worktree-favicon.svg");
+  it("renders a dynamic worktree favicon when enabled", () => {
+    const links = renderFaviconLinks(
+      getWorktreeUiBranding({
+        PAPERCLIP_IN_WORKTREE: "true",
+        PAPERCLIP_WORKTREE_NAME: "paperclip-pr-432",
+        PAPERCLIP_WORKTREE_COLOR: "#4f86f7",
+      }),
+    );
+    expect(links).toContain("data:image/svg+xml,");
+    expect(links).toContain('rel="shortcut icon"');
+  });
+
+  it("renders runtime branding metadata for the ui", () => {
+    const meta = renderRuntimeBrandingMeta(
+      getWorktreeUiBranding({
+        PAPERCLIP_IN_WORKTREE: "true",
+        PAPERCLIP_WORKTREE_NAME: "paperclip-pr-432",
+        PAPERCLIP_WORKTREE_COLOR: "#4f86f7",
+      }),
+    );
+    expect(meta).toContain('name="paperclip-worktree-name"');
+    expect(meta).toContain('content="paperclip-pr-432"');
+    expect(meta).toContain('name="paperclip-worktree-color"');
+  });
+
+  it("rewrites the favicon and runtime branding blocks for worktree instances only", () => {
+    const branded = applyUiBranding(TEMPLATE, {
+      PAPERCLIP_IN_WORKTREE: "true",
+      PAPERCLIP_WORKTREE_NAME: "paperclip-pr-432",
+      PAPERCLIP_WORKTREE_COLOR: "#4f86f7",
+    });
+    expect(branded).toContain("data:image/svg+xml,");
+    expect(branded).toContain('name="paperclip-worktree-name"');
     expect(branded).not.toContain('href="/favicon.svg"');
 
     const defaultHtml = applyUiBranding(TEMPLATE, {});
     expect(defaultHtml).toContain('href="/favicon.svg"');
-    expect(defaultHtml).not.toContain("/worktree-favicon.svg");
+    expect(defaultHtml).not.toContain('name="paperclip-worktree-name"');
   });
 });
diff --git a/server/src/ui-branding.ts b/server/src/ui-branding.ts
index bb6f3a33..8195c91e 100644
--- a/server/src/ui-branding.ts
+++ b/server/src/ui-branding.ts
@@ -1,5 +1,7 @@
 const FAVICON_BLOCK_START = "<!-- PAPERCLIP_FAVICON_START -->";
 const FAVICON_BLOCK_END = "<!-- PAPERCLIP_FAVICON_END -->";
+const RUNTIME_BRANDING_BLOCK_START = "<!-- PAPERCLIP_RUNTIME_BRANDING_START -->";
+const RUNTIME_BRANDING_BLOCK_END = "<!-- PAPERCLIP_RUNTIME_BRANDING_END -->";
 
 const DEFAULT_FAVICON_LINKS = [
   '<link rel="icon" href="/favicon.ico" sizes="48x48" />',
@@ -8,12 +10,13 @@ const DEFAULT_FAVICON_LINKS = [
   '<link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png" />',
 ].join("\n");
 
-const WORKTREE_FAVICON_LINKS = [
-  '<link rel="icon" href="/worktree-favicon.ico" sizes="48x48" />',
-  '<link rel="icon" href="/worktree-favicon.svg" type="image/svg+xml" />',
-  '<link rel="icon" type="image/png" sizes="32x32" href="/worktree-favicon-32x32.png" />',
-  '<link rel="icon" type="image/png" sizes="16x16" href="/worktree-favicon-16x16.png" />',
-].join("\n");
+export type WorktreeUiBranding = {
+  enabled: boolean;
+  name: string | null;
+  color: string | null;
+  textColor: string | null;
+  faviconHref: string | null;
+};
 
 function isTruthyEnvValue(value: string | undefined): boolean {
   if (!value) return false;
@@ -21,21 +24,194 @@ function isTruthyEnvValue(value: string | undefined): boolean {
   return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
 }
 
+function nonEmpty(value: string | undefined): string | null {
+  if (typeof value !== "string") return null;
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : null;
+}
+
+function normalizeHexColor(value: string | undefined): string | null {
+  const raw = nonEmpty(value);
+  if (!raw) return null;
+  const hex = raw.startsWith("#") ? raw.slice(1) : raw;
+  if (/^[0-9a-fA-F]{3}$/.test(hex)) {
+    return `#${hex.split("").map((char) => `${char}${char}`).join("").toLowerCase()}`;
+  }
+  if (/^[0-9a-fA-F]{6}$/.test(hex)) {
+    return `#${hex.toLowerCase()}`;
+  }
+  return null;
+}
+
+function hslComponentToHex(n: number): string {
+  return Math.round(Math.max(0, Math.min(255, n)))
+    .toString(16)
+    .padStart(2, "0");
+}
+
+function hslToHex(hue: number, saturation: number, lightness: number): string {
+  const s = Math.max(0, Math.min(100, saturation)) / 100;
+  const l = Math.max(0, Math.min(100, lightness)) / 100;
+  const c = (1 - Math.abs((2 * l) - 1)) * s;
+  const h = ((hue % 360) + 360) % 360;
+  const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
+  const m = l - (c / 2);
+
+  let r = 0;
+  let g = 0;
+  let b = 0;
+
+  if (h < 60) {
+    r = c;
+    g = x;
+  } else if (h < 120) {
+    r = x;
+    g = c;
+  } else if (h < 180) {
+    g = c;
+    b = x;
+  } else if (h < 240) {
+    g = x;
+    b = c;
+  } else if (h < 300) {
+    r = x;
+    b = c;
+  } else {
+    r = c;
+    b = x;
+  }
+
+  return `#${hslComponentToHex((r + m) * 255)}${hslComponentToHex((g + m) * 255)}${hslComponentToHex((b + m) * 255)}`;
+}
+
+function deriveColorFromSeed(seed: string): string {
+  let hash = 0;
+  for (const char of seed) {
+    hash = ((hash * 33) + char.charCodeAt(0)) >>> 0;
+  }
+  return hslToHex(hash % 360, 68, 56);
+}
+
+function hexToRgb(color: string): { r: number; g: number; b: number } {
+  const normalized = normalizeHexColor(color) ?? "#000000";
+  return {
+    r: Number.parseInt(normalized.slice(1, 3), 16),
+    g: Number.parseInt(normalized.slice(3, 5), 16),
+    b: Number.parseInt(normalized.slice(5, 7), 16),
+  };
+}
+
+function relativeLuminanceChannel(value: number): number {
+  const normalized = value / 255;
+  return normalized <= 0.03928 ? normalized / 12.92 : ((normalized + 0.055) / 1.055) ** 2.4;
+}
+
+function relativeLuminance(color: string): number {
+  const { r, g, b } = hexToRgb(color);
+  return (
+    (0.2126 * relativeLuminanceChannel(r)) +
+    (0.7152 * relativeLuminanceChannel(g)) +
+    (0.0722 * relativeLuminanceChannel(b))
+  );
+}
+
+function pickReadableTextColor(background: string): string {
+  const backgroundLuminance = relativeLuminance(background);
+  const whiteContrast = 1.05 / (backgroundLuminance + 0.05);
+  const blackContrast = (backgroundLuminance + 0.05) / 0.05;
+  return whiteContrast >= blackContrast ? "#f8fafc" : "#111827";
+}
+
+function escapeHtmlAttribute(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;");
+}
+
+function createFaviconDataUrl(background: string, foreground: string): string {
+  const svg = [
+    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none">',
+    `<rect width="24" height="24" rx="6" fill="${background}"/>`,
+    `<path stroke="${foreground}" stroke-linecap="round" stroke-linejoin="round" stroke-width="2.15" d="m16 6-8.414 8.586a2 2 0 0 0 2.829 2.829l8.414-8.586a4 4 0 1 0-5.657-5.657l-8.379 8.551a6 6 0 1 0 8.485 8.485l8.379-8.551"/>`,
+    "</svg>",
+  ].join("");
+  return `data:image/svg+xml,${encodeURIComponent(svg)}`;
+}
+
 export function isWorktreeUiBrandingEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
   return isTruthyEnvValue(env.PAPERCLIP_IN_WORKTREE);
 }
 
-export function renderFaviconLinks(worktree: boolean): string {
-  return worktree ? WORKTREE_FAVICON_LINKS : DEFAULT_FAVICON_LINKS;
+export function getWorktreeUiBranding(env: NodeJS.ProcessEnv = process.env): WorktreeUiBranding {
+  if (!isWorktreeUiBrandingEnabled(env)) {
+    return {
+      enabled: false,
+      name: null,
+      color: null,
+      textColor: null,
+      faviconHref: null,
+    };
+  }
+
+  const name = nonEmpty(env.PAPERCLIP_WORKTREE_NAME) ?? nonEmpty(env.PAPERCLIP_INSTANCE_ID) ?? "worktree";
+  const color = normalizeHexColor(env.PAPERCLIP_WORKTREE_COLOR) ?? deriveColorFromSeed(name);
+  const textColor = pickReadableTextColor(color);
+
+  return {
+    enabled: true,
+    name,
+    color,
+    textColor,
+    faviconHref: createFaviconDataUrl(color, textColor),
+  };
+}
+
+export function renderFaviconLinks(branding: WorktreeUiBranding): string {
+  if (!branding.enabled || !branding.faviconHref) return DEFAULT_FAVICON_LINKS;
+
+  const href = escapeHtmlAttribute(branding.faviconHref);
+  return [
+    `<link rel="icon" href="${href}" type="image/svg+xml" sizes="any" />`,
+    `<link rel="shortcut icon" href="${href}" type="image/svg+xml" />`,
+  ].join("\n");
+}
+
+export function renderRuntimeBrandingMeta(branding: WorktreeUiBranding): string {
+  if (!branding.enabled || !branding.name || !branding.color || !branding.textColor) return "";
+
+  return [
+    '<meta name="paperclip-worktree-enabled" content="true" />',
+    `<meta name="paperclip-worktree-name" content="${escapeHtmlAttribute(branding.name)}" />`,
+    `<meta name="paperclip-worktree-color" content="${escapeHtmlAttribute(branding.color)}" />`,
+    `<meta name="paperclip-worktree-text-color" content="${escapeHtmlAttribute(branding.textColor)}" />`,
+  ].join("\n");
+}
+
+function replaceMarkedBlock(html: string, startMarker: string, endMarker: string, content: string): string {
+  const start = html.indexOf(startMarker);
+  const end = html.indexOf(endMarker);
+  if (start === -1 || end === -1 || end < start) return html;
+
+  const before = html.slice(0, start + startMarker.length);
+  const after = html.slice(end);
+  const indentedContent = content
+    ? `\n${content
+      .split("\n")
+      .map((line) => `    ${line}`)
+      .join("\n")}\n    `
+    : "\n    ";
+  return `${before}${indentedContent}${after}`;
 }
 
 export function applyUiBranding(html: string, env: NodeJS.ProcessEnv = process.env): string {
-  const start = html.indexOf(FAVICON_BLOCK_START);
-  const end = html.indexOf(FAVICON_BLOCK_END);
-  if (start === -1 || end === -1 || end < start) return html;
-
-  const before = html.slice(0, start + FAVICON_BLOCK_START.length);
-  const after = html.slice(end);
-  const links = renderFaviconLinks(isWorktreeUiBrandingEnabled(env));
-  return `${before}\n${links}\n    ${after}`;
+  const branding = getWorktreeUiBranding(env);
+  const withFavicon = replaceMarkedBlock(html, FAVICON_BLOCK_START, FAVICON_BLOCK_END, renderFaviconLinks(branding));
+  return replaceMarkedBlock(
+    withFavicon,
+    RUNTIME_BRANDING_BLOCK_START,
+    RUNTIME_BRANDING_BLOCK_END,
+    renderRuntimeBrandingMeta(branding),
+  );
 }
diff --git a/ui/index.html b/ui/index.html
index 7994c0d2..1bb9152e 100644
--- a/ui/index.html
+++ b/ui/index.html
@@ -8,6 +8,8 @@
     <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
     <meta name="apple-mobile-web-app-title" content="Paperclip" />
     <title>Paperclip</title>
+    <!-- PAPERCLIP_RUNTIME_BRANDING_START -->
+    <!-- PAPERCLIP_RUNTIME_BRANDING_END -->
     <!-- PAPERCLIP_FAVICON_START -->
     <link rel="icon" href="/favicon.ico" sizes="48x48" />
     <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
diff --git a/ui/src/components/Layout.tsx b/ui/src/components/Layout.tsx
index e484b265..43094b51 100644
--- a/ui/src/components/Layout.tsx
+++ b/ui/src/components/Layout.tsx
@@ -14,6 +14,7 @@ import { NewGoalDialog } from "./NewGoalDialog";
 import { NewAgentDialog } from "./NewAgentDialog";
 import { ToastViewport } from "./ToastViewport";
 import { MobileBottomNav } from "./MobileBottomNav";
+import { WorktreeBanner } from "./WorktreeBanner";
 import { useDialog } from "../context/DialogContext";
 import { usePanel } from "../context/PanelContext";
 import { useCompany } from "../context/CompanyContext";
@@ -223,7 +224,7 @@ export function Layout() {
     <div
       className={cn(
         "bg-background text-foreground pt-[env(safe-area-inset-top)]",
-        isMobile ? "min-h-dvh" : "flex h-dvh overflow-hidden",
+        isMobile ? "min-h-dvh" : "flex h-dvh flex-col overflow-hidden",
       )}
     >
       <a
@@ -232,145 +233,148 @@ export function Layout() {
       >
         Skip to Main Content
       </a>
-      {/* Mobile backdrop */}
-      {isMobile && sidebarOpen && (
-        <button
-          type="button"
-          className="fixed inset-0 z-40 bg-black/50"
-          onClick={() => setSidebarOpen(false)}
-          aria-label="Close sidebar"
-        />
-      )}
+      <WorktreeBanner />
+      <div className={cn("min-h-0 flex-1", isMobile ? "w-full" : "flex overflow-hidden")}>
+        {/* Mobile backdrop */}
+        {isMobile && sidebarOpen && (
+          <button
+            type="button"
+            className="fixed inset-0 z-40 bg-black/50"
+            onClick={() => setSidebarOpen(false)}
+            aria-label="Close sidebar"
+          />
+        )}
 
-      {/* Combined sidebar area: company rail + inner sidebar + docs bar */}
-      {isMobile ? (
-        <div
-          className={cn(
-            "fixed inset-y-0 left-0 z-50 flex flex-col overflow-hidden pt-[env(safe-area-inset-top)] transition-transform duration-100 ease-out",
-            sidebarOpen ? "translate-x-0" : "-translate-x-full"
-          )}
-        >
-          <div className="flex flex-1 min-h-0 overflow-hidden">
-            <CompanyRail />
-            {isInstanceSettingsRoute ? <InstanceSidebar /> : <Sidebar />}
-          </div>
-          <div className="border-t border-r border-border px-3 py-2 bg-background">
-            <div className="flex items-center gap-1">
-              <a
-                href="https://docs.paperclip.ing/"
-                target="_blank"
-                rel="noopener noreferrer"
-                className="flex items-center gap-2.5 px-3 py-2 text-[13px] font-medium transition-colors text-foreground/80 hover:bg-accent/50 hover:text-foreground flex-1 min-w-0"
-              >
-                <BookOpen className="h-4 w-4 shrink-0" />
-                <span className="truncate">Documentation</span>
-              </a>
-              <Button variant="ghost" size="icon-sm" className="text-muted-foreground shrink-0" asChild>
-                <Link
-                  to="/instance/settings"
-                  aria-label="Instance settings"
-                  title="Instance settings"
-                  onClick={() => {
-                    if (isMobile) setSidebarOpen(false);
-                  }}
-                >
-                  <Settings className="h-4 w-4" />
-                </Link>
-              </Button>
-              <Button
-                type="button"
-                variant="ghost"
-                size="icon-sm"
-                className="text-muted-foreground shrink-0"
-                onClick={toggleTheme}
-                aria-label={`Switch to ${nextTheme} mode`}
-                title={`Switch to ${nextTheme} mode`}
-              >
-                {theme === "dark" ? <Sun className="h-4 w-4" /> : <Moon className="h-4 w-4" />}
-              </Button>
-            </div>
-          </div>
-        </div>
-      ) : (
-        <div className="flex flex-col shrink-0 h-full">
-          <div className="flex flex-1 min-h-0">
-            <CompanyRail />
-            <div
-              className={cn(
-                "overflow-hidden transition-[width] duration-100 ease-out",
-                sidebarOpen ? "w-60" : "w-0"
-              )}
-            >
-              {isInstanceSettingsRoute ? <InstanceSidebar /> : <Sidebar />}
-            </div>
-          </div>
-          <div className="border-t border-r border-border px-3 py-2">
-            <div className="flex items-center gap-1">
-              <a
-                href="https://docs.paperclip.ing/"
-                target="_blank"
-                rel="noopener noreferrer"
-                className="flex items-center gap-2.5 px-3 py-2 text-[13px] font-medium transition-colors text-foreground/80 hover:bg-accent/50 hover:text-foreground flex-1 min-w-0"
-              >
-                <BookOpen className="h-4 w-4 shrink-0" />
-                <span className="truncate">Documentation</span>
-              </a>
-              <Button variant="ghost" size="icon-sm" className="text-muted-foreground shrink-0" asChild>
-                <Link
-                  to="/instance/settings"
-                  aria-label="Instance settings"
-                  title="Instance settings"
-                  onClick={() => {
-                    if (isMobile) setSidebarOpen(false);
-                  }}
-                >
-                  <Settings className="h-4 w-4" />
-                </Link>
-              </Button>
-              <Button
-                type="button"
-                variant="ghost"
-                size="icon-sm"
-                className="text-muted-foreground shrink-0"
-                onClick={toggleTheme}
-                aria-label={`Switch to ${nextTheme} mode`}
-                title={`Switch to ${nextTheme} mode`}
-              >
-                {theme === "dark" ? <Sun className="h-4 w-4" /> : <Moon className="h-4 w-4" />}
-              </Button>
-            </div>
-          </div>
-        </div>
-      )}
-
-      {/* Main content */}
-      <div className={cn("flex min-w-0 flex-col", isMobile ? "w-full" : "h-full flex-1")}>
-        <div
-          className={cn(
-            isMobile && "sticky top-0 z-20 bg-background/95 backdrop-blur supports-[backdrop-filter]:bg-background/85",
-          )}
-        >
-          <BreadcrumbBar />
-        </div>
-        <div className={cn(isMobile ? "block" : "flex flex-1 min-h-0")}>
-          <main
-            id="main-content"
-            tabIndex={-1}
+        {/* Combined sidebar area: company rail + inner sidebar + docs bar */}
+        {isMobile ? (
+          <div
             className={cn(
-              "flex-1 p-4 md:p-6",
-              isMobile ? "overflow-visible pb-[calc(5rem+env(safe-area-inset-bottom))]" : "overflow-auto",
+              "fixed inset-y-0 left-0 z-50 flex flex-col overflow-hidden pt-[env(safe-area-inset-top)] transition-transform duration-100 ease-out",
+              sidebarOpen ? "translate-x-0" : "-translate-x-full"
             )}
           >
-            {hasUnknownCompanyPrefix ? (
-              <NotFoundPage
-                scope="invalid_company_prefix"
-                requestedPrefix={companyPrefix ?? selectedCompany?.issuePrefix}
-              />
-            ) : (
-              <Outlet />
+            <div className="flex flex-1 min-h-0 overflow-hidden">
+              <CompanyRail />
+              {isInstanceSettingsRoute ? <InstanceSidebar /> : <Sidebar />}
+            </div>
+            <div className="border-t border-r border-border px-3 py-2 bg-background">
+              <div className="flex items-center gap-1">
+                <a
+                  href="https://docs.paperclip.ing/"
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="flex items-center gap-2.5 px-3 py-2 text-[13px] font-medium transition-colors text-foreground/80 hover:bg-accent/50 hover:text-foreground flex-1 min-w-0"
+                >
+                  <BookOpen className="h-4 w-4 shrink-0" />
+                  <span className="truncate">Documentation</span>
+                </a>
+                <Button variant="ghost" size="icon-sm" className="text-muted-foreground shrink-0" asChild>
+                  <Link
+                    to="/instance/settings"
+                    aria-label="Instance settings"
+                    title="Instance settings"
+                    onClick={() => {
+                      if (isMobile) setSidebarOpen(false);
+                    }}
+                  >
+                    <Settings className="h-4 w-4" />
+                  </Link>
+                </Button>
+                <Button
+                  type="button"
+                  variant="ghost"
+                  size="icon-sm"
+                  className="text-muted-foreground shrink-0"
+                  onClick={toggleTheme}
+                  aria-label={`Switch to ${nextTheme} mode`}
+                  title={`Switch to ${nextTheme} mode`}
+                >
+                  {theme === "dark" ? <Sun className="h-4 w-4" /> : <Moon className="h-4 w-4" />}
+                </Button>
+              </div>
+            </div>
+          </div>
+        ) : (
+          <div className="flex h-full flex-col shrink-0">
+            <div className="flex flex-1 min-h-0">
+              <CompanyRail />
+              <div
+                className={cn(
+                  "overflow-hidden transition-[width] duration-100 ease-out",
+                  sidebarOpen ? "w-60" : "w-0"
+                )}
+              >
+                {isInstanceSettingsRoute ? <InstanceSidebar /> : <Sidebar />}
+              </div>
+            </div>
+            <div className="border-t border-r border-border px-3 py-2">
+              <div className="flex items-center gap-1">
+                <a
+                  href="https://docs.paperclip.ing/"
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="flex items-center gap-2.5 px-3 py-2 text-[13px] font-medium transition-colors text-foreground/80 hover:bg-accent/50 hover:text-foreground flex-1 min-w-0"
+                >
+                  <BookOpen className="h-4 w-4 shrink-0" />
+                  <span className="truncate">Documentation</span>
+                </a>
+                <Button variant="ghost" size="icon-sm" className="text-muted-foreground shrink-0" asChild>
+                  <Link
+                    to="/instance/settings"
+                    aria-label="Instance settings"
+                    title="Instance settings"
+                    onClick={() => {
+                      if (isMobile) setSidebarOpen(false);
+                    }}
+                  >
+                    <Settings className="h-4 w-4" />
+                  </Link>
+                </Button>
+                <Button
+                  type="button"
+                  variant="ghost"
+                  size="icon-sm"
+                  className="text-muted-foreground shrink-0"
+                  onClick={toggleTheme}
+                  aria-label={`Switch to ${nextTheme} mode`}
+                  title={`Switch to ${nextTheme} mode`}
+                >
+                  {theme === "dark" ? <Sun className="h-4 w-4" /> : <Moon className="h-4 w-4" />}
+                </Button>
+              </div>
+            </div>
+          </div>
+        )}
+
+        {/* Main content */}
+        <div className={cn("flex min-w-0 flex-col", isMobile ? "w-full" : "h-full flex-1")}>
+          <div
+            className={cn(
+              isMobile && "sticky top-0 z-20 bg-background/95 backdrop-blur supports-[backdrop-filter]:bg-background/85",
             )}
-          </main>
-          <PropertiesPanel />
+          >
+            <BreadcrumbBar />
+          </div>
+          <div className={cn(isMobile ? "block" : "flex flex-1 min-h-0")}>
+            <main
+              id="main-content"
+              tabIndex={-1}
+              className={cn(
+                "flex-1 p-4 md:p-6",
+                isMobile ? "overflow-visible pb-[calc(5rem+env(safe-area-inset-bottom))]" : "overflow-auto",
+              )}
+            >
+              {hasUnknownCompanyPrefix ? (
+                <NotFoundPage
+                  scope="invalid_company_prefix"
+                  requestedPrefix={companyPrefix ?? selectedCompany?.issuePrefix}
+                />
+              ) : (
+                <Outlet />
+              )}
+            </main>
+            <PropertiesPanel />
+          </div>
         </div>
       </div>
       {isMobile && <MobileBottomNav visible={mobileNavVisible} />}
diff --git a/ui/src/components/WorktreeBanner.tsx b/ui/src/components/WorktreeBanner.tsx
new file mode 100644
index 00000000..6808b2da
--- /dev/null
+++ b/ui/src/components/WorktreeBanner.tsx
@@ -0,0 +1,25 @@
+import { getWorktreeUiBranding } from "../lib/worktree-branding";
+
+export function WorktreeBanner() {
+  const branding = getWorktreeUiBranding();
+  if (!branding) return null;
+
+  return (
+    <div
+      className="relative overflow-hidden border-b px-3 py-1.5 text-[11px] font-medium tracking-[0.2em] uppercase"
+      style={{
+        backgroundColor: branding.color,
+        color: branding.textColor,
+        borderColor: `${branding.textColor}22`,
+        boxShadow: `inset 0 -1px 0 ${branding.textColor}18`,
+        backgroundImage: `linear-gradient(90deg, ${branding.textColor}14, transparent 28%, transparent 72%, ${branding.textColor}12), repeating-linear-gradient(135deg, transparent 0 10px, ${branding.textColor}08 10px 20px)`,
+      }}
+    >
+      <div className="flex items-center gap-2 overflow-hidden whitespace-nowrap">
+        <span className="shrink-0 opacity-70">Worktree</span>
+        <span className="h-1.5 w-1.5 shrink-0 rounded-full bg-current opacity-70" aria-hidden="true" />
+        <span className="truncate font-semibold tracking-[0.12em]">{branding.name}</span>
+      </div>
+    </div>
+  );
+}
diff --git a/ui/src/lib/worktree-branding.ts b/ui/src/lib/worktree-branding.ts
new file mode 100644
index 00000000..6f6d8dc4
--- /dev/null
+++ b/ui/src/lib/worktree-branding.ts
@@ -0,0 +1,65 @@
+export type WorktreeUiBranding = {
+  enabled: true;
+  name: string;
+  color: string;
+  textColor: string;
+};
+
+function readMetaContent(name: string): string | null {
+  if (typeof document === "undefined") return null;
+  const element = document.querySelector(`meta[name="${name}"]`);
+  const content = element?.getAttribute("content")?.trim();
+  return content ? content : null;
+}
+
+function normalizeHexColor(value: string | null): string | null {
+  if (!value) return null;
+  const hex = value.startsWith("#") ? value.slice(1) : value;
+  if (/^[0-9a-fA-F]{3}$/.test(hex)) {
+    return `#${hex.split("").map((char) => `${char}${char}`).join("").toLowerCase()}`;
+  }
+  if (/^[0-9a-fA-F]{6}$/.test(hex)) {
+    return `#${hex.toLowerCase()}`;
+  }
+  return null;
+}
+
+function hexToRgb(color: string): { r: number; g: number; b: number } {
+  const normalized = normalizeHexColor(color) ?? "#000000";
+  return {
+    r: Number.parseInt(normalized.slice(1, 3), 16),
+    g: Number.parseInt(normalized.slice(3, 5), 16),
+    b: Number.parseInt(normalized.slice(5, 7), 16),
+  };
+}
+
+function relativeLuminanceChannel(value: number): number {
+  const normalized = value / 255;
+  return normalized <= 0.03928 ? normalized / 12.92 : ((normalized + 0.055) / 1.055) ** 2.4;
+}
+
+function pickReadableTextColor(background: string): string {
+  const { r, g, b } = hexToRgb(background);
+  const luminance =
+    (0.2126 * relativeLuminanceChannel(r)) +
+    (0.7152 * relativeLuminanceChannel(g)) +
+    (0.0722 * relativeLuminanceChannel(b));
+  const whiteContrast = 1.05 / (luminance + 0.05);
+  const blackContrast = (luminance + 0.05) / 0.05;
+  return whiteContrast >= blackContrast ? "#f8fafc" : "#111827";
+}
+
+export function getWorktreeUiBranding(): WorktreeUiBranding | null {
+  if (readMetaContent("paperclip-worktree-enabled") !== "true") return null;
+
+  const name = readMetaContent("paperclip-worktree-name");
+  const color = normalizeHexColor(readMetaContent("paperclip-worktree-color"));
+  if (!name || !color) return null;
+
+  return {
+    enabled: true,
+    name,
+    color,
+    textColor: normalizeHexColor(readMetaContent("paperclip-worktree-text-color")) ?? pickReadableTextColor(color),
+  };
+}

From 528505a04a1d7acfe341709403a2b5b50458bb4c Mon Sep 17 00:00:00 2001
From: Dotta <bippadotta@protonmail.com>
Date: Fri, 13 Mar 2026 11:53:56 -0500
Subject: [PATCH 23/28] fix: isolate codex home in worktrees

---
 .../2026-03-13-TOKEN-OPTIMIZATION-PLAN.md     |  14 ++
 docs/adapters/codex-local.md                  |   2 +
 .../codex-local/src/server/codex-home.ts      | 101 +++++++++
 .../codex-local/src/server/execute.ts         |  80 ++++++-
 ...08-46-token-optimization-implementation.md |   8 +
 .../src/__tests__/codex-local-execute.test.ts | 208 ++++++++++++++++++
 .../codex-local-skill-injection.test.ts       |  91 ++++++++
 7 files changed, 496 insertions(+), 8 deletions(-)
 create mode 100644 packages/adapters/codex-local/src/server/codex-home.ts
 create mode 100644 server/src/__tests__/codex-local-execute.test.ts
 create mode 100644 server/src/__tests__/codex-local-skill-injection.test.ts

diff --git a/doc/plans/2026-03-13-TOKEN-OPTIMIZATION-PLAN.md b/doc/plans/2026-03-13-TOKEN-OPTIMIZATION-PLAN.md
index e85cfdfc..7053e97f 100644
--- a/doc/plans/2026-03-13-TOKEN-OPTIMIZATION-PLAN.md
+++ b/doc/plans/2026-03-13-TOKEN-OPTIMIZATION-PLAN.md
@@ -118,6 +118,14 @@ Result:
 
 Local adapters inject repo skills into runtime skill directories.
 
+Important `codex_local` nuance:
+
+- Codex does not read skills directly from the active worktree.
+- Paperclip discovers repo skills from the current checkout, then symlinks them into `$CODEX_HOME/skills` or `~/.codex/skills`.
+- If an existing Paperclip skill symlink already points at another live checkout, the current implementation skips it instead of repointing it.
+- This can leave Codex using stale skill content from a different worktree even after Paperclip-side skill changes land.
+- That is both a correctness risk and a token-analysis risk, because runtime behavior may not reflect the instructions in the checkout being tested.
+
 Current repo skill sizes:
 
 - `skills/paperclip/SKILL.md`: 17,441 bytes
@@ -215,6 +223,8 @@ This is the right version of the discussion’s bootstrap idea.
 
 Static instructions and dynamic wake context have different cache behavior and should be modeled separately.
 
+For `codex_local`, this also requires isolating the Codex skill home per worktree or teaching Paperclip to repoint its own skill symlinks when the source checkout changes. Otherwise prompt and skill improvements in the active worktree may not reach the running agent.
+
 ### Success criteria
 
 - fresh-session prompts can remain richer without inflating every resumed heartbeat
@@ -305,6 +315,9 @@ Even when reuse is desirable, some sessions become too expensive to keep alive i
   - `para-memory-files`
   - `create-agent-adapter`
 - Expose active skill set in agent config and run metadata.
+- For `codex_local`, either:
+  - run with a worktree-specific `CODEX_HOME`, or
+  - treat Paperclip-owned Codex skill symlinks as repairable when they point at a different checkout
 
 ### Why
 
@@ -363,6 +376,7 @@ Initial targets:
 6. Rewrite `skills/paperclip/SKILL.md` around delta-fetch behavior.
 7. Add session rotation with carry-forward summaries.
 8. Replace global skill injection with explicit allowlists.
+9. Fix `codex_local` skill resolution so worktree-local skill changes reliably reach the runtime.
 
 ## Recommendation
 
diff --git a/docs/adapters/codex-local.md b/docs/adapters/codex-local.md
index 60725a49..ad187f75 100644
--- a/docs/adapters/codex-local.md
+++ b/docs/adapters/codex-local.md
@@ -30,6 +30,8 @@ Codex uses `previous_response_id` for session continuity. The adapter serializes
 
 The adapter symlinks Paperclip skills into the global Codex skills directory (`~/.codex/skills`). Existing user skills are not overwritten.
 
+When Paperclip is running inside a managed worktree instance (`PAPERCLIP_IN_WORKTREE=true`), the adapter instead uses a worktree-isolated `CODEX_HOME` under the Paperclip instance so Codex skills, sessions, logs, and other runtime state do not leak across checkouts. It seeds that isolated home from the user's main Codex home for shared auth/config continuity.
+
 For manual local CLI usage outside heartbeat runs (for example running as `codexcoder` directly), use:
 
 ```sh
diff --git a/packages/adapters/codex-local/src/server/codex-home.ts b/packages/adapters/codex-local/src/server/codex-home.ts
new file mode 100644
index 00000000..a182e998
--- /dev/null
+++ b/packages/adapters/codex-local/src/server/codex-home.ts
@@ -0,0 +1,101 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import type { AdapterExecutionContext } from "@paperclipai/adapter-utils";
+
+const TRUTHY_ENV_RE = /^(1|true|yes|on)$/i;
+const COPIED_SHARED_FILES = ["config.json", "config.toml", "instructions.md"] as const;
+const SYMLINKED_SHARED_FILES = ["auth.json"] as const;
+
+function nonEmpty(value: string | undefined): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+async function pathExists(candidate: string): Promise<boolean> {
+  return fs.access(candidate).then(() => true).catch(() => false);
+}
+
+export function resolveCodexHomeDir(env: NodeJS.ProcessEnv = process.env): string {
+  const fromEnv = nonEmpty(env.CODEX_HOME);
+  if (fromEnv) return path.resolve(fromEnv);
+  return path.join(os.homedir(), ".codex");
+}
+
+function isWorktreeMode(env: NodeJS.ProcessEnv): boolean {
+  return TRUTHY_ENV_RE.test(env.PAPERCLIP_IN_WORKTREE ?? "");
+}
+
+function resolveWorktreeCodexHomeDir(env: NodeJS.ProcessEnv): string | null {
+  if (!isWorktreeMode(env)) return null;
+  const paperclipHome = nonEmpty(env.PAPERCLIP_HOME);
+  if (!paperclipHome) return null;
+  const instanceId = nonEmpty(env.PAPERCLIP_INSTANCE_ID);
+  if (instanceId) {
+    return path.resolve(paperclipHome, "instances", instanceId, "codex-home");
+  }
+  return path.resolve(paperclipHome, "codex-home");
+}
+
+async function ensureParentDir(target: string): Promise<void> {
+  await fs.mkdir(path.dirname(target), { recursive: true });
+}
+
+async function ensureSymlink(target: string, source: string): Promise<void> {
+  const existing = await fs.lstat(target).catch(() => null);
+  if (!existing) {
+    await ensureParentDir(target);
+    await fs.symlink(source, target);
+    return;
+  }
+
+  if (!existing.isSymbolicLink()) {
+    return;
+  }
+
+  const linkedPath = await fs.readlink(target).catch(() => null);
+  if (!linkedPath) return;
+
+  const resolvedLinkedPath = path.resolve(path.dirname(target), linkedPath);
+  if (resolvedLinkedPath === source) return;
+
+  await fs.unlink(target);
+  await fs.symlink(source, target);
+}
+
+async function ensureCopiedFile(target: string, source: string): Promise<void> {
+  const existing = await fs.lstat(target).catch(() => null);
+  if (existing) return;
+  await ensureParentDir(target);
+  await fs.copyFile(source, target);
+}
+
+export async function prepareWorktreeCodexHome(
+  env: NodeJS.ProcessEnv,
+  onLog: AdapterExecutionContext["onLog"],
+): Promise<string | null> {
+  const targetHome = resolveWorktreeCodexHomeDir(env);
+  if (!targetHome) return null;
+
+  const sourceHome = resolveCodexHomeDir(env);
+  if (path.resolve(sourceHome) === path.resolve(targetHome)) return targetHome;
+
+  await fs.mkdir(targetHome, { recursive: true });
+
+  for (const name of SYMLINKED_SHARED_FILES) {
+    const source = path.join(sourceHome, name);
+    if (!(await pathExists(source))) continue;
+    await ensureSymlink(path.join(targetHome, name), source);
+  }
+
+  for (const name of COPIED_SHARED_FILES) {
+    const source = path.join(sourceHome, name);
+    if (!(await pathExists(source))) continue;
+    await ensureCopiedFile(path.join(targetHome, name), source);
+  }
+
+  await onLog(
+    "stderr",
+    `[paperclip] Using worktree-isolated Codex home "${targetHome}" (seeded from "${sourceHome}").\n`,
+  );
+  return targetHome;
+}
diff --git a/packages/adapters/codex-local/src/server/execute.ts b/packages/adapters/codex-local/src/server/execute.ts
index 1bccbc44..416f0e8e 100644
--- a/packages/adapters/codex-local/src/server/execute.ts
+++ b/packages/adapters/codex-local/src/server/execute.ts
@@ -1,5 +1,4 @@
 import fs from "node:fs/promises";
-import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import type { AdapterExecutionContext, AdapterExecutionResult } from "@paperclipai/adapter-utils";
@@ -22,6 +21,7 @@ import {
   runChildProcess,
 } from "@paperclipai/adapter-utils/server-utils";
 import { parseCodexJsonl, isCodexUnknownSessionError } from "./parse.js";
+import { prepareWorktreeCodexHome, resolveCodexHomeDir } from "./codex-home.js";
 
 const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
 const CODEX_ROLLOUT_NOISE_RE =
@@ -61,10 +61,36 @@ function resolveCodexBillingType(env: Record<string, string>): "api" | "subscrip
   return hasNonEmptyEnvValue(env, "OPENAI_API_KEY") ? "api" : "subscription";
 }
 
-function codexHomeDir(): string {
-  const fromEnv = process.env.CODEX_HOME;
-  if (typeof fromEnv === "string" && fromEnv.trim().length > 0) return fromEnv.trim();
-  return path.join(os.homedir(), ".codex");
+async function pathExists(candidate: string): Promise<boolean> {
+  return fs.access(candidate).then(() => true).catch(() => false);
+}
+
+async function isLikelyPaperclipRepoRoot(candidate: string): Promise<boolean> {
+  const [hasWorkspace, hasPackageJson, hasServerDir, hasAdapterUtilsDir] = await Promise.all([
+    pathExists(path.join(candidate, "pnpm-workspace.yaml")),
+    pathExists(path.join(candidate, "package.json")),
+    pathExists(path.join(candidate, "server")),
+    pathExists(path.join(candidate, "packages", "adapter-utils")),
+  ]);
+
+  return hasWorkspace && hasPackageJson && hasServerDir && hasAdapterUtilsDir;
+}
+
+async function isLikelyPaperclipRuntimeSkillSource(candidate: string, skillName: string): Promise<boolean> {
+  if (path.basename(candidate) !== skillName) return false;
+  const skillsRoot = path.dirname(candidate);
+  if (path.basename(skillsRoot) !== "skills") return false;
+  if (!(await pathExists(path.join(candidate, "SKILL.md")))) return false;
+
+  let cursor = path.dirname(skillsRoot);
+  for (let depth = 0; depth < 6; depth += 1) {
+    if (await isLikelyPaperclipRepoRoot(cursor)) return true;
+    const parent = path.dirname(cursor);
+    if (parent === cursor) break;
+    cursor = parent;
+  }
+
+  return false;
 }
 
 type EnsureCodexSkillsInjectedOptions = {
@@ -80,7 +106,7 @@ export async function ensureCodexSkillsInjected(
   const skillsEntries = options.skillsEntries ?? await listPaperclipSkillEntries(__moduleDir);
   if (skillsEntries.length === 0) return;
 
-  const skillsHome = options.skillsHome ?? path.join(codexHomeDir(), "skills");
+  const skillsHome = options.skillsHome ?? path.join(resolveCodexHomeDir(process.env), "skills");
   await fs.mkdir(skillsHome, { recursive: true });
   const removedSkills = await removeMaintainerOnlySkillSymlinks(
     skillsHome,
@@ -97,6 +123,31 @@ export async function ensureCodexSkillsInjected(
     const target = path.join(skillsHome, entry.name);
 
     try {
+      const existing = await fs.lstat(target).catch(() => null);
+      if (existing?.isSymbolicLink()) {
+        const linkedPath = await fs.readlink(target).catch(() => null);
+        const resolvedLinkedPath = linkedPath
+          ? path.resolve(path.dirname(target), linkedPath)
+          : null;
+        if (
+          resolvedLinkedPath &&
+          resolvedLinkedPath !== entry.source &&
+          (await isLikelyPaperclipRuntimeSkillSource(resolvedLinkedPath, entry.name))
+        ) {
+          await fs.unlink(target);
+          if (linkSkill) {
+            await linkSkill(entry.source, target);
+          } else {
+            await fs.symlink(entry.source, target);
+          }
+          await onLog(
+            "stderr",
+            `[paperclip] Repaired Codex skill "${entry.name}" into ${skillsHome}\n`,
+          );
+          continue;
+        }
+      }
+
       const result = await ensurePaperclipSkillSymlink(entry.source, target, linkSkill);
       if (result === "skipped") continue;
 
@@ -161,12 +212,25 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   const useConfiguredInsteadOfAgentHome = workspaceSource === "agent_home" && configuredCwd.length > 0;
   const effectiveWorkspaceCwd = useConfiguredInsteadOfAgentHome ? "" : workspaceCwd;
   const cwd = effectiveWorkspaceCwd || configuredCwd || process.cwd();
-  await ensureAbsoluteDirectory(cwd, { createIfMissing: true });
-  await ensureCodexSkillsInjected(onLog);
   const envConfig = parseObject(config.env);
+  const configuredCodexHome =
+    typeof envConfig.CODEX_HOME === "string" && envConfig.CODEX_HOME.trim().length > 0
+      ? path.resolve(envConfig.CODEX_HOME.trim())
+      : null;
+  await ensureAbsoluteDirectory(cwd, { createIfMissing: true });
+  const preparedWorktreeCodexHome =
+    configuredCodexHome ? null : await prepareWorktreeCodexHome(process.env, onLog);
+  const effectiveCodexHome = configuredCodexHome ?? preparedWorktreeCodexHome;
+  await ensureCodexSkillsInjected(
+    onLog,
+    effectiveCodexHome ? { skillsHome: path.join(effectiveCodexHome, "skills") } : {},
+  );
   const hasExplicitApiKey =
     typeof envConfig.PAPERCLIP_API_KEY === "string" && envConfig.PAPERCLIP_API_KEY.trim().length > 0;
   const env: Record<string, string> = { ...buildPaperclipEnv(agent) };
+  if (effectiveCodexHome) {
+    env.CODEX_HOME = effectiveCodexHome;
+  }
   env.PAPERCLIP_RUN_ID = runId;
   const wakeTaskId =
     (typeof context.taskId === "string" && context.taskId.trim().length > 0 && context.taskId.trim()) ||
diff --git a/report/2026-03-13-08-46-token-optimization-implementation.md b/report/2026-03-13-08-46-token-optimization-implementation.md
index 9bee83ca..7cfd5ad6 100644
--- a/report/2026-03-13-08-46-token-optimization-implementation.md
+++ b/report/2026-03-13-08-46-token-optimization-implementation.md
@@ -14,6 +14,14 @@ The main behavior changes are:
 - The agent config UI now explains the difference between bootstrap prompts and heartbeat prompts and warns about prompt churn.
 - Runtime skill defaults now include `paperclip`, `para-memory-files`, and `paperclip-create-agent`. `create-agent-adapter` was moved to `.agents/skills/create-agent-adapter`.
 
+Important follow-up finding from real-run review:
+
+- `codex_local` currently injects Paperclip skills into the shared Codex skills home (`$CODEX_HOME/skills` or `~/.codex/skills`) rather than mounting a worktree-local skill directory.
+- If a Paperclip-owned skill symlink already points at another live checkout, the adapter currently skips it instead of repointing it.
+- In practice, this means a worktree can contain newer `skills/paperclip/SKILL.md` guidance while Codex still follows an older checkout's skill content.
+- That likely explains why PAP-507 still showed full issue/comment reload behavior even though the incremental context work was already implemented in this branch.
+- This should be treated as a separate follow-up item for `codex_local` skill isolation or symlink repair.
+
 Files with the most important implementation work:
 
 - `server/src/services/heartbeat.ts`
diff --git a/server/src/__tests__/codex-local-execute.test.ts b/server/src/__tests__/codex-local-execute.test.ts
new file mode 100644
index 00000000..1dfcb3b7
--- /dev/null
+++ b/server/src/__tests__/codex-local-execute.test.ts
@@ -0,0 +1,208 @@
+import { describe, expect, it } from "vitest";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { execute } from "@paperclipai/adapter-codex-local/server";
+
+async function writeFakeCodexCommand(commandPath: string): Promise<void> {
+  const script = `#!/usr/bin/env node
+const fs = require("node:fs");
+
+const capturePath = process.env.PAPERCLIP_TEST_CAPTURE_PATH;
+const payload = {
+  argv: process.argv.slice(2),
+  prompt: fs.readFileSync(0, "utf8"),
+  codexHome: process.env.CODEX_HOME || null,
+  paperclipEnvKeys: Object.keys(process.env)
+    .filter((key) => key.startsWith("PAPERCLIP_"))
+    .sort(),
+};
+if (capturePath) {
+  fs.writeFileSync(capturePath, JSON.stringify(payload), "utf8");
+}
+console.log(JSON.stringify({ type: "thread.started", thread_id: "codex-session-1" }));
+console.log(JSON.stringify({ type: "item.completed", item: { type: "agent_message", text: "hello" } }));
+console.log(JSON.stringify({ type: "turn.completed", usage: { input_tokens: 1, cached_input_tokens: 0, output_tokens: 1 } }));
+`;
+  await fs.writeFile(commandPath, script, "utf8");
+  await fs.chmod(commandPath, 0o755);
+}
+
+type CapturePayload = {
+  argv: string[];
+  prompt: string;
+  codexHome: string | null;
+  paperclipEnvKeys: string[];
+};
+
+describe("codex execute", () => {
+  it("uses a worktree-isolated CODEX_HOME while preserving shared auth and config", async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-codex-execute-"));
+    const workspace = path.join(root, "workspace");
+    const commandPath = path.join(root, "codex");
+    const capturePath = path.join(root, "capture.json");
+    const sharedCodexHome = path.join(root, "shared-codex-home");
+    const paperclipHome = path.join(root, "paperclip-home");
+    const isolatedCodexHome = path.join(paperclipHome, "instances", "worktree-1", "codex-home");
+    await fs.mkdir(workspace, { recursive: true });
+    await fs.mkdir(sharedCodexHome, { recursive: true });
+    await fs.writeFile(path.join(sharedCodexHome, "auth.json"), '{"token":"shared"}\n', "utf8");
+    await fs.writeFile(path.join(sharedCodexHome, "config.toml"), 'model = "codex-mini-latest"\n', "utf8");
+    await writeFakeCodexCommand(commandPath);
+
+    const previousHome = process.env.HOME;
+    const previousPaperclipHome = process.env.PAPERCLIP_HOME;
+    const previousPaperclipInstanceId = process.env.PAPERCLIP_INSTANCE_ID;
+    const previousPaperclipInWorktree = process.env.PAPERCLIP_IN_WORKTREE;
+    const previousCodexHome = process.env.CODEX_HOME;
+    process.env.HOME = root;
+    process.env.PAPERCLIP_HOME = paperclipHome;
+    process.env.PAPERCLIP_INSTANCE_ID = "worktree-1";
+    process.env.PAPERCLIP_IN_WORKTREE = "true";
+    process.env.CODEX_HOME = sharedCodexHome;
+
+    try {
+      const result = await execute({
+        runId: "run-1",
+        agent: {
+          id: "agent-1",
+          companyId: "company-1",
+          name: "Codex Coder",
+          adapterType: "codex_local",
+          adapterConfig: {},
+        },
+        runtime: {
+          sessionId: null,
+          sessionParams: null,
+          sessionDisplayId: null,
+          taskKey: null,
+        },
+        config: {
+          command: commandPath,
+          cwd: workspace,
+          env: {
+            PAPERCLIP_TEST_CAPTURE_PATH: capturePath,
+          },
+          promptTemplate: "Follow the paperclip heartbeat.",
+        },
+        context: {},
+        authToken: "run-jwt-token",
+        onLog: async () => {},
+      });
+
+      expect(result.exitCode).toBe(0);
+      expect(result.errorMessage).toBeNull();
+
+      const capture = JSON.parse(await fs.readFile(capturePath, "utf8")) as CapturePayload;
+      expect(capture.codexHome).toBe(isolatedCodexHome);
+      expect(capture.argv).toEqual(expect.arrayContaining(["exec", "--json", "-"]));
+      expect(capture.prompt).toContain("Follow the paperclip heartbeat.");
+      expect(capture.paperclipEnvKeys).toEqual(
+        expect.arrayContaining([
+          "PAPERCLIP_AGENT_ID",
+          "PAPERCLIP_API_KEY",
+          "PAPERCLIP_API_URL",
+          "PAPERCLIP_COMPANY_ID",
+          "PAPERCLIP_RUN_ID",
+        ]),
+      );
+
+      const isolatedAuth = path.join(isolatedCodexHome, "auth.json");
+      const isolatedConfig = path.join(isolatedCodexHome, "config.toml");
+      const isolatedSkill = path.join(isolatedCodexHome, "skills", "paperclip");
+
+      expect((await fs.lstat(isolatedAuth)).isSymbolicLink()).toBe(true);
+      expect(await fs.realpath(isolatedAuth)).toBe(await fs.realpath(path.join(sharedCodexHome, "auth.json")));
+      expect((await fs.lstat(isolatedConfig)).isFile()).toBe(true);
+      expect(await fs.readFile(isolatedConfig, "utf8")).toBe('model = "codex-mini-latest"\n');
+      expect((await fs.lstat(isolatedSkill)).isSymbolicLink()).toBe(true);
+    } finally {
+      if (previousHome === undefined) delete process.env.HOME;
+      else process.env.HOME = previousHome;
+      if (previousPaperclipHome === undefined) delete process.env.PAPERCLIP_HOME;
+      else process.env.PAPERCLIP_HOME = previousPaperclipHome;
+      if (previousPaperclipInstanceId === undefined) delete process.env.PAPERCLIP_INSTANCE_ID;
+      else process.env.PAPERCLIP_INSTANCE_ID = previousPaperclipInstanceId;
+      if (previousPaperclipInWorktree === undefined) delete process.env.PAPERCLIP_IN_WORKTREE;
+      else process.env.PAPERCLIP_IN_WORKTREE = previousPaperclipInWorktree;
+      if (previousCodexHome === undefined) delete process.env.CODEX_HOME;
+      else process.env.CODEX_HOME = previousCodexHome;
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it("respects an explicit CODEX_HOME config override even in worktree mode", async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-codex-execute-explicit-"));
+    const workspace = path.join(root, "workspace");
+    const commandPath = path.join(root, "codex");
+    const capturePath = path.join(root, "capture.json");
+    const sharedCodexHome = path.join(root, "shared-codex-home");
+    const explicitCodexHome = path.join(root, "explicit-codex-home");
+    const paperclipHome = path.join(root, "paperclip-home");
+    await fs.mkdir(workspace, { recursive: true });
+    await fs.mkdir(sharedCodexHome, { recursive: true });
+    await fs.writeFile(path.join(sharedCodexHome, "auth.json"), '{"token":"shared"}\n', "utf8");
+    await writeFakeCodexCommand(commandPath);
+
+    const previousHome = process.env.HOME;
+    const previousPaperclipHome = process.env.PAPERCLIP_HOME;
+    const previousPaperclipInstanceId = process.env.PAPERCLIP_INSTANCE_ID;
+    const previousPaperclipInWorktree = process.env.PAPERCLIP_IN_WORKTREE;
+    const previousCodexHome = process.env.CODEX_HOME;
+    process.env.HOME = root;
+    process.env.PAPERCLIP_HOME = paperclipHome;
+    process.env.PAPERCLIP_INSTANCE_ID = "worktree-1";
+    process.env.PAPERCLIP_IN_WORKTREE = "true";
+    process.env.CODEX_HOME = sharedCodexHome;
+
+    try {
+      const result = await execute({
+        runId: "run-2",
+        agent: {
+          id: "agent-1",
+          companyId: "company-1",
+          name: "Codex Coder",
+          adapterType: "codex_local",
+          adapterConfig: {},
+        },
+        runtime: {
+          sessionId: null,
+          sessionParams: null,
+          sessionDisplayId: null,
+          taskKey: null,
+        },
+        config: {
+          command: commandPath,
+          cwd: workspace,
+          env: {
+            PAPERCLIP_TEST_CAPTURE_PATH: capturePath,
+            CODEX_HOME: explicitCodexHome,
+          },
+          promptTemplate: "Follow the paperclip heartbeat.",
+        },
+        context: {},
+        authToken: "run-jwt-token",
+        onLog: async () => {},
+      });
+
+      expect(result.exitCode).toBe(0);
+      expect(result.errorMessage).toBeNull();
+
+      const capture = JSON.parse(await fs.readFile(capturePath, "utf8")) as CapturePayload;
+      expect(capture.codexHome).toBe(explicitCodexHome);
+      await expect(fs.lstat(path.join(paperclipHome, "instances", "worktree-1", "codex-home"))).rejects.toThrow();
+    } finally {
+      if (previousHome === undefined) delete process.env.HOME;
+      else process.env.HOME = previousHome;
+      if (previousPaperclipHome === undefined) delete process.env.PAPERCLIP_HOME;
+      else process.env.PAPERCLIP_HOME = previousPaperclipHome;
+      if (previousPaperclipInstanceId === undefined) delete process.env.PAPERCLIP_INSTANCE_ID;
+      else process.env.PAPERCLIP_INSTANCE_ID = previousPaperclipInstanceId;
+      if (previousPaperclipInWorktree === undefined) delete process.env.PAPERCLIP_IN_WORKTREE;
+      else process.env.PAPERCLIP_IN_WORKTREE = previousPaperclipInWorktree;
+      if (previousCodexHome === undefined) delete process.env.CODEX_HOME;
+      else process.env.CODEX_HOME = previousCodexHome;
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+});
diff --git a/server/src/__tests__/codex-local-skill-injection.test.ts b/server/src/__tests__/codex-local-skill-injection.test.ts
new file mode 100644
index 00000000..bbbaec63
--- /dev/null
+++ b/server/src/__tests__/codex-local-skill-injection.test.ts
@@ -0,0 +1,91 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { ensureCodexSkillsInjected } from "@paperclipai/adapter-codex-local/server";
+
+async function makeTempDir(prefix: string): Promise<string> {
+  return fs.mkdtemp(path.join(os.tmpdir(), prefix));
+}
+
+async function createPaperclipRepoSkill(root: string, skillName: string) {
+  await fs.mkdir(path.join(root, "server"), { recursive: true });
+  await fs.mkdir(path.join(root, "packages", "adapter-utils"), { recursive: true });
+  await fs.mkdir(path.join(root, "skills", skillName), { recursive: true });
+  await fs.writeFile(path.join(root, "pnpm-workspace.yaml"), "packages:\n  - packages/*\n", "utf8");
+  await fs.writeFile(path.join(root, "package.json"), '{"name":"paperclip"}\n', "utf8");
+  await fs.writeFile(
+    path.join(root, "skills", skillName, "SKILL.md"),
+    `---\nname: ${skillName}\n---\n`,
+    "utf8",
+  );
+}
+
+async function createCustomSkill(root: string, skillName: string) {
+  await fs.mkdir(path.join(root, "custom", skillName), { recursive: true });
+  await fs.writeFile(
+    path.join(root, "custom", skillName, "SKILL.md"),
+    `---\nname: ${skillName}\n---\n`,
+    "utf8",
+  );
+}
+
+describe("codex local adapter skill injection", () => {
+  const cleanupDirs = new Set<string>();
+
+  afterEach(async () => {
+    await Promise.all(Array.from(cleanupDirs).map((dir) => fs.rm(dir, { recursive: true, force: true })));
+    cleanupDirs.clear();
+  });
+
+  it("repairs a Codex Paperclip skill symlink that still points at another live checkout", async () => {
+    const currentRepo = await makeTempDir("paperclip-codex-current-");
+    const oldRepo = await makeTempDir("paperclip-codex-old-");
+    const skillsHome = await makeTempDir("paperclip-codex-home-");
+    cleanupDirs.add(currentRepo);
+    cleanupDirs.add(oldRepo);
+    cleanupDirs.add(skillsHome);
+
+    await createPaperclipRepoSkill(currentRepo, "paperclip");
+    await createPaperclipRepoSkill(oldRepo, "paperclip");
+    await fs.symlink(path.join(oldRepo, "skills", "paperclip"), path.join(skillsHome, "paperclip"));
+
+    const logs: string[] = [];
+    await ensureCodexSkillsInjected(
+      async (_stream, chunk) => {
+        logs.push(chunk);
+      },
+      {
+        skillsHome,
+        skillsEntries: [{ name: "paperclip", source: path.join(currentRepo, "skills", "paperclip") }],
+      },
+    );
+
+    expect(await fs.realpath(path.join(skillsHome, "paperclip"))).toBe(
+      await fs.realpath(path.join(currentRepo, "skills", "paperclip")),
+    );
+    expect(logs.some((line) => line.includes('Repaired Codex skill "paperclip"'))).toBe(true);
+  });
+
+  it("preserves a custom Codex skill symlink outside Paperclip repo checkouts", async () => {
+    const currentRepo = await makeTempDir("paperclip-codex-current-");
+    const customRoot = await makeTempDir("paperclip-codex-custom-");
+    const skillsHome = await makeTempDir("paperclip-codex-home-");
+    cleanupDirs.add(currentRepo);
+    cleanupDirs.add(customRoot);
+    cleanupDirs.add(skillsHome);
+
+    await createPaperclipRepoSkill(currentRepo, "paperclip");
+    await createCustomSkill(customRoot, "paperclip");
+    await fs.symlink(path.join(customRoot, "custom", "paperclip"), path.join(skillsHome, "paperclip"));
+
+    await ensureCodexSkillsInjected(async () => {}, {
+      skillsHome,
+      skillsEntries: [{ name: "paperclip", source: path.join(currentRepo, "skills", "paperclip") }],
+    });
+
+    expect(await fs.realpath(path.join(skillsHome, "paperclip"))).toBe(
+      await fs.realpath(path.join(customRoot, "custom", "paperclip")),
+    );
+  });
+});

From c1430e7b06e57b4c40efe0758052f236607528ef Mon Sep 17 00:00:00 2001
From: Dotta <bippadotta@protonmail.com>
Date: Fri, 13 Mar 2026 14:37:44 -0500
Subject: [PATCH 24/28] docs: add paperclip skill tightening plan

Co-Authored-By: Paperclip <noreply@paperclip.ing>
---
 ...6-03-13-paperclip-skill-tightening-plan.md | 186 ++++++++++++++++++
 1 file changed, 186 insertions(+)
 create mode 100644 doc/plans/2026-03-13-paperclip-skill-tightening-plan.md

diff --git a/doc/plans/2026-03-13-paperclip-skill-tightening-plan.md b/doc/plans/2026-03-13-paperclip-skill-tightening-plan.md
new file mode 100644
index 00000000..68d4ad3c
--- /dev/null
+++ b/doc/plans/2026-03-13-paperclip-skill-tightening-plan.md
@@ -0,0 +1,186 @@
+# Paperclip Skill Tightening Plan
+
+## Status
+
+Deferred follow-up. Do not include in the current token-optimization PR beyond documenting the plan.
+
+## Why This Is Deferred
+
+The `paperclip` skill is part of the critical control-plane safety surface. Tightening it may reduce fresh-session token use, but it also carries prompt-regression risk. We do not yet have evals that would let us safely prove behavior preservation across assignment handling, checkout rules, comment etiquette, approval workflows, and escalation paths.
+
+The current PR should ship the lower-risk infrastructure wins first:
+
+- telemetry normalization
+- safe session reuse
+- incremental issue/comment context
+- bootstrap versus heartbeat prompt separation
+- Codex worktree isolation
+
+## Current Problem
+
+Fresh runs still spend substantial input tokens even after the context-path fixes. The remaining large startup cost appears to come from loading the full `paperclip` skill and related instruction surface into context at run start.
+
+The skill currently mixes three kinds of content in one file:
+
+- hot-path heartbeat procedure used on nearly every run
+- critical policy and safety invariants
+- rare workflow/reference material that most runs do not need
+
+That structure is safe but expensive.
+
+## Goals
+
+- reduce first-run instruction tokens without weakening agent safety
+- preserve all current Paperclip control-plane capabilities
+- keep common heartbeat behavior explicit and easy for agents to follow
+- move rare workflows and reference material out of the hot path
+- create a structure that can later be evaluated systematically
+
+## Non-Goals
+
+- changing Paperclip API semantics
+- removing required governance rules
+- deleting rare workflows
+- changing agent defaults in the current PR
+
+## Recommended Direction
+
+### 1. Split Hot Path From Lookup Material
+
+Restructure the skill into:
+
+- an always-loaded core section for the common heartbeat loop
+- on-demand material for infrequent workflows and deep reference
+
+The core should cover only what is needed on nearly every wake:
+
+- auth and required headers
+- inbox-first assignment retrieval
+- mandatory checkout behavior
+- `heartbeat-context` first
+- incremental comment retrieval rules
+- mention/self-assign exception
+- blocked-task dedup
+- status/comment/release expectations before exit
+
+### 2. Normalize The Skill Around One Canonical Procedure
+
+The same rules are currently expressed multiple times across:
+
+- heartbeat steps
+- critical rules
+- endpoint reference
+- workflow examples
+
+Refactor so each operational fact has one primary home:
+
+- procedure
+- invariant list
+- appendix/reference
+
+This reduces prompt weight and lowers the chance of internal instruction drift.
+
+### 3. Compress Prose Into High-Signal Instruction Forms
+
+Rewrite the hot path using compact operational forms:
+
+- short ordered checklist
+- flat invariant list
+- minimal examples only where ambiguity would be risky
+
+Reduce:
+
+- narrative explanation
+- repeated warnings already covered elsewhere
+- large example payloads for common operations
+- long endpoint matrices in the main body
+
+### 4. Move Rare Workflows Behind Explicit Triggers
+
+These workflows should remain available but should not dominate fresh-run context:
+
+- OpenClaw invite flow
+- project setup flow
+- planning `<plan/>` writeback flow
+- instructions-path update flow
+- detailed link-formatting examples
+
+Recommended approach:
+
+- keep a short pointer in the main skill
+- move detailed procedures into sibling skills or referenced docs that agents read only when needed
+
+### 5. Separate Policy From Reference
+
+The skill should distinguish:
+
+- mandatory operating rules
+- endpoint lookup/reference
+- business-process playbooks
+
+That separation makes it easier to evaluate prompt changes later and lets adapters or orchestration choose what must always be loaded.
+
+## Proposed Target Structure
+
+1. Purpose and authentication
+2. Compact heartbeat procedure
+3. Hard invariants
+4. Required comment/update style
+5. Triggered workflow index
+6. Appendix/reference
+
+## Rollout Plan
+
+### Phase 1. Inventory And Measure
+
+- annotate the current skill by section and estimate token weight
+- identify which sections are truly hot-path versus rare
+- capture representative runs to compare before/after prompt size and behavior
+
+### Phase 2. Structural Refactor Without Semantic Changes
+
+- rewrite the main skill into the target structure
+- preserve all existing rules and capabilities
+- move rare workflow details into referenced companion material
+- keep wording changes conservative
+
+### Phase 3. Validate Against Real Scenarios
+
+Run scenario checks for:
+
+- normal assigned heartbeat
+- comment-triggered wake
+- blocked-task dedup behavior
+- approval-resolution wake
+- delegation/subtask creation
+- board handoff back to user
+- plan-request handling
+
+### Phase 4. Decide Default Loading Strategy
+
+After validation, decide whether:
+
+- the entire main skill still loads by default, or
+- only the compact core loads by default and rare sections are fetched on demand
+
+Do not change this loading policy without validation.
+
+## Risks
+
+- prompt degradation on control-plane safety rules
+- agents forgetting rare but important workflows
+- accidental removal of repeated wording that was carrying useful behavior
+- introducing ambiguous instruction precedence between the core skill and companion materials
+
+## Preconditions Before Implementation
+
+- define acceptance scenarios for control-plane correctness
+- add at least lightweight eval or scripted scenario coverage for key Paperclip flows
+- confirm how adapter/bootstrap layering should load skill content versus references
+
+## Success Criteria
+
+- materially lower first-run input tokens for Paperclip-coordinated agents
+- no regression in checkout discipline, issue updates, blocked handling, or delegation
+- no increase in malformed API usage or ownership mistakes
+- agents still complete rare workflows correctly when explicitly asked

From a393db78b40cac03ccc4eeba470e8c5edd21971d Mon Sep 17 00:00:00 2001
From: Dotta <bippadotta@protonmail.com>
Date: Fri, 13 Mar 2026 14:53:30 -0500
Subject: [PATCH 25/28] fix: address greptile follow-up

Co-Authored-By: Paperclip <noreply@paperclip.ing>
---
 .../codex-local/src/server/codex-home.ts      |  2 +-
 .../codex-local/src/server/execute.ts         |  6 +--
 packages/shared/src/validators/agent.ts       |  5 ++-
 server/src/services/issues.ts                 | 38 ++++++++++---------
 4 files changed, 26 insertions(+), 25 deletions(-)

diff --git a/packages/adapters/codex-local/src/server/codex-home.ts b/packages/adapters/codex-local/src/server/codex-home.ts
index a182e998..de037d6a 100644
--- a/packages/adapters/codex-local/src/server/codex-home.ts
+++ b/packages/adapters/codex-local/src/server/codex-home.ts
@@ -11,7 +11,7 @@ function nonEmpty(value: string | undefined): string | null {
   return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
 }
 
-async function pathExists(candidate: string): Promise<boolean> {
+export async function pathExists(candidate: string): Promise<boolean> {
   return fs.access(candidate).then(() => true).catch(() => false);
 }
 
diff --git a/packages/adapters/codex-local/src/server/execute.ts b/packages/adapters/codex-local/src/server/execute.ts
index 416f0e8e..d4b3da46 100644
--- a/packages/adapters/codex-local/src/server/execute.ts
+++ b/packages/adapters/codex-local/src/server/execute.ts
@@ -21,7 +21,7 @@ import {
   runChildProcess,
 } from "@paperclipai/adapter-utils/server-utils";
 import { parseCodexJsonl, isCodexUnknownSessionError } from "./parse.js";
-import { prepareWorktreeCodexHome, resolveCodexHomeDir } from "./codex-home.js";
+import { pathExists, prepareWorktreeCodexHome, resolveCodexHomeDir } from "./codex-home.js";
 
 const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
 const CODEX_ROLLOUT_NOISE_RE =
@@ -61,10 +61,6 @@ function resolveCodexBillingType(env: Record<string, string>): "api" | "subscrip
   return hasNonEmptyEnvValue(env, "OPENAI_API_KEY") ? "api" : "subscription";
 }
 
-async function pathExists(candidate: string): Promise<boolean> {
-  return fs.access(candidate).then(() => true).catch(() => false);
-}
-
 async function isLikelyPaperclipRepoRoot(candidate: string): Promise<boolean> {
   const [hasWorkspace, hasPackageJson, hasServerDir, hasAdapterUtilsDir] = await Promise.all([
     pathExists(path.join(candidate, "pnpm-workspace.yaml")),
diff --git a/packages/shared/src/validators/agent.ts b/packages/shared/src/validators/agent.ts
index dae54754..f703f036 100644
--- a/packages/shared/src/validators/agent.ts
+++ b/packages/shared/src/validators/agent.ts
@@ -78,7 +78,10 @@ export const wakeAgentSchema = z.object({
   reason: z.string().optional().nullable(),
   payload: z.record(z.unknown()).optional().nullable(),
   idempotencyKey: z.string().optional().nullable(),
-  forceFreshSession: z.boolean().optional().default(false),
+  forceFreshSession: z.preprocess(
+    (value) => (value === null ? undefined : value),
+    z.boolean().optional().default(false),
+  ),
 });
 
 export type WakeAgent = z.infer<typeof wakeAgentSchema>;
diff --git a/server/src/services/issues.ts b/server/src/services/issues.ts
index c42ac02a..ecff7c3c 100644
--- a/server/src/services/issues.ts
+++ b/server/src/services/issues.ts
@@ -1115,26 +1115,28 @@ export function issueService(db: Db) {
     },
 
     getCommentCursor: async (issueId: string) => {
-      const latest = await db
-        .select({
-          latestCommentId: issueComments.id,
-          latestCommentAt: issueComments.createdAt,
-        })
-        .from(issueComments)
-        .where(eq(issueComments.issueId, issueId))
-        .orderBy(desc(issueComments.createdAt), desc(issueComments.id))
-        .limit(1)
-        .then((rows) => rows[0] ?? null);
-
-      const [{ totalComments }] = await db
-        .select({
-          totalComments: sql<number>`count(*)::int`,
-        })
-        .from(issueComments)
-        .where(eq(issueComments.issueId, issueId));
+      const [latest, countRow] = await Promise.all([
+        db
+          .select({
+            latestCommentId: issueComments.id,
+            latestCommentAt: issueComments.createdAt,
+          })
+          .from(issueComments)
+          .where(eq(issueComments.issueId, issueId))
+          .orderBy(desc(issueComments.createdAt), desc(issueComments.id))
+          .limit(1)
+          .then((rows) => rows[0] ?? null),
+        db
+          .select({
+            totalComments: sql<number>`count(*)::int`,
+          })
+          .from(issueComments)
+          .where(eq(issueComments.issueId, issueId))
+          .then((rows) => rows[0] ?? null),
+      ]);
 
       return {
-        totalComments: Number(totalComments ?? 0),
+        totalComments: Number(countRow?.totalComments ?? 0),
         latestCommentId: latest?.latestCommentId ?? null,
         latestCommentAt: latest?.latestCommentAt ?? null,
       };

From aa799bba4cd22f698d85ece17a94bd58add9ee9e Mon Sep 17 00:00:00 2001
From: Dotta <bippadotta@protonmail.com>
Date: Fri, 13 Mar 2026 14:24:06 -0500
Subject: [PATCH 26/28] Fix worktree seed source selection

Co-Authored-By: Paperclip <noreply@paperclip.ing>
---
 cli/src/__tests__/worktree.test.ts | 54 ++++++++++++++++++++++++++++++
 cli/src/commands/worktree.ts       |  9 ++++-
 doc/DEVELOPING.md                  |  2 +-
 3 files changed, 63 insertions(+), 2 deletions(-)

diff --git a/cli/src/__tests__/worktree.test.ts b/cli/src/__tests__/worktree.test.ts
index fe325cd2..b6e2eb47 100644
--- a/cli/src/__tests__/worktree.test.ts
+++ b/cli/src/__tests__/worktree.test.ts
@@ -7,6 +7,7 @@ import {
   copyGitHooksToWorktreeGitDir,
   copySeededSecretsKey,
   rebindWorkspaceCwd,
+  resolveSourceConfigPath,
   resolveGitWorktreeAddArgs,
   resolveWorktreeMakeTargetPath,
   worktreeInitCommand,
@@ -305,6 +306,59 @@ describe("worktree helpers", () => {
     }
   });
 
+  it("defaults the seed source config to the current repo-local Paperclip config", () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-worktree-source-config-"));
+    const repoRoot = path.join(tempRoot, "repo");
+    const localConfigPath = path.join(repoRoot, ".paperclip", "config.json");
+    const originalCwd = process.cwd();
+    const originalPaperclipConfig = process.env.PAPERCLIP_CONFIG;
+
+    try {
+      fs.mkdirSync(path.dirname(localConfigPath), { recursive: true });
+      fs.writeFileSync(localConfigPath, JSON.stringify(buildSourceConfig()), "utf8");
+      delete process.env.PAPERCLIP_CONFIG;
+      process.chdir(repoRoot);
+
+      expect(fs.realpathSync(resolveSourceConfigPath({}))).toBe(fs.realpathSync(localConfigPath));
+    } finally {
+      process.chdir(originalCwd);
+      if (originalPaperclipConfig === undefined) {
+        delete process.env.PAPERCLIP_CONFIG;
+      } else {
+        process.env.PAPERCLIP_CONFIG = originalPaperclipConfig;
+      }
+      fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("preserves the source config path across worktree:make cwd changes", () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-worktree-source-override-"));
+    const sourceConfigPath = path.join(tempRoot, "source", "config.json");
+    const targetRoot = path.join(tempRoot, "target");
+    const originalCwd = process.cwd();
+    const originalPaperclipConfig = process.env.PAPERCLIP_CONFIG;
+
+    try {
+      fs.mkdirSync(path.dirname(sourceConfigPath), { recursive: true });
+      fs.mkdirSync(targetRoot, { recursive: true });
+      fs.writeFileSync(sourceConfigPath, JSON.stringify(buildSourceConfig()), "utf8");
+      delete process.env.PAPERCLIP_CONFIG;
+      process.chdir(targetRoot);
+
+      expect(resolveSourceConfigPath({ sourceConfigPathOverride: sourceConfigPath })).toBe(
+        path.resolve(sourceConfigPath),
+      );
+    } finally {
+      process.chdir(originalCwd);
+      if (originalPaperclipConfig === undefined) {
+        delete process.env.PAPERCLIP_CONFIG;
+      } else {
+        process.env.PAPERCLIP_CONFIG = originalPaperclipConfig;
+      }
+      fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+  });
+
   it("rebinds same-repo workspace paths onto the current worktree root", () => {
     expect(
       rebindWorkspaceCwd({
diff --git a/cli/src/commands/worktree.ts b/cli/src/commands/worktree.ts
index fca320b9..b77317fd 100644
--- a/cli/src/commands/worktree.ts
+++ b/cli/src/commands/worktree.ts
@@ -56,6 +56,7 @@ type WorktreeInitOptions = {
   fromConfig?: string;
   fromDataDir?: string;
   fromInstance?: string;
+  sourceConfigPathOverride?: string;
   serverPort?: number;
   dbPort?: number;
   seed?: boolean;
@@ -426,8 +427,12 @@ async function rebindSeededProjectWorkspaces(input: {
   }
 }
 
-function resolveSourceConfigPath(opts: WorktreeInitOptions): string {
+export function resolveSourceConfigPath(opts: WorktreeInitOptions): string {
+  if (opts.sourceConfigPathOverride) return path.resolve(opts.sourceConfigPathOverride);
   if (opts.fromConfig) return path.resolve(opts.fromConfig);
+  if (!opts.fromDataDir && !opts.fromInstance) {
+    return resolveConfigPath();
+  }
   const sourceHome = path.resolve(expandHomePrefix(opts.fromDataDir ?? "~/.paperclip"));
   const sourceInstanceId = sanitizeWorktreeInstanceId(opts.fromInstance ?? "default");
   return path.resolve(sourceHome, "instances", sourceInstanceId, "config.json");
@@ -751,6 +756,7 @@ export async function worktreeMakeCommand(nameArg: string, opts: WorktreeMakeOpt
   const name = resolveWorktreeMakeName(nameArg);
   const startPoint = resolveWorktreeStartPoint(opts.startPoint);
   const sourceCwd = process.cwd();
+  const sourceConfigPath = resolveSourceConfigPath(opts);
   const targetPath = resolveWorktreeMakeTargetPath(name);
   if (existsSync(targetPath)) {
     throw new Error(`Target path already exists: ${targetPath}`);
@@ -810,6 +816,7 @@ export async function worktreeMakeCommand(nameArg: string, opts: WorktreeMakeOpt
     await runWorktreeInit({
       ...opts,
       name,
+      sourceConfigPathOverride: sourceConfigPath,
     });
   } catch (error) {
     throw error;
diff --git a/doc/DEVELOPING.md b/doc/DEVELOPING.md
index 4b379dcb..e3668516 100644
--- a/doc/DEVELOPING.md
+++ b/doc/DEVELOPING.md
@@ -142,7 +142,7 @@ This command:
 - creates an isolated instance under `~/.paperclip-worktrees/instances/<worktree-id>/`
 - when run inside a linked git worktree, mirrors the effective git hooks into that worktree's private git dir
 - picks a free app port and embedded PostgreSQL port
-- by default seeds the isolated DB in `minimal` mode from your main instance via a logical SQL snapshot
+- by default seeds the isolated DB in `minimal` mode from the current effective Paperclip instance/config (repo-local worktree config when present, otherwise the default instance) via a logical SQL snapshot
 
 Seed modes:
 

From 626a8f1976c7638bf23e35a8b0fb58f317492ff5 Mon Sep 17 00:00:00 2001
From: Dotta <bippadotta@protonmail.com>
Date: Fri, 13 Mar 2026 15:07:49 -0500
Subject: [PATCH 27/28] fix(cli): quote env values with special characters

---
 cli/src/__tests__/agent-jwt-env.test.ts | 18 ++++++++++++++++++
 cli/src/__tests__/worktree.test.ts      |  2 +-
 cli/src/config/env.ts                   |  9 ++++++++-
 3 files changed, 27 insertions(+), 2 deletions(-)

diff --git a/cli/src/__tests__/agent-jwt-env.test.ts b/cli/src/__tests__/agent-jwt-env.test.ts
index 40bb1554..baf5db51 100644
--- a/cli/src/__tests__/agent-jwt-env.test.ts
+++ b/cli/src/__tests__/agent-jwt-env.test.ts
@@ -4,7 +4,9 @@ import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import {
   ensureAgentJwtSecret,
+  mergePaperclipEnvEntries,
   readAgentJwtSecretFromEnv,
+  readPaperclipEnvEntries,
   resolveAgentJwtEnvFile,
 } from "../config/env.js";
 import { agentJwtSecretCheck } from "../checks/agent-jwt-secret-check.js";
@@ -58,4 +60,20 @@ describe("agent jwt env helpers", () => {
     const result = agentJwtSecretCheck(configPath);
     expect(result.status).toBe("pass");
   });
+
+  it("quotes hash-prefixed env values so dotenv round-trips them", () => {
+    const configPath = tempConfigPath();
+    const envPath = resolveAgentJwtEnvFile(configPath);
+
+    mergePaperclipEnvEntries(
+      {
+        PAPERCLIP_WORKTREE_COLOR: "#439edb",
+      },
+      envPath,
+    );
+
+    const contents = fs.readFileSync(envPath, "utf-8");
+    expect(contents).toContain('PAPERCLIP_WORKTREE_COLOR="#439edb"');
+    expect(readPaperclipEnvEntries(envPath).PAPERCLIP_WORKTREE_COLOR).toBe("#439edb");
+  });
 });
diff --git a/cli/src/__tests__/worktree.test.ts b/cli/src/__tests__/worktree.test.ts
index b6e2eb47..a8333ba5 100644
--- a/cli/src/__tests__/worktree.test.ts
+++ b/cli/src/__tests__/worktree.test.ts
@@ -294,7 +294,7 @@ describe("worktree helpers", () => {
       const envContents = fs.readFileSync(envPath, "utf8");
       expect(envContents).toContain("PAPERCLIP_AGENT_JWT_SECRET=worktree-shared-secret");
       expect(envContents).toContain("PAPERCLIP_WORKTREE_NAME=repo");
-      expect(envContents).toMatch(/PAPERCLIP_WORKTREE_COLOR=#[0-9a-f]{6}/);
+      expect(envContents).toMatch(/PAPERCLIP_WORKTREE_COLOR=\"#[0-9a-f]{6}\"/);
     } finally {
       process.chdir(originalCwd);
       if (originalJwtSecret === undefined) {
diff --git a/cli/src/config/env.ts b/cli/src/config/env.ts
index 4bc8f16e..a7266ea2 100644
--- a/cli/src/config/env.ts
+++ b/cli/src/config/env.ts
@@ -22,11 +22,18 @@ function parseEnvFile(contents: string) {
   }
 }
 
+function formatEnvValue(value: string): string {
+  if (/^[A-Za-z0-9_./:@-]+$/.test(value)) {
+    return value;
+  }
+  return JSON.stringify(value);
+}
+
 function renderEnvFile(entries: Record<string, string>) {
   const lines = [
     "# Paperclip environment variables",
     "# Generated by Paperclip CLI commands",
-    ...Object.entries(entries).map(([key, value]) => `${key}=${value}`),
+    ...Object.entries(entries).map(([key, value]) => `${key}=${formatEnvValue(value)}`),
     "",
   ];
   return lines.join("\n");

From db81a0638671e1b0f95d4011b45c505dd0d485bf Mon Sep 17 00:00:00 2001
From: Dotta <bippadotta@protonmail.com>
Date: Fri, 13 Mar 2026 15:07:56 -0500
Subject: [PATCH 28/28] docs: add agent evals framework plan

---
 doc/plans/2026-03-13-agent-evals-framework.md | 775 ++++++++++++++++++
 1 file changed, 775 insertions(+)
 create mode 100644 doc/plans/2026-03-13-agent-evals-framework.md

diff --git a/doc/plans/2026-03-13-agent-evals-framework.md b/doc/plans/2026-03-13-agent-evals-framework.md
new file mode 100644
index 00000000..6c4cc55e
--- /dev/null
+++ b/doc/plans/2026-03-13-agent-evals-framework.md
@@ -0,0 +1,775 @@
+# Agent Evals Framework Plan
+
+Date: 2026-03-13
+
+## Context
+
+We need evals for the thing Paperclip actually ships:
+
+- agent behavior produced by adapter config
+- prompt templates and bootstrap prompts
+- skill sets and skill instructions
+- model choice
+- runtime policy choices that affect outcomes and cost
+
+We do **not** primarily need a fine-tuning pipeline.
+We need a regression framework that can answer:
+
+- if we change prompts or skills, do agents still do the right thing?
+- if we switch models, what got better, worse, or more expensive?
+- if we optimize tokens, did we preserve task outcomes?
+- can we grow the suite over time from real Paperclip usage?
+
+This plan is based on:
+
+- `doc/GOAL.md`
+- `doc/PRODUCT.md`
+- `doc/SPEC-implementation.md`
+- `docs/agents-runtime.md`
+- `doc/plans/2026-03-13-TOKEN-OPTIMIZATION-PLAN.md`
+- Discussion #449: <https://github.com/paperclipai/paperclip/discussions/449>
+- OpenAI eval best practices: <https://developers.openai.com/api/docs/guides/evaluation-best-practices>
+- Promptfoo docs: <https://www.promptfoo.dev/docs/configuration/test-cases/> and <https://www.promptfoo.dev/docs/providers/custom-api/>
+- LangSmith complex agent eval docs: <https://docs.langchain.com/langsmith/evaluate-complex-agent>
+- Braintrust dataset/scorer docs: <https://www.braintrust.dev/docs/annotate/datasets> and <https://www.braintrust.dev/docs/evaluate/write-scorers>
+
+## Recommendation
+
+Paperclip should take a **two-stage approach**:
+
+1. **Start with Promptfoo now** for narrow, prompt-and-skill behavior evals across models.
+2. **Grow toward a first-party, repo-local eval harness in TypeScript** for full Paperclip scenario evals.
+
+So the recommendation is no longer “skip Promptfoo.” It is:
+
+- use Promptfoo as the fastest bootstrap layer
+- keep eval cases and fixtures in this repo
+- avoid making Promptfoo config the deepest long-term abstraction
+
+More specifically:
+
+1. The canonical eval definitions should live in this repo under a top-level `evals/` directory.
+2. `v0` should use Promptfoo to run focused test cases across models and providers.
+3. The longer-term harness should run **real Paperclip scenarios** against seeded companies/issues/agents, not just raw prompt completions.
+4. The scoring model should combine:
+   - deterministic checks
+   - structured rubric scoring
+   - pairwise candidate-vs-baseline judging
+   - efficiency metrics from normalized usage/cost telemetry
+5. The framework should compare **bundles**, not just models.
+
+A bundle is:
+
+- adapter type
+- model id
+- prompt template(s)
+- bootstrap prompt template
+- skill allowlist / skill content version
+- relevant runtime flags
+
+That is the right unit because that is what actually changes behavior in Paperclip.
+
+## Why This Is The Right Shape
+
+### 1. We need to evaluate system behavior, not only prompt output
+
+Prompt-only tools are useful, but Paperclip’s real failure modes are often:
+
+- wrong issue chosen
+- wrong API call sequence
+- bad delegation
+- failure to respect approval boundaries
+- stale session behavior
+- over-reading context
+- claiming completion without producing artifacts or comments
+
+Those are control-plane behaviors. They require scenario setup, execution, and trace inspection.
+
+### 2. The repo is already TypeScript-first
+
+The existing monorepo already uses:
+
+- `pnpm`
+- `tsx`
+- `vitest`
+- TypeScript across server, UI, shared contracts, and adapters
+
+A TypeScript-first harness will fit the repo and CI better than introducing a Python-first test subsystem as the default path.
+
+Python can stay optional later for specialty scorers or research experiments.
+
+### 3. We need provider/model comparison without vendor lock-in
+
+OpenAI’s guidance is directionally right:
+
+- eval early and often
+- use task-specific evals
+- log everything
+- prefer pairwise/comparison-style judging over open-ended scoring
+
+But OpenAI’s Evals API is not the right control plane for Paperclip as the primary system because our target is explicitly multi-model and multi-provider.
+
+### 4. Hosted eval products are useful, and Promptfoo is the right bootstrap tool
+
+The current tradeoff:
+
+- Promptfoo is very good for local, repo-based prompt/provider matrices and CI integration.
+- LangSmith is strong on trajectory-style agent evals.
+- Braintrust has a clean dataset + scorer + experiment model and strong TypeScript support.
+
+The community suggestion is directionally right:
+
+- Promptfoo lets us start small
+- it supports simple assertions like contains / not-contains / regex / custom JS
+- it can run the same cases across multiple models
+- it supports OpenRouter
+- it can move into CI later
+
+That makes it the best `v0` tool for “did this prompt/skill/model change obviously regress?”
+
+But Paperclip should still avoid making a hosted platform or a third-party config format the core abstraction before we have our own stable eval model.
+
+The right move is:
+
+- start with Promptfoo for quick wins
+- keep the data portable and repo-owned
+- build a thin first-party harness around Paperclip concepts as the system grows
+- optionally export to or integrate with other tools later if useful
+
+## What We Should Evaluate
+
+We should split evals into four layers.
+
+### Layer 1: Deterministic contract evals
+
+These should require no judge model.
+
+Examples:
+
+- agent comments on the assigned issue
+- no mutation outside the agent’s company
+- approval-required actions do not bypass approval flow
+- task transitions are legal
+- output contains required structured fields
+- artifact links exist when the task required an artifact
+- no full-thread refetch on delta-only cases once the API supports it
+
+These are cheap, reliable, and should be the first line of defense.
+
+### Layer 2: Single-step behavior evals
+
+These test narrow behaviors in isolation.
+
+Examples:
+
+- chooses the correct issue from inbox
+- writes a reasonable first status comment
+- decides to ask for approval instead of acting directly
+- delegates to the correct report
+- recognizes blocked state and reports it clearly
+
+These are the closest thing to prompt evals, but still framed in Paperclip terms.
+
+### Layer 3: End-to-end scenario evals
+
+These run a full heartbeat or short sequence of heartbeats against a seeded scenario.
+
+Examples:
+
+- new assignment pickup
+- long-thread continuation
+- mention-triggered clarification
+- approval-gated hire request
+- manager escalation
+- workspace coding task that must leave a meaningful issue update
+
+These should evaluate both final state and trace quality.
+
+### Layer 4: Efficiency and regression evals
+
+These are not “did the answer look good?” evals. They are “did we preserve quality while improving cost/latency?” evals.
+
+Examples:
+
+- normalized input tokens per successful heartbeat
+- normalized tokens per completed issue
+- session reuse rate
+- full-thread reload rate
+- wall-clock duration
+- cost per successful scenario
+
+This layer is especially important for token optimization work.
+
+## Core Design
+
+## 1. Canonical object: `EvalCase`
+
+Each eval case should define:
+
+- scenario setup
+- target bundle(s)
+- execution mode
+- expected invariants
+- scoring rubric
+- tags/metadata
+
+Suggested shape:
+
+```ts
+type EvalCase = {
+  id: string;
+  description: string;
+  tags: string[];
+  setup: {
+    fixture: string;
+    agentId: string;
+    trigger: "assignment" | "timer" | "on_demand" | "comment" | "approval";
+  };
+  inputs?: Record<string, unknown>;
+  checks: {
+    hard: HardCheck[];
+    rubric?: RubricCheck[];
+    pairwise?: PairwiseCheck[];
+  };
+  metrics: MetricSpec[];
+};
+```
+
+The important part is that the case is about a Paperclip scenario, not a standalone prompt string.
+
+## 2. Canonical object: `EvalBundle`
+
+Suggested shape:
+
+```ts
+type EvalBundle = {
+  id: string;
+  adapter: string;
+  model: string;
+  promptTemplate: string;
+  bootstrapPromptTemplate?: string;
+  skills: string[];
+  flags?: Record<string, string | number | boolean>;
+};
+```
+
+Every comparison run should say which bundle was tested.
+
+This avoids the common mistake of saying “model X is better” when the real change was model + prompt + skills + runtime behavior.
+
+## 3. Canonical output: `EvalTrace`
+
+We should capture a normalized trace for scoring:
+
+- run ids
+- prompts actually sent
+- session reuse metadata
+- issue mutations
+- comments created
+- approvals requested
+- artifacts created
+- token/cost telemetry
+- timing
+- raw outputs
+
+The scorer layer should never need to scrape ad hoc logs.
+
+## Scoring Framework
+
+## 1. Hard checks first
+
+Every eval should start with pass/fail checks that can invalidate the run immediately.
+
+Examples:
+
+- touched wrong company
+- skipped required approval
+- no issue update produced
+- returned malformed structured output
+- marked task done without required artifact
+
+If a hard check fails, the scenario fails regardless of style or judge score.
+
+## 2. Rubric scoring second
+
+Rubric scoring should use narrow criteria, not vague “how good was this?” prompts.
+
+Good rubric dimensions:
+
+- task understanding
+- governance compliance
+- useful progress communication
+- correct delegation
+- evidence of completion
+- concision / unnecessary verbosity
+
+Each rubric should be a small 0-1 or 0-2 decision, not a mushy 1-10 scale.
+
+## 3. Pairwise judging for candidate vs baseline
+
+OpenAI’s eval guidance is right that LLMs are better at discrimination than open-ended generation.
+
+So for non-deterministic quality checks, the default pattern should be:
+
+- run baseline bundle on the case
+- run candidate bundle on the same case
+- ask a judge model which is better on explicit criteria
+- allow `baseline`, `candidate`, or `tie`
+
+This is better than asking a judge for an absolute quality score with no anchor.
+
+## 4. Efficiency scoring is separate
+
+Do not bury efficiency inside a single blended quality score.
+
+Record it separately:
+
+- quality score
+- cost score
+- latency score
+
+Then compute a summary decision such as:
+
+- candidate is acceptable only if quality is non-inferior and efficiency is improved
+
+That is much easier to reason about than one magic number.
+
+## Suggested Decision Rule
+
+For PR gating:
+
+1. No hard-check regressions.
+2. No significant regression on required scenario pass rate.
+3. No significant regression on key rubric dimensions.
+4. If the change is token-optimization-oriented, require efficiency improvement on target scenarios.
+
+For deeper comparison reports, show:
+
+- pass rate
+- pairwise wins/losses/ties
+- median normalized tokens
+- median wall-clock time
+- cost deltas
+
+## Dataset Strategy
+
+We should explicitly build the dataset from three sources.
+
+### 1. Hand-authored seed cases
+
+Start here.
+
+These should cover core product invariants:
+
+- assignment pickup
+- status update
+- blocked reporting
+- delegation
+- approval request
+- cross-company access denial
+- issue comment follow-up
+
+These are small, clear, and stable.
+
+### 2. Production-derived cases
+
+Per OpenAI’s guidance, we should log everything and mine real usage for eval cases.
+
+Paperclip should grow eval coverage by promoting real runs into cases when we see:
+
+- regressions
+- interesting failures
+- edge cases
+- high-value success patterns worth preserving
+
+The initial version can be manual:
+
+- take a real run
+- redact/normalize it
+- convert it into an `EvalCase`
+
+Later we can automate trace-to-case generation.
+
+### 3. Adversarial and guardrail cases
+
+These should intentionally probe failure modes:
+
+- approval bypass attempts
+- wrong-company references
+- stale context traps
+- irrelevant long threads
+- misleading instructions in comments
+- verbosity traps
+
+This is where promptfoo-style red-team ideas can become useful later, but it is not the first slice.
+
+## Repo Layout
+
+Recommended initial layout:
+
+```text
+evals/
+  README.md
+  promptfoo/
+    promptfooconfig.yaml
+    prompts/
+    cases/
+  cases/
+    core/
+    approvals/
+    delegation/
+    efficiency/
+  fixtures/
+    companies/
+    issues/
+  bundles/
+    baseline/
+    experiments/
+  runners/
+    scenario-runner.ts
+    compare-runner.ts
+  scorers/
+    hard/
+    rubric/
+    pairwise/
+  judges/
+    rubric-judge.ts
+    pairwise-judge.ts
+  lib/
+    types.ts
+    traces.ts
+    metrics.ts
+  reports/
+    .gitignore
+```
+
+Why top-level `evals/`:
+
+- it makes evals feel first-class
+- it avoids hiding them inside `server/` even though they span adapters and runtime behavior
+- it leaves room for both TS and optional Python helpers later
+- it gives us a clean place for Promptfoo `v0` config plus the later first-party runner
+
+## Execution Model
+
+The harness should support three modes.
+
+### Mode A: Cheap local smoke
+
+Purpose:
+
+- run on PRs
+- keep cost low
+- catch obvious regressions
+
+Characteristics:
+
+- 5 to 20 cases
+- 1 or 2 bundles
+- mostly hard checks and narrow rubrics
+
+### Mode B: Candidate vs baseline compare
+
+Purpose:
+
+- evaluate a prompt/skill/model change before merge
+
+Characteristics:
+
+- paired runs
+- pairwise judging enabled
+- quality + efficiency diff report
+
+### Mode C: Nightly broader matrix
+
+Purpose:
+
+- compare multiple models and bundles
+- grow historical benchmark data
+
+Characteristics:
+
+- larger case set
+- multiple models
+- more expensive rubric/pairwise judging
+
+## CI and Developer Workflow
+
+Suggested commands:
+
+```sh
+pnpm evals:smoke
+pnpm evals:compare --baseline baseline/codex-default --candidate experiments/codex-lean-skillset
+pnpm evals:nightly
+```
+
+PR behavior:
+
+- run `evals:smoke` on prompt/skill/adapter/runtime changes
+- optionally trigger `evals:compare` for labeled PRs or manual runs
+
+Nightly behavior:
+
+- run larger matrix
+- save report artifact
+- surface trend lines on pass rate, pairwise wins, and efficiency
+
+## Framework Comparison
+
+## Promptfoo
+
+Best use for Paperclip:
+
+- prompt-level micro-evals
+- provider/model comparison
+- quick local CI integration
+- custom JS assertions and custom providers
+- bootstrap-layer evals for one skill or one agent workflow
+
+What changed in this recommendation:
+
+- Promptfoo is now the recommended **starting point**
+- especially for “one skill, a handful of cases, compare across models”
+
+Why it still should not be the only long-term system:
+
+- its primary abstraction is still prompt/provider/test-case oriented
+- Paperclip needs scenario setup, control-plane state inspection, and multi-step traces as first-class concepts
+
+Recommendation:
+
+- use Promptfoo first
+- store Promptfoo config and cases in-repo under `evals/promptfoo/`
+- use custom JS/TS assertions and, if needed later, a custom provider that calls Paperclip scenario runners
+- do not make Promptfoo YAML the only canonical Paperclip eval format once we outgrow prompt-level evals
+
+## LangSmith
+
+What it gets right:
+
+- final response evals
+- trajectory evals
+- single-step evals
+
+Why not the primary system today:
+
+- stronger fit for teams already centered on LangChain/LangGraph
+- introduces hosted/external workflow gravity before our own eval model is stable
+
+Recommendation:
+
+- copy the trajectory/final/single-step taxonomy
+- do not adopt the platform as the default requirement
+
+## Braintrust
+
+What it gets right:
+
+- TypeScript support
+- clean dataset/task/scorer model
+- production logging to datasets
+- experiment comparison over time
+
+Why not the primary system today:
+
+- still externalizes the canonical dataset and review workflow
+- we are not yet at the maturity where hosted experiment management should define the shape of the system
+
+Recommendation:
+
+- borrow its dataset/scorer/experiment mental model
+- revisit once we want hosted review and experiment history at scale
+
+## OpenAI Evals / Evals API
+
+What it gets right:
+
+- strong eval principles
+- emphasis on task-specific evals
+- continuous evaluation mindset
+
+Why not the primary system:
+
+- Paperclip must compare across models/providers
+- we do not want our primary eval runner coupled to one model vendor
+
+Recommendation:
+
+- use the guidance
+- do not use it as the core Paperclip eval runtime
+
+## First Implementation Slice
+
+The first version should be intentionally small.
+
+## Phase 0: Promptfoo bootstrap
+
+Build:
+
+- `evals/promptfoo/promptfooconfig.yaml`
+- 5 to 10 focused cases for one skill or one agent workflow
+- model matrix using the providers we care about most
+- mostly deterministic assertions:
+  - contains
+  - not-contains
+  - regex
+  - custom JS assertions
+
+Target scope:
+
+- one skill, or one narrow workflow such as assignment pickup / first status update
+- compare a small set of bundles across several models
+
+Success criteria:
+
+- we can run one command and compare outputs across models
+- prompt/skill regressions become visible quickly
+- the team gets signal before building heavier infrastructure
+
+## Phase 1: Skeleton and core cases
+
+Build:
+
+- `evals/` scaffold
+- `EvalCase`, `EvalBundle`, `EvalTrace` types
+- scenario runner for seeded local cases
+- 10 hand-authored core cases
+- hard checks only
+
+Target cases:
+
+- assigned issue pickup
+- write progress comment
+- ask for approval when required
+- respect company boundary
+- report blocked state
+- avoid marking done without artifact/comment evidence
+
+Success criteria:
+
+- a developer can run a local smoke suite
+- prompt/skill changes can fail the suite deterministically
+- Promptfoo `v0` cases either migrate into or coexist with this layer cleanly
+
+## Phase 2: Pairwise and rubric layer
+
+Build:
+
+- rubric scorer interface
+- pairwise judge runner
+- candidate vs baseline compare command
+- markdown/html report output
+
+Success criteria:
+
+- model/prompt bundle changes produce a readable diff report
+- we can tell “better”, “worse”, or “same” on curated scenarios
+
+## Phase 3: Efficiency integration
+
+Build:
+
+- normalized token/cost metrics into eval traces
+- cost and latency comparisons
+- efficiency gates for token optimization work
+
+Dependency:
+
+- this should align with the telemetry normalization work in `2026-03-13-TOKEN-OPTIMIZATION-PLAN.md`
+
+Success criteria:
+
+- quality and efficiency can be judged together
+- token-reduction work no longer relies on anecdotal improvements
+
+## Phase 4: Production-case ingestion
+
+Build:
+
+- tooling to promote real runs into new eval cases
+- metadata tagging
+- failure corpus growth process
+
+Success criteria:
+
+- the eval suite grows from real product behavior instead of staying synthetic
+
+## Initial Case Categories
+
+We should start with these categories:
+
+1. `core.assignment_pickup`
+2. `core.progress_update`
+3. `core.blocked_reporting`
+4. `governance.approval_required`
+5. `governance.company_boundary`
+6. `delegation.correct_report`
+7. `threads.long_context_followup`
+8. `efficiency.no_unnecessary_reloads`
+
+That is enough to start catching the classes of regressions we actually care about.
+
+## Important Guardrails
+
+### 1. Do not rely on judge models alone
+
+Every important scenario needs deterministic checks first.
+
+### 2. Do not gate PRs on a single noisy score
+
+Use pass/fail invariants plus a small number of stable rubric or pairwise checks.
+
+### 3. Do not confuse benchmark score with product quality
+
+The suite must keep growing from real runs, otherwise it will become a toy benchmark.
+
+### 4. Do not evaluate only final output
+
+Trajectory matters for agents:
+
+- did they call the right Paperclip APIs?
+- did they ask for approval?
+- did they communicate progress?
+- did they choose the right issue?
+
+### 5. Do not make the framework vendor-shaped
+
+Our eval model should survive changes in:
+
+- judge provider
+- candidate provider
+- adapter implementation
+- hosted tooling choices
+
+## Open Questions
+
+1. Should the first scenario runner invoke the real server over HTTP, or call services directly in-process?
+   My recommendation: start in-process for speed, then add HTTP-mode coverage once the model stabilizes.
+
+2. Should we support Python scorers in v1?
+   My recommendation: no. Keep v1 all-TypeScript.
+
+3. Should we commit baseline outputs?
+   My recommendation: commit case definitions and bundle definitions, but keep run artifacts out of git.
+
+4. Should we add hosted experiment tracking immediately?
+   My recommendation: no. Revisit after the local harness proves useful.
+
+## Final Recommendation
+
+Start with Promptfoo for immediate, narrow model-and-prompt comparisons, then grow into a first-party `evals/` framework in TypeScript that evaluates **Paperclip scenarios and bundles**, not just prompts.
+
+Use this structure:
+
+- Promptfoo for `v0` bootstrap
+- deterministic hard checks as the foundation
+- rubric and pairwise judging for non-deterministic quality
+- normalized efficiency metrics as a separate axis
+- repo-local datasets that grow from real runs
+
+Use external tools selectively:
+
+- Promptfoo as the initial path for narrow prompt/provider tests
+- Braintrust or LangSmith later if we want hosted experiment management
+
+But keep the canonical eval model inside the Paperclip repo and aligned to Paperclip’s actual control-plane behaviors.