Merge remote-tracking branch 'public-gh/master' into PAP-989-multi-user-implementation-using-plan-from-pap-958

* public-gh/master: (32 commits)
  fix(dev-runner): tighten worktree env bootstrap
  fix(inbox): avoid refetching on filter-only changes
  fix(codex-local): avoid fast mode in env probe
  fix: isolate dev runner worktree env
  Broaden comment matches in issue search
  Add inbox issue search fallback
  feat(codex-local): add fast mode support
  Harden tailnet bind setup
  Fix dev runner workspace import regression
  Introduce bind presets for deployment setup
  fix: address PR 3355 review regressions
  test(ui): fix heartbeat run fixture drift
  fix: restore inbox optimistic run fixture
  fix: keep thread polish independent of quicklook routing
  fix: keep runtime UI changes self-contained
  fix: keep inbox quicklook and tests standalone
  fix: use CLI tsx entrypoint for workspace preflight
  chore: improve worktree tooling and security docs
  feat: polish issue thread markdown and references
  fix: harden heartbeat and adapter runtime workflows
  ...

# Conflicts:
#	cli/src/__tests__/worktree.test.ts
#	scripts/ensure-workspace-package-links.ts
#	server/src/__tests__/claude-local-execute.test.ts
#	server/src/__tests__/issues-service.test.ts
#	ui/src/components/Layout.tsx

.agents/skills/deal-with-security-advisory/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: deal-with-security-advisory
+description: >
+  Handle a GitHub Security Advisory response for Paperclip, including
+  confidential fix development in a temporary private fork, human coordination
+  on advisory-thread comments, CVE request, synchronized advisory publication,
+  and immediate security release steps.
+---
+
+# Security Vulnerability Response Instructions
+
+## ⚠️ CRITICAL: This is a security vulnerability. Everything about this process is confidential until the advisory is published. Do not mention the vulnerability details in any public commit message, PR title, branch name, or comment. Do not push anything to a public branch. Do not discuss specifics in any public channel. Assume anything on the public repo is visible to attackers who will exploit the window between disclosure and user upgrades.
+
+***
+
+## Context
+
+A security vulnerability has been reported via GitHub Security Advisory:
+
+* **Advisory:** {{ghsaId}} (e.g. GHSA-x8hx-rhr2-9rf7)
+* **Reporter:** {{reporterHandle}}
+* **Severity:** {{severity}}
+* **Notes:** {{notes}}
+
+***
+
+## Step 0: Fetch the Advisory Details
+
+Pull the full advisory so you understand the vulnerability before doing anything else:
+
+```
+gh api repos/paperclipai/paperclip/security-advisories/{{ghsaId}}
+
+```
+
+Read the `description`, `severity`, `cvss`, and `vulnerabilities` fields. Understand the attack vector before writing code.
+
+## Step 1: Acknowledge the Report
+
+⚠️ **This step requires a human.** The advisory thread does not have a comment API. Ask the human operator to post a comment on the private advisory thread acknowledging the report. Provide them this template:
+
+> Thanks for the report, @{{reporterHandle}}. We've confirmed the issue and are working on a fix. We're targeting a patch release within {{timeframe}}. We'll keep you updated here.
+
+Give your human this template, but still continue
+
+Below we use `gh` tools - you do have access and credentials outside of your sandbox, so use them.
+
+## Step 2: Create the Temporary Private Fork
+
+This is where all fix development happens. Never push to the public repo.
+
+```
+gh api --method POST \
+  repos/paperclipai/paperclip/security-advisories/{{ghsaId}}/forks
+
+```
+
+This returns a repository object for the private fork. Save the `full_name` and `clone_url`.
+
+Clone it and set up your workspace:
+
+```
+# Clone the private fork somewhere outside ~/paperclip
+git clone <clone_url_from_response> ~/security-patch-{{ghsaId}}
+cd ~/security-patch-{{ghsaId}}
+git checkout -b security-fix
+
+```
+
+**Do not edit `~/paperclip`** — the dev server is running off the `~/paperclip` master branch and we don't want to touch it. All work happens in the private fork clone.
+
+**TIPS:**
+
+* Do not commit `pnpm-lock.yaml` — the repo has actions to manage this
+* Do not use descriptive branch names that leak the vulnerability (e.g., no `fix-dns-rebinding-rce`). Use something generic like `security-fix`
+* All work stays in the private fork until publication
+* CI/GitHub Actions will NOT run on the temporary private fork — this is a GitHub limitation by design. You must run tests locally
+
+## Step 3: Develop and Validate the Fix
+
+Write the patch. Same content standards as any PR:
+
+* It must functionally work — **run tests locally** since CI won't run on the private fork
+* Consider the whole codebase, not just the narrow vulnerability path. A patch that fixes one vector but opens another is worse than no patch
+* Ensure backwards compatibility for the database, or be explicit about what breaks
+* Make sure any UI components still look correct if the fix touches them
+* The fix should be minimal and focused — don't bundle unrelated changes into a security patch. Reviewers (and the reporter) should be able to read the diff and understand exactly what changed and why
+
+**Specific to security fixes:**
+
+* Verify the fix actually closes the attack vector described in the advisory. Reproduce the vulnerability first (using the reporter's description), then confirm the patch prevents it
+* Consider adjacent attack vectors — if DNS rebinding is the issue, are there other endpoints or modes with the same class of problem?
+* Do not introduce new dependencies unless absolutely necessary — new deps in a security patch raise eyebrows
+
+Push your fix to the private fork:
+
+```
+git add -A
+git commit -m "Fix security vulnerability"
+git push origin security-fix
+
+```
+
+## Step 4: Coordinate with the Reporter
+
+⚠️ **This step requires a human.** Ask the human operator to post on the advisory thread letting the reporter know the fix is ready and giving them a chance to review. Provide them this template:
+
+> @{{reporterHandle}} — fix is ready in the private fork if you'd like to review before we publish. Planning to release within {{timeframe}}.
+
+Proceed
+
+## Step 5: Request a CVE
+
+This makes vulnerability scanners (npm audit, Snyk, Dependabot) warn users to upgrade. Without it, nobody gets automated notification.
+
+```
+gh api --method POST \
+  repos/paperclipai/paperclip/security-advisories/{{ghsaId}}/cve
+
+```
+
+GitHub is a CVE Numbering Authority and will assign one automatically. The CVE may take a few hours to propagate after the advisory is published.
+
+## Step 6: Publish Everything Simultaneously
+
+This all happens at once — do not stagger these steps. The goal is **zero window** between the vulnerability becoming public knowledge and the fix being available.
+
+### 6a. Verify reporter credit before publishing
+
+```
+gh api repos/paperclipai/paperclip/security-advisories/{{ghsaId}} --jq '.credits'
+
+```
+
+If the reporter is not credited, add them:
+
+```
+gh api --method PATCH \
+  repos/paperclipai/paperclip/security-advisories/{{ghsaId}} \
+  --input - << 'EOF'
+{
+  "credits": [
+    {
+      "login": "{{reporterHandle}}",
+      "type": "reporter"
+    }
+  ]
+}
+EOF
+
+```
+
+### 6b. Update the advisory with the patched version and publish
+
+```
+gh api --method PATCH \
+  repos/paperclipai/paperclip/security-advisories/{{ghsaId}} \
+  --input - << 'EOF'
+{
+  "state": "published",
+  "vulnerabilities": [
+    {
+      "package": {
+        "ecosystem": "npm",
+        "name": "paperclip"
+      },
+      "vulnerable_version_range": "< {{patchedVersion}}",
+      "patched_versions": "{{patchedVersion}}"
+    }
+  ]
+}
+EOF
+
+```
+
+Publishing the advisory simultaneously:
+
+* Makes the GHSA public
+* Merges the temporary private fork into your repo
+* Triggers the CVE assignment (if requested in step 5)
+
+### 6c. Cut a release immediately after merge
+
+```
+cd ~/paperclip
+git pull origin master
+
+gh release create v{{patchedVersion}} \
+  --repo paperclipai/paperclip \
+  --title "v{{patchedVersion}} — Security Release" \
+  --notes "## Security Release
+
+This release fixes a critical security vulnerability.
+
+### What was fixed
+{{briefDescription}} (e.g., Remote code execution via DNS rebinding in \`local_trusted\` mode)
+
+### Advisory
+https://github.com/paperclipai/paperclip/security/advisories/{{ghsaId}}
+
+### Credit
+Thanks to @{{reporterHandle}} for responsibly disclosing this vulnerability.
+
+### Action required
+All users running versions prior to {{patchedVersion}} should upgrade immediately."
+
+```
+
+## Step 7: Post-Publication Verification
+
+```
+# Verify the advisory is published and CVE is assigned
+gh api repos/paperclipai/paperclip/security-advisories/{{ghsaId}} \
+  --jq '{state: .state, cve_id: .cve_id, published_at: .published_at}'
+
+# Verify the release exists
+gh release view v{{patchedVersion}} --repo paperclipai/paperclip
+
+```
+
+If the CVE hasn't been assigned yet, that's normal — it can take a few hours.
+
+⚠️ **Human step:** Ask the human operator to post a final comment on the advisory thread confirming publication and thanking the reporter.
+
+Tell the human operator what you did by posting a comment to this task, including:
+
+* The published advisory URL: `https://github.com/paperclipai/paperclip/security/advisories/{{ghsaId}}`
+* The release URL
+* Whether the CVE has been assigned yet
+* All URLs to any pull requests or branches

.mailmap

@@ -1 +1,3 @@
-Dotta <bippadotta@protonmail.com> Forgotten <forgottenrunes@protonmail.com>
+Dotta <bippadotta@protonmail.com> <34892728+cryppadotta@users.noreply.github.com>
+Dotta <bippadotta@protonmail.com> <forgottenrunes@protonmail.com>
+Dotta <bippadotta@protonmail.com> <dotta@example.com>

README.md

@@ -177,6 +177,14 @@ Open source. Self-hosted. No Paperclip account required.
 npx paperclipai onboard --yes
 ```
 
+That quickstart path now defaults to trusted local loopback mode for the fastest first run. To start in authenticated/private mode instead, choose a bind preset explicitly:
+
+```bash
+npx paperclipai onboard --yes --bind lan
+# or:
+npx paperclipai onboard --yes --bind tailnet
+```
+
 If you already have Paperclip configured, rerunning `onboard` keeps the existing config in place. Use `paperclipai configure` to edit settings.
 
 Or manually:
@@ -243,11 +251,18 @@ See [doc/DEVELOPING.md](doc/DEVELOPING.md) for the full development guide.
 - ✅ Skills Manager
 - ✅ Scheduled Routines
 - ✅ Better Budgeting
-- ⚪ Artifacts & Deployments
-- ⚪ CEO Chat
-- ⚪ MAXIMIZER MODE
+- ✅ Agent Reviews and Approvals
 - ⚪ Multiple Human Users
 - ⚪ Cloud / Sandbox agents (e.g. Cursor / e2b agents)
+- ⚪ Artifacts & Work Products
+- ⚪ Memory & Knowledge
+- ⚪ Enforced Outcomes
+- ⚪ MAXIMIZER MODE
+- ⚪ Deep Planning
+- ⚪ Work Queues
+- ⚪ Self-Organization
+- ⚪ Automatic Organizational Learning
+- ⚪ CEO Chat
 - ⚪ Cloud deployments
 - ⚪ Desktop App
 
@@ -263,12 +278,12 @@ Paperclip collects anonymous usage telemetry to help us understand how the produ
 
 Telemetry is **enabled by default** and can be disabled with any of the following:
 
-| Method | How |
-|---|---|
-| Environment variable | `PAPERCLIP_TELEMETRY_DISABLED=1` |
-| Standard convention | `DO_NOT_TRACK=1` |
-| CI environments | Automatically disabled when `CI=true` |
-| Config file | Set `telemetry.enabled: false` in your Paperclip config |
+| Method               | How                                                     |
+| -------------------- | ------------------------------------------------------- |
+| Environment variable | `PAPERCLIP_TELEMETRY_DISABLED=1`                        |
+| Standard convention  | `DO_NOT_TRACK=1`                                        |
+| CI environments      | Automatically disabled when `CI=true`                   |
+| Config file          | Set `telemetry.enabled: false` in your Paperclip config |
 
 ## Contributing
 

SECURITY.md

@@ -0,0 +1,8 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+Please report security vulnerabilities through GitHub's Security Advisory feature:
+[https://github.com/paperclipai/paperclip/security/advisories/new](https://github.com/paperclipai/paperclip/security/advisories/new)
+
+Do not open public issues for security vulnerabilities.

cli/README.md

@@ -177,6 +177,14 @@ Open source. Self-hosted. No Paperclip account required.
 npx paperclipai onboard --yes
 ```
 
+That quickstart path now defaults to trusted local loopback mode for the fastest first run. To start in authenticated/private mode instead, choose a bind preset explicitly:
+
+```bash
+npx paperclipai onboard --yes --bind lan
+# or:
+npx paperclipai onboard --yes --bind tailnet
+```
+
 If you already have Paperclip configured, rerunning `onboard` keeps the existing config in place. Use `paperclipai configure` to edit settings.
 
 Or manually:

cli/src/__tests__/network-bind.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from "vitest";
+import { resolveRuntimeBind, validateConfiguredBindMode } from "@paperclipai/shared";
+import { buildPresetServerConfig } from "../config/server-bind.js";
+
+describe("network bind helpers", () => {
+  it("rejects non-loopback bind modes in local_trusted", () => {
+    expect(
+      validateConfiguredBindMode({
+        deploymentMode: "local_trusted",
+        deploymentExposure: "private",
+        bind: "lan",
+        host: "0.0.0.0",
+      }),
+    ).toContain("local_trusted requires server.bind=loopback");
+  });
+
+  it("resolves tailnet bind using the detected tailscale address", () => {
+    const resolved = resolveRuntimeBind({
+      bind: "tailnet",
+      host: "127.0.0.1",
+      tailnetBindHost: "100.64.0.8",
+    });
+
+    expect(resolved.errors).toEqual([]);
+    expect(resolved.host).toBe("100.64.0.8");
+  });
+
+  it("requires a custom bind host when bind=custom", () => {
+    const resolved = resolveRuntimeBind({
+      bind: "custom",
+      host: "127.0.0.1",
+    });
+
+    expect(resolved.errors).toContain("server.customBindHost is required when server.bind=custom");
+  });
+
+  it("stores the detected tailscale address for tailnet presets", () => {
+    process.env.PAPERCLIP_TAILNET_BIND_HOST = "100.64.0.8";
+
+    const preset = buildPresetServerConfig("tailnet", {
+      port: 3100,
+      allowedHostnames: [],
+      serveUi: true,
+    });
+
+    expect(preset.server.host).toBe("100.64.0.8");
+
+    delete process.env.PAPERCLIP_TAILNET_BIND_HOST;
+  });
+
+  it("falls back to loopback when no tailscale address is available for tailnet presets", () => {
+    delete process.env.PAPERCLIP_TAILNET_BIND_HOST;
+
+    const preset = buildPresetServerConfig("tailnet", {
+      port: 3100,
+      allowedHostnames: [],
+      serveUi: true,
+    });
+
+    expect(preset.server.host).toBe("127.0.0.1");
+  });
+});

cli/src/__tests__/onboard.test.ts

@@ -74,6 +74,11 @@ function createExistingConfigFixture() {
   return { configPath, configText: fs.readFileSync(configPath, "utf8") };
 }
 
+function createFreshConfigPath() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-onboard-fresh-"));
+  return path.join(root, ".paperclip", "config.json");
+}
+
 describe("onboard", () => {
   beforeEach(() => {
     process.env = { ...ORIGINAL_ENV };
@@ -105,4 +110,57 @@ describe("onboard", () => {
     expect(fs.existsSync(`${fixture.configPath}.backup`)).toBe(false);
     expect(fs.existsSync(path.join(path.dirname(fixture.configPath), ".env"))).toBe(true);
   });
+
+  it("keeps --yes onboarding on local trusted loopback defaults", async () => {
+    const configPath = createFreshConfigPath();
+    process.env.HOST = "0.0.0.0";
+    process.env.PAPERCLIP_BIND = "lan";
+
+    await onboard({ config: configPath, yes: true, invokedByRun: true });
+
+    const raw = JSON.parse(fs.readFileSync(configPath, "utf8")) as PaperclipConfig;
+    expect(raw.server.deploymentMode).toBe("local_trusted");
+    expect(raw.server.exposure).toBe("private");
+    expect(raw.server.bind).toBe("loopback");
+    expect(raw.server.host).toBe("127.0.0.1");
+  });
+
+  it("supports authenticated/private quickstart bind presets", async () => {
+    const configPath = createFreshConfigPath();
+    process.env.PAPERCLIP_TAILNET_BIND_HOST = "100.64.0.8";
+
+    await onboard({ config: configPath, yes: true, invokedByRun: true, bind: "tailnet" });
+
+    const raw = JSON.parse(fs.readFileSync(configPath, "utf8")) as PaperclipConfig;
+    expect(raw.server.deploymentMode).toBe("authenticated");
+    expect(raw.server.exposure).toBe("private");
+    expect(raw.server.bind).toBe("tailnet");
+    expect(raw.server.host).toBe("100.64.0.8");
+  });
+
+  it("keeps tailnet quickstart on loopback until tailscale is available", async () => {
+    const configPath = createFreshConfigPath();
+    delete process.env.PAPERCLIP_TAILNET_BIND_HOST;
+
+    await onboard({ config: configPath, yes: true, invokedByRun: true, bind: "tailnet" });
+
+    const raw = JSON.parse(fs.readFileSync(configPath, "utf8")) as PaperclipConfig;
+    expect(raw.server.deploymentMode).toBe("authenticated");
+    expect(raw.server.exposure).toBe("private");
+    expect(raw.server.bind).toBe("tailnet");
+    expect(raw.server.host).toBe("127.0.0.1");
+  });
+
+  it("ignores deployment env overrides during --yes quickstart", async () => {
+    const configPath = createFreshConfigPath();
+    process.env.PAPERCLIP_DEPLOYMENT_MODE = "authenticated";
+
+    await onboard({ config: configPath, yes: true, invokedByRun: true });
+
+    const raw = JSON.parse(fs.readFileSync(configPath, "utf8")) as PaperclipConfig;
+    expect(raw.server.deploymentMode).toBe("local_trusted");
+    expect(raw.server.exposure).toBe("private");
+    expect(raw.server.bind).toBe("loopback");
+    expect(raw.server.host).toBe("127.0.0.1");
+  });
 });

cli/src/__tests__/worktree.test.ts

@@ -2,11 +2,21 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
-import { authUsers, createDb, getEmbeddedPostgresTestSupport, startEmbeddedPostgresTestDatabase } from "@paperclipai/db";
+import { randomUUID } from "node:crypto";
 import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  agents,
+  authUsers,
+  companies,
+  createDb,
+  projects,
+  routines,
+  routineTriggers,
+} from "@paperclipai/db";
 import {
   copyGitHooksToWorktreeGitDir,
   copySeededSecretsKey,
+  pauseSeededScheduledRoutines,
   readSourceAttachmentBody,
   rebindWorkspaceCwd,
   resolveSourceConfigPath,
@@ -29,11 +39,22 @@ import {
   sanitizeWorktreeInstanceId,
 } from "../commands/worktree-lib.js";
 import type { PaperclipConfig } from "../config/schema.js";
+import {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+} from "./helpers/embedded-postgres.js";
 
 const ORIGINAL_CWD = process.cwd();
 const ORIGINAL_ENV = { ...process.env };
 const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
 const itEmbeddedPostgres = embeddedPostgresSupport.supported ? it : it.skip;
+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
+
+if (!embeddedPostgresSupport.supported) {
+  console.warn(
+    `Skipping embedded Postgres worktree CLI tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,
+  );
+}
 
 afterEach(() => {
   process.chdir(ORIGINAL_CWD);
@@ -917,3 +938,138 @@ describe("worktree helpers", () => {
     }
   }, 20_000);
 });
+
+describeEmbeddedPostgres("pauseSeededScheduledRoutines", () => {
+  it("pauses only routines with enabled schedule triggers", async () => {
+    const tempDb = await startEmbeddedPostgresTestDatabase("paperclip-worktree-routines-");
+    const db = createDb(tempDb.connectionString);
+    const companyId = randomUUID();
+    const projectId = randomUUID();
+    const agentId = randomUUID();
+    const activeScheduledRoutineId = randomUUID();
+    const activeApiRoutineId = randomUUID();
+    const pausedScheduledRoutineId = randomUUID();
+    const archivedScheduledRoutineId = randomUUID();
+    const disabledScheduleRoutineId = randomUUID();
+
+    try {
+      await db.insert(companies).values({
+        id: companyId,
+        name: "Paperclip",
+        issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+        requireBoardApprovalForNewAgents: false,
+      });
+      await db.insert(agents).values({
+        id: agentId,
+        companyId,
+        name: "Coder",
+        adapterType: "process",
+        adapterConfig: {},
+        runtimeConfig: {},
+        permissions: {},
+      });
+      await db.insert(projects).values({
+        id: projectId,
+        companyId,
+        name: "Project",
+        status: "in_progress",
+      });
+      await db.insert(routines).values([
+        {
+          id: activeScheduledRoutineId,
+          companyId,
+          projectId,
+          assigneeAgentId: agentId,
+          title: "Active scheduled",
+          status: "active",
+        },
+        {
+          id: activeApiRoutineId,
+          companyId,
+          projectId,
+          assigneeAgentId: agentId,
+          title: "Active API",
+          status: "active",
+        },
+        {
+          id: pausedScheduledRoutineId,
+          companyId,
+          projectId,
+          assigneeAgentId: agentId,
+          title: "Paused scheduled",
+          status: "paused",
+        },
+        {
+          id: archivedScheduledRoutineId,
+          companyId,
+          projectId,
+          assigneeAgentId: agentId,
+          title: "Archived scheduled",
+          status: "archived",
+        },
+        {
+          id: disabledScheduleRoutineId,
+          companyId,
+          projectId,
+          assigneeAgentId: agentId,
+          title: "Disabled schedule",
+          status: "active",
+        },
+      ]);
+      await db.insert(routineTriggers).values([
+        {
+          companyId,
+          routineId: activeScheduledRoutineId,
+          kind: "schedule",
+          enabled: true,
+          cronExpression: "0 9 * * *",
+          timezone: "UTC",
+        },
+        {
+          companyId,
+          routineId: activeApiRoutineId,
+          kind: "api",
+          enabled: true,
+        },
+        {
+          companyId,
+          routineId: pausedScheduledRoutineId,
+          kind: "schedule",
+          enabled: true,
+          cronExpression: "0 10 * * *",
+          timezone: "UTC",
+        },
+        {
+          companyId,
+          routineId: archivedScheduledRoutineId,
+          kind: "schedule",
+          enabled: true,
+          cronExpression: "0 11 * * *",
+          timezone: "UTC",
+        },
+        {
+          companyId,
+          routineId: disabledScheduleRoutineId,
+          kind: "schedule",
+          enabled: false,
+          cronExpression: "0 12 * * *",
+          timezone: "UTC",
+        },
+      ]);
+
+      const pausedCount = await pauseSeededScheduledRoutines(tempDb.connectionString);
+      expect(pausedCount).toBe(1);
+
+      const rows = await db.select({ id: routines.id, status: routines.status }).from(routines);
+      const statusById = new Map(rows.map((row) => [row.id, row.status]));
+      expect(statusById.get(activeScheduledRoutineId)).toBe("paused");
+      expect(statusById.get(activeApiRoutineId)).toBe("active");
+      expect(statusById.get(pausedScheduledRoutineId)).toBe("paused");
+      expect(statusById.get(archivedScheduledRoutineId)).toBe("archived");
+      expect(statusById.get(disabledScheduleRoutineId)).toBe("active");
+    } finally {
+      await db.$client?.end?.({ timeout: 5 }).catch(() => undefined);
+      await tempDb.cleanup();
+    }
+  }, 20_000);
+});

cli/src/checks/deployment-auth-check.ts

@@ -1,24 +1,21 @@
+import { inferBindModeFromHost } from "@paperclipai/shared";
 import type { PaperclipConfig } from "../config/schema.js";
 import type { CheckResult } from "./index.js";
 
-function isLoopbackHost(host: string) {
-  const normalized = host.trim().toLowerCase();
-  return normalized === "127.0.0.1" || normalized === "localhost" || normalized === "::1";
-}
-
 export function deploymentAuthCheck(config: PaperclipConfig): CheckResult {
   const mode = config.server.deploymentMode;
   const exposure = config.server.exposure;
   const auth = config.auth;
+  const bind = config.server.bind ?? inferBindModeFromHost(config.server.host);
 
   if (mode === "local_trusted") {
-    if (!isLoopbackHost(config.server.host)) {
+    if (bind !== "loopback") {
       return {
         name: "Deployment/auth mode",
         status: "fail",
-        message: `local_trusted requires loopback host binding (found ${config.server.host})`,
+        message: `local_trusted requires loopback binding (found ${bind})`,
         canRepair: false,
-        repairHint: "Run `paperclipai configure --section server` and set host to 127.0.0.1",
+        repairHint: "Run `paperclipai configure --section server` and choose Local trusted / loopback reachability",
       };
     }
     return {
@@ -86,6 +83,6 @@ export function deploymentAuthCheck(config: PaperclipConfig): CheckResult {
   return {
     name: "Deployment/auth mode",
     status: "pass",
-    message: `Mode ${mode}/${exposure} with auth URL mode ${auth.baseUrlMode}`,
+    message: `Mode ${mode}/${exposure} with bind ${bind} and auth URL mode ${auth.baseUrlMode}`,
   };
 }

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

@@ -3,6 +3,7 @@ import * as p from "@clack/prompts";
 import pc from "picocolors";
 import { and, eq, gt, isNull } from "drizzle-orm";
 import { createDb, instanceUserRoles, invites } from "@paperclipai/db";
+import { inferBindModeFromHost } from "@paperclipai/shared";
 import { loadPaperclipEnvFile } from "../config/env.js";
 import { readConfig, resolveConfigPath } from "../config/store.js";
 
@@ -40,9 +41,13 @@ function resolveBaseUrl(configPath?: string, explicitBaseUrl?: string) {
   if (config?.auth.baseUrlMode === "explicit" && config.auth.publicBaseUrl) {
     return config.auth.publicBaseUrl.replace(/\/+$/, "");
   }
-  const host = config?.server.host ?? "localhost";
+  const bind = config?.server.bind ?? inferBindModeFromHost(config?.server.host);
+  const host =
+    bind === "custom"
+      ? config?.server.customBindHost ?? config?.server.host ?? "localhost"
+      : config?.server.host ?? "localhost";
   const port = config?.server.port ?? 3100;
-  const publicHost = host === "0.0.0.0" ? "localhost" : host;
+  const publicHost = host === "0.0.0.0" || bind === "lan" ? "localhost" : host;
   return `http://${publicHost}:${port}`;
 }
 

cli/src/commands/configure.ts

@@ -54,6 +54,7 @@ function defaultConfig(): PaperclipConfig {
     server: {
       deploymentMode: "local_trusted",
       exposure: "private",
+      bind: "loopback",
       host: "127.0.0.1",
       port: 3100,
       allowedHostnames: [],

cli/src/commands/db-backup.ts

@@ -73,7 +73,7 @@ export async function dbBackupCommand(opts: DbBackupOptions): Promise<void> {
     const result = await runDatabaseBackup({
       connectionString: connection.value,
       backupDir,
-      retentionDays,
+      retention: { dailyDays: retentionDays, weeklyWeeks: 4, monthlyMonths: 1 },
       filenamePrefix,
     });
     spinner.stop(`Backup saved: ${formatDatabaseBackupResult(result)}`);

cli/src/commands/onboard.ts

@@ -3,10 +3,14 @@ import path from "node:path";
 import pc from "picocolors";
 import {
   AUTH_BASE_URL_MODES,
+  BIND_MODES,
   DEPLOYMENT_EXPOSURES,
   DEPLOYMENT_MODES,
   SECRET_PROVIDERS,
   STORAGE_PROVIDERS,
+  inferBindModeFromHost,
+  resolveRuntimeBind,
+  type BindMode,
   type AuthBaseUrlMode,
   type DeploymentExposure,
   type DeploymentMode,
@@ -23,6 +27,7 @@ import { promptLogging } from "../prompts/logging.js";
 import { defaultSecretsConfig } from "../prompts/secrets.js";
 import { defaultStorageConfig, promptStorage } from "../prompts/storage.js";
 import { promptServer } from "../prompts/server.js";
+import { buildPresetServerConfig } from "../config/server-bind.js";
 import {
   describeLocalInstancePaths,
   expandHomePrefix,
@@ -46,10 +51,14 @@ type OnboardOptions = {
   run?: boolean;
   yes?: boolean;
   invokedByRun?: boolean;
+  bind?: BindMode;
 };
 
 type OnboardDefaults = Pick<PaperclipConfig, "database" | "logging" | "server" | "auth" | "storage" | "secrets">;
 
+const TAILNET_BIND_WARNING =
+  "No Tailscale address was detected during setup. The saved config will stay on loopback until Tailscale is available or PAPERCLIP_TAILNET_BIND_HOST is set.";
+
 const ONBOARD_ENV_KEYS = [
   "PAPERCLIP_PUBLIC_URL",
   "DATABASE_URL",
@@ -59,6 +68,9 @@ const ONBOARD_ENV_KEYS = [
   "PAPERCLIP_DB_BACKUP_DIR",
   "PAPERCLIP_DEPLOYMENT_MODE",
   "PAPERCLIP_DEPLOYMENT_EXPOSURE",
+  "PAPERCLIP_BIND",
+  "PAPERCLIP_BIND_HOST",
+  "PAPERCLIP_TAILNET_BIND_HOST",
   "HOST",
   "PORT",
   "SERVE_UI",
@@ -104,29 +116,62 @@ function resolvePathFromEnv(rawValue: string | undefined): string | null {
   return path.resolve(expandHomePrefix(rawValue.trim()));
 }
 
-function quickstartDefaultsFromEnv(): {
+function describeServerBinding(server: Pick<PaperclipConfig["server"], "bind" | "customBindHost" | "host" | "port">): string {
+  const bind = server.bind ?? inferBindModeFromHost(server.host);
+  const detail =
+    bind === "custom"
+      ? server.customBindHost ?? server.host
+      : bind === "tailnet"
+        ? "detected tailscale address"
+        : server.host;
+  return `${bind}${detail ? ` (${detail})` : ""}:${server.port}`;
+}
+
+function quickstartDefaultsFromEnv(opts?: { preferTrustedLocal?: boolean }): {
   defaults: OnboardDefaults;
   usedEnvKeys: string[];
   ignoredEnvKeys: Array<{ key: string; reason: string }>;
 } {
+  const preferTrustedLocal = opts?.preferTrustedLocal ?? false;
   const instanceId = resolvePaperclipInstanceId();
   const defaultStorage = defaultStorageConfig();
   const defaultSecrets = defaultSecretsConfig();
   const databaseUrl = process.env.DATABASE_URL?.trim() || undefined;
-  const publicUrl =
-    process.env.PAPERCLIP_PUBLIC_URL?.trim() ||
-    process.env.PAPERCLIP_AUTH_PUBLIC_BASE_URL?.trim() ||
-    process.env.BETTER_AUTH_URL?.trim() ||
-    process.env.BETTER_AUTH_BASE_URL?.trim() ||
-    undefined;
-  const deploymentMode =
-    parseEnumFromEnv<DeploymentMode>(process.env.PAPERCLIP_DEPLOYMENT_MODE, DEPLOYMENT_MODES) ?? "local_trusted";
+  const publicUrl = preferTrustedLocal
+    ? undefined
+    : (
+      process.env.PAPERCLIP_PUBLIC_URL?.trim() ||
+      process.env.PAPERCLIP_AUTH_PUBLIC_BASE_URL?.trim() ||
+      process.env.BETTER_AUTH_URL?.trim() ||
+      process.env.BETTER_AUTH_BASE_URL?.trim() ||
+      undefined
+    );
+  const deploymentMode = preferTrustedLocal
+    ? "local_trusted"
+    : (parseEnumFromEnv<DeploymentMode>(process.env.PAPERCLIP_DEPLOYMENT_MODE, DEPLOYMENT_MODES) ?? "local_trusted");
   const deploymentExposureFromEnv = parseEnumFromEnv<DeploymentExposure>(
     process.env.PAPERCLIP_DEPLOYMENT_EXPOSURE,
     DEPLOYMENT_EXPOSURES,
   );
   const deploymentExposure =
     deploymentMode === "local_trusted" ? "private" : (deploymentExposureFromEnv ?? "private");
+  const bindFromEnv = parseEnumFromEnv<BindMode>(process.env.PAPERCLIP_BIND, BIND_MODES);
+  const customBindHostFromEnv = process.env.PAPERCLIP_BIND_HOST?.trim() || undefined;
+  const hostFromEnv = process.env.HOST?.trim() || undefined;
+  const configuredBindHost = customBindHostFromEnv ?? hostFromEnv;
+  const bind = preferTrustedLocal
+    ? "loopback"
+    : (
+      deploymentMode === "local_trusted"
+        ? "loopback"
+        : (bindFromEnv ?? (configuredBindHost ? inferBindModeFromHost(configuredBindHost) : "lan"))
+    );
+  const resolvedBind = resolveRuntimeBind({
+    bind,
+    host: hostFromEnv ?? (bind === "loopback" ? "127.0.0.1" : "0.0.0.0"),
+    customBindHost: customBindHostFromEnv,
+    tailnetBindHost: process.env.PAPERCLIP_TAILNET_BIND_HOST?.trim(),
+  });
   const authPublicBaseUrl = publicUrl;
   const authBaseUrlModeFromEnv = parseEnumFromEnv<AuthBaseUrlMode>(
     process.env.PAPERCLIP_AUTH_BASE_URL_MODE,
@@ -183,7 +228,9 @@ function quickstartDefaultsFromEnv(): {
     server: {
       deploymentMode,
       exposure: deploymentExposure,
-      host: process.env.HOST ?? "127.0.0.1",
+      bind: resolvedBind.bind,
+      ...(resolvedBind.customBindHost ? { customBindHost: resolvedBind.customBindHost } : {}),
+      host: resolvedBind.host,
       port: Number(process.env.PORT) || 3100,
       allowedHostnames: Array.from(new Set([...allowedHostnamesFromEnv, ...(hostnameFromPublicUrl ? [hostnameFromPublicUrl] : [])])),
       serveUi: parseBooleanFromEnv(process.env.SERVE_UI) ?? true,
@@ -220,12 +267,49 @@ function quickstartDefaultsFromEnv(): {
     },
   };
   const ignoredEnvKeys: Array<{ key: string; reason: string }> = [];
+  if (preferTrustedLocal) {
+    const forcedLocalReason = "Ignored because --yes quickstart forces trusted local loopback defaults";
+    for (const key of [
+      "PAPERCLIP_DEPLOYMENT_MODE",
+      "PAPERCLIP_DEPLOYMENT_EXPOSURE",
+      "PAPERCLIP_BIND",
+      "PAPERCLIP_BIND_HOST",
+      "HOST",
+      "PAPERCLIP_AUTH_BASE_URL_MODE",
+      "PAPERCLIP_AUTH_PUBLIC_BASE_URL",
+      "PAPERCLIP_PUBLIC_URL",
+      "BETTER_AUTH_URL",
+      "BETTER_AUTH_BASE_URL",
+    ] as const) {
+      if (process.env[key] !== undefined) {
+        ignoredEnvKeys.push({ key, reason: forcedLocalReason });
+      }
+    }
+  }
   if (deploymentMode === "local_trusted" && process.env.PAPERCLIP_DEPLOYMENT_EXPOSURE !== undefined) {
     ignoredEnvKeys.push({
       key: "PAPERCLIP_DEPLOYMENT_EXPOSURE",
       reason: "Ignored because deployment mode local_trusted always forces private exposure",
     });
   }
+  if (deploymentMode === "local_trusted" && process.env.PAPERCLIP_BIND !== undefined) {
+    ignoredEnvKeys.push({
+      key: "PAPERCLIP_BIND",
+      reason: "Ignored because deployment mode local_trusted always uses loopback reachability",
+    });
+  }
+  if (deploymentMode === "local_trusted" && process.env.PAPERCLIP_BIND_HOST !== undefined) {
+    ignoredEnvKeys.push({
+      key: "PAPERCLIP_BIND_HOST",
+      reason: "Ignored because deployment mode local_trusted always uses loopback reachability",
+    });
+  }
+  if (deploymentMode === "local_trusted" && process.env.HOST !== undefined) {
+    ignoredEnvKeys.push({
+      key: "HOST",
+      reason: "Ignored because deployment mode local_trusted always uses loopback reachability",
+    });
+  }
 
   const ignoredKeySet = new Set(ignoredEnvKeys.map((entry) => entry.key));
   const usedEnvKeys = ONBOARD_ENV_KEYS.filter(
@@ -239,6 +323,10 @@ function canCreateBootstrapInviteImmediately(config: Pick<PaperclipConfig, "data
 }
 
 export async function onboard(opts: OnboardOptions): Promise<void> {
+  if (opts.bind && !["loopback", "lan", "tailnet"].includes(opts.bind)) {
+    throw new Error(`Unsupported bind preset for onboard: ${opts.bind}. Use loopback, lan, or tailnet.`);
+  }
+
   printPaperclipCliBanner();
   p.intro(pc.bgCyan(pc.black(" paperclipai onboard ")));
   const configPath = resolveConfigPath(opts.config);
@@ -293,7 +381,7 @@ export async function onboard(opts: OnboardOptions): Promise<void> {
         `Database: ${existingConfig.database.mode}`,
         existingConfig.llm ? `LLM: ${existingConfig.llm.provider}` : "LLM: not configured",
         `Logging: ${existingConfig.logging.mode} -> ${existingConfig.logging.logDir}`,
-        `Server: ${existingConfig.server.deploymentMode}/${existingConfig.server.exposure} @ ${existingConfig.server.host}:${existingConfig.server.port}`,
+        `Server: ${existingConfig.server.deploymentMode}/${existingConfig.server.exposure} @ ${describeServerBinding(existingConfig.server)}`,
         `Allowed hosts: ${existingConfig.server.allowedHostnames.length > 0 ? existingConfig.server.allowedHostnames.join(", ") : "(loopback only)"}`,
         `Auth URL mode: ${existingConfig.auth.baseUrlMode}${existingConfig.auth.publicBaseUrl ? ` (${existingConfig.auth.publicBaseUrl})` : ""}`,
         `Storage: ${existingConfig.storage.provider}`,
@@ -336,7 +424,13 @@ export async function onboard(opts: OnboardOptions): Promise<void> {
 
   let setupMode: SetupMode = "quickstart";
   if (opts.yes) {
-    p.log.message(pc.dim("`--yes` enabled: using Quickstart defaults."));
+    p.log.message(
+      pc.dim(
+        opts.bind
+          ? `\`--yes\` enabled: using Quickstart defaults with bind=${opts.bind}.`
+          : "`--yes` enabled: using Quickstart defaults.",
+      ),
+    );
   } else {
     const setupModeChoice = await p.select({
       message: "Choose setup path",
@@ -365,7 +459,9 @@ export async function onboard(opts: OnboardOptions): Promise<void> {
   if (tc) trackInstallStarted(tc);
 
   let llm: PaperclipConfig["llm"] | undefined;
-  const { defaults: derivedDefaults, usedEnvKeys, ignoredEnvKeys } = quickstartDefaultsFromEnv();
+  const { defaults: derivedDefaults, usedEnvKeys, ignoredEnvKeys } = quickstartDefaultsFromEnv({
+    preferTrustedLocal: opts.yes === true && !opts.bind,
+  });
   let {
     database,
     logging,
@@ -375,6 +471,19 @@ export async function onboard(opts: OnboardOptions): Promise<void> {
     secrets,
   } = derivedDefaults;
 
+  if (opts.bind === "loopback" || opts.bind === "lan" || opts.bind === "tailnet") {
+    const preset = buildPresetServerConfig(opts.bind, {
+      port: server.port,
+      allowedHostnames: server.allowedHostnames,
+      serveUi: server.serveUi,
+    });
+    server = preset.server;
+    auth = preset.auth;
+    if (opts.bind === "tailnet" && server.host === "127.0.0.1") {
+      p.log.warn(TAILNET_BIND_WARNING);
+    }
+  }
+
   if (setupMode === "advanced") {
     p.log.step(pc.bold("Database"));
     database = await promptDatabase(database);
@@ -462,7 +571,13 @@ export async function onboard(opts: OnboardOptions): Promise<void> {
     );
   } else {
     p.log.step(pc.bold("Quickstart"));
-    p.log.message(pc.dim("Using quickstart defaults."));
+    p.log.message(
+      pc.dim(
+        opts.bind
+          ? `Using quickstart defaults with bind=${opts.bind}.`
+          : `Using quickstart defaults: ${server.deploymentMode}/${server.exposure} @ ${describeServerBinding(server)}.`,
+      ),
+    );
     if (usedEnvKeys.length > 0) {
       p.log.message(pc.dim(`Environment-aware defaults active (${usedEnvKeys.length} env var(s) detected).`));
     } else {
@@ -521,7 +636,7 @@ export async function onboard(opts: OnboardOptions): Promise<void> {
       `Database: ${database.mode}`,
       llm ? `LLM: ${llm.provider}` : "LLM: not configured",
       `Logging: ${logging.mode} -> ${logging.logDir}`,
-      `Server: ${server.deploymentMode}/${server.exposure} @ ${server.host}:${server.port}`,
+      `Server: ${server.deploymentMode}/${server.exposure} @ ${describeServerBinding(server)}`,
       `Allowed hosts: ${server.allowedHostnames.length > 0 ? server.allowedHostnames.join(", ") : "(loopback only)"}`,
       `Auth URL mode: ${auth.baseUrlMode}${auth.publicBaseUrl ? ` (${auth.publicBaseUrl})` : ""}`,
       `Storage: ${storage.provider}`,

cli/src/commands/run.ts

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { spawnSync } from "node:child_process";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import * as p from "@clack/prompts";
 import pc from "picocolors";
@@ -21,6 +22,7 @@ interface RunOptions {
   instance?: string;
   repair?: boolean;
   yes?: boolean;
+  bind?: "loopback" | "lan" | "tailnet";
 }
 
 interface StartedServer {
@@ -57,7 +59,7 @@ export async function runCommand(opts: RunOptions): Promise<void> {
     }
 
     p.log.step("No config found. Starting onboarding...");
-    await onboard({ config: configPath, invokedByRun: true });
+    await onboard({ config: configPath, invokedByRun: true, bind: opts.bind });
   }
 
   p.log.step("Running doctor checks...");
@@ -146,11 +148,35 @@ function maybeEnableUiDevMiddleware(entrypoint: string): void {
   }
 }
 
+function ensureDevWorkspaceBuildDeps(projectRoot: string): void {
+  const buildScript = path.resolve(projectRoot, "scripts/ensure-plugin-build-deps.mjs");
+  if (!fs.existsSync(buildScript)) return;
+
+  const result = spawnSync(process.execPath, [buildScript], {
+    cwd: projectRoot,
+    stdio: "inherit",
+    timeout: 120_000,
+  });
+
+  if (result.error) {
+    throw new Error(
+      `Failed to prepare workspace build artifacts before starting the Paperclip dev server.\n${formatError(result.error)}`,
+    );
+  }
+
+  if ((result.status ?? 1) !== 0) {
+    throw new Error(
+      "Failed to prepare workspace build artifacts before starting the Paperclip dev server.",
+    );
+  }
+}
+
 async function importServerEntry(): Promise<StartedServer> {
   // Dev mode: try local workspace path (monorepo with tsx)
   const projectRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
   const devEntry = path.resolve(projectRoot, "server/src/index.ts");
   if (fs.existsSync(devEntry)) {
+    ensureDevWorkspaceBuildDeps(projectRoot);
     maybeEnableUiDevMiddleware(devEntry);
     const mod = await import(pathToFileURL(devEntry).href);
     return await startServerFromModule(mod, devEntry);

cli/src/commands/worktree-lib.ts

@@ -214,6 +214,8 @@ export function buildWorktreeConfig(input: {
     server: {
       deploymentMode: source?.server.deploymentMode ?? "local_trusted",
       exposure: source?.server.exposure ?? "private",
+      ...(source?.server.bind ? { bind: source.server.bind } : {}),
+      ...(source?.server.customBindHost ? { customBindHost: source.server.customBindHost } : {}),
       host: source?.server.host ?? "127.0.0.1",
       port: serverPort,
       allowedHostnames: source?.server.allowedHostnames ?? [],

cli/src/commands/worktree.ts

@@ -39,6 +39,8 @@ import {
   issues,
   projectWorkspaces,
   projects,
+  routines,
+  routineTriggers,
   runDatabaseBackup,
   runDatabaseRestore,
   createEmbeddedPostgresLogBuffer,
@@ -922,6 +924,36 @@ async function ensureEmbeddedPostgres(dataDir: string, preferredPort: number): P
   };
 }
 
+export async function pauseSeededScheduledRoutines(connectionString: string): Promise<number> {
+  const db = createDb(connectionString);
+  try {
+    const scheduledRoutineIds = await db
+      .selectDistinct({ routineId: routineTriggers.routineId })
+      .from(routineTriggers)
+      .where(and(eq(routineTriggers.kind, "schedule"), eq(routineTriggers.enabled, true)));
+    const idsToPause = scheduledRoutineIds
+      .map((row) => row.routineId)
+      .filter((value): value is string => Boolean(value));
+
+    if (idsToPause.length === 0) {
+      return 0;
+    }
+
+    const paused = await db
+      .update(routines)
+      .set({
+        status: "paused",
+        updatedAt: new Date(),
+      })
+      .where(and(inArray(routines.id, idsToPause), sql`${routines.status} <> 'paused'`, sql`${routines.status} <> 'archived'`))
+      .returning({ id: routines.id });
+
+    return paused.length;
+  } finally {
+    await db.$client?.end?.({ timeout: 5 }).catch(() => undefined);
+  }
+}
+
 async function seedWorktreeDatabase(input: {
   sourceConfigPath: string;
   sourceConfig: PaperclipConfig;
@@ -959,7 +991,7 @@ async function seedWorktreeDatabase(input: {
     const backup = await runDatabaseBackup({
       connectionString: sourceConnectionString,
       backupDir: path.resolve(input.targetPaths.backupDir, "seed"),
-      retentionDays: 7,
+      retention: { dailyDays: 7, weeklyWeeks: 4, monthlyMonths: 1 },
       filenamePrefix: `${input.instanceId}-seed`,
       includeMigrationJournal: true,
       excludeTables: seedPlan.excludedTables,
@@ -979,6 +1011,7 @@ async function seedWorktreeDatabase(input: {
       backupFile: backup.backupFile,
     });
     await applyPendingMigrations(targetConnectionString);
+    await pauseSeededScheduledRoutines(targetConnectionString);
     const reboundWorkspaces = await rebindSeededProjectWorkspaces({
       targetConnectionString,
       currentCwd: input.targetPaths.cwd,

cli/src/config/server-bind.ts

@@ -0,0 +1,183 @@
+import { execFileSync } from "node:child_process";
+import {
+  ALL_INTERFACES_BIND_HOST,
+  LOOPBACK_BIND_HOST,
+  inferBindModeFromHost,
+  isAllInterfacesHost,
+  isLoopbackHost,
+  type BindMode,
+  type DeploymentExposure,
+  type DeploymentMode,
+} from "@paperclipai/shared";
+import type { AuthConfig, ServerConfig } from "./schema.js";
+
+const TAILSCALE_DETECT_TIMEOUT_MS = 3000;
+
+type BaseServerInput = {
+  port: number;
+  allowedHostnames: string[];
+  serveUi: boolean;
+};
+
+export function inferConfiguredBind(server?: Partial<ServerConfig>): BindMode {
+  if (server?.bind) return server.bind;
+  return inferBindModeFromHost(server?.customBindHost ?? server?.host);
+}
+
+export function detectTailnetBindHost(): string | undefined {
+  const explicit = process.env.PAPERCLIP_TAILNET_BIND_HOST?.trim();
+  if (explicit) return explicit;
+
+  try {
+    const stdout = execFileSync("tailscale", ["ip", "-4"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: TAILSCALE_DETECT_TIMEOUT_MS,
+    });
+    return stdout
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .find(Boolean);
+  } catch {
+    return undefined;
+  }
+}
+
+export function buildPresetServerConfig(
+  bind: Exclude<BindMode, "custom">,
+  input: BaseServerInput,
+): { server: ServerConfig; auth: AuthConfig } {
+  const host =
+    bind === "loopback"
+      ? LOOPBACK_BIND_HOST
+      : bind === "tailnet"
+        ? (detectTailnetBindHost() ?? LOOPBACK_BIND_HOST)
+        : ALL_INTERFACES_BIND_HOST;
+
+  return {
+    server: {
+      deploymentMode: bind === "loopback" ? "local_trusted" : "authenticated",
+      exposure: "private",
+      bind,
+      customBindHost: undefined,
+      host,
+      port: input.port,
+      allowedHostnames: input.allowedHostnames,
+      serveUi: input.serveUi,
+    },
+    auth: {
+      baseUrlMode: "auto",
+      disableSignUp: false,
+    },
+  };
+}
+
+export function buildCustomServerConfig(input: BaseServerInput & {
+  deploymentMode: DeploymentMode;
+  exposure: DeploymentExposure;
+  host: string;
+  publicBaseUrl?: string;
+}): { server: ServerConfig; auth: AuthConfig } {
+  const normalizedHost = input.host.trim();
+  const bind = isLoopbackHost(normalizedHost)
+    ? "loopback"
+    : isAllInterfacesHost(normalizedHost)
+      ? "lan"
+      : "custom";
+
+  return {
+    server: {
+      deploymentMode: input.deploymentMode,
+      exposure: input.deploymentMode === "local_trusted" ? "private" : input.exposure,
+      bind,
+      customBindHost: bind === "custom" ? normalizedHost : undefined,
+      host: normalizedHost,
+      port: input.port,
+      allowedHostnames: input.allowedHostnames,
+      serveUi: input.serveUi,
+    },
+    auth:
+      input.deploymentMode === "authenticated" && input.exposure === "public"
+        ? {
+          baseUrlMode: "explicit",
+          disableSignUp: false,
+          publicBaseUrl: input.publicBaseUrl,
+        }
+        : {
+          baseUrlMode: "auto",
+          disableSignUp: false,
+        },
+  };
+}
+
+export function resolveQuickstartServerConfig(input: {
+  bind?: BindMode | null;
+  deploymentMode?: DeploymentMode | null;
+  exposure?: DeploymentExposure | null;
+  host?: string | null;
+  port: number;
+  allowedHostnames: string[];
+  serveUi: boolean;
+  publicBaseUrl?: string;
+}): { server: ServerConfig; auth: AuthConfig } {
+  const trimmedHost = input.host?.trim();
+  const explicitBind = input.bind ?? null;
+
+  if (explicitBind === "loopback" || explicitBind === "lan" || explicitBind === "tailnet") {
+    return buildPresetServerConfig(explicitBind, {
+      port: input.port,
+      allowedHostnames: input.allowedHostnames,
+      serveUi: input.serveUi,
+    });
+  }
+
+  if (explicitBind === "custom") {
+    return buildCustomServerConfig({
+      deploymentMode: input.deploymentMode ?? "authenticated",
+      exposure: input.exposure ?? "private",
+      host: trimmedHost || LOOPBACK_BIND_HOST,
+      port: input.port,
+      allowedHostnames: input.allowedHostnames,
+      serveUi: input.serveUi,
+      publicBaseUrl: input.publicBaseUrl,
+    });
+  }
+
+  if (trimmedHost) {
+    return buildCustomServerConfig({
+      deploymentMode: input.deploymentMode ?? (isLoopbackHost(trimmedHost) ? "local_trusted" : "authenticated"),
+      exposure: input.exposure ?? "private",
+      host: trimmedHost,
+      port: input.port,
+      allowedHostnames: input.allowedHostnames,
+      serveUi: input.serveUi,
+      publicBaseUrl: input.publicBaseUrl,
+    });
+  }
+
+  if (input.deploymentMode === "authenticated") {
+    if (input.exposure === "public") {
+      return buildCustomServerConfig({
+        deploymentMode: "authenticated",
+        exposure: "public",
+        host: ALL_INTERFACES_BIND_HOST,
+        port: input.port,
+        allowedHostnames: input.allowedHostnames,
+        serveUi: input.serveUi,
+        publicBaseUrl: input.publicBaseUrl,
+      });
+    }
+
+    return buildPresetServerConfig("lan", {
+      port: input.port,
+      allowedHostnames: input.allowedHostnames,
+      serveUi: input.serveUi,
+    });
+  }
+
+  return buildPresetServerConfig("loopback", {
+    port: input.port,
+    allowedHostnames: input.allowedHostnames,
+    serveUi: input.serveUi,
+  });
+}

cli/src/index.ts

@@ -50,7 +50,8 @@ program
   .description("Interactive first-run setup wizard")
   .option("-c, --config <path>", "Path to config file")
   .option("-d, --data-dir <path>", DATA_DIR_OPTION_HELP)
-  .option("-y, --yes", "Accept defaults (quickstart + start immediately)", false)
+  .option("--bind <mode>", "Quickstart reachability preset (loopback, lan, tailnet)")
+  .option("-y, --yes", "Accept quickstart defaults (trusted local loopback unless --bind is set) and start immediately", false)
   .option("--run", "Start Paperclip immediately after saving config", false)
   .action(onboard);
 
@@ -108,6 +109,7 @@ program
   .option("-c, --config <path>", "Path to config file")
   .option("-d, --data-dir <path>", DATA_DIR_OPTION_HELP)
   .option("-i, --instance <id>", "Local instance id (default: default)")
+  .option("--bind <mode>", "On first run, use onboarding reachability preset (loopback, lan, tailnet)")
   .option("--repair", "Attempt automatic repairs during doctor", true)
   .option("--no-repair", "Disable automatic repairs during doctor")
   .action(runCommand);

cli/src/prompts/server.ts

@@ -1,6 +1,16 @@
 import * as p from "@clack/prompts";
+import { isLoopbackHost, type BindMode } from "@paperclipai/shared";
 import type { AuthConfig, ServerConfig } from "../config/schema.js";
 import { parseHostnameCsv } from "../config/hostnames.js";
+import { buildCustomServerConfig, buildPresetServerConfig, inferConfiguredBind } from "../config/server-bind.js";
+
+const TAILNET_BIND_WARNING =
+  "No Tailscale address was detected during setup. The saved config will stay on loopback until Tailscale is available or PAPERCLIP_TAILNET_BIND_HOST is set.";
+
+function cancelled(): never {
+  p.cancel("Setup cancelled.");
+  process.exit(0);
+}
 
 export async function promptServer(opts?: {
   currentServer?: Partial<ServerConfig>;
@@ -8,69 +18,37 @@ export async function promptServer(opts?: {
 }): Promise<{ server: ServerConfig; auth: AuthConfig }> {
   const currentServer = opts?.currentServer;
   const currentAuth = opts?.currentAuth;
+  const currentBind = inferConfiguredBind(currentServer);
 
-  const deploymentModeSelection = await p.select({
-    message: "Deployment mode",
+  const bindSelection = await p.select({
+    message: "Reachability",
     options: [
       {
-        value: "local_trusted",
-        label: "Local trusted",
-        hint: "Easiest for local setup (no login, localhost-only)",
+        value: "loopback" as const,
+        label: "Trusted local",
+        hint: "Recommended for first run: localhost only, no login friction",
       },
       {
-        value: "authenticated",
-        label: "Authenticated",
-        hint: "Login required; use for private network or public hosting",
+        value: "lan" as const,
+        label: "Private network",
+        hint: "Broad private bind for LAN, VPN, or legacy --tailscale-auth style access",
+      },
+      {
+        value: "tailnet" as const,
+        label: "Tailnet",
+        hint: "Private authenticated access using the machine's detected Tailscale address",
+      },
+      {
+        value: "custom" as const,
+        label: "Custom",
+        hint: "Choose exact auth mode, exposure, and host manually",
       },
     ],
-    initialValue: currentServer?.deploymentMode ?? "local_trusted",
+    initialValue: currentBind,
   });
 
-  if (p.isCancel(deploymentModeSelection)) {
-    p.cancel("Setup cancelled.");
-    process.exit(0);
-  }
-  const deploymentMode = deploymentModeSelection as ServerConfig["deploymentMode"];
-
-  let exposure: ServerConfig["exposure"] = "private";
-  if (deploymentMode === "authenticated") {
-    const exposureSelection = await p.select({
-      message: "Exposure profile",
-      options: [
-        {
-          value: "private",
-          label: "Private network",
-          hint: "Private access (for example Tailscale), lower setup friction",
-        },
-        {
-          value: "public",
-          label: "Public internet",
-          hint: "Internet-facing deployment with stricter requirements",
-        },
-      ],
-      initialValue: currentServer?.exposure ?? "private",
-    });
-    if (p.isCancel(exposureSelection)) {
-      p.cancel("Setup cancelled.");
-      process.exit(0);
-    }
-    exposure = exposureSelection as ServerConfig["exposure"];
-  }
-
-  const hostDefault = deploymentMode === "local_trusted" ? "127.0.0.1" : "0.0.0.0";
-  const hostStr = await p.text({
-    message: "Bind host",
-    defaultValue: currentServer?.host ?? hostDefault,
-    placeholder: hostDefault,
-    validate: (val) => {
-      if (!val.trim()) return "Host is required";
-    },
-  });
-
-  if (p.isCancel(hostStr)) {
-    p.cancel("Setup cancelled.");
-    process.exit(0);
-  }
+  if (p.isCancel(bindSelection)) cancelled();
+  const bind = bindSelection as BindMode;
 
   const portStr = await p.text({
     message: "Server port",
@@ -84,15 +62,113 @@ export async function promptServer(opts?: {
     },
   });
 
-  if (p.isCancel(portStr)) {
-    p.cancel("Setup cancelled.");
-    process.exit(0);
+  if (p.isCancel(portStr)) cancelled();
+  const port = Number(portStr) || 3100;
+  const serveUi = currentServer?.serveUi ?? true;
+
+  if (bind === "loopback") {
+    return buildPresetServerConfig("loopback", {
+      port,
+      allowedHostnames: [],
+      serveUi,
+    });
   }
 
+  if (bind === "lan" || bind === "tailnet") {
+    const allowedHostnamesInput = await p.text({
+      message: "Allowed private hostnames (comma-separated, optional)",
+      defaultValue: (currentServer?.allowedHostnames ?? []).join(", "),
+      placeholder:
+        bind === "tailnet"
+          ? "your-machine.tailnet.ts.net"
+          : "dotta-macbook-pro, host.docker.internal",
+      validate: (val) => {
+        try {
+          parseHostnameCsv(val);
+          return;
+        } catch (err) {
+          return err instanceof Error ? err.message : "Invalid hostname list";
+        }
+      },
+    });
+
+    if (p.isCancel(allowedHostnamesInput)) cancelled();
+
+    const preset = buildPresetServerConfig(bind, {
+      port,
+      allowedHostnames: parseHostnameCsv(allowedHostnamesInput),
+      serveUi,
+    });
+    if (bind === "tailnet" && isLoopbackHost(preset.server.host)) {
+      p.log.warn(TAILNET_BIND_WARNING);
+    }
+    return preset;
+  }
+
+  const deploymentModeSelection = await p.select({
+    message: "Auth mode",
+    options: [
+      {
+        value: "local_trusted",
+        label: "Local trusted",
+        hint: "No login required; only safe with loopback-only or similarly trusted access",
+      },
+      {
+        value: "authenticated",
+        label: "Authenticated",
+        hint: "Login required; supports both private-network and public deployments",
+      },
+    ],
+    initialValue: currentServer?.deploymentMode ?? "authenticated",
+  });
+
+  if (p.isCancel(deploymentModeSelection)) cancelled();
+  const deploymentMode = deploymentModeSelection as ServerConfig["deploymentMode"];
+
+  let exposure: ServerConfig["exposure"] = "private";
+  if (deploymentMode === "authenticated") {
+    const exposureSelection = await p.select({
+      message: "Exposure profile",
+      options: [
+        {
+          value: "private",
+          label: "Private network",
+          hint: "Private access only, with automatic URL handling",
+        },
+        {
+          value: "public",
+          label: "Public internet",
+          hint: "Internet-facing deployment with explicit public URL requirements",
+        },
+      ],
+      initialValue: currentServer?.exposure ?? "private",
+    });
+    if (p.isCancel(exposureSelection)) cancelled();
+    exposure = exposureSelection as ServerConfig["exposure"];
+  }
+
+  const defaultHost =
+    currentServer?.customBindHost ??
+    currentServer?.host ??
+    (deploymentMode === "local_trusted" ? "127.0.0.1" : "0.0.0.0");
+  const host = await p.text({
+    message: "Bind host",
+    defaultValue: defaultHost,
+    placeholder: defaultHost,
+    validate: (val) => {
+      if (!val.trim()) return "Host is required";
+      if (deploymentMode === "local_trusted" && !isLoopbackHost(val.trim())) {
+        return "Local trusted mode requires a loopback host such as 127.0.0.1";
+      }
+    },
+  });
+
+  if (p.isCancel(host)) cancelled();
+
   let allowedHostnames: string[] = [];
   if (deploymentMode === "authenticated" && exposure === "private") {
     const allowedHostnamesInput = await p.text({
-      message: "Allowed hostnames (comma-separated, optional)",
+      message: "Allowed private hostnames (comma-separated, optional)",
       defaultValue: (currentServer?.allowedHostnames ?? []).join(", "),
       placeholder: "dotta-macbook-pro, your-host.tailnet.ts.net",
       validate: (val) => {
@@ -105,15 +181,11 @@ export async function promptServer(opts?: {
       },
     });
 
-    if (p.isCancel(allowedHostnamesInput)) {
-      p.cancel("Setup cancelled.");
-      process.exit(0);
-    }
+    if (p.isCancel(allowedHostnamesInput)) cancelled();
     allowedHostnames = parseHostnameCsv(allowedHostnamesInput);
   }
 
-  const port = Number(portStr) || 3100;
-  let auth: AuthConfig = { baseUrlMode: "auto", disableSignUp: false };
+  let publicBaseUrl: string | undefined;
   if (deploymentMode === "authenticated" && exposure === "public") {
     const urlInput = await p.text({
       message: "Public base URL",
@@ -133,32 +205,17 @@ export async function promptServer(opts?: {
         }
       },
     });
-    if (p.isCancel(urlInput)) {
-      p.cancel("Setup cancelled.");
-      process.exit(0);
-    }
-    auth = {
-      baseUrlMode: "explicit",
-      disableSignUp: false,
-      publicBaseUrl: urlInput.trim().replace(/\/+$/, ""),
-    };
-  } else if (currentAuth?.baseUrlMode === "explicit" && currentAuth.publicBaseUrl) {
-    auth = {
-      baseUrlMode: "explicit",
-      disableSignUp: false,
-      publicBaseUrl: currentAuth.publicBaseUrl,
-    };
+    if (p.isCancel(urlInput)) cancelled();
+    publicBaseUrl = urlInput.trim().replace(/\/+$/, "");
   }
 
-  return {
-    server: {
-      deploymentMode,
-      exposure,
-      host: hostStr.trim(),
-      port,
-      allowedHostnames,
-      serveUi: currentServer?.serveUi ?? true,
-    },
-    auth,
-  };
+  return buildCustomServerConfig({
+    deploymentMode,
+    exposure,
+    host: host.trim(),
+    port,
+    allowedHostnames,
+    serveUi,
+    publicBaseUrl,
+  });
 }

doc/CLI.md

@@ -32,10 +32,12 @@ Mode taxonomy and design intent are documented in `doc/DEPLOYMENT-MODES.md`.
 Current CLI behavior:
 
 - `paperclipai onboard` and `paperclipai configure --section server` set deployment mode in config
+- server onboarding/configure ask for reachability intent and write `server.bind`
+- `paperclipai run --bind <loopback|lan|tailnet>` passes a quickstart bind preset into first-run onboarding when config is missing
 - runtime can override mode with `PAPERCLIP_DEPLOYMENT_MODE`
-- `paperclipai run` and `paperclipai doctor` do not yet expose a direct `--mode` flag
+- `paperclipai run` and `paperclipai doctor` still do not expose a direct low-level `--mode` flag
 
-Target behavior (planned) is documented in `doc/DEPLOYMENT-MODES.md` section 5.
+Canonical behavior is documented in `doc/DEPLOYMENT-MODES.md`.
 
 Allow an authenticated/private hostname (for example custom Tailscale DNS):
 

doc/DEPLOYMENT-MODES.md

@@ -17,6 +17,11 @@ Paperclip supports two runtime modes:
 
 This keeps one authenticated auth stack while still separating low-friction private-network defaults from internet-facing hardening requirements.
 
+Paperclip now treats **bind** as a separate concern from auth:
+
+- auth model: `local_trusted` vs `authenticated`, plus `private/public`
+- reachability model: `server.bind = loopback | lan | tailnet | custom`
+
 ## 2. Canonical Model
 
 | Runtime Mode | Exposure | Human auth | Primary use |
@@ -25,6 +30,15 @@ This keeps one authenticated auth stack while still separating low-friction priv
 | `authenticated` | `private` | Login required | Private-network access (for example Tailscale/VPN/LAN) |
 | `authenticated` | `public` | Login required | Internet-facing/cloud deployment |
 
+## Reachability Model
+
+| Bind | Meaning | Typical use |
+|---|---|---|
+| `loopback` | Listen on localhost only | default local usage, reverse-proxy deployments |
+| `lan` | Listen on all interfaces (`0.0.0.0`) | LAN/VPN/private-network access |
+| `tailnet` | Listen on a detected Tailscale IP | Tailscale-only access |
+| `custom` | Listen on an explicit host/IP | advanced interface-specific setups |
+
 ## 3. Security Policy
 
 ## `local_trusted`
@@ -38,12 +52,14 @@ This keeps one authenticated auth stack while still separating low-friction priv
 - login required
 - low-friction URL handling (`auto` base URL mode)
 - private-host trust policy required
+- bind can be `loopback`, `lan`, `tailnet`, or `custom`
 
 ## `authenticated + public`
 
 - login required
 - explicit public URL required
 - stricter deployment checks and failures in doctor
+- recommended bind is `loopback` behind a reverse proxy; direct `lan/custom` is advanced
 
 ## 4. Onboarding UX Contract
 
@@ -55,14 +71,22 @@ pnpm paperclipai onboard
 
 Server prompt behavior:
 
-1. ask mode, default `local_trusted`
-2. option copy:
-- `local_trusted`: "Easiest for local setup (no login, localhost-only)"
-- `authenticated`: "Login required; use for private network or public hosting"
-3. if `authenticated`, ask exposure:
-- `private`: "Private network access (for example Tailscale), lower setup friction"
-- `public`: "Internet-facing deployment, stricter security requirements"
-4. ask explicit public URL only for `authenticated + public`
+1. quickstart `--yes` defaults to `server.bind=loopback` and therefore `local_trusted/private`
+2. advanced server setup asks reachability first:
+- `Trusted local` → `bind=loopback`, `local_trusted/private`
+- `Private network` → `bind=lan`, `authenticated/private`
+- `Tailnet` → `bind=tailnet`, `authenticated/private`
+- `Custom` → manual mode/exposure/host entry
+3. raw host entry is only required for the `Custom` path
+4. explicit public URL is only required for `authenticated + public`
+
+Examples:
+
+```sh
+pnpm paperclipai onboard --yes
+pnpm paperclipai onboard --yes --bind lan
+pnpm paperclipai run --bind tailnet
+```
 
 `configure --section server` follows the same interactive behavior.
 

doc/DEVELOPING.md

@@ -55,10 +55,23 @@ pnpm dev:stop
 Tailscale/private-auth dev mode:
 
 ```sh
-pnpm dev --tailscale-auth
+pnpm dev --bind lan
 ```
 
-This runs dev as `authenticated/private` and binds the server to `0.0.0.0` for private-network access.
+This runs dev as `authenticated/private` with a private-network bind preset.
+
+For Tailscale-only reachability on a detected tailnet address:
+
+```sh
+pnpm dev --bind tailnet
+```
+
+Legacy aliases still map to the old broad private-network behavior:
+
+```sh
+pnpm dev --tailscale-auth
+pnpm dev --authenticated-private
+```
 
 Allow additional private hostnames (for example custom Tailscale hostnames):
 
@@ -175,7 +188,9 @@ Seed modes:
 
 After `worktree init`, both the server and the CLI auto-load the repo-local `.paperclip/.env` when run inside that worktree, so normal commands like `pnpm dev`, `paperclipai doctor`, and `paperclipai db:backup` stay scoped to the worktree instance.
 
-Provisioned git worktrees also pause all seeded routines in the isolated worktree database by default. This prevents copied daily/cron routines from firing unexpectedly inside the new workspace instance during development.
+`pnpm dev` now fails fast in a linked git worktree when `.paperclip/.env` is missing, instead of silently booting against the default instance/port. If that happens, run `paperclipai worktree init` in the worktree first.
+
+Provisioned git worktrees also pause seeded routines that still have enabled schedule triggers in the isolated worktree database by default. This prevents copied daily/cron routines from firing unexpectedly inside the new workspace instance during development without disabling webhook/API-only routines.
 
 That repo-local env also sets:
 

doc/OPENCLAW_ONBOARDING.md

@@ -3,7 +3,7 @@ Use this exact checklist.
 1. Start Paperclip in auth mode.
 ```bash
 cd <paperclip-repo-root>
-pnpm dev --tailscale-auth
+pnpm dev --bind lan
 ```
 Then verify:
 ```bash

doc/memory-landscape.md

@@ -22,6 +22,7 @@ The question is not "which memory project wins?" The question is "what is the sm
 ### Hosted memory APIs
 
 - `mem0`
+- `AWS Bedrock AgentCore Memory`
 - `supermemory`
 - `Memori`
 
@@ -49,6 +50,7 @@ These emphasize local persistence, inspectability, and low operational overhead.
 |---|---|---|---|---|
 | [nuggets](https://github.com/NeoVertex1/nuggets) | local memory engine + messaging gateway | topic-scoped HRR memory with `remember`, `recall`, `forget`, fact promotion into `MEMORY.md` | good example of lightweight local memory and automatic promotion | very specific architecture; not a general multi-tenant service |
 | [mem0](https://github.com/mem0ai/mem0) | hosted + OSS SDK | `add`, `search`, `getAll`, `get`, `update`, `delete`, `deleteAll`; entity partitioning via `user_id`, `agent_id`, `run_id`, `app_id` | closest to a clean provider API with identities and metadata filters | provider owns extraction heavily; Paperclip should not assume every backend behaves like mem0 |
+| [AWS Bedrock AgentCore Memory](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/memory.html) | AWS-managed memory service | explicit short-term and long-term memories, actor/session/event APIs, memory strategies, namespace templates, optional self-managed extraction pipeline | strong example of provider-managed memory with clear scoped ids, retention controls, and standalone API access outside a single agent framework | AWS-hosted and IAM-centric; Paperclip would still need its own company/run/comment provenance, cost rollups, and likely a plugin wrapper instead of baking AWS semantics into core |
 | [MemOS](https://github.com/MemTensor/MemOS) | memory OS / framework | unified add-retrieve-edit-delete, memory cubes, multimodal memory, tool memory, async scheduler, feedback/correction | strong source for optional capabilities beyond plain search | much broader than the minimal contract Paperclip should standardize first |
 | [supermemory](https://github.com/supermemoryai/supermemory) | hosted memory + context API | `add`, `profile`, `search.memories`, `search.documents`, document upload, settings; automatic profile building and forgetting | strong example of "context bundle" rather than raw search results | heavily productized around its own ontology and hosted flow |
 | [memU](https://github.com/NevaMind-AI/memU) | proactive agent memory framework | file-system metaphor, proactive loop, intent prediction, always-on companion model | good source for when memory should trigger agent behavior, not just retrieval | proactive assistant framing is broader than Paperclip's task-centric control plane |
@@ -77,6 +79,7 @@ These differences are exactly why Paperclip needs a layered contract instead of
 ### 1. Who owns extraction?
 
 - `mem0`, `supermemory`, and `Memori` expect the provider to infer memories from conversations.
+- `AWS Bedrock AgentCore Memory` supports both provider-managed extraction and self-managed pipelines where the host writes curated long-term memory records.
 - `memsearch` expects the host to decide what markdown to write, then indexes it.
 - `MemOS`, `memU`, `EverMemOS`, and `OpenViking` sit somewhere in between and often expose richer memory construction pipelines.
 
@@ -104,6 +107,7 @@ Paperclip should make plain search the minimum contract and richer outputs optio
 ### 4. Is memory synchronous or asynchronous?
 
 - local tools often work synchronously in-process.
+- `AWS Bedrock AgentCore Memory` is synchronous at the API edge, but its long-term memory path includes background extraction/indexing behavior and retention policies managed by the provider.
 - larger systems add schedulers, background indexing, compaction, or sync jobs.
 
 Paperclip needs both direct request/response operations and background maintenance hooks.

doc/plans/2026-03-17-memory-service-surface-api.md

@@ -7,10 +7,10 @@ Define a Paperclip memory service and surface API that can sit above multiple me
 - company scoping
 - auditability
 - provenance back to Paperclip work objects
-- budget / cost visibility
+- budget and cost visibility
 - plugin-first extensibility
 
-This plan is based on the external landscape summarized in `doc/memory-landscape.md` and on the current Paperclip architecture in:
+This plan is based on the external landscape summarized in `doc/memory-landscape.md`, the AWS AgentCore comparison captured in [PAP-1274](/PAP/issues/PAP-1274), and the current Paperclip architecture in:
 
 - `doc/SPEC-implementation.md`
 - `doc/plugins/PLUGIN_SPEC.md`
@@ -19,23 +19,26 @@ This plan is based on the external landscape summarized in `doc/memory-landscape
 
 ## Recommendation In One Sentence
 
-Paperclip should not embed one opinionated memory engine into core. It should add a company-scoped memory control plane with a small normalized adapter contract, then let built-ins and plugins implement the provider-specific behavior.
+Paperclip should add a company-scoped memory control plane with company default plus agent override resolution, shared hook delivery, and full operation attribution, while leaving extraction and storage semantics to built-ins and plugins.
 
 ## Product Decisions
 
-### 1. Memory is company-scoped by default
+### 1. Memory resolution is company default plus agent override
 
 Every memory binding belongs to exactly one company.
 
-That binding can then be:
+Resolution order in V1:
 
-- the company default
-- an agent override
-- a project override later if we need it
+- company default binding
+- optional per-agent override
+
+There is no per-project override in V1.
+
+Project context can still appear in scope and provenance so providers can use it for retrieval and partitioning, but projects do not participate in binding selection.
 
 No cross-company memory sharing in the initial design.
 
-### 2. Providers are selected by key
+### 2. Providers are selected by stable binding key
 
 Each configured memory provider gets a stable key inside a company, for example:
 
@@ -44,36 +47,53 @@ Each configured memory provider gets a stable key inside a company, for example:
 - `local-markdown`
 - `research-kb`
 
-Agents and services resolve the active provider by key, not by hard-coded vendor logic.
+Agents, tools, and background hooks resolve the active provider by key, not by hard-coded vendor logic.
 
 ### 3. Plugins are the primary provider path
 
 Built-ins are useful for a zero-config local path, but most providers should arrive through the existing Paperclip plugin runtime.
 
-That keeps the core small and matches the current direction that optional knowledge-like systems live at the edges.
+That keeps the core small and matches the broader Paperclip direction that specialized knowledge systems live at the edges.
 
-### 4. Paperclip owns routing, provenance, and accounting
+### 4. Paperclip owns routing, provenance, and policy
 
 Providers should not decide how Paperclip entities map to governance.
 
 Paperclip core should own:
 
+- binding resolution
 - who is allowed to call a memory operation
-- which company / agent / project scope is active
-- what issue / run / comment / document the operation belongs to
-- how usage gets recorded
+- which company, agent, issue, project, run, and subject scope is active
+- what source object the operation belongs to
+- how usage and costs are attributed
+- how operators inspect what happened
 
-### 5. Automatic memory should be narrow at first
+### 5. Paperclip exposes shared hooks, providers own extraction
+
+Paperclip should emit a common set of memory hooks that built-ins, third-party adapters, and plugins can all use.
+
+Those hooks should pass structured Paperclip source objects plus normalized metadata. The provider then decides how to extract from those objects.
+
+Paperclip should not force one extraction pipeline or one canonical "memory text" transform before the provider sees the input.
+
+### 6. Automatic memory should start narrow, but the hook surface should be general
 
 Automatic capture is useful, but broad silent capture is dangerous.
 
-Initial automatic hooks should be:
+Initial built-in automatic hooks should be:
 
+- pre-run hydrate for agent context recall
 - post-run capture from agent runs
-- issue comment / document capture when the binding enables it
-- pre-run recall for agent context hydration
+- optional issue comment capture
+- optional issue document capture
 
-Everything else should start explicit.
+The hook registry itself should be general enough that other providers can subscribe to the same events without core changes.
+
+### 7. No approval gate for binding changes in the open-source product
+
+For the open-source version, changing memory bindings should not require approvals.
+
+Paperclip should still log those changes in activity and preserve full auditability. Approval-gated memory governance can remain an enterprise or future policy layer.
 
 ## Proposed Concepts
 
@@ -83,7 +103,7 @@ A built-in or plugin-supplied implementation that stores and retrieves memory.
 
 Examples:
 
-- local markdown + vector index
+- local markdown plus semantic index
 - mem0 adapter
 - supermemory adapter
 - MemOS adapter
@@ -94,6 +114,15 @@ A company-scoped configuration record that points to a provider and carries prov
 
 This is the object selected by key.
 
+### Memory binding target
+
+A mapping from a Paperclip target to a binding.
+
+V1 targets:
+
+- `company`
+- `agent`
+
 ### Memory scope
 
 The normalized Paperclip scope passed into a provider request.
@@ -105,7 +134,9 @@ At minimum:
 - optional `projectId`
 - optional `issueId`
 - optional `runId`
-- optional `subjectId` for external/user identity
+- optional `subjectId` for external or user identity
+- optional `sessionKey` for providers that organize memory around sessions
+- optional `namespace` for providers that need an explicit partition hint
 
 ### Memory source reference
 
@@ -121,24 +152,36 @@ Supported source kinds should include:
 - `manual_note`
 - `external_document`
 
+### Memory hook
+
+A normalized trigger emitted by Paperclip when something memory-relevant happens.
+
+Initial hook kinds:
+
+- `pre_run_hydrate`
+- `post_run_capture`
+- `issue_comment_capture`
+- `issue_document_capture`
+- `manual_capture`
+
 ### Memory operation
 
-A normalized write, query, browse, or delete action performed through Paperclip.
+A normalized capture, record-write, query, browse, get, correction, or delete action performed through Paperclip.
 
-Paperclip should log every operation, whether the provider is local or external.
+Paperclip should log every memory operation whether the provider is local, plugin-backed, or external.
 
 ## Required Adapter Contract
 
-The required core should be small enough to fit `memsearch`, `mem0`, `Memori`, `MemOS`, or `OpenViking`.
+The required core should be small enough to fit `memsearch`, `mem0`, `Memori`, `MemOS`, or `OpenViking`, but strong enough to satisfy Paperclip's attribution and inspectability requirements.
 
 ```ts
 export interface MemoryAdapterCapabilities {
   profile?: boolean;
-  browse?: boolean;
   correction?: boolean;
-  asyncIngestion?: boolean;
   multimodal?: boolean;
   providerManagedExtraction?: boolean;
+  asyncExtraction?: boolean;
+  providerNativeBrowse?: boolean;
 }
 
 export interface MemoryScope {
@@ -148,6 +191,8 @@ export interface MemoryScope {
   issueId?: string;
   runId?: string;
   subjectId?: string;
+  sessionKey?: string;
+  namespace?: string;
 }
 
 export interface MemorySourceRef {
@@ -168,10 +213,34 @@ export interface MemorySourceRef {
   externalRef?: string;
 }
 
+export interface MemoryHookContext {
+  hookKind:
+    | "pre_run_hydrate"
+    | "post_run_capture"
+    | "issue_comment_capture"
+    | "issue_document_capture"
+    | "manual_capture";
+  hookId: string;
+  triggeredAt: string;
+  actorAgentId?: string;
+  heartbeatRunId?: string;
+}
+
+export interface MemorySourcePayload {
+  text?: string;
+  mimeType?: string;
+  metadata?: Record<string, unknown>;
+  object?: Record<string, unknown>;
+}
+
 export interface MemoryUsage {
   provider: string;
+  biller?: string;
   model?: string;
+  billingType?: "metered_api" | "subscription_included" | "subscription_overage" | "unknown";
+  attributionMode?: "billed_directly" | "included_in_run" | "external_invoice" | "untracked";
   inputTokens?: number;
+  cachedInputTokens?: number;
   outputTokens?: number;
   embeddingTokens?: number;
   costCents?: number;
@@ -179,20 +248,32 @@ export interface MemoryUsage {
   details?: Record<string, unknown>;
 }
 
-export interface MemoryWriteRequest {
-  bindingKey: string;
-  scope: MemoryScope;
-  source: MemorySourceRef;
-  content: string;
-  metadata?: Record<string, unknown>;
-  mode?: "append" | "upsert" | "summarize";
-}
-
 export interface MemoryRecordHandle {
   providerKey: string;
   providerRecordId: string;
 }
 
+export interface MemoryCaptureRequest {
+  bindingKey: string;
+  scope: MemoryScope;
+  source: MemorySourceRef;
+  payload: MemorySourcePayload;
+  hook?: MemoryHookContext;
+  mode?: "capture_residue" | "capture_record";
+  metadata?: Record<string, unknown>;
+}
+
+export interface MemoryRecordWriteRequest {
+  bindingKey: string;
+  scope: MemoryScope;
+  source?: MemorySourceRef;
+  records: Array<{
+    text: string;
+    summary?: string;
+    metadata?: Record<string, unknown>;
+  }>;
+}
+
 export interface MemoryQueryRequest {
   bindingKey: string;
   scope: MemoryScope;
@@ -202,6 +283,14 @@ export interface MemoryQueryRequest {
   metadataFilter?: Record<string, unknown>;
 }
 
+export interface MemoryListRequest {
+  bindingKey: string;
+  scope: MemoryScope;
+  cursor?: string;
+  limit?: number;
+  metadataFilter?: Record<string, unknown>;
+}
+
 export interface MemorySnippet {
   handle: MemoryRecordHandle;
   text: string;
@@ -217,30 +306,149 @@ export interface MemoryContextBundle {
   usage?: MemoryUsage[];
 }
 
+export interface MemoryListPage {
+  items: MemorySnippet[];
+  nextCursor?: string;
+  usage?: MemoryUsage[];
+}
+
+export interface MemoryExtractionJob {
+  providerJobId: string;
+  status: "queued" | "running" | "succeeded" | "failed" | "cancelled";
+  hookKind?: MemoryHookContext["hookKind"];
+  source?: MemorySourceRef;
+  error?: string;
+  submittedAt?: string;
+  startedAt?: string;
+  finishedAt?: string;
+}
+
 export interface MemoryAdapter {
   key: string;
   capabilities: MemoryAdapterCapabilities;
-  write(req: MemoryWriteRequest): Promise<{
+  capture(req: MemoryCaptureRequest): Promise<{
+    records?: MemoryRecordHandle[];
+    jobs?: MemoryExtractionJob[];
+    usage?: MemoryUsage[];
+  }>;
+  upsertRecords(req: MemoryRecordWriteRequest): Promise<{
     records?: MemoryRecordHandle[];
     usage?: MemoryUsage[];
   }>;
   query(req: MemoryQueryRequest): Promise<MemoryContextBundle>;
+  list(req: MemoryListRequest): Promise<MemoryListPage>;
   get(handle: MemoryRecordHandle, scope: MemoryScope): Promise<MemorySnippet | null>;
   forget(handles: MemoryRecordHandle[], scope: MemoryScope): Promise<{ usage?: MemoryUsage[] }>;
 }
 ```
 
-This contract intentionally does not force a provider to expose its internal graph, filesystem, or ontology.
+This contract intentionally does not force a provider to expose its internal graph, file tree, or ontology. It does require enough structure for Paperclip to browse, attribute, and audit what happened.
 
 ## Optional Adapter Surfaces
 
 These should be capability-gated, not required:
 
-- `browse(scope, filters)` for file-system / graph / timeline inspection
 - `correct(handle, patch)` for natural-language correction flows
 - `profile(scope)` when the provider can synthesize stable preferences or summaries
-- `sync(source)` for connectors or background ingestion
+- `listExtractionJobs(scope, cursor)` when async extraction needs richer operator visibility
+- `retryExtractionJob(jobId)` when a provider supports re-drive
 - `explain(queryResult)` for providers that can expose retrieval traces
+- provider-native browse or graph surfaces exposed through plugin UI
+
+## Lessons From AWS AgentCore Memory API
+
+AWS AgentCore Memory is a useful check on whether this plan is too abstract or missing important operational surfaces.
+
+The broad direction still looks right:
+
+- AWS splits memory into a control plane (`CreateMemory`, `UpdateMemory`, `ListMemories`) and a data plane (`CreateEvent`, `RetrieveMemoryRecords`, `GetMemoryRecord`, `ListMemoryRecords`)
+- AWS separates raw interaction capture from curated long-term memory records
+- AWS supports both provider-managed extraction and self-managed pipelines
+- AWS treats browse and list operations as first-class APIs, not ad hoc debugging helpers
+- AWS exposes extraction jobs instead of hiding asynchronous maintenance completely
+
+That lines up with the Paperclip plan at a high level: provider configuration, scoped writes, scoped retrieval, provider-managed extraction as a capability, and a browse and inspect surface.
+
+The concrete changes Paperclip should take from AWS are:
+
+### 1. Keep config APIs separate from runtime traffic
+
+The rollout should preserve a clean separation between:
+
+- control-plane APIs for binding CRUD, defaults, overrides, and capability metadata
+- runtime APIs and tools for capture, record writes, query, list, get, forget, and extraction status
+
+This keeps governance changes distinct from high-volume memory traffic.
+
+### 2. Distinguish capture from curated record writes
+
+AWS does not flatten everything into one write primitive. It distinguishes captured events from durable memory records.
+
+Paperclip should do the same:
+
+- `capture(...)` for raw run, comment, document, or activity residue
+- `upsertRecords(...)` for curated durable facts and notes
+
+That is a better fit for provider-managed extraction and for manual curation flows.
+
+### 3. Make list and browse first-class
+
+AWS exposes list and retrieve surfaces directly. Paperclip should not make browse optional at the portable layer.
+
+The minimum portable surface should include:
+
+- `query`
+- `list`
+- `get`
+
+Provider-native graph or file browsing can remain optional beyond that.
+
+### 4. Add pagination and cursors for operator inspection
+
+AWS consistently uses pagination on browse-heavy APIs.
+
+Paperclip should add cursor-based pagination to:
+
+- record listing
+- extraction job listing
+- memory operation explorer APIs
+
+Prompt hydration can continue to use `topK`, but operator surfaces need cursors.
+
+### 5. Add explicit session and namespace hints
+
+AWS uses `actorId`, `sessionId`, `namespace`, and `memoryStrategyId` heavily.
+
+Paperclip should keep its own control-plane-centric model, but the adapter contract needs obvious places to map those concepts:
+
+- `sessionKey`
+- `namespace`
+
+The provider adapter can map them to AWS or other vendor-specific identifiers without leaking those identifiers into core.
+
+### 6. Treat asynchronous extraction as a real operational surface
+
+AWS exposes extraction jobs explicitly. Paperclip should too.
+
+Operators should be able to see:
+
+- pending extraction work
+- failed extraction work
+- which hook or source caused the work
+- whether a retry is available
+
+### 7. Keep Paperclip provenance primary
+
+Paperclip should continue to center:
+
+- `companyId`
+- `agentId`
+- `projectId`
+- `issueId`
+- `runId`
+- issue comments, documents, and activity as sources
+
+The lesson from AWS is to support clean mapping into provider-specific models, not to let provider identifiers take over the core product model.
 
 ## What Paperclip Should Persist
 
@@ -248,39 +456,67 @@ Paperclip should not mirror the full provider memory corpus into Postgres unless
 
 Paperclip core should persist:
 
-- memory bindings and overrides
+- memory bindings
+- company default and agent override resolution targets
 - provider keys and capability metadata
 - normalized memory operation logs
-- provider record handles returned by operations when available
 - source references back to issue comments, documents, runs, and activity
-- usage and cost data
+- provider record handles returned by operations when available
+- hook delivery records and extraction job state
+- usage and cost attribution
 
-For external providers, the memory payload itself can remain in the provider.
+For external providers, the actual memory payload can remain in the provider.
 
 ## Hook Model
 
-### Automatic hooks
+### Shared hook surface
+
+Paperclip should expose one shared hook system for memory.
+
+That same system must be available to:
+
+- built-in memory providers
+- plugin-based memory providers
+- third-party adapter integrations that want to use memory hooks
+
+### What a hook delivers
+
+Each hook delivery should include:
+
+- resolved binding key
+- normalized `MemoryScope`
+- `MemorySourceRef`
+- structured source payload
+- hook metadata such as hook kind, trigger time, and related run id
+
+The payload should include structured objects where possible so the provider can decide how to extract and chunk.
+
+### Initial automatic hooks
 
 These should be low-risk and easy to reason about:
 
-1. `pre-run hydrate`
+1. `pre_run_hydrate`
    Before an agent run starts, Paperclip may call `query(... intent = "agent_preamble")` using the active binding.
 
-2. `post-run capture`
-   After a run finishes, Paperclip may write a summary or transcript-derived note tied to the run.
+2. `post_run_capture`
+   After a run finishes, Paperclip may call `capture(...)` with structured run output, excerpts, and provenance.
 
-3. `issue comment / document capture`
-   When enabled on the binding, Paperclip may capture selected issue comments or issue documents as memory sources.
+3. `issue_comment_capture`
+   When enabled on the binding, Paperclip may call `capture(...)` for selected issue comments.
 
-### Explicit hooks
+4. `issue_document_capture`
+   When enabled on the binding, Paperclip may call `capture(...)` for selected issue documents.
 
-These should be tool- or UI-driven first:
+### Explicit tools and APIs
+
+These should be tool-driven or UI-driven first:
 
 - `memory.search`
 - `memory.note`
 - `memory.forget`
 - `memory.correct`
-- `memory.browse`
+- memory record list and get
+- extraction-job inspection
 
 ### Not automatic in the first version
 
@@ -309,34 +545,69 @@ The initial browse surface should support:
 
 - active binding by company and agent
 - recent memory operations
-- recent write sources
+- recent write and capture sources
+- record list and record detail with source backlinks
 - query results with source backlinks
-- filters by agent, issue, run, source kind, and date
-- provider usage / cost / latency summaries
+- extraction job status
+- filters by agent, issue, project, run, source kind, and date
+- provider usage, cost, and latency summaries
 
 When a provider supports richer browsing, the plugin can add deeper views through the existing plugin UI surfaces.
 
 ## Cost And Evaluation
 
-Every adapter response should be able to return usage records.
+Paperclip should treat memory accounting as two related but distinct concerns:
 
-Paperclip should roll up:
+### 1. `memory_operations` is the authoritative audit trail
 
-- memory inference tokens
-- embedding tokens
-- external provider cost
+Every memory action should create a normalized operation record that captures:
+
+- binding
+- scope
+- source provenance
+- operation type
+- success or failure
 - latency
-- query count
-- write count
+- usage details reported by the provider
+- attribution mode
+- related run, issue, and agent when available
 
-It should also record evaluation-oriented metrics where possible:
+This is where operators answer "what memory work happened and why?"
+
+### 2. `cost_events` remains the canonical spend ledger for billable metered usage
+
+The current `cost_events` model is already the canonical cost ledger for token and model spend, and `agent_runtime_state` plus `heartbeat_runs.usageJson` already roll up and summarize run usage.
+
+The recommendation is:
+
+- if a memory operation runs inside a normal Paperclip agent heartbeat and the model usage is already counted on that run, do not create a duplicate `cost_event`
+- instead, store the memory operation with `attributionMode = "included_in_run"` and link it to the related `heartbeatRunId`
+- if a memory provider makes a direct metered model call outside the agent run accounting path, the provider must report usage and Paperclip should create a `cost_event`
+- that direct `cost_event` should still link back to the memory operation, agent, company, and issue or run context when possible
+
+### 3. `finance_events` should carry flat subscription or invoice-style costs
+
+If a memory service incurs:
+
+- monthly subscription cost
+- storage invoices
+- provider platform charges not tied to one request
+
+those should be represented as `finance_events`, not as synthetic per-query memory operations.
+
+That keeps usage telemetry separate from accounting entries like invoices and flat fees.
+
+### 4. Evaluation metrics still matter
+
+Paperclip should record evaluation-oriented metrics where possible:
 
 - recall hit rate
 - empty query rate
 - manual correction count
-- per-binding success / failure counts
+- extraction failure count
+- per-binding success and failure counts
 
-This is important because a memory system that "works" but silently burns budget is not acceptable in Paperclip.
+This is important because a memory system that "works" but silently burns budget or silently fails extraction is not acceptable in Paperclip.
 
 ## Suggested Data Model Additions
 
@@ -344,23 +615,36 @@ At the control-plane level, the likely new core tables are:
 
 - `memory_bindings`
   - company-scoped key
-  - provider id / plugin id
+  - provider id or plugin id
   - config blob
   - enabled status
 
 - `memory_binding_targets`
-  - target type (`company`, `agent`, later `project`)
+  - target type (`company`, `agent`)
   - target id
   - binding id
 
 - `memory_operations`
   - company id
   - binding id
-  - operation type (`write`, `query`, `forget`, `browse`, `correct`)
+  - operation type (`capture`, `record_upsert`, `query`, `list`, `get`, `forget`, `correct`)
   - scope fields
   - source refs
-  - usage / latency / cost
-  - success / error
+  - usage, latency, and attribution mode
+  - related heartbeat run id
+  - related cost event id
+  - success or error
+
+- `memory_extraction_jobs`
+  - company id
+  - binding id
+  - operation id
+  - provider job id
+  - hook kind
+  - status
+  - source refs
+  - error
+  - submitted, started, and finished timestamps
 
 Provider-specific long-form state should stay in plugin state or the provider itself unless a built-in local provider needs its own schema.
 
@@ -382,45 +666,46 @@ The design should still treat that built-in as just another provider behind the
 ### Phase 1: Control-plane contract
 
 - add memory binding models and API types
-- add plugin capability / registration surface for memory providers
-- add operation logging and usage reporting
+- add company default plus agent override resolution
+- add plugin capability and registration surface for memory providers
 
-### Phase 2: One built-in + one plugin example
+### Phase 2: Hook delivery and operation audit
+
+- add shared memory hook emission in core
+- add operation logging, extraction job state, and usage attribution
+- add direct-provider cost and finance-event linkage rules
+
+### Phase 3: One built-in plus one plugin example
 
 - ship a local markdown-first provider
 - ship one hosted adapter example to validate the external-provider path
 
-### Phase 3: UI inspection
+### Phase 4: UI inspection
 
-- add company / agent memory settings
+- add company and agent memory settings
 - add a memory operation explorer
+- add record list and detail surfaces
 - add source backlinks to issues and runs
 
-### Phase 4: Automatic hooks
-
-- pre-run hydrate
-- post-run capture
-- selected issue comment / document capture
-
 ### Phase 5: Rich capabilities
 
 - correction flows
-- provider-native browse / graph views
-- project-level overrides if needed
+- provider-native browse or graph views
 - evaluation dashboards
+- retention and quota controls
 
-## Open Questions
+## Remaining Open Questions
 
-- Should project overrides exist in V1 of the memory service, or should we force company default + agent override first?
-- Do we want Paperclip-managed extraction pipelines at all, or should built-ins be the only place where Paperclip owns extraction?
-- Should memory usage extend the current `cost_events` model directly, or should memory operations keep a parallel usage log and roll up into `cost_events` secondarily?
-- Do we want provider install / binding changes to require approvals for some companies?
+- Which built-in local provider should ship first: pure markdown, markdown plus embeddings, or a lightweight local vector store?
+- How much source payload should Paperclip snapshot inside `memory_operations` for debugging without duplicating large transcripts?
+- Should correction flows mutate provider state directly, create superseding records, or both depending on provider capability?
+- What default retention and size limits should the local built-in enforce?
 
 ## Bottom Line
 
 The right abstraction is:
 
-- Paperclip owns memory bindings, scopes, provenance, governance, and usage reporting.
+- Paperclip owns bindings, resolution, hooks, provenance, policy, and attribution.
 - Providers own extraction, ranking, storage, and provider-native memory semantics.
 
-That gives Paperclip a stable "memory service" without locking the product to one memory philosophy or one vendor.
+That gives Paperclip a stable memory service without locking the product to one memory philosophy or one vendor, and it integrates the AWS lessons without importing AWS's model into core.

docs/adapters/codex-local.md

@@ -20,6 +20,7 @@ The `codex_local` adapter runs OpenAI's Codex CLI locally. It supports session p
 | `env` | object | No | Environment variables (supports secret refs) |
 | `timeoutSec` | number | No | Process timeout (0 = no timeout) |
 | `graceSec` | number | No | Grace period before force-kill |
+| `fastMode` | boolean | No | Enables Codex Fast mode. Currently supported on `gpt-5.4` only and burns credits faster |
 | `dangerouslyBypassApprovalsAndSandbox` | boolean | No | Skip safety checks (dev only) |
 
 ## Session Persistence
@@ -30,8 +31,22 @@ Codex uses `previous_response_id` for session continuity. The adapter serializes
 
 The adapter symlinks Paperclip skills into the global Codex skills directory (`~/.codex/skills`). Existing user skills are not overwritten.
 
+## Fast Mode
+
+When `fastMode` is enabled, Paperclip adds Codex config overrides equivalent to:
+
+```sh
+-c 'service_tier="fast"' -c 'features.fast_mode=true'
+```
+
+Paperclip currently applies that only when the selected model is `gpt-5.4`. On other models, the toggle is preserved in config but ignored at execution time to avoid unsupported runs.
+
+## Managed `CODEX_HOME`
+
 When Paperclip is running inside a managed worktree instance (`PAPERCLIP_IN_WORKTREE=true`), the adapter instead uses a worktree-isolated `CODEX_HOME` under the Paperclip instance so Codex skills, sessions, logs, and other runtime state do not leak across checkouts. It seeds that isolated home from the user's main Codex home for shared auth/config continuity.
 
+## Manual Local CLI
+
 For manual local CLI usage outside heartbeat runs (for example running as `codexcoder` directly), use:
 
 ```sh

docs/cli/setup-commands.md

@@ -89,6 +89,8 @@ Show resolved environment configuration:
 pnpm paperclipai env
 ```
 
+This now includes bind-oriented deployment settings such as `PAPERCLIP_BIND` and `PAPERCLIP_BIND_HOST` when configured.
+
 ## `paperclipai allowed-hostname`
 
 Allow a private hostname for authenticated/private mode:

docs/deploy/deployment-modes.md

@@ -3,13 +3,14 @@ title: Deployment Modes
 summary: local_trusted vs authenticated (private/public)
 ---
 
-Paperclip supports two runtime modes with different security profiles.
+Paperclip supports two runtime modes with different security profiles. Reachability is configured separately with `bind`.
 
 ## `local_trusted`
 
 The default mode. Optimized for single-operator local use.
 
 - **Host binding**: loopback only (localhost)
+- **Bind**: `loopback`
 - **Authentication**: no login required
 - **Use case**: local development, solo experimentation
 - **Board identity**: auto-created local board user
@@ -31,6 +32,7 @@ For private network access (Tailscale, VPN, LAN).
 - **Authentication**: login required via Better Auth
 - **URL handling**: auto base URL mode (lower friction)
 - **Host trust**: private-host trust policy required
+- **Bind**: choose `loopback`, `lan`, `tailnet`, or `custom`
 
 ```sh
 pnpm paperclipai onboard
@@ -50,6 +52,7 @@ For internet-facing deployment.
 - **Authentication**: login required
 - **URL**: explicit public URL required
 - **Security**: stricter deployment checks in doctor
+- **Bind**: usually `loopback` behind a reverse proxy; `lan/custom` is advanced
 
 ```sh
 pnpm paperclipai onboard
@@ -81,5 +84,5 @@ pnpm paperclipai configure --section server
 Runtime override via environment variable:
 
 ```sh
-PAPERCLIP_DEPLOYMENT_MODE=authenticated pnpm paperclipai run
+PAPERCLIP_DEPLOYMENT_MODE=authenticated PAPERCLIP_BIND=lan pnpm paperclipai run
 ```

docs/deploy/environment-variables.md

@@ -10,11 +10,14 @@ All environment variables that Paperclip uses for server configuration.
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `PORT` | `3100` | Server port |
-| `HOST` | `127.0.0.1` | Server host binding |
+| `PAPERCLIP_BIND` | `loopback` | Reachability preset: `loopback`, `lan`, `tailnet`, or `custom` |
+| `PAPERCLIP_BIND_HOST` | (unset) | Required when `PAPERCLIP_BIND=custom` |
+| `HOST` | `127.0.0.1` | Legacy host override; prefer `PAPERCLIP_BIND` for new setups |
 | `DATABASE_URL` | (embedded) | PostgreSQL connection string |
 | `PAPERCLIP_HOME` | `~/.paperclip` | Base directory for all Paperclip data |
 | `PAPERCLIP_INSTANCE_ID` | `default` | Instance identifier (for multiple local instances) |
 | `PAPERCLIP_DEPLOYMENT_MODE` | `local_trusted` | Runtime mode override |
+| `PAPERCLIP_DEPLOYMENT_EXPOSURE` | `private` | Exposure policy when deployment mode is `authenticated` |
 
 ## Secrets
 

docs/deploy/local-development.md

@@ -38,19 +38,26 @@ This does:
 2. Runs `paperclipai doctor` with repair enabled
 3. Starts the server when checks pass
 
-## Tailscale/Private Auth Dev Mode
+## Bind Presets In Dev
 
-To run in `authenticated/private` mode for network access:
+Default `pnpm dev` stays in `local_trusted` with loopback-only binding.
+
+To open Paperclip to a private network with login enabled:
+
+```sh
+pnpm dev --bind lan
+```
+
+For Tailscale-only binding on a detected tailnet address:
+
+```sh
+pnpm dev --bind tailnet
+```
+
+Legacy aliases still work and map to the older broad private-network behavior:
 
 ```sh
 pnpm dev --tailscale-auth
-```
-
-This binds the server to `0.0.0.0` for private-network access.
-
-Alias:
-
-```sh
 pnpm dev --authenticated-private
 ```
 

docs/deploy/tailscale-private-access.md

@@ -1,6 +1,6 @@
 ---
 title: Tailscale Private Access
-summary: Run Paperclip with Tailscale-friendly host binding and connect from other devices
+summary: Run Paperclip with Tailscale-friendly bind presets and connect from other devices
 ---
 
 Use this when you want to access Paperclip over Tailscale (or a private LAN/VPN) instead of only `localhost`.
@@ -8,20 +8,25 @@ Use this when you want to access Paperclip over Tailscale (or a private LAN/VPN)
 ## 1. Start Paperclip in private authenticated mode
 
 ```sh
-pnpm dev --tailscale-auth
+pnpm dev --bind tailnet
 ```
 
-This configures:
+Recommended behavior:
 
 - `PAPERCLIP_DEPLOYMENT_MODE=authenticated`
 - `PAPERCLIP_DEPLOYMENT_EXPOSURE=private`
-- `PAPERCLIP_AUTH_BASE_URL_MODE=auto`
-- `HOST=0.0.0.0` (bind on all interfaces)
+- `PAPERCLIP_BIND=tailnet`
 
-Equivalent flag:
+If you want the old broad private-network behavior instead, use:
 
 ```sh
+pnpm dev --bind lan
+```
+
+Legacy aliases still map to `authenticated/private + bind=lan`:
+
 pnpm dev --authenticated-private
+pnpm dev --tailscale-auth
 ```
 
 ## 2. Find your reachable Tailscale address
@@ -73,5 +78,5 @@ Expected result:
 ## Troubleshooting
 
 - Login or redirect errors on a private hostname: add it with `paperclipai allowed-hostname`.
-- App only works on `localhost`: make sure you started with `--tailscale-auth` (or set `HOST=0.0.0.0` in private mode).
+- App only works on `localhost`: make sure you started with `--bind lan` or `--bind tailnet` instead of plain `pnpm dev`.
 - Can connect locally but not remotely: verify both devices are on the same Tailscale network and port `3100` is reachable.

package.json

@@ -3,6 +3,7 @@
   "private": true,
   "type": "module",
   "scripts": {
+    "preflight:workspace-links": "node cli/node_modules/tsx/dist/cli.mjs scripts/ensure-workspace-package-links.ts",
     "dev": "pnpm --filter @paperclipai/server exec tsx ../scripts/dev-runner.ts watch",
     "dev:watch": "pnpm --filter @paperclipai/server exec tsx ../scripts/dev-runner.ts watch",
     "dev:once": "pnpm --filter @paperclipai/server exec tsx ../scripts/dev-runner.ts dev",
@@ -10,10 +11,10 @@
     "dev:stop": "pnpm --filter @paperclipai/server exec tsx ../scripts/dev-service.ts stop",
     "dev:server": "pnpm --filter @paperclipai/server dev",
     "dev:ui": "pnpm --filter @paperclipai/ui dev",
-    "build": "pnpm -r build",
-    "typecheck": "pnpm -r typecheck",
-    "test": "vitest",
-    "test:run": "vitest run",
+    "build": "pnpm run preflight:workspace-links && pnpm -r build",
+    "typecheck": "pnpm run preflight:workspace-links && pnpm -r typecheck",
+    "test": "pnpm run preflight:workspace-links && vitest",
+    "test:run": "pnpm run preflight:workspace-links && vitest run",
     "db:generate": "pnpm --filter @paperclipai/db generate",
     "db:migrate": "pnpm --filter @paperclipai/db migrate",
     "secrets:migrate-inline-env": "tsx scripts/migrate-inline-env-secrets.ts",

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

@@ -2,6 +2,24 @@ import { randomUUID } from "node:crypto";
 import { describe, expect, it } from "vitest";
 import { runChildProcess } from "./server-utils.js";
 
+function isPidAlive(pid: number) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function waitForPidExit(pid: number, timeoutMs = 2_000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!isPidAlive(pid)) return true;
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+  return !isPidAlive(pid);
+}
+
 describe("runChildProcess", () => {
   it("waits for onSpawn before sending stdin to the child", async () => {
     const spawnDelayMs = 150;
@@ -35,4 +53,36 @@ describe("runChildProcess", () => {
     expect(onSpawnCompletedAt).toBeGreaterThanOrEqual(startedAt + spawnDelayMs);
     expect(finishedAt - startedAt).toBeGreaterThanOrEqual(spawnDelayMs);
   });
+
+  it.skipIf(process.platform === "win32")("kills descendant processes on timeout via the process group", async () => {
+    let descendantPid: number | null = null;
+
+    const result = await runChildProcess(
+      randomUUID(),
+      process.execPath,
+      [
+        "-e",
+        [
+          "const { spawn } = require('node:child_process');",
+          "const child = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)'], { stdio: 'ignore' });",
+          "process.stdout.write(String(child.pid));",
+          "setInterval(() => {}, 1000);",
+        ].join(" "),
+      ],
+      {
+        cwd: process.cwd(),
+        env: {},
+        timeoutSec: 1,
+        graceSec: 1,
+        onLog: async () => {},
+        onSpawn: async () => {},
+      },
+    );
+
+    descendantPid = Number.parseInt(result.stdout.trim(), 10);
+    expect(result.timedOut).toBe(true);
+    expect(Number.isInteger(descendantPid) && descendantPid > 0).toBe(true);
+
+    expect(await waitForPidExit(descendantPid!, 2_000)).toBe(true);
+  });
 });

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

@@ -19,6 +19,7 @@ export interface RunProcessResult {
 interface RunningProcess {
   child: ChildProcess;
   graceSec: number;
+  processGroupId: number | null;
 }
 
 interface SpawnTarget {
@@ -34,6 +35,28 @@ type ChildProcessWithEvents = ChildProcess & {
   ): ChildProcess;
 };
 
+function resolveProcessGroupId(child: ChildProcess) {
+  if (process.platform === "win32") return null;
+  return typeof child.pid === "number" && child.pid > 0 ? child.pid : null;
+}
+
+function signalRunningProcess(
+  running: Pick<RunningProcess, "child" | "processGroupId">,
+  signal: NodeJS.Signals,
+) {
+  if (process.platform !== "win32" && running.processGroupId && running.processGroupId > 0) {
+    try {
+      process.kill(-running.processGroupId, signal);
+      return;
+    } catch {
+      // Fall back to the direct child signal if group signaling fails.
+    }
+  }
+  if (!running.child.killed) {
+    running.child.kill(signal);
+  }
+}
+
 export const runningProcesses = new Map<string, RunningProcess>();
 export const MAX_CAPTURE_BYTES = 4 * 1024 * 1024;
 export const MAX_EXCERPT_BYTES = 32 * 1024;
@@ -1034,7 +1057,7 @@ export async function runChildProcess(
     graceSec: number;
     onLog: (stream: "stdout" | "stderr", chunk: string) => Promise<void>;
     onLogError?: (err: unknown, runId: string, message: string) => void;
-    onSpawn?: (meta: { pid: number; startedAt: string }) => Promise<void>;
+    onSpawn?: (meta: { pid: number; processGroupId: number | null; startedAt: string }) => Promise<void>;
     stdin?: string;
   },
 ): Promise<RunProcessResult> {
@@ -1064,19 +1087,21 @@ export async function runChildProcess(
         const child = spawn(target.command, target.args, {
           cwd: opts.cwd,
           env: mergedEnv,
+          detached: process.platform !== "win32",
           shell: false,
           stdio: [opts.stdin != null ? "pipe" : "ignore", "pipe", "pipe"],
         }) as ChildProcessWithEvents;
         const startedAt = new Date().toISOString();
+        const processGroupId = resolveProcessGroupId(child);
 
         const spawnPersistPromise =
           typeof child.pid === "number" && child.pid > 0 && opts.onSpawn
-            ? opts.onSpawn({ pid: child.pid, startedAt }).catch((err) => {
+            ? opts.onSpawn({ pid: child.pid, processGroupId, startedAt }).catch((err) => {
               onLogError(err, runId, "failed to record child process metadata");
             })
             : Promise.resolve();
 
-        runningProcesses.set(runId, { child, graceSec: opts.graceSec });
+        runningProcesses.set(runId, { child, graceSec: opts.graceSec, processGroupId });
 
         let timedOut = false;
         let stdout = "";
@@ -1087,11 +1112,9 @@ export async function runChildProcess(
           opts.timeoutSec > 0
             ? setTimeout(() => {
                 timedOut = true;
-                child.kill("SIGTERM");
+                signalRunningProcess({ child, processGroupId }, "SIGTERM");
                 setTimeout(() => {
-                  if (!child.killed) {
-                    child.kill("SIGKILL");
-                  }
+                  signalRunningProcess({ child, processGroupId }, "SIGKILL");
                 }, Math.max(1, opts.graceSec) * 1000);
               }, opts.timeoutSec * 1000)
             : null;

packages/adapter-utils/src/types.ts

@@ -120,7 +120,7 @@ export interface AdapterExecutionContext {
   context: Record<string, unknown>;
   onLog: (stream: "stdout" | "stderr", chunk: string) => Promise<void>;
   onMeta?: (meta: AdapterInvocationMeta) => Promise<void>;
-  onSpawn?: (meta: { pid: number; startedAt: string }) => Promise<void>;
+  onSpawn?: (meta: { pid: number; processGroupId: number | null; startedAt: string }) => Promise<void>;
   authToken?: string;
 }
 
@@ -372,6 +372,7 @@ export interface CreateConfigValues {
   chrome: boolean;
   dangerouslySkipPermissions: boolean;
   search: boolean;
+  fastMode: boolean;
   dangerouslyBypassSandbox: boolean;
   command: string;
   args: string;

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

@@ -1,5 +1,4 @@
 import fs from "node:fs/promises";
-import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import type { AdapterExecutionContext, AdapterExecutionResult } from "@paperclipai/adapter-utils";
@@ -33,35 +32,10 @@ import {
 } from "./parse.js";
 import { resolveClaudeDesiredSkillNames } from "./skills.js";
 import { isBedrockModelId } from "./models.js";
+import { prepareClaudePromptBundle } from "./prompt-cache.js";
 
 const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
 
-/**
- * Create a tmpdir with `.claude/skills/` containing symlinks to skills from
- * the repo's `skills/` directory, so `--add-dir` makes Claude Code discover
- * them as proper registered skills.
- */
-async function buildSkillsDir(config: Record<string, unknown>): Promise<string> {
-  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-skills-"));
-  const target = path.join(tmp, ".claude", "skills");
-  await fs.mkdir(target, { recursive: true });
-  const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
-  const desiredNames = new Set(
-    resolveClaudeDesiredSkillNames(
-      config,
-      availableEntries,
-    ),
-  );
-  for (const entry of availableEntries) {
-    if (!desiredNames.has(entry.key)) continue;
-    await fs.symlink(
-      entry.source,
-      path.join(target, entry.runtimeName),
-    );
-  }
-  return tmp;
-}
-
 interface ClaudeExecutionInput {
   runId: string;
   agent: AdapterExecutionContext["agent"];
@@ -361,47 +335,64 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     ),
   );
   const billingType = resolveClaudeBillingType(effectiveEnv);
-  const skillsDir = await buildSkillsDir(config);
-
-  const runtimeSessionParams = parseObject(runtime.sessionParams);
-  const runtimeSessionId = asString(runtimeSessionParams.sessionId, runtime.sessionId ?? "");
-  const runtimeSessionCwd = asString(runtimeSessionParams.cwd, "");
-  const canResumeSession =
-    runtimeSessionId.length > 0 &&
-    (runtimeSessionCwd.length === 0 || path.resolve(runtimeSessionCwd) === path.resolve(cwd));
-  const sessionId = canResumeSession ? runtimeSessionId : null;
-  if (runtimeSessionId && !canResumeSession) {
-    await onLog(
-      "stdout",
-      `[paperclip] Claude session "${runtimeSessionId}" was saved for cwd "${runtimeSessionCwd}" and will not be resumed in "${cwd}".\n`,
-    );
-  }
-
-  let effectiveInstructionsFilePath: string | undefined;
-  let preparedInstructionsFile = false;
-
-  const ensureEffectiveInstructionsFilePath = async (resumeSessionId: string | null) => {
-    if (resumeSessionId || !instructionsFilePath) return undefined;
-    if (preparedInstructionsFile) return effectiveInstructionsFilePath;
-
-    preparedInstructionsFile = true;
+  const claudeSkillEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
+  const desiredSkillNames = new Set(resolveClaudeDesiredSkillNames(config, claudeSkillEntries));
+  // When instructionsFilePath is configured, build a stable content-addressed
+  // file that includes both the file content and the path directive, so we only
+  // need --append-system-prompt-file (Claude CLI forbids using both flags together).
+  let combinedInstructionsContents: string | null = null;
+  if (instructionsFilePath) {
     try {
       const instructionsContent = await fs.readFile(instructionsFilePath, "utf-8");
-      const pathDirective = `\nThe above agent instructions were loaded from ${instructionsFilePath}. Resolve any relative file references from ${instructionsFileDir}.`;
-      const combinedPath = path.join(skillsDir, "agent-instructions.md");
-      await fs.writeFile(combinedPath, instructionsContent + pathDirective, "utf-8");
-      effectiveInstructionsFilePath = combinedPath;
+      const pathDirective =
+        `\nThe above agent instructions were loaded from ${instructionsFilePath}. ` +
+        `Resolve any relative file references from ${instructionsFileDir}. ` +
+        `This base directory is authoritative for sibling instruction files such as ` +
+        `./HEARTBEAT.md, ./SOUL.md, and ./TOOLS.md; do not resolve those from the parent agent directory.`;
+      combinedInstructionsContents = instructionsContent + pathDirective;
     } catch (err) {
       const reason = err instanceof Error ? err.message : String(err);
       await onLog(
         "stderr",
         `[paperclip] Warning: could not read agent instructions file "${instructionsFilePath}": ${reason}\n`,
       );
-      effectiveInstructionsFilePath = undefined;
     }
+  }
+  const promptBundle = await prepareClaudePromptBundle({
+    companyId: agent.companyId,
+    skills: claudeSkillEntries.filter((entry) => desiredSkillNames.has(entry.key)),
+    instructionsContents: combinedInstructionsContents,
+    onLog,
+  });
+  const effectiveInstructionsFilePath = promptBundle.instructionsFilePath ?? undefined;
 
-    return effectiveInstructionsFilePath;
-  };
+  const runtimeSessionParams = parseObject(runtime.sessionParams);
+  const runtimeSessionId = asString(runtimeSessionParams.sessionId, runtime.sessionId ?? "");
+  const runtimeSessionCwd = asString(runtimeSessionParams.cwd, "");
+  const runtimePromptBundleKey = asString(runtimeSessionParams.promptBundleKey, "");
+  const hasMatchingPromptBundle =
+    runtimePromptBundleKey.length === 0 || runtimePromptBundleKey === promptBundle.bundleKey;
+  const canResumeSession =
+    runtimeSessionId.length > 0 &&
+    hasMatchingPromptBundle &&
+    (runtimeSessionCwd.length === 0 || path.resolve(runtimeSessionCwd) === path.resolve(cwd));
+  const sessionId = canResumeSession ? runtimeSessionId : null;
+  if (
+    runtimeSessionId &&
+    runtimeSessionCwd.length > 0 &&
+    path.resolve(runtimeSessionCwd) !== path.resolve(cwd)
+  ) {
+    await onLog(
+      "stdout",
+      `[paperclip] Claude session "${runtimeSessionId}" was saved for cwd "${runtimeSessionCwd}" and will not be resumed in "${cwd}".\n`,
+    );
+  }
+  if (runtimeSessionId && runtimePromptBundleKey.length > 0 && runtimePromptBundleKey !== promptBundle.bundleKey) {
+    await onLog(
+      "stdout",
+      `[paperclip] Claude session "${runtimeSessionId}" was saved for prompt bundle "${runtimePromptBundleKey}" and will not be resumed with "${promptBundle.bundleKey}".\n`,
+    );
+  }
   const bootstrapPromptTemplate = asString(config.bootstrapPromptTemplate, "");
   const templateData = {
     agentId: agent.id,
@@ -456,7 +447,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     if (attemptInstructionsFilePath && !resumeSessionId) {
       args.push("--append-system-prompt-file", attemptInstructionsFilePath);
     }
-    args.push("--add-dir", skillsDir);
+    args.push("--add-dir", promptBundle.addDir);
     if (extraArgs.length > 0) args.push(...extraArgs);
     return args;
   };
@@ -478,14 +469,17 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   };
 
   const runAttempt = async (resumeSessionId: string | null) => {
-    const attemptInstructionsFilePath = await ensureEffectiveInstructionsFilePath(resumeSessionId);
+    const attemptInstructionsFilePath = resumeSessionId ? undefined : effectiveInstructionsFilePath;
     const args = buildClaudeArgs(resumeSessionId, attemptInstructionsFilePath);
-    const commandNotes =
-      attemptInstructionsFilePath && !resumeSessionId
-        ? [
-            `Injected agent instructions via --append-system-prompt-file ${instructionsFilePath} (with path directive appended)`,
-          ]
-        : [];
+    const commandNotes: string[] = [];
+    if (!resumeSessionId) {
+      commandNotes.push(`Using stable Claude prompt bundle ${promptBundle.bundleKey}.`);
+    }
+    if (attemptInstructionsFilePath && !resumeSessionId) {
+      commandNotes.push(
+        `Injected agent instructions via --append-system-prompt-file ${instructionsFilePath} (with path directive appended)`,
+      );
+    }
     if (onMeta) {
       await onMeta({
         adapterType: "claude_local",
@@ -582,6 +576,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
       ? ({
         sessionId: resolvedSessionId,
         cwd,
+        promptBundleKey: promptBundle.bundleKey,
         ...(workspaceId ? { workspaceId } : {}),
         ...(workspaceRepoUrl ? { repoUrl: workspaceRepoUrl } : {}),
         ...(workspaceRepoRef ? { repoRef: workspaceRepoRef } : {}),
@@ -614,25 +609,21 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     };
   };
 
-  try {
-    const initial = await runAttempt(sessionId ?? null);
-    if (
-      sessionId &&
-      !initial.proc.timedOut &&
-      (initial.proc.exitCode ?? 0) !== 0 &&
-      initial.parsed &&
-      isClaudeUnknownSessionError(initial.parsed)
-    ) {
-      await onLog(
-        "stdout",
-        `[paperclip] Claude resume session "${sessionId}" is unavailable; retrying with a fresh session.\n`,
-      );
-      const retry = await runAttempt(null);
-      return toAdapterResult(retry, { fallbackSessionId: null, clearSessionOnMissingSession: true });
-    }
-
-    return toAdapterResult(initial, { fallbackSessionId: runtimeSessionId || runtime.sessionId });
-  } finally {
-    fs.rm(skillsDir, { recursive: true, force: true }).catch(() => {});
+  const initial = await runAttempt(sessionId ?? null);
+  if (
+    sessionId &&
+    !initial.proc.timedOut &&
+    (initial.proc.exitCode ?? 0) !== 0 &&
+    initial.parsed &&
+    isClaudeUnknownSessionError(initial.parsed)
+  ) {
+    await onLog(
+      "stdout",
+      `[paperclip] Claude resume session "${sessionId}" is unavailable; retrying with a fresh session.\n`,
+    );
+    const retry = await runAttempt(null);
+    return toAdapterResult(retry, { fallbackSessionId: null, clearSessionOnMissingSession: true });
   }
+
+  return toAdapterResult(initial, { fallbackSessionId: runtimeSessionId || runtime.sessionId });
 }

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

@@ -36,12 +36,16 @@ export const sessionCodec: AdapterSessionCodec = {
       readNonEmptyString(record.cwd) ??
       readNonEmptyString(record.workdir) ??
       readNonEmptyString(record.folder);
+    const promptBundleKey =
+      readNonEmptyString(record.promptBundleKey) ??
+      readNonEmptyString(record.prompt_bundle_key);
     const workspaceId = readNonEmptyString(record.workspaceId) ?? readNonEmptyString(record.workspace_id);
     const repoUrl = readNonEmptyString(record.repoUrl) ?? readNonEmptyString(record.repo_url);
     const repoRef = readNonEmptyString(record.repoRef) ?? readNonEmptyString(record.repo_ref);
     return {
       sessionId,
       ...(cwd ? { cwd } : {}),
+      ...(promptBundleKey ? { promptBundleKey } : {}),
       ...(workspaceId ? { workspaceId } : {}),
       ...(repoUrl ? { repoUrl } : {}),
       ...(repoRef ? { repoRef } : {}),
@@ -55,12 +59,16 @@ export const sessionCodec: AdapterSessionCodec = {
       readNonEmptyString(params.cwd) ??
       readNonEmptyString(params.workdir) ??
       readNonEmptyString(params.folder);
+    const promptBundleKey =
+      readNonEmptyString(params.promptBundleKey) ??
+      readNonEmptyString(params.prompt_bundle_key);
     const workspaceId = readNonEmptyString(params.workspaceId) ?? readNonEmptyString(params.workspace_id);
     const repoUrl = readNonEmptyString(params.repoUrl) ?? readNonEmptyString(params.repo_url);
     const repoRef = readNonEmptyString(params.repoRef) ?? readNonEmptyString(params.repo_ref);
     return {
       sessionId,
       ...(cwd ? { cwd } : {}),
+      ...(promptBundleKey ? { promptBundleKey } : {}),
       ...(workspaceId ? { workspaceId } : {}),
       ...(repoUrl ? { repoUrl } : {}),
       ...(repoRef ? { repoRef } : {}),

packages/adapters/claude-local/src/server/prompt-cache.ts

@@ -0,0 +1,172 @@
+import { constants as fsConstants } from "node:fs";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { createHash, type Hash } from "node:crypto";
+import type { AdapterExecutionContext } from "@paperclipai/adapter-utils";
+import { ensurePaperclipSkillSymlink, type PaperclipSkillEntry } from "@paperclipai/adapter-utils/server-utils";
+
+const DEFAULT_PAPERCLIP_INSTANCE_ID = "default";
+
+type SkillEntry = PaperclipSkillEntry;
+
+export interface ClaudePromptBundle {
+  bundleKey: string;
+  rootDir: string;
+  addDir: string;
+  instructionsFilePath: string | null;
+}
+
+function nonEmpty(value: string | undefined): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+function resolveManagedClaudePromptCacheRoot(
+  env: NodeJS.ProcessEnv,
+  companyId: string,
+): string {
+  const paperclipHome = nonEmpty(env.PAPERCLIP_HOME) ?? path.resolve(os.homedir(), ".paperclip");
+  const instanceId = nonEmpty(env.PAPERCLIP_INSTANCE_ID) ?? DEFAULT_PAPERCLIP_INSTANCE_ID;
+  return path.resolve(
+    paperclipHome,
+    "instances",
+    instanceId,
+    "companies",
+    companyId,
+    "claude-prompt-cache",
+  );
+}
+
+async function hashPathContents(
+  candidate: string,
+  hash: Hash,
+  relativePath: string,
+  seenDirectories: Set<string>,
+): Promise<void> {
+  const stat = await fs.lstat(candidate);
+
+  if (stat.isSymbolicLink()) {
+    hash.update(`symlink:${relativePath}\n`);
+    const resolved = await fs.realpath(candidate).catch(() => null);
+    if (!resolved) {
+      hash.update("missing\n");
+      return;
+    }
+    await hashPathContents(resolved, hash, relativePath, seenDirectories);
+    return;
+  }
+
+  if (stat.isDirectory()) {
+    const realDir = await fs.realpath(candidate).catch(() => candidate);
+    hash.update(`dir:${relativePath}\n`);
+    if (seenDirectories.has(realDir)) {
+      hash.update("loop\n");
+      return;
+    }
+    seenDirectories.add(realDir);
+    const entries = await fs.readdir(candidate, { withFileTypes: true });
+    entries.sort((left, right) => left.name.localeCompare(right.name));
+    for (const entry of entries) {
+      const childRelativePath = relativePath.length > 0 ? `${relativePath}/${entry.name}` : entry.name;
+      await hashPathContents(path.join(candidate, entry.name), hash, childRelativePath, seenDirectories);
+    }
+    return;
+  }
+
+  if (stat.isFile()) {
+    hash.update(`file:${relativePath}\n`);
+    hash.update(await fs.readFile(candidate));
+    hash.update("\n");
+    return;
+  }
+
+  hash.update(`other:${relativePath}:${stat.mode}\n`);
+}
+
+async function buildClaudePromptBundleKey(input: {
+  skills: SkillEntry[];
+  instructionsContents: string | null;
+}): Promise<string> {
+  const hash = createHash("sha256");
+  hash.update("paperclip-claude-prompt-bundle:v1\n");
+  if (input.instructionsContents) {
+    hash.update("instructions\n");
+    hash.update(input.instructionsContents);
+    hash.update("\n");
+  } else {
+    hash.update("instructions:none\n");
+  }
+
+  const sortedSkills = [...input.skills].sort((left, right) => left.runtimeName.localeCompare(right.runtimeName));
+  for (const entry of sortedSkills) {
+    hash.update(`skill:${entry.key}:${entry.runtimeName}\n`);
+    await hashPathContents(entry.source, hash, entry.runtimeName, new Set<string>());
+  }
+
+  return hash.digest("hex");
+}
+
+async function ensureReadableFile(targetPath: string, contents: string): Promise<void> {
+  try {
+    await fs.access(targetPath, fsConstants.R_OK);
+    return;
+  } catch {
+    // Fall through and materialize the file.
+  }
+
+  await fs.mkdir(path.dirname(targetPath), { recursive: true });
+  const tempPath = `${targetPath}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    await fs.writeFile(tempPath, contents, "utf8");
+    await fs.rename(tempPath, targetPath);
+  } catch (err) {
+    const targetReadable = await fs.access(targetPath, fsConstants.R_OK).then(() => true).catch(() => false);
+    if (!targetReadable) {
+      throw err;
+    }
+  } finally {
+    await fs.rm(tempPath, { force: true }).catch(() => {});
+  }
+}
+
+export async function prepareClaudePromptBundle(input: {
+  companyId: string;
+  skills: SkillEntry[];
+  instructionsContents: string | null;
+  onLog: AdapterExecutionContext["onLog"];
+}): Promise<ClaudePromptBundle> {
+  const { companyId, skills, instructionsContents, onLog } = input;
+  const bundleKey = await buildClaudePromptBundleKey({
+    skills,
+    instructionsContents,
+  });
+  const rootDir = path.join(resolveManagedClaudePromptCacheRoot(process.env, companyId), bundleKey);
+  const skillsHome = path.join(rootDir, ".claude", "skills");
+  await fs.mkdir(skillsHome, { recursive: true });
+
+  for (const entry of skills) {
+    const target = path.join(skillsHome, entry.runtimeName);
+    try {
+      await ensurePaperclipSkillSymlink(entry.source, target);
+    } catch (err) {
+      await onLog(
+        "stderr",
+        `[paperclip] Failed to materialize Claude skill "${entry.key}" into ${skillsHome}: ${err instanceof Error ? err.message : String(err)}\n`,
+      );
+    }
+  }
+
+  const instructionsFilePath = instructionsContents
+    ? path.join(rootDir, "agent-instructions.md")
+    : null;
+  if (instructionsFilePath && instructionsContents) {
+    await ensureReadableFile(instructionsFilePath, instructionsContents);
+  }
+
+  return {
+    bundleKey,
+    rootDir,
+    addDir: rootDir,
+    instructionsFilePath,
+  };
+}

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

@@ -47,7 +47,7 @@ async function buildClaudeSkillSnapshot(config: Record<string, unknown>): Promis
     sourcePath: entry.source,
     targetPath: null,
     detail: desiredSet.has(entry.key)
-      ? "Will be mounted into the ephemeral Claude skill directory on the next run."
+      ? "Will be materialized into the stable Paperclip-managed Claude prompt bundle on the next run."
       : null,
     required: Boolean(entry.required),
     requiredReason: entry.requiredReason ?? null,

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

@@ -2,6 +2,14 @@ export const type = "codex_local";
 export const label = "Codex (local)";
 export const DEFAULT_CODEX_LOCAL_MODEL = "gpt-5.3-codex";
 export const DEFAULT_CODEX_LOCAL_BYPASS_APPROVALS_AND_SANDBOX = true;
+export const CODEX_LOCAL_FAST_MODE_SUPPORTED_MODELS = ["gpt-5.4"] as const;
+
+export function isCodexLocalFastModeSupported(model: string | null | undefined): boolean {
+  const normalizedModel = typeof model === "string" ? model.trim() : "";
+  return CODEX_LOCAL_FAST_MODE_SUPPORTED_MODELS.includes(
+    normalizedModel as (typeof CODEX_LOCAL_FAST_MODE_SUPPORTED_MODELS)[number],
+  );
+}
 
 export const models = [
   { id: "gpt-5.4", label: "gpt-5.4" },
@@ -27,6 +35,7 @@ Core fields:
 - modelReasoningEffort (string, optional): reasoning effort override (minimal|low|medium|high|xhigh) passed via -c model_reasoning_effort=...
 - promptTemplate (string, optional): run prompt template
 - search (boolean, optional): run codex with --search
+- fastMode (boolean, optional): enable Codex Fast mode; currently supported on GPT-5.4 only and consumes credits faster
 - dangerouslyBypassApprovalsAndSandbox (boolean, optional): run with bypass flag
 - command (string, optional): defaults to "codex"
 - extraArgs (string[], optional): additional CLI args
@@ -45,5 +54,6 @@ Notes:
 - Paperclip injects desired local skills into the effective CODEX_HOME/skills/ directory at execution time so Codex can discover "$paperclip" and related skills without polluting the project working directory. In managed-home mode (the default) this is ~/.paperclip/instances/<id>/companies/<companyId>/codex-home/skills/; when CODEX_HOME is explicitly overridden in adapter config, that override is used instead.
 - Unless explicitly overridden in adapter config, Paperclip runs Codex with a per-company managed CODEX_HOME under the active Paperclip instance and seeds auth/config from the shared Codex home (the CODEX_HOME env var, when set, or ~/.codex).
 - Some model/tool combinations reject certain effort levels (for example minimal with web search enabled).
+- Fast mode is currently supported on GPT-5.4 only. When enabled, Paperclip applies \`service_tier="fast"\` and \`features.fast_mode=true\`.
 - 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/codex-args.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from "vitest";
+import { buildCodexExecArgs } from "./codex-args.js";
+
+describe("buildCodexExecArgs", () => {
+  it("enables Codex fast mode overrides for GPT-5.4", () => {
+    const result = buildCodexExecArgs({
+      model: "gpt-5.4",
+      search: true,
+      fastMode: true,
+    });
+
+    expect(result.fastModeRequested).toBe(true);
+    expect(result.fastModeApplied).toBe(true);
+    expect(result.fastModeIgnoredReason).toBeNull();
+    expect(result.args).toEqual([
+      "--search",
+      "exec",
+      "--json",
+      "--model",
+      "gpt-5.4",
+      "-c",
+      'service_tier="fast"',
+      "-c",
+      "features.fast_mode=true",
+      "-",
+    ]);
+  });
+
+  it("ignores fast mode for unsupported models", () => {
+    const result = buildCodexExecArgs({
+      model: "gpt-5.3-codex",
+      fastMode: true,
+    });
+
+    expect(result.fastModeRequested).toBe(true);
+    expect(result.fastModeApplied).toBe(false);
+    expect(result.fastModeIgnoredReason).toContain("currently only supported on gpt-5.4");
+    expect(result.args).toEqual([
+      "exec",
+      "--json",
+      "--model",
+      "gpt-5.3-codex",
+      "-",
+    ]);
+  });
+});

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

@@ -0,0 +1,74 @@
+import { asBoolean, asString, asStringArray } from "@paperclipai/adapter-utils/server-utils";
+import {
+  CODEX_LOCAL_FAST_MODE_SUPPORTED_MODELS,
+  isCodexLocalFastModeSupported,
+} from "../index.js";
+
+export type BuildCodexExecArgsResult = {
+  args: string[];
+  model: string;
+  fastModeRequested: boolean;
+  fastModeApplied: boolean;
+  fastModeIgnoredReason: string | null;
+};
+
+function readExtraArgs(config: unknown): string[] {
+  const fromExtraArgs = asStringArray(asRecord(config).extraArgs);
+  if (fromExtraArgs.length > 0) return fromExtraArgs;
+  return asStringArray(asRecord(config).args);
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function formatFastModeSupportedModels(): string {
+  return CODEX_LOCAL_FAST_MODE_SUPPORTED_MODELS.join(", ");
+}
+
+export function buildCodexExecArgs(
+  config: unknown,
+  options: { resumeSessionId?: string | null } = {},
+): BuildCodexExecArgsResult {
+  const record = asRecord(config);
+  const model = asString(record.model, "").trim();
+  const modelReasoningEffort = asString(
+    record.modelReasoningEffort,
+    asString(record.reasoningEffort, ""),
+  ).trim();
+  const search = asBoolean(record.search, false);
+  const fastModeRequested = asBoolean(record.fastMode, false);
+  const fastModeApplied = fastModeRequested && isCodexLocalFastModeSupported(model);
+  const bypass = asBoolean(
+    record.dangerouslyBypassApprovalsAndSandbox,
+    asBoolean(record.dangerouslyBypassSandbox, false),
+  );
+  const extraArgs = readExtraArgs(record);
+
+  const args = ["exec", "--json"];
+  if (search) args.unshift("--search");
+  if (bypass) args.push("--dangerously-bypass-approvals-and-sandbox");
+  if (model) args.push("--model", model);
+  if (modelReasoningEffort) {
+    args.push("-c", `model_reasoning_effort=${JSON.stringify(modelReasoningEffort)}`);
+  }
+  if (fastModeApplied) {
+    args.push("-c", 'service_tier="fast"', "-c", "features.fast_mode=true");
+  }
+  if (extraArgs.length > 0) args.push(...extraArgs);
+  if (options.resumeSessionId) args.push("resume", options.resumeSessionId, "-");
+  else args.push("-");
+
+  return {
+    args,
+    model,
+    fastModeRequested,
+    fastModeApplied,
+    fastModeIgnoredReason:
+      fastModeRequested && !fastModeApplied
+        ? `Configured fast mode is currently only supported on ${formatFastModeSupportedModels()}; Paperclip will ignore it for model ${model || "(default)"}.`
+        : null,
+  };
+}

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

@@ -5,8 +5,6 @@ import { inferOpenAiCompatibleBiller, type AdapterExecutionContext, type Adapter
 import {
   asString,
   asNumber,
-  asBoolean,
-  asStringArray,
   parseObject,
   buildPaperclipEnv,
   buildInvocationEnvForLogs,
@@ -26,6 +24,7 @@ import {
 import { parseCodexJsonl, isCodexUnknownSessionError } from "./parse.js";
 import { pathExists, prepareManagedCodexHome, resolveManagedCodexHomeDir, resolveSharedCodexHomeDir } from "./codex-home.js";
 import { resolveCodexDesiredSkillNames } from "./skills.js";
+import { buildCodexExecArgs } from "./codex-args.js";
 
 const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
 const CODEX_ROLLOUT_NOISE_RE =
@@ -223,15 +222,6 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   );
   const command = asString(config.command, "codex");
   const model = asString(config.model, "");
-  const modelReasoningEffort = asString(
-    config.modelReasoningEffort,
-    asString(config.reasoningEffort, ""),
-  );
-  const search = asBoolean(config.search, false);
-  const bypass = asBoolean(
-    config.dangerouslyBypassApprovalsAndSandbox,
-    asBoolean(config.dangerouslyBypassSandbox, false),
-  );
 
   const workspaceContext = parseObject(context.paperclipWorkspace);
   const workspaceCwd = asString(workspaceContext.cwd, "");
@@ -399,11 +389,6 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
 
   const timeoutSec = asNumber(config.timeoutSec, 0);
   const graceSec = asNumber(config.graceSec, 20);
-  const extraArgs = (() => {
-    const fromExtraArgs = asStringArray(config.extraArgs);
-    if (fromExtraArgs.length > 0) return fromExtraArgs;
-    return asStringArray(config.args);
-  })();
 
   const runtimeSessionParams = parseObject(runtime.sessionParams);
   const runtimeSessionId = asString(runtimeSessionParams.sessionId, runtime.sessionId ?? "");
@@ -499,26 +484,19 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     heartbeatPromptChars: renderedPrompt.length,
   };
 
-  const buildArgs = (resumeSessionId: string | null) => {
-    const args = ["exec", "--json"];
-    if (search) args.unshift("--search");
-    if (bypass) args.push("--dangerously-bypass-approvals-and-sandbox");
-    if (model) args.push("--model", model);
-    if (modelReasoningEffort) args.push("-c", `model_reasoning_effort=${JSON.stringify(modelReasoningEffort)}`);
-    if (extraArgs.length > 0) args.push(...extraArgs);
-    if (resumeSessionId) args.push("resume", resumeSessionId, "-");
-    else args.push("-");
-    return args;
-  };
-
   const runAttempt = async (resumeSessionId: string | null) => {
-    const args = buildArgs(resumeSessionId);
+    const execArgs = buildCodexExecArgs(config, { resumeSessionId });
+    const args = execArgs.args;
+    const commandNotesWithFastMode =
+      execArgs.fastModeIgnoredReason == null
+        ? commandNotes
+        : [...commandNotes, execArgs.fastModeIgnoredReason];
     if (onMeta) {
       await onMeta({
         adapterType: "codex_local",
         command: resolvedCommand,
         cwd,
-        commandNotes,
+        commandNotes: commandNotesWithFastMode,
         commandArgs: args.map((value, idx) => {
           if (idx === args.length - 1 && value !== "-") return `<prompt ${prompt.length} chars>`;
           return value;

packages/adapters/codex-local/src/server/parse.test.ts

@@ -27,6 +27,39 @@ describe("parseCodexJsonl", () => {
       errorMessage: "resume failed",
     });
   });
+
+  it("uses the last agent message as the summary when commentary updates precede the final answer", () => {
+    const stdout = [
+      JSON.stringify({ type: "thread.started", thread_id: "thread_123" }),
+      JSON.stringify({
+        type: "item.completed",
+        item: { type: "reasoning", text: "Checking the heartbeat procedure" },
+      }),
+      JSON.stringify({
+        type: "item.completed",
+        item: { type: "agent_message", text: "I’m checking out the issue and reading the docs now." },
+      }),
+      JSON.stringify({
+        type: "item.completed",
+        item: { type: "agent_message", text: "Fixed the issue and verified the targeted tests pass." },
+      }),
+      JSON.stringify({
+        type: "turn.completed",
+        usage: { input_tokens: 10, cached_input_tokens: 2, output_tokens: 4 },
+      }),
+    ].join("\n");
+
+    expect(parseCodexJsonl(stdout)).toEqual({
+      sessionId: "thread_123",
+      summary: "Fixed the issue and verified the targeted tests pass.",
+      usage: {
+        inputTokens: 10,
+        cachedInputTokens: 2,
+        outputTokens: 4,
+      },
+      errorMessage: null,
+    });
+  });
 });
 
 describe("isCodexUnknownSessionError", () => {

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

@@ -2,7 +2,7 @@ import { asString, asNumber, parseObject, parseJson } from "@paperclipai/adapter
 
 export function parseCodexJsonl(stdout: string) {
   let sessionId: string | null = null;
-  const messages: string[] = [];
+  let finalMessage: string | null = null;
   let errorMessage: string | null = null;
   const usage = {
     inputTokens: 0,
@@ -33,7 +33,7 @@ export function parseCodexJsonl(stdout: string) {
       const item = parseObject(event.item);
       if (asString(item.type, "") === "agent_message") {
         const text = asString(item.text, "");
-        if (text) messages.push(text);
+        if (text) finalMessage = text;
       }
       continue;
     }
@@ -55,7 +55,7 @@ export function parseCodexJsonl(stdout: string) {
 
   return {
     sessionId,
-    summary: messages.join("\n\n").trim(),
+    summary: finalMessage?.trim() ?? "",
     usage,
     errorMessage,
   };

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

@@ -5,8 +5,6 @@ import type {
 } from "@paperclipai/adapter-utils";
 import {
   asString,
-  asBoolean,
-  asStringArray,
   parseObject,
   ensureAbsoluteDirectory,
   ensureCommandResolvable,
@@ -16,6 +14,7 @@ import {
 import path from "node:path";
 import { parseCodexJsonl } from "./parse.js";
 import { codexHomeDir, readCodexAuthInfo } from "./quota.js";
+import { buildCodexExecArgs } from "./codex-args.js";
 
 function summarizeStatus(checks: AdapterEnvironmentCheck[]): AdapterEnvironmentTestResult["status"] {
   if (checks.some((check) => check.level === "error")) return "fail";
@@ -140,31 +139,16 @@ export async function testEnvironment(
         hint: "Use the `codex` CLI command to run the automatic login and installation probe.",
       });
     } else {
-      const model = asString(config.model, "").trim();
-      const modelReasoningEffort = asString(
-        config.modelReasoningEffort,
-        asString(config.reasoningEffort, ""),
-      ).trim();
-      const search = asBoolean(config.search, false);
-      const bypass = asBoolean(
-        config.dangerouslyBypassApprovalsAndSandbox,
-        asBoolean(config.dangerouslyBypassSandbox, false),
-      );
-      const extraArgs = (() => {
-        const fromExtraArgs = asStringArray(config.extraArgs);
-        if (fromExtraArgs.length > 0) return fromExtraArgs;
-        return asStringArray(config.args);
-      })();
-
-      const args = ["exec", "--json"];
-      if (search) args.unshift("--search");
-      if (bypass) args.push("--dangerously-bypass-approvals-and-sandbox");
-      if (model) args.push("--model", model);
-      if (modelReasoningEffort) {
-        args.push("-c", `model_reasoning_effort=${JSON.stringify(modelReasoningEffort)}`);
+      const execArgs = buildCodexExecArgs({ ...config, fastMode: false });
+      const args = execArgs.args;
+      if (execArgs.fastModeIgnoredReason) {
+        checks.push({
+          code: "codex_fast_mode_unsupported_model",
+          level: "warn",
+          message: execArgs.fastModeIgnoredReason,
+          hint: "Switch the agent model to GPT-5.4 to enable Codex Fast mode.",
+        });
       }
-      if (extraArgs.length > 0) args.push(...extraArgs);
-      args.push("-");
 
       const probe = await runChildProcess(
         `codex-envtest-${Date.now()}-${Math.random().toString(16).slice(2)}`,

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

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest";
+import { buildCodexLocalConfig } from "./build-config.js";
+import type { CreateConfigValues } from "@paperclipai/adapter-utils";
+
+function makeValues(overrides: Partial<CreateConfigValues> = {}): CreateConfigValues {
+  return {
+    adapterType: "codex_local",
+    cwd: "",
+    instructionsFilePath: "",
+    promptTemplate: "",
+    model: "gpt-5.4",
+    thinkingEffort: "",
+    chrome: false,
+    dangerouslySkipPermissions: true,
+    search: false,
+    fastMode: false,
+    dangerouslyBypassSandbox: true,
+    command: "",
+    args: "",
+    extraArgs: "",
+    envVars: "",
+    envBindings: {},
+    url: "",
+    bootstrapPrompt: "",
+    payloadTemplateJson: "",
+    workspaceStrategyType: "project_primary",
+    workspaceBaseRef: "",
+    workspaceBranchTemplate: "",
+    worktreeParentDir: "",
+    runtimeServicesJson: "",
+    maxTurnsPerRun: 1000,
+    heartbeatEnabled: false,
+    intervalSec: 300,
+    ...overrides,
+  };
+}
+
+describe("buildCodexLocalConfig", () => {
+  it("persists the fastMode toggle into adapter config", () => {
+    const config = buildCodexLocalConfig(
+      makeValues({
+        search: true,
+        fastMode: true,
+      }),
+    );
+
+    expect(config).toMatchObject({
+      model: "gpt-5.4",
+      search: true,
+      fastMode: true,
+      dangerouslyBypassApprovalsAndSandbox: true,
+    });
+  });
+});

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

@@ -85,6 +85,7 @@ export function buildCodexLocalConfig(v: CreateConfigValues): Record<string, unk
   }
   if (Object.keys(env).length > 0) ac.env = env;
   ac.search = v.search;
+  ac.fastMode = v.fastMode;
   ac.dangerouslyBypassApprovalsAndSandbox =
     typeof v.dangerouslyBypassSandbox === "boolean"
       ? v.dangerouslyBypassSandbox

packages/adapters/openclaw-gateway/doc/ONBOARDING_AND_TEST_PLAN.md

@@ -66,7 +66,7 @@ OPENCLAW_RESET_STATE=1 OPENCLAW_BUILD=1 ./scripts/smoke/openclaw-docker-ui.sh
 
 ### 1) Start Paperclip
 ```bash
-pnpm dev --tailscale-auth
+pnpm dev --bind lan
 curl -fsS http://127.0.0.1:3100/api/health
 ```
 

packages/db/src/backup-lib.test.ts

@@ -125,12 +125,12 @@ describeEmbeddedPostgres("runDatabaseBackup", () => {
         const result = await runDatabaseBackup({
           connectionString: sourceConnectionString,
           backupDir,
-          retentionDays: 7,
+          retention: { dailyDays: 7, weeklyWeeks: 4, monthlyMonths: 1 },
           filenamePrefix: "paperclip-test",
         });
 
-        expect(result.backupFile).toMatch(/paperclip-test-.*\.sql$/);
-        expect(result.sizeBytes).toBeGreaterThan(1024 * 1024);
+        expect(result.backupFile).toMatch(/paperclip-test-.*\.sql\.gz$/);
+        expect(result.sizeBytes).toBeGreaterThan(0);
         expect(fs.existsSync(result.backupFile)).toBe(true);
 
         await runDatabaseRestore({

packages/db/src/backup-lib.ts

@@ -1,12 +1,20 @@
 import { createReadStream, createWriteStream, existsSync, mkdirSync, readdirSync, statSync, unlinkSync } from "node:fs";
 import { basename, resolve } from "node:path";
 import { createInterface } from "node:readline";
+import { pipeline } from "node:stream/promises";
+import { createGunzip, createGzip } from "node:zlib";
 import postgres from "postgres";
 
+export type BackupRetentionPolicy = {
+  dailyDays: number;
+  weeklyWeeks: number;
+  monthlyMonths: number;
+};
+
 export type RunDatabaseBackupOptions = {
   connectionString: string;
   backupDir: string;
-  retentionDays: number;
+  retention: BackupRetentionPolicy;
   filenamePrefix?: string;
   connectTimeoutSeconds?: number;
   includeMigrationJournal?: boolean;
@@ -75,23 +83,91 @@ function timestamp(date: Date = new Date()): string {
   return `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}-${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`;
 }
 
-function pruneOldBackups(backupDir: string, retentionDays: number, filenamePrefix: string): number {
+/**
+ * ISO week key for grouping backups by calendar week (ISO 8601).
+ */
+function isoWeekKey(date: Date): string {
+  const d = new Date(Date.UTC(date.getFullYear(), date.getMonth(), date.getDate()));
+  d.setUTCDate(d.getUTCDate() + 4 - (d.getUTCDay() || 7));
+  const yearStart = new Date(Date.UTC(d.getUTCFullYear(), 0, 1));
+  const weekNo = Math.ceil(((d.getTime() - yearStart.getTime()) / 86400000 + 1) / 7);
+  return `${d.getUTCFullYear()}-W${String(weekNo).padStart(2, "0")}`;
+}
+
+function monthKey(date: Date): string {
+  return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}`;
+}
+
+/**
+ * Tiered backup pruning:
+ * - Daily tier: keep ALL backups from the last `dailyDays` days
+ * - Weekly tier: keep the NEWEST backup per calendar week for `weeklyWeeks` weeks
+ * - Monthly tier: keep the NEWEST backup per calendar month for `monthlyMonths` months
+ * - Everything else is deleted
+ */
+function pruneOldBackups(backupDir: string, retention: BackupRetentionPolicy, filenamePrefix: string): number {
   if (!existsSync(backupDir)) return 0;
-  const safeRetention = Math.max(1, Math.trunc(retentionDays));
-  const cutoff = Date.now() - safeRetention * 24 * 60 * 60 * 1000;
-  let pruned = 0;
+
+  const now = Date.now();
+  const dailyCutoff = now - Math.max(1, retention.dailyDays) * 24 * 60 * 60 * 1000;
+  const weeklyCutoff = now - Math.max(1, retention.weeklyWeeks) * 7 * 24 * 60 * 60 * 1000;
+  const monthlyCutoff = now - Math.max(1, retention.monthlyMonths) * 30 * 24 * 60 * 60 * 1000;
+
+  type BackupEntry = { name: string; fullPath: string; mtimeMs: number };
+  const entries: BackupEntry[] = [];
 
   for (const name of readdirSync(backupDir)) {
-    if (!name.startsWith(`${filenamePrefix}-`) || !name.endsWith(".sql")) continue;
+    if (!name.startsWith(`${filenamePrefix}-`)) continue;
+    if (!name.endsWith(".sql") && !name.endsWith(".sql.gz")) continue;
     const fullPath = resolve(backupDir, name);
     const stat = statSync(fullPath);
-    if (stat.mtimeMs < cutoff) {
-      unlinkSync(fullPath);
-      pruned++;
-    }
+    entries.push({ name, fullPath, mtimeMs: stat.mtimeMs });
   }
 
-  return pruned;
+  // Sort newest first so the first entry per week/month bucket is the one we keep
+  entries.sort((a, b) => b.mtimeMs - a.mtimeMs);
+
+  const keepWeekBuckets = new Set<string>();
+  const keepMonthBuckets = new Set<string>();
+  const toDelete: string[] = [];
+
+  for (const entry of entries) {
+    // Daily tier — keep everything within dailyDays
+    if (entry.mtimeMs >= dailyCutoff) continue;
+
+    const date = new Date(entry.mtimeMs);
+    const week = isoWeekKey(date);
+    const month = monthKey(date);
+
+    // Weekly tier — keep newest per calendar week
+    if (entry.mtimeMs >= weeklyCutoff) {
+      if (keepWeekBuckets.has(week)) {
+        toDelete.push(entry.fullPath);
+      } else {
+        keepWeekBuckets.add(week);
+      }
+      continue;
+    }
+
+    // Monthly tier — keep newest per calendar month
+    if (entry.mtimeMs >= monthlyCutoff) {
+      if (keepMonthBuckets.has(month)) {
+        toDelete.push(entry.fullPath);
+      } else {
+        keepMonthBuckets.add(month);
+      }
+      continue;
+    }
+
+    // Beyond all retention tiers — delete
+    toDelete.push(entry.fullPath);
+  }
+
+  for (const filePath of toDelete) {
+    unlinkSync(filePath);
+  }
+
+  return toDelete.length;
 }
 
 function formatBackupSize(sizeBytes: number): string {
@@ -148,7 +224,9 @@ function tableKey(schemaName: string, tableName: string): string {
 }
 
 async function* readRestoreStatements(backupFile: string): AsyncGenerator<string> {
-  const stream = createReadStream(backupFile, { encoding: "utf8" });
+  const raw = createReadStream(backupFile);
+  const stream = backupFile.endsWith(".gz") ? raw.pipe(createGunzip()) : raw;
+  stream.setEncoding("utf8");
   const reader = createInterface({
     input: stream,
     crlfDelay: Infinity,
@@ -180,6 +258,7 @@ async function* readRestoreStatements(backupFile: string): AsyncGenerator<string
   } finally {
     reader.close();
     stream.destroy();
+    raw.destroy();
   }
 }
 
@@ -281,15 +360,16 @@ export function createBufferedTextFileWriter(filePath: string, maxBufferedBytes
 
 export async function runDatabaseBackup(opts: RunDatabaseBackupOptions): Promise<RunDatabaseBackupResult> {
   const filenamePrefix = opts.filenamePrefix ?? "paperclip";
-  const retentionDays = Math.max(1, Math.trunc(opts.retentionDays));
+  const retention = opts.retention;
   const connectTimeout = Math.max(1, Math.trunc(opts.connectTimeoutSeconds ?? 5));
   const includeMigrationJournal = opts.includeMigrationJournal === true;
   const excludedTableNames = normalizeTableNameSet(opts.excludeTables);
   const nullifiedColumnsByTable = normalizeNullifyColumnMap(opts.nullifyColumns);
   const sql = postgres(opts.connectionString, { max: 1, connect_timeout: connectTimeout });
   mkdirSync(opts.backupDir, { recursive: true });
-  const backupFile = resolve(opts.backupDir, `${filenamePrefix}-${timestamp()}.sql`);
-  const writer = createBufferedTextFileWriter(backupFile);
+  const sqlFile = resolve(opts.backupDir, `${filenamePrefix}-${timestamp()}.sql`);
+  const backupFile = `${sqlFile}.gz`;
+  const writer = createBufferedTextFileWriter(sqlFile);
 
   try {
     await sql`SELECT 1`;
@@ -664,8 +744,14 @@ export async function runDatabaseBackup(opts: RunDatabaseBackupOptions): Promise
 
     await writer.close();
 
+    // Compress the SQL file with gzip
+    const sqlReadStream = createReadStream(sqlFile);
+    const gzWriteStream = createWriteStream(backupFile);
+    await pipeline(sqlReadStream, createGzip(), gzWriteStream);
+    unlinkSync(sqlFile);
+
     const sizeBytes = statSync(backupFile).size;
-    const prunedCount = pruneOldBackups(opts.backupDir, retentionDays, filenamePrefix);
+    const prunedCount = pruneOldBackups(opts.backupDir, retention, filenamePrefix);
 
     return {
       backupFile,
@@ -674,6 +760,12 @@ export async function runDatabaseBackup(opts: RunDatabaseBackupOptions): Promise
     };
   } catch (error) {
     await writer.abort();
+    if (existsSync(backupFile)) {
+      try { unlinkSync(backupFile); } catch { /* ignore */ }
+    }
+    if (existsSync(sqlFile)) {
+      try { unlinkSync(sqlFile); } catch { /* ignore */ }
+    }
     throw error;
   } finally {
     await sql.end();

packages/db/src/backup.ts

@@ -85,7 +85,7 @@ function resolveBackupDir(config: PartialConfig | null): string {
 }
 
 function resolveRetentionDays(config: PartialConfig | null): number {
-  return asPositiveInt(config?.database?.backup?.retentionDays) ?? 30;
+  return asPositiveInt(config?.database?.backup?.retentionDays) ?? 7;
 }
 
 async function main() {
@@ -103,7 +103,7 @@ async function main() {
     const result = await runDatabaseBackup({
       connectionString,
       backupDir,
-      retentionDays,
+      retention: { dailyDays: retentionDays, weeklyWeeks: 4, monthlyMonths: 1 },
       filenamePrefix: "paperclip",
     });
 

packages/db/src/index.ts

@@ -21,6 +21,7 @@ export {
   runDatabaseBackup,
   runDatabaseRestore,
   formatDatabaseBackupResult,
+  type BackupRetentionPolicy,
   type RunDatabaseBackupOptions,
   type RunDatabaseBackupResult,
   type RunDatabaseRestoreOptions,

packages/db/src/migrations/0055_kind_weapon_omega.sql

@@ -0,0 +1 @@
+ALTER TABLE "heartbeat_runs" ADD COLUMN "process_group_id" integer;--> statement-breakpoint

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

@@ -386,6 +386,13 @@
       "when": 1775750400000,
       "tag": "0054_draft_routines",
       "breakpoints": true
+    },
+    {
+      "idx": 55,
+      "version": "7",
+      "when": 1775825256196,
+      "tag": "0055_kind_weapon_omega",
+      "breakpoints": true
     }
   ]
-}
+}

packages/db/src/schema/heartbeat_runs.ts

@@ -32,6 +32,7 @@ export const heartbeatRuns = pgTable(
     errorCode: text("error_code"),
     externalRunId: text("external_run_id"),
     processPid: integer("process_pid"),
+    processGroupId: integer("process_group_id"),
     processStartedAt: timestamp("process_started_at", { withTimezone: true }),
     retryOfRunId: uuid("retry_of_run_id").references((): AnyPgColumn => heartbeatRuns.id, {
       onDelete: "set null",

packages/shared/src/config-schema.ts

@@ -1,11 +1,13 @@
 import { z } from "zod";
 import {
   AUTH_BASE_URL_MODES,
+  BIND_MODES,
   DEPLOYMENT_EXPOSURES,
   DEPLOYMENT_MODES,
   SECRET_PROVIDERS,
   STORAGE_PROVIDERS,
 } from "./constants.js";
+import { validateConfiguredBindMode } from "./network-bind.js";
 
 export const configMetaSchema = z.object({
   version: z.literal(1),
@@ -21,7 +23,7 @@ export const llmConfigSchema = z.object({
 export const databaseBackupConfigSchema = z.object({
   enabled: z.boolean().default(true),
   intervalMinutes: z.number().int().min(1).max(7 * 24 * 60).default(60),
-  retentionDays: z.number().int().min(1).max(3650).default(30),
+  retentionDays: z.number().int().min(1).max(3650).default(7),
   dir: z.string().default("~/.paperclip/instances/default/data/backups"),
 });
 
@@ -33,7 +35,7 @@ export const databaseConfigSchema = z.object({
   backup: databaseBackupConfigSchema.default({
     enabled: true,
     intervalMinutes: 60,
-    retentionDays: 30,
+    retentionDays: 7,
     dir: "~/.paperclip/instances/default/data/backups",
   }),
 });
@@ -46,6 +48,8 @@ export const loggingConfigSchema = z.object({
 export const serverConfigSchema = z.object({
   deploymentMode: z.enum(DEPLOYMENT_MODES).default("local_trusted"),
   exposure: z.enum(DEPLOYMENT_EXPOSURES).default("private"),
+  bind: z.enum(BIND_MODES).optional(),
+  customBindHost: z.string().optional(),
   host: z.string().default("127.0.0.1"),
   port: z.number().int().min(1).max(65535).default(3100),
   allowedHostnames: z.array(z.string().min(1)).default([]),
@@ -132,15 +136,26 @@ export const paperclipConfigSchema = z
     }),
   })
   .superRefine((value, ctx) => {
-    if (value.server.deploymentMode === "local_trusted") {
-      if (value.server.exposure !== "private") {
-        ctx.addIssue({
-          code: z.ZodIssueCode.custom,
-          message: "server.exposure must be private when deploymentMode is local_trusted",
-          path: ["server", "exposure"],
-        });
-      }
-      return;
+    if (value.server.deploymentMode === "local_trusted" && value.server.exposure !== "private") {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "server.exposure must be private when deploymentMode is local_trusted",
+        path: ["server", "exposure"],
+      });
+    }
+
+    for (const message of validateConfiguredBindMode({
+      deploymentMode: value.server.deploymentMode,
+      deploymentExposure: value.server.exposure,
+      bind: value.server.bind,
+      host: value.server.host,
+      customBindHost: value.server.customBindHost,
+    })) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message,
+        path: message.includes("customBindHost") ? ["server", "customBindHost"] : ["server", "bind"],
+      });
     }
 
     if (value.auth.baseUrlMode === "explicit" && !value.auth.publicBaseUrl) {

packages/shared/src/constants.ts

@@ -7,6 +7,9 @@ export type DeploymentMode = (typeof DEPLOYMENT_MODES)[number];
 export const DEPLOYMENT_EXPOSURES = ["private", "public"] as const;
 export type DeploymentExposure = (typeof DEPLOYMENT_EXPOSURES)[number];
 
+export const BIND_MODES = ["loopback", "lan", "tailnet", "custom"] as const;
+export type BindMode = (typeof BIND_MODES)[number];
+
 export const AUTH_BASE_URL_MODES = ["auto", "explicit"] as const;
 export type AuthBaseUrlMode = (typeof AUTH_BASE_URL_MODES)[number];
 

packages/shared/src/index.ts

@@ -3,6 +3,7 @@ export {
   COMPANY_STATUSES,
   DEPLOYMENT_MODES,
   DEPLOYMENT_EXPOSURES,
+  BIND_MODES,
   AUTH_BASE_URL_MODES,
   AGENT_STATUSES,
   AGENT_ADAPTER_TYPES,
@@ -82,6 +83,7 @@ export {
   type CompanyStatus,
   type DeploymentMode,
   type DeploymentExposure,
+  type BindMode,
   type AuthBaseUrlMode,
   type AgentStatus,
   type AgentAdapterType,
@@ -154,6 +156,16 @@ export {
   type PluginBridgeErrorCode,
 } from "./constants.js";
 
+export {
+  ALL_INTERFACES_BIND_HOST,
+  LOOPBACK_BIND_HOST,
+  inferBindModeFromHost,
+  isAllInterfacesHost,
+  isLoopbackHost,
+  resolveRuntimeBind,
+  validateConfiguredBindMode,
+} from "./network-bind.js";
+
 export type {
   Company,
   FeedbackVote,
@@ -194,6 +206,7 @@ export type {
   InstanceExperimentalSettings,
   InstanceGeneralSettings,
   InstanceSettings,
+  BackupRetentionPolicy,
   Agent,
   AgentAccessState,
   AgentChainOfCommandEntry,
@@ -384,6 +397,13 @@ export {
   DEFAULT_FEEDBACK_DATA_SHARING_TERMS_VERSION,
 } from "./types/feedback.js";
 
+export {
+  DAILY_RETENTION_PRESETS,
+  WEEKLY_RETENTION_PRESETS,
+  MONTHLY_RETENTION_PRESETS,
+  DEFAULT_BACKUP_RETENTION,
+} from "./types/instance.js";
+
 export {
   getClosedIsolatedExecutionWorkspaceMessage,
   isClosedIsolatedExecutionWorkspace,

packages/shared/src/network-bind.ts

@@ -0,0 +1,105 @@
+import type { BindMode, DeploymentExposure, DeploymentMode } from "./constants.js";
+
+export const LOOPBACK_BIND_HOST = "127.0.0.1";
+export const ALL_INTERFACES_BIND_HOST = "0.0.0.0";
+
+function normalizeHost(host: string | null | undefined): string | undefined {
+  const trimmed = host?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+export function isLoopbackHost(host: string | null | undefined): boolean {
+  const normalized = normalizeHost(host)?.toLowerCase();
+  return normalized === "127.0.0.1" || normalized === "localhost" || normalized === "::1";
+}
+
+export function isAllInterfacesHost(host: string | null | undefined): boolean {
+  const normalized = normalizeHost(host)?.toLowerCase();
+  return normalized === "0.0.0.0" || normalized === "::";
+}
+
+export function inferBindModeFromHost(
+  host: string | null | undefined,
+  opts?: { tailnetBindHost?: string | null | undefined },
+): BindMode {
+  const normalized = normalizeHost(host);
+  const tailnetBindHost = normalizeHost(opts?.tailnetBindHost);
+
+  if (!normalized || isLoopbackHost(normalized)) return "loopback";
+  if (isAllInterfacesHost(normalized)) return "lan";
+  if (tailnetBindHost && normalized === tailnetBindHost) return "tailnet";
+  return "custom";
+}
+
+export function validateConfiguredBindMode(input: {
+  deploymentMode: DeploymentMode;
+  deploymentExposure: DeploymentExposure;
+  bind?: BindMode | null | undefined;
+  host?: string | null | undefined;
+  customBindHost?: string | null | undefined;
+}): string[] {
+  const bind = input.bind ?? inferBindModeFromHost(input.host);
+  const customBindHost = normalizeHost(input.customBindHost);
+  const errors: string[] = [];
+
+  if (input.deploymentMode === "local_trusted" && bind !== "loopback") {
+    errors.push("local_trusted requires server.bind=loopback");
+  }
+
+  if (bind === "custom" && !customBindHost) {
+    const legacyHost = normalizeHost(input.host);
+    if (!legacyHost || isLoopbackHost(legacyHost) || isAllInterfacesHost(legacyHost)) {
+      errors.push("server.customBindHost is required when server.bind=custom");
+    }
+  }
+
+  if (input.deploymentMode === "authenticated" && input.deploymentExposure === "public" && bind === "tailnet") {
+    errors.push("server.bind=tailnet is only supported for authenticated/private deployments");
+  }
+
+  return errors;
+}
+
+export function resolveRuntimeBind(input: {
+  bind?: BindMode | null | undefined;
+  host?: string | null | undefined;
+  customBindHost?: string | null | undefined;
+  tailnetBindHost?: string | null | undefined;
+}): {
+  bind: BindMode;
+  host: string;
+  customBindHost?: string;
+  errors: string[];
+} {
+  const bind = input.bind ?? inferBindModeFromHost(input.host, { tailnetBindHost: input.tailnetBindHost });
+  const legacyHost = normalizeHost(input.host);
+  const customBindHost =
+    normalizeHost(input.customBindHost) ??
+    (bind === "custom" && legacyHost && !isLoopbackHost(legacyHost) && !isAllInterfacesHost(legacyHost)
+      ? legacyHost
+      : undefined);
+
+  switch (bind) {
+    case "loopback":
+      return { bind, host: LOOPBACK_BIND_HOST, customBindHost, errors: [] };
+    case "lan":
+      return { bind, host: ALL_INTERFACES_BIND_HOST, customBindHost, errors: [] };
+    case "custom":
+      return customBindHost
+        ? { bind, host: customBindHost, customBindHost, errors: [] }
+        : { bind, host: legacyHost ?? LOOPBACK_BIND_HOST, errors: ["server.customBindHost is required when server.bind=custom"] };
+    case "tailnet": {
+      const tailnetBindHost = normalizeHost(input.tailnetBindHost);
+      return tailnetBindHost
+        ? { bind, host: tailnetBindHost, customBindHost, errors: [] }
+        : {
+          bind,
+          host: legacyHost ?? LOOPBACK_BIND_HOST,
+          customBindHost,
+          errors: [
+            "server.bind=tailnet requires a detected Tailscale address or PAPERCLIP_TAILNET_BIND_HOST",
+          ],
+        };
+    }
+  }
+}

packages/shared/src/telemetry/client.ts

@@ -6,7 +6,10 @@ import type {
   TelemetryState,
 } from "./types.js";
 
-const DEFAULT_ENDPOINT = "https://telemetry.paperclip.ing/ingest";
+const DEFAULT_ENDPOINTS = [
+  "https://telemetry.paperclip.ing/ingest",
+  "https://rusqrrg391.execute-api.us-east-1.amazonaws.com/ingest",
+] as const;
 const BATCH_SIZE = 50;
 const SEND_TIMEOUT_MS = 5_000;
 
@@ -44,29 +47,35 @@ export class TelemetryClient {
 
     const events = this.queue.splice(0);
     const state = this.getState();
-    const endpoint = this.config.endpoint ?? DEFAULT_ENDPOINT;
+    const endpoints = this.resolveEndpoints();
     const app = this.config.app ?? "paperclip";
     const schemaVersion = this.config.schemaVersion ?? "1";
+    const body = JSON.stringify({
+      app,
+      schemaVersion,
+      installId: state.installId,
+      version: this.version,
+      events,
+    });
 
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), SEND_TIMEOUT_MS);
-    try {
-      await fetch(endpoint, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-          app,
-          schemaVersion,
-          installId: state.installId,
-          version: this.version,
-          events,
-        }),
-        signal: controller.signal,
-      });
-    } catch {
-      // Fire-and-forget: silent failure, no retries
-    } finally {
-      clearTimeout(timer);
+    for (const endpoint of endpoints) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), SEND_TIMEOUT_MS);
+      try {
+        const response = await fetch(endpoint, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body,
+          signal: controller.signal,
+        });
+        if (response.ok) {
+          return;
+        }
+      } catch {
+        // Try the next built-in endpoint before dropping the batch.
+      } finally {
+        clearTimeout(timer);
+      }
     }
   }
 
@@ -102,4 +111,9 @@ export class TelemetryClient {
     }
     return this.state;
   }
+
+  private resolveEndpoints(): readonly string[] {
+    const configured = this.config.endpoint?.trim();
+    return configured ? [configured] : DEFAULT_ENDPOINTS;
+  }
 }

packages/shared/src/types/heartbeat.ts

@@ -34,6 +34,7 @@ export interface HeartbeatRun {
   errorCode: string | null;
   externalRunId: string | null;
   processPid: number | null;
+  processGroupId?: number | null;
   processStartedAt: Date | null;
   retryOfRunId: string | null;
   processLossRetryCount: number;

packages/shared/src/types/index.ts

@@ -11,7 +11,8 @@ export type {
   FeedbackTraceBundleFile,
   FeedbackTraceBundle,
 } from "./feedback.js";
-export type { InstanceExperimentalSettings, InstanceGeneralSettings, InstanceSettings } from "./instance.js";
+export type { InstanceExperimentalSettings, InstanceGeneralSettings, InstanceSettings, BackupRetentionPolicy } from "./instance.js";
+export { DAILY_RETENTION_PRESETS, WEEKLY_RETENTION_PRESETS, MONTHLY_RETENTION_PRESETS, DEFAULT_BACKUP_RETENTION } from "./instance.js";
 export type {
   CompanySkillSourceType,
   CompanySkillTrustLevel,

packages/shared/src/types/instance.ts

@@ -1,9 +1,26 @@
 import type { FeedbackDataSharingPreference } from "./feedback.js";
 
+export const DAILY_RETENTION_PRESETS = [3, 7, 14] as const;
+export const WEEKLY_RETENTION_PRESETS = [1, 2, 4] as const;
+export const MONTHLY_RETENTION_PRESETS = [1, 3, 6] as const;
+
+export interface BackupRetentionPolicy {
+  dailyDays: (typeof DAILY_RETENTION_PRESETS)[number];
+  weeklyWeeks: (typeof WEEKLY_RETENTION_PRESETS)[number];
+  monthlyMonths: (typeof MONTHLY_RETENTION_PRESETS)[number];
+}
+
+export const DEFAULT_BACKUP_RETENTION: BackupRetentionPolicy = {
+  dailyDays: 7,
+  weeklyWeeks: 4,
+  monthlyMonths: 1,
+};
+
 export interface InstanceGeneralSettings {
   censorUsernameInLogs: boolean;
   keyboardShortcuts: boolean;
   feedbackDataSharingPreference: FeedbackDataSharingPreference;
+  backupRetention: BackupRetentionPolicy;
 }
 
 export interface InstanceExperimentalSettings {

packages/shared/src/validators/instance.ts

@@ -1,13 +1,33 @@
 import { z } from "zod";
 import { DEFAULT_FEEDBACK_DATA_SHARING_PREFERENCE } from "../types/feedback.js";
+import {
+  DAILY_RETENTION_PRESETS,
+  WEEKLY_RETENTION_PRESETS,
+  MONTHLY_RETENTION_PRESETS,
+  DEFAULT_BACKUP_RETENTION,
+} from "../types/instance.js";
 import { feedbackDataSharingPreferenceSchema } from "./feedback.js";
 
+function presetSchema<T extends readonly number[]>(presets: T, label: string) {
+  return z.number().refine(
+    (v): v is T[number] => (presets as readonly number[]).includes(v),
+    { message: `${label} must be one of: ${presets.join(", ")}` },
+  );
+}
+
+export const backupRetentionPolicySchema = z.object({
+  dailyDays: presetSchema(DAILY_RETENTION_PRESETS, "dailyDays").default(DEFAULT_BACKUP_RETENTION.dailyDays),
+  weeklyWeeks: presetSchema(WEEKLY_RETENTION_PRESETS, "weeklyWeeks").default(DEFAULT_BACKUP_RETENTION.weeklyWeeks),
+  monthlyMonths: presetSchema(MONTHLY_RETENTION_PRESETS, "monthlyMonths").default(DEFAULT_BACKUP_RETENTION.monthlyMonths),
+});
+
 export const instanceGeneralSettingsSchema = z.object({
   censorUsernameInLogs: z.boolean().default(false),
   keyboardShortcuts: z.boolean().default(false),
   feedbackDataSharingPreference: feedbackDataSharingPreferenceSchema.default(
     DEFAULT_FEEDBACK_DATA_SHARING_PREFERENCE,
   ),
+  backupRetention: backupRetentionPolicySchema.default(DEFAULT_BACKUP_RETENTION),
 }).strict();
 
 export const patchInstanceGeneralSettingsSchema = instanceGeneralSettingsSchema.partial();

scripts/dev-runner.ts

@@ -6,6 +6,7 @@ import { createInterface } from "node:readline/promises";
 import { stdin, stdout } from "node:process";
 import { shouldTrackDevServerPath } from "./dev-runner-paths.mjs";
 import { createDevServiceIdentity, repoRoot } from "./dev-service-profile.ts";
+import { bootstrapDevRunnerWorktreeEnv } from "../server/src/dev-runner-worktree.ts";
 import {
   findAdoptableLocalService,
   removeLocalServiceRegistryRecord,
@@ -13,6 +14,19 @@ import {
   writeLocalServiceRegistryRecord,
 } from "../server/src/services/local-service-supervisor.ts";
 
+// Keep these values local so the dev runner can boot from the server package's
+// tsx context without requiring workspace package resolution first.
+const BIND_MODES = ["loopback", "lan", "tailnet", "custom"] as const;
+type BindMode = (typeof BIND_MODES)[number];
+
+const worktreeEnvBootstrap = bootstrapDevRunnerWorktreeEnv(repoRoot, process.env);
+if (worktreeEnvBootstrap.missingEnv) {
+  console.error(
+    `[paperclip] linked git worktree at ${repoRoot} is missing ${path.relative(repoRoot, worktreeEnvBootstrap.envPath)}. Run \`paperclipai worktree init\` in this worktree before \`pnpm dev\`.`,
+  );
+  process.exit(1);
+}
+
 const mode = process.argv[2] === "watch" ? "watch" : "dev";
 const cliArgs = process.argv.slice(3);
 const scanIntervalMs = 1500;
@@ -61,13 +75,36 @@ const tailscaleAuthFlagNames = new Set([
 ]);
 
 let tailscaleAuth = false;
+let bindMode: BindMode | null = null;
+let bindHost: string | null = null;
 const forwardedArgs: string[] = [];
 
-for (const arg of cliArgs) {
+for (let index = 0; index < cliArgs.length; index += 1) {
+  const arg = cliArgs[index];
   if (tailscaleAuthFlagNames.has(arg)) {
     tailscaleAuth = true;
     continue;
   }
+  if (arg === "--bind") {
+    const value = cliArgs[index + 1];
+    if (!value || value.startsWith("--") || !BIND_MODES.includes(value as BindMode)) {
+      console.error(`[paperclip] invalid --bind value. Use one of: ${BIND_MODES.join(", ")}`);
+      process.exit(1);
+    }
+    bindMode = value as BindMode;
+    index += 1;
+    continue;
+  }
+  if (arg === "--bind-host") {
+    const value = cliArgs[index + 1];
+    if (!value || value.startsWith("--")) {
+      console.error("[paperclip] --bind-host requires a value");
+      process.exit(1);
+    }
+    bindHost = value;
+    index += 1;
+    continue;
+  }
   forwardedArgs.push(arg);
 }
 
@@ -77,6 +114,16 @@ if (process.env.npm_config_tailscale_auth === "true") {
 if (process.env.npm_config_authenticated_private === "true") {
   tailscaleAuth = true;
 }
+if (!bindMode && process.env.npm_config_bind && BIND_MODES.includes(process.env.npm_config_bind as BindMode)) {
+  bindMode = process.env.npm_config_bind as BindMode;
+}
+if (!bindHost && process.env.npm_config_bind_host) {
+  bindHost = process.env.npm_config_bind_host;
+}
+if (bindMode === "custom" && !bindHost) {
+  console.error("[paperclip] --bind custom requires --bind-host <host>");
+  process.exit(1);
+}
 
 const env: NodeJS.ProcessEnv = {
   ...process.env,
@@ -93,13 +140,36 @@ if (mode === "watch") {
   env.PAPERCLIP_MIGRATION_AUTO_APPLY ??= "true";
 }
 
-if (tailscaleAuth) {
-  env.PAPERCLIP_DEPLOYMENT_MODE = "authenticated";
-  env.PAPERCLIP_DEPLOYMENT_EXPOSURE = "private";
-  env.PAPERCLIP_AUTH_BASE_URL_MODE = "auto";
-  env.HOST = "0.0.0.0";
-  console.log("[paperclip] dev mode: authenticated/private (tailscale-friendly) on 0.0.0.0");
+if (tailscaleAuth || bindMode) {
+  const effectiveBind = bindMode ?? "lan";
+  if (tailscaleAuth) {
+    console.log("[paperclip] note: --tailscale-auth/--authenticated-private are legacy aliases for --bind lan");
+  }
+  env.PAPERCLIP_BIND = effectiveBind;
+  if (bindHost) {
+    env.PAPERCLIP_BIND_HOST = bindHost;
+  } else {
+    delete env.PAPERCLIP_BIND_HOST;
+  }
+  if (effectiveBind === "loopback" && !tailscaleAuth) {
+    delete env.PAPERCLIP_DEPLOYMENT_MODE;
+    delete env.PAPERCLIP_DEPLOYMENT_EXPOSURE;
+    delete env.PAPERCLIP_AUTH_BASE_URL_MODE;
+    console.log("[paperclip] dev mode: local_trusted (bind=loopback)");
+  } else {
+    env.PAPERCLIP_DEPLOYMENT_MODE = "authenticated";
+    env.PAPERCLIP_DEPLOYMENT_EXPOSURE = "private";
+    env.PAPERCLIP_AUTH_BASE_URL_MODE = "auto";
+    console.log(
+      `[paperclip] dev mode: authenticated/private (bind=${effectiveBind}${bindHost ? `:${bindHost}` : ""})`,
+    );
+  }
 } else {
+  delete env.PAPERCLIP_BIND;
+  delete env.PAPERCLIP_BIND_HOST;
+  delete env.PAPERCLIP_DEPLOYMENT_MODE;
+  delete env.PAPERCLIP_DEPLOYMENT_EXPOSURE;
+  delete env.PAPERCLIP_AUTH_BASE_URL_MODE;
   console.log("[paperclip] dev mode: local_trusted (default)");
 }
 
@@ -107,7 +177,7 @@ const serverPort = Number.parseInt(env.PORT ?? process.env.PORT ?? "3100", 10) |
 const devService = createDevServiceIdentity({
   mode,
   forwardedArgs,
-  tailscaleAuth,
+  networkProfile: tailscaleAuth ? `legacy:${bindMode ?? "lan"}` : (bindMode ?? "default"),
   port: serverPort,
 });
 

scripts/dev-service-profile.ts

@@ -8,7 +8,7 @@ export const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)
 export function createDevServiceIdentity(input: {
   mode: "watch" | "dev";
   forwardedArgs: string[];
-  tailscaleAuth: boolean;
+  networkProfile: string;
   port: number;
 }) {
   const envFingerprint = createHash("sha256")
@@ -16,7 +16,7 @@ export function createDevServiceIdentity(input: {
       JSON.stringify({
         mode: input.mode,
         forwardedArgs: input.forwardedArgs,
-        tailscaleAuth: input.tailscaleAuth,
+        networkProfile: input.networkProfile,
         port: input.port,
       }),
     )

scripts/ensure-workspace-package-links.ts

@@ -1,10 +1,11 @@
 #!/usr/bin/env -S node --import tsx
-import { spawn } from "node:child_process";
-import { existsSync, readFileSync, realpathSync } from "node:fs";
+import fs from "node:fs/promises";
+import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync } from "node:fs";
 import path from "node:path";
 import { repoRoot } from "./dev-service-profile.ts";
 
 type WorkspaceLinkMismatch = {
+  workspaceDir: string;
   packageName: string;
   expectedPath: string;
   actualPath: string | null;
@@ -14,44 +15,77 @@ function readJsonFile(filePath: string): Record<string, unknown> {
   return JSON.parse(readFileSync(filePath, "utf8")) as Record<string, unknown>;
 }
 
-function resolveWorkspacePackagePath(packageName: string): string | null {
-  if (packageName === "@paperclipai/adapter-utils") {
-    return path.join(repoRoot, "packages", "adapter-utils");
+function discoverWorkspacePackagePaths(rootDir: string): Map<string, string> {
+  const packagePaths = new Map<string, string>();
+  const ignoredDirNames = new Set([".git", ".paperclip", "dist", "node_modules"]);
+
+  function visit(dirPath: string) {
+    const packageJsonPath = path.join(dirPath, "package.json");
+    if (existsSync(packageJsonPath)) {
+      const packageJson = readJsonFile(packageJsonPath);
+      if (typeof packageJson.name === "string" && packageJson.name.length > 0) {
+        packagePaths.set(packageJson.name, dirPath);
+      }
+    }
+
+    for (const entry of readdirSync(dirPath, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      if (ignoredDirNames.has(entry.name)) continue;
+      visit(path.join(dirPath, entry.name));
+    }
   }
-  if (packageName === "@paperclipai/db") {
-    return path.join(repoRoot, "packages", "db");
-  }
-  if (packageName === "@paperclipai/shared") {
-    return path.join(repoRoot, "packages", "shared");
-  }
-  if (packageName === "@paperclipai/plugin-sdk") {
-    return path.join(repoRoot, "packages", "plugins", "sdk");
-  }
-  if (packageName.startsWith("@paperclipai/adapter-")) {
-    return path.join(repoRoot, "packages", "adapters", packageName.slice("@paperclipai/adapter-".length));
-  }
-  return null;
+
+  visit(path.join(rootDir, "packages"));
+  visit(path.join(rootDir, "server"));
+  visit(path.join(rootDir, "ui"));
+  visit(path.join(rootDir, "cli"));
+
+  return packagePaths;
 }
 
-function findServerWorkspaceLinkMismatches(): WorkspaceLinkMismatch[] {
-  const serverPackageJson = readJsonFile(path.join(repoRoot, "server", "package.json"));
+function isLinkedGitWorktreeCheckout(rootDir: string) {
+  const gitMetadataPath = path.join(rootDir, ".git");
+  if (!existsSync(gitMetadataPath)) return false;
+
+  const stat = lstatSync(gitMetadataPath);
+  if (!stat.isFile()) return false;
+
+  return readFileSync(gitMetadataPath, "utf8").trimStart().startsWith("gitdir:");
+}
+
+if (!isLinkedGitWorktreeCheckout(repoRoot)) {
+  process.exit(0);
+}
+
+const workspacePackagePaths = discoverWorkspacePackagePaths(repoRoot);
+const workspaceDirs = Array.from(
+  new Set(
+    Array.from(workspacePackagePaths.values())
+      .map((packagePath) => path.relative(repoRoot, packagePath))
+      .filter((workspaceDir) => workspaceDir.length > 0),
+  ),
+).sort();
+
+function findWorkspaceLinkMismatches(workspaceDir: string): WorkspaceLinkMismatch[] {
+  const packageJson = readJsonFile(path.join(repoRoot, workspaceDir, "package.json"));
   const dependencies = {
-    ...(serverPackageJson.dependencies as Record<string, unknown> | undefined),
-    ...(serverPackageJson.devDependencies as Record<string, unknown> | undefined),
+    ...(packageJson.dependencies as Record<string, unknown> | undefined),
+    ...(packageJson.devDependencies as Record<string, unknown> | undefined),
   };
   const mismatches: WorkspaceLinkMismatch[] = [];
 
   for (const [packageName, version] of Object.entries(dependencies)) {
     if (typeof version !== "string" || !version.startsWith("workspace:")) continue;
 
-    const expectedPath = resolveWorkspacePackagePath(packageName);
+    const expectedPath = workspacePackagePaths.get(packageName);
     if (!expectedPath) continue;
 
-    const linkPath = path.join(repoRoot, "server", "node_modules", ...packageName.split("/"));
+    const linkPath = path.join(repoRoot, workspaceDir, "node_modules", ...packageName.split("/"));
     const actualPath = existsSync(linkPath) ? path.resolve(realpathSync(linkPath)) : null;
     if (actualPath === path.resolve(expectedPath)) continue;
 
     mismatches.push({
+      workspaceDir,
       packageName,
       expectedPath: path.resolve(expectedPath),
       actualPath,
@@ -61,53 +95,32 @@ function findServerWorkspaceLinkMismatches(): WorkspaceLinkMismatch[] {
   return mismatches;
 }
 
-function runCommand(command: string, args: string[], cwd: string) {
-  return new Promise<void>((resolve, reject) => {
-    const child = spawn(command, args, {
-      cwd,
-      env: process.env,
-      stdio: "inherit",
-    });
-
-    child.on("error", reject);
-    child.on("exit", (code, signal) => {
-      if (code === 0) {
-        resolve();
-        return;
-      }
-      reject(
-        new Error(
-          `${command} ${args.join(" ")} failed with ${signal ? `signal ${signal}` : `exit code ${code ?? "unknown"}`}`,
-        ),
-      );
-    });
-  });
-}
-
-async function ensureServerWorkspaceLinksCurrent() {
-  const mismatches = findServerWorkspaceLinkMismatches();
+async function ensureWorkspaceLinksCurrent(workspaceDir: string) {
+  const mismatches = findWorkspaceLinkMismatches(workspaceDir);
   if (mismatches.length === 0) return;
 
-  console.log("[paperclip] detected stale workspace package links for server; relinking dependencies...");
+  console.log(`[paperclip] detected stale workspace package links for ${workspaceDir}; relinking dependencies...`);
   for (const mismatch of mismatches) {
     console.log(
       `[paperclip]   ${mismatch.packageName}: ${mismatch.actualPath ?? "missing"} -> ${mismatch.expectedPath}`,
     );
   }
 
-  const pnpmBin = process.platform === "win32" ? "pnpm.cmd" : "pnpm";
-  await runCommand(
-    pnpmBin,
-    ["install", "--force", "--config.confirmModulesPurge=false"],
-    repoRoot,
-  );
+  for (const mismatch of mismatches) {
+    const linkPath = path.join(repoRoot, mismatch.workspaceDir, "node_modules", ...mismatch.packageName.split("/"));
+    await fs.mkdir(path.dirname(linkPath), { recursive: true });
+    await fs.rm(linkPath, { recursive: true, force: true });
+    await fs.symlink(mismatch.expectedPath, linkPath);
+  }
 
-  const remainingMismatches = findServerWorkspaceLinkMismatches();
+  const remainingMismatches = findWorkspaceLinkMismatches(workspaceDir);
   if (remainingMismatches.length === 0) return;
 
   throw new Error(
-    `Workspace relink did not repair all server package links: ${remainingMismatches.map((item) => item.packageName).join(", ")}`,
+    `Workspace relink did not repair all ${workspaceDir} package links: ${remainingMismatches.map((item) => item.packageName).join(", ")}`,
   );
 }
 
-await ensureServerWorkspaceLinksCurrent();
+for (const workspaceDir of workspaceDirs) {
+  await ensureWorkspaceLinksCurrent(workspaceDir);
+}

scripts/paperclip-issue-update.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage:
+  scripts/paperclip-issue-update.sh [--issue-id ID] [--status STATUS] [--comment TEXT] [--dry-run]
+
+Reads a multiline markdown comment from stdin when stdin is piped. This preserves
+newlines when building the JSON payload for PATCH /api/issues/{issueId}.
+
+Examples:
+  scripts/paperclip-issue-update.sh --issue-id "$PAPERCLIP_TASK_ID" --status in_progress <<'MD'
+  Investigating formatting
+
+  - Pulled the raw comment body
+  - Comparing it with the run transcript
+  MD
+
+  scripts/paperclip-issue-update.sh --issue-id "$PAPERCLIP_TASK_ID" --status done --dry-run <<'MD'
+  Done
+
+  - Fixed the issue update helper
+  MD
+EOF
+}
+
+require_command() {
+  if ! command -v "$1" >/dev/null 2>&1; then
+    printf 'Missing required command: %s\n' "$1" >&2
+    exit 1
+  fi
+}
+
+issue_id="${PAPERCLIP_TASK_ID:-}"
+status=""
+comment_arg=""
+dry_run=0
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --issue-id)
+      issue_id="${2:-}"
+      shift 2
+      ;;
+    --status)
+      status="${2:-}"
+      shift 2
+      ;;
+    --comment)
+      comment_arg="${2:-}"
+      shift 2
+      ;;
+    --dry-run)
+      dry_run=1
+      shift
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    *)
+      printf 'Unknown argument: %s\n' "$1" >&2
+      usage >&2
+      exit 1
+      ;;
+  esac
+done
+
+if [[ -z "$issue_id" ]]; then
+  printf 'Missing issue id. Pass --issue-id or set PAPERCLIP_TASK_ID.\n' >&2
+  exit 1
+fi
+
+comment=""
+if [[ -n "$comment_arg" ]]; then
+  comment="$comment_arg"
+elif [[ ! -t 0 ]]; then
+  comment="$(cat)"
+fi
+
+require_command jq
+
+payload="$(
+  jq -nc \
+    --arg status "$status" \
+    --arg comment "$comment" \
+    '
+      (if $status == "" then {} else {status: $status} end) +
+      (if $comment == "" then {} else {comment: $comment} end)
+    '
+)"
+
+if [[ "$dry_run" == "1" ]]; then
+  printf '%s\n' "$payload"
+  exit 0
+fi
+
+if [[ -z "${PAPERCLIP_API_URL:-}" || -z "${PAPERCLIP_API_KEY:-}" || -z "${PAPERCLIP_RUN_ID:-}" ]]; then
+  printf 'Missing PAPERCLIP_API_URL, PAPERCLIP_API_KEY, or PAPERCLIP_RUN_ID.\n' >&2
+  exit 1
+fi
+
+curl -sS -X PATCH \
+  "$PAPERCLIP_API_URL/api/issues/$issue_id" \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
+  -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
+  -H 'Content-Type: application/json' \
+  --data-binary "$payload"

scripts/provision-worktree.sh

@@ -246,6 +246,8 @@ async function main() {
     server: {
       deploymentMode: sourceConfig?.server?.deploymentMode ?? "local_trusted",
       exposure: sourceConfig?.server?.exposure ?? "private",
+      ...(sourceConfig?.server?.bind ? { bind: sourceConfig.server.bind } : {}),
+      ...(sourceConfig?.server?.customBindHost ? { customBindHost: sourceConfig.server.customBindHost } : {}),
       host: sourceConfig?.server?.host ?? "127.0.0.1",
       port: serverPort,
       allowedHostnames: sourceConfig?.server?.allowedHostnames ?? [],
@@ -337,20 +339,6 @@ else
   write_fallback_worktree_config
 fi
 
-disable_seeded_routines() {
-  local company_id="${PAPERCLIP_COMPANY_ID:-}"
-  if [[ -z "$company_id" ]]; then
-    echo "PAPERCLIP_COMPANY_ID not set; skipping routine disable post-step." >&2
-    return 0
-  fi
-
-  if ! run_paperclipai_command routines disable-all --config "$worktree_config_path" --company-id "$company_id"; then
-    echo "paperclipai CLI not available in this workspace; skipping routine disable post-step." >&2
-  fi
-}
-
-disable_seeded_routines
-
 list_base_node_modules_paths() {
   cd "$base_cwd" &&
     find . \

server/src/__tests__/activity-routes.test.ts

@@ -10,6 +10,10 @@ const mockActivityService = vi.hoisted(() => ({
   create: vi.fn(),
 }));
 
+const mockHeartbeatService = vi.hoisted(() => ({
+  getRun: vi.fn(),
+}));
+
 const mockIssueService = vi.hoisted(() => ({
   getById: vi.fn(),
   getByIdentifier: vi.fn(),
@@ -22,6 +26,7 @@ function registerRouteMocks() {
 
   vi.doMock("../services/index.js", () => ({
     issueService: () => mockIssueService,
+    heartbeatService: () => mockHeartbeatService,
   }));
 }
 
@@ -62,6 +67,7 @@ describe("activity routes", () => {
     mockActivityService.runsForIssue.mockResolvedValue([
       {
         runId: "run-1",
+        adapterType: "codex_local",
       },
     ]);
 
@@ -72,6 +78,34 @@ describe("activity routes", () => {
     expect(mockIssueService.getByIdentifier).toHaveBeenCalledWith("PAP-475");
     expect(mockIssueService.getById).not.toHaveBeenCalled();
     expect(mockActivityService.runsForIssue).toHaveBeenCalledWith("company-1", "issue-uuid-1");
-    expect(res.body).toEqual([{ runId: "run-1" }]);
+    expect(res.body).toEqual([{ runId: "run-1", adapterType: "codex_local" }]);
+  });
+
+  it("requires company access before creating activity events", async () => {
+    const app = await createApp();
+    const res = await request(app)
+      .post("/api/companies/company-2/activity")
+      .send({
+        actorId: "user-1",
+        action: "test.event",
+        entityType: "issue",
+        entityId: "issue-1",
+      });
+
+    expect(res.status).toBe(403);
+    expect(mockActivityService.create).not.toHaveBeenCalled();
+  });
+
+  it("requires company access before listing issues for another company's run", async () => {
+    mockHeartbeatService.getRun.mockResolvedValue({
+      id: "run-2",
+      companyId: "company-2",
+    });
+
+    const app = await createApp();
+    const res = await request(app).get("/api/heartbeat-runs/run-2/issues");
+
+    expect(res.status).toBe(403);
+    expect(mockActivityService.issuesForRun).not.toHaveBeenCalled();
   });
 });

server/src/__tests__/adapter-session-codecs.test.ts

@@ -19,16 +19,19 @@ describe("adapter session codecs", () => {
     const parsed = claudeSessionCodec.deserialize({
       session_id: "claude-session-1",
       folder: "/tmp/workspace",
+      prompt_bundle_key: "bundle-1",
     });
     expect(parsed).toEqual({
       sessionId: "claude-session-1",
       cwd: "/tmp/workspace",
+      promptBundleKey: "bundle-1",
     });
 
     const serialized = claudeSessionCodec.serialize(parsed);
     expect(serialized).toEqual({
       sessionId: "claude-session-1",
       cwd: "/tmp/workspace",
+      promptBundleKey: "bundle-1",
     });
     expect(claudeSessionCodec.getDisplayId?.(serialized ?? null)).toBe("claude-session-1");
   });

server/src/__tests__/agent-instructions-routes.test.ts

@@ -298,15 +298,6 @@ describe("agent instructions bundle routes", () => {
       });
 
     expect(res.status, JSON.stringify(res.body)).toBe(200);
-    expect(mockAgentService.update).toHaveBeenCalledWith(
-      "11111111-1111-4111-8111-111111111111",
-      expect.objectContaining({
-        adapterConfig: expect.objectContaining({
-          command: "codex --profile engineer",
-        }),
-      }),
-      expect.any(Object),
-    );
     expect(res.body.adapterConfig).toMatchObject({
       command: "codex --profile engineer",
     });

server/src/__tests__/agent-live-run-routes.test.ts

@@ -0,0 +1,117 @@
+import express from "express";
+import request from "supertest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { agentRoutes } from "../routes/agents.js";
+import { errorHandler } from "../middleware/index.js";
+
+const mockAgentService = vi.hoisted(() => ({
+  getById: vi.fn(),
+}));
+
+const mockHeartbeatService = vi.hoisted(() => ({
+  getRunIssueSummary: vi.fn(),
+  getActiveRunIssueSummaryForAgent: vi.fn(),
+}));
+
+const mockIssueService = vi.hoisted(() => ({
+  getById: vi.fn(),
+  getByIdentifier: vi.fn(),
+}));
+
+vi.mock("../services/index.js", () => ({
+  agentService: () => mockAgentService,
+  agentInstructionsService: () => ({}),
+  accessService: () => ({}),
+  approvalService: () => ({}),
+  companySkillService: () => ({ listRuntimeSkillEntries: vi.fn() }),
+  budgetService: () => ({}),
+  heartbeatService: () => mockHeartbeatService,
+  issueApprovalService: () => ({}),
+  issueService: () => mockIssueService,
+  logActivity: vi.fn(),
+  secretService: () => ({}),
+  syncInstructionsBundleConfigFromFilePath: vi.fn((_agent, config) => config),
+  workspaceOperationService: () => ({}),
+}));
+
+vi.mock("../adapters/index.js", () => ({
+  findServerAdapter: vi.fn(),
+  listAdapterModels: vi.fn(),
+  detectAdapterModel: vi.fn(),
+  findActiveServerAdapter: vi.fn(),
+  requireServerAdapter: vi.fn(),
+}));
+
+function createApp() {
+  const app = express();
+  app.use(express.json());
+  app.use((req, _res, next) => {
+    (req as any).actor = {
+      type: "board",
+      userId: "local-board",
+      companyIds: ["company-1"],
+      source: "local_implicit",
+      isInstanceAdmin: false,
+    };
+    next();
+  });
+  app.use("/api", agentRoutes({} as any));
+  app.use(errorHandler);
+  return app;
+}
+
+describe("agent live run routes", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockIssueService.getByIdentifier.mockResolvedValue({
+      id: "issue-1",
+      companyId: "company-1",
+      executionRunId: "run-1",
+      assigneeAgentId: "agent-1",
+      status: "in_progress",
+    });
+    mockIssueService.getById.mockResolvedValue(null);
+    mockAgentService.getById.mockResolvedValue({
+      id: "agent-1",
+      companyId: "company-1",
+      name: "Builder",
+      adapterType: "codex_local",
+    });
+    mockHeartbeatService.getRunIssueSummary.mockResolvedValue({
+      id: "run-1",
+      status: "running",
+      invocationSource: "on_demand",
+      triggerDetail: "manual",
+      startedAt: new Date("2026-04-10T09:30:00.000Z"),
+      finishedAt: null,
+      createdAt: new Date("2026-04-10T09:29:59.000Z"),
+      agentId: "agent-1",
+      issueId: "issue-1",
+    });
+    mockHeartbeatService.getActiveRunIssueSummaryForAgent.mockResolvedValue(null);
+  });
+
+  it("returns a compact active run payload for issue polling", async () => {
+    const res = await request(createApp()).get("/api/issues/PAP-1295/active-run");
+
+    expect(res.status, JSON.stringify(res.body)).toBe(200);
+    expect(mockIssueService.getByIdentifier).toHaveBeenCalledWith("PAP-1295");
+    expect(mockHeartbeatService.getRunIssueSummary).toHaveBeenCalledWith("run-1");
+    expect(res.body).toEqual({
+      id: "run-1",
+      status: "running",
+      invocationSource: "on_demand",
+      triggerDetail: "manual",
+      startedAt: "2026-04-10T09:30:00.000Z",
+      finishedAt: null,
+      createdAt: "2026-04-10T09:29:59.000Z",
+      agentId: "agent-1",
+      issueId: "issue-1",
+      agentName: "Builder",
+      adapterType: "codex_local",
+    });
+    expect(res.body).not.toHaveProperty("resultJson");
+    expect(res.body).not.toHaveProperty("contextSnapshot");
+    expect(res.body).not.toHaveProperty("logRef");
+  });
+});

server/src/__tests__/agent-permissions-routes.test.ts

@@ -1,6 +1,8 @@
 import express from "express";
 import request from "supertest";
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import { errorHandler } from "../middleware/index.js";
+import { agentRoutes } from "../routes/agents.js";
 
 const agentId = "11111111-1111-4111-8111-111111111111";
 const companyId = "22222222-2222-4222-8222-222222222222";
@@ -59,6 +61,8 @@ const mockBudgetService = vi.hoisted(() => ({
 const mockHeartbeatService = vi.hoisted(() => ({
   listTaskSessions: vi.fn(),
   resetRuntimeSession: vi.fn(),
+  getRun: vi.fn(),
+  cancelRun: vi.fn(),
 }));
 
 const mockIssueApprovalService = vi.hoisted(() => ({
@@ -86,32 +90,30 @@ const mockLogActivity = vi.hoisted(() => vi.fn());
 const mockTrackAgentCreated = vi.hoisted(() => vi.fn());
 const mockGetTelemetryClient = vi.hoisted(() => vi.fn());
 
-function registerServiceMocks() {
-  vi.doMock("@paperclipai/shared/telemetry", () => ({
-    trackAgentCreated: mockTrackAgentCreated,
-    trackErrorHandlerCrash: vi.fn(),
-  }));
+vi.mock("@paperclipai/shared/telemetry", () => ({
+  trackAgentCreated: mockTrackAgentCreated,
+  trackErrorHandlerCrash: vi.fn(),
+}));
 
-  vi.doMock("../telemetry.js", () => ({
-    getTelemetryClient: mockGetTelemetryClient,
-  }));
+vi.mock("../telemetry.js", () => ({
+  getTelemetryClient: mockGetTelemetryClient,
+}));
 
-  vi.doMock("../services/index.js", () => ({
-    agentService: () => mockAgentService,
-    agentInstructionsService: () => mockAgentInstructionsService,
-    accessService: () => mockAccessService,
-    approvalService: () => mockApprovalService,
-    companySkillService: () => mockCompanySkillService,
-    budgetService: () => mockBudgetService,
-    heartbeatService: () => mockHeartbeatService,
-    issueApprovalService: () => mockIssueApprovalService,
-    issueService: () => mockIssueService,
-    logActivity: mockLogActivity,
-    secretService: () => mockSecretService,
-    syncInstructionsBundleConfigFromFilePath: vi.fn((_agent, config) => config),
-    workspaceOperationService: () => mockWorkspaceOperationService,
-  }));
-}
+vi.mock("../services/index.js", () => ({
+  agentService: () => mockAgentService,
+  agentInstructionsService: () => mockAgentInstructionsService,
+  accessService: () => mockAccessService,
+  approvalService: () => mockApprovalService,
+  companySkillService: () => mockCompanySkillService,
+  budgetService: () => mockBudgetService,
+  heartbeatService: () => mockHeartbeatService,
+  issueApprovalService: () => mockIssueApprovalService,
+  issueService: () => mockIssueService,
+  logActivity: mockLogActivity,
+  secretService: () => mockSecretService,
+  syncInstructionsBundleConfigFromFilePath: vi.fn((_agent, config) => config),
+  workspaceOperationService: () => mockWorkspaceOperationService,
+}));
 
 function createDbStub() {
   return {
@@ -129,11 +131,7 @@ function createDbStub() {
   };
 }
 
-async function createApp(actor: Record<string, unknown>) {
-  const [{ agentRoutes }, { errorHandler }] = await Promise.all([
-    import("../routes/agents.js"),
-    import("../middleware/index.js"),
-  ]);
+function createApp(actor: Record<string, unknown>) {
   const app = express();
   app.use(express.json());
   app.use((req, _res, next) => {
@@ -147,8 +145,6 @@ async function createApp(actor: Record<string, unknown>) {
 
 describe("agent permission routes", () => {
   beforeEach(() => {
-    vi.resetModules();
-    registerServiceMocks();
     vi.resetAllMocks();
     mockGetTelemetryClient.mockReturnValue({ track: vi.fn() });
     mockAgentService.getById.mockResolvedValue(baseAgent);
@@ -195,7 +191,7 @@ describe("agent permission routes", () => {
   });
 
   it("grants tasks:assign by default when board creates a new agent", async () => {
-    const app = await createApp({
+    const app = createApp({
       type: "board",
       userId: "board-user",
       source: "local_implicit",
@@ -231,7 +227,7 @@ describe("agent permission routes", () => {
   });
 
   it("normalizes direct agent creation to disable timer heartbeats by default", async () => {
-    const app = await createApp({
+    const app = createApp({
       type: "board",
       userId: "board-user",
       source: "local_implicit",
@@ -253,7 +249,7 @@ describe("agent permission routes", () => {
         },
       });
 
-    expect(res.status).toBe(201);
+    expect([200, 201]).toContain(res.status);
     expect(mockAgentService.create).toHaveBeenCalledWith(
       companyId,
       expect.objectContaining({
@@ -268,7 +264,7 @@ describe("agent permission routes", () => {
   });
 
   it("normalizes hire requests to disable timer heartbeats by default", async () => {
-    const app = await createApp({
+    const app = createApp({
       type: "board",
       userId: "board-user",
       source: "local_implicit",
@@ -319,7 +315,7 @@ describe("agent permission routes", () => {
       },
     ]);
 
-    const app = await createApp({
+    const app = createApp({
       type: "board",
       userId: "board-user",
       source: "local_implicit",
@@ -340,7 +336,7 @@ describe("agent permission routes", () => {
       permissions: { canCreateAgents: true },
     });
 
-    const app = await createApp({
+    const app = createApp({
       type: "board",
       userId: "board-user",
       source: "local_implicit",
@@ -375,7 +371,7 @@ describe("agent permission routes", () => {
       },
     ]);
 
-    const app = await createApp({
+    const app = createApp({
       type: "agent",
       agentId,
       companyId,
@@ -397,4 +393,26 @@ describe("agent permission routes", () => {
       },
     ]);
   });
+
+  it("rejects heartbeat cancellation outside the caller company scope", async () => {
+    mockHeartbeatService.getRun.mockResolvedValue({
+      id: "run-1",
+      companyId: "33333333-3333-4333-8333-333333333333",
+      agentId,
+      status: "running",
+    });
+
+    const app = createApp({
+      type: "board",
+      userId: "board-user",
+      source: "session",
+      isInstanceAdmin: false,
+      companyIds: [companyId],
+    });
+
+    const res = await request(app).post("/api/heartbeat-runs/run-1/cancel").send({});
+
+    expect(res.status).toBe(403);
+    expect(mockHeartbeatService.cancelRun).not.toHaveBeenCalled();
+  });
 });

server/src/__tests__/agent-skills-routes.test.ts

@@ -57,7 +57,7 @@ const mockAdapter = vi.hoisted(() => ({
   syncSkills: vi.fn(),
 }));
 
-function registerRouteMocks() {
+function registerModuleMocks() {
   vi.doMock("@paperclipai/shared/telemetry", () => ({
     trackAgentCreated: mockTrackAgentCreated,
     trackErrorHandlerCrash: vi.fn(),
@@ -149,7 +149,7 @@ function makeAgent(adapterType: string) {
 describe("agent skill routes", () => {
   beforeEach(() => {
     vi.resetModules();
-    registerRouteMocks();
+    registerModuleMocks();
     vi.resetAllMocks();
     mockGetTelemetryClient.mockReturnValue({ track: vi.fn() });
     mockAgentService.resolveByReference.mockResolvedValue({
@@ -238,9 +238,6 @@ describe("agent skill routes", () => {
       .get("/api/agents/11111111-1111-4111-8111-111111111111/skills?companyId=company-1");
 
     expect(res.status, JSON.stringify(res.body)).toBe(200);
-    expect(mockCompanySkillService.listRuntimeSkillEntries).toHaveBeenCalledWith("company-1", {
-      materializeMissing: false,
-    });
     expect(mockAdapter.listSkills).toHaveBeenCalledWith(
       expect.objectContaining({
         adapterType: "claude_local",
@@ -266,9 +263,6 @@ describe("agent skill routes", () => {
       .get("/api/agents/11111111-1111-4111-8111-111111111111/skills?companyId=company-1");
 
     expect(res.status, JSON.stringify(res.body)).toBe(200);
-    expect(mockCompanySkillService.listRuntimeSkillEntries).toHaveBeenCalledWith("company-1", {
-      materializeMissing: false,
-    });
   });
 
   it("keeps runtime materialization for persistent skill adapters", async () => {
@@ -286,9 +280,6 @@ describe("agent skill routes", () => {
       .get("/api/agents/11111111-1111-4111-8111-111111111111/skills?companyId=company-1");
 
     expect(res.status, JSON.stringify(res.body)).toBe(200);
-    expect(mockCompanySkillService.listRuntimeSkillEntries).toHaveBeenCalledWith("company-1", {
-      materializeMissing: true,
-    });
   });
 
   it("skips runtime materialization when syncing Claude skills", async () => {
@@ -299,9 +290,6 @@ describe("agent skill routes", () => {
       .send({ desiredSkills: ["paperclipai/paperclip/paperclip"] });
 
     expect(res.status, JSON.stringify(res.body)).toBe(200);
-    expect(mockCompanySkillService.listRuntimeSkillEntries).toHaveBeenCalledWith("company-1", {
-      materializeMissing: false,
-    });
     expect(mockAdapter.syncSkills).toHaveBeenCalled();
   });
 
@@ -313,7 +301,6 @@ describe("agent skill routes", () => {
       .send({ desiredSkills: ["paperclip"] });
 
     expect(res.status, JSON.stringify(res.body)).toBe(200);
-    expect(mockCompanySkillService.resolveRequestedSkillKeys).toHaveBeenCalledWith("company-1", ["paperclip"]);
     expect(mockAgentService.update).toHaveBeenCalledWith(
       expect.any(String),
       expect.objectContaining({
@@ -339,7 +326,6 @@ describe("agent skill routes", () => {
       });
 
     expect([200, 201], JSON.stringify(res.body)).toContain(res.status);
-    expect(mockCompanySkillService.resolveRequestedSkillKeys).toHaveBeenCalledWith("company-1", ["paperclip"]);
     expect(mockAgentService.create).toHaveBeenCalledWith(
       "company-1",
       expect.objectContaining({
@@ -368,15 +354,7 @@ describe("agent skill routes", () => {
         },
       });
 
-    expect(res.status, JSON.stringify(res.body)).toBe(201);
-    expect(mockAgentInstructionsService.materializeManagedBundle).toHaveBeenCalledWith(
-      expect.objectContaining({
-        id: "11111111-1111-4111-8111-111111111111",
-        adapterType: "claude_local",
-      }),
-      { "AGENTS.md": "You are QA." },
-      { entryFile: "AGENTS.md", replaceExisting: false },
-    );
+    expect([200, 201], JSON.stringify(res.body)).toContain(res.status);
     expect(mockAgentService.update).toHaveBeenCalledWith(
       "11111111-1111-4111-8111-111111111111",
       expect.objectContaining({
@@ -404,7 +382,7 @@ describe("agent skill routes", () => {
         adapterConfig: {},
       });
 
-    expect(res.status, JSON.stringify(res.body)).toBe(201);
+    expect([200, 201], JSON.stringify(res.body)).toContain(res.status);
     expect(mockAgentInstructionsService.materializeManagedBundle).toHaveBeenCalledWith(
       expect.objectContaining({
         id: "11111111-1111-4111-8111-111111111111",
@@ -431,7 +409,7 @@ describe("agent skill routes", () => {
         adapterConfig: {},
       });
 
-    expect(res.status, JSON.stringify(res.body)).toBe(201);
+    expect([200, 201], JSON.stringify(res.body)).toContain(res.status);
     expect(mockAgentInstructionsService.materializeManagedBundle).toHaveBeenCalledWith(
       expect.objectContaining({
         id: "11111111-1111-4111-8111-111111111111",
@@ -459,7 +437,6 @@ describe("agent skill routes", () => {
       });
 
     expect(res.status, JSON.stringify(res.body)).toBe(201);
-    expect(mockCompanySkillService.resolveRequestedSkillKeys).toHaveBeenCalledWith("company-1", ["paperclip"]);
     expect(mockApprovalService.create).toHaveBeenCalledWith(
       "company-1",
       expect.objectContaining({

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

@@ -1,8 +1,6 @@
 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(),
@@ -39,7 +37,11 @@ vi.mock("../services/index.js", () => ({
   secretService: () => mockSecretService,
 }));
 
-function createApp() {
+async function createApp(actorOverrides: Record<string, unknown> = {}) {
+  const [{ approvalRoutes }, { errorHandler }] = await Promise.all([
+    import("../routes/approvals.js"),
+    import("../middleware/index.js"),
+  ]);
   const app = express();
   app.use(express.json());
   app.use((req, _res, next) => {
@@ -49,6 +51,7 @@ function createApp() {
       companyIds: ["company-1"],
       source: "session",
       isInstanceAdmin: false,
+      ...actorOverrides,
     };
     next();
   });
@@ -57,7 +60,11 @@ function createApp() {
   return app;
 }
 
-function createAgentApp() {
+async function createAgentApp() {
+  const [{ approvalRoutes }, { errorHandler }] = await Promise.all([
+    import("../routes/approvals.js"),
+    import("../middleware/index.js"),
+  ]);
   const app = express();
   app.use(express.json());
   app.use((req, _res, next) => {
@@ -77,13 +84,22 @@ function createAgentApp() {
 
 describe("approval routes idempotent retries", () => {
   beforeEach(() => {
-    vi.clearAllMocks();
+    vi.resetModules();
+    vi.resetAllMocks();
     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.getById.mockResolvedValue({
+      id: "approval-1",
+      companyId: "company-1",
+      type: "hire_agent",
+      status: "approved",
+      payload: {},
+      requestedByAgentId: "agent-1",
+    });
     mockApprovalService.approve.mockResolvedValue({
       approval: {
         id: "approval-1",
@@ -96,7 +112,7 @@ describe("approval routes idempotent retries", () => {
       applied: false,
     });
 
-    const res = await request(createApp())
+    const res = await request(await createApp())
       .post("/api/approvals/approval-1/approve")
       .send({});
 
@@ -107,6 +123,13 @@ describe("approval routes idempotent retries", () => {
   });
 
   it("does not emit duplicate rejection logs when reject is already resolved", async () => {
+    mockApprovalService.getById.mockResolvedValue({
+      id: "approval-1",
+      companyId: "company-1",
+      type: "hire_agent",
+      status: "rejected",
+      payload: {},
+    });
     mockApprovalService.reject.mockResolvedValue({
       approval: {
         id: "approval-1",
@@ -118,7 +141,7 @@ describe("approval routes idempotent retries", () => {
       applied: false,
     });
 
-    const res = await request(createApp())
+    const res = await request(await createApp())
       .post("/api/approvals/approval-1/reject")
       .send({});
 
@@ -126,6 +149,40 @@ describe("approval routes idempotent retries", () => {
     expect(mockLogActivity).not.toHaveBeenCalled();
   });
 
+  it("rejects approval decisions for companies outside the caller scope", async () => {
+    mockApprovalService.getById.mockResolvedValue({
+      id: "approval-2",
+      companyId: "company-2",
+      type: "hire_agent",
+      status: "pending",
+      payload: {},
+    });
+
+    const res = await request(await createApp())
+      .post("/api/approvals/approval-2/approve")
+      .send({});
+
+    expect(res.status).toBe(403);
+    expect(mockApprovalService.approve).not.toHaveBeenCalled();
+  });
+
+  it("rejects approval revision requests for companies outside the caller scope", async () => {
+    mockApprovalService.getById.mockResolvedValue({
+      id: "approval-3",
+      companyId: "company-2",
+      type: "hire_agent",
+      status: "pending",
+      payload: {},
+    });
+
+    const res = await request(await createApp())
+      .post("/api/approvals/approval-3/request-revision")
+      .send({ decisionNote: "Need changes" });
+
+    expect(res.status).toBe(403);
+    expect(mockApprovalService.requestRevision).not.toHaveBeenCalled();
+  });
+
   it("lets agents create generic issue-linked board approval requests", async () => {
     mockApprovalService.create.mockResolvedValue({
       id: "approval-1",
@@ -142,7 +199,7 @@ describe("approval routes idempotent retries", () => {
       updatedAt: new Date("2026-04-06T00:00:00.000Z"),
     });
 
-    const res = await request(createAgentApp())
+    const res = await request(await createAgentApp())
       .post("/api/companies/company-1/approvals")
       .send({
         type: "request_board_approval",

server/src/__tests__/claude-local-execute.test.ts

@@ -7,11 +7,21 @@ import { execute } from "@paperclipai/adapter-claude-local/server";
 async function writeFakeClaudeCommand(commandPath: string): Promise<void> {
   const script = `#!/usr/bin/env node
 const fs = require("node:fs");
+const path = require("node:path");
 
+const argv = process.argv.slice(2);
+const addDirIndex = argv.indexOf("--add-dir");
+const addDir = addDirIndex >= 0 ? argv[addDirIndex + 1] : null;
+const instructionsIndex = argv.indexOf("--append-system-prompt-file");
+const instructionsFilePath = instructionsIndex >= 0 ? argv[instructionsIndex + 1] : null;
 const capturePath = process.env.PAPERCLIP_TEST_CAPTURE_PATH;
 const payload = {
-  argv: process.argv.slice(2),
+  argv,
   prompt: fs.readFileSync(0, "utf8"),
+  addDir,
+  instructionsFilePath,
+  instructionsContents: instructionsFilePath ? fs.readFileSync(instructionsFilePath, "utf8") : null,
+  skillEntries: addDir ? fs.readdirSync(path.join(addDir, ".claude", "skills")).sort() : [],
   claudeConfigDir: process.env.CLAUDE_CONFIG_DIR || null,
 };
 if (capturePath) {
@@ -25,7 +35,284 @@ console.log(JSON.stringify({ type: "result", session_id: "claude-session-1", res
   await fs.chmod(commandPath, 0o755);
 }
 
+type CapturePayload = {
+  argv: string[];
+  prompt: string;
+  addDir: string | null;
+  instructionsFilePath: string | null;
+  instructionsContents: string | null;
+  skillEntries: string[];
+  claudeConfigDir: string | null;
+  appendedSystemPromptFilePath?: string | null;
+  appendedSystemPromptFileContents?: string | null;
+};
+
+async function writeRetryThenSucceedClaudeCommand(commandPath: string): Promise<void> {
+  const script = `#!/usr/bin/env node
+const fs = require("node:fs");
+
+const capturePath = process.env.PAPERCLIP_TEST_CAPTURE_PATH;
+const statePath = process.env.PAPERCLIP_TEST_STATE_PATH;
+const promptFileFlagIndex = process.argv.indexOf("--append-system-prompt-file");
+const appendedSystemPromptFilePath = promptFileFlagIndex >= 0 ? process.argv[promptFileFlagIndex + 1] : null;
+const payload = {
+  argv: process.argv.slice(2),
+  prompt: fs.readFileSync(0, "utf8"),
+  claudeConfigDir: process.env.CLAUDE_CONFIG_DIR || null,
+  appendedSystemPromptFilePath,
+  appendedSystemPromptFileContents: appendedSystemPromptFilePath ? fs.readFileSync(appendedSystemPromptFilePath, "utf8") : null,
+};
+if (capturePath) {
+  const entries = fs.existsSync(capturePath) ? JSON.parse(fs.readFileSync(capturePath, "utf8")) : [];
+  entries.push(payload);
+  fs.writeFileSync(capturePath, JSON.stringify(entries), "utf8");
+}
+const resumed = process.argv.includes("--resume");
+const shouldFailResume = resumed && statePath && !fs.existsSync(statePath);
+if (shouldFailResume) {
+  fs.writeFileSync(statePath, "retried", "utf8");
+  console.log(JSON.stringify({
+    type: "result",
+    subtype: "error",
+    session_id: "claude-session-1",
+    result: "No conversation found with session id claude-session-1",
+    errors: ["No conversation found with session id claude-session-1"],
+  }));
+  process.exit(1);
+}
+console.log(JSON.stringify({ type: "system", subtype: "init", session_id: "claude-session-2", model: "claude-sonnet" }));
+console.log(JSON.stringify({ type: "assistant", session_id: "claude-session-2", message: { content: [{ type: "text", text: "hello" }] } }));
+console.log(JSON.stringify({ type: "result", session_id: "claude-session-2", result: "hello", usage: { input_tokens: 1, cache_read_input_tokens: 0, output_tokens: 1 } }));
+`;
+  await fs.writeFile(commandPath, script, "utf8");
+  await fs.chmod(commandPath, 0o755);
+}
+
+async function setupExecuteEnv(
+  root: string,
+  options?: { commandWriter?: (commandPath: string) => Promise<void> },
+) {
+  const workspace = path.join(root, "workspace");
+  const binDir = path.join(root, "bin");
+  const commandPath = path.join(binDir, "claude");
+  const capturePath = path.join(root, "capture.json");
+  const statePath = path.join(root, "state.txt");
+  await fs.mkdir(workspace, { recursive: true });
+  await fs.mkdir(binDir, { recursive: true });
+  await (options?.commandWriter ?? writeFakeClaudeCommand)(commandPath);
+  const previousHome = process.env.HOME;
+  const previousPath = process.env.PATH;
+  process.env.HOME = root;
+  process.env.PATH = `${binDir}${path.delimiter}${process.env.PATH ?? ""}`;
+  return {
+    workspace, commandPath, capturePath, statePath,
+    restore: () => {
+      if (previousHome === undefined) delete process.env.HOME;
+      else process.env.HOME = previousHome;
+      if (previousPath === undefined) delete process.env.PATH;
+      else process.env.PATH = previousPath;
+    },
+  };
+}
+
 describe("claude execute", () => {
+  /**
+   * Regression tests for https://github.com/paperclipai/paperclip/issues/2848
+   *
+   * --append-system-prompt-file should only be passed on fresh sessions.
+   * On resumed sessions the instructions are already in the session cache;
+   * re-injecting them wastes tokens and may be rejected by the CLI.
+   */
+  it("passes --append-system-prompt-file on a fresh session when instructionsFile is set", async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-claude-exec-fresh-"));
+    const { workspace, commandPath, capturePath, restore } = await setupExecuteEnv(root);
+    const instructionsFile = path.join(root, "instructions.md");
+    await fs.writeFile(instructionsFile, "# Agent instructions", "utf-8");
+    try {
+      await execute({
+        runId: "run-fresh",
+        agent: { id: "agent-1", companyId: "co-1", name: "Test", adapterType: "claude_local", adapterConfig: {} },
+        runtime: { sessionId: null, sessionParams: null, sessionDisplayId: null, taskKey: null },
+        config: {
+          command: commandPath,
+          cwd: workspace,
+          env: { PAPERCLIP_TEST_CAPTURE_PATH: capturePath },
+          promptTemplate: "Do work.",
+          instructionsFilePath: instructionsFile,
+        },
+        context: {},
+        authToken: "tok",
+        onLog: async () => {},
+        onMeta: async () => {},
+      });
+      const captured = JSON.parse(await fs.readFile(capturePath, "utf-8"));
+      expect(captured.argv).toContain("--append-system-prompt-file");
+    } finally {
+      restore();
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it("omits --append-system-prompt-file on a resumed session even when instructionsFile is set", async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-claude-exec-resume-"));
+    const { workspace, commandPath, capturePath, restore } = await setupExecuteEnv(root);
+    const instructionsFile = path.join(root, "instructions.md");
+    await fs.writeFile(instructionsFile, "# Agent instructions", "utf-8");
+    try {
+      await execute({
+        runId: "run-resume",
+        agent: { id: "agent-1", companyId: "co-1", name: "Test", adapterType: "claude_local", adapterConfig: {} },
+        runtime: { sessionId: "claude-session-1", sessionParams: null, sessionDisplayId: null, taskKey: null },
+        config: {
+          command: commandPath,
+          cwd: workspace,
+          env: { PAPERCLIP_TEST_CAPTURE_PATH: capturePath },
+          promptTemplate: "Do work.",
+          instructionsFilePath: instructionsFile,
+        },
+        context: {},
+        authToken: "tok",
+        onLog: async () => {},
+        onMeta: async () => {},
+      });
+      const captured = JSON.parse(await fs.readFile(capturePath, "utf-8"));
+      expect(captured.argv).not.toContain("--append-system-prompt-file");
+      expect(captured.argv).toContain("--resume");
+    } finally {
+      restore();
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+
+  /**
+   * Regression tests for commandNotes accuracy (Greptile P2).
+   *
+   * commandNotes should only claim instructions were injected when the flag
+   * was actually passed — i.e. on fresh sessions, not resumed ones.
+   */
+  it("commandNotes reports injection on a fresh session with instructionsFile", async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-claude-exec-notes-fresh-"));
+    const { workspace, commandPath, restore } = await setupExecuteEnv(root);
+    const instructionsFile = path.join(root, "instructions.md");
+    await fs.writeFile(instructionsFile, "# Agent instructions", "utf-8");
+    let capturedNotes: string[] = [];
+    try {
+      await execute({
+        runId: "run-notes-fresh",
+        agent: { id: "agent-1", companyId: "co-1", name: "Test", adapterType: "claude_local", adapterConfig: {} },
+        runtime: { sessionId: null, sessionParams: null, sessionDisplayId: null, taskKey: null },
+        config: {
+          command: commandPath,
+          cwd: workspace,
+          env: {},
+          promptTemplate: "Do work.",
+          instructionsFilePath: instructionsFile,
+        },
+        context: {},
+        authToken: "tok",
+        onLog: async () => {},
+        onMeta: async (meta) => { capturedNotes = (meta.commandNotes as string[]) ?? []; },
+      });
+      expect(capturedNotes.some((n) => n.includes("--append-system-prompt-file"))).toBe(true);
+    } finally {
+      restore();
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it("commandNotes is empty on a resumed session even when instructionsFile is set", async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-claude-exec-notes-resume-"));
+    const { workspace, commandPath, restore } = await setupExecuteEnv(root);
+    const instructionsFile = path.join(root, "instructions.md");
+    await fs.writeFile(instructionsFile, "# Agent instructions", "utf-8");
+    let capturedNotes: string[] = ["sentinel"];
+    try {
+      await execute({
+        runId: "run-notes-resume",
+        agent: { id: "agent-1", companyId: "co-1", name: "Test", adapterType: "claude_local", adapterConfig: {} },
+        runtime: { sessionId: "claude-session-1", sessionParams: null, sessionDisplayId: null, taskKey: null },
+        config: {
+          command: commandPath,
+          cwd: workspace,
+          env: {},
+          promptTemplate: "Do work.",
+          instructionsFilePath: instructionsFile,
+        },
+        context: {},
+        authToken: "tok",
+        onLog: async () => {},
+        onMeta: async (meta) => { capturedNotes = (meta.commandNotes as string[]) ?? []; },
+      });
+      expect(capturedNotes).toHaveLength(0);
+    } finally {
+      restore();
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it("rebuilds the combined instructions file when an unknown resumed session falls back to fresh", async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-claude-exec-resume-fallback-"));
+    const { workspace, commandPath, capturePath, statePath, restore } = await setupExecuteEnv(root, {
+      commandWriter: writeRetryThenSucceedClaudeCommand,
+    });
+    const instructionsFile = path.join(root, "instructions.md");
+    await fs.writeFile(instructionsFile, "# Agent instructions", "utf-8");
+    const metaEvents: Array<{ commandArgs: string[]; commandNotes: string[] }> = [];
+    try {
+      const result = await execute({
+        runId: "run-resume-fallback",
+        agent: { id: "agent-1", companyId: "co-1", name: "Test", adapterType: "claude_local", adapterConfig: {} },
+        runtime: { sessionId: "claude-session-1", sessionParams: null, sessionDisplayId: null, taskKey: null },
+        config: {
+          command: commandPath,
+          cwd: workspace,
+          env: {
+            PAPERCLIP_TEST_CAPTURE_PATH: capturePath,
+            PAPERCLIP_TEST_STATE_PATH: statePath,
+          },
+          promptTemplate: "Do work.",
+          instructionsFilePath: instructionsFile,
+        },
+        context: {},
+        authToken: "tok",
+        onLog: async () => {},
+        onMeta: async (meta) => {
+          metaEvents.push({
+            commandArgs: ((meta.commandArgs as string[]) ?? []).slice(),
+            commandNotes: ((meta.commandNotes as string[]) ?? []).slice(),
+          });
+        },
+      });
+      const captured = JSON.parse(await fs.readFile(capturePath, "utf-8")) as Array<{
+        argv: string[];
+        appendedSystemPromptFilePath: string | null;
+        appendedSystemPromptFileContents: string | null;
+      }>;
+      expect(captured).toHaveLength(2);
+      expect(captured[0]?.argv).toContain("--resume");
+      expect(captured[0]?.argv).not.toContain("--append-system-prompt-file");
+      expect(captured[1]?.argv).not.toContain("--resume");
+      expect(captured[1]?.argv).toContain("--append-system-prompt-file");
+      expect(captured[1]?.appendedSystemPromptFilePath).toContain("agent-instructions.md");
+      expect(captured[1]?.appendedSystemPromptFilePath).not.toBe(instructionsFile);
+      expect(captured[1]?.appendedSystemPromptFileContents).toContain("# Agent instructions");
+      expect(captured[1]?.appendedSystemPromptFileContents).toContain(
+        `The above agent instructions were loaded from ${instructionsFile}. ` +
+        `Resolve any relative file references from ${path.dirname(instructionsFile)}/. ` +
+        `This base directory is authoritative for sibling instruction files such as ` +
+        `./HEARTBEAT.md, ./SOUL.md, and ./TOOLS.md; do not resolve those from the parent agent directory.`,
+      );
+      expect(metaEvents).toHaveLength(2);
+      expect(metaEvents[0]?.commandNotes).toHaveLength(0);
+      expect(metaEvents[1]?.commandNotes.some((note) => note.includes("--append-system-prompt-file"))).toBe(true);
+      expect(result.sessionId).toBe("claude-session-2");
+      expect(result.clearSession).toBe(false);
+    } finally {
+      restore();
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+
   it("logs HOME, CLAUDE_CONFIG_DIR, and the resolved executable path in invocation metadata", async () => {
     const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-claude-execute-meta-"));
     const workspace = path.join(root, "workspace");
@@ -96,4 +383,259 @@ describe("claude execute", () => {
       await fs.rm(root, { recursive: true, force: true });
     }
   });
+
+  it("reuses a stable Paperclip-managed Claude prompt bundle across equivalent runs", async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-claude-execute-bundle-"));
+    const workspace = path.join(root, "workspace");
+    const commandPath = path.join(root, "claude");
+    const capturePath1 = path.join(root, "capture-1.json");
+    const capturePath2 = path.join(root, "capture-2.json");
+    const instructionsPath = path.join(root, "AGENTS.md");
+    const paperclipHome = path.join(root, "paperclip-home");
+    await fs.mkdir(workspace, { recursive: true });
+    await fs.writeFile(instructionsPath, "You are managed instructions.\n", "utf8");
+    await writeFakeClaudeCommand(commandPath);
+
+    const previousHome = process.env.HOME;
+    const previousPaperclipHome = process.env.PAPERCLIP_HOME;
+    process.env.HOME = root;
+    process.env.PAPERCLIP_HOME = paperclipHome;
+
+    try {
+      const first = await execute({
+        runId: "run-1",
+        agent: {
+          id: "agent-1",
+          companyId: "company-1",
+          name: "Claude Coder",
+          adapterType: "claude_local",
+          adapterConfig: {},
+        },
+        runtime: {
+          sessionId: null,
+          sessionParams: null,
+          sessionDisplayId: null,
+          taskKey: null,
+        },
+        config: {
+          command: commandPath,
+          cwd: workspace,
+          instructionsFilePath: instructionsPath,
+          env: {
+            PAPERCLIP_TEST_CAPTURE_PATH: capturePath1,
+          },
+          promptTemplate: "Follow the paperclip heartbeat.",
+        },
+        context: {},
+        authToken: "run-jwt-token",
+        onLog: async () => {},
+      });
+
+      expect(first.exitCode).toBe(0);
+      expect(first.errorMessage).toBeNull();
+      expect(first.sessionParams).toMatchObject({
+        sessionId: "claude-session-1",
+        cwd: workspace,
+      });
+      expect(typeof first.sessionParams?.promptBundleKey).toBe("string");
+
+      const second = await execute({
+        runId: "run-2",
+        agent: {
+          id: "agent-1",
+          companyId: "company-1",
+          name: "Claude Coder",
+          adapterType: "claude_local",
+          adapterConfig: {},
+        },
+        runtime: {
+          sessionId: null,
+          sessionParams: first.sessionParams ?? null,
+          sessionDisplayId: null,
+          taskKey: null,
+        },
+        config: {
+          command: commandPath,
+          cwd: workspace,
+          instructionsFilePath: instructionsPath,
+          env: {
+            PAPERCLIP_TEST_CAPTURE_PATH: capturePath2,
+          },
+          promptTemplate: "Follow the paperclip heartbeat.",
+        },
+        context: {
+          issueId: "issue-1",
+          taskId: "issue-1",
+          wakeReason: "issue_commented",
+          wakeCommentId: "comment-2",
+          paperclipWake: {
+            reason: "issue_commented",
+            issue: {
+              id: "issue-1",
+              identifier: "PAP-874",
+              title: "chat-speed issues",
+              status: "in_progress",
+              priority: "medium",
+            },
+            commentIds: ["comment-2"],
+            latestCommentId: "comment-2",
+            comments: [
+              {
+                id: "comment-2",
+                issueId: "issue-1",
+                body: "Second comment",
+                bodyTruncated: false,
+                createdAt: "2026-03-28T14:35:10.000Z",
+                author: { type: "user", id: "user-1" },
+              },
+            ],
+            commentWindow: {
+              requestedCount: 1,
+              includedCount: 1,
+              missingCount: 0,
+            },
+            truncated: false,
+            fallbackFetchNeeded: false,
+          },
+        },
+        authToken: "run-jwt-token",
+        onLog: async () => {},
+      });
+
+      expect(second.exitCode).toBe(0);
+      expect(second.errorMessage).toBeNull();
+
+      const capture1 = JSON.parse(await fs.readFile(capturePath1, "utf8")) as CapturePayload;
+      const capture2 = JSON.parse(await fs.readFile(capturePath2, "utf8")) as CapturePayload;
+      const expectedRoot = path.join(
+        paperclipHome,
+        "instances",
+        "default",
+        "companies",
+        "company-1",
+        "claude-prompt-cache",
+      );
+
+      expect(capture1.addDir).toBeTruthy();
+      expect(capture1.addDir).toBe(capture2.addDir);
+      expect(capture1.instructionsFilePath).toBeTruthy();
+      expect(capture2.instructionsFilePath ?? null).toBeNull();
+      expect(capture1.addDir?.startsWith(expectedRoot)).toBe(true);
+      expect(capture1.instructionsFilePath?.startsWith(expectedRoot)).toBe(true);
+      expect(capture1.instructionsContents).toContain("You are managed instructions.");
+      expect(capture1.instructionsContents).toContain(`The above agent instructions were loaded from ${instructionsPath}.`);
+      expect(capture1.skillEntries).toContain("paperclip");
+      expect(capture2.argv).toContain("--resume");
+      expect(capture2.argv).toContain("claude-session-1");
+      expect(capture2.prompt).toContain("## Paperclip Resume Delta");
+      expect(capture2.prompt).not.toContain("Follow the paperclip heartbeat.");
+    } finally {
+      if (previousHome === undefined) delete process.env.HOME;
+      else process.env.HOME = previousHome;
+      if (previousPaperclipHome === undefined) delete process.env.PAPERCLIP_HOME;
+      else process.env.PAPERCLIP_HOME = previousPaperclipHome;
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it("starts a fresh Claude session when the stable prompt bundle changes", async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-claude-execute-reset-"));
+    const workspace = path.join(root, "workspace");
+    const commandPath = path.join(root, "claude");
+    const capturePath1 = path.join(root, "capture-before.json");
+    const capturePath2 = path.join(root, "capture-after.json");
+    const instructionsPath = path.join(root, "AGENTS.md");
+    const paperclipHome = path.join(root, "paperclip-home");
+    const logs: string[] = [];
+    await fs.mkdir(workspace, { recursive: true });
+    await fs.writeFile(instructionsPath, "Version one instructions.\n", "utf8");
+    await writeFakeClaudeCommand(commandPath);
+
+    const previousHome = process.env.HOME;
+    const previousPaperclipHome = process.env.PAPERCLIP_HOME;
+    process.env.HOME = root;
+    process.env.PAPERCLIP_HOME = paperclipHome;
+
+    try {
+      const first = await execute({
+        runId: "run-before",
+        agent: {
+          id: "agent-1",
+          companyId: "company-1",
+          name: "Claude Coder",
+          adapterType: "claude_local",
+          adapterConfig: {},
+        },
+        runtime: {
+          sessionId: null,
+          sessionParams: null,
+          sessionDisplayId: null,
+          taskKey: null,
+        },
+        config: {
+          command: commandPath,
+          cwd: workspace,
+          instructionsFilePath: instructionsPath,
+          env: {
+            PAPERCLIP_TEST_CAPTURE_PATH: capturePath1,
+          },
+          promptTemplate: "Follow the paperclip heartbeat.",
+        },
+        context: {},
+        authToken: "run-jwt-token",
+        onLog: async () => {},
+      });
+
+      await fs.writeFile(instructionsPath, "Version two instructions.\n", "utf8");
+
+      const second = await execute({
+        runId: "run-after",
+        agent: {
+          id: "agent-1",
+          companyId: "company-1",
+          name: "Claude Coder",
+          adapterType: "claude_local",
+          adapterConfig: {},
+        },
+        runtime: {
+          sessionId: null,
+          sessionParams: first.sessionParams ?? null,
+          sessionDisplayId: null,
+          taskKey: null,
+        },
+        config: {
+          command: commandPath,
+          cwd: workspace,
+          instructionsFilePath: instructionsPath,
+          env: {
+            PAPERCLIP_TEST_CAPTURE_PATH: capturePath2,
+          },
+          promptTemplate: "Follow the paperclip heartbeat.",
+        },
+        context: {},
+        authToken: "run-jwt-token",
+        onLog: async (_stream, chunk) => {
+          logs.push(chunk);
+        },
+      });
+
+      expect(first.exitCode).toBe(0);
+      expect(second.exitCode).toBe(0);
+      expect(second.errorMessage).toBeNull();
+
+      const before = JSON.parse(await fs.readFile(capturePath1, "utf8")) as CapturePayload;
+      const after = JSON.parse(await fs.readFile(capturePath2, "utf8")) as CapturePayload;
+
+      expect(before.instructionsFilePath).not.toBe(after.instructionsFilePath);
+      expect(after.argv).not.toContain("--resume");
+      expect(after.prompt).toContain("Follow the paperclip heartbeat.");
+      expect(logs.join("")).toContain("will not be resumed with");
+    } finally {
+      if (previousHome === undefined) delete process.env.HOME;
+      else process.env.HOME = previousHome;
+      if (previousPaperclipHome === undefined) delete process.env.PAPERCLIP_HOME;
+      else process.env.PAPERCLIP_HOME = previousPaperclipHome;
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  }, 15_000);
 });

server/src/__tests__/cli-auth-routes.test.ts

@@ -1,6 +1,8 @@
 import express from "express";
 import request from "supertest";
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import { accessRoutes } from "../routes/access.js";
+import { errorHandler } from "../middleware/index.js";
 
 const mockAccessService = vi.hoisted(() => ({
   isInstanceAdmin: vi.fn(),
@@ -25,16 +27,14 @@ const mockBoardAuthService = vi.hoisted(() => ({
 
 const mockLogActivity = vi.hoisted(() => vi.fn());
 
-function registerServiceMocks() {
-  vi.doMock("../services/index.js", () => ({
-    accessService: () => mockAccessService,
-    agentService: () => mockAgentService,
-    boardAuthService: () => mockBoardAuthService,
-    logActivity: mockLogActivity,
-    notifyHireApproved: vi.fn(),
-    deduplicateAgentName: vi.fn((name: string) => name),
-  }));
-}
+vi.mock("../services/index.js", () => ({
+  accessService: () => mockAccessService,
+  agentService: () => mockAgentService,
+  boardAuthService: () => mockBoardAuthService,
+  logActivity: mockLogActivity,
+  notifyHireApproved: vi.fn(),
+  deduplicateAgentName: vi.fn((name: string) => name),
+}));
 
 function createApp(actor: any) {
   const app = express();
@@ -43,28 +43,22 @@ function createApp(actor: any) {
     req.actor = actor;
     next();
   });
-  return import("../routes/access.js").then(({ accessRoutes }) =>
-    import("../middleware/index.js").then(({ errorHandler }) => {
-      app.use(
-        "/api",
-        accessRoutes({} as any, {
-          deploymentMode: "authenticated",
-          deploymentExposure: "private",
-          bindHost: "127.0.0.1",
-          allowedHostnames: [],
-        }),
-      );
-      app.use(errorHandler);
-      return app;
-    })
+  app.use(
+    "/api",
+    accessRoutes({} as any, {
+      deploymentMode: "authenticated",
+      deploymentExposure: "private",
+      bindHost: "127.0.0.1",
+      allowedHostnames: [],
+    }),
   );
+  app.use(errorHandler);
+  return app;
 }
 
 describe("cli auth routes", () => {
   beforeEach(() => {
-    vi.resetModules();
-    registerServiceMocks();
-    vi.clearAllMocks();
+    vi.resetAllMocks();
   });
 
   it("creates a CLI auth challenge with approval metadata", async () => {
@@ -77,7 +71,7 @@ describe("cli auth routes", () => {
       pendingBoardToken: "pcp_board_token",
     });
 
-    const app = await createApp({ type: "none", source: "none" });
+    const app = createApp({ type: "none", source: "none" });
     const res = await request(app)
       .post("/api/cli-auth/challenges")
       .send({
@@ -113,7 +107,7 @@ describe("cli auth routes", () => {
       approvedByUser: null,
     });
 
-    const app = await createApp({ type: "none", source: "none" });
+    const app = createApp({ type: "none", source: "none" });
     const res = await request(app).get("/api/cli-auth/challenges/challenge-1?token=pcp_cli_auth_secret");
 
     expect(res.status).toBe(200);
@@ -139,7 +133,7 @@ describe("cli auth routes", () => {
     });
     mockBoardAuthService.resolveBoardActivityCompanyIds.mockResolvedValue(["company-1"]);
 
-    const app = await createApp({
+    const app = createApp({
       type: "board",
       userId: "user-1",
       source: "session",
@@ -179,7 +173,7 @@ describe("cli auth routes", () => {
     });
     mockBoardAuthService.resolveBoardActivityCompanyIds.mockResolvedValue(["company-a", "company-b"]);
 
-    const app = await createApp({
+    const app = createApp({
       type: "board",
       userId: "admin-1",
       source: "session",
@@ -206,7 +200,7 @@ describe("cli auth routes", () => {
     });
     mockBoardAuthService.resolveBoardActivityCompanyIds.mockResolvedValue(["company-z"]);
 
-    const app = await createApp({
+    const app = createApp({
       type: "board",
       userId: "admin-2",
       keyId: "board-key-3",

server/src/__tests__/company-branding-route.test.ts

@@ -39,17 +39,15 @@ const mockFeedbackService = vi.hoisted(() => ({
   saveIssueVote: vi.fn(),
 }));
 
-function registerServiceMocks() {
-  vi.doMock("../services/index.js", () => ({
-    accessService: () => mockAccessService,
-    agentService: () => mockAgentService,
-    budgetService: () => mockBudgetService,
-    companyPortabilityService: () => mockCompanyPortabilityService,
-    companyService: () => mockCompanyService,
-    feedbackService: () => mockFeedbackService,
-    logActivity: mockLogActivity,
-  }));
-}
+vi.mock("../services/index.js", () => ({
+  accessService: () => mockAccessService,
+  agentService: () => mockAgentService,
+  budgetService: () => mockBudgetService,
+  companyPortabilityService: () => mockCompanyPortabilityService,
+  companyService: () => mockCompanyService,
+  feedbackService: () => mockFeedbackService,
+  logActivity: mockLogActivity,
+}));
 
 function createCompany() {
   const now = new Date("2026-03-19T02:00:00.000Z");
@@ -90,7 +88,6 @@ async function createApp(actor: Record<string, unknown>) {
 describe("PATCH /api/companies/:companyId/branding", () => {
   beforeEach(() => {
     vi.resetModules();
-    registerServiceMocks();
     vi.resetAllMocks();
   });
 

server/src/__tests__/company-portability-routes.test.ts

@@ -175,4 +175,50 @@ describe("company portability routes", () => {
     expect(res.status).toBe(403);
     expect(res.body.error).toContain("Board access required");
   });
+
+  it("requires instance admin for new-company import preview", async () => {
+    const app = await createApp({
+      type: "board",
+      userId: "user-1",
+      companyIds: ["11111111-1111-4111-8111-111111111111"],
+      source: "session",
+      isInstanceAdmin: false,
+    });
+
+    const res = await request(app)
+      .post("/api/companies/import/preview")
+      .send({
+        source: { type: "inline", files: { "COMPANY.md": "---\nname: Test\n---\n" } },
+        include: { company: true, agents: true, projects: false, issues: false },
+        target: { mode: "new_company", newCompanyName: "Imported Test" },
+        collisionStrategy: "rename",
+      });
+
+    expect(res.status).toBe(403);
+    expect(res.body.error).toContain("Instance admin");
+    expect(mockCompanyPortabilityService.previewImport).not.toHaveBeenCalled();
+  });
+
+  it("requires instance admin for new-company import apply", async () => {
+    const app = await createApp({
+      type: "board",
+      userId: "user-1",
+      companyIds: ["11111111-1111-4111-8111-111111111111"],
+      source: "session",
+      isInstanceAdmin: false,
+    });
+
+    const res = await request(app)
+      .post("/api/companies/import")
+      .send({
+        source: { type: "inline", files: { "COMPANY.md": "---\nname: Test\n---\n" } },
+        include: { company: true, agents: true, projects: false, issues: false },
+        target: { mode: "new_company", newCompanyName: "Imported Test" },
+        collisionStrategy: "rename",
+      });
+
+    expect(res.status).toBe(403);
+    expect(res.body.error).toContain("Instance admin");
+    expect(mockCompanyPortabilityService.importBundle).not.toHaveBeenCalled();
+  });
 });

server/src/__tests__/company-skills-routes.test.ts

@@ -20,23 +20,21 @@ const mockLogActivity = vi.hoisted(() => vi.fn());
 const mockTrackSkillImported = vi.hoisted(() => vi.fn());
 const mockGetTelemetryClient = vi.hoisted(() => vi.fn());
 
-function registerRouteMocks() {
-  vi.doMock("@paperclipai/shared/telemetry", () => ({
-    trackSkillImported: mockTrackSkillImported,
-    trackErrorHandlerCrash: vi.fn(),
-  }));
+vi.mock("@paperclipai/shared/telemetry", () => ({
+  trackSkillImported: mockTrackSkillImported,
+  trackErrorHandlerCrash: vi.fn(),
+}));
 
-  vi.doMock("../telemetry.js", () => ({
-    getTelemetryClient: mockGetTelemetryClient,
-  }));
+vi.mock("../telemetry.js", () => ({
+  getTelemetryClient: mockGetTelemetryClient,
+}));
 
-  vi.doMock("../services/index.js", () => ({
-    accessService: () => mockAccessService,
-    agentService: () => mockAgentService,
-    companySkillService: () => mockCompanySkillService,
-    logActivity: mockLogActivity,
-  }));
-}
+vi.mock("../services/index.js", () => ({
+  accessService: () => mockAccessService,
+  agentService: () => mockAgentService,
+  companySkillService: () => mockCompanySkillService,
+  logActivity: mockLogActivity,
+}));
 
 async function createApp(actor: Record<string, unknown>) {
   const [{ companySkillRoutes }, { errorHandler }] = await Promise.all([
@@ -57,8 +55,7 @@ async function createApp(actor: Record<string, unknown>) {
 describe("company skill mutation permissions", () => {
   beforeEach(() => {
     vi.resetModules();
-    registerRouteMocks();
-    vi.clearAllMocks();
+    vi.resetAllMocks();
     mockGetTelemetryClient.mockReturnValue({ track: vi.fn() });
     mockCompanySkillService.importFromSource.mockResolvedValue({
       imported: [],

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

@@ -71,21 +71,19 @@ const mockBudgetService = vi.hoisted(() => ({
   resolveIncident: vi.fn(),
 }));
 
-function registerRouteMocks() {
-  vi.doMock("../services/index.js", () => ({
-    budgetService: () => mockBudgetService,
-    costService: () => mockCostService,
-    financeService: () => mockFinanceService,
-    companyService: () => mockCompanyService,
-    agentService: () => mockAgentService,
-    heartbeatService: () => mockHeartbeatService,
-    logActivity: mockLogActivity,
-  }));
+vi.mock("../services/index.js", () => ({
+  budgetService: () => mockBudgetService,
+  costService: () => mockCostService,
+  financeService: () => mockFinanceService,
+  companyService: () => mockCompanyService,
+  agentService: () => mockAgentService,
+  heartbeatService: () => mockHeartbeatService,
+  logActivity: mockLogActivity,
+}));
 
-  vi.doMock("../services/quota-windows.js", () => ({
-    fetchAllQuotaWindows: mockFetchAllQuotaWindows,
-  }));
-}
+vi.mock("../services/quota-windows.js", () => ({
+  fetchAllQuotaWindows: mockFetchAllQuotaWindows,
+}));
 
 async function createApp() {
   const [{ costRoutes }, { errorHandler }] = await Promise.all([
@@ -119,10 +117,14 @@ async function createAppWithActor(actor: any) {
   return app;
 }
 
+async function loadCostParsers() {
+  const { parseCostDateRange, parseCostLimit } = await import("../routes/costs.js");
+  return { parseCostDateRange, parseCostLimit };
+}
+
 beforeEach(() => {
   vi.resetModules();
-  registerRouteMocks();
-  vi.clearAllMocks();
+  vi.resetAllMocks();
   mockCompanyService.update.mockResolvedValue({
     id: "company-1",
     name: "Paperclip",
@@ -140,30 +142,25 @@ beforeEach(() => {
 });
 
 describe("cost routes", () => {
-  it("accepts valid ISO date strings and passes them to cost summary routes", async () => {
-    const app = await createApp();
-    const res = await request(app)
-      .get("/api/companies/company-1/costs/summary")
-      .query({ from: "2026-01-01T00:00:00.000Z", to: "2026-01-31T23:59:59.999Z" });
-    expect(res.status).toBe(200);
+  it("accepts valid ISO date strings", async () => {
+    const { parseCostDateRange } = await loadCostParsers();
+    expect(parseCostDateRange({
+      from: "2026-01-01T00:00:00.000Z",
+      to: "2026-01-31T23:59:59.999Z",
+    })).toEqual({
+      from: new Date("2026-01-01T00:00:00.000Z"),
+      to: new Date("2026-01-31T23:59:59.999Z"),
+    });
   });
 
   it("returns 400 for an invalid 'from' date string", async () => {
-    const app = await createApp();
-    const res = await request(app)
-      .get("/api/companies/company-1/costs/summary")
-      .query({ from: "not-a-date" });
-    expect(res.status).toBe(400);
-    expect(res.body.error).toMatch(/invalid 'from' date/i);
+    const { parseCostDateRange } = await loadCostParsers();
+    expect(() => parseCostDateRange({ from: "not-a-date" })).toThrow(/invalid 'from' date/i);
   });
 
   it("returns 400 for an invalid 'to' date string", async () => {
-    const app = await createApp();
-    const res = await request(app)
-      .get("/api/companies/company-1/costs/summary")
-      .query({ to: "banana" });
-    expect(res.status).toBe(400);
-    expect(res.body.error).toMatch(/invalid 'to' date/i);
+    const { parseCostDateRange } = await loadCostParsers();
+    expect(() => parseCostDateRange({ to: "banana" })).toThrow(/invalid 'to' date/i);
   });
 
   it("returns finance summary rows for valid requests", async () => {
@@ -176,21 +173,13 @@ describe("cost routes", () => {
   });
 
   it("returns 400 for invalid finance event list limits", async () => {
-    const app = await createApp();
-    const res = await request(app)
-      .get("/api/companies/company-1/costs/finance-events")
-      .query({ limit: "0" });
-    expect(res.status).toBe(400);
-    expect(res.body.error).toMatch(/invalid 'limit'/i);
+    const { parseCostLimit } = await loadCostParsers();
+    expect(() => parseCostLimit({ limit: "0" })).toThrow(/invalid 'limit'/i);
   });
 
   it("accepts valid finance event list limits", async () => {
-    const app = await createApp();
-    const res = await request(app)
-      .get("/api/companies/company-1/costs/finance-events")
-      .query({ limit: "25" });
-    expect(res.status).toBe(200);
-    expect(mockFinanceService.list).toHaveBeenCalledWith("company-1", undefined, 25);
+    const { parseCostLimit } = await loadCostParsers();
+    expect(parseCostLimit({ limit: "25" })).toBe(25);
   });
 
   it("rejects company budget updates for board users outside the company", async () => {

server/src/__tests__/dev-runner-worktree.test.ts

@@ -0,0 +1,75 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  bootstrapDevRunnerWorktreeEnv,
+  isLinkedGitWorktreeCheckout,
+  resolveWorktreeEnvFilePath,
+} from "../dev-runner-worktree.ts";
+
+const tempRoots = new Set<string>();
+
+afterEach(() => {
+  for (const root of tempRoots) {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+  tempRoots.clear();
+});
+
+function createTempRoot(prefix: string): string {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+  tempRoots.add(root);
+  return root;
+}
+
+describe("dev-runner worktree env bootstrap", () => {
+  it("detects linked git worktrees from .git files", () => {
+    const root = createTempRoot("paperclip-dev-runner-worktree-");
+    fs.writeFileSync(path.join(root, ".git"), "gitdir: /tmp/paperclip/.git/worktrees/feature\n", "utf8");
+
+    expect(isLinkedGitWorktreeCheckout(root)).toBe(true);
+  });
+
+  it("loads repo-local Paperclip env for initialized worktrees without overriding explicit env", () => {
+    const root = createTempRoot("paperclip-dev-runner-worktree-env-");
+    fs.mkdirSync(path.join(root, ".paperclip"), { recursive: true });
+    fs.writeFileSync(path.join(root, ".git"), "gitdir: /tmp/paperclip/.git/worktrees/feature\n", "utf8");
+    fs.writeFileSync(
+      resolveWorktreeEnvFilePath(root),
+      [
+        "PAPERCLIP_HOME=/tmp/paperclip-worktrees",
+        "PAPERCLIP_INSTANCE_ID=feature-worktree",
+        "PAPERCLIP_IN_WORKTREE=true",
+        "PAPERCLIP_WORKTREE_NAME=feature-worktree",
+        "PAPERCLIP_OPTIONAL= # comment-only value",
+        "",
+      ].join("\n"),
+      "utf8",
+    );
+
+    const env: NodeJS.ProcessEnv = {
+      PAPERCLIP_INSTANCE_ID: "already-set",
+    };
+    const result = bootstrapDevRunnerWorktreeEnv(root, env);
+
+    expect(result).toEqual({
+      envPath: resolveWorktreeEnvFilePath(root),
+      missingEnv: false,
+    });
+    expect(env.PAPERCLIP_HOME).toBe("/tmp/paperclip-worktrees");
+    expect(env.PAPERCLIP_INSTANCE_ID).toBe("already-set");
+    expect(env.PAPERCLIP_IN_WORKTREE).toBe("true");
+    expect(env.PAPERCLIP_OPTIONAL).toBe("");
+  });
+
+  it("reports uninitialized linked worktrees so dev runner can fail fast", () => {
+    const root = createTempRoot("paperclip-dev-runner-worktree-missing-");
+    fs.writeFileSync(path.join(root, ".git"), "gitdir: /tmp/paperclip/.git/worktrees/feature\n", "utf8");
+
+    expect(bootstrapDevRunnerWorktreeEnv(root, {})).toEqual({
+      envPath: resolveWorktreeEnvFilePath(root),
+      missingEnv: true,
+    });
+  });
+});

server/src/__tests__/heartbeat-list.test.ts

@@ -0,0 +1,91 @@
+import { randomUUID } from "node:crypto";
+import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
+import { agents, companies, createDb, heartbeatRuns } from "@paperclipai/db";
+import {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+} from "./helpers/embedded-postgres.js";
+import { heartbeatService } from "../services/heartbeat.ts";
+
+const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
+
+if (!embeddedPostgresSupport.supported) {
+  console.warn(
+    `Skipping embedded Postgres heartbeat list tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,
+  );
+}
+
+describeEmbeddedPostgres("heartbeat list", () => {
+  let db!: ReturnType<typeof createDb>;
+  let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
+
+  beforeAll(async () => {
+    tempDb = await startEmbeddedPostgresTestDatabase("paperclip-heartbeat-list-");
+    db = createDb(tempDb.connectionString);
+  }, 20_000);
+
+  afterEach(async () => {
+    await db.delete(heartbeatRuns);
+    await db.delete(agents);
+    await db.delete(companies);
+  });
+
+  afterAll(async () => {
+    await tempDb?.cleanup();
+  });
+
+  it("returns runs even when the linked db schema lacks processGroupId", async () => {
+    const companyId = randomUUID();
+    const agentId = randomUUID();
+    const runId = randomUUID();
+
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Paperclip",
+      issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+      requireBoardApprovalForNewAgents: false,
+    });
+
+    await db.insert(agents).values({
+      id: agentId,
+      companyId,
+      name: "CodexCoder",
+      role: "engineer",
+      status: "running",
+      adapterType: "codex_local",
+      adapterConfig: {},
+      runtimeConfig: {},
+      permissions: {},
+    });
+
+    await db.insert(heartbeatRuns).values({
+      id: runId,
+      companyId,
+      agentId,
+      invocationSource: "assignment",
+      status: "running",
+      contextSnapshot: { issueId: randomUUID() },
+    });
+
+    const originalDescriptor = Object.getOwnPropertyDescriptor(heartbeatRuns, "processGroupId");
+    Object.defineProperty(heartbeatRuns, "processGroupId", {
+      value: undefined,
+      configurable: true,
+      writable: true,
+    });
+
+    try {
+      const runs = await heartbeatService(db).list(companyId, agentId, 5);
+      expect(runs).toHaveLength(1);
+      expect(runs[0]?.id).toBe(runId);
+      expect(runs[0]?.processGroupId ?? null).toBeNull();
+    } finally {
+      if (originalDescriptor) {
+        Object.defineProperty(heartbeatRuns, "processGroupId", originalDescriptor);
+      } else {
+        delete (heartbeatRuns as Record<string, unknown>).processGroupId;
+      }
+    }
+  });
+});

server/src/__tests__/heartbeat-process-recovery.test.ts

@@ -49,10 +49,70 @@ function spawnAliveProcess() {
   });
 }
 
+function isPidAlive(pid: number | null | undefined) {
+  if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function waitForPidExit(pid: number, timeoutMs = 2_000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!isPidAlive(pid)) return true;
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+  return !isPidAlive(pid);
+}
+
+async function spawnOrphanedProcessGroup() {
+  const leader = spawn(
+    process.execPath,
+    [
+      "-e",
+      [
+        "const { spawn } = require('node:child_process');",
+        "const child = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)'], { stdio: 'ignore' });",
+        "process.stdout.write(String(child.pid));",
+        "setTimeout(() => process.exit(0), 25);",
+      ].join(" "),
+    ],
+    {
+      detached: true,
+      stdio: ["ignore", "pipe", "ignore"],
+    },
+  );
+
+  let stdout = "";
+  leader.stdout?.on("data", (chunk) => {
+    stdout += String(chunk);
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    leader.once("error", reject);
+    leader.once("exit", () => resolve());
+  });
+
+  const descendantPid = Number.parseInt(stdout.trim(), 10);
+  if (!Number.isInteger(descendantPid) || descendantPid <= 0) {
+    throw new Error(`Failed to capture orphaned descendant pid from detached process group: ${stdout}`);
+  }
+
+  return {
+    processPid: leader.pid ?? null,
+    processGroupId: leader.pid ?? null,
+    descendantPid,
+  };
+}
+
 describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {
   let db!: ReturnType<typeof createDb>;
   let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
   const childProcesses = new Set<ChildProcess>();
+  const cleanupPids = new Set<number>();
 
   beforeAll(async () => {
     tempDb = await startEmbeddedPostgresTestDatabase("paperclip-heartbeat-recovery-");
@@ -66,6 +126,14 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {
       child.kill("SIGKILL");
     }
     childProcesses.clear();
+    for (const pid of cleanupPids) {
+      try {
+        process.kill(pid, "SIGKILL");
+      } catch {
+        // Ignore already-dead cleanup targets.
+      }
+    }
+    cleanupPids.clear();
     await db.delete(issues);
     await db.delete(heartbeatRunEvents);
     await db.delete(heartbeatRuns);
@@ -79,6 +147,14 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {
       child.kill("SIGKILL");
     }
     childProcesses.clear();
+    for (const pid of cleanupPids) {
+      try {
+        process.kill(pid, "SIGKILL");
+      } catch {
+        // Ignore already-dead cleanup targets.
+      }
+    }
+    cleanupPids.clear();
     runningProcesses.clear();
     await tempDb?.cleanup();
   });
@@ -88,6 +164,7 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {
     agentStatus?: "paused" | "idle" | "running";
     runStatus?: "running" | "queued" | "failed";
     processPid?: number | null;
+    processGroupId?: number | null;
     processLossRetryCount?: number;
     includeIssue?: boolean;
     runErrorCode?: string | null;
@@ -143,6 +220,7 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {
       wakeupRequestId,
       contextSnapshot: input?.includeIssue === false ? {} : { issueId },
       processPid: input?.processPid ?? null,
+      processGroupId: input?.processGroupId ?? null,
       processLossRetryCount: input?.processLossRetryCount ?? 0,
       errorCode: input?.runErrorCode ?? null,
       error: input?.runError ?? null,
@@ -228,6 +306,45 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {
     expect(issue?.checkoutRunId).toBe(runId);
   });
 
+  it.skipIf(process.platform === "win32")("reaps orphaned descendant process groups when the parent pid is already gone", async () => {
+    const orphan = await spawnOrphanedProcessGroup();
+    cleanupPids.add(orphan.descendantPid);
+    expect(isPidAlive(orphan.descendantPid)).toBe(true);
+
+    const { agentId, runId, issueId } = await seedRunFixture({
+      processPid: orphan.processPid,
+      processGroupId: orphan.processGroupId,
+    });
+    const heartbeat = heartbeatService(db);
+
+    const result = await heartbeat.reapOrphanedRuns();
+    expect(result.reaped).toBe(1);
+    expect(result.runIds).toEqual([runId]);
+
+    expect(await waitForPidExit(orphan.descendantPid, 2_000)).toBe(true);
+
+    const runs = await db
+      .select()
+      .from(heartbeatRuns)
+      .where(eq(heartbeatRuns.agentId, agentId));
+    expect(runs).toHaveLength(2);
+
+    const failedRun = runs.find((row) => row.id === runId);
+    expect(failedRun?.status).toBe("failed");
+    expect(failedRun?.errorCode).toBe("process_lost");
+    expect(failedRun?.error).toContain("descendant process group");
+
+    const retryRun = runs.find((row) => row.id !== runId);
+    expect(retryRun?.status).toBe("queued");
+
+    const issue = await db
+      .select()
+      .from(issues)
+      .where(eq(issues.id, issueId))
+      .then((rows) => rows[0] ?? null);
+    expect(issue?.executionRunId).toBe(retryRun?.id ?? null);
+  });
+
   it("does not queue a second retry after the first process-loss retry was already used", async () => {
     const { agentId, runId, issueId } = await seedRunFixture({
       processPid: 999_999_999,

server/src/__tests__/heartbeat-run-summary.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from "vitest";
 import {
   summarizeHeartbeatRunResultJson,
   buildHeartbeatRunIssueComment,
+  mergeHeartbeatRunResultJson,
 } from "../services/heartbeat-run-summary.js";
 
 describe("summarizeHeartbeatRunResultJson", () => {
@@ -55,3 +56,35 @@ describe("buildHeartbeatRunIssueComment", () => {
     expect(buildHeartbeatRunIssueComment({ costUsd: 1.2 })).toBeNull();
   });
 });
+
+describe("mergeHeartbeatRunResultJson", () => {
+  it("adds adapter summaries into stored result json for comment posting", () => {
+    const merged = mergeHeartbeatRunResultJson(
+      { stdout: "raw stdout", stderr: "" },
+      "## Summary\n\n1. first thing\n2. second thing",
+    );
+
+    expect(merged).toEqual({
+      stdout: "raw stdout",
+      stderr: "",
+      summary: "## Summary\n\n1. first thing\n2. second thing",
+    });
+    expect(buildHeartbeatRunIssueComment(merged)).toBe("## Summary\n\n1. first thing\n2. second thing");
+  });
+
+  it("creates a result payload when only a summary exists", () => {
+    expect(mergeHeartbeatRunResultJson(null, "done")).toEqual({ summary: "done" });
+  });
+
+  it("does not overwrite an explicit summary already returned by the adapter", () => {
+    expect(
+      mergeHeartbeatRunResultJson(
+        { summary: "adapter result", stdout: "raw stdout" },
+        "fallback summary",
+      ),
+    ).toEqual({
+      summary: "adapter result",
+      stdout: "raw stdout",
+    });
+  });
+});

server/src/__tests__/instance-settings-routes.test.ts

@@ -11,12 +11,10 @@ const mockInstanceSettingsService = vi.hoisted(() => ({
 }));
 const mockLogActivity = vi.hoisted(() => vi.fn());
 
-function registerRouteMocks() {
-  vi.doMock("../services/index.js", () => ({
-    instanceSettingsService: () => mockInstanceSettingsService,
-    logActivity: mockLogActivity,
-  }));
-}
+vi.mock("../services/index.js", () => ({
+  instanceSettingsService: () => mockInstanceSettingsService,
+  logActivity: mockLogActivity,
+}));
 
 async function createApp(actor: any) {
   const [{ instanceSettingsRoutes }, { errorHandler }] = await Promise.all([
@@ -37,8 +35,7 @@ async function createApp(actor: any) {
 describe("instance settings routes", () => {
   beforeEach(() => {
     vi.resetModules();
-    registerRouteMocks();
-    vi.clearAllMocks();
+    vi.resetAllMocks();
     mockInstanceSettingsService.getGeneral.mockResolvedValue({
       censorUsernameInLogs: false,
       keyboardShortcuts: false,

server/src/__tests__/issue-activity-events-routes.test.ts

@@ -1,8 +1,8 @@
 import express from "express";
 import request from "supertest";
 import { beforeEach, describe, expect, it, vi } from "vitest";
-import { errorHandler } from "../middleware/index.js";
 import { issueRoutes } from "../routes/issues.js";
+import { errorHandler } from "../middleware/index.js";
 import { normalizeIssueExecutionPolicy } from "../services/issue-execution-policy.ts";
 
 const mockIssueService = vi.hoisted(() => ({
@@ -170,7 +170,7 @@ describe("issue activity event routes", () => {
         }),
       }),
     );
-  });
+  }, 15_000);
 
   it("logs explicit reviewer and approver activity when execution policy participants change", async () => {
     const existingPolicy = normalizeIssueExecutionPolicy({

server/src/__tests__/issue-comment-reopen-routes.test.ts

@@ -38,48 +38,49 @@ const mockTx = vi.hoisted(() => ({
 const mockDb = vi.hoisted(() => ({
   transaction: vi.fn(async (fn: (tx: typeof mockTx) => Promise<unknown>) => fn(mockTx)),
 }));
+const mockFeedbackService = vi.hoisted(() => ({
+  listIssueVotesForUser: vi.fn(async () => []),
+  saveIssueVote: vi.fn(async () => ({ vote: null, consentEnabledNow: false, sharingEnabled: false })),
+}));
+const mockInstanceSettingsService = vi.hoisted(() => ({
+  get: vi.fn(async () => ({
+    id: "instance-settings-1",
+    general: {
+      censorUsernameInLogs: false,
+      feedbackDataSharingPreference: "prompt",
+    },
+  })),
+  listCompanyIds: vi.fn(async () => ["company-1"]),
+}));
+const mockRoutineService = vi.hoisted(() => ({
+  syncRunStatusForIssue: vi.fn(async () => undefined),
+}));
 
-function registerServiceMocks() {
-  vi.doMock("@paperclipai/shared/telemetry", () => ({
-    trackAgentTaskCompleted: vi.fn(),
-    trackErrorHandlerCrash: vi.fn(),
-  }));
+vi.mock("@paperclipai/shared/telemetry", () => ({
+  trackAgentTaskCompleted: vi.fn(),
+  trackErrorHandlerCrash: vi.fn(),
+}));
 
-  vi.doMock("../telemetry.js", () => ({
-    getTelemetryClient: vi.fn(() => ({ track: vi.fn() })),
-  }));
+vi.mock("../telemetry.js", () => ({
+  getTelemetryClient: vi.fn(() => ({ track: vi.fn() })),
+}));
 
-  vi.doMock("../services/index.js", () => ({
-    accessService: () => mockAccessService,
-    agentService: () => mockAgentService,
-    documentService: () => ({}),
-    executionWorkspaceService: () => ({}),
-    feedbackService: () => ({
-      listIssueVotesForUser: vi.fn(async () => []),
-      saveIssueVote: vi.fn(async () => ({ vote: null, consentEnabledNow: false, sharingEnabled: false })),
-    }),
-    goalService: () => ({}),
-    heartbeatService: () => mockHeartbeatService,
-    instanceSettingsService: () => ({
-      get: vi.fn(async () => ({
-        id: "instance-settings-1",
-        general: {
-          censorUsernameInLogs: false,
-          feedbackDataSharingPreference: "prompt",
-        },
-      })),
-      listCompanyIds: vi.fn(async () => ["company-1"]),
-    }),
-    issueApprovalService: () => ({}),
-    issueService: () => mockIssueService,
-    logActivity: mockLogActivity,
-    projectService: () => ({}),
-    routineService: () => ({
-      syncRunStatusForIssue: vi.fn(async () => undefined),
-    }),
-    workProductService: () => ({}),
-  }));
-}
+vi.mock("../services/index.js", () => ({
+  accessService: () => mockAccessService,
+  agentService: () => mockAgentService,
+  documentService: () => ({}),
+  executionWorkspaceService: () => ({}),
+  feedbackService: () => mockFeedbackService,
+  goalService: () => ({}),
+  heartbeatService: () => mockHeartbeatService,
+  instanceSettingsService: () => mockInstanceSettingsService,
+  issueApprovalService: () => ({}),
+  issueService: () => mockIssueService,
+  logActivity: mockLogActivity,
+  projectService: () => ({}),
+  routineService: () => mockRoutineService,
+  workProductService: () => ({}),
+}));
 
 function createApp() {
   const app = express();
@@ -134,7 +135,7 @@ function makeIssue(status: "todo" | "done") {
 describe("issue comment reopen routes", () => {
   beforeEach(() => {
     vi.resetModules();
-    registerServiceMocks();
+    vi.resetAllMocks();
     mockIssueService.getById.mockReset();
     mockIssueService.assertCheckoutOwner.mockReset();
     mockIssueService.update.mockReset();
@@ -151,6 +152,11 @@ describe("issue comment reopen routes", () => {
     mockHeartbeatService.cancelRun.mockReset();
     mockAgentService.getById.mockReset();
     mockLogActivity.mockReset();
+    mockFeedbackService.listIssueVotesForUser.mockReset();
+    mockFeedbackService.saveIssueVote.mockReset();
+    mockInstanceSettingsService.get.mockReset();
+    mockInstanceSettingsService.listCompanyIds.mockReset();
+    mockRoutineService.syncRunStatusForIssue.mockReset();
     mockTxInsertValues.mockReset();
     mockTxInsert.mockReset();
     mockDb.transaction.mockReset();
@@ -163,6 +169,21 @@ describe("issue comment reopen routes", () => {
     mockHeartbeatService.getActiveRunForAgent.mockResolvedValue(null);
     mockHeartbeatService.cancelRun.mockResolvedValue(null);
     mockLogActivity.mockResolvedValue(undefined);
+    mockFeedbackService.listIssueVotesForUser.mockResolvedValue([]);
+    mockFeedbackService.saveIssueVote.mockResolvedValue({
+      vote: null,
+      consentEnabledNow: false,
+      sharingEnabled: false,
+    });
+    mockInstanceSettingsService.get.mockResolvedValue({
+      id: "instance-settings-1",
+      general: {
+        censorUsernameInLogs: false,
+        feedbackDataSharingPreference: "prompt",
+      },
+    });
+    mockInstanceSettingsService.listCompanyIds.mockResolvedValue(["company-1"]);
+    mockRoutineService.syncRunStatusForIssue.mockResolvedValue(undefined);
     mockIssueService.addComment.mockResolvedValue({
       id: "comment-1",
       issueId: "11111111-1111-4111-8111-111111111111",

server/src/__tests__/issue-document-restore-routes.test.ts

@@ -1,6 +1,8 @@
 import express from "express";
 import request from "supertest";
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import { issueRoutes } from "../routes/issues.js";
+import { errorHandler } from "../middleware/index.js";
 
 const issueId = "11111111-1111-4111-8111-111111111111";
 const companyId = "22222222-2222-4222-8222-222222222222";
@@ -50,11 +52,7 @@ vi.mock("../services/index.js", () => ({
   workProductService: () => ({}),
 }));
 
-async function createApp() {
-  const [{ issueRoutes }, { errorHandler }] = await Promise.all([
-    import("../routes/issues.js"),
-    import("../middleware/index.js"),
-  ]);
+function createApp() {
   const app = express();
   app.use(express.json());
   app.use((req, _res, next) => {
@@ -74,7 +72,6 @@ async function createApp() {
 
 describe("issue document revision routes", () => {
   beforeEach(() => {
-    vi.resetModules();
     vi.resetAllMocks();
     mockIssueService.getById.mockResolvedValue({
       id: issueId,
@@ -125,10 +122,9 @@ describe("issue document revision routes", () => {
   });
 
   it("returns revision snapshots including title and format", async () => {
-    const res = await request(await createApp()).get(`/api/issues/${issueId}/documents/plan/revisions`);
+    const res = await request(createApp()).get(`/api/issues/${issueId}/documents/plan/revisions`);
 
     expect(res.status).toBe(200);
-    expect(mockDocumentsService.listIssueDocumentRevisions).toHaveBeenCalledWith(issueId, "plan");
     expect(res.body).toEqual([
       expect.objectContaining({
         revisionNumber: 2,
@@ -140,7 +136,7 @@ describe("issue document revision routes", () => {
   });
 
   it("restores a revision through the append-only route and logs the action", async () => {
-    const res = await request(await createApp())
+    const res = await request(createApp())
       .post(`/api/issues/${issueId}/documents/plan/revisions/revision-1/restore`)
       .send({});
 
@@ -172,7 +168,7 @@ describe("issue document revision routes", () => {
   });
 
   it("rejects invalid document keys before attempting restore", async () => {
-    const res = await request(await createApp())
+    const res = await request(createApp())
       .post(`/api/issues/${issueId}/documents/INVALID KEY/revisions/revision-1/restore`)
       .send({});
 

server/src/__tests__/issue-execution-policy-routes.test.ts

@@ -60,19 +60,17 @@ vi.mock("../services/index.js", () => ({
   workProductService: () => ({}),
 }));
 
-function createApp(
-  actor: Record<string, unknown> = {
-    type: "board",
-    userId: "local-board",
-    companyIds: ["company-1"],
-    source: "local_implicit",
-    isInstanceAdmin: false,
-  },
-) {
+function createApp() {
   const app = express();
   app.use(express.json());
   app.use((req, _res, next) => {
-    (req as any).actor = actor;
+    (req as any).actor = {
+      type: "board",
+      userId: "local-board",
+      companyIds: ["company-1"],
+      source: "local_implicit",
+      isInstanceAdmin: false,
+    };
     next();
   });
   app.use("/api", issueRoutes({} as any, {} as any));
@@ -139,63 +137,4 @@ describe("issue execution policy routes", () => {
     expect(updatePatch.executionState).toBeUndefined();
     expect(mockHeartbeatService.wakeup).not.toHaveBeenCalled();
   });
-
-  it("rejects agent stage advances from non-participants", async () => {
-    const reviewerAgentId = "33333333-3333-4333-8333-333333333333";
-    const approverAgentId = "44444444-4444-4444-8444-444444444444";
-    const executorAgentId = "22222222-2222-4222-8222-222222222222";
-    const policy = normalizeIssueExecutionPolicy({
-      stages: [
-        {
-          id: "11111111-1111-4111-8111-111111111111",
-          type: "review",
-          participants: [{ type: "agent", agentId: reviewerAgentId }],
-        },
-        {
-          id: "55555555-5555-4555-8555-555555555555",
-          type: "approval",
-          participants: [{ type: "agent", agentId: approverAgentId }],
-        },
-      ],
-    })!;
-    const issue = {
-      id: "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
-      companyId: "company-1",
-      status: "in_review",
-      assigneeAgentId: reviewerAgentId,
-      assigneeUserId: null,
-      createdByUserId: "local-board",
-      identifier: "PAP-1000",
-      title: "Execution policy guard",
-      executionPolicy: policy,
-      executionState: {
-        status: "pending",
-        currentStageId: "11111111-1111-4111-8111-111111111111",
-        currentStageIndex: 0,
-        currentStageType: "review",
-        currentParticipant: { type: "agent", agentId: reviewerAgentId },
-        returnAssignee: { type: "agent", agentId: executorAgentId },
-        completedStageIds: [],
-        lastDecisionId: null,
-        lastDecisionOutcome: null,
-      },
-    };
-    mockIssueService.getById.mockResolvedValue(issue);
-
-    const res = await request(
-      createApp({
-        type: "agent",
-        agentId: approverAgentId,
-        companyId: "company-1",
-        source: "api_key",
-        runId: "run-1",
-      }),
-    )
-      .patch("/api/issues/aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa")
-      .send({ status: "done", comment: "Skipping review." });
-
-    expect(res.status).toBe(403);
-    expect(res.body.error).toContain("active review participant");
-    expect(mockIssueService.update).not.toHaveBeenCalled();
-  });
 });

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

@@ -413,45 +413,33 @@ describe("issue execution policy transitions", () => {
     const policy = twoStagePolicy();
     const reviewStageId = policy.stages[0].id;
 
-    it("non-participant stage updates are coerced back to the active stage", () => {
-      const result = applyIssueExecutionPolicyTransition({
-        issue: {
-          status: "in_review",
-          assigneeAgentId: qaAgentId,
-          assigneeUserId: null,
-          executionPolicy: policy,
-          executionState: {
-            status: "pending",
-            currentStageId: reviewStageId,
-            currentStageIndex: 0,
-            currentStageType: "review",
-            currentParticipant: { type: "agent", agentId: qaAgentId },
-            returnAssignee: { type: "agent", agentId: coderAgentId },
-            completedStageIds: [],
-            lastDecisionId: null,
-            lastDecisionOutcome: null,
+    it("non-participant cannot advance the active stage", () => {
+      expect(() =>
+        applyIssueExecutionPolicyTransition({
+          issue: {
+            status: "in_review",
+            assigneeAgentId: qaAgentId,
+            assigneeUserId: null,
+            executionPolicy: policy,
+            executionState: {
+              status: "pending",
+              currentStageId: reviewStageId,
+              currentStageIndex: 0,
+              currentStageType: "review",
+              currentParticipant: { type: "agent", agentId: qaAgentId },
+              returnAssignee: { type: "agent", agentId: coderAgentId },
+              completedStageIds: [],
+              lastDecisionId: null,
+              lastDecisionOutcome: null,
+            },
           },
-        },
-        policy,
-        requestedStatus: "done",
-        requestedAssigneePatch: { assigneeUserId: boardUserId },
-        actor: { agentId: coderAgentId },
-        commentBody: "Trying to bypass review",
-      });
-
-      expect(result.patch).toMatchObject({
-        status: "in_review",
-        assigneeAgentId: qaAgentId,
-        assigneeUserId: null,
-        executionState: {
-          status: "pending",
-          currentStageId: reviewStageId,
-          currentStageType: "review",
-          currentParticipant: { type: "agent", agentId: qaAgentId },
-          returnAssignee: { type: "agent", agentId: coderAgentId },
-        },
-      });
-      expect(result.decision).toBeUndefined();
+          policy,
+          requestedStatus: "done",
+          requestedAssigneePatch: { assigneeUserId: boardUserId },
+          actor: { agentId: coderAgentId },
+          commentBody: "Trying to bypass review",
+        }),
+      ).toThrow("Only the active reviewer or approver can advance");
     });
 
     it("non-participant can still post non-advancing updates", () => {

server/src/__tests__/issue-feedback-routes.test.ts

@@ -21,56 +21,60 @@ const mockIssueService = vi.hoisted(() => ({
 const mockFeedbackExportService = vi.hoisted(() => ({
   flushPendingFeedbackTraces: vi.fn(async () => ({ attempted: 1, sent: 1, failed: 0 })),
 }));
+const mockAccessService = vi.hoisted(() => ({
+  canUser: vi.fn(),
+  hasPermission: vi.fn(),
+}));
+const mockAgentService = vi.hoisted(() => ({
+  getById: vi.fn(),
+}));
+const mockHeartbeatService = vi.hoisted(() => ({
+  wakeup: vi.fn(async () => undefined),
+  reportRunActivity: vi.fn(async () => undefined),
+  getRun: vi.fn(async () => null),
+  getActiveRunForAgent: vi.fn(async () => null),
+  cancelRun: vi.fn(async () => null),
+}));
+const mockInstanceSettingsService = vi.hoisted(() => ({
+  get: vi.fn(async () => ({
+    id: "instance-settings-1",
+    general: {
+      censorUsernameInLogs: false,
+      feedbackDataSharingPreference: "prompt",
+    },
+  })),
+  listCompanyIds: vi.fn(async () => ["company-1"]),
+}));
+const mockRoutineService = vi.hoisted(() => ({
+  syncRunStatusForIssue: vi.fn(async () => undefined),
+}));
+const mockLogActivity = vi.hoisted(() => vi.fn(async () => undefined));
 
-function registerServiceMocks() {
-  vi.doMock("@paperclipai/shared/telemetry", () => ({
-    trackAgentTaskCompleted: vi.fn(),
-    trackErrorHandlerCrash: vi.fn(),
-  }));
+vi.mock("@paperclipai/shared/telemetry", () => ({
+  trackAgentTaskCompleted: vi.fn(),
+  trackErrorHandlerCrash: vi.fn(),
+}));
 
-  vi.doMock("../telemetry.js", () => ({
-    getTelemetryClient: vi.fn(() => ({ track: vi.fn() })),
-  }));
+vi.mock("../telemetry.js", () => ({
+  getTelemetryClient: vi.fn(() => ({ track: vi.fn() })),
+}));
 
-  vi.doMock("../services/index.js", () => ({
-    accessService: () => ({
-      canUser: vi.fn(),
-      hasPermission: vi.fn(),
-    }),
-    agentService: () => ({
-      getById: vi.fn(),
-    }),
-    documentService: () => ({}),
-    executionWorkspaceService: () => ({}),
-    feedbackService: () => mockFeedbackService,
-    goalService: () => ({}),
-    heartbeatService: () => ({
-      wakeup: vi.fn(async () => undefined),
-      reportRunActivity: vi.fn(async () => undefined),
-      getRun: vi.fn(async () => null),
-      getActiveRunForAgent: vi.fn(async () => null),
-      cancelRun: vi.fn(async () => null),
-    }),
-    instanceSettingsService: () => ({
-      get: vi.fn(async () => ({
-        id: "instance-settings-1",
-        general: {
-          censorUsernameInLogs: false,
-          feedbackDataSharingPreference: "prompt",
-        },
-      })),
-      listCompanyIds: vi.fn(async () => ["company-1"]),
-    }),
-    issueApprovalService: () => ({}),
-    issueService: () => mockIssueService,
-    logActivity: vi.fn(async () => undefined),
-    projectService: () => ({}),
-    routineService: () => ({
-      syncRunStatusForIssue: vi.fn(async () => undefined),
-    }),
-    workProductService: () => ({}),
-  }));
-}
+vi.mock("../services/index.js", () => ({
+  accessService: () => mockAccessService,
+  agentService: () => mockAgentService,
+  documentService: () => ({}),
+  executionWorkspaceService: () => ({}),
+  feedbackService: () => mockFeedbackService,
+  goalService: () => ({}),
+  heartbeatService: () => mockHeartbeatService,
+  instanceSettingsService: () => mockInstanceSettingsService,
+  issueApprovalService: () => ({}),
+  issueService: () => mockIssueService,
+  logActivity: mockLogActivity,
+  projectService: () => ({}),
+  routineService: () => mockRoutineService,
+  workProductService: () => ({}),
+}));
 
 async function createApp(actor: Record<string, unknown>) {
   const [{ issueRoutes }, { errorHandler }] = await Promise.all([
@@ -91,13 +95,27 @@ async function createApp(actor: Record<string, unknown>) {
 describe("issue feedback trace routes", () => {
   beforeEach(() => {
     vi.resetModules();
-    registerServiceMocks();
     vi.resetAllMocks();
     mockFeedbackExportService.flushPendingFeedbackTraces.mockResolvedValue({
       attempted: 1,
       sent: 1,
       failed: 0,
     });
+    mockHeartbeatService.wakeup.mockResolvedValue(undefined);
+    mockHeartbeatService.reportRunActivity.mockResolvedValue(undefined);
+    mockHeartbeatService.getRun.mockResolvedValue(null);
+    mockHeartbeatService.getActiveRunForAgent.mockResolvedValue(null);
+    mockHeartbeatService.cancelRun.mockResolvedValue(null);
+    mockInstanceSettingsService.get.mockResolvedValue({
+      id: "instance-settings-1",
+      general: {
+        censorUsernameInLogs: false,
+        feedbackDataSharingPreference: "prompt",
+      },
+    });
+    mockInstanceSettingsService.listCompanyIds.mockResolvedValue(["company-1"]);
+    mockRoutineService.syncRunStatusForIssue.mockResolvedValue(undefined);
+    mockLogActivity.mockResolvedValue(undefined);
   });
 
   it("flushes a newly shared feedback trace immediately after saving the vote", async () => {

server/src/__tests__/issue-telemetry-routes.test.ts

@@ -1,6 +1,8 @@
 import express from "express";
 import request from "supertest";
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import { errorHandler } from "../middleware/index.js";
+import { issueRoutes } from "../routes/issues.js";
 
 const mockIssueService = vi.hoisted(() => ({
   getById: vi.fn(),
@@ -16,41 +18,39 @@ const mockAgentService = vi.hoisted(() => ({
 const mockTrackAgentTaskCompleted = vi.hoisted(() => vi.fn());
 const mockGetTelemetryClient = vi.hoisted(() => vi.fn());
 
-function registerRouteMocks() {
-  vi.doMock("@paperclipai/shared/telemetry", () => ({
-    trackAgentTaskCompleted: mockTrackAgentTaskCompleted,
-    trackErrorHandlerCrash: vi.fn(),
-  }));
+vi.mock("@paperclipai/shared/telemetry", () => ({
+  trackAgentTaskCompleted: mockTrackAgentTaskCompleted,
+  trackErrorHandlerCrash: vi.fn(),
+}));
 
-  vi.doMock("../telemetry.js", () => ({
-    getTelemetryClient: mockGetTelemetryClient,
-  }));
+vi.mock("../telemetry.js", () => ({
+  getTelemetryClient: mockGetTelemetryClient,
+}));
 
-  vi.doMock("../services/index.js", () => ({
-    accessService: () => ({
-      canUser: vi.fn(),
-      hasPermission: vi.fn(),
-    }),
-    agentService: () => mockAgentService,
-    documentService: () => ({}),
-    executionWorkspaceService: () => ({}),
-    feedbackService: () => ({}),
-    goalService: () => ({}),
-    heartbeatService: () => ({
-      wakeup: vi.fn(async () => undefined),
-      reportRunActivity: vi.fn(async () => undefined),
-    }),
-    instanceSettingsService: () => ({}),
-    issueApprovalService: () => ({}),
-    issueService: () => mockIssueService,
-    logActivity: vi.fn(async () => undefined),
-    projectService: () => ({}),
-    routineService: () => ({
-      syncRunStatusForIssue: vi.fn(async () => undefined),
-    }),
-    workProductService: () => ({}),
-  }));
-}
+vi.mock("../services/index.js", () => ({
+  accessService: () => ({
+    canUser: vi.fn(),
+    hasPermission: vi.fn(),
+  }),
+  agentService: () => mockAgentService,
+  documentService: () => ({}),
+  executionWorkspaceService: () => ({}),
+  feedbackService: () => ({}),
+  goalService: () => ({}),
+  heartbeatService: () => ({
+    wakeup: vi.fn(async () => undefined),
+    reportRunActivity: vi.fn(async () => undefined),
+  }),
+  instanceSettingsService: () => ({}),
+  issueApprovalService: () => ({}),
+  issueService: () => mockIssueService,
+  logActivity: vi.fn(async () => undefined),
+  projectService: () => ({}),
+  routineService: () => ({
+    syncRunStatusForIssue: vi.fn(async () => undefined),
+  }),
+  workProductService: () => ({}),
+}));
 
 function makeIssue(status: "todo" | "done") {
   return {
@@ -65,11 +65,7 @@ function makeIssue(status: "todo" | "done") {
   };
 }
 
-async function createApp(actor: Record<string, unknown>) {
-  const [{ issueRoutes }, { errorHandler }] = await Promise.all([
-    import("../routes/issues.js"),
-    import("../middleware/index.js"),
-  ]);
+function createApp(actor: Record<string, unknown>) {
   const app = express();
   app.use(express.json());
   app.use((req, _res, next) => {
@@ -83,8 +79,6 @@ async function createApp(actor: Record<string, unknown>) {
 
 describe("issue telemetry routes", () => {
   beforeEach(() => {
-    vi.resetModules();
-    registerRouteMocks();
     vi.resetAllMocks();
     mockGetTelemetryClient.mockReturnValue({ track: vi.fn() });
     mockIssueService.getById.mockResolvedValue(makeIssue("todo"));
@@ -104,7 +98,7 @@ describe("issue telemetry routes", () => {
       adapterType: "codex_local",
     });
 
-    const app = await createApp({
+    const app = createApp({
       type: "agent",
       agentId: "agent-1",
       companyId: "company-1",
@@ -124,7 +118,7 @@ describe("issue telemetry routes", () => {
   }, 10_000);
 
   it("does not emit agent task-completed telemetry for board-driven completions", async () => {
-    const app = await createApp({
+    const app = createApp({
       type: "board",
       userId: "local-board",
       companyIds: ["company-1"],

server/src/__tests__/issue-update-comment-wakeup-routes.test.ts

@@ -0,0 +1,202 @@
+import express from "express";
+import request from "supertest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { errorHandler } from "../middleware/index.js";
+import { issueRoutes } from "../routes/issues.js";
+
+const ASSIGNEE_AGENT_ID = "11111111-1111-4111-8111-111111111111";
+
+const mockIssueService = vi.hoisted(() => ({
+  getById: vi.fn(),
+  update: vi.fn(),
+  addComment: vi.fn(),
+  findMentionedAgents: vi.fn(),
+  getRelationSummaries: vi.fn(),
+  listWakeableBlockedDependents: vi.fn(),
+  getWakeableParentAfterChildCompletion: vi.fn(),
+}));
+
+const mockHeartbeatService = vi.hoisted(() => ({
+  wakeup: vi.fn(async () => undefined),
+  reportRunActivity: vi.fn(async () => undefined),
+  getRun: vi.fn(async () => null),
+  getActiveRunForAgent: vi.fn(async () => null),
+  cancelRun: vi.fn(async () => null),
+}));
+
+vi.mock("../services/index.js", () => ({
+  accessService: () => ({
+    canUser: vi.fn(async () => true),
+    hasPermission: vi.fn(async () => true),
+  }),
+  agentService: () => ({
+    getById: vi.fn(async () => null),
+  }),
+  documentService: () => ({}),
+  executionWorkspaceService: () => ({}),
+  feedbackService: () => ({
+    listIssueVotesForUser: vi.fn(async () => []),
+    saveIssueVote: vi.fn(async () => ({ vote: null, consentEnabledNow: false, sharingEnabled: false })),
+  }),
+  goalService: () => ({}),
+  heartbeatService: () => mockHeartbeatService,
+  instanceSettingsService: () => ({
+    get: vi.fn(async () => ({
+      id: "instance-settings-1",
+      general: {
+        censorUsernameInLogs: false,
+        feedbackDataSharingPreference: "prompt",
+      },
+    })),
+    listCompanyIds: vi.fn(async () => ["company-1"]),
+  }),
+  issueApprovalService: () => ({}),
+  issueService: () => mockIssueService,
+  logActivity: vi.fn(async () => undefined),
+  projectService: () => ({}),
+  routineService: () => ({
+    syncRunStatusForIssue: vi.fn(async () => undefined),
+  }),
+  workProductService: () => ({}),
+}));
+
+function createApp() {
+  const app = express();
+  app.use(express.json());
+  app.use((req, _res, next) => {
+    (req as any).actor = {
+      type: "board",
+      userId: "local-board",
+      companyIds: ["company-1"],
+      source: "local_implicit",
+      isInstanceAdmin: false,
+    };
+    next();
+  });
+  app.use("/api", issueRoutes({} as any, {} as any));
+  app.use(errorHandler);
+  return app;
+}
+
+function makeIssue(overrides: Record<string, unknown> = {}) {
+  return {
+    id: "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
+    companyId: "company-1",
+    status: "todo",
+    priority: "medium",
+    projectId: null,
+    goalId: null,
+    parentId: null,
+    assigneeAgentId: null,
+    assigneeUserId: "local-board",
+    createdByUserId: "local-board",
+    identifier: "PAP-999",
+    title: "Wake test",
+    executionPolicy: null,
+    executionState: null,
+    hiddenAt: null,
+    ...overrides,
+  };
+}
+
+describe("issue update comment wakeups", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockIssueService.findMentionedAgents.mockResolvedValue([]);
+    mockIssueService.getRelationSummaries.mockResolvedValue({ blockedBy: [], blocks: [] });
+    mockIssueService.listWakeableBlockedDependents.mockResolvedValue([]);
+    mockIssueService.getWakeableParentAfterChildCompletion.mockResolvedValue(null);
+  });
+
+  it("includes the new comment in assignment wakes from issue updates", async () => {
+    const existing = makeIssue();
+    const updated = makeIssue({
+      assigneeAgentId: ASSIGNEE_AGENT_ID,
+      assigneeUserId: null,
+    });
+    mockIssueService.getById.mockResolvedValue(existing);
+    mockIssueService.update.mockResolvedValue(updated);
+    mockIssueService.addComment.mockResolvedValue({
+      id: "comment-1",
+      issueId: existing.id,
+      companyId: existing.companyId,
+      body: "write the whole thing",
+    });
+
+    const res = await request(createApp())
+      .patch(`/api/issues/${existing.id}`)
+      .send({
+        assigneeAgentId: ASSIGNEE_AGENT_ID,
+        assigneeUserId: null,
+        comment: "write the whole thing",
+      });
+
+    expect(res.status).toBe(200);
+    expect(mockHeartbeatService.wakeup).toHaveBeenCalledTimes(1);
+    expect(mockHeartbeatService.wakeup).toHaveBeenCalledWith(
+      ASSIGNEE_AGENT_ID,
+      expect.objectContaining({
+        source: "assignment",
+        reason: "issue_assigned",
+        payload: expect.objectContaining({
+          issueId: existing.id,
+          commentId: "comment-1",
+          mutation: "update",
+        }),
+        contextSnapshot: expect.objectContaining({
+          issueId: existing.id,
+          taskId: existing.id,
+          commentId: "comment-1",
+          wakeCommentId: "comment-1",
+          source: "issue.update",
+        }),
+      }),
+    );
+  });
+
+  it("wakes the assignee on comment-only issue updates", async () => {
+    const existing = makeIssue({
+      assigneeAgentId: ASSIGNEE_AGENT_ID,
+      assigneeUserId: null,
+      status: "in_progress",
+    });
+    const updated = { ...existing };
+    mockIssueService.getById.mockResolvedValue(existing);
+    mockIssueService.update.mockResolvedValue(updated);
+    mockIssueService.addComment.mockResolvedValue({
+      id: "comment-2",
+      issueId: existing.id,
+      companyId: existing.companyId,
+      body: "please revise this",
+    });
+
+    const res = await request(createApp())
+      .patch(`/api/issues/${existing.id}`)
+      .send({
+        comment: "please revise this",
+      });
+
+    expect(res.status).toBe(200);
+    expect(mockHeartbeatService.wakeup).toHaveBeenCalledTimes(1);
+    expect(mockHeartbeatService.wakeup).toHaveBeenCalledWith(
+      ASSIGNEE_AGENT_ID,
+      expect.objectContaining({
+        source: "automation",
+        reason: "issue_commented",
+        payload: expect.objectContaining({
+          issueId: existing.id,
+          commentId: "comment-2",
+          mutation: "comment",
+        }),
+        contextSnapshot: expect.objectContaining({
+          issueId: existing.id,
+          taskId: existing.id,
+          commentId: "comment-2",
+          wakeCommentId: "comment-2",
+          wakeReason: "issue_commented",
+          source: "issue.comment",
+        }),
+      }),
+    );
+  });
+});

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

@@ -249,6 +249,135 @@ describeEmbeddedPostgres("issueService.list participantAgentId", () => {
     expect(result.map((issue) => issue.id)).toEqual([matchedIssueId]);
   });
 
+  it("applies result limits to issue search", async () => {
+    const companyId = randomUUID();
+
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Paperclip",
+      issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+      requireBoardApprovalForNewAgents: false,
+    });
+
+    const exactIdentifierId = randomUUID();
+    const titleMatchId = randomUUID();
+    const descriptionMatchId = randomUUID();
+
+    await db.insert(issues).values([
+      {
+        id: exactIdentifierId,
+        companyId,
+        issueNumber: 42,
+        identifier: "PAP-42",
+        title: "Completely unrelated",
+        status: "todo",
+        priority: "medium",
+      },
+      {
+        id: titleMatchId,
+        companyId,
+        title: "Search ranking issue",
+        status: "todo",
+        priority: "medium",
+      },
+      {
+        id: descriptionMatchId,
+        companyId,
+        title: "Another item",
+        description: "Contains the search keyword",
+        status: "todo",
+        priority: "medium",
+      },
+    ]);
+
+    const result = await svc.list(companyId, {
+      q: "search",
+      limit: 2,
+    });
+
+    expect(result.map((issue) => issue.id)).toEqual([titleMatchId, descriptionMatchId]);
+  });
+
+  it("ranks comment matches ahead of description-only matches", async () => {
+    const companyId = randomUUID();
+    const commentMatchId = randomUUID();
+    const descriptionMatchId = randomUUID();
+
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Paperclip",
+      issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+      requireBoardApprovalForNewAgents: false,
+    });
+
+    await db.insert(issues).values([
+      {
+        id: commentMatchId,
+        companyId,
+        title: "Comment match",
+        status: "todo",
+        priority: "medium",
+      },
+      {
+        id: descriptionMatchId,
+        companyId,
+        title: "Description match",
+        description: "Contains pull/3303 in the description",
+        status: "todo",
+        priority: "medium",
+      },
+    ]);
+
+    await db.insert(issueComments).values({
+      companyId,
+      issueId: commentMatchId,
+      body: "Reference: https://github.com/paperclipai/paperclip/pull/3303",
+    });
+
+    const result = await svc.list(companyId, {
+      q: "pull/3303",
+      limit: 2,
+      includeRoutineExecutions: true,
+    });
+
+    expect(result.map((issue) => issue.id)).toEqual([commentMatchId, descriptionMatchId]);
+  });
+
+  it("accepts issue identifiers through getById", async () => {
+    const companyId = randomUUID();
+    const issueId = randomUUID();
+
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Paperclip",
+      issuePrefix: "PAP",
+      requireBoardApprovalForNewAgents: false,
+    });
+
+    await db.insert(issues).values({
+      id: issueId,
+      companyId,
+      issueNumber: 1064,
+      identifier: "PAP-1064",
+      title: "Feedback votes error",
+      status: "todo",
+      priority: "medium",
+      createdByUserId: "user-1",
+    });
+
+    const issue = await svc.getById("PAP-1064");
+
+    expect(issue).toEqual(
+      expect.objectContaining({
+        id: issueId,
+        identifier: "PAP-1064",
+      }),
+    );
+  });
+
+  it("returns null instead of throwing for malformed non-uuid issue refs", async () => {
+    await expect(svc.getById("not-a-uuid")).resolves.toBeNull();
+  });
   it("filters issues by execution workspace id", async () => {
     const companyId = randomUUID();
     const projectId = randomUUID();

server/src/__tests__/llms-routes.test.ts

@@ -0,0 +1,56 @@
+import express from "express";
+import request from "supertest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { llmRoutes } from "../routes/llms.js";
+import { errorHandler } from "../middleware/index.js";
+
+const mockAgentService = vi.hoisted(() => ({
+  getById: vi.fn(),
+}));
+
+const mockListServerAdapters = vi.hoisted(() => vi.fn());
+
+vi.mock("../services/index.js", () => ({
+  agentService: () => mockAgentService,
+}));
+
+vi.mock("../adapters/index.js", () => ({
+  listServerAdapters: mockListServerAdapters,
+}));
+
+function createApp(actor: Record<string, unknown>) {
+  const app = express();
+  app.use(express.json());
+  app.use((req, _res, next) => {
+    (req as any).actor = actor;
+    next();
+  });
+  app.use("/api", llmRoutes({} as never));
+  app.use(errorHandler);
+  return app;
+}
+
+describe("llm routes", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockListServerAdapters.mockReturnValue([
+      { type: "codex_local", agentConfigurationDoc: "# codex_local agent configuration" },
+    ]);
+  });
+
+  it("documents timer heartbeats as opt-in for new hires", async () => {
+    const app = createApp({
+      type: "board",
+      userId: "board-user",
+      companyIds: ["company-1"],
+      source: "local_implicit",
+      isInstanceAdmin: true,
+    });
+
+    const res = await request(app).get("/api/llms/agent-configuration.txt");
+
+    expect(res.status).toBe(200);
+    expect(res.text).toContain("Timer heartbeats are opt-in for new hires.");
+    expect(res.text).toContain("Leave runtimeConfig.heartbeat.enabled false");
+  });
+});

server/src/__tests__/openclaw-invite-prompt-route.test.ts

@@ -1,6 +1,8 @@
 import express from "express";
 import request from "supertest";
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import { accessRoutes } from "../routes/access.js";
+import { errorHandler } from "../middleware/index.js";
 
 const mockAccessService = vi.hoisted(() => ({
   hasPermission: vi.fn(),
@@ -33,16 +35,14 @@ const mockBoardAuthService = vi.hoisted(() => ({
 
 const mockLogActivity = vi.hoisted(() => vi.fn());
 
-function registerServiceMocks() {
-  vi.doMock("../services/index.js", () => ({
-    accessService: () => mockAccessService,
-    agentService: () => mockAgentService,
-    boardAuthService: () => mockBoardAuthService,
-    deduplicateAgentName: vi.fn(),
-    logActivity: mockLogActivity,
-    notifyHireApproved: vi.fn(),
-  }));
-}
+vi.mock("../services/index.js", () => ({
+  accessService: () => mockAccessService,
+  agentService: () => mockAgentService,
+  boardAuthService: () => mockBoardAuthService,
+  deduplicateAgentName: vi.fn(),
+  logActivity: mockLogActivity,
+  notifyHireApproved: vi.fn(),
+}));
 
 function createDbStub() {
   const createdInvite = {
@@ -105,11 +105,7 @@ function createDbStub() {
   };
 }
 
-async function createApp(actor: Record<string, unknown>, db: Record<string, unknown>) {
-  const [{ accessRoutes }, { errorHandler }] = await Promise.all([
-    import("../routes/access.js"),
-    import("../middleware/index.js"),
-  ]);
+function createApp(actor: Record<string, unknown>, db: Record<string, unknown>) {
   const app = express();
   app.use(express.json());
   app.use((req, _res, next) => {
@@ -131,9 +127,7 @@ async function createApp(actor: Record<string, unknown>, db: Record<string, unkn
 
 describe("POST /companies/:companyId/openclaw/invite-prompt", () => {
   beforeEach(() => {
-    vi.resetModules();
-    registerServiceMocks();
-    vi.clearAllMocks();
+    vi.resetAllMocks();
     mockAccessService.canUser.mockResolvedValue(false);
     mockAgentService.getById.mockReset();
     mockLogActivity.mockResolvedValue(undefined);
@@ -146,7 +140,7 @@ describe("POST /companies/:companyId/openclaw/invite-prompt", () => {
       companyId: "company-1",
       role: "engineer",
     });
-    const app = await createApp(
+    const app = createApp(
       {
         type: "agent",
         agentId: "agent-1",
@@ -171,7 +165,7 @@ describe("POST /companies/:companyId/openclaw/invite-prompt", () => {
       companyId: "company-1",
       role: "ceo",
     });
-    const app = await createApp(
+    const app = createApp(
       {
         type: "agent",
         agentId: "agent-1",
@@ -199,7 +193,7 @@ describe("POST /companies/:companyId/openclaw/invite-prompt", () => {
 
   it("includes companyName in invite summary responses", async () => {
     const db = createDbStub();
-    const app = await createApp(
+    const app = createApp(
       {
         type: "board",
         userId: "user-1",
@@ -223,7 +217,7 @@ describe("POST /companies/:companyId/openclaw/invite-prompt", () => {
   it("allows board callers with invite permission", async () => {
     const db = createDbStub();
     mockAccessService.canUser.mockResolvedValue(true);
-    const app = await createApp(
+    const app = createApp(
       {
         type: "board",
         userId: "user-1",
@@ -246,12 +240,12 @@ describe("POST /companies/:companyId/openclaw/invite-prompt", () => {
         allowedJoinTypes: "agent",
       }),
     );
-  });
+  }, 15_000);
 
   it("rejects board callers without invite permission", async () => {
     const db = createDbStub();
     mockAccessService.canUser.mockResolvedValue(false);
-    const app = await createApp(
+    const app = createApp(
       {
         type: "board",
         userId: "user-1",