more docs on workspace strategy'

.changeset/add-pi-adapter-support.md

@@ -0,0 +1,5 @@
+---
+"@paperclipai/shared": minor
+---
+
+Add support for Pi local adapter in constants and onboarding UI.

.github/workflows/release.yml

@@ -32,7 +32,7 @@ concurrency:
 
 jobs:
   verify:
-    if: startsWith(github.ref, 'refs/heads/release/')
+    if: github.ref == 'refs/heads/master'
     runs-on: ubuntu-latest
     timeout-minutes: 30
     permissions:
@@ -68,7 +68,7 @@ jobs:
         run: pnpm build
 
   publish:
-    if: startsWith(github.ref, 'refs/heads/release/')
+    if: github.ref == 'refs/heads/master'
     needs: verify
     runs-on: ubuntu-latest
     timeout-minutes: 45
@@ -115,9 +115,9 @@ jobs:
           fi
           ./scripts/release.sh "${args[@]}"
 
-      - name: Push stable release branch commit and tag
+      - name: Push stable release commit and tag
         if: inputs.channel == 'stable' && !inputs.dry_run
-        run: git push origin "HEAD:${GITHUB_REF_NAME}" --follow-tags
+        run: git push origin HEAD:master --follow-tags
 
       - name: Create GitHub Release
         if: inputs.channel == 'stable' && !inputs.dry_run

Dockerfile

@@ -32,10 +32,8 @@ RUN test -f server/dist/index.js || (echo "ERROR: server build output missing" &
 
 FROM base AS production
 WORKDIR /app
-COPY --chown=node:node --from=build /app /app
-RUN npm install --global --omit=dev @anthropic-ai/claude-code@latest @openai/codex@latest opencode-ai \
-  && mkdir -p /paperclip \
-  && chown node:node /paperclip
+COPY --from=build /app /app
+RUN npm install --global --omit=dev @anthropic-ai/claude-code@latest @openai/codex@latest opencode-ai
 
 ENV NODE_ENV=production \
   HOME=/paperclip \
@@ -51,5 +49,4 @@ ENV NODE_ENV=production \
 VOLUME ["/paperclip"]
 EXPOSE 3100
 
-USER node
 CMD ["node", "--import", "./server/node_modules/tsx/dist/loader.mjs", "server/dist/index.js"]

cli/CHANGELOG.md

@@ -1,26 +1,5 @@
 # paperclipai
 
-## 0.3.0
-
-### Minor Changes
-
-- Stable release preparation for 0.3.0
-
-### Patch Changes
-
-- Updated dependencies [6077ae6]
-- Updated dependencies
-  - @paperclipai/shared@0.3.0
-  - @paperclipai/adapter-utils@0.3.0
-  - @paperclipai/adapter-claude-local@0.3.0
-  - @paperclipai/adapter-codex-local@0.3.0
-  - @paperclipai/adapter-cursor-local@0.3.0
-  - @paperclipai/adapter-openclaw-gateway@0.3.0
-  - @paperclipai/adapter-opencode-local@0.3.0
-  - @paperclipai/adapter-pi-local@0.3.0
-  - @paperclipai/db@0.3.0
-  - @paperclipai/server@0.3.0
-
 ## 0.2.7
 
 ### Patch Changes

cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paperclipai",
-  "version": "0.3.0",
+  "version": "0.2.7",
   "description": "Paperclip CLI — orchestrate AI agent teams to run a business",
   "type": "module",
   "bin": {

cli/src/__tests__/worktree.test.ts

@@ -1,8 +1,5 @@
-import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
 import { describe, expect, it } from "vitest";
-import { copySeededSecretsKey, rebindWorkspaceCwd } from "../commands/worktree.js";
 import {
   buildWorktreeConfig,
   buildWorktreeEnvEntries,
@@ -125,78 +122,4 @@ describe("worktree helpers", () => {
     expect(full.excludedTables).toEqual([]);
     expect(full.nullifyColumns).toEqual({});
   });
-
-  it("copies the source local_encrypted secrets key into the seeded worktree instance", () => {
-    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-worktree-secrets-"));
-    try {
-      const sourceConfigPath = path.join(tempRoot, "source", "config.json");
-      const sourceKeyPath = path.join(tempRoot, "source", "secrets", "master.key");
-      const targetKeyPath = path.join(tempRoot, "target", "secrets", "master.key");
-      fs.mkdirSync(path.dirname(sourceKeyPath), { recursive: true });
-      fs.writeFileSync(sourceKeyPath, "source-master-key", "utf8");
-
-      const sourceConfig = buildSourceConfig();
-      sourceConfig.secrets.localEncrypted.keyFilePath = sourceKeyPath;
-
-      copySeededSecretsKey({
-        sourceConfigPath,
-        sourceConfig,
-        sourceEnvEntries: {},
-        targetKeyFilePath: targetKeyPath,
-      });
-
-      expect(fs.readFileSync(targetKeyPath, "utf8")).toBe("source-master-key");
-    } finally {
-      fs.rmSync(tempRoot, { recursive: true, force: true });
-    }
-  });
-
-  it("writes the source inline secrets master key into the seeded worktree instance", () => {
-    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-worktree-secrets-"));
-    try {
-      const sourceConfigPath = path.join(tempRoot, "source", "config.json");
-      const targetKeyPath = path.join(tempRoot, "target", "secrets", "master.key");
-
-      copySeededSecretsKey({
-        sourceConfigPath,
-        sourceConfig: buildSourceConfig(),
-        sourceEnvEntries: {
-          PAPERCLIP_SECRETS_MASTER_KEY: "inline-source-master-key",
-        },
-        targetKeyFilePath: targetKeyPath,
-      });
-
-      expect(fs.readFileSync(targetKeyPath, "utf8")).toBe("inline-source-master-key");
-    } finally {
-      fs.rmSync(tempRoot, { recursive: true, force: true });
-    }
-  });
-
-  it("rebinds same-repo workspace paths onto the current worktree root", () => {
-    expect(
-      rebindWorkspaceCwd({
-        sourceRepoRoot: "/Users/nmurray/paperclip",
-        targetRepoRoot: "/Users/nmurray/paperclip-pr-432",
-        workspaceCwd: "/Users/nmurray/paperclip",
-      }),
-    ).toBe("/Users/nmurray/paperclip-pr-432");
-
-    expect(
-      rebindWorkspaceCwd({
-        sourceRepoRoot: "/Users/nmurray/paperclip",
-        targetRepoRoot: "/Users/nmurray/paperclip-pr-432",
-        workspaceCwd: "/Users/nmurray/paperclip/packages/db",
-      }),
-    ).toBe("/Users/nmurray/paperclip-pr-432/packages/db");
-  });
-
-  it("does not rebind paths outside the source repo root", () => {
-    expect(
-      rebindWorkspaceCwd({
-        sourceRepoRoot: "/Users/nmurray/paperclip",
-        targetRepoRoot: "/Users/nmurray/paperclip-pr-432",
-        workspaceCwd: "/Users/nmurray/other-project",
-      }),
-    ).toBeNull();
-  });
 });

cli/src/commands/auth-bootstrap-ceo.ts

@@ -75,11 +75,6 @@ export async function bootstrapCeoInvite(opts: {
   }
 
   const db = createDb(dbUrl);
-  const closableDb = db as typeof db & {
-    $client?: {
-      end?: (options?: { timeout?: number }) => Promise<void>;
-    };
-  };
   try {
     const existingAdminCount = await db
       .select()
@@ -127,7 +122,5 @@ export async function bootstrapCeoInvite(opts: {
   } catch (err) {
     p.log.error(`Could not create bootstrap invite: ${err instanceof Error ? err.message : String(err)}`);
     p.log.info("If using embedded-postgres, start the Paperclip server and run this command again.");
-  } finally {
-    await closableDb.$client?.end?.({ timeout: 5 }).catch(() => undefined);
   }
 }

cli/src/commands/run.ts

@@ -86,29 +86,11 @@ export async function runCommand(opts: RunOptions): Promise<void> {
     await bootstrapCeoInvite({
       config: configPath,
       dbUrl: startedServer.databaseUrl,
-      baseUrl: resolveBootstrapInviteBaseUrl(config, startedServer),
+      baseUrl: startedServer.apiUrl.replace(/\/api$/, ""),
     });
   }
 }
 
-function resolveBootstrapInviteBaseUrl(
-  config: PaperclipConfig,
-  startedServer: StartedServer,
-): string {
-  const explicitBaseUrl =
-    process.env.PAPERCLIP_PUBLIC_URL ??
-    process.env.PAPERCLIP_AUTH_PUBLIC_BASE_URL ??
-    process.env.BETTER_AUTH_URL ??
-    process.env.BETTER_AUTH_BASE_URL ??
-    (config.auth.baseUrlMode === "explicit" ? config.auth.publicBaseUrl : undefined);
-
-  if (typeof explicitBaseUrl === "string" && explicitBaseUrl.trim().length > 0) {
-    return explicitBaseUrl.trim().replace(/\/+$/, "");
-  }
-
-  return startedServer.apiUrl.replace(/\/api$/, "");
-}
-
 function formatError(err: unknown): string {
   if (err instanceof Error) {
     if (err.message && err.message.trim().length > 0) return err.message;

cli/src/commands/worktree.ts

@@ -1,17 +1,14 @@
-import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, rmSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
 import { createServer } from "node:net";
 import * as p from "@clack/prompts";
 import pc from "picocolors";
-import { eq } from "drizzle-orm";
 import {
   applyPendingMigrations,
-  createDb,
   ensurePostgresDatabase,
   formatDatabaseBackupResult,
-  projectWorkspaces,
   runDatabaseBackup,
   runDatabaseRestore,
 } from "@paperclipai/db";
@@ -21,7 +18,6 @@ import { expandHomePrefix } from "../config/home.js";
 import type { PaperclipConfig } from "../config/schema.js";
 import { readConfig, resolveConfigPath, writeConfig } from "../config/store.js";
 import { printPaperclipCliBanner } from "../utils/banner.js";
-import { resolveRuntimeLikePath } from "../utils/path-resolver.js";
 import {
   buildWorktreeConfig,
   buildWorktreeEnvEntries,
@@ -77,20 +73,6 @@ type EmbeddedPostgresHandle = {
   stop: () => Promise<void>;
 };
 
-type GitWorkspaceInfo = {
-  root: string;
-  commonDir: string;
-};
-
-type SeedWorktreeDatabaseResult = {
-  backupSummary: string;
-  reboundWorkspaces: Array<{
-    name: string;
-    fromCwd: string;
-    toCwd: string;
-  }>;
-};
-
 function nonEmpty(value: string | null | undefined): string | null {
   return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
 }
@@ -150,107 +132,6 @@ function detectGitBranchName(cwd: string): string | null {
   }
 }
 
-function detectGitWorkspaceInfo(cwd: string): GitWorkspaceInfo | null {
-  try {
-    const root = execFileSync("git", ["rev-parse", "--show-toplevel"], {
-      cwd,
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "ignore"],
-    }).trim();
-    const commonDirRaw = execFileSync("git", ["rev-parse", "--git-common-dir"], {
-      cwd: root,
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "ignore"],
-    }).trim();
-    return {
-      root: path.resolve(root),
-      commonDir: path.resolve(root, commonDirRaw),
-    };
-  } catch {
-    return null;
-  }
-}
-
-export function rebindWorkspaceCwd(input: {
-  sourceRepoRoot: string;
-  targetRepoRoot: string;
-  workspaceCwd: string;
-}): string | null {
-  const sourceRepoRoot = path.resolve(input.sourceRepoRoot);
-  const targetRepoRoot = path.resolve(input.targetRepoRoot);
-  const workspaceCwd = path.resolve(input.workspaceCwd);
-  const relative = path.relative(sourceRepoRoot, workspaceCwd);
-  if (!relative || relative === "") {
-    return targetRepoRoot;
-  }
-  if (relative.startsWith("..") || path.isAbsolute(relative)) {
-    return null;
-  }
-  return path.resolve(targetRepoRoot, relative);
-}
-
-async function rebindSeededProjectWorkspaces(input: {
-  targetConnectionString: string;
-  currentCwd: string;
-}): Promise<SeedWorktreeDatabaseResult["reboundWorkspaces"]> {
-  const targetRepo = detectGitWorkspaceInfo(input.currentCwd);
-  if (!targetRepo) return [];
-
-  const db = createDb(input.targetConnectionString);
-  const closableDb = db as typeof db & {
-    $client?: { end?: (opts?: { timeout?: number }) => Promise<void> };
-  };
-
-  try {
-    const rows = await db
-      .select({
-        id: projectWorkspaces.id,
-        name: projectWorkspaces.name,
-        cwd: projectWorkspaces.cwd,
-      })
-      .from(projectWorkspaces);
-
-    const rebound: SeedWorktreeDatabaseResult["reboundWorkspaces"] = [];
-    for (const row of rows) {
-      const workspaceCwd = nonEmpty(row.cwd);
-      if (!workspaceCwd) continue;
-
-      const sourceRepo = detectGitWorkspaceInfo(workspaceCwd);
-      if (!sourceRepo) continue;
-      if (sourceRepo.commonDir !== targetRepo.commonDir) continue;
-
-      const reboundCwd = rebindWorkspaceCwd({
-        sourceRepoRoot: sourceRepo.root,
-        targetRepoRoot: targetRepo.root,
-        workspaceCwd,
-      });
-      if (!reboundCwd) continue;
-
-      const normalizedCurrent = path.resolve(workspaceCwd);
-      if (reboundCwd === normalizedCurrent) continue;
-      if (!existsSync(reboundCwd)) continue;
-
-      await db
-        .update(projectWorkspaces)
-        .set({
-          cwd: reboundCwd,
-          updatedAt: new Date(),
-        })
-        .where(eq(projectWorkspaces.id, row.id));
-
-      rebound.push({
-        name: row.name,
-        fromCwd: normalizedCurrent,
-        toCwd: reboundCwd,
-      });
-    }
-
-    return rebound;
-  } finally {
-    await closableDb.$client?.end?.({ timeout: 5 }).catch(() => undefined);
-  }
-}
-
 function resolveSourceConfigPath(opts: WorktreeInitOptions): string {
   if (opts.fromConfig) return path.resolve(opts.fromConfig);
   const sourceHome = path.resolve(expandHomePrefix(opts.fromDataDir ?? "~/.paperclip"));
@@ -273,54 +154,6 @@ function resolveSourceConnectionString(config: PaperclipConfig, envEntries: Reco
   return `postgres://paperclip:paperclip@127.0.0.1:${port}/paperclip`;
 }
 
-export function copySeededSecretsKey(input: {
-  sourceConfigPath: string;
-  sourceConfig: PaperclipConfig;
-  sourceEnvEntries: Record<string, string>;
-  targetKeyFilePath: string;
-}): void {
-  if (input.sourceConfig.secrets.provider !== "local_encrypted") {
-    return;
-  }
-
-  mkdirSync(path.dirname(input.targetKeyFilePath), { recursive: true });
-
-  const sourceInlineMasterKey =
-    nonEmpty(input.sourceEnvEntries.PAPERCLIP_SECRETS_MASTER_KEY) ??
-    nonEmpty(process.env.PAPERCLIP_SECRETS_MASTER_KEY);
-  if (sourceInlineMasterKey) {
-    writeFileSync(input.targetKeyFilePath, sourceInlineMasterKey, {
-      encoding: "utf8",
-      mode: 0o600,
-    });
-    try {
-      chmodSync(input.targetKeyFilePath, 0o600);
-    } catch {
-      // best effort
-    }
-    return;
-  }
-
-  const sourceKeyFileOverride =
-    nonEmpty(input.sourceEnvEntries.PAPERCLIP_SECRETS_MASTER_KEY_FILE) ??
-    nonEmpty(process.env.PAPERCLIP_SECRETS_MASTER_KEY_FILE);
-  const sourceConfiguredKeyPath = sourceKeyFileOverride ?? input.sourceConfig.secrets.localEncrypted.keyFilePath;
-  const sourceKeyFilePath = resolveRuntimeLikePath(sourceConfiguredKeyPath, input.sourceConfigPath);
-
-  if (!existsSync(sourceKeyFilePath)) {
-    throw new Error(
-      `Cannot seed worktree database because source local_encrypted secrets key was not found at ${sourceKeyFilePath}.`,
-    );
-  }
-
-  copyFileSync(sourceKeyFilePath, input.targetKeyFilePath);
-  try {
-    chmodSync(input.targetKeyFilePath, 0o600);
-  } catch {
-    // best effort
-  }
-}
-
 async function ensureEmbeddedPostgres(dataDir: string, preferredPort: number): Promise<EmbeddedPostgresHandle> {
   const moduleName = "embedded-postgres";
   let EmbeddedPostgres: EmbeddedPostgresCtor;
@@ -378,16 +211,10 @@ async function seedWorktreeDatabase(input: {
   targetPaths: WorktreeLocalPaths;
   instanceId: string;
   seedMode: WorktreeSeedMode;
-}): Promise<SeedWorktreeDatabaseResult> {
+}): Promise<string> {
   const seedPlan = resolveWorktreeSeedPlan(input.seedMode);
   const sourceEnvFile = resolvePaperclipEnvFile(input.sourceConfigPath);
   const sourceEnvEntries = readPaperclipEnvEntries(sourceEnvFile);
-  copySeededSecretsKey({
-    sourceConfigPath: input.sourceConfigPath,
-    sourceConfig: input.sourceConfig,
-    sourceEnvEntries,
-    targetKeyFilePath: input.targetPaths.secretsKeyFilePath,
-  });
   let sourceHandle: EmbeddedPostgresHandle | null = null;
   let targetHandle: EmbeddedPostgresHandle | null = null;
 
@@ -426,15 +253,8 @@ async function seedWorktreeDatabase(input: {
       backupFile: backup.backupFile,
     });
     await applyPendingMigrations(targetConnectionString);
-    const reboundWorkspaces = await rebindSeededProjectWorkspaces({
-      targetConnectionString,
-      currentCwd: input.targetPaths.cwd,
-    });
 
-    return {
-      backupSummary: formatDatabaseBackupResult(backup),
-      reboundWorkspaces,
-    };
+    return formatDatabaseBackupResult(backup);
   } finally {
     if (targetHandle?.startedByThisProcess) {
       await targetHandle.stop();
@@ -495,7 +315,6 @@ export async function worktreeInitCommand(opts: WorktreeInitOptions): Promise<vo
   loadPaperclipEnvFile(paths.configPath);
 
   let seedSummary: string | null = null;
-  let reboundWorkspaceSummary: SeedWorktreeDatabaseResult["reboundWorkspaces"] = [];
   if (opts.seed !== false) {
     if (!sourceConfig) {
       throw new Error(
@@ -505,7 +324,7 @@ export async function worktreeInitCommand(opts: WorktreeInitOptions): Promise<vo
     const spinner = p.spinner();
     spinner.start(`Seeding isolated worktree database from source instance (${seedMode})...`);
     try {
-      const seeded = await seedWorktreeDatabase({
+      seedSummary = await seedWorktreeDatabase({
         sourceConfigPath,
         sourceConfig,
         targetConfig,
@@ -513,8 +332,6 @@ export async function worktreeInitCommand(opts: WorktreeInitOptions): Promise<vo
         instanceId,
         seedMode,
       });
-      seedSummary = seeded.backupSummary;
-      reboundWorkspaceSummary = seeded.reboundWorkspaces;
       spinner.stop(`Seeded isolated worktree database (${seedMode}).`);
     } catch (error) {
       spinner.stop(pc.red("Failed to seed worktree database."));
@@ -530,11 +347,6 @@ export async function worktreeInitCommand(opts: WorktreeInitOptions): Promise<vo
   if (seedSummary) {
     p.log.message(pc.dim(`Seed mode: ${seedMode}`));
     p.log.message(pc.dim(`Seed snapshot: ${seedSummary}`));
-    for (const rebound of reboundWorkspaceSummary) {
-      p.log.message(
-        pc.dim(`Rebound workspace ${rebound.name}: ${rebound.fromCwd} -> ${rebound.toCwd}`),
-      );
-    }
   }
   p.outro(
     pc.green(

cli/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "../tsconfig.base.json",
+  "extends": "../tsconfig.json",
   "compilerOptions": {
     "outDir": "dist",
     "rootDir": "src"

doc/DOCKER.md

@@ -122,7 +122,5 @@ Notes:
 - Container runtime user id defaults to your local `id -u` so the mounted data dir stays writable while avoiding root runtime.
 - Smoke script defaults to `authenticated/private` mode so `HOST=0.0.0.0` can be exposed to the host.
 - Smoke script defaults host port to `3131` to avoid conflicts with local Paperclip on `3100`.
-- Smoke script also defaults `PAPERCLIP_PUBLIC_URL` to `http://localhost:<HOST_PORT>` so bootstrap invite URLs and auth callbacks use the reachable host port instead of the container's internal `3100`.
-- In authenticated mode, the smoke script defaults `SMOKE_AUTO_BOOTSTRAP=true` and drives the real bootstrap path automatically: it signs up a real user, runs `paperclipai auth bootstrap-ceo` inside the container to mint a real bootstrap invite, accepts that invite over HTTP, and verifies board session access.
 - Run the script in the foreground to watch the onboarding flow; stop with `Ctrl+C` after validation.
 - The image definition is in `Dockerfile.onboard-smoke`.

doc/PUBLISHING.md

@@ -8,11 +8,10 @@ For the maintainer release workflow, use [doc/RELEASING.md](RELEASING.md). This
 
 Use these scripts instead of older one-off publish commands:
 
-- [`scripts/release-start.sh`](../scripts/release-start.sh) to create or resume `release/X.Y.Z`
 - [`scripts/release-preflight.sh`](../scripts/release-preflight.sh) before any canary or stable release
 - [`scripts/release.sh`](../scripts/release.sh) for canary and stable npm publishes
 - [`scripts/rollback-latest.sh`](../scripts/rollback-latest.sh) to repoint `latest` during rollback
-- [`scripts/create-github-release.sh`](../scripts/create-github-release.sh) after pushing the stable branch tag
+- [`scripts/create-github-release.sh`](../scripts/create-github-release.sh) after a stable push
 
 ## Why the CLI needs special packaging
 
@@ -88,7 +87,7 @@ This means:
 
 Stable releases publish normal semver versions such as `1.2.3` under the npm dist-tag `latest`.
 
-The stable publish flow also creates the local release commit and git tag on `release/X.Y.Z`. Pushing that branch commit/tag, creating the GitHub Release, and merging the release branch back to `master` happen afterward as separate maintainer steps.
+The stable publish flow also creates the local release commit and git tag. Pushing the commit/tag and creating the GitHub Release happen afterward as separate maintainer steps.
 
 ## Rollback model
 
@@ -110,7 +109,7 @@ Recommended CI release setup:
 
 - use npm trusted publishing via GitHub OIDC
 - require approval through the `npm-release` environment
-- run releases from `release/X.Y.Z`
+- run releases from `master`
 - use canary first, then stable
 
 ## Related Files

doc/RELEASING.md

@@ -2,138 +2,260 @@
 
 Maintainer runbook for shipping a full Paperclip release across npm, GitHub, and the website-facing changelog surface.
 
-The release model is branch-driven:
+This document is intentionally practical:
 
-1. Start a release train on `release/X.Y.Z`
-2. Draft the stable changelog on that branch
-3. Publish one or more canaries from that branch
-4. Publish stable from that same branch head
-5. Push the branch commit and tag
-6. Create the GitHub Release
-7. Merge `release/X.Y.Z` back to `master` without squash or rebase
+- TL;DR command sequences are at the top.
+- Detailed checklists come next.
+- Motivation, failure handling, and rollback playbooks follow after that.
 
 ## Release Surfaces
 
-Every release has four separate surfaces:
+Every Paperclip release has four separate surfaces:
 
-1. **Verification** — the exact git SHA passes typecheck, tests, and build
-2. **npm** — `paperclipai` and public workspace packages are published
-3. **GitHub** — the stable release gets a git tag and GitHub Release
-4. **Website / announcements** — the stable changelog is published externally and announced
+1. **Verification** — the exact git SHA must pass typecheck, tests, and build.
+2. **npm** — `paperclipai` and the public workspace packages are published.
+3. **GitHub** — the stable release gets a git tag and a GitHub Release.
+4. **Website / announcements** — the stable changelog is published externally and announced.
 
-A release is done only when all four surfaces are handled.
-
-## Core Invariants
-
-- Canary and stable for `X.Y.Z` must come from the same `release/X.Y.Z` branch.
-- The release scripts must run from the matching `release/X.Y.Z` branch.
-- Once `vX.Y.Z` exists locally, on GitHub, or on npm, that release train is frozen.
-- Do not squash-merge or rebase-merge a release branch PR back to `master`.
-- The stable changelog is always `releases/vX.Y.Z.md`. Never create canary changelog files.
-
-The reason for the merge rule is simple: the tag must keep pointing at the exact published commit. Squash or rebase breaks that property.
+Treat those as related but separate. npm can succeed while the GitHub Release is still pending. GitHub can be correct while the website changelog is stale. A maintainer release is done only when all four surfaces are handled.
 
 ## TL;DR
 
-### 1. Start the release train
+### Canary release
 
-Use this to compute the next version, create or resume the branch, create or resume a dedicated worktree, and push the branch to GitHub.
+Use this when you want an installable prerelease without changing `latest`.
 
 ```bash
-./scripts/release-start.sh patch
-```
+# 0. Confirm master already has the CI-owned lockfile refresh merged
+#    If package manifests changed recently, wait for the refresh-lockfile PR first.
 
-That script:
-
-- fetches the release remote and tags
-- computes the next stable version from the latest `v*` tag
-- creates or resumes `release/X.Y.Z`
-- creates or resumes a dedicated worktree
-- pushes the branch to the remote by default
-- refuses to reuse a frozen release train
-
-### 2. Draft the stable changelog
-
-From the release worktree:
-
-```bash
-VERSION=X.Y.Z
-claude --print --output-format stream-json --verbose --dangerously-skip-permissions --model claude-opus-4-6 "Use the release-changelog skill to draft or update releases/v${VERSION}.md for Paperclip. Read doc/RELEASING.md and skills/release-changelog/SKILL.md, then generate the stable changelog for v${VERSION} from commits since the last stable tag. Do not create a canary changelog."
-```
-
-### 3. Verify and publish a canary
-
-```bash
+# 1. Preflight the canary candidate
 ./scripts/release-preflight.sh canary patch
+
+# 2. Draft or update the stable changelog for the intended stable version
+VERSION=0.2.8
+claude --print --output-format stream-json --verbose --dangerously-skip-permissions --model claude-opus-4-6 "Use the release-changelog skill to draft or update releases/v${VERSION}.md for Paperclip. Read doc/RELEASING.md and skills/release-changelog/SKILL.md, then generate the stable changelog for v${VERSION} from commits since the last stable tag. Do not create a canary changelog."
+
+# 3. Preview the canary release
 ./scripts/release.sh patch --canary --dry-run
+
+# 4. Publish the canary
 ./scripts/release.sh patch --canary
+
+# 5. Smoke test what users will actually install
 PAPERCLIPAI_VERSION=canary ./scripts/docker-onboard-smoke.sh
-```
 
-Users install canaries with:
-
-```bash
+# Users install with:
 npx paperclipai@canary onboard
 ```
 
-### 4. Publish stable
+Result:
+
+- npm gets a prerelease such as `1.2.3-canary.0` under dist-tag `canary`
+- `latest` is unchanged
+- no git tag is created
+- no GitHub Release is created
+- the working tree returns to clean after the script finishes
+- after stable `0.2.7`, a patch canary targets `0.2.8-canary.0`, never `0.2.7-canary.N`
+
+### Stable release
+
+Use this only after the canary SHA is good enough to become the public default.
 
 ```bash
+# 0. Confirm master already has the CI-owned lockfile refresh merged
+#    If package manifests changed recently, wait for the refresh-lockfile PR first.
+
+# 1. Start from the vetted commit
+git checkout master
+git pull
+
+# 2. Preflight the stable candidate
 ./scripts/release-preflight.sh stable patch
+
+# 3. Confirm the stable changelog exists
+VERSION=0.2.8
+ls "releases/v${VERSION}.md"
+
+# 4. Preview the stable publish
 ./scripts/release.sh patch --dry-run
+
+# 5. Publish the stable release to npm and create the local release commit + tag
 ./scripts/release.sh patch
-git push public-gh HEAD --follow-tags
+
+# 6. Push the release commit and tag
+git push public-gh HEAD:master --follow-tags
+
+# 7. Create or update the GitHub Release from the pushed tag
 ./scripts/create-github-release.sh X.Y.Z
 ```
 
-Then open a PR from `release/X.Y.Z` to `master` and merge without squash or rebase.
+Result:
 
-## Release Branches
+- npm gets stable `X.Y.Z` under dist-tag `latest`
+- a local git commit and tag `vX.Y.Z` are created
+- after push, GitHub gets the matching Release
+- the website and announcement steps still need to be handled manually
 
-Paperclip uses one release branch per target stable version:
+### Emergency rollback
 
-- `release/0.3.0`
-- `release/0.3.1`
-- `release/1.0.0`
-
-Do not create separate per-canary branches like `canary/0.3.0-1`. A canary is just a prerelease snapshot of the same stable train.
-
-## Script Entry Points
-
-- [`scripts/release-start.sh`](../scripts/release-start.sh) — create or resume the release train branch/worktree
-- [`scripts/release-preflight.sh`](../scripts/release-preflight.sh) — validate branch, version plan, git/npm state, and verification gate
-- [`scripts/release.sh`](../scripts/release.sh) — publish canary or stable from the release branch
-- [`scripts/create-github-release.sh`](../scripts/create-github-release.sh) — create or update the GitHub Release after pushing the tag
-- [`scripts/rollback-latest.sh`](../scripts/rollback-latest.sh) — repoint `latest` to the last good stable version
-
-## Detailed Workflow
-
-### 1. Start or resume the release train
-
-Run:
+If `latest` is broken after publish, repoint it to the last known good stable version first, then work on the fix.
 
 ```bash
-./scripts/release-start.sh <patch|minor|major>
+# Preview
+./scripts/rollback-latest.sh X.Y.Z --dry-run
+
+# Roll back latest for every public package
+./scripts/rollback-latest.sh X.Y.Z
 ```
 
-Useful options:
+This does **not** unpublish anything. It only moves the `latest` dist-tag back to the last good stable release.
+
+### Standalone onboarding smoke
+
+You already have a script for isolated onboarding verification:
 
 ```bash
-./scripts/release-start.sh patch --dry-run
-./scripts/release-start.sh minor --worktree-dir ../paperclip-release-0.4.0
-./scripts/release-start.sh patch --no-push
+HOST_PORT=3232 DATA_DIR=./data/release-smoke-canary PAPERCLIPAI_VERSION=canary ./scripts/docker-onboard-smoke.sh
+HOST_PORT=3233 DATA_DIR=./data/release-smoke-stable PAPERCLIPAI_VERSION=latest ./scripts/docker-onboard-smoke.sh
 ```
 
-The script is intentionally idempotent:
+This is the best existing fit when you want:
 
-- if `release/X.Y.Z` already exists locally, it reuses it
-- if the branch already exists on the remote, it resumes it locally
-- if the branch is already checked out in another worktree, it points you there
-- if `vX.Y.Z` already exists locally, remotely, or on npm, it refuses to reuse that train
+- a standalone Paperclip data dir
+- a dedicated host port
+- an end-to-end `npx paperclipai ... onboard` check
 
-### 2. Write the stable changelog early
+In authenticated/private mode, the expected result is a full authenticated onboarding flow, including printing the bootstrap CEO invite once startup completes.
 
-Create or update:
+If you want to exercise onboarding from a fresh local checkout rather than npm, use:
+
+```bash
+./scripts/clean-onboard-git.sh
+```
+
+That is not a required release step every time, but it is a useful higher-confidence check when onboarding is the main risk area or when you need to verify what the current codebase does before publishing.
+
+If you want to exercise onboarding from the current committed ref in your local repo, use:
+
+```bash
+./scripts/clean-onboard-ref.sh
+PAPERCLIP_PORT=3234 ./scripts/clean-onboard-ref.sh
+./scripts/clean-onboard-ref.sh HEAD
+```
+
+This uses the current committed `HEAD` in a detached temp worktree. It does **not** include uncommitted local edits.
+
+### GitHub Actions release
+
+There is also a manual workflow at [`.github/workflows/release.yml`](../.github/workflows/release.yml). It is designed for npm trusted publishing via GitHub OIDC instead of long-lived npm tokens.
+
+Use it from the Actions tab:
+
+1. Choose `Release`
+2. Choose `channel`: `canary` or `stable`
+3. Choose `bump`: `patch`, `minor`, or `major`
+4. Choose whether this is a `dry_run`
+5. Run it from `master`
+
+The workflow:
+
+- reruns `typecheck`, `test:run`, and `build`
+- gates publish behind the `npm-release` environment
+- can publish canaries without touching `latest`
+- can publish stable, push the release commit and tag, and create the GitHub Release
+
+## Release Checklist
+
+### Before any publish
+
+- [ ] The working tree is clean, including untracked files
+- [ ] The target branch and SHA are the ones you actually want to release
+- [ ] If package manifests changed, the CI-owned `pnpm-lock.yaml` refresh is already merged on `master`
+- [ ] The required verification gate passed on that exact SHA
+- [ ] The bump type is correct for the user-visible impact
+- [ ] The stable changelog file exists or is ready to be written at `releases/vX.Y.Z.md`
+- [ ] You know which previous stable version you would roll back to if needed
+
+### Before a canary
+
+- [ ] You are intentionally testing something that should be installable before it becomes default
+- [ ] You are comfortable with users installing it via `npx paperclipai@canary onboard`
+- [ ] You understand that each canary is a new immutable npm version such as `1.2.3-canary.1`
+
+### Before a stable
+
+- [ ] The candidate has already passed smoke testing
+- [ ] The changelog should be the stable version only, for example `v1.2.3`
+- [ ] You are ready to push the release commit and tag immediately after npm publish
+- [ ] You are ready to create the GitHub Release immediately after the push
+- [ ] You have a post-release website / announcement plan
+
+### After a stable
+
+- [ ] `npm view paperclipai@latest version` matches the new stable version
+- [ ] The git tag exists on GitHub
+- [ ] The GitHub Release exists and uses `releases/vX.Y.Z.md`
+- [ ] The website changelog is updated
+- [ ] Any announcement copy matches the shipped release, not the canary
+
+## Verification Gate
+
+The repository standard is:
+
+```bash
+pnpm -r typecheck
+pnpm test:run
+pnpm build
+```
+
+This matches [`.github/workflows/pr-verify.yml`](../.github/workflows/pr-verify.yml). Run it before claiming a release candidate is ready.
+
+The release workflow at [`.github/workflows/release.yml`](../.github/workflows/release.yml) installs with `pnpm install --frozen-lockfile`. That is intentional. Releases must use the exact dependency graph already committed on `master`; if manifests changed and the CI-owned lockfile refresh has not landed yet, the release should fail until that prerequisite is merged.
+
+For release work, prefer:
+
+```bash
+./scripts/release-preflight.sh canary <patch|minor|major>
+./scripts/release-preflight.sh stable <patch|minor|major>
+```
+
+That script runs the verification gate and prints the computed target versions before you publish anything.
+
+## Versioning Policy
+
+### Stable versions
+
+Stable releases use normal semver:
+
+- `patch` for bug fixes
+- `minor` for additive features, endpoints, and additive migrations
+- `major` for destructive migrations, removed APIs, or other breaking behavior
+
+### Canary versions
+
+Canaries are semver prereleases of the **intended stable version**:
+
+- `1.2.3-canary.0`
+- `1.2.3-canary.1`
+- `1.2.3-canary.2`
+
+That gives you three useful properties:
+
+1. Users can install the prerelease explicitly with `@canary`
+2. `latest` stays safe
+3. The stable changelog can remain just `v1.2.3`
+
+We do **not** create separate changelog files for canary versions.
+
+Concrete example:
+
+- if the latest stable release is `0.2.7`, a patch canary is `0.2.8-canary.0`
+- `0.2.7-canary.0` is invalid, because `0.2.7` is already the shipped stable version
+
+## Changelog Policy
+
+The maintainer changelog source of truth is:
 
 - `releases/vX.Y.Z.md`
 
@@ -146,13 +268,14 @@ Recommended structure:
 - `Improvements`
 - `Fixes`
 - `Upgrade Guide` when needed
-- `Contributors` — @-mention every contributor by GitHub username (no emails)
 
 Package-level `CHANGELOG.md` files are generated as part of the release mechanics. They are not the main release narrative.
 
-### 3. Run release preflight
+## Detailed Workflow
 
-From the `release/X.Y.Z` worktree:
+### 1. Decide the bump
+
+Run preflight first:
 
 ```bash
 ./scripts/release-preflight.sh canary <patch|minor|major>
@@ -160,54 +283,70 @@ From the `release/X.Y.Z` worktree:
 ./scripts/release-preflight.sh stable <patch|minor|major>
 ```
 
-The preflight script now checks all of the following before it runs the verification gate:
+That command:
 
-- the worktree is clean, including untracked files
-- the current branch matches the computed `release/X.Y.Z`
-- the release train is not frozen
-- the target version is still free on npm
-- the target tag does not already exist locally or remotely
-- whether the remote release branch already exists
-- whether `releases/vX.Y.Z.md` is present
+- verifies the worktree is clean, including untracked files
+- shows the last stable tag and computed next versions
+- shows the commit range since the last stable tag
+- highlights migration and breaking-change signals
+- runs `pnpm -r typecheck`, `pnpm test:run`, and `pnpm build`
 
-Then it runs:
+If you want the raw inputs separately, review the range since the last stable tag:
 
 ```bash
-pnpm -r typecheck
-pnpm test:run
-pnpm build
+LAST_TAG=$(git tag --list 'v*' --sort=-version:refname | head -1)
+git log "${LAST_TAG}..HEAD" --oneline --no-merges
+git diff --name-only "${LAST_TAG}..HEAD" -- packages/db/src/migrations/
+git diff "${LAST_TAG}..HEAD" -- packages/db/src/schema/
+git log "${LAST_TAG}..HEAD" --format="%s" | grep -E 'BREAKING CHANGE|BREAKING:|^[a-z]+!:' || true
 ```
 
-### 4. Publish one or more canaries
+Use the higher bump if there is any doubt.
+
+### 2. Write the stable changelog first
+
+Create or update:
+
+```bash
+VERSION=X.Y.Z
+claude -p "Use the release-changelog skill to draft or update releases/v${VERSION}.md for Paperclip. Read doc/RELEASING.md and skills/release-changelog/SKILL.md, then generate the stable changelog for v${VERSION} from commits since the last stable tag. Do not create a canary changelog."
+```
+
+This is deliberate. The release notes should describe the stable story, not the canary mechanics.
+
+### 3. Publish one or more canaries
 
 Run:
 
 ```bash
-./scripts/release.sh <patch|minor|major> --canary --dry-run
 ./scripts/release.sh <patch|minor|major> --canary
 ```
 
-Result:
+What the script does:
 
-- npm gets a prerelease such as `1.2.3-canary.0` under dist-tag `canary`
-- `latest` is unchanged
-- no git tag is created
-- no GitHub Release is created
-- the worktree returns to clean after the script finishes
+1. Verifies the working tree is clean
+2. Computes the intended stable version from the last stable tag
+3. Computes the next canary ordinal from npm
+4. Versions the public packages to `X.Y.Z-canary.N`
+5. Builds the workspace and publishable CLI
+6. Publishes to npm under dist-tag `canary`
+7. Cleans up the temporary versioning state so your branch returns to clean
 
-Guardrails:
+This means the script is safe to repeat as many times as needed while iterating:
 
-- the script refuses to run from the wrong branch
-- the script refuses to publish from a frozen train
-- the canary is always derived from the next stable version
-- if the stable notes file is missing, the script warns before you forget it
+- `1.2.3-canary.0`
+- `1.2.3-canary.1`
+- `1.2.3-canary.2`
 
-Concrete example:
+The target stable release can still remain `1.2.3`.
 
-- if the latest stable is `0.2.7`, a patch canary targets `0.2.8-canary.0`
-- `0.2.7-canary.N` is invalid because `0.2.7` is already stable
+Guardrail:
 
-### 5. Smoke test the canary
+- the canary is always derived from the **next stable version**
+- after stable `0.2.7`, the next patch canary is `0.2.8-canary.0`
+- the scripts refuse to publish `0.2.7-canary.N` once `0.2.7` is already the stable release
+
+### 4. Smoke test the canary
 
 Run the actual install path in Docker:
 
@@ -222,198 +361,165 @@ HOST_PORT=3232 DATA_DIR=./data/release-smoke-canary PAPERCLIPAI_VERSION=canary .
 HOST_PORT=3233 DATA_DIR=./data/release-smoke-stable PAPERCLIPAI_VERSION=latest ./scripts/docker-onboard-smoke.sh
 ```
 
-If you want to exercise onboarding from the current committed ref instead of npm, use:
+If you want to smoke onboarding from the current codebase rather than npm, run:
 
 ```bash
+./scripts/clean-onboard-git.sh
 ./scripts/clean-onboard-ref.sh
-PAPERCLIP_PORT=3234 ./scripts/clean-onboard-ref.sh
-./scripts/clean-onboard-ref.sh HEAD
 ```
 
 Minimum checks:
 
-- `npx paperclipai@canary onboard` installs
-- onboarding completes without crashes
-- the server boots
-- the UI loads
-- basic company creation and dashboard load work
+- [ ] `npx paperclipai@canary onboard` installs
+- [ ] onboarding completes without crashes
+- [ ] the server boots
+- [ ] the UI loads
+- [ ] basic company creation and dashboard load work
 
-If smoke testing fails:
+### 5. Publish stable from the vetted commit
 
-1. stop the stable release
-2. fix the issue on the same `release/X.Y.Z` branch
-3. publish another canary
-4. rerun smoke testing
-
-### 6. Publish stable from the same release branch
-
-Once the branch head is vetted, run:
+Once the candidate SHA is good, run the stable flow on that exact commit:
 
 ```bash
-./scripts/release.sh <patch|minor|major> --dry-run
 ./scripts/release.sh <patch|minor|major>
 ```
 
-Stable publish:
+What the script does:
 
-- publishes `X.Y.Z` to npm under `latest`
-- creates the local release commit
-- creates the local tag `vX.Y.Z`
+1. Verifies the working tree is clean
+2. Versions the public packages to the stable semver
+3. Builds the workspace and CLI publish bundle
+4. Publishes to npm under `latest`
+5. Restores temporary publish artifacts
+6. Creates the local release commit and git tag
 
-Stable publish refuses to proceed if:
+What it does **not** do:
 
-- the current branch is not `release/X.Y.Z`
-- the remote release branch does not exist yet
-- the stable notes file is missing
-- the target tag already exists locally or remotely
-- the stable version already exists on npm
+- it does not push for you
+- it does not update the website
+- it does not announce the release for you
 
-Those checks intentionally freeze the train after stable publish.
+### 6. Push the release and create the GitHub Release
 
-### 7. Push the stable branch commit and tag
-
-After stable publish succeeds:
+After a stable publish succeeds:
 
 ```bash
-git push public-gh HEAD --follow-tags
+git push public-gh HEAD:master --follow-tags
 ./scripts/create-github-release.sh X.Y.Z
 ```
 
-The GitHub Release notes come from:
+The GitHub release notes come from:
 
 - `releases/vX.Y.Z.md`
 
-### 8. Merge the release branch back to `master`
-
-Open a PR:
-
-- base: `master`
-- head: `release/X.Y.Z`
-
-Merge rule:
-
-- allowed: merge commit or fast-forward
-- forbidden: squash merge
-- forbidden: rebase merge
-
-Post-merge verification:
-
-```bash
-git fetch public-gh --tags
-git merge-base --is-ancestor "vX.Y.Z" "public-gh/master"
-```
-
-That command must succeed. If it fails, the published tagged commit is not reachable from `master`, which means the merge strategy was wrong.
-
-### 9. Finish the external surfaces
+### 7. Complete the external surfaces
 
 After GitHub is correct:
 
 - publish the changelog on the website
-- write and send the announcement copy
+- write the announcement copy
 - ensure public docs and install guidance point to the stable version
 
-## GitHub Actions Release
+## GitHub Actions and npm Trusted Publishing
 
-There is also a manual workflow at [`.github/workflows/release.yml`](../.github/workflows/release.yml).
+If you want GitHub to own the actual npm publish, use [`.github/workflows/release.yml`](../.github/workflows/release.yml) together with npm trusted publishing.
 
-Use it from the Actions tab on the relevant `release/X.Y.Z` branch:
+Recommended setup:
 
-1. Choose `Release`
-2. Choose `channel`: `canary` or `stable`
-3. Choose `bump`: `patch`, `minor`, or `major`
-4. Choose whether this is a `dry_run`
-5. Run it from the release branch, not from `master`
+1. Configure the GitHub Actions workflow as a trusted publisher for **every public package** on npm
+2. Use the `npm-release` GitHub environment with required reviewers
+3. Run stable publishes from `master` only
+4. Keep the workflow manual via `workflow_dispatch`
 
-The workflow:
+Why this is the right shape:
 
-- reruns `typecheck`, `test:run`, and `build`
-- gates publish behind the `npm-release` environment
-- can publish canaries without touching `latest`
-- can publish stable, push the stable branch commit and tag, and create the GitHub Release
-
-It does not merge the release branch back to `master` for you.
-
-## Release Checklist
-
-### Before any publish
-
-- [ ] The release train exists on `release/X.Y.Z`
-- [ ] The working tree is clean, including untracked files
-- [ ] If package manifests changed, the CI-owned `pnpm-lock.yaml` refresh is already merged on `master` before the train is cut
-- [ ] The required verification gate passed on the exact branch head you want to publish
-- [ ] The bump type is correct for the user-visible impact
-- [ ] The stable changelog file exists or is ready at `releases/vX.Y.Z.md`
-- [ ] You know which previous stable version you would roll back to if needed
-
-### Before a stable
-
-- [ ] The candidate has already passed smoke testing
-- [ ] The remote `release/X.Y.Z` branch exists
-- [ ] You are ready to push the stable branch commit and tag immediately after npm publish
-- [ ] You are ready to create the GitHub Release immediately after the push
-- [ ] You are ready to open the PR back to `master`
-
-### After a stable
-
-- [ ] `npm view paperclipai@latest version` matches the new stable version
-- [ ] The git tag exists on GitHub
-- [ ] The GitHub Release exists and uses `releases/vX.Y.Z.md`
-- [ ] `vX.Y.Z` is reachable from `master`
-- [ ] The website changelog is updated
-- [ ] Announcement copy matches the stable release, not the canary
+- no long-lived npm token needs to live in GitHub secrets
+- reviewers can approve the publish step at the environment gate
+- the workflow reruns verification on the release SHA before publish
+- stable and canary use the same mechanics
 
 ## Failure Playbooks
 
+### If the canary fails before publish
+
+Nothing shipped. Fix the code and rerun the canary workflow.
+
 ### If the canary publishes but the smoke test fails
 
-Do not publish stable.
+Do **not** publish stable.
 
 Instead:
 
-1. fix the issue on `release/X.Y.Z`
-2. publish another canary
-3. rerun smoke testing
+1. Fix the issue
+2. Publish another canary
+3. Re-run smoke testing
 
-### If stable npm publish succeeds but push or GitHub release creation fails
+The canary version number will increase, but the stable target version can remain the same.
+
+### If the stable npm publish succeeds but push fails
 
 This is a partial release. npm is already live.
 
 Do this immediately:
 
-1. fix the git or GitHub issue from the same checkout
-2. push the stable branch commit and tag
-3. create the GitHub Release
+1. Fix the git issue
+2. Push the release commit and tag from the same checkout
+3. Create the GitHub Release
 
-Do not republish the same version.
+Do **not** publish the same version again.
 
-### If `latest` is broken after stable publish
+### If the stable release is bad after `latest` moves
 
-Preview:
+Use the rollback script first:
 
 ```bash
-./scripts/rollback-latest.sh X.Y.Z --dry-run
+./scripts/rollback-latest.sh <last-good-version>
 ```
 
-Roll back:
+Then:
 
-```bash
-./scripts/rollback-latest.sh X.Y.Z
-```
+1. open an incident note or maintainer comment
+2. fix forward on a new patch release
+3. update the changelog / release notes if the user-facing guidance changed
 
-This does not unpublish anything. It only moves the `latest` dist-tag back to the last good stable release.
+### If the GitHub Release is wrong
 
-Then fix forward with a new patch release.
-
-### If the GitHub Release notes are wrong
-
-Re-run:
+Edit it by re-running:
 
 ```bash
 ./scripts/create-github-release.sh X.Y.Z
 ```
 
-If the release already exists, the script updates it.
+This updates the release notes if the GitHub Release already exists.
+
+### If the website changelog is wrong
+
+Fix the website independently. Do not republish npm just to repair the website surface.
+
+## Rollback Strategy
+
+The default rollback strategy is **dist-tag rollback, then fix forward**.
+
+Why:
+
+- npm versions are immutable
+- users need `npx paperclipai onboard` to recover quickly
+- moving `latest` back is faster and safer than trying to delete history
+
+Rollback procedure:
+
+1. identify the last known good stable version
+2. run `./scripts/rollback-latest.sh <version>`
+3. verify `npm view paperclipai@latest version`
+4. fix forward with a new stable release
+
+## Scripts Reference
+
+- [`scripts/release.sh`](../scripts/release.sh) — stable and canary npm publish flow
+- [`scripts/release-preflight.sh`](../scripts/release-preflight.sh) — clean-tree, version-plan, and verification-gate preflight
+- [`scripts/create-github-release.sh`](../scripts/create-github-release.sh) — create or update the GitHub Release after push
+- [`scripts/rollback-latest.sh`](../scripts/rollback-latest.sh) — repoint `latest` to the last good stable release
+- [`scripts/docker-onboard-smoke.sh`](../scripts/docker-onboard-smoke.sh) — Docker smoke test for the installed CLI
 
 ## Related Docs
 

package.json

@@ -4,7 +4,7 @@
   "type": "module",
   "scripts": {
     "dev": "node scripts/dev-runner.mjs watch",
-    "dev:watch": "cross-env PAPERCLIP_MIGRATION_PROMPT=never node scripts/dev-runner.mjs watch",
+    "dev:watch": "PAPERCLIP_MIGRATION_PROMPT=never node scripts/dev-runner.mjs watch",
     "dev:once": "node scripts/dev-runner.mjs dev",
     "dev:server": "pnpm --filter @paperclipai/server dev",
     "dev:ui": "pnpm --filter @paperclipai/ui dev",
@@ -18,7 +18,6 @@
     "db:backup": "./scripts/backup-db.sh",
     "paperclipai": "node cli/node_modules/tsx/dist/cli.mjs cli/src/index.ts",
     "build:npm": "./scripts/build-npm.sh",
-    "release:start": "./scripts/release-start.sh",
     "release": "./scripts/release.sh",
     "release:preflight": "./scripts/release-preflight.sh",
     "release:github": "./scripts/create-github-release.sh",
@@ -35,7 +34,6 @@
   },
   "devDependencies": {
     "@changesets/cli": "^2.30.0",
-    "cross-env": "^10.1.0",
     "@playwright/test": "^1.58.2",
     "esbuild": "^0.27.3",
     "typescript": "^5.7.3",

packages/adapter-utils/CHANGELOG.md

@@ -1,11 +1,5 @@
 # @paperclipai/adapter-utils
 
-## 0.3.0
-
-### Minor Changes
-
-- Stable release preparation for 0.3.0
-
 ## 0.2.7
 
 ### Patch Changes

packages/adapter-utils/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paperclipai/adapter-utils",
-  "version": "0.3.0",
+  "version": "0.2.7",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",

packages/adapter-utils/src/index.ts

@@ -3,6 +3,7 @@ export type {
   AdapterRuntime,
   UsageSummary,
   AdapterBillingType,
+  AdapterRuntimeServiceReport,
   AdapterExecutionResult,
   AdapterInvocationMeta,
   AdapterExecutionContext,

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

@@ -15,11 +15,6 @@ interface RunningProcess {
   graceSec: number;
 }
 
-interface SpawnTarget {
-  command: string;
-  args: string[];
-}
-
 type ChildProcessWithEvents = ChildProcess & {
   on(event: "error", listener: (err: Error) => void): ChildProcess;
   on(
@@ -130,78 +125,6 @@ export function defaultPathForPlatform() {
   return "/usr/local/bin:/opt/homebrew/bin:/usr/local/sbin:/usr/bin:/bin:/usr/sbin:/sbin";
 }
 
-function windowsPathExts(env: NodeJS.ProcessEnv): string[] {
-  return (env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";").filter(Boolean);
-}
-
-async function pathExists(candidate: string) {
-  try {
-    await fs.access(candidate, process.platform === "win32" ? fsConstants.F_OK : fsConstants.X_OK);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-async function resolveCommandPath(command: string, cwd: string, env: NodeJS.ProcessEnv): Promise<string | null> {
-  const hasPathSeparator = command.includes("/") || command.includes("\\");
-  if (hasPathSeparator) {
-    const absolute = path.isAbsolute(command) ? command : path.resolve(cwd, command);
-    return (await pathExists(absolute)) ? absolute : null;
-  }
-
-  const pathValue = env.PATH ?? env.Path ?? "";
-  const delimiter = process.platform === "win32" ? ";" : ":";
-  const dirs = pathValue.split(delimiter).filter(Boolean);
-  const exts = process.platform === "win32" ? windowsPathExts(env) : [""];
-  const hasExtension = process.platform === "win32" && path.extname(command).length > 0;
-
-  for (const dir of dirs) {
-    const candidates =
-      process.platform === "win32"
-        ? hasExtension
-          ? [path.join(dir, command)]
-          : exts.map((ext) => path.join(dir, `${command}${ext}`))
-        : [path.join(dir, command)];
-    for (const candidate of candidates) {
-      if (await pathExists(candidate)) return candidate;
-    }
-  }
-
-  return null;
-}
-
-function quoteForCmd(arg: string) {
-  if (!arg.length) return '""';
-  const escaped = arg.replace(/"/g, '""');
-  return /[\s"&<>|^()]/.test(escaped) ? `"${escaped}"` : escaped;
-}
-
-async function resolveSpawnTarget(
-  command: string,
-  args: string[],
-  cwd: string,
-  env: NodeJS.ProcessEnv,
-): Promise<SpawnTarget> {
-  const resolved = await resolveCommandPath(command, cwd, env);
-  const executable = resolved ?? command;
-
-  if (process.platform !== "win32") {
-    return { command: executable, args };
-  }
-
-  if (/\.(cmd|bat)$/i.test(executable)) {
-    const shell = env.ComSpec || process.env.ComSpec || "cmd.exe";
-    const commandLine = [quoteForCmd(executable), ...args.map(quoteForCmd)].join(" ");
-    return {
-      command: shell,
-      args: ["/d", "/s", "/c", commandLine],
-    };
-  }
-
-  return { command: executable, args };
-}
-
 export function ensurePathInEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
   if (typeof env.PATH === "string" && env.PATH.length > 0) return env;
   if (typeof env.Path === "string" && env.Path.length > 0) return env;
@@ -246,12 +169,36 @@ export async function ensureAbsoluteDirectory(
 }
 
 export async function ensureCommandResolvable(command: string, cwd: string, env: NodeJS.ProcessEnv) {
-  const resolved = await resolveCommandPath(command, cwd, env);
-  if (resolved) return;
-  if (command.includes("/") || command.includes("\\")) {
+  const hasPathSeparator = command.includes("/") || command.includes("\\");
+  if (hasPathSeparator) {
     const absolute = path.isAbsolute(command) ? command : path.resolve(cwd, command);
-    throw new Error(`Command is not executable: "${command}" (resolved: "${absolute}")`);
+    try {
+      await fs.access(absolute, fsConstants.X_OK);
+    } catch {
+      throw new Error(`Command is not executable: "${command}" (resolved: "${absolute}")`);
+    }
+    return;
   }
+
+  const pathValue = env.PATH ?? env.Path ?? "";
+  const delimiter = process.platform === "win32" ? ";" : ":";
+  const dirs = pathValue.split(delimiter).filter(Boolean);
+  const windowsExt = process.platform === "win32"
+    ? (env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";")
+    : [""];
+
+  for (const dir of dirs) {
+    for (const ext of windowsExt) {
+      const candidate = path.join(dir, process.platform === "win32" ? `${command}${ext}` : command);
+      try {
+        await fs.access(candidate, fsConstants.X_OK);
+        return;
+      } catch {
+        // continue scanning PATH
+      }
+    }
+  }
+
   throw new Error(`Command not found in PATH: "${command}"`);
 }
 
@@ -272,100 +219,79 @@ export async function runChildProcess(
   const onLogError = opts.onLogError ?? ((err, id, msg) => console.warn({ err, runId: id }, msg));
 
   return new Promise<RunProcessResult>((resolve, reject) => {
-    const rawMerged: NodeJS.ProcessEnv = { ...process.env, ...opts.env };
+    const mergedEnv = ensurePathInEnv({ ...process.env, ...opts.env });
+    const child = spawn(command, args, {
+      cwd: opts.cwd,
+      env: mergedEnv,
+      shell: false,
+      stdio: [opts.stdin != null ? "pipe" : "ignore", "pipe", "pipe"],
+    }) as ChildProcessWithEvents;
 
-    // Strip Claude Code nesting-guard env vars so spawned `claude` processes
-    // don't refuse to start with "cannot be launched inside another session".
-    // These vars leak in when the Paperclip server itself is started from
-    // within a Claude Code session (e.g. `npx paperclipai run` in a terminal
-    // owned by Claude Code) or when cron inherits a contaminated shell env.
-    const CLAUDE_CODE_NESTING_VARS = [
-      "CLAUDECODE",
-      "CLAUDE_CODE_ENTRYPOINT",
-      "CLAUDE_CODE_SESSION",
-      "CLAUDE_CODE_PARENT_SESSION",
-    ] as const;
-    for (const key of CLAUDE_CODE_NESTING_VARS) {
-      delete rawMerged[key];
+    if (opts.stdin != null && child.stdin) {
+      child.stdin.write(opts.stdin);
+      child.stdin.end();
     }
 
-    const mergedEnv = ensurePathInEnv(rawMerged);
-    void resolveSpawnTarget(command, args, opts.cwd, mergedEnv)
-      .then((target) => {
-        const child = spawn(target.command, target.args, {
-          cwd: opts.cwd,
-          env: mergedEnv,
-          shell: false,
-          stdio: [opts.stdin != null ? "pipe" : "ignore", "pipe", "pipe"],
-        }) as ChildProcessWithEvents;
+    runningProcesses.set(runId, { child, graceSec: opts.graceSec });
 
-        if (opts.stdin != null && child.stdin) {
-          child.stdin.write(opts.stdin);
-          child.stdin.end();
-        }
+    let timedOut = false;
+    let stdout = "";
+    let stderr = "";
+    let logChain: Promise<void> = Promise.resolve();
 
-        runningProcesses.set(runId, { child, graceSec: opts.graceSec });
+    const timeout =
+      opts.timeoutSec > 0
+        ? setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGTERM");
+            setTimeout(() => {
+              if (!child.killed) {
+                child.kill("SIGKILL");
+              }
+            }, Math.max(1, opts.graceSec) * 1000);
+          }, opts.timeoutSec * 1000)
+        : null;
 
-        let timedOut = false;
-        let stdout = "";
-        let stderr = "";
-        let logChain: Promise<void> = Promise.resolve();
+    child.stdout?.on("data", (chunk: unknown) => {
+      const text = String(chunk);
+      stdout = appendWithCap(stdout, text);
+      logChain = logChain
+        .then(() => opts.onLog("stdout", text))
+        .catch((err) => onLogError(err, runId, "failed to append stdout log chunk"));
+    });
 
-        const timeout =
-          opts.timeoutSec > 0
-            ? setTimeout(() => {
-                timedOut = true;
-                child.kill("SIGTERM");
-                setTimeout(() => {
-                  if (!child.killed) {
-                    child.kill("SIGKILL");
-                  }
-                }, Math.max(1, opts.graceSec) * 1000);
-              }, opts.timeoutSec * 1000)
-            : null;
+    child.stderr?.on("data", (chunk: unknown) => {
+      const text = String(chunk);
+      stderr = appendWithCap(stderr, text);
+      logChain = logChain
+        .then(() => opts.onLog("stderr", text))
+        .catch((err) => onLogError(err, runId, "failed to append stderr log chunk"));
+    });
 
-        child.stdout?.on("data", (chunk: unknown) => {
-          const text = String(chunk);
-          stdout = appendWithCap(stdout, text);
-          logChain = logChain
-            .then(() => opts.onLog("stdout", text))
-            .catch((err) => onLogError(err, runId, "failed to append stdout log chunk"));
+    child.on("error", (err: Error) => {
+      if (timeout) clearTimeout(timeout);
+      runningProcesses.delete(runId);
+      const errno = (err as NodeJS.ErrnoException).code;
+      const pathValue = mergedEnv.PATH ?? mergedEnv.Path ?? "";
+      const msg =
+        errno === "ENOENT"
+          ? `Failed to start command "${command}" in "${opts.cwd}". Verify adapter command, working directory, and PATH (${pathValue}).`
+          : `Failed to start command "${command}" in "${opts.cwd}": ${err.message}`;
+      reject(new Error(msg));
+    });
+
+    child.on("close", (code: number | null, signal: NodeJS.Signals | null) => {
+      if (timeout) clearTimeout(timeout);
+      runningProcesses.delete(runId);
+      void logChain.finally(() => {
+        resolve({
+          exitCode: code,
+          signal,
+          timedOut,
+          stdout,
+          stderr,
         });
-
-        child.stderr?.on("data", (chunk: unknown) => {
-          const text = String(chunk);
-          stderr = appendWithCap(stderr, text);
-          logChain = logChain
-            .then(() => opts.onLog("stderr", text))
-            .catch((err) => onLogError(err, runId, "failed to append stderr log chunk"));
-        });
-
-        child.on("error", (err: Error) => {
-          if (timeout) clearTimeout(timeout);
-          runningProcesses.delete(runId);
-          const errno = (err as NodeJS.ErrnoException).code;
-          const pathValue = mergedEnv.PATH ?? mergedEnv.Path ?? "";
-          const msg =
-            errno === "ENOENT"
-              ? `Failed to start command "${command}" in "${opts.cwd}". Verify adapter command, working directory, and PATH (${pathValue}).`
-              : `Failed to start command "${command}" in "${opts.cwd}": ${err.message}`;
-          reject(new Error(msg));
-        });
-
-        child.on("close", (code: number | null, signal: NodeJS.Signals | null) => {
-          if (timeout) clearTimeout(timeout);
-          runningProcesses.delete(runId);
-          void logChain.finally(() => {
-            resolve({
-              exitCode: code,
-              signal,
-              timedOut,
-              stdout,
-              stderr,
-            });
-          });
-        });
-      })
-      .catch(reject);
+      });
+    });
   });
 }

packages/adapter-utils/src/types.ts

@@ -32,6 +32,27 @@ export interface UsageSummary {
 
 export type AdapterBillingType = "api" | "subscription" | "unknown";
 
+export interface AdapterRuntimeServiceReport {
+  id?: string | null;
+  projectId?: string | null;
+  projectWorkspaceId?: string | null;
+  issueId?: string | null;
+  scopeType?: "project_workspace" | "execution_workspace" | "run" | "agent";
+  scopeId?: string | null;
+  serviceName: string;
+  status?: "starting" | "running" | "stopped" | "failed";
+  lifecycle?: "shared" | "ephemeral";
+  reuseKey?: string | null;
+  command?: string | null;
+  cwd?: string | null;
+  port?: number | null;
+  url?: string | null;
+  providerRef?: string | null;
+  ownerAgentId?: string | null;
+  stopPolicy?: Record<string, unknown> | null;
+  healthStatus?: "unknown" | "healthy" | "unhealthy";
+}
+
 export interface AdapterExecutionResult {
   exitCode: number | null;
   signal: string | null;
@@ -51,6 +72,7 @@ export interface AdapterExecutionResult {
   billingType?: AdapterBillingType | null;
   costUsd?: number | null;
   resultJson?: Record<string, unknown> | null;
+  runtimeServices?: AdapterRuntimeServiceReport[];
   summary?: string | null;
   clearSession?: boolean;
 }
@@ -208,6 +230,12 @@ export interface CreateConfigValues {
   envBindings: Record<string, unknown>;
   url: string;
   bootstrapPrompt: string;
+  payloadTemplateJson?: string;
+  workspaceStrategyType?: string;
+  workspaceBaseRef?: string;
+  workspaceBranchTemplate?: string;
+  worktreeParentDir?: string;
+  runtimeServicesJson?: string;
   maxTurnsPerRun: number;
   heartbeatEnabled: boolean;
   intervalSec: number;

packages/adapter-utils/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "../../tsconfig.base.json",
+  "extends": "../../tsconfig.json",
   "compilerOptions": {
     "outDir": "dist",
     "rootDir": "src"

packages/adapters/claude-local/CHANGELOG.md

@@ -1,16 +1,5 @@
 # @paperclipai/adapter-claude-local
 
-## 0.3.0
-
-### Minor Changes
-
-- Stable release preparation for 0.3.0
-
-### Patch Changes
-
-- Updated dependencies
-  - @paperclipai/adapter-utils@0.3.0
-
 ## 0.2.7
 
 ### Patch Changes

packages/adapters/claude-local/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paperclipai/adapter-claude-local",
-  "version": "0.3.0",
+  "version": "0.2.7",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",

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

@@ -25,8 +25,13 @@ Core fields:
 - command (string, optional): defaults to "claude"
 - extraArgs (string[], optional): additional CLI args
 - env (object, optional): KEY=VALUE environment variables
+- workspaceStrategy (object, optional): execution workspace strategy; currently supports { type: "git_worktree", baseRef?, branchTemplate?, worktreeParentDir? }
+- workspaceRuntime (object, optional): workspace runtime service intents; local host-managed services are realized before Claude starts and exposed back via context/env
 
 Operational fields:
 - timeoutSec (number, optional): run timeout in seconds
 - graceSec (number, optional): SIGTERM grace period in seconds
+
+Notes:
+- When Paperclip realizes a workspace/runtime for a run, it injects PAPERCLIP_WORKSPACE_* and PAPERCLIP_RUNTIME_* env vars for agent-side tooling.
 `;

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

@@ -115,14 +115,28 @@ async function buildClaudeRuntimeConfig(input: ClaudeExecutionInput): Promise<Cl
   const workspaceContext = parseObject(context.paperclipWorkspace);
   const workspaceCwd = asString(workspaceContext.cwd, "");
   const workspaceSource = asString(workspaceContext.source, "");
+  const workspaceStrategy = asString(workspaceContext.strategy, "");
   const workspaceId = asString(workspaceContext.workspaceId, "") || null;
   const workspaceRepoUrl = asString(workspaceContext.repoUrl, "") || null;
   const workspaceRepoRef = asString(workspaceContext.repoRef, "") || null;
+  const workspaceBranch = asString(workspaceContext.branchName, "") || null;
+  const workspaceWorktreePath = asString(workspaceContext.worktreePath, "") || null;
   const workspaceHints = Array.isArray(context.paperclipWorkspaces)
     ? context.paperclipWorkspaces.filter(
         (value): value is Record<string, unknown> => typeof value === "object" && value !== null,
       )
     : [];
+  const runtimeServiceIntents = Array.isArray(context.paperclipRuntimeServiceIntents)
+    ? context.paperclipRuntimeServiceIntents.filter(
+        (value): value is Record<string, unknown> => typeof value === "object" && value !== null,
+      )
+    : [];
+  const runtimeServices = Array.isArray(context.paperclipRuntimeServices)
+    ? context.paperclipRuntimeServices.filter(
+        (value): value is Record<string, unknown> => typeof value === "object" && value !== null,
+      )
+    : [];
+  const runtimePrimaryUrl = asString(context.paperclipRuntimePrimaryUrl, "");
   const configuredCwd = asString(config.cwd, "");
   const useConfiguredInsteadOfAgentHome = workspaceSource === "agent_home" && configuredCwd.length > 0;
   const effectiveWorkspaceCwd = useConfiguredInsteadOfAgentHome ? "" : workspaceCwd;
@@ -183,6 +197,9 @@ async function buildClaudeRuntimeConfig(input: ClaudeExecutionInput): Promise<Cl
   if (workspaceSource) {
     env.PAPERCLIP_WORKSPACE_SOURCE = workspaceSource;
   }
+  if (workspaceStrategy) {
+    env.PAPERCLIP_WORKSPACE_STRATEGY = workspaceStrategy;
+  }
   if (workspaceId) {
     env.PAPERCLIP_WORKSPACE_ID = workspaceId;
   }
@@ -192,9 +209,24 @@ async function buildClaudeRuntimeConfig(input: ClaudeExecutionInput): Promise<Cl
   if (workspaceRepoRef) {
     env.PAPERCLIP_WORKSPACE_REPO_REF = workspaceRepoRef;
   }
+  if (workspaceBranch) {
+    env.PAPERCLIP_WORKSPACE_BRANCH = workspaceBranch;
+  }
+  if (workspaceWorktreePath) {
+    env.PAPERCLIP_WORKSPACE_WORKTREE_PATH = workspaceWorktreePath;
+  }
   if (workspaceHints.length > 0) {
     env.PAPERCLIP_WORKSPACES_JSON = JSON.stringify(workspaceHints);
   }
+  if (runtimeServiceIntents.length > 0) {
+    env.PAPERCLIP_RUNTIME_SERVICE_INTENTS_JSON = JSON.stringify(runtimeServiceIntents);
+  }
+  if (runtimeServices.length > 0) {
+    env.PAPERCLIP_RUNTIME_SERVICES_JSON = JSON.stringify(runtimeServices);
+  }
+  if (runtimePrimaryUrl) {
+    env.PAPERCLIP_RUNTIME_PRIMARY_URL = runtimePrimaryUrl;
+  }
 
   for (const [key, value] of Object.entries(envConfig)) {
     if (typeof value === "string") env[key] = value;

packages/adapters/claude-local/src/ui/build-config.ts

@@ -50,6 +50,18 @@ function parseEnvBindings(bindings: unknown): Record<string, unknown> {
   return env;
 }
 
+function parseJsonObject(text: string): Record<string, unknown> | null {
+  const trimmed = text.trim();
+  if (!trimmed) return null;
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+    return parsed as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
 export function buildClaudeLocalConfig(v: CreateConfigValues): Record<string, unknown> {
   const ac: Record<string, unknown> = {};
   if (v.cwd) ac.cwd = v.cwd;
@@ -70,6 +82,18 @@ export function buildClaudeLocalConfig(v: CreateConfigValues): Record<string, un
   if (Object.keys(env).length > 0) ac.env = env;
   ac.maxTurnsPerRun = v.maxTurnsPerRun;
   ac.dangerouslySkipPermissions = v.dangerouslySkipPermissions;
+  if (v.workspaceStrategyType === "git_worktree") {
+    ac.workspaceStrategy = {
+      type: "git_worktree",
+      ...(v.workspaceBaseRef ? { baseRef: v.workspaceBaseRef } : {}),
+      ...(v.workspaceBranchTemplate ? { branchTemplate: v.workspaceBranchTemplate } : {}),
+      ...(v.worktreeParentDir ? { worktreeParentDir: v.worktreeParentDir } : {}),
+    };
+  }
+  const runtimeServices = parseJsonObject(v.runtimeServicesJson ?? "");
+  if (runtimeServices && Array.isArray(runtimeServices.services)) {
+    ac.workspaceRuntime = runtimeServices;
+  }
   if (v.command) ac.command = v.command;
   if (v.extraArgs) ac.extraArgs = parseCommaArgs(v.extraArgs);
   return ac;

packages/adapters/claude-local/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "../../../tsconfig.base.json",
+  "extends": "../../../tsconfig.json",
   "compilerOptions": {
     "outDir": "dist",
     "rootDir": "src"

packages/adapters/codex-local/CHANGELOG.md

@@ -1,16 +1,5 @@
 # @paperclipai/adapter-codex-local
 
-## 0.3.0
-
-### Minor Changes
-
-- Stable release preparation for 0.3.0
-
-### Patch Changes
-
-- Updated dependencies
-  - @paperclipai/adapter-utils@0.3.0
-
 ## 0.2.7
 
 ### Patch Changes

packages/adapters/codex-local/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paperclipai/adapter-codex-local",
-  "version": "0.3.0",
+  "version": "0.2.7",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",

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

@@ -31,6 +31,8 @@ Core fields:
 - command (string, optional): defaults to "codex"
 - extraArgs (string[], optional): additional CLI args
 - env (object, optional): KEY=VALUE environment variables
+- workspaceStrategy (object, optional): execution workspace strategy; currently supports { type: "git_worktree", baseRef?, branchTemplate?, worktreeParentDir? }
+- workspaceRuntime (object, optional): workspace runtime service intents; local host-managed services are realized before Codex starts and exposed back via context/env
 
 Operational fields:
 - timeoutSec (number, optional): run timeout in seconds
@@ -40,4 +42,5 @@ Notes:
 - Prompts are piped via stdin (Codex receives "-" prompt argument).
 - Paperclip auto-injects local skills into Codex personal skills dir ("$CODEX_HOME/skills" or "~/.codex/skills") when missing, so Codex can discover "$paperclip" and related skills.
 - Some model/tool combinations reject certain effort levels (for example minimal with web search enabled).
+- When Paperclip realizes a workspace/runtime for a run, it injects PAPERCLIP_WORKSPACE_* and PAPERCLIP_RUNTIME_* env vars for agent-side tooling.
 `;

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

@@ -126,14 +126,28 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   const workspaceContext = parseObject(context.paperclipWorkspace);
   const workspaceCwd = asString(workspaceContext.cwd, "");
   const workspaceSource = asString(workspaceContext.source, "");
+  const workspaceStrategy = asString(workspaceContext.strategy, "");
   const workspaceId = asString(workspaceContext.workspaceId, "");
   const workspaceRepoUrl = asString(workspaceContext.repoUrl, "");
   const workspaceRepoRef = asString(workspaceContext.repoRef, "");
+  const workspaceBranch = asString(workspaceContext.branchName, "");
+  const workspaceWorktreePath = asString(workspaceContext.worktreePath, "");
   const workspaceHints = Array.isArray(context.paperclipWorkspaces)
     ? context.paperclipWorkspaces.filter(
         (value): value is Record<string, unknown> => typeof value === "object" && value !== null,
       )
     : [];
+  const runtimeServiceIntents = Array.isArray(context.paperclipRuntimeServiceIntents)
+    ? context.paperclipRuntimeServiceIntents.filter(
+        (value): value is Record<string, unknown> => typeof value === "object" && value !== null,
+      )
+    : [];
+  const runtimeServices = Array.isArray(context.paperclipRuntimeServices)
+    ? context.paperclipRuntimeServices.filter(
+        (value): value is Record<string, unknown> => typeof value === "object" && value !== null,
+      )
+    : [];
+  const runtimePrimaryUrl = asString(context.paperclipRuntimePrimaryUrl, "");
   const configuredCwd = asString(config.cwd, "");
   const useConfiguredInsteadOfAgentHome = workspaceSource === "agent_home" && configuredCwd.length > 0;
   const effectiveWorkspaceCwd = useConfiguredInsteadOfAgentHome ? "" : workspaceCwd;
@@ -192,6 +206,9 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   if (workspaceSource) {
     env.PAPERCLIP_WORKSPACE_SOURCE = workspaceSource;
   }
+  if (workspaceStrategy) {
+    env.PAPERCLIP_WORKSPACE_STRATEGY = workspaceStrategy;
+  }
   if (workspaceId) {
     env.PAPERCLIP_WORKSPACE_ID = workspaceId;
   }
@@ -201,9 +218,24 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   if (workspaceRepoRef) {
     env.PAPERCLIP_WORKSPACE_REPO_REF = workspaceRepoRef;
   }
+  if (workspaceBranch) {
+    env.PAPERCLIP_WORKSPACE_BRANCH = workspaceBranch;
+  }
+  if (workspaceWorktreePath) {
+    env.PAPERCLIP_WORKSPACE_WORKTREE_PATH = workspaceWorktreePath;
+  }
   if (workspaceHints.length > 0) {
     env.PAPERCLIP_WORKSPACES_JSON = JSON.stringify(workspaceHints);
   }
+  if (runtimeServiceIntents.length > 0) {
+    env.PAPERCLIP_RUNTIME_SERVICE_INTENTS_JSON = JSON.stringify(runtimeServiceIntents);
+  }
+  if (runtimeServices.length > 0) {
+    env.PAPERCLIP_RUNTIME_SERVICES_JSON = JSON.stringify(runtimeServices);
+  }
+  if (runtimePrimaryUrl) {
+    env.PAPERCLIP_RUNTIME_PRIMARY_URL = runtimePrimaryUrl;
+  }
   for (const [k, v] of Object.entries(envConfig)) {
     if (typeof v === "string") env[k] = v;
   }

packages/adapters/codex-local/src/ui/build-config.ts

@@ -54,6 +54,18 @@ function parseEnvBindings(bindings: unknown): Record<string, unknown> {
   return env;
 }
 
+function parseJsonObject(text: string): Record<string, unknown> | null {
+  const trimmed = text.trim();
+  if (!trimmed) return null;
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+    return parsed as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
 export function buildCodexLocalConfig(v: CreateConfigValues): Record<string, unknown> {
   const ac: Record<string, unknown> = {};
   if (v.cwd) ac.cwd = v.cwd;
@@ -76,6 +88,18 @@ export function buildCodexLocalConfig(v: CreateConfigValues): Record<string, unk
     typeof v.dangerouslyBypassSandbox === "boolean"
       ? v.dangerouslyBypassSandbox
       : DEFAULT_CODEX_LOCAL_BYPASS_APPROVALS_AND_SANDBOX;
+  if (v.workspaceStrategyType === "git_worktree") {
+    ac.workspaceStrategy = {
+      type: "git_worktree",
+      ...(v.workspaceBaseRef ? { baseRef: v.workspaceBaseRef } : {}),
+      ...(v.workspaceBranchTemplate ? { branchTemplate: v.workspaceBranchTemplate } : {}),
+      ...(v.worktreeParentDir ? { worktreeParentDir: v.worktreeParentDir } : {}),
+    };
+  }
+  const runtimeServices = parseJsonObject(v.runtimeServicesJson ?? "");
+  if (runtimeServices && Array.isArray(runtimeServices.services)) {
+    ac.workspaceRuntime = runtimeServices;
+  }
   if (v.command) ac.command = v.command;
   if (v.extraArgs) ac.extraArgs = parseCommaArgs(v.extraArgs);
   return ac;

packages/adapters/codex-local/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "../../../tsconfig.base.json",
+  "extends": "../../../tsconfig.json",
   "compilerOptions": {
     "outDir": "dist",
     "rootDir": "src"

packages/adapters/cursor-local/CHANGELOG.md

@@ -1,16 +1,5 @@
 # @paperclipai/adapter-cursor-local
 
-## 0.3.0
-
-### Minor Changes
-
-- Stable release preparation for 0.3.0
-
-### Patch Changes
-
-- Updated dependencies
-  - @paperclipai/adapter-utils@0.3.0
-
 ## 0.2.7
 
 ### Patch Changes

packages/adapters/cursor-local/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paperclipai/adapter-cursor-local",
-  "version": "0.3.0",
+  "version": "0.2.7",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",

packages/adapters/cursor-local/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "../../../tsconfig.base.json",
+  "extends": "../../../tsconfig.json",
   "compilerOptions": {
     "outDir": "dist",
     "rootDir": "src",

packages/adapters/openclaw-gateway/CHANGELOG.md

@@ -1,12 +0,0 @@
-# @paperclipai/adapter-openclaw-gateway
-
-## 0.3.0
-
-### Minor Changes
-
-- Stable release preparation for 0.3.0
-
-### Patch Changes
-
-- Updated dependencies
-  - @paperclipai/adapter-utils@0.3.0

packages/adapters/openclaw-gateway/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paperclipai/adapter-openclaw-gateway",
-  "version": "0.3.0",
+  "version": "0.2.7",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",

packages/adapters/openclaw-gateway/src/index.ts

@@ -31,6 +31,7 @@ Gateway connect identity fields:
 
 Request behavior fields:
 - payloadTemplate (object, optional): additional fields merged into gateway agent params
+- workspaceRuntime (object, optional): desired runtime service intents; Paperclip forwards these in a standardized paperclip.workspaceRuntime block for remote execution environments
 - timeoutSec (number, optional): adapter timeout in seconds (default 120)
 - waitTimeoutMs (number, optional): agent.wait timeout override (default timeoutSec * 1000)
 - autoPairOnFirstConnect (boolean, optional): on first "pairing required", attempt device.pair.list/device.pair.approve via shared auth, then retry once (default true)
@@ -39,4 +40,15 @@ Request behavior fields:
 Session routing fields:
 - sessionKeyStrategy (string, optional): issue (default), fixed, or run
 - sessionKey (string, optional): fixed session key when strategy=fixed (default paperclip)
+
+Standard outbound payload additions:
+- paperclip (object): standardized Paperclip context added to every gateway agent request
+- paperclip.workspace (object, optional): resolved execution workspace for this run
+- paperclip.workspaces (array, optional): additional workspace hints Paperclip exposed to the run
+- paperclip.workspaceRuntime (object, optional): normalized runtime service intent config for the workspace
+
+Standard result metadata supported:
+- meta.runtimeServices (array, optional): normalized adapter-managed runtime service reports
+- meta.previewUrl (string, optional): shorthand single preview URL
+- meta.previewUrls (string[], optional): shorthand multiple preview URLs
 `;

packages/adapters/openclaw-gateway/src/server/execute.ts

@@ -1,4 +1,8 @@
-import type { AdapterExecutionContext, AdapterExecutionResult } from "@paperclipai/adapter-utils";
+import type {
+  AdapterExecutionContext,
+  AdapterExecutionResult,
+  AdapterRuntimeServiceReport,
+} from "@paperclipai/adapter-utils";
 import { asNumber, asString, buildPaperclipEnv, parseObject } from "@paperclipai/adapter-utils/server-utils";
 import crypto, { randomUUID } from "node:crypto";
 import { WebSocket } from "ws";
@@ -411,6 +415,58 @@ function appendWakeText(baseText: string, wakeText: string): string {
   return trimmedBase.length > 0 ? `${trimmedBase}\n\n${wakeText}` : wakeText;
 }
 
+function buildStandardPaperclipPayload(
+  ctx: AdapterExecutionContext,
+  wakePayload: WakePayload,
+  paperclipEnv: Record<string, string>,
+  payloadTemplate: Record<string, unknown>,
+): Record<string, unknown> {
+  const templatePaperclip = parseObject(payloadTemplate.paperclip);
+  const workspace = asRecord(ctx.context.paperclipWorkspace);
+  const workspaces = Array.isArray(ctx.context.paperclipWorkspaces)
+    ? ctx.context.paperclipWorkspaces.filter((entry): entry is Record<string, unknown> => Boolean(asRecord(entry)))
+    : [];
+  const configuredWorkspaceRuntime = parseObject(ctx.config.workspaceRuntime);
+  const runtimeServiceIntents = Array.isArray(ctx.context.paperclipRuntimeServiceIntents)
+    ? ctx.context.paperclipRuntimeServiceIntents.filter(
+        (entry): entry is Record<string, unknown> => Boolean(asRecord(entry)),
+      )
+    : [];
+
+  const standardPaperclip: Record<string, unknown> = {
+    runId: ctx.runId,
+    companyId: ctx.agent.companyId,
+    agentId: ctx.agent.id,
+    agentName: ctx.agent.name,
+    taskId: wakePayload.taskId,
+    issueId: wakePayload.issueId,
+    issueIds: wakePayload.issueIds,
+    wakeReason: wakePayload.wakeReason,
+    wakeCommentId: wakePayload.wakeCommentId,
+    approvalId: wakePayload.approvalId,
+    approvalStatus: wakePayload.approvalStatus,
+    apiUrl: paperclipEnv.PAPERCLIP_API_URL ?? null,
+  };
+
+  if (workspace) {
+    standardPaperclip.workspace = workspace;
+  }
+  if (workspaces.length > 0) {
+    standardPaperclip.workspaces = workspaces;
+  }
+  if (runtimeServiceIntents.length > 0 || Object.keys(configuredWorkspaceRuntime).length > 0) {
+    standardPaperclip.workspaceRuntime = {
+      ...configuredWorkspaceRuntime,
+      ...(runtimeServiceIntents.length > 0 ? { services: runtimeServiceIntents } : {}),
+    };
+  }
+
+  return {
+    ...templatePaperclip,
+    ...standardPaperclip,
+  };
+}
+
 function normalizeUrl(input: string): URL | null {
   try {
     return new URL(input);
@@ -835,6 +891,91 @@ function parseUsage(value: unknown): AdapterExecutionResult["usage"] | undefined
   };
 }
 
+function extractRuntimeServicesFromMeta(meta: Record<string, unknown> | null): AdapterRuntimeServiceReport[] {
+  if (!meta) return [];
+  const reports: AdapterRuntimeServiceReport[] = [];
+
+  const runtimeServices = Array.isArray(meta.runtimeServices)
+    ? meta.runtimeServices.filter((entry): entry is Record<string, unknown> => Boolean(asRecord(entry)))
+    : [];
+  for (const entry of runtimeServices) {
+    const serviceName = nonEmpty(entry.serviceName) ?? nonEmpty(entry.name);
+    if (!serviceName) continue;
+    const rawStatus = nonEmpty(entry.status)?.toLowerCase();
+    const status =
+      rawStatus === "starting" || rawStatus === "running" || rawStatus === "stopped" || rawStatus === "failed"
+        ? rawStatus
+        : "running";
+    const rawLifecycle = nonEmpty(entry.lifecycle)?.toLowerCase();
+    const lifecycle = rawLifecycle === "shared" ? "shared" : "ephemeral";
+    const rawScopeType = nonEmpty(entry.scopeType)?.toLowerCase();
+    const scopeType =
+      rawScopeType === "project_workspace" ||
+      rawScopeType === "execution_workspace" ||
+      rawScopeType === "agent"
+        ? rawScopeType
+        : "run";
+    const rawHealth = nonEmpty(entry.healthStatus)?.toLowerCase();
+    const healthStatus =
+      rawHealth === "healthy" || rawHealth === "unhealthy" || rawHealth === "unknown"
+        ? rawHealth
+        : status === "running"
+          ? "healthy"
+          : "unknown";
+
+    reports.push({
+      id: nonEmpty(entry.id),
+      projectId: nonEmpty(entry.projectId),
+      projectWorkspaceId: nonEmpty(entry.projectWorkspaceId),
+      issueId: nonEmpty(entry.issueId),
+      scopeType,
+      scopeId: nonEmpty(entry.scopeId),
+      serviceName,
+      status,
+      lifecycle,
+      reuseKey: nonEmpty(entry.reuseKey),
+      command: nonEmpty(entry.command),
+      cwd: nonEmpty(entry.cwd),
+      port: parseOptionalPositiveInteger(entry.port),
+      url: nonEmpty(entry.url),
+      providerRef: nonEmpty(entry.providerRef) ?? nonEmpty(entry.previewId),
+      ownerAgentId: nonEmpty(entry.ownerAgentId),
+      stopPolicy: asRecord(entry.stopPolicy),
+      healthStatus,
+    });
+  }
+
+  const previewUrl = nonEmpty(meta.previewUrl);
+  if (previewUrl) {
+    reports.push({
+      serviceName: "preview",
+      status: "running",
+      lifecycle: "ephemeral",
+      scopeType: "run",
+      url: previewUrl,
+      providerRef: nonEmpty(meta.previewId) ?? previewUrl,
+      healthStatus: "healthy",
+    });
+  }
+
+  const previewUrls = Array.isArray(meta.previewUrls)
+    ? meta.previewUrls.filter((entry): entry is string => typeof entry === "string" && entry.trim().length > 0)
+    : [];
+  previewUrls.forEach((url, index) => {
+    reports.push({
+      serviceName: index === 0 ? "preview" : `preview-${index + 1}`,
+      status: "running",
+      lifecycle: "ephemeral",
+      scopeType: "run",
+      url,
+      providerRef: `${url}#${index}`,
+      healthStatus: "healthy",
+    });
+  });
+
+  return reports;
+}
+
 function extractResultText(value: unknown): string | null {
   const record = asRecord(value);
   if (!record) return null;
@@ -924,9 +1065,11 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
 
   const templateMessage = nonEmpty(payloadTemplate.message) ?? nonEmpty(payloadTemplate.text);
   const message = templateMessage ? appendWakeText(templateMessage, wakeText) : wakeText;
+  const paperclipPayload = buildStandardPaperclipPayload(ctx, wakePayload, paperclipEnv, payloadTemplate);
 
   const agentParams: Record<string, unknown> = {
     ...payloadTemplate,
+    paperclip: paperclipPayload,
     message,
     sessionKey,
     idempotencyKey: ctx.runId,
@@ -1188,12 +1331,24 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
         null;
       const summary = summaryFromEvents || summaryFromPayload || null;
 
-      const meta = asRecord(asRecord(acceptedPayload?.result)?.meta) ?? asRecord(acceptedPayload?.meta);
-      const agentMeta = asRecord(meta?.agentMeta);
-      const usage = parseUsage(agentMeta?.usage ?? meta?.usage);
-      const provider = nonEmpty(agentMeta?.provider) ?? nonEmpty(meta?.provider) ?? "openclaw";
-      const model = nonEmpty(agentMeta?.model) ?? nonEmpty(meta?.model) ?? null;
-      const costUsd = asNumber(agentMeta?.costUsd ?? meta?.costUsd, 0);
+      const acceptedResult = asRecord(acceptedPayload?.result);
+      const latestPayload = asRecord(latestResultPayload);
+      const latestResult = asRecord(latestPayload?.result);
+      const acceptedMeta = asRecord(acceptedResult?.meta) ?? asRecord(acceptedPayload?.meta);
+      const latestMeta = asRecord(latestResult?.meta) ?? asRecord(latestPayload?.meta);
+      const mergedMeta = {
+        ...(acceptedMeta ?? {}),
+        ...(latestMeta ?? {}),
+      };
+      const agentMeta =
+        asRecord(mergedMeta.agentMeta) ??
+        asRecord(acceptedMeta?.agentMeta) ??
+        asRecord(latestMeta?.agentMeta);
+      const usage = parseUsage(agentMeta?.usage ?? mergedMeta.usage);
+      const runtimeServices = extractRuntimeServicesFromMeta(agentMeta ?? mergedMeta);
+      const provider = nonEmpty(agentMeta?.provider) ?? nonEmpty(mergedMeta.provider) ?? "openclaw";
+      const model = nonEmpty(agentMeta?.model) ?? nonEmpty(mergedMeta.model) ?? null;
+      const costUsd = asNumber(agentMeta?.costUsd ?? mergedMeta.costUsd, 0);
 
       await ctx.onLog(
         "stdout",
@@ -1209,6 +1364,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
         ...(usage ? { usage } : {}),
         ...(costUsd > 0 ? { costUsd } : {}),
         resultJson: asRecord(latestResultPayload),
+        ...(runtimeServices.length > 0 ? { runtimeServices } : {}),
         ...(summary ? { summary } : {}),
       };
     } catch (err) {

packages/adapters/openclaw-gateway/src/ui/build-config.ts

@@ -1,5 +1,17 @@
 import type { CreateConfigValues } from "@paperclipai/adapter-utils";
 
+function parseJsonObject(text: string): Record<string, unknown> | null {
+  const trimmed = text.trim();
+  if (!trimmed) return null;
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+    return parsed as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
 export function buildOpenClawGatewayConfig(v: CreateConfigValues): Record<string, unknown> {
   const ac: Record<string, unknown> = {};
   if (v.url) ac.url = v.url;
@@ -8,5 +20,11 @@ export function buildOpenClawGatewayConfig(v: CreateConfigValues): Record<string
   ac.sessionKeyStrategy = "issue";
   ac.role = "operator";
   ac.scopes = ["operator.admin"];
+  const payloadTemplate = parseJsonObject(v.payloadTemplateJson ?? "");
+  if (payloadTemplate) ac.payloadTemplate = payloadTemplate;
+  const runtimeServices = parseJsonObject(v.runtimeServicesJson ?? "");
+  if (runtimeServices && Array.isArray(runtimeServices.services)) {
+    ac.workspaceRuntime = runtimeServices;
+  }
   return ac;
 }

packages/adapters/openclaw-gateway/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "../../../tsconfig.base.json",
+  "extends": "../../../tsconfig.json",
   "compilerOptions": {
     "outDir": "dist",
     "rootDir": "src"

packages/adapters/opencode-local/CHANGELOG.md

@@ -1,16 +1,5 @@
 # @paperclipai/adapter-opencode-local
 
-## 0.3.0
-
-### Minor Changes
-
-- Stable release preparation for 0.3.0
-
-### Patch Changes
-
-- Updated dependencies
-  - @paperclipai/adapter-utils@0.3.0
-
 ## 0.2.7
 
 ### Patch Changes

packages/adapters/opencode-local/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paperclipai/adapter-opencode-local",
-  "version": "0.3.0",
+  "version": "0.2.7",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",

packages/adapters/opencode-local/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "../../../tsconfig.base.json",
+  "extends": "../../../tsconfig.json",
   "compilerOptions": {
     "outDir": "dist",
     "rootDir": "src"

packages/adapters/pi-local/CHANGELOG.md

@@ -1,12 +0,0 @@
-# @paperclipai/adapter-pi-local
-
-## 0.3.0
-
-### Minor Changes
-
-- Stable release preparation for 0.3.0
-
-### Patch Changes
-
-- Updated dependencies
-  - @paperclipai/adapter-utils@0.3.0

packages/adapters/pi-local/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paperclipai/adapter-pi-local",
-  "version": "0.3.0",
+  "version": "0.1.0",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",

packages/adapters/pi-local/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "../../../tsconfig.base.json",
+  "extends": "../../../tsconfig.json",
   "compilerOptions": {
     "outDir": "dist",
     "rootDir": "src"

packages/db/CHANGELOG.md

@@ -1,17 +1,5 @@
 # @paperclipai/db
 
-## 0.3.0
-
-### Minor Changes
-
-- Stable release preparation for 0.3.0
-
-### Patch Changes
-
-- Updated dependencies [6077ae6]
-- Updated dependencies
-  - @paperclipai/shared@0.3.0
-
 ## 0.2.7
 
 ### Patch Changes

packages/db/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paperclipai/db",
-  "version": "0.3.0",
+  "version": "0.2.7",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",

packages/db/src/migrations/0026_lying_pete_wisdom.sql

@@ -0,0 +1,39 @@
+CREATE TABLE "workspace_runtime_services" (
+	"id" uuid PRIMARY KEY NOT NULL,
+	"company_id" uuid NOT NULL,
+	"project_id" uuid,
+	"project_workspace_id" uuid,
+	"issue_id" uuid,
+	"scope_type" text NOT NULL,
+	"scope_id" text,
+	"service_name" text NOT NULL,
+	"status" text NOT NULL,
+	"lifecycle" text NOT NULL,
+	"reuse_key" text,
+	"command" text,
+	"cwd" text,
+	"port" integer,
+	"url" text,
+	"provider" text NOT NULL,
+	"provider_ref" text,
+	"owner_agent_id" uuid,
+	"started_by_run_id" uuid,
+	"last_used_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"started_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"stopped_at" timestamp with time zone,
+	"stop_policy" jsonb,
+	"health_status" text DEFAULT 'unknown' NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "workspace_runtime_services" ADD CONSTRAINT "workspace_runtime_services_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 "workspace_runtime_services" ADD CONSTRAINT "workspace_runtime_services_project_id_projects_id_fk" FOREIGN KEY ("project_id") REFERENCES "public"."projects"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "workspace_runtime_services" ADD CONSTRAINT "workspace_runtime_services_project_workspace_id_project_workspaces_id_fk" FOREIGN KEY ("project_workspace_id") REFERENCES "public"."project_workspaces"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "workspace_runtime_services" ADD CONSTRAINT "workspace_runtime_services_issue_id_issues_id_fk" FOREIGN KEY ("issue_id") REFERENCES "public"."issues"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "workspace_runtime_services" ADD CONSTRAINT "workspace_runtime_services_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 "workspace_runtime_services" ADD CONSTRAINT "workspace_runtime_services_started_by_run_id_heartbeat_runs_id_fk" FOREIGN KEY ("started_by_run_id") REFERENCES "public"."heartbeat_runs"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "workspace_runtime_services_company_workspace_status_idx" ON "workspace_runtime_services" USING btree ("company_id","project_workspace_id","status");--> statement-breakpoint
+CREATE INDEX "workspace_runtime_services_company_project_status_idx" ON "workspace_runtime_services" USING btree ("company_id","project_id","status");--> statement-breakpoint
+CREATE INDEX "workspace_runtime_services_run_idx" ON "workspace_runtime_services" USING btree ("started_by_run_id");--> statement-breakpoint
+CREATE INDEX "workspace_runtime_services_company_updated_idx" ON "workspace_runtime_services" USING btree ("company_id","updated_at");

packages/db/src/migrations/0027_tranquil_tenebrous.sql

@@ -0,0 +1,2 @@
+ALTER TABLE "issues" ADD COLUMN "execution_workspace_settings" jsonb;--> statement-breakpoint
+ALTER TABLE "projects" ADD COLUMN "execution_workspace_policy" jsonb;

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

@@ -183,6 +183,20 @@
       "when": 1772807461603,
       "tag": "0025_nasty_salo",
       "breakpoints": true
+    },
+    {
+      "idx": 26,
+      "version": "7",
+      "when": 1773089625430,
+      "tag": "0026_lying_pete_wisdom",
+      "breakpoints": true
+    },
+    {
+      "idx": 27,
+      "version": "7",
+      "when": 1773150731736,
+      "tag": "0027_tranquil_tenebrous",
+      "breakpoints": true
     }
   ]
 }

packages/db/src/schema/index.ts

@@ -13,6 +13,7 @@ export { agentTaskSessions } from "./agent_task_sessions.js";
 export { agentWakeupRequests } from "./agent_wakeup_requests.js";
 export { projects } from "./projects.js";
 export { projectWorkspaces } from "./project_workspaces.js";
+export { workspaceRuntimeServices } from "./workspace_runtime_services.js";
 export { projectGoals } from "./project_goals.js";
 export { goals } from "./goals.js";
 export { issues } from "./issues.js";

packages/db/src/schema/issues.ts

@@ -40,6 +40,7 @@ export const issues = pgTable(
     requestDepth: integer("request_depth").notNull().default(0),
     billingCode: text("billing_code"),
     assigneeAdapterOverrides: jsonb("assignee_adapter_overrides").$type<Record<string, unknown>>(),
+    executionWorkspaceSettings: jsonb("execution_workspace_settings").$type<Record<string, unknown>>(),
     startedAt: timestamp("started_at", { withTimezone: true }),
     completedAt: timestamp("completed_at", { withTimezone: true }),
     cancelledAt: timestamp("cancelled_at", { withTimezone: true }),

packages/db/src/schema/projects.ts

@@ -1,4 +1,4 @@
-import { pgTable, uuid, text, timestamp, date, index } from "drizzle-orm/pg-core";
+import { pgTable, uuid, text, timestamp, date, index, jsonb } from "drizzle-orm/pg-core";
 import { companies } from "./companies.js";
 import { goals } from "./goals.js";
 import { agents } from "./agents.js";
@@ -15,6 +15,7 @@ export const projects = pgTable(
     leadAgentId: uuid("lead_agent_id").references(() => agents.id),
     targetDate: date("target_date"),
     color: text("color"),
+    executionWorkspacePolicy: jsonb("execution_workspace_policy").$type<Record<string, unknown>>(),
     archivedAt: timestamp("archived_at", { withTimezone: true }),
     createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
     updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),

packages/db/src/schema/workspace_runtime_services.ts

@@ -0,0 +1,64 @@
+import {
+  index,
+  integer,
+  jsonb,
+  pgTable,
+  text,
+  timestamp,
+  uuid,
+} from "drizzle-orm/pg-core";
+import { companies } from "./companies.js";
+import { projects } from "./projects.js";
+import { projectWorkspaces } from "./project_workspaces.js";
+import { issues } from "./issues.js";
+import { agents } from "./agents.js";
+import { heartbeatRuns } from "./heartbeat_runs.js";
+
+export const workspaceRuntimeServices = pgTable(
+  "workspace_runtime_services",
+  {
+    id: uuid("id").primaryKey(),
+    companyId: uuid("company_id").notNull().references(() => companies.id),
+    projectId: uuid("project_id").references(() => projects.id, { onDelete: "set null" }),
+    projectWorkspaceId: uuid("project_workspace_id").references(() => projectWorkspaces.id, { onDelete: "set null" }),
+    issueId: uuid("issue_id").references(() => issues.id, { onDelete: "set null" }),
+    scopeType: text("scope_type").notNull(),
+    scopeId: text("scope_id"),
+    serviceName: text("service_name").notNull(),
+    status: text("status").notNull(),
+    lifecycle: text("lifecycle").notNull(),
+    reuseKey: text("reuse_key"),
+    command: text("command"),
+    cwd: text("cwd"),
+    port: integer("port"),
+    url: text("url"),
+    provider: text("provider").notNull(),
+    providerRef: text("provider_ref"),
+    ownerAgentId: uuid("owner_agent_id").references(() => agents.id, { onDelete: "set null" }),
+    startedByRunId: uuid("started_by_run_id").references(() => heartbeatRuns.id, { onDelete: "set null" }),
+    lastUsedAt: timestamp("last_used_at", { withTimezone: true }).notNull().defaultNow(),
+    startedAt: timestamp("started_at", { withTimezone: true }).notNull().defaultNow(),
+    stoppedAt: timestamp("stopped_at", { withTimezone: true }),
+    stopPolicy: jsonb("stop_policy").$type<Record<string, unknown>>(),
+    healthStatus: text("health_status").notNull().default("unknown"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    companyWorkspaceStatusIdx: index("workspace_runtime_services_company_workspace_status_idx").on(
+      table.companyId,
+      table.projectWorkspaceId,
+      table.status,
+    ),
+    companyProjectStatusIdx: index("workspace_runtime_services_company_project_status_idx").on(
+      table.companyId,
+      table.projectId,
+      table.status,
+    ),
+    runIdx: index("workspace_runtime_services_run_idx").on(table.startedByRunId),
+    companyUpdatedIdx: index("workspace_runtime_services_company_updated_idx").on(
+      table.companyId,
+      table.updatedAt,
+    ),
+  }),
+);

packages/db/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "../../tsconfig.base.json",
+  "extends": "../../tsconfig.json",
   "compilerOptions": {
     "outDir": "dist",
     "rootDir": "src"

packages/shared/CHANGELOG.md

@@ -1,12 +1,5 @@
 # @paperclipai/shared
 
-## 0.3.0
-
-### Minor Changes
-
-- 6077ae6: Add support for Pi local adapter in constants and onboarding UI.
-- Stable release preparation for 0.3.0
-
 ## 0.2.7
 
 ### Patch Changes

packages/shared/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paperclipai/shared",
-  "version": "0.3.0",
+  "version": "0.2.7",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",

packages/shared/src/index.ts

@@ -77,6 +77,12 @@ export type {
   Project,
   ProjectGoalRef,
   ProjectWorkspace,
+  WorkspaceRuntimeService,
+  ExecutionWorkspaceStrategyType,
+  ExecutionWorkspaceMode,
+  ExecutionWorkspaceStrategy,
+  ProjectExecutionWorkspacePolicy,
+  IssueExecutionWorkspaceSettings,
   Issue,
   IssueAssigneeAdapterOverrides,
   IssueComment,
@@ -156,9 +162,11 @@ export {
   type UpdateProject,
   type CreateProjectWorkspace,
   type UpdateProjectWorkspace,
+  projectExecutionWorkspacePolicySchema,
   createIssueSchema,
   createIssueLabelSchema,
   updateIssueSchema,
+  issueExecutionWorkspaceSettingsSchema,
   checkoutIssueSchema,
   addIssueCommentSchema,
   linkIssueApprovalSchema,

packages/shared/src/types/index.ts

@@ -11,6 +11,14 @@ export type {
 } from "./agent.js";
 export type { AssetImage } from "./asset.js";
 export type { Project, ProjectGoalRef, ProjectWorkspace } from "./project.js";
+export type {
+  WorkspaceRuntimeService,
+  ExecutionWorkspaceStrategyType,
+  ExecutionWorkspaceMode,
+  ExecutionWorkspaceStrategy,
+  ProjectExecutionWorkspacePolicy,
+  IssueExecutionWorkspaceSettings,
+} from "./workspace-runtime.js";
 export type {
   Issue,
   IssueAssigneeAdapterOverrides,

packages/shared/src/types/issue.ts

@@ -1,6 +1,7 @@
 import type { IssuePriority, IssueStatus } from "../constants.js";
 import type { Goal } from "./goal.js";
 import type { Project, ProjectWorkspace } from "./project.js";
+import type { IssueExecutionWorkspaceSettings } from "./workspace-runtime.js";
 
 export interface IssueAncestorProject {
   id: string;
@@ -73,6 +74,7 @@ export interface Issue {
   requestDepth: number;
   billingCode: string | null;
   assigneeAdapterOverrides: IssueAssigneeAdapterOverrides | null;
+  executionWorkspaceSettings: IssueExecutionWorkspaceSettings | null;
   startedAt: Date | null;
   completedAt: Date | null;
   cancelledAt: Date | null;

packages/shared/src/types/project.ts

@@ -1,4 +1,5 @@
 import type { ProjectStatus } from "../constants.js";
+import type { ProjectExecutionWorkspacePolicy, WorkspaceRuntimeService } from "./workspace-runtime.js";
 
 export interface ProjectGoalRef {
   id: string;
@@ -15,6 +16,7 @@ export interface ProjectWorkspace {
   repoRef: string | null;
   metadata: Record<string, unknown> | null;
   isPrimary: boolean;
+  runtimeServices?: WorkspaceRuntimeService[];
   createdAt: Date;
   updatedAt: Date;
 }
@@ -33,6 +35,7 @@ export interface Project {
   leadAgentId: string | null;
   targetDate: string | null;
   color: string | null;
+  executionWorkspacePolicy: ProjectExecutionWorkspacePolicy | null;
   workspaces: ProjectWorkspace[];
   primaryWorkspace: ProjectWorkspace | null;
   archivedAt: Date | null;

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

@@ -0,0 +1,56 @@
+export type ExecutionWorkspaceStrategyType = "project_primary" | "git_worktree";
+
+export type ExecutionWorkspaceMode = "inherit" | "project_primary" | "isolated" | "agent_default";
+
+export interface ExecutionWorkspaceStrategy {
+  type: ExecutionWorkspaceStrategyType;
+  baseRef?: string | null;
+  branchTemplate?: string | null;
+  worktreeParentDir?: string | null;
+}
+
+export interface ProjectExecutionWorkspacePolicy {
+  enabled: boolean;
+  defaultMode?: "project_primary" | "isolated";
+  allowIssueOverride?: boolean;
+  workspaceStrategy?: ExecutionWorkspaceStrategy | null;
+  workspaceRuntime?: Record<string, unknown> | null;
+  branchPolicy?: Record<string, unknown> | null;
+  pullRequestPolicy?: Record<string, unknown> | null;
+  cleanupPolicy?: Record<string, unknown> | null;
+}
+
+export interface IssueExecutionWorkspaceSettings {
+  mode?: ExecutionWorkspaceMode;
+  workspaceStrategy?: ExecutionWorkspaceStrategy | null;
+  workspaceRuntime?: Record<string, unknown> | null;
+}
+
+export interface WorkspaceRuntimeService {
+  id: string;
+  companyId: string;
+  projectId: string | null;
+  projectWorkspaceId: string | null;
+  issueId: string | null;
+  scopeType: "project_workspace" | "execution_workspace" | "run" | "agent";
+  scopeId: string | null;
+  serviceName: string;
+  status: "starting" | "running" | "stopped" | "failed";
+  lifecycle: "shared" | "ephemeral";
+  reuseKey: string | null;
+  command: string | null;
+  cwd: string | null;
+  port: number | null;
+  url: string | null;
+  provider: "local_process" | "adapter_managed";
+  providerRef: string | null;
+  ownerAgentId: string | null;
+  startedByRunId: string | null;
+  lastUsedAt: Date;
+  startedAt: Date;
+  stoppedAt: Date | null;
+  stopPolicy: Record<string, unknown> | null;
+  healthStatus: "unknown" | "healthy" | "unhealthy";
+  createdAt: Date;
+  updatedAt: Date;
+}

packages/shared/src/validators/index.ts

@@ -49,16 +49,19 @@ export {
   updateProjectSchema,
   createProjectWorkspaceSchema,
   updateProjectWorkspaceSchema,
+  projectExecutionWorkspacePolicySchema,
   type CreateProject,
   type UpdateProject,
   type CreateProjectWorkspace,
   type UpdateProjectWorkspace,
+  type ProjectExecutionWorkspacePolicy,
 } from "./project.js";
 
 export {
   createIssueSchema,
   createIssueLabelSchema,
   updateIssueSchema,
+  issueExecutionWorkspaceSettingsSchema,
   checkoutIssueSchema,
   addIssueCommentSchema,
   linkIssueApprovalSchema,
@@ -66,6 +69,7 @@ export {
   type CreateIssue,
   type CreateIssueLabel,
   type UpdateIssue,
+  type IssueExecutionWorkspaceSettings,
   type CheckoutIssue,
   type AddIssueComment,
   type LinkIssueApproval,

packages/shared/src/validators/issue.ts

@@ -1,6 +1,23 @@
 import { z } from "zod";
 import { ISSUE_PRIORITIES, ISSUE_STATUSES } from "../constants.js";
 
+const executionWorkspaceStrategySchema = z
+  .object({
+    type: z.enum(["project_primary", "git_worktree"]).optional(),
+    baseRef: z.string().optional().nullable(),
+    branchTemplate: z.string().optional().nullable(),
+    worktreeParentDir: z.string().optional().nullable(),
+  })
+  .strict();
+
+export const issueExecutionWorkspaceSettingsSchema = z
+  .object({
+    mode: z.enum(["inherit", "project_primary", "isolated", "agent_default"]).optional(),
+    workspaceStrategy: executionWorkspaceStrategySchema.optional().nullable(),
+    workspaceRuntime: z.record(z.unknown()).optional().nullable(),
+  })
+  .strict();
+
 export const issueAssigneeAdapterOverridesSchema = z
   .object({
     adapterConfig: z.record(z.unknown()).optional(),
@@ -21,6 +38,7 @@ export const createIssueSchema = z.object({
   requestDepth: z.number().int().nonnegative().optional().default(0),
   billingCode: z.string().optional().nullable(),
   assigneeAdapterOverrides: issueAssigneeAdapterOverridesSchema.optional().nullable(),
+  executionWorkspaceSettings: issueExecutionWorkspaceSettingsSchema.optional().nullable(),
   labelIds: z.array(z.string().uuid()).optional(),
 });
 
@@ -39,6 +57,7 @@ export const updateIssueSchema = createIssueSchema.partial().extend({
 });
 
 export type UpdateIssue = z.infer<typeof updateIssueSchema>;
+export type IssueExecutionWorkspaceSettings = z.infer<typeof issueExecutionWorkspaceSettingsSchema>;
 
 export const checkoutIssueSchema = z.object({
   agentId: z.string().uuid(),

packages/shared/src/validators/project.ts

@@ -1,6 +1,28 @@
 import { z } from "zod";
 import { PROJECT_STATUSES } from "../constants.js";
 
+const executionWorkspaceStrategySchema = z
+  .object({
+    type: z.enum(["project_primary", "git_worktree"]).optional(),
+    baseRef: z.string().optional().nullable(),
+    branchTemplate: z.string().optional().nullable(),
+    worktreeParentDir: z.string().optional().nullable(),
+  })
+  .strict();
+
+export const projectExecutionWorkspacePolicySchema = z
+  .object({
+    enabled: z.boolean(),
+    defaultMode: z.enum(["project_primary", "isolated"]).optional(),
+    allowIssueOverride: z.boolean().optional(),
+    workspaceStrategy: executionWorkspaceStrategySchema.optional().nullable(),
+    workspaceRuntime: z.record(z.unknown()).optional().nullable(),
+    branchPolicy: z.record(z.unknown()).optional().nullable(),
+    pullRequestPolicy: z.record(z.unknown()).optional().nullable(),
+    cleanupPolicy: z.record(z.unknown()).optional().nullable(),
+  })
+  .strict();
+
 const projectWorkspaceFields = {
   name: z.string().min(1).optional(),
   cwd: z.string().min(1).optional().nullable(),
@@ -43,6 +65,7 @@ const projectFields = {
   leadAgentId: z.string().uuid().optional().nullable(),
   targetDate: z.string().optional().nullable(),
   color: z.string().optional().nullable(),
+  executionWorkspacePolicy: projectExecutionWorkspacePolicySchema.optional().nullable(),
   archivedAt: z.string().datetime().optional().nullable(),
 };
 
@@ -56,3 +79,5 @@ export type CreateProject = z.infer<typeof createProjectSchema>;
 export const updateProjectSchema = z.object(projectFields).partial();
 
 export type UpdateProject = z.infer<typeof updateProjectSchema>;
+
+export type ProjectExecutionWorkspacePolicy = z.infer<typeof projectExecutionWorkspacePolicySchema>;

packages/shared/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "../../tsconfig.base.json",
+  "extends": "../../tsconfig.json",
   "compilerOptions": {
     "outDir": "dist",
     "rootDir": "src"

releases/v0.3.0.md

@@ -4,9 +4,9 @@
 
 ## Highlights
 
-- **New adapters: Cursor, OpenCode, and Pi** — Paperclip now supports three additional local coding agents. Cursor and OpenCode integrate as first-class adapters with model discovery, run-log streaming, and skill injection. Pi adds a local RPC mode with cost tracking. All three appear in the onboarding wizard alongside Claude Code and Codex. ([#62](https://github.com/paperclipai/paperclip/pull/62), [#141](https://github.com/paperclipai/paperclip/pull/141), [#240](https://github.com/paperclipai/paperclip/pull/240), [#183](https://github.com/paperclipai/paperclip/pull/183), @aaaaron, @Konan69, @richardanaya)
-- **OpenClaw gateway adapter** — A new gateway-only OpenClaw flow replaces the legacy adapter. It uses strict SSE streaming, supports device-key pairing, and handles invite-based onboarding with join-token validation. ([#270](https://github.com/paperclipai/paperclip/pull/270))
-- **Inbox and unread semantics** — Issues now track per-user read state. Unread indicators appear in the inbox, dashboard, and browser tab (blue dot). The inbox badge includes join requests and approvals, and inbox ordering is alert-focused. ([#196](https://github.com/paperclipai/paperclip/pull/196), @hougangdev)
+- **New adapters: Cursor, OpenCode, and Pi** — Paperclip now supports three additional local coding agents. Cursor and OpenCode integrate as first-class adapters with model discovery, run-log streaming, and skill injection. Pi adds a local RPC mode with cost tracking. All three appear in the onboarding wizard alongside Claude Code and Codex.
+- **OpenClaw gateway adapter** — A new gateway-only OpenClaw flow replaces the legacy adapter. It uses strict SSE streaming, supports device-key pairing, and handles invite-based onboarding with join-token validation.
+- **Inbox and unread semantics** — Issues now track per-user read state. Unread indicators appear in the inbox, dashboard, and browser tab (blue dot). The inbox badge includes join requests and approvals, and inbox ordering is alert-focused.
 - **PWA support** — The UI ships as an installable Progressive Web App with a service worker and enhanced manifest. The service worker uses a network-first strategy to prevent stale content.
 - **Agent creation wizard** — A new choice modal and full-page configuration flow make it easier to add agents. The sidebar AGENTS header now has a quick-add button.
 
@@ -19,35 +19,29 @@
 - **Project status clickable** — The status chip in the project properties pane is now clickable for quick updates.
 - **Scroll-to-bottom button** — Issue detail and run pages show a floating scroll-to-bottom button when you scroll up.
 - **Database backup CLI** — `paperclipai db:backup` lets you snapshot the database on demand, with optional automatic scheduling.
-- **Disable sign-up** — A new `auth.disableSignUp` config option (and `AUTH_DISABLE_SIGNUP` env var) lets operators lock registration. ([#279](https://github.com/paperclipai/paperclip/pull/279), @JasonOA888)
-- **Deduplicated shortnames** — Agent and project shortnames are now auto-deduplicated on create and update instead of rejecting duplicates. ([#264](https://github.com/paperclipai/paperclip/pull/264), @mvanhorn)
-- **Human-readable role labels** — The agent list and properties pane show friendly role names. ([#263](https://github.com/paperclipai/paperclip/pull/263), @mvanhorn)
+- **Disable sign-up** — A new `auth.disableSignUp` config option (and `AUTH_DISABLE_SIGNUP` env var) lets operators lock registration.
+- **Deduplicated shortnames** — Agent and project shortnames are now auto-deduplicated on create and update instead of rejecting duplicates.
+- **Human-readable role labels** — The agent list and properties pane show friendly role names.
 - **Assignee picker sorting** — Recent selections appear first, then alphabetical.
-- **Mobile layout polish** — Unified GitHub-style issue rows across issues, inbox, and dashboard. Improved popover scrolling, command palette centering, and property toggles on mobile. ([#118](https://github.com/paperclipai/paperclip/pull/118), @MumuTW)
+- **Mobile layout polish** — Unified GitHub-style issue rows across issues, inbox, and dashboard. Improved popover scrolling, command palette centering, and property toggles on mobile.
 - **Invite UX improvements** — Invite links auto-copy to clipboard, snippet-only flow in settings, 10-minute invite TTL, and clearer network-host guidance.
 - **Permalink anchors on comments** — Each comment has a stable anchor link and a GET-by-ID API endpoint.
-- **Docker deployment hardening** — Authenticated deployment mode by default, named data volume, `PAPERCLIP_PUBLIC_URL` and `PAPERCLIP_ALLOWED_HOSTNAMES` exposed in compose files, health-check DB wait, and Node 24 base image. ([#400](https://github.com/paperclipai/paperclip/pull/400), [#283](https://github.com/paperclipai/paperclip/pull/283), [#284](https://github.com/paperclipai/paperclip/pull/284), @AiMagic5000, @mingfang)
-- **Updated model lists** — Added `claude-sonnet-4-6`, `claude-haiku-4-6`, and `gpt-5.4` to adapter model constants. ([#293](https://github.com/paperclipai/paperclip/pull/293), [#110](https://github.com/paperclipai/paperclip/pull/110), @cpfarhood, @artokun)
+- **Docker deployment hardening** — Authenticated deployment mode by default, named data volume, `PAPERCLIP_PUBLIC_URL` and `PAPERCLIP_ALLOWED_HOSTNAMES` exposed in compose files, health-check DB wait, and Node 24 base image.
+- **Updated model lists** — Added `claude-sonnet-4-6`, `claude-haiku-4-6`, and `gpt-5.4` to adapter model constants.
 - **Playwright e2e tests** — New end-to-end test suite covering the onboarding wizard flow.
 
 ## Fixes
 
-- **Secret redaction in run logs** — Env vars sourced from secrets are now redacted by provenance, with consistent `secretKeys` tracking. ([#261](https://github.com/paperclipai/paperclip/pull/261), @mvanhorn)
-- **SPA catch-all 500s** — The server serves cached `index.html` in the catch-all route and uses `root` in `sendFile`, preventing 500 errors on dotfile paths and SPA refreshes. ([#269](https://github.com/paperclipai/paperclip/pull/269), [#78](https://github.com/paperclipai/paperclip/pull/78), @mvanhorn, @MumuTW)
-- **Unmatched API routes return 404 JSON** — Previously fell through to the SPA handler. ([#269](https://github.com/paperclipai/paperclip/pull/269), @mvanhorn)
-- **Agent wake logic** — Agents wake when issues move out of backlog, skip self-wake on own comments, and skip wakeup for backlog-status changes. Pending-approval agents are excluded from heartbeat timers. ([#159](https://github.com/paperclipai/paperclip/pull/159), [#154](https://github.com/paperclipai/paperclip/pull/154), [#267](https://github.com/paperclipai/paperclip/pull/267), [#72](https://github.com/paperclipai/paperclip/pull/72), @Logesh-waran2003, @cschneid, @mvanhorn, @STRML)
-- **Run log fd leak** — Fixed a file-descriptor leak in log append that caused `spawn EBADF` errors. ([#266](https://github.com/paperclipai/paperclip/pull/266), @mvanhorn)
+- **Secret redaction in run logs** — Env vars sourced from secrets are now redacted by provenance, with consistent `secretKeys` tracking.
+- **SPA catch-all 500s** — The server serves cached `index.html` in the catch-all route and uses `root` in `sendFile`, preventing 500 errors on dotfile paths and SPA refreshes.
+- **Unmatched API routes return 404 JSON** — Previously fell through to the SPA handler.
+- **Agent wake logic** — Agents wake when issues move out of backlog, skip self-wake on own comments, and skip wakeup for backlog-status changes. Pending-approval agents are excluded from heartbeat timers.
+- **Run log fd leak** — Fixed a file-descriptor leak in log append that caused `spawn EBADF` errors.
 - **500 error logging** — Error logs now include the actual error message and request context instead of generic pino-http output.
-- **Boolean env parsing** — `parseBooleanFromEnv` no longer silently treats common truthy values as false. ([#91](https://github.com/paperclipai/paperclip/pull/91), @zvictor)
-- **Onboarding env defaults** — `onboard` now correctly derives secrets from env vars and reports ignored exposure settings in `local_trusted` mode. ([#91](https://github.com/paperclipai/paperclip/pull/91), @zvictor)
-- **Windows path compatibility** — Migration paths use `fileURLToPath` for Windows-safe resolution. ([#265](https://github.com/paperclipai/paperclip/pull/265), [#413](https://github.com/paperclipai/paperclip/pull/413), @mvanhorn, @online5880)
-- **Secure cookies on HTTP** — Disabled secure cookie flag for plain HTTP deployments to prevent auth failures. ([#376](https://github.com/paperclipai/paperclip/pull/376), @dalestubblefield)
-- **URL encoding** — `buildUrl` splits path and query to prevent `%3F` encoding issues. ([#260](https://github.com/paperclipai/paperclip/pull/260), @mvanhorn)
-- **Auth trusted origins** — Effective trusted origins and allowed hostnames are now applied correctly in public mode. ([#99](https://github.com/paperclipai/paperclip/pull/99), @zvictor)
-- **UI stability** — Fixed blank screen when prompt templates are emptied, search URL sync causing re-renders, issue title overflow in inbox, and sidebar badge counts including approvals. ([#262](https://github.com/paperclipai/paperclip/pull/262), [#196](https://github.com/paperclipai/paperclip/pull/196), [#423](https://github.com/paperclipai/paperclip/pull/423), @mvanhorn, @hougangdev, @RememberV)
-
-## Contributors
-
-Thank you to everyone who contributed to this release!
-
-@aaaaron, @AiMagic5000, @artokun, @cpfarhood, @cschneid, @dalestubblefield, @Dotta, @eltociear, @fahmmin, @gsxdsm, @hougangdev, @JasonOA888, @Konan69, @Logesh-waran2003, @mingfang, @MumuTW, @mvanhorn, @numman-ali, @online5880, @RememberV, @richardanaya, @STRML, @tylerwince, @zvictor
+- **Boolean env parsing** — `parseBooleanFromEnv` no longer silently treats common truthy values as false.
+- **Onboarding env defaults** — `onboard` now correctly derives secrets from env vars and reports ignored exposure settings in `local_trusted` mode.
+- **Windows path compatibility** — Migration paths use `fileURLToPath` for Windows-safe resolution.
+- **Secure cookies on HTTP** — Disabled secure cookie flag for plain HTTP deployments to prevent auth failures.
+- **URL encoding** — `buildUrl` splits path and query to prevent `%3F` encoding issues.
+- **Auth trusted origins** — Effective trusted origins and allowed hostnames are now applied correctly in public mode.
+- **UI stability** — Fixed blank screen when prompt templates are emptied, search URL sync causing re-renders, issue title overflow in inbox, and sidebar badge counts including approvals.

scripts/create-github-release.sh

@@ -2,8 +2,7 @@
 set -euo pipefail
 
 REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
-# shellcheck source=./release-lib.sh
-. "$REPO_ROOT/scripts/release-lib.sh"
+PUBLISH_REMOTE="${PUBLISH_REMOTE:-public-gh}"
 
 dry_run=false
 version=""
@@ -18,8 +17,7 @@ Examples:
   ./scripts/create-github-release.sh 1.2.3 --dry-run
 
 Notes:
-  - Run this after pushing the stable release branch and tag.
-  - Defaults to git remote public-gh.
+  - Run this after pushing the release commit and tag.
   - If the release already exists, this script updates its title and notes.
 EOF
 }
@@ -54,19 +52,12 @@ fi
 
 tag="v$version"
 notes_file="$REPO_ROOT/releases/${tag}.md"
-PUBLISH_REMOTE="${PUBLISH_REMOTE:-public-gh}"
-PUBLISH_REMOTE="$(resolve_release_remote)"
+
 if ! command -v gh >/dev/null 2>&1; then
   echo "Error: gh CLI is required to create GitHub releases." >&2
   exit 1
 fi
 
-GITHUB_REPO="$(github_repo_from_remote "$PUBLISH_REMOTE" || true)"
-if [ -z "$GITHUB_REPO" ]; then
-  echo "Error: could not determine GitHub repository from remote $PUBLISH_REMOTE." >&2
-  exit 1
-fi
-
 if [ ! -f "$notes_file" ]; then
   echo "Error: release notes file not found at $notes_file." >&2
   exit 1
@@ -78,7 +69,7 @@ if ! git -C "$REPO_ROOT" rev-parse "$tag" >/dev/null 2>&1; then
 fi
 
 if [ "$dry_run" = true ]; then
-  echo "[dry-run] gh release create $tag -R $GITHUB_REPO --title $tag --notes-file $notes_file"
+  echo "[dry-run] gh release create $tag --title $tag --notes-file $notes_file"
   exit 0
 fi
 
@@ -87,10 +78,10 @@ if ! git -C "$REPO_ROOT" ls-remote --exit-code --tags "$PUBLISH_REMOTE" "refs/ta
   exit 1
 fi
 
-if gh release view "$tag" -R "$GITHUB_REPO" >/dev/null 2>&1; then
-  gh release edit "$tag" -R "$GITHUB_REPO" --title "$tag" --notes-file "$notes_file"
+if gh release view "$tag" >/dev/null 2>&1; then
+  gh release edit "$tag" --title "$tag" --notes-file "$notes_file"
   echo "Updated GitHub Release $tag"
 else
-  gh release create "$tag" -R "$GITHUB_REPO" --title "$tag" --notes-file "$notes_file"
+  gh release create "$tag" --title "$tag" --notes-file "$notes_file"
   echo "Created GitHub Release $tag"
 fi

scripts/docker-onboard-smoke.sh

@@ -9,199 +9,14 @@ DATA_DIR="${DATA_DIR:-$REPO_ROOT/data/docker-onboard-smoke}"
 HOST_UID="${HOST_UID:-$(id -u)}"
 PAPERCLIP_DEPLOYMENT_MODE="${PAPERCLIP_DEPLOYMENT_MODE:-authenticated}"
 PAPERCLIP_DEPLOYMENT_EXPOSURE="${PAPERCLIP_DEPLOYMENT_EXPOSURE:-private}"
-PAPERCLIP_PUBLIC_URL="${PAPERCLIP_PUBLIC_URL:-http://localhost:${HOST_PORT}}"
-SMOKE_AUTO_BOOTSTRAP="${SMOKE_AUTO_BOOTSTRAP:-true}"
-SMOKE_ADMIN_NAME="${SMOKE_ADMIN_NAME:-Smoke Admin}"
-SMOKE_ADMIN_EMAIL="${SMOKE_ADMIN_EMAIL:-smoke-admin@paperclip.local}"
-SMOKE_ADMIN_PASSWORD="${SMOKE_ADMIN_PASSWORD:-paperclip-smoke-password}"
-CONTAINER_NAME="${IMAGE_NAME//[^a-zA-Z0-9_.-]/-}"
-LOG_PID=""
-COOKIE_JAR=""
-TMP_DIR=""
+DOCKER_TTY_ARGS=()
+
+if [[ -t 0 && -t 1 ]]; then
+  DOCKER_TTY_ARGS=(-it)
+fi
 
 mkdir -p "$DATA_DIR"
 
-cleanup() {
-  if [[ -n "$LOG_PID" ]]; then
-    kill "$LOG_PID" >/dev/null 2>&1 || true
-  fi
-  docker stop "$CONTAINER_NAME" >/dev/null 2>&1 || true
-  if [[ -n "$TMP_DIR" && -d "$TMP_DIR" ]]; then
-    rm -rf "$TMP_DIR"
-  fi
-}
-
-trap cleanup EXIT INT TERM
-
-wait_for_http() {
-  local url="$1"
-  local attempts="${2:-60}"
-  local sleep_seconds="${3:-1}"
-  local i
-  for ((i = 1; i <= attempts; i += 1)); do
-    if curl -fsS "$url" >/dev/null 2>&1; then
-      return 0
-    fi
-    sleep "$sleep_seconds"
-  done
-  return 1
-}
-
-generate_bootstrap_invite_url() {
-  local bootstrap_output
-  local bootstrap_status
-  if bootstrap_output="$(
-    docker exec \
-      -e PAPERCLIP_DEPLOYMENT_MODE="$PAPERCLIP_DEPLOYMENT_MODE" \
-      -e PAPERCLIP_DEPLOYMENT_EXPOSURE="$PAPERCLIP_DEPLOYMENT_EXPOSURE" \
-      -e PAPERCLIP_PUBLIC_URL="$PAPERCLIP_PUBLIC_URL" \
-      -e PAPERCLIP_HOME="/paperclip" \
-      "$CONTAINER_NAME" bash -lc \
-      'timeout 20s npx --yes "paperclipai@${PAPERCLIPAI_VERSION}" auth bootstrap-ceo --data-dir "$PAPERCLIP_HOME" --base-url "$PAPERCLIP_PUBLIC_URL"' \
-      2>&1
-  )"; then
-    bootstrap_status=0
-  else
-    bootstrap_status=$?
-  fi
-
-  if [[ $bootstrap_status -ne 0 && $bootstrap_status -ne 124 ]]; then
-    echo "Smoke bootstrap failed: could not run bootstrap-ceo inside container" >&2
-    printf '%s\n' "$bootstrap_output" >&2
-    return 1
-  fi
-
-  local invite_url
-  invite_url="$(
-    printf '%s\n' "$bootstrap_output" \
-      | grep -o 'https\?://[^[:space:]]*/invite/pcp_bootstrap_[[:alnum:]]*' \
-      | tail -n 1
-  )"
-
-  if [[ -z "$invite_url" ]]; then
-    echo "Smoke bootstrap failed: bootstrap-ceo did not print an invite URL" >&2
-    printf '%s\n' "$bootstrap_output" >&2
-    return 1
-  fi
-
-  if [[ $bootstrap_status -eq 124 ]]; then
-    echo "    Smoke bootstrap: bootstrap-ceo timed out after printing invite URL; continuing" >&2
-  fi
-
-  printf '%s\n' "$invite_url"
-}
-
-post_json_with_cookies() {
-  local url="$1"
-  local body="$2"
-  local output_file="$3"
-  curl -sS \
-    -o "$output_file" \
-    -w "%{http_code}" \
-    -c "$COOKIE_JAR" \
-    -b "$COOKIE_JAR" \
-    -H "Content-Type: application/json" \
-    -H "Origin: $PAPERCLIP_PUBLIC_URL" \
-    -X POST \
-    "$url" \
-    --data "$body"
-}
-
-get_with_cookies() {
-  local url="$1"
-  curl -fsS \
-    -c "$COOKIE_JAR" \
-    -b "$COOKIE_JAR" \
-    -H "Accept: application/json" \
-    "$url"
-}
-
-sign_up_or_sign_in() {
-  local signup_response="$TMP_DIR/signup.json"
-  local signup_status
-  signup_status="$(post_json_with_cookies \
-    "$PAPERCLIP_PUBLIC_URL/api/auth/sign-up/email" \
-    "{\"name\":\"$SMOKE_ADMIN_NAME\",\"email\":\"$SMOKE_ADMIN_EMAIL\",\"password\":\"$SMOKE_ADMIN_PASSWORD\"}" \
-    "$signup_response")"
-  if [[ "$signup_status" =~ ^2 ]]; then
-    echo "    Smoke bootstrap: created admin user $SMOKE_ADMIN_EMAIL"
-    return 0
-  fi
-
-  local signin_response="$TMP_DIR/signin.json"
-  local signin_status
-  signin_status="$(post_json_with_cookies \
-    "$PAPERCLIP_PUBLIC_URL/api/auth/sign-in/email" \
-    "{\"email\":\"$SMOKE_ADMIN_EMAIL\",\"password\":\"$SMOKE_ADMIN_PASSWORD\"}" \
-    "$signin_response")"
-  if [[ "$signin_status" =~ ^2 ]]; then
-    echo "    Smoke bootstrap: signed in existing admin user $SMOKE_ADMIN_EMAIL"
-    return 0
-  fi
-
-  echo "Smoke bootstrap failed: could not sign up or sign in admin user" >&2
-  echo "Sign-up response:" >&2
-  cat "$signup_response" >&2 || true
-  echo >&2
-  echo "Sign-in response:" >&2
-  cat "$signin_response" >&2 || true
-  echo >&2
-  return 1
-}
-
-auto_bootstrap_authenticated_smoke() {
-  local health_url="$PAPERCLIP_PUBLIC_URL/api/health"
-  local health_json
-  health_json="$(curl -fsS "$health_url")"
-  if [[ "$health_json" != *'"deploymentMode":"authenticated"'* ]]; then
-    return 0
-  fi
-
-  sign_up_or_sign_in
-
-  if [[ "$health_json" == *'"bootstrapStatus":"ready"'* ]]; then
-    echo "    Smoke bootstrap: instance already ready"
-  else
-    local invite_url
-    invite_url="$(generate_bootstrap_invite_url)"
-    echo "    Smoke bootstrap: generated bootstrap invite via auth bootstrap-ceo"
-
-    local invite_token="${invite_url##*/}"
-    local accept_response="$TMP_DIR/accept.json"
-    local accept_status
-    accept_status="$(post_json_with_cookies \
-      "$PAPERCLIP_PUBLIC_URL/api/invites/$invite_token/accept" \
-      '{"requestType":"human"}' \
-      "$accept_response")"
-    if [[ ! "$accept_status" =~ ^2 ]]; then
-      echo "Smoke bootstrap failed: bootstrap invite acceptance returned HTTP $accept_status" >&2
-      cat "$accept_response" >&2 || true
-      echo >&2
-      return 1
-    fi
-    echo "    Smoke bootstrap: accepted bootstrap invite"
-  fi
-
-  local session_json
-  session_json="$(get_with_cookies "$PAPERCLIP_PUBLIC_URL/api/auth/get-session")"
-  if [[ "$session_json" != *'"userId"'* ]]; then
-    echo "Smoke bootstrap failed: no authenticated session after bootstrap" >&2
-    echo "$session_json" >&2
-    return 1
-  fi
-
-  local companies_json
-  companies_json="$(get_with_cookies "$PAPERCLIP_PUBLIC_URL/api/companies")"
-  if [[ "${companies_json:0:1}" != "[" ]]; then
-    echo "Smoke bootstrap failed: board companies endpoint did not return JSON array" >&2
-    echo "$companies_json" >&2
-    return 1
-  fi
-
-  echo "    Smoke bootstrap: board session verified"
-  echo "    Smoke admin credentials: $SMOKE_ADMIN_EMAIL / $SMOKE_ADMIN_PASSWORD"
-}
-
 echo "==> Building onboard smoke image"
 docker build \
   --build-arg PAPERCLIPAI_VERSION="$PAPERCLIPAI_VERSION" \
@@ -212,38 +27,16 @@ docker build \
 
 echo "==> Running onboard smoke container"
 echo "    UI should be reachable at: http://localhost:$HOST_PORT"
-echo "    Public URL: $PAPERCLIP_PUBLIC_URL"
-echo "    Smoke auto-bootstrap: $SMOKE_AUTO_BOOTSTRAP"
 echo "    Data dir: $DATA_DIR"
 echo "    Deployment: $PAPERCLIP_DEPLOYMENT_MODE/$PAPERCLIP_DEPLOYMENT_EXPOSURE"
 echo "    Live output: onboard banner and server logs stream in this terminal (Ctrl+C to stop)"
-
-docker rm -f "$CONTAINER_NAME" >/dev/null 2>&1 || true
-
-docker run -d --rm \
-  --name "$CONTAINER_NAME" \
+docker run --rm \
+  "${DOCKER_TTY_ARGS[@]}" \
+  --name "${IMAGE_NAME//[^a-zA-Z0-9_.-]/-}" \
   -p "$HOST_PORT:3100" \
   -e HOST=0.0.0.0 \
   -e PORT=3100 \
   -e PAPERCLIP_DEPLOYMENT_MODE="$PAPERCLIP_DEPLOYMENT_MODE" \
   -e PAPERCLIP_DEPLOYMENT_EXPOSURE="$PAPERCLIP_DEPLOYMENT_EXPOSURE" \
-  -e PAPERCLIP_PUBLIC_URL="$PAPERCLIP_PUBLIC_URL" \
   -v "$DATA_DIR:/paperclip" \
-  "$IMAGE_NAME" >/dev/null
-
-docker logs -f "$CONTAINER_NAME" &
-LOG_PID=$!
-
-TMP_DIR="$(mktemp -d "${TMPDIR:-/tmp}/paperclip-onboard-smoke.XXXXXX")"
-COOKIE_JAR="$TMP_DIR/cookies.txt"
-
-if ! wait_for_http "$PAPERCLIP_PUBLIC_URL/api/health" 90 1; then
-  echo "Smoke bootstrap failed: server did not become ready at $PAPERCLIP_PUBLIC_URL/api/health" >&2
-  exit 1
-fi
-
-if [[ "$SMOKE_AUTO_BOOTSTRAP" == "true" && "$PAPERCLIP_DEPLOYMENT_MODE" == "authenticated" ]]; then
-  auto_bootstrap_authenticated_smoke
-fi
-
-wait "$LOG_PID"
+  "$IMAGE_NAME"

scripts/release-lib.sh

@@ -1,251 +0,0 @@
-#!/usr/bin/env bash
-
-if [ -z "${REPO_ROOT:-}" ]; then
-  REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-fi
-
-release_info() {
-  echo "$@"
-}
-
-release_warn() {
-  echo "Warning: $*" >&2
-}
-
-release_fail() {
-  echo "Error: $*" >&2
-  exit 1
-}
-
-git_remote_exists() {
-  git -C "$REPO_ROOT" remote get-url "$1" >/dev/null 2>&1
-}
-
-github_repo_from_remote() {
-  local remote_url
-
-  remote_url="$(git -C "$REPO_ROOT" remote get-url "$1" 2>/dev/null || true)"
-  [ -n "$remote_url" ] || return 1
-
-  remote_url="${remote_url%.git}"
-  remote_url="${remote_url#ssh://}"
-
-  node - "$remote_url" <<'NODE'
-const remoteUrl = process.argv[2];
-
-const patterns = [
-  /^https?:\/\/github\.com\/([^/]+\/[^/]+)$/,
-  /^git@github\.com:([^/]+\/[^/]+)$/,
-  /^[^:]+:([^/]+\/[^/]+)$/
-];
-
-for (const pattern of patterns) {
-  const match = remoteUrl.match(pattern);
-  if (!match) continue;
-  process.stdout.write(match[1]);
-  process.exit(0);
-}
-
-process.exit(1);
-NODE
-}
-
-resolve_release_remote() {
-  local remote="${RELEASE_REMOTE:-${PUBLISH_REMOTE:-}}"
-
-  if [ -n "$remote" ]; then
-    git_remote_exists "$remote" || release_fail "git remote '$remote' does not exist."
-    printf '%s\n' "$remote"
-    return
-  fi
-
-  if git_remote_exists public-gh; then
-    printf 'public-gh\n'
-    return
-  fi
-
-  if git_remote_exists origin; then
-    printf 'origin\n'
-    return
-  fi
-
-  release_fail "no git remote found. Configure RELEASE_REMOTE or PUBLISH_REMOTE."
-}
-
-fetch_release_remote() {
-  git -C "$REPO_ROOT" fetch "$1" --prune --tags
-}
-
-get_last_stable_tag() {
-  git -C "$REPO_ROOT" tag --list 'v*' --sort=-version:refname | head -1
-}
-
-get_current_stable_version() {
-  local tag
-  tag="$(get_last_stable_tag)"
-  if [ -z "$tag" ]; then
-    printf '0.0.0\n'
-  else
-    printf '%s\n' "${tag#v}"
-  fi
-}
-
-compute_bumped_version() {
-  node - "$1" "$2" <<'NODE'
-const current = process.argv[2];
-const bump = process.argv[3];
-const match = current.match(/^(\d+)\.(\d+)\.(\d+)$/);
-
-if (!match) {
-  throw new Error(`invalid semver version: ${current}`);
-}
-
-let [major, minor, patch] = match.slice(1).map(Number);
-
-if (bump === 'patch') {
-  patch += 1;
-} else if (bump === 'minor') {
-  minor += 1;
-  patch = 0;
-} else if (bump === 'major') {
-  major += 1;
-  minor = 0;
-  patch = 0;
-} else {
-  throw new Error(`unsupported bump type: ${bump}`);
-}
-
-process.stdout.write(`${major}.${minor}.${patch}`);
-NODE
-}
-
-next_canary_version() {
-  local stable_version="$1"
-  local versions_json
-
-  versions_json="$(npm view paperclipai versions --json 2>/dev/null || echo '[]')"
-
-  node - "$stable_version" "$versions_json" <<'NODE'
-const stable = process.argv[2];
-const versionsArg = process.argv[3];
-
-let versions = [];
-try {
-  const parsed = JSON.parse(versionsArg);
-  versions = Array.isArray(parsed) ? parsed : [parsed];
-} catch {
-  versions = [];
-}
-
-const pattern = new RegExp(`^${stable.replace(/\./g, '\\.')}-canary\\.(\\d+)$`);
-let max = -1;
-
-for (const version of versions) {
-  const match = version.match(pattern);
-  if (!match) continue;
-  max = Math.max(max, Number(match[1]));
-}
-
-process.stdout.write(`${stable}-canary.${max + 1}`);
-NODE
-}
-
-release_branch_name() {
-  printf 'release/%s\n' "$1"
-}
-
-release_notes_file() {
-  printf '%s/releases/v%s.md\n' "$REPO_ROOT" "$1"
-}
-
-default_release_worktree_path() {
-  local version="$1"
-  local parent_dir
-  local repo_name
-
-  parent_dir="$(cd "$REPO_ROOT/.." && pwd)"
-  repo_name="$(basename "$REPO_ROOT")"
-  printf '%s/%s-release-%s\n' "$parent_dir" "$repo_name" "$version"
-}
-
-git_current_branch() {
-  git -C "$REPO_ROOT" symbolic-ref --quiet --short HEAD 2>/dev/null || true
-}
-
-git_local_branch_exists() {
-  git -C "$REPO_ROOT" show-ref --verify --quiet "refs/heads/$1"
-}
-
-git_remote_branch_exists() {
-  git -C "$REPO_ROOT" ls-remote --exit-code --heads "$2" "refs/heads/$1" >/dev/null 2>&1
-}
-
-git_local_tag_exists() {
-  git -C "$REPO_ROOT" show-ref --verify --quiet "refs/tags/$1"
-}
-
-git_remote_tag_exists() {
-  git -C "$REPO_ROOT" ls-remote --exit-code --tags "$2" "refs/tags/$1" >/dev/null 2>&1
-}
-
-npm_version_exists() {
-  local version="$1"
-  local resolved
-
-  resolved="$(npm view "paperclipai@${version}" version 2>/dev/null || true)"
-  [ "$resolved" = "$version" ]
-}
-
-require_clean_worktree() {
-  if [ -n "$(git -C "$REPO_ROOT" status --porcelain)" ]; then
-    release_fail "working tree is not clean. Commit, stash, or remove changes before releasing."
-  fi
-}
-
-git_worktree_path_for_branch() {
-  local branch_ref="refs/heads/$1"
-
-  git -C "$REPO_ROOT" worktree list --porcelain | awk -v branch_ref="$branch_ref" '
-    $1 == "worktree" { path = substr($0, 10) }
-    $1 == "branch" && $2 == branch_ref { print path; exit }
-  '
-}
-
-path_is_worktree_for_branch() {
-  local path="$1"
-  local branch="$2"
-  local current_branch
-
-  [ -d "$path" ] || return 1
-  current_branch="$(git -C "$path" symbolic-ref --quiet --short HEAD 2>/dev/null || true)"
-  [ "$current_branch" = "$branch" ]
-}
-
-ensure_release_branch_for_version() {
-  local stable_version="$1"
-  local current_branch
-  local expected_branch
-
-  current_branch="$(git_current_branch)"
-  expected_branch="$(release_branch_name "$stable_version")"
-
-  if [ -z "$current_branch" ]; then
-    release_fail "release work must run from branch $expected_branch, but HEAD is detached."
-  fi
-
-  if [ "$current_branch" != "$expected_branch" ]; then
-    release_fail "release work must run from branch $expected_branch, but current branch is $current_branch."
-  fi
-}
-
-stable_release_exists_anywhere() {
-  local stable_version="$1"
-  local remote="$2"
-  local tag="v$stable_version"
-
-  git_local_tag_exists "$tag" || git_remote_tag_exists "$tag" "$remote" || npm_version_exists "$stable_version"
-}
-
-release_train_is_frozen() {
-  stable_release_exists_anywhere "$1" "$2"
-}

scripts/release-preflight.sh

@@ -2,8 +2,6 @@
 set -euo pipefail
 
 REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
-# shellcheck source=./release-lib.sh
-. "$REPO_ROOT/scripts/release-lib.sh"
 export GIT_PAGER=cat
 
 channel=""
@@ -20,9 +18,7 @@ Examples:
 
 What it does:
   - verifies the git worktree is clean, including untracked files
-  - verifies you are on the matching release/X.Y.Z branch
   - shows the last stable tag and the target version(s)
-  - shows the git/npm/GitHub release-train state
   - shows commits since the last stable tag
   - highlights migration/schema/breaking-change signals
   - runs the verification gate:
@@ -67,19 +63,79 @@ if [[ ! "$bump_type" =~ ^(patch|minor|major)$ ]]; then
   exit 1
 fi
 
-RELEASE_REMOTE="$(resolve_release_remote)"
-fetch_release_remote "$RELEASE_REMOTE"
+compute_bumped_version() {
+  node - "$1" "$2" <<'NODE'
+const current = process.argv[2];
+const bump = process.argv[3];
+const match = current.match(/^(\d+)\.(\d+)\.(\d+)$/);
+
+if (!match) {
+  throw new Error(`invalid semver version: ${current}`);
+}
+
+let [major, minor, patch] = match.slice(1).map(Number);
+
+if (bump === 'patch') {
+  patch += 1;
+} else if (bump === 'minor') {
+  minor += 1;
+  patch = 0;
+} else if (bump === 'major') {
+  major += 1;
+  minor = 0;
+  patch = 0;
+} else {
+  throw new Error(`unsupported bump type: ${bump}`);
+}
+
+process.stdout.write(`${major}.${minor}.${patch}`);
+NODE
+}
+
+next_canary_version() {
+  local stable_version="$1"
+  local versions_json
+
+  versions_json="$(npm view paperclipai versions --json 2>/dev/null || echo '[]')"
+
+  node - "$stable_version" "$versions_json" <<'NODE'
+const stable = process.argv[2];
+const versionsArg = process.argv[3];
+
+let versions = [];
+try {
+  const parsed = JSON.parse(versionsArg);
+  versions = Array.isArray(parsed) ? parsed : [parsed];
+} catch {
+  versions = [];
+}
+
+const pattern = new RegExp(`^${stable.replace(/\./g, '\\.')}-canary\\.(\\d+)$`);
+let max = -1;
+
+for (const version of versions) {
+  const match = version.match(pattern);
+  if (!match) continue;
+  max = Math.max(max, Number(match[1]));
+}
+
+process.stdout.write(`${stable}-canary.${max + 1}`);
+NODE
+}
+
+LAST_STABLE_TAG="$(git -C "$REPO_ROOT" tag --list 'v*' --sort=-version:refname | head -1)"
+CURRENT_STABLE_VERSION="${LAST_STABLE_TAG#v}"
+if [ -z "$CURRENT_STABLE_VERSION" ]; then
+  CURRENT_STABLE_VERSION="0.0.0"
+fi
 
-LAST_STABLE_TAG="$(get_last_stable_tag)"
-CURRENT_STABLE_VERSION="$(get_current_stable_version)"
 TARGET_STABLE_VERSION="$(compute_bumped_version "$CURRENT_STABLE_VERSION" "$bump_type")"
 TARGET_CANARY_VERSION="$(next_canary_version "$TARGET_STABLE_VERSION")"
-EXPECTED_RELEASE_BRANCH="$(release_branch_name "$TARGET_STABLE_VERSION")"
-CURRENT_BRANCH="$(git_current_branch)"
-RELEASE_TAG="v$TARGET_STABLE_VERSION"
-NOTES_FILE="$(release_notes_file "$TARGET_STABLE_VERSION")"
 
-require_clean_worktree
+if [ -n "$(git -C "$REPO_ROOT" status --porcelain)" ]; then
+  echo "Error: working tree is not clean. Commit, stash, or remove changes before releasing." >&2
+  exit 1
+fi
 
 if [ "$TARGET_STABLE_VERSION" = "$CURRENT_STABLE_VERSION" ]; then
   echo "Error: next stable version matches the current stable version." >&2
@@ -91,41 +147,10 @@ if [[ "$TARGET_CANARY_VERSION" == "${CURRENT_STABLE_VERSION}-canary."* ]]; then
   exit 1
 fi
 
-ensure_release_branch_for_version "$TARGET_STABLE_VERSION"
-
-REMOTE_BRANCH_EXISTS="no"
-REMOTE_TAG_EXISTS="no"
-LOCAL_TAG_EXISTS="no"
-NPM_STABLE_EXISTS="no"
-
-if git_remote_branch_exists "$EXPECTED_RELEASE_BRANCH" "$RELEASE_REMOTE"; then
-  REMOTE_BRANCH_EXISTS="yes"
-fi
-
-if git_local_tag_exists "$RELEASE_TAG"; then
-  LOCAL_TAG_EXISTS="yes"
-fi
-
-if git_remote_tag_exists "$RELEASE_TAG" "$RELEASE_REMOTE"; then
-  REMOTE_TAG_EXISTS="yes"
-fi
-
-if npm_version_exists "$TARGET_STABLE_VERSION"; then
-  NPM_STABLE_EXISTS="yes"
-fi
-
-if [ "$LOCAL_TAG_EXISTS" = "yes" ] || [ "$REMOTE_TAG_EXISTS" = "yes" ] || [ "$NPM_STABLE_EXISTS" = "yes" ]; then
-  echo "Error: release train $EXPECTED_RELEASE_BRANCH is frozen because $RELEASE_TAG already exists locally, remotely, or version $TARGET_STABLE_VERSION is already on npm." >&2
-  exit 1
-fi
-
 echo ""
 echo "==> Release preflight"
-echo "  Remote: $RELEASE_REMOTE"
 echo "  Channel: $channel"
 echo "  Bump: $bump_type"
-echo "  Current branch: ${CURRENT_BRANCH:-<detached>}"
-echo "  Expected branch: $EXPECTED_RELEASE_BRANCH"
 echo "  Last stable tag: ${LAST_STABLE_TAG:-<none>}"
 echo "  Current stable version: $CURRENT_STABLE_VERSION"
 echo "  Next stable version: $TARGET_STABLE_VERSION"
@@ -137,23 +162,6 @@ fi
 echo ""
 echo "==> Working tree"
 echo "  ✓ Clean"
-echo "  ✓ Branch matches release train"
-
-echo ""
-echo "==> Release train state"
-echo "  Remote branch exists: $REMOTE_BRANCH_EXISTS"
-echo "  Local stable tag exists: $LOCAL_TAG_EXISTS"
-echo "  Remote stable tag exists: $REMOTE_TAG_EXISTS"
-echo "  Stable version on npm: $NPM_STABLE_EXISTS"
-if [ -f "$NOTES_FILE" ]; then
-  echo "  Release notes: present at $NOTES_FILE"
-else
-  echo "  Release notes: missing at $NOTES_FILE"
-fi
-
-if [ "$REMOTE_BRANCH_EXISTS" = "no" ]; then
-  echo "  Warning: remote branch $EXPECTED_RELEASE_BRANCH does not exist on $RELEASE_REMOTE yet."
-fi
 
 echo ""
 echo "==> Commits since last stable tag"
@@ -185,10 +193,8 @@ pnpm build
 
 echo ""
 echo "==> Release preflight summary"
-echo "  Remote: $RELEASE_REMOTE"
 echo "  Channel: $channel"
 echo "  Bump: $bump_type"
-echo "  Release branch: $EXPECTED_RELEASE_BRANCH"
 echo "  Last stable tag: ${LAST_STABLE_TAG:-<none>}"
 echo "  Current stable version: $CURRENT_STABLE_VERSION"
 echo "  Next stable version: $TARGET_STABLE_VERSION"

scripts/release-start.sh

@@ -1,182 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
-# shellcheck source=./release-lib.sh
-. "$REPO_ROOT/scripts/release-lib.sh"
-
-dry_run=false
-push_branch=true
-bump_type=""
-worktree_path=""
-
-usage() {
-  cat <<'EOF'
-Usage:
-  ./scripts/release-start.sh <patch|minor|major> [--dry-run] [--no-push] [--worktree-dir PATH]
-
-Examples:
-  ./scripts/release-start.sh patch
-  ./scripts/release-start.sh minor --dry-run
-  ./scripts/release-start.sh major --worktree-dir ../paperclip-release-1.0.0
-
-What it does:
-  - fetches the release remote and tags
-  - computes the next stable version from the latest stable tag
-  - creates or resumes branch release/X.Y.Z
-  - creates or resumes a dedicated worktree for that branch
-  - pushes the release branch to the remote by default
-
-Notes:
-  - Stable publishes freeze a release train. If vX.Y.Z already exists locally,
-    remotely, or on npm, this script refuses to reuse release/X.Y.Z.
-  - Use --no-push only if you intentionally do not want the release branch on
-    GitHub yet.
-EOF
-}
-
-while [ $# -gt 0 ]; do
-  case "$1" in
-    --dry-run) dry_run=true ;;
-    --no-push) push_branch=false ;;
-    --worktree-dir)
-      shift
-      [ $# -gt 0 ] || release_fail "--worktree-dir requires a path."
-      worktree_path="$1"
-      ;;
-    -h|--help)
-      usage
-      exit 0
-      ;;
-    *)
-      if [ -n "$bump_type" ]; then
-        release_fail "only one bump type may be provided."
-      fi
-      bump_type="$1"
-      ;;
-  esac
-  shift
-done
-
-if [[ ! "$bump_type" =~ ^(patch|minor|major)$ ]]; then
-  usage
-  exit 1
-fi
-
-release_remote="$(resolve_release_remote)"
-fetch_release_remote "$release_remote"
-
-last_stable_tag="$(get_last_stable_tag)"
-current_stable_version="$(get_current_stable_version)"
-target_stable_version="$(compute_bumped_version "$current_stable_version" "$bump_type")"
-target_canary_version="$(next_canary_version "$target_stable_version")"
-release_branch="$(release_branch_name "$target_stable_version")"
-release_tag="v$target_stable_version"
-
-if [ -z "$worktree_path" ]; then
-  worktree_path="$(default_release_worktree_path "$target_stable_version")"
-fi
-
-if stable_release_exists_anywhere "$target_stable_version" "$release_remote"; then
-  release_fail "release train $release_branch is frozen because $release_tag already exists locally, remotely, or version $target_stable_version is already on npm."
-fi
-
-branch_exists_local=false
-branch_exists_remote=false
-branch_worktree_path=""
-created_worktree=false
-created_branch=false
-pushed_branch=false
-
-if git_local_branch_exists "$release_branch"; then
-  branch_exists_local=true
-fi
-
-if git_remote_branch_exists "$release_branch" "$release_remote"; then
-  branch_exists_remote=true
-fi
-
-branch_worktree_path="$(git_worktree_path_for_branch "$release_branch")"
-if [ -n "$branch_worktree_path" ]; then
-  worktree_path="$branch_worktree_path"
-fi
-
-if [ -e "$worktree_path" ] && ! path_is_worktree_for_branch "$worktree_path" "$release_branch"; then
-  release_fail "path $worktree_path already exists and is not a worktree for $release_branch."
-fi
-
-if [ -z "$branch_worktree_path" ]; then
-  if [ "$dry_run" = true ]; then
-    if [ "$branch_exists_local" = true ] || [ "$branch_exists_remote" = true ]; then
-      release_info "[dry-run] Would add worktree $worktree_path for existing branch $release_branch"
-    else
-      release_info "[dry-run] Would create branch $release_branch from $release_remote/master"
-      release_info "[dry-run] Would add worktree $worktree_path"
-    fi
-  else
-    if [ "$branch_exists_local" = true ]; then
-      git -C "$REPO_ROOT" worktree add "$worktree_path" "$release_branch"
-    elif [ "$branch_exists_remote" = true ]; then
-      git -C "$REPO_ROOT" branch --track "$release_branch" "$release_remote/$release_branch"
-      git -C "$REPO_ROOT" worktree add "$worktree_path" "$release_branch"
-      created_branch=true
-    else
-      git -C "$REPO_ROOT" worktree add -b "$release_branch" "$worktree_path" "$release_remote/master"
-      created_branch=true
-    fi
-    created_worktree=true
-  fi
-fi
-
-if [ "$dry_run" = false ] && [ "$push_branch" = true ] && [ "$branch_exists_remote" = false ]; then
-  git -C "$worktree_path" push -u "$release_remote" "$release_branch"
-  pushed_branch=true
-fi
-
-if [ "$dry_run" = false ] && [ "$branch_exists_remote" = true ]; then
-  git -C "$worktree_path" branch --set-upstream-to "$release_remote/$release_branch" "$release_branch" >/dev/null 2>&1 || true
-fi
-
-release_info ""
-release_info "==> Release train"
-release_info "  Remote: $release_remote"
-release_info "  Last stable tag: ${last_stable_tag:-<none>}"
-release_info "  Current stable version: $current_stable_version"
-release_info "  Bump: $bump_type"
-release_info "  Target stable version: $target_stable_version"
-release_info "  Next canary version: $target_canary_version"
-release_info "  Branch: $release_branch"
-release_info "  Tag (reserved until stable publish): $release_tag"
-release_info "  Worktree: $worktree_path"
-release_info "  Release notes path: $worktree_path/releases/v${target_stable_version}.md"
-
-release_info ""
-release_info "==> Status"
-if [ -n "$branch_worktree_path" ]; then
-  release_info "  ✓ Reusing existing worktree for $release_branch"
-elif [ "$dry_run" = true ]; then
-  release_info "  ✓ Dry run only; no branch or worktree created"
-else
-  [ "$created_branch" = true ] && release_info "  ✓ Created branch $release_branch"
-  [ "$created_worktree" = true ] && release_info "  ✓ Created worktree $worktree_path"
-fi
-
-if [ "$branch_exists_remote" = true ]; then
-  release_info "  ✓ Remote branch already exists on $release_remote"
-elif [ "$dry_run" = true ] && [ "$push_branch" = true ]; then
-  release_info "  [dry-run] Would push $release_branch to $release_remote"
-elif [ "$push_branch" = true ] && [ "$pushed_branch" = true ]; then
-  release_info "  ✓ Pushed $release_branch to $release_remote"
-elif [ "$push_branch" = false ]; then
-  release_warn "release branch was not pushed. Stable publish will later refuse until the branch exists on $release_remote."
-fi
-
-release_info ""
-release_info "Next steps:"
-release_info "  cd $worktree_path"
-release_info "  Draft or update releases/v${target_stable_version}.md"
-release_info "  ./scripts/release-preflight.sh canary $bump_type"
-release_info "  ./scripts/release.sh $bump_type --canary"
-release_info ""
-release_info "Merge rule:"
-release_info "  Merge $release_branch back to master without squash or rebase so tag $release_tag remains reachable from master."

scripts/release.sh

@@ -15,11 +15,10 @@ set -euo pipefail
 # npm dist-tag "canary". Stable releases publish 1.2.3 under "latest".
 
 REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
-# shellcheck source=./release-lib.sh
-. "$REPO_ROOT/scripts/release-lib.sh"
 CLI_DIR="$REPO_ROOT/cli"
 TEMP_CHANGESET_FILE="$REPO_ROOT/.changeset/release-bump.md"
 TEMP_PRE_FILE="$REPO_ROOT/.changeset/pre.json"
+PUBLISH_REMOTE="${PUBLISH_REMOTE:-public-gh}"
 
 dry_run=false
 canary=false
@@ -42,7 +41,6 @@ Notes:
   - Canary publishes prerelease versions like 1.2.3-canary.0 under the npm
     dist-tag "canary".
   - Stable publishes 1.2.3 under the npm dist-tag "latest".
-  - Run this from branch release/X.Y.Z matching the computed target version.
   - Dry runs leave the working tree clean.
 EOF
 }
@@ -75,6 +73,15 @@ if [[ ! "$bump_type" =~ ^(patch|minor|major)$ ]]; then
   exit 1
 fi
 
+info() {
+  echo "$@"
+}
+
+fail() {
+  echo "Error: $*" >&2
+  exit 1
+}
+
 restore_publish_artifacts() {
   if [ -f "$CLI_DIR/package.dev.json" ]; then
     mv "$CLI_DIR/package.dev.json" "$CLI_DIR/package.json"
@@ -123,22 +130,28 @@ set_cleanup_trap() {
   trap cleanup_release_state EXIT
 }
 
+require_clean_worktree() {
+  if [ -n "$(git -C "$REPO_ROOT" status --porcelain)" ]; then
+    fail "working tree is not clean. Commit, stash, or remove changes before releasing."
+  fi
+}
+
 require_npm_publish_auth() {
   if [ "$dry_run" = true ]; then
     return
   fi
 
   if npm whoami >/dev/null 2>&1; then
-    release_info "  ✓ Logged in to npm as $(npm whoami)"
+    info "  ✓ Logged in to npm as $(npm whoami)"
     return
   fi
 
   if [ "${GITHUB_ACTIONS:-}" = "true" ]; then
-    release_info "  ✓ npm publish auth will be provided by GitHub Actions trusted publishing"
+    info "  ✓ npm publish auth will be provided by GitHub Actions trusted publishing"
     return
   fi
 
-  release_fail "npm publish auth is not available. Use 'npm login' locally or run from the GitHub release workflow."
+  fail "npm publish auth is not available. Use 'npm login' locally or run from the GitHub release workflow."
 }
 
 list_public_package_info() {
@@ -189,6 +202,66 @@ for (const [dir, name] of rows) {
 NODE
 }
 
+compute_bumped_version() {
+  node - "$1" "$2" <<'NODE'
+const current = process.argv[2];
+const bump = process.argv[3];
+const match = current.match(/^(\d+)\.(\d+)\.(\d+)$/);
+
+if (!match) {
+  throw new Error(`invalid semver version: ${current}`);
+}
+
+let [major, minor, patch] = match.slice(1).map(Number);
+
+if (bump === 'patch') {
+  patch += 1;
+} else if (bump === 'minor') {
+  minor += 1;
+  patch = 0;
+} else if (bump === 'major') {
+  major += 1;
+  minor = 0;
+  patch = 0;
+} else {
+  throw new Error(`unsupported bump type: ${bump}`);
+}
+
+process.stdout.write(`${major}.${minor}.${patch}`);
+NODE
+}
+
+next_canary_version() {
+  local stable_version="$1"
+  local versions_json
+
+  versions_json="$(npm view paperclipai versions --json 2>/dev/null || echo '[]')"
+
+  node - "$stable_version" "$versions_json" <<'NODE'
+const stable = process.argv[2];
+const versionsArg = process.argv[3];
+
+let versions = [];
+try {
+  const parsed = JSON.parse(versionsArg);
+  versions = Array.isArray(parsed) ? parsed : [parsed];
+} catch {
+  versions = [];
+}
+
+const pattern = new RegExp(`^${stable.replace(/\./g, '\\.')}-canary\\.(\\d+)$`);
+let max = -1;
+
+for (const version of versions) {
+  const match = version.match(pattern);
+  if (!match) continue;
+  max = Math.max(max, Number(match[1]));
+}
+
+process.stdout.write(`${stable}-canary.${max + 1}`);
+NODE
+}
+
 replace_version_string() {
   local from_version="$1"
   local to_version="$2"
@@ -239,55 +312,25 @@ for (const relFile of extraFiles) {
 NODE
 }
 
-PUBLISH_REMOTE="$(resolve_release_remote)"
-fetch_release_remote "$PUBLISH_REMOTE"
-
-LAST_STABLE_TAG="$(get_last_stable_tag)"
-CURRENT_STABLE_VERSION="$(get_current_stable_version)"
+LAST_STABLE_TAG="$(git -C "$REPO_ROOT" tag --list 'v*' --sort=-version:refname | head -1)"
+CURRENT_STABLE_VERSION="${LAST_STABLE_TAG#v}"
+if [ -z "$CURRENT_STABLE_VERSION" ]; then
+  CURRENT_STABLE_VERSION="0.0.0"
+fi
 
 TARGET_STABLE_VERSION="$(compute_bumped_version "$CURRENT_STABLE_VERSION" "$bump_type")"
 TARGET_PUBLISH_VERSION="$TARGET_STABLE_VERSION"
-CURRENT_BRANCH="$(git_current_branch)"
-EXPECTED_RELEASE_BRANCH="$(release_branch_name "$TARGET_STABLE_VERSION")"
-NOTES_FILE="$(release_notes_file "$TARGET_STABLE_VERSION")"
-RELEASE_TAG="v$TARGET_STABLE_VERSION"
 
 if [ "$canary" = true ]; then
   TARGET_PUBLISH_VERSION="$(next_canary_version "$TARGET_STABLE_VERSION")"
 fi
 
 if [ "$TARGET_STABLE_VERSION" = "$CURRENT_STABLE_VERSION" ]; then
-  release_fail "next stable version matches the current stable version. Refusing to publish."
+  fail "next stable version matches the current stable version. Refusing to publish."
 fi
 
 if [[ "$TARGET_PUBLISH_VERSION" == "${CURRENT_STABLE_VERSION}-canary."* ]]; then
-  release_fail "canary versions must be derived from the next stable version, never ${CURRENT_STABLE_VERSION}-canary.N."
-fi
-
-require_clean_worktree
-ensure_release_branch_for_version "$TARGET_STABLE_VERSION"
-
-if git_local_tag_exists "$RELEASE_TAG" || git_remote_tag_exists "$RELEASE_TAG" "$PUBLISH_REMOTE"; then
-  release_fail "release train $EXPECTED_RELEASE_BRANCH is frozen because tag $RELEASE_TAG already exists locally or on $PUBLISH_REMOTE."
-fi
-
-if npm_version_exists "$TARGET_STABLE_VERSION"; then
-  release_fail "stable version $TARGET_STABLE_VERSION is already published on npm. Refusing to reuse release train $EXPECTED_RELEASE_BRANCH."
-fi
-
-if [ "$canary" = false ] && [ ! -f "$NOTES_FILE" ]; then
-  release_fail "stable release notes file is required at $NOTES_FILE before publishing stable."
-fi
-
-if [ "$canary" = true ] && [ ! -f "$NOTES_FILE" ]; then
-  release_warn "stable release notes file is missing at $NOTES_FILE. Draft it before you finalize stable."
-fi
-
-if ! git_remote_branch_exists "$EXPECTED_RELEASE_BRANCH" "$PUBLISH_REMOTE"; then
-  if [ "$canary" = false ] && [ "$dry_run" = false ]; then
-    release_fail "remote branch $EXPECTED_RELEASE_BRANCH does not exist on $PUBLISH_REMOTE. Run ./scripts/release-start.sh $bump_type first or push the branch before stable publish."
-  fi
-  release_warn "remote branch $EXPECTED_RELEASE_BRANCH does not exist on $PUBLISH_REMOTE yet."
+  fail "canary versions must be derived from the next stable version, never ${CURRENT_STABLE_VERSION}-canary.N."
 fi
 
 PUBLIC_PACKAGE_INFO="$(list_public_package_info)"
@@ -295,36 +338,33 @@ PUBLIC_PACKAGE_NAMES="$(printf '%s\n' "$PUBLIC_PACKAGE_INFO" | cut -f2)"
 PUBLIC_PACKAGE_DIRS="$(printf '%s\n' "$PUBLIC_PACKAGE_INFO" | cut -f1)"
 
 if [ -z "$PUBLIC_PACKAGE_INFO" ]; then
-  release_fail "no public packages were found in the workspace."
+  fail "no public packages were found in the workspace."
 fi
 
-release_info ""
-release_info "==> Release plan"
-release_info "  Remote: $PUBLISH_REMOTE"
-release_info "  Current branch: ${CURRENT_BRANCH:-<detached>}"
-release_info "  Expected branch: $EXPECTED_RELEASE_BRANCH"
-release_info "  Last stable tag: ${LAST_STABLE_TAG:-<none>}"
-release_info "  Current stable version: $CURRENT_STABLE_VERSION"
+info ""
+info "==> Release plan"
+info "  Last stable tag: ${LAST_STABLE_TAG:-<none>}"
+info "  Current stable version: $CURRENT_STABLE_VERSION"
 if [ "$canary" = true ]; then
-  release_info "  Target stable version: $TARGET_STABLE_VERSION"
-  release_info "  Canary version: $TARGET_PUBLISH_VERSION"
-  release_info "  Guard: canary is derived from next stable version, not ${CURRENT_STABLE_VERSION}-canary.N"
+  info "  Target stable version: $TARGET_STABLE_VERSION"
+  info "  Canary version: $TARGET_PUBLISH_VERSION"
+  info "  Guard: canary is derived from next stable version, not ${CURRENT_STABLE_VERSION}-canary.N"
 else
-  release_info "  Stable version: $TARGET_STABLE_VERSION"
+  info "  Stable version: $TARGET_STABLE_VERSION"
 fi
 
-release_info ""
-release_info "==> Step 1/7: Preflight checks..."
-release_info "  ✓ Working tree is clean"
-release_info "  ✓ Branch matches release train"
+info ""
+info "==> Step 1/7: Preflight checks..."
+require_clean_worktree
+info "  ✓ Working tree is clean"
 require_npm_publish_auth
 
 if [ "$dry_run" = true ] || [ "$canary" = true ]; then
   set_cleanup_trap
 fi
 
-release_info ""
-release_info "==> Step 2/7: Creating release changeset..."
+info ""
+info "==> Step 2/7: Creating release changeset..."
 {
   echo "---"
   while IFS= read -r pkg_name; do
@@ -339,10 +379,10 @@ release_info "==> Step 2/7: Creating release changeset..."
     echo "Stable release preparation for $TARGET_STABLE_VERSION"
   fi
 } > "$TEMP_CHANGESET_FILE"
-release_info "  ✓ Created release changeset for $(printf '%s\n' "$PUBLIC_PACKAGE_NAMES" | sed '/^$/d' | wc -l | xargs) packages"
+info "  ✓ Created release changeset for $(printf '%s\n' "$PUBLIC_PACKAGE_NAMES" | sed '/^$/d' | wc -l | xargs) packages"
 
-release_info ""
-release_info "==> Step 3/7: Versioning packages..."
+info ""
+info "==> Step 3/7: Versioning packages..."
 cd "$REPO_ROOT"
 if [ "$canary" = true ]; then
   npx changeset pre enter canary
@@ -358,12 +398,12 @@ fi
 
 VERSION_IN_CLI_PACKAGE="$(node -e "console.log(require('$CLI_DIR/package.json').version)")"
 if [ "$VERSION_IN_CLI_PACKAGE" != "$TARGET_PUBLISH_VERSION" ]; then
-  release_fail "versioning drift detected. Expected $TARGET_PUBLISH_VERSION but found $VERSION_IN_CLI_PACKAGE."
+  fail "versioning drift detected. Expected $TARGET_PUBLISH_VERSION but found $VERSION_IN_CLI_PACKAGE."
 fi
-release_info "  ✓ Versioned workspace to $TARGET_PUBLISH_VERSION"
+info "  ✓ Versioned workspace to $TARGET_PUBLISH_VERSION"
 
-release_info ""
-release_info "==> Step 4/7: Building workspace artifacts..."
+info ""
+info "==> Step 4/7: Building workspace artifacts..."
 cd "$REPO_ROOT"
 pnpm build
 bash "$REPO_ROOT/scripts/prepare-server-ui-dist.sh"
@@ -371,49 +411,49 @@ for pkg_dir in server packages/adapters/claude-local packages/adapters/codex-loc
   rm -rf "$REPO_ROOT/$pkg_dir/skills"
   cp -r "$REPO_ROOT/skills" "$REPO_ROOT/$pkg_dir/skills"
 done
-release_info "  ✓ Workspace build complete"
+info "  ✓ Workspace build complete"
 
-release_info ""
-release_info "==> Step 5/7: Building publishable CLI bundle..."
+info ""
+info "==> Step 5/7: Building publishable CLI bundle..."
 "$REPO_ROOT/scripts/build-npm.sh" --skip-checks
-release_info "  ✓ CLI bundle ready"
+info "  ✓ CLI bundle ready"
 
-release_info ""
+info ""
 if [ "$dry_run" = true ]; then
-  release_info "==> Step 6/7: Previewing publish payloads (--dry-run)..."
+  info "==> Step 6/7: Previewing publish payloads (--dry-run)..."
   while IFS= read -r pkg_dir; do
     [ -z "$pkg_dir" ] && continue
-    release_info "  --- $pkg_dir ---"
+    info "  --- $pkg_dir ---"
     cd "$REPO_ROOT/$pkg_dir"
     npm pack --dry-run 2>&1 | tail -3
   done <<< "$PUBLIC_PACKAGE_DIRS"
   cd "$REPO_ROOT"
   if [ "$canary" = true ]; then
-    release_info "  [dry-run] Would publish ${TARGET_PUBLISH_VERSION} under dist-tag canary"
+    info "  [dry-run] Would publish ${TARGET_PUBLISH_VERSION} under dist-tag canary"
   else
-    release_info "  [dry-run] Would publish ${TARGET_PUBLISH_VERSION} under dist-tag latest"
+    info "  [dry-run] Would publish ${TARGET_PUBLISH_VERSION} under dist-tag latest"
   fi
 else
   if [ "$canary" = true ]; then
-    release_info "==> Step 6/7: Publishing canary to npm..."
+    info "==> Step 6/7: Publishing canary to npm..."
     npx changeset publish
-    release_info "  ✓ Published ${TARGET_PUBLISH_VERSION} under dist-tag canary"
+    info "  ✓ Published ${TARGET_PUBLISH_VERSION} under dist-tag canary"
   else
-    release_info "==> Step 6/7: Publishing stable release to npm..."
+    info "==> Step 6/7: Publishing stable release to npm..."
     npx changeset publish
-    release_info "  ✓ Published ${TARGET_PUBLISH_VERSION} under dist-tag latest"
+    info "  ✓ Published ${TARGET_PUBLISH_VERSION} under dist-tag latest"
   fi
 fi
 
-release_info ""
+info ""
 if [ "$dry_run" = true ]; then
-  release_info "==> Step 7/7: Cleaning up dry-run state..."
-  release_info "  ✓ Dry run leaves the working tree unchanged"
+  info "==> Step 7/7: Cleaning up dry-run state..."
+  info "  ✓ Dry run leaves the working tree unchanged"
 elif [ "$canary" = true ]; then
-  release_info "==> Step 7/7: Cleaning up canary state..."
-  release_info "  ✓ Canary state will be discarded after publish"
+  info "==> Step 7/7: Cleaning up canary state..."
+  info "  ✓ Canary state will be discarded after publish"
 else
-  release_info "==> Step 7/7: Finalizing stable release commit..."
+  info "==> Step 7/7: Finalizing stable release commit..."
   restore_publish_artifacts
 
   git -C "$REPO_ROOT" add -u .changeset packages server cli
@@ -423,24 +463,23 @@ else
 
   git -C "$REPO_ROOT" commit -m "chore: release v$TARGET_STABLE_VERSION"
   git -C "$REPO_ROOT" tag "v$TARGET_STABLE_VERSION"
-  release_info "  ✓ Created commit and tag v$TARGET_STABLE_VERSION"
+  info "  ✓ Created commit and tag v$TARGET_STABLE_VERSION"
 fi
 
-release_info ""
+info ""
 if [ "$dry_run" = true ]; then
   if [ "$canary" = true ]; then
-    release_info "Dry run complete for canary ${TARGET_PUBLISH_VERSION}."
+    info "Dry run complete for canary ${TARGET_PUBLISH_VERSION}."
   else
-    release_info "Dry run complete for stable v${TARGET_STABLE_VERSION}."
+    info "Dry run complete for stable v${TARGET_STABLE_VERSION}."
   fi
 elif [ "$canary" = true ]; then
-  release_info "Published canary ${TARGET_PUBLISH_VERSION}."
-  release_info "Install with: npx paperclipai@canary onboard"
-  release_info "Stable version remains: $CURRENT_STABLE_VERSION"
+  info "Published canary ${TARGET_PUBLISH_VERSION}."
+  info "Install with: npx paperclipai@canary onboard"
+  info "Stable version remains: $CURRENT_STABLE_VERSION"
 else
-  release_info "Published stable v${TARGET_STABLE_VERSION}."
-  release_info "Next steps:"
-  release_info "  git push ${PUBLISH_REMOTE} HEAD --follow-tags"
-  release_info "  ./scripts/create-github-release.sh $TARGET_STABLE_VERSION"
-  release_info "  Open a PR from ${EXPECTED_RELEASE_BRANCH} to master and merge without squash or rebase"
+  info "Published stable v${TARGET_STABLE_VERSION}."
+  info "Next steps:"
+  info "  git push ${PUBLISH_REMOTE} HEAD:master --follow-tags"
+  info "  ./scripts/create-github-release.sh $TARGET_STABLE_VERSION"
 fi

server/CHANGELOG.md

@@ -1,25 +1,5 @@
 # @paperclipai/server
 
-## 0.3.0
-
-### Minor Changes
-
-- Stable release preparation for 0.3.0
-
-### Patch Changes
-
-- Updated dependencies [6077ae6]
-- Updated dependencies
-  - @paperclipai/shared@0.3.0
-  - @paperclipai/adapter-utils@0.3.0
-  - @paperclipai/adapter-claude-local@0.3.0
-  - @paperclipai/adapter-codex-local@0.3.0
-  - @paperclipai/adapter-cursor-local@0.3.0
-  - @paperclipai/adapter-openclaw-gateway@0.3.0
-  - @paperclipai/adapter-opencode-local@0.3.0
-  - @paperclipai/adapter-pi-local@0.3.0
-  - @paperclipai/db@0.3.0
-
 ## 0.2.7
 
 ### Patch Changes

server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paperclipai/server",
-  "version": "0.3.0",
+  "version": "0.2.7",
   "type": "module",
   "exports": {
     ".": "./src/index.ts"
@@ -23,7 +23,7 @@
   ],
   "scripts": {
     "dev": "tsx src/index.ts",
-    "dev:watch": "cross-env PAPERCLIP_MIGRATION_PROMPT=never tsx watch --ignore ../ui/node_modules --ignore ../ui/.vite --ignore ../ui/dist src/index.ts",
+    "dev:watch": "PAPERCLIP_MIGRATION_PROMPT=never tsx watch --ignore ../ui/node_modules --ignore ../ui/.vite --ignore ../ui/dist src/index.ts",
     "prepare:ui-dist": "bash ../scripts/prepare-server-ui-dist.sh",
     "build": "tsc",
     "prepack": "pnpm run prepare:ui-dist",
@@ -64,7 +64,6 @@
     "@types/node": "^24.6.0",
     "@types/supertest": "^6.0.2",
     "@types/ws": "^8.18.1",
-    "cross-env": "^10.1.0",
     "supertest": "^7.0.0",
     "tsx": "^4.19.2",
     "typescript": "^5.7.3",

server/src/__tests__/approval-routes-idempotency.test.ts

@@ -1,110 +0,0 @@
-import express from "express";
-import request from "supertest";
-import { beforeEach, describe, expect, it, vi } from "vitest";
-import { approvalRoutes } from "../routes/approvals.js";
-import { errorHandler } from "../middleware/index.js";
-
-const mockApprovalService = vi.hoisted(() => ({
-  list: vi.fn(),
-  getById: vi.fn(),
-  create: vi.fn(),
-  approve: vi.fn(),
-  reject: vi.fn(),
-  requestRevision: vi.fn(),
-  resubmit: vi.fn(),
-  listComments: vi.fn(),
-  addComment: vi.fn(),
-}));
-
-const mockHeartbeatService = vi.hoisted(() => ({
-  wakeup: vi.fn(),
-}));
-
-const mockIssueApprovalService = vi.hoisted(() => ({
-  listIssuesForApproval: vi.fn(),
-  linkManyForApproval: vi.fn(),
-}));
-
-const mockSecretService = vi.hoisted(() => ({
-  normalizeHireApprovalPayloadForPersistence: vi.fn(),
-}));
-
-const mockLogActivity = vi.hoisted(() => vi.fn());
-
-vi.mock("../services/index.js", () => ({
-  approvalService: () => mockApprovalService,
-  heartbeatService: () => mockHeartbeatService,
-  issueApprovalService: () => mockIssueApprovalService,
-  logActivity: mockLogActivity,
-  secretService: () => mockSecretService,
-}));
-
-function createApp() {
-  const app = express();
-  app.use(express.json());
-  app.use((req, _res, next) => {
-    (req as any).actor = {
-      type: "board",
-      userId: "user-1",
-      companyIds: ["company-1"],
-      source: "session",
-      isInstanceAdmin: false,
-    };
-    next();
-  });
-  app.use("/api", approvalRoutes({} as any));
-  app.use(errorHandler);
-  return app;
-}
-
-describe("approval routes idempotent retries", () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-    mockHeartbeatService.wakeup.mockResolvedValue({ id: "wake-1" });
-    mockIssueApprovalService.listIssuesForApproval.mockResolvedValue([{ id: "issue-1" }]);
-    mockLogActivity.mockResolvedValue(undefined);
-  });
-
-  it("does not emit duplicate approval side effects when approve is already resolved", async () => {
-    mockApprovalService.approve.mockResolvedValue({
-      approval: {
-        id: "approval-1",
-        companyId: "company-1",
-        type: "hire_agent",
-        status: "approved",
-        payload: {},
-        requestedByAgentId: "agent-1",
-      },
-      applied: false,
-    });
-
-    const res = await request(createApp())
-      .post("/api/approvals/approval-1/approve")
-      .send({});
-
-    expect(res.status).toBe(200);
-    expect(mockIssueApprovalService.listIssuesForApproval).not.toHaveBeenCalled();
-    expect(mockHeartbeatService.wakeup).not.toHaveBeenCalled();
-    expect(mockLogActivity).not.toHaveBeenCalled();
-  });
-
-  it("does not emit duplicate rejection logs when reject is already resolved", async () => {
-    mockApprovalService.reject.mockResolvedValue({
-      approval: {
-        id: "approval-1",
-        companyId: "company-1",
-        type: "hire_agent",
-        status: "rejected",
-        payload: {},
-      },
-      applied: false,
-    });
-
-    const res = await request(createApp())
-      .post("/api/approvals/approval-1/reject")
-      .send({});
-
-    expect(res.status).toBe(200);
-    expect(mockLogActivity).not.toHaveBeenCalled();
-  });
-});

server/src/__tests__/approvals-service.test.ts

@@ -1,110 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
-import { approvalService } from "../services/approvals.js";
-
-const mockAgentService = vi.hoisted(() => ({
-  activatePendingApproval: vi.fn(),
-  create: vi.fn(),
-  terminate: vi.fn(),
-}));
-
-const mockNotifyHireApproved = vi.hoisted(() => vi.fn());
-
-vi.mock("../services/agents.js", () => ({
-  agentService: vi.fn(() => mockAgentService),
-}));
-
-vi.mock("../services/hire-hook.js", () => ({
-  notifyHireApproved: mockNotifyHireApproved,
-}));
-
-type ApprovalRecord = {
-  id: string;
-  companyId: string;
-  type: string;
-  status: string;
-  payload: Record<string, unknown>;
-  requestedByAgentId: string | null;
-};
-
-function createApproval(status: string): ApprovalRecord {
-  return {
-    id: "approval-1",
-    companyId: "company-1",
-    type: "hire_agent",
-    status,
-    payload: { agentId: "agent-1" },
-    requestedByAgentId: "requester-1",
-  };
-}
-
-function createDbStub(selectResults: ApprovalRecord[][], updateResults: ApprovalRecord[]) {
-  const selectWhere = vi.fn();
-  for (const result of selectResults) {
-    selectWhere.mockResolvedValueOnce(result);
-  }
-
-  const from = vi.fn(() => ({ where: selectWhere }));
-  const select = vi.fn(() => ({ from }));
-
-  const returning = vi.fn().mockResolvedValue(updateResults);
-  const updateWhere = vi.fn(() => ({ returning }));
-  const set = vi.fn(() => ({ where: updateWhere }));
-  const update = vi.fn(() => ({ set }));
-
-  return {
-    db: { select, update },
-    selectWhere,
-    returning,
-  };
-}
-
-describe("approvalService resolution idempotency", () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-    mockAgentService.activatePendingApproval.mockResolvedValue(undefined);
-    mockAgentService.create.mockResolvedValue({ id: "agent-1" });
-    mockAgentService.terminate.mockResolvedValue(undefined);
-    mockNotifyHireApproved.mockResolvedValue(undefined);
-  });
-
-  it("treats repeated approve retries as no-ops after another worker resolves the approval", async () => {
-    const dbStub = createDbStub(
-      [[createApproval("pending")], [createApproval("approved")]],
-      [],
-    );
-
-    const svc = approvalService(dbStub.db as any);
-    const result = await svc.approve("approval-1", "board", "ship it");
-
-    expect(result.applied).toBe(false);
-    expect(result.approval.status).toBe("approved");
-    expect(mockAgentService.activatePendingApproval).not.toHaveBeenCalled();
-    expect(mockNotifyHireApproved).not.toHaveBeenCalled();
-  });
-
-  it("treats repeated reject retries as no-ops after another worker resolves the approval", async () => {
-    const dbStub = createDbStub(
-      [[createApproval("pending")], [createApproval("rejected")]],
-      [],
-    );
-
-    const svc = approvalService(dbStub.db as any);
-    const result = await svc.reject("approval-1", "board", "not now");
-
-    expect(result.applied).toBe(false);
-    expect(result.approval.status).toBe("rejected");
-    expect(mockAgentService.terminate).not.toHaveBeenCalled();
-  });
-
-  it("still performs side effects when the resolution update is newly applied", async () => {
-    const approved = createApproval("approved");
-    const dbStub = createDbStub([[createApproval("pending")]], [approved]);
-
-    const svc = approvalService(dbStub.db as any);
-    const result = await svc.approve("approval-1", "board", "ship it");
-
-    expect(result.applied).toBe(true);
-    expect(mockAgentService.activatePendingApproval).toHaveBeenCalledWith("agent-1");
-    expect(mockNotifyHireApproved).toHaveBeenCalledTimes(1);
-  });
-});

server/src/__tests__/attachment-types.test.ts

@@ -1,97 +0,0 @@
-import { describe, it, expect } from "vitest";
-import {
-  parseAllowedTypes,
-  matchesContentType,
-  DEFAULT_ALLOWED_TYPES,
-} from "../attachment-types.js";
-
-describe("parseAllowedTypes", () => {
-  it("returns default image types when input is undefined", () => {
-    expect(parseAllowedTypes(undefined)).toEqual([...DEFAULT_ALLOWED_TYPES]);
-  });
-
-  it("returns default image types when input is empty string", () => {
-    expect(parseAllowedTypes("")).toEqual([...DEFAULT_ALLOWED_TYPES]);
-  });
-
-  it("parses comma-separated types", () => {
-    expect(parseAllowedTypes("image/*,application/pdf")).toEqual([
-      "image/*",
-      "application/pdf",
-    ]);
-  });
-
-  it("trims whitespace", () => {
-    expect(parseAllowedTypes(" image/png , application/pdf ")).toEqual([
-      "image/png",
-      "application/pdf",
-    ]);
-  });
-
-  it("lowercases entries", () => {
-    expect(parseAllowedTypes("Application/PDF")).toEqual(["application/pdf"]);
-  });
-
-  it("filters empty segments", () => {
-    expect(parseAllowedTypes("image/png,,application/pdf,")).toEqual([
-      "image/png",
-      "application/pdf",
-    ]);
-  });
-});
-
-describe("matchesContentType", () => {
-  it("matches exact types", () => {
-    const patterns = ["application/pdf", "image/png"];
-    expect(matchesContentType("application/pdf", patterns)).toBe(true);
-    expect(matchesContentType("image/png", patterns)).toBe(true);
-    expect(matchesContentType("text/plain", patterns)).toBe(false);
-  });
-
-  it("matches /* wildcard patterns", () => {
-    const patterns = ["image/*"];
-    expect(matchesContentType("image/png", patterns)).toBe(true);
-    expect(matchesContentType("image/jpeg", patterns)).toBe(true);
-    expect(matchesContentType("image/svg+xml", patterns)).toBe(true);
-    expect(matchesContentType("application/pdf", patterns)).toBe(false);
-  });
-
-  it("matches .* wildcard patterns", () => {
-    const patterns = ["application/vnd.openxmlformats-officedocument.*"];
-    expect(
-      matchesContentType(
-        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
-        patterns,
-      ),
-    ).toBe(true);
-    expect(
-      matchesContentType(
-        "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
-        patterns,
-      ),
-    ).toBe(true);
-    expect(matchesContentType("application/pdf", patterns)).toBe(false);
-  });
-
-  it("is case-insensitive", () => {
-    const patterns = ["application/pdf"];
-    expect(matchesContentType("APPLICATION/PDF", patterns)).toBe(true);
-    expect(matchesContentType("Application/Pdf", patterns)).toBe(true);
-  });
-
-  it("combines exact and wildcard patterns", () => {
-    const patterns = ["image/*", "application/pdf", "text/*"];
-    expect(matchesContentType("image/webp", patterns)).toBe(true);
-    expect(matchesContentType("application/pdf", patterns)).toBe(true);
-    expect(matchesContentType("text/csv", patterns)).toBe(true);
-    expect(matchesContentType("application/zip", patterns)).toBe(false);
-  });
-
-  it("handles plain * as allow-all wildcard", () => {
-    const patterns = ["*"];
-    expect(matchesContentType("image/png", patterns)).toBe(true);
-    expect(matchesContentType("application/pdf", patterns)).toBe(true);
-    expect(matchesContentType("text/plain", patterns)).toBe(true);
-    expect(matchesContentType("application/zip", patterns)).toBe(true);
-  });
-});

server/src/__tests__/codex-local-adapter-environment.test.ts

@@ -4,8 +4,6 @@ import os from "node:os";
 import path from "node:path";
 import { testEnvironment } from "@paperclipai/adapter-codex-local/server";
 
-const itWindows = process.platform === "win32" ? it : it.skip;
-
 describe("codex_local environment diagnostics", () => {
   it("creates a missing working directory when cwd is absolute", async () => {
     const cwd = path.join(
@@ -31,45 +29,4 @@ describe("codex_local environment diagnostics", () => {
     expect(stats.isDirectory()).toBe(true);
     await fs.rm(path.dirname(cwd), { recursive: true, force: true });
   });
-
-  itWindows("runs the hello probe when Codex is available via a Windows .cmd wrapper", async () => {
-    const root = path.join(
-      os.tmpdir(),
-      `paperclip-codex-local-probe-${Date.now()}-${Math.random().toString(16).slice(2)}`,
-    );
-    const binDir = path.join(root, "bin");
-    const cwd = path.join(root, "workspace");
-    const fakeCodex = path.join(binDir, "codex.cmd");
-    const script = [
-      "@echo off",
-      "echo {\"type\":\"thread.started\",\"thread_id\":\"test-thread\"}",
-      "echo {\"type\":\"item.completed\",\"item\":{\"type\":\"agent_message\",\"text\":\"hello\"}}",
-      "echo {\"type\":\"turn.completed\",\"usage\":{\"input_tokens\":1,\"cached_input_tokens\":0,\"output_tokens\":1}}",
-      "exit /b 0",
-      "",
-    ].join("\r\n");
-
-    try {
-      await fs.mkdir(binDir, { recursive: true });
-      await fs.writeFile(fakeCodex, script, "utf8");
-
-      const result = await testEnvironment({
-        companyId: "company-1",
-        adapterType: "codex_local",
-        config: {
-          command: "codex",
-          cwd,
-          env: {
-            OPENAI_API_KEY: "test-key",
-            PATH: `${binDir}${path.delimiter}${process.env.PATH ?? ""}`,
-          },
-        },
-      });
-
-      expect(result.status).toBe("pass");
-      expect(result.checks.some((check) => check.code === "codex_hello_probe_passed")).toBe(true);
-    } finally {
-      await fs.rm(root, { recursive: true, force: true });
-    }
-  });
 });

server/src/__tests__/execution-workspace-policy.test.ts

@@ -0,0 +1,137 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildExecutionWorkspaceAdapterConfig,
+  defaultIssueExecutionWorkspaceSettingsForProject,
+  parseIssueExecutionWorkspaceSettings,
+  parseProjectExecutionWorkspacePolicy,
+  resolveExecutionWorkspaceMode,
+} from "../services/execution-workspace-policy.ts";
+
+describe("execution workspace policy helpers", () => {
+  it("defaults new issue settings from enabled project policy", () => {
+    expect(
+      defaultIssueExecutionWorkspaceSettingsForProject({
+        enabled: true,
+        defaultMode: "isolated",
+      }),
+    ).toEqual({ mode: "isolated" });
+    expect(
+      defaultIssueExecutionWorkspaceSettingsForProject({
+        enabled: true,
+        defaultMode: "project_primary",
+      }),
+    ).toEqual({ mode: "project_primary" });
+    expect(defaultIssueExecutionWorkspaceSettingsForProject(null)).toBeNull();
+  });
+
+  it("prefers explicit issue mode over project policy and legacy overrides", () => {
+    expect(
+      resolveExecutionWorkspaceMode({
+        projectPolicy: { enabled: true, defaultMode: "project_primary" },
+        issueSettings: { mode: "isolated" },
+        legacyUseProjectWorkspace: false,
+      }),
+    ).toBe("isolated");
+  });
+
+  it("falls back to project policy before legacy project-workspace compatibility flag", () => {
+    expect(
+      resolveExecutionWorkspaceMode({
+        projectPolicy: { enabled: true, defaultMode: "isolated" },
+        issueSettings: null,
+        legacyUseProjectWorkspace: false,
+      }),
+    ).toBe("isolated");
+    expect(
+      resolveExecutionWorkspaceMode({
+        projectPolicy: null,
+        issueSettings: null,
+        legacyUseProjectWorkspace: false,
+      }),
+    ).toBe("agent_default");
+  });
+
+  it("applies project policy strategy and runtime defaults when isolation is enabled", () => {
+    const result = buildExecutionWorkspaceAdapterConfig({
+      agentConfig: {
+        workspaceStrategy: { type: "project_primary" },
+      },
+      projectPolicy: {
+        enabled: true,
+        defaultMode: "isolated",
+        workspaceStrategy: {
+          type: "git_worktree",
+          baseRef: "origin/main",
+        },
+        workspaceRuntime: {
+          services: [{ name: "web", command: "pnpm dev" }],
+        },
+      },
+      issueSettings: null,
+      mode: "isolated",
+      legacyUseProjectWorkspace: null,
+    });
+
+    expect(result.workspaceStrategy).toEqual({
+      type: "git_worktree",
+      baseRef: "origin/main",
+    });
+    expect(result.workspaceRuntime).toEqual({
+      services: [{ name: "web", command: "pnpm dev" }],
+    });
+  });
+
+  it("clears managed workspace strategy when issue opts out to project primary or agent default", () => {
+    const baseConfig = {
+      workspaceStrategy: { type: "git_worktree", branchTemplate: "{{issue.identifier}}" },
+      workspaceRuntime: { services: [{ name: "web" }] },
+    };
+
+    expect(
+      buildExecutionWorkspaceAdapterConfig({
+        agentConfig: baseConfig,
+        projectPolicy: { enabled: true, defaultMode: "isolated" },
+        issueSettings: { mode: "project_primary" },
+        mode: "project_primary",
+        legacyUseProjectWorkspace: null,
+      }).workspaceStrategy,
+    ).toBeUndefined();
+
+    const agentDefault = buildExecutionWorkspaceAdapterConfig({
+      agentConfig: baseConfig,
+      projectPolicy: null,
+      issueSettings: { mode: "agent_default" },
+      mode: "agent_default",
+      legacyUseProjectWorkspace: null,
+    });
+    expect(agentDefault.workspaceStrategy).toBeUndefined();
+    expect(agentDefault.workspaceRuntime).toBeUndefined();
+  });
+
+  it("parses persisted JSON payloads into typed project and issue workspace settings", () => {
+    expect(
+      parseProjectExecutionWorkspacePolicy({
+        enabled: true,
+        defaultMode: "isolated",
+        workspaceStrategy: {
+          type: "git_worktree",
+          worktreeParentDir: ".paperclip/worktrees",
+        },
+      }),
+    ).toEqual({
+      enabled: true,
+      defaultMode: "isolated",
+      workspaceStrategy: {
+        type: "git_worktree",
+        worktreeParentDir: ".paperclip/worktrees",
+      },
+    });
+    expect(
+      parseIssueExecutionWorkspaceSettings({
+        mode: "project_primary",
+      }),
+    ).toEqual({
+      mode: "project_primary",
+    });
+  });
+});

server/src/__tests__/openclaw-gateway-adapter.test.ts

@@ -2,7 +2,10 @@ import { afterEach, describe, expect, it } from "vitest";
 import { createServer } from "node:http";
 import { WebSocketServer } from "ws";
 import { execute, testEnvironment } from "@paperclipai/adapter-openclaw-gateway/server";
-import { parseOpenClawGatewayStdoutLine } from "@paperclipai/adapter-openclaw-gateway/ui";
+import {
+  buildOpenClawGatewayConfig,
+  parseOpenClawGatewayStdoutLine,
+} from "@paperclipai/adapter-openclaw-gateway/ui";
 import type { AdapterExecutionContext } from "@paperclipai/adapter-utils";
 
 function buildContext(
@@ -36,7 +39,9 @@ function buildContext(
   };
 }
 
-async function createMockGatewayServer() {
+async function createMockGatewayServer(options?: {
+  waitPayload?: Record<string, unknown>;
+}) {
   const server = createServer();
   const wss = new WebSocketServer({ server });
 
@@ -136,7 +141,7 @@ async function createMockGatewayServer() {
             type: "res",
             id: frame.id,
             ok: true,
-            payload: {
+            payload: options?.waitPayload ?? {
               runId: frame.params?.runId,
               status: "ok",
               startedAt: 1,
@@ -412,6 +417,29 @@ describe("openclaw gateway adapter execute", () => {
             onLog: async (_stream, chunk) => {
               logs.push(chunk);
             },
+            context: {
+              taskId: "task-123",
+              issueId: "issue-123",
+              wakeReason: "issue_assigned",
+              issueIds: ["issue-123"],
+              paperclipWorkspace: {
+                cwd: "/tmp/worktrees/pap-123",
+                strategy: "git_worktree",
+                branchName: "pap-123-test",
+              },
+              paperclipWorkspaces: [
+                {
+                  id: "workspace-1",
+                  cwd: "/tmp/project",
+                },
+              ],
+              paperclipRuntimeServiceIntents: [
+                {
+                  name: "preview",
+                  lifecycle: "ephemeral",
+                },
+              ],
+            },
           },
         ),
       );
@@ -428,6 +456,33 @@ describe("openclaw gateway adapter execute", () => {
       expect(String(payload?.message ?? "")).toContain("wake now");
       expect(String(payload?.message ?? "")).toContain("PAPERCLIP_RUN_ID=run-123");
       expect(String(payload?.message ?? "")).toContain("PAPERCLIP_TASK_ID=task-123");
+      expect(payload?.paperclip).toEqual(
+        expect.objectContaining({
+          runId: "run-123",
+          companyId: "company-123",
+          agentId: "agent-123",
+          taskId: "task-123",
+          issueId: "issue-123",
+          workspace: expect.objectContaining({
+            cwd: "/tmp/worktrees/pap-123",
+            strategy: "git_worktree",
+          }),
+          workspaces: [
+            expect.objectContaining({
+              id: "workspace-1",
+              cwd: "/tmp/project",
+            }),
+          ],
+          workspaceRuntime: expect.objectContaining({
+            services: [
+              expect.objectContaining({
+                name: "preview",
+                lifecycle: "ephemeral",
+              }),
+            ],
+          }),
+        }),
+      );
 
       expect(logs.some((entry) => entry.includes("[openclaw-gateway:event] run=run-123 stream=assistant"))).toBe(true);
     } finally {
@@ -441,6 +496,54 @@ describe("openclaw gateway adapter execute", () => {
     expect(result.errorCode).toBe("openclaw_gateway_url_missing");
   });
 
+  it("returns adapter-managed runtime services from gateway result meta", async () => {
+    const gateway = await createMockGatewayServer({
+      waitPayload: {
+        runId: "run-123",
+        status: "ok",
+        startedAt: 1,
+        endedAt: 2,
+        meta: {
+          runtimeServices: [
+            {
+              name: "preview",
+              scopeType: "run",
+              url: "https://preview.example/run-123",
+              providerRef: "sandbox-123",
+              lifecycle: "ephemeral",
+            },
+          ],
+        },
+      },
+    });
+
+    try {
+      const result = await execute(
+        buildContext({
+          url: gateway.url,
+          headers: {
+            "x-openclaw-token": "gateway-token",
+          },
+          waitTimeoutMs: 2000,
+        }),
+      );
+
+      expect(result.exitCode).toBe(0);
+      expect(result.runtimeServices).toEqual([
+        expect.objectContaining({
+          serviceName: "preview",
+          scopeType: "run",
+          url: "https://preview.example/run-123",
+          providerRef: "sandbox-123",
+          lifecycle: "ephemeral",
+          status: "running",
+        }),
+      ]);
+    } finally {
+      await gateway.close();
+    }
+  });
+
   it("auto-approves pairing once and retries the run", async () => {
     const gateway = await createMockGatewayServerWithPairing();
     const logs: string[] = [];
@@ -479,6 +582,62 @@ describe("openclaw gateway adapter execute", () => {
   });
 });
 
+describe("openclaw gateway ui build config", () => {
+  it("parses payload template and runtime services json", () => {
+    const config = buildOpenClawGatewayConfig({
+      adapterType: "openclaw_gateway",
+      cwd: "",
+      promptTemplate: "",
+      model: "",
+      thinkingEffort: "",
+      chrome: false,
+      dangerouslySkipPermissions: false,
+      search: false,
+      dangerouslyBypassSandbox: false,
+      command: "",
+      args: "",
+      extraArgs: "",
+      envVars: "",
+      envBindings: {},
+      url: "wss://gateway.example/ws",
+      payloadTemplateJson: JSON.stringify({
+        agentId: "remote-agent-123",
+        metadata: { team: "platform" },
+      }),
+      runtimeServicesJson: JSON.stringify({
+        services: [
+          {
+            name: "preview",
+            lifecycle: "shared",
+          },
+        ],
+      }),
+      bootstrapPrompt: "",
+      maxTurnsPerRun: 0,
+      heartbeatEnabled: true,
+      intervalSec: 300,
+    });
+
+    expect(config).toEqual(
+      expect.objectContaining({
+        url: "wss://gateway.example/ws",
+        payloadTemplate: {
+          agentId: "remote-agent-123",
+          metadata: { team: "platform" },
+        },
+        workspaceRuntime: {
+          services: [
+            {
+              name: "preview",
+              lifecycle: "shared",
+            },
+          ],
+        },
+      }),
+    );
+  });
+});
+
 describe("openclaw gateway testEnvironment", () => {
   it("reports missing url as failure", async () => {
     const result = await testEnvironment({

server/src/__tests__/workspace-runtime.test.ts

@@ -0,0 +1,300 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  ensureRuntimeServicesForRun,
+  normalizeAdapterManagedRuntimeServices,
+  realizeExecutionWorkspace,
+  releaseRuntimeServicesForRun,
+  type RealizedExecutionWorkspace,
+} from "../services/workspace-runtime.ts";
+
+const execFileAsync = promisify(execFile);
+const leasedRunIds = new Set<string>();
+
+async function runGit(cwd: string, args: string[]) {
+  await execFileAsync("git", args, { cwd });
+}
+
+async function createTempRepo() {
+  const repoRoot = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-worktree-repo-"));
+  await runGit(repoRoot, ["init"]);
+  await runGit(repoRoot, ["config", "user.email", "paperclip@example.com"]);
+  await runGit(repoRoot, ["config", "user.name", "Paperclip Test"]);
+  await fs.writeFile(path.join(repoRoot, "README.md"), "hello\n", "utf8");
+  await runGit(repoRoot, ["add", "README.md"]);
+  await runGit(repoRoot, ["commit", "-m", "Initial commit"]);
+  await runGit(repoRoot, ["checkout", "-B", "main"]);
+  return repoRoot;
+}
+
+function buildWorkspace(cwd: string): RealizedExecutionWorkspace {
+  return {
+    baseCwd: cwd,
+    source: "project_primary",
+    projectId: "project-1",
+    workspaceId: "workspace-1",
+    repoUrl: null,
+    repoRef: "HEAD",
+    strategy: "project_primary",
+    cwd,
+    branchName: null,
+    worktreePath: null,
+    warnings: [],
+    created: false,
+  };
+}
+
+afterEach(async () => {
+  await Promise.all(
+    Array.from(leasedRunIds).map(async (runId) => {
+      await releaseRuntimeServicesForRun(runId);
+      leasedRunIds.delete(runId);
+    }),
+  );
+});
+
+describe("realizeExecutionWorkspace", () => {
+  it("creates and reuses a git worktree for an issue-scoped branch", async () => {
+    const repoRoot = await createTempRepo();
+
+    const first = await realizeExecutionWorkspace({
+      base: {
+        baseCwd: repoRoot,
+        source: "project_primary",
+        projectId: "project-1",
+        workspaceId: "workspace-1",
+        repoUrl: null,
+        repoRef: "HEAD",
+      },
+      config: {
+        workspaceStrategy: {
+          type: "git_worktree",
+          branchTemplate: "{{issue.identifier}}-{{slug}}",
+        },
+      },
+      issue: {
+        id: "issue-1",
+        identifier: "PAP-447",
+        title: "Add Worktree Support",
+      },
+      agent: {
+        id: "agent-1",
+        name: "Codex Coder",
+        companyId: "company-1",
+      },
+    });
+
+    expect(first.strategy).toBe("git_worktree");
+    expect(first.created).toBe(true);
+    expect(first.branchName).toBe("PAP-447-add-worktree-support");
+    expect(first.cwd).toContain(path.join(".paperclip", "worktrees"));
+    await expect(fs.stat(path.join(first.cwd, ".git"))).resolves.toBeTruthy();
+
+    const second = await realizeExecutionWorkspace({
+      base: {
+        baseCwd: repoRoot,
+        source: "project_primary",
+        projectId: "project-1",
+        workspaceId: "workspace-1",
+        repoUrl: null,
+        repoRef: "HEAD",
+      },
+      config: {
+        workspaceStrategy: {
+          type: "git_worktree",
+          branchTemplate: "{{issue.identifier}}-{{slug}}",
+        },
+      },
+      issue: {
+        id: "issue-1",
+        identifier: "PAP-447",
+        title: "Add Worktree Support",
+      },
+      agent: {
+        id: "agent-1",
+        name: "Codex Coder",
+        companyId: "company-1",
+      },
+    });
+
+    expect(second.created).toBe(false);
+    expect(second.cwd).toBe(first.cwd);
+    expect(second.branchName).toBe(first.branchName);
+  });
+});
+
+describe("ensureRuntimeServicesForRun", () => {
+  it("reuses shared runtime services across runs and starts a new service after release", async () => {
+    const workspaceRoot = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-runtime-workspace-"));
+    const workspace = buildWorkspace(workspaceRoot);
+    const serviceCommand =
+      "node -e \"require('node:http').createServer((req,res)=>res.end('ok')).listen(Number(process.env.PORT), '127.0.0.1')\"";
+
+    const config = {
+      workspaceRuntime: {
+        services: [
+          {
+            name: "web",
+            command: serviceCommand,
+            port: { type: "auto" },
+            readiness: {
+              type: "http",
+              urlTemplate: "http://127.0.0.1:{{port}}",
+              timeoutSec: 10,
+              intervalMs: 100,
+            },
+            expose: {
+              type: "url",
+              urlTemplate: "http://127.0.0.1:{{port}}",
+            },
+            lifecycle: "shared",
+            reuseScope: "project_workspace",
+            stopPolicy: {
+              type: "on_run_finish",
+            },
+          },
+        ],
+      },
+    };
+
+    const run1 = "run-1";
+    const run2 = "run-2";
+    leasedRunIds.add(run1);
+    leasedRunIds.add(run2);
+
+    const first = await ensureRuntimeServicesForRun({
+      runId: run1,
+      agent: {
+        id: "agent-1",
+        name: "Codex Coder",
+        companyId: "company-1",
+      },
+      issue: null,
+      workspace,
+      config,
+      adapterEnv: {},
+    });
+
+    expect(first).toHaveLength(1);
+    expect(first[0]?.reused).toBe(false);
+    expect(first[0]?.url).toMatch(/^http:\/\/127\.0\.0\.1:\d+$/);
+    const response = await fetch(first[0]!.url!);
+    expect(await response.text()).toBe("ok");
+
+    const second = await ensureRuntimeServicesForRun({
+      runId: run2,
+      agent: {
+        id: "agent-1",
+        name: "Codex Coder",
+        companyId: "company-1",
+      },
+      issue: null,
+      workspace,
+      config,
+      adapterEnv: {},
+    });
+
+    expect(second).toHaveLength(1);
+    expect(second[0]?.reused).toBe(true);
+    expect(second[0]?.id).toBe(first[0]?.id);
+
+    await releaseRuntimeServicesForRun(run1);
+    leasedRunIds.delete(run1);
+    await releaseRuntimeServicesForRun(run2);
+    leasedRunIds.delete(run2);
+
+    const run3 = "run-3";
+    leasedRunIds.add(run3);
+    const third = await ensureRuntimeServicesForRun({
+      runId: run3,
+      agent: {
+        id: "agent-1",
+        name: "Codex Coder",
+        companyId: "company-1",
+      },
+      issue: null,
+      workspace,
+      config,
+      adapterEnv: {},
+    });
+
+    expect(third).toHaveLength(1);
+    expect(third[0]?.reused).toBe(false);
+    expect(third[0]?.id).not.toBe(first[0]?.id);
+  });
+});
+
+describe("normalizeAdapterManagedRuntimeServices", () => {
+  it("fills workspace defaults and derives stable ids for adapter-managed services", () => {
+    const workspace = buildWorkspace("/tmp/project");
+    const now = new Date("2026-03-09T12:00:00.000Z");
+
+    const first = normalizeAdapterManagedRuntimeServices({
+      adapterType: "openclaw_gateway",
+      runId: "run-1",
+      agent: {
+        id: "agent-1",
+        name: "Gateway Agent",
+        companyId: "company-1",
+      },
+      issue: {
+        id: "issue-1",
+        identifier: "PAP-447",
+        title: "Worktree support",
+      },
+      workspace,
+      reports: [
+        {
+          serviceName: "preview",
+          url: "https://preview.example/run-1",
+          providerRef: "sandbox-123",
+          scopeType: "run",
+        },
+      ],
+      now,
+    });
+
+    const second = normalizeAdapterManagedRuntimeServices({
+      adapterType: "openclaw_gateway",
+      runId: "run-1",
+      agent: {
+        id: "agent-1",
+        name: "Gateway Agent",
+        companyId: "company-1",
+      },
+      issue: {
+        id: "issue-1",
+        identifier: "PAP-447",
+        title: "Worktree support",
+      },
+      workspace,
+      reports: [
+        {
+          serviceName: "preview",
+          url: "https://preview.example/run-1",
+          providerRef: "sandbox-123",
+          scopeType: "run",
+        },
+      ],
+      now,
+    });
+
+    expect(first).toHaveLength(1);
+    expect(first[0]).toMatchObject({
+      companyId: "company-1",
+      projectId: "project-1",
+      projectWorkspaceId: "workspace-1",
+      issueId: "issue-1",
+      serviceName: "preview",
+      provider: "adapter_managed",
+      status: "running",
+      healthStatus: "healthy",
+      startedByRunId: "run-1",
+    });
+    expect(first[0]?.id).toBe(second[0]?.id);
+  });
+});

server/src/attachment-types.ts

@@ -1,68 +0,0 @@
-/**
- * Shared attachment content-type configuration.
- *
- * By default only image types are allowed.  Set the
- * `PAPERCLIP_ALLOWED_ATTACHMENT_TYPES` environment variable to a
- * comma-separated list of MIME types or wildcard patterns to expand the
- * allowed set.
- *
- * Examples:
- *   PAPERCLIP_ALLOWED_ATTACHMENT_TYPES=image/*,application/pdf
- *   PAPERCLIP_ALLOWED_ATTACHMENT_TYPES=image/*,application/pdf,text/*
- *
- * Supported pattern syntax:
- *   - Exact types:   "application/pdf"
- *   - Wildcards:     "image/*"  or  "application/vnd.openxmlformats-officedocument.*"
- */
-
-export const DEFAULT_ALLOWED_TYPES: readonly string[] = [
-  "image/png",
-  "image/jpeg",
-  "image/jpg",
-  "image/webp",
-  "image/gif",
-];
-
-/**
- * Parse a comma-separated list of MIME type patterns into a normalised array.
- * Returns the default image-only list when the input is empty or undefined.
- */
-export function parseAllowedTypes(raw: string | undefined): string[] {
-  if (!raw) return [...DEFAULT_ALLOWED_TYPES];
-  const parsed = raw
-    .split(",")
-    .map((s) => s.trim().toLowerCase())
-    .filter((s) => s.length > 0);
-  return parsed.length > 0 ? parsed : [...DEFAULT_ALLOWED_TYPES];
-}
-
-/**
- * Check whether `contentType` matches any entry in `allowedPatterns`.
- *
- * Supports exact matches ("application/pdf") and wildcard / prefix
- * patterns ("image/*", "application/vnd.openxmlformats-officedocument.*").
- */
-export function matchesContentType(contentType: string, allowedPatterns: string[]): boolean {
-  const ct = contentType.toLowerCase();
-  return allowedPatterns.some((pattern) => {
-    if (pattern === "*") return true;
-    if (pattern.endsWith("/*") || pattern.endsWith(".*")) {
-      return ct.startsWith(pattern.slice(0, -1));
-    }
-    return ct === pattern;
-  });
-}
-
-// ---------- Module-level singletons read once at startup ----------
-
-const allowedPatterns: string[] = parseAllowedTypes(
-  process.env.PAPERCLIP_ALLOWED_ATTACHMENT_TYPES,
-);
-
-/** Convenience wrapper using the process-level allowed list. */
-export function isAllowedContentType(contentType: string): boolean {
-  return matchesContentType(contentType, allowedPatterns);
-}
-
-export const MAX_ATTACHMENT_BYTES =
-  Number(process.env.PAPERCLIP_ATTACHMENT_MAX_BYTES) || 10 * 1024 * 1024;

server/src/index.ts

@@ -25,7 +25,7 @@ import { createApp } from "./app.js";
 import { loadConfig } from "./config.js";
 import { logger } from "./middleware/logger.js";
 import { setupLiveEventsWebSocketServer } from "./realtime/live-events-ws.js";
-import { heartbeatService } from "./services/index.js";
+import { heartbeatService, reconcilePersistedRuntimeServicesOnStartup } from "./services/index.js";
 import { createStorageServiceFromConfig } from "./storage/index.js";
 import { printStartupBanner } from "./startup-banner.js";
 import { getBoardClaimWarningUrl, initializeBoardClaimChallenge } from "./board-claim.js";
@@ -495,6 +495,19 @@ export async function startServer(): Promise<StartedServer> {
     deploymentMode: config.deploymentMode,
     resolveSessionFromHeaders,
   });
+
+  void reconcilePersistedRuntimeServicesOnStartup(db as any)
+    .then((result) => {
+      if (result.reconciled > 0) {
+        logger.warn(
+          { reconciled: result.reconciled },
+          "reconciled persisted runtime services from a previous server process",
+        );
+      }
+    })
+    .catch((err) => {
+      logger.error({ err }, "startup reconciliation of persisted runtime services failed");
+    });
   
   if (config.heartbeatSchedulerEnabled) {
     const heartbeat = heartbeatService(db as any);
@@ -503,7 +516,7 @@ export async function startServer(): Promise<StartedServer> {
     void heartbeat.reapOrphanedRuns().catch((err) => {
       logger.error({ err }, "startup reap of orphaned heartbeat runs failed");
     });
-  
+
     setInterval(() => {
       void heartbeat
         .tickTimers(new Date())

server/src/routes/approvals.ts

@@ -121,92 +121,85 @@ export function approvalRoutes(db: Db) {
   router.post("/approvals/:id/approve", validate(resolveApprovalSchema), async (req, res) => {
     assertBoard(req);
     const id = req.params.id as string;
-    const { approval, applied } = await svc.approve(
-      id,
-      req.body.decidedByUserId ?? "board",
-      req.body.decisionNote,
-    );
+    const approval = await svc.approve(id, req.body.decidedByUserId ?? "board", req.body.decisionNote);
+    const linkedIssues = await issueApprovalsSvc.listIssuesForApproval(approval.id);
+    const linkedIssueIds = linkedIssues.map((issue) => issue.id);
+    const primaryIssueId = linkedIssueIds[0] ?? null;
 
-    if (applied) {
-      const linkedIssues = await issueApprovalsSvc.listIssuesForApproval(approval.id);
-      const linkedIssueIds = linkedIssues.map((issue) => issue.id);
-      const primaryIssueId = linkedIssueIds[0] ?? null;
+    await logActivity(db, {
+      companyId: approval.companyId,
+      actorType: "user",
+      actorId: req.actor.userId ?? "board",
+      action: "approval.approved",
+      entityType: "approval",
+      entityId: approval.id,
+      details: {
+        type: approval.type,
+        requestedByAgentId: approval.requestedByAgentId,
+        linkedIssueIds,
+      },
+    });
 
-      await logActivity(db, {
-        companyId: approval.companyId,
-        actorType: "user",
-        actorId: req.actor.userId ?? "board",
-        action: "approval.approved",
-        entityType: "approval",
-        entityId: approval.id,
-        details: {
-          type: approval.type,
-          requestedByAgentId: approval.requestedByAgentId,
-          linkedIssueIds,
-        },
-      });
+    if (approval.requestedByAgentId) {
+      try {
+        const wakeRun = await heartbeat.wakeup(approval.requestedByAgentId, {
+          source: "automation",
+          triggerDetail: "system",
+          reason: "approval_approved",
+          payload: {
+            approvalId: approval.id,
+            approvalStatus: approval.status,
+            issueId: primaryIssueId,
+            issueIds: linkedIssueIds,
+          },
+          requestedByActorType: "user",
+          requestedByActorId: req.actor.userId ?? "board",
+          contextSnapshot: {
+            source: "approval.approved",
+            approvalId: approval.id,
+            approvalStatus: approval.status,
+            issueId: primaryIssueId,
+            issueIds: linkedIssueIds,
+            taskId: primaryIssueId,
+            wakeReason: "approval_approved",
+          },
+        });
 
-      if (approval.requestedByAgentId) {
-        try {
-          const wakeRun = await heartbeat.wakeup(approval.requestedByAgentId, {
-            source: "automation",
-            triggerDetail: "system",
-            reason: "approval_approved",
-            payload: {
-              approvalId: approval.id,
-              approvalStatus: approval.status,
-              issueId: primaryIssueId,
-              issueIds: linkedIssueIds,
-            },
-            requestedByActorType: "user",
-            requestedByActorId: req.actor.userId ?? "board",
-            contextSnapshot: {
-              source: "approval.approved",
-              approvalId: approval.id,
-              approvalStatus: approval.status,
-              issueId: primaryIssueId,
-              issueIds: linkedIssueIds,
-              taskId: primaryIssueId,
-              wakeReason: "approval_approved",
-            },
-          });
-
-          await logActivity(db, {
-            companyId: approval.companyId,
-            actorType: "user",
-            actorId: req.actor.userId ?? "board",
-            action: "approval.requester_wakeup_queued",
-            entityType: "approval",
-            entityId: approval.id,
-            details: {
-              requesterAgentId: approval.requestedByAgentId,
-              wakeRunId: wakeRun?.id ?? null,
-              linkedIssueIds,
-            },
-          });
-        } catch (err) {
-          logger.warn(
-            {
-              err,
-              approvalId: approval.id,
-              requestedByAgentId: approval.requestedByAgentId,
-            },
-            "failed to queue requester wakeup after approval",
-          );
-          await logActivity(db, {
-            companyId: approval.companyId,
-            actorType: "user",
-            actorId: req.actor.userId ?? "board",
-            action: "approval.requester_wakeup_failed",
-            entityType: "approval",
-            entityId: approval.id,
-            details: {
-              requesterAgentId: approval.requestedByAgentId,
-              linkedIssueIds,
-              error: err instanceof Error ? err.message : String(err),
-            },
-          });
-        }
+        await logActivity(db, {
+          companyId: approval.companyId,
+          actorType: "user",
+          actorId: req.actor.userId ?? "board",
+          action: "approval.requester_wakeup_queued",
+          entityType: "approval",
+          entityId: approval.id,
+          details: {
+            requesterAgentId: approval.requestedByAgentId,
+            wakeRunId: wakeRun?.id ?? null,
+            linkedIssueIds,
+          },
+        });
+      } catch (err) {
+        logger.warn(
+          {
+            err,
+            approvalId: approval.id,
+            requestedByAgentId: approval.requestedByAgentId,
+          },
+          "failed to queue requester wakeup after approval",
+        );
+        await logActivity(db, {
+          companyId: approval.companyId,
+          actorType: "user",
+          actorId: req.actor.userId ?? "board",
+          action: "approval.requester_wakeup_failed",
+          entityType: "approval",
+          entityId: approval.id,
+          details: {
+            requesterAgentId: approval.requestedByAgentId,
+            linkedIssueIds,
+            error: err instanceof Error ? err.message : String(err),
+          },
+        });
       }
     }
 
@@ -216,23 +209,17 @@ export function approvalRoutes(db: Db) {
   router.post("/approvals/:id/reject", validate(resolveApprovalSchema), async (req, res) => {
     assertBoard(req);
     const id = req.params.id as string;
-    const { approval, applied } = await svc.reject(
-      id,
-      req.body.decidedByUserId ?? "board",
-      req.body.decisionNote,
-    );
+    const approval = await svc.reject(id, req.body.decidedByUserId ?? "board", req.body.decisionNote);
 
-    if (applied) {
-      await logActivity(db, {
-        companyId: approval.companyId,
-        actorType: "user",
-        actorId: req.actor.userId ?? "board",
-        action: "approval.rejected",
-        entityType: "approval",
-        entityId: approval.id,
-        details: { type: approval.type },
-      });
-    }
+    await logActivity(db, {
+      companyId: approval.companyId,
+      actorType: "user",
+      actorId: req.actor.userId ?? "board",
+      action: "approval.rejected",
+      entityType: "approval",
+      entityId: approval.id,
+      details: { type: approval.type },
+    });
 
     res.json(redactApprovalPayload(approval));
   });

server/src/routes/assets.ts

@@ -5,14 +5,22 @@ import { createAssetImageMetadataSchema } from "@paperclipai/shared";
 import type { StorageService } from "../storage/types.js";
 import { assetService, logActivity } from "../services/index.js";
 import { assertCompanyAccess, getActorInfo } from "./authz.js";
-import { isAllowedContentType, MAX_ATTACHMENT_BYTES } from "../attachment-types.js";
+
+const MAX_ASSET_IMAGE_BYTES = Number(process.env.PAPERCLIP_ATTACHMENT_MAX_BYTES) || 10 * 1024 * 1024;
+const ALLOWED_IMAGE_CONTENT_TYPES = new Set([
+  "image/png",
+  "image/jpeg",
+  "image/jpg",
+  "image/webp",
+  "image/gif",
+]);
 
 export function assetRoutes(db: Db, storage: StorageService) {
   const router = Router();
   const svc = assetService(db);
   const upload = multer({
     storage: multer.memoryStorage(),
-    limits: { fileSize: MAX_ATTACHMENT_BYTES, files: 1 },
+    limits: { fileSize: MAX_ASSET_IMAGE_BYTES, files: 1 },
   });
 
   async function runSingleFileUpload(req: Request, res: Response) {
@@ -33,7 +41,7 @@ export function assetRoutes(db: Db, storage: StorageService) {
     } catch (err) {
       if (err instanceof multer.MulterError) {
         if (err.code === "LIMIT_FILE_SIZE") {
-          res.status(422).json({ error: `File exceeds ${MAX_ATTACHMENT_BYTES} bytes` });
+          res.status(422).json({ error: `Image exceeds ${MAX_ASSET_IMAGE_BYTES} bytes` });
           return;
         }
         res.status(400).json({ error: err.message });
@@ -49,8 +57,8 @@ export function assetRoutes(db: Db, storage: StorageService) {
     }
 
     const contentType = (file.mimetype || "").toLowerCase();
-    if (!isAllowedContentType(contentType)) {
-      res.status(422).json({ error: `Unsupported file type: ${contentType || "unknown"}` });
+    if (!ALLOWED_IMAGE_CONTENT_TYPES.has(contentType)) {
+      res.status(422).json({ error: `Unsupported image type: ${contentType || "unknown"}` });
       return;
     }
     if (file.buffer.length <= 0) {

server/src/routes/health.ts

@@ -1,7 +1,7 @@
 import { Router } from "express";
 import type { Db } from "@paperclipai/db";
-import { and, count, eq, gt, isNull, sql } from "drizzle-orm";
-import { instanceUserRoles, invites } from "@paperclipai/db";
+import { count, sql } from "drizzle-orm";
+import { instanceUserRoles } from "@paperclipai/db";
 import type { DeploymentExposure, DeploymentMode } from "@paperclipai/shared";
 
 export function healthRoutes(
@@ -27,7 +27,6 @@ export function healthRoutes(
     }
 
     let bootstrapStatus: "ready" | "bootstrap_pending" = "ready";
-    let bootstrapInviteActive = false;
     if (opts.deploymentMode === "authenticated") {
       const roleCount = await db
         .select({ count: count() })
@@ -35,23 +34,6 @@ export function healthRoutes(
         .where(sql`${instanceUserRoles.role} = 'instance_admin'`)
         .then((rows) => Number(rows[0]?.count ?? 0));
       bootstrapStatus = roleCount > 0 ? "ready" : "bootstrap_pending";
-
-      if (bootstrapStatus === "bootstrap_pending") {
-        const now = new Date();
-        const inviteCount = await db
-          .select({ count: count() })
-          .from(invites)
-          .where(
-            and(
-              eq(invites.inviteType, "bootstrap_ceo"),
-              isNull(invites.revokedAt),
-              isNull(invites.acceptedAt),
-              gt(invites.expiresAt, now),
-            ),
-          )
-          .then((rows) => Number(rows[0]?.count ?? 0));
-        bootstrapInviteActive = inviteCount > 0;
-      }
     }
 
     res.json({
@@ -60,7 +42,6 @@ export function healthRoutes(
       deploymentExposure: opts.deploymentExposure,
       authReady: opts.authReady,
       bootstrapStatus,
-      bootstrapInviteActive,
       features: {
         companyDeletionEnabled: opts.companyDeletionEnabled,
       },

server/src/routes/issues.ts

@@ -26,7 +26,15 @@ import { logger } from "../middleware/logger.js";
 import { forbidden, HttpError, unauthorized } from "../errors.js";
 import { assertCompanyAccess, getActorInfo } from "./authz.js";
 import { shouldWakeAssigneeOnCheckout } from "./issues-checkout-wakeup.js";
-import { isAllowedContentType, MAX_ATTACHMENT_BYTES } from "../attachment-types.js";
+
+const MAX_ATTACHMENT_BYTES = Number(process.env.PAPERCLIP_ATTACHMENT_MAX_BYTES) || 10 * 1024 * 1024;
+const ALLOWED_ATTACHMENT_CONTENT_TYPES = new Set([
+  "image/png",
+  "image/jpeg",
+  "image/jpg",
+  "image/webp",
+  "image/gif",
+]);
 
 export function issueRoutes(db: Db, storage: StorageService) {
   const router = Router();
@@ -222,7 +230,6 @@ export function issueRoutes(db: Db, storage: StorageService) {
       touchedByUserId,
       unreadForUserId,
       projectId: req.query.projectId as string | undefined,
-      parentId: req.query.parentId as string | undefined,
       labelId: req.query.labelId as string | undefined,
       q: req.query.q as string | undefined,
     });
@@ -1060,7 +1067,7 @@ export function issueRoutes(db: Db, storage: StorageService) {
       return;
     }
     const contentType = (file.mimetype || "").toLowerCase();
-    if (!isAllowedContentType(contentType)) {
+    if (!ALLOWED_ATTACHMENT_CONTENT_TYPES.has(contentType)) {
       res.status(422).json({ error: `Unsupported attachment type: ${contentType || "unknown"}` });
       return;
     }

server/src/services/approvals.ts

@@ -1,4 +1,4 @@
-import { and, asc, eq, inArray } from "drizzle-orm";
+import { and, asc, eq } from "drizzle-orm";
 import type { Db } from "@paperclipai/db";
 import { approvalComments, approvals } from "@paperclipai/db";
 import { notFound, unprocessable } from "../errors.js";
@@ -8,9 +8,6 @@ import { notifyHireApproved } from "./hire-hook.js";
 export function approvalService(db: Db) {
   const agentsSvc = agentService(db);
   const canResolveStatuses = new Set(["pending", "revision_requested"]);
-  const resolvableStatuses = Array.from(canResolveStatuses);
-  type ApprovalRecord = typeof approvals.$inferSelect;
-  type ResolutionResult = { approval: ApprovalRecord; applied: boolean };
 
   async function getExistingApproval(id: string) {
     const existing = await db
@@ -22,50 +19,6 @@ export function approvalService(db: Db) {
     return existing;
   }
 
-  async function resolveApproval(
-    id: string,
-    targetStatus: "approved" | "rejected",
-    decidedByUserId: string,
-    decisionNote: string | null | undefined,
-  ): Promise<ResolutionResult> {
-    const existing = await getExistingApproval(id);
-    if (!canResolveStatuses.has(existing.status)) {
-      if (existing.status === targetStatus) {
-        return { approval: existing, applied: false };
-      }
-      throw unprocessable(
-        `Only pending or revision requested approvals can be ${targetStatus === "approved" ? "approved" : "rejected"}`,
-      );
-    }
-
-    const now = new Date();
-    const updated = await db
-      .update(approvals)
-      .set({
-        status: targetStatus,
-        decidedByUserId,
-        decisionNote: decisionNote ?? null,
-        decidedAt: now,
-        updatedAt: now,
-      })
-      .where(and(eq(approvals.id, id), inArray(approvals.status, resolvableStatuses)))
-      .returning()
-      .then((rows) => rows[0] ?? null);
-
-    if (updated) {
-      return { approval: updated, applied: true };
-    }
-
-    const latest = await getExistingApproval(id);
-    if (latest.status === targetStatus) {
-      return { approval: latest, applied: false };
-    }
-
-    throw unprocessable(
-      `Only pending or revision requested approvals can be ${targetStatus === "approved" ? "approved" : "rejected"}`,
-    );
-  }
-
   return {
     list: (companyId: string, status?: string) => {
       const conditions = [eq(approvals.companyId, companyId)];
@@ -88,16 +41,27 @@ export function approvalService(db: Db) {
         .then((rows) => rows[0]),
 
     approve: async (id: string, decidedByUserId: string, decisionNote?: string | null) => {
-      const { approval: updated, applied } = await resolveApproval(
-        id,
-        "approved",
-        decidedByUserId,
-        decisionNote,
-      );
+      const existing = await getExistingApproval(id);
+      if (!canResolveStatuses.has(existing.status)) {
+        throw unprocessable("Only pending or revision requested approvals can be approved");
+      }
+
+      const now = new Date();
+      const updated = await db
+        .update(approvals)
+        .set({
+          status: "approved",
+          decidedByUserId,
+          decisionNote: decisionNote ?? null,
+          decidedAt: now,
+          updatedAt: now,
+        })
+        .where(eq(approvals.id, id))
+        .returning()
+        .then((rows) => rows[0]);
 
       let hireApprovedAgentId: string | null = null;
-      const now = new Date();
-      if (applied && updated.type === "hire_agent") {
+      if (updated.type === "hire_agent") {
         const payload = updated.payload as Record<string, unknown>;
         const payloadAgentId = typeof payload.agentId === "string" ? payload.agentId : null;
         if (payloadAgentId) {
@@ -139,18 +103,30 @@ export function approvalService(db: Db) {
         }
       }
 
-      return { approval: updated, applied };
+      return updated;
     },
 
     reject: async (id: string, decidedByUserId: string, decisionNote?: string | null) => {
-      const { approval: updated, applied } = await resolveApproval(
-        id,
-        "rejected",
-        decidedByUserId,
-        decisionNote,
-      );
+      const existing = await getExistingApproval(id);
+      if (!canResolveStatuses.has(existing.status)) {
+        throw unprocessable("Only pending or revision requested approvals can be rejected");
+      }
 
-      if (applied && updated.type === "hire_agent") {
+      const now = new Date();
+      const updated = await db
+        .update(approvals)
+        .set({
+          status: "rejected",
+          decidedByUserId,
+          decisionNote: decisionNote ?? null,
+          decidedAt: now,
+          updatedAt: now,
+        })
+        .where(eq(approvals.id, id))
+        .returning()
+        .then((rows) => rows[0]);
+
+      if (updated.type === "hire_agent") {
         const payload = updated.payload as Record<string, unknown>;
         const payloadAgentId = typeof payload.agentId === "string" ? payload.agentId : null;
         if (payloadAgentId) {
@@ -158,7 +134,7 @@ export function approvalService(db: Db) {
         }
       }
 
-      return { approval: updated, applied };
+      return updated;
     },
 
     requestRevision: async (id: string, decidedByUserId: string, decisionNote?: string | null) => {

server/src/services/execution-workspace-policy.ts

@@ -0,0 +1,141 @@
+import type {
+  ExecutionWorkspaceMode,
+  ExecutionWorkspaceStrategy,
+  IssueExecutionWorkspaceSettings,
+  ProjectExecutionWorkspacePolicy,
+} from "@paperclipai/shared";
+import { asString, parseObject } from "../adapters/utils.js";
+
+type ParsedExecutionWorkspaceMode = Exclude<ExecutionWorkspaceMode, "inherit">;
+
+function cloneRecord(value: Record<string, unknown> | null | undefined): Record<string, unknown> | null {
+  if (!value) return null;
+  return { ...value };
+}
+
+function parseExecutionWorkspaceStrategy(raw: unknown): ExecutionWorkspaceStrategy | null {
+  const parsed = parseObject(raw);
+  const type = asString(parsed.type, "");
+  if (type !== "project_primary" && type !== "git_worktree") {
+    return null;
+  }
+  return {
+    type,
+    ...(typeof parsed.baseRef === "string" ? { baseRef: parsed.baseRef } : {}),
+    ...(typeof parsed.branchTemplate === "string" ? { branchTemplate: parsed.branchTemplate } : {}),
+    ...(typeof parsed.worktreeParentDir === "string" ? { worktreeParentDir: parsed.worktreeParentDir } : {}),
+  };
+}
+
+export function parseProjectExecutionWorkspacePolicy(raw: unknown): ProjectExecutionWorkspacePolicy | null {
+  const parsed = parseObject(raw);
+  if (Object.keys(parsed).length === 0) return null;
+  const enabled = typeof parsed.enabled === "boolean" ? parsed.enabled : false;
+  const defaultMode = asString(parsed.defaultMode, "");
+  const allowIssueOverride =
+    typeof parsed.allowIssueOverride === "boolean" ? parsed.allowIssueOverride : undefined;
+  return {
+    enabled,
+    ...(defaultMode === "project_primary" || defaultMode === "isolated" ? { defaultMode } : {}),
+    ...(allowIssueOverride !== undefined ? { allowIssueOverride } : {}),
+    ...(parseExecutionWorkspaceStrategy(parsed.workspaceStrategy)
+      ? { workspaceStrategy: parseExecutionWorkspaceStrategy(parsed.workspaceStrategy) }
+      : {}),
+    ...(parsed.workspaceRuntime && typeof parsed.workspaceRuntime === "object" && !Array.isArray(parsed.workspaceRuntime)
+      ? { workspaceRuntime: { ...(parsed.workspaceRuntime as Record<string, unknown>) } }
+      : {}),
+    ...(parsed.branchPolicy && typeof parsed.branchPolicy === "object" && !Array.isArray(parsed.branchPolicy)
+      ? { branchPolicy: { ...(parsed.branchPolicy as Record<string, unknown>) } }
+      : {}),
+    ...(parsed.pullRequestPolicy && typeof parsed.pullRequestPolicy === "object" && !Array.isArray(parsed.pullRequestPolicy)
+      ? { pullRequestPolicy: { ...(parsed.pullRequestPolicy as Record<string, unknown>) } }
+      : {}),
+    ...(parsed.cleanupPolicy && typeof parsed.cleanupPolicy === "object" && !Array.isArray(parsed.cleanupPolicy)
+      ? { cleanupPolicy: { ...(parsed.cleanupPolicy as Record<string, unknown>) } }
+      : {}),
+  };
+}
+
+export function parseIssueExecutionWorkspaceSettings(raw: unknown): IssueExecutionWorkspaceSettings | null {
+  const parsed = parseObject(raw);
+  if (Object.keys(parsed).length === 0) return null;
+  const mode = asString(parsed.mode, "");
+  return {
+    ...(mode === "inherit" || mode === "project_primary" || mode === "isolated" || mode === "agent_default"
+      ? { mode }
+      : {}),
+    ...(parseExecutionWorkspaceStrategy(parsed.workspaceStrategy)
+      ? { workspaceStrategy: parseExecutionWorkspaceStrategy(parsed.workspaceStrategy) }
+      : {}),
+    ...(parsed.workspaceRuntime && typeof parsed.workspaceRuntime === "object" && !Array.isArray(parsed.workspaceRuntime)
+      ? { workspaceRuntime: { ...(parsed.workspaceRuntime as Record<string, unknown>) } }
+      : {}),
+  };
+}
+
+export function defaultIssueExecutionWorkspaceSettingsForProject(
+  projectPolicy: ProjectExecutionWorkspacePolicy | null,
+): IssueExecutionWorkspaceSettings | null {
+  if (!projectPolicy?.enabled) return null;
+  return {
+    mode: projectPolicy.defaultMode === "isolated" ? "isolated" : "project_primary",
+  };
+}
+
+export function resolveExecutionWorkspaceMode(input: {
+  projectPolicy: ProjectExecutionWorkspacePolicy | null;
+  issueSettings: IssueExecutionWorkspaceSettings | null;
+  legacyUseProjectWorkspace: boolean | null;
+}): ParsedExecutionWorkspaceMode {
+  const issueMode = input.issueSettings?.mode;
+  if (issueMode && issueMode !== "inherit") {
+    return issueMode;
+  }
+  if (input.projectPolicy?.enabled) {
+    return input.projectPolicy.defaultMode === "isolated" ? "isolated" : "project_primary";
+  }
+  if (input.legacyUseProjectWorkspace === false) {
+    return "agent_default";
+  }
+  return "project_primary";
+}
+
+export function buildExecutionWorkspaceAdapterConfig(input: {
+  agentConfig: Record<string, unknown>;
+  projectPolicy: ProjectExecutionWorkspacePolicy | null;
+  issueSettings: IssueExecutionWorkspaceSettings | null;
+  mode: ParsedExecutionWorkspaceMode;
+  legacyUseProjectWorkspace: boolean | null;
+}): Record<string, unknown> {
+  const nextConfig = { ...input.agentConfig };
+  const projectHasPolicy = Boolean(input.projectPolicy?.enabled);
+  const issueHasWorkspaceOverrides = Boolean(
+    input.issueSettings?.mode ||
+    input.issueSettings?.workspaceStrategy ||
+    input.issueSettings?.workspaceRuntime,
+  );
+  const hasWorkspaceControl = projectHasPolicy || issueHasWorkspaceOverrides || input.legacyUseProjectWorkspace === false;
+
+  if (hasWorkspaceControl) {
+    if (input.mode === "isolated") {
+      const strategy =
+        input.issueSettings?.workspaceStrategy ??
+        input.projectPolicy?.workspaceStrategy ??
+        parseExecutionWorkspaceStrategy(nextConfig.workspaceStrategy) ??
+        ({ type: "git_worktree" } satisfies ExecutionWorkspaceStrategy);
+      nextConfig.workspaceStrategy = strategy as unknown as Record<string, unknown>;
+    } else {
+      delete nextConfig.workspaceStrategy;
+    }
+
+    if (input.mode === "agent_default") {
+      delete nextConfig.workspaceRuntime;
+    } else if (input.issueSettings?.workspaceRuntime) {
+      nextConfig.workspaceRuntime = cloneRecord(input.issueSettings.workspaceRuntime) ?? undefined;
+    } else if (input.projectPolicy?.workspaceRuntime) {
+      nextConfig.workspaceRuntime = cloneRecord(input.projectPolicy.workspaceRuntime) ?? undefined;
+    }
+  }
+
+  return nextConfig;
+}

server/src/services/heartbeat.ts

@@ -11,6 +11,7 @@ import {
   heartbeatRuns,
   costEvents,
   issues,
+  projects,
   projectWorkspaces,
 } from "@paperclipai/db";
 import { conflict, notFound } from "../errors.js";
@@ -23,6 +24,20 @@ import { createLocalAgentJwt } from "../agent-auth-jwt.js";
 import { parseObject, asBoolean, asNumber, appendWithCap, MAX_EXCERPT_BYTES } from "../adapters/utils.js";
 import { secretService } from "./secrets.js";
 import { resolveDefaultAgentWorkspaceDir } from "../home-paths.js";
+import {
+  buildWorkspaceReadyComment,
+  ensureRuntimeServicesForRun,
+  persistAdapterManagedRuntimeServices,
+  realizeExecutionWorkspace,
+  releaseRuntimeServicesForRun,
+} from "./workspace-runtime.js";
+import { issueService } from "./issues.js";
+import {
+  buildExecutionWorkspaceAdapterConfig,
+  parseIssueExecutionWorkspaceSettings,
+  parseProjectExecutionWorkspacePolicy,
+  resolveExecutionWorkspaceMode,
+} from "./execution-workspace-policy.js";
 
 const MAX_LIVE_LOG_CHUNK_BYTES = 8 * 1024;
 const HEARTBEAT_MAX_CONCURRENT_RUNS_DEFAULT = 1;
@@ -406,6 +421,7 @@ function resolveNextSessionState(input: {
 export function heartbeatService(db: Db) {
   const runLogStore = getRunLogStore();
   const secretsSvc = secretService(db);
+  const issuesSvc = issueService(db);
 
   async function getAgent(agentId: string) {
     return db
@@ -1071,8 +1087,10 @@ export function heartbeatService(db: Db) {
     const issueAssigneeConfig = issueId
       ? await db
           .select({
+            projectId: issues.projectId,
             assigneeAgentId: issues.assigneeAgentId,
             assigneeAdapterOverrides: issues.assigneeAdapterOverrides,
+            executionWorkspaceSettings: issues.executionWorkspaceSettings,
           })
           .from(issues)
           .where(and(eq(issues.id, issueId), eq(issues.companyId, agent.companyId)))
@@ -1084,6 +1102,18 @@ export function heartbeatService(db: Db) {
             issueAssigneeConfig.assigneeAdapterOverrides,
           )
         : null;
+    const issueExecutionWorkspaceSettings = parseIssueExecutionWorkspaceSettings(
+      issueAssigneeConfig?.executionWorkspaceSettings,
+    );
+    const contextProjectId = readNonEmptyString(context.projectId);
+    const executionProjectId = issueAssigneeConfig?.projectId ?? contextProjectId;
+    const projectExecutionWorkspacePolicy = executionProjectId
+      ? await db
+          .select({ executionWorkspacePolicy: projects.executionWorkspacePolicy })
+          .from(projects)
+          .where(and(eq(projects.id, executionProjectId), eq(projects.companyId, agent.companyId)))
+          .then((rows) => parseProjectExecutionWorkspacePolicy(rows[0]?.executionWorkspacePolicy))
+      : null;
     const taskSession = taskKey
       ? await getTaskSession(agent.companyId, agent.id, agent.adapterType, taskKey)
       : null;
@@ -1093,20 +1123,72 @@ export function heartbeatService(db: Db) {
     const previousSessionParams = normalizeSessionParams(
       sessionCodec.deserialize(taskSessionForRun?.sessionParamsJson ?? null),
     );
+    const config = parseObject(agent.adapterConfig);
+    const executionWorkspaceMode = resolveExecutionWorkspaceMode({
+      projectPolicy: projectExecutionWorkspacePolicy,
+      issueSettings: issueExecutionWorkspaceSettings,
+      legacyUseProjectWorkspace: issueAssigneeOverrides?.useProjectWorkspace ?? null,
+    });
     const resolvedWorkspace = await resolveWorkspaceForRun(
       agent,
       context,
       previousSessionParams,
-      { useProjectWorkspace: issueAssigneeOverrides?.useProjectWorkspace ?? null },
+      { useProjectWorkspace: executionWorkspaceMode !== "agent_default" },
     );
+    const workspaceManagedConfig = buildExecutionWorkspaceAdapterConfig({
+      agentConfig: config,
+      projectPolicy: projectExecutionWorkspacePolicy,
+      issueSettings: issueExecutionWorkspaceSettings,
+      mode: executionWorkspaceMode,
+      legacyUseProjectWorkspace: issueAssigneeOverrides?.useProjectWorkspace ?? null,
+    });
+    const mergedConfig = issueAssigneeOverrides?.adapterConfig
+      ? { ...workspaceManagedConfig, ...issueAssigneeOverrides.adapterConfig }
+      : workspaceManagedConfig;
+    const { config: resolvedConfig, secretKeys } = await secretsSvc.resolveAdapterConfigForRuntime(
+      agent.companyId,
+      mergedConfig,
+    );
+    const issueRef = issueId
+      ? await db
+          .select({
+            id: issues.id,
+            identifier: issues.identifier,
+            title: issues.title,
+          })
+          .from(issues)
+          .where(and(eq(issues.id, issueId), eq(issues.companyId, agent.companyId)))
+          .then((rows) => rows[0] ?? null)
+      : null;
+    const executionWorkspace = await realizeExecutionWorkspace({
+      base: {
+        baseCwd: resolvedWorkspace.cwd,
+        source: resolvedWorkspace.source,
+        projectId: resolvedWorkspace.projectId,
+        workspaceId: resolvedWorkspace.workspaceId,
+        repoUrl: resolvedWorkspace.repoUrl,
+        repoRef: resolvedWorkspace.repoRef,
+      },
+      config: resolvedConfig,
+      issue: issueRef,
+      agent: {
+        id: agent.id,
+        name: agent.name,
+        companyId: agent.companyId,
+      },
+    });
     const runtimeSessionResolution = resolveRuntimeSessionParamsForWorkspace({
       agentId: agent.id,
       previousSessionParams,
-      resolvedWorkspace,
+      resolvedWorkspace: {
+        ...resolvedWorkspace,
+        cwd: executionWorkspace.cwd,
+      },
     });
     const runtimeSessionParams = runtimeSessionResolution.sessionParams;
     const runtimeWorkspaceWarnings = [
       ...resolvedWorkspace.warnings,
+      ...executionWorkspace.warnings,
       ...(runtimeSessionResolution.warning ? [runtimeSessionResolution.warning] : []),
       ...(resetTaskSession && sessionResetReason
         ? [
@@ -1117,16 +1199,33 @@ export function heartbeatService(db: Db) {
         : []),
     ];
     context.paperclipWorkspace = {
-      cwd: resolvedWorkspace.cwd,
-      source: resolvedWorkspace.source,
-      projectId: resolvedWorkspace.projectId,
-      workspaceId: resolvedWorkspace.workspaceId,
-      repoUrl: resolvedWorkspace.repoUrl,
-      repoRef: resolvedWorkspace.repoRef,
+      cwd: executionWorkspace.cwd,
+      source: executionWorkspace.source,
+      mode: executionWorkspaceMode,
+      strategy: executionWorkspace.strategy,
+      projectId: executionWorkspace.projectId,
+      workspaceId: executionWorkspace.workspaceId,
+      repoUrl: executionWorkspace.repoUrl,
+      repoRef: executionWorkspace.repoRef,
+      branchName: executionWorkspace.branchName,
+      worktreePath: executionWorkspace.worktreePath,
     };
     context.paperclipWorkspaces = resolvedWorkspace.workspaceHints;
-    if (resolvedWorkspace.projectId && !readNonEmptyString(context.projectId)) {
-      context.projectId = resolvedWorkspace.projectId;
+    const runtimeServiceIntents = (() => {
+      const runtimeConfig = parseObject(resolvedConfig.workspaceRuntime);
+      return Array.isArray(runtimeConfig.services)
+        ? runtimeConfig.services.filter(
+            (value): value is Record<string, unknown> => typeof value === "object" && value !== null,
+          )
+        : [];
+    })();
+    if (runtimeServiceIntents.length > 0) {
+      context.paperclipRuntimeServiceIntents = runtimeServiceIntents;
+    } else {
+      delete context.paperclipRuntimeServiceIntents;
+    }
+    if (executionWorkspace.projectId && !readNonEmptyString(context.projectId)) {
+      context.projectId = executionWorkspace.projectId;
     }
     const runtimeSessionFallback = taskKey || resetTaskSession ? null : runtime.sessionId;
     const previousSessionDisplayId = truncateDisplayId(
@@ -1146,7 +1245,6 @@ export function heartbeatService(db: Db) {
     let handle: RunLogHandle | null = null;
     let stdoutExcerpt = "";
     let stderrExcerpt = "";
-
     try {
       const startedAt = run.startedAt ?? new Date();
       const runningWithSession = await db
@@ -1154,6 +1252,7 @@ export function heartbeatService(db: Db) {
         .set({
           startedAt,
           sessionIdBefore: runtimeForAdapter.sessionDisplayId ?? runtimeForAdapter.sessionId,
+          contextSnapshot: context,
           updatedAt: new Date(),
         })
         .where(eq(heartbeatRuns.id, run.id))
@@ -1235,15 +1334,54 @@ export function heartbeatService(db: Db) {
       for (const warning of runtimeWorkspaceWarnings) {
         await onLog("stderr", `[paperclip] ${warning}\n`);
       }
-
-      const config = parseObject(agent.adapterConfig);
-      const mergedConfig = issueAssigneeOverrides?.adapterConfig
-        ? { ...config, ...issueAssigneeOverrides.adapterConfig }
-        : config;
-      const { config: resolvedConfig, secretKeys } = await secretsSvc.resolveAdapterConfigForRuntime(
-        agent.companyId,
-        mergedConfig,
+      const adapterEnv = Object.fromEntries(
+        Object.entries(parseObject(resolvedConfig.env)).filter(
+          (entry): entry is [string, string] => typeof entry[0] === "string" && typeof entry[1] === "string",
+        ),
       );
+      const runtimeServices = await ensureRuntimeServicesForRun({
+        db,
+        runId: run.id,
+        agent: {
+          id: agent.id,
+          name: agent.name,
+          companyId: agent.companyId,
+        },
+        issue: issueRef,
+        workspace: executionWorkspace,
+        config: resolvedConfig,
+        adapterEnv,
+        onLog,
+      });
+      if (runtimeServices.length > 0) {
+        context.paperclipRuntimeServices = runtimeServices;
+        context.paperclipRuntimePrimaryUrl =
+          runtimeServices.find((service) => readNonEmptyString(service.url))?.url ?? null;
+        await db
+          .update(heartbeatRuns)
+          .set({
+            contextSnapshot: context,
+            updatedAt: new Date(),
+          })
+          .where(eq(heartbeatRuns.id, run.id));
+      }
+      if (issueId && (executionWorkspace.created || runtimeServices.some((service) => !service.reused))) {
+        try {
+          await issuesSvc.addComment(
+            issueId,
+            buildWorkspaceReadyComment({
+              workspace: executionWorkspace,
+              runtimeServices,
+            }),
+            { agentId: agent.id },
+          );
+        } catch (err) {
+          await onLog(
+            "stderr",
+            `[paperclip] Failed to post workspace-ready comment: ${err instanceof Error ? err.message : String(err)}\n`,
+          );
+        }
+      }
       const onAdapterMeta = async (meta: AdapterInvocationMeta) => {
         if (meta.env && secretKeys.size > 0) {
           for (const key of secretKeys) {
@@ -1284,6 +1422,54 @@ export function heartbeatService(db: Db) {
         onMeta: onAdapterMeta,
         authToken: authToken ?? undefined,
       });
+      const adapterManagedRuntimeServices = adapterResult.runtimeServices
+        ? await persistAdapterManagedRuntimeServices({
+            db,
+            adapterType: agent.adapterType,
+            runId: run.id,
+            agent: {
+              id: agent.id,
+              name: agent.name,
+              companyId: agent.companyId,
+            },
+            issue: issueRef,
+            workspace: executionWorkspace,
+            reports: adapterResult.runtimeServices,
+          })
+        : [];
+      if (adapterManagedRuntimeServices.length > 0) {
+        const combinedRuntimeServices = [
+          ...runtimeServices,
+          ...adapterManagedRuntimeServices,
+        ];
+        context.paperclipRuntimeServices = combinedRuntimeServices;
+        context.paperclipRuntimePrimaryUrl =
+          combinedRuntimeServices.find((service) => readNonEmptyString(service.url))?.url ?? null;
+        await db
+          .update(heartbeatRuns)
+          .set({
+            contextSnapshot: context,
+            updatedAt: new Date(),
+          })
+          .where(eq(heartbeatRuns.id, run.id));
+        if (issueId) {
+          try {
+            await issuesSvc.addComment(
+              issueId,
+              buildWorkspaceReadyComment({
+                workspace: executionWorkspace,
+                runtimeServices: adapterManagedRuntimeServices,
+              }),
+              { agentId: agent.id },
+            );
+          } catch (err) {
+            await onLog(
+              "stderr",
+              `[paperclip] Failed to post adapter-managed runtime comment: ${err instanceof Error ? err.message : String(err)}\n`,
+            );
+          }
+        }
+      }
       const nextSessionState = resolveNextSessionState({
         codec: sessionCodec,
         adapterResult,
@@ -1460,6 +1646,7 @@ export function heartbeatService(db: Db) {
 
       await finalizeAgentStatus(agent.id, "failed");
     } finally {
+      await releaseRuntimeServicesForRun(run.id);
       await startNextQueuedRunForAgent(agent.id);
     }
   }

server/src/services/index.ts

@@ -17,4 +17,5 @@ export { companyPortabilityService } from "./company-portability.js";
 export { logActivity, type LogActivityInput } from "./activity-log.js";
 export { notifyHireApproved, type NotifyHireApprovedInput } from "./hire-hook.js";
 export { publishLiveEvent, subscribeCompanyLiveEvents } from "./live-events.js";
+export { reconcilePersistedRuntimeServicesOnStartup } from "./workspace-runtime.js";
 export { createStorageServiceFromConfig, getStorageService } from "../storage/index.js";

server/src/services/issues.ts

@@ -18,6 +18,10 @@ import {
 } from "@paperclipai/db";
 import { extractProjectMentionIds } from "@paperclipai/shared";
 import { conflict, notFound, unprocessable } from "../errors.js";
+import {
+  defaultIssueExecutionWorkspaceSettingsForProject,
+  parseProjectExecutionWorkspacePolicy,
+} from "./execution-workspace-policy.js";
 
 const ALL_ISSUE_STATUSES = ["backlog", "todo", "in_progress", "in_review", "blocked", "done", "cancelled"];
 
@@ -53,7 +57,6 @@ export interface IssueFilters {
   touchedByUserId?: string;
   unreadForUserId?: string;
   projectId?: string;
-  parentId?: string;
   labelId?: string;
   q?: string;
 }
@@ -459,7 +462,6 @@ export function issueService(db: Db) {
         conditions.push(unreadForUserCondition(companyId, unreadForUserId));
       }
       if (filters?.projectId) conditions.push(eq(issues.projectId, filters.projectId));
-      if (filters?.parentId) conditions.push(eq(issues.parentId, filters.parentId));
       if (filters?.labelId) {
         const labeledIssueIds = await db
           .select({ issueId: issueLabels.issueId })
@@ -637,6 +639,19 @@ export function issueService(db: Db) {
         throw unprocessable("in_progress issues require an assignee");
       }
       return db.transaction(async (tx) => {
+        let executionWorkspaceSettings =
+          (issueData.executionWorkspaceSettings as Record<string, unknown> | null | undefined) ?? null;
+        if (executionWorkspaceSettings == null && issueData.projectId) {
+          const project = await tx
+            .select({ executionWorkspacePolicy: projects.executionWorkspacePolicy })
+            .from(projects)
+            .where(and(eq(projects.id, issueData.projectId), eq(projects.companyId, companyId)))
+            .then((rows) => rows[0] ?? null);
+          executionWorkspaceSettings =
+            defaultIssueExecutionWorkspaceSettingsForProject(
+              parseProjectExecutionWorkspacePolicy(project?.executionWorkspacePolicy),
+            ) as Record<string, unknown> | null;
+        }
         const [company] = await tx
           .update(companies)
           .set({ issueCounter: sql`${companies.issueCounter} + 1` })
@@ -646,7 +661,13 @@ export function issueService(db: Db) {
         const issueNumber = company.issueCounter;
         const identifier = `${company.issuePrefix}-${issueNumber}`;
 
-        const values = { ...issueData, companyId, issueNumber, identifier } as typeof issues.$inferInsert;
+        const values = {
+          ...issueData,
+          ...(executionWorkspaceSettings ? { executionWorkspaceSettings } : {}),
+          companyId,
+          issueNumber,
+          identifier,
+        } as typeof issues.$inferInsert;
         if (values.status === "in_progress" && !values.startedAt) {
           values.startedAt = new Date();
         }

server/src/services/projects.ts

@@ -1,17 +1,22 @@
 import { and, asc, desc, eq, inArray } from "drizzle-orm";
 import type { Db } from "@paperclipai/db";
-import { projects, projectGoals, goals, projectWorkspaces } from "@paperclipai/db";
+import { projects, projectGoals, goals, projectWorkspaces, workspaceRuntimeServices } from "@paperclipai/db";
 import {
   PROJECT_COLORS,
   deriveProjectUrlKey,
   isUuidLike,
   normalizeProjectUrlKey,
+  type ProjectExecutionWorkspacePolicy,
   type ProjectGoalRef,
   type ProjectWorkspace,
+  type WorkspaceRuntimeService,
 } from "@paperclipai/shared";
+import { listWorkspaceRuntimeServicesForProjectWorkspaces } from "./workspace-runtime.js";
+import { parseProjectExecutionWorkspacePolicy } from "./execution-workspace-policy.js";
 
 type ProjectRow = typeof projects.$inferSelect;
 type ProjectWorkspaceRow = typeof projectWorkspaces.$inferSelect;
+type WorkspaceRuntimeServiceRow = typeof workspaceRuntimeServices.$inferSelect;
 const REPO_ONLY_CWD_SENTINEL = "/__paperclip_repo_only__";
 type CreateWorkspaceInput = {
   name?: string | null;
@@ -23,10 +28,11 @@ type CreateWorkspaceInput = {
 };
 type UpdateWorkspaceInput = Partial<CreateWorkspaceInput>;
 
-interface ProjectWithGoals extends ProjectRow {
+interface ProjectWithGoals extends Omit<ProjectRow, "executionWorkspacePolicy"> {
   urlKey: string;
   goalIds: string[];
   goals: ProjectGoalRef[];
+  executionWorkspacePolicy: ProjectExecutionWorkspacePolicy | null;
   workspaces: ProjectWorkspace[];
   primaryWorkspace: ProjectWorkspace | null;
 }
@@ -74,11 +80,46 @@ async function attachGoals(db: Db, rows: ProjectRow[]): Promise<ProjectWithGoals
       urlKey: deriveProjectUrlKey(r.name, r.id),
       goalIds: g.map((x) => x.id),
       goals: g,
+      executionWorkspacePolicy: parseProjectExecutionWorkspacePolicy(r.executionWorkspacePolicy),
     } as ProjectWithGoals;
   });
 }
 
-function toWorkspace(row: ProjectWorkspaceRow): ProjectWorkspace {
+function toRuntimeService(row: WorkspaceRuntimeServiceRow): WorkspaceRuntimeService {
+  return {
+    id: row.id,
+    companyId: row.companyId,
+    projectId: row.projectId ?? null,
+    projectWorkspaceId: row.projectWorkspaceId ?? null,
+    issueId: row.issueId ?? null,
+    scopeType: row.scopeType as WorkspaceRuntimeService["scopeType"],
+    scopeId: row.scopeId ?? null,
+    serviceName: row.serviceName,
+    status: row.status as WorkspaceRuntimeService["status"],
+    lifecycle: row.lifecycle as WorkspaceRuntimeService["lifecycle"],
+    reuseKey: row.reuseKey ?? null,
+    command: row.command ?? null,
+    cwd: row.cwd ?? null,
+    port: row.port ?? null,
+    url: row.url ?? null,
+    provider: row.provider as WorkspaceRuntimeService["provider"],
+    providerRef: row.providerRef ?? null,
+    ownerAgentId: row.ownerAgentId ?? null,
+    startedByRunId: row.startedByRunId ?? null,
+    lastUsedAt: row.lastUsedAt,
+    startedAt: row.startedAt,
+    stoppedAt: row.stoppedAt ?? null,
+    stopPolicy: (row.stopPolicy as Record<string, unknown> | null) ?? null,
+    healthStatus: row.healthStatus as WorkspaceRuntimeService["healthStatus"],
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
+function toWorkspace(
+  row: ProjectWorkspaceRow,
+  runtimeServices: WorkspaceRuntimeService[] = [],
+): ProjectWorkspace {
   return {
     id: row.id,
     companyId: row.companyId,
@@ -89,15 +130,20 @@ function toWorkspace(row: ProjectWorkspaceRow): ProjectWorkspace {
     repoRef: row.repoRef ?? null,
     metadata: (row.metadata as Record<string, unknown> | null) ?? null,
     isPrimary: row.isPrimary,
+    runtimeServices,
     createdAt: row.createdAt,
     updatedAt: row.updatedAt,
   };
 }
 
-function pickPrimaryWorkspace(rows: ProjectWorkspaceRow[]): ProjectWorkspace | null {
+function pickPrimaryWorkspace(
+  rows: ProjectWorkspaceRow[],
+  runtimeServicesByWorkspaceId?: Map<string, WorkspaceRuntimeService[]>,
+): ProjectWorkspace | null {
   if (rows.length === 0) return null;
   const explicitPrimary = rows.find((row) => row.isPrimary);
-  return toWorkspace(explicitPrimary ?? rows[0]);
+  const primary = explicitPrimary ?? rows[0];
+  return toWorkspace(primary, runtimeServicesByWorkspaceId?.get(primary.id) ?? []);
 }
 
 /** Batch-load workspace refs for a set of projects. */
@@ -110,6 +156,17 @@ async function attachWorkspaces(db: Db, rows: ProjectWithGoals[]): Promise<Proje
     .from(projectWorkspaces)
     .where(inArray(projectWorkspaces.projectId, projectIds))
     .orderBy(desc(projectWorkspaces.isPrimary), asc(projectWorkspaces.createdAt), asc(projectWorkspaces.id));
+  const runtimeServicesByWorkspaceId = await listWorkspaceRuntimeServicesForProjectWorkspaces(
+    db,
+    rows[0]!.companyId,
+    workspaceRows.map((workspace) => workspace.id),
+  );
+  const sharedRuntimeServicesByWorkspaceId = new Map(
+    Array.from(runtimeServicesByWorkspaceId.entries()).map(([workspaceId, services]) => [
+      workspaceId,
+      services.map(toRuntimeService),
+    ]),
+  );
 
   const map = new Map<string, ProjectWorkspaceRow[]>();
   for (const row of workspaceRows) {
@@ -123,11 +180,16 @@ async function attachWorkspaces(db: Db, rows: ProjectWithGoals[]): Promise<Proje
 
   return rows.map((row) => {
     const projectWorkspaceRows = map.get(row.id) ?? [];
-    const workspaces = projectWorkspaceRows.map(toWorkspace);
+    const workspaces = projectWorkspaceRows.map((workspace) =>
+      toWorkspace(
+        workspace,
+        sharedRuntimeServicesByWorkspaceId.get(workspace.id) ?? [],
+      ),
+    );
     return {
       ...row,
       workspaces,
-      primaryWorkspace: pickPrimaryWorkspace(projectWorkspaceRows),
+      primaryWorkspace: pickPrimaryWorkspace(projectWorkspaceRows, sharedRuntimeServicesByWorkspaceId),
     };
   });
 }
@@ -402,7 +464,18 @@ export function projectService(db: Db) {
         .from(projectWorkspaces)
         .where(eq(projectWorkspaces.projectId, projectId))
         .orderBy(desc(projectWorkspaces.isPrimary), asc(projectWorkspaces.createdAt), asc(projectWorkspaces.id));
-      return rows.map(toWorkspace);
+      if (rows.length === 0) return [];
+      const runtimeServicesByWorkspaceId = await listWorkspaceRuntimeServicesForProjectWorkspaces(
+        db,
+        rows[0]!.companyId,
+        rows.map((workspace) => workspace.id),
+      );
+      return rows.map((row) =>
+        toWorkspace(
+          row,
+          (runtimeServicesByWorkspaceId.get(row.id) ?? []).map(toRuntimeService),
+        ),
+      );
     },
 
     createWorkspace: async (

server/src/services/workspace-runtime.ts

@@ -0,0 +1,962 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import fs from "node:fs/promises";
+import net from "node:net";
+import { createHash, randomUUID } from "node:crypto";
+import path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import type { AdapterRuntimeServiceReport } from "@paperclipai/adapter-utils";
+import type { Db } from "@paperclipai/db";
+import { workspaceRuntimeServices } from "@paperclipai/db";
+import { and, desc, eq, inArray } from "drizzle-orm";
+import { asNumber, asString, parseObject, renderTemplate } from "../adapters/utils.js";
+import { resolveHomeAwarePath } from "../home-paths.js";
+
+export interface ExecutionWorkspaceInput {
+  baseCwd: string;
+  source: "project_primary" | "task_session" | "agent_home";
+  projectId: string | null;
+  workspaceId: string | null;
+  repoUrl: string | null;
+  repoRef: string | null;
+}
+
+export interface ExecutionWorkspaceIssueRef {
+  id: string;
+  identifier: string | null;
+  title: string | null;
+}
+
+export interface ExecutionWorkspaceAgentRef {
+  id: string;
+  name: string;
+  companyId: string;
+}
+
+export interface RealizedExecutionWorkspace extends ExecutionWorkspaceInput {
+  strategy: "project_primary" | "git_worktree";
+  cwd: string;
+  branchName: string | null;
+  worktreePath: string | null;
+  warnings: string[];
+  created: boolean;
+}
+
+export interface RuntimeServiceRef {
+  id: string;
+  companyId: string;
+  projectId: string | null;
+  projectWorkspaceId: string | null;
+  issueId: string | null;
+  serviceName: string;
+  status: "starting" | "running" | "stopped" | "failed";
+  lifecycle: "shared" | "ephemeral";
+  scopeType: "project_workspace" | "execution_workspace" | "run" | "agent";
+  scopeId: string | null;
+  reuseKey: string | null;
+  command: string | null;
+  cwd: string | null;
+  port: number | null;
+  url: string | null;
+  provider: "local_process" | "adapter_managed";
+  providerRef: string | null;
+  ownerAgentId: string | null;
+  startedByRunId: string | null;
+  lastUsedAt: string;
+  startedAt: string;
+  stoppedAt: string | null;
+  stopPolicy: Record<string, unknown> | null;
+  healthStatus: "unknown" | "healthy" | "unhealthy";
+  reused: boolean;
+}
+
+interface RuntimeServiceRecord extends RuntimeServiceRef {
+  db?: Db;
+  child: ChildProcess | null;
+  leaseRunIds: Set<string>;
+  idleTimer: ReturnType<typeof globalThis.setTimeout> | null;
+  envFingerprint: string;
+}
+
+const runtimeServicesById = new Map<string, RuntimeServiceRecord>();
+const runtimeServicesByReuseKey = new Map<string, string>();
+const runtimeServiceLeasesByRun = new Map<string, string[]>();
+
+function stableStringify(value: unknown): string {
+  if (Array.isArray(value)) {
+    return `[${value.map((entry) => stableStringify(entry)).join(",")}]`;
+  }
+  if (value && typeof value === "object") {
+    const rec = value as Record<string, unknown>;
+    return `{${Object.keys(rec).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(rec[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function stableRuntimeServiceId(input: {
+  adapterType: string;
+  runId: string;
+  scopeType: RuntimeServiceRef["scopeType"];
+  scopeId: string | null;
+  serviceName: string;
+  reportId: string | null;
+  providerRef: string | null;
+  reuseKey: string | null;
+}) {
+  if (input.reportId) return input.reportId;
+  const digest = createHash("sha256")
+    .update(
+      stableStringify({
+        adapterType: input.adapterType,
+        runId: input.runId,
+        scopeType: input.scopeType,
+        scopeId: input.scopeId,
+        serviceName: input.serviceName,
+        providerRef: input.providerRef,
+        reuseKey: input.reuseKey,
+      }),
+    )
+    .digest("hex")
+    .slice(0, 32);
+  return `${input.adapterType}-${digest}`;
+}
+
+function toRuntimeServiceRef(record: RuntimeServiceRecord, overrides?: Partial<RuntimeServiceRef>): RuntimeServiceRef {
+  return {
+    id: record.id,
+    companyId: record.companyId,
+    projectId: record.projectId,
+    projectWorkspaceId: record.projectWorkspaceId,
+    issueId: record.issueId,
+    serviceName: record.serviceName,
+    status: record.status,
+    lifecycle: record.lifecycle,
+    scopeType: record.scopeType,
+    scopeId: record.scopeId,
+    reuseKey: record.reuseKey,
+    command: record.command,
+    cwd: record.cwd,
+    port: record.port,
+    url: record.url,
+    provider: record.provider,
+    providerRef: record.providerRef,
+    ownerAgentId: record.ownerAgentId,
+    startedByRunId: record.startedByRunId,
+    lastUsedAt: record.lastUsedAt,
+    startedAt: record.startedAt,
+    stoppedAt: record.stoppedAt,
+    stopPolicy: record.stopPolicy,
+    healthStatus: record.healthStatus,
+    reused: record.reused,
+    ...overrides,
+  };
+}
+
+function sanitizeSlugPart(value: string | null | undefined, fallback: string): string {
+  const raw = (value ?? "").trim().toLowerCase();
+  const normalized = raw
+    .replace(/[^a-z0-9/_-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^[-/]+|[-/]+$/g, "");
+  return normalized.length > 0 ? normalized : fallback;
+}
+
+function renderWorkspaceTemplate(template: string, input: {
+  issue: ExecutionWorkspaceIssueRef | null;
+  agent: ExecutionWorkspaceAgentRef;
+  projectId: string | null;
+  repoRef: string | null;
+}) {
+  const issueIdentifier = input.issue?.identifier ?? input.issue?.id ?? "issue";
+  const slug = sanitizeSlugPart(input.issue?.title, sanitizeSlugPart(issueIdentifier, "issue"));
+  return renderTemplate(template, {
+    issue: {
+      id: input.issue?.id ?? "",
+      identifier: input.issue?.identifier ?? "",
+      title: input.issue?.title ?? "",
+    },
+    agent: {
+      id: input.agent.id,
+      name: input.agent.name,
+    },
+    project: {
+      id: input.projectId ?? "",
+    },
+    workspace: {
+      repoRef: input.repoRef ?? "",
+    },
+    slug,
+  });
+}
+
+function sanitizeBranchName(value: string): string {
+  return value
+    .trim()
+    .replace(/[^A-Za-z0-9._/-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^[-/.]+|[-/.]+$/g, "")
+    .slice(0, 120) || "paperclip-work";
+}
+
+function isAbsolutePath(value: string) {
+  return path.isAbsolute(value) || value.startsWith("~");
+}
+
+function resolveConfiguredPath(value: string, baseDir: string): string {
+  if (isAbsolutePath(value)) {
+    return resolveHomeAwarePath(value);
+  }
+  return path.resolve(baseDir, value);
+}
+
+async function runGit(args: string[], cwd: string): Promise<string> {
+  const proc = await new Promise<{ stdout: string; stderr: string; code: number | null }>((resolve, reject) => {
+    const child = spawn("git", args, {
+      cwd,
+      stdio: ["ignore", "pipe", "pipe"],
+      env: process.env,
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (chunk) => {
+      stdout += String(chunk);
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr += String(chunk);
+    });
+    child.on("error", reject);
+    child.on("close", (code) => resolve({ stdout, stderr, code }));
+  });
+  if (proc.code !== 0) {
+    throw new Error(proc.stderr.trim() || proc.stdout.trim() || `git ${args.join(" ")} failed`);
+  }
+  return proc.stdout.trim();
+}
+
+async function directoryExists(value: string) {
+  return fs.stat(value).then((stats) => stats.isDirectory()).catch(() => false);
+}
+
+export async function realizeExecutionWorkspace(input: {
+  base: ExecutionWorkspaceInput;
+  config: Record<string, unknown>;
+  issue: ExecutionWorkspaceIssueRef | null;
+  agent: ExecutionWorkspaceAgentRef;
+}): Promise<RealizedExecutionWorkspace> {
+  const rawStrategy = parseObject(input.config.workspaceStrategy);
+  const strategyType = asString(rawStrategy.type, "project_primary");
+  if (strategyType !== "git_worktree") {
+    return {
+      ...input.base,
+      strategy: "project_primary",
+      cwd: input.base.baseCwd,
+      branchName: null,
+      worktreePath: null,
+      warnings: [],
+      created: false,
+    };
+  }
+
+  const repoRoot = await runGit(["rev-parse", "--show-toplevel"], input.base.baseCwd);
+  const branchTemplate = asString(rawStrategy.branchTemplate, "{{issue.identifier}}-{{slug}}");
+  const renderedBranch = renderWorkspaceTemplate(branchTemplate, {
+    issue: input.issue,
+    agent: input.agent,
+    projectId: input.base.projectId,
+    repoRef: input.base.repoRef,
+  });
+  const branchName = sanitizeBranchName(renderedBranch);
+  const configuredParentDir = asString(rawStrategy.worktreeParentDir, "");
+  const worktreeParentDir = configuredParentDir
+    ? resolveConfiguredPath(configuredParentDir, repoRoot)
+    : path.join(repoRoot, ".paperclip", "worktrees");
+  const worktreePath = path.join(worktreeParentDir, branchName);
+  const baseRef = asString(rawStrategy.baseRef, input.base.repoRef ?? "HEAD");
+
+  await fs.mkdir(worktreeParentDir, { recursive: true });
+
+  const existingWorktree = await directoryExists(worktreePath);
+  if (existingWorktree) {
+    const existingGitDir = await runGit(["rev-parse", "--git-dir"], worktreePath).catch(() => null);
+    if (existingGitDir) {
+      return {
+        ...input.base,
+        strategy: "git_worktree",
+        cwd: worktreePath,
+        branchName,
+        worktreePath,
+        warnings: [],
+        created: false,
+      };
+    }
+    throw new Error(`Configured worktree path "${worktreePath}" already exists and is not a git worktree.`);
+  }
+
+  await runGit(["worktree", "add", "-B", branchName, worktreePath, baseRef], repoRoot);
+
+  return {
+    ...input.base,
+    strategy: "git_worktree",
+    cwd: worktreePath,
+    branchName,
+    worktreePath,
+    warnings: [],
+    created: true,
+  };
+}
+
+async function allocatePort(): Promise<number> {
+  return await new Promise<number>((resolve, reject) => {
+    const server = net.createServer();
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      server.close((err) => {
+        if (err) {
+          reject(err);
+          return;
+        }
+        if (!address || typeof address === "string") {
+          reject(new Error("Failed to allocate port"));
+          return;
+        }
+        resolve(address.port);
+      });
+    });
+    server.on("error", reject);
+  });
+}
+
+function buildTemplateData(input: {
+  workspace: RealizedExecutionWorkspace;
+  agent: ExecutionWorkspaceAgentRef;
+  issue: ExecutionWorkspaceIssueRef | null;
+  adapterEnv: Record<string, string>;
+  port: number | null;
+}) {
+  return {
+    workspace: {
+      cwd: input.workspace.cwd,
+      branchName: input.workspace.branchName ?? "",
+      worktreePath: input.workspace.worktreePath ?? "",
+      repoUrl: input.workspace.repoUrl ?? "",
+      repoRef: input.workspace.repoRef ?? "",
+      env: input.adapterEnv,
+    },
+    issue: {
+      id: input.issue?.id ?? "",
+      identifier: input.issue?.identifier ?? "",
+      title: input.issue?.title ?? "",
+    },
+    agent: {
+      id: input.agent.id,
+      name: input.agent.name,
+    },
+    port: input.port ?? "",
+  };
+}
+
+function resolveServiceScopeId(input: {
+  service: Record<string, unknown>;
+  workspace: RealizedExecutionWorkspace;
+  issue: ExecutionWorkspaceIssueRef | null;
+  runId: string;
+  agent: ExecutionWorkspaceAgentRef;
+}): {
+  scopeType: "project_workspace" | "execution_workspace" | "run" | "agent";
+  scopeId: string | null;
+} {
+  const scopeTypeRaw = asString(input.service.reuseScope, input.service.lifecycle === "shared" ? "project_workspace" : "run");
+  const scopeType =
+    scopeTypeRaw === "project_workspace" ||
+    scopeTypeRaw === "execution_workspace" ||
+    scopeTypeRaw === "agent"
+      ? scopeTypeRaw
+      : "run";
+  if (scopeType === "project_workspace") return { scopeType, scopeId: input.workspace.workspaceId ?? input.workspace.projectId };
+  if (scopeType === "execution_workspace") return { scopeType, scopeId: input.workspace.cwd };
+  if (scopeType === "agent") return { scopeType, scopeId: input.agent.id };
+  return { scopeType: "run" as const, scopeId: input.runId };
+}
+
+async function waitForReadiness(input: {
+  service: Record<string, unknown>;
+  url: string | null;
+}) {
+  const readiness = parseObject(input.service.readiness);
+  const readinessType = asString(readiness.type, "");
+  if (readinessType !== "http" || !input.url) return;
+  const timeoutSec = Math.max(1, asNumber(readiness.timeoutSec, 30));
+  const intervalMs = Math.max(100, asNumber(readiness.intervalMs, 500));
+  const deadline = Date.now() + timeoutSec * 1000;
+  let lastError = "service did not become ready";
+  while (Date.now() < deadline) {
+    try {
+      const response = await fetch(input.url);
+      if (response.ok) return;
+      lastError = `received HTTP ${response.status}`;
+    } catch (err) {
+      lastError = err instanceof Error ? err.message : String(err);
+    }
+    await delay(intervalMs);
+  }
+  throw new Error(`Readiness check failed for ${input.url}: ${lastError}`);
+}
+
+function toPersistedWorkspaceRuntimeService(record: RuntimeServiceRecord): typeof workspaceRuntimeServices.$inferInsert {
+  return {
+    id: record.id,
+    companyId: record.companyId,
+    projectId: record.projectId,
+    projectWorkspaceId: record.projectWorkspaceId,
+    issueId: record.issueId,
+    scopeType: record.scopeType,
+    scopeId: record.scopeId,
+    serviceName: record.serviceName,
+    status: record.status,
+    lifecycle: record.lifecycle,
+    reuseKey: record.reuseKey,
+    command: record.command,
+    cwd: record.cwd,
+    port: record.port,
+    url: record.url,
+    provider: record.provider,
+    providerRef: record.providerRef,
+    ownerAgentId: record.ownerAgentId,
+    startedByRunId: record.startedByRunId,
+    lastUsedAt: new Date(record.lastUsedAt),
+    startedAt: new Date(record.startedAt),
+    stoppedAt: record.stoppedAt ? new Date(record.stoppedAt) : null,
+    stopPolicy: record.stopPolicy,
+    healthStatus: record.healthStatus,
+    updatedAt: new Date(),
+  };
+}
+
+async function persistRuntimeServiceRecord(db: Db | undefined, record: RuntimeServiceRecord) {
+  if (!db) return;
+  const values = toPersistedWorkspaceRuntimeService(record);
+  await db
+    .insert(workspaceRuntimeServices)
+    .values(values)
+    .onConflictDoUpdate({
+      target: workspaceRuntimeServices.id,
+      set: {
+        projectId: values.projectId,
+        projectWorkspaceId: values.projectWorkspaceId,
+        issueId: values.issueId,
+        scopeType: values.scopeType,
+        scopeId: values.scopeId,
+        serviceName: values.serviceName,
+        status: values.status,
+        lifecycle: values.lifecycle,
+        reuseKey: values.reuseKey,
+        command: values.command,
+        cwd: values.cwd,
+        port: values.port,
+        url: values.url,
+        provider: values.provider,
+        providerRef: values.providerRef,
+        ownerAgentId: values.ownerAgentId,
+        startedByRunId: values.startedByRunId,
+        lastUsedAt: values.lastUsedAt,
+        startedAt: values.startedAt,
+        stoppedAt: values.stoppedAt,
+        stopPolicy: values.stopPolicy,
+        healthStatus: values.healthStatus,
+        updatedAt: values.updatedAt,
+      },
+    });
+}
+
+function clearIdleTimer(record: RuntimeServiceRecord) {
+  if (!record.idleTimer) return;
+  clearTimeout(record.idleTimer);
+  record.idleTimer = null;
+}
+
+export function normalizeAdapterManagedRuntimeServices(input: {
+  adapterType: string;
+  runId: string;
+  agent: ExecutionWorkspaceAgentRef;
+  issue: ExecutionWorkspaceIssueRef | null;
+  workspace: RealizedExecutionWorkspace;
+  reports: AdapterRuntimeServiceReport[];
+  now?: Date;
+}): RuntimeServiceRef[] {
+  const nowIso = (input.now ?? new Date()).toISOString();
+  return input.reports.map((report) => {
+    const scopeType = report.scopeType ?? "run";
+    const scopeId =
+      report.scopeId ??
+      (scopeType === "project_workspace"
+        ? input.workspace.workspaceId
+        : scopeType === "execution_workspace"
+          ? input.workspace.cwd
+          : scopeType === "agent"
+            ? input.agent.id
+            : input.runId) ??
+      null;
+    const serviceName = asString(report.serviceName, "").trim() || "service";
+    const status = report.status ?? "running";
+    const lifecycle = report.lifecycle ?? "ephemeral";
+    const healthStatus =
+      report.healthStatus ??
+      (status === "running" ? "healthy" : status === "failed" ? "unhealthy" : "unknown");
+    return {
+      id: stableRuntimeServiceId({
+        adapterType: input.adapterType,
+        runId: input.runId,
+        scopeType,
+        scopeId,
+        serviceName,
+        reportId: report.id ?? null,
+        providerRef: report.providerRef ?? null,
+        reuseKey: report.reuseKey ?? null,
+      }),
+      companyId: input.agent.companyId,
+      projectId: report.projectId ?? input.workspace.projectId,
+      projectWorkspaceId: report.projectWorkspaceId ?? input.workspace.workspaceId,
+      issueId: report.issueId ?? input.issue?.id ?? null,
+      serviceName,
+      status,
+      lifecycle,
+      scopeType,
+      scopeId,
+      reuseKey: report.reuseKey ?? null,
+      command: report.command ?? null,
+      cwd: report.cwd ?? null,
+      port: report.port ?? null,
+      url: report.url ?? null,
+      provider: "adapter_managed",
+      providerRef: report.providerRef ?? null,
+      ownerAgentId: report.ownerAgentId ?? input.agent.id,
+      startedByRunId: input.runId,
+      lastUsedAt: nowIso,
+      startedAt: nowIso,
+      stoppedAt: status === "running" || status === "starting" ? null : nowIso,
+      stopPolicy: report.stopPolicy ?? null,
+      healthStatus,
+      reused: false,
+    };
+  });
+}
+
+async function startLocalRuntimeService(input: {
+  db?: Db;
+  runId: string;
+  agent: ExecutionWorkspaceAgentRef;
+  issue: ExecutionWorkspaceIssueRef | null;
+  workspace: RealizedExecutionWorkspace;
+  adapterEnv: Record<string, string>;
+  service: Record<string, unknown>;
+  onLog?: (stream: "stdout" | "stderr", chunk: string) => Promise<void>;
+  reuseKey: string | null;
+  scopeType: "project_workspace" | "execution_workspace" | "run" | "agent";
+  scopeId: string | null;
+}): Promise<RuntimeServiceRecord> {
+  const serviceName = asString(input.service.name, "service");
+  const lifecycle = asString(input.service.lifecycle, "shared") === "ephemeral" ? "ephemeral" : "shared";
+  const command = asString(input.service.command, "");
+  if (!command) throw new Error(`Runtime service "${serviceName}" is missing command`);
+  const serviceCwdTemplate = asString(input.service.cwd, ".");
+  const portConfig = parseObject(input.service.port);
+  const port = asString(portConfig.type, "") === "auto" ? await allocatePort() : null;
+  const envConfig = parseObject(input.service.env);
+  const templateData = buildTemplateData({
+    workspace: input.workspace,
+    agent: input.agent,
+    issue: input.issue,
+    adapterEnv: input.adapterEnv,
+    port,
+  });
+  const serviceCwd = resolveConfiguredPath(renderTemplate(serviceCwdTemplate, templateData), input.workspace.cwd);
+  const env: Record<string, string> = { ...process.env, ...input.adapterEnv } as Record<string, string>;
+  for (const [key, value] of Object.entries(envConfig)) {
+    if (typeof value === "string") {
+      env[key] = renderTemplate(value, templateData);
+    }
+  }
+  if (port) {
+    const portEnvKey = asString(portConfig.envKey, "PORT");
+    env[portEnvKey] = String(port);
+  }
+  const shell = process.env.SHELL?.trim() || "/bin/sh";
+  const child = spawn(shell, ["-lc", command], {
+    cwd: serviceCwd,
+    env,
+    detached: false,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  let stderrExcerpt = "";
+  let stdoutExcerpt = "";
+  child.stdout?.on("data", async (chunk) => {
+    const text = String(chunk);
+    stdoutExcerpt = (stdoutExcerpt + text).slice(-4096);
+    if (input.onLog) await input.onLog("stdout", `[service:${serviceName}] ${text}`);
+  });
+  child.stderr?.on("data", async (chunk) => {
+    const text = String(chunk);
+    stderrExcerpt = (stderrExcerpt + text).slice(-4096);
+    if (input.onLog) await input.onLog("stderr", `[service:${serviceName}] ${text}`);
+  });
+
+  const expose = parseObject(input.service.expose);
+  const readiness = parseObject(input.service.readiness);
+  const urlTemplate =
+    asString(expose.urlTemplate, "") ||
+    asString(readiness.urlTemplate, "");
+  const url = urlTemplate ? renderTemplate(urlTemplate, templateData) : null;
+
+  try {
+    await waitForReadiness({ service: input.service, url });
+  } catch (err) {
+    child.kill("SIGTERM");
+    throw new Error(
+      `Failed to start runtime service "${serviceName}": ${err instanceof Error ? err.message : String(err)}${stderrExcerpt ? ` | stderr: ${stderrExcerpt.trim()}` : ""}`,
+    );
+  }
+
+  const envFingerprint = createHash("sha256").update(stableStringify(envConfig)).digest("hex");
+  return {
+    id: randomUUID(),
+    companyId: input.agent.companyId,
+    projectId: input.workspace.projectId,
+    projectWorkspaceId: input.workspace.workspaceId,
+    issueId: input.issue?.id ?? null,
+    serviceName,
+    status: "running",
+    lifecycle,
+    scopeType: input.scopeType,
+    scopeId: input.scopeId,
+    reuseKey: input.reuseKey,
+    command,
+    cwd: serviceCwd,
+    port,
+    url,
+    provider: "local_process",
+    providerRef: child.pid ? String(child.pid) : null,
+    ownerAgentId: input.agent.id,
+    startedByRunId: input.runId,
+    lastUsedAt: new Date().toISOString(),
+    startedAt: new Date().toISOString(),
+    stoppedAt: null,
+    stopPolicy: parseObject(input.service.stopPolicy),
+    healthStatus: "healthy",
+    reused: false,
+    db: input.db,
+    child,
+    leaseRunIds: new Set([input.runId]),
+    idleTimer: null,
+    envFingerprint,
+  };
+}
+
+function scheduleIdleStop(record: RuntimeServiceRecord) {
+  clearIdleTimer(record);
+  const stopType = asString(record.stopPolicy?.type, "manual");
+  if (stopType !== "idle_timeout") return;
+  const idleSeconds = Math.max(1, asNumber(record.stopPolicy?.idleSeconds, 1800));
+  record.idleTimer = setTimeout(() => {
+    stopRuntimeService(record.id).catch(() => undefined);
+  }, idleSeconds * 1000);
+}
+
+async function stopRuntimeService(serviceId: string) {
+  const record = runtimeServicesById.get(serviceId);
+  if (!record) return;
+  clearIdleTimer(record);
+  record.status = "stopped";
+  record.lastUsedAt = new Date().toISOString();
+  record.stoppedAt = new Date().toISOString();
+  if (record.child && !record.child.killed) {
+    record.child.kill("SIGTERM");
+  }
+  runtimeServicesById.delete(serviceId);
+  if (record.reuseKey) {
+    runtimeServicesByReuseKey.delete(record.reuseKey);
+  }
+  await persistRuntimeServiceRecord(record.db, record);
+}
+
+function registerRuntimeService(db: Db | undefined, record: RuntimeServiceRecord) {
+  record.db = db;
+  runtimeServicesById.set(record.id, record);
+  if (record.reuseKey) {
+    runtimeServicesByReuseKey.set(record.reuseKey, record.id);
+  }
+
+  record.child?.on("exit", (code, signal) => {
+    const current = runtimeServicesById.get(record.id);
+    if (!current) return;
+    clearIdleTimer(current);
+    current.status = code === 0 || signal === "SIGTERM" ? "stopped" : "failed";
+    current.healthStatus = current.status === "failed" ? "unhealthy" : "unknown";
+    current.lastUsedAt = new Date().toISOString();
+    current.stoppedAt = new Date().toISOString();
+    runtimeServicesById.delete(current.id);
+    if (current.reuseKey && runtimeServicesByReuseKey.get(current.reuseKey) === current.id) {
+      runtimeServicesByReuseKey.delete(current.reuseKey);
+    }
+    void persistRuntimeServiceRecord(db, current);
+  });
+}
+
+export async function ensureRuntimeServicesForRun(input: {
+  db?: Db;
+  runId: string;
+  agent: ExecutionWorkspaceAgentRef;
+  issue: ExecutionWorkspaceIssueRef | null;
+  workspace: RealizedExecutionWorkspace;
+  config: Record<string, unknown>;
+  adapterEnv: Record<string, string>;
+  onLog?: (stream: "stdout" | "stderr", chunk: string) => Promise<void>;
+}): Promise<RuntimeServiceRef[]> {
+  const runtime = parseObject(input.config.workspaceRuntime);
+  const rawServices = Array.isArray(runtime.services)
+    ? runtime.services.filter((entry): entry is Record<string, unknown> => typeof entry === "object" && entry !== null)
+    : [];
+  const acquiredServiceIds: string[] = [];
+  const refs: RuntimeServiceRef[] = [];
+  runtimeServiceLeasesByRun.set(input.runId, acquiredServiceIds);
+
+  try {
+    for (const service of rawServices) {
+      const lifecycle = asString(service.lifecycle, "shared") === "ephemeral" ? "ephemeral" : "shared";
+      const { scopeType, scopeId } = resolveServiceScopeId({
+        service,
+        workspace: input.workspace,
+        issue: input.issue,
+        runId: input.runId,
+        agent: input.agent,
+      });
+      const envConfig = parseObject(service.env);
+      const envFingerprint = createHash("sha256").update(stableStringify(envConfig)).digest("hex");
+      const serviceName = asString(service.name, "service");
+      const reuseKey =
+        lifecycle === "shared"
+          ? [scopeType, scopeId ?? "", serviceName, envFingerprint].join(":")
+          : null;
+
+      if (reuseKey) {
+        const existingId = runtimeServicesByReuseKey.get(reuseKey);
+        const existing = existingId ? runtimeServicesById.get(existingId) : null;
+        if (existing && existing.status === "running") {
+          existing.leaseRunIds.add(input.runId);
+          existing.lastUsedAt = new Date().toISOString();
+          existing.stoppedAt = null;
+          clearIdleTimer(existing);
+          await persistRuntimeServiceRecord(input.db, existing);
+          acquiredServiceIds.push(existing.id);
+          refs.push(toRuntimeServiceRef(existing, { reused: true }));
+          continue;
+        }
+      }
+
+      const record = await startLocalRuntimeService({
+        db: input.db,
+        runId: input.runId,
+        agent: input.agent,
+        issue: input.issue,
+        workspace: input.workspace,
+        adapterEnv: input.adapterEnv,
+        service,
+        onLog: input.onLog,
+        reuseKey,
+        scopeType,
+        scopeId,
+      });
+      registerRuntimeService(input.db, record);
+      await persistRuntimeServiceRecord(input.db, record);
+      acquiredServiceIds.push(record.id);
+      refs.push(toRuntimeServiceRef(record));
+    }
+  } catch (err) {
+    await releaseRuntimeServicesForRun(input.runId);
+    throw err;
+  }
+
+  return refs;
+}
+
+export async function releaseRuntimeServicesForRun(runId: string) {
+  const acquired = runtimeServiceLeasesByRun.get(runId) ?? [];
+  runtimeServiceLeasesByRun.delete(runId);
+  for (const serviceId of acquired) {
+    const record = runtimeServicesById.get(serviceId);
+    if (!record) continue;
+    record.leaseRunIds.delete(runId);
+    record.lastUsedAt = new Date().toISOString();
+    const stopType = asString(record.stopPolicy?.type, record.lifecycle === "ephemeral" ? "on_run_finish" : "manual");
+    await persistRuntimeServiceRecord(record.db, record);
+    if (record.leaseRunIds.size === 0) {
+      if (record.lifecycle === "ephemeral" || stopType === "on_run_finish") {
+        await stopRuntimeService(serviceId);
+        continue;
+      }
+      scheduleIdleStop(record);
+    }
+  }
+}
+
+export async function listWorkspaceRuntimeServicesForProjectWorkspaces(
+  db: Db,
+  companyId: string,
+  projectWorkspaceIds: string[],
+) {
+  if (projectWorkspaceIds.length === 0) return new Map<string, typeof workspaceRuntimeServices.$inferSelect[]>();
+  const rows = await db
+    .select()
+    .from(workspaceRuntimeServices)
+    .where(
+      and(
+        eq(workspaceRuntimeServices.companyId, companyId),
+        inArray(workspaceRuntimeServices.projectWorkspaceId, projectWorkspaceIds),
+      ),
+    )
+    .orderBy(desc(workspaceRuntimeServices.updatedAt), desc(workspaceRuntimeServices.createdAt));
+
+  const grouped = new Map<string, typeof workspaceRuntimeServices.$inferSelect[]>();
+  for (const row of rows) {
+    if (!row.projectWorkspaceId) continue;
+    const existing = grouped.get(row.projectWorkspaceId);
+    if (existing) existing.push(row);
+    else grouped.set(row.projectWorkspaceId, [row]);
+  }
+  return grouped;
+}
+
+export async function reconcilePersistedRuntimeServicesOnStartup(db: Db) {
+  const staleRows = await db
+    .select({ id: workspaceRuntimeServices.id })
+    .from(workspaceRuntimeServices)
+    .where(
+      and(
+        eq(workspaceRuntimeServices.provider, "local_process"),
+        inArray(workspaceRuntimeServices.status, ["starting", "running"]),
+      ),
+    );
+
+  if (staleRows.length === 0) return { reconciled: 0 };
+
+  const now = new Date();
+  await db
+    .update(workspaceRuntimeServices)
+    .set({
+      status: "stopped",
+      healthStatus: "unknown",
+      stoppedAt: now,
+      lastUsedAt: now,
+      updatedAt: now,
+    })
+    .where(
+      and(
+        eq(workspaceRuntimeServices.provider, "local_process"),
+        inArray(workspaceRuntimeServices.status, ["starting", "running"]),
+      ),
+    );
+
+  return { reconciled: staleRows.length };
+}
+
+export async function persistAdapterManagedRuntimeServices(input: {
+  db: Db;
+  adapterType: string;
+  runId: string;
+  agent: ExecutionWorkspaceAgentRef;
+  issue: ExecutionWorkspaceIssueRef | null;
+  workspace: RealizedExecutionWorkspace;
+  reports: AdapterRuntimeServiceReport[];
+}) {
+  const refs = normalizeAdapterManagedRuntimeServices(input);
+  if (refs.length === 0) return refs;
+
+  const existingRows = await input.db
+    .select()
+    .from(workspaceRuntimeServices)
+    .where(inArray(workspaceRuntimeServices.id, refs.map((ref) => ref.id)));
+  const existingById = new Map(existingRows.map((row) => [row.id, row]));
+
+  for (const ref of refs) {
+    const existing = existingById.get(ref.id);
+    const startedAt = existing?.startedAt ?? new Date(ref.startedAt);
+    const createdAt = existing?.createdAt ?? new Date();
+    await input.db
+      .insert(workspaceRuntimeServices)
+      .values({
+        id: ref.id,
+        companyId: ref.companyId,
+        projectId: ref.projectId,
+        projectWorkspaceId: ref.projectWorkspaceId,
+        issueId: ref.issueId,
+        scopeType: ref.scopeType,
+        scopeId: ref.scopeId,
+        serviceName: ref.serviceName,
+        status: ref.status,
+        lifecycle: ref.lifecycle,
+        reuseKey: ref.reuseKey,
+        command: ref.command,
+        cwd: ref.cwd,
+        port: ref.port,
+        url: ref.url,
+        provider: ref.provider,
+        providerRef: ref.providerRef,
+        ownerAgentId: ref.ownerAgentId,
+        startedByRunId: ref.startedByRunId,
+        lastUsedAt: new Date(ref.lastUsedAt),
+        startedAt,
+        stoppedAt: ref.stoppedAt ? new Date(ref.stoppedAt) : null,
+        stopPolicy: ref.stopPolicy,
+        healthStatus: ref.healthStatus,
+        createdAt,
+        updatedAt: new Date(),
+      })
+      .onConflictDoUpdate({
+        target: workspaceRuntimeServices.id,
+        set: {
+          projectId: ref.projectId,
+          projectWorkspaceId: ref.projectWorkspaceId,
+          issueId: ref.issueId,
+          scopeType: ref.scopeType,
+          scopeId: ref.scopeId,
+          serviceName: ref.serviceName,
+          status: ref.status,
+          lifecycle: ref.lifecycle,
+          reuseKey: ref.reuseKey,
+          command: ref.command,
+          cwd: ref.cwd,
+          port: ref.port,
+          url: ref.url,
+          provider: ref.provider,
+          providerRef: ref.providerRef,
+          ownerAgentId: ref.ownerAgentId,
+          startedByRunId: ref.startedByRunId,
+          lastUsedAt: new Date(ref.lastUsedAt),
+          startedAt,
+          stoppedAt: ref.stoppedAt ? new Date(ref.stoppedAt) : null,
+          stopPolicy: ref.stopPolicy,
+          healthStatus: ref.healthStatus,
+          updatedAt: new Date(),
+        },
+      });
+  }
+
+  return refs;
+}
+
+export function buildWorkspaceReadyComment(input: {
+  workspace: RealizedExecutionWorkspace;
+  runtimeServices: RuntimeServiceRef[];
+}) {
+  const lines = ["## Workspace Ready", ""];
+  lines.push(`- Strategy: \`${input.workspace.strategy}\``);
+  if (input.workspace.branchName) lines.push(`- Branch: \`${input.workspace.branchName}\``);
+  lines.push(`- CWD: \`${input.workspace.cwd}\``);
+  if (input.workspace.worktreePath && input.workspace.worktreePath !== input.workspace.cwd) {
+    lines.push(`- Worktree: \`${input.workspace.worktreePath}\``);
+  }
+  for (const service of input.runtimeServices) {
+    const detail = service.url ? `${service.serviceName}: ${service.url}` : `${service.serviceName}: running`;
+    const suffix = service.reused ? " (reused)" : "";
+    lines.push(`- Service: ${detail}${suffix}`);
+  }
+  return lines.join("\n");
+}