Merge origin/master into PAP-1293 memory branch

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-10-21 16:27:18 +02:00 · 2026-04-20 07:16:40 -05:00
commit e654c4efd2
@@ -154,6 +154,14 @@ Each AGENTS.md body should include not just what the agent does, but how they fi

 This turns a collection of agents into an organization that actually works together. Without workflow context, agents operate in isolation — they do their job but don't know what happens before or after them.

+Add a concise execution contract to every generated working agent:
+
+- Start actionable work in the same heartbeat and do not stop at a plan unless planning was requested.
+- Leave durable progress in comments, documents, or work products with the next action.
+- Use child issues for long or parallel delegated work instead of polling agents, sessions, or processes.
+- Mark blocked work with the unblock owner and action.
+- Respect budget, pause/cancel, approval gates, and company boundaries.
+
 ### Step 5: Confirm Output Location

 Ask the user where to write the package. Common options:
@@ -105,6 +105,13 @@ Your responsibilities:
 - Implement features and fix bugs
 - Write tests and documentation
 - Participate in code reviews
+
+Execution contract:
+
+- Start actionable implementation work in the same heartbeat; do not stop at a plan unless planning was requested.
+- Leave durable progress with a clear next action.
+- Use child issues for long or parallel delegated work instead of polling agents, sessions, or processes.
+- Mark blocked work with the unblock owner and action.
 ```

 ## teams/engineering/TEAM.md
@@ -548,7 +548,7 @@ Import from `@paperclipai/adapter-utils/server-utils`:
 ### Prompt Templates
 - Support `promptTemplate` for every run
 - Use `renderTemplate()` with the standard variable set
- Default prompt: `"You are agent {{agent.id}} ({{agent.name}}). Continue your Paperclip work."`
+- Default prompt should use `DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE` from `@paperclipai/adapter-utils/server-utils` so local adapters share Paperclip's execution contract: act in the same heartbeat, avoid planning-only exits unless requested, leave durable progress and a next action, use child issues instead of polling, mark blockers with owner/action, and respect governance boundaries.

 ### Error Handling
 - Differentiate timeout vs process error vs parse failure
@@ -2,3 +2,6 @@ DATABASE_URL=postgres://paperclip:paperclip@localhost:5432/paperclip
 PORT=3100
 SERVE_UI=false
 BETTER_AUTH_SECRET=paperclip-dev-secret
+
+# Discord webhook for daily merge digest (scripts/discord-daily-digest.sh)
+# DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
@@ -38,6 +38,8 @@

 -

+> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`.
+
 ## Model Used

 <!--
@@ -57,6 +59,7 @@

 - [ ] I have included a thinking path that traces from project context to this change
 - [ ] I have specified the model used (with version and capability details)
+- [ ] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work
 - [ ] I have run tests locally and they pass
 - [ ] I have added or updated tests where applicable
 - [ ] If this change affects the UI, I have included before/after screenshots
@@ -1,4 +1,7 @@
+node_modules
 node_modules/
+**/node_modules
+**/node_modules/
 dist/
 .env
 *.tsbuildinfo
@@ -32,6 +35,7 @@ server/src/**/*.d.ts
 server/src/**/*.d.ts.map
 tmp/
 feedback-export-*
+diagnostics/

 # Editor / tool temp files
 *.tmp
@@ -108,6 +108,21 @@ Notes:

 ## 7. Verification Before Hand-off

+Default local/agent test path:
+
+```sh
+pnpm test
+```
+
+This is the cheap default and only runs the Vitest suite. Browser suites stay opt-in:
+
+```sh
+pnpm test:e2e
+pnpm test:release-smoke
+```
+
+Run the browser suites only when your change touches them or when you are explicitly verifying CI/release flows.
+
 Run this full check before claiming done:

 ```sh
@@ -51,6 +51,21 @@ All tests must pass before a PR can be merged. Run them locally first and verify

 We use [Greptile](https://greptile.com) for automated code review. Your PR must achieve a **5/5 Greptile score** with **all Greptile comments addressed** before it can be merged. If Greptile leaves comments, fix or respond to each one and request a re-review.

+## Feature Contributions
+
+We actively manage the core Paperclip feature roadmap.
+
+Uncoordinated feature PRs against the core product may be closed, even when the implementation is thoughtful and high quality. That is about roadmap ownership, product coherence, and long-term maintenance commitment, not a judgment about the effort.
+
+If you want to contribute a feature:
+
+- Check [ROADMAP.md](ROADMAP.md) first
+- Start the discussion in Discord -> `#dev` before writing code
+- If the idea fits as an extension, prefer building it with the [plugin system](doc/plugins/PLUGIN_SPEC.md)
+- If you want to show a possible direction, reference implementations are welcome as feedback, but they generally will not be merged directly into core
+
+Bugs, docs improvements, and small targeted improvements are still the easiest path to getting merged, and we really do appreciate them.
+
 ## General Rules (both paths)

 - Write clear commit messages
@@ -2,15 +2,7 @@ FROM node:lts-trixie-slim AS base
 ARG USER_UID=1000
 ARG USER_GID=1000
 RUN apt-get update \
-  && apt-get install -y --no-install-recommends ca-certificates gosu curl git wget ripgrep python3 \
-  && mkdir -p -m 755 /etc/apt/keyrings \
-  && wget -nv -O/etc/apt/keyrings/githubcli-archive-keyring.gpg https://cli.github.com/packages/githubcli-archive-keyring.gpg \
-  && echo "20e0125d6f6e077a9ad46f03371bc26d90b04939fb95170f5a1905099cc6bcc0  /etc/apt/keyrings/githubcli-archive-keyring.gpg" | sha256sum -c - \
-  && chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
-  && mkdir -p -m 755 /etc/apt/sources.list.d \
-  && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" > /etc/apt/sources.list.d/github-cli.list \
-  && apt-get update \
-  && apt-get install -y --no-install-recommends gh \
+  && apt-get install -y --no-install-recommends ca-certificates gosu curl gh git wget ripgrep python3 \
  && rm -rf /var/lib/apt/lists/* \
  && corepack enable

@@ -56,6 +48,9 @@ ARG USER_GID=1000
 WORKDIR /app
 COPY --chown=node:node --from=build /app /app
 RUN npm install --global --omit=dev @anthropic-ai/claude-code@latest @openai/codex@latest opencode-ai \
+  && apt-get update \
+  && apt-get install -y --no-install-recommends openssh-client jq \
+  && rm -rf /var/lib/apt/lists/* \
  && mkdir -p /paperclip \
  && chown node:node /paperclip

@@ -233,11 +233,15 @@ pnpm dev:once         # Full dev without file watching
 pnpm dev:server       # Server only
 pnpm build            # Build all
 pnpm typecheck        # Type checking
-pnpm test:run         # Run tests
+pnpm test             # Cheap default test run (Vitest only)
+pnpm test:watch       # Vitest watch mode
+pnpm test:e2e         # Playwright browser suite
 pnpm db:generate      # Generate DB migration
 pnpm db:migrate       # Apply migrations
 ```

+`pnpm test` does not run Playwright. Browser suites stay separate and are typically run only when working on those flows or in CI.
+
 See [doc/DEVELOPING.md](doc/DEVELOPING.md) for the full development guide.

 <br/>
@@ -255,7 +259,7 @@ See [doc/DEVELOPING.md](doc/DEVELOPING.md) for the full development guide.
 - ⚪ Multiple Human Users
 - ⚪ Cloud / Sandbox agents (e.g. Cursor / e2b agents)
 - ⚪ Artifacts & Work Products
- ⚪ Memory & Knowledge
+- ⚪ Memory / Knowledge
 - ⚪ Enforced Outcomes
 - ⚪ MAXIMIZER MODE
 - ⚪ Deep Planning
@@ -266,6 +270,8 @@ See [doc/DEVELOPING.md](doc/DEVELOPING.md) for the full development guide.
 - ⚪ Cloud deployments
 - ⚪ Desktop App

+This is the short roadmap preview. See the full roadmap in [ROADMAP.md](ROADMAP.md).
+
 <br/>

 ## Community & Plugins
@@ -0,0 +1,97 @@
+# Roadmap
+
+This document expands the roadmap preview in `README.md`.
+
+Paperclip is still moving quickly. The list below is directional, not promised, and priorities may shift as we learn from users and from operating real AI companies with the product.
+
+We value community involvement and want to make sure contributor energy goes toward areas where it can land.
+
+We may accept contributions in the areas below, but if you want to work on roadmap-level core features, please coordinate with us first in Discord (`#dev`) before writing code. Bugs, docs, polish, and tightly scoped improvements are still the easiest contributions to merge.
+
+If you want to extend Paperclip today, the best path is often the [plugin system](doc/plugins/PLUGIN_SPEC.md). Community reference implementations are also useful feedback even when they are not merged directly into core.
+
+## Milestones
+
+### ✅ Plugin system
+
+Paperclip should keep a thin core and rich edges. Plugins are the path for optional capabilities like knowledge bases, custom tracing, queues, doc editors, and other product-specific surfaces that do not need to live in the control plane itself.
+
+### ✅ Get OpenClaw / claw-style agent employees
+
+Paperclip should be able to hire and manage real claw-style agent workers, not just a narrow built-in runtime. This is part of the larger "bring your own agent" story and keeps the control plane useful across different agent ecosystems.
+
+### ✅ companies.sh - import and export entire organizations
+
+Reusable companies matter. Import/export is the foundation for moving org structures, agent definitions, and reusable company setups between environments and eventually for broader company-template distribution.
+
+### ✅ Easy AGENTS.md configurations
+
+Agent setup should feel repo-native and legible. Simple `AGENTS.md`-style configuration lowers the barrier to getting an agent team running and makes it easier for contributors to understand how a company is wired together.
+
+### ✅ Skills Manager
+
+Agents need a practical way to discover, install, and use skills without every setup becoming bespoke. The skills layer is part of making Paperclip companies more reusable and easier to operate.
+
+### ✅ Scheduled Routines
+
+Recurring work should be native. Routine tasks like reports, reviews, and other periodic work need first-class scheduling so the company keeps operating even when no human is manually kicking work off.
+
+### ✅ Better Budgeting
+
+Budgets are a core control-plane feature, not an afterthought. Better budgeting means clearer spend visibility, safer hard stops, and better operator control over how autonomy turns into real cost.
+
+### ✅ Agent Reviews and Approvals
+
+Paperclip should support explicit review and approval stages as first-class workflow steps, not just ad hoc comments. That means reviewer routing, approval gates, change requests, and durable audit trails that fit the same task model as the rest of the control plane.
+
+### ⚪ Multiple Human Users
+
+Paperclip needs a clearer path from solo operator to real human teams. That means shared board access, safer collaboration, and a better model for several humans supervising the same autonomous company.
+
+### ⚪ Cloud / Sandbox agents (e.g. Cursor / e2b agents)
+
+We want agents to run in more remote and sandboxed environments while preserving the same Paperclip control-plane model. This makes the system safer, more flexible, and more useful outside a single trusted local machine.
+
+### ⚪ Artifacts & Work Products
+
+Paperclip should make outputs first-class. That means generated artifacts, previews, deployable outputs, and the handoff from "agent did work" to "here is the result" should become more visible and easier to operate.
+
+### ⚪ Memory / Knowledge
+
+We want a stronger memory and knowledge surface for companies, agents, and projects. That includes durable memory, better recall of prior decisions and context, and a clearer path for knowledge-style capabilities without turning Paperclip into a generic chat app.
+
+### ⚪ Enforced Outcomes
+
+Paperclip should get stricter about what counts as finished work. Tasks, approvals, and execution flows should resolve to clear outcomes like merged code, published artifacts, shipped docs, or explicit decisions instead of stopping at vague status updates.
+
+### ⚪ MAXIMIZER MODE
+
+This is the direction for higher-autonomy execution: more aggressive delegation, deeper follow-through, and stronger operating loops with clear budgets, visibility, and governance. The point is not hidden autonomy; the point is more output per human supervisor.
+
+### ⚪ Deep Planning
+
+Some work needs more than a task description before execution starts. Deeper planning means stronger issue documents, revisionable plans, and clearer review loops for strategy-heavy work before agents begin execution.
+
+### ⚪ Work Queues
+
+Paperclip should support queue-style work streams for repeatable inputs like support, triage, review, and backlog intake. That would make it easier to route work continuously without turning every system into a one-off workflow.
+
+### ⚪ Self-Organization
+
+As companies grow, agents should be able to propose useful structural changes such as role adjustments, delegation changes, and new recurring routines. The goal is adaptive organizations that still stay within governance and approval boundaries.
+
+### ⚪ Automatic Organizational Learning
+
+Paperclip should get better at turning completed work into reusable organizational knowledge. That includes capturing playbooks, recurring fixes, and decision patterns so future work starts from what the company has already learned.
+
+### ⚪ CEO Chat
+
+We want a lighter-weight way to talk to leadership agents, but those conversations should still resolve to real work objects like plans, issues, approvals, or decisions. This should improve interaction without changing the core task-and-comments model.
+
+### ⚪ Cloud deployments
+
+Local-first remains important, but Paperclip also needs a cleaner shared deployment story. Teams should be able to run the same product in hosted or semi-hosted environments without changing the mental model.
+
+### ⚪ Desktop App
+
+A desktop app can make Paperclip feel more accessible and persistent for day-to-day operators. The goal is easier access, better local ergonomics, and a smoother default experience for users who want the control plane always close at hand.
@@ -12,7 +12,7 @@
 <p align="center">
  <a href="https://github.com/paperclipai/paperclip/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License" /></a>
  <a href="https://github.com/paperclipai/paperclip/stargazers"><img src="https://img.shields.io/github/stars/paperclipai/paperclip?style=flat" alt="Stars" /></a>
-  <a href="https://discord.gg/m4HZY7xNG3"><img src="https://img.shields.io/badge/discord-join%20chat-5865F2?logo=discord&logoColor=white" alt="Discord" /></a>
+  <a href="https://discord.gg/m4HZY7xNG3"><img src="https://img.shields.io/discord/000000000?label=discord" alt="Discord" /></a>
 </p>

 <br/>
@@ -233,11 +233,15 @@ pnpm dev:once         # Full dev without file watching
 pnpm dev:server       # Server only
 pnpm build            # Build all
 pnpm typecheck        # Type checking
-pnpm test:run         # Run tests
+pnpm test             # Cheap default test run (Vitest only)
+pnpm test:watch       # Vitest watch mode
+pnpm test:e2e         # Playwright browser suite
 pnpm db:generate      # Generate DB migration
 pnpm db:migrate       # Apply migrations
 ```

+`pnpm test` does not run Playwright. Browser suites stay separate and are typically run only when working on those flows or in CI.
+
 See [doc/DEVELOPING.md](https://github.com/paperclipai/paperclip/blob/master/doc/DEVELOPING.md) for the full development guide.

 <br/>
@@ -3,11 +3,15 @@ import os from "node:os";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
+import { eq } from "drizzle-orm";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import {
  agents,
+  authUsers,
  companies,
  createDb,
+  issueComments,
+  issues,
  projects,
  routines,
  routineTriggers,
@@ -16,6 +20,7 @@ import {
  copyGitHooksToWorktreeGitDir,
  copySeededSecretsKey,
  pauseSeededScheduledRoutines,
+  quarantineSeededWorktreeExecutionState,
  readSourceAttachmentBody,
  rebindWorkspaceCwd,
  resolveSourceConfigPath,
@@ -23,6 +28,7 @@ import {
  resolveWorktreeReseedTargetPaths,
  resolveGitWorktreeAddArgs,
  resolveWorktreeMakeTargetPath,
+  worktreeRepairCommand,
  worktreeInitCommand,
  worktreeMakeCommand,
  worktreeReseedCommand,
@@ -46,6 +52,7 @@ import {
 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) {
@@ -279,6 +286,138 @@ describe("worktree helpers", () => {
    expect(full.nullifyColumns).toEqual({});
  });

+  itEmbeddedPostgres("quarantines copied live execution state in seeded worktree databases", async () => {
+    const tempDb = await startEmbeddedPostgresTestDatabase("paperclip-worktree-quarantine-");
+    const db = createDb(tempDb.connectionString);
+    const companyId = randomUUID();
+    const agentId = randomUUID();
+    const idleAgentId = randomUUID();
+    const inProgressIssueId = randomUUID();
+    const todoIssueId = randomUUID();
+    const reviewIssueId = randomUUID();
+    const userIssueId = randomUUID();
+
+    try {
+      await db.insert(companies).values({
+        id: companyId,
+        name: "Paperclip",
+        issuePrefix: "WTQ",
+        requireBoardApprovalForNewAgents: false,
+      });
+      await db.insert(agents).values([
+        {
+          id: agentId,
+          companyId,
+          name: "CodexCoder",
+          role: "engineer",
+          status: "running",
+          adapterType: "codex_local",
+          adapterConfig: {},
+          runtimeConfig: {
+            heartbeat: { enabled: true, intervalSec: 60 },
+            wakeOnDemand: true,
+          },
+          permissions: {},
+        },
+        {
+          id: idleAgentId,
+          companyId,
+          name: "Reviewer",
+          role: "reviewer",
+          status: "idle",
+          adapterType: "codex_local",
+          adapterConfig: {},
+          runtimeConfig: { heartbeat: { enabled: false, intervalSec: 300 } },
+          permissions: {},
+        },
+      ]);
+      await db.insert(issues).values([
+        {
+          id: inProgressIssueId,
+          companyId,
+          title: "Copied in-flight issue",
+          status: "in_progress",
+          priority: "medium",
+          assigneeAgentId: agentId,
+          issueNumber: 1,
+          identifier: "WTQ-1",
+          executionAgentNameKey: "codexcoder",
+          executionLockedAt: new Date("2026-04-18T00:00:00.000Z"),
+        },
+        {
+          id: todoIssueId,
+          companyId,
+          title: "Copied assigned todo issue",
+          status: "todo",
+          priority: "medium",
+          assigneeAgentId: agentId,
+          issueNumber: 2,
+          identifier: "WTQ-2",
+        },
+        {
+          id: reviewIssueId,
+          companyId,
+          title: "Copied assigned review issue",
+          status: "in_review",
+          priority: "medium",
+          assigneeAgentId: idleAgentId,
+          issueNumber: 3,
+          identifier: "WTQ-3",
+        },
+        {
+          id: userIssueId,
+          companyId,
+          title: "Copied user issue",
+          status: "todo",
+          priority: "medium",
+          assigneeUserId: "user-1",
+          issueNumber: 4,
+          identifier: "WTQ-4",
+        },
+      ]);
+
+      await expect(quarantineSeededWorktreeExecutionState(tempDb.connectionString)).resolves.toEqual({
+        disabledTimerHeartbeats: 1,
+        resetRunningAgents: 1,
+        quarantinedInProgressIssues: 1,
+        unassignedTodoIssues: 1,
+        unassignedReviewIssues: 1,
+      });
+
+      const [quarantinedAgent] = await db.select().from(agents).where(eq(agents.id, agentId));
+      expect(quarantinedAgent?.status).toBe("idle");
+      expect(quarantinedAgent?.runtimeConfig).toMatchObject({
+        heartbeat: { enabled: false, intervalSec: 60 },
+        wakeOnDemand: true,
+      });
+
+      const [inProgressIssue] = await db.select().from(issues).where(eq(issues.id, inProgressIssueId));
+      expect(inProgressIssue?.status).toBe("blocked");
+      expect(inProgressIssue?.assigneeAgentId).toBeNull();
+      expect(inProgressIssue?.executionAgentNameKey).toBeNull();
+      expect(inProgressIssue?.executionLockedAt).toBeNull();
+
+      const [todoIssue] = await db.select().from(issues).where(eq(issues.id, todoIssueId));
+      expect(todoIssue?.status).toBe("todo");
+      expect(todoIssue?.assigneeAgentId).toBeNull();
+
+      const [reviewIssue] = await db.select().from(issues).where(eq(issues.id, reviewIssueId));
+      expect(reviewIssue?.status).toBe("in_review");
+      expect(reviewIssue?.assigneeAgentId).toBeNull();
+
+      const [userIssue] = await db.select().from(issues).where(eq(issues.id, userIssueId));
+      expect(userIssue?.status).toBe("todo");
+      expect(userIssue?.assigneeUserId).toBe("user-1");
+
+      const comments = await db.select().from(issueComments).where(eq(issueComments.issueId, inProgressIssueId));
+      expect(comments).toHaveLength(1);
+      expect(comments[0]?.body).toContain("Quarantined during worktree seed");
+    } finally {
+      await db.$client?.end?.({ timeout: 5 }).catch(() => undefined);
+      await tempDb.cleanup();
+    }
+  }, 20_000);
+
  it("copies the source local_encrypted secrets key into the seeded worktree instance", () => {
    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-worktree-secrets-"));
    const originalInlineMasterKey = process.env.PAPERCLIP_SECRETS_MASTER_KEY;
@@ -372,6 +511,97 @@ describe("worktree helpers", () => {
    }
  });

+  itEmbeddedPostgres(
+    "seeds authenticated users into minimally cloned worktree instances",
+    async () => {
+      const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-worktree-auth-seed-"));
+      const worktreeRoot = path.join(tempRoot, "PAP-999-auth-seed");
+      const sourceHome = path.join(tempRoot, "source-home");
+      const sourceConfigDir = path.join(sourceHome, "instances", "source");
+      const sourceConfigPath = path.join(sourceConfigDir, "config.json");
+      const sourceEnvPath = path.join(sourceConfigDir, ".env");
+      const sourceKeyPath = path.join(sourceConfigDir, "secrets", "master.key");
+      const worktreeHome = path.join(tempRoot, ".paperclip-worktrees");
+      const originalCwd = process.cwd();
+      const sourceDb = await startEmbeddedPostgresTestDatabase("paperclip-worktree-auth-source-");
+
+      try {
+        const sourceDbClient = createDb(sourceDb.connectionString);
+        await sourceDbClient.insert(authUsers).values({
+          id: "user-existing",
+          email: "existing@paperclip.ing",
+          name: "Existing User",
+          emailVerified: true,
+          createdAt: new Date(),
+          updatedAt: new Date(),
+        });
+
+        fs.mkdirSync(path.dirname(sourceKeyPath), { recursive: true });
+        fs.mkdirSync(worktreeRoot, { recursive: true });
+
+        const sourceConfig = buildSourceConfig();
+        sourceConfig.database = {
+          mode: "postgres",
+          embeddedPostgresDataDir: path.join(sourceConfigDir, "db"),
+          embeddedPostgresPort: 54329,
+          backup: {
+            enabled: true,
+            intervalMinutes: 60,
+            retentionDays: 30,
+            dir: path.join(sourceConfigDir, "backups"),
+          },
+          connectionString: sourceDb.connectionString,
+        };
+        sourceConfig.logging.logDir = path.join(sourceConfigDir, "logs");
+        sourceConfig.storage.localDisk.baseDir = path.join(sourceConfigDir, "storage");
+        sourceConfig.secrets.localEncrypted.keyFilePath = sourceKeyPath;
+
+        fs.writeFileSync(sourceConfigPath, JSON.stringify(sourceConfig, null, 2) + "\n", "utf8");
+        fs.writeFileSync(sourceEnvPath, "", "utf8");
+        fs.writeFileSync(sourceKeyPath, "source-master-key", "utf8");
+
+        process.chdir(worktreeRoot);
+        await worktreeInitCommand({
+          name: "PAP-999-auth-seed",
+          home: worktreeHome,
+          fromConfig: sourceConfigPath,
+          force: true,
+        });
+
+        const targetConfig = JSON.parse(
+          fs.readFileSync(path.join(worktreeRoot, ".paperclip", "config.json"), "utf8"),
+        ) as PaperclipConfig;
+        const { default: EmbeddedPostgres } = await import("embedded-postgres");
+        const targetPg = new EmbeddedPostgres({
+          databaseDir: targetConfig.database.embeddedPostgresDataDir,
+          user: "paperclip",
+          password: "paperclip",
+          port: targetConfig.database.embeddedPostgresPort,
+          persistent: true,
+          initdbFlags: ["--encoding=UTF8", "--locale=C", "--lc-messages=C"],
+          onLog: () => {},
+          onError: () => {},
+        });
+
+        await targetPg.start();
+        try {
+          const targetDb = createDb(
+            `postgres://paperclip:paperclip@127.0.0.1:${targetConfig.database.embeddedPostgresPort}/paperclip`,
+          );
+          const seededUsers = await targetDb.select().from(authUsers);
+          expect(seededUsers.some((row) => row.email === "existing@paperclip.ing")).toBe(true);
+        } finally {
+          await targetPg.stop();
+        }
+      } finally {
+        process.chdir(originalCwd);
+        await sourceDb.cleanup();
+        fs.rmSync(tempRoot, { recursive: true, force: true });
+      }
+    },
+    20000,
+  );
+
  it("avoids ports already claimed by sibling worktree instance configs", async () => {
    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-worktree-claimed-ports-"));
    const repoRoot = path.join(tempRoot, "repo");
@@ -844,6 +1074,113 @@ describe("worktree helpers", () => {
      fs.rmSync(tempRoot, { recursive: true, force: true });
    }
  }, 20_000);
+
+  it("no-ops on the primary checkout unless --branch is provided", async () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-worktree-repair-primary-"));
+    const repoRoot = path.join(tempRoot, "repo");
+    const originalCwd = process.cwd();
+
+    try {
+      fs.mkdirSync(repoRoot, { recursive: true });
+      execFileSync("git", ["init"], { cwd: repoRoot, stdio: "ignore" });
+      execFileSync("git", ["config", "user.email", "test@example.com"], { cwd: repoRoot, stdio: "ignore" });
+      execFileSync("git", ["config", "user.name", "Test User"], { cwd: repoRoot, stdio: "ignore" });
+      fs.writeFileSync(path.join(repoRoot, "README.md"), "# temp\n", "utf8");
+      execFileSync("git", ["add", "README.md"], { cwd: repoRoot, stdio: "ignore" });
+      execFileSync("git", ["commit", "-m", "Initial commit"], { cwd: repoRoot, stdio: "ignore" });
+
+      process.chdir(repoRoot);
+      await worktreeRepairCommand({});
+
+      expect(fs.existsSync(path.join(repoRoot, ".paperclip", "config.json"))).toBe(false);
+      expect(fs.existsSync(path.join(repoRoot, ".paperclip", "worktrees"))).toBe(false);
+    } finally {
+      process.chdir(originalCwd);
+      fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("repairs the current linked worktree when Paperclip metadata is missing", async () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-worktree-repair-current-"));
+    const repoRoot = path.join(tempRoot, "repo");
+    const worktreePath = path.join(repoRoot, ".paperclip", "worktrees", "repair-me");
+    const sourceConfigPath = path.join(tempRoot, "source-config.json");
+    const worktreeHome = path.join(tempRoot, ".paperclip-worktrees");
+    const worktreePaths = resolveWorktreeLocalPaths({
+      cwd: worktreePath,
+      homeDir: worktreeHome,
+      instanceId: sanitizeWorktreeInstanceId(path.basename(worktreePath)),
+    });
+    const originalCwd = process.cwd();
+
+    try {
+      fs.mkdirSync(repoRoot, { recursive: true });
+      execFileSync("git", ["init"], { cwd: repoRoot, stdio: "ignore" });
+      execFileSync("git", ["config", "user.email", "test@example.com"], { cwd: repoRoot, stdio: "ignore" });
+      execFileSync("git", ["config", "user.name", "Test User"], { cwd: repoRoot, stdio: "ignore" });
+      fs.writeFileSync(path.join(repoRoot, "README.md"), "# temp\n", "utf8");
+      execFileSync("git", ["add", "README.md"], { cwd: repoRoot, stdio: "ignore" });
+      execFileSync("git", ["commit", "-m", "Initial commit"], { cwd: repoRoot, stdio: "ignore" });
+      fs.mkdirSync(path.dirname(worktreePath), { recursive: true });
+      execFileSync("git", ["worktree", "add", "-b", "repair-me", worktreePath, "HEAD"], {
+        cwd: repoRoot,
+        stdio: "ignore",
+      });
+
+      fs.writeFileSync(sourceConfigPath, JSON.stringify(buildSourceConfig(), null, 2), "utf8");
+      fs.mkdirSync(worktreePaths.instanceRoot, { recursive: true });
+      fs.writeFileSync(path.join(worktreePaths.instanceRoot, "marker.txt"), "stale", "utf8");
+
+      process.chdir(worktreePath);
+      await worktreeRepairCommand({
+        fromConfig: sourceConfigPath,
+        home: worktreeHome,
+        noSeed: true,
+      });
+
+      expect(fs.existsSync(path.join(worktreePath, ".paperclip", "config.json"))).toBe(true);
+      expect(fs.existsSync(path.join(worktreePath, ".paperclip", ".env"))).toBe(true);
+      expect(fs.existsSync(path.join(worktreePaths.instanceRoot, "marker.txt"))).toBe(false);
+    } finally {
+      process.chdir(originalCwd);
+      fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+  }, 20_000);
+
+  it("creates and repairs a missing branch worktree when --branch is provided", async () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-worktree-repair-branch-"));
+    const repoRoot = path.join(tempRoot, "repo");
+    const sourceConfigPath = path.join(tempRoot, "source-config.json");
+    const worktreeHome = path.join(tempRoot, ".paperclip-worktrees");
+    const originalCwd = process.cwd();
+    const expectedWorktreePath = path.join(repoRoot, ".paperclip", "worktrees", "feature-repair-me");
+
+    try {
+      fs.mkdirSync(repoRoot, { recursive: true });
+      execFileSync("git", ["init"], { cwd: repoRoot, stdio: "ignore" });
+      execFileSync("git", ["config", "user.email", "test@example.com"], { cwd: repoRoot, stdio: "ignore" });
+      execFileSync("git", ["config", "user.name", "Test User"], { cwd: repoRoot, stdio: "ignore" });
+      fs.writeFileSync(path.join(repoRoot, "README.md"), "# temp\n", "utf8");
+      execFileSync("git", ["add", "README.md"], { cwd: repoRoot, stdio: "ignore" });
+      execFileSync("git", ["commit", "-m", "Initial commit"], { cwd: repoRoot, stdio: "ignore" });
+      fs.writeFileSync(sourceConfigPath, JSON.stringify(buildSourceConfig(), null, 2), "utf8");
+
+      process.chdir(repoRoot);
+      await worktreeRepairCommand({
+        branch: "feature/repair-me",
+        fromConfig: sourceConfigPath,
+        home: worktreeHome,
+        noSeed: true,
+      });
+
+      expect(fs.existsSync(path.join(expectedWorktreePath, ".git"))).toBe(true);
+      expect(fs.existsSync(path.join(expectedWorktreePath, ".paperclip", "config.json"))).toBe(true);
+      expect(fs.existsSync(path.join(expectedWorktreePath, ".paperclip", ".env"))).toBe(true);
+    } finally {
+      process.chdir(originalCwd);
+      fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+  }, 20_000);
 });

 describeEmbeddedPostgres("pauseSeededScheduledRoutines", () => {
@@ -93,6 +93,7 @@ type WorktreeInitOptions = {
  dbPort?: number;
  seed?: boolean;
  seedMode?: string;
+  preserveLiveWork?: boolean;
  force?: boolean;
 };

@@ -126,10 +127,23 @@ type WorktreeReseedOptions = {
  fromDataDir?: string;
  fromInstance?: string;
  seedMode?: string;
+  preserveLiveWork?: boolean;
  yes?: boolean;
  allowLiveTarget?: boolean;
 };

+type WorktreeRepairOptions = {
+  branch?: string;
+  home?: string;
+  fromConfig?: string;
+  fromDataDir?: string;
+  fromInstance?: string;
+  seedMode?: string;
+  preserveLiveWork?: boolean;
+  noSeed?: boolean;
+  allowLiveTarget?: boolean;
+};
+
 type EmbeddedPostgresInstance = {
  initialise(): Promise<void>;
  start(): Promise<void>;
@@ -168,6 +182,8 @@ type CopiedGitHooksResult = {

 type SeedWorktreeDatabaseResult = {
  backupSummary: string;
+  pausedScheduledRoutines: number;
+  executionQuarantine: SeededWorktreeExecutionQuarantineSummary;
  reboundWorkspaces: Array<{
    name: string;
    fromCwd: string;
@@ -175,6 +191,14 @@ type SeedWorktreeDatabaseResult = {
  }>;
 };

+export type SeededWorktreeExecutionQuarantineSummary = {
+  disabledTimerHeartbeats: number;
+  resetRunningAgents: number;
+  quarantinedInProgressIssues: number;
+  unassignedTodoIssues: number;
+  unassignedReviewIssues: number;
+};
+
 function nonEmpty(value: string | null | undefined): string | null {
  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
 }
@@ -187,6 +211,18 @@ function isCurrentSourceConfigPath(sourceConfigPath: string): boolean {
  return path.resolve(currentConfigPath) === path.resolve(sourceConfigPath);
 }

+function formatSeededWorktreeExecutionQuarantineSummary(
+  summary: SeededWorktreeExecutionQuarantineSummary,
+): string {
+  return [
+    `disabled timer heartbeats: ${summary.disabledTimerHeartbeats}`,
+    `reset running agents: ${summary.resetRunningAgents}`,
+    `quarantined in-progress issues: ${summary.quarantinedInProgressIssues}`,
+    `unassigned todo issues: ${summary.unassignedTodoIssues}`,
+    `unassigned review issues: ${summary.unassignedReviewIssues}`,
+  ].join(", ");
+}
+
 const WORKTREE_NAME_PREFIX = "paperclip-";

 function resolveWorktreeMakeName(name: string): string {
@@ -550,6 +586,46 @@ function detectGitBranchName(cwd: string): string | null {
  }
 }

+function validateGitBranchName(cwd: string, branchName: string): string {
+  const value = nonEmpty(branchName);
+  if (!value) {
+    throw new Error("Branch name is required.");
+  }
+  try {
+    execFileSync("git", ["check-ref-format", "--branch", value], {
+      cwd,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+  } catch (error) {
+    throw new Error(`Invalid branch name "${branchName}": ${extractExecSyncErrorMessage(error) ?? String(error)}`);
+  }
+  return value;
+}
+
+function isPrimaryGitWorktree(cwd: string): boolean {
+  const workspace = detectGitWorkspaceInfo(cwd);
+  return Boolean(workspace && workspace.gitDir === workspace.commonDir);
+}
+
+function resolvePrimaryGitRepoRoot(cwd: string): string {
+  const workspace = detectGitWorkspaceInfo(cwd);
+  if (!workspace) {
+    throw new Error("Current directory is not inside a git repository.");
+  }
+  if (workspace.gitDir === workspace.commonDir) {
+    return workspace.root;
+  }
+  return path.resolve(workspace.commonDir, "..");
+}
+
+function resolveRepairWorktreeDirName(branchName: string): string {
+  const normalized = branchName.trim()
+    .replace(/[^A-Za-z0-9._-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^[-._]+|[-._]+$/g, "");
+  return normalized || "worktree";
+}
+
 function detectGitWorkspaceInfo(cwd: string): GitWorkspaceInfo | null {
  try {
    const root = execFileSync("git", ["rev-parse", "--show-toplevel"], {
@@ -773,6 +849,21 @@ export function resolveWorktreeReseedSource(input: WorktreeReseedOptions): Resol
  );
 }

+function resolveWorktreeRepairSource(input: WorktreeRepairOptions): ResolvedWorktreeReseedSource {
+  const fromConfig = nonEmpty(input.fromConfig);
+  const fromDataDir = nonEmpty(input.fromDataDir);
+  const fromInstance = nonEmpty(input.fromInstance) ?? "default";
+  const configPath = resolveSourceConfigPath({
+    fromConfig: fromConfig ?? undefined,
+    fromDataDir: fromDataDir ?? undefined,
+    fromInstance,
+  });
+  return {
+    configPath,
+    label: configPath,
+  };
+}
+
 export function resolveWorktreeReseedTargetPaths(input: {
  configPath: string;
  rootPath: string;
@@ -794,6 +885,105 @@ export function resolveWorktreeReseedTargetPaths(input: {
  });
 }

+function resolveExistingGitWorktree(selector: string, cwd: string): MergeSourceChoice | null {
+  const trimmed = selector.trim();
+  if (trimmed.length === 0) return null;
+
+  const directPath = path.resolve(trimmed);
+  if (existsSync(directPath)) {
+    return {
+      worktree: directPath,
+      branch: null,
+      branchLabel: path.basename(directPath),
+      hasPaperclipConfig: existsSync(path.resolve(directPath, ".paperclip", "config.json")),
+      isCurrent: directPath === path.resolve(cwd),
+    };
+  }
+
+  return toMergeSourceChoices(cwd).find((choice) =>
+    choice.worktree === directPath
+    || path.basename(choice.worktree) === trimmed
+    || choice.branchLabel === trimmed
+    || choice.branch === trimmed,
+  ) ?? null;
+}
+
+async function ensureRepairTargetWorktree(input: {
+  selector?: string;
+  seedMode: WorktreeSeedMode;
+  opts: WorktreeRepairOptions;
+}): Promise<ResolvedWorktreeRepairTarget | null> {
+  const cwd = process.cwd();
+  const currentRoot = path.resolve(cwd);
+  const currentConfigPath = path.resolve(currentRoot, ".paperclip", "config.json");
+
+  if (!input.selector) {
+    if (isPrimaryGitWorktree(cwd)) {
+      return null;
+    }
+    return {
+      rootPath: currentRoot,
+      configPath: currentConfigPath,
+      label: path.basename(currentRoot),
+      branchName: detectGitBranchName(cwd),
+      created: false,
+    };
+  }
+
+  const existing = resolveExistingGitWorktree(input.selector, cwd);
+  if (existing) {
+    return {
+      rootPath: existing.worktree,
+      configPath: path.resolve(existing.worktree, ".paperclip", "config.json"),
+      label: existing.branchLabel,
+      branchName: existing.branchLabel === "(detached)" ? null : existing.branchLabel,
+      created: false,
+    };
+  }
+
+  const repoRoot = resolvePrimaryGitRepoRoot(cwd);
+  const branchName = validateGitBranchName(repoRoot, input.selector);
+  const targetPath = path.resolve(
+    repoRoot,
+    ".paperclip",
+    "worktrees",
+    resolveRepairWorktreeDirName(branchName),
+  );
+
+  if (existsSync(targetPath)) {
+    throw new Error(`Target path already exists but is not a registered git worktree: ${targetPath}`);
+  }
+
+  mkdirSync(path.dirname(targetPath), { recursive: true });
+
+  const spinner = p.spinner();
+  spinner.start(`Creating git worktree for ${branchName}...`);
+  try {
+    execFileSync("git", resolveGitWorktreeAddArgs({
+      branchName,
+      targetPath,
+      branchExists: localBranchExists(repoRoot, branchName),
+    }), {
+      cwd: repoRoot,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    spinner.stop(`Created git worktree at ${targetPath}.`);
+  } catch (error) {
+    spinner.stop(pc.red("Failed to create git worktree."));
+    throw new Error(extractExecSyncErrorMessage(error) ?? String(error));
+  }
+
+  installDependenciesBestEffort(targetPath);
+
+  return {
+    rootPath: targetPath,
+    configPath: path.resolve(targetPath, ".paperclip", "config.json"),
+    label: branchName,
+    branchName,
+    created: true,
+  };
+}
+
 function resolveSourceConnectionString(config: PaperclipConfig, envEntries: Record<string, string>, portOverride?: number): string {
  if (config.database.mode === "postgres") {
    const connectionString = nonEmpty(envEntries.DATABASE_URL) ?? nonEmpty(config.database.connectionString);
@@ -954,6 +1144,133 @@ export async function pauseSeededScheduledRoutines(connectionString: string): Pr
  }
 }

+const EMPTY_SEEDED_WORKTREE_EXECUTION_QUARANTINE_SUMMARY: SeededWorktreeExecutionQuarantineSummary = {
+  disabledTimerHeartbeats: 0,
+  resetRunningAgents: 0,
+  quarantinedInProgressIssues: 0,
+  unassignedTodoIssues: 0,
+  unassignedReviewIssues: 0,
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function isEnabledValue(value: unknown): boolean {
+  return value === true || value === "true" || value === 1 || value === "1";
+}
+
+function normalizeWorktreeRuntimeConfig(runtimeConfig: unknown): {
+  runtimeConfig: Record<string, unknown>;
+  disabledTimerHeartbeat: boolean;
+  changed: boolean;
+} {
+  const nextRuntimeConfig = isRecord(runtimeConfig) ? { ...runtimeConfig } : {};
+  const heartbeat = isRecord(nextRuntimeConfig.heartbeat) ? { ...nextRuntimeConfig.heartbeat } : null;
+  if (!heartbeat) {
+    return { runtimeConfig: nextRuntimeConfig, disabledTimerHeartbeat: false, changed: false };
+  }
+
+  const disabledTimerHeartbeat = isEnabledValue(heartbeat.enabled);
+  if (heartbeat.enabled !== false) {
+    heartbeat.enabled = false;
+    nextRuntimeConfig.heartbeat = heartbeat;
+    return { runtimeConfig: nextRuntimeConfig, disabledTimerHeartbeat, changed: true };
+  }
+
+  return { runtimeConfig: nextRuntimeConfig, disabledTimerHeartbeat: false, changed: false };
+}
+
+export async function quarantineSeededWorktreeExecutionState(
+  connectionString: string,
+): Promise<SeededWorktreeExecutionQuarantineSummary> {
+  const db = createDb(connectionString);
+  const summary = { ...EMPTY_SEEDED_WORKTREE_EXECUTION_QUARANTINE_SUMMARY };
+  try {
+    await db.transaction(async (tx) => {
+      const seededAgents = await tx
+        .select({
+          id: agents.id,
+          status: agents.status,
+          runtimeConfig: agents.runtimeConfig,
+        })
+        .from(agents);
+
+      for (const agent of seededAgents) {
+        const normalized = normalizeWorktreeRuntimeConfig(agent.runtimeConfig);
+        const nextStatus = agent.status === "running" ? "idle" : agent.status;
+        if (normalized.disabledTimerHeartbeat) {
+          summary.disabledTimerHeartbeats += 1;
+        }
+        if (agent.status === "running") {
+          summary.resetRunningAgents += 1;
+        }
+        if (normalized.changed || nextStatus !== agent.status) {
+          await tx
+            .update(agents)
+            .set({
+              runtimeConfig: normalized.runtimeConfig,
+              status: nextStatus,
+              updatedAt: new Date(),
+            })
+            .where(eq(agents.id, agent.id));
+        }
+      }
+
+      const affectedIssues = await tx
+        .select({
+          id: issues.id,
+          companyId: issues.companyId,
+          status: issues.status,
+        })
+        .from(issues)
+        .where(
+          and(
+            sql`${issues.assigneeAgentId} is not null`,
+            sql`${issues.assigneeUserId} is null`,
+            inArray(issues.status, ["todo", "in_progress", "in_review"]),
+          ),
+        );
+
+      for (const issue of affectedIssues) {
+        const nextStatus = issue.status === "in_progress" ? "blocked" : issue.status;
+        await tx
+          .update(issues)
+          .set({
+            status: nextStatus,
+            assigneeAgentId: null,
+            checkoutRunId: null,
+            executionRunId: null,
+            executionAgentNameKey: null,
+            executionLockedAt: null,
+            executionWorkspaceId: null,
+            updatedAt: new Date(),
+          })
+          .where(eq(issues.id, issue.id));
+
+        if (issue.status === "in_progress") {
+          summary.quarantinedInProgressIssues += 1;
+          await tx.insert(issueComments).values({
+            companyId: issue.companyId,
+            issueId: issue.id,
+            body:
+              "Quarantined during worktree seed so copied in-flight work does not auto-run in this isolated instance. " +
+              "Reassign or unblock here only if you intentionally want the worktree instance to own this task.",
+          });
+        } else if (issue.status === "todo") {
+          summary.unassignedTodoIssues += 1;
+        } else if (issue.status === "in_review") {
+          summary.unassignedReviewIssues += 1;
+        }
+      }
+    });
+
+    return summary;
+  } finally {
+    await db.$client?.end?.({ timeout: 5 }).catch(() => undefined);
+  }
+}
+
 async function seedWorktreeDatabase(input: {
  sourceConfigPath: string;
  sourceConfig: PaperclipConfig;
@@ -961,6 +1278,7 @@ async function seedWorktreeDatabase(input: {
  targetPaths: WorktreeLocalPaths;
  instanceId: string;
  seedMode: WorktreeSeedMode;
+  preserveLiveWork?: boolean;
 }): Promise<SeedWorktreeDatabaseResult> {
  const seedPlan = resolveWorktreeSeedPlan(input.seedMode);
  const sourceEnvFile = resolvePaperclipEnvFile(input.sourceConfigPath);
@@ -1011,7 +1329,10 @@ async function seedWorktreeDatabase(input: {
      backupFile: backup.backupFile,
    });
    await applyPendingMigrations(targetConnectionString);
-    await pauseSeededScheduledRoutines(targetConnectionString);
+    const executionQuarantine = input.preserveLiveWork
+      ? { ...EMPTY_SEEDED_WORKTREE_EXECUTION_QUARANTINE_SUMMARY }
+      : await quarantineSeededWorktreeExecutionState(targetConnectionString);
+    const pausedScheduledRoutines = await pauseSeededScheduledRoutines(targetConnectionString);
    const reboundWorkspaces = await rebindSeededProjectWorkspaces({
      targetConnectionString,
      currentCwd: input.targetPaths.cwd,
@@ -1019,6 +1340,8 @@ async function seedWorktreeDatabase(input: {

    return {
      backupSummary: formatDatabaseBackupResult(backup),
+      pausedScheduledRoutines,
+      executionQuarantine,
      reboundWorkspaces,
    };
  } finally {
@@ -1097,6 +1420,8 @@ async function runWorktreeInit(opts: WorktreeInitOptions): Promise<void> {
  const copiedGitHooks = copyGitHooksToWorktreeGitDir(cwd);

  let seedSummary: string | null = null;
+  let seedExecutionQuarantineSummary: SeededWorktreeExecutionQuarantineSummary | null = null;
+  let pausedScheduledRoutineCount: number | null = null;
  let reboundWorkspaceSummary: SeedWorktreeDatabaseResult["reboundWorkspaces"] = [];
  if (opts.seed !== false) {
    if (!sourceConfig) {
@@ -1114,8 +1439,11 @@ async function runWorktreeInit(opts: WorktreeInitOptions): Promise<void> {
        targetPaths: paths,
        instanceId,
        seedMode,
+        preserveLiveWork: opts.preserveLiveWork,
      });
      seedSummary = seeded.backupSummary;
+      seedExecutionQuarantineSummary = seeded.executionQuarantine;
+      pausedScheduledRoutineCount = seeded.pausedScheduledRoutines;
      reboundWorkspaceSummary = seeded.reboundWorkspaces;
      spinner.stop(`Seeded isolated worktree database (${seedMode}).`);
    } catch (error) {
@@ -1138,6 +1466,16 @@ async function runWorktreeInit(opts: WorktreeInitOptions): Promise<void> {
  if (seedSummary) {
    p.log.message(pc.dim(`Seed mode: ${seedMode}`));
    p.log.message(pc.dim(`Seed snapshot: ${seedSummary}`));
+    if (opts.preserveLiveWork) {
+      p.log.warning("Preserved copied live work; this worktree instance may auto-run source-instance assignments.");
+    } else if (seedExecutionQuarantineSummary) {
+      p.log.message(
+        pc.dim(`Seed execution quarantine: ${formatSeededWorktreeExecutionQuarantineSummary(seedExecutionQuarantineSummary)}`),
+      );
+    }
+    if (pausedScheduledRoutineCount != null) {
+      p.log.message(pc.dim(`Paused scheduled routines: ${pausedScheduledRoutineCount}`));
+    }
    for (const rebound of reboundWorkspaceSummary) {
      p.log.message(
        pc.dim(`Rebound workspace ${rebound.name}: ${rebound.fromCwd} -> ${rebound.toCwd}`),
@@ -1205,18 +1543,7 @@ export async function worktreeMakeCommand(nameArg: string, opts: WorktreeMakeOpt
    throw new Error(extractExecSyncErrorMessage(error) ?? String(error));
  }

-  const installSpinner = p.spinner();
-  installSpinner.start("Installing dependencies...");
-  try {
-    execFileSync("pnpm", ["install"], {
-      cwd: targetPath,
-      stdio: ["ignore", "pipe", "pipe"],
-    });
-    installSpinner.stop("Installed dependencies.");
-  } catch (error) {
-    installSpinner.stop(pc.yellow("Failed to install dependencies (continuing anyway)."));
-    p.log.warning(extractExecSyncErrorMessage(error) ?? String(error));
-  }
+  installDependenciesBestEffort(targetPath);

  const originalCwd = process.cwd();
  try {
@@ -1233,6 +1560,21 @@ export async function worktreeMakeCommand(nameArg: string, opts: WorktreeMakeOpt
  }
 }

+function installDependenciesBestEffort(targetPath: string): void {
+  const installSpinner = p.spinner();
+  installSpinner.start("Installing dependencies...");
+  try {
+    execFileSync("pnpm", ["install"], {
+      cwd: targetPath,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    installSpinner.stop("Installed dependencies.");
+  } catch (error) {
+    installSpinner.stop(pc.yellow("Failed to install dependencies (continuing anyway)."));
+    p.log.warning(extractExecSyncErrorMessage(error) ?? String(error));
+  }
+}
+
 type WorktreeCleanupOptions = {
  instance?: string;
  home?: string;
@@ -1266,6 +1608,14 @@ type ResolvedWorktreeReseedSource = {
  label: string;
 };

+type ResolvedWorktreeRepairTarget = {
+  rootPath: string;
+  configPath: string;
+  label: string;
+  branchName: string | null;
+  created: boolean;
+};
+
 function parseGitWorktreeList(cwd: string): GitWorktreeListEntry[] {
  const raw = execFileSync("git", ["worktree", "list", "--porcelain"], {
    cwd,
@@ -2707,10 +3057,7 @@ export async function worktreeMergeHistoryCommand(sourceArg: string | undefined,
  }
 }

-export async function worktreeReseedCommand(opts: WorktreeReseedOptions): Promise<void> {
-  printPaperclipCliBanner();
-  p.intro(pc.bgCyan(pc.black(" paperclipai worktree reseed ")));
-
+async function runWorktreeReseed(opts: WorktreeReseedOptions): Promise<void> {
  const seedMode = opts.seedMode ?? "full";
  if (!isWorktreeSeedMode(seedMode)) {
    throw new Error(`Unsupported seed mode "${seedMode}". Expected one of: minimal, full.`);
@@ -2773,11 +3120,20 @@ export async function worktreeReseedCommand(opts: WorktreeReseedOptions): Promis
      targetPaths,
      instanceId: targetPaths.instanceId,
      seedMode,
+      preserveLiveWork: opts.preserveLiveWork,
    });
    spinner.stop(`Reseeded ${targetEndpoint.label} (${seedMode}).`);
    p.log.message(pc.dim(`Source: ${source.configPath}`));
    p.log.message(pc.dim(`Target: ${targetEndpoint.configPath}`));
    p.log.message(pc.dim(`Seed snapshot: ${seeded.backupSummary}`));
+    if (opts.preserveLiveWork) {
+      p.log.warning("Preserved copied live work; this worktree instance may auto-run source-instance assignments.");
+    } else {
+      p.log.message(
+        pc.dim(`Seed execution quarantine: ${formatSeededWorktreeExecutionQuarantineSummary(seeded.executionQuarantine)}`),
+      );
+    }
+    p.log.message(pc.dim(`Paused scheduled routines: ${seeded.pausedScheduledRoutines}`));
    for (const rebound of seeded.reboundWorkspaces) {
      p.log.message(
        pc.dim(`Rebound workspace ${rebound.name}: ${rebound.fromCwd} -> ${rebound.toCwd}`),
@@ -2790,6 +3146,98 @@ export async function worktreeReseedCommand(opts: WorktreeReseedOptions): Promis
  }
 }

+export async function worktreeReseedCommand(opts: WorktreeReseedOptions): Promise<void> {
+  printPaperclipCliBanner();
+  p.intro(pc.bgCyan(pc.black(" paperclipai worktree reseed ")));
+  await runWorktreeReseed(opts);
+}
+
+export async function worktreeRepairCommand(opts: WorktreeRepairOptions): Promise<void> {
+  printPaperclipCliBanner();
+  p.intro(pc.bgCyan(pc.black(" paperclipai worktree repair ")));
+
+  const seedMode = opts.seedMode ?? "minimal";
+  if (!isWorktreeSeedMode(seedMode)) {
+    throw new Error(`Unsupported seed mode "${seedMode}". Expected one of: minimal, full.`);
+  }
+
+  const target = await ensureRepairTargetWorktree({
+    selector: nonEmpty(opts.branch) ?? undefined,
+    seedMode,
+    opts,
+  });
+  if (!target) {
+    p.log.warn("Current checkout is the primary repo worktree. Pass --branch to create or repair a linked worktree.");
+    p.outro(pc.yellow("No worktree repaired."));
+    return;
+  }
+
+  const source = resolveWorktreeRepairSource(opts);
+  if (!existsSync(source.configPath)) {
+    throw new Error(`Source config not found at ${source.configPath}.`);
+  }
+  if (path.resolve(source.configPath) === path.resolve(target.configPath)) {
+    throw new Error("Source and target Paperclip configs are the same. Use --from-config/--from-instance to point repair at a different source.");
+  }
+
+  const targetConfig = existsSync(target.configPath) ? readConfig(target.configPath) : null;
+  const targetEnvEntries = readPaperclipEnvEntries(resolvePaperclipEnvFile(target.configPath));
+  const targetHasWorktreeEnv = Boolean(
+    nonEmpty(targetEnvEntries.PAPERCLIP_HOME) && nonEmpty(targetEnvEntries.PAPERCLIP_INSTANCE_ID),
+  );
+
+  if (targetConfig && targetHasWorktreeEnv && opts.noSeed) {
+    p.log.message(pc.dim(`Target ${target.label} already has worktree-local config/env. Skipping reseed because --no-seed was passed.`));
+    p.outro(pc.green(`Worktree metadata already looks healthy for ${target.label}.`));
+    return;
+  }
+
+  if (targetConfig && targetHasWorktreeEnv) {
+    await runWorktreeReseed({
+      fromConfig: source.configPath,
+      to: target.rootPath,
+      seedMode,
+      preserveLiveWork: opts.preserveLiveWork,
+      yes: true,
+      allowLiveTarget: opts.allowLiveTarget,
+    });
+    return;
+  }
+
+  const repairInstanceId = sanitizeWorktreeInstanceId(path.basename(target.rootPath));
+  const repairPaths = resolveWorktreeLocalPaths({
+    cwd: target.rootPath,
+    homeDir: resolveWorktreeHome(opts.home),
+    instanceId: repairInstanceId,
+  });
+  const runningTargetPid = readRunningPostmasterPid(path.resolve(repairPaths.embeddedPostgresDataDir, "postmaster.pid"));
+  if (runningTargetPid && !opts.allowLiveTarget) {
+    throw new Error(
+      `Target worktree database appears to be running (pid ${runningTargetPid}). Stop Paperclip in ${target.rootPath} before repairing, or re-run with --allow-live-target if you want to override this guard.`,
+    );
+  }
+  if (runningTargetPid && opts.allowLiveTarget) {
+    p.log.warning(`Proceeding even though the target embedded PostgreSQL appears to be running (pid ${runningTargetPid}).`);
+  }
+
+  const originalCwd = process.cwd();
+  try {
+    process.chdir(target.rootPath);
+    await runWorktreeInit({
+      home: opts.home,
+      fromConfig: source.configPath,
+      fromDataDir: opts.fromDataDir,
+      fromInstance: opts.fromInstance,
+      seed: opts.noSeed ? false : true,
+      seedMode,
+      preserveLiveWork: opts.preserveLiveWork,
+      force: true,
+    });
+  } finally {
+    process.chdir(originalCwd);
+  }
+}
+
 export function registerWorktreeCommands(program: Command): void {
  const worktree = program.command("worktree").description("Worktree-local Paperclip instance helpers");

@@ -2806,6 +3254,7 @@ export function registerWorktreeCommands(program: Command): void {
    .option("--server-port <port>", "Preferred server port", (value) => Number(value))
    .option("--db-port <port>", "Preferred embedded Postgres port", (value) => Number(value))
    .option("--seed-mode <mode>", "Seed profile: minimal or full (default: minimal)", "minimal")
+    .option("--preserve-live-work", "Do not quarantine copied agent timers or assigned open issues in the seeded worktree", false)
    .option("--no-seed", "Skip database seeding from the source instance")
    .option("--force", "Replace existing repo-local config and isolated instance data", false)
    .action(worktreeMakeCommand);
@@ -2822,6 +3271,7 @@ export function registerWorktreeCommands(program: Command): void {
    .option("--server-port <port>", "Preferred server port", (value) => Number(value))
    .option("--db-port <port>", "Preferred embedded Postgres port", (value) => Number(value))
    .option("--seed-mode <mode>", "Seed profile: minimal or full (default: minimal)", "minimal")
+    .option("--preserve-live-work", "Do not quarantine copied agent timers or assigned open issues in the seeded worktree", false)
    .option("--no-seed", "Skip database seeding from the source instance")
    .option("--force", "Replace existing repo-local config and isolated instance data", false)
    .action(worktreeInitCommand);
@@ -2861,10 +3311,25 @@ export function registerWorktreeCommands(program: Command): void {
    .option("--from-data-dir <path>", "Source PAPERCLIP_HOME used when deriving the source config")
    .option("--from-instance <id>", "Source instance id when deriving the source config")
    .option("--seed-mode <mode>", "Seed profile: minimal or full (default: full)", "full")
+    .option("--preserve-live-work", "Do not quarantine copied agent timers or assigned open issues in the seeded worktree", false)
    .option("--yes", "Skip the destructive confirmation prompt", false)
    .option("--allow-live-target", "Override the guard that requires the target worktree DB to be stopped first", false)
    .action(worktreeReseedCommand);

+  worktree
+    .command("repair")
+    .description("Create or repair a linked worktree-local Paperclip instance without touching the primary checkout")
+    .option("--branch <name>", "Existing branch/worktree selector to repair, or a branch name to create under .paperclip/worktrees")
+    .option("--home <path>", `Home root for worktree instances (env: PAPERCLIP_WORKTREES_DIR, default: ${DEFAULT_WORKTREE_HOME})`)
+    .option("--from-config <path>", "Source config.json to seed from")
+    .option("--from-data-dir <path>", "Source PAPERCLIP_HOME used when deriving the source config")
+    .option("--from-instance <id>", "Source instance id when deriving the source config (default: default)")
+    .option("--seed-mode <mode>", "Seed profile: minimal or full (default: minimal)", "minimal")
+    .option("--preserve-live-work", "Do not quarantine copied agent timers or assigned open issues in the seeded worktree", false)
+    .option("--no-seed", "Repair metadata only and skip reseeding when bootstrapping a missing worktree config", false)
+    .option("--allow-live-target", "Override the guard that requires the target worktree DB to be stopped first", false)
+    .action(worktreeRepairCommand);
+
  program
    .command("worktree:cleanup")
    .description("Safely remove a worktree, its branch, and its isolated instance data")
@@ -142,3 +142,4 @@ This prevents lockout when a user migrates from long-running local trusted usage
 - implementation plan: `doc/plans/deployment-auth-mode-consolidation.md`
 - V1 contract: `doc/SPEC-implementation.md`
 - operator workflows: `doc/DEVELOPING.md` and `doc/CLI.md`
+- invite/join state map: `doc/spec/invite-flow.md`
@@ -79,6 +79,29 @@ Allow additional private hostnames (for example custom Tailscale hostnames):
 pnpm paperclipai allowed-hostname dotta-macbook-pro
 ```

+## Test Commands
+
+Use the cheap local default unless you are specifically working on browser flows:
+
+```sh
+pnpm test
+```
+
+`pnpm test` runs the Vitest suite only. For interactive Vitest watch mode use:
+
+```sh
+pnpm test:watch
+```
+
+Browser suites stay separate:
+
+```sh
+pnpm test:e2e
+pnpm test:release-smoke
+```
+
+These browser suites are intended for targeted local verification and CI, not the default agent/human test command.
+
 ## One-Command Local Run

 For a first-time local install, you can bootstrap and run in one command:
@@ -186,6 +209,8 @@ Seed modes:
 - `full` makes a full logical clone of the source instance
 - `--no-seed` creates an empty isolated instance

+Seeded worktree instances quarantine copied live execution by default for both `minimal` and `full` seeds. During restore, Paperclip disables copied agent timer heartbeats, resets copied `running` agents to `idle`, blocks and unassigns copied agent-owned `in_progress` issues, and unassigns copied agent-owned `todo`/`in_review` issues. This keeps a freshly booted worktree from starting agents for work already owned by the source instance. Pass `--preserve-live-work` only when you intentionally want the isolated worktree to resume copied assignments.
+
 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.

 `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.
@@ -199,6 +224,8 @@ That repo-local env also sets:
 - `PAPERCLIP_WORKTREE_COLOR=<hex-color>`

 The server/UI use those values for worktree-specific branding such as the top banner and dynamically colored favicon.
+Authenticated worktree servers also use the `PAPERCLIP_INSTANCE_ID` value to scope Better Auth cookie names.
+Browser cookies are shared by host rather than port, so this prevents logging into one `127.0.0.1:<port>` worktree from replacing another worktree server's session cookie.

 Print shell exports explicitly when needed:

@@ -239,7 +266,7 @@ paperclipai worktree init --force
 Repair an already-created repo-managed worktree and reseed its isolated instance from the main default install:

 ```sh
-cd ~/.paperclip/worktrees/PAP-884-ai-commits-component
+cd /path/to/paperclip/.paperclip/worktrees/PAP-884-ai-commits-component
 pnpm paperclipai worktree init --force --seed-mode minimal \
  --name PAP-884-ai-commits-component \
  --from-config ~/.paperclip/instances/default/config.json
@@ -247,6 +274,33 @@ pnpm paperclipai worktree init --force --seed-mode minimal \

 That rewrites the worktree-local `.paperclip/config.json` + `.paperclip/.env`, recreates the isolated instance under `~/.paperclip-worktrees/instances/<worktree-id>/`, and preserves the git worktree contents themselves.

+For an already-created worktree where you want the CLI to decide whether to rebuild missing worktree metadata or just reseed the isolated DB, use `worktree repair`.
+
+**`pnpm paperclipai worktree repair [options]`** — Repair the current linked worktree by default, or create/repair a named linked worktree under `.paperclip/worktrees/` when `--branch` is provided. The command never targets the primary checkout unless you explicitly pass `--branch`.
+
+| Option | Description |
+|---|---|
+| `--branch <name>` | Existing branch/worktree selector to repair, or a branch name to create under `.paperclip/worktrees` |
+| `--home <path>` | Home root for worktree instances (default: `~/.paperclip-worktrees`) |
+| `--from-config <path>` | Source config.json to seed from |
+| `--from-data-dir <path>` | Source `PAPERCLIP_HOME` used when deriving the source config |
+| `--from-instance <id>` | Source instance id when deriving the source config (default: `default`) |
+| `--seed-mode <mode>` | Seed profile: `minimal` or `full` (default: `minimal`) |
+| `--no-seed` | Repair metadata only when bootstrapping a missing worktree config |
+| `--allow-live-target` | Override the guard that requires the target worktree DB to be stopped first |
+
+Examples:
+
+```sh
+# From inside a linked worktree, rebuild missing .paperclip metadata and reseed it from the default instance.
+cd /path/to/paperclip/.paperclip/worktrees/PAP-1132-assistant-ui-pap-1131-make-issues-comments-be-like-a-chat
+pnpm paperclipai worktree repair
+
+# From the primary checkout, create or repair a linked worktree for a branch under .paperclip/worktrees/.
+cd /path/to/paperclip
+pnpm paperclipai worktree repair --branch PAP-1132-assistant-ui-pap-1131-make-issues-comments-be-like-a-chat
+```
+
 For an already-created worktree where you want to keep the existing repo-local config/env and only overwrite the isolated database, use `worktree reseed` instead. Stop the target worktree's Paperclip server first so the command can replace the DB safely.

 **`pnpm paperclipai worktree reseed [options]`** — Re-seed an existing worktree-local instance from another Paperclip instance or worktree while preserving the target worktree's current config, ports, and instance identity.
@@ -115,38 +115,6 @@ If the first real publish returns npm `E404`, check npm-side prerequisites befor
 - The initial publish must include `--access public` for a public scoped package.
 - npm also requires either account 2FA for publishing or a granular token that is allowed to bypass 2FA.

-### Manual first publish for `@paperclipai/mcp-server`
-
-If you need to publish only the MCP server package once by hand, use:
-
- `@paperclipai/mcp-server`
-
-Recommended flow from the repo root:
-
-```bash
-# optional sanity check: this 404s until the first publish exists
-npm view @paperclipai/mcp-server version
-
-# make sure the build output is fresh
-pnpm --filter @paperclipai/mcp-server build
-
-# confirm your local npm auth before the real publish
-npm whoami
-
-# safe preview of the exact publish payload
-cd packages/mcp-server
-pnpm publish --dry-run --no-git-checks --access public
-
-# real publish
-pnpm publish --no-git-checks --access public
-```
-
-Notes:
-
- Publish from `packages/mcp-server/`, not the repo root.
- If `npm view @paperclipai/mcp-server version` already returns the same version that is in [`packages/mcp-server/package.json`](../packages/mcp-server/package.json), do not republish. Bump the version or use the normal repo-wide release flow in [`scripts/release.sh`](../scripts/release.sh).
- The same npm-side prerequisites apply as above: valid npm auth, permission to publish to the `@paperclipai` scope, `--access public`, and the required publish auth/2FA policy.
-
 ## Version formats

 Paperclip uses calendar versions:
@@ -395,6 +395,8 @@ Side effects:
 - entering `done` sets `completed_at`
 - entering `cancelled` sets `cancelled_at`

+Detailed ownership, execution, blocker, and crash-recovery semantics are documented in `doc/execution-semantics.md`.
+
 ## 8.3 Approval Status

 - `pending -> approved | rejected | cancelled`
@@ -617,7 +619,7 @@ Per-agent schedule fields in `adapter_config`:

 - `enabled` boolean
 - `intervalSec` integer (minimum 30)
- `maxConcurrentRuns` fixed at `1` for V1
+- `maxConcurrentRuns` integer; new agents default to `5`

 Scheduler must skip invocation when:

@@ -0,0 +1,252 @@
+# Execution Semantics
+
+Status: Current implementation guide
+Date: 2026-04-13
+Audience: Product and engineering
+
+This document explains how Paperclip interprets issue assignment, issue status, execution runs, wakeups, parent/sub-issue structure, and blocker relationships.
+
+`doc/SPEC-implementation.md` remains the V1 contract. This document is the detailed execution model behind that contract.
+
+## 1. Core Model
+
+Paperclip separates four concepts that are easy to blur together:
+
+1. structure: parent/sub-issue relationships
+2. dependency: blocker relationships
+3. ownership: who is responsible for the issue now
+4. execution: whether the control plane currently has a live path to move the issue forward
+
+The system works best when those are kept separate.
+
+## 2. Assignee Semantics
+
+An issue has at most one assignee.
+
+- `assigneeAgentId` means the issue is owned by an agent
+- `assigneeUserId` means the issue is owned by a human board user
+- both cannot be set at the same time
+
+This is a hard invariant. Paperclip is single-assignee by design.
+
+## 3. Status Semantics
+
+Paperclip issue statuses are not just UI labels. They imply different expectations about ownership and execution.
+
+### `backlog`
+
+The issue is not ready for active work.
+
+- no execution expectation
+- no pickup expectation
+- safe resting state for future work
+
+### `todo`
+
+The issue is actionable but not actively claimed.
+
+- it may be assigned or unassigned
+- no checkout/execution lock is required yet
+- for agent-assigned work, Paperclip may still need a wake path to ensure the assignee actually sees it
+
+### `in_progress`
+
+The issue is actively owned work.
+
+- requires an assignee
+- for agent-owned issues, this is a strict execution-backed state
+- for user-owned issues, this is a human ownership state and is not backed by heartbeat execution
+
+For agent-owned issues, `in_progress` should not be allowed to become a silent dead state.
+
+### `blocked`
+
+The issue cannot proceed until something external changes.
+
+This is the right state for:
+
+- waiting on another issue
+- waiting on a human decision
+- waiting on an external dependency or system
+- work that automatic recovery could not safely continue
+
+### `in_review`
+
+Execution work is paused because the next move belongs to a reviewer or approver, not the current executor.
+
+### `done`
+
+The work is complete and terminal.
+
+### `cancelled`
+
+The work will not continue and is terminal.
+
+## 4. Agent-Owned vs User-Owned Execution
+
+The execution model differs depending on assignee type.
+
+### Agent-owned issues
+
+Agent-owned issues are part of the control plane's execution loop.
+
+- Paperclip can wake the assignee
+- Paperclip can track runs linked to the issue
+- Paperclip can recover some lost execution state after crashes/restarts
+
+### User-owned issues
+
+User-owned issues are not executed by the heartbeat scheduler.
+
+- Paperclip can track the ownership and status
+- Paperclip cannot rely on heartbeat/run semantics to keep them moving
+- stranded-work reconciliation does not apply to them
+
+This is why `in_progress` can be strict for agents without forcing the same runtime rules onto human-held work.
+
+## 5. Checkout and Active Execution
+
+Checkout is the bridge from issue ownership to active agent execution.
+
+- checkout is required to move an issue into agent-owned `in_progress`
+- `checkoutRunId` represents issue-ownership lock for the current agent run
+- `executionRunId` represents the currently active execution path for the issue
+
+These are related but not identical:
+
+- `checkoutRunId` answers who currently owns execution rights for the issue
+- `executionRunId` answers which run is actually live right now
+
+Paperclip already clears stale execution locks and can adopt some stale checkout locks when the original run is gone.
+
+## 6. Parent/Sub-Issue vs Blockers
+
+Paperclip uses two different relationships for different jobs.
+
+### Parent/Sub-Issue (`parentId`)
+
+This is structural.
+
+Use it for:
+
+- work breakdown
+- rollup context
+- explaining why a child issue exists
+- waking the parent assignee when all direct children become terminal
+
+Do not treat `parentId` as execution dependency by itself.
+
+### Blockers (`blockedByIssueIds`)
+
+This is dependency semantics.
+
+Use it for:
+
+- \"this issue cannot continue until that issue changes state\"
+- explicit waiting relationships
+- automatic wakeups when all blockers resolve
+
+If a parent is truly waiting on a child, model that with blockers. Do not rely on the parent/child relationship alone.
+
+## 7. Consistent Execution Path Rules
+
+For agent-assigned, non-terminal, actionable issues, Paperclip should not leave work in a state where nobody is working it and nothing will wake it.
+
+The relevant execution path depends on status.
+
+### Agent-assigned `todo`
+
+This is dispatch state: ready to start, not yet actively claimed.
+
+A healthy dispatch state means at least one of these is true:
+
+- the issue already has a queued/running wake path
+- the issue is intentionally resting in `todo` after a successful agent heartbeat, not after an interrupted dispatch
+- the issue has been explicitly surfaced as stranded
+
+### Agent-assigned `in_progress`
+
+This is active-work state.
+
+A healthy active-work state means at least one of these is true:
+
+- there is an active run for the issue
+- there is already a queued continuation wake
+- the issue has been explicitly surfaced as stranded
+
+## 8. Crash and Restart Recovery
+
+Paperclip now treats crash/restart recovery as a stranded-assigned-work problem, not just a stranded-run problem.
+
+There are two distinct failure modes.
+
+### 8.1 Stranded assigned `todo`
+
+Example:
+
+- issue is assigned to an agent
+- status is `todo`
+- the original wake/run died during or after dispatch
+- after restart there is no queued wake and nothing picks the issue back up
+
+Recovery rule:
+
+- if the latest issue-linked run failed/timed out/cancelled and no live execution path remains, Paperclip queues one automatic assignment recovery wake
+- if that recovery wake also finishes and the issue is still stranded, Paperclip moves the issue to `blocked` and posts a visible comment
+
+This is a dispatch recovery, not a continuation recovery.
+
+### 8.2 Stranded assigned `in_progress`
+
+Example:
+
+- issue is assigned to an agent
+- status is `in_progress`
+- the live run disappeared
+- after restart there is no active run and no queued continuation
+
+Recovery rule:
+
+- Paperclip queues one automatic continuation wake
+- if that continuation wake also finishes and the issue is still stranded, Paperclip moves the issue to `blocked` and posts a visible comment
+
+This is an active-work continuity recovery.
+
+## 9. Startup and Periodic Reconciliation
+
+Startup recovery and periodic recovery are different from normal wakeup delivery.
+
+On startup and on the periodic recovery loop, Paperclip now does three things in sequence:
+
+1. reap orphaned `running` runs
+2. resume persisted `queued` runs
+3. reconcile stranded assigned work
+
+That last step is what closes the gap where issue state survives a crash but the wake/run path does not.
+
+## 10. What This Does Not Mean
+
+These semantics do not change V1 into an auto-reassignment system.
+
+Paperclip still does not:
+
+- automatically reassign work to a different agent
+- infer dependency semantics from `parentId` alone
+- treat human-held work as heartbeat-managed execution
+
+The recovery model is intentionally conservative:
+
+- preserve ownership
+- retry once when the control plane lost execution continuity
+- escalate visibly when the system cannot safely keep going
+
+## 11. Practical Interpretation
+
+For a board operator, the intended meaning is:
+
+- agent-owned `in_progress` should mean \"this is live work or clearly surfaced as a problem\"
+- agent-owned `todo` should not stay assigned forever after a crash with no remaining wake path
+- parent/sub-issue explains structure
+- blockers explain waiting
+
+That is the execution contract Paperclip should present to operators.
@@ -0,0 +1,382 @@
+# VS Code Task Interoperability Plan
+
+Status: planning only, no code changes
+Date: 2026-04-12
+Related issue: `PAP-1377`
+
+## Summary
+
+Paperclip should not replace its workspace runtime service model with VS Code tasks.
+It should add a narrow interoperability layer that can discover and adopt supported entries from `.vscode/tasks.json`.
+
+The core product model should stay:
+
+- Paperclip owns long-running workspace services and their desired state
+- Paperclip shows operators exactly which named thing they are starting or stopping
+- Paperclip distinguishes long-running services from one-shot jobs
+
+VS Code tasks should be treated as:
+
+- an import/discovery format for workspace commands
+- a convenience for repos that already maintain `tasks.json`
+- a partial compatibility layer, not a full execution model
+
+## Current State
+
+The current implementation is already service-oriented:
+
+- project workspaces and execution workspaces can store `workspaceRuntime` config plus `desiredState` and per-service `serviceStates`
+- the UI renders one control row per configured service and persists start/stop intent
+- the backend supervises long-running local processes, reuses eligible services, and restores desired services on startup
+
+Relevant files:
+
+- `packages/shared/src/types/workspace-runtime.ts`
+- `server/src/services/workspace-runtime.ts`
+- `server/src/services/project-workspace-runtime-config.ts`
+- `ui/src/components/WorkspaceRuntimeControls.tsx`
+- `ui/src/pages/ProjectWorkspaceDetail.tsx`
+- `ui/src/pages/ExecutionWorkspaceDetail.tsx`
+
+This is directionally correct for Paperclip because it gives the control plane an explicit model for service lifecycle, health, reuse, and restart behavior.
+
+## Problem To Solve
+
+The current UX is still too raw:
+
+- operators have to hand-author runtime JSON
+- a workspace can have multiple attached services, but the higher-level intent is not obvious
+- start/stop controls are visible in multiple places, which makes it easy to lose track of what is being controlled
+- there is no interoperability with repos that already define useful local workflows in `.vscode/tasks.json`
+
+The issue is not that services are the wrong abstraction.
+The issue is that the configuration surface is too low-level and Paperclip does not yet leverage existing workspace metadata.
+
+## Recommendation
+
+Keep Paperclip runtime services as the source of truth for service supervision.
+Add a new workspace command model above the raw JSON layer, with VS Code task discovery as one input.
+
+The product model should become:
+
+1. `Workspace command`
+   A named runnable thing attached to a workspace.
+
+2. `Workspace service`
+   A workspace command that is expected to stay alive and be supervised.
+
+3. `Workspace job`
+   A workspace command that runs once and exits.
+
+4. `Runtime service instance`
+   The live process record that already exists today in Paperclip.
+
+In that model, VS Code tasks are a way to populate workspace commands.
+Only commands that map cleanly to Paperclip service or job semantics should become runnable in Paperclip.
+
+## Why Not Fully Adopt VS Code Tasks
+
+VS Code tasks are broader than Paperclip runtime services.
+They include shell/process tasks, compound tasks, background/watch tasks, presentation settings, extension/task-provider types, variable substitution, and problem-matcher-driven lifecycle.
+
+That creates a bad fit if Paperclip tries to use `tasks.json` as its only runtime model:
+
+- many tasks are one-shot jobs, not long-running services
+- some tasks depend on VS Code task providers or editor-only variable resolution
+- compound task graphs are useful, but they are not the same thing as a supervised service
+- problem matcher readiness is useful metadata, but it is not enough to replace Paperclip's persisted service lifecycle model
+
+The right boundary is interoperability, not replacement.
+
+## Interoperability Contract
+
+Paperclip should support a conservative subset of VS Code tasks and clearly mark unsupported entries.
+
+### Supported in phase 1
+
+- `shell` and `process` tasks with a concrete command Paperclip can resolve
+- optional task `options.cwd`
+- optional task environment values that can be flattened safely
+- task labels and detail text for naming and display
+- `dependsOn` for import-time expansion or display-only dependency hints
+- background/watch-oriented tasks that can reasonably be treated as long-running services
+
+### Maybe supported in later phases
+
+- grouping and default task metadata for better UX
+- selected variable substitution when Paperclip can resolve it safely from workspace context
+- mapping task metadata into Paperclip readiness/expose hints
+- limited compound-task launch flows
+
+### Not supported initially
+
+- extension-provided task types Paperclip cannot execute directly
+- arbitrary VS Code variable substitution semantics
+- problem matcher parsing as the main source of service health
+- full parity with VS Code task execution behavior
+
+## Long-Running Service Detection
+
+Paperclip needs an explicit classification layer instead of assuming every VS Code task is a service.
+
+Recommended classification:
+
+- `service`
+  Explicitly marked by Paperclip metadata, or confidently inferred from background/watch task semantics
+
+- `job`
+  One-shot command expected to exit
+
+- `unsupported`
+  Present in `tasks.json`, but not safely runnable by Paperclip
+
+The important product decision is that service classification must be visible and editable by the operator.
+Inference can help, but it should not be the only source of truth.
+
+## Proposed Product Shape
+
+### 1. Replace raw-first editing with command-first editing
+
+Project and execution workspace pages should stop making raw runtime JSON the primary editing surface.
+
+Default UI should show:
+
+- workspace commands
+- command type: service or job
+- source: Paperclip or VS Code
+- exact command and cwd
+- current state for services
+- explicit start, stop, restart, and run-now actions
+
+Raw JSON should remain available behind an advanced section.
+
+### 2. Add VS Code task discovery on workspaces
+
+For a workspace with `cwd`, Paperclip should look for `.vscode/tasks.json`.
+
+The workspace UI should show:
+
+- whether a `tasks.json` file was found
+- last parse time
+- supported commands discovered
+- unsupported tasks with reasons
+- whether commands are inherited into execution workspaces
+
+### 3. Make the controlled thing explicit
+
+Start and stop UI should always name the exact entry being controlled.
+
+Examples:
+
+- `Start web`
+- `Stop api`
+- `Run db:migrate`
+
+Avoid generic workspace-level labels when multiple commands exist.
+
+### 4. Separate services from jobs in the UI
+
+Do not mix one-shot jobs and long-running services into one undifferentiated list.
+
+Recommended sections:
+
+- `Services`
+- `Jobs`
+- `Unsupported imported tasks`
+
+That resolves the ambiguity called out in the issue.
+
+## Data Model Direction
+
+Do not replace `workspaceRuntime` immediately.
+Instead add a higher-level representation that can compile down to the existing runtime-service machinery.
+
+Suggested workspace metadata shape:
+
+```ts
+type WorkspaceCommandSource =
+  | { type: "paperclip" }
+  | { type: "vscode_task"; taskLabel: string; taskPath: ".vscode/tasks.json" };
+
+type WorkspaceCommandKind = "service" | "job";
+
+type WorkspaceCommandDefinition = {
+  id: string;
+  name: string;
+  kind: WorkspaceCommandKind;
+  source: WorkspaceCommandSource;
+  command: string | null;
+  cwd: string | null;
+  env?: Record<string, string> | null;
+  autoStart?: boolean;
+  serviceConfig?: {
+    lifecycle?: "shared" | "ephemeral";
+    reuseScope?: "project_workspace" | "execution_workspace" | "run";
+    readiness?: Record<string, unknown> | null;
+    expose?: Record<string, unknown> | null;
+  } | null;
+  importWarnings?: string[];
+  disabledReason?: string | null;
+};
+```
+
+`workspaceRuntime` can then become a derived or advanced representation for service-type commands until the rest of the system is migrated.
+
+## VS Code Mapping Rules
+
+Paperclip should map imported tasks with explicit, documented rules.
+
+Recommended rules:
+
+1. A task becomes a `job` by default.
+2. A task becomes a `service` only when:
+   - Paperclip metadata marks it as a service, or
+   - the task clearly represents a background/watch process and the operator confirms the classification.
+3. Unsupported tasks stay visible but disabled.
+4. Task labels become default command names.
+5. `dependsOn` is preserved as metadata, not silently flattened into hidden behavior.
+
+Paperclip-specific metadata can live in a namespaced field on the imported task definition, for example:
+
+```json
+{
+  "label": "web",
+  "type": "shell",
+  "command": "pnpm dev",
+  "isBackground": true,
+  "paperclip": {
+    "kind": "service",
+    "readiness": {
+      "type": "http",
+      "urlTemplate": "http://127.0.0.1:${port}"
+    },
+    "expose": {
+      "type": "url",
+      "urlTemplate": "http://127.0.0.1:${port}"
+    }
+  }
+}
+```
+
+That gives us interoperability without depending on VS Code-only semantics for service readiness and exposure.
+
+## Execution Policy
+
+Project workspaces should be the main place where imported commands are discovered and curated.
+Execution workspaces should inherit that curated command set by default, with optional issue-level overrides.
+
+Recommended precedence:
+
+1. execution workspace override
+2. project workspace command set
+3. imported VS Code tasks from the linked workspace
+4. advanced raw runtime fallback
+
+This matches the existing direction in `doc/plans/2026-03-10-workspace-strategy-and-git-worktrees.md`.
+
+## Implementation Plan
+
+### Phase 1: Discovery and read-only visibility
+
+Goal:
+show imported VS Code tasks in the workspace UI without changing runtime behavior.
+
+Work:
+
+- parse `.vscode/tasks.json` for project workspaces with local `cwd`
+- derive a list of candidate commands plus unsupported items
+- show source, label, command, cwd, and classification
+- show parse warnings and unsupported reasons
+
+Success condition:
+an operator can see what Paperclip would import and why.
+
+### Phase 2: Command model and explicit classification
+
+Goal:
+introduce a first-class workspace command layer above raw runtime JSON.
+
+Work:
+
+- add a persisted command definition model in workspace metadata or a dedicated table
+- allow operator edits to imported command classification
+- separate `service` and `job` in UI
+- keep existing runtime-service storage for live supervised processes
+
+Success condition:
+the workspace UI is command-first, and raw runtime JSON is advanced-only.
+
+### Phase 3: Service execution backed by existing runtime supervisor
+
+Goal:
+run supported imported service commands through the current Paperclip supervisor.
+
+Work:
+
+- compile service commands into the existing runtime service start/stop path
+- persist desired state per named command
+- keep startup restoration behavior for service commands
+- make the active command name explicit everywhere control actions appear
+
+Success condition:
+imported service commands behave like native Paperclip services once adopted.
+
+### Phase 4: Job execution and optional dependency handling
+
+Goal:
+support one-shot imported commands without pretending they are services.
+
+Work:
+
+- add `Run` actions for jobs
+- record output in workspace operations
+- optionally support simple `dependsOn` execution for jobs with clear logging
+
+Success condition:
+one-shot tasks are runnable, but they are not mixed into the service lifecycle model.
+
+### Phase 5: Adapter and execution workspace integration
+
+Goal:
+let agents and issue-scoped workspaces consume the curated command model consistently.
+
+Work:
+
+- expose inherited workspace commands to execution workspaces
+- allow issue-level selection of a default service command when relevant
+- make service selection explicit in issue and workspace views
+
+Success condition:
+agents, operators, and workspaces all refer to the same named commands.
+
+## Non-Goals
+
+- full VS Code task-runner parity
+- support for every VS Code task type
+- removal of Paperclip's own runtime supervision model
+- editor-dependent execution semantics inside the control plane
+
+## Risks
+
+- overfitting Paperclip to VS Code and making the model worse for non-VS-Code repos
+- misclassifying watch tasks as durable services
+- hiding too much detail and making debugging harder
+- allowing imported task graphs to become implicit magic
+
+These risks are manageable if the import layer stays explicit, conservative, and operator-editable.
+
+## Decision
+
+Paperclip should adopt VS Code tasks as an optional workspace command source, not as the canonical runtime model.
+
+The main UX change should be:
+
+- move from raw runtime JSON to named workspace commands
+- separate services from jobs
+- make the exact controlled command explicit
+- let `.vscode/tasks.json` pre-populate those commands when available
+
+## External References
+
+- VS Code tasks documentation: https://code.visualstudio.com/docs/debugtest/tasks
+- Existing Paperclip workspace plan: `doc/plans/2026-03-10-workspace-strategy-and-git-worktrees.md`
@@ -114,14 +114,14 @@ If the connection drops, the UI reconnects automatically.

 1. Enable timer wakeups (for example every 300s)
 2. Keep assignment wakeups on
-3. Use a focused prompt template
+3. Use a focused prompt template that tells agents to act in the same heartbeat, leave durable progress, and mark blocked work with an owner/action
 4. Watch run logs and adjust prompt/config over time

 ## 7.2 Event-driven loop (less constant polling)

 1. Disable timer or set a long interval
 2. Keep wake-on-assignment enabled
-3. Use on-demand wakeups for manual nudges
+3. Use child issues, comments, and on-demand wakeups for handoffs instead of loops that poll agents, sessions, or processes

 ## 7.3 Safety-first loop

@@ -0,0 +1,299 @@
+# Invite Flow State Map
+
+Status: Current implementation map
+Date: 2026-04-13
+
+This document maps the current invite creation and acceptance states implemented in:
+
+- `ui/src/pages/CompanyInvites.tsx`
+- `ui/src/pages/CompanySettings.tsx`
+- `ui/src/pages/InviteLanding.tsx`
+- `server/src/routes/access.ts`
+- `server/src/lib/join-request-dedupe.ts`
+
+## State Legend
+
+- Invite state: `active`, `revoked`, `accepted`, `expired`
+- Join request status: `pending_approval`, `approved`, `rejected`
+- Claim secret state for agent joins: `available`, `consumed`, `expired`
+- Invite type: `company_join` or `bootstrap_ceo`
+- Join type: `human`, `agent`, or `both`
+
+## Entity Lifecycle
+
+```mermaid
+flowchart TD
+  Board[Board user on invite screen]
+  HumanInvite[Create human company invite]
+  OpenClawInvite[Generate OpenClaw invite prompt]
+  Active[Invite state: active]
+  Revoked[Invite state: revoked]
+  Expired[Invite state: expired]
+  Accepted[Invite state: accepted]
+  BootstrapDone[Bootstrap accepted<br/>no join request]
+  HumanReuse{Matching human join request<br/>already exists for same user/email?}
+  HumanPending[Join request<br/>pending_approval]
+  HumanApproved[Join request<br/>approved]
+  HumanRejected[Join request<br/>rejected]
+  AgentPending[Agent join request<br/>pending_approval<br/>+ optional claim secret]
+  AgentApproved[Agent join request<br/>approved]
+  AgentRejected[Agent join request<br/>rejected]
+  ClaimAvailable[Claim secret available]
+  ClaimConsumed[Claim secret consumed]
+  ClaimExpired[Claim secret expired]
+  OpenClawReplay[Special replay path:<br/>accepted invite can be POSTed again<br/>for openclaw_gateway only]
+
+  Board --> HumanInvite --> Active
+  Board --> OpenClawInvite --> Active
+  Active --> Revoked: revoke
+  Active --> Expired: expiresAt passes
+
+  Active --> BootstrapDone: bootstrap_ceo accept
+  BootstrapDone --> Accepted
+
+  Active --> HumanReuse: human accept
+  HumanReuse --> HumanPending: reuse existing pending request
+  HumanReuse --> HumanApproved: reuse existing approved request
+  HumanReuse --> HumanPending: no reusable request<br/>create new request
+  HumanPending --> HumanApproved: board approves
+  HumanPending --> HumanRejected: board rejects
+  HumanPending --> Accepted
+  HumanApproved --> Accepted
+
+  Active --> AgentPending: agent accept
+  AgentPending --> Accepted
+  AgentPending --> AgentApproved: board approves
+  AgentPending --> AgentRejected: board rejects
+  AgentApproved --> ClaimAvailable: createdAgentId + claimSecretHash
+  ClaimAvailable --> ClaimConsumed: POST claim-api-key succeeds
+  ClaimAvailable --> ClaimExpired: secret expires
+
+  Accepted --> OpenClawReplay
+  OpenClawReplay --> AgentPending
+  OpenClawReplay --> AgentApproved
+```
+
+## Board-Side Screen States
+
+```mermaid
+stateDiagram-v2
+  [*] --> CompanySelection
+
+  CompanySelection --> NoCompany: no company selected
+  CompanySelection --> LoadingHistory: selectedCompanyId present
+  LoadingHistory --> HistoryError: listInvites failed
+  LoadingHistory --> Ready: listInvites succeeded
+
+  state Ready {
+    [*] --> EmptyHistory
+    EmptyHistory --> PopulatedHistory: invites exist
+    PopulatedHistory --> LoadingMore: View more
+    LoadingMore --> PopulatedHistory: next page loaded
+
+    PopulatedHistory --> RevokePending: Revoke active invite
+    RevokePending --> PopulatedHistory: revoke succeeded
+    RevokePending --> PopulatedHistory: revoke failed
+
+    EmptyHistory --> CreatePending: Create invite
+    PopulatedHistory --> CreatePending: Create invite
+    CreatePending --> LatestInviteVisible: create succeeded
+    CreatePending --> Ready: create failed
+    LatestInviteVisible --> CopiedToast: clipboard copy succeeded
+    LatestInviteVisible --> Ready: navigate away or refresh
+  }
+
+  CompanySelection --> OpenClawPromptReady: Company settings prompt generator
+  OpenClawPromptReady --> OpenClawPromptPending: Generate OpenClaw Invite Prompt
+  OpenClawPromptPending --> OpenClawSnippetVisible: prompt generated
+  OpenClawPromptPending --> OpenClawPromptReady: generation failed
+```
+
+## Invite Landing Screen States
+
+```mermaid
+stateDiagram-v2
+  [*] --> TokenGate
+
+  TokenGate --> InvalidToken: token missing
+  TokenGate --> Loading: token present
+  Loading --> InviteUnavailable: invite fetch failed or invite not returned
+  Loading --> CheckingAccess: signed-in session and invite.companyId
+  Loading --> InviteResolved: invite loaded without membership check
+  Loading --> AcceptedInviteSummary: invite already consumed<br/>but linked join request still exists
+
+  CheckingAccess --> RedirectToBoard: current user already belongs to company
+  CheckingAccess --> InviteResolved: membership check finished and no join-request summary state is active
+  CheckingAccess --> AcceptedInviteSummary: membership check finished and invite has joinRequestStatus
+
+  state InviteResolved {
+    [*] --> Branch
+    Branch --> AgentForm: company_join + allowedJoinTypes=agent
+    Branch --> InlineAuth: authenticated mode + no session + join is not agent-only
+    Branch --> AcceptReady: bootstrap invite or human-ready session/local_trusted
+
+    InlineAuth --> InlineAuth: toggle sign-up/sign-in
+    InlineAuth --> InlineAuth: auth validation or auth error message
+    InlineAuth --> RedirectToBoard: auth succeeded and company membership already exists
+    InlineAuth --> AcceptPending: auth succeeded and invite still needs acceptance
+
+    AgentForm --> AcceptPending: submit request
+    AgentForm --> AgentForm: validation or accept error
+
+    AcceptReady --> AcceptPending: Accept invite
+    AcceptReady --> AcceptReady: accept error
+  }
+
+  AcceptPending --> BootstrapComplete: bootstrapAccepted=true
+  AcceptPending --> RedirectToBoard: join status=approved
+  AcceptPending --> PendingApprovalResult: join status=pending_approval
+  AcceptPending --> RejectedResult: join status=rejected
+
+  state AcceptedInviteSummary {
+    [*] --> SummaryBranch
+    SummaryBranch --> PendingApprovalReload: joinRequestStatus=pending_approval
+    SummaryBranch --> OpeningCompany: joinRequestStatus=approved<br/>and human invite user is now a member
+    SummaryBranch --> RejectedReload: joinRequestStatus=rejected
+    SummaryBranch --> ConsumedReload: approved agent invite or other consumed state
+  }
+
+  PendingApprovalResult --> PendingApprovalReload: reload after submit
+  RejectedResult --> RejectedReload: reload after board rejects
+  RedirectToBoard --> OpeningCompany: brief pre-navigation render when approved membership is detected
+  OpeningCompany --> RedirectToBoard: navigate to board
+```
+
+## Sequence Diagrams
+
+### Human Invite Creation And First Acceptance
+
+```mermaid
+sequenceDiagram
+  autonumber
+  actor Board as Board user
+  participant Settings as Company Invites UI
+  participant API as Access routes
+  participant Invites as invites table
+  actor Invitee as Invite recipient
+  participant Landing as Invite landing UI
+  participant Auth as Auth session
+  participant Join as join_requests table
+
+  Board->>Settings: Choose role and click Create invite
+  Settings->>API: POST /api/companies/:companyId/invites
+  API->>Invites: Insert active invite
+  API-->>Settings: inviteUrl + metadata
+
+  Invitee->>Landing: Open invite URL
+  Landing->>API: GET /api/invites/:token
+  API->>Invites: Load active invite
+  API-->>Landing: Invite summary
+
+  alt Authenticated mode and no session
+    Landing->>Auth: Sign up or sign in
+    Auth-->>Landing: Session established
+  end
+
+  Landing->>API: POST /api/invites/:token/accept (requestType=human)
+  API->>Join: Look for reusable human join request
+  alt Reusable pending or approved request exists
+    API->>Invites: Mark invite accepted
+    API-->>Landing: Existing join request status
+  else No reusable request exists
+    API->>Invites: Mark invite accepted
+    API->>Join: Insert pending_approval join request
+    API-->>Landing: New pending_approval join request
+  end
+```
+
+### Human Approval And Reload Path
+
+```mermaid
+sequenceDiagram
+  autonumber
+  actor Invitee as Invite recipient
+  participant Landing as Invite landing UI
+  participant API as Access routes
+  participant Join as join_requests table
+  actor Approver as Company admin
+  participant Queue as Access queue UI
+  participant Membership as company_memberships + grants
+
+  Invitee->>Landing: Reload consumed invite URL
+  Landing->>API: GET /api/invites/:token
+  API->>Join: Load join request by inviteId
+  API-->>Landing: joinRequestStatus + joinRequestType
+
+  alt joinRequestStatus = pending_approval
+    Landing-->>Invitee: Show waiting-for-approval panel
+    Approver->>Queue: Review request in Company Settings -> Access
+    Queue->>API: POST /companies/:companyId/join-requests/:requestId/approve
+    API->>Membership: Ensure membership and grants
+    API->>Join: Mark join request approved
+    Invitee->>Landing: Refresh after approval
+    Landing->>API: GET /api/invites/:token
+    API->>Join: Reload approved join request
+    API-->>Landing: approved status
+    Landing-->>Invitee: Opening company and redirect
+  else joinRequestStatus = rejected
+    Landing-->>Invitee: Show rejected error panel
+  else joinRequestStatus = approved but membership missing
+    Landing-->>Invitee: Fall through to consumed/unavailable state
+  end
+```
+
+### Agent Invite Approval, Claim, And Replay
+
+```mermaid
+sequenceDiagram
+  autonumber
+  actor Board as Board user
+  participant Settings as Company Settings UI
+  participant API as Access routes
+  participant Invites as invites table
+  actor Gateway as OpenClaw gateway agent
+  participant Join as join_requests table
+  actor Approver as Company admin
+  participant Agents as agents table
+  participant Keys as agent_api_keys table
+
+  Board->>Settings: Generate OpenClaw invite prompt
+  Settings->>API: POST /api/companies/:companyId/openclaw-invite-prompt
+  API->>Invites: Insert active agent invite
+  API-->>Settings: Prompt text + invite token
+
+  Gateway->>API: POST /api/invites/:token/accept (agent, openclaw_gateway)
+  API->>Invites: Mark invite accepted
+  API->>Join: Insert pending_approval join request + claimSecretHash
+  API-->>Gateway: requestId + claimSecret + claimApiKeyPath
+
+  Approver->>API: POST /companies/:companyId/join-requests/:requestId/approve
+  API->>Agents: Create agent + membership + grants
+  API->>Join: Mark request approved and store createdAgentId
+
+  Gateway->>API: POST /api/join-requests/:requestId/claim-api-key (claimSecret)
+  API->>Keys: Create initial API key
+  API->>Join: Mark claim secret consumed
+  API-->>Gateway: Plaintext Paperclip API key
+
+  opt Replay accepted invite for updated gateway defaults
+    Gateway->>API: POST /api/invites/:token/accept again
+    API->>Join: Reuse existing approved or pending request
+    API->>Agents: Update approved agent adapter config when applicable
+    API-->>Gateway: Updated join request payload
+  end
+```
+
+## Notes
+
+- `GET /api/invites/:token` treats `revoked` and `expired` invites as unavailable. Accepted invites remain resolvable when they already have a linked join request, and the summary now includes `joinRequestStatus` plus `joinRequestType`.
+- Human acceptance consumes the invite immediately and then either creates a new join request or reuses an existing `pending_approval` or `approved` human join request for the same user/email.
+- The landing page has two layers of post-accept UI:
+  - immediate mutation-result UI from `POST /api/invites/:token/accept`
+  - reload-time summary UI from `GET /api/invites/:token` once the invite has already been consumed
+- Reload behavior for accepted company invites is now status-sensitive:
+  - `pending_approval` re-renders the waiting-for-approval panel
+  - `rejected` renders the "This join request was not approved." error panel
+  - `approved` only becomes a success path for human invites after membership is visible to the current session; otherwise the page falls through to the generic consumed/unavailable state
+- `GET /api/invites/:token/logo` still rejects accepted invites, so accepted-invite reload states may fall back to the generated company icon even though the summary payload still carries `companyLogoUrl`.
+- The only accepted-invite replay path in the current implementation is `POST /api/invites/:token/accept` for `agent` requests with `adapterType=openclaw_gateway`, and only when the existing join request is still `pending_approval` or already `approved`.
+- `bootstrap_ceo` invites are one-time and do not create join requests.
@@ -203,6 +203,43 @@ export const sessionCodec: AdapterSessionCodec = {
 };
 ```

+## Capability Flags
+
+Adapters can declare what "local" capabilities they support by setting optional fields on the `ServerAdapterModule`. The server and UI use these flags to decide which features to enable for agents using the adapter (instructions bundle editor, skills sync, JWT auth, etc.).
+
+| Flag | Type | Default | What it controls |
+|------|------|---------|------------------|
+| `supportsLocalAgentJwt` | `boolean` | `false` | Whether heartbeat generates a local JWT for the agent |
+| `supportsInstructionsBundle` | `boolean` | `false` | Managed instructions bundle (AGENTS.md) — server-side resolution + UI editor |
+| `instructionsPathKey` | `string` | `"instructionsFilePath"` | The `adapterConfig` key that holds the instructions file path |
+| `requiresMaterializedRuntimeSkills` | `boolean` | `false` | Whether runtime skill entries must be written to disk before execution |
+
+These flags are exposed via `GET /api/adapters` in a `capabilities` object, along with a derived `supportsSkills` flag (true when `listSkills` or `syncSkills` is defined).
+
+### Example
+
+```ts
+export function createServerAdapter(): ServerAdapterModule {
+  return {
+    type: "my_k8s_adapter",
+    execute: myExecute,
+    testEnvironment: myTestEnvironment,
+    listSkills: myListSkills,
+    syncSkills: mySyncSkills,
+
+    // Capability flags
+    supportsLocalAgentJwt: true,
+    supportsInstructionsBundle: true,
+    instructionsPathKey: "instructionsFilePath",
+    requiresMaterializedRuntimeSkills: true,
+  };
+}
+```
+
+With these flags set, the Paperclip UI will automatically show the instructions bundle editor, skills management tab, and working directory field for agents using this adapter — no Paperclip source changes required.
+
+If capability flags are not set, the server falls back to legacy hardcoded lists for built-in adapter types. External adapters that omit the flags will default to `false` for all capabilities.
+
 ## Skills Injection

 Make Paperclip skills discoverable to your agent runtime without writing to the agent's working directory:
@@ -124,14 +124,14 @@ If the connection drops, the UI reconnects automatically.

 1. Enable timer wakeups (for example every 300s)
 2. Keep assignment wakeups on
-3. Use a focused prompt template
+3. Use a focused prompt template that tells agents to act in the same heartbeat, leave durable progress, and mark blocked work with an owner/action
 4. Watch run logs and adjust prompt/config over time

 ## 7.2 Event-driven loop (less constant polling)

 1. Disable timer or set a long interval
 2. Keep wake-on-assignment enabled
-3. Use on-demand wakeups for manual nudges
+3. Use child issues, comments, and on-demand wakeups for handoffs instead of loops that poll agents, sessions, or processes

 ## 7.3 Safety-first loop

@@ -13,6 +13,8 @@ GET /api/companies/{companyId}/agents

 Returns all agents in the company.

+This route does not accept query filters. Unsupported query parameters return `400`.
+
 ## Get Agent

 ```
@@ -66,6 +66,8 @@ The optional `comment` field adds a comment in the same call.

 Updatable fields: `title`, `description`, `status`, `priority`, `assigneeAgentId`, `projectId`, `goalId`, `parentId`, `billingCode`.

+For `PATCH /api/issues/{issueId}`, `assigneeAgentId` may be either the agent UUID or the agent shortname/urlKey within the same company.
+
 ## Checkout (Claim Task)

 ```
@@ -18,6 +18,7 @@ All environment variables that Paperclip uses for server configuration.
 | `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` |
+| `PAPERCLIP_API_URL` | (auto-derived) | Paperclip API base URL. When set externally (e.g., via Kubernetes ConfigMap, load balancer, or reverse proxy), the server preserves the value instead of deriving it from the listen host and port. Useful for deployments where the public-facing URL differs from the local bind address. |

 ## Secrets

@@ -35,7 +36,7 @@ These are set automatically by the server when invoking agents:
 |----------|-------------|
 | `PAPERCLIP_AGENT_ID` | Agent's unique ID |
 | `PAPERCLIP_COMPANY_ID` | Company ID |
-| `PAPERCLIP_API_URL` | Paperclip API base URL |
+| `PAPERCLIP_API_URL` | Paperclip API base URL (inherits the server-level value; see Server Configuration above) |
 | `PAPERCLIP_API_KEY` | Short-lived JWT for API auth |
 | `PAPERCLIP_RUN_ID` | Current heartbeat run ID |
 | `PAPERCLIP_TASK_ID` | Issue that triggered this wake |
@@ -48,6 +48,8 @@
              "guides/board-operator/managing-tasks",
              "guides/board-operator/execution-workspaces-and-runtime-services",
              "guides/board-operator/delegation",
+              "guides/board-operator/execution-workspaces-and-runtime-services",
+              "guides/board-operator/delegation",
              "guides/board-operator/approvals",
              "guides/board-operator/costs-and-budgets",
              "guides/board-operator/activity-log",
@@ -66,7 +66,9 @@ Read ancestors to understand why this task exists. If woken by a specific commen

 ### Step 7: Do the Work

-Use your tools and capabilities to complete the task.
+Use your tools and capabilities to complete the task. If the issue is actionable, take a concrete action in the same heartbeat. Do not stop at a plan unless the issue asked for planning.
+
+Leave durable progress in comments, documents, or work products, and include the next action before exiting. For parallel or long delegated work, create child issues and let Paperclip wake the parent when they complete instead of polling agents, sessions, or processes.

 ### Step 8: Update Status

@@ -102,6 +104,22 @@ Always set `parentId` and `goalId` on subtasks.
 - **Always checkout** before working — never PATCH to `in_progress` manually
 - **Never retry a 409** — the task belongs to someone else
 - **Always comment** on in-progress work before exiting a heartbeat
+- **Start actionable work** in the same heartbeat; planning-only exits are for planning tasks
+- **Leave a clear next action** in durable issue context
+- **Use child issues instead of polling** for long or parallel delegated work
 - **Always set parentId** on subtasks
 - **Never cancel cross-team tasks** — reassign to your manager
 - **Escalate when stuck** — use your chain of command
+
+## Run Liveness
+
+Paperclip records run liveness as metadata on heartbeat runs. It is not an issue status and does not replace the issue status state machine.
+
+- Issue status remains authoritative for workflow: `todo`, `in_progress`, `blocked`, `in_review`, `done`, and related states.
+- Run liveness describes the latest run outcome: for example `completed`, `advanced`, `plan_only`, `empty_response`, `blocked`, `failed`, or `needs_followup`.
+- Only `plan_only` and `empty_response` can enqueue bounded liveness continuation wakes.
+- Continuations re-wake the same assigned agent on the same issue when the issue is still active and budget/execution policy allow it.
+- `continuationAttempt` counts semantic liveness continuations for a source run chain. It is separate from process recovery, queued wake delivery, adapter session resume, and other operational retries.
+- Liveness continuation wake prompts include the attempt, source run, liveness state, liveness reason, and the instruction for the next heartbeat.
+- Continuations do not mark the issue `blocked` or `done`. If automatic continuations are exhausted, Paperclip leaves an audit comment so a human or manager can clarify, block, or assign follow-up work.
+- Workspace provisioning alone is not treated as concrete task progress. Durable progress should appear as tool/action events, issue comments, document or work-product revisions, activity log entries, commits, or tests.
@@ -5,22 +5,28 @@ summary: How project runtime configuration, execution workspaces, and issue runs

 This guide documents the intended runtime model for projects, execution workspaces, and issue runs in Paperclip.

+Paperclip now presents this as a workspace-command model:
+
+- `Services` are long-running commands that stay supervised.
+- `Jobs` are one-shot commands that run once and exit.
+- Raw runtime JSON is still available for advanced config, but it is no longer the primary mental model.
+
 ## Project runtime configuration

 You can define how to run a project on the project workspace itself.

- Project workspace runtime config describes how to run services for that project checkout.
+- Project workspace runtime config describes the services and jobs available for that project checkout.
 - This is the default runtime configuration that child execution workspaces may inherit.
 - Defining the config does not start anything by itself.

 ## Manual runtime control

-Runtime services are manually controlled from the UI.
+Workspace commands are manually controlled from the UI.

- Project workspace runtime services are started and stopped from the project workspace UI.
- Execution workspace runtime services are started and stopped from the execution workspace UI.
- Paperclip does not automatically start or stop these runtime services as part of issue execution.
- Paperclip also does not automatically restart workspace runtime services on server boot.
+- Project workspace services are started and stopped from the project workspace UI, and project jobs can be run on demand there.
+- Execution workspace services are started and stopped from the execution workspace UI, and execution-workspace jobs can be run on demand there.
+- Paperclip does not automatically start or stop these workspace services as part of issue execution.
+- Paperclip also does not automatically restart workspace services on server boot.

 ## Execution workspace inheritance

@@ -29,7 +35,7 @@ Execution workspaces isolate code and runtime state from the project primary wor
 - An isolated execution workspace has its own checkout path, branch, and local runtime instance.
 - The runtime configuration may inherit from the linked project workspace by default.
 - The execution workspace may override that runtime configuration with its own workspace-specific settings.
- The inherited configuration answers "how to run the service", but the running process is still specific to that execution workspace.
+- The inherited configuration answers "which commands exist and how to run them", but any running service process is still specific to that execution workspace.

 ## Issues and execution workspaces

@@ -38,7 +44,7 @@ Issues are attached to execution workspace behavior, not to automatic runtime ma
 - An issue may create a new execution workspace when you choose an isolated workspace mode.
 - An issue may reuse an existing execution workspace when you choose reuse.
 - Multiple issues may intentionally share one execution workspace so they can work against the same branch and running runtime services.
- Assigning or running an issue does not automatically start or stop runtime services for that workspace.
+- Assigning or running an issue does not automatically start or stop workspace services for that workspace.

 ## Execution workspace lifecycle

@@ -62,7 +68,7 @@ Heartbeat still resolves a workspace for the run, but that is about code locatio

 With the current implementation:

- Project workspace runtime config is the fallback for execution workspace UI controls.
+- Project workspace command config is the fallback for execution workspace UI controls.
 - Execution workspace runtime overrides are stored on the execution workspace.
- Heartbeat runs do not auto-start workspace runtime services.
- Server startup does not auto-restart workspace runtime services.
+- Heartbeat runs do not auto-start workspace services.
+- Server startup does not auto-restart workspace services.
@@ -20,6 +20,13 @@ The Heartbeat Procedure:
 8. Update status: PATCH /api/issues/{issueId} with status and comment
 9. Delegate if needed: POST /api/companies/{companyId}/issues

+Execution Contract:
+- If the issue is actionable, start concrete work in this heartbeat. Do not stop at a plan unless the issue asks for planning.
+- Leave durable progress in comments, documents, or work products, with a clear next action.
+- Use child issues for parallel or long delegated work instead of polling agents, sessions, or processes.
+- If blocked, PATCH the issue to blocked and name the unblock owner and action.
+- Respect budget, pause/cancel, approval gates, and company boundaries.
+
 Critical Rules:
 - Always checkout before working. Never PATCH to in_progress manually.
 - Never retry a 409. The task belongs to someone else.
@@ -13,7 +13,8 @@
    "dev:ui": "pnpm --filter @paperclipai/ui dev",
    "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": "pnpm run test:run",
+    "test:watch": "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",
@@ -33,6 +34,7 @@
    "smoke:openclaw-sse-standalone": "./scripts/smoke/openclaw-sse-standalone.sh",
    "test:e2e": "npx playwright test --config tests/e2e/playwright.config.ts",
    "test:e2e:headed": "npx playwright test --config tests/e2e/playwright.config.ts --headed",
+    "test:e2e:multiuser-authenticated": "npx playwright test --config tests/e2e/playwright-multiuser-authenticated.config.ts",
    "evals:smoke": "cd evals/promptfoo && npx promptfoo@0.103.3 eval",
    "test:release-smoke": "npx playwright test --config tests/release-smoke/playwright.config.ts",
    "test:release-smoke:headed": "npx playwright test --config tests/release-smoke/playwright.config.ts --headed",
@@ -1,6 +1,12 @@
 import { randomUUID } from "node:crypto";
 import { describe, expect, it } from "vitest";
-import { runChildProcess } from "./server-utils.js";
+import {
+  appendWithByteCap,
+  DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,
+  renderPaperclipWakePrompt,
+  runChildProcess,
+  stringifyPaperclipWakePayload,
+} from "./server-utils.js";

 function isPidAlive(pid: number) {
  try {
@@ -21,6 +27,25 @@ async function waitForPidExit(pid: number, timeoutMs = 2_000) {
 }

 describe("runChildProcess", () => {
+  it("does not arm a timeout when timeoutSec is 0", async () => {
+    const result = await runChildProcess(
+      randomUUID(),
+      process.execPath,
+      ["-e", "setTimeout(() => process.stdout.write('done'), 150);"],
+      {
+        cwd: process.cwd(),
+        env: {},
+        timeoutSec: 0,
+        graceSec: 1,
+        onLog: async () => {},
+      },
+    );
+
+    expect(result.exitCode).toBe(0);
+    expect(result.timedOut).toBe(false);
+    expect(result.stdout).toBe("done");
+  });
+
  it("waits for onSpawn before sending stdin to the child", async () => {
    const spawnDelayMs = 150;
    const startedAt = Date.now();
@@ -86,3 +111,118 @@ describe("runChildProcess", () => {
    expect(await waitForPidExit(descendantPid!, 2_000)).toBe(true);
  });
 });
+
+describe("appendWithByteCap", () => {
+  it("keeps valid UTF-8 when trimming through multibyte text", () => {
+    const output = appendWithByteCap("prefix ", "hello — world", 7);
+
+    expect(output).not.toContain("\uFFFD");
+    expect(Buffer.from(output, "utf8").toString("utf8")).toBe(output);
+    expect(Buffer.byteLength(output, "utf8")).toBeLessThanOrEqual(7);
+  });
+});
+
+describe("renderPaperclipWakePrompt", () => {
+  it("keeps the default local-agent prompt action-oriented", () => {
+    expect(DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE).toContain("Start actionable work in this heartbeat");
+    expect(DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE).toContain("do not stop at a plan");
+    expect(DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE).toContain("Use child issues");
+    expect(DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE).toContain("instead of polling agents, sessions, or processes");
+    expect(DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE).toContain(
+      "Respect budget, pause/cancel, approval gates, and company boundaries",
+    );
+  });
+
+  it("adds the execution contract to scoped wake prompts", () => {
+    const prompt = renderPaperclipWakePrompt({
+      reason: "issue_assigned",
+      issue: {
+        id: "issue-1",
+        identifier: "PAP-1580",
+        title: "Update prompts",
+        status: "in_progress",
+      },
+      commentWindow: {
+        requestedCount: 0,
+        includedCount: 0,
+        missingCount: 0,
+      },
+      comments: [],
+      fallbackFetchNeeded: false,
+    });
+
+    expect(prompt).toContain("## Paperclip Wake Payload");
+    expect(prompt).toContain("Execution contract: take concrete action in this heartbeat");
+    expect(prompt).toContain("use child issues instead of polling");
+    expect(prompt).toContain("mark blocked work with the unblock owner/action");
+  });
+
+  it("includes continuation and child issue summaries in structured wake context", () => {
+    const payload = {
+      reason: "issue_children_completed",
+      issue: {
+        id: "parent-1",
+        identifier: "PAP-100",
+        title: "Integrate child work",
+        status: "in_progress",
+        priority: "medium",
+      },
+      continuationSummary: {
+        key: "continuation-summary",
+        title: "Continuation Summary",
+        body: "# Continuation Summary\n\n## Next Action\n\n- Integrate child outputs.",
+        updatedAt: "2026-04-18T12:00:00.000Z",
+      },
+      livenessContinuation: {
+        attempt: 2,
+        maxAttempts: 2,
+        sourceRunId: "run-1",
+        state: "plan_only",
+        reason: "Run described future work without concrete action evidence",
+        instruction: "Take the first concrete action now.",
+      },
+      childIssueSummaries: [
+        {
+          id: "child-1",
+          identifier: "PAP-101",
+          title: "Implement helper",
+          status: "done",
+          priority: "medium",
+          summary: "Added the helper route and tests.",
+        },
+      ],
+    };
+
+    expect(JSON.parse(stringifyPaperclipWakePayload(payload) ?? "{}")).toMatchObject({
+      continuationSummary: {
+        body: expect.stringContaining("Continuation Summary"),
+      },
+      livenessContinuation: {
+        attempt: 2,
+        maxAttempts: 2,
+        sourceRunId: "run-1",
+        state: "plan_only",
+        instruction: "Take the first concrete action now.",
+      },
+      childIssueSummaries: [
+        {
+          identifier: "PAP-101",
+          summary: "Added the helper route and tests.",
+        },
+      ],
+    });
+
+    const prompt = renderPaperclipWakePrompt(payload);
+    expect(prompt).toContain("Issue continuation summary:");
+    expect(prompt).toContain("Integrate child outputs.");
+    expect(prompt).toContain("Run liveness continuation:");
+    expect(prompt).toContain("- attempt: 2/2");
+    expect(prompt).toContain("- source run: run-1");
+    expect(prompt).toContain("- liveness state: plan_only");
+    expect(prompt).toContain("- reason: Run described future work without concrete action evidence");
+    expect(prompt).toContain("- instruction: Take the first concrete action now.");
+    expect(prompt).toContain("Direct child issue summaries:");
+    expect(prompt).toContain("PAP-101 Implement helper (done)");
+    expect(prompt).toContain("Added the helper route and tests.");
+  });
+});
@@ -66,6 +66,17 @@ const PAPERCLIP_SKILL_ROOT_RELATIVE_CANDIDATES = [
  "../../../../../skills",
 ];

+export const DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE = [
+  "You are agent {{agent.id}} ({{agent.name}}). Continue your Paperclip work.",
+  "",
+  "Execution contract:",
+  "- Start actionable work in this heartbeat; do not stop at a plan unless the issue asks for planning.",
+  "- Leave durable progress in comments, documents, or work products with a clear next action.",
+  "- Use child issues for parallel or long delegated work instead of polling agents, sessions, or processes.",
+  "- If blocked, mark the issue blocked and name the unblock owner and action.",
+  "- Respect budget, pause/cancel, approval gates, and company boundaries.",
+].join("\n");
+
 export interface PaperclipSkillEntry {
  key: string;
  runtimeName: string;
@@ -180,6 +191,22 @@ export function appendWithCap(prev: string, chunk: string, cap = MAX_CAPTURE_BYT
  return combined.length > cap ? combined.slice(combined.length - cap) : combined;
 }

+export function appendWithByteCap(prev: string, chunk: string, cap = MAX_CAPTURE_BYTES) {
+  const combined = prev + chunk;
+  const bytes = Buffer.byteLength(combined, "utf8");
+  if (bytes <= cap) return combined;
+
+  const buffer = Buffer.from(combined, "utf8");
+  let start = Math.max(0, bytes - cap);
+  while (start < buffer.length && (buffer[start]! & 0xc0) === 0x80) start += 1;
+  return buffer.subarray(start).toString("utf8");
+}
+
+function resumeReadable(readable: { resume: () => unknown; destroyed?: boolean } | null | undefined) {
+  if (!readable || readable.destroyed) return;
+  readable.resume();
+}
+
 export function resolvePathValue(obj: Record<string, unknown>, dottedPath: string) {
  const parts = dottedPath.split(".");
  let cursor: unknown = obj;
@@ -250,10 +277,41 @@ type PaperclipWakeComment = {
  authorId: string | null;
 };

+type PaperclipWakeContinuationSummary = {
+  key: string | null;
+  title: string | null;
+  body: string;
+  bodyTruncated: boolean;
+  updatedAt: string | null;
+};
+
+type PaperclipWakeLivenessContinuation = {
+  attempt: number | null;
+  maxAttempts: number | null;
+  sourceRunId: string | null;
+  state: string | null;
+  reason: string | null;
+  instruction: string | null;
+};
+
+type PaperclipWakeChildIssueSummary = {
+  id: string | null;
+  identifier: string | null;
+  title: string | null;
+  status: string | null;
+  priority: string | null;
+  summary: string | null;
+};
+
 type PaperclipWakePayload = {
  reason: string | null;
  issue: PaperclipWakeIssue | null;
+  checkedOutByHarness: boolean;
  executionStage: PaperclipWakeExecutionStage | null;
+  continuationSummary: PaperclipWakeContinuationSummary | null;
+  livenessContinuation: PaperclipWakeLivenessContinuation | null;
+  childIssueSummaries: PaperclipWakeChildIssueSummary[];
+  childIssueSummaryTruncated: boolean;
  commentIds: string[];
  latestCommentId: string | null;
  comments: PaperclipWakeComment[];
@@ -297,6 +355,50 @@ function normalizePaperclipWakeComment(value: unknown): PaperclipWakeComment | n
  };
 }

+function normalizePaperclipWakeContinuationSummary(value: unknown): PaperclipWakeContinuationSummary | null {
+  const summary = parseObject(value);
+  const body = asString(summary.body, "").trim();
+  if (!body) return null;
+  return {
+    key: asString(summary.key, "").trim() || null,
+    title: asString(summary.title, "").trim() || null,
+    body,
+    bodyTruncated: asBoolean(summary.bodyTruncated, false),
+    updatedAt: asString(summary.updatedAt, "").trim() || null,
+  };
+}
+
+function normalizePaperclipWakeLivenessContinuation(value: unknown): PaperclipWakeLivenessContinuation | null {
+  const continuation = parseObject(value);
+  const attempt = asNumber(continuation.attempt, 0);
+  const maxAttempts = asNumber(continuation.maxAttempts, 0);
+  const sourceRunId = asString(continuation.sourceRunId, "").trim() || null;
+  const state = asString(continuation.state, "").trim() || null;
+  const reason = asString(continuation.reason, "").trim() || null;
+  const instruction = asString(continuation.instruction, "").trim() || null;
+  if (!attempt && !maxAttempts && !sourceRunId && !state && !reason && !instruction) return null;
+  return {
+    attempt: attempt > 0 ? attempt : null,
+    maxAttempts: maxAttempts > 0 ? maxAttempts : null,
+    sourceRunId,
+    state,
+    reason,
+    instruction,
+  };
+}
+
+function normalizePaperclipWakeChildIssueSummary(value: unknown): PaperclipWakeChildIssueSummary | null {
+  const child = parseObject(value);
+  const id = asString(child.id, "").trim() || null;
+  const identifier = asString(child.identifier, "").trim() || null;
+  const title = asString(child.title, "").trim() || null;
+  const status = asString(child.status, "").trim() || null;
+  const priority = asString(child.priority, "").trim() || null;
+  const summary = asString(child.summary, "").trim() || null;
+  if (!id && !identifier && !title && !status && !summary) return null;
+  return { id, identifier, title, status, priority, summary };
+}
+
 function normalizePaperclipWakeExecutionPrincipal(value: unknown): PaperclipWakeExecutionPrincipal | null {
  const principal = parseObject(value);
  const typeRaw = asString(principal.type, "").trim().toLowerCase();
@@ -355,15 +457,27 @@ export function normalizePaperclipWakePayload(value: unknown): PaperclipWakePayl
        .map((entry) => entry.trim())
    : [];
  const executionStage = normalizePaperclipWakeExecutionStage(payload.executionStage);
+  const continuationSummary = normalizePaperclipWakeContinuationSummary(payload.continuationSummary);
+  const livenessContinuation = normalizePaperclipWakeLivenessContinuation(payload.livenessContinuation);
+  const childIssueSummaries = Array.isArray(payload.childIssueSummaries)
+    ? payload.childIssueSummaries
+        .map((entry) => normalizePaperclipWakeChildIssueSummary(entry))
+        .filter((entry): entry is PaperclipWakeChildIssueSummary => Boolean(entry))
+    : [];

-  if (comments.length === 0 && commentIds.length === 0 && !executionStage && !normalizePaperclipWakeIssue(payload.issue)) {
+  if (comments.length === 0 && commentIds.length === 0 && childIssueSummaries.length === 0 && !executionStage && !continuationSummary && !livenessContinuation && !normalizePaperclipWakeIssue(payload.issue)) {
    return null;
  }

  return {
    reason: asString(payload.reason, "").trim() || null,
    issue: normalizePaperclipWakeIssue(payload.issue),
+    checkedOutByHarness: asBoolean(payload.checkedOutByHarness, false),
    executionStage,
+    continuationSummary,
+    livenessContinuation,
+    childIssueSummaries,
+    childIssueSummaryTruncated: asBoolean(payload.childIssueSummaryTruncated, false),
    commentIds,
    latestCommentId: asString(payload.latestCommentId, "").trim() || null,
    comments,
@@ -404,6 +518,8 @@ export function renderPaperclipWakePrompt(
        "Focus on the new wake delta below and continue the current task without restating the full heartbeat boilerplate.",
        "Fetch the API thread only when `fallbackFetchNeeded` is true or you need broader history than this batch.",
        "",
+        "Execution contract: take concrete action in this heartbeat when the issue is actionable; do not stop at a plan unless planning was requested. Leave durable progress with a clear next action, use child issues instead of polling for long or parallel work, and mark blocked work with the unblock owner/action.",
+        "",
        `- reason: ${normalized.reason ?? "unknown"}`,
        `- issue: ${normalized.issue?.identifier ?? normalized.issue?.id ?? "unknown"}${normalized.issue?.title ? ` ${normalized.issue.title}` : ""}`,
        `- pending comments: ${normalized.includedCount}/${normalized.requestedCount}`,
@@ -419,6 +535,8 @@ export function renderPaperclipWakePrompt(
        "Use this inline wake data first before refetching the issue thread.",
        "Only fetch the API thread when `fallbackFetchNeeded` is true or you need broader history than this batch.",
        "",
+        "Execution contract: take concrete action in this heartbeat when the issue is actionable; do not stop at a plan unless planning was requested. Leave durable progress with a clear next action, use child issues instead of polling for long or parallel work, and mark blocked work with the unblock owner/action.",
+        "",
        `- reason: ${normalized.reason ?? "unknown"}`,
        `- issue: ${normalized.issue?.identifier ?? normalized.issue?.id ?? "unknown"}${normalized.issue?.title ? ` ${normalized.issue.title}` : ""}`,
        `- pending comments: ${normalized.includedCount}/${normalized.requestedCount}`,
@@ -432,6 +550,9 @@ export function renderPaperclipWakePrompt(
  if (normalized.issue?.priority) {
    lines.push(`- issue priority: ${normalized.issue.priority}`);
  }
+  if (normalized.checkedOutByHarness) {
+    lines.push("- checkout: already claimed by the harness for this run");
+  }
  if (normalized.missingCount > 0) {
    lines.push(`- omitted comments: ${normalized.missingCount}`);
  }
@@ -465,6 +586,64 @@ export function renderPaperclipWakePrompt(
    }
  }

+  if (normalized.continuationSummary) {
+    lines.push(
+      "",
+      "Issue continuation summary:",
+      normalized.continuationSummary.body,
+    );
+    if (normalized.continuationSummary.bodyTruncated) {
+      lines.push("[continuation summary truncated]");
+    }
+  }
+
+  if (normalized.livenessContinuation) {
+    const continuation = normalized.livenessContinuation;
+    lines.push("", "Run liveness continuation:");
+    if (continuation.attempt) {
+      lines.push(
+        `- attempt: ${continuation.attempt}${continuation.maxAttempts ? `/${continuation.maxAttempts}` : ""}`,
+      );
+    }
+    if (continuation.sourceRunId) {
+      lines.push(`- source run: ${continuation.sourceRunId}`);
+    }
+    if (continuation.state) {
+      lines.push(`- liveness state: ${continuation.state}`);
+    }
+    if (continuation.reason) {
+      lines.push(`- reason: ${continuation.reason}`);
+    }
+    if (continuation.instruction) {
+      lines.push(`- instruction: ${continuation.instruction}`);
+    }
+  }
+
+  if (normalized.childIssueSummaries.length > 0) {
+    lines.push("", "Direct child issue summaries:");
+    for (const child of normalized.childIssueSummaries) {
+      const label = child.identifier ?? child.id ?? "unknown";
+      lines.push(
+        `- ${label}${child.title ? ` ${child.title}` : ""}${child.status ? ` (${child.status})` : ""}`,
+      );
+      if (child.summary) {
+        lines.push(`  ${child.summary}`);
+      }
+    }
+    if (normalized.childIssueSummaryTruncated) {
+      lines.push("[child issue summaries truncated]");
+    }
+  }
+
+  if (normalized.checkedOutByHarness) {
+    lines.push(
+      "",
+      "The harness already checked out this issue for the current run.",
+      "Do not call `/api/issues/{id}/checkout` again unless you intentionally switch to a different task.",
+      "",
+    );
+  }
+
  if (normalized.comments.length > 0) {
    lines.push("New comments in order:");
  }
@@ -1120,19 +1299,27 @@ export async function runChildProcess(
            : null;

        child.stdout?.on("data", (chunk: unknown) => {
+          const readable = child.stdout;
+          if (!readable) return;
+          readable.pause();
          const text = String(chunk);
          stdout = appendWithCap(stdout, text);
          logChain = logChain
            .then(() => opts.onLog("stdout", text))
-            .catch((err) => onLogError(err, runId, "failed to append stdout log chunk"));
+            .catch((err) => onLogError(err, runId, "failed to append stdout log chunk"))
+            .finally(() => resumeReadable(readable));
        });

        child.stderr?.on("data", (chunk: unknown) => {
+          const readable = child.stderr;
+          if (!readable) return;
+          readable.pause();
          const text = String(chunk);
          stderr = appendWithCap(stderr, text);
          logChain = logChain
            .then(() => opts.onLog("stderr", text))
-            .catch((err) => onLogError(err, runId, "failed to append stderr log chunk"));
+            .catch((err) => onLogError(err, runId, "failed to append stderr log chunk"))
+            .finally(() => resumeReadable(readable));
        });

        const stdin = child.stdin;
@@ -328,6 +328,36 @@ export interface ServerAdapterModule {
   * resolved inside this method — the caller receives a fully hydrated schema.
   */
  getConfigSchema?: () => Promise<AdapterConfigSchema> | AdapterConfigSchema;
+
+  // ---------------------------------------------------------------------------
+  // Adapter capability flags
+  //
+  // These allow adapter plugins to declare what "local" capabilities they
+  // support, replacing hardcoded type lists in the server and UI.
+  // All flags are optional — when undefined, the server falls back to
+  // legacy hardcoded lists for built-in adapters.
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Adapter supports managed instructions bundle (AGENTS.md files).
+   * When true, the server uses instructionsPathKey (default "instructionsFilePath")
+   * to resolve the instructions config key, and the UI shows the bundle editor.
+   * Built-in local adapters default to true; external plugins must opt in.
+   */
+  supportsInstructionsBundle?: boolean;
+
+  /**
+   * The adapterConfig key that holds the instructions file path.
+   * Defaults to "instructionsFilePath" when supportsInstructionsBundle is true.
+   */
+  instructionsPathKey?: string;
+
+  /**
+   * Adapter needs runtime skill entries materialized (written to disk)
+   * before being passed via config. Used by adapters that scan a directory
+   * rather than reading config.paperclipRuntimeSkills.
+   */
+  requiresMaterializedRuntimeSkills?: boolean;
 }

 // ---------------------------------------------------------------------------
@@ -2,6 +2,7 @@ export const type = "claude_local";
 export const label = "Claude Code (local)";

 export const models = [
+  { id: "claude-opus-4-7", label: "Claude Opus 4.7" },
  { id: "claude-opus-4-6", label: "Claude Opus 4.6" },
  { id: "claude-sonnet-4-6", label: "Claude Sonnet 4.6" },
  { id: "claude-haiku-4-6", label: "Claude Haiku 4.6" },
@@ -21,6 +21,7 @@ import {
  renderTemplate,
  renderPaperclipWakePrompt,
  stringifyPaperclipWakePayload,
+  DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,
  runChildProcess,
 } from "@paperclipai/adapter-utils/server-utils";
 import {
@@ -300,7 +301,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec

  const promptTemplate = asString(
    config.promptTemplate,
-    "You are agent {{agent.id}} ({{agent.name}}). Continue your Paperclip work.",
+    DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,
  );
  const model = asString(config.model, "");
  const effort = asString(config.effort, "");
@@ -187,13 +187,15 @@ function formatExtraUsageLabel(extraUsage: AnthropicExtraUsage): string | null {
  ) {
    return null;
  }
-  return `${formatCurrencyAmount(usedCredits, extraUsage.currency)} / ${formatCurrencyAmount(monthlyLimit, extraUsage.currency)}`;
+  // API returns values in cents — convert to dollars for display
+  return `${formatCurrencyAmount(usedCredits / 100, extraUsage.currency)} / ${formatCurrencyAmount(monthlyLimit / 100, extraUsage.currency)}`;
 }

-/** Convert a 0-1 utilization fraction to a 0-100 integer percent. Returns null for null/undefined input. */
+/** Convert a utilization value to a 0-100 integer percent. Returns null for null/undefined input.
+ *  Handles both 0-1 fractions (legacy) and 0-100 percentages (current API). */
 export function toPercent(utilization: number | null | undefined): number | null {
  if (utilization == null) return null;
-  return Math.min(100, Math.round(utilization * 100));
+  return Math.min(100, Math.round(utilization < 1 ? utilization * 100 : utilization));
 }

 /** fetch with an abort-based timeout so a hanging provider api doesn't block the response indefinitely */
@@ -18,6 +18,7 @@ import {
  renderTemplate,
  renderPaperclipWakePrompt,
  stringifyPaperclipWakePayload,
+  DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,
  joinPromptSections,
  runChildProcess,
 } from "@paperclipai/adapter-utils/server-utils";
@@ -218,7 +219,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec

  const promptTemplate = asString(
    config.promptTemplate,
-    "You are agent {{agent.id}} ({{agent.name}}). Continue your Paperclip work.",
+    DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,
  );
  const command = asString(config.command, "codex");
  const model = asString(config.model, "");
@@ -21,6 +21,7 @@ import {
  renderTemplate,
  renderPaperclipWakePrompt,
  stringifyPaperclipWakePayload,
+  DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,
  joinPromptSections,
  runChildProcess,
 } from "@paperclipai/adapter-utils/server-utils";
@@ -164,7 +165,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec

  const promptTemplate = asString(
    config.promptTemplate,
-    "You are agent {{agent.id}} ({{agent.name}}). Continue your Paperclip work.",
+    DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,
  );
  const command = asString(config.command, "agent");
  const model = asString(config.model, DEFAULT_CURSOR_LOCAL_MODEL).trim();
@@ -24,6 +24,7 @@ import {
  renderTemplate,
  renderPaperclipWakePrompt,
  stringifyPaperclipWakePayload,
+  DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,
  runChildProcess,
 } from "@paperclipai/adapter-utils/server-utils";
 import { DEFAULT_GEMINI_LOCAL_MODEL } from "../index.js";
@@ -140,7 +141,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec

  const promptTemplate = asString(
    config.promptTemplate,
-    "You are agent {{agent.id}} ({{agent.name}}). Continue your Paperclip work.",
+    DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,
  );
  const command = asString(config.command, "gemini");
  const model = asString(config.model, DEFAULT_GEMINI_LOCAL_MODEL).trim();
@@ -420,7 +420,9 @@ function buildWakeText(
    "   - POST /api/issues/{issueId}/checkout with {\"agentId\":\"$PAPERCLIP_AGENT_ID\",\"expectedStatuses\":[\"todo\",\"backlog\",\"blocked\",\"in_review\"]}",
    "   - GET /api/issues/{issueId}",
    "   - GET /api/issues/{issueId}/comments",
-    "   - Execute the issue instructions exactly.",
+    "   - Execute the issue instructions exactly. If the issue is actionable, take concrete action in this run; do not stop at a plan unless planning was requested.",
+    "   - Leave durable progress with a clear next action. Use child issues for long or parallel delegated work instead of polling agents, sessions, or processes.",
+    "   - If blocked, PATCH /api/issues/{issueId} with {\"status\":\"blocked\",\"comment\":\"what is blocked, who owns the unblock, and the next action\"}.",
    "   - If instructions require a comment, POST /api/issues/{issueId}/comments with {\"body\":\"...\"}.",
    "   - PATCH /api/issues/{issueId} with {\"status\":\"done\",\"comment\":\"what changed and why\"}.",
    "4) If issueId does not exist:",
@@ -19,6 +19,7 @@ import {
  renderTemplate,
  renderPaperclipWakePrompt,
  stringifyPaperclipWakePayload,
+  DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,
  runChildProcess,
  readPaperclipRuntimeSkillEntries,
  resolvePaperclipDesiredSkillNames,
@@ -97,7 +98,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec

  const promptTemplate = asString(
    config.promptTemplate,
-    "You are agent {{agent.id}} ({{agent.name}}). Continue your Paperclip work.",
+    DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,
  );
  const command = asString(config.command, "opencode");
  const model = asString(config.model, "").trim();
@@ -22,6 +22,7 @@ import {
  renderTemplate,
  renderPaperclipWakePrompt,
  stringifyPaperclipWakePayload,
+  DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,
  runChildProcess,
 } from "@paperclipai/adapter-utils/server-utils";
 import { isPiUnknownSessionError, parsePiJsonl } from "./parse.js";
@@ -113,7 +114,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec

  const promptTemplate = asString(
    config.promptTemplate,
-    "You are agent {{agent.id}} ({{agent.name}}). Continue your Paperclip work.",
+    DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,
  );
  const command = asString(config.command, "pi");
  const model = asString(config.model, "").trim();
@@ -276,7 +277,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
        `${instructionsContents}\n\n` +
        `The above agent instructions were loaded from ${resolvedInstructionsFilePath}. ` +
        `Resolve any relative file references from ${instructionsFileDir}.\n\n` +
-        `You are agent {{agent.id}} ({{agent.name}}). Continue your Paperclip work.`;
+        DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE;
    } catch (err) {
      instructionsReadFailed = true;
      const reason = err instanceof Error ? err.message : String(err);
@@ -0,0 +1,84 @@
+import { createHash, randomBytes } from "node:crypto";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { and, eq, gt, isNull } from "drizzle-orm";
+import { createDb } from "../src/client.js";
+import { invites } from "../src/schema/index.js";
+
+function hashToken(token: string) {
+  return createHash("sha256").update(token).digest("hex");
+}
+
+function createInviteToken() {
+  return `pcp_bootstrap_${randomBytes(24).toString("hex")}`;
+}
+
+function readArg(flag: string) {
+  const index = process.argv.indexOf(flag);
+  if (index === -1) return null;
+  return process.argv[index + 1] ?? null;
+}
+
+async function main() {
+  const configPath = readArg("--config");
+  const baseUrl = readArg("--base-url");
+
+  if (!configPath || !baseUrl) {
+    throw new Error("Usage: tsx create-auth-bootstrap-invite.ts --config <path> --base-url <url>");
+  }
+
+  const config = JSON.parse(readFileSync(path.resolve(configPath), "utf8")) as {
+    database?: {
+      mode?: string;
+      embeddedPostgresPort?: number;
+      connectionString?: string;
+    };
+  };
+  const dbUrl =
+    config.database?.mode === "postgres"
+      ? config.database.connectionString
+      : `postgres://paperclip:paperclip@127.0.0.1:${config.database?.embeddedPostgresPort ?? 54329}/paperclip`;
+  if (!dbUrl) {
+    throw new Error(`Could not resolve database connection from ${configPath}`);
+  }
+
+  const db = createDb(dbUrl);
+  const closableDb = db as typeof db & {
+    $client?: {
+      end?: (options?: { timeout?: number }) => Promise<void>;
+    };
+  };
+
+  try {
+    const now = new Date();
+    await db
+      .update(invites)
+      .set({ revokedAt: now, updatedAt: now })
+      .where(
+        and(
+          eq(invites.inviteType, "bootstrap_ceo"),
+          isNull(invites.revokedAt),
+          isNull(invites.acceptedAt),
+          gt(invites.expiresAt, now)
+        )
+      );
+
+    const token = createInviteToken();
+    await db.insert(invites).values({
+      inviteType: "bootstrap_ceo",
+      tokenHash: hashToken(token),
+      allowedJoinTypes: "human",
+      expiresAt: new Date(Date.now() + 72 * 60 * 60 * 1000),
+      invitedByUserId: "system",
+    });
+
+    process.stdout.write(`${baseUrl.replace(/\/+$/, "")}/invite/${token}\n`);
+  } finally {
+    await closableDb.$client?.end?.({ timeout: 5 }).catch(() => undefined);
+  }
+}
+
+main().catch((error) => {
+  process.stderr.write(`${error instanceof Error ? error.stack ?? error.message : String(error)}\n`);
+  process.exit(1);
+});
@@ -127,6 +127,7 @@ describeEmbeddedPostgres("runDatabaseBackup", () => {
          backupDir,
          retention: { dailyDays: 7, weeklyWeeks: 4, monthlyMonths: 1 },
          filenamePrefix: "paperclip-test",
+          backupEngine: "javascript",
        });

        expect(result.backupFile).toMatch(/paperclip-test-.*\.sql\.gz$/);
@@ -148,14 +149,17 @@ describeEmbeddedPostgres("runDatabaseBackup", () => {
          title: string;
          payload: string;
          state: string;
-          metadata: { index: number; even: boolean };
+          metadata: { index: number; even: boolean } | string;
        }[]>(`
          SELECT "title", "payload", "state"::text AS "state", "metadata"
          FROM "public"."backup_test_records"
          WHERE "title" IN ('row-0', 'row-159')
          ORDER BY "title"
        `);
-        expect(sampleRows).toEqual([
+        expect(sampleRows.map((row) => ({
+          ...row,
+          metadata: typeof row.metadata === "string" ? JSON.parse(row.metadata) : row.metadata,
+        }))).toEqual([
          {
            title: "row-0",
            payload,
@@ -1,6 +1,8 @@
 import { createReadStream, createWriteStream, existsSync, mkdirSync, readdirSync, statSync, unlinkSync } from "node:fs";
 import { basename, resolve } from "node:path";
 import { createInterface } from "node:readline";
+import { spawn } from "node:child_process";
+import { open as openFile } from "node:fs/promises";
 import { pipeline } from "node:stream/promises";
 import { createGunzip, createGzip } from "node:zlib";
 import postgres from "postgres";
@@ -20,6 +22,7 @@ export type RunDatabaseBackupOptions = {
  includeMigrationJournal?: boolean;
  excludeTables?: string[];
  nullifyColumns?: Record<string, string[]>;
+  backupEngine?: "auto" | "pg_dump" | "javascript";
 };

 export type RunDatabaseBackupResult = {
@@ -61,6 +64,9 @@ type ExtensionDefinition = {
 const DRIZZLE_SCHEMA = "drizzle";
 const DRIZZLE_MIGRATIONS_TABLE = "__drizzle_migrations";
 const DEFAULT_BACKUP_WRITE_BUFFER_BYTES = 1024 * 1024;
+const BACKUP_DATA_CURSOR_ROWS = 100;
+const BACKUP_CLI_STDERR_BYTES = 64 * 1024;
+const BACKUP_BREAKPOINT_DETECT_BYTES = 64 * 1024;

 const STATEMENT_BREAKPOINT = "-- paperclip statement breakpoint 69f6f3f1-42fd-46a6-bf17-d1d85f8f3900";

@@ -223,6 +229,134 @@ function tableKey(schemaName: string, tableName: string): string {
  return `${schemaName}.${tableName}`;
 }

+function hasBackupTransforms(opts: RunDatabaseBackupOptions): boolean {
+  return opts.includeMigrationJournal === true ||
+    (opts.excludeTables?.length ?? 0) > 0 ||
+    Object.keys(opts.nullifyColumns ?? {}).length > 0;
+}
+
+function formatSqlValue(rawValue: unknown, columnName: string | undefined, nullifiedColumns: Set<string>): string {
+  const val = columnName && nullifiedColumns.has(columnName) ? null : rawValue;
+  if (val === null || val === undefined) return "NULL";
+  if (typeof val === "boolean") return val ? "true" : "false";
+  if (typeof val === "number") return String(val);
+  if (val instanceof Date) return formatSqlLiteral(val.toISOString());
+  if (typeof val === "object") return formatSqlLiteral(JSON.stringify(val));
+  return formatSqlLiteral(String(val));
+}
+
+function appendCapturedStderr(previous: string, chunk: Buffer | string): string {
+  const next = previous + (Buffer.isBuffer(chunk) ? chunk.toString("utf8") : chunk);
+  if (Buffer.byteLength(next, "utf8") <= BACKUP_CLI_STDERR_BYTES) return next;
+  return Buffer.from(next, "utf8").subarray(-BACKUP_CLI_STDERR_BYTES).toString("utf8");
+}
+
+async function waitForChildExit(child: ReturnType<typeof spawn>, label: string): Promise<void> {
+  let stderr = "";
+  child.stderr?.on("data", (chunk) => {
+    stderr = appendCapturedStderr(stderr, chunk);
+  });
+
+  const result = await new Promise<{ code: number | null; signal: NodeJS.Signals | null }>((resolve, reject) => {
+    child.once("error", reject);
+    child.once("exit", (code, signal) => resolve({ code, signal }));
+  });
+
+  if (result.signal) {
+    throw new Error(`${label} exited via ${result.signal}${stderr.trim() ? `: ${stderr.trim()}` : ""}`);
+  }
+  if (result.code !== 0) {
+    throw new Error(`${label} failed with exit code ${result.code ?? "unknown"}${stderr.trim() ? `: ${stderr.trim()}` : ""}`);
+  }
+}
+
+async function runPgDumpBackup(opts: {
+  connectionString: string;
+  backupFile: string;
+  connectTimeout: number;
+}): Promise<void> {
+  const pgDumpBin = process.env.PAPERCLIP_PG_DUMP_PATH || "pg_dump";
+  const child = spawn(
+    pgDumpBin,
+    [
+      `--dbname=${opts.connectionString}`,
+      "--format=plain",
+      "--clean",
+      "--if-exists",
+      "--no-owner",
+      "--no-privileges",
+      "--schema=public",
+    ],
+    {
+      stdio: ["ignore", "pipe", "pipe"],
+      env: {
+        ...process.env,
+        PGCONNECT_TIMEOUT: String(opts.connectTimeout),
+      },
+    },
+  );
+
+  if (!child.stdout) {
+    throw new Error("pg_dump did not expose stdout");
+  }
+
+  await Promise.all([
+    pipeline(child.stdout, createGzip(), createWriteStream(opts.backupFile)),
+    waitForChildExit(child, pgDumpBin),
+  ]);
+}
+
+async function restoreWithPsql(opts: RunDatabaseRestoreOptions, connectTimeout: number): Promise<void> {
+  const psqlBin = process.env.PAPERCLIP_PSQL_PATH || "psql";
+  const child = spawn(
+    psqlBin,
+    [
+      `--dbname=${opts.connectionString}`,
+      "--set=ON_ERROR_STOP=1",
+      "--quiet",
+      "--no-psqlrc",
+    ],
+    {
+      stdio: ["pipe", "ignore", "pipe"],
+      env: {
+        ...process.env,
+        PGCONNECT_TIMEOUT: String(connectTimeout),
+      },
+    },
+  );
+
+  if (!child.stdin) {
+    throw new Error("psql did not expose stdin");
+  }
+
+  const input = opts.backupFile.endsWith(".gz")
+    ? createReadStream(opts.backupFile).pipe(createGunzip())
+    : createReadStream(opts.backupFile);
+
+  await Promise.all([
+    pipeline(input, child.stdin),
+    waitForChildExit(child, psqlBin),
+  ]);
+}
+
+async function hasStatementBreakpoints(backupFile: string): Promise<boolean> {
+  const raw = createReadStream(backupFile);
+  const stream = backupFile.endsWith(".gz") ? raw.pipe(createGunzip()) : raw;
+  let text = "";
+
+  try {
+    for await (const chunk of stream) {
+      text += Buffer.isBuffer(chunk) ? chunk.toString("utf8") : String(chunk);
+      if (text.includes(STATEMENT_BREAKPOINT)) return true;
+      if (Buffer.byteLength(text, "utf8") >= BACKUP_BREAKPOINT_DETECT_BYTES) return false;
+    }
+    return text.includes(STATEMENT_BREAKPOINT);
+  } finally {
+    stream.destroy();
+    raw.destroy();
+  }
+}
+
 async function* readRestoreStatements(backupFile: string): AsyncGenerator<string> {
  const raw = createReadStream(backupFile);
  const stream = backupFile.endsWith(".gz") ? raw.pipe(createGunzip()) : raw;
@@ -263,41 +397,21 @@ async function* readRestoreStatements(backupFile: string): AsyncGenerator<string
 }

 export function createBufferedTextFileWriter(filePath: string, maxBufferedBytes = DEFAULT_BACKUP_WRITE_BUFFER_BYTES) {
-  const stream = createWriteStream(filePath, { encoding: "utf8" });
+  const filePromise = openFile(filePath, "w");
  const flushThreshold = Math.max(1, Math.trunc(maxBufferedBytes));
  let bufferedLines: string[] = [];
  let bufferedBytes = 0;
  let firstChunk = true;
  let closed = false;
-  let streamError: Error | null = null;
  let pendingWrite = Promise.resolve();

-  stream.on("error", (error) => {
-    streamError = error;
-  });
-
-  const writeChunk = async (chunk: string): Promise<void> => {
-    if (streamError) throw streamError;
-    const canContinue = stream.write(chunk);
-    if (!canContinue) {
-      await new Promise<void>((resolve, reject) => {
-        const handleDrain = () => {
-          cleanup();
-          resolve();
-        };
-        const handleError = (error: Error) => {
-          cleanup();
-          reject(error);
-        };
-        const cleanup = () => {
-          stream.off("drain", handleDrain);
-          stream.off("error", handleError);
-        };
-        stream.once("drain", handleDrain);
-        stream.once("error", handleError);
-      });
+  const writeChunk = async (chunk: string | Buffer): Promise<void> => {
+    const file = await filePromise;
+    if (typeof chunk === "string") {
+      await file.write(chunk, null, "utf8");
+    } else {
+      await file.write(chunk);
    }
-    if (streamError) throw streamError;
  };

  const flushBufferedLines = () => {
@@ -316,37 +430,43 @@ export function createBufferedTextFileWriter(filePath: string, maxBufferedBytes
      if (closed) {
        throw new Error(`Cannot write to closed backup file: ${filePath}`);
      }
-      if (streamError) throw streamError;
      bufferedLines.push(line);
      bufferedBytes += Buffer.byteLength(line, "utf8") + 1;
      if (bufferedBytes >= flushThreshold) {
        flushBufferedLines();
      }
    },
+    async drain() {
+      if (closed) {
+        throw new Error(`Cannot drain closed backup file: ${filePath}`);
+      }
+      flushBufferedLines();
+      await pendingWrite;
+    },
+    async writeRaw(chunk: string | Buffer) {
+      if (closed) {
+        throw new Error(`Cannot write to closed backup file: ${filePath}`);
+      }
+      flushBufferedLines();
+      firstChunk = false;
+      pendingWrite = pendingWrite.then(() => writeChunk(chunk));
+      await pendingWrite;
+    },
    async close() {
      if (closed) return;
      closed = true;
      flushBufferedLines();
      await pendingWrite;
-      await new Promise<void>((resolve, reject) => {
-        if (streamError) {
-          reject(streamError);
-          return;
-        }
-        stream.end((error?: Error | null) => {
-          if (error) reject(error);
-          else resolve();
-        });
-      });
-      if (streamError) throw streamError;
+      const file = await filePromise;
+      await file.close();
    },
    async abort() {
      if (closed) return;
      closed = true;
      bufferedLines = [];
      bufferedBytes = 0;
-      stream.destroy();
      await pendingWrite.catch(() => {});
+      await filePromise.then((file) => file.close()).catch(() => {});
      if (existsSync(filePath)) {
        try {
          unlinkSync(filePath);
@@ -362,16 +482,53 @@ export async function runDatabaseBackup(opts: RunDatabaseBackupOptions): Promise
  const filenamePrefix = opts.filenamePrefix ?? "paperclip";
  const retention = opts.retention;
  const connectTimeout = Math.max(1, Math.trunc(opts.connectTimeoutSeconds ?? 5));
+  const backupEngine = opts.backupEngine ?? "auto";
+  const canUsePgDump = !hasBackupTransforms(opts);
  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 });
+  let sql = postgres(opts.connectionString, { max: 1, connect_timeout: connectTimeout });
+  let sqlClosed = false;
+  const closeSql = async () => {
+    if (sqlClosed) return;
+    sqlClosed = true;
+    await sql.end();
+  };
  mkdirSync(opts.backupDir, { recursive: true });
  const sqlFile = resolve(opts.backupDir, `${filenamePrefix}-${timestamp()}.sql`);
  const backupFile = `${sqlFile}.gz`;
  const writer = createBufferedTextFileWriter(sqlFile);

  try {
+    if (backupEngine === "pg_dump" || (backupEngine === "auto" && canUsePgDump)) {
+      await sql`SELECT 1`;
+      try {
+        await closeSql();
+        await runPgDumpBackup({
+          connectionString: opts.connectionString,
+          backupFile,
+          connectTimeout,
+        });
+        await writer.abort();
+        const sizeBytes = statSync(backupFile).size;
+        const prunedCount = pruneOldBackups(opts.backupDir, retention, filenamePrefix);
+        return {
+          backupFile,
+          sizeBytes,
+          prunedCount,
+        };
+      } catch (error) {
+        if (existsSync(backupFile)) {
+          try { unlinkSync(backupFile); } catch { /* ignore */ }
+        }
+        if (backupEngine === "pg_dump") {
+          throw error;
+        }
+        sql = postgres(opts.connectionString, { max: 1, connect_timeout: connectTimeout });
+        sqlClosed = false;
+      }
+    }
+
    await sql`SELECT 1`;

    const emit = (line: string) => writer.emit(line);
@@ -703,20 +860,39 @@ export async function runDatabaseBackup(opts: RunDatabaseBackupOptions): Promise

      emit(`-- Data for: ${schema_name}.${tablename} (${count[0]!.n} rows)`);

-      const rows = await sql.unsafe(`SELECT * FROM ${qualifiedTableName}`).values();
      const nullifiedColumns = nullifiedColumnsByTable.get(tablename) ?? new Set<string>();
-      for (const row of rows) {
-        const values = row.map((rawValue: unknown, index) => {
-          const columnName = cols[index]?.column_name;
-          const val = columnName && nullifiedColumns.has(columnName) ? null : rawValue;
-          if (val === null || val === undefined) return "NULL";
-          if (typeof val === "boolean") return val ? "true" : "false";
-          if (typeof val === "number") return String(val);
-          if (val instanceof Date) return formatSqlLiteral(val.toISOString());
-          if (typeof val === "object") return formatSqlLiteral(JSON.stringify(val));
-          return formatSqlLiteral(String(val));
-        });
-        emitStatement(`INSERT INTO ${qualifiedTableName} (${colNames}) VALUES (${values.join(", ")});`);
+      if (backupEngine !== "javascript" && nullifiedColumns.size === 0) {
+        emit(`COPY ${qualifiedTableName} (${colNames}) FROM stdin;`);
+        await writer.writeRaw("\n");
+        const copySql = postgres(opts.connectionString, { max: 1, connect_timeout: connectTimeout });
+        try {
+          const copyStream = await copySql
+            .unsafe(`COPY ${qualifiedTableName} (${colNames}) TO STDOUT`)
+            .readable();
+          for await (const chunk of copyStream) {
+            await writer.writeRaw(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+          }
+        } finally {
+          await copySql.end();
+        }
+        await writer.writeRaw("\\.\n");
+        emitStatementBoundary();
+        emit("");
+        continue;
+      }
+
+      const rowCursor = sql
+        .unsafe(`SELECT * FROM ${qualifiedTableName}`)
+        .values()
+        .cursor(BACKUP_DATA_CURSOR_ROWS) as AsyncIterable<unknown[][]>;
+      for await (const rows of rowCursor) {
+        for (const row of rows) {
+          const values = row.map((rawValue, index) =>
+            formatSqlValue(rawValue, cols[index]?.column_name, nullifiedColumns),
+          );
+          emitStatement(`INSERT INTO ${qualifiedTableName} (${colNames}) VALUES (${values.join(", ")});`);
+        }
+        await writer.drain();
      }
      emit("");
    }
@@ -768,12 +944,23 @@ export async function runDatabaseBackup(opts: RunDatabaseBackupOptions): Promise
    }
    throw error;
  } finally {
-    await sql.end();
+    await closeSql();
  }
 }

 export async function runDatabaseRestore(opts: RunDatabaseRestoreOptions): Promise<void> {
  const connectTimeout = Math.max(1, Math.trunc(opts.connectTimeoutSeconds ?? 5));
+  try {
+    await restoreWithPsql(opts, connectTimeout);
+    return;
+  } catch (error) {
+    if (!(await hasStatementBreakpoints(opts.backupFile))) {
+      throw new Error(
+        `Failed to restore ${basename(opts.backupFile)} with psql: ${sanitizeRestoreErrorMessage(error)}`,
+      );
+    }
+  }
+
  const sql = postgres(opts.connectionString, { max: 1, connect_timeout: connectTimeout });

  try {
@@ -1,151 +0,0 @@
-CREATE TABLE "memory_binding_targets" (
-	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
-	"company_id" uuid NOT NULL,
-	"binding_id" uuid NOT NULL,
-	"target_type" text NOT NULL,
-	"target_id" uuid NOT NULL,
-	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
-	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
-);
--> statement-breakpoint
-CREATE TABLE "memory_bindings" (
-	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
-	"company_id" uuid NOT NULL,
-	"key" text NOT NULL,
-	"name" text,
-	"provider_key" text NOT NULL,
-	"config" jsonb DEFAULT '{}'::jsonb NOT NULL,
-	"enabled" boolean DEFAULT true NOT NULL,
-	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
-	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
-);
--> statement-breakpoint
-CREATE TABLE "memory_extraction_jobs" (
-	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
-	"company_id" uuid NOT NULL,
-	"binding_id" uuid NOT NULL,
-	"provider_key" text NOT NULL,
-	"operation_id" uuid,
-	"status" text DEFAULT 'queued' NOT NULL,
-	"provider_job_id" text,
-	"source_kind" text,
-	"source_issue_id" uuid,
-	"source_comment_id" uuid,
-	"source_document_key" text,
-	"source_run_id" uuid,
-	"source_activity_id" uuid,
-	"source_external_ref" text,
-	"result_json" jsonb,
-	"error" text,
-	"started_at" timestamp with time zone,
-	"completed_at" timestamp with time zone,
-	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
-	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
-);
--> statement-breakpoint
-CREATE TABLE "memory_local_records" (
-	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
-	"company_id" uuid NOT NULL,
-	"binding_id" uuid NOT NULL,
-	"provider_key" text NOT NULL,
-	"scope_agent_id" uuid,
-	"scope_project_id" uuid,
-	"scope_issue_id" uuid,
-	"scope_run_id" uuid,
-	"scope_subject_id" text,
-	"source_kind" text,
-	"source_issue_id" uuid,
-	"source_comment_id" uuid,
-	"source_document_key" text,
-	"source_run_id" uuid,
-	"source_activity_id" uuid,
-	"source_external_ref" text,
-	"title" text,
-	"content" text NOT NULL,
-	"summary" text,
-	"metadata" jsonb DEFAULT '{}'::jsonb NOT NULL,
-	"created_by_operation_id" uuid,
-	"deleted_at" timestamp with time zone,
-	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
-	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
-);
--> statement-breakpoint
-CREATE TABLE "memory_operations" (
-	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
-	"company_id" uuid NOT NULL,
-	"binding_id" uuid NOT NULL,
-	"provider_key" text NOT NULL,
-	"operation_type" text NOT NULL,
-	"trigger_kind" text DEFAULT 'manual' NOT NULL,
-	"hook_kind" text,
-	"status" text DEFAULT 'succeeded' NOT NULL,
-	"actor_type" text NOT NULL,
-	"actor_id" text NOT NULL,
-	"agent_id" uuid,
-	"user_id" text,
-	"scope_agent_id" uuid,
-	"scope_project_id" uuid,
-	"scope_issue_id" uuid,
-	"scope_run_id" uuid,
-	"scope_subject_id" text,
-	"source_kind" text,
-	"source_issue_id" uuid,
-	"source_comment_id" uuid,
-	"source_document_key" text,
-	"source_run_id" uuid,
-	"source_activity_id" uuid,
-	"source_external_ref" text,
-	"query_text" text,
-	"record_count" integer DEFAULT 0 NOT NULL,
-	"request_json" jsonb,
-	"result_json" jsonb,
-	"usage_json" jsonb DEFAULT '[]'::jsonb NOT NULL,
-	"error" text,
-	"cost_event_id" uuid,
-	"finance_event_id" uuid,
-	"occurred_at" timestamp with time zone DEFAULT now() NOT NULL,
-	"created_at" timestamp with time zone DEFAULT now() NOT NULL
-);
--> statement-breakpoint
-ALTER TABLE "memory_binding_targets" ADD CONSTRAINT "memory_binding_targets_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "memory_binding_targets" ADD CONSTRAINT "memory_binding_targets_binding_id_memory_bindings_id_fk" FOREIGN KEY ("binding_id") REFERENCES "public"."memory_bindings"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "memory_bindings" ADD CONSTRAINT "memory_bindings_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "memory_extraction_jobs" ADD CONSTRAINT "memory_extraction_jobs_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "memory_extraction_jobs" ADD CONSTRAINT "memory_extraction_jobs_binding_id_memory_bindings_id_fk" FOREIGN KEY ("binding_id") REFERENCES "public"."memory_bindings"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "memory_extraction_jobs" ADD CONSTRAINT "memory_extraction_jobs_operation_id_memory_operations_id_fk" FOREIGN KEY ("operation_id") REFERENCES "public"."memory_operations"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "memory_local_records" ADD CONSTRAINT "memory_local_records_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "memory_local_records" ADD CONSTRAINT "memory_local_records_binding_id_memory_bindings_id_fk" FOREIGN KEY ("binding_id") REFERENCES "public"."memory_bindings"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "memory_local_records" ADD CONSTRAINT "memory_local_records_scope_agent_id_agents_id_fk" FOREIGN KEY ("scope_agent_id") REFERENCES "public"."agents"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "memory_local_records" ADD CONSTRAINT "memory_local_records_scope_project_id_projects_id_fk" FOREIGN KEY ("scope_project_id") REFERENCES "public"."projects"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "memory_local_records" ADD CONSTRAINT "memory_local_records_scope_issue_id_issues_id_fk" FOREIGN KEY ("scope_issue_id") REFERENCES "public"."issues"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "memory_local_records" ADD CONSTRAINT "memory_local_records_scope_run_id_heartbeat_runs_id_fk" FOREIGN KEY ("scope_run_id") REFERENCES "public"."heartbeat_runs"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "memory_local_records" ADD CONSTRAINT "memory_local_records_source_issue_id_issues_id_fk" FOREIGN KEY ("source_issue_id") REFERENCES "public"."issues"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "memory_local_records" ADD CONSTRAINT "memory_local_records_source_run_id_heartbeat_runs_id_fk" FOREIGN KEY ("source_run_id") REFERENCES "public"."heartbeat_runs"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "memory_local_records" ADD CONSTRAINT "memory_local_records_created_by_operation_id_memory_operations_id_fk" FOREIGN KEY ("created_by_operation_id") REFERENCES "public"."memory_operations"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "memory_operations" ADD CONSTRAINT "memory_operations_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "memory_operations" ADD CONSTRAINT "memory_operations_binding_id_memory_bindings_id_fk" FOREIGN KEY ("binding_id") REFERENCES "public"."memory_bindings"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "memory_operations" ADD CONSTRAINT "memory_operations_agent_id_agents_id_fk" FOREIGN KEY ("agent_id") REFERENCES "public"."agents"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "memory_operations" ADD CONSTRAINT "memory_operations_scope_agent_id_agents_id_fk" FOREIGN KEY ("scope_agent_id") REFERENCES "public"."agents"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "memory_operations" ADD CONSTRAINT "memory_operations_scope_project_id_projects_id_fk" FOREIGN KEY ("scope_project_id") REFERENCES "public"."projects"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "memory_operations" ADD CONSTRAINT "memory_operations_scope_issue_id_issues_id_fk" FOREIGN KEY ("scope_issue_id") REFERENCES "public"."issues"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "memory_operations" ADD CONSTRAINT "memory_operations_scope_run_id_heartbeat_runs_id_fk" FOREIGN KEY ("scope_run_id") REFERENCES "public"."heartbeat_runs"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "memory_operations" ADD CONSTRAINT "memory_operations_source_issue_id_issues_id_fk" FOREIGN KEY ("source_issue_id") REFERENCES "public"."issues"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "memory_operations" ADD CONSTRAINT "memory_operations_source_comment_id_issue_comments_id_fk" FOREIGN KEY ("source_comment_id") REFERENCES "public"."issue_comments"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "memory_operations" ADD CONSTRAINT "memory_operations_source_run_id_heartbeat_runs_id_fk" FOREIGN KEY ("source_run_id") REFERENCES "public"."heartbeat_runs"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "memory_operations" ADD CONSTRAINT "memory_operations_source_activity_id_activity_log_id_fk" FOREIGN KEY ("source_activity_id") REFERENCES "public"."activity_log"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "memory_operations" ADD CONSTRAINT "memory_operations_cost_event_id_cost_events_id_fk" FOREIGN KEY ("cost_event_id") REFERENCES "public"."cost_events"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "memory_operations" ADD CONSTRAINT "memory_operations_finance_event_id_finance_events_id_fk" FOREIGN KEY ("finance_event_id") REFERENCES "public"."finance_events"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
-CREATE UNIQUE INDEX "memory_binding_targets_company_target_idx" ON "memory_binding_targets" USING btree ("company_id","target_type","target_id");--> statement-breakpoint
-CREATE INDEX "memory_binding_targets_company_binding_idx" ON "memory_binding_targets" USING btree ("company_id","binding_id");--> statement-breakpoint
-CREATE UNIQUE INDEX "memory_bindings_company_key_idx" ON "memory_bindings" USING btree ("company_id","key");--> statement-breakpoint
-CREATE INDEX "memory_bindings_company_provider_idx" ON "memory_bindings" USING btree ("company_id","provider_key");--> statement-breakpoint
-CREATE INDEX "memory_extraction_jobs_company_status_created_idx" ON "memory_extraction_jobs" USING btree ("company_id","status","created_at");--> statement-breakpoint
-CREATE INDEX "memory_extraction_jobs_company_binding_created_idx" ON "memory_extraction_jobs" USING btree ("company_id","binding_id","created_at");--> statement-breakpoint
-CREATE INDEX "memory_local_records_company_binding_created_idx" ON "memory_local_records" USING btree ("company_id","binding_id","created_at");--> statement-breakpoint
-CREATE INDEX "memory_local_records_company_agent_created_idx" ON "memory_local_records" USING btree ("company_id","scope_agent_id","created_at");--> statement-breakpoint
-CREATE INDEX "memory_local_records_company_issue_created_idx" ON "memory_local_records" USING btree ("company_id","scope_issue_id","created_at");--> statement-breakpoint
-CREATE INDEX "memory_local_records_fts_idx" ON "memory_local_records" USING gin (to_tsvector('english', coalesce("title", '') || ' ' || "content"));--> statement-breakpoint
-CREATE INDEX "memory_operations_company_occurred_idx" ON "memory_operations" USING btree ("company_id","occurred_at");--> statement-breakpoint
-CREATE INDEX "memory_operations_company_binding_occurred_idx" ON "memory_operations" USING btree ("company_id","binding_id","occurred_at");--> statement-breakpoint
-CREATE INDEX "memory_operations_company_issue_occurred_idx" ON "memory_operations" USING btree ("company_id","scope_issue_id","occurred_at");--> statement-breakpoint
-CREATE INDEX "memory_operations_company_run_occurred_idx" ON "memory_operations" USING btree ("company_id","scope_run_id","occurred_at");
@@ -0,0 +1,22 @@
+CREATE TABLE "company_user_sidebar_preferences" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"user_id" text NOT NULL,
+	"project_order" jsonb DEFAULT '[]'::jsonb NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "user_sidebar_preferences" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"user_id" text NOT NULL,
+	"company_order" jsonb DEFAULT '[]'::jsonb NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "company_user_sidebar_preferences" ADD CONSTRAINT "company_user_sidebar_preferences_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "company_user_sidebar_preferences_company_idx" ON "company_user_sidebar_preferences" USING btree ("company_id");--> statement-breakpoint
+CREATE INDEX "company_user_sidebar_preferences_user_idx" ON "company_user_sidebar_preferences" USING btree ("user_id");--> statement-breakpoint
+CREATE UNIQUE INDEX "company_user_sidebar_preferences_company_user_uq" ON "company_user_sidebar_preferences" USING btree ("company_id","user_id");--> statement-breakpoint
+CREATE UNIQUE INDEX "user_sidebar_preferences_user_uq" ON "user_sidebar_preferences" USING btree ("user_id");
@@ -1,60 +0,0 @@
-ALTER TABLE "memory_local_records" ADD COLUMN "scope_type" text DEFAULT 'org' NOT NULL;--> statement-breakpoint
-ALTER TABLE "memory_local_records" ADD COLUMN "scope_id" text;--> statement-breakpoint
-ALTER TABLE "memory_local_records" ADD COLUMN "scope_workspace_id" text;--> statement-breakpoint
-ALTER TABLE "memory_local_records" ADD COLUMN "scope_team_id" text;--> statement-breakpoint
-ALTER TABLE "memory_local_records" ADD COLUMN "owner_type" text;--> statement-breakpoint
-ALTER TABLE "memory_local_records" ADD COLUMN "owner_id" text;--> statement-breakpoint
-ALTER TABLE "memory_local_records" ADD COLUMN "created_by_actor_type" text;--> statement-breakpoint
-ALTER TABLE "memory_local_records" ADD COLUMN "created_by_actor_id" text;--> statement-breakpoint
-ALTER TABLE "memory_local_records" ADD COLUMN "sensitivity_label" text DEFAULT 'internal' NOT NULL;--> statement-breakpoint
-ALTER TABLE "memory_local_records" ADD COLUMN "retention_policy" jsonb;--> statement-breakpoint
-ALTER TABLE "memory_local_records" ADD COLUMN "expires_at" timestamp with time zone;--> statement-breakpoint
-ALTER TABLE "memory_local_records" ADD COLUMN "retention_state" text DEFAULT 'active' NOT NULL;--> statement-breakpoint
-ALTER TABLE "memory_local_records" ADD COLUMN "citation_json" jsonb;--> statement-breakpoint
-ALTER TABLE "memory_local_records" ADD COLUMN "supersedes_record_id" uuid;--> statement-breakpoint
-ALTER TABLE "memory_local_records" ADD COLUMN "superseded_by_record_id" uuid;--> statement-breakpoint
-ALTER TABLE "memory_local_records" ADD COLUMN "revoked_at" timestamp with time zone;--> statement-breakpoint
-ALTER TABLE "memory_local_records" ADD COLUMN "revoked_by_actor_type" text;--> statement-breakpoint
-ALTER TABLE "memory_local_records" ADD COLUMN "revoked_by_actor_id" text;--> statement-breakpoint
-ALTER TABLE "memory_local_records" ADD COLUMN "revocation_reason" text;--> statement-breakpoint
-ALTER TABLE "memory_operations" ADD COLUMN "scope_type" text;--> statement-breakpoint
-ALTER TABLE "memory_operations" ADD COLUMN "scope_id" text;--> statement-breakpoint
-ALTER TABLE "memory_operations" ADD COLUMN "scope_workspace_id" text;--> statement-breakpoint
-ALTER TABLE "memory_operations" ADD COLUMN "scope_team_id" text;--> statement-breakpoint
-ALTER TABLE "memory_operations" ADD COLUMN "max_sensitivity_label" text;--> statement-breakpoint
-ALTER TABLE "memory_operations" ADD COLUMN "policy_decision_json" jsonb;--> statement-breakpoint
-ALTER TABLE "memory_operations" ADD COLUMN "revocation_selector_json" jsonb;--> statement-breakpoint
-ALTER TABLE "memory_operations" ADD COLUMN "retention_action_json" jsonb;--> statement-breakpoint
-UPDATE "memory_local_records"
-SET
-	"scope_type" = CASE
-		WHEN "scope_run_id" IS NOT NULL THEN 'run'
-		WHEN "scope_agent_id" IS NOT NULL THEN 'agent'
-		WHEN "scope_project_id" IS NOT NULL THEN 'project'
-		ELSE 'org'
-	END,
-	"scope_id" = COALESCE("scope_run_id"::text, "scope_agent_id"::text, "scope_project_id"::text, "company_id"::text),
-	"retention_state" = CASE WHEN "deleted_at" IS NOT NULL THEN 'revoked' ELSE 'active' END,
-	"revoked_at" = CASE WHEN "deleted_at" IS NOT NULL THEN "deleted_at" ELSE NULL END,
-	"revocation_reason" = CASE WHEN "deleted_at" IS NOT NULL THEN 'Record was forgotten before governed memory migration' ELSE NULL END;--> statement-breakpoint
-UPDATE "memory_local_records" AS "record"
-SET
-	"owner_type" = "operation"."actor_type",
-	"owner_id" = "operation"."actor_id",
-	"created_by_actor_type" = "operation"."actor_type",
-	"created_by_actor_id" = "operation"."actor_id"
-FROM "memory_operations" AS "operation"
-WHERE "record"."created_by_operation_id" = "operation"."id";--> statement-breakpoint
-UPDATE "memory_operations"
-SET
-	"scope_type" = CASE
-		WHEN "scope_run_id" IS NOT NULL THEN 'run'
-		WHEN "scope_agent_id" IS NOT NULL THEN 'agent'
-		WHEN "scope_project_id" IS NOT NULL THEN 'project'
-		ELSE 'org'
-	END,
-	"scope_id" = COALESCE("scope_run_id"::text, "scope_agent_id"::text, "scope_project_id"::text, "company_id"::text);--> statement-breakpoint
-CREATE INDEX "memory_local_records_company_scope_created_idx" ON "memory_local_records" USING btree ("company_id","scope_type","scope_id","created_at");--> statement-breakpoint
-CREATE INDEX "memory_local_records_company_sensitivity_created_idx" ON "memory_local_records" USING btree ("company_id","sensitivity_label","created_at");--> statement-breakpoint
-CREATE INDEX "memory_local_records_company_retention_created_idx" ON "memory_local_records" USING btree ("company_id","retention_state","expires_at","created_at");--> statement-breakpoint
-CREATE INDEX "memory_operations_company_scope_occurred_idx" ON "memory_operations" USING btree ("company_id","scope_type","scope_id","occurred_at");
@@ -0,0 +1,57 @@
+WITH ranked_user_requests AS (
+  SELECT
+    id,
+    row_number() OVER (
+      PARTITION BY company_id, requesting_user_id
+      ORDER BY created_at ASC, id ASC
+    ) AS rank
+  FROM join_requests
+  WHERE request_type = 'human'
+    AND status = 'pending_approval'
+    AND requesting_user_id IS NOT NULL
+)
+UPDATE join_requests
+SET
+  status = 'rejected',
+  rejected_at = COALESCE(rejected_at, now()),
+  updated_at = now()
+WHERE id IN (
+  SELECT id
+  FROM ranked_user_requests
+  WHERE rank > 1
+);
+--> statement-breakpoint
+WITH ranked_email_requests AS (
+  SELECT
+    id,
+    row_number() OVER (
+      PARTITION BY company_id, lower(request_email_snapshot)
+      ORDER BY created_at ASC, id ASC
+    ) AS rank
+  FROM join_requests
+  WHERE request_type = 'human'
+    AND status = 'pending_approval'
+    AND request_email_snapshot IS NOT NULL
+)
+UPDATE join_requests
+SET
+  status = 'rejected',
+  rejected_at = COALESCE(rejected_at, now()),
+  updated_at = now()
+WHERE id IN (
+  SELECT id
+  FROM ranked_email_requests
+  WHERE rank > 1
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "join_requests_pending_human_user_uq"
+ON "join_requests" USING btree ("company_id", "requesting_user_id")
+WHERE "request_type" = 'human'
+  AND "status" = 'pending_approval'
+  AND "requesting_user_id" IS NOT NULL;
+--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "join_requests_pending_human_email_uq"
+ON "join_requests" USING btree ("company_id", lower("request_email_snapshot"))
+WHERE "request_type" = 'human'
+  AND "status" = 'pending_approval'
+  AND "request_email_snapshot" IS NOT NULL;
@@ -1,6 +0,0 @@
-ALTER TABLE "memory_local_records" ADD COLUMN "review_state" text DEFAULT 'pending' NOT NULL;--> statement-breakpoint
-ALTER TABLE "memory_local_records" ADD COLUMN "reviewed_at" timestamp with time zone;--> statement-breakpoint
-ALTER TABLE "memory_local_records" ADD COLUMN "reviewed_by_actor_type" text;--> statement-breakpoint
-ALTER TABLE "memory_local_records" ADD COLUMN "reviewed_by_actor_id" text;--> statement-breakpoint
-ALTER TABLE "memory_local_records" ADD COLUMN "review_note" text;--> statement-breakpoint
-CREATE INDEX "memory_local_records_company_review_created_idx" ON "memory_local_records" USING btree ("company_id","review_state","created_at");
@@ -0,0 +1,6 @@
+ALTER TABLE "heartbeat_runs" ADD COLUMN IF NOT EXISTS "liveness_state" text;--> statement-breakpoint
+ALTER TABLE "heartbeat_runs" ADD COLUMN IF NOT EXISTS "liveness_reason" text;--> statement-breakpoint
+ALTER TABLE "heartbeat_runs" ADD COLUMN IF NOT EXISTS "continuation_attempt" integer DEFAULT 0 NOT NULL;--> statement-breakpoint
+ALTER TABLE "heartbeat_runs" ADD COLUMN IF NOT EXISTS "last_useful_action_at" timestamp with time zone;--> statement-breakpoint
+ALTER TABLE "heartbeat_runs" ADD COLUMN IF NOT EXISTS "next_action" text;--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "heartbeat_runs_company_liveness_idx" ON "heartbeat_runs" USING btree ("company_id","liveness_state","created_at");
@@ -0,0 +1,486 @@
+CREATE TABLE IF NOT EXISTS "background_job_cost_events" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"run_id" uuid NOT NULL,
+	"cost_event_id" uuid NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "background_job_events" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"run_id" uuid NOT NULL,
+	"event_type" text NOT NULL,
+	"level" text DEFAULT 'info' NOT NULL,
+	"message" text,
+	"progress_percent" integer,
+	"total_items" integer,
+	"processed_items" integer,
+	"succeeded_items" integer,
+	"failed_items" integer,
+	"skipped_items" integer,
+	"current_item" text,
+	"details" jsonb,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "background_job_runs" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"job_id" uuid,
+	"job_key" text NOT NULL,
+	"job_type" text NOT NULL,
+	"trigger" text DEFAULT 'manual' NOT NULL,
+	"status" text DEFAULT 'queued' NOT NULL,
+	"requested_by_actor_type" text DEFAULT 'system' NOT NULL,
+	"requested_by_actor_id" text DEFAULT 'system' NOT NULL,
+	"requested_by_agent_id" uuid,
+	"requested_by_user_id" text,
+	"source_issue_id" uuid,
+	"source_project_id" uuid,
+	"source_agent_id" uuid,
+	"heartbeat_run_id" uuid,
+	"total_items" integer,
+	"processed_items" integer DEFAULT 0 NOT NULL,
+	"succeeded_items" integer DEFAULT 0 NOT NULL,
+	"failed_items" integer DEFAULT 0 NOT NULL,
+	"skipped_items" integer DEFAULT 0 NOT NULL,
+	"progress_percent" integer,
+	"current_item" text,
+	"cancellation_requested_at" timestamp with time zone,
+	"cancelled_at" timestamp with time zone,
+	"error" text,
+	"result" jsonb,
+	"started_at" timestamp with time zone,
+	"finished_at" timestamp with time zone,
+	"duration_ms" integer,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "background_jobs" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"key" text NOT NULL,
+	"job_type" text NOT NULL,
+	"display_name" text NOT NULL,
+	"description" text,
+	"backend_kind" text DEFAULT 'server_worker' NOT NULL,
+	"status" text DEFAULT 'active' NOT NULL,
+	"config" jsonb DEFAULT '{}'::jsonb NOT NULL,
+	"created_by_agent_id" uuid,
+	"created_by_user_id" text,
+	"source_issue_id" uuid,
+	"source_project_id" uuid,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "memory_binding_targets" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"binding_id" uuid NOT NULL,
+	"target_type" text NOT NULL,
+	"target_id" uuid NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "memory_bindings" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"key" text NOT NULL,
+	"name" text,
+	"provider_key" text NOT NULL,
+	"config" jsonb DEFAULT '{}'::jsonb NOT NULL,
+	"enabled" boolean DEFAULT true NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "memory_extraction_jobs" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"binding_id" uuid NOT NULL,
+	"provider_key" text NOT NULL,
+	"operation_id" uuid,
+	"status" text DEFAULT 'queued' NOT NULL,
+	"provider_job_id" text,
+	"source_kind" text,
+	"source_issue_id" uuid,
+	"source_comment_id" uuid,
+	"source_document_key" text,
+	"source_run_id" uuid,
+	"source_activity_id" uuid,
+	"source_external_ref" text,
+	"result_json" jsonb,
+	"error" text,
+	"started_at" timestamp with time zone,
+	"completed_at" timestamp with time zone,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "memory_local_records" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"binding_id" uuid NOT NULL,
+	"provider_key" text NOT NULL,
+	"scope_agent_id" uuid,
+	"scope_project_id" uuid,
+	"scope_issue_id" uuid,
+	"scope_run_id" uuid,
+	"scope_subject_id" text,
+	"scope_type" text DEFAULT 'org' NOT NULL,
+	"scope_id" text,
+	"scope_workspace_id" text,
+	"scope_team_id" text,
+	"source_kind" text,
+	"source_issue_id" uuid,
+	"source_comment_id" uuid,
+	"source_document_key" text,
+	"source_run_id" uuid,
+	"source_activity_id" uuid,
+	"source_external_ref" text,
+	"title" text,
+	"content" text NOT NULL,
+	"summary" text,
+	"metadata" jsonb DEFAULT '{}'::jsonb NOT NULL,
+	"owner_type" text,
+	"owner_id" text,
+	"created_by_actor_type" text,
+	"created_by_actor_id" text,
+	"sensitivity_label" text DEFAULT 'internal' NOT NULL,
+	"retention_policy" jsonb,
+	"expires_at" timestamp with time zone,
+	"retention_state" text DEFAULT 'active' NOT NULL,
+	"review_state" text DEFAULT 'pending' NOT NULL,
+	"reviewed_at" timestamp with time zone,
+	"reviewed_by_actor_type" text,
+	"reviewed_by_actor_id" text,
+	"review_note" text,
+	"citation_json" jsonb,
+	"supersedes_record_id" uuid,
+	"superseded_by_record_id" uuid,
+	"revoked_at" timestamp with time zone,
+	"revoked_by_actor_type" text,
+	"revoked_by_actor_id" text,
+	"revocation_reason" text,
+	"created_by_operation_id" uuid,
+	"deleted_at" timestamp with time zone,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "memory_operations" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"binding_id" uuid NOT NULL,
+	"provider_key" text NOT NULL,
+	"operation_type" text NOT NULL,
+	"trigger_kind" text DEFAULT 'manual' NOT NULL,
+	"hook_kind" text,
+	"status" text DEFAULT 'succeeded' NOT NULL,
+	"actor_type" text NOT NULL,
+	"actor_id" text NOT NULL,
+	"agent_id" uuid,
+	"user_id" text,
+	"scope_agent_id" uuid,
+	"scope_project_id" uuid,
+	"scope_issue_id" uuid,
+	"scope_run_id" uuid,
+	"scope_subject_id" text,
+	"scope_type" text,
+	"scope_id" text,
+	"scope_workspace_id" text,
+	"scope_team_id" text,
+	"max_sensitivity_label" text,
+	"source_kind" text,
+	"source_issue_id" uuid,
+	"source_comment_id" uuid,
+	"source_document_key" text,
+	"source_run_id" uuid,
+	"source_activity_id" uuid,
+	"source_external_ref" text,
+	"query_text" text,
+	"record_count" integer DEFAULT 0 NOT NULL,
+	"request_json" jsonb,
+	"result_json" jsonb,
+	"policy_decision_json" jsonb,
+	"revocation_selector_json" jsonb,
+	"retention_action_json" jsonb,
+	"usage_json" jsonb DEFAULT '[]'::jsonb NOT NULL,
+	"error" text,
+	"cost_event_id" uuid,
+	"finance_event_id" uuid,
+	"occurred_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+-- Compatibility for databases that ran the old branch-numbered memory migrations before this merge.
+ALTER TABLE "memory_local_records" ADD COLUMN IF NOT EXISTS "scope_type" text DEFAULT 'org' NOT NULL;--> statement-breakpoint
+ALTER TABLE "memory_local_records" ADD COLUMN IF NOT EXISTS "scope_id" text;--> statement-breakpoint
+ALTER TABLE "memory_local_records" ADD COLUMN IF NOT EXISTS "scope_workspace_id" text;--> statement-breakpoint
+ALTER TABLE "memory_local_records" ADD COLUMN IF NOT EXISTS "scope_team_id" text;--> statement-breakpoint
+ALTER TABLE "memory_local_records" ADD COLUMN IF NOT EXISTS "owner_type" text;--> statement-breakpoint
+ALTER TABLE "memory_local_records" ADD COLUMN IF NOT EXISTS "owner_id" text;--> statement-breakpoint
+ALTER TABLE "memory_local_records" ADD COLUMN IF NOT EXISTS "created_by_actor_type" text;--> statement-breakpoint
+ALTER TABLE "memory_local_records" ADD COLUMN IF NOT EXISTS "created_by_actor_id" text;--> statement-breakpoint
+ALTER TABLE "memory_local_records" ADD COLUMN IF NOT EXISTS "sensitivity_label" text DEFAULT 'internal' NOT NULL;--> statement-breakpoint
+ALTER TABLE "memory_local_records" ADD COLUMN IF NOT EXISTS "retention_policy" jsonb;--> statement-breakpoint
+ALTER TABLE "memory_local_records" ADD COLUMN IF NOT EXISTS "expires_at" timestamp with time zone;--> statement-breakpoint
+ALTER TABLE "memory_local_records" ADD COLUMN IF NOT EXISTS "retention_state" text DEFAULT 'active' NOT NULL;--> statement-breakpoint
+ALTER TABLE "memory_local_records" ADD COLUMN IF NOT EXISTS "citation_json" jsonb;--> statement-breakpoint
+ALTER TABLE "memory_local_records" ADD COLUMN IF NOT EXISTS "supersedes_record_id" uuid;--> statement-breakpoint
+ALTER TABLE "memory_local_records" ADD COLUMN IF NOT EXISTS "superseded_by_record_id" uuid;--> statement-breakpoint
+ALTER TABLE "memory_local_records" ADD COLUMN IF NOT EXISTS "revoked_at" timestamp with time zone;--> statement-breakpoint
+ALTER TABLE "memory_local_records" ADD COLUMN IF NOT EXISTS "revoked_by_actor_type" text;--> statement-breakpoint
+ALTER TABLE "memory_local_records" ADD COLUMN IF NOT EXISTS "revoked_by_actor_id" text;--> statement-breakpoint
+ALTER TABLE "memory_local_records" ADD COLUMN IF NOT EXISTS "revocation_reason" text;--> statement-breakpoint
+ALTER TABLE "memory_operations" ADD COLUMN IF NOT EXISTS "scope_type" text;--> statement-breakpoint
+ALTER TABLE "memory_operations" ADD COLUMN IF NOT EXISTS "scope_id" text;--> statement-breakpoint
+ALTER TABLE "memory_operations" ADD COLUMN IF NOT EXISTS "scope_workspace_id" text;--> statement-breakpoint
+ALTER TABLE "memory_operations" ADD COLUMN IF NOT EXISTS "scope_team_id" text;--> statement-breakpoint
+ALTER TABLE "memory_operations" ADD COLUMN IF NOT EXISTS "max_sensitivity_label" text;--> statement-breakpoint
+ALTER TABLE "memory_operations" ADD COLUMN IF NOT EXISTS "policy_decision_json" jsonb;--> statement-breakpoint
+ALTER TABLE "memory_operations" ADD COLUMN IF NOT EXISTS "revocation_selector_json" jsonb;--> statement-breakpoint
+ALTER TABLE "memory_operations" ADD COLUMN IF NOT EXISTS "retention_action_json" jsonb;--> statement-breakpoint
+UPDATE "memory_local_records"
+SET
+	"scope_type" = CASE
+		WHEN "scope_run_id" IS NOT NULL THEN 'run'
+		WHEN "scope_agent_id" IS NOT NULL THEN 'agent'
+		WHEN "scope_project_id" IS NOT NULL THEN 'project'
+		ELSE 'org'
+	END,
+	"scope_id" = COALESCE("scope_run_id"::text, "scope_agent_id"::text, "scope_project_id"::text, "company_id"::text),
+	"retention_state" = CASE WHEN "deleted_at" IS NOT NULL THEN 'revoked' ELSE 'active' END,
+	"revoked_at" = CASE WHEN "deleted_at" IS NOT NULL THEN "deleted_at" ELSE NULL END,
+	"revocation_reason" = CASE WHEN "deleted_at" IS NOT NULL THEN 'Record was forgotten before governed memory migration' ELSE NULL END;--> statement-breakpoint
+UPDATE "memory_local_records" AS "record"
+SET
+	"owner_type" = "operation"."actor_type",
+	"owner_id" = "operation"."actor_id",
+	"created_by_actor_type" = "operation"."actor_type",
+	"created_by_actor_id" = "operation"."actor_id"
+FROM "memory_operations" AS "operation"
+WHERE "record"."created_by_operation_id" = "operation"."id";--> statement-breakpoint
+UPDATE "memory_operations"
+SET
+	"scope_type" = CASE
+		WHEN "scope_run_id" IS NOT NULL THEN 'run'
+		WHEN "scope_agent_id" IS NOT NULL THEN 'agent'
+		WHEN "scope_project_id" IS NOT NULL THEN 'project'
+		ELSE 'org'
+	END,
+	"scope_id" = COALESCE("scope_run_id"::text, "scope_agent_id"::text, "scope_project_id"::text, "company_id"::text);--> statement-breakpoint
+ALTER TABLE "memory_local_records" ADD COLUMN IF NOT EXISTS "review_state" text DEFAULT 'pending' NOT NULL;--> statement-breakpoint
+ALTER TABLE "memory_local_records" ADD COLUMN IF NOT EXISTS "reviewed_at" timestamp with time zone;--> statement-breakpoint
+ALTER TABLE "memory_local_records" ADD COLUMN IF NOT EXISTS "reviewed_by_actor_type" text;--> statement-breakpoint
+ALTER TABLE "memory_local_records" ADD COLUMN IF NOT EXISTS "reviewed_by_actor_id" text;--> statement-breakpoint
+ALTER TABLE "memory_local_records" ADD COLUMN IF NOT EXISTS "review_note" text;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "background_job_cost_events" ADD CONSTRAINT "background_job_cost_events_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "background_job_cost_events" ADD CONSTRAINT "background_job_cost_events_run_id_background_job_runs_id_fk" FOREIGN KEY ("run_id") REFERENCES "public"."background_job_runs"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "background_job_cost_events" ADD CONSTRAINT "background_job_cost_events_cost_event_id_cost_events_id_fk" FOREIGN KEY ("cost_event_id") REFERENCES "public"."cost_events"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "background_job_events" ADD CONSTRAINT "background_job_events_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "background_job_events" ADD CONSTRAINT "background_job_events_run_id_background_job_runs_id_fk" FOREIGN KEY ("run_id") REFERENCES "public"."background_job_runs"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "background_job_runs" ADD CONSTRAINT "background_job_runs_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "background_job_runs" ADD CONSTRAINT "background_job_runs_job_id_background_jobs_id_fk" FOREIGN KEY ("job_id") REFERENCES "public"."background_jobs"("id") ON DELETE set null ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "background_job_runs" ADD CONSTRAINT "background_job_runs_requested_by_agent_id_agents_id_fk" FOREIGN KEY ("requested_by_agent_id") REFERENCES "public"."agents"("id") ON DELETE set null ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "background_job_runs" ADD CONSTRAINT "background_job_runs_source_issue_id_issues_id_fk" FOREIGN KEY ("source_issue_id") REFERENCES "public"."issues"("id") ON DELETE set null ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "background_job_runs" ADD CONSTRAINT "background_job_runs_source_project_id_projects_id_fk" FOREIGN KEY ("source_project_id") REFERENCES "public"."projects"("id") ON DELETE set null ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "background_job_runs" ADD CONSTRAINT "background_job_runs_source_agent_id_agents_id_fk" FOREIGN KEY ("source_agent_id") REFERENCES "public"."agents"("id") ON DELETE set null ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "background_job_runs" ADD CONSTRAINT "background_job_runs_heartbeat_run_id_heartbeat_runs_id_fk" FOREIGN KEY ("heartbeat_run_id") REFERENCES "public"."heartbeat_runs"("id") ON DELETE set null ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "background_jobs" ADD CONSTRAINT "background_jobs_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "background_jobs" ADD CONSTRAINT "background_jobs_created_by_agent_id_agents_id_fk" FOREIGN KEY ("created_by_agent_id") REFERENCES "public"."agents"("id") ON DELETE set null ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "background_jobs" ADD CONSTRAINT "background_jobs_source_issue_id_issues_id_fk" FOREIGN KEY ("source_issue_id") REFERENCES "public"."issues"("id") ON DELETE set null ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "background_jobs" ADD CONSTRAINT "background_jobs_source_project_id_projects_id_fk" FOREIGN KEY ("source_project_id") REFERENCES "public"."projects"("id") ON DELETE set null ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "memory_binding_targets" ADD CONSTRAINT "memory_binding_targets_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "memory_binding_targets" ADD CONSTRAINT "memory_binding_targets_binding_id_memory_bindings_id_fk" FOREIGN KEY ("binding_id") REFERENCES "public"."memory_bindings"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "memory_bindings" ADD CONSTRAINT "memory_bindings_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "memory_extraction_jobs" ADD CONSTRAINT "memory_extraction_jobs_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "memory_extraction_jobs" ADD CONSTRAINT "memory_extraction_jobs_binding_id_memory_bindings_id_fk" FOREIGN KEY ("binding_id") REFERENCES "public"."memory_bindings"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "memory_extraction_jobs" ADD CONSTRAINT "memory_extraction_jobs_operation_id_memory_operations_id_fk" FOREIGN KEY ("operation_id") REFERENCES "public"."memory_operations"("id") ON DELETE set null ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "memory_local_records" ADD CONSTRAINT "memory_local_records_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "memory_local_records" ADD CONSTRAINT "memory_local_records_binding_id_memory_bindings_id_fk" FOREIGN KEY ("binding_id") REFERENCES "public"."memory_bindings"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "memory_local_records" ADD CONSTRAINT "memory_local_records_scope_agent_id_agents_id_fk" FOREIGN KEY ("scope_agent_id") REFERENCES "public"."agents"("id") ON DELETE no action ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "memory_local_records" ADD CONSTRAINT "memory_local_records_scope_project_id_projects_id_fk" FOREIGN KEY ("scope_project_id") REFERENCES "public"."projects"("id") ON DELETE no action ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "memory_local_records" ADD CONSTRAINT "memory_local_records_scope_issue_id_issues_id_fk" FOREIGN KEY ("scope_issue_id") REFERENCES "public"."issues"("id") ON DELETE no action ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "memory_local_records" ADD CONSTRAINT "memory_local_records_scope_run_id_heartbeat_runs_id_fk" FOREIGN KEY ("scope_run_id") REFERENCES "public"."heartbeat_runs"("id") ON DELETE no action ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "memory_local_records" ADD CONSTRAINT "memory_local_records_source_issue_id_issues_id_fk" FOREIGN KEY ("source_issue_id") REFERENCES "public"."issues"("id") ON DELETE no action ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "memory_local_records" ADD CONSTRAINT "memory_local_records_source_run_id_heartbeat_runs_id_fk" FOREIGN KEY ("source_run_id") REFERENCES "public"."heartbeat_runs"("id") ON DELETE no action ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "memory_local_records" ADD CONSTRAINT "memory_local_records_created_by_operation_id_memory_operations_id_fk" FOREIGN KEY ("created_by_operation_id") REFERENCES "public"."memory_operations"("id") ON DELETE set null ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "memory_operations" ADD CONSTRAINT "memory_operations_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "memory_operations" ADD CONSTRAINT "memory_operations_binding_id_memory_bindings_id_fk" FOREIGN KEY ("binding_id") REFERENCES "public"."memory_bindings"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "memory_operations" ADD CONSTRAINT "memory_operations_agent_id_agents_id_fk" FOREIGN KEY ("agent_id") REFERENCES "public"."agents"("id") ON DELETE no action ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "memory_operations" ADD CONSTRAINT "memory_operations_scope_agent_id_agents_id_fk" FOREIGN KEY ("scope_agent_id") REFERENCES "public"."agents"("id") ON DELETE no action ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "memory_operations" ADD CONSTRAINT "memory_operations_scope_project_id_projects_id_fk" FOREIGN KEY ("scope_project_id") REFERENCES "public"."projects"("id") ON DELETE no action ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "memory_operations" ADD CONSTRAINT "memory_operations_scope_issue_id_issues_id_fk" FOREIGN KEY ("scope_issue_id") REFERENCES "public"."issues"("id") ON DELETE no action ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "memory_operations" ADD CONSTRAINT "memory_operations_scope_run_id_heartbeat_runs_id_fk" FOREIGN KEY ("scope_run_id") REFERENCES "public"."heartbeat_runs"("id") ON DELETE no action ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "memory_operations" ADD CONSTRAINT "memory_operations_source_issue_id_issues_id_fk" FOREIGN KEY ("source_issue_id") REFERENCES "public"."issues"("id") ON DELETE no action ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "memory_operations" ADD CONSTRAINT "memory_operations_source_comment_id_issue_comments_id_fk" FOREIGN KEY ("source_comment_id") REFERENCES "public"."issue_comments"("id") ON DELETE no action ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "memory_operations" ADD CONSTRAINT "memory_operations_source_run_id_heartbeat_runs_id_fk" FOREIGN KEY ("source_run_id") REFERENCES "public"."heartbeat_runs"("id") ON DELETE no action ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "memory_operations" ADD CONSTRAINT "memory_operations_source_activity_id_activity_log_id_fk" FOREIGN KEY ("source_activity_id") REFERENCES "public"."activity_log"("id") ON DELETE no action ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "memory_operations" ADD CONSTRAINT "memory_operations_cost_event_id_cost_events_id_fk" FOREIGN KEY ("cost_event_id") REFERENCES "public"."cost_events"("id") ON DELETE no action ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	ALTER TABLE "memory_operations" ADD CONSTRAINT "memory_operations_finance_event_id_finance_events_id_fk" FOREIGN KEY ("finance_event_id") REFERENCES "public"."finance_events"("id") ON DELETE no action ON UPDATE no action;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "background_job_cost_events_run_idx" ON "background_job_cost_events" USING btree ("run_id");--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "background_job_cost_events_cost_event_uq" ON "background_job_cost_events" USING btree ("cost_event_id");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "background_job_events_run_created_idx" ON "background_job_events" USING btree ("run_id","created_at");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "background_job_events_company_created_idx" ON "background_job_events" USING btree ("company_id","created_at");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "background_job_runs_company_created_idx" ON "background_job_runs" USING btree ("company_id","created_at");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "background_job_runs_company_type_status_idx" ON "background_job_runs" USING btree ("company_id","job_type","status");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "background_job_runs_company_issue_created_idx" ON "background_job_runs" USING btree ("company_id","source_issue_id","created_at");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "background_job_runs_job_created_idx" ON "background_job_runs" USING btree ("job_id","created_at");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "background_jobs_company_type_status_idx" ON "background_jobs" USING btree ("company_id","job_type","status");--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "background_jobs_company_key_uq" ON "background_jobs" USING btree ("company_id","key");--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "memory_binding_targets_company_target_idx" ON "memory_binding_targets" USING btree ("company_id","target_type","target_id");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "memory_binding_targets_company_binding_idx" ON "memory_binding_targets" USING btree ("company_id","binding_id");--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "memory_bindings_company_key_idx" ON "memory_bindings" USING btree ("company_id","key");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "memory_bindings_company_provider_idx" ON "memory_bindings" USING btree ("company_id","provider_key");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "memory_extraction_jobs_company_status_created_idx" ON "memory_extraction_jobs" USING btree ("company_id","status","created_at");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "memory_extraction_jobs_company_binding_created_idx" ON "memory_extraction_jobs" USING btree ("company_id","binding_id","created_at");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "memory_local_records_company_binding_created_idx" ON "memory_local_records" USING btree ("company_id","binding_id","created_at");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "memory_local_records_company_agent_created_idx" ON "memory_local_records" USING btree ("company_id","scope_agent_id","created_at");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "memory_local_records_company_issue_created_idx" ON "memory_local_records" USING btree ("company_id","scope_issue_id","created_at");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "memory_local_records_company_scope_created_idx" ON "memory_local_records" USING btree ("company_id","scope_type","scope_id","created_at");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "memory_local_records_company_sensitivity_created_idx" ON "memory_local_records" USING btree ("company_id","sensitivity_label","created_at");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "memory_local_records_company_retention_created_idx" ON "memory_local_records" USING btree ("company_id","retention_state","expires_at","created_at");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "memory_local_records_company_review_created_idx" ON "memory_local_records" USING btree ("company_id","review_state","created_at");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "memory_local_records_fts_idx" ON "memory_local_records" USING gin (to_tsvector('english', coalesce("title", '') || ' ' || "content"));--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "memory_operations_company_occurred_idx" ON "memory_operations" USING btree ("company_id","occurred_at");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "memory_operations_company_binding_occurred_idx" ON "memory_operations" USING btree ("company_id","binding_id","occurred_at");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "memory_operations_company_issue_occurred_idx" ON "memory_operations" USING btree ("company_id","scope_issue_id","occurred_at");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "memory_operations_company_run_occurred_idx" ON "memory_operations" USING btree ("company_id","scope_run_id","occurred_at");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "memory_operations_company_scope_occurred_idx" ON "memory_operations" USING btree ("company_id","scope_type","scope_id","occurred_at");
@@ -1,104 +0,0 @@
-CREATE TABLE "background_job_cost_events" (
-	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
-	"company_id" uuid NOT NULL,
-	"run_id" uuid NOT NULL,
-	"cost_event_id" uuid NOT NULL,
-	"created_at" timestamp with time zone DEFAULT now() NOT NULL
-);
--> statement-breakpoint
-CREATE TABLE "background_job_events" (
-	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
-	"company_id" uuid NOT NULL,
-	"run_id" uuid NOT NULL,
-	"event_type" text NOT NULL,
-	"level" text DEFAULT 'info' NOT NULL,
-	"message" text,
-	"progress_percent" integer,
-	"total_items" integer,
-	"processed_items" integer,
-	"succeeded_items" integer,
-	"failed_items" integer,
-	"skipped_items" integer,
-	"current_item" text,
-	"details" jsonb,
-	"created_at" timestamp with time zone DEFAULT now() NOT NULL
-);
--> statement-breakpoint
-CREATE TABLE "background_job_runs" (
-	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
-	"company_id" uuid NOT NULL,
-	"job_id" uuid,
-	"job_key" text NOT NULL,
-	"job_type" text NOT NULL,
-	"trigger" text DEFAULT 'manual' NOT NULL,
-	"status" text DEFAULT 'queued' NOT NULL,
-	"requested_by_actor_type" text DEFAULT 'system' NOT NULL,
-	"requested_by_actor_id" text DEFAULT 'system' NOT NULL,
-	"requested_by_agent_id" uuid,
-	"requested_by_user_id" text,
-	"source_issue_id" uuid,
-	"source_project_id" uuid,
-	"source_agent_id" uuid,
-	"heartbeat_run_id" uuid,
-	"total_items" integer,
-	"processed_items" integer DEFAULT 0 NOT NULL,
-	"succeeded_items" integer DEFAULT 0 NOT NULL,
-	"failed_items" integer DEFAULT 0 NOT NULL,
-	"skipped_items" integer DEFAULT 0 NOT NULL,
-	"progress_percent" integer,
-	"current_item" text,
-	"cancellation_requested_at" timestamp with time zone,
-	"cancelled_at" timestamp with time zone,
-	"error" text,
-	"result" jsonb,
-	"started_at" timestamp with time zone,
-	"finished_at" timestamp with time zone,
-	"duration_ms" integer,
-	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
-	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
-);
--> statement-breakpoint
-CREATE TABLE "background_jobs" (
-	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
-	"company_id" uuid NOT NULL,
-	"key" text NOT NULL,
-	"job_type" text NOT NULL,
-	"display_name" text NOT NULL,
-	"description" text,
-	"backend_kind" text DEFAULT 'server_worker' NOT NULL,
-	"status" text DEFAULT 'active' NOT NULL,
-	"config" jsonb DEFAULT '{}'::jsonb NOT NULL,
-	"created_by_agent_id" uuid,
-	"created_by_user_id" text,
-	"source_issue_id" uuid,
-	"source_project_id" uuid,
-	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
-	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
-);
--> statement-breakpoint
-ALTER TABLE "background_job_cost_events" ADD CONSTRAINT "background_job_cost_events_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "background_job_cost_events" ADD CONSTRAINT "background_job_cost_events_run_id_background_job_runs_id_fk" FOREIGN KEY ("run_id") REFERENCES "public"."background_job_runs"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "background_job_cost_events" ADD CONSTRAINT "background_job_cost_events_cost_event_id_cost_events_id_fk" FOREIGN KEY ("cost_event_id") REFERENCES "public"."cost_events"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "background_job_events" ADD CONSTRAINT "background_job_events_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "background_job_events" ADD CONSTRAINT "background_job_events_run_id_background_job_runs_id_fk" FOREIGN KEY ("run_id") REFERENCES "public"."background_job_runs"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "background_job_runs" ADD CONSTRAINT "background_job_runs_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "background_job_runs" ADD CONSTRAINT "background_job_runs_job_id_background_jobs_id_fk" FOREIGN KEY ("job_id") REFERENCES "public"."background_jobs"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "background_job_runs" ADD CONSTRAINT "background_job_runs_requested_by_agent_id_agents_id_fk" FOREIGN KEY ("requested_by_agent_id") REFERENCES "public"."agents"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "background_job_runs" ADD CONSTRAINT "background_job_runs_source_issue_id_issues_id_fk" FOREIGN KEY ("source_issue_id") REFERENCES "public"."issues"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "background_job_runs" ADD CONSTRAINT "background_job_runs_source_project_id_projects_id_fk" FOREIGN KEY ("source_project_id") REFERENCES "public"."projects"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "background_job_runs" ADD CONSTRAINT "background_job_runs_source_agent_id_agents_id_fk" FOREIGN KEY ("source_agent_id") REFERENCES "public"."agents"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "background_job_runs" ADD CONSTRAINT "background_job_runs_heartbeat_run_id_heartbeat_runs_id_fk" FOREIGN KEY ("heartbeat_run_id") REFERENCES "public"."heartbeat_runs"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "background_jobs" ADD CONSTRAINT "background_jobs_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "background_jobs" ADD CONSTRAINT "background_jobs_created_by_agent_id_agents_id_fk" FOREIGN KEY ("created_by_agent_id") REFERENCES "public"."agents"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "background_jobs" ADD CONSTRAINT "background_jobs_source_issue_id_issues_id_fk" FOREIGN KEY ("source_issue_id") REFERENCES "public"."issues"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "background_jobs" ADD CONSTRAINT "background_jobs_source_project_id_projects_id_fk" FOREIGN KEY ("source_project_id") REFERENCES "public"."projects"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
-CREATE INDEX "background_job_cost_events_run_idx" ON "background_job_cost_events" USING btree ("run_id");--> statement-breakpoint
-CREATE UNIQUE INDEX "background_job_cost_events_cost_event_uq" ON "background_job_cost_events" USING btree ("cost_event_id");--> statement-breakpoint
-CREATE INDEX "background_job_events_run_created_idx" ON "background_job_events" USING btree ("run_id","created_at");--> statement-breakpoint
-CREATE INDEX "background_job_events_company_created_idx" ON "background_job_events" USING btree ("company_id","created_at");--> statement-breakpoint
-CREATE INDEX "background_job_runs_company_created_idx" ON "background_job_runs" USING btree ("company_id","created_at");--> statement-breakpoint
-CREATE INDEX "background_job_runs_company_type_status_idx" ON "background_job_runs" USING btree ("company_id","job_type","status");--> statement-breakpoint
-CREATE INDEX "background_job_runs_company_issue_created_idx" ON "background_job_runs" USING btree ("company_id","source_issue_id","created_at");--> statement-breakpoint
-CREATE INDEX "background_job_runs_job_created_idx" ON "background_job_runs" USING btree ("job_id","created_at");--> statement-breakpoint
-CREATE INDEX "background_jobs_company_type_status_idx" ON "background_jobs" USING btree ("company_id","job_type","status");--> statement-breakpoint
-CREATE UNIQUE INDEX "background_jobs_company_key_uq" ON "background_jobs" USING btree ("company_id","key");
@@ -1,6 +1,6 @@
 {
-  "id": "7489b6fa-6a53-4c30-a852-73761e7a3da9",
-  "prevId": "0cb92f3b-c1c4-454a-9ccd-e8d43aebbeda",
+  "id": "11957e00-fbcf-4021-9d6e-3a97126ff0f1",
+  "prevId": "58b07646-6b04-4945-b6d2-e3409d238235",
  "version": "7",
  "dialect": "postgresql",
  "tables": {
@@ -4654,6 +4654,125 @@
      "checkConstraints": {},
      "isRLSEnabled": false
    },
+    "public.company_user_sidebar_preferences": {
+      "name": "company_user_sidebar_preferences",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "company_id": {
+          "name": "company_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "project_order": {
+          "name": "project_order",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'[]'::jsonb"
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "company_user_sidebar_preferences_company_idx": {
+          "name": "company_user_sidebar_preferences_company_idx",
+          "columns": [
+            {
+              "expression": "company_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "company_user_sidebar_preferences_user_idx": {
+          "name": "company_user_sidebar_preferences_user_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "company_user_sidebar_preferences_company_user_uq": {
+          "name": "company_user_sidebar_preferences_company_user_uq",
+          "columns": [
+            {
+              "expression": "company_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "company_user_sidebar_preferences_company_id_companies_id_fk": {
+          "name": "company_user_sidebar_preferences_company_id_companies_id_fk",
+          "tableFrom": "company_user_sidebar_preferences",
+          "tableTo": "companies",
+          "columnsFrom": [
+            "company_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
    "public.cost_events": {
      "name": "cost_events",
      "schema": "",
@@ -7257,6 +7376,37 @@
          "primaryKey": false,
          "notNull": false
        },
+        "liveness_state": {
+          "name": "liveness_state",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "liveness_reason": {
+          "name": "liveness_reason",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "continuation_attempt": {
+          "name": "continuation_attempt",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "last_useful_action_at": {
+          "name": "last_useful_action_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "next_action": {
+          "name": "next_action",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
        "context_snapshot": {
          "name": "context_snapshot",
          "type": "jsonb",
@@ -7305,6 +7455,33 @@
          "concurrently": false,
          "method": "btree",
          "with": {}
+        },
+        "heartbeat_runs_company_liveness_idx": {
+          "name": "heartbeat_runs_company_liveness_idx",
+          "columns": [
+            {
+              "expression": "company_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "liveness_state",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
        }
      },
      "foreignKeys": {
@@ -10551,6 +10728,50 @@
          "concurrently": false,
          "method": "btree",
          "with": {}
+        },
+        "join_requests_pending_human_user_uq": {
+          "name": "join_requests_pending_human_user_uq",
+          "columns": [
+            {
+              "expression": "company_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "requesting_user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"join_requests\".\"request_type\" = 'human' AND \"join_requests\".\"status\" = 'pending_approval' AND \"join_requests\".\"requesting_user_id\" IS NOT NULL",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "join_requests_pending_human_email_uq": {
+          "name": "join_requests_pending_human_email_uq",
+          "columns": [
+            {
+              "expression": "company_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "lower(\"request_email_snapshot\")",
+              "asc": true,
+              "isExpression": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"join_requests\".\"request_type\" = 'human' AND \"join_requests\".\"status\" = 'pending_approval' AND \"join_requests\".\"request_email_snapshot\" IS NOT NULL",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
        }
      },
      "foreignKeys": {
@@ -15180,6 +15401,69 @@
      "checkConstraints": {},
      "isRLSEnabled": false
    },
+    "public.user_sidebar_preferences": {
+      "name": "user_sidebar_preferences",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "company_order": {
+          "name": "company_order",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'[]'::jsonb"
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "user_sidebar_preferences_user_uq": {
+          "name": "user_sidebar_preferences_user_uq",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
    "public.workspace_operations": {
      "name": "workspace_operations",
      "schema": "",
@@ -397,29 +397,29 @@
    {
      "idx": 56,
      "version": "7",
-      "when": 1775925298474,
-      "tag": "0056_oval_gauntlet",
+      "when": 1776084034244,
+      "tag": "0056_spooky_ultragirl",
      "breakpoints": true
    },
    {
      "idx": 57,
      "version": "7",
-      "when": 1776377673907,
-      "tag": "0057_misty_riptide",
+      "when": 1776309613598,
+      "tag": "0057_tidy_join_requests",
      "breakpoints": true
    },
    {
      "idx": 58,
      "version": "7",
-      "when": 1776647797670,
-      "tag": "0058_lovely_eternals",
+      "when": 1776542245004,
+      "tag": "0058_wealthy_starbolt",
      "breakpoints": true
    },
    {
      "idx": 59,
      "version": "7",
-      "when": 1776648937778,
-      "tag": "0059_lazy_nick_fury",
+      "when": 1776687049119,
+      "tag": "0059_foamy_jackpot",
      "breakpoints": true
    }
  ]
@@ -0,0 +1,22 @@
+import { pgTable, uuid, text, timestamp, jsonb, uniqueIndex, index } from "drizzle-orm/pg-core";
+import { companies } from "./companies.js";
+
+export const companyUserSidebarPreferences = pgTable(
+  "company_user_sidebar_preferences",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    companyId: uuid("company_id").notNull().references(() => companies.id, { onDelete: "cascade" }),
+    userId: text("user_id").notNull(),
+    projectOrder: jsonb("project_order").$type<string[]>().notNull().default([]),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    companyIdx: index("company_user_sidebar_preferences_company_idx").on(table.companyId),
+    userIdx: index("company_user_sidebar_preferences_user_idx").on(table.userId),
+    companyUserUq: uniqueIndex("company_user_sidebar_preferences_company_user_uq").on(
+      table.companyId,
+      table.userId,
+    ),
+  }),
+);
@@ -41,6 +41,11 @@ export const heartbeatRuns = pgTable(
    issueCommentStatus: text("issue_comment_status").notNull().default("not_applicable"),
    issueCommentSatisfiedByCommentId: uuid("issue_comment_satisfied_by_comment_id"),
    issueCommentRetryQueuedAt: timestamp("issue_comment_retry_queued_at", { withTimezone: true }),
+    livenessState: text("liveness_state"),
+    livenessReason: text("liveness_reason"),
+    continuationAttempt: integer("continuation_attempt").notNull().default(0),
+    lastUsefulActionAt: timestamp("last_useful_action_at", { withTimezone: true }),
+    nextAction: text("next_action"),
    contextSnapshot: jsonb("context_snapshot").$type<Record<string, unknown>>(),
    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
@@ -51,5 +56,10 @@ export const heartbeatRuns = pgTable(
      table.agentId,
      table.startedAt,
    ),
+    companyLivenessIdx: index("heartbeat_runs_company_liveness_idx").on(
+      table.companyId,
+      table.livenessState,
+      table.createdAt,
+    ),
  }),
 );
@@ -3,10 +3,12 @@ export { companyLogos } from "./company_logos.js";
 export { authUsers, authSessions, authAccounts, authVerifications } from "./auth.js";
 export { instanceSettings } from "./instance_settings.js";
 export { instanceUserRoles } from "./instance_user_roles.js";
+export { userSidebarPreferences } from "./user_sidebar_preferences.js";
 export { agents } from "./agents.js";
 export { boardApiKeys } from "./board_api_keys.js";
 export { cliAuthChallenges } from "./cli_auth_challenges.js";
 export { companyMemberships } from "./company_memberships.js";
+export { companyUserSidebarPreferences } from "./company_user_sidebar_preferences.js";
 export { principalPermissionGrants } from "./principal_permission_grants.js";
 export { invites } from "./invites.js";
 export { joinRequests } from "./join_requests.js";
@@ -1,3 +1,4 @@
+import { sql } from "drizzle-orm";
 import { pgTable, uuid, text, timestamp, jsonb, index, uniqueIndex } from "drizzle-orm/pg-core";
 import { companies } from "./companies.js";
 import { invites } from "./invites.js";
@@ -37,5 +38,11 @@ export const joinRequests = pgTable(
      table.requestType,
      table.createdAt,
    ),
+    pendingHumanUserUniqueIdx: uniqueIndex("join_requests_pending_human_user_uq")
+      .on(table.companyId, table.requestingUserId)
+      .where(sql`${table.requestType} = 'human' AND ${table.status} = 'pending_approval' AND ${table.requestingUserId} IS NOT NULL`),
+    pendingHumanEmailUniqueIdx: uniqueIndex("join_requests_pending_human_email_uq")
+      .on(table.companyId, sql`lower(${table.requestEmailSnapshot})`)
+      .where(sql`${table.requestType} = 'human' AND ${table.status} = 'pending_approval' AND ${table.requestEmailSnapshot} IS NOT NULL`),
  }),
 );
@@ -0,0 +1,15 @@
+import { pgTable, uuid, text, timestamp, jsonb, uniqueIndex } from "drizzle-orm/pg-core";
+
+export const userSidebarPreferences = pgTable(
+  "user_sidebar_preferences",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    userId: text("user_id").notNull(),
+    companyOrder: jsonb("company_order").$type<string[]>().notNull().default([]),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    userUq: uniqueIndex("user_sidebar_preferences_user_uq").on(table.userId),
+  }),
+);
@@ -13,6 +13,7 @@ export const API = {
  activity: `${API_PREFIX}/activity`,
  dashboard: `${API_PREFIX}/dashboard`,
  sidebarBadges: `${API_PREFIX}/sidebar-badges`,
+  sidebarPreferences: `${API_PREFIX}/sidebar-preferences`,
  invites: `${API_PREFIX}/invites`,
  joinRequests: `${API_PREFIX}/join-requests`,
  members: `${API_PREFIX}/members`,
@@ -66,6 +66,8 @@ export const AGENT_ROLE_LABELS: Record<AgentRole, string> = {
  general: "General",
 };

+export const AGENT_DEFAULT_MAX_CONCURRENT_RUNS = 5;
+
 export const AGENT_ICON_NAMES = [
  "bot",
  "cpu",
@@ -141,6 +143,16 @@ export type IssueOriginKind = (typeof ISSUE_ORIGIN_KINDS)[number];
 export const ISSUE_RELATION_TYPES = ["blocks"] as const;
 export type IssueRelationType = (typeof ISSUE_RELATION_TYPES)[number];

+export const ISSUE_CONTINUATION_SUMMARY_DOCUMENT_KEY = "continuation-summary" as const;
+export const SYSTEM_ISSUE_DOCUMENT_KEYS = [ISSUE_CONTINUATION_SUMMARY_DOCUMENT_KEY] as const;
+export type SystemIssueDocumentKey = (typeof SYSTEM_ISSUE_DOCUMENT_KEYS)[number];
+
+const SYSTEM_ISSUE_DOCUMENT_KEY_SET = new Set<string>(SYSTEM_ISSUE_DOCUMENT_KEYS);
+
+export function isSystemIssueDocumentKey(key: string): key is SystemIssueDocumentKey {
+  return SYSTEM_ISSUE_DOCUMENT_KEY_SET.has(key);
+}
+
 export const ISSUE_EXECUTION_POLICY_MODES = ["normal", "auto"] as const;
 export type IssueExecutionPolicyMode = (typeof ISSUE_EXECUTION_POLICY_MODES)[number];

@@ -343,6 +355,17 @@ export const HEARTBEAT_RUN_STATUSES = [
 ] as const;
 export type HeartbeatRunStatus = (typeof HEARTBEAT_RUN_STATUSES)[number];

+export const RUN_LIVENESS_STATES = [
+  "completed",
+  "advanced",
+  "plan_only",
+  "empty_response",
+  "blocked",
+  "failed",
+  "needs_followup",
+] as const;
+export type RunLivenessState = (typeof RUN_LIVENESS_STATES)[number];
+
 export const LIVE_EVENT_TYPES = [
  "heartbeat.run.queued",
  "heartbeat.run.status",
@@ -359,9 +382,33 @@ export type LiveEventType = (typeof LIVE_EVENT_TYPES)[number];
 export const PRINCIPAL_TYPES = ["user", "agent"] as const;
 export type PrincipalType = (typeof PRINCIPAL_TYPES)[number];

-export const MEMBERSHIP_STATUSES = ["pending", "active", "suspended"] as const;
+export const MEMBERSHIP_STATUSES = ["pending", "active", "suspended", "archived"] as const;
 export type MembershipStatus = (typeof MEMBERSHIP_STATUSES)[number];

+export const COMPANY_MEMBERSHIP_ROLES = [
+  "owner",
+  "admin",
+  "operator",
+  "viewer",
+  "member",
+] as const;
+export type CompanyMembershipRole = (typeof COMPANY_MEMBERSHIP_ROLES)[number];
+
+export const HUMAN_COMPANY_MEMBERSHIP_ROLES = [
+  "owner",
+  "admin",
+  "operator",
+  "viewer",
+] as const;
+export type HumanCompanyMembershipRole = (typeof HUMAN_COMPANY_MEMBERSHIP_ROLES)[number];
+
+export const HUMAN_COMPANY_MEMBERSHIP_ROLE_LABELS: Record<HumanCompanyMembershipRole, string> = {
+  owner: "Owner",
+  admin: "Admin",
+  operator: "Operator",
+  viewer: "Viewer",
+};
+
 export const INSTANCE_USER_ROLES = ["instance_admin"] as const;
 export type InstanceUserRole = (typeof INSTANCE_USER_ROLES)[number];

@@ -9,6 +9,7 @@ export {
  AGENT_ADAPTER_TYPES,
  AGENT_ROLES,
  AGENT_ROLE_LABELS,
+  AGENT_DEFAULT_MAX_CONCURRENT_RUNS,
  AGENT_ICON_NAMES,
  ISSUE_STATUSES,
  INBOX_MINE_ISSUE_STATUSES,
@@ -16,6 +17,9 @@ export {
  ISSUE_PRIORITIES,
  ISSUE_ORIGIN_KINDS,
  ISSUE_RELATION_TYPES,
+  ISSUE_CONTINUATION_SUMMARY_DOCUMENT_KEY,
+  SYSTEM_ISSUE_DOCUMENT_KEYS,
+  isSystemIssueDocumentKey,
  ISSUE_EXECUTION_POLICY_MODES,
  ISSUE_EXECUTION_STAGE_TYPES,
  ISSUE_EXECUTION_STATE_STATUSES,
@@ -49,11 +53,15 @@ export {
  BUDGET_INCIDENT_RESOLUTION_ACTIONS,
  HEARTBEAT_INVOCATION_SOURCES,
  HEARTBEAT_RUN_STATUSES,
+  RUN_LIVENESS_STATES,
  WAKEUP_TRIGGER_DETAILS,
  WAKEUP_REQUEST_STATUSES,
  LIVE_EVENT_TYPES,
  PRINCIPAL_TYPES,
  MEMBERSHIP_STATUSES,
+  COMPANY_MEMBERSHIP_ROLES,
+  HUMAN_COMPANY_MEMBERSHIP_ROLES,
+  HUMAN_COMPANY_MEMBERSHIP_ROLE_LABELS,
  INSTANCE_USER_ROLES,
  INVITE_TYPES,
  INVITE_JOIN_TYPES,
@@ -112,6 +120,7 @@ export {
  type IssuePriority,
  type IssueOriginKind,
  type IssueRelationType,
+  type SystemIssueDocumentKey,
  type IssueExecutionPolicyMode,
  type IssueExecutionStageType,
  type IssueExecutionStateStatus,
@@ -144,11 +153,14 @@ export {
  type BudgetIncidentResolutionAction,
  type HeartbeatInvocationSource,
  type HeartbeatRunStatus,
+  type RunLivenessState,
  type WakeupTriggerDetail,
  type WakeupRequestStatus,
  type LiveEventType,
  type PrincipalType,
  type MembershipStatus,
+  type CompanyMembershipRole,
+  type HumanCompanyMembershipRole,
  type InstanceUserRole,
  type InviteType,
  type InviteJoinType,
@@ -268,6 +280,7 @@ export type {
  ProjectGoalRef,
  ProjectWorkspace,
  ExecutionWorkspace,
+  ExecutionWorkspaceSummary,
  ExecutionWorkspaceConfig,
  ExecutionWorkspaceCloseAction,
  ExecutionWorkspaceCloseActionKind,
@@ -276,7 +289,11 @@ export type {
  ExecutionWorkspaceCloseReadiness,
  ExecutionWorkspaceCloseReadinessState,
  ProjectWorkspaceRuntimeConfig,
+  WorkspaceCommandDefinition,
+  WorkspaceCommandKind,
+  WorkspaceRuntimeControlTarget,
  WorkspaceRuntimeService,
+  WorkspaceRuntimeServiceStateMap,
  WorkspaceOperation,
  WorkspaceOperationPhase,
  WorkspaceOperationStatus,
@@ -388,13 +405,32 @@ export type {
  LiveEvent,
  DashboardSummary,
  ActivityEvent,
+  UserProfileActivitySummary,
+  UserProfileAgentUsage,
+  UserProfileDailyPoint,
+  UserProfileIdentity,
+  UserProfileIssueSummary,
+  UserProfileProviderUsage,
+  UserProfileResponse,
+  UserProfileWindowStats,
  SidebarBadges,
+  SidebarOrderPreference,
  InboxDismissal,
+  AccessUserProfile,
+  CompanyMemberRecord,
+  CompanyMembersResponse,
  CompanyMembership,
+  CompanyInviteListResponse,
+  CompanyInviteRecord,
  PrincipalPermissionGrant,
  Invite,
  JoinRequest,
+  JoinRequestInviteSummary,
+  JoinRequestRecord,
  InstanceUserRoleGrant,
+  AdminUserDirectoryEntry,
+  UserCompanyAccessEntry,
+  UserCompanyAccessResponse,
  CompanyPortabilityInclude,
  CompanyPortabilityEnvInput,
  CompanyPortabilityFileEntry,
@@ -463,6 +499,21 @@ export type {
  ProviderQuotaResult,
 } from "./types/index.js";

+export {
+  sidebarOrderPreferenceSchema,
+  upsertSidebarOrderPreferenceSchema,
+  type UpsertSidebarOrderPreference,
+} from "./validators/sidebar-preferences.js";
+
+export { workspaceRuntimeControlTargetSchema } from "./validators/execution-workspace.js";
+export {
+  findWorkspaceCommandDefinition,
+  listWorkspaceCommandDefinitions,
+  listWorkspaceServiceCommandDefinitions,
+  matchWorkspaceRuntimeServiceToCommand,
+  scoreWorkspaceRuntimeServiceMatch,
+} from "./workspace-commands.js";
+
 export {
  DEFAULT_FEEDBACK_DATA_SHARING_PREFERENCE,
  FEEDBACK_TARGET_TYPES,
@@ -547,6 +598,7 @@ export {
  type UpdateProjectWorkspace,
  projectExecutionWorkspacePolicySchema,
  createIssueSchema,
+  createChildIssueSchema,
  createIssueLabelSchema,
  updateIssueSchema,
  issueExecutionPolicySchema,
@@ -574,6 +626,7 @@ export {
  upsertIssueDocumentSchema,
  restoreIssueDocumentRevisionSchema,
  type CreateIssue,
+  type CreateChildIssue,
  type CreateIssueLabel,
  type UpdateIssue,
  type CheckoutIssue,
@@ -671,12 +724,20 @@ export {
  createCompanyInviteSchema,
  createOpenClawInvitePromptSchema,
  acceptInviteSchema,
+  listCompanyInvitesQuerySchema,
  listJoinRequestsQuerySchema,
  claimJoinRequestApiKeySchema,
  boardCliAuthAccessLevelSchema,
  createCliAuthChallengeSchema,
  resolveCliAuthChallengeSchema,
+  currentUserProfileSchema,
+  authSessionSchema,
+  updateCurrentUserProfileSchema,
+  updateCompanyMemberSchema,
+  updateCompanyMemberWithPermissionsSchema,
+  archiveCompanyMemberSchema,
  updateMemberPermissionsSchema,
+  searchAdminUsersQuerySchema,
  updateUserCompanyAccessSchema,
  type CreateCostEvent,
  type CreateFinanceEvent,
@@ -713,12 +774,20 @@ export {
  type CreateCompanyInvite,
  type CreateOpenClawInvitePrompt,
  type AcceptInvite,
+  type ListCompanyInvitesQuery,
  type ListJoinRequestsQuery,
  type ClaimJoinRequestApiKey,
  type BoardCliAuthAccessLevel,
  type CreateCliAuthChallenge,
  type ResolveCliAuthChallenge,
+  type CurrentUserProfile,
+  type AuthSession,
+  type UpdateCurrentUserProfile,
+  type UpdateCompanyMember,
+  type UpdateCompanyMemberWithPermissions,
+  type ArchiveCompanyMember,
  type UpdateMemberPermissions,
+  type SearchAdminUsersQuery,
  type UpdateUserCompanyAccess,
  companySkillSourceTypeSchema,
  companySkillTrustLevelSchema,
@@ -798,18 +867,23 @@ export {
  AGENT_MENTION_SCHEME,
  PROJECT_MENTION_SCHEME,
  SKILL_MENTION_SCHEME,
+  USER_MENTION_SCHEME,
  buildAgentMentionHref,
  buildProjectMentionHref,
  buildSkillMentionHref,
+  buildUserMentionHref,
  extractAgentMentionIds,
+  extractProjectMentionIds,
  extractSkillMentionIds,
+  extractUserMentionIds,
  parseAgentMentionHref,
  parseProjectMentionHref,
  parseSkillMentionHref,
-  extractProjectMentionIds,
+  parseUserMentionHref,
  type ParsedAgentMention,
  type ParsedProjectMention,
  type ParsedSkillMention,
+  type ParsedUserMention,
 } from "./project-mentions.js";

 export {
@@ -3,12 +3,15 @@ import {
  buildAgentMentionHref,
  buildProjectMentionHref,
  buildSkillMentionHref,
+  buildUserMentionHref,
  extractAgentMentionIds,
  extractProjectMentionIds,
  extractSkillMentionIds,
+  extractUserMentionIds,
  parseAgentMentionHref,
  parseProjectMentionHref,
  parseSkillMentionHref,
+  parseUserMentionHref,
 } from "./project-mentions.js";

 describe("project-mentions", () => {
@@ -30,6 +33,14 @@ describe("project-mentions", () => {
    expect(extractAgentMentionIds(`[@CodexCoder](${href})`)).toEqual(["agent-123"]);
  });

+  it("round-trips user mentions", () => {
+    const href = buildUserMentionHref("user-123");
+    expect(parseUserMentionHref(href)).toEqual({
+      userId: "user-123",
+    });
+    expect(extractUserMentionIds(`[@Taylor](${href})`)).toEqual(["user-123"]);
+  });
+
  it("round-trips skill mentions with slug metadata", () => {
    const href = buildSkillMentionHref("skill-123", "release-changelog");
    expect(parseSkillMentionHref(href)).toEqual({
@@ -1,5 +1,6 @@
 export const PROJECT_MENTION_SCHEME = "project://";
 export const AGENT_MENTION_SCHEME = "agent://";
+export const USER_MENTION_SCHEME = "user://";
 export const SKILL_MENTION_SCHEME = "skill://";

 const HEX_COLOR_RE = /^[0-9a-f]{6}$/i;
@@ -8,6 +9,7 @@ const HEX_COLOR_WITH_HASH_RE = /^#[0-9a-f]{6}$/i;
 const HEX_COLOR_SHORT_WITH_HASH_RE = /^#[0-9a-f]{3}$/i;
 const PROJECT_MENTION_LINK_RE = /\[[^\]]*]\((project:\/\/[^)\s]+)\)/gi;
 const AGENT_MENTION_LINK_RE = /\[[^\]]*]\((agent:\/\/[^)\s]+)\)/gi;
+const USER_MENTION_LINK_RE = /\[[^\]]*]\((user:\/\/[^)\s]+)\)/gi;
 const SKILL_MENTION_LINK_RE = /\[[^\]]*]\((skill:\/\/[^)\s]+)\)/gi;
 const AGENT_ICON_NAME_RE = /^[a-z0-9-]+$/i;
 const SKILL_SLUG_RE = /^[a-z0-9][a-z0-9-]*$/i;
@@ -22,6 +24,10 @@ export interface ParsedAgentMention {
  icon: string | null;
 }

+export interface ParsedUserMention {
+  userId: string;
+}
+
 export interface ParsedSkillMention {
  skillId: string;
  slug: string | null;
@@ -111,6 +117,28 @@ export function parseAgentMentionHref(href: string): ParsedAgentMention | null {
  };
 }

+export function buildUserMentionHref(userId: string): string {
+  return `${USER_MENTION_SCHEME}${userId.trim()}`;
+}
+
+export function parseUserMentionHref(href: string): ParsedUserMention | null {
+  if (!href.startsWith(USER_MENTION_SCHEME)) return null;
+
+  let url: URL;
+  try {
+    url = new URL(href);
+  } catch {
+    return null;
+  }
+
+  if (url.protocol !== "user:") return null;
+
+  const userId = `${url.hostname}${url.pathname}`.replace(/^\/+/, "").trim();
+  if (!userId) return null;
+
+  return { userId };
+}
+
 export function buildSkillMentionHref(skillId: string, slug?: string | null): string {
  const trimmedSkillId = skillId.trim();
  const normalizedSlug = normalizeSkillSlug(slug ?? null);
@@ -165,6 +193,18 @@ export function extractAgentMentionIds(markdown: string): string[] {
  return [...ids];
 }

+export function extractUserMentionIds(markdown: string): string[] {
+  if (!markdown) return [];
+  const ids = new Set<string>();
+  const re = new RegExp(USER_MENTION_LINK_RE);
+  let match: RegExpExecArray | null;
+  while ((match = re.exec(markdown)) !== null) {
+    const parsed = parseUserMentionHref(match[1]);
+    if (parsed) ids.add(parsed.userId);
+  }
+  return [...ids];
+}
+
 export function extractSkillMentionIds(markdown: string): string[] {
  if (!markdown) return [];
  const ids = new Set<string>();
@@ -50,9 +50,12 @@ export function trackGoalCreated(

 export function trackAgentCreated(
  client: TelemetryClient,
-  dims: { agentRole: string },
+  dims: { agentRole: string; agentId?: string },
 ): void {
-  client.track("agent.created", { agent_role: dims.agentRole });
+  client.track("agent.created", {
+    agent_role: dims.agentRole,
+    ...(dims.agentId ? { agent_id: dims.agentId } : {}),
+  });
 }

 export function trackSkillImported(
@@ -67,16 +70,24 @@ export function trackSkillImported(

 export function trackAgentFirstHeartbeat(
  client: TelemetryClient,
-  dims: { agentRole: string },
+  dims: { agentRole: string; agentId?: string },
 ): void {
-  client.track("agent.first_heartbeat", { agent_role: dims.agentRole });
+  client.track("agent.first_heartbeat", {
+    agent_role: dims.agentRole,
+    ...(dims.agentId ? { agent_id: dims.agentId } : {}),
+  });
 }

 export function trackAgentTaskCompleted(
  client: TelemetryClient,
-  dims: { agentRole: string },
+  dims: { agentRole: string; agentId?: string; adapterType?: string; model?: string },
 ): void {
-  client.track("agent.task_completed", { agent_role: dims.agentRole });
+  client.track("agent.task_completed", {
+    agent_role: dims.agentRole,
+    ...(dims.agentId ? { agent_id: dims.agentId } : {}),
+    ...(dims.adapterType ? { adapter_type: dims.adapterType } : {}),
+    ...(dims.model ? { model: dims.model } : {}),
+  });
 }

 export function trackErrorHandlerCrash(
@@ -1,5 +1,7 @@
 import type {
  AgentAdapterType,
+  CompanyStatus,
+  HumanCompanyMembershipRole,
  InstanceUserRole,
  InviteJoinType,
  InviteType,
@@ -33,6 +35,39 @@ export interface PrincipalPermissionGrant {
  updatedAt: Date;
 }

+export interface AccessUserProfile {
+  id: string;
+  email: string | null;
+  name: string | null;
+  image: string | null;
+}
+
+export interface CompanyMemberRecord extends CompanyMembership {
+  principalType: "user";
+  membershipRole: HumanCompanyMembershipRole | null;
+  user: AccessUserProfile | null;
+  grants: PrincipalPermissionGrant[];
+  removal?: {
+    canArchive: boolean;
+    reason: string | null;
+  };
+}
+
+export interface CompanyMembersResponse {
+  members: CompanyMemberRecord[];
+  access: {
+    currentUserRole: HumanCompanyMembershipRole | null;
+    canManageMembers: boolean;
+    canInviteUsers: boolean;
+    canApproveJoinRequests: boolean;
+  };
+}
+
+export interface ArchiveCompanyMemberResponse {
+  member: CompanyMemberRecord;
+  reassignedIssueCount: number;
+}
+
 export interface Invite {
  id: string;
  companyId: string | null;
@@ -48,6 +83,22 @@ export interface Invite {
  updatedAt: Date;
 }

+export type InviteState = "active" | "revoked" | "accepted" | "expired";
+
+export interface CompanyInviteRecord extends Invite {
+  companyName: string | null;
+  humanRole: HumanCompanyMembershipRole | null;
+  inviteMessage: string | null;
+  state: InviteState;
+  invitedByUser: AccessUserProfile | null;
+  relatedJoinRequestId: string | null;
+}
+
+export interface CompanyInviteListResponse {
+  invites: CompanyInviteRecord[];
+  nextOffset: number | null;
+}
+
 export interface JoinRequest {
  id: string;
  inviteId: string;
@@ -72,6 +123,26 @@ export interface JoinRequest {
  updatedAt: Date;
 }

+export interface JoinRequestInviteSummary {
+  id: string;
+  inviteType: InviteType;
+  allowedJoinTypes: InviteJoinType;
+  humanRole: HumanCompanyMembershipRole | null;
+  inviteMessage: string | null;
+  createdAt: Date;
+  expiresAt: Date;
+  revokedAt: Date | null;
+  acceptedAt: Date | null;
+  invitedByUser: AccessUserProfile | null;
+}
+
+export interface JoinRequestRecord extends JoinRequest {
+  requesterUser: AccessUserProfile | null;
+  approvedByUser: AccessUserProfile | null;
+  rejectedByUser: AccessUserProfile | null;
+  invite: JoinRequestInviteSummary | null;
+}
+
 export interface InstanceUserRoleGrant {
  id: string;
  userId: string;
@@ -79,3 +150,21 @@ export interface InstanceUserRoleGrant {
  createdAt: Date;
  updatedAt: Date;
 }
+
+export interface AdminUserDirectoryEntry extends AccessUserProfile {
+  isInstanceAdmin: boolean;
+  activeCompanyMembershipCount: number;
+}
+
+export interface UserCompanyAccessEntry extends CompanyMembership {
+  principalType: "user";
+  companyName: string | null;
+  companyStatus: CompanyStatus | null;
+}
+
+export interface UserCompanyAccessResponse {
+  user: (AccessUserProfile & {
+    isInstanceAdmin: boolean;
+  }) | null;
+  companyAccess: UserCompanyAccessEntry[];
+}
@@ -3,6 +3,7 @@ import type {
  AgentStatus,
  HeartbeatInvocationSource,
  HeartbeatRunStatus,
+  RunLivenessState,
  WakeupTriggerDetail,
  WakeupRequestStatus,
 } from "../constants.js";
@@ -38,6 +39,11 @@ export interface HeartbeatRun {
  processStartedAt: Date | null;
  retryOfRunId: string | null;
  processLossRetryCount: number;
+  livenessState: RunLivenessState | null;
+  livenessReason: string | null;
+  continuationAttempt: number;
+  lastUsefulActionAt: Date | null;
+  nextAction: string | null;
  contextSnapshot: Record<string, unknown> | null;
  createdAt: Date;
  updatedAt: Date;
@@ -63,6 +63,7 @@ export type { AssetImage } from "./asset.js";
 export type { Project, ProjectCodebase, ProjectCodebaseOrigin, ProjectGoalRef, ProjectWorkspace } from "./project.js";
 export type {
  ExecutionWorkspace,
+  ExecutionWorkspaceSummary,
  ExecutionWorkspaceConfig,
  ExecutionWorkspaceCloseAction,
  ExecutionWorkspaceCloseActionKind,
@@ -71,7 +72,11 @@ export type {
  ExecutionWorkspaceCloseReadiness,
  ExecutionWorkspaceCloseReadinessState,
  ProjectWorkspaceRuntimeConfig,
+  WorkspaceCommandDefinition,
+  WorkspaceCommandKind,
+  WorkspaceRuntimeControlTarget,
  WorkspaceRuntimeService,
+  WorkspaceRuntimeServiceStateMap,
  WorkspaceRuntimeDesiredState,
  ExecutionWorkspaceStrategyType,
  ExecutionWorkspaceMode,
@@ -213,14 +218,36 @@ export type {
 export type { LiveEvent } from "./live.js";
 export type { DashboardSummary } from "./dashboard.js";
 export type { ActivityEvent } from "./activity.js";
+export type {
+  UserProfileActivitySummary,
+  UserProfileAgentUsage,
+  UserProfileDailyPoint,
+  UserProfileIdentity,
+  UserProfileIssueSummary,
+  UserProfileProviderUsage,
+  UserProfileResponse,
+  UserProfileWindowStats,
+} from "./user-profile.js";
 export type { SidebarBadges } from "./sidebar-badges.js";
+export type { SidebarOrderPreference } from "./sidebar-preferences.js";
 export type { InboxDismissal } from "./inbox-dismissal.js";
 export type {
+  AccessUserProfile,
+  CompanyMemberRecord,
+  CompanyMembersResponse,
+  ArchiveCompanyMemberResponse,
  CompanyMembership,
+  CompanyInviteListResponse,
+  CompanyInviteRecord,
  PrincipalPermissionGrant,
  Invite,
  JoinRequest,
+  JoinRequestInviteSummary,
+  JoinRequestRecord,
  InstanceUserRoleGrant,
+  AdminUserDirectoryEntry,
+  UserCompanyAccessEntry,
+  UserCompanyAccessResponse,
 } from "./access.js";
 export type { QuotaWindow, ProviderQuotaResult } from "./quota.js";
 export type {
@@ -1,10 +1,10 @@
 import type { PauseReason, ProjectStatus } from "../constants.js";
-import type { AgentEnvConfig } from "./secrets.js";
 import type {
  ProjectExecutionWorkspacePolicy,
  ProjectWorkspaceRuntimeConfig,
  WorkspaceRuntimeService,
 } from "./workspace-runtime.js";
+import type { AgentEnvConfig } from "./secrets.js";

 export type ProjectWorkspaceSourceType = "local_path" | "git_repo" | "remote_managed" | "non_git_path";
 export type ProjectWorkspaceVisibility = "default" | "advanced";
@@ -129,7 +129,7 @@ export interface RoutineExecutionIssueOrigin {
 }

 export interface RoutineListItem extends Routine {
-  triggers: Pick<RoutineTrigger, "id" | "kind" | "label" | "enabled" | "nextRunAt" | "lastFiredAt" | "lastResult">[];
+  triggers: Pick<RoutineTrigger, "id" | "kind" | "label" | "enabled" | "cronExpression" | "timezone" | "nextRunAt" | "lastFiredAt" | "lastResult">[];
  lastRun: RoutineRunSummary | null;
  activeIssue: RoutineIssueSummary | null;
 }
@@ -0,0 +1,4 @@
+export interface SidebarOrderPreference {
+  orderedIds: string[];
+  updatedAt: Date | null;
+}
@@ -0,0 +1,88 @@
+import type { IssuePriority, IssueStatus } from "../constants.js";
+
+export interface UserProfileIdentity {
+  id: string;
+  slug: string;
+  name: string | null;
+  email: string | null;
+  image: string | null;
+  membershipRole: string | null;
+  membershipStatus: string;
+  joinedAt: Date;
+}
+
+export interface UserProfileWindowStats {
+  key: "last7" | "last30" | "all";
+  label: string;
+  touchedIssues: number;
+  createdIssues: number;
+  completedIssues: number;
+  assignedOpenIssues: number;
+  commentCount: number;
+  activityCount: number;
+  costCents: number;
+  inputTokens: number;
+  cachedInputTokens: number;
+  outputTokens: number;
+  costEventCount: number;
+}
+
+export interface UserProfileDailyPoint {
+  date: string;
+  activityCount: number;
+  completedIssues: number;
+  costCents: number;
+  inputTokens: number;
+  cachedInputTokens: number;
+  outputTokens: number;
+}
+
+export interface UserProfileIssueSummary {
+  id: string;
+  identifier: string | null;
+  title: string;
+  status: IssueStatus;
+  priority: IssuePriority;
+  assigneeAgentId: string | null;
+  assigneeUserId: string | null;
+  updatedAt: Date;
+  completedAt: Date | null;
+}
+
+export interface UserProfileActivitySummary {
+  id: string;
+  action: string;
+  entityType: string;
+  entityId: string;
+  details: Record<string, unknown> | null;
+  createdAt: Date;
+}
+
+export interface UserProfileAgentUsage {
+  agentId: string;
+  agentName: string | null;
+  costCents: number;
+  inputTokens: number;
+  cachedInputTokens: number;
+  outputTokens: number;
+}
+
+export interface UserProfileProviderUsage {
+  provider: string;
+  biller: string;
+  model: string;
+  costCents: number;
+  inputTokens: number;
+  cachedInputTokens: number;
+  outputTokens: number;
+}
+
+export interface UserProfileResponse {
+  user: UserProfileIdentity;
+  stats: UserProfileWindowStats[];
+  daily: UserProfileDailyPoint[];
+  recentIssues: UserProfileIssueSummary[];
+  recentActivity: UserProfileActivitySummary[];
+  topAgents: UserProfileAgentUsage[];
+  topProviders: UserProfileProviderUsage[];
+}
@@ -46,6 +46,27 @@ export type ExecutionWorkspaceCloseActionKind =
  | "remove_local_directory";

 export type WorkspaceRuntimeDesiredState = "running" | "stopped";
+export type WorkspaceRuntimeServiceStateMap = Record<string, WorkspaceRuntimeDesiredState>;
+export type WorkspaceCommandKind = "service" | "job";
+
+export interface WorkspaceCommandSource {
+  type: "paperclip";
+  key: "commands" | "services" | "jobs";
+  index: number;
+}
+
+export interface WorkspaceCommandDefinition {
+  id: string;
+  name: string;
+  kind: WorkspaceCommandKind;
+  command: string | null;
+  cwd: string | null;
+  lifecycle: "shared" | "ephemeral" | null;
+  serviceIndex: number | null;
+  disabledReason: string | null;
+  rawConfig: Record<string, unknown>;
+  source: WorkspaceCommandSource;
+}

 export interface ExecutionWorkspaceStrategy {
  type: ExecutionWorkspaceStrategyType;
@@ -62,11 +83,19 @@ export interface ExecutionWorkspaceConfig {
  cleanupCommand: string | null;
  workspaceRuntime: Record<string, unknown> | null;
  desiredState: WorkspaceRuntimeDesiredState | null;
+  serviceStates?: WorkspaceRuntimeServiceStateMap | null;
 }

 export interface ProjectWorkspaceRuntimeConfig {
  workspaceRuntime: Record<string, unknown> | null;
  desiredState: WorkspaceRuntimeDesiredState | null;
+  serviceStates?: WorkspaceRuntimeServiceStateMap | null;
+}
+
+export interface WorkspaceRuntimeControlTarget {
+  workspaceCommandId?: string | null;
+  runtimeServiceId?: string | null;
+  serviceIndex?: number | null;
 }

 export interface ExecutionWorkspaceCloseAction {
@@ -132,6 +161,13 @@ export interface IssueExecutionWorkspaceSettings {
  workspaceRuntime?: Record<string, unknown> | null;
 }

+export interface ExecutionWorkspaceSummary {
+  id: string;
+  name: string;
+  mode: Exclude<ExecutionWorkspaceMode, "inherit" | "reuse_existing" | "agent_default"> | "adapter_managed" | "cloud_sandbox";
+  projectWorkspaceId: string | null;
+}
+
 export interface ExecutionWorkspace {
  id: string;
  companyId: string;
@@ -187,6 +223,7 @@ export interface WorkspaceRuntimeService {
  stoppedAt: Date | null;
  stopPolicy: Record<string, unknown> | null;
  healthStatus: "unknown" | "healthy" | "unhealthy";
+  configIndex?: number | null;
  createdAt: Date;
  updatedAt: Date;
 }
@@ -1,5 +1,7 @@
 import { z } from "zod";
 import {
+  AGENT_ADAPTER_TYPES,
+  HUMAN_COMPANY_MEMBERSHIP_ROLES,
  INVITE_JOIN_TYPES,
  JOIN_REQUEST_STATUSES,
  JOIN_REQUEST_TYPES,
@@ -9,6 +11,7 @@ import { optionalAgentAdapterTypeSchema } from "../adapter-type.js";

 export const createCompanyInviteSchema = z.object({
  allowedJoinTypes: z.enum(INVITE_JOIN_TYPES).default("both"),
+  humanRole: z.enum(HUMAN_COMPANY_MEMBERSHIP_ROLES).optional().nullable(),
  defaultsPayload: z.record(z.string(), z.unknown()).optional().nullable(),
  agentMessage: z.string().max(4000).optional().nullable(),
 });
@@ -46,6 +49,14 @@ export const listJoinRequestsQuerySchema = z.object({

 export type ListJoinRequestsQuery = z.infer<typeof listJoinRequestsQuerySchema>;

+export const listCompanyInvitesQuerySchema = z.object({
+  state: z.enum(["active", "revoked", "accepted", "expired"]).optional(),
+  limit: z.coerce.number().int().min(1).max(100).optional().default(20),
+  offset: z.coerce.number().int().min(0).optional().default(0),
+});
+
+export type ListCompanyInvitesQuery = z.infer<typeof listCompanyInvitesQuerySchema>;
+
 export const claimJoinRequestApiKeySchema = z.object({
  claimSecret: z.string().min(16).max(256),
 });
@@ -85,8 +96,104 @@ export const updateMemberPermissionsSchema = z.object({

 export type UpdateMemberPermissions = z.infer<typeof updateMemberPermissionsSchema>;

+const editableMembershipStatuses = ["pending", "active", "suspended"] as const;
+
+export const updateCompanyMemberSchema = z.object({
+  membershipRole: z.enum(HUMAN_COMPANY_MEMBERSHIP_ROLES).optional().nullable(),
+  status: z.enum(editableMembershipStatuses).optional(),
+}).refine((value) => value.membershipRole !== undefined || value.status !== undefined, {
+  message: "membershipRole or status is required",
+});
+
+export type UpdateCompanyMember = z.infer<typeof updateCompanyMemberSchema>;
+
+export const updateCompanyMemberWithPermissionsSchema = z.object({
+  membershipRole: z.enum(HUMAN_COMPANY_MEMBERSHIP_ROLES).optional().nullable(),
+  status: z.enum(editableMembershipStatuses).optional(),
+  grants: updateMemberPermissionsSchema.shape.grants.default([]),
+}).refine((value) => value.membershipRole !== undefined || value.status !== undefined, {
+  message: "membershipRole or status is required",
+});
+
+export type UpdateCompanyMemberWithPermissions = z.infer<typeof updateCompanyMemberWithPermissionsSchema>;
+
+export const archiveCompanyMemberSchema = z.object({
+  reassignment: z
+    .object({
+      assigneeAgentId: z.string().uuid().optional().nullable(),
+      assigneeUserId: z.string().uuid().optional().nullable(),
+    })
+    .optional()
+    .nullable(),
+}).superRefine((value, ctx) => {
+  if (value.reassignment?.assigneeAgentId && value.reassignment.assigneeUserId) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "Choose either an agent or user reassignment target",
+      path: ["reassignment"],
+    });
+  }
+});
+
+export type ArchiveCompanyMember = z.infer<typeof archiveCompanyMemberSchema>;
+
 export const updateUserCompanyAccessSchema = z.object({
  companyIds: z.array(z.string().uuid()).default([]),
 });

 export type UpdateUserCompanyAccess = z.infer<typeof updateUserCompanyAccessSchema>;
+
+export const searchAdminUsersQuerySchema = z.object({
+  query: z.string().trim().max(120).optional().default(""),
+});
+
+export type SearchAdminUsersQuery = z.infer<typeof searchAdminUsersQuerySchema>;
+
+const profileImageAssetPathPattern = /^\/api\/assets\/[^/?#]+\/content(?:\?[^#]*)?(?:#.*)?$/;
+
+function isValidProfileImage(value: string): boolean {
+  if (profileImageAssetPathPattern.test(value)) return true;
+
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" || url.protocol === "http:";
+  } catch {
+    return false;
+  }
+}
+
+const profileImageSchema = z
+  .string()
+  .trim()
+  .min(1)
+  .max(4000)
+  .refine(isValidProfileImage, { message: "Invalid profile image URL" });
+
+export const currentUserProfileSchema = z.object({
+  id: z.string().min(1),
+  email: z.string().email().nullable(),
+  name: z.string().min(1).max(120).nullable(),
+  image: profileImageSchema.nullable(),
+});
+
+export type CurrentUserProfile = z.infer<typeof currentUserProfileSchema>;
+
+export const authSessionSchema = z.object({
+  session: z.object({
+    id: z.string().min(1),
+    userId: z.string().min(1),
+  }),
+  user: currentUserProfileSchema,
+});
+
+export type AuthSession = z.infer<typeof authSessionSchema>;
+
+export const updateCurrentUserProfileSchema = z.object({
+  name: z.string().trim().min(1).max(120),
+  image: z
+    .union([profileImageSchema, z.literal(""), z.null()])
+    .optional()
+    .transform((value) => value === "" ? null : value),
+});
+
+export type UpdateCurrentUserProfile = z.infer<typeof updateCurrentUserProfileSchema>;
@@ -12,14 +12,12 @@ export type CreateApproval = z.infer<typeof createApprovalSchema>;

 export const resolveApprovalSchema = z.object({
  decisionNote: z.string().optional().nullable(),
-  decidedByUserId: z.string().optional().default("board"),
 });

 export type ResolveApproval = z.infer<typeof resolveApprovalSchema>;

 export const requestApprovalRevisionSchema = z.object({
  decisionNote: z.string().optional().nullable(),
-  decidedByUserId: z.string().optional().default("board"),
 });

 export type RequestApprovalRevision = z.infer<typeof requestApprovalRevisionSchema>;
@@ -14,6 +14,13 @@ export const executionWorkspaceConfigSchema = z.object({
  cleanupCommand: z.string().optional().nullable(),
  workspaceRuntime: z.record(z.unknown()).optional().nullable(),
  desiredState: z.enum(["running", "stopped"]).optional().nullable(),
+  serviceStates: z.record(z.enum(["running", "stopped"])).optional().nullable(),
+}).strict();
+
+export const workspaceRuntimeControlTargetSchema = z.object({
+  workspaceCommandId: z.string().min(1).optional().nullable(),
+  runtimeServiceId: z.string().uuid().optional().nullable(),
+  serviceIndex: z.number().int().nonnegative().optional().nullable(),
 }).strict();

 export const executionWorkspaceCloseReadinessStateSchema = z.enum([
@@ -88,10 +95,10 @@ export const workspaceRuntimeServiceSchema = z.object({
  stoppedAt: z.coerce.date().nullable(),
  stopPolicy: z.record(z.unknown()).nullable(),
  healthStatus: z.enum(["unknown", "healthy", "unhealthy"]),
+  configIndex: z.number().int().nonnegative().nullable().optional(),
  createdAt: z.coerce.date(),
  updatedAt: z.coerce.date(),
 }).strict();
-
 export const executionWorkspaceCloseReadinessSchema = z.object({
  workspaceId: z.string().uuid(),
  state: executionWorkspaceCloseReadinessStateSchema,
@@ -32,6 +32,11 @@ export {
  upsertIssueFeedbackVoteSchema,
  type UpsertIssueFeedbackVote,
 } from "./feedback.js";
+export {
+  sidebarOrderPreferenceSchema,
+  upsertSidebarOrderPreferenceSchema,
+  type UpsertSidebarOrderPreference,
+} from "./sidebar-preferences.js";
 export {
  companySkillSourceTypeSchema,
  companySkillTrustLevelSchema,
@@ -129,6 +134,7 @@ export {

 export {
  createIssueSchema,
+  createChildIssueSchema,
  createIssueLabelSchema,
  updateIssueSchema,
  issueExecutionPolicySchema,
@@ -143,6 +149,7 @@ export {
  upsertIssueDocumentSchema,
  restoreIssueDocumentRevisionSchema,
  type CreateIssue,
+  type CreateChildIssue,
  type CreateIssueLabel,
  type UpdateIssue,
  type IssueExecutionWorkspaceSettings,
@@ -321,22 +328,38 @@ export {
  createCompanyInviteSchema,
  createOpenClawInvitePromptSchema,
  acceptInviteSchema,
+  listCompanyInvitesQuerySchema,
  listJoinRequestsQuerySchema,
  claimJoinRequestApiKeySchema,
  boardCliAuthAccessLevelSchema,
  createCliAuthChallengeSchema,
  resolveCliAuthChallengeSchema,
+  currentUserProfileSchema,
+  authSessionSchema,
+  updateCurrentUserProfileSchema,
+  updateCompanyMemberSchema,
+  updateCompanyMemberWithPermissionsSchema,
+  archiveCompanyMemberSchema,
  updateMemberPermissionsSchema,
+  searchAdminUsersQuerySchema,
  updateUserCompanyAccessSchema,
  type CreateCompanyInvite,
  type CreateOpenClawInvitePrompt,
  type AcceptInvite,
+  type ListCompanyInvitesQuery,
  type ListJoinRequestsQuery,
  type ClaimJoinRequestApiKey,
  type BoardCliAuthAccessLevel,
  type CreateCliAuthChallenge,
  type ResolveCliAuthChallenge,
+  type CurrentUserProfile,
+  type AuthSession,
+  type UpdateCurrentUserProfile,
+  type UpdateCompanyMember,
+  type UpdateCompanyMemberWithPermissions,
+  type ArchiveCompanyMember,
  type UpdateMemberPermissions,
+  type SearchAdminUsersQuery,
  type UpdateUserCompanyAccess,
 } from "./access.js";

@@ -138,6 +138,18 @@ export const createIssueSchema = z.object({

 export type CreateIssue = z.infer<typeof createIssueSchema>;

+export const createChildIssueSchema = createIssueSchema
+  .omit({
+    parentId: true,
+    inheritExecutionWorkspaceFromIssueId: true,
+  })
+  .extend({
+    acceptanceCriteria: z.array(z.string().trim().min(1).max(500)).max(20).optional(),
+    blockParentUntilDone: z.boolean().optional().default(false),
+  });
+
+export type CreateChildIssue = z.infer<typeof createChildIssueSchema>;
+
 export const createIssueLabelSchema = z.object({
  name: z.string().trim().min(1).max(48),
  color: z.string().regex(/^#(?:[0-9a-fA-F]{6})$/, "Color must be a 6-digit hex value"),
@@ -146,6 +158,7 @@ export const createIssueLabelSchema = z.object({
 export type CreateIssueLabel = z.infer<typeof createIssueLabelSchema>;

 export const updateIssueSchema = createIssueSchema.partial().extend({
+  assigneeAgentId: z.string().trim().min(1).optional().nullable(),
  comment: z.string().min(1).optional(),
  reopen: z.boolean().optional(),
  interrupt: z.boolean().optional(),
@@ -31,6 +31,7 @@ export const projectExecutionWorkspacePolicySchema = z
 export const projectWorkspaceRuntimeConfigSchema = z.object({
  workspaceRuntime: z.record(z.unknown()).optional().nullable(),
  desiredState: z.enum(["running", "stopped"]).optional().nullable(),
+  serviceStates: z.record(z.enum(["running", "stopped"])).optional().nullable(),
 }).strict();

 const projectWorkspaceSourceTypeSchema = z.enum(["local_path", "git_repo", "remote_managed", "non_git_path"]);
@@ -0,0 +1,14 @@
+import { z } from "zod";
+
+const sidebarOrderedIdSchema = z.string().uuid();
+
+export const sidebarOrderPreferenceSchema = z.object({
+  orderedIds: z.array(sidebarOrderedIdSchema),
+  updatedAt: z.coerce.date().nullable(),
+});
+
+export const upsertSidebarOrderPreferenceSchema = z.object({
+  orderedIds: z.array(sidebarOrderedIdSchema),
+});
+
+export type UpsertSidebarOrderPreference = z.infer<typeof upsertSidebarOrderPreferenceSchema>;
@@ -0,0 +1,78 @@
+import { describe, expect, it } from "vitest";
+import {
+  findWorkspaceCommandDefinition,
+  listWorkspaceCommandDefinitions,
+  matchWorkspaceRuntimeServiceToCommand,
+} from "./workspace-commands.js";
+
+describe("workspace command helpers", () => {
+  it("derives service and job commands from command-first runtime config", () => {
+    const commands = listWorkspaceCommandDefinitions({
+      commands: [
+        { id: "web", name: "web", kind: "service", command: "pnpm dev" },
+        { id: "db-migrate", name: "db:migrate", kind: "job", command: "pnpm db:migrate" },
+      ],
+    });
+
+    expect(commands).toEqual([
+      expect.objectContaining({ id: "web", kind: "service", serviceIndex: 0 }),
+      expect.objectContaining({ id: "db-migrate", kind: "job", serviceIndex: null }),
+    ]);
+  });
+
+  it("falls back to legacy services and jobs arrays", () => {
+    const commands = listWorkspaceCommandDefinitions({
+      services: [{ name: "web", command: "pnpm dev" }],
+      jobs: [{ name: "lint", command: "pnpm lint" }],
+    });
+
+    expect(commands).toEqual([
+      expect.objectContaining({ id: "service:web", kind: "service", serviceIndex: 0 }),
+      expect.objectContaining({ id: "job:lint", kind: "job", serviceIndex: null }),
+    ]);
+  });
+
+  it("matches a configured service command to the current runtime service", () => {
+    const workspaceRuntime = {
+      commands: [
+        { id: "web", name: "web", kind: "service", command: "pnpm dev", cwd: "." },
+      ],
+    };
+    const command = findWorkspaceCommandDefinition(workspaceRuntime, "web");
+    expect(command).not.toBeNull();
+
+    const match = matchWorkspaceRuntimeServiceToCommand(command!, [
+      {
+        id: "runtime-web",
+        serviceName: "web",
+        command: "pnpm dev",
+        cwd: "/repo",
+        configIndex: null,
+      },
+    ]);
+
+    expect(match).toEqual(expect.objectContaining({ id: "runtime-web" }));
+  });
+
+  it("does not match a stale runtime service after the configured command changes", () => {
+    const workspaceRuntime = {
+      commands: [
+        { id: "web", name: "web", kind: "service", command: "pnpm dev:once --tailscale-auth", cwd: "." },
+      ],
+    };
+    const command = findWorkspaceCommandDefinition(workspaceRuntime, "web");
+    expect(command).not.toBeNull();
+
+    const match = matchWorkspaceRuntimeServiceToCommand(command!, [
+      {
+        id: "runtime-web",
+        serviceName: "web",
+        command: "pnpm dev",
+        cwd: "/repo",
+        configIndex: null,
+      },
+    ]);
+
+    expect(match).toBeNull();
+  });
+});
@@ -0,0 +1,208 @@
+import type { WorkspaceCommandDefinition, WorkspaceRuntimeService } from "./types/workspace-runtime.js";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readNonEmptyString(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function slugify(value: string | null | undefined) {
+  const normalized = (value ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return normalized.length > 0 ? normalized : null;
+}
+
+function deriveWorkspaceCommandId(input: {
+  kind: WorkspaceCommandDefinition["kind"];
+  explicitId: string | null;
+  name: string;
+  index: number;
+}) {
+  const explicitId = slugify(input.explicitId);
+  if (explicitId) return explicitId;
+  const nameSlug = slugify(input.name);
+  return nameSlug ? `${input.kind}:${nameSlug}` : `${input.kind}:${input.index + 1}`;
+}
+
+function buildWorkspaceCommandDefinition(input: {
+  entry: Record<string, unknown>;
+  kind: WorkspaceCommandDefinition["kind"];
+  sourceKey: WorkspaceCommandDefinition["source"]["key"];
+  sourceIndex: number;
+  serviceIndex: number | null;
+  fallbackName: string;
+}): WorkspaceCommandDefinition {
+  return {
+    id: deriveWorkspaceCommandId({
+      kind: input.kind,
+      explicitId: readNonEmptyString(input.entry.id),
+      name:
+        readNonEmptyString(input.entry.name)
+        ?? readNonEmptyString(input.entry.label)
+        ?? readNonEmptyString(input.entry.title)
+        ?? input.fallbackName,
+      index: input.sourceIndex,
+    }),
+    name:
+      readNonEmptyString(input.entry.name)
+      ?? readNonEmptyString(input.entry.label)
+      ?? readNonEmptyString(input.entry.title)
+      ?? input.fallbackName,
+    kind: input.kind,
+    command: readNonEmptyString(input.entry.command),
+    cwd: readNonEmptyString(input.entry.cwd),
+    lifecycle:
+      input.kind === "service"
+        ? input.entry.lifecycle === "ephemeral"
+          ? "ephemeral"
+          : "shared"
+        : null,
+    serviceIndex: input.serviceIndex,
+    disabledReason: readNonEmptyString(input.entry.disabledReason),
+    rawConfig: { ...input.entry },
+    source: {
+      type: "paperclip",
+      key: input.sourceKey,
+      index: input.sourceIndex,
+    },
+  };
+}
+
+function uniqueWorkspaceCommandId(
+  seen: Set<string>,
+  commandId: string,
+  sourceKey: WorkspaceCommandDefinition["source"]["key"],
+  sourceIndex: number,
+) {
+  if (!seen.has(commandId)) {
+    seen.add(commandId);
+    return commandId;
+  }
+  const fallbackId = `${commandId}-${sourceKey}-${sourceIndex + 1}`;
+  seen.add(fallbackId);
+  return fallbackId;
+}
+
+function readCommandEntries(
+  workspaceRuntime: Record<string, unknown> | null | undefined,
+  key: "commands" | "services" | "jobs",
+) {
+  const raw = workspaceRuntime?.[key];
+  return Array.isArray(raw) ? raw.filter((entry): entry is Record<string, unknown> => isRecord(entry)) : [];
+}
+
+export function listWorkspaceCommandDefinitions(
+  workspaceRuntime: Record<string, unknown> | null | undefined,
+): WorkspaceCommandDefinition[] {
+  if (!workspaceRuntime) return [];
+
+  const commandEntries = readCommandEntries(workspaceRuntime, "commands");
+  const seenIds = new Set<string>();
+  let nextServiceIndex = 0;
+
+  const finalize = (command: WorkspaceCommandDefinition) => ({
+    ...command,
+    id: uniqueWorkspaceCommandId(seenIds, command.id, command.source.key, command.source.index),
+  });
+
+  if (commandEntries.length > 0) {
+    return commandEntries.map((entry, index) =>
+      finalize(buildWorkspaceCommandDefinition({
+        entry,
+        kind: entry.kind === "job" ? "job" : "service",
+        sourceKey: "commands",
+        sourceIndex: index,
+        serviceIndex: entry.kind === "job" ? null : nextServiceIndex++,
+        fallbackName: entry.kind === "job" ? `Job ${index + 1}` : `Service ${index + 1}`,
+      })));
+  }
+
+  const serviceDefinitions = readCommandEntries(workspaceRuntime, "services").map((entry, index) =>
+    finalize(buildWorkspaceCommandDefinition({
+      entry,
+      kind: "service",
+      sourceKey: "services",
+      sourceIndex: index,
+      serviceIndex: nextServiceIndex++,
+      fallbackName: `Service ${index + 1}`,
+    })));
+  const jobDefinitions = readCommandEntries(workspaceRuntime, "jobs").map((entry, index) =>
+    finalize(buildWorkspaceCommandDefinition({
+      entry,
+      kind: "job",
+      sourceKey: "jobs",
+      sourceIndex: index,
+      serviceIndex: null,
+      fallbackName: `Job ${index + 1}`,
+    })));
+
+  return [...serviceDefinitions, ...jobDefinitions];
+}
+
+export function listWorkspaceServiceCommandDefinitions(
+  workspaceRuntime: Record<string, unknown> | null | undefined,
+) {
+  return listWorkspaceCommandDefinitions(workspaceRuntime).filter((command) => command.kind === "service");
+}
+
+export function findWorkspaceCommandDefinition(
+  workspaceRuntime: Record<string, unknown> | null | undefined,
+  workspaceCommandId: string | null | undefined,
+) {
+  const normalizedId = readNonEmptyString(workspaceCommandId);
+  if (!normalizedId) return null;
+  return listWorkspaceCommandDefinitions(workspaceRuntime).find((command) => command.id === normalizedId) ?? null;
+}
+
+export function scoreWorkspaceRuntimeServiceMatch(
+  command: Pick<WorkspaceCommandDefinition, "serviceIndex" | "name" | "command" | "cwd">,
+  runtimeService: Pick<WorkspaceRuntimeService, "configIndex" | "serviceName" | "command" | "cwd">,
+) {
+  if (command.command && runtimeService.command && runtimeService.command !== command.command) {
+    return -1;
+  }
+
+  if (command.serviceIndex !== null && runtimeService.configIndex !== null && runtimeService.configIndex !== undefined) {
+    return runtimeService.configIndex === command.serviceIndex ? 100 : -1;
+  }
+
+  let score = 0;
+  if (runtimeService.serviceName === command.name) score += 4;
+  if ((runtimeService.command ?? null) === (command.command ?? null)) score += 4;
+  if (
+    command.cwd
+    && runtimeService.cwd
+    && (runtimeService.cwd === command.cwd || runtimeService.cwd.endsWith(`/${command.cwd}`))
+  ) {
+    score += 2;
+  }
+  return score;
+}
+
+export function matchWorkspaceRuntimeServiceToCommand<
+  T extends Pick<WorkspaceRuntimeService, "configIndex" | "serviceName" | "command" | "cwd">,
+>(
+  command: Pick<WorkspaceCommandDefinition, "serviceIndex" | "name" | "command" | "cwd">,
+  runtimeServices: T[] | null | undefined,
+) {
+  let bestMatch: T | null = null;
+  let bestScore = -1;
+
+  for (const runtimeService of runtimeServices ?? []) {
+    const score = scoreWorkspaceRuntimeServiceMatch(command, runtimeService);
+    if (score > bestScore) {
+      bestMatch = runtimeService;
+      bestScore = score;
+    }
+  }
+
+  return bestScore > 0 ? bestMatch : null;
+}
@@ -0,0 +1,107 @@
+# v2026.414.0
+
+> Released: 2026-04-14
+
+## Security
+
+- **Authorization hardening (GHSA-68qg-g8mg-6pr7)** — Scoped import, approval, activity, and heartbeat API routes to enforce proper authorization checks. Previously, certain administrative endpoints were accessible without adequate permission verification. All users are strongly encouraged to upgrade. ([#3315](https://github.com/paperclipai/paperclip/pull/3315), [#3009](https://github.com/paperclipai/paperclip/pull/3009), @KhairulA)
+- **Removed hardcoded JWT secret fallback** — The `createBetterAuthInstance` function no longer falls back to a hardcoded JWT secret, closing a credential-hygiene gap. ([#3124](https://github.com/paperclipai/paperclip/pull/3124), @cleanunicorn)
+- **Redact Bearer tokens in logs** — Server log output now redacts Bearer tokens to prevent accidental credential exposure.
+- **Dependency bumps** — Updated `multer` to 2.1.1 (HIGH CVEs) and `rollup` to 4.59.0 (path-traversal CVE). ([#2909](https://github.com/paperclipai/paperclip/pull/2909), @marysomething99-prog)
+
+## Highlights
+
+- **Multi-user access and invites** — Full multi-user authentication, company roles, and invite management. Board users can create invite links, approve join requests, and manage member roles. Invite flows support auto-accept for signed-in users, paginated history, and human-readable requester identities in approval views.
+- **Human user identities everywhere** — Human users now appear with real names and avatars across activity feeds, issue tables, assignee pickers, and @-mention menus. A lightweight user directory endpoint powers consistent identity resolution across the UI.
+- **Issue chat thread** — Replaced the classic comment timeline with a full chat-style thread powered by assistant-ui. Agent run transcripts, chain-of-thought, and user messages render inline as a continuous conversation with polished avatars, action bars, and relative timestamps. ([#3079](https://github.com/paperclipai/paperclip/pull/3079))
+- **External adapter plugin system** — Third-party adapters can now be installed as npm packages or loaded from local directories. Plugins declare a config schema and an optional UI transcript parser; built-in adapters can be overridden by external ones. Includes Hermes local session management and provider/model display in run details. ([#2649](https://github.com/paperclipai/paperclip/pull/2649), [#2650](https://github.com/paperclipai/paperclip/pull/2650), [#2651](https://github.com/paperclipai/paperclip/pull/2651), [#2654](https://github.com/paperclipai/paperclip/pull/2654), [#2655](https://github.com/paperclipai/paperclip/pull/2655), [#2659](https://github.com/paperclipai/paperclip/pull/2659), @plind-dm)
+- **Execution policies** — Issues can carry a review/approval execution policy with multi-stage signoff workflows. Reviewers and approvers are selected per-stage, and Paperclip routes the issue through each stage automatically. ([#3222](https://github.com/paperclipai/paperclip/pull/3222))
+- **Blocker dependencies** — First-class issue blocker relations with automatic wake-on-dependency-resolved. Set `blockedByIssueIds` on any issue and Paperclip wakes the assignee when all blockers reach `done`. ([#2797](https://github.com/paperclipai/paperclip/pull/2797))
+- **Standalone MCP server** — New `@paperclipai/mcp-server` package exposing the Paperclip API as an MCP tool server, including approval creation. ([#2435](https://github.com/paperclipai/paperclip/pull/2435))
+
+## Improvements
+
+- **Invite UX polish** — Auto-submit for signed-in invites, inline auth flow, paginated invite history, requester identity in join approvals, and prevention of duplicate join requests and member re-invites.
+- **Board approvals** — Generic issue-linked board approvals with card styling and visibility improvements in the issue detail sidebar. ([#3220](https://github.com/paperclipai/paperclip/pull/3220))
+- **Inbox parent-child nesting** — Parent issues group their children in the inbox Mine view with a toggle button, j/k keyboard traversal across nested items, and collapsible groups. ([#2218](https://github.com/paperclipai/paperclip/pull/2218), @HenkDz)
+- **Inbox workspace grouping** — Issues can now be grouped by workspace in the inbox with collapsible mobile groups and shared column controls across inbox and issues lists. ([#3356](https://github.com/paperclipai/paperclip/pull/3356))
+- **Issue search** — Trigram-indexed full-text search across titles, identifiers, descriptions, and comments with debounced input. Comment matches now surface in search results. ([#2999](https://github.com/paperclipai/paperclip/pull/2999))
+- **Sub-issues inline** — Sub-issues moved from a separate tab to inline display on the issue detail, with parent-inherited workspace defaults and assignee propagation. ([#3355](https://github.com/paperclipai/paperclip/pull/3355))
+- **Issue-to-issue navigation** — Faster navigation between issues with scroll reset, prefetch, and detail-view optimizations. ([#3542](https://github.com/paperclipai/paperclip/pull/3542))
+- **Auto-checkout for scoped wakes** — Agent harness now automatically checks out the scoped issue on comment-driven wakes, reducing latency for agent heartbeats. ([#3538](https://github.com/paperclipai/paperclip/pull/3538))
+- **Document revision diff viewer** — Side-by-side diff viewer for issue document revisions with improved modal layout. ([#2792](https://github.com/paperclipai/paperclip/pull/2792))
+- **Keyboard shortcuts cheatsheet** — Press `?` to open a keyboard shortcut reference dialog; new `g i` (go to inbox), `g c` (comment composer), and inbox archive undo shortcuts. ([#2772](https://github.com/paperclipai/paperclip/pull/2772))
+- **Bedrock model selection** — Claude local adapter now supports AWS Bedrock authentication and model selection. ([#3033](https://github.com/paperclipai/paperclip/pull/3033), [#2793](https://github.com/paperclipai/paperclip/pull/2793), @kimnamu)
+- **Codex fast mode** — Added fast mode support for the Codex local adapter with env probe safeguards. ([#3383](https://github.com/paperclipai/paperclip/pull/3383))
+- **Backup improvements** — Gzip-compressed backups with tiered daily/weekly/monthly retention and UI controls in Instance Settings. ([#3015](https://github.com/paperclipai/paperclip/pull/3015), @aronprins)
+- **GitHub webhook signing modes** — Added `github_hmac` and `none` webhook signing modes with timing-safe HMAC comparison. ([#1961](https://github.com/paperclipai/paperclip/pull/1961), @antonio-mello-ai)
+- **Sidebar order persistence** — Sidebar project and company ordering preferences now persist per-user.
+- **Workspace runtime controls** — Start/stop controls, runtime state reconciliation, runtime service improvements, and workspace branch/folder display in the issue properties sidebar. ([#3354](https://github.com/paperclipai/paperclip/pull/3354))
+- **Attachment improvements** — Arbitrary file attachments (not just images), drag-and-drop non-image files onto markdown editor, and square-cropped image gallery grid. ([#2749](https://github.com/paperclipai/paperclip/pull/2749))
+- **Image gallery in chat** — Clicking images in chat messages now opens a full gallery viewer.
+- **Mobile UX** — Gmail-inspired mobile top bar for inbox issue views, responsive execution workspace pages, mobile mention menu placement, and mobile comment copy button feedback.
+- **Routine improvements** — Draft routine defaults, run-time overrides, routine title variables, and relaxed project/agent requirements for routines. ([#3220](https://github.com/paperclipai/paperclip/pull/3220))
+- **Project environment variables** — Projects can now define environment variables that are inherited by workspace runs.
+- **Skill auto-enable** — Mentioned skills are automatically enabled for heartbeat runs.
+- **Comment wake batching** — Multiple comment wakes are batched into a single inline payload for more efficient agent heartbeats.
+- **Server-side adapter pause/resume** — Builtin adapter types can now be paused/resumed from the server with `overridePaused`. ([#2542](https://github.com/paperclipai/paperclip/pull/2542), @plind-dm)
+- **Skill slash-command autocomplete** — Skill names now autocomplete in the editor.
+- **Worktree reseed command** — New CLI command to reseed worktrees from latest repo state. ([#3353](https://github.com/paperclipai/paperclip/pull/3353))
+
+## Fixes
+
+- **Assignee name overflow** — Fixed long assignee names overflowing in the issues list grid with proper truncation.
+- **Company alerts isolation** — Company-level alerts no longer appear in personal inbox.
+- **Invite state management** — Fixed reused invite refresh pending state, paginated invite history cache isolation, and invite flow state mapping across reloads.
+- **Issue detail stability** — Fixed visible refreshes during agent updates, comment post resets, ref update loops, split regressions, and main-pane focus on navigation. ([#3355](https://github.com/paperclipai/paperclip/pull/3355))
+- **Inbox badge count** — Badge now correctly counts only unread Mine issues. ([#2512](https://github.com/paperclipai/paperclip/pull/2512), @AllenHyang)
+- **Inbox keyboard navigation** — Fixed j/k traversal across groups and nesting column alignment. ([#2218](https://github.com/paperclipai/paperclip/pull/2218), @HenkDz)
+- **Execution workspaces** — Fixed linked worktree reuse, dev runner isolation, workspace import regressions, and workspace preflight through server toolchain.
+- **Stale execution locks** — Fixed stale execution lock lifecycle with proper `executionAgentNameKey` clearing. ([#2643](https://github.com/paperclipai/paperclip/pull/2643), @chrisschwer)
+- **Agent env bindings** — Fixed cleared agent env bindings not persisting on save. ([#3232](https://github.com/paperclipai/paperclip/pull/3232), @officialasishkumar)
+- **Capabilities field** — Fixed blank screen when clearing the Capabilities field. ([#2442](https://github.com/paperclipai/paperclip/pull/2442), @sparkeros)
+- **Skill deletion** — Company skills can now be deleted with an agent usage check. ([#2441](https://github.com/paperclipai/paperclip/pull/2441), @DanielSousa)
+- **Claude session resume** — Fixed `--append-system-prompt-file` being sent on resumed Claude sessions and preserved instructions on resume fallback. ([#2949](https://github.com/paperclipai/paperclip/pull/2949), [#2936](https://github.com/paperclipai/paperclip/pull/2936), [#2937](https://github.com/paperclipai/paperclip/pull/2937), @Lempkey)
+- **Agent auth JWT** — Fixed agent auth to fall back to `BETTER_AUTH_SECRET` when `PAPERCLIP_AGENT_JWT_SECRET` is absent. ([#2866](https://github.com/paperclipai/paperclip/pull/2866), @ergonaworks)
+- **Typing lag** — Fixed typing lag in long comment threads. ([#3163](https://github.com/paperclipai/paperclip/pull/3163))
+- **Shimmer animation** — Fixed shimmer text using invalid `hsl()` wrapper on `oklch` colors, loop jitter, and added pause between repeats.
+- **Mention selection** — Restored touch mention selection and fixed spaced mention queries.
+- **Inbox archive** — Fixed archive flashing back after fade-out.
+- **Goal description** — Made goal description area scrollable in create dialog. ([#2148](https://github.com/paperclipai/paperclip/pull/2148), @shoaib050326)
+- **Worktree provisioning** — Fixed symlink relinking, fallback seeding, dependency hydration, and validated linked worktrees before reuse. ([#3354](https://github.com/paperclipai/paperclip/pull/3354))
+- **Node keepAliveTimeout** — Increased timeout behind reverse proxies to prevent 502 errors.
+- **Codex tool-use transcripts** — Fixed Codex tool-use transcript completion parsing.
+- **Codex resume error** — Recognize missing-rollout Codex resume error as stale session.
+- **Pi quota exhaustion** — Treat Pi quota exhaustion as a failed run. ([#2305](https://github.com/paperclipai/paperclip/pull/2305))
+- **Issue identifier collisions** — Prevented identifier collisions during concurrent issue creation.
+- **OpenClaw CEO paths** — Fixed `$AGENT_HOME` references in CEO onboarding instructions to use relative paths. ([#3299](https://github.com/paperclipai/paperclip/pull/3299), @aronprins)
+- **Windows adapter** — Uses `cmd.exe` for `.cmd`/`.bat` wrappers on Windows. ([#2662](https://github.com/paperclipai/paperclip/pull/2662), @wbelt)
+- **Markdown autoformat** — Fixed autoformat of pasted markdown in inline editor. ([#2733](https://github.com/paperclipai/paperclip/pull/2733), @davison)
+- **Paused agent dimming** — Correctly dim paused agents in list and org chart views; skip dimming on Paused filter tab. ([#2397](https://github.com/paperclipai/paperclip/pull/2397), @HearthCore)
+- **Import role fallback** — Import now reads agent role from frontmatter before defaulting to "agent". ([#2594](https://github.com/paperclipai/paperclip/pull/2594), @plind-dm)
+- **Backup cleanup** — Clean up orphaned `.sql` files on compression failure and fix stale startup log.
+
+## Upgrade Guide
+
+Nine new database migrations (`0049`–`0056`) will run automatically on startup. These add:
+
+- Issue blocker relations table (`0049`)
+- Project environment variables (`0050`)
+- Trigram search indexes on issues and comments (`0051` — requires `pg_trgm` extension)
+- Execution policy decision tracking (`0052`)
+- Non-issue inbox dismissals (`0053`)
+- Relaxed routine constraints (`0054`)
+- Heartbeat run process group tracking (`0055`)
+- User sidebar preferences (`0056`)
+
+All migrations are additive — no existing data is modified or removed.
+
+**`pg_trgm` extension**: Migration `0051` creates the `pg_trgm` PostgreSQL extension for full-text search. If your database user does not have `CREATE EXTENSION` privileges, ask your DBA to run `CREATE EXTENSION IF NOT EXISTS pg_trgm;` before upgrading.
+
+If you use external adapter plugins, note that built-in adapters can now be overridden by external ones. The `overriddenBuiltin` flag in the adapter API indicates when this is happening.
+
+## Contributors
+
+Thank you to everyone who contributed to this release!
+
+@AllenHyang, @antonio-mello-ai, @aronprins, @chrisschwer, @cleanunicorn, @cryppadotta, @DanielSousa, @davison, @ergonaworks, @HearthCore, @HenkDz, @KhairulA, @kimnamu, @Lempkey, @marysomething99-prog, @mvanhorn, @officialasishkumar, @plind-dm, @shoaib050326, @sparkeros, @wbelt
@@ -0,0 +1,27 @@
+# v2026.415.0
+
+> Released: 2026-04-15
+
+## Highlights
+
+- **Faster issues page first paint** — The issues list now renders the initial view significantly faster by deferring non-critical work and optimizing workspace lookups.
+- **Issue detail performance** — Reduced unnecessary rerenders on the issue detail page and kept queued issue chat mounted to avoid layout thrash during agent runs.
+- **Inbox search expansion** — Added an "Other results" section to inbox search, surfacing matches beyond the current filter scope.
+
+## Improvements
+
+- **Properties pane polish** — Workspace link, copy-on-click for identifiers, and an inline parent navigation arrow in the issue properties sidebar.
+- **Routine UX** — Routine name now appears above the "Run routine" title in the run dialog; routine execution issues are shown in issue lists by default.
+- **Filter label clarity** — Renamed the routine-run filter to "Hide routine runs" so the default state shows no active filter badge.
+- **Stranded issue diagnostics** — Stranded issue comments now include the latest run failure message for faster triage.
+- **Issues search responsiveness** — Debounce and rendering improvements make the issues page search feel snappier.
+- **Live run refresh** — Visible issue runs now refresh automatically on status updates without a manual reload.
+- **Heartbeat payload hygiene** — Raw `result_json` writes are preserved exactly as received; payloads are bounded to prevent oversized records.
+- **Heartbeat log scoping** — Narrowed heartbeat log endpoint lookups to reduce query overhead.
+- **Vite dev watch** — UI test files are now excluded from the Vite dev watcher, reducing unnecessary rebuilds during development.
+
+## Fixes
+
+- **Self-comment code block scrolling** — Fixed horizontal scrolling for code blocks inside an agent's own comment thread.
+- **Markdown long-string wrapping** — Long unbroken strings in markdown comments now wrap correctly instead of overflowing the container.
+- **Dev asset serving order** — Fixed dev mode to serve public assets before the HTML shell, preventing 404s on static files during local development.
@@ -0,0 +1,108 @@
+# v2026.416.0
+
+> Released: 2026-04-16
+
+## Highlights
+
+- **Issue chat thread** — Replaced the classic comment timeline with a full chat-style thread powered by assistant-ui. Agent run transcripts, chain-of-thought, and user messages now render inline as a continuous conversation with polished avatars, action bars, and relative timestamps. ([#3079](https://github.com/paperclipai/paperclip/pull/3079))
+- **Execution policies** — Issues can now carry a review/approval execution policy with multi-stage signoff workflows. Reviewers and approvers are selected per-stage, and Paperclip routes the issue through each stage automatically. ([#3222](https://github.com/paperclipai/paperclip/pull/3222))
+- **Blocker dependencies** — First-class issue blocker relations with automatic wake-on-dependency-resolved. Set `blockedByIssueIds` on any issue and Paperclip wakes the assignee when all blockers reach `done`. ([#2797](https://github.com/paperclipai/paperclip/pull/2797))
+- **Issue-to-issue navigation** — Faster navigation between issues with scroll reset, prefetch, and detail-view optimizations. ([#3542](https://github.com/cryppadotta/paperclip/pull/3542))
+- **Auto-checkout for scoped wakes** — The agent harness now automatically checks out the scoped issue on comment-driven wakes, reducing latency for agent heartbeats. ([#3538](https://github.com/cryppadotta/paperclip/pull/3538))
+- **Inbox parent-child nesting** — Parent issues group their children in the inbox Mine view with a toggle button, `j`/`k` keyboard traversal across nested items, and collapsible groups. ([#2218](https://github.com/paperclipai/paperclip/pull/2218), @HenkDz)
+
+## Improvements
+
+- **BETA Standalone MCP server** — New `@paperclipai/mcp-server` package exposing the Paperclip API as an MCP tool server, including approval creation. ([#2435](https://github.com/paperclipai/paperclip/pull/2435))
+- **Board approvals** — Generic issue-linked board approvals with card styling and visibility improvements in the issue detail sidebar. ([#3220](https://github.com/paperclipai/paperclip/pull/3220))
+- **Inbox workspace grouping** — Issues can now be grouped by workspace in the inbox with collapsible mobile groups and shared column controls across inbox and issues lists. ([#3356](https://github.com/paperclipai/paperclip/pull/3356))
+- **Improvements to plugin system** — Third-party adapters can now be installed as npm packages or loaded from local directories. Plugins declare a config schema and an optional UI transcript parser; built-in adapters can be overridden by external ones. Includes Hermes local session management and provider/model display in run details. ([#2649](https://github.com/paperclipai/paperclip/pull/2649), [#2650](https://github.com/paperclipai/paperclip/pull/2650), [#2651](https://github.com/paperclipai/paperclip/pull/2651), [#2654](https://github.com/paperclipai/paperclip/pull/2654), [#2655](https://github.com/paperclipai/paperclip/pull/2655), [#2659](https://github.com/paperclipai/paperclip/pull/2659), @plind-dm)
+- **Issue search** — Trigram-indexed full-text search across titles, identifiers, descriptions, and comments with debounced input. Comment matches now surface in search results. ([#2999](https://github.com/paperclipai/paperclip/pull/2999))
+- **Sub-issues inline** — Sub-issues moved from a separate tab to inline display on the issue detail, with parent-inherited workspace defaults and assignee propagation. ([#3355](https://github.com/paperclipai/paperclip/pull/3355))
+- **Document revision diff viewer** — Side-by-side diff viewer for issue document revisions with improved modal layout. ([#2792](https://github.com/paperclipai/paperclip/pull/2792))
+- **Keyboard shortcut cheatsheet** — Press `?` to open a keyboard shortcut reference dialog; new `g i` (go to inbox), `g c` (comment composer), and inbox archive undo shortcuts. ([#2772](https://github.com/paperclipai/paperclip/pull/2772))
+- **Bedrock model selection** — Claude local adapter now supports AWS Bedrock authentication and model selection. ([#3033](https://github.com/paperclipai/paperclip/pull/3033), @kimnamu)
+- **Codex fast mode** — Added fast mode support for the Codex local adapter. ([#3383](https://github.com/paperclipai/paperclip/pull/3383))
+- **Backup improvements** — Gzip-compressed backups with tiered daily/weekly/monthly retention and UI controls in Instance Settings. ([#3015](https://github.com/paperclipai/paperclip/pull/3015), @aronprins)
+- **GitHub webhook signing modes** — Added `github_hmac` and `none` webhook signing modes with timing-safe HMAC comparison. ([#1961](https://github.com/paperclipai/paperclip/pull/1961), @antonio-mello-ai)
+- **Project environment variables** — Projects can now define environment variables that are inherited by workspace runs.
+- **Routine improvements** — Draft routine defaults, run-time overrides, routine title variables, and relaxed project/agent requirements for routines. ([#3220](https://github.com/paperclipai/paperclip/pull/3220))
+- **Workspace runtime controls** — Start/stop controls, runtime state reconciliation, runtime service JSON textarea improvements, and workspace branch/folder display in the issue properties sidebar. ([#3354](https://github.com/paperclipai/paperclip/pull/3354))
+- **Attachment improvements** — Arbitrary file attachments (not just images), drag-and-drop non-image files onto markdown editor, and square-cropped image gallery grid. ([#2749](https://github.com/paperclipai/paperclip/pull/2749))
+- **Image gallery in chat** — Clicking images in chat messages now opens a full gallery viewer.
+- **Mobile UX** — Gmail-inspired mobile top bar for inbox issue views, responsive execution workspace pages, mobile mention menu placement, and mobile comment copy button feedback.
+- **Sidebar order persistence** — Sidebar project and company ordering preferences now persist per-user.
+- **Skill auto-enable** — Mentioned skills are automatically enabled for heartbeat runs.
+- **Comment wake batching** — Multiple comment wakes are batched into a single inline payload for more efficient agent heartbeats.
+- **Server-side adapter pause/resume** — Builtin adapter types can now be paused/resumed from the server with `overridePaused`. ([#2542](https://github.com/paperclipai/paperclip/pull/2542), @plind-dm)
+- **Skill slash-command autocomplete** — Skill names now autocomplete in the editor.
+- **Worktree reseed command** — New CLI command to reseed worktrees from latest repo state. ([#3353](https://github.com/paperclipai/paperclip/pull/3353))
+
+## Fixes
+
+- **Issue detail stability** — Fixed visible refreshes during agent updates, comment post resets, ref update loops, split regressions, main-pane focus on navigation, and other detail-view rerender issues. ([#3355](https://github.com/paperclipai/paperclip/pull/3355))
+- **Inbox badge count** — Badge now correctly counts only unread Mine issues. ([#2512](https://github.com/paperclipai/paperclip/pull/2512), @AllenHyang)
+- **Inbox keyboard navigation** — Fixed `j`/`k` traversal across groups and nesting column alignment. ([#2218](https://github.com/paperclipai/paperclip/pull/2218), @HenkDz)
+- **Vite HTML transforms** — Fixed repeated Vite HTML transforms in dev mode.
+- **Auth session lookup** — Skipped unnecessary auth session lookups on non-API requests.
+- **Stale execution locks** — Fixed stale execution lock lifecycle with proper `executionAgentNameKey` clearing. ([#2643](https://github.com/paperclipai/paperclip/pull/2643), @chrisschwer)
+- **Agent env bindings** — Fixed cleared agent env bindings not persisting on save. ([#3232](https://github.com/paperclipai/paperclip/pull/3232), @officialasishkumar)
+- **Capabilities field** — Fixed blank screen when clearing the Capabilities field. ([#2442](https://github.com/paperclipai/paperclip/pull/2442), @sparkeros)
+- **Skill deletion** — Company skills can now be deleted with an agent usage check. ([#2441](https://github.com/paperclipai/paperclip/pull/2441), @DanielSousa)
+- **Claude session resume** — Fixed `--append-system-prompt-file` being sent on resumed Claude sessions, preserved instructions on resume fallback, and tightened fresh-session-only instruction file handling. ([#2949](https://github.com/paperclipai/paperclip/pull/2949), [#2936](https://github.com/paperclipai/paperclip/pull/2936), [#2937](https://github.com/paperclipai/paperclip/pull/2937), @Lempkey)
+- **Typing lag** — Fixed typing lag in long comment threads. ([#3163](https://github.com/paperclipai/paperclip/pull/3163))
+- **Comment editor sync** — Hardened issue comment editor synchronization.
+- **Document revisions freshness** — The latest issue document revision now stays current in the UI. ([#3342](https://github.com/cryppadotta/paperclip/pull/3342))
+- **Infinite render loop** — Fixed infinite render loop in the inbox mobile toolbar.
+- **Shimmer animation** — Fixed shimmer text using an invalid `hsl()` wrapper on `oklch` colors, reduced loop jitter, and added a pause between repeats.
+- **Mention selection** — Restored touch mention selection and fixed spaced mention queries.
+- **Inbox archive** — Fixed archive flashing back after fade-out.
+- **Goal description** — Made the goal description area scrollable in the create dialog. ([#2148](https://github.com/paperclipai/paperclip/pull/2148), @shoaib050326)
+- **Worktree provisioning** — Fixed symlink relinking, fallback seeding, dependency hydration, and validated linked worktrees before reuse. ([#3354](https://github.com/paperclipai/paperclip/pull/3354))
+- **Node keepAliveTimeout** — Increased timeout behind reverse proxies to prevent 502 errors.
+- **Noisy request logging** — Reduced noisy server request logging.
+- **Codex tool-use transcripts** — Fixed Codex tool-use transcript completion parsing.
+- **Codex resume error** — Recognize missing-rollout Codex resume error as a stale session.
+- **Pi quota exhaustion** — Treat Pi quota exhaustion as a failed run. ([#2305](https://github.com/paperclipai/paperclip/pull/2305))
+- **Issue identifier collisions** — Prevented identifier collisions during concurrent issue creation.
+- **OpenClaw CEO paths** — Fixed `$AGENT_HOME` references in CEO onboarding instructions to use relative paths. ([#3299](https://github.com/paperclipai/paperclip/pull/3299), @aronprins)
+- **Windows adapter wrappers** — Use `cmd.exe` for `.cmd` and `.bat` wrappers on Windows. ([#2662](https://github.com/paperclipai/paperclip/pull/2662), @wbelt)
+- **Markdown autoformat** — Fixed autoformat of pasted markdown in the inline editor. ([#2733](https://github.com/paperclipai/paperclip/pull/2733), @davison)
+- **Paused agent dimming** — Correctly dim paused agents in list and org chart views while skipping dimming on the Paused filter tab. ([#2397](https://github.com/paperclipai/paperclip/pull/2397), @HearthCore)
+- **Import role fallback** — Import now reads agent role from frontmatter before defaulting to `agent`. ([#2594](https://github.com/paperclipai/paperclip/pull/2594), @plind-dm)
+- **Backup cleanup** — Clean up orphaned `.sql` files on compression failure and fix stale startup logs.
+- **Chat layout alignment** — Fixed avatar positioning, activity line alignment, comment alignment, and feedback panel closing.
+
+## Security
+
+- **Authorization hardening (GHSA-68qg-g8mg-6pr7)** — Scoped import, approval, activity, and heartbeat API routes to enforce proper authorization checks. All deployments should upgrade. ([#3315](https://github.com/cryppadotta/paperclip/pull/3315))
+- **JWT secret handling** — Removed the hardcoded JWT secret fallback and fixed agent auth to fall back to `BETTER_AUTH_SECRET` when `PAPERCLIP_AGENT_JWT_SECRET` is absent. ([#3124](https://github.com/paperclipai/paperclip/pull/3124), [#2866](https://github.com/paperclipai/paperclip/pull/2866), @cleanunicorn, @ergonaworks)
+- **Redacted Bearer tokens in logs** — Server log output now redacts Bearer tokens to prevent accidental credential exposure. ([#2659](https://github.com/cryppadotta/paperclip/pull/2659))
+- **Dependency security bumps** — Updated `multer` to 2.1.1 (HIGH CVEs) and `rollup` to 4.59.0 (path-traversal CVE). ([#2819](https://github.com/cryppadotta/paperclip/pull/2819), [#2909](https://github.com/paperclipai/paperclip/pull/2909), @marysomething99-prog)
+
+## Upgrade Guide
+
+Eight new database migrations (`0049`–`0056`) will run automatically on startup. These add:
+
+- Issue blocker relations table (`0049`)
+- Project environment variables (`0050`)
+- Trigram search indexes on issues and comments (`0051` — requires `pg_trgm` extension)
+- Execution policy decision tracking (`0052`)
+- Non-issue inbox dismissals (`0053`)
+- Relaxed routine constraints (`0054`)
+- Heartbeat run process group tracking (`0055`)
+- User sidebar preferences (`0056`)
+
+All migrations are additive — no existing data is modified or removed.
+
+**`pg_trgm` extension**: Migration `0051` creates the `pg_trgm` PostgreSQL extension for full-text search. If your database user does not have `CREATE EXTENSION` privileges, ask your DBA to run `CREATE EXTENSION IF NOT EXISTS pg_trgm;` before upgrading.
+
+If you use external adapter plugins, note that built-in adapters can now be overridden by external ones. The `overriddenBuiltin` flag in the adapter API indicates when this is happening.
+
+This release also includes the fix for [GHSA-68qg-g8mg-6pr7](https://github.com/cryppadotta/paperclip/security/advisories/GHSA-68qg-g8mg-6pr7). Upgrade all deployments as soon as practical.
+
+## Contributors
+
+Thank you to everyone who contributed to this release!
+
+@AllenHyang, @antonio-mello-ai, @aronprins, @chrisschwer, @cleanunicorn, @cryppadotta, @DanielSousa, @davison, @ergonaworks, @HearthCore, @HenkDz, @KhairulA, @kimnamu, @Lempkey, @marysomething99-prog, @mvanhorn, @officialasishkumar, @plind-dm, @shoaib050326, @sparkeros, @wbelt
@@ -14,6 +14,8 @@ const ignoredTestConfigBasenames = new Set([
  "vitest.config.ts",
 ]);

+const nodeDiagnosticReportPattern = /^report\.\d{8}\.\d{6}\.\d+\.\d+\.\d+\.json$/i;
+
 export function shouldTrackDevServerPath(relativePath) {
  const normalizedPath = String(relativePath).replaceAll("\\", "/").replace(/^\.\/+/, "");
  if (normalizedPath.length === 0) return false;
@@ -21,6 +23,9 @@ export function shouldTrackDevServerPath(relativePath) {
  const segments = normalizedPath.split("/");
  const basename = segments.at(-1) ?? normalizedPath;

+  if (nodeDiagnosticReportPattern.test(basename)) {
+    return false;
+  }
  if (segments.includes(".paperclip")) {
    return false;
  }
@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { createInterface } from "node:readline/promises";
@@ -16,6 +17,8 @@ const gracefulShutdownTimeoutMs = 10_000;
 const changedPathSampleLimit = 5;
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const devServerStatusFilePath = path.join(repoRoot, ".paperclip", "dev-server-status.json");
+const devServerStatusToken = mode === "dev" ? randomUUID() : null;
+const devServerStatusTokenHeader = "x-paperclip-dev-server-status-token";

 const watchedDirectories = [
  "cli",
@@ -81,9 +84,11 @@ const env = {

 if (mode === "dev") {
  env.PAPERCLIP_DEV_SERVER_STATUS_FILE = devServerStatusFilePath;
+  env.PAPERCLIP_DEV_SERVER_STATUS_TOKEN = devServerStatusToken ?? "";
 }

 if (mode === "watch") {
+  delete env.PAPERCLIP_DEV_SERVER_STATUS_TOKEN;
  env.PAPERCLIP_MIGRATION_PROMPT ??= "never";
  env.PAPERCLIP_MIGRATION_AUTO_APPLY ??= "true";
 }
@@ -426,7 +431,9 @@ async function scanForBackendChanges() {

 async function getDevHealthPayload() {
  const serverPort = env.PORT ?? process.env.PORT ?? "3100";
-  const response = await fetch(`http://127.0.0.1:${serverPort}/api/health`);
+  const response = await fetch(`http://127.0.0.1:${serverPort}/api/health`, {
+    headers: devServerStatusToken ? { [devServerStatusTokenHeader]: devServerStatusToken } : undefined,
+  });
  if (!response.ok) {
    throw new Error(`Health request failed (${response.status})`);
  }
@@ -1,10 +1,11 @@
 #!/usr/bin/env -S node --import tsx
 import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { createInterface } from "node:readline/promises";
 import { stdin, stdout } from "node:process";
-import { createCapturedOutputBuffer, parseJsonResponseWithLimit } from "./dev-runner-output.mjs";
+import { createCapturedOutputBuffer, parseJsonResponseWithLimit } from "./dev-runner-output.ts";
 import { shouldTrackDevServerPath } from "./dev-runner-paths.mjs";
 import { createDevServiceIdentity, repoRoot } from "./dev-service-profile.ts";
 import { bootstrapDevRunnerWorktreeEnv } from "../server/src/dev-runner-worktree.ts";
@@ -35,6 +36,8 @@ const autoRestartPollIntervalMs = 2500;
 const gracefulShutdownTimeoutMs = 10_000;
 const changedPathSampleLimit = 5;
 const devServerStatusFilePath = path.join(repoRoot, ".paperclip", "dev-server-status.json");
+const devServerStatusToken = mode === "dev" ? randomUUID() : null;
+const devServerStatusTokenHeader = "x-paperclip-dev-server-status-token";

 const watchedDirectories = [
  "cli",
@@ -133,10 +136,12 @@ const env: NodeJS.ProcessEnv = {

 if (mode === "dev") {
  env.PAPERCLIP_DEV_SERVER_STATUS_FILE = devServerStatusFilePath;
+  env.PAPERCLIP_DEV_SERVER_STATUS_TOKEN = devServerStatusToken ?? "";
  env.PAPERCLIP_MIGRATION_AUTO_APPLY ??= "true";
 }

 if (mode === "watch") {
+  delete env.PAPERCLIP_DEV_SERVER_STATUS_TOKEN;
  env.PAPERCLIP_MIGRATION_PROMPT ??= "never";
  env.PAPERCLIP_MIGRATION_AUTO_APPLY ??= "true";
 }
@@ -553,11 +558,13 @@ async function scanForBackendChanges() {
 }

 async function getDevHealthPayload() {
-  const response = await fetch(`http://127.0.0.1:${serverPort}/api/health`);
+  const response = await fetch(`http://127.0.0.1:${serverPort}/api/health`, {
+    headers: devServerStatusToken ? { [devServerStatusTokenHeader]: devServerStatusToken } : undefined,
+  });
  if (!response.ok) {
    throw new Error(`Health request failed (${response.status})`);
  }
-  return await parseJsonResponseWithLimit<{ devServer?: { enabled?: boolean; autoRestartEnabled?: boolean; activeRunCount?: number } }>(response);
+  return await parseJsonResponseWithLimit(response);
 }

 async function waitForChildExit() {
@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$REPO_ROOT"
+
+WEBHOOK_URL="${DISCORD_WEBHOOK_URL:-}"
+DATE="${1:-$(date +%Y-%m-%d)}"
+REPO_URL="https://github.com/paperclipai/paperclip"
+
+if [[ -z "$WEBHOOK_URL" ]]; then
+  echo "Error: DISCORD_WEBHOOK_URL env var is required" >&2
+  echo "Usage: DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/... $0 [date]" >&2
+  echo "  date defaults to today (YYYY-MM-DD format)" >&2
+  exit 1
+fi
+
+NEXT_DATE=$(date -j -v+1d -f "%Y-%m-%d" "$DATE" "+%Y-%m-%d" 2>/dev/null \
+  || date -d "$DATE + 1 day" "+%Y-%m-%d" 2>/dev/null)
+
+COMMITS=$(git log --since="${DATE}T00:00:00" --until="${NEXT_DATE}T00:00:00" master \
+  --format="%h|%s|%an" 2>/dev/null || true)
+
+json_escape() {
+  python3 -c 'import json, sys; print(json.dumps(sys.stdin.read().rstrip("\n"))[1:-1])'
+}
+
+if [[ -z "$COMMITS" ]]; then
+  PAYLOAD=$(cat <<ENDJSON
+{
+  "embeds": [{
+    "title": "📋 Daily Merge Digest — ${DATE}",
+    "description": "No commits were merged into \`master\` today.",
+    "color": 9807270
+  }]
+}
+ENDJSON
+)
+else
+  COMMIT_COUNT=$(echo "$COMMITS" | wc -l | tr -d ' ')
+
+  LINES=""
+  while IFS='|' read -r hash subject author; do
+    escaped_subject=$(printf '%s' "$subject" | json_escape)
+    escaped_author=$(printf '%s' "$author" | json_escape)
+    LINES="${LINES}• [\`${hash}\`](${REPO_URL}/commit/${hash}) ${escaped_subject} — *${escaped_author}*\\n"
+  done <<< "$COMMITS"
+
+  PAYLOAD=$(cat <<ENDJSON
+{
+  "embeds": [{
+    "title": "📋 Daily Merge Digest — ${DATE}",
+    "description": "**${COMMIT_COUNT} commit(s)** merged into \`master\` today:\\n\\n${LINES}",
+    "color": 3066993,
+    "footer": {
+      "text": "paperclipai/paperclip • master"
+    }
+  }]
+}
+ENDJSON
+)
+fi
+
+if [[ "${DRY_RUN:-}" == "1" ]]; then
+  echo "$PAYLOAD" | python3 -m json.tool 2>/dev/null || echo "$PAYLOAD"
+  exit 0
+fi
+
+RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" \
+  -H "Content-Type: application/json" \
+  -d "$PAYLOAD" \
+  "$WEBHOOK_URL")
+
+if [[ "$RESPONSE" == "204" || "$RESPONSE" == "200" ]]; then
+  echo "Discord digest posted for ${DATE} (${COMMIT_COUNT:-0} commits)"
+else
+  echo "Error: Discord webhook returned HTTP ${RESPONSE}" >&2
+  exit 1
+fi
@@ -1,6 +1,6 @@
 #!/usr/bin/env -S node --import tsx
 import fs from "node:fs/promises";
-import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, realpathSync } from "node:fs";
 import path from "node:path";
 import { repoRoot } from "./dev-service-profile.ts";

@@ -43,20 +43,6 @@ function discoverWorkspacePackagePaths(rootDir: string): Map<string, string> {
  return packagePaths;
 }

-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(
@@ -67,6 +53,11 @@ const workspaceDirs = Array.from(
 ).sort();

 function findWorkspaceLinkMismatches(workspaceDir: string): WorkspaceLinkMismatch[] {
+  const nodeModulesDir = path.join(repoRoot, workspaceDir, "node_modules");
+  if (!existsSync(nodeModulesDir)) {
+    return [];
+  }
+
  const packageJson = readJsonFile(path.join(repoRoot, workspaceDir, "package.json"));
  const dependencies = {
    ...(packageJson.dependencies as Record<string, unknown> | undefined),
@@ -436,9 +436,6 @@ async function searchWindow(

  for (let page = 2; page <= pageCount; page += 1) {
    const response = await searchPage(client, options, start, end, page, 100);
-    if (response.incomplete_results) {
-      throw new Error(`GitHub returned incomplete search results for window ${windowKey} on page ${page}`);
-    }
    ingestSearchItems(cache, response.items, shas);
  }

@@ -512,7 +509,7 @@ function sortFilteredShas(cache: CacheFile, shas: string[]): string[] {
 }

 function formatQueryDate(value: Date): string {
-  return new Date(Math.floor(value.getTime() / 1000) * 1000).toISOString().replace(".000Z", "Z");
+  return value.toISOString().replace(".000Z", "Z");
 }

 function ingestSearchItems(cache: CacheFile, items: SearchCommitItem[], shas: Set<string>) {
@@ -850,14 +847,6 @@ class GitHubClient {
        return (await response.json()) as T;
      }

-      const retryAfter = response.headers.get("retry-after");
-      if ((response.status === 403 || response.status === 429) && retryAfter) {
-        const waitMs = Math.max(Number.parseInt(retryAfter, 10) * 1000, 1_000);
-        console.error(`GitHub secondary rate limit hit for ${pathname}; waiting ${Math.ceil(waitMs / 1000)}s...`);
-        await sleep(waitMs);
-        continue;
-      }
-
      const remaining = response.headers.get("x-ratelimit-remaining");
      const resetAt = response.headers.get("x-ratelimit-reset");
      if ((response.status === 403 || response.status === 429) && remaining === "0" && resetAt) {
@@ -31,41 +31,55 @@ source_env_path="$(dirname "$source_config_path")/.env"

 mkdir -p "$paperclip_dir"

-run_paperclipai_command() {
-  local command_args=("$@")
+run_isolated_worktree_init() {
+  local base_cli_runner="$base_cwd/cli/node_modules/tsx/dist/cli.mjs"
+  local base_cli_entry="$base_cwd/cli/src/index.ts"
+
+  if [[ -f "$base_cli_runner" && -f "$base_cli_entry" ]]; then
+    (
+      cd "$worktree_cwd"
+      node "$base_cli_runner" "$base_cli_entry" worktree init --force --seed-mode minimal --name "$worktree_name" --from-config "$source_config_path"
+    )
+    return 0
+  fi
+
+  if command -v pnpm >/dev/null 2>&1 && pnpm paperclipai --help >/dev/null 2>&1; then
+    (
+      cd "$worktree_cwd"
+      pnpm paperclipai worktree init --force --seed-mode minimal --name "$worktree_name" --from-config "$source_config_path"
+    )
+    return 0
+  fi
+
+  if command -v paperclipai >/dev/null 2>&1; then
+    (
+      cd "$worktree_cwd"
+      paperclipai worktree init --force --seed-mode minimal --name "$worktree_name" --from-config "$source_config_path"
+    )
+    return 0
+  fi
+
+  return 127
+}
+
+paperclipai_command_available() {
  if command -v pnpm >/dev/null 2>&1 && pnpm paperclipai --help >/dev/null 2>&1; then
-    pnpm paperclipai "${command_args[@]}"
    return 0
  fi

  local base_cli_tsx_path="$base_cwd/cli/node_modules/tsx/dist/cli.mjs"
  local base_cli_entry_path="$base_cwd/cli/src/index.ts"
  if command -v node >/dev/null 2>&1 && [[ -f "$base_cli_tsx_path" ]] && [[ -f "$base_cli_entry_path" ]]; then
-    node "$base_cli_tsx_path" "$base_cli_entry_path" "${command_args[@]}"
    return 0
  fi

  if command -v paperclipai >/dev/null 2>&1; then
-    paperclipai "${command_args[@]}"
    return 0
  fi

  return 1
 }

-run_isolated_worktree_init() {
-  run_paperclipai_command \
-    worktree \
-    init \
-    --force \
-    --seed-mode \
-    minimal \
-    --name \
-    "$worktree_name" \
-    --from-config \
-    "$source_config_path"
-}
-
 write_fallback_worktree_config() {
  WORKTREE_NAME="$worktree_name" \
  BASE_CWD="$base_cwd" \
@@ -318,9 +332,15 @@ main().catch((error) => {
 EOF
 }

-if ! run_isolated_worktree_init; then
-  echo "paperclipai CLI not available in this workspace; writing isolated fallback config without DB seeding." >&2
-  write_fallback_worktree_config
+if [[ -e "$worktree_config_path" && -e "$worktree_env_path" ]]; then
+  echo "Reusing existing isolated Paperclip worktree config at $worktree_config_path" >&2
+else
+  if paperclipai_command_available; then
+    run_isolated_worktree_init
+  else
+    echo "paperclipai CLI not available in this workspace; writing isolated fallback config without DB seeding." >&2
+    write_fallback_worktree_config
+  fi
 fi

 list_base_node_modules_paths() {
@@ -384,14 +404,49 @@ if [[ -f "$worktree_cwd/package.json" && -f "$worktree_cwd/pnpm-lock.yaml" ]]; t
      done
    }

-    (
-      cd "$worktree_cwd"
-      pnpm install --frozen-lockfile
-    ) || {
-      restore_moved_symlinks
-      exit 1
+    run_pnpm_install() {
+      local stdout_path stderr_path
+      stdout_path="$(mktemp)"
+      stderr_path="$(mktemp)"
+
+      if (
+        cd "$worktree_cwd"
+        pnpm install "$@"
+      ) >"$stdout_path" 2>"$stderr_path"; then
+        cat "$stdout_path"
+        cat "$stderr_path" >&2
+        rm -f "$stdout_path" "$stderr_path"
+        return 0
+      fi
+
+      local exit_code=$?
+      cat "$stdout_path"
+      cat "$stderr_path" >&2
+      if grep -q "ERR_PNPM_OUTDATED_LOCKFILE" "$stdout_path" "$stderr_path"; then
+        rm -f "$stdout_path" "$stderr_path"
+        return 90
+      fi
+
+      rm -f "$stdout_path" "$stderr_path"
+      return "$exit_code"
    }

+    if run_pnpm_install --frozen-lockfile; then
+      :
+    else
+      install_exit_code=$?
+      if [[ "$install_exit_code" -eq 90 ]]; then
+        echo "pnpm-lock.yaml is out of date in this execution workspace; retrying install without --frozen-lockfile." >&2
+        run_pnpm_install --no-frozen-lockfile || {
+          restore_moved_symlinks
+          exit 1
+        }
+      else
+        restore_moved_symlinks
+        exit "$install_exit_code"
+      fi
+    fi
+
    cleanup_moved_symlinks
  fi

@@ -0,0 +1,224 @@
+import { randomUUID } from "node:crypto";
+import { eq } from "drizzle-orm";
+import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
+import {
+  companies,
+  companyMemberships,
+  createDb,
+  instanceUserRoles,
+  issues,
+  principalPermissionGrants,
+} from "@paperclipai/db";
+import {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+} from "./helpers/embedded-postgres.js";
+import { accessService } from "../services/access.js";
+
+const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
+
+async function createCompanyWithOwner(db: ReturnType<typeof createDb>) {
+  const company = await db
+    .insert(companies)
+    .values({
+      name: `Access Service ${randomUUID()}`,
+      issuePrefix: `AS${randomUUID().slice(0, 6).toUpperCase()}`,
+    })
+    .returning()
+    .then((rows) => rows[0]!);
+
+  const owner = await db
+    .insert(companyMemberships)
+    .values({
+      companyId: company.id,
+      principalType: "user",
+      principalId: `owner-${randomUUID()}`,
+      status: "active",
+      membershipRole: "owner",
+    })
+    .returning()
+    .then((rows) => rows[0]!);
+
+  return { company, owner };
+}
+
+describeEmbeddedPostgres("access service", () => {
+  let db!: ReturnType<typeof createDb>;
+  let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
+
+  beforeAll(async () => {
+    tempDb = await startEmbeddedPostgresTestDatabase("paperclip-access-service-");
+    db = createDb(tempDb.connectionString);
+  }, 20_000);
+
+  afterEach(async () => {
+    await db.delete(issues);
+    await db.delete(principalPermissionGrants);
+    await db.delete(instanceUserRoles);
+    await db.delete(companyMemberships);
+    await db.delete(companies);
+  });
+
+  afterAll(async () => {
+    await tempDb?.cleanup();
+  });
+
+  it("rejects combined access updates that would demote the last active owner", async () => {
+    const { company, owner } = await createCompanyWithOwner(db);
+    const access = accessService(db);
+
+    await expect(
+      access.updateMemberAndPermissions(
+        company.id,
+        owner.id,
+        { membershipRole: "admin", grants: [] },
+        "admin-user",
+      ),
+    ).rejects.toThrow("Cannot remove the last active owner");
+
+    const unchanged = await db
+      .select()
+      .from(companyMemberships)
+      .where(eq(companyMemberships.id, owner.id))
+      .then((rows) => rows[0]!);
+    expect(unchanged.membershipRole).toBe("owner");
+  });
+
+  it("rejects role-only updates that would suspend the last active owner", async () => {
+    const { company, owner } = await createCompanyWithOwner(db);
+    const access = accessService(db);
+
+    await expect(
+      access.updateMember(company.id, owner.id, { status: "suspended" }),
+    ).rejects.toThrow("Cannot remove the last active owner");
+
+    const unchanged = await db
+      .select()
+      .from(companyMemberships)
+      .where(eq(companyMemberships.id, owner.id))
+      .then((rows) => rows[0]!);
+    expect(unchanged.status).toBe("active");
+  });
+
+  it("archives members, clears grants, and reassigns open issues without deleting history", async () => {
+    const { company, owner } = await createCompanyWithOwner(db);
+    const member = await db
+      .insert(companyMemberships)
+      .values({
+        companyId: company.id,
+        principalType: "user",
+        principalId: `member-${randomUUID()}`,
+        status: "active",
+        membershipRole: "operator",
+      })
+      .returning()
+      .then((rows) => rows[0]!);
+    await db.insert(principalPermissionGrants).values({
+      companyId: company.id,
+      principalType: "user",
+      principalId: member.principalId,
+      permissionKey: "tasks:assign",
+      grantedByUserId: owner.principalId,
+    });
+    const openIssue = await db
+      .insert(issues)
+      .values({
+        companyId: company.id,
+        title: "Open assigned issue",
+        status: "in_progress",
+        assigneeUserId: member.principalId,
+      })
+      .returning()
+      .then((rows) => rows[0]!);
+    const doneIssue = await db
+      .insert(issues)
+      .values({
+        companyId: company.id,
+        title: "Historical assigned issue",
+        status: "done",
+        assigneeUserId: member.principalId,
+      })
+      .returning()
+      .then((rows) => rows[0]!);
+
+    const access = accessService(db);
+    const result = await access.archiveMember(company.id, member.id, {
+      reassignment: { assigneeUserId: owner.principalId },
+    });
+
+    expect(result?.reassignedIssueCount).toBe(1);
+    const archived = await db
+      .select()
+      .from(companyMemberships)
+      .where(eq(companyMemberships.id, member.id))
+      .then((rows) => rows[0]!);
+    expect(archived.status).toBe("archived");
+
+    const remainingGrants = await db
+      .select()
+      .from(principalPermissionGrants)
+      .where(eq(principalPermissionGrants.principalId, member.principalId));
+    expect(remainingGrants).toHaveLength(0);
+
+    const reassignedIssue = await db
+      .select()
+      .from(issues)
+      .where(eq(issues.id, openIssue.id))
+      .then((rows) => rows[0]!);
+    expect(reassignedIssue.assigneeUserId).toBe(owner.principalId);
+    expect(reassignedIssue.status).toBe("todo");
+
+    const historicalIssue = await db
+      .select()
+      .from(issues)
+      .where(eq(issues.id, doneIssue.id))
+      .then((rows) => rows[0]!);
+    expect(historicalIssue.assigneeUserId).toBe(member.principalId);
+  });
+
+  it("rejects instance-level company access removal for self and protected users", async () => {
+    const { company, owner } = await createCompanyWithOwner(db);
+    const access = accessService(db);
+
+    await expect(
+      access.setUserCompanyAccess(owner.principalId, [], { actorUserId: owner.principalId }),
+    ).rejects.toThrow("You cannot remove yourself");
+
+    const admin = await db
+      .insert(companyMemberships)
+      .values({
+        companyId: company.id,
+        principalType: "user",
+        principalId: `admin-${randomUUID()}`,
+        status: "active",
+        membershipRole: "admin",
+      })
+      .returning()
+      .then((rows) => rows[0]!);
+
+    await expect(
+      access.setUserCompanyAccess(admin.principalId, [], { actorUserId: owner.principalId }),
+    ).rejects.toThrow("Owners and admins cannot be removed from company access");
+
+    const operator = await db
+      .insert(companyMemberships)
+      .values({
+        companyId: company.id,
+        principalType: "user",
+        principalId: `operator-${randomUUID()}`,
+        status: "active",
+        membershipRole: "operator",
+      })
+      .returning()
+      .then((rows) => rows[0]!);
+    await db.insert(instanceUserRoles).values({
+      userId: operator.principalId,
+      role: "instance_admin",
+    });
+
+    await expect(
+      access.setUserCompanyAccess(operator.principalId, [], { actorUserId: owner.principalId }),
+    ).rejects.toThrow("Instance admins cannot be removed from company access");
+  });
+});
@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+import {
+  updateCompanyMemberWithPermissionsSchema,
+  updateCurrentUserProfileSchema,
+} from "@paperclipai/shared";
+
+describe("access validators", () => {
+  it("accepts HTTP(S) and Paperclip asset image URLs", () => {
+    expect(updateCurrentUserProfileSchema.safeParse({
+      name: "Ada Lovelace",
+      image: "https://example.com/avatar.png",
+    }).success).toBe(true);
+    expect(updateCurrentUserProfileSchema.safeParse({
+      name: "Ada Lovelace",
+      image: "/api/assets/avatar/content",
+    }).success).toBe(true);
+  });
+
+  it("rejects data URI profile images", () => {
+    expect(updateCurrentUserProfileSchema.safeParse({
+      name: "Ada Lovelace",
+      image: "data:image/png;base64,AAAA",
+    }).success).toBe(false);
+  });
+
+  it("defaults omitted combined member grants to an empty list", () => {
+    const result = updateCompanyMemberWithPermissionsSchema.parse({
+      membershipRole: "operator",
+    });
+
+    expect(result.grants).toEqual([]);
+  });
+});