Merge branch 'dev' into local

# Conflicts:
#	packages/db/src/migrations/meta/_journal.json

packages/adapter-utils/README.md

@@ -0,0 +1,37 @@
+# @paperclipai/adapter-utils
+
+Shared utilities for Paperclip adapters: process spawning, environment
+injection, sandbox/SSH transport, workspace sync, and the round-trip helpers
+that move code between the local execution-workspace cwd and wherever the
+agent actually runs.
+
+For the adapter-author guide see
+[`docs/adapters/creating-an-adapter.md`](../../docs/adapters/creating-an-adapter.md)
+and the in-repo notes at [`packages/adapters/AUTHORING.md`](../adapters/AUTHORING.md).
+
+## No-remote-git contract
+
+The local execution-workspace cwd is the only persistence boundary across
+runs. No adapter may depend on a git remote for cross-run state.
+
+Adapters that run the agent on a different host should use the SSH round-trip
+helpers in [`src/ssh.ts`](./src/ssh.ts):
+
+- `prepareWorkspaceForSshExecution({ spec, localDir, remoteDir })` — bundles
+  the local cwd (tracked files, dirty edits, untracked additions, and the git
+  history needed to reconstruct it) to `remoteDir` before the run starts. Runs
+  with no `git remote` configured.
+- `restoreWorkspaceFromSshExecution({ spec, localDir, remoteDir, ... })` —
+  syncs the remote cwd back into `localDir` after the run, including any new
+  commits the agent created. Also runs with no `git remote` configured.
+
+`prepareRemoteManagedRuntime` in
+[`src/remote-managed-runtime.ts`](./src/remote-managed-runtime.ts) wraps both
+calls for adapters that want a per-run remote workspace and an automatic
+`restoreWorkspace()` finally hook.
+
+The invariant is pinned by the `no-remote-git contract` case in
+[`src/ssh-fixture.test.ts`](./src/ssh-fixture.test.ts), which asserts that a
+remote-only commit propagates to the local worktree through the
+prepare → restore round-trip with no git remote configured at any point. Do
+not regress that test.

packages/adapter-utils/src/server-utils.test.ts

@@ -6,6 +6,8 @@ import { describe, expect, it } from "vitest";
 import {
   applyPaperclipWorkspaceEnv,
   appendWithByteCap,
+  buildPersistentSkillSnapshot,
+  buildRuntimeMountedSkillSnapshot,
   buildInvocationEnvForLogs,
   DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,
   materializePaperclipSkillCopy,
@@ -205,6 +207,186 @@ describe("materializePaperclipSkillCopy", () => {
   });
 });
 
+describe("adapter skill snapshots", () => {
+  const requiredEntry = {
+    key: "paperclipai/paperclip/paperclip",
+    runtimeName: "paperclip",
+    source: "/runtime/paperclip",
+    required: true,
+    requiredReason: "Required for Paperclip heartbeats.",
+  };
+  const optionalEntry = {
+    key: "company/ascii-heart",
+    runtimeName: "ascii-heart",
+    source: "/runtime/ascii-heart",
+  };
+
+  it("reports runtime-mounted adapters as configured or missing without install state", () => {
+    const snapshot = buildRuntimeMountedSkillSnapshot({
+      adapterType: "codex_local",
+      availableEntries: [requiredEntry],
+      desiredSkills: [requiredEntry.key, "missing-skill"],
+      configuredDetail: "Mounted on next run.",
+    });
+
+    expect(snapshot).toMatchObject({
+      supported: true,
+      mode: "ephemeral",
+      desiredSkills: [requiredEntry.key, "missing-skill"],
+    });
+    expect(snapshot.entries).toEqual([
+      expect.objectContaining({
+        key: "missing-skill",
+        state: "missing",
+        origin: "external_unknown",
+        desired: true,
+      }),
+      expect.objectContaining({
+        key: requiredEntry.key,
+        state: "configured",
+        origin: "paperclip_required",
+        required: true,
+        detail: "Mounted on next run.",
+      }),
+    ]);
+  });
+
+  it("reports source-missing company runtime skills without orphan warnings", () => {
+    const snapshot = buildRuntimeMountedSkillSnapshot({
+      adapterType: "codex_local",
+      availableEntries: [{
+        key: "company/example/reflection-coach",
+        runtimeName: "reflection-coach--abc123",
+        source: "/paperclip/skills/example/__runtime__/reflection-coach--abc123",
+        sourceStatus: "missing",
+        missingDetail: "Company skill exists, but its local source is missing.",
+      }],
+      desiredSkills: ["company/example/reflection-coach"],
+      configuredDetail: "Mounted on next run.",
+    });
+
+    expect(snapshot.warnings).toEqual([]);
+    expect(snapshot.entries).toEqual([
+      expect.objectContaining({
+        key: "company/example/reflection-coach",
+        state: "missing",
+        origin: "company_managed",
+        sourcePath: null,
+        detail: "Company skill exists, but its local source is missing.",
+      }),
+    ]);
+  });
+
+  it("keeps unsupported runtime-mounted adapters in tracked-only state", () => {
+    const snapshot = buildRuntimeMountedSkillSnapshot({
+      adapterType: "acpx_local",
+      availableEntries: [requiredEntry],
+      desiredSkills: [requiredEntry.key],
+      configuredDetail: "Mounted on next run.",
+      mode: "unsupported",
+      unsupportedDetail: "Tracked only.",
+    });
+
+    expect(snapshot.supported).toBe(false);
+    expect(snapshot.mode).toBe("unsupported");
+    expect(snapshot.entries).toContainEqual(expect.objectContaining({
+      key: requiredEntry.key,
+      desired: true,
+      state: "available",
+      detail: "Tracked only.",
+    }));
+  });
+
+  it("can surface read-only external skills for runtime-mounted adapters", () => {
+    const snapshot = buildRuntimeMountedSkillSnapshot({
+      adapterType: "claude_local",
+      availableEntries: [requiredEntry],
+      desiredSkills: [requiredEntry.key],
+      configuredDetail: "Mounted on next run.",
+      externalInstalled: new Map([
+        ["crack-python", { targetPath: "/home/me/.claude/skills/crack-python", kind: "directory" }],
+      ]),
+      externalLocationLabel: "~/.claude/skills",
+      externalDetail: "Installed outside Paperclip management in the Claude skills home.",
+    });
+
+    expect(snapshot.entries).toContainEqual(expect.objectContaining({
+      key: "crack-python",
+      runtimeName: "crack-python",
+      state: "external",
+      managed: false,
+      origin: "user_installed",
+      locationLabel: "~/.claude/skills",
+      readOnly: true,
+    }));
+  });
+
+  it("reports persistent adapter installed, stale, external, and missing states", () => {
+    const snapshot = buildPersistentSkillSnapshot({
+      adapterType: "cursor",
+      availableEntries: [requiredEntry, optionalEntry],
+      desiredSkills: [requiredEntry.key, "missing-skill"],
+      installed: new Map([
+        ["paperclip", { targetPath: "/runtime/paperclip", kind: "symlink" }],
+        ["ascii-heart", { targetPath: "/other/ascii-heart", kind: "directory" }],
+        ["old-managed", { targetPath: "/runtime/old-managed", kind: "symlink" }],
+      ]),
+      skillsHome: "/home/me/.cursor/skills",
+      locationLabel: "~/.cursor/skills",
+      installedDetail: "Installed in the Cursor skills home.",
+      missingDetail: "Configured but not linked.",
+      externalConflictDetail: "Name occupied externally.",
+      externalDetail: "Installed outside Paperclip management.",
+    });
+
+    expect(snapshot.mode).toBe("persistent");
+    expect(snapshot.entries).toContainEqual(expect.objectContaining({
+      key: requiredEntry.key,
+      state: "installed",
+      managed: true,
+      origin: "paperclip_required",
+    }));
+    expect(snapshot.entries).toContainEqual(expect.objectContaining({
+      key: optionalEntry.key,
+      state: "external",
+      managed: false,
+      detail: "Installed outside Paperclip management.",
+    }));
+    expect(snapshot.entries).toContainEqual(expect.objectContaining({
+      key: "missing-skill",
+      state: "missing",
+      origin: "external_unknown",
+    }));
+    expect(snapshot.entries).toContainEqual(expect.objectContaining({
+      key: "old-managed",
+      state: "external",
+      origin: "user_installed",
+    }));
+  });
+
+  it("reports stale managed persistent skills when Paperclip owns an undesired available skill", () => {
+    const snapshot = buildPersistentSkillSnapshot({
+      adapterType: "cursor",
+      availableEntries: [optionalEntry],
+      desiredSkills: [],
+      installed: new Map([
+        ["ascii-heart", { targetPath: "/runtime/ascii-heart", kind: "symlink" }],
+      ]),
+      skillsHome: "/home/me/.cursor/skills",
+      missingDetail: "Configured but not linked.",
+      externalConflictDetail: "Name occupied externally.",
+      externalDetail: "Installed outside Paperclip management.",
+    });
+
+    expect(snapshot.entries).toContainEqual(expect.objectContaining({
+      key: optionalEntry.key,
+      desired: false,
+      state: "stale",
+      managed: true,
+    }));
+  });
+});
+
 describe("runChildProcess", () => {
   it("does not arm a timeout when timeoutSec is 0", async () => {
     const result = await runChildProcess(

packages/adapter-utils/src/ssh-fixture.test.ts

@@ -451,6 +451,68 @@ describe("ssh env-lab fixture", () => {
     await expect(readFile(path.join(localRepo, "tracked.txt"), "utf8")).resolves.toBe("dirty remote\n");
   }, SSH_FIXTURE_TEST_TIMEOUT_MS);
 
+  it("propagates remote commits to the local worktree with no git remote configured (no-remote-git contract)", async () => {
+    // Locks in the architectural contract documented in
+    // packages/adapter-utils/README.md and packages/adapters/AUTHORING.md:
+    // the local execution-workspace cwd is the only persistence boundary
+    // across runs. No adapter may depend on a git remote for cross-run state.
+    const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-ssh-fixture-"));
+    cleanupDirs.push(rootDir);
+    const statePath = path.join(rootDir, "state.json");
+    const localRepo = path.join(rootDir, "local-workspace");
+
+    await mkdir(localRepo, { recursive: true });
+    await git(localRepo, ["init"]);
+    await git(localRepo, ["checkout", "-b", "main"]);
+    await git(localRepo, ["config", "user.name", "Paperclip Test"]);
+    await git(localRepo, ["config", "user.email", "test@paperclip.dev"]);
+    await writeFile(path.join(localRepo, "tracked.txt"), "base\n", "utf8");
+    await git(localRepo, ["add", "tracked.txt"]);
+    await git(localRepo, ["commit", "-m", "initial"]);
+
+    // Assert there is no git remote configured before we begin, and verify
+    // that no point in the round-trip introduces one. `git remote` returns an
+    // empty string when no remotes exist (and exit code 0).
+    expect(await git(localRepo, ["remote"])).toBe("");
+
+    const started = await startSshEnvLabFixtureOrSkip(
+      statePath,
+      "no-remote-git contract test",
+    );
+    if (!started) return;
+    const config = await buildSshEnvLabFixtureConfig(started);
+    const spec = {
+      ...config,
+      remoteCwd: started.workspaceDir,
+    } as const;
+
+    const prepared = await prepareRemoteManagedRuntime({
+      spec,
+      runId: "run-no-remote",
+      adapterKey: "test-adapter",
+      workspaceLocalDir: localRepo,
+    });
+
+    // Remote commit lands a deliverable that must show up locally via
+    // sync-back alone — no `git push`, no fetch from any origin.
+    await runSshCommand(
+      config,
+      `cd ${JSON.stringify(prepared.workspaceRemoteDir)} && git config user.name "Paperclip SSH" && git config user.email "ssh@paperclip.dev" && printf "deliverable\\n" > tracked.txt && git add tracked.txt && git commit -m "remote-only commit" >/dev/null`,
+      { timeoutMs: 30_000, maxBuffer: 256 * 1024 },
+    );
+
+    await prepared.restoreWorkspace();
+
+    expect(await git(localRepo, ["log", "-1", "--pretty=%s"])).toBe(
+      "remote-only commit",
+    );
+    expect(await readFile(path.join(localRepo, "tracked.txt"), "utf8")).toBe(
+      "deliverable\n",
+    );
+    // Final assertion: still no git remote — restore did not silently add one.
+    expect(await git(localRepo, ["remote"])).toBe("");
+  }, SSH_FIXTURE_TEST_TIMEOUT_MS);
+
   it("merges concurrent remote commits through the managed runtime restore path", async () => {
     const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-ssh-fixture-"));
     cleanupDirs.push(rootDir);

packages/adapters/AUTHORING.md

@@ -0,0 +1,58 @@
+# Adapter Authoring Notes
+
+In-repo notes for adapter authors. The user-facing guide lives at
+[`docs/adapters/creating-an-adapter.md`](../../docs/adapters/creating-an-adapter.md);
+this file holds invariants that are easy to violate from inside the adapter
+package itself.
+
+## No-remote-git contract (cross-run persistence)
+
+The local execution-workspace cwd is the only persistence boundary across
+runs. No adapter may depend on a git remote for cross-run state.
+
+Why: Paperclip resolves a local execution workspace (a worktree) for each
+heartbeat. Code state is carried forward by syncing that local cwd to wherever
+the agent actually runs — over ssh, into a sandbox, into a managed runtime —
+and then syncing changes back when the run finishes. Treating a `git remote`
+as the source of truth (`git push` from inside the agent, fetch on the next
+wake) breaks dependent issues that are gated on the local worktree being
+caught up, and breaks isolated execution workspaces that have no remote
+configured at all.
+
+How to apply:
+
+- Never `git push` from adapter runtime code. Never assume the local worktree
+  has any `git remote` configured. If you need data from the previous run,
+  read it from the local cwd Paperclip handed you.
+- If your adapter runs the agent on a different host (ssh, sandbox, remote
+  container), use the round-trip helpers in `@paperclipai/adapter-utils`:
+  [`prepareWorkspaceForSshExecution`](../adapter-utils/src/ssh.ts) bundles the
+  local cwd to the remote dir before the run, and
+  [`restoreWorkspaceFromSshExecution`](../adapter-utils/src/ssh.ts) syncs
+  remote-side changes (including new git commits) back into the local cwd
+  after the run. Both run with no `git remote` configured.
+- If your adapter runs the agent locally, you can read and write the cwd
+  directly — same invariant applies: changes that future runs need must live
+  in the local cwd by the time `execute()` returns.
+- A failed sync-back is a run-level error. The heartbeat records
+  `workspace_finalize=failed` on the execution workspace, which gates
+  dependent issue wakes until the next successful finalize. Do not swallow
+  restore errors.
+
+The invariant is pinned by the `no-remote-git contract` case in
+[`packages/adapter-utils/src/ssh-fixture.test.ts`](../adapter-utils/src/ssh-fixture.test.ts),
+which asserts that a remote-only commit propagates to the local worktree
+through `prepareWorkspaceForSshExecution` → `restoreWorkspaceFromSshExecution`
+with no git remote configured at any point.
+
+A static check enforces the rule before runtime ever sees it:
+[`scripts/check-no-git-push.mjs`](../../scripts/check-no-git-push.mjs) scans
+adapter and runtime source (`packages/adapters/`, `packages/adapter-utils/`,
+`server/src/`, `cli/src/`) and fails the `policy` CI job if any unapproved
+`git push` invocation is added. If you are building an operator-configured
+path that legitimately must push, add a
+`// paperclip:allow-git-push: <reason>` comment on the line (or the line
+above) so the opt-in shows up in code review.
+
+For the architecture-level write-up of cross-run persistence, see
+[`docs/guides/board-operator/execution-workspaces-and-runtime-services.md`](../../docs/guides/board-operator/execution-workspaces-and-runtime-services.md#cross-run-persistence-no-remote-git-contract).

packages/adapters/acpx-local/src/server/skills.ts

@@ -2,10 +2,10 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import type {
   AdapterSkillContext,
-  AdapterSkillEntry,
   AdapterSkillSnapshot,
 } from "@paperclipai/adapter-utils";
 import {
+  buildRuntimeMountedSkillSnapshot,
   readPaperclipRuntimeSkillEntries,
   resolvePaperclipDesiredSkillNames,
 } from "@paperclipai/adapter-utils/server-utils";
@@ -35,9 +35,7 @@ function unsupportedDetail(): string {
 async function buildAcpxSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
   const acpxAgent = normalizeAcpxSkillAgent(config);
   const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
-  const availableByKey = new Map(availableEntries.map((entry) => [entry.key, entry]));
   const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
-  const desiredSet = new Set(desiredSkills);
   const supported = acpxAgent !== "custom";
   const warnings: string[] = supported
     ? []
@@ -45,53 +43,16 @@ async function buildAcpxSkillSnapshot(config: Record<string, unknown>): Promise<
         "Custom ACP commands do not expose a Paperclip skill integration contract yet; selected skills are tracked only.",
       ];
 
-  const entries: AdapterSkillEntry[] = availableEntries.map((entry) => {
-    const desired = desiredSet.has(entry.key);
-    return {
-      key: entry.key,
-      runtimeName: entry.runtimeName,
-      desired,
-      managed: true,
-      state: desired ? "configured" : "available",
-      origin: entry.required ? "paperclip_required" : "company_managed",
-      originLabel: entry.required ? "Required by Paperclip" : "Managed by Paperclip",
-      readOnly: false,
-      sourcePath: entry.source,
-      targetPath: null,
-      detail: desired ? (supported ? configuredDetail(acpxAgent) : unsupportedDetail()) : null,
-      required: Boolean(entry.required),
-      requiredReason: entry.requiredReason ?? null,
-    };
-  });
-
-  for (const desiredSkill of desiredSkills) {
-    if (availableByKey.has(desiredSkill)) continue;
-    warnings.push(`Desired skill "${desiredSkill}" is not available from the Paperclip skills directory.`);
-    entries.push({
-      key: desiredSkill,
-      runtimeName: null,
-      desired: true,
-      managed: true,
-      state: "missing",
-      origin: "external_unknown",
-      originLabel: "External or unavailable",
-      readOnly: false,
-      sourcePath: null,
-      targetPath: null,
-      detail: "Paperclip cannot find this skill in the local runtime skills directory.",
-    });
-  }
-
-  entries.sort((left, right) => left.key.localeCompare(right.key));
-
-  return {
+  return buildRuntimeMountedSkillSnapshot({
     adapterType: "acpx_local",
+    availableEntries,
+    desiredSkills,
     supported,
     mode: supported ? "ephemeral" : "unsupported",
-    desiredSkills,
-    entries,
+    configuredDetail: configuredDetail(acpxAgent),
+    unsupportedDetail: unsupportedDetail(),
     warnings,
-  };
+  });
 }
 
 export async function listAcpxSkills(ctx: AdapterSkillContext): Promise<AdapterSkillSnapshot> {

packages/adapters/claude-local/src/index.ts

@@ -6,6 +6,7 @@ export const label = "Claude Code (local)";
 export const SANDBOX_INSTALL_COMMAND = "npm install -g @anthropic-ai/claude-code";
 
 export const models = [
+  { id: "claude-opus-4-8", label: "Claude Opus 4.8" },
   { id: "claude-opus-4-7", label: "Claude Opus 4.7" },
   { id: "claude-opus-4-6", label: "Claude Opus 4.6" },
   { id: "claude-sonnet-4-6", label: "Claude Sonnet 4.6" },

packages/adapters/claude-local/src/server/index.ts

@@ -1,6 +1,6 @@
 export { claudeSessionCwdMatchesExecutionTarget, execute, runClaudeLogin } from "./execute.js";
 export { listClaudeSkills, syncClaudeSkills } from "./skills.js";
-export { listClaudeModels } from "./models.js";
+export { listClaudeModels, refreshClaudeModels, resetClaudeModelsCacheForTests } from "./models.js";
 export { testEnvironment } from "./test.js";
 export {
   parseClaudeStreamJson,

packages/adapters/claude-local/src/server/models.ts

@@ -1,13 +1,22 @@
+import { createHash } from "node:crypto";
 import type { AdapterModel } from "@paperclipai/adapter-utils";
 import { models as DIRECT_MODELS } from "../index.js";
 
+const ANTHROPIC_MODELS_ENDPOINT = "/v1/models";
+const ANTHROPIC_MODELS_TIMEOUT_MS = 5000;
+const ANTHROPIC_MODELS_CACHE_TTL_MS = 60_000;
+const ANTHROPIC_API_VERSION = "2023-06-01";
+
 /** AWS Bedrock model IDs — region-qualified identifiers required by the Bedrock API. */
 const BEDROCK_MODELS: AdapterModel[] = [
+  { id: "us.anthropic.claude-opus-4-8-v1", label: "Bedrock Opus 4.8" },
   { id: "us.anthropic.claude-opus-4-6-v1", label: "Bedrock Opus 4.6" },
   { id: "us.anthropic.claude-sonnet-4-5-20250929-v2:0", label: "Bedrock Sonnet 4.5" },
   { id: "us.anthropic.claude-haiku-4-5-20251001-v1:0", label: "Bedrock Haiku 4.5" },
 ];
 
+let cached: { keyFingerprint: string; baseUrl: string; expiresAt: number; models: AdapterModel[] } | null = null;
+
 function isBedrockEnv(): boolean {
   return (
     process.env.CLAUDE_CODE_USE_BEDROCK === "1" ||
@@ -17,13 +26,134 @@ function isBedrockEnv(): boolean {
   );
 }
 
+function fingerprint(apiKey: string): string {
+  const digest = createHash("sha256").update(apiKey).digest("base64url").slice(0, 16);
+  return `${apiKey.length}:${digest}`;
+}
+
+function dedupeModels(models: AdapterModel[]): AdapterModel[] {
+  const seen = new Set<string>();
+  const deduped: AdapterModel[] = [];
+  for (const model of models) {
+    const id = model.id.trim();
+    if (!id || seen.has(id)) continue;
+    seen.add(id);
+    deduped.push({ id, label: model.label.trim() || id });
+  }
+  return deduped;
+}
+
+function mergedWithFallback(models: AdapterModel[]): AdapterModel[] {
+  return dedupeModels([
+    ...models,
+    ...DIRECT_MODELS,
+  ]);
+}
+
+function resolveAnthropicApiKey(): string | null {
+  const apiKey = process.env.ANTHROPIC_API_KEY?.trim();
+  return apiKey && apiKey.length > 0 ? apiKey : null;
+}
+
+function resolveAnthropicBaseUrl(): string {
+  const baseUrl = process.env.ANTHROPIC_BASE_URL?.trim();
+  return baseUrl && baseUrl.length > 0 ? baseUrl.replace(/\/+$/, "") : "https://api.anthropic.com";
+}
+
+async function fetchAnthropicModels(apiKey: string, baseUrl: string): Promise<AdapterModel[]> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), ANTHROPIC_MODELS_TIMEOUT_MS);
+  try {
+    const response = await fetch(`${baseUrl}${ANTHROPIC_MODELS_ENDPOINT}`, {
+      headers: {
+        "anthropic-version": ANTHROPIC_API_VERSION,
+        "x-api-key": apiKey,
+      },
+      signal: controller.signal,
+    });
+    if (!response.ok) return [];
+
+    const payload = (await response.json()) as { data?: unknown };
+    const data = Array.isArray(payload.data) ? payload.data : [];
+    const models: AdapterModel[] = [];
+    for (const item of data) {
+      if (typeof item !== "object" || item === null) continue;
+      const record = item as { id?: unknown; display_name?: unknown };
+      if (typeof record.id !== "string" || record.id.trim().length === 0) continue;
+      const displayName =
+        typeof record.display_name === "string" && record.display_name.trim().length > 0
+          ? record.display_name
+          : record.id;
+      models.push({
+        id: record.id,
+        label: displayName,
+      });
+    }
+    return dedupeModels(models);
+  } catch (error) {
+    console.warn("[paperclip] Claude model discovery failed", {
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return [];
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+async function loadClaudeModels(options?: { forceRefresh?: boolean }): Promise<AdapterModel[]> {
+  if (isBedrockEnv()) return dedupeModels(BEDROCK_MODELS);
+
+  const fallback = dedupeModels(DIRECT_MODELS);
+  const apiKey = resolveAnthropicApiKey();
+  if (!apiKey) return fallback;
+
+  const now = Date.now();
+  const baseUrl = resolveAnthropicBaseUrl();
+  const keyFingerprint = fingerprint(apiKey);
+  if (
+    options?.forceRefresh !== true &&
+    cached &&
+    cached.keyFingerprint === keyFingerprint &&
+    cached.baseUrl === baseUrl &&
+    cached.expiresAt > now
+  ) {
+    return cached.models;
+  }
+
+  const fetched = await fetchAnthropicModels(apiKey, baseUrl);
+  if (fetched.length > 0) {
+    const merged = mergedWithFallback(fetched);
+    cached = {
+      keyFingerprint,
+      baseUrl,
+      expiresAt: now + ANTHROPIC_MODELS_CACHE_TTL_MS,
+      models: merged,
+    };
+    return merged;
+  }
+
+  if (cached && cached.keyFingerprint === keyFingerprint && cached.baseUrl === baseUrl && cached.models.length > 0) {
+    return cached.models;
+  }
+
+  return fallback;
+}
+
 /**
  * Return the model list appropriate for the current auth mode.
  * When Bedrock env vars are detected, returns Bedrock-native model IDs;
  * otherwise returns standard Anthropic API model IDs.
  */
 export async function listClaudeModels(): Promise<AdapterModel[]> {
-  return isBedrockEnv() ? BEDROCK_MODELS : DIRECT_MODELS;
+  return loadClaudeModels();
+}
+
+export async function refreshClaudeModels(): Promise<AdapterModel[]> {
+  return loadClaudeModels({ forceRefresh: true });
+}
+
+export function resetClaudeModelsCacheForTests() {
+  cached = null;
 }
 
 /** Check whether a model ID is a Bedrock-native identifier (not an Anthropic API short name). */

packages/adapters/claude-local/src/server/skills.ts

@@ -3,10 +3,10 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import type {
   AdapterSkillContext,
-  AdapterSkillEntry,
   AdapterSkillSnapshot,
 } from "@paperclipai/adapter-utils";
 import {
+  buildRuntimeMountedSkillSnapshot,
   readPaperclipRuntimeSkillEntries,
   readInstalledSkillTargets,
   resolvePaperclipDesiredSkillNames,
@@ -30,76 +30,19 @@ function resolveClaudeSkillsHome(config: Record<string, unknown>) {
 
 async function buildClaudeSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
   const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
-  const availableByKey = new Map(availableEntries.map((entry) => [entry.key, entry]));
   const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
-  const desiredSet = new Set(desiredSkills);
   const skillsHome = resolveClaudeSkillsHome(config);
   const installed = await readInstalledSkillTargets(skillsHome);
-  const entries: AdapterSkillEntry[] = availableEntries.map((entry) => ({
-    key: entry.key,
-    runtimeName: entry.runtimeName,
-    desired: desiredSet.has(entry.key),
-    managed: true,
-    state: desiredSet.has(entry.key) ? "configured" : "available",
-    origin: entry.required ? "paperclip_required" : "company_managed",
-    originLabel: entry.required ? "Required by Paperclip" : "Managed by Paperclip",
-    readOnly: false,
-    sourcePath: entry.source,
-    targetPath: null,
-    detail: desiredSet.has(entry.key)
-      ? "Will be materialized into the stable Paperclip-managed Claude prompt bundle on the next run."
-      : null,
-    required: Boolean(entry.required),
-    requiredReason: entry.requiredReason ?? null,
-  }));
-  const warnings: string[] = [];
-
-  for (const desiredSkill of desiredSkills) {
-    if (availableByKey.has(desiredSkill)) continue;
-    warnings.push(`Desired skill "${desiredSkill}" is not available from the Paperclip skills directory.`);
-    entries.push({
-      key: desiredSkill,
-      runtimeName: null,
-      desired: true,
-      managed: true,
-      state: "missing",
-      origin: "external_unknown",
-      originLabel: "External or unavailable",
-      readOnly: false,
-      sourcePath: undefined,
-      targetPath: undefined,
-      detail: "Paperclip cannot find this skill in the local runtime skills directory.",
-    });
-  }
-
-  for (const [name, installedEntry] of installed.entries()) {
-    if (availableEntries.some((entry) => entry.runtimeName === name)) continue;
-    entries.push({
-      key: name,
-      runtimeName: name,
-      desired: false,
-      managed: false,
-      state: "external",
-      origin: "user_installed",
-      originLabel: "User-installed",
-      locationLabel: "~/.claude/skills",
-      readOnly: true,
-      sourcePath: null,
-      targetPath: installedEntry.targetPath ?? path.join(skillsHome, name),
-      detail: "Installed outside Paperclip management in the Claude skills home.",
-    });
-  }
-
-  entries.sort((left, right) => left.key.localeCompare(right.key));
-
-  return {
+  return buildRuntimeMountedSkillSnapshot({
     adapterType: "claude_local",
-    supported: true,
-    mode: "ephemeral",
+    availableEntries,
     desiredSkills,
-    entries,
-    warnings,
-  };
+    configuredDetail: "Will be materialized into the stable Paperclip-managed Claude prompt bundle on the next run.",
+    externalInstalled: installed,
+    externalLocationLabel: "~/.claude/skills",
+    externalDetail: "Installed outside Paperclip management in the Claude skills home.",
+    skillsHome,
+  });
 }
 
 export async function listClaudeSkills(ctx: AdapterSkillContext): Promise<AdapterSkillSnapshot> {

packages/adapters/codex-local/src/server/skills.ts

@@ -2,10 +2,10 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import type {
   AdapterSkillContext,
-  AdapterSkillEntry,
   AdapterSkillSnapshot,
 } from "@paperclipai/adapter-utils";
 import {
+  buildRuntimeMountedSkillSnapshot,
   readPaperclipRuntimeSkillEntries,
   resolvePaperclipDesiredSkillNames,
 } from "@paperclipai/adapter-utils/server-utils";
@@ -16,56 +16,13 @@ async function buildCodexSkillSnapshot(
   config: Record<string, unknown>,
 ): Promise<AdapterSkillSnapshot> {
   const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
-  const availableByKey = new Map(availableEntries.map((entry) => [entry.key, entry]));
   const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
-  const desiredSet = new Set(desiredSkills);
-  const entries: AdapterSkillEntry[] = availableEntries.map((entry) => ({
-    key: entry.key,
-    runtimeName: entry.runtimeName,
-    desired: desiredSet.has(entry.key),
-    managed: true,
-    state: desiredSet.has(entry.key) ? "configured" : "available",
-    origin: entry.required ? "paperclip_required" : "company_managed",
-    originLabel: entry.required ? "Required by Paperclip" : "Managed by Paperclip",
-    readOnly: false,
-    sourcePath: entry.source,
-    targetPath: null,
-    detail: desiredSet.has(entry.key)
-      ? "Will be linked into the effective CODEX_HOME/skills/ directory on the next run."
-      : null,
-    required: Boolean(entry.required),
-    requiredReason: entry.requiredReason ?? null,
-  }));
-  const warnings: string[] = [];
-
-  for (const desiredSkill of desiredSkills) {
-    if (availableByKey.has(desiredSkill)) continue;
-    warnings.push(`Desired skill "${desiredSkill}" is not available from the Paperclip skills directory.`);
-    entries.push({
-      key: desiredSkill,
-      runtimeName: null,
-      desired: true,
-      managed: true,
-      state: "missing",
-      origin: "external_unknown",
-      originLabel: "External or unavailable",
-      readOnly: false,
-      sourcePath: null,
-      targetPath: null,
-      detail: "Paperclip cannot find this skill in the local runtime skills directory.",
-    });
-  }
-
-  entries.sort((left, right) => left.key.localeCompare(right.key));
-
-  return {
+  return buildRuntimeMountedSkillSnapshot({
     adapterType: "codex_local",
-    supported: true,
-    mode: "ephemeral",
+    availableEntries,
     desiredSkills,
-    entries,
-    warnings,
-  };
+    configuredDetail: "Will be linked into the effective CODEX_HOME/skills/ directory on the next run.",
+  });
 }
 
 export async function listCodexSkills(ctx: AdapterSkillContext): Promise<AdapterSkillSnapshot> {

packages/adapters/grok-local/src/server/skills.ts

@@ -2,10 +2,10 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import type {
   AdapterSkillContext,
-  AdapterSkillEntry,
   AdapterSkillSnapshot,
 } from "@paperclipai/adapter-utils";
 import {
+  buildRuntimeMountedSkillSnapshot,
   readPaperclipRuntimeSkillEntries,
   resolvePaperclipDesiredSkillNames,
 } from "@paperclipai/adapter-utils/server-utils";
@@ -16,56 +16,13 @@ async function buildGrokSkillSnapshot(
   config: Record<string, unknown>,
 ): Promise<AdapterSkillSnapshot> {
   const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
-  const availableByKey = new Map(availableEntries.map((entry) => [entry.key, entry]));
   const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
-  const desiredSet = new Set(desiredSkills);
-  const entries: AdapterSkillEntry[] = availableEntries.map((entry) => ({
-    key: entry.key,
-    runtimeName: entry.runtimeName,
-    desired: desiredSet.has(entry.key),
-    managed: true,
-    state: desiredSet.has(entry.key) ? "configured" : "available",
-    origin: entry.required ? "paperclip_required" : "company_managed",
-    originLabel: entry.required ? "Required by Paperclip" : "Managed by Paperclip",
-    readOnly: false,
-    sourcePath: entry.source,
-    targetPath: null,
-    detail: desiredSet.has(entry.key)
-      ? "Will be copied into `.claude/skills` in the execution workspace on the next run."
-      : null,
-    required: Boolean(entry.required),
-    requiredReason: entry.requiredReason ?? null,
-  }));
-  const warnings: string[] = [];
-
-  for (const desiredSkill of desiredSkills) {
-    if (availableByKey.has(desiredSkill)) continue;
-    warnings.push(`Desired skill "${desiredSkill}" is not available from the Paperclip skills directory.`);
-    entries.push({
-      key: desiredSkill,
-      runtimeName: null,
-      desired: true,
-      managed: true,
-      state: "missing",
-      origin: "external_unknown",
-      originLabel: "External or unavailable",
-      readOnly: false,
-      sourcePath: null,
-      targetPath: null,
-      detail: "Paperclip cannot find this skill in the local runtime skills directory.",
-    });
-  }
-
-  entries.sort((left, right) => left.key.localeCompare(right.key));
-
-  return {
+  return buildRuntimeMountedSkillSnapshot({
     adapterType: "grok_local",
-    supported: true,
-    mode: "ephemeral",
+    availableEntries,
     desiredSkills,
-    entries,
-    warnings,
-  };
+    configuredDetail: "Will be copied into `.claude/skills` in the execution workspace on the next run.",
+  });
 }
 
 export async function listGrokSkills(ctx: AdapterSkillContext): Promise<AdapterSkillSnapshot> {

packages/adapters/openclaw-gateway/README.md

@@ -70,3 +70,16 @@ Structured gateway event logs use:
 - `[openclaw-gateway:event] run=<id> stream=<stream> data=<json>` for `event agent` frames
 
 UI/CLI parsers consume these lines to render transcript updates.
+
+## No-remote-git contract
+
+Like every Paperclip adapter, this one must treat the local execution-workspace
+cwd as the only persistence boundary across runs — no `git push` from runtime
+code, no assuming a `git remote` exists. The gateway transport here doesn't
+touch the workspace directly, but if you extend the adapter to ship code to
+the OpenClaw side, use the round-trip helpers in `@paperclipai/adapter-utils`
+(`prepareWorkspaceForSshExecution` → `restoreWorkspaceFromSshExecution`)
+rather than reaching for a git remote. See
+[`packages/adapters/AUTHORING.md`](../AUTHORING.md#no-remote-git-contract-cross-run-persistence)
+for the full contract and the pinning test at
+[`packages/adapter-utils/src/ssh-fixture.test.ts`](../../adapter-utils/src/ssh-fixture.test.ts).

packages/db/src/migrations/0092_mighty_puma.sql

@@ -0,0 +1,28 @@
+CREATE TABLE "issue_plan_decompositions" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"source_issue_id" uuid NOT NULL,
+	"accepted_plan_revision_id" uuid NOT NULL,
+	"accepted_interaction_id" uuid,
+	"status" text DEFAULT 'in_flight' NOT NULL,
+	"request_fingerprint" text NOT NULL,
+	"requested_child_count" integer DEFAULT 0 NOT NULL,
+	"requested_children" jsonb DEFAULT '[]'::jsonb NOT NULL,
+	"child_issue_ids" jsonb DEFAULT '[]'::jsonb NOT NULL,
+	"owner_agent_id" uuid,
+	"owner_user_id" text,
+	"owner_run_id" uuid,
+	"completed_at" timestamp with time zone,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "issue_plan_decompositions" ADD CONSTRAINT "issue_plan_decompositions_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issue_plan_decompositions" ADD CONSTRAINT "issue_plan_decompositions_source_issue_id_issues_id_fk" FOREIGN KEY ("source_issue_id") REFERENCES "public"."issues"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issue_plan_decompositions" ADD CONSTRAINT "issue_plan_decompositions_accepted_plan_revision_id_document_revisions_id_fk" FOREIGN KEY ("accepted_plan_revision_id") REFERENCES "public"."document_revisions"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issue_plan_decompositions" ADD CONSTRAINT "issue_plan_decompositions_accepted_interaction_id_issue_thread_interactions_id_fk" FOREIGN KEY ("accepted_interaction_id") REFERENCES "public"."issue_thread_interactions"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issue_plan_decompositions" ADD CONSTRAINT "issue_plan_decompositions_owner_agent_id_agents_id_fk" FOREIGN KEY ("owner_agent_id") REFERENCES "public"."agents"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issue_plan_decompositions" ADD CONSTRAINT "issue_plan_decompositions_owner_run_id_heartbeat_runs_id_fk" FOREIGN KEY ("owner_run_id") REFERENCES "public"."heartbeat_runs"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "issue_plan_decompositions_company_source_status_idx" ON "issue_plan_decompositions" USING btree ("company_id","source_issue_id","status");--> statement-breakpoint
+CREATE INDEX "issue_plan_decompositions_active_owner_idx" ON "issue_plan_decompositions" USING btree ("company_id","owner_agent_id") WHERE "issue_plan_decompositions"."status" = 'in_flight';--> statement-breakpoint
+CREATE UNIQUE INDEX "issue_plan_decompositions_source_revision_uq" ON "issue_plan_decompositions" USING btree ("company_id","source_issue_id","accepted_plan_revision_id");

packages/db/src/migrations/0093_giant_green_goblin.sql

@@ -0,0 +1,6 @@
+ALTER TABLE "execution_workspaces" DROP CONSTRAINT "execution_workspaces_company_id_companies_id_fk";
+--> statement-breakpoint
+ALTER TABLE "workspace_operations" DROP CONSTRAINT "workspace_operations_company_id_companies_id_fk";
+--> statement-breakpoint
+ALTER TABLE "execution_workspaces" ADD CONSTRAINT "execution_workspaces_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "workspace_operations" ADD CONSTRAINT "workspace_operations_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;

packages/db/src/migrations/meta/_journal.json

@@ -645,6 +645,20 @@
       "when": 1778810394522,
       "tag": "0091_old_swarm",
       "breakpoints": true
+    },
+    {
+      "idx": 92,
+      "version": "7",
+      "when": 1779999768200,
+      "tag": "0092_mighty_puma",
+      "breakpoints": true
+    },
+    {
+      "idx": 93,
+      "version": "7",
+      "when": 1780040470886,
+      "tag": "0093_giant_green_goblin",
+      "breakpoints": true
     }
   ]
-}
+}

packages/db/src/schema/execution_workspaces.ts

@@ -16,7 +16,7 @@ export const executionWorkspaces = pgTable(
   "execution_workspaces",
   {
     id: uuid("id").primaryKey().defaultRandom(),
-    companyId: uuid("company_id").notNull().references(() => companies.id),
+    companyId: uuid("company_id").notNull().references(() => companies.id, { onDelete: "cascade" }),
     projectId: uuid("project_id").notNull().references(() => projects.id, { onDelete: "cascade" }),
     projectWorkspaceId: uuid("project_workspace_id").references(() => projectWorkspaces.id, { onDelete: "set null" }),
     sourceIssueId: uuid("source_issue_id").references((): AnyPgColumn => issues.id, { onDelete: "set null" }),

packages/db/src/schema/index.ts

@@ -32,6 +32,7 @@ export { workspaceRuntimeServices } from "./workspace_runtime_services.js";
 export { projectGoals } from "./project_goals.js";
 export { goals } from "./goals.js";
 export { issues } from "./issues.js";
+export { issuePlanDecompositions } from "./issue_plan_decompositions.js";
 export { issueRecoveryActions } from "./issue_recovery_actions.js";
 export { issueReferenceMentions } from "./issue_reference_mentions.js";
 export { issueRelations } from "./issue_relations.js";

packages/db/src/schema/issue_plan_decompositions.ts

@@ -0,0 +1,48 @@
+import { sql } from "drizzle-orm";
+import { pgTable, uuid, text, integer, timestamp, jsonb, index, uniqueIndex } from "drizzle-orm/pg-core";
+import { agents } from "./agents.js";
+import { companies } from "./companies.js";
+import { documentRevisions } from "./document_revisions.js";
+import { heartbeatRuns } from "./heartbeat_runs.js";
+import { issueThreadInteractions } from "./issue_thread_interactions.js";
+import { issues } from "./issues.js";
+
+export const issuePlanDecompositions = pgTable(
+  "issue_plan_decompositions",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    companyId: uuid("company_id").notNull().references(() => companies.id),
+    sourceIssueId: uuid("source_issue_id").notNull().references(() => issues.id, { onDelete: "cascade" }),
+    acceptedPlanRevisionId: uuid("accepted_plan_revision_id")
+      .notNull()
+      .references(() => documentRevisions.id, { onDelete: "cascade" }),
+    acceptedInteractionId: uuid("accepted_interaction_id")
+      .references(() => issueThreadInteractions.id, { onDelete: "set null" }),
+    status: text("status").notNull().default("in_flight"),
+    requestFingerprint: text("request_fingerprint").notNull(),
+    requestedChildCount: integer("requested_child_count").notNull().default(0),
+    requestedChildren: jsonb("requested_children").$type<Record<string, unknown>[]>().notNull().default(sql`'[]'::jsonb`),
+    childIssueIds: jsonb("child_issue_ids").$type<string[]>().notNull().default(sql`'[]'::jsonb`),
+    ownerAgentId: uuid("owner_agent_id").references(() => agents.id, { onDelete: "set null" }),
+    ownerUserId: text("owner_user_id"),
+    ownerRunId: uuid("owner_run_id").references(() => heartbeatRuns.id, { onDelete: "set null" }),
+    completedAt: timestamp("completed_at", { withTimezone: true }),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    companySourceStatusIdx: index("issue_plan_decompositions_company_source_status_idx").on(
+      table.companyId,
+      table.sourceIssueId,
+      table.status,
+    ),
+    activeOwnerIdx: index("issue_plan_decompositions_active_owner_idx")
+      .on(table.companyId, table.ownerAgentId)
+      .where(sql`${table.status} = 'in_flight'`),
+    sourceRevisionUq: uniqueIndex("issue_plan_decompositions_source_revision_uq").on(
+      table.companyId,
+      table.sourceIssueId,
+      table.acceptedPlanRevisionId,
+    ),
+  }),
+);

packages/db/src/schema/workspace_operations.ts

@@ -17,7 +17,7 @@ export const workspaceOperations = pgTable(
   "workspace_operations",
   {
     id: uuid("id").primaryKey().defaultRandom(),
-    companyId: uuid("company_id").notNull().references(() => companies.id),
+    companyId: uuid("company_id").notNull().references(() => companies.id, { onDelete: "cascade" }),
     executionWorkspaceId: uuid("execution_workspace_id").references(() => executionWorkspaces.id, {
       onDelete: "set null",
     }),

packages/plugins/create-paperclip-plugin/README.md

@@ -34,7 +34,7 @@ Inside this repo, the generated package uses `@paperclipai/plugin-sdk` via `work
 Outside this repo, the scaffold snapshots `@paperclipai/plugin-sdk` from your local Paperclip checkout into a `.paperclip-sdk/` tarball and points the generated package at that local file by default. You can override the SDK source explicitly:
 
 ```bash
-node packages/plugins/create-paperclip-plugin/dist/index.js @acme/my-plugin \
+node packages/plugins/create-paperclip-plugin/dist/bin.js @acme/my-plugin \
   --output /absolute/path/to/plugins \
   --sdk-path /absolute/path/to/paperclip/packages/plugins/sdk
 ```

packages/plugins/create-paperclip-plugin/package.json

@@ -13,7 +13,7 @@
   },
   "type": "module",
   "bin": {
-    "create-paperclip-plugin": "./dist/index.js"
+    "create-paperclip-plugin": "./dist/bin.js"
   },
   "exports": {
     ".": "./src/index.ts"
@@ -21,7 +21,7 @@
   "publishConfig": {
     "access": "public",
     "bin": {
-      "create-paperclip-plugin": "./dist/index.js"
+      "create-paperclip-plugin": "./dist/bin.js"
     },
     "exports": {
       ".": {
@@ -38,6 +38,7 @@
   "scripts": {
     "build": "tsc",
     "clean": "rm -rf dist",
+    "test": "pnpm -w exec vitest run --root packages/plugins/create-paperclip-plugin --config vitest.config.ts",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {

packages/plugins/create-paperclip-plugin/src/bin.ts

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { scaffoldPluginProject, type ScaffoldPluginOptions } from "./index.js";
+
+interface RunCliDeps {
+  cwd?: string;
+  stdout?: (message: string) => void;
+  stderr?: (message: string) => void;
+  exit?: (code: number) => never;
+}
+
+function parseArg(argv: string[], name: string): string | undefined {
+  const index = argv.indexOf(name);
+  if (index === -1) return undefined;
+  return argv[index + 1];
+}
+
+/** Convert `@scope/name` to an output directory basename (`name`). */
+function packageToDirName(pluginName: string): string {
+  return pluginName.replace(/^@[^/]+\//, "");
+}
+
+/** CLI wrapper for `scaffoldPluginProject`. */
+export function runCli(argv = process.argv, deps: RunCliDeps = {}): string | undefined {
+  const pluginName = argv[2];
+  const stderr = deps.stderr ?? console.error;
+  const stdout = deps.stdout ?? console.log;
+  const exit = deps.exit ?? process.exit;
+
+  if (!pluginName) {
+    stderr("Usage: create-paperclip-plugin <name> [--template default|connector|workspace] [--output <dir>] [--sdk-path <paperclip-sdk-path>]");
+    exit(1);
+  }
+
+  const template = (parseArg(argv, "--template") ?? "default") as ScaffoldPluginOptions["template"];
+  const outputRoot = parseArg(argv, "--output") ?? deps.cwd ?? process.cwd();
+  const targetDir = path.resolve(outputRoot, packageToDirName(pluginName));
+
+  const out = scaffoldPluginProject({
+    pluginName,
+    outputDir: targetDir,
+    template,
+    displayName: parseArg(argv, "--display-name"),
+    description: parseArg(argv, "--description"),
+    author: parseArg(argv, "--author"),
+    category: parseArg(argv, "--category") as ScaffoldPluginOptions["category"] | undefined,
+    sdkPath: parseArg(argv, "--sdk-path"),
+  });
+
+  stdout(`Created plugin scaffold at ${out}`);
+  return out;
+}
+
+function isMainModule(): boolean {
+  const entrypoint = process.argv[1];
+  return entrypoint ? import.meta.url === pathToFileURL(entrypoint).href : false;
+}
+
+if (isMainModule()) {
+  runCli();
+}

packages/plugins/create-paperclip-plugin/src/entrypoints.test.ts

@@ -0,0 +1,74 @@
+import fs from "node:fs";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+
+const tempDirs: string[] = [];
+
+function makeTempDir(): string {
+  const dir = fs.mkdtempSync(path.join(process.cwd(), ".tmp-create-paperclip-plugin-"));
+  tempDirs.push(dir);
+  return dir;
+}
+
+afterEach(() => {
+  while (tempDirs.length > 0) {
+    const dir = tempDirs.pop();
+    if (dir) fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+describe("create-paperclip-plugin entrypoints", () => {
+  it("keeps src/index.ts import-safe when process.argv points at another bundled CLI", async () => {
+    const originalArgv = process.argv;
+    const outputRoot = makeTempDir();
+
+    try {
+      process.argv = [process.execPath, path.resolve("cli/dist/index.js"), "demo-plugin", "--output", outputRoot];
+      const library = await import("./index.js");
+
+      expect(library.scaffoldPluginProject).toBeTypeOf("function");
+      expect(fs.existsSync(path.join(outputRoot, "demo-plugin"))).toBe(false);
+    } finally {
+      process.argv = originalArgv;
+    }
+  });
+
+  it("runs scaffolding from src/bin.ts", async () => {
+    const { runCli } = await import("./bin.js");
+    const outputRoot = makeTempDir();
+    const stdout: string[] = [];
+    const outputDir = path.join(outputRoot, "demo-plugin");
+
+    const result = runCli(
+      [
+        process.execPath,
+        "create-paperclip-plugin",
+        "demo-plugin",
+        "--output",
+        outputRoot,
+        "--sdk-path",
+        path.resolve("packages/plugins/sdk"),
+      ],
+      {
+        stdout: (message) => stdout.push(message),
+        stderr: (message) => {
+          throw new Error(message);
+        },
+        exit: (code) => {
+          throw new Error(`unexpected exit ${code}`);
+        },
+      },
+    );
+
+    expect(result).toBe(outputDir);
+    expect(stdout).toEqual([`Created plugin scaffold at ${outputDir}`]);
+    expect(JSON.parse(fs.readFileSync(path.join(outputDir, "package.json"), "utf8"))).toMatchObject({
+      name: "demo-plugin",
+      paperclipPlugin: {
+        manifest: "./dist/manifest.js",
+        worker: "./dist/worker.js",
+        ui: "./dist/ui/",
+      },
+    });
+  });
+});

packages/plugins/create-paperclip-plugin/src/index.ts

@@ -1,4 +1,3 @@
-#!/usr/bin/env node
 import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
@@ -699,41 +698,3 @@ paperclipai plugin install ${shellQuote(toPosixPath(outputDir))}
 
   return outputDir;
 }
-
-function parseArg(name: string): string | undefined {
-  const index = process.argv.indexOf(name);
-  if (index === -1) return undefined;
-  return process.argv[index + 1];
-}
-
-/** CLI wrapper for `scaffoldPluginProject`. */
-function runCli() {
-  const pluginName = process.argv[2];
-  if (!pluginName) {
-    // eslint-disable-next-line no-console
-    console.error("Usage: create-paperclip-plugin <name> [--template default|connector|workspace] [--output <dir>] [--sdk-path <paperclip-sdk-path>]");
-    process.exit(1);
-  }
-
-  const template = (parseArg("--template") ?? "default") as PluginTemplate;
-  const outputRoot = parseArg("--output") ?? process.cwd();
-  const targetDir = path.resolve(outputRoot, packageToDirName(pluginName));
-
-  const out = scaffoldPluginProject({
-    pluginName,
-    outputDir: targetDir,
-    template,
-    displayName: parseArg("--display-name"),
-    description: parseArg("--description"),
-    author: parseArg("--author"),
-    category: parseArg("--category") as ScaffoldPluginOptions["category"] | undefined,
-    sdkPath: parseArg("--sdk-path"),
-  });
-
-  // eslint-disable-next-line no-console
-  console.log(`Created plugin scaffold at ${out}`);
-}
-
-if (import.meta.url === `file://${process.argv[1]}`) {
-  runCli();
-}

packages/plugins/create-paperclip-plugin/tsconfig.json

@@ -5,5 +5,6 @@
     "rootDir": "src",
     "types": ["node"]
   },
-  "include": ["src"]
+  "include": ["src"],
+  "exclude": ["src/**/*.test.ts"]
 }

packages/plugins/create-paperclip-plugin/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    include: ["src/**/*.test.ts"],
+  },
+});

packages/plugins/sandbox-providers/exe-dev/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paperclipai/plugin-exe-dev",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "exe.dev sandbox provider plugin for Paperclip environments",
   "license": "MIT",
   "homepage": "https://github.com/paperclipai/paperclip",

packages/plugins/sandbox-providers/exe-dev/src/manifest.ts

@@ -1,7 +1,7 @@
 import type { PaperclipPluginManifestV1 } from "@paperclipai/plugin-sdk";
 
 const PLUGIN_ID = "paperclip.exe-dev-sandbox-provider";
-const PLUGIN_VERSION = "0.1.0";
+const PLUGIN_VERSION = "0.1.1";
 
 const manifest: PaperclipPluginManifestV1 = {
   id: PLUGIN_ID,
@@ -26,106 +26,150 @@ const manifest: PaperclipPluginManifestV1 = {
       configSchema: {
         type: "object",
         properties: {
+          // ---- Essentials (always visible, in this order) ----
           apiKey: {
             type: "string",
             format: "secret-ref",
             description:
-              "Environment-specific exe.dev API token. Needs `/exec` permission for at least `new`, `ls`, and `rm`. Paste a token or an existing Paperclip secret reference; saved environments store pasted values as company secrets. Falls back to EXE_API_KEY if omitted.",
-          },
-          apiUrl: {
-            type: "string",
-            description:
-              "Optional exe.dev HTTPS API base URL or /exec endpoint. Defaults to https://exe.dev/exec.",
-          },
-          namePrefix: {
-            type: "string",
-            description: "Optional prefix used when generating VM names.",
-            default: "paperclip",
-          },
-          image: {
-            type: "string",
-            description: "Optional container image to use when creating the VM.",
-          },
-          command: {
-            type: "string",
-            description: "Optional container command passed to `exe.dev new --command`.",
-          },
-          cpu: {
-            type: "number",
-            description: "Optional CPU count passed to `exe.dev new --cpu`.",
-          },
-          memory: {
-            type: "string",
-            description: "Optional memory size such as `4GB`.",
-          },
-          disk: {
-            type: "string",
-            description: "Optional disk size such as `20GB`.",
-          },
-          comment: {
-            type: "string",
-            description: "Optional short note attached to created VMs.",
-          },
-          env: {
-            type: "object",
-            description: "Optional environment variables applied at VM creation time.",
-            additionalProperties: { type: "string" },
-          },
-          integrations: {
-            type: "array",
-            description: "Optional exe.dev integrations to attach during VM creation.",
-            items: { type: "string" },
-          },
-          tags: {
-            type: "array",
-            description: "Optional tags to apply during VM creation.",
-            items: { type: "string" },
-          },
-          setupScript: {
-            type: "string",
-            description: "Optional first-boot setup script passed to `exe.dev new --setup-script`.",
-          },
-          prompt: {
-            type: "string",
-            description: "Optional Shelley prompt passed to `exe.dev new --prompt`.",
-          },
-          timeoutMs: {
-            type: "number",
-            description: "Timeout for VM lifecycle and SSH operations in milliseconds.",
-            default: 300000,
-          },
-          reuseLease: {
-            type: "boolean",
-            description:
-              "Whether to keep the VM alive between runs instead of deleting it on release.",
-            default: false,
-          },
-          sshUser: {
-            type: "string",
-            description: "Optional SSH username for direct VM access.",
+              "Paste your exe.dev API token, or pick a saved Paperclip secret. Create one at exe.dev → Settings → API tokens with `/exec` scope (`new`, `ls`, `rm`).",
           },
           sshPrivateKey: {
             type: "string",
             format: "secret-ref",
-            maxLength: 4096,
+            maxLength: 8192,
             description:
-              "Optional exe.dev-registered SSH private key. Paste the private key or an existing Paperclip secret reference; saved environments store pasted values as company secrets. If omitted, Paperclip falls back to sshIdentityFile, then the host's default SSH agent/keychain.",
+              "Paste the SSH private key you registered with exe.dev, or pick a saved secret. Leave blank to fall back to an on-host key (see Advanced → SSH access).",
+          },
+          // ---- Advanced: SSH access ----
+          sshUser: {
+            type: "string",
+            description:
+              "Login user on the VM. Leave blank to use the image default, usually `root`.",
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "SSH access",
           },
           sshIdentityFile: {
             type: "string",
             description:
-              "Optional absolute path to the SSH private key the Paperclip host should use for VM access when sshPrivateKey is omitted. Leave both blank to rely on the host's default SSH agent/keychain.",
+              "Absolute path to a private key on the Paperclip host. Used only when SSH Private Key is empty.",
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "SSH access",
           },
           sshPort: {
             type: "number",
             description: "SSH port for direct VM access.",
             default: 22,
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "SSH access",
           },
           strictHostKeyChecking: {
             type: "string",
             description:
               "Host key policy passed to ssh via StrictHostKeyChecking. Typical values are `accept-new`, `yes`, or `no`.",
             default: "accept-new",
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "SSH access",
+          },
+          // ---- Advanced: VM resources ----
+          image: {
+            type: "string",
+            description: "Optional container image to use when creating the VM.",
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "VM resources",
+          },
+          cpu: {
+            type: "number",
+            description: "Optional CPU count passed to `exe.dev new --cpu`.",
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "VM resources",
+          },
+          memory: {
+            type: "string",
+            description: "Optional memory size such as `4GB`.",
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "VM resources",
+          },
+          disk: {
+            type: "string",
+            description: "Optional disk size such as `20GB`.",
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "VM resources",
+          },
+          // ---- Advanced: VM creation ----
+          command: {
+            type: "string",
+            description: "Optional container command passed to `exe.dev new --command`.",
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "VM creation",
+          },
+          env: {
+            type: "object",
+            description: "Optional environment variables applied at VM creation time.",
+            additionalProperties: { type: "string" },
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "VM creation",
+          },
+          integrations: {
+            type: "array",
+            description: "Optional exe.dev integrations to attach during VM creation.",
+            items: { type: "string" },
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "VM creation",
+          },
+          tags: {
+            type: "array",
+            description: "Optional tags to apply during VM creation.",
+            items: { type: "string" },
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "VM creation",
+          },
+          setupScript: {
+            type: "string",
+            description: "Optional first-boot setup script passed to `exe.dev new --setup-script`.",
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "VM creation",
+          },
+          prompt: {
+            type: "string",
+            description: "Optional Shelley prompt passed to `exe.dev new --prompt`.",
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "VM creation",
+          },
+          comment: {
+            type: "string",
+            description: "Optional short note attached to created VMs.",
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "VM creation",
+          },
+          namePrefix: {
+            type: "string",
+            description: "Optional prefix used when generating VM names.",
+            default: "paperclip",
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "VM creation",
+          },
+          // ---- Advanced: API + runtime ----
+          apiUrl: {
+            type: "string",
+            description:
+              "Optional exe.dev HTTPS API base URL or /exec endpoint. Defaults to https://exe.dev/exec.",
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "API + runtime",
+          },
+          timeoutMs: {
+            type: "number",
+            description: "Timeout for VM lifecycle and SSH operations in milliseconds.",
+            default: 300000,
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "API + runtime",
+          },
+          reuseLease: {
+            type: "boolean",
+            description:
+              "Whether to keep the VM alive between runs instead of deleting it on release.",
+            default: false,
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "API + runtime",
           },
         },
       },

packages/plugins/sandbox-providers/exe-dev/src/plugin.test.ts

@@ -14,7 +14,7 @@ vi.mock("node:child_process", async () => {
   };
 });
 
-import plugin from "./plugin.js";
+import plugin, { validateSshPrivateKey } from "./plugin.js";
 
 class MockChildProcess extends EventEmitter {
   stdout = new EventEmitter();
@@ -165,6 +165,117 @@ describe("exe.dev sandbox provider plugin", () => {
     });
   });
 
+  describe("sshPrivateKey validation", () => {
+    const VALID_OPENSSH = [
+      "-----BEGIN OPENSSH PRIVATE KEY-----",
+      "b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAAAMwAAAAtzc2gt",
+      "ZWQyNTUxOQAAACBPzMxQp4Y6XCfDV2t6oWmqHkKx0K7C7w7q9F6gQ3jPbgAAAJjJ8jjE",
+      "yfI4xAAAAAtzc2gtZWQyNTUxOQAAACBPzMxQp4Y6XCfDV2t6oWmqHkKx0K7C7w7q9F6g",
+      "Q3jPbgAAAEDqLhB4kV1tw8m4gE9oNCkF2cJv0YnHQ8E5sHU3xKnD5k/MzFCnhjpcJ8NX",
+      "a3qhaaoeQrHQrsLvDur0XqBDeM9uAAAAFXVzZXJAaG9zdAECAwQ=",
+      "-----END OPENSSH PRIVATE KEY-----",
+    ].join("\n");
+    const VALID_RSA_PEM = [
+      "-----BEGIN RSA PRIVATE KEY-----",
+      "MIIBOgIBAAJBAKj34GkxFhD90vcNLYLInFEX6Ppy1tPf9Cnzj4p4WGeKLs1Pt8Qu",
+      "KUpRKfFLfRYC9AIKjbJTWit+CqvjWYzvQwECAwEAAQJAIJLixBy2qpFoS4DSmoEm",
+      "o3qGy0t6z5tZbcgvflRslzu1HxXLpwYqQq2gMNw9UQAoHs3rDl+EzBjF6trBV5wF",
+      "wQIhANwiwDR7TVlIRk5kbgPMd2dDgY8mAU1cQ8KbWvjVMmKxAiEAxYTUyVjwhfQy",
+      "VJoR7T0n4XdR1n+W8Eth7AEPxnHfaQECIB5cNuqB9F1qC2pSyf6e+UAyl9rmKQXp",
+      "-----END RSA PRIVATE KEY-----",
+    ].join("\n");
+
+    it("accepts a valid OpenSSH PEM block", () => {
+      expect(validateSshPrivateKey(VALID_OPENSSH)).toBeNull();
+    });
+
+    it("accepts a valid PKCS#1 RSA PEM block", () => {
+      expect(validateSshPrivateKey(VALID_RSA_PEM)).toBeNull();
+    });
+
+    it("accepts UUID-like secret reference values from the save-time schema stage", async () => {
+      process.env.EXE_API_KEY = "host-key";
+
+      const result = await plugin.definition.onEnvironmentValidateConfig?.({
+        driverKey: "exe-dev",
+        config: {
+          apiKey: "api-key",
+          sshPrivateKey: "11111111-1111-4111-8111-111111111111",
+        },
+      });
+
+      expect(result).toMatchObject({
+        ok: true,
+        normalizedConfig: {
+          sshPrivateKey: "11111111-1111-4111-8111-111111111111",
+        },
+      });
+      expect(result?.errors ?? []).toEqual([]);
+    });
+
+    it("treats empty / whitespace-only input as valid (falls back to on-host key)", () => {
+      expect(validateSshPrivateKey("")).toBeNull();
+      expect(validateSshPrivateKey("   \n\n  ")).toBeNull();
+    });
+
+    it("rejects a pasted public key", () => {
+      expect(
+        validateSshPrivateKey("ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIE+gT9 user@host"),
+      ).toMatch(/looks like a PUBLIC key/);
+    });
+
+    it("rejects a PuTTY PPK file paste", () => {
+      const ppk = [
+        "PuTTY-User-Key-File-3: ssh-ed25519",
+        "Encryption: none",
+        "Comment: imported-openssh-key",
+        "Public-Lines: 2",
+        "AAAAC3NzaC1lZDI1NTE5AAAAIE+gT9zMxQp4Y6XCfDV2t6oWmqHkKx0K7C7w7q9F6g",
+        "Q3jP",
+      ].join("\n");
+      expect(validateSshPrivateKey(ppk)).toMatch(/PuTTY \.ppk/);
+    });
+
+    it("rejects a missing END marker (truncated paste)", () => {
+      const truncated = VALID_OPENSSH.split("\n").slice(0, -1).join("\n");
+      expect(validateSshPrivateKey(truncated)).toMatch(/missing its '-----END/);
+    });
+
+    it("rejects a body with non-base64 characters", () => {
+      const garbled = [
+        "-----BEGIN OPENSSH PRIVATE KEY-----",
+        "this is not base64!!",
+        "-----END OPENSSH PRIVATE KEY-----",
+      ].join("\n");
+      expect(validateSshPrivateKey(garbled)).toMatch(/non-base64/);
+    });
+
+    it("rejects a header/footer label mismatch", () => {
+      const mismatched = [
+        "-----BEGIN OPENSSH PRIVATE KEY-----",
+        "Zm9vYmFy",
+        "-----END RSA PRIVATE KEY-----",
+      ].join("\n");
+      expect(validateSshPrivateKey(mismatched)).toMatch(/header\/footer mismatch/);
+    });
+
+    it("returns the sshPrivateKey error from onEnvironmentValidateConfig on save", async () => {
+      process.env.EXE_API_KEY = "host-key";
+
+      const result = await plugin.definition.onEnvironmentValidateConfig?.({
+        driverKey: "exe-dev",
+        config: {
+          sshPrivateKey: "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIE+gT9 user@host",
+        },
+      });
+
+      expect(result?.ok).toBe(false);
+      expect(result?.errors ?? []).toEqual(
+        expect.arrayContaining([expect.stringMatching(/sshPrivateKey looks like a PUBLIC key/)]),
+      );
+    });
+  });
+
   it("acquires a lease by creating a VM and preparing the SSH workspace", async () => {
     fetchMock.mockResolvedValueOnce(
       new Response(JSON.stringify({
@@ -346,6 +457,38 @@ describe("exe.dev sandbox provider plugin", () => {
     expect(String(fetchMock.mock.calls[1]?.[1]?.body ?? "")).toBe("rm --json 'paperclip-env-run'");
   });
 
+  it("surfaces invalid SSH key-format guidance during lease acquisition", async () => {
+    fetchMock.mockResolvedValueOnce(
+      new Response(JSON.stringify({
+        vm_name: "paperclip-env-run",
+        ssh_dest: "paperclip-env-run.exe.xyz",
+        https_url: "https://paperclip-env-run.exe.xyz",
+        status: "running",
+      }), { status: 200 }),
+    );
+    fetchMock.mockResolvedValueOnce(new Response("{}", { status: 200 }));
+    queueSpawnResult({
+      code: 255,
+      stderr: 'Load key "/tmp/paperclip-exe-dev-ssh-abc/id_ed25519": invalid format\n',
+    });
+
+    await expect(plugin.definition.onEnvironmentAcquireLease?.({
+      driverKey: "exe-dev",
+      companyId: "company-1",
+      environmentId: "env-1",
+      runId: "run-1",
+      config: {
+        apiKey: "api-key",
+        sshPrivateKey: "not-actually-a-key",
+        timeoutMs: 300000,
+      },
+    })).rejects.toThrow(
+      "the configured SSH private key isn't an OpenSSH-format private key",
+    );
+
+    expect(String(fetchMock.mock.calls[1]?.[1]?.body ?? "")).toBe("rm --json 'paperclip-env-run'");
+  });
+
   it("redacts sensitive lifecycle flags in API errors", async () => {
     fetchMock.mockResolvedValueOnce(new Response("upstream boom", { status: 500 }));
 

packages/plugins/sandbox-providers/exe-dev/src/plugin.ts

@@ -68,6 +68,8 @@ const SSH_SIGKILL_GRACE_MS = 250;
 const MAX_VM_RECORD_DEPTH = 4;
 const EXE_DEV_SSH_ONBOARDING_MARKER = "Please complete registration by running: ssh exe.dev";
 const EXE_DEV_SSH_EMAIL_PROMPT = "Please enter your email address:";
+const EXE_DEV_SSH_INVALID_KEY_FORMAT = /Load key [^\n]*invalid format/i;
+const UUID_SECRET_REF_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
 // exe.dev's `--setup-script` runs at VM init as the unprivileged `exedev` user, which
 // has passwordless sudo. The Paperclip sandbox callback bridge is a Node script, so
@@ -139,6 +141,74 @@ function isValidUrl(value: string): boolean {
   }
 }
 
+function isSecretRef(value: string): boolean {
+  return UUID_SECRET_REF_RE.test(value);
+}
+
+// Catch the SSH-key paste failure modes we've seen in the wild (wrong file,
+// PPK export, truncated paste) before the user pays the cost of provisioning a
+// VM and getting a cryptic SSH error. Inline parse — no `ssh-keygen` dependency
+// — so this also works on hosts where openssh-client isn't installed.
+export function validateSshPrivateKey(rawKey: string): string | null {
+  const trimmed = rawKey.trim();
+  if (!trimmed) return null;
+
+  if (/^PuTTY-User-Key-File-\d/m.test(trimmed)) {
+    return "sshPrivateKey looks like a PuTTY .ppk file. Convert it to OpenSSH format (PuTTYgen → Conversions → Export OpenSSH key) and paste the resulting PEM.";
+  }
+
+  if (
+    /^(?:ssh-(?:rsa|dss|ed25519)|ecdsa-sha2-[a-z0-9-]+|sk-(?:ssh-ed25519|ecdsa-sha2-[a-z0-9-]+)@openssh\.com)\s+\S/.test(
+      trimmed,
+    )
+  ) {
+    return "sshPrivateKey looks like a PUBLIC key. Paste the matching private key (the file without the .pub extension).";
+  }
+
+  const headerMatch = trimmed.match(/^-----BEGIN ([A-Z0-9 ]*)PRIVATE KEY-----/m);
+  if (!headerMatch) {
+    return "sshPrivateKey must be a PEM-encoded private key starting with a line like '-----BEGIN OPENSSH PRIVATE KEY-----'.";
+  }
+
+  const footerMatch = trimmed.match(/^-----END ([A-Z0-9 ]*)PRIVATE KEY-----\s*$/m);
+  if (!footerMatch) {
+    return "sshPrivateKey is missing its '-----END … PRIVATE KEY-----' footer. Make sure you copied the whole file, including the final line.";
+  }
+
+  const headerLabel = headerMatch[1].trim();
+  const footerLabel = footerMatch[1].trim();
+  if (headerLabel !== footerLabel) {
+    return `sshPrivateKey header/footer mismatch (BEGIN ${headerLabel || "(none)"} vs END ${footerLabel || "(none)"}). The file is likely truncated or two keys are concatenated.`;
+  }
+
+  const headerLineEnd = trimmed.indexOf("\n", headerMatch.index ?? 0);
+  const footerStart = trimmed.lastIndexOf(footerMatch[0]);
+  if (headerLineEnd < 0 || footerStart <= headerLineEnd) {
+    return "sshPrivateKey appears to be empty between its BEGIN and END markers.";
+  }
+
+  const bodyLines = trimmed
+    .slice(headerLineEnd + 1, footerStart)
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+  if (bodyLines.length === 0) {
+    return "sshPrivateKey appears to be empty between its BEGIN and END markers.";
+  }
+
+  // PEM bodies are base64 lines, optionally preceded by `Header: value` lines
+  // on encrypted PKCS#1 keys (`Proc-Type:`, `DEK-Info:`).
+  const base64Line = /^[A-Za-z0-9+/=]+$/;
+  const pemHeaderLine = /^[A-Za-z][A-Za-z0-9-]*:\s.+$/;
+  for (const line of bodyLines) {
+    if (!base64Line.test(line) && !pemHeaderLine.test(line)) {
+      return "sshPrivateKey body contains non-base64 characters. The key may have been corrupted by line-wrapping or copy-paste.";
+    }
+  }
+
+  return null;
+}
+
 function normalizeApiUrl(value: string | null): string {
   if (!value) return DEFAULT_API_URL;
   const trimmed = value.trim();
@@ -498,6 +568,13 @@ function formatSshFailure(
     ].join(" ");
   }
 
+  if (EXE_DEV_SSH_INVALID_KEY_FORMAT.test(combinedOutput)) {
+    return [
+      `Failed to ${action} exe.dev VM ${vmName}: the configured SSH private key isn't an OpenSSH-format private key.`,
+      "Confirm the secret starts with `-----BEGIN … PRIVATE KEY-----` and isn't the `.pub` file or a PuTTY `.ppk` export.",
+    ].join(" ");
+  }
+
   return `Failed to ${action} exe.dev VM ${vmName}: ${result.stderr.trim() || result.stdout.trim() || "unknown error"}`;
 }
 
@@ -686,6 +763,10 @@ const plugin = definePlugin({
     ) {
       errors.push("strictHostKeyChecking cannot be empty.");
     }
+    if (config.sshPrivateKey && !isSecretRef(config.sshPrivateKey)) {
+      const sshKeyError = validateSshPrivateKey(config.sshPrivateKey);
+      if (sshKeyError) errors.push(sshKeyError);
+    }
 
     warnings.push(
       "The Paperclip host must have SSH access to the created exe.dev VM, and its SSH key must be registered with exe.dev. The API token only covers provisioning.",

packages/shared/src/document-anchors.test.ts

@@ -0,0 +1,183 @@
+import { describe, expect, it } from "vitest";
+import {
+  createDocumentAnchorSelector,
+  projectMarkdownToText,
+  remapDocumentAnchor,
+  resolveProjectionRange,
+  verifyDocumentAnchorSelector,
+} from "./document-anchors.js";
+
+function selectorFor(markdown: string, quote: string) {
+  const projection = projectMarkdownToText(markdown);
+  const start = projection.text.indexOf(quote);
+  expect(start).toBeGreaterThanOrEqual(0);
+  const range = resolveProjectionRange(projection, start, start + quote.length);
+  expect(range).not.toBeNull();
+  return createDocumentAnchorSelector(projection, range!);
+}
+
+describe("document text projection", () => {
+  it("projects markdown into normalized rendered text with source ranges", () => {
+    const markdown = [
+      "# Heading",
+      "",
+      "- Ship **bold** [link text](https://example.com) and `code span`.",
+      "| Name | Value |",
+      "| --- | --- |",
+      "| Alpha | Beta |",
+    ].join("\n");
+
+    const projection = projectMarkdownToText(markdown);
+
+    expect(projection.text).toContain("Heading");
+    expect(projection.text).toContain("Ship bold link text and code span.");
+    expect(projection.text).toContain("Name Value");
+    expect(projection.text).toContain("Alpha Beta");
+    expect(projection.text).not.toContain("https://example.com");
+    expect(projection.positions).toHaveLength(projection.text.length);
+
+    const linkStart = projection.text.indexOf("link text");
+    const range = resolveProjectionRange(projection, linkStart, linkStart + "link text".length);
+    expect(range?.markdownStart).toBe(markdown.indexOf("link text"));
+    expect(range?.markdownEnd).toBe(markdown.indexOf("link text") + "link text".length);
+  });
+
+  it("normalizes whitespace while retaining markdown offsets", () => {
+    const markdown = "First   line\n\nSecond\t\tline";
+    const projection = projectMarkdownToText(markdown);
+
+    expect(projection.text).toBe("First line Second line");
+    const range = resolveProjectionRange(projection, projection.text.indexOf("Second"), projection.text.length);
+    expect(range?.markdownStart).toBe(markdown.indexOf("Second"));
+    expect(range?.markdownEnd).toBe(markdown.length);
+  });
+
+  it("preserves non-link punctuation", () => {
+    const markdown = "Keep (parenthetical) [plain brackets] visible.";
+    const projection = projectMarkdownToText(markdown);
+
+    expect(projection.text).toBe("Keep (parenthetical) [plain brackets] visible.");
+  });
+});
+
+describe("document anchor verification and remapping", () => {
+  it("verifies a selector against its base revision", () => {
+    const markdown = "Intro text with **selected text** inside.";
+    const selector = selectorFor(markdown, "selected text");
+
+    const result = verifyDocumentAnchorSelector({ markdown, selector });
+
+    expect(result.ok).toBe(true);
+    expect(result.anchor?.selectedText).toBe("selected text");
+    expect(result.anchor?.markdownStart).toBe(markdown.indexOf("selected text"));
+  });
+
+  it("remaps exact anchors after surrounding text moves", () => {
+    const selector = selectorFor("Alpha paragraph.\n\nTarget sentence here.\n\nOmega paragraph.", "Target sentence here.");
+    const previousAnchor = {
+      selectedText: selector.quote.exact,
+      prefixText: selector.quote.prefix,
+      suffixText: selector.quote.suffix,
+      normalizedStart: selector.position.normalizedStart,
+      normalizedEnd: selector.position.normalizedEnd,
+      markdownStart: selector.position.markdownStart,
+      markdownEnd: selector.position.markdownEnd,
+    };
+
+    const result = remapDocumentAnchor({
+      previousAnchor,
+      nextMarkdown: "Omega paragraph.\n\nAlpha paragraph.\n\nTarget sentence here.",
+    });
+
+    expect(result.anchorState).toBe("active");
+    expect(result.confidence).toBe("exact");
+    expect(result.anchor?.selectedText).toBe("Target sentence here.");
+  });
+
+  it("uses context and proximity to disambiguate duplicate quotes", () => {
+    const selector = selectorFor("One apple near the start.\n\nTwo apple near the end.", "apple");
+    const previousAnchor = {
+      selectedText: selector.quote.exact,
+      prefixText: selector.quote.prefix,
+      suffixText: selector.quote.suffix,
+      normalizedStart: selector.position.normalizedStart,
+      normalizedEnd: selector.position.normalizedEnd,
+      markdownStart: selector.position.markdownStart,
+      markdownEnd: selector.position.markdownEnd,
+    };
+
+    const result = remapDocumentAnchor({
+      previousAnchor,
+      nextMarkdown: "Zero apple elsewhere.\n\nOne apple near the start.\n\nTwo apple near the end.",
+    });
+
+    expect(result.anchorState).toBe("active");
+    expect(result.confidence).toBe("duplicate");
+    expect(result.anchor?.prefixText).toContain("One");
+  });
+
+  it("marks duplicate anchors ambiguous when context cannot distinguish them", () => {
+    const selector = selectorFor("apple apple", "apple");
+    const previousAnchor = {
+      selectedText: selector.quote.exact,
+      prefixText: "",
+      suffixText: "",
+      normalizedStart: selector.position.normalizedStart,
+      normalizedEnd: selector.position.normalizedEnd,
+      markdownStart: selector.position.markdownStart,
+      markdownEnd: selector.position.markdownEnd,
+    };
+
+    const result = remapDocumentAnchor({ previousAnchor, nextMarkdown: "apple apple" });
+
+    expect(result.anchorState).toBe("stale");
+    expect(result.confidence).toBe("ambiguous");
+  });
+
+  it("keeps edited anchors as stale fuzzy matches", () => {
+    const selector = selectorFor("We rely on an important launch assumption for scope.", "important launch assumption");
+    const previousAnchor = {
+      selectedText: selector.quote.exact,
+      prefixText: selector.quote.prefix,
+      suffixText: selector.quote.suffix,
+      normalizedStart: selector.position.normalizedStart,
+      normalizedEnd: selector.position.normalizedEnd,
+      markdownStart: selector.position.markdownStart,
+      markdownEnd: selector.position.markdownEnd,
+    };
+
+    const result = remapDocumentAnchor({
+      previousAnchor,
+      nextMarkdown: "We rely on an important product launch assumption for scope.",
+    });
+
+    expect(result.anchorState).toBe("stale");
+    expect(result.confidence).toBe("fuzzy");
+    expect(result.anchor?.selectedText).toBe("important product launch assumption");
+  });
+
+  it("marks deleted anchors orphaned and allows future remapping from the latest known anchor", () => {
+    const selector = selectorFor("Keep this reviewed phrase in mind.", "reviewed phrase");
+    const previousAnchor = {
+      selectedText: selector.quote.exact,
+      prefixText: selector.quote.prefix,
+      suffixText: selector.quote.suffix,
+      normalizedStart: selector.position.normalizedStart,
+      normalizedEnd: selector.position.normalizedEnd,
+      markdownStart: selector.position.markdownStart,
+      markdownEnd: selector.position.markdownEnd,
+    };
+
+    const missing = remapDocumentAnchor({ previousAnchor, nextMarkdown: "The target disappeared." });
+    const recovered = remapDocumentAnchor({
+      previousAnchor,
+      nextMarkdown: "The target came back: reviewed phrase.",
+    });
+
+    expect(missing.anchorState).toBe("orphaned");
+    expect(missing.confidence).toBe("missing");
+    expect(missing.anchor).toBeNull();
+    expect(recovered.anchorState).toBe("active");
+    expect(recovered.anchor?.selectedText).toBe("reviewed phrase");
+  });
+});

packages/shared/src/index.ts

@@ -473,6 +473,12 @@ export type {
   RequestConfirmationTarget,
   RequestConfirmationPayload,
   RequestConfirmationResult,
+  AcceptedPlanDecompositionStatus,
+  AcceptedPlanDecompositionChild,
+  AcceptedPlanDecomposition,
+  AcceptedPlanDecompositionResult,
+  AcceptedPlanDecompositionChildIssue,
+  AcceptedPlanDecompositionSummary,
   IssueThreadInteractionBase,
   SuggestTasksInteraction,
   AskUserQuestionsInteraction,
@@ -868,6 +874,7 @@ export {
   createIssueSchema,
   createIssueInputSchema,
   createChildIssueSchema,
+  createAcceptedPlanDecompositionSchema,
   resolveCreateIssueStatusDefault,
   createIssueLabelSchema,
   issueBlockedInboxAttentionSchema,
@@ -936,6 +943,7 @@ export {
   releaseIssueTreeHoldSchema,
   type CreateIssue,
   type CreateChildIssue,
+  type CreateAcceptedPlanDecomposition,
   type CreateIssueLabel,
   type UpdateIssue,
   type ResolveIssueRecoveryAction,

packages/shared/src/types/index.ts

@@ -238,6 +238,12 @@ export type {
   RequestConfirmationTarget,
   RequestConfirmationPayload,
   RequestConfirmationResult,
+  AcceptedPlanDecompositionStatus,
+  AcceptedPlanDecompositionChild,
+  AcceptedPlanDecomposition,
+  AcceptedPlanDecompositionResult,
+  AcceptedPlanDecompositionChildIssue,
+  AcceptedPlanDecompositionSummary,
   IssueThreadInteractionBase,
   SuggestTasksInteraction,
   AskUserQuestionsInteraction,

packages/shared/src/types/instance.ts

@@ -29,6 +29,7 @@ export interface InstanceGeneralSettings {
 export interface InstanceExperimentalSettings {
   enableEnvironments: boolean;
   enableIsolatedWorkspaces: boolean;
+  enableIssuePlanDecompositions: boolean;
   enableCloudSync: boolean;
   autoRestartDevServerWhenIdle: boolean;
   enableIssueGraphLivenessAutoRecovery: boolean;

packages/shared/src/types/issue.ts

@@ -129,6 +129,71 @@ export interface LegacyPlanDocument {
   source: "issue_description";
 }
 
+export type AcceptedPlanDecompositionStatus = "in_flight" | "completed";
+
+export interface AcceptedPlanDecompositionChild {
+  projectId?: string | null;
+  projectWorkspaceId?: string | null;
+  goalId?: string | null;
+  blockedByIssueIds?: string[];
+  title: string;
+  description?: string | null;
+  status: IssueStatus;
+  workMode: IssueWorkMode;
+  priority: IssuePriority;
+  assigneeAgentId?: string | null;
+  assigneeUserId?: string | null;
+  requestDepth?: number;
+  billingCode?: string | null;
+  assigneeAdapterOverrides?: IssueAssigneeAdapterOverrides | null;
+  executionPolicy?: IssueExecutionPolicy | null;
+  executionWorkspaceId?: string | null;
+  executionWorkspacePreference?: string | null;
+  executionWorkspaceSettings?: IssueExecutionWorkspaceSettings | null;
+  labelIds?: string[];
+  acceptanceCriteria?: string[];
+  blockParentUntilDone?: boolean;
+}
+
+export interface AcceptedPlanDecomposition {
+  id: string;
+  companyId: string;
+  sourceIssueId: string;
+  acceptedPlanRevisionId: string;
+  acceptedInteractionId: string | null;
+  status: AcceptedPlanDecompositionStatus;
+  requestFingerprint: string;
+  requestedChildCount: number;
+  childIssueIds: string[];
+  ownerAgentId: string | null;
+  ownerUserId: string | null;
+  ownerRunId: string | null;
+  completedAt: Date | string | null;
+  createdAt: Date | string;
+  updatedAt: Date | string;
+}
+
+export interface AcceptedPlanDecompositionResult {
+  decomposition: AcceptedPlanDecomposition;
+  childIssueIds: string[];
+  newlyCreatedChildIssueIds: string[];
+}
+
+export interface AcceptedPlanDecompositionChildIssue {
+  id: string;
+  identifier: string | null;
+  title: string;
+  status: IssueStatus;
+  priority: IssuePriority;
+  assigneeAgentId: string | null;
+  assigneeUserId: string | null;
+}
+
+export interface AcceptedPlanDecompositionSummary extends AcceptedPlanDecomposition {
+  acceptedPlanRevisionNumber: number | null;
+  childIssues: AcceptedPlanDecompositionChildIssue[];
+}
+
 export interface IssueRelationIssueSummary {
   id: string;
   identifier: string | null;

packages/shared/src/types/plugin.ts

@@ -38,8 +38,24 @@ import type { Routine, RoutineTrigger, RoutineVariable } from "./routine.js";
 /**
  * A JSON Schema object used for plugin config schemas and tool parameter schemas.
  * Plugins provide these as plain JSON Schema compatible objects.
+ *
+ * The Paperclip extension keywords below are recognised by the Paperclip UI
+ * but are otherwise ignored by standard JSON Schema validators.
  */
-export type JsonSchema = Record<string, unknown>;
+export type JsonSchema = {
+  /**
+   * When true, the Paperclip config UI hides this property behind an
+   * "Advanced options" disclosure. Defaults to false (always visible).
+   */
+  "x-paperclip-advanced"?: boolean;
+  /**
+   * Optional sub-section heading used to group advanced properties inside
+   * the disclosure (e.g. "SSH access", "VM resources"). Ignored when
+   * `x-paperclip-advanced` is not true.
+   */
+  "x-paperclip-group"?: string;
+  [key: string]: unknown;
+};
 
 export type {
   PluginDatabaseCoreReadTable,

packages/shared/src/types/workspace-operation.ts

@@ -2,7 +2,8 @@ export type WorkspaceOperationPhase =
   | "worktree_prepare"
   | "workspace_provision"
   | "workspace_teardown"
-  | "worktree_cleanup";
+  | "worktree_cleanup"
+  | "workspace_finalize";
 
 export type WorkspaceOperationStatus = "running" | "succeeded" | "failed" | "skipped";
 

packages/shared/src/validators/company-skill.test.ts

@@ -0,0 +1,158 @@
+import { describe, expect, it } from "vitest";
+import {
+  catalogSkillFileDetailSchema,
+  catalogSkillListQuerySchema,
+  companySkillAuditResultSchema,
+  companySkillInstallCatalogResultSchema,
+  companySkillInstallCatalogSchema,
+  companySkillInstallUpdateSchema,
+  companySkillResetSchema,
+  companySkillUpdateStatusSchema,
+} from "./company-skill.js";
+
+const catalogSkill = {
+  id: "paperclipai:bundled:software-development:review",
+  key: "paperclipai/bundled/software-development/review",
+  kind: "bundled",
+  category: "software-development",
+  slug: "review",
+  name: "review",
+  description: "Review code",
+  path: "catalog/bundled/software-development/review",
+  entrypoint: "SKILL.md",
+  trustLevel: "markdown_only",
+  compatibility: "compatible",
+  defaultInstall: false,
+  recommendedForRoles: ["engineer"],
+  requires: [],
+  tags: ["review"],
+  files: [{ path: "SKILL.md", kind: "skill", sizeBytes: 8, sha256: "abc" }],
+  contentHash: "sha256:abc",
+};
+
+const companySkill = {
+  id: "00000000-0000-4000-8000-000000000001",
+  companyId: "00000000-0000-4000-8000-000000000002",
+  key: catalogSkill.key,
+  slug: catalogSkill.slug,
+  name: catalogSkill.name,
+  description: catalogSkill.description,
+  markdown: "# Review\n",
+  sourceType: "catalog",
+  sourceLocator: "/tmp/review",
+  sourceRef: catalogSkill.contentHash,
+  trustLevel: "markdown_only",
+  compatibility: "compatible",
+  fileInventory: [{ path: "SKILL.md", kind: "skill" }],
+  metadata: {
+    sourceKind: "catalog",
+    catalogId: catalogSkill.id,
+    originHash: catalogSkill.contentHash,
+  },
+  createdAt: "2026-05-26T00:00:00.000Z",
+  updatedAt: "2026-05-26T00:00:00.000Z",
+};
+
+describe("company skill catalog validators", () => {
+  it("accepts catalog list and install request shapes", () => {
+    expect(catalogSkillListQuerySchema.parse({
+      kind: "bundled",
+      category: "software-development",
+      q: "review",
+    })).toEqual({
+      kind: "bundled",
+      category: "software-development",
+      q: "review",
+    });
+
+    expect(companySkillInstallCatalogSchema.parse({
+      catalogSkillId: catalogSkill.id,
+      slug: "team-review",
+      force: true,
+    })).toEqual({
+      catalogSkillId: catalogSkill.id,
+      slug: "team-review",
+      force: true,
+    });
+  });
+
+  it("rejects invalid catalog filter and install payloads", () => {
+    expect(() => catalogSkillListQuerySchema.parse({ kind: "external" })).toThrow();
+    expect(() => companySkillInstallCatalogSchema.parse({ force: true })).toThrow();
+  });
+
+  it("accepts catalog file and install result responses", () => {
+    expect(catalogSkillFileDetailSchema.parse({
+      catalogSkillId: catalogSkill.id,
+      path: "SKILL.md",
+      kind: "skill",
+      content: "# Review\n",
+      language: "markdown",
+      markdown: true,
+    })).toMatchObject({
+      catalogSkillId: catalogSkill.id,
+      path: "SKILL.md",
+    });
+
+    expect(companySkillInstallCatalogResultSchema.parse({
+      action: "created",
+      skill: companySkill,
+      catalogSkill,
+      warnings: [],
+    })).toMatchObject({
+      action: "created",
+      skill: {
+        key: catalogSkill.key,
+        sourceType: "catalog",
+      },
+      catalogSkill: {
+        id: catalogSkill.id,
+      },
+    });
+  });
+
+  it("accepts update status, audit, update, and reset contract shapes", () => {
+    expect(companySkillUpdateStatusSchema.parse({
+      supported: true,
+      reason: null,
+      trackingRef: catalogSkill.id,
+      currentRef: "sha256:old",
+      latestRef: catalogSkill.contentHash,
+      hasUpdate: true,
+      installedHash: "sha256:installed",
+      originHash: catalogSkill.contentHash,
+      userModifiedAt: "2026-05-26T00:00:00.000Z",
+      updateHoldReason: "local_modifications",
+      auditVerdict: "warning",
+      auditCodes: ["local_modifications"],
+    })).toMatchObject({
+      supported: true,
+      updateHoldReason: "local_modifications",
+      auditVerdict: "warning",
+    });
+
+    expect(companySkillAuditResultSchema.parse({
+      skillId: companySkill.id,
+      installedHash: "sha256:installed",
+      originHash: catalogSkill.contentHash,
+      verdict: "fail",
+      codes: ["remote_fetch_exec"],
+      findings: [{
+        code: "remote_fetch_exec",
+        severity: "error",
+        message: "Remote-fetch or dynamic execution pattern is not allowed.",
+        path: "SKILL.md",
+      }],
+      scannedAt: "2026-05-26T00:00:00.000Z",
+      scanVersion: "skills-audit-v1",
+    })).toMatchObject({
+      verdict: "fail",
+      codes: ["remote_fetch_exec"],
+    });
+
+    expect(companySkillInstallUpdateSchema.parse(undefined)).toEqual({});
+    expect(companySkillInstallUpdateSchema.parse({ force: true })).toEqual({ force: true });
+    expect(companySkillResetSchema.parse(undefined)).toEqual({});
+    expect(companySkillResetSchema.parse({ force: true })).toEqual({ force: true });
+  });
+});

packages/shared/src/validators/index.ts

@@ -186,6 +186,7 @@ export {
   createIssueSchema,
   createIssueInputSchema,
   createChildIssueSchema,
+  createAcceptedPlanDecompositionSchema,
   resolveCreateIssueStatusDefault,
   createIssueLabelSchema,
   issueBlockedInboxAttentionSchema,
@@ -237,6 +238,7 @@ export {
   restoreIssueDocumentRevisionSchema,
   type CreateIssue,
   type CreateChildIssue,
+  type CreateAcceptedPlanDecomposition,
   type CreateIssueLabel,
   type UpdateIssue,
   type IssueExecutionWorkspaceSettings,

packages/shared/src/validators/instance.ts

@@ -38,6 +38,7 @@ export const patchInstanceGeneralSettingsSchema = instanceGeneralSettingsSchema.
 export const instanceExperimentalSettingsSchema = z.object({
   enableEnvironments: z.boolean().default(false),
   enableIsolatedWorkspaces: z.boolean().default(false),
+  enableIssuePlanDecompositions: z.boolean().default(false),
   enableCloudSync: z.boolean().default(false),
   autoRestartDevServerWhenIdle: z.boolean().default(false),
   enableIssueGraphLivenessAutoRecovery: z.boolean().default(false),

packages/shared/src/validators/issue.ts

@@ -412,6 +412,13 @@ export const createChildIssueSchema = withCreateIssueStatusDefault(createIssueBa
 
 export type CreateChildIssue = z.infer<typeof createChildIssueSchema>;
 
+export const createAcceptedPlanDecompositionSchema = z.object({
+  acceptedPlanRevisionId: z.string().uuid(),
+  children: z.array(createChildIssueSchema).min(1).max(25),
+});
+
+export type CreateAcceptedPlanDecomposition = z.infer<typeof createAcceptedPlanDecompositionSchema>;
+
 export const createIssueLabelSchema = z.object({
   name: z.string().trim().min(1).max(48),
   color: z.string().regex(/^#(?:[0-9a-fA-F]{6})$/, "Color must be a 6-digit hex value"),